# 终端 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`

两者不是互斥关系，而是前后配合关系。
