dsh-plugin-prompt-tool 2.1.0 → 3.0.1

package/engine/fillers.mjs

@@ -4,7 +4,10 @@
  */
 
 import { getService, parseToolNames } from './shared.mjs'
+import { machinePaths } from './machine-paths.mjs'
+import { SAFE_ENV_KEYS } from './env-safety.mjs'
 import { createInstructionHintResolver } from './instruction-hint.mjs'
+import { DISCOVERY_SERVICE } from './service-names.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -13,30 +16,57 @@ function explicitTemplate(config) {
   return texts.length > 0 ? texts.join('\n\n') : typeof config.params?.text === 'string' ? config.params.text : ''
 }
 
+/** 只读同规则工具面声明；文案、条件和投递仍归普通注入动作。 */
+function createToolCatalogResolver(config) {
+  if (config.params?.templateEvaluation === true) throw new TypeError('tool-catalog is read-only and does not support templateEvaluation')
+  if (typeof config.params?.action !== 'string' || config.params.action.trim().length === 0) {
+    throw new TypeError('tool-catalog requires params.action referencing a tool-visibility action')
+  }
+  const text = explicitTemplate(config)
+  return ({ ctx, agent }) => {
+    if (text.trim().length === 0) return null
+    const source = config.toolCatalogSource
+    if (source === undefined) throw new TypeError('tool-catalog requires a same-rule tool-visibility action')
+    const deny = new Set(source.deny ?? [])
+    const resident = [...new Set(source.allow)].filter(tool => !deny.has(tool))
+    const adapter = source.discovery === undefined ? undefined
+      : getService(ctx, DISCOVERY_SERVICE)?.get?.(agent, source.discovery.kind)
+    if (source.discovery !== undefined && typeof adapter?.tool !== 'string') {
+      throw new Error(`tool-catalog discovery adapter ${source.discovery.kind} is unavailable`)
+    }
+    return { text, variables: { RESIDENT_TOOLS: resident.join(', '), DISCOVERY_TOOL: adapter?.tool ?? '' } }
+  }
+}
+
 /**
  * env-facts:机器事实动态填充器。
  * params.envKeys 逗号分隔环境变量白名单：取值归模板/预设，留空 = 不附加宿主环境
- * 变量（CWD/WORKSPACE 仍由会话事实提供）。
+ * 变量（CWD/WORKSPACE 仍由会话事实提供）。白名单外的键在构造期拒绝，不读取任意 process.env。
  * 只提供 facts 变量；正文必须由 text/params.text 显式模板声明。
  */
 function createEnvFactsResolver(config) {
   const template = explicitTemplate(config)
-  if (template.trim().length === 0) return () => null
   const keys = parseToolNames(typeof config.params?.envKeys === 'string' ? config.params.envKeys : '')
+  const rejected = keys.filter((key) => !SAFE_ENV_KEYS.has(key))
+  if (rejected.length > 0) {
+    throw new TypeError(`${name}: env-facts envKeys not in SAFE_ENV_KEYS: ${rejected.join(', ')} — safe keys: ${[...SAFE_ENV_KEYS].join(', ')}`)
+  }
+  if (template.trim().length === 0) return () => null
   return ({ agent }) => {
     const session = agent?.session
-    const cwd = session?.header?.cwd ?? process.cwd()
-    const builtinHome = process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : '')
+    // 路径类事实取唯一来源；白名单（envKeys）与「空串不算有值」是本处的策略，不外包。
+    const paths = machinePaths(session)
     const facts = {}
     for (const key of keys) {
       let value
-      if (key === 'CWD' || key === 'WORKSPACE') value = cwd
-      else if (key === 'DSH_HOME') value = builtinHome
+      if (key === 'CWD') value = paths.CWD
+      else if (key === 'WORKSPACE') value = paths.WORKSPACE
+      else if (key === 'DSH_HOME') value = paths.DSH_HOME
       else value = process.env[key]
       if (typeof value === 'string' && value.length > 0) facts[key] = value
     }
-    facts.WORKSPACE = process.env.DSH_WORKSPACE ?? cwd
-    facts.CWD = cwd
+    facts.WORKSPACE = paths.WORKSPACE
+    facts.CWD = paths.CWD
     const envFacts = Object.entries(facts).map(([key, value]) => `- ${key}=${value}`).join('\n')
     return { text: template, variables: { ...facts, ENV_FACTS: envFacts } }
   }
@@ -138,6 +168,7 @@ export const FILLERS = {
   'instruction-hint': (config) => createInstructionHintResolver(config),
   'env-facts': (config) => createEnvFactsResolver(config),
   'skill-catalog': (config) => createSkillCatalogResolver(config),
+  'tool-catalog': (config) => createToolCatalogResolver(config),
 }
 
 export function createPlaceholderResolver(config) {

package/engine/fixed-registration.mjs

@@ -0,0 +1,12 @@
+/**
+ * 「固定注册效果」判据的唯一实现：只有 `system-section` 层的 `complete` /
+ * `suppressRuntimeContext` 是注册期效果（无逐轮求值时机）。其他层写同名键是死配置。
+ * `layer` 是声明缺省层——config 可能省略 layer，回退规则与
+ * `injectionConfigSpec` 的 `config.layer ?? rule.layer ?? 'pre-step'` 一致。
+ */
+import { record } from './record.mjs'
+
+export function isFixedRegistration(config, layer) {
+  return record(config) && (config.layer ?? layer) === 'system-section'
+    && (config.params?.complete === true || config.params?.suppressRuntimeContext === true)
+}

package/engine/history.mjs

@@ -0,0 +1,71 @@
+/**
+ * history — 会话历史的**唯一**读取入口，给出两个互不替代的视图。
+ *
+ * 1. `currentEvents()`：**当前模型可见上下文**，即 surface 有序节点（`session.surface.nodes`）指向的事件。
+ *    压缩 / 位置替换遮蔽掉的节点不在其中，这正是「当前上下文」与「本会话曾经发生过」的差别。
+ * 2. `historyEvents()`：**完整历史**，按 log 序返回本会话全部 durable 事件，供「必须看全量」的消费点。
+ *
+ * 两个视图都是纯函数：每次都读当场快照，不缓存、不跨会话保存任何状态。
+ */
+
+/**
+ * 完整历史：`snapshotEvents()` 的全量不可变快照。
+ * 宿主缺该接口（或返回非数组）时按空日志降级，不读取旧 `events` 数组。
+ */
+export function historyEvents(session) {
+  const snapshot = session?.snapshotEvents?.()
+  return Array.isArray(snapshot) ? snapshot : []
+}
+
+/**
+ * 一次工具实际调用的 durable 事件：顶层 `tool/call`，以及 PTC `run_code` 内的
+ * `tool/ptc-dispatch`。只观察「执行了哪个工具」时读两者；观察「模型动作 / 相位晋升」
+ * 仍只看顶层 `tool/call`，不要把本集合直接替换过去。
+ */
+export const TOOL_INVOCATION_EVENT_TYPES = Object.freeze(['tool/call', 'tool/ptc-dispatch'])
+
+/**
+ * 当前上下文是否**真的**受限：surface 在场（`nodes` 是数组）且每个节点都指向日志里的事件。
+ * 判据只有这一处 —— `currentEvents()` 的降级与消费点的视图口径都由它回答，避免两边静默分叉。
+ * 空 `nodes` 是受限（可见上下文为空），不是降级。
+ * `events` 是调用方已经取好的 `historyEvents(session)`（可选，省掉一次快照读）。
+ */
+export function viewRestricted(session, events = historyEvents(session)) {
+  const nodes = session?.surface?.nodes
+  return Array.isArray(nodes) && nodes.every(seq => events[seq] !== undefined)
+}
+
+/**
+ * 当前模型可见上下文：按 surface 节点序取出对应事件。
+ *
+ * `surface.nodes` 存的是 log seq，而 seq 就是 log 下标（`snapshotEvents()` 返回 [0, seq) 的切片），
+ * 因此一次快照加索引即可映射，无需折叠、无需已 deprecated 的 `eventAt()`。
+ *
+ * 降级：surface 缺失、`nodes` 非数组，或任何节点越界（seq >= 日志长度）时退回完整历史 ——
+ * 「宁可多看见，不少看见」，且等价于迁移前的旧行为。空 `nodes` 是合法状态（新会话尚无消息），
+ * 按「当前上下文为空」返回空数组，**不**降级。
+ * shortcut: 与 `deriveMessages()` 的差别是这里不跳过派生出 null 的空内容节点（判据读事件而非正文）；
+ * 需要正文的消费点出现时再按 `deriveMessages()` 收窄。
+ * 同一 seq 可在 `nodes` 中出现多次（位置替换后同一事件占多个位置），按条数计数的消费点需自行按 seq 去重。
+ */
+export function currentEvents(session) {
+  const events = historyEvents(session)
+  if (!viewRestricted(session, events)) return events
+  return session.surface.nodes.map(seq => events[seq])
+}
+
+/**
+ * surface 只承载**消息类**事件——`system/message`、`developer/message`、`user/message`、
+ * `assistant/message`、`tool/result`（真值源：宿主 `packages/core/session/src/surface.ts` 的
+ * `SURFACE_EVENT_TYPES`）。非该集合的事件（`tool/call`、`turn/start`、`compaction/end`）永远不是
+ * surface 节点，按 `currentEvents()` 读它们只会读到空 —— 它们只能按完整历史读。
+ * shortcut: 宿主扩大 `SURFACE_EVENT_TYPES` 时这里要同步，否则新的消息类事件会被当成 log-only
+ * （count 多计、session 恒不命中）。
+ */
+export const SURFACE_MESSAGE_TYPES = new Set([
+  'system/message',
+  'developer/message',
+  'user/message',
+  'assistant/message',
+  'tool/result',
+])

package/engine/instruction-blocks.d.mts

@@ -0,0 +1,13 @@
+/**
+ * `instruction-blocks.mjs` 的手写声明：只声明 `src/` 消费的导出，形状按实现写实。
+ */
+
+/** 一个官方指令标题块；`index` 是标题行首在正文中的位置。 */
+export interface InstructionBlock {
+  action: 'set' | 'replace' | 'remove'
+  path: string
+  index: number
+}
+
+/** 解析系统提醒正文里的 4 种官方指令标题。 */
+export declare function instructionBlocks(text: string): InstructionBlock[]

package/engine/instruction-blocks.mjs

@@ -0,0 +1,21 @@
+/**
+ * 官方系统提醒正文里的指令文件标题：filter 分段与 hint 路径提取共用的唯一解析。
+ * 只认这 4 种行首标题；path 原样返回（调用方各自 trim/匹配），index 是标题行首位置。
+ */
+const ACTIONS = {
+  'Instructions from:': 'set',
+  'Additional instructions from:': 'set',
+  'Updated instructions from:': 'replace',
+  'Instructions removed:': 'remove',
+}
+
+const HEADING_RE = new RegExp('^(' + Object.keys(ACTIONS).join('|') + ') ([^\r\n]+)\r?$', 'gm')
+
+export function instructionBlocks(text) {
+  if (typeof text !== 'string' || text.length === 0) return []
+  return [...text.matchAll(HEADING_RE)].map(match => ({
+    action: ACTIONS[match[1]],
+    path: match[2],
+    index: match.index,
+  }))
+}

package/engine/instruction-files.d.mts

@@ -0,0 +1,5 @@
+/** 宿主依赖面：只声明 src/ 用到的符号，引擎全貌不在此（见 docs/engine-reuse.md 的类型边界）。 */
+export declare const PROJECT_INSTRUCTION_CANDIDATES: readonly string[]
+export declare const USER_GLOBAL_INSTRUCTION_FILE: string
+export declare function ancestorDirs(cwd: string): string[]
+export declare function instructionPlan(cwd: string, markerDirs: ReadonlySet<string>): { root: string; dirs: string[] }

package/engine/instruction-files.mjs

@@ -0,0 +1,97 @@
+/**
+ * instruction-files — 指令文件探测的判据。
+ *
+ * 探测判据（候选清单、项目根、目录链）是纯函数；读盘由两个消费者各自完成——
+ * 引擎用本文件提供的异步执行器（collectInstructionFiles），宿主用 node:fs 同步 +
+ * 信任根校验。本文件随 engine/ 一起复制；行 instruction-hint 只消费这里的执行器。
+ */
+import { dirname, join } from 'node:path'
+import { machinePaths } from './machine-paths.mjs'
+
+/** 项目目录链中按优先级探测的指令文件名。 */
+export const PROJECT_INSTRUCTION_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
+export const USER_GLOBAL_INSTRUCTION_FILE = 'AGENTS.md'
+
+/** 引擎侧的项目根标记；宿主有自己的集合（例如只要 .git），因此这里不做统一。 */
+export const ENGINE_PROJECT_ROOT_MARKERS = ['.git', '.hg', '.svn']
+
+/** cwd 到文件系统根：含自身，父目录等于自身时停止。 */
+export function ancestorDirs(cwd) {
+  const dirs = [cwd]
+  for (;;) {
+    const parent = dirname(dirs[dirs.length - 1])
+    if (parent === dirs[dirs.length - 1]) return dirs
+    dirs.push(parent)
+  }
+}
+
+/** 最近的含 marker 祖先；没有 marker 或 marker 不在祖先链上时回落 cwd。 */
+function resolveProjectRoot(cwd, markerDirs) {
+  for (const dir of ancestorDirs(cwd)) if (markerDirs.has(dir)) return dir
+  return cwd
+}
+
+/** 项目根到 cwd 的目录链（广到窄）；root 必来自 ancestorDirs(cwd)，因此一定在链上。 */
+function instructionDirs(cwd, root) {
+  const dirs = ancestorDirs(cwd)
+  return dirs.slice(0, dirs.indexOf(root) + 1).reverse()
+}
+
+/**
+ * 一次给出项目根与目录链（广到窄）；要「近者优先」的注入顺序由调用方自行反转。
+ * markerDirs 的字符串必须取自 ancestorDirs（同一套规范化，UNC 共享名根带尾分隔符）。
+ */
+export function instructionPlan(cwd, markerDirs) {
+  const root = resolveProjectRoot(cwd, markerDirs)
+  return { root, dirs: instructionDirs(cwd, root) }
+}
+
+/** 列出某目录里的候选文件（按候选顺序）；探测失败逐条跳过，不阻断会话。 */
+async function presentInDir(fs, dir, candidates, signal) {
+  const found = []
+  for (const candidate of candidates) {
+    try {
+      const target = await fs.resolve(join(dir, candidate), { cwd: dir, signal })
+      const info = await fs.stat(target, signal)
+      if (info !== undefined && info.type === 'file') found.push(candidate)
+    } catch {
+      // 不存在或不可读——跳过。
+    }
+  }
+  return found
+}
+
+/**
+ * 探测 cwd 到项目根的完整目录链，以及 DSH_HOME 下的用户级指令文件。
+ * 计划与读盘分离：先由 ancestorDirs 得到祖先，再异步探 marker，最后交给纯函数选根。
+ */
+export async function collectInstructionFiles(fs, cwd, signal, home) {
+  const markerDirs = new Set()
+  for (const dir of ancestorDirs(cwd)) {
+    for (const marker of ENGINE_PROJECT_ROOT_MARKERS) {
+      try {
+        const target = await fs.resolve(join(dir, marker), { cwd: dir, signal })
+        if (await fs.stat(target, signal) !== undefined) { markerDirs.add(dir); break }
+      } catch {
+        // 标记不存在——继续看上一层。
+      }
+    }
+    // 最近 marker 即项目根：再向上的探测不会改变 instructionPlan 的结果。
+    if (markerDirs.has(dir)) break
+  }
+  const plan = instructionPlan(cwd, markerDirs)
+  const projectFiles = []
+  // 注入顺序要求近者优先：cwd 先于项目根；根目录下的文件用裸候选名。
+  for (const dir of [...plan.dirs].reverse()) {
+    for (const candidate of await presentInDir(fs, dir, PROJECT_INSTRUCTION_CANDIDATES, signal)) {
+      projectFiles.push(dir === plan.root ? candidate : join(dir, candidate))
+    }
+  }
+  const userGlobalFiles = []
+  // 路径类事实取唯一来源；本处需要 undefined 表示「没有可探测的全局目录」，故把空串折回缺省。
+  const dshHome = home ?? (machinePaths().DSH_HOME || undefined)
+  if (dshHome !== undefined) {
+    userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_INSTRUCTION_FILE], signal))
+  }
+  return { root: plan.root, projectFiles, userGlobalFiles, userGlobalHome: dshHome }
+}

package/engine/instruction-hint.mjs

@@ -1,9 +1,10 @@
 /**
- * instruction-hint — 通用内置指令文件提示引擎。
+ * instruction-hint — 通用内置指令文件提示引擎（可挂载的行 + 消息构造）。
  *
- * 本模块同时是「可 import 的纯函数库」与「可被组合源挂载的 plugin」：
+ * 探测（候选清单、项目根、目录链）归 engine/instruction-files.mjs，本模块只消费它的
+ * 异步执行器。两个入口：
  * - prompt-config 的 strategy=placeholder + fill=instruction-hint
- *   直接使用本模块的探测与消息构造；
+ *   直接使用本模块的消息构造与 instruction-files 的探测结果；
  * - plugin 形态（见文件末尾 apply）：**挂本行 = 开启**「晋升后把
  *   agent-instructions 全文替换为一次性 hint，后续全文消息丢弃」的转换。
  *
@@ -19,97 +20,30 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
 import { createEpochPromotion } from './compaction-epoch.mjs'
+import {
+  ancestorDirs,
+  collectInstructionFiles,
+  ENGINE_PROJECT_ROOT_MARKERS,
+  PROJECT_INSTRUCTION_CANDIDATES,
+  USER_GLOBAL_INSTRUCTION_FILE,
+} from './instruction-files.mjs'
 import { interpolateStatic } from './interpolate.mjs'
+import { machinePaths } from './machine-paths.mjs'
+import { resolveRealWithin } from './path-safety.mjs'
 import { booleanOption, createWarnOnce, getService, parsePromoteOn, validateConfig } from './shared.mjs'
+import { PRE_STEP_COORDINATOR_SERVICE } from './service-names.mjs'
+import { instructionBlocks } from './instruction-blocks.mjs'
 
 export const name = 'instruction-hint'
 
 /** 无 inject：监听器只在使用时触碰 ctx 服务（同 tool-bootstrap / context-gate 纪律）。 */
 export const inject = []
 
-/** 项目目录链中按优先级探测的指令文件名。 */
-export const PROJECT_INSTRUCTION_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
-export const USER_GLOBAL_INSTRUCTION_CANDIDATE = 'AGENTS.md'
 const templateOf = (templates, key) => typeof templates?.[key] === 'string' ? templates[key] : ''
 
-/** Join one path segment onto a directory (platform-agnostic string join). */
-export function joinPath(dir, segment) {
-  if (dir.endsWith('/') || dir.endsWith('\\')) return dir + segment
-  const sep = dir.includes('\\') ? '\\' : '/'
-  return dir + sep + segment
-}
-
-/** Parent of an absolute Windows or POSIX path. */
-export function parentPath(path) {
-  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
-  if (idx <= 0) return path
-  const parent = path.slice(0, idx)
-  return parent.length === 0 ? path : parent
-}
-
-/** Find the project root: first ancestor containing any root marker. */
-export async function findProjectRoot(fs, cwd, signal) {
-  let current = cwd
-  for (;;) {
-    for (const marker of ['.git', '.hg', '.svn']) {
-      try {
-        const target = await fs.resolve(joinPath(current, marker), { cwd, signal })
-        const info = await fs.stat(target, signal)
-        if (info !== undefined) return current
-      } catch {
-        // Probe failure = marker absent; continue.
-      }
-    }
-    const parent = parentPath(current)
-    if (parent === current || parent.length === 0) return cwd
-    current = parent
-  }
-}
-
-/** List instruction files present in one directory. */
-export async function presentInDir(fs, dir, candidates, signal) {
-  const found = []
-  for (const candidate of candidates) {
-    try {
-      const target = await fs.resolve(joinPath(dir, candidate), { cwd: dir, signal })
-      const info = await fs.stat(target, signal)
-      if (info !== undefined && info.type === 'file') found.push(candidate)
-    } catch {
-      // Absent or unreadable — skip.
-    }
-  }
-  return found
-}
-
-/**
- * 探测 cwd 到项目根的完整目录链，以及 DSH_HOME 下的用户级 AGENTS.md。
- * home 未传时使用当前宿主的 DSH_HOME/USERPROFILE 推导值。
- */
-export async function collectInstructionFiles(fs, cwd, signal, home) {
-  const root = await findProjectRoot(fs, cwd, signal)
-  const projectFiles = []
-  let probed = cwd
-  for (;;) {
-    for (const candidate of await presentInDir(fs, probed, PROJECT_INSTRUCTION_CANDIDATES, signal)) {
-      projectFiles.push(probed === root ? candidate : joinPath(probed, candidate))
-    }
-    if (probed === root) break
-    const parent = parentPath(probed)
-    if (parent === probed || parent.length === 0) break
-    probed = parent
-  }
-
-  const userGlobalFiles = []
-  const dshHome = home ?? process.env.DSH_HOME
-    ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : undefined)
-  if (dshHome !== undefined) {
-    userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_INSTRUCTION_CANDIDATE], signal))
-  }
-  return { root, projectFiles, userGlobalFiles, userGlobalHome: dshHome }
-}
-
 /**
  * 用显式模板格式化探测结果；无文件或无正文模板时返回空字符串。
  * scope 限定只报告某一来源：all（默认）/ global（$DSH_HOME/AGENTS.md）/ project（cwd→项目根链）。
@@ -117,14 +51,14 @@ export async function collectInstructionFiles(fs, cwd, signal, home) {
 export function buildInstructionHintText({ root, projectFiles = [], userGlobalFiles = [], userGlobalHome } = {}, scope = 'all', templates = {}) {
   const sections = []
   if (scope !== 'global' && projectFiles.length > 0) {
-    const text = interpolateStatic(templateOf(templates, 'projectTemplate'), { FILES: projectFiles.join(', '), ROOT: root ?? '' })
+    const text = interpolateStatic(templateOf(templates, 'projectTemplate'), { FILES: projectFiles.join(', '), ROOT: root ?? '' }, undefined, 'projectTemplate')
     if (text.trim().length > 0) sections.push(text)
   }
   if (scope !== 'project' && userGlobalFiles.length > 0) {
     const paths = typeof userGlobalHome === 'string' && userGlobalHome.length > 0
-      ? userGlobalFiles.map((name) => joinPath(userGlobalHome, name))
+      ? userGlobalFiles.map((name) => join(userGlobalHome, name))
       : userGlobalFiles
-    const text = interpolateStatic(templateOf(templates, 'globalTemplate'), { FILES: paths.join(', '), ROOT: root ?? '' })
+    const text = interpolateStatic(templateOf(templates, 'globalTemplate'), { FILES: paths.join(', '), ROOT: root ?? '' }, undefined, 'globalTemplate')
     if (text.trim().length > 0) sections.push(text)
   }
   if (sections.length === 0) return ''
@@ -139,13 +73,54 @@ function hintScope(value) {
   return typeof value === 'string' && HINT_SCOPES.has(value) ? value : 'all'
 }
 
+/** params.file 的白名单：与探测清单同源，只允许指令文件候选名。 */
+const INSTRUCTION_FILE_NAMES = new Set([...PROJECT_INSTRUCTION_CANDIDATES, USER_GLOBAL_INSTRUCTION_FILE])
+
+/**
+ * 指令文件的信任根：cwd 的目录链，向上到最近的项目根为止（与探测范围一致）；
+ * 没有 marker 时只有 cwd。不延伸到项目根之上——那会把同一卷上的任意路径都算进来。
+ */
+function instructionRoots(cwd) {
+  const dirs = ancestorDirs(cwd)
+  for (const [index, dir] of dirs.entries()) {
+    if (ENGINE_PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(dir, marker)))) return dirs.slice(0, index + 1)
+  }
+  return [cwd]
+}
+
+/**
+ * 文件即真相：每次注入都重读绑定文件，外部编辑立即生效。
+ * 信任根 = cwd 的目录链到最近项目根（探测同一范围，故项目根 AGENTS.md 合法）+ DSH_HOME。
+ * 越界、链接逃逸与非法名字直接抛出（executor 会 warn/skip 该配置）；
+ * 目标或其父目录不存在时按缺失文件返回空串。
+ */
+function readBoundInstructionFile(file, cwd) {
+  if (!INSTRUCTION_FILE_NAMES.has(basename(file))) {
+    throw new Error(`instruction-hint: params.file must be an instruction file name (${[...INSTRUCTION_FILE_NAMES].join(', ')}), got ${JSON.stringify(file)}`)
+  }
+  let real
+  try {
+    real = resolveRealWithin(resolve(cwd, file), [...instructionRoots(cwd), machinePaths().DSH_HOME], 'instruction file')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return ''
+    throw error
+  }
+  try {
+    return readFileSync(real, 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
 /**
  * prompt-config placeholder fill=instruction-hint 的 resolver。
  * params.text（自定义提示）优先；params.file（文件卡绑定的单个指令文件）次之——
  * 运行时读该文件正文并加 `Instructions from:` 头注入；最后按 params.scope 探测来源
  * （all / global / project）按显式 projectTemplate/globalTemplate 生成提示。
  * 未配置提示模板时返回 null；引擎不提供默认引导文案。
- * 文件缺失、不可读或空内容时返回 null，不注入任何消息。
+ * params.file 不是任意文件读取：名字必须是指令文件候选名，真实路径必须在会话 cwd 到
+ * 项目根的目录链或 DSH_HOME 内；越界、链接逃逸与非法名字在解析期抛错（executor 按单配置
+ * 告警跳过）。文件缺失、不可读或空内容时返回 null。
  */
 export function createInstructionHintResolver(config = {}) {
   const customText = typeof config?.params?.text === 'string' ? config.params.text.trim()
@@ -157,14 +132,6 @@ export function createInstructionHintResolver(config = {}) {
   const fileLabel = typeof config?.params?.displayPath === 'string' && config.params.displayPath.trim().length > 0
     ? config.params.displayPath.trim()
     : file
-  /** 文件即真相：每次注入都重读绑定文件，外部编辑立即生效。 */
-  const readBoundFile = () => {
-    try {
-      return readFileSync(file, 'utf8').trim()
-    } catch {
-      return ''
-    }
-  }
 
   return async ({ ctx, agent, session }) => {
     const id = `instruction-hint-${session.id}-${randomUUID()}`
@@ -172,7 +139,7 @@ export function createInstructionHintResolver(config = {}) {
       return { id, text: customText, source: { kind: 'instruction-hint', form: 'hint' } }
     }
     if (file.length > 0) {
-      const content = readBoundFile()
+      const content = readBoundInstructionFile(file, session.header?.cwd ?? process.cwd())
       return content.length > 0
         ? { id, text: `Instructions from: ${fileLabel}\n\n${content}`, source: { kind: 'instruction-file', form: 'instructions' } }
         : null
@@ -189,16 +156,15 @@ export function createInstructionHintResolver(config = {}) {
   }
 }
 
-const INSTRUCTION_FROM_RE = /(?:^|\n) *(?:Additional |Updated )?Instructions from: ([^\n]+)/g
-
-/** 从 agent-instructions 注入消息提取参考文件路径。 */
+/** 从 agent-instructions 注入消息提取参考文件路径；removed 不是参考文件。 */
 export function extractInstructionPaths(message) {
   const paths = []
   const blocks = Array.isArray(message?.content) ? message.content : []
   for (const block of blocks) {
     if (block?.type !== 'text' || typeof block.text !== 'string') continue
-    for (const match of block.text.matchAll(INSTRUCTION_FROM_RE)) {
-      const path = match[1].trim()
+    for (const parsed of instructionBlocks(block.text)) {
+      if (parsed.action === 'remove') continue
+      const path = parsed.path.trim()
       if (path !== '' && !paths.includes(path)) paths.push(path)
     }
   }
@@ -209,7 +175,7 @@ export function extractInstructionPaths(message) {
 export function buildInstructionHint(original, paths, sourceName = 'instruction-hint', templates = {}) {
   const template = templateOf(templates, 'messageTemplate')
   if (template.trim().length === 0) return original
-  const text = interpolateStatic(template, { FILES: paths.join(', '), SUFFIX: templateOf(templates, 'suffixTemplate') })
+  const text = interpolateStatic(template, { FILES: paths.join(', '), SUFFIX: templateOf(templates, 'suffixTemplate') }, undefined, 'messageTemplate')
   if (text.trim().length === 0) return original
   return {
     id: typeof original?.id === 'string' && original.id !== '' ? original.id : `instruction-hint-${randomUUID()}`,
@@ -284,7 +250,7 @@ export function apply(ctx, config) {
       if (!promotion.status(agent).promoted) return decision
       if (!Array.isArray(decision.messages)) return decision
       if (agent?.session === undefined) return decision
-      const coordinator = getService(ctx, 'promptToolPreStep')
+      const coordinator = getService(ctx, PRE_STEP_COORDINATOR_SERVICE)
       const messages = typeof coordinator?.filterInstructions === 'function'
         ? coordinator.filterInstructions(agent, decision.messages)
         : decision.messages

package/engine/interpolate.d.mts

@@ -0,0 +1,7 @@
+/** `interpolate.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** 保留名判据（内建变量 + 动态宏）；任何值都接受，非字符串按空名处理。 */
+export function isReservedInterpolationName(key: unknown): boolean
+
+/** ST 宏写法归一（`{{roll 1d6}}` / `{{roll:1d6}}` → `{{roll::1d6}}`），幂等。 */
+export function normalizeMacroSyntax(text: string): string