auxiliary-development

auxiliary-development 是一个本地仓库级 AI 开发流程控制工具。它不负责收集或整理原始需求，而是接收 requirements-refiner 已生成并审核完成的需求包，再控制 AI 进行代码现实分析、方案、实现、验证、评审和归档。

requirements-refiner 需求包
          ↓
需求包校验与冻结
          ↓
Flow 分类 → 代码现实分析 → 方案/计划 → 实现 → 验证 → 评审/归档

输入边界

唯一需求入口是：

requirement-package.json

auxiliary-development 不再：

• 连接或读取原始需求平台；
• 连接或读取原始设计平台；
• 生成资料获取配置；
• 保存上游平台的在线响应；
• 兼容旧的链接式 intake 参数。

需求正文和审核结论由 requirements-refiner 需求包提供；0.1.9 起 UI 只交接已审核链接，开发阶段按链接重新获取设计数据。

快速开始

使用一次性 npx 安装器安装 Codex Plugin，不全局安装 npm 包，也不向业务项目添加依赖：

npx auxiliary-development@latest

安装器会把完整 Plugin 原子复制到 $CODEX_HOME/auxiliary-development/marketplace/，注册 auxiliary-development Marketplace，并安装或更新同名 Plugin。安装完成后请完全退出并重新打开 Codex。

如果机器上安装过旧版全局 CLI，可在 Plugin 安装成功后手动执行 npm uninstall -g @xiaobao/auxiliary-development；安装器不会擅自修改全局 npm 环境。

然后在业务仓库中告诉 Codex：

使用 $auxiliary-development 接入 docs/requirements/示例需求/一期/requirement-package.json，需求编号 DEMAND-001，选择全部范围。

Plugin Skill 会调用内置 CLI，不依赖系统 PATH 中存在全局 auxiliary-development 命令。本文后续的 auxiliary-development ... 示例表示其内部 Action 协议，通常不需要开发者手工执行。

也可以只选择某个范围：

auxiliary-development start DEMAND-001 \
  --requirements-package docs/requirements/示例需求/一期/requirement-package.json \
  --select UC01

auxiliary-development start DEMAND-002 \
  --requirements-package docs/requirements/示例需求/一期/requirement-package.json \
  --select P1-UC01-FR001

支持完整需求编号、UCxx、COM、REQ 和 all。

安装器管理命令：

npx auxiliary-development@latest update
npx auxiliary-development@latest doctor
npx auxiliary-development@latest uninstall

需求包接入条件

接入时会检查：

• schemaVersion 是否受支持；
• requirement.reviewStatus 是否为 completed；
• 是否还有阻塞开发问题；
• guide、requirement index、详细需求文件是否存在；
• 选择器是否能匹配需求；
• 被选需求引用的 UI 来源是否存在且 developmentReady: true；
• UI 缓存、source map、渲染图索引和归档文件是否完整；
• 文件哈希与需求包指纹是否一致。

接入成功后，Change 中会生成：

docs/auxiliary-development/changes/<id>/
  package-check.json
  package-check.md
  input-package.json
  requirement-selection.json
  intake.md
  requirement-inventory.md
  requirement-matrix.md
  evidence.yml
  risks.md

input-package.json 是本次开发的冻结快照。需求包后续变化会触发漂移阻断，必须 replan 后重新接入。

首次 start 会按需创建 docs/auxiliary-development/。auxiliary-development 自身不会修改业务仓库的 package.json、锁文件、.gitignore、AGENTS.md、.agents/ 或 .github/；后续进入 implement 后，Coding Agent 仍可按批准的 Allowed files 修改业务源码和测试。

UI 和关键渲染图

UI 结构来自需求包 uiAnalysisSources[].links[]。Coding Agent 在 reality-check 前通过 MasterGo MCP 逐链接重新获取，只把业务摘要、设计差异和开发影响写入 ui-refetch.md，不保存原始 DSL 或节点响应。

使用需求包内已核对渲染图：

auxiliary-development visual-baseline DEMAND-001 --image /path/to/baseline.png

或使用明确提供的本地图片：

auxiliary-development visual-baseline DEMAND-001 --image ./baseline.png

完整视觉闭环：

auxiliary-development check DEMAND-001 --stage visual \
  --package-render UI-01-R001 \
  --url http://localhost:3000/page \
  --threshold 1%

会生成 baseline、actual、diff 和对应报告。

四种 Flow

| Flow | 用途 | 固定人工确认 | | --- | --- | --- | | direct-change | 明确、低风险的小改 | 无 | | focused-bugfix | 可复现的常规 Bug | 仅业务歧义时 | | focused-feature | 范围明确的小功能 | solution | | full-feature | 高风险、跨应用或高歧义需求 | requirement、solution、acceptance |

TDD、浏览器行为和视觉不是 Flow，它们由 Verification Plan 独立启用。

公共动作

start
chat
progress
approve
work
check
close
sync
doctor
automation
dev

常用流程：

start → chat 分类 → 必要决策/确认 → work → check → close

自然语言示例：

使用这个 requirement-package.json 开始需求。
继续。
确认当前方案和文件范围，确认人 chenshiwei。
为什么这个需求走当前流程？
检查需求到代码和验证有没有遗漏。
这次用了哪些 Skill、需求包、Context 和 Token？

“继续 / 可以 / 好 / OK”只表示查询下一步，不构成人工确认或实现授权。

目录

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

本分支不会创建仓库根 Agent 配置、docs/auxiliary-development/mcp/、.vscode/mcp.json 或其他资料获取配置。Codex/Copilot 参考资料也只保存在 docs/auxiliary-development/runtime/adapters/。

验证

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

详细说明见 开发者指南、架构 和 需求包适配合同。