shellward 0.7.12 → 0.7.14

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/shellward?color=cb0000&label=npm)](https://www.npmjs.com/package/shellward)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-303%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-315%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 **🌐 官网: https://jnmetacode.github.io/shellward/**

package/dist/cli.js

@@ -17,6 +17,7 @@ import { ShellWard } from './core/engine.js';
 import { runProjectComplianceAudit } from './compliance/audit.js';
 import { renderComplianceReport, renderProjectFindings } from './compliance/report.js';
 import { renderHtmlReport } from './compliance/html-report.js';
+import { runInit } from './init.js';
 import { resolveLocale } from './types.js';
 const argv = process.argv.slice(2);
 const wantsHelp = argv.includes('--help') || argv.includes('-h') || argv[0] === 'help';
@@ -31,6 +32,10 @@ async function main() {
         await import('./mcp-server.js');
         return;
     }
+    if (cmd === 'init') {
+        runInitCommand(argv.includes('--dry-run'));
+        return;
+    }
     if (cmd === 'web') {
         const { startWebServer } = await import('./web/scan-server.js');
         const local = argv.includes('--local');
@@ -151,6 +156,33 @@ function runScan(args) {
             process.exit(1);
     }
 }
+/** `shellward init`：把 ShellWard 接入已安装 AI 工具的 MCP 配置（运行时防护） */
+function runInitCommand(dryRun) {
+    const out = runInit({ dryRun });
+    console.log('\n🔌 ShellWard 接入 AI 工具运行时防护' + (dryRun ? '（预览，不写入）' : '') + '\n');
+    const ICON = { added: '✅', updated: '✅', unchanged: '✔️', skipped: '·', error: '⚠️' };
+    let touched = 0;
+    for (const o of out) {
+        const label = { added: '已接入', updated: '已更新', unchanged: '已接入(无变化)', skipped: '跳过', error: '失败' }[o.result];
+        if (o.result === 'added' || o.result === 'updated')
+            touched++;
+        console.log(`  ${ICON[o.result] || '·'} ${o.name} — ${label}${o.detail ? '：' + o.detail : ''}`);
+        if (o.result !== 'skipped')
+            console.log(`      ${o.path}`);
+    }
+    console.log('');
+    if (dryRun) {
+        console.log('这是预览。去掉 --dry-run 实际接入。');
+    }
+    else if (touched > 0) {
+        console.log('✅ 已接入。请重启对应的 AI 工具，ShellWard 即作为运行时防护生效（拦注入/外泄/危险命令）。');
+        console.log('   验证：在工具里问"调用 shellward 的 security_status"。原配置已备份为 *.shellward.bak。');
+    }
+    else {
+        console.log('未发现可接入的已安装 AI 工具配置。也可手动加 MCP：');
+        console.log('   {"mcpServers":{"shellward":{"command":"npx","args":["-y","-p","shellward","shellward-mcp"]}}}');
+    }
+}
 /** 跨平台在默认浏览器打开 URL 或本地文件（失败静默，不影响主流程） */
 function openBrowser(target) {
     const cmd = process.platform === 'darwin' ? 'open'
@@ -187,6 +219,7 @@ Usage:
   shellward scan --serve   Scan and serve the report at http://localhost (local)
   shellward web [port]     Web scanner for public repo URLs (deploy this)
   shellward web --local    Local web GUI: scan a local path (private, no upload)
+  shellward init           Install ShellWard into your AI tools (MCP runtime guard)
   shellward mcp            Start MCP server (stdio)
   shellward --help
 
@@ -206,6 +239,7 @@ PII in files, .env permissions. Maps to CSL / PIPL / MLPS / cross-border / label
   shellward scan --serve    扫描并在 http://localhost 提供报告（本地服务）
   shellward web [端口]       公开仓库 web 扫描器（贴 URL 体检，用于部署）
   shellward web --local     本地 web GUI：填本地路径扫描（私有、不上传，客户端体验）
+  shellward init            一键接入你的 AI 工具（MCP 运行时防护，--dry-run 预览）
   shellward mcp             启动 MCP 服务器（stdio）
   shellward --help
 

package/dist/compliance/audit.js

@@ -236,9 +236,10 @@ function checkEnv(c, env) {
         if (env.overseas.length > 0) {
             const names = env.overseas.map(o => o.provider_zh).join(', ');
             const namesEn = env.overseas.map(o => o.provider_en).join(', ');
-            return mk(c, 'fail', `检测到境外大模型端点配置: ${names} — 若向其发送个人信息/重要数据即构成数据出境，须走合规路径`, `Overseas LLM endpoint(s) configured: ${namesEn} — sending PI/important data = cross-border export`);
+            // 检出境外调用是"事实"，是否违规取决于是否发送 PII/重要数据 → 标"需评估"而非"不合规"
+            return mk(c, 'warn', `检测到境外大模型调用: ${names}。是否违规取决于发送的数据：涉及个人信息/重要数据需走合规路径或改用境内模型；仅非个人/非重要数据通常可接受。`, `Overseas LLM detected: ${namesEn}. Compliance depends on the data sent — PI/important data needs a compliant path; non-personal data is usually fine.`);
         }
-        return mk(c, 'pass', '未检测到境外大模型端点配置', 'No overseas LLM endpoint detected');
+        return mk(c, 'pass', '未检测到境外大模型调用', 'No overseas LLM detected');
     }
     return mk(c, 'manual', '需人工确认', 'Manual check required');
 }

package/dist/compliance/html-report.js

@@ -14,7 +14,7 @@ const STATUS = {
     manual: { zh: '待确认', en: 'Review', cls: 'manual' },
 };
 const KIND = {
-    overseas: { zh: '数据出境风险', en: 'Data export risk', icon: '🌐' },
+    overseas: { zh: '境外大模型调用（需评估出境）', en: 'Overseas LLM (assess export)', icon: '🌐' },
     secret: { zh: '硬编码密钥', en: 'Hardcoded secret', icon: '🔑' },
     pii: { zh: '个人信息暴露', en: 'PII exposure', icon: '🪪' },
     'env-perm': { zh: '.env 权限', en: '.env permission', icon: '📂' },
@@ -161,6 +161,18 @@ export function renderHtmlReport(report, scan, locale, meta) {
         }
         S.push('</tbody></table></div>');
     }
+    // ===== 接入运行时指引：把 ⚪ 待核验项变成可验证（回答"需要接入才能测"）=====
+    if (report.staticScan && report.manual > 0) {
+        const cfg = `{
+  "mcpServers": {
+    "shellward": { "command": "npx", "args": ["-y", "-p", "shellward", "shellward-mcp"] }
+  }
+}`;
+        S.push(sectionHead('🔌', t('让待核验项可验证：接入运行时', 'Make ⚪ items verifiable: deploy runtime'), t('静态扫描测不了运行时行为，接入后这些项才能被持续验证', 'Static scan cannot test runtime behavior; deploy to validate')));
+        S.push(`<p class="note">${t(`把下面这段加到 Claude Desktop / Cursor / OpenClaw 的 MCP 配置，重启后 ShellWard 就作为<b>运行时防护</b>在你的 AI 应用里运行——上方 ${report.manual} 项（审计留存、运行时拦截、数据外发管控等）即可被真实验证。`, `Add this to your Claude Desktop / Cursor / OpenClaw MCP config and restart — ShellWard then runs as a <b>runtime guard</b>, validating the ${report.manual} ⚪ items above.`)}</p>`);
+        S.push(`<div class="cfg"><pre id="mcpcfg">${esc(cfg)}</pre><button onclick="(function(b){navigator.clipboard&&navigator.clipboard.writeText(document.getElementById('mcpcfg').textContent).then(function(){b.textContent='${t('已复制', 'Copied')}'})})(this)">${t('复制', 'Copy')}</button></div>`);
+        S.push(`<p class="muted">${t('或命令行直接起：', 'Or run directly:')} <code>npx shellward mcp</code> · ${t('文档', 'Docs')}: <a href="https://github.com/jnMetaCode/shellward">github.com/jnMetaCode/shellward</a></p>`);
+    }
     const disclaimer = t('本报告由 ShellWard 合规网关自动生成，帮助评估并满足合规技术要求，不构成法律意见，亦不替代算法备案/定级备案/PIA 等主体责任。⚪ 待确认项需结合业务人工判定。', 'Generated by ShellWard Compliance Gateway. Assists with technical compliance; not legal advice. ⚪ items require manual review.');
     return `<!DOCTYPE html>
 <html lang="${zh ? 'zh-CN' : 'en'}">
@@ -323,6 +335,12 @@ table.tbl td.right{width:64px}
 .manual-note{margin:8px 36px 12px;font-size:13px;color:#475569;background:#eff6ff;
   border-left:3px solid #3b82f6;line-height:1.6}
 .manual-note code{background:#dbeafe;padding:1px 6px;border-radius:5px}
+.cfg{position:relative;margin:8px 36px}
+.cfg pre{background:#0f172a;color:#e2e8f0;border-radius:10px;padding:16px 18px;margin:0;
+  font-family:ui-monospace,Menlo,monospace;font-size:12.5px;overflow-x:auto;line-height:1.5}
+.cfg button{position:absolute;top:10px;right:12px;background:#1e293b;color:#94a3b8;border:0;
+  border-radius:6px;padding:5px 12px;font-size:12px;cursor:pointer}
+.cfg button:hover{color:#fff}
 
 /* 法规分组 */
 .reg{margin:14px 36px;padding:0;border:1px solid var(--line);border-radius:12px;overflow:hidden}

package/dist/compliance/report.js

@@ -116,7 +116,7 @@ export function renderComplianceReport(report, locale) {
     return L.join('\n');
 }
 const KIND_LABEL = {
-    overseas: { zh: '数据出境风险', en: 'Data export risk', icon: '🌐' },
+    overseas: { zh: '境外大模型调用（需评估出境）', en: 'Overseas LLM (assess export)', icon: '🌐' },
     secret: { zh: '硬编码密钥', en: 'Hardcoded secret', icon: '🔑' },
     pii: { zh: '个人信息暴露', en: 'PII exposure', icon: '🪪' },
     'env-perm': { zh: '.env 权限', en: '.env permission', icon: '📂' },

package/dist/init.d.ts

@@ -0,0 +1,38 @@
+/** 标准 MCP 接入条目：零安装，npx 拉取已发布的 shellward-mcp */
+export declare const SHELLWARD_MCP_ENTRY: {
+    command: string;
+    args: string[];
+};
+export interface InitTarget {
+    name: string;
+    path: string;
+    /** 配置里放 MCP 服务器的字段名（绝大多数是 mcpServers） */
+    key: string;
+    /** 工具未安装时是否允许新建配置文件 */
+    createIfMissing?: boolean;
+}
+/** 已知 AI 工具的 MCP 配置位置（跨平台） */
+export declare function knownTargets(home?: string): InitTarget[];
+export type MergeResult = {
+    status: 'added' | 'updated';
+    config: any;
+} | {
+    status: 'unchanged';
+    config: any;
+};
+/**
+ * 纯合并：把 shellward 条目并入配置对象。已存在且相同→unchanged；不同→updated；没有→added。
+ * 不破坏其它 MCP 服务器条目。
+ */
+export declare function mergeShellward(config: any, key: string): MergeResult;
+export interface InitOutcome {
+    name: string;
+    path: string;
+    result: 'added' | 'updated' | 'unchanged' | 'skipped' | 'error';
+    detail?: string;
+}
+/** 执行接入：探测→读取→合并→备份→写回。dryRun 仅预览不写。 */
+export declare function runInit(opts?: {
+    dryRun?: boolean;
+    home?: string;
+}): InitOutcome[];

package/dist/init.js

@@ -0,0 +1,77 @@
+// src/init.ts — `shellward init`：一条命令把 ShellWard 接入已安装的 AI 工具（MCP 运行时防护）
+//
+// 把"扫描 → 运行时防护"的部署摩擦降到一条命令：自动探测 Claude Desktop / Cursor /
+// Claude Code / Windsurf 的 MCP 配置，安全地加入 shellward 条目（备份、合并、不覆盖）。
+// 这是「安装按钮」的正确形态——只对已知配置文件操作、改前备份、可 --dry-run 预览。
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+/** 标准 MCP 接入条目：零安装，npx 拉取已发布的 shellward-mcp */
+export const SHELLWARD_MCP_ENTRY = {
+    command: 'npx',
+    args: ['-y', '-p', 'shellward', 'shellward-mcp'],
+};
+/** 已知 AI 工具的 MCP 配置位置（跨平台） */
+export function knownTargets(home = homedir()) {
+    const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+    const claudeDesktop = process.platform === 'darwin' ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        : process.platform === 'win32' ? join(appData, 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    return [
+        { name: 'Claude Desktop', path: claudeDesktop, key: 'mcpServers', createIfMissing: true },
+        { name: 'Cursor', path: join(home, '.cursor', 'mcp.json'), key: 'mcpServers', createIfMissing: true },
+        { name: 'Claude Code', path: join(home, '.claude.json'), key: 'mcpServers' },
+        { name: 'Windsurf', path: join(home, '.codeium', 'windsurf', 'mcp_config.json'), key: 'mcpServers' },
+    ];
+}
+/**
+ * 纯合并：把 shellward 条目并入配置对象。已存在且相同→unchanged；不同→updated；没有→added。
+ * 不破坏其它 MCP 服务器条目。
+ */
+export function mergeShellward(config, key) {
+    const cfg = config && typeof config === 'object' ? config : {};
+    const servers = cfg[key] && typeof cfg[key] === 'object' ? cfg[key] : {};
+    const existing = servers.shellward;
+    const same = existing && JSON.stringify(existing) === JSON.stringify(SHELLWARD_MCP_ENTRY);
+    if (same)
+        return { status: 'unchanged', config: cfg };
+    const status = existing ? 'updated' : 'added';
+    cfg[key] = { ...servers, shellward: { ...SHELLWARD_MCP_ENTRY } };
+    return { status, config: cfg };
+}
+/** 执行接入：探测→读取→合并→备份→写回。dryRun 仅预览不写。 */
+export function runInit(opts = {}) {
+    const targets = knownTargets(opts.home);
+    const out = [];
+    for (const t of targets) {
+        const exists = existsSync(t.path);
+        if (!exists && !t.createIfMissing) {
+            out.push({ name: t.name, path: t.path, result: 'skipped', detail: '未安装/无配置' });
+            continue;
+        }
+        try {
+            let config = {};
+            if (exists) {
+                const raw = readFileSync(t.path, 'utf-8').trim();
+                config = raw ? JSON.parse(raw) : {};
+            }
+            const merged = mergeShellward(config, t.key);
+            if (merged.status === 'unchanged') {
+                out.push({ name: t.name, path: t.path, result: 'unchanged', detail: '已接入' });
+                continue;
+            }
+            if (!opts.dryRun) {
+                if (exists)
+                    copyFileSync(t.path, t.path + '.shellward.bak'); // 改前备份
+                else
+                    mkdirSync(dirname(t.path), { recursive: true });
+                writeFileSync(t.path, JSON.stringify(merged.config, null, 2) + '\n');
+            }
+            out.push({ name: t.name, path: t.path, result: merged.status, detail: opts.dryRun ? '预览（未写入）' : (exists ? '已加入（原文件已备份 .bak）' : '已新建配置') });
+        }
+        catch (e) {
+            out.push({ name: t.name, path: t.path, result: 'error', detail: e?.message || String(e) });
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "mcpName": "io.github.jnMetaCode/shellward",
   "description": "AI agent security & MCP security middleware — prompt injection detection, AI firewall, runtime guardrails & data-loss prevention for LLM tool calls. 8-layer defense against data exfiltration & dangerous commands. Zero dependencies. SDK + OpenClaw plugin. Supports LangChain, AutoGPT, Claude Code, Cursor, OpenAI Agents, Hermes Agent.",
   "keywords": [
@@ -57,7 +57,7 @@
   "scripts": {
     "build": "tsc",
     "mcp": "npx tsx src/mcp-server.ts",
-    "test": "npx tsx test-sdk.ts && npx tsx test-integration.ts && npx tsx test-edge-cases.ts && npx tsx test-rugpull.ts && npx tsx test-redos.ts && npx tsx test-mcp-client.ts && npx tsx test-mcp.ts && npx tsx test-compliance.ts && npx tsx test-web.ts",
+    "test": "npx tsx test-sdk.ts && npx tsx test-integration.ts && npx tsx test-edge-cases.ts && npx tsx test-rugpull.ts && npx tsx test-redos.ts && npx tsx test-mcp-client.ts && npx tsx test-mcp.ts && npx tsx test-compliance.ts && npx tsx test-web.ts && npx tsx test-init.ts",
     "test:redos": "npx tsx test-redos.ts",
     "test:compliance": "npx tsx test-compliance.ts",
     "test:integration": "npx tsx test-integration.ts",
@@ -66,7 +66,8 @@
     "test:mcp": "npx tsx test-mcp.ts",
     "bench": "npx tsx bench/run.ts",
     "bench:scan": "npx tsx bench/scan-bench.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test:init": "npx tsx test-init.ts"
   },
   "openclaw": {
     "extensions": [

package/src/cli.ts

@@ -18,6 +18,7 @@ import { ShellWard } from './core/engine.js'
 import { runProjectComplianceAudit } from './compliance/audit.js'
 import { renderComplianceReport, renderProjectFindings } from './compliance/report.js'
 import { renderHtmlReport } from './compliance/html-report.js'
+import { runInit } from './init.js'
 import { resolveLocale } from './types.js'
 
 const argv = process.argv.slice(2)
@@ -36,6 +37,11 @@ async function main() {
     return
   }
 
+  if (cmd === 'init') {
+    runInitCommand(argv.includes('--dry-run'))
+    return
+  }
+
   if (cmd === 'web') {
     const { startWebServer } = await import('./web/scan-server.js')
     const local = argv.includes('--local')
@@ -163,6 +169,30 @@ function runScan(args: string[]) {
   }
 }
 
+/** `shellward init`：把 ShellWard 接入已安装 AI 工具的 MCP 配置（运行时防护） */
+function runInitCommand(dryRun: boolean): void {
+  const out = runInit({ dryRun })
+  console.log('\n🔌 ShellWard 接入 AI 工具运行时防护' + (dryRun ? '（预览，不写入）' : '') + '\n')
+  const ICON: Record<string, string> = { added: '✅', updated: '✅', unchanged: '✔️', skipped: '·', error: '⚠️' }
+  let touched = 0
+  for (const o of out) {
+    const label = { added: '已接入', updated: '已更新', unchanged: '已接入(无变化)', skipped: '跳过', error: '失败' }[o.result]
+    if (o.result === 'added' || o.result === 'updated') touched++
+    console.log(`  ${ICON[o.result] || '·'} ${o.name} — ${label}${o.detail ? '：' + o.detail : ''}`)
+    if (o.result !== 'skipped') console.log(`      ${o.path}`)
+  }
+  console.log('')
+  if (dryRun) {
+    console.log('这是预览。去掉 --dry-run 实际接入。')
+  } else if (touched > 0) {
+    console.log('✅ 已接入。请重启对应的 AI 工具，ShellWard 即作为运行时防护生效（拦注入/外泄/危险命令）。')
+    console.log('   验证：在工具里问"调用 shellward 的 security_status"。原配置已备份为 *.shellward.bak。')
+  } else {
+    console.log('未发现可接入的已安装 AI 工具配置。也可手动加 MCP：')
+    console.log('   {"mcpServers":{"shellward":{"command":"npx","args":["-y","-p","shellward","shellward-mcp"]}}}')
+  }
+}
+
 /** 跨平台在默认浏览器打开 URL 或本地文件（失败静默，不影响主流程） */
 function openBrowser(target: string): void {
   const cmd = process.platform === 'darwin' ? 'open'
@@ -199,6 +229,7 @@ Usage:
   shellward scan --serve   Scan and serve the report at http://localhost (local)
   shellward web [port]     Web scanner for public repo URLs (deploy this)
   shellward web --local    Local web GUI: scan a local path (private, no upload)
+  shellward init           Install ShellWard into your AI tools (MCP runtime guard)
   shellward mcp            Start MCP server (stdio)
   shellward --help
 
@@ -217,6 +248,7 @@ PII in files, .env permissions. Maps to CSL / PIPL / MLPS / cross-border / label
   shellward scan --serve    扫描并在 http://localhost 提供报告（本地服务）
   shellward web [端口]       公开仓库 web 扫描器（贴 URL 体检，用于部署）
   shellward web --local     本地 web GUI：填本地路径扫描（私有、不上传，客户端体验）
+  shellward init            一键接入你的 AI 工具（MCP 运行时防护，--dry-run 预览）
   shellward mcp             启动 MCP 服务器（stdio）
   shellward --help
 

package/src/compliance/audit.ts

@@ -317,11 +317,12 @@ function checkEnv(c: ComplianceControl, env: EnvFacts): ControlResult {
     if (env.overseas.length > 0) {
       const names = env.overseas.map(o => o.provider_zh).join(', ')
       const namesEn = env.overseas.map(o => o.provider_en).join(', ')
-      return mk(c, 'fail',
-        `检测到境外大模型端点配置: ${names} — 若向其发送个人信息/重要数据即构成数据出境，须走合规路径`,
-        `Overseas LLM endpoint(s) configured: ${namesEn} — sending PI/important data = cross-border export`)
+      // 检出境外调用是"事实"，是否违规取决于是否发送 PII/重要数据 → 标"需评估"而非"不合规"
+      return mk(c, 'warn',
+        `检测到境外大模型调用: ${names}。是否违规取决于发送的数据：涉及个人信息/重要数据需走合规路径或改用境内模型；仅非个人/非重要数据通常可接受。`,
+        `Overseas LLM detected: ${namesEn}. Compliance depends on the data sent — PI/important data needs a compliant path; non-personal data is usually fine.`)
     }
-    return mk(c, 'pass', '未检测到境外大模型端点配置', 'No overseas LLM endpoint detected')
+    return mk(c, 'pass', '未检测到境外大模型调用', 'No overseas LLM detected')
   }
   return mk(c, 'manual', '需人工确认', 'Manual check required')
 }

package/src/compliance/html-report.ts

@@ -20,7 +20,7 @@ const STATUS: Record<ControlStatus, { zh: string; en: string; cls: string }> = {
 }
 
 const KIND: Record<FindingKind, { zh: string; en: string; icon: string }> = {
-  overseas: { zh: '数据出境风险', en: 'Data export risk', icon: '🌐' },
+  overseas: { zh: '境外大模型调用（需评估出境）', en: 'Overseas LLM (assess export)', icon: '🌐' },
   secret: { zh: '硬编码密钥', en: 'Hardcoded secret', icon: '🔑' },
   pii: { zh: '个人信息暴露', en: 'PII exposure', icon: '🪪' },
   'env-perm': { zh: '.env 权限', en: '.env permission', icon: '📂' },
@@ -192,6 +192,22 @@ export function renderHtmlReport(
     S.push('</tbody></table></div>')
   }
 
+  // ===== 接入运行时指引：把 ⚪ 待核验项变成可验证（回答"需要接入才能测"）=====
+  if (report.staticScan && report.manual > 0) {
+    const cfg = `{
+  "mcpServers": {
+    "shellward": { "command": "npx", "args": ["-y", "-p", "shellward", "shellward-mcp"] }
+  }
+}`
+    S.push(sectionHead('🔌', t('让待核验项可验证：接入运行时', 'Make ⚪ items verifiable: deploy runtime'),
+      t('静态扫描测不了运行时行为，接入后这些项才能被持续验证', 'Static scan cannot test runtime behavior; deploy to validate')))
+    S.push(`<p class="note">${t(
+      `把下面这段加到 Claude Desktop / Cursor / OpenClaw 的 MCP 配置，重启后 ShellWard 就作为<b>运行时防护</b>在你的 AI 应用里运行——上方 ${report.manual} 项（审计留存、运行时拦截、数据外发管控等）即可被真实验证。`,
+      `Add this to your Claude Desktop / Cursor / OpenClaw MCP config and restart — ShellWard then runs as a <b>runtime guard</b>, validating the ${report.manual} ⚪ items above.`)}</p>`)
+    S.push(`<div class="cfg"><pre id="mcpcfg">${esc(cfg)}</pre><button onclick="(function(b){navigator.clipboard&&navigator.clipboard.writeText(document.getElementById('mcpcfg').textContent).then(function(){b.textContent='${t('已复制', 'Copied')}'})})(this)">${t('复制', 'Copy')}</button></div>`)
+    S.push(`<p class="muted">${t('或命令行直接起：', 'Or run directly:')} <code>npx shellward mcp</code> · ${t('文档', 'Docs')}: <a href="https://github.com/jnMetaCode/shellward">github.com/jnMetaCode/shellward</a></p>`)
+  }
+
   const disclaimer = t(
     '本报告由 ShellWard 合规网关自动生成，帮助评估并满足合规技术要求，不构成法律意见，亦不替代算法备案/定级备案/PIA 等主体责任。⚪ 待确认项需结合业务人工判定。',
     'Generated by ShellWard Compliance Gateway. Assists with technical compliance; not legal advice. ⚪ items require manual review.')
@@ -364,6 +380,12 @@ table.tbl td.right{width:64px}
 .manual-note{margin:8px 36px 12px;font-size:13px;color:#475569;background:#eff6ff;
   border-left:3px solid #3b82f6;line-height:1.6}
 .manual-note code{background:#dbeafe;padding:1px 6px;border-radius:5px}
+.cfg{position:relative;margin:8px 36px}
+.cfg pre{background:#0f172a;color:#e2e8f0;border-radius:10px;padding:16px 18px;margin:0;
+  font-family:ui-monospace,Menlo,monospace;font-size:12.5px;overflow-x:auto;line-height:1.5}
+.cfg button{position:absolute;top:10px;right:12px;background:#1e293b;color:#94a3b8;border:0;
+  border-radius:6px;padding:5px 12px;font-size:12px;cursor:pointer}
+.cfg button:hover{color:#fff}
 
 /* 法规分组 */
 .reg{margin:14px 36px;padding:0;border:1px solid var(--line);border-radius:12px;overflow:hidden}

package/src/compliance/report.ts

@@ -130,7 +130,7 @@ export function renderComplianceReport(report: ComplianceReport, locale: 'zh' |
 }
 
 const KIND_LABEL: Record<FindingKind, { zh: string; en: string; icon: string }> = {
-  overseas: { zh: '数据出境风险', en: 'Data export risk', icon: '🌐' },
+  overseas: { zh: '境外大模型调用（需评估出境）', en: 'Overseas LLM (assess export)', icon: '🌐' },
   secret: { zh: '硬编码密钥', en: 'Hardcoded secret', icon: '🔑' },
   pii: { zh: '个人信息暴露', en: 'PII exposure', icon: '🪪' },
   'env-perm': { zh: '.env 权限', en: '.env permission', icon: '📂' },

package/src/init.ts

@@ -0,0 +1,99 @@
+// src/init.ts — `shellward init`：一条命令把 ShellWard 接入已安装的 AI 工具（MCP 运行时防护）
+//
+// 把"扫描 → 运行时防护"的部署摩擦降到一条命令：自动探测 Claude Desktop / Cursor /
+// Claude Code / Windsurf 的 MCP 配置，安全地加入 shellward 条目（备份、合并、不覆盖）。
+// 这是「安装按钮」的正确形态——只对已知配置文件操作、改前备份、可 --dry-run 预览。
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { homedir } from 'os'
+
+/** 标准 MCP 接入条目：零安装，npx 拉取已发布的 shellward-mcp */
+export const SHELLWARD_MCP_ENTRY = {
+  command: 'npx',
+  args: ['-y', '-p', 'shellward', 'shellward-mcp'],
+}
+
+export interface InitTarget {
+  name: string
+  path: string
+  /** 配置里放 MCP 服务器的字段名（绝大多数是 mcpServers） */
+  key: string
+  /** 工具未安装时是否允许新建配置文件 */
+  createIfMissing?: boolean
+}
+
+/** 已知 AI 工具的 MCP 配置位置（跨平台） */
+export function knownTargets(home = homedir()): InitTarget[] {
+  const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming')
+  const claudeDesktop =
+    process.platform === 'darwin' ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+    : process.platform === 'win32' ? join(appData, 'Claude', 'claude_desktop_config.json')
+    : join(home, '.config', 'Claude', 'claude_desktop_config.json')
+  return [
+    { name: 'Claude Desktop', path: claudeDesktop, key: 'mcpServers', createIfMissing: true },
+    { name: 'Cursor', path: join(home, '.cursor', 'mcp.json'), key: 'mcpServers', createIfMissing: true },
+    { name: 'Claude Code', path: join(home, '.claude.json'), key: 'mcpServers' },
+    { name: 'Windsurf', path: join(home, '.codeium', 'windsurf', 'mcp_config.json'), key: 'mcpServers' },
+  ]
+}
+
+export type MergeResult =
+  | { status: 'added' | 'updated'; config: any }
+  | { status: 'unchanged'; config: any }
+
+/**
+ * 纯合并：把 shellward 条目并入配置对象。已存在且相同→unchanged；不同→updated；没有→added。
+ * 不破坏其它 MCP 服务器条目。
+ */
+export function mergeShellward(config: any, key: string): MergeResult {
+  const cfg = config && typeof config === 'object' ? config : {}
+  const servers = cfg[key] && typeof cfg[key] === 'object' ? cfg[key] : {}
+  const existing = servers.shellward
+  const same = existing && JSON.stringify(existing) === JSON.stringify(SHELLWARD_MCP_ENTRY)
+  if (same) return { status: 'unchanged', config: cfg }
+  const status = existing ? 'updated' : 'added'
+  cfg[key] = { ...servers, shellward: { ...SHELLWARD_MCP_ENTRY } }
+  return { status, config: cfg }
+}
+
+export interface InitOutcome {
+  name: string
+  path: string
+  result: 'added' | 'updated' | 'unchanged' | 'skipped' | 'error'
+  detail?: string
+}
+
+/** 执行接入：探测→读取→合并→备份→写回。dryRun 仅预览不写。 */
+export function runInit(opts: { dryRun?: boolean; home?: string } = {}): InitOutcome[] {
+  const targets = knownTargets(opts.home)
+  const out: InitOutcome[] = []
+  for (const t of targets) {
+    const exists = existsSync(t.path)
+    if (!exists && !t.createIfMissing) {
+      out.push({ name: t.name, path: t.path, result: 'skipped', detail: '未安装/无配置' })
+      continue
+    }
+    try {
+      let config: any = {}
+      if (exists) {
+        const raw = readFileSync(t.path, 'utf-8').trim()
+        config = raw ? JSON.parse(raw) : {}
+      }
+      const merged = mergeShellward(config, t.key)
+      if (merged.status === 'unchanged') {
+        out.push({ name: t.name, path: t.path, result: 'unchanged', detail: '已接入' })
+        continue
+      }
+      if (!opts.dryRun) {
+        if (exists) copyFileSync(t.path, t.path + '.shellward.bak') // 改前备份
+        else mkdirSync(dirname(t.path), { recursive: true })
+        writeFileSync(t.path, JSON.stringify(merged.config, null, 2) + '\n')
+      }
+      out.push({ name: t.name, path: t.path, result: merged.status, detail: opts.dryRun ? '预览（未写入）' : (exists ? '已加入（原文件已备份 .bak）' : '已新建配置') })
+    } catch (e: any) {
+      out.push({ name: t.name, path: t.path, result: 'error', detail: e?.message || String(e) })
+    }
+  }
+  return out
+}