pSEO 内容生产 Workflow 设计：把不确定的 AI 写作变成可控流水线

pSEO（Programmatic SEO）的核心矛盾并不是“能不能批量生成文章”，而是“能不能在批量生成时保持质量、可追踪、可恢复、可发布”。如果只是把关键词丢给大模型，让模型直接输出文章，很快会遇到几个现实问题：外部搜索数据不稳定、竞品页面抓取失败、模型输出格式漂移、文章质量不可控、内链策略难以统一、封面图和发布链路难以复用。

这个 pSEO 项目的 workflow 设计，解决思路不是追求一个巨大的 Prompt，而是把文章生产拆成一条可观测、可重试、可落库的工程流水线。

一、整体架构：同步建任务，异步跑生产

系统对外暴露的是一组简单的 HTTP 接口：开始任务、取消任务、重跑任务、强制重跑、查询文章、发布文章。真正的内容生产不在接口请求里直接完成，而是通过数据库任务表和 RocketMQ 异步执行。

一次任务大致分成三层：

1. 批量任务层：记录本次请求的关键词集合、项目 ID、创建人和任务状态。
2. 单关键词 Job 层：每个关键词拆成一个独立 job，分别记录 queued、running、success、failed、cancelled。
3. 文章资产层：单关键词 job 成功后，生成可发布的文章草稿，包括标题、摘要、正文、封面图、阅读时长和扩展信息。

这种分层有两个好处。

第一，接口响应可以很快返回。用户提交 100 个关键词时，服务只需要校验参数、写入任务、投递消息，而不需要等待 100 篇文章全部生成。

第二，失败边界足够清晰。一个关键词失败，不影响同批次其他关键词；一个 job 可以独立重跑；文章已存在时也可以选择跳过、restart 或 force restart。

二、任务状态设计：区分“派发状态”和“生产状态”

这个项目里有一个重要细节：批量任务表的状态主要表示 MQ 派发状态，而不是每篇文章最终生产状态。

批量任务可能从 init 变成 running，再根据 job 派发结果变成 success、partial_failed 或 failed。但真正的文章生产结果，要看任务明细表里的每个 job 状态。

这种设计看起来容易误解，但它符合异步系统的现实：

• 批量任务负责“是否成功把关键词拆成可执行 job”。
• 明细 job 负责“某个关键词是否真正完成内容生产”。
• 文章表负责“最终可消费的内容资产”。

如果把所有语义都塞进一个状态字段，后续排查会非常困难。现在的设计虽然需要调用方理解状态边界，但故障定位更清晰。

三、Workflow 主链路：从关键词到可发布文章

单个关键词的 workflow 可以概括为七个阶段。

1. 数据采集

第一步不是直接写文章，而是先通过 Ahrefs 获取关键词数据。

系统会拉取两类信息：

• matching terms：用于获取相关词和搜索意图。
• SERP URLs：用于找到当前搜索结果里的竞品文章。

这里有几个工程化保护：

• Ahrefs 请求有节流，避免打爆接口。
• 同一天相同关键词有内存缓存，减少重复请求。
• SERP URL 会过滤 PDF、Reddit、YouTube、Quora 等不适合作为文章参考的页面。
• SERP 数量不足或更新时间过旧时，数据采集阶段会失败。

这一步的关键价值是：让后面的写作基于真实搜索结果，而不是纯模型想象。

2. 竞品内容采集

拿到 SERP URL 后，系统会逐个抓取竞品页面正文。

抓取逻辑不是简单读取 HTML，而是结合 axios、JSDOM、Mozilla Readability 和 Markdown 清洗，把网页转成相对干净的内容输入。系统还会过滤挑战页、链接密集区、图片、无效正文，并限制单篇竞品内容长度。

这里的设计重点是“宁可少，也不要脏”。如果竞品内容不足 3 篇，整个阶段会失败。因为低质量竞品输入会直接污染后续写作。

3. LLM 写作

写作阶段通过 TCC 里的 pseo_prompt.write 模板构造 Prompt，再调用内部 ModelHub。输入包含：

• 主关键词
• 二级关键词
• 搜索意图
• 内容目标
• 市场区域
• 竞品内容 JSON

输出被严格要求为 JSON：

{
  "meta_title": "...",
  "meta_description": "...",
  "title": "...",
  "article_content": "..."
}

系统没有信任模型一定按格式输出，而是做了两层兜底：

• 首次解析失败时，用格式修复 Prompt 让模型把上一轮响应转成合法 JSON。
• 解析工具支持从混杂文本里截取 JSON 对象，并做有限的 loose parse。

写作完成后，还会做正文归一化：去掉 H1、去掉模型自己插入的链接、修正产品词大小写、规范 FAQ 标题和问题标点。

4. Review

Review 不是单纯让模型“评价一下”。它分成客观规则检查和主观 LLM Review。

客观检查覆盖：

• meta title 长度不超过 60 字符。
• meta description 长度不超过 160 字符。
• 标题、描述、正文必须包含 focus keyword。
• 文章不少于 1500 英文词。
• Introduction 前 100 词必须出现 focus keyword。
• Introduction 不超过 200 词、最多 2 段。
• 必须有 Conclusion 和 FAQs，且它们是最后两个 H2。
• FAQ 外必须有 H3。
• 不允许出现指定的 AI 味禁用词。

主观 Review 则继续调用 LLM，输出 passed + feedback。最终只有客观和主观都通过，Review 才算通过。

这一步体现了一个重要原则：能用代码判断的，不交给模型；必须靠语义判断的，再交给模型。

5. Repair，最多三轮

如果 Review 不通过，系统不会直接失败，而是进入修复阶段。

Repair Prompt 会拿到当前文章和 Review feedback，让模型只针对问题修复，并再次输出同样的四字段 JSON。修复后重新进入 Review。最多执行 3 轮。

这个闭环的价值在于：workflow 可以自动消化一部分模型偏差，而不是把所有失败都丢给人工。

但它也设置了上限。最多 3 轮意味着系统承认有些文章不值得无限修，超过上限就失败并落库上下文，方便后续排查。

6. 内链插入

文章通过 Review 后，系统进入内链阶段。

内链不是让模型自由发挥，而是用本地 internal-link-library.json 做确定性插入。算法会：

• 跳过 Markdown 标题。
• 避免改动已有链接。
• 按 anchor 精确匹配。
• 避免同一 URL 重复插入。
• Introduction 内最多插入两个链接。
• 强制补充 Lark 和 project management tools 等核心 anchor。

这一步把 SEO 策略从模型输出里剥离出来，变成稳定、可维护、可审计的规则系统。

7. 封面图生成与上传

最后，系统根据关键词、meta title、meta description 生成封面图 Prompt，调用图片模型生成 4:3、1K 规格图片。

图片返回后会做格式和尺寸校验：

• 只允许 png、jpg、webp。
• 小于 5MB。
• 宽高比接近 4:3。
• 长边在 900 到 1400 像素之间。

校验通过后上传到 TOS，并把 URL 写入文章结果。

四、成本与可观测性：每次模型调用都入账

这个 workflow 不是只保存最终文章，还会保存每次 LLM 调用的成本明细。

每次写作、Review、Repair、封面图生成都会记录：

• task 类型
• round 轮次
• provider 和 model
• modelhub logid
• 输入输出 token
• cache token
• reasoning token
• 估算美元成本
• 原始 usage

这些数据写入 hera_pseo_task_detail_cost。这让团队可以回答几个关键问题：

• 一篇文章平均成本是多少？
• 哪个阶段最贵？
• 哪些关键词反复 Repair？
• 某次模型调用失败时，能不能用 logid 追踪？

对于批量 AI 系统来说，成本观测不是锦上添花，而是上线后的基本能力。

五、失败恢复：取消、重跑和强制重跑

workflow 设计里另一个成熟点是恢复机制。

取消任务时，系统会把还在 init 状态的 detail job 标记为 cancelled。正在执行的 job 会在关键节点检查批量任务是否已取消，如果发现取消，就不再写成功文章。

普通 restart 只允许重跑已有历史记录且当前可重跑的关键词，通常用于失败或取消任务。

force restart 更激进，会允许覆盖既有文章，适合人工确认要重新生成的场景。

这三种操作分别对应三个不同语义：

• cancel：停止还没开始的工作。
• restart：修复失败任务。
• force restart：主动替换已有结果。

语义拆开后，调用方不需要靠复杂参数猜行为，系统也能更好地保护已有文章资产。

六、发布链路：内容生产和上线解耦

生成成功的文章默认是草稿状态，存放在 hera_pseo_article。发布时才会把文章 JSON 上传到资源路径。

发布动作会：

1. 校验 env 只能是 boe 或 live。
2. 按 article id 查询文章。
3. 构造标准 article JSON。
4. 上传到 TOS 资源路径。
5. 更新 page status、published by、published at。
6. 调用 library rebuild。

这样设计的好处是：生产内容和发布上线被明确解耦。生成失败不会污染线上；生成成功也不代表立即上线；发布可以批量、可控地执行。

七、这个 Workflow 设计的核心取舍

这个 pSEO workflow 的设计可以总结成四个取舍。

第一，少相信模型，多相信流程。模型负责写作、主观 Review 和图片生成，但数据采集、客观校验、内链、状态流转、成本记录都由代码控制。

第二，用阶段化降低复杂度。每个阶段都有输入、输出、passed 和 msg。失败时能明确知道是 Ahrefs、竞品抓取、写作、Review、内链还是封面图出了问题。

第三，用异步 job 承接长耗时任务。批量 pSEO 文章生产天然耗时，HTTP 请求只负责建任务，真正执行交给 Worker 和 MQ。

第四，把可恢复性做进数据模型。任务表、明细表、文章表、成本表分工明确，使取消、重跑、覆盖、排查都有落点。

结语

一个可上线的 pSEO 系统，本质不是“批量调用大模型”，而是“围绕大模型构建一套生产系统”。

这个项目的 workflow 把关键词研究、竞品理解、文章生成、质量检查、自动修复、内链策略、封面图生成、成本记录和发布动作串成一条工程化流水线。它没有假设 AI 永远正确，而是在每个关键环节设置了校验、重试、失败落库和人工可介入的边界。

这也是批量 AI 内容系统最重要的设计经验：让模型输出内容，让 workflow 保证秩序。