dsh-ppt-studio 1.1.2 → 1.1.4

package/lib/pptd/svgCharts.js

@@ -1,7 +1,13 @@
 /**
  * 图表 SVG 生成（HTML 预览用）：bar / line / pie。
- * ppbx 导出用矢量拼绘（见 export-pptx.js），两处共用数据解析。
+ * 导出侧：原生可编辑图表（默认，见 nativeChart.js）或矢量拼绘（`render: 'vector'`，见 export-pptx.js 的 chartSp）。
+ *
+ * 第三轮（2026-09-27）**预览与成品对齐**：原生图表自带坐标轴/网格线/刻度标签/图例/数据标签，
+ * SVG 也必须画这些——否则"预览 ≠ 成品"，模型与用户会被误导（ppt_shot/ppt_measure 的输入就是这份 SVG）。
+ * 三层同源：`chartOptions()`（schema.js 给默认）→ `resolveChart()`（本文件，落地 auto 默认）→
+ * 预览 SVG 与导出 chartN.xml 都读同一个 resolveChart 结果。
  */
+import { chartOptions } from './schema.js'
 
 /** 解析 chart 数据为 { categories: [...], values: [number], series: [{name, values}] } */
 export function chartData(chart) {
@@ -33,6 +39,33 @@ export function chartData(chart) {
   return out
 }
 
+/**
+ * 解析成"预览/导出共用"的图表模型（**唯一真相**）：
+ * 类别、系列（名 + 数值）、分类列名、配色、已落地的渲染选项（render/legend/labels/axes）。
+ */
+export function resolveChart(chart) {
+  const data = chartData(chart)
+  const cols = chart?.data?.cols ?? []
+  const series = data.series.map((s, i) => ({ name: String(s.name ?? `系列${i + 1}`), values: s.values }))
+  const opt = chartOptions(chart)
+  const multi = series.length > 1
+  const vector = opt.render === 'vector'
+  // auto 语义（schema.js chartOptions 注释里有同一份说明）：多系列/饼图才有必要画图例；单系列图例是噪音。
+  const legend = vector ? false : (opt.legend === 'auto' ? (chart?.type === 'pie' || multi ? 'bottom' : false) : opt.legend)
+  // auto 语义：饼图的"百分比 + 分类名"是必要信息；柱/线逐点标数字会糊。
+  const labels = vector ? false : (opt.labels === 'auto' ? (chart?.type === 'pie') : opt.labels)
+  // 矢量拼绘（chartSp）不画坐标轴/网格线 ⇒ 预览也不画（否则"预览 ≠ 成品"）。schema 对 vector+axes 显式值直接报错。
+  const axes = vector ? false : opt.axes
+  return {
+    type: chart?.type,
+    categories: data.categories,
+    series,
+    catHeader: String(cols[0] ?? '类别'),
+    colors: chartColors(chart),
+    opts: { render: opt.render, legend, labels, axes },
+  }
+}
+
 /**
  * 图表数据检查（P1 修复，v0.6.1）：把"静默失败"变显式。
  * 返回问题描述字符串或 null（正常）。
@@ -58,54 +91,86 @@ export function chartColors(chart) {
   return (chart.colors?.length ? chart.colors : PALETTE).map((c) => c)
 }
 
-/** 生成 SVG 字符串；viewBox 由调用方传入（px 坐标）。
- * padding: 坐标轴留白 [t, r, b, l] 默认 [8, 12, 24, 12]。
+const GRID = '#e2e8f0'
+const AXIS = '#cbd5e1'
+const TICK_TEXT = '#64748b'
+
+/**
+ * 生成 SVG 字符串；viewBox 由调用方传入（px 坐标）。
+ * 与成品对齐的内容：坐标轴（轴线+刻度）、网格线、刻度标签、分类标签、图例、数据标签。
  */
 export function chartSvg(chart, w, h) {
-  const data = chartData(chart)
-  const colors = chartColors(chart)
-  const pad = { t: 12, r: 12, b: data.categories.length ? 28 : 12, l: 36 }
+  const m = resolveChart(chart)
+  const colors = m.colors
+  const colorOf = (i) => colors[i % colors.length]
+  const n = m.categories.length
+  const vals = m.series.flatMap((s) => s.values)
+  const maxV = Math.max(1e-9, ...vals)
+  const minV = Math.min(0, ...vals)
+  const span = Math.max(1e-9, maxV - minV)
+  const showAxes = m.type !== 'pie' && m.opts.axes !== false
+
+  // ── 图例（与原生图表的 c:legend 同位置）──
+  const legendItems = m.type === 'pie'
+    ? m.categories.map((c, i) => ({ label: c, color: colorOf(i) }))
+    : m.series.map((s, i) => ({ label: s.name, color: colorOf(i) }))
+  const legend = m.opts.legend ? layoutLegend(legendItems, w, h, m.opts.legend) : null
+
+  const pad = { t: 12, r: 12, b: showAxes && n ? 28 : 12, l: showAxes ? 36 : 12 }
+  if (legend?.pos === 'top') pad.t += legend.h
+  if (legend?.pos === 'bottom') pad.b += legend.h
+  if (legend?.pos === 'left') pad.l += legend.w
+  if (legend?.pos === 'right') pad.r += legend.w
+  if (m.opts.labels && m.type !== 'pie') pad.t += 12 // 数据标签要地方
   const iw = Math.max(1, w - pad.l - pad.r)
   const ih = Math.max(1, h - pad.t - pad.b)
-  const maxV = Math.max(1e-9, ...data.series.flatMap((s) => s.values))
-  const minV = Math.min(0, ...data.series.flatMap((s) => s.values))
-  const span = Math.max(1e-9, maxV - minV)
+  const slot = iw / Math.max(1, n)
   const y0 = pad.t + (maxV / span) * ih
   const y = (v) => pad.t + ((maxV - v) / span) * ih
   const parts = []
-  // gridline + y 轴刻度
-  for (let i = 0; i <= 4; i++) {
-    const gy = pad.t + (ih * i) / 4
-    parts.push(`<line x1="${pad.l}" y1="${gy}" x2="${w - pad.r}" y2="${gy}" stroke="#e2e8f0" stroke-width="1"/>`)
-    const gv = maxV - (span * i) / 4
-    parts.push(`<text x="${pad.l - 4}" y="${gy + 3}" font-size="9" fill="#64748b" text-anchor="end">${fmtNum(gv)}</text>`)
+
+  // 网格线 + 值轴刻度标签 + 刻度线
+  if (showAxes) {
+    for (let i = 0; i <= 4; i++) {
+      const gy = pad.t + (ih * i) / 4
+      parts.push(`<line x1="${pad.l}" y1="${gy.toFixed(1)}" x2="${(w - pad.r).toFixed(1)}" y2="${gy.toFixed(1)}" stroke="${GRID}" stroke-width="1"/>`)
+      parts.push(`<line x1="${pad.l - 3}" y1="${gy.toFixed(1)}" x2="${pad.l}" y2="${gy.toFixed(1)}" stroke="${AXIS}" stroke-width="1"/>`)
+      const gv = maxV - (span * i) / 4
+      parts.push(`<text x="${pad.l - 5}" y="${(gy + 3).toFixed(1)}" font-size="9" fill="${TICK_TEXT}" text-anchor="end">${fmtNum(gv)}</text>`)
+    }
+    // 坐标轴轴线（原生图表有，预览以前没有 ⇒ 补齐）
+    parts.push(`<line x1="${pad.l}" y1="${pad.t}" x2="${pad.l}" y2="${(pad.t + ih).toFixed(1)}" stroke="${AXIS}" stroke-width="1"/>`)
+    parts.push(`<line x1="${pad.l}" y1="${(pad.t + ih).toFixed(1)}" x2="${(w - pad.r).toFixed(1)}" y2="${(pad.t + ih).toFixed(1)}" stroke="${AXIS}" stroke-width="1"/>`)
   }
-  const n = data.categories.length
-  const grouped = data.series.length > 1 && chart.type === 'bar'
-  const slot = iw / Math.max(1, n)
-  if (chart.type === 'bar') {
-    const sGroup = grouped ? 0.72 : 1
-    data.series.forEach((s, si) => {
+
+  if (m.type === 'bar') {
+    const grouped = m.series.length > 1
+    m.series.forEach((s, si) => {
       s.values.forEach((v, i) => {
         const cx = pad.l + slot * i + slot / 2
-        const bw = groupWidth(slot, data.series.length) * sGroup
-        const off = grouped ? (si - (data.series.length - 1) / 2) * (bw + 1.5) : 0
+        const bw = groupWidth(slot, m.series.length)
+        const off = grouped ? (si - (m.series.length - 1) / 2) * (bw + 1.5) : 0
         const bh = Math.max(1, Math.abs(y(v) - y0))
         const by = v >= 0 ? y(v) : y0
-        parts.push(`<rect x="${cx + off - bw / 2}" y="${by}" width="${bw.toFixed(1)}" height="${bh.toFixed(1)}" fill="${colors[si % colors.length]}"><title>${esc(data.categories[i])}: ${v}</title></rect>`)
+        parts.push(`<rect x="${(cx + off - bw / 2).toFixed(1)}" y="${by.toFixed(1)}" width="${bw.toFixed(1)}" height="${bh.toFixed(1)}" fill="${colorOf(si)}"><title>${esc(s.name)} · ${esc(m.categories[i])}: ${v}</title></rect>`)
+        if (m.opts.labels) parts.push(labelText(cx + off, by - 4, fmtNum(v)))
       })
     })
-  } else if (chart.type === 'line') {
-    data.series.forEach((s, si) => {
+  } else if (m.type === 'line') {
+    m.series.forEach((s, si) => {
       const pts = s.values.map((v, i) => `${(pad.l + slot * i + slot / 2).toFixed(1)},${y(v).toFixed(1)}`)
-      parts.push(`<polyline points="${pts.join(' ')}" fill="none" stroke="${colors[si % colors.length]}" stroke-width="2"/>`)
-      pts.forEach((p, i) => parts.push(`<circle cx="${p.split(',')[0]}" cy="${p.split(',')[1]}" r="2.5" fill="${colors[si % colors.length]}"><title>${esc(data.categories[i])}: ${s.values[i]}</title></circle>`))
+      parts.push(`<polyline points="${pts.join(' ')}" fill="none" stroke="${colorOf(si)}" stroke-width="2"/>`)
+      pts.forEach((p, i) => {
+        const [px, py] = p.split(',')
+        parts.push(`<circle cx="${px}" cy="${py}" r="2.5" fill="${colorOf(si)}"><title>${esc(s.name)} · ${esc(m.categories[i])}: ${s.values[i]}</title></circle>`)
+        if (m.opts.labels) parts.push(labelText(Number(px), Number(py) - 6, fmtNum(s.values[i])))
+      })
     })
-  } else if (chart.type === 'pie') {
-    const v = data.series[0].values
+  } else if (m.type === 'pie') {
+    const v = m.series[0]?.values ?? []
     const total = v.reduce((a, b) => a + Math.max(0, b), 0) || 1
-    const r = Math.min(iw, ih) / 2 - 2
-    const cx = w / 2
+    const r = Math.min(iw, ih) / 2 - (m.opts.labels ? 6 : 2)
+    const cx = pad.l + iw / 2
     const cy = pad.t + ih / 2
     let angle = -Math.PI / 2
     v.forEach((val, i) => {
@@ -117,22 +182,100 @@ export function chartSvg(chart, w, h) {
       const x2 = cx + r * Math.cos(a2)
       const y2 = cy + r * Math.sin(a2)
       if (frac > 0.0005) {
-        parts.push(`<path d="M${cx},${cy} L${x1.toFixed(1)},${y1.toFixed(1)} A${r},${r} 0 ${large} 1 ${x2.toFixed(1)},${y2.toFixed(1)} Z" fill="${colors[i % colors.length]}"><title>${esc(data.categories[i])}: ${val}</title></path>`)
+        parts.push(`<path d="M${cx},${cy} L${x1.toFixed(1)},${y1.toFixed(1)} A${r},${r} 0 ${large} 1 ${x2.toFixed(1)},${y2.toFixed(1)} Z" fill="${colorOf(i)}"><title>${esc(m.categories[i])}: ${val}</title></path>`)
+      }
+      if (m.opts.labels && frac > 0.0005) {
+        const mid = angle + frac * Math.PI
+        const lx = cx + (r + 10) * Math.cos(mid)
+        const ly = cy + (r + 10) * Math.sin(mid)
+        parts.push(labelText(lx, ly + 3, `${m.categories[i]} ${Math.round(frac * 100)}%`, mid > Math.PI / 2 || mid < -Math.PI / 2 ? 'end' : 'start'))
       }
       angle = a2
     })
   }
-  data.categories.forEach((c, i) => {
-    if (chart.type === 'pie') return
+
+  m.categories.forEach((c, i) => {
+    if (m.type === 'pie') return
+    if (!showAxes) return
     const cx = pad.l + slot * i + slot / 2
     const label = c.length > 8 ? c.slice(0, 8) + '…' : c
-    parts.push(`<text x="${cx.toFixed(1)}" y="${h - 8}" font-size="9" fill="#475569" text-anchor="middle">${esc(label)}</text>`)
+    parts.push(`<text x="${cx.toFixed(1)}" y="${(pad.t + ih + 12).toFixed(1)}" font-size="9" fill="#475569" text-anchor="middle">${esc(label)}</text>`)
+    parts.push(`<line x1="${cx.toFixed(1)}" y1="${(pad.t + ih).toFixed(1)}" x2="${cx.toFixed(1)}" y2="${(pad.t + ih + 3).toFixed(1)}" stroke="${AXIS}" stroke-width="1"/>`)
   })
+
+  if (legend) parts.push(...renderLegend(legend, w, h, pad, legendItems))
+
   return `<svg viewBox="0 0 ${w} ${h}" width="${w}" height="${h}" xmlns="http://www.w3.org/2000/svg" style="display:block">${parts.join('')}</svg>`
 }
 
+function labelText(x, y, text, anchor = 'middle') {
+  return `<text x="${x.toFixed(1)}" y="${y.toFixed(1)}" font-size="9" fill="#334155" text-anchor="${anchor}">${esc(text)}</text>`
+}
+
+/** 估算文本宽度（CJK 按 1em，其余 0.55em）——只用于图例排布，不需要精确。 */
+function textW(s, size) {
+  let w = 0
+  for (const ch of String(s)) w += /[\u2E80-\u9FFF\uF900-\uFAFF\uFF00-\uFFEF]/.test(ch) ? size : size * 0.55
+  return w
+}
+
+/** 图例占位计算：bottom/top 横排（超宽自动换行），left/right 竖排。 */
+function layoutLegend(items, w, h, pos) {
+  const SIZE = 9
+  const swatch = 8
+  const gap = 6
+  const rowH = 14
+  if (pos === 'left' || pos === 'right') {
+    const maxItem = Math.max(20, ...items.map((it) => textW(it.label, SIZE))) + swatch + gap + 6
+    return { pos, w: Math.min(Math.round(w * 0.32), Math.ceil(maxItem)), h: rowH, rows: 1 }
+  }
+  const avail = Math.max(20, w - 16)
+  const items2 = items.map((it) => textW(it.label, SIZE) + swatch + gap + 8)
+  let rows = 1
+  let acc = 0
+  for (const iw2 of items2) {
+    if (acc > 0 && acc + iw2 > avail) { rows++; acc = iw2 } else acc += iw2
+  }
+  return { pos, w: 0, h: rows * rowH + 2, rows }
+}
+
+function renderLegend(legend, w, h, pad, items) {
+  const out = []
+  const SIZE = 9
+  const swatch = 8
+  const gap = 6
+  const rowH = 14
+  const widths = items.map((it) => textW(it.label, SIZE) + swatch + gap + 8)
+  if (legend.pos === 'left' || legend.pos === 'right') {
+    const totalH = items.length * rowH
+    let y = Math.max(pad.t, (h - totalH) / 2)
+    const x = legend.pos === 'left' ? 6 : w - legend.w + 6
+    for (let i = 0; i < items.length; i++) {
+      out.push(`<rect x="${x}" y="${(y + 3).toFixed(1)}" width="${swatch}" height="${swatch}" fill="${items[i].color}" rx="1"/>`)
+      out.push(`<text x="${x + swatch + gap}" y="${(y + 10).toFixed(1)}" font-size="${SIZE}" fill="${TICK_TEXT}">${esc(items[i].label)}</text>`)
+      y += rowH
+    }
+    return out
+  }
+  const top = legend.pos === 'top'
+  const avail = Math.max(20, w - 16)
+  let row = 0
+  let acc = 0
+  const baseY = top ? 4 : h - legend.h + 2
+  for (let i = 0; i < items.length; i++) {
+    if (acc > 0 && acc + widths[i] > avail) { row++; acc = 0 }
+    const x = 8 + acc
+    const y = baseY + row * rowH
+    out.push(`<rect x="${x}" y="${(y + 3).toFixed(1)}" width="${swatch}" height="${swatch}" fill="${items[i].color}" rx="1"/>`)
+    out.push(`<text x="${x + swatch + gap}" y="${(y + 10).toFixed(1)}" font-size="${SIZE}" fill="${TICK_TEXT}">${esc(items[i].label)}</text>`)
+    acc += widths[i]
+  }
+  return out
+}
+
 function groupWidth(slot, count) {
-  const bw = count > 1 ? slot * 0.7 : slot * 0.62
+  // 与原生图表 gapWidth=100（柱宽 = 1/2 槽）/ gapWidth=100+聚类（≈0.7/n 槽）对齐
+  const bw = count > 1 ? slot * 0.7 : slot * 0.5
   return Math.max(2, bw / Math.max(1, count))
 }
 

package/lib/pptxPy.js

@@ -1,6 +1,6 @@
 /**
  * python-pptx 引擎：把中间层（deck.yaml）映射为 python-pptx 脚本（兜底引擎）。
- * 覆盖 text / shape / image / table；chart 降级为表格+说明。
+ * 覆盖 text / shape / image / table / **chart（原生可编辑图表 + 内嵌数据工作簿）**。
  * 需要 python 环境 + python-pptx（运行前探测，缺失则报错提示）。
  */
 import { readFile } from 'node:fs/promises'
@@ -8,6 +8,8 @@ import { join, isAbsolute } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import YAML from 'yaml'
 import { normalizePage, measureText } from './pptd/layout.js'
+import { chartData, chartColors } from './pptd/svgCharts.js'
+import { findBundledPython } from './capabilities.js'
 
 export function genPythonScript(ctx) {
   const py = []
@@ -16,6 +18,10 @@ export function genPythonScript(ctx) {
   py.push('from pptx.dml.color import RGBColor')
   py.push('from pptx.enum.shapes import MSO_SHAPE, MSO_CONNECTOR')
   py.push('from pptx.enum.text import PP_ALIGN, MSO_ANCHOR')
+  // 原生图表（2026-09-26 第二轮 ③）：python-pptx 会自己写 `ppt/charts/chartN.xml` + **内嵌数据工作簿**
+  // `ppt/embeddings/*.xlsx`，于是成品里的图表可"编辑数据/换类型"、数据随文件走。
+  py.push('from pptx.chart.data import CategoryChartData')
+  py.push('from pptx.enum.chart import XL_CHART_TYPE')
   py.push('import json, sys')
   py.push('')
   // OUT 由 runPythonExport 替换成字面量路径（见文件末尾的 replace）。
@@ -126,7 +132,54 @@ export function genPythonScript(ctx) {
           break
         }
         case 'chart': {
-          py.push(`# chart 降级：引擎 B 以表格表达（引擎 A 支持矢量拼绘）`)
+          // 原生可编辑图表（2026-09-26 第二轮 ③）——**不再降级为表格**。
+          // 旧行为是"图表以表格表达"，用户拿到成品看不见图、也改不了数据；现在交给 python-pptx
+          // 生成原生图表：`ppt/charts/chartN.xml` + 内嵌工作簿一起落盘 ⇒ PowerPoint 里可"编辑数据"、
+          // 可切换图表类型、坐标轴/图例/数据标签都由图表自己算。
+          const cdata = chartData(el.chart)
+          const ccolors = chartColors(el.chart)
+          const kindOf = { bar: 'COLUMN_CLUSTERED', line: 'LINE_MARKERS', pie: 'PIE' }
+          const kind = kindOf[el.chart?.type] ?? 'COLUMN_CLUSTERED'
+          const series = cdata.series.length ? cdata.series : [{ name: '系列1', values: [] }]
+          py.push(`chart_data = CategoryChartData()`)
+          py.push(`chart_data.categories = ${pyLit(cdata.categories)}`)
+          for (const s of series) {
+            const vals = s.values.map((v) => (Number.isFinite(v) ? String(v) : '0'))
+            // 单元素元组必须带尾逗号，否则 `(12)` 是整数而不是序列
+            py.push(`chart_data.add_series(${pyLit(s.name ?? '系列')}, (${vals.join(', ')}${vals.length === 1 ? ',' : ''}))`)
+          }
+          py.push(`gf = slide.shapes.add_chart(XL_CHART_TYPE.${kind}, Emu(${x}*12700), Emu(${y}*12700), Emu(${w}*12700), Emu(${h}*12700), chart_data)`)
+          py.push(`chart = gf.chart`)
+          py.push(`chart.has_legend = ${series.length > 1 ? 'True' : 'False'}`)
+          if (series.length > 1) py.push(`chart.legend.include_in_layout = False`)
+          py.push(`plot = chart.plots[0]`)
+          if (el.chart?.type === 'pie') {
+            py.push(`plot.has_data_labels = True`)
+            py.push(`plot.data_labels.show_percentage = True`)
+            py.push(`plot.data_labels.show_value = False`)
+          } else {
+            // `vary_by_categories=False` 是必须的：python-pptx 默认模板会按分类上色，
+            // 于是单系列图例列成分类名、每根柱子不同色（2026-09-26 实测），与我们的观感预期不符。
+            py.push(`plot.vary_by_categories = False`)
+            py.push(`plot.has_data_labels = True`)
+            py.push(`plot.data_labels.number_format = '0'`)
+            py.push(`plot.data_labels.number_format_is_linked = False`)
+          }
+          // 上色是**观感项**：任何 API 差异都不该让整册导出失败 ⇒ 整块 try/except 包住。
+          py.push(`try:`)
+          if (el.chart?.type === 'pie') {
+            py.push(`    _pie = ${pyLit(ccolors)}`)
+            py.push(`    for i, pt in enumerate(plot.points):`)
+            py.push(`        pt.format.fill.solid(); pt.format.fill.fore_color.rgb = rgb(_pie[i % len(_pie)])`)
+          } else {
+            py.push(`    _cols = ${pyLit(ccolors)}`)
+            py.push(`    for i, s in enumerate(chart.series):`)
+            py.push(`        _c = rgb(_cols[i % len(_cols)])`)
+            py.push(`        s.format.fill.solid(); s.format.fill.fore_color.rgb = _c`)
+            if (el.chart?.type === 'line') py.push(`        s.format.line.color.rgb = _c`)
+          }
+          py.push(`except Exception:`)
+          py.push(`    pass`)
           break
         }
       }
@@ -167,21 +220,51 @@ function isApproxFill(fill) {
     && (fill.type === 'gradient' || fill.alpha != null || Array.isArray(fill.stops)))
 }
 
+/**
+ * 找可用的 python-pptx 解释器。**顺序很重要**（2026-09-26，第二轮兜底增强）：
+ *   ① **捆绑 Python**（桌面端：`<dshHome>/dsh-runtimes/dsh-primary-runtime/dependencies/python/python.exe`
+ *      或 carrier `resources/runtime/primary-runtime/...`）——它自带 python-pptx 1.0.2 / lxml / Pillow /
+ *      XlsxWriter / openpyxl / pandas，正是官方三个 office 技能假定的那一套；这条**不需要用户装任何东西**。
+ *   ② PATH 上的 `python` / `py` / `python3`（老路子）。
+ * 语义（向后兼容）：能 `import pptx` 的立刻返回 `has:true` 并带 `source`；只找到"能跑但缺库"的，
+ * 记下**第一个**作为 `has:false` 结果（继续往后找，别被一个残缺解释器挡住），供错误信息说明原因。
+ */
 export function findPython() {
-  for (const cmd of ['python', 'py']) {
+  let partial = null
+  const probe = (cmd, source) => {
     try {
-      const r = spawnSync(cmd, ['-c', 'import pptx; print("ok")'], { encoding: 'utf8', timeout: 15000 })
-      if (r.status === 0 && r.stdout.includes('ok')) return { cmd, has: true }
-      if (r.status === 0 || (r.error === undefined && r.stderr === '')) return { cmd, has: false }
-    } catch { /* try next */ }
+      const r = spawnSync(cmd, ['-c', 'import pptx; print("ok")'], { encoding: 'utf8', timeout: 20000 })
+      if (r.status === 0 && String(r.stdout).includes('ok')) return { cmd, has: true, source }
+      // 能起来但没装 pptx（stderr 非空且不是 spawn 失败）⇒ 记为"残缺但可用"，继续找下一个
+      if (r.status === 0 || (r.error === undefined && r.stderr === '')) return { cmd, has: false, source, partial: true }
+      return null
+    } catch { return null }
+  }
+  const bundled = findBundledPython()
+  if (bundled !== null) {
+    const r = probe(bundled.path, `bundled:${bundled.source}`)
+    if (r?.has) return { cmd: r.cmd, has: true, source: r.source }
+    if (r?.partial && partial === null) partial = r
   }
-  return { cmd: null, has: false }
+  for (const cmd of ['python', 'py', 'python3']) {
+    const r = probe(cmd, 'path')
+    if (r?.has) return { cmd: r.cmd, has: true, source: r.source }
+    if (r?.partial && partial === null) partial = r
+  }
+  return partial ?? { cmd: null, has: false, source: null }
 }
 
 export function runPythonScript(ctx, script) {
   const py = findPython()
-  if (!py.has) throw new Error('python-pptx 引擎不可用：未检测到带 python-pptx 的 python 环境（pip install python-pptx）——可改用默认 pptd 引擎')
-  return startPython(py.cmd, script)
+  if (!py.has) {
+    const bundled = findBundledPython()
+    throw new Error('python-pptx 引擎不可用：未检测到带 python-pptx 的解释器'
+      + (bundled === null
+        ? '（未探测到捆绑 Python，PATH 上也没有可用的 python；可 pip install python-pptx）'
+        : `（探测到捆绑 Python 但缺库：${bundled.path}）`)
+      + '——可改用默认 pptd 引擎')
+  }
+  return { stdout: startPython(py.cmd, script), cmd: py.cmd, source: py.source }
 }
 
 function startPython(cmd, script) {
@@ -201,5 +284,7 @@ export async function runPythonExport(ctx, out) {
   //   `python -c` 下没有 argv[1] ⇒ **文件已写出却报执行失败**）
   const script = genPythonScript(ctx).replace(/^OUT = .*$/m, `OUT = ${JSON.stringify(outPath)}`)
   const result = await runPythonScript(ctx, script)
-  return { file: outPath, engine: 'python-pptx', note: result.trim() }
+  // 解释器来源一并带出（2026-09-26）：兜底是"最后保险"，报告里要能看出**用的是哪一个解释器**，
+  // 否则"捆绑 Python 到底有没有被用上"只能靠猜。
+  return { file: outPath, engine: 'python-pptx', note: result.stdout.trim(), interpreter: result.cmd, interpreterSource: result.source }
 }

package/lib/preset-delivery.js

@@ -37,8 +37,22 @@
  *   · 注册表缺失（极简部署 / 低于 0.1.7 的宿主）只告警，**绝不抛**——预设没了也不能让插件挂不上；
  *   · 组合里出现解析不了的相对名时**拒绝声明**（宁可没有预设，也不声明一条注定 broken 的声明：
  *     broken 的预设会被 `presetOptions()` 过滤掉，等于白声明还多一条误导日志）。
+ *
+ * ── 2026-09-26 新增：**自定位行**（"只在「PPT 工作室」里可见"的载体）──────────────────
+ * 用户要求"装上插件后**其他预设完全不受影响**"。做法是把本包**挂进自己的预设组合**：
+ * 声明预设时在 `plugins` 末尾追加一行
+ *     { id: 'ppt-studio-scope', name: 'file:///<本包绝对路径>/lib/index.js', config: { scope: 'preset' } }
+ * —— 预设的常驻组合会真的 import 并 apply 这行（`dsh-agent-preset-registry` 声明即挂载），
+ * 而注册进"预设作用域 ctx"的工具/技能/提示段**只对该预设的会话可见**（分层注册表按 scope 链合并）。
+ * 三条必须守住的细节：
+ *   ① **行名必须是绝对 `file://`**：预设行按**注册表所在 ctx 的 baseUrl** 解析（历史事故根因），
+ *      裸包名/相对名在 profile 里解析不到；而 Loader 对**非 `.` 开头**的名字**原样 `import(name)`**
+ *      ⇒ `file://` 不看 baseUrl。这是 2026-09-26 真宿主实测通过的路径。
+ *   ② **路径现算，不写死**：用 `import.meta.url` 推出本包绝对路径 ⇒ 升级换代、换 profile 都不会陈旧。
+ *   ③ **预设档实例必须 `autoPreset: false`**：否则它会再声明一次预设 ⇒ 注册表对重复 id 直接 throw。
+ * 本行只在"想要隔离"时追加；不健康时由 index.js 自动回落到全局能力面（隔离失效但功能不丢）。
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { parse } from 'yaml'
@@ -60,11 +74,59 @@ export function builtinPresetDir() {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'agent-presets', PRESET_ID)
 }
 
+/** 包根（`lib/` 的上一级）。 */
+export function packageRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..')
+}
+
+/** **自定位行的 id**（预设档实例的身份标识，便于从日志/状态里认出来）。 */
+export const SCOPE_ROW_ID = 'ppt-studio-scope'
+
+/**
+ * 本包的加载入口（用于自定位行）。优先 `lib/index.js`（`package.json` 的 main），
+ * 其次读 `package.json.main`；都拿不到返回 null（调用方据此**不追加**该行——宁可不隔离，也不加一行注定 broken 的）。
+ * 路径经 `realpathSync` 归一：pnpm 顶层软链与 `.pnpm/...` 真实路径在 Node 里解析成同一模块实例。
+ */
+export function pluginEntryFile() {
+  const pkgRoot = packageRoot()
+  const candidate = join(pkgRoot, 'lib', 'index.js')
+  const fallbackMain = (() => {
+    try {
+      const main = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).main
+      return typeof main === 'string' && main ? resolve(pkgRoot, main) : null
+    } catch { return null }
+  })()
+  const entry = existsSync(candidate) ? candidate : (fallbackMain && existsSync(fallbackMain) ? fallbackMain : null)
+  if (entry === null) return null
+  try { return realpathSync(entry) } catch { return entry }
+}
+
+/**
+ * 自定位预设行：让本包被**自己的预设**挂载一次，从而把能力面注册进**预设作用域**。
+ * `config.scope: 'preset'` = 预设档实例；`autoPreset: false` = 它不再声明预设（重复 id 会 throw）。
+ * @param {{presetIds?: string[]}} [extra] 额外透传的配置
+ * @returns {object|null} 入口文件缺失时返回 null
+ */
+export function selfPresetRow(extra = {}) {
+  const entry = pluginEntryFile()
+  if (entry === null) return null
+  return {
+    id: SCOPE_ROW_ID,
+    name: pathToFileURL(entry).href,
+    config: { scope: 'preset', autoPreset: false, presetIds: extra?.presetIds ?? [PRESET_ID] },
+  }
+}
+
 /** 最近一次声明的结果（供 ppt_state 与测试观测；进程内单例）。 */
-const STATUS = { id: PRESET_ID, declared: false, via: '', reason: '尚未装配', rows: 0 }
+const STATUS = { id: PRESET_ID, declared: false, via: '', reason: '尚未装配', rows: 0, selfRow: false, health: 'unknown', isolation: 'unknown' }
 export function presetDeliveryStatus() {
   return { ...STATUS }
 }
+/** 覆盖/合并交付状态的附加字段（index.js 用它写入"隔离是否生效 / 是否已回落"）。 */
+export function notePresetStatus(patch = {}) {
+  for (const [k, v] of Object.entries(patch)) STATUS[k] = v
+  return presetDeliveryStatus()
+}
 
 function loggerOf(ctx) {
   try { return typeof ctx.logger === 'function' ? ctx.logger('ppt-studio') : ctx.logger } catch { return undefined }
@@ -97,9 +159,11 @@ function absolutizeRows(rows, baseDir) {
 /**
  * 组装交给 `agentPresets.register()` 的声明。
  * @param {string} [dir] 预设目录（缺省 = 包内自带那份）
- * @returns {{id: string, name: string, description: string, order: number, plugins: object[]}}
+ * @param {{selfRow?: boolean, presetIds?: string[]}} [opts] `selfRow: true` 时在末尾追加**自定位行**
+ *   （= 让本包在自己的预设里以"预设档"再挂一次，能力面因此只对该预设可见）
+ * @returns {{id: string, name: string, description: string, order: number, plugins: object[], selfRow: boolean}}
  */
-export function presetDeclaration(dir = builtinPresetDir()) {
+export function presetDeclaration(dir = builtinPresetDir(), opts = {}) {
   const composition = join(dir, 'agent.cordis.yml')
   if (!existsSync(composition)) throw new Error(`包内预设组合缺失：${composition}`)
   let meta = {}
@@ -108,12 +172,22 @@ export function presetDeclaration(dir = builtinPresetDir()) {
     try { meta = parse(readFileSync(metaFile, 'utf8')) ?? {} } catch { meta = {} }
   }
   const plugins = absolutizeRows(readEntryList(composition), dir)
+  let selfRow = false
+  if (opts?.selfRow === true) {
+    const row = selfPresetRow({ presetIds: opts?.presetIds })
+    if (row !== null) {
+      // 幂等：组合里若已存在同名行（用户手工加过），不重复追加
+      if (!plugins.some((r) => r?.id === SCOPE_ROW_ID)) { plugins.push(row); selfRow = true }
+      else selfRow = true
+    }
+  }
   return {
     id: PRESET_ID,
     name: typeof meta.name === 'string' ? meta.name : 'PPT 工作室',
     description: typeof meta.description === 'string' ? meta.description : '',
     order: typeof meta.order === 'number' ? meta.order : 2,
     plugins,
+    selfRow,
   }
 }
 
@@ -123,55 +197,79 @@ function readRegistry(ctx) {
 
 /**
  * 幂等地把「PPT 工作室」预设声明给 agent-preset 注册表。
- * @returns {{id: string, declared: boolean, via: string, reason: string, rows: number}} 当前（可能尚未完成的）状态
+ * @param {object} ctx 插件作用域 ctx（profile 档）
+ * @param {object} [config] 插件配置（`autoPreset:false` 关闭；`scope:'preset'` 时追加自定位行）
+ * @param {{selfRow?: boolean, onSettled?: (health: {ok: boolean, reason: string, rows?: number, selfRow?: boolean, presetId: string}) => void}} [hooks]
+ *   `onSettled` 在声明落地（成功/失败/注册表不可见）后**恰好调用一次**，供调用方决定是否需要回落。
+ * @returns {{id: string, declared: boolean, via: string, reason: string, rows: number, selfRow: boolean, health: string}} 当前（可能尚未完成的）状态
  */
-export function declareAgentPreset(ctx, config = {}) {
+export function declareAgentPreset(ctx, config = {}, hooks = {}) {
   if (config?.autoPreset === false) {
     STATUS.declared = false
     STATUS.via = ''
+    STATUS.health = 'off'
     STATUS.reason = 'autoPreset=false（配置关闭）'
     return presetDeliveryStatus()
   }
 
+  const wantIsolation = hooks?.selfRow === true || config?.scope === 'preset'
   let declaration
   try {
-    declaration = presetDeclaration()
+    declaration = presetDeclaration(builtinPresetDir(), { selfRow: wantIsolation, presetIds: config?.presetIds })
   } catch (e) {
     STATUS.declared = false
     STATUS.via = ''
+    STATUS.health = 'unavailable'
     STATUS.reason = `预设组合不可用（未声明）：${String(e?.message ?? e)}`
     loggerOf(ctx)?.warn?.(`[ppt-studio] ${STATUS.reason}`)
     return presetDeliveryStatus()
   }
   STATUS.rows = declaration.plugins.length
+  STATUS.selfRow = declaration.selfRow === true
+  STATUS.health = 'pending'
   STATUS.reason = '等待 agentPresets 注册表…'
 
   const warn = (message) => { try { loggerOf(ctx)?.warn?.(`[ppt-studio] ${message}`) } catch { /* 无 logger 时静默 */ } }
   let release
   let closed = false
+  let settled = false
   let queue = Promise.resolve()
+  const settle = (health) => {
+    if (settled) return
+    settled = true
+    try { hooks?.onSettled?.(health) } catch (e) { warn(`onSettled 回调异常：${String(e?.message ?? e)}`) }
+  }
 
   const declare = (registry) => {
     queue = queue.then(async () => {
       if (closed || release !== undefined) return
       if (registry === undefined) {
         STATUS.reason = 'agentPresets 服务不可见（本部署未装配预设注册表？）——预设未声明'
+        STATUS.health = 'no-registry'
         warn(STATUS.reason)
+        settle({ ok: false, reason: STATUS.reason, rows: STATUS.rows, selfRow: STATUS.selfRow, presetId: PRESET_ID })
         return
       }
       try {
         release = await registry.register(declaration)
         STATUS.declared = true
         STATUS.via = 'agentPresets.register'
-        STATUS.reason = `已声明（${declaration.plugins.length} 行）——新建会话的预设选择器里可选「${declaration.name}」`
+        STATUS.health = 'declared'
+        STATUS.reason = `已声明（${declaration.plugins.length} 行${declaration.selfRow ? '，含自定位行' : ''}）——新建会话的预设选择器里可选「${declaration.name}」`
         try { loggerOf(ctx)?.info?.(`[ppt-studio] ${STATUS.reason}`) } catch { /* 忽略 */ }
+        settle({ ok: true, reason: STATUS.reason, rows: STATUS.rows, selfRow: STATUS.selfRow, presetId: PRESET_ID })
       } catch (e) {
         STATUS.declared = false
         STATUS.via = ''
+        STATUS.health = 'failed'
         STATUS.reason = `声明失败（不影响插件本身）：${String(e?.message ?? e)}`
         warn(STATUS.reason)
+        settle({ ok: false, reason: STATUS.reason, rows: STATUS.rows, selfRow: STATUS.selfRow, presetId: PRESET_ID })
       }
-    }).catch((e) => { warn(`预设声明队列异常：${String(e?.message ?? e)}`) })
+    }).catch((e) => {
+      warn(`预设声明队列异常：${String(e?.message ?? e)}`)
+      settle({ ok: false, reason: `预设声明队列异常：${String(e?.message ?? e)}`, presetId: PRESET_ID })
+    })
   }
 
   ctx.effect(() => {