用 Story CLI 对 Markdown…

当需要对手写 Markdown 小说项目做结构校验、注册表重建、字数统计、链接/连续性/文风检查、进度报告、导入导出或构建成品时，用 Story CLI 执行机械性维护。

适用场景

解决思路

1. 优先按顺序使用可用的 CLI 入口：`story <command>`（已安装 bin）、`bun run story -- <command>`（在本仓库中）、`node scripts/story.js <command>`（相对本技能目录解析的兜底脚本）；三者都不可用时，按 `story-init` 的约定手动完成维护。
2. 就地运行已安装或内置的 CLI，不要把 `scripts/story.js` 复制进用户的故事项目，也不要创建项目本地的构建脚本、生成脚本或批量写入脚本来生成故事内容；故事项目应保持 markdown 优先，外加显式请求的导出（如 `manuscript.md`）。
3. 在故事项目根目录运行命令，或显式传入故事路径。
4. 初始化之后以及任何多文件编辑结束时运行 `story validate .`。
5. 新增、删除或重命名任何实体文件后运行 `story reindex .`，它会重建 character、location、system、faction、artifact、arc、chapter、scene、question、promise、clue、glossary 注册表；`story add` 会自行重建索引，手写文件不会。
6. 写完或修改章节后运行 `story wordcount . --write`。
7. 修改人物关系、重要地点、arc 参与者或章节引用后运行 `story links .`。
8. 起草或修改章节后、以及用户询问矛盾、已死角色出场、未回收的铺垫或过期状态时运行 `story continuity .`：它确定性地检查 `died-in` 顺序、promise/question 章节顺序、Chekhov 缺口、POV/演员一致性以及 `continuity/state.md` 引用；对线索台账（`continuity/clues/`）复用 promise 排序机制（payoff 早于 plant 是错误，已完成故事仍有 planned/planted 线索是错误）；Chekhov 警告（线索或 promise 已埋设三个或更多章节）要求 `status: planted`，`story add clue --planted` 只记录章节并保留 `status: planned`，所以线索真正出现在页面上时要设为 `status: planted`；已记录 payoff 章节但仍在最新章节之后时会抑制“尚无 payoff”警告；它还检查道具保管——`destroyed` 或 `lost` 状态的 artifact 不得在其销毁章节之后被引用（记录在 object-state 的 `since: chapter-NN`，后续场景在 `state-changes` 或 `mentions` 中引用它们是错误）——以及当场景或章节带有 `date: YYYY-MM-DD` / `time: HH:MM` frontmatter 时检查时钟/时间合理性（time 可为 `dawn`、`morning`、`midday`、`afternoon`、`evening`、`night`；场景 `travel-hours: N` 断言最短旅行时间），没有日期就不产生时间发现；有意例外写入 `continuity/exemptions.md`（frontmatter `type: exemption-log`，条目含 `pattern` + `reason`），被豁免的发现报告为 dismissed 而非错误。
9. 修订之后、或用户询问自某草稿以来有何变化时运行 `story compare`：`--ref` 用 `git show` 读取 git 分支、标签或提交处的章节（绝不写入仓库），`--against` 读取项目的另一份副本；它报告每章字数变化、新增和删除的章节以及未变段落占比；快照方法见 `revision-continuity` 技能的 Draft Snapshots。
10. 用户询问书进展到哪、能否赶上截止日期、或一次写作会话之后运行 `story progress`：它报告相对 `story.md` 中 `target-words` 的字数、距 `deadline` 剩余天数和每日所需字数、章节 `target-words` 以及来自 `progress.md` 的节奏；`--log` 在其中记录今日总数（`--date YYYY-MM-DD` 可补记），仅在用户保留日志或明确要求时记录。
11. 用户询问何时发生何事、闪回如何与主线对应、谁的 POV 占主导、或某角色在哪里退场时运行 `story timeline`：它按 `date` 和 `time` 排列有日期的场景（以及没有场景记录的章节），标记在更晚事件之后叙述的条目，按阅读顺序列出无日期场景，统计每个 POV 的章节数和字数，并报告每个角色的章节出现、最长缺席以及是否缺席最后几章；它是只读的，时钟错误由 `continuity` 负责。
12. 用户要求文风检查或分享草稿前运行 `story prose`：逐章统计句子长度及分布、每 1000 叙述词中的 filter words 和 -ly 副词、普通对话标签与 said-bookism、重复词、watch words 以及 `style-sheet.md` 中避免的拼写（`dialect`、`preferred`、`watch-words`、`allow-words`）；全书范围列出重复的 4 词短语和相似的角色名；发现是建议性警告且命令退出码为 0；如何应对见 `voice-style` 技能。
13. 当 `story.md` 有指向其他书的 `follows` 或 `precedes` 链接时运行 `story series`：它按时间顺序排列关联的续集和前传，并检查共享正典（前作中已死亡的角色、演员表、跨书重新得知的事实、名称漂移、被毁 artifact）；用 `init --follows <path>` 或 `init --precedes <path>` 开始关联书，跨书携带正典见 `series-continuity` 技能。
14. 用户已有手稿或章节草稿并想据此构建 Story Skills 项目时运行 `story import draft.md --title "Title"`，随后根据打印出的实体候选创建角色和地点文件；目录来源按自然文件名顺序导入（`chapter-2` 在 `chapter-10` 之前）；`import --force` 到已有目录会在写入导入章节前删除 `chapters/` 中每个 `chapter-NN.md`，所以在对已有草稿章节的项目强制导入前先与用户确认。
15. 用户要求项目状态、清单、进度或快速健康摘要时运行 `story report .`（可加 `--actionable`）。
16. 起草会话前运行 `story next .` 以确定下一个确定性动作。
17. 用户询问什么过期、损坏或不一致时运行 `story doctor .`。
18. 项目 schema 版本较旧或缺少 v2 路径时运行 `story migrate .`。
19. 当请求的变更适合时，用 `story add`、`story rename`、`story remove` 做确定性实体文件操作。
20. 用户想要献词、题词、版权页、致谢、作者注、作者简介或 also-by 页时用 `story add matter`：页面位于 `matter/`（由 reindex 索引到 `matter/_index.md`），带 `title`、`placement`（`front` 或 `back`）、`order` 和 `heading`（献词或题词设 `heading: false`）；直接在文件中写页面文本，未写的页面会被构建排除且 `validate` 会警告；绝不编造致谢、传记事实或版权细节，要向用户询问。
21. 故事依赖现实世界事实时用 `story add research`：笔记位于 `research/`，带 `status`（`open`、`verified`、`disputed`）、整条引用的 `sources` 和 `used-in` 章节 id；当最终章节依赖 open 或 disputed 研究时 `validate` 会警告；见 `research` 技能。
22. 仅在用户要求生成指定路径的合并手稿时运行 `story export . --out manuscript.md`，它包含前置和后置页。
23. 用户要求构建成品书时运行 `story build`：支持在 `dist/` 中输出 markdown、EPUB 和 DOCX，含前置和后置页；EPUB 需在 `story.md` 中设置 `cover: path/to/cover.jpg`（项目内）和 `author` 以嵌入封面图和创作者。
24. 用户想要 Shunn 手稿格式 markdown 时运行 `story build . --format shunn`：标题页、联系块、字数、章节分隔和双倍行距正文；`story build . --format docx --shunn` 对 DOCX 输出应用同样的 Shunn 格式。
25. 用户询问某角色在给定章节知道什么时运行 `story knowledge <character-id> --at <chapter-id>`：它列出 `learned-in` 章节在该章节或之前的 knowledge-state 条目，以及没有 `learned-in` 的条目作为既有知识。
26. 用户埋设新线索时运行 `story add clue "Name" --planted chapter-02 --payoff chapter-05`：它在 `continuity/clues/` 创建带 `status: planned` 的线索台账实体；payoff 未知时省略 `--payoff`，线索出现在页面上时设 `status: planted`。
27. 用户想要机械式梗概时运行 `story synopsis [--pages 1|3] [--out file]`：先取 `story.md` 的 `## Synopsis` 部分第一句，然后每个 arc 的 Setup、Rising Action、Climax 和 Resolution；一页为 500 词，三页为 1500 词；输出是脚手架，`submission` 技能会把它改写成面向经纪人的梗概。
28. 把 CLI 错误视为可执行的维护发现。
29. 当请求的任务隐含需要修复时，修复损坏的引用、缺失的必需文件、过期注册表或不正确的字数。
30. 不要仅为满足机械检查而覆盖创作性散文或故事内容。
31. 如果验证警告反映的是用户有意为之的数据，报告它而不是静默更改。
32. 如果 `story reindex` 因损坏的 `plot/_index.md` 失败，不要为绕过它而手改故事内容：从 git 恢复该索引 frontmatter，或删除 `plot/_index.md` 让 reindex 重建，然后重跑。
33. `story import --force` 会删除已有章节文件，执行前先与用户确认。
34. `story export` 仅在用户明确要求合并手稿时使用。
35. `story progress --log` 仅在用户保留日志或明确要求时记录。
36. `story add matter` 不得编造致谢、传记事实或版权细节。

适用边界 · 注意事项

• 不要用 CLI 做创作性故事决策（情节、人物、文风取舍），这些仍由创作类技能负责。
• 不要把 `scripts/story.js` 复制进用户项目，也不要创建项目本地的构建/生成/批量写入脚本。
• 不要仅为通过机械检查而覆盖创作性散文或故事内容。