HaAgent 是一个本地优先的个人 AI 助手。用户配置一次模型后，可以在任意目录运行 haagent，通过 Textual TUI 围绕当前目录完成文件阅读、资料整理、文档修改、项目分析、命令执行和多轮任务延续。
- 当前目录即工作区：默认把启动目录作为 workspace root，也可以用
--workspace-root显式指定。 - Textual TUI 会话工作台：在一个终端界面里管理对话、状态、工具审批、失败信息和上下文帮助。
- 先规划再执行：用
/plan进入只读规划模式，确认或反馈方案后自动生成 Todo 并继续执行。 - 多轮会话恢复：支持继续最新 session，或按 session id / package 路径恢复历史工作。
- 本地/混合模型中心：管理云端 OpenAI-compatible 连接，发现 Ollama / LM Studio，并可配置一个显式备用模型。
- 工具与权限边界：文件、命令、联网和 MCP 工具都通过 runtime 统一路由，并受 workspace 与 policy 约束。
- 记忆候选审查：长期记忆先进入候选队列，再由用户或确定性策略确认。
- 可观测 runtime：每轮任务写 episode package，支持 inspect、eval、export 和 smoke/dogfood 验证工作流。
- Python 3.11+
- uv
- PowerShell 7+（Windows 推荐，项目命令示例默认使用
pwsh语义）
当前正式分发源是 GitHub 仓库。使用 uv tool install 安装后，haagent 会成为用户级命令，可以在任意目录直接运行：
uv tool install "git+https://github.com/linbei0/HaAgent.git"确认安装成功：
haagent --help进入希望助手处理的目录并启动：
cd E:\some-folder
haagent也可以从任意位置显式指定工作区：
haagent --workspace-root E:\some-folder恢复会话：
haagent --continue
haagent --resume <session>启用只读联网工具：
haagent --web/channels 的微信扫码登录可以使用 channels-weixin extra 在终端渲染 ASCII 二维码。首次安装时启用：
uv tool install "haagent[channels-weixin] @ git+https://github.com/linbei0/HaAgent.git"HaAgent 会在 ~/.haagent/logs/tui-diagnostics.log 写入轮转的 TUI 生命周期摘要。日志只包含启动/退出时间、Python 与 Textual 版本、终端标识和未处理异常类型，不记录对话、工具输出、文件内容或凭据。
如果终端显示 CloseOnCleanExit，先检查该日志是否已有 tui_stopped 或 unhandled_exception，再按同一时间戳查看 Windows Application Event Log。若 HaAgent 已正常停止而终端仍异常退出，请分别在 Windows Terminal 和 WezTerm 复现；这通常指向 PowerShell/ConPTY 或终端环境，而不是会话数据。
如果已经安装基础版本，使用同一命令加 --force 重装：
uv tool install --force "haagent[channels-weixin] @ git+https://github.com/linbei0/HaAgent.git"不安装该 extra 时，微信登录仍可继续，但 TUI 只显示二维码 URL 文本。
需要修改代码或运行测试时再克隆仓库：
git clone https://github.com/linbei0/HaAgent.git
cd HaAgent
uv sync
uv run haagent希望本地源码改动立即反映到全局 haagent 命令时，可以在仓库根目录安装 editable tool：
uv tool install --force --editable .HaAgent 的日常操作都在 TUI 内完成。常用 slash commands：
| 命令 | 用途 |
|---|---|
/connect |
配置供应商连接和凭据 |
/model |
切换模型、扫描本机运行时或设置备用模型 |
/sessions |
打开会话列表 |
/memory |
审查记忆候选 |
/channels |
配置微信等外部聊天渠道 |
/schedules |
管理计划任务与运行收件箱 |
/web |
切换联网工具 |
/plan |
只读规划任务，确认后自动执行 |
/new |
新建 session |
/resume |
继续当前 workspace 的最新 session |
/cancel |
取消当前任务 |
/help |
打开上下文帮助 |
需要先审阅方案时，输入 /plan <任务>；也可以先输入 /plan，再在输入框中描述任务。规划阶段只允许读取和分析，不会修改文件或执行命令。方案出现后可直接提交反馈要求修订，或切换到批准按钮开始执行。批准后 HaAgent 会把步骤转换为 Todo：窄终端显示当前进度摘要，宽终端可展开查看 待处理、进行中、已完成 和 已取消 四种状态。规划确认或执行过程中按 Ctrl+X 会取消任务；仅按 Esc 只收起确认面板，不会默认批准或拒绝。
升级通过 GitHub 安装的版本：
uv tool upgrade haagent如果使用 editable 源码安装，先在仓库中更新代码和锁定依赖：
git pull --ff-only
uv sync --locked卸载不会删除用户级 ~/.haagent/ 配置和运行数据（包括 ~/.haagent/runs/ 中的会话与 episode）：
uv tool uninstall haagent如需彻底清理数据，请先自行备份，再处理用户目录 ~/.haagent/；会话按 runs/sessions/YYYY/MM/DD/、episode 按 runs/episodes/YYYY/MM/DD/ 分层存放。HaAgent 不提供自动删除用户数据的命令。
HaAgent 使用用户级 profile 管理模型连接配置：
- profile 文件：
~/.haagent/providers.json - 当前激活 profile：
~/.haagent/settings.json - 支持 gateway：
openai、openai-chat，以及模型目录明确识别的 Anthropic 与 Google 原生 gateway；运行时类型包括remote、ollama与lm_studio - API key 解析顺序：当前环境变量、系统凭据库、显式 opt-in 的明文用户文件
- Ollama 默认无需凭据；LM Studio 开启认证时使用
LM_STUDIO_API_KEY或已配置凭据
推荐在 TUI 的 /connect 中新增供应商连接，在 /model 中切换模型。模型中心按 l 只扫描 127.0.0.1:11434（Ollama）和 127.0.0.1:1234（LM Studio），选择模型后才保存本地连接；b 设置本地备用，c 设置已明确同意的云端备用。远端连接的 API key 通过 masked 输入直接写入系统凭据库；TUI 不回显、复制或写入明文配置。
providers.json 当前为 version 4。一个无需凭据的 Ollama 连接如下；本地能力来自实时发现，不写入配置：
{
"version": 4,
"connections": [
{
"id": "local-ollama",
"name": "Ollama",
"provider_id": "ollama",
"provider_name": "Ollama",
"gateway_provider": "openai",
"base_url": "http://127.0.0.1:11434/v1",
"api_key_env": "",
"credential_source": "none",
"runtime_kind": "ollama"
}
]
}模型配置可选 max_context_tokens，用于把 provider 的上下文能力限制为 HaAgent 本地上限。例如将 1M 模型限制为 400K：
{
"models": {
"gpt-5": {
"max_context_tokens": 400000
}
}
}该字段只影响上下文占比、压缩预算、能力判断和 fallback；不会作为未知参数发送给 provider。未配置时保持 provider 或本地发现的窗口行为。
普通 route 会先协商模型能力和协议。Responses 仅在能力元数据不支持，或首个有效输出前收到 404/405/501 时降级到 Chat Completions；备用模型仅在能力明确不足，或内部重试耗尽后的 network、timeout、可重试 429/5xx 且尚无有效 delta 时启用。认证、无效请求、取消及已有输出后的失败会直接暴露，不会静默重放。
GitHub Actions（.github/workflows/ci.yml）在 push/pull_request 到 main/master 时自动运行 uv sync --locked --all-extras、uv run pytest -q 与 uv run haagent check（默认 fake provider，无需 API key）。本地常用命令：
uv sync
uv run pytest -q
uv run pytest tests/tui -q -n 0
uv run pytest tests/extended -q -n 0
uv run haagent check高级 runtime 与验证入口：
| 命令 | 定位 |
|---|---|
uv run haagent run <task.yaml> |
运行结构化任务或复现实验任务 |
uv run haagent inspect <episode> |
查看 episode package 摘要与诊断 |
uv run haagent eval <path> |
运行评测用例 |
uv run haagent export-eval <episode> |
从 episode 导出评测样本 |
uv run haagent smoke |
运行最小 smoke 套件 |
uv run haagent dogfood |
手动运行真实模型 dogfood 任务 |
项目使用 src/haagent 存放源码，tests 存放测试。行为变更应配套 pytest 覆盖；触及 runtime 合同、工具路由、模型网关、上下文、episode、CLI 入口、workspace 边界或 secret 处理时，交付前运行完整测试。
- 在
pyproject.toml更新版本号，并确认 GitHub Release 中准备了对应变更说明。 - 从干净工作树同步锁定依赖并运行发布门禁：
uv sync --locked uv run pytest -q uv run pytest tests/tui -q -n 0 uv run pytest tests/extended -q -n 0 uv run haagent check --pytest
- 构建 wheel 和源码包，并在本机安装 wheel 验证普通命令入口：
uv build $wheel = (Get-ChildItem dist\*.whl | Select-Object -First 1).FullName uv tool install --force $wheel haagent --help
- 创建并推送与版本一致的标签，例如：
git tag v0.1.0 git push origin v0.1.0
- 在 GitHub 创建 Release 并上传
dist/中的 wheel 与源码包。只有在项目完成 PyPI 账户、token 或 Trusted Publishing 配置后，才执行uv publish；不要把发布凭据写入仓库、命令历史、日志或 episode。
发布失败时不要复用同一个版本号覆盖已有制品；修复后递增版本并重新执行完整门禁。