Codex Team Collaboration Environment

最新调试结论见 AUDIT-2026-11-07.md。

本地优先的 Codex 多 Agent 协作环境，实现 Plan B：

• SQLite 任务图与依赖关系

• 原子认领、claim token 和 lease

• 每个 write 任务强制使用独立 Git worktree/branch

• 主 Agent 唯一终审和完成权限

• append-only 任务事件与团队消息

• Codex MCP stdio 服务

• 无外部依赖的本地 Web Kanban

两个仓库如何联动

本系统由两个独立仓库组成：

• RSmfOffice/codex-team-board：任务数据库、MCP、自动集群、worktree 和 Web 看板。

• RSmfOffice/codex-context-meter：跟随 Codex 的上下文监控插件；右键菜单可以 打开并自动拉起团队看板。

上下文插件通过以下顺序寻找面板：

1. %LOCALAPPDATA%\CodexContextMeter\config.json 中的 team_board_root。

2. 用户环境变量 CODEX_TEAM_BOARD_ROOT，兼容旧变量 CODEX_TEAM_ROOT。

3. %USERPROFILE%\plugins\codex-team-board。

4. %USERPROFILE%\CodexTools\codex-team-board。

5. 两个仓库位于同一父目录时的同级 codex-team-board。

6. %LOCALAPPDATA%\CodexTeamBoard。

面板安装器会写入 CODEX_TEAM_BOARD_ROOT 和 CODEX_TEAM_DASHBOARD_URL，因此 不要求两个仓库采用固定绝对路径。只要二者在同级目录，或插件安装时显式传入 -TeamBoardRoot，移动安装目录后仍能重新发现。

Related MCP server: synco-mcp

新机器完整安装

1. 前置条件

• Windows 10/11。

• Codex 桌面版、Codex CLI。

• Python 3.11+、PowerShell 5.1+。

• 上下文插件需要 Pillow：python -m pip install -r requirements.txt。

• 插件 MCP 需要 Node.js 18+。

• 自动 worktree 需要 Git。

2. 克隆两个仓库

推荐放在同一父目录：

$root = Join-Path $env:USERPROFILE "CodexTools"
New-Item -ItemType Directory -Force -Path $root | Out-Null
Set-Location $root
git clone https://github.com/RSmfOffice/codex-team-board.git
git clone https://github.com/RSmfOffice/codex-context-meter.git
python -m pip install -r .\codex-context-meter\requirements.txt

3. 一条命令安装并联动

Set-Location (Join-Path $env:USERPROFILE "CodexTools\codex-team-board")
powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\install.ps1 `
  -ContextMeterRoot (Join-Path $env:USERPROFILE "CodexTools\codex-context-meter")

安装器会：

1. 注册 codexTeamBoard MCP，并显式传入稳定的 CODEX_TEAM_HOME。

2. 安装全局角色、项目角色模板和团队协作 AGENTS 托管区块。

3. 安装 teamd watchdog，自动恢复 Lead/Worker 调度。

4. 启动 http://127.0.0.1:8765。

5. 调用上下文插件安装器，写入 team_board_root、注册个人 marketplace、 计划任务和插件。

安装完成后完全退出并重新打开 Codex。

4. 验证联动

Invoke-RestMethod http://127.0.0.1:8765/api/health
codex mcp get codexTeamBoard --json

预期看板健康响应包含 "service": "codex-team-board"。在 Codex 右侧点击上下文 悬浮窗右键，选择“打开 Codex 团队看板”；看板已运行时应直接打开浏览器，未运行 时应自动启动后打开。

单独安装

只安装面板：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

单独安装上下文插件时，显式告知面板路径：

Set-Location ..\codex-context-meter
powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\codex-context-meter-plugin\scripts\install.ps1 `
  -TeamBoardRoot ..\codex-team-board

不使用团队看板时：

powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\codex-context-meter-plugin\scripts\install.ps1 `
  -NoTeamBoardIntegration

上下文插件也可以通过 GitHub marketplace 安装：

codex plugin marketplace add RSmfOffice/codex-context-meter --ref v0.1.5
codex plugin add codex-context-meter@codex-tools

架构

主 Agent / Lead
  ├─ team_create_task
  ├─ team_create_worktree
  └─ team_review_task
          ↓
codexTeamBoard MCP
  ├─ SQLite 任务图 / 租约 / 审计
  └─ 本地 Web 看板
          ↓
team_explorer / team_worker / team_reviewer
  ├─ claim task
  ├─ work only in assigned worktree
  ├─ heartbeat
  └─ submit commit + tests to review

任务数据库默认位于：

%LOCALAPPDATA%\CodexTeam\team.sqlite

可通过 CODEX_TEAM_HOME 覆盖。

在 Windows 打包版 Codex 中，%LOCALAPPDATA% 可能被重定向到应用包缓存。 安装脚本会把实际解析后的 CODEX_TEAM_HOME 写入用户环境，并显式传给 CLI、 watchdog 和计划任务，确保它们始终连接同一个正式数据库。

初始化项目

只支持 Git 仓库。命令会注册项目、安装三个项目级角色，并向 AGENTS.md 写入托管协作规则，不覆盖原有内容。

.\scripts\team.ps1 init --repo "D:\path\to\repo"

当前安装的 Codex 0.157.1 提供原生 multi_agent，但尚未启用自动角色 TOML 加载。环境因此同时安装两层角色：

• ~/.codex/agents/*.toml：面向后续 Codex 版本的角色配置。

• .codex/team-roles/*.md：当前版本使用的便携 Prompt 包。

主 Agent 先调用 team_role_prompt，再把返回内容作为原生子 Agent 的 spawn prompt。这样不依赖当前版本尚未生效的 multi_agent_v2。

主 Agent 工作流

创建只读调研任务：

.\scripts\team.ps1 task create `
  --repo "D:\path\to\repo" `
  --title "梳理认证流程" `
  --description "定位入口、状态变化和风险" `
  --acceptance "返回文件、符号和调用链证据" `
  --kind read `
  --owner-role team_explorer

创建写作任务：

.\scripts\team.ps1 task create `
  --repo "D:\path\to\repo" `
  --title "实现登录修复" `
  --description "只在认证模块内修改" `
  --acceptance "回归测试通过且无未提交文件" `
  --kind write `
  --owner-role team_worker

为写作任务建立隔离工作区：

.\scripts\team.ps1 worktree create <task-id> --repo "D:\path\to\repo"

在此之前主 checkout 必须干净并位于命名分支。team init 生成的 AGENTS.md 和 .codex 文件应先由用户提交，保证每个 worktree 都包含团队规范。

Worker 认领：

.\scripts\team.ps1 task claim <task-id> --actor worker-auth

认领结果中的 claim_token 不能写入 Git、日志、任务描述或最终回复。Worker 在 指定 worktree 中完成修改、提交和测试后：

.\scripts\team.ps1 task submit <task-id> `
  --actor worker-auth `
  --token "<claim-token>" `
  --commit "<worker-commit>" `
  --result "修复了 token 刷新竞态" `
  --tests "pytest tests/auth -q: 42 passed"

自动集群的 Codex JSONL 日志会实时把 claim_token 字段替换为 [REDACTED]；作业结束时还会再次扫描日志和最终输出来清除遗漏值。

result 使用固定交接格式，避免信息遗漏：

行为：
变更文件：
验证：
风险：
Review 重点：
待决问题：

查看任务交接事件：

.\scripts\team.ps1 task events <task-id>

主 Agent 合并分支、运行集成测试后：

.\scripts\team.ps1 task review <task-id> `
  --actor lead `
  --approve `
  --notes "Review 和集成测试通过" `
  --merge-commit "<main-merge-commit>"

write 任务审批时系统会检查：

• worktree 仍然存在；

• worktree 没有未提交文件；

• merge_commit 能在主仓库解析；

• merge_commit 已包含在创建任务时固定下来的目标分支中，不受当前 checkout 切换影响。

可视化看板

.\scripts\dashboard.ps1

浏览器打开 http://127.0.0.1:8765。看板每 2 秒刷新，只读展示：Ready、 Running、Review、Blocked、Done 泳道，以及依赖、租约、分支、worktree、审计结果、 交接事件和团队消息。所有写入仍通过 MCP 或 CLI 完成。

也可以双击根目录的 启动Codex团队看板.cmd。

看板只显示已经通过 codexTeamBoard MCP 或 team.ps1 task create/ cluster start 写入任务图的任务。普通 Codex 对话和原生子 Agent 不会自动变成 看板任务；如果预期有任务但页面为空，先检查 /api/board 的 tasks 数量和 CODEX_TEAM_HOME 是否指向同一数据库。

项目与任务归档

归档按钮会根据当前上下文切换目标：

• 没有打开任务详情时：归档或恢复当前项目。

• 打开任务详情时：归档或恢复当前任务。

• 先关闭任务详情，按钮才会切回项目归档。

项目和任务都采用软归档：

• 默认的“所有活动项目”视图会隐藏归档项目、归档任务及其消息。

• 勾选“显示已归档”后可以重新查看，按钮会切换为“恢复当前项目”或 “恢复当前任务”。

• 归档不会删除数据库记录、任务事件、worktree、分支或合并提交。

• 有未结束的集群目标、Running 任务或活动 Agent 进程时禁止归档。

• 已归档任务不能 claim；已归档项目不能创建任务、cluster goal 或 worktree， 恢复后解除限制。

MCP 工具

• team_init_project

• team_status

• team_list_roles

• team_role_prompt

• team_create_task

• team_list_tasks

• team_get_task

• team_get_task_events

• team_create_worktree

• team_list_worktrees

• team_claim_task

• team_heartbeat

• team_update_task

• team_submit_task

• team_block_task

• team_unblock_task

• team_review_task

• team_add_message

• team_list_messages

状态规则

ready → running → review → done
   ↘ blocked ↗        ↘ ready（拒绝）

• 有未完成依赖时不能 claim。

• 一个任务同一时间只有一个有效 claim。

• claim 超过 lease 后可被重新领取。

• write 任务没有 worktree 时不能 claim。

• Worker 不能将任务直接标记 done。

• 只有 lead、main 或 human 可以终审。

自动 Agent 集群

启动一个持续目标：

.\scripts\team.ps1 cluster start `
  --repo "D:\path\to\repo" `
  --objective "实现并验证目标，自动拆分、执行、测试和验收" `
  --autonomy auto

常驻 teamd 会：

• 首次启动受管 Lead 线程，由 Lead 拆任务。

• 自动为 ready 任务启动 Worker，并创建 write worktree。

• Worker 异常退出后回收任务并按上限重试。

• Lead 进程中断后优先 resume 同一 thread；连续失败后新建 Lead generation， 用 board 状态恢复。

• 所有 task 完成后自动关闭 goal。

• supervised 模式只自动执行到 Review，不自动合并。

Codex 的 workspace-write 沙箱会把 .git/ 递归设为只读，即使工作区其他位置 可写。因此：

• write Worker 和 auto 模式 Lead 使用 danger-full-access，以便执行 git commit、合并和验收。

• 只读调研与普通 Review Worker 继续使用 workspace-write。

• 这只应运行在可信的本地项目和由 teamd 分配的隔离 worktree 中。

• 项目初始化是幂等的；未显式传入 --max-threads 时保留已有配置，不会因为 Lead 再次确认项目而把干净 checkout 改脏。

相关官方说明： Protected paths in writable roots。

查看和停止：

.\scripts\team.ps1 cluster list
.\scripts\team.ps1 cluster status <goal-id>
.\scripts\team.ps1 cluster pause <goal-id>
.\scripts\team.ps1 cluster resume <goal-id>
.\scripts\team.ps1 cluster cancel <goal-id>

优先注册 Windows 计划任务 Codex Team Cluster，每 5 分钟检查一次 daemon。 如果计划任务注册被系统策略拒绝，安装器会退回到用户级启动 watchdog：

HKCU\Software\Microsoft\Windows\CurrentVersion\Run\CodexTeamClusterWatchdog

watchdog 每分钟调用 ensure-cluster-daemon.ps1，并通过命名互斥量防止重复实例。 它不需要管理员权限；Windows 询问是否允许 PowerShell 开机启动时，这一项就是 自动恢复组件。拒绝启动不会破坏当前会话，但登录后不会自动拉起 teamd。

测试

$env:PYTHONPATH = ".\src"
python -m unittest discover -s tests -v

发布包

powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-release.ps1

输出位于 dist\codex-team-board-v0.2.0.zip，同时生成 SHA256 文件。GitHub Release 应附带 ZIP 与 .sha256 两个资产。