dsh-plugin-prompt-tool 3.0.1 → 3.1.0

package/modules/tool-surface/module.yml

@@ -7,12 +7,15 @@
 # 常驻集只在这里写一次；首轮提示由普通注入动作组合。
 #
 # 解锁的生效时机：声明在每个 model step 前重算，解锁在下一步的模型请求里已经可见。
-# `requireMatch: true` 是刻意的：任一常驻工具缺失（或模型解锁了不存在的名字）就放弃裁剪、
-# 暴露完整目录——收窄错了会让当前工作流调不到工具，比多花上下文严重。
+# `requireMatch: true` 是刻意的，但判据是「名单与装配面整体错位」：常驻名单里的名字
+# **一个都不在**当前装配面时才放弃裁剪、暴露完整目录；只缺一两个（提供方被替换或关闭）
+# 仍照常收窄，缺项只留一条诊断。解锁名不参与这个判定。
 #
 # 工具名必须与**实际装配名**一致：本项目 harness 是 `pwsh`、`edit` + `write`；
 # `bash` 由平台各自提供——Windows 是本模块声明的 `tool-git-bash` 行（Git Bash，`bash -c`），
-# POSIX 是官方持久 bash。写错名字会触发 requireMatch 的 fail-open，表现为「收窄没生效」。
+# POSIX 是官方持久 bash。替换提供方（如 dsh-ops 的 `ops_bash`）属于部署事实，不写进随包名单：
+# 加在部署层模块副本（`$DSH_HOME/.prompt-tool/modules/tool-surface/module.yml`）的 allow 即可；
+# 没装该插件的部署里这个名字不存在，不产生任何影响。
 #
 # 停用即回滚：本模块在 config.yml 的 enabled 里删掉即可，重启后工具面完全恢复。
 
@@ -49,7 +52,7 @@ rules:
           - skill_search
           - skill_load
           - tool_search
-          # 平台各自的 bash 名：装配里没有提供方时这里就是缺失名，收窄整体失效。
+          # 平台各自的 bash 名；替换提供方（如 ops_bash）由部署层名单登记，随包名单只写官方名。
           - bash
         discovery: { kind: tools }
         requireMatch: true
@@ -66,6 +69,6 @@ rules:
               fill: tool-catalog
               position: after-all
               dedupe: session
-              text: 常驻工具：{{RESIDENT_TOOLS}}。缺少所需工具时，先用 {{DISCOVERY_TOOL}} 搜索并解锁。
+              text: 常驻工具：{{RESIDENT_TOOLS}}。缺少所需工具时，先用 {{DISCOVERY_TOOL}} 搜索；要用某个工具，先以 {"toolNames":["<工具名>"]} 解锁——解锁从下一次请求起生效，之后才可调用。
               params:
                 action: narrow-tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-prompt-tool",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "DSH 插件：提示词工具，规范模型的思维链与回答内容，提供 Web UI 编辑 module.yml 与 AGENTS.md，并按 skills 目录注册可开关技能。",
   "license": "MIT",
   "repository": {

package/skills/dsh-module/reference.md

@@ -42,7 +42,7 @@
 |---|---|---|---|
 | `inject-text` | 由 config.layer 决定（**六层可注入**，agent-request/llm-stream/tool-pipeline 只作展示归属） | layer、strategy（static/placeholder/context-activation）、position、dedupe、mergeMode、role、order、text/texts、params、templateFile、configKind | 空正文不生成投递；变量赋值模板另按显式求值事务处理 |
 | `assembly` | `system-prompt/assemble` 下游 | `target.sections`（`add`/`remove` **或** `keep`）、`target.contexts`（`add`/`remove` **或** `clear`，二者互斥——并存编译期拒绝）；`target.tools` 已移除 | 返回未改动的装配 |
-| `tool-visibility` | system-prompt/assemble 下游 | allow 与/或 deny（先保留再剔除）、requireMatch（仅 allow）、discovery（{ kind }；tool/key 可选，只作断言）；受众归 scope，提示归普通注入动作 | 呈现面失败保留原装配；执行闸失败留痕，不静默放行 |
+| `tool-visibility` | system-prompt/assemble 下游 | allow 与/或 deny（先保留再剔除）、requireMatch（仅 allow；名单全缺才放宽）、discovery（{ kind }；tool/key 可选，只作断言）；受众归 scope，提示归普通注入动作 | 呈现面失败保留原装配；执行闸失败留痕，不静默放行 |
 | `tool-gate` | tools/pre-execute | decision（allow/deny/ask）、reason；工具名归 names 条件 | 一律放行——裁决 bug 不卡死调用 |
 | `tool-result` | tools/post-execute | action（accept/replace/block）、text（仅 replace/block）；工具名归 names 条件 | 一律接受——结果处理 bug 不把调用变成失败 |
 | `append-context` | tools/post-execute | text；续跑用 inject-text 的 turn-stop 层 | 保持原结果 |
@@ -86,7 +86,7 @@ rules:
   requireMatch: true
 ```
 
-声明 discovery 的模块必须在 modules 里列出对应适配器行（tools → tool-search），缺行在装配准备期失败。discovery 在首次装配时按 agent 解析适配器，并从持久 tool/call 与 PTC tool/ptc-dispatch 参数回收解锁名（只做加法、跨压缩保留）；工具由适配器行注册，discovery.tool/key 可选、只作断言。提示用同规则普通 inject-text 组合 count（user-message，max: 1）与 session 去重，采用 strategy: placeholder、fill: tool-catalog、params: { action: narrow }。只读 RESIDENT_TOOLS 是引用动作 allow 去 deny 后的逗号名单，DISCOVERY_TOOL 是当前 Agent 的发现适配器工具名；模块 text 控制提示正文，保留自动名单而不复制声明。requireMatch 在任一常驻工具缺失时放弃裁剪、暴露完整目录（fail-open），声明名单不等同实时工具面。allow 的执行面由 guard 兜底，不调用 restrict——restrict 的 allow 只收继承面名字，而全局 schemas 视图会漏预设/祖先层工具，局部 allow 反而会把它们裁掉；deny 才用 restrict + guard。PTC 下 tools 数组只有保留传输 `run_code`，实际可见面是 `tools:sdk` 正文；`run_code` 不写进 allow 也保留，且不参与 requireMatch，因此原生收窄声明可以直接与 PTC 共存。
+声明 discovery 的模块必须在 modules 里列出对应适配器行（tools → tool-search），缺行在装配准备期失败。discovery 在首次装配时按 agent 解析适配器，并从持久 tool/call 与 PTC tool/ptc-dispatch 参数回收解锁名（只做加法、跨压缩保留）；工具由适配器行注册，discovery.tool/key 可选、只作断言。提示用同规则普通 inject-text 组合 count（user-message，max: 1）与 session 去重，采用 strategy: placeholder、fill: tool-catalog、params: { action: narrow }。只读 RESIDENT_TOOLS 是引用动作 allow 去 deny、再按当前可见面过滤后的逗号名单（观测不到工具面时回落声明名单；观测到工具面但一个常驻名都不在时跳过提示），DISCOVERY_TOOL 是当前 Agent 的发现适配器工具名；模块 text 控制提示正文，保留自动名单而不复制声明。requireMatch 只在名单里的名字**一个都不存在**时放弃裁剪、暴露完整目录（fail-open）；缺一两个提供方只是少一个常驻工具，收窄照常生效，替换提供方（如 dsh-ops 的 ops_bash）写进部署层名单。解锁名不参与放宽判定。allow 的执行面由 guard 兜底，不调用 restrict——restrict 的 allow 只收继承面名字，而全局 schemas 视图会漏预设/祖先层工具，局部 allow 反而会把它们裁掉；deny 才用 restrict + guard。PTC 下 tools 数组只有保留传输 `run_code`，实际可见面是 `tools:sdk` 正文；`run_code` 不写进 allow 也保留，且不参与 requireMatch，因此原生收窄声明可以直接与 PTC 共存。
 
 tool-catalog 引用目标必须有 allow；仅支持普通只读插值，`templateEvaluation: true` 拒绝。未知动作引用保存前拒绝，发现适配器不可用则跳过提示并告警。
 

package/templates/80-tool-surface.yml

@@ -3,10 +3,10 @@
 # `tool-visibility` 声明常驻集、目录与 SDK 正文的呈现、执行闸和发现来源。
 # 首轮提示由同规则的普通注入动作组合；常驻名单只写一次。
 #
-# 本模板只带规则、不带 `modules` 声明：装配里没有提供方时 `bash` 就是缺失名，
-# `requireMatch` 反过来把整条收窄废掉——用模板建模块时要自己把提供方行带进装配。
-# 写错名字的后果很隐蔽：allow 里的名字不存在会触发 requireMatch 的 fail-open，
-# 表现为「收窄没生效」而不是报错。
+# 本模板只带规则、不带 `modules` 声明：用模板建模块时要自己把提供方行带进装配。
+# `requireMatch` 只在名单**全部**缺失时放弃裁剪；缺一两个提供方只是少一个常驻工具，
+# 收窄照常生效（提供方被替换或关闭不是声明错位）。替换提供方的名字写进 allow：
+# 随包模板只写官方名，未安装替换插件的部署里该名字不存在，不产生任何影响。
 #
 # 发现适配器由 `tool-search` 行提供（模块必须列该行）；解锁名从持久 `tool/call` 参数回收，
 # 因此下一步请求即可见，压缩遮蔽后仍然保留。
@@ -27,10 +27,11 @@ then:
       - skill_search
       - skill_load
       - tool_search
-      # 平台各自的 bash 名：装配里没有提供方时这里就是缺失名，收窄整体失效。
+      # 平台各自的 bash 名；替换提供方（如 ops_bash）登记在部署层名单里。
       - bash
     discovery: { kind: tools }
-    # 任一常驻工具缺失就放弃裁剪、暴露完整目录（fail-open），避免静默裁成空目录。
+    # 名单里的名字一个都不存在时才放弃裁剪、暴露完整目录（fail-open）；
+    # 部分缺失不触发放宽——提供方被替换或关闭是正常部署差异。
     requireMatch: true
   - if:
       count:
@@ -45,6 +46,6 @@ then:
           fill: tool-catalog
           position: after-all
           dedupe: session
-          text: 常驻工具：{{RESIDENT_TOOLS}}。缺少所需工具时，先用 {{DISCOVERY_TOOL}} 搜索并解锁。
+          text: 常驻工具：{{RESIDENT_TOOLS}}。缺少所需工具时，先用 {{DISCOVERY_TOOL}} 搜索；要用某个工具，先以 {"toolNames":["<工具名>"]} 解锁——解锁从下一次请求起生效，之后才可调用。
           params:
             action: narrow-tools