progress-doc · 进度文档代替长会话
这个 skill 解决什么
长会话越堆越长，上下文越来越重、容易跑偏、换会话就断。本 skill 用一份轻量 Markdown 进度文档取代超长会话：
- 每个任务 / 领域一份独立进度文档
- 推进中持续更新它（不是更新对话历史）
- 新会话第一句「先读进度文档」，AI 读一份文件就能恢复全部上下文
比维持一个超长会话轻量得多，且跨会话、跨设备、可交接。
🛡️ 为什么「删 WorkBuddy 空间 / 会话也不丢项目上下文」
这是本 skill 最重要的保证，务必记住：
- 进度文档是本地磁盘文件（
<workspace>/.workbuddy/progress/<任务名>.md，或任意--dir），不依赖 WorkBuddy 的云端会话/空间。 - 即使你删掉 WorkBuddy 的某个会话、关闭空间、甚至清空云端历史，这些 .md 文件仍然躺在磁盘上，毫发无损。
- 新会话（哪怕是新空间、新设备、跨人交接）只要说一句「先读进度文档 —— <任务名>」，AI 读一份本地文件就能秒恢复全部上下文。
- 结论：会话会死，文档长在。把上下文固化进进度文档，就等于把记忆外置到不会过期的介质上。
🔁 实时增量更新（默认行为 · 收尾铁律）
每次任务推进到一个节点（完成一个子任务 / 一个阶段 / 一次迭代收尾），必须自动把进展写回对应进度文档——无需老板提醒。
- 落盘命令：
python progress_doc.py update <任务名> --note "做了什么" [--section 已完成|进行中|待办|关键决策|上下文恢复要点|相关文件] - 跑过的每个项目都回写各自文档，保证「对所有项目做实时增量更新」覆盖到位。
- 收尾前 30 秒写回，比事后补记准得多。这是「接上之前的任务始终有料」的唯一可靠做法。
进度文档放哪
默认工作区内的 .workbuddy/progress/ 目录（不污染项目根、随项目走）：
<工作区>/.workbuddy/progress/<任务名>.md
也可 --dir 指定任意目录（如 E:/project/lianghua/.workbuddy/progress/）。
三种用法
用法 A：创建 / 初始化进度文档
触发：「开个进度文档」「给 XX 任务建进度文档」「记一下进度」
- 运行 progress_doc.py init <任务名> [--title 标题] [--dir 目录]
- 自动写入标准模板（见下），含当前目标 / 已完成 / 进行中 / 待办 / 关键决策 / 上下文恢复要点 / 变更日志
- 告诉老板文档路径，请老板把这句话记在脑子里：「下次新会话说『先读进度文档 —— <任务名>』」
用法 B：更新进度文档
触发：「更新进度文档」「把刚做的记进进度文档」「进度变了」
- 用 Edit 工具改写对应段落（不要整篇重写，只改变化的字段）
- 务必同步更新顶部「最后更新」日期 + 底部「变更日志」加一行
- 优先更新「上下文恢复要点」段——这是给未来会话看的，越准越省事
用法 C：只读恢复上下文（新会话开头）
触发：老板说「先读进度文档」「先读进度文档 —— <任务名>」「恢复 XX 任务上下文」
- 运行 progress_doc.py list 列出所有进度文档（老板没说具体哪个时）
- 用 Read 读取目标文档，回复一段结构化摘要（当前目标 / 卡在哪 / 下一步），然后直接接着干
- 不要复述整篇文档，只提炼 AI 行动需要的信息
用法 D：实时增量更新（收尾自动写回 · 核心）
触发：「任务收尾」「把进展写回」「增量更新进度」「更新一下 XX 的进度」
- 运行 progress_doc.py update <任务名> --note "本次做了什么" [--section <段落>] [--dir 目录]
- 命令会：① 刷新顶部「最后更新」日期；② 在「变更日志」追加一行（最新在上）；③ 若给了 --section，再在该段落追加一条。
- 这是默认行为：任何任务推进到收尾节点，AI 主动跑这条命令，把动过的每个项目进度文档都写回。
- 需要大幅改写（而非追加）时，才用 Edit 直接改对应段落（见用法 B）。
标准模板
# 进度文档：<任务名>
> 创建：YYYY-MM-DD ｜ 最后更新：YYYY-MM-DD
## 🎯 当前目标
（一句话：这个任务/领域要达成什么）
## ✅ 已完成
-
## 🔄 进行中
-
## 📋 待办（按优先级）
- [ ]
## 🧠 关键决策 / 约定
- （技术选型、接口约定、老板偏好、踩过的雷）
## 🔗 上下文恢复要点（给新会话看）
- 项目/任务的关键背景、约束、雷区
- 哪些文件是核心、改了会有什么连锁反应
-
## 📎 相关文件 / 链接
-
## 📝 变更日志
- YYYY-MM-DD：初始化进度文档
辅助脚本
progress_doc.py（纯标准库，无需额外依赖）：
- python progress_doc.py init <任务名> [--title 标题] [--dir 目录] → 创建模板
- python progress_doc.py list [--dir 目录] → 列出全部进度文档及修改时间
- python progress_doc.py read <任务名> [--dir 目录] → 打印文档内容（方便 AI 直接读）
- python progress_doc.py update <任务名> --note "进展" [--section 已完成|进行中|待办|关键决策|上下文恢复要点|相关文件] [--dir 目录] → 增量写回（收尾铁律）
使用托管 Python：
C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe progress_doc.py init <任务名>
平台适配（Windows + WorkBuddy）
- 进度文档用 UTF-8，中文无乱码
- 任务名会自动转成安全文件名（去掉
/ \ : * ? " < > |等非法字符） - 不依赖网络、不调用任何外部服务，纯本地文件
安全 / 约定
- 进度文档是个人工作记录，含未决决策与雷区，勿外发
- 只动
.workbuddy/progress/内的进度文档；不要借机改写项目代码 - 「先读进度文档」是只读动作，不要擅自开始大改，先给摘要确认再动手
- 一份文档对应一个任务/领域；若一个领域裂成多个独立方向，拆成多份文档，别堆一份里
红色警戒
- 不要为了「完整」把整段对话贴进进度文档——它要的是决议与状态，不是流水账
- 文档不更新 = 没用。每次任务推进收尾前，跑
progress_doc.py update <任务名> --note "..."把状态写回，这是默认动作，不要等老板提醒 - 删 WorkBuddy 空间/会话不会丢上下文——文档在本地磁盘；但前提是「收尾前已写回」，否则没写的内容照样不在文档里
- 老板说「先读进度文档」但没说哪个任务时，用
list列出让他选，别瞎猜
适用场景 / 常见疑问 / 反模式 / 快速示例
- 适用场景：见上方 SKILL.md 正文（受众 + 触发词 + 能力边界）。
- 常见疑问：是否联网 / 读取私钥？→ 默认只读、零网络外呼、无密钥访问（详见 SKILL.md 安全约定）。
- 反模式：不要期望它在所有场景都给答案；超出能力边界时它会诚实说明，而非编造。
- 快速示例：见 SKILL.md 中的命令 / 脚本用法与模板。
