# advisor-mcp

Claude Code(便宜执行者)通过 MCP 指挥 kimi code CLI(贵顾问 · 对话级会话记忆)在
蓝图 / 破局 / 验收三唤醒点把关。省钱:贵模型只在关键点进场 + 同一对话复用同一
kimi 会话(上下文延续,不重复喂历史)。

## 架构

```
CC 对话 (session_id,由 UserPromptSubmit hook 落盘)
   │ stdio MCP · 绑定表 <cwd>/.agent/advisor-tasks.json(键 = CC 对话 session_id)
   ▼
advisor-mcp server
   │ kimi -S <session_id> -p <msg> --output-format stream-json
   ▼
kimi 会话 (~/.kimi-code/sessions/ · 对话级记忆)
```

对话级绑定:一个 CC 对话(恢复/重启不换 session_id)对应一个 kimi 顾问会话。
consult 自动判定:有绑定直接续聊,无绑定自动开新 kimi 会话并记录 —— 无需先 create。

## 安装

```bash
cd cc_advisor_mcp
python -m pip install -e ".[dev]"
python -m advisor_mcp.install_agent   # 装顾问人格到 ~/.kimi-code/agents/advisor-mcp/
```

注意:kimi ≥0.34 的 agent 文件必须带 YAML frontmatter(`name`/`description`),
否则被发现时静默跳过——`kimi_agent/system.md` 已带,重装即可。

## 全局生效(推荐,用户级)

一次性配置到用户级,所有工程自动启用顾问纪律;不需要逐工程接线。

```bash
# ① 注册 MCP server 到用户级配置(写入 ~/.claude.json 顶层 mcpServers)
claude mcp add -s user advisor-mcp -- python -m advisor_mcp.server
claude mcp get advisor-mcp      # 应显示 Scope: User config / Status: ✔ Connected
```

② 装对话标识 hook(对话级绑定的前提):把 `templates/hook.py` 复制到
`~/.claude/advisor-hook.py`,并在用户级 `~/.claude/settings.json` 的
`hooks.UserPromptSubmit` 数组里**追加**一条(不动已有条目):

```json
{
  "hooks": [
    { "type": "command", "command": "python '<home>/.claude/advisor-hook.py'", "timeout": 10 }
  ]
}
```

`<home>` 换成你家目录的绝对路径(Windows 如 `C:/Users/<用户名>`;macOS/Linux 如
`/home/<用户名>`;JSON 里 `~` 不会展开,必须写绝对路径)。

hook 在每次你发消息时把当前对话的 `session_id` 按「事件 cwd hash + 会话前 8 位」写入
`~/.claude/advisor-current-session-<hash>-<sid8>.json`(每个 CC 窗口写各自文件,
同工程双窗口也互不覆盖);MCP server glob 全部候选文件,按文件内容里记录的 cwd
与 server 是否同工程(互为祖先/后代)过滤,取 mtime 最新的那个做绑定键
(崩溃残留的旧文件 mtime 必然最旧,不会当选,无需超时机制)—— 在 build
子目录里启动的窗口写出的文件,工程根目录的 server 同样认领。

③ 把 `templates/CLAUDE.md` 的「顾问纪律(advisor-mcp)」一节追加到 `~/.claude/CLAUDE.md`(纪律 ① · 三个唤醒点 + 复用纪律 + 成本纪律)。

④ 把 `templates/commands/*.md` 复制到 `~/.claude/commands/`(纪律 ② · /advisor /blueprint /review 全局可用):

```bash
mkdir -p ~/.claude/commands
cp templates/commands/*.md ~/.claude/commands/
```

⑤ 把 `templates/settings.json` 的 `permissions` 块并入 `~/.claude/settings.json`,并在 `env` 块加
`"MCP_TOOL_TIMEOUT": "600000"`(兜底:深度咨询超过 CC 的 120s 观察点时会转后台继续跑,
这个值保证不被更早 abort;纪律 ③ · 5 个工具中 3 个需要 ask 确认,list/poll 免确认):

```json
"permissions": {
  "allow": [
    "mcp__advisor-mcp__advisor_list_tasks",
    "mcp__advisor-mcp__advisor_poll"
  ],
  "ask": [
    "mcp__advisor-mcp__advisor_create_task",
    "mcp__advisor-mcp__advisor_consult",
    "mcp__advisor-mcp__advisor_close_task"
  ]
}
```

注意:settings.json 若已有 env / hooks / 其他字段,合并时不要覆盖,只新增 `permissions` 和 hook 条目。

## 工程级接线(不用全局时)

1. MCP 配置指向本 server:`advisor-mcp`(stdio;`cwd` 设为你的工程目录)
2. 项目 CLAUDE.md 并入 `templates/CLAUDE.md`
3. `templates/commands/*.md` 复制到项目 `.claude/commands/`
4. `templates/settings.json` 的 permissions 并入项目 `.claude/settings.json`
5. hook 仍需装(用户级或项目级 settings.json),对话级绑定依赖它

### cwd 说明

用户级注册时**不要指定 `cwd`**。stdio MCP 子进程继承 Claude Code 启动时的工作目录,
绑定表(`.agent/advisor-tasks.json`,目录不存在自动创建)落在每个工程的根目录,
按工程天然隔离。hook 文件里
记录了 cwd,MCP server 只认与自己工作目录一致的会话标识(防跨工程误绑)。

## 工具

| 工具 | 作用 |
|---|---|
| advisor_consult | 咨询(默认当前对话绑定),**自动绑定**:有绑定续聊,无绑定自动建新 kimi 会话并记录(建会话与首答一次完成,不用先 create);**异步发起**:立即返回任务号,用 advisor_poll 查结果;mode 可选 blueprint/unstick/review(自动带指令前缀);task_id 可显式指定其他会话 |
| advisor_create_task | 可选:显式登记/改名任务,预设 goal 背景,force_new=True 开新 kimi 会话(默认流程无需它) |
| advisor_poll | 查咨询任务状态:⏳ 运行中(已耗时) / ✅ 结果 / ❌ 失败原因 |
| advisor_list_tasks | 列出本工程绑定(会话名 / 状态 / kimi 会话) |
| advisor_close_task | 关闭当前对话(或 task_id 指定)的绑定,会话保留在 kimi 侧可回看 |

## 异步咨询(poll)

`advisor_consult` 只做同步校验(绑定存在、mode 合法),随后后台线程跑 kimi,立即返回
`⏳ 咨询已发起 #t1`。之后用 `advisor_poll("t1")` 轮询:

- 运行中:`⏳ 顾问仍在思考(已 34s)· 稍后再 poll`
- 完成:顾问的完整答复(含重建提示/工具动作摘要)
- 失败:`❌ 咨询失败: <原因>`

任务表存在 server 进程内,重启后需重新发起咨询。consult 保持 ask 权限
(花钱的操作要确认),poll 免确认(纯查询)。

## 手动验证矩阵(验收标准)

| # | 场景 | 预期 |
|---|---|---|
| 1 | create → consult 两次 | 第二次顾问记得第一轮上下文(跨轮记忆) |
| 2 | 同对话二次 create | 复用同一 kimi 会话(只改名,不新开) |
| 3 | consult(mode=blueprint) | 输出为施工单结构(清单/禁区/顺序/验收标准) |
| 4 | resume 会话后 consult | 绑定延续(session_id 不变) |
| 5 | 同工程双窗口各 create/consult | 两个 CC 对话各绑各的,互不串 |
| 6 | `/blueprint` slash command | 完整流程走通(create→consult→执行) |
| 7 | CC 中调用 advisor_consult | ask 权限弹窗出现,批准才执行 |
| 8 | 其他工程裸跑 `kimi` | 行为不变(advisor-mcp agent 不影响 default) |
| 9 | `pytest`(单测) | 全过,e2e 默认排除 |
| 10 | `pytest -m e2e`(需 kimi 登录) | 真实链路:create 两次复用同一会话,consult 记得暗号 |

## 自愈与防护

- **自动绑定**:consult 无绑定(或绑定已 closed)时自动开新 kimi 会话并记录,
  CC 无需先调 create;首答即咨询结果,不重复调用。
- **会话失效自愈**:kimi 侧会话被清理后,consult 检测到 `Session "…" not found`
  会自动按绑定表里持久化的 goal 重建会话并重试一次,输出带重建提示(原上下文丢失)。
- **超时防护**:kimi 无任何输出超过 30s 报「首字节超时」(挂死兜底);总时长不设限,
  深咨询可跑任意久,顾问一直在输出就一直等(poll 查询已耗时)。
- **绑定表多进程安全**:写操作(create/close/touch/重绑)在文件锁内先重读磁盘再写,
  同工程多窗口的多个 server 进程不会互相覆盖记录。
- **closed 记录归档**:同对话 close 后再次使用,旧记录归档保留(旧 kimi sid 可回看),
  不再被覆盖。

## 已知取舍

- `kimi -p` 无权限位,且 `--plan` 与 `-p` 不兼容(实测):顾问会话能改文件,只能
  靠人格指令约束——system.md 已删除「对方要求实现时可直接改文件」条款,顾问只读不写
- stream-json 无 reasoning 事件:顾问"思考过程"不可转发,在场感只到工具动作粒度
- 会话标识按「事件 cwd hash + 会话前 8 位」分文件,多窗口互不覆盖;server 按
  内容 cwd 同工程(祖先/后代)过滤后取 mtime 最新者——同工程双窗口靠
  「consult 总紧跟本窗口最近一次发言」的启发式成立,极端场景(另一窗口在你
  发言后、你 consult 前又发言)可能读错窗口,用 task_id 显式指定即可纠正
- 会话失效自愈以「重建」实现:新 kimi 会话不带原上下文,只有 goal 回喂

---

## 变更日志

<!-- 新条目添加在最上方 -->

### 2026-08-13

- **feat**: 绑定表落盘移入 `.agent` 目录,不存在时自动创建(`advisor-mcp`)

### 2026-08-12

- **fix**: 取消 600s 总时长上限 — 深咨询误杀修复,等待不设限,首字节 30s 仍兜底挂死(`advisor-mcp`)
- **feat**: consult 自动绑定 — 免 create 直聊,无绑定自动建会话并记录,首答即结果(子目录窗口靠祖先/后代过滤认领,TTL 移除)(`advisor-mcp`)
- **docs**: 同步自动绑定文档与顾问运行期纪律(poll 期间只监控、等回复)(`advisor-mcp`)