跳到主内容

别再急着装 River Writer 了:本地优先写作里,我先踩了 3 个坑

River Writer 是一个 Mac 上的纯文本剧本编辑器:左边写 .fountain 或 .md,右边实时显示排版好的页,能导出 PDF,版本用内置 Git 管,不联网、不带 AI。结论先给:它的排版引擎值得抄,发行方式不值得抄。引擎把 120 页剧本的每一行算到具体坐标,用 11 个 Rust crate 做纯函数式的排版;发行方式只给源码,macOS 13 起,自己编译。2026-10-18 一天里 66 次提交,之后仓库没有新提交。这套东西适合当技术样本读,不适合当日常软件装。

分流只需要一个问题。你手上有没有一台 macOS 13 以上的 Mac,并且愿意为它装 Xcode 命令行工具、Rust 1.96+、Node 22.12+、pnpm 9。答案是「有」,往下走编译分支。答案是「没有」,这篇就当源码逐读,别装。

先把三个事实摆出来

谈感受之前先看数。下面每条都能自己复现,命令和返回值我都留着。

事实一,仓库是单日冲刺产物。GitHub API 返回 created_at=2026-10-18T18:41:34Z,pushed_at=2026-10-18T22:30:49Z,66 次提交全部落在 2026-10-18 的 00:54Z 到 22:30Z 之间——21.6 小时。release v1.0.0 的时间戳是 21:22Z。星标 8,fork 1,tag 只有 v1.0.0 一个。

事实二,源码不大,但下载不快。tarball 2,802,448 字节,实测 37.1 秒下完,折算 75.5 KB/s。Cargo.lock 里 165 个包。

事实三,UI 和引擎是两套东西。引擎 11 个 crate:river-parse、river-layout、river-paginate、river-pdf、river-render、river-text、river-model、river-templates、river-vcs、river-service、river-cli。GUI 是 Tauri 2 + SolidJS + CodeMirror 6。引擎侧不依赖 Tauri,这条写在 docs/09-engine-cli.md 第一段。

这个分层不是洁癖。我们做网页附件批量下载那阵子也踩过同样的取舍:判定规则必须能脱离界面、脱离网络跑断言,改规则不用靠手点按钮验证(post/408)。River 把这条做到了 CLI 上——river export 就是没有窗口的排版入口。

关键依赖只有五个,每个都对应一件事。parley 0.12 做文本整形与断行,决定一段话在哪折行;skrifa 0.44 读字体,把 Courier Prime 的字形取出来;krilla 0.8 写 PDF,负责子集嵌入和可选文本;tiny-skia 0.12 光栅化,给预览出 PNG;pulldown-cmark 0.13 解析 Markdown 子集。五个库各司其职,没有一个管网络。

这套组合值得记一笔:做排版最难的从来不是画字,是断行和分页。parley 解决断行,river-paginate 自己解决分页,两个问题分开治。想自己写排版的人,先想清楚这两个边界在哪,别一上来就调 PDF 库。

第一层分支:编译这一关你过不过得去

判定条件很硬。缺一样,后面所有分支都作废。

xcode-select --install
# Rust 1.96 或更新
# Node.js 22.12 或更新
corepack enable

这四样逐项看,每样都有个下限原因。xcode-select --install 给的是 clang 和系统 SDK,Rust 在 macOS 上链接要它,缺了报 linker command failed。Rust 下限 1.96 来自 Cargo.toml 的 rust-version = "1.96",同时 edition = "2024",低于 1.85 的编译器连 edition 都不认。Node 下限 22.12 是 Tauri 2 CLI 与 Vite 8 的要求,Node 20 装 @tauri-apps/cli 会警告。pnpm 9 用 corepack enable 拉起来,仓库带 pnpm-lock.yaml,装依赖时带 --frozen-lockfile,版本对不上会直接失败而不是悄悄升版本。

版本卡这么死是有代价的。工具链任一项漂移,构建报错的位置离真正原因很远——你看到的是某个 crate 编译失败,实际是 Node 版本让前端产物路径变了。先对齐版本,再看报错。

官方 README 的构建步骤是四行:

git clone https://github.com/arjunacharya10/river-writer.git
cd river-writer
pnpm --dir app install --frozen-lockfile
pnpm --dir app tauri build --bundles app

我在 Windows 上试了。不是要跑 GUI,只想跑 cargo test --workspace,验证排版 crate 能不能跨平台。

第一次,离线模式。报 error: no matching package named `parley` found。本地没缓存,正常。

第二次,联网。cargo fetch 重试三轮,每轮四行 warning: spurious network error (N tries remaining): [6] Could not resolve hostname (Could not resolve host: index.crates.io)。最后 error: failed to get `parley` as a dependency of package `river-text v1.0.0`。

同一个终端里 curl https://index.crates.io/config.json 是 200。cargo 解不出域名,curl 解得出来。这台机器的 DNS 对那个域名返回 Server failed。换机器可能就好了,但那不是我该假设的事。

排查顺序别乱。先确认域名解析,再怀疑依赖版本,最后才看代码。我先做了两次 cargo fetch,等于把同一个错误确认了两遍,白花四分钟。做 OCR 表格识别那次也是这个教训:先提输入分辨率,再查是不是被拆成多个子表,顺序反了就一直在调模型参数(post/263)。排查顺序错了,努力全是无效功。

编译分支到这儿断了。我改成读源码加跑 golden 输出。这个替代路线反而挖到了更多细节,后面几节都用它。

分支判定:编译过不去,走只读路线;能编过,直接看第五节模板参数,那是这套引擎最值钱的部分。

第二层分支:你要的是排版,还是版本管理

这两个需求经常被混在一起说。分开看,结论完全不同。

排版侧是真的做了事。四套模板不是换 CSS,是四组几何参数加四套分页规则。每一行的 x、y、字号都算出来,预览和 PDF 从同一份 display list 画。官方说法是「preview = print, exactly」,webview 不做排版。这话在代码里对得上:river-layout 出几何,river-pdf 和 river-render 各画一遍。

版本管理侧用的是真 git,不是自研格式。river-vcs 的依赖只有一行:git2 = { version = "0.20", default-features = false }。关掉默认特性等于砍掉传输层,库里没有 push 能力。

建仓那行值得单独看:

let mut options = git2::RepositoryInitOptions::new();
options.initial_head("main");

写死 main。而系统 git 2.55 在 Windows 上 git init 默认还是 master。我按这个差异踩了第二个坑,第 8 节讲。

还有一个细节很讨巧。_river/river.json 是每台机器的 UI 状态,作者没去改用户的 .gitignore,而是往 .git/info/exclude 里写一行。原文注释是「River never edits the writer's .gitignore」。这个做法我们写电商系统二开时也用过:只加不改,旁挂一个扩展表,主表一行不动(post/350)。侵入性小,回滚也干净。

分支判定:你只想要「写完能出正确排版的 PDF」,排版分支够用;你想要的是「草稿有版本、能开分支写另一个结局」,版本分支能用但别指望协作——v1 没有远端。

性能预算也值得看一眼。官方 docs/05-architecture.md 写的是 M 系列 Mac 上的目标:敲键到高亮小于 16ms,敲键到大纲刷新小于 100ms(防抖 50ms),120 页剧本改一次到预览更新小于 150ms,400 页小说小于 300ms,导出 120 页 PDF 小于 1 秒,提交小于 300ms。注意这些是目标值,不是实测值,作者自己标了 budget 这个词。

预算里最狠的一条是分页时机:只在预览打开或导出时跑,编辑器从不请求分页数据。这条决定了写长稿不卡——页面数据在你关掉预览的那一刻就不算。我实测提交 3,359 行、82,778 字节的剧本花了 0.14 秒,落在 300ms 预算内。分页我没跑成,这条只能算官方口径。

四套模板的参数,逐项拆开看

这套引擎最硬的干货在 crates/river-templates/templates.json。全部参数就七项,四套模板各一份。抄下来是这样:

参数screenplayscreenplay-multicamstageplaymanuscript是什么、改错会怎样
pitch12121224行距(pt)。版面可用高 648pt(TOP=72、BOTTOM=720),12pt 得 54 行,24pt 得 27 行。改成 18 会出现半行,页尾留白肉眼可见
dialogue_pitch12241224只作用于对白与歌词。multicam 用它做双倍行距,这是美式多机情景喜剧的惯例。误设成 12,多机位稿会挤成普通剧本
first_indent00036首行缩进。只有 manuscript 用 36pt(半英寸)。剧本侧必须 0,缩进会把动作行挤到对白列
cheat2460600页尾允许超出的余量(pt)。代码里是 BOTTOM + cheat(),且只在页脚为空时生效。误把 cheat 调到 200,最后一行的基线会压到页码带上
sentence_breakstruetruetruefalse分页优先在句号处切。剧本要它,小说不要——小说按段落流,硬切句子会读出断裂感
print_sectionsfalsefalsefalsetrue是否把 # 章节打进成品。剧本的 section 是给编剧看的骨架,不进纸面;小说里它就是章标题
number_firstfalsefalsefalsetrue首页是否编号。剧本首页是标题页,不打页码;小说从第 1 页开始数

几何也对得上。screenplay 的 scene 起点 x=108(1.5 英寸),宽 400.032;cue x=248.976,宽 248.976;dialogue x=178.992,宽 248.976;parenthetical x=207。stageplay 的动作行不是从 108 起,是 x=288、宽 252——舞台剧的舞台指示居中偏右,这跟剧本不一样。manuscript 全部拉到 x=72、宽 468,一栏到底。

元素screenplaystageplaymanuscript看什么
action108 / 432288 / 25272 / 468舞台剧的动作行窄且右移,打印后紧贴对白上方
scene108 / 400.032108 / 400.03272 / 468场景标题一律左顶格,宽不到版心,长标题会折行
cue248.976 / 248.976214.992 / 325.00872 / 468角色名起点,小数位来自英寸换算,不是手填
parenthetical207 / 211.032214.992 / 239.97672 / 468括注比对白左移一点,避免与对白首行齐头
dialogue178.992 / 248.976124.272 / 330.98472 / 468剧本对白最窄,舞台剧放宽,小说通栏
lyric178.992 / 361.008108 / 348.98472 / 468歌词要跨过对白列,宽度比 dialogue 大

单位都是 pt,格式是「起点 x / 宽度」。看这张表能发现一个设计倾向:屏幕剧本把版面切成窄栏,对白只占 248.976pt,相当于 3.46 英寸;舞台剧反过来,对白给到 330.984pt。同一个引擎,两套版式逻辑,靠数据切换,不靠 if 分支。

这些数不是拍脑袋。官方 docs/01-product-brief.md 说参数参照的是行为研究(Highland 一类工具的实际输出),不是抄某家资产。我核过 golden 文件里的 y 坐标:screenplay 正文第一行 y=72,步进 12,到 276 换页;manuscript 步进 24。与表里参数一致。

验收方式也值得抄。他们不截图比界面,而是把 layout 结果 dump 成文本,逐行比 x、y、字号。fixtures/golden/ 下四个文件就是四套模板的黄金输出。我们给 PDF 工具做验收时也是这个路子——不看界面数字自证,把成品光栅化后实测框位(post/327)。界面会骗人,坐标不会。

第三层分支:边界情况怎么判

边界才是排版引擎的真面目。同一份 fixtures/screenplay.fountain,我拿 River 的 golden 输出和 Python 的 screenplain 各跑一遍,差异都在这。

双人对白。原文在第二个角色名后加 ^。River 输出两列:MAYA 的 cue 在 x=162,ELIAS 的 cue 在 x=396,对白分别在 108 和 342。左右各占一栏,宽度 234。screenplain 用 div.dual 套左右两个 div,也是并排,但列宽交给 CSS。两条路线都对,River 的选择是几何确定,跟浏览器无关。

歌词。原文 ~The river runs beneath the road.。River 认成 Lyric 元素,x=178.992,斜体。stageplay 模板下还额外大写,输出 THE RIVER RUNS BENEATH THE ROAD.。screenplain 原样输出带波浪号的一行。规范里 ~ 是 1.1 才加的强制歌词,老实现不认,正常。

强制角色大小写。原文 @McKay。规范说 @ 的本意是保住混合大小写。River 输出 MCKAY——它的模板规则里 Cue 一律大写,uppercase() 那个函数第一行就是 matches!(kind, Kind::Scene | Kind::Cue)。screenplain 输出 McKay。这里两家对规范的理解不一致,你要混合大小写的角色名,得知道成品会变大写。

未定义的强调。原文故意写了 +yellow light+ 和 ~~dead~~。River 的 golden 里是干净的「A yellow light flashes twice. The dead radio begins to hum.」——标记被剥掉,文字留下。screenplain 把 + 和 ~~ 原样打进成品。往稿子里塞非标准标记,换工具就露馅。

注释与场景号。原文有 [[The two lines above overlap...]],两边都不打印。#2# 场景号,River 的正文文本里没有,screenplain 输出成 2INT. SIGNAL ROOM - NIGHT2,靠 CSS 摆到两侧。数字进不进文本流,直接影响你怎么 grep 剧本。

标题页。同一份 front matter,manuscript 模板只输出 Title 和 Author,Credit: Written by 那行丢了。剧本模板才印 Credit。小说稿不需要「Written by」这种署名行,这个取舍说得通,但你得知道。

这类边界我习惯先列清单再验,跟做大纲转 PPT 时踩的坑一个道理——标题写完直接跟「- 要点」,第一条要点会被吃掉,只有专门写一条断言才测得出来(post/356)。边界不写进用例,就等于没测。

分页规则也属于边界,而且是最容易出错的一类。官方 docs/09-engine-cli.md 列了四条:对白过长要拆页时给 (MORE) 和重复的 CUE (CONT'D),两边各留至少两行正文;括注必须跟后续对白同页;场景标题要 keep-with-next,不能孤零零留在页尾;段落有孤行寡行控制,句子优先切页,句子比整页还长时退回整行切,保证每页都有进展。

这几条在 golden 的输出里看不到,因为样例太短,一场戏才十来行。想看拆页效果得自己造长稿。我的判断是:这套逻辑比模板参数值钱,参数抄得走,规则抄不走。

还有一处边界在文件层。相对路径的 {{INCLUDE: path}} 会被展开,但规范路径必须留在初始文件所在目录内,循环引用和超过 32 层嵌套直接拒绝,且明确写「No content is fetched from the network」。这条限制看着保守,实际是在堵「模板引用外部文件」的口子——一旦允许向上跳目录,项目文件夹就不再是自包含的。

各分支的默认推荐

三条默认,按你的实际处境挑。

只想安静写、不折腾工具——纯文本 + 系统自带备份。.fountain 和 .md 都是文本,二十年后还能打开。这条最便宜,也最不容易废。

要「写完直接出正确排版的 PDF」,且人在 Mac 上——用 River 的引擎,自己编。代价是一次编译,收益是四套模板的几何精度。

要多人改同一份稿——别用 v1。决策日志 #64 写得很清楚:远端、push/pull/fetch、clone 全部推到 v1.1。v1 没有跨机器副本。

还有一条反向建议。你要的如果是「AI 帮我写」,这工具明确不做。README 那句是「No accounts, cloud, telemetry or AI」。不是没做完,是产品决定。

判定别做成二选一。分三档更实用:完全满足、部分满足、不满足。完全满足是 Mac 13 以上加愿意编译,直接上。部分满足是人在 Mac 但不想碰终端,那就只用它的模板参数,别装 GUI。不满足是 Windows 或要协作,读源码学思路就行。我们做简历岗位对照工具时也用了三档判定——除了「有」和「没有」,中间留一档「部分覆盖」,同词根不同形态、固定搭配只中一半、中文二元组命中六成以上都算部分(post/372)。二值判定会把大量真实处境挤到「不满足」里去,结论就失真了。

每个分支的最小可行做法

编译分支,五步。命令照抄,端口和路径按自己机器改。

git clone https://github.com/arjunacharya10/river-writer.git
cd river-writer
pnpm --dir app install --frozen-lockfile
pnpm --dir app tauri build --bundles app
cp -R "app/src-tauri/target/release/bundle/macos/River Writer.app" /Applications/

官方决策 #65 记录:全新 clone 加 Node 22.12,Rust 编译约 1 分钟,app 18 MB,codesign --verify --deep --strict 通过,能启动。为什么没有 Gatekeeper 拦截——自己编的包没有 quarantine 标记。这也是他们不买 99 美元开发者账号的理由。

引擎分支,不用 GUI 也能出 PDF:

cargo run -p river-cli -- export fixtures/screenplay.fountain -o output.pdf
cargo run -p river-cli -- export fixtures/manuscript.md -o m.pdf --preview-dir preview
cargo run -p river-cli -- inspect fixtures/screenplay.fountain
cargo run -p river-cli -- check fixtures/manuscript.md

--preview-dir 出 144 dpi 的 PNG,跟 PDF 同一份 display list。--template 可选四个值,不传就按扩展名判:.fountain 走 screenplay,.md 走 manuscript。没有字体选项,Courier Prime 是打包进去的(OFL 授权)。

导出有三条保护,文档里写了,很容易忽略。目标目录必须预先存在,PDF 和 JSON 的父目录不会自动创建,只有预览目录会自动建。已存在的输出文件默认不覆盖,要加 --force。源文件本身不能当输出——包括被 include 的文件、以及指向它们的硬链接和别名,拿源文件当输出会被拒。写文件走临时文件再落位,但多文件导出不是一次原子事务。

这三条保护来自踩坑,不是设计洁癖。我猜最疼的是「拿源文件当输出」,一次手滑把 script.fountain 覆盖成 PDF,稿子就没了。默认不覆盖 这条比任何备份策略都直接。

版本分支,三个动作就够:commit、开分支、切回来。第 8 节的数是我在本机实测的。

准备一份 3,359 行、82,778 字节的剧本,git init 后首次提交 0.14 秒,.git 占 76 KB。连续提交 20 次(模拟自动存稿),.git 涨到 290 KB。git gc 之后 pack 只有 11.55 KiB,21 个版本压成 11.55 KiB。

继续加到 101 个提交,git gc 后 pack 50.00 KiB,.git 191 KB。一个 120 场戏的剧本,100 个版本,50 KiB。这个成本基本可以忽略。

分支操作更快。新建 ending-dark 并切过去 0.056 秒,改结尾后提交 0.150 秒,切回 master 0.053 秒,再切到 ending-dark 0.063 秒。代价在几十毫秒级,比等一次预览重排还短。

这里踩了第二个坑。我按习惯敲 git switch main,返回 fatal: invalid reference: main。系统 git 2.55 建出来的是 master,River 建仓写死 main。两边混用时,先 git branch -a 看一眼再切。

第三个坑在身份上。river-vcs 取作者信息是这条链:先读 git 配置,没有再调 /usr/bin/id -F 和 id -un 拿 Mac 账户名,都没有才用 River Writer <river@localhost>。我在 Windows 上执行 /usr/bin/id -F,返回 id: unknown option -- F。这个分支在 macOS 之外等于永久失效,好在有最后那层兜底。

备份这条要说清。v1 没有远端,作者自己丢了跨机器副本(#64 明确接受这个后果)。日常靠 Time Machine。river.json 里的 _river/ 状态不进版本库,只在本机。

三档规模,三套参数与代价

同一套工具,稿子长短不同,该开的开关完全不同。按行数算最直观:54 行一页,120 页剧本约 6,480 行,400 页小说按 27 行一页约 10,800 行。我那份 3,359 行的测试稿,折算 62 页。

小规模,短片或单场景,20 到 30 页,一两千行。参数全用默认,git 可以不开——你一个人写三天,靠自动保存就够。代价是零。这条路上唯一值得改的是 pitch,你要给导演看双倍行距的版本,把 12 改成 24,页数立刻翻一倍,54 行变 27 行,页数从 30 变 60。别改 cheat,小稿用不上页尾余量。

中等规模,标准长片,100 到 120 页。这是 River 默认参数的目标区间。该开的都开:sentence_breaks 保持 true,让分页落在句号处;cheat 保持 24,页尾多两行能少一次尴尬的拆页;git 必开,因为你要试另一个结局。我实测的 21 个版本占 11.55 KiB,切分支 36 到 63 毫秒,代价可以忽略。这一档真正的时间成本在「改模板后回改旧稿」——参数一动,历史稿的分页全变,得逐篇复查。我们改站内锚文本那次就是这样,47 篇旧文一篇篇过(post/151)。参数集中管理的意义就在这儿:改一处,知影响面。

大规模,400 页小说或剧集,上萬行。麻烦不在排版,在版本和备份。manuscript 模板 pitch 24,10,800 行排 400 页,一次全量重排的耗时官方给的预算是 300ms,但那是目标值。更硬的约束是 v1 没有远端——决策 #64 明确说 v1 没有跨机器副本,作者把「remotes 推到 v1.1」当成可接受的取舍。多人改同一部剧,v1 直接出局。你要么等 v1.1,要么用系统 git 在外面接管这个仓库:River 认已经存在的仓库,ensure_repository 里那句注释是「An existing repository with history is adopted as it is」,你在外面 git remote add 推上去,River 不管,也不会拦。

三档的共同点只有一条:文件和版式分开。这条跟稿子长短无关,是所有分支的底座。

分支对照表

你的处境选哪条要付的代价得到的
Mac 13+,愿意装工具链自己编译 GUI四套工具 + 约 1 分钟 Rust 编译实时预览、四模板、PDF 导出、内置 git
Mac,不想装 GUI 依赖只编 river-cli没有实时预览,靠 --preview-dir 看 PNG批量出 PDF,可进 CI
Windows / Linux读源码 + 自己实现排版模板参数要自己搬抄到 54 行/页与四套几何,不用背框架
要多人协作等 v1.1,或换工具现在没有远端—
要 AI 辅助写作换工具—River 明确不做 AI

表里「54 行/页」不是估的。river-paginate 顶部两行常量 TOP=72.0、BOTTOM=720.0,可用高 648pt,除以 pitch 12 得 54。manuscript 的 pitch 是 24,得 27 行。

走错分支的典型症状

症状一,在 Windows 上死磕编译。你会看到 Could not resolve host: index.crates.io 连刷三轮,然后 cargo 放弃。这不是 River 的问题,是依赖拉不下来。换台机器或者换条路。

症状二,指望 v1 能 push。你在 Source Control 面板里找不到远端入口,不是藏起来了,是没做。#64 把「加远端、push/pull/fetch、clone」整批推到 v1.1。

症状三,以为有 AI 补全。README 写的是 no AI。它的价值在排版和版本,不在生成。

症状四,以为会自动更新。决策 #30 明确不检查更新。Help 菜单里那两项是把网页丢给浏览器打开,River 自己不联网。

症状五,找「历史版本」侧栏。v1 删掉了私人时间线(#66),版本就是 git commit。没提交过的文字,关掉标签页就没了。这条代价作者自己写进了决策日志。

症状六,拿它写 Markdown 技术文档。manuscript 模板只认一个小子集:标题、段落、强调、引用、列表、分场景线。代码块和图片会报 diagnostic。这不是通用 Markdown 渲染器,官方文档原话是「deliberately a small creative-writing subset」。想写文档还是回编辑器。

症状七,以为装完就齐活。你翻设置找「导出 A4」「打印」「项目全局搜索替换」「标签页分组」,全都没有——决策 #64 那张单子把 A4、原生打印、全局搜索替换、分割编辑器、标签、教学提示整批推到 v1.1。这不是半成品,是明确的范围冻结。真要用这些功能,得等版本,或者自己写。我们那个大纲转 PPT 工具也是这么过来的,内部迭代了几个版本才补上拖拽和进度日志(post/147)。v1 的定义是「能用」,不是「齐全」。

「无网络」这句承诺,自己怎么验

作者的卖点是「makes no network connections」。这种话不能只看 README,得看配置。我按四层查了一遍。

查什么怎么看结果
依赖里有没有 HTTP 栈翻 Cargo.lock 的 165 个包名没有 reqwest、hyper、ureq、rustls、openssl、h2
git 能不能推看 river-vcs 的依赖声明git2 带 default-features = false,传输层被关掉
Tauri 挂了什么插件看 app/src-tauri/Cargo.tomltauri = { version = "2", features = [] },只多一个 tauri-plugin-dialog
webview 能连哪看 tauri.conf.json 的 CSPconnect-src ipc: http://ipc.localhost,外网域名不在白名单
前端有什么权限看 capabilities只有 core:event:allow-listen 与 allow-unlisten,没有 fs、没有 http

四层都对得上。唯一一次 std::process::Command 是调 /usr/bin/id,本地进程,不联网。

验不出来的时候,退回最保守的用法。别信「无网络」标签,把项目文件夹当纯文本目录看:.fountain 和 .md 用任何编辑器能开,git 用系统自带的也能跑。工具坏了,稿子还在。我们把表格识别工具逼到保底路线时也是这个逻辑——识别不稳就取消「保留表格」,让它输出普通文本段落,手工再整理(post/283)。保底方案不难看,难看的是没有保底。

这种「查配置而不是查声明」的习惯值得留。我们做 RSS 抓取器时坚持纯标准库,理由一样:交付给普通用户双击就用,多一个依赖就多一种在别人机器上跑不起来的可能(post/275)。依赖表比功能列表更能说明一个软件的边界。

反过来说,这也解释了它为什么只发源码。没有更新器、没有签名、没有下载页,网络承诺才守得住。代价是用户得自己动手。

常见问题

Windows 上到底能不能跑

引擎大概率能,GUI 现在不能。引擎 11 个 crate 是纯 Rust,只有 river-vcs 里有一处 /usr/bin/id 依赖 macOS,会静默降级到 River Writer <river@localhost> 这个兜底身份。真正的拦路虎是打包:tauri.conf.json 的 bundle.targets 只写 ["app"],macOS.minimumSystemVersion 是 13.0,signingIdentity 是 -(ad-hoc 签名)。决策 #36 的原话是 Windows 推后、不为跨平台牺牲 Mac 体验。我在 Windows 上连 cargo fetch 都没过——本机 DNS 解不出 index.crates.io,三轮重试后报 failed to get `parley`。换台网络正常的机器,cargo test --workspace 有机会跑通,但这只是推断,我没跑成。想做实验,最省事的路径是先在一台 Linux 机器上把引擎 crate 单独编出来,跳过 app/ 目录,因为 engine 侧不依赖 Tauri。

不编译,能不能只用它的排版规则

能,而且这是性价比最高的用法。crates/river-templates/templates.json 里四套模板的七项参数是纯数据:pitch、dialogue_pitch、first_indent、cheat、sentence_breaks、print_sections、number_first,加上每个元素的 x 与宽度。抄下来放进自己的模板引擎,半小时能对齐大半。真正的难点不在参数,在分页:对白跨页要给 (MORE) 和 CUE (CONT'D),两边各留至少两行;括注不能跟对白拆开;场景标题不能单独留在页尾。这几条在 river-paginate 里占了大部分代码,抄参数容易,抄规则难。

那个 cheat 参数是干什么的

页尾的余量,单位 pt。代码里判断是 self.y + block.height() <= BOTTOM + self.cheat(),BOTTOM 是 720。screenplay 给 24,等于允许正文压到 744,多塞两行。multicam 和 stageplay 给 60,能多塞五行。manuscript 给 0,一行都不让超。有个附加条件容易漏:cheat() 这个函数里先判页脚,页脚是 %none 或者空串才返回模板的 cheat 值,否则返回 0。也就是说,你一旦设了页脚文字,cheat 自动失效。误以为 cheat 永远生效,页尾的留白会跟预期差两行。页码那套也藏在同一个地方:页眉画在 y=36,页脚画在 y=744,占位符认 %p、%pp、%title,用竖线分隔可以排三栏,每栏 156pt 宽。第一页要不要编号,由 number_first 决定——剧本不打首页页码,是因为首页是标题页。

用它写小说,跟用 Word 有什么区别

区别在「文件和版式分离」。River 里小说存 .md,一个项目就是一个文件夹,章节是文件,正文是纯文本。manuscript 模板负责版式:pitch 24(双倍行距)、首行缩进 36pt、print_sections 打开(# 变成章标题)、number_first 打开(首页就编号)、sentence_breaks 关闭(不按句切页)。Word 里版式和内容混在一个二进制文件里,改字体可能挤掉一段的分页。River 这边改模板不动文本,改文本不动模板。代价是它不认代码块和图片,官方明说只支持写作子集。

版本管理会不会把稿子搞乱

不会,但要接受两个前提。第一,commit 是全量提交,没有暂存区概念,官方把 index 藏在后面,点提交就是全部改动——你没法只提交某一段。第二,v1 没有 merge、没有远端、没有 tag。docs/04-versioning-git.md 的 v1 范围写着 commit、history、diff、restore、branch create/switch,其余推到 v1.1。我实测的成本很低:3,359 行 82,778 字节的剧本,21 个版本 git gc 后 11.55 KiB,100 个版本 50.00 KiB,分支切换 36 到 63 毫秒。真正的风险不在 Git,在「忘了提交」——没提交的文字关掉标签页就找不回来。

源码仓库在哪,star 多少

仓库是 github.com/arjunacharya10/river-writer,MIT 授权。截至 2026-11-15 查 API:8 star、1 fork、1 个 release(v1.0.0,发布于 2026-10-18T21:22:31Z)、66 次提交全部落在 2026-10-18 当天。pushed_at 也是 2026-10-18T22:30:49Z,之后没有新提交。星标会变,这个数只代表我查的那天。项目热度不高,但文档写得比多数高星项目细——docs/ 下 11 篇,含决策日志 60 多条,每条都写了备选方案和取舍理由。读它的决策日志,比读十篇测评有用。

最后留一句判断。这套代码值得学的是「几何先算、渲染后画」和「参数全放进 JSON」,不值得学的是发行方式。想清楚你要的是排版精度还是省事,分支自然就出来了。仓库地址在上面,源码自己看。

相关阅读

分享到:

本文链接:https://www.biyeyuanma.cn/post/431.html

服务热线

加我微信

加我微信