文档
使用指南
第一次用就按「开始」一组从上往下读：装好、配一个模型服务、派出第一个任务。日常用到的输入、权限与撤销在「日常使用」里。
开始
- 安装与首次启动 一条命令装好 heng-agent，配一个模型服务，然后在项目目录里启动它。第一次运行会自动找你电脑上现成的密钥，找到了一键就能用。
- 派第一个任务 以「给登录接口加限流」为例走一遍完整的任务：用中文描述、它先读懂项目、改文件前给你看改动、跑测试直到通过，最后看改了什么、花了多少。
- 服务商与配置文件 heng-agent 内置 9 个服务商配置档（DeepSeek、Kimi、GLM、通义千问等），设好密钥就能用；自己的中转站、默认服务商、按项目区分写在 ~/.heng-agent/config.json。
- 接自己的模型（heng） 用内置的 heng 配置档连本机的 heng serve：跑自己训练的模型，或用 proxy 配置把请求转发到 Claude。两个终端，一个起模型服务，一个在项目里用 heng-agent。
日常使用
- 输入框与快捷键 heng-agent 的输入框怎么用：换行、@ 附文件、! 自己跑命令、粘贴截图；回答过程中接着打字排队、插话、Ctrl+X Ctrl+S 立刻发送、/btw 随口问一句；答完 Tab 采纳下一句建议；ESC、Ctrl+C 各管什么；底部两行状态栏怎么看。
- 权限模式与规则 heng-agent 改文件、跑命令前默认都先问你。四种权限模式（手动确认 / 自动改文件 / 计划模式 / 全部放行）怎么选、怎么切，确认框的四个选项，以及用允许 / 拒绝规则把常用命令放行、把危险命令拦死。
- 撤销与回退 改错了怎么办：/undo 撤销上一问改过的文件、对话也退回去；/rewind（或空输入框里双击 ESC）选一问，对话和代码一起回到它之前。也说清哪些改动撤不回来。
- 会话：恢复、命名、导出 heng-agent 的每次对话都存成会话：-c 接最近一次、/resume 挑一个接着聊、/rename 起名、/export 导出 Markdown；上下文快满时自动压缩，/compact 按你的要求压；/status、/usage、/stats、/context 看状态和花费；多开互不干扰。
- 项目记忆 HENG.md 把项目规矩写进 HENG.md（或沿用现成的 AGENTS.md、CLAUDE.md），heng-agent 每次启动自动读入；用
- 后台任务 开发服务器、watch 这类不会自己结束的命令放到后台跑：模型自己会放，前台命令跑着时 Ctrl+B 也能转过去；/tasks 查看与停止，状态栏显示「后台 N」，退出时全部停掉。长任务结束时响铃提醒。
- 思考模式与强度 难题让模型先想清楚再动手：/think 开关思考、设预算、看最近一次想了什么；/effort 选 low 到 max 的思考强度，状态栏显示 ✻ high。不同模型（Claude、DeepSeek、Kimi、GLM、OpenAI 协议）怎么适配。
进阶
- 技能与自定义命令 技能是某类任务的做法说明，模型用得上时自己去读；heng-agent 内置 debugging、writing-tests 等 5 个，也能写自己的。自定义命令把常用提示词存成 /名字，支持 $ARGUMENTS；/commit、/review 可以按团队规矩改写。
- 子智能体 模型把调研类的事交给子智能体去做，只把结论带回来，主对话不被中间过程挤满；最多 4 个并行，可以放到后台；子智能体面板里随时看它在做什么；自定义「测试员」「审查员」这类角色。
- MCP 服务 在 config.json 里接入 MCP 服务（stdio 启动程序或 http 连接），Claude Code、Kimi 的 mcpServers 配置可以直接贴；状态栏看连接情况，/mcp 看工具与原因；工具太多时按需加载，项目里的服务要确认信任才启动。
- 钩子 钩子是在工具执行前后、发消息前、模型停下时、启动时自动跑的命令：改完文件自动格式化、拦下危险命令、注入当前分支、测试没过不许停。写在 config.json 的 hooks 里，项目里的要确认信任；Claude Code 的钩子也认。
- git 工作树隔离 想试个有风险的改动、或让两件事互不干扰，用 heng-agent -w 名字 或 /worktree new 名字，在 .heng-agent/worktrees 下的独立工作树和 heng/名字 分支里干活，不碰主分支和你没提交的改动；满意了 /commit 再合并，不满意整个删掉。
- 脚本模式 -p heng-agent -p "任务" 执行完这一个任务就退出：接管道、输出 JSON 或逐行事件，放进脚本、CI、定时任务里用。没人可问，需要确认的操作默认都拒绝，用 --allowed-tools 精确放行。
- 在编辑器里用（ACP） heng-agent --acp 以 Agent Client Protocol 运行，Zed、JetBrains 等支持 ACP 的编辑器或桌面应用能在自己的界面里驱动它：流式回答、改文件前弹窗看改动对比、随时取消、恢复旧会话；模型、权限模式、思考三个下拉框。
- 兼容 Claude Code 与 AGENTS.md 从 Claude Code 转过来不用迁移：CLAUDE.md、AGENTS.md、.claude 里的技能、子智能体、自定义命令、权限规则、钩子，以及 .mcp.json 都直接读；哪些照搬、哪些不跟，怎么关掉用户级的读取。
参考
- 命令行参数 heng-agent 启动时能带的全部参数：选服务商与模型、权限模式、工作目录与数据目录、接着上次的会话、工作树、脚本模式 -p 与输出格式、放行与禁止规则、ACP，以及 heng-agent upgrade。
- 配置项一览 heng-agent 配置文件 config.json 的全部字段：服务商配置档（protocol、base_url、model、密钥、价格、代理、上下文长度……）与 settings 段的启动默认值（权限模式、轮数上限、超时、自动压缩、思考、下一句建议、状态栏……），默认值与哪些只能写在用户配置里。
- 遇到问题 /doctor heng-agent 出问题先运行 /doctor：一项项检查配置、服务商连接（真的连一次）、密钥、代理、终端、git、说明文件、钩子、MCP；反馈问题用 /doctor copy。附常见问题的原因与处理：找不到命令、升级失败、连不上服务商、中转站 401、Shift+Enter 不换行、MCP 连不上。
- 斜杠命令速查