jarvis-agent-factory 2.1.4 → 3.0.0-alpha

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

@@ -12,19 +12,31 @@ effort: high
 
 **每个涉及后端 API 变更的任务必须执行**，验证"文档不撒谎"。
 
+**"已有文档"指什么**：现代后端框架大多支持从代码注解/装饰器自动生成 OpenAPI spec。例如 FastAPI 的 Pydantic 模型 + `/openapi.json`、NestJS 的 `@ApiProperty` 装饰器 + swagger 插件、Spring Boot 的 springdoc、Go 的 swaggo 注解、Express 的 swagger-jsdoc。**验证就是拿这份自动生成的 spec，去对比实际的 route/controller 实现代码**，检查注解有没有过时、漏写或写错。
+
 职责：
-- 对比 API 实现代码（路由/控制器）与已有 OpenAPI/Swagger 文档
+- 对比 API 实现代码（路由/控制器）与自动生成的 OpenAPI/Swagger spec
 - 检查路径、方法、参数、响应 schema 是否一致
-- 标记漂移项（文档未更新、实现未文档化、breaking change 未标注）
+- 标记漂移项：注解改了但 spec 没重新生成、实现改了注解没改、breaking change 未标注
 - 输出契约一致性验证报告
 
 执行流程：
-1. 读取 API 路由实现代码（controller/router 文件）
-2. 读取已有 OpenAPI/Swagger 文档（如有）
+1. 读取 API 路由实现代码（controller/router 文件 + 类型/DTO 定义）
+2. 定位项目的 OpenAPI spec 来源（`/openapi.json` 端点、`swagger.yaml` 文件、`@nestjs/swagger` 插件输出等）
 3. 逐端点对比：路径、HTTP 方法、参数名/类型/必填、响应 status/schema
-4. 标记每条端点的状态：✅ 一致 / ⚠ 文档过时 / ❌ 未文档化 / 🔴 breaking change
+4. 标记每条端点的状态：✅ 一致 / ⚠ spec 过时（代码改了文档没更新）/ ❌ 未文档化（缺少注解）/ 🔴 breaking change
 5. 输出 `docs/testing/YYYY-MM-DD-<topic>-api-contract-report.md`
 
+**常见框架的 spec 来源**：
+| 框架 | 自动生成机制 | 获取方式 |
+|------|-------------|---------|
+| FastAPI | Pydantic 模型 → OpenAPI | `GET /openapi.json` |
+| NestJS | `@nestjs/swagger` 装饰器 | SwaggerModule 生成的 `/api-json` |
+| Spring Boot | springdoc-openapi 注解 | `/v3/api-docs` |
+| Express | swagger-jsdoc 注释 | 构建输出的 `swagger.json` |
+| Go (swaggo) | 代码注释 → `swag init` | `docs/swagger.json` |
+| Django | drf-spectacular | `GET /api/schema/` |
+
 **红线**：不编写 API 实现代码、不修改路由、不凭记忆对比。
 
 ## 模式 B：手写 API 参考文档（按需触发）

package/README.md

@@ -1,12 +1,12 @@
 # Jarvis Agent Factory · 贾维斯智能体工厂
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-[![Version](https://img.shields.io/badge/version-v2.1.0-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
+[![Version](https://img.shields.io/badge/version-v2.1.5-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
 <br>**简体中文** | [English](./README_EN.md)
 
 一套跨平台的多智能体（Multi-Agent）AI 编程助手配置集，定义了一条**从想法到交付的完整软件开发流水线**。支持 Claude Code、OpenCode、Codex 三平台，共享同一套工作流规范与技能体系。
 
-> **v2.1.0** — Claude Code 47 agents + 15 commands / OpenCode 55 agents（纯智能体切换） / Codex 45 agents + 42 skills（Skill 触发）
+> **v2.1.5** — Claude Code 47 agents + 15 commands / OpenCode 55 agents（纯智能体切换） / Codex 45 agents + 42 skills（Skill 触发）
 
 ## 核心概念
 
@@ -44,6 +44,7 @@
 | 3 | **Bug 闭环** | `bug-fix` | Bug → agent-browser 复现 → 定位根因 → 修复 → 验证 |
 | 4 | **审查闭环** | `review-fix-optimize` | 初审 → 规划 → 执行 → 验证 → 复审关闭 |
 | 5 | **安全闭环** | Gate E | security-auditor → 威胁建模 + CVE + SAST → 修复 → 重扫 |
+| 6 | **契约闭环** | Gate C2（API 变更强制） | api-docs-worker 模式A → 对比 auto-generated spec vs 代码实现 → 标记漂移 |
 
 失败自动路由到修复闭环，最多 2 轮；第 3 轮仍失败标记 BLOCKED 并保留产物。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-agent-factory",
-  "version": "2.1.4",
+  "version": "3.0.0-alpha",
   "description": "Jarvis Agent Factory CLI — 跨平台多智能体 AI 编程助手配置安装器 | Multi-agent AI coding assistant config installer for Claude Code / OpenCode / Codex",
   "keywords": [
     "jarvis",
@@ -41,5 +41,9 @@
   ],
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1"
   }
 }

package/src/cli.js

@@ -6,6 +6,7 @@ import { createInterface } from 'node:readline';
 import { homedir } from 'node:os';
 import { install } from './install.js';
 import { doctor } from './doctor.js';
+import { startEngine, stopEngine, engineStatus } from './engine/server.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -32,7 +33,10 @@ Usage:
   jarvis add <p...> [path]       Add platform(s) to project
   jarvis remove <p...> [path]    Remove platform(s) from project
   jarvis upgrade [path]          Upgrade to latest config version
-  jarvis doctor [path]           Verify installation
+  jarvis engine start [--dashboard] [--port=N]  Start MCP orchestration server
+  jarvis engine stop                              Stop engine
+  jarvis engine status                            Engine status
+  jarvis doctor [path]                            Verify installation
 
 Options:
   -g, --global    Target user global directory instead of project
@@ -206,6 +210,21 @@ export async function run() {
       break;
     }
 
+    case 'engine': {
+      const sub = positional[1];
+      if (sub === 'start') {
+        const port = parseInt(positional.find(a => a.startsWith('--port='))?.split('=')[1] || '3456');
+        const dashboard = positional.includes('--dashboard') || positional.includes('-d');
+        await startEngine({ port, dashboard, projectRoot: positional.find(a => !a.startsWith('-') && a !== 'start' && a !== 'engine') || '.' });
+      } else if (sub === 'stop') {
+        stopEngine();
+      } else if (sub === 'status') {
+        engineStatus();
+      } else {
+        console.log('\nUsage: jarvis engine <start|stop|status> [--dashboard] [--port=<N>]\n');
+      }
+      break;
+    }
     case 'doctor':
     case 'check': {
       const path = positional[1];

package/src/engine/server.js

@@ -0,0 +1,223 @@
+import express from 'express';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * Jarvis Engine — HTTP MCP Server
+ * Phase 1: pipeline_status tool + requirements resource
+ *
+ * Start:  jarvis engine start [--port 3456] [--dashboard]
+ * Stop:   jarvis engine stop
+ * Status: jarvis engine status
+ */
+
+const PID_FILE = resolve(homedir(), '.jarvis', 'engine.pid');
+const DEFAULT_PORT = 3456;
+
+export async function startEngine({ port = DEFAULT_PORT, dashboard = false, projectRoot = '.' } = {}) {
+  const root = resolve(projectRoot);
+
+  // Save PID
+  const pidDir = resolve(homedir(), '.jarvis');
+  if (!existsSync(pidDir)) {
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(pidDir, { recursive: true });
+  }
+  writeFileSync(PID_FILE, String(process.pid));
+
+  const app = express();
+  app.use(express.json());
+
+  // ---- MCP Server ----
+  const server = new McpServer({
+    name: 'jarvis-engine',
+    version: readPkgVersion(),
+  });
+
+  // Tool: pipeline_status
+  server.tool(
+    'pipeline_status',
+    '读取当前项目的流水线状态：当前 Gate、已通过 Gate、产物文件列表',
+    {},
+    async () => {
+      const gates = ['Gate A', 'Gate B', 'Gate C', 'Gate C1', 'Gate C1.5', 'Gate C2', 'Gate D', 'Gate E'];
+      const status = [];
+      const docsDir = join(root, 'docs');
+
+      for (const gate of gates) {
+        const results = findGateArtifacts(docsDir, gate);
+        status.push({ gate, complete: results.length > 0, artifacts: results });
+      }
+
+      const currentGate = status.find(g => !g.complete)?.gate || 'Gate E';
+      const completedGates = status.filter(g => g.complete).map(g => g.gate);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          project: root,
+          current_gate: currentGate,
+          completed_gates: completedGates,
+          gates: status,
+        }, null, 2) }],
+      };
+    }
+  );
+
+  // Resource: requirements://list
+  server.resource(
+    'requirements_list',
+    'requirements://list',
+    {
+      name: 'Requirements List',
+      description: '列出项目中所有 REQ-XXX 需求文档',
+      mimeType: 'text/markdown',
+    },
+    async () => {
+      const reqsDir = join(root, 'docs', 'requirements');
+      if (!existsSync(reqsDir)) {
+        return { contents: [{ uri: 'requirements://list', text: '# No requirements found\n\nRun Gate A first.', mimeType: 'text/markdown' }] };
+      }
+      const files = readdirSync(reqsDir).filter(f => f.endsWith('.md'));
+      if (files.length === 0) {
+        return { contents: [{ uri: 'requirements://list', text: '# No requirements yet\n\nNo REQ documents found.', mimeType: 'text/markdown' }] };
+      }
+      const list = files.map(f => {
+        const content = readFileSync(join(reqsDir, f), 'utf-8');
+        const reqMatch = content.match(/REQ-\d{3}/g);
+        const reqs = reqMatch ? [...new Set(reqMatch)] : [];
+        return `- **${f}** — ${reqs.join(', ') || 'no REQ found'}`;
+      }).join('\n');
+      return { contents: [{ uri: 'requirements://list', text: `# Requirements\n\n${list}`, mimeType: 'text/markdown' }] };
+    }
+  );
+
+  // Resource: requirement detail
+  server.resource(
+    'requirement_detail',
+    'requirements://{reqId}',
+    {
+      name: 'Requirement Detail',
+      description: '读取指定 REQ-XXX 的完整需求文档内容',
+      mimeType: 'text/markdown',
+    },
+    async (uri) => {
+      const reqId = uri.pathname.replace('/requirements/', '').replace('/', '');
+      const reqsDir = join(root, 'docs', 'requirements');
+      if (!existsSync(reqsDir)) return { contents: [{ uri: uri.href, text: `# ${reqId} — Not Found`, mimeType: 'text/markdown' }] };
+
+      const files = readdirSync(reqsDir).filter(f => f.endsWith('.md'));
+      for (const f of files) {
+        const content = readFileSync(join(reqsDir, f), 'utf-8');
+        if (content.includes(reqId)) {
+          return { contents: [{ uri: uri.href, text: content, mimeType: 'text/markdown' }] };
+        }
+      }
+      return { contents: [{ uri: uri.href, text: `# ${reqId} — Not Found`, mimeType: 'text/markdown' }] };
+    }
+  );
+
+  // ---- MCP Transport ----
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  });
+
+  app.post('/mcp', async (req, res) => {
+    try {
+      await transport.handleRequest(req, res, req.body);
+    } catch (e) {
+      console.error('MCP error:', e.message);
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.get('/mcp/sse', async (req, res) => {
+    await transport.handleRequest(req, res, undefined);
+  });
+
+  await server.connect(transport);
+
+  // ---- Health ----
+  app.get('/health', (_req, res) => res.json({ status: 'ok', version: readPkgVersion() }));
+
+  // ---- Dashboard (placeholder) ----
+  if (dashboard) {
+    app.get('/dashboard', (_req, res) => {
+      res.send(`<!DOCTYPE html><html><head><title>Jarvis Engine</title>
+<style>body{font-family:system-ui;max-width:800px;margin:40px auto;padding:20px;background:#111;color:#eee}
+h1{color:#FF6B35}.card{background:#1a1a2e;border-radius:8px;padding:16px;margin:8px 0}</style></head>
+<body><h1>🧠 Jarvis Engine v${readPkgVersion()}</h1>
+<div class="card"><h3>MCP Endpoint</h3><code>POST /mcp</code> · <code>GET /mcp/sse</code></div>
+<div class="card"><h3>Tools</h3><p>pipeline_status — 流水线状态</p></div>
+<div class="card"><h3>Resources</h3><p>requirements://list · requirements://{reqId}</p></div>
+</body></html>`);
+    });
+  }
+
+  // Start server
+  app.listen(port, () => {
+    console.log(`🧠 Jarvis Engine v${readPkgVersion()} — http://localhost:${port}`);
+    console.log(`   MCP:  POST http://localhost:${port}/mcp`);
+    if (dashboard) console.log(`   Web:  http://localhost:${port}/dashboard`);
+    console.log(`   PID:  ${process.pid} (saved to ${PID_FILE})`);
+  });
+}
+
+export function stopEngine() {
+  if (!existsSync(PID_FILE)) {
+    console.log('No running engine found.');
+    return;
+  }
+  const pid = readFileSync(PID_FILE, 'utf-8').trim();
+  try {
+    process.kill(Number(pid), 'SIGTERM');
+    const { unlinkSync } = require('node:fs');
+    try { unlinkSync(PID_FILE); } catch {}
+    console.log(`Engine stopped (PID ${pid}).`);
+  } catch {
+    console.log(`Engine not running (stale PID ${pid}).`);
+    try { require('node:fs').unlinkSync(PID_FILE); } catch {}
+  }
+}
+
+export function engineStatus() {
+  if (!existsSync(PID_FILE)) {
+    console.log('Engine: not running');
+    return false;
+  }
+  const pid = readFileSync(PID_FILE, 'utf-8').trim();
+  try { process.kill(Number(pid), 0); } catch {
+    console.log(`Engine: not running (stale PID ${pid})`);
+    try { require('node:fs').unlinkSync(PID_FILE); } catch {}
+    return false;
+  }
+  console.log(`Engine: running (PID ${pid})`);
+  return true;
+}
+
+function readPkgVersion() {
+  try {
+    return JSON.parse(readFileSync(resolve(import.meta.dirname, '..', '..', 'package.json'), 'utf-8')).version;
+  } catch { return '?.?.?'; }
+}
+
+function findGateArtifacts(docsDir, gate) {
+  const gateMap = {
+    'Gate A': 'requirements',
+    'Gate B': 'tasks',
+    'Gate C': 'plans',
+    'Gate C1': 'implementation',
+    'Gate C1.5': 'implementation',
+    'Gate C2': 'testing',
+    'Gate D': 'review',
+    'Gate E': 'shipping',
+  };
+  const subdir = gateMap[gate];
+  if (!subdir) return [];
+  const dir = join(docsDir, subdir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(f => f.endsWith('.md')).slice(0, 5);
+}