# 设计说明 更新时间: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. 同步剩余设计 / 交接文档