✨ 安全重构 ScriptCat MCP 桥接：分级授权、人工确认与商店构建隔离

.github/workflows/test.yaml

@@ -18,6 +18,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Setup pnpm
         env:
@@ -68,6 +69,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Setup pnpm
         env:
@@ -95,11 +97,8 @@ jobs:
 
       - name: Run test shard
         run: >
-          pnpm exec vitest run
-          --coverage
-          --silent
-          --reporter=blob
-          --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+          pnpm exec vitest run --coverage --silent --reporter=blob --shard=${{ matrix.shardIndex }}/${{
+          matrix.shardTotal }}
 
       - name: Upload blob report
         if: ${{ !cancelled() }}
@@ -121,6 +120,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Setup pnpm
         env:
@@ -155,11 +155,7 @@ jobs:
 
       - name: Merge test and coverage reports
         run: >
-          pnpm exec vitest
-          --merge-reports
-          --coverage
-          --reporter=default
-          --reporter.default.summary=false
+          pnpm exec vitest --merge-reports --coverage --reporter=default --reporter.default.summary=false
 
       - name: Verify prerequisite jobs
         if: ${{ always() && (needs.lint.result != 'success' || needs.test-shards.result != 'success') }}
@@ -168,6 +164,72 @@ jobs:
       - name: Upload coverage reports to Codecov with GitHub Action
         uses: codecov/codecov-action@v5
 
+  native-host:
+    runs-on: ${{ matrix.os }}
+    name: Native host (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v5
+
+      - name: Use Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 20
+          cache: "pnpm"
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Setup pnpm
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm --filter @scriptcat/native-messaging-host build
+
+      - name: Test
+        run: pnpm --filter @scriptcat/native-messaging-host test
+
+  pack-profiles:
+    runs-on: ubuntu-latest
+    name: Pack profile assertions
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v5
+
+      - name: Use Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: "pnpm"
+
+      - name: Setup pnpm
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      # A throwaway signing key — CI verifies build-output compliance, it never publishes this
+      # artifact, so a real signing key (secrets.CHROME_PEM, used only by packageRelease.yml) is
+      # neither needed nor available on pull_request runs.
+      - name: Generate throwaway signing key
+        run: |
+          mkdir -p dist
+          openssl genrsa -out ./dist/scriptcat.pem 2048
+
+      - name: store-stable must not contain nativeMessaging or MCP UI strings
+        run: SC_PACK_PROFILE=store-stable pnpm run pack
+
+      - name: store-beta must not contain nativeMessaging or MCP UI strings
+        run: rm -rf dist/ext && SC_PACK_PROFILE=store-beta pnpm run pack
+
+      - name: developer profile must contain nativeMessaging when SC_ENABLE_MCP=true
+        run: rm -rf dist/ext && SC_PACK_PROFILE=developer SC_ENABLE_MCP=true pnpm run pack
+
   e2e:
     runs-on: ubuntu-latest
     name: Run E2E tests (${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
@@ -182,6 +244,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Setup pnpm
         env:

docs/DOC-MAINTENANCE.md

@@ -31,6 +31,9 @@ Aspirational / feature-branch content belongs in that branch's docs, or is clear
 | [`verification.md`](./verification.md) | Lightweight end-to-end functional verification — throwaway scratch scripts driving the real built extension; report template split to [`references/verification-report-template.md`](./references/verification-report-template.md), debugging FAQ to [`references/verification-debugging.md`](./references/verification-debugging.md). |
 | [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md). |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
+| [`store-review/mcp.md`](./store-review/mcp.md) | MCP bridge store-review package (data flow, tool privilege table, consent surfaces, kill-switch); protocol/threat-model detail lives in `packages/native-messaging-host/PROTOCOL.md`/`THREAT-MODEL.md` — link, don't duplicate. |
+| [`mcp-bridge-guide.md`](./mcp-bridge-guide.md) | End-user how-to for the MCP bridge: build/install/pair steps, tool table, worked examples. Security rationale lives in the threat model/store-review docs above — link, don't duplicate. `mcp-bridge-guide_zh-CN.md` is its zh-CN translation — keep in sync via [`translation.md`](./translation.md), don't fork content. |
+| [`../packages/native-messaging-host/README.md`](../packages/native-messaging-host/README.md) | The `native-messaging-host` package's own developer README: CLI reference, package layout, build/test commands. `README_zh-CN.md` is its zh-CN translation. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules + fact-check / anti-drift discipline. |
 | [`README.md`](./README.md) | The index that points to all of the above. |
 

docs/README.md

@@ -13,6 +13,18 @@
 | [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)。 |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、一键校验脚本。**改/审文档前先读。** |
 
+## MCP 桥接 / MCP Bridge
+
+仅存在于 developer 构建产物(`SC_ENABLE_MCP=true`),不进入 store-stable/store-beta。
+
+| 文档 | 说明 |
+| --- | --- |
+| [`mcp-bridge-guide.md`](./mcp-bridge-guide.md) | 使用指南:构建/安装/配对/授权的实操步骤,附工具清单与真实用例(读取源码、请求安装、启停、删除脚本、撤销客户端)。**想实际用起来先读这份。**中文版见 [`mcp-bridge-guide_zh-CN.md`](./mcp-bridge-guide_zh-CN.md)。 |
+| [`../packages/native-messaging-host/README.md`](../packages/native-messaging-host/README.md) | `native-messaging-host` 包的开发者文档:CLI 参考、目录结构、构建/测试命令。中文版见 [`README_zh-CN.md`](../packages/native-messaging-host/README_zh-CN.md)。 |
+| [`../packages/native-messaging-host/PROTOCOL.md`](../packages/native-messaging-host/PROTOCOL.md) | 协议规范:浏览器↔主机 native messaging、shim↔主机本地 socket、面向 agent 的 MCP 工具/资源目录三层协议。 |
+| [`../packages/native-messaging-host/THREAT-MODEL.md`](../packages/native-messaging-host/THREAT-MODEL.md) | 威胁模型:资产、攻击者与入口点、鉴权鉴权、写路径 TOCTOU 不变量、限流、审计模型。 |
+| [`store-review/mcp.md`](./store-review/mcp.md) | 应用商店审核材料汇编:数据流、工具权限表、同意界面、令牌存储与吊销、审计日志、隐私披露。 |
+
 ## 翻译 / Translation
 
 | 文档 | 说明 |

docs/develop.md

@@ -32,6 +32,29 @@ pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for stag
 
 After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension.
 
+### Build profiles & MCP gate
+
+The MCP bridge (`src/app/service/service_worker/mcp/`, `packages/native-messaging-host/`) is gated
+by a build-time flag on top of the usual dev/prod split, because `nativeMessaging` must never reach
+a store-submitted artifact:
+
+```bash
+SC_ENABLE_MCP=true pnpm dev           # dev build with the MCP bridge compiled in
+pnpm run pack:dev                     # developer-profile package with MCP enabled (SC_PACK_PROFILE=developer)
+```
+
+`SC_ENABLE_MCP` (default off) is the build-time gate — when off, `rspack.config.ts` swaps
+`McpSection.tsx` for a stub via `NormalModuleReplacementPlugin` and omits the `mcp_confirm` entry
+entirely, so the code never lands in the bundle at all (not just dead-code-eliminated). At runtime
+there is a second, independent gate: `mcp_enabled` (`SystemConfig`, device-local, off by default) —
+the bridge only connects to the native host once both gates are on. `scripts/pack.js`'s
+`--profile <store-stable|store-beta|developer>` flag (env `SC_PACK_PROFILE`) asserts store profiles
+never contain `nativeMessaging` or MCP UI strings in the built output, failing the build if they do.
+See [`docs/store-review/mcp.md`](./store-review/mcp.md) for the full store-review rationale and
+[`packages/native-messaging-host/PROTOCOL.md`](../packages/native-messaging-host/PROTOCOL.md) /
+[`THREAT-MODEL.md`](../packages/native-messaging-host/THREAT-MODEL.md) for the protocol and security
+design.
+
 ## Project Structure & Module Organization
 
 Core entry points live in `src` (`service_worker.ts`, `content.ts`, `inject.ts`, `offscreen.ts`, `sandbox.ts`). UI pages are in `src/pages`, with shared UI in `src/pages/components` and state in `src/pages/store`. Reusable domain code is in `src/pkg`; app services are in `src/app`; templates are in `src/template`; assets and translations are in `src/assets` and `src/locales`. Workspace packages live in `packages`, including browser mocks and filesystem adapters. Unit tests are colocated as `*.test.ts`/`*.test.tsx` or placed in `tests`; E2E specs are in `e2e`.