interactive-fiction

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Interactive Fiction

互动小说

Overview

概述

Plan, draft, and revise a branching book: a story project whose chapters are passages joined by

choices

in their frontmatter. The chapters and their choices are the source of truth.

story continuity

follows the paths of choices, and

story build --format twee

--format ink

turns the project into a playable Twine or ink story.

This skill owns books written to branch from the start. Turning an existing linear book into an interactive edition (a branch map drawn from its scenes, then a copied project) belongs to the

adaptation

skill; once that edition project exists, draft and revise its chapters here.

规划、起草并修订分支故事书：一种故事项目，其中各章节都是段落，并通过其 frontmatter 中的

choices

相互连接。章节及其

choices

是唯一的事实来源。

story continuity

沿 choices 的路径进行跟踪，

story build --format twee

或

--format ink

则将项目转换为可玩的 Twine 或 ink 故事。

本 skill 专门处理从创作之初就设计为分支结构的书。将现有线性书转换为互动版（先根据其场景绘制分支图，再复制生成项目）属于

adaptation

skill 的职责；该互动版项目建立后，可在此起草和修订其章节。

Prerequisites

前置条件

A story project with

story.md

in the root. For a new book, start it with the

story-init

skill first. Read

story.md

(

language

pov

tense

form

status

ifid

) and

chapters/_index.md

, then the

choices

of every chapter: together they are the graph. A small example is

examples/the-gull-rock-light

, a branch-and-bottleneck story with two endings.

需要准备一个根目录中包含

story.md

的故事项目。对于新书，应先使用

story-init

skill 创建。读取

story.md

（

language

、

pov

、

tense

、

form

、

status

、

ifid

）和

chapters/_index.md

，然后读取每个章节的

choices

；它们共同构成整个图。一个小型示例是

examples/the-gull-rock-light

，这是一个包含两个结局的分支—瓶颈型故事。

When to Use

使用场景

Planning a choice graph: structure, branch points, rejoins, endings
Writing or changing
```
choices
```
entries
Drafting a chapter on a branch, at a rejoin, or at an ending
Revising a branching book, and reading
```
state-differs-by-path
```
,
```
unreachable-chapter
```
, and the other branching findings
Building the book as Twine or ink
NOT for converting a linear book (use
```
adaptation
```
), drafting a linear chapter (use
```
chapter-writing
```
), or a linear continuity audit (use
```
revision-continuity
```
). Prose craft inside a passage still comes from
```
scene-craft
```
and
```
line-editing
```

规划选择图：结构、分支点、汇合点、结局
编写或修改
```
choices
```
条目
起草位于分支、汇合点或结局的章节
修订分支故事书，并读取
```
state-differs-by-path
```
、
```
unreachable-chapter
```
及其他分支检查结果
将故事构建为 Twine 或 ink
不适用于转换线性书（使用
```
adaptation
```
）、起草线性章节（使用
```
chapter-writing
```
）或执行线性连续性审计（使用
```
revision-continuity
```
）。passage 内部的行文创作仍应采用
```
scene-craft
```
和
```
line-editing
```

How The Graph Works

图的工作方式

Each chapter is one passage. Its

choices

are where the reader can go:

yaml

choices:
  - text: Search the rocks for Tobias
    to: chapter-02
  - text: Climb the tower to the lamp
    to: chapter-03

The lowest-numbered chapter is the start.
Once any chapter has
```
choices
```
, the links are exactly the choices: a chapter with none is an ending, and a chapter that leads on to one place needs a single choice (
```
text: Continue
```
). With no choices anywhere the book is linear again.
```
text
```
becomes the link text: no
```
[
```
,
```
]
```
,
```
|
```
,
```
->
```
,
```
<-
```
, or line break, and no final
```
<
```
. Quote it if it looks like a number.
```
to
```
is a chapter id. It may be the chapter itself (a loop) or, while planning, a
```
chapter-NN
```
with no file yet; the builds need every target written.

每个章节（

chapter

）都是一个段落（

passage

）。其

choices

表示读者可以前往的位置：

yaml

choices:
  - text: Search the rocks for Tobias
    to: chapter-02
  - text: Climb the tower to the lamp
    to: chapter-03

编号最小的章节是起点。
一旦任何章节包含
```
choices
```
，链接关系就完全由这些 choices 构成：没有 choices 的章节是结局；需要继续前往下一处的章节必须只有一个 choice（
```
text: Continue
```
）。如果整个故事中都没有任何 choices，它就会重新变成线性结构。
```
text
```
会成为链接文本：其中不得包含
```
[
```
、
```
]
```
、
```
|
```
、
```
->
```
、
```
<-
```
或换行，也不得以
```
<
```
结尾。如果它看起来像数字，请使用引号。
```
to
```
是 chapter id。它可以指向章节自身（形成循环），也可以在规划阶段指向尚无文件的
```
chapter-NN
```
；构建时所有目标都必须已经写好。

Workflow

工作流

1. Plan The Choice Graph

1. 规划选择图

Agree the shape with the user before drafting; see

references/choice-graph.md

for the structures, choice design, and numbering. Then:

Draw the graph: every passage, every choice, every rejoin, every ending. Count passages and endings against
```
target-words
```
and the
```
form
```
.
Number chapters so each choice leads to a higher number, except a loop back. The promise, question, and clue ledgers, the clock and route checks,
```
story pacing
```
, and the
```
story diagram
```
and
```
story series
```
lifelines still read chapter numbers, so this keeps them close to the paths.

Scaffold each passage as an outline chapter with its POV and cast, then add its

choices

by hand (

story add

does not write them):

shell

story add chapter 'The Landing' --number 1 --status outline --pov ada-fenn --character ada-fenn --hook decision --path .

Check the skeleton before writing prose.
```
story links .
```
warns
```
unreachable-chapter
```
for every chapter no path from the start reaches, and errors on a choice to a missing chapter, except a
```
chapter-NN
```
with no file yet, which it allows as scheduled. So a typo such as
```
chapter-09
```
for
```
chapter-08
```
passes: compare every
```
to
```
with the planned passage list by hand, and once every passage has a file, run
```
story build . --format twee
```
, which refuses any choice to a missing chapter.
Record the state choices set that the CLI does not track (flags, trust, items the reader can carry down one branch) in
```
notes/branch-map.md
```
, a working file the CLI ignores: a table of each flag, the chapter that sets it, and the chapters that read it.

起草前应先与用户确认图形结构。有关结构、choice 设计和编号方式，请参阅

references/choice-graph.md

。然后：

绘制整张图：每个 passage、每个 choice、每个汇合点和每个结局。结合
```
target-words
```
和
```
form
```
核对段落数与结局数。
为章节编号，使每个 choice 都通向编号更大的章节，只有循环会返回之前的章节。承诺、问题和线索台账、时钟与路线检查、
```
story pacing
```
，以及
```
story diagram
```
和
```
story series
```
的生命线仍会读取章节编号，因此这种方式可以让它们与路径保持紧密对应。

先将每个 passage 搭建成包含 POV 和角色阵容的大纲章节，再手动添加其

choices

（

story add

不会写入这些 choices）：

shell

story add chapter 'The Landing' --number 1 --status outline --pov ada-fenn --character ada-fenn --hook decision --path .

在编写正文前检查骨架。
```
story links .
```
会对每个无法从起点到达的 chapter 发出
```
unreachable-chapter
```
警告，并对指向缺失章节的 choice 报错；但尚无文件的
```
chapter-NN
```
会被视为已排期的目标，因此允许通过。因此，本应指向
```
chapter-08
```
却误写为
```
chapter-09
```
之类的错误会暂时通过检查：请手动将每个
```
to
```
与计划中的 passage 列表进行比对；待所有 passage 都有文件后，运行
```
story build . --format twee
```
，该命令会拒绝任何指向缺失章节的 choice。
在
```
notes/branch-map.md
```
中记录 CLI 不会跟踪、由 choices 设置的状态（flags、信任状态、读者可沿某个分支携带的物品）。这是一个 CLI 会忽略的工作文件：用表格记录每个 flag、设置它的章节以及读取它的章节。

2. Draft A Passage

2. 起草段落

Draft with the

chapter-writing

workflow (outline, approval, prose, post-write updates), with these differences:

Run
```
story context chapter-NN --path .
```
for every passage. In a branching book it holds only what was drafted and learned on a path to that chapter, so a sibling branch never leaks in.
On a branch: the passage may use everything on the paths that lead to it, and nothing from its sibling.
At a rejoin: the context lists the scenes of every branch that leads there. Read each incoming chapter and write only what is true on every path: who is where, who is hurt, what the reader has seen. Facts are marked known when any incoming path teaches them, so check each fact the rejoin uses against every branch. A detail that differs by path stays out of the rejoin prose, or is carried by a flag in the built Twine or ink file (see Build).
At a branch point: end on the decision (
```
hook: decision
```
) and make each choice meaningful, informed, and acknowledged in the passage it leads to.
At an ending: no
```
choices
```
,
```
hook: resolution
```
, and an ending that pays off the path that reached it. Name it as an ending in the prose if the book's style does (
```
THE END.
```
).

After saving the passage, record continuity as

chapter-writing

does, following

references/path-continuity.md

for the branching rules: deaths and revivals, one

knowledge-state

entry per branch for a fact learned on two branches, and the

continuity/state.md

snapshot.

使用

chapter-writing

工作流进行起草（大纲、审批、正文、写入后更新），但需遵循以下差异：

对每个 passage 运行
```
story context chapter-NN --path .
```
。在分支故事书中，它只包含沿通往该章节的路径已起草和已获知的内容，因此兄弟分支的信息不会泄漏进来。
**位于分支上时：**段落可以使用通往它的所有路径上的信息，但不得使用其兄弟分支的任何信息。
**位于汇合点时：**上下文会列出每条通往该处的分支上的场景。读取每个入站章节，并且只写入在所有路径上都成立的内容：谁在哪里、谁受了伤、读者见过什么。任一入站路径教会某项事实后，它就会被标记为 known（已知），因此必须将汇合点使用的每个事实与所有分支逐一核对。路径不同而存在差异的细节不应写入汇合点正文，或者可通过构建后的 Twine 或 ink 文件中的 flag 承载（见“构建”）。
**位于分支点时：**在决定处结束（
```
hook: decision
```
），并确保每个 choice 都有明确意义、能让读者获得充分依据，并在其通往的段落中得到回应。
**位于结局时：**不得设置
```
choices
```
，应使用
```
hook: resolution
```
，并让结局兑现抵达该处的路径铺垫。如果故事风格需要，应在正文中明确标示结局（
```
THE END.
```
）。

保存段落后，应按照

chapter-writing

的方式记录连续性信息，并遵循

references/path-continuity.md

中的分支规则：记录死亡与复活；对于在两个分支中各自学到的事实，每个分支各记录一条

knowledge-state

条目；并维护

continuity/state.md

快照。

3. Revise A Branching Book

3. 修订分支故事书

Use

revision-continuity

for the passes, plus these checks:

Reachability: fix every
```
unreachable-chapter
```
by adding a choice that leads there, from a passage the user agrees (see Hard Rules). Removing the chapter deletes its file and its drafted prose, so offer it only as an option, and put the whole removal to the user for one approval:
1. Take a snapshot (see Draft Snapshots in the
```
revision-continuity
```
  skill).
2. ```
remove chapter
```
  refuses while scene files point at the chapter, so dry-run each of its scenes:
```
story remove scene <scene-id> --path . --dry-run
```
  .
3. Dry-run the chapter:
```
story remove chapter <id> --path . --dry-run
```
  . While the chapter still has scenes, this prints only that refusal. It also refuses while a
```
died-in
```
  ,
```
since
```
  , or
```
learned-in
```
  field, or a progression's
```
from
```
  , names the chapter, so search the project for the chapter id and list those references too: each needs another chapter before the removal can run.
4. Show the user every file the dry runs would update and delete, and every reference that blocks the removal. Only with their explicit approval, repoint the blocking references, remove the scenes, then remove the chapter. It drops the choices that led to the chapter and warns which chapters became endings.
5. If the chapter removal is still refused after the scenes are gone, stop and ask the user: go on with the next fix, or restore the snapshot (
```
story snapshot --restore <name> --path . --dry-run
```
  first, as the
```
revision-continuity
```
  skill describes).
Endings: list the chapters with no
```
choices
```
. Each should be a deliberate ending. A chapter that lost its last choice in a revision is an accidental ending: give it a choice.
Loops: the CLI does not check that a loop has a way out. Trace every loop and confirm a choice leaves it.
Path continuity: run
```
story continuity .
```
and read the branching findings in
```
references/path-continuity.md
```
. Then do the hand checks there for what the checker reads by chapter number. Branching books in
```
../story-maintenance/references/continuity-checks.md
```
says which
```
continuity
```
,
```
knowledge
```
,
```
context
```
,
```
timeline
```
, and
```
grid
```
results follow the paths and which go by chapter number.
Renumbering:
```
story move chapter
```
,
```
story split
```
, and
```
story merge
```
rewrite every
```
to
```
that named an old id. Split and merge work here only on chapters with no
```
choices
```
, and merge only when no choice leads to the second chapter; restructure anything else by hand. A split gives its first half a
```
Continue
```
choice that leads to the rest, so offer the user other words for it. None of them edits prose, so reread the passages for chapter numbers in the text.
Rejoin prose: after changing a branch, reread every rejoin it leads to and confirm the prose still holds on that path.

使用

revision-continuity

完成各轮修订，同时进行以下检查：

**可达性：**通过从用户认可的 passage（见“硬性规则”）添加一个通向目标章节的 choice，修复每个
```
unreachable-chapter
```
。删除 chapter 会同时删除其文件和已起草的正文，因此只能将其作为一个备选方案提出，并将整个删除操作一次性提交给用户审批：
1. 创建快照（参见
```
revision-continuity
```
  skill 中的“草稿快照”）。
2. ```
remove chapter
```
  在场景文件仍指向该章节时会拒绝执行，因此应对每个相关场景运行
```
story remove scene <scene-id> --path . --dry-run
```
  。
3. 对章节运行
```
story remove chapter <id> --path . --dry-run
```
  。当章节仍有场景时，它只会输出这一拒绝信息。如果某个
```
died-in
```
  、
```
since
```
  或
```
learned-in
```
  字段，或者某个 progression 的
```
from
```
  指向该章节，它也会拒绝执行，因此应搜索项目中的 chapter id，并同时列出这些引用：每个引用都必须先改指向另一个 chapter，删除操作才能继续。
4. 向用户展示所有 dry run 将更新或删除的文件，以及所有阻止删除的引用。只有在用户明确批准后，才可重新指向这些阻塞引用、删除场景，最后删除章节。该操作会移除原本通向该章节的 choices，并警告哪些章节因此变成了结局。
5. 如果删除场景后章节仍被拒绝执行，请停止并询问用户：是继续处理下一个问题，还是恢复快照（先按照
```
revision-continuity
```
  skill 的说明运行
```
story snapshot --restore <name> --path . --dry-run
```
  ）。
**结局：**列出所有没有
```
choices
```
的章节。它们每一个都应是有意设计的结局。如果某个章节在修订中失去了最后一个 choice，它就是意外结局：应为它添加一个 choice。
**循环：**CLI 不会检查循环是否存在出口。追踪每个循环，并确认其中有一个 choice 能够离开循环。
**路径连续性：**运行
```
story continuity .
```
，并阅读
```
references/path-continuity.md
```
中的分支检查结果。随后按照该引用中的说明，执行针对检查器仍按章节编号读取内容的手工检查。
```
../story-maintenance/references/continuity-checks.md
```
中的“分支故事书”一节说明了哪些
```
continuity
```
、
```
knowledge
```
、
```
context
```
、
```
timeline
```
和
```
grid
```
结果按路径追踪，哪些仍按章节编号处理。
重新编号：
```
story move chapter
```
、
```
story split
```
和
```
story merge
```
会重写所有曾指向旧 id 的
```
to
```
。在这里，
```
split
```
和
```
merge
```
仅适用于没有
```
choices
```
的章节；
```
merge
```
还要求没有 choice 通向第二个章节，其他结构必须手动重组。拆分后的前半部分会获得一个通往后半部分的
```
Continue
```
choice，因此应为用户提供其他措辞。这些操作都不会编辑正文，因此应重新阅读各 passage，检查正文中出现的章节编号。
**汇合点正文：**更改某个分支后，应重新阅读它通向的每个汇合点，确认正文在该路径上仍然成立。

4. Build

4. 构建

shell

story build . --format twee
story build . --format ink

Both write to

dist/

and refuse to build while a choice is malformed or leads to a missing chapter. Without

ifid:

story.md

, they derive the IFID from the story id and warn with the line to add; add it before sharing the story, so a retitle keeps the same IFID.

The ink build escapes ink syntax in the prose, so flags and conditional text (

VAR

{ }

) never go in chapters. Once the graph is settled, build a working copy with

--out adaptations/interactive/{story-id}.ink

and write that logic into it by hand.

--out

never replaces an existing file, so a rebuild after changing

choices

means deleting the old copy and carrying the hand-written logic into the new one: ask the author before deleting a file that has hand-written logic in it. Ink and Twine syntax for that layer is in the

adaptation

skill's

references/interactive-fiction.md

shell

story build . --format twee
story build . --format ink

两种构建都会写入

dist/

，并在 choice 格式错误或指向缺失章节时拒绝构建。如果

story.md

中没有

ifid:

，它们会根据 story id 推导 IFID，并警告需要添加哪一行；应在分享故事前添加它，这样更改标题后仍能保留相同的 IFID。

ink 构建会转义正文中的 ink 语法，因此 flags 和条件文本（

VAR

、

{ }

）绝不能写进章节。整张图确定后，使用

--out adaptations/interactive/{story-id}.ink

构建一个工作副本，并手动将相关逻辑写入其中。

--out

绝不会覆盖现有文件，因此更改

choices

后重新构建时，需要删除旧副本并把手写逻辑迁移到新副本中；删除包含手写逻辑的文件前，必须先征得作者同意。该逻辑层的 Ink 和 Twine 语法见

adaptation

skill 的

references/interactive-fiction.md

。

Maintenance

维护

After adding, removing, renumbering, or rewriting chapters or their

choices

, run:

shell

story reindex .
story wordcount . --write
story check .

Repair every error. Treat

unreachable-chapter

and

state-differs-by-path

as findings to resolve or record.

story next .

suggests drafting the next chapter number, as for a linear book: plan from the graph instead.

story

is not installed, use the bundled fallback

node ../story-maintenance/scripts/story.js

with the same arguments. Use

node <checkout>/bin/story.js

instead only when the user names a Story Skills repository checkout or you are working in one. Write the script as an absolute path (resolve the fallback relative to this skill folder) and run it from the folder you would run

story

from, so

and other relative paths keep their meaning. Use Node, not Bun or a package script: Bun would load that folder's

bunfig.toml

(which can run code) and

.env

, and a package script runs from the checkout's root.

添加、删除、重新编号或重写章节及其

choices

后，运行：

shell

story reindex .
story wordcount . --write
story check .

修复每一个错误。将

unreachable-chapter

和

state-differs-by-path

视为需要解决或记录的问题。

story next .

会建议下一个要起草的章节编号，与线性书相同：此时应从图出发进行规划。

如果未安装

story

，可使用参数相同的内置回退脚本

node ../story-maintenance/scripts/story.js

。只有在用户指定了 Story Skills 仓库检出目录，或你正在该目录中工作时，才改用

node <checkout>/bin/story.js

。将脚本路径写成绝对路径（相对于此 skill 文件夹解析回退脚本路径），并从原本会运行

story

的文件夹执行它，以保持

和其他相对路径的含义。使用 Node，不要使用 Bun 或 package script：Bun 会加载该文件夹中的

bunfig.toml

（其中可以运行代码）和

.env

，而 package script 会从检出目录的根目录运行。

Hard Rules

硬性规则

Never invent a branch, ending, or choice the user has not agreed; offer options instead.
Never remove a chapter or scene without the user's explicit approval, given after a snapshot and a
```
--dry-run
```
that lists what it deletes.
Never write rejoin prose that is true on only one incoming path.
Never silence
```
state-differs-by-path
```
with an
```
object-state
```
entry the rejoin chapter's prose does not make true.
Never put ink logic in chapter prose; keep it in the built copy under
```
adaptations/interactive/
```
. Write Twine macros in chapters only once the author has picked a story format (Harlowe, SugarCube, Chapbook).

绝不擅自创建用户未同意的 branch、ending 或 choice；应改为提供选项。
未经用户明确批准，绝不删除任何 chapter 或 scene；批准必须发生在创建快照并运行列出待删除内容的
```
--dry-run
```
之后。
绝不在仅有一条入站路径成立的 rejoin 中编写正文。
绝不能使用 rejoin 章节正文中并未成立的事实，通过
```
object-state
```
条目消除
```
state-differs-by-path
```
问题。
绝不能将 ink 逻辑写入章节正文；应将其保留在
```
adaptations/interactive/
```
下的构建副本中。只有在作者选定故事格式（Harlowe、SugarCube、Chapbook）后，才可在章节中编写 Twine macros。

Reference Files

参考文件

references/choice-graph.md
- Branching structures, designing choices, numbering, rejoins, endings, and scope
references/path-continuity.md
- What
```
story continuity
```
follows by path and what it still reads by number, the branching findings and their fixes, and the hand checklist

references/choice-graph.md
——分支结构、choice 设计、编号、汇合点、结局与范围
references/path-continuity.md
——
```
story continuity
```
按路径跟踪和仍按编号读取的内容、分支检查结果及其修复方式，以及手工检查清单

Shared Conventions

共享约定

Every story skill follows the shared conventions in

../story-maintenance/references/conventions.md

, resolved relative to this skill folder. Read it before creating, renaming, or linking story files. If that file is missing because this skill was installed without

story-maintenance

, the essentials are: kebab-case ids and filenames, YAML frontmatter on every story-project file,

_index.md

registry tables that

story reindex

rebuilds (never edit them by hand), bidirectional links between entities,

characters

for who is on the page and

mentions

for who is only referred to,

status: deceased

plus

died-in: chapter-{NN}

for deaths, and no project-local generator or build scripts (run only the installed or bundled Story CLI).

每个 story skill 都遵循

../story-maintenance/references/conventions.md

中的共享约定，该路径相对于此 skill 文件夹解析。在创建、重命名或链接故事文件前，应先阅读该文件。如果此 skill 是在未同时安装

story-maintenance

的情况下安装的，导致该文件缺失，则应遵循以下核心要求：id 和文件名使用 kebab-case；每个故事项目文件都包含 YAML frontmatter；

_index.md

注册表由

story reindex

重建（绝不能手动编辑）；实体之间使用双向链接；使用

characters

表示实际在场的角色，使用

mentions

表示仅被提及的角色；角色死亡时使用

status: deceased

和

died-in: chapter-{NN}

；不得使用项目本地的生成器或构建脚本（只能运行已安装或内置的 Story CLI）。