@gong-ym/ai-spec-auto 0.2.3

package/.agents/roles/INDEX.md

@@ -0,0 +1,346 @@
+---
+id: roles-display-index
+name: 角色展示名索引
+version: 1
+description: 供插件页面读取的角色展示索引。优先解析下方的 yaml 数据块。
+---
+
+# 角色展示名索引
+
+这份索引用于统一角色展示层数据，避免插件页面逐个扫描所有角色文件。
+
+当前统计：
+
+- `active` 角色：21 个
+- `planned` 候选角色：13 个
+
+插件页面建议优先解析下面的 `yaml` 数据块。
+
+## index-data
+
+```yaml
+version: 1
+domains:
+  - id: orchestration
+    name: 任务编排层
+    order: 0
+    visibility: internal
+  - id: demand-design
+    name: 需求设计域
+    order: 1
+    visibility: public
+  - id: governance
+    name: 规范治理域
+    order: 2
+    visibility: public
+  - id: engineering
+    name: 工程构建域
+    order: 3
+    visibility: public
+  - id: testing
+    name: 测试验证域
+    order: 4
+    visibility: public
+  - id: delivery
+    name: 发布交付域
+    order: 5
+    visibility: public
+  - id: documentation
+    name: 文档知识域
+    order: 6
+    visibility: public
+  - id: performance
+    name: 性能体验域
+    order: 7
+    visibility: public
+  - id: observability
+    name: 可观测治理域
+    order: 8
+    visibility: public
+  - id: security-a11y
+    name: 安全与可访问性域
+    order: 9
+    visibility: public
+
+roles:
+  - id: task-orchestrator
+    name: 任务主代理
+    status: active
+    bucket: common
+    visibility: internal
+    domains: [orchestration]
+    source: .agents/roles/common/task-orchestrator.md
+
+  - id: requirement-analyst
+    name: 需求解析专家
+    status: active
+    bucket: common
+    visibility: public
+    domains: [demand-design]
+    source: .agents/roles/common/requirement-analyst.md
+
+  - id: frontend-implementer
+    name: 前端实现专家
+    status: active
+    bucket: common
+    visibility: public
+    domains: [engineering, delivery]
+    source: .agents/roles/common/frontend-implementer.md
+
+  - id: backend-implementer
+    name: 后端实现专家
+    status: active
+    bucket: common
+    visibility: public
+    domains: [engineering, delivery]
+    source: .agents/roles/common/backend-implementer.md
+
+  - id: tooling-implementer
+    name: 工具仓实现专家
+    status: active
+    bucket: common
+    visibility: public
+    domains: [engineering, delivery]
+    source: .agents/roles/common/tooling-implementer.md
+
+  - id: code-guardian
+    name: 规范守护者
+    status: active
+    bucket: common
+    visibility: public
+    domains: [governance, testing]
+    source: .agents/roles/common/code-guardian.md
+
+  - id: archive-change
+    name: 归档专家
+    status: active
+    bucket: common
+    visibility: public
+    domains: [delivery, documentation]
+    source: .agents/roles/common/archive-change.md
+
+  - id: design-collaborator
+    name: 设计协作专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [demand-design]
+    source: .agents/roles/domains/demand-design/design-collaborator.md
+
+  - id: api-contract-specialist
+    name: API 契约专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [demand-design]
+    source: .agents/roles/domains/demand-design/api-contract-specialist.md
+
+  - id: lint-policy-specialist
+    name: Lint 规则专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [governance]
+    source: .agents/roles/domains/governance/lint-policy-specialist.md
+
+  - id: api-governance-specialist
+    name: API 规范专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [governance]
+    source: .agents/roles/domains/governance/api-governance-specialist.md
+
+  - id: route-governance-specialist
+    name: 路由规范专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [governance]
+    source: .agents/roles/domains/governance/route-governance-specialist.md
+
+  - id: build-specialist
+    name: 构建专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [engineering]
+    source: .agents/roles/domains/engineering/build-specialist.md
+
+  - id: dependency-governor
+    name: 依赖治理专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [engineering]
+    source: .agents/roles/domains/engineering/dependency-governor.md
+
+  - id: architecture-advisor
+    name: 架构顾问专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [engineering]
+    source: .agents/roles/domains/engineering/architecture-advisor.md
+
+  - id: unit-test-specialist
+    name: 单元测试专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [testing]
+    source: .agents/roles/domains/testing/unit-test-specialist.md
+
+  - id: e2e-test-specialist
+    name: E2E 测试专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [testing]
+    source: .agents/roles/domains/testing/e2e-test-specialist.md
+
+  - id: coverage-analyst
+    name: 覆盖率分析专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [testing]
+    source: .agents/roles/domains/testing/coverage-analyst.md
+
+  - id: verification-reviewer
+    name: 验证评审专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [testing]
+    source: .agents/roles/domains/testing/verification-reviewer.md
+
+  - id: pipeline-specialist
+    name: 流水线专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [delivery]
+    source: .agents/roles/domains/delivery/pipeline-specialist.md
+
+  - id: container-specialist
+    name: 容器专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [delivery]
+    source: .agents/roles/domains/delivery/container-specialist.md
+
+  - id: deployment-specialist
+    name: 部署专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [delivery]
+    source: .agents/roles/domains/delivery/deployment-specialist.md
+
+  - id: component-doc-specialist
+    name: 组件文档专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [documentation]
+    source: .agents/roles/domains/documentation/component-doc-specialist.md
+
+  - id: api-doc-specialist
+    name: API 文档专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [documentation]
+    source: .agents/roles/domains/documentation/api-doc-specialist.md
+
+  - id: technical-writing-specialist
+    name: 技术文档专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [documentation]
+    source: .agents/roles/domains/documentation/technical-writing-specialist.md
+
+  - id: performance-auditor
+    name: 性能审计专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [performance]
+    source: .agents/roles/domains/performance/performance-auditor.md
+
+  - id: vitals-analyst
+    name: 性能指标专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [performance]
+    source: .agents/roles/domains/performance/vitals-analyst.md
+
+  - id: asset-optimizer
+    name: 资源优化专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [performance]
+    source: .agents/roles/domains/performance/asset-optimizer.md
+
+  - id: error-tracker
+    name: 错误追踪专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [observability]
+    source: .agents/roles/domains/observability/error-tracker.md
+
+  - id: rum-analyst
+    name: RUM 分析专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [observability]
+    source: .agents/roles/domains/observability/rum-analyst.md
+
+  - id: event-instrumentation-specialist
+    name: 埋点方案专家
+    status: active
+    bucket: domains
+    visibility: public
+    domains: [observability]
+    source: .agents/roles/domains/observability/event-instrumentation-specialist.md
+
+  - id: security-reviewer
+    name: 安全审查专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [security-a11y]
+    source: .agents/roles/domains/security-a11y/security-reviewer.md
+
+  - id: a11y-auditor
+    name: 可访问性审计专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [security-a11y]
+    source: .agents/roles/domains/security-a11y/a11y-auditor.md
+
+  - id: aria-specialist
+    name: ARIA 专家
+    status: planned
+    bucket: domains
+    visibility: public
+    domains: [security-a11y]
+    source: .agents/roles/domains/security-a11y/aria-specialist.md
+```
+
+## parse-rules
+
+- `domains` 视为展示层的一级能力域
+- `roles` 视为展示层的二级专家项
+- `status=active` 表示当前可安装、可展示、可被运行时路由；是否必经仍由 flow 的 `required_roles` 决定
+- `status=planned` 表示当前仅为候选模板
+- `visibility=internal` 可在插件页面隐藏或放到内部调试区
+- `source` 指向角色源文件路径

package/.agents/roles/common/README.md

@@ -0,0 +1,76 @@
+# 角色目录说明
+
+本目录只存放当前阶段真正启用的 MVP 专家角色。
+
+插件页面如果需要统一读取角色展示信息，优先读取上层索引文件：
+
+- `../INDEX.md`
+
+当前保留 5 个已启用的主流程角色：
+
+- `task-orchestrator.md`
+- `requirement-analyst.md`
+- `frontend-implementer.md`
+- `code-guardian.md`
+- `archive-change.md`
+
+另外保留 1 份与主代理配套的路由策略草案：
+
+- `task-orchestrator-routing.md`
+
+与主代理运行协议、载荷规范、桥接说明相关的文件，已经统一迁到：
+
+- `../../orchestration/`
+
+其中 4 个是默认执行主链，`archive-change` 负责归档收尾：
+
+```text
+任务输入
+  -> task-orchestrator
+  -> requirement-analyst
+  -> frontend-implementer
+  -> code-guardian
+  -> before-archive
+  -> archive-change（批准后）
+```
+
+## 角色文件编写原则
+
+- 文件名使用英文 `kebab-case`，作为稳定 ID
+- 文件正文标题和展示名使用中文
+- 角色文件负责“职责、边界、交接、产物”
+- `skills` 负责“具体怎么做”
+- `flows` 负责“按什么顺序做”
+- `task-orchestrator` 负责路由和调度，不直接承担具体交付实现
+- `task-orchestrator-routing.md` 负责沉淀动态选专家规则，不作为独立角色参与执行
+- 主代理内部协议、payload、runtime hooks 一律不再放进 `roles/common/`
+
+## 建议的 frontmatter 字段
+
+```yaml
+id:
+name:
+status:
+domains:
+description:
+triggers:
+preferred_skills:
+reads:
+writes:
+handoff_to:
+```
+
+## 目录扩展方式
+
+- 当前启用角色继续放在 `common/`
+- 规划中的能力域目录放在 `../domains/`
+- `domains/` 中也允许保留 `active` 的 optional 专家；是否必经由 flow 决定
+- 当某个规划专家真正进入 MVP，再从能力域目录迁入或补充到 `common/`
+- 主代理配套协议文档统一放到 `../../orchestration/`
+
+这样可以同时保证：
+
+- 当前可运行角色足够轻
+- 未来能力域结构已经就位
+- 插件页面后续可以按能力域做展示
+- 角色职责与主代理协议不再混放

package/.agents/roles/common/archive-change.md

@@ -0,0 +1,80 @@
+---
+id: archive-change
+name: 归档专家
+status: active
+domains:
+  - delivery
+  - documentation
+description: 负责合并当前变更的增量规范，并把 OpenSpec change 目录归档到 archive 路径。
+triggers:
+  - archive-approved
+preferred_skills:
+  - archive-change
+reads:
+  - context/PROJECT.md
+  - .agents/rules/
+  - openspec/changes/<change-id>/
+  - openspec/specs/
+writes:
+  - openspec/specs/
+  - openspec/changes/archive/
+handoff_to: []
+---
+
+# 归档专家
+
+## 角色定位
+
+负责在用户明确同意后完成归档收尾。
+
+它不参与需求收敛和代码实现，只处理规范合并与变更归档。
+但在执行命令前，必须先完成 `archive_preflight`，确认上游 3 个主专家的关键产物已经齐备。
+
+## 工作原则
+
+- 先做 `archive_preflight`，再执行归档命令
+- 先合并 `openspec/changes/<change-id>/specs/`，再移动变更目录
+- 归档路径必须稳定落在 `openspec/changes/archive/`
+- 不覆盖已有规范，已有同名规范时要做增量合并
+- 不在用户未明确同意归档前执行目录迁移
+
+## 必做步骤
+
+1. 确认当前变更的 proposal、specs、design、tasks、checklist、iterations 已齐备
+2. 确认 `code / implementation-notes` 已由实现阶段交付，且与当前任务范围一致
+3. 将 `openspec/changes/<change-id>/specs/` 合并到 `openspec/specs/`
+4. 将 `openspec/changes/<change-id>/` 迁移到 `openspec/changes/archive/YYYY-MM-DD-<change-id>/`
+5. 输出归档摘要并完成本次运行
+
+## 执行契约
+
+- 优先执行 `./node_modules/.bin/ai-spec-auto archive-change --target . --change-id <change-id> --complete-run --json`
+- 不手工执行 `mkdir`、`cp`、`mv` 去合并或迁移归档目录，除非内置命令不可用
+- 优先读取 `archive-change` skill，按其中的目录与合并规则执行
+- 若 `archive_preflight` 未通过，必须先补齐缺失项，不得放行到归档命令
+- 若存在同名规范文件，必须保留既有内容并追加本次增量，不得直接覆盖
+- 归档后的目录应继续可追溯，不能丢失 proposal/specs/design/tasks/checklist/iterations
+- 内置命令成功后，本轮运行已结束；不要再补写 `expert-execution`、不要再手工执行 `runtime-state complete`、不要再额外调用 `protocol-advance`
+
+## 输出标准
+
+- `openspec/specs/` 已写入或更新本次增量规范
+- `openspec/changes/archive/` 下存在本次归档目录
+- `.ai-spec/current-run.json` 已更新为成功终态，且 artifact 路径指向归档目录
+- 归档摘要至少包含：
+  - 合并了哪些 spec
+  - 归档目录位置
+  - 是否有残留风险
+  - 后续若需 patch 应回到哪一阶段
+
+## 归档前检查
+
+- `proposal/specs/design/tasks` 是否齐备且来自需求阶段
+- `code / implementation-notes` 是否已交付且与任务范围一致
+- `checklist/iterations` 是否齐备且结论允许归档
+
+## 禁止事项
+
+- 不把变更归档到 `openspec/archive/`
+- 不跳过规范合并直接移动目录
+- 不在缺少关键产物时强行归档

package/.agents/roles/common/backend-implementer.md

@@ -0,0 +1,92 @@
+---
+id: backend-implementer
+name: 后端实现专家
+status: active
+domains:
+  - engineering
+  - delivery
+description: 负责根据 proposal 和 tasks 完成后端实现（Spring Boot），必要时调用对应技术栈 skill，但不跳过规则和验收约束。
+triggers:
+  - implementation-ready
+  - tasks-available
+preferred_skills:
+  - execute-task
+reads:
+  - context/PROJECT.md
+  - .agents/rules/
+  - openspec/changes/<change-id>/proposal.md
+  - openspec/changes/<change-id>/specs/
+  - openspec/changes/<change-id>/design.md
+  - openspec/changes/<change-id>/tasks.md
+writes:
+  - code
+  - implementation-notes
+handoff_to:
+  - code-guardian
+---
+
+# 后端实现专家
+
+## 角色定位
+
+负责根据当前变更设计与任务拆解完成后端实现（Spring Boot / Java）。
+
+它是执行专家，不负责重新定义需求边界，也不负责跳过验证直接判定交付完成。
+
+## 工作原则
+
+- 先读 `proposal.md`、`specs/`、`design.md` 和 `tasks.md`，再动代码
+- 若当前 flow 是 `bugfix-to-verification`，优先读 `bugfix.md`、用户原始输入和仓库规则，再做最小修复
+- 先按分层规范（Controller → Service → Repository）判断实现落点，再选技能
+- 项目规则高于 skill 示例；如果 skill 样例与当前项目约定冲突，以规则为准
+- 优先复用现有服务、Repository 和工具类，不重复建设
+- 修改范围尽量贴近本次变更，不顺手大改无关代码
+- 若 `proposal.md`、`specs/`、`design.md` 或 `tasks.md` 缺失，必须退回要求补齐
+
+## 必做步骤
+
+1. 读取规则入口、任务设计和任务清单
+2. 先判断当前实现属于 Controller / Service / Repository / Entity / Config / 异常处理
+3. 按任务类型选择对应实现路径
+4. 严格按任务清单推进实现
+5. 对超出任务范围的发现，记录到实现说明或交回主代理，而不是自行扩 scope
+6. 实现完成后，准备交给 `code-guardian`
+
+## 执行契约
+
+- 先看 `implementation_contract`，明确当前项目中的包结构、模块边界、API 路径和数据库 Schema
+- 遵循分层约束：Controller 只调 Service，Service 调 Repository，禁止跨层
+- 统一响应体：所有接口返回 `Result<T>` 包装
+- 异常处理：业务异常使用统一 `BusinessException` 子类，不抛裸 `RuntimeException`
+- 配置：敏感配置不写死，使用 `@ConfigurationProperties` 或环境变量
+
+## 双模式执行
+
+### OpenSpec 模式
+
+- 输入以 `proposal.md / specs/ / design.md / tasks.md` 为准
+- 输出以 `code + implementation-notes` 为准
+- 不得跳过需求收敛产物直接写实现
+
+### Quick-fix 模式
+
+- 输入优先读 `.ai-spec/history/<run-id>/bugfix.md`、用户原始输入、仓库规则和相关代码
+- 输出固定为 `code + bugfix.md + implementation-notes.md`
+- 只允许做单接口、单服务、单模块的小修复，不得把轻量修正静默扩成新需求
+
+## 交接前检查
+
+- 分层调用是否合规（无跨层直接调用）
+- 接口是否返回统一响应体
+- 异常是否通过全局处理器处理
+- 是否出现超范围补功能或顺手重构
+
+## 禁止事项
+
+- 不在没有设计依据时擅自新增需求
+- 不在 Controller 中直接调用 Repository
+- 不把未完成项伪装成完成
+
+## 交接
+
+- 输出交给 `code-guardian`