dsh-plugin-prompt-tool 2.0.1 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-prompt-tool",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "DSH 插件：提示词工具，规范模型的思维链与回答内容，提供 Web UI 编辑 preset.md 与 AGENTS.md，并按 skills 目录注册可开关技能。",
   "license": "MIT",
   "repository": {
@@ -109,6 +109,7 @@
     "cordis.patch.yml",
     "LICENSE",
     "modules",
+    "skills",
     "templates",
     "README.md"
   ],
@@ -123,7 +124,8 @@
     "rematerialize:presets": "node scripts/rematerialize-presets.mjs",
     "migrate:rules": "node lib/migrate-rules.mjs",
     "repair:profile": "node scripts/repair-profile.mjs",
-    "verify:host": "node scripts/verify-host-contracts.mjs"
+    "verify:host": "node scripts/verify-host-contracts.mjs",
+    "verify:pack": "node scripts/verify-package.mjs"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",

package/skills/dsh-module/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: dsh-module
+description: 给 DSH 写一个 prompt-tool 模块：一份 $DSH_HOME/.prompt-tool/modules/<id>/module.yml 定义规则（if → then）、注入正文、人设、共享参数、自定义工具与子代理策略。模块由插件在各 Agent 自己的 scope 里装配，启停只由存储根 config.yml 的启用表决定，与官方会话预设互不干涉。Use when 用户要新建/改写/审查一个模块、把规范或人设做成常驻注入、给模块配九层注入与条件动作、让模型多出工具或委派能力、把 GitHub 仓库／CLI／HTTP 服务／文档／SillyTavern 资源移植成模块、或排查模块已启用却不生效、注入没到达模型。
+---
+
+# dsh 模块
+
+最短路径：写 `$DSH_HOME/.prompt-tool/modules/<id>/module.yml` → 把 `<id>` 加进 `$DSH_HOME/.prompt-tool/config.yml` 的 `enabled` → 重启 DSH 服务。
+
+**本技能里的路径相对插件包根，不在本技能目录下**：`engine/`、`modules/`、`templates/` 都在插件包里。包名 `dsh-plugin-prompt-tool`，定位用环境变量 `$env:DSH_PROFILE_DIR`（bash 里读 `$DSH_PROFILE_DIR`），包就在它的 `node_modules/` 下。读包内文件用**文件读取工具**——Desktop 部署下包可能落在 `app.asar` 里，shell、glob、grep、node 都打不开它。找不到包时以 `reference.md` 为准，它是那些源码的摘要。
+
+行为写在 `module.yml` 的 `rules` 里，参数写在 `layerSettings` 里，能力段写在顶层（`persona` / `variables` / `customTools` / `subagentToolPolicy`）——`module.yml` 是唯一要编辑的文件，旁边的 `rules/` 切片由插件从它物化。
+
+一个模块 = 一个目录 `$DSH_HOME/.prompt-tool/modules/<id>/`，`module.yml` 是**唯一完整定义**与恢复依据。`rules/<规则id>.yml`、`rules/_settings.yml`、`rules/variables.yml` 是插件从它物化出的切片，只读；改了会被单向重切回来。
+
+模块不是官方预设：它不进官方预设册、不切换会话预设、也不依赖宿主扫描。装配由插件在**每个 Agent 自己的 scope** 里做，成员由存储根 `$DSH_HOME/.prompt-tool/config.yml` 的 `enabled` 列表决定。所以「这个模块装了什么」与「会话用的是哪个官方预设」是两件互不干涉的事。
+
+先判这次做哪一种，再往下走：
+
+| 你要的效果 | 落点 |
+|---|---|
+| 把规则、规范、人设、提示词注入到某层某个时机 | 第 2～3 步（规则与层） |
+| 让模型多出工具、委派、内容资产、模型参数 | 第 3 步末尾补 `modules` 与能力段 |
+| 把外部项目（仓库／CLI／HTTP／文档／ST 资源）搬进来 | 先读第 6 步的形态表，再回到第 1 步 |
+| 审查一个已有模块 | 直接跳「审查已有模块」 |
+
+**只审不改**：用户要的是判断（「这个定义对不对」「为什么没生效」）时，逐条给依据与改法就收尾——不写盘、不重启、也不顺手「修好」再报告，除非他明确让你改。
+
+## 第 1 步 立文件与身份
+
+```yaml
+# $DSH_HOME/.prompt-tool/modules/my-rules/module.yml
+id: my-rules            # 必须与目录名一致；^[a-z0-9][a-z0-9-]*$，全小写
+name: 我的规则
+version: 1.0.0
+engineCompat: ">=0.4.2"
+description: 一句话说明，只给人看
+modules:                # 这个模块启用哪些引擎能力行
+  - rule-engine         # 声明了 rules 就要它
+rules: []               # 规则在这里；空模块不自动生成正文或规则
+```
+
+- 先解析 `$DSH_HOME` 再动手：PowerShell 读 `$env:DSH_HOME`，bash 读 `$DSH_HOME`；它未设置时插件回落到 `~/.dsh`。别假设默认路径就是现场在用的那个，也别把模块写到别的根。
+- 目录建在存储根 `modules/` 下；包内 `modules/` 是启动时的补建来源（随包分发三个：`ponytail`、`tool-surface`、`skill-surface`），同名用户目录保持原样。
+- 顶层字段：`id` `name` `version` `engineCompat` `description` `modules` `rules` `layerSettings` `persona` `variables` `customTools` `subagentToolPolicy` `configOrder` `moduleConfigs` `meta` `order`。
+
+**完成判据**：目录名与 `id` 一致、`module.yml` 能被解析——工作台模块页能列出它（列表就是 `/meta` 的 `modules`），或只读读取接口能看到。
+
+## 第 2 步 写规则：`if` → `then`
+
+规则字段：`id` `name` `enabled` `layer` `group` `exclusive` `if` `then` `else`。
+
+```yaml
+rules:
+  - id: my-rules-main          # 稳定身份，禁用也要合法；不含 / \ : * ? " < > | 与控制字符
+    name: 规则正文
+    enabled: true
+    layer: system-section
+    then:
+      - id: inject             # 动作 id 在整条规则内唯一（含分支里的）
+        kind: inject-text
+        config:
+          layer: system-section
+          strategy: static
+          order: 190
+          text: |-
+            规则正文……
+```
+
+- `if` 是**只有一个键**的节点：组合算子 `all` / `any` / `not` / `notAny`，或九个谓词之一。`if` 缺省 = 无条件。九个谓词、每个的字段与语义见 `reference.md` 第一节。
+- `then` 非空数组；动作按数组顺序在同一执行点执行，条件只求值一次。
+- 分支写 `else`（承接规则级 `if` 的反面）；一个动作要自己有分支，就把它写成 `{ if, then, else }` 节点嵌在 `then` / `else` 里，可继续嵌套。一个 `else` 结构上保证必有一支命中，适合「两档互斥、总得给一档」。
+- 互斥档位：同模块内同名非空 `group` 里任一规则写 `exclusive: true`，整组最多一条启用。切换要**先关旧档再开新档**，或由工作台显式激活目标卡（它会在一次事务里关掉同组其他卡）。
+- 条件拿不到必要事实时返回 `UNAVAILABLE`：只有严格 `true` 才执行。
+
+**完成判据**：模块保存成功（保存路径会用 `compileRules` 编译完整候选，不合法直接拒绝），或手动编译通过：
+
+```powershell
+node --input-type=module -e "import {compileRules} from './engine/rule-spec.mjs'; import {parse} from 'yaml'; import {readFileSync} from 'node:fs'; const d=parse(readFileSync(process.argv[1],'utf8')); compileRules(d.rules ?? [])" '<module.yml 绝对路径>'
+```
+
+（在仓库根执行；只做校验，不写盘。）
+
+## 第 3 步 选层与动作
+
+**层是官方扩展点，不是一个管线**：九个层彼此独立，没有跨层运行顺序。规则顶层的 `layer` 只用于展示与分组，真正生效的层取**动作**里的 `config.layer`。
+
+| 层 | 真实入口 | 主要用途 |
+|---|---|---|
+| `pre-step` | `agent/pre-step` 消息批 | 每轮/首轮注入、来源过滤、按任务给子代理分档 |
+| `system-section` | `ctx.systemPrompt.section` | 常驻系统段；`params.complete` 可独占整个 system prompt |
+| `runtime-context` | `ctx.systemPrompt.context` | 动态快照（沙箱、审批、委派事实） |
+| `agent-request` | `agent/request` | 改模型请求参数（provider/model/temperature/maxTokens/stop） |
+| `llm-stream` | `llm/stream` | 包装或替代模型输出流 |
+| `tool-pipeline` | `tools/*` | 工具放行/拦截/改写结果 |
+| `turn-stop` | `agent/turn-stopping` | 命中后强制续跑一步（引擎内每轮 1 次、每会话 3 次上限） |
+| `subagent-start` | `subagent/start` | 向新子代理注入上下文 |
+| `subagent-end` | `subagent/end` | 记录或向主会话投递子代理结果 |
+
+三条容易踩的约束：
+
+1. **层字段白名单**：`position` 用在 `pre-step`；`subject` / `match` 用在 `pre-step`、`tool-pipeline`、`turn-stop`、`subagent-start`、`subagent-end`；`audience` 用在 `pre-step`、`system-section`、`agent-request`、`tool-pipeline`。全表见 `reference.md` 第三节。
+2. **注册制层的条件写在规则级 `if`**：`system-section` 与 `runtime-context` 用 `if` 表达条件（走条件文本贡献通道，每次 assembly 求值；`system-section` 配 `if.scope.audience` 是常见写法）；动作级 `{ if, then, else }` 分支用在带逐轮时机的层（`pre-step` 等）。
+3. **通用门写在规则级 `if`**：`audience` / `modelScope` / `promotion` / `subject` / `match` 都在规则 `if` 里；`system-section` 的静态注册 `audience` 是写在动作 `config` 里的唯一例外。
+
+九个动作——`inject-text`、`assembly`、`decision`、`append-context`、`guard`、`sdk-strip`、`request-params`、`inbox-prepend`、`pre-step-filter`——各自的字段、执行点与失败降级见 `reference.md` 第二节。几条不写会后悔的：
+
+- 工具面收窄用 `assembly.target.tools`：`allow` 是**白名单**（没点名即裁掉），`deny` 是黑名单，二者取一。配 `requireMatch: true` 让名单里任一工具缺失时整体放弃裁剪、暴露完整目录——宁可多给上下文，也不静默裁成空目录。
+- 把解锁做到跨请求，靠 `allowFrom: { tool, key }`：从本会话已持久化的 `tool/call` 参数里回收名单。**只能做加法**，永远解不开黑名单；它必须与发现工具成对出现，否则解锁是一次性的。
+- `guard` 是最终拒绝层（`assembly` 只管呈现）：被它点名的工具，即使经 `run_code` 子调用也会在实际执行点被拒。它按**工具名**裁决，`run_code` 作为 PTC 的唯一入口始终可用。
+- 禁用或收窄某个工具要三层同做：呈现裁目录（`assembly.target.tools.deny`）、文本裁声明（`sdk-strip.mask.deny`）、执行层拒绝（`guard.mask.deny`）。`guard` 注册在 agent scope，**会话原有预设装的行也归它裁决**——这是模块禁用官方工具的硬手段；完整写法与最小 YAML 见 `reference.md` 第二节。
+- `pre-step-filter` 的 `sources` 是严格白名单，且同时作用于被领取的消息批：名单要**枚举全部真实 kind**——没写进去的 kind 会连同它的消息一起消失。`modules/skill-surface/module.yml` 里的 14 种 kind 就是一次实测枚举。
+
+**完成判据**：每个动作的字段都落在该层白名单内；条件与通用门都写在规则级 `if`。
+
+## 第 4 步 挂能力与参数
+
+`modules` 声明这个模块启用哪些能力行；模块名就是 `engine/compositions/source/local/` 下的文件名。参数放在 `layerSettings.<层名>.<键>`，公开共享键四个：
+
+| 键 | 归属层 | 作用 |
+|---|---|---|
+| `instructionHint` | `pre-step` | 晋升后把官方指令全文换成一次路径提示（默认关） |
+| `maxDepth` | `subagent-start` | 已启用的插件子代理策略的递归深度 |
+| `toolGitBashEnabled` | `tool-pipeline` | Windows Git Bash 适配行开关 |
+| `customToolRequireApproval` | `tool-pipeline` | 需要用户批准的自定义执行器：shell / http / delegate / fs / ask-user |
+
+模型与采样参数走 `agent-request` 动作的 `patch`，受众用规则的 `if.scope` 区分。
+
+其余能力各有自己的顶层段，互不混写：
+
+- `persona: { prefix, suffix, complete, includeRuntimeContext }` —— 人设；`complete: true` 让它独占总个 system prompt（同一 scope 一个）。
+- `variables: { 名字: 值 }` —— `{{名字}}` 插值源；空字符串是**有意义的占位**，不按「空值删键」处理。局部覆盖写在动作的 `config.variables`。
+- `customTools: [...]` —— 自定义模型工具，五种执行器 `shell` / `http` / `delegate` / `fs` / `ask-user`；结构照 `templates/tools/*.yml` 抄。`shell` 只继承白名单环境变量（`PATH` `HOME` `USERPROFILE` `DSH_*` 等），要透传别的（token、代理）得在工具定义的 `execute.env` 里显式写。
+- `subagentToolPolicy: {...}` —— 子代理工具授权（`ceiling` / `profiles` / `taskRules` / `modelExpansion`）；缺省时子代理按官方委派行为，不受本模块约束。
+
+**完成判据**：每个用到的能力都有对应 `modules` 行；每个 `layerSettings` 键都在上表四个之内；`persona.complete` 若为真，同 scope 内只有它一条独占段。
+
+## 第 5 步 启用与验证
+
+1. 把模块 id 加进 `$DSH_HOME/.prompt-tool/config.yml` 的 `enabled`（工作台模块页的开关也写这里），然后**重启 DSH 服务**——手改 `module.yml` 后同样要重启才加载。
+2. 注入类改动逐条确认到模型真的收到：
+   - 模块被列出且定义有效（工作台模块页 / 只读接口）；
+   - 规则编译通过（保存时的编译就是同一个 `compileRules`）；
+   - 开一个新会话，在系统消息或对话流里核对正文**真的到了模型**——「已启用」不等于「模型收到」；
+   - 工具类改动看工具预览：自定义工具与被放行的工具确实可见，被挡的工具在 `run_code` 子调用里也被拒；
+   - 停用一次并重启，确认贡献干净撤回（已落进会话历史的消息保留）。
+3. 报告时如实区分「跑了哪些验证」与「只是静态检查」：没有真机现场证据的，就说未验证。
+
+**完成判据**：五条里与本次改动相关的都跑过并留下结论；没有把静态可解析当成运行时生效。
+
+## 第 6 步 把外部项目做成模块
+
+先判能搬哪一块——模块不执行第三方代码，能搬的是**用法**与**接口**：
+
+| 来源形态 | 能搬的部分 | 落在哪个能力 |
+|---|---|---|
+| 规范／方法论 | 规则文本 | `inject-text`（`system-section` 或 `pre-step`） |
+| CLI 工具 | 命令用法与约定 | 注入 + `customTools` 的 `shell` 执行器 |
+| HTTP 服务／API | 接口调用 | `customTools` 的 `http` 执行器 + 规则门控 |
+| 文档／手册 | 操作流程 | 技能（放进技能来源根，模型按需加载，不常驻上下文） |
+| 库／SDK | 只有它的命令行入口 | `shell` 执行器；安装需用户批准 |
+| 数据／模型 | 只能被上面几种引用 | 世界书与模块记忆 `memory.md` |
+| 别的 agent 平台插件／MCP | 不能直接搬 | 宿主平面，不是模块能表达的 |
+
+挑能力时逐条问「这个来源为什么需要它」，说不出理由的能力族就别装：多装一族就多一份工具面与复杂度。**完成判据**：能一句话说出「搬哪一块、动哪几个能力、前提是什么」。
+
+SillyTavern 预设、角色卡与世界书走工作台导入，不走手写：导入产物**就是普通模块**（同一目录、同一启用表、无角色专属存储），导入后仍要在启用表里启用才参与装配。
+
+**做不到的事要直说，别硬凑一个能跑的假实现**：
+
+| 要求 | 怎么回 |
+|---|---|
+| 「把这个仓库跑起来／复刻它的运行时」 | 模块不执行第三方代码；能做的是 shell 调它已装的 CLI，或 http 调它的服务 |
+| 「把依赖装上」 | 属于宿主与插件通道，需要用户批准 |
+| 「加一种全新工具类型／新执行器」 | 要写插件（创造模式预设 + `plugin_manager`），模块只能从既有能力里选 |
+| 「加一个新的引擎模块／改门控行为」 | 属于插件开发，模块只能从既有模块库选 |
+| 「改宿主默认行为／全局设置」 | 宿主平面；模块只作用于装了它的 Agent |
+| 「接一个 MCP 服务器」 | 走宿主的配置型 bundle patch |
+| 「把整仓塞进上下文」 | 只提炼规范与接口；整仓进上下文是 token 与权限双重失控 |
+
+## 审查已有模块
+
+逐条核对，每条给出依据（文件与行）：
+
+1. `id` 与目录名一致、符合 `^[a-z0-9][a-z0-9-]*$`；顶层键都在第 1 步那份字段表里。
+2. 规则字段是那九个；动作 id 在整条规则内唯一。
+3. 每个动作的字段都在该层白名单内（回第 3 步）。
+4. 条件与通用门都写在规则级 `if`。
+5. 互斥组同组只有一条启用；换档说明写在 `description`（给人看），正文留给模型。
+6. `layerSettings` 只用了那四个公开键。
+7. 能力声明既存在又必要：`modules` 里的名字都在 `source/local/` 下；用到的 `customTools` / `subagentToolPolicy` / `persona` 都有对应声明。
+8. 手改后重载过（模块在启动时读盘）。
+9. `rules/` 下的切片保持原样——编辑入口是 `module.yml`。
+
+## 相关技能
+
+- 组合行与插件行层面的细节：`editing-cordis-compositions`
+- 需要写新插件或新能力：`cordis-plugin-development`
+- 指令文件（AGENTS.md / CLAUDE.md）正文与开关：那不属于模块，见仓库的指令文件文档

package/skills/dsh-module/reference.md

@@ -0,0 +1,158 @@
+# 模块参考
+
+由 `SKILL.md` 的指针进入：挑条件、挑动作、查层字段、查模块名与参数时读它。
+
+权威来源是源码：`engine/rule-spec.mjs`、`engine/conditions/`、`engine/actions/catalog.mjs`、
+`engine/schema.mjs` 都在**插件包内**；参数表的源头是 `src/shared/engine-params.ts`（只有源码仓库里有，
+装态对应 `lib/` 的编译产物）。本文件是摘要，**冲突时以源码为准**。
+
+**这些路径相对插件包根，不在本技能目录下。** 技能随包分发、装在 `$DSH_HOME/skills/dsh-module/`，
+而 `engine/`、`modules/`、`templates/` 在插件包里。包名 `dsh-plugin-prompt-tool`，定位用环境变量
+`$env:DSH_PROFILE_DIR`（bash 里读 `$DSH_PROFILE_DIR`）——包就在它的 `node_modules/` 下。读包内文件用
+**文件读取工具**：Desktop 部署下包可能落在 `app.asar` 里，shell、glob、grep、node 都打不开它。
+找不到包时以本文件为准，它是源码摘要，只有存疑才需要回源。
+
+## 一、条件谓词（`if` 里能写什么）
+
+`if` 是**单键节点**：要么组合算子，要么一个谓词。缺省即无条件。
+
+组合算子：`all` / `any`（非空数组）、`not`（单节点）、`notAny`（非空数组）。
+
+| 谓词 | 字段 | 语义与边界 |
+|---|---|---|
+| `text` | `keys` / `secondaryKeys` 至少一个非空；`logic`（`any`/`all`/`not`/`notAny`，对齐 ST world_info_logic）；`mode`（`scan` 全文 / `prefix` 词首）；`caseSensitive`；`wholeWords`；`useRegex`（`true` 强制正则 / `false` 强制字面 / 缺省＝只把 `/pattern/flags` 形态当正则）；`stWords`；`subject` | 文本匹配。`subject` 决定匹配哪段文本，缺省由层决定（见第三节） |
+| `phase` | `promoted`（缺省 `true`＝只匹配已晋升；`false`；`'ignore'` 必须同时写 `compacted`）；`compacted`；`promoteOn`（`either`/`tool-call`/`assistant-message`）；`includeSubagents`（缺省 false＝子代理视为已晋升）；`promoteGate` + `reasoningPattern`/`reasoningNegativePattern`/`reasoningFlags`；`maxPromoteSteps`；`promoteAfterFirstResponse` | 晋升相位。**单个节点表达不了「两个相位都命中」**，用 `any` 拼 `{promoted: true}` 与 `{compacted: true, promoted: false}` |
+| `source` | `kind` / `plugin`（字符串或字符串数组，两个都写是**合取**）；`caseSensitive`（缺省 true）；`match`（`exact` 缺省 / `prefix`） | 消息来源。列举多值要析取时用 `any` 显式写两支 |
+| `count` | `of`（`tool-call`/`tool-result`/`assistant-message`/`assistant-chars`/`user-message`/`turn`）；`per`（`session` 缺省 / `turn`）；`min` / `max` / `every`（**至少写一个**，否则恒真）；`includeCurrent`；`delegated` | 计数。冷启动从持久事件流重建，重启后同一结果 |
+| `names` | `allow` / `deny`；`caseSensitive`（缺省 true） | 名称名单：工具名（工具通道）、子代理 provider（`subagent/start`、`subagent/end`） |
+| `session` | `type`（事件类型，如 `user/message`）；`present`（缺省 `false`＝该事件还没有）；`delegated` | 会话态。判「首轮」用 `{type: user/message, present: false}` |
+| `preset` | `presetId` | 当前**挂载**的官方会话预设；取不到时返回 `UNAVAILABLE`（不乐观放行） |
+| `scope` | `audience`（`main`/`subagent`）；`modelScope`（`all` 缺省 / `pro` / `flash`） | 受众与模型范围。这是**唯一**该写这些门的地方 |
+| `anchor` | `keys`（前缀匹配确认词）；`fallbackAfter` | 锚定确认：首条 assistant reasoning 命中 `keys` 即确认；`fallbackAfter: N` 表示 assistant 消息超过 N 条后也放行 |
+
+拿不到必要事实时谓词返回 `UNAVAILABLE`：只有严格 `true` 才执行；`any` 遇已知 `true`、`all` 遇已知
+`false` 仍可决断。
+
+## 二、动作（`then` / `else` 里能写什么）
+
+`then` 是非空数组；每个动作要有唯一非空 `id` 与合法 `kind`。动作级分支写成 `{ if, then, else }`
+节点嵌在数组里，可嵌套。`else` 结构上保证必有一支命中。
+
+| 动作 | 执行点 | 主要字段 | 失败时 |
+|---|---|---|---|
+| `inject-text` | 由 `config.layer` 决定（九层） | `layer`、`strategy`（`static`/`placeholder`/`first-turn-anchor`/`guide-auto`/`anchor-notice`/`world-book`）、`position`、`dedupe`、`mergeMode`、`role`、`order`、`text`/`texts`、`variables`、`params`、`templateFile`、`configKind` | 空正文＝不注册 |
+| `assembly` | `system-prompt/assemble` 下游 | `target.tools`（`allow` **或** `deny`，可加 `requireMatch`、`allowFrom`）、`target.sections`（`add`/`remove` **或** `keep`）、`target.contexts`（`add`/`remove`/`clear`） | 返回未改动的装配（对 tools 即暴露完整目录） |
+| `decision` | `tools/pre-execute` / `tools/post-execute` | `phase`（`pre`/`post`）、`decision`（`allow`/`deny`/`ask`）、`action`（`accept`/`replace`/`block`）、`toolNames`、`text`、`reason` | 一律放行／接受——裁决 bug 不卡死调用 |
+| `append-context` | `mode: context` → `tools/post-execute`；`mode: continue` → `agent/turn-stopping` | `mode`、`text` | 保持原结果 |
+| `guard` | 注册期（agent scope） | `mask.allow` **或** `mask.deny`、`includeSubagents`、`reason`、`audience` | 静默不注册（**不**退化成放行以外的东西） |
+| `sdk-strip` | `system-prompt/assemble` 下游 | `mask.allow` **或** `mask.deny` | 原样返回；只删不增 |
+| `request-params` | `agent/request` 下游 | `patch`（浅合并）、`unset`（`{键: 期望值}`）、`replace`（整体替换） | 保持原请求配置 |
+| `inbox-prepend` | `agent/inbox/inserted`（emit，无 next） | `target`（`next-turn` 缺省 / `next-step`）、`text` | 不命中即什么都不做 |
+| `pre-step-filter` | `agent/pre-step` 下游 | `sources` **或** `keepKinds`（互斥，未声明即不过滤）、`blockPlugins`（正交，空＝关闭） | 异常时保留全部消息 |
+
+通用规则：
+
+- 名单类参数（`allow`/`deny`/`sources`/`toolNames`）写成逗号分隔字符串或字符串数组都接受。
+- `allow` 与 `deny` **取一**（同一声明里二选一）。
+- `maxPerTurn`（正整数）用在 `assembly` / `decision` / `append-context` / `sdk-strip` /
+  `request-params` / `inbox-prepend` / `pre-step-filter` 上；它数的是「本动作本轮生效几次」，
+  与 `count` 谓词（数持久事件）是两回事。
+- `guard`、`complete`、`suppressRuntimeContext` 是**固定注册效果**：所在规则不带 `if`（注册期即生效）。
+
+### 禁用或收窄某个工具
+
+工具的装配面由**会话原有预设**与各模块共同决定，所以「禁用」要在三层同时下手，只做一层会留下可见痕迹：
+
+| 层次 | 动作 | 效果 |
+|---|---|---|
+| 呈现 | `assembly` + `target.tools.deny` | 本次请求的工具目录里没有它 |
+| 文本 | `sdk-strip` + `mask.deny` | `tools:sdk` 段里的声明正文消失 |
+| 执行 | `guard` + `mask.deny` | 真正调不动——经 `run_code` 的子调用同样被拒 |
+
+```yaml
+rules:
+  - id: no-web-presentation
+    then:
+      - id: drop-from-assembly
+        kind: assembly
+        target: { tools: { deny: [web_search, web_fetch] } }
+      - id: strip-sdk-text
+        kind: sdk-strip
+        mask: { deny: [web_search, web_fetch] }
+  - id: no-web-execution   # 固定注册效果：自成一条不带 if 的规则
+    then:
+      - id: deny-at-execution
+        kind: guard
+        mask: { deny: [web_search, web_fetch] }
+        reason: 本模块不开放联网工具
+```
+
+`guard` 注册在 **agent scope** 上，会话原有预设装的行也归它裁决——这是模块禁用官方工具的硬手段。要**收窄**而非禁用，用 `assembly.tools.allow` 白名单（范例见 `modules/tool-surface/module.yml`）；要让禁用传播到子代理，加 `guard.includeSubagents: true`。
+
+## 三、九层与字段
+
+层是官方扩展点，彼此独立，没有跨层运行顺序。规则顶层的 `layer` 只用于展示、可省略；
+真正生效的层取**动作**里的 `config.layer`（工具、装配、请求类动作自带执行点）。
+
+| 层 | 官方入口 | 层上合法字段 | 可用策略 | 层内 `params` |
+|---|---|---|---|---|
+| `pre-step` | `agent/pre-step` 消息批 | `position` `dedupe` `promotion` `audience` `modelScope` `mergeMode` `order` `role` `subject` `match` | 六种全支持 | — |
+| `system-section` | `ctx.systemPrompt.section` | `audience` `mergeMode` `order` | `static` | `sectionName` `complete` `suppressRuntimeContext` |
+| `runtime-context` | `ctx.systemPrompt.context` | `mergeMode` `order` | `static` `placeholder` | `contextName` |
+| `agent-request` | `agent/request` | `audience` `modelScope` `order` | `static` | `patch` `replace` |
+| `llm-stream` | `llm/stream` | `modelScope` `order` | `static` | `mode`（`pass`/`replace`） |
+| `tool-pipeline` | `tools/pre-execute` `tools/post-execute` | `audience` `modelScope` `order` `subject` `match` | `static` | `toolNames` `preDecision` `denyReason` `postAction` |
+| `turn-stop` | `agent/turn-stopping` | `modelScope` `order` `subject` `match` | `static` | — |
+| `subagent-start` | `subagent/start` | `modelScope` `order` `subject` `match` | `static` | — |
+| `subagent-end` | `subagent/end` | `modelScope` `order` `subject` `match` | `static` | `action`（`observe`/`inject-main`） |
+
+三条边界：
+
+1. 层字段按上表用：`position`/`dedupe`/`role`/`promotion` 在 `pre-step`；`subject`/`match` 在
+   `pre-step`、`tool-pipeline`、`turn-stop`、`subagent-start`、`subagent-end`。
+2. 各层缺省的匹配对象：`pre-step` → `userMessage`、`tool-pipeline` → `toolArgs`、`turn-stop` →
+   `assistantText`、`subagent-*` → `subagentInfo`。按任务内容分档放在 `pre-step`——`subagent/start`
+   的事件里只有 provider 与 id，没有任务文本。
+3. 注册制层（`system-section`、`runtime-context`）的条件写在**规则级 `if`**：它在每次 assembly 走
+   条件文本贡献通道求值，`if.scope.audience` 是常见写法；动作级 `{ if, then, else }` 分支留给带逐轮
+   时机的层。`complete` 是「唯一 system 段」（同一 scope 一个）。
+
+策略 × 层：`static` 全层；`placeholder` 在 `pre-step`、`runtime-context`；`first-turn-anchor` /
+`guide-auto` / `anchor-notice` / `world-book` 在 `pre-step`——后五者都需要每轮求值的 resolver。
+
+## 四、模块名与参数
+
+**可写进 `modules` 的名字**（＝ `engine/compositions/source/local/` 下的文件名；下面这份就是完整清单，不必去枚举目录）：
+
+```
+character-tools, dev-tool-search, filesystem-editor, instruction-hint, persistent-shell-posix,
+rule-engine, run-code-env, session-var-tools, skill-search, subagent-tool-policy,
+tool-bash-disabled, tool-config-engine, tool-git-bash, world-book-tools
+```
+
+官方组合块已随预设解耦清理：`tool-pwsh`、`tool-fs`、`delegation`、`planning`、`compaction`、
+`tool-web` 这些能力由**会话原有的官方预设**提供。声明了 `rules` 就写 `rule-engine`。
+
+**共享参数**四个键，写在 `layerSettings.<层名>.<键>`；层由参数自己的 `storageLayer` 固定：
+
+| 键 | 层 | 说明 |
+|---|---|---|
+| `instructionHint` | `pre-step` | 布尔，默认关：晋升后把官方指令全文换成一次路径提示 |
+| `maxDepth` | `subagent-start` | 数字 / `provider-managed` / 空；只在插件子代理策略启用时约束 |
+| `toolGitBashEnabled` | `tool-pipeline` | 布尔，默认 true：Windows Git Bash 适配行 |
+| `customToolRequireApproval` | `tool-pipeline` | 列表：`shell` `http` `delegate` `fs` `ask-user` |
+
+模型与采样参数走 `agent-request` 动作的 `patch`，受众由规则 `if.scope` 区分。
+
+**顶层段**各有所有者，互不混写：
+
+- `persona`：`prefix` / `suffix` / `complete` / `includeRuntimeContext`。
+- `variables`：`{{键}}` 插值源；空字符串是合法占位（不按空值删键处理）。
+- `customTools`：模型工具定义，执行器五种；结构见仓库 `templates/tools/*.yml`。
+- `subagentToolPolicy`：`ceiling` / `defaultProfile` / `profiles` / `characterBindings` /
+  `taskRules` / `modelExpansion`；缺省时子代理走官方委派行为。
+- `moduleConfigs`：行级 config 直写（优先级低于已声明的共享参数），给参数桥没覆盖的键用。
+- `configOrder`：规则 id → 序号；缺省按声明序 ×10。切片里落在 `rules/_settings.yml`。
+
+**目录形态**：`modules/<id>/module.yml` 是定义；旁边的 `rules/<规则id>.yml`、`rules/_settings.yml`、
+`rules/variables.yml` 是插件从它物化的切片。

package/templates/61-deny-tools-presentation.yml

@@ -0,0 +1,27 @@
+# 模板：工具下架（呈现面）—— assembly 剔除工具条目 + sdk-strip 裁掉 tools:sdk 段正文。
+#
+# 工具的可见面有两处，只删一处会留痕：
+#   - `tools:sdk` 段的声明正文（模型读到的工具说明）→ `sdk-strip` 删文本；
+#   - assembly 的 tools 列表（本次请求实际发出去的目录）→ `assembly` 删条目。
+# 执行层的最终拒绝是**第三件**，见 62-guard-deny-tools.yml：`guard` 是固定注册效果、
+# 不接受规则级 `if`，因此必须自成一条没有 `if` 的规则。
+#
+# 三处名单要逐字一致（assembly.tools.deny / sdk-strip.mask.deny / guard.mask.deny）。
+# 分叉的后果不对称：呈现层漏了只是模型看不见，执行层漏了才是真能调得到。
+id: example-deny-tools
+name: 工具下架（呈现面）
+enabled: false
+then:
+  - id: drop-from-assembly
+    kind: assembly
+    target:
+      tools:
+        deny:
+          - web_search
+          - web_fetch
+  - id: strip-sdk-text
+    kind: sdk-strip
+    mask:
+      deny:
+        - web_search
+        - web_fetch

package/templates/62-guard-deny-tools.yml

@@ -0,0 +1,20 @@
+# 模板：工具下架（执行层最终拒绝）。
+#
+# `guard` 注册在 agent scope 上，是工具真正执行前的最后一道闸：本层与晚到的工具也归它裁决。
+# 它属于**固定注册效果**——不接受规则级 `if`，也不接受 `waterfallPosition`；要按条件开关，
+# 改同名单的呈现面（61-deny-tools-presentation.yml），或另立一条带 `if` 的规则控制别的动作。
+#
+# `deny` 里不能写 `run_code`：它是 PTC 呈现唯一可调用的入口，写进去会在挂载期被拒绝。
+# `includeSubagents` 缺省 false：本 guard 只作用于主会话；要让子代理一并受限，
+# 显式写 `includeSubagents: true`（会沿 scope 链 restrict，同样名单）。
+id: example-deny-tools-guard
+name: 工具下架（执行层）
+enabled: false
+then:
+  - id: deny-at-execution
+    kind: guard
+    mask:
+      deny:
+        - web_search
+        - web_fetch
+    reason: 当前模块不开放联网工具

package/templates/63-append-context.yml

@@ -0,0 +1,22 @@
+# 模板：工具结果之后追加一条 durable user 通知。
+#
+# 与 `decision`(post) 的分工：`decision` 改写的是**工具结果本身**（replace / block），
+# `append-context` 不动结果，只在结果之后追加一条 user 角色通知。
+# 需要模型**再做一步**时改用 `mode: continue`：它走 `agent/turn-stopping` 强制续跑一步，
+# 每轮 1 次、每会话 3 次的上限由引擎内置，不能配置关闭（失控的续跑会把会话卡住）。
+#
+# 条件用规则级 `if.names`（工具名，取自 exec.name）：它与 `decision.toolNames` 是两回事——
+# 后者是动作自己的名单，前者决定这条规则要不要跑。
+id: example-append-context
+name: 工具结果后追加上下文
+enabled: false
+layer: tool-pipeline
+if:
+  names:
+    allow:
+      - web_fetch
+then:
+  - id: note-after-tool
+    kind: append-context
+    mode: context
+    text: 网络结果可能已过期；引用它时说明来源与抓取时间。

package/templates/64-pre-step-filter.yml

@@ -0,0 +1,23 @@
+# 模板：前置步骤（agent/pre-step）注入过滤。
+#
+# 两种白名单模式**互斥**：
+#   - `sources`：严格白名单，只放行列表里的 `source.kind`，**同时作用于本批已领取的消息**。
+#     漏一个 kind 就是静默删掉一段上下文（无告警、无计数），所以它只适合你**枚举过真实 kind**
+#     的场合——`modules/skill-surface/module.yml` 就是这种用法（14 种 kind 的实测枚举）。
+#   - `keepKinds`：保留已领取基线的对象身份 + 这些 kind。实测它什么都不删（claimed 基线
+#     的身份保留规则把所有消息都保住了），所以本模板不推荐它。
+# 未声明任一模式 = 不注册、零开销。
+#
+# `blockPlugins` 是与两者**正交**的另一维度，可共存：仅当 `source.kind` 是插件来源时，
+# 按 `source.plugin` 做大小写不敏感的**精确等值**匹配（不做子串 / 正则 / glob——要覆盖某个
+# 插件就得写全名）。空名单 = 关闭，这与白名单「空 = 全拦」正好相反。
+id: example-pre-step-filter
+name: 前置步骤过滤（按插件屏蔽）
+enabled: false
+layer: pre-step
+then:
+  - id: block-one-plugin
+    kind: pre-step-filter
+    blockPlugins:
+      - example-plugin
+    # sources: ['user', 'agent-instructions']

package/templates/67-inbox-prepend.yml

@@ -0,0 +1,22 @@
+# 模板：首轮向收件箱前置一条消息。
+#
+# `inbox-prepend` 走 `agent/inbox/inserted`（emit 通道，没有 next）：命中即前置，
+# 不命中什么都不做。缺省 `target: next-turn`，也可写 `next-step`。
+# 插件来源的消息（含本动作自己插入的那条）永不再次前置，防自触发插队。
+#
+# 判「首轮」用 `session: { type: user/message, present: false }`——还没有任何
+# user/message 事件。注意 `agent/inbox/inserted` 拿不到任务文本本身，所以别在这里
+# 用 `text` 谓词筛任务内容（那是 `pre-step` 层的事，见 70-subagent-maintenance.yml）。
+id: example-inbox-prepend
+name: 首轮前置一条消息
+enabled: false
+layer: pre-step
+if:
+  session:
+    type: user/message
+    present: false
+then:
+  - id: prepend-first-turn
+    kind: inbox-prepend
+    target: next-turn
+    text: 动手之前先读工作区的 AGENTS.md，再决定改哪里。

package/templates/80-tool-surface.yml

@@ -3,7 +3,7 @@
 # 为什么：工具面实测 **156 个工具、描述合计 46894 字符（≈12K token）**，每个请求都付。
 # 收窄到核心集后只剩约 10 个工具，其余按需解锁。
 #
-# 与 test/engine/declarations/tool-bootstrap.yml 的关键差别：那份原型**只在受控相位收窄**
+# 与已退场的 `tool-bootstrap` 原型的关键差别：那份**只在受控相位收窄**
 # （`promoted: false`），晋升后原样放开；本模板**覆盖全部相位**——晋升后放开等于白省，
 # 而工具描述是每请求的固定开销。若要旧语义，给 `phase` 加 `promoted: false` 并把
 # `compacted` 拆成两条即可。
@@ -23,11 +23,11 @@
 # 就放弃裁剪、暴露完整目录。宁可多给上下文，也不静默裁成空目录——收窄错了会让当前
 # 工作流调不到工具，那是比多花 token 严重得多的故障。
 #
-# **本模板走规则路径，不能声明 `waterfallPosition`**（那是声明 `triggers` 路径的字段，
-# `compileRules` 会以 unknown fields 拒绝）。`assembly` 的改写发生在通道下游结算之后，
-# 与相邻动作的先后由规则顺序与模块顺序决定。若确实需要 `outermost`（`prepend: true`，
-# 保证本动作在普通注册之外先看到装配），改用声明路径（同 test/engine/declarations/
-# tool-bootstrap.yml 的格式）而不是本模板。
+# **本模板走规则路径，不能声明 `waterfallPosition`**（那是声明式路径的字段，规则路径会以
+# unknown fields 拒绝）。`assembly` 的改写发生在通道下游结算之后，与相邻动作的先后由规则
+# 顺序与模块顺序决定。需要 `outermost`（`prepend: true`：保证本动作落在普通注册之外、
+# 先看到装配）时，模块层没有出口——`declared-triggers` 与顶层 `triggers` 都已退役
+# （写进 `modules` 或定义顶层即 409），只能回到插件侧声明。
 id: tool-surface-resident
 name: 工具面收窄（核心文件与任务集）
 enabled: true

package/engine/compositions/library/agent-instructions.yml

@@ -1,9 +0,0 @@
-# module: agent-instructions
-# source: master/packages/bundle/web-app/presets/standard.patch.yml
-# commit: 4878cdabd87d4041bdaff61d04c966883b9fd07a
-# local patches: 0
-
-- id: agent-instructions
-  name: '@deepseek-ai/dsh-agent-instructions'
-  config:
-    maxBytes: 65536

package/engine/compositions/library/command-goal.yml

@@ -1,7 +0,0 @@
-# module: command-goal
-# source: master/packages/bundle/web-app/presets/standard.patch.yml
-# commit: 4878cdabd87d4041bdaff61d04c966883b9fd07a
-# local patches: 0
-
-- id: command-goal
-  name: '@deepseek-ai/dsh-command-goal'

package/engine/compositions/library/compaction.yml

@@ -1,22 +0,0 @@
-# module: compaction
-# source: master/packages/bundle/web-app/presets/standard.patch.yml
-# commit: 4878cdabd87d4041bdaff61d04c966883b9fd07a
-# local patches: 0
-
-- id: compaction
-  name: cordis:group
-  group: true
-  isolate:
-    compaction: true
-    toolResultPruner: true
-  config:
-    - id: compaction-basic
-      name: '@deepseek-ai/dsh-compaction-basic'
-    - id: command-compact
-      name: '@deepseek-ai/dsh-command-compact'
-    - id: tool-result-pruner
-      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
-      config:
-        thresholdChars: 8192
-        headChars: 4096
-        tailChars: 1024

package/engine/compositions/library/delegation-ptc.yml

@@ -1,58 +0,0 @@
-# module: delegation-ptc
-# source: master/packages/bundle/web-app/presets/ptc.patch.yml
-# commit: 4878cdabd87d4041bdaff61d04c966883b9fd07a
-# local patches: 0
-
-- id: delegation
-  name: cordis:group
-  group: true
-  isolate:
-    workflowEngine: true
-  config:
-    - id: tool-subagent-control
-      name: '@deepseek-ai/dsh-tool-subagent-control'
-    - id: tool-subagent-list-agents
-      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
-    - id: tool-subagent
-      name: '@deepseek-ai/dsh-tool-subagent'
-      config:
-        provider: spawn
-        toolName: subagent
-        modelSelectionSettings: true
-        backgroundMode: continuable
-    - id: tool-subagent-fork
-      name: '@deepseek-ai/dsh-tool-subagent'
-      config:
-        provider: fork
-        toolName: subagent_fork
-        backgroundMode: continuable
-    - id: tool-subagent-codex
-      name: '@deepseek-ai/dsh-tool-subagent'
-      disabled: true
-      config:
-        provider: codex
-        toolName: subagent_codex
-        backgroundMode: one-shot
-        maxDepth: provider-managed
-    - id: tool-subagent-claude-code
-      name: '@deepseek-ai/dsh-tool-subagent'
-      disabled: true
-      config:
-        provider: claude-code
-        toolName: subagent_claude_code
-        backgroundMode: one-shot
-        maxDepth: provider-managed
-    - id: workflow-ptc
-      name: '@deepseek-ai/dsh-workflow-ptc'
-      disabled: true
-      config:
-        provider: spawn
-    - id: tool-workflow
-      name: '@deepseek-ai/dsh-tool-workflow'
-      disabled: true
-    - id: tool-ralph
-      name: '@deepseek-ai/dsh-tool-ralph'
-      disabled: true
-      config:
-        subagentProvider: spawn
-        maxRounds: 64