评价文件分析报告

用户给一份评价导出文件，产出一份按类目维度拆解的单文件 HTML 分析报告。

适用场景

• 「这份评价帮我分析一下」「看看买家都在说什么」
• 「总结一下这款商品的用户反馈」「差评集中在哪」
• 竞品评价表对比、新品上架前摸底同款反馈
• 拼多多/淘宝/天猫/京东后台导出的评价 Excel / CSV

不适用：
- 需要全网检索口碑、跨平台聚合评价 → 用 product-review-aggregator
- 查价格、找商品、查销量
- 只有一两条评价的简单问答

与同级技能的分工

评价类需求有三个技能，按「数据从哪来」区分，触发时先判断属于哪一个：

关键差异：taobao-review-insight 只吃纯文本 / HTML / JSON，
不支持 xlsx/csv（它的 parse_reviews.py 只有 --text/--stdin/--html/--json）。
用户给的是表格文件时，本技能才是有能力处理的那个。

反向情况：用户只给产品名或链接、手上没有任何数据时，本技能无处下手，
应转 taobao-review-insight（淘宝）或 product-review-aggregator（全网）。

本技能与 taobao-review-insight 的输出取向不同，注意不要混用口径：
- 本技能：只做中性总结，不给运营动作建议
- taobao-review-insight：阶段五会给出差评结论、详情页文案方向等行动建议

核心工作流

四个阶段依次执行。不要跳步——先把数据解析干净，再做分析，最后才渲染。

阶段一：确认输入与表头

得到文件路径后，先跑解析器的预览模式确认列识别是否正确：

python scripts/parse_reviews.py "<评价文件路径>" --preview

检查输出中的 列识别结果：
- content 必须命中，否则报告无从生成
- sku / time / images / videos 命中越多报告越丰富
- score 未命中是正常的——多数平台导出的评价表不带星级，此时情感完全由文本规则判定

若 content 识别错误，用 --content-col N 指定列号（从 0 开始）。

若表头是英文或非常规写法（如 review_body、买家留言），词典可能漏匹配。
此时先读一下 CSV/XLSX 的表头，然后在 scripts/parse_reviews.py 的
COLUMN_PATTERNS 里补充该列名，再重跑。这是遇到新平台格式时的标准动作。

阶段二：解析与统计

python scripts/parse_reviews.py "<评价文件路径>" -o parsed.json
python scripts/analyze_reviews.py parsed.json -o agg.json --source-name "<文件名>"

分析器输出好评 / 褒贬不一 / 中性 / 差评四条线、十个维度的拆解，
以及差评归因（见下节）。通用维度：

类目专属维度（自动切换，见下节）：

判定优先级：平台情感列 > 平台评分 > 文本规则。三者都没有就是文本规则。

类目自动识别与切换

分析器会自动判断类目，从评价正文里投票（CATEGORY_HINTS），
终端会打印识别结果：

类目：食品饮品（命中 372 次）

自动识别不准时用 --category 强制指定：

python scripts/analyze_reviews.py parsed.json -o agg.json --category apparel

取值：food / apparel / appliance / beauty / daily。

手动指定优先于自动识别。判断依据不足时（命中数 < 样本量的 5%）
会退回食品默认包并在输出里说明，此时应当用 --category 明确指定。

类目识别不准的典型信号

跑完看终端和报告，出现以下情况说明类目选错了：
- 报告里的维度名与商品明显不符（如服饰报告出现「口感味道」）
- 大量评价归入中性、维度提及量极低
- 差评归因出现不符类目的原因（如服饰差评归到「口味不合」）

处理：先试 --category 指定。若目标类目不在上面五个里（如母婴、宠物、图书），
需要扩展 CATEGORY_PACKS，见 references/extending-categories.md。

差评归因（负面原因统计）

analyze_reviews.py 会额外产出一份 negative_analysis，
把「差评 + 褒贬不一里的负面表述」按原因归类，并在报告里用环形占比图呈现。

十二个通用原因（跨类目）：运输破损、密封失效、口味异常、口感质地、
发错货、少发漏发、临期过期、异物卫生、身体不适、物流慢、客服差、价格不值。

类目专属原因同样按类目切换：服饰有「尺码不合适 / 面料做工差 / 色差」，
家电有「功能不达预期 / 噪音震动 / 故障损坏」等。
跨类目的原因会被自动过滤（服饰评价不会归到「口味不合」）。

三个输出维度：
1. 原因分布 —— 每条给一个主因，环形图 + 图例显示占比
2. 环节聚合 —— 把原因归到业务环节（物流包装 / 生产包装 / 配方口味 /
品质管控 / 发货环节 / 客服售后 / 价格策略），看问题集中在哪一环
3. 严重度排序 —— 涉及安全与健康的原因（异物、变质、过敏等，
REASON_SEVERITY >= 9）在报告里单独用红框警示

归因结果里每条原因都附命中的关键词和证据原声，
未命中的负向表述会单独列在「未能归类」折叠块里（不隐藏），便于发现词典盲区。

归因准确性的自查方法

跑完后重点检查两处：
- 未能归类 的条目里若有多条其实有明显原因，说明 NEGATIVE_REASONS
的关键词要补
- 原因分布 里若某条评价归因明显错误，多半是关键词跨类目误命中
（如食品的「硬」误伤服饰的「硬挺」）

补词典时优先用两字以上的词组，单字词误伤率极高。

阶段三：渲染报告

python scripts/render_report.py agg.json -t "<商品名>" -o 评价分析报告.html

商品名从文件名或评价内容里推断（如文件叫 至尊宝_导出excel.xlsx，
评价里频繁出现「冷卡荞麦面」，则可定名为「冷卡荞麦面（至尊宝）」）。
名字要能让人一眼看出是哪款商品。

阶段四：核对与交付

渲染后必须打开报告自查，重点看三处：

1. 差评和褒贬不一的明细是否合理 —— 若出现明显是好评的内容被判成差评，
   是情感词典有误判。定位方法：把可疑文本单独喂给 judge_sentiment() 调试。
   常见坑：单字负向词（慢、硬、烂）极易误伤，如「慢排空」「柔软」；
   应用两字以上词组。
2. 维度数量是否为 0 —— 若某维度 total 为 0，说明词典与该类目不匹配。
3. 有没有 None / nan 字样漏到页面上 —— 说明某字段缺失未兜底。

核对无误后用 present_files 把 HTML 交给用户。

关键实现细节

情感判定的否定逻辑（最容易出错的地方）

中文评价里否定词的处理必须位置感知，不能做子串匹配：

• ❌ "别" in "特别好吃" → 误判为否定
• ✅ 用正则加左侧边界：(?:^|[^一-龥])(不太|不是|没有|没|不|无)

三类特殊搭配需要单独处理：
- 否定负面词 = 夸奖：没有胀包、不易碎、没破损 → 正
- 否定正面词 = 差评：不会回购、不推荐、不再买 → 负
- 豁免词：不错、不油腻、不坨、无添加 → 正

发现新的误判搭配时，往 NEGATION_EXEMPT 或 NEGATED_NEGATIVE_PRAISE
里补，比调权重更可靠。

换成非食品类目

优先靠 --category 自动切换（五个内置类目），不用手改代码。
只有目标类目不在内置五个里时，才需要扩 CATEGORY_PACKS——
步骤见 references/extending-categories.md。

POSITIVE_WORDS / NEGATIVE_WORDS 是跨类目共用的，
里面已经混入了服饰/家电/美妆/日用的通用词，一般无需再改。

关键词提取

不依赖 jieba 等分词库（避免让用户装依赖），改用 2-4 字 n-gram 频次统计 +
停用词过滤。对评价这种短文本效果好。若环境已有 jieba，也可替换为分词方案，
但要在脚本注释里说明可选依赖。

报告口径

报告只呈现数据事实与用户原话，不给运营动作建议（主图文案、活动报名方向等）。
这是山海的明确要求——他要的是客观输入，决策自己做。
在页脚已写明样本口径与自动化判定的局限。

依赖

pip install openpyxl          # 必需，读 xlsx / xlsm
pip install xlrd              # 可选，仅当输入是老式 .xls

csv / tsv / txt 走标准库，不需要任何第三方依赖。

环境就绪检查（首次使用或换机器后先跑这个）：

python scripts/parse_reviews.py --self-check

会打印 Python 路径、各依赖状态，缺什么直接给出可复制的安装命令。
依赖缺失时脚本本身也会输出同样的友好提示，不是一句 ImportError。

无法安装依赖时的兜底：让用户把评价表另存为
「CSV UTF-8（逗号分隔）」，CSV 路径零依赖，功能完全一致。

分享给他人

技能通过 zip 分发，对方解压到自己的 ~/.workbuddy/skills/ 即可（重启生效）。
zip 内含 README.md，接收方照着装就行。

打包（必须含 README，package_skill.py 不会自动收录它）：

import zipfile, os
src = "路径/review-file-insight"
z = zipfile.ZipFile("review-file-insight.zip", "w", zipfile.ZIP_DEFLATED)
for root, dirs, files in os.walk(src):
    dirs[:] = [d for d in dirs if d not in ("__pycache__", ".git")]
    for f in files:
        if f.endswith((".pyc", ".pyo")):
            continue
        p = os.path.join(root, f)
        z.write(p, os.path.join("review-file-insight", os.path.relpath(p, src)))
z.close()

结构陷阱：zip 内顶层必须是 review-file-insight/，解压后
review-file-insight/SKILL.md 直接可见。若多套一层
（review-file-insight/review-file-insight/SKILL.md）技能不会被识别。
打包后应解压到干净目录验证一遍再发出。

个人级技能只对安装者生效；要团队共享，用项目级
（.workbuddy/skills/，跟代码仓库走）或发布到技能市场。

发布到技能市场（SkillHub）

本技能已备齐发布元数据，只差登录。完整流程见
references/publishing.md，关键点：

skillhub login --key skh_xxx          # 登录（需用户去 SkillHub 领 Token）
skillhub publish "<技能目录>" --dry-run   # 预检，通过才继续
skillhub publish "<技能目录>" --changelog "..."

最容易踩的坑：SkillHub 的发布校验要求 SKILL.md 里有
slug / displayName / version / summary（见
_validate_metadata），这与 skill-creator 的 quick_validate.py
是两套不同标准——本地校验通过不代表能发布。
所以每次发布前必须跑 --dry-run 确认。

迭代发布时要同步改 version（如 1.2.0 → 1.2.1），否则服务端判为重复版本拒绝。

参考文件

• README.md —— 面向使用者的安装与使用说明（分发时一起打包给接收方）
• references/publishing.md —— 发布到 SkillHub 技能市场的完整流程
• references/report-structure.md —— 报告各板块的取舍理由与扩展方式
• references/extending-categories.md —— 新增类目词典包的完整步骤
• scripts/parse_reviews.py —— 文件解析、列识别、环境自检（--self-check）
• scripts/analyze_reviews.py —— 情感判定、维度归类、差评归因、关键词统计
• scripts/render_report.py —— HTML 渲染（含 SVG 环形图组件）