归档与清理

随着项目推进，已完成的任务会不断累积。Backlog.md 提供归档和清理机制，帮助你保持任务列表的整洁。

归档任务

归档是将不再活跃的任务移入 backlog/archive/tasks/ 目录的操作，属于软删除：

backlog task archive back-10

归档后：

• 任务文件从 backlog/tasks/ 移入 backlog/archive/tasks/
• 任务不再出现在默认的任务列表、看板和搜索结果中
• 原任务 ID 被释放，后续新建任务可以复用该编号

归档草稿

草稿也可以单独归档：

backlog draft archive draft-2

已归档任务 ID 可复用

Backlog.md 的 ID 分配机制会自动跳过已被占用的编号。归档任务后，其原 ID 会被系统回收，后续执行 backlog task create 时可能分配到该编号。

腾出 ID 时的引用清理

归档（task archive）与降级（task demote）会自动清理其他任务对腾出 ID 的引用：

• 活跃任务与 completed 语料中指向该 ID 的依赖、引用会被移除或修正，防止 ID 复用后旧引用静默绑定到新任务
• 清理涉及的任务 ID 会在 CLI 输出、MCP 结果与 Web 响应（cleanedTaskIds）中列出，自动提交时一并纳入提交范围
• 降级产生的草稿保留自己的依赖与父任务字段，但其他任务对它的引用被移除（而不是改写到新的草稿 ID）
• 完成（complete / cleanup）不做清理——completed 记录正是就绪判定需要的完成证据
• 归档与降级按本地工作副本解析（local-first），不会跨分支误改

被清理的任务文件同样受文件锁与自动提交覆盖，无需手工跟进。

清理命令

清理命令用于将已完成的旧任务从活跃目录批量移入 backlog/completed/ 文件夹：

backlog cleanup

执行后，交互式向导将引导你完成以下步骤：

1. 系统扫描所有处于终端状态（通常为 Done）的任务
2. 选择时间阈值：1 天、1 周、2 周、3 周、1 个月、3 个月或 1 年
3. 列出符合阈值的所有任务
4. 确认后批量移动到 backlog/completed/ 目录

Found 12 tasks marked as Done.

Move tasks to completed folder if they are older than:
> 1 month

Found 8 tasks older than 1 month:
  - back-3: 设计数据库表 (2026-04-01)
  - back-4: 实现用户注册 (2026-04-02)
  ... and 6 more

Move 8 tasks to completed folder? (y/N)

单任务完成清理

cleanup 面向批量清理；如果只想把单个终端状态任务移出活跃看板，使用 task complete：

backlog task complete back-10

与 cleanup 不同，task complete 只做完成迁移：校验任务处于终端状态（按 config.statuses 的类别/出口判定，不是「末位即终态」），然后把任务文件从 backlog/tasks/ 移入 backlog/completed/，不触碰其他任务中的引用——completed 语料正是其他任务就绪判定所需的完成证据。任务不在终端状态时命令报错，并提示先用 backlog task edit <id> -s "<终端状态>" 推进状态。

MCP 侧对应工具为 task_complete（参数 id），语义一致：仅接受本地任务，终态校验失败时返回 VALIDATION_ERROR。注意与 task_archive 的分工——task_archive 会拒绝终态任务并提示改用 task_complete。

归档与完成的区别

维护建议

保持活跃任务列表精简，有助于提升看板加载速度、改善搜索体验，并让团队聚焦于当前正在进行的工作。