Templated-PPT-Master/INSTALL.md

安装和升级

仓库根目录是 ppt-template-workflow，不需要寻找 skills/ 子目录。安装只需 Git、Python 和目标 Agent 的本地 Skill 目录；不依赖其他 Skill。以下步骤适用于独立 Git 服务，无 GitHub 专属 API、账号或安装器要求。

安装步骤

1. 识别目标 Agent 和范围。Codex 用户级目录通常为 ~/.agents/skills/；项目级目录为项目内 .agents/skills/。若宿主使用其他目录或环境变量，按其实际发现规则传入 --dest。不要同时在多个发现目录安装副本。Codex 的目录与启停规则以官方说明为准。
2. 克隆用户给出的地址到临时目录，读取根 README、SKILL.md 和本说明；记录 git rev-parse HEAD，需要固定版本时 checkout 已审阅的完整提交号。不要使用 curl | sh，不要将凭据写入地址或日志。
3. 选择 Python 3.12+；系统 python3 可能较旧，用 --version 验证。安装脚本只用标准库；原生导出需要 runtime/requirements.txt 的九项精确依赖。
4. 在明确的目标路径运行下列命令。首次安装不带 --replace；更新已有版本加上 --replace，旧目录会完整保存在发现目录之外。--prepare-runtime 只在指定 venv 中安装依赖，不修改系统 Python。
5. 运行 --check，确认文件哈希、280 个编译器文件、精确依赖、编译器加载和根入口启用状态。Codex 中只禁用嵌套署名入口，保留其文件与其他配置。下一轮任务可使用 Skill；未发现时重新打开会话或重启客户端。

以下 macOS／Linux 示例中 python3.12 可替换为实际可用的 Python 3.12+ 绝对路径。CODEX_HOME、AGENTS_HOME 若已设置则沿用；这些变量不负责下载 Python。

git clone https://git.commilitia.net/admin/Templated-PPT-Master.git /tmp/templated-ppt-master-install
cd /tmp/templated-ppt-master-install
git rev-parse HEAD
python3.12 --version
python3.12 scripts/install_skill.py \
  --dest "${AGENTS_HOME:-$HOME/.agents}/skills/ppt-template-workflow" \
  --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --venv "${CODEX_HOME:-$HOME/.codex}/runtimes/ppt-template-workflow/venv" \
  --prepare-runtime
python3.12 scripts/install_skill.py \
  --dest "${AGENTS_HOME:-$HOME/.agents}/skills/ppt-template-workflow" \
  --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --venv "${CODEX_HOME:-$HOME/.codex}/runtimes/ppt-template-workflow/venv" --check

临时目录已存在时换一个空目录；不要删除用户已有文件来腾位置。Windows PowerShell 示例：

git clone https://git.commilitia.net/admin/Templated-PPT-Master.git "$env:TEMP\templated-ppt-master-install"
Set-Location "$env:TEMP\templated-ppt-master-install"
$pptAgentsRoot = if ($env:AGENTS_HOME) { $env:AGENTS_HOME } else { Join-Path $HOME '.agents' }
$pptCodexRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
py -3.12 scripts/install_skill.py --dest "$pptAgentsRoot\skills\ppt-template-workflow" --codex-home $pptCodexRoot --venv "$pptCodexRoot\runtimes\ppt-template-workflow\venv" --prepare-runtime
py -3.12 scripts/install_skill.py --dest "$pptAgentsRoot\skills\ppt-template-workflow" --codex-home $pptCodexRoot --venv "$pptCodexRoot\runtimes\ppt-template-workflow\venv" --check

其他兼容 Agent：显式传入其 --dest；不要传入 --codex-home。若它递归发现 SKILL.md，需要使用其原生配置排除安装目录下精确的 runtime/ppt-master/SKILL.md，不要删除或修改上游文件。无法排除时报告该宿主尚未完成发现验证。运行库可用同一脚本准备。

已有运行库和离线环境

已准备好的 venv 可直接传 --venv 而不加 --prepare-runtime；脚本只检查，不调用 pip。也可仅安装 Skill 文件，省略 --venv，结果会明确标为 files-only，不能宣称原生制作已就绪。元数据选择／工程／paint 工具本身支持 Python 3.10+，但本安装入口要求 3.12+ 以覆盖完整原生路线。

离线安装先由安装方准备 Python、精确依赖和所选模板的字体，再将完整 Skill 源码复制到设备并运行安装和检查。使用本地 wheel 时可在创建 venv 后执行 python -m pip install --no-index --find-links /path/to/wheels -r runtime/requirements.txt，然后不带 --prepare-runtime 安装。不得因为依赖缺失就改用其他已安装 Skill。ImageGen、应用操作与 PowerPoint 为按任务需要使用的宿主能力，不随包安装。

template、字体和首次使用

template 不属于 Skill 安装载荷。按用户指定的独立 template 仓库说明安装，或直接给 Agent 一个可读的正式 manifest；不要硬编码默认 template 或 theme。每个模板的字体、素材许可和实际渲染需要单独验证。只有 Skill 安装请求时，不自动下载某组织模板。

首次调用示例和命令见 USAGE.md。安装收据位于目标目录 .installation.json，包含源码版本、提交、完整文件哈希、备份和运行库状态；它不是视觉或 PowerPoint 编辑验收。若目录受另一安装器管理，使用该管理方升级源锁和安装快照，避免其下次同步退回旧版本。

排错和恢复

现象	处理
Git 401／403／404，或要求用户名	确认用户指定地址和访问权限；仅使用现有或用户指定凭据，不自动替换身份
Python 版本过旧或缺少 venv／pip	使用已安装的 3.12+ 或由安装方准备 Python／venv 支持
依赖检查失败	在指定 venv 安装 requirements.txt；已有 Skill 在依赖准备失败时保持原状
目标已存在	已授权更新时加 --replace；不要手工清空目录
目标是符号链接	使用其安装管理方，或显式选择实际目标；脚本拒绝跟随链接替换
Codex 根入口已禁用或嵌套入口存在冲突配置	使用宿主原生配置检查该精确条目；脚本保留现有决定并给出错误
升级后需恢复	停止相关制作，将新目录移出发现路径，再把收据中的备份目录移回原目标；配置备份按需只恢复本次精确条目

脚本不卸载模板、运行库或字体。Windows／其他 Agent 的实际客户端发现、另一物理设备和应用编辑需在目标环境验证，不能由本机源码检查推定。