面向 Codex 的生产级自主编程飞控：先把需求变成可持续文档，再把大目标拆成可验证的 Wave，以机械门禁、持久状态、一层子代理和动态战术指导约束长期开发。
作者：showjiangnan
Codex Flight Control（Codex 编程飞控）不是另一个会替代模型思考的任务清单，也不依赖 Codex Goal Mode。模型仍负责理解问题、规划、编码、调试和纠错；插件负责保存跨轮次事实、 限定下一步动作、校验权限与证据，并在模型偏航时把执行拉回已确认的开发路线。
当前版本为 0.16.4（P16-R4）。macOS arm64 上的本地工程证据已达到
ENGINEERING_READY；它尚不是正式公开 Release Candidate，详见
当前发布事实和
开源准备状态。
复杂软件项目很少因为“模型不会写代码”而失败，更多时候是因为：
- 需求仍然模糊，却过早进入实现；
- 长任务在多轮上下文中丢失目标、边界或历史决定；
- 大目标没有被拆成适合当前模型能力的小步；
- 子代理遇到困难后继续猜测，造成错误扩散；
- “测试通过”“工作完成”等结论只来自模型自报；
- 多个任务在同一项目中相互污染运行状态；
- 自动化拥有超出当前任务所需的权限。
飞控为这些问题建立一条确定性的控制链：
模糊想法
→ Discovery Wave
→ 用户确认的持续文档工程
→ MissionSpec + Verification Manifest
→ 顺序 Wave / 原子 Slice
→ 一层子代理 + 战术指导信箱
→ HOST_EXECUTED Evidence
→ Completion Gate
→ 本地 commit
每次接管项目时，插件先评估当前文档工程。空白或稀疏项目可以先通过
$flight-brainstorm 建立产品愿景、范围、非目标、架构方向、验收标准、风险和开发计划；
成熟项目则在原有文档体系附近兼容补充，不覆盖已存在的手写事实源。业务代码写入必须
绑定一份当前、完整且状态为 READY 的文档快照。
头脑风暴不是一次聊天总结，而是四个顺序 Discovery Wave：
| Wave | 解决的问题 | 主要产物 |
|---|---|---|
FRAMING |
做什么、为谁做、解决什么问题 | Intent Canvas |
VALUE |
核心场景、价值与成功指标 | 方案卡片、对比矩阵 |
BOUNDARIES |
范围、非目标、安全、数据、成本与风险 | 边界和风险清单 |
ENGINEERING |
架构方向、验证方式与开发命令 | 工程基线与验证计划 |
插件可显示网络隔离的 MCP App Workbench；宿主不支持 UI 时，同一状态机仍通过结构化文本 工作。任何选项都必须由用户选择，模型不能替用户确认。
Flight Progression Engine 是 Mission 的唯一推进权威。它从持久状态派生唯一的下一 Action，并通过 exact Action Gateway 执行；模型不能自行跳过 Wave、伪造状态、替换 参数或调用被隐藏的写工具。Codex Goal 不会被启用、镜像或作为第二套完成状态。
大目标按 Wave 顺序推进，同一 Run 同时最多一个活动 Wave。Wave 再拆成路径、命令、 预期产物和验证条件都被冻结的原子 Slice。所有 Worker 都是 Lead 的直接子节点，禁止 形成失控的嵌套代理树；只有 Gateway 返回经过签名的 spawn envelope 时，宿主才会创建 一个子代理。
Worker 遇到关键事实缺失或连续失败时，不得继续猜测。它会提交一个脱敏 Problem Capsule 并原子让出当前 Attempt。Tactical Advisor 从本地持久信箱领取请求，结合当前 Wave 的 冻结合同和匹配到的 Private Skill 返回有界建议。没有匹配 Skill 时，指导者可以基于 模型能力给出建议，也可以明确弃权或升级给 Lead。
Private Skill 不是会话开始时全部注入的全局提示，而是只在困难节点按角色、任务类型和 当前 Wave 快照动态路由。它只能由用户显式选择以下一种来源创建：
- GitHub 仓库：安全 clone 到独占临时目录后，从本地快照熔炼；
- 本机 Codex Skill：只读派生，绝不修改、移动或删除原 Skill；
- 当前任务、指定任务或结构化导出物：只提取可观察、可验证的会话证据。
候选 Skill 会经历隔离、审查、影子验证和生命周期控制；插件不会自动把普通会话总结成 Skill，也不会自动安装成全局 Skill。
格式、类型、单元、集成、恢复、安全和验收义务会被编译进 Verification Manifest。
只有宿主在受限执行边界中真实运行冻结命令产生的 HOST_EXECUTED Evidence，才能满足
Completion Gate。模型自报成功和子代理报告都不能替代证据。
首次使用会验证本地 main；缺失时只安全创建本地基线，不移动已有 main。写入 Wave
在插件托管 worktree 和 codex/flight-* 分支中执行，完成后只创建可恢复的本地 commit。
插件永不自动 push、创建 PR、发布、merge 或删除用户 worktree。
运行时绑定 Codex 根任务线程，而不只绑定工作区。同一项目中新开一个 Codex 任务，会得到 独立的飞控运行域，不会继承或干涉旧任务的 Run、Discovery、Guidance、credential 或 幂等范围；resume/compact 只恢复同一根任务的持久状态。
关键提示使用统一的简体中文弱模型微协议，明确角色、当前事实、唯一动作、必须输入、 禁止事项、成功判据和停止条件。生产连接默认只暴露 8 项 Bootstrap 工具；完整 81 项 工具注册表会按状态投影成最小 Surface。顺序、版本、权限、用户确认和完成条件均由 SQLite/MCP 机械校验，不能靠模型理解力自觉遵守。
插件提供不上传数据的本地诊断、只读 Flight Cockpit、恢复检查点、内容寻址的大型仓库 索引，以及需要用户精确授权的不可变维护计划。诊断会省略绝对路径、prompt、源码正文、 Private Skill、bearer 和授权 token。
仓库不提交可重建的 dist/ bundle，因此从源码安装前需要先构建。支持的运行时合同为
Node.js >=22.22.0 <23 || >=24.19.0 <25，开发基准为 Node.js 24.19.0、
npm 12.0.2。
git clone https://github.com/showjiangnan/codex-flight-control.git
cd codex-flight-control/code/codex-flight-control
npm install --global npm@12.0.2
npm ci
npm run build随后在仓库根目录创建一个本地 marketplace 清单 .agents/plugins/marketplace.json：
{
"name": "codex-flight-control-source",
"interface": {
"displayName": "Codex Flight Control Source"
},
"plugins": [
{
"name": "codex-flight-control",
"source": {
"source": "local",
"path": "./code/codex-flight-control"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}再把该本地 marketplace 加入 Codex 并安装插件：
codex plugin marketplace add .
codex plugin add codex-flight-control@codex-flight-control-source安装或更新后，请新建一个 Codex 任务，使新的 Skill、MCP 工具和 Hook 在干净的任务边界
加载。若 codex 不在 PATH，可使用 Codex App 自带的 CLI 可执行文件执行相同命令。
当前仓库是私有源码仓库时，其他用户还需要相应的 GitHub 读取权限。正式发行版应通过 经验证的 marketplace/package 工件安装，而不是要求最终用户构建源码；发布流程仍在 发布准备清单中跟踪。
拉取新版本后重新执行：
cd code/codex-flight-control
npm ci
npm run build
codex plugin add codex-flight-control@codex-flight-control-source如果 Codex 仍命中旧缓存，应按项目的 本地插件更新流程生成开发 cachebuster 后再 重新安装，并从新任务验证安装态。
在项目目录中新建 Codex 任务，显式输入：
$flight-brainstorm
描述你的初步想法，然后逐轮选择模型给出的 2–3 个实质性选项。飞控会完成四个
Discovery Wave，展示最终文档预览，并在你明确确认后物化 D0 文档工程。它不会在这个
流程中创建 Run 或业务代码。文档达到 DOCUMENTATION_READY 后，在新的输入中调用：
$flight-control
在项目目录中新建 Codex 任务，描述本次目标并显式输入：
$flight-control
飞控将先扫描项目和文档，建立或验证本地 main 基线，再从当前 READY 文档编译
MissionSpec 与 Verification Manifest。后续只按 Engine 返回的唯一 Action 推进，直到
完成门禁通过、需要用户决策或出现可证明的安全阻断。
输入：
$flight-diagnose
插件会生成有界的本地健康报告，并依据当前证据解释 runtime、文档、Run、Wave、 Guidance、Private Skill、角色策略、Evidence、Git 和恢复状态。诊断只读，不会为了让 报告“看起来完整”而创建或修改状态。
| Skill | 何时使用 | 调用方式与关键边界 |
|---|---|---|
$flight-control |
文档已明确，需要接管、继续、修复或完成复杂开发 | 主推进入口；可隐式匹配，但建议显式调用；只走 Engine/Gateway |
$flight-brainstorm |
项目空白、需求模糊或方向重大变化 | 必须显式调用；只创建文档，不启动 Run、不写业务代码 |
$flight-diagnose |
查询健康、阻断原因或恢复建议 | 只读、本地、脱敏，不自动修复 |
$flight-configure-roles |
查看、设置或重置角色模型策略 | 变更必须显式授权，仅影响未来 Run |
$flight-forge-github |
从一个 GitHub 仓库熔炼项目私有战术 | 必须显式调用；安全 clone 到临时目录，不执行仓库代码 |
$flight-forge-local-skill |
从选定的本机 Skill 派生私有战术 | 只读来源，保留原 Skill |
$flight-forge-session |
从当前/指定任务或导出物提炼私有战术 | 只使用可观察证据，不读取 Codex 私有 transcript 存储 |
$flight-approve-verification |
人工判断无法由命令证明的验收项 | 精确语法：<run_id> <entry_id> <APPROVE|REJECT> |
$flight-control-run |
暂停、恢复或取消指定 Controller | 精确语法：<run_id> <controller_id> <version> <PAUSE|RESUME|CANCEL> |
$flight-connect-host |
为指定 Run 启用/关闭可选 App Server 续航 | 精确语法：<run_id> <thread_id> <ENABLE|DISABLE>；没有新鲜 sandbox 证明时保持 POLL_ONLY |
$flight-maintain |
应用已经封存且用户审阅过的本地维护计划 | 精确语法：<plan_id> <plan_hash>；任何漂移立即停止 |
每个 Skill 的完整协议位于
code/codex-flight-control/skills/。
一个 Run 会冻结十类角色的模型策略：Wave Planner、Explorer、Worker、Verifier、 Integrator、Tactical Advisor、Documentation Engineer、Skill Forger、Skill Reviewer 和 Recovery Agent。当前默认全部为：
model: gpt-5.6-sol
reasoning_effort: max
on_unavailable: block
Fast 由根任务的 Host priority service tier 提供，不是子代理 spawn 参数。用户可以用
$flight-configure-roles 设置用户级或项目级稀疏覆盖；插件会先通过宿主 Model Catalog
验证 model ID 和 reasoning effort，配置无效时失败关闭，不会静默换成另一个模型。
- 不实现或调用 Computer Use；该能力属于未来独立插件；
- 不自动创建 Private Skill，三种熔炼方式都需要用户显式选择；
- 不建立嵌套子代理树；
- 不把聊天文本、模型置信度或 Agent report 当作完成证据；
- 不在日志、诊断、prompt 或 commit 中暴露一次性 credential；
- 不上传诊断或遥测；
- 不自动 push、PR、tag、Release、publish、merge 或修改远端；
- 不移动已有
main，不修改用户主 worktree 的 dirty 文件； - 不把 Codex Goal 作为核心推进状态；
- 宿主能力、sandbox、Hook、配置或迁移证明缺失时失败关闭。
进一步阅读：
.
├── code/codex-flight-control/
│ ├── .codex-plugin/ # 插件 manifest
│ ├── src/ # TypeScript 源码
│ ├── tests/ # 单元、集成、恢复与负向测试
│ ├── scripts/ # 确定性工程门禁
│ ├── skills/ # 11 个控制 Skill
│ ├── hooks/ # 8 类 Hook 配置
│ ├── migrations/ # SQLite schema 1–16
│ ├── assets/ # Discovery Workbench 与 Flight Cockpit
│ ├── schemas/ # 配置与公共数据合同
│ ├── release/ # 发布、风险、提示词和复杂度机器合同
│ └── evals/ # 弱模型行为评估语料
└── docs/ # 产品、架构、ADR、安全、质量、运维与发布文档
安装依赖并运行完整门禁：
cd code/codex-flight-control
npm ci
npm run check
npm run real-host:checknpm run check 覆盖格式、lint、严格类型、测试与覆盖率、构建、简体中文提示门禁、MCP
smoke、真实 manifest 启动、1200 行结构上限、包 allowlist、文档、许可证依赖、秘密、
风险映射、可重复构建、性能、模型 Eval 和依赖漏洞审计。当前基线为 542 项确定性测试、
3 项 opt-in 真实宿主测试、87 项 CRITICAL 风险机器证据和 64 文件安装包合同。
本 GitHub 仓库只保存可维护源码、测试、脚本、配置、插件资源和完整文档；dist/、
source map、coverage、node_modules/、缓存、临时包和本机运行态不提交。发布或本地安装
前由 npm run build 确定性重建 dist/，再由包/安装门禁验证产物。
开发与贡献入口：
已验证的是本地工程证据，不等于已经承诺全部平台和公开发行。目前仍需完成：
- 项目许可证选择；
- 真实目标模型 campaign；
- macOS x64、Linux x64 和 Windows x64 候选证据；
- 正式公开支持范围与 Hook trust 验证；
- 项目所有者的 go/no-go。
因此，请把当前仓库视为可审查、可构建的生产级开发版本，而不是已经完成公开发布的稳定 发行版。