Consumer Insight Agent · System Architecture Whitepaper

01 · BACKGROUND & PROBLEM

背景与问题

消费者洞察是跨境电商品类决策的关键依据——立项需要回答用户怎么说、卖点如何确定、Persona 如何切分。然而消费者声音分散于多个数据源，传统调研模式在覆盖度、可复现性与可迭代性三个维度同时受限。

信息源现状

跨境电商场景下，消费者声音主要分布于两类来源。任意单一来源观察都无法构成完整画像。

来源	分布特征
用户购后自有数据	分布于电商平台（Amazon / Lazada）以及品牌独立站、垂类网站。Amazon 评论之外的来源在传统调研中通常未被覆盖。
社交媒体讨论	分布于 YouTube / TikTok / Instagram / Reddit / X 等多个平台。各品类的活跃平台分布不同，业务侧通常缺少跨平台的系统性视角。

传统调研模式的五项局限

问题不仅是产出周期，更体现在覆盖度、可复现性、可迭代性等维度的系统性受限。

维度	表现	业务影响
人力依赖	1 名资深产品经理 + 若干实习生协作完成一份完整品类洞察报告，周期约 1 周	调研周期与跨境电商品类决策的窗口期不匹配
覆盖不全	缺少跨平台数据源的系统性扫描，依赖经验抓取主流平台	非主流平台上的真实用户声音被遗漏
不可复现	跨源融合依赖个人经验，结论缺少结构化证据链；同一研究员两次结论可能不一致	结论难以被审计，决策链路缺少证据支撑
不可规模化	团队产能受限于资深 PM 数量，单团队约 1 周 1 份	大量品类决策无法获得调研支持
不可迭代	每份报告独立产出，高质量洞察未沉淀，bad case 缺少机制化复用	调研能力不会随项目数量自然累积

02 · ANALYTICAL FRAMEWORK

分析框架：三圈层信息生态模型

系统内置一套领域分析框架——三圈层信息生态模型，对消费者信息环境从微观到宏观逐层解码。下一节的 Multi-Agent 架构，是为了让该框架在工程上可执行、可观测、可迭代。

CORE LAYER · 01

核心圈 · 个人体验层（Voice of Customer）

从真实购后反馈中提取物理体验信号，用于识别产品功能层面的口碑驱动因素与缺陷类型。

数据源：电商平台用户评论（Amazon 等）
分析维度：情感分布 / 体验深度分层 / 场景体验矩阵 / 功能优先级决策矩阵
核心价值：用于检验产品物理可靠性，识别 P0/P1 级口碑风险

EXAMPLE · 示意数据 某品类正面 VOC 集中在性能维度（约 57.6%）；负面 VOC 集中在结构耐用性（约 27.1%）→ 提示 P0 级改进方向

MIDDLE LAYER · 02

中间圈 · 社区口碑层（Social Proof）

分析口碑在不同社媒平台之间的流动模式，识别每个平台在该品类中的角色定位。

数据源：Reddit / YouTube / TikTok / Instagram / X
分析维度：平台角色画像 / 话题传播矩阵 / 社区参与者画像 / 季节性趋势
核心价值：定位口碑的发酵地与放大器，明确各平台的传播职能

EXAMPLE · 示意数据 某品类中 Reddit 承担技术讨论职能（约 28.7% 发帖占比）；YouTube 承担性能展示职能（触达量级 ≈ 8.86 亿）

OUTER LAYER · 03

外围圈 · 文化叙事层（Cultural Narrative）

解析消费行为背后的文化驱动因素，将产品参数与目标市场的文化语境对齐。

数据源：社媒 + VOC + 文化背景知识融合推理
分析维度：核心叙事线 / 文化价值映射 / 偏好迁移路径
核心价值：将技术规格映射到文化语境，支撑卖点叙事与品牌定位

EXAMPLE · 示意数据 某品类的核心叙事从"实用代步"迁移至"自我效能感"，反映目标市场对个体能动性的文化偏好

跨圈层一致性校验

三圈层之间的一致性本身是高价值信号。当核心圈识别出"结构耐用性投诉"，而外围圈仍在传播"坚固"叙事时，这一矛盾即指向品牌叙事与产品力的脱节。系统在三层分析完成后执行逻辑对齐矩阵与矛盾点分析作为后置步骤，输出战略级结论（Golden Insight）。

分析维度	核心圈信号	中间圈信号	对齐状态
功能预期	爬坡动力	性能测评	一致
痛点映射	结构耐用性投诉	耐用性叙事	矛盾
心理动机	安全焦虑	文化自主权	部分一致

示意数据上表为示例性结构，实际报告中的对齐矩阵会基于具体品类的真实数据动态生成。

03 · AGENT TOPOLOGY

系统拓扑：1 Master + 7 Sub-Agents + 5 Tools

系统采用分层式 Multi-Agent 架构。Master Agent 负责调度与状态管理，不直接执行业务计算；7 个专用 Sub-Agent 各自承担一类业务职责；5 个底层 Tool 封装外部业务 API。整体由 7 个主层加 2 个横切层构成 9 层结构。

Notation & Conventions · 术语速查

HITLHuman-in-the-Loop · 人工卡点

ACIAgent-Computer Interface · Agent 与 Tool 的接口范式

VOCVoice of Customer · 用户购后反馈

ABSAAspect-Based Sentiment Analysis · 基于方面的情感分析

KANO需求分类模型（基本 / 期望 / 兴奋 / 无差异）

ITKItem Type Keyword · Amazon 标准商品类型词

SLAService Level Agreement · 服务等级约定

KBKnowledge Base · 向量化知识库

C1–C77 处 Self-Check 自检节点编号

S1–S77 个 Sub-Agent 编号

W1–W4Cross-Analysis Agent 内部 4 个 Worker

v0.1MVP 版本目标值（标"v0.1 设计目标"的数据）

3.1 主调用链（7 主层）

主调用链描述任务执行时组件间的纵向依赖关系：用户请求经接入层进入 Master Agent，由其分发至 Sub-Agent 层；Sub-Agent 调用 Tools 访问业务 API，并直接调用 LLM 推理服务；Memory 层为各 Sub-Agent 提供短期、历史与领域知识三类存储。

flowchart TB
    USR["① 用户层
选品 PM / 研究员 / 业务负责人"]:::user

    subgraph L2["② 接入层"]
      direction LR
      API["REST API"]
      WEB["Web UI / HITL"]
      MAIL["Email Delivery"]
    end

    subgraph L3["③ Master Agent · 编排控制中心"]
      direction LR
      WE["Workflow Engine"]
      SM["State Machine"]
      DISP["Dispatcher"]
      CPB["Context Pack Builder"]
    end

    subgraph L4["④ Sub-Agent 层（7 专用 Agent）"]
      direction LR
      S1["S1 · Amazon KW"]
      S2["S2 · Social KW"]
      S3["S3 · Social Collection"]
      S4["S4 · VOC Insight"]
      S5["S5 · Cross-Analysis ⭐"]
      S6["S6 · Report Gen"]
      S7["S7 · Evaluation"]
    end

    subgraph L5["⑤ Tools 层（5 业务封装 · ACI 范式）"]
      direction LR
      T1["amazon-keyword-mapper"]
      T2["social-keyword-gen"]
      T3["social-collect-request"]
      T4["consumer_insight (VOC)"]
      T5["consumer-insight-gen"]
    end

    subgraph L6A["⑥A 业务外部服务"]
      direction LR
      EB1["TikHub API"]
      EB2["Amazon Data API"]
      EB3["Object Storage"]
    end

    subgraph L6B["⑥B LLM 推理服务"]
      direction LR
      EL1["Claude API"]
      EL2["Aliyun Qwen API"]
    end

    subgraph L7["⑦ Memory 层"]
      direction LR
      WM["Working · Redis 24h"]
      EM["Episodic · PostgreSQL"]
      KB["Knowledge Base · Qdrant"]
    end

    USR --> L2
    L2 --> L3
    L3 == "task + Context Pack" ==> L4
    L4 --> L5
    L5 --> L6A
    L4 -. LLM 直调 .-> L6B
    L4 <-.读写.-> L7
    L3 <-.持久化.-> L7
    L3 --> MAIL

    classDef user fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e
    classDef intf fill:#fef3c7,stroke:#b45309,color:#78350f
    classDef master fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef sub fill:#7c3aed,stroke:#5b21b6,color:#ffffff
    classDef cross fill:#dc2626,stroke:#7f1d1d,color:#ffffff
    classDef tool fill:#10b981,stroke:#047857,color:#ffffff
    classDef extbiz fill:#6b7280,stroke:#374151,color:#ffffff
    classDef extllm fill:#a855f7,stroke:#7e22ce,color:#ffffff
    classDef mem fill:#f59e0b,stroke:#b45309,color:#1c1917

    class USR user
    class API,WEB,MAIL intf
    class WE,SM,DISP,CPB master
    class S1,S2,S3,S4,S6,S7 sub
    class S5 cross
    class T1,T2,T3,T4,T5 tool
    class EB1,EB2,EB3 extbiz
    class EL1,EL2 extllm
    class WM,EM,KB mem

图 3.1 · 7 主层主调用链。⑥A 业务 API 仅由 Tools 调用；⑥B LLM 推理服务允许 Sub-Agent 直接调用。

Master · 1

编排控制中心

仅负责任务编排、调度、状态管理与 Trace 写入，不执行业务计算。采用 Orchestrator-Workers + Evaluator-Optimizer 复合模式。

Workflow Engine：9 步 DAG 调度
State Machine：13 状态持久化
Dispatcher：分发任务至 Sub-Agent
Context Pack Builder：构建上下文最小子集

Sub-Agents · 7

专用业务 Agent

每个 Sub-Agent 选用 Tool Use / Reflection / Prompt Chaining / Orchestrator-Workers / Evaluator-Optimizer 五种 workflow 模式之一。

S1 Amazon KW · 品类至 ITK 与扩展词映射
S2 Social KW · 5 平台搜索词推荐
S3 Social Collection · 5 平台数据采集
S4 VOC Insight · ABSA 多维度分析
S5 Cross-Analysis ⭐ · 4 Worker 跨源融合
S6 Report Gen · 4 章 HTML 报告生成
S7 Evaluation · 6 维 LLM-as-Judge

Tools · 5

业务能力封装

遵循 ACI 五原则：读写分离、参数防误用、稳定返回、示例覆盖、边界声明。每个 Tool 仅承担一类原子动作。

amazon-keyword-mapper
social-keyword-gen
social-collect-request
consumer_insight · VOC API
consumer-insight-gen

3.2 横切层（Evaluation 与 Observability）

两个横切层独立于主调用链，每次 Sub-Agent 与 Tool 调用都会被横切层捕获。Evaluation 层负责质量评估与失败回退，Observability 层负责 Trace、Cost 与告警。

flowchart LR
    subgraph CHAIN["主调用链每一次调用"]
      direction LR
      ST1["Master 调度"]
      ST2["Sub-Agent 执行"]
      ST3["Tool / LLM 调用"]
      ST1 --> ST2 --> ST3
    end

    subgraph EVAL["⑧ Evaluation 横切"]
      direction TB
      SC["Self-Check C1-C7"]
      EVA["Evaluator Agent · 6 维评分"]
      BC["Bad Case 闭环"]
    end

    subgraph OBS["⑨ Observability 横切"]
      direction TB
      TR["Trace Recorder"]
      COST["Cost Aggregator"]
      ALERT["Alerting · 飞书告警"]
    end

    CHAIN -. 每次调用打点 .-> EVAL
    CHAIN -. 每次调用打点 .-> OBS

    EVAL == "失败回退 / 改进信号" ==> CHAIN
    OBS == "异常告警" ==> CHAIN

    classDef chain fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef eval fill:#dc2626,stroke:#7f1d1d,color:#ffffff
    classDef obs fill:#0891b2,stroke:#155e75,color:#ffffff

    class ST1,ST2,ST3 chain
    class SC,EVA,BC eval
    class TR,COST,ALERT obs

图 3.2 · 横切层独立于主调用链，按"打点 + 反向干预"模式运作。

3.3 9 层架构职责一览

7 主层（纵向调用链）与 2 横切层（横向贯穿所有调用）的角色、技术抓手与失败影响域汇总。

层	角色	关键技术抓手	失败影响域
① 用户层	请求源	—	仅本次请求
② 接入层	API / Web / Email	REST + WebSocket + SMTP	单 task
③ Master Agent	编排 / 状态机	Workflow Engine + State Machine + Dispatcher + Context Pack Builder	单 task
④ Sub-Agent	7 专用 Agent	5 种 workflow 模式按需选用	该 Sub-Agent 链路
⑤ Tools	业务封装（5）	ACI 原则 + 读写分离 + 参数防误用	该 Tool 调用
⑥A 业务外部服务	数据源 / 投递	TikHub / Amazon Data / Object Storage 仅 Tools 调	该数据源不可用
⑥B LLM 推理服务	推理引擎	Claude / Aliyun Qwen Sub-Agent 直调	该 Sub-Agent 推理不可用
⑦ Memory	三层存储	Redis + PostgreSQL + Qdrant	复用率与成本
⑧ Evaluation 横切	7 自检 + Evaluator + Bad Case 闭环	自检前置 + LLM-as-Judge + 迭代回流	质量信号回流
⑨ Observability 横切	Trace + Cost + Alert	全链路 trace_id + 飞书告警	监控盲区

04 · WORKFLOW ORCHESTRATION

任务编排：9 步主链 + 3 处 HITL + 7 处自检

前一节描述静态架构，本节描述动态执行。系统将传统调研流程显式化为 9 个机器可执行步骤，每步均明确输入、处理、输出与自检规则。3 处 HITL 卡点设置在关键决策节点，提供人工兜底，并为后续版本的自动化预留迁移路径。

4.1 总流程图

蓝色为 Action 动作节点；黄色为可直接消费的 Output 产出；红色为需自检的 Review 产出；绿色为 Self-Check 自检节点；橙色为 HITL 人工卡点。Step 5a 与 Step 5b 并行启动，C3 与 C4 同时通过后才进入 Step 6（Cross-Analysis）。

flowchart TD
    USR[/"用户输入
category + marketplace
+ optional params"/]:::stage --> M0["Step 1
Master Agent · 解析与校验"]:::action
    M0 --> R0(["task_id 生成
+ 状态初始化"]):::output

    R0 --> S1["Step 2
Amazon Keyword Agent"]:::action
    S1 --> R1{{"Amazon ITK + 扩展关键词包"}}:::review
    R1 --> C1["C1 · 自检 keyword
英文 / 拼写 / 品类覆盖"]:::check

    C1 --> S2["Step 3
Social Keyword Agent"]:::action
    S2 --> R2{{"5 平台搜索关键词"}}:::review
    R2 --> C2["C2 · 自检 search keywords
覆盖度 / 平台适配"]:::check

    C2 --> H1{{"HITL 1 · 关键词确认"}}:::hitl

    H1 -->|通过| FORK(("并行分发")):::fork

    FORK -->|分支 A| S3["Step 5a
Social Collection Agent
5 平台采集 ≈ 1h"]:::action
    S3 --> R3(["社媒 data_pack"]):::output
    R3 --> C3["C3 · 自检社媒数据质量
样本数 / 平台覆盖 / 转录率"]:::check

    FORK -->|分支 B| S4["Step 5b
VOC Insight Agent
ABSA 分析 ≈ 2h"]:::action
    S4 --> R4{{"VOC insight"}}:::review
    R4 --> C4["C4 · 自检 VOC 质量
aspect 数 / sample / 分布"]:::check

    C3 --> JOIN(("汇合")):::join
    C4 --> JOIN
    JOIN --> S5["Step 6
Cross-Analysis Agent ⭐
4 Worker 跨源融合"]:::cross
    S5 --> R5{{"融合结论 + 草稿 Personas
+ 证据链"}}:::review
    R5 --> C5["C5 · 自检 Cross-Analysis
融合数 / 证据链 / 置信度"]:::check

    C5 --> H2{{"HITL 2 · Persona 边界确认"}}:::hitl

    H2 -->|通过| S6["Step 7
Report Gen Agent
Markdown 4 章"]:::action
    S6 --> R6{{"Markdown 报告"}}:::review
    R6 --> C6["C6 · 自检 Markdown
4 章 / Persona 字段"]:::check

    C6 --> S7v["Step 8
HTML 渲染 + 图表"]:::action
    S7v --> R7{{"HTML 报告"}}:::review
    R7 --> C7["C7 · 自检 HTML
渲染 / 对齐 Markdown"]:::check

    C7 --> S8["Step 9
Evaluator Agent
6 维评分"]:::action
    S8 --> R8(["质量评分 + 改进建议"]):::output
    R8 -->|"评分 ≥ 4"| H3{{"HITL 3 · 终稿确认"}}:::hitl
    R8 -->|"评分 < 4"| S6

    H3 -->|通过| DELIV["邮件投递
+ HTML 静态归档"]:::deliver
    DELIV --> END(["交付完成"]):::output

    classDef stage fill:#78716c,stroke:#44403c,color:#ffffff
    classDef action fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef output fill:#fbbf24,stroke:#b45309,color:#1c1917
    classDef review fill:#dc2626,stroke:#7f1d1d,color:#ffffff
    classDef check fill:#10b981,stroke:#047857,color:#ffffff
    classDef hitl fill:#f97316,stroke:#c2410c,color:#ffffff
    classDef cross fill:#7c3aed,stroke:#5b21b6,color:#ffffff
    classDef fork fill:#06b6d4,stroke:#0e7490,color:#ffffff
    classDef join fill:#06b6d4,stroke:#0e7490,color:#ffffff
    classDef deliver fill:#059669,stroke:#047857,color:#ffffff

图 4.1 · 9 步主链与并行分支。Step 5a / 5b 并行执行后于 Step 6 收敛。

4.2 9 步主链拆解

每一步均定义输入、处理、输出与自检规则，作为 Sub-Agent 实施的工程基线。

#	步骤	输入	处理	输出	自检
1	输入校验 Master 解析	用户 payload	字段合法性 / 权限 / 配额	task_id + 初始化状态	—
2	Amazon Keyword Tool Use + Reflection	category_cn/en/img	调 amazon-keyword-mapper	Amazon ITK + 扩展关键词包	C1
3	Social Keyword Tool Use + AI Filter	Amazon 关键词	调 social-keyword-gen + LLM 过滤	5 平台搜索关键词	C2
—	HITL 1 人工卡点	关键词包	研究员审阅 / 修订	确认后关键词	人工
4	Social Collection Tool Use + SSE 流式	5 平台关键词	调 social-collect-request 跨平台采集	social_data_pack	C3
5	VOC Insight（可选） Tool Use + Reflection · 与 Step 4 并行	ASIN 池	ABSA 多维度分析	VOC insight	C4
6	Cross-Analysis ⭐ Orchestrator-Workers (4)	VOC + Social + KB	跨源融合 / 冲突识别 / 归因 / 置信度	cross_result + 草稿 Persona	C5
—	HITL 2 人工卡点	草稿 Persona	研究员确认 Persona 边界	确认后 Persona	人工
7	Report Gen Prompt Chaining + Reflection	cross_result + Persona	4 章顺序生成 + 自我审阅	Markdown 报告	C6
8	HTML 渲染模板渲染	Markdown	模板渲染 + 图表注入	HTML 报告	C7
9	Evaluator + 投递 Evaluator-Optimizer	报告	6 维评分 → HITL 3 → 邮件投递	邮件 + HTML 归档	—

4.3 并行设计与 HITL 定位

消费者洞察任务需要并行回答三类问题：用户购后反馈（VOC）、社媒传播（Social）、人群与决策切分（Persona）。三者数据源、分析方法、产出形态不同，串行执行将产生不必要的阻塞。Step 5a / 5b 并行 + Step 6 收敛是端到端时长控制的主要设计抓手。HITL 1 / 2 / 3 分别守住"输入边界、人群切分、终稿质量"三个不可逆决策节点。

05 · MEMORY DESIGN

记忆设计：三层 Memory + Context Pack

Sub-Agent 通过 Retrieval 调用

用途

领域知识资产化，支撑跨品类知识迁移

5.2 Memory 写入规则

Memory 一旦被低质内容污染，下游会被持续误导。系统通过四条强制写入规则控制污染传播。

规则	说明
① 仅写入已通过自检（C1-C7）的内容	Sub-Agent 输出在自检通过前不进入 Memory，避免幻觉传播至下游
② 写入前执行 schema 校验	每类 Memory 定义结构化 schema，缺字段或类型不符直接拒绝
③ 不写入原始 LLM 草稿	所有原始 LLM 中间输出仅在 Working Memory 暂存，task 结束后过期
④ KB 入库需 Evaluator 评分 ≥ 4/5	跨 task 共享内容须经过质量评估，避免低质洞察被复用放大

5.3 Context Pack 设计原则

Context Pack 是 Master Agent 注入给每个 Sub-Agent 的上下文最小子集。设计目标是在保证语义完整的前提下控制 Token 成本与版本可追溯性。

原则	说明	反例
① 最小必要	仅注入 Sub-Agent 完成本次任务必须的字段	注入完整 task 历史输出
② 引用而非内嵌	大对象通过 Memory key 指针引用，按需取	将完整原始社媒数据塞入 prompt
③ 版本化	每个 Context Pack 标记 prompt_version，支持 diff 与回放	修改 prompt 后无法对比历史结果
④ 输出契约前置	Context Pack 中包含 expected output schema	由 Sub-Agent 自由决定输出格式
⑤ Retrieval Hints 显式	需从 KB 检索的字段在 Context Pack 中显式声明	由 Sub-Agent 自行判断检索时机

06 · QUALITY LOOP

质量闭环：Detect → Capture → Triage → Iterate

系统将质量保障设计为四步闭环：发现失败信号、结构化捕获上下文、分诊到错误类型、按类型选择迭代抓手。该机制使 bad case 从一次性事件转化为可分类、可量化、可分配的迭代项。

6.1 闭环全景图

闭环的四个阶段独立成模块：每个 Bad Case 在产生时自动捕获结构化字段，分诊到 6 类错误中的唯一一类，再按错误类型路由至对应的迭代抓手。

flowchart LR
    subgraph DETECT["① Detect 发现"]
      D1["Self-Check
C1-C7 失败"]
      D2["Evaluator
评分 < 4"]
      D3["HITL 1/2/3
用户拒绝"]
      D4["用户事后反馈
邮件 / 飞书"]
    end

    subgraph CAPTURE["② Capture 捕获"]
      C1["trace_id
+ Context Pack
+ prompt_version
+ 失败输出
+ 失败原因"]
      C2[("episodic_memory
.bad_cases 表")]
      C1 --> C2
    end

    subgraph TRIAGE["③ Triage 分诊"]
      T1["A · LLM 幻觉"]
      T2["B · 数据质量"]
      T3["C · Prompt 设计"]
      T4["D · Context 缺失"]
      T5["E · Tool bug"]
      T6["F · 边缘 case"]
    end

    subgraph ITERATE["④ Iterate 迭代"]
      I1["加 Guardrail
护栏"]
      I2["升级自检阈值"]
      I3["改 Sub-Agent
Prompt"]
      I4["扩展
Context Pack"]
      I5["修复 Tool
+ 改 SKILL.md"]
      I6["加进 Eval Set
+ 沉淀到 KB"]
    end

    DETECT --> CAPTURE
    CAPTURE --> TRIAGE
    T1 --> I1
    T2 --> I2
    T3 --> I3
    T4 --> I4
    T5 --> I5
    T6 --> I6

    classDef d fill:#fef3c7,stroke:#b45309,color:#78350f
    classDef cap fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e
    classDef tri fill:#fce7f3,stroke:#be185d,color:#831843
    classDef it fill:#dcfce7,stroke:#16a34a,color:#14532d

    class D1,D2,D3,D4 d
    class C1,C2 cap
    class T1,T2,T3,T4,T5,T6 tri
    class I1,I2,I3,I4,I5,I6 it

图 6.1 · 质量闭环四阶段。Triage 至 Iterate 的映射为多对一固定路由。

6.2 Bad Case 的 4 类来源

系统区分 Evals 与 Bad Case 两个概念：Evals 指评估机制，Bad Case 指评估输出的失败样本。Evals 仅是 Bad Case 4 类来源中的一类，其余三类分别来自人工卡点与用户反馈。

SOURCE 01 · OBJECTIVE EVAL

来源 1：自检 C1-C7（嵌入式硬性规则）

每个 Sub-Agent 输出后由代码执行规则检查——4 章是否齐全、Persona 8 字段是否齐、引用格式是否合规、关键词是否覆盖品类核心叫法等。属 Objective 类 evals。

SOURCE 02 · SUBJECTIVE EVAL

来源 2：Evaluator Agent（LLM-as-Judge）

报告终稿前执行 6 维评分（数据完整性 / 准确性 / 新颖性 / 跨源一致性 / 证据充分性 / 可读性），每维 0-5，总分 ≥ 4 通过。属 Subjective 类 evals。

SOURCE 03 · HUMAN GATE

来源 3：HITL 1/2/3 拒绝

3 处人工卡点（关键词 / Persona 边界 / 终稿）由研究员或业务方做出否决，并附拒绝原因。该来源信号密度高，标注为高价值。

SOURCE 04 · POST-DELIVERY

来源 4：用户事后反馈

报告交付后，用户经邮件、飞书或反馈接口提供反馈。task 已结束，但相关信息仍写入 bad_cases 表，关联原 task_id 用于后续分析。

6.3 两条时间线：实时（任务内）与离线（跨任务）

同一个 Bad Case 同时进入两条独立时间线，实时线保障当前任务交付质量，离线线驱动系统级迭代。

REAL-TIME · 任务内

保障当前任务交付质量

失败立即触发回退动作——单点重跑、Reflection 重写或人工升级，由 Master 状态机统一管控。

触发动作：
· C1-C7 自检失败 → 重试 ≤ 3 次 / 升级 HITL
· Evaluator < 4 → 触发 Reflection（≤ 2 轮）/ HITL 3
· HITL 拒绝 → 收集人工备注后回退至对应 Sub-Agent
· 整链路失败 → 回滚至上一 Checkpoint 重跑

OFFLINE · 跨任务

驱动系统级持续迭代

所有 Bad Case 写入 bad_cases 表，按错误类型分诊，按类型路由迭代抓手。

三层节奏：
· 每日（自动）→ bad cases 入库 + 错误类型自动分类
· 每周（人工）→ Triage review 会议 → 输出迭代 ticket
· 每月（回归）→ 用最新 Eval Set 跑 regression，对比 prompt 版本

闭环达成判据：同一类 bad case 在第 N 周后不再出现

6.4 6 类错误与对应迭代抓手

每个 bad case 必须分诊到唯一一类。不同错误类型的修复路径完全不同，分诊是迭代抓手有效性的前置条件。

A · HALLUCINATION

LLM 幻觉

Sub-Agent 输出无证据的"创造性"内容（如 Persona 描述出现品类中不存在的功能）

抓手：加 Guardrail（forbidden_terms / require_citations）

B · DATA QUALITY

数据质量问题

上游数据不足、噪声或偏差（如社媒采集仅返回 50 条样本，不足以支持后续分析）

抓手：升级 C3/C4 自检阈值，补充 Tool 校验

C · PROMPT

Prompt 设计问题

当前 prompt 无法稳定产出预期格式（如 Persona 8 字段周期性缺失 2-3 个）

抓手：升级 Sub-Agent Task Prompt（升 prompt_version）+ A/B 评估

D · CONTEXT

Context 缺失

Sub-Agent 未获得必要的上下文（如 Cross-Analysis 在未注入 KANO 词典的情况下执行分类）

抓手：扩展 Context Pack（补 retrieval_hints / upstream_artifacts）

E · TOOL BUG

Tool bug

Tool 实现错误或 SKILL.md 描述不清（如 social-collect-request 在 DE 市场返回 EN 语言数据）

抓手：提交 Tool repo issue，修订 SKILL.md description

F · EDGE CASE

边缘 case

业务输入超出当前覆盖范围（如品类粒度过宽，"宠物用品"等）

抓手：加入 Eval Set（regression test），沉淀到 KB

07 · GUARDRAILS & RECOVERY

5 类 Guardrails + 4 路恢复机制

Guardrails 在主调用链上的关键节点执行硬性检查，覆盖数据质量、洞察质量、引用证据、幻觉控制与成本性能五个维度。任一类 Guardrail 失败时，系统按严重程度递增的顺序选择恢复路径。

7.1 Guardrails 总览

5 类 Guardrails 沿任务执行流串联——从输入数据进入到最终输出，每一步都有对应的护栏检查。

flowchart LR
    INPUT["输入数据"] --> G1["① 数据质量
Guardrails"]
    G1 --> AGENT["Sub-Agent 执行"]
    AGENT --> G2["② 洞察质量
Guardrails"]
    G2 --> G3["③ 引用证据
Guardrails"]
    G3 --> G4["④ 幻觉控制
Guardrails"]
    G4 --> G5["⑤ 成本&性能
Guardrails"]
    G5 --> OUT["输出"]

    G1 -.fail.-> RECOVERY["错误恢复"]
    G2 -.fail.-> RECOVERY
    G3 -.fail.-> RECOVERY
    G4 -.fail.-> RECOVERY
    G5 -.fail.-> RECOVERY

    RECOVERY --> RETRY["重试"]
    RECOVERY --> FALLBACK["降级"]
    RECOVERY --> HITL["HITL 升级"]
    RECOVERY --> ROLLBACK["Workflow 回滚"]

    classDef io fill:#78716c,stroke:#44403c,color:#ffffff
    classDef agent fill:#1e40af,stroke:#1e3a8a,color:#ffffff
    classDef guard fill:#dc2626,stroke:#7f1d1d,color:#ffffff
    classDef recover fill:#f59e0b,stroke:#b45309,color:#1c1917

    class INPUT,OUT io
    class AGENT agent
    class G1,G2,G3,G4,G5 guard
    class RECOVERY,RETRY,FALLBACK,HITL,ROLLBACK recover

图 7.1 · 5 类 Guardrails 串联于主调用链，失败统一进入错误恢复机制。

GUARD 01

数据质量

VOC 评论 ≥ 50
社媒帖子 ≥ 100
平台覆盖 ≥ 3
转录成功率 ≥ 80%
数据时效 ≤ 12 月
Aspect 数 ≥ 5

GUARD 02

洞察质量

Fused signal ≥ 3
Persona 数 2-3
Persona 8 字段齐全
KANO 4 类齐
Finding high tier ≥ 3
Evaluator ≥ 4/5

GUARD 03

引用证据

Citation 格式 100%
Per-finding 引用 ≥ 3
Per-Persona 字段引用 ≥ 1
Evidence ID 可追溯
数字必含口径

GUARD 04

幻觉控制

forbidden_terms 黑名单
require_citations 强制
关键判断双源验证
禁主观词汇
Evidence 原文摘录
LLM-Judge 抽样核对

GUARD 05

成本&性能

Token ≤ 50K in / 30K out
单 task ≤ ¥100（告警阈值）
Sub-Agent 内 SLA P95
端到端 ≤ 12h（v0.1）
Memory 单 key ≤ 10MB

7.2 错误恢复 4 路径

任一类 Guardrail 失败时，系统按"重试 → 降级 → HITL 升级 → Workflow 回滚"的严重程度递增顺序选择恢复路径，避免不必要的人工介入。

↻

重试

指数退避 10s/30s/90s 共 3 次。LLM 超时可切换备用模型（Claude ↔ Qwen）。

↘

降级

单平台失败时跳过并标记 warning。无 ASIN 池时切至 has_voc=false 单源模式。

👤

HITL 升级

3 次重试仍失败时升级至 HITL，由业务方或研究员人工介入决策。

⟲

Workflow 回滚

每个 Step 完成后写 Checkpoint。整链路失败时回滚至上一 Checkpoint 续跑。

7.3 与 Bad Case 闭环的关系

Guardrails 与上一节的 Bad Case 闭环承担互补职能：Guardrails 针对已知错误类型设置硬性下限，Bad Case 闭环针对未知错误模式驱动系统级改进。Guardrails 失败时同时触发恢复路径与 Bad Case 写入，两者通过同一 trace_id 关联。

08 · OUTPUT SPECIFICATION

输出规格：报告结构、Persona Schema 与决策框架

报告每个字段均标注生成逻辑——LLM 推理、工程管线或规则模板。该标注是质量回溯与定向优化的前置条件，使下游可识别"哪些数字来自统计可查、哪些结论来自模型推理"。

8.1 标准报告章节结构

章节	核心内容	生成逻辑	设计意图
管理层摘要	战略结论 / 核心发现 / 最大风险 / 数据速览	LLM 全文 Review	支持决策者快速获取结论；最后写最先读
Ch.1 数据口径	数据范围 / 来源 / 样本构成 / 触达量	PIPELINE	建立统计学边界，前置数据信心
Ch.2 三圈层分析	核心圈（VOC）/ 中间圈（Social）/ 外围圈（文化）/ 跨圈层验证	LLM PIPELINE	从微观体验到宏观叙事的完整地图
Ch.3 Persona Cards	9 字段完整 Schema（命名 → 边界 → JTBD → Proof Kit）	LLM RULE	可执行的人群画像，从洞察直达 PDP
Ch.4 购买核心逻辑	从 8 种消费决策类型中选定主导逻辑	LLM RULE	锚定品类的消费决策元认知
Ch.5 Key Findings	3-5 条可行动洞察，每条关联 Persona + 证据	LLM	从数据到行动的最后一公里

8.2 Persona Schema 设计理念（9 字段）

系统采用处方性 Persona Schema：每个字段均强制对齐到可执行的业务动作，9 个字段构成"定义 → 决策 → 落地"三段式闭环结构。

FIELDS 1-3 · DEFINITION

定义层

命名 · 场景 + 约束，禁纯性格形容词
角色 + 场景 + 约束 · 30 字描述用户卡点
一句话定义 · Who + Scene + Job + Anxiety

回答：这是谁

FIELDS 4-6 · DECISION

决策层

边界规则 · 3-5 条可投放的判定规则
决策驱动 · Why buy + Why stuck
JTBD · 主任务 + 购买前 / 使用中 / 最坏情形

回答：怎么找 + 怎么打动

FIELDS 7-9 · GROUNDING

落地层

反对点 & 成交条件 · 3 个 Objection + Done Criteria
洞察-需求-功能映射 · Insight → Need → Function → KANO
Proof Kit · PDP 模块 + 内容模块

回答：产品页 / 内容该放什么

系统对 Persona 9 字段执行 5 条自动一致性校验：边界 ↔ JTBD 一致、Objections ↔ Done Criteria 闭环、Done Criteria ↔ Proof Kit 可落地、决策驱动 ↔ Key Findings 映射存在、映射表 ↔ 上游字段可追溯。

8.3 购买核心逻辑框架（8 种消费决策类型）

不同品类的消费者使用不同底层逻辑做决策。该框架支撑系统在生成具体洞察前先锚定品类的决策元认知。

类型	核心定义	典型品类	关键营销词
成本优先型	TCO 最小化	白牌日用品	"省 XX 元" / "平替"
效率赎买型	用金钱兑换时间	即时配送、SaaS	"即刻" / "一键"
风险厌恶型	为避免不可逆后果支付溢价	安全座椅、医疗	"零事故" / "终身质保"
身份信号型	通过消费传递阶层归属	奢侈品、潮牌	"身份象征" / "社交货币"
情绪兑付型	为即时多巴胺买单	盲盒、即时娱乐	"治愈系" / "悦己"
决策外包型	将筛选成本转移给权威	家电、母婴	"销量第一" / "闭眼入"
能力投资型	长线人力资本投资	知识付费、健身	"认知升级" / "复利"
信息套利型	为未普及新体验支付早期溢价	科技新品、限量联名	"首发" / "信息差"

事后人工归因实施成本低，但缺少可复现性与可量化性——研究员的"质量差"反馈无法对应到具体 Sub-Agent、prompt 版本或 Context 字段，导致迭代无法系统化。

结论

结构化捕获将"报告质量差"这一模糊反馈转化为可分诊、可分配、可量化的迭代项；每周 Triage 节奏与每月回归评估构成完整闭环。

消费者声音分散于电商与多个社媒平台

Multi-Agent 编排 + 专有分析框架 + 质量闭环

端到端 12h、单 Report ¥600、4 章齐全率 100%