auxiliary-development

auxiliary-development 是一个 Codex Plugin，用于把 requirements-refiner 已整理、审核并确认可开发的需求包，转换为受需求事实、文件范围、人工确认和验证结果约束的 AI 开发流程。

它不是需求收集工具，也不是安装到业务项目中的 npm 开发依赖。日常使用入口是 Codex 对话中的 $auxiliary-development，不是终端里的全局 auxiliary-development 命令。

口述、需求文档或设计稿
          ↓
requirements-refiner 整理与审核
          ↓
requirement-package.json
          ↓
$auxiliary-development 接入目标代码仓库
          ↓
需求包校验 → 代码现实分析 → 技术方案 → 授权实现 → 验证 → 评审归档

1. 安装或升级

以下命令在终端执行，只负责管理 Codex Plugin：

# 首次安装
npx auxiliary-development@latest

# 升级已安装的 Plugin
npx auxiliary-development@latest update

# 检查安装状态
npx auxiliary-development@latest doctor

# 卸载
npx auxiliary-development@latest uninstall

安装器会把 Plugin 部署到 $CODEX_HOME/auxiliary-development/marketplace/，注册并安装 auxiliary-development Plugin。它不会：

• 全局安装业务流程 CLI；
• 修改业务项目的 package.json 或锁文件；
• 把 auxiliary-development 添加为业务项目依赖。

安装或升级完成后，请完全退出并重新打开 Codex，再开始使用。

2. 准备需求包

auxiliary-development 的唯一需求输入是 requirements-refiner 生成的：

requirement-package.json

建议使用 requirements-refiner 0.1.10 或更高版本。需求包必须满足：

requirement.reviewStatus = completed
developmentReadiness.ready = true

也就是说，口述小需求、无设计需求、只有设计稿的需求以及需求与设计稿冲突，都要先由 requirements-refiner 整理和审核。auxiliary-development 不会在开发阶段替用户补写、猜测或修改业务规则。

示例：先在 Codex 中整理一个口述需求：

使用 $requirements-refiner 整理下面这个小需求：
把订单列表的“提交时间”改成“创建时间”。

确认需求范围和验收标准，并完成上游审核后，再把生成的 requirement-package.json 交给 auxiliary-development。

3. 在目标代码仓库中开始开发流程

在 Codex 中打开真正需要修改的业务代码仓库，然后发送：

使用 $auxiliary-development 接入
/绝对路径/requirement-package.json。

需求编号：DEMAND-001
选择范围：all

请先校验需求包、分析代码现实并生成技术方案，暂时不要修改业务代码。

推荐使用需求包的绝对路径，避免在不同工作目录中找错文件。

也可以只选择需求包中的部分范围：

使用 $auxiliary-development 接入 /绝对路径/requirement-package.json。
需求编号：DEMAND-002。
只处理 UC01，先分析，不修改代码。

支持的选择方式包括：

| 选择器 | 含义 | | --- | --- | | all | 选择所有本期需求 | | UC01 | 选择某个用例下的需求 | | P1-UC01-FR001 | 选择一个完整需求编号 | | COM | 选择公共需求 | | REQ | 选择 P*-REQ-* 类型需求 |

正常用户不需要手工执行 auxiliary-development start ...。Plugin Skill 会通过内置包装器调用同一版本的流程 CLI；npm 暴露的 npx auxiliary-development@latest 是安装器入口，不是业务开发入口。

4. 接入时会检查什么

接入前会只读检查：

• 需求包 schema 是否受支持；
• reviewStatus 是否为 completed；
• developmentReadiness.ready 是否为 true；
• 本期范围是否已确认；
• 本期需求事实是否均为已确认状态；
• 引导文档是否覆盖全部本期需求；
• 是否还有影响开发或验收的待确认问题；
• requirement index、引导文档和详细需求文件是否完整；
• 选择器是否能匹配有效需求；
• 被选需求引用的 UI 精确链接是否已登记；
• 包内路径、文件哈希和需求包指纹是否一致。

link-only-refetch 新需求包不应该保存 MasterGo DSL、节点树、UI 缓存、source map 或渲染图索引。旧 UI 工件仅作为历史需求包的只读兼容输入。

检查失败时不会创建半成品 Change，也不会修改业务代码。应该回到 requirements-refiner 修正并重新审核需求包，而不是手工伪造 ready 字段。

5. 接入后会生成什么

首次接入会在目标仓库创建：

docs/auxiliary-development/
  changes/DEMAND-001/
    package-check.json
    package-check.md
    input-package.json
    requirement-selection.json
    selected-requirements.json
    selected-requirements.md
    intake.md
    requirement-inventory.md
    requirement-matrix.md
    evidence.yml
    risks.md

如果本次需求引用 UI 链接，还会生成：

ui-refetch.md
ui-refetch-evidence.json

其中：

• input-package.json 是本次接入的需求包冻结快照；
• selected-requirements.json/md 是技术方案唯一允许使用的完整业务事实来源；
• requirement-matrix.md 记录需求、来源和覆盖关系；
• ui-refetch.md 记录当前设计摘要、与已审核需求的差异和开发影响；
• ui-refetch-evidence.json 记录需求包指纹、精确 URL、获取能力、时间、返回计数和摘要哈希。

需求包之后发生变化会触发漂移阻断，必须重新规划并重新接入。不要直接修改冻结快照或 fingerprint。

6. UI 需求怎么处理

如果需求包声明 uiHandoff.strategy=link-only-refetch，Coding Agent 会在代码现实分析前：

1. 只读取需求包已经登记并审核的精确 UI 链接；
2. 优先通过 MasterGo getDesignSections 逐链接重新获取；
3. 该能力失败时才使用 getDsl；
4. 只保存业务摘要、设计差异、开发影响和机器证据；
5. 不保存原始 DSL、节点树、分区响应、token 或临时下载地址。

链接失效、权限不足、MCP 缺失或最新设计与已审核需求发生漂移时，流程保持阻塞，不会自行采用新设计或改变需求。

没有设计稿不会自动阻塞非视觉需求。此时技术方案必须明确写明“无 UI 来源”，复用项目现有组件与规范，但不能自行创造业务行为或无证据的视觉参数。

需要像素级视觉比较时，由用户另外提供明确的本地 PNG：

为 DEMAND-001 使用 /绝对路径/baseline.png 作为视觉基准，
实现后对 http://localhost:3000/page 执行视觉验证。

7. 分析、确认和实现

接入后可以直接询问：

查看 DEMAND-001 当前进度、Flow、阻塞项、技术方案和下一步。

检查 DEMAND-001 的需求事实、代码分析和技术方案中是否存在无来源推断。

用户说“生成技术方案”后，流程固定执行：

1. 自动判断需求包、开发就绪度、选择范围、完整需求事实和未决问题。
2. 未就绪时只询问阻断问题；就绪时直接生成技术方案。
3. 有设计链接时，在方案会话中按链接调用 MasterGo 查看设计。
4. 方案有疑问时集中询问；没有疑问时只问“技术方案已生成，是否执行代码？”。
5. 用户同意后，有设计链接的需求在实施会话再次调用 MasterGo；设计无漂移才开始编码。

四种 Flow 都必须先有合法需求包，并且都不能绕过需求事实、需求包漂移、适用的 UI 重取和文件范围门禁。Flow 只调节分析和验证强度，不再增加 requirement、acceptance 或岗位人工会签。

用户明确回复“执行代码”“开始实现”，或在上述唯一询问后回复“是/可以”，即可授权实施，不要求再提供确认人：

执行代码。

普通“继续”仍只查询下一步；只有当前明确停在“是否执行代码”时，肯定回复才会授权。实现阶段发现设计漂移、范围扩大、接口缺失、需求与代码现实冲突、需要修改禁止文件或验证失败时，流程会停止并进入 replan，不会静默改变方案。

8. 验证和归档

实现完成后，可以要求 Plugin 按 Verification Plan 执行适用验证：

对 DEMAND-001 执行适用的构建、TDD、Browser、Visual 和 Review 检查，
列出每项证据以及未通过原因。

TDD、Browser 和 Visual 是独立验证维度，不是额外 Flow：

• 业务规则、可复现 Bug、权限、状态机和可复用逻辑优先执行 TDD；
• 点击、请求、响应、焦点和状态反馈通过 Browser 验证；
• 明确的布局、样式和视觉还原要求通过 Visual 验证；
• 文字或局部非视觉改动不会无条件要求全部验证。

验证完成后由 AI reviewer 核对需求覆盖、代码和适用的视觉证据；通过后自动进入确定性收口，不再要求人工验收或归档确认：

完成 DEMAND-001 的验证、评审和归档，并告诉我真实结果。

9. 常用对话

使用 $auxiliary-development 接入 /绝对路径/requirement-package.json，
需求编号 DEMAND-001，选择 all，先分析不要写代码。

查看 DEMAND-001 当前进度和下一步。

为什么 DEMAND-001 被分类为当前 Flow？

为什么当前门禁没有通过？给出对应文件和真实失败原因。

检查需求到代码、技术方案和验证矩阵是否有遗漏或无依据扩展。

这次实际使用了哪些 Skill、需求事实、Context 和验证证据？

10. 目录边界

auxiliary-development 自身的状态、方案、报告和验证证据写入：

docs/auxiliary-development/
  changes/          每个需求的状态、方案、门禁和验证证据
  knowledge/        项目知识和组件映射
  prompts/          阶段提示模板
  skills/           项目运行时 Skill 参考
  runtime/          执行器同步、上下文和诊断报告
  policy.yml        范围与验证策略

接入和分析阶段不会修改业务仓库的 package.json、锁文件、.gitignore、AGENTS.md、.agents/ 或 .github/。获得实现授权后，Coding Agent 只能按批准的 Allowed files 修改业务源码和测试。

11. 常见问题

| 问题 | 处理方式 | | --- | --- | | Codex 找不到 $auxiliary-development | 运行 npx auxiliary-development@latest doctor，必要时 update，然后完全重启 Codex | | reviewStatus 不是 completed | 回到 requirements-refiner 完成审核 | | developmentReadiness.ready 不是 true | 解决待确认范围、事实、覆盖或问题，再重新生成需求包 | | 选择器没有匹配 | 使用 all、UC 编号或 requirement index 中的完整需求 ID | | UI 链接失效或无权限 | 修复 MasterGo 链接/权限并回到上游确认，不能绕过证据 | | 设计重新获取后发生变化 | 停止开发，更新并重新审核需求包后再接入 | | 需求包 fingerprint 改变 | 进入 replan，重新接入新需求包 | | 没有设计稿 | 非视觉需求可以继续；不得自行补充业务规则或视觉参数 | | 只有口述需求 | 先通过 requirements-refiner 生成最小需求包 |

12. 维护者说明

Plugin 内部稳定 Action 包括 start、chat、progress、approve、work、check、close、sync 和 doctor。这些 Action 由 $auxiliary-development Skill 的内置包装器调用，不要求用户安装全局 CLI。

仓库开发与发布前验证：

npm run build
npm run check:types
npm run check:engine-unused
npm run check:core-unit
npm run smoke:requirement-package
npm run smoke:docs-boundary
npm run smoke:visual
npm run smoke
npm run release:check

更多内部协议见开发者指南、架构说明和需求包适配合同。