@deepwhale-cn/dsh-compliance-doc 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深鲸 DeepWhale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @deepwhale-cn/dsh-compliance-doc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/zh/plugins/feely0208/dsh-compliance-doc)
+
+**检查结果别只躺在终端里 —— 自查表、整改说明、带边界声明的合规证明，一次生成三份能直接交出去的文档。**
+
+**关键词**：合规报告 · 自查表 · 整改说明 · 合规证明 · 等保三级 · 安全自查 · 整改复核 · 一键体检 · 交付文档 · 审计留痕
+
+---
+
+## 先说清楚它是什么、不是什么
+
+**不装的代价**：扫描结果只在终端滚一遍屏，领导要「自查表」、客户要「整改说明」、
+测评机构要「检查记录」，你还得手工从日志里一条条复制进 Excel —— 慢、容易漏、
+格式还不统一；更麻烦的是，手写文档很容易顺手写一句「已合规」，把提示项说成结论。
+
+**是**：把一份本地静态检查报告，整理成三份**可以直接交付**的文件：
+
+| 文件 | 内容 | 谁看 |
+|---|---|---|
+| `自查表.csv` | 序号 / 检查项 / 严重度 / 依据 / 位置 / 状态 / 建议，UTF-8 BOM，Excel 双击就能开 | 执行整改的人 |
+| `整改说明.md` | 背景、检查范围与方法、逐条问题 + 整改建议、复核方式 | 领导 / 客户 / 项目经理 |
+| `合规证明.md` | 检查范围、规则条数、依据清单（去重）、结论措辞 | 对外提交 / 归档 |
+
+**不是**：
+- ❌ **不是合规认证** —— 静态检查证明不了合规，它只如实记录「规则库这一次查到了什么」
+- ❌ **不是等保测评 / 监管检查 / 第三方审计的替代品** —— 那需要测评机构按标准现场核查
+- ❌ **不产生新判据** —— 规则来自你已安装的深鲸守护插件，它只做整理和成文
+- ❌ **不写「已合规」「保证通过」** —— 三份文件都带同一条声明，结论措辞按「提示项」而非「违规」表述
+
+**一句话分界**：别的插件负责「查」，它负责把查出来的东西写成**能交出去、且有边界说明**的文档。
+
+```
+dsh-sbom / dsh-data-rights / ...  = 查
+dsh-fix-verify                     = 复核改前改后
+dsh-compliance-doc                 = 把上面两步的结果变成可交付文档
+```
+
+---
+
+## 用法
+
+```bash
+# 从一个普通扫描报告生成三份文档
+dsh-compliance-doc --input report.json --out ./交付文档
+
+# 带单位名、检查日期、等保三级文档档次
+dsh-compliance-doc --input report.json --out ./交付 \
+  --org "某某科技有限公司" --date 2026-10-20 --profile 等保三级
+
+# 配合 dsh-fix-verify：把改前改后复核结果整理成整改说明
+dsh-fix-verify --before old --after new --json > fix-verify.json
+dsh-compliance-doc --input fix-verify.json --out ./交付 --org "某某科技有限公司"
+```
+
+输出目录不存在会**自动创建**。
+
+### 输入兼容两种 JSON
+
+**① 普通 / suite 扫描报告**（`dsh-guard-core` 的标准输出）：
+
+```json
+{ "generatedAt": "...", "stats": { "scannedFiles": 34, "rulesRun": 12, ... }, "findings": [ ... ] }
+```
+
+**② `dsh-fix-verify` 的复核报告**：顶层有 `fixed` / `remaining` / `regressed` 数组。
+
+字段不对、JSON 坏、输入缺失 → **exit 2**，不会硬编一份「看起来正常」的文档。
+
+---
+
+## 措辞红线（三份文件都写）
+
+> 本文件由本地静态检查生成，不构成合规结论，不替代等保测评/监管检查/第三方审计。
+
+- 不出现「已合规」「保证通过」「绝对合规」这类结论；
+- 规则未命中时 `合规证明.md` 会写「本次检查覆盖 N 条规则、M 个文件，未发现提示项」，
+  同时明确提醒「**未命中不等于没有问题**」；
+- `--profile 等保三级` 只影响**文档组织方式**，不改变规则集，也不构成等保测评结论。
+
+---
+
+## 输出示例
+
+```
+  ✅ 自查表.csv        3 条检查项，Excel 可直接打开
+  ✅ 整改说明.md       背景 / 范围与方法 / 逐条问题与建议 / 复核方式
+  ✅ 合规证明.md       范围 / 规则条数 / 依据清单 / 结论措辞
+
+  扫描    34 个文件 · 运行规则 12 条
+  提示项  3 条（高 1 · 中 1 · 低 1）
+```
+
+### 退出码
+
+| 码 | 含义 |
+|---|---|
+| `0` | 三份文件正常生成 |
+| `2` | 输入缺失 / JSON 解析失败 / 字段不对 / 参数错误 |
+
+---
+
+## 不要做什么
+
+- 不要把它生成的 `合规证明.md` 当成「合规证书」对外使用 —— 它只是检查记录
+- 不要删掉文件里的免责声明 —— 那句话是这份文档能用的前提
+- 不要在输入报告为空时断定「项目没问题」—— 未命中不等于没有问题
+- 不要把它当扫描器 —— 它不跑规则，只整理报告
+- 不要用 `--profile 等保三级` 暗示已经做过等保测评 —— 那只影响文档排版
+
+## 安装
+
+```bash
+dsh plugin --profile web add @deepwhale-cn/dsh-compliance-doc
+```
+
+## License
+
+MIT © 深鲸 DeepWhale
+
+## 深鲸网安守护系列（共 39 个）
+
+> 一个插件做一件事。**安全问题是链式的** —— 配套用才完整。
+
+**国内合规**（12）｜ [等保对照](https://github.com/feely0208/dsh-cn-mlps) · [日志留存](https://github.com/feely0208/dsh-cn-log-retention) · [备案公示](https://github.com/feely0208/dsh-cn-filing) · [用户同意](https://github.com/feely0208/dsh-consent-guard) · [个人信息权利](https://github.com/feely0208/dsh-data-rights) · [未成年人保护](https://github.com/feely0208/dsh-minor-guard) · [影响评估](https://github.com/feely0208/dsh-pipia) · [数据分类分级](https://github.com/feely0208/dsh-data-classify) · [算法备案](https://github.com/feely0208/dsh-algorithm-filing) · [数据出境](https://github.com/feely0208/dsh-cn-data-export) · [国密合规](https://github.com/feely0208/dsh-cn-crypto) · [AI 内容标识](https://github.com/feely0208/dsh-cn-ai-labeling)
+
+**AI 与 Agent 治理**（6）｜ [AI 输出信任](https://github.com/feely0208/dsh-ai-output-trust) · [外部内容信任](https://github.com/feely0208/dsh-content-trust) · [MCP 安全](https://github.com/feely0208/dsh-mcp-audit) · [Agent 权限](https://github.com/feely0208/dsh-agent-scope) · [策略核对](https://github.com/feely0208/dsh-agent-policy) · [可疑指令](https://github.com/feely0208/dsh-phishing-guard)
+
+**数据与凭据**（5）｜ [敏感数据](https://github.com/feely0208/dsh-data-scan) · [密钥轮换](https://github.com/feely0208/dsh-key-rotate) · [数据留存](https://github.com/feely0208/dsh-data-lifecycle) · [配置审计](https://github.com/feely0208/dsh-env-audit) · [密钥扫描](https://github.com/feely0208/dsh-secret-scan)
+
+**供应链与构建**（5）｜ [开源许可](https://github.com/feely0208/dsh-license-guard) · [依赖投毒](https://github.com/feely0208/dsh-dep-audit) · [CI 安全](https://github.com/feely0208/dsh-ci-guard) · [工具审查](https://github.com/feely0208/dsh-tool-vet) · [物料清单](https://github.com/feely0208/dsh-sbom)
+
+**权限与应急**（3）｜ [最小权限](https://github.com/feely0208/dsh-least-privilege) · [告警外发](https://github.com/feely0208/dsh-alert-relay) · [应急证据包](https://github.com/feely0208/dsh-incident-package)
+
+**行业专项**（4）｜ [医疗行业专项](https://github.com/feely0208/dsh-industry-medical) · [教育行业专项](https://github.com/feely0208/dsh-industry-education) · [金融行业专项](https://github.com/feely0208/dsh-industry-finance) · [地方数据条例](https://github.com/feely0208/dsh-local-regulation)
+
+**编排与交付**（4）｜ [一键体检](https://github.com/feely0208/dsh-guard-suite) · [改前改后复核](https://github.com/feely0208/dsh-fix-verify) · [合规可交付文档](https://github.com/feely0208/dsh-compliance-doc) · [整改建议](https://github.com/feely0208/dsh-remediation)
+
+都在 DSH 插件市场（dsh-plugin.org）、npm 和 deepwhale.org.cn/guard.html 上。

package/bin/cli.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * dsh-compliance-doc —— 合规可交付文档
+ *
+ * 吃一份本地静态检查报告（普通扫描报告 或 dsh-fix-verify 的 JSON），
+ * 吐出三份能直接交出去的文件：
+ *   自查表.csv       Excel 直接打开（UTF-8 BOM）
+ *   整改说明.md      背景 / 范围 / 逐条问题与整改建议 / 复核方式
+ *   合规证明.md      范围 / 规则条数 / 依据清单 / 结论措辞
+ *
+ * 措辞红线：三份文件都写明「本文件由本地静态检查生成，不构成合规结论，
+ * 不替代等保测评/监管检查/第三方审计」，不写「已合规」「保证通过」。
+ *
+ * 退出码：
+ *   0  正常
+ *   2  输入缺失 / JSON 解析失败 / 字段不对 / 参数错误
+ */
+
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildDocuments, buildModel, DISCLAIMER, InputError, NO_HIT_NOTE, PROFILES, severityLabel } from '../lib/docs.mjs';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+const TOOL = 'dsh-compliance-doc';
+
+function usage() {
+  console.log(`
+  ${TOOL} v${pkg.version} · 合规可交付文档
+
+  ${pkg.description}
+
+  用法：
+    dsh-compliance-doc --input <报告.json> --out <输出目录> [选项]
+
+  选项：
+    --input <file>       输入 JSON：普通扫描报告，或 dsh-fix-verify 的 --json 输出（必填）
+    --out <dir>          输出目录（不存在会自动创建，必填）
+    --profile <档次>     文档档次：通用（默认）| 等保三级
+    --org "<公司名>"     文档里的单位 / 组织名称
+    --date <YYYY-MM-DD>  检查日期（默认今天）
+    --quiet              只输出一行结果
+    -h, --help           显示帮助
+
+  生成的三份文件：
+    自查表.csv      序号 / 检查项 / 严重度 / 依据 / 位置 / 状态 / 建议（UTF-8 BOM，Excel 可直接打开）
+    整改说明.md     背景 / 检查范围与方法 / 逐条问题与整改建议 / 复核方式
+    合规证明.md     检查范围 / 规则条数 / 依据清单（去重）/ 结论措辞
+
+  措辞边界：
+    三份文件都会写明「本文件由本地静态检查生成，不构成合规结论，
+    不替代等保测评/监管检查/第三方审计」。静态检查不是合规认证。
+
+  退出码：
+    0  正常生成
+    2  输入缺失 / JSON 解析失败 / 字段不对 / 参数错误
+`);
+}
+
+function die(msg) {
+  console.error(`\n  ❌ ${msg}\n`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const opt = { input: null, out: null, profile: '通用', org: '', date: null, quiet: false, help: false };
+  const need = (a, i) => {
+    const v = argv[i + 1];
+    if (!v || v.startsWith('--')) die(`参数 ${a} 缺少值`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--input') { opt.input = need(a, i); i++; }
+    else if (a === '--out') { opt.out = need(a, i); i++; }
+    else if (a === '--profile') { opt.profile = need(a, i); i++; }
+    else if (a === '--org') { opt.org = need(a, i); i++; }
+    else if (a === '--date') { opt.date = need(a, i); i++; }
+    else if (a === '--quiet') opt.quiet = true;
+    else if (a === '-h' || a === '--help') opt.help = true;
+    else die(`未知参数：${a}（用 --help 看用法）`);
+  }
+  return opt;
+}
+
+function todayLocal() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function validDate(s) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return false;
+  const [y, m, d] = s.split('-').map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+}
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+function main() {
+  const opt = parseArgs(process.argv.slice(2));
+  if (opt.help) { usage(); process.exit(0); }
+
+  if (!opt.input) die('缺少 --input <报告.json>');
+  if (!opt.out) die('缺少 --out <输出目录>');
+  if (!PROFILES.includes(opt.profile)) {
+    die(`--profile 只支持：${PROFILES.join(' | ')}（收到：${opt.profile}）`);
+  }
+  const date = opt.date || todayLocal();
+  if (!validDate(date)) die(`--date 不是合法日期（应为 YYYY-MM-DD）：${date}`);
+
+  const inputPath = resolve(opt.input);
+  if (!isFile(inputPath)) die(`输入文件不存在：${inputPath}`);
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(inputPath, 'utf-8'));
+  } catch (e) {
+    die(`输入 JSON 解析失败：${inputPath}\n     ${e && e.message}`);
+  }
+
+  let model;
+  try {
+    model = buildModel(raw, { org: opt.org, date, profile: opt.profile });
+  } catch (e) {
+    if (e instanceof InputError) die(`输入字段不对：${e.message}`);
+    die(`生成文档前处理输入失败：${e && e.message}`);
+  }
+
+  const outDir = resolve(opt.out);
+  try {
+    mkdirSync(outDir, { recursive: true });
+  } catch (e) {
+    die(`无法创建输出目录：${outDir}（${e && e.message}）`);
+  }
+
+  const docs = buildDocuments(model);
+  const written = [];
+  for (const [name, content] of Object.entries(docs)) {
+    const full = join(outDir, name);
+    try {
+      writeFileSync(full, content, 'utf-8');
+      written.push({ name, full });
+    } catch (e) {
+      die(`写入失败：${full}（${e && e.message}）`);
+    }
+  }
+
+  const ruleCount = model.rulesCount ?? 0;
+  const fileCount = model.scannedFiles ?? 0;
+
+  const countLabel = model.mode === 'fix-verify'
+    ? `已修复 ${model.fixedCount} / 遗留 ${model.byStatus['遗留'] || 0} / 新增回归 ${model.byStatus['新增回归'] || 0}`
+    : `提示项 ${model.total} 条`;
+  const inputLabel = model.mode === 'fix-verify'
+    ? `${model.total} 条比对记录`
+    : `${model.total} 条提示项`;
+
+  if (opt.quiet) {
+    console.log(`已生成 ${written.length} 份文件 → ${outDir}（${countLabel} / 规则 ${ruleCount} 条 / 文件 ${fileCount} 个）`);
+  } else {
+    console.log(`\n  ${TOOL} v${pkg.version} · 合规可交付文档`);
+    console.log('  ────────────────────────────────────────────────');
+    console.log(`  输入    ${inputPath}（${model.modeLabel} · ${inputLabel}）`);
+    console.log(`  输出    ${outDir}`);
+    console.log('');
+    console.log('  ✅ 自查表.csv        ' + (model.total ? `${model.total} 条检查项，Excel 可直接打开` : '0 条提示项（含说明行）'));
+    console.log('  ✅ 整改说明.md       背景 / 范围与方法 / 逐条问题与建议 / 复核方式');
+    console.log('  ✅ 合规证明.md       范围 / 规则条数 / 依据清单 / 结论措辞');
+    console.log('');
+    console.log(`  扫描    ${fileCount} 个文件 · 运行规则 ${ruleCount} 条`);
+    if (model.mode === 'fix-verify') {
+      console.log(`  复核    ${countLabel}`);
+    } else if (model.total) {
+      const sev = ['critical', 'high', 'medium', 'low']
+        .filter((s) => model.bySeverity[s])
+        .map((s) => `${severityLabel(s)} ${model.bySeverity[s]}`)
+        .join(' · ');
+      console.log(`  提示项  ${model.total} 条${sev ? `（${sev}）` : ''}`);
+    } else {
+      console.log('  提示项  0 条 —— 但未命中不等于没有问题');
+    }
+    console.log('');
+    console.log(`  > ${DISCLAIMER}`);
+    console.log(`  > ${NO_HIT_NOTE}`);
+    console.log('');
+  }
+
+  process.exit(0);
+}
+
+main();

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @deepwhale-cn/dsh-compliance-doc 的组合层
+- insert:
+    - id: compliance-doc
+      name: '@deepwhale-cn/dsh-compliance-doc'

package/lib/discover.mjs

@@ -0,0 +1,158 @@
+/**
+ * 规则源发现器 —— dsh-compliance-doc 自带一份。
+ *
+ * 为什么每个工具插件都带一份、而不是互相 import：
+ * 每个插件要能**独立安装**。用户只装了 dsh-compliance-doc 时，它得自己找到
+ * 已经装好的规则插件；不能因为「另一个工具插件没装」而直接报错。
+ *
+ * 搜索顺序（先到先得，同一目录按 realpath 去重）：
+ *   1) 显式传入的 extraDirs（--rules-from）
+ *   2) <pkgRoot>/node_modules/@deepwhale-cn/dsh-<插件名>/rules
+ *   3) <dirname(pkgRoot)>/dsh-<插件名>/rules（插件并排安装 / monorepo 开发时）
+ *   4) 环境变量 DSH_GUARD_PLUGINS（冒号分隔）
+ *
+ * 只接受「含 rules/*.json 且至少 1 条合法规则」的目录。
+ * 每条规则注入 `_plugin`（目录名去掉 dsh- 前缀），用于在报告里标明出处。
+ *
+ * 找不到规则源时，调用方必须 **报错退出**，绝不允许把「没检查」当成「0 命中」。
+ */
+
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const SCOPE = '@deepwhale-cn';
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function real(p) {
+  try { return realpathSync(p); } catch { return resolve(p); }
+}
+
+/** 目录名 dsh-sbom -> short 名 sbom */
+function shortOf(dir) {
+  const n = basename(dir);
+  return n.startsWith('dsh-') ? n.slice(4) : n;
+}
+
+/**
+ * 读一个插件根目录下的 rules/*.json。
+ * 单个文件坏掉只跳过并记 warning —— 不能让一条坏规则把整个工具搞挂，
+ * 但也不能假装它不存在：warning 会打到 stderr。
+ */
+function loadRulesFrom(root, warnings) {
+  const rdir = join(root, 'rules');
+  let files;
+  try {
+    files = readdirSync(rdir).filter((f) => f.endsWith('.json')).sort();
+  } catch {
+    return [];
+  }
+  const rules = [];
+  for (const f of files) {
+    const full = join(rdir, f);
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(full, 'utf-8'));
+    } catch (e) {
+      warnings.push(`规则文件无法解析，已跳过：${full}（${e && e.message}）`);
+      continue;
+    }
+    if (!raw || typeof raw !== 'object' || !raw.id || !raw.check) {
+      warnings.push(`规则文件缺 id/check，已跳过：${full}`);
+      continue;
+    }
+    rules.push(raw);
+  }
+  return rules;
+}
+
+function childDirs(parent) {
+  try {
+    return readdirSync(parent, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => join(parent, e.name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.pkgRoot              本插件根目录（绝对路径）
+ * @param {string[]} [o.extraDirs]        --rules-from 传入的目录（可重复）
+ * @param {NodeJS.ProcessEnv} [o.env]     用于读 DSH_GUARD_PLUGINS
+ * @returns {{sources: Array<{name:string,short:string,dir:string,rules:Array}>, warnings:string[], candidates:Array}}
+ */
+export function discoverRuleSources({ pkgRoot, extraDirs = [], env = process.env } = {}) {
+  const warnings = [];
+  const sources = [];
+  const candidates = [];
+  const seenRoots = new Set();
+  const seenCandidates = new Set();
+  const pkgReal = pkgRoot ? real(pkgRoot) : null;
+
+  function consider(pluginDir, via) {
+    if (!isDir(pluginDir)) return;
+    const rr = real(pluginDir);
+    if (pkgReal && rr === pkgReal) return; // 自己是工具插件，没有规则，也算不上来源
+    const rules = loadRulesFrom(rr, warnings);
+    if (!seenCandidates.has(rr)) {
+      seenCandidates.add(rr);
+      candidates.push({ name: basename(rr), short: shortOf(rr), dir: rr, rules: rules.length, via });
+    }
+    if (rules.length === 0) return;
+    if (seenRoots.has(rr)) return;
+    seenRoots.add(rr);
+    const short = shortOf(rr);
+    for (const r of rules) r._plugin = short;
+    sources.push({ name: basename(rr), short, dir: rr, rules });
+  }
+
+  /** extraDirs / env：可以是插件根，也可以是「装着多个插件的父目录」 */
+  function considerCandidateDir(dir, via) {
+    if (!dir) return;
+    const d = resolve(String(dir));
+    if (!isDir(d)) {
+      warnings.push(`规则源目录不存在或不是目录（已跳过）：${d}`);
+      return;
+    }
+    if (isDir(join(d, 'rules'))) {
+      consider(d, via);
+      return;
+    }
+    let hit = false;
+    for (const child of childDirs(d)) {
+      if (isDir(join(child, 'rules'))) {
+        consider(child, via);
+        hit = true;
+      }
+    }
+    if (!hit) warnings.push(`目录里没有可用规则源（未找到 dsh-*/rules）：${d}`);
+  }
+
+  // 1) 显式指定
+  for (const d of extraDirs || []) considerCandidateDir(d, 'extra');
+
+  if (pkgRoot) {
+    // 2) 当前插件自己的 node_modules（项目本地安装的守护插件）
+    const scopeDir = join(pkgRoot, 'node_modules', SCOPE);
+    for (const child of childDirs(scopeDir)) {
+      if (basename(child).startsWith('dsh-')) consider(child, 'node_modules');
+    }
+
+    // 3) 与当前插件并排安装的守护插件
+    for (const child of childDirs(dirname(pkgRoot))) {
+      if (basename(child).startsWith('dsh-')) consider(child, 'sibling');
+    }
+  }
+
+  // 4) 环境变量
+  const envVal = env && env.DSH_GUARD_PLUGINS;
+  if (envVal) {
+    for (const p of String(envVal).split(':').filter(Boolean)) considerCandidateDir(p, 'env');
+  }
+
+  return { sources, warnings, candidates };
+}

package/lib/docs.mjs

@@ -0,0 +1,416 @@
+/**
+ * 报告解析 + 三份交付文档生成。
+ *
+ * 输入兼容两种 JSON：
+ *   ① 普通扫描报告 { generatedAt, stats, findings[] }（stats 来自 dsh-guard-core）
+ *   ② dsh-fix-verify 的 JSON { fixed[], remaining[], regressed[], ... }
+ *
+ * 输出：自查表.csv / 整改说明.md / 合规证明.md
+ *
+ * ── 措辞红线 ─────────────────────────────────────────────────────
+ * 静态检查只是「把规则库能表达的东西查一遍」，它证明不了合规。
+ * 所以三份文件都必须带同一句声明；不得出现「已合规」「保证通过」这类结论。
+ */
+
+export const DISCLAIMER =
+  '本文件由本地静态检查生成，不构成合规结论，不替代等保测评/监管检查/第三方审计。';
+
+export const NO_HIT_NOTE =
+  '未命中不等于没有问题：静态检查只覆盖规则库能表达的判据，配置、流程、人员与实际运行情况仍需人工核查。';
+
+export const PROFILES = ['通用', '等保三级'];
+
+const SEV_LABEL = { critical: '严重', high: '高', medium: '中', low: '低' };
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, unknown: 9 };
+const STATUS_ORDER = { 遗留: 0, 新增回归: 0, 待确认: 0, 已修复: 1 };
+const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+
+export class InputError extends Error {}
+
+function str(v, fallback = '') {
+  return typeof v === 'string' ? v : fallback;
+}
+
+function num(v) {
+  return Number.isFinite(Number(v)) ? Number(v) : null;
+}
+
+export function severityLabel(sev) {
+  return SEV_LABEL[sev] || '未知';
+}
+
+function normalizeItem(f, status) {
+  if (!f || typeof f !== 'object' || Array.isArray(f)) {
+    throw new InputError('findings / 比对结果里存在非对象条目');
+  }
+  return {
+    ruleId: str(f.ruleId || f.id, '(未知规则)'),
+    title: str(f.title, '(未命名检查项)'),
+    severity: SEV_LABEL[f.severity] ? f.severity : 'unknown',
+    source: str(f.source),
+    advice: str(f.advice),
+    file: str(f.file, '(全局)'),
+    line: num(f.line) && num(f.line) > 0 ? num(f.line) : 0,
+    status,
+  };
+}
+
+function countBy(items, keyFn) {
+  const out = {};
+  for (const it of items) {
+    const k = keyFn(it);
+    out[k] = (out[k] || 0) + 1;
+  }
+  return out;
+}
+
+export function locationOf(it) {
+  return it.line ? `${it.file}:${it.line}` : it.file;
+}
+
+/**
+ * 把任意一种输入 JSON 归一化成统一的 model。
+ * 字段不对直接抛 InputError（CLI 会转成 exit 2）—— 绝不硬编一份看起来正常的文档。
+ */
+export function normalizeReport(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new InputError('输入 JSON 顶层必须是对象');
+  }
+
+  const hasFixShape = ['fixed', 'remaining', 'regressed'].every((k) => Array.isArray(raw[k]));
+  const hasScanShape = Array.isArray(raw.findings);
+
+  if (hasFixShape) {
+    const remaining = raw.remaining.map((f) => normalizeItem(f, '遗留'));
+    const regressed = raw.regressed.map((f) => normalizeItem(f, '新增回归'));
+    const fixed = raw.fixed.map((f) => normalizeItem(f, '已修复'));
+    const items = [...remaining, ...regressed, ...fixed];
+    const ruleIds = new Set(items.map((i) => i.ruleId));
+    const pluginSources = Array.isArray(raw.rules?.sources)
+      ? raw.rules.sources.map((s) => str(s?.name || s?.short)).filter(Boolean)
+      : [];
+    return {
+      mode: 'fix-verify',
+      modeLabel: '改前改后复核',
+      generatedAt: str(raw.generatedAt),
+      items,
+      scannedFiles: num(raw.after?.stats?.scannedFiles),
+      beforeScannedFiles: num(raw.before?.stats?.scannedFiles),
+      skippedCount: num(raw.after?.stats?.skippedCount),
+      rulesCount: num(raw.rules?.total) ?? ruleIds.size,
+      pluginSources,
+    };
+  }
+
+  if (hasScanShape) {
+    if (!raw.stats || typeof raw.stats !== 'object' || Array.isArray(raw.stats)) {
+      throw new InputError('扫描报告缺少合法的 stats 字段（应为对象）');
+    }
+    const items = raw.findings.map((f) => normalizeItem(f, '待确认'));
+    const ruleIds = new Set(items.map((i) => i.ruleId));
+    return {
+      mode: 'scan',
+      modeLabel: '静态扫描',
+      generatedAt: str(raw.generatedAt),
+      items,
+      scannedFiles: num(raw.stats.scannedFiles),
+      beforeScannedFiles: null,
+      skippedCount: num(raw.stats.skippedCount),
+      rulesCount: num(raw.stats.rulesRun) ?? num(raw.stats.rulesTotal) ?? ruleIds.size,
+      pluginSources: [],
+    };
+  }
+
+  throw new InputError(
+    '无法识别的输入：既不是 {generatedAt, stats, findings[]} 扫描报告，' +
+    '也不是含 fixed/remaining/regressed 数组的 dsh-fix-verify 报告',
+  );
+}
+
+/** 在归一化结果上补文档元信息与统计，并按「问题优先 + 严重度」排序 */
+export function buildModel(raw, { org = '', date, profile = '通用' } = {}) {
+  const base = normalizeReport(raw);
+  const items = [...base.items];
+  items.sort((a, b) =>
+    (STATUS_ORDER[a.status] ?? 0) - (STATUS_ORDER[b.status] ?? 0) ||
+    (SEV_ORDER[a.severity] ?? 9) - (SEV_ORDER[b.severity] ?? 9) ||
+    a.ruleId.localeCompare(b.ruleId) ||
+    a.file.localeCompare(b.file));
+
+  const bySeverity = countBy(items, (i) => i.severity);
+  const byStatus = countBy(items, (i) => i.status);
+  const problems = items.filter((i) => i.status !== '已修复');
+
+  return {
+    ...base,
+    org: org || '（未填写）',
+    date,
+    profile,
+    items,
+    total: items.length,
+    problemCount: problems.length,
+    fixedCount: byStatus['已修复'] || 0,
+    bySeverity,
+    byStatus,
+  };
+}
+
+// ── 自查表.csv ───────────────────────────────────────────────────
+
+function csvCell(v) {
+  const s = String(v ?? '');
+  return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+}
+
+function csvRow(cells) {
+  return cells.map(csvCell).join(',');
+}
+
+export function buildCsv(model) {
+  const lines = ['序号,检查项,严重度,依据,位置,状态,建议'];
+  model.items.forEach((it, i) => {
+    lines.push(csvRow([
+      i + 1,
+      it.title,
+      severityLabel(it.severity),
+      it.source,
+      locationOf(it),
+      it.status,
+      it.advice,
+    ]));
+  });
+  if (!model.items.length) {
+    lines.push(csvRow(['', '本次检查未发现提示项（未命中不等于没有问题）', '', '', '', '—', NO_HIT_NOTE]));
+  }
+  lines.push(csvRow(['', '【声明】' + DISCLAIMER, '', '', '', '仅供参考', '']));
+  // UTF-8 BOM：Excel 直接双击打开不乱码
+  return '\uFEFF' + lines.join('\r\n') + '\r\n';
+}
+
+// ── 整改说明.md ──────────────────────────────────────────────────
+
+function metaLines(model) {
+  const L = [];
+  L.push(`- 单位 / 组织：${model.org}`);
+  L.push(`- 检查日期：${model.date}`);
+  L.push(`- 检查方式：${model.modeLabel}（本地静态检查，不联网、不执行被检代码）`);
+  L.push(`- 文档生成时间：${new Date().toISOString()}`);
+  if (model.generatedAt) L.push(`- 报告生成时间：${model.generatedAt}`);
+  L.push(`- 文档档次（profile）：${model.profile}`);
+  return L;
+}
+
+function problemItems(model) {
+  return model.items.filter((i) => i.status !== '已修复');
+}
+
+function renderItem(it, idx) {
+  const L = [];
+  L.push(`### ${idx}. [${severityLabel(it.severity)}] ${it.title}`, '');
+  L.push(`- 规则：\`${it.ruleId}\``);
+  L.push(`- 位置：\`${locationOf(it)}\``);
+  L.push(`- 状态：${it.status}`);
+  L.push(`- 依据：${it.source || '（该检查项未提供依据文本）'}`);
+  L.push(`- 整改建议：${it.advice || '（该检查项未提供整改建议，请按规则依据人工确认）'}`);
+  L.push('');
+  return L.join('\n');
+}
+
+export function buildRectificationMd(model) {
+  const L = [];
+  L.push('# 整改说明', '');
+  L.push('> **声明**：' + DISCLAIMER, '');
+  L.push('## 文档信息', '');
+  L.push(metaLines(model).join('\n'));
+  L.push('');
+  L.push('## 一、背景', '');
+  if (model.mode === 'fix-verify') {
+    L.push('本说明依据一次「改前改后复核」的本地静态检查结果整理：对同一项目的旧快照与新快照运行同一套规则，' +
+      '逐条比对两次结果，区分已修复、遗留与新增回归项。');
+  } else {
+    L.push('本说明依据一次本地静态检查结果整理：使用深鲸守护插件提供的规则，对目标项目做只读扫描，' +
+      '把命中的提示项汇总成可跟踪的整改清单。');
+  }
+  L.push('静态检查的作用是**提示需要确认的位置**，不是判定违规；本说明也不对合规状态作结论。');
+  L.push('');
+  L.push('## 二、检查范围与方法', '');
+  const scope = [];
+  if (model.scannedFiles != null) scope.push(`扫描文件 ${model.scannedFiles} 个（跳过非文本 ${model.skippedCount ?? 0} 个）`);
+  if (model.mode === 'fix-verify' && model.beforeScannedFiles != null) {
+    scope.push(`旧快照 ${model.beforeScannedFiles} 个文件、新快照 ${model.scannedFiles} 个文件`);
+  }
+  scope.push(`运行规则 ${model.rulesCount} 条`);
+  if (model.pluginSources.length) scope.push(`规则来源插件：${model.pluginSources.join('、')}`);
+  L.push('- ' + scope.join('；'));
+  L.push('- 方法：只读遍历文件内容并按规则匹配，不联网、不执行被检代码、不上传任何文件；' +
+    '每条提示项都带「文件:行号」定位与规则依据，便于逐条核对。');
+  if (model.profile === '等保三级') {
+    L.push('- 说明：文档按「等保三级」关注点组织呈现，但规则集不变，本文件**不构成等保测评结论**。');
+  }
+  L.push('- 扫描范围只覆盖文本类文件；被扫描器跳过的目录（node_modules、dist 等）不在本次范围。');
+  L.push('');
+  L.push('## 三、发现的问题与整改建议', '');
+  const problems = problemItems(model);
+  if (!problems.length) {
+    L.push(model.mode === 'fix-verify'
+      ? '改后快照未发现提示项（遗留与新增回归均为 0）。'
+      : '本次静态检查未发现提示项。');
+    L.push('');
+    L.push('> ' + NO_HIT_NOTE);
+  } else {
+    L.push(`本次共整理 ${problems.length} 个提示项，按严重度从高到低列出：`);
+    L.push('');
+    problems.forEach((it, i) => L.push(renderItem(it, i + 1)));
+  }
+  L.push('');
+  const fixed = model.items.filter((i) => i.status === '已修复');
+  L.push('## 四、本轮已修复项（不计入待整改）', '');
+  if (!fixed.length) {
+    L.push('无。');
+  } else {
+    L.push(`本轮复核确认 ${fixed.length} 项在改后快照中已不再命中：`);
+    L.push('');
+    fixed.forEach((it, i) => {
+      L.push(`${i + 1}. [${severityLabel(it.severity)}] ${it.title}（\`${it.ruleId}\`，\`${locationOf(it)}\`）—— 改后快照未再命中`);
+    });
+  }
+  L.push('');
+  L.push('## 五、复核方式', '');
+  L.push('1. **重新跑一遍扫描**：用同一套规则、同一扫描范围重新生成报告；');
+  L.push('2. **改前改后对比**：用 `dsh-fix-verify --before <旧快照> --after <新快照>` 复核，' +
+    '确认「遗留」与「新增回归」是否归零；');
+  L.push('3. **逐条对照**：把新报告与本说明第三章逐条比对，确认状态是否由「遗留 / 待确认」变为「已修复」；');
+  L.push('4. **留痕**：旧报告、新报告与本说明一并归档，作为整改过程的证据；');
+  L.push('5. **人工复核**：规则覆盖不到的管理制度、流程、人员与运行情况，仍需人工核查。');
+  L.push('');
+  L.push('## 六、声明', '');
+  L.push('> ' + DISCLAIMER);
+  L.push('>');
+  L.push('> ' + NO_HIT_NOTE);
+  L.push('');
+  return L.join('\n');
+}
+
+// ── 合规证明.md ──────────────────────────────────────────────────
+
+function uniqueSources(items) {
+  const seen = new Set();
+  const out = [];
+  for (const it of items) {
+    const s = it.source.trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+function conclusionText(model) {
+  const rules = model.rulesCount ?? 0;
+  const files = model.scannedFiles ?? 0;
+  if (model.problemCount === 0) {
+    const extra = (model.mode === 'fix-verify' && model.fixedCount)
+      ? ` 本轮复核另确认已修复 ${model.fixedCount} 项。`
+      : '';
+    return [
+      `本次检查覆盖 ${rules} 条规则、${files} 个文件，未发现提示项。` + extra,
+      '',
+      '**措辞边界**：上述表述仅指本次静态检查在其规则覆盖范围内没有报出提示项。' +
+      '未命中不等于没有问题；' + DISCLAIMER,
+    ].join('\n');
+  }
+  if (model.mode === 'fix-verify') {
+    return [
+      `本轮复核结果：已修复 ${model.fixedCount} 项，遗留 ${model.byStatus['遗留'] || 0} 项，` +
+      `新增回归 ${model.byStatus['新增回归'] || 0} 项。`,
+      '',
+      '**措辞边界**：上述数字只描述同一套规则在改前/改后两份快照上的比对结果，' +
+      '不代表项目整体安全或合规状态。' + DISCLAIMER,
+    ].join('\n');
+  }
+  const sev = SEVERITIES
+    .filter((s) => model.bySeverity[s])
+    .map((s) => `${severityLabel(s)} ${model.bySeverity[s]} 项`)
+    .join('、');
+  return [
+    `本次检查覆盖 ${rules} 条规则、${files} 个文件，共发现 ${model.total} 个提示项` +
+    (sev ? `（${sev}）` : '') + '，已逐条列入《整改说明.md》。',
+    '',
+    '**措辞边界**：上述结果只是静态检查提示，不是违规判定，也不代表项目整体合规状态。' +
+    '在完成整改与人工复核前，不应引用本文件作为合规结论。' + DISCLAIMER,
+  ].join('\n');
+}
+
+export function buildAttestationMd(model) {
+  const L = [];
+  L.push('# 合规证明', '');
+  L.push('> **声明**：' + DISCLAIMER, '');
+  L.push('## 一、检查范围', '');
+  L.push(metaLines(model).join('\n'));
+  L.push('');
+  L.push('本次检查的对象与边界：');
+  L.push('');
+  L.push(`- 扫描文件数：${model.scannedFiles ?? '未提供'}` +
+    (model.mode === 'fix-verify' && model.beforeScannedFiles != null
+      ? `（旧快照 ${model.beforeScannedFiles} 个）`
+      : ''));
+  L.push('- 扫描方式：本地只读静态检查，不联网、不执行被检代码、不上传文件；');
+  L.push('- 规则来源：深鲸守护插件规则库（可在报告中核对每条规则 ID 与依据）；');
+  if (model.profile === '等保三级') {
+    L.push('- 文档档次：等保三级（仅影响文档组织方式，**不构成等保测评结论**）');
+  }
+  L.push('');
+  L.push('## 二、检查方法与规则条数', '');
+  L.push(`- 运行规则：${model.rulesCount ?? 0} 条`);
+  if (model.pluginSources.length) L.push(`- 规则来源插件：${model.pluginSources.join('、')}`);
+  L.push('- 判定方法：逐文件匹配规则库中的判据；命中项输出文件、行号、依据与建议；');
+  L.push('- 规则未命中不代表该项目不存在问题 —— 静态规则只能覆盖可文本化、可自动化的判据。');
+  L.push('');
+  L.push('## 三、依据清单（去重）', '');
+  const sources = uniqueSources(model.items);
+  if (!sources.length) {
+    L.push('本次检查未发现提示项，无对应依据条目。');
+  } else {
+    sources.forEach((s, i) => L.push(`${i + 1}. ${s}`));
+  }
+  L.push('');
+  L.push('## 四、检查结果', '');
+  if (model.problemCount === 0) {
+    L.push(`本次检查覆盖 ${model.rulesCount ?? 0} 条规则、${model.scannedFiles ?? 0} 个文件，未发现提示项。`);
+    if (model.mode === 'fix-verify' && model.fixedCount) {
+      L.push('');
+      L.push(`本轮复核另确认已修复 ${model.fixedCount} 项（改后快照不再命中）。`);
+    }
+    L.push('');
+    L.push('> ' + NO_HIT_NOTE);
+  } else if (model.mode === 'fix-verify') {
+    L.push(`- 已修复：${model.fixedCount} 项`);
+    L.push(`- 遗留：${model.byStatus['遗留'] || 0} 项`);
+    L.push(`- 新增回归：${model.byStatus['新增回归'] || 0} 项`);
+    L.push('');
+    L.push('> 逐条明细见《整改说明.md》。');
+  } else {
+    L.push(`- 提示项合计：${model.total} 项`);
+    L.push(`- 按状态：${Object.entries(model.byStatus).map(([k, v]) => `${k} ${v} 项`).join('、')}`);
+    L.push(`- 按严重度：${SEVERITIES.filter((s) => model.bySeverity[s]).map((s) => `${severityLabel(s)} ${model.bySeverity[s]} 项`).join('、') || '—'}`);
+    L.push('');
+    L.push('> 逐条明细与整改建议见《整改说明.md》，清单见《自查表.csv》。');
+  }
+  L.push('');
+  L.push('## 五、结论措辞', '');
+  L.push(conclusionText(model));
+  L.push('');
+  L.push('---', '');
+  L.push('本文件为机器生成的检查记录，可作为内部自查材料归档；对外提交前请由责任人核对并补充人工复核意见。');
+  L.push('');
+  return L.join('\n');
+}
+
+/** 生成三份文件：文件名 -> 内容 */
+export function buildDocuments(model) {
+  return {
+    '自查表.csv': buildCsv(model),
+    '整改说明.md': buildRectificationMd(model),
+    '合规证明.md': buildAttestationMd(model),
+  };
+}

package/lib/index.js

@@ -0,0 +1,14 @@
+import { createPlugin, pkgRootFrom } from '@deepwhale-cn/dsh-guard-core/plugin';
+
+// 把本地静态检查结果变成能交出去的文档：
+// 自查表.csv / 整改说明.md / 合规证明.md，三份都带「不构成合规结论」声明。
+export const { name, inject, apply } = createPlugin({
+  name: 'compliance-doc',
+  pkgRoot: pkgRootFrom(import.meta.url),
+  skillFile: 'skill/compliance-doc.md',
+  binFile: 'bin/cli.mjs',
+  description: '一份能交出去的自查表、整改说明和合规证明',
+  whenToUse: '用户要把安全检查结果整理成可交付文档时使用：' +
+    '「出一份自查表」「写个整改说明」「做一份合规证明」「检查报告要给领导/客户/测评机构看」。' +
+    '输入可以是普通扫描报告，也可以是 dsh-fix-verify 的 --json 复核结果。',
+});

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@deepwhale-cn/dsh-compliance-doc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "一份能交出去的自查表、整改说明和合规证明",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "plugin",
+    "skill",
+    "security",
+    "guard",
+    "compliance-doc",
+    "合规报告",
+    "自查表",
+    "整改说明",
+    "合规证明",
+    "等保"
+  ],
+  "files": [
+    "lib",
+    "skill",
+    "bin",
+    "docs",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./discover": "./lib/discover.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-compliance-doc": "bin/cli.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.1.0-rc.6 <0.3.0",
+    "node": ">=18"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepwhale-cn/dsh-guard-core": "^0.10.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feely0208/dsh-compliance-doc.git"
+  },
+  "homepage": "https://www.deepwhale.org.cn/skills.html",
+  "bugs": {
+    "url": "https://github.com/feely0208/dsh-compliance-doc/issues"
+  }
 }

package/skill/compliance-doc.md

@@ -0,0 +1,71 @@
+# 合规可交付文档（dsh-compliance-doc）
+
+**什么时候用**：安全检查已经跑完，要把结果整理成能交出去的文档。
+用户会说：「出一份自查表」「写个整改说明」「做一份合规证明」「报告要给领导 / 客户 / 测评机构看」
+「扫描结果导出成 Excel」「整改完要留个记录」。
+
+## 怎么用
+
+```bash
+<cli 路径> --input <报告.json> --out <输出目录>                       # 三份文件
+<cli 路径> --input <报告.json> --out <目录> --org "公司名"             # 写上单位
+<cli 路径> --input <报告.json> --out <目录> --date 2026-10-20          # 指定检查日期
+<cli 路径> --input <报告.json> --out <目录> --profile 等保三级          # 文档档次
+<cli 路径> --input <报告.json> --out <目录> --quiet                   # 只输出一行结果
+```
+
+输入有两种来源：
+
+```bash
+# ① 普通 / suite 扫描报告（{ generatedAt, stats, findings[] }）
+<cli 路径> --input report.json --out ./交付
+
+# ② dsh-fix-verify 的 --json 输出（含 fixed / remaining / regressed）
+dsh-fix-verify --before old --after new --json > fix-verify.json
+<cli 路径> --input fix-verify.json --out ./交付
+```
+
+## 生成什么
+
+| 文件 | 内容 |
+|---|---|
+| `自查表.csv` | 序号 / 检查项 / 严重度 / 依据 / 位置 / 状态 / 建议；UTF-8 BOM，Excel 直接打开 |
+| `整改说明.md` | 背景 / 检查范围与方法 / 逐条问题与整改建议 / 复核方式说明 |
+| `合规证明.md` | 检查范围 / 规则条数 / 依据清单（去重）/ 结论措辞 |
+
+fix-verify 输入时，状态列会区分「已修复 / 遗留 / 新增回归」；
+整改说明会单列「本轮已修复项」，不和待整改问题混在一起。
+
+## 输入格式
+
+**扫描报告**：必须有 `findings` 数组和 `stats` 对象（`scannedFiles`、`rulesRun` 等来自
+`dsh-guard-core`）。0 命中就是 `findings: []`。
+
+**fix-verify 报告**：顶层有 `fixed` / `remaining` / `regressed` 三个数组；
+文件数取自 `after.stats.scannedFiles`，规则数取自 `rules.total`。
+
+字段不对、JSON 解析失败、输入不存在 → **exit 2**（不会生成半份假文档）。
+
+## 退出码
+
+| 码 | 含义 |
+|---|---|
+| `0` | 三份文件正常生成 |
+| `2` | 输入缺失 / JSON 解析失败 / 字段不对 / 参数错误（含非法 profile、非法日期） |
+
+## 措辞边界（必须保留）
+
+三份文件都会写明：
+
+> 本文件由本地静态检查生成，不构成合规结论，不替代等保测评/监管检查/第三方审计。
+
+- 0 命中时写「本次检查覆盖 N 条规则、M 个文件，未发现提示项」，并提醒「未命中不等于没有问题」；
+- 不写「已合规」「保证通过」；
+- `--profile 等保三级` 只改变文档组织方式，不构成等保测评结论。
+
+## 不要做什么
+
+- 不要把生成的 `合规证明.md` 当合规证书用
+- 不要删掉免责声明或把「提示项」改写成「违规项」
+- 不要用它代替人工复核与真实测评
+- 不要在没有扫描报告时手编输入 —— 先用扫描插件 / `dsh-fix-verify` 生成真实报告