@bushizhanghan/dsh-publish-gate 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.11.0
+
+- `tool-no-description` (error), `tool-description-thin` (warn), `tool-no-parameters` (error): the host
+  renders name + description + parameters into the prompt and nothing else, so those three fields are the
+  tool's entire specification. A tool with no description is a name in a list; a tool that reads args with no
+  schema never receives them. All nine of my plugins were clean, so this guards the shape rather than a
+  specific crash — the first two fixtures that had `description: 'd'` did fail, which is the point.
+## 0.10.0
+
+- `client-double-load` (warn): the client probe now evaluates the bundle a second time against the same
+  `window`, with a loader that throws on a repeated registration. A bundle inserted by two patches (its own,
+  plus any sidebar plugin that injects `dsh-client-modules`) aborted web boot this way. A window-level guard
+  makes it a no-op, which is what the recommended bundle shape now shows.
 ## 0.9.0
 
 - `checkChangelog()`: `changelog-missing-version` (warn), `changelog-no-versions` (warn), `no-changelog` (info).

package/README.md

@@ -104,6 +104,9 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `tool-present-call-throws` | `presentCall` 抛——调用记录渲染时炸 |
 | `tool-bad-card-kind` | `card: 'generic'` 的 `kind` 不在宿主认识的那一组里（`other` / `execute` / `search` / `read` / `edit` / `delete` / `fetch`）。注册不报错，卡片渲染坏掉——我五个插件一起踩过 |
 | `tool-bad-parameter-type` | `parameters` 里某个 `type` 写错（`"strin"`）。宿主把 `parameters` 渲染进 prompt、但**从不校验**调用值，所以这个 typo 只是悄悄把类型提示弄丢 |
+| `tool-no-description` | 工具没有 description。模型是靠 name + description + parameters 挑工具的，没有描述就只剩名字——工具发出去了，但基本选不中 |
+| `tool-description-thin` | description 少于 30 字符，或者就是把工具名重复一遍。等于没写 |
+| `tool-no-parameters` | execute 读 `args.x`，但整个 `parameters` 都没有。模型拿不到参数清单，不知道该传什么 |
 | `tool-undeclared-param` | `execute` 读了 `args.x`，但 `parameters.properties` 里没有 `x`。模型只能传 schema 声明过的参数，所以这个值在真实调用里永远是 `undefined`——代码在，永远不跑，也不报错。`args.x`、`args['x']`、`const { x } = args` 三种写法都认 |
 | `tool-output-invalid` | 工具返回的东西**自己的 output schema 不收**。宿主每个结果都拿 schema 校验，不匹配就抛 `ToolOutputError`——工具从第一次调用起就不可用，而报错只给一个 JSON 路径，不给是哪行代码返回的。只有点名 `call` 真的调了才检查。这个插件自己踩过：schema 收紧成 `additionalProperties: false`，但有一条错误分支还在返回 `{ ok, error }` |
 | `tool-input-throws` | 把每个声明过的参数**塞一个错类型的值**去调，工具直接抛 `TypeError` 而不是回答。宿主从不拿 `parameters` 校验入参，所以这个值真的会到你的代码里——调用方拿到的是 `The "path" argument must be of type string`，插件日志里没有一行说是哪个工具。这条规则是在自己的工作区里跑出 **12 个真实崩溃** 之后才加的（`session`/`profile`/`casePath`/`workspace` 各一个入口），现在九个插件全绿。默认关：它会把每个工具都调一遍，用 `skip` 点名排除那些会开程序、写文件的 |
@@ -124,6 +127,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `client-apply-throws` | `apply(ctx)` 抛 |
 | `client-no-registration` | `apply` 跑完一次服务都没调用——面板不会出现 |
 | `client-inject-missing-<service>` | `apply` 用了 `ctx.sidebarRightTabs` 但 `inject` 数组里没写它。cordis 不会把没声明的服务给你，于是 `ctx.sidebarRightTabs` 是 `undefined`，`apply` 一碰就抛（或静默什么都没注册） |
+| `client-double-load` | 同一个 bundle 被注入了两次（它自己的 patch 一次，注入 `dsh-client-modules` 的侧边栏插件再一次）。loader 按 id 建工厂，第二次注册直接抛错，整个 Web 启动被中断——不是这个面板没了，是所有面板都没了。用 `if (window.__xLoaded) return; window.__xLoaded = true` 挡一下 |
 | `client-parse-failed` | 文件有语法错误。**单独判**：`SyntaxError` 说明 bundle 本身是坏的，别的报错说明是沙箱不够真，两者别混为一谈 |
 | `client-unavailable` | 子进程没跑起来（warn）——这一层没跑，别把它当干净 |
 
@@ -216,7 +220,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 97 个引擎单测
+node --test                      # 102 个引擎单测
 node test/integration.test.mjs   # 27 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -1201,11 +1201,8 @@ const walkParams = (schema, path) => {
 const ARG_DOT = /\\bargs\\s*\\??\\.\\s*([A-Za-z_$][\\w$]*)/g
 const ARG_INDEX = /\\bargs\\s*\\[\\s*['"]([^'"]+)['"]\\s*\\]/g
 const ARG_DESTRUCTURE = /\\{\\s*([^{}]+?)\\s*\\}\\s*=\\s*args\\b/g
-const undeclaredArgs = (def) => {
-  const props = def?.parameters?.properties
-  if (!props || typeof props !== 'object') return []
-  const declared = Object.keys(props)
-  if (typeof def.execute !== 'function') return []
+const argReads = (def) => {
+  if (typeof def?.execute !== 'function') return []
   let src = ''
   try { src = def.execute.toString() } catch { return [] }
   const reads = []
@@ -1217,7 +1214,13 @@ const undeclaredArgs = (def) => {
       if (/^[A-Za-z_$][\\w$]*$/.test(key)) reads.push(key)
     }
   }
-  return [...new Set(reads)].filter((r) => !declared.includes(r))
+  return [...new Set(reads)]
+}
+const undeclaredArgs = (def) => {
+  const props = def?.parameters?.properties
+  if (!props || typeof props !== 'object') return []
+  const declared = Object.keys(props)
+  return argReads(def).filter((r) => !declared.includes(r))
 }
 const noopService = () => new Proxy(function () {}, {
   get: (target, prop) => {
@@ -1249,6 +1252,8 @@ ctx.tools = {
       hasOutputSchema: Boolean(def && def.output && def.output.schema),
       schema: (def && def.output && def.output.schema) || null,
       parameters: (def && def.parameters) || null,
+      description: typeof def?.description === 'string' ? def.description : '',
+      argReads: argReads(def),
       cardKind: card,
       undeclaredParams: undeclaredArgs(def),
       run: typeof def?.execute === 'function' ? def.execute : null,
@@ -1477,7 +1482,47 @@ export async function checkToolRegistrations(dir, opts = {}) {
     else seen.add(t.name)
 
     if (!t.hasExecute) out.push(F('tool-missing-execute', 'error', `tool "${label}" has no execute function`, "It appears in the model's tool list and throws the moment it is called.", 'Add execute(args, exec).'))
-    if (!t.hasOutputSchema) out.push(F('tool-missing-output-schema', 'warn', `tool "${label}" declares no output.schema`, 'The host validates tool output against output.schema; without one the contract is implicit and a malformed result reaches the caller.', "Add output: { schema: { type: 'json' }, render }."))
+
+    // The description is the only thing that tells the model what the tool is
+    // for. Without one the tool is a name in a list, and a name is not a
+    // specification: it gets called for the wrong thing or not at all.
+    const desc = typeof t.description === 'string' ? t.description.trim() : ''
+    if (!desc) {
+      out.push(
+        F(
+          'tool-no-description',
+          'error',
+          `tool "${label}" has no description`,
+          "The model chooses tools from name + description + parameters. With no description it has to guess from the name alone, so the tool is shipped but effectively unselectable.",
+          'Write one sentence: what it reads, and what it returns.',
+        ),
+      )
+    } else if (desc.length < 30 || desc.toLowerCase() === String(label).toLowerCase()) {
+      out.push(
+        F(
+          'tool-description-thin',
+          'warn',
+          `tool "${label}" has a ${desc.length}-character description`,
+          'A description that only repeats the name adds nothing the model did not already have, so it picks between tools on vibes.',
+          'Say what it takes and what it gives back, in one sentence.',
+        ),
+      )
+    }
+
+    // A tool that reads args but declares no parameters schema: the model is
+    // given no argument list at all, so every field it must send is invisible.
+    if (!t.parameters && Array.isArray(t.argReads) && t.argReads.length > 0) {
+      out.push(
+        F(
+          'tool-no-parameters',
+          'error',
+          `tool "${label}" reads args.${t.argReads[0]} but declares no parameters schema`,
+          'The host renders parameters into the prompt. With none, the model is never told which arguments exist, so it cannot send them.',
+          'Declare parameters: { type: "object", properties: { … } }.',
+        ),
+      )
+    }
+    if (!t.hasOutputSchema) out.push(F('tool-missing-output-schema', 'tool-no-description', 'tool-description-thin', 'tool-no-parameters', 'warn', `tool "${label}" declares no output.schema`, 'The host validates tool output against output.schema; without one the contract is implicit and a malformed result reaches the caller.', "Add output: { schema: { type: 'json' }, render }."))
     if (t.cardKind && typeof t.cardKind === 'object') {
       out.push(F('tool-present-call-throws', 'error', `tool "${label}" presentCall() throws`, `presentCall renders the transcript card and must be total: ${t.cardKind.threw}`, 'Do not read args fields that may be absent.'))
     } else if (typeof t.cardKind === 'string' && !CARD_KINDS.has(t.cardKind)) {
@@ -1786,6 +1831,24 @@ if (!records.parseError) {
     else records.evalError = text
   }
 }
+// The same bundle can reach the page twice: its own patch inserts it, and any
+// sidebar-style plugin that injects dsh-client-modules inserts it again. The
+// loader keys factories by id and throws on the second registration, which
+// aborts web boot. Evaluate a second time against the same window and see
+// whether load() is called again; a window-level guard makes it a no-op.
+records.doubleLoad = null
+if (!records.parseError && records.loaded > 0) {
+  let second = 0
+  const first = globalThis.window.__ModuleLoader__.load
+  globalThis.window.__ModuleLoader__.load = (spec) => {
+    second += 1
+    throw new Error('duplicate factory registration: ' + String(spec && spec.id))
+  }
+  try { new Function(source)() } catch (e) {
+    records.doubleLoad = second > 0 ? String(e && e.message || e) : null
+  }
+  globalThis.window.__ModuleLoader__.load = first
+}
 process.stdout.write('\\n@@PG@@' + JSON.stringify(records))
 process.exit(0)
 `
@@ -1847,6 +1910,17 @@ export async function checkClientRuntime(dir, opts = {}) {
   if (r.applyError) {
     out.push(F('client-apply-throws', 'error', `apply() in ${target} throws: ${String(r.applyError).slice(0, 160)}`, 'Registration happens inside apply(); a throw there leaves the panel unregistered while the host half keeps working.', 'Wrap the failing registration, or fix the cause.'))
   }
+  if (r.doubleLoad) {
+    out.push(
+      F(
+        'client-double-load',
+        'warn',
+        `${target} registers a factory again when evaluated a second time (${String(r.doubleLoad).slice(0, 120)})`,
+        'A client bundle can reach the page twice: its own patch inserts it, and any sidebar-style plugin that injects dsh-client-modules inserts it again. The loader keys factories by id and throws on the second registration, which aborts web boot — the whole panel disappears, not just this one.',
+        'Guard the load call with a window-level flag: if (window.__myPluginLoaded) return; window.__myPluginLoaded = true.',
+      ),
+    )
+  }
   if (r.hasApply && !r.applyError && r.registrations.length === 0) {
     out.push(
       F(
@@ -2234,7 +2308,7 @@ const RULE_ORDER = [
   'missing-field', 'not-esm', 'files-omits-lib', 'files-omits-patch', 'no-exports', 'client-without-export', 'client-without-platform',
   'entry-path-missing', 'bundle-patch-not-declared', 'no-publish-config-access', 'private-field-set', 'publish-config-registry',
   'client-file-missing', 'client-no-module-loader', 'client-parse-failed', 'client-load-not-called',
-  'client-factory-throws', 'client-no-apply', 'client-apply-throws', 'client-no-registration',
+  'client-factory-throws', 'client-no-apply', 'client-apply-throws', 'client-no-registration', 'client-double-load',
   'client-inject-missing-slots', 'client-inject-missing-sidebarRightTabs', 'client-unavailable',
   'no-patch-file', 'no-insert-row', 'insert-missing-name', 'insert-name-mismatch',
   'patch-name-unresolvable', 'no-name-export', 'no-apply-export', 'no-inject', 'require-in-esm',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Pre-publish gate for DSH plugins: manifest, dependencies, artifact, runtime, browser half, traceability and market readiness — plus an input fuzzer that drives every declared parameter with the wrong type. 发布前的七层门禁 + 入参模糊测试。",
   "type": "module",
   "main": "lib/index.js",