Apex Workflow是一个可配置的工作流框架，通过仓库感知设置、切片清单、MCP/GitNexus路由、追踪器集成和验证门控等机制，为Codex和LLM编程代理提供可靠的工程化软件开发流程。

Apex Workflow：为LLM编程代理构建的工程化控制平面\n\n## LLM编程代理的困境\n\n近年来，基于大语言模型（LLM）的编程代理如GitHub Copilot、Codex等正在改变软件开发的方式。然而，这些代理在实际工程实践中常常面临一个根本性问题：它们并非因为"不会写代码"而失败，而是因为缺乏"工程纪律"。\n\n具体表现为：代理在尚未阅读权威文档的情况下就开始搜索代码；将共享模块当作本地辅助函数随意修改；在修改过程中丢失对当前工作范围的跟踪；将截图视为代码审查的充分证据；跳过问题追踪器的状态更新或创建无意义的工单。结果是，每次会话结束后，代码库留下的是混乱的修改树和半遗忘的对话记录，下一个会话不得不从脏状态开始重建上下文。\n\n## Apex Workflow的解决方案\n\nApex Workflow正是为了解决这些问题而设计的。它是一个可移植的工作流框架，能够将任意代码仓库转变为"代理可操作"的系统。通过安装应用特定的工作流配置文件，Apex为代理提供了一个模式/状态机，并在代码被触碰之前将每个有意义的切片记录在清单中。\n\n这种设计带来的不是模糊的"我修改了一些文件"的自动化，而是受控的工程实践：已知的权威文档、明确的作用域所有权、显式的禁止触碰区域、代码智能检查、聚焦的验证机制，以及清晰的下一步安全切片。\n\n## 架构设计与核心组件\n\nApex Workflow的架构可以分为几个层次：\n\n控制平面层：apex-workflow仓库本身提供了初始化脚本、配置检查工具、诊断工具、清单管理脚本以及核心技能文档。\n\n目标应用层：安装后，目标仓库会获得AGENTS.md中的托管配置块、apex.workflow.json配置文件、临时工作目录以及仓库文档/契约/测试。\n\n代理技能层：$apex-workflow代理技能提供了模式选择器、清单纪律管理、契约与路由门控，以及完成包交接机制。\n\n外部智能与操作层：通过适配器连接到GitNexus MCP、GitNexus包装器回退、Linear/GitHub/文件追踪器、代理浏览器和聚焦源代码搜索等外部工具。\n\n## 九步工作流模式\n\nApex定义了一个严格的九步工作流，代理必须按顺序执行：\n\n第一步：定向（Orient）\n代理首先读取AGENTS.md、apex.workflow.json和权威文档，建立对仓库结构和规则的理解。\n\n第二步：选择模式（Select Mode）\n根据任务性质选择合适的工作模式：微型修复（tiny）、本地路由（route-local）、共享表面（shared-surface）、问题恢复（issue-resume）、规划（planning）或协调（reconciliation）。\n\n第三步：打开切片清单（Open Slice Manifest）\n明确声明拥有的文件、禁止触碰的表面和需要执行的检查。\n\n第四步：编辑前路由（Route Before Edit）\n查阅所有者文档、契约、状态和调用者信息。\n\n第五步：影响检查（Impact Check）\n通过GitNexus MCP或回退机制分析变更的潜在影响范围。\n\n第六步：编辑（Edit）\n在声明的作用域内进行窄范围实现。\n\n第七步：验证（Verify）\n执行路径范围内的测试、代码检查、类型检查、构建验证，必要时提供浏览器证据。\n\n第八步：检测作用域（Detect Scope）\n将变更文件和受影响流程与清单进行比较。\n\n第九步：完成包（Finish Packet）\n生成交付报告，包括已落地、已验证、未验证、风险点和下一步安全切片。\n\n## 六种工作模式详解\n\nApex的六种模式覆盖了不同的开发场景：\n\n微型模式（tiny）：适用于单一已知文件、低爆炸半径的简单修复。直接读取文件，进行路径范围内的检查即可。\n\n本地路由模式（route-local）：适用于单一所有者且有明确调用者的场景。需要清单、所有者文档和聚焦验证。\n\n共享表面模式（shared-surface）：适用于修改共享的shell、store、hook、auth、workspace等表面。需要契约、影响分析和禁止触碰清单。\n\n问题恢复模式（issue-resume）：适用于从命名追踪器问题或脏状态继续工作的场景。需要获取最新状态，识别第一个真正的缺口，禁止扩大范围。\n\n规划模式（planning）：适用于产品/设计/架构在编码之前的阶段。在有用时生成持久的决策产物。\n\n协调模式（reconciliation）：适用于代码已落地，剩余工作是审查/追踪器/审计的场景。生成证据包，不再重新打开代码流程。\n\n## MCP优先与回退机制\n\nApex采用MCP（Model Context Protocol）优先策略。当配置GitNexus时，配置文件优先使用gitnexus_query、gitnexus_context、gitnexus_impact等MCP工具。\n\n如果MCP由于主机配置、运行时问题、陈旧重载或本地存储问题而失败，Apex会记录一个包装器回退。该回退通过仓库本地命令暴露相同的意图，如npm run gitnexus:status、npm run gitnexus -- impact 等。\n\n这种设计确保了MCP是干净路径，而包装器是生存路径。配置文件会分别记录配置偏好、检测到的仓库支持、当前主机可用性和回退命令就绪状态。\n\n## 安装与配置\n\n安装Apex时，用户需要回答一个关键问题：是自动从仓库证据配置，还是选择追踪器/GitNexus/浏览器选项？\n\n自动模式命令：\n\nnpm run init -- --target=/path/to/app --config-mode=auto --yes\n\n\n自定义模式允许指定追踪器（如Linear）、代码智能工具（如gitnexus-mcp）、浏览器工具等。\n\n安装器会写入apex.workflow.json，向目标仓库的AGENTS.md添加托管Apex块，验证配置文件，并在本地Codex技能目录中创建$apex-workflow技能的符号链接。\n\n## 配置文件结构\n\napex.workflow.json是目标应用与代理之间的契约，示例结构如下：\njson\n{\n \"authority\": {\n \"productTruth\": [\"PRD.md\"],\n \"executionTruth\": [\"ROADMAP.md\"],\n \"workflowRules\": [\"AGENTS.md\"]\n },\n \"tracker\": {\n \"provider\": \"linear\"\n },\n \"codeIntelligence\": {\n \"provider\": \"gitnexus-mcp\",\n \"wrapperFallback\": {\n \"enabled\": true\n }\n },\n \"manifest\": {\n \"defaultDir\": \"tmp/apex-workflow\"\n }\n}\n\n\n它告诉代理什么是产品真相、工作流规则、使用哪个追踪器、GitNexus是通过MCP还是包装器运行、契约文档的位置、哪些检查重要，以及浏览器证据应如何处理。\n\n## 诊断与验证\n\n在第一次实现切片之前，应针对目标仓库运行诊断工具：\n\nnpm run doctor -- --target=/path/to/app --config=apex.workflow.json\n\n\n诊断工具会检查未解决的设置审查项、猜测的推断路径、tmp/apex-workflow/是否被忽略、托管AGENTS.md块、适配器就绪性、本地技能符号链接，以及安装的设置是否具有干净的基线检查点。\n\n## 总结与意义\n\nApex Workflow代表了LLM编程代理从"能写代码"向"能进行工程化开发"演进的重要一步。通过引入严格的流程控制、作用域管理和验证机制，它为AI辅助软件开发建立了可重复、可审计、可维护的工程纪律。\n\n随着AI编程工具的普及，类似Apex这样的工作流框架将成为企业级应用开发的必备基础设施，确保AI代理在提升效率的同时，不会牺牲代码质量和工程规范。

Apex Workflow：为LLM编程代理构建的工程化控制平面\n\nLLM编程代理的困境\n\n近年来，基于大语言模型（LLM）的编程代理如GitHub Copilot、Codex等正在改变软件开发的方式。然而，这些代理在实际工程实践中常常面临一个根本性问题：它们并非因为"不会写代码"而失败，而是因为缺乏"工程纪律"。\n\n具体表现为：代理在尚未阅读权威文档的情况下就开始搜索代码；将共享模块当作本地辅助函数随意修改；在修改过程中丢失对当前工作范围的跟踪；将截图视为代码审查的充分证据；跳过问题追踪器的状态更新或创建无意义的工单。结果是，每次会话结束后，代码库留下的是混乱的修改树和半遗忘的对话记录，下一个会话不得不从脏状态开始重建上下文。\n\nApex Workflow的解决方案\n\nApex Workflow正是为了解决这些问题而设计的。它是一个可移植的工作流框架，能够将任意代码仓库转变为"代理可操作"的系统。通过安装应用特定的工作流配置文件，Apex为代理提供了一个模式/状态机，并在代码被触碰之前将每个有意义的切片记录在清单中。\n\n这种设计带来的不是模糊的"我修改了一些文件"的自动化，而是受控的工程实践：已知的权威文档、明确的作用域所有权、显式的禁止触碰区域、代码智能检查、聚焦的验证机制，以及清晰的下一步安全切片。\n\n架构设计与核心组件\n\nApex Workflow的架构可以分为几个层次：\n\n控制平面层：apex-workflow仓库本身提供了初始化脚本、配置检查工具、诊断工具、清单管理脚本以及核心技能文档。\n\n目标应用层：安装后，目标仓库会获得AGENTS.md中的托管配置块、apex.workflow.json配置文件、临时工作目录以及仓库文档/契约/测试。\n\n代理技能层：$apex-workflow代理技能提供了模式选择器、清单纪律管理、契约与路由门控，以及完成包交接机制。\n\n外部智能与操作层：通过适配器连接到GitNexus MCP、GitNexus包装器回退、Linear/GitHub/文件追踪器、代理浏览器和聚焦源代码搜索等外部工具。\n\n九步工作流模式\n\nApex定义了一个严格的九步工作流，代理必须按顺序执行：\n\n第一步：定向（Orient）\n代理首先读取AGENTS.md、apex.workflow.json和权威文档，建立对仓库结构和规则的理解。\n\n第二步：选择模式（Select Mode）\n根据任务性质选择合适的工作模式：微型修复（tiny）、本地路由（route-local）、共享表面（shared-surface）、问题恢复（issue-resume）、规划（planning）或协调（reconciliation）。\n\n第三步：打开切片清单（Open Slice Manifest）\n明确声明拥有的文件、禁止触碰的表面和需要执行的检查。\n\n第四步：编辑前路由（Route Before Edit）\n查阅所有者文档、契约、状态和调用者信息。\n\n第五步：影响检查（Impact Check）\n通过GitNexus MCP或回退机制分析变更的潜在影响范围。\n\n第六步：编辑（Edit）\n在声明的作用域内进行窄范围实现。\n\n第七步：验证（Verify）\n执行路径范围内的测试、代码检查、类型检查、构建验证，必要时提供浏览器证据。\n\n第八步：检测作用域（Detect Scope）\n将变更文件和受影响流程与清单进行比较。\n\n第九步：完成包（Finish Packet）\n生成交付报告，包括已落地、已验证、未验证、风险点和下一步安全切片。\n\n六种工作模式详解\n\nApex的六种模式覆盖了不同的开发场景：\n\n微型模式（tiny）：适用于单一已知文件、低爆炸半径的简单修复。直接读取文件，进行路径范围内的检查即可。\n\n本地路由模式（route-local）：适用于单一所有者且有明确调用者的场景。需要清单、所有者文档和聚焦验证。\n\n共享表面模式（shared-surface）：适用于修改共享的shell、store、hook、auth、workspace等表面。需要契约、影响分析和禁止触碰清单。\n\n问题恢复模式（issue-resume）：适用于从命名追踪器问题或脏状态继续工作的场景。需要获取最新状态，识别第一个真正的缺口，禁止扩大范围。\n\n规划模式（planning）：适用于产品/设计/架构在编码之前的阶段。在有用时生成持久的决策产物。\n\n协调模式（reconciliation）：适用于代码已落地，剩余工作是审查/追踪器/审计的场景。生成证据包，不再重新打开代码流程。\n\nMCP优先与回退机制\n\nApex采用MCP（Model Context Protocol）优先策略。当配置GitNexus时，配置文件优先使用gitnexus_query、gitnexus_context、gitnexus_impact等MCP工具。\n\n如果MCP由于主机配置、运行时问题、陈旧重载或本地存储问题而失败，Apex会记录一个包装器回退。该回退通过仓库本地命令暴露相同的意图，如npm run gitnexus:status、npm run gitnexus -- impact 等。\n\n这种设计确保了MCP是干净路径，而包装器是生存路径。配置文件会分别记录配置偏好、检测到的仓库支持、当前主机可用性和回退命令就绪状态。\n\n安装与配置\n\n安装Apex时，用户需要回答一个关键问题：是自动从仓库证据配置，还是选择追踪器/GitNexus/浏览器选项？\n\n自动模式命令：\n\nnpm run init -- --target=/path/to/app --config-mode=auto --yes\n\n\n自定义模式允许指定追踪器（如Linear）、代码智能工具（如gitnexus-mcp）、浏览器工具等。\n\n安装器会写入apex.workflow.json，向目标仓库的AGENTS.md添加托管Apex块，验证配置文件，并在本地Codex技能目录中创建$apex-workflow技能的符号链接。\n\n配置文件结构\n\napex.workflow.json是目标应用与代理之间的契约，示例结构如下：\njson\n{\n \"authority\": {\n \"productTruth\": [\"PRD.md\"],\n \"executionTruth\": [\"ROADMAP.md\"],\n \"workflowRules\": [\"AGENTS.md\"]\n },\n \"tracker\": {\n \"provider\": \"linear\"\n },\n \"codeIntelligence\": {\n \"provider\": \"gitnexus-mcp\",\n \"wrapperFallback\": {\n \"enabled\": true\n }\n },\n \"manifest\": {\n \"defaultDir\": \"tmp/apex-workflow\"\n }\n}\n\n\n它告诉代理什么是产品真相、工作流规则、使用哪个追踪器、GitNexus是通过MCP还是包装器运行、契约文档的位置、哪些检查重要，以及浏览器证据应如何处理。\n\n诊断与验证\n\n在第一次实现切片之前，应针对目标仓库运行诊断工具：\n\nnpm run doctor -- --target=/path/to/app --config=apex.workflow.json\n\n\n诊断工具会检查未解决的设置审查项、猜测的推断路径、tmp/apex-workflow/是否被忽略、托管AGENTS.md块、适配器就绪性、本地技能符号链接，以及安装的设置是否具有干净的基线检查点。\n\n总结与意义\n\nApex Workflow代表了LLM编程代理从"能写代码"向"能进行工程化开发"演进的重要一步。通过引入严格的流程控制、作用域管理和验证机制，它为AI辅助软件开发建立了可重复、可审计、可维护的工程纪律。\n\n随着AI编程工具的普及，类似Apex这样的工作流框架将成为企业级应用开发的必备基础设施，确保AI代理在提升效率的同时，不会牺牲代码质量和工程规范。