dsh-tool-content-guard 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 变更记录（Changelog）
+
+本文件记录 `dsh-tool-content-guard` 的对外变更。版本号语义：修 bug → patch，
+行为/配置新增 → minor，不兼容的挂载点或默认行为变更 → major。
+
+## [1.0.0] — 2026-10-13
+
+首个发布版。
+
+- **兜底归一化**：工具 content 块里 `text` 不是字符串时，在结果落进会话日志**之前**强制归一化——
+  数组逐元素取文本、`\n` 拼接（嵌套数组 `flat(Infinity)`；`null`/`undefined` → 空行；标量 → `String`；
+  对象 → JSON）；数字/布尔/对象/`null` 同样变成可读字符串。
+- **挂载点**：官方扩展点 `tools/post-execute`（`prepend`，最外层：先 `await next()` 让其它策略跑完，
+  再归一化**最终** content）；PTC 子调用的 `tools/ptc-dispatch-log` 瀑布同样处理。
+- **三种模式**：`coerce`（默认：修好 + `logger.warn` 点名工具/callId/形状/片段，不打断调用）、
+  `block`（不修，直接把这次调用判失败并把诊断回给模型，插件开发者自查用）、`off`（不挂监听）；
+  `warnChars` 控制告警里回显的字符数（默认 160，0=不回显）。
+- **无副作用**：合法 content 原样返回**同一个 decision 对象**（不拷贝、不告警）；只重建被改到的块
+  （`{ ...block, text }`），未改的块保持同一引用，深冻结安全。
+- **自检**：35 项纯 Node 单测（`npm test`，末行 `CONTENT GUARD: OK`）。
+
+**背景（为什么要它）**：2026-10-13 `patent_invalidation_verify` 的 `render()` 把 `text` 写成了
+30 行数组，请求体里出现 `{"type":"text","text":[…]}`，DeepSeek Messages 网关整包 422
+（`messages[N].content: invalid type: sequence, expected a string`），而这条结果已原样落进会话日志——
+该会话之后**每一次**请求都被拒、重试无效，只能对会话日志做单帧修复。插件侧已改成 `].join('\n')`，
+本插件是防复发。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZHC
+
+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,168 @@
-# Temporary Holding Version
+# 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
+```
+
+**方式二：从 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 字（见上面「自检」里的真数据交叉验证）。
+
+## 发版（维护者）
+
+```powershell
+# 1) 改 package.json 的 version（唯一版本源；修 bug → patch，行为/配置新增 → minor）
+#    同步在 CHANGELOG.md 顶部加一条
+npm test                 # 35 项，必须末行 CONTENT GUARD: OK
+npm pack --dry-run       # 看 tarball 内容，确认没多带东西
+# 2) 提交并推 Gitee，打 tag
+git add -A; git commit -m "release: v1.0.0"; git tag v1.0.0
+git push origin main --tags
+# 3) 发 npm（首发 2026-10-13 已完成；此后就是 npm publish）
+npm publish
+```
+
+发布物白名单 = `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)。
 
-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.

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# 工具 content 兜底守卫 — bundle patch.
+#
+# One Host row: `tool-content-guard` mounts the `tools/post-execute` guard from
+# `index.js`. `config` is validated against the plugin's `Config` schema at
+# activation, and this profile layer survives plugin upgrades.
+#
+# 说明：这里**故意不带 `config:`**——loader 的「热挂载」只支持**纯 insert**，行里一写
+# config/表达式就必须重启才生效（市场面板的 activation 会写 `restart`）。插件的
+# `Config` 自带默认值（mode: coerce、warnChars: 160），所以空 config 的行为就是默认行为。
+#
+# 要改 mode/warnChars，在 profile 的 `cordis.patch.yml` 里按 id 覆盖（patch 层在 bundle
+# 层之后应用），例如：
+#
+#   - id: tool-content-guard
+#     config:
+#       mode: block      # coerce（默认）| block（开发自查：直接判失败）| off
+#       warnChars: 160
+- insert:
+    - id: tool-content-guard
+      name: 'dsh-tool-content-guard'

package/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="#2563EB" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 3l7 3v5.5c0 4.2-2.9 7.9-7 9.5-4.1-1.6-7-5.3-7-9.5V6z" />
+  <path d="M9.6 9.6H8.3v4.8h1.3M14.4 9.6h1.3v4.8h-1.3M9.6 12h4.8" />
+</svg>

package/index.js

@@ -0,0 +1,188 @@
+/**
+ * dsh-tool-content-guard — host 侧兜底：工具 content 的 `text` 必须是字符串。
+ *
+ * ## 为什么要有它
+ *
+ * DSH 对工具 `output.render()` 返回的 content 只做**无损 JSON 快照**，不会替插件拼接。
+ * 插件一旦把 `text` 写成行数组：
+ *
+ * ```js
+ * { type: 'text', text: ['第 1 行', '第 2 行'] }      // ✗
+ * { 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」那个会话打毒）。
+ *
+ * ## 它做什么
+ *
+ * 挂在官方扩展点 `tools/post-execute`（`prepend`，最外层）：先让其它 post-execute 策略
+ * 跑完（`await next()`），再对**最终** content 做一次归一化；PTC 子调用的
+ * `tools/ptc-dispatch-log` 瀑布同样处理（它也是持久记录）：
+ *
+ * - `text` 是数组 → 逐元素取文本、用 `\n` 拼成字符串（与插件自己该写的 `join('\n')` 等价，
+ *   嵌套数组按 `flat(Infinity)` 展开；`null`/`undefined` → 空行；标量 → `String`；对象 → JSON）；
+ * - `text` 是数字/布尔/对象/`null` → 变成可读字符串；
+ * - `text` 已经是字符串 → **原样返回同一个 decision**（不做无谓的拷贝）；
+ * - 只重建被改到的块（content 与块在管线里是深冻结的，就地改会抛）。
+ *
+ * `mode`：
+ *
+ * | 值 | 行为 |
+ * |---|---|
+ * | `coerce`（默认） | 修好 + `logger.warn` 点名工具/callId/形状/片段，**不打断**这次调用 |
+ * | `block` | 不修，直接把这次工具调用判失败（`isError`），把诊断文本回给模型——插件开发者自查用 |
+ * | `off` | 完全不挂监听 |
+ *
+ * ## 已知边界
+ *
+ * - 工具自己的 `finalizeContent` 在 post-execute **之后**执行，它引入的非法 `text` 这里拦不到
+ *   （现网没有工具用它；`tools/result` 是只读观察点，改不了内容）。
+ * - 别的策略替换了 `value` 时，注册表会重新 `render()` 得到新 content，那条路径不再经过
+ *   post-execute，也拦不到。
+ * - **已经落进会话日志**的坏记录不会再次经过这里：那是日志修复的事，
+ *   用 `D:\DWork\dsfix\repair-session-text.mjs` 修。
+ * - 这条守卫是兜底，不是许可：真正的修法仍然是插件 `render()` 里写 `[ ... ].join('\n')`。
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+/** Stable Loader identity. */
+const name = 'tool-content-guard'
+
+/** Services the plugin needs; without the tool registry it stays inactive. */
+const inject = ['tools']
+
+/** Validated configuration, overridable in the profile's cordis.patch.yml. */
+const Config = z.object({
+  /** coerce=修好并告警（默认）；block=判失败并把诊断回给模型；off=不挂监听。 */
+  mode: z.union(['coerce', 'block', 'off']).default('coerce'),
+  /** 告警里回显被修文本的字符数（0=不回显）。 */
+  warnChars: z.number().default(160),
+})
+
+/* ------------------------------------------------------------------ helpers */
+
+/** 数组元素 → 一行文本：字符串原样；null/undefined 视作空行；标量 String；其余 JSON。 */
+function elementText(value) {
+  if (typeof value === 'string') return value
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') return String(value)
+  try {
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    return String(value) // 循环引用等
+  }
+}
+
+/**
+ * 任意 `text` 值 → 字符串。
+ * @param value - 插件 render 放进 text 字段的任意 JSON 值。
+ * @returns 可直接发给 provider 的字符串。
+ */
+function coerceText(value) {
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return value.flat(Infinity).map(elementText).join('\n')
+  return elementText(value)
+}
+
+/** 形状描述（告警用）。 */
+function shapeOf(value) {
+  if (Array.isArray(value)) return `数组(${value.length} 行)`
+  if (value === null) return 'null'
+  return typeof value
+}
+
+/**
+ * 归一化一个 content 数组。
+ * @param content - 有序 content 块（可能是深冻结的）。
+ * @returns 无非法块时 `undefined`（调用方原样透传 decision）；否则新的 content 与改动清单。
+ */
+function normalizeContent(content) {
+  if (!Array.isArray(content)) return undefined
+  const found = []
+  content.forEach((block, index) => {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text !== 'string') {
+      found.push({ index, block })
+    }
+  })
+  if (found.length === 0) return undefined
+  const next = content.slice()
+  for (const { index, block } of found) next[index] = { ...block, text: coerceText(block.text) }
+  return { content: next, found }
+}
+
+/* -------------------------------------------------------------------- apply */
+
+/**
+ * Install the guard.
+ * @param ctx - agent-scoped services (`tools`, `logger`).
+ * @param config - mode / warnChars.
+ */
+function apply(ctx, config = {}) {
+  const mode = config.mode ?? 'coerce'
+  if (mode === 'off') return
+  const warnChars = Number.isFinite(config.warnChars) ? Math.max(0, config.warnChars) : 160
+
+  /**
+   * 归一化一段 content 并记账；没有非法块返回 `undefined`。
+   * @param where - 诊断里的位置描述（工具名 + callId）。
+   */
+  const normalize = (content, where) => {
+    const normalized = normalizeContent(content)
+    if (normalized === undefined) return undefined
+    const shapes = normalized.found.map(({ index, block }) => `content[${index}].text=${shapeOf(block.text)}`).join('、')
+    const diagnosis =
+      `${where} 的 content 里有非字符串 text（${shapes}）：DSH 只做无损 JSON 快照，原样发给 provider 会被拒` +
+      `（DeepSeek Messages: messages[N].content: invalid type: sequence, expected a string），并且会落进会话日志毒掉整个会话。` +
+      `请把 render() 里的 text 写成 [ ... ].join('\\n')。`
+    if (mode === 'block') return { block: diagnosis }
+    const preview =
+      warnChars === 0 ? '' : ` 片段：${normalized.content[normalized.found[0].index].text.slice(0, warnChars).replace(/\n/gu, ' ⏎ ')}`
+    ctx.logger?.warn?.(`tool-content-guard(coerce): 已强制字符串化 — ${diagnosis}${preview}`)
+    return { content: normalized.content }
+  }
+
+  ctx.on(
+    'tools/post-execute',
+    async (exec, result, next) => {
+      const decision = await next()
+      // 只处理「接受」且没被换 value 的路径；block/失败原样透传。
+      if (decision?.kind !== 'accept' || Object.hasOwn(decision, 'value')) return decision
+      const where = `工具 ${exec?.name ?? '(unknown tool)'}${exec?.callId === undefined ? '' : `（callId ${exec.callId}）`}`
+      const verdict = normalize(decision.content ?? result?.content, where)
+      if (verdict === undefined) return decision
+      if (verdict.block !== undefined) {
+        ctx.logger?.warn?.(`tool-content-guard(block): ${verdict.block}`)
+        return { kind: 'block', feedback: [{ type: 'text', text: `Error: ${verdict.block}` }] }
+      }
+      return { ...decision, content: verdict.content }
+    },
+    { prepend: true },
+  )
+
+  // PTC 子调用的 dispatch 日志走另一条瀑布，同样归一化（它也是持久记录）。
+  ctx.on(
+    'tools/ptc-dispatch-log',
+    async (dispatch, next) => {
+      const content = await next()
+      const verdict = normalize(content, `PTC 子调用 ${dispatch?.name ?? '(unknown tool)'}`)
+      return verdict?.content ?? content
+    },
+    { prepend: true },
+  )
+}
+
+export { Config, apply, coerceText, inject, name, normalizeContent }
+
+/* ------------------------------------------------------------- test surface */
+
+export { elementText }

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tool content guard",
+    "description": "Host-side safety net: a tool whose render() puts a line array into a content block's text gets it joined into a string (prevents the DeepSeek Messages 422 that poisons a session); a dev mode can fail the call instead."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "工具 content 兜底守卫",
+    "description": "host 侧保险：工具 render 把 content 的 text 写成数组时，自动拼成字符串（避免 DeepSeek Messages 422 打毒会话）；开发模式可改为直接判失败。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "dsh-tool-content-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "DSH 插件：host 侧兜底——把工具 content 里非字符串的 `text` 强制字符串化（默认），或在开发模式下直接把这次调用判失败。挂在官方扩展点 tools/post-execute，先让其它策略跑完再归一化，避免 `{\"type\":\"text\",\"text\":[…]}` 这种非法块把 DeepSeek Messages 请求打成 422（invalid type: sequence, expected a string），也避免它落进会话日志、毒掉整个会话。",
+  "license": "MIT",
+  "icon": "./icon.svg",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "cordis",
+    "tools",
+    "post-execute",
+    "content",
+    "text",
+    "guard",
+    "422",
+    "session",
+    "工具兜底"
+  ],
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/hc905/dsh-tool-content-guard.git"
+  },
+  "homepage": "https://gitee.com/hc905/dsh-tool-content-guard",
+  "bugs": {
+    "url": "https://gitee.com/hc905/dsh-tool-content-guard/issues"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "cordis.patch.yml",
+    "index.js",
+    "locale",
+    "test",
+    "icon.svg",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node test/content-guard.test.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/test/content-guard.test.mjs

@@ -0,0 +1,153 @@
+/**
+ * 离线契约测试：不起 host，直接把插件挂到一个 stub ctx 上，然后按 DSH 的
+ * `tools/post-execute` / `tools/ptc-dispatch-log` 调用约定驱动真实监听器。
+ *
+ *   node test/content-guard.test.mjs
+ *
+ * 退出码 0=全部通过，1=有失败。
+ */
+const { apply, coerceText, normalizeContent } = await import(new URL('../index.js', import.meta.url).href)
+
+let failures = 0
+const check = (label, condition, detail) => {
+  if (condition) {
+    console.log(`✓ ${label}`)
+    return
+  }
+  failures += 1
+  console.log(`✗ ${label}${detail === undefined ? '' : ` — ${detail}`}`)
+}
+const equal = (label, actual, expected) =>
+  check(label, JSON.stringify(actual) === JSON.stringify(expected), `实际 ${JSON.stringify(actual)} ≠ 期望 ${JSON.stringify(expected)}`)
+
+/** 挂一次插件，返回按事件名分组的监听器与告警。 */
+function mount(config) {
+  const handlers = []
+  const warnings = []
+  const ctx = {
+    on: (event, listener, options) => handlers.push({ event, listener, options }),
+    logger: { warn: (message) => warnings.push(message) },
+  }
+  apply(ctx, config)
+  return {
+    handlers,
+    warnings,
+    events: handlers.map((item) => item.event),
+    on: (event) => handlers.find((item) => item.event === event),
+  }
+}
+
+const textBlock = (text) => ({ type: 'text', text })
+const accept = (content) => ({ kind: 'accept', content })
+const frozen = (value) => {
+  const freeze = (node) => {
+    if (node !== null && typeof node === 'object') {
+      for (const child of Object.values(node)) freeze(child)
+      Object.freeze(node)
+    }
+    return node
+  }
+  return freeze(value)
+}
+
+/* ---------------------------------------------------------------- 纯函数层 */
+
+equal('coerceText：字符串原样', coerceText('a\nb'), 'a\nb')
+equal('coerceText：行数组 join', coerceText(['a', 'b', '']), 'a\nb\n')
+equal('coerceText：嵌套数组展平', coerceText([['a', 'b'], 'c']), 'a\nb\nc')
+equal('coerceText：混合类型', coerceText(['a', 3, null, undefined, true, { x: 1 }]), 'a\n3\n\n\ntrue\n{"x":1}')
+equal('coerceText：非数组标量', coerceText(42), '42')
+equal('coerceText：null → 空串', coerceText(null), '')
+check('normalizeContent：合法内容返回 undefined', normalizeContent([textBlock('ok'), { type: 'image', attachment: {} }]) === undefined)
+{
+  const content = frozen([textBlock(['a', 'b']), textBlock('keep')])
+  const result = normalizeContent(content)
+  equal('normalizeContent：只重建被改的块', result.found.map((item) => item.index), [0])
+  equal('normalizeContent：改后 text 是字符串', result.content[0].text, 'a\nb')
+  check('normalizeContent：不改写原数组（深冻结安全）', Array.isArray(content[0].text))
+  check('normalizeContent：未改的块保持同一引用', result.content[1] === content[1])
+}
+
+/* --------------------------------------------------------- 监听器 · coerce */
+
+{
+  const mounted = mount({ mode: 'coerce' })
+  equal('注册了 post-execute 与 ptc-dispatch-log 两个监听器', mounted.events, ['tools/post-execute', 'tools/ptc-dispatch-log'])
+  check('post-execute 监听器 prepend（保证在其它策略之后归一化）', mounted.on('tools/post-execute').options?.prepend === true)
+  check('ptc-dispatch-log 监听器 prepend', mounted.on('tools/ptc-dispatch-log').options?.prepend === true)
+  const listener = mounted.on('tools/post-execute').listener
+  const dispatchListener = mounted.on('tools/ptc-dispatch-log').listener
+
+  // 正常 content：原样透传同一个 decision
+  const passThrough = accept([textBlock('fine')])
+  const kept = await listener({ name: 'demo' }, { content: [textBlock('fine')] }, async () => passThrough)
+  check('合法 content：原样透传同一个 decision 对象', kept === passThrough)
+  equal('合法 content：不产生告警', mounted.warnings.length, 0)
+
+  // 事故现场：数组 text
+  const input = frozen({ content: [textBlock(['第 1 行', '第 2 行', '第 3 行'])] })
+  const decision = await listener({ name: 'patent_invalidation_verify', callId: 'call_x' }, input, async () => accept(input.content))
+  equal('数组 text：被拼成字符串', decision.content[0].text, '第 1 行\n第 2 行\n第 3 行')
+  equal('数组 text：decision 仍是 accept', decision.kind, 'accept')
+  equal('数组 text：告警点名叫工具与 callId', mounted.warnings.length === 1 && mounted.warnings[0].includes('patent_invalidation_verify') && mounted.warnings[0].includes('call_x'), true)
+
+  // additionalContexts 必须保留
+  const withContexts = accept([textBlock([1, 2])])
+  withContexts.additionalContexts = [{ marker: 'ctx' }]
+  const preserved = await listener({ name: 'demo' }, { content: withContexts.content }, async () => withContexts)
+  equal('additionalContexts 原样保留', preserved.additionalContexts, [{ marker: 'ctx' }])
+
+  // 别的策略已经 block / 换 value：一律不碰
+  const blocked = { kind: 'block', feedback: [textBlock('denied')] }
+  check('block decision：原样透传', (await listener({ name: 'demo' }, { content: [textBlock(['x'])] }, async () => blocked)) === blocked)
+  const valueReplaced = { kind: 'accept', value: { anything: true } }
+  check('换 value 的 decision：原样透传（注册表会重新 render）', (await listener({ name: 'demo' }, { content: [textBlock(['x'])] }, async () => valueReplaced)) === valueReplaced)
+
+  // 其它 post-execute 策略替换过 content：以 decision.content 为准
+  const replaced = accept([textBlock(['left', 'right'])])
+  const result = await listener({ name: 'demo' }, { content: [textBlock('原始')] }, async () => replaced)
+  equal('以 decision.content 为准（尊重其它策略的替换）', result.content[0].text, 'left\nright')
+
+  // text 是对象/null/数字
+  equal('text=对象：JSON 化', (await listener({ name: 'demo' }, { content: [textBlock({ a: 1 })] }, async () => accept([textBlock({ a: 1 })]))).content[0].text, '{"a":1}')
+  equal('text=null：空串', (await listener({ name: 'demo' }, { content: [textBlock(null)] }, async () => accept([textBlock(null)]))).content[0].text, '')
+
+  // PTC 子调用日志：同样归一化；合法内容原样返回同一数组
+  const dispatchFixed = await dispatchListener({ name: 'read_image', subCallId: 'demo:ptc:1' }, async () => [textBlock(['x', 'y'])])
+  equal('ptc-dispatch-log：数组 text 被拼成字符串', dispatchFixed[0].text, 'x\ny')
+  const dispatchContent = [textBlock('fine')]
+  check('ptc-dispatch-log：合法内容原样返回同一数组', (await dispatchListener({ name: 'read_image' }, async () => dispatchContent)) === dispatchContent)
+}
+
+/* ---------------------------------------------------------- 监听器 · block */
+
+{
+  const mounted = mount({ mode: 'block' })
+  const listener = mounted.on('tools/post-execute').listener
+  const decision = await listener({ name: 'bad_tool', callId: 'call_y' }, { content: [textBlock(['a', 'b'])] }, async () => accept([textBlock(['a', 'b'])]))
+  equal('block 模式：返回 block', decision.kind, 'block')
+  check('block 模式：feedback 是合法 content 块', Array.isArray(decision.feedback) && decision.feedback.every((block) => block.type === 'text' && typeof block.text === 'string'))
+  check('block 模式：feedback 点名叫工具并要求 join', decision.feedback[0].text.includes('bad_tool') && decision.feedback[0].text.includes("join('\\n')"))
+  equal('block 模式：告警 1 条', mounted.warnings.length, 1)
+  const fine = accept([textBlock('ok')])
+  check('block 模式：合法内容仍透传', (await listener({ name: 'ok_tool' }, { content: fine.content }, async () => fine)) === fine)
+}
+
+/* ------------------------------------------------------------------ off */
+
+{
+  const mounted = mount({ mode: 'off' })
+  equal('off 模式：不注册任何监听器', mounted.handlers.length, 0)
+}
+
+/* ---------------------------------------------------------------- 默认值 */
+
+{
+  const mounted = mount({})
+  equal('缺省 config：默认 coerce（挂两个监听）', mounted.handlers.length, 2)
+  const none = mount(undefined)
+  equal('config 为 undefined：默认 coerce', none.handlers.length, 2)
+}
+
+console.log(failures === 0 ? '\nCONTENT GUARD: OK' : `\nCONTENT GUARD: FAIL (${failures})`)
+process.exit(failures === 0 ? 0 : 1)