SEO 内容规划智能体

本页说明 SEO 内容规划智能体如何调研公开 SERP 与竞争内容，对照规划库中的已覆盖主题生成选题清单与内容简报。读完本页，你能理解这个场景为什么以 Web Agent 为核心、规划状态为什么放在规划库或 CMS 而不是 Memory，以及什么时候才需要交互式确认。

适用场景

Growth 或 content 团队需要基于公开 SERP、竞品内容和站点自身的规划状态安排下一批内容。SERP 与竞品内容随时在变，人工汇总时容易漏掉已覆盖的主题，也难以持续跟踪竞争内容的变化；选题决策需要每条都有数据或页面来源支撑，否则内容团队无从判断优先级。

典型触发时机：

新一季内容日历规划启动，需要基于关键词空白产出选题清单。
某组关键词流量下滑，需要调研竞品内容并评估更新优先级。
站点进入新主题领域，需要梳理关键词空白和已覆盖主题的边界。

工程挑战

SERP 数据强时效：排名与内容形态每周在变，采集时间不带上，规划就建立在过期样本上；跨关键词组比较时，各组数据还必须来自相近的时间窗才有可比性。
规划状态属于系统而不是记忆：已覆盖主题、内容日历和关键词策略是团队共享、随发布流程更新的结构化状态。把它们放进个人记忆，会和 CMS 的实际发布状态脱节——选题重复或互相冲突就是从这里开始的。
证据链：每条选题的优先级依据都要能回溯到具体 SERP 或数据来源，否则内容团队无法判断该不该做，规划评审也无从复核。

模块组合

模块	角色	说明
GenAuth	核心	运行时以静默委托签发短时效凭证（所有产品调用必需）；本场景默认无需交互式确认，接入登录态或写动作时才升级 interactive。
Web Agent	核心	通过 WebSearch 查询公开 SERP 与竞争内容，逐条保留来源 URL 与采集时间。
GUMem	不使用	关键词策略、已覆盖主题和内容日历是团队共享的规划状态，放在规划库或 CMS 里按版本维护、随发布流程更新；不存在需要跨会话沉淀的个人记忆。

SEO 内容规划智能体：场景架构

何时需要交互式确认

所有产品调用都需要 GenAuth 委托令牌；公开只读场景用静默委托即可。公开 SERP 调研不需要用户逐次确认授权，静默签发的运行时凭证已经提供这个场景需要的约束：凭证短时效、可随时撤销、每次调用都带 grantId 与 auditId 可供追溯。

需要升级为 mode: 'interactive' 交互式确认、让用户在 Qoni Console 明确确认的情况：

登录态访问：任务需要进入 Search Console、analytics 或 CMS 后台等登录后才可见的数据——本页示例不涉及；页面表现数据由你的应用自行导出后注入任务。
写动作：发布、覆盖或删除 CMS 内容——本场景默认排除，选题清单由内容团队复核后按发布流程执行。

注意：本样例申请 webSearch、doAnything 产品权限。可查询范围等业务边界需要由应用和下游服务配置、校验；产品 scope 和 prompt 中的规则不提供这些细粒度限制。本样例未展示该配置。授权语义见 Delegate Token 与缩权。

工作流程

SEO 内容规划智能体：工作流程

用户选择站点、主题或关键词范围。
应用从规划库或 CMS 读取关键词策略、已覆盖主题和内容日历（带版本），并获取静默运行时凭证。
Web Agent 通过 WebSearch 逐组查询公开 SERP，记录排名页面、内容角度和来源 URL 与采集时间。
检查点：每条 SERP 数据都带来源 URL 与采集时间；跨关键词组比较时确认采集时间窗相近。
Agent 对照已覆盖主题去重、找差距，生成选题清单、内容简报和优先级建议。
检查点：每条选题的优先级依据都应能回溯到具体数据或页面来源；无来源支撑的判断不进交付物。
内容团队复核清单；确认后的选题和日历决策写回规划库或 CMS，作为下一轮规划的输入。

示例代码

本页使用已发布到 npm 的 @qoniai/qoni 0.9.0；下载包附带同版本 SDK，由 npm ci 安装。默认围绕 Firefox 的浏览器隐私主题，结合官方隐私页规划内容选题。公开网页由真实 SDK 读取，业务输入在 scenarios.ts 中标记为 public-demo。

本演示不读取或写入 GUMem；任务输入来自页面清单和明确提供的业务数据。Web Search 先取得 results[] 来源，再由 DoAnything 阅读和分析。接入自己的数据时，用 --input 指定 JSON 文件；需要用户同意时用 --interactive 发起委托，站点登录与交互处理见 Qoni SDK。

下载完整可运行样例，或在文档仓库中执行：

bash

cd examples/qoni
npm ci
npm run case -- seo-content-planner-agent
# 使用自己的输入
npm run case -- seo-content-planner-agent --input /path/to/input.json

运行前设置服务端 QONI_ACCESS_KEY、QONI_SECRET_KEY。QONI_USER_ID 可指定业务已识别的 GenAuth 用户；未指定时，本地演示从绑定用户池取用户。涉及演示 Memory 写入时，程序创建独立用户以避免修改业务用户的偏好。

本场景的真实执行入口：

import { cliOptions } from '../runtime.js'
import { inputFile, runScenario } from '../run-case.js'

// 从真实搜索结果和页面证据中提出内容选题。
const report = await runScenario('seo-content-planner-agent', cliOptions(), inputFile())
// report.items：选题、搜索意图和参考来源；这里不测量关键词搜索量。
// 校验字段：topic, searchIntent, sourceUrl.
console.log(JSON.stringify(report, null, 2))

入口按场景 ID 读取下面这段定义，代码直接引用实际执行的 scenarios.ts，注释按页面语言显示：任务描述、输出字段、来源字段、Web Search 查询（如有）、是否使用 Memory，以及演示输入。执行链会在任务描述后追加输入数据、搜索来源、召回的 Memory 和通用安全约束，拼成最终的任务描述，完整拼装逻辑见下方执行链。

// 从真实搜索结果和页面证据中提出内容选题。
research('seo-content-planner-agent',
  'Use the search results and page content to propose two content topics about Firefox privacy. Return [{topic,searchIntent,sourceUrl}]. These are proposed topics, not measured keyword volume. Do not change any website or CMS.',
  ['topic','searchIntent','sourceUrl'], 'sourceUrl', ['Firefox privacy features Mozilla official'], sample([privacy], { approvedTopics:['browser privacy'], existingTopics:[] })),

这里的 runScenario()、browser()、research() 和 sample() 是样例包的应用函数。实际 SDK 调用都在下面的执行链中：委托与权限查询 → 所需的 Memory/搜索 → 网页任务或监控 → 校验与保存。fields、sourceField 规定本场景如何校验业务输出；它们由应用使用。辅助函数的完整实现在样例包的 runtime.ts 中。

查看实际 SDK 执行链

// 场景构造器：browser() 只调用 DoAnything；research() 先 Web Search 再 DoAnything；sample() 标记 public-demo 演示输入。
const firefox = 'https://www.mozilla.org/en-US/firefox/new/'
const manifesto = 'https://www.mozilla.org/en-US/about/manifesto/'
const privacy = 'https://www.mozilla.org/en-US/privacy/firefox/'
const support = 'https://support.mozilla.org/en-US/kb/get-started-firefox-overview-main-features'
// 演示文案规则会加入 prompt；它们不替代服务端权限或业务规则校验。
const policy = {
  version: 'demo-2026-09',
  approvedClaims: ['Describe only features supported by the cited page.'],
  forbiddenClaims: ['guaranteed security', '100% private', 'unverified pricing or performance'],
  voice: 'concise and warm',
}
const sample = (pages: string[], business: JsonObject = {}): JsonObject => ({
  dataset: 'public-demo', pages, policy, business,
  notice: 'Business records are synthetic demonstration inputs. Referenced websites and SDK execution are real.',
})
// fields 是必填输出字段；sourceField 指定需要校验 URL 格式的字段，memory 控制是否调用 GUMem。
const browser = (id: string, task: string, fields: string[], sourceField: string | undefined, input: JsonObject, memory = false): Scenario => ({
  id, products: ['doAnything'], task, fields, sourceField, input, memory,
})
const research = (id: string, task: string, fields: string[], sourceField: string, queries: string[], input: JsonObject, memory = false): Scenario => ({
  id, products: ['webSearch', 'doAnything'], task, fields, sourceField, queries, input, memory,
})

import { QoniScopes, type JsonObject, type RunResult } from '@qoniai/qoni'
import { readFileSync } from 'node:fs'
import { getScenario, type Scenario } from './scenarios.js'
import { appendTrace, checkInputCoverage, cleanupDemoUser, createContext, delegate, handleInteraction, inputEntryCount, isolateDemoUser, object, readWithRetry, renderScreenshot,
  save, saveArtifacts, searchHits, settled, settleRun, validateItems, withCleanup, type Context, type Options } from './runtime.js'

export async function runScenario(id: string, options: Options = {}, input?: JsonObject) {
  // 按场景 ID 读取真实任务定义；--input 只替换业务输入。
  const scenario = getScenario(id)
  const data = input ?? scenario.input
  if (scenario.memory && data.dataset !== 'public-demo' && options.mode !== 'interactive' && !options.userId && !process.env.QONI_USER_ID) {
    throw new Error('Business Memory writes require the current QONI_USER_ID; do not select an arbitrary bound user')
  }
  const context = await createContext(id, { ...options,
    skipUserResolution: scenario.memory && data.dataset === 'public-demo' })
  return withCleanup(context, async register => {
    register('isolated demonstration user', () => cleanupDemoUser(context))
    // 演示偏好写入隔离用户；业务 Memory 必须属于明确识别的当前用户。
    if (scenario.memory && data.dataset === 'public-demo') await isolateDemoUser(context)
    return await executeScenario(context, scenario, data)
  })
}

export async function executeScenario(context: Context, scenario: Scenario, input: JsonObject) {
  const pages = input.pages
  if (!Array.isArray(pages) || !pages.length || pages.some(page => typeof page !== 'string' || !/^https:\/\//.test(page))) {
    throw new Error('Input pages must be an array of HTTPS URLs')
  }
  if (input.requiresLogin === true && context.mode !== 'interactive') {
    throw new Error('Targets that require sign-in need --interactive and user-controlled login')
  }
  const memoryScopes = scenario.memory
    ? [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_MEMORY_WRITE, QoniScopes.GUMEM_MESSAGE_WRITE] : []
  // delegate() 是应用函数，内部调用 delegateToken / completeDelegateToken。
  const grant = await delegate(context, scenario.id, scenario.products, memoryScopes)
  // 查询实际授权范围；readWithRetry() 只对可重试的读取错误有限重试。
  const { data: tokenInfo } = await readWithRetry(context, 'delegation introspection',
    () => context.qoni.genauth.introspectDelegationToken({ token: grant.token }))
  const info = object(tokenInfo)
  if (info.active !== true) throw new Error('The delegation token is not active')
  const audit = { grantId: grant.grantId, auditId: grant.auditId, scopes: info.scope }
  let memory: unknown
  if (scenario.memory) {
    // Session 将本次对话关联到当前用户，sessionId 由应用生成。
    const sessionId = `${scenario.id}-${Date.now()}`
    await context.qoni.gumem.createSession({
      token: grant.token, userId: context.userId, sessionId, title: scenario.id,
    })
    const preferences = object(input.business ?? {}).confirmedPreferences
    if (Array.isArray(preferences) && preferences.length) {
      // 只写入业务已经确认的偏好；sync: true 请求同步处理这次写入。
      await context.qoni.gumem.addMessages({ token: grant.token, userId: context.userId, sessionId, sync: true,
        messages: [{ role: 'user', content: `Confirmed demonstration preferences: ${preferences.join('; ')}` }] })
    }
    // 召回与任务有关的偏好，作为后续 prompt 的上下文。
    memory = (await readWithRetry(context, 'GUMem recall', () => context.qoni.gumem.recall({ token: grant.token, sessionId,
      query: 'Confirmed preferences relevant to this task', details: true }))).data
    save(context, 'memory.json', { sessionId, context: memory })
    if (Array.isArray(preferences) && preferences.length && !preferences.every(value => JSON.stringify(memory).includes(String(value)))) {
      throw new Error('Recall did not include the confirmed preferences just written by this demo')
    }
  }

  if (scenario.products.includes('track')) return runMonitor(context, scenario, input, grant.token, audit)

  let hits: ReturnType<typeof searchHits> = []
  if (scenario.queries) {
    // Web Search 返回真实 results[]；搜索来源将提供给 DoAnything 阅读。
    const search = await context.qoni.webSearch.run({ token: grant.token, prompt: scenario.queries, maxResultsPerQuery: 3 })
    save(context, 'search-ref.json', { runId: search.id, audit })
    await withCleanup(context, async register => {
      register('Web Search run', () => search.cancel('Documentation demonstration cleanup'))
      const result = await settleRun(context, search)
      save(context, 'search-result.json', result)
      settled(result)
      hits = searchHits(result.output)
    })
  }

  // 逐项对应输入的场景按输入项数要求条数，其余场景最多两项。
  const requiredItems = inputEntryCount(scenario.id, input)
  // 拼装场景任务、业务输入、搜索来源和 Memory；这些都是应用约定的上下文。
  const prompt = [scenario.task, `Task inputs: ${JSON.stringify(input)}`,
    `Search sources: ${JSON.stringify(hits)}`, `Confirmed memory: ${JSON.stringify(memory ?? null)}`,
    `Actual collection time: ${new Date().toISOString()}`,
    requiredItems === undefined
      ? 'Inspect the supplied sources. Return at most two items in the requested JSON array, without prose or Markdown.'
      : `Inspect the supplied sources. Return exactly ${requiredItems} item${requiredItems === 1 ? '' : 's'} in the requested JSON array, one per input entry, without prose or Markdown.`,
    'Keep synthetic demonstration data identified as synthetic. Do not send messages, publish, pay, edit accounts or submit forms.',
    input.requiresLogin === true ? 'Request user sign-in through an interaction when required; never enter credentials yourself.' : 'Public demonstration sources only; do not sign in.',
  ].join('\n\n')
  // 使用同一委托启动 Agent；capture 接收服务端交付的截图，不保证每步都有图。
  const run = await context.qoni.doAnything.run({ token: grant.token, prompt, capture: { screenshots: true } })
  save(context, 'run-ref.json', { runId: run.id, session: run.sessionRef, audit })
  let result: RunResult
  const trace = (event: { type: string; data: unknown }) => {
    context.eventCounts[event.type] = (context.eventCounts[event.type] ?? 0) + 1
    if (['progress','message','done'].includes(event.type)) appendTrace(context, event)
    if (event.type === 'browserLiveUrlChanged') {
      const liveUrl = object(event.data).liveUrl
      if (typeof liveUrl === 'string') context.browserUrl = liveUrl
    }
  }
  return withCleanup(context, async register => {
    register('DoAnything run', () => run.cancel('Documentation demonstration cleanup'))
    if (context.delivery === 'events') {
      // --events 实时读取事件；普通交互对象先转换为 SDK 句柄再交给用户处理。
      for await (const event of run.events({ signal: AbortSignal.any([context.abort.signal, AbortSignal.timeout(context.timeoutMs)]) })) {
        trace(event)
        if (event.type === 'screenshot') renderScreenshot(context, event.image)
        if (event.type === 'interaction') await handleInteraction(context, run.interactionHandle(event.data))
      }
      result = await settleRun(context, run)
    } else {
      // 回调模式在 wait 内接收同一次任务的事件；这里的辅助函数会保存图像和询问用户。
      result = await settleRun(context, run, { onEvent: trace,
        onScreenshot: (image, index) => renderScreenshot(context, image, index),
        onInteraction: interaction => handleInteraction(context, interaction) })
    }
    save(context, 'result.json', result)
    settled(result)
    await saveArtifacts(context, result)
    if (scenario.id === 'landing-page-audit-agent' && context.screenshots === 0) throw new Error('The landing-page audit did not deliver the requested screenshot')
    // 应用校验必填字段和来源 URL 格式；事实准确性仍需业务复核。
    const items = validateItems(result.output, scenario.fields, scenario.sourceField)
    // 要求逐项对应输入的场景，再核对每个输入项都有对应输出。
    checkInputCoverage(scenario.id, items, input)
    const report = { scenario: scenario.id, dataset: input.dataset, passed: true, runId: run.id,
      status: result.status, items, audit, screenshots: context.screenshots, interactions: context.interactions,
      events: context.eventCounts, artifactIds: result.artifacts.map(artifact => artifact.id) }
    save(context, 'report.json', report)
    return report
  })
}

async function runMonitor(context: Context, scenario: Scenario, input: JsonObject, token: string, audit: JsonObject) {
  // Track 单独创建 monitor：声明目标、抽取字段并请求每小时调度。
  const monitor = await context.qoni.track.create({ token, prompt: scenario.task,
    targetUrls: input.pages, extractionSchema: { heading: 'string', source_url: 'string' },
    tickInstructions: `Open the target URLs and read the actual visible heading. Return a JSON object with heading and source_url. ${scenario.task}`,
    triggerDsl: { on: 'change' }, schedule: { kind: 'interval', intervalSeconds: 3600 } })
  save(context, 'monitor-ref.json', { id: monitor.id, audit })
  return withCleanup(context, async register => {
    register('Track monitor', () => monitor.delete())
    const definition = await monitor.get()
    save(context, 'monitor-definition.json', definition)
    if (object(definition.schedule).intervalSeconds !== 3600) throw new Error('Track did not persist the requested schedule interval')
    // 立即运行一次，再读取该 runId 的实际抽取；completed 本身不足以证明取数成功。
    const tick = await monitor.runNow()
    save(context, 'tick.json', tick)
    if (tick.state !== 'completed') throw new Error(`Track execution failed: ${tick.state} / ${tick.error ?? ''}`)
    const runId = tick.runId
    if (typeof runId !== 'string') throw new Error('Track tick did not return a runId')
    const detail = await monitor.run(runId)
    save(context, 'tick-detail.json', detail)
    if (detail.state !== 'completed' || !detail.extracted || !Object.keys(object(detail.extracted)).length) {
      throw new Error('Track did not extract page data')
    }
    const extracted = object(detail.extracted)
    if (typeof extracted.heading !== 'string' || !extracted.heading.trim() ||
      typeof extracted.source_url !== 'string' || !/^https:\/\//.test(extracted.source_url)) {
      throw new Error('Track extraction is missing a heading or source URL')
    }
    const normalizeUrl = (value: string) => { const url = new URL(value); url.hash = ''; return url.href.replace(/\/$/, '') }
    if (!(input.pages as string[]).some(url => normalizeUrl(url) === normalizeUrl(String(extracted.source_url)))) {
      throw new Error('The Track source URL is not a configured target')
    }
    // 检查暂停/恢复是否保存；withCleanup() 在退出时调用 monitor.delete()。
    await monitor.pause()
    if ((await monitor.get()).status !== 'paused') throw new Error('Track did not persist the paused state')
    await monitor.resume()
    if ((await monitor.get()).status !== 'active') throw new Error('Track did not persist the active state')
    const report = { scenario: scenario.id, dataset: input.dataset, passed: true, monitorId: monitor.id,
      runId, state: detail.state, outcome: detail.outcome, extracted: detail.extracted, audit }
    save(context, 'report.json', report)
    return report
  })
}

export function inputFile(): JsonObject | undefined {
  const index = process.argv.indexOf('--input')
  return index >= 0 ? object(JSON.parse(readFileSync(process.argv[index + 1], 'utf8'))) : undefined
}

结果写入 output/seo-content-planner-agent/report.json。report.items 包含选题、搜索意图和参考来源；这里不测量关键词搜索量，字段为 topic, searchIntent, sourceUrl；audit 保存委托 ID、审计 ID 和实际授权范围，http.json 记录脱敏请求状态。应用解析 DoAnything 输出，并检查必填字段和来源 URL 格式。内容判断仍需业务人员结合原始来源复核。

数据与记忆边界

这个场景涉及四类数据，没有一类属于 GUMem：

规划状态：关键词策略、已覆盖主题、内容日历——团队共享的结构化状态，放在规划库或 CMS 里按版本维护，任务时注入，确认后的选题决策也写回这里。
业务状态：选题清单、内容简报和 SERP 采集样本——归档供规划评审与复核。
审计记录：grantId 与 auditId 构成的委托与行为链——由 GenAuth 维护。
用户 Memory：本场景不使用。如果未来要沉淀某个编辑的个人偏好（例如简报的写作口吻），那才是 GUMem 的位置；团队共享的规划状态不属于个人记忆。

失败处理

情况	推荐处理
SERP 结果不稳定或抓取失败	按失败处理并记录采集时间，不用不完整的样本得出趋势结论。
关键词组之间采集时间窗差距过大	重新采集对齐时间窗后再比较，不混用新旧样本。
输出条目缺少来源或采集时间	应用侧校验直接丢弃该条目，并在清单中标注丢弃数量。
需要登录才可见的分析数据	本任务不访问；由应用另行导出注入，或另行发起交互式委托。

生产注意点

不要自动发布或覆盖 CMS 内容：选题清单由内容团队复核后按发布流程执行。对排名和竞品数据要保留来源与采集时间；SERP 数据有时效性，超过合理时间窗的数据应重新采集而不是直接复用。选题和优先级是基于当前数据的建议，不应向用户承诺排名效果。

下一步

阅读快速开始跑通 Agent 身份与委托的最短路径。
阅读 WebSearch 了解公开 SERP 查询的工作方式。
继续查看营销简报智能体了解相邻场景。

SEO 内容规划智能体 ​

适用场景 ​

工程挑战 ​

模块组合 ​

何时需要交互式确认 ​

工作流程 ​

示例代码 ​

数据与记忆边界 ​

失败处理 ​

生产注意点 ​

下一步 ​