Structured Writer — 结构化写作智能体

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

版本：3.1.9 | 作者：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.11] - 2026-10-02

修复（判定型 prompt 正反例范式统一——L07 假问题事件驱动）

事件：L07 推理审核出现"detail 写好评（前文铺垫充分，转折逻辑合理）、result 却标 SOFT"的自相矛盾输出，假问题进入修复面板，勾选后会对无问题的段落做整段重构（字数 ±15%）。根因：判定型 prompt 只给裸枚举（PASS/HARD/SOFT、true/false、三分类），无级别定义、无正反例、无一致性约束，小模型默认"既然让你审了就得标个非 PASS"。本次统一照搬播客智能体范式（probe.py / paradigms.py：描述应当怎样 + 示范长什么样 + ✅正例 + ❌反例 + 自检），8 处判定型 prompt 全部补齐；代码侧删掉全部语义关键词猜测，只保留结构级校验。

• novel_reasoning_check.py · 判定级别定义（根因修复）：prompt 注入 PASS/HARD/SOFT 三级别的定义 + 每级 ✅正例 + ❌反例 + 一致性铁律（detail 正面措辞时 result 必须 PASS；判 HARD/SOFT 必须描述具体缺陷；严禁"detail 说好话、result 标反"）+ 自检句。PASS 的 ❌反例直接点名本次事故形态（result=SOFT, detail=铺垫充分，逻辑合理）
• novel_reasoning_check.py · 代码删语义猜测：删除原 result 字段自然语言关键词判级分支（"符合/合理/无问题"→PASS、"矛盾/突兀"→SOFT）与"无法评估"关键词跳过分支——Python 不懂语义，关键词硬匹配是硬编码 hack；新增 _classify_items() 纯结构校验：result 为合法枚举 → 采信；字段填反（dimension 含级别、result 含说明）→ 结构归位；两者都不是合法枚举 → 该条交人工复核（problem 标注"未给出合法级别"），绝不猜级别
• novel_reasoning_check.py · DIMENSIONS 五维度：因果/人物/情绪/对话/论证五维度 desc 全部补 ✅/❌ 具体例（伏笔回收、谨慎角色设定、情绪过渡、口吻身份匹配、线索推理）
• novel_pledge_check.py · JUDGE_PROMPT：已兑现/未兑现/悬停三分类补 ✅正例 + ❌反例（反例点名"evidence 写未再提及却填未兑现"式自相矛盾）；边界规则写死：部分兑现（核心未达）→未兑现、换方式/他人代为→已兑现、承诺人死亡无接续→悬停；加 status-evidence 一致性铁律 + 自检
• novel_pledge_check.py · EXTRACT_PROMPT：修格式模板与示例的 sub 字段矛盾（格式行 [{"text","char"}] 无 sub、示例却带 sub——三处不一致导致模型丢 sub 后 _locate_source_text 定位失败），格式行补 "sub":"S01" 标注必填；补 ❌反例："已经潜入了实验室"（已完成动作）、"想起当年决定"（回忆）不提取
• novel_4dim_check.py · PROMPT_TPL（四布尔）：时间衔接/情绪匹配/话题过渡/角色承接四维度各配 ✅/❌ 具体场景例；加 ok-reason 一致性铁律（ok=false 时 reason 必须写具体问题，严禁"false + 理由夸好"方向矛盾）+ 自检
• novel_4dim_check.py · FIDELITY_PROMPT：fidelity_ok 布尔补 ✅/❌ 正反例并写清边界（关键事件缺失/状态反转=false；次要细节省略≠false）；加 ok-reason 一致性铁律
• novel_fidelity.py · 收尾类型判定：封闭式/开放式/悬停式三类补 ✅正例 + 两组最易混 ❌对照（踏上新旅程=开放式不是悬停式；停在犹豫未决=悬停式不是开放式）；输出格式强约束"第一行只写类型名，理由中不得出现其他类型名"
• novel_fidelity.py · _pick_ending()（结构级修正）：原按 ENDING_TYPES 元组顺序子串匹配，模型输出"悬停式"但理由里提到"开放式"三字会被劫走判成开放式；改为取类型名在响应中最早出现位置，无类型名返回 None。仅结构级修正，无语义猜测
• novel_entity_extractor.py：type 5 值（character/object/location/organization/abstract）、status 7 值（active/dead/injured/unconscious/destroyed/damaged/closed）枚举逐个给适用边界解释（organization 与 abstract 的区分、destroyed 与 damaged 的程度分界、closed 的适用对象等）
• novel_reasoning_check.py · 章内/章级检测分离（架构归位）：章内推理审核只产子结构级问题——prompt 取消 sub=null 通道（sub 必填，整章性问题也定位到主要涉及的段），代码侧 sub 非法/缺失的条目直接丢弃（打日志），绝不落章级；章级/跨章判定仍由全文完结层（finalize_novel：全文承诺/大纲忠实度/结尾收束）统一做，两级互不污染。修复"章级问题（无法整段重构，需人工处理）"污染章门禁的问题
• novel_reasoning_check.py · prompt 补"维度不适用"规则：维度在本章无评估对象（如本章无对话、无推理情节）→ result=PASS，detail 写明"维度不适用，非缺陷"；❌反例点名实际事故（result=HARD, detail="无具体对话"——无对话不是缺陷）。补齐删除 b19 关键词跳过后模型侧规则的缺口；打回纠正的重试 prompt 同步移除 null 示例
• 验证：_classify_items 确定性回归 4 断言全绿（sub=null 假 HARD 被丢弃不落章级 / 真问题仍定位 S02.txt / PASS 跳过 / 非法枚举交人工复核 SOFT 不阻断）；py_compile 通过；f-string 模板转义经编译校验
• 通用线核查结论（不改）：writer/planner/aux_parser 的 5 处 prompt 全部为生成/选择型任务，无判定枚举；GEN_TEMPLATE_SYSTEM_PROMPT 已是解释+示例+互斥规则的合格范式；唯一"判定"环节（引用校验）此前已删 LLM 判定、改为 all_rag_headers 前置规范——通用线无此缺陷族
• 验证：5 文件 py_compile 通过；_pick_ending 回归（悬停式输出+理由混入"开放式"→ 仍判悬停式；纯类型名正常；无类型名返回 None）；全部 prompt 格式槽位 format() 完整性通过；6 处 prompt 正反例+一致性铁律块存在性断言通过；scripts/check_version.py 三端一致校验通过