dsh-plugin-prompt-tool 2.0.1 → 2.1.0

package/README.md

@@ -22,7 +22,7 @@ dsh --profile prompt-tool
 
 从 web 模板初始化会让 profile 自带 `@deepseek-ai/dsh-base` 与 `@deepseek-ai/dsh-web-app` 两层，无需额外的 Web 自愈步骤。`--from-default-profile` 只在 profile 不存在时创建，不要对既有 profile 反复执行；已初始化的 profile 不会被改写。
 
-技能**留在各自的来源目录里**（项目 `.dsh/skills`、项目 `.agents/skills`、你添加的技能文件夹、`$DSH_HOME/skills`、`~/.agents/skills`、官方内置）。引用目录复用官方 filesystem provider 发现与监听；管理页按当前会话快照标注生效、同名遮蔽和未确认状态。用户根与显式引用目录中的普通技能均可开关、删除；删除移入对应来源根的回收站，保留资源和恢复记录。插件不分发顶层 `skills/`，新增技能可创建或复制导入；同名导入先确认，成功后不保存技能历史版本。
+技能**留在各自的来源目录里**（项目 `.dsh/skills`、项目 `.agents/skills`、你添加的技能文件夹、`$DSH_HOME/skills`、`~/.agents/skills`、官方内置）。引用目录复用官方 filesystem provider 发现与监听；管理页按当前会话快照标注生效、同名遮蔽和未确认状态。用户根与显式引用目录中的普通技能均可开关、删除；删除移入对应来源根的回收站，保留资源和恢复记录。插件随包分发内置技能（`skills/dsh-module`），安装与每次启动按「只补缺失」补建到 `$DSH_HOME/skills`——已有同名目录保持原样，用户改过或删过的不会被铺回来；新增技能可创建或复制导入，同名导入先确认，成功后不保存技能历史版本。
 
 **停用 = 改写技能文件的调用策略**：模型端写 `disable-model-invocation`、用户端写 `user-invocable`。单端开关只修改该端，保留另一端的最新状态；正文、注释和未知字段保留，提交前校验原文并原子替换。官方工具与可选 `skill_search/skill_load` 都执行调用策略。状态文件 `$DSH_HOME/skills/.system/prompt-tool/skills.yml` 只保存引用目录 `folders`（v4）；技能清单与调用策略均不进入 settings。详见 [docs/skills-management.md](docs/skills-management.md)。
 
@@ -57,7 +57,7 @@ pnpm --dir $Repo migrate:rules -- --root '<DSH_HOME>/.prompt-tool/modules' --cha
 - 🗂️ **完整定义与校验切片**：module.yml 保存完整行为，rules/<id>.yml 保存正文，_settings.yml 保存顺序和启停，variables.yml 保存模板变量；失配单向恢复，不生成旧宿主装配产物。
 - 🧩 **显式互斥**：同模块同组中任一卡声明互斥时，启用目标卡会原子关闭同组其他卡的总开关；重排不改变启用状态。
 - 🖥️ **可拖动悬浮工作台入口**：工作台经官方 `shell.overlay` 渲染悬浮触发器与 body portal 抽屉；按钮可拖动、位置存插件自己的 localStorage、窗口变化自动夹回可见区（不读宿主布局树，已移除 `sidebar.footer.action` 几何探针）；五页（主会话/子代理/工具预览/技能设置/模块）在抽屉内渲染，抽屉用 fixed + z-index 置顶，不被宿主导航栏遮挡
-- 🧪 **条件与内容分离**：`when` 支持组合判断；注入动作支持 `static / first-turn-anchor / guide-auto / anchor-notice / placeholder / world-book`。旧 `custom-fallback` 拆为锚点条件与通知内容。
+- 🧪 **条件与内容分离**：`if` 支持组合判断（另有 `else` 分支）；注入动作支持 `static / first-turn-anchor / guide-auto / anchor-notice / placeholder / world-book`。旧 `custom-fallback` 拆为锚点条件与通知内容。
 - 🛡️ **失败不伤会话**：单条失败跳过 + `warnOnce`；配置错误挂载时 fail loud；`dedupe: session` 持久幂等
 - 🧭 **通用 instruction-hint 引擎**：模块可通过 `strategy: placeholder` 与 `fill: instruction-hint` 提示指令文件存在；实现位于 `engine/instruction-hint.mjs`。`layerSettings.pre-step.instructionHint` 可启用该能力，按模型可见 surface 去重，重挂不重复，被压缩遮蔽后才再次提示
 - 📦 **Bridge 载荷**：JSON 请求统一 32 MiB 硬上限并明确返回 413；角色卡原始图片走 64 MiB 流式通道，按 PNG 魔数识别。
@@ -76,9 +76,9 @@ pnpm --dir $Repo migrate:rules -- --root '<DSH_HOME>/.prompt-tool/modules' --cha
 
 ## Web 客户端结构
 
-每条配置保留一张卡，复用原卡壳、折叠箭头和拖拽样式，指令文件卡置顶。卡内通过“条件 / 动作 / JSON / 设置”平级侧边导航编辑，窄屏改为横向页签，正文归对应注入动作。上移、下移与拖拽按钮位于卡头总开关旁。Linear 风格统一桌面控件为 28px、按钮与下拉为胶囊；短输入按字符宽度收紧，下拉按最长选项文案限宽，数字 96px，正文与 JSON 保留完整编辑宽度。粗指针的 44px 触控目标扩大控件本体，不覆盖外部空白。
+每条配置保留一张卡，复用原卡壳、折叠箭头和拖拽样式，指令文件卡置顶。卡内通过“规则 / JSON / 设置”平级侧边导航编辑，窄屏改为横向页签。**规则面板按条件作用域组织**：规则级 `if` 是一张条件卡，它管住的 `then` 节点在一段竖线作用域里各自成卡——动作卡与分支卡（卡头即「当 ⟨条件⟩ → ⟨动作⟩」）；每张卡默认收起、卡头单行省略给出「条件 → 动作」一览，展开才编辑，`×` 删除整张卡，`then`/`else` 里的分支节点 `{if, then, else}` 可展开编辑、可继续嵌套。上移、下移与拖拽按钮位于卡头总开关旁。Linear 风格统一桌面控件为 28px、按钮与下拉为胶囊；短输入按字符宽度收紧，下拉按最长选项文案限宽，数字 96px，正文与 JSON 保留完整编辑宽度。粗指针的 44px 触控目标扩大控件本体，不覆盖外部空白。
 
-规则编辑器通过 `/rules` 保存局部修改与完整文件版本，保留在途新输入、未知字段和未完成 JSON 草稿。动态注入支持 `when`；固定注册的独占、抑制及安全守卫拒绝不支持的动态条件。具体支持范围见 [引擎复用指南](docs/engine-reuse.md#声明的条件与动作边界)。
+规则编辑器通过 `/rules` 保存局部修改与完整文件版本，保留在途新输入、未知字段和未完成 JSON 草稿。动态注入支持 `if` / `then` / `else`（旧名 `when` / `do` 已退役，撞上会显式报错）；固定注册的独占、抑制及安全守卫拒绝不支持的动态条件。具体支持范围见 [引擎复用指南](docs/engine-reuse.md#声明的条件与动作边界)。
 
 Web 客户端按四层组织：
 
@@ -131,7 +131,7 @@ src/client/
 |---|---|
 | `layerSettings.<层名>` | 模块共享参数；磁盘归属由参数目录的 `storageLayer` 固定，不随 UI 分组改变 |
 | `moduleConfigs` | 行级 config 直写通道（参数桥未覆盖的键：超时/环境白名单/ST 导入等），不锁定覆盖 UI 可管理参数 |
-| `rules` | 独立身份、条件树 `when` 与动作数组 `do`；注入正文与参数归相应动作 |
+| `rules` | 独立身份、条件树 `if` 与动作数组 `then` / `else`；注入正文与参数归相应动作 |
 | `configOrder` | 规则 ID 到序号的完整定义映射；运行切片中为 _settings.yml.rules[id].order，文件名不带序号 |
 
 ### 共享参数一览（全部可选，缺省按对应模块解释）
@@ -220,7 +220,7 @@ UI / 写盘按上表分组；这是展示顺序，不是模型提示词优先级
 - 采样参数（`temperature` / `openai_max_tokens` / `reasoning_effort`）**剥离**——模型参数统一由「模型设置」UI / 宿主默认管理
 - ST 变量：保留可启停的赋值模板，在运行时顺序求值；声明变量在合并和角色卡应用时保持局部绑定
 - ST 管理工具：始终装配 `character-tools`、`session-var-tools` 与 `tool-config-engine`
-- `enable_web_search`：`true` → 额外组装 `tool-web`（fetch 启用）；`false` → 产出三条规则（`assembly` 呈现剔除 + `sdk-strip` 裁 `tools:sdk` 正文 + `guard` 执行层拒绝，共用同一份 `deny: [web_search, web_fetch]`），PTC 下同样生效
+- `enable_web_search`：`true` → 本插件**不再组装 web 工具行**（`tool-web` 已随预设解耦从模块库退役，联网能力由会话原有预设提供），只在转换报告里如实提示；`false` → 产出三条规则（`assembly` 呈现剔除 + `sdk-strip` 裁 `tools:sdk` 正文 + `guard` 执行层拒绝，共用同一份 `deny: [web_search, web_fetch]`），PTC 下同样生效
 - 含有效 `character_book` 条目时自动追加 `world-book-tools` 模块，使导入预设可直接调用世界书管理工具
 - 世界书条目级条件：`delayUntilRecursion`（延迟到递归扫描的层级池）、`useGroupScoring`（组内评分淘汰）、`matchCreatorNotes` / `matchCharacterDepthPrompt`（按需扫描卡片备注与深度提示词）按 ST 语义求值；`characterFilter`（角色/标签过滤）、`automationId`（STscript 自动化）、`outletName` 与向量检索**不实现**，只保留来源事实并在预览卡里逐条告警
 - 触发键里的 ST 宏（例如只存在于 ST 全局 persona 的 `{{user}}`）登记为「模板变量」空占位并产出诊断：未赋值时该键不参与匹配（不会退化成字面量误判），在模板变量里赋值后按既有匹配路径生效

package/engine/actions/catalog.mjs

@@ -6,7 +6,7 @@ export const ACTION_DEGRADE = Object.freeze({
 })
 
 /**
- * 七类动作的声明：**合法事件通道** + **降级语义** + 触发时机。
+ * 九类动作的声明：**合法事件通道** + **降级语义** + 触发时机。
  * `events` 是动作允许注册的官方事件（注册到声明外的事件在挂载期 fail loud）；
  * `services` 是它允许触碰的宿主服务方法（同一纪律的文档面）。
  */

package/engine/actions/inbox-prepend.mjs

@@ -12,8 +12,7 @@ export function prepareInboxPrepend(action, plugin) {
   if (text.length === 0) return
   return (_ctx, { warnOnce, on, collect, take }) => collect(on('agent/inbox/inserted', ({ agent, message } = {}) => {
     try {
-      // 无 session 的 agent 不锚定（与原 `anchor-turn` 的守卫逐条对齐；声明侧见
-      // `test/engine/declarations/anchor-turn.yml` 的 session 谓词）：锚定是**会话**
+      // 无 session 的 agent 不锚定（与原 `anchor-turn` 的守卫逐条对齐）：锚定是**会话**
       // 首轮语义，没有会话就没有「首轮」；缺这条会让匿名/临时 agent 也被插一条合成消息
       // （对拍实测：声明路径多插 2 条）。
       if (agent?.session === undefined) return

package/engine/actions/shared.mjs

@@ -41,8 +41,7 @@ export function createMask(source, label, plugin, allowExtra) {
     allowExtra,
     /**
      * fail-open 兜底开关（**可选**，缺省 false）：原 `tool-bootstrap` 的语义是
-     * 「keep 名单里的工具在本次装配目录里一个都不存在 → 放弃裁剪、暴露完整目录」（声明侧见
-     * `test/engine/declarations/tool-bootstrap.yml` 的 `requireMatch: true`），而原
+     * 「keep 名单里的工具在本次装配目录里一个都不存在 → 放弃裁剪、暴露完整目录」，而原
      * `tool-filter` 的同名场景是**照名单裁成空目录**。两种语义都真实存在，所以这里
      * **不设默认**——要兜底的声明自己写 `requireMatch: true`。把某一个模块的特有语义当成
      * 通用默认，会让另一个声明路径的行为被悄悄改掉（这正是对拍抓出来的）。

package/engine/branch.mjs

@@ -1,5 +1,5 @@
 /**
- * 分支语法的唯一展开器：`if`/`then`/`else` 是当前名，`when`/`do` 是兼容输入。
+ * 分支语法的唯一展开器：只认 `if`/`then`/`else`，旧名 `when`/`do` 由各入口显式拒绝。
  *
  * 规则（`rule-spec.mjs`）与触发器声明（`trigger-spec.mjs`）共用这一份实现——
  * 两套入口必须是同一套语义，否则同一个模块换个入口就换行为。

package/engine/compositions/source/local/instruction-hint.yml

@@ -1,11 +1,10 @@
 # module: instruction-hint
 # source: engine/compositions/source/local/instruction-hint.yml (本地附加,非官方模块)
-# context-gate 的 instructionHint 转换在本模块的归属行——删除前的原始语义见
-# context-gate.mjs:64-66，替换点 :243-248，pre-step 挂载 :226-255：晋升后把
+# 本行承接已退场的 `context-gate` 的 instructionHint 转换：晋升后把
 # agent-instructions 全文换成一次性非命令式 hint，后续全文 dump 丢弃。
 # opt-in：enabled 默认 false（与原 instructionHint 默认 false 同值），由参数桥
 # params.instructionHint（→ 本行 enabled）或本行 config.enabled: true 打开；
-# 相位词汇与 tool-bootstrap / promoted-code-mode 同源（compaction-epoch.mjs）。
+# 相位词汇与 compaction-epoch.mjs 同源。
 #
 # 四个模板必须随行给全（2026-10-05 修）：`instruction-hint.mjs#apply` 的首行是
 #   `if (!enabled || templateOf(source, 'messageTemplate').trim().length === 0) return`

package/engine/conditions/composite.mjs

@@ -70,7 +70,7 @@ export function composite(node) {
   // 组合层必须**转发子谓词的 observe**（B7 T1 的跨能力缺口修复）：两条挂载路径的观察器
   // 接线都按 `when.observe` 过滤（`trigger.mjs` 的 `wireTriggerObservers`），被组合包住的
   // phase / count / session 谓词否则永远收不到活的 `session/event`——状态按 `session.id`
-  // 缓存后不再重扫（`shared.mjs` 的 `sessionMapGet`），判定会停在冷扫那一刻（计数恒旧值、
+  // 缓存后不再重扫（`shared.mjs` 的 `sessionState`），判定会停在冷扫那一刻（计数恒旧值、
   // 相位永不晋升）。`phase` 有 `subscribe: false` 可绕（代价是每次判定冷扫），
   // `count` / `session` 没有该档，所以这条转发是它们唯一的活路。
   const observers = children.filter((child) => typeof child.observe === 'function')

package/engine/conditions/count.mjs

@@ -50,8 +50,7 @@ export function createCountPredicate(options = {}) {
   const min = boundOf(options.min, 'min')
   const max = boundOf(options.max, 'max')
   // 节奏判据（2026-09-22 用户拍板⑤「改用可重建计数」的核心语义）：`every: N` = 每 N 次命中一次。
-  // 原 `progress-reminder` 的 `results % every === 0` 配的是**自增后**的计数
-  // （声明侧见 `test/engine/declarations/progress-reminder.yml` 的 `count.every`），
+  // 原 `progress-reminder` 的 `results % every === 0` 配的是**自增后**的计数，
   // 所以这里必须要求 `count > 0`——否则 `0 % N === 0` 会让第 0 次就命中。
   const every = options.every === undefined
     ? undefined

package/engine/conditions/phase.mjs

@@ -30,8 +30,7 @@ export function createPhasePredicate(options = {}) {
   // 为什么需要它（对拍实测）：原实现把 `compacted` 与 `promoted` 写成**合取**，于是可表达的
   // 原子只有 `P`、`C∧P`、`¬C∧P`——三者在 **¬P 的会话上全为 false**，用 `any`/`all`/`not`/
   // `notAny` 的任何组合都表达不出原 `tool-bootstrap` compaction 回退要的 **`C ∧ ¬P`**
-  // （受控相位 + 已压缩：压缩后回到受控工具集；声明侧见
-  // `test/engine/declarations/tool-bootstrap.yml` 声明 2）。解耦后
+  // （受控相位 + 已压缩：压缩后回到受控工具集）。解耦后
   // `{ compacted: true, promoted: false }` 就是 `C ∧ ¬P`。
   const promotedOption = options.promoted
   if (promotedOption !== undefined && promotedOption !== true && promotedOption !== false && promotedOption !== 'ignore') {

package/engine/conditions/subject.mjs

@@ -78,7 +78,7 @@ export function subjectOf(channel, args, warn, ctx) {
       case 'agent/turn-stopping': return { assistantText: lastAssistantText(args[0]?.agent?.session) }
       // 子代理事件的 `name` = provider（`SubagentRunInfo` 里唯一稳定的分类事实：
       // spawn / fork / acp / codex / claude-code / dsh-sdk）。`names` 谓词读的就是
-      // `payload.name`，因此 `when: { names: { allow: ['fork'] } }` 在此可用。
+      // `payload.name`，因此 `if: { names: { allow: ['fork'] } }` 在此可用。
       // provider 可能缺席（官方注释：已接受的 one-shot 变 ready 或持久 Activation 冷恢复时
       // 提供方未必仍注册）——那时不写键，让 `names` 走 UNAVAILABLE，而不是塞空串当「已知为空」。
       case 'subagent/start':

package/engine/layers.mjs

@@ -359,8 +359,7 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on) {
  *   - `replace: true`：整体替换为 `patch`（不叠加 base，故 `unset` 无比较对象）；
  *   - `unset`：**按值条件删键** —— 仅当合并结果里的值**恰好等于**声明值时删除该键
  *     （`Object.is` 比较）。这来自原 `tool-bootstrap` 剥离 `bootstrapMaxTokens` 的语义
- *     （「仅当解析后的 maxTokens 恰好等于本声明注入的那个值时才删」；声明侧见
- *     `test/engine/declarations/tool-bootstrap.yml` 声明 4 的 `do.unset`），不是"存在即删"
+ *     （「仅当解析后的 maxTokens 恰好等于本声明注入的那个值时才删」），不是"存在即删"
  *     ——模型或其它插件设置的同名参数不会被删。
  *     浅合并做不到删键，故删键必须走显式通道。
  * @param params 提示词配置的 `params`（或动作的等价声明）。
@@ -537,7 +536,7 @@ export function createTurnStopBudget() {
   /**
    * 会话预算条目（`sessionState`：统一访问接口，策略逐条声明）。
    *
-   * 键类型 `session.id`；淘汰策略超限 `clear()` 全清（与迁移前的 `sessionMapGet` 同档：
+   * 键类型 `session.id`；淘汰策略超限 `clear()` 全清（与迁移前的会话态记账同档：
    * 第 `MAX_TRACKED_SESSIONS` 个会话仍会清空整个容器）；**不声明复位**——预算是纯增量、
    * 不可从事件流重建的计数（与 `progress-reminder` 同档），丢失时机必须与迁移前逐字一致，
    * compaction 也不重置它。
@@ -551,7 +550,7 @@ export function createTurnStopBudget() {
 
   const stateOf = (sessionId, turn) => {
     // 对外仍是 `(sessionId, turn)`：按 id 造一次性键宿主，`keyOf` 取的就是 `.id`，与旧的
-    // `sessionMapGet(state, sessionId, …)` 写进同一个槽位、同一个 clear 时机。
+    // 记账写法写进同一个槽位、同一个 clear 时机。
     // 唯一差异在**无 id 的会话**（`sessionId === undefined`）：`sessionState` 刻意不记账
     // （见 shared.mjs），旧写法把 `undefined` 当一个共享槽位。两个调用点（actions.mjs 的
     // append-context 与下方 turn-stop 层）都在 `entry()` 之前守卫 `session?.id === undefined`，

package/engine/rule-spec.mjs

@@ -7,7 +7,7 @@ import { ACTION_EXAMPLES } from './actions/examples.mjs'
 import { PREDICATE_EXAMPLES } from './conditions/examples.mjs'
 import { conjunction, expandActions } from './branch.mjs'
 
-/** 规则字段：`if`/`then`/`else` 是当前名，`when`/`do` 保留为兼容输入（见 pickAlias）。 */
+/** 规则字段：只有 `if`/`then`/`else`；旧名 `when`/`do` 留在名单里，只为把 unknown fields 换成一句「已退役，改用 X」。 */
 const RULE_FIELDS = new Set(['id', 'name', 'enabled', 'layer', 'group', 'exclusive', 'if', 'then', 'else', 'when', 'do'])
 const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
 const nonempty = value => typeof value === 'string' && value.trim().length > 0

package/engine/shared.mjs

@@ -151,24 +151,12 @@ export function keepDisposer(ctx, disposer, label) {
  *  （进程内快路径，真相在 durable 事件流，清空仅触发一次冷扫重建）。 */
 export const MAX_TRACKED_SESSIONS = 4096
 
-/** 按会话 key 取 Map 条目；超限时清空后重建（防 session 数无界增长）。 */
-export function sessionMapGet(map, key, create) {
-  let entry = map.get(key)
-  if (entry === undefined) {
-    if (map.size >= MAX_TRACKED_SESSIONS) map.clear()
-    entry = create()
-    map.set(key, entry)
-  }
-  return entry
-}
-
 /**
  * 会话态声明的统一访问接口（B4 T1 步骤一）。
  *
  * 收敛「每个模块自己维护会话态 Map、自己决定上限与清空策略、自己决定复位时机」，
  * 但**不改变任何既有策略**：键类型、淘汰策略、复位语义逐项由调用方按现状声明，
- * 本函数只把它们收进同一套读写入口。它**不替代** `sessionMapGet`（后者仍是
- * 「按 id + 超限全清」这一档的实现，本函数在 `evict` 缺省且按 id 索引时逐字复用它）。
+ * 本函数只把它们收进同一套读写入口。
  *
  * ## 三个必答项（正好对应现状的三处差异）
  *

package/engine/subagent-tool-policy.mjs

@@ -10,8 +10,8 @@
  * tool-config-engine.yml 及 test/engine/provider-boundary.test.mjs 同一份措辞）：
  *   - 会给模型提供可调用能力（注册工具 / 域 / 服务）的 → 能力提供者；
  *   - 干预流程（改提示词、改装配、裁决、追加）的 → 声明式触发器。
- * 因此本模块**不接入** engine/trigger.mjs：它不订阅装配 waterfall，也没有 when/do
- * 声明，只在 agent 创建时向该 agent 的 scope 注册两个可调用工具。影子工具解决的是
+ * 因此本模块**不接入** engine/trigger.mjs：它不订阅装配 waterfall，也没有声明式
+ * 触发器（`if`/`then` 声明），只在 agent 创建时向该 agent 的 scope 注册两个可调用工具。影子工具解决的是
  * 「子代理能用什么工具」，属于能力面，不是流程干预面。
  *
  * 样板收敛：

package/engine/tool-config-engine.mjs

@@ -27,7 +27,7 @@
  *   - 会给模型提供可调用能力（注册工具 / 域 / 服务）的 → 能力提供者；
  *   - 干预流程（改提示词、改装配、裁决、追加）的 → 声明式触发器。
  * 因此本模块**不接入** engine/trigger.mjs：它不订阅装配 waterfall，也没有
- * when/do 声明，只在装配期把 module.yml 的 customTools 段编译出的工具注册进官方
+ * 声明式触发器（`if`/`then` 声明），只在装配期把 module.yml 的 customTools 段编译出的工具注册进官方
  * registry。强行并进触发器会让引擎同时承担「提供能力」与「干预流程」两种职责。
  *
  * 样板收敛：

package/engine/trigger-spec.mjs

@@ -7,7 +7,7 @@ export { compileWhen, COMPOSITE_OPERATORS, PREDICATE_FACTORIES } from './conditi
 const DECLARATION_FIELDS = Object.freeze(['id', 'channel', 'channelOrder', 'waterfallPosition', 'phase', 'if', 'then', 'else', 'when', 'do'])
 const ACTION_PHASES = Object.freeze(['before-next', 'after-next'])
 
-/** `then`/`do` 归一化为动作声明数组；分支节点留到 `expandActions` 展开。 */
+/** `then`（单个动作或数组）归一化为动作声明数组；分支节点留到 `expandActions` 展开。 */
 function actionList(value, label) {
   const list = Array.isArray(value) ? value : [value]
   if (list.length === 0) throw new TypeError(`${label} must be an action declaration or a non-empty array of them`)
@@ -40,9 +40,9 @@ function actionGate(declarationWhen, action) {
 }
 
 /**
- * 编译一条声明：校验字段 + 编译 `when` + 归一化 `do`。
+ * 编译一条声明：校验字段 + 编译 `if` 判定 + 归一化 `then` 动作。
  *
- * @param {object} spec 声明（`{ id, channel, when?, do, channelOrder?, waterfallPosition?, phase? }`）
+ * @param {object} spec 声明（`{ id, channel, if?, then, else?, channelOrder?, waterfallPosition?, phase? }`）
  * @param {object} [context] 同 {@link compileWhen}，另可提供 promptConfigOptions（createPromptConfigs 的模板/策略编译选项）。
  * @returns {{id: string, channel: string, channelOrder: number, waterfallPosition: string, phase: string, when: Function|undefined, actions: object[], promptConfigOptions?: object}}
  */

package/engine/trigger.mjs

@@ -2,8 +2,8 @@
  * trigger — 触发器引擎（B3）：把「声明」变成「注册」。
  *
  * 本文件负责调度层，**不含**判断原语与动作实现：
- *   - `when` 由 `engine/predicates.mjs` 提供（七类判断的组合）；
- *   - `do`   由 `engine/actions.mjs` 提供（七类动作）；
+ *   - `when` 判定由 `engine/conditions/` 提供（九个判断原语 + all/any/not/notAny 组合）；
+ *   - `do`   动作由 `engine/actions/` 提供（九类动作）；`predicates.mjs` / `actions.mjs` 只留重导出入口。
  *   - 本文件只做：声明校验（复用 B2 的 fields.mjs）、同通道内的稳定排序、
  *     宿主 waterfall 位置映射、注册与 disposer、降级与统一告警、会话态生命周期。
  *