Skip to content

dsh-tool-content-guard

Verified

dsh-tool-content-guard · v1.0.3 · MIT

DSH 插件:host 侧兜底——把工具 content 里非字符串的 `text` 强制字符串化(默认),或在开发模式下直接把这次调用判失败。挂在官方扩展点 tools/post-execute,先让其它策略跑完再归一化,避免 `{"type":"text","text":[…]}` 这种非法块把 DeepSeek Messages 请求打成 422(invalid type: sequence, expected a string),也避免它落进会话日志、毒掉整个会话。

Install

dsh plugin add dsh-tool-content-guard

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

dsh-tool-content-guard — 工具 content 兜底守卫

host 侧的保险:工具 content 块里的 text 必须是字符串。插件(或任何工具作者)把 text 写成行数组时,这条守卫在结果落进会话日志之前把它强制拼成字符串,并点名是哪个 工具干的。

它防的是什么

DSH 对工具 output.render() 返回的 content 只做无损 JSON 快照,不会替插件拼接:

render: () => [{ type: 'text', text: [ '第 1 行', '第 2 行' ] }]              // ✗
render: () => [{ type: 'text', text: [ '第 1 行', '第 2 行' ].join('\n') }]    // ✓

前者会让请求体里出现 {"type":"text","text":[…]},DeepSeek Messages 网关整包 422:

Failed to deserialize the JSON body into the target type:
messages[887].content: invalid type: sequence, expected a string

而且这条工具结果会原样落进会话日志——只要它在历史里,该会话之后每一次请求都被拒, 重试无效(2026-10-13 真实事故:patent_invalidation_verify 的第一次成功返回把 「制作照明装置无效口审PPT」那个会话打毒;插件侧已改成 ].join('\n'),这条守卫是防复发)。

挂在哪儿

官方扩展点 tools/post-execute(prepend,最外层):先 await next() 让其它 post-execute 策略跑完,再归一化最终 content;PTC 子调用的 tools/ptc-dispatch-log 瀑布同样处理(它也是持久记录)。

归一化规则:

进来的 text 出去
字符串 原样(且原样返回同一个 decision 对象,不做无谓拷贝)
数组 逐元素取文本、\n 拼接;嵌套数组 flat(Infinity);null/undefined → 空行;标量 → String;对象 → JSON
数字 / 布尔 / 对象 / null 变成可读字符串
content 不是数组 / 没有非法块 原样透传

深冻结安全:只重建被改到的块({ ...block, text }),未改的块保持同一引用,不改写原数组。

配置

mode:

值 行为
coerce(默认) 修好 + logger.warn 点名工具/callId/形状/片段,不打断这次调用
block 不修,直接把这次工具调用判失败(isError),把诊断文本回给模型——插件开发者自查用
off 完全不挂监听

warnChars:告警里回显被修文本的字符数(默认 160,0=不回显)。

安装

方式一:npm(不需要本机安装 git)

DSH 桌面端 → 侧栏「插件」→「添加插件」,输入:

dsh-tool-content-guard

npm 首发 1.0.0 已于 2026-10-13 上线(实测 pnpm add dsh-tool-content-guard 装到 1.0.0, 且装下来的那份自检 35 项全过)。发布瞬间 registry 上曾只出现占位版 0.0.0-stage (“Temporary package placeholder for staged publishing”),几分钟后 dist-tags.latest 自动指向 1.0.0;这段经过记在下面「发版(维护者)」里,供下次发布排障。

方式二:从 Gitee 仓库安装(需要本机已安装 git;地址注意结尾的 .git)

https://gitee.com/hc905/dsh-tool-content-guard.git

结尾不带 .git 的裸地址(https://gitee.com/hc905/dsh-tool-content-guard)会被 pnpm 当成 tarball 去解包,报 ERR_PNPM_TARBALL_EXTRACT;写 git+https://…git 也等价。 实测(pnpm 11.7.0):.git 结尾 → 装成 dsh-tool-content-guard 1.0.0 ✓。

方式三:本地路径(开发用)

// ~/.dsh/profiles/desktop/package.json
"dependencies": { "dsh-tool-content-guard": "link:<插件目录的绝对路径>" },
"dsh": { "profile": { "bundles": [ /* … */ "dsh-tool-content-guard" ] } }

无论哪种方式,都要在 profile 的 cordis.patch.yml 里留一行挂载项(默认行为已经够用, 只有要改 mode 才需要写 config):

# ~/.dsh/profiles/desktop/cordis.patch.yml(改 mode 就按 id 覆盖)
- id: tool-content-guard
  disabled: false
  # config: { mode: block }   # coerce(默认)| block | off

必须重启 DSH:loader 只在启动时读 profile 的 bundle 层,本次会话内不会热挂载 (市场的 activation 会写 restart)。

同一台机器不要同时装「npm 版」「git 版」「本地 link 版」——三者的挂载 id 都是 tool-content-guard,会冲突。

卸载

# 在 profile 目录执行(npm / git / 本地 link 安装都用这个包名)
pnpm remove dsh-tool-content-guard
# 再把 profile 的 dsh.profile.bundles 里的 dsh-tool-content-guard 删掉,然后重启 DSH

已知边界

  • 工具自己的 finalizeContent 在 post-execute 之后执行,它引入的非法 text 拦不到 (现网没有工具用它;tools/result 是只读观察点)。
  • 别的策略替换了 value 时,注册表会重新 render() 得到新 content,那条路径不经过 post-execute,也拦不到。
  • 已经落进会话日志的坏记录不会再次经过这里:那是日志修复的事 (D:\DWork\dsfix\repair-session-text.mjs)。
  • 这是兜底,不是许可:插件 render() 仍然要写 [ ... ].join('\n')。

自检

# 纯 Node 单测:35 项,末行 CONTENT GUARD: OK(随包发布;任何 Node ≥18 都能跑)
node test/content-guard.test.mjs
npm test                                      # 等价写法

本机另有一份真数据交叉验证(不随包发布):拿被污染会话里那条真实坏记录 (seq=2856,数组 30 行)喂给守卫,断言输出与「插件侧 join」逐字符一致(1551 字):

node D:\DWork\dsfix\verify-guard-vs-log.mjs   # 末行 GUARD vs LOG: OK

活体验证记录(2026-10-13)

重启 DSH 后在本机做过一次真实链路核对(当时用的临时探针插件已删除,只留结论):

  • 市场接口 /dsh-market/installed 对本插件读作 state: live / hot: true(bundle 层已挂上);
  • 用真实案件文件跑 patent_invalidation_verify(正是当年把会话打毒的那次调用), 这条工具结果在会话日志里落成 content[0].text = string,1551 字 / 30 行, 与插件侧 ].join('\n') 的结果一致;
  • 同一份坏数据(日志备份 seq=2856 的数组 30 行)走守卫,输出同样是这 1551 字(见上面「自检」里的真数据交叉验证)。

发版(维护者)

完整流程见 《Gitee + npm 发布操作清单》(本机 D:\DWork\Gitee+npm发布操作清单.md): 改版本号 + CHANGELOG → 跑自检 → npm pack --dry-run → 提交并打 annotated tag vX.Y.Z → 推 master 与 tag → npm publish → 核对 tag 与 npm 的 shasum 一致。

本插件自己的两点:

  • 自检:npm test(35 项,末行必须 CONTENT GUARD: OK);
  • 发布物白名单 = package.json 的 files:cordis.patch.yml、index.js、locale、 test、icon.svg、CHANGELOG.md,外加 npm 强制包含的 README.md / LICENSE / package.json;node_modules/(本地 junction)与 *.bak-* 由 .gitignore 挡住。

npm 发布会被分阶段(staged publishing)— 2026-10-13 实测

本机 ~/.npmrc 里是绕过 2FA 的 token,npm 正在限制这类 token 用于 direct publishing, 于是 npm publish 返回成功(+ [email protected]),版本却进了分阶段发布队列: registry 上只多出一个占位版 0.0.0-stage(description = “Temporary package placeholder for staged publishing”,2 files / 344 B),dist-tags.latest 指向它,真正的 1.0.0 不可见、不可装。 用同一个 token 也读不到待批队列:npm stage list 返回 [],npm profile get 直接 403。

批准(要过账号 2FA,在能交互输入 OTP 的终端里做):

npm login                 # 换成能过 2FA 的登录态(或直接在 npmjs.com 包页面点批准)
npm stage list            # 记下 stage-id(UUID)
npm stage approve <stage-id>
npm view dsh-tool-content-guard version    # 期望 1.0.0,不再是 0.0.0-stage

要避免这一步:用能通过 2FA 的发布方式(交互式 npm login 后的会话), 或调整账号的 2FA 策略。判据:npm view <pkg> version 显示 0.0.0-stage 就是还卡在审批。

本次实测的结局:没有做任何批准动作,约 6 分钟后 dist-tags.latest 自己变成了 1.0.0 (versions 里 0.0.0-stage 与 1.0.0 并存,前者是占位残留)。所以看到 0.0.0-stage 先别慌,过几分钟复查一次;若长时间仍是占位,再用上面的批准命令或去 npmjs.com 点批准。

发布物白名单 = package.json 的 files:cordis.patch.yml、index.js、locale、 test、icon.svg、CHANGELOG.md,外加 npm 强制包含的 README.md / LICENSE / package.json。node_modules/(本地 junction)与 *.bak-* 由 .gitignore 挡住, 既不进仓库也不进包。

本机是 link: 安装(指向上面的工作目录):改了 index.js 必须重启 DSH 才生效, loader 按模块 URL 缓存已加载的插件。

变更记录

见 CHANGELOG.md。