dsh-ppt-master-wrapper

首次使用：环境自检、依赖与 .env

1. 环境自检：调用 ppt_master_check_env 工具，确认 python3 就绪、完整性门通过、Python 依赖已安装。

2. 安装 Python 依赖：调用 ppt_master_setup_deps（幂等执行 pip3 install -r "${SKILL_DIR}/requirements.txt"），或手动 pip3 install -r skills/ppt-master/requirements.txt。

3. 配置 .env（按需）：上游图像生成脚本需要图像后端配置。首次使用时从 vendor 的模板复制一份到工作区根目录：

   cp skills/ppt-master/.env.example .env
   

   请在你的会话工作目录（即运行 PPT 生成的 cwd——上游 .env 查找顺序的第 1 位）执行该 cp；插件根目录下的副本也会被上游按第 3 顺位（REPO_ROOT）读取——打包布局下插件根恰为上游 config.py 的 REPO_ROOT；仅当工作目录无 .env 时才会走到该顺位。

   然后按需填写图像后端 API key：设置 IMAGE_BACKEND（推荐核心后端 openai / gemini / qwen / zhipu / volcengine）并取消注释对应提供商的 key/model 行。也可不写 .env，直接以进程环境变量提供同样配置。各项含义与全部可用后端见 .env.example 内注释。

   .env 已列入 .gitignore，不会被提交；本插件工具不读取、不回显 .env 内容或任何密钥。

venv 隔离与配置卡片

插件声明原生 cordis Config（venv.enabled / venv.path / venv.oldPathPolicy，三叶子逐个 .volatile()）。本包自带客户端半边（lib/client.js，经 package.json 的 dsh.client / exports["./client"] 声明），在宿主「插件」页上渲染本插件的配置卡片——这是本版的首选配置入口。宿主侧 dsh-settings.describe() 仍会为带 volatile 的 profile 条目投影出 settings 命名空间；profile cordis.patch.yml 手工条目保留为等价通道（见下节），且该通道手工编辑后不热生效、需重启 DSH。

懒创建：venv 的创建/删除只发生在 ppt_master_setup_deps，改配置本身零副作用。

配置卡片（首选入口）

• 入口路径：GUI 侧边栏 插件页 → 已安装 → dsh-ppt-master-wrapper → 包详情页的配置卡片。
• 卡片内容：三字段（venv.enabled 开关 / venv.path 文本框 / venv.oldPathPolicy 选择器）＋版本信息块（插件版本 / 上游 ppt-master 版本 / 技能目录 /skills/ppt-master），文案中英双语跟随界面语言。
• 保存语义：改动经宿主配置通道保存——三叶子全 volatile ⇒ 走宿主 volatile 快路径（只写 fiber._config + _commitVolatile() → loader/volatile-update，不 remount、不重跑 apply），免重启生效（工具行为与入口 skill 正文随 volatile 引用原地换代）。
• memory 模式：若宿主以 memory 模式提供配置（非回环浏览器），卡片显式提示「当前会话为 memory 模式，本次会话不会写入宿主配置」——写永不落盘，静默失效不可接受。
• 失败呈现：卡片保存失败按两类呈现（宿主拒绝 / 被更高优先级配置层覆盖 vs 传输失败），"被覆盖"只在文案里给一般化提示。
• 等价性：卡片与 profile patch 通道二者等价、先写者为准。

配置指引（profile patch——与卡片等价的通道）

编辑 profile 的 cordis.patch.yml，追加：

- id: dsh-ppt-master-wrapper
  config:
    venv:
      enabled: true
      path: /dsh-home/.ppt-master/venv
      oldPathPolicy: keep

三个字段写全——patch 的 config 是整体替换语义（缺字段回落默认值）；保存后须重启 DSH 生效（这条手工 patch 通道无 watcher 热应用；与插件页卡片的免重启快路径不同）。

venv.path 须为绝对路径或 ~ 前缀（~ 按宿主进程 HOME 展开；相对路径判无效 → venv 视为关闭 + 应用期 console.warn；可见反馈通道＝入口 skill「配置无效」态与 ppt_master_check_env 的 venv.path=null——渲染行逐字打印 venv: enabled=true path=- exists=false python=skipped）。生效核验：ppt_master_check_env 应打印 venv: enabled=true path= …。

宿主设置页 describe 输出的 applies:"live" 是固定输出；手工 patch 通道改后不热生效，别按它推断"改了就热生效"——卡片通道才是免重启的。

默认路径理由：~/.ppt-master/venv 兼顾非容器 DSH 用户的通用性，贴合上游 ~/.ppt-master/.env（USER_ENV_FILE）目录惯例；容器用户宜显式配置到挂载卷（如 /dsh-home/.ppt-master/venv）。

入口技能用法（四态）

任何 ppt-master 路由前先读 ppt-master-env（内存合成、不落盘）。四态：

1. venv 开、已建且就绪（就绪＝解释器 /bin/python3 与安装路径 /bin/pip3 两者都可用，与 setup_deps 的收编体检同一判据）→ 一律以解析后绝对路径的 /bin/python3 替换上游脚本里的字面 python3（含 SKILL.md 第 2 步 attribution_guard.py 的调用），并给出 SKILL_DIR；
2. venv 开但未建 → 先调 ppt_master_setup_deps，在此之前不要用系统 python3 跑业务脚本；
3. venv 关 → 现行系统 python3；
4. 配置无效 → 按正文给出的修正方式处理后按系统模式继续。

未就绪子态（on-ready + broken：bin/python3 不可用，或有 bin/python3 但缺 bin/pip3 的半成品——python3 -m venv 在 ensurepip 阶段失败的残留）不属①：没有可用的解释器路径可替换，正文按②给「先 setup_deps 准备环境」的指引（setup_deps 会以恢复指引 fail-loud：手动删除该目录后重跑；缺 bin/pip3 时另提示"若系统缺 ensurepip，需先安装 python3-venv"）。

三面口径一致：同一形态下 info 报 exists=true ∧ pythonPath=null、check_env 渲染 python=not found（deps 全 UNKNOWN、guard {skipped}）、入口正文按②——不存在"某面说健康、另一面说未就绪"的分叉。正文是插件实例注册期快照：文件系统变化（如 venv 被外部删除）后可能陈旧，以 ppt_master_info / ppt_master_check_env 的实时输出为准。

删除安全与孤儿处理

• 标记即授权：自动删除只对带所有权标记（/.ppt-master-wrapper.json）且同时满足四条件（路径≠当前、新旧路径互不段感知前缀包含、pyvenv.cfg 存在、带标记）的目录生效。条件①②按规范化（canonical）路径判定——重复分隔符、./..、符号链接别名、以及 .. 作用在符号链接上的拼写都按内核语义化到同一形态后比较：同一实体（canonical 相等；另以 dev+ino 相等作额外正判据）与包含关系都据此拒绝，"本次在用的 venv"及其祖先/内部目录绝不会落到删除路径上。前缀包含是段感知的：/a/venv 不包含 /a/venv-older（朴素 startsWith 会误拒，导致旧 venv 永远清不掉）。删除原语收到的仍是配置里那条路径的原值。 退化文件系统注记：别名判定依赖 realpath/st_ino 的可靠性——st_ino/st_dev 为 0 的 FS 上 dev+ino 判据自动停用（否则任意两目录都会"相等"，清理被永久锁死），此时只按 canonical 路径比较；这类文件系统上可能额外拒绝（拒绝面只会更保守）——限定：「不会误删」仅对 realpath 可解析的别名成立，若同时存在 canonical 折不掉的别名（如 bind mount），该保护不覆盖包含面。已标记 venv 目录内混入的用户数据会被递归删除——不要往 venv 目录里放数据。
• 禁用后手动清理：venv.enabled=false 不删除任何目录；oldPathPolicy=keep（默认）时旧 venv 保留待手动清理，delete 也仅删「带所有权标记且满足删除四条件」的旧目录。手动清理：rm -rf 。
• 两类孤儿（均手动处理）：
  1. 未标记孤儿（目录是 venv 但无标记）：清理永不触碰（安全侧默认），info / check_env 也不提示——需手动 rm -rf。
  2. 有标记无登记孤儿：登记位置固定为 /.ppt-master/wrapper-state.json，而 venv 常居持久卷——层级错配：容器场景 HOME 易失，容器重建后登记丢失，旧 venv 便成「有标记但无登记」的孤儿；无登记即无清理依据，永不自动删，只能手动 rm -rf。取舍：登记位置保持 `` 单一、不做多位置登记。

挂载卷 / 镜像不变边界与 PEP 668

• 挂载卷：挂载只保证数据不丢；跨容器重建后 venv 是否可用依赖镜像不变（venv 内符号链接指向容器内绝对路径）。容器挂载卷建议：把 venv.path 显式配置到持久卷（如 /dsh-home/.ppt-master/venv），不要留在容器 rootfs。
• 损坏恢复：镜像换代、或 venv 损坏（未就绪子态）时，恢复方式＝删除重建：rm -rf 后重跑 ppt_master_setup_deps（工具不会自动删除损坏 venv，只给出该指引）；半成品 venv（有 bin/python3 无 bin/pip3）同样＝删除重建；若根因是系统缺 ensurepip，须先 apt install python3-venv，否则删了重建照样失败。
• PEP 668：本机系统 Python 为 PEP 668（EXTERNALLY-MANAGED）时，裸 pip3 install 需 --break-system-packages，且装入容器 rootfs、重建即丢。开启 venv 隔离后由 /bin/pip3 install -r ... 安装，不受 PEP 668 拦截。user / breakSystemPackages 两个参数仅系统模式生效，venv 模式下被忽略并在返回中注明。

配置卡片（首选入口）

• 入口路径：GUI 侧边栏 插件页 → 已安装 → dsh-ppt-master-wrapper → 包详情页的配置卡片。
• 卡片内容：三字段（venv.enabled 开关 / venv.path 文本框 / venv.oldPathPolicy 选择器）＋版本信息块（插件版本 / 上游 ppt-master 版本 / 技能目录 /skills/ppt-master），文案中英双语跟随界面语言。
• 保存语义：改动经宿主配置通道保存——三叶子全 volatile ⇒ 走宿主 volatile 快路径（只写 fiber._config + _commitVolatile() → loader/volatile-update，不 remount、不重跑 apply），免重启生效（工具行为与入口 skill 正文随 volatile 引用原地换代）。
• memory 模式：若宿主以 memory 模式提供配置（非回环浏览器），卡片显式提示「当前会话为 memory 模式，本次会话不会写入宿主配置」——写永不落盘，静默失效不可接受。
• 失败呈现：卡片保存失败按两类呈现（宿主拒绝 / 被更高优先级配置层覆盖 vs 传输失败），"被覆盖"只在文案里给一般化提示。
• 等价性：卡片与 profile patch 通道二者等价、先写者为准。

配置指引（profile patch——与卡片等价的通道）

编辑 profile 的 cordis.patch.yml，追加：

- id: dsh-ppt-master-wrapper
  config:
    venv:
      enabled: true
      path: /dsh-home/.ppt-master/venv
      oldPathPolicy: keep

三个字段写全——patch 的 config 是整体替换语义（缺字段回落默认值）；保存后须重启 DSH 生效（这条手工 patch 通道无 watcher 热应用；与插件页卡片的免重启快路径不同）。

venv.path 须为绝对路径或 ~ 前缀（~ 按宿主进程 HOME 展开；相对路径判无效 → venv 视为关闭 + 应用期 console.warn；可见反馈通道＝入口 skill「配置无效」态与 ppt_master_check_env 的 venv.path=null——渲染行逐字打印 venv: enabled=true path=- exists=false python=skipped）。生效核验：ppt_master_check_env 应打印 venv: enabled=true path= …。

宿主设置页 describe 输出的 applies:"live" 是固定输出；手工 patch 通道改后不热生效，别按它推断"改了就热生效"——卡片通道才是免重启的。

默认路径理由：~/.ppt-master/venv 兼顾非容器 DSH 用户的通用性，贴合上游 ~/.ppt-master/.env（USER_ENV_FILE）目录惯例；容器用户宜显式配置到挂载卷（如 /dsh-home/.ppt-master/venv）。

配置卡片诊断（卡片不出现 / 不可用时的分层排查）

本包自带客户端半边（注册 plugins.bundle.config 卡片，键＝包名），故本版 DSH 应能出配置卡片。若卡片没出现或显示不可用，按四层依次排查：

1. 声明面是否已生效：dsh.client / exports["./client"] 属装载期声明——刚改过 package.json 需重启 DSH 才重新装载客户端半边（仅改 lib/client.js 免重启，stat 轮询热更新）。这是最常见的"改了没反应"。
2. 宿主页是否在场：卡片由插件页渲染，槽位名 plugins.bundle.config；若宿主页 dsh-client-ui-plugin-manager 缺席或未提供该槽位，则槽位无人声明 ⇒ 卡片不出现（与"半边未装载"不同，且宿主对 dsh.client.inject 图内不存在的包静默跳过、不报 warn——inject 只用于装载排序，不是 Cordis 服务注入）。
3. configForms 服务是否可用：该服务经 ctx.inject(['configForms'], cb) 可选接入（不在硬 inject 里）。服务缺失 ⇒ 回调不触发、该接入不注册，但槽位注册照常 ⇒ 卡片显示「配置通道未接入：宿主未提供 configForms 服务」（快照恒 undefined；命名空间未暴露时另显「配置通道不可用」态，两者文案不混用）。
4. 老宿主不认 dsh.client：该字段为惰性元数据，宿主半边照常工作、浏览器不加载任何东西 ⇒ 安静降级，插件功能不受影响（只是没有卡片）；此时配置仍可走 profile patch 通道，或升级宿主。宿主下限：客户端半边依赖 DSH 0.2.0-rc.2 的契约（dsh.engines.dsh 仍写 >=0.1.1-rc.1，故老宿主不会因引擎门被拒装，而是走本条静默降级）。

另有硬失败形态（非安静降级）：硬服务 slots / locale 缺失时 apply 不被调用，宿主以 pending (waiting for service…) 上报；同理若 dsh.client.external 未声明 react，require 命中不了模块表并冒泡出页。单个注册点异常（字典 / 槽位 / 订阅）则各自 try/catch → warn，不影响其余注册点。