# dsh-tool-content-guard **Repository Path**: hc905/dsh-tool-content-guard ## Basic Information - **Project Name**: dsh-tool-content-guard - **Description**: host 侧保险:工具 render 把 content 的 text 写成数组时,自动拼成字符串(避免 DeepSeek Messages 422 打毒会话);开发模式可改为直接判失败。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-13 - **Last Updated**: 2026-10-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # dsh-tool-content-guard — 工具 content 兜底守卫 host 侧的保险:**工具 content 块里的 `text` 必须是字符串**。插件(或任何工具作者)把 `text` 写成行数组时,这条守卫在结果落进会话日志**之前**把它强制拼成字符串,并点名是哪个 工具干的。 ## 它防的是什么 DSH 对工具 `output.render()` 返回的 content 只做**无损 JSON 快照**,不会替插件拼接: ```js 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` ✓。 **方式三:本地路径**(开发用) ```jsonc // ~/.dsh/profiles/desktop/package.json "dependencies": { "dsh-tool-content-guard": "link:<插件目录的绝对路径>" }, "dsh": { "profile": { "bundles": [ /* … */ "dsh-tool-content-guard" ] } } ``` 无论哪种方式,都要在 profile 的 `cordis.patch.yml` 里留一行挂载项(默认行为已经够用, 只有要改 `mode` 才需要写 `config`): ```yaml # ~/.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')`。 ## 自检 ```powershell # 纯 Node 单测:35 项,末行 CONTENT GUARD: OK(随包发布;任何 Node ≥18 都能跑) node test/content-guard.test.mjs npm test # 等价写法 ``` 本机另有一份**真数据交叉验证**(不随包发布):拿被污染会话里那条真实坏记录 (`seq=2856`,数组 30 行)喂给守卫,断言输出与「插件侧 join」逐字符一致(1551 字): ```powershell 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` 返回成功(`+ dsh-tool-content-guard@1.0.0`),版本却进了**分阶段发布队列**: 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 的终端里做): ```powershell npm login # 换成能过 2FA 的登录态(或直接在 npmjs.com 包页面点批准) npm stage list # 记下 stage-id(UUID) npm stage approve npm view dsh-tool-content-guard version # 期望 1.0.0,不再是 0.0.0-stage ``` 要避免这一步:用能通过 2FA 的发布方式(交互式 `npm login` 后的会话), 或调整账号的 2FA 策略。**判据**:`npm view 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](./CHANGELOG.md)。