Voicescope Voc Deep Insight

VoiceScope VOC Insight Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

python scripts/vs_api.py taxonomies
python scripts/vs_api.py tag-batch --table  --column  --taxonomy  --result-column 
python scripts/vs_api.py wait 
python scripts/vs_api.py results  --out tagged.csv

工作流 C：生成标签体系

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

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

• 直接入库（agent 闭环）：confirm-draft --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 取值：

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

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

登录

先检查登录状态：

python scripts/vs_api.py auth-status

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

python scripts/vs_api.py login

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

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

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

本地联调后端时可设置：

VOICESCOPE_API_BASE=http://127.0.0.1:8000

退出：

python scripts/vs_api.py logout

错误处理

按 error.code 决定下一步：

交付口径

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

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

• 在线（需登录）：优先转述脚本给出的直达链接（links.open_url，形如 https://voiceaiscope.com/workbench?openTaskId=），点开即定位到本次任务结果，未登录会先提示登录再跳回，可分享。后端没回 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=，点开即定位到本次结果），skill 透传即可；后端未回时回落到 project_url 工作台首页。