文档管理

Backlog.md 将项目文档作为一等公民管理。所有文档存储在 backlog/docs/ 目录下，以 Markdown 文件形式保存，支持嵌套子文件夹、全局 ID 索引和 CLI 全生命周期操作。

创建文档

# 最简创建
backlog doc create "API 设计指南"

# 指定文档类型
backlog doc create "架构决策说明" -t guide

# 创建到子目录
backlog doc create "部署手册" -p guides/deployment

创建成功后，CLI 会输出生成的文件路径，例如 backlog/docs/guides/deployment/doc-5 - 部署手册.md。文档 ID（如 doc-5）在整个 backlog/docs/ 树中全局唯一，无论文件位于哪个子文件夹，都可以通过该 ID 进行查看和更新。

doc create 也接受 --plain 标志。创建输出本身就是纯文本，该标志被接受（而非切换输出格式）是为了让按统一习惯给每条命令附加 --plain 的代理调用不会因 "unknown option" 而失败。

子路径规则

• 路径总是相对于 backlog/docs/ 目录，无需写绝对路径。
• 支持多级嵌套，例如 -p guides/deployment/aws。
• 不允许使用 .. 或绝对路径，系统会自动拒绝越级访问。

更新文档

# 更新文档内容
backlog doc update doc-5 --content "## 部署步骤\n\n1. 构建镜像\n2. 推送仓库"

# 同时更新标题、类型和标签
backlog doc update doc-5 --title "生产环境部署手册" -t runbook --tags deploy,aws

# 移动到新的子目录
backlog doc update doc-5 -p guides/production

backlog doc update 采用增量更新策略：只提供需要修改的字段，未提供的字段会保持原值不变。例如仅传入 --title 时，文档内容和路径均不受影响。

多行内容与追加

--content 支持 \n 换行转义，与任务的 --desc、--plan、--notes 行为一致：

backlog doc update doc-5 --content "## 概述\n\n第一段\n第二段"

如需在保留原有内容的前提下追加文档块，使用可重复的 --append-content 选项。追加的块与基础内容之间以空行分隔，可与 --content 组合（追加在替换内容之后）：

# 追加一段到现有文档末尾
backlog doc update doc-5 --append-content "## 附录\n\n补充说明"

# 先替换再追加
backlog doc update doc-5 --content "新内容" --append-content "附录部分"

MCP 的 document_update 工具对应提供 appendContent 参数。

列出文档

backlog doc list

在支持 TTY 的终端中，该命令会打开双栏交互浏览器：左栏列出 Documents (N)，右栏实时渲染选中文档的 Markdown 内容。← / → 切换左右栏焦点，↑ / ↓（或 j / k）在当前栏内导航或滚动，Enter 打开完整查看器，? 打开帮助弹窗，q 退出。活动栏的边框高亮为黄色，失去焦点后恢复。--plain、--json 以及非 TTY 环境仍输出列表文本，行为不变。

该命令扫描 backlog/docs/ 及其所有子目录，输出全部文档的 ID、标题、类型和所在路径。当文档数量较多时，可结合分页窗口与模糊查找：

# 分页窗口：只看前 20 条 / 翻下一页 / 只输出总数
backlog doc list --max-count 20
backlog doc list --max-count 20 --skip 20
backlog doc list --count

backlog search "部署"

分页选项（--max-count / --skip / --count）与 search、task list 等 8 个列表命令语义一致，集中说明见 搜索与序列 的「列表分页」一节。搜索范围同时覆盖任务、文档和决策记录（memo 与 Wiki 结果见 Web 全局搜索）。

查看文档

# 交互式查看（TUI 弹窗渲染 Markdown）
backlog doc view doc-5

# 纯文本输出（适合 AI 代理或脚本解析）
backlog doc view doc-5 --plain

--plain 标志会输出原始 Markdown 内容与 frontmatter 元数据，方便在流水线或聊天窗口中直接阅读。

引用形式与歧义处理

doc view 接受三种引用形式，按顺序尝试解析：

身份解析是 fail-closed 的：当同一 ID 出现在不同子目录（例如 guide/doc-1 - A.md 与 migration/doc-1 - B.md）时，裸 ID 会立即报错并列出全部候选路径（退出码 1），而不会任选一个。错误信息附带可直接运行的消歧建议——候选唯一时给出 目录/ID，否则给出完整路径（含空格时自动加引号）。路径形式拒绝 .. 越级与盘符前缀，匹配到多个文件同样报错。

相关行为：

• 文档或决策缺少 id frontmatter 时仍出现在列表中，但无法通过 ID 寻址
• Web 界面遇到歧义时显示专用提示（服务端返回 HTTP 409 与候选列表），不会回退到缓存中的旧条目
• MCP 返回 AMBIGUOUS_ID 错误并在结构化内容中给出候选路径

反向链接

文档页面（CLI doc view 的交互式浏览器右栏、Web 文档详情页）会展示反向链接列表，列出哪些任务、文档、决策或 Wiki 页面引用了当前文档：

• 索引在客户端构建（buildBacklinkIndex），随内容变更实时刷新，不回写任何文件
• 每条反向链接显示来源类型图标、标题与 ID，点击即在当前视图打开来源
• 多个 ID 同时命中的来源会以下拉选择器折叠展示，避免长列表淹没页面

反向链接是只读的导航辅助，不影响文档内容或依赖解析。

实况 SQL 查询块

文档（任务、文档、决策、备忘、Wiki 页通用）的正文中可嵌入 sqlite-query 与 duckdb-query 围栏代码块，Web 阅读视图会把块渲染为针对真实数据库文件的实况只读查询结果（编辑态仍显示源码原文）：

```sqlite-query
source: backlog/databases/shop.sqlite
view: table
sql: |
  SELECT product, price, stock
  FROM inventory
  ORDER BY price DESC
```

块字段（YAML 极小子集）：

结果默认最多返回 500 行，上限由 config.yml 的 query_max_rows 配置，超出即截断并在块内提示；块头可开启分页浏览，分页由引擎侧 LIMIT / OFFSET 下推，不受预览上限约束。块头提供四个动作：Refresh（按磁盘当前状态重跑）、Show / Hide Query（展开/收起只读的 source + SQL，默认收起）、Copy Markdown（把当前结果序列化为 GFM 表格复制到剪贴板）、Export CSV（服务端重跑并生成 CSV，浏览器保存到用户所选位置）。安全路径校验不通过或查询出错时，错误信息就地渲染在块内，不影响页面其余部分。

查询块还可以直接出图（view: echarts），或让独立图表用 fromQuery 引用它；流程图与数据图的完整用法见 图表块。

文档组织建议

随着项目演进，backlog/docs/ 下的文件会逐渐增多。推荐采用以下目录结构保持清晰：

backlog/docs/
├── readme.md              # 文档目录说明
├── api/
│   ├── doc-1 - REST-规范.md
│   └── doc-2 - GraphQL- schema.md
├── guides/
│   ├── doc-3 - 本地开发.md
│   └── doc-4 - 部署流程.md
└── runbooks/
    └── doc-5 - 故障排查.md

提示：backlog doc list 和 backlog doc view 会自动穿透所有子目录。文档 ID 全局唯一时只需记住 ID；若不同子目录出现同名 ID，可用 目录/ID（如 migration/doc-14）或标题 slug 消歧，歧义时命令会列出全部候选路径。