配置管理

Backlog.md 提供灵活的配置系统，支持通过交互式向导或命令行直接管理项目设置。配置存储在 YAML 文件中，与项目代码一起纳入版本控制，确保团队成员使用一致的工作流规范。

交互式配置向导

backlog config 命令启动高级配置向导，以交互式问答形式引导你完成所有关键设置：

backlog config

向导涵盖以下配置环节：

• Shell 补全安装
• 跨分支任务状态检查
• Git 钩子绕过设置
• 自动提交启用
• ID 零填充格式化
• 默认编辑器选择
• 定义完成（DoD）默认项管理
• Web UI 端口与浏览器自动打开

按提示逐步回答即可，每个选项都有默认值和说明提示。配置完成后，Backlog.md 会自动将设置写入项目配置文件。

命令行直接操作

对于需要快速修改单个配置项的场景，使用 backlog config get 和 backlog config set 命令。

查看当前配置

列出所有已配置项及其当前值：

backlog config list

# 纯文本输出（AI 可读输出的统一约定；输出与不带该标志时逐字节一致）
backlog config list --plain

--plain 被 overview 指引列为读取实时配置的标准方式：输出本就是纯文本，该标志被接受是为了让按统一习惯附加 --plain 的代理调用不会因 "unknown option" 而失败。

config list 在 statuses 行之后还会打印一行派生的终态集合，例如 terminalStatuses: [Done, Dropped] (derived from statuses)。终态由状态机中各列的 category（done / dropped）派生，只是只读呈现，不是可设置的配置键——要调整终态请在状态机编辑器中修改对应状态的 category。

查看单个配置项：

backlog config get projectName
backlog config get statuses
backlog config get defaultPort

修改配置项

设置单个配置项的值：

backlog config set projectName "我的项目"
backlog config set defaultPort 8080
backlog config set autoCommit true

设置列表类型的配置项：

backlog config set statuses "To Do,In Progress,Done"
backlog config set labels "bug,feature,docs"

config get/set/list 通过共享的可用键列表展示一致的配置项。对于列表型配置（statuses、labels），推荐使用 backlog config get <key> 查看当前值后直接编辑 config.yml 的对应字段（支持块状 YAML 序列），而非通过 config set 覆盖。

关键配置项说明

项目基础信息

状态列表的顺序决定了看板中的列排列顺序。第一个状态视为任务的初始状态；终态由状态的 category 决定（done / dropped），不再简单等同于列表末位。

状态机配置

statuses 采用对象形式描述状态机，每个状态是一个对象：

statuses:
  - name: To Do
    category: active
    next:
      - to: Planning
        when: 描述与验收标准完整，可以开工
        ai: allowed
  - name: Done
    category: done
    exit: complete
    next: []
  - name: Dropped
    category: dropped
    exit: archive
    display: false
    next: []

旧式字符串数组写法仍然兼容（末位为终态）。没有 CLI 命令设置 statuses：推荐在 Web 设置页的状态机编辑器中可视化维护，或直接编辑本文件——整体写回、不丢字段。backlog instructions overview（及 MCP 同名 overview 资源）会自动渲染当前状态机的完整可读描述。首次 backlog init 直接写入内置的七列默认状态机（To Do / Planning / Plan Review / In Progress / In Review / Done / Dropped，随界面语言本地化）。语义细节见任务生命周期。

任务默认值

# 设置默认负责人（列表，逗号分隔）
backlog config set defaultAssignee "@alice,@bob"

# 取消默认负责人（空值会移除该键）
backlog config set defaultAssignee ""

# 清除默认编辑器——服务默认的 "code --wait" 会挂住无人值守的代理进程
backlog config set defaultEditor ""
backlog init --default-editor ""

defaultAssignee 的生效规则是一条三态语义：

• 不传 -a（字段缺省）→ 应用配置中的默认负责人
• 显式传 -a（哪怕只有一个）→ 完全替换默认值，不与默认值合并
• 显式取消 --unassign（或 Web UI 中清空负责人 chips）→ 保存为空列表，不回落默认值

默认值在 core 的创建漏斗层应用，因此 CLI task create、draft create、创建向导、TUI N 键创建器、Web 端 POST /api/tasks 与 MCP task_create 行为一致。

defaultEditor 设为空字符串即表示"不使用默认编辑器"：config set defaultEditor "" 跳过可执行文件校验并移除该键，init --default-editor "" 同样清除既有配置。非空值仍会校验可执行文件是否存在。

编辑器解析优先级与 Vim / Neovim 配置

按 E 打开编辑器时，解析优先级为（doc-002）：EDITOR 环境变量 > config.yml 的 defaultEditor > 平台默认（macOS/Linux 为 nano，Windows 为 notepad）。使用 Vim / Neovim 推荐直接设环境变量：

export EDITOR=nvim          # 或 vim
# 也可以写入项目配置
backlog config set defaultEditor nvim

• 在 TUI（backlog board / backlog task <id>）中按 E 时，界面会挂起字符屏幕、退出备用缓冲区，编辑器退出后自动恢复终端状态
• 排查：颜色异常时设 TERM=xterm-256color；编辑器无响应或立即退出多见于编辑器路径含参数——请写完整可执行路径或用包装脚本
• 可针对单条命令覆盖：EDITOR=nvim backlog board

分支与 Git 集成

启用 checkActiveBranches 后，Backlog.md 会在加载任务时检查其他本地和远程分支，确保跨分支的任务状态准确。这在大型仓库中可能影响性能，可通过减小 activeBranchDays 来加速。

includeCrossBranch（对应 config.yml 的 include_cross_branch）控制展示：开启后看板、任务列表与搜索会纳入只存在于其他分支的任务；未设置时保持本地优先（历史 CLI 行为）。它与 checkActiveBranches 是两个独立轴——后者管"是否扫描"（并决定任务 ID 分配的候选分支集），前者管"扫描结果是否展示"。关闭扫描会同时收窄 ID 分配候选集，请配合 activeBranchDays 理解代价。两个开关都可以在 Web 设置页的 Advanced Settings 卡片中找到，保存后立即生效无需重启。

remoteOperations 依赖于 checkActiveBranches，当后者关闭时，前者自动失效。

自动化行为

onStatusChange 命令经 sh -c 在项目根目录执行，任务信息通过环境变量注入：$TASK_ID（任务 ID）、$OLD_STATUS（旧状态）、$NEW_STATUS（新状态）、$TASK_TITLE（标题），在命令字符串中以 $TASK_ID 等形式引用。回调失败只打印错误日志，不会阻塞状态变更。单个任务 frontmatter 中的 onStatusChange 字段优先于全局配置。此键不在 config get/set 的可用键列表中，请直接编辑 config.yml 设置。

启用 autoCommit 后，每次通过 CLI 创建或修改任务，Backlog.md 会自动执行 git commit，省去手动提交的步骤。配合 bypassGitHooks 可在 pre-commit 钩子耗时较长时提升效率。

autoCommit 只提交每次写入实际触碰的文件（新建文件、被替换的旧路径、移动/归档的源路径与目标路径），不会对整个 backlog/ 目录执行 git add，也不会清空你已有的 staged/unstaged 改动。这保证了自动提交与用户当前工作区的其他变更互不干扰。

filesystemOnly 适用于纯文件系统项目或无 Git 的环境，开启后所有 Git 相关功能均被禁用。

ID 与前缀

前缀配置允许自定义任务和草稿的 ID 格式。例如，将 prefixes.task 设为 back 后，新任务的 ID 将变为 back-1、back-2 等。

保留前缀：任务前缀只允许字母，且不能使用保留名称 doc 与 decision（它们分别被文档与决策占用）。该规则在所有入口一致生效——init 的 --task-prefix 标志、交互向导、浏览器初始化页都会拒绝；backlog doctor 会报告存量项目的前缀冲突，且冲突未解除时拒绝执行 --fix（避免修复重复 ID 时把新编号分配进冲突的存储）。已使用保留前缀的存量项目仍可正常工作，重新初始化不会主动改写它。

zeroPaddedIds 控制 ID 的格式化宽度。设为 3 时，ID 显示为 task-001；设为 4 时，显示为 task-0001。这有助于保持文件名的字典序一致性。

Web UI

修改 defaultPort 可避免与其他本地服务端口冲突。开启 autoPort（默认）时，若默认端口已被占用，服务器会自动改用后续可用端口并在终端打印实际地址；系统只接受用户端口范围（1024–65535）内由自己扫描出的端口，拒绝操作系统分配的随机高位端口。关闭 autoPort 后，端口占用会恢复为直接报 EADDRINUSE 错误。也可在 Web 界面「设置」面板中切换该开关。关闭 autoOpenBrowser 后，运行 backlog browser 只会启动服务器，不会弹出浏览器窗口，适合远程开发或服务器环境。

hideEmptyColumns（对应 config.yml 的 hide_empty_columns）开启后，看板会隐藏当前没有任何任务的状态列，减少视觉杂乱；拖拽期间所有状态列保持可见以便放置。也可在 Web 界面「设置」面板的 Auto Open Browser 开关旁切换。

MCP HTTP 传输

mcp.http.* 系列键（mcp.http.host / mcp.http.port / mcp.http.auth.*）目前只是预留配置：当前版本 MCP 仅实现 stdio 传输（backlog mcp start），不监听任何网络端口，也没有 HTTP 传输的消费逻辑。配置这些键不会产生任何效果，请保持 stdio 方式接入，详见MCP 工作流。

配置存储位置

Backlog.md 按以下优先级查找配置文件：

1. backlog/config.yml
2. backlog.config.yml（项目根目录）

推荐使用 backlog/config.yml，这样配置与任务、文档等项目数据集中存放，便于备份和迁移。当使用 backlog.config.yml 时，可通过 backlogDirectory 项指定 backlog 文件夹的相对路径（如 .backlog）。

自定义 backlog 目录全面生效：memo 存储与图谱扫描/监听此前把目录名硬编码为 backlog，在 .backlog 等自定义目录项目下会读写/监听错误路径、图谱为空；现已统一解析配置目录。若你此前在自定义目录项目中使用过 memo，旧数据仍在你的 backlog-dir/memos 下、现在能被正确识别；若根下误建了空的 backlog/memos 可手动删除。重跑 backlog init 也会补建缺失的 memos/、docs/ 等目录。

配置文件的 YAML 格式示例：

projectName: "我的项目"
statuses:
  - Backlog
  - To Do
  - In Progress
  - Done
labels:
  - bug
  - feature
  - docs
dateFormat: "YYYY-MM-DD"
checkActiveBranches: true
include_cross_branch: false
remoteOperations: true
activeBranchDays: 30
autoCommit: false
bypassGitHooks: false
prefixes:
  task: "back"
  draft: "draft"
defaultAssignee:
  - "@alice"
defaultEditor: "vim"
defaultPort: 6420
autoPort: true
autoOpenBrowser: true
hide_empty_columns: false

块状 YAML 列表：列表型配置（statuses、labels）既支持上面的块状序列写法，也支持内联写法（statuses: ["To Do", "In Progress", "Done"]）。系统会优先按标准 YAML 语义解析块状列表，同时兼容旧版内联括号格式。

修改配置文件后，Backlog.md 会自动加载最新设置，无需重启服务。