Plan With Files — 持久化任务规划系统
概述
AI 编程助手最大的痛点是什么？每次新会话都要重新交代项目背景。 你花 15 分钟解释需求、描述架构、指定约束，然后会话结束——下次开始，一切归零。
Plan With Files 用最朴素却最有效的方式解决了这个问题：把计划写成 Markdown 文件，存放在项目目录中。 WorkBuddy 启动时自动读取规划文件，瞬间恢复完整上下文——任务目标、子任务进度、决策记录、已知约束，一目了然。
> 计划文件不是"聊天记录"，而是"可 diff、可 review、可交接的工程产物"。对中高级开发者和技术 PM 来说，这几乎是最刚需的能力补充。
为什么选择文件式规划
| 对比维度 | 聊天式记忆 | 文件式规划 |
|---|---|---|
| 持久性 | 依赖会话存储，可能丢失 | 文件永存，Git 管理 |
| 可审查性 | 难以回顾历史决策 | git log --planning/ 即可追溯 |
| 团队协作 | 仅自己可见 | 提交到仓库，全员可见 |
| 可交接性 | 新会话从零开始 | 读取文件即可接手续推进 |
| 可扩展性 | 上下文窗口有限 | 文件外存，无窗口压力 |
| 格式 | 非结构化 | 标准化 Markdown 模板 |
规划文件格式
主计划文件 .planning/plan.md
# 项目规划：用户认证模块重构
## 元信息
- **创建日期**：2026-07-18
- **目标日期**：2026-07-25
- **优先级**：High
- **状态**：进行中
## 目标概述
将现有的 Session-based 认证迁移为 JWT + Refresh Token 双 token 方案，
支持移动端和 Web 端统一认证。
## 任务分解
### 1. 后端 JWT 基础设施 ✅
- [x] 1.1 添加 pyjwt 依赖
- [x] 1.2 实现 token 生成工具类
- [x] 1.3 实现 token 验证中间件
### 2. Refresh Token 机制 🔄
- [ ] 2.1 设计 refresh token 数据模型
- [x] 2.2 实现 token 刷新 API
- [ ] 2.3 实现 token 黑名单
### 3. 前端适配 ⏳
- [ ] 3.1 封装认证拦截器
- [ ] 3.2 实现 token 自动刷新
- [ ] 3.3 更新登录/登出流程
## 决策记录
### 决策 #1：Token 存储方案
- **日期**：2026-07-18
- **选项 A**：localStorage（方便但有 XSS 风险）
- **选项 B**：httpOnly Cookie（安全但不适合移动端）
- **选项 C**：Web 端用 httpOnly Cookie，移动端用 Secure Storage ✅
- **结论**：选择 C，兼顾安全性和跨平台需求
- **影响**：需要实现平台检测逻辑
### 决策 #2：Refresh Token 过期策略
- **日期**：2026-07-18
- **结论**：Access Token 15min，Refresh Token 7 天，滑动过期
- **理由**：平衡安全性和用户体验
## 约束与注意事项
- 必须向后兼容现有的 Session 认证（至少到 Q3）
- 移动端 SDK 版本需 ≥ 2.1.0
- 不能修改 `/api/v1/legacy/*` 路由
## 会话恢复提示
上次会话完成了任务 1.2 和 2.2。
接下来应该继续任务 2.3（token 黑名单实现）。
子任务模板 .planning/tasks/2.3-token-blacklist.md
# 任务 2.3：Token 黑名单实现
## 状态：待开始
## 优先级：High
## 预估时间：4h
## 依赖：2.1（数据模型）, 2.2（刷新 API）
## 描述
实现 token 黑名单机制，当用户登出或 token 被盗用时，
将 refresh token 加入黑名单，阻止其继续使用。
## 技术方案
使用 Redis SET 存储黑名单 token 的 jti，
TTL 设置为 token 过期时间。
## 验收标准
- [ ] 登出时 refresh token 被加入黑名单
- [ ] 黑名单中的 token 无法用于刷新
- [ ] Redis 故障时降级为全部拒绝（安全优先）
- [ ] 单元测试覆盖率 ≥ 80%
## 相关文件
- `src/auth/token_service.py`
- `src/auth/blacklist.py`（待创建）
- `tests/auth/test_blacklist.py`（待创建）
快速上手
初始化规划系统
# 在当前项目初始化
$plan init
# WorkBuddy 自动创建 .planning/ 目录结构：
# .planning/
# ├── plan.md # 主计划文件
# ├── decisions.md # 决策日志
# ├── tasks/ # 子任务详情
# └── config.yaml # 规划系统配置
开始规划
# 描述你的任务，WorkBuddy 自动生成结构化计划
$plan create "实现用户认证模块的 JWT 迁移"
# WorkBuddy 会：
# 1. 分析任务复杂度
# 2. 拆解为可执行子任务
# 3. 生成 .planning/plan.md
# 4. 自动提交到 Git（可配置）
恢复上下文
# 新会话开始时，WorkBuddy 自动执行：
# 1. 读取 .planning/plan.md
# 2. 识别未完成的任务
# 3. 加载最近的决策记录
# 4. 提示你当前进度
# 你也可以手动触发
$plan resume
计划命令系统
计划管理
| 命令 | 说明 |
|---|---|
$plan init |
初始化规划系统 |
$plan create "<描述>" |
创建新计划 |
$plan resume |
恢复当前计划上下文 |
$plan status |
显示当前进度概览 |
$plan list |
列出所有活跃计划 |
$plan archive |
归档已完成计划 |
任务管理
| 命令 | 说明 |
|---|---|
$plan task add "<描述>" |
添加子任务 |
$plan task start <任务ID> |
开始执行子任务 |
$plan task complete <任务ID> |
标记子任务完成 |
$plan task block <任务ID> --reason "<原因>" |
标记子任务阻塞 |
$plan task detail <任务ID> |
查看子任务详情 |
决策管理
| 命令 | 说明 |
|---|---|
$plan decide "<标题>" |
记录技术决策 |
$plan decisions |
查看所有决策记录 |
$plan decision <编号> |
查看特定决策详情 |
进度跟踪
$plan status
输出示例：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
用户认证模块重构 — 进度 55%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 1. 后端 JWT 基础设施 (3/3)
🔄 2. Refresh Token 机制 (1/3)
✅ 2.2 实现 token 刷新 API
⏳ 2.1 设计数据模型
❌ 2.3 token 黑名单（阻塞：等待 Redis 集群部署）
⏳ 3. 前端适配 (0/3)
下一步：继续任务 2.1
工作流模式
模式一：单人大项目开发
第 1 天:
$plan create "构建电商后台管理系统"
→ WorkBuddy 拆解为 20+ 子任务
→ 完成任务 1-3
第 2 天（新会话）:
$plan resume
→ 自动加载进度：已完成 3/20，接下来是任务 4
→ 无需重新解释项目背景
→ 继续推进
第 N 天:
$plan status → 查看进度
$plan archive → 项目完成，归档记录
模式二：Bug 修复流程
$plan create "修复支付回调重复处理 Bug"
# WorkBuddy 自动生成：
# 1. 问题描述
# 2. 复现步骤
# 3. 根因分析（逐步填写）
# 4. 修复方案
# 5. 验证步骤
# 6. 回归测试清单
模式三：技术方案调研
$plan create "评估消息队列方案：RabbitMQ vs Kafka vs Redis Streams"
# WorkBuddy 自动生成对比表格模板：
# - 性能指标对比
# - 运维复杂度
# - 生态集成
# - 成本估算
# 每个子任务完成后自动填入结论
团队协作
Git 集成
规划文件存放在 .planning/ 目录，纳入版本控制：
# 团队成员拉取最新计划
git pull
$plan resume # WorkBuddy 自动读取最新计划
# 提交计划更新
git add .planning/
git commit -m "plan: 完成任务 2.3 token 黑名单实现"
# 查看计划演进
git log --oneline -- .planning/plan.md
冲突处理
规划文件可能产生 Git 冲突。Plan With Files 提供冲突解决辅助：
$plan resolve-conflict
# WorkBuddy 分析冲突内容，给出合并建议
团队规范
建议在团队中统一以下约定：
# .planning/config.yaml
team:
naming: "task-{id}-{slug}.md" # 子任务文件命名规范
require_review: true # 关键决策需要 PR 审查
auto_commit: false # 不自动提交，手动审查后提交
notify_on_complete: true # 任务完成时通知团队
最佳实践
1. 计划粒度适中
- ❌ 太粗：「实现用户系统」（一个任务拆不满）
- ✅ 适中：「实现用户注册 API」（3-5 个子任务）
- ❌ 太细：「在 models.py 第 15 行添加 email 字段」
2. 决策及时记录
# 不要等到事后回忆
# 在做技术选型的同时记录决策
$plan decide "数据库选型：PostgreSQL vs MySQL"
→ WorkBuddy 引导你填写选项对比和结论
3. 阻塞任务标注原因
$plan task block 2.3 --reason "等待运维部署 Redis 集群，预计 7/20 完成"
# 其他团队成员看到后可以主动协助或调整计划
4. 定期回顾
# 每周五回顾本周计划进展
$plan review --since "7 days ago"
# 输出：
# 本周完成：8 个任务
# 新增任务：3 个
# 阻塞任务：1 个（等待外部依赖）
# 决策记录：2 条
5. 清理归档
# 项目完成后归档
$plan archive --move-to docs/archive/2026-q3/
# 定期清理废弃的计划草稿
$plan clean --older-than 30d --dry-run
常见问题
Q: 规划文件会不会和代码一起被部署？
A: .planning/ 目录仅用于开发阶段，建议在 .dockerignore 和部署配置中排除。它不会影响生产环境。
Q: 和 ECC Toolkit 的记忆系统有什么区别？
A: ECC Toolkit 的记忆系统是自动的、隐式的；Plan With Files 是显式的、结构化的。两者可以互补——ECC 自动捕获会话上下文，Plan With Files 手动管理任务规划。推荐同时使用。
Q: 计划文件会不会变得非常大？
A: 主 plan.md 建议控制在 200 行以内。超过则拆分为多个子任务文件。WorkBuddy 启动时只加载主计划（~2KB），按需读取子任务详情。
Q: 多人同时编辑计划文件冲突怎么办？
A: 建议在团队中采用"任务认领"模式：每个开发者认领不同的子任务，减少同一文件的编辑冲突。冲突发生时使用 $plan resolve-conflict 辅助解决。
Q: 可以用于非代码项目吗？
A: 当然。Plan With Files 是一个通用的任务规划系统，可以用于技术方案调研、系统架构设计、项目管理工作分解等任何需要结构化规划的领域。
Plan With Files — 把计划从聊天记录里拽出来，变成可 diff、可 review、可交接的工程资产。
