# 终端 AI 接入手册
## 目的
这份文档说明如何把 `spool-mcp` 接入终端中的 AI 客户端，使其能够在对话过程中调用 `spool` 的 MCP 能力。
当前优先支持：
- Claude Code
- Codex
## 接入后的目标效果
接入完成后，终端 AI 可以调用：
- `memory_search`
- `memory_wakeup`
- `memory_explain`
- `prompt_optimize`
其中最重要的是：
- `prompt_optimize`
它会把：
- context
- wakeup
组合成一段更适合直接注入当前终端 AI 对话的 prompt block。
## 前提条件
你需要先保证：
1. 本仓库已经编译出 `spool-mcp`
2. 你有一个可用的 `spool` 配置文件
3. 该配置文件中的 vault / 项目路由是有效的
## 构建 MCP 二进制
先构建二进制：
```bash
cargo build --bin spool-mcp
```
默认输出路径通常是：
```bash
target/debug/spool-mcp
```
## Claude Code 接入
Claude Code 读取的配置文件是：
```bash
~/.claude.json
```
你需要在其中的 `mcpServers` 下增加一个 `spool` 条目。
示例：
```json
"spool": {
"type": "stdio",
"command": "/Users/long/Work/spool/target/debug/spool-mcp",
"args": ["--config", "/abs/path/to/spool.toml"]
}
```
如果你的 `~/.claude.json` 里已经有别的 MCP server：
- 不要覆盖原有内容
- 只是在 `mcpServers` 下新增 `spool`
## Codex 接入
Codex 读取的配置文件通常是：
```bash
~/.codex/config.toml
```
你需要在 `mcp_servers` 下增加一个 `spool` 条目。
示例：
```toml
[mcp_servers.spool]
type = "stdio"
command = "/Users/long/Work/spool/target/debug/spool-mcp"
args = ["--config", "/abs/path/to/spool.toml"]
```
如果已经存在其他 MCP server：
- 不要覆盖原有项
- 只需追加 `spool`
## 如何确认是否接入成功
当前桌面端已经会检测：
- Claude 是否注册了 `spool`
- Codex 是否注册了 `spool`
你可以在桌面端查看：
- 顶部状态区中的 `MCP`
- `当前工作状态` 卡片中的：
- `Claude MCP`
- `Codex MCP`
如果显示为已检测，说明桌面端已在本机配置文件里发现 `spool` 注册信息。
注意区分两类状态：
- `已检测 / 已接入`：只表示本机配置文件里已经注册了 `spool`
- `已增强`：表示终端会话已经真实调用过 `prompt_optimize`
## 如何使用 `prompt_optimize`
接入成功后，终端 AI 客户端理论上可以直接调用：
- `prompt_optimize`
输入：
- `task`
- `cwd`
- 可选 `files`
- 可选 `target`
- 可选 `profile`
- 可选 `provider`
- 可选 `session_id`
输出：
- `combined_prompt`
- `context_prompt`
- `wakeup_prompt`
- `runtime_trace`
其中 `combined_prompt` 最适合直接作为注入块使用。
`runtime_trace` 会保存最近一次真实增强的最小摘要，包括：
- 时间
- cwd
- task
- target
- provider
- session_id
桌面端状态区会优先读取这条真实记录，而不是只根据 MCP 注册情况做静态推断。
## 推荐使用方式
推荐工作流：
1. 先在桌面端选中当前会话
2. 点击“用于注入”
3. 让桌面端自动带入：
- cwd
- 最近用户问题
4. 点击“生成注入内容”
5. 复制结果
6. 在终端 AI 中配合 `spool-mcp` 使用
## 常见问题
### 1. 桌面端显示 Claude/Codex MCP 未检测
检查：
- 配置文件是否写对
- 是否把 `spool` 写到了正确节点下
- `command` 路径是否真实存在
- `--config` 后面的路径是否真实存在
### 2. 终端 AI 能看到 MCP，但调用失败
检查：
- `spool-mcp` 是否能单独启动
- `--config` 指向的配置是否有效
- vault 路径是否存在
- 当前 `cwd` 是否能命中某个配置项目
### 3. Claude/Codex 已注册，但桌面端仍显示未检测
可能原因：
- 配置格式不符合当前检测逻辑
- 配置文件位置不是默认路径
- 桌面端尚未刷新状态
先尝试：
1. 回到桌面端 `基础配置`
2. 修改或重新确认 `Config Path / 当前工作目录 / 知识库路径`
3. 触发状态刷新
## 设计说明
为什么要同时保留：
- 桌面端“生成注入内容”
- 终端端“MCP 调用”
原因是它们解决的是两个层次的问题：
- 桌面端：让用户看见、理解、控制上下文增强过程
- 终端端：让 AI 客户端在实际工作流里直接使用 `spool`
两者不是互斥关系，而是前后配合关系。