营销简报智能体

本页说明营销简报智能体如何以静默委托完成公开市场调研，把应用显式注入的产品资料、目标客群和历史营销活动与带来源的市场事实组合成简报草稿，并以事件流形式返回调研进度。读完本页，你能理解这个场景什么时候才需要交互式确认、外部事实为什么必须带来源，以及产品资料这类数据为什么应该作为显式输入而不是 Memory。

适用场景

Marketing 团队准备新营销活动时，需要快速整理目标、受众、核心信息、竞品背景、渠道建议和风险边界。内部资料分散在 docs、CRM 和营销活动 workspace 中，公开市场信息又需要逐条核对来源；人工汇总一份简报往往要跨多个系统反复检索。

典型触发时机：

新季度营销活动规划启动，需要在一周内产出首版简报。
产品进入新市场或新客群，需要汇总竞品背景和渠道建议。
上一次营销活动复盘结束，需要把经验教训沉淀进下一份简报。

工程挑战

事实与假设混在一份文档里：简报同时包含带来源的市场事实、内部判断和未经验证的假设，不区分三者的简报会把猜测当事实传给下游团队，输出必须逐条标注来源或标记为假设。
公开信息过期快且互相矛盾：市场规模、竞品动态在不同来源之间经常不一致，每条外部数据都需要采集时间和来源 URL，冲突来源要并列呈现而不是擅自裁决。
内部输入与公开查询必须隔离：产品资料、客群画像和未发布信息由应用显式注入任务，一旦任务把这些内容带进公开搜索词，就构成信息外泄。

模块组合

模块	角色	说明
GenAuth	核心	运行时以静默委托签发短时效凭证（所有产品调用必需）；本场景默认无需交互式确认，接入登录态或写动作时才升级 interactive。凭证短时效、可撤销、留审计链。
Web Agent	核心	通过 WebSearch 扫描行业趋势与公开报告，再逐页调研竞品页面，每条外部事实保留来源 URL 与采集时间。
GUMem	不使用	产品资料、目标客群、历史营销活动经验属于业务数据，由你的应用从 docs、CRM 和营销活动记录中读取后显式注入任务，不属于 Memory。

营销简报智能体：场景架构

何时需要交互式确认

所有产品调用都需要 GenAuth 委托令牌；公开只读场景用静默委托即可。本场景的默认路径只做公开网页调研：应用用与 Qoni 凭证绑定的 GenAuth 用户 ID 直接换取运行时凭证，不需要用户跳转确认。凭证是显式、短时效、可撤销的，只覆盖公开读取与任务执行；修改内部资料、导出客户明细和对外发布不在任何委托范围内。

需要升级为交互式确认（mode: 'interactive'）的情况：

需要 Agent 在受控会话中读取内部资料库或文档系统的授权可见页面，而不是由应用注入摘要。
调研要接入登录态页面或付费数据源。

升级方式与其他场景相同：mode: 'interactive' + redirectUri，用户在 Qoni Console 确认后由服务端 completeDelegateToken 兑换凭证，完整流程见快速开始；受控读取内部资料的完整示例见产品发布话术智能体。

工作流程

营销简报智能体：工作流程

用户选择产品、受众和营销活动目标。
应用以静默委托换取运行时凭证（公开调研，无需用户跳转确认）。
应用从 docs、CRM 和营销活动记录读取产品资料、客群画像和历史经验，作为显式输入注入任务。
检查点：内部资料只作为输入使用；未发布产品信息不应出现在后续任何公开网页任务的查询内容中。
Web Agent 通过 WebSearch 扫描行业趋势和公开报告，每条结果保留来源 URL 和发布时间。
Web Agent 逐页调研竞品页面，交叉核对市场信息；调研进度以事件流实时返回。
Agent 汇总内外部输入，生成简报草稿：目标、受众、核心信息、渠道建议、假设和风险边界。
Agent 输出简报草稿、来源清单和待确认问题，附 audit id；应用侧校验后交负责人确认。
检查点：简报中每条外部事实都应能回溯到具体来源；无来源支撑的结论应标记为假设，不作为事实进入交付物。

示例代码

本页使用已发布到 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 -- campaign-brief-agent
# 使用自己的输入
npm run case -- campaign-brief-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'

// 搜索公开来源并生成区分事实和假设的 brief。
const report = await runScenario('campaign-brief-agent', cliOptions(), inputFile())
// report.items：brief 章节、陈述、事实或假设标记及来源。
// 校验字段：section, statement, kind, sourceUrl.
console.log(JSON.stringify(report, null, 2))

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

// 搜索公开来源并生成区分事实和假设的 brief。
research('campaign-brief-agent',
  'Use the pages, search results and synthetic campaign inputs to draft a campaign brief. Return [{section,statement,kind,sourceUrl}], where kind is fact or assumption. Every item must include sourceUrl. Cite facts; label campaign recommendations as assumptions and cite the product source that informed them, without presenting the recommendation as a claim made by that source. Do not publish or edit anything.',
  ['section','statement','kind','sourceUrl'], 'sourceUrl', ['Mozilla Firefox features official'], sample([firefox], { product:'Firefox', audience:'People comparing desktop browsers', goal:'Draft an awareness campaign' })),

这里的 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/campaign-brief-agent/report.json。report.items 包含简报章节、陈述、事实或假设标记及来源，字段为 section, statement, kind, sourceUrl；audit 保存委托 ID、审计 ID 和实际授权范围，http.json 记录脱敏请求状态。应用解析 DoAnything 输出，并检查必填字段和来源 URL 格式。内容判断仍需业务人员结合原始来源复核。

数据与记忆边界

这个场景涉及四类数据，本场景不使用 GUMem：

版本化规则：品牌语气与禁用表达如果需要约束简报措辞，放在你的规则库（policy store）里按版本注入。
业务状态：产品资料、客群画像、历史营销活动经验和本次简报的结论——由你的应用从 docs、CRM 和营销活动记录中读取并显式注入，结论写回同一套业务存储。
审计记录：grantId 与 auditId 构成的委托与行为链——由 GenAuth 维护。
用户 Memory（可选）：只有用户明确确认的长期个人偏好才属于 GUMem；客群画像和营销活动经验是团队级业务数据，不是个人记忆，本场景默认不召回也不写回。

失败处理

情况	推荐处理
内部输入读取失败	按缺失输入处理并提示用户补充，不降级为猜测。
公开来源之间市场信息互相矛盾	并列列出冲突来源和时间，标记为待确认，不擅自裁决。
事件流断线	SDK 按 `sseMaxRetries` 自动重连续传；超出上限时按失败处理并回放已收到的事件。
输出条目标为事实却缺少来源	应用侧校验降级为假设或直接丢弃，并在简报中标注处理数量。

生产注意点

不要把未发布产品信息发送到公开网页任务中。对外宣传主张必须标记为待人工确认。简报中的市场规模、竞品动态等外部数据应保留采集时间，避免过期信息被当作现状引用。内部输入的读取范围应限制在本次营销活动需要的资料，不要把整个 CRM 导出注入任务。

下一步

阅读快速开始跑通 Agent 身份与委托的最短路径。
阅读授权与浏览器沙盒了解受控会话的安全边界。
继续查看产品发布话术智能体了解相邻场景。

营销简报智能体 ​

适用场景 ​

工程挑战 ​

模块组合 ​

何时需要交互式确认 ​

工作流程 ​

示例代码 ​

数据与记忆边界 ​

失败处理 ​

生产注意点 ​

下一步 ​