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 默认执行策略会拦 npm.ps1，必须用 npm.cmd
& "C:\Program Files\nodejs\npm.cmd" install `
    "@microsoft/[email protected]" `
    "@microsoft/[email protected]"

装好后告诉插件它们在哪儿（指向包含 node_modules 的目录）：

$env:DSH_POWERBI_CLI_DIR = "D:\tools\pbi-cli"     # 该目录下有 node_modules\.bin\powerbi-report-author.cmd

Store 版 Power BI Desktop 的路径不在官方 CLI 的候选列表里，插件会自动用 Get-AppxPackage 找到它；也可以手动指定：

$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：

{
  "dependencies": { "dsh-plugin-powerbi": "file:D:/path/to/dsh-plugin-powerbi" },
  "dsh": { "profile": { "bundles": [ "...", "dsh-plugin-powerbi" ] } }
}

从 npm 安装

cd $env:USERPROFILE\.dsh\profiles\desktop
& "C:\Program Files\nodejs\npm.cmd" install dsh-plugin-powerbi

然后把 dsh-plugin-powerbi 加进 dsh.profile.bundles。

7. 测试

node test/core.test.mjs [项目路径]    # 核心逻辑（不需要 DSH）
node test/entry.test.mjs [项目路径]   # 工具注册与动作分发（mock ctx）
node test/e2e.patch.mjs [项目路径]    # patch 成功/回滚/备份还原三条路径

8. 许可

MIT