TUI 看板

在终端中运行 backlog board，即可启动基于字符界面的交互式看板。看板按状态分栏展示所有任务，支持键盘导航、任务移动、实时筛选和文件监控，无需离开终端即可掌握项目全貌。

启动看板

backlog board

首次启动时，看板会自动加载项目配置中的状态列，并将任务按状态归入对应列。旧式字符串配置默认 To Do、In Progress、Done 三列；新初始化的项目使用内置的七列默认状态机（见任务生命周期）。状态机中 display: false 的状态列会与列内任务一起隐藏。如果启用了里程碑模式，任务会按里程碑分组展示。

常用启动选项

# 垂直布局（状态列纵向堆叠，适合窄屏终端）
backlog board --vertical

# 显式指定布局方向
backlog board --layout vertical
backlog board --layout horizontal

# 里程碑分组模式（按里程碑泳道展示任务）
backlog board --milestones

键盘导航

看板启动后，使用以下按键进行操作：

提示：按 E 编辑任务时，TUI 会自动挂起并恢复，无需手动重启看板。

按 E 时系统按该行的实际文件位置决定打开任务还是草稿：草稿目录中的行打开草稿文件、任务目录中的行打开任务文件——即使文件的 status 字段与所在目录不一致（如降级后状态未改写）也不会开错对象；提示文案中的名词（任务 / 草稿）与实际编辑对象一致。

vim 按键族与边界行为

列表组件同时支持方向键与 vim 按键族（h/j/k/l），两套按键的边界语义是统一的：

• 到达列表首/尾后，按键行为由所在面板决定：可以停在边界、翻页，或跳转到相邻面板——而不是无声无息地失效
• 该规则同样适用于筛选弹窗等复合列表，弹窗内也能用 vim 键导航
• 无需开启配置：vim 键默认可用，与方向键并存

在看板中创建任务

按 N 键可直接在看板中打开任务创建器，无需退出 TUI 或切换到 Web 界面：

• 字段：Title、Description、Status（包含 Draft 和工作流状态）、Priority，以及五个日期字段——Due、Planned from/to、Actual from/to；日期格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm，非法日期会被拒绝并聚焦回出错字段
• 使用方向键在字段间移动，Tab / Shift+Tab 切换字段
• 创建非 Draft 任务后，任务会立即插入看板并被聚焦
• 创建 Draft 任务后，系统会提示该草稿不会在看板中显示
• 空看板也保持可打开，创建器始终可用

创建器的交互细节

• 鼠标支持：直接点击 Title / Description / Status / Priority 字段即可聚焦或打开选择器
• 极端终端尺寸：弹窗高度与宽度按实际屏幕自适应，最低约 8 行的终端中输入框仍可编辑；宽度按配置的状态/优先级文案长度动态计算，超长状态名会自动切换为紧凑堆叠布局
• Unicode 安全输入：在 astral 字符（如某些生僻汉字）旁插入、删除文字不会造成乱码或光标错位，宽字符按两个显示单元处理（emoji 同样按双宽测量）

草稿会话

backlog draft list 的交互界面是一个以草稿为语料的看板会话：

• 按 N 打开的创建器状态固定为 Draft，标题显示为「Create Draft」，字段与任务创建器完全相同（含日期）
• 会话实时监听 backlog/drafts/ 目录：外部编辑、删除草稿即时反映；草稿被提升为任务后自动从会话中消失
• 任务看板会话始终不显示草稿文件

看板移动模式

移动模式允许你直接在终端中变更任务状态：

1. 在看板中用方向键选中要移动的任务。
2. 按 M 进入移动模式，当前任务会被标记为待移动状态。
3. 使用 ← → 选择目标状态列，用 ↑ ↓ 调整插入位置。
4. 再次按 M 或 Enter 确认移动，任务状态即刻更新并同步到 Markdown 文件。
5. 按 Esc 可取消移动并恢复原位。

注意：来自其他分支的跨分支任务无法在看板中直接移动，系统会在底部状态栏提示原因。

多选移动（Shift + 方向键）

移动模式支持一次移动多个任务：

1. 按 M 进入移动模式后，用 Shift+↑ / Shift+↓ 在目标列中移动高亮条（不影响看板顺序）。
2. 按 M（或 Shift+M）将高亮任务招募进移动集合；不支持 Shift 方向键的终端可用此键招募邻近任务。
3. 招募后第一个普通方向键收起高亮，预览整组任务作为一个相邻块落位；确认后一次性写入。
4. 写入期间方向键与取消键冻结；落在原位的移动是无操作。逐任务失败会在底部状态栏报告。

跨分支任务不能被招募。确认采用防抖设计，重复按 Enter 不会重复提交。

任务列表与筛选

按 Tab 键可从看板切换至任务列表视图。列表视图支持更精细的筛选：

• 状态筛选：只显示特定状态的任务。
• 负责人筛选：按 @用户名 过滤。
• 标签筛选：按标签多选过滤。
• 里程碑筛选：只显示归属某一里程碑的任务。
• 优先级筛选：高 / 中 / 低。
• 搜索框：实时模糊匹配任务标题与描述。

在列表视图底部，按对应快捷键打开筛选面板，勾选条件后列表会即时刷新。筛选条件在看板视图与列表视图之间共享，返回看板后仍保持生效。

紧凑视图

当终端高度有限时，列表视图会自动切换为紧凑模式，隐藏部分元数据，仅保留任务 ID、标题和状态，确保在小型终端窗口中也能浏览大量任务。

里程碑看板视图

backlog milestones 提供侧栏 + 嵌入式看板的双栏布局：

• 左侧栏列出「未分配」桶与全部里程碑（含已完成标记），↑ / ↓ 移动光标，Space 将看板限定到该里程碑（行首显示 ▶），Enter 打开里程碑详情弹窗（纯元数据，无任务列表）
• 右侧为完整看板，键盘在看板与侧栏之间按焦点路由；筛选栏末尾显示 <当前显示>/<任务总数>
• N 在侧栏创建里程碑、在看板创建任务（默认归属当前限定的里程碑）；里程碑弹窗中按 E 打开编辑表单（标题、描述、Due、Planned / Actual 起止，日期格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm；标题创建后只读）
• 里程碑与任务变更都会实时同步：外部编辑里程碑后弹窗原地刷新，被归档 / 删除的里程碑弹窗会带提示关闭

非 TTY 环境下，backlog milestones list --plain 输出与 backlog board -m 一致的 Markdown 分组看板（先「No Milestone」，再按里程碑文件顺序分节，节内按状态分组），--show-completed 可纳入已完成任务。

实时文件监控

TUI 看板底层使用文件系统监控（Bun.watch），当以下情况发生时，看板会自动刷新：

• 在 Web UI 或其他终端中修改了任务状态
• 通过 backlog task edit 命令更新了任务
• AI 代理通过 MCP 工具修改了任务文件

这意味着你可以同时打开 TUI 看板和 Web 界面，任意一侧的改动都会实时同步到另一侧。

实时刷新对原子写入（atomic writes）具有弹性：CLI 写入任务文件时可能触发短暂的部分内容事件，TUI 会等待文件稳定后再刷新，避免读取到不完整的任务内容。选中任务在刷新、移动、归档或删除后仍保持有效，删除后会自动选中相邻任务。

已打开弹窗的同步：看板任务弹窗与里程碑弹窗同样是"活"的——外部修改内容时按内容签名比对后原地重渲染，记录被移出当前视图时弹窗带提示关闭；无变化的刷新（如自己在弹窗内保存产生的回声）不会引起闪烁或重建。

验收标准进度指示

状态为 In Progress 且包含验收标准（AC）的任务，看板行会显示 ASCII 进度条，如 [#####-----] 5/10：

• 使用 #（已完成）与 -（未完成）纯 ASCII 字符，任何终端字体都能正确渲染
• 列宽足够时显示 10 格条，紧凑列显示 5 格条（宽度阈值 40 列）
• 颜色按完成度：全部完成绿色、不足三分之一红色、其余黄色；只要有勾选就至少显示一格
• 从验收标准实时派生，不持久化；没有 AC 或非 In Progress 的任务不显示
• 任务详情面板不再显示进度条，只保留 checklist 本身——看板行是唯一的进度面

帮助弹窗

按 ? 打开帮助弹窗：弹窗高度随终端尺寸自适应（从不超出屏幕），调整终端大小时实时重排；滚动上限按实际渲染行数计算，窄终端中换行的说明文字也能滚到底。任务详情弹窗的背景遮罩同样随终端尺寸变化实时重排，缩放终端后不会残留错位区域。

主题自适应与稳定切换

TUI 看板采用终端主题自适应渲染，避免硬编码 ANSI 颜色带来的可读性问题：

• 大多数控件边框使用终端默认色，跟随当前配色方案
• 保留看板移动态的青色高亮，作为当前待移动任务的可识别标记
• 长列表和滚动区支持 PageUp / PageDown / Home / End 快速定位，并显示滚动条指示器

Tab 键在看板与任务列表之间切换经过稳定性处理，切换前后不会丢失 stdin 输入或积累重复监听器，双向切换均可靠。

依赖就绪提示

任务详情面板会为含有依赖的任务显示一行 Readiness 判定：

• ✓ Ready to start — 依赖全部就绪，可以立即开工
• ● Blocked by <ID> — 至少有一个依赖尚未完成或无法解析

判定采用 fail-closed：依赖数据不完整、循环或存在歧义时一律按"阻塞"处理，不会猜测。同一判定也出现在 Web 任务详情的 Dependencies 卡片、Web 任务详情的状态徽章、backlog task list --ready 以及 MCP task_list 的 ready: true 参数中。该提示只做展示与筛选，不会修改任务或改变排序。

隐藏空状态列

看板可以隐藏当前没有任何任务的状态列，减少视觉杂乱：

• 使用共享配置键 hide_empty_columns（与 Web 界面同一开关）
• 在看板内切换时界面立即反映（乐观更新），写入异步落盘
• 退出 TUI 时会等待挂起的写入完成，避免配置丢失
• 拖拽/移动任务期间所有状态列保持可见，以便作为有效的放置目标

窗口标题

进入 TUI 时，终端窗口标题会更新为包含项目名的标题；退出时恢复原标题。标题的压入/弹出严格配对，在 tmux 等嵌套终端中也能通过透传序列正确恢复。

按键提示约定

底部 footer 与帮助面板中的按键提示统一使用大写字母表示可按键（如 N 新建、E 编辑、M 移动），避免大小写混用造成误解；footer 文案集中为常量，防止不同视图之间出现措辞漂移。

非终端环境的纯文本回退

当 backlog board 运行在非 TTY 环境（如 CI 流水线、脚本管道、IDE 集成终端）时，它会自动回退为纯文本输出，打印结构化的 Markdown 看板表格，而非启动交互式界面：

# 在 CI 中查看看板状态
backlog board > board-status.md

纯文本输出包含项目名、时间戳、各状态列的任务清单以及负责人和标签等元数据，便于存档和邮件分享。

同时运行多个视图

backlog board 与 backlog browser 可以并行运行。终端看板适合专注编码时快速查看状态，Web 界面适合详细编辑和拖拽操作，两者数据完全互通。