@chongyan/autospec 1.0.1

package/knowledge/guides/stages/ai-effect-evaluator.md

@@ -0,0 +1,93 @@
+---
+name: ai-effect-evaluator
+description: 当需要执行AI/模型组件的效果评测、验证任务完成质量时触发
+type: execute
+---
+
+## 定位
+
+效果评测执行阶段的"执行"类skill。负责加载评测数据集、执行评测、计算指标。
+
+> **使用场景**：项目包含AI/模型组件，需要验证效果是否满足要求。
+
+## 输入
+
+- 必须输入：AI/模型组件、评测数据集
+- 可选输入：评测方案（evaluation-plan.md）、评测脚本
+
+## 执行步骤
+
+### Step 1: 准备评测环境
+
+1. 检查是否有评测方案（`.autospec/specs/{feature}/evaluation-plan.md`）
+2. 检查是否有评测数据集（`.autospec/specs/{feature}/evaluation/dataset/`）
+3. 检查是否有评测脚本（`tests/evaluation/`, `evaluation/`）
+
+### Step 2: 加载评测数据集
+
+1. 读取评测数据集
+2. 验证数据集格式
+3. 统计数据集规模
+
+### Step 3: 执行评测
+
+1. 初始化被评测的AI/模型组件
+2. 对每个测试用例执行推理
+3. 收集预测结果
+
+### Step 4: 计算评测指标
+
+根据评测方案中的指标定义计算：
+
+1. **准确率指标**：
+   - 激活准确率、匹配准确率等
+
+2. **质量指标**：
+   - 响应质量、任务完成率等
+
+3. **性能指标**：
+   - 响应时间、吞吐量等
+
+### Step 5: 生成评测报告
+
+1. 汇总各项指标
+2. 与目标值对比
+3. 识别badcase
+
+## 输出格式
+
+```
+## 效果评测结果
+
+### 评测对象
+- 组件名称：{component_name}
+- 评测数据集：{dataset_path}
+- 测试用例数：{total_cases}
+
+### 评测指标
+| 指标名称 | 目标值 | 实际值 | 状态 |
+|----------|--------|--------|------|
+| ... | ... | ... | ✅/❌ |
+
+### Badcase 分析
+| 用例ID | 输入 | 预期输出 | 实际输出 | 问题描述 |
+|--------|------|----------|----------|----------|
+| ... | ... | ... | ... | ... |
+
+### 结论
+- 评测通过：✅ 是/❌ 否
+- 达标指标：{passed_count}/{total_count}
+- 需要优化：{需要优化的点}
+```
+
+## 判定标准
+
+- **通过**：所有指标达到目标值
+- **部分通过**：部分指标达标
+- **不通过**：主要指标未达标，需要优化
+
+## 适用场景
+
+- 适用：AI/模型组件需要验证效果
+- 不适用：普通功能无需效果评测
+- 对应做类skill：test-generator（生成测试）

package/knowledge/guides/stages/code-implementer.md

@@ -0,0 +1,205 @@
+---
+name: code-implementer
+description: 当技术方案通过评审、需要忠实落地为可运行代码时触发
+type: produce
+---
+
+## 定位
+编码阶段的核心"做"类skill。将技术方案忠实转化为可运行代码，确保实现与设计一致。
+
+## 输入
+- 必须输入：经方案评审通过的技术方案文档（含关键假设清单）
+- 可选输入：项目代码规范、现有代码库（用于理解上下文和复用）、现有测试代码（用于学习风格）
+
+## 输出
+- 功能代码（符合方案设计）
+- 单元测试和模块内集成测试（**仅限模块内部，跨系统集成留给 QA 测试阶段**）
+- 自测报告（覆盖了什么、测试结果、使用的测试框架）
+- **关键假设清单**（继承设计阶段 + 实现中新发现的假设）
+- **证据清单**（测试通过日志、覆盖率数据）
+
+## 职责边界
+
+| 测试类型 | 编码阶段（自测） | QA 测试阶段 |
+|---------|-----------------|-------------|
+| 单元测试 | ✅ 核心 | ❌ 不重复 |
+| 模块内集成 | ✅ 基础 | ❌ 不重复 |
+| 跨系统集成 | ❌ 留给 QA | ✅ 重点 |
+| E2E 测试 | ❌ 留给 QA | ✅ 重点 |
+| 验收测试 | ❌ 留给 QA | ✅ 重点 |
+
+## 执行步骤
+
+### Step 0: 学习现有测试风格（新增）
+
+在编写测试前，先分析项目现有的测试风格：
+
+1. **检测测试框架和工具**：
+   - Node.js: 检查 `package.json` 的 devDependencies
+   - Python: 检查 `requirements.txt` 或 `pyproject.toml`
+   - Java: 检查 `pom.xml` 或 `build.gradle`
+
+2. **分析断言风格和组织结构**：
+   - 断言风格：`expect().toBe()` vs `assert.equal()`
+   - 组织结构：`describe/it` 嵌套、`beforeEach/afterEach` 使用
+
+3. **提取测试基础设施**：
+   - Setup/Teardown 文件位置（`jest.setup.js`, `conftest.py`）
+   - Fixtures 目录结构
+   - Mock 配置
+
+4. **记录测试上下文**：
+   - 记录检测到的测试框架、断言风格
+   - 后续生成的测试必须与现有风格一致
+
+**关键**：如果项目已有测试代码，生成的测试必须复用现有基础设施并保持风格一致。
+
+### Step 1: 确定模式
+
+读取 `.autospec/config.json`，检查 `subsystems` 字段：
+- **无 subsystems 或长度为1** → 单系统模式
+- **有 subsystems 且长度>1** → 多系统模式
+
+### Step 2: 单系统模式
+
+1. 通读技术方案 `design.md`，理解架构、接口、数据模型的设计意图
+   - 预期产出：对方案的理解确认
+   - 失败处理：方案不清晰的部分标记，不自行猜测
+2. **校验设计阶段关键假设**，在代码中体现约束
+3. **搜索现有代码库**，识别可复用的组件和工具
+4. 按方案的模块划分，确定编码顺序（先基础后上层）
+5. 逐模块编码：
+   a. 严格按方案中的接口定义实现
+   b. 严格按方案中的数据模型实现
+   c. 遵循项目编码规范
+   d. 在逻辑不自明的地方添加注释
+6. 编写单元测试（覆盖核心逻辑路径 + 关键边界条件）：
+   - **使用 Step 0 检测到的测试框架**
+   - **复用现有的测试基础设施**（setup/teardown、fixtures）
+   - **保持与现有测试风格一致**
+   - 职责：仅覆盖本模块的核心逻辑和边界条件
+7. 编写模块内集成测试（覆盖模块间交互）：
+   - **仅覆盖本模块的内部集成**
+   - **跨系统集成留给 QA 测试阶段**
+   - 使用现有的 Mock 策略
+8. 本地运行所有测试，确保全部通过
+9. **生成自测报告**：
+   ```markdown
+   ## 自测报告
+
+   ### 测试执行结果
+   - 单元测试：X 个用例，全部通过
+   - 模块内集成测试：X 个用例，全部通过
+   - 覆盖率：XX%
+
+   ### 测试框架
+   - 框架：Jest / pytest / JUnit
+   - 复用基础设施：jest.setup.js, tests/fixtures/
+
+   ### 覆盖范围
+   - 核心逻辑：✓
+   - 边界条件：✓
+   - 异常路径：✓
+   - 关键假设：✓
+
+   ### 证据
+   - 测试执行日志：[粘贴]
+   - 覆盖率报告：[粘贴]
+   ```
+10. **自查清单**：
+    a. 逐项对照方案接口定义
+    b. 逐项对照方案数据模型
+    c. 检查关键假设在代码中的体现
+11. 如发现方案有缺陷 → **不自行修改**，标记问题提请回退到设计阶段
+12. **整理关键假设清单**（继承 + 新发现），**整理证据清单**
+
+### Step 3: 多系统模式
+
+1. **读取整体架构**：读取 `design/overview.md`，理解：
+   - 系统交互关系
+   - 跨系统接口契约
+   - 开发顺序（通常：后端 → 前端 → 移动端；有ml时可能需要先验证效果）
+   - 解耦并行机会（契约定义后可并行的任务）
+
+2. **按依赖顺序处理子系统**：
+   ```
+   for subsystem in config.subsystems（按依赖顺序）:
+     a. 读取 design/{subsystem.name}.md
+     b. 切换到 {subsystem.path} 目录
+     c. 搜索现有代码，识别可复用组件
+     d. 按方案编码
+     e. 执行子系统验证：
+        - {subsystem.build}（如有）
+        - {subsystem.test}（如有）
+        - {subsystem.lint}（如有）
+     f. 记录验证结果
+   ```
+
+3. **面向契约并行开发**：
+   - **契约先行**：优先产出接口契约（OpenAPI/GraphQL Schema/数据Schema）
+   - **下游Mock开发**：契约定义后，下游子系统可基于Mock数据并行开发
+   - **联调验证**：上游实现完成后，下游切换真实接口联调
+   - **契约变更管理**：契约变更需通知所有相关方
+
+4. **并行执行机会**：
+   - **原生并行**：无依赖关系的任务可并行（如前端页面A和前端页面B）
+   - **解耦并行**：通过契约解耦的任务可并行（如后端实现 ∥ 前端Mock开发）
+   - 并行条件：无共享写入资源、无执行顺序约束、失败互不影响
+   - 标记为 `[P]` 或 `→contract` 的任务可同时启动多个 Agent 并行执行
+
+5. **集成验证**：
+   - 验证跨系统接口联调
+   - 验证数据流正确性
+   - 记录集成问题
+
+### Step 4: 数据/AI子系统特殊处理
+
+当子系统类型为 `data` 或 `ai` 时：
+
+**数据系统（data）**：
+- 数据模型实现（表结构、字段定义）
+- ETL脚本开发
+- 数据质量检查脚本
+- 数据测试用例
+
+**AI/模型系统（ai）**：
+- 模型训练/推理代码
+- 特征工程代码
+- 评测数据集构建（如设计阶段定义）
+- 评测脚本开发（如设计阶段定义）
+- 效果验证脚本
+
+## Layer 1 验证要求
+
+### 单系统模式
+- 编译检查、测试执行、Lint检查、类型检查
+- 每项必须附真实执行日志，无日志=BLOCKED
+
+### 多系统模式
+- **每个子系统都必须通过验证**
+- 按顺序验证：先确保上游子系统通过，再验证下游
+- 汇总所有子系统的验证结果
+- 任一子系统失败 = 整体 BLOCKED
+
+### 数据/AI子系统验证
+- **数据系统**：数据质量检查通过、ETL流程可执行
+- **AI/模型系统**：模型可加载、推理可执行、评测脚本可运行
+
+## 反模式清单（DP7）
+1. **偏离设计**：编码时觉得方案不好，自行修改。检测：逐项对照方案接口和数据模型
+2. **自测走过场**：只测happy path。检测：checklist强制要求覆盖异常路径
+3. **过度优化**：在实现阶段做性能优化。检测：先正确后优化，除非方案明确要求
+4. **蛮力修复**：测试不过用@JsonIgnore、跳过测试、增加内存。检测：禁止skip/ignore注解
+5. **虚假成功声明**：测试红灯时称代码完成。检测：Layer 1确定性验证不可绕过
+6. **重复造轮子**：不搜索项目已有工具/组件就新建。检测：新建文件前搜索同名/同功能
+7. **跳过效果验证**：AI/模型系统不开发评测脚本。检测：ml类型子系统必须有评测代码
+
+## 适用场景与边界
+- 适用：有明确技术方案需要落地为代码的场景
+- 不适用：探索性编码（用experiment模式）；纯重构（需单独skill）
+- 边界：忠实执行方案，发现方案问题时提出而非自行解决
+- 前置：design-reviewer通过
+- 后续：Layer 1确定性验证 → code-reviewer审查
+
+## 示例
+（待从实践中积累第一个完整示例）

package/knowledge/guides/stages/code-reviewer.md

@@ -0,0 +1,111 @@
+---
+name: code-reviewer
+description: 当代码自测通过Layer 1确定性验证后、需要独立审查代码质量和安全性以决定是否可合并时触发
+type: review
+---
+
+## 定位
+审查阶段的核心"审"类skill。独立审查代码质量，作为进入QA测试阶段的Layer 2质量关卡。
+
+> **做审分离（DP2）**：必须由独立于code-implementer的AI实例执行。
+
+## 输入
+- 必须输入：自测通过的代码（Layer 1已通过）、技术方案文档、自测报告
+- 可选输入：methodology/checklists/code.md（检查标准）、关键假设清单（累积至今）
+
+## 评判标准
+必须满足：
+- [ ] 代码实现与技术方案一致，未偏离设计
+- [ ] 单元测试覆盖核心逻辑路径
+- [ ] 所有测试运行通过
+- [ ] 无安全漏洞（SQL注入、XSS、CSRF、越权访问、敏感信息泄露）
+- [ ] 无硬编码的密钥、密码、配置项
+- [ ] 错误处理合理
+- [ ] 关键假设在代码中正确体现
+
+建议满足：
+- [ ] 测试覆盖边界条件和异常路径
+- [ ] 代码可读性良好
+- [ ] 无重复代码
+- [ ] 资源管理正确
+- [ ] 日志记录合理
+
+## 评审步骤
+0. **差异对比**（如为更新任务）
+   - 获取旧版本代码
+   - 获取新版本代码
+   - 对比差异维度：新增、修改、删除
+   - 输出结构化差异报告
+1. 对照技术方案，检查代码实现是否一致（架构、接口、数据模型）
+   - 证据获取：逐个接口对照方案定义
+2. 审查代码质量
+   a. 可读性：命名清晰、逻辑直观
+   b. 可维护性：模块化合理、不过度耦合
+   c. 代码规范：符合项目约定
+3. 审查安全性
+   a. 输入校验：是否对用户输入做了验证
+   b. 注入防护：SQL、命令注入、XSS
+   c. 认证授权：权限检查是否完善
+   d. 敏感信息：是否有硬编码密钥或泄露风险
+   e. 金额处理：是否使用专用金额类型（禁止浮点数）
+4. 审查工程规范
+   a. 接口变更是否向后兼容（出入参只增不减）
+   b. 幂等性：服务方是否严格区分成功/失败/重复/未知
+   c. 并发控制：是否遵循"一锁二判三处理"
+   d. 异常处理：是否明确区分业务异常/系统异常，禁止吞异常
+   e. 线程上下文变量设置与清除是否配对（finally中清理）
+5. 审查性能
+   a. 是否有明显的性能问题（N+1查询、无限循环风险等）
+   b. 资源管理（连接、文件句柄是否正确释放）
+   c. SQL语句是否带where条件，是否走索引，禁止select *
+6. 审查测试充分性
+   a. 核心逻辑路径是否覆盖
+   b. 边界条件和异常路径覆盖情况
+7. **校验关键假设跨阶段一致性**（需求→设计→实现）
+8. 区分blocking和non-blocking问题
+9. 逐项输出判定结果，**每项附具体证据（代码位置+问题描述）**
+
+## 输出格式
+
+```
+## 审查结论：通过 / 不通过
+
+### 逐项判定
+| 检查项 | 结论 | 证据 | 备注 |
+|--------|------|------|------|
+| 方案一致性 | ✅/❌ | {接口对照结果} | {偏离详情} |
+| 安全性 | ✅/❌ | {具体代码位置} | {修复建议} |
+| ... | ... | ... | ... |
+
+### 必须修复（blocking）
+- [{文件}:{行号}] {问题描述} → {修复建议}
+
+### 建议改进（non-blocking）
+- [{文件}:{行号}] {问题描述} → {改进方向}
+
+### 关键假设验证
+- 设计假设X：在代码中正确体现/存在偏差（证据：{代码位置}）
+
+### 严重问题判定
+如发现以下任一情况，标记为严重问题并进入问题归因阶段：
+- 核心指标缺失或重复
+- 违反业务规则的强规则
+- 数据量波动超过阈值
+- 计算逻辑错误
+- 影响下游业务使用
+```
+
+## 反模式清单（DP7）
+1. **橡皮图章**：审查走过场。检测：每条"通过"必须附具体代码位置作为证据
+2. **吹毛求疵**：纠结代码风格等非关键问题。检测：风格问题不可blocking
+3. **缺乏上下文**：不了解需求和设计就审代码。检测：审查步骤第一步必须对照方案
+4. **假设漂移忽视**：不校验跨阶段假设一致性。检测：输出必须包含假设验证section
+5. **自我确认偏差**：做和审是同一个AI实例。检测：command-runner确保实例隔离
+
+## 适用场景与边界
+- 适用：编码完成并自测通过Layer 1后，进入QA测试前
+- 不适用：代码还在编写中（先完成编码和自测）
+- 对应做类skill：code-implementer
+
+## 示例
+（待从实践中积累第一个完整示例）

package/knowledge/guides/stages/consistency-checker.md

@@ -0,0 +1,177 @@
+---
+name: consistency-checker
+description: 当需要执行跨产物一致性检查（DP18）时触发。检测需求、设计、代码、测试之间的重复、歧义、规格不全、宪法对齐、覆盖缺口、术语漂移。
+type: review
+---
+
+## 定位
+
+跨产物一致性检查专用技能（DP18实现）。在阶段交付前或全流程完成后，检查六维一致性。
+
+## 输入
+
+- 必须输入：
+  - 需求文档（.autospec/specs/{feature}/requirement.md）
+  - 技术方案（.autospec/specs/{feature}/design.md）
+  - 代码实现（变更文件列表 + 代码内容）
+  - 测试报告（如果有）
+- 可选输入：
+  - 历史版本的文档（用于检测术语漂移）
+  - 架构图、API契约文档
+
+## 输出
+
+```markdown
+## 跨产物一致性检查报告（DP18六维检测）
+
+### 检查结论：✅ 通过 / ⚠️ 有警告 / ❌ 不通过
+
+### 1. 重复检测
+| 位置A | 位置B | 重复内容摘要 | 严重程度 |
+|-------|-------|--------------|----------|
+| ... | ... | ... | ... |
+
+### 2. 歧义检测
+| 术语/描述 | 出现的文档 | 不同解释 | 建议 |
+|-----------|------------|----------|------|
+| ... | ... | ... | ... |
+
+### 3. 规格不全检测
+| 需求条目 | 设计覆盖 | 代码实现 | 测试验证 | 缺失环节 |
+|----------|----------|----------|----------|----------|
+| 收藏功能 | ✅ | ✅ | ❌ | 缺少测试 |
+
+### 4. 宪法对齐检测
+| 宪法条款 | 相关文档段落 | 对齐状态 | 问题描述 |
+|----------|--------------|----------|----------|
+| DP6 Layer1必须执行 | 设计.md第15行 | ✅ | ... |
+
+### 5. 覆盖缺口检测
+| 需求点 | 设计覆盖 | 代码覆盖 | 测试覆盖 | 状态 |
+|--------|----------|----------|----------|------|
+| ... | ... | ... | ... | ... |
+
+### 6. 术语漂移检测
+| 术语 | 需求用词 | 设计用词 | 代码用词 | 漂移程度 |
+|------|----------|----------|----------|----------|
+| 用户收藏 | favorite | bookmark | collection | ⚠️ 中等 |
+
+### 必须修复（Critical/High）
+- ...
+
+### 建议改进（Medium/Low）
+- ...
+
+### 检查者信息
+- 检查Agent：autospec-consistency
+- 置信度：{高/中/低}
+- 六维雷达图：[重复, 歧义, 规格, 宪法, 覆盖, 术语] = [5,4,3,5,2,4] /5
+```
+
+## 执行步骤
+
+### Step 1: 收集产物（确定性）
+
+读取所有相关产物：
+1. 需求文档：提取用户故事、验收标准、关键术语
+2. 技术方案：提取数据模型、API定义、模块划分
+3. 代码实现：提取实际实现的功能点、API端点、数据结构
+4. 测试报告：提取测试覆盖的功能点、测试用例关联的需求
+
+### Step 2: 重复检测（两两比对）
+
+**检测逻辑**：
+- 段落级别：相同或相似的段落出现在多个文档中
+- 代码级别：相同逻辑在多个地方重复实现
+- 配置级别：配置与代码中的硬编码重复
+
+**输出**：重复内容的位置、相似度、建议（保留一处+引用）
+
+### Step 3: 歧义检测（术语多义）
+
+**检测逻辑**：
+- 同一术语在不同文档中有不同解释
+- 示例："用户"在需求中指"终端用户"，在代码中指"系统用户"
+
+**输出**：术语、出现的文档、不同解释、建议（统一术语）
+
+### Step 4: 规格不全检测（追踪矩阵）
+
+**检测逻辑**：
+建立需求→设计→代码→测试的追踪矩阵：
+- 每个需求ID是否有对应设计？
+- 每个设计点是否有代码实现？
+- 每个代码功能是否有测试验证？
+
+**输出**：缺失环节的清单
+
+### Step 5: 宪法对齐检测（红线检查）
+
+**检测逻辑**：
+检查各产物是否符合宪法条款：
+- DP6: Layer 1验证是否有真实执行日志
+- DP2: 审查是否独立执行
+- DP10: 不可逆操作是否有安全审计
+- DP7: 反模式清单是否被提及
+
+**输出**：违反宪法条款的具体位置
+
+### Step 6: 覆盖缺口检测
+
+**检测逻辑**：
+- 需求中的边界条件在设计中是否覆盖
+- 设计中的异常处理在代码中是否实现
+- 代码中的功能在测试中是否验证
+
+**输出**：未覆盖点的清单和风险评估
+
+### Step 7: 术语漂移检测
+
+**检测逻辑**：
+- 提取各文档中同一概念的不同用词
+- 计算术语一致性分数
+
+**示例漂移**：
+- 需求："收藏商品"
+- 设计："加入收藏夹"
+- 代码：saveToFavorites()
+- 测试："bookmark功能"
+
+**输出**：术语对照表、漂移程度、建议统一用词
+
+### Step 8: 汇总报告
+
+输出结构化报告，包含：
+- 六维雷达图（可视化一致性评分）
+- 必须修复项（Critical/High）
+- 建议改进项（Medium/Low）
+- 总体通过/不通过结论
+
+## 反模式清单（DP7）
+
+1. **假阳性泛滥**：将正常的同义词使用标记为术语漂移
+   - 检测：区分术语漂移和合理同义词
+
+2. **忽视上下文**：不考虑产物间的正常演进关系
+   - 检测：设计比需求详细是合理的，不是规格不全
+
+3. **机械化比对**：只比对字面而不理解语义
+   - 检测：使用语义相似度而非字面匹配
+
+4. **忽略优先级**：把所有不一致同等对待
+   - 检测：按严重程度分级处理
+
+## 适用场景与边界
+
+- **适用**：
+  - 阶段交付前（尤其是交付部署前）
+  - 全流程完成后归档前
+  - 发现跨阶段不一致问题时
+
+- **不适用**：
+  - 单阶段内部审查（不需要跨产物检查）
+  - 初始阶段（只有需求文档时无其他产物可对比）
+
+- **触发时机**：
+  - 自动：/autospec:archive 命令执行前自动触发
+  - 手动：/consistency 命令