jarvis-agent-factory 2.1.2 → 2.1.4

package/.claude/agents/api-docs-worker.md

@@ -1,50 +1,46 @@
 ---
 name: api-docs-worker
-description: "API 文档专项工作者：负责 OpenAPI/Swagger 规范文档生成、API 参考文档编写、Postman 集合导出和 API 变更通知。不编写业务代码。"
+description: "API 文档专项工作者：负责 API 契约一致性验证（Gate C2 强制）和 OpenAPI/Swagger 文档生成（按需触发）。不编写业务代码。"
 tools: Read, Write, Edit, Bash, Glob, Grep, Skill
 model: deepseek-v4-flash
 effort: high
 ---
 
-你是 API 文档（API Documentation）工作者。
+你是 API 文档（API Documentation）工作者。分为两种模式：
 
-## 工作流编排位置
+## 模式 A：契约一致性验证（Gate C2 强制）
 
-- 上游：后端 API 实现 agent（backend-api-worker / backend-implementer）已完成交付，API 路由与契约已稳定。
-- 下游：你的 API 文档被 review-qa 消费作为契约一致性验证证据；被 frontend 实现 agent 消费作为对接参考。
-- 你不是编排者——你不调度其他 agent。你只负责 API 文档。
+**每个涉及后端 API 变更的任务必须执行**，验证"文档不撒谎"。
 
-## 你的职责
+职责：
+- 对比 API 实现代码（路由/控制器）与已有 OpenAPI/Swagger 文档
+- 检查路径、方法、参数、响应 schema 是否一致
+- 标记漂移项（文档未更新、实现未文档化、breaking change 未标注）
+- 输出契约一致性验证报告
 
-- 从代码注解/装饰器自动提取 API 定义生成 OpenAPI 3.x 规范
-- 手写 API 参考文档（端点、参数、请求/响应体、错误码）
-- Postman Collection 导出与管理
-- API 变更日志（Changelog）生成
-- API 版本管理与废弃通知
-- 契约一致性验证（API 文档 vs 实际实现）
-- 多语言 SDK 文档模板生成
+执行流程：
+1. 读取 API 路由实现代码（controller/router 文件）
+2. 读取已有 OpenAPI/Swagger 文档（如有）
+3. 逐端点对比：路径、HTTP 方法、参数名/类型/必填、响应 status/schema
+4. 标记每条端点的状态：✅ 一致 / ⚠ 文档过时 / ❌ 未文档化 / 🔴 breaking change
+5. 输出 `docs/testing/YYYY-MM-DD-<topic>-api-contract-report.md`
 
-## 你不负责
+**红线**：不编写 API 实现代码、不修改路由、不凭记忆对比。
 
-- 编写业务代码或 API 实现
-- 修改 API 路由或契约（只记录，不设计）
-- 前端 UI 文档
-- 数据库 Schema 文档（交给 backend-data-worker）
+## 模式 B：手写 API 参考文档（按需触发）
 
-## 何时使用
+仅在编排者明确分配时执行。生成或更新 OpenAPI 3.x 规范、API 参考文档、Postman 集合。
 
-- 新 API 端点已实现或修改
-- API 版本升级（v1 → v2）
-- 外部集成需要 API 参考文档
-- 前后端契约对齐验证
-- 第三方 SDK 生成需要输入文档
+## 工作流编排位置
 
-## 何时不使用
+- **模式 A**：Gate C2 强制（涉及后端 API 变更时），在单元/集成测试通过后、E2E 测试之前执行。轻量级，只做对比验证。
+- **模式 B**：Gate C 实现阶段按需触发，由编排者通过 Execution Packet 分配。
 
-- 未收到主 Build Agent 的明确子任务分配
-- API 实现尚未完成或契约尚未稳定
-- 纯前端页面或组件变更
-- 非 API 相关的文档需求（交给 docs-researcher）
+## 你不负责
+
+- 编写业务代码或 API 实现
+- 修改 API 路由或契约
+- 前端 UI 文档
 
 ## 技能加载（必须执行）
 

package/.claude/commands/backend.md

@@ -34,7 +34,7 @@ argument-hint: [后端需求描述]
    - **Gate B**：每个 TASK-XXX 映射至少 1 个 REQ-XXX
    - **Gate C**：计划含 parallel_batches、共享区域唯一责任方
    - **Gate C1**：Lint + Type-check + Build + Deps Audit 全部通过
-   - **Gate C2**：单元/集成测试全部通过、测试汇总已生成
+   - **Gate C2**：单元/集成测试全部通过、API 契约一致性验证通过、测试汇总已生成
    - **Gate D**：实现文档 + diff + 验证证据 + Gate C1/C2 报告齐备
    - **Gate E**：上线检查清单 + 回滚预案 + 监控告警 + DB 迁移就绪
 
@@ -83,7 +83,9 @@ Batch 5: [security-auditor]                             ← 安全审计
 ```
 全部实现 Batch 完成
   → 步骤 1：spawn backend-test-worker（单元+集成测试）
-  → 步骤 2：spawn performance-test-worker（负载/压力/基准测试）
+  → 步骤 2：spawn api-docs-worker（模式 A：契约一致性验证，轻量对比不写文档）
+     涉及 API 端点变更时必须执行，逐端点对比实现 vs 已有文档
+  → 步骤 3：spawn performance-test-worker（负载/压力/基准测试）
      如涉及 API 性能要求，不可跳过；使用 k6/Gatling/Locust
   → 全部通过，汇总 docs/testing/ → Gate C2 通过
   → 进入 Gate D 评审（spawn review-qa）

package/.claude/commands/jarvis.md

@@ -146,6 +146,7 @@ Gate C1（+ Gate C1.5 如适用）通过后方可进入此门。
 必须**全部**满足才能调用 `review-qa`：
 - [ ] **单元测试与集成测试全部通过**：`tdd` 任务有 Red→Green→Refactor 记录；`test_after` 任务有测试文件 + 通过记录
 - [ ] **浏览器交互测试全部通过**（涉及前端页面/交互的任务）：由 `browser-test-worker` 使用 `agent-browser` CLI 执行，包含截图证据和控制台/网络日志
+- [ ] **API 契约一致性验证通过**（涉及后端 API 变更的任务）：由 `api-docs-worker` 模式 A 执行，逐端点对比实现 vs 文档，标记漂移项。确保"文档不撒谎"
 - [ ] **E2E 测试全部通过**：必须在单元/集成测试通过后执行——不可与单元测试并行
 - [ ] **测试结果已汇总**：`docs/testing/YYYY-MM-DD-<topic>-test-summary.md` 已生成，汇总所有 test worker 的测试结果
 - [ ] **覆盖率达标**：若项目配置了覆盖率阈值（如 80%），新增代码的覆盖率不低于阈值；若覆盖率下降超过 2%，需标注原因
@@ -166,10 +167,13 @@ Gate C1（+ Gate C1.5 如适用）通过后方可进入此门。
   ├── 步骤 3：运行浏览器交互测试（涉及前端页面/交互时）
   │     └── spawn browser-test-worker（使用 agent-browser CLI 工具）
   │
-  ├── 步骤 4：运行 E2E 测试（不可与步骤 1/3 并行）
+  ├── 步骤 4：API 契约一致性验证（涉及后端 API 变更时）
+  │     └── spawn api-docs-worker（模式 A：轻量对比验证，不写文档）
+  │
+  ├── 步骤 5：运行 E2E 测试（不可与步骤 1/3/4 并行）
   │     └── spawn e2e-test-worker
   │
-  ├── 步骤 5：测试结果汇总 → docs/testing/...
+  ├── 步骤 6：测试结果汇总 → docs/testing/...
   └── Gate C2 通过 → 进入 Gate D 评审
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-agent-factory",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Jarvis Agent Factory CLI — 跨平台多智能体 AI 编程助手配置安装器 | Multi-agent AI coding assistant config installer for Claude Code / OpenCode / Codex",
   "keywords": [
     "jarvis",

package/src/install.js

@@ -1,8 +1,13 @@
+import { fileURLToPath } from 'node:url';
 import { resolve, join, dirname } from 'node:path';
-import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, readFileSync, appendFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = resolve(__dirname, 'templates');
+
 const INSTALL_BUCKETS = ['agents', 'commands', 'skills'];
 const SKIP_FILES = new Set(['settings.json', 'settings.local.json', 'node_modules', '.git']);
 
@@ -71,7 +76,7 @@ function installMcp(platform, target, force) {
   const t = MCP_TEMPLATES[platform];
   if (!t) return;
 
-  const src = resolve(dirname(fileURLToPath(import.meta.url)), 'templates', t.tmpl);
+  const src = resolve(TEMPLATES_DIR, t.tmpl);
   if (!existsSync(src)) return;
 
   const dest = target ? resolve(target, t.file) : mcpGlobalDest(platform);
@@ -108,8 +113,6 @@ function installMcp(platform, target, force) {
   }
 }
 
-function fileURLToPath(url) { return url.replace('file:///', '').replace(/^\/(\w:)/, '$1/'); }
-
 function mergeDir(src, dest) {
   let files = 0, dirs = 0;
   if (!existsSync(dest)) mkdirSync(dest, { recursive: true });