Skip to content

zenstory-ai/oh-story-claudecode / skills/story-setup

story-setup

Flagged

网文写作工具集基础设施部署与检查。为 Claude Code / OpenCode / Codex / Google Antigravity / ZCode / OpenClaw / Reasonix 提供内置适配;Web AI / 通用 Agent 可走 skills + AGENTS.md 文件模式。触发方式:/story-setup、$story-setup、「准备写书」「帮我搭一下环境」「配置写作项目」「检查写作环境」。

FileKindSize
SKILL.mdskill md16.7 KB
UPGRADING.mdmarkdown17.4 KB
references/agent-references/agent-quality.mdmarkdown3.7 KB
references/agent-references/agent-reference-profiles.mdmarkdown4.3 KB
references/agent-references/banned-words.mdmarkdown10.9 KB
references/agent-references/benchmark-style-load.mdmarkdown10.1 KB
references/agent-references/character-basics.mdmarkdown12.3 KB
references/agent-references/character-relations.mdmarkdown10.2 KB
references/agent-references/cross-book-recall.mdmarkdown3.9 KB
references/agent-references/deslop-gates.mdmarkdown2.3 KB
references/agent-references/dialogue-mastery.mdmarkdown11.0 KB
references/agent-references/expression.mdmarkdown9.6 KB
references/agent-references/female-audience-writing.mdmarkdown7.5 KB
references/agent-references/format-and-structure.mdmarkdown8.0 KB
references/agent-references/genre-prose-cards.mdmarkdown7.0 KB
references/agent-references/genre-prose-cards/东方仙侠.mdmarkdown2.3 KB
references/agent-references/genre-prose-cards/传统玄幻.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/历史古代.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/历史脑洞.mdmarkdown2.0 KB
references/agent-references/genre-prose-cards/双男主.mdmarkdown2.3 KB
references/agent-references/genre-prose-cards/古言脑洞.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/古风世情.mdmarkdown2.3 KB
references/agent-references/genre-prose-cards/女频悬疑.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/女频种田.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/宫斗宅斗.mdmarkdown1.6 KB
references/agent-references/genre-prose-cards/年代.mdmarkdown2.1 KB
references/agent-references/genre-prose-cards/快穿.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/悬疑灵异.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/悬疑脑洞.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/战神赘婿.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/抗战谍战.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/星光璀璨.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/民国言情.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/流派兜底.mdmarkdown8.4 KB
references/agent-references/genre-prose-cards/游戏体育.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/玄幻脑洞.mdmarkdown2.0 KB
references/agent-references/genre-prose-cards/玄幻言情.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/现言脑洞.mdmarkdown1.8 KB
references/agent-references/genre-prose-cards/科幻末世.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/职场婚恋.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/西方奇幻.mdmarkdown1.9 KB
references/agent-references/genre-prose-cards/豪门总裁.mdmarkdown2.3 KB
references/agent-references/genre-prose-cards/都市修真.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/都市日常.mdmarkdown2.8 KB
references/agent-references/genre-prose-cards/都市种田.mdmarkdown1.7 KB
references/agent-references/genre-prose-cards/都市脑洞.mdmarkdown2.4 KB
references/agent-references/genre-prose-cards/都市高武.mdmarkdown2.0 KB
references/agent-references/genre-prose-cards/青春甜宠.mdmarkdown1.8 KB
references/agent-references/genre-readers.mdmarkdown6.9 KB
references/agent-references/long-chapter-hooks.mdmarkdown6.5 KB
references/agent-references/long-emotional-methods.mdmarkdown7.9 KB
references/agent-references/long-genre-catalog.mdmarkdown11.9 KB
references/agent-references/long-genre-mechanics.mdmarkdown8.3 KB
references/agent-references/long-quality.mdmarkdown3.2 KB
references/agent-references/long-reversal.mdmarkdown12.3 KB
references/agent-references/long-suspense.mdmarkdown9.2 KB
references/agent-references/narrative-focus.mdmarkdown6.7 KB
references/agent-references/opening-design.mdmarkdown4.5 KB
references/agent-references/outline-methods.mdmarkdown12.5 KB
references/agent-references/plot-core-methods.mdmarkdown5.3 KB
references/agent-references/short-chapter-hooks.mdmarkdown8.0 KB
references/agent-references/short-emotional-methods.mdmarkdown4.6 KB
references/agent-references/short-genre-formulas.mdmarkdown18.8 KB
references/agent-references/short-quality.mdmarkdown2.8 KB
references/agent-references/short-reversal.mdmarkdown12.7 KB
references/agent-references/story-logic.mdmarkdown5.9 KB
references/agent-references/style-combat-face.mdmarkdown9.1 KB
references/agent-references/style-resolution.mdmarkdown3.0 KB
references/agent-references/writing-craft.mdmarkdown23.6 KB
references/antigravity/hooks/hooks.jsonconfig1.0 KB
references/antigravity/hooks/story_antigravity_hook.jsscript8.4 KB
references/antigravity/hooks/story_hook_core.jsscript67.0 KB
references/antigravity/rules/oh-story.mdmarkdown3.7 KB
references/codex/AGENTS.md.tmplother3.8 KB
references/codex/agents/chapter-extractor.tomlconfig14.0 KB
references/codex/agents/character-designer.tomlconfig5.1 KB
references/codex/agents/consistency-checker.tomlconfig12.0 KB
references/codex/agents/narrative-writer.tomlconfig15.7 KB
references/codex/agents/story-architect.tomlconfig9.0 KB
references/codex/agents/story-explorer.tomlconfig11.7 KB
references/codex/agents/story-researcher.tomlconfig10.6 KB
references/codex/hooks/hooks.jsonconfig6.8 KB
references/codex/hooks/run-story-hook.cmdscript717 B
references/codex/hooks/run-story-hook.shexecutablescript805 B
references/codex/hooks/story_codex_hook.jsexecutablescript10.4 KB
references/codex/hooks/story_hook_core.jsscript67.0 KB
references/deploy-antigravity.mdmarkdown8.9 KB
references/deploy-claude-code.mdmarkdown7.6 KB
references/deploy-codex.mdmarkdown6.1 KB
references/deploy-generic.mdmarkdown2.5 KB
references/deploy-openclaw.mdmarkdown3.0 KB
references/deploy-opencode.mdmarkdown14.7 KB
references/deploy-reasonix.mdmarkdown3.5 KB
references/deploy-zcode.mdmarkdown7.5 KB
references/diagnostics.mdmarkdown4.3 KB
references/generic/AGENTS.md.tmplother4.4 KB
references/openclaw/AGENTS.md.tmplother5.0 KB
references/opencode/AGENTS.md.tmplother3.2 KB
references/opencode/agents/chapter-extractor.mdmarkdown13.8 KB
references/opencode/agents/character-designer.mdmarkdown4.7 KB
references/opencode/agents/consistency-checker.mdmarkdown11.5 KB
references/opencode/agents/narrative-writer.mdmarkdown15.3 KB
references/opencode/agents/story-architect.mdmarkdown8.5 KB
references/opencode/agents/story-explorer.mdmarkdown11.2 KB
references/opencode/agents/story-researcher.mdmarkdown10.1 KB
references/opencode/commands/browser-cdp.mdmarkdown284 B
references/opencode/commands/story-cover.mdmarkdown189 B
references/opencode/commands/story-deslop.mdmarkdown222 B
references/opencode/commands/story-import.mdmarkdown235 B
references/opencode/commands/story-long-analyze.mdmarkdown214 B
references/opencode/commands/story-long-scan.mdmarkdown232 B
references/opencode/commands/story-long-write.mdmarkdown200 B
references/opencode/commands/story-publish.mdmarkdown224 B
references/opencode/commands/story-review.mdmarkdown212 B
references/opencode/commands/story-setup.mdmarkdown322 B
references/opencode/commands/story-short-analyze.mdmarkdown209 B
references/opencode/commands/story-short-scan.mdmarkdown215 B
references/opencode/commands/story-short-write.mdmarkdown192 B
references/opencode/commands/story.mdmarkdown243 B
references/opencode/plugin.tsscript12.6 KB
references/opencode/pre-commit.shexecutablescript525 B
references/opencode/story_hook_core.jsscript67.0 KB
references/reasonix/AGENTS.md.tmplother5.3 KB
references/templates/.gitkeepother0 B
references/templates/CLAUDE.md.tmplother3.2 KB
references/templates/agents/chapter-extractor.mdmarkdown13.9 KB
references/templates/agents/character-designer.mdmarkdown4.5 KB
references/templates/agents/consistency-checker.mdmarkdown11.3 KB
references/templates/agents/narrative-writer.mdmarkdown15.2 KB
references/templates/agents/story-architect.mdmarkdown8.4 KB
references/templates/agents/story-explorer.mdmarkdown10.9 KB
references/templates/agents/story-researcher.mdmarkdown10.0 KB
references/templates/hooks/run-story-hook.shexecutablescript1.2 KB
references/templates/hooks/story_hook_cli.jsexecutablescript19.3 KB
references/templates/hooks/story_hook_core.jsscript67.0 KB
references/templates/rules/story-consistency.mdmarkdown2.5 KB
references/templates/rules/story-format.mdmarkdown3.4 KB
references/templates/rules/story-narrative.mdmarkdown1.5 KB
references/templates/rules/story-outline.mdmarkdown3.5 KB
references/templates/settings-hooks.jsonconfig2.1 KB
references/zcode/AGENTS.md.tmplother4.3 KB
references/zcode/agents/chapter-extractor.mdmarkdown13.5 KB
references/zcode/agents/character-designer.mdmarkdown4.4 KB
references/zcode/agents/consistency-checker.mdmarkdown11.3 KB
references/zcode/agents/narrative-writer.mdmarkdown15.0 KB
references/zcode/agents/story-architect.mdmarkdown8.3 KB
references/zcode/agents/story-explorer.mdmarkdown11.0 KB
references/zcode/agents/story-researcher.mdmarkdown9.9 KB
references/zcode/commands/browser-cdp.mdmarkdown221 B
references/zcode/commands/story-cover.mdmarkdown204 B
references/zcode/commands/story-deslop.mdmarkdown234 B
references/zcode/commands/story-import.mdmarkdown200 B
references/zcode/commands/story-long-analyze.mdmarkdown218 B
references/zcode/commands/story-long-scan.mdmarkdown206 B
references/zcode/commands/story-long-write.mdmarkdown202 B
references/zcode/commands/story-publish.mdmarkdown247 B
references/zcode/commands/story-review.mdmarkdown217 B
references/zcode/commands/story-setup.mdmarkdown363 B
references/zcode/commands/story-short-analyze.mdmarkdown214 B
references/zcode/commands/story-short-scan.mdmarkdown217 B
references/zcode/commands/story-short-write.mdmarkdown204 B
references/zcode/commands/story.mdmarkdown221 B
references/zcode/config.json.patchother1.7 KB
references/zcode/hooks/hooks.jsonconfig1.6 KB
references/zcode/hooks/story_hook_core.jsscript67.0 KB
references/zcode/hooks/story_zcode_hook.jsexecutablescript6.9 KB
scripts/copy-path-safety.jsexecutablescript8.9 KB
scripts/deploy-antigravity-skills.jsexecutablescript9.3 KB
scripts/generate-antigravity-agents.mjsexecutablescript12.4 KB
scripts/merge-hooks.jsexecutablescript9.5 KB
scripts/merge-project-instructions.jsexecutablescript12.8 KB

UPGRADING.md

View on GitHub
# 升级指南

## 当前版本

助手版本 45(待发布版本 / Unreleased)。已有项目更新技能包后,在项目根重跑 `/story-setup`(Codex 用 `$story-setup`,Antigravity 用 `/skills` 或直接点名),再新开会话。

- `setup_skill_version: 1.3.12`
- `agents_version: 45`

`.story-deployed` 字段不全,或 `agents_version` 不是整数、低于 45,都算待更新,重跑 story-setup 即可。项目里的 `agents_version` 大于 45,说明本机技能包比项目旧:先更新 oh-story-claudecode,不要用旧包覆盖。各版本改了什么见仓库根目录 `CHANGELOG.md`。

## 升级步骤

1. 更新技能包:命令行装的重跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`,插件市场或 Plugin Management 装的在面板里更新。
2. 在写作项目根重跑 `/story-setup`(Codex 用 `$story-setup`)。
3. 新开会话,让新的助手和 hook 生效;Codex 提示要信任 hook 时,在 `/hooks` 里信任一下。
4. 正在写的长篇:确认每本书有 `追踪/_tracking-state.json`。没有就按下方「追踪模型迁移」重建,否则写下一章会被拦。
5. 拆文成果或细纲不满足当前格式时,按检查提示定点补齐,不因单项缺口整本重拆。

## 待发布版本(Unreleased,助手版本 45,更新后必须重跑 story-setup)

- 五个支持 Hook 的宿主(Claude Code、Codex、OpenCode、Antigravity、ZCode)全部统一到单一 Node.js 18+ 共享核 `story_hook_core.js`:Claude Code 的 `.claude/hooks/` 收敛为 `run-story-hook.sh` + `story_hook_cli.js` + `story_hook_core.js`(重跑 story-setup 会自动清理旧版独立 `.sh` 脚本并刷新 `.claude/settings.local.json`),Codex 改用 `story_codex_hook.js` + `story_hook_core.js`,OpenCode `pre-commit` 改为调用同一共享核。
- 需要本机 PATH 中有 Node.js 18+;缺 Node 时会在会话起点发出提示。书稿、设定、追踪不用迁移。

## v0.10.5 的改动(助手版本 44)

- 写手、排纲、拆文、审稿助手与各端写后钩子按真人网文校准了万字短篇句式阻断门槛、退化与截断检查、弯引号默认、审稿细则和 0.10 细纲字段;重跑 story-setup 后新开会话才生效。
- 书稿、设定、追踪不用迁移。

## v0.10.4 的改动(助手版本 43)

- 写手、排纲、审稿助手与参考资料按真人网文校准了情绪直写、利害算账、标点整理和去味阻断门槛,各端写后钩子同步按单章次数分级,重部署时还会清掉受管目录里已退役的旧文件;重跑 story-setup 后新开会话才生效。
- 书稿、设定、追踪不用迁移。

## v0.10.3 的改动(助手版本 42)

- 7 个专业助手与它们读的参考资料去掉了重复段落和培训腔,保留全部输出模板、速查表与正反例;重跑 story-setup 后新开会话才生效。
- 书稿、设定、追踪不用迁移。

## v0.10.2 的改动(助手版本 41)

- 写手、排纲、拆文、去味助手与它们读的参考资料做了一轮精修,Antigravity 2.0、ZCode 3.7+、OpenCode 2.x 与 Reasonix 2.57 的项目配置和插件也一起更新;重跑 story-setup 后新开会话才生效。
- 书稿、设定、追踪不用迁移。

## v0.10.1 的改动(助手版本 40)

- 排纲助手多了一份跨书召回的资料。登记了 2 本及以上对标书的项目,重跑 story-setup 后新开会话,出卷纲、细纲和定设定才不会停下。
- 书稿、设定、追踪不用迁移。

## v0.10.0 的改动(助手版本 39)

- 长篇写作的写手、排纲助手、项目规则都改了,重跑 story-setup 后新开会话才生效。
- 书稿、设定、追踪不用迁移。老书的卷纲、细纲照样能读能写,不必转换(如需当年一次性格式转换脚本 `convert_outline_format.py`,可从仓库 `v0.10.5` tag 取用)。
- 作者记忆只用你确认过的条目。之前记下但没确认的写作习惯不再生效,想保留的再说一次。
- 正文里引号内的省略号不再被替换;长篇、短篇一起生效。

## v0.9.2 升级说明(助手版本 38)

- 新增发布资料技能 `story-publish`。重跑 story-setup 后,项目里才会有这个技能(OpenClaw、Reasonix、通用模式复制到项目 `skills/`)、项目指令里的「发布资料」入口,以及 OpenCode、ZCode 的 `/story-publish` 命令。
- 书稿、设定、追踪和作者记忆不用迁移。

## v0.9.1 升级说明(助手版本 37)

- 更新技能包后重跑 story-setup,并新开会话,让新版助手与 hook 生效。
- ZCode 用户须先更新并启用 `oh-story` 插件,再从**更新后的插件副本**运行 story-setup,覆盖项目 `.zcode/skills` 快照;不要用项目里的旧 story-setup 重部署。独立安装的 Skills 不会注册插件角色。
- ZCode 若仍命中项目旧快照,先把受管目录 `.zcode/skills/story-setup` 移出 `.zcode/skills` 留作备份,再从新版插件运行 story-setup;部署完成后该目录由新版重新生成。不必删除其他项目 Skills。
- Windows 用户重跑后会刷新项目 hook,避免继续使用旧版入口。

## v0.9.0 升级说明(助手版本 36)

- 写手、架构师、角色设计、一致性检查、查资料、资料研究这些助手的模板都改了。参考资料包里的排纲、开篇、人物、题材和情绪方法按使用环节重新整理,删掉了重复和过时的几份;写手读的技法与去 AI 味方法对齐。不重跑的话,项目里的旧助手会去找已经删掉的资料。
- 项目指令(`CLAUDE.md`、`AGENTS.md`)改成每个编程工具一个管理块,从 `<!-- oh-story:{工具} 开始` 到 `<!-- oh-story:{工具} 结束 -->`。第一次重跑会把旧版 oh-story 写进去的段落换成管理块,你自己写的段落留在块外;以后重跑只替换块里的内容。几个工具共用 `AGENTS.md` 时各占一块,互不覆盖。
- Claude Code 的 `.claude/rules/` 去掉了和写作流程打架的写死条目(章首、章尾钩子必须从固定类型里选、每章必须有情绪变化、固定段数和字数的警戒线),卷纲、细纲字段改以写作流程的模板为准,旧细纲缺字段照旧不拦。
- 一致性检查和查资料助手也能处理短篇项目(`设定.md`、`小节大纲.md`、`正文.md`)。资料研究助手发现浏览器调试端口没开时,把情况交回主会话,由主会话问你要不要启动浏览器。
- 书稿、设定、大纲、追踪和作者记忆的数据格式不变,不用迁移。
- 之前导入的长篇,卷纲里的剧情单元是一张表,写正文时无法按单元读取这些旧单元。续写新章不受影响:写第 N 章会先按单元卡写法补上新单元。要重写导入时的旧章,先让 `/story-long-write` 把那一卷的旧单元改写成单元卡。

## 从 v0.8.5 及更早升上来

重跑一次 story-setup 就会装上当前版本,中间版本不用逐个补。下面是写书时会碰到的变化:

- 长篇写后检查需要 Node.js 18+:缺 Node 时这一章不能提交,装好后重跑检查。长篇拆文仅可选的人物关系图 PNG 渲染(`render_relation_chart.py`)需要 Python 3。
- 改已经提交过的章,写作流程会先生成这一章的修订草稿再提交,不直接改追踪文件。
- 细纲可以加一行「字数范围:2000-2600」,填入你给的范围;没写就按默认上下浮动。老细纲、老卷纲照常可用,排纲时才按新格式补。
- 写正文前细纲不能是空壳(去掉 `#` 号和空白不到 30 字会被拦);标了 `<!-- 去味:跳过 -->` 的章不会因为这行标记被判有问题。
- 扫榜每次写进 `扫榜/{日期}/` 新目录,旧目录不用动。
- 换了编程工具后重跑 story-setup,会问你要不要把当前工具一起装上。
- 项目里旧的 `.claude/agent-memory/` 不再使用,可以删掉。

## OpenCode 只支持 2.x(v0.7.11)

OpenCode 2.0 起发布在 npm 包 `@opencode/cli`(`opencode-ai` 停在 1.x)。本适配只支持 2.x:1.x 的插件 loader 读不了新版 `story-hooks.ts`,在 1.x 上会没有写正文守卫与写后兜底;1.x 也不认 agents 的 `permissions:` 规则,只读 agent 会失去权限限制。story-setup 在版本是 1.x 或无法确定时停止部署。

1. 升级 OpenCode:先卸载旧包 `npm rm -g opencode-ai`,再 `npm i -g @opencode/cli`(或 `curl -fsSL https://opencode.ai/v2/install | bash`),确认 `opencode --version` 为 2.x。两个包都提供 `opencode` 命令,不先卸载旧包时 PATH 上可能仍是 1.x。
2. 更新技能包后,在写作项目根重跑 story-setup:替换 `.opencode/plugins/story-hooks.ts` 与 `.opencode/agents/`(改为 2.x 原生 `permissions:` 规则列表,已配的 `model:` 会保留),并从 `opencode.json` / `opencode.jsonc` 删除旧的 story-hooks 插件注册。

## 插件打包身份迁移(v0.7.9 同版本修复)

Claude Code / ZCode 市场改为单一 `oh-story` 插件,当时包含全部 13 个 Skills(v0.9.2 起为 14 个)。该迁移始于 v0.7.9 的同版本修复,仍使用旧插件身份的用户需手动迁移;`npx skills` 安装无需迁移。卸载前备份要保留的插件数据,以下操作仅针对旧插件记录,保留写作项目及 story-setup 部署文件。

### Claude Code

1. 先在受影响的写作项目目录中列出已安装插件,按记录中的 `id` 与 `scope` 核对实际旧身份;`project` / `local` 记录属于各自项目,多个项目须分别核对:

   ```bash
   claude plugin list --json
   ```

   只处理列表中确实存在、marketplace 为 `oh-story-skills` 的以下旧 ID:

   ```text
   browser-cdp@oh-story-skills
   story@oh-story-skills
   story-cover@oh-story-skills
   story-deslop@oh-story-skills
   story-import@oh-story-skills
   story-long-analyze@oh-story-skills
   story-long-scan@oh-story-skills
   story-long-write@oh-story-skills
   story-review@oh-story-skills
   story-setup@oh-story-skills
   story-short-analyze@oh-story-skills
   story-short-scan@oh-story-skills
   story-short-write@oh-story-skills
   ```

2. **刷新 catalog 前**,逐个卸载实际存在的旧 ID,并使用列表中原有的 `user`、`project` 或 `local` scope。以下以 user-scope 的 `story` 插件为例:

   ```bash
   claude plugin uninstall story@oh-story-skills --scope user --keep-data
   ```

   `--keep-data` 保留该旧插件身份的数据,但不会把它迁移到新的 `oh-story` 身份。同一旧 ID 若出现在多个 scope,每个 scope 分别执行。

3. 所有实际旧身份卸载完后,刷新已有 catalog;若本机尚未添加该 catalog,则添加仓库:

   ```bash
   claude plugin marketplace update oh-story-skills
   # 仅在 catalog 尚不存在时:
   claude plugin marketplace add https://github.com/zenstory-ai/oh-story-claudecode
   ```

4. 在原 scope 安装统一 bundle;多个 scope 分别安装:

   ```bash
   claude plugin install oh-story@oh-story-skills --scope user
   ```

5. 新开 Claude Code 会话,使用 `/oh-story:story-setup` 或 `/oh-story:story dashboard`。命令与 manifest 格式见 [Claude Code 插件参考](https://code.claude.com/docs/en/plugins-reference)。

### ZCode

在 Plugin Management 中卸载受影响的旧条目,刷新市场;必要时重新添加本仓库,再安装一个 `oh-story`。沿用界面中的市场名(`oh-story-skills` 或 `oh-story-zcode`),避免重复安装。若无法卸载,保留数据备份,附 ZCode 版本与界面现象联系官方支持,不要清空全部缓存或手改缓存 JSON。操作说明见 [ZCode 插件文档](https://zcode.z.ai/en/docs/plugin)。

## 项目里多出的嵌套目录

旧版部署可能在项目里留下嵌套目录:`agent-references/agent-references/`(可能多层)或 `skills/story-setup/skills/`,严重时会撑满磁盘。新版部署会拒绝这种复制并自动删掉残留。

OpenClaw、Reasonix 和通用模式把 skill 放在项目 `skills/` 里,重跑时执行的是项目里那份旧 skill,无法自动清理:先手动删掉上面两类目录,再用更新后的技能包覆盖项目 `skills/` 下的 14 个目录。

## 追踪模型迁移(v0.7.2 及更早的长篇项目必读)

长篇追踪以 `追踪/_tracking-state.json` 为准,由写作流程的提交工具统一写入;续写状态卡、逐章记录、角色快照、伏笔表和两份时间线都由工具整份生成,不手改。

判断与后果:

| 情况 | 表现 |
|------|------|
| `追踪/_tracking-state.json` 存在且 `check` 通过 | 正常,无需处理 |
| 缺 `_tracking-state.json` 但已有正文 | 日更停止;Claude Code、Codex、OpenCode、ZCode、Antigravity 上写正文会被 hook 直接拦下,其他工具由写作流程自己停下 |
| 存在但自动生成的追踪文件被手改 | `check` 报 `derived view differs from _tracking-state.json` |

迁移**不需要重跑全书拆解**:正文、`设定/`、`大纲/`、`拆文库/` 都不受影响,只重建 `追踪/`。执行 `/story-import` 的「旧追踪项目迁移」:数出最后完整章号 `N`,从旧追踪文件与最近几章正文整理出当前状态,构造 `last_chapter=N` 的初始化事务跑 `tracking_commit.js init`。旧追踪文件会原样移入 `追踪/_旧追踪存档/` 留底,不删除、也不再读取。

退役结构:`_tracking-meta.json`、`时间线/事件库.json` 及更早的追踪文件不再使用,`commit` 与 `check` 遇到会直接拒绝。

之后写作时,追踪只通过写作流程提交;生成文件被手改后,用该章的修订提交整份重建。

## 作者记忆两级存储迁移(v0.7.11 之前的项目)

作者记忆从「一个工作区一份」改成两级:工作区 `.story/作者记忆/` 只存全局、题材、流程条目(编号 `AP`),每本书目录下的 `.story/作者记忆/` 存这本书的条目(编号 `BP`),记忆随书归档、迁移。同时不再从反复修改或成稿推断偏好:`record` 拒绝 `repeated_correction` / `inferred_pattern` 来源,存量条目照常可读、可确认、可退役。

下方命令中的 `{所用写作 skill 根}` 指 `story-long-write` 或 `story-short-write` 的安装目录。

迁移时按以下三点处理:

1. 新的本书偏好必须传 `--book-root {书目录}` 才能写入;旧 skill 副本没带这个参数会报错,重跑 `/story-setup` 让脚本与文档同版。
2. 升级前写进工作区的本书条目**不再被 `query` 返回**(全局、题材、流程条目不受影响),直到搬进书目录;它们仍在工作区 `作者画像.md` 里可见。
3. 对每本书运行一次即可整批搬家,幂等、中途失败直接重跑:

   ```text
   node {所用写作 skill 根}/scripts/author_memory_commit.js migrate --workspace {工作区} --book-root {工作区}/长篇/{书名}
   ```

   断言、原话证据、确认次数、重要度原样保留;与全局条目的冲突候选在迁移后退回待确认。也可以对 agent 说「整理作者记忆」,迁移会列为默认提案项。

**单书布局**(`正文/`、`追踪/` 直接在工作区根):书级数据存储在 `{工作区}/.story/作者记忆/书级/`,迁移时 `--book-root` 就传工作区本身:

   ```text
   node {所用写作 skill 根}/scripts/author_memory_commit.js migrate --workspace {工作区} --book-root {工作区}
   ```

书名默认取存量本书条目里的书名;存量里有多本书的条目时用 `--book {书名}` 指定。用过 main 上预发布版本、查询时报 `project-level state must not carry state.book` 的工作区,带 `--book-root {工作区}` 运行任一命令即自动修复,不丢条目。

## 长篇拆文旧成果(v0.7.10 及更早拆的书)

- v0.7.10 及更早的拆文库如果原文以楔子/序章开头,续拆会先停下询问(旧版不认楔子,直接续跑会错一章)。只拆到黄金三章的库选「楔子单独成章重拆」代价最小;已有逐章摘要的库推荐「楔子并入第一章,按旧章号继续」。
- `拆文报告.md` 小节结构变了(去掉「质量评估」,「证据边界与待核事项」改为「还不确定的地方」),旧报告不会自动改写,重跑 Stage 5 才生效。
- 人物关系图改为 `人物关系图/人物关系图.md`(文字清单保留中文,支持 Mermaid 的查看器可显示关系图),有中文字体时另出 PNG;以前生成的拼音版 PNG 不会自动删除,可手动删掉。
- 拆文进度文件 `_progress.md` 只认 `schema_version: 2`;更早格式的进度文件不能续拆,按提示从头拆。

## 导入项目的自对标清理

旧版 `story-import` 可能把作者自己的导入书误建成 `对标/{当前书名}/`,甚至把本书设定登记成“主对标”。升级不会自动删除用户文件,按以下边界人工核对:

1. 保留 `拆文库/{导入书名}/`:它是导入时整理本书结构用的底稿,留着即可。
2. 以项目根 `设定/` 为本书正式设定。若 `对标/{当前书名}/` 的内容确认只是从本书 `设定/` 或 `拆文库/{导入书名}/` 复制而来,且没有人工补充,再删除这个误建目录。
3. 清理 `设定/题材定位.md` 中把当前书登记为主/副对标的字段;真实外部对标登记不动。
4. 若某个 `对标/{外部书名}/` 目录名看似外部作品,但内容实际来自当前书,删除这份错误视图,再从真正的 `拆文库/{对标书名}/` 重新同步;不要改名冒充修复。
5. 重新运行 `/story-setup`(Codex 用 `$story-setup`)并新开会话,让当前助手模板生效。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall