会话日志脱敏 L-ingqin12/dsh-redaction

dsh-redaction

为 DeepSeek Harness 提供的两个插件，以及催生它们的平台研究。

它们解决的问题是：一次公开网络搜索、一条 gh 命令、一次日志抓取——任何工具都可能返回你不应保留的内容。在 DSH 中，这些内容不仅仅是流经而已：存储的 tool/result 事件就是面向模型的消息，因此一次写入就会把它同时提交到持久会话日志和未来每一次的提供商请求中。如果它属于提供商的內容过滤器会拒绝的那类内容，那么该轮次就会失败——而且之后的每一轮也会失败，因为历史记录会一直携带它。

两个包

| 包 | 层级 | 作用 |
| dsh-plugin-content-policy | 预防 | 在 tools/execute 瀑布流上应用规则和结构化剥离，在结果被持久化之前执行。重写结果的 value，因此渲染出的文本和持久化的 meta 会一起被清理。 |
| dsh-plugin-redact | 补救 | 对已有的 session.vN.jsonl.zstd 日志进行就地脱敏和回滚，由 dsh-tui 内部驱动。包含一个帧级引擎（也可作为 dsh-redact CLI 使用）、会话内实时 hide、轮次回滚和撤销。 |

它们被刻意分开：预防无法处理已经落盘的内容，而补救对下一次搜索结果无能为力。

dsh plugin --profile add ./packages/dsh-plugin-content-policy
dsh plugin --profile add ./packages/dsh-plugin-redact
dsh --profile --dump-config # confirm both rows composed

/redact pick——即键盘可选择的节点列表——默认关闭：当审批面板处于待处理状态时，该模态对话框可能会锁住 TUI 键盘。机制详见 docs/01-platform/dsh-tui-internals.md，一行式启用方式见该包 README。

背后的研究

docs/reports/ 中的一切内容都是通过阅读已安装的部署并运行它而确立的——并非来自文档，因为文档并未覆盖其中大部分内容。这些是原始产物，保留下来是因为结论的可靠性取决于证据：

| 路径 | 内容 |
| reports/redteam/ | 对脱敏工具的红队审查：十项发现，附机制、复现脚本，以及以读者为判据的结论。其中两项会使会话永久无法打开，而工具却报告成功。 |
| reports/fix/ | 修复方案，附每项发现的前后输出对比，以及测试套件结果 |
| reports/dialog-root-cause/ | 插件对话框为何会锁住终端键盘：确切的三部分机制、死锁状态矩阵，以及独立复现脚本 |
| reports/dialog-contract/ | 真实的 tuiDialogs 契约——校验边界、promise 语义、唯一的抛出路径，以及能否在打开模态框之前检测到渲染器（不能） |
| reports/boot-verify/ | 真实 boot() 路径的复现：加载/激活扫描、配置边界矩阵、双轨 Config 对比，以及证明 --dump-config 完全不导入插件模块 的测量 |
| reports/surveys-existing-plugins.zh.md | 在撰写本文之前 DSH 插件生态系统中已经存在的内容，以及每个近似方案止步于何处 |

一组综合的平台笔记（会话日志格式、持久化内部机制、工具结果流水线、TUI 的扩展面、缺陷目录以及流程回顾）存放在作者的本地 Obsidian 仓库中，而非此处，因为它是按照该仓库的链接和元数据约定撰写的。

验证状态

| 套件 | 断言数 |
| dsh-plugin-redact 处理器 | 248 |
| dsh-plugin-redact 回归（以真实读取器为基准） | 54 |
| dsh-plugin-redact 加固 | 78 |
| dsh-plugin-redact 引擎 / CLI | 34 |
| dsh-plugin-content-policy（4 个套件） | 103 |

dsh-plugin-redact 引擎还通过使用真实的 JsonlSessionPersistence.open() 打开其输出进行额外验证；仅运行工具自身自检的套件不被接受为证据（这个错误曾导致一个缺陷被发布——参见回顾）。

需要 Node >= 22.15 以使用 zlib zstd API。插件本身没有运行时依赖——只有可选的 peer 依赖。

在本地复现这些检查

cd packages/dsh-plugin-redact && npm test # engine 34 + handler 248 + torn-tail 11 + CLI smoke
cd packages/dsh-plugin-content-policy && npm test # the two pure suites: 45 + 36
node .github/scripts/portability.selftest.mjs # from the repo root
node .github/scripts/pack-check.mjs # from the repo root

.github/workflows/ci.yml 在 ubuntu-latest 和 windows-latest 上，跨 Node 22.15、22.x 和 24.x 运行这些相同的命令。需要真实 DSH 安装的套件被有意地不纳入 CI：它们从 DSH_HOME 推导安装位置，并在其缺失时以 3 退出，而不是空洞地通过。

如果你在 Windows 上开发，你可以在推送前复现 Linux 分支，而不必等待一次失败的构建。WSL 就足够了——不需要 Docker：

curl -fsSL https://nodejs.org/dist/v22.21.0/node-v22.21.0-linux-x64.tar.xz | tar -xJ -C /opt
/opt/node-v22.21.0-linux-x64/bin/node test/engine.selftest.mjs

为什么存在可移植性防护

第一次 CI 运行在 37 秒后失败：test/preflight.mjs 读取了 process.env.USERPROFILE，而它在 Linux 上是 undefined，因此 path.join(undefined, '.dsh') 抛出了 ERR_INVALID_ARG_TYPE。该文件位于 npm files 允许列表中，因此每个运行 npm test 的非 Windows 消费者都会遇到它。仅在 Windows 上运行测试无法发现这一类缺陷——它恰恰在它被编写的地方不可见。
因此，.github/scripts/portability.mjs 会静态扫描两个包中已发布的代码和测试，以查找四种仅适用于 Windows 的假设：

| 规则 | 它捕获的内容 |
| win-only-env | 使用 USERPROFILE / HOMEDRIVE / APPDATA / LOCALAPPDATA 时，后面没有紧跟 ?? 或 \|\| 回退 |
| import-meta-pathname | import.meta.url 与 .pathname 组合使用，这会在包含空格的路径中留下 %20 |
| hardcoded-win-path | 字符串字面量中硬编码的驱动器号 |
| path-win32 | path.win32，它会在所有平台上强制使用 Windows 语义 |

win-only-env 的规则刻意针对变量，而不是行：DSH_HOME ?? path.join(process.env.USERPROFILE, '.dsh') 包含 ??，但仍然是坏的。

它的自测正是其意义所在。portability.selftest.mjs 将真实的 USERPROFILE 缺陷重新注入 preflight.mjs，断言该守卫失败并指出文件名和正确的行号，然后在 finally 中恢复该文件。一个不会失败的守卫比没有守卫更糟，而硬编码到测试中的行号就是一个会因错误原因而变红的守卫。

为什么会有打包检查

每个 package.json 中的 files 允许列表是手工维护的，而 index.js 导入 lib/engine.mjs，同时 bin/dsh-redact.mjs 又第二次导入它。添加一个导入却忘记允许列表条目，这里的每个检查都会保持绿色，而发布的包却缺少一个文件——这种失败只有使用者才能看到。

.github/scripts/pack-check.mjs 询问 npm 它实际会发布什么（npm pack --dry-run --json），然后遍历已发布入口点内的每个相对导入，并要求每个解析后的目标都在该 tarball 中。它还断言测试运行中的任何内容（fixture.、plan-.json、needle.txt、broken.zstd）都不会被一并带上。从允许列表中移除 lib/engine.mjs 会让它按名称报告两个导入方。

License

MIT — 见 LICENSE。

维护者：PUBLISHING.md 涵盖了 npm 发布步骤和发布前门禁。