jarvis-agent-factory 3.7.0 → 3.7.2

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.5-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
+[![Version](https://img.shields.io/badge/version-v3.7.0-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
 <br>**简体中文** | [English](./README_EN.md)
 
 一套跨平台的多智能体（Multi-Agent）AI 编程助手配置集，定义了一条**从想法到交付的完整软件开发流水线**。支持 Claude Code、OpenCode、Codex 三平台，共享同一套工作流规范与技能体系。
 
-> **v2.1.5** — Claude Code 47 agents + 15 commands / OpenCode 55 agents（纯智能体切换） / Codex 45 agents + 42 skills（Skill 触发）
+> **v3.7.0** — MCP 编排引擎 + 硬约束状态机 + 三平台钩子驱动 + npm CLI 一键部署
 
 ## 核心概念
 
@@ -48,6 +48,41 @@
 
 失败自动路由到修复闭环，最多 2 轮；第 3 轮仍失败标记 BLOCKED 并保留产物。
 
+## 编排引擎（v3）
+
+```
+提示词工程（软约束）→ 引擎驱动（硬约束）
+"请勿跳过 Gate"       → FSM 直接拒绝非法操作
+```
+
+| 组件 | 说明 |
+|------|------|
+| **MCP Server** | 4 个编排工具：pipeline_init / status / gate_enforce / advance_gate |
+| **硬约束 FSM** | 跳过 Gate 被拒 / 乱序推进被拒 / 条件未满足被拒 |
+| **SQLite 持久化** | pipeline + sessions + checkpoints + agent_models 四表 |
+| **Session 管理** | Leader 选举 + 心跳超时 + Observer 只读 |
+| **三平台钩子** | PostToolUse{Agent} → `jarvis hook gate-check`，每次 spawn 后自动验证 |
+| **Web Dashboard** | Gate 进度条 + Agent 像素模型配置卡片 + SSE 实时推送 |
+| **REST API** | `/api/pipeline` `/api/gate/enforce` `/api/gate/advance` `/api/agents` |
+
+```bash
+jarvis engine start --dashboard   # 启动引擎 + Web 面板 → localhost:3456
+jarvis engine stop                # 停止
+```
+
+## 架构
+
+```
+src/
+├── engine/     🧠 MCP Server + SQLite + FSM 状态机
+├── web/        🌐 REST API + Dashboard + SSE
+├── cli.js      ⌨️  init/add/remove/upgrade/doctor/engine/hook
+├── install.js  📥  平台安装 + MCP 生成 + 钩子注入
+├── templates/  📋  三平台配置模板 + MCP 模板 + 钩子模板
+│   └── platforms/{claude,opencode,codex}/  ← 单一事实源
+└── hook.js     🪝  gate-check / gate-advance / status
+```
+
 ## 使用方法
 
 ### npm CLI（推荐）
@@ -201,19 +236,22 @@ npm i -g agent-browser && agent-browser install
 ## 目录结构
 
 ```
-.claude/                         # Claude Code
-  settings.json                  #   权限与全局设置
-  commands/                      #   15 个 slash 命令
-  agents/                        #   47 个智能体
-  skills/                        #   27 个技能
-
-.opencode/                       # OpenCode
-  agents/                        #   55 个智能体（10 主智能体 + 45 子智能体）
-  skills/                        #   27 个技能（无命令目录）
-
-.codex/                          # Codex
-  agents/                        #   45 个智能体
-  skills/                        #   42 个技能（含 13 个主流程 + 15 个共享技能 + review-only/fix-optimize）
+src/
+├── templates/platforms/         # 📦 配置模板（单一事实源）
+│   ├── claude/                  #   47 agents + 15 commands + 27 skills
+│   ├── opencode/                #   55 agents + 27 skills
+│   └── codex/                   #   45 agents + 42 skills + config.toml
+├── engine/                      # 🧠 引擎层
+│   ├── server.js                #   MCP HTTP Server
+│   ├── db.js                    #   SQLite 持久化（WAL）
+│   └── gates.js                 #   状态机 + Agent 定义
+├── web/                         # 🌐 Web 层
+│   ├── routes.js                #   REST API + SSE
+│   └── views/                   #   Dashboard HTML
+├── templates/                   # 📋 MCP + 钩子模板
+├── cli.js                       # ⌨️  CLI 入口
+├── install.js                   # 📥 安装 + 钩子注入
+└── hook.js                      # 🪝 钩子集成
 ```
 
 ## 设计原则

package/package.json

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

package/src/templates/platforms/claude/commands/jarvis.md

@@ -13,6 +13,8 @@ description: 启动贾维斯编排模式——需求→文档→任务→计划
    Gate C1 时加载：`Skill("code-quality-gate")`
    Gate E 时加载：`Skill("shipping-and-launch")` `Skill("git-workflow-and-versioning")` `Skill("finishing-a-development-branch")`
 
+   **引擎检查**：如果项目中有 `.jarvis/engine.db`，说明引擎已就绪。每个 Gate 通过后调用 `jarvis hook gate-advance` 推进硬状态机。
+
 2. 判断当前需求是否适合流水线：
    - ❌ **不适合**：用户提问信息量（"有多少模块？"）、明确要求单 agent 执行、纯文档格式化翻译
    - ✅ **适合**：开发、改造、配置、调试、Bug 修复、新功能
@@ -110,7 +112,7 @@ Batch 3: [TASK-005, TASK-006]                ← 依赖 Batch 2 完成
 
 ## 🟠 Gate C1：代码质量门（不可绕过）
 
-实现完成后的第一道质量门。**不可绕过。** 加载 `Skill("code-quality-gate")` 执行四项检查（Lint → Type-check → Build → Deps Audit），按技能中的项目类型工具链表选择命令。全部通过后输出质量检查摘要，作为 Gate C2 前置输入。
+实现完成后的第一道质量门。**不可绕过。** 加载 `Skill("code-quality-gate")` 执行四项检查（Lint → Type-check → Build → Deps Audit），按技能中的项目类型工具链表选择命令。全部通过后输出质量检查摘要，作为 Gate C2 前置输入。通过后 `jarvis hook gate-advance`。
 
 必须**全部**满足才能进入 Gate C2：
 - [ ] **Lint 零错误**（warning 可接受但需记录）
@@ -174,7 +176,7 @@ Gate C1（+ Gate C1.5 如适用）通过后方可进入此门。
   │     └── spawn e2e-test-worker
   │
   ├── 步骤 6：测试结果汇总 → docs/testing/...
-  └── Gate C2 通过 → 进入 Gate D 评审
+  ├── Gate C2 通过 → `jarvis hook gate-advance` → 进入 Gate D 评审
 ```
 
 ### test_after 策略规范

package/src/templates/platforms/codex/skills/jarvis/SKILL.md

@@ -77,6 +77,22 @@ description: 贾维斯编排模式——需求→文档→任务→计划→实
 | 基础设施 | `infra_worker` `api_docs_worker` |
 | 探索 | `repo_explorer` `docs_researcher` |
 
+## Execution Packet 模板
+
+spawn 子 Agent 时必须传递以下字段：
+
+```
+### task_id: TASK-XXX
+### task_name: <名称>
+### requirement_ids: REQ-XXX
+### objective: <一句话目标>
+### allowed_paths / forbidden_paths: <文件路径>
+### required_skills: <技能列表。子Agent启动后逐一加载。planner按技能分配规则指定>
+### acceptance_criteria: <可验证验收条件>
+### test_strategy: tdd / test_after / manual_only
+### escalation_rule: 共享区域变更必须先回编排者
+```
+
 ## Plan Patch 机制
 
 实现 Agent 变更共享区域前必须提交 plan patch（提出者/关联任务/冲突描述/建议变更/影响评估/替代方案），编排者评估决策后更新计划。

package/src/templates/platforms/opencode/agents/planner.md

@@ -1,13 +1,11 @@
----
+---
+name: planner
 description: "在需求文档已通过 Gate A、任务文档已通过 Gate B 后使用；选择当前轮次任务包，生成执行计划，并明确实现代理分工、共享改动归属与 Execution Packet。"
-mode: subagent
-model: deepseek/deepseek-v4-pro
-reasoningEffort: max
-permission:
-  edit: allow
-  bash: allow
-  task: deny
+tools: Read, Write, Edit, Bash, Glob, Grep, Skill
+effort: max
+model: deepseek-v4-pro
 ---
+
 你是执行规划代理。
 
 ## 工作流编排位置
@@ -63,20 +61,42 @@ permission:
 - TDD 任务的 Red→Green→Refactor 必须串行
 - 不同 TDD 任务的 Red 步骤可并行
 
+### 技能分配规则
+
+根据任务类型和 test_strategy，在 Execution Packet 中指定 `required_skills`。子 Agent 收到后会在启动时加载这些技能。
+
+| 任务场景 | required_skills（基础 + 场景） |
+|---------|------|
+| 所有任务（基础） | `behavioral-guidelines` `code-standards` |
+| 代码实现 | + `source-driven-development` `incremental-implementation` `verification-before-completion` |
+| TDD 任务 | + `test-driven-development` |
+| 前端 UI/组件 | + `source-driven-development` `incremental-implementation` `verification-before-completion` |
+| 后端业务逻辑 | + `source-driven-development` `incremental-implementation` `verification-before-completion` |
+| 代码审查 | + `code-review-and-quality` |
+| 架构设计 | + `source-driven-development` `documentation-and-adrs` |
+| 安全审计 | + `security-and-hardening` |
+| 数据层/DB | + `source-driven-development` |
+| 性能测试 | + `debugging-and-error-recovery` |
+| E2E 测试 | + `debugging-and-error-recovery` `verification-before-completion` |
+| 浏览器测试 | + `agent-browser` `browser-testing` |
+| Bug 修复 | + `source-driven-development` `debugging-and-error-recovery` |
+| 重构 | + `code-simplification` `source-driven-development` `verification-before-completion` |
+| API 文档 | + `source-driven-development` `chinese-documentation` |
+| 发布/部署 | + `shipping-and-launch` `git-workflow-and-versioning` `finishing-a-development-branch` |
+
+> 若任务有项目专属 skill（如 `.claude/skills/my-custom-skill/`），编排者可在 Execution Packet 的 `required_skills` 中追加。
+
 ### 变更规模控制
 
 单轮次所有任务的预期变更总行数不应超过 ~1000 行。超过时考虑拆分为两个轮次。
 
-## 行为准则
+## 技能加载（必须执行）
 
-**必须遵守**：加载并遵守 `behavioral-guidelines` 技能中定义的四项核心行为准则：
+**开始规划前，必须调用 `Skill` 工具加载技能。**
 
-1. **先思考，再编码** — 不假设。不隐藏困惑。主动暴露权衡。不确定时先问，多种解释时列出全部方案。
-2. **简单优先** — 最小代码解决问题。不添加需求外功能，不为单点使用创建抽象，不为不可能场景做错误处理。
-3. **精准修改** — 只动必须动的，遵循现有风格，每个改动行可追溯到用户请求。移除自身改动造成的孤儿代码。
-4. **目标驱动执行** — 将任务转化为可验证目标。先写测试再使其通过。多步骤时陈述计划与验证点。
-
-> 完整准则见技能：`behavioral-guidelines`。简单任务可自行判断，有疑问时优先谨慎。
+```
+Skill(skill="behavioral-guidelines")
+```
 
 ## 反合理化表
 
@@ -151,7 +171,7 @@ permission:
 
 ## parallel_batches 输出格式（必须使用）
 
-计划文档中必须包含以下格式的并行批次定义，确保编排者可以直接解析并 spawn Task：
+计划文档中必须包含以下格式的并行批次定义，确保主 Build Agent 可以直接解析并 spawn Agent：
 
 ```
 ## parallel_batches
@@ -217,6 +237,7 @@ permission:
 ### allowed_paths: <允许修改的目录/文件>
 ### forbidden_paths: <禁止修改的共享区域>
 ### dependencies: <依赖的 API / 契约 / schema>
+### required_skills: <技能列表，按上方「技能分配规则」填写。子 Agent 启动后必须逐一 Skill() 加载>
 ### parallel_group: <可与此任务并行的任务 ID 列表>
 ### wait_for: <必须等待完成的任务 ID 列表>
 ### acceptance_criteria: <可验证的验收条件>