使用说明 — TopWriter

快速上手

前置条件：下载页的四步已完成（Zed + writer-core 在 PATH 上）。从这里到第一句灰字，五步。

1

写好模型上游配置

新建 ~/.writer/upstream.env，告诉网关往哪里发请求：

WRITER_UPSTREAM_BASE=https://api.deepseek.com/v1
WRITER_UPSTREAM_KEY=sk-你的密钥
WRITER_CHAT_MODEL=deepseek-chat
WRITER_FIM_REASONING_EFFORT=none

字段含义见下一节。编辑器侧不用写真实模型名，固定用别名 writer-main，由网关改写。

2

从模板建书

把仓库里的 templates/novel/ 复制成你的写作目录。里面已经就位： .novel/（人物卡、世界观简报、时间线、伏笔账本）与 chapters/（章节正文）。

3

启动网关（单项目模式）

哪本书正在写，由启动参数决定。换书 = 换目录重启：

$ ./script/writer-serve.sh /path/to/你的小说
网关：127.0.0.1:8787  项目：/path/to/你的小说

脚本自动读入 ~/.writer/upstream.env。目录里没有 .novel/ 时会警告——那样续写拿不到设定。

4

配置编辑器

两件事，都只做一次：

① 把 docs/CONFIG.md 里的「A 块」粘进全局 settings （macOS：~/.zed/settings.json）；
② 命令面板执行 zed: install dev extension，选仓库里的 extension/ 目录。

为什么必须写全局：模型与续写配置（language_models / edit_predictions / agent.default_model）只读全局 settings，写进项目级 .zed/settings.json 就是「配了却不生效」。

5

开写

打开 chapters/ 里的任意一章，光标停在段落末尾一秒。

✓ 通关标志：浅灰色的续写字浮现出来，按 Tab 采纳——整条链路已通。没有灰字？看常见问题第 1 条。

配置模型与续写

writer 的配置分三层：网关的环境变量、编辑器的全局 settings、书目录里的 .novel/。各管各的。

upstream.env 字段表

变量	必填	说明
`WRITER_UPSTREAM_BASE`	✓	OpenAI 兼容上游地址，如 `https://api.deepseek.com/v1`
`WRITER_UPSTREAM_KEY`	—	不设时透传客户端 Authorization（占位 key 会被网关忽略）
`WRITER_CHAT_MODEL`	—	把请求里的 `writer-main` 别名改写为真实模型名
`WRITER_FIM_MODEL`	—	承接 FIM 改写的模型，默认 `writer-main`（可单独指定续写模型）
`WRITER_FIM_REASONING_EFFORT`	—	默认 `none`。保持不动，见下方警告

续写（FIM）通道必须关推理：推理模型会把预算花在隐藏推理上，返回空续写（实测约三分之一的请求返回空）。保持 WRITER_FIM_REASONING_EFFORT=none 不要改。

编辑器配置作用域

文件	放什么
`~/.zed/settings.json`（全局）	`language_models` / `edit_predictions` / `agent.default_model` —— 模型与续写类配置只能写这里
`你的书/.zed/settings.json`（项目级）	只有 `languages.*` 与 `context_servers`

改了 .novel/ 里的设定文件？设定类型在 .novel/writer.json 里声明；解析失败时网关会直接关闭注入、cli check 报错——不会带着坏配置继续写。修好后重启网关即可。

跨设备同步

整本稿打成 zip 归档，同步到 sync.topwriter.club。零配置：端点已内置，一串同步码就是全部凭证。

先有身份（可选）

书可以归属账号（推荐，邮箱仅作标识，不验证）：

$ writer-core auth register --email you@example.com --password '至少8位'
$ writer-core auth whoami

登录会话存本机（180 天），之后同步自动带上，不用重复登录。不用账号也可以，匿名同步码照常工作。

六个命令

命令	作用
`cli sync --push`	推最新稿。第一次执行自动创建同步码并打印
`cli sync --link ABCD-2345`	在另一台设备绑定同一本书
`cli sync --pull`	拉最新。覆盖前先存本地快照，不怕丢
`cli sync --status`	云端几个版本、本机落后没有
`cli sync --rotate`	换码。旧码立即失效，云端版本完整搬迁
`cli sync --delete --yes`	清空云端全部版本，本地稿件不动

以上均为 writer-core cli …。

两台设备同时 push？不会互相覆盖：服务端用 CAS 检查，后到的一端收到 409 和可读提示——先 pull 再 push。一台设备删掉的章节，另一台 pull 后也会真的删掉（manifest 机制），.git/ 永不上传。

日常写作

写完一章、换一章、交稿，常用的几条命令。

全书体检

$ writer-core cli check

伏笔账本、人名表、设定引用的一致性都在这里查；编辑器里的波浪线诊断与之共用同一份判据。

快照与回滚

保存即自动存快照（2 秒去抖，只记录小说目录）。手动管理与回看：

$ writer-core cli snapshot --list
$ writer-core cli snapshot --diff abc123   # 中文可读 diff：「透→涌」这种差异能看出来
$ writer-core cli snapshot --restore abc123

导出成书

$ writer-core cli export --format docx --root /path/to/你的小说 --out ~/Desktop/书名.docx

支持 txt / md / docx / epub；docx 带中文首行缩进与宋体，书名作者取自 .novel/project.json。

章节与字数

$ writer-core cli chapters new --title '第三章 灯下' --root .
$ writer-core cli words

常见问题

按踩到的概率排序。

1. 续写灰字不出现？

按顺序查：① 确认 WRITER_FIM_REASONING_EFFORT=none（开着推理会返回空续写）； ② 改过 .novel/ 或 projects.json 之后重启过网关吗；③ 翻 ~/.writer/events.jsonl，空续写会打 WARN（含 finish_reason）。

2. 配置写了没生效？

九成是作用域写错了：模型与续写类配置只认全局 settings，项目级只承载 languages.* 与 context_servers。见配置一节的作用域表。

3. 稿件隐私怎么保障？

正文只经过本机 127.0.0.1 网关；模型请求发往你自己配置的上游。只有主动 sync 时稿件归档才到同步服务，且 sync --delete --yes 随时可清空云端。

4. 两台设备同时写会怎样？

不自动合并。后 push 的一端被服务端 409 拒绝并提示先 pull；pull 覆盖前自动存快照。

5. 同步码丢了 / 泄露了？

码存在书的 .novel/sync-code 里，pull 过的设备自动继承。泄露就 sync --rotate：秒换新码，旧码立即失效。

6. 忘记密码怎么办？

内测阶段暂无自助找回（邮箱仅作标识）。联系服务端管理员重置，或换一个邮箱重新注册。

7. 有手机端吗？

暂无。现阶段可把书目录放进 git 远端，在移动端用 Obsidian 等工具查看改稿。