dsh-tool-content-guard
Verifieddsh-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。