@skillfm/local 2.0.5 → 2.0.7

package/dist/index.js

@@ -12,13 +12,29 @@
 // 不做: JSONL mailbox、stdio MCP bridge、自动升级、多租户、email OTP 路径
 import { createServer } from 'node:http';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { probeSoulFile, buildConsentPayload, writeSkillfmBlock, removeSkillfmBlock, verifySkillfmBlock, markDeclined, hasDeclined, } from './soul.js';
 import { guardState } from './guard/state.js';
 import { agentHint } from './agent-hints.js';
+import { buildElicitationError, buildElicitationId, buildIsErrorResult, buildRejectEnvelope, } from './mcp-output/builder.js';
+import { MCP_OUTPUT_FEATURES, MCP_OUTPUT_VERSION, } from './mcp-output/types.js';
+import { renderNotFoundPage, renderReviewPage, reviewStore, } from './mcp-output/deny-review.js';
 const PKG_NAME = '@skillfm/local';
-const PKG_VERSION = '0.2.4';
+// 动态从 package.json 读 version, 避免硬编码字符串与 package.json 不同步
+// (历史教训 v3.2.x: 硬编码 '0.2.6' 与 package.json "2.0.6" 长期对不上)
+// dist/index.js 相对 package.json 在 ../package.json
+const PKG_VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+})();
 // OAuth endpoints live at API root (not under /api/v1), so we keep two base URLs.
 const DEFAULT_API_ROOT = process.env.SKILLFM_API_ROOT || 'https://api.skillfm.ai';
 const DEFAULT_API_BASE_URL = process.env.SKILLFM_API_URL || `${DEFAULT_API_ROOT}/api/v1`;
@@ -259,6 +275,17 @@ function json(res, status, body) {
     });
     res.end(payload);
 }
+function html(res, status, body) {
+    res.writeHead(status, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+function buildSidecarBaseUrl() {
+    const port = parseInt(process.env.SKILLFM_LOCAL_PORT || '19821', 10);
+    return `http://127.0.0.1:${port}`;
+}
 const routes = {
     'GET /health': async (_req, res) => {
         json(res, 200, { ok: true, service: PKG_NAME, version: PKG_VERSION });
@@ -912,12 +939,33 @@ const routes = {
     },
     // --------------------------------------------------------------------
     // GET /internal/guard/check?session_id=<id>&tool=<name>&harness=<name>
-    //   PreToolUse hook 触发；返回 200 放行 / 412 阻断
+    //                          &format=native|mcp-error|mcp-result|mcp-envelope
+    //                          &task_id=<id>&request_id=<id>&redline=<S1..S9>&tier=<A|B|C>
+    //
+    // PreToolUse hook 触发；返回 200 放行 / 412 阻断（native）
+    //                       或 200 + MCP-style envelope（mcp-* formats）
+    //
+    // M9.5 升级：format 参数支持 4 种输出
+    //   - native (默认，向后兼容)：旧 412 + { reason, hint }
+    //   - mcp-error    : URLElicitationRequiredError(-32042) only
+    //   - mcp-result   : { result, isError:true } only
+    //   - mcp-envelope : 双发（{ error, result }）
     // --------------------------------------------------------------------
     'GET /internal/guard/check': async (req, res) => {
         const url = new URL(req.url || '/', 'http://x');
         const session_id = url.searchParams.get('session_id') || '';
         const tool = url.searchParams.get('tool') || undefined;
+        const format = (url.searchParams.get('format') || 'native');
+        const task_id = url.searchParams.get('task_id') || `task-${Date.now().toString(36)}`;
+        const request_id_raw = url.searchParams.get('request_id');
+        const request_id = request_id_raw
+            ? /^\d+$/.test(request_id_raw)
+                ? parseInt(request_id_raw, 10)
+                : request_id_raw
+            : null;
+        const redline = url.searchParams.get('redline') || undefined;
+        const tierRaw = url.searchParams.get('tier');
+        const tier = tierRaw === 'A' || tierRaw === 'B' || tierRaw === 'C' ? tierRaw : undefined;
         if (!session_id) {
             return json(res, 400, { ok: false, error: 'session_id required' });
         }
@@ -925,14 +973,76 @@ const routes = {
         if (decision.allow) {
             return json(res, 200, { ok: true, allow: true, reason: decision.reason });
         }
-        return json(res, 412, {
-            ok: false,
-            allow: false,
-            reason: decision.reason,
+        // 拒绝路径
+        if (format === 'native') {
+            return json(res, 412, {
+                ok: false,
+                allow: false,
+                reason: decision.reason,
+                hint: decision.hint,
+            });
+        }
+        const rejectInput = {
+            task_id,
+            reason: decision.reason || 'guard 校验未通过',
             hint: decision.hint,
+            tool,
+            tier,
+            redline,
+            sidecarBaseUrl: buildSidecarBaseUrl(),
+            requestId: request_id,
+        };
+        // 提前生成 elicitation_id，登记到 reviewStore，让 envelope 与 store index 配对
+        const elicitation_id = buildElicitationId(task_id);
+        reviewStore.open(rejectInput, elicitation_id);
+        if (format === 'mcp-error') {
+            return json(res, 200, buildElicitationError(rejectInput, elicitation_id));
+        }
+        if (format === 'mcp-result') {
+            return json(res, 200, buildIsErrorResult(rejectInput));
+        }
+        // mcp-envelope (双发)
+        return json(res, 200, buildRejectEnvelope(rejectInput, elicitation_id));
+    },
+    // --------------------------------------------------------------------
+    // GET /internal/mcp/probe
+    //   doctor 用：暴露 sidecar MCP 输出层版本和能力
+    // --------------------------------------------------------------------
+    'GET /internal/mcp/probe': async (_req, res) => {
+        return json(res, 200, {
+            ok: true,
+            output_version: MCP_OUTPUT_VERSION,
+            features: MCP_OUTPUT_FEATURES,
+            formats: ['native', 'mcp-error', 'mcp-result', 'mcp-envelope'],
         });
     },
     // --------------------------------------------------------------------
+    // GET /internal/mcp/reviews
+    //   debug：列出当前 pending / decided 的审阅记录
+    // --------------------------------------------------------------------
+    'GET /internal/mcp/reviews': async (_req, res) => {
+        return json(res, 200, { ok: true, reviews: reviewStore.list() });
+    },
+    // --------------------------------------------------------------------
+    // GET /internal/mcp/elicitation/poll?elicitationId=<id>
+    //   M9.5 L2-4: SkillFM MCP bridge 用来 polling 等审阅完成。
+    //   返回 { status: 'pending' | 'complete' | 'not-found', payload?, decision? }
+    // --------------------------------------------------------------------
+    'GET /internal/mcp/elicitation/poll': async (req, res) => {
+        const url = new URL(req.url || '/', 'http://x');
+        const eid = url.searchParams.get('elicitationId') || '';
+        if (!eid)
+            return json(res, 400, { ok: false, error: 'elicitationId required' });
+        const rec = reviewStore.getByElicitationId(eid);
+        if (!rec)
+            return json(res, 200, { status: 'not-found' });
+        if (rec.decision === 'pending')
+            return json(res, 200, { status: 'pending' });
+        const { buildElicitationCompletePayload } = await import('./mcp-output/deny-review.js');
+        const payload = buildElicitationCompletePayload(rec);
+        return json(res, 200, { status: 'complete', decision: rec.decision, payload });
+    },
+    // --------------------------------------------------------------------
     // POST /internal/guard/post-tool-use
     //   body: { session_id, tool?, outcome? }
     //   PostToolUse hook；仅 audit，warn-only，永远 200。
@@ -967,6 +1077,99 @@ async function handleRequest(req, res) {
     }
     const method = req.method || 'GET';
     const url = (req.url || '/').split('?')[0];
+    // ---- SSE: /internal/mcp/elicitation/stream?elicitationId=<id> ----
+    if (url === '/internal/mcp/elicitation/stream' && method === 'GET') {
+        const u = new URL(req.url || '/', 'http://x');
+        const eid = u.searchParams.get('elicitationId') || '';
+        if (!eid) {
+            res.writeHead(400);
+            res.end('elicitationId required');
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+        });
+        // 已 decided：立即 push + 关闭
+        const existing = reviewStore.getByElicitationId(eid);
+        if (existing && existing.decision !== 'pending') {
+            const { buildElicitationCompletePayload } = await import('./mcp-output/deny-review.js');
+            const payload = buildElicitationCompletePayload(existing);
+            res.write(`event: elicitation-complete\n`);
+            res.write(`data: ${JSON.stringify(payload)}\n\n`);
+            res.end();
+            return;
+        }
+        // 订阅 — 每 15s 发 keepalive 注释，事件来了发完即关
+        const onComplete = (payload) => {
+            try {
+                res.write(`event: elicitation-complete\n`);
+                res.write(`data: ${JSON.stringify(payload.payload)}\n\n`);
+            }
+            catch {
+                // ignore
+            }
+            finally {
+                try {
+                    res.end();
+                }
+                catch {
+                    // ignore
+                }
+                clearInterval(keepAlive);
+                reviewStore.off(`elicitation:${eid}`, onComplete);
+            }
+        };
+        const keepAlive = setInterval(() => {
+            try {
+                res.write(`: keepalive\n\n`);
+            }
+            catch {
+                clearInterval(keepAlive);
+                reviewStore.off(`elicitation:${eid}`, onComplete);
+            }
+        }, 15_000);
+        reviewStore.on(`elicitation:${eid}`, onComplete);
+        req.on('close', () => {
+            clearInterval(keepAlive);
+            reviewStore.off(`elicitation:${eid}`, onComplete);
+        });
+        return;
+    }
+    // ---- prefix route: /deny-review/:task_id [/approve|/cancel|/modify] ----
+    if (url.startsWith('/deny-review/')) {
+        const tail = url.slice('/deny-review/'.length);
+        const parts = tail.split('/').filter(Boolean);
+        const task_id = decodeURIComponent(parts[0] || '');
+        const action = parts[1] || ''; // '' | 'approve' | 'cancel' | 'modify'
+        if (!task_id) {
+            res.writeHead(400);
+            res.end('task_id required');
+            return;
+        }
+        if (method === 'GET' && !action) {
+            const rec = reviewStore.get(task_id);
+            if (!rec)
+                return html(res, 404, renderNotFoundPage(task_id));
+            return html(res, 200, renderReviewPage(rec));
+        }
+        if (method === 'POST' && (action === 'approve' || action === 'cancel' || action === 'modify')) {
+            const decision = action === 'approve'
+                ? 'approved'
+                : action === 'cancel'
+                    ? 'cancelled'
+                    : 'modified';
+            const rec = reviewStore.decide(task_id, decision);
+            if (!rec) {
+                return json(res, 404, { ok: false, error: 'task_not_found', task_id });
+            }
+            return json(res, 200, { ok: true, decision: rec.decision, task_id });
+        }
+        res.writeHead(405);
+        res.end('method not allowed');
+        return;
+    }
     const key = `${method} ${url}`;
     const handler = routes[key];
     if (!handler) {
@@ -1168,11 +1371,22 @@ function cmdHelp() {
     console.log(`${PKG_NAME} v${PKG_VERSION}
 
 Usage:
-  skillfm-local start    Start local sidecar on 127.0.0.1:${DEFAULT_PORT}
-                           (falls back to a random port if ${DEFAULT_PORT} is taken)
-  skillfm-local stop     Stop the running sidecar
-  skillfm-local status   Print current sidecar state
-  skillfm-local help     Show this help
+  skillfm-local start              Start local sidecar on 127.0.0.1:${DEFAULT_PORT}
+                                     (falls back to a random port if ${DEFAULT_PORT} is taken)
+  skillfm-local stop               Stop the running sidecar
+  skillfm-local status             Print current sidecar state
+  skillfm-local init [--v3] [--host=<id>]
+                                   Project-level init: write SKILL.md priming + harness
+                                     PreToolUse hook (Layer 1 + Layer 3). --v3 = three-layer
+                                     architecture (recommended); omit for v2 flat (legacy).
+  skillfm-local bootstrap [--host=<id>] [--json]
+                                   ⭐ One-line full setup: verify sidecar + activation,
+                                     then run init --v3 in current cwd. Recommended for
+                                     first-time agents after activation.
+  skillfm-local doctor [--v2] [--disable-hooks] [--json]
+                                   Three-layer self-check (Layer 1 SKILL.md / Layer 2 MCP
+                                     reject / Layer 3 hook), or v0.2 layered defense check.
+  skillfm-local help               Show this help
 
 Service discovery:
   ${LOCAL_SETTINGS_FILE}   JSON with {url, pid, started_at}
@@ -1205,6 +1419,9 @@ const main = async () => {
         case 'init':
             await cmdInit();
             break;
+        case 'bootstrap':
+            await cmdBootstrap();
+            break;
         case 'doctor':
             await cmdDoctor();
             break;
@@ -1225,6 +1442,8 @@ const main = async () => {
 async function cmdInit() {
     const { detectHarness } = await import('./harness/detector.js');
     const { initHarness } = await import('./harness/writers.js');
+    const { detectPrimaryHost, installAll } = await import('./harness/kernels/registry.js');
+    const { writeProjectSkillMd, writeUserScopeSkillMd } = await import('./skill-md/writer.js');
     const args = process.argv.slice(3);
     const flags = {};
     for (let i = 0; i < args.length; i += 1) {
@@ -1247,25 +1466,267 @@ async function cmdInit() {
     const detected = detectHarness({});
     const harness = (typeof flags.harness === 'string' && flags.harness) || detected.harness;
     const lang = (typeof flags.lang === 'string' && flags.lang) || 'auto';
+    const apply = flags['dry-run'] !== true;
+    const v3 = flags['v3'] === true || flags['kernels'] === true;
+    // ---- v3 路径（推荐）：3 层抽象 — Layer 1 SKILL.md + Layer 3 kernel registry
+    if (v3) {
+        const host = typeof flags.host === 'string'
+            ? { host: flags.host, source: 'forced', reason: 'user --host flag' }
+            : detectPrimaryHost();
+        // Layer 1: SKILL.md
+        const skillMd = writeProjectSkillMd({ cwd: process.cwd(), lang });
+        let userSkillMd = null;
+        if (host.host === 'claude-code' && flags['copy-to-user'] === true) {
+            userSkillMd = writeUserScopeSkillMd(lang);
+        }
+        // Layer 3: kernel adapters
+        const layer3 = await installAll({
+            host,
+            cwd: process.cwd(),
+            apply,
+            forceKernel: typeof flags.kernel === 'string' ? flags.kernel : undefined,
+            alsoInstallMcpHosts: typeof flags['also-mcp-hosts'] === 'string'
+                ? flags['also-mcp-hosts'].split(',').map((s) => s.trim()).filter(Boolean)
+                : undefined,
+        });
+        if (flags['json'] === true) {
+            console.log(JSON.stringify({
+                ok: true,
+                architecture: 'v3-three-layer',
+                detect: detected,
+                host,
+                layer1_skill_md: { project: skillMd, user: userSkillMd },
+                layer3_kernels: layer3,
+            }, null, 2));
+            return;
+        }
+        // 人类可读输出
+        const lines = [];
+        lines.push(`✓ 检测 host: ${host.host}${host.source !== 'detected' ? ` (${host.source})` : ''}`);
+        if (host.reason)
+            lines.push(`  reason: ${host.reason}`);
+        lines.push('');
+        // Layer 1
+        const skillBadge = skillMd.action === 'created'
+            ? '已创建'
+            : skillMd.action === 'replaced'
+                ? '已升级'
+                : skillMd.action === 'appended'
+                    ? '已追加'
+                    : '已就绪';
+        lines.push(`✓ Layer 1: SKILL.md (${skillBadge}) — ${skillMd.path}`);
+        if (userSkillMd) {
+            lines.push(`✓ Layer 1: 用户级 SKILL.md (${userSkillMd.action}) — ${userSkillMd.path}`);
+        }
+        lines.push('');
+        // Layer 2 — 提示用户 sidecar MCP reject 是否在跑（可选探测）
+        lines.push(`ℹ Layer 2: MCP Protocol-Reject 由 sidecar 输出层提供`);
+        lines.push(`  → 检查 \`skillfm doctor\` Layer 2 是否 ✅ (output_version=v2)`);
+        lines.push('');
+        // Layer 3
+        if (layer3.matched.length === 0) {
+            lines.push(`⚠ Layer 3: 当前 host=${host.host} 未匹配任何 kernel`);
+            lines.push(`  → 仅 Layer 1+2 生效；如需 Layer 3 强制，加 --kernel=<hook-file|deny-pipeline|mcp-only>`);
+        }
+        else {
+            for (const result of layer3.results) {
+                const fileSummary = result.files
+                    .map((f) => `${f.action} ${f.path}`)
+                    .join(', ');
+                lines.push(`✓ Layer 3 [${result.kernel}] host=${result.host}: ${fileSummary || '(无文件改动)'}`);
+                for (const w of result.warnings)
+                    lines.push(`  ⚠ ${w}`);
+            }
+        }
+        lines.push('');
+        // 顶层 warnings
+        if (layer3.warnings.length > 0) {
+            lines.push('⚠ 整体提示：');
+            for (const w of layer3.warnings)
+                lines.push(`  - ${w}`);
+            lines.push('');
+        }
+        // mcp-only 主动联动提示
+        if (layer3.matched.includes('mcp-only')) {
+            lines.push('🔗 mcp-only 内核强制力依赖 Layer 2：');
+            lines.push('   - 确保 sidecar 在跑（skillfm start）');
+            lines.push('   - 确保 sidecar 输出层 ≥ v2（URLElicitationRequiredError）');
+            lines.push('   - 跑 `skillfm doctor` 验证三层全部就绪');
+            lines.push('');
+        }
+        lines.push(`下一步:`);
+        lines.push(`  - skillfm start          # 启 sidecar (如未启)`);
+        lines.push(`  - skillfm doctor         # 三层架构自检`);
+        lines.push(`  - 在 ${host.host} 内开新 session 验证 priming + hook 生效`);
+        console.log(lines.join('\n'));
+        return;
+    }
+    // ---- v2 路径（兼容）：单 harness × 单模板
     const report = initHarness({
         harness,
         cwd: process.cwd(),
         lang,
         llmOnly: flags['llm-only'] === true,
     });
-    console.log(JSON.stringify({ ok: true, detect: detected, report }, null, 2));
+    console.log(JSON.stringify({ ok: true, architecture: 'v2-flat', detect: detected, report }, null, 2));
+}
+// ============================================================================
+// cmdBootstrap — 一行命令完整安装：start + activate (auto) + init --v3
+// ============================================================================
+/**
+ * 解决"激活后只写 2 个文件"的 UX 缺陷。
+ *
+ * 流程：
+ *   1. 检测 sidecar 是否在跑；不在跑则启
+ *   2. 检测是否已激活（~/.skillfm/config.json brain_key）；未激活则提示用户走 OAuth
+ *      （bootstrap 不能自动完成 OAuth — 用户必须在浏览器手动授权）
+ *   3. 已激活后立即触发 init --v3 在 cwd 写 SKILL.md + harness hook + MCP 注册
+ *
+ * 与 cmdStart 区别：start 只起 sidecar；bootstrap 是 start + 强引导激活 + 项目级 init。
+ *
+ * 使用：
+ *   npx -y -p @skillfm/local skillfm-local bootstrap
+ *   npx -y -p @skillfm/local skillfm-local bootstrap --host=cursor
+ *   npx -y -p @skillfm/local skillfm-local bootstrap --json
+ */
+async function cmdBootstrap() {
+    const args = process.argv.slice(3);
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const t = args[i];
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            if (eq > 0)
+                flags[t.slice(2, eq)] = t.slice(eq + 1);
+            else {
+                const nxt = args[i + 1];
+                if (nxt !== undefined && !nxt.startsWith('--')) {
+                    flags[t.slice(2)] = nxt;
+                    i += 1;
+                }
+                else
+                    flags[t.slice(2)] = true;
+            }
+        }
+    }
+    const asJson = flags['json'] === true;
+    const lines = [];
+    const log = (msg) => {
+        if (!asJson)
+            console.log(msg);
+        lines.push(msg);
+    };
+    // 1. sidecar 状态
+    const existing = readLocalSettings();
+    const sidecarRunning = existing && isPidAlive(existing.pid);
+    if (sidecarRunning) {
+        log(`✓ sidecar 已在 ${existing.url} 运行 (PID ${existing.pid})`);
+    }
+    else {
+        log(`⚠ sidecar 未在跑，请先启动：npx -y -p @skillfm/local skillfm-local start`);
+        log(`  bootstrap 不会自动启 sidecar（避免子进程孤儿化）；请单独跑 start 后再 bootstrap。`);
+        if (asJson) {
+            console.log(JSON.stringify({ ok: false, reason: 'sidecar_not_running', steps: lines }, null, 2));
+        }
+        process.exit(1);
+    }
+    // 2. 激活状态
+    const cfg = readConfig();
+    const activated = Boolean(cfg.agentToken);
+    if (!activated) {
+        log(`⚠ 尚未激活 — brain_key 未保存。`);
+        log(`  请走 OAuth 流程：`);
+        log(`    curl -sS -X POST ${existing.url}/activate/start`);
+        log(`    用户在浏览器完成授权后，每 5s 轮询：`);
+        log(`    curl -sS -X POST ${existing.url}/activate/poll`);
+        log(`  激活成功后再次跑 bootstrap 完成项目级 init。`);
+        if (asJson) {
+            console.log(JSON.stringify({ ok: false, reason: 'not_activated', steps: lines }, null, 2));
+        }
+        process.exit(1);
+    }
+    log(`✓ 已激活 (brain_key 长度 ${cfg.agentToken.length} chars)`);
+    // 3. 项目级 init --v3
+    log(``);
+    log(`正在执行 init --v3 完成项目级三层防御注入...`);
+    // 直接复用 cmdInit 内 v3 路径的实现（detectPrimaryHost + writeProjectSkillMd + installAll）
+    const { detectPrimaryHost, installAll } = await import('./harness/kernels/registry.js');
+    const { writeProjectSkillMd } = await import('./skill-md/writer.js');
+    const host = typeof flags.host === 'string'
+        ? { host: flags.host, source: 'forced', reason: 'bootstrap --host flag' }
+        : detectPrimaryHost();
+    const lang = (typeof flags.lang === 'string' && flags.lang) || 'auto';
+    const skillMd = writeProjectSkillMd({ cwd: process.cwd(), lang });
+    log(`✓ Layer 1 SKILL.md (${skillMd.action}) — ${skillMd.path}`);
+    const layer3 = await installAll({
+        host,
+        cwd: process.cwd(),
+        apply: true,
+        forceKernel: typeof flags.kernel === 'string' ? flags.kernel : undefined,
+    });
+    if (layer3.matched.length === 0) {
+        log(`⚠ Layer 3: host=${host.host} 未匹配任何 kernel；仅 Layer 1+2 生效`);
+    }
+    else {
+        for (const result of layer3.results) {
+            const fileSummary = result.files.map((f) => `${f.action} ${f.path}`).join(', ');
+            log(`✓ Layer 3 [${result.kernel}] host=${result.host}: ${fileSummary || '(无文件改动)'}`);
+        }
+    }
+    log(``);
+    log(`✅ Bootstrap 完成。三层防御已就绪：`);
+    log(`   Layer 1 SKILL.md priming → ./SKILL.md`);
+    log(`   Layer 2 MCP Protocol-Reject → sidecar 输出层 v2`);
+    log(`   Layer 3 ${layer3.matched.join('+') || '(unknown host, layer 1+2 only)'}`);
+    log(``);
+    log(`下一步：跑 \`skillfm doctor\` 自检三层全部就绪`);
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            architecture: 'v3-three-layer',
+            sidecar: { url: existing.url, pid: existing.pid },
+            activated: true,
+            host,
+            layer1_skill_md: skillMd,
+            layer3_kernels: layer3,
+            steps: lines,
+        }, null, 2));
+    }
 }
 async function cmdDoctor() {
-    const { runDoctor, renderDoctorReport } = await import('./doctor.js');
-    const report = await runDoctor(process.cwd());
-    if (process.argv.includes('--json')) {
-        console.log(JSON.stringify(report, null, 2));
+    const flags = process.argv.slice(3);
+    const useV2 = flags.includes('--v2');
+    const asJson = flags.includes('--json');
+    const disableHooksMode = flags.includes('--disable-hooks');
+    if (useV2) {
+        const { runDoctor, renderDoctorReport } = await import('./doctor.js');
+        const report = await runDoctor(process.cwd());
+        if (asJson)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.log(renderDoctorReport(report));
+        const hasFail = report.items.some((i) => i.status === 'fail');
+        process.exit(hasFail ? 1 : 0);
+    }
+    // v3 默认（三层抽象架构）
+    const { runDoctorV3, renderDoctorV3Report, renderDisableHooksReport } = await import('./doctor.js');
+    const report = await runDoctorV3(process.cwd());
+    if (asJson) {
+        console.log(JSON.stringify(disableHooksMode ? { ...report, mode: 'disable-hooks-preview' } : report, null, 2));
+    }
+    else if (disableHooksMode) {
+        console.log(renderDisableHooksReport(report));
     }
     else {
-        console.log(renderDoctorReport(report));
+        console.log(renderDoctorV3Report(report));
+    }
+    // 退出码：任意 fail 项 → 1（disable-hooks 模式只是预览，永远 0）
+    if (disableHooksMode) {
+        process.exit(0);
     }
-    const hasFail = report.items.some((i) => i.status === 'fail');
-    process.exit(hasFail ? 1 : 0);
+    const layer1HasFail = report.layer1.items.some((i) => i.status === 'fail');
+    const layer2Fail = report.layer2.diagnose.level === 'absent';
+    process.exit(layer1HasFail || layer2Fail ? 1 : 0);
 }
 main().catch((e) => {
     console.error(JSON.stringify({ ok: false, error: e?.message || String(e) }));