dsh-ppt-master-plus
把上游 ppt-master 技能集忠实封装为 DeepSeek Harness (DSH) 插件 —— 逐字节 vendor、零改写、零运行时依赖、可一键同步上游。
上游技能集本身是一个完整的 AI 演示文稿工作流（生成 / 重构 / 美化 PPTX、Brand·Style·Layout·Deck 工作区、原生模板填充）。本包装层不做任何内容改写，只负责把它可靠地装进 DSH：注册技能、暴露生命周期工具、提供 venv 解释器隔离、图形化配置卡片与工具可见范围控制。
- 零改写：vendor 的
skills/ppt-master/ 与上游 release 逐字节一致，天然通过上游 attribution_guard.py 完整性门；
- 零运行时 npm 依赖：纯 Node 内置模块实现；技能的 Python 依赖由生命周期工具按需安装；
- 可更新：
scripts/sync-upstream.mjs 一键同步上游新版本（下载 → 完整性门 → 校验 → 替换 → commit/tag/push）；
- 解释器可隔离：可选 venv 模式，为上游脚本提供独立解释器，容器场景可落到持久卷；
- 配置图形化：自带客户端半边，DSH「插件」页直接出配置卡片（中英双语），保存免重启生效。
架构
%%{init: {"flowchart": {"wrappingWidth": 320}}}%%
flowchart TB
UP["上游 ppt-master<br/>GitHub · MIT"]:::up
SYNC["scripts/sync-upstream.mjs<br/>下载 → 完整性门 → 替换"]:::tool
VENDOR["skills/ppt-master/<br/>逐字节 vendor（零改写）"]:::artifact
HOST["index.js<br/>ctx.skills · ctx.tools.register"]:::code
CARD["lib/client.js<br/>插件页配置卡片"]:::code
DSH["DeepSeek Harness<br/>2 个技能 · 3 个工具<br/>+ 插件页配置卡片"]:::host
UP --> SYNC --> VENDOR --> HOST --> DSH
CARD --> DSH
classDef up fill:#d9a52122,stroke:#b8860b,stroke-width:1.5px,rx:6,ry:6
classDef tool fill:#4f6ef722,stroke:#4f6ef7,stroke-width:1.5px,rx:6,ry:6
classDef artifact fill:#2f9e7822,stroke:#2f9e78,stroke-width:1.5px,rx:6,ry:6
classDef code fill:#4f6ef722,stroke:#4f6ef7,stroke-width:1.5px,rx:6,ry:6
classDef host fill:#8c959f22,stroke:#8c959f,stroke-width:1.5px,rx:6,ry:6
技能面由 index.js 经 ctx.skills 注册：vendor 的 ppt-master 技能＋一个内存合成、不落盘的入口技能 ppt-master-env（解释器路由入口）。DSH 通过 resourceBase 注入技能目录绝对路径，由执行 agent 代入上游约定的 ${SKILL_DIR}——机制等价满足上游 SKILL.md 的硬规则。
安装
前置依赖
| 依赖 | 用途 | 备注 |
|---|
| DeepSeek Harness | 运行宿主 | 配置卡片需 DSH ≥ 0.2.0-rc.2；更早版本安静降级为"无卡片"，其余功能不受影响 |
| Node.js ≥ 20 | 插件与工具运行时 | 纯内置模块，无 npm 依赖 |
| Python ≥ 3.10 | 上游脚本套件与完整性门 | POSIX 用 python3；Windows 依次尝试 python3 → py -3 → python。建议 venv 可用（venv 模式依赖其 ensurepip） |
| pip | 安装上游 Python 依赖 | 统一用 python -m pip；venv 模式下用 <venv>/Scripts/pip.exe（Windows）或 <venv>/bin/pip3（POSIX），不受 PEP 668 拦截 |
| git / tar | 同步脚本 | 仅同步上游时需要 |
Windows 支持
- 解释器解析：
python3 → py -3 → python，逐项探测并以 ≥ 3.10 为准；Microsoft Store 的 python3.exe 占位程序（退出码 49 / WindowsApps / Microsoft Store）会被单独识别并给出安装指引，不再误报成“没有 Python”。
- venv 布局：Windows 为
Scripts\python.exe / Scripts\pip.exe，POSIX 为 bin/python3 / bin/pip3；探测、创建、安装与诊断共用同一份平台常量（lib/platform.js）。
- 安装命令：一律
python -m pip（解释器候选前缀保留，py -3 -m pip …），不假设 pip3 在 PATH 上。
.env 路径：ppt_master_check_env 回报实际命中的文件（会话工作目录 → SKILL_DIR → 插件根 → ~/.ppt-master），而不是只回答“存在/不存在”。- 符号链接：Windows 默认策略下无法创建 symlink 的测试会显式
skip；产品侧不依赖 symlink。
- tar：
verify-plugin 的诊断与 sync-upstream 的解压均把路径归一为平台无关文本；解压对 GNU tar（Git Bash）的盘符解析做了规避，Windows 自带的 bsdtar 同样可用。
安装到 DSH
# 方式一：GitHub 直接安装（推荐）
dsh plugin --profile <name> add https://github.com/AlbertZJ/dsh-ppt-master-plus.git
# 方式二：本地路径 link（开发机）
dsh plugin --profile <name> add link:/path/to/dsh-ppt-master-plus
安装后重启会话，ppt-master 技能即对 agent 可见；客户端半边（配置卡片）须宿主重启一次才首次装载——之后保存配置即免重启生效。
安装体积约 65 MB：其中绝大部分是逐字节 vendor 的上游技能树（含模板与参考文档），不是运行时依赖；插件本身零 npm 依赖。
首次使用
- 环境自检：调用
ppt_master_check_env，确认解释器就绪、完整性门通过、Python 依赖已安装，并查看实际生效的 .env 路径。
- 安装 Python 依赖：调用
ppt_master_setup_deps（幂等），或手动 python -m pip install -r skills/ppt-master/requirements.txt。
- 配置
.env（按需）：上游图像生成脚本需要图像后端配置。在会话工作目录（上游 .env 查找顺序第 1 位；插件根目录为第 3 顺位兜底）执行
cp skills/ppt-master/.env.example .env，按文件内注释填写 IMAGE_BACKEND 与对应 key/model
（也可用进程环境变量提供同样配置）。.env 已列入 .gitignore；插件工具不读取、不回显其内容。
生命周期工具
| 工具 | 参数 | 行为 |
|---|
ppt_master_info | 无 | 插件版本、上游版本、SKILL_DIR 绝对路径与上游 repo 链接。纯读。 |
ppt_master_check_env | 无 | 环境自检：解释器就绪度（Windows 含候选回退与 Store 别名诊断）、运行 attribution_guard.py、探测 Python 依赖安装状态、回报实际生效的 .env 路径。只读。 |
ppt_master_setup_deps | user?、breakSystemPackages? | 幂等安装 requirements.txt，完成后自动复跑自检。唯一有副作用的工具；venv 的创建/删除只发生在它。 |
三个工具均 venv 感知（payload 带 venv 小节；venv.enabled=true 时工具描述追加解释器提示）。user / breakSystemPackages 仅系统模式生效，venv 模式下被忽略并在返回中注明。
配置
插件声明原生 cordis Config，两组键、全部叶子 .volatile()——经插件页卡片保存后走宿主 volatile 快路径，免重启生效（三个工具每轮现读配置，venv.* 与 scope.* 同等；唯一例外是合成入口技能 ppt-master-env 的正文，它是注册期快照，正文自带脚注指向两个实时工具）；经 profile cordis.patch.yml 手工编辑则需重启 DSH。两通道等价、先写者为准。
插件页卡片（首选入口）
GUI 侧边栏 插件页 → 已安装 → dsh-ppt-master-plus → 包详情页配置卡片：venv 三字段（enabled / path / oldPathPolicy）＋「工具可见范围」一节＋版本信息块，文案中英双语跟随界面语言。memory 模式会话中卡片显式提示"本次不会写入宿主配置"。
venv 隔离
| 键 | 取值 | 默认 |
|---|
venv.enabled | 是否启用 venv 解释器隔离 | false |
venv.path | venv 目录（绝对路径或 ~ 前缀；相对路径判无效） | ~/.ppt-master/venv |
venv.oldPathPolicy | 改路径后旧 venv 处置：keep / delete | keep |
- 懒创建：改配置零副作用；创建/删除只发生在
ppt_master_setup_deps。
- 容器建议：把
venv.path 显式配置到持久卷（如 /dsh-home/.ppt-master/venv）——venv 内符号链接指向容器内绝对路径，跨镜像重建是否可用依赖镜像不变。
- 损坏恢复：删除重建（
rm -rf <venv.path> 后重跑 setup_deps）；半成品（缺 Scripts\pip.exe / bin/pip3）同样删除重建，系统缺 ensurepip 时先装 python3-venv（Windows 的 python.org 安装器默认自带 ensurepip）。
- 删除安全：自动删除只碰带所有权标记且满足安全条件的旧 venv；
enabled=false 不删除任何东西；不要往 venv 目录里放用户数据。两类孤儿目录（无标记 / 有标记无登记）均需手动 rm -rf。
- 配置热更新：三个工具每轮现读
venv.*，卡片保存即生效（无需重启）；合成入口技能 ppt-master-env 的正文是注册期快照，改了 venv.* 后它仍显示旧的路由指引——以其脚注指向的 ppt_master_info / ppt_master_check_env 输出为准（重启 DSH 可让正文也刷新）。
- 完整判定条件与实现细节见 AGENTS.md §6。
工具可见范围（全局 / 指定工作区）
3 个 ppt_master_* 工具默认注册为全局工具。工作区很多且多数与 PPT 无关时，可把它们从无关工作区的工具表里真正移除（宿主装配层 tools.restrict，不是前端过滤）：
| 键 | 取值 | 默认 |
|---|
scope.mode | global（所有工作区可见） / selected（仅名单内可见） | global |
scope.workspaceIds | 工作区 id 字符串数组 | [] |
selected 下：会话按「工作区 sessionIds 成员 → 会话 cwd 规范路径」两级判定归属，命中且 id 在名单里才可见——不属于任何工作区的会话也看不到。降级口径（明示收窄意图，答不出来时不静默放宽）：缺判定服务时按最严口径拒绝并 console.warn；注册表瞬时读失败维持上一轮判定；宿主缺 tools.restrict 时退化为仅执行层拒绝。配置走卡片的模式单选 + 工作区勾选列表（清单来自宿主 workspaces 服务），保存即生效。
宿主下限：scope.mode=selected 除配置卡片外，还依赖宿主注入 agents / workspaceRegistry 服务与 tools.restrict / tools.guard 能力；缺任一时按上述降级口径拒绝或降级（不静默放宽），不影响 global 模式与其余功能。
已知限制：只收窄工具不收窄技能条目；判定基于会话创建时的 cwd；已删除工作区的 id 被忽略；释放限制层时宿主抛错则该层可能残留（重启可清）；市场截图 assets/screenshot-1-config-card.png 待重制（卡片新增了可见范围节）。
profile patch（等价通道）
编辑 profile 的 cordis.patch.yml 追加（字段写全——patch 的 config 是整体替换语义；保存后须重启 DSH）：
- id: dsh-ppt-master-plus
config:
venv:
enabled: true
path: /dsh-home/.ppt-master/venv
oldPathPolicy: keep
scope:
mode: selected
workspaceIds:
- b6ef89f7-74a6-4e4f-84eb-07581e390020
插件升级新增配置字段后，已存在的 patch 条目需比对补全（或直接在卡片上重新保存一次），否则新字段回落默认值。
重启边界与诊断
哪些改动需要重启：
- 卡片保存配置——不需要（volatile 快路径；工具侧立即生效，含
venv.*）。合成入口技能 ppt-master-env 的正文是注册期快照，保存后不会自己改写——正文自带脚注，实时状态以 ppt_master_info / ppt_master_check_env 为准；
- 只改
lib/client.js——不需要（宿主 stat 轮询热更新，约 500ms）；
- 改
package.json 的 dsh.client / exports["./client"] 声明面、或手工编辑 profile patch——需要。
卡片没出现 / 不可用，按序排查：① 刚改过 package.json 声明面？→ 重启 DSH（最常见）；② 宿主「插件」页是否提供 plugins.bundle.config 槽位；③ 卡片显示「配置通道未接入」＝宿主缺 configForms 服务（可选拼装，功能面不受影响）；④ 老宿主不认 dsh.client → 安静降级，插件功能不受影响，配置走 profile patch 或升级宿主。
其他：插件装载失败并连带技能面消失，通常是 @deepseek-ai/schemastery 受控解析失败——确认宿主 profile 的 node_modules 内有该包，且 DSH_NODE_MODULES / DSH_PROFILE_DIR / DSH_HOME 指向它（详见 AGENTS.md §3）。入口技能缺失：宿主拒绝不带 resourceBase 的合成候选时仅入口技能缺席，vendor 技能与工具不受影响。
同步上游更新
node scripts/sync-upstream.mjs [选项]
| 选项 | 语义 |
|---|
--ref <tag|branch|commit> | 指定上游 ref（默认：最新语义版本 release tag） |
--repo <url> | 上游仓库 URL（默认 https://github.com/hugohe3/ppt-master.git） |
--refresh | 忽略 .upstream/ 缓存重新下载 |
--confirm-structural | 结构变化已人工确认，强制走自动路径 |
--skip-guard | 跳过 attribution_guard.py 执行（须与 --no-push 或 --dry-run 联用） |
--no-push | 只本地 commit + tag，不推送 |
--dry-run | 只输出将发生的变化 |
流程：解析最新 tag → 下载（或缓存）→ 完整性门 → 结构变化检测 → 自动路径：校验前置于替换 → 替换 skills/ → bump 版本（自动联动改写 lib/client.js 版本常量）→ commit + tag v<version> → push。结构变化 🔴（skill 目录增删、重命名、metadata.version 缺失等）时停下报告（退出码 2，报告写仓库根 sync-report.txt），人工评估后以 --confirm-structural 重跑。
推送凭据：优先配置 git credential helper（git credential fill 可解析即可，GitHub / GitLab 同法）；推 GitLab 镜像时也可设 DSH_PPT_GITLAB_PAT。缺失时推送环节以退出码 6 失败并给出指引。
版本策略：package.json version 镜像上游版本（如 6.7.1）；仅包装层自身变更追加 -rN 后缀。
退出码：0 成功/最新 · 1 用法 · 2 结构变化待人工 · 3 完整性门失败 · 4 校验失败 · 5 网络/来源失败 · 6 推送失败/tag 冲突 · 7 工具链缺失。
目录结构
dsh-ppt-master-plus/
├── package.json / cordis.patch.yml # DSH 插件清单与 bundle 层补丁
├── index.js # 插件入口
├── lib/ # 客户端半边 / 工具 / venv / skill provider / scope
├── skills/ppt-master/ # ★ 上游 vendor 树（逐字节，零改写）
├── scripts/ # sync-upstream / verify-plugin / check-dsh-compat
├── tests/ # node:test 全套（727 用例）
├── docs/superpowers/ # 设计与计划文档（开发史）
├── .github/ # CI 与 issue/PR 模板
└── README / AGENTS.md / CONTRIBUTING.md / NOTICE / LICENSE
开发流程（GitHub Flow）
main 受保护，不直接推送。每次改动走 Issue → 分支 → PR → Squash merge；提交信息用约定式前缀。细节见 CONTRIBUTING.md；面向 agent 的机制备忘、测试地图与版本记账见 AGENTS.md。
本地校验（开发）
node scripts/check-dsh-compat.mjs # 契约检查：spec §7.7 六项（+⑦）设计成立性前置
node --test tests/*.test.mjs # 全套测试（stub SDK 环境 727/715/12 skip）
node scripts/verify-plugin.mjs --upstream .upstream/refs/tags/<ref>@<sha> # 完整性校验（需缓存目录）
无宿主 SDK 的机器（含 CI）：node tests/helpers/stub-sdk.mjs .ci-stub 建默认 stub 树，以 DSH_NODE_MODULES=$PWD/.ci-stub/node_modules 跑前两条（预期 727/715/12 skip，skip 为显式声明：Windows 无权限创建 symlink 等）；机制与红灯形态见 AGENTS.md §4，CI 见 .github/workflows/ci.yml。
版本历史
| 版本（tag） | 说明 |
|---|
v6.7.0 | 首次交付：vendor 上游 v6.7.0 + skill provider + 三生命周期工具 + 三脚本 |
v6.7.0-r1 … r2 | 包装层修订（审查修复波：同步脚本健壮性） |
v6.7.0-r3 | venv 解释器隔离 + 插件页配置卡片 + GitHub 发布面 |
v6.7.1 | 上游同步：vendor v6.7.1（逐字节） |
v6.7.1-r1 | 工具可见范围（scope 双键 + 装配层移除 + guard 兜底） |
v6.7.1-r2 | 审查修复波：scope 运行时加固（safeString / 注入看门狗 / disposed 清理 / 每轮单次刷新）+ 卡片勾选框基值缺失禁用与只读样式 + 契约探针补强 + 单轮严格定位判据 |
v6.7.1-r3 | venv 配置现读：卡片保存后三个工具立即按新 venv.* 工作，不再读 apply 期快照（设计 R8 / issue #16）；配置改坏时保存即告警 |
v6.7.3 | 上游同步：vendor v6.7.3（逐字节）。含 v6.7.2 的「不再静默丢失/覆盖内容」一批修复（skill-only 安装的项目落工作目录、PDF 表格不再按单篇样例重写、HTML/.txt 按声明编码解码、同名批次互不覆盖、图像检索整词匹配、原生图表 part 名冲突、公式 MCE fallback 让 WPS/LibreOffice 不再空白）与 v6.7.3 的 Edit Native 往返修复；另修 verify-plugin 的 baseName 反斜杠兼容（Windows 上第⑥项不再误报） |
v6.7.3-r1 | 包装层修订（本仓库起点）：Windows 运行时支持（python3 → py -3 → python 解析、Scripts\python.exe / Scripts\pip.exe 布局、统一 python -m pip、Microsoft Store 别名诊断）、check_env 回报实际生效的 .env 路径、verify-plugin / sync-upstream 诊断与报告路径归一、GNU tar 盘符规避；测试增至 727 项 |
版本规则：base 镜像上游 release，包装层修订追加 -rN。逐项明细见 AGENTS.md §5。
致谢与许可
- 上游项目：hugohe3/ppt-master（MIT，© 2025-2026 Hugo He）——本包装层的全部能力来自上游技能集，感谢作者的杰出工作。
- 包装层来源：SAXEM1997/dsh-ppt-master-wrapper（MIT，© 2026 dsh-ppt-master-wrapper contributors）——本仓库在它的基础上派生并完成 Windows 支持与上述修订。
- 双 LICENSE 归属：插件根
LICENSE 为本项目自身的 MIT 许可；vendor skills/ppt-master/LICENSE 为上游原文，逐字节保留（受完整性门校验，不得改动）。完整上游版权声明见 NOTICE；vendor 内 SPONSORS*.md 同样逐字节保留，欢迎按上游指引赞助原作者。
MIT，见 LICENSE。
