@oh-story/dsh 0.1.16 → 0.1.18

package/lib/oh-story/skills/story/SKILL.md

@@ -9,7 +9,7 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 ## 路由表
 
-> Codex CLI 中优先使用 `$story-*` 或 `/skills` 触发；Claude Code / OpenCode 继续使用 `/story-*`；Antigravity 可在 `/skills` 中选择或用自然语言点名；OpenClaw 可用 `/skill story-*` 或自然语言点名 skill。下表以 slash command 展示，Codex 可将 `/story-long-write` 等价替换为 `$story-long-write`，OpenClaw 可将其等价替换为 `/skill story-long-write`。
+各宿主的调用写法：Claude Code、OpenCode 用 `/story-*`（Claude 插件安装时为 `/oh-story:story-*`），也可 `Skill("story-*")`；Codex、ZCode 用 `$story-*`（Codex 也可 `/skills`）；OpenClaw 用 `/skill story-*`；Antigravity、Reasonix 在 skill 入口选择或用自然语言点名。下表按 `/story-*` 写，其他宿主照此替换，本文件其余地方同理。
 
 | 用户意图 | 关键词示例 | 路由到 |
 |---|---|---|
@@ -18,8 +18,8 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 | 长篇拆文 | 拆文、分析这本书、黄金三章、灵感库、跨书灵感聚合 | `/story-long-analyze` |
 | 短篇拆文 | 拆短篇、分析这个故事 | `/story-short-analyze` |
 | 长篇扫榜 | 长篇排行、什么火、新书在冒什么、起点/番茄/晋江/七猫长篇 | `/story-long-scan` |
-| 选题决策 | 写什么能爆、帮我选题、选题方向 | `/story-long-scan` |
 | 短篇扫榜 | 短篇排行、知乎盐言排行 | `/story-short-scan` |
+| 选题决策 | 写什么能爆、帮我选题、选题方向 | 长篇 `/story-long-scan`，短篇 `/story-short-scan`；没说篇幅先问一句 |
 | 去 AI 味 | 去 AI 味、太 AI、去味 | `/story-deslop` |
 | 审查稿件 | 审查、审稿、帮我审一下、一致性检查、看看有没有问题 | `/story-review` |
 | 封面 | 封面、封面图 | `/story-cover` |
@@ -29,25 +29,98 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 | 工作台 | dashboard、工作台、看拆文库、浏览项目文件、打开项目面板 | 见下方「Dashboard 工作台」 |
 | 检查/更新版本 | 检查更新、有新版本吗、升级、更新工具箱 | 见下方「版本更新检查」 |
 | 切换/列出书目 | 切书、换书、列出我的书、我在写哪几本、切换项目 | 见下方「多书切换」 |
-| 管理作者习惯 | 记住我的写作习惯、作者画像、待确认偏好、忘掉这个偏好 | `/story-long-write` 或 `/story-short-write`（按下方规则选择） |
-| 查故事资料 | 查角色、查伏笔、查进度、查设定、什么状态、写到哪了 | spawn `story-explorer` agent（结构化 prompt：`项目目录：{dir}\n查询类型：{根据意图选择}\n查询参数：{用户查询}`）；agent 不可用时见下方「查询降级」 |
-| 查资料 | 查资料、帮我查资料、调研、搜索一下、搜一下 | spawn `story-researcher` agent；agent 不可用时见下方「查询降级」 |
+| 管理作者习惯 | 记住我的写作习惯、作者画像、待确认偏好、忘掉这个偏好 | 见下方「作者习惯管理」 |
+| 查故事资料 | 查角色、查伏笔、查进度、查设定、什么状态、写到哪了 | 见下方「查询」 |
+| 查资料 | 查资料、帮我查资料、调研、搜索一下、搜一下 | 见下方「查询」 |
+
+能明确匹配就直接调用对应 skill；匹配不上时只问缺的那一项。用户说"我想写小说"但没说长篇还是短篇，先问篇幅再路由。
 
 ### 裸调用与新手
 
-只说 `/story`、看不出意图时，不贴路由表，给四个白话选项：「开一本长篇或接着写」→ `/story-long-write`；「写一篇短篇」→ `/story-short-write`；「把一章改得不那么 AI」→ `/story-deslop`；「更多（拆书、扫榜、导入旧稿、审稿、封面）」→ 再列进阶项。还没部署过（项目根没有 `.story-deployed`）时先建议 `/story-setup`。
+只说 `/story`、看不出意图时，不贴路由表，给四个白话选项：「开一本长篇或接着写」→ `/story-long-write`；「写一篇短篇」→ `/story-short-write`；「把一章改得不那么 AI」→ `/story-deslop`；「更多（拆书、扫榜、导入旧稿、审稿、封面）」→ 再列进阶项。还没部署过（项目根没有 `.story-deployed`）时先建议 `/story-setup`，并说明部署完要新开一个会话再开始，写作助手才会生效。
 
 ### 导入续写顺序
 
-用户问"导入续写先 setup 还是 import"时，直接回答：**推荐先 `/story-setup`，新开/刷新会话后 `/story-import`，最后 `/story-long-write 日更` 或 `/story-long-write 写第N章`**。如果用户已经直接触发 `/story-import`，按 story-import 自带环境检测继续：未 setup 时让用户选择先去 setup 或继续串行导入。
+用户问"导入续写先 setup 还是 import"时，直接回答：**推荐先 `/story-setup`，新开会话后 `/story-import`；导完长篇说 `/story-long-write 写第N章`（N 是导入后的下一章），短篇用 `/story-short-write` 先补完构思**。如果用户已经直接触发 `/story-import`，按 story-import 自带环境检测继续：未 setup 时让用户选择先去 setup 或继续串行导入。
+
+## 书目录判定
+
+本文件的"书目录""当前书"均按此查找：
+
+1. 项目根有 `.active-book` 且指向项目内一个存在的目录 → 就是它。
+2. 否则在项目根往下最多 4 层找，跳过以 `.` 开头的目录、`node_modules`、`拆文库/`、`对标/`：
+   - 含 `追踪/`、`正文/` 子目录或 `正文.md` 文件的目录（与写作 hook 同一口径）；
+   - 刚定完方向、还没有正文的长篇：含 `设定/题材定位.md` 的目录；
+   - 构思中、还没有正文的短篇：同时有 `设定.md` 与 `小节大纲.md` 的目录。
+   找到多本又没有 `.active-book` 时，需要"当前书"就问作者是哪本（做法同「多书切换」）。
+3. 篇幅：有 `正文/` 或 `设定/` 子目录的是长篇，有 `正文.md` 或 `设定.md` 文件的是短篇。
+
+没找到任何书目录：创建写作项目时先运行 `/story-setup`；只讨论结构、选题，或要扫榜、拆文时直接路由。找到了：按目标 skill 自己的环境检查继续，需要初始化或补部署时运行 `/story-setup`。
+
+## 作者习惯管理
+
+按用户明确指定的长篇/短篇选写作 skill；没指定时按当前书的篇幅。没有当前书的通用习惯交 `/story-long-write` 管理；只针对某本书却定位不到时问是哪本，不要求先建书。路由层只转交，不读写作者记忆文件。
+
+## 查询
+
+### 交给哪个助手、传什么
+
+「查故事资料」交 `story-explorer`，prompt 三行：
 
-### 作者习惯管理路由
+```text
+项目目录：{书目录的绝对路径}
+查询类型：{按下表选}
+查询参数：{用户问到的角色名、伏笔、设定关键词或章节范围}
+```
 
-按用户明确指定的长篇/短篇类型选择对应写作 skill；未指定时用当前书类型（`正文/` 为长篇，`正文.md` 与 `小节大纲.md` 或 `设定.md` 为短篇）。无当前书的通用习惯默认交长篇入口管理；只限定本书却无法定位时问哪本书，不要求先建书。将管理请求交给该写作 skill，路由层不读写作者记忆文件。
+| 用户在问 | 查询类型 |
+|---|---|
+| 某角色现在什么状态 | `character_status` |
+| 某角色在哪几章出场 | `character_appearances` |
+| 某条伏笔的情况 | `foreshadow_status` |
+| 还有哪些伏笔、哪些没收 | `foreshadow_list` |
+| 某个设定怎么定的 | `setting_detail` |
+| 某个设定在哪些章出现过 | `setting_appearances` |
+| 第 X 到 Y 章发生了什么 | `timeline`（查询参数默认带 `perspective: reader`；作者明确问幕后真相时用 `author`） |
+| 写到哪了 | `progress` |
+| 两个角色现在什么关系 | `relationship` |
+
+一句话含多类查询时，分次调用或只选最主要的一类；问的是创作建议而不是查已有内容时，不交给它，主会话直接答。
+
+「查资料」交 `story-researcher`，prompt 按下面写，没有的可选项整行省略：
+
+```text
+query：{要查的主题}
+type：{可选：历史考证、地理/环境、职业知识、文化习俗、器物/服饰、描写参考、命名参考、体系构建、诗词典故、视觉参考、真实案例、读者偏好}
+context：{可选：为什么要查，如正在写哪一段}
+project_dir：{书目录的绝对路径；没有书目录时用项目根}
+cdp_port：{可选：Chrome 调试端口不是 9222 时写}
+```
+
+### 能不能用助手
+
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 36` 不一致时（标记缺失、字段缺失/非整数、小于或大于 36）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时用一句白话提示作者「查资料助手是旧版，运行 /story-setup 后新开会话」，`Notice: agents bundle 版本不匹配（项目 {N}，本版 36）` 原文写进回答最末一行「技术备注：」；大于 36 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，`Fallback: ... -> solo` 同样只进技术备注行。
+
+走助手前先做轻量可用性检查（路由只做这一层，不承担全局部署策略）：当前不在子代理上下文、当前运行时的 Agent/Task 或 `invoke_subagent` 工具可用，且对应部署文件存在（Claude `.claude/agents/*.md`、OpenCode `.opencode/agents/*.md`、Codex `.codex/agents/*.toml`、Antigravity `.agents/agents/agent-name/agent.md`，其中 `agent-name` 为目标 agent 名）→ 可尝试 spawn。Antigravity 用 `invoke_subagent` + 同名 `TypeName`，不得因其他端文件存在而误判。任一不满足，或运行时返回 unknown agent / 未暴露 custom-agent registry，则降级处理：
+
+- `story-explorer` 不可用 → 主会话直接用 Read/Grep 从书目录检索（角色状态、伏笔、进度、设定），回答前说一句「查资料助手没启用，这次我直接翻项目文件」；项目尚未部署时提示先 `/story-setup`。
+- `story-researcher` 不可用 → 主会话用当前可用的搜索能力回答，回答前说一句「查资料助手没启用，这次我直接搜」；搜不到就如实说明。
+
+### 怎么回答作者
+
+讲故事里的事（谁、在哪章、发生了什么）；文件字段名、伏笔/事件编号不单独出现，编号必须跟着故事描述。助手返回的英文字段和缺口说明由主会话翻成白话再说。
+
+## 多书切换
+
+用户想切换或查看在写的书时（一个项目可同时有多本）：
+
+1. 按「书目录判定」第 2 条列出所有书目录，标出当前 `.active-book` 指向的那本。
+2. 让用户选择，把所选书的相对路径写入项目根 `.active-book`（覆盖原内容）。
+3. 只发现一本时直接确认为活跃书，无需询问。
 
 ## Dashboard 工作台
 
-用户执行 `/story dashboard`（Codex 为 `$story dashboard`），或明确要求打开工作台、查看项目文件时，启动本 skill 的本地 Dashboard：
+用户执行 `/story dashboard`，或明确要求打开工作台、查看项目文件时，启动本 skill 的本地 Dashboard：
 
 1. 把**当前工作目录**作为默认工作区；用户明确给出目录时改用该目录。目录必须存在。
 2. 从当前已加载的 `story` skill 目录定位 `scripts/dashboard-server.mjs`，不要硬编码仓库路径、
@@ -63,62 +136,29 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 5. Dashboard 默认只监听 `127.0.0.1`。不要主动增加 `--allow-network`，不要把工作区暴露到
    局域网或公网。
 
-工作台会识别标准 `拆文库/{书名}/`，兼容存量 `拆文库-{书名}/`。写作项目识别同时支持：
+工作台按自己的规则识别目录，与上方「书目录判定」不同：识别标准 `拆文库/{书名}/`，兼容存量 `拆文库-{书名}/`；写作项目识别同时支持：
 
 - 长篇目录结构：目录内含 `正文/`、`大纲/`、`设定/` 或 `追踪/` 任一普通子目录。
 - 短篇单文件结构：目录内含普通文件 `正文.md`，并同时含 `小节大纲.md` 或 `设定.md`。
 
 符号链接不作为项目标记，只有单个 `正文.md` 的资料目录不识别为写作项目。浏览器可编辑 `.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`；保存或确认删除时核对文件内容版本，避免覆盖外部修改。
 
-停止服务时终止对应的 Node 长运行进程即可。若用户只问用法，不要替他启动；给出
-`/story dashboard` / `$story dashboard` 两种平台对应入口。
-
-## 路由流程
-
-1. 分析用户请求，提取意图关键词
-2. 匹配上表，找到对应的 skill
-3. 如果能明确匹配，直接调用对应 skill（Claude/OpenCode 可用 `Skill("skill-name")` 或 slash command；Codex 用 `$skill-name` / `/skills`；Antigravity 用 `/skills` 或自然语言点名；OpenClaw 用 `/skill skill-name` 或自然语言点名）
-4. 无法匹配时只问缺失信息；写作篇幅按下一条处理
-5. 如果用户说"我想写小说"但未指定长篇/短篇，询问篇幅类型后再路由
-
-## 查询降级
-
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 35` 不一致时（标记缺失、字段缺失/非整数、小于或大于 35）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 35）` 并提示重新运行 `/story-setup` 后新开会话；大于 35 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
-
-「查故事资料」「查资料」走 agent 前先做轻量可用性检查（路由只做这一层，不承担全局部署策略）：当前不在子代理上下文、当前运行时的 Agent/Task 或 `invoke_subagent` 工具可用，且对应部署文件存在（Claude `.claude/agents/*.md`、OpenCode `.opencode/agents/*.md`、Codex `.codex/agents/*.toml`、Antigravity `.agents/agents/agent-name/agent.md`，其中 `agent-name` 为目标 agent 名）→ 可尝试 spawn。Antigravity 用 `invoke_subagent` + 同名 `TypeName`，不得因其他端文件存在而误判。任一不满足，或运行时返回 unknown agent / 未暴露 custom-agent registry，则降级，不硬失败：
-
-- `story-explorer` 不可用 → 主会话直接用 Read/Grep 从项目文件检索（角色状态/伏笔/进度/设定），回答前说一句「查资料助手没启用，这次我直接翻项目文件」；项目尚未部署时提示先 `/story-setup`（Codex 中用 `$story-setup`）。
-- `story-researcher` 不可用 → 主会话用现有检索/回答能力完成，或提示用户改用 `/browser-cdp` 采集，同样用一句白话说明。
-
-回答作者时讲故事里的事（谁、在哪章、发生了什么）；文件字段名、伏笔/事件编号不单独出现，编号必须跟着故事描述。
-
-## 项目状态感知
-
-路由前先检查当前项目状态：
-
-- **无项目目录**（没有包含 `追踪/` 或 `设定/` 的书名目录，也没有同时有 `正文.md` 与 `小节大纲.md`（或 `设定.md`）的短篇目录）：
-  - 创建写作项目时先运行 `/story-setup` 初始化环境（Codex 中用 `$story-setup`）；只讨论结构或选题时直接路由
-  - 如果用户要扫榜/拆文，直接路由
-- **已有项目**：读取 `.story-deployed`，按目标 skill 的环境检查继续；查询沿用上方降级，导入保留串行选项。需要初始化或补部署时运行 `/story-setup`（Codex 中用 `$story-setup`）。
-
-## 多书切换
-
-用户想切换或查看在写的书时（一个项目可同时有多本）：
-
-1. 在项目根查找所有书目录：包含 `追踪/` 或 `设定/` 子目录的目录，或同时有 `正文.md` 与 `小节大纲.md`（或 `设定.md`）的目录（含 `长篇/`、`短篇/` 下的子目录）。
-2. 列出书名，并标出当前 `.active-book` 指向的那本。
-3. 让用户选择，把所选书的相对路径写入项目根 `.active-book`（覆盖原内容）。
-4. 只发现一本时直接确认为活跃书，无需询问。
+停止服务时终止对应的 Node 长运行进程即可。若用户只问用法，不要替他启动；告诉用户用 `/story dashboard`（按上方宿主写法替换）。
 
 ## 版本更新检查
 
 用户问“有没有新版本”“检查更新”“升级”时执行。**先报告版本，是否安装由用户决定。**
 
-1. **当前版本**：读本 skill 同目录的 `VERSION` 文件；缺失则视为未知。
+1. **当前版本**：读本 skill 同目录的 `VERSION` 文件；缺失则视为未知。本 skill 在写作项目里（如项目下的 `skills/`、`.agents/skills/`、`.zcode/skills/`）时，读到的是项目副本的版本。
 2. **最新版本**：优先 `gh release view --json tagName,name,url -R zenstory-ai/oh-story-claudecode` 取 `tagName`；无 gh 用 `curl -fsS --max-time 5 https://api.github.com/repos/zenstory-ai/oh-story-claudecode/releases/latest` 取 `.tag_name`（jq 或 grep）。查不到 → 告知"暂时拉不到最新版本，可手动看 [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)"，不报错。
 3. **比较**：当前版本已知时，去掉 `v` 前缀按语义版本比较（major.minor.patch）；未知时只展示最新稳定版，不判定是否已最新。`gh release` 默认取 latest 稳定版，不含 pre-release。
 4. **告知**：
    - 已最新 → 「已是最新版 vX.Y.Z」。
-   - 有新版或当前版本未知 → 展示已知版本与 [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)/[CHANGELOG](https://github.com/zenstory-ai/oh-story-claudecode/blob/main/CHANGELOG.md)，有 release notes 时附更新要点，再用宿主可用的提问方式问「现在更新吗？」：
-     - 选更新 → 跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`（`-g` 全局，去掉则只更当前目录）；完成后提示：已部署过的项目在项目根重跑 `/story-setup`（Codex 中用 `$story-setup`）同步 hooks/agents/references，并**新开一个会话**让 agents 重新注册。
-     - 选先不 → 不动，告知随时可再来。
+   - 有新版或当前版本未知 → 展示已知版本与 [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)/[CHANGELOG](https://github.com/zenstory-ai/oh-story-claudecode/blob/main/CHANGELOG.md)，有 release notes 时附更新要点，再用宿主可用的提问方式问「现在更新吗？」。选先不 → 不动，告知随时可再来。
+5. **更新**（用户同意后）：按本 skill 目录的位置判断安装方式。
+   - 在插件目录里（路径含 `plugins/`）：Claude Code 跑 `claude plugin marketplace update oh-story-skills` 再跑 `claude plugin update oh-story@oh-story-skills`，重启后生效；ZCode 在 Plugin Management 里刷新市场后更新 `oh-story`。
+   - 用 `npx skills` 装在全局或当前目录：重跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`（原来装在当前目录的去掉 `-g`）。
+   - 其他安装方式（如 ClawHub）：按原来的方式重装最新版。
+   - 本 skill 在写作项目里：先用上面对应的方式更新安装包，再用新装的包在项目根运行 `/story-setup`，项目里的副本才会换成新版；OpenClaw、Reasonix 和通用文件模式下项目里跑的就是这份旧副本，要用新包手动覆盖项目 `skills/` 下的 13 个 skill 目录。
+
+   更新完提示：已部署过的项目在项目根重跑 `/story-setup` 同步 hooks、agents 和参考资料，然后**新开一个会话**，写作助手才会重新加载。

package/lib/oh-story/skills/story/VERSION

@@ -1 +1 @@
-0.8.6
+0.9.0

package/lib/oh-story/skills/story-cover/SKILL.md

@@ -13,259 +13,79 @@ metadata: {"openclaw":{"requires":{"env":["GPT_IMAGE_API_KEY"],"bins":["curl","j
 ## 生成通路
 
 - **Codex 内置（优先）**：当前 Codex CLI 会话可调用 `$imagegen` / `image_gen` 时，直接调用工具生成并保存，无需 `OPENAI_API_KEY` 或 `GPT_IMAGE_API_KEY`，不运行 `curl`。
-- **API 回退**：仅在会话没有内置工具或用户明确指定 API 时使用，需要 `GPT_IMAGE_API_KEY`。工具缺失不等于 Codex 订阅不支持生图；内置调用失败时先报告错误，不静默切换到可能收费的 API。
-
-## 输出参数与 API 回退环境变量
-
-| 变量 | 必填 | 默认 | 说明 |
-|:-----|:----:|:-----|:-----|
-| `GPT_IMAGE_API_KEY` | API 回退必填 | — | OpenAI 或兼容代理的 API Key；Codex 内置通路不用 |
-| `GPT_IMAGE_BASE_URL` | | `https://api.openai.com/v1` | 兼容代理时改这个 |
-| `GPT_IMAGE_MODEL` | | `gpt-image-2` | 仅在测试新模型时覆盖 |
-| `GPT_IMAGE_SIZE` | | `1024x1536` | API 回退的请求尺寸：番茄 3:4→`768x1024`，默认 2:3→`1024x1536`。实际尺寸以出图结果为准，固定上传像素由「导出平台上传尺寸」步骤保证 |
-| `UPLOAD_SIZE` | | — | 平台固定上传像素（番茄 `600x800`）；设置后由「导出平台上传尺寸」步骤居中裁剪+缩放出上传版（不变形、不依赖出图尺寸） |
-| `BOOK_DIR` | ✅ | — | 输出目录，建议 `./covers/<书名>` |
-| `REF_IMAGE` | | — | 参考图本地路径或 URL；内置通路先把图片载入会话，API 回退走 `images/edits` 图生图 |
-
----
+- **API 回退**：仅在会话没有内置工具或用户明确指定 API 时使用，需要 `GPT_IMAGE_API_KEY`；环境变量和命令在 [references/api-fallback.md](references/api-fallback.md)，走这条通路时再读。工具缺失不等于 Codex 订阅不支持生图；内置调用失败时先报告错误，不静默切换到可能收费的 API。
 
 ## 生成流程
 
 ### Step 1：收集信息
 
-必填：书名、作者名（笔名）、目标平台、输出目录 `BOOK_DIR`。目录建议为 `./covers/<书名>`；API 回退通过环境变量传入，内置通路直接使用本次确定的目录。问作者时说「封面存在哪？默认 `./covers/<书名>`」。
-选填：参考图 `REF_IMAGE`（本地路径或 URL）、风格偏好、尺寸；参考图的用法见 Step 4 对应通路。
-
-> **书名和笔名是封面必需信息**：缺任一时，先用宿主可用的提问方式请作者补全，不得编造或留空。
+先找当前书：项目根 `.active-book` 指向项目内现有目录时就是当前书；否则从项目根往下最多 4 层找（跳过 `.` 开头的目录、`node_modules`、`拆文库/`、`对标/`），含 `追踪/`、`正文/`、`设定/` 子目录或 `正文.md`、`设定.md` 文件的是书目录，找到多本时请作者选择。有 `正文/` 或 `设定/` 子目录的是长篇，有 `正文.md` 或 `设定.md` 的是短篇。找到后读：
 
-**按目标平台定封面尺寸**：番茄上传 600×800，比例为 **3:4**；出图比例不符时，平台再次裁剪可能切掉书名或笔名。
+- 长篇：`设定/题材定位.md`「基本信息」的书名、题材类型、目标平台、核心梗；
+- 短篇：`设定.md`「基本信息」的标题、目标平台、目标情绪，以及「一句话梗概」「题材招式」。
 
-| 平台 | 上传尺寸 | 比例 | 生成 `GPT_IMAGE_SIZE`（尽量） |
-|:-----|:--------|:-----|:-------------------|
-| 番茄小说 | 600×800 | 3:4 | `768x1024` |
-| 其他平台（默认竖版） | 按平台规格 | 2:3 | `1024x1536` |
+已有字段不再问；笔名不在这些文件里，每次都要问。没有书目录或缺项时，用宿主可用的提问方式一次问齐：书名、笔名、目标平台。
 
-内置通路把目标比例写进提示词；API 回退再 `export GPT_IMAGE_SIZE`。平台有固定上传像素时设置 `UPLOAD_SIZE`（番茄 `600x800`），在 Step 5 居中裁剪并缩放到精确尺寸。平台与题材风格见 [references/cover-styles.md](references/cover-styles.md)。
+> **书名和笔名是封面必需信息**：缺任一时先请作者补全，不得编造或留空。
 
-### Step 2：题材判定
-
-扫描书名（必要时简介）中的关键词，对照 [references/cover-styles.md](references/cover-styles.md) 的「题材推断规则」表选定题材。
-
-- 单题材命中 → 直接采用
-- 多题材命中 → 按优先级取一：仙侠 > 西幻 > 古言 > 现言 > 都市 > 悬疑 > 科幻 > 历史 > 灵异 > 轻小说
-- 零命中 → 默认 `都市`
-
-### Step 3：构建提示词
+选填：参考图 `REF_IMAGE`（本地路径或 URL）、风格偏好；参考图的用法见 Step 4。
 
-提示词 = **文字层** + **风格层** + **画面层**。设计指令用英文，书名和笔名保留作者提供的原文。
+**保存位置**：有书目录时存到 `{书目录}/封面/`，不用问；没有书目录时用 `./covers/{书名}/封面/`。下文 `BOOK_DIR` 指 `封面/` 的上一层。
 
-#### 文字层：书名 + 作者名字体设计
+**按目标平台定比例和上传尺寸**：番茄上传 600×800，比例 **3:4**，出图比例不符时平台再次裁剪可能切掉书名或笔名；其他平台按竖版 2:3 交付，作者给出平台上传像素时按该尺寸导出。各平台的画风关键词见 [references/cover-styles.md](references/cover-styles.md)「平台风格」。
 
-在提示词中直接包含中文书名和作者名，GPT-Image-2 可直接渲染。**重点描述字体风格**：
-
-```
-Title text '书名' at top center in [书名字体风格].
-Author name '作者名' at bottom center in [作者名字体风格].
-```
-
-#### 书名字体风格
-
-| 题材 | 描述关键词 |
-|:-----|:-----------|
-| 玄幻/仙侠 | `bold golden brush calligraphy with metallic glow and sharp strokes` |
-| 都市 | `modern bold sans-serif with metallic silver finish` |
-| 古言/宫斗 | `elegant golden traditional Kai script with ornate decoration` |
-| 现言/甜宠 | `soft rounded handwritten style in white with pink glow` |
-| 悬疑/推理 | `distorted bold cracked letters in blood red` |
-| 科幻/末世 | `neon glowing futuristic font in electric blue` |
-| 西幻 | `metallic embossed fantasy lettering with glow effect` |
-| 历史/军事 | `heavy stone-carved seal script in deep red` |
-| 灵异/恐怖 | `eerie dripping handwritten font in sickly green` |
-| 轻小说 | `colorful cartoon outlined bubbly font` |
-
-#### 作者名字体风格（重点：作者名必须精心设计，不能只是"小字"）
-
-作者名指定**字体、颜色和装饰元素**，与书名风格呼应，保持清晰可读而不抢焦点。
+### Step 2：题材判定
 
-| 题材 | 作者名风格提示词 |
-|:-----|:----------------|
-| 玄幻/仙侠 | `small refined white serif text with faint golden glow, flanked by delicate cloud-scroll ornaments on both sides, resting on a thin horizontal gold line` |
-| 都市 | `small clean white modern text with subtle drop shadow, positioned above a thin silver horizontal divider line` |
-| 古言/宫斗 | `small elegant dark red traditional text inside a thin golden rectangular border frame with corner decorations` |
-| 现言/甜宠 | `small soft pink-white handwritten text with a tiny heart motif on the left side, light sparkle effect` |
-| 悬疑/推理 | `small pale grey text with slight blur effect, almost hidden in the shadows, a thin cracked line underneath` |
-| 科幻/末世 | `small crisp white monospace text with subtle cyan scanline overlay, flanked by small geometric brackets` |
-| 西幻 | `small bronze medieval script text with aged parchment texture, enclosed in a small decorative shield or banner shape` |
-| 历史/军事 | `small dignified white Song typeface text above a double horizontal line in dark red` |
-| 灵异/恐怖 | `small faded grey-green text slightly tilted, with a thin dripping ink line above` |
-| 轻小说 | `small playful rounded white text with pastel color outline, tiny star decorations on both sides` |
+在 [references/cover-styles.md](references/cover-styles.md) 的「风格库」里选一个题材：
 
-**作者名通用规则**：
-- 大小：`small`（不能太大抢书名焦点，也不能太小看不清）
-- 位置：`at bottom center`，与画面底部保持适当间距
-- 必须有装饰元素：线条/边框/小图标/光效中至少一种
-- 颜色与背景形成对比但不刺眼
+1. 有「题材类型」（长篇）或梗概、题材招式（短篇）时，按内容选风格库中最接近的一节。
+2. 没有，或对不上风格库任何一节（如年代、种田、无限流、电竞）时，用书名（必要时简介）对照「题材推断规则」：只命中一个题材就用它；命中多个按该表下方的优先级取一；都没命中先用「都市」。
+3. 第 2 条推断出的题材，在 Step 4 给作者看方案时一并说出来，作者可以改。
 
-#### 风格层：平台风格
+### Step 3：构建提示词
 
-从 [references/cover-styles.md](references/cover-styles.md) 的「平台风格」节选取目标平台对应的关键词串。
+提示词 = **文字层** + **风格层** + **画面层**。设计指令用英文，书名和笔名保留作者提供的原文。所选题材的字体、标签、色彩、人物、背景、光效都在「风格库」同一节里查。
 
-#### 画面层：题材 + 构图
+**文字层**：GPT-Image-2 可直接渲染中文。书名在上方居中，用该题材的书名字体；笔名在下方居中，用该题材的笔名字体。笔名要和书名风格呼应、清晰可读而不抢焦点：
 
-从 [references/cover-styles.md](references/cover-styles.md) 读取题材对应的风格标签、色彩、人物、背景描述。
+- 大小用 `small`；位置 `at bottom center`，与画面底部留出间距；
+- 必须带一种装饰：线条、边框、小图标或光效；
+- 颜色与背景形成对比但不刺眼。
 
-构图变体（首次输出 2-3 个方案）：
+**风格层**：目标平台在「平台风格」表里有对应时，取它的关键词串；没有对应（如黑岩、红果、小程序）时省掉这一层，只靠题材风格。
 
-| 方案 | 构图 | 适合题材 |
-|:-----|:-----|:---------|
-| A | 人物特写 + 场景 | 全题材通用 |
-| B | 全身像 + 动态姿势 | 玄幻、都市、西幻 |
-| C | 纯场景/氛围图 | 悬疑、科幻、历史 |
+**画面层**：题材的风格标签、人物、背景、色彩、光效，加上一种构图（见「构图变体」）。
 
-#### 完整提示词模板
+完整提示词模板（唯一一份，示例和改版都按它拼）：
 
 ```
 Chinese web novel cover design, [平台风格].
-Title text '{书名}' at top center in [书名字体风格].
-Author name '{作者名}' at bottom center in [作者名字体风格 — 从上表选择].
-[题材风格标签]. [人物描述]. [背景描述].
+Title text '{书名}' at top center in [书名字体].
+Author name '{笔名}' at bottom center in [笔名字体].
+[题材风格标签]. [构图关键词]. [人物描述]. [背景描述].
 [色彩指令]. [光效指令].
 Professional book cover, high detail digital painting, portrait [平台比例：番茄=3:4，默认=2:3] ratio, keep title and author name inside the central safe area away from edges (inner ~85%), no watermark
 ```
 
-#### 提示词技巧（实测验证）
+写法要点：
+- 人物描述写清服饰、姿态、发型、表情、道具，不要只写 `a man`；
+- 背景分三层：前景人物或道具，中景场景，远景氛围；
+- 光效写清光源方向和颜色，如 `dramatic golden light from above`；
+- 用 `digital painting style`，不用 `photo`，避免真人照片感。
 
-- 人物描述越具体越好：服饰、姿态、发型、表情、道具每个维度都指定
-- 背景分层：前景（人物）→ 中景（场景）→ 远景（氛围）
-- 光效是指定光源方向 + 颜色（如 `dramatic golden light from above`）
-- 用 `digital painting style` 而非 `photo`，避免真人照片感
+### Step 4：选方案并生成
 
-### Step 4：生成并保存
+先从「构图变体」里挑 2-3 种适合本题材的构图，每种用一句话描述画面（构图、主色、书名字体），连同 Step 2 定的题材一起给作者挑。作者选定后只生成那一张；作者说「都出」时每个方案单独生成一次。
 
 #### Codex 内置 ImageGen（优先）
 
 1. 用 Step 3 的完整提示词调用 `image_gen`。比例和安全区写进提示词，不传 `GPT_IMAGE_MODEL`、`GPT_IMAGE_SIZE`、`response_format` 等 API 参数。
 2. 有 `REF_IMAGE` 时，本地文件先用图片查看工具载入会话；URL 先下载再载入。说明它是编辑目标还是风格参考，并列出必须保持的内容。
-3. 每个构图方案单独调用一次。先创建 `BOOK_DIR/封面/`，再把工具返回的图片复制为 `封面_vN.png`，`N` 自增且不覆盖旧版；保留 `$CODEX_HOME/generated_images/` 原文件，同时保存同名 `.prompt.txt`，有参考图再保存 `.ref.txt`。确认图片可读，并把原图绝对路径交给 Step 5。
+3. 先创建 `BOOK_DIR/封面/`，再把工具返回的图片复制为 `封面_vN.png`，`N` 自增且不覆盖旧版；保留 `$CODEX_HOME/generated_images/` 原文件，同时保存同名 `.prompt.txt`，有参考图再保存 `.ref.txt`。确认图片可读，并把原图绝对路径交给 Step 5。
 
 #### API 回退
 
-`gpt-image-2` 返回 base64，请求体不带 `response_format`。`$PROMPT` 使用 Step 3 拼出的完整提示词。
-
-两种调用方式二选一：未设置 `REF_IMAGE` → 走「文生图」；设置了 → 走「图生图」。
-
-#### 文生图（默认）
-
-```bash
-set -euo pipefail
-: "${GPT_IMAGE_API_KEY:?请设置 export GPT_IMAGE_API_KEY=你的key}"
-: "${PROMPT:?请先 export PROMPT=构建提示词步骤拼好的完整提示词}"
-BASE_URL="${GPT_IMAGE_BASE_URL:-https://api.openai.com/v1}"
-MODEL="${GPT_IMAGE_MODEL:-gpt-image-2}"
-SIZE="${GPT_IMAGE_SIZE:-1024x1536}"
-BOOK_DIR="${BOOK_DIR:?请先 export BOOK_DIR=./covers/<书名>}"
-
-mkdir -p "$BOOK_DIR/封面"
-
-# 自增版本号，避免覆盖之前生成的封面
-i=1
-while [ -f "$BOOK_DIR/封面/封面_v${i}.png" ]; do i=$((i+1)); done
-OUT="$BOOK_DIR/封面/封面_v${i}.png"
-RESP=$(mktemp)
-trap 'rm -f "$RESP"' EXIT
-
-# 用 jq 拼 JSON 体，避免 PROMPT 里的引号/换行/中文把 shell 字符串撑破
-BODY=$(jq -n \
-  --arg m "$MODEL" \
-  --arg p "$PROMPT" \
-  --arg s "$SIZE" \
-  '{model:$m, prompt:$p, size:$s}')
-
-curl -fsS --max-time 180 --retry 2 --retry-delay 5 \
-  "$BASE_URL/images/generations" \
-  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d "$BODY" > "$RESP"
-
-# API 出错时早退，避免把 error JSON 当成 base64 写成损坏 PNG
-if jq -e '.error' "$RESP" >/dev/null 2>&1; then
-  echo "API error:" >&2
-  jq '.error' "$RESP" >&2
-  exit 1
-fi
-
-# `// empty` 让缺失字段输出空串而非 "null"，配合下面的 -s 检查避免写出 3 字节假 PNG
-jq -er '.data[0].b64_json // empty' "$RESP" | base64 --decode > "$OUT"
-[ -s "$OUT" ] || { echo "empty or malformed output: $OUT" >&2; head -c 300 "$RESP" >&2; exit 1; }
-
-# 落地提示词副本，方便迭代时基于上一次微调
-printf '%s\n' "$PROMPT" > "${OUT%.png}.prompt.txt"
-
-file "$OUT"
-ls -lt "$BOOK_DIR/封面/"
-```
-
-#### 图生图（提供参考图时）
-
-下面的 `/v1/images/edits` 命令通过 `multipart/form-data` 上传本地图片，不加 `Content-Type: application/json`。文本字段用 `--form-string`，图片字段用 `-F image=@path`。
-
-```bash
-set -euo pipefail
-: "${GPT_IMAGE_API_KEY:?请设置 export GPT_IMAGE_API_KEY=你的key}"
-: "${PROMPT:?请先 export PROMPT=构建提示词步骤拼好的完整提示词}"
-BASE_URL="${GPT_IMAGE_BASE_URL:-https://api.openai.com/v1}"
-MODEL="${GPT_IMAGE_MODEL:-gpt-image-2}"
-SIZE="${GPT_IMAGE_SIZE:-1024x1536}"
-BOOK_DIR="${BOOK_DIR:?请先 export BOOK_DIR=./covers/<书名>}"
-REF_IMAGE="${REF_IMAGE:?请先 export REF_IMAGE=本地路径或 URL}"
-
-mkdir -p "$BOOK_DIR/封面"
-
-# 自增版本号
-i=1
-while [ -f "$BOOK_DIR/封面/封面_v${i}.png" ]; do i=$((i+1)); done
-OUT="$BOOK_DIR/封面/封面_v${i}.png"
-RESP=$(mktemp)
-REF_TMP=""
-trap '[ -n "$REF_TMP" ] && rm -f "$REF_TMP"; rm -f "$RESP"' EXIT
-
-# URL 先下载到临时文件，本地路径直接用。用裸 mktemp 以保证 macOS/Linux 行为一致。
-case "$REF_IMAGE" in
-  http://*|https://*)
-    REF_TMP=$(mktemp)
-    curl -fsSL --max-time 60 -o "$REF_TMP" "$REF_IMAGE"
-    REF_LOCAL="$REF_TMP"
-    ;;
-  *)
-    [ -f "$REF_IMAGE" ] || { echo "参考图不存在: $REF_IMAGE" >&2; exit 1; }
-    REF_LOCAL="$REF_IMAGE"
-    ;;
-esac
-
-curl -fsS --max-time 240 --retry 2 --retry-delay 5 \
-  "$BASE_URL/images/edits" \
-  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
-  --form-string "model=$MODEL" \
-  --form-string "size=$SIZE" \
-  --form-string "prompt=$PROMPT" \
-  -F "image=@$REF_LOCAL" > "$RESP"
-
-if jq -e '.error' "$RESP" >/dev/null 2>&1; then
-  echo "API error:" >&2
-  jq '.error' "$RESP" >&2
-  exit 1
-fi
-
-# `// empty` 让缺失字段输出空串而非 "null"，配合 -s 检查避免写出 3 字节假 PNG
-jq -er '.data[0].b64_json // empty' "$RESP" | base64 --decode > "$OUT"
-[ -s "$OUT" ] || { echo "empty or malformed output: $OUT" >&2; head -c 300 "$RESP" >&2; exit 1; }
-
-printf '%s\n' "$PROMPT"    > "${OUT%.png}.prompt.txt"
-printf '%s\n' "$REF_IMAGE" > "${OUT%.png}.ref.txt"
-
-file "$OUT"
-ls -lt "$BOOK_DIR/封面/"
-```
+读 [references/api-fallback.md](references/api-fallback.md)，按其中的环境变量和命令生成；没有参考图走文生图，有参考图走图生图。生成后把原图绝对路径交给 Step 5。
 
 ### Step 5：导出平台上传尺寸（平台有固定像素时）
 
@@ -302,12 +122,12 @@ fi
 | 检查项 | 标准 |
 |:-------|:-----|
 | 文字渲染 | 书名、笔名清晰可辨，字体风格匹配题材 |
-| 题材匹配 | 视觉风格与书名题材一致 |
+| 题材匹配 | 视觉风格与本书题材一致 |
 | 构图合理 | 主体突出，文字不遮挡核心画面 |
-| 平台适配 | 符合目标平台的封面风格调性 |
+| 平台适配 | 符合目标平台的封面风格 |
 | 平台尺寸 | 比例与平台一致；缩放到上传尺寸后书名、笔名完整可见、未被裁切 |
 
-未达标或作者希望调整时，可更换构图、色调、字体或平台风格。
+未达标或作者希望调整时，可更换构图、色调、字体或平台风格，改完重新生成一张。
 
 交付时这样告诉作者；命令、环境变量和接口报错不贴给作者，失败时用一句话说原因和办法（如「生图接口没配好，需要先设置 API Key」）：
 
@@ -322,6 +142,7 @@ fi
 
 ## 参考资料
 
-| 文件 | 何时加载 |
+| 文件 | 何时读 |
 |:-----|:---------|
-| [references/cover-styles.md](references/cover-styles.md) | 题材→视觉风格映射、平台风格详情、提示词模板 |
+| [references/cover-styles.md](references/cover-styles.md) | Step 1 定平台风格、Step 2 定题材、Step 3 查字体和画面时 |
+| [references/api-fallback.md](references/api-fallback.md) | Step 4 走 API 回退时 |