shellward 0.6.2 → 0.6.4

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-233%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-251%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 [English](#demo) | [中文](#中文)
@@ -34,9 +34,9 @@ Outputs a red/yellow/green scorecard mapped to 网安法 / PIPL / 等保2.0 /
 合规得分: 75/100  [B]   🟢 8 ｜ 🟡 3 ｜ 🔴 1 ｜ ⚪ 2
 ```
 
-`npx shellward scan --json` for CI · `--ci` to fail the build on critical findings · see [GitHub Action](#github-action-pr-compliance-gate).
+`npx shellward scan --json` for CI · `--ci` to fail the build on critical findings · `--html report.html` for a self-contained report you can print to PDF for 备案/audit · see [GitHub Action](#github-action-pr-compliance-gate).
 
-> Detects overseas-LLM endpoints (**data-export risk** — a China-only concept English tools ignore), hardcoded secrets, Chinese PII in files, and `.env` exposure.
+> Detects overseas-LLM endpoints (**data-export risk** — a China-only concept English tools ignore), hardcoded secrets, Chinese PII in files, and `.env` exposure. When it finds an overseas model (e.g. an `openai` dependency), it **prescribes domestic compliant alternatives** (通义千问 / DeepSeek / Kimi / 智谱) with their OpenAI-compatible `base_url` — most migrations are just a `base_url` swap.
 
 ## Demo
 

package/dist/cli.js

@@ -13,6 +13,7 @@ import { writeFileSync } from 'fs';
 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 { resolveLocale } from './types.js';
 const argv = process.argv.slice(2);
 const wantsHelp = argv.includes('--help') || argv.includes('-h') || argv[0] === 'help';
@@ -39,6 +40,7 @@ function runScan(args) {
     const json = args.includes('--json');
     const ci = args.includes('--ci');
     const outPath = flagValue(args, '--out');
+    const htmlPath = flagValue(args, '--html');
     const dirArg = args.find(a => !a.startsWith('-'));
     const root = resolve(dirArg || process.cwd());
     // 用环境变量解析 locale；layers/mode 用默认（代表「采用 ShellWard 默认部署」的合规覆盖）
@@ -67,6 +69,13 @@ function runScan(args) {
             })),
         }, null, 2) + '\n');
     }
+    else if (htmlPath) {
+        const html = renderHtmlReport(report, scan, locale, { root });
+        writeFileSync(resolve(htmlPath), html, 'utf-8');
+        process.stdout.write(zh
+            ? `✅ HTML 合规报告已导出: ${resolve(htmlPath)}\n   得分 ${report.score}/100 [${report.grade}]，浏览器打开可打印成 PDF，供备案/审计存档。\n`
+            : `✅ HTML compliance report exported: ${resolve(htmlPath)}\n   Score ${report.score}/100 [${report.grade}]. Open in a browser, print to PDF.\n`);
+    }
     else {
         // 头条：项目实测风险（关于「你的项目」）+ 合规映射评分卡
         const body = [
@@ -117,6 +126,7 @@ Usage:
   shellward scan --json    Output JSON (for CI)
   shellward scan --ci      Exit non-zero if critical findings
   shellward scan --out f   Export the full report to a Markdown file
+  shellward scan --html f  Export a self-contained HTML report (print to PDF)
   shellward mcp            Start MCP server (stdio)
   shellward --help
 
@@ -131,6 +141,7 @@ PII in files, .env permissions. Maps to CSL / PIPL / MLPS / cross-border / label
   shellward scan --json     输出 JSON（CI 用）
   shellward scan --ci       有 critical 发现时非零退出
   shellward scan --out 文件  导出完整报告为 Markdown（合规存档）
+  shellward scan --html 文件 导出自包含 HTML 报告（浏览器可打印成 PDF）
   shellward mcp             启动 MCP 服务器（stdio）
   shellward --help
 

package/dist/compliance/html-report.d.ts

@@ -0,0 +1,8 @@
+import type { ComplianceReport } from './audit.js';
+import type { ProjectScanResult } from './project-scan.js';
+export interface HtmlReportMeta {
+    /** 扫描的项目根 */
+    root: string;
+}
+/** 生成自包含 HTML 合规报告 */
+export declare function renderHtmlReport(report: ComplianceReport, scan: ProjectScanResult, locale: 'zh' | 'en', meta: HtmlReportMeta): string;

package/dist/compliance/html-report.js

@@ -0,0 +1,185 @@
+// src/compliance/html-report.ts — HTML 合规报告（合规包雏形）
+//
+// 终端输出给开发者看；这份 HTML 给法务/合规/测评机构看 —— 可在浏览器打开、
+// 打印成 PDF、用于等保/PIPL 备案存档。自包含（内联 CSS、零外部依赖、无需联网）。
+import { REGULATION_NAMES } from './regulations.js';
+import { suggestDomestic } from '../rules/domestic-alternatives.js';
+const STATUS = {
+    pass: { zh: '合规', en: 'Pass', cls: 'pass' },
+    warn: { zh: '部分', en: 'Partial', cls: 'warn' },
+    fail: { zh: '不合规', en: 'Fail', cls: 'fail' },
+    manual: { zh: '待确认', en: 'Manual', cls: 'manual' },
+};
+const KIND = {
+    overseas: { zh: '数据出境风险', en: 'Data export risk' },
+    secret: { zh: '硬编码密钥', en: 'Hardcoded secret' },
+    pii: { zh: '个人信息暴露', en: 'PII exposure' },
+    'env-perm': { zh: '.env 权限', en: '.env permission' },
+};
+const KIND_ORDER = ['overseas', 'secret', 'pii', 'env-perm'];
+const REG_ORDER = ['CSL', 'PIPL', 'MLPS', 'CBDT', 'GENAI'];
+const GRADE_COLOR = { A: '#15803d', B: '#65a30d', C: '#d97706', D: '#dc2626' };
+/** 生成自包含 HTML 合规报告 */
+export function renderHtmlReport(report, scan, locale, meta) {
+    const zh = locale === 'zh';
+    const t = (z, e) => (zh ? z : e);
+    const gradeColor = GRADE_COLOR[report.grade] || '#475569';
+    const when = report.generatedAt.slice(0, 19).replace('T', ' ');
+    const sections = [];
+    // ===== 评分卡 =====
+    sections.push(`
+  <section class="score-card">
+    <div class="gauge" style="--c:${gradeColor}">
+      <div class="score">${report.score}<span>/100</span></div>
+      <div class="grade" style="color:${gradeColor}">${esc(report.grade)}</div>
+    </div>
+    <div class="summary">
+      <div class="bar"><div class="fill" style="width:${report.score}%;background:${gradeColor}"></div></div>
+      <ul class="counts">
+        <li class="pass">🟢 ${t('合规', 'Pass')} ${report.passed}</li>
+        <li class="warn">🟡 ${t('部分', 'Partial')} ${report.warned}</li>
+        <li class="fail">🔴 ${t('不合规', 'Fail')} ${report.failed}</li>
+        <li class="manual">⚪ ${t('待确认', 'Manual')} ${report.manual}</li>
+      </ul>
+      ${report.projectPenalty ? `<p class="penalty">${t('含项目实测风险扣分', 'Includes project-scan penalty')} −${report.projectPenalty}</p>` : ''}
+    </div>
+  </section>`);
+    // ===== 项目实测风险 =====
+    sections.push(`<h2>🔍 ${t('项目实测风险', 'Project Scan Findings')}</h2>`);
+    sections.push(`<p class="muted">${t('已扫描', 'Scanned')} ${scan.filesScanned} ${t('个文件', 'files')}${scan.truncated ? t('（已达上限）', ' (limit reached)') : ''}</p>`);
+    if (scan.findings.length === 0) {
+        sections.push(`<p class="ok">🟢 ${t('未在项目文件中发现硬编码密钥、个人信息暴露或境外端点。', 'No hardcoded secrets, PII, or overseas endpoints found.')}</p>`);
+    }
+    else {
+        for (const kind of KIND_ORDER) {
+            const items = scan.findings.filter(f => f.kind === kind);
+            if (items.length === 0)
+                continue;
+            sections.push(`<h3>${t(KIND[kind].zh, KIND[kind].en)} (${items.length})</h3>`);
+            sections.push('<table class="findings"><thead><tr>'
+                + `<th>${t('位置', 'Location')}</th><th>${t('说明', 'Detail')}</th><th>${t('严重度', 'Severity')}</th></tr></thead><tbody>`);
+            for (const f of items) {
+                const loc = f.line ? `${f.file}:${f.line}` : f.file;
+                sections.push(`<tr><td class="loc">${esc(loc)}</td><td>${esc(f.detail)}</td><td class="sev-${f.severity}">${f.severity}</td></tr>`);
+            }
+            sections.push('</tbody></table>');
+        }
+    }
+    // ===== 境内合规替代建议 =====
+    const overseas = scan.findings.filter(f => f.kind === 'overseas');
+    if (overseas.length > 0) {
+        const seen = new Set();
+        const providers = [];
+        for (const f of overseas) {
+            const k = (f.endpointId || f.provider_en || f.provider_zh || '').toLowerCase();
+            if (!k || seen.has(k))
+                continue;
+            seen.add(k);
+            providers.push({ key: f.endpointId || f.provider_en || '', zh: f.provider_zh, en: f.provider_en });
+        }
+        sections.push(`<h2>✅ ${t('境内合规替代建议', 'Domestic Compliance Alternatives')}</h2>`);
+        sections.push('<ul class="migrate">');
+        for (const p of providers) {
+            const s = suggestDomestic(p.key, p.zh, p.en);
+            sections.push(`<li><b>${esc(zh ? s.overseas_zh : s.overseas_en)}</b> → ${esc(zh ? s.difficulty_zh : s.difficulty_en)}</li>`);
+        }
+        sections.push('</ul>');
+        const alts = suggestDomestic(providers[0].key, providers[0].zh, providers[0].en).alternatives;
+        sections.push('<table class="findings"><thead><tr>'
+            + `<th>${t('境内模型', 'Domestic model')}</th><th>${t('厂商', 'Vendor')}</th><th>${t('OpenAI 兼容 base_url', 'OpenAI-compatible base_url')}</th></tr></thead><tbody>`);
+        for (const m of alts) {
+            sections.push(`<tr><td>${esc(zh ? m.name_zh : m.name_en)}</td><td>${esc(m.vendor_zh)}</td><td class="loc">${esc(m.baseUrl)}</td></tr>`);
+        }
+        sections.push('</tbody></table>');
+        sections.push(`<p class="muted">${t('对使用 openai SDK 的项目：通常仅需把 base_url 与 api_key 换成上表任一境内模型即可，业务代码无需改动。', 'For openai-SDK projects: usually just swap base_url + api_key — no code change.')}</p>`);
+    }
+    // ===== 控制项明细 =====
+    sections.push(`<h2>📋 ${t('合规控制项明细', 'Compliance Controls')}</h2>`);
+    const grouped = groupBy(report.results);
+    for (const reg of REG_ORDER) {
+        const items = grouped[reg];
+        if (!items || items.length === 0)
+            continue;
+        sections.push(`<h3>${esc(zh ? REGULATION_NAMES[reg].zh : REGULATION_NAMES[reg].en)}</h3>`);
+        sections.push('<table class="controls"><thead><tr>'
+            + `<th>${t('状态', 'Status')}</th><th>${t('控制项', 'Control')}</th><th>${t('条款', 'Article')}</th><th>${t('结论', 'Result')}</th></tr></thead><tbody>`);
+        for (const r of items) {
+            const st = STATUS[r.status];
+            sections.push(`<tr><td><span class="badge ${st.cls}">${zh ? st.zh : st.en}</span></td>`
+                + `<td>${esc(zh ? r.control.title_zh : r.control.title_en)}</td>`
+                + `<td class="loc">${esc(r.control.article)}</td>`
+                + `<td>${esc(zh ? r.detail_zh : r.detail_en)}</td></tr>`);
+        }
+        sections.push('</tbody></table>');
+    }
+    const disclaimer = t('本报告由 ShellWard 合规网关自动生成，帮助评估并满足合规技术要求，不构成法律意见，亦不替代算法备案/定级备案/PIA 等主体责任。⚪ 待确认项需结合业务人工判定。', 'Generated by ShellWard Compliance Gateway. Assists with technical compliance; not legal advice.');
+    return `<!DOCTYPE html>
+<html lang="${zh ? 'zh-CN' : 'en'}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${t('AI 应用合规体检报告', 'AI Compliance Report')}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+  <header>
+    <h1>🛡️ ${t('AI 应用合规体检报告', 'AI Application Compliance Report')}</h1>
+    <p class="meta">${t('生成时间', 'Generated')}: ${esc(when)} UTC ｜ ${t('扫描目录', 'Scanned')}: <code>${esc(meta.root)}</code></p>
+  </header>
+  ${sections.join('\n')}
+  <footer>${esc(disclaimer)}</footer>
+</main>
+</body>
+</html>`;
+}
+function groupBy(results) {
+    const out = {};
+    for (const r of results)
+        (out[r.control.regulation] ||= []).push(r);
+    return out;
+}
+/** HTML 转义，防止文件路径/详情里的特殊字符破坏结构 */
+function esc(s) {
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const CSS = `
+:root{--ink:#1e293b;--muted:#64748b;--line:#e2e8f0;--bg:#f8fafc}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}
+main{max-width:920px;margin:0 auto;padding:32px 24px;background:#fff}
+header{border-bottom:2px solid var(--line);padding-bottom:16px;margin-bottom:24px}
+h1{font-size:24px;margin:0 0 6px}
+h2{font-size:19px;margin:32px 0 12px;padding-bottom:6px;border-bottom:1px solid var(--line)}
+h3{font-size:15px;margin:20px 0 8px;color:var(--muted)}
+.meta{color:var(--muted);font-size:13px;margin:0}
+code{background:#f1f5f9;padding:1px 5px;border-radius:4px;font-size:13px}
+.score-card{display:flex;gap:28px;align-items:center;background:#f1f5f9;border-radius:12px;padding:24px}
+.gauge{text-align:center;min-width:120px}
+.gauge .score{font-size:44px;font-weight:700;color:var(--c)}
+.gauge .score span{font-size:18px;color:var(--muted);font-weight:400}
+.gauge .grade{font-size:28px;font-weight:700}
+.summary{flex:1}
+.bar{height:14px;background:#e2e8f0;border-radius:7px;overflow:hidden;margin-bottom:12px}
+.bar .fill{height:100%}
+.counts{list-style:none;display:flex;gap:18px;flex-wrap:wrap;padding:0;margin:0;font-size:14px}
+.penalty{color:#dc2626;font-size:13px;margin:8px 0 0}
+table{width:100%;border-collapse:collapse;margin:8px 0 4px;font-size:13.5px}
+th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line);vertical-align:top}
+th{background:#f8fafc;font-weight:600;color:var(--muted)}
+.loc{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12.5px;color:#0f172a;white-space:nowrap}
+.sev-critical{color:#dc2626;font-weight:600}.sev-high{color:#ea580c}.sev-medium{color:#d97706}
+.badge{display:inline-block;padding:2px 8px;border-radius:999px;font-size:12px;font-weight:600}
+.badge.pass{background:#dcfce7;color:#15803d}.badge.warn{background:#fef9c3;color:#a16207}
+.badge.fail{background:#fee2e2;color:#b91c1c}.badge.manual{background:#e2e8f0;color:#475569}
+.muted{color:var(--muted);font-size:13px}
+.ok{color:#15803d;font-weight:600}
+.migrate{margin:8px 0}
+footer{margin-top:36px;padding-top:16px;border-top:1px solid var(--line);color:var(--muted);font-size:12px}
+@media print{body{background:#fff}main{max-width:none;padding:0}h2{break-after:avoid}table{break-inside:auto}tr{break-inside:avoid}}
+`;

package/dist/compliance/report.js

@@ -3,6 +3,7 @@
 // 把 ComplianceReport 渲染成红黄绿评分卡（可截图传播 = 月1 获客钩子）。
 // 按法规分组，每项给状态图标 + 结论 + 整改建议。
 import { REGULATION_NAMES } from './regulations.js';
+import { suggestDomestic } from '../rules/domestic-alternatives.js';
 const STATUS_ICON = {
     pass: '🟢',
     warn: '🟡',
@@ -139,8 +140,55 @@ export function renderProjectFindings(scan, locale) {
         }
         L.push('');
     }
+    // 处方：境内合规替代建议（仅当存在境外模型风险时）
+    L.push(...renderDomesticGuidance(scan, locale));
     return L.join('\n');
 }
+/** 渲染「境内合规替代建议」—— 把数据出境风险变成可执行的迁移处方 */
+function renderDomesticGuidance(scan, locale) {
+    const zh = locale === 'zh';
+    const overseas = scan.findings.filter(f => f.kind === 'overseas');
+    if (overseas.length === 0)
+        return [];
+    // 去重境外厂商
+    const seen = new Set();
+    const providers = [];
+    for (const f of overseas) {
+        const key = (f.endpointId || f.provider_en || f.provider_zh || '').toLowerCase();
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        providers.push({ key: f.endpointId || f.provider_en || '', zh: f.provider_zh, en: f.provider_en });
+    }
+    const L = [];
+    L.push(zh ? '## ✅ 境内合规替代建议' : '## ✅ Domestic Compliance Alternatives');
+    L.push('');
+    L.push(zh
+        ? '把数据出境风险变成可执行的迁移路径。境内主流模型多为 **OpenAI 兼容**接口：'
+        : 'Turn data-export risk into a concrete migration path. Most domestic models are **OpenAI-compatible**:');
+    L.push('');
+    // 每个境外厂商的迁移难度
+    for (const p of providers) {
+        const s = suggestDomestic(p.key, p.zh, p.en);
+        L.push(zh
+            ? `- **${s.overseas_zh}** → 迁移难度: ${s.difficulty_zh}`
+            : `- **${s.overseas_en}** → migration: ${s.difficulty_en}`);
+    }
+    L.push('');
+    // 共享的境内候选表（取第一个建议的 alternatives，避免重复）
+    const alts = suggestDomestic(providers[0].key, providers[0].zh, providers[0].en).alternatives;
+    L.push(zh ? '| 境内模型 | 厂商 | OpenAI 兼容 base_url |' : '| Domestic model | Vendor | OpenAI-compatible base_url |');
+    L.push('|---|---|---|');
+    for (const m of alts) {
+        L.push(`| ${zh ? m.name_zh : m.name_en} | ${m.vendor_zh} | \`${m.baseUrl}\` |`);
+    }
+    L.push('');
+    L.push(zh
+        ? '> 对使用 `openai` SDK 的项目：通常仅需把 `base_url` 与 `api_key` 换成上表任一境内模型即可，业务代码无需改动。迁移前请以各厂商官方文档为准。'
+        : '> For projects using the `openai` SDK: usually just swap `base_url` + `api_key` to a domestic model above — no business-code change. Verify against each vendor’s official docs first.');
+    L.push('');
+    return L;
+}
 function scoreBar(score) {
     const filled = Math.round(score / 5);
     return '█'.repeat(filled) + '░'.repeat(20 - filled);

package/dist/rules/domestic-alternatives.d.ts

@@ -0,0 +1,27 @@
+export interface DomesticModel {
+    id: string;
+    name_zh: string;
+    name_en: string;
+    vendor_zh: string;
+    /** OpenAI 兼容 base_url（若支持） */
+    baseUrl: string;
+    /** 是否提供 OpenAI 兼容接口（决定迁移难度） */
+    openaiCompatible: boolean;
+}
+/** 境内主流大模型（均为境内可备案/合规部署，按知名度排序） */
+export declare const DOMESTIC_MODELS: DomesticModel[];
+export interface DomesticSuggestion {
+    /** 触发的境外厂商（中文） */
+    overseas_zh: string;
+    overseas_en: string;
+    /** 迁移难度 */
+    difficulty_zh: string;
+    difficulty_en: string;
+    /** 推荐的境内替代（取兼容优先的前几个） */
+    alternatives: DomesticModel[];
+}
+/**
+ * 针对某个境外厂商给出境内替代建议。
+ * @param key endpointId（如 'openai'）或 provider_en（如 'OpenAI'）
+ */
+export declare function suggestDomestic(key: string, provider_zh?: string, provider_en?: string): DomesticSuggestion;

package/dist/rules/domestic-alternatives.js

@@ -0,0 +1,62 @@
+// src/rules/domestic-alternatives.ts — 境内已备案大模型替代建议
+//
+// 扫到境外大模型（端点/SDK 依赖）后，给出可执行的「境内合规替代」处方：
+// 把"你有数据出境风险"变成"换成这个、这样换"。这是 ShellWard 面向中国
+// 市场最具差异化、最可执行的一环 —— 英文工具不会做。
+//
+// 杀手锏：境内主流模型多数提供 **OpenAI 兼容接口**，对 `openai` SDK 的项目
+// 往往只需改 base_url + api key、代码零改动即可迁移到合规模型。
+//
+// 注：base_url 为各厂商公开的 OpenAI 兼容端点（可能随官方调整，迁移前以官方文档为准）。
+/** 境内主流大模型（均为境内可备案/合规部署，按知名度排序） */
+export const DOMESTIC_MODELS = [
+    {
+        id: 'qwen', name_zh: '通义千问', name_en: 'Qwen', vendor_zh: '阿里云百炼/DashScope',
+        baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1', openaiCompatible: true,
+    },
+    {
+        id: 'deepseek', name_zh: 'DeepSeek', name_en: 'DeepSeek', vendor_zh: '深度求索',
+        baseUrl: 'https://api.deepseek.com', openaiCompatible: true,
+    },
+    {
+        id: 'kimi', name_zh: 'Kimi', name_en: 'Kimi (Moonshot)', vendor_zh: '月之暗面',
+        baseUrl: 'https://api.moonshot.cn/v1', openaiCompatible: true,
+    },
+    {
+        id: 'glm', name_zh: '智谱 GLM', name_en: 'Zhipu GLM', vendor_zh: '智谱 AI',
+        baseUrl: 'https://open.bigmodel.cn/api/paas/v4', openaiCompatible: true,
+    },
+    {
+        id: 'doubao', name_zh: '豆包', name_en: 'Doubao', vendor_zh: '字节火山方舟',
+        baseUrl: 'https://ark.cn-beijing.volces.com/api/v3', openaiCompatible: true,
+    },
+    {
+        id: 'ernie', name_zh: '文心一言', name_en: 'ERNIE', vendor_zh: '百度千帆',
+        baseUrl: 'https://qianfan.baidubce.com/v2', openaiCompatible: true,
+    },
+];
+// 哪些境外厂商走 OpenAI 兼容协议（其 SDK 项目可零代码迁移到境内兼容端点）
+const OPENAI_PROTOCOL = new Set(['openai', 'azure-openai', 'groq', 'together', 'mistral', 'perplexity', 'openrouter', 'xai']);
+/**
+ * 针对某个境外厂商给出境内替代建议。
+ * @param key endpointId（如 'openai'）或 provider_en（如 'OpenAI'）
+ */
+export function suggestDomestic(key, provider_zh, provider_en) {
+    const k = key.toLowerCase();
+    const isOpenAiProtocol = OPENAI_PROTOCOL.has(k) || /openai/.test(k);
+    // 推荐：OpenAI 兼容的境内模型优先（迁移最省事）
+    const alternatives = DOMESTIC_MODELS.filter(m => m.openaiCompatible).slice(0, 4);
+    const difficulty_zh = isOpenAiProtocol
+        ? '低 — 多为 OpenAI 兼容协议，通常只需改 base_url + API key，代码零改动'
+        : '中 — SDK 不同，建议改用境内模型的 OpenAI 兼容端点并调整调用代码';
+    const difficulty_en = isOpenAiProtocol
+        ? 'Low — OpenAI-compatible; usually just swap base_url + API key, no code change'
+        : 'Medium — different SDK; switch to a domestic OpenAI-compatible endpoint and adjust calls';
+    return {
+        overseas_zh: provider_zh || key,
+        overseas_en: provider_en || key,
+        difficulty_zh,
+        difficulty_en,
+        alternatives,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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": [

package/src/cli.ts

@@ -14,6 +14,7 @@ import { writeFileSync } from 'fs'
 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 { resolveLocale } from './types.js'
 
 const argv = process.argv.slice(2)
@@ -46,6 +47,7 @@ function runScan(args: string[]) {
   const json = args.includes('--json')
   const ci = args.includes('--ci')
   const outPath = flagValue(args, '--out')
+  const htmlPath = flagValue(args, '--html')
   const dirArg = args.find(a => !a.startsWith('-'))
   const root = resolve(dirArg || process.cwd())
 
@@ -76,6 +78,12 @@ function runScan(args: string[]) {
         id: r.control.id, regulation: r.control.regulation, status: r.status,
       })),
     }, null, 2) + '\n')
+  } else if (htmlPath) {
+    const html = renderHtmlReport(report, scan, locale, { root })
+    writeFileSync(resolve(htmlPath), html, 'utf-8')
+    process.stdout.write(zh
+      ? `✅ HTML 合规报告已导出: ${resolve(htmlPath)}\n   得分 ${report.score}/100 [${report.grade}]，浏览器打开可打印成 PDF，供备案/审计存档。\n`
+      : `✅ HTML compliance report exported: ${resolve(htmlPath)}\n   Score ${report.score}/100 [${report.grade}]. Open in a browser, print to PDF.\n`)
   } else {
     // 头条：项目实测风险（关于「你的项目」）+ 合规映射评分卡
     const body = [
@@ -127,6 +135,7 @@ Usage:
   shellward scan --json    Output JSON (for CI)
   shellward scan --ci      Exit non-zero if critical findings
   shellward scan --out f   Export the full report to a Markdown file
+  shellward scan --html f  Export a self-contained HTML report (print to PDF)
   shellward mcp            Start MCP server (stdio)
   shellward --help
 
@@ -140,6 +149,7 @@ PII in files, .env permissions. Maps to CSL / PIPL / MLPS / cross-border / label
   shellward scan --json     输出 JSON（CI 用）
   shellward scan --ci       有 critical 发现时非零退出
   shellward scan --out 文件  导出完整报告为 Markdown（合规存档）
+  shellward scan --html 文件 导出自包含 HTML 报告（浏览器可打印成 PDF）
   shellward mcp             启动 MCP 服务器（stdio）
   shellward --help
 

package/src/compliance/html-report.ts

@@ -0,0 +1,210 @@
+// src/compliance/html-report.ts — HTML 合规报告（合规包雏形）
+//
+// 终端输出给开发者看；这份 HTML 给法务/合规/测评机构看 —— 可在浏览器打开、
+// 打印成 PDF、用于等保/PIPL 备案存档。自包含（内联 CSS、零外部依赖、无需联网）。
+
+import { REGULATION_NAMES } from './regulations.js'
+import type { Regulation } from './regulations.js'
+import type { ComplianceReport, ControlResult, ControlStatus } from './audit.js'
+import type { ProjectScanResult, FindingKind } from './project-scan.js'
+import { suggestDomestic } from '../rules/domestic-alternatives.js'
+
+const STATUS: Record<ControlStatus, { zh: string; en: string; cls: string }> = {
+  pass: { zh: '合规', en: 'Pass', cls: 'pass' },
+  warn: { zh: '部分', en: 'Partial', cls: 'warn' },
+  fail: { zh: '不合规', en: 'Fail', cls: 'fail' },
+  manual: { zh: '待确认', en: 'Manual', cls: 'manual' },
+}
+
+const KIND: Record<FindingKind, { zh: string; en: string }> = {
+  overseas: { zh: '数据出境风险', en: 'Data export risk' },
+  secret: { zh: '硬编码密钥', en: 'Hardcoded secret' },
+  pii: { zh: '个人信息暴露', en: 'PII exposure' },
+  'env-perm': { zh: '.env 权限', en: '.env permission' },
+}
+const KIND_ORDER: FindingKind[] = ['overseas', 'secret', 'pii', 'env-perm']
+const REG_ORDER: Regulation[] = ['CSL', 'PIPL', 'MLPS', 'CBDT', 'GENAI']
+
+const GRADE_COLOR: Record<string, string> = { A: '#15803d', B: '#65a30d', C: '#d97706', D: '#dc2626' }
+
+export interface HtmlReportMeta {
+  /** 扫描的项目根 */
+  root: string
+}
+
+/** 生成自包含 HTML 合规报告 */
+export function renderHtmlReport(
+  report: ComplianceReport,
+  scan: ProjectScanResult,
+  locale: 'zh' | 'en',
+  meta: HtmlReportMeta,
+): string {
+  const zh = locale === 'zh'
+  const t = (z: string, e: string) => (zh ? z : e)
+  const gradeColor = GRADE_COLOR[report.grade] || '#475569'
+  const when = report.generatedAt.slice(0, 19).replace('T', ' ')
+
+  const sections: string[] = []
+
+  // ===== 评分卡 =====
+  sections.push(`
+  <section class="score-card">
+    <div class="gauge" style="--c:${gradeColor}">
+      <div class="score">${report.score}<span>/100</span></div>
+      <div class="grade" style="color:${gradeColor}">${esc(report.grade)}</div>
+    </div>
+    <div class="summary">
+      <div class="bar"><div class="fill" style="width:${report.score}%;background:${gradeColor}"></div></div>
+      <ul class="counts">
+        <li class="pass">🟢 ${t('合规', 'Pass')} ${report.passed}</li>
+        <li class="warn">🟡 ${t('部分', 'Partial')} ${report.warned}</li>
+        <li class="fail">🔴 ${t('不合规', 'Fail')} ${report.failed}</li>
+        <li class="manual">⚪ ${t('待确认', 'Manual')} ${report.manual}</li>
+      </ul>
+      ${report.projectPenalty ? `<p class="penalty">${t('含项目实测风险扣分', 'Includes project-scan penalty')} −${report.projectPenalty}</p>` : ''}
+    </div>
+  </section>`)
+
+  // ===== 项目实测风险 =====
+  sections.push(`<h2>🔍 ${t('项目实测风险', 'Project Scan Findings')}</h2>`)
+  sections.push(`<p class="muted">${t('已扫描', 'Scanned')} ${scan.filesScanned} ${t('个文件', 'files')}${scan.truncated ? t('（已达上限）', ' (limit reached)') : ''}</p>`)
+  if (scan.findings.length === 0) {
+    sections.push(`<p class="ok">🟢 ${t('未在项目文件中发现硬编码密钥、个人信息暴露或境外端点。', 'No hardcoded secrets, PII, or overseas endpoints found.')}</p>`)
+  } else {
+    for (const kind of KIND_ORDER) {
+      const items = scan.findings.filter(f => f.kind === kind)
+      if (items.length === 0) continue
+      sections.push(`<h3>${t(KIND[kind].zh, KIND[kind].en)} (${items.length})</h3>`)
+      sections.push('<table class="findings"><thead><tr>'
+        + `<th>${t('位置', 'Location')}</th><th>${t('说明', 'Detail')}</th><th>${t('严重度', 'Severity')}</th></tr></thead><tbody>`)
+      for (const f of items) {
+        const loc = f.line ? `${f.file}:${f.line}` : f.file
+        sections.push(`<tr><td class="loc">${esc(loc)}</td><td>${esc(f.detail)}</td><td class="sev-${f.severity}">${f.severity}</td></tr>`)
+      }
+      sections.push('</tbody></table>')
+    }
+  }
+
+  // ===== 境内合规替代建议 =====
+  const overseas = scan.findings.filter(f => f.kind === 'overseas')
+  if (overseas.length > 0) {
+    const seen = new Set<string>()
+    const providers: { key: string; zh?: string; en?: string }[] = []
+    for (const f of overseas) {
+      const k = (f.endpointId || f.provider_en || f.provider_zh || '').toLowerCase()
+      if (!k || seen.has(k)) continue
+      seen.add(k)
+      providers.push({ key: f.endpointId || f.provider_en || '', zh: f.provider_zh, en: f.provider_en })
+    }
+    sections.push(`<h2>✅ ${t('境内合规替代建议', 'Domestic Compliance Alternatives')}</h2>`)
+    sections.push('<ul class="migrate">')
+    for (const p of providers) {
+      const s = suggestDomestic(p.key, p.zh, p.en)
+      sections.push(`<li><b>${esc(zh ? s.overseas_zh : s.overseas_en)}</b> → ${esc(zh ? s.difficulty_zh : s.difficulty_en)}</li>`)
+    }
+    sections.push('</ul>')
+    const alts = suggestDomestic(providers[0].key, providers[0].zh, providers[0].en).alternatives
+    sections.push('<table class="findings"><thead><tr>'
+      + `<th>${t('境内模型', 'Domestic model')}</th><th>${t('厂商', 'Vendor')}</th><th>${t('OpenAI 兼容 base_url', 'OpenAI-compatible base_url')}</th></tr></thead><tbody>`)
+    for (const m of alts) {
+      sections.push(`<tr><td>${esc(zh ? m.name_zh : m.name_en)}</td><td>${esc(m.vendor_zh)}</td><td class="loc">${esc(m.baseUrl)}</td></tr>`)
+    }
+    sections.push('</tbody></table>')
+    sections.push(`<p class="muted">${t('对使用 openai SDK 的项目：通常仅需把 base_url 与 api_key 换成上表任一境内模型即可，业务代码无需改动。', 'For openai-SDK projects: usually just swap base_url + api_key — no code change.')}</p>`)
+  }
+
+  // ===== 控制项明细 =====
+  sections.push(`<h2>📋 ${t('合规控制项明细', 'Compliance Controls')}</h2>`)
+  const grouped = groupBy(report.results)
+  for (const reg of REG_ORDER) {
+    const items = grouped[reg]
+    if (!items || items.length === 0) continue
+    sections.push(`<h3>${esc(zh ? REGULATION_NAMES[reg].zh : REGULATION_NAMES[reg].en)}</h3>`)
+    sections.push('<table class="controls"><thead><tr>'
+      + `<th>${t('状态', 'Status')}</th><th>${t('控制项', 'Control')}</th><th>${t('条款', 'Article')}</th><th>${t('结论', 'Result')}</th></tr></thead><tbody>`)
+    for (const r of items) {
+      const st = STATUS[r.status]
+      sections.push(`<tr><td><span class="badge ${st.cls}">${zh ? st.zh : st.en}</span></td>`
+        + `<td>${esc(zh ? r.control.title_zh : r.control.title_en)}</td>`
+        + `<td class="loc">${esc(r.control.article)}</td>`
+        + `<td>${esc(zh ? r.detail_zh : r.detail_en)}</td></tr>`)
+    }
+    sections.push('</tbody></table>')
+  }
+
+  const disclaimer = t(
+    '本报告由 ShellWard 合规网关自动生成，帮助评估并满足合规技术要求，不构成法律意见，亦不替代算法备案/定级备案/PIA 等主体责任。⚪ 待确认项需结合业务人工判定。',
+    'Generated by ShellWard Compliance Gateway. Assists with technical compliance; not legal advice.')
+
+  return `<!DOCTYPE html>
+<html lang="${zh ? 'zh-CN' : 'en'}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${t('AI 应用合规体检报告', 'AI Compliance Report')}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+  <header>
+    <h1>🛡️ ${t('AI 应用合规体检报告', 'AI Application Compliance Report')}</h1>
+    <p class="meta">${t('生成时间', 'Generated')}: ${esc(when)} UTC ｜ ${t('扫描目录', 'Scanned')}: <code>${esc(meta.root)}</code></p>
+  </header>
+  ${sections.join('\n')}
+  <footer>${esc(disclaimer)}</footer>
+</main>
+</body>
+</html>`
+}
+
+function groupBy(results: ControlResult[]): Record<Regulation, ControlResult[]> {
+  const out = {} as Record<Regulation, ControlResult[]>
+  for (const r of results) (out[r.control.regulation] ||= []).push(r)
+  return out
+}
+
+/** HTML 转义，防止文件路径/详情里的特殊字符破坏结构 */
+function esc(s: string): string {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+const CSS = `
+:root{--ink:#1e293b;--muted:#64748b;--line:#e2e8f0;--bg:#f8fafc}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}
+main{max-width:920px;margin:0 auto;padding:32px 24px;background:#fff}
+header{border-bottom:2px solid var(--line);padding-bottom:16px;margin-bottom:24px}
+h1{font-size:24px;margin:0 0 6px}
+h2{font-size:19px;margin:32px 0 12px;padding-bottom:6px;border-bottom:1px solid var(--line)}
+h3{font-size:15px;margin:20px 0 8px;color:var(--muted)}
+.meta{color:var(--muted);font-size:13px;margin:0}
+code{background:#f1f5f9;padding:1px 5px;border-radius:4px;font-size:13px}
+.score-card{display:flex;gap:28px;align-items:center;background:#f1f5f9;border-radius:12px;padding:24px}
+.gauge{text-align:center;min-width:120px}
+.gauge .score{font-size:44px;font-weight:700;color:var(--c)}
+.gauge .score span{font-size:18px;color:var(--muted);font-weight:400}
+.gauge .grade{font-size:28px;font-weight:700}
+.summary{flex:1}
+.bar{height:14px;background:#e2e8f0;border-radius:7px;overflow:hidden;margin-bottom:12px}
+.bar .fill{height:100%}
+.counts{list-style:none;display:flex;gap:18px;flex-wrap:wrap;padding:0;margin:0;font-size:14px}
+.penalty{color:#dc2626;font-size:13px;margin:8px 0 0}
+table{width:100%;border-collapse:collapse;margin:8px 0 4px;font-size:13.5px}
+th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line);vertical-align:top}
+th{background:#f8fafc;font-weight:600;color:var(--muted)}
+.loc{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12.5px;color:#0f172a;white-space:nowrap}
+.sev-critical{color:#dc2626;font-weight:600}.sev-high{color:#ea580c}.sev-medium{color:#d97706}
+.badge{display:inline-block;padding:2px 8px;border-radius:999px;font-size:12px;font-weight:600}
+.badge.pass{background:#dcfce7;color:#15803d}.badge.warn{background:#fef9c3;color:#a16207}
+.badge.fail{background:#fee2e2;color:#b91c1c}.badge.manual{background:#e2e8f0;color:#475569}
+.muted{color:var(--muted);font-size:13px}
+.ok{color:#15803d;font-weight:600}
+.migrate{margin:8px 0}
+footer{margin-top:36px;padding-top:16px;border-top:1px solid var(--line);color:var(--muted);font-size:12px}
+@media print{body{background:#fff}main{max-width:none;padding:0}h2{break-after:avoid}table{break-inside:auto}tr{break-inside:avoid}}
+`

package/src/compliance/report.ts

@@ -7,6 +7,7 @@ import { REGULATION_NAMES } from './regulations.js'
 import type { Regulation } from './regulations.js'
 import type { ComplianceReport, ControlResult, ControlStatus } from './audit.js'
 import type { ProjectScanResult, FindingKind } from './project-scan.js'
+import { suggestDomestic } from '../rules/domestic-alternatives.js'
 
 const STATUS_ICON: Record<ControlStatus, string> = {
   pass: '🟢',
@@ -157,9 +158,61 @@ export function renderProjectFindings(scan: ProjectScanResult, locale: 'zh' | 'e
     }
     L.push('')
   }
+
+  // 处方：境内合规替代建议（仅当存在境外模型风险时）
+  L.push(...renderDomesticGuidance(scan, locale))
+
   return L.join('\n')
 }
 
+/** 渲染「境内合规替代建议」—— 把数据出境风险变成可执行的迁移处方 */
+function renderDomesticGuidance(scan: ProjectScanResult, locale: 'zh' | 'en'): string[] {
+  const zh = locale === 'zh'
+  const overseas = scan.findings.filter(f => f.kind === 'overseas')
+  if (overseas.length === 0) return []
+
+  // 去重境外厂商
+  const seen = new Set<string>()
+  const providers: { key: string; zh?: string; en?: string }[] = []
+  for (const f of overseas) {
+    const key = (f.endpointId || f.provider_en || f.provider_zh || '').toLowerCase()
+    if (!key || seen.has(key)) continue
+    seen.add(key)
+    providers.push({ key: f.endpointId || f.provider_en || '', zh: f.provider_zh, en: f.provider_en })
+  }
+
+  const L: string[] = []
+  L.push(zh ? '## ✅ 境内合规替代建议' : '## ✅ Domestic Compliance Alternatives')
+  L.push('')
+  L.push(zh
+    ? '把数据出境风险变成可执行的迁移路径。境内主流模型多为 **OpenAI 兼容**接口：'
+    : 'Turn data-export risk into a concrete migration path. Most domestic models are **OpenAI-compatible**:')
+  L.push('')
+
+  // 每个境外厂商的迁移难度
+  for (const p of providers) {
+    const s = suggestDomestic(p.key, p.zh, p.en)
+    L.push(zh
+      ? `- **${s.overseas_zh}** → 迁移难度: ${s.difficulty_zh}`
+      : `- **${s.overseas_en}** → migration: ${s.difficulty_en}`)
+  }
+  L.push('')
+
+  // 共享的境内候选表（取第一个建议的 alternatives，避免重复）
+  const alts = suggestDomestic(providers[0].key, providers[0].zh, providers[0].en).alternatives
+  L.push(zh ? '| 境内模型 | 厂商 | OpenAI 兼容 base_url |' : '| Domestic model | Vendor | OpenAI-compatible base_url |')
+  L.push('|---|---|---|')
+  for (const m of alts) {
+    L.push(`| ${zh ? m.name_zh : m.name_en} | ${m.vendor_zh} | \`${m.baseUrl}\` |`)
+  }
+  L.push('')
+  L.push(zh
+    ? '> 对使用 `openai` SDK 的项目：通常仅需把 `base_url` 与 `api_key` 换成上表任一境内模型即可，业务代码无需改动。迁移前请以各厂商官方文档为准。'
+    : '> For projects using the `openai` SDK: usually just swap `base_url` + `api_key` to a domestic model above — no business-code change. Verify against each vendor’s official docs first.')
+  L.push('')
+  return L
+}
+
 function scoreBar(score: number): string {
   const filled = Math.round(score / 5)
   return '█'.repeat(filled) + '░'.repeat(20 - filled)

package/src/rules/domestic-alternatives.ts

@@ -0,0 +1,90 @@
+// src/rules/domestic-alternatives.ts — 境内已备案大模型替代建议
+//
+// 扫到境外大模型（端点/SDK 依赖）后，给出可执行的「境内合规替代」处方：
+// 把"你有数据出境风险"变成"换成这个、这样换"。这是 ShellWard 面向中国
+// 市场最具差异化、最可执行的一环 —— 英文工具不会做。
+//
+// 杀手锏：境内主流模型多数提供 **OpenAI 兼容接口**，对 `openai` SDK 的项目
+// 往往只需改 base_url + api key、代码零改动即可迁移到合规模型。
+//
+// 注：base_url 为各厂商公开的 OpenAI 兼容端点（可能随官方调整，迁移前以官方文档为准）。
+
+export interface DomesticModel {
+  id: string
+  name_zh: string
+  name_en: string
+  vendor_zh: string
+  /** OpenAI 兼容 base_url（若支持） */
+  baseUrl: string
+  /** 是否提供 OpenAI 兼容接口（决定迁移难度） */
+  openaiCompatible: boolean
+}
+
+/** 境内主流大模型（均为境内可备案/合规部署，按知名度排序） */
+export const DOMESTIC_MODELS: DomesticModel[] = [
+  {
+    id: 'qwen', name_zh: '通义千问', name_en: 'Qwen', vendor_zh: '阿里云百炼/DashScope',
+    baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1', openaiCompatible: true,
+  },
+  {
+    id: 'deepseek', name_zh: 'DeepSeek', name_en: 'DeepSeek', vendor_zh: '深度求索',
+    baseUrl: 'https://api.deepseek.com', openaiCompatible: true,
+  },
+  {
+    id: 'kimi', name_zh: 'Kimi', name_en: 'Kimi (Moonshot)', vendor_zh: '月之暗面',
+    baseUrl: 'https://api.moonshot.cn/v1', openaiCompatible: true,
+  },
+  {
+    id: 'glm', name_zh: '智谱 GLM', name_en: 'Zhipu GLM', vendor_zh: '智谱 AI',
+    baseUrl: 'https://open.bigmodel.cn/api/paas/v4', openaiCompatible: true,
+  },
+  {
+    id: 'doubao', name_zh: '豆包', name_en: 'Doubao', vendor_zh: '字节火山方舟',
+    baseUrl: 'https://ark.cn-beijing.volces.com/api/v3', openaiCompatible: true,
+  },
+  {
+    id: 'ernie', name_zh: '文心一言', name_en: 'ERNIE', vendor_zh: '百度千帆',
+    baseUrl: 'https://qianfan.baidubce.com/v2', openaiCompatible: true,
+  },
+]
+
+export interface DomesticSuggestion {
+  /** 触发的境外厂商（中文） */
+  overseas_zh: string
+  overseas_en: string
+  /** 迁移难度 */
+  difficulty_zh: string
+  difficulty_en: string
+  /** 推荐的境内替代（取兼容优先的前几个） */
+  alternatives: DomesticModel[]
+}
+
+// 哪些境外厂商走 OpenAI 兼容协议（其 SDK 项目可零代码迁移到境内兼容端点）
+const OPENAI_PROTOCOL = new Set(['openai', 'azure-openai', 'groq', 'together', 'mistral', 'perplexity', 'openrouter', 'xai'])
+
+/**
+ * 针对某个境外厂商给出境内替代建议。
+ * @param key endpointId（如 'openai'）或 provider_en（如 'OpenAI'）
+ */
+export function suggestDomestic(key: string, provider_zh?: string, provider_en?: string): DomesticSuggestion {
+  const k = key.toLowerCase()
+  const isOpenAiProtocol = OPENAI_PROTOCOL.has(k) || /openai/.test(k)
+
+  // 推荐：OpenAI 兼容的境内模型优先（迁移最省事）
+  const alternatives = DOMESTIC_MODELS.filter(m => m.openaiCompatible).slice(0, 4)
+
+  const difficulty_zh = isOpenAiProtocol
+    ? '低 — 多为 OpenAI 兼容协议，通常只需改 base_url + API key，代码零改动'
+    : '中 — SDK 不同，建议改用境内模型的 OpenAI 兼容端点并调整调用代码'
+  const difficulty_en = isOpenAiProtocol
+    ? 'Low — OpenAI-compatible; usually just swap base_url + API key, no code change'
+    : 'Medium — different SDK; switch to a domestic OpenAI-compatible endpoint and adjust calls'
+
+  return {
+    overseas_zh: provider_zh || key,
+    overseas_en: provider_en || key,
+    difficulty_zh,
+    difficulty_en,
+    alternatives,
+  }
+}