Workbench Navigation

Workbench Navigation — Workspace 与终端工作现场

Status: Accepted product requirement / implementation pending · Owner: Haisu · 2026-10-06。

来源：Haisu 在 2026-10-06 PM 讨论中要求统一管理 workspace → project → worktree → terminal/agent；纠正左下为 agent session 状态管理、右侧为 terminal tabs 与原生 CLI TUI；明确确认每 worktree 保留自己的 tabs/layout、切换恢复现场、点击 agent 跳到已有 worktree → tab → pane，并同意按此方案补 GitHub issues。本文扩展 First-Usable-Version 的交互要求，细化 Product-Model 的 UI 投影；不改变 Resident/Task/Execution/Grant 的领域边界。

1. 管理模型与界面

Workspace（项目组合/工作语境；顶部选择）
  Project（首版导航以 repo 节点呈现）
    Worktree（一个 checkout 的终端工作现场）
      Tab（终端工作页）
        Pane（显示一个 terminal）
          Terminal（运行 agent CLI / shell / test）

Agent session list（跨现场的状态投影）→ 定位已有 worktree/tab/pane

• 默认三个区域：左上 project/worktree 树，左下 agent sessions 状态总览，右侧 terminal tabs 与当前 tab 的终端 panes。Workspace 不占独立常驻 pane；右侧默认单 pane，可分屏。
• Project ≠ Repository 继续有效：repo 是首版导航的简化呈现，不把底层概念合并。非 Git 工作目录保持可打开，不伪造 Git worktree。
• 左下条目是一次 agent session，普通 shell/test 不占 agent 条目；同 CLI 可有多个 sessions，同成员也可有多个执行。长期 Resident 配置/历史有独立入口，不强制增加常驻成员 pane。
• Task/Execution 继续保存目标、结果、归属与授权；Task 信息可从工作位置/session 进入，不要求另加一个常驻 Task pane，不增加第二套工作流状态。

2. 打开与组合 Workspace

支持打开已有本地 .code-workspace、在 Viva 新建/命名/添加项目/另存组合，以及直接打开单 repo 后再加入其他项目。目录可来自不同父目录，不因组合形成软件依赖。

兼容范围：JSONC、folders 的 path/name、相对/绝对本地路径。相对路径以组合文件目录为基准；非本地 URI、缺失路径、非 Git 目录明确报告。原文件默认不改，保存组合保留其他字段；不会执行 VS Code settings/tasks/launch。文件仅表达组合，终端/布局/任务与执行历史仍在 Viva 状态层，不混写原生 CLI 会话。

组合的引用、移除与切换不复制已有项目身份，不删除文件/历史，不误停运行进程，不扩大成员 grant。多组合共享 repo 时的稳定身份/成员关系由 #74 的实现契约明确，导航不会回写历史执行的 attribution。

3. 工作现场与终端交互

每 worktree 保存 tabs、active tab、每 tab 的分屏/zoom/focus；选择已有 worktree 恢复现场，明确 New tab/New terminal 才启动进程。点击 agent 定位原 worktree/tab/pane，不通过替换当前 pane 拼出假跳转。关闭视图与 Stop session 明确分开，隐藏运行会话可再次找回。

完整终端呈现至少保留样式/Unicode 宽度/光标及必要输入模式；Esc 可交给 CLI，多行粘贴按终端模式处理，窗口/split/zoom/tab 切换的真实 inner rect 联动 PTY resize；host scrollback 与活动/alternate screen 分开，鼠标导航和 CLI 输入边界明确。优先检查现有 vt100/成熟 adapter，仅在证据证明阻断性缺口时替换引擎。

生命周期仍由 ADR-0012 约束：默认关闭 TUI 为 detach，运行任务继续；pause/stop/server shutdown 各有明确语义。UI 布局恢复、原生 CLI session resume、进程 fd 活转移分别验收，不将三者合称已无损恢复。状态来源沿用 controlled/process/screen 分层，screen 推断不能成为 Task 完成依据。

4. 2026-10-06 源码证据与限制

Viva 本地基线 dd97ae7，最新远端 main a00f1d2 的变化为发布文档整理；herdr 本地基线 e35f3937b0efe40ec0dab675709c68e1d8e8c9e6。只读源码/测试阅读，没有在本轮启动程序、运行测试或进行性能测量。

发现	固定源码
herdr Workspace 是 cwd + tabs 的终端现场；每 tab 有 layout/panes	workspace · tab
herdr agent 列表排除普通 shell，点击定位已有现场	过滤 · 聚焦
Viva 当前唯一全局 grid / workbench_layout；worktree Enter 新开 shell	全局布局 · 保存 · Enter
Viva agents 当前遍历全部 terminals	列表
Viva PTY 经 vt100 解析，但 TUI 快照只传文本行，渲染为 Paragraph	快照 · 渲染
Viva 工作台只处理 Key，Esc 被外层截获；有 resize API 但本循环未调用	loop · 键盘

这些差异是源码证据，不等于 herdr 所有工具兼容性实测 PASS，也不证明 Viva 资源或授权完整验收通过。herdr 已有 server/活转移、Viva 也有对应基础；本次不推翻 ADR-0011 的 Rust/SQLite/Pi 选型与 ADR-0012 的 server 决定。

5. Issue 交付与已有能力

Slice	结果	已检查复用与缺口
#74	Workspace 打开/组合与 .code-workspace 兼容	#11 注册、#17 discovery；缺组合文件入口和当前 workspace 投影
#75	每 worktree tabs/layout、现场恢复	#44 PaneNode、#43/#45/#48 PTY/恢复；缺工作现场所有权与 tab 层
#76	Agent session 状态总览与跨现场定位	#46 状态来源；缺 agent-only 投影及到原 tab/pane 的导航
#77	原生 CLI TUI 的呈现与输入	#14 PTY/vt100、#15/#44 renderer；缺样式/光标/模式投影及输入/几何联动

复用 #27 为集成入口、#21 为资源/故障/最终真实验收；#18/#19 保留 Pi 和跨 harness 能力验收，#63/#66 保留真实故障与验收工具修复；#49 的 SSH/主题等后续范围仍有效。没有直接矛盾的 open issue，不能仅因旧票不完整或验收未结束就关闭。

#74、#75、#77 可在明确接口下准备；#76 状态投影可先做，最终导航依赖 #75、workspace 筛选依赖 #74。共同修改 workbench/mod.rs、main.rs、server/protocol.rs 与 migrations 时固定接口/owner，独立 worktree/branch，集成顺序不作为所有开发开工屏障。

6. 完成门槛（尚未执行）

• 两个真实 repo、各两个 worktree；各有至少两个 tabs，至少一个 tab 分屏；A→B→A 保持现场和焦点，重复选择不新建进程。
• 左下普通 shell/test 不冒充 agent；点击异地 agent 回原 pane，状态来源可辨、执行归属不串。
• 真 Pi + 第二已安装 CLI 的颜色/光标、Esc、多行粘贴、Unicode、resize、scrollback 与鼠标路径留工具版本/机器/真实证据。
• detach/attach、live handoff、单 session stop、旧布局迁移与无效引用不丢历史、不误停邻居、不盲目重放。
• #27 的三真实任务演示与 #21 的 Intel Mac/16真实 Agent 资源门槛继续独立记录。缺机器/凭证保持 pending；issue 创建不是功能完成，布局快照或测试 fixture 不是本轮实测。