# 第 9/10 步详细设计：KBaaS / 连接器市场 / 合规门户 / L1 有码沙箱

> 依据：docs/ecosystem-design-v1.2.md 第 9/10 步。本文为设计交付（📐），不含实现；
> 实现顺序仍受 v1.2 §一落地顺序约束（第 9 步依赖第 7 步市场 beta 运行数据，第 10 步按触发条件立项）。
>
> **优先级调整（v1.3 评审后）**：商业化相关能力（市场变现、订阅代收自动化、真实支付/资金通道、
> KBaaS 商业交付）**放缓实施**；资源优先投入企业内 AI 资产治理与运营（资产台账/健康巡检/成本报表，
> 已在 v1.3 交付）。本文设计保留作为后续参考。

---

## 第 9 步之一：知识库即服务（KBaaS）

### 定位
解决「每个企业客户都要一遍数据进入」：平台统一承接文档入库、切分、索引、检索，只以
`knowledgebase.read` 能力 + org 租户隔离对外；私有知识库走 `plugin:<id>:kb` 前缀复用同一管道。

### 架构（复用既有底座，最小新增）
```
企业文档 → kb.ingest（上传/分块/向量化登记）→ kb 集合（JSON：文档元数据）
                                        → 向量索引（SQLite FTS5 起步 / pgvector 升级位）
检索请求（Agent/App/L0 插件经能力授权）→ kb.search（混合检索：FTS 关键词 + 向量相似）
                                        → usage.record（resource: kb:<orgId>，meters: [{key:'kb.queries', unit:'次'}]）
```
- 权限：`knowledgebase.read` 能力 + org 归属双校验（跨 org 不可见，跨租户硬隔离）；
- RAG 质量红线（v1.1 §三.1 继承）：检索结果必须带引用定位（docId + 段落偏移），无引用不返回；
- 计费：价格簿 `kb:*` 按次计价；私有插件知识库按 `plugin:<id>:kb` 单独计价。

### 交付拆分
1. kb.ingest + 分块（按标题/段落，512 token 窗口）+ FTS5 索引；
2. kb.search（BM25 起步，向量位预留 `embedding` 列）+ 引用返回 + 能力校验；
3. 计量接入 + 私有前缀路由。

---

## 第 9 步之二：连接器市场（企业系统 MCP 化）

### 定位
把 ERP/CRM/工单/数据库等企业系统以 MCP 服务形式统一接入（复用第 0 步已真实化的 MCP 传输层），
第三方也可发布「连接器型 L0 插件」（声明式：只含连接配置模板 + 工具描述，无代码）。

### 关键设计
- 连接器 = MCP 服务（`exec: 'real'`，endpoint 指向厂商侧或平台托管网关）+ 权限组模板（安装即带
  预设 readOnly 策略，企业安装时二次确认）；
- 凭证托管：企业系统凭证存平台密钥库（data 目录加密文件起步，KMS 升级位），连接器只见引用；
- 健康与 SLO：复用第 0 步真实探活（熔断/灰度已有）；
- 商业形态：平台自营连接器（订阅制）+ 第三方连接器（L3 分成，复用市场流水线与分账 ledger）。

---

## 第 9 步之三：安全合规门户

### 定位（v1.1 §六继承 + 补强）
平台统一承接企业客户安全诉求，第三方插件不重复应付企业安全问卷。

### 模块
1. **数据安全门户**：内容审计（复用四类审计日志 + L0 内容扫描规则企业可配置）、
   敏感信息出口策略（脱敏模板作为自营 L0 插件首发）；
2. **数据分级**：permissions.yaml 声明 `data: pii-read` → 安装时企业分级审批
   （市场 install 已实现 approved ⊆ requested，扩展 data 类能力枚举）；
3. **审计继承**：第三方插件审计自动进入企业租户视图（按 tenant_id 过滤已有）；
4. **合规文档中心**：安全白皮书、DPA、渗透测试报告、数据处理登记——静态内容 + 版本管理；
5. **上架安全门现状声明**（评审轻微问题 1 修正）：当前 = L0 门禁 + 静态扫描 + 运行时对账；
   L1 沙箱（第 10 步）交付后升级为「L0/L1 双轨 + 出网白名单」。

---

## 第 10 步：L1 有码 JS 沙箱（自研模块加载器）

### 立项触发条件（M3 消解，非收入单一信号）
满足任一即立项：
- 平台自营 L0 插件付费转化 ≥ 3 单；
- 开发者 waitlist ≥ 20；
- 企业客户询盘（需有码能力）≥ 5。

### 技术路线（评审②的「需自研模块加载器」判断落地）
cordis 为单进程插件框架，无插件级沙箱语义；L1 需要**模块加载器级隔离**：

1. **加载器**：`vm.SourceTextModule`（`--experimental-vm-modules`）或 worker 隔离运行第三方代码；
   插件代码以 ESM 源码提交，平台编译为模块图后注入**代理 ctx**（第 3 步已交付的事件源鉴别 + 能力裁剪层）；
2. **模块白名单**：`import` 只允许解析到平台暴露的受控模块表（@dsh-ops/contract），未列入模块解析即失败；
   `require/fs/net/process/child_process` 不可达（模块图内不存在即不可 import）；
3. **运行时防线叠加**：静态扫描（提交时）→ 代理 ctx（加载期）→ 运行时对账（持续，usage 能力漂移已上线）
   → 出网白名单（网络层，默认 deny，安装时逐域名审批）；
4. **资源限额**：CPU（时间片预算）、内存（堆上限）、事件发射速率（令牌桶），
   超限 suspend + 告警（复用审批中心的 suspend 流转）；
5. **存储**：`plugin:<id>:` 前缀集合强制（已有 uniqueOn 前缀校验位），跨插件集合不可寻址；
6. **升级策略**：与 vendored fork（@deepseek-ai/cordis，固定 4.0.0-rc.7 快照）解耦——
   沙箱不依赖框架内部 API，fork 升级不影响沙箱层。

### 交付验收（硬性）
- 逃逸测试集：动态 import / eval / 原型链逃逸 / 全局对象篡改 / 超时死循环 / 事件风暴，全部被拦；
- 性能：单插件冷启动 < 500ms，代理层开销 < 10%；
- 契约验证：`dshctl plugin init --sandbox=L1` 生成的有码 Hello World 在沙箱内跑通并计量；
- 市场门禁切换：L1 交付验收全绿后，市场准入门禁从「仅 L0」放开为「L0 + L1」
  （门禁代码点：plugin-market `parseManifest` 的 sandbox 校验分支）。

---

## 与既有实现的衔接点（代码级）

| 衔接点 | 位置 | 状态 |
|---|---|---|
| MCP 真实传输（连接器市场执行层） | plugin-mcp `realTransport`/`realProbe` | ✅ 已交付（第 0 步） |
| 能力审批（数据分级安装确认） | plugin-market `install(approvedCapabilities)` | ✅ 已交付（第 3 步） |
| 运行时对账（L1 第 3 层防线） | plugin-usage `capabilityDrift` | ✅ 已交付（第 2 步） |
| 代理 ctx（L1 第 2 层防线） | platform-core `plugin-ctx.ts` | ✅ 已交付（第 3 步） |
| 分账（连接器 L3 分成） | plugin-billing `settle`/`reverse` | ✅ 已交付（第 8 步） |
| L0 门禁切换点 | plugin-market `parseManifest` sandbox 分支 | ✅ 已硬编码 L0-only，待 L1 验收后放开 |