Synthadoc v1.2：用 Agentic Workflow 替代人工文档维护循环

每个 wiki 最终都会产生这样一个维护循环。

源文档更新了，从它派生出来的 wiki 页面却过时了。你运行 synthadoc ingest 重新处理这个文件。等待。运行 lint 检查页面是否通过质量检查。再等待。如果通过，lint 将其提升为 active 状态。如果没有通过，你就诊断问题并重复上述步骤。现在把这个过程乘以十二个过期页面。

这是一个定义明确的序列。但也很繁琐——每一步都阻塞在前一步之后，你必须全程在场，而且忘记某个步骤的风险是真实存在的。

Synthadoc v1.2 带来了一个智能体维护工作流，用一个 prompt 替代了这个循环。

What the agent actually does

当你发送"重新摄入过期页面"时，ActionAgent 并不是简单解析你的意图然后交给一个固定函数。它运行的是一个工具调用循环：模型发出一个结构化的工具调用，agent 执行它，将结果返回给模型，然后模型决定下一步调用什么。如此循环，直到模型产生一个没有待处理工具调用的纯文本摘要。

对于过期页面工作流，序列是这样的：

find_stale_pages ：返回每个过期页面及其源文件路径

confirm ：向 UI 发送一个确认请求，列出范围；阻塞直到你批准或拒绝

ingest_source（×N）：一次强制重新摄入一个源文件，反复轮询直到每个作业达到终态

run_lint ：将完整的 lint 检查加入队列

poll_job ：等待 lint 作业完成

get_page_states ：检查每个重新摄入页面的最终生命周期状态

纯文本摘要，包含所有结果、lint 结果和页面状态

整个过程由模型驱动。如果某个摄入在 workflow 中途失败，agent 会继续处理剩余页面并在摘要中报告失败。没有硬编码的分支逻辑，失败处理来自模型所运行其中的系统提示词。

The confirmation gate

confirm 工具不是一种客套。agent 在写入任何内容之前，会向 UI 发送一个 confirm_request 事件，携带完整的范围——哪些页面、哪些源文件——并阻塞直到你响应。120 秒超时的默认设置是拒绝而非批准。

这很关键，因为"重新摄入过期页面"和"重新摄入所有页面，包括我故意保留为过期的那些"，在一个没有确认步骤的系统里看起来完全相同。这道门让你保持对重写内容的控制权。

一个耗时三分钟却只在最后才显示输出的 workflow 会让人觉得它卡住了。智能体 workflow 在每个工具步骤都发出 tool_progress SSE 事件——"正在重新摄入：alan-turing.md"、"摄入运行中... (7s)"、"✓ alan-turing 已重新摄入"、"正在运行 lint 检查..."——让 UI 全程保持活跃。

同样的事件会出现在 Obsidian 插件的查询模态框中。workflow 完成后，web UI 会预填充聊天文本框，提出逻辑上的下一个操作——"运行 lint 以提升重新摄入的页面"——所以下一步只需一次点击，而不是输入命令。

同样的智能体循环无论从哪里发起都会运行：

Web UI：在聊天界面输入 prompt，观察进度流。或者从知识图谱中，对任何过期页面节点右键，直接从图谱视图触发按 slug 重新摄入

CLI：synthadoc query "re-ingest stale pages" 运行相同的 agent、相同的确认提示、相同的结果

CLI 路径将 tool_progress 事件作为终端行输出，并用 [Yes/Cancel] 提示交互式处理确认门，所以这个 workflow 完全可以在没有浏览器的情况下使用。

这个 workflow 构建在一个抽象接口之上：AgenticWorkflow 声明了 build_system_prompt()、build_initial_message() 和 get_tool_fns()。循环机制——工具调度、结果注入、终止检测、30 次调用限制、确认超时——存在于 action agent 中，并由每个 workflow 继承。

添加一个新的 workflow 意味着实现三个方法并编写一个系统提示词。现有基础设施处理其余的事情。

下面的演练全程展示了完整循环：两个过期页面、确认门、逐页摄入进度、lint 自动运行，以及 Obsidian 中的内容快照 diff，显示版本之间具体发生了什么变化。

📺 Synthadoc Agentic Maintenance Workflow — YouTube

What we learned building this

系统提示词是策略层。governing 这个 workflow 的规则——首先发现范围、写操作前始终确认、逐个处理页面、所有摄入后运行 lint——存在于系统提示词中，而不是代码中。当我们需要为按 slug 路径调整顺序时，只需要四行文本，而不是代码变更。

每步进度让一切感觉更快。实际持续时间没有变化，但感知到的延迟确实变了。

一次失败不应该停止整个批处理。如果源文件在发现和摄入之间消失了，workflow 会报告失败并继续。在一开始就接入这个机制，后来节省了一次真正的调试会话。

Synthadoc CE v1.2.0 是开源的。智能体 workflow、可插拔接口和完整的 SSE 协议都在仓库中。