feat(docs): add development documentation, prototypes, and war-room components

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-04-11 08:49:41 +08:00
parent 1ca8855751
commit 21c869db62
1218 changed files with 11858 additions and 0 deletions

View File

@@ -0,0 +1,90 @@
# War Room 实施计划索引
本目录用于沉淀 `War Room` 页面的分阶段实施计划。目标不是重写一份设计稿,而是把已经批准的规格文档与仓库当前实现状态对齐,形成一套可直接执行、可验证、可拆分的交付路线。
规格来源:
- `docs/superpowers/specs/2026-04-09-war-room-design.md`
当前仓库锚点:
- `frontend/src/pages/war-room/index.vue`
- `frontend/src/app/router/routes.ts`
- `frontend/src/pages/agents/`
- `frontend/src/pages/chat/`
- `frontend/src/api/`
- `backend/app/routers/`
## 文档说明
| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、设计原则、风险与推荐顺序 |
| `phase-wr-0-current-state.md` | 当前实现盘点、差距分析、目标边界 |
| `phase-wr-1-shell-and-fixed-mode.md` | 页面骨架、组件拆分、FIXED 模式落地 |
| `phase-wr-2-studio-foundation.md` | STUDIO 模式画布、节点交互、本地编排状态 |
| `phase-wr-3-data-contract-and-api.md` | 前后端数据契约、API、状态管理与 mock 替换 |
| `phase-wr-4-teams-runtime-chat-handoff.md` | TEAMS、Runtime、/chat 执行链与联调收口 |
| `checklist.md` | 供 Codex 或人工执行的勾选清单 |
## 推荐阅读顺序
1. `phase-wr-0-current-state.md`
2. `phase-wr-1-shell-and-fixed-mode.md`
3. `phase-wr-2-studio-foundation.md`
4. `phase-wr-3-data-contract-and-api.md`
5. `phase-wr-4-teams-runtime-chat-handoff.md`
6. `checklist.md`
## 当前总体状态2026-04-10
| Phase | 状态 | 说明 |
|------|------|------|
| WR-0 | 已完成 | 已完成现状盘点与目标拆分 |
| WR-1 | 待开始 | 先把单文件样机收敛成可扩展页面骨架 |
| WR-2 | 待开始 | 补 STUDIO 的真实交互和画布状态 |
| WR-3 | 待开始 | 接入真实数据契约与 API |
| WR-4 | 待开始 | 完成 TEAMS、Runtime 与 /chat 执行闭环 |
## 当前实现结论
1. `/war-room` 页面已经存在,但本质上仍是静态样机。
2. 主要数据来自 `index.vue` 内部硬编码数组,尚未接任何 `war-room` 专用 API。
3. 页面目前额外存在 `runs` 模式,这与已批准 spec 的三模式 `FIXED | STUDIO | TEAMS` 不完全一致。
4. 当前文件存在中文文案乱码,说明在编码或文案维护链路上已有质量问题。
5. 页面代码集中在单个 SFC 中,后续接 API、拖拽和 Inspector 交互时维护成本会迅速放大。
## 总体实施原则
1. 先拆骨架再接能力,避免在超大单文件上继续叠加逻辑。
2. 先保留现有视觉语言,再把 mock 数据逐步替换成真实状态。
3. 先建立最小可运行的本地编排模型,再接后端编排 API。
4. `/war-room``/agents` 保持风格连续,但不强行共用不稳定实现。
5. `/chat` 执行链路必须在计划中尽早定接口,否则 `运行` 按钮只能长期停留在占位态。
6. 每一阶段都要求有明确验证物,而不是只交页面视觉变化。
## 阶段依赖图
```text
WR-0 -> WR-1 -> WR-2 -> WR-3 -> WR-4
```
不建议跳阶段。尤其是:
- 没有完成 WR-1 的组件化拆分WR-2 的画布交互会持续堆积技术债。
- 没有完成 WR-3 的数据契约WR-4 的运行态和 `/chat` 交接无法闭环。
## 预估工作量
| Phase | 预估 |
|------|------|
| WR-1 | 1.5 天 |
| WR-2 | 2 天 |
| WR-3 | 2 天 |
| WR-4 | 1.5 天 |
| 总计 | 7 天 |
## 关键风险
1. 现有 `war-room` 样机和批准 spec 在模式定义上已有偏差,实施前需要以 spec 为准清理页面信息架构。
2. STUDIO 模式若引入拖拽库或画布库,会触发“无新依赖”的约束;默认应优先使用现有能力或原生方案。
3. `GET /api/agents/templates` 与现有 `agent.py` 路由职责边界需要先定,避免后端语义混乱。
4. `/chat` 如何接受编排执行上下文目前仍是待确认项,必须在 WR-3 结束前明确。

View File

@@ -0,0 +1,59 @@
# War Room 执行清单
## WR-0 现状梳理
- [x] 阅读批准规格文档
- [x] 盘点现有 `/war-room` 页面
- [x] 识别与 spec 的主要偏差
- [x]`development-doc/plan/war-room-update/` 落盘计划文档
## WR-1 页面骨架与 FIXED
- [ ] 移除 `RUNS` 一级模式或降为非一级入口
- [ ] 拆分 `index.vue`
- [ ] 新建 `useWarRoomPage.ts`
- [ ] 新建 `ModeStrip`
- [ ] 新建 `ResourceBay`
- [ ] 新建 `InspectorBay`
- [ ] 新建 `RuntimeStrip`
- [ ] 新建 `StageFixed`
- [ ] 修复中文乱码
- [ ] 完成 FIXED 选中与 Inspector 联动
- [ ] 完成模板实例化为本地 orchestration 草稿
## WR-2 STUDIO
- [ ] 定义 `FlowNode` / `FlowEdge` / orchestration draft 类型
- [ ] 新建 `NodePalette`
- [ ] 新建 `FlowCanvas`
- [ ] 支持节点新增
- [ ] 支持节点选择
- [ ] 支持节点移动
- [ ] 支持节点删除
- [ ] 支持连线创建
- [ ] 支持 Inspector 配置联动
- [ ] 打通 FIXED -> STUDIO
## WR-3 数据与 API
- [ ] 新建 `frontend/src/api/warRoom.ts`
- [ ] 设计 Agent Templates API
- [ ] 设计 Orchestrations API
- [ ] 设计 Teams API
- [ ] 新增后端 router / schema / service
- [ ] 替换首页 mock 数据
- [ ] 增加加载态 / 空态 / 错误态
- [ ] 补充前后端测试
## WR-4 闭环与联调
- [ ] 实现 `StageTeams`
- [ ] 实现 TeamNetwork
- [ ] Runtime feed 接真实数据
- [ ] 设计并实现 launch 接口
- [ ] 打通 `/war-room` -> `/chat`
- [ ] 清理无效按钮和占位行为
- [ ] 完成响应式回归
- [ ] 运行前端测试
- [ ] 运行后端测试
- [ ] 手测完整主链路

View File

@@ -0,0 +1,111 @@
# WR-0 当前状态与目标边界
## 1. 现状盘点
### 1.1 已有能力
1. 前端已有路由 `frontend/src/app/router/routes.ts -> /war-room`
2. 页面主体已存在于 `frontend/src/pages/war-room/index.vue`
3. 页面已有较完整的科幻视觉语言:
- 顶部指挥栏
- 左侧资源面板
- 中央主舞台
- 右侧 Inspector
- 底部 Runtime Strip
4. 页面已经有四组静态展示数据:
- `fixedOps`
- `studioNodes`
- `teams`
- `runFeed`
### 1.2 当前缺口
1. 页面仍是单文件实现,结构、状态、样式全部耦合在一个 SFC 内。
2. 当前数据全部 hardcoded没有 Pinia store、没有 composable、没有 API 层。
3. Inspector 并不真正跟随画布选中项变化。
4. STUDIO 只是示意图,没有拖拽、连线、缩放、平移、删除等 spec 级交互。
5. TEAMS 模式只有静态卡片,没有成员拓扑、协作协议详情、操作入口。
6. Runtime feed 只有静态列表,不反映真实运行记录。
7. 顶部按钮没有闭环:
- `NEW AGENT`
- `LAUNCH FLOW`
8. 文案中存在乱码,说明页面内容还未进入可交付质量线。
9. 现有页面多出 `RUNS` 模式,与批准 spec 不一致。
## 2. 设计与实现的差距
| 维度 | Spec 要求 | 当前状态 | 结论 |
|------|-----------|----------|------|
| 模式数量 | FIXED / STUDIO / TEAMS | fixed / studio / teams / runs | 需要收敛模式定义 |
| 数据来源 | API + 可持续维护的数据结构 | 本地 mock | 必须抽离 |
| 组件结构 | WarRoomPage + 子组件 | 单文件 | 必须拆分 |
| FIXED | 模板浏览与实例化 | 静态卡片 | 可复用现有视觉,但要接真实数据 |
| STUDIO | 可编排画布 | 仅示意图 | 需要实做交互层 |
| TEAMS | 群组协作视图 | 静态卡片 | 需要补数据与拓扑 |
| Runtime | 实时事件滚动 | 静态假数据 | 需要接执行记录 |
| /chat handoff | 可运行当前编排 | 未落地 | 必须定义接口 |
## 3. 目标边界
本轮计划的目标是把 `/war-room` 做成“可维护、可接真实数据、可触发执行”的页面,而不是一步做完所有高级编排能力。
本轮完成标准:
1. 页面结构完成组件化和状态分层。
2. FIXED / STUDIO / TEAMS 三模式与 spec 对齐。
3. 至少一条最小编排链路可以保存并交给 `/chat` 执行。
4. Inspector、Runtime、资源面板不再是纯静态展示。
5. 现有乱码文案清理完成。
本轮不强求:
1. 完整 BPMN 级流程设计器。
2. 真正的多人实时协同编辑。
3. 复杂权限系统。
4. 高级运行回放或可视化 tracing。
## 4. 建议目标架构
### 4.1 前端
建议拆分为:
- `frontend/src/pages/war-room/index.vue`
- `frontend/src/pages/war-room/composables/useWarRoomPage.ts`
- `frontend/src/pages/war-room/components/ModeStrip.vue`
- `frontend/src/pages/war-room/components/ResourceBay.vue`
- `frontend/src/pages/war-room/components/InspectorBay.vue`
- `frontend/src/pages/war-room/components/RuntimeStrip.vue`
- `frontend/src/pages/war-room/components/stage-fixed/*`
- `frontend/src/pages/war-room/components/stage-studio/*`
- `frontend/src/pages/war-room/components/stage-teams/*`
- `frontend/src/api/warRoom.ts`
### 4.2 后端
建议按职责拆分:
- `backend/app/routers/agent.py`
- 扩展模板读取接口,或显式挂载模板子路由
- `backend/app/routers/orchestration.py`
- `backend/app/routers/team.py`
- `backend/app/schemas/war_room.py`
- `backend/app/services/war_room/`
### 4.3 状态
建议建立统一页面状态:
- 当前模式
- 资源列表
- 当前选中项
- 当前编排图
- 团队列表
- 运行态 feed
- 加载与错误状态
## 5. 前置决策
1. 以批准 spec 为准,移除或降级当前 `RUNS` 模式。
2. 先不引入新依赖STUDIO 默认使用原生事件 + SVG 方案。
3. Agent templates 与 orchestrations 的 API 职责分离,不把所有 war-room 数据都塞进一个接口。
4. `/chat` 执行链先走最小方案:
- 选择当前 orchestration
- 生成执行 payload
- 跳转 `/chat` 并带上 orchestration id 或 execution context

View File

@@ -0,0 +1,82 @@
# WR-1 页面骨架与 FIXED 模式
## 目标
把当前 `frontend/src/pages/war-room/index.vue` 从静态单文件样机收敛成可扩展页面骨架,并完成 FIXED 模式的真实结构化落地。
## 范围
1. 页面组件化拆分。
2. 状态从本地散落常量迁移到 composable 或 store。
3. 统一模式定义,只保留 `fixed / studio / teams`
4. FIXED 模式完成模板浏览、选中、详情展示和“实例化到编排”入口。
5. 清理乱码文案。
## 具体任务
### 1. 拆页面骨架
建议拆分:
- `index.vue` 只保留页面装配
- `ModeStrip.vue`
- `ResourceBay.vue`
- `InspectorBay.vue`
- `RuntimeStrip.vue`
- `StageFixed.vue`
### 2. 抽页面状态
新增 `useWarRoomPage.ts`,集中管理:
- `activeMode`
- `selectedResourceId`
- `selectedEntity`
- `templateList`
- `runtimeFeed`
- 页面级动作方法
### 3. FIXED 模式最小闭环
FIXED 要先支持:
1. 展示模板列表
2. 点击模板卡片后 Inspector 更新
3. `OPEN` 打开详情态
4. `INSTANTIATE` 将模板转成一份本地 orchestration 草稿
### 4. 样式收敛
1. 保留现有视觉方向,不做大规模重设计。
2. 把 stage 内部样式拆到子组件可维护范围。
3. 校正文案乱码,统一中英文策略。
## 建议文件变更
### Frontend
- 新增 `frontend/src/pages/war-room/composables/useWarRoomPage.ts`
- 新增 `frontend/src/pages/war-room/components/ModeStrip.vue`
- 新增 `frontend/src/pages/war-room/components/ResourceBay.vue`
- 新增 `frontend/src/pages/war-room/components/InspectorBay.vue`
- 新增 `frontend/src/pages/war-room/components/RuntimeStrip.vue`
- 新增 `frontend/src/pages/war-room/components/stage-fixed/StageFixed.vue`
- 视情况新增 `frontend/src/pages/war-room/types.ts`
- 重写 `frontend/src/pages/war-room/index.vue`
## 验收标准
1. `war-room` 页面不再依赖单个超大 SFC。
2. 页面模式与 spec 对齐,没有额外 `RUNS` 一级模式。
3. 选中 FIXED 卡片时Inspector 正确更新。
4. `INSTANTIATE` 能产生本地 orchestration 草稿状态。
5. 页面中文文案不再乱码。
## 验证建议
1. 前端单测:
- 模式切换
- FIXED 卡片选中
- instantiate 行为
2. 页面手测:
- `/war-room`
- 窄屏布局
- Inspector 切换

View File

@@ -0,0 +1,101 @@
# WR-2 STUDIO 模式基础能力
## 目标
把 STUDIO 从静态示意画布升级为“可编辑的最小编排画布”。
## 范围
1. NodePalette 节点面板
2. FlowCanvas 本地状态
3. 节点选中、拖拽、删除
4. SVG 连线
5. Inspector 与节点配置联动
## 具体任务
### 1. 节点模型落地
建立前端类型:
- `FlowNode`
- `FlowEdge`
- `FlowHandle`
- `OrchestrationDraft`
补充最小字段:
- `id`
- `type`
- `label`
- `role`
- `position`
- `config`
- `status`
### 2. NodePalette
按 spec 至少支持:
- Trigger
- Agent
- Tool
- Condition
- Memory
第一版可先做“点击添加到画布”,第二版再补完整拖拽源体验。
### 3. 画布交互
最小要求:
1. 新增节点
2. 选择节点
3. 移动节点
4. 删除节点
5. 建立连接
6. 画布缩放和平移
### 4. Inspector 联动
选中节点后展示:
- 节点类型
- 角色/标签
- 配置摘要
- 删除/复制/断开操作
### 5. FIXED 到 STUDIO 的桥接
WR-1 里 `INSTANTIATE` 生成的草稿,必须能在 STUDIO 中打开并编辑。
## 建议文件变更
### Frontend
- 新增 `frontend/src/pages/war-room/components/stage-studio/StageStudio.vue`
- 新增 `frontend/src/pages/war-room/components/stage-studio/NodePalette.vue`
- 新增 `frontend/src/pages/war-room/components/stage-studio/FlowCanvas.vue`
- 新增 `frontend/src/pages/war-room/components/stage-studio/StudioNode.vue`
- 新增 `frontend/src/pages/war-room/components/stage-studio/FlowEdges.vue`
- 扩展 `useWarRoomPage.ts`
## 验收标准
1. STUDIO 中至少能完成一个最小链路:
- Trigger -> Agent -> Condition -> Output
2. Inspector 会随着选中节点切换。
3. 删除节点后相关连线同步清理。
4. 从 FIXED 实例化进入 STUDIO 不丢节点数据。
## 风险与约束
1. 默认不引入新依赖,画布能力优先原生实现。
2. 若原生方案复杂度失控,再单独评估依赖引入,不在本阶段默认实施。
## 验证建议
1. 交互测试:
- 节点新增
- 节点删除
- 连线创建
- Inspector 更新
2. 手测:
- 缩放和平移
- 复杂布局下的线条表现

View File

@@ -0,0 +1,120 @@
# WR-3 数据契约与 API 集成
## 目标
`war-room` 从本地草稿和 mock 数据过渡到真实数据契约,完成前后端 API、页面状态和测试的基础闭环。
## 范围
1. 设计并实现模板、编排、群组三组接口。
2. 建立前端 `warRoom.ts` API 层。
3. 接入 Pinia 或 composable 的异步数据流。
4. 去除页面核心 mock 数据。
## API 规划
### 1. Agent Templates
优先对齐 spec
- `GET /api/agents/templates`
- `GET /api/agents/templates/:id`
说明:
- 可以挂在现有 `agent.py`,但只承载模板读取,不混入运行态编辑逻辑。
### 2. Orchestrations
建议新增路由:
- `GET /api/orchestrations`
- `POST /api/orchestrations`
- `PUT /api/orchestrations/:id`
- `DELETE /api/orchestrations/:id`
### 3. Teams
建议新增路由:
- `GET /api/teams`
- `POST /api/teams`
- `PUT /api/teams/:id`
- `DELETE /api/teams/:id`
## 数据结构建议
### Frontend / Backend 共识
```ts
interface AgentTemplate {
id: string
name: string
type: 'schedule' | 'knowledge' | 'bookkeeping' | 'dispatch'
kicker: string
icon: string
tone: 'cyan' | 'amber' | 'green' | 'violet'
summary: string
stats: string[]
flow: string[]
}
```
```ts
interface Orchestration {
id: string
name: string
nodes: FlowNode[]
edges: FlowEdge[]
source_template_id?: string | null
updated_at: string
}
```
```ts
interface TeamSummary {
id: string
name: string
protocol: 'leader-led' | 'pipeline' | 'roundtable'
member_count: number
focus: string
}
```
## 建议文件变更
### Backend
- 新增 `backend/app/routers/orchestration.py`
- 新增 `backend/app/routers/team.py`
- 新增 `backend/app/schemas/war_room.py`
- 视情况新增 `backend/app/services/war_room/`
- 修改 `backend/app/main.py` 注册路由
### Frontend
- 新增 `frontend/src/api/warRoom.ts`
- 扩展 `useWarRoomPage.ts`
- 让 FIXED / STUDIO / TEAMS 从 API 读数据
## 验收标准
1. `/war-room` 首屏不再依赖硬编码模板与团队数据。
2. orchestration 草稿可以创建、读取、更新。
3. TEAMS 模式能读取真实列表。
4. 数据加载、空态、错误态都可见。
## 测试要求
### Backend
- router 单测
- schema 序列化校验
- create/update/delete 流程测试
### Frontend
- API mock 测试
- 页面加载状态测试
- 保存 orchestration 行为测试
## 前置决策
WR-3 结束前必须明确 `/chat` 接口需要的最小执行 payload否则 WR-4 无法完成。

View File

@@ -0,0 +1,89 @@
# WR-4 TEAMS、Runtime 与 /chat 执行闭环
## 目标
完成 `war-room` 的最后一公里,让页面从“可编辑”升级为“可发起执行并观察结果”。
## 范围
1. TEAMS 模式真实化
2. Runtime strip 与运行记录联动
3. 顶部 `运行` 按钮接入 `/chat`
4. 页面整体联调和回归验证
## 具体任务
### 1. TEAMS 模式
补齐:
- TeamCard
- TeamNetwork
- 协作协议说明
- 选中群组后的 Inspector 详情
### 2. Runtime Feed
最小要求:
1. 读取最近执行记录
2. 显示时间、事件、详情、状态
3. 与当前 orchestration 或 team 建立过滤关系
### 3. /chat handoff
建议最小方案:
1. 用户在 `/war-room` 选择当前 orchestration
2. 点击 `运行`
3. 前端调用执行准备接口,返回 `execution_context`
4. 跳转 `/chat`
5. `/chat` 根据上下文自动加载对应执行任务或预填 prompt
候选接口:
- `POST /api/orchestrations/:id/launch`
返回建议:
- `orchestration_id`
- `execution_id`
- `chat_seed`
- `target_route`
### 4. 页面收口
1. 统一顶部按钮行为
2. 统一空态、错误态和加载态
3. 完成视觉细节与响应式收口
4. 去掉临时占位按钮和无效入口
## 建议文件变更
### Frontend
- 新增 `frontend/src/pages/war-room/components/stage-teams/StageTeams.vue`
- 新增 `frontend/src/pages/war-room/components/stage-teams/TeamCard.vue`
- 新增 `frontend/src/pages/war-room/components/stage-teams/TeamNetwork.vue`
- 扩展 `RuntimeStrip.vue`
- 修改 `/chat` 接收 war-room 上下文的入口逻辑
### Backend
- 扩展 orchestration launch 接口
- 增加运行记录查询接口或复用现有日志/任务体系
## 验收标准
1. TEAMS 模式展示真实群组数据。
2. Runtime feed 能展示真实运行记录或最小真实事件流。
3. 点击 `运行` 可以从 `/war-room` 跳转 `/chat` 并带上执行上下文。
4. 页面不存在主要占位假按钮。
## 验证建议
1. 后端接口测试:
- launch
- runtime list
2. 前端集成测试:
- launch 成功跳转
- runtime feed 刷新
3. 手测:
- FIXED -> STUDIO -> 保存 -> 运行 -> /chat
- TEAMS 选中与 Inspector 联动