| 1 | # 工作间（Workroom）架构 |
| 2 | |
| 3 | > 英文原文：[WORKROOM_ARCHITECTURE.md](../WORKROOM_ARCHITECTURE.md)。 |
| 4 | > 最后与英文同步日期（last synced with English revision）：2026-09-29。 |
| 5 | |
| 6 | ## 目的 |
| 7 | |
| 8 | 工作间是 Codewhale 面向聊天的抽象，用来表示持久、可寻址的智能体（agent）工作线程。 |
| 9 | 它们位于 Runtime API 的临时线程模型与面向用户的表面（TUI、移动端、聊天桥）之间。 |
| 10 | |
| 11 | 这是一份草案性的 v0.9 架构说明。在 v0.8.62 中，只存在协议数据类型和链接解析器。 |
| 12 | Runtime 端点、持久状态、移动端渲染，以及模型可见的链接解析，都是计划中的后续工作。 |
| 13 | |
| 14 | ## 组件图 |
| 15 | |
| 16 | ``` |
| 17 | ┌─────────────────────────────────────────────────────┐ |
| 18 | │ User surfaces │ |
| 19 | │ ┌──────┐ ┌─────────┐ ┌──────────┐ │ |
| 20 | │ │ TUI │ │ Mobile │ │ Bridges │ │ |
| 21 | │ └──┬───┘ └────┬────┘ └────┬─────┘ │ |
| 22 | │ │ │ │ │ |
| 23 | │ └───────────┼────────────┘ │ |
| 24 | │ │ future HTTP + workroom links │ |
| 25 | ├─────────────────┼───────────────────────────────────┤ |
| 26 | │ Runtime API │ │ |
| 27 | │ ┌──────────────┴──────────────┐ │ |
| 28 | │ │ Planned workroom endpoints │ │ |
| 29 | │ │ GET /workrooms │ │ |
| 30 | │ │ GET /workroom/:id/threads │ │ |
| 31 | │ │ GET /workroom/resolve │ │ |
| 32 | │ └──────────────┬─────────────┘ │ |
| 33 | │ │ │ |
| 34 | │ ┌──────────────┴─────────────┐ │ |
| 35 | │ │ Existing endpoints │ │ |
| 36 | │ │ /thread /app /prompt ... │ │ |
| 37 | │ └────────────────────────────┘ │ |
| 38 | └─────────────────────────────────────────────────────┘ |
| 39 | ``` |
| 40 | |
| 41 | ## 数据流 |
| 42 | |
| 43 | 1. **创建。** 未来的工作间在启动一个带工作间上下文（标题、工作区、外部引用）的线程时创建。 |
| 44 | 工作间 id 是稳定的，可以作为 `codewhale://workroom/...` 链接分享。 |
| 45 | |
| 46 | 2. **事件发布。** 每个智能体动作（工具调用、审批、失败）都会作为 `WorkroomEvent` |
| 47 | 记录在工作间的事件日志里。事件带有 `AgentAttribution` 元数据， |
| 48 | 追踪是哪个提供商（provider）、模型和智能体产生了它们。 |
| 49 | |
| 50 | 3. **链接解析。** 当 `codewhale://workroom/...` 链接出现在聊天表面时， |
| 51 | 未来的 `resolve_workroom_link` 工具（或 API 端点）会解析它并返回有作用域的上下文： |
| 52 | 线程元数据、外部引用和最近的事件摘要。调用方模型随后可以决定是否读取完整的线程对话记录（transcript）。 |
| 53 | |
| 54 | 4. **列出。** 未来的 `/workrooms` 端点返回所有可见工作间的摘要 |
| 55 | （id、标题、updated_at、活跃线程数）。各个表面消费它来支撑收件箱/最近活动视图。 |
| 56 | |
| 57 | ## 状态存储 |
| 58 | |
| 59 | 持久化的工作间状态应当与现有 Codewhale 状态放在一起： |
| 60 | |
| 61 | ``` |
| 62 | ~/.codewhale/ |
| 63 | ├── workrooms/ |
| 64 | │ ├── wr_abc123.json # Workroom metadata + event log |
| 65 | │ └── wr_def456.json |
| 66 | ├── threads/ # Existing thread state (unchanged) |
| 67 | ├── checkpoints/ |
| 68 | ├── config.toml |
| 69 | └── ... |
| 70 | ``` |
| 71 | |
| 72 | 每个 `.json` 文件会包含工作间元数据（`Workroom` 结构体）、一组 `WorkroomThread` 描述符， |
| 73 | 以及一组有界的最近 `WorkroomEvent` 记录。这个状态存储尚未实现。 |
| 74 | |
| 75 | ## Crate 职责 |
| 76 | |
| 77 | | Crate | 职责 | |
| 78 | |---|---| |
| 79 | | `codewhale-protocol` | 类型：`Workroom`、`WorkroomId`、`WorkroomThread`、`WorkroomEvent`、`WorkroomLink`、`ExternalThreadRef`、`AgentAttribution` | |
| 80 | | `codewhale-app-server` | 未来的端点：`GET /workrooms`、`GET /workroom/:id/threads`、`GET /workroom/resolve` | |
| 81 | | `codewhale-tui` | 未来面向模型的链接解析，以及可选的任务面板收件箱 | |
| 82 | | `codewhale-state` | 未来：持久工作间存储（第 2 阶段） | |
| 83 | |
| 84 | ## 阶段状态 |
| 85 | |
| 86 | | 阶段 | 功能 | 状态 | |
| 87 | |---|---|---| |
| 88 | | 1 | RFC 设计文档 | ✅ 已完成 | |
| 89 | | 1 | 协议数据类型 | ✅ 已完成（含测试） | |
| 90 | | 1 | App-server 工作间端点 | ⏳ 尚未开始 | |
| 91 | | 1 | `resolve_workroom_link` 工具 | ⏳ 尚未开始 | |
| 92 | | 1 | 安全模型文档 | ✅ 已完成 | |
| 93 | | 1 | 架构文档 | ✅ 已完成 | |
| 94 | | 2 | 持久工作间状态存储 | ⏳ 尚未开始 | |
| 95 | | 2 | 移动端页面的工作间收件箱 | ⏳ 尚未开始 | |
| 96 | | 2 | 聊天桥事件集成 | ⏳ 尚未开始 | |
| 97 | | 2 | TUI 任务面板收件箱 | ⏳ 尚未开始 | |
| 98 |