jarvis-agent-factory 3.7.2 → 3.8.0

package/README.md

@@ -1,273 +1,186 @@
 # Jarvis Agent Factory · 贾维斯智能体工厂
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-[![Version](https://img.shields.io/badge/version-v3.7.0-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
+[![Version](https://img.shields.io/badge/version-v3.7.2-green)](https://gitee.com/wujl1124/JarvisAgentFactory/releases)
+[![npm](https://img.shields.io/npm/v/jarvis-agent-factory)](https://www.npmjs.com/package/jarvis-agent-factory)
 <br>**简体中文** | [English](./README_EN.md)
 
-一套跨平台的多智能体（Multi-Agent）AI 编程助手配置集，定义了一条**从想法到交付的完整软件开发流水线**。支持 Claude Code、OpenCode、Codex 三平台，共享同一套工作流规范与技能体系。
+跨平台多智能体 AI 编程助手配置集 + MCP 编排引擎。从想法到交付的完整软件开发流水线，支持 **Claude Code / OpenCode / Codex** 三平台。
 
-> **v3.7.0** — MCP 编排引擎 + 硬约束状态机 + 三平台钩子驱动 + npm CLI 一键部署
+> **v3.7.2** — 提示词工程（软约束）→ 引擎驱动（硬约束），FSM 直接拒绝非法操作
 
-## 核心概念
+## 快速开始
 
-**Jarvis（贾维斯）**——唯一的编排中枢，直接与用户对话，通过 Agent/Task 工具调度所有子智能体。子智能体职责单一、不可递归调度，所有阶段必须通过对应闸门（Gate）检查。
-
-### 工作流
-
-```
-想法细化 → 需求澄清 → 需求文档 → 任务分解 → 执行规划 → 并行实现 → 代码质量 → 视觉验证 → 测试 → 评审 → 发布
-   │         │        │         │         │         │         │         │         │         │         │
-   └─ 阶段 0           Gate A    Gate B    Gate C    │    Gate C1    Gate C1.5  Gate C2    Gate D    Gate E
-                                                     │
-                                          ┌──────────┘
-                                          │ 同 Batch 内任务并行
-                                          │ Batch 之间串行等待
-                                          └── 无共享依赖 → 可跨 Batch 提前启动
+```bash
+npm i -g jarvis-agent-factory   # 安装 CLI
+jarvis init my-app -y           # 一键部署三平台配置 + MCP + 钩子
+cd my-app
+jarvis engine start --dashboard # 启动编排引擎 + Web 面板
+# → http://localhost:3456/dashboard
 ```
 
-### 故障恢复
-
-| 维度 | 策略 |
-|------|------|
-| **Agent 重试** | 4 种失败类型差异化重试，最多 3 次 |
-| **Batch 部分失败** | 成功产物保留，仅重试失败任务 |
-| **回滚/中止** | 可修复→重试→回退→中止，同 Gate 最多回退 2 次 |
-| **会话检查点** | 每个 Gate 通过后输出检查点，支持中断恢复 |
-| **冲突解决** | Plan patch 排队，数据层 > API 层 > UI 层，10 分钟超时 |
-
-## 闭环体系
-
-| # | 闭环 | 触发 | 流程 |
-|---|------|------|------|
-| 1 | **开发闭环** | 编排者 Gate C→C1→C2 | 实现 → 质量检查 → 测试 → 失败回退 |
-| 2 | **测试闭环** | `browser-test` | 写用例 → agent-browser 执行 → 截图 → 失败→修复→重测 |
-| 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 并保留产物。
+然后在你用的平台里开始开发。引擎会在后台自动检查 Gate 条件，Dashboard 实时显示进度。
 
-## 编排引擎（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                # 停止
+jarvis init ./my-project        # 安装全部三平台配置 + MCP + 钩子
 ```
 
-## 架构
+这一步会在项目里生成：
 
 ```
-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
+my-project/
+├── .claude/          ← Claude Code: 47 agents + 15 命令 + 27 skills
+│   └── settings.json ← 含引擎钩子（PostToolUse{Agent} → gate-check）
+├── .opencode/        ← OpenCode: 55 agents + 27 skills
+├── .codex/           ← Codex: 45 agents + 42 skills
+│   └── hooks.json    ← Codex 钩子
+├── .mcp.json         ← Playwright + Jarvis Engine MCP 配置
+└── opencode.json     ← OpenCode MCP 配置
 ```
 
-## 使用方法
-
-### npm CLI（推荐）
+### 第二步：启动引擎
 
 ```bash
-npm i -g jarvis-agent-factory
+jarvis engine start --dashboard   # 后台运行 + Web 面板
+jarvis engine start               # 纯后台（无面板）
 ```
 
-| 命令 | 说明 |
-|------|------|
-| `jarvis` | 引导当前目录（≡ `jarvis init .`） |
-| `jarvis init [path]` | 初始化项目，安装全部三平台 + Playwright MCP 配置 |
-| `jarvis add <p...> [path]` | 添加指定平台（`claude` `opencode` `codex` 可多选） |
-| `jarvis remove <p...> [path]` | 移除指定平台 + 对应 MCP 配置 |
-| `jarvis upgrade [path]` | 升级已安装的配置到最新版本 |
-| `jarvis doctor [path]` | 健康检查 |
-| `-g, --global` | 安装到用户全局目录 `~/.claude/` 等 |
-| `-y, --yes` | 跳过覆盖确认 |
-| `-v, --version` | 查看版本 |
-| `-h, --help` | 帮助 |
+引擎监听 `localhost:3456`，SQLite 持久化状态到 `.jarvis/engine.db`。
 
-```bash
-# 常用
-jarvis                                  # 引导当前目录
-jarvis init my-app -y                   # 一键初始化
-jarvis add claude                       # 追加 Claude Code
-jarvis remove codex                     # 移除 Codex
-jarvis upgrade                          # 升级配置
-jarvis doctor                           # 检查
-
-# 全局安装
-jarvis init -g -y                       # 一键全局安装
-jarvis add opencode -g                  # 全局追加 OpenCode
-```
+### 第三步：在平台里开发
 
-### 手动安装
+**Claude Code：**
+```
+/jarvis "做一个登录页"
+```
+命令自动按 Gate A→B→C→... 流程推进。每次 spawn 子 Agent 后，引擎钩子自动触发 `gate-check` 验证条件。
 
+**OpenCode：**
 ```bash
-cp -r path/to/.claude/ your-project/
-claude
+opencode --agent frontend        # 切换到前端编排中枢
+# 然后说"做一个登录页"
 ```
+OpenCode 原生兼容 Claude Code 钩子格式，同样自动触发 `gate-check`。
 
-**领域开发命令**（完整生命周期 A→B→C→C1→C1.5→C2→D→E，不可绕过）：
-
-| 命令 | 领域 | 专属 Agent |
-|------|------|-----------|
-| **`/backend`** | 后端 | backend-implementer, backend-api/data/service-worker, backend-test-worker, database-specialist, performance-test-worker, security-auditor, api-docs-worker, infra-worker |
-| **`/frontend`** | 前端 | frontend-implementer, frontend-ui/state-worker, frontend-test-worker, browser-test-worker, e2e-test-worker, performance-audit-reviewer, security-auditor, infra-worker |
-| **`/taro`** | Taro 小程序/H5 | taro-worker, taro-ui/state-worker, browser-test-worker, e2e-test-worker |
-| **`/android`** | Android | android-worker, android-ui/state-worker, e2e-test-worker |
-| **`/ios`** | iOS | ios-worker, ios-ui/state-worker, e2e-test-worker |
-| **`/expo`** | Expo 跨端 | react-native-worker, rn-ui/state-worker, browser-test-worker, e2e-test-worker |
-| **`/flutter`** | Flutter | flutter-worker, flutter-ui/state-worker, browser-test-worker, e2e-test-worker |
-
-**专项命令**：
-
-| 命令 | 用途 |
-|------|------|
-| **`/jarvis`** | 全栈流水线编排（跨领域完整生命周期） |
-| **`/browser-test`** | 浏览器自动化测试闭环（agent-browser） |
-| **`/bug-fix`** | Bug 修复闭环（agent-browser 复现→修复→验证） |
-| **`/review`** | 只读审查模式（不修改文件） |
-| **`/review-fix`** | 审查修复优化闭环（初审→规划→执行→验证→复审） |
-| **`/algorithm-expert`** | 算法专家（选型/复杂度/性能优化） |
-| **`/frontend-architect`** | 前端架构师（技术选型/组件架构/构建策略） |
-| **`/backend-architect`** | 后端架构师（微服务/数据库/分布式） |
-
-### OpenCode
-
+**Codex：**
 ```bash
-opencode --agent frontend       # 切换至前端编排中枢
-opencode --agent backend        # 切换至后端编排中枢
-opencode --agent jarvis         # 切换至全栈编排中枢
+codex                            # 启动后加载 jarvis skill
+# 然后说"做一个登录页"
 ```
+Codex 钩子在每次 Bash 工具执行后自动触发 gate-check。
 
-55 智能体 + 0 命令，**纯智能体切换模式**：切换到主智能体即可进入对应领域的完整生命周期（Gate A→B→C→C1→C1.5→C2→D→E）。
+### 第四步：查看进度
 
-| 主智能体 | 领域 |
-|---------|------|
-| `jarvis` | 全栈编排 |
-| `frontend` `backend` | 前后端 |
-| `taro` `android` `ios` `expo` `flutter` | 移动端五平台 |
-| `review-only` | 只读审查 |
-| `review-fix-optimize` | 审查修复闭环 |
+打开 `http://localhost:3456/dashboard` 查看：
+- Gate 进度条（A→B→C→...→E）
+- 点 Gate 行 → 检查条件是否满足
+- 点 **Advance →** 推进到下一 Gate
+- `/agents` 页配置每个子 Agent 的模型
 
-### Codex
+### 引擎提供的能力
 
-```bash
-cp -r path/to/.codex/ your-project/
-```
+| 能力 | 机制 | 自动/手动 |
+|------|------|----------|
+| 每次 Agent spawn 后检查 Gate 条件 | **钩子**（PostToolUse） | 🔄 自动 |
+| 条件不满足时报警 | **钩子** → `gate_enforce` | 🔄 自动 |
+| 推进到下一个 Gate | `jarvis hook gate-advance` | 👆 编排者手动调用 |
+| 跳过 Gate 被拒绝 | **FSM** 硬约束 | 🔄 自动 |
+| 乱序推进被拒绝 | **FSM** 硬约束 | 🔄 自动 |
+| 查看流水线状态 | **Dashboard** / `jarvis hook status` | 👆 按需 |
+| Session 并发控制 | **Leader 选举 + 写锁** | 🔄 自动 |
+
+---
 
-45 智能体 + 42 技能，**Skill 触发模式**：加载技能进入对应工作流。
+## 三平台适配确认
 
-| 技能 | 用途 |
-|------|------|
-| `jarvis` `frontend` `backend` `android` `ios` `flutter` `expo` `taro` | 领域生命周期 |
-| `algorithm-expert` `backend-architect` `frontend-architect` | 专家对话 |
-| `browser-test` `bug-fix` | 测试闭环 |
-| `review-only` `review-fix-optimize` | 审查模式 |
+| 适配项 | Claude Code | OpenCode | Codex |
+|------|:--:|:--:|:--:|
+| **编排入口** | `/` 命令 | 智能体切换 `--agent` | Skill 加载 |
+| **子 Agent 格式** | `.md` + `tools:` | `.md` + `permission:` | `.toml` + `sandbox_mode` |
+| **Spawn 机制** | `Agent()` | `Task()` | Task via skill |
+| **钩子机制** | `settings.json` hooks | 原生兼容 Claude 格式 | `.codex/hooks.json` |
+| **MCP 引擎连接** | `.mcp.json` `:3456/mcp` | `opencode.json` `:3456/mcp` | `config.toml` `:3456/mcp` |
+| **Playwright MCP** | ✅ 28 tools | ✅ `mcp: playwright: allow` | ✅ config.toml |
+| **e2e/browser-test 边界** | ✅ 明确分离 | ✅ 明确分离 | ✅ 明确分离 |
+| **required_skills** | ✅ 4处 | ✅ 4处 | ✅ jarvis skill |
+| **子 Agent 隔离** | `Skill` tool | `task: deny` (44 agent) | TOML 独立 |
 
-## 浏览器自动化
+---
 
-统一使用 **agent-browser** CLI（Vercel Labs, 29K+ GitHub stars，80+ 命令），替代 Claude in Chrome MCP 和 browser-use。
+## CLI 命令
 
 ```bash
-npm i -g agent-browser && agent-browser install
-```
+jarvis                                  # 引导当前目录
+jarvis init [path] -y                   # 初始化项目
+jarvis add <claude|opencode|codex>      # 添加平台（多选）
+jarvis remove <platform> [path]         # 移除平台
+jarvis upgrade [path]                   # 升级配置
+jarvis doctor [path]                    # 健康检查
 
-- **快照+引用**：`agent-browser snapshot -i` → `@e1, @e2` 紧凑元素引用，token 高效
-- **Chrome profile**：`agent-browser --profile "Default" open <url>` 复用登录态
-- **全能力覆盖**：网络监控、控制台日志、性能追踪、视觉回归、React DevTools
-- Claude Code 额外搭配 Preview MCP 做本地开发预览验证
-
-## 智能体体系
-
-| 类别 | 智能体 |
-|------|--------|
-| **编排中枢（Primary）** | `jarvis`（全栈）、`frontend`、`backend`、`android`、`ios`、`flutter`、`expo`、`taro` |
-| **审查主控（Primary）** | `review-only`（只读）、`review-fix-optimize`（审查修复闭环） |
-| **规划与评审** | `task-design`、`planner`、`review-qa` |
-| **探索与资料** | `repo-explorer`、`docs-researcher` |
-| **架构设计** | `algorithm-expert`、`frontend-architect`、`backend-architect`、`database-specialist` |
-| **审查与修复** | `project-audit-reviewer`、`diff-code-reviewer`、`performance-audit-reviewer`、`security-auditor`、`remediation-planner`、`remediation-worker`、`post-change-reviewer` |
-| **后端实现** | `backend-implementer`、`backend-api-worker`、`backend-service-worker`、`backend-data-worker`、`backend-test-worker` |
-| **前端实现** | `frontend-implementer`、`frontend-ui-worker`、`frontend-state-worker`、`frontend-test-worker` |
-| **移动端** | `taro-worker`、`android-worker`、`ios-worker`、`react-native-worker`（Expo）、`flutter-worker`（各含 ui/state 子变体，共 15 个） |
-| **测试与文档** | `browser-test-worker`、`e2e-test-worker`、`performance-test-worker`、`api-docs-worker` |
-| **基础设施** | `infra-worker` |
-
-> **10 个 Primary 智能体**（OpenCode 专属）：支持 `opencode --agent <name>` 直接切换，每个都是完整的领域编排中枢，含独立 Gate 闭环。Claude Code 通过 `/command` 等价触发，Codex 通过 Skill 触发。
-
-## 技能系统
-
-**27 个共享技能**（三平台同步）+ Codex 额外 15 个主流程技能（共 42 个）：
-
-| 类别 | 技能 |
-|------|------|
-| **基础** | `behavioral-guidelines` `context-engineering` `using-agent-skills` |
-| **需求** | `spec-driven-development` `idea-refine` |
-| **规划** | `planning-and-task-breakdown` |
-| **实现** | `source-driven-development` `incremental-implementation` `test-driven-development` `code-standards` `code-simplification` |
-| **质量** | `code-quality-gate` `code-review-and-quality` `verification-before-completion` |
-| **调试** | `debugging-and-error-recovery` |
-| **浏览器** | `agent-browser` `browser-testing` |
-| **安全** | `security-and-hardening` |
-| **流程** | `shipping-and-launch` `git-workflow-and-versioning` `finishing-a-development-branch` |
-| **文档** | `chinese-documentation` `documentation-and-adrs` `writing-skills` |
-| **探索** | `find-docs` `find-skills` |
-| **工具** | `mcp-builder` |
-
-## 目录结构
+jarvis engine start [--dashboard]       # 启动编排引擎
+jarvis engine stop                      # 停止引擎
+jarvis engine status                    # 引擎状态
 
-```
-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                      # 🪝 钩子集成
-```
+jarvis hook gate-check                  # 钩子：检查 Gate 条件
+jarvis hook gate-advance                # 钩子：推进 Gate
+jarvis hook status [--json]             # 钩子：流水线状态
 
-## 设计原则
+# 选项：-g 全局  -y 跳过确认  -v 版本  -h 帮助
+```
 
-- **垂直切片** — 任务按端到端功能拆分，非技术层级
-- **闸门控制** — 每阶段必须满足条件才推进，不可绕过
-- **需求可追溯** — 每条代码变更追溯到 `REQ-XXX`
-- **共享区域唯一责任方** — 避免并行写入冲突
-- **最大并发** — 无依赖任务同消息批量调度
-- **注释语言约定** — 遵循 `behavioral-guidelines` 准则 5
+---
 
-## 致谢
+## 闭环体系
 
-- **[agent-browser](https://github.com/vercel-labs/agent-browser)** — Vercel Labs，浏览器自动化 CLI（80+ 命令），支撑测试与 Bug 闭环
-- **[superpowers](https://github.com/obra/superpowers)** — 技能即文档方法论
-- **[superpowers-zh](https://github.com/jnMetaCode/superpowers-zh)** — 中文技能体系参考
+| # | 闭环 | 流程 |
+|---|------|------|
+| 1 | **开发** | 实现 → Gate C1 质量门 → Gate C2 测试门 → 失败回退 |
+| 2 | **测试** | 写用例 → agent-browser 执行 → 截图 → 失败→修复→重测 |
+| 3 | **Bug 修复** | Bug → agent-browser 复现 → 定位根因 → 修复 → 验证 |
+| 4 | **审查** | 初审 → 规划 → 执行 → 验证 → 复审关闭 |
+| 5 | **安全** | security-auditor → 威胁建模 + CVE + SAST → 修复 |
+| 6 | **契约** | api-docs-worker 模式A → 对比 auto spec vs 实现 → 标记漂移 |
+
+---
+
+## 平台入口速查
+
+| 领域 | Claude Code | OpenCode | Codex |
+|------|-----------|----------|-------|
+| 全栈 | `/jarvis` | `--agent jarvis` | `jarvis` skill |
+| 前端 | `/frontend` | `--agent frontend` | `frontend` skill |
+| 后端 | `/backend` | `--agent backend` | `backend` skill |
+| Android | `/android` | `--agent android` | `android` skill |
+| iOS | `/ios` | `--agent ios` | `ios` skill |
+| Flutter | `/flutter` | `--agent flutter` | `flutter` skill |
+| Expo | `/expo` | `--agent expo` | `expo` skill |
+| Taro | `/taro` | `--agent taro` | `taro` skill |
+| 审查 | `/review` | `--agent review-only` | `review-only` skill |
+| 修复闭环 | `/review-fix` | `--agent review-fix-optimize` | `review-fix-optimize` skill |
+| 浏览器测试 | `/browser-test` | spawn browser-test-worker | `browser-test` skill |
+| Bug 修复 | `/bug-fix` | spawn via orchestrator | `bug-fix` skill |
+| 算法专家 | `/algorithm-expert` | `--agent algorithm-expert` | `algorithm-expert` skill |
+| 前端架构 | `/frontend-architect` | `--agent frontend-architect` | `frontend-architect` skill |
+| 后端架构 | `/backend-architect` | `--agent backend-architect` | `backend-architect` skill |
+
+---
+
+## 统计
+
+| | Claude Code | OpenCode | Codex |
+|---|:--:|:--:|:--:|
+| Agents | 47 | 55 | 45 |
+| Commands | 15 | 0 | 0 |
+| Skills | 27 | 27 | 42 |
+| 钩子 | settings.json | 兼容 Claude 格式 | hooks.json |
+
+---
 
 ## License
 

package/package.json

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

package/src/doctor.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
 
 /**
  * Check the health of installed Jarvis configurations.
@@ -52,10 +53,23 @@ export function doctor({ target, platforms, pkgRoot }) {
   }
 
   console.log('');
+  // Check engine status (sync — check PID file)
+  const pidFile = resolve(homedir(), '.jarvis', 'engine.pid');
+  let engineRunning = false;
+  if (existsSync(pidFile)) {
+    try { const pid = Number(readFileSync(pidFile, 'utf-8').trim()); process.kill(pid, 0); engineRunning = true; } catch {}
+  }
+  if (!engineRunning) {
+    console.log('\n  ⚠️  Engine not running. Gate enforcement is INACTIVE.');
+    console.log('  Start it: jarvis engine start [--dashboard]\n');
+    allOk = false;
+  }
+
   if (allOk) {
-    console.log('  ✅ All platforms OK\n');
+    console.log('  ✅ All platforms OK, engine running\n');
   } else {
-    console.log('  ⚠️  Some platforms need attention. Run `jarvis install <platform>` to fix.\n');
+    if (!engineRunning) console.log('  ⚠️  Start the engine to enable gate enforcement.\n');
+    else console.log('  ⚠️  Some platforms need attention. Run `jarvis add <platform>` to fix.\n');
   }
 }
 

package/src/hook.js

@@ -25,7 +25,12 @@ export async function hookCommand(args) {
       const g = await api(`/api/gate/${encodeURIComponent(current)}/enforce`);
       if (g.allowed) { console.log(`✅ ${current} — OK`); process.exit(0); }
       else { console.log(`🚫 ${current} BLOCKED — ${g.required}`); process.exit(1); }
-    } catch (e) { console.error(`⚠ Engine unreachable: ${e.message}`); process.exit(0); }
+    } catch (e) {
+      // Engine not running — warn loudly so user knows enforcement is absent
+      console.error(`\n⚠️  Jarvis Engine is NOT running. Gate enforcement is INACTIVE.`);
+      console.error(`   Start it: jarvis engine start\n`);
+      process.exit(2); // Exit 2 = block (Claude Code treats exit 2 as feedback)
+    }
   }
 
   else if (sub === 'gate-advance') {
@@ -34,7 +39,11 @@ export async function hookCommand(args) {
       const g = await r.json();
       if (g.allowed) { console.log(`🚀 ${g.previous} → ${g.current}${g.next ? ` (next: ${g.next})` : ''}`); process.exit(0); }
       else { console.log(`🚫 BLOCKED — ${g.error}`); process.exit(1); }
-    } catch (e) { console.error(`⚠ Engine unreachable: ${e.message}`); process.exit(0); }
+    } catch (e) {
+      console.error(`\n⚠️  Jarvis Engine is NOT running. Cannot advance gate.`);
+      console.error(`   Start it: jarvis engine start\n`);
+      process.exit(2);
+    }
   }
 
   else if (sub === 'status') {
@@ -43,7 +52,10 @@ export async function hookCommand(args) {
       if (args.includes('--json')) console.log(JSON.stringify(p, null, 2));
       else console.log(p._display || `${p.current_gate}`);
       process.exit(0);
-    } catch (e) { console.error(`⚠ Engine unreachable: ${e.message}`); process.exit(0); }
+    } catch (e) {
+      console.log('Engine: not running. Start with: jarvis engine start');
+      process.exit(0);
+    }
   }
 
   else {

package/src/templates/mcp-claude.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
     },
-    "jarvis": {
+    "jarvis-engine": {
       "url": "http://localhost:3456/mcp"
     }
   }

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

@@ -13,7 +13,7 @@ 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` 推进硬状态机。
+   **引擎驱动**：引擎运行后，MCP 工具自动可用。每个 Gate 工作完成后调用 `mcp__jarvis-engine__gate_enforce` 验证条件，通过后调用 `mcp__jarvis-engine__advance_gate` 推进硬状态机。
 
 2. 判断当前需求是否适合流水线：
    - ❌ **不适合**：用户提问信息量（"有多少模块？"）、明确要求单 agent 执行、纯文档格式化翻译
@@ -112,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 前置输入。通过后 `jarvis hook gate-advance`。
+实现完成后的第一道质量门。**不可绕过。** 加载 `Skill("code-quality-gate")` 执行四项检查（Lint → Type-check → Build → Deps Audit），按技能中的项目类型工具链表选择命令。全部通过后输出质量检查摘要，作为 Gate C2 前置输入。通过后 `mcp__jarvis-engine__advance_gate({ gate: "Gate C2" })`。
 
 必须**全部**满足才能进入 Gate C2：
 - [ ] **Lint 零错误**（warning 可接受但需记录）
@@ -176,7 +176,7 @@ Gate C1（+ Gate C1.5 如适用）通过后方可进入此门。
   │     └── spawn e2e-test-worker
   │
   ├── 步骤 6：测试结果汇总 → docs/testing/...
-  ├── Gate C2 通过 → `jarvis hook gate-advance` → 进入 Gate D 评审
+  ├── Gate C2 通过 → `mcp__jarvis-engine__advance_gate({ gate: "Gate D" })` → 进入 Gate D 评审
 ```
 
 ### test_after 策略规范