discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
GLFzr/QianBi-Novel · source
Snapshot 0 · 2026-11-04T12:47:28Z · Python · MIT
Content fingerprint
1ee9a567b859b4e887c498304e545749f6661529d1312b706d654c76e3420938GitHub description at capture
千笔一文 Novel — 人 AI 共写的长篇网文创作台：条目化世界书 · 正则 must 契约（确定性复检，违规拦住锁定）· 三层审校（引证验真 + 投票）· 同人文外部导入可整批撤销 · 升级不动书稿 · BYOK 全本地 · MIT。A long-form fiction co-writing agent whose pipeline knows how to say no.
README at capture
# 千笔一文 Novel
**中文** · [English](README.en.md)
[](https://github.com/GLFzr/QianBi-Novel/releases/latest)
[](LICENSE)
[](#下载)
[](https://github.com/GLFzr/QianBi-Novel/actions/workflows/tests.yml)
**人 AI 共写的长篇网文创作台** —— AI 全程透明写作，人永远是作者。
写一部长篇网文真正的难点不是「让 AI 写出一章」，而是写到第 300 章时
**设定还没崩、代价还没赖账、伏笔还记得收**。千笔一文把这件事拆成一条有闸门的流水线，
以及在每个环节都能插手的共写界面。
> 🚀 **公测进行中**：下载安装 → 「设置 → 连接与模型」贴 Key → 开写。
> 问题与建议提 [Issue](https://github.com/GLFzr/QianBi-Novel/issues/new/choose)（有模板），
> 长讨论与晒书去 [Discussions](https://github.com/GLFzr/QianBi-Novel/discussions)。
> **作者的话**：我认为写作 Agent 的终局不是「更会写的模型」，而是**会拒绝的流水线** ——
> 所以它可能是未来最好用的那一个。这不是跑分结论，而是一个工程判断：模型会换代，
> 而「哪条设定在第几章被丢弃」「这句引证在原文里不存在」「这次锁定绕过了哪条 must」
> 这些证据一旦能被机器钉住，就能一届一届攒下去。本仓库里最重的部分正是这套底座：
> 提示词装配基线、引证验真、确定性复检、把回执与承诺对上账的门禁。它不性感，但它是复利。
- 🗂️ **条目化世界书**：设定按条目登记、按锚点激活、按预算注入 —— 长设定不会在 500 章后被截成一团糊
- 💰 **成本架构（v0.19.5）**：卷级会话栈（长篇命中率 80.4% → 94-96%，理论终点推算值，非长跑实测）+ 静态指令冻结
+ 台账 JSON 补丁（追踪输出 -43%，不再随章数截顶）+ 补尾式扩写（-81%）+ 摘要降频
（-68%）+ 清算级联 + L0 账本对照 —— 同跨度对照每章总成本 -29%
- 🧭 **Agent 操作层（v0.19）**：在共写对话里说「回退到去味之前」「重写第2章，铺垫足一点」，
Agent 真的去操作应用（断点回退/细纲重生成/章节重写/设置开关），破坏性操作先归档留底（`pipeline_debug/agent_tools/`，恢复入口见「关于 → 打开数据目录」）
- ✍️ **人工审校模式（v0.19）**：作者在定稿门里填阻断问题、AI 只负责修复——审校模型调用归零
- ⛓️ **代价必须兑现**：正则契约（must 级）+ 因果对账，金手指越界直接判阻塞
- 🤝 **共写档六阶段（v0.20 起为默认档）**：立项 → 核心设定 → 剧情总纲 → 世界书与正则 → 单元细纲 → 正文写作，每阶段可与 Agent 讨论后「确定」定稿；全自动档保留为批量补章路径（切换在流水线面板）
- 🔍 **三层审校**：本地 L0 确定性预检（零成本）→ 6 维 LLM 终审（引证验真 + 3 票投票降噪）→ 反馈环定向修复
- 🔄 **剧情反哺**：正文里冒出来的新设定回写世界书/伏笔表，并约束后文 —— 而不是各写各的
- 📥 **外部文档导入（同人文专用路径）**：设定集 TXT 丢进来，Agent 只拆文档里真有的部分并逐条验真，
**预览映射表确认后才落盘**；借来的原作自动 `[常驻]` 免被预算裁掉，分歧点落成 must 契约拦住 OOC，整批可撤销
- 📜 **本书契约面板**：正则规则逐条可见、可改、可删；导入批次在同一页整批撤销 —— 契约不该是一个黑盒
- 🎨 **10 套题材预设**：修仙·凡人流 / 都市改命 / 克苏鲁 / 规则怪谈 / 无限流 / 末日废土 / 历史权谋 …，每套含 6 阶段特化提示
- 🔑 **BYOK + 全本地**：自带模型 Key，书稿、配置、版本历史全在你机器上（MIT 开源，无云端）
- 🖥️ **Windows 桌面应用**：PySide6 + QML，安装包开箱即用，无需 Python
## 它在同类里站在哪
| | 自动生成器类 | 在线商业写作 SaaS | **千笔一文** |
|---|---|---|---|
| 人的位置 | 给设定、收全书 | 对话式辅助为主 | **共写六阶段，每步可插手、可回滚** |
| 防幻觉 | 多靠模型自觉 | 多靠模型自觉 | **引证验真：编造的引证当场作废，三票定案** |
| 硬规则 | prompt 约束 | prompt 约束 | **must 契约注入每张写作 prompt + 确定性复检拦住锁定** |
| 你的数据 | 各家云端 | 平台云端 | **全本地：书稿在你的文档目录，Key 入 Windows 凭据管理器** |
| 费用 | 订阅 / 点数 | 订阅 | **MIT 开源 + BYOK，真实 e2e 写 5 章 ≈ ¥0.07**（测试脚本口径，见下） |
| 长篇一致性 | 上下文塞设定 | 对话窗口 | **条目化世界书 + 剧情反哺 + 摘要链** |
> 表里每一格都对应仓库里可运行的代码与测试——欢迎按 [## 测试](#测试) 一节自己验。
> 成本口径：¥0.07 / 5 章是 `tests/test_5ch_e2e.py` **测试脚本**实测（加速档 + 测试渠道 +
> 固定文本，非产品默认配置）；产品默认配置的量级参考是 **¥0.25/章**（v0.19.8 同书同渠道
> 13 章真跑口径，离峰，见 [CHANGELOG](CHANGELOG.md)）。两个数并存、口径不同，都为真——
> 差异来源是配置与文本，不是数字过期，详见[测试](#测试)一节的说明。
---
## 下载
| 方式 | 文件 | 说明 |
|---|---|---|
| **安装版（推荐）** | `QianBi-Novel-v<版本号>-setup.exe` | Inno Setup，per-user 安装（免管理员）；**创建桌面快捷方式**，在「设置 → 应用」里可卸载，卸载时**保留书稿** |
| **便携版** | `QianBi-Novel-v<版本号>-portable.zip` | 解压双击即用；**不建快捷方式、不写注册表、无卸载入口**（删文件夹即清除）。包内附《使用说明.txt》 |
程序与数据分开：配置/预设/日志在 `%USERPROFILE%\.qianbi_novel\`，书稿默认在
`%USERPROFILE%\Documents\千笔一文\`（新建书目时可改保存位置）。两种版本共用这两处，换着用最方便。
→ **[Releases](https://github.com/GLFzr/QianBi-Novel/releases/latest)** ·
每个版本附 `SHA256SUMS.txt`，校验后再运行。
系统要求：Windows 10/11 x64。无需安装 Python。
---
## 如何更新
升级不动你的书稿。有新版本时，**左栏会出现一个下载图标的角标**，点开是一份「更新」面板，
四条路同时摆在同一屏上——按你当时的网络处境挑一条：
| 你的处境 | 怎么做 |
|---|---|
| GitHub 连得上 | 点「下载并校验」，进度走完点「立即安装」：应用自己退出、拉起安装器、装完重开。**全程不用离开应用** |
| GitHub 连不上 | 「打开发布页」或「复制直链」，用任何你现在能用的办法（手机拷、网盘、微信传）把 `...-setup.exe` 弄到本机，然后「选择已下载的安装包」让应用对一次 SHA-256，对上了才给安装 |
| 连版本清单都拿不到 | 「导入离线清单」：把仓库根那份 `latest.json`（约 1KB）发给任意能上网的人/设备，下回来导入。之后同上一条 |
| 用的是便携版 / 源码 | 面板只给链接与哈希，**不会去覆盖正在运行的自己**（那必然失败），照旧解压替换即可 |
清单本身走四条通道依次试：自定义镜像 → GitHub raw → GitHub Pages → jsDelivr，第一条成功就停；
下载安装包时**没挂代理会自动切换到实测镜像站**（gh-proxy 等五站逐一实测：直连可达、支持断点
续传、整包 SHA-256 与官方一致），不再被 GitHub 断在半路；镜像只影响速度，字节仍由验签清单
内的 SHA-256 把关。
面板里会**逐条列出每条通道是怎么死的**（连接被重置 / 404 / 超时），你据此判断该配代理还是走离线。
系统代理会被自动读出来用，全链失败时还会**再用直连试一遍**——一个配错了的陈旧代理不该挡死更新。
### 为什么敢让你填镜像、敢让你导入手来的清单
因为「能给你推一个新版本」的人，等于「能在你机器上跑一个 exe」的人。所以多通道和签名是同一件事：
- 清单必须用**源码里 pin 住的 Ed25519 公钥**（`app/update_check.py` 的 `PUBKEYS`）验签通过；
- 安装包的 **SHA-256 必须与清单一致**，本地手选的文件也一样先算哈希再比；
- 两条任何一条没过，面板上**根本不会出现「立即安装」**——那份清单只会被显示出来给你看，
应用不会照着它下载或执行任何东西。安装包地址与面板里替你打开的链接**只认 https**，
`file://` 与网络路径直接拒；清单那一侧允许 http（真正兜底的是签名，明文最多让它晚一步拿到），
你自己填的局域网镜像也允许，但它下回来的每个字节照样过 sha256。
### Windows 弹「已保护你的电脑」
安装包**没有代码签名证书**（独立项目的证书年费不划算），所以从浏览器下载后双击，
SmartScreen 会拦一道蓝底提示。那是缺证书，不是文件坏了：点 **「更多信息」→「仍要运行」**。
不确定就核对一下 SHA-256 与面板/Release 页列的是否一致——一致就是我发布的那个文件。
开机自动检查**默认开启**：每次启动最多一个请求，下载一份约 1KB 的公开版本清单，
24 小时内不重复问（间隔可在面板里改成 6/12/24/72 小时），**不上传任何内容**（不带书名、不带配置、不带 Key），在面板里可关，
关掉后启动阶段零请求。详见 [docs/PRIVACY.md](docs/PRIVACY.md)。
「不会吃掉旧数据」这件事是有机器保证的，不是靠提醒：
- 安装器**只往程序目录写文件**（`%LocalAppData%\Programs\QianBi-Novel`），书稿与配置都在它之外；
- 覆盖安装前先清空上一版程序树，不留新旧模块混杂的残留；
- 若你把安装位置改成装着书稿或 `config.json` 的目录，目录页会**当场拦下**不让继续；
- 卸载只删程序文件，配置与书稿原样保留；
- 新版读旧 `config.json` 按键补齐，看不懂的键与你自建的连接档案都保留；配置万一损坏，
先另存为 `config.json.broken-<时间戳>` 再回落默认值，不会静默丢弃。
除你自己在应用里的操作外，没有任何后台任务会改你的书稿。
备份就是把上面两个目录拷走 —— 只拷 `.qianbi_novel` 会丢掉全部书稿。
---
## 两种档位，同一套内核
### 自动档 —— 你定方向，AI 跑完全程
```
立项 → 核心设定 → 全书大纲 → 章节细纲 → 〔每章微循环 ×N〕 → 完本
```
每章微循环：
```
① 上下文组装 核心设定 + 题材预设 + 条目化世界书 + 正则契约 + 细纲 + 场景卡
+ 前 3 章摘要 + 角色状态 + 未回收伏笔 + 上一章结尾
② 草稿生成 写作槽，流式（thinking → 生成 → 完成，可暂停阅读已生成部分）
③ 字数闸门 本地判定，不足扩写 / 超标压缩，带防注水约束
④ AI 味扫描 本地正则，零成本
⑤ 去味改写 最多 2 轮
⑥ 6 维终审 审校槽，L0 预检先行；PASS 快速道（干净章 3 票→1 票）
├─ PASS / PASS-WITH-NOTES → 可锁定
└─ REJECT → 反馈环（根因溯源 → 定向改稿 → 再审，3 轮熔断）
（或切「人工审校模式」：你在门里填阻断问题，AI 只负责修复）
⑦ 设定清算 flash 预扫 → 干净采信 / 有硬伤升 pro 只复核疑点（级联，-82%）
⑧ 定稿落库 正文 + 追踪四文件 + 摘要链 + 章级生成配置快照
```
### 共写档 —— 每个阶段都能插手
六个阶段各自与对应 Agent 多轮讨论，谈拢了点「确定」总结定稿、进入下一阶段：
| 阶段 | 对话对象 | 「确定」做什么 |
|---|---|---|
| 创建项目 | — | 立项信息落盘 |
| 核心设定 | 设定 Agent | 总结定稿 → 交接块给下一阶段 |
| 剧情总纲 | 大纲 Agent | 同上 |
| 世界书与正则 | 世界书 Agent | 逐条对账契约 |
| 单元细纲 | 细纲 Agent | 校验衔接 → 滚动生成下一批 5 章 |
| 正文写作 | 写作 Agent | 主 Agent 衔接比对 → 终稿锁定 |
外加两个角色：**主 Agent（Supervisor）** 做跨章衔接比对与范围控制，
**读改 Agent（Readback）** 揣摩你手改的意图并反推该改哪些上游。
---
## 值得单独说的几件事
### 条目化世界书引擎 `app/wb.py`
整本设定字符串塞进 prompt，是长篇写到中后期崩掉的头号原因 —— 预算不够就截断，
截断就丢规则。这里改成条目级：
- `parse(doc)` 兼容四种现存写法（粗体反哺行 / `### 名` + 属性行 / `- 名：述` / 表格行），同名条目按「归一化名#节」合并
- 每条有稳定 `id` 与 `content_hash` —— 能区分「条目还在但内容变了」
- `assemble(proj, num, budget, preset=…, phase=…, anchors=…)` 按优先级入预算：
**常驻 > 本章命中 > 近章登记 > 节权重**，返回 `activated` / `dropped` 留痕
- 选择顺序 ≠ 渲染顺序：注入按优先级挑，输出恒按文件原序（避免同一章每次读到的设定顺序都不同）
- 快速路径不变式：整本装得进预算时逐字返回原文件
### 契约与代价：正则 must 级
设定里的硬规则写成 `规则描述｜level：must｜scope：全书`。must 级规则会：
- 注入**每一张会写正文的 prompt** —— 正文生成、扩写、压缩、去味改写、局部改写。
这四步全在整章或整段重写正文，只给初稿注入契约等于让中间步骤裸写
- 要求**逐条给出本章落点**；给不出落点又与本章事件冲突时，Agent 必须先问你，不得自行绕开
- 进审校维 D 因果对账，违反即 fail
- **确定性复检**：规则里带反引号 pattern 的（`` 禁止三连感叹：`!{3,}` ``），
由 `app/mustscan.py` 零成本本地判定，不依赖模型自觉；命中的原文片段作为引证可被验真
优先级固定为：**作者显式指令 > 本书正则 must > 本书世界书 > 本章细纲 > 题材预设**。
绕过是有出口的，但它不会悄悄发生：确定性违规会拦住终稿锁定，你仍可选择强锁，
而这条违规会连同原因一起写进该章的强留痕记录。
需要说清楚的是：**注入不等于执行**。自然语言写的 must（「改命必须索回代价」）
机器无从判定，仍然只能靠 prompt 约束 + 审校裁决，是概率性的。硬闸门只覆盖
可确定的那一小部分 —— 对判不准的东西亮红，只会制造假阻断，最终把人逼成无脑点强锁。
「主角每次改命必须索回代价」这种话，不该只靠模型心情。
### 三层审校
| 层 | 成本 | 作用 |
|---|---|---|
| **L0 确定性预检** `app/core/scan.py` | 零 | 专名错乱、≥15 字重复串、数字矛盾、钩子缺失、术语漂移 —— 先拦硬伤 |
| **6 维 LLM 终审** | 审校槽 | 黄金开章 / 爽点闭环 / 金手指一致 / 因果对账 / 人物弧光 / 钩子 |
| **引证验真 + 投票** | 同上 | 每条问题必须带原文引证，规范化子串 + 种子锚定模糊匹配；**验真失败的引证降级为 marginal 且不进修复环**。k=3 投票取维级众数，平票从严 |
第三层是为了解决一个很烦的实际问题：审校模型会**编造引证**。
编出来的「原文」根本不在正文里，修复环照着改就永远改不完。
自动修复环的轮数上限由 `config.json` → `gates.review_max_rounds` 控制（出厂 3，可配 1 起效）：
每一轮是一次「六维终审 → 定向修复」往返，调大上限换更干净的收尾，但审校槽调用与 token 成本随轮数线性上涨。
### 剧情反哺
正文阶段模型常会冒出细纲里没写的新设定。反哺链把它接住：
```
锁定章节 → MemoryBackflowWorker 提取
├─ 新实体 / 新规则 → 幂等写入世界书「## 追加登记」分区（原位合并，保留首见章号）
├─ 伏笔变动 → 更新追踪表（新增去重，回收只命中未回收行）
├─ 偏离点 → 转 marginal findings 登记
└─ 一句话摘要 → 进摘要链
```
世界书被人工改过之后，已锁定章节会收到影响提示（建议显式解锁复核），未锁定章节按新契约续写。
### 章级配置快照与「固化为模板」
每章生成时落 `正文/.annotations/第N.json`：预设、采样、分相位参数、
本章实际激活/丢弃了哪些世界书条目、每次 LLM 调用的 slot/model/prompt_hash。
**不进 state.json**，所以不会把状态文件撑爆。
队列里右键「查看生成配置…」可以看到某章到底是怎么长出来的，
满意就「固化为模板」—— 把这一章的两层参数存成用户预设，下本书直接复用。
### 成本架构：双层前缀 + 章会话（命中率 16% → 73%+，v0.18.5 旧口径；当前口径见顶部 94-96%）
DeepSeek 前缀缓存三定律（官方 KV cache 文档 + deepseek-harness 实证）：前缀按位置逐字节匹配、
静态前置动态殿后、append-only。落到流水线上是两件事：
- **双层稳定前缀**：`project_header`（题材/核心设定/约束条款/must 全文/世界书常驻条目/写作纪律，
全书逐字节稳定）+ `chapter_header`（本章细纲/全局摘要/近章摘要/角色状态/时间线/待回收伏笔/
上一章结尾与文风样本，章内逐字节稳定）——九张大模板统一 `[项目头][章头][阶段体]` 三段式，
散装注入全部收敛。实测混合命中率 57.8% → 73.2%（早期版本 16%）。
- **章会话消息栈**：一章一个会话，system=双层前缀，正文写作是首轮，后续扩写/去味/审校/
修复/追踪/摘要都是追加轮次——正文在章内只计费一次，历史前缀逐字节复用。回退闸门
（G6/G7/G8 与修复稿否决）同步截断历史，保证「最近一条章正文消息」永远指向实际正文。
- **分相位思考预算**：机械相位（追踪/摘要/去味/扩写）关思考、细纲与清算预扫 low、
审校 disabled（埋雷测试实测召回反而更高）、清算 pro 终审 high——官方确认思考 token
按输出同价计费，档位错配是最贵的浪费。
- **离峰挂机**（设置面板开关）：DeepSeek 高价时段（北京时间工作日上午/午后）自动等待、
半价时段自动续跑——挂机跑批直接省一半。
### 清算级联：质量闸门的钱花在刀刃上（-82%）
设定清算（正文 vs 世界观底册的对账）曾是单章最贵的调用：flash 首判在 high 档必然空流
（API 侧），按 F1 设计升级 V4-pro 全量复核 ≈ ¥0.18/章。v0.19 改成级联：
```
flash+low 全文预扫 → 干净（0 硬伤）→ 直接采信（软伤/收编/台账是回写型产物，无闸门风险）
→ 有硬伤/跨章矛盾 → pro 只复核 flagged 项
（输入=候选清单+引文定位片段+邻章结尾；输出=紧凑裁决+补漏权限）
```
真机对照（同 3 章固定草稿）：**清算成本 -82%**（¥0.675 → ¥0.122），pro 终审仍在环上
（确认 flagged + 可新增发现），预扫引文真实性 88%。预扫解析失败/退化仍走 pro 全量兜底，
质量上限不受损。
### 人工审校模式：你自己当审校
设置面板开启后，定稿前的门里**你填阻断问题（每行一条）**，AI 按「最小改动纪律」只修你指的
问题，修完交回复验（循环至放行或回退）。审校模型调用归零——只有你填了问题才花一次修复调用。
字数预检结果会写进门文案提醒你；修复稿的健全性守卫（拒绝修订计划/长度骤减）与自动模式同款。
### Agent 操作层：说一句话，它去操作应用
以前每个 Agent 都是一次性文本生成器，对程序零掌控——你说「回退到去味」应用无动于衷。
现在共写对话里可以直接下指令：
```
「回退到去味之前」 → 断点回退，下次启动从去味续跑（审校票清空）
「重跑第4章审校」 → 同上，章号可省略（默认当前章）
「重新生成第3章的细纲」 → 归档旧细纲并删除，下次启动自动重生成
「重写第2章，铺垫再足一点」→ 归档正文+清断点，你的指导写进阶段指导带入重写
「看看第3章正文」「现在进度怎么样」
```
- 规则层解析（中文高频表达，零成本零延迟）+ LLM 意图兜底（口语化表达，实测对抗集
理解率 44% → 89%，均 255 token/次）
- 安全纪律：破坏性操作**先归档再删除**（`pipeline_debug/agent_tools/` 留底，「关于 → 打开数据目录」可取回）；
设置修改只认白名单；**流水线运行中只放行只读操作**（防对运行中的内存状态做手术）；
执行结果回显到对话区，你永远知道 Agent 刚动了什么
- 评测体系：黄金指令集 63 条 + 对抗集 15 条（`scripts/agent_eval.py`），误触发红线 ≤1%
### 提示词装配基线（防「悄悄丢字段」）
`tests/probe_prompt_baseline.py` 在固定夹具书下录 54 个装配点 prompt 的 sha256。
改装配必须显式 `--update-baseline`，否则红。
配套 `wiring_check()` 做**正例断言**：填了值的预设字段必须出现在承载它的 prompt 里，
缺槽即 `WIRING FAIL`。动机很实在 —— 曾有一个 `deslop_extra` 字段是零调用死字段，
84–238 字的题材腔调配额从每一张正文 prompt 里静默消失，而字节基线永远测不出来。
---
## 界面
| | |
|---|---|
| **书架** 多书管理、新建时选题材预设 |  |
| **章节队列** 状态徽标、过期结论提示、待修汇总与一键修复 |  |
| **预设库** 10 套内置 + 自定义导入导出、6 阶段提示预览 |  |
| **设置** 多连接档案、写作/辅助/审校三槽位路由、采样参数 |  |
阅读器：全屏沉浸（F5）、3 主题（夜间/羊皮纸/纯白，Ctrl+T 循环）、
选中标注三色高亮 + 批注 + 灵感直通创作笔记、每章位置记忆、多书签。
版本：保存驱动 —— 只有点「保存」才产生版本（30 版/章，diff 与回退），
5s 防抖草稿暂存 + 崩溃恢复。导出 txt / epub，项目 zip 一键备份 + 每日自动备份（默认关，可在设置开启；打开项目时触发）。
---
## 从源码运行
```bash
git clone https://github.com/GLFzr/QianBi-Novel.git
cd QianBi-Novel
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
.venv/Scripts/python run.py
```
首次启动在「设置 → 连接与模型」填 API Key。
**Key 存进 Windows 凭据管理器**（`app/secrets.py`），`config.json` 里只留指纹，不落明文；
崩溃 dump、日志、遥测出口统一脱敏。
> **提示词适配范围**：内置 prompt 工程（正文/去味/审校等）按 **DeepSeek API** 的
> thinking / reasoning_effort / 参数习惯调校，所以**三个槽位（写作/辅助/审校）出厂都指向
> 「DeepSeek 官方 Flash（推荐）」行**（A14 裁决：出厂零 Pro——Pro 行仅在你显式开
> 严格清算档或自行改槽位后才可及；槽位绑定原样生效，选了 Flash 就是 Flash，无静默换型）。
> 出厂预设**不带模型名**（模型名是各家变得最快的参数，预置进去过期即误导）：
> 先把这行的 Key 填上、再从表单候选下拉（或「拉取」实时列表）选一个模型，全流程才跑得通。
> 出厂另预置 12 家 OpenAI 兼容平台（13 行连接档案，DeepSeek 有 Flash/Pro 两行）：国内 8 家
> （DeepSeek / 阿里云百炼 / 智谱 / Kimi / 火山方舟 / 腾讯混元 / MiniMax / 硅基流动）+ 国外 4 家
> （OpenRouter / Google Gemini / xAI Grok / Groq），每条地址都从本机实打过一次
> `<base>/chat/completions`，各家 hint 里写的就是实测结论（401=路径对、只差鉴权；国外几家
> 本机直连超时，需要代理）。换非 DeepSeek 模型协议上是通的，但写作质量与
> 闸门收敛不保证同一水准（换模型后建议先跑三章再看闸门判不判得住）。
> 其余中转与本地 Ollama / LM Studio 走「自定义（OpenAI 兼容）」。
> **刻意没有预置 Azure OpenAI 与 Cloudflare Workers AI**：它们分别要 `deployment_id` 和
> `account_id`，不是「地址 + Key + 模型」三份参数能表达的东西，硬塞进预设只会给用户
> 一堆调不通的连接——需要就走自定义。
> v0.18.1 下架的那两行出厂预设（`ds-v4-flash` / `ocgo-flash`）会在升级时自动清掉，**只清三样都满足的**：
> 从没被改过、没有槽位指着它、也没在凭据管理器里存过 Key。改过、在用、填过 Key 的一律原样留着。
---
## 测试
```bash
# 离线单测（无需 API Key，约 25 秒）
.venv/Scripts/python -m pytest tests/unit -q --tb=no -p no:cacheprovider
# → 1061 passed, 2 skipped（2026-09-25 实测，命令即口径）
# 离线探针舰队：真实 Bridge + QML 无头驱动，覆盖闸门/锁定/反哺/接力/导入/导出/更新等链路
.venv/Scripts/python tests/probe_agent_relay.py
.venv/Scripts/python tests/probe_word_block.py
.venv/Scripts/python tests/probe_update_ui.py
# …… 共 50 支 probe_*.py（探针舰队进 CI 门禁）+ 单测构成发布闸门；probe_models /
# probe_flash_reasoning 等少数几支是真实 LLM 实验，需要 QIANBI_TEST_KEY；probe_packaged
# 由发布流水线带 --exe 调用，probe_ui_gallery 产出全量 UI 截图
```
| 探针 | 覆盖 |
|---|---|
| `probe_prompt_baseline.py` | 54 个装配点 prompt 摘要 + 预设字段接线正例断言 |
| `probe_qml_compile.py` | 42 个 QML 组件逐个编译（属性写错会让整棵界面树静默加载失败）|
| `probe_agent_relay.py` | 共写接力编排：每 Agent 只注入上环节产物、Supervisor 上下文上限、锁定触发点 |
| `probe_word_block.py` | 字数闸门、锁定拦截、强锁留痕、陈旧队列 |
| `probe_backflow_chain.py` | 反哺全链路：幂等、外部直改、缺细纲、中断、补跑队列 |
| `probe_import_ui.py` | 外部文档导入：只拆实有 → 预览映射 → 勾选才落盘 → 契约页整批撤销 |
| `probe_update_ui.py` | 更新链路 46 项（零真网络）：多通道回退与逐条死因、未验签不给安装按钮、离线导入清单、本机包对哈希、24h 限流、设置白名单、面板溢出 |
| `probe_conn_delete.py` | 连接删除 20 项：两步确认才删、Key 随连接一起从凭据管理器消失、只剩一条不许删、退役出厂行的三条删除护栏 |
| `probe_about_ui.py` | 关于页：书稿/配置路径与 Bridge 一致，「更新…」入口把面板开起来 |
| `probe_packaged.py` | 打包态资源清单审计 + 开发态/打包态装配摘要对拍 |
| `probe_panel_fit.py` | 六面板横溢/纵溢/压扁/越界（设置页含「确认删除」那一态，它是行内最宽的文案）|
**真实 LLM e2e**（需 Key，约 20 分钟）：
```bash
.venv/Scripts/python tests/test_5ch_e2e.py
```
> **两个成本数并存，口径不同，各自为真**（N-35 收口口径）：
> - **≈ ¥0.07 / 5 章**：`test_5ch_e2e.py` 测试脚本口径 —— 加速档 + 测试渠道 + 固定文本，
> 目标是低成本冒烟，**不代表产品默认配置**；
> - **≈ ¥0.25 / 章**：v0.19.8 同书同渠道 13 章真跑口径（离峰，含完整审校/清算/反哺链），
> 见 [CHANGELOG](CHANGELOG.md) v0.19.8。
>
> 差异来源是配置与文本不同，不是数字过期——不存在单一「真实成本」，按你要复现的东西选口径。
---
## 项目结构
```
app/
wb.py ★ 条目化世界书引擎（parse / assemble）
importdoc.py ★ 外部文档导入引擎（分段拆解 / 验真 / 落点映射 / 整批撤销）
mustscan.py ★ 正则 must 契约的确定性复检（零成本）
secrets.py ★ API Key 入凭据管理器 + 统一脱敏
selftest.py ★ 打包态自检（导入/资源/装配摘要/QML 装载）
usage.py token 与成本计量
update_check.py 多通道清单检查 + Ed25519 验签
update_mirrors.py 无代理镜像自动切换（五站实测表）
offpeak.py 离峰挂机（v4 分时价 peak 等待）
usage.py token/缓存命中/相位/推理 token 计量
singleinstance.py 单实例锁（二次启动唤起既有窗口）
crash.py / logger.py / diagnostics.py / telemetry.py
config.py 连接档案 / 槽位路由 / 闸门策略
project.py 项目读写（设定/大纲/正文/追踪）
deslop.py 本地 AI 味扫描（零成本）
export.py txt / epub 导出
llm/ OpenAI 兼容客户端（流式/重试/退化档）+ 服务商预设
prompts/ planning / writing / review / memory / co_writing / scene_cards
core/
orchestrator.py 调度（QThread / 断点续跑 / 暂停停止 / 离峰挂机闸门）
stages.py 阶段实现 + 6 维审校 + 反馈环 + 分相位思考预算 + 章会话调度
chapter_session.py 章会话消息栈（同章阶段共享前缀，正文只计费一次）
shared_prefix.py 双层稳定前缀（项目头 + 八节章头，缓存命中主力）
canon_audit.py 设定清算（三分类对账 + flash-low 预扫→pro 疑点复核级联）
agent_tools.py Agent 操作层（6 工具 + 中文指令解析 + LLM 意图兜底）
scan.py ★ L0 确定性预检（双端镜像）
state.py 断点状态 / 陈旧判定 / 需人工标记
gates.py 字数 / AI味 / 审校闸门 + 字数预检
memory.py 摘要链、追踪、反哺写回、世界书修正提案
versions.py 保存驱动版本（30 版滚动 + diff）
co_writing.py 共写档状态机
co_dialogue.py 共写 Worker（Dialogue/Summarize/Readback/Supervisor/Backflow）
presets/ 10 套 v2 题材预设
ui/
bridge.py Python↔QML 桥
qml/ Main + 6 面板 + Theme（3 主题）
components/ 25 个组件（ReaderView / CwDialogueDock / ImportDialog / ReviewIssueDialog / …）
scripts/
build_release.py 一键发布流水线（质量闸门 → 版本资源 → 打包 → 冒烟 → 摘要对拍）
tests/
docs/ 设计与计划文档、隐私说明
```
**一本小说在磁盘上**（用户目录，全部本地）：
```
<书名>/
设定/ 题材定位 · 选题信息 · 世界书 · 正则 · 简介与标签 · 世界观/角色/势力/
大纲/ 大纲.md · 单元总纲.md · 细纲_第NNN章.md
正文/ 第NNN章_章名.md
.versions/ 保存驱动版本
.annotations/ 章级生成配置快照 + 批注
.drafts/ 防抖草稿
追踪/ 角色状态 · 伏笔 · 时间线 · 上下文 · 章节摘要 · 全局摘要
pipeline_state.json
```
---
## 开发
```bash
.venv/Scripts/python scripts/build_release.py # 完整发布流水线
```
发布流水线带**六道不可跳过的质量闸门**（提示词装配基线 / QML 编译 / 视觉令牌 /
私钥扫描 / 更新链路 / 连接删除；TUI 退役后「共享层同源」闸门已随之移除——§9-Q2 裁决），
发布前清单见 [docs/release_checklist.md](docs/release_checklist.md)。
---
## 隐私与安全
- **数据不出本机**。书稿（含版本历史 `.versions/`、草稿 `.drafts/`，都在书稿目录内）
默认在 `~/Documents/千笔一文/`；配置、预设、日志在 `~/.qianbi_novel/`；除模型 API 调用外没有云端。唯一的自动对外请求是检查更新：开机默认开、
24 小时最多一次，只向 GitHub（或你自填的镜像）**下载**一份约 1KB 的公开版本清单，
不上传任何内容，在「更新」面板里关掉之后启动阶段零请求。
- **API Key 存 Windows 凭据管理器**，配置文件不落明文；日志与崩溃 dump 统一脱敏。
- **遥测默认关闭**，且只写本地文件、不上传。详见 [docs/PRIVACY.md](docs/PRIVACY.md)。
- 依赖与字体第三方声明见 [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md)。
- 安全漏洞报告渠道见 [SECURITY.md](SECURITY.md)。
---
## 文档
- [docs/用户手册_v1.md](docs/用户手册_v1.md) —— 面向新作者：安装、贴 Key、建书、共写六阶段、
门开关、导出与备份、报障包、FAQ 与术语表
- [docs/0.20.0_收口裁决记录_v1.md](docs/0.20.0_收口裁决记录_v1.md) —— 0.20.0 收口全部遗留裁决的落档
（Wave C 取消、签名证书不买、私钥本地加密备份、命中率验收口径、成本口径标注等）
- [docs/PRIVACY.md](docs/PRIVACY.md) —— 隐私说明（数据在哪、联网行为逐条列出）
- [examples/README.md](examples/README.md) —— 示例项目结构与导入说明
---
## 优化战役史：每一轮做了什么
这个项目的迭代是按「战役」组织的——每轮一个主题、一轮评测、一份公开报告
（`docs/` 下全部留档，含失败与负优化，不只写成功）。
### 能力轮 —— 把「写得像网文」变成可度量的质量体系（v0.15–0.18.4）
目标：让写作质量可评估、可回归、可迭代。8 轮「写 → 审 → 修」迭代把专业评审总分
从 72 分推到 86 分，单章地板稳定在 7.5 以上：
- **审校体系**：6 维终审（黄金开章/爽点闭环/金手指一致/因果对账/人物弧光/钩子），
每条问题必须带原文引证、**引证验真**（编造引证降级不进修复环）、3 票投票取维级众数
- **反馈环**：REJECT → 根因溯源（问题定位到 ROOT_PROSE/ROOT_OUTLINE/ROOT_SETTING 层）
→ 定向改稿 → 复审，3 轮熔断标人工
- **记忆层**：全书连续性台账（人物/物件/制度/时间四表）、拍点级对表 beat_check、
设定清算三分类（违反/收编/台账回写）、日历偏差提案（正文历法 vs 案发日历）
- **去 AI 味红线**：15 条结构指纹（视线词配额/否定刹车句/设定朗读症/台词可区分…）+
本地正则零成本扫描 + 逐章口头禅黑名单
- **10 套题材预设**：每套 6 阶段特化提示 + 分相位采样参数，字数闸门与预算纪律
### 用户体验轮 —— 缓存架构 + 成本可观测（v0.18.4–0.18.5）
目标：让默认配置的成本降下来、让花的每一分钱看得见：
- **双层稳定前缀 + 章会话**（见上文成本架构节）：混合缓存命中率 **16% → 73.2%**（v0.18.5 旧口径），
审校票延迟 170s → 43s
- **分相位思考预算**：机械相位关思考（墙钟 200-600s → 秒级）、细纲 low（输出 35-41k
→ 5-7k tok/笔）
- **成本可观测**：usage.jsonl 逐笔记录 hit/miss/phase/reasoning token，缓存命中率、
推理占比全部可见
- **公测数据包**：匿名导出使用数据（不含书稿/提示词/Key），用大家的数据驱动迭代
### 成本实验战役 —— 用实验说话，负优化也公开（v0.18.6–0.19.0）
方法：同源种子书克隆 + 变量数据化预设 + **埋雷测试**（在正文植入已知缺陷做标准答案）
+ 固定草稿确定性对比。10 个实验（E1-E10）逐个量化，结论全部留档：
- **留优**：清算级联（-82%）、审校 disabled（埋雷召回 4/4 vs 3/4、成本 -88%）、
审校 PASS 快速道、细纲 low
- **弃劣（同样重要）**：prose=low（+5%，正文变弱下游修复链吃回）、prose=medium
（+64%，推理失控）、清算 medium/disabled（检出缩水或引文编造）、审校 low
（灾难性假阳性）——「降档」不是普适的省钱开关，**任务性质决定档位**：
对照检查表任务（审校）不需要推理，跨章事实对账任务（清算）推理是命根子
### Agent 化 —— 从「生成文本」到「操作应用」（v0.19）
- L1 规则指令层（零成本确定性）→ L2 LLM 意图兜底（对抗集理解率 44% → 89%，
均 255 token/次），误触发红线 0%
- L3 常驻操作助手等公测使用率数据；L4 全自动总控**明确不做**——作者掌舵是产品定位
- 评测体系沉淀：黄金指令集 63 条 + 对抗集 15 条，每条误判自动转为回归用例
---
## 已知边界
诚实列一下，避免踩坑：
- **仅 Windows 打包**。Linux/macOS 需自行从源码跑，未做发行验证。
- **提示词按 DeepSeek 调校**。换其他家模型时闸门判定会更抖（审校相位已统一低温运行来缓解）。
- **长请求受端点稳定性影响**。部分兼容网关在单次输出较长时会断连，客户端有重试与退化档，
但换模型/换网关仍可能遇到。
- **流水线没有上游重做环**。改设定后需要手动解锁受影响章节重跑（共写档有对应入口）。
- **`is_chapter_need_human`** 由反馈环写入，但自动档目前不消费它（只作队列标记）。
- 3 轮反馈环不收敛的章节会标记待人工，不会无限重试。
- **外部文档导入是「摘录 + 映射」，不是「读完整本书」**。长文按 3 万字分段、单次最多 8 段；
只处理文档里真写得有的内容（拆不出来的落点会明确告诉你缺什么），模型补写出来的一律判不通过。
- **更新链路还剩三件事做不到**：① 安装包**没有代码签名证书**，双击必然撞 SmartScreen 的
「Windows 已保护你的电脑」，要手点「更多信息 → 仍要运行」；② 「立即安装」只对**安装版**开放，
便携版与源码态不会去覆盖正在运行的自己（那样必失败），只给链接与哈希；③ 51MB 的安装包
**变不出带宽**——应用能做的是把「有没有新版」降到一份 1KB 的多通道清单、把离线路径做成
一等公民、把完整性钉死在签名与哈希上，而不是宣称连不上也能下包。
---
## 版本
版本号唯一来源是 `app/__init__.py` 的 `__version__`。
完整变更见 [CHANGELOG.md](CHANGELOG.md)。
| 版本 | 主题 |
|---|---|
| **v0.20.0** | **共写档设为默认档**（新装/新项目默认六阶段共写，老用户档位原样保留）+ 演示引导（无需 Key 看懂全流程）+ **对话全量落盘**（书内 `.dialogue/`，本地可关不上网）+ **一键报障包**（含书稿档 / 仅日志档，Key 与家目录自动脱敏）+ 门停靠详情（拦哪条 / 当前值 vs 阈值 / 继续与回退各发生什么）+ 修复环上限显式迁移（N-06）+ UI 质感与确认感三层收口 + lieflat 去 AI 味规则源集成（实验性，默认未启用） |
| **v0.19.9** | **槽位绑定原样生效**：选了 Flash 一定是 Flash——无静默升级/换型/过滤（Pro 计费考古定案后的模型选择契约）+ 出厂三槽改指官方 Flash（A14：出厂零 Pro）+ 输出治理收尾（新书 3 章试跑较 0.19.7 世代 -53%） |
| **v0.19.0** | **成本架构升级 + Agent 操作层**：清算级联（flash 预扫→干净采信/有硬伤 pro 只复核疑点，-82%）+ 审校思考档重置（埋雷测试：关思考召回 4/4 vs 3/4，-88% 成本）+ **人工审校模式**（作者填问题、AI 只修复，审校调用归零）+ **Agent 操作层**（共写对话下指令→真实回退/重生成/重写，规则层+LLM 兜底双层解析，误触发红线 0%）+ PASS 快速道默认开 + 细纲思考降档 |
| **v0.18.5** | 无代理镜像加速下载（五站实测自动切换，SHA-256 仍把关）+ 写作缓存三包深修（章级共享上下文正式生效、审校投票重排、章会话消息栈、细纲思考降档、离峰挂机、reasoning 用量口径）——混合命中率 57.8% → 73.2%，审校票延迟 170s → 43s |
| **v0.18.4** | 公测版起点：双层稳定前缀架构（命中率 16% → 57.8%）+ 记忆层（连续性台账/拍点对表/设定清算/日历偏差提案）+ 原作世界书导入（同人档）+ **公测数据包**（匿名导出，不含书稿/提示词/Key） |
| **v0.18.1** | 更新链路成型：开机自动检查（默认开 + 24h 限流）+ 左栏常驻更新图标 + 四通道清单与逐条死因 + **Ed25519 验签才准执行** + 离线清单导入/本机包对哈希 + 安装版一键升级（下载→校验→退出→拉起）；连接预设从 3 家换成 12 家实测平台 |
| **v0.17.0** | UI 成熟化：设计系统 2.0（明度阶梯/控件全自绘/语义色降噪）+ 弹窗遮罩与字体重叠五连修 + 阅读器标题层级与中文引号 + 面板零边距根因修复（ScrollView 忽略 Layout.margins）|
| **v0.16.0** | 外部文档导入（同人文路径：只拆实有 · 预览映射 · 整批可撤）+ 本书契约面板 + 更新通道两条路径不吃数据 + 流式可中断与思考过程可见 + 界面描边与细纲批次控制 |
| v0.15.0 | 世界书条目化激活 + 预设组装层（工艺卡/分相位采样/章级快照/固化为模板）+ 审核三层 + 剧情反哺 + 字数闸门 + 打包一致性门禁 |
| v0.14.0 | 商业化封装：安装器与便携包、单实例锁、崩溃处理、Key 入凭据管理器、检查更新、首启向导 |
| v0.13.0 | TUI 优势功能完整移植：10 套 v2 预设、6 维终审 + 反馈环、6 类场景卡、3 主题 |
---
## License
MIT License © 2026 GLFzr