# GitHub AI VOC / Review Intelligence 对标报告

> 调研快照：2026-08-06  
> 对标对象：`E:\workspace\Saas-voc` 的反馈收件箱、AI VOC 洞察历史与 ActionItem 流程  
> 资料口径：仅使用项目官方 GitHub README、仓库源码、测试与 GitHub 仓库元数据；Star 数为调研时快照，不作为唯一质量判断。

## 1. 结论先行

当前系统已经具备一条可运行的主链路：

```text
反馈收件箱
  -> 筛选并审阅原始评价
  -> AI / deterministic 洞察
  -> AnalysisRun 历史保存与恢复
  -> 洞察引用 evidenceIds
  -> 创建 ActionItem
```

本轮源码复核还确认，前端创建 ActionItem 时已经携带：

- `sourceAnalysisId`
- `sourceInsightId`
- `evidenceIds`
- `validationMetric`

因此下一步不应重做收件箱或再建一套孤立的 AI 卡片，而应把已有链路升级为四个可审计闭环：

1. **输入可信**：多来源反馈进入统一事件模型，先归一化、去重、脱敏，再进入 AI。
2. **结论有据**：每条洞察只能引用本次 AnalysisRun 输入中的证据 ID，服务端再次校验。
3. **决策可审计**：`needs_validation`、人工确认、发布和行动创建是不同业务状态。
4. **结果可回流**：行动完成后记录验证指标、基线、结果与结论，作为下一轮分析输入。

最值得组合采用的路线不是复制某一个项目，而是：

```text
AWS 的连接器与统一反馈事件
  + ReviewRadar 的规则优先、脱敏和 P0/P1 分类
  + OpenVoC / Qiaomu 的证据引用与稳定历史页面
  + Microsoft 的 grounded retrieval 与 schema validator
  + Formbricks 的 Summary / Responses 双层工作台
  + Langfuse 的运行追踪、版本和评估
  + 当前 Saas-voc 的人工行动流
```

## 2. 当前 Saas-voc 基线

### 2.1 已具备

| 能力 | 当前实现 | 判断 |
| --- | --- | --- |
| 原始证据收件箱 | 正文、来源、评分、主题、同类样本、置信表达、搜索与筛选 | 已形成专业工作台基础 |
| 证据回跳 | `reviewId` 查询参数恢复反馈详情 | 已可审阅单条证据 |
| AI 输入边界 | scope、sentiment、sample limit、来源/主题统计、稳定 evidence ID | 已具备输入审计信息 |
| 结构化洞察 | finding、user need、severity、opportunity status、recommendation、validation metric | 已具备可执行结果结构 |
| Grounding | AI 输出 evidence ID 白名单过滤，无有效引用的洞察不进入结果 | 已在前端生成层生效 |
| 规则降级 | deterministic 聚合保留证据 ID，并统一标记 `needs_validation` | 方向正确 |
| 运行历史 | AnalysisRun 创建、processing、completed/partial/failed、列表与恢复 | 已具备运行级历史 |
| 行动关联 | ActionItem 请求携带分析、洞察、证据与验证指标 | 前端契约已具备 |
| 操作确认 | 用户点击并提交行动表单后才创建 ActionItem | 有显式用户动作，但不是独立确认记录 |

### 2.2 当前关键缺口

| 缺口 | 风险 | 对标启发 |
| --- | --- | --- |
| 证据约束主要在前端 | 绕过前端或历史数据写入时可能出现跨运行、未知或空 evidence ID | OpenVoC、Microsoft、Langfuse |
| AI 前脱敏未成为固定处理阶段 | 原始反馈可能携带邮箱、电话、地址或账号信息 | ReviewRadar、Microsoft |
| AnalysisRun 是运行状态，不是洞察发布状态 | `completed` 容易被误解为“业务结论已确认” | Langfuse 的 desired/effective status 分离 |
| 没有独立人工决策记录 | 无法查询谁确认、为何驳回、要求补什么证据 | OpenVoC roadmap、当前业务审计 |
| ActionItem 关联字段虽已发送，但需服务端引用完整性和幂等约束 | 重复创建、孤儿引用或跨 workspace 引用仍可能发生 | OpenVoC action draft、Langfuse API 约束 |
| 缺少行动效果记录 | 链路停在“任务已创建/已完成”，无法证明问题改善 | ADK backlog、产品实验思路 |
| 缺少稳定的 AI 回归数据集 | 更换模型、提示词或聚类规则后无法判断质量变化 | ADK eval、ReviewRadar golden dataset、Langfuse datasets |
| 数据源接入仍与业务代码耦合 | 新增平台可能重复改前端、后端和配置 | AWS plugin manifest |

## 3. 项目总览

| 项目 | 快照活跃度 | 类型 | 本项目最值得借鉴的部分 | 适用层级 |
| --- | ---: | --- | --- | --- |
| [OpenVoC Radar](https://github.com/IreliaWuW/openvoc-radar) | 0 Star，2026-06 新项目，MIT | 本地 VOC MVP | normalize → dedupe → classify → persist；洞察、报告、行动草稿始终保留 source ticket IDs | 业务链路样板，不是成熟度基准 |
| [Qiaomu App Review Insights](https://github.com/joeseesun/qiaomu-app-review-insights) | 217 Star，MIT | App Review Intelligence | 稳定缓存页、评论历史、版本风险、来源分布、map/reduce 式证据样例 | 评论洞察与 UI 样板 |
| [ReviewRadar](https://github.com/abhishekdubey331/ReviewRadar) | 0 Star，2026-03 推送，MIT | MCP Review Intelligence | 规则 + 选择性 LLM、PII 清理、P0/P1、趋势、周报、golden dataset | AI 前处理与质量规则样板 |
| [Microsoft Conversation Knowledge Mining](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) | 461 Star，2026-08-06 有推送，MIT | Grounded knowledge mining | 混合检索、SQL、引用、schema-aware dashboard、LLM plan validator | Grounding 与自适应洞察样板 |
| [AWS Voice of Customer Data Lake](https://github.com/aws-samples/sample-voice-of-customer-datalake) | 22 Star，2026-08 活跃，MIT-0 | 多源 VOC 数据平台 | manifest 驱动连接器、统一 feedback schema、队列、去重、LLM 失败可观测 | 数据接入与标准化样板 |
| [ADK Product Engineers / VoC Insights](https://github.com/addyosmani/adk-product-engineers) | 43 Star，未检测到仓库许可证 | VOC Agent 示例 | deterministic clustering、memory、趋势、backlog artifacts、eval | 分析编排与回归样板 |
| [Formbricks](https://github.com/formbricks/formbricks) | 12,727 Star，2026-08-06 活跃，混合许可证 | 成熟反馈/问卷平台 | Summary / Responses 双视图、强筛选、可配置表格、单条响应详情 | 专业工作台 UI/IA 样板 |
| [Langfuse](https://github.com/langfuse/langfuse) | 32,611 Star，2026-08-06 活跃，核心 MIT/EE 分区 | LLM 工程平台 | trace、prompt version、dataset schema、experiment/eval rule、effective status | AI 运行与评估样板 |

说明：OpenVoC Radar 与 ReviewRadar 的社区规模很小，本报告只采用其代码中可验证的业务机制，不把它们视为生产成熟度证明。Formbricks 和 Langfuse 不是 VOC 洞察产品，但其工作台和 AI 工程机制对本项目有高参考价值。

## 4. 逐项目对标

### 4.1 OpenVoC Radar

官方依据：[README](https://github.com/IreliaWuW/openvoc-radar/blob/main/README.md)、[架构](https://github.com/IreliaWuW/openvoc-radar/blob/main/docs/ARCHITECTURE.md)、[报告与行动草稿代码](https://github.com/IreliaWuW/openvoc-radar/blob/main/backend/app/services/reports.py)、[Issue Clusters 页面](https://github.com/IreliaWuW/openvoc-radar/blob/main/frontend/app/clusters/page.tsx)。

**可借鉴的业务机制**

- 明确的四段管线：`normalize -> dedupe -> classify -> persist`，先确定事实层，再做 AI 分类。
- `VocItem`、cluster、weekly report 和 product action draft 都携带 `source_ticket_ids`。
- 行动草稿按 `voc_item_id + draft_type` 去重，避免同一洞察重复生成同类草稿。
- OpenAI 结构化结果校验失败时回退 mock/deterministic 分类，运行不因模型输出格式中断。
- README 主动标注聚类和相似度只是 placeholder，避免把 demo 能力包装成生产语义聚类。

**UI / 信息架构做法**

- 顶层导航拆为 Overview、Trends、Issue Clusters、Reports、Product Actions、Settings。
- cluster 卡片直接展示严重度、关联数量和 source ticket ID，而不是只给摘要。
- Product Actions 先展示可编辑的 bug / feature draft，强调“草稿”而不是自动创建正式任务。

**我们不应照搬**

- 同用户、时间窗和关键词的简单去重不足以处理中文评论、模板化评价和跨来源重复。
- cluster 页是卡片平铺，数据规模上升后扫描效率不如“表格/列表 + 详情侧栏”。
- action draft 没有负责人、验证指标、审批和效果回流，不足以替代当前 ActionItem。
- 本地 SQLite 与 mock 模式适合演示，不应成为多 workspace SaaS 的生产边界。

**映射到 Saas-voc**

- 保留当前 evidence ID 设计，并在服务端建立 `sourceAnalysisId + sourceInsightId + evidenceIds` 的引用校验。
- 给 ActionItem 增加服务端幂等键，避免同一洞察被重复提交成同类行动。

### 4.2 Qiaomu App Review Insights

官方依据：[README](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/README.md)、[缓存与生成](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/src/lib/appstore/cache.ts)、[评论历史](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/src/lib/appstore/review-history.ts)、[AI map/reduce](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/src/lib/analysis/ai-insights-service.ts)、[洞察卡片](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/src/components/app-review/insight-cards.tsx)、[版本诊断](https://github.com/joeseesun/qiaomu-app-review-insights/blob/main/src/components/app-review/version-diagnostics.tsx)。

**可借鉴的业务机制**

- 每个 App 生成稳定、可分享、可再次访问的缓存洞察页，不把一次 LLM 响应当临时聊天消息。
- 评论历史按 review ID 合并并原子写文件，避免增量抓取覆盖已有语料。
- AI 分析按 chunk 做 map，再按 `category + normalized title` reduce；样例保留 review ID 和 snippet。
- 同时保留 `reviews`、`allReviews`、source breakdown、diagnostics、model 和 generatedAt，结果页能解释样本边界。
- 版本维度展示评分、负向占比、问题热力图和情绪时间线，直接服务发布风险判断。

**UI / 信息架构做法**

- 洞察分为核心痛点、产品机会、正向信号、用户分层、版本风险、行动建议六类。
- 独立来源分布和版本诊断，帮助用户区分“洞察结论”和“数据口径”。
- ECharts 使用稳定高度、ResizeObserver 和无数据状态，避免图表布局跳动。
- 提供 regenerate 与缓存复用，用户能理解当前页面是历史结果还是新生成结果。

**我们不应照搬**

- 项目主要围绕 App Store，不能直接覆盖客服工单、问卷、社媒和国内电商评价。
- 仓库并存两套洞察结构：部分卡片使用自由文本 `evidence`，另一套 taxonomy 使用 review ID examples；我们应坚持唯一 evidence schema。
- 以 title 文本归并主题在同义词、多语言和短标题场景中容易产生碎片。
- 其行动建议停留在报告内容，没有当前 Saas-voc 的责任人、期限和状态流。

**映射到 Saas-voc**

- 在现有 AI 洞察历史上增加“版本/时间窗口对比”，优先显示新增、升温、缓解和复发主题。
- 历史恢复卡需要同时显示模型/规则模式、样本时间范围、来源分布和 evidence coverage。

### 4.3 ReviewRadar

官方依据：[README](https://github.com/abhishekdubey331/ReviewRadar/blob/main/README.md)、[架构](https://github.com/abhishekdubey331/ReviewRadar/blob/main/docs/architecture.md)、[聚类工具](https://github.com/abhishekdubey331/ReviewRadar/blob/main/src/tools/cluster_reviews.ts)、[PII 清理](https://github.com/abhishekdubey331/ReviewRadar/blob/main/src/utils/redact.ts)、[golden dataset](https://github.com/abhishekdubey331/ReviewRadar/blob/main/__tests__/fixtures/golden_dataset.json)。

**可借鉴的业务机制**

- 两阶段处理：Schema/limits、PII、规则和 severity precedence 在前，只有必要样本才路由 LLM。
- 输出采用严格 JSON schema，MCP Host 接收结构化结果，不依赖自然语言解析。
- P0/P1/P2/FYI 规则强调安全、支付、崩溃、性能等业务优先级，不只按情感负面程度排序。
- 持久化向量索引与 metadata，支持跨进程的语义搜索和诊断。
- golden dataset 明确每条 review 的 expected issue type 和 severity，适合做变更回归。

**UI / 信息架构做法**

- 该项目核心是 MCP tool IA：import、analyze、cluster、trend、search、weekly report。
- 它没有成熟 Web UI，因此适合学习“能力边界和返回结构”，不适合作为页面视觉基准。
- 周报输出按 P0/P1 和趋势变化组织，适合作为 Action Center 的管理摘要入口。

**我们不应照搬**

- 当前 PII 代码主要是邮箱、电话和坐标正则，无法覆盖姓名、账号、订单号、地址和中文语境。
- severity precedence 需要按本项目品类和业务风险配置，不能硬编码移动 App 分类。
- MCP-only 交互不适合需要证据审阅、人工确认和跨角色协作的 SaaS 主流程。
- 0 Star 小项目缺少大规模生产验证，工程机制应通过本项目自己的数据回归后采用。

**映射到 Saas-voc**

- 在 AI 网关调用前增加 `normalize -> pii_redact -> rule_tag -> llm` 固定阶段，并记录每阶段版本。
- 建立至少 50 条中文 golden feedback，覆盖未知证据 ID、低样本、重复反馈、P0 风险和无效文本。

### 4.4 Microsoft Conversation Knowledge Mining

官方依据：[README](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/README.md)、[统一检索引擎](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/src/api/modules/runtime/retrieval_engine.py)、[洞察 planner 与 validator](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/src/api/modules/insights/service.py)、[提示词](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/src/api/config/prompts.yaml)、[Insights 页面](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/src/app/src/pages/Insights.tsx)。

**可借鉴的业务机制**

- ChatAgent 同时调用语义检索与 SQL 结构化分析，回答既能找原文，也能计算真实聚合。
- 检索结果统一为 source kind、source name、source file 等字段，便于跨来源引用。
- LLM 先根据数据 schema 规划 KPI 和 chart，再由代码 validator 删除未知字段和非法图表。
- planner 明确排除 identifier、contact、PII 字段，不允许进入图表、KPI 和筛选。
- 对 field coverage 设置阈值，只让覆盖率足够的字段成为主指标。

**UI / 信息架构做法**

- Home、Explore、Insights 三个主面：数据接入、对话探索、结构化洞察职责分离。
- Insights 页按 headline、KPI、filter、insight cards、distribution/chart 和 evidence 组织。
- 使用响应式 grid、固定最小列宽、skeleton、empty/error/notice 状态，适合专业数据工作台。
- 问答支持引用，dashboard 支持 suggested questions，用户能从发现继续追问。

**我们不应照搬**

- Azure Search、SQL、Foundry Agent 和 Content Understanding 的完整栈成本与复杂度高于当前阶段。
- 完全 schema-aware 的动态 dashboard 容易产生视觉和指标漂移；核心 VOC 指标仍应由产品定义。
- README 自身明确该方案是加速器/PoC，生成内容仍需业务判断。
- 对话入口不能取代收件箱和洞察审批；它应是探索工具，不应直接改变业务状态。

**映射到 Saas-voc**

- 保持固定 VOC 工作台骨架，只允许 AI 在受控 schema 内建议图表和追问。
- 后续 Grounded Explore 同时调用 evidence search 与结构化统计 API，回答中返回可点击 review ID。

### 4.5 AWS Voice of Customer Data Lake

官方依据：[README](https://github.com/aws-samples/sample-voice-of-customer-datalake/blob/main/README.md)、[插件架构](https://github.com/aws-samples/sample-voice-of-customer-datalake/blob/main/docs/plugin-architecture.md)、[处理管线](https://github.com/aws-samples/sample-voice-of-customer-datalake/blob/main/docs/processing-pipeline.md)、[统一反馈 schema](https://github.com/aws-samples/sample-voice-of-customer-datalake/blob/main/voc-datalake/schemas/feedback-event.schema.json)、[反馈详情页](https://github.com/aws-samples/sample-voice-of-customer-datalake/blob/main/voc-datalake/frontend/src/pages/FeedbackDetail/FeedbackDetail.tsx)。

**可借鉴的业务机制**

- 每个数据源使用自包含插件；`manifest.json` 同时驱动基础设施、配置 UI、密钥和 setup 文案。
- manifest 由 Zod 校验，目录名必须与 plugin ID 一致，避免连接器配置漂移。
- 统一 feedback event 包含内部 ID、source ID、platform、channel、source URL、原文、时间和 LLM metadata。
- `feedback_id` 使用来源 ID 或稳定组合键生成，LLM 前先查重。
- Bedrock 失败时保留基础处理结果，并记录 processed with/without LLM、throttle 和 processing error 指标。

**UI / 信息架构做法**

- Settings 根据 manifest 动态渲染来源配置，连接器启停不占用业务页面。
- Feedback Detail 分为原文、分类、persona、问题分析、标签、metadata 和 similar feedback。
- 原文与 normalized/translated text 分开展示，避免用户误把转换文本当原声。
- Similar Feedback 作为详情页标签，不挤占收件箱主列表。

**我们不应照搬**

- S3、SQS、Lambda、DynamoDB、CDK 全套基础设施不适合直接移植到当前 Node/Angular 架构。
- 固定分类和 journey stage 必须做 workspace 配置与版本管理，不能成为全局硬编码。
- `direct_customer_quote` 等 LLM 字段需要绑定 source offset 或 evidence ID，不能只存一段模型生成文本。
- 动态连接器 UI 只能负责配置，不能让 manifest 控制核心权限和数据治理规则。

**映射到 Saas-voc**

- 先定义平台无关的 `NormalizedFeedbackEvent`，再让电商、App Review、客服和 CSV adapter 输出同一结构。
- 来源注册表可借鉴 manifest，但使用当前后端配置和权限体系实现，不引入 AWS 依赖。

### 4.6 ADK Product Engineers / VoC Insights

官方依据：[仓库 README](https://github.com/addyosmani/adk-product-engineers/blob/main/README.md)、[VoC README](https://github.com/addyosmani/adk-product-engineers/blob/main/python/agents/voc_insights/README.md)、[Agent 与 deterministic tools](https://github.com/addyosmani/adk-product-engineers/blob/main/python/agents/voc_insights/agent.py)、[eval cases](https://github.com/addyosmani/adk-product-engineers/blob/main/python/agents/voc_insights/eval/test_cases.jsonl)。

**可借鉴的业务机制**

- load、clean/dedupe、cluster、synthesize、artifact 是明确工作流，不让 LLM 同时承担所有步骤。
- deterministic keyword clustering 确保相同输入可复现，LLM 负责解释和建议。
- MemoryService 用于保存上次主题并回答“与上周相比有什么变化”。
- 输出 `themes.json` 与 `recommendations.csv`，把洞察和 backlog 作为可版本化 artifact。
- eval 关注主题稳定、不得编造引用、建议必须匹配主题、执行轨迹必须正确。

**UI / 信息架构做法**

- 该示例没有产品级 UI，但输出结构适合映射到“主题趋势、建议、验收标准”三个区域。
- artifact-first 比聊天记录更适合长期运营；当前 AnalysisRun result 可承担第一阶段 artifact。

**我们不应照搬**

- 默认 MemoryService 重启后丢失，不满足当前历史恢复要求。
- 关键词表和 20 条样本只能用于演示，不适合中文、多品类和同义表达。
- eval 只有 3 条高层案例，不能代替 evidence precision、schema pass rate 和人工一致性测试。
- 仓库未检测到明确许可证，不能直接复制源码进入本项目。

**映射到 Saas-voc**

- 将 `promptVersion + modelVersion + ruleVersion + taxonomyVersion` 写入 AnalysisRun。
- 把历史对比变成确定性统计：主题新增率、升温幅度、复发率、证据增量；LLM 只解释变化。

### 4.7 Formbricks

官方依据：[README](https://github.com/formbricks/formbricks/blob/main/README.md)、[Summary / Responses 导航](https://github.com/formbricks/formbricks/blob/main/apps/web/app/%28app%29/workspaces/%5BworkspaceId%5D/surveys/%5BsurveyId%5D/%28analysis%29/components/SurveyAnalysisNavigation.tsx)、[ResponseTable](https://github.com/formbricks/formbricks/blob/main/apps/web/app/%28app%29/workspaces/%5BworkspaceId%5D/surveys/%5BsurveyId%5D/%28analysis%29/responses/components/ResponseTable.tsx)、[Response detail modal](https://github.com/formbricks/formbricks/blob/main/apps/web/app/%28app%29/workspaces/%5BworkspaceId%5D/surveys/%5BsurveyId%5D/%28analysis%29/responses/components/ResponseCardModal.tsx)、[SummaryPage](https://github.com/formbricks/formbricks/blob/main/apps/web/app/%28app%29/workspaces/%5BworkspaceId%5D/surveys/%5BsurveyId%5D/%28analysis%29/summary/components/SummaryPage.tsx)。

**可借鉴的业务机制**

- 原始 responses 与 aggregate summary 使用同一套 filter context，证据与汇总口径一致。
- 服务端分页、筛选和导出，避免把全部反馈加载到浏览器后再处理。
- 表格列顺序、显隐、宽度和展开偏好可持久化，适合高频运营人员。
- 单条响应详情支持前后翻页，保留用户在当前筛选队列中的位置。

**UI / 信息架构做法**

- `Summary` 与 `Responses` 是同一分析对象的二级导航，先看总体，再下钻原声。
- ResponseTable 使用固定布局、列固定、列拖动、批量选择、下载和 skeleton。
- SummaryPage 组合 metadata、drop-off、impressions、filter 和各题型 summary，不把所有信息塞进一层卡片。
- 详情使用 modal/side detail，用户无需离开当前筛选上下文。

**我们不应照搬**

- Formbricks 以问卷和 response 为核心，无法直接表达主题聚类、证据链、洞察确认和行动效果。
- 当前系统不需要复制其问卷编辑器和大量题型组件。
- 仓库核心 AGPLv3，另有 EE 和 SDK 分区许可证；可学习 IA，不应直接复制受约束代码。
- 高自由度列配置应只用于证据表格，洞察主字段必须保持统一，避免每个用户看到不同结论结构。

**映射到 Saas-voc**

- AI 洞察页采用 `洞察摘要 / 原始证据 / 分析历史` 二级视图，三者共用同一筛选上下文。
- 收件箱桌面端可增加可配置密度和列偏好，但保留当前 queue + detail 的核心工作流。

### 4.8 Langfuse

官方依据：[README](https://github.com/langfuse/langfuse/blob/main/README.md)、[Trace API](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition/trace.yml)、[Dataset API](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition/datasets.yml)、[Evaluation Rules](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition/unstable/evaluation-rules.yml)、[Prompt Version](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition/prompt-version.yml)。

**可借鉴的业务机制**

- trace 将输入、输出、metadata、scores、observations、token、cost、latency、version 和 release 关联起来。
- prompt 有不可混淆的 version 与 label；`latest` 由系统管理，避免用户手工覆盖。
- dataset 支持 input schema 和 expected output schema，所有 dataset item 必须通过同一校验。
- evaluation rule 明确 target、filter、variable mapping、sampling 和 evaluator version。
- `enabled` 是用户期望状态，`status` 是系统校验后的有效状态；`enabled=true/status=paused` 能解释阻塞原因。

**UI / 信息架构做法**

- 从 trace 列表进入单次输入/输出，再查看 score、observation 和成本，适合作为 AnalysisRun 的技术详情抽屉。
- dataset、experiment、evaluation 和 prompt management 分开，避免把运营工作台变成 AI 配置页。
- 坏结果可以从 trace 进入 playground 复现，缩短提示词迭代路径。

**我们不应照搬**

- Langfuse 是通用 LLMOps，不具备 VOC 的证据确认、洞察发布和行动业务语义。
- ClickHouse、trace ingestion 和完整评估平台在当前规模可能过重。
- 仓库包含核心 MIT 与 EE 许可证分区，采用前需确认具体目录边界。
- 技术 trace 不应直接暴露给所有业务用户；业务页只展示模型、版本、模式、耗时和质量摘要。

**映射到 Saas-voc**

- 先为 AnalysisRun 增加轻量 trace metadata，而不是引入完整 LLMOps 平台。
- AI 质量中心建立 dataset run：同一证据集在不同模型/提示词/规则版本上对比 schema、引用和人工评分。

## 5. 横向机制对比

| 机制 | 代表项目 | 当前 Saas-voc | 建议目标 |
| --- | --- | --- | --- |
| 多来源接入 | AWS、Formbricks | 已有业务数据适配，但未形成插件契约 | manifest/registry + `NormalizedFeedbackEvent` |
| 归一化与去重 | OpenVoC、AWS、ADK | 主题准备已有，跨来源去重弱 | 稳定 source key + text fingerprint + 可解释相似度 |
| AI 前脱敏 | ReviewRadar、Microsoft | 未形成固定阶段 | 可配置 PII policy + redaction audit |
| 规则与 LLM 分工 | ReviewRadar、ADK | deterministic fallback 已有 | 规则产事实，LLM 做语义归纳与建议 |
| 证据引用 | OpenVoC、Microsoft、Qiaomu | 前端 evidence ID 白名单已具备 | 服务端 subset 校验 + source offset/snippet |
| 分析历史 | Qiaomu、Langfuse | AnalysisRun 已保存并恢复 | 增加模型、提示词、规则、taxonomy 版本 |
| 人工确认 | OpenVoC roadmap | 只有创建行动表单这一隐式确认 | 独立 InsightDecision 与审计事件 |
| 洞察发布 | Langfuse 的版本思想 | AnalysisRun 终态被用作结果状态 | `draft -> confirmed -> published -> archived` |
| 行动关联 | OpenVoC | 前端已传 source IDs/evidence/metric | 服务端引用、唯一性、反向查询 |
| 效果回流 | ADK backlog 可提供起点 | 缺失 | ActionValidation + 新一轮 AnalysisRun 输入 |
| 趋势/版本风险 | Qiaomu、ReviewRadar、ADK | 主要是单次结果 | 时间窗 diff + 版本/批次诊断 |
| AI 评估 | ReviewRadar、ADK、Langfuse | 单元测试为主 | golden dataset + experiment + scorecard |

## 6. 推荐目标信息架构

### 6.1 反馈收件箱

保持当前 `队列 + 证据详情`，补充：

- 可保存的筛选视图：来源、产品、时间、主题、评分、处理状态。
- 详情中的“相似反馈”标签，展示相似原因和真实 evidence ID。
- 原文、归一化文本、翻译文本分栏，明确哪个字段是原始证据。
- 去重组视图：主反馈、重复成员、去重规则和可撤销合并。

### 6.2 AI 洞察工作台

采用受控的三层结构：

1. `洞察摘要`：结论、状态、严重度、证据覆盖、建议与验证指标。
2. `原始证据`：与当前筛选一致的证据列表，可回跳收件箱。
3. `分析历史`：运行状态、模式、模型/提示词/规则版本、样本窗口和恢复。

历史列表应显示全部状态，但只有 `completed/partial` 且通过 schema 校验的结果可恢复；`failed/cancelled` 用于诊断与重试，不伪装成业务洞察。

### 6.3 洞察资产详情

新增独立业务对象后，单条洞察详情使用五个标签：

```text
Evidence | Decision | Actions | Validation | Versions
```

- Evidence：引用、coverage、样本限制、来源分布。
- Decision：confirmed/rejected/needs_more_evidence、决策人、时间、备注。
- Actions：关联 ActionItem、负责人、截止时间和状态。
- Validation：基线、目标、观察窗口、结果与结论。
- Versions：来自哪次 AnalysisRun、人工修改和发布版本。

### 6.4 行动中心

ActionItem 详情顶部固定展示来源链：

```text
ActionItem -> Insight -> AnalysisRun -> Evidence
```

完成行动前要求填写验证方式；关闭行动时记录 `effective / partially_effective / ineffective / not_measured`，其中 `not_measured` 必须填写原因。

### 6.5 AI 质量中心

该页面面向管理员/分析师，不进入普通业务用户主导航：

- 运行量、成功率、fallback 率、平均耗时、模型与提示词版本。
- JSON schema pass rate、evidence precision、evidence coverage、unknown ID rejection。
- golden dataset 运行对比与人工评分。
- 失败样本进入可复现详情，不展示敏感原文给无权限角色。

## 7. P0 / P1 / P2 实施清单

### P0：先闭合可信决策链

#### P0-1 服务端 Grounding 不变量

- 服务端保存 AnalysisRun 结果前校验每个 `insight.evidenceIds` 是本次 `input.evidenceIds` 的非空子集。
- 拒绝未知 ID、跨 workspace ID、重复 ID、空引用和 `evidenceCount` 不一致。
- 保存 `schemaVersion`、`promptVersion`、`model`、`ruleVersion`、`taxonomyVersion`。
- 对相同 workspace、输入指纹和版本组合支持幂等创建，避免刷新产生并发运行。

验收：构造未知 evidence ID 和跨运行 ID 的 PATCH，API 返回 4xx；合法结果可恢复且引用数一致。

#### P0-2 AI 前脱敏与审计

- 建立 `normalize -> redact -> rule tag -> LLM` 固定管线。
- 首批覆盖邮箱、手机号、账号/订单号、URL 参数、地址候选和自定义词典。
- AnalysisRun 只记录脱敏统计和策略版本，不把原始敏感内容写入错误日志。
- 允许按 workspace 配置字段白名单与“完全不发送 AI”的数据源。

验收：golden feedback 中的敏感字段在网关请求与日志中均不可见，原始证据仍按权限保留在收件箱。

#### P0-3 独立人工决策门槛

- 新增 `InsightDecision`：`confirmed | rejected | needs_more_evidence`。
- 保存 `decidedBy`、`decidedAt`、`comment`、`reviewedEvidenceIds` 和审计事件。
- `needs_validation` 与 deterministic 洞察默认只能“请求补证据”，确认后才开放正式行动创建。
- 不允许以修改 AnalysisRun 终态代替人工确认。

验收：未确认洞察在 UI 与 API 均不能创建正式 ActionItem；确认记录可查询且不可静默覆盖。

#### P0-4 ActionItem 引用与幂等

- 延续现有前端字段：`sourceAnalysisId`、`sourceInsightId`、`evidenceIds`、`validationMetric`。
- 服务端校验分析、洞察、证据、确认记录与 workspace 一致。
- 增加 `sourceDecisionId` 和 action type 维度的唯一约束或幂等键。
- Action Center 支持从行动反向跳回洞察和每条原始证据。

验收：重复提交只产生一个行动；删除/归档洞察不破坏已存在行动的历史引用。

#### P0-5 最小 AI 质量门禁

- 建立 50-100 条中文 golden dataset，覆盖本品/竞品、低样本、重复、P0 风险、无效文本和混合情感。
- 指标至少包括：schema pass rate、evidence precision、unknown ID rejection、fallback rate、人工确认一致率。
- AI 与 deterministic 结果使用同一 schema validator。
- 提示词、模型或 taxonomy 变更必须跑回归，并保存对比结果。

验收：CI 可重复运行；任一 evidence precision 下降或 schema 失败超过阈值时阻止发布。

### P1：形成可运营的洞察资产

#### P1-1 统一反馈事件与来源注册表

- 定义 `NormalizedFeedbackEvent`：internal ID、source ID、platform、channel、URL、original text、normalized text、language、timestamps、product/workspace、metadata。
- 每个来源 adapter 输出同一 schema，并提供健康状态、增量游标和错误统计。
- 来源配置、密钥引用与 UI 字段由 registry/manifest 驱动，但权限规则仍由平台控制。

#### P1-2 洞察生命周期与版本

- 新增 `InsightRecord`，生命周期为 `draft -> confirmed -> published -> archived`。
- AnalysisRun 只负责生成；InsightRecord 负责业务发布。
- 人工编辑或重新生成产生新版本，不原地覆盖已发布版本。
- 发布、归档、恢复均记录原因和操作者。

#### P1-3 趋势与版本诊断

- 以确定性统计计算主题新增、升温、缓解、复发和证据增量。
- 支持按商品版本、渠道、地区、批次和时间窗口对比。
- AI 只解释已计算的变化，并引用造成变化的 evidence IDs。
- 图表下方保留样本量、时间窗和数据缺口说明。

#### P1-4 行动效果回流

- 新增 `ActionValidation`：metric、baseline、target、window、observed value、verdict、verifiedBy、verifiedAt。
- 行动完成后进入待验证，而不是直接视为问题已解决。
- 验证结果可按洞察、主题、产品和时间查询，并进入下一轮 AnalysisRun context。
- 对 ineffective/partially_effective 自动生成复盘草稿，不自动创建新任务。

#### P1-5 Grounded Explore

- 增加受控追问入口，同时使用 evidence search 与结构化统计。
- 每个回答返回 citations、筛选口径和计算来源。
- 对话不能直接确认、发布或创建行动，只能预填业务表单并等待用户提交。

### P2：在基础稳定后扩展规模与智能

#### P2-1 受控 schema-aware dashboard

- AI 可建议 KPI、图表和追问，但仅从白名单 field、metric 和 visualization 中选择。
- 代码 validator 检查字段存在、覆盖率、PII、基数和图表类型。
- 核心 VOC 总览保持产品定义，不随模型输出改变布局。

#### P2-2 自动周报与多渠道分发

- 周报按 P0/P1、趋势变化、待确认洞察、逾期行动和验证结果组织。
- 每条摘要携带可点击 insight/evidence 链接。
- Slack/飞书/邮件只发送摘要，确认和操作回到平台完成。

#### P2-3 相似反馈与跨周期记忆

- 建立混合检索：稳定规则过滤 + embedding 相似度 + source/time/product 权限过滤。
- 相似结果展示匹配原因和分数，不自动合并。
- 主题跨期 identity 由确定性 key 和人工 merge/split 维护，避免模型每周重命名。

#### P2-4 规模化 AI 实验

- 支持 dataset experiment、sampling evaluator、模型/提示词 A/B 和人工盲评。
- 业务评分与技术 trace 分层展示。
- 只有通过回归阈值的版本可标记为 production label。

## 8. 建议执行顺序

| 阶段 | 目标 | 依赖 | 完成信号 |
| --- | --- | --- | --- |
| 1 | 服务端 evidence subset 校验、PII、版本元数据 | 现有 AnalysisRun | 任意历史结果可解释“输入、版本、证据、模式” |
| 2 | InsightDecision 与 ActionItem 幂等引用 | 阶段 1 | 未确认洞察无法进入正式行动 |
| 3 | golden dataset 与质量门禁 | 阶段 1 | 模型/提示词升级有可比较报告 |
| 4 | InsightRecord 生命周期与版本 | 阶段 2 | 运行完成与业务发布彻底分离 |
| 5 | ActionValidation 效果回流 | 阶段 2、4 | 可回答“哪类行动真正改善了哪类 VOC” |
| 6 | 连接器 registry、趋势、Grounded Explore | 前述契约稳定 | 新来源和新智能能力不破坏证据链 |

## 9. 明确不做的复制

- 不复制单一项目的完整云基础设施；当前架构优先复用 Angular、现有 Node 服务和仓储实现。
- 不把 LLM 聚类结果直接当作主题事实；聚类、计数、趋势和版本差异优先确定性计算。
- 不允许自由文本 `evidence` 代替 evidence ID 与原文回跳。
- 不把 `AnalysisRun.completed` 当作“洞察已确认”或“行动已批准”。
- 不让聊天或 Agent 自动确认、发布或创建正式行动。
- 不使用只有颜色和卡片数量变化的“AI 仪表盘”；专业 UI 优先支持扫描、筛选、比较、恢复和审计。
- 不直接复制 AGPL/EE 或无明确许可证仓库的源码；只学习公开的产品机制与信息架构。

## 10. 最终产品判断

Saas-voc 当前已超过“把评论丢给 LLM 得到摘要”的阶段。真正的产品壁垒应放在：

```text
可追溯证据
  + 可解释规则
  + 可恢复运行
  + 可审计人工决策
  + 可执行行动
  + 可量化效果回流
```

GitHub 对标显示，成熟项目通常只在其中两到三项做得突出。我们的机会是把这些能力统一到一条业务链，而不是继续增加孤立 AI 功能。按本报告优先级，先完成 P0 的服务端证据约束、人工决策门槛、行动幂等和 AI 质量门禁，才能让后续趋势、对话和自动周报建立在可信数据上。