Voicescope Voc Deep Insight

VoiceScope VOC 客户反馈分析：自动登录 VoiceScope，上传反馈数据（CSV/Excel/TXT）， 观点提取与聚类，生成/校验标签体系，批量打标签，逐行通用分析（情感判断/关键词提取/ 摘要/场景/行动），取回结果并生成洞察摘要。 当用户要分析客户反馈、用户评论、投诉、问卷开放题，或提到“打标签”“标签体系”“VOC” “反馈分类”“观点提取”“观点聚类”“高频观点”“情感判断”“关键词提取”“自定义分析列”时使用。

VoiceScope VOC Insight Skill

本 Skill 只做入口、编排和展示。所有鉴权、额度、长任务、LLM 调用和结果持久化都在 VoiceScope 后端完成，正式结果写入用户自己的 VoiceScope 项目。

功能总览（用户问“能干什么/怎么用”时按此回答）

能力	说明	工作流
观点提取 + 聚类	从每条反馈抽取观点片段（带情感极性），再语义聚类出正/负/中三桶高频观点簇	工作流 A
批量打标签	用标签体系给每条反馈分类，结果写回表格可导出	工作流 B
生成标签体系	没有标签体系时，从反馈样本自动生成草案，用户确认后可直接入库（或到控制台精修入库）	工作流 C
校验标签体系	默认检查结构/规则问题；加 --llm 进一步做语义检查	validate
通用分析列	对某列逐行做单一类型分析：情感判断 / 关键词提取 / 摘要 / 场景识别 / 行动建议，结果写回表列	工作流 D

支持的数据格式：CSV、Excel（.xlsx/.xlsm）、TXT（每行一条）。Excel 旧格式 .xls 不支持，提示用户另存为 .xlsx。

工作流 D 与控制台「添加自定义分析列」同源（复用后端 ai_analysis 引擎），按月度 U 额度计量。注意：聚类链路里那个内部 bigram 指纹 signature_keywords 不是关键词产物、不对外——工作流 D 的 keyword 是独立的 per-row 关键词分析，两者不要混为一谈。

意图分流（先判断用户要什么，再选工作流）

用户说法	走哪条
“提取观点”“聚类”“大家都在说什么”“高频观点/痛点”	工作流 A：观点提取 → 聚类
“打标签”“分类”“按标签统计”	工作流 B：打标签（先确认标签体系，见下）
“帮我建标签体系”“没有标签体系”	工作流 C：生成标签草案
既要观点又要标签	先 A 后 B，同一张表复用
“判断情感/情绪”“正负面”“逐行打情感”	工作流 D：analyze --type sentiment
“提关键词”“每条抽关键词”	工作流 D：analyze --type keyword（注意：不是观点聚类的内部指纹）
“逐行摘要/总结”“识别使用场景”“给行动建议”	工作流 D：--type summary / scenario / action

工作流 D 与工作流 A 的区分：A 是「全表观点提取＋跨行聚类」，产出三桶高频观点簇；D 是「对某列逐行做单一类型分析」，每行一个结果写回表列。用户说“高频/大家都在说什么/痛点排行”走 A；说“给每条/逐行/这一列都判断一下”走 D。

用户想打标签但没说用哪个标签库时，必须先停下来问，不要替用户默认选择，更不要直接抓一个预置体系就开打：

• 预置/已有体系不一定贴合用户数据。先 taxonomies 列出项目里现成的（含预置行业模板）给用户看，并明确告知：“这些是通用/预置模板，不一定完全契合你的反馈，先确认是否够用。”
• 给用户两条路二选一：① 用已有/预置体系——挑一个 taxonomy_id；② 从你的数据现生成一套——走工作流 C，生成草案后在控制台改完入库（更贴合）。
• 用户没明确选定之前，不要进入打标。

通用前置步骤（所有工作流共用）

1. 登录检查：auth-status，未登录先 login（见下方“登录”）。

2. 预览数据并确认列：用户给的是 CSV/Excel 时，先本地预览列名：

   bash

   python scripts/vs_api.py preview --file 用户的文件.xlsx
   

   把列名和样例展示给用户，必须停下来等用户确认对哪一列做分析，拿到确认前不要上传、不要进入任何工作流。这是硬性闸门：分析按行扣额度，选错列＝白扣额度，所以即使某列"明显"是反馈原文、即使全表只有一列文本、即使用户在开头已经提过列名，也仍要把"我准备用『X』列，对吗？"明确问出来、得到肯定答复后再继续。绝不替用户默认、绝不猜列直接开跑。

3. 上传（仅在用户确认列之后执行）：

   bash

   python scripts/vs_api.py upload --file 用户的文件.xlsx --text-column 用户原声
   

   记下输出的 table_id、text_column_id（和打标用的 result_column_id）。

工作流 A：观点提取 → 聚类

这是两步流水线：先逐行提取观点片段（按行扣额度），再对观点列做语义聚类（不按行扣额度）。

bash

# 第一步：提取（--column 传 text_column_id；输出会给出观点列 result_column_id）
python scripts/vs_api.py extract-viewpoints --table <table_id> --column <text_column_id>
python scripts/vs_api.py wait <extract_task_id>

# 第二步：聚类（--column 传上一步返回的 result_column_id，不是原文列！）
python scripts/vs_api.py cluster --table <table_id> --column <viewpoint_column_id>
python scripts/vs_api.py wait <cluster_task_id>

# 取结果（控制台摘要；--out 导出。.xlsx=官方观点洞察 Excel，推荐；也支持 .csv/.json）
python scripts/vs_api.py cluster-results <cluster_task_id> --out clusters.xlsx

结果是 pos/neg/neu 三桶 Top-K 簇，每簇含 LLM 命名（簇名）、片段数、桶内占比和原声样例。向用户汇报时按“正面亮点 / 负面痛点 / 中性观察”组织，引用簇名 + 片段数 + 一两条原声。

--out *.xlsx 直接下载官方观点洞察 Excel：与控制台 Studio「保存到报告 → 导出 Excel」走同一套序列化（观点 / 数量 / 占比 / 对应原声，按正负向分 sheet），skill 与控制台导出格式一致。注意观点洞察链路没有“关键词”这个产物——聚类内部的 bigram 指纹只用作 LLM 命名缓存 key，不对外、不要当关键词汇报。

注意：

• extract-viewpoints 可加 --background "产品背景" 提升提取质量。
• 聚类报 viewpoints_not_extracted：说明传错列（传成原文列）或提取还没完成。
• 同列重复聚类会命中快照缓存秒回；数据变了想强制重算加 --force-refresh。

工作流 B：批量打标签

前置：确认 taxonomy_id（taxonomies 列出让用户选；没有合适的走工作流 C）。

bash

python scripts/vs_api.py taxonomies
python scripts/vs_api.py tag-batch --table <table_id> --column <text_column_id> --taxonomy <taxonomy_id> --result-column <result_column_id>
python scripts/vs_api.py wait <task_id>
python scripts/vs_api.py results <task_id> --out tagged.csv

工作流 C：生成标签体系

bash

# CSV/Excel 用 --text-column 指定取哪一列做样本；TXT 整文件按行
python scripts/vs_api.py generate --file 用户的文件.xlsx --text-column 用户原声
python scripts/vs_api.py wait <task_id>
python scripts/vs_api.py draft <task_id>
# 展示草案给用户、得到确认后再入库（下面二选一）
python scripts/vs_api.py confirm-draft <task_id> --name "标签体系名"

必须先把草案展示给用户、拿到明确确认再入库，不要拿到草案就自动 confirm。确认后两条入库路径二选一：

• 直接入库（agent 闭环）：confirm-draft <task_id> --name "…"，返回正式 taxonomy_id，可立刻走工作流 B 打标。需要按用户意见微调草案时，把编辑后的行写成 JSON 数组用 --items-file edited.json 传入（后端会重新校验，depth=3 模式下 l3 必填）。
• 控制台精修入库：需要人工细调（下钻 L3、批量改定义）时，引导用户到控制台改完入库，再用 taxonomies 拿 taxonomy_id。

用户自带标签体系可先 validate --file taxonomy.json 做结构与规则校验；需要进一步检查标签语义重叠、命名等问题时使用 validate --file taxonomy.json --llm（会调用 LLM）。

工作流 D：通用分析列（情感判断 / 关键词 / 摘要 / 场景 / 行动）

对某一列逐行做单一类型分析，结果写回表列（按月度 U 额度计量，与打标 / 观点提取同口径）。--type 取值：

type	含义	每行产出
sentiment	情感判断	正面 / 负面 / 中性
keyword	关键词提取	该行关键词列表
summary	摘要	一句话总结
scenario	场景识别	使用/反馈场景
action	行动建议	可执行建议

bash

# --column 传源文本列 id（text_column_id）；result_column_id 缺省后端自动建列
python scripts/vs_api.py analyze --table <table_id> --column <text_column_id> --type sentiment
python scripts/vs_api.py wait <task_id>
python scripts/vs_api.py analysis-results <task_id> --out analysis.csv   # 不加 --out 只预览前 5 行

• 可加 --background "产品背景" 提升质量（同观点提取）。
• 一次只跑一种 --type；要多种就分别提交、各自一个结果列。
• 汇报口径：行数、有结果/空行数、sentiment 额外给情感分布；keyword 不要和工作流 A 聚类里的内部 signature_keywords 指纹混淆，那个不对外。

登录

先检查登录状态：

bash

python scripts/vs_api.py auth-status

如果返回 auth_required 或提示未登录，执行：

bash

python scripts/vs_api.py login

登录会自动打开浏览器。用户在 VoiceScope 网页登录并确认授权后，脚本会把 token 保存到 ~/.voicescope/auth.json。无浏览器环境使用：

bash

python scripts/vs_api.py login --no-browser

开发者 fallback：如果环境变量里有 VOICESCOPE_API_KEY=vs_xxx，脚本会优先使用 API Key，不读取本地登录 token。

本地联调后端时可设置：

bash

VOICESCOPE_API_BASE=http://127.0.0.1:8000

退出：

bash

python scripts/vs_api.py logout

错误处理

按 error.code 决定下一步：

code	处理
auth_required	执行 login。
authorization_pending	用户还没在浏览器确认，继续等待。
authorization_expired	设备码过期，重新执行 login。
token_expired	脚本会自动 refresh；失败则重新 login。
token_revoked	本地登录已撤销，重新 login。
quota_exceeded	告诉用户本月 U 额度不足，引导到控制台查看用量或升级套餐。
task_not_ready	继续 wait，不要重复提交任务。
viewpoints_not_extracted	聚类的 --column 传错（应传观点列）或提取未完成，先完成工作流 A 第一步。
missing_dependency	本地缺 openpyxl：pip install openpyxl 后重试。
validation_failed	按 message 修正参数后重试。

交付口径

任务完成后只汇报关键数字：行数、命中数/未命中数、簇数与各桶片段数、issue 数、task_id、导出文件路径或控制台链接。大结果不要塞进对话上下文，除非用户明确要求抽样展示。观点聚类汇报模板：总片段数 → 负面 Top 痛点（簇名+数量+原声例）→ 正面 Top 亮点 → 值得注意的中性观察。

务必讲清楚结果在哪看，给用户两个明确出口，不要让用户猜（results / cluster-results 命令末尾已自动打印这两条，转述即可）：

• 在线（需登录）：优先转述脚本给出的直达链接（links.open_url，形如 https://voiceaiscope.com/workbench?openTaskId=<task_id>），点开即定位到本次任务结果，未登录会先提示登录再跳回，可分享。后端没回 open_url 时才回落到工作台首页 project_url。正式结果都写在用户自己的项目里，刷新即见。
• 下载到本地：cluster-results 加 --out 文件名.xlsx（官方观点洞察 Excel，与控制台导出一致，推荐）导出到本地，把绝对路径告诉用户；也支持 .csv / .json。results（打标）用 --out 文件名.csv。

打标完成时，除了命中数，也要把未命中讲明白：未命中＝该行没匹配到任何标签，常见原因是标签体系不够贴合，可建议换体系或走工作流 C 重新生成。

引导用户去平台做更强的后续（强后续类型才提示）

skill 是上车点，平台 Studio 才是深度分析的地方（词云、标签洞察、情感看板、报告这些可视化终端做不了）。所以只在「平台确有更强后续」的分析类型完成后，顺带引导用户去平台继续——不是每次都弹，避免噪音。results / cluster-results / analysis-results 命令已在结果末尾自动打印这句引导，转述即可：

• keyword（工作流 D）→ 平台可一键生成词云
• 打标 / tag（工作流 B）→ 标签 Studio 的洞察 / 趋势 / 下钻 / 交叉透视
• sentiment（工作流 D）→ 情感分布看板
• 观点聚类（工作流 A）→ 保存为观点洞察报告、与标签交叉分析

summary / scenario / action 无强后续，不提示。链接优先用后端回传的 open_url 直达深链（?openTaskId=<task_id>，点开即定位到本次结果），skill 透传即可；后端未回时回落到 project_url 工作台首页。