这周主要围绕一个“长篇研究报告生成智能体”项目做迭代。这个项目的目标并不是简单调用大模型生成一段文章，而是希望把长篇研究报告的生产过程拆成可追踪、可恢复、可审核的工程流程。换句话说，模型负责生成和推理，但系统要负责边界、态、证据和质量控制。

刚开始设计时，最直观的方案是把题目、资料和要求一次性塞进prompt，让模型直接输出完整报告。但长篇报告不适合这种方式。一方面上下文长度有限，另一方面章节之间容易重复或冲突，事实来源也很难统一管理。尤其是研究类文档，一旦写到几十页甚至上百页，如果前期方向错了，后面修正成本会非常高。

因此，这周的主要工作就是把“写报告”这件事拆成一条相对稳定的流水线。

用TaskSpec明确研究边界

项目里有一个核心输入模型“TaskSpec”，它相当于用户需求和系统执行之间的正式契约。里面会定义研究主题、报告标题、目标读者、研究机构、岗位范围、时间范围、必须包含的章节、排除主题、目标页数、引用格式、输出格式、证据标准和审核策略。

这个设计看起来比一句prompt复杂很多，但对于长篇研究任务很有必要。以项目中的示例任务为例，研究对象是“国际组织高级数字化岗位体系”，涉及联合国、ILO、UNDP、世界银行等机构，还要处理 D-1、D-2、ASG等职级范围。如果不提前结构化这些边界，模型很容易在生成过程中自由扩展，最后得到一份表面完整但难以审计的文本。

有了“TaskSpec”之后，后续的检索、证据抽取、章节规划和导出都可以围绕同一份结构化配置展开，流程会稳定很多。

用LangGraph编排完整生产流程

这部分不是简单地串联几个 LLM 调用，而是把长篇报告拆成多个明确节点：

这里比较关键的是流程具备“可暂停、可恢复、可修订”的能力。比如全文方案生成后，会通过 LangGraph 的interrupt()暂停，等待人工确认；如果证据覆盖不达标，系统会优先补充检索，达到检索上限后再交给人工决定是否继续；小节生成后会进入验证环节，检查证据编号、事实性表达和跨小节重复问题。

这让Agent不再只是一次性生成文本，而是更像一个受流程约束的生产系统。模型仍然会参与规划、抽取、写作和修订，但每一步都有状态记录和质量判断。

用SQLite保存过程和结果

持久化也是本周比较重要的一部分。当前项目使用 SQLite 保存项目、任务配置、运行记录、来源、证据卡片、全文方案、章节、小节草稿、章节冻结版本、验证问题、全文审校问题和导出产物。

LangGraph的checkpoint也落在SQLite中，因此任务中途失败后，可以基于thread_id从已有状态继续执行，而不是每次都从头开始。对于长篇报告这种耗时任务来说，这一点非常实用。

另外，Graph State只保存项目ID、当前章节、当前小节、证据ID等轻量信息；真正的大块内容放在数据库和本地文件中。来源快照保存在 `data/sources/`，最终报告导出到 `output/doc/`。这种设计不复杂，但排查问题时很方便，可以直接查看数据库记录和文件内容。

人工审批是质量控制的一部分

在这个项目里，我没有把“全自动”作为唯一目标。长篇研究报告有几个关键节点必须允许人工介入，比如全文大纲、证据缺口、章节方案和验证失败后的处理。

如果全文大纲偏离需求，后续生成越快，返工越多；如果证据不充分还继续写，最终文本可能只是“看起来像研究报告”。因此项目在这些位置设置了审批节点：用户可以批准、拒绝、带着证据缺口继续，也可以批准后续全部章节。

这种方式会牺牲一点“一键到底”的体验，但换来的是更可控的结果。对于研究类 Agent 来说，这个取舍是值得的。

FastAPI和Streamlit让过程可见

后端使用 FastAPI，提供创建项目、启动运行、恢复运行、查看运行状态、查看证据、下载产物等接口。为了支持长任务，后端也实现了后台运行、进度记录和失败重试。

前端使用 Streamlit，重点是把执行过程展示出来。用户可以看到当前节点、检索轮次、来源数量、证据卡片数量、正在生成的章节和小节、目标字数、实际字数以及验证问题。长篇任务运行时间较长，如果界面只显示加载状态，体验会很差；把执行细节展示出来，至少能让用户知道系统正在处理哪一步。

DOCX导出也需要单独处理

Markdown 导出相对简单，DOCX 则需要考虑字体、标题层级、页边距、行距、页眉页脚和参考资料。项目使用 `python-docx` 生成 Word 文件，并支持从 `TaskSpec` 中读取样式配置。

另外，正文中的 `[EV-xxxx]` 证据编号会在导出时转换为参考资料编号，最后统一生成参考资料列表。对于一些方法说明类章节，例如“研究范围、比较框架、证据标准”，导出时也可以按配置排除，避免把中间过程内容混入最终交付版。

小结

目前这个项目已经跑通了从任务配置、研究计划、检索、证据抽取、章节写作、验证修订、全文审校到 Markdown/DOCX 导出的主流程。测试也覆盖了 TaskSpec、Graph、API、证据选择、验证器和导出模块。

当然，现在仍然有不少可以继续加强的地方。离线种子搜索主要用于演示，后续需要接入更完整的来源抓取；事实验证目前主要检查证据绑定、数字和事实信号，还可以进一步加入语义蕴含判断；DOCX 排版也可以继续补充目录、脚注、图表和更规范的参考文献格式。

这周最大的体会是：研究类 Agent 的核心不只是“让模型更会写”，而是让系统更会约束模型。只要流程具备明确边界、状态记录、证据追踪、失败处理和人工介入点，长篇内容生产才有可能从一次性生成，逐步变成一条可迭代的研究生产线。