ainovel-cli 立纪：一台确定性引擎与它的文件系统事实层

当大多数「AI 写小说」项目还是提示词脚本的时候，有人把长篇创作做成了一台工程机械。这一天，voocel/ainovel-cli 被完整摸底——结论是：文档、架构、测试三者高度一致，不是 README 吹牛型项目。

一、架构：确定性的铁，语义层的风

七万三千行 Go 代码（另有二万五千行测试，占比约三成五）立起的是一句话——「事实层确定、语义层自主」：用确定性代码管流程和状态，LLM 只负责创作和少数语义裁定。拆开看是五件套：

• Engine/Route 确定性路由——router.go 的 Route(state) → Instruction 是纯函数，「下一个派谁」查表决定，主循环零 LLM 开销。真正值钱的是配套的 router_exhaustive_test.go：决策表的独立镜像规格（故意不复用实现代码），万级组合穷举测试钉死行为——改流程必须先改规格再改实现。
• 三个 Worker——Architect 规划设定、Writer 逐章 plan→draft→check→commit 全自主、Editor 七维评审（含审美维度且必须引用原文举证）。
• Arbiter 语义裁定——选规划师、用户干预分诊、僵局出路，都是单次 LLM 调用完成，每次裁定落 meta/decisions.jsonl，可审计、可离线重放回归。
• 文件系统事实层——写入是 temp + fsync + rename 原子操作，章节提交是跨域可恢复的 Saga 加 checkpoint，崩溃后精确到 plan/draft/check/commit 步骤恢复，重启即读 store 续跑，没有会话状态。
• 长篇能力——卷/弧双层滚动规划（只规划前两卷，后续按需展开）、三级摘要加四级上下文压缩管线（含零 LLM 开销的 store 压缩）、四维度相关历史章节推荐，明确面向五百章以上的网文。

二、密钥审计：交给它之前的那一问

用户要把 API Key 交给它，于是一次全链路安全审计随扫描附赠。结论：泄露风险很低，密钥处理恰恰是这个项目做得最规范的环节之一。存储上，密钥只落 ~/.ainovel/config.json，写入走临时文件加 Chmod(0o600)，还有专门的测试把这个行为钉死；.gitignore 显式排除 .ainovel/。流转上，全仓日志只记 provider 名和模型名，没有任何一处记 key 或请求头；不支持从环境变量读密钥（全仓无 os.Getenv），也就没有「错误信息 dump 环境变量」这类经典泄露面；唯一的非常规网络出口是 GitHub API 检查更新，就是个 GET，不带任何用户数据。暴露面上，TUI 里已保存的 Key 只显示首尾脱敏，/diag 导出的诊断文件本来就是设计给用户贴 issue 的——小说正文和思考内容全部替换成哈希，工具参数只保留三十二字符以内的纯 ASCII 结构标识符。如实说明的残余风险三条：日志文件是 0o644（多用户机器上的卫生问题）、密钥终究会发向配置的 base_url（任何 LLM 客户端的固有属性）、作者自研的 litellm 适配库只做了结构性审计没逐行审完。一个实用建议：即使审计通过也用限额密钥——轮换 key 在这个项目里只是改一处配置重启生效的成本。

三、成品与机制：一本书一个文件夹

v0.7.9 的 Windows x86_64 成品落桌（SHA256 与官方 checksums 一致，实跑验证出版本号），顺带确认了几件事。它是纯终端程序——介绍图里那个像 GUI 的界面是 Bubble Tea 在终端字符网格上画的 TUI，标题栏里的 213×57 就是终端尺寸；「TUI + Headless 双入口」正因如此，SSH、NAS、Docker、CI 里都能无人值守跑。一本书绑定一个目录——全部产物落 {启动目录}/output/novel/：chapters/drafts/summaries/reviews 加 premise.md、outline.json、characters.json、world_rules.json、timeline，以及 meta 下的 progress/checkpoints/foreshadow/state_changes/snapshots/compass/decisions.jsonl/style_rules.json——一本书是可整体搬运的，拷到另一台机器 cd 回去启动就从最近 checkpoint 续写；目录带 flock，两个实例抢同一本书会被挡下。四个 agent 一个模型就能跑——Arbiter 不能单独配（固定用默认模型），Architect/Writer/Editor 不配就回落默认；分角色配纯粹是成本质量权衡（贵的模型只干 Writer 的活），Engine 是单 goroutine 串行循环，同一时刻只有一个 agent 在跑，不存在并发冲突。上下文窗口的三个入口与一条锁定线——TUI /config、按模型配 context_window、旧版顶层字段；不设就按「模型专属值→旧顶层值→内置注册表→200K 兜底」解析；压缩阈值锁死在 85%（window×0.85），给下一轮 prompt 和工具结果留 15% 余量，让 1M 大窗口模型也主动压而不是吃满——那是注意力衰退区。最巧的是工厂模式：Writer 的上下文管理器每章按当前模型重建、Architect/Editor 每次运行重建——所以 /config 改窗口不用退出，正在写的这章跑完（天然的安全边界），下一章就生效。

四、两份诚实的差评

扫描报告没有只唱赞歌。协议不一致——README 写 MIT，仓库里的 LICENSE 实际是 Apache-2.0，想商用得找作者澄清。发布落后于开发——main 上 9 月 26 日之后没有新提交，最新 release 是 9 月 4 日的 v0.7.9，落后 main 五周以上；10 月 11/12 还有 CI 失败记录，但那些 run 跑在其他分支上——main 本身双矩阵（ubuntu+windows 的 gofmt/vet/test/race）全绿，不误报。另有三个结构性特点被记录在案：依赖作者自研双库（agentcore 和 litellm 都是 voocel 自己的项目，生态上是单点）、强网文化导向（伏笔台账、章末钩子、去 AI 味，做英文出版向并不对口）、Go 1.25.5 门槛较高。评价一句话：如果场景是中文网文连载的批量生产，这是目前 GitHub 上完成度最高的开源方案之一；只是偶尔写短篇，它的重型架构优势发挥不出来。

真实坐标

• 架构：325 个 Go 文件约 7.3 万行 + 120 个测试文件 2.5 万行（测试占比约 35%）；2026-03-07 建库、300+ 提交、2.2k stars/441 forks；Route 纯函数 + router_exhaustive_test.go 独立镜像规格穷举；Arbiter 裁定落 decisions.jsonl 可回放；temp+fsync+rename 原子写、Saga+checkpoint step 级恢复
• 密钥审计：config.json 0o600（测试钉死）、.gitignore 排除 .ainovel/、日志只记 provider/model、无 os.Getenv、唯一出口 GitHub API 更新检查、TUI maskKey 首尾脱敏、/diag 正文思考全哈希+工具参数 ≤32 字符 ASCII；残余风险=日志 0o644、key 必发 base_url、litellm 子库仅结构审计；建议限额密钥
• 成品：v0.7.9（2026-09-04）Windows x86_64 5.6MB SHA256 校验一致；纯终端 Bubble Tea TUI（截图里 213×57 网格）；output/novel/ 一本书一目录、flock 防撞、整书可搬运、/sync 按 SHA-256 吸纳人工修订
• 机制：四 agent 单 goroutine 串行（Arbiter 不可单独配、其余回落默认）；上下文三入口+200K 兜底；压缩锁 85% 留 15% 余量；工厂模式每章/每次运行重建上下文管理器——/config 热改下一章生效
• 差评：README 的 MIT vs 实际 Apache-2.0；release 落后 main 五周（main CI 全绿、失败 run 在其他分支）；自研双库单点依赖；强网文导向；Go 1.25.5 门槛