viettran-edgeAI/codex_workflow

codex_workflow – 面向 Codex 的 Token 高效代理编排

它是什么

一个基于 Python 的工作流包，扩展了 Codex AI 助手（“Codex CLI/app”），提供结构化的多代理执行模式。用户可以选择 light、medium 或 heavy 路径，每条路径定义了产生多少个子代理（Explorer、Investigator、Executor、Tester、Archivist 等）以及它们如何共享上下文。
该工作流将项目级记忆存储在 agent_docs/ 文件夹中，在会话之间保留目标、架构决策、进度笔记和交接摘要。

为什么重要

大型语言模型代理按 token 计费。通过将工作委派给专门的子代理并批量处理其结果，codex_workflow 减少了主代理的 token 消耗，同时仍然支持复杂多步骤任务。
它提供了一种可复现的“群”模式，可以在许多项目中重用，而无需编写自定义编排代码。

快速开始（安装）

下载 GitHub Releases 页面中的最新发布 zip。
使用提供的 SHA256SUMS 文件验证下载。
解压归档，按照随附的 codex_workflow/operate/bootstrap.md 说明操作（通过 archivist 子代理创建 agent_docs/ 框架）。
重新启动 Codex 应用程序。

现在，您可以从任何项目目录运行：

codex_workflow --install   # 为该项目设置工作流

要求 – Python 3.11+ 以及可用的 Codex CLI/应用安装。

如何使用工作流

路径	何时选择	功能
Light	简单的问答、快速修复	没有额外的子代理；主 Codex 代理直接回答。
Medium	需要研究或文档但主代理仍应实现/验证的任务	生成 Explorer（搜索）、Investigator（深入分析）和 Archivist（笔记记录）。主代理负责编码/验证。
Heavy	大型跨学科项目（例如，前端设计、3D 可视化、广泛测试）	在 Medium 栈上添加 Executor 和 Tester。主代理只进行编排、综合报告和最终决策。

切换路径 – 在 Codex 聊天中输入：

use medium route. <你的任务描述>

或者将 medium 替换为 heavy。所选路径在更改前一直有效。

运行命令 – 该工作流附带一个小型 CLI 包装器：

codex_workflow --install      # 为当前项目设置
codex_workflow --check-update # 检查是否有较新版本
codex_workflow --update       # 升级工作流
codex_workflow --remove       # 彻底卸载
codex_workflow --version      # 显示安装的版本

核心功能

持久项目记忆 – agent_docs/ 自动记录目标、架构、决策、进度和交接。
Token 感知批处理 – 内置启发式规则（自 v1.1.3 起）限制主代理生成工作者的频率，减少重复的上下文 token。
并行子代理 – 最多三个工作者可以同时运行（Codex 平台将会话限制为总共 4 个代理）。
证据链接报告 – 工作者返回简洁的摘要，引用完整的日志/工件，保持主代理的上下文较小。
高级执行器回退 – 对于特别困难的问题，可以自动调用更高容量的执行器。
会话结束 Token 统计 – 每次运行后，您会获得每个代理使用 token 的细分。
可自定义策略文件 – 全局设置位于 ~/.codex/AGENTS.md；项目级覆盖与 agent_docs/ 一起存储。

基准与性能

仓库包含一个 light benchmark，展示了批处理指南如何减少主代理的缓存输入 token（最大的成本驱动因素）。提供了视觉分析（light_benchmark/analysis.png）和扩展基准的提案。

限制与注意事项

该工作流依赖于 Codex 平台当前的 四个并发代理 限制；在不更改平台的情况下，更大规模的群是不可能的。
Heavy 路径的任务会消耗更多总体 token，因为更多子代理处于活动状态，尽管主代理的生成被削减。
安装过程需要手动下载 zip 资产并验证；目前还没有 pip 风格的安装程序。
Token 节省启发式规则是根据作者的实验调整的；结果可能因不同的 LLM 提供商或模型版本而异。

了解更多

完整架构、生命周期和安全说明：workflow_breakdown.md
基准想法以及如何贡献新测试：benchmarks/README.md
代理生命周期细节：codex_workflow/agent_lifecycle.md

结论 – codex_workflow 是一个即用型编排层，让 Codex 高级用户能够运行多代理、token 高效的流水线，从快速回答到重量级开发项目，同时自动维护项目级知识库。