| name | wip-tracker |
| description | 当用户说"留档""存档""断头工作""继续之前的工作""有哪些未完成""WIP"或任务中断需要交接时使用。 未完成任务追踪：留档、查询、恢复、去重。关键词：留档、存档、继续、未完成、中断、接手。
|
wip-tracker (任务延续)
触发词
留档、存档、WIP、断头工作、继续之前的工作、有哪些未完成、接手、任务中断、上次做到哪了
概述
长任务跨多次会话时的延续机制。任务中断时创建留档（机器可读 JSON + 人类可读 MD），新 agent 接手时读留档从 next_steps 继续。让中断的任务能被无缝接手，不丢失上下文。
前置条件
.agents/wip/ 目录存在（不存在则创建）.agents/memory/wip_index.json 存在（不存在则创建为 []）
目录结构
.agents/wip/
{task_id}.json # 机器可读（id/title/status/goal/progress/next_steps/tags）
{task_id}.md # 人类可读（目标/探索历程/经验教训/中期结论/下一步）
task_id 命名规范：wip_ + 6位随机 hex（如 wip_a3f2c9），保证唯一- JSON 给 agent 读，MD 给人看，两者必须同步，不能只改一边
记忆索引
.agents/memory/wip_index.json 存所有任务的摘要列表：
[
{
"id": "wip_a3f2c9",
"title": "用户登录模块改造",
"status": "in_progress",
"progress": 60,
"updated_at": "2026-07-12T10:30:00",
"tags": ["auth", "backend"]
}
]
新增/更新留档后必须同步更新此索引。
工作流
场景 A：留档（任务中断/会话结束前）
-
生成 task_id：wip_ + 6位随机 hex
-
创建 JSON 留档 .agents/wip/{task_id}.json：
{
"id": "wip_a3f2c9",
"title": "任务标题（一句话）",
"status": "in_progress",
"goal": "这个任务要达成什么目标（1-2句）",
"progress": 60,
"current_state": "当前做到哪了，已完成哪些步骤",
"next_steps": [
"下一步1（具体可执行）",
"下一步2（具体可执行）"
],
"tags": ["模块标签"],
"related_files": ["相关源码路径"],
"related_skills": ["相关 skill 名"],
"related_memory_keys":
场景 B：查询（用户问"有哪些未完成"）
- 读取
.agents/memory/wip_index.json
- 按
status 分组汇总：
## 未完成任务（X 个）
### 进行中
- wip_a3f2c9 — 用户登录模块改造（60%）— 下一步：实现 token 刷新
- wip_b7e1d4 — 数据导出功能（30%）— 下一步：写 Excel 导出逻辑
### 阻塞中
- wip_c2f8a1 — 支付集成（10%）— 阻塞原因：等第三方 SDK 文档
### 已完成（最近 7 天）
- wip_d9a3e5 — 用户注册验证（100%）— 2026-07-10 完成
- 询问用户要继续哪个，或开始新任务
场景 C：恢复（用户说"继续 wip_xxx" 或 "继续之前的工作"）
- 如果用户指定了 task_id：直接读
.agents/wip/{task_id}.json 和 .md
- 如果用户说"继续之前的工作"：
- 读
.agents/memory/wip_index.json
- 找最近更新的
in_progress 任务
- 如果多个，列出让用户选
- 读取留档后向用户复述：
## 恢复任务：{标题}
- 目标：{goal}
- 上次进度：{progress}% — {current_state}
- 下一步：
1. {next_steps[0]}
2. {next_steps[1]}
从第 1 步继续吗？
- 用户确认后从
next_steps[0] 开始执行
- 执行过程中持续更新 JSON 的
current_state 和 progress
- 完成后更新
status: completed
场景 D：去重（用户提了和已有 WIP 相似的需求）
- 读取
.agents/memory/wip_index.json
- 用
tags 和 title 关键词匹配已有任务
- 如果匹配到相似任务：
这个需求和已有 WIP 可能相关：
- wip_a3f2c9 — 用户登录模块改造（tags: auth, backend）
要继续这个任务，还是创建新任务？
- 用户决定后走场景 C（继续）或场景 A（新建留档）
坑点清单（Gotchas）
- JSON 和 MD 不同步：只改了 JSON 忘了改 MD，或反过来。两者必须同步，下次 agent 读到不一致的信息会混乱
- next_steps 太抽象：写"完成登录功能"是垃圾留档，agent 无法直接执行。必须写"在
auth.py 第 45 行的 login() 函数中添加 token 刷新逻辑"
- 忘了更新 wip_index.json：留档文件创建了但索引没更新，用户问"有哪些未完成"时看不到
- status 字段混乱：只用
in_progress / blocked / completed 三种，不要自创状态
- 长期不清理：>90 天的已完成任务留档堆积，neat-freak 时应归档或删除
- blocked_reason 留空：status=blocked 时必须填 blocked_reason，否则 agent 不知道在等什么
关键规则
- 必须双格式留档：JSON（机器读）+ MD（人读），缺一不可
- 必须更新 wip_index.json：留档后索引必须同步
next_steps 必须具体可执行：写明改哪个文件、做什么、怎么验证- 绝不覆盖已有留档：更新时先读后改再写
- 必须向用户确认留档：留档后告知 task_id 和恢复方式
不要做
- 不要把整个会话日志塞进 MD 留档 — 只提炼目标/历程/教训/结论/下一步
- 不要在
next_steps 写"完成所有剩余功能"这种废话 — 拆成具体步骤
- 不要创建 task_id 时不检查是否已存在同名 — 用随机 hex 保证唯一
- 不要在留档里写敏感信息（密码、密钥）— 留档可能进版本控制
输入/输出
- 输入：当前任务上下文（留档时）或 task_id/索引（查询/恢复时）
- 输出：
.agents/wip/{task_id}.json + .agents/wip/{task_id}.md + 更新 .agents/memory/wip_index.json
依赖
| 依赖 | 路径 | 说明 |
|---|
| WIP 目录 | .agents/wip/ | 留档文件存放 |
| 索引文件 | .agents/memory/wip_index.json | 任务摘要列表 |
| 记忆目录 | .agents/memory/ | 相关功能记忆（如 feature_progress.json） |
