dsh-ppt-studio 1.1.0

package/lib/crosscheck.js

@@ -0,0 +1,300 @@
+/**
+ * 内容审阅材料包（M3 重写，2026-09-18 用户决定）——
+ *
+ * 旧版（v0.13.0 M3，2026-09-04）做两件事：跨页数字对账（同数字/百分比入组）+
+ * 证据核查表（页面 source → grounded / unmapped）。**2026-09-18 用户质疑后实测，该抽象层不成立**：
+ *   ① 数字必须放回整句/整页语境才有含义——按"数字字符串相同"分组只能确认**本来就一致**的数，
+ *      看不见**同指标不同值**。实测：故意在第 2 页写 毛利率 32%、第 3 页写 38% → 0 命中，
+ *      反而报了无害的 12%；fx-pro 12 页出 6 组、0 组可行动（40 字以内 vs 40px 混义成一组、
+ *      版本号 v1.0.0 被拆成 "1.0" 与 "0" 两组、提示文案里的数字入组）。
+ *   ② page.source 是作者自己写的一行自由文本，机器只判"有没有填"——它既不是证据（没有任何环节
+ *      去取/读/核对那份来源），也不进成品（全库唯一消费者就是这张表），grounded/unmapped 因此是
+ *      伪状态；且它按"页"判，封面/章节页也标 unmapped。
+ *
+ * 现职责（**只做精确、零判断的事**）：把审阅者需要一次看全的材料端上桌——
+ *   全页正文（阅读顺序，含表格/图表数据/讲稿/作者自述出处）+ 工作区实扫的外部素材清单 +
+ *   审阅协议（判定四分类：一致/冲突/无来源支撑/无法核实）。
+ * 判断交给人/模型（有独立子代理更佳，且**用户禁止子代理时严格自审**）。
+ * **本文件不产生任何判定、状态、比例或阈值**，因此既不进门禁，也不可能与门禁机制冲突。
+ */
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 内联正文上限（字符）：超过则内联前若干页 + 指明完整包路径（完整包永不截断）。 */
+const INLINE_BODY_CAP = 24000
+/** 素材扫描：可据以核对"有无依据"的文档类扩展名。 */
+const DATA_EXT = /\.(pptx|docx|xlsx|xls|csv|pdf|md|txt|json|html?)$/i
+/** 根目录里属于"本工具的产物"而非素材的文件（导出物不是依据）。 */
+const ARTIFACT_EXT = /^(out|out-surgical|out-claude|.*-spliced|.*-single|.*-rendered)\.pptx$/i
+
+const fmtBytes = (n) => (n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`)
+
+/** 单元格文本：markdown 表格里转义竖线、压掉换行（表格结构不能被我自己的渲染破坏）。 */
+const cell = (v) => String(v ?? '').replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ')
+
+/**
+ * 工作区实扫素材清单（客观事实，不含判断）。
+ * 只回答一个问题：**审阅者手上到底有没有可核对的外部依据**——这决定了外部主张该判
+ * "无来源支撑"还是"无法核实"（旧版把这两件事混成 unmapped 是错的）。
+ */
+export function scanMaterials(dir) {
+  const out = []
+  const push = (rel, role) => {
+    const abs = join(dir, rel)
+    if (!existsSync(abs)) return
+    let st
+    try { st = statSync(abs) } catch { return }
+    if (!st.isFile()) return
+    out.push({ path: rel, bytes: st.size, role })
+  }
+  const listDir = (rel) => {
+    const abs = join(dir, rel)
+    if (!existsSync(abs)) return []
+    try { return readdirSync(abs).sort() } catch { return [] }
+  }
+  // 双轨真相层（ppt_import / 模板工作区自带）
+  push('reference/source.pptx', '导入原稿（内容真相层）')
+  push('source.pptx', '导入原稿副本')
+  push('reference/template.pptx', '模板真相层')
+  push('reference/audit.yaml', '模板风格审计缓存')
+  for (const f of listDir(join('reference'))) {
+    if (f === 'source.pptx' || f === 'template.pptx' || f === 'audit.yaml') continue
+    push(join('reference', f), 'reference/ 其他文件')
+  }
+  for (const f of listDir(join('reference', 'previews'))) push(join('reference', 'previews', f), '原稿真渲染整页（需读图能力）')
+  // 用户素材（约定目录名）
+  for (const sub of ['materials', 'sources', '素材', 'docs']) {
+    for (const f of listDir(sub)) push(join(sub, f), '用户素材')
+  }
+  // 工程根目录的文档类文件（素材常常直接扔在根上）
+  for (const f of listDir('.')) {
+    if (!DATA_EXT.test(f) || ARTIFACT_EXT.test(f)) continue
+    push(f, '工程内文件')
+  }
+  // media/：图片素材，按目录聚合（不是数据依据，标注清楚免得审阅者误用）
+  const mediaFiles = listDir('media')
+  if (mediaFiles.length) {
+    let total = 0
+    for (const f of mediaFiles) { try { total += statSync(join(dir, 'media', f)).size } catch { /* 忽略单个文件错误 */ } }
+    out.push({ path: 'media/', bytes: total, role: `页面图片素材 ×${mediaFiles.length}（媒体，非数据依据）` })
+  }
+  return out
+}
+
+/**
+ * 汇总材料包数据（**纯函数、无副作用、无判定字段**）。
+ * 返回 { dir, title, size, pages: [...], materials: [...] }。
+ */
+export function crosscheckDeck(ctx) {
+  const dir = ctx.dir
+  const pages = (ctx.pages ?? []).map((p, i) => {
+    const page = p.page ?? {}
+    const els = Array.isArray(page.elements) ? page.elements : []
+    const texts = []
+    const tables = []
+    const charts = []
+    const images = []
+    for (const e of els) {
+      const id = e.elementId ?? '(无 id)'
+      const type = e.elementType ?? e.kind
+      if (type === 'text') {
+        const t = String(e.content?.text ?? e.text ?? '')
+        if (t) texts.push({ id, text: t })
+      } else if (type === 'table') {
+        tables.push({
+          id,
+          cols: (e.cols ?? []).map(String),
+          rows: (e.rows ?? []).map((r) => (Array.isArray(r) ? r : []).map(String)),
+        })
+      } else if (type === 'chart') {
+        const c = e.chart ?? {}
+        charts.push({
+          id,
+          type: String(c.type ?? '?'),
+          cols: (c.data?.cols ?? []).map(String),
+          rows: (c.data?.rows ?? []).map((r) => (Array.isArray(r) ? r : []).map(String)),
+        })
+      } else if (type === 'image') {
+        images.push({ id, src: String(e.src ?? e.content?.src ?? ''), fit: String(e.fit ?? e.content?.fit ?? '') })
+      }
+    }
+    return {
+      index: i + 1,
+      ref: p.ref ?? '',
+      pageType: String(page.pageType ?? '(未写)'),
+      title: page.title ? String(page.title) : null,
+      notes: page.notes ? String(page.notes) : '',
+      // 作者自述出处：**未经核实**，只当审阅线索（旧版据此判 grounded/unmapped 已废除）
+      authorSource: page.source ? String(page.source) : null,
+      texts,
+      tables,
+      charts,
+      images,
+    }
+  })
+  return {
+    dir,
+    title: String(ctx.deck?.title ?? ''),
+    size: ctx.size ?? null,
+    pages,
+    materials: scanMaterials(dir),
+  }
+}
+
+function renderMeta(d) {
+  const wh = d.size ? `${d.size.width}×${d.size.height}px` : '(未知尺寸)'
+  const lines = [
+    '# 内容审阅材料包',
+    '',
+    `- 工程：**${d.title || '(无标题)'}**｜页面 ${wh}｜共 **${d.pages.length} 页**`,
+    '- 生成：`ppt_crosscheck`（**只汇总材料，不做任何判定**——旧版"跨页数字分组 + grounded/unmapped 状态"已于 2026-09-18 废除：数字必须放回整句语境才有含义，来源标注是作者自述而非证据）',
+    '- 用途：把判定所需材料一次看全。**判定在下文第三节的审阅协议里产生，由审阅者给出**。',
+    '- 下一步：按协议执行内容审阅——**默认独立子代理**（全新上下文，只给本包与素材；用户明确禁止子代理时改自审并标注）。本工具不构成门禁。',
+    '',
+  ]
+  return lines.join('\n')
+}
+
+function renderMaterials(d) {
+  const lines = ['## 二、可核对的外部素材（工作区实扫，客观清单）', '']
+  if (!d.materials.length) {
+    lines.push('**未发现任何外部素材。**', '')
+    lines.push('→ 由此决定判定口径：涉及外部事实/数字的主张本次**只能判「无法核实」**——不得判「一致」（没有依据可依），也不得判「无来源支撑」（那是猜，不是核实）。')
+    return lines.join('\n')
+  }
+  lines.push('| 文件 | 大小 | 用途 |', '|---|---|---|')
+  for (const m of d.materials) lines.push(`| \`${m.path}\` | ${fmtBytes(m.bytes)} | ${m.role} |`)
+  lines.push('')
+  const checkable = d.materials.filter((m) => /导入原稿|模板真相层|用户素材|工程内文件/.test(m.role))
+  const visualOnly = d.materials.filter((m) => /真渲染整页|图片素材/.test(m.role))
+  lines.push(checkable.length
+    ? `可据以判定"有无依据"的素材：**${checkable.length} 项**（原稿/文档类）。审阅者应当实际打开它们比对，而不是凭印象。`
+    : `**只有图片/预览类素材（${visualOnly.length} 项）**：图片里的数字需读图能力才能核对；读不到就判「无法核实」，不要猜。`)
+  return lines.join('\n')
+}
+
+function renderPageSection(p) {
+  const lines = [`### 第 ${p.index} 页 · \`${p.ref}\``, '']
+  const head = [`类型 \`${p.pageType}\``]
+  if (p.title) head.push(`标题 \`${p.title}\``)
+  lines.push(`- ${head.join('｜')}`)
+  if (p.authorSource) lines.push(`- 作者自述出处（**未核实**，仅线索）：\`${p.authorSource}\``)
+  if (!p.texts.length && !p.tables.length && !p.charts.length && !p.images.length) {
+    lines.push('- （本页无文字/表格/图表/图片元素）')
+  }
+  for (const t of p.texts) {
+    if (t.text.includes('\n')) {
+      lines.push(`- 文本 \`${t.id}\`：`)
+      for (const l of t.text.split('\n')) lines.push(`  > ${l}`)
+    } else {
+      lines.push(`- 文本 \`${t.id}\`：${t.text}`)
+    }
+  }
+  for (const t of p.tables) {
+    lines.push(`- 表格 \`${t.id}\`（${t.cols.length} 列 × ${t.rows.length} 行）：`)
+    lines.push(`  | ${t.cols.map(cell).join(' | ')} |`)
+    lines.push(`  |${' --- |'.repeat(Math.max(1, t.cols.length))}`)
+    for (const r of t.rows) lines.push(`  | ${r.map(cell).join(' | ')} |`)
+  }
+  for (const c of p.charts) {
+    lines.push(`- 图表 \`${c.id}\`：${c.type}｜列 \`${c.cols.join('、')}\``)
+    for (const r of c.rows) lines.push(`  - ${r.map(cell).join('｜')}`)
+  }
+  for (const im of p.images) lines.push(`- 图片 \`${im.id}\`：\`${im.src}\`${im.fit ? `（fit ${im.fit}）` : ''}`)
+  if (p.notes) {
+    lines.push('- 讲稿（notes，会导出为备注页）：')
+    for (const l of p.notes.split('\n')) lines.push(`  > ${l}`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * 审阅协议：**工具本身不判定**，判定标准与方法在这里写给审阅者（人 或 模型/子代理）。
+ * 注意：本节内不出现反引号，避免与模板字符串转义纠缠（纯文本，读起来等价）。
+ */
+const PROTOCOL = [
+  '## 四、审阅协议（给审阅者：判定在这里产生，本工具不判定）',
+  '',
+  '### 目标（三件事）',
+  '1. **内容前后一致**：同一事实、指标、名称、时间范围、口径在不同页之间不得互相矛盾。',
+  '2. **数据不冲突**：同一指标在同一口径/同一期间下，不得在不同页出现不同值。',
+  '3. **无编造/曲解**：具体数字与事实须能在上面素材中找到依据；结论不得强于所引数据（不得把相关性说成因果、不得丢掉限定条件、不得断章取义、不得把目标写成已完成）。',
+  '',
+  '### 审阅方式（按优先级，且必须服从用户指令）',
+  '1. **用户明确要求"不要使用子代理"（或同义要求）→ 自审**：在同一上下文里逐条核对，报告开头必须写「自审（同上下文，可信度较低）」。**此时不得改用子代理。**',
+  '2. 用户未禁止、且当前会话有独立子代理能力（如 subagent 工具）→ **优先用独立子代理审阅**：全新上下文、只给本材料包（preview/review-pack.md）与素材文件、**不给**作者的推理过程或结论；报告标注「独立子代理审阅」。',
+  '3. 两者都没有 → 自审，并同样标注。',
+  '无论哪种方式：**审阅必须真的发生**——不得跳过，也不得只回一句"已核查、无问题"。',
+  '',
+  '### 判定四分类（每条只能取其一，且必须给页码 + 原句）',
+  '- **一致**：与素材或其他页一致。',
+  '- **冲突**：同一指标/事实在不同页出现不同值或相反表述——必须同时列出两处原文。',
+  '- **无来源支撑**：**仅当**上面确实列有可核对素材、且在其中找不到依据时使用（疑似编造或曲解）。',
+  '- **无法核实**：未提供素材，或素材未覆盖该主张——**不得因为"没有素材"就判「一致」，也不得判「无来源支撑」**。',
+  '',
+  '### 必须逐条回答（避免空转式结论）',
+  '1. 列出正文中全部具体数字/百分比与页码，逐条给判定（并说明单位与口径是否写清）。',
+  '2. 指出同一指标在多页出现的位置，判定值/单位/时间范围是否一致。',
+  '3. 列出无法在素材中找到依据的具体主张（有素材时）。',
+  '4. 列出结论强于数据的表述（如"显著领先/第一/翻倍"而没有支撑数据）。',
+  '5. 声明本次未覆盖的范围（素材缺失、图片无法读、正文被截断等）——**不得把未覆盖说成已通过**。',
+  '',
+  '### 输出格式与纪律',
+  '- markdown 表：`主张/数字 | 页码 | 判定 | 依据（原句或素材出处）`，其后给「必须修改项」与「建议项」。',
+  '- 审阅者**不得修改任何文件**；发现问题只报告，不改写引文来凑判定。',
+  '- 边界：本协议只管**语义一致性**；版式/溢出/重叠/出界由 `ppt_verify` 等门禁负责，不要混。',
+  '- 什么时候跑：有具体数字/事实主张的稿子，交付前跑一次；纯装饰稿可跳过（省成本）。',
+  '',
+].join('\n')
+
+/**
+ * 工具输出（markdown）：完整包落盘 `preview/review-pack.md`，内联部分超上限时明确声明未内联的页
+ * （**绝不静默截断**——审阅者必须知道自己没看到什么）。
+ */
+export function crosscheckReport(ctx) {
+  const d = crosscheckDeck(ctx)
+  const meta = renderMeta(d)
+  const materials = renderMaterials(d)
+  const bodyHead = `## 三、正文（阅读顺序，共 ${d.pages.length} 页）\n`
+  const secs = d.pages.map(renderPageSection)
+  const fullBody = bodyHead + '\n' + secs.join('\n')
+  const pack = `${meta}\n${materials}\n\n${fullBody.trimEnd()}\n\n${PROTOCOL}`
+
+  let saved = null
+  let saveErr = null
+  try {
+    mkdirSync(join(d.dir, 'preview'), { recursive: true })
+    writeFileSync(join(d.dir, 'preview', 'review-pack.md'), pack, 'utf8')
+    saved = 'preview/review-pack.md'
+  } catch (e) { saveErr = String(e?.message ?? e) }
+
+  let inlineBody = fullBody
+  let trunc = null
+  if (saved && fullBody.length > INLINE_BODY_CAP) {
+    let acc = ''
+    let kept = 0
+    for (const s of secs) {
+      if (acc.length + s.length > INLINE_BODY_CAP) break
+      acc += s
+      kept += 1
+    }
+    const omitted = d.pages.slice(kept).map((p) => p.index)
+    trunc = [
+      `> ⚠ 正文 ${fullBody.length} 字符 > 内联上限 ${INLINE_BODY_CAP}：**以下只内联前 ${kept} 页**（第 ${omitted.join('、')} 页未内联）。`,
+      `> 审阅者**必须**读完整包 \`${saved}\`（含全部 ${d.pages.length} 页）；未读全不得判"全册一致"，并须在第 5 条里声明未覆盖页。`,
+      '',
+    ].join('\n')
+    inlineBody = bodyHead + '\n' + trunc + '\n' + acc
+  }
+  if (!saved) {
+    inlineBody = `${fullBody}\n> ⚠ 材料包未能落盘（${saveErr ?? '未知原因'}）——以上为完整内联，请直接据本文审阅。\n`
+  }
+
+  const pointer = saved
+    ? `- 完整包已落盘：\`${join(d.dir, 'preview', 'review-pack.md')}\`（同一内容；子代理审阅请让它直接读该文件）`
+    : ''
+  const head = [meta.trimEnd(), pointer].filter(Boolean).join('\n')
+  // 分隔线前必须留空行：正文最后一行是列表项，紧贴 `---` 会被 markdown 当成 setext 标题下划线
+  return `${head}\n\n---\n\n${materials}\n\n---\n\n${inlineBody.trimEnd()}\n\n---\n\n${PROTOCOL}`
+}

package/lib/imgmeta.js

@@ -0,0 +1,55 @@
+/**
+ * 图片元数据：从文件头读宽高/格式（无需视觉模型；任何环境可用）。
+ * 支持 PNG / JPEG / GIF / WebP。
+ */
+
+export function imageInfo(file) {
+  const head = file.subarray(0, 64)
+  if (head.length >= 24 && head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47) {
+    return { format: 'png', width: head.readUInt32BE(16), height: head.readUInt32BE(20) }
+  }
+  if (head.length >= 10 && head[0] === 0xff && head[1] === 0xd8) {
+    return jpegSize(file)
+  }
+  if (head.length >= 10 && head[0] === 0x47 && head[1] === 0x49 && head[2] === 0x46) {
+    return { format: 'gif', width: head.readUInt16LE(6), height: head.readUInt16LE(8) }
+  }
+  if (head.length >= 30 && head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46) {
+    if (head.subarray(8, 12).toString() === 'WEBP') return webpSize(file)
+  }
+  return { format: 'unknown', width: 0, height: 0 }
+}
+
+function jpegSize(file) {
+  let p = 2
+  while (p + 9 < file.length) {
+    if (file[p] !== 0xff) { p++; continue }
+    const marker = file[p + 1]
+    if (marker >= 0xc0 && marker <= 0xc3 || marker >= 0xc5 && marker <= 0xc7 || marker >= 0xc9 && marker <= 0xcb || marker >= 0xcd && marker <= 0xcf) {
+      return { format: 'jpeg', width: file.readUInt16BE(p + 7), height: file.readUInt16BE(p + 5) }
+    }
+    const len = file.readUInt16BE(p + 2)
+    p += 2 + len
+  }
+  return { format: 'jpeg', width: 0, height: 0 }
+}
+
+function webpSize(file) {
+  const kind = file.subarray(12, 16).toString()
+  if (kind === 'VP8 ') {
+    return { format: 'webp', width: file.readUInt16LE(26) & 0x3fff, height: file.readUInt16LE(28) & 0x3fff }
+  }
+  if (kind === 'VP8L') {
+    const b = file.subarray(20, 25)
+    const bits = b[0] | (b[1] << 8) | (b[2] << 16) | (b[3] << 24) | (b[4] << 32)
+    return { format: 'webp', width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 }
+  }
+  if (kind === 'VP8X') {
+    return {
+      format: 'webp',
+      width: 1 + (file[24] | (file[25] << 8) | (file[26] << 16)),
+      height: 1 + (file[27] | (file[28] << 8) | (file[29] << 16)),
+    }
+  }
+  return { format: 'webp', width: 0, height: 0 }
+}

package/lib/index.js

@@ -0,0 +1,239 @@
+/**
+ * dsh-ppt-studio —— PPT 工作室插件（host）。
+ *
+ * 装配模型（2026-09-24 **第三次修订：适配 DSH 0.1.7-rc.1**）：
+ *   `apply()` 做四件事——① 装配防重；② **全局管道**（/ppt-preview 路由、预设**声明**、语义路由）；
+ *   ③ 工作流提示段注入（`system-prompt/assemble`）；④ **在本 ctx 注册全部能力面**：
+ *   22 个 `ppt_*` 工具 / `/ppt` 命令面 / `ppt_state` / 4 本内嵌技能。
+ *   ⇒ **装上插件，所有会话都能用**（= 1.0.0 的行为）。
+ *
+ * 0.1.7 的那一处真适配是**预设交付**：宿主不再扫描 `<dshHome>/.agent-presets/`（上游原文
+ * "the harness discovers no preset on disk"），预设改为向 `agentPresets` 注册表**声明**。
+ * 详见 src/preset-delivery.js 顶部（含 `!!js` 保真与相对名解析这两条源码级细节）。
+ *
+ * 为什么放弃了"只让「PPT 工作室」预设看到"（两件事，都有实测与源码依据）：
+ *   ① **切换预设拿不到**：空白会话切预设时 `agent-presets.swap` 确实会 `recompose(agent.ctx, id)`，
+ *      但那一刻该 agent **已经存在**，而我们的 `agent/created` 监听者是在这次组合里才注册的
+ *      ⇒ 它永远不会为这个已有 agent 触发 ⇒ "先建会话再切到该预设"永远看不到工具
+ *      （用户实测：只有一开始就建在该预设上才有工具）。
+ *   ② **技能在父层读不到**：技能注册表分层，技能工具在**预设层**读；我们只能注册到 `agent.ctx`（子层）
+ *      或 profile 根 ⇒ 预设层读不到 ⇒ 技能永不出现。而"用预设行挂载"这条路同样封死
+ *      （行里的裸包名按 **harness base** 解析，不是 profile ⇒ 预设被判 `broken` ⇒ 选择器不显示它）。
+ *   ⇒ 在这版 DSH 上，"按预设隔离"无法可靠交付。宁可**功能完整、行为可预期**，也不要"看起来隔离、
+ *      实际一半会话没能力面"。隔离代码留在 git 历史（`4ea7037` 起的提交）里，等 DSH 提供稳定的
+ *      "预设已组合/已切换"信号再恢复。
+ *
+ * 「PPT 工作室」预设仍然存在并自交付：它负责**身份/人格**（名字、简介、standard 能力面副本）。
+ */
+import { registerTools, defineTool } from './tools.js'
+import { registerCommands } from './commands.js'
+import { loadSession, saveSession } from './state.js'
+import { isPptIntent, isPptOff, isQuickIntent, detectTaskType, workflowSection } from './router.js'
+import { registerPreviewRoute } from './preview-server.js'
+import { registerManualSkill, manualSkillStatus } from './skill.js'
+import { declareAgentPreset, presetDeliveryStatus } from './preset-delivery.js'
+import { existsSync, statSync, mkdirSync, appendFileSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const name = 'dsh-ppt-studio'
+// skills 为可选依赖（ctx.get('skills')）：极简装配缺 dsh-skill 时插件仍完整可用
+export const inject = ['tools', 'commands', 'systemPrompt']
+
+function loggerOf(ctx) {
+  try { return typeof ctx.logger === 'function' ? ctx.logger('ppt-studio') : ctx.logger } catch { return undefined }
+}
+
+/**
+ * 按需诊断日志（**默认关闭**）：`PPT_STUDIO_DEBUG=1`，或存在 `<dshHome>/ppt-studio/debug.on` 时启用。
+ *
+ * 为什么需要它（2026-09-18 的真实排查困境）：本插件的"不生效"有三种完全不同的原因——
+ *   ① 插件没被加载（装法/装配问题）；② 加载了，但门控判成"这个 agent 不属于本插件"；
+ *   ③ 门控放行，但能力面挂到 agent 作用域时失败。
+ * 三者在 UI 上**长得一模一样**（都看不到工具），而会话里一个工具都没有时**什么都问不了**
+ * （连诊断工具本身都没挂上）——所以诊断必须写到**文件**，不依赖"模型肯不肯说"。
+ * 每次判定一行；超过 256KB 时截断保留尾部。
+ */
+function diag(event, detail = '') {
+  try {
+    const home = process.env.DSH_HOME || join(process.env.USERPROFILE || process.env.HOME || '', '.dsh')
+    const dir = join(home, 'ppt-studio')
+    const on = process.env.PPT_STUDIO_DEBUG === '1' || existsSync(join(dir, 'debug.on'))
+    if (!on) return
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, 'debug.log')
+    try { if (existsSync(file) && statSync(file).size > 256 * 1024) {
+      const buf = readFileSync(file); writeFileSync(file, buf.subarray(buf.length - 128 * 1024))
+    } } catch { /* 忽略 */ }
+    appendFileSync(file, `${new Date().toISOString()}  ${event}  ${detail}\n`, 'utf8')
+  } catch { /* 诊断永不抛 */ }
+}
+
+export function apply(ctx, config = {}) {
+  diag('apply', `baseUrl=${String(ctx?.baseUrl ?? '(无)').slice(0, 90)}`
+    + `｜agentPresets=${(() => { try { return ctx.get('agentPresets') ? '可见' : '不可见' } catch { return '取用抛错' } })()}`
+    + `｜presetIds=${JSON.stringify(config?.presetIds ?? ['ppt'])}｜pid=${process.pid}`)
+  // ── 装配防重（2026-09-14 新增 profile bundle 安装路径后必需）────────────────────────
+  // 同一个包可能在**同一进程**里被挂两次：
+  //   ① profile bundle 行（包的 cordis.patch.yml，`dsh plugin add` 装完即挂）；
+  //   ② 预设内的插件行（`--isolate` 模式把本包挂进「PPT 工作室」预设的组合里）。
+  // 首个挂载真正装配，后续只计数（注册仍归各自 ctx.effect 所有，owner ctx 卸载即释放）。
+  // 第二条在本版本上更重要：预设声明会随第二次装配**重复注册**，而注册表对重复 id 直接
+  // throw（`Duplicate agent preset`）——防重同时挡住了这个双挂载事故。
+  const CORE = globalThis.__pptCoreReg ?? { count: 0 }
+  globalThis.__pptCoreReg = CORE
+  if (CORE.count > 0) {
+    CORE.count++
+    try {
+      loggerOf(ctx)?.warn?.('[ppt-studio] 本包在同一进程被挂载了两次（profile bundle 行 + 预设内的插件行？）——'
+        + '已按"首个生效"跳过本次装配。两者是替代关系，建议二选一：`dsh plugin --profile <p> remove <包>` 或改用 `--isolate` 安装（见 README §0.7）。')
+    } catch { /* 无 logger 时静默 */ }
+    ctx.effect(() => () => { CORE.count-- }, 'ppt-studio: duplicate mount (ref)')
+    return
+  }
+  CORE.count++
+  // 注意 Cordis 语义：`ctx.effect(cb)` **立即执行 cb**，并用 cb 的**返回值**当 disposer。
+  // 所以计数递减必须写成"返回一个函数"（写成 `() => { count-- }` 会当场递减，等于没防重——
+  // 这个错误由 smoke 的行为断言当场抓到）。
+  ctx.effect(() => () => { CORE.count-- }, 'ppt-studio: core mount (ref)')
+
+  // ── 全局管道（与会话无关）──────────────────────────────────────────────────────
+  registerPreviewRoute(ctx) // /ppt-preview/ 路由（无 webServer 环境自动跳过）
+  // 声明「PPT 工作室」预设（0.1.7 起：注册表声明，不再写预设目录——目录已无发现路径）。
+  // 失败只告警不抛；状态经 ppt_state 的 presetDelivery 暴露，避免"预设没出现"只能翻日志。
+  declareAgentPreset(ctx, config)
+
+  // 语义路由：user/message → 激活/退出（auto 模式）。只写会话状态文件，不暴露任何能力面。
+  ctx.on('session/event', async (session, event) => {
+    if (event.type !== 'user/message') return
+    const data = event.data ?? {}
+    if (data.source?.kind !== 'user' && data.source?.kind !== undefined) return
+    const text = extractText(data)
+    const attachments = data.attachments ?? []
+    try {
+      const state = await loadSession(session.id)
+      if (state.routing === 'off') return
+      if (state.routing === 'on') { state.workflowActive = true; await saveSession(session.id, state); return }
+      // auto：语义判断
+      if (!state.workflowActive && isPptIntent(text, attachments)) {
+        state.workflowActive = true
+        state.taskType = detectTaskType(text)
+        if (isQuickIntent(text)) state.quick = true
+        await saveSession(session.id, state)
+      } else if (state.workflowActive && isPptOff(text) && !attachments.some((a) => /\.pptx?$/i.test(a.name ?? a.path ?? ''))) {
+        state.workflowActive = false
+        await saveSession(session.id, state)
+      } else if (state.workflowActive && isQuickIntent(text, true)) {
+        state.quick = true
+        await saveSession(session.id, state)
+      }
+    } catch { /* 防缺失目录等异常 */ }
+  })
+
+  // 工作流提示词注入（**不按预设门控**——见下"回滚"说明）
+  ctx.on('system-prompt/assemble', async (assembly, context, next) => {
+    const assembled = await next()
+    const agent = context.agent
+    if (!agent?.session?.id) return assembled
+    const sessionId = agent.session.id
+    let state
+    try { state = await loadSession(sessionId) } catch { return assembled }
+    if (!state.workflowActive) return assembled
+    const sections = [...(assembled.sections ?? [])]
+    const idx = sections.findIndex((s) => s?.name === 'ppt-workflow')
+    if (idx >= 0) sections.splice(idx, 1)
+    sections.push(workflowSection(state.taskType ?? 'unknown', state))
+    return { ...assembled, sections }
+  })
+
+  // ── 能力面：注册在**本 ctx**（= 装它的那一层）——2026-09-18 第二轮回滚 ──────────────────
+  // 背景（用户实测 + DSH 源码实锤，两件事一起推翻了"按预设隔离"这条路）：
+  //   ① **切换预设拿不到能力面**：空白会话切预设（`agent-presets.swap`）确实会
+  //      `recompose(agent.ctx, id)` 重新组合，但那一刻**该 agent 已经存在**——我们的
+  //      `agent/created` 监听者是在这次组合中才注册的，**永远不会**为这个已有 agent 触发。
+  //      于是"先建会话再切过去"= 工具永远不出现（用户原话：只有一开始就是该预设才有工具）。
+  //   ② **技能在预设层读不到**：注册表是**分层**的（`dsh-skill` 的 preset 层），而技能工具
+  //      （`tool-skill`）在**预设层**读；我们注册进 `agent.ctx`（子层）⇒ 父层读不到 ⇒ 技能永远不出现。
+  //      在 profile bundle 装法下我们的 ctx 就是 profile 根，**够不到预设层**，
+  //      而预设行又无法解析本包（行按 harness base 解析，见 preset 模板末尾说明）⇒ 这条路封死。
+  // 结论：本 DSH 版本上"只让某个预设看到工具/技能"**无法可靠交付**。按用户指示回滚到
+  // 「装上插件 → 所有会话都能用」这一久经验证的行为（= 1.0.0 的行为），并把预设保留为**身份/人格**。
+  const faces = []
+  const step = (label, fn) => { try { fn() } catch (e) { faces.push(`${label}: ${String(e?.message ?? e)}`) } }
+  step('tools', () => registerTools(ctx))
+  step('commands', () => registerCommands(ctx))
+  step('ppt_state', () => statusToolFor(ctx))
+  step('skills', () => registerManualSkill(ctx))
+  if (faces.length) loggerOf(ctx)?.warn?.(`[ppt-studio] 部分能力面注册失败：${faces.join('；')}`)
+  diag('faces', `tools/commands/ppt_state/skills 已注册在 apply ctx（回滚为全局可见）｜失败=${faces.length ? faces.join(';') : '无'}`)
+}
+
+/**
+ * 【已删除】`mountForAgent` / `agentIsOurs` / `computeOurs`（2026-09-18 第二次修订回滚）
+ *
+ * 它们实现了"只让「PPT 工作室」预设的会话看到工具/技能"，但在这版 DSH 上**无法可靠交付**：
+ *   ① 空白会话**切换**预设时，`agent-presets.swap` 会 `recompose(agent.ctx, id)`，可那一刻该 agent
+ *      已经存在——我们的 `agent/created` 监听者是这次组合才注册的，**不会**为它触发 ⇒ 工具永不出现
+ *      （用户实测：只有一开始就是该预设才有工具）；
+ *   ② 技能注册表是**分层**的，技能工具在**预设层**读，而我们只能注册到 `agent.ctx`（子层）或
+ *      profile 根 ⇒ 父层读不到 ⇒ 技能永不出现；而"预设行挂载"这条路又被
+ *      "行按 harness base 解析"封死（见 agent-presets/ppt/agent.cordis.yml 末尾说明）。
+ * 代码留在 git 历史里（提交 4ea7037 起）。
+ *
+ * 【2026-09-24 补注（0.1.7-rc.1）】当时封死"预设行挂载"的那条判据**依然成立**：注册表 mount 预设时
+ * 用 `scope.ctx.extend({ baseUrl: <注册表所在 ctx 的 baseUrl> })`（= harness base），裸包名
+ * `dsh-ppt-studio` 在那里解析不到 ⇒ 预设会被判 broken。所以现在的 `--isolate` 走的是
+ * 另一条路：**不挂 profile bundle**，把插件行写进预设声明的 `plugins` 里，并给插件行
+ * `autoPreset:false`（预设已由该声明本身提供，插件不能再声明一次）。本注释里的
+ * `mountForAgent` 是"插件自己在运行时按 agent 门控"那套，与上面这条不同，仍然不恢复。
+ */
+
+function extractText(data) {
+  const c = data.content
+  if (typeof c === 'string') return c
+  if (Array.isArray(c)) return c.filter((b) => b.type === 'text').map((b) => b.text ?? '').join(' ')
+  return ''
+}
+
+/** 调试工具（agent 可见）：当前工作流状态。 */
+export function statusToolFor(ctx) {
+  return ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'ppt_state',
+    description: '查看/更新 PPT 工作流会话状态（档位/激活）。debug/自优化用',
+    parameters: {
+      set: { type: 'string', description: '可选 key=value（如 mode=strict workflowActive=true）' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
+    async execute(args, exec) {
+      // 会话 id 取自工具执行的 agent（DSH 的 execute(args, exec) 第二参数）；
+      // 历史坑：ctx.get('agent') 恒为 undefined（DSH 只有 agents 服务），会误落到 'default' 会话文件。
+      const agent = exec?.agent
+      const sid = agent?.session?.id ?? agent?.id ?? 'default'
+      const state = await loadSession(sid)
+      if (args.set) {
+        for (const kv of String(args.set).split(/\s+/)) {
+          const [k, ...rest] = kv.split('=')
+          const v = rest.join('=')
+          if (k && v !== undefined) state[k] = v === 'true' ? true : v === 'false' ? false : v === 'null' ? null : v
+        }
+        await saveSession(sid, state)
+      }
+      // 交付通道自检：内嵌技能在技能注册表里是否可见（自包含诊断，不依赖外部工具）
+      const delivery = manualSkillStatus()
+      try {
+        const skills = ctx.get('skills')
+        if (skills === undefined) delivery.visible = 'skills 服务缺失'
+        else {
+          const rows = []
+          for (const s of delivery.skills) {
+            const one = await skills.get(s.name)
+            rows.push(`${s.name}=${one === undefined ? 'MISSING' : `${String(one.provider)}/${String(one.source)}/len=${String(one.content).length}`}`)
+          }
+          delivery.visible = rows.length ? rows.join(' · ') : 'MISSING'
+        }
+      } catch (error) {
+        delivery.visible = `查询失败：${error?.message ?? error}`
+      }
+      return JSON.stringify({ session: sid, state, manualSkill: delivery, presetDelivery: presetDeliveryStatus() }, null, 2)
+    },
+  })), 'ppt-studio: ppt_state')
+}