Agents_Team/docs/design.md

设计说明

更新时间：2026-03-14

1. 当前产品定义

这不是“全局固定团队系统”，而是：

• 项目级 lead
• 项目级团队
• lead 对话驱动工作台

用户默认只和当前项目的 lead 聊。 团队由 lead 先提出草案，用户确认后才创建正式成员。 团队内正式成员之间允许直接互相发消息，不限制成“执行成员只能找 reviewer”。

2. 当前已经成立的主工作流

当前仓库已经不只是 MVP 骨架，而是已经有一条真实可跑的主链路：

1. 创建项目
2. 生成项目专属团队草案
3. 确认团队
4. lead 派发任务
5. 成员执行
6. reviewer 接单审查
7. 打回 / 通过
8. 成员返工后复审
9. 结果回到 lead 汇总

其中 lead 回复、团队草案生成、成员线程回复、任务启动回执、reviewer 接单、reviewer 审查结论、成员复审回执，已经接入真实 Codex CLI。

3. 当前核心数据结构

服务端类型定义在：

• D:\AI Code\Agents Team\server\src\types.ts

当前比较关键的对象有：

• Project
• LeadProfile
• TeamProposal
• TeamState
• TeamChangeState
• ProjectMember
• RuntimeSession
• MailboxMessage
• MailboxDigest
• SharedMemoryEntry
• TaskItem
• ReviewItem
• TaskActivityEntry

3.1 阶段状态

项目阶段已经固定为：

• lead_only
• discovery_pending
• team_drafting
• team_pending_confirmation
• team_active
• executing
• reviewing
• blocked
• done

3.2 团队变更确认

当正式团队已经存在时，再改团队草案，不会直接覆盖正式团队。

当前会先生成：

• 新增项
• 移出项
• 调整项

然后再单独确认团队变更。

3.3 运行态 / 会话身份

每个正式角色都会保存：

• 当前模型
• 模型来源
• 最近 thread id
• 恢复命令
• 接管命令
• 最近输出
• 错误状态
• 身份状态

身份状态当前分为：

• fresh
• resume_ready
• needs_rebuild

4. Codex CLI 接法

当前策略是“薄适配层”，不修改 Codex CLI 本体。

核心文件：

• D:\AI Code\Agents Team\server\src\runtime.ts
• D:\AI Code\Agents Team\server\src\codexConfig.ts

4.1 已经做成的事情

• 真实调用 Codex CLI 生成 lead / 成员 / reviewer 关键回复
• 角色 thread 建立后，后续优先走 codex exec resume
• 原生接管口使用 codex resume ...
• Web 端可以对单个角色覆盖模型
• 模型列表优先通过 Codex app-server 的 model/list 动态获取

4.2 当前真实模型能力

Web 端现在看到的可用模型，不再主要靠 config.toml 猜，而是：

1. 优先调用 Codex app-server model/list
2. 失败时退回配置文件兜底

所以页面里已经能看到：

• 模型显示名
• 模型说明
• 默认推理档位
• 支持的推理档位
• 是否支持 personality
• 是否是当前默认模型

5. 存储策略

5.1 全局索引

全局只保留项目索引：

• D:\AI Code\Agents Team\data\db.json

这个文件现在只保存：

• id
• name
• path
• description
• createdAt
• updatedAt

5.2 项目级状态

每个项目自己的真实状态保存在：

• <项目目录>\.agents-team\workbench\

当前已经落地的文件：

• project-state.json
• mailbox.json
• shared-memory.json
• shared-memory.md
• task-activity.json

这样项目的协作状态会跟着项目走，不会继续把所有项目状态堆在全局一个 JSON 里。

6. 当前页面结构

前端主页面在：

• D:\AI Code\Agents Team\web\src\pages\HomePage.tsx
• D:\AI Code\Agents Team\web\src\pages\ProjectPage.tsx

6.1 项目页

项目页当前已经是：

• 左侧像素办公室 / 成员状态区
• 中间大面积 lead / 成员对话区
• 右侧收纳区

收纳区当前已经包含：

• 团队草案
• 团队变更确认清单
• 任务推进
• Mailbox
• 共享记忆
• 项目摸底
• 运行态 / 接管口
• 人工接管
• Git 状态

6.2 Mailbox 展示

Mailbox 现在不是简单平铺消息。

当前已经有：

• 服务端摘要分组
• lead 汇总视角
• 按任务 / 成员往来折叠
• 参与人信息
• 建议下一步
• 高亮重点

6.3 运行态展示

运行态面板当前已经支持：

• 当前模型切换
• 切回继承默认模型
• 同步恢复入口
• 重建角色会话
• 打开原生接管口
• 复制恢复命令
• 复制接管命令

7. 当前 API

后端入口：

• D:\AI Code\Agents Team\server\src\index.ts

当前主要 API 已包括：

• 项目列表 / 项目详情
• 创建项目
• 保存团队草案
• 确认团队
• 确认团队变更
• 发起 / 确认项目摸底
• lead / 成员消息发送
• 创建任务
• 送审
• 复审
• reviewer 审查
• mailbox 发送 / 状态更新
• 写入共享记忆
• 会话模型切换
• 会话恢复
• 会话重建
• 打开原生接管口
• 人工接管记录

8. 现在还没做完的部分

还有这些尾项没有完全收口：

• 固定角色虽然已经支持按 thread 恢复，但还没做到“所有长期身份都只靠原生会话驱动”
• 页内还没有嵌入原生终端
• mailbox 摘要卡还能继续增强
• docs/ 里其它历史文档还没完全同步

9. 接下来最合理的方向

按当前进度，后面最值得继续推的是：

1. 继续收口角色长期身份，让更多长期动作都复用同一原生会话
2. 继续加强 mailbox 的长对话摘要和冲突压缩
3. 评估是否要做页内原生终端 / 更顺手的接管体验
4. 同步剩余设计 / 交接文档