# 后续任务执行说明

## 目的

这份文档用于配合 [spool 后续任务拆解 TO DO list.csv](/Users/long/Work/spool/spool%20后续任务拆解%20TO%20DO%20list.csv) 使用，帮助你在新开的窗口里直接接手开发。

当前路线已经收敛为三条主线：

- 会话优先：把桌面端收敛成会话浏览、会话详情、继续对话、删除对话
- MCP 优先：把 `spool-mcp` 变成实际工作流里的上下文优化入口，而不是只在桌面端展示
- 检索优先：强化知识库检索、项目规范召回、知识提炼与回写闭环

## 开始前建议

建议先按这个顺序快速读一遍：

1. [docs/DESKTOP_PRODUCT_REFOCUS_PLAN.md](/Users/long/Work/spool/docs/DESKTOP_PRODUCT_REFOCUS_PLAN.md)
2. [docs/TERMINAL_AI_INTEGRATION.md](/Users/long/Work/spool/docs/TERMINAL_AI_INTEGRATION.md)
3. [docs/SESSION_HANDOFF.md](/Users/long/Work/spool/docs/SESSION_HANDOFF.md)
4. [docs/NEXT_STEPS.md](/Users/long/Work/spool/docs/NEXT_STEPS.md)

任务状态查看与推进：

```bash
python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py status --file '/Users/long/Work/spool/spool 后续任务拆解 TO DO list.csv' --verbose
python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py advance --file '/Users/long/Work/spool/spool 后续任务拆解 TO DO list.csv' --notes '本项已完成'
```

## 子任务 1

### 收敛会话浏览为分页列表与完整上下文详情

推荐入口文件：

- [src/session_sources.rs](/Users/long/Work/spool/src/session_sources.rs)
- [src/desktop.rs](/Users/long/Work/spool/src/desktop.rs)
- [src/desktop/tauri.rs](/Users/long/Work/spool/src/desktop/tauri.rs)
- [frontend/desktop.js](/Users/long/Work/spool/frontend/desktop.js)
- [frontend/desktop.css](/Users/long/Work/spool/frontend/desktop.css)

实施重点：

- 把会话列表稳定为默认第一页 10 条，按更新时间倒序
- 明确 `has_more`、`total`、当前页码的前后端契约
- 会话详情从“预览”升级成“可读的上下文查看器”，至少要能看最近消息、角色、时间、关联 memory
- 调整列表和详情区域比例，避免桌面端首屏信息过密

验收标准：

- 打开桌面端后，会话页默认只展示最近 10 条
- 点击“加载更多”会追加下一页，不会重复、不丢项
- 点击任意会话后可以看到清晰的对话上下文，而不只是摘要
- 当前工作目录匹配的会话在列表中有明确标识

建议验证：

- `cargo test --test tauri_smoke`
- `node --check frontend/desktop.js`

## 子任务 2

### 完善继续对话、删除会话与选择回退交互

推荐入口文件：

- [src/desktop.rs](/Users/long/Work/spool/src/desktop.rs)
- [src/session_sources.rs](/Users/long/Work/spool/src/session_sources.rs)
- [src-tauri/src/commands.rs](/Users/long/Work/spool/src-tauri/src/commands.rs)
- [frontend/desktop.js](/Users/long/Work/spool/frontend/desktop.js)

实施重点：

- “继续对话”必须更接近 `cc-switch` 的行为，直接打开终端并注入正确的会话标识
- 删除前增加确认或软删除保护，避免误删
- 删除后自动回退到相邻会话，避免详情区悬空
- 继续对话失败时要返回具体失败原因，不要只有通用报错

验收标准：

- Claude 会话可触发 `claude -r <session_id>`
- Codex 会话可触发 `codex resume <session_id>`
- 删除成功后列表与详情自动刷新并切换到下一条可用会话
- 删除失败和继续对话失败时，界面有可读错误信息

建议验证：

- `cargo test --test tauri_smoke`
- 在 macOS 本机手动点击一次“继续对话”和“删除对话”

## 子任务 3

### 建立 MCP 运行时增强追踪与状态回显

推荐入口文件：

- [src/mcp.rs](/Users/long/Work/spool/src/mcp.rs)
- [src/desktop_status.rs](/Users/long/Work/spool/src/desktop_status.rs)
- [src/desktop.rs](/Users/long/Work/spool/src/desktop.rs)
- [frontend/desktop.js](/Users/long/Work/spool/frontend/desktop.js)
- [docs/TERMINAL_AI_INTEGRATION.md](/Users/long/Work/spool/docs/TERMINAL_AI_INTEGRATION.md)

实施重点：

- 区分“已注册 MCP”与“当前会话实际使用过 MCP”
- 为 `prompt_optimize` 增加最近调用记录，至少记录时间、cwd、task、target、session/provider
- 桌面端状态区显示最近一次真实增强，而不是只显示静态推断
- 让用户能判断 MCP 是否真正参与了当前 AI 对话

验收标准：

- 仅注册配置时显示“已接入”
- 调用 `prompt_optimize` 后显示“已增强”，并能看到最近一次增强摘要
- 不同客户端的增强记录不会混淆
- 重启桌面端后仍能看到最近一次增强信息，或至少有明确的持久化策略说明

建议验证：

- `cargo test prompt_optimize_tool_should_return_combined_prompt_bundle --lib`
- 新增一组运行时追踪测试

## 子任务 4

### 抽离注入编排服务并统一 prompt_optimize 流程

推荐入口文件：

- [src/mcp.rs](/Users/long/Work/spool/src/mcp.rs)
- [src/memory_gateway.rs](/Users/long/Work/spool/src/memory_gateway.rs)
- [src/app.rs](/Users/long/Work/spool/src/app.rs)
- [src/output/prompt.rs](/Users/long/Work/spool/src/output/prompt.rs)

实施重点：

- 不要让 `mcp.rs` 同时承担协议层和注入编排层
- 抽一个明确的 orchestration/service 模块，统一：
  - context 构建
  - wakeup 构建
  - combined prompt 组装
  - 运行时追踪写入
- 桌面端和 MCP 后续都复用同一套注入编排

验收标准：

- `prompt_optimize` 不再直接堆在 `mcp.rs` 的分支逻辑里
- 编排服务有单元测试覆盖 context + wakeup + combined 三段输出
- 桌面端生成注入内容与 MCP 生成注入内容的行为一致

建议验证：

- `cargo test --lib`
- 对比桌面端生成结果与 MCP 返回结果

## 子任务 5

### 重构检索排序以强化约束、决策、规范与偏好召回

推荐入口文件：

- [src/engine/scorer.rs](/Users/long/Work/spool/src/engine/scorer.rs)
- [src/engine/selector.rs](/Users/long/Work/spool/src/engine/selector.rs)
- [src/domain/note.rs](/Users/long/Work/spool/src/domain/note.rs)
- [src/output/json.rs](/Users/long/Work/spool/src/output/json.rs)
- [docs/PRODUCT.md](/Users/long/Work/spool/docs/PRODUCT.md)

实施重点：

- 强化 `constraint`、`decision`、`preference`、`workflow`、`pattern` 在开发任务中的召回权重
- 让项目级规则优先于泛化知识
- 丰富可解释的 score reasons，避免黑盒排序
- 改善 section/excerpt 选取，让结果更像“可直接给 AI 的任务边界”

验收标准：

- 同一项目里，历史规范、边界、决策类笔记优先于普通笔记
- JSON 输出里能看见更清晰的打分原因
- 至少增加一组针对“项目规范召回”的回归测试
- 检索结果对当前开发任务更聚焦，减少无关知识片段

建议验证：

- `cargo test --lib`
- 为 scorer 和 selector 增加回归用例

## 子任务 6

### 实现项目级知识提炼、回写与二次召回闭环

推荐入口文件：

- [src/lifecycle_service.rs](/Users/long/Work/spool/src/lifecycle_service.rs)
- [src/lifecycle_store.rs](/Users/long/Work/spool/src/lifecycle_store.rs)
- [src/domain/memory_lifecycle.rs](/Users/long/Work/spool/src/domain/memory_lifecycle.rs)
- [src/session_sources.rs](/Users/long/Work/spool/src/session_sources.rs)
- [docs/OBSIDIAN_SCHEMA.md](/Users/long/Work/spool/docs/OBSIDIAN_SCHEMA.md)

实施重点：

- 从会话或增强结果中提炼项目约束、开发规范、架构决策
- 区分 raw memory、候选知识、已确认知识
- 为二次召回准备结构化字段，例如 `project_id`、`memory_type`、`source_ref`
- 优先做“可审阅的提炼”，不要直接污染 Obsidian 主知识库

验收标准：

- 至少存在一条从会话提炼到 memory 的可执行链路
- 提炼出的项目规范可以在同项目后续对话中被优先召回
- 保留来源链路，能追溯到原始会话或证据引用
- 不会把未经确认的草稿直接写入最终知识笔记

建议验证：

- `cargo test --lib`
- 手动构造一条会话提炼并再次检索验证召回

## 子任务 7

### 扩展多 AI 客户端适配与统一 MCP 管理能力

推荐入口文件：

- [src/desktop_status.rs](/Users/long/Work/spool/src/desktop_status.rs)
- [src/session_sources.rs](/Users/long/Work/spool/src/session_sources.rs)
- [docs/TERMINAL_AI_INTEGRATION.md](/Users/long/Work/spool/docs/TERMINAL_AI_INTEGRATION.md)
- [docs/DESKTOP_PRODUCT_REFOCUS_PLAN.md](/Users/long/Work/spool/docs/DESKTOP_PRODUCT_REFOCUS_PLAN.md)

实施重点：

- 保持一个 MCP 对多个 AI 客户端的策略不变
- 优先补客户端适配层，不要把 provider 分支散落进核心编排层
- 先把 Claude、Codex 做稳，再抽象 Cursor、Kiro、Antigravity 的接入契约
- 桌面端应更像“统一管理器”，而不是单个客户端的注入器

验收标准：

- provider 检测与会话读取逻辑可扩展，不靠散乱条件分支硬塞
- MCP 注册状态展示可继续扩展到更多客户端
- 文档中明确每个客户端的接入路径、配置位置和验证方式

建议验证：

- 为 provider 发现逻辑增加测试
- 校对文档示例与真实配置路径

## 子任务 8

### 补齐验证基线、运行文档与调试手册

推荐入口文件：

- [docs/DESKTOP_RUNBOOK.md](/Users/long/Work/spool/docs/DESKTOP_RUNBOOK.md)
- [docs/TERMINAL_AI_INTEGRATION.md](/Users/long/Work/spool/docs/TERMINAL_AI_INTEGRATION.md)
- [docs/README.md](/Users/long/Work/spool/docs/README.md)
- [src-tauri/Cargo.toml](/Users/long/Work/spool/src-tauri/Cargo.toml)
- [frontend/package.json](/Users/long/Work/spool/frontend/package.json)

实施重点：

- 明确“怎么运行、怎么测试、怎么调试、怎么验证 MCP 生效”
- 把桌面端、MCP、终端客户端三条链路的验证命令写清楚
- 给常见报错提供定位方式，尤其是配置路径、vault 路径、会话源路径
- 每完成一轮大改，都更新手册，避免文档再次过时

验收标准：

- 新窗口开发者不看聊天记录，只看文档也能跑起来
- 能快速定位：
  - 桌面端启动失败
  - MCP 注册失败
  - `prompt_optimize` 调用失败
  - 会话源未识别
- 文档内容与当前实现一致，不再保留过时操作描述

建议验证：

- 按文档完整走一遍桌面端启动与 MCP 接入流程
- 更新 [docs/README.md](/Users/long/Work/spool/docs/README.md) 的文档索引

## 执行顺序建议

建议按下面顺序推进，不要平均用力：

1. 子任务 1
2. 子任务 2
3. 子任务 3
4. 子任务 4
5. 子任务 5
6. 子任务 6
7. 子任务 7
8. 子任务 8

原因：

- 先把会话浏览和会话动作做顺，桌面端才有实际入口
- 再把 MCP 运行时增强做成“真实可见”
- 然后抽离编排与强化检索，回到真正的核心价值
- 最后再扩展多客户端和补齐文档/验证
