Codex Control

本项目是一个围绕 Codex 使用方式进行开发、编排与验证的控制项目。当前包含 Operit 侧的 Codex Control 插件，以及用于约束任务路由和审计流程的 Skills；后续计划将 Codex Control 插件移植到 PC 平台，采用 MCP + skill 的形式提供本机 Codex 控制能力。

通过 Operit 持久终端会话间接控制本机 Codex CLI 的插件（ToolPkg）+ 配套 Skill（codex-audit）。

codex-control/
├── plugin/                 # Codex Control ToolPkg（安装到 Operit）
│   └── codex-control/      #   manifest.json + src/ + dist/
└── skills/                 # 配套 Skill（安装到 Operit skills/）
    ├── codex-audit/        #   中文工程编排：13 模式 + 12 模板 + Agent 元数据
    └── codex-use/          #   英文 Codex 路由 Skill，按复杂度委派 Terra / Sol

项目路线

• 当前形态：Operit ToolPkg 通过持久终端会话投递和查询 Codex CLI 任务，codex-audit 负责调用边界、审计和实施状态机。
• Codex 使用策略：主执行 Agent 不绑定具体模型或供应商，应低成本、快速，适合清晰、重复和高吞吐工程工作；只有架构设计、复杂根因、跨文件审计等需要专家判断时，才创建短生命周期的 Terra / Sol 子任务。codex-use 保持英文，codex-audit 默认使用中文。
• 后续目标：将 Codex Control 插件移植到 PC 平台，使用 MCP 暴露控制能力，并用 skill 提供任务路由、上下文压缩、模型选择和验证规范。

codex-audit 与 codex-use Skill

项目内的 skills/codex-audit/ 是中文工程编排 Skill，包含：

• SKILL.md：模型无关的主执行策略、专家升级门、coding 授权门、验证和 Git/发布边界。
• agents/openai.yaml：Skill 展示信息和默认提示词。
• modes/：coding、diagnose、review_plan、implementation_plan、architecture_review、verification、knowledge_extraction、code_review、regression_analysis、incident_response、security_audit、migration_review、performance_analysis，共 13 种模式。
• templates/：共 12 个中文报告模板。

13 个模式对应 12 个模板是有意设计：diagnose 与 security_audit 共享 templates/audit-report.md，因为二者都使用“范围 → 证据 → 发现 → 结论 → 剩余不确定性”的证据化报告骨架，专项要求分别写在各自的模式文件中，不是漏文件。

项目内的 skills/codex-use/ 是保持英文的独立 Codex Skill，提供同样的 13 模式 / 12 模板架构。两个 Skill 都可独立安装；codex-audit 的任务、报告和面向用户结果默认使用中文，codex-use 继续使用英文。

在 Codex 中可用 $codex-audit 或 $codex-use 显式调用；复制到其他 Skill 目录时，请保持对应技能目录名。

背景与设计

Operit 的 ToolPkg 运行于 QuickJS 宿主（非 Node），无法直接使用 child_process 执行 Codex CLI。本插件通过 Operit 持久终端会话（terminal.create + terminal.input）投递 codex exec --json 任务：投递后立即返回 task_id，任务在终端会话中后台运行，codex_status 轮询状态文件查询进度。

为什么不用 hiddenExec：实测 hiddenExec 可被长/取消调用污染（残留 proot+bash 坏会话、跨重启残留、全局挂起）。本插件完全使用 visible 持久 terminal session（方案 X），不触碰 hiddenExec。

插件（plugin/codex-control）

工具

工具	说明
codex_run	启动或 resume 一个 Codex 任务。project 必须命中白名单（CME/CMS 逻辑名），model/reasoning 白名单校验；投递到持久 codex-control 会话后立即返回 task_id
codex_status	查询任务状态：idle/running/completed/failed，含 task_id/project/started_at/finished_at/exit_code/report/session_id。session_id 是 Codex thread id（可用于 resume_session）；任务运行中也能从 stdout.jsonl 提取
test_terminal_call	诊断：验证 ToolPkg 内调用 Operit terminal 与人工终端环境一致

安装

1. 将 plugin/codex-control/ 放入 Operit 开发目录，或用 debug_install_toolpkg 烧录（source_path 指向该目录）。
2. 在 Operit 中启用 codex_control 子包。

项目白名单

只接受逻辑项目名，不接受任意路径：

逻辑名	目录
CME	/root/projects/CME
CMS	/root/projects/CMS

模型白名单：gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna；reasoning 白名单：low/medium/high/xhigh/max。

任务存储

• 状态文件：/root/.operit-codex/tasks/<task_id>/{prompt.txt, result.json, stdout.jsonl, stderr.log}
• 任务正文通过 prompt.txt 文件通道传递，不进入 Shell 命令行；runner 从 ToolPkg resource 原子部署到 /root/.operit-codex/runner.sh。
• resume_session 仅接受标准 UUID；task_id 仅接受插件系统生成格式（兼容历史 1–4 位序号）。
• 错误码：PROJECT_NOT_ALLOWED / MODEL_NOT_ALLOWED / REASONING_NOT_ALLOWED / INVALID_RESUME_SESSION / INVALID_TASK_ID / EMPTY_TASK / SESSION_UNAVAILABLE / BUSY / INTERNAL_ERROR
• 注意：顶层 success 恒为 true（Operit 工具层把 success:false 当 Step error），用 ok:false + code 表达错误。

开发

cd plugin/codex-control
npm install        # typescript + @types/node（仅开发期）
tsc -p tsconfig.json

Skill（skills/codex-audit）

codex-audit 是配合本插件的中文工程编排 Skill。主执行 Agent 不绑定具体模型或供应商，定位为低成本、快速，适合清晰、重复和高吞吐工程工作；只有专家能力确有价值时，才通过 Codex Control 调用 Terra 或 Sol。

安装：将 skills/codex-audit/ 放入 Operit skills/ 目录（目录名与 SKILL.md 的 name 一致：codex-audit）。

工作模式

共 13 种模式：

mode	用途	是否允许修改源码
coding	用户明确授权后的复杂编码	是，仅授权范围
diagnose	复现故障、定位根因、区分证据与假设	否
review_plan	依据需求、决策和代码事实评审已有方案	否
implementation_plan	把已确认决策转换成可验证工程任务	否
architecture_review	评审架构是否满足目标与约束	否
verification	验证原始问题是否真的解决	否
knowledge_extraction	将已验证报告沉淀为工程知识	默认否
code_review	审查 commit、branch、PR 或 patch	默认否
regression_analysis	分析变更对非目标区域的影响	否
incident_response	生产事故响应与事故复盘	仅按授权执行
security_audit	审查认证、注入、路径穿越和信任边界	否
migration_review	评审数据、API、架构或平台迁移	否
performance_analysis	定位性能瓶颈并制定复测计划	否

模式与模板

当前有 12 个中文报告模板。diagnose 与 security_audit 有意共享 templates/audit-report.md，因为二者都使用“范围 → 证据 → 发现 → 结论 → 剩余不确定性”的证据化报告骨架，专项要求分别由各自模式文件约束，不是漏文件。

13 个模式 - 2 个模式共享 1 个模板 = 12 个模板

使用顺序与授权

常规顺序：

diagnose → review_plan（可选）→ architecture_review（可选）
→ implementation_plan → 用户确认 → coding
→ code_review → verification → regression_analysis
→ knowledge_extraction

用户一开始明确要求实施范围清晰的修改时，可以直接进入 coding。只读模式不修改源码；即使 coding 已授权，未经额外授权也不 commit、不 push、不烧录、不发布。

codex-audit 的任务、报告和面向用户的结果默认使用中文。

License

MIT