Add Swarm TUI v2 docs: gap assessment, design mock, PRD, and tech spec

docs/SWARM_SYMPHONY_TUI_GAP_ASSESSMENT_2026-05-28.md

@@ -0,0 +1,108 @@
+# Swarm / Symphony 实现度评估（2026-05-28）
+
+## 1) 结论（TL;DR）
+
+- **Swarm 协议层（ASP）已经实现了本地可用的 v1 能力**：包含 envelope/blackboard/ownership/handoff/协作投影与回放证据，足以支撑“单机/本地多 agent 协作”的主路径。  
+- **Symphony 已达到“可运行的本地调度器”状态**：具备 work source 拉取、并发调度、重试恢复、workspace 生命周期、runner 事件回传和状态可观测。  
+- **与你们文档里的“完整愿景”相比，仍是“本地优先、分布式延后”**：跨主机路由、复杂共识、分布式 checkpoint/trace 等明确被标注为 deferred。  
+- **TUI 产品化能力较成熟，但品牌识别尚不足**：当前大量采用 CC-style 的交互原则（这是好事），但在“Swarm 独有信息架构 + 视觉语义叙事 + 协作心智模型”上还有明显提升空间。
+
+## 2) 对照 Swarm.md（ASP 设计）
+
+### 已落地（强）
+
+- 运行时已提供 swarm 协作可视投影：participants / mailbox / ownership / negotiations / squads / conflicts 等核心协作态。  
+- 提供 swarm workbench 与 summary 输出，能把黑板、handoff、actor heartbeat 等“协作证据”显式展示。  
+- 具备与本地 work-board 的关联投影，说明协议态和执行态已开始融合而非分离。
+
+### 未完全落地（按设计文档口径）
+
+- 分布式 transport（跨 host 网络路由）仍未作为“完成能力”对外承诺。  
+- 更复杂共识策略（超出 reviewer/本地协议夹具）未完成产品化。  
+- 更丰富 checkpoint 编排仍停留在“有边界能力（list/create/revert）”，非全局编排层。
+
+### 评估
+
+- 如果你们目标是 **“本地可用、可验证、可发布”**：已基本达标。  
+- 如果你们目标是 **“广域分布式 swarm 平台”**：仍在 roadmap 中段。
+
+## 3) 对照 Symphony.md（服务编排设计）
+
+### 已落地（强）
+
+- 设计里要求的 orchestrator / workspace / runner / observability 主干在 README 的当前状态声明中已经逐项对应。  
+- 明确支持 repository-owned workflow（`WORKFLOW.md`）和本地工作源，符合规范“策略在仓库内版本化”的核心思想。  
+- 具备失败恢复、生命周期、运行状态输出与共享状态格式（CLI/Gateway/TUI）的一致性描述。
+
+### 边界与风险
+
+- “无持久 DB 也能恢复”的实践质量要继续靠故障注入回归测试保障（尤其是 kill -9 / partial writes / 重入）。  
+- 当前优势是“本地自治 + 可解释”；若未来接入远端 provider 和多租户语义，治理复杂度会跃升。
+
+### 评估
+
+- Symphony 作为 **本地 daemon 编排器** 已可用；作为 **云控制平面替代品** 还不是目标，也不该被当前版本要求。
+
+## 4) TUI：现在做得好在哪里
+
+- 产品边界正确：把 TUI 作为主入口，其他 surface 作为自动化/证据渠道。  
+- 交互原则正确：conversation-first、键盘优先、低噪声状态、显式 detail surface。  
+- 工程基础扎实：自研 DOM renderer、input parser、focus/layering、virtual transcript、性能与视觉回归测试链路完整。  
+- 主题系统已具备语义 token 和 profile（dark/contrast/monochrome），有后续塑造“品牌化 TUI”基础。
+
+## 5) 为什么你会感觉“像 Claude Code，而不是 Swarm”
+
+这是一个正常且准确的产品感知：
+
+1. **交互骨架相似**：conversation + transcript + status rail + footer pills 本身是现代 coding-agent TUI 的收敛形态。  
+2. **信息优先级仍偏“工具事件流”**：用户首先看到的是会话与工具执行，而不是“swarm 协作状态机”的叙事中心。  
+3. **品牌语义还在 token 层，未形成“默认主视图叙事”**：你们有 `swarm/workboard/ownership` 数据，但默认视图里它们还不是第一层心智地图。
+
+## 6) 建议的 TUI 重构方向（保留优点 + 建立自我风格）
+
+### A. 信息架构：从“聊天 UI”升级为“协作驾驶舱”
+
+- 默认首屏仍是可输入对话，但在 transcript 上方/侧边给出 **Swarm Topology Strip**：
+  - Active squad
+  - Owner leases
+  - Risk/conflict count
+  - Current policy mode（approval/sandbox）
+- 把 “我问了什么” 与 “Swarm 正在如何协作解决”并列呈现。
+
+### B. 视觉语义：强化“协作身份层”
+
+- 让 user/assistant/tool 之外，新增并强化 **planner/worker/reviewer/aggregator** 角色徽标体系。  
+- 每条关键事件附带 `who decided / who executed / who verified` 三元标签。
+
+### C. 交互语法：把协议动作变成一等快捷操作
+
+- 新增面向 swarm 的直接动作：
+  - `r` 重分配当前阻塞任务
+  - `o` 打开 ownership 冲突列表并可一键 take-over
+  - `n` 展开 negotiation thread
+  - `b` 快速跳转 blackboard claim/proposal/decision
+- 目标：从“看日志”升级为“调度协作”。
+
+### D. 结果叙事：从“命令输出”升级为“决策链证明”
+
+- Result Card 增加 **Decision Trail**（简版因果链）：
+  - 任务拆分 → 关键分配 → 冲突处理 → 验证结论 → 最终建议
+- 对你们这种 Swarm 产品，这会是与通用 coding TUI 的核心差异点。
+
+## 7) 一个可执行的重构路线（建议 3 个阶段）
+
+1. **Phase 1（低风险）**：只加新视图，不改默认键位语义
+   - 增加 `Swarm Topology Strip`
+   - 在 Result Card 增加 Decision Trail
+2. **Phase 2（中风险）**：引入协作操作快捷键
+   - ownership / negotiation / blackboard 快捷入口
+3. **Phase 3（高辨识度）**：品牌化视觉协议
+   - 角色徽标、协作链路色彩、冲突/风险动效节奏
+
+每阶段都沿用现有 release gate，避免“风格升级破坏稳定性”。
+
+## 8) 现在是否“已经可以实现我们的功能”？
+
+- **如果你们当前功能定义是：本地多 agent 协作开发 + 可观测 + 可恢复 + 可审批执行**，答案是：**是，已经可用，并且工程上比较扎实**。  
+- **如果你们下一步功能定义是：强分布式 swarm 网络编排**，答案是：**尚未完全实现，当前版本属于明确的本地优先架构**。  
+- **如果你们产品目标是“有自己风格的 TUI”**，答案是：**技术地基已具备，现在主要是产品信息架构与视觉语义重构问题，而不是底层能力不足**。

docs/TUI_DESIGN_MOCK_V2.md

@@ -0,0 +1,121 @@
+# Swarm TUI 设计稿 v2（文本线框 + 交互稿）
+
+Status: Draft (2026-05-28)
+
+## 1. 首屏线框（120 columns）
+
+```text
+┌ Swarm ───────────────────────────────────────────────────────────────────────────────────────────┐
+│ TOPOLOGY  SQ:2(active)  OW:1(blocked)  CF:0  AP:2(wait)  POLICY:scoped-write  [Enter: detail] │
+├──────────────────────────────────────────────────────────────────────────────────────────────────┤
+│ USER      修复 CI 里 parser 的 flaky test，并说明 root cause                                    │
+│ SWARM     已拆分为 3 个子任务，先定位 nondeterminism 来源，再收敛 patch。                         │
+│ WORKER#1  Running tests: parser/retry.spec.ts                                                    │
+│ TOOL      npm test -- parser/retry.spec.ts (folded, 320 lines)                                  │
+│ REVIEWER  建议增加 deterministic seed，避免 clock drift。                                        │
+│ RESULT    ✅ fixed 2 files / ✅ tests pass / ⚠ risk: legacy retry path untouched                 │
+│           Decision Trail: [split][assign][verify][decide][risk]                                 │
+│                                                                                                  │
+│ > Ask Swarm:                                                                                     │
+├──────────────────────────────────────────────────────────────────────────────────────────────────┤
+│ mode:auto  perm:approval  sandbox:workspace  Gateway:ON  Symphony:2run  LSP:ready  MCP:3        │
+│ / search · o ownership · n negotiation · b blackboard · r reassign · Esc back                  │
+└──────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. 窄屏线框（80 columns）
+
+```text
+┌ Swarm ────────────────────────────────────────────────────────────────┐
+│ TOPO SQ2 OW1 CF0 AP2 POL:SW                                          │
+├───────────────────────────────────────────────────────────────────────┤
+│ USER   修复 flaky test                                                │
+│ SWARM  已拆解，正在验证。                                              │
+│ ...                                                                   │
+│ > Ask Swarm:                                                          │
+├───────────────────────────────────────────────────────────────────────┤
+│ auto · approval · ws · G:on · Sy:2 · LSP:ok                          │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+## 3. Ownership Overlay
+
+```text
+┌ Ownership (blocked first) ────────────────────────────────────────────┐
+│ [1] task:parser-seed owner:worker#2 status:blocked wait:review        │
+│ [2] handoff:handoff_17 owner:reviewer status:pending                  │
+│                                                                        │
+│ Enter open · t take-over · a reassign · Esc close                     │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+## 4. Negotiation Overlay
+
+```text
+┌ Negotiation Threads ───────────────────────────────────────────────────┐
+│ neg_23  assign policy conflict  from:planner to:reviewer  status:open │
+│ neg_21  test scope narrowing     from:worker2 to:planner  status:done │
+│                                                                        │
+│ Enter open thread · c resolve proposal · Esc close                     │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+## 5. Blackboard Timeline Overlay
+
+```text
+┌ Blackboard Timeline ───────────────────────────────────────────────────┐
+│ claim      task/parser      by worker#1   10:31:10Z                   │
+│ proposal   fix/seed         by worker#1   10:31:43Z                   │
+│ decision   accept/proposal  by reviewer   10:32:12Z                   │
+│ artifact   test-log         by tool       10:32:18Z                   │
+│                                                                        │
+│ / filter · Enter detail · y copy id · Esc close                       │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+## 6. Decision Trail 展开态
+
+```text
+RESULT CARD
+- Summary: flaky parser fixed via deterministic seed + retry bound
+- Changed: src/parser/retry.ts, src/parser/retry.spec.ts
+- Checks: npm test parser ✅
+
+Decision Trail
+  split:
+    - isolate nondeterminism source
+    - reproduce under stress run
+  assign:
+    - worker#1 owns repro
+    - worker#2 owns patch
+  verify:
+    - reviewer requires 100x loop pass
+  decide:
+    - accept seed patch; reject timeout-only workaround
+  risk:
+    - legacy retry path not fully covered
+```
+
+## 7. 视觉语义建议
+
+- Planner: cyan marker
+- Worker: magenta marker
+- Reviewer: yellow marker
+- Aggregator: green marker
+- Danger/Conflict: red token + `!` glyph
+- Monochrome 模式改用前缀标签（`[PLAN] [WORK] [REV] [AGG]`）
+
+## 8. 交互节奏
+
+1. 用户输入后，先看到 Topology Strip 数值变化，再看到 transcript 细节。
+2. 冲突出现时，Action Rail 只提示“可处理动作”，不自动弹窗。
+3. 用户按 `o/n/b` 进入对应 overlay，Esc 返回 prompt。
+4. 结果出现时默认折叠 Decision Trail，按 Enter 或快捷键展开。
+
+## 9. 可用性验收清单
+
+- Prompt 在任意 overlay 操作后可 1 次 Esc 返回。
+- 空 Enter 不打开 command output 详情页。
+- 80 列下无横向滚动。
+- Monochrome 仍可区分角色与状态。
+- Ctrl+C 后终端状态完整恢复。

docs/TUI_PRD_V2.md

@@ -0,0 +1,113 @@
+# Swarm TUI PRD v2（协作驾驶舱版）
+
+Status: Draft v2 (2026-05-28)
+Owner: Product + Runtime + TUI
+
+## 1. 产品目标
+
+在保持 conversation-first 的前提下，把 Swarm TUI 从“通用 coding chat 终端”升级为“可操作的多 agent 协作驾驶舱”。
+
+核心目标：
+
+1. 用户在首屏可以同时理解 **对话进展 + 协作拓扑 + 风险状态**。
+2. 协议对象（ownership/negotiation/blackboard）从“诊断信息”升级为“一等交互对象”。
+3. 最终结果从“输出摘要”升级为“可审计决策链”。
+
+## 2. 用户与场景
+
+### 2.1 用户类型
+
+- 日常开发者：希望快改快验，不想看噪声日志。
+- Lead/Reviewer：希望判断协作是否失控、谁在阻塞。
+- Agent Builder：希望观察协议行为与策略效果。
+
+### 2.2 关键场景
+
+- 场景 A：单任务快速修复，用户只看结果与风险。
+- 场景 B：多 worker 并行，用户要快速定位阻塞 ownership。
+- 场景 C：争议结果复盘，用户需看到 decision trail。
+
+## 3. 体验原则
+
+- Prompt 永远可见、可输入。
+- 协作态要“可见、可跳转、可操作”，不只可阅读。
+- 默认低噪声，细节通过显式动作展开。
+- 所有关键状态有 evidence 文案，不给模糊 unknown。
+
+## 4. 信息架构（IA）
+
+首屏固定四层：
+
+1. **Topology Strip（新增）**
+   - squads / ownership / conflicts / approvals / policy
+2. **Transcript 主区**
+   - user/assistant/tool/result/progress
+3. **Action Rail（增强）**
+   - 当前动作、最近异常、可恢复建议
+4. **Prompt + Footer**
+   - 输入区 + 服务 pills + 快捷提示
+
+## 5. 核心功能需求
+
+### F1 Topology Strip
+
+- 展示 active squad 数、blocked ownership 数、conflict 数、pending approvals 数。
+- 支持键盘切换 focus，Enter 打开对应 detail。
+- 宽度不足时压缩为 token 化摘要（如 `SQ2 OW1 CF0 AP2`）。
+
+### F2 协作快捷操作
+
+- `o`: 打开 ownership 列表，支持 take-over / reassign。
+- `n`: 打开 negotiation thread 列表。
+- `b`: 打开 blackboard claim/proposal/decision timeline。
+- `r`: 对当前 blocked task 发起“建议重分配”动作（需审批策略允许）。
+
+### F3 Decision Trail（结果卡增强）
+
+结果卡新增结构化区块：
+
+- split（如何拆解）
+- assign（如何分配）
+- verify（如何验证）
+- decide（为何结论成立）
+- risk（剩余风险与回滚建议）
+
+### F4 品牌化角色层
+
+引入稳定角色标记：
+
+- Planner
+- Worker
+- Reviewer
+- Aggregator
+
+每条关键事件可显示三元 attribution：`decided by / executed by / verified by`。
+
+## 6. 非功能需求
+
+- 80/100/120/160 列无水平溢出。
+- 长会话必须维持虚拟化与 append cache 性能。
+- 不破坏现有 renderer 生命周期与 Ctrl+C 清理。
+- NO_COLOR 模式保留状态可辨识（通过 label+layout）。
+
+## 7. 成功指标
+
+- 首次定位阻塞时间（TTFB: time-to-find-blocker）下降 30%。
+- 用户使用协作快捷键占比 > 25%。
+- 结果卡“可解释评分”（内部 dogfood）提升 20%。
+- 因协作状态不透明导致的中断/误操作工单下降。
+
+## 8. 发布策略
+
+- Phase 1: Topology Strip + Decision Trail（默认开启）
+- Phase 2: 协作快捷键（feature flag）
+- Phase 3: 品牌视觉协议（默认开启，保留 monochrome 等效）
+
+## 9. 风险与缓解
+
+- 风险：首屏信息过载。
+  - 缓解：Topology Strip 只展示计数+证据，详细信息延迟展开。
+- 风险：快捷键冲突。
+  - 缓解：统一 shortcuts registry，新增冲突测试。
+- 风险：协作数据不一致。
+  - 缓解：统一 surface projection 源，detail 引用同一快照版本。