advisor-mcp

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

架构

CC 对话 (session_id,由 UserPromptSubmit hook 落盘)
   │ stdio MCP · 绑定表 <cwd>/.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。

Related MCP server: Claude-Gemini Collaborative Integration

安装

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 已带,重装即可。

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

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

# ① 注册 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 数组里追加一条(不动已有条目):

{
  "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 全局可用):

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 免确认):

"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 启动时的工作目录, 绑定表(.advisor-tasks.json)落在每个工程的根目录,按工程天然隔离。hook 文件里 记录了 cwd,MCP server 只认与自己工作目录一致的会话标识(防跨工程误绑)。

工具

异步咨询(poll)

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

• 运行中:⏳ 顾问仍在思考(已 34s)· 稍后再 poll

• 完成:顾问的完整答复(含重建提示/工具动作摘要)

• 失败:❌ 咨询失败: <原因>

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

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

自愈与防护

• 自动绑定: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-12

• fix: 取消 600s 总时长上限 — 深咨询误杀修复,等待不设限,首字节 30s 仍兜底挂死(advisor-mcp)

• feat: consult 自动绑定 — 免 create 直聊,无绑定自动建会话并记录,首答即结果(子目录窗口靠祖先/后代过滤认领,TTL 移除)(advisor-mcp)

• docs: 同步自动绑定文档与顾问运行期纪律(poll 期间只监控、等回复)(advisor-mcp)