# 安装和升级

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

## 安装步骤

1. 识别目标 Agent 和范围。Codex 用户级目录通常为 `~/.agents/skills/`；项目级目录为项目内 `.agents/skills/`。若宿主使用其他目录或环境变量，按其实际发现规则传入 `--dest`。不要同时在多个发现目录安装副本。Codex 的目录与启停规则以[官方说明](https://learn.chatgpt.com/docs/build-skills)为准。
2. 克隆用户给出的地址到临时目录，读取根 README、SKILL.md 和本说明；记录 `git rev-parse HEAD`，需要固定版本时 checkout 已审阅的完整提交号。不要使用 `curl | sh`，不要将凭据写入地址或日志。
3. 选择 Python **3.12+**；系统 `python3` 可能较旧，用 `--version` 验证。安装脚本只用标准库；原生导出需要 [runtime/requirements.txt](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。

```sh
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 示例：

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

## 排错和恢复

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

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