Webnovel Writer for OpenCode — AI 长篇网文创作系统
1. 引言
在 AI 辅助写作的浪潮中，一个优秀的创作系统就像是一座灯塔，指引着作者在漫长的连载旅程中保持方向感和一致性。正如 Antoine de Saint-Exupéry 在《小王子》中所说："一个人只有用心去看，才能看到真实。事物的真实本质是肉眼无法看到的。"
1.1 为什么我们需要这个项目
长篇网文创作的核心挑战不在于"写出一章"，而在于"写到第二百章时还记得第一章的伏笔"。传统 AI 写作工具面临三个根本性困境：
| 困境 | 表现 | 本项目的应对 |
|---|
| 遗忘 | AI 忘记前文设定、角色关系、已埋伏笔 | 三层 RAG 上下文 + 故事合约引擎 + SSOT 事件溯源（伏笔/实体/世界规则全投影） |
| 幻觉 | AI 凭空编造设定、前后矛盾 | Graph-RAG 实体关系图谱 + Code Checker 硬约束阻断 |
| 风格漂移 | 长篇连载中写作风格逐渐偏离初始设定 | MASTER_SETTING 合约 + OOC 审查器 + 题材模板约束 |
在《代码大全》中，Steve McConnell 强调："良好的文档能够帮助开发者避免很多不必要的错误和困惑，提高工作效率。" 对于 AI 写作而言，"文档"就是设定集、大纲和故事合约——它们是确保 AI 在 200 章后仍能遵循初始设定的关键。
1.2 项目的主要组成部分
一个完整的 AI 写作系统，就像一支专业的编辑团队，每个模块各司其职：
| 组成部分 | 角色 | 类比 |
|---|
| 故事合约引擎 | 维护世界规则的"法律体系" | 总编辑 |
| 上下文管理 | 每章组装最相关的设定和伏笔 | 责任编辑 |
| 分层审查 | 6 维度结构化检查章节质量 | 审校团队 |
| 记忆系统 | 三层记忆压缩和检索 | 资料管理员 |
| 知识库 | CSV 结构化写作技法和命名规则 | 风格指南 |
正如《人月神话》中 Fred Brooks 所言："良好的文档是软件产品成功的关键。" 本项目的每个模块都围绕着一个核心理念：将写作知识结构化，让 AI 能够持续、一致地创作。
2. 项目标题和描述
2.1 项目名称的含义
Webnovel Writer for OpenCode —— 这个名字传达了三个关键信息：
| 要素 | 含义 |
|---|
| Webnovel | 专为长篇网文设计，理解网文的独特节奏和爽点体系 |
| Writer | 不是"生成器"，而是辅助作者完成创作的"写作伙伴" |
| for OpenCode | 基于 OpenCode 框架，与 AI 编程助手深度集成 |
2.2 项目描述
Webnovel Writer for OpenCode 是一个面向长篇中文网文的 AI 辅助写作系统。它通过分层 RAG 检索、故事合约引擎和结构化质量审查，解决 AI 在连载创作中的"遗忘"和"幻觉"问题，支持从项目初始化到平台发布的全流程。
本项目源于 lingfengQAQ/webnovel-writer，已深度重构为 OpenCode 架构，扩展了审查器体系、CSV 结构化知识库、故事合约引擎、记忆系统、发布通道等模块。v2.8 起借鉴 Narcooo/inkOS 的核心设计，引入了 SSOT 事件溯源、Observer→Reflector 双段事实提取、运行时产物持久化和真相文件 Markdown 投影。v3.0 起新增三项能力：① 一致性错误密度（CED）——审查指标从"过程指标"升级为"质量指标"，每万字一致性错误数三口径（原始/加权/阻断）；② 叙事预报（Narrative Forecast）——写章前生成 2-5 个相互隔离的候选未来分支（冲突升级/伏笔回收/平静过渡），选支后只把选中分支追加进章纲；③ 门禁分层——LLM 语义审查不再自动拒章（降级为 review_flags 观察标记，由 flag-triage 人工裁决），技术故障（节点缺失/消歧未决/审查不可解析）仍 fail-closed 拒章。
核心设计理念：不是让 AI "代替"作者，而是让 AI "理解"作者创造的世界，并在这个世界的约束下持续创作。
3. 安装和使用说明
新手指南 从安装到完成第一本书的手把手教程，每一步都有详细说明：docs/guides/getting-started.md
3.1 安装
系统要求：Node.js ≥ 22、Python 3.10+、OpenCode 运行环境。
npx @cszx/webnovel-writer-opencode init
离线包内置（1.7 MB），无需联网下载。自动检测 Python 并安装依赖。完成后在工作目录打开 OpenCode 即可开始写作。
📌 npm 版本与 AGENTS.md 的时间线（npm view @cszx/webnovel-writer-opencode version 可查当前最新）：
2.9.2-11（2026-09-18）：遗漏整批 OpenCode v2 适配，license 还误标为 MIT。勿再使用。2.9.2-12 ～ 2.9.2-15：已含 v2 适配（opencode.json、agent permissions、
写保护双入口、wn-* 诊断命令、随包 LICENSE），但离线包里没有 AGENTS.md——
OpenCode 2.x 用户装完没有任何项目说明（2.x 不回退 CLAUDE.md）。2.9.2-16 起：离线包内置 AGENTS.md + CLAUDE.md，安装时部署到工作区根
（与 .opencode/ 平级，正是 2.x 的发现位置）。装过旧版执行
npx @cszx/webnovel-writer-opencode update 即可补齐。
从 git 安装则须自己生成 AGENTS.md：
git clone https://github.com/lujih/webnovel-writer-opencode.git
cd webnovel-writer-opencode
python .opencode/scripts/webnovel.py sync-agents-md
npx @cszx/webnovel-writer-opencode update # 更新
npx @cszx/webnovel-writer-opencode uninstall # 卸载
3.2 配置 API Key
编辑 .env 文件：
# Embedding 模型（向量化章节内容）
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_api_key
# Rerank 模型（检索结果重排）
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_api_key
3.3 在 OpenCode 中使用
所有功能通过 OpenCode 的斜杠命令调用：
| 命令 | 功能 | 使用场景 |
|---|
/webnovel-init | 初始化新书项目 | 开始一本新书 |
/webnovel-plan | 规划大纲 | 设计故事结构 |
/webnovel-write | 撰写单章 | 日常写作 |
/webnovel-write-batch | 批量写作 | 集中赶稿 |
/webnovel-review | 审查润色 | 质量把控 |
/webnovel-delete | 安全删除章节 | 回退重写 |
/webnovel-rewrite | 重写章节 | 翻修烂章 |
/webnovel-heal | 修复问题章节 | 诊断修复 |
/webnovel-export | 导出正文 | 分发备份 |
/webnovel-publish | 发布番茄小说 | 平台上线 |
/webnovel-dashboard | 可视化看板 + 文风约束编辑 | 全局监控 + 文风管理 |
/webnovel-query | 查询设定 | 快速检索 |
3.4 OpenCode v2 诊断命令
除创作流程外，另有一组只读斜杠命令，用于随时核对数据一致性：
| 命令 | 功能 | 说明 |
|---|
/wn-status | 项目健康总览 | 章节进度、字数、投影一致性 |
/wn-doctor | 五类健康诊断 | 文件 / JSON / SQLite / 投影 / Python |
/wn-ssot-verify | SSOT 一致性校验 | state.json 与事件日志是否漂移 |
/wn-where | 查看当前绑定的书 | 防止写错项目（静默数据损坏） |
/wn-chapter-status N | 第 N 章阶段状态 | PLANNING→…→COMMITTED |
这些命令会把命令行的真实输出在提问提交前注入，无需你手动粘贴。它们只做只读诊断；ssot verify 发现漂移时不会自动重建——重建会按事件日志重写全部投影，需你确认后才执行。
3.5 OpenCode 版本兼容性
同时兼容 OpenCode 1.x 与 2.x：
- 1.x：≥ 1.18.29（旧版需升级——写保护插件的双入口写法从该版本起才生效）。
- 2.x：直接可用。仓库已按 V2 规范适配，配置文件
.opencode/opencode.json。
- 项目说明走
AGENTS.md：OpenCode 2.x 只发现 AGENTS.md、不再回退 CLAUDE.md。克隆后请运行 python .opencode/scripts/webnovel.py sync-agents-md 生成（CI 会校验二者一致）。注意不要把 AGENTS.md 加进 .gitignore——那是仓库的正式产物，漏了会导致模型看不到全部项目规则。
- 不要开启
formatter：内置格式化器（prettier / biome）覆盖 .md，而章节正文全是 .md，开启会重排你的作品。配置里已显式关闭。
⚠️ V1 用户的一处功能差异：opencode.json 里刻意不写 V2 的 permissions 键。
实测 OpenCode 1.18.34 遇到该键会以 rc=1 拒绝加载整份配置
（"V2 permissions are not supported by OpenCode V1"），那会让所有 V1 用户起不来。
代价是：在 V2 下，主 agent（你直接对话的那个）不再"看不见" SSOT 路径的
edit 工具，改为在运行时被拒绝。SSOT 写保护本身没有消失——
.opencode/plugins/write-guard.js 是全局 tool hook，对所有 agent 生效、V1/V2 都跑。
受影响的只是 V2 主 agent 少了一层"工具不可见"的提前拦截。
⚠️ OpenCode 会自动改写你的文件（已实测，非 bug，不必修）：
- 每次运行都会往
.opencode/opencode.json 插入 "$schema"——
恰是我们刻意避开的那个陈旧 V1 schema。仓库提交的版本不含它；
本地被写回无害（V1/V2 都接受该键）。
- 每次运行都会往
.opencode/package.json 追加 @opencode-ai/plugin 依赖
（并同步 lock）。回退后下次运行又出现，无法持久去除。本项目刻意不用它，
留着无副作用。
- 不要在 V2 里运行官方的 "Migrate my OpenCode configuration" 迁移提示词。
它会把配置转成 V2 原生形态（含
permissions），此后 V1 将无法加载
（rc=1，见上方 V1 差异说明）。双版本兼容的前提是配置保持 V1 安全形态；
V2 官方文档也明确警告"不要让 V1 指向已转换为原生 V2 形态的配置"。
3.6 提供帮助和支持
遇到问题时，可以通过以下渠道获取帮助：
Donald Knuth 在《计算机程序设计艺术》中写道："程序是为人类读写的，不是为机器执行的。" 我们的文档同样遵循这一原则——为作者而写，而非为 AI 而写。
4. 项目结构和文件组织
4.1 核心目录结构
webnovel-writer/ # 仓库根目录（OpenCode 工作区）
├── manifest.json # 文件清单（SHA256，增量更新用）
├── LICENSE # GPL v3（继承自 lingfengQAQ/webnovel-writer）
├── CLAUDE.md # 项目说明正本（面向开发者与 agent）
├── AGENTS.md # 正本的镜像：OpenCode v2 只发现这个文件
├── README.md # 项目技术概览（本文件）
│
├── .opencode/ # OpenCode 引擎核心
│ ├── opencode.json # 项目配置（v2 规范；权限 / 压缩 / 监听）
│ │
│ ├── agents/ # 6 个 Agent
│ │ ├── context-agent.md # 上下文搜集 Agent
│ │ ├── observer-agent.md # 自由事实提取 Agent（coverage-first）
│ │ ├── chapter-writer-agent.md # 章节起草 Agent
│ │ ├── data-agent.md # 数据处理 Agent（实体消歧 + 履约）
│ │ ├── reviewer.md # 审查 Agent（6 维度结构化检查）
│ │ └── deconstruction-agent.md # 作品解构 Agent
│ │
│ ├── skills/ # 16 个 Skills（webnovel-*）
│ │
│ ├── commands/ # 5 个只读诊断斜杠命令（wn-*）
│ │
│ ├── plugins/ # write-guard.js：禁止直接写 SSOT 文件
│ │
│ ├── dashboard/ # 可视化面板
│ │ ├── app.py # FastAPI 应用入口
│ │ ├── server.py # 服务器配置
│ │ └── frontend/ # React 19 前端（ECharts）
│ │
│ ├── genres/ # 6 大题材模板（38+ 细分）
│ ├── references/ # 结构化知识库
│ │ ├── csv/ # 9 张知识表 + BM25 检索
│ │ ├── writing/ # 写作技法参考
│ │ └── review/ # 审查规则
│ │
│ └── scripts/ # Python 核心脚本
│ ├── webnovel.py # CLI 统一入口（40 个子命令）
│ ├── data_modules/ # 核心数据模块（75 个）
│ └── tests/ # 测试（164 个测试文件，2349 用例）
│
└── docs/ # 文档
├── architecture/ # 系统架构
├── guides/ # 使用指南
├── operations/ # 运维文档
├── memory/ # 记忆系统设计
├── specs/ # 规格说明
└── research/ # 研究笔记
审查维度是 6 个（设定 / 时间线 / 连贯 / 角色 / 逻辑 / 项目规则）。AI 味、节奏、毒点不由 reviewer 检查，而由润色阶段处理——早期文档曾写"13 维"，代码中并不存在。
4.2 六层数据流架构
项目采用六层管道架构，每层为下一层提供经过加工的数据：
| 层级 | 名称 | 职责 | 核心模块 |
|---|
| L1 | Knowledge | CSV 结构化知识 + BM25 检索 | .opencode/references/csv/, reference_search.py |
| L2 | Reasoning | 题材路由 + 反模式排序 | .opencode/genres/ |
| L3 | Contract | MASTER_SETTING + 卷纲章纲 + 审查合约 | story_system_engine.py, story_contracts.py |
| L4 | Context | JSON 拼装写作上下文 | context_manager.py |
| L5 | Commit | 事实提取 + 事件溯源 + 投影路由 | chapter_commit_service.py, event_log_store.py |
| L6 | Projection | 5 个 Writers：state/index/summary/memory/vector | 各 *_writer.py 模块 |
正如《代码大全》中所说："一个好的目录结构可以帮助开发者快速地找到他们需要的信息，从而提高生产效率。" 六层架构的设计确保了每一层都有明确的输入和输出，修改某一层不会影响其他层。
4.3 关键子系统
| 子系统 | 核心文件 | 功能 |
|---|
| 故事合约引擎 | story_system_engine.py | MASTER_SETTING 维护 + Runtime 合同生成 |
| SSOT 事件溯源 | ssot_enforcer.py | append-only 事件日志 + 投影重建 + 一致性校验 |
| Override 合约引擎 | override_contract_engine.py | 世界规则版本化演进 + 上下文提示生成 |
| Observer→Reflector | observer_settler.py | 双段事实提取——自由文本提取+Pydantic Schema 校验 |
| 记忆系统 | memory/orchestrator.py | 三层记忆（工作/情节/语义）+ 压缩编排 |
| 审查管线 | review_pipeline.py | Code Checker 预处理 → 6 维度结构化审查（写-修循环最多 2 轮） |
| Graph-RAG | entity_linker.py | 实体关系图谱 + SQLite 持久化 |
| 追读债 / Override 合约 | index_debt_mixin.py | chase_debt 数值表（金额/利息/到期）+ 版本化世界规则合同；伏笔事件经 _sync_foreshadowing 自动建/销债 |
| 一致性错误密度（CED） | review_schema.py | 审查质量指标（区别于过程指标）：ced_raw/ced_weighted/ced_blocking 三口径，落库 review_metrics（5 新列 + 幂等 ALTER 迁移），dashboard 经 /api/review/analytics 的 ced_trends/ced_summary 展示 |
| 叙事预报（Narrative Forecast） | narrative_forecast.py | 写章前生成候选未来分支（确定性模板，不依赖 LLM），对齐度（字符 2-gram Jaccard），选支幂等追加章纲；webnovel.py forecast generate|select|list |
| 门禁分层（review_flags） | chapter_commit_service.py | LLM 语义问题不拒章、降级为 commit 里的观察标记；flag_triage.py CLI + dashboard /api/review/flags 仲裁入口（confirm/dismiss，不改 status） |
| 发布模块 | .opencode/scripts/publisher/ | Playwright 浏览器自动化（番茄 / 七猫适配器） |
5. 贡献指南
5.1 如何为项目做出贡献
贡献开源项目不仅仅是代码的贡献，还包括文档完善、问题报告、新功能建议。正如《人月神话》中所说："好的程序员不仅仅是写出能工作的代码，还需要写出能维护的代码。"
了解项目：
找到贡献的机会：
贡献代码：
- Fork 项目到你的 GitHub 账户
- 在本地开发和测试你的代码
- 确保代码遵循项目的编码标准和风格指南
- 提交 Pull Request
5.2 提交问题和拉取请求的流程
| 方面 | 提交问题 | 提交拉取请求 |
|---|
| 标题 | 明确、具体 | 清晰、描述目的 |
| 描述 | 详细、包含重现步骤 | 详细、解释更改的必要性 |
| 附加信息 | 屏幕截图、日志 | 符合编码和风格标准 |
在《代码大全》中，作者强调："代码是写给人看的，顺便给机器执行。" 提交的 Issue 和 PR 同样应该让人容易理解。
提交规范：所有提交必须遵循 Conventional Commits 格式：
<type>: <简短描述>
Co-Authored-By: AI Assistant <[email protected]>
常用类型：feat:（新功能）、fix:（Bug 修复）、docs:（文档）、refactor:（重构）、test:（测试）。
6. 许可证
6.1 选择合适的开源许可证
本项目采用 GPL v3 许可证，继承自原项目 lingfengQAQ/webnovel-writer。
GPL v3 要求任何使用、修改或分发本代码的人必须将其更改公开，并使用相同的许可证。正如 Richard Stallman 在《自由软件，自由社会》中所说："自由软件是关于自由和合作。"
6.2 许可证的含义
| 权限 | 允许 | 条件 |
|---|
| 商业使用 | ✓ | 必须开源衍生作品 |
| 修改 | ✓ | 必须使用 GPL v3 协议 |
| 分发 | ✓ | 必须附上原始许可证 |
| 私人使用 | ✓ | 无限制 |
完整许可证文本见 LICENSE 文件。
⚠️ npm 包同样受 GPL v3 约束。 @cszx/webnovel-writer-opencode 的
package.json 过去声明为 "license": "MIT"，与仓库正本矛盾——MIT 允许
闭源再分发，与 GPL 的 copyleft 义务不兼容。现已更正为 GPL-3.0-only，
并在构建时把 LICENSE 一并打进包内（GPL §4(a) 要求分发时附许可证副本）。
通过 npm 安装与通过 git clone 使用，受同一许可证约束。
7. 联系信息和致谢
7.1 联系方式
如果你有任何问题或建议，请通过以下方式联系：
7.2 致谢
每一个成功的开源项目背后，都有一个支持和贡献的社区。正如《人类简史》中所说："合作是人类成功的秘诀。"
7.3 社区文化
我们欢迎每一个人的参与和贡献，无论你的技能水平如何，都有你的一席之地。无论你是经验丰富的 Python 开发者、热爱写作的网文作者，还是刚刚接触开源的新手，你的每一次 Issue、每一个 PR、每一条建议，都是项目前进的动力。
结语
在我们的 AI 写作探索之旅中，理解系统架构是迈向高质量创作的重要一步。然而，掌握新工具、新理念，始终需要时间和坚持。从写作的角度看，使用 AI 辅助创作往往伴随着不断的试错和调整——作者和 AI 在一次次互动中逐渐找到最佳的协作节奏。
这就是为什么当我们遇到 AI 的"遗忘"或"幻觉"时，我们应该将其视为理解系统运作方式的机会，而不仅仅是困扰。通过理解上下文管理、故事合约和审查管线的工作原理，我们不仅可以修复当前的章节，更可以提升整体的创作质量，在未来的章节中保持更高的一致性。
我鼓励大家积极参与进来，不断探索 AI 辅助写作的可能性。无论你是网文作者还是技术开发者，希望这个项目能对你的创作之路有所帮助。如果你觉得这个项目有用，不妨点击 Star，或者留下你的 Issue 分享你的使用体验和改进建议。
每一次的 Star、Issue、PR 和分享都是对这个项目的最大支持，也是我们持续改进和创新的动力。让我们一起，用代码和创意，书写更好的故事。
