dsh-plugin-prompt-tool 2.1.0 → 3.0.0

package/skills/dsh-module/reference.md

@@ -10,7 +10,7 @@
 而 `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` 里能写什么）
 
@@ -20,15 +20,15 @@
 
 | 谓词 | 字段 | 语义与边界 |
 |---|---|---|
-| `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` 决定匹配哪段文本，缺省由层决定（见第三节） |
+| `text` | `keys` / `secondaryKeys`，或单独 `minChars` / `maxChars`（含端点的非负安全整数）；`logic`（any/all/not/notAny）；`mode`（scan/prefix）；`caseSensitive`；`wholeWords`；`useRegex`；`wordBoundary`；`subject` | 关键词与长度同时声明时取交集，minChars 不得大于 maxChars；userMessage 读取本批全部真实用户文本。动作级条件必须声明本通道可用的 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` | 计数。冷启动从持久事件流重建，重启后同一结果 |
+| `count` | `of`（`tool-call`/`tool-result`/`assistant-message`/`assistant-chars`/`user-message`/`turn`）；`per`（`session` 缺省 / `turn`）；`min` / `max` / `every`（**至少写一个**，否则恒真）；`includeCurrent`；`delegated` | 消息类信号按可见历史；tool-call/turn 按完整日志，冷启动按相同视图重建 |
 | `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 条后也放行 |
+| `anchor` | `subject`（userMessage/assistantReasoning/assistantText/toolResult，缺省 assistantReasoning）；`keys`；scan 模式可选既有匹配选项；`after: { action: seed }`；可选正整数 `fallbackAfter` | 当前可见已结算消息确认；缺省 prefix 只按 keys 作 ASCII 忽略大小写的字面前缀匹配，显式 secondaryKeys/caseSensitive/wholeWords/useRegex/logic/wordBoundary 一律拒绝，需这些选项时用 scan。关联只看同规则动作实际投递后的输出；第 N 个含所选内容块的完整输出仍未命中时兜底，中断模型消息不计，省略持续等待 |
 
 拿不到必要事实时谓词返回 `UNAVAILABLE`：只有严格 `true` 才执行；`any` 遇已知 `true`、`all` 遇已知
 `false` 仍可决断。
@@ -36,123 +36,150 @@
 ## 二、动作（`then` / `else` 里能写什么）
 
 `then` 是非空数组；每个动作要有唯一非空 `id` 与合法 `kind`。动作级分支写成 `{ if, then, else }`
-节点嵌在数组里，可嵌套。`else` 结构上保证必有一支命中。
+节点嵌在数组里，可嵌套。else 必须有对应 if；必要事实未知时两支都不执行。
 
 | 动作 | 执行点 | 主要字段 | 失败时 |
 |---|---|---|---|
-| `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` | 原样返回；只删不增 |
+| `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-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 层 | 保持原结果 |
 | `request-params` | `agent/request` 下游 | `patch`（浅合并）、`unset`（`{键: 期望值}`）、`replace`（整体替换） | 保持原请求配置 |
+| `stream-output` | llm/stream | mode（pass 缺省 / replace）、text（替代正文） | 保持原流 |
 | `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` 上；它数的是「本动作本轮生效几次」，
+- 名单类参数（allow/deny/sources）写成逗号分隔字符串或字符串数组都接受。
+- 工具可见面的 `allow` 与 `deny` 可以同时给：对齐官方 `ToolRestriction`，先按 `allow` 保留、再按 `deny` 剔除。
+- `maxPerTurn`（正整数）用在 `assembly` / `tool-gate` / `tool-result` / `append-context` / `request-params` /
+  `inbox-prepend` / `pre-step-filter` 上；它数的是「本动作本轮生效几次」，
   与 `count` 谓词（数持久事件）是两回事。
-- `guard`、`complete`、`suppressRuntimeContext` 是**固定注册效果**：所在规则不带 `if`（注册期即生效）。
+- `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 的规则
+  - id: no-web
     then:
-      - id: deny-at-execution
-        kind: guard
-        mask: { deny: [web_search, web_fetch] }
+      - id: hide-web
+        kind: tool-visibility
+        deny: [web_search, web_fetch]
         reason: 本模块不开放联网工具
 ```
 
-`guard` 注册在 **agent scope** 上，会话原有预设装的行也归它裁决——这是模块禁用官方工具的硬手段。要**收窄**而非禁用，用 `assembly.tools.allow` 白名单（范例见 `modules/tool-surface/module.yml`）；要让禁用传播到子代理，加 `guard.includeSubagents: true`。
+一份 deny 名单同时裁装配目录、tools:sdk 正文，并在 agent scope 注册执行闸——会话原有预设装的行也归它裁决，经 run_code 的子调用同样被拒。要让禁用只作用于子代理，在规则或分支写 if.scope.audience: subagent；不设受众条件则两者都执行。
+
+要收窄，用同一动作的 allow 白名单（范例见 modules/tool-surface/module.yml），并按需声明 discovery：
+
+```yaml
+- id: narrow
+  kind: tool-visibility
+  allow: [pwsh, read, write, edit, glob, grep, todo_write, skill_search, skill_load, tool_search, bash]
+  discovery: { kind: tools }
+  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 共存。
+
+tool-catalog 引用目标必须有 allow；仅支持普通只读插值，`templateEvaluation: 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`） |
+层是官方扩展点，彼此独立，没有跨层运行顺序。规则顶层 layer 是动作未声明 config.layer 时的缺省及展示归属；
+动作显式声明 config.layer 时优先使用动作值（工具、装配、请求类动作自带执行点）。
+
+层字段矩阵（`position` / `dedupe` / `promotion` / `audience` / `modelScope` / `merge` / `order` / `role` / `placeholder`；config 里写 `mergeMode`）由 `/meta` 的 `layerFieldPolicies` 下发，根 `module.yml` 也由同一份 `engine/schema.mjs` 生成；本文不再抄写，避免第三份副本漂移。
+
+| 层 | 官方入口 | 可用策略 | 层内 `params` |
+|---|---|---|---|
+| `pre-step` | `agent/pre-step` 消息批 | static/placeholder/context-activation | — |
+| `system-section` | `ctx.systemPrompt.section` | `static` | `sectionName` `complete` `suppressRuntimeContext` |
+| `runtime-context` | `ctx.systemPrompt.context` | `static` `placeholder` | `contextName` |
+| `agent-request` | `agent/request` | — | request-params 动作的 patch/unset/replace |
+| `llm-stream` | `llm/stream` | — | stream-output 动作的 mode/text |
+| `tool-pipeline` | 仅展示归属（**无注入通道**） | — | 工具链的裁决 / 结果处理 / 追加上下文改用 `tool-gate` / `tool-result` / `append-context` 动作 |
+| `turn-stop` | `agent/turn-stopping` | `static` | — |
+| `subagent-start` | `subagent/start` | `static` | — |
+| `subagent-end` | `subagent/end` | `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 一个）。
+1. 层字段以 `/meta` 的 `layerFieldPolicies` 为准：`position`/`role`/`promotion` 在 `pre-step`，`dedupe` 另支持 `turn-stop` 的 none/session。
+2. 声明式 `config.subject`/`config.match` 已删除；live 条件在规则 `if` 里写 `text.subject` / `anchor.subject`，
+   可选值见 `/meta` 的 `subjects`。按任务内容分档放在 `pre-step`——`subagent/start` 的事件里只有
+   provider 与 id，没有任务文本。
+3. system-section、runtime-context 的普通文本贡献支持规则级 if 和嵌套 `{ if, then, else }`，
+   每次 assembly 在条件文本贡献通道按当前事实求值，不动态重注册段；if.scope.audience 是常见写法。
+   complete / suppressRuntimeContext 属固定注册效果，仍拒绝动态条件分支；complete 表示同 scope 唯一 system 段。
 
-策略 × 层：`static` 全层；`placeholder` 在 `pre-step`、`runtime-context`；`first-turn-anchor` /
-`guide-auto` / `anchor-notice` / `world-book` 在 `pre-step`——后五者都需要每轮求值的 resolver。
+策略 × 层：static 在六个可注入层；placeholder 在 pre-step、runtime-context；
+context-activation 在 pre-step。分类与正文用通用条件和分支组合（模板15），动态内容策略使用既有 resolver。
 
-## 四、模块名与参数
+### 确认后注入
 
-**可写进 `modules` 的名字**（＝ `engine/compositions/source/local/` 下的文件名；下面这份就是完整清单，不必去枚举目录）：
+先用普通 `inject-text` 动作投递自定义锚句，再在嵌套分支写 `if: { anchor: { keys: [已确认], after: { action: seed } } }`，then 使用另一个普通注入动作声明正文与位置。完整示例见包内 `templates/16-custom-fallback.yml`，运行边界见 [引擎指南](../../docs/engine-reuse.md#字词句确认与动作关联)。不要把等待条件放在锚句动作的父级，否则锚句也无法投递。
 
-```
-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
+`after.action` 仅引用同规则 separate 模式的 pre-step/runtime-context/turn-stop 注入动作；缺引用、自引用、循环、投递身份歧义、system-section 与 merged 目标在编译时拒绝。未实际接纳或已不再可见的起点返回 UNAVAILABLE，旧输出和 fork 继承不算当前会话的新投递。当前可见上下文变化后重判；默认等下次正常请求，显式 turn-stop 续跑仍受预算和取消信号约束。
+
+直接匹配当前 pre-step 用户消息用 `text.subject: userMessage`（模板14）；`anchor.subject: userMessage` 看已接纳历史。确认词只写条件，正文只写动作；source.summary 是用户元数据，不生成动态确认/兜底说明。旧 first-turn-anchor、anchor-notice 策略与专属参数已移除，不保留兼容入口，也不自动修改用户模块。
+
+## 四、能力、参数与数据所有权
+
+能力目录以包内 engine/compositions/source/local 的实际文件为准；模块工具统一为 module-file-tools、module-import-tools、module-manifest-tools、module-rule-tools、module-variable-tools。
+
+**模块装配清单**（固定 `assets/manifest.yml`，由 `module_manifest` 解释，工具不认业务字段）：
+
+```yaml
+dirs:
+  - data/10-宪章
+files:
+  - from: assets/templates/agents-template.md
+    to: data/AGENTS.md
+checks:
+  - path: data/02-墨.jsonl
+    kind: jsonl
+    maxBytes: 8388608
 ```
 
-官方组合块已随预设解耦清理：`tool-pwsh`、`tool-fs`、`delegation`、`planning`、`compaction`、
-`tool-web` 这些能力由**会话原有的官方预设**提供。声明了 `rules` 就写 `rule-engine`。
+- `dirs` / `files.to` / `checks.path` 只允许 `data/`；`files.from` 只允许 `assets/`（必须存在，单文件 ≤ 1 MiB）。
+- `checks.kind` ∈ `file`/`text`/`json`/`jsonl`；`maxBytes` 缺省 1 MiB。
+- `action`：`next` 返回第一条缺失（`ok` = 是否已完成），`check` 返回全部检查结果（`ok` = 是否全部通过），`apply` 建目录并只落缺失文件（不覆盖、不删除）。
+- 未知键、未知 kind、越界路径与链接都 fail loud。官方工具、规划、压缩与普通委派由会话原有预设提供，空模块不自动获得这些能力。
 
-**共享参数**四个键，写在 `layerSettings.<层名>.<键>`；层由参数自己的 `storageLayer` 固定：
+共享参数由 `ENGINE_PARAM_DEFINITIONS` 唯一登记，`storageLayer` 决定磁盘路径：主/子模型各有路由与采样键，另含 PTC 呈现（presentAsEnabled、ptcMainMode、ptcSubagentMode）、run_code 环境（runCodeEnvEnabled、runCodeEnvKeys）、Git Bash（toolGitBashEnabled、路径、超时、输出上限）、指令提示（instructionHint 及 promoteOn/includeSubagents/模板）和工具批准（customToolRequireApproval）；完整键、options 与默认值以源码为准，不在摘要抄数量。模型卡在装配期合成 request-params 规则；未配置继承宿主。子代理递归深度归官方 `subagent.maxDepth`，插件不提供。
 
-| 键 | 层 | 说明 |
-|---|---|---|
-| `instructionHint` | `pre-step` | 布尔，默认关：晋升后把官方指令全文换成一次路径提示 |
-| `maxDepth` | `subagent-start` | 数字 / `provider-managed` / 空；只在插件子代理策略启用时约束 |
-| `toolGitBashEnabled` | `tool-pipeline` | 布尔，默认 true：Windows Git Bash 适配行 |
-| `customToolRequireApproval` | `tool-pipeline` | 列表：`shell` `http` `delegate` `fs` `ask-user` |
+- persona.main/subagent：各模块保存 prefix/suffix/complete/includeRuntimeContext，省略继承、空文本清空、false 明确值；rules/_settings.yml 只作校验投影。
+- config.yml.personaSources：main/subagent 各单选官方默认或一个模块 ID，不存正文、不自动启用 rules。只读取所选受众字段，不跨模块逐字段合并；有效官方人设与启用规则的 complete 仍预检，配装失败保留旧状态。
+- variables：模块持久值，覆盖同安装 global；空串保留，删键才回落。普通规则手动建立变量，ST 导入自动登记缺失裸引用为空占位。
+- customTools：shell/http/delegate/fs/ask-user，定义见包内 templates/tools。delegate 走官方工具管线。
+- subagentToolPolicy：授权上限、工具档、角色绑定、任务规则与受控扩权；缺省官方委派。
+- moduleConfigs：已声明共享参数优先于行级配置，不能绕过工具批准。
+- configOrder：模块内规则id→非负序号，排序不修改正文和启停。
+
+## 五、上下文激活与模板
+
+`context-activation` 只在 pre-step 使用。`params.activation.scan` 必须为 batch 或 history；历史只扫描模型可见的真实对话，排除插件/指令/工具回执。`scanDepth:0` 不扫描聊天、变量和递归正文，常驻例外。
+
+匹配共有字段：keys、secondaryKeys、constant、caseSensitive、wholeWords、useRegex、wordBoundary、selectiveLogic。词边界 unicode 为原生字母数字边界，ascii-token 为 ST 单词 ASCII/多词子串规则。副键先开启 activation.selective；P=主键命中数，S=副键命中数，N=原副键项数：
+
+| 具名逻辑 | 条件 |
+|---|---|
+| AND_ANY | P>0 且 S>0 |
+| NOT_ALL | P>0 且 S<N |
+| NOT_ANY | P>0 且 S=0 |
+| AND_ALL | P>0 且 S=N |
 
-模型与采样参数走 `agent-request` 动作的 `patch`，受众由规则 `if.scope` 区分。
+未开 selective 或无副键只要求 P>0；空主键不自动常驻。求值为空的副键仍占一项。activation 还拥有 scanVariables、概率、selectionGroup、评分、sticky/cooldown/delay、递归排除与延迟层级；它的候选组与规则 group/exclusive 不同。模块递归用 contextActivationRecursive，默认 false，池跨模块共享。
 
-**顶层段**各有所有者，互不混写：
+原生模板显式设置 params.templateEvaluation:true。module/global 的 set/get/add/inc/dec 在暂存变更集求值；同卡读到先前写入，单卡只写一个域，所有读取域都参与 CAS。扫描/预览只读。真实执行提交后跨出口和重挂不重放；跨进程崩溃不保证 exactly-once。
 
-- `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` 是插件从它物化的切片。
+旧 world-book/stWorldBook/stWorldBookRecursive/stMacros/stSource、动作 config.variables、扁平 persona 和旧工具能力不作为运行兼容面。重新导入标准 ST 或按 SKILL.md 的转换步骤改写；保留原件和私有记忆，不能靠删来源标记绕过分享保护。旧 API 别名不等于新工具授权。

package/templates/10-pre-step.yml

@@ -4,7 +4,8 @@
 #   - configKind=anchor → 固定锚点序，按模块文件相对顺序排所有 ordered 之前（原 13-anchor）
 # 接入：复制本文件到 模块规则模板目录，或把对象写入 module.yml.rules 数组。
 # 保存前可 POST /api/prompt-tool/settings/rules 做权威校验。
-# audience 为配置项（缺省=公用；main=仅主会话；subagent=仅子代理），模板不锁定。
+# 受众写在规则 if.scope.audience（main/subagent）；不设置即公用。
+# 如需 {{WHO}}，先在工作台的模块变量卡手动建立 WHO；本模板不自动登记变量。
 id: example-pre-step
 name: 示例：消息批注入
 enabled: false
@@ -30,6 +31,4 @@ then:
         value: example-pre-step
       text: |
 
-      variables:
-        WHO: ''
       params: {}

package/templates/14-first-turn-anchor.yml

@@ -1,31 +1,27 @@
-# 模板：首句锚点（strategy=first-turn-anchor）
-# 首条真实用户消息后按任务类型（build / inspect / deep）注入锚句，每会话一次。
-# 纯净模板：参数全部留空，由用户自定义；锚句与分类正则由模板或用户配置提供，引擎不提供默认正文。
-# 提示：把本文件放入 模块规则模板目录，或把对象写入 module.yml.rules 数组。
+# 直接匹配真实用户消息，再以普通动作注入自定义正文。
+# 确认词与正文由用户填写；复制分支可表达不同任务的注入规则。
 id: example-first-turn-anchor
-name: 示例：首句锚点
+name: 示例：匹配后注入
 enabled: false
 layer: pre-step
+if:
+  text:
+    subject: userMessage
+    keys: [自定义触发词]
 then:
   - id: inject
     kind: inject-text
     config:
       id: example-first-turn-anchor
       layer: pre-step
-      strategy: first-turn-anchor
+      strategy: static
       position: after-user
       dedupe: session
       configKind: ordered
       order: 0
       role: user
       mergeMode: separate
-      sourceKind: ''
+      sourceKind: plugin
       form: notice
       params:
-        useCustom: false
-        text: "" # 自定义锚文本（useCustom=true 时固定注入）
-        buildPattern: "" # 构建任务正则；留空 = 该分类不生效
-        complexPattern: "" # 复杂任务正则；留空 = 该分类不生效
-        firstTurnBuild: "" # 构建任务锚句（留空 = 不注入该类别锚句）
-        firstTurnInspect: "" # 排查任务锚句（留空 = 不注入该类别锚句）
-        firstTurnDeep: "" # 复杂设计锚句（留空 = 不注入该类别锚句）
+        text: "" # 自定义正文

package/templates/15-guide-auto.yml

@@ -1,11 +1,5 @@
-# 复杂任务判定 fallback 复用锚定卡的 complexPattern；长度判定仅使用显式 complexMinChars；未设置时不按长度分类
-# 简单任务自动引导句（留空 = 不注入该类别引导）
-# 复杂任务自动引导句（留空 = 不注入该类别引导）
-
-# 模板：每轮引导（strategy=guide-auto）
-# 晋升后每轮用户消息后按复杂度注入弱/深度引导；modelScope=flash 表示仅 flash 模型会话注入。
-# 纯净模板：参数全部留空，由用户自定义；引导句由模板或用户配置提供，留空不注入。
-# 提示：把本文件放入 模块规则模板目录，或把对象写入 module.yml.rules 数组。
+# 模板：按当前批次全部真实用户文本选择引导；正文留空，由用户填写后启用。
+# minChars/maxChars 含端点；复杂度由正则或长度分支表达，无专用策略参数。
 id: example-guide-auto
 name: 示例：每轮引导
 enabled: false
@@ -17,24 +11,34 @@ if:
     - phase:
         promoted: true
         includeSubagents: false
+    - text:
+        subject: userMessage
+        minChars: 1
 then:
-  - id: inject
-    kind: inject-text
-    config:
-      id: example-guide-auto
-      layer: pre-step
-      strategy: guide-auto
-      position: after-user
-      dedupe: batch
-      configKind: ordered
-      order: 10
-      role: user
-      mergeMode: separate
-      sourceKind: ''
-      form: notice
-      params:
-        useCustom: false
-        text: ""
-        guideWeak: ""
-        guideDeep: ""
-        complexMinChars: 120
+  - if:
+      any:
+        - text:
+            subject: userMessage
+            keys: ['复杂|重构|排查'] # 按需替换分类表达式
+            useRegex: true
+        - text:
+            subject: userMessage
+            minChars: 121
+    then:
+      - id: deep-guide
+        kind: inject-text
+        config:
+          layer: pre-step
+          strategy: static
+          position: after-user
+          dedupe: batch
+          text: "" # 复杂任务引导
+    else:
+      - id: weak-guide
+        kind: inject-text
+        config:
+          layer: pre-step
+          strategy: static
+          position: after-user
+          dedupe: batch
+          text: "" # 简单任务引导

package/templates/16-custom-fallback.yml

@@ -1,35 +1,47 @@
-# 模板：自定义锚词兜底注入（strategy=custom-fallback）
-# 首轮推理命中锚定确认词后注入一次；未命中最多两轮兜底。确认词集合 anchorWords 由
-# writePreset 从锚句自动派生（firstTurnWord 空时）；显式 firstTurnWord 覆盖派生。
-# 两者都为空 = 不做词确认，只走未命中兜底注入（引擎不内置确认词）。
-# 提示：把本文件放入 模块规则模板目录，或把对象写入 module.yml.rules 数组。
+# 先投递锚句，仅确认该次投递后的模型推理，再注入正文。
+# 默认持续等待；需要兜底时在 anchor 下显式添加 fallbackAfter: N。
+# 默认等待下一次正常请求；续跑通过既有 turn-stop 规则显式配置。
 id: example-custom-fallback
-name: 示例：自定义锚词兜底注入
+name: 示例：锚句确认后注入
 enabled: false
 layer: pre-step
-if:
-  all:
-    - phase:
-        promoted: true
-        includeSubagents: false
-    - anchor:
-        keys: []
-        fallbackAfter: 1
 then:
-  - id: inject
+  - id: seed
     kind: inject-text
     config:
-      id: example-custom-fallback
+      id: example-custom-fallback-seed
       layer: pre-step
-      strategy: anchor-notice
-      position: before-all
+      strategy: static
+      position: after-user
       dedupe: session
       configKind: ordered
-      order: 20
+      order: 0
       role: user
       mergeMode: separate
       sourceKind: plugin
       form: notice
       params:
-        text: "" # 注入文本（如 preset.md 内容）；留空 = 不注入
-        firstTurnWord: "" # 锚定确认词（显式覆盖；空 = 自动派生）
+        text: "" # 自定义锚句，要求模型输出约定确认词
+  - if:
+      anchor:
+        subject: assistantReasoning
+        keys: [自定义确认词]
+        after:
+          action: seed
+    then:
+      - id: body
+        kind: inject-text
+        config:
+          id: example-custom-fallback-body
+          layer: pre-step
+          strategy: static
+          position: before-all
+          dedupe: session
+          configKind: ordered
+          order: 20
+          role: user
+          mergeMode: separate
+          sourceKind: plugin
+          form: notice
+          params:
+            text: "" # 自定义正文

package/templates/20-system-section.yml

@@ -1,8 +1,6 @@
 # 模板：system-section 静态 system 段（缓存友好，静态内容优先放这里）
 # order 参考：-100 身份 / 0 persona-prefix / 100-199 工具引导 / 10200 persona-suffix。
-# 人设用法：params.sectionName = deployment:persona-prefix（第一方指导之前）或
-# deployment:persona-suffix（第一方指导之后）时注册为人设段
-# （同名 shadow 全局 persona，模块列表显示「人设」徽标；子代理经 scope 链继承）。
+# 自定义系统段使用自己的 sectionName；官方人设覆盖由独立 persona.main/subagent 卡管理。
 #   - complete: true 让本段成为唯一的 system prompt 段（身份注入、人设后缀、工具指南等
 #     其余 system 段全部被抑制；工具链、运行时上下文与变量仍保留）。同一模块只能有一个，
 #     且与顶层人设的「独占」互斥：写盘前由 bridge 拒绝（400），装配前另有一道兜底校验，
@@ -22,7 +20,6 @@ then:
       mergeMode: merged
       text: |
 
-      variables: {}
       params:
         complete: false
         suppressRuntimeContext: false

package/templates/50-llm-stream.yml

@@ -5,13 +5,7 @@ if:
   scope:
     modelScope: flash
 then:
-  - id: inject
-    kind: inject-text
-    config:
-      id: example-llm-stream
-      layer: llm-stream
-      strategy: static
-      order: 0
-      text: "" # mode=replace 时替代整个模型流的文本
-      params:
-        mode: pass
+  - id: output
+    kind: stream-output
+    mode: pass
+    text: "" # mode=replace 时替代整个模型流的文本

package/templates/60-tool-pipeline.yml

@@ -1,19 +1,21 @@
-# postAction=replace/block 时使用的文本
-
-# 模板：tool-pipeline 工具行为策略（对已注册工具的 pre/post 改写；
-# 自定义工具定义见工具管理区块——tool-pipeline 层筛选可见）。
+# 模板：tool-pipeline 工具行为策略
+#
+# 工具链拆成两个动作、两个执行点：
+#   - `tool-gate`（tools/pre-execute）：allow / deny / ask，只读 decision / reason；
+#   - `tool-result`（tools/post-execute）：accept / replace / block，只读 action / text。
+# 工具名只在共享 names 条件声明。
+# 写错相位的字段在编译期就是未知字段，不会静默失效。
 id: example-tool-pipeline
 layer: tool-pipeline
+if:
+  names:
+    allow: [bash, run_code]
 then:
   - id: before
-    kind: decision
-    phase: pre
+    kind: tool-gate
     decision: allow
-    toolNames: bash,run_code
     reason: 该工具被提示词配置禁用
   - id: after
-    kind: decision
-    phase: post
+    kind: tool-result
     action: accept
-    toolNames: bash,run_code
     text: ""

package/templates/63-append-context.yml

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

package/templates/65-turn-stop.yml

@@ -1,6 +1,6 @@
 # 模板：turn-stop 轮次停止层（命中条件时阻止本轮停止，强制模型续跑一步）
-# 接入：subject 缺省 assistantText（匹配最后一条 assistant 消息文本）；不写 match
-#       即无条件续跑。续跑上限固定在引擎内——每轮 1 次、每会话 3 次，配置关不掉。
+# 接入：条件写在规则 if（本模板用 text）；turn-stop 不再有 config.subject/match。
+#       续跑上限固定在引擎内——每个来源（模块）每轮 1 次 / 每会话 3 次，配置关不掉。
 id: example-turn-stop
 name: 未完成时强制续跑
 layer: turn-stop

package/templates/67-inbox-prepend.yml

@@ -4,8 +4,8 @@
 # 不命中什么都不做。缺省 `target: next-turn`，也可写 `next-step`。
 # 插件来源的消息（含本动作自己插入的那条）永不再次前置，防自触发插队。
 #
-# 判「首轮」用 `session: { type: user/message, present: false }`——还没有任何
-# user/message 事件。注意 `agent/inbox/inserted` 拿不到任务文本本身，所以别在这里
+# 判「首轮」用 `session: { type: user/message, present: false }`——模型**当前可见**
+# 的上下文里还没有 user/message 事件（判据按可见上下文，压缩遮蔽的历史不算数）。注意 `agent/inbox/inserted` 拿不到任务文本本身，所以别在这里
 # 用 `text` 谓词筛任务内容（那是 `pre-step` 层的事，见 70-subagent-maintenance.yml）。
 id: example-inbox-prepend
 name: 首轮前置一条消息