任务生命周期
Backlog.md 中每个任务都是一份独立的 Markdown 文件，从想法萌芽到最终归档，经历完整的状态流转。
状态流转
任务从创建到完结的完整流程如下：
Draft（草稿） → To Do → In Progress → Done → Archived / Completed
| 状态 | 说明 |
|---|---|
| Draft | 草稿状态，使用独立 ID 空间（如 draft-1），不占用正式任务编号 |
| To Do | 新建任务的默认状态，等待开始 |
| In Progress | 开始工作时手动标记，或通过 AI 代理自动更新 |
| Done | 工作已完成，任务仍保留在 backlog/tasks/ 目录中 |
| Archived | 执行 backlog task archive 后移入 backlog/archive/tasks/，属于软删除 |
| Completed | 执行 backlog cleanup 后，Done 任务被移入 backlog/completed/ 目录 |
状态机
上表是默认状态列；项目的实际状态列由 backlog/config.yml 的 statuses 配置声明，支持带语义的对象形式：
| 字段 | 说明 |
|---|---|
name |
状态名（列标签） |
category |
六类之一：initial / active / wip / blocked / done / dropped，取代「末位即终态」的位置约定 |
exit |
终态的离开动作（如 archive） |
display |
false 时看板隐藏该列（列内任务一并隐藏） |
next |
转换边数组，每条边可声明 when / requires / evidence / ai 权限 |
要点：
- 新初始化的项目使用内置七列默认状态机（To Do → Planning → Plan Review → In Progress → In Review → Done，另含留档终态 Dropped）。CLI 的
config只有 get/set/list 子命令，没有重置命令；要恢复默认状态机，需在 Web 设置页的状态机编辑器中点 Default 按钮——该按钮只把默认状态机载入编辑器，仍需保存才生效 - 默认机器已内置收尾门禁：
In Progress → In Review要求任务文件按 task-finalization 完成、In Review → Done要求按 task-finalization 验收通过——新项目开箱即带，无需手动配置（BACK-816 把定稿门禁同步进了四语言默认机器） - 状态机只声明、不强制：越界推进不报错，但 CLI/MCP 指南（
backlog instructions overview）会渲染完整的状态表、类别、迁移边与「停下等人工」清单，AI 代理按声明的机器工作 - 旧式字符串数组配置仍兼容；设置页提供可视化状态机编辑器维护对象形式配置
- 完整语义见 wiki 概念页 状态机语义
任务文件结构
每个任务文件顶部包含 YAML frontmatter，用于存储结构化元数据；正文部分记录任务描述、验收标准、实现计划等信息。
---
id: back-10
title: "任务标题"
status: "In Progress"
assignee: ["@user"]
reporter: "@user"
created_date: "2026-05-06"
updated_date: "2026-05-06"
completed_date: "2026-05-06"
labels: ["feature", "backend"]
priority: high
milestone: "M1 - CLI"
dependencies: ["back-1", "back-2"]
references: ["https://docs.example.com", "src/api.ts"]
docs: ["doc-1"]
ordinal: 1000
type: feature
dueDate: "2026-05-20"
plannedStart: "2026-05-10"
plannedEnd: "2026-05-18"
actual_start: "2026-05-10 09:00"
actual_end: "2026-05-15 18:30"
parentTaskId: "back-4"
---
核心字段说明
| 字段 | 说明 | 示例 |
|---|---|---|
id |
任务唯一标识，支持自定义前缀 | back-10、proj-42 |
title |
任务标题，单行文本 | "实现用户登录" |
status |
当前状态，必须在项目配置的 config.statuses 列表中 |
"To Do"、"In Progress" |
assignee |
负责人列表，使用 @username 格式 |
["@alice", "@bob"] |
reporter |
创建人 | "@alice" |
priority |
优先级，可选 high、medium、low |
high |
milestone |
所属里程碑的 ID 或标题 | "M1 - CLI" |
dependencies |
依赖的其他任务 ID 列表 | ["back-1", "back-2"] |
ordinal |
自定义排序权重，数值越小越靠前 | 1000 |
type |
任务类型，如 bug、feature、enhancement、docs |
feature |
dueDate |
截止日期（ISO 格式，date-only） | "2026-05-20" |
plannedStart |
计划开始日期（ISO 格式，date-only） | "2026-05-10" |
plannedEnd |
计划结束日期（ISO 格式，date-only） | "2026-05-18" |
actual_start |
实际开始时间（UTC datetime） | "2026-05-10 09:00" |
actual_end |
实际结束时间（UTC datetime） | "2026-05-15 18:30" |
parentTaskId |
父任务 ID，存在时该任务为子任务 | "back-4" |
labels |
标签列表 | ["backend", "api"] |
references |
外部引用链接或文件路径 | ["src/api.ts"] |
docs |
关联文档 ID | ["doc-5"] |
实际时间自动填充
actualStart 和 actualEnd 用于追踪任务实际开始和完成时间，系统会在特定条件下自动填充：
- 当任务状态从其他状态变更为 In Progress 时，若
actualStart为空，自动设置为当前日期时间 - 当任务状态变更为 Done（或其他终态）时，若
actualEnd为空，自动设置为当前日期时间 - 创建任务时直接指定
--status "In Progress"或--status "Done"也会触发自动填充 - 自动填充仅在字段为空时执行，你可以随时手动覆盖
状态变更方式
通过 CLI
# 标记为进行中
backlog task edit <id> --status "In Progress"
# 标记为已完成（将状态设为终端状态，通常为 Done）
backlog task edit <id> --status "Done"
# 归档任务
backlog task archive <id>
通过 TUI 看板
运行 backlog board 启动终端看板，选中任务卡片后使用方向键或快捷键在不同状态列之间移动。
通过 Web UI
运行 backlog browser 启动浏览器界面，在看板视图中拖放任务卡片到目标状态列。
通过 AI 代理（MCP）
AI 代理可直接调用 update_task 工具变更任务状态，无需人工介入。
重复任务 ID 检测与修复
正常情况下，任务 ID 在创建时即保证唯一。但跨分支合并、零填充等价（back-1 与 back-01）、外部或手动编辑仍可能产生重复的任务 ID，导致任务在视图、搜索和编辑中静默坍缩。
使用 backlog doctor 检测并修复重复 ID：
# 预览冲突（列出冲突组、文件路径、计划的重命名、需人工审查的引用）
backlog doctor
# 确认修复并丢弃 .bak 备份（最终化）
backlog doctor --commit
# 回滚修复（恢复 .bak 备份）
backlog doctor --rollback
修复原则：只改动任务文件名与 frontmatter 中的 id，保留内容；重命名与 frontmatter 同步进行（原子性）；对歧义结构 fail-closed 不猜测引用；操作可回滚（生成 .bak 备份），--commit/--rollback 均需人工确认后执行。
序号变更不影响 updated_date
仅调整任务序号（如看板重排、批量排序）时，任务的 updated_date 不会被刷新，避免产生无意义的 Git diff 噪音。只有当任务内容或元数据真正变化时，updated_date 才会更新。