子任务与依赖

Backlog.md 支持通过子任务拆分复杂工作，以及通过依赖关系定义任务间的执行顺序。

子任务创建

在创建任务时，使用 --parent（或 -p）指定父任务 ID，即可创建子任务：

backlog task create "设计数据库表" -p back-4
backlog task create "实现 REST API" -p back-4
backlog task create "编写单元测试" -p back-4

小数编号规则

子任务使用小数编号体系，格式为 父任务ID.序号：

编号规则：

• 子任务序号按创建顺序自动递增
• 一个父任务可以拥有任意数量的子任务
• 子任务本身不能再拥有子任务（单层结构）
• 子任务在列表、看板、Web UI 中默认与父任务关联展示

查看子任务

# 查看指定父任务的所有子任务
backlog task list -p back-4

# 查看任务详情时，子任务会自动列出
backlog task view back-4

修改父子关系

已存在的任务可以改换父任务（重定父），无需删除重建：

# 将任务挂到新父任务下
backlog task edit back-10 --parent back-4

# 解除父子关系（回到顶层）
backlog task edit back-10 --clear-parent

--parent / --clear-parent 由 CLI 与 MCP 共享实现：只改写任务的 parent_task_id 边、对输入 ID 做归一化，并在写入前防止构成环（会回滚并报错）。重定父不改变任务的序号或内容，仅调整层级归属。

依赖任务设置

创建任务时，使用 --dep（或 --depends-on）指定依赖的其他任务：

backlog task create "部署到生产环境" \
  --dep "back-5,back-6" \
  --notes "需等前端和后端任务都完成后才能部署"

也可在任务创建后追加或修改依赖：

# 覆盖设置依赖
backlog task edit back-10 --dep "back-3,back-4"

# 依赖多个任务时可多次使用选项
backlog task edit back-10 --dep "back-3" --dep "back-4"

依赖目标的解析规则

依赖目标在工作副本任务与 completed 语料中解析：

• 依赖一个已完成任务是合法的——完成记录正是就绪判定读取的"完成证据"
• 归档任务的 ID 会被新任务复用，因此归档记录不参与依赖解析；只存在于归档中的 ID 视同未知 ID
• 一个 ID 被多条记录同时声称，或一次输入命中多个身份时，命令以歧义错误失败（fail-closed），不会任选一个
• 草稿不能作为依赖目标（草稿可以依赖任务，但任务不能依赖草稿）

写入门禁：自依赖与循环拒绝

创建和编辑依赖时，系统执行硬校验：

• 依赖自身（--dep back-10 写在 back-10 上）被拒绝
• 会形成循环的依赖被拒绝，错误信息中给出完整链路（如 TASK-1 -> TASK-2 -> TASK-1）
• 无法解析的新依赖条目被拒绝（创建时一律严格）

对存量缺陷的软化规则：编辑任务时，记录中原本就存在且本次未改动的无法解析条目会被原样保留（CLI 打印警告，JSON/MCP 结果中以数据形式携带），不会因顺手改标题就被迫清理历史债；一旦重写该条目则按新规则校验。

依赖缺陷诊断（doctor）

backlog doctor 新增依赖缺陷报告，按类别分节列出整个语料的问题：

• 循环依赖（含自环），按 ID 顺序列出
• 悬空依赖：引用了不存在 ID 的任务逐条列出
• 草稿目标：任务依赖了草稿（被禁止的方向）
• 已释放 ID：依赖指向已归档、编号可被复用的旧 ID，附带可能重新绑定的警告
• 歧义引用：与重复 ID 报告交叉引用

该报告是纯诊断：只报告、不修复（--fix 仍只修复重复 ID）；依赖缺陷不影响退出码——语料中长期存在的历史问题不应让每次诊断都失败。

依赖关系对序列的影响

Backlog.md 会根据任务间的依赖关系自动计算执行序列（Sequences）：

• 无依赖、无被依赖、无 ordinal 的任务归类为 Unsequenced（未排序）
• 有依赖关系的任务按拓扑排序分层，形成 Sequence 1、Sequence 2……
• 同一 Sequence 中的任务互不依赖，可以并行执行
• 不同 Sequence 之间存在先后关系，Sequence N 的所有任务必须在 Sequence N-1 完成后才能开始

查看序列

backlog sequence list

输出示例：

Unsequenced:
  back-8 - 优化构建速度

Sequence 1:
  back-1 - 设计数据库表
  back-2 - 搭建项目骨架

Sequence 2:
  back-3 - 实现用户注册 API
  back-4 - 实现用户登录 API

Sequence 3:
  back-5 - 部署到测试环境

在上述示例中：

• back-1 和 back-2 可以并行开发
• back-3 和 back-4 依赖于 back-1 和 back-2，需等它们完成后才能开始
• back-3 和 back-4 之间可以并行
• back-5 依赖于 back-3 和 back-4，必须在最后执行

Web UI 依赖项钻取

在 Web 界面的任务详情面板中，Dependencies 区域会列出该任务的所有依赖任务。每个依赖任务以蓝色标签形式展示：

• 点击依赖任务标签：直接打开该依赖任务的详情面板，无需返回看板或列表重新查找
• 返回按钮：当通过点击依赖进入子任务后，任务详情面板标题栏左侧会出现 ← 返回 箭头按钮，点击即可回到上一层父任务
• 关闭按钮：点击右上角的 × 与浏览器后退等价，每次退一层——已钻取时先回到上一层父任务，回到最外层后再点一次即关闭整个模态框

此功能在新建任务或编辑任务模式下不可用，仅在预览（preview）模式下生效。

模态框中的父子层级区块

任务详情模态框在标题下方提供层级区块，便于在模态框内直接上下浏览：

• PARENT 行：当前任务有父任务时显示，包含父任务 ID、标题与状态标签，点击即打开父任务
• SUBTASKS 区：当前任务有子任务时显示完成计数（如 1/6）与进度条，点击区块标题行展开或折叠；每条子任务显示完成指示、ID、标题、状态标签与钻取箭头，点击即打开该子任务

两个区块都只在相应关系存在时渲染；没有父子关系的任务不会出现该区块。

已完成子任务也纳入视图：父任务的 SUBTASKS 区现在同时列出 active 与 completed 子任务，已完成子任务此前会在父视图中消失的问题已修复；完成计数（如 1/6）据此正确统计。约 100 个历史文件仍使用旧的 task- 前缀引用，不在此特性的改写范围内。

通过 Markdown 链接钻取

在任务描述、文档、决策记录和 Wiki 页面中，如果包含指向其他任务的 /task/:id 链接（如 http://localhost:6420/task/506），点击后也会在模态框中直接打开目标任务，体验与点击依赖标签一致：

• 支持前缀无关匹配：裸数字（如 /task/123）与带前缀的完整 ID 都能正确解析
• 系统会将完整 URL 自动渲染为短别名 TASK#506，提升可读性
• 钻取后同样支持返回按钮和浏览器前进/后退导航

稳定 URL 与分享

每个任务都有独立的 /task/:id/:title URL：

http://localhost:6420/task/506/Fix-CLI-actualStart-actualEnd-missing-local-to-UTC-conversion

你可以直接复制地址栏链接分享给团队成员，对方打开后会以默认视图为背景显示该任务详情，并能继续钻取其依赖关系。

依赖规划建议