创建与编辑任务

创建任务

基础创建

执行以下命令，输入任务标题即可快速创建任务：

backlog task create "任务标题"

若当前终端支持交互式 TTY 且未提供标题，系统将自动启动创建向导，引导你填写任务详情。

backlog task create --help 与 backlog task edit --help 的输出末尾附有 Note 提示，指向 backlog instructions overview 工作流概览。项目期望每个会话从该概览开始——其中包含项目状态机指引与 AI 可读输出的 --plain 约定，直接查阅 --help 的新读者也能看到这条引导。

完整参数创建

通过命令行选项可在创建时一次性设置所有字段：

backlog task create "实现用户登录" \
  -d "支持邮箱和密码登录" \
  -a "@developer" \
  -s "To Do" \
  -l "feature" \
  --priority high \
  --ac "用户可以使用邮箱登录" \
  --ac "密码需要至少8位" \
  --plan "1. 设计数据库表 2. 实现API 3. 写测试" \
  --notes "参考现有认证模块" \
  --dep "back-1" \
  --ref "https://docs.example.com/auth" \
  --doc "doc-5"

常用选项说明

description 中的换行

--description 和 --desc 支持跨平台一致的换行输入：

# 在描述中插入换行
backlog task create "标题" --desc "第一行\n第二行"

# 编辑时同样支持
backlog task edit back-10 --desc "修复内容：\n1. 修复 A\n2. 修复 B"

• Windows 上输入 \n 即可得到换行（CLI 内部模拟 bash 双引号转义层后统一处理）
• 如需输入字面 \n 而非换行，Windows 需输入 \\\\n，非 Windows 输入 \\n
• 此转义仅处理 \n（换行）和 \\（字面反斜杠），其他序列如 \t 原样保留
• --plan、--notes、--final-summary 同样支持上述跨平台换行转义

避免 bash ANSI-C 引号：不要用 $'...' 包装多行值。bash 的 $'...' 会在 CLI 看到参数之前就把 \n 解析成真实换行，导致回显命令跨行断裂、CLI 只取到第一行。请改用普通双引号内的 \n 转义（--plan "第一步\n第二步"）。此规则同样适用于 --desc、--notes、--comment、--final-summary、--append-notes、--append-final-summary 等所有多行字段。

查看任务

交互式 TUI 查看

backlog task <id>

或显式使用 view 子命令：

backlog task view <id>

进入 TUI 后：

• 使用方向键或 j/k 浏览任务详情
• 按 E 在系统编辑器中打开任务文件（TUI 自动挂起，退出编辑器后恢复）
• 按 Escape 或 q 退出查看

纯文本输出

在非交互式环境（如脚本或 AI 会话）中，使用 --plain 输出结构化纯文本：

backlog task <id> --plain
backlog task view <id> --plain

稳定 JSON 输出

读取类命令支持 --json 输出结构化、版本化的 JSON，便于脚本解析：

backlog task list --json
backlog task view back-10 --json
backlog task back-10 --json
backlog search "api" --json
backlog doc list --json

输出使用统一信封 { schemaVersion: 1, kind: "..." }，字段与 --plain 保持一致，并包含 dueDate、plannedStart、plannedEnd、actualStart、actualEnd 等日期字段，以及验收标准进度 acceptanceCriteriaCompleted / acceptanceCriteriaCount（无验收标准的任务为 0/0）。任务列表、任务详情与搜索结果三类 JSON 使用同一套字段。--json 只写 stdout，错误写 stderr；与 --plain 互斥，同时指定会报错并返回非零。

JSON 摘要还包含以下字段：

• isReady：该任务的依赖就绪判定，与 --ready 过滤使用同一份投影结果，两者不会互相矛盾；task view --json 额外给出 readiness 块（isReady / isBlocked / blockingDependencies / missingDependencies）
• references / modifiedFiles：任务的引用与修改文件列表（无值时为空数组），列表、搜索与详情三类载荷一致携带
• source：默认读取为 null；当通过 --completed 扩大语料时，来自 completed 目录的行标记为 "completed"

持续监视（--json --watch）

task list --json --watch 进入监视模式：监听任务目录变更，每次变化输出一份与一次性 --json 逐字节一致的完整 JSON 替换帧，内容未变化时不重复输出：

# 配合 jq 持续观察某负责人的待办队列
backlog task list -a "@alice" -s "To Do" --json --watch | jq --unbuffered '.tasks | length'

• 选项、筛选、排序在每次读取时重新求值，与一次性命令不会漂移
• 通过 SIGINT / SIGTERM 或有界关闭退出；适用于脚本订阅与仪表盘管道
• 启动方退出即停：当驱动 watch 输出的上游程序（如某个脚本或 IDE 插件）在未停止 watch 的情况下退出时，watcher 会检测到启动方进程消失并自行结束，不会在安静仓库中沦为无限运行的孤儿进程
• 空转低 CPU：无事发生时，每秒的 reconcile tick 只做一次廉价的文件 stat 签名比较（条目名 + size + mtime + ctime，仅一层深），签名不变就不重新读取；大仓库空转 CPU 占用从约 35% 降到 1% 以下，输出字节与更新延迟不变

编辑任务

基础编辑

backlog task edit <id> --title "新标题" --status "In Progress"

若未提供任何编辑字段，且终端支持交互式 TTY，系统将启动编辑向导。

多 ID 批量编辑

task edit 接受多个任务 ID，用于批量应用共享类标志：

# 将多个任务一次性移动到同一状态
backlog task edit back-1 back-2 back-3 -s "In Progress"

# 批量追加标签
backlog task edit back-1 back-2 --add-label sprint-3

规则：

• 可批量应用的标志：-s/--status、-a/--assignee、-l/--label、--add-label、--remove-label、--priority、-m/--milestone、--clear-milestone、--add-doc、--add-ref 等共享字段
• 逐任务字段（--title、--desc、--plan、--notes、--comment、--ordinal、AC/DoD 项、日期清除等）在多 ID 调用中会被拒绝
• 单个任务失败不中断整批，命令结束时汇总报告每个失败
• 多 ID 调用若未携带任何可批量应用的标志，会报错而不是打开编辑向导

对应地，服务端提供 POST /api/tasks/move 批量移动接口，Web 看板的多选拖拽即通过它一次提交（见 看板视图 的多选小节）。

常用编辑选项

验收标准操作示例

# 添加新的验收标准
backlog task edit back-10 --ac "新的验收项"

# 删除第 2 条验收标准
backlog task edit back-10 --remove-ac 2

# 勾选第 1 条验收标准
backlog task edit back-10 --check-ac 1

# 取消勾选
backlog task edit back-10 --uncheck-ac 1

# 原子清空全部验收标准（再重新添加，即 clear-then-add 工作流）
backlog task edit back-10 --clear-ac --ac "全新的验收标准"

--clear-ac 用于一次性清空全部验收标准，且会拒绝与其它 AC 变更选项（--ac、--remove-ac 等）以外的组合冲突。AC 与 DoD 的编辑与序列化是确定性的，重复编辑不会产生冗余或错乱的清单结构。

实现计划追加示例

# 在现有计划后追加内容
backlog task edit back-10 --append-plan "补充集成测试用例"

# 先替换计划，再追加多条
backlog task edit back-10 --plan "新计划" --append-plan "第一步" --append-plan "第二步"

每次追加会以一个空行与已有内容分隔；多个 --append-plan 按命令行顺序依次应用。纯空白值会被忽略。当实现计划章节不存在时，第一次非空追加会自动创建该章节。

备注与总结操作示例

# 追加备注
backlog task edit back-10 --append-notes "新的备注内容"

# 设置最终总结
backlog task edit back-10 --final-summary "任务已完成，实现了..."

# 追加到最终总结
backlog task edit back-10 --append-final-summary "补充说明"

# 清除最终总结
backlog task edit back-10 --clear-final-summary

评论操作示例

# 追加一条评论
backlog task edit back-10 --comment "建议将 UI 部分拆分到独立 PR"

# 追加评论并指定作者
backlog task edit back-10 --comment "建议将 UI 部分拆分到独立 PR" --comment-author @sara

# 同时追加多条评论
backlog task edit back-10 --comment "第一条评论" --comment "第二条评论"

评论正文支持 Markdown，但单独的 --- 行被保留为评论分隔符，不能出现在评论正文中。评论会显示在任务详情的 Comments 区域，按追加顺序排列，包含序号、作者（如有）和时间戳。

评论与实现备注、最终总结的区别：

列表型字段：设置 / 追加 / 移除 / 清空

--ref、--doc、--dep 一类列表字段支持四种语义，同一次命令中互斥：

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

# 追加一个依赖，已有依赖保持不变
backlog task edit back-10 --add-dep back-5

# 按值移除某个依赖
backlog task edit back-10 --remove-dep back-4

# 清空全部依赖
backlog task edit back-10 --clear-deps

规则：

• 设置与追加不可混用（--ref 与 --add-ref 互斥），清空也不可与同类设置/追加/移除混用；违规时命令失败且任务文件保持不变
• 移除标志可重复出现或逗号分隔，空值会被拒绝
• 空值设置会被拒绝：backlog task edit back-10 --dep "" 报错并提示改用 --clear-deps（旧版本会静默无操作却退出 0，属于假成功）
• MCP task_edit 语义一致：数组中出现空字符串元素会被拒绝，只有显式空数组 [] 才表示清空

引用条目的三种形态

--ref / --add-ref 的每个条目是一个位置，支持三种形态：

• 一个条目只承载一个位置；要引用同一份文件的两个区域，请写两个条目
• --remove-ref 按存储的完整字符串匹配，行号后缀也需一并给出
• Web 界面中点击带行号后缀的链接会在预览框中按指定行范围展示内容

评论删除

# 删除第 2 条评论
backlog task edit back-10 --remove-comment 2

# 一次删除多条（列表编辑类标志均支持逗号分隔）
backlog task edit back-10 --remove-comment 2,3

# 清空全部评论
backlog task edit back-10 --clear-comments

--remove-comment 接受 1-based 序号，越界时报错并提示可用序号；--clear-comments 不能与 --comment 同时使用。删除后剩余评论按位置重新编号（序号本身不持久化）。CLI、MCP task_edit、Web UI 评论区的逐条删除按钮与「Clear comments」按钮行为一致。

并发编辑保护

任务的"读取—修改—写入"由文件锁保护，避免两个进程同时编辑同一任务时静默丢失其中一次修改。争用时会立即失败：

Edit failed: back-10 is being modified by another process; retry if appropriate.

采用 fail-fast：不等待、不合并、不自动重试，失败方需自行重试。锁基于任务文件本身，跨独立的 backlog 进程生效，而不是只在单个进程内有效。锁也会覆盖草稿降级路径。

任务列表与筛选

# 列出所有任务
backlog task list

# 按状态筛选
backlog task list -s "In Progress"

# 多状态筛选（重复或逗号分隔）
backlog task list -s "To Do" -s "In Progress"

# 排除某状态
backlog task list --exclude-status "Done"

# 只看未指派任务（与 --assignee 互斥）
backlog task list --unassigned

# 按负责人筛选
backlog task list -a "@developer"

# 按里程碑筛选
backlog task list -m "M1 - CLI"

# 按优先级筛选
backlog task list --priority high

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

# 按字段排序（priority 或 id）
backlog task list --sort priority

# 只列出依赖已就绪、可以立即开始的任务
backlog task list --ready

# 扩大语料：同时列出 completed 目录中的历史任务
backlog task list --completed

# 纯文本输出
backlog task list --plain

--completed将读取范围从活跃任务扩大到 backlog/completed/ 语料，JSON 行以 source: "completed" 标记；backlog search --completed 与 MCP list_tasks / search_tasks 的 completed: true 参数语义一致。注意：MCP task_search 现在默认只搜索活跃任务，需显式传 completed: true 才会包含历史任务。

纯文本列表行在任务含验收标准时附带 (ac: 已勾选/总数) 后缀，MCP 纯文本列表同样输出；无验收标准的任务不显示该后缀。

列表分页

task list 与 search、draft list、milestone list、doc list、doc search、decision list、memo list 统一支持 grep 风格的分页窗口选项：

窗口在过滤、排序、--limit 之后按输出顺序应用，连续翻页不重叠不遗漏；被截断的文本输出以 Showing <first>-<last> of <total> items. Next: backlog task list --skip <n> 结尾，照抄命令即可翻页。--count 只输出数字且不能与 --json 组合（返回非零退出）；JSON 信封仅在窗口截断时附加 total / nextSkip 字段，未截断时逐字节不变。分页语义的集中说明见 搜索与序列 的「列表分页」一节。

依赖就绪过滤（--ready）

backlog task list --ready 只保留可以立即开工的任务：

• 判定采用 fail-closed：依赖中只要存在未完成或无法解析的条目，该任务即视为被阻塞
• 已完成的任务无论其状态字符串是什么，都算作"已完成证据"（以完成语料库中的位置为准）
• 依赖身份按规范化 ID 匹配（前缀与零填充差异不影响判定）
• 循环依赖与歧义依赖数据会被如实标记为阻塞，不会猜测
• 相同判定同时出现在 CLI（--ready，plain/json/交互式三种输出）、TUI 任务详情面板的 Readiness 行、Web 任务详情 Dependencies 卡片的状态徽章，以及 MCP task_list 的 ready: true 参数
• 该过滤只做标记与筛选，不修改任何任务，也不改变 ordinal 排序的权威性

完成任务与归档

完成任务的第一步是将其状态修改为终端状态（通常为 Done）：

backlog task edit <id> --status "Done"

状态到达终端后，若想把任务从活跃看板中清出，可执行 complete 子命令，把任务文件移入 backlog/completed/ 目录：

backlog task complete <id>

task complete 是清理操作：任务必须处于终端状态，否则命令报错并提示先用 backlog task edit <id> -s "<终端状态>" 完成状态推进；成功后任务从活跃看板消失，文件移入 completed 目录，输出 Completed task <id>. 与新文件路径。MCP 侧对应工具为 task_complete（参数 id），语义相同，且不允许完成其他分支的任务。

归档任务会将文件移入 backlog/archive/tasks/ 目录，属于软删除，原 ID 可被后续新任务复用：

backlog task archive <id>

若希望将已完成的任务从活跃列表中移除，可定期执行清理命令：

backlog cleanup

日期字段

创建或编辑任务时，可通过以下选项管理日期字段：

# 计划字段（date-only）
backlog task create "API 文档" --due-date 2026-06-01 --planned-start 2026-05-25 --planned-end 2026-05-30

# 实际字段（datetime）
backlog task create "紧急修复" --status "In Progress" --actual-start "2026-05-29 10:00"
backlog task edit back-10 --actual-end "2026-05-30 18:00" --clear-actual-start

• 计划字段格式为 YYYY-MM-DD（date-only）
• 实际字段格式为 YYYY-MM-DD HH:MM（UTC datetime）
• 在交互式 TTY 环境下，创建/编辑向导会提示输入日期

Web UI 中的日期编辑

在任务详情弹窗的侧边栏中：

• Due Date / Planned Start / Planned End — date 输入框
• Actual Start / Actual End — datetime-local 输入框（支持 UTC ↔ 本地时区转换）

自动填充规则：当设置 Due Date 且 Planned Start 为空时，系统会自动填充 Planned Start 为当前日期、Planned End 为 Due Date 的值。你可在保存前修改这些自动填充值。

实际时间自动填充：当在 Web UI 中将任务状态变更为 In Progress 或 Done 时，系统会自动填充对应的 actual 字段（若为空）。

日期清除：点击任意日期输入框的 Clear 按钮后，保存任务即可从文件中移除对应日期字段。清除操作通过空字符串传递，确保服务端正确接收删除指令。

Web UI 创建任务

在 Web UI 中点击看板或任务列表的「新建任务」按钮打开创建模态框：

• References / Documentation：创建模式下即可通过路径自动补全添加引用链接或关联文档；输入 .back 可发现 .backlog 目录
• 保存后 references 和 documentation 会写入任务文件

降级为草稿

若发现某个任务尚需完善、暂时无法执行，可将其降级为草稿：

backlog task demote <id>

降级后任务将移入 backlog/drafts/ 目录，并获得独立的草稿 ID（如 draft-3）。其他任务对原 ID 的引用会被自动清理（见 归档与清理）。

Web 界面的降级操作带有防误触保护：降级进行中所有编辑、状态变更与快捷键都被锁定，网络错误时会明确提示"降级可能已成功"并刷新视图供你核对，避免重复提交。

标签输入（Web UI）

在 Web UI 的任务详情弹窗中编辑标签时，标签输入框支持智能自动完成：

• 下拉提示：点击标签输入框或开始输入时，会显示项目中所有已有标签的下拉列表（包含配置标签和所有任务中的标签）
• 模糊搜索：输入时按字符顺序模糊匹配，如输入 we 可匹配 web-ui
• 键盘选择：使用 ↑ / ↓ 箭头高亮选项，按 Enter 选中；按 Escape 关闭下拉框
• 创建新标签：输入内容不匹配任何现有标签时，按 Enter 或输入逗号 , 即可创建新标签
• 重复检测：如果尝试添加与已有标签仅大小写不同的重复项（如已有 feature 时输入 Feature），输入框边框会变红提示，且下拉框显示 feature already added

在编辑器中打开任务

TUI 中编辑

在 backlog task <id> 或 backlog board 的 TUI 界面中：

• 选中目标任务
• 按 E（或 Shift+e）直接在系统编辑器中打开任务文件
• 编辑器关闭后 TUI 自动恢复，并重新加载最新内容

手动编辑

任务文件即为普通 Markdown，可直接使用任何编辑器修改：

vim backlog/tasks/back-10.md

手动编辑后，Backlog.md 的文件监视器会自动刷新索引，无需重启服务。