dsh-plugin-prompt-tool 2.0.1 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-prompt-tool",
-  "version": "2.0.1",
-  "description": "DSH 插件：提示词工具，规范模型的思维链与回答内容，提供 Web UI 编辑 preset.md 与 AGENTS.md，并按 skills 目录注册可开关技能。",
+  "version": "3.0.0",
+  "description": "DSH 插件：提示词工具，规范模型的思维链与回答内容，提供 Web UI 编辑 module.yml 与 AGENTS.md，并按 skills 目录注册可开关技能。",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,9 +10,6 @@
   "type": "module",
   "main": "lib/index.mjs",
   "types": "lib/index.d.mts",
-  "bin": {
-    "prompt-tool-migrate-rules": "lib/migrate-rules.mjs"
-  },
   "exports": {
     ".": {
       "types": "./lib/index.d.mts",
@@ -23,9 +20,11 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": "^22.19.0 || >=24.0.0"
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.0-rc.1"
   },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
@@ -62,35 +61,32 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-agent": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-agent-preset-registry": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-api-remotes": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-store": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-session": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-workspace": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-commands": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-fs": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-package-manifest": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-scope": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-skill": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-skill-filesystem": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-subagent": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-system-prompt": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-tool-subagent": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.1",
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-commands": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-fs": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-settings": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-skill": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-skill-filesystem": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
     "@types/node": "^26.2.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.0",
@@ -109,25 +105,28 @@
     "cordis.patch.yml",
     "LICENSE",
     "modules",
+    "skills",
     "templates",
     "README.md"
   ],
   "scripts": {
     "build": "tsdown",
     "prepare": "tsdown",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "lint": "oxlint src test tsdown.config.ts",
     "test": "node scripts/run-tests.mjs",
     "sync:yaml": "node scripts/sync-yaml-vendor.mjs",
-    "rebuild:preset-template": "node scripts/rebuild-preset-template.mjs",
-    "rematerialize:presets": "node scripts/rematerialize-presets.mjs",
-    "migrate:rules": "node lib/migrate-rules.mjs",
+    "sync:harness": "node scripts/sync-harness-deps.mjs",
+    "rebuild:module-template": "node scripts/rebuild-module-template.mjs",
+    "rematerialize:modules": "node scripts/rematerialize-modules.mjs",
     "repair:profile": "node scripts/repair-profile.mjs",
-    "verify:host": "node scripts/verify-host-contracts.mjs"
+    "verify:harness": "node scripts/sync-harness-deps.mjs --check",
+    "verify:host": "node scripts/verify-host-contracts.mjs",
+    "verify:pack": "node scripts/verify-package.mjs"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
     "@zip.js/zip.js": "2.15.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   }
 }

package/skills/dsh-module/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: dsh-module
+description: 新建、修改、审查 DSH Prompt Tool 模块，或把规则、人设、工具和 SillyTavern 来源转成原生 module.yml；也用于排查启用后未注入、将旧内部上下文/会话变量格式显式转换为原生规则。模块由插件在各 Agent scope 装配，与官方会话预设分开。
+---
+
+# DSH 模块
+
+先确定任务是创建、编辑、审查、导入还是旧格式转换。只读审查不授予修复；用户已经授权的修改直接完成，不额外请求确认。涉及安装、启用新能力、覆盖用户文件或重启服务，遵守会话已有授权和项目边界。
+
+路径基于实际 `$DSH_HOME`。模块定义为 `.prompt-tool/modules/<id>/module.yml`，启用集合在 `.prompt-tool/config.yml`。包内 `engine/`、`templates/`、`modules/` 相对插件包根，不相对本技能目录；可通过已加载插件位置或实际安装信息定位，不猜默认 profile。
+
+## 1. 读取目标与所有者
+
+读取完整 module.yml 与有关资产，确认目录名和 id 一致，保留用户已有修改。不要编辑 `rules/`：它是完整定义的校验投影，手改会被恢复。
+
+| 内容 | 写入位置 |
+|---|---|
+| 条件、动作、正文、规则启停 | rules |
+| 共享模型/能力参数 | layerSettings 的登记层 |
+| 持久模块变量 | 顶层 variables |
+| 全局变量 | 同一 DSH_HOME 的插件 variables.yml，经变量 owner 读写 |
+| 人设正文/选项 | 各模块 persona.main / persona.subagent；rules/_settings.yml 仅作投影 |
+| 主/子人设来源 | config.yml.personaSources 只存单选模块 ID，默认官方 |
+| 自定义工具/子代理授权 | customTools / subagentToolPolicy |
+| 模块私有文件 | memory.md、assets/（只读）、data/（只追加），经 module_file_read/append 显式读写；装配清单走 module_manifest |
+| 用户指令文件 | 原文件与独立指令策略，独立授权通道 |
+
+完成判据：每处改动都有单一 owner，工具操作目标与 UI 编辑模块不混淆。
+
+## 2. 创建最小规则
+
+```yaml
+id: my-module
+name: 我的模块
+version: 1.0.0
+modules: [rule-engine]
+variables: {}
+rules:
+  - id: project-rules
+    enabled: false
+    then:
+      - id: inject
+        kind: inject-text
+        config:
+          layer: system-section
+          strategy: static
+          text: |-
+            按用户确认的项目约束执行。
+```
+
+一条规则有独立总开关；动作 id 在整条规则的 then/else/嵌套树内唯一。if 缺省为无条件，else 必须有对应 if。条件未知时不能以“否定”为由放行。规则级 layer 是动作缺省层与展示归属，不是全局执行阶段。
+
+条件、动作和字段选择查 [reference.md](reference.md)。工具或请求类动作有自身执行点；tool-pipeline 没有 inject-text 通道。普通文本空白保持空，不补未经请求的默认正文。
+
+完成判据：完整候选通过唯一 compileRules 校验，规则启停、受众、层、位置和次数符合请求。静态可解析不等于模型实际收到。
+
+## 3. 变量、人设和上下文激活
+
+普通规则引用的变量需手动在模块变量卡建立；不要扫描正文偷偷登记。空字符串是有效占位，会遮住同名全局值；删除模块键才回落全局。动作 config.variables 已退役。
+
+需要赋值才声明 `params.templateEvaluation: true`，使用 `{{module.set::key::value}}` 或 module/global 的 get/add/inc/dec。一张模板只能写一个域，扫描与预览只读；禁止用 session 表或执行重挂伪装持久事务。
+
+人设正文使用模块内 persona.main/subagent；主会话和子代理各自单选来源，默认官方。来源由独立人设卡下拉选择，config.yml.personaSources 只存模块 ID，不能放正文；选择不自动启用来源模块 rules。仅取所选模块对应受众的字段，不跨模块逐字段合并。省略字段继承、空文本清空、complete:false 解除人设独占；有效官方人设与启用规则的 complete 冲突仍需配装预检。人设不进入规则数组或排序，rules/_settings.yml 的校验投影保持只读。
+
+上下文激活使用 `strategy: context-activation`、`params.activation.scan: batch|history`。关键词、候选组和副键约束的语义查 reference；启停与受众仍归规则。记忆不自动生成常驻规则。
+
+完成判据：变量来源和空值语义明确，人设继承可表达，激活字段无需依赖“来自 ST”才生效。
+
+## 4. 能力与模型工具
+
+只声明任务需要的能力。模型工具目录与能力映射如下：
+
+| 能力 | 工具 |
+|---|---|
+| module-rule-tools | module_rules_read / module_rules_edit |
+| module-variable-tools | module_variables |
+| module-file-tools | module_file_read / module_file_append |
+| module-manifest-tools | module_manifest |
+| module-import-tools | module_import |
+| tool-config-engine | customTools 声明的工具 |
+
+规则先读完整树与 revisions，再携带 expectedModuleId/expectedRevisions 编辑完整合法规则；关闭标记 settingsChanged，显式启用用 activateRuleId，删除整规则用 rule:null。正文保存不覆盖并发状态，版本冲突先重读。
+
+变量先 list/get 取版本，再 set/delete；set 必须显式字符串，空串不是删除。global 写影响同一安装的所有模块。文件 append 带当前目标身份与显式 path，与规则事务分开；module_manifest 按清单只写 data/、不覆盖。module_import 先预览并完成选择，提交原始 files 与两份预览凭据，默认另存且不自动启用。
+
+共享模型/能力参数以 `ENGINE_PARAM_DEFINITIONS` 为唯一目录，使用登记的 layerSettings 路径：主/子模型路由与采样、PTC 呈现、run_code 环境、Git Bash、指令提示和工具批准都在其中；数量与 options 以源码为准，不抄旧文档的固定键数。也可通过 request-params 动作按受众改请求。官方工具、规划、压缩和普通委派来自官方预设，模块不重声明它们。
+
+完成判据：声明与实际工具注册一致，目标、版本、批准和取消保护没有绕过。
+
+## 5. 导入和显式转换
+
+ST 预设、角色卡、世界书优先经工作台或 module_import 转换。**ST 导入自动登记缺失裸变量为空占位；普通规则不自动登记。** 导入只转换文本和声明，不执行 STscript 或任意来源代码；报告与生成后的 enabled 状态必须一起检查。
+
+用户要求转换旧内部模块时：
+
+1. 读取完整定义并保存用户同意范围内的备份；保留未知资产、记忆与来源证明。
+2. 将旧上下文策略转换为 context-activation，明确 scan；ST 数字副键映射为具名真值逻辑，不能照抄旧 any/not 注释。
+3. 将 stWorldBook 执行字段拆为 activation，把角色/位置/不支持控制项移至 source.original；模块递归声明 contextActivationRecursive。
+4. 将 set/get/add/inc/decvar 经 parser 转为 module/global 操作，启用 templateEvaluation。局部变量无冲突提升到顶层 variables，同名不同值先报告并解决；不建立第三层变量。
+5. 将旧工具与能力改为上表名称；完整规则替换保留分支与未改字段，记忆从 note 副作用分离。
+6. 将扁平 persona 明确分配到 main/subagent，保留省略/空串/false；由用户为两类受众各选择官方或一个模块来源，不因转换自动启用规则或切换来源。
+7. 旧私有记忆标记先核实并把私有内容归回 memory.md；不能单删标记后导出。
+8. 在隔离候选校验与读回，再按授权提交；失败保留原定义。
+
+插件不提供自动迁移器。未知宏、不等价控制或无法证明的行为要明确报告，不能把成功解析当成转换完成。
+
+## 6. 生效与交付
+
+工作台保存和开关走官方插件运行更新；变量内容更新不重挂 Agent。直接手改 module.yml 的实际加载结果需通过重新读取/重建链确认。代码、bundle、patch 更新需要用户重启 DSH；不自行停止正在运行的服务。
+
+验证以实际公共出口为准：层、位置、次数、受众、规则条件、epoch、变量写入与 disposer。读取失败、过期版本、解析拒绝不应改盘；发布失败区分已保存与尚未生效，refreshOnly 不重放写入。
+
+在本仓库开发时遵守 AGENTS.md 的隔离 cwd 和完整 package gates。一次性探针放临时目录，永久测试须满足项目的 seam/独立真值/公共接口准入，不为退役符号写墓碑测试。
+
+完成判据：用户要求的改动、生效验证和失败路径已覆盖，交付明确实际运行过的检查与未验证限制。
+
+## 审查已有模块
+
+按身份、完整规则树、执行点、受众、变量 owner、共享参数归属、能力授权、人设单选来源与 complete 冲突、排序、保存版本逐项核对。纯审查只给事实与改法，不自动把发现转成修复授权。

package/skills/dsh-module/reference.md

@@ -0,0 +1,185 @@
+# 模块参考
+
+由 `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`，或单独 `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` | 消息类信号按可见历史；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` | `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` 仍可决断。
+
+## 二、动作（`then` / `else` 里能写什么）
+
+`then` 是非空数组；每个动作要有唯一非空 `id` 与合法 `kind`。动作级分支写成 `{ if, then, else }`
+节点嵌在数组里，可嵌套。else 必须有对应 if；必要事实未知时两支都不执行。
+
+| 动作 | 执行点 | 主要字段 | 失败时 |
+|---|---|---|---|
+| `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）写成逗号分隔字符串或字符串数组都接受。
+- 工具可见面的 `allow` 与 `deny` 可以同时给：对齐官方 `ToolRestriction`，先按 `allow` 保留、再按 `deny` 剔除。
+- `maxPerTurn`（正整数）用在 `assembly` / `tool-gate` / `tool-result` / `append-context` / `request-params` /
+  `inbox-prepend` / `pre-step-filter` 上；它数的是「本动作本轮生效几次」，
+  与 `count` 谓词（数持久事件）是两回事。
+- `complete` 与 `suppressRuntimeContext` 是**固定注册效果**：所在规则不带 `if`（注册期即生效）。
+
+### 禁用或收窄某个工具
+
+工具的装配面由**会话原有预设**与各模块共同决定，所以「禁用」必须同时落到呈现与执行两层——只做一层会留下可见痕迹：
+
+```yaml
+rules:
+  - id: no-web
+    then:
+      - id: hide-web
+        kind: tool-visibility
+        deny: [web_search, web_fetch]
+        reason: 本模块不开放联网工具
+```
+
+一份 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 时的缺省及展示归属；
+动作显式声明 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. 层字段以 `/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；
+context-activation 在 pre-step。分类与正文用通用条件和分支组合（模板15），动态内容策略使用既有 resolver。
+
+### 确认后注入
+
+先用普通 `inject-text` 动作投递自定义锚句，再在嵌套分支写 `if: { anchor: { keys: [已确认], after: { action: seed } } }`，then 使用另一个普通注入动作声明正文与位置。完整示例见包内 `templates/16-custom-fallback.yml`，运行边界见 [引擎指南](../../docs/engine-reuse.md#字词句确认与动作关联)。不要把等待条件放在锚句动作的父级，否则锚句也无法投递。
+
+`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
+```
+
+- `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。官方工具、规划、压缩与普通委派由会话原有预设提供，空模块不自动获得这些能力。
+
+共享参数由 `ENGINE_PARAM_DEFINITIONS` 唯一登记，`storageLayer` 决定磁盘路径：主/子模型各有路由与采样键，另含 PTC 呈现（presentAsEnabled、ptcMainMode、ptcSubagentMode）、run_code 环境（runCodeEnvEnabled、runCodeEnvKeys）、Git Bash（toolGitBashEnabled、路径、超时、输出上限）、指令提示（instructionHint 及 promoteOn/includeSubagents/模板）和工具批准（customToolRequireApproval）；完整键、options 与默认值以源码为准，不在摘要抄数量。模型卡在装配期合成 request-params 规则；未配置继承宿主。子代理递归深度归官方 `subagent.maxDepth`，插件不提供。
+
+- 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 |
+
+未开 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。
+
+## 六、退役输入的显式转换
+
+旧 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: "" # 简单任务引导