dsh-prompt-customizer 0.4.2 → 0.5.1

package/lib/effective.js

@@ -46,7 +46,7 @@ export function mergeConfig(globalCfg, ovr) {
  * 阶段模式匹配 —— bootstrap（未晋级）→ `bootstrap`，active（已晋级）→
  * `active`，compact（压缩后仍未晋级）→ `compaction`。每个阶段的注入集
  * 互相独立（各自的 order 空间），用于「每阶段独立名单 + 虚拟 order」。
- * 传入 `status`（promotion.status() 结果 `{ promoted, boundary }`），
+ * 传入 `status`（阶段投影 statusOf 的结果 `{ promoted, boundary }`），
  * 不再沿用旧的布尔 promoted（旧的 compaction 窗口被硬塞进 bootstrap 期，
  * 无法独立排序）。
  */
@@ -67,7 +67,7 @@ export function filterInjectByPhase(injectList, status) {
  * 走了阶段独立性：界面按三个阶段分别勾选，而引导期的勾选状态既反映不了静态
  * 名单里已隐藏的工具（显示成"可见"、模型其实看不见），往引导期名单里加一项又
  * 会让整个静态名单在该阶段失效（其它工具的隐藏一起蒸发）。
- * `status` 是 promotion.status() 的结果 `{ promoted, boundary }`。
+ * `status` 是阶段投影 statusOf 的结果 `{ promoted, boundary }`。
  */
 export function pickToolsFilter(toolsCfg, status) {
   if (!status.promoted) {

package/lib/index.js

@@ -40,7 +40,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { Config, NS } from './schema.js'
 import { mergeConfig, pickToolsFilter, pickSectionsForStatus, applyToolFilter, applySectionPolicy } from './effective.js'
-import { createPromotion, presetOfSession } from './promotion.js'
+import { createPhaseProjection, presetOfSession, statusOf } from './promotion.js'
 import { createConfigStore, readLegacySection } from './store.js'
 import { createCatalog } from './catalog.js'
 import { registerVariables, listVariableNames } from './vars.js'
@@ -60,8 +60,7 @@ function dshHome() {
   return process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh')
 }
 
-/** 收集并解析一个请求体（JSON），超过上限直接拒绝——路由是本进程私有的，上限只是防御。 */
-function readJsonBody(req, limit = 2 * 1024 * 1024) {
+/** 收集并解析一个请求体（JSON），超过上限直接拒绝——路由是本进程私有的，上限只是防御。 */function readJsonBody(req, limit = 2 * 1024 * 1024) {
   return new Promise((resolve, reject) => {
     let size = 0
     const chunks = []
@@ -159,11 +158,16 @@ export function apply(ctx, entry = {}) {
   // 启动时剥掉并记一条日志（逐处列出被去掉的名字），不静默改用户文件。
   stripLegacyInclude(store, (message) => { try { ctx.logger?.info?.(message) } catch { /* logger 缺席 */ } })
 
-  // 2) 晋级 tracker：增量维护每会话的 bootstrap/active 阶段（durable 事件
-  //    推导，compaction 复位，subagent 恒已晋级）。
-  const promotion = createPromotion()
-  ctx.on('session/event', (session, event) => {
-    try { promotion.observe(session, event) } catch { /* tracker 故障绝不影响事件流 */ }
+  // 2) 阶段投影：把 bootstrap/active 推导注册成宿主的会话投影 unit —— 宿主按会话
+  //    折叠（含 resume / reload 后从日志重建）并增量驱动，本插件不再自扫历史
+  //    （`Session.events` 已在 0.1.2-alpha.4 移除，同步历史读在 0.1.6 已 deprecated；
+  //    见 promotion.js 顶部说明）。注册随本插件的 fiber 一起注销。
+  ctx.inject(['sessionProjections'], (projectionCtx) => {
+    try {
+      projectionCtx.sessionProjections.register(createPhaseProjection())
+    } catch (error) {
+      try { ctx.logger?.warn?.(`prompt-customizer: 阶段投影注册失败（阶段视图回落为已晋级）：${String((error && error.message) || error)}`) } catch { /* logger 缺席 */ }
+    }
   })
 
   // 单次降级告警：过滤逻辑出错时退回未加工的装配，绝不拖垮会话。
@@ -196,20 +200,30 @@ export function apply(ctx, entry = {}) {
   // 3) 装配目标解析（瀑布流与 assemble 强制覆盖共用）：生效配置 = 显式预览
   //    提示 > 会话所属 agent 预设（字段级覆盖）> 全局默认。预览 hint 优先于
   //    会话事件推导的阶段，让同一份配置能渲染 bootstrap / compaction / active
-  //    三种阶段视图。boundary 语义与 promotion.status 一致（-1 = 从未压缩）。
+  //    三种阶段视图。boundary 语义与阶段投影 statusOf 一致（-1 = 从未压缩）。
+  //    预览装配可携带 promptCustomizerPatch（UI 未保存草稿）：只在内存里叠加
+  //    到目标层（overlayPatch），磁盘不动 —— 实时预览「所见即保存后所得」。
   const resolveTarget = (context) => {
     const raw = read()
+    const patch = context?.promptCustomizerPatch
+    const base = patch !== null && typeof patch === 'object' && !Array.isArray(patch)
+      ? overlayPatch(raw,
+          typeof context.promptCustomizerTarget === 'string' && context.promptCustomizerTarget.length > 0
+            ? context.promptCustomizerTarget
+            : undefined,
+          patch)
+      : raw
     const id = typeof context?.promptCustomizerPreset === 'string'
       ? context.promptCustomizerPreset
-      : presetOfSession(context?.agent?.session)
-    const cfg = mergeConfig(raw, raw.overrides?.[id])
+      : presetOfSession(ctx.get('sessionProjections'), context?.agent?.session)
+    const cfg = mergeConfig(base, base.overrides?.[id])
     const phaseHint = typeof context?.promptCustomizerPhase === 'string'
       ? context.promptCustomizerPhase
       : undefined
     const status = phaseHint === 'bootstrap' ? { promoted: false, boundary: -1 }
       : phaseHint === 'compaction' ? { promoted: false, boundary: 1 }
       : phaseHint === 'active' ? { promoted: true, boundary: -1 }
-      : promotion.status(context?.agent)
+      : statusOf(ctx.get('sessionProjections'), context?.agent)
     return { raw, cfg, status }
   }
 
@@ -341,7 +355,38 @@ export function apply(ctx, entry = {}) {
   //    会抛 "cannot get property without inject"。
   const webserver = ctx.get('webServer')
   if (webserver) {
-    const dispose = webserver.register({
+    // 连接信任闸（宿主 0.1.2-alpha.1 起）：官方 /api 通道走 process 级 bootstrap
+    // token + 签名 Cookie，而直接注册在 webServer 上的自建路由不在其中 —— 宿主
+    // 契约要求先问过 connection.requestRejection：其 Host/Origin 围栏挡 DNS
+    // rebinding 与跨站调用，浏览器认证再挡未持 Cookie 的调用。本插件的路由会写盘
+    // （config/presets），必须过闸；闸本身不可用（connection 服务缺席）时保守
+    // 拒绝（fail-closed）——「没有认证面」不等于「无需认证」。
+    //
+    // 服务每次请求现读，绝不在 apply 时捕获：connection 由同 profile 的另一条
+    // entry 提供，entry 创建顺序不保证（实测冷启时本插件 apply 早于其提供，
+    // 捕获版会让整组路由永久 503）；宿主自带路由（open-in-app 等）同款懒读。
+    const unauthenticated = (req, res) => {
+      const connection = ctx.get('connection')
+      if (typeof connection?.requestRejection !== 'function') {
+        writeJson(res, 503, { ok: false, error: 'connection service unavailable: prompt-customizer routes refuse to serve unauthenticated' })
+        return true
+      }
+      const rejection = connection.requestRejection(req)
+      if (rejection === undefined) return false
+      res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+      return true
+    }
+    /** 与 webserver.register 同形，统一在 handler 前挂信任闸（注册顺序与 disposer 不变）。 */
+    const register = (route) => webserver.register({
+      kind: route.kind,
+      path: route.path,
+      handler: (req, res) => {
+        if (unauthenticated(req, res)) return undefined
+        return route.handler(req, res)
+      },
+    })
+    const dispose = register({
       kind: 'exact',
       path: '/api/prompt-customizer/inventory',
       handler: async (req, res) => {
@@ -376,13 +421,24 @@ export function apply(ctx, entry = {}) {
     // 使用 standard agent，与清单一致）；可选 `?phase=<bootstrap|compaction|
     // active>` 预览指定对话阶段的三态视图（省略时按晋级推导，只读路由下
     // 即 active / 静态视图）。
-    const disposePreview = webserver.register({
+    // POST 形态（UI 实时预览）：body { target?, patch?, phase? } —— patch 是
+    // UI 未保存的编辑草稿，只在内存里叠加（overlayPatch），绝不写盘。
+    const disposePreview = register({
       kind: 'exact',
       path: '/api/prompt-customizer/preview',
       handler: async (req, res) => {
         try {
-          const { scopeKey, hintId, phase, scopeResolved } = await previewTarget(ctx, req)
-          const preview = await buildPreview(ctx, scopeKey, hintId, phase, catalog)
+          let body = null
+          if (req.method === 'POST') {
+            try { body = await readJsonBody(req) } catch { body = null }
+          }
+          const { scopeKey, hintId, phase, scopeResolved } = await previewTarget(ctx, req, body)
+          const patch = body !== null && typeof body === 'object'
+            && body.patch !== null && typeof body.patch === 'object' && !Array.isArray(body.patch)
+            ? body.patch
+            : undefined
+          const patchTarget = typeof body?.target === 'string' && body.target.length > 0 ? body.target : undefined
+          const preview = await buildPreview(ctx, scopeKey, hintId, phase, catalog, patch, patchTarget)
           writeJson(res, 200, { ...preview, scopeResolved, phase })
         } catch (error) {
           writeJson(res, 500, {
@@ -396,7 +452,7 @@ export function apply(ctx, entry = {}) {
 
     // agent 预设枚举路由：直接读 roster 的 list()（未 memo 化，运行中新增
     // 的预设立即可见），给 UI 的目标选择器与预览选择器供货。
-    const disposePresets = webserver.register({
+    const disposePresets = register({
       kind: 'exact',
       path: '/api/prompt-customizer/agent-presets',
       handler: async (_req, res) => {
@@ -423,7 +479,7 @@ export function apply(ctx, entry = {}) {
     // 来源预设的原样组成 + 我刚改好的定制，这才叫「保存的是我修改后的样子」。
     // 我们不再自己生成骨架：骨架带着 persona complete: true，宿主会在水流之后把
     // sections 还原成那一条段，段级定制在它上面根本不生效。
-    const disposePresetsCreate = webserver.register({
+    const disposePresetsCreate = register({
       kind: 'exact',
       path: '/api/prompt-customizer/presets',
       handler: async (req, res) => {
@@ -486,7 +542,7 @@ export function apply(ctx, entry = {}) {
     //  GET  /config        → { ok, config }（解析后含默认值）
     //  POST /config/set    → body { field, value }；写入并返回最新 config
     //  POST /config/unset  → body { field }；删除字段并返回最新 config
-    const disposeConfig = webserver.register({
+    const disposeConfig = register({
       kind: 'exact',
       path: '/api/prompt-customizer/config',
       handler: async (_req, res) => {
@@ -511,14 +567,14 @@ export function apply(ctx, entry = {}) {
         })
       }
     }
-    const disposeConfigSet = webserver.register({
+    const disposeConfigSet = register({
       kind: 'exact',
       path: '/api/prompt-customizer/config/set',
       handler: withFieldWrite(({ field, value }) => store.setField(field, value)),
     })
     ctx.effect(() => disposeConfigSet, 'prompt-customizer: config set route')
 
-    const disposeConfigUnset = webserver.register({
+    const disposeConfigUnset = register({
       kind: 'exact',
       path: '/api/prompt-customizer/config/unset',
       handler: withFieldWrite(({ field }) => store.setField(field, undefined)),
@@ -529,7 +585,7 @@ export function apply(ctx, entry = {}) {
     // 无需卸载 / 重启（forceSections: false 时 assemble 包装直接放行宿主原样，
     // 瀑布流里空配置的过滤是无操作）。文件本身保留，避免卸载重装后迁移逻辑
     // 再次触发；之后要重新启用定制，把 forceSections 改回 true 或删除该行即可。
-    const disposeConfigReset = webserver.register({
+    const disposeConfigReset = register({
       kind: 'exact',
       path: '/api/prompt-customizer/config/reset',
       handler: async (_req, res) => {
@@ -547,11 +603,10 @@ export function apply(ctx, entry = {}) {
     ctx.effect(() => disposeConfigReset, 'prompt-customizer: config reset route')
 
     // 批量保存路由：UI「统一保存按钮」的唯一写盘通道。body { target?, patch }，
-    // patch 只认业务字段（只认下列业务字段，含每阶段独立段名单），字段值为 null 表示
-    // 删除（回退默认/全局）。target 缺省写全局顶层；target 为 agent 预设 id
-    // 时写 overrides[id]，清空后的空 override 连带删除，避免配置文件堆积空壳。
-    const APPLY_FIELDS = ['sections', 'sectionsBootstrap', 'sectionsCompaction', 'replace', 'inject', 'tools']
-    const disposeConfigApply = webserver.register({
+    // patch 只认业务字段（含每阶段独立段名单），字段值为 null 表示删除（回退
+    // 默认/全局）。target 缺省写全局顶层；target 为 agent 预设 id 时写
+    // overrides[id]。叠加语义与 /preview 的草稿预览共用 overlayPatch（一份实现）。
+    const disposeConfigApply = register({
       kind: 'exact',
       path: '/api/prompt-customizer/config/apply',
       handler: async (req, res) => {
@@ -563,26 +618,7 @@ export function apply(ctx, entry = {}) {
             return
           }
           const target = typeof body.target === 'string' && body.target.length > 0 ? body.target : undefined
-          const base = { ...(store.raw() ?? {}) }
-          const applyPatch = (obj) => {
-            for (const field of APPLY_FIELDS) {
-              if (!Object.hasOwn(patch, field)) continue
-              if (patch[field] === null) delete obj[field]
-              else obj[field] = patch[field]
-            }
-          }
-          if (target === undefined) {
-            applyPatch(base)
-          } else {
-            const overrides = { ...(base.overrides ?? {}) }
-            const ovr = { ...(overrides[target] ?? {}) }
-            applyPatch(ovr)
-            if (Object.keys(ovr).length > 0) overrides[target] = ovr
-            else delete overrides[target]
-            if (Object.keys(overrides).length > 0) base.overrides = overrides
-            else delete base.overrides
-          }
-          store.writeSection(base)
+          store.writeSection(overlayPatch({ ...(store.raw() ?? {}) }, target, patch))
           writeJson(res, 200, { ok: true, config: read() })
         } catch (error) {
           writeJson(res, 400, {
@@ -604,6 +640,39 @@ function withTimeout(value, ms, fallback) {
   ])
 }
 
+/** 配置补丁认得的业务字段（与 UI 编辑域一一对应；含每阶段独立名单）。 */
+const APPLY_FIELDS = ['sections', 'sectionsBootstrap', 'sectionsCompaction', 'replace', 'inject', 'tools']
+
+/**
+ * 把一份补丁叠加到 raw 配置的目标层，返回新对象（不改原对象、不碰磁盘）。
+ * target 缺省 = 全局顶层；字符串 = overrides[id]。字段值为 null = 删除该字段
+ *（回退默认 / 全局）；全空的 override 连带删除，避免配置堆积空壳。
+ * /config/apply 落盘与 /preview 的草稿叠加（实时预览，只读内存）共用这一份
+ * 语义 —— 两处行为永远一致。
+ */
+function overlayPatch(raw, target, patch) {
+  const base = { ...(raw ?? {}) }
+  const applyPatch = (obj) => {
+    for (const field of APPLY_FIELDS) {
+      if (!Object.hasOwn(patch, field)) continue
+      if (patch[field] === null) delete obj[field]
+      else obj[field] = patch[field]
+    }
+  }
+  if (target === undefined) {
+    applyPatch(base)
+  } else {
+    const overrides = { ...(base.overrides ?? {}) }
+    const ovr = { ...(overrides[target] ?? {}) }
+    applyPatch(ovr)
+    if (Object.keys(ovr).length > 0) overrides[target] = ovr
+    else delete overrides[target]
+    if (Object.keys(overrides).length > 0) base.overrides = overrides
+    else delete base.overrides
+  }
+  return base
+}
+
 /**
  * 宿主 authoring API（`agentPresets.copy`）抛错 → HTTP 状态码。
  *
@@ -735,61 +804,34 @@ async function resolveScopeFor(ctx, id) {
  * id 挂载失败时展示会回落 standard scope，但标记为 false，让 UI 明确警示
  * 「预览的不是该预设的原生装配」。
  */
-async function previewTarget(ctx, req) {
+async function previewTarget(ctx, req, body = null) {
   const id = queryOf(req).get('scope') ?? undefined
   const resolved = id ? await resolveScopeFor(ctx, id) : await resolveStandardScope(ctx)
   const scopeKey = resolved ?? (id ? await resolveStandardScope(ctx) : undefined)
-  // `?phase=`：bootstrap / compaction / active 三态预览；其它值一律回退实际推导。
-  const rawPhase = queryOf(req).get('phase') ?? undefined
+  // `?phase=`（或 POST body.phase）：bootstrap / compaction / active 三态预览；
+  // 其它值一律回退实际推导。
+  const rawPhase = (body !== null && typeof body === 'object' ? body.phase : undefined)
+    ?? queryOf(req).get('phase')
+    ?? undefined
   const phase = rawPhase === 'bootstrap' || rawPhase === 'compaction' || rawPhase === 'active'
     ? rawPhase
     : undefined
   return { scopeKey, hintId: id, phase, scopeResolved: resolved !== undefined }
 }
 
-/**
- * 按预览阶段合成一个最小伪会话 agent。预设原生的阶段裁剪插件（zero-tool
- * bootstrap / router-bootstrap / warmup 等）在 assemble 瀑布流里只读
- * `session.id / session.events / session.header / agent.options.model` 推导
- * 晋级状态并动态裁剪工具目录 —— 合成的 durable 事件让这些规则在只读预览
- * 里按所选阶段真实运行（而非挤在常驻视图）：
- * - bootstrap：空事件（boundary -1，未晋级，首轮形态）
- * - compaction：一条 compaction/end（压缩后未重新晋级）
- * - active：一条晋级信号（assistant/message，event 形状见各预设的
- *   compaction-epoch.mjs —— 只认 type 与 seq）
- */
-export function fakeAgentFor(phase, presetId) {
-  const events = phase === 'compaction'
-    ? [{ type: 'compaction/end', seq: 1 }]
-    : phase === 'active'
-      ? [{ type: 'assistant/message', seq: 1 }]
-      : []
-  return {
-    session: {
-      id: `prompt-customizer-preview-${phase}`,
-      events,
-      header: {
-        delegationDepth: 0,
-        agentPreset: presetId,
-        cwd: process.cwd(),
-        meta: {},
-      },
-    },
-    options: { provider: '', model: '' },
-  }
-}
-
 /**
  * 渲染某个 scope 的最终系统提示词：跑完整的装配瀑布流（所有插件的过滤、
  * 包括我们自己的都会生效），再把幸存的段拼成文本。这就是模型实际看到的内容。
  *
- * `phase` 给定时额外携带伪会话 agent，让预设原生的阶段裁剪规则（引导期
- * 收敛目录等）也按所选阶段真实运行；伪会话触发任何插件异常时降级为无
- * 会话装配（原生规则视为已晋级 / 全目录）并标记 degraded，预览永远可用。
- * 同时返回注册表原始目录总数 registryTotal，与模型可见目录形成对照
- * （如 PTC / Code Mode 把全目录包装成单一 run_code）。
+ * 装配是**纯 scope 的诊断装配（不带 agent）**：宿主的不变量契约明确「诊断
+ * 性装配不得携带 agent」—— agent-presets 的 roster 不变量见到未加入预设的
+ * agent 就 fail（抛异常），旧版伪会话每次都触发它，让每次阶段预览都降级。
+ * 当前 harness 的装配瀑布流里也没有读会话推导阶段的插件（阶段裁剪发生在
+ * agent-loop 层，不在 assemble 钩子），三个阶段视图完全由我们自己的
+ * promptCustomizerPhase hint 驱动。同时返回注册表原始目录总数 registryTotal，
+ * 与模型可见目录形成对照（如 PTC / Code Mode 把全目录包装成单一 run_code）。
  */
-async function buildPreview(ctx, scopeKey, hintId, phase, catalog) {
+async function buildPreview(ctx, scopeKey, hintId, phase, catalog, patch, patchTarget) {
   // promptCustomizerPreset / promptCustomizerPhase 都是本插件的自定义装配
   // 字段：让我们的过滤器在这次装配里按该 agent 预设的 override 与指定阶段
   // 视图生效（AssembleContext 允许插件自定义字段）。
@@ -798,20 +840,18 @@ async function buildPreview(ctx, scopeKey, hintId, phase, catalog) {
     promptCustomizerPreset: hintId,
     promptCustomizerPhase: phase,
     // 请求预过滤视图（base）：本插件的过滤器把进入过滤前的段 / 工具原文
-    // 连同屏蔽 / 隐藏标记一起附在装配结果上，作为三个 Tab 的统一数据源。
+    // 连同屏蔽 / 隐藏标记一起附在装配结果上，作为面板两个栏的统一数据源。
     promptCustomizerBase: true,
   }
-  let assembled
-  let degraded = false
-  try {
-    assembled = await ctx.systemPrompt.assemble(
-      phase ? { ...hint, agent: fakeAgentFor(phase, hintId) } : hint,
-    )
-  } catch {
-    // 伪会话让某个预设插件抛错了：退回无会话装配，原生规则不参与本次预览。
-    degraded = phase !== undefined
-    assembled = await ctx.systemPrompt.assemble(hint)
+  // 实时预览（UI 未保存草稿）：补丁挂进装配上下文，过滤器在 resolveTarget
+  // 里把它叠加到目标层 —— 只读内存，磁盘不动。
+  if (patch !== undefined) {
+    hint.promptCustomizerPatch = patch
+    hint.promptCustomizerTarget = patchTarget
   }
+  // 纯 scope 诊断装配（不带 agent，见上方函数注释）：让宿主 roster 不变量
+  // 按「诊断」放行，三个阶段视图由 promptCustomizerPhase hint 驱动。
+  const assembled = await ctx.systemPrompt.assemble(hint)
   const sections = Array.isArray(assembled.sections)
     ? assembled.sections.map((section) => ({ name: section.name, text: String(section.text ?? '') }))
     : []
@@ -840,7 +880,6 @@ async function buildPreview(ctx, scopeKey, hintId, phase, catalog) {
   return {
     ok: true,
     scope: scopeKey,
-    degraded,
     registryTotal,
     /** 该 scope 注册表的工具名清单：供界面区分「在本预设里、只是被该阶段裁掉」
      *  与「根本不属于本预设（无法加回）」。 */

package/lib/promotion.js

@@ -1,80 +1,76 @@
 /**
- * Epoch-aware 晋级 tracker —— 行为对标 agent-presets 实验预设里的
- * compaction-epoch.mjs：晋级由 durable 会话事件推导（默认首个
- * `tool/call` 或 `assistant/message`），compaction 之后复位（首个压缩后
- * 请求回到 bootstrap 态，直到新的晋级信号），subagent 视为恒已晋级。
+ * Epoch-aware 晋级（bootstrap / active）阶段推导 + 会话预设解析。
  *
- * 状态按 session.id 记忆，冷会话扫一遍 durable log 后 O(1)，因此 resume
- * / reload 重建出相同的阶段。
+ * 阶段语义（行为对标 agent-presets 实验预设里的 compaction-epoch.mjs）：晋级由
+ * durable 会话事件推导（默认首个 `tool/call` 或 `assistant/message`），compaction
+ * 之后复位（首个压缩后请求回到 bootstrap 态，直到新的晋级信号），subagent 视为
+ * 恒已晋级。resume / reload 后由宿主投影的懒折叠从日志重建出相同的阶段。
+ *
+ * 读取方式：宿主 0.1.2-alpha.4 移除了 `Session.events`，0.1.6 又把同步历史读
+ * （`eventAt` / `snapshotEvents` / `ownEvents`）标记为 deprecated（见
+ * .agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md，
+ * 长期方向是「投影状态 + 增量维护」）。因此本插件不再自行扫历史：阶段推导注册成
+ * 宿主的会话投影 unit（宿主负责折叠与增量驱动），预设解析直接读宿主 agent-presets
+ * 注册的 `agentPreset` 投影。投影服务缺席（自组 profile 未挂载 session-projection）
+ * 时，读取端回落到「已晋级」——与清单读取的静态视图一致，绝不阻断装配。
  */
 
+import { z } from 'zod'
+
 /** 默认的晋级信号事件。 */
 const DEFAULT_PROMOTE_EVENTS = ['tool/call', 'assistant/message']
 
-/** 构建一个晋级 tracker；promoteEvents 可换成单事件数组。 */
-export function createPromotion(promoteEvents = DEFAULT_PROMOTE_EVENTS) {
-  const promote = new Set(promoteEvents)
-  /** sessionId -> { boundary, promoted } */
-  const state = new Map()
+/** 本插件注册的阶段投影 key（带命名空间，避免与宿主 / 其它插件撞名）。 */
+export const PHASE_PROJECTION_KEY = 'prompt-customizer/phase'
 
-  /** 从 durable log 冷扫描。 */
-  const scan = (session) => {
-    let boundary = -1
-    let promoted = false
-    for (const event of session.events ?? []) {
-      const seq = event.seq ?? 0 // 没有 seq 的事件视为边界之后
-      if (event.type === 'compaction/end') {
-        boundary = seq
-        promoted = false
-        continue
-      }
-      if (promote.has(event.type) && seq > boundary) promoted = true
-    }
-    const entry = { boundary, promoted }
-    state.set(session.id, entry)
-    return entry
-  }
+/** 无从推导时的阶段：视为已晋级（静态视图）。 */
+export const PROMOTED_STATUS = Object.freeze({ boundary: -1, promoted: true })
 
+/**
+ * 构建阶段投影 unit（`ctx.sessionProjections.register` 的入参）。
+ *
+ * state 是纯 JSON `{ boundary, promoted }`（投影契约要求）；apply 是纯函数，
+ * 未命中事件必须返回原引用（宿主以 Object.is 抑制下游工作）。
+ * ponytail: 只覆盖 compaction 边界这一种 epoch，未跟踪 fork 语义。
+ * 升级路径：参照 anchored-standard 的 fork-aware 边界扩展 apply。
+ */
+export function createPhaseProjection(promoteEvents = DEFAULT_PROMOTE_EVENTS) {
+  const promote = new Set(promoteEvents)
   return {
-    /**
-     * 当前 agent 的阶段。agent 缺席（纯清单读取等）或子代理一律已晋级；
-     * ponytail: 只覆盖 compaction 边界这一种 epoch，未跟踪 fork 语义。
-     * 升级路径：参照 anchored-standard 的 fork-aware 边界扩展 scan。
-     */
-    status(agent) {
-      const session = agent?.session
-      if (!session) return { boundary: -1, promoted: true }
-      if ((session.header?.delegationDepth ?? 0) > 0) return { boundary: -1, promoted: true }
-      return state.get(session.id) ?? scan(session)
-    },
-
-    /** 增量喂入 `session/event`，避免每次装配全量扫描。 */
-    observe(session, event) {
-      const entry = state.get(session.id)
-      if (entry === undefined) return
-      const seq = event.seq ?? 0
-      if (event.type === 'compaction/end') {
-        state.set(session.id, { boundary: seq, promoted: false })
-        return
-      }
-      if (promote.has(event.type) && seq > entry.boundary && !entry.promoted) {
-        state.set(session.id, { ...entry, promoted: true })
+    key: PHASE_PROJECTION_KEY,
+    stateSchema: z.object({ boundary: z.number().int(), promoted: z.boolean() }),
+    init: () => ({ boundary: -1, promoted: false }),
+    apply: (state, event) => {
+      const seq = event.seq ?? 0 // 没有 seq 的事件视为边界之后
+      if (event.type === 'compaction/end') return { boundary: seq, promoted: false }
+      if (promote.has(event.type) && seq > state.boundary && !state.promoted) {
+        return { ...state, promoted: true }
       }
+      return state
     },
+    stateVersion: 1,
   }
 }
 
 /**
- * 解析一个会话所属的 agent 预设 id：header 记录创建时值，
- * `agent-preset/selected` 事件记录空白期切换后的值，后者优先。
+ * 当前 agent 的阶段。agent 缺席（纯清单读取等）或子代理一律已晋级；
+ * 投影 unit 未注册（服务缺席 / 尚未注册）时同样回落到已晋级。
  */
-export function presetOfSession(session) {
-  if (!session) return undefined
-  let preset = typeof session.header?.agentPreset === 'string' ? session.header.agentPreset : undefined
-  for (const event of session.events ?? []) {
-    if (event.type === 'agent-preset/selected' && typeof event.data?.agentPreset === 'string') {
-      preset = event.data.agentPreset
-    }
-  }
-  return preset
+export function statusOf(projections, agent) {
+  const session = agent?.session
+  if (!session) return PROMOTED_STATUS
+  if ((session.header?.delegationDepth ?? 0) > 0) return PROMOTED_STATUS
+  return projections?.stateOf?.(session, PHASE_PROJECTION_KEY) ?? PROMOTED_STATUS
 }
+
+/**
+ * 解析一个会话所属的 agent 预设 id：优先宿主 agent-presets 注册的 `agentPreset`
+ * 投影（header 记录创建时值，投影随 `agent-preset/selected` 事件推进），
+ * 投影缺席（无 roster 的组合）时回落到 header 的创建时值。
+ */
+export function presetOfSession(projections, session) {
+  if (!session) return undefined
+  const projected = projections?.stateOf?.(session, 'agentPreset')
+  if (typeof projected === 'string') return projected
+  return typeof session.header?.agentPreset === 'string' ? session.header.agentPreset : undefined
+}

package/lib/sectionOps.d.mts

@@ -30,3 +30,38 @@ export function phaseInjectEntries<T extends object>(
   key: PhaseKey,
   rows: T[],
 ): Array<Record<string, unknown>>
+/** 三态同步持久化：rowsByKey 给出三个阶段各自的有序行集合，生成完整 inject
+ *  列表（always 条目原样保留，三阶段各自连续虚拟 order）。 */
+export function mergedPhaseInjectEntries<T extends object>(
+  cfg: unknown,
+  rowsByKey: Record<PhaseKey, T[]>,
+): Array<Record<string, unknown>>
+/** 提示词 Tab 一个阶段部分的行（含屏蔽行与注入行）。 */
+export interface PhaseRow {
+  name: string
+  text: string
+  replaced: boolean
+  custom: boolean
+  override: string
+  blocked: boolean
+}
+/** 一个阶段部分的全部行（post ∪ 被屏蔽 ∪ 本阶段注入条目，草稿序叠加）。
+ *  `view` = 三阶段预览装配里对应阶段的视图（可为 null = 视为空）。 */
+export function phaseRows(cfg: unknown, view: unknown, key: PhaseKey): PhaseRow[]
+/** 「应用中文」（开关开启）一次性覆盖：三阶段行里名字命中 zhMap 的非自定义
+ *  行覆盖为中文译本，生成完整 inject 列表；未命中保持原样。zhMap 条目为字符
+ *  串或函数（入参该行原文，返回空值 = 放弃替换）。 */
+export function zhMergedInjectEntries(
+  cfg: unknown,
+  views: unknown,
+  zhMap: Record<string, string | ((original: string) => string | null | undefined)>,
+): Array<Record<string, unknown>>
+/** 「回归英文」（开关关闭）：命中译本的非自定义行清空替换文本（服务端回落
+ *  注册表英文原文），生成完整 inject 列表；自定义段不碰。 */
+export function zhRevertInjectEntries(
+  cfg: unknown,
+  views: unknown,
+  zhMap: Record<string, string | ((original: string) => string | null | undefined)>,
+): Array<Record<string, unknown>>
+/** 开关状态探测：任一注入条目文本等于字符串译本即视为已应用。 */
+export function zhApplied(cfg: unknown, zhMap: Record<string, string | ((original: string) => string | null | undefined)>): boolean