演示文稿大师 SAXEM1997/dsh-ppt-master-wrapper

dsh-ppt-master-wrapper

把上游 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-masterGitHub · MIT"]:::up
SYNC["scripts/sync-upstream.mjs下载 → 完整性门 → 替换"]:::tool
VENDOR["skills/ppt-master/逐字节 vendor（零改写）"]:::artifact
HOST["index.jsctx.skills · ctx.tools.register"]:::code
CARD["lib/client.js插件页配置卡片"]:::code
DSH["DeepSeek Harness2 个技能 · 3 个工具+ 插件页配置卡片"]:::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 依赖 |
| python3 ≥ 3.10 | 上游脚本套件与完整性门 | 建议 python3-venv 可用（venv 模式依赖其 ensurepip） |
| pip3 | 安装上游 Python 依赖 | venv 模式下改用 <venv>/bin/pip3，不受 PEP 668 拦截 |
| git / tar | 同步脚本 | 仅同步上游时需要 |

安装到 DSH

方式一：GitHub 直接安装（推荐）
dsh plugin --profile <name> add https://github.com/SAXEM1997/dsh-ppt-master-wrapper.git

方式二：本地路径 link（开发机）
dsh plugin --profile <name> add link:/path/to/dsh-ppt-master-wrapper

方式三——内网镜像（可选，与 GitHub 同源）：把上面的 URL 换成内网 GitLab 上本仓库的地址即可。安装后重启会话，ppt-master 技能即对 agent 可见；客户端半边（配置卡片）须宿主重启一次才首次装载——之后保存配置即免重启生效。

首次使用

1. 环境自检：调用 ppt_master_check_env，确认 python3 就绪、完整性门通过、Python 依赖已安装。
2. 安装 Python 依赖：调用 ppt_master_setup_deps（幂等），或手动 pip3 install -r skills/ppt-master/requirements.txt。
3. 配置 .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 | 无 | 环境自检：python3 就绪度；运行 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-wrapper → 包详情页配置卡片：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）；半成品（缺 bin/pip3）同样删除重建，系统缺 ensurepip 时先装 python3-venv。
- 删除安全：自动删除只碰带所有权标记且满足安全条件的旧 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-wrapper
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 重跑。

推送凭据：设 DSH_PPT_GITLAB_PAT（GitLab 镜像）或配置 git credential helper；缺失时推送环节以退出码 6 失败并给出指引。

版本策略：package.json version 镜像上游版本（如 6.7.1）；仅包装层自身变更追加 -rN 后缀。

退出码：0 成功/最新 · 1 用法 · 2 结构变化待人工 · 3 完整性门失败 · 4 校验失败 · 5 网络/来源失败 · 6 推送失败/tag 冲突 · 7 工具链缺失。

目录结构

dsh-ppt-master-wrapper/
├── 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 全套（720 用例） ├── 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 # 全套测试（本机真实 SDK 环境 720/720）
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 跑前两条（预期 720/718/2 skip，skip 为显式声明）；机制与红灯形态见 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.8.0 | 上游同步：vendor v6.8.0（逐字节）。AI 图像生成默认换 gpt-image-2.5-sunburst（约 1/4 输出 token、约一半耗时、支持真 RGBA 透明），aspect_ratio 接受任意正 W:H，Retry-After 全后端与 manifest 重排生效；Edit Native 的数据变更图表改为原地 patch（渐变/图例/单点标签等保留），合并单元格表格改任一格不再让 --native-charts-and-tables 失败；PPTX 导入零尺寸几何不再硬失败（无法恢复者保留并报告），作者隐藏内容不再泄漏进源 Markdown/Beautify 清单/重建讲解词；source_to_md 保留 Office Math 为 LaTeX、DOCX 文本与 Word 显示一致、EPUB/ODT/RTF 找回被跳过文本；动画时长按 PowerPoint beat 语义；超链接比较前先 XML 解码；支持的 Python 上限改为 3.14 |

版本规则：base 镜像上游 release，包装层修订追加 -rN。逐项明细见 AGENTS.md §5。

致谢与许可

- 上游项目：hugohe3/ppt-master（MIT，© 2025-2026 Hugo He）——本包装层的全部能力来自上游技能集，感谢作者的杰出工作。
- 双 LICENSE 归属：插件根 LICENSE 为本项目自身的 MIT 许可；vendor skills/ppt-master/LICENSE 为上游原文，逐字节保留（受完整性门校验，不得改动）。完整上游版权声明见 NOTICE；vendor 内 SPONSORS*.md 同样逐字节保留，欢迎按上游指引赞助原作者。

MIT，见 LICENSE。