里程碑管理

里程碑用于将任务按迭代、版本或发布周期分组，是追踪阶段进度和规划路线图的核心工具。Backlog.md 的里程碑数据以 Markdown 文件形式存储在 backlog/milestones/ 目录中，与任务文件共同纳入版本控制。

创建里程碑

里程碑可通过 CLI、Web 界面或 MCP 创建。

CLI 创建

backlog milestone add "M3 - Web UI"

# 一次性设置描述、日期与关联文档
backlog milestone add "M3 - Web UI" \
  --description "本阶段的界面与交互目标" \
  --due-date 2026-07-31 --planned-start 2026-07-01 --planned-end 2026-07-25 \
  --doc doc-5 --doc doc-8

--doc 可重复使用以关联多个文档，空值会被拒绝；创建时会自动写入 created_date。

Web 界面创建

运行 backlog browser 启动 Web 界面。
点击导航栏的「里程碑」进入里程碑管理页。
点击「添加里程碑」按钮，输入里程碑名称（例如 M3 - Web UI）。
描述字段支持 Markdown 编辑、Mermaid 预览与粘贴上传图片（保存前自动 promote 到 paste/）。
点击保存，系统会在 backlog/milestones/ 下生成对应的里程碑文件。

提示：AI 代理用户可通过 MCP 工具的 milestone_add 直接创建里程碑，无需打开浏览器。

编辑里程碑

通过 CLI 编辑里程碑的标题、描述和日期字段：

backlog milestone edit M1 --title "M1 - 核心 CLI" --description "第一阶段目标" \
  --due-date 2026-06-30 --planned-start 2026-05-01 --planned-end 2026-06-15 \
  --actual-start "2026-05-01 09:00" --actual-end "2026-06-10 18:00"

# 清空日期字段
backlog milestone edit M1 --clear-due-date --clear-planned-end --clear-actual-start

支持通过标题或 ID 定位里程碑（模糊匹配）。
计划字段（dueDate / plannedStart / plannedEnd）格式为 YYYY-MM-DD。
实际字段（actualStart / actualEnd）格式为 YYYY-MM-DD HH:MM（UTC）。
传空字符串可清空对应字段。

里程碑也支持与任务一致的关联文档字段：

# 覆盖式设置关联文档
backlog milestone edit M1 --doc doc-5

# 追加 / 按值移除 / 清空
backlog milestone edit M1 --add-doc doc-8
backlog milestone edit M1 --remove-doc doc-5
backlog milestone edit M1 --clear-docs

--doc（设置）与 --add-doc（追加）在同一命令中互斥，--clear-docs 不可与同类其它标志混用；规则与任务的列表型字段完全一致。文档链接的增删属于实质性变更，会刷新 updated_date。

Web UI 中的里程碑日期编辑

在里程碑管理页点击里程碑卡片，可打开编辑弹窗：

Due Date / Planned Start / Planned End — date 输入框
Actual Start / Actual End — datetime-local 输入框
Documentation — 关联文档条目可直接在弹窗内预览渲染：本地（非 URL）条目是点击预览控件，打开与任务弹窗共享的应用内文件预览；http(s) 条目仍为外链在新标签页打开。预览在切换里程碑时自动复位，不会残留到弹窗关闭之后

里程碑的 actualStart / actualEnd 由下属任务的状态变化自动驱动：

当里程碑下任一任务变更为 In Progress 时，若 actualStart 为空，自动设为当前日期时间
当里程碑下最后一个非终态任务变更为 Done 时，若 actualEnd 为空，自动设为当前日期时间
你可以随时手动覆盖这些自动填充值

里程碑列表与详情

在终端中查看所有里程碑及其完成状态：

backlog milestone list

输出示例：

Active milestones (2):
  m-1: M1 - CLI (8/12 done)
  m-2: M2 - MCP 支持 (3/5 done)

Completed milestones (1):
  (collapsed, use --show-completed to list)

每个里程碑显示已完成任务数与总任务数的比值，一目了然地展示进度。

里程碑 ID 显示样式：里程碑 ID 在各界面统一以大写 M-N 形式显示，与任务 ID 的 TASK-9 风格对齐——Web 列表与详情弹窗用 em dash（M-9 — Title），TUI 里程碑行与 CLI milestone list --plain 的分节标题用连字符（M-9 - Title、## M-9 - Title (n tasks)）。这是纯显示层变更，存储格式与别名解析（m-2、2、M2 等输入形式）均不受影响。

查看已完成的里程碑

默认情况下，已完成的里程碑会被折叠，减少信息噪音。如需展开：

backlog milestone list --show-completed

纯文本输出（适合脚本解析）：

backlog milestone list --plain

# 分页窗口：窗口单位是里程碑
backlog milestone list --max-count 10
backlog milestone list --max-count 10 --skip 10
backlog milestone list --count

--plain 输出与 backlog board -m 完全一致的 Markdown 分组看板：先是「No Milestone」节，再按里程碑文件顺序分节，节内任务按 ### <状态> (数量) 小标题分组列出；默认排除 completed 目录中的任务，--show-completed 可将其纳入；空状态列自动收窄。

TUI 里程碑看板

在 TTY 中运行 backlog milestones 进入交互式里程碑看板：左侧为里程碑列表（Space 限定范围、Enter 查看元数据、N 新建），右侧为嵌入式任务看板，里程碑详情弹窗支持按 E 编辑日期与描述。详见 TUI 看板。

任务分配到里程碑

将任务归属到某个里程碑有三种方式：

1. 创建任务时指定

backlog task create "实现看板拖拽" -m "M2 - MCP 支持"

-m 选项支持模糊匹配，系统会自动找到最接近的里程碑。也可以使用里程碑 ID（如 m-2）或纯数字（如 2）。

2. 编辑现有任务

backlog task edit 7 --milestone "M2 - MCP 支持"

3. 按里程碑 ID 过滤任务列表

在 backlog task list 的里程碑过滤中，可以使用多种形式定位里程碑：

# 数字别名
backlog task list -m 2

# 规范 ID
backlog task list -m m-2

# 大小写变体
backlog task list -m "M2"

# 标题精确/部分匹配
backlog task list -m "MCP 支持"

过滤解析支持数字别名、规范 ID（m-N）、大小写变体以及带标点符号的标题，行为在 CLI、交互式任务列表和 MCP task_list 的 active/draft 路径中保持一致。如果查询没有匹配到任何里程碑，则返回空列表。

4. 清除里程碑归属

backlog task edit 7 --clear-milestone

5. Web 界面拖放分配

在 Web 界面的里程碑管理页中，「未分配任务池」展示了所有没有里程碑归属的任务。将任务卡片拖拽到目标里程碑卡片中即可完成分配，反向拖拽则可移除。

里程碑完成检测与归档

自动完成检测

当一个里程碑下的所有任务都进入 Done 状态时，系统会自动将该里程碑标记为已完成。在 backlog milestone list 中，它会从「Active milestones」区域移动到「Completed milestones」区域。

归档里程碑

已完成的里程碑如果长期保留在活跃列表中会累积噪音。可将其归档：

backlog milestone archive "M1 - CLI"

归档后的里程碑：

从活跃里程碑列表中移除
其下任务自动变为「未分配」状态（任务本身不会被删除，仅解除里程碑绑定）
文件移入归档区，ID 不再参与模糊匹配

归档操作支持通过标题或 ID 定位里程碑：

backlog milestone archive m-1
backlog milestone archive 1

归档不会修改任何任务文件——任务保留对该里程碑的引用。如果希望同时清空或改挂任务上的里程碑字段，请使用 remove（见下一节）。

created_date 与 updated_date

里程碑与任务一样自动维护两个时间戳：

created_date：创建时写入（UTC，YYYY-MM-DD HH:MM）
updated_date：仅在实质性变更时刷新——仅顺序调整不会刷新，文档链接的增删会刷新

backlog milestone list 会在条目后追加 (updated ...)（无更新记录时回退为 (created ...)）；MCP milestone_list 显示 Created: / Updated: 标签。历史文件缺少这两个字段时不会报错，显示时回退到 created_date。Web 界面在里程碑卡片上显示「最近更新」，详情页顶部信息框显示「创建于 / 更新于」。

移除里程碑（remove）

除 archive 之外还有 remove。两者都会把里程碑文件移入归档目录，区别在于是否处理任务文件上的里程碑字段：

# 默认：清空匹配任务的里程碑字段
backlog milestone remove "Release 1.0"

# 保留任务上的里程碑引用
backlog milestone remove "Release 1.0" --task-handling keep

# 改挂到另一个活跃里程碑
backlog milestone remove "Release 1.0" --task-handling reassign --reassign-to "Release 2.0"

操作	里程碑文件	任务文件
`archive`	移入归档目录	不修改，任务保留对该里程碑的引用
`remove --task-handling keep`	移入归档目录	不修改
`remove --task-handling clear`（默认）	移入归档目录	清空匹配任务的里程碑字段
`remove --task-handling reassign`	移入归档目录	改挂到 `--reassign-to` 指定的活跃里程碑

未分配任务池

未归属任何活跃里程碑的任务构成了「未分配任务池」。在 Web 界面的里程碑页中，这些任务集中展示在页面顶部，方便你：

快速审视尚未纳入迭代规划的工作项
批量拖拽分配到合适的里程碑
识别遗漏或需要重新排期的任务

在终端中，未分配任务不会在 backlog milestone list 中显示，但可以通过筛选查看：

backlog task list --milestone ""

在看板中按里程碑分组

TUI 看板和 Web 看板都支持里程碑分组模式：

# TUI 看板按里程碑泳道展示
backlog board --milestones

在此模式下，看板不再单纯按状态分列，而是在每列内按里程碑形成横向泳道，帮助你直观对比各迭代的剩余工作量。

里程碑管理

里程碑管理

创建里程碑

CLI 创建

Web 界面创建

编辑里程碑

Web UI 中的里程碑日期编辑

里程碑列表与详情

查看已完成的里程碑

TUI 里程碑看板

任务分配到里程碑

1. 创建任务时指定

2. 编辑现有任务

3. 按里程碑 ID 过滤任务列表

4. 清除里程碑归属

5. Web 界面拖放分配

里程碑完成检测与归档

自动完成检测

归档里程碑

created_date 与 updated_date

移除里程碑（remove）

未分配任务池

在看板中按里程碑分组

results matching ""

No results matching ""