shellward 0.6.2 → 0.6.3

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-242%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 [English](#demo) | [中文](#中文)
@@ -36,7 +36,7 @@ Outputs a red/yellow/green scorecard mapped to 网安法 / PIPL / 等保2.0 /
 
 `npx shellward scan --json` for CI · `--ci` to fail the build on critical findings · 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/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.3",
   "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/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,
+  }
+}