dsh-plugin-powerbi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin-powerbi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# dsh-plugin-powerbi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Operate local **Power BI** (`.pbip` projects / Power BI Desktop) from [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+> This plugin bakes a set of **empirically verified hard constraints** into its behaviour instead of leaving them for you to discover the hard way. See section 4.
+
+中文文档见 [README.zh.md](./README.zh.md).
+
+## 1. What it does
+
+One tool, `powerbi`, with 12 actions:
+
+| Action | Purpose |
+|---|---|
+| `check` | Self-check: Node, both official CLIs, Power BI Desktop, named-pipe reachability |
+| `inspect` | Read-only inventory: pages, visuals, field bindings, theme state — **plus cross-table binding risks** |
+| `validate` | Run Microsoft's PBIR validator, return structured diagnostics |
+| `status` | Query the Desktop bridge (instances, current file, readiness, pages) |
+| `open` | Open a `.pbip` in Desktop and poll until ready |
+| `reload` | Ask Desktop to re-read report-layer edits from disk |
+| `screenshot` | Capture all pages, **with empty-page detection and automatic retry** |
+| `backup` / `backups` / `restore` | Whole-directory backup, list, restore |
+| `patch` | **Guarded report-layer editing**: backup → apply → validate → **auto-rollback if diagnostics increase** |
+
+It deliberately provides **no way to write model TMDL** — see section 4.
+
+## 2. Requirements
+
+The plugin itself needs no Power BI SDK. It drives two **official Microsoft CLIs**:
+
+```powershell
+# PowerShell blocks npm.ps1 by default — use npm.cmd
+& "C:\Program Files\nodejs\npm.cmd" install `
+    "@microsoft/powerbi-report-authoring-cli@0.4.0" `
+    "@microsoft/powerbi-desktop-bridge-cli@1.0.0"
+```
+
+Point the plugin at them:
+
+```powershell
+$env:DSH_POWERBI_CLI_DIR = "D:\tools\pbi-cli"     # dir containing node_modules\.bin\powerbi-report-author.cmd
+```
+
+The Microsoft Store build of Power BI Desktop lives outside the official CLI's search paths;
+the plugin discovers it via `Get-AppxPackage`. You can also pin it:
+
+```powershell
+$env:PBI_DESKTOP_PATH = "C:\Program Files\WindowsApps\Microsoft.MicrosoftPowerBIDesktop_<ver>_x64__8wekyb3d8bbwe\bin\PBIDesktop.exe"
+```
+
+## 3. Quick start
+
+```
+powerbi(action="check")
+powerbi(action="inspect", path="D:\reports\sales.pbip")
+powerbi(action="validate", path="D:\reports\sales.pbip")
+powerbi(action="open", path="D:\reports\sales.pbip")
+powerbi(action="patch", path="...", patch={ visual: "2b5023e9", set: [ ... ] })
+powerbi(action="reload")
+powerbi(action="screenshot")
+```
+
+Recommended rhythm: **inspect → backup → patch → validate → reload → screenshot**.
+
+## 4. Why the limits exist (all empirically verified, not defensive design)
+
+| Fact | Consequence | Plugin's answer |
+|---|---|---|
+| Microsoft's `validate` covers **only the report layer (PBIR), not TMDL**; no TMDL schema exists in `microsoft/json-schemas` | Model edits have **zero machine validation** | Provides **no** model-writing capability |
+| A TMDL measure referencing a **non-existent column** makes the whole `.pbip` **silently unopenable** (no error — the window just stays "Untitled") | One typo bricks the project | Same as above + mandatory whole-directory backup |
+| A **syntactically broken** measure (unclosed paren) **loads fine** — the model silently ignores it | Errors can hide until runtime | Does not treat "it loads" as correctness |
+| This Desktop build does **not support model hot-reload** (`--reload-with-model` → `CAPABILITY_UNSUPPORTED`) | Model changes require reopening Desktop | `reload` is report-layer only |
+| After `reload` returns success, **visuals are still querying** | An immediate screenshot captures a **blank page** | `screenshot` retries on empty output |
+| Desktop's own `.pbip` export **omits `$schema`**, which Fabric rejects | Upload fails | Surfaced by `inspect` / `validate` |
+| A theme JSON's internal `name` must equal its filename (GUID suffix included) | `PBIR_THEME_FILE_NAME_MISMATCH` | `inspect` flags the mismatch |
+| `validate` **cannot detect cross-table binding errors** (Cartesian products) | Inflated numbers with no warning | `inspect` includes a cross-table binding check |
+| On Windows, Node 20+ **cannot spawn `.cmd` directly** | `spawn EINVAL` | Routed through `cmd.exe /d /s /c` |
+
+## 5. The `patch` safety model
+
+`patch` is the only action that writes:
+
+1. **Whole-directory backup first** (keeps the most recent N, default 5, auto-rotated)
+2. Apply declarative edits (only under `Report/definition/**`)
+3. Run the official validator and compare against the **pre-edit baseline**
+4. **If diagnostics increased → roll the whole directory back** and report exactly which code appeared
+
+Supported `set` ops: `setQueryField`, `removeQueryProjection`, `setObject`, `removeObject`,
+`setFilter`, `removeFilter`, `setSort`, `setTitle`, `setPosition`.
+
+> Passing `validate` is necessary, not sufficient — it cannot see cross-table bindings or
+> whether the numbers are right. Run `reload` + `screenshot` after a successful `patch`.
+
+## 6. Install
+
+Local (development):
+
+```json
+{
+  "dependencies": { "dsh-plugin-powerbi": "file:D:/path/to/dsh-plugin-powerbi" },
+  "dsh": { "profile": { "bundles": [ "...", "dsh-plugin-powerbi" ] } }
+}
+```
+
+From npm: install into your profile and add `dsh-plugin-powerbi` to `dsh.profile.bundles`.
+
+## 7. Tests
+
+```powershell
+node test/core.test.mjs [project-path]
+node test/entry.test.mjs [project-path]
+node test/e2e.patch.mjs [project-path]
+```
+
+## 8. License
+
+MIT

package/README.zh.md

@@ -0,0 +1,140 @@
+# dsh-plugin-powerbi
+
+用 DeepSeek Harness 操作本地 **Power BI**（`.pbip` 项目 / Power BI Desktop）。
+
+> 这个插件把一批实测得到的**硬约束**直接内建为行为，而不是留给使用者去踩坑。
+> 约束来源与验证证据见仓库内 `_插件硬约束_已验证.md` 的思路（本插件 README 第 4 节摘录了要点）。
+
+## 1. 它能做什么
+
+一个工具 `powerbi`，12 个动作：
+
+| 动作 | 作用 |
+|---|---|
+| `check` | 自检：Node / 两个官方 CLI / Power BI Desktop / 命名管道，并给出修复建议 |
+| `inspect` | 只读盘点：页面、视觉对象、字段绑定、主题状态；**并列出跨表绑定风险** |
+| `validate` | 跑官方 PBIR 校验，返回结构化诊断明细 |
+| `status` | 查 Desktop 桥状态（实例、当前文件、是否 ready、页面列表） |
+| `open` | 用 Desktop 打开 `.pbip` 并轮询到 ready |
+| `reload` | 让 Desktop 重载磁盘上的报表层改动 |
+| `screenshot` | 截图全部页面，**带非空校验与自动重试** |
+| `backup` / `backups` / `restore` | 整目录备份、列举、还原 |
+| `patch` | **受控改写报表层**：自动备份 → 应用 → 校验对比 → 诊断变多则自动回滚 |
+
+设计上刻意**不提供写模型 TMDL 的能力** —— 原因见第 4 节。
+
+## 2. 依赖
+
+插件本身不依赖任何 Power BI SDK，但要装两个**微软官方 CLI**（它们才是真正干活的）：
+
+```powershell
+# 注意：PowerShell 默认执行策略会拦 npm.ps1，必须用 npm.cmd
+& "C:\Program Files\nodejs\npm.cmd" install `
+    "@microsoft/powerbi-report-authoring-cli@0.4.0" `
+    "@microsoft/powerbi-desktop-bridge-cli@1.0.0"
+```
+
+装好后告诉插件它们在哪儿（指向包含 `node_modules` 的目录）：
+
+```powershell
+$env:DSH_POWERBI_CLI_DIR = "D:\tools\pbi-cli"     # 该目录下有 node_modules\.bin\powerbi-report-author.cmd
+```
+
+Store 版 Power BI Desktop 的路径**不在官方 CLI 的候选列表里**，插件会自动用
+`Get-AppxPackage` 找到它；也可以手动指定：
+
+```powershell
+$env:PBI_DESKTOP_PATH = "C:\Program Files\WindowsApps\Microsoft.MicrosoftPowerBIDesktop_<版本>_x64__8wekyb3d8bbwe\bin\PBIDesktop.exe"
+```
+
+## 3. 快速开始
+
+```
+powerbi(action="check")                                  # 先自检
+powerbi(action="inspect", path="D:\报表\销售.pbip")        # 摸清现状
+powerbi(action="validate", path="D:\报表\销售.pbip")       # 校验
+powerbi(action="open", path="D:\报表\销售.pbip")           # 打开并等就绪
+powerbi(action="patch", path="...", patch={
+  visual: "2b5023e9",
+  set: [{ op: "setObject", object: "labels",
+          properties: { show: { expr: { Literal: { Value: "true" } } } } }]
+})                                                       # 受控改写（自动备份+回滚）
+powerbi(action="reload")                                 # 热重载报表层
+powerbi(action="screenshot")                             # 截图确认
+```
+
+推荐节奏：**inspect → backup → patch → validate → reload → screenshot**。
+
+## 4. 为什么有这些限制（全部实测，不是保守设计）
+
+| 事实 | 后果 | 插件对策 |
+|---|---|---|
+| 官方 `validate` **只校验报表层 PBIR，完全不校验 TMDL**；微软 json-schemas 里也没有 TMDL schema | 模型层改动**没有任何机器校验兜底** | **不提供**写模型的能力 |
+| TMDL 里引用一个**不存在的列** → 整个 `.pbip` **静默打不开**（不报错，只是窗口永远"无标题"） | 一次笔误就毁掉项目 | 同上 + 强制整目录备份 |
+| 语法错（如括号不闭合）的度量值**反而能被加载**（模型静默忽略） | 错误可能潜伏到运行期 | 不依赖"能加载"当正确性判据 |
+| 本版本 Desktop **不支持模型热重载**（`--reload-with-model` 返回 `CAPABILITY_UNSUPPORTED`） | 模型改动必须重开 Desktop | `reload` 只用于报表层 |
+| `reload` 返回 success 后**视觉对象仍在查询** | 立刻截图会拍到**空白页** | `screenshot` 做非空校验 + 自动重试 |
+| Desktop 自己导出的 `.pbip` **不写 `$schema`**，但 Fabric 拒收 | 上云时报错 | `inspect`/`validate` 会报出来 |
+| 主题 JSON 内部 `name` 必须等于文件名（含 GUID） | 校验器报 `PBIR_THEME_FILE_NAME_MISMATCH` | `inspect` 标出是否一致 |
+| `validate` **抓不到跨表绑定错误**（笛卡尔积） | 图表数值虚高却没报错 | `inspect` 自带跨表绑定检查 |
+| Windows 上 Node 20+ **不能直接 spawn `.cmd`** | `spawn EINVAL` | 内部走 `cmd.exe /d /s /c` |
+
+## 5. `patch` 的安全模型
+
+`patch` 是唯一会写盘的动作，它的流程是：
+
+1. **先整目录备份**（保留最近 N 份，默认 5，自动轮转）
+2. 应用声明式改动（只碰 `Report/definition/**`）
+3. 跑官方 `validate`，与**改前基线**对比
+4. **诊断数增加 → 立即整目录回滚**，并如实报告新增了哪条诊断
+
+支持的 `set` 操作：
+
+| op | 说明 |
+|---|---|
+| `setQueryField` | 改类别/系列/Y 轴的字段绑定（`role`、`index`、`field`、`queryRef`） |
+| `removeQueryProjection` | 删一个字段投影 |
+| `setObject` | 设/合并视觉对象的格式属性（`object`、`properties`、`selectorIndex`） |
+| `removeObject` | 删一个格式对象（例如去除写反的 `dataPoint` 配色） |
+| `setFilter` / `removeFilter` | 设/清视觉级筛选（`filterConfig.filters`） |
+| `setSort` | 设/清排序 |
+| `setTitle` | 设标题 |
+| `setPosition` | 改位置尺寸 |
+
+> 注意：`validate` 通过只是**必要条件**。跨表绑定、数值是否正确它管不到，
+> 所以 `patch` 成功后建议接着 `reload` + `screenshot` 做视觉确认。
+
+## 6. 安装
+
+### 本地安装（开发/自用）
+
+在 profile 的 `package.json` 的 `dependencies` 与 `dsh.profile.bundles` 里各加一条，
+然后 `pnpm install`：
+
+```json
+{
+  "dependencies": { "dsh-plugin-powerbi": "file:D:/path/to/dsh-plugin-powerbi" },
+  "dsh": { "profile": { "bundles": [ "...", "dsh-plugin-powerbi" ] } }
+}
+```
+
+### 从 npm 安装
+
+```powershell
+cd $env:USERPROFILE\.dsh\profiles\desktop
+& "C:\Program Files\nodejs\npm.cmd" install dsh-plugin-powerbi
+```
+
+然后把 `dsh-plugin-powerbi` 加进 `dsh.profile.bundles`。
+
+## 7. 测试
+
+```powershell
+node test/core.test.mjs [项目路径]    # 核心逻辑（不需要 DSH）
+node test/entry.test.mjs [项目路径]   # 工具注册与动作分发（mock ctx）
+node test/e2e.patch.mjs [项目路径]    # patch 成功/回滚/备份还原三条路径
+```
+
+## 8. 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# 本插件自己的 loader 条目：把 dsh-plugin-powerbi 挂进 DSH 的插件树。
+# 由 package.json 的 dsh.bundle.patch 指向，profile 的 bundles 里加上本包即生效。
+- id: powerbi
+  name: dsh-plugin-powerbi

package/lib/index.js

@@ -0,0 +1,351 @@
+/**
+ * DSH Power BI 插件 —— 工具注册入口。
+ *
+ * 只暴露**验证过可行**的能力，并把《插件硬约束》内建为行为：
+ *  - check / inspect / validate / status / open / reload / screenshot：全程只读或报表层
+ *  - patch：报表层受控改写（自动备份 + 改后 validate 对比，诊断变多即自动回滚）
+ *  - backup / restore：整目录备份与回滚
+ *  - **不提供**写模型 TMDL 的能力（那层没有校验护栏，实测错一个列引用整个项目就打不开）
+ *
+ * @module dsh-plugin-powerbi
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import z from '@deepseek-ai/schemastery'
+import {
+  resolveProject,
+  resolveDesktopExe,
+  reportAuthorCli,
+  desktopBridgeCli,
+  validateReport,
+  desktopStatus,
+  pickInstance,
+  openProject,
+  waitReady,
+  reloadProject,
+  screenshotWithRetry,
+  readReportMeta,
+  inspectVisuals,
+  findCrossTableBindings,
+  backupProject,
+  restoreBackup,
+  listBackups,
+} from './powerbi.js'
+import { applyPatch } from './patch.js'
+
+export const name = 'dsh-plugin-powerbi'
+export const inject = ['tools']
+
+/** 供 DSH 校验的配置 schema。 */
+export const Config = z.object({
+  /** 覆盖 report-author CLI 路径 */
+  reportAuthorPath: z.string().default(''),
+  /** 覆盖 desktop bridge CLI 路径 */
+  desktopBridgePath: z.string().default(''),
+  /** 截图默认缩放 */
+  screenshotScale: z.number().default(2),
+  /** 备份保留份数 */
+  backupKeep: z.number().default(5),
+})
+
+const TEXT = (text) => [{ type: 'text', text }]
+
+/** 统一的动作说明表，供模型选择动作。 */
+const ACTIONS = {
+  check: '自检环境：Node/CLI/Power BI Desktop/命名管道可用性，并给出修复建议',
+  inspect: '只读盘点项目：页面、视觉对象、字段绑定、主题状态、页面尺寸；并列出跨表绑定风险',
+  validate: '跑官方 PBIR 校验，返回结构化诊断（error/warning 明细）',
+  status: '查询 Power BI Desktop 桥状态（实例、当前文件、是否 ready、页面列表）',
+  open: '用 Desktop 打开 .pbip 并轮询到 ready（Store 版会自动设置 PBI_DESKTOP_PATH）',
+  reload: '让 Desktop 重载磁盘上的报表层改动（模型层改动不支持热重载）',
+  screenshot: '截图全部页面，带非空校验与自动重试（reload 后视觉对象仍需时间查询）',
+  backup: '整目录备份项目（改任何东西之前应先跑这个）',
+  restore: '从备份整目录还原',
+  backups: '列出已有备份',
+  patch: '受控改写报表层：自动备份 → 应用改动 → validate 对比 → 诊断变多则自动回滚',
+}
+
+function fmtDiagnostics(diag) {
+  if (!diag) return '（无诊断）'
+  const lines = []
+  for (const [code, group] of Object.entries(diag)) {
+    lines.push(`${group.severity === 'error' ? 'ERROR' : 'WARNING'} [${code}] ×${group.items.length}`)
+    for (const it of group.items.slice(0, 4)) {
+      lines.push(`    ${it.message}`)
+      if (it.file) lines.push(`      file: ${it.file}${it.path ? ' @ ' + it.path : ''}`)
+    }
+    if (group.items.length > 4) lines.push(`    …还有 ${group.items.length - 4} 条`)
+  }
+  return lines.join('\n')
+}
+
+async function doCheck() {
+  const out = []
+  out.push(`Node: ${process.version}`)
+  const exe = resolveDesktopExe()
+  out.push(
+    exe.path
+      ? `Power BI Desktop: ${exe.path}  (来源: ${exe.source})`
+      : 'Power BI Desktop: ✘ 未找到 —— 请设置 PBI_DESKTOP_PATH',
+  )
+  const ra = reportAuthorCli()
+  const db = desktopBridgeCli()
+  out.push(ra ? `powerbi-report-author CLI: ${ra}` : 'powerbi-report-author CLI: ✘ 未找到')
+  out.push(db ? `powerbi-desktop CLI: ${db}` : 'powerbi-desktop CLI: ✘ 未找到')
+  if (!ra || !db) {
+    out.push('')
+    out.push('安装命令（注意 PowerShell 需用 npm.cmd）：')
+    out.push('  & "C:\\Program Files\\nodejs\\npm.cmd" install "@microsoft/powerbi-report-authoring-cli@0.4.0" "@microsoft/powerbi-desktop-bridge-cli@1.0.0"')
+    out.push('  然后把该目录的 node_modules 加进 DSH 的模块解析路径，或设置 DSH_POWERBI_CLI_DIR 指向它的父目录')
+  }
+  if (db) {
+    try {
+      const s = await desktopStatus({ timeoutMs: 30000 })
+      out.push(`桥状态: ${s.status}（实例 ${(s.instances ?? []).length} 个）`)
+      for (const i of s.instances ?? []) {
+        out.push(`  pid=${i.pid} bridge=${i.bridgeStatus} file=${i.currentFilePath ?? '-'} pages=${(i.pages ?? []).length}`)
+      }
+    } catch (e) {
+      out.push(`桥查询失败: ${e.message}`)
+    }
+  }
+  out.push('')
+  out.push('已知边界：报表层可改（有 validate + 热重载）；模型层 *.tmdl 无任何校验、不能热重载，本插件不提供写入。')
+  return out.join('\n')
+}
+
+async function doInspect(proj) {
+  const meta = readReportMeta(proj)
+  const { visuals } = inspectVisuals(proj)
+  const cross = findCrossTableBindings(proj)
+  const out = []
+  out.push(`项目: ${proj.name}`)
+  out.push(`  .pbip      : ${proj.pbip ?? '(无)'}`)
+  out.push(`  Report     : ${proj.reportDir}`)
+  out.push(`  SemanticModel: ${proj.modelDir}${proj.modelDir && listBackupsSafe(proj) ? '' : ''}`)
+  out.push('')
+  out.push(`PBIR 版本: ${meta.version?.version ?? '?'}`)
+  out.push(`页面数: ${(meta.pages?.pageOrder ?? []).length}`)
+  const pageDims = []
+  for (const p of meta.pages?.pageOrder ?? []) pageDims.push(p)
+  out.push(`视觉对象数: ${visuals.length}`)
+  out.push('')
+  if (meta.theme) {
+    out.push(`主题: ${meta.theme.name}`)
+    out.push(`  文件存在: ${meta.theme.exists}`)
+    out.push(`  内部 name: ${meta.theme.themeName}`)
+    out.push(`  name 与文件名${meta.theme.mismatch ? '❌ 不一致（应改为文件名）' : '✅ 一致'}`)
+    out.push(`  dataColors[0..7]: ${(meta.theme.dataColors ?? []).join(', ')}`)
+  } else {
+    out.push('主题: (未使用自定义主题)')
+  }
+  out.push('')
+  out.push('视觉对象字段绑定:')
+  for (const v of visuals) {
+    const refs = v.refs.map((r) => `${r.entity}[${r.property}]`).join('  ')
+    out.push(`  [${v.visualType ?? '容器'}] ${v.visual.slice(0, 8)}  ${refs || '(无字段)'}`)
+  }
+  if (cross.length) {
+    out.push('')
+    out.push(`⚠ 跨表绑定风险 ${cross.length} 处（官方 validate 抓不到这类问题）：`)
+    for (const c of cross) {
+      out.push(`  ${c.visualType} ${c.visual.slice(0, 8)}: 引用了 ${c.entities.join(' + ')}`)
+      out.push(`      ${c.note}`)
+    }
+  }
+  return out.join('\n')
+}
+
+function listBackupsSafe(proj) {
+  try {
+    return listBackups(proj)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * @param {any} ctx cordis 上下文
+ * @param {any} config
+ */
+export function apply(ctx, config = {}) {
+  if (process.env.DSH_POWERBI_CLI_DIR && !config.reportAuthorPath) {
+    // 允许通过环境变量指定 CLI 目录（findCliInNodeModules 会读它）
+  }
+  const scale = config.screenshotScale ?? 2
+  const keep = config.backupKeep ?? 5
+
+  // 防重复注册：DSH Desktop 用 patchReload: live，插件可能在同一 tools 注册表上被重复 apply
+  const key = ctx.tools
+  if (apply.__done?.has(key)) return
+  apply.__done ??= new WeakSet()
+  apply.__done.add(key)
+
+  ctx.tools.register(
+    defineTool({
+      name: 'powerbi',
+      description: [
+        '操作本地 Power BI 项目（.pbip）与 Power BI Desktop。',
+        '',
+        '动作：',
+        ...Object.entries(ACTIONS).map(([k, v]) => `  ${k} — ${v}`),
+        '',
+        '重要边界（实测结论，务必遵守）：',
+        '  · 报表层 Report/definition/** 可以改：有官方 validate 兜底，且能被 Desktop 热重载。',
+        '  · 模型层 *.tmdl 是雷区：官方 validate 完全覆盖不到，且本版本 Desktop 不支持模型热重载；',
+        '    实测只要引用一个不存在的列，整个 .pbip 就会静默打不开。**本插件不提供写模型的能力。**',
+        '  · 改任何东西之前先跑 action="backup"；patch 会自动备份并在诊断变多时自动回滚。',
+        '  · reload 之后不要立刻截图（视觉对象仍在查询），用 action="screenshot" 它自带重试与非空校验。',
+      ].join('\n'),
+      parameters: {
+        action: {
+          type: 'string',
+          required: true,
+          enum: Object.keys(ACTIONS),
+          description: '要执行的动作，见描述中的动作表。',
+        },
+        path: {
+          type: 'string',
+          description: '项目路径：可以是 .pbip 文件、.Report 目录，或包含它们的项目目录。除 check 外都需要。',
+        },
+        pid: {
+          type: 'string',
+          description: 'reload / screenshot 用的 Desktop 进程号。省略则自动取已连接的实例。',
+        },
+        outDir: {
+          type: 'string',
+          description: 'screenshot 的输出目录。默认 <项目目录>/_shots。',
+        },
+        backup: {
+          type: 'string',
+          description: 'restore 用的备份目录名（可只给后缀片段）。省略则用最近一份。',
+        },
+        keep: {
+          type: 'number',
+          description: 'backup 时保留的备份份数，默认沿用插件配置。',
+        },
+        patch: {
+          type: 'object',
+          additionalProperties: true,
+          description: [
+            'patch 动作的改动描述（声明式，不写代码）：',
+            '  { "visual": "<视觉对象目录名或前 8 位>", "set": [ ... ] }',
+            'set 支持的操作：',
+            '  { "op":"setQueryField", "role":"Category|Series|Y|Values", "index":0,',
+            '    "field":{"Measure":{"Expression":{"SourceRef":{"Entity":"_Measures"}},"Property":"度量值名"}},',
+            '    "queryRef":"_Measures.度量值名", "nativeQueryRef":"度量值名" }',
+            '  { "op":"setObject", "object":"labels", "properties":{ "show":{"expr":{"Literal":{"Value":"true"}}} } }',
+            '  { "op":"removeObject", "object":"dataPoint" }',
+            '  { "op":"setFilter", "filters":[ ... FilterConfig 结构 ... ] }',
+            '  { "op":"setSort", "sort":{ "sort":[...], "isDefaultSort":true } }',
+          ].join('\n'),
+        },
+        scale: { type: 'number', description: 'screenshot 缩放，默认沿用插件配置。' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            action: { type: 'string', required: true },
+            ok: { type: 'boolean', required: true },
+            text: { type: 'string', required: true },
+          },
+        },
+      },
+      async execute(args, exec) {
+        const action = args.action
+        try {
+          if (action === 'check') {
+            return { action, ok: true, text: await doCheck() }
+          }
+
+          if (!args.path) throw new Error(`action="${action}" 需要 path 参数`)
+          const proj = resolveProject(args.path)
+
+          if (action === 'inspect') {
+            return { action, ok: true, text: await doInspect(proj) }
+          }
+
+          if (action === 'validate') {
+            const v = await validateReport(proj)
+            const head = `result=${v.result}  errors=${v.errorCount}  warnings=${v.warningCount}`
+            return { action, ok: v.errorCount === 0, text: head + '\n\n' + fmtDiagnostics(v.diagnostics) }
+          }
+
+          if (action === 'status') {
+            const s = await desktopStatus()
+            return { action, ok: s.status === 'ready', text: JSON.stringify(s, null, 2) }
+          }
+
+          if (action === 'open') {
+            if (!proj.pbip) throw new Error('该项目没有 .pbip 文件，无法用 Desktop 打开')
+            const r = await openProject(proj.pbip)
+            const txt = r.ok
+              ? `已就绪\npid=${r.instance.pid}\n页面: ${(r.instance.pages ?? []).map((p) => p.displayName).join(', ')}`
+              : `未在超时内就绪（这是重要信号：项目很可能有问题，而不是"再等等"）\n` + JSON.stringify(r.status, null, 2)
+            return { action, ok: r.ok, text: txt }
+          }
+
+          if (action === 'reload') {
+            let pid = args.pid
+            if (!pid) {
+              const s = await desktopStatus()
+              const inst = pickInstance(s)
+              if (!inst) throw new Error('没有已连接的 Desktop 实例；先跑 action="open"')
+              pid = inst.pid
+            }
+            const r = await reloadProject(pid)
+            return { action, ok: r?.result?.success === true || r?.status === 'ok', text: JSON.stringify(r, null, 2) }
+          }
+
+          if (action === 'screenshot') {
+            let pid = args.pid
+            if (!pid) {
+              const s = await desktopStatus()
+              const inst = pickInstance(s)
+              if (!inst) throw new Error('没有已连接的 Desktop 实例；先跑 action="open"')
+              pid = inst.pid
+            }
+            const outDir = args.outDir || `${proj.projectDir}\\_shots`
+            const r = await screenshotWithRetry(pid, outDir, { scale: args.scale ?? scale })
+            const lines = [`status=${r.status} attempts=${r.attempts ?? 1} 输出: ${outDir}`]
+            for (const s of r.screenshots ?? []) {
+              lines.push(`  ${s.pageDisplayName} -> ${s.outputPath}`)
+            }
+            if (r.emptySuspected) lines.push('⚠ 截图疑似仍为空白（已重试到上限）。可再等一会重跑，或先 action="reload"。')
+            if (r.failures?.length) lines.push('失败页: ' + JSON.stringify(r.failures))
+            return { action, ok: r.status === 'ok' && !r.emptySuspected, text: lines.join('\n') }
+          }
+
+          if (action === 'backup') {
+            const b = backupProject(proj, { keep: args.keep ?? keep })
+            const lines = [`已备份到: ${b.dest}`, `文件 ${b.files} 个，${b.bytes} 字节`]
+            if (b.removed.length) lines.push(`已轮转删除旧备份: ${b.removed.join(', ')}`)
+            lines.push(`现有备份: ${listBackupsSafe(proj).join(', ') || '(无)'}`)
+            return { action, ok: true, text: lines.join('\n') }
+          }
+
+          if (action === 'backups') {
+            const list = listBackupsSafe(proj)
+            return { action, ok: true, text: list.length ? list.join('\n') : '(没有备份)' }
+          }
+
+          if (action === 'restore') {
+            const r = restoreBackup(proj, args.backup)
+            return { action, ok: true, text: `已从备份还原: ${r.restored}` }
+          }
+
+          if (action === 'patch') {
+            if (!args.patch) throw new Error('patch 动作需要 patch 参数')
+            const r = await applyPatch(proj, args.patch, { keep: args.keep ?? keep })
+            return { action, ok: r.ok, text: r.text }
+          }
+
+          throw new Error(`未知动作: ${action}`)
+        } catch (e) {
+          return { action, ok: false, text: `执行失败: ${e?.message ?? String(e)}` }
+        }
+      },
+    }),
+  )
+}