# 配套 skills 的安装与使用

[教程总入口](README.md)

## 1. 这两个 skill 分别做什么

| Skill | 用途 | 不负责 |
| --- | --- | --- |
| [story-studio-authoring](../.agents/skills/story-studio-authoring/SKILL.md) | 逐步带学，或直接帮助编辑、试走章节；素材、分支、动作、奖励、回忆录 | 编辑器 UI 开发、一般小说剧本创作 |
| [story-studio-release](../.agents/skills/story-studio-release/SKILL.md) | 检查客户端剧情包、跨章依赖、封面、配置合并及上线报错 | 编辑器服务部署、通用网站发布 |

两者均包含 SKILL.md、agents/openai.yaml 和精简 references，可独立复制使用。完整逐步教程在本仓库 `docs/tutorials/`；skill 是指导 Codex 如何协助工作的规则，不是另一个剧情运行程序，也不会自动打开服务器权限。

编辑器 0.3.5 的“教程 ↗”入口也能直接阅读本页。左侧“下载教程与 Skill 源文件”提供完整文档和技能目录的 ZIP；解压后包含 `docs/` 和 `.agents/skills/`，可按下文安装。下载到的内容是该编辑器构建时的快照，团队最新版本仍以 Git 仓库为准。

## 2. 从 Git 获取

团队成员拉取本仓库时，应同时取得 `docs/` 和 `.agents/skills/`。不要只复制 SKILL.md，漏掉 references。技能文件都是文本，不包含第一集媒体或访问口令。

本地仓库不等于远程仓库：若团队还没配置 remote，需要先由团队建立并配置远程地址，再推送已审阅的提交。教程的创建不会自动替你上传公网或创建远程仓库。

## 3. 让 Codex 发现 skill

本仓库将技能源码放在 `.agents/skills/`。支持仓库级 skill 发现的 Codex 环境中，以 **story-chapters 仓库目录**作为项目/工作目录，并新开会话后检查技能列表。若会话的工作目录在这个仓库的上一级，不应假定它会递归发现子仓库技能。

若客户端未发现仓库级技能，或希望在任意项目中使用，可以把两个完整技能目录复制到 Codex 的用户技能目录：设置过 CODEX_HOME 时使用 `$CODEX_HOME/skills`，否则 Windows 为 `%USERPROFILE%/.codex/skills`、Linux/macOS 为 `~/.codex/skills`。

Windows PowerShell 示例，在 **story-chapters 仓库根目录**执行。脚本在目标技能已存在时停止，避免把已有定制文件悄悄覆盖：

```powershell
$skillSourceRoot = Join-Path (Get-Location) '.agents/skills'
$skillInstallRoot = if ($env:CODEX_HOME) {
  Join-Path $env:CODEX_HOME 'skills'
} else {
  Join-Path $env:USERPROFILE '.codex/skills'
}
$skillNames = @('story-studio-authoring', 'story-studio-release')
foreach ($skillName in $skillNames) {
  $skillSource = Join-Path $skillSourceRoot $skillName
  $skillTarget = Join-Path $skillInstallRoot $skillName
  if (-not (Test-Path -LiteralPath (Join-Path $skillSource 'SKILL.md'))) {
    throw "缺少技能源文件：$skillSource"
  }
  if (Test-Path -LiteralPath $skillTarget) {
    throw "目标已存在，请先比较并备份：$skillTarget"
  }
}
New-Item -ItemType Directory -Force -Path $skillInstallRoot | Out-Null
foreach ($skillName in $skillNames) {
  Copy-Item -LiteralPath (Join-Path $skillSourceRoot $skillName) -Destination (Join-Path $skillInstallRoot $skillName) -Recurse
}
```

这只是安装方法；本次文档交付不自动写入每个人的全局技能目录。复制后新开会话确认能看到 skill；已有会话不一定动态加载。若暂时没有出现在列表，可明确提供本仓库 SKILL.md 的路径让 Codex 读取。

不要同时维护两份不同版本而不记录：仓库副本是团队源码；全局副本是安装版本。更新先 `git pull`，比较仓库与安装内容，备份有定制的旧版本后复制完整新目录，再新开会话。

## 4. 从零逐步教学

示例请求：

```text
使用 $story-studio-authoring，按 docs/tutorials/01-basics.md 从 B01 开始教我。
编辑器是 http://127.0.0.1:8790/，章节仓库是当前目录。
每次只教一步，等我完成验收再继续；已有工程保留，使用 tutorial-001 作为新练习目录。
```

预期行为：Codex 先确认当前工程与目录是否占用，然后教新建空章；收到“空工程已新建”再教素材导入。它不应因你说“从零”就清空旧章，也不应一次性替你完成全部练习。

继续上次进度：

```text
使用 $story-studio-authoring，我已经完成 A07，奖励测试正常。
当前工程是 tutorial-001-copy，解锁变量为 practice_memory_1。
现在从 A08 教我登记回忆。
```

只说“奖励测试正常”也可在原对话中续课；换会话时附上 [学习记录](learning-record.md) 更可靠。

## 5. 让 Codex 直接辅助制作

```text
使用 $story-studio-authoring，在当前已保存的 tutorial-001-copy 中调整闪避窗口为 1–4 秒，
保留已有成功、失败和奖励路线。完成后验证一次点击成功与一次超时失败。
```

这种请求是代办，不是教学。Codex 应执行范围内的改动、处理保存和验证，不需要每填一个表单都等回复。界面工具不可用时，skill 可使用真实 CLI/API；它必须说明没实际完成的 UI 验证。

## 6. 检查双章交付与报错

```text
使用 $story-studio-release，检查我刚导出的客户端剧情包。
实际文件路径为 D:/Deliveries/tutorial-runtime.zip。
确认含主线与回忆录、封面路径及媒体完整性；先给我手工上传步骤。
```

有全量配置时可继续：

```text
使用 $story-studio-release，把这次包的章节和变量合并到 D:/Deliveries/server-configs 中的完整配置，
保留其他线上章节，输出到新的 merged 目录，并列出差异。由我自己上传服务器。
```

定位历史问题：

```text
使用 $story-studio-release，封面请求中的目录是 Stories，但服务器原版目录为 stories。
根据这次导出包和报错 URL 检查配置与文件对应关系，给我需要替换的具体文件。
```

预期行为：检查真实文件与路径，处理小写 stories，不把局部 ChapterList 直接覆盖完整列表；没有现有配置或上传权限时完成可做的检查并明确缺口，不声称已经上线。

## 7. 团队维护与验证

编辑入口文档时同步检查技能中对应的精简契约。按钮改名、导出路径或动作机制改变，至少更新相关教程步骤、references 及适用版本。

技能目录可以使用安装环境自带的 skill-creator 验证器检查，路径按实际安装位置替换。验证器需要 Python 的 PyYAML 依赖；这是维护时的检查依赖，运行编辑器或读取 skill 不需要它。Windows 上若系统默认文本编码不是 UTF-8，给 Python 加 `-X utf8`：

```sh
python -X utf8 /path/to/skill-creator/scripts/quick_validate.py .agents/skills/story-studio-authoring
python -X utf8 /path/to/skill-creator/scripts/quick_validate.py .agents/skills/story-studio-release
```

格式通过不代表行为正确。建议在独立测试 workspace 进行这些验收：

| 请求 | 应有行为 |
| --- | --- |
| 已完成 B07，现在教图片按钮 | 接 B08，检查宿主，不重建整章 |
| 奖励测试正常，下一步 | 若上下文确认 A07，接 A08，并提醒广告解锁关闭直接解锁 |
| 复制工程后状态串了 | 识别同名业务变量和站点预览存档，不随意重建素材 GUID |
| 从主线导出的包没包含回忆录 | 解释依赖方向，检查回忆录→主线引用后从回忆录导出 |
| 上传后封面 Stories 404 | 核对实际大小写、配置、文件，再提供修复方案 |
| 只给局部 ChapterList，要求保留线上其他章 | 取得或请求全量配置，不假造原章节 |

文档和 skill 可使用单独提交：

```sh
git add README.md docs .agents/skills
git diff --cached --stat
git commit -m "Document story editing workflow and reusable skills"
```

推送使用团队已配置的远程和分支；不要把教程中的示例路径、章节 ID 或测试通过状态直接当成本次真实结果。