@xiaobanli/dsh-enterprise-compliance

Readme

# @xiaobanli/dsh-enterprise-compliance

企业级一体化合规插件（DeepSeek Harness / DSH）。六大能力 + 三大快赢增强：

1. **SOC2 / GDPR 自动化合规自检** — `compliance_report` 模型工具：读取真实运行时事实，按
   CC6.1 / CC6.2 / CC7.2 / CC6.6 / A1.2 与 GDPR Art.5 / Art.25 逐项 PASS / WARN / FAIL 并打分；
   支持 `summary / json / markdown` 三格式导出，并记录**评分历史趋势**。
2. **敏感信息拦截与脱敏** — `compliance_redact` 模型工具 + 9 类正则规则（邮箱、手机号、身份证、
   银行卡、API Key、JWT、Bearer、私钥、IP）；已挂载到 `session-telemetry/record` 瀑布流，
   遥测导出前自动脱敏（GDPR 数据最小化）。
3. **操作审计追溯 + 持久化导出** — `compliance_audit` 模型工具：监听 `tools/result`，记录每次
   工具调用的时间、工具名、成功 / 失败、会话 ID、**脱敏后的参数**；审计**持久化到 settings.yaml**，
   重启不丢证据，支持 `text / json / csv` 导出与按工具 / 会话 / 时间过滤。
4. **敏感数据文件扫描** — `compliance_scan` 模型工具：扫描工作区文件 / 目录中的明文敏感信息，
   返回逐文件命中统计与脱敏样例（默认限工作区，可 `allowOutside`）；默认**遵守 `.gitignore`**
   并跳过 `.git` / `node_modules`（可 `respectGitignore: false` 关闭）。
5. **GDPR 数据主体权利** — `compliance_data_export`（Art.20 导出采集的数据）/ `compliance_data_erase`
   （Art.17 一键擦除审计 / 历史 / 报警状态，需 `confirm: true`）。
6. **阈值报警 + 可配置策略** — 评分跌破 `alertThreshold` 时发出 `enterprise-compliance/alert` 事件并
   在页面显示告警横幅；检查项开关、脱敏规则开关、报警阈值、审计持久化条数均可在 设置 里调整。
7. **策略读写工具（快赢）** — `compliance_policy` 模型工具：读取 / 修改报警阈值、审计持久化条数、
   检查项开关、脱敏规则开关、告警 Webhook，修改即持久化。
8. **告警 Webhook 投递（快赢）** — 策略配置 `alertWebhook` 后，评分跌破阈值触发 / 恢复时 POST JSON
   到指定 URL（5s 超时，失败静默不影响主流程）。
9. **卡片策略开关（快赢）** — 「企业合规中心」页内直接点击开关切换检查项，写入策略并持久化。

另附浏览器「企业合规中心」独立页面（设置 → 左侧导航，`settings.section`），订阅 Host 发布的合规状态，展示评分、检查项、最近审计、评分趋势、告警横幅与策略开关。

## 目录结构

```
enterprise-compliance/
├── package.json        # npm 清单：dsh.bundle.patch / dsh.client / exports / peers
├── cordis.patch.yml    # bundle 补丁：把本插件插入 profile 的组合层
├── src/
│   ├── redact.js       # 脱敏引擎（纯函数、零依赖、可独立测试）
│   ├── gitignore.js    # .gitignore 匹配器（扫描用，极简子集）
│   ├── index.js        # Host 插件（真实 Host API：tools.register / ctx.on / settings）
│   └── client.js       # Client 插件（__ModuleLoader__.load 包装，settings 侧边栏页）
├── lib/                # 提交的 Host 构建产物（git 安装无需 prepare）
├── client/client.js    # 提交的 Client 构建产物
├── scripts/build.mjs   # 同步 src → lib/client
├── test/               # node --test 单元测试
├── snapshot/           # 早期动态插件版本（compl-1/pkg-1）的源码快照，仅存档
├── README.md / LICENSE / .gitignore
```

## 安装

**本地 / git 安装**（`dsh plugin` 或插件市场，profile 根目录下有 `package.json` 与 `pnpm-workspace.yaml`）：

```bash
dsh plugin --profile desktop add github:<owner>/<repository>
# 或本地路径：
dsh plugin --profile desktop add file:./enterprise-compliance
```

安装后本包被加入 profile 的 `dsh.profile.bundles`，`cordis.patch.yml` 在下次启动自动应用。

本插件**只依赖 DSH 官方契约**（无 Desktop 专属服务），web 与 desktop profile 均可安装：

```bash
dsh plugin --profile web add file:./enterprise-compliance      # web 版
dsh plugin --profile desktop add file:./enterprise-compliance  # desktop 版
```

> **已知坑（compact-after-task）**：`dsh plugin add` 的 pnpm reconcile 会把 profile 里原本按
> 「patch insert」挂载的第三方插件一并挪进 `dsh.profile.bundles`，从而改变其 client 模块 id 的
> 期望（= 包名）。第三方 client 若未按包名注册 `__ModuleLoader__.load({ id })` 就会启动报错
> `loaded without registering "…"`。恢复方法：把该插件放回 profile 的 `cordis.patch.yml`
> insert，并从 `dsh.profile.bundles` 移除（本插件自身已按包名注册，无此问题）。

**npm 安装**：`dsh plugin add @xiaobanli/dsh-enterprise-compliance`。

## 发布到 GitHub / npm

```bash
# 1. 填入仓库地址后提交并推送
git init
git add .
git commit -m "feat: enterprise compliance plugin"
git remote add origin git@github.com:<owner>/<repository>.git
git push -u origin main
gh repo edit <owner>/<repository> --add-topic dsh-plugin

# 2. 发布到 npm
npm publish

# 3. （可选）提交到社区目录：见 submit-dsh-plugin 流程
#    https://github.com/imsai-sh/awesome-deepseek-harness-plugins
```

> 本包已发布到 npm `@xiaobanli` scope（`@xiaobanli/dsh-enterprise-compliance`）。发布前把
> `package.json` 的 `repository.url` 从占位符改成真实地址；若换 scope，改 `name` 为
> `@<scope>/dsh-enterprise-compliance` 并同步 `cordis.patch.yml` 的 `name` 与 client 模块 id
> （`__ModuleLoader__.load({ id })`，id 必须等于包名）。

## 测试

三个测试套件，共 43 项，全部不依赖浏览器 / 真实 DSH 进程即可运行：

```bash
node test/redact.test.mjs       # 14 项：9 类脱敏规则 + 递归/深度 + 规则开关
node test/host.smoke.test.mjs   # 25 项：真实加载 lib/index.js，mock ctx 驱动 apply()
node test/client.smoke.test.mjs # 4 项：真实加载 client/client.js，校验工厂与渲染
npm test                        # 或 node --test test/（等价，node --test 会按文件分进程）
npm run build                   # 把 src/ 同步到 lib/ 与 client/
npm run check                   # build + test
```

**Host 冒烟测试覆盖**（直接执行插件代码，非仅语法检查）：
- 模块契约 `{ name, inject, apply }` 与 **7 个工具**注册（`ctx.tools.register(defineTool(...))`）；
- `compliance_report` 评分场景：全部服务挂载 → 100/100，危险沙箱 + 无审批 → 71/100（warn/fail 降级）；
  `json` / `markdown` 导出与历史趋势、同分 60s 去重；
- 策略可配置：关闭某检查项后 total 减少且该项不再出现；
- 阈值报警：跌破阈值触发 `enterprise-compliance/alert` 事件 + `lastAlert` 写入，恢复后清零；
- 告警 Webhook：配置 URL 后触发 / 恢复各 POST JSON 一次，未配置时静默跳过；
- `compliance_policy`：只读返回策略、修改阈值 / 检查项 / 规则并持久化到 settings、修改后 report 按新策略打分；
- `compliance_redact` 掩码与命中统计、`rules` 参数局部启用；`compliance_audit` 初始空 / 入账 /
  `json` / `csv` 导出与 tool / session / since 过滤；
- 重启回载：settings 持久化的审计 / 历史 / 策略在 apply 时恢复；
- `compliance_data_export` 导出采集数据、`compliance_data_erase` confirm 必填 + 确认后清空；
- `compliance_scan` 真实文件扫描发现敏感信息（含脱敏样例）、默认拒绝工作区外路径、
  遵守 `.gitignore`（忽略文件 / 目录不报告）、`respectGitignore=false` 关闭忽略；
- `tools/result` 成功 / 失败事件入账、`session-telemetry/record` 脱敏接线（数据最小化）；
- `settings` 桥：命名空间注册、初始状态发布、5s 刷新定时器、节流与「无变化不重复写盘」；
- 缺全部服务时的健壮性（apply 不抛错、工具仍可用）。

**Client 冒烟测试覆盖**：`__ModuleLoader__.load({ id, factory })` 契约（**id = 包名**）、工厂返回
`{ name, inject: ['slots','locale','settingsScope'], apply }`、apply 接线（locale 注册 /
settingsScope 绑定 / `settings.section` 侧边栏页注册）、页面用真实 `React.createElement`
渲染出评分、检查项、审计行。

**Host 测试的 Guard 语义**：mock ctx 带 Cordis Guard（未在 `inject` 声明的 ctx 属性访问即抛错），
从模块导出的 `inject` 自动同步——若 apply 用了未声明的服务，测试当场红。历史上两处真实环境
Guard 翻车（`inject=[]` 却访问 `ctx.tools`、settings 未挂载即注册）都由这种盲区漏掉，现已堵上。

> **依赖说明**：仓库内 `node_modules/` 已 gitignore。沙箱本地测试时复制了 DSH 自带
> `@deepseek-ai/*`、`react` 等包以便运行上述冒烟测试；真实环境安装后由 DSH / npm 解析，
> 无需提交这些依赖。

> **schemastery API 注意**：本机 DSH 内置的 `@deepseek-ai/schemastery@3.18.1` **没有
> `.optional()`**（与 zod 不同），可选字段用 `.default(...)` 表达（`dsh-compact-after-task`
> 等内置插件同款写法）。`StatusSchema` 已按此适配。

## 架构说明

- **Host（src/index.js）**：ESM 导出 `{ name, apply(ctx) }`，用真实 Host 服务注册 7 个模型工具
  （`ctx.tools.register(defineTool(...))`：`compliance_report` / `compliance_redact` /
  `compliance_audit` / `compliance_scan` / `compliance_data_export` / `compliance_data_erase` /
  `compliance_policy`），
  监听 `tools/result` 采集审计、`session-telemetry/record` 做导出脱敏，`ctx.settings.register`
  维护合规状态命名空间（含策略 / 持久化审计 / 历史 / 报警）供 Client 读取并落盘 settings.yaml。
  告警 Webhook 用 `node:http` / `node:https` 投递（策略 `alertWebhook` 可配置）。
- **Client（src/client.js）**：`settings.section` 侧边栏注册「企业合规中心」独立页面，订阅
  `enterprise-compliance` settings 命名空间；含 zh/en 双语词典。Host 端 `inject: ['tools','settings']`
  （settings 为硬依赖，保证命名空间注册时服务已挂载），Client 端 `inject: ['slots','locale','settingsScope']`。
- **副作用均 Fiber 所有**：`ctx.on` / `ctx.tools.register` / `ctx.settings.register` /
  `ctx.effect` / `slots.inject` / `locale.register`，插件卸载时自动清理。

## 已知限制

- 审计**持久化不含参数**（`args` 仅在内存环中存在，落盘的是时间 / 工具 / 结果 / 会话 / 错误，重启后参数不再可查）。
- 持久化条数默认 100（`policy.auditPersist` 可调），内存环上限 500。
- `compliance_scan` 跳过二进制文件与超过 1MB 的文本文件。
- `compliance_data_erase` 仅擦除**本插件自身**采集的数据（审计 / 历史 / 报警状态），不涉及 DSH 其他数据。
- 部分检查项结果取决于运行时服务是否挂载（审批 / 凭证 / 持久化 / 遥测）。
- 合规中心页面依赖 `settings` 服务存在；缺失时仅影响页面展示，不影响模型工具。

## 与早期动态插件版本的关系

`snapshot/` 保存了最初作为动态 Cordis 插件（`compl-1/pkg-1`，动态 `harness.*` API）运行的源码，
仅供存档对照。本工程已把逻辑改写为**可安装插件的真实 Host / Client API**。