这是一份写给第一次上手的人的完整说明。3Q工具箱-AI写作是一个单机本地运行的 AI 网文写作工作台—— 你定立意和大纲，AI 写正文；它同时帮你管住「写到第五十章还记得第三章埋了什么伏笔」这件事。 稿子存在你自己的电脑上，但生成内容要联网：模型跑在你配置的云端服务商那边。 装上就能免费体验 45 天或 100 章，不用先联系任何人要激活码，照着本页做就能跑起来，不需要懂编程。
是什么：一个帮你写长篇中文网文的工作台。它把写作拆成四层——设定库 → 分卷大纲 → 章纲 → 正文，每一层的产出你都能改，改完再往下走。
不是什么：不是一键出书。全自动生成的百万字没人读得下去。这个工具的设计前提是你改，它写。
装在哪：你自己的电脑。程序只绑定 127.0.0.1，不监听外网；小说全部存成本机的 SQLite 文件。唯一的对外通信是把提示词发给你自己配置的模型服务商，没有任何中间服务器。
设定锁定、人物状态按章回溯、伏笔台账、一致性校验，四道闸门专门对付「写到后面自己都记不清」。
正文一个场景一个场景生成并落库。超时、断网、余额不足之后再点一次，从断的那个场景接着写，钱不白花。
自定义规则附加到每一次模型调用；投喂自己的旧稿提炼文风卡，写正文和润色都照它来。
四个角色（planner / writer / polisher / checker）各自路由到不同服务商，贵的模型只用在决定骨架的地方。
下载的是安装程序（Setup），双击跟着向导走就行：选安装目录（默认在系统盘的 \3Q工具箱-AI写作，可以改）、勾桌面 / 开始菜单快捷方式，装完点桌面图标就能开。不用装 Python 或 Node，也不用配环境。macOS（苹果系统）暂不支持。
启动后没有黑窗口、不是浏览器标签页，几秒直接弹出一个独立的应用窗口（原生窗口，没有地址栏和标签页）；极少数机器上缺少它依赖的浏览器内核时，会退回系统默认浏览器打开，用法一样。
别直接删安装目录、别把 exe 单独拷走。你的稿子和设置都在安装目录里：data\（一本书一个 .db）、config.json、out\（导出与备份）、logs\。要卸载走 Windows「设置 → 应用 → 已安装的应用」（或控制面板的「程序和功能」）——卸载只删程序，默认保留你的书稿；反过来直接删目录会把稿子一起删掉。详见第十六节：数据存在哪、怎么迁移。
首次启动不用填任何东西。程序会自动开通免费体验：45 天或 100 章， 直接进工作台开写，不会拦在激活窗口上。界面顶部有一行小字告诉你还剩几天、还能生成几章。
想长期用再去要秘钥：点顶栏「去激活」，粘贴秘钥点「激活并进入」。秘钥只校验它本身， 不和软件版本绑定——以后升级程序不用重新激活。
通过后秘钥保存在本机用户目录，之后每次启动都会自动向授权服务校验一次，有效性结论不落本地。到期前 15 天内，每次启动都会提示续期，可以关掉继续写。到期时间显示在顶栏版本号下面，剩 15 天内会标黄。
常见拒绝原因：秘钥无效（拼错或不存在）、秘钥已被禁用、秘钥已过期、 连不上授权服务（检查网络，校验必须联网）。
想换一把秘钥：点顶栏版本号下面那行到期时间，会弹出换秘钥窗口。这个窗口和首次激活的那个不一样——它能取消，取消后原来的授权分毫不动，工作台也不会被退回激活界面，手上的内容不会丢。输错了只提示错误，不会把你踢出去。到期提醒弹窗上也有「换秘钥」按钮，另一个「知道了」是关掉提醒继续写。
右上角「模型设置」→ 服务商 cloud 那行「编辑」→ 粘贴 Key → 保存 → 点「测试连接」。不配 Key，程序自己没法生成任何内容——但你可以用左栏的「免费网页问答」手动问模型（见第五节），那条路不用 Key。详见第四节。
左栏填书名和一句话立意，保存后点「属性」选题材 / 情节 / 情绪 / 时空标签。这几样是后面每一次生成的底座。
左栏「生成世界观与人物」。产出后仔细读金手指的规则、代价、上限，不满意就改，满意的锁上。
中栏三组按钮按顺序点。章纲一次生成 3–5 章，逐章改完再写正文；先写一章，读完再决定要不要批量往下。
这三步在编辑器和右栏，是长篇不崩的关键，不要攒到十章再做。
不用先要秘钥。第一次启动程序就自动开通免费体验： 45 天或 100 章，先到先得，期间功能是完整的—— 生成世界观、出章纲、写正文、AI 味自查、导出，全都照常用。
之所以敢这么给：你的 AI 调用走的是你自己的 API Key， 体验期消耗的 token 从你自己的平台账户扣，我们这边一分成本也没有， 所以没必要用激活窗口把人挡在门外。
到期之后会怎样：只停用 AI 生成。已经写好的稿子照常查看、编辑、导出， 一本都不丢。界面顶部会显示还剩几天、还能生成几章，随时可以激活接着写。
免费体验的两条边界：
秘钥不在任何页面上自助购买， 必须联系站长获取——下面两条路都行，选一条就够，微信通常回得更快。
① 微信公众号（推荐）：在微信里搜索公众号 「3Q工具箱」， 关注后直接发私信说明要秘钥即可。想再体验一阵也可以直接要一张 体验码（短期秘钥），不用等。
② 站长邮箱：bragg_chen@163.com （页面最底部也有一份）
不用再报版本号。早期秘钥与软件版本绑定校验，说错版本会拿到一把用不了的秘钥； 现在只校验秘钥本身——软件升级后不用重新激活，换版本也不会突然用不了。
这个工具本身不含 AI，它调用云端的大模型来写，所以每一次生成都要联网。你需要一个 API Key，相当于账号密码。
还没申请 Key 或额度用完时，可以先走另一条路——左栏的「免费网页问答」：程序在你自己的浏览器里打开网页版模型，你提问、回来一键取回答案，不用 Key、不额外花钱。见第五节。
以 DeepSeek 为例：打开 platform.deepseek.com → 注册登录 → 左侧「API keys」→「创建 API key」→ 复制（形如 sk- 开头的一长串）。必须充值，否则生成时报「Insufficient Balance」。按量计费，充 10 元能写很久。
右上角「模型设置」→ 服务商 cloud 那行点「编辑」→ 把 Key 粘进「API Key」→ 保存。点「测试连接」能立刻验证通不通，不花钱，还能看到该端点支持哪些模型名。
填完立刻生效，不用重启。界面上只显示 sk-***后四位，完整 Key 不会再回到页面。
data\keys.json，明文。把整个 data\ 目录发给别人等于连 Key 一起给出去；单独发某一本 .db 不含 Key。
打开 PowerShell，粘贴这三行回车（输入 Key 时屏幕不显示字符是正常的）：
$k = Read-Host '粘贴你的 API Key' -AsSecureString
$p = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($k))
[Environment]::SetEnvironmentVariable('AIW_CLOUD_KEY', $p, 'User'); Remove-Variable k, p设好后必须重启程序才生效（顶栏点「退出」，再双击启动）。界面里填的优先于环境变量；界面没填才去读环境变量。
「模型设置」→「+ 新增服务商」，填三样：
kimi、glm。角色路由里用这个名字引用https://api.moonshot.cn/v1、https://open.bigmodel.cn/api/paas/v4下面这些平台都提供OpenAI 兼容接口，所以都能直接加到「模型设置」里用。共同的申请流程是：注册 → 实名认证 → 充值 → 在控制台创建 API Key → 复制（几乎所有平台都要实名，不实名拿不到 Key 或额度极低）。
| 平台 | 官网 / 控制台 | 申请路径 | 接口地址（填进「接口地址」） |
|---|---|---|---|
| DeepSeek 深度求索 |
platform.deepseek.com | 登录 → 左侧「API keys」→ 创建 API key → 「充值」页充钱 | https://api.deepseek.com/v1 |
| 阿里云百炼 通义千问 Qwen |
bailian.console.aliyun.com | 阿里云账号登录并开通百炼 → 右上角「API-KEY」→ 创建我的 API-KEY | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 智谱 GLM |
open.bigmodel.cn | 登录 → 右上角头像「API Keys」→ 新建 → 「财务」里充值 | https://open.bigmodel.cn/api/paas/v4 |
| 月之暗面 Kimi |
platform.moonshot.cn | 登录 → 「API Key 管理」→ 新建 → 「账户充值」 | https://api.moonshot.cn/v1 |
| 火山方舟 字节 · 豆包 |
console.volcengine.com/ark | 火山引擎账号 + 实名 → 方舟控制台「API Key 管理」→ 新建；还要在「在线推理」里开通要用的模型 | https://ark.cn-beijing.volces.com/api/v3 |
| 百度千帆 文心 ERNIE |
console.bce.baidu.com/qianfan | 百度智能云账号 + 实名 → 千帆控制台「API Key」→ 创建 | https://qianfan.baidubce.com/v2 |
| 腾讯混元 Hunyuan |
console.cloud.tencent.com/hunyuan | 腾讯云账号 + 实名 → 混元控制台开通服务 → 「API KEY 管理」→ 创建 | https://api.hunyuan.cloud.tencent.com/v1 |
| 硅基流动 SiliconFlow · 多家模型聚合 |
cloud.siliconflow.cn | 登录 + 实名 → 「API 密钥」→ 新建密钥 | https://api.siliconflow.cn/v1 |
| MiniMax | platform.minimaxi.com | 登录 + 实名 → 「账户管理 / 接口密钥」→ 创建 | https://api.minimaxi.com/v1 |
| 阶跃星辰 StepFun |
platform.stepfun.com | 登录 + 实名 → 「接口密钥」→ 创建 | https://api.stepfun.com/v1 |
planner 决定骨架，值得用同一家的旗舰档。想一家搞定就用聚合平台，想省钱就 planner 和 writer 分开挂两家。| 角色 | 负责 | 调用频率 | 选模型建议 |
|---|---|---|---|
planner | 世界观、人物、分卷大纲、章纲 | 整本书几十次 | 决定骨架，值得用贵的 |
writer | 写正文（按场景） | 最多，九成费用在这 | 用便宜快的 |
polisher | 润色（勾了「生成后润色」才用） | 可选 | 中档即可 |
checker | 摘要、状态与伏笔抽取、一致性校验 | 每章 3 次 | 要能稳定输出 JSON |
界面上的「模型设置 → 测试连接」就是做这件事：逐个角色试一次真实调用，告诉你哪里不通，不必敲命令，也不消耗费用。
i，鼠标停上去有这个字段的说明（温度是什么、为什么 max_tokens 宁大勿小）。角色路由改「服务商 / 模型 / 温度 / 最大输出 token」都是改完立刻存盘生效，不用点总的保存按钮，也不用重启。
每个角色都有一项「推理」（开（思考后输出） / 关（直接输出））。四个角色默认都该是「关」：写正文、出摘要、做校验都不需要模型先写一大段思维链，开了只会多烧 token、变慢，严重时会把输出预算全花在思考上、正文一个字都不返回。
麻烦在于各家关掉思考的参数名不统一。程序已经把主流写法都备好，会按顺序自动试探、确认后记住（同一个服务商只试一次），你不用管这些细节：
| 服务商 | 关闭思考的写法 |
|---|---|
| DeepSeek 官方、火山方舟、智谱 GLM、Kimi K2、腾讯混元、百度千帆 | thinking: {"type": "disabled"} |
| 阿里云百炼（Qwen3 混合思考）、硅基流动 | enable_thinking: false |
| 自部署 vLLM / SGLang | chat_template_kwargs: {"enable_thinking": false} |
| Ollama（本机模型） | think: false |
thinking、reasoner、R1 的那些（例如 qwen3-235b-a22b-thinking-2507、deepseek-reasoner），厂商规定它必须先思考，任何参数都关不掉——换成同一系列不带这些后缀的档位。
二是中转站剥掉了不认识的参数（自建 one-api / new-api 开了严格参数校验）：让它透传未知参数，或直接连官方端点。
左栏最底部有一块「免费网页问答」。它和上面几节讲的 AI 生成不是一条路：不用你的 API Key，也不额外花钱——程序在你自己电脑的 Edge（或 Chrome）里打开网页版的豆包 / DeepSeek / 文心，你在里面照常提问，回到程序点一下「取回回答」，答案就落进你的写作材料里。中间不经过本工具的任何服务器。
适合这几种时候：还没申请 Key、额度暂时用完了、或者只是想拿某个网页版模型试试手感。
预览弹窗左上角的下拉决定这次取多少：
| 范围 | 取什么 | 什么时候用 |
|---|---|---|
| 最新一条 | 页面上最后一次回答 | 默认用它，一句一攒 |
| 全部对话 | 整页所有问答 | 聊了好几轮想一次收走 |
| 页面选中 | 你在浏览器里选中的那截文字 | 站点改版认不出回答区时最准，也最不怕改版 |
取回前会先看内容写完没有：还在流式输出的话会拦一下让你再等会儿，不会把半截话存进去。默认是「最新一条」，聊了好几轮又想一次收走时，切到「全部对话」。
data\cdp_sites.json，改了即时生效，不用升级程序顶栏固定在页顶，从左到右：
项目基础信息（书名、一句话立意、属性、文风参考）、设定库、人物。全部可手填、可编辑、可锁定。
写作流程按钮 → 分卷列表与章节树 → 编辑器（章纲 + 正文）。
任务进度、待确认状态变更、伏笔台账、一致性问题、全文检索。
几个和布局有关的细节：
✕、属性标签上的删除 ✕。找不到它们时把指针停在那一行上。书架还是空的时候，左栏只有一个「建立项目」按钮，点它才出现上面这些字段。
四组标签，限制是刻意的：
| 组 | 最多选 | 作用 |
|---|---|---|
| 题材 | 1 个 | 决定这本书的赛道（玄幻、都市、仙侠…），同时同步为项目的类型 |
| 情节 | 3 个 | 常见套路与主线形态（复仇、扮猪吃虎、群像…） |
| 情绪 | 3 个 | 整体调性（热血、压抑、轻松…） |
| 时空 | 1 个 | 时代与空间设定（古代、近未来、异世界…） |
为什么限量：标签会附在每一次模型调用上。选太多会互相矛盾，模型无从取舍，最后什么都不像。
怎么改：单选组（题材、时空）点另一个标签就是直接替换，不用先取消；多选组选满 3 个之后再点会提示你先取消一个。每组标题右边有「清空」（该组有选中时才出现），一键清掉这一组。弹窗里的改动点「保存」才入库，点「取消」全部丢弃。
自建标签：内置里没有你要的，直接输入新增。自建标签入库保存，下次打开还在，取消选中也不会消失；不需要了把鼠标移到标签上、点出现的 ✕ 删除。内置标签不可删除。
两个分区的标题行上各有一个 ⤢ 放大 按钮，点开是一个大弹窗，条目会铺成多列。设定正文长的时候在左栏全是省略号，放大看就舒服多了。
弹窗里能干的事和左栏完全一样：新增、编辑、锁定 / 解锁、删除。它和左栏读的是同一份数据，任何一边保存，另一边立刻跟着变——不存在两处对不上的问题。
世界观、金手指规则、力量体系、势力，以及你自建的任何分类。每条卡片有编辑 / 锁定 / 删除，「+ 新增设定」在分区标题行上——列表长了也不用滚到底才点得到。
身份、性格、说话习惯，以及当前状态（境界、持有物、所在地）。状态是随章节推进的：写第 50 章时，喂给模型的是第 49 章末的状态，而不是今天的最新状态——这样倒查旧章时不会被「未来的信息」污染。
这些是全书的地基，写到一半改动会让已经写完的章节「不合规」。右栏「一致性问题」里的批量校验就是为这种情况准备的：指定章号范围，逐章重新比对当前设定，把冲突集中列出来。改完设定顺手跑一遍，比等读者发现便宜得多。
入口在顶栏「规则与文风」。
有些要求贯穿全书：「不许写『他感到』」「打斗不要超过三百字」。写进设定条目 AI 不一定当回事——规则会附在每一次模型调用的提示词末尾，四个角色都受约束。
config.json）+ 本书（只影响当前这本，存那本书的 .db）写规则的建议：一条只说一件事，用「不要……」「必须……」这种祈使句，比一大段描述有效得多。
为什么是卡片而不是直接喂原文：原文几万字，每次写作都带上成本翻几倍，而且长样本会把设定和前情挤出上下文。所以只在「提炼」那一次完整读样本，之后每次只带几百字的卡片。抽象描述会丢语感，所以程序额外带一小段原文片段（默认 800 字，可调到 0），界面实时显示「每次写正文附带约 N 字」。
每条样本左边有一个开关，它管两件事。面板上会按当前开了几条，实时算出这些数字给你看：
想对比两种写法时，别把它们一起开着提炼——那会得到一张「平均风格」的卡，两种风格都被磨平。正确做法是分批提炼：先只开 A 组提炼一张，再只开 B 组提炼一张，然后在文风卡页签上用「设为生效」来回切。平时同一本书开 2–3 条风格最接近目标的样本就够了。
| 按钮 | 做什么 | 什么时候点 |
|---|---|---|
| 生成分卷大纲 | 规划 3–5 卷的走向 | 设定确认并锁定后 |
| 生成章纲 | 指定卷号，一次生成连续 N 章的剧情、爽点、章末钩子 | 分卷定了之后 |
| 写正文 | 按场景逐段写出正文，可填起止章批量写 | 章纲你看过、改过之后 |
config.json，鼠标停在输入框上会显示按当前值算出的整章字数。「写正文」工具条上勾选「生成后润色」，这一章按场景写完正文后，AI 会把整章再过一遍润色环节，只做三件事，不改剧情、不增删情节、不改人物：
卷号不在编辑范围内：改卷号要连带迁移所有章节的归属，属于「移动分卷」，不是「编辑分卷」，混在一个入口里迟早串号。
点任意一章打开，分两块：
当前在跑什么 + 实时进度（能看到「场景 2/3 完成，1566 字」）。重开界面或换台电脑打开也能重新接上正在跑的任务，不会以为白跑了。
AI 从正文里读出的人物变化（如「境界：凡人 → 灵徒一层」）。你点「并入人物状态」才生效，不会自动改你的设定。
本章埋了什么悬念、打算第几章回收、有没有回收。长篇烂尾几乎都是伏笔失控，这个看板就是防它的。
只搜已写的正文（放大镜和输入框是一体的，回车也能搜）。想知道「这个人物之前怎么说话」时很有用。搜章节名或章纲要用中栏章节树上面那个搜索框，两个是不同的入口。
对着正在选中的那一段跟 AI 来回改，直到满意。用法见第十九节。
爽点率、钩子率、章均字数；连续多章没爽点会预警。详见第十九节。
质检结论记的是当时那版正文里的原句。你用改稿、选区改写或手改更新了正文之后， 那条原句可能已经不在了——这时它不会消失，也不会被当成「已处理」，而是变灰并标上「原文已变，待复核」， 还可能带上「基于 N 个版本前」说明它是哪一版正文的结论。
cross）的问题看的是区间摘要，不跟着某一章的正文走，所以不参与这套标记；重跑跨章体检本来就是整体重算。台账里每条伏笔后面那个按钮，是告诉 AI 这条悬念已经在正文里交代完了，以后生成章纲时不用再惦记它。 它只改一个状态位，不动正文、不花钱、不调模型。
批量校验可指定章号范围，一章一次模型调用，点之前会把规模和章数摆给你看。改过设定、改过人物之后用它复查旧章。
每条问题后面有「标记已处理」：改完正文或改完设定后点它，这条从列表里消失。它只管台账好看，不会再调模型复查——想确认真的改对了，重新跑一次校验。
书名、一句话立意、属性标签（题材 / 情节 / 情绪 / 时空）。
逐条读，尤其金手指的规则、代价、上限。不满意就改，满意的锁定。
看每卷目标是否和你想的一致，不一致直接编辑那一卷。
一次 3–5 章。逐章改剧情、爽点、钩子，保存。这一步最值得花时间。
先写一章，读完再决定要不要批量往下。
产出摘要、登记伏笔与状态变更。不做这步，后面章节就没有「前情」。
右栏看问题列表，有 block 就回去改。
点「并入人物状态」，人物卡才会更新。
顶栏「导出」，可全量或按章节，格式选 .md 或 .txt。
养成两个习惯，长篇才不会崩：
1. 每写完一章，立刻做第 6、7、8 步。攒到十章再做，错误已经互相缠在一起了。
2. 改了设定之后，回头批量校验已经写过的章节。设定变了，旧正文可能就不合规了。
一本书一个文件，互不干扰。顶栏「小说」下拉框显示当前打开的是哪本。
.dbdata\ 里的历史备份都能导。会复制一份进书架，原文件不动；导入前校验这是不是本程序的小说库，选错文件会直接告诉你；书名默认取文件名，撞名自动加 -2；老版本的库导入后自动补齐新增的表生成任务正在跑时不能切换或导入，程序会让你先等它结束——避免两本书的内容串在一起。移除最后一本书之后界面会回到空白的新建状态，不会残留上一本的内容。
顶栏「导出」打开弹窗，选两件事：
# 书名、## 章节标题，留着自己看、以后再排版。# 和 > 在那里会被当成正文字符。out\ 下，文件名自动带书名和章节范围，例如 剑问沧州.md、剑问沧州_第3-8章.txt——同一本书的多次分段导出不会互相覆盖。out\，扩展名限 .md / .txt / .epub，避免误操作覆盖到别处的文件。书名.bak-年月日-时分秒.md；内容没变就不再堆备份。.db。建议每写完一卷复制一份，命名成 novel-第一卷完.db。| 环节 | 调用次数 | tokens | 说明 |
|---|---|---|---|
| 写正文 | 3 | 约 9,000 | 三个场景，每场景约三千 |
| 摘要 | 1 | 约 3,400 | 输入整章正文，输出一百多字 |
| 抽取状态与伏笔 | 1 | 约 5,700 | 输入整章正文，输出结构化 JSON |
| 一致性校验 | 1 | 约 13,800 | 输入设定 + 人物 + 正文，输出问题清单 |
| 合计 | 6 | 约 27,000 | 一章约 ¥0.08 |
按每章三千字、约 330 章算，一部百万字长篇约 ¥25。（实测数据来自 DeepSeek，折算约每百万 tokens 三元多。）
不会因为「正文越写越多」而变贵。每次调模型都是重新拼一份提示词，不是把之前的对话和已写的几十万字一路带着走。前情只带最近 N 章的摘要（默认 3 章，每章一两百字，带摘要不带正文），写场景时再加上一场景结尾的 800 字。所以写第 300 章和写第 3 章，单章的 token 基本是同一个量级。
真正会随着书变厚而缓慢推高成本的是三张清单，它们每次都全量注入：
另外两处本来就封了顶，不用担心：自定义规则启用中合计不超过 3000 字，文风参考片段由 style_excerpt_chars 限长（默认 800）。
想把它压住，四个动作：设定条目写规则和限制而不是散文；路人别建人物卡，退场的角色该删就删；每章交代完的伏笔顺手标记已回收；「前情摘要章数」不必调大，3 章通常够。想知道有没有真的变贵，打开 AI 调用台账看「按章节」那一块，第 10 章和第 100 章的 token 一比就清楚。
| 环节 | 耗时 |
|---|---|
| 生成世界观与人物 | 约 60 秒 |
| 生成三卷大纲 | 约 70 秒 |
| 生成三章章纲 | 约 40 秒 |
| 写一章正文（三个场景） | 45–75 秒 |
| 一章的摘要与抽取 | 35–46 秒 |
| 一章的一致性校验 | 35–85 秒 |
一章从动笔到校验完大约两三分钟。顶栏一直显示累计 token，对着服务商账单可以核对实际花费。
点顶栏那行「token 入 N / 出 M」就打开台账面板。每一次模型调用的角色、模型、步骤、章号、输入输出 token、耗时都在里面，分五块看：
两个口径要知道：
数据存在这本书的 llm_log 表里，跟着 .db 走；界面「用量」页就是读这张表来的。
| 提示 | 怎么办 |
|---|---|
HTTP 402: Insufficient Balance | 账户没钱，去服务商后台充值 |
Key 缺失，需设置环境变量 AIW_CLOUD_KEY | 没配 Key，去「模型设置」填，或按第四节设环境变量 |
⚠ 未在列表中找到 xxx | 模型名变了。在角色路由里改成真实模型名（「测试连接」能列出可用模型） |
返回空内容（finish_reason=length） | 输出预算被模型的「思考过程」用光。先把该角色的「最大输出 token」调大；还不行就是思考没关掉——换一个非思考档的模型，见第四节「推理」开关 |
连接失败 / 网络不可达 | 断网或服务商域名被拦。AI 生成必须联网，本机不跑模型；检查网络和代理后重试，已写的内容不受影响 |
等待响应超过 600s 超时 | 服务商那边太慢或卡住了。稍后重试；经常这样就把该角色换成响应更快的模型 |
[重试] writer 第 1/2 次失败 | 不是报错，是程序在扛网络抖动。超时、连不上、限流 429、5xx 会自动重试两次，间隔 3 秒起逐次翻倍。余额不足、Key 错误这类不重试，立刻报出来 |
端口 9000 无法绑定 | 只在你显式指定端口时出现。换一个：--port 9007 |
已有生成任务在跑，等它结束再来 | 同一时刻只允许一个生成任务，避免重复花钱。等右栏任务跑完 |
第 N 卷下还有 M 章 | 删卷时要勾「连章节一起删」，这是防手滑的闸门 |
启用中的规则合计超过 3000 字 | 先停用几条规则。这段文字每次请求都要重发 |
出了说明不了的问题，打开安装目录里的 logs\aiw.log（用记事本或 VS Code，别用 PowerShell 的 type，中文会乱码），最后几行就是现场记录。
安装目录\（默认在系统盘根目录：\3Q工具箱-AI写作\）
├─ data\
│ ├─ novels.json 书架索引：有哪些书、当前打开哪本
│ ├─ keys.json 界面里填的 API Key（明文！）
│ ├─ novel.db 第一本书
│ └─ 剑修小说.db 按书名生成的另一本书
├─ out\ 导出的 Markdown 与自动备份
├─ logs\aiw.log 运行记录（任务开始/完成/报错）
└─ config.json 模型路由与全局规则.db 里。.db——里面没有 Key。整个 data\ 发出去会把 keys.json 一起带走。data\ 和 config.json 一起拷走（Key 也跟着走，不用重填）。config.json、data\、logs\、out\ 都生成在安装目录里。所以换一台机器装好之后，把这两个东西拷回新机器上的同一个目录即可；反过来，直接删安装目录就等于删稿子——要删程序请走「应用和功能」卸载（默认保留这些文件）。out\ 和 logs\ 删掉不影响使用。界面「模型设置」改的就是这个文件。手改也行（手改要重启；界面改立刻生效）。
"roles": {
"planner": { "provider": "cloud", "model": "deepseek-v4-pro", "temperature": 0.9, "max_tokens": 12288 },
"writer": { "provider": "cloud", "model": "deepseek-flash", "temperature": 0.9, "max_tokens": 16384 },
"polisher": { "provider": "cloud", "model": "deepseek-flash", "temperature": 0.55, "max_tokens": 12288 },
"checker": { "provider": "cloud", "model": "deepseek-flash", "temperature": 0.1, "max_tokens": 32768 }
},
"scene_target_words": 1500,
"recent_summary_count": 3,
"style_excerpt_chars": 800,
"rules": [
{ "id": 1, "title": "禁用词", "body": "不要写「他感到」「他意识到」", "enabled": true }
]scene_target_words：每个场景写多少字，中栏的「每场景字数」改的就是它recent_summary_count：写新章时带几章前情摘要。带多了贵，带少了容易断片style_excerpt_chars：写正文时附带的原文片段总长，设 0 就只带文风卡rules：界面上的全局规则。本书规则不在这里，在那本书的 .db 里license_api：授权校验服务的基地址。这个地址**不在配置文件里**，写死在程序代码中（默认 https://3qtools.cn，带不带 /api 都认）——配置文件就在安装目录里，明文谁都能改，留着这个字段就能把校验指向一个假冒的服务。启动时实际使用的校验地址会记进 logs\aiw.logtemperature 是「放飞程度」：写正文 0.9 左右有灵气又不至于跑偏，润色 0.55（只修措辞不重写），校验 0.1 保证 JSON 稳定max_tokens 是输出上限，不是目标长度：按实际输出计费，调大不多花钱；设小了会被截断，思考型模型还会把预算烧在推理上导致返回空内容——所以宁大勿小data\keys.json 或环境变量），所以 config.json 可以放心拷给别人参考可以，而且不用先激活。第一次启动程序会自动开通免费体验：45 天或 100 章，先到先得， 期间功能是完整的——生成设定、出章纲、写正文、AI 味自查、导出全都照常用。
之所以能免费给：AI 调用走的是你自己的 API Key，体验期消耗的 token 从你自己的模型平台账户扣， 软件这边不代收、不加价。到期后见第三章。
在。到期只停用 AI 生成，正文、设定、人物、伏笔台账、历史版本全部保留， 编辑和导出不受任何影响。想继续生成，联系站长拿秘钥激活即可，进度接着走。 秘钥不绑定软件版本，升级后不用重新激活。
不能，也不该这样用。全自动生成的百万字没人读得下去。真正决定质量的是你在章纲阶段花的时间——章纲错了，正文再润色也是白费。
四道闸门：设定锁定后不被覆盖；人物状态按章回溯，写第 50 章带的是第 49 章末的状态；伏笔台账记录每条悬念计划第几章回收；一致性校验逐章比对。改了地基之后还能批量校验已写章节。
它们不随「写正文」自动产生。写完正文点编辑器里的「摘要与抽取」登记伏笔与人物状态变化，点「一致性校验」（或批量校验）产生问题清单。这样你才能决定什么时候花这笔钱。
点顶栏的累计 token 打开AI 调用台账：按步骤、按角色、按模型、按章节四个口径统计，还有逐笔明细。最常见的结论是「校验比写正文还贵」和「某一章反复重写吃掉了一大块」。台账只记 token 不算钱，乘你自己的单价即可。
重装同一台电脑不用；换一台电脑要。秘钥激活后会存进本机的用户目录（不在安装目录里， 也不在浏览器里），所以重启、升级、覆盖安装、换安装目录都还是已激活状态；换机器才需要重新输一次。 秘钥本身不限次数，输对就能继续用到有效期结束。 另外换到一台新机器会重新算一次免费体验（它是按机器登记的），所以在新电脑上可以先接着试用再决定要不要激活。 注意校验必须联网：每次启动都会向授权服务确认一次，连不上就进不去界面。
小说数据全在本机 .db 文件里，程序只绑定 127.0.0.1。对外通信只有两处：把提示词发给你自己配置的模型服务商，以及启动时校验授权秘钥。
断网不能用：一是启动时的授权校验需要联网，断网连界面都进不去；二是所有 AI 生成都要联网——模型不在你电脑上跑，写正文、生成大纲、摘要、校验都是把提示词发到云端再等结果。联网后照常。
「规则与文风」→ 投喂 200–50000 字自己的旧稿 → 「提炼文风卡」。卡片可手改，之后写正文和润色都按它写。想更硬的约束就写自定义规则，它会附在每一次调用上。
写正文时勾上「生成后润色」，这一章写完后 AI 会把整章再过一遍：拆长句、删堆叠的形容词和抒情排比，把直接说明情绪的句子改成动作或身体反应，消除重复用词和句式雷同——不改剧情、不增删情节、不改人物。没设文风卡也能用：有卡按卡润，没卡退回项目里的文风一句话，两者都没有就按通用规则修。润色前的旧稿自动进历史版本可回滚；整章会再过一次模型，费用约为只写正文的 1.5 倍，只想改局部用选中一段的改写工具更省。
不会。正文按场景落库，重新点「写正文」从断点继续；重开界面后右栏会自动接回正在跑的任务。
编辑器正文区右侧的「历史版本」下拉里选一版，点「回滚到此版本」。每次覆盖生成和手动保存都会把旧稿存进历史。
可以，一本一个 .db，顶栏下拉框切换。但同一时刻只允许一个生成任务，避免两本书的内容串在一起。
能。顶栏 ☀ / ☾ 按钮切浅色和暗色，默认暗色。选择记在本机，下次打开保持，连窗口标题栏也跟着变色；本页教程也跟着一起换。
往平台编辑器或手机阅读器里粘贴，选 .txt——Markdown 的 #、> 在那里会变成正文字符。留着自己看、以后再排版选 .md（按章分节）。发布前请自行确认目标平台对 AI 辅助创作的披露要求。
不收。工具本身不向任何功能收费，也没有单独的计费模块。规则类检查全部在你自己电脑上算；只有真正把请求发到你选的模型平台时才产生费用，钱由平台按官方价格从你自己的账户扣，我们不代收、不加价。详见第十九节开头。
设计上是往「改得少」那一边站的。一次最多修 6 条（喂十几条会让模型顺手把整章重写一遍，那不是修是重写）， 每一轮都会单独存一个历史版本，改坏了可以整轮回退。
还有一层保护：修完之后会复查一遍再销账——如果那条问题对应的原文还在正文里，说明模型根本没动它， 这条就不销账、留在待办清单，结果弹窗里也会告诉你有几条没修掉。宁可多留一条，也不让漏改的问题从清单里悄悄消失。
开关决定这条样本参不参与，管两件事：点「提炼文风卡」时只把开着的样本合成一张卡； 平时写正文时，额外带的原文片段只取最近投喂的 2 条开着开关的样本。
不是开得越多越好。提炼时喂给模型的样本总量固定 12000 字，在所有开着的样本之间平分： 开 1 条每条能读到 12000 字，开 3 条每条只剩 4000 字，开 10 条每条只有 1200 字—— 开太多，模型每条只看个开头就去提炼，质量反而更差。平时开 2–3 条风格最接近目标的样本就够了。 想对比两种写法要分批提炼，一起开会得到一张被磨平的「平均风格」卡。
都能删，都要二次确认。删样本只删当初那份投喂记录， 已经从它提炼出来的文风卡不受影响，照常能用（卡片是提炼的结果，提炼完就不依赖原样本了）。
删掉正在生效的那张卡时，写正文会退回项目里的「文风一句话」，不会自动替你挑另一张接替—— 换成哪张是作者的选择。只想暂时不用就关开关，开关不影响已经提炼出来的卡片。
前面十七节解决的是「第一稿从哪来」。这一节是后半程——改和查。长篇真正拉开差距的地方在这里：AI 一次能写三千字，可那三千字往往要改三十次才拿得出手。
先说钱：这一节里所有功能都不额外收费。工具本身不卖额度、不代充、不加价。只有真正把请求发到你选的模型平台时才产生费用，由平台按官方价格从你自己的账户扣（口径见第十四节）。
在正文里用鼠标拖选一段字，松开鼠标，正文上方就浮出一行工具条。
| 按钮 | 它做什么 | 什么时候按 |
|---|---|---|
| 改写 | 保持原意重写这一句 / 这一段 | 读着别扭，但意思没错 |
| 扩写 | 加细节、动作、心理，把短的写长 | 该发力的一段只剩两句 |
| 续写 | 从这里往下接 | 写到一半卡住了 |
| 补描写 | 补环境、感官、外貌 | 这段全是对话，画面感没了 |
| 具体要求 | 自己写一句话下发 | 四个预设都不对味 |
| 管理指令 | 把常用说法存成按钮 | 同一句话你每个月要敲几十次 |
几条容易忽略的：
点「具体要求」会展开一个输入框，写清楚你要什么就行，举例比术语管用：
改得更冲一点加一段打脸补上环境描写长句拆开，一句不超过 20 字留空则按默认口径处理，回车即提交。
「管理技能」里三样东西：
字数≥800、对话占比≥30%、不含：首先、其次），告诉你过没过，只针对刚改出来的那一段。存完它出现在选区工具条上，下次选中一段，一键就用，改完直接给出验收结果。
右栏「改稿对话」是针对已经选中的那一段的，而且是一轮一轮改：
什么时候用哪个：方向明确就用改写按钮，方向还在摸索就用对话。前者一次成型、便宜；后者多轮，但省得重写整段。
入口两个：
查的是平台判定「AI 粗制滥造」的那几类：遗留提示词、AI 特征词、句式重复、段落异常。
入口在右栏「一致性问题」里的「跨章体检」。它做的是单章校验做不到的事——把连续的章节放在一起，看人物掉线、能力膨胀、时间线冲突、说话串味。
什么时候值得跑：写完一卷，或者动了重要设定之后。设改动往往要连着改后面几十章，提前跑一次能捞回大半返工。
右栏「一致性问题」里攒了一堆问题时，不必一条条手改：点「修复本章」，程序把问题交给模型，让它对着原文逐条改。
右栏「伏笔台账」里，标了预计回收章、过了这个章号还没收的伏笔会带一行「已超期 N 章」。
编辑器下方「历史版本」下拉里选一个旧版，点「看差异」，就以逐行的方式列出两版之间改了什么（再点一次「收起差异」收起）。
右栏「节奏」给出三个数字和一条字数曲线：爽点率（多少比例的章写了爽点）、钩子率（多少比例的章章末留了钩子）、章均字数。
同时提交多个生成 / 校验任务时，它们排队执行。右栏任务面板会显示当前在跑什么，以及后面排队任务的位次（「排队第 N 位」）。
「模型设置」里给写作角色填「候选模型」（逗号分隔，如 deepseek-reasoner, qwen-max）：写正文的每个场景会用主模型和候选模型各生成一份，再由校验模型打分，选好的那份留下。
「模型设置」底部有一块「提示词（高级）」，把每个角色的提示词模板摊开给你改。
config.json 里的 codex_mode 可以退回全量注入（full）。导出弹窗里现在有第三种格式「电子书（.epub）」，目录按卷 → 章分级，手机、Kindle 上直接能读。三种格式怎么选，见第十三节。