Cortex 多代理协调协议
用纯 Markdown 文件让一个「幕僚长」代理调度一群工作代理。
- Star 数
- ★ 12
- 最近更新
- 5 个月前
- License
- MIT
- FA 评分
- 42/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台Claude CodeCodex · OpenAI API · Claude API（部分支持）
- 开始前需要
- 典型场景
- 你同时维护接单服务与仪表盘两个项目，想让一个幕僚长代理分别向 billing-dev、dashboard-dev 派活并在 Telegram 上收日报。
- 主要局限
- 开箱即用的插件路径绑定 Claude Code，非 Claude Code 用户需要自行按 docs/protocol.md 与 docs/adapters/ 写适配代码。
这个 Agent 能做什么，适合哪些场景？
Cortex 是一套开源协议，通过共享目录里的纯 Markdown 文件（带 YAML frontmatter）来协调多个 AI 代理。它自带一个 Claude Code 插件，包含 /setup、/register、/join、/leave 四个技能，但协议本身不依赖特定模型运行时，Codex、Cursor、Gemini CLI、OpenCode 等只要能读写文件都能接入。执行模型是「一个幕僚长 + 若干工作代理」：幕僚长接收你的指令，把任务写入 agents/<slug>/tasks.md，工作代理按心跳轮询任务文件，自行认领并汇报状态。代理之间不做直接通信，所有协调都经由团队目录完成，因此代理无需同时在线。
首次运行 /setup 会创建团队目录结构、写入 ~/.cortex/config.yaml 并注册幕僚长代理；/register <name> 在 <team_dir>/agents/<slug>/ 下生成代理笔记与空的 tasks.md；/join <name> 读取代理笔记，在当前项目生成 .cortex.md 完整协议文件，并更新 CLAUDE.local.md 使代理在会话启动时自动同步，同时启动心跳（默认每 15 分钟轮询）。任务文件遵循 ready → in-progress → done 状态机，附 Started/Completed 时间戳与 ### Summary 段落，格式沿用 Shuttle Protocol。幕僚长按 daily_briefing 与 daily_review 时间点发送简报，并通过 <!-- cortex:last-tick --> 存活时间戳识别疑似掉线但仍持有任务的代理；每日审查会清理 7 天前的 done 任务、把 Session Log 裁剪为每代理最新一条，历史内容由 git 保留。
- 你同时维护接单服务与仪表盘两个项目，想让一个幕僚长代理分别向 billing-dev、dashboard-dev 派活并在 Telegram 上收日报。
- 团队已有 Obsidian 笔记库，希望直接把 vault 当团队目录，用 Markdown 文件承载代理笔记与任务。
- 幕僚长用 Claude Code、工作代理用 Codex 或 Gemini CLI 的混合团队，通过 docs/adapters/ 的适配器让异构运行时协同。
- 工作代理无法与幕僚长同时在线，只能在夜间空闲时段执行任务，依赖文件队列异步取活。
- 想在任务文件中保留可审计的 assigned/started/completed 时间线，并借 git 提交历史追溯被清理的旧任务。
- 只想用终端或远程控制、不接 Telegram 的用户，用 /join 与心跳轮询完成无人值守的日常调度。
如何安装或部署这个 Agent？
本地克隆安装：
claude plugins marketplace add /path/to/cortex --scope user
claude plugins install cortex@agentweave从 GitHub 安装：
claude plugins marketplace add https://github.com/agentweave/cortex --scope user
claude plugins install cortex@agentweave市场名 agentweave 来自仓库中的 .claude-plugin/marketplace.json，该文件是插件被发现和安装的必要条件。安装完成后在 Claude Code 中运行 /setup，按提示填写团队目录路径（默认 ~/cortex-team）、Telegram chat ID（可选）、心跳间隔与每日日程时间。
如何使用这个 Agent？
在项目目录内加入成为某个代理：
/join Chief of Staff这会生成 .cortex.md 协议文件、更新 CLAUDE.local.md，并自动启动心跳（每 15 分钟轮询一次），每次会话重新运行 /join 时心跳会重启。注册并入职一个工作代理：
/register Billing Dev然后在工作代理的项目目录执行：
/join Billing Dev退出时用 /leave Billing Dev 删除 .cortex.md、清理 CLAUDE.local.md 并把该代理状态设为 inactive。配置文件 ~/.cortex/config.yaml 形如：
team_dir: ~/cortex-team
heartbeat_minutes: 15
daily_briefing: "09:00"
daily_review: "18:00"
telegram_chat_id: "your-chat-id"
chief_of_staff_project: "~/Projects/chief-of-staff"这个 Agent 有哪些优点和局限？
- 协调层是纯 Markdown 文件，任何能读写文件的运行时都能参与，Claude Code、Codex、Cursor、Gemini CLI、OpenCode 有官方适配器示例，可混编团队。
- 代理之间不直接通信，工作代理可以数小时后才取任务，不要求所有代理同时在线。
- 任务文件有明确的 ready → in-progress → done 状态机与 Started/Completed 时间戳，配合 git 提交历史可审计、可回溯被裁剪的旧数据。
- 用 <!-- cortex:last-tick --> 存活时间戳识别「有在办任务但已掉线」的代理，并提供每日审查自动清理 7 天前的 done 任务。
- MIT 许可，团队目录可用 Obsidian vault、git 仓库或任意目录，目录结构（agents/、projects/、templates/）清晰。
- 开箱即用的插件路径绑定 Claude Code，非 Claude Code 用户需要自行按 docs/protocol.md 与 docs/adapters/ 写适配代码。
- 采用「自己发提示词、自己收回复」的方式，缺少独立的守护进程；心跳依赖会话启动时运行 /join 才生效，会话不开就不轮询。
- Telegram 仅当作通知通道，且必须另装官方 Claude Code Telegram 插件，Cortex 自己只读取 telegram_chat_id。
- 多代理同时写同一任务文件存在并发覆盖风险，文档未描述锁或冲突解决机制。
- 配置文件 ~/.cortex/config.yaml 为全局单份，跨团队切换需要改动全局配置。
- 插件安装依赖 .claude-plugin/marketplace.json，仓库中其他运行时的适配器属于示例而非可安装产物。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Cortex 多代理协调协议 当前 | 42 · 缺口较多 | — | ★ 12 | 5 个月前 | — | Claude Code |
| RepoBrain 代码库智能问答引擎 | 49 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 1.3k | 17 天前 | Python | Codex · Claude Code |
| Brigade | 87 · 表现良好 | 命令行工具免费 | ★ 72 | 1 天前 | Python | — |
| AI 文档生成器（Divar） | 50 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 763 | 2 个月前 | Python | Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
README 明确说明代理之间不直接通信、全部通过共享 markdown 目录协调，数据流描述较清楚（data_flow_transparency=2）。但权限最小化仅停留在“文件读写”层面，未说明代理可执行命令、可访问路径或沙箱边界（least_privilege=1）；/setup、/register、/join 会创建目录、写入 ~/.cortex/config.yaml 并修改 CLAUDE.local.md，属于有副作用的操作，但未见任何确认或 dry-run 提示（user_confirmation=1）；Telegram chat ID 等配置被写入本地文件，未讨论敏感信息存储或脱敏（sensitive_data_handling=1）；心跳轮询、每日简报、自动删除 7 天前已完成任务等外部效应有描述但缺少同意与恢复机制（external_effects=1）；回滚仅依赖“团队目录应为 git 仓库、git log 保留历史”，未提供显式回滚流程（rollback=1）；仓库未提供依赖清单或锁文件，无法评估依赖安全（dependency_security=0）；来源归属仅指向 agentweave 与 Shuttle Protocol 链接，发布者身份未经验证（source_attribution=1）。
README 内部一致：协议、任务状态生命周期、slug 规则、目录结构相互吻合（self_consistency=2）。依赖可用性方面，安装依赖 Claude Code 插件市场与外部 Telegram 插件，且 docs/protocol.md、docs/adapters/ 等被引用的文件未在本次证据中出现，无法确认其存在（dependency_availability=1）。失败信息方面，仅提到“chief 检测到 stale agent 视为可能宕机”，没有错误码、日志或恢复指引（failure_messages=1）。
面向场景描述清晰，覆盖 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 及通用适配器（audience_and_scenarios=2）。能力边界只说明“不做代理间直接通信”，未界定代理可执行的操作范围或禁止事项（capability_boundaries=1）。触发精度方面，心跳 15 分钟、每日简报/评审时间可配置，但任务状态匹配规则较粗（trigger_precision=1）。环境适配较好，团队目录可为 Obsidian vault、git 仓库或任意目录，且支持混合运行时（environment_fit=2）。
信息架构清晰，README 分节合理，插件结构、目录结构、技能参考齐备（information_architecture=2）。安装说明具体，给出本地与 GitHub 两种 marketplace 安装命令（install_notes=2）。命名稳定性好，slug 派生规则有表格示例（naming_stability=2）。示例与 FAQ 仅有任务文件示例，缺少常见问题与故障排查（examples_and_faq=1）。已知限制完全未提及，例如并发写入冲突、markdown 解析歧义、多代理同时轮询的竞态（known_limitations=0）。MIT 许可证完整（license=2）。版本号在 package.json 中为 0.4.0，但无 CHANGELOG 或版本演进说明（versioning_changelog=1）。维护责任仅署名为 agentweave，无维护者联系方式或治理说明（maintenance_responsibility=1）。
输出可用性较好，任务文件格式、状态生命周期、简报机制都有具体示例，代理可直接消费（output_usability=2）。边际价值方面，用 markdown 文件做消息总线是轻量方案，但相比直接使用各运行时的任务编排能力，增量价值有限且未量化（marginal_value=1）。成本收益方面，需要维护团队目录、心跳轮询与每日评审，成本描述缺失，收益也未与替代方案对比（cost_benefit=1）。
主张可追溯性一般：README 声称“运行时无关”“混合团队开箱即用”，但支撑这些主张的 docs/protocol.md 与适配器文档未在证据中呈现（claim_traceability=1）。交叉来源印证有限，仅 README、LICENSE、package.json 三份文件，且 package.json 的 skills 列表与 README 技能描述基本一致，但无测试或代码佐证（cross_source_corroboration=1）。事实与推断分离尚可，README 区分了协议规范与实现细节，但“开箱即用”等表述属于未经验证的推断（fact_inference_separation=1）。
- 源码中未见：依赖安全审查安装前固定版本并做一次依赖扫描（如 npm audit、pip-audit）；优先放在容器里运行。
- 未提供依赖清单或锁文件，无法评估第三方依赖的安全性。
- 安装与初始化会写入 ~/.cortex/config.yaml 并修改 CLAUDE.local.md，但未见确认或 dry-run 机制。
- 自动删除 7 天前已完成任务、修剪会话日志等破坏性操作仅依赖 git 历史兜底，缺少显式回滚流程。
- README 引用的 docs/protocol.md 与 docs/adapters/ 未在证据中出现，运行时无关与混合团队等主张无法核实。
- 未讨论并发写入冲突、markdown 解析歧义或多代理轮询竞态等已知限制。
- 发布者身份未经验证，维护责任与更新路径不明确。