cold-open

Cold Open

Cold Open 是一款免费的开源剧本创作应用。它支持读写 Fountain 和 Final Draft（.fdx）文件，并且绝不会丢失你的作品。每项操作都是一条命令，你可以通过桌面应用、命令行、stdio 上的 JSON 或 MCP 服务来驱动它。

状态： alpha 阶段，正在招募测试者。第 1 至第 5 阶段构建了编辑器、命令行、MCP 服务、.fdx 文件交换、修订跟踪、修订版本、剧本差异比较和报告；第 6a 阶段构建了编剧可安装的版本，第 6b 阶段完成了用户指南、反馈和崩溃报告。网站 https://theyungstump.github.io/cold-open/ 提供用户指南和如何加入 alpha。计划见 docs/spec.md，各阶段的进展见 docs/progress/，各版本的说明见 CHANGELOG.md。

安装

Windows（x64 和 ARM64）、macOS（Apple Silicon 和 Intel）以及 Linux（x86-64 和 ARM64；.deb、AppImage 和 Flatpak）的 alpha 版本可在发布页面获取。每个下载文件都小于 15 MB。目前这些版本尚未通过 Microsoft 签名或 Apple 公证（见代码签名政策）；发布说明介绍了如何跳过各系统上的首次启动警告。命令行工具 coldopen 随应用一同提供，适用于所有系统（docs/specs/release.md §4）。

为了帮助我们测量 Cold Open 在你的计算机上的运行表现，请在命令面板中选择 测量性能，或运行 coldopen bench，然后将它写入“下载”文件夹的两个小文件发送给我们（docs/specs/bench.md）。文件中包含模型名称和耗时，不包含任何个人信息。

代码签名政策

由 SignPath.io 提供免费代码签名，证书由 SignPath Foundation 提供。

Cold Open 正在申请 SignPath Foundation 面向开源项目的计划。在项目获批之前，Windows 版本未签名，Windows 在首次运行时会发出警告。

团队角色：

• 作者（提交者）：可在无需他人审核的情况下修改源代码：TheYungStump。
• 审核者： 在合并其他人的每项更改（例如拉取请求）之前进行审核：TheYungStump。
• 批准者： 手动批准每项签名请求：TheYungStump。

发布签名流程：

• 每个版本都由 GitHub Actions 根据此仓库中带标签的提交构建（.github/workflows/release.yml）。
• 仅对 Cold Open 自有程序进行签名：桌面应用、命令行工具和 Windows 安装程序。
• 每项签名请求都由批准者手动批准。
• 每位团队成员都为 GitHub 和 SignPath 启用了多因素身份验证。

Cold Open 的许多代码由 AI 编码 Agent 在作者指导下、使用作者的 GitHub 账号编写。作者会在每项更改合并前进行审核。

隐私

除非用户或安装或运行该程序的人员明确提出要求，否则本程序不会向其他联网系统传输任何信息。

简而言之：网站使用 Cloudflare Web Analytics 匿名统计访问量，不使用 Cookie；应用不会发送任何数据。

具体来说：

• **Cold Open 不会建立网络连接。**它不会检查更新，也不会联系任何服务。
• 仅保存在你电脑上的使用情况摘要（自 0.1.0-alpha.3 起）。Cold Open 只在这台电脑上统计你使用了哪些功能，除非你在反馈中附上，否则绝不会发送。它只保存次数，不会保存你的文本、名称或文件路径。设置（Ctrl+Comma，或 Mac 上的 Cmd+Comma）可完整查看摘要、重置摘要或关闭统计。(docs/specs/usage-summary.md)
• **Agent 链接仅保留在你的电脑上。**应用与 coldopen mcp 通过只有你的用户帐户才能打开的套接字或管道进行通信（docs/specs/mcp.md）。你连接的 AI Agent 是独立程序：它会读取脚本中的哪些内容，以及会将这些内容发送到哪里，都由该程序及其自身的隐私政策决定。
• **链接会在浏览器中打开，**且只有在你点击时才会打开。
• 测量性能会在你的“下载”文件夹中写入两个报告文件。只有在你发送这些文件时，它们才会离开你的电脑。

从 0.1.0-alpha.2 起，你可以通过应用内的两种方式向我们反馈问题。两种方式都不会自动发送任何内容：

• **报告问题…**会在浏览器中打开一个已准备好填写的页面：GitHub issue，或供没有 GitHub 帐户的用户使用的 Google 表单。应用会填入 Cold Open 的版本和提交标识、构建目标、操作系统名称和版本，以及绘制窗口的渲染器。不会附加脚本文本、文件名或路径，也不会附加用户或电脑名称。除非你亲自提交页面，否则不会发送任何内容；提交前你也可以修改页面内容。
• 崩溃报告。如果 Cold Open 崩溃，它会在你的电脑上保存一份报告：错误消息（移除其中引用的文本）、错误发生位置（Cold Open 代码中的位置）、不含文件路径的代码地址回溯、版本、操作系统和渲染器。报告不包含脚本文本、文件名或用户名。下次启动时，Cold Open 会询问你是否要查看报告。在任何内容离开你的电脑前，它会向你展示完整报告。之后，你可以打开已填好的 issue 或表单，也可以复制报告并自行粘贴。你可以选择不再询问。

网站使用 Cloudflare Web Analytics 匿名统计汇总访问量，不使用 Cookie；不会通过其他方式衡量访客（网站的隐私页面）。

GitHub issue 是公开的，适用 GitHub 的隐私声明。表单回答会通过 Google Forms 私下发送给项目，适用 Google 的隐私政策。

构建

你需要 Rust 1.89 或更高版本。从 https://rustup.rs 安装，然后进行构建：

cargo build --release

这会在 target/release 中构建两个程序：桌面应用 coldopen-app，以及命令行工具 coldopen，后者也会运行 MCP 服务。两者均可在 Windows、macOS 和 Linux 上运行（Windows 上为 .exe）。在 Linux 上，应用运行时需要 X11 或 Wayland，以及 libxkbcommon。

CI 会为每个系统构建软件包（.github/workflows/build.yml、.github/packaging/package.sh）；每个拉取请求的运行结果都会在 Summary ▸ Artifacts 下提供这些软件包。

使用桌面应用

coldopen-app [script.fountain]

• 编写。 新脚本会从场景标题开始。按 Enter 和 Tab 可按编剧习惯在各元素间移动（标题、动作、角色、对白、括号说明、转场）；顶部栏会显示接下来将输入的内容。在标题、角色名和转场中输入的文字会自动转换为大写。自动补全会提供角色名、INT./EXT.、地点、时段和扩展；按 Tab 或 Enter 可接受建议。
• 所有操作都可用键盘完成。 Ctrl+K（macOS 上为 Cmd+K）可打开命令面板，其中列出所有命令、所有应用操作及其快捷键，还有最近打开的文件。
• 页面。 脚本会按打印效果逐页显示，也可切换为连续草稿视图（Ctrl+Shift+D）。左侧导航器会列出场景；拖动场景，或按 Alt+Up/Down，即可调整顺序。
• 文件。 Ctrl+S 可保存（在后台保存，不会打断输入），Ctrl+Shift+E 可导出 PDF；关闭时会询问是否处理未保存的更改。
• 自定义按键与元素流。 设置文件夹中的 keymap.json 和 flow.json 可更改快捷键以及 Enter 和 Tab 的操作；参见 docs/specs/editor.md §5.2 和 §10。应用不会改写这些文件。
• 绘制。 应用在 Windows 和 Linux 上使用 CPU 绘制，在 macOS 上使用 GPU 绘制。GPU 在 4K 和 Retina 屏幕上更流畅；CPU 占用的内存少得多。可通过面板在两者之间切换。

完整行为说明见 docs/specs/editor.md。

让 AI Agent 编辑脚本

claude mcp add coldopen -- coldopen mcp

coldopen mcp 是一个 MCP 服务：每条命令都是一个工具（block_insert、text_replace、scene_list 等），而脚本及其区块、页面和场景都是资源。任何 MCP 客户端的使用方式都相同。

当脚本在桌面应用中打开时，Agent 的 doc_open 会连接到应用，而不是打开文件：你可以看到每项编辑实时显示，紫色标记条会标出它更改的区块，按 Ctrl+Z 即可像撤销自己的编辑一样撤销。每个 Agent 步骤都会标注 Agent 的名称和所用工具，且 Agent 只能撤销自己的步骤。状态栏会显示已连接的 Agent，并提供断开连接按钮和关闭 Agent 访问权限的开关。

两者之间的连接仅对你在本机上的用户账户开放：使用只有你能打开的文件夹中的套接字，或只有你能访问的 Windows 管道，并配有一个全新的 256 位令牌。没有应用时，coldopen mcp 会自行打开文件，并使用同一份崩溃日志。详情见：docs/specs/mcp.md。

使用命令行

转换脚本

coldopen convert draft.fountain clean.fountain

这会将脚本改写为规范的 Fountain 格式。含义不变；空格和标记会经过整理。

若要改为将文档的区块和 ID 输出为 JSON：

coldopen convert draft.fountain - --to json

将 - 设为输出目标，即可写入标准输出。如果目标格式无法容纳脚本中的所有内容，除非添加 --allow-lossy，否则不会写入任何内容。

列出场景

coldopen scenes draft.fountain

输出如下：

   1  1    p. 1     3/8  EXT. LIGHTHOUSE - DUSK  (15 blocks, 39 words)
   2  2    p. 1     2/8  INT. RADIO ROOM - NIGHT  (5 blocks, 18 words)

每行显示场景的起始页，以及以八分之一页为单位的长度。添加 --json 可输出机器可读的结果。

导出 PDF

coldopen export draft.fountain draft.pdf
coldopen export draft.fountain review.pdf --watermark "DRAFT" --scene-numbers

PDF 使用随附的 Courier Prime 字体，在 Windows、macOS 和 Linux 上生成的字节内容完全一致。--no-title-page 可省略标题页。对于字体没有字形的字符（例如中文或表情符号），打印时会显示方框，命令也会指出是哪些字符。

以文本形式查看页面

coldopen pages draft.fountain

会以纯文本形式逐页输出打印效果，采用每英寸 10 个字符的网格，并在每页添加一行页眉，说明该页结束的原因。此功能便于检查分页符。

许可证

coldopen licenses 会打印 Cold Open 的许可证以及随附字体的 SIL Open Font License。你也可以在面板的「关于」中查看这些许可证。

运行一批编辑

edits.json 是一个 JSON 命令数组，也可以每行写一个命令：

[
  {"command": "text.replace", "params": {"find": "MAYA", "with": "NINA"}},
  {"command": "block.insert", "params": {"type": "transition", "text": "FADE OUT."}}
]

对脚本运行：

coldopen run edits.json --doc draft.fountain --save

• run 会为每条命令打印一个 JSON 响应。
• 遇到第一个失败时会停止，除非你添加 --keep-going。
• 如果任何命令失败，它会以状态码 1 退出。
• 如果没有使用 --save（或批处理中没有 doc.save），批处理结束时更改会被丢弃。
• 从崩溃日志中恢复的未保存工作绝不会被丢弃。如果批处理没有触及它，它会留在日志中，供下次打开时使用；如果批处理更改了它，则会保留一份日志副本，并由 run 告知副本位置。

通过标准输入／输出提供命令服务

coldopen serve --stdio

服务会逐行读取 JSON 请求，并逐行以 JSON 响应作答。任何语言都可以通过这种方式驱动它：

→ {"v":1,"id":1,"command":"doc.open","params":{"path":"draft.fountain"}}
← {"v":1,"id":1,"ok":true,"result":{"blocks":42,"format":"fountain","path":"draft.fountain","recovered":null,"scenes":6,"warnings":[]}}
→ {"v":1,"id":2,"command":"block.insert","params":{"after":"b_3","type":"character","text":"MAYA"}}
← {"v":1,"id":2,"ok":true,"result":{"id":"b_43"}}
→ {"v":1,"id":3,"command":"undo"}
← {"v":1,"id":3,"ok":true,"result":{"undone":"block.insert"}}

完整的命令列表、参数和错误代码见 docs/specs/commands.md。

你的工作安全无虞

崩溃日志。 脚本打开期间，每次更改都会在命令返回前写入崩溃日志。对于 draft.fountain，日志是与脚本同目录下的隐藏文件 .draft.fountain.coldopen-journal。

• 如果 Cold Open 崩溃或机器断电，下次执行 doc.open 时会重放日志，并返回 "recovered": {"commands": N}。你的撤销历史也会恢复。桌面应用会显示恢复的内容，并让你选择保留它们或恢复到已保存的文件。
• 在桌面应用中，每次按键都会先写入日志，再显示在屏幕上，并在 250 ms 内刷新到磁盘。无论何时结束应用，屏幕上显示的内容都不会丢失；断电时最多只会丢失最后四分之一秒的内容。未保存的脚本也有日志，应用会在下次启动时提供该日志。
• 保存会重置日志，关闭已保存的文档会删除日志。
• 如果脚本位于 git 仓库中，请将 .*.coldopen-journal 添加到 .gitignore。

原子保存。 保存是原子的：保存过程中发生崩溃时，留下的要么是旧文件，要么是新文件，绝不会各留一半。

详情见 docs/specs/journal.md。

Fountain 支持

Cold Open 支持 Fountain 语法页面中的所有内容：

• 标题页
• 场景标题，包括强制标题和场景编号，以及一些编剧使用的反向 EXT/INT 和 E/I 前缀
• 动作、角色、对白、括号说明和双人对白
• 歌词、转场和居中文本
• 强调
• 注释、废稿区、章节和梗概
• 分页符

每条规则，以及我们如何处理语法页面未明确规定的情况，都记录在 docs/specs/fountain.md 中。

测试

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

测试套件包括：

• Fountain 一致性用例。 每条规则对应一个用例，位于 tests/fixtures/fountain，预期结果均由人工编写。
• 属性测试。 随机生成的 Fountain 文本和随机编辑序列会检查往返转换、撤销、重做和日志重放。
• 崩溃测试。 在一连串编辑过程中终止 coldopen serve --stdio，然后检查新进程是否恢复了所有已确认的编辑。
• 应用的测试门禁。 应用自身的测试会在无头模式下运行，并通过真实界面模拟实际按键。输入门禁会使用智能流转、自动补全、变音符号、一次撤销和保存来输入一个简短场景，并逐字节比较文件；崩溃门禁会在输入过程中随机时刻将应用作为独立进程终止，并检查恢复情况；Agent 门禁会通过真实的 coldopen mcp 进程驱动应用。

私有语料库

真实剧本受版权保护，因此绝不会提交。将 .fountain 文件放在 corpus/ 下（该目录已加入 git 忽略），或将 COLDOPEN_CORPUS 指向其他文件夹。语料库测试会检查每个脚本能否无损往返转换。没有语料库时，该测试会跳过。

模糊测试

fuzz/ 文件夹中存放 cargo-fuzz 目标。它们需要 nightly Rust，并且可在 Linux 或 macOS 上运行：

cd fuzz
cargo +nightly fuzz run fountain_roundtrip

其他目标包括 envelope、journal_replay、fdx_read、link_line 和 app_config。定时工作流会在每周日运行全部六个目标；你也可以从 Actions 选项卡手动启动它。

目录结构

Crate	许可证	内容
crates/screenplay	MIT OR Apache-2.0	剧本类型：元素、富文本、标题页
crates/fountain	MIT OR Apache-2.0	Fountain 解析器和写入器
crates/fonts	OFL-1.1 (字体), MIT OR Apache-2.0 (代码)	随附字体：用于页面的 Courier Prime，以及用于应用界面的 Atkinson Hyperlegible Next
crates/layout	MIT OR Apache-2.0	字符网格布局、分页、页面视图和 PDF 导出
crates/fdx	MIT OR Apache-2.0	只读 .fdx 读取器（第 2 阶段）；写入和修复功能将在第 4 阶段推出
crates/core	GPL-3.0-or-later	文档、命令、调度器、撤销、日志、原子保存
crates/cli	GPL-3.0-or-later	coldopen 二进制文件
crates/app	GPL-3.0-or-later	桌面应用 coldopen-app
crates/mcp	GPL-3.0-or-later	coldopen mcp 背后的 MCP 服务
crates/link	GPL-3.0-or-later	应用与 coldopen mcp 之间的私有连接

这些格式库采用宽松许可证，以便其他应用也能使用。应用本身采用 GPL-3.0-or-later 许可证；详见 LICENSE。Courier Prime 和 Atkinson Hyperlegible Next 字体采用 SIL Open Font License 1.1（crates/fonts/fonts/）；你导出的 PDF 归你所有，不受该许可证约束。

tools/refpdf 是一个开发工具，用于为布局测试测量参考 PDF；它不会随产品发布。