Codex Agent Legion 实现原理与 GitHub 使用指南两件事Codex Agent Legion 整体是怎么实现的。别人从 GitHub 拿到这个项目以后应该怎么安装、运行和接入自己的任务。项目地址https://github.com/ergou-yu/codex-agent-legion在线说明页https://ergou-yu.github.io/codex-agent-legion/这个项目到底是什么Codex Agent Legion 不是一个在线服务也不是一个真正会自动启动很多 agent 的后台系统。它更像一个本地调度控制台你输入一个任务它根据任务内容判断这个任务是否需要拆给子 agent。需要几个子 agent。应该选 explorer、worker、reviewer还是外部候选 agent。哪些事情必须留给主 Codex 自己做。最后生成哪些 prompt 和 JSON 计划文件。它的核心产物不是“直接执行结果”而是一份可检查、可审计、可交给 Codex 继续执行的调度计划。整体运行流程没有有用户输入任务CLI 解析参数读取 config/legion.roster.json识别任务信号判断复杂度和风险是否传入自定义算法使用默认启发式调度加载 decide(context)规范化算法输出生成 dispatch plan写入 logs/runs//生成 dispatch-plan.json生成 dispatch-request.json渲染 prompts/*.md一次命令大概是这样nodetools/legionctl.js plan帮我分析这个项目并修复构建失败--jsonCLI 会把任务变成一组结构化信号比如domains: 任务属于代码、研究、浏览器、数据、文档、审查、工作流还是运维。complexity:simple、standard、complex或epic。risk_flags: 是否涉及密钥、登录态、发消息、付款、生产写入等风险。requested_agent_count: 用户有没有明确要求几个 agent。然后它用这些信号决定要不要拆任务以及拆给谁。核心文件怎么分工1.tools/legionctl.js这是项目的核心 CLI。它主要做这些事parseArgs: 解析命令行参数比如plan、doctor、--json、--algorithm。detectDomains: 从任务文字里识别任务领域比如代码、文档、数据、浏览器、审查。detectRiskFlags: 判断任务是否涉及敏感动作。inferComplexity: 根据任务长度和领域数量推断复杂度。targetAgentCount: 根据复杂度、风险和用户显式要求决定子 agent 数量。heuristicPlan: 默认调度策略选择 explorer、worker、reviewer 或外部候选 agent。loadAlgorithm: 加载用户自定义的调度算法文件。normalizeAlgorithmPlan: 把自定义算法输出整理成统一格式。buildPlan: 生成最终dispatch-plan.json。writeRunArtifacts: 写入 plan、request 和 prompt 文件。doctor: 检查项目文件、配置、候选 agent、密钥风险和基本健康状态。也就是说这个项目的实现重点不是复杂框架而是把“任务判断 - agent 选择 - 计划生成 - prompt 输出”这条链路做成稳定的本地工具。2.config/legion.roster.json这是军团名册也是调度策略的配置中心。里面定义了commander 是谁。commander 能做什么不能委托什么。默认最多允许几个并行 agent。敏感任务最多允许几个 agent。内置 Codex agent 有哪些。外部开源 agent 候选有哪些。每个 agent 对应哪个 prompt 模板。默认 commander 是{id:codex-gpt55-commander,runtime:codex,model:gpt-5.5}默认策略是保守的优先用 Codex 内置子 agent。外部 agent 默认只是候选不会自动启动。reviewer 通常放在实现之后的后置波次。涉及敏感操作时减少 delegation。3.prompts/*.md这里放的是不同角色的 prompt 模板。例如prompts/commander.md: 主 Codex 的总控提示。prompts/explorer.md: 负责读上下文和定位边界。prompts/worker.md: 负责明确范围内的实现。prompts/reviewer.md: 负责检查风险和测试缺口。prompts/browser.md: 浏览器任务候选模板。prompts/data.md: 数据任务候选模板。prompts/workflow-runtime.md: 长链路工作流候选模板。运行army-plan后工具会把任务、分工、范围、禁止事项和验收标准填进这些模板生成可以交给 Codex 或外部 agent 的任务包。4.schemas/*.json这里定义机器可读的数据契约。dispatch-request.schema.json: 输入请求的结构。task-plan.schema.json: 调度计划的结构。agent-result.schema.json: 子 agent 回传结果的结构。review-finding.schema.json: reviewer 发现问题的结构。这些 schema 的意义是以后你接入自己的调度算法时不需要猜 CLI 要什么格式直接按合同输出即可。5.scripts/army-*这些是更顺手的入口脚本。常用的是scripts/army-plan你的任务scripts/army-doctor它们内部还是调用tools/legionctl.js只是比每次写node tools/legionctl.js ...更适合日常使用。6.examples/custom-algorithm.sample.js这是自定义调度算法示例。你以后可以写自己的decide(context)让它决定应该选哪些 agentasyncfunctiondecide({task,request,roster,signals}){return{strategy:my-algorithm-v1,selected_agents:[{id:codex-explorer,role:Explorer,reason:先读仓库结构和风险边界,count:1},{id:codex-reviewer,role:Reviewer,reason:最后检查计划和测试缺口,count:1}]};}module.exports{decide};运行nodetools/legionctl.js plan分析这个项目的架构--algorithm./my-algorithm.js--json为什么 reviewer 要放在后面这个项目里一个很重要的默认设计是reviewer 不和 worker 放在同一个执行波次里。原因很简单实现还没完成时reviewer 很容易看到半成品然后给出不稳定的结论。这里默认把实现 agent 放在前一波把 reviewer 放在后一波让它审查已经形成的 diff、计划或输出。在dispatch-plan.json里会看到类似结构{parallel_groups:[[codex-worker],[codex-reviewer]]}这表示 worker 先做reviewer 后审。从 GitHub 怎么用方式一直接 clone 仓库运行适合想看源码、改配置、接入自己算法的人。gitclone https://github.com/ergou-yu/codex-agent-legion.gitcdcodex-agent-legionnpmtest生成一个调度计划scripts/army-plan帮我审查这个项目的发布风险--json或者nodetools/legionctl.js plan帮我审查这个项目的发布风险--json查看健康状态scripts/army-doctor输出会在logs/runs/timestamp-slug/里面通常包含dispatch-plan.json dispatch-request.json prompts/commander.md prompts/agent.md方式二从 GitHub Release 安装本地命令适合只想用命令不想改源码的人。下载 release 包curl-L-ocodex-agent-legion-0.1.0.tgz\https://github.com/ergou-yu/codex-agent-legion/releases/download/v0.1.0/codex-agent-legion-0.1.0.tgz全局安装npminstall-g./codex-agent-legion-0.1.0.tgz安装后可以直接用army-plan给这个仓库做一次代码审查--jsonarmy-doctor legionctl plan整理一个发布计划方式三在自己的项目旁边使用假设你的项目在~/work/my-project你可以把 Codex Agent Legion 单独 clone 到另一个目录gitclone https://github.com/ergou-yu/codex-agent-legion.gitcdcodex-agent-legion然后用任务描述明确告诉它目标项目scripts/army-plan请为 ~/work/my-project 做一次构建失败排查计划需要先读项目结构再安排实现和审查--json它会生成调度计划和 prompt。真正执行时主 Codex 根据生成的 plan 去对应项目里读代码、分配子任务、运行验证。一次真实输出长什么样运行scripts/army-plan给这个仓库做一次代码审查--json可能得到{strategy:conservative-heuristic,commander:codex-gpt55-commander,model:gpt-5.5,domains:[code,review],complexity:standard,selected_agents:[{id:codex-worker,role:Code Worker,count:1,runtime:multi_agent_v1},{id:codex-reviewer,role:Reviewer,count:1,runtime:multi_agent_v1}]}这不是最终代码改动而是告诉主 Codex这个任务属于代码和审查。复杂度是标准。可以拆给一个 worker 和一个 reviewer。reviewer 应该作为后置检查而不是和 worker 同时抢同一份文件。怎么改成自己的版本你最可能改这几个地方改 agent 名册编辑config/legion.roster.json可以新增 agent、减少外部候选、调整最大并行数量或者改变敏感任务的 agent 上限。改 prompt 模板编辑prompts/*.md如果你希望 worker 更严格、reviewer 更挑剔、explorer 输出更短就改这里。接自己的调度算法新建一个文件比如my-scheduler.js导出module.exports{asyncdecide(context){return{strategy:my-scheduler,selected_agents:[{id:codex-explorer,role:Explorer,reason:先读上下文,count:1}]};}};然后运行nodetools/legionctl.js plan你的任务--algorithm./my-scheduler.js当前边界这个项目目前做的是“计划生成”和“任务包生成”不是完全自动执行器。也就是说它会告诉你应该调用哪些 agent。它会生成 prompt 和 JSON 计划。它会检查配置和明显密钥风险。它不会自动拿你的账号去启动外部工具。它不会自动写生产数据库。它不会绕过主 Codex 的最终验收。这个边界是故意保留的。因为多 agent 系统真正容易出问题的地方往往不是“不会调用”而是“调用太多、边界不清、没人验收”。Codex Agent Legion 的核心价值就是把边界、数量、角色和验收写清楚。