Structured Writer — 结构化写作智能体

模板驱动的大纲规划 + 串行写作引擎。基于 LLM 的结构化长文写作系统，支持两级 RAG 增强、事实自检、引用自动格式化、交互式大纲控制、快速范例复用、两级局部重规划，以及小说模式（章级规划→写作→章检→修复→全文三检）。

版本：3.1.0 | 作者：wUwproject | 许可证：Apache 2.0

目录

• 一、它是什么
• 二、环境要求与依赖
• 三、搭建步骤
• 四、使用流程总览
• 五、配置面板详解
• 六、模板编辑指南
• 七、大纲评审详解
• 八、关键概念与功能关联
• 九、写作控制与输出
• 十、会话管理
• 十一、常见问题
• 十二、小说模式（NOVEL MODE）
• 协议

一、它是什么

Structured Writer 是一个本地运行的结构化长文写作工具。你给它一个主题，它会：

1. 按你选定的模板（公文、学术论文、综述、新闻、报告等）规划出结构化大纲
2. 让你在浏览器里交互式调整大纲（勾选、排序、改字数、标记重点、绑定知识库）
3. 逐节串行写作，每节写作时自动注入前文回顾、RAG 参考资料、辅助知识
4. 输出完整的 Markdown 文章，支持事实自检标注与参考文献自动格式化

核心设计理念：模板决定结构，大纲承载规划，写作引擎只负责执行。

二、环境要求与依赖

后端说明（v3.1.0b1 起）：llama.cpp 直挂后端已废弃。写作/规划统一走 LM Studio（lms load → GPU → HTTP 1234）；判定模型（章检 4维 8B / 推理 R1 7B）在勾选「统一管理」时也走 LM Studio GPU，否则回退 transformers 3B/1.5B；实体/行为提取永远用 transformers Qwen2.5-3B CPU。

获取 RAG 智能体

版本要求：必须 2.2.10 及以上。Structured Writer 依赖 rag-assistant 的 /api/kb/query 外部接口（端口 8767），低版本缺少文档元数据回填能力，引用功能无法工作。

端口说明：rag-assistant 的外部 API 端口是 8767（注意不是它的 Web 界面 8765）。Structured Writer 只通过 8767 与它通信。

三、搭建步骤

方式一：Windows 一键启动

1. 确保 LM Studio（或 Ollama）已运行，且已加载一个模型
2. 双击 setup.bat
3. 浏览器访问 http://localhost:8770

方式二：手动启动

# 1. 安装依赖
pip install -r requirements.txt

# 2.（推荐）先启动 RAG 智能体的外部 API
python rag-assistant路径/main.py --no-web --api-port 8767

# 3. 启动 Structured Writer
python main.py

# 4. 浏览器访问 http://localhost:8770

对外写作 API（v1.7.0，仿 rag-assistant 8767 模式）

独立端口启动，与 Web UI 隔离：

python main.py --api-port 8777     # 同时启动 Web UI(8770) + 对外 API(8777)
python main.py --api-port 8777 --no-web   # 仅对外 API（--no-web 需自行控制 Web 不启）

两级 RAG 自动走 rag-assistant 8767 /api/kb/query；rag-assistant 离线且 cold_start=true 时自动拉起其子进程，失败降级纯 LLM 写作（不报错，返回 rag.status=degraded）。

搭建后的首次配置

端口：Structured Writer 默认 8770。可用 python main.py --port 9000 修改。

四、使用流程总览

选择模板 → 填写元数据 → 发送主题
    ↓
[规划] LLM 按模板生成结构化大纲
    ↓
[评审] 调整大纲：勾选/排序/字数/重点/RAG/辅助知识/改名/局部重规划
    ↓
[生成] 逐节串行写作（自动注入 RAG、前文回顾、事实自检）
    ↓
[输出] Markdown 文章 + 会话保存

快速调用模式（v1.7.0，跳过 LLM 规划）：

发送区选快速范例 + 输入新主题
    ↓
[加载] 直接载入范例大纲（跳过 LLM 全局规划）→ 进入评审界面
    ↓
[评审] 按需改标题 / 局部重规划（章节或子结构级）→ 开始生成

一句话流程：模板定骨架 → LLM 填血肉 → 你掌舵 → 引擎执行。范例一键复用，省掉规划，只留掌舵。

五、配置面板详解

配置面板分为以下几个区域：

1. 模型配置

2. 模板管理

3. RAG 配置

RAG 状态灯：配置页会实时显示 8767 是否在线。只有在线时，大纲里的 RAG 复选框才可用。

4. 写作参数

六、模板编辑指南

模板由四部分组成，各自独立、互不干扰：

元数据字段（meta）

内容树字段（content）

七、大纲评审详解

规划完成后进入大纲评审界面，你可以对每一节做以下调整：

辅助知识与 RAG 的区别：RAG 是知识库自动检索（系统决定查什么），辅助知识是你明确指定要写进去的内容（你决定用什么）。两者独立注入，互不覆盖。

辅助资料（子结构「+」按钮，v1.2.0）

模态框分两部分：使用指令（如"必须真实采用以下资料进行营收分析"）+ 资料文件。资料按类型三条特化管线：

大表蓝皮书取数（v1.9.0）：修复旧版"只给前 50 行标识 → LLM 猜"的漏数据缺陷。按规模分档：小表 ≤100 行 py 全量 0 次 LLM；中表 蓝皮书 + 全量行标识 1 次 LLM 选列行；大表 2 次 LLM——粗筛（py 统计生成蓝皮书 → LLM 选维度和分段）→ 精取（段内全量行标识 → LLM 选列行）→ py 在全量数据精确切。2016 年在第 10 万行也取得到。蓝皮书统计为天然算法（无领域预设）：每列唯一值分析（2~500 天然维度）→ 日期列自动聚合到年/月 → 随机列尝试文本前缀聚合 → 数值列等频分箱。

插件系统（v1.9.0，仿 RAG 形态）：子结构「+」模态框新增「数据源插件」区。插件 = 一个目录（plugin.json + 实现类），所有设置都在插件内——预置「数据库数据源」插件把连接信息（SQLite 路径 / MySQL·PG 的 host·port·账号·密码 / CSV 路径）固化一次，写作时点插件名自动取数挂载，零手填；取什么数据由「+」使用指令 + 蓝皮书取数决定，插件不预设 SQL。只读安全：SQLite 只读模式、MySQL/PG 仅 SELECT、表名白名单、凭证仅会话内存不落盘。自定义插件 = 复制 structured_writer/plugins/builtin/db_source/ 目录改配置（或放 data/plugins/<名称>/），实现 execute(inputs) → {type: table|text|image, content} 即可。

防造数据：注入表格时收集数据源数字，生成后扫描正文带单位数值，未在数据源找到的（非年份/编号）追加到"建议人工复审"清单，防止 LLM 编造数据。

输出目录化（v1.2.0）：每篇文章一个文件夹 data/outputs/<标题>_<时间戳>/，md 与图片集同目录、相对路径引用——一篇文章的所有内容在一起，方便移动/打包。

tex/pdf 生成（v1.7.0）：预览模态框「生成 tex+pdf」按钮一键转换并编译——md → .tex（新模块 md2tex.py，确定性映射：标题/表格/列表/引用/代码块 + 特殊字符转义，中文经 ctex）→ xelatex 编译（复用 latex-modular 技能的 validate.py --fix 自动修复错误；xelatex 优先，ctex 兼容性最好）。图片自动四类排版（读像素尺寸分类，标准库零依赖）：小图两列并排各 0.48 页宽、中图 0.8 页宽居中、竖大图 0.92 页宽 × 0.85 页高双约束、超宽全景（>2600px 且宽高比 ≥2.5）旋转 90° 竖放——所有阈值比例化，与纸张尺寸无关。图片块为非浮动独立块：紧跟文本流末尾下一行，空间不足自动整块换页，不与文字混排、不强制本页。LaTeX 环境自包含：未检测到引擎时自动 winget install MiKTeX，宏包自动安装（AutoInstall=1 无弹窗），MiKTeX bin 自动注入 PATH。产物 .tex + .pdf 与 md、图片同目录。

快速范例（v1.7.0）

范例 = 「大纲 + 文章」的配对快照，存于 data/examples/examples.json。它比模板多一层价值：带着真实成型的标题、要点、字数，可完全跳过 LLM 规划直接写作。

保存范例是前置计划性动作：必须在写作前点「保存范例并生成」，写作完成后没有补存入口。范例名重复时覆盖同名条目。

两级局部重规划（v1.7.0）

与整篇重规划（「重新规划」按钮）并列，但只重做目标节点：

身份继承铁律：重规划产生的新节点显式继承 _tmpl_key/show_label/is_key/rag/_logical_order（身份属性），标题/要点/字数取 LLM 新结果（展示属性）。重规划后章节字数自动 = 新子结构之和，状态重置为待写。

标题可编辑与 _tmpl_key 血缘（v1.7.0）

评审界面章节/子结构标题可直接改名。模板绑定（desc 权威写作要求、引用校验、逻辑顺序）不随标题变化而丢失——每章在规划时烙下 _tmpl_key（= 模板 content 源字段名），写作时按它查表。例如「参考文献」改名「文献引用」后，GB/T 7714 格式要求、引用自动格式化、最后写的逻辑顺序全部原样生效。评审界面总是显示标题（方便你识别），show_label 只在最终输出时决定是否打印 ## 标题 行。

八、关键概念与功能关联

1. 字数为 0 的含义

重点：字数只是约束之一，真正决定一节"写成什么样"的是模板里的字段描述。描述怎么写，LLM 就怎么写。

2. 两级 RAG 检索

开启 RAG 的节，写作时会做两次检索：

节级检索：以"文章主题 + 节标题 + 节要点"为查询 → 注入【背景资料】
子结构级检索：以"节标题 + 子结构标题"为查询 → 注入【针对性资料】

两次结果都注入该子结构的写作提示，LLM 选择性参考。

3. 参考文献自动格式化（学术/综述模板）

在模板编辑界面给某一节（必须为 leaf 类型）勾选「引用」并指定格式（如 [x]=1.）后，全流程自动：

规划时：该节字数自动设为 0，标记为引用节
写作时：正文中出现"引用自来源N" → 按正文真实引用顺序重新编号
       （只编号实际用到的来源；未用到的来源不进入编号；不存在的来源标记直接删除）
       → 替换为用户配置的格式（如 [1]）
      该引用节本身跳过 LLM 写作
生成后：仅对正文真实引用的来源构建参考文献列表（按新编号，编号保持连贯）
        → 按模板要求的格式（如 GB/T 7714）由 LLM 规范化
        → 直接替换进参考文献节；正文无任何引用时整个参考文献节删除

关联性要求：引用功能需要同时满足

1. 在模板编辑界面给该节（leaf 类型）勾选了「引用」并指定格式
2. 该文启用了 RAG 且检索到了带元信息的文档
3. rag-assistant ≥ 2.2.10（提供文档元数据）

4. 前文回顾与续写

• 前文回顾：每节写作时注入前面已写内容（按配置字数截断），保证逻辑连贯。长文建议调小回顾字数防超限
• 续写机制：写作模型输出被 token 上限截断时，自动追加"请继续写"指令接着写，直到完成或内容为空

5. 事实自检

开启后，写作模型在每节末尾用内嵌标记标注自己不确定的数据/前沿信息/案例（不额外调用 LLM）。文章末尾自动生成「建议人工复审」清单——即使全部无问题也会输出"未发现需标记的问题"。

6. 逻辑顺序 vs 输出顺序

模板的 logic（逻辑提示词）和 content 的 logical_order 控制写作顺序，大纲评审的排序控制输出顺序。两者独立——例如学术论文：引言→方法→结论先写，摘要、参考文献最后写（写作顺序），但最终文章里摘要仍在开头、参考文献仍在结尾（输出顺序）。

九、写作控制与输出

写作过程中的控制

输出

• 每篇文章输出为 Markdown 文件，保存在 data/outputs/
• 完成后可在界面查看内容、读取、删除
• 文章包含：标题 + 元数据块 + 各节正文 + （可选）事实自检清单 + （可选）参考文献列表

十、会话管理

十一、常见问题

Q：为什么关键词/摘要节输出了一大段正文而不是列表？ A：请确认使用的是 v1.4.0b3 及以上版本。旧版本存在"模板字段描述未注入写作提示"的问题。新版本中，leaf 节的字数按模板描述解析（关键词这类无字数描述的自动为 0），且模板字段描述会作为「本节要求」确定性注入写作提示。

Q：RAG 复选框灰色不可用？ A：说明 rag-assistant 的外部 API（8767）不在线。在配置面板点「冷启动 RAG」或手动启动，等状态灯变绿。

Q：写作中途报错 / 某节内容为空？ A：常见原因是写作模型被 token 截断后输出为空（推理模型思考吃光 token）。建议：提高写作模型的 max_tokens、换上下文窗口更大的模型、或把前文回顾字数调小。

Q：参考文献没有自动生成？ A：检查三点：① 模板编辑界面是否给该节（leaf 类型）勾选了「引用」；② rag-assistant 是否 ≥ 2.2.10 且在线；③ 该文是否启用了 RAG 并检索到文档。

Q：如何在公网访问？ A：默认监听 0.0.0.0:8770，局域网可直接访问。公网访问建议配合反向代理，注意配置中不要存放敏感信息。

十二、小说模式（NOVEL MODE）

选择「小说」模板（题材/篇幅为锁定字段）后进入小说模式——独立一条线，与通用写作线隔离：

流程总览

场景配置（人物/时代/地点/冲突）→ 章数组（短3-6/中8-10/长11-15）→ 因果链验证
    ↓
逐章循环：
  ├─ 章内子结构规划（S01-S05，tone/emotions/writing_prompt≥50 硬校验，确认面板门控）
  ├─ 逐段写作（上下文注入：角色表/人格/实体关系网/时间线/情绪基调/上章行为轨迹）
  ├─ 章检（4维 8B + 格式 + 逻辑 + 推理 R1）
  │   ├─ HARD/FAIL → 修复弹窗（T0 自动修 / T1 写作模型重构 / 跳过=通过）
  │   └─ 通过 → 标章 done → 下一章
    ↓
全书所有章 done → 全文三检：大纲忠实度 + 全文承诺 + 结尾收束
    ↓
三检问题 → 修复弹窗（勾选修复当场重检 / 全部跳过）→ 处理完放行

章检与全文三检

• 触发点：全文三检只在全书所有章 done 之后触发一次（"if 规划 else 全文三检"）
• 修复弹窗：勾选 = 用写作模型重构（保持文风）；不勾选/全部跳过 = 立即标记通过（跳过=通过）

小说质检配置（配置 Tab）

• 「章内检测」：4维（3B/8B）/ 格式 / 推理R1（各自独立开关）+ 自动修复 + 修复轮次
• 「全文检测」：大纲忠实度 / 全文承诺（慢）/ 结尾收束
• 「统一管理」勾选：判定 8B/7B 走 LM Studio GPU（仅 planner/writer 都是 LM Studio 时可勾）
• 「检测模型」：一键检测/安装缺失模型（8B/7B 自动下载到 LM Studio 模型库并 import）

小说项目数据

• 项目目录：data/novel/projects/{project_id}/（data/novel_state.json + chapters/<章>/*.txt）
• 章级 md 实时落盘（chapters/<章>.md），整本由手动「拼合」生成

协议

Apache 2.0 © wUwproject

更新说明

[3.1.2] - 2026-08-19

修复（整本拼合缺章——用户"五章全写完过了三检，但输出只有 1/2/3/5 缺第四章"）

• 现象：《躯体协议》5 章全写完（txt 全齐）、全文三检通过，但输出 chapters/ 只有 L01/L02/L03/L05.md，缺 L04.md——整本拼合/预览缺第四章
• 根因：章级 md 由 novel_writer 写作循环内生成（751 行）——L04 章检 HARD 后用户"全部跳过"（skip 接口只标章 status=done + hint，不生成章级 md）→ L04 done 但 md 从未写 → 输出缺章（skip 标 done 与 md 生成解耦）
• 修复：
  1. _handle_repair_skip 标 done 后，自动补齐章级 md（_ensure_chapter_md：从项目 chapters/<章>/*.txt 拼，无【别名】/末行编号残留，章标题 + 各子结构）
  2. 三处整本拼合/预览/texpdf 接口兜底：md 缺失但项目 txt 存在的章 → 现场拼（覆盖 skip/中断/其他未生成 md 场景）
• 验证：实机补 L04.md（10825 字符，## 强制收容 + 5 子结构标题全对，无别名/编号残留）；输出目录 5 章齐 ✅
• bump 3.1.2（不 git-sync，用户指示）