buluslan/review-analyzer-skill

English | 简体中文

---

项目简介

review-analyzer-skill 是由 buluslan（公众号：新西楼.AI）研发的电商评论深度分析 Skill（VOC 客户之声分析），他会帮你把一堆产品评论变成一份能落地的决策依据——22 维 AI 打标提炼用户画像、痛点和真实需求，输出 15 章深度洞察报告和可视化看板，从差评里挖出产品优化机会点、从好评里找到爆款基因。

[!TIP] 更多跨境电商 AI 实战内容，请关注公众号「新西楼.AI」

作为 Agent 原生 工具，它适配 Claude Code、Codex、Cursor、OpenCode 等主流 AI Coding Agent，支持本地 CSV 数据导入和 卖家精灵 平台数据对接（可选增强），零 API Key 即可运行。

V2.2 · Agent 自执行模式：LLM 工序（评论打标、15 章报告撰写）由宿主 Agent 自己完成，不依赖本机安装 claude CLI——任何 AI Coding Agent 都能完整跑通。另保留 --llm cli 直跑模式作为无宿主 Agent 时的 headless 后备。

V2.0 核心升级

工作流程

数据输入: 本地 CSV（主源）或 卖家精灵（可选）
     ↓
Phase 1: AI 深度打标（并发4，22维度标签）
Phase 2: 用户画像识别（3-4个画像，3正+3负黄金样本）
Phase 3: 洞察报告生成（15章结构化报告）
Phase 4: 统一输出（MD + HTML看板 + 飞书同步）

V2.2 起 Phase 1/3 的 LLM 工序默认由宿主 Agent 自执行（--llm agent，prepare → Agent 打标 → --resume → Agent 撰写报告 → --resume 收尾）；上图 CLI 并发路径保留为 headless 后备（--llm cli）。

📄 在线查看完整洞察报告示例（飞书文档） — 包含 15 章完整内容（V2.1 版，含异常信号卡）+ 飞书白板 mermaid 图表

---

核心特性

📊 22维度智能标签

全面覆盖评论信息的8大维度：

人群维度 (4): 性别、年龄段、职业、购买角色
场景维度 (1): 使用场景
功能维度 (2): 满意度、具体功能
质量维度 (3): 材质、做工、耐用性
服务维度 (5): 发货速度、包装质量、客服响应、退换货、保修
体验维度 (4): 舒适度、易用性、外观设计、价格感知
市场维度 (2): 竞品对比、复购意愿
情感维度 (1): 总体评价

🎨 6套主题可视化看板

可直接用于工作汇报的 HTML 报告，共享基座架构确保内容结构统一：

每个看板包含：11个板块 + 异常信号卡区、交互式 Chart.js 图表（主题色板）、响应式设计、玻璃拟态卡片效果。

📋 15章深度洞察报告

1. 洞察总览（核心判断 + 战略方向 + 市场定位）
2. 核心用户画像（多维度画像 + 核心诉求 + 原声引用）
3. 核心卖点与价值验证（数据支撑 + 用户原话）
4. 主要痛点与负面归因（严重性 + 瀑布效应 + 行动建议）
5. 改进建议与优先级（P0/P1/P2 + 预期收益）
6. 潜在机会与差异化（数据 + 建议）
7. 典型用户深度解析 8-12. 深度内容章节
8. 异常信号卡（严重度分级决策卡 + 代表原话引用 + 建议动作）
9. 行动决策仪表盘
10. 数据附录

📦 多格式输出 + 飞书同步

---

🎁 接入福利

接入卖家精灵 MCP 数据源时,用以下 buluslan(公众号:新西楼.AI)专属优惠码享折扣(下单时在「折扣券」处粘贴对应码):

🏠 交流社区

系统要求

飞书同步说明：如需将分析结果同步到飞书文档，需提前安装 lark-cli（npm install -g lark-cli）并完成 lark-cli login 认证。如果未安装，工具会自动跳过飞书同步步骤，不影响其他功能。

---

快速开始

方式1：使用 skills.sh 生态安装（推荐）

npx skills add buluslan/review-analyzer-skill

安装后，在 Claude Code 中直接用自然语言调用：

# 示例1：指定文件分析
请分析这个产品的评论：reviews.csv

# 示例2：描述需求
帮我做一下竞品评论的深度分析

方式2：手动克隆仓库

git clone https://github.com/buluslan/review-analyzer-skill.git
cd review-analyzer-skill
pip install -r requirements.txt

运行参数

# === 数据输入方式 ===

# 方式1：本地 CSV 文件
python3 main.py your_reviews.csv --max-reviews 200

# 方式2：卖家精灵平台数据（可选增强，需配置 SELLERSPRITE_SECRET_KEY）
python3 main.py --source sellersprite --asin B09XYZ123 --site US --max-reviews 200

# === LLM 执行模式（V2.2） ===
# agent（推荐，宿主 Agent 自执行打标与报告，零 CLI 依赖）:
python3 main.py your_reviews.csv --llm agent --max-reviews 200 --creator "Your Name"
#   → prepare 退出后，宿主 Agent 按 prompt 打标/撰写报告，用 --resume  推进
# cli（默认，headless 后备，subprocess 调 claude/opencode 一次跑完）:
python3 main.py your_reviews.csv --max-reviews 200 --creator "Your Name"

# === 完整参数 ===
python3 main.py your_reviews.csv \
  --asin B09XYZ123 \
  --template premium-gold \
  --feishu-sync \
  --concurrent 4 \
  --creator "Your Name"

# === 可视化模板（6选1，或 none 跳过） ===
--template premium-gold|dark-tech|linear-minimal|posthog-analytics|stripe-executive|warm-editorial|none

# === 飞书同步（需提前安装 lark-cli 并认证） ===
--feishu-sync auto|manual|skip

---

CSV文件格式要求

工具支持自动模糊匹配列名，CSV文件需包含：

示例：详见 examples/reviews_sample.csv

---

输出示例

运行完成后，将在 output/ 目录生成以下文件：

1. CSV标签数据

评论内容,评分,性别,年龄段,职业,购买角色,使用场景,满意度...
"The quality is amazing",5,女性,25-34岁,白领,自用,家用办公,高...

2. Markdown洞察报告

# 产品分析洞察报告

## 核心发现
- 用户满意度：92%
- 主要优势：材质优良、设计美观
- 改进建议：优化包装、增强耐用性
...

3. HTML可视化看板

• 黑金奢华配色
• 交互式图表
• 动态数据展示
• 创作者署名（鎏金发光效果）

---

使用场景

场景1：产品优化

分析自己产品的评论，发现用户痛点，优化产品功能和设计。

场景2：竞品分析

分析竞品评论，了解竞争对手的优势和劣势，寻找差异化机会。

场景3：市场调研

批量分析多个产品的评论，了解市场需求、用户偏好和行业趋势。

场景4：用户洞察

深度了解目标用户群体，构建精准用户画像，优化营销策略。

---

项目结构

review-analyzer-skill/
├── main.py                      # V2.0 主入口（4 Phase 流程）
├── SKILL.md                     # Agent 指令文件（Claude Code Skill）
├── requirements.txt             # Python 依赖
├── .env.example                 # 环境变量模板
├── src/
│   ├── config.py                # CLI 单一模式配置
│   ├── template_engine.py       # 统一模板引擎（Jinja2 SSR + 共享基座）
│   ├── chart_engine.py          # Chart.js 图表配置生成
│   ├── insights_generator.py    # 15章洞察报告生成（CLI subprocess）
│   ├── agent_pipeline.py        # Agent 自执行模式（prepare/resume 状态机）
│   ├── pipeline_common.py       # 共享输出阶段（打标CSV + MD + HTML + 飞书）
│   ├── output_manager.py        # 输出管理（MD + HTML + 飞书同步）
│   ├── feishu_sync.py           # 飞书文档 + 白板同步
│   ├── report_generator.py      # 报告生成（兼容层）
│   ├── data_fetchers/           # 数据接入层（CSV + 卖家精灵）
│   ├── prompts/                 # 15章 Prompt 体系
│   └── templates/               # 可视化看板模板
│       ├── base/                # 共享基座
│       │   ├── dashboard_base.html   # 基座 HTML（Jinja2）
│       │   └── dashboard_base.css    # 基座布局 CSS
│       ├── premium-gold/        # 黑金主题
│       ├── dark-tech/           # 赛博朋克主题
│       ├── linear-minimal/      # 极简蓝白主题
│       ├── posthog-analytics/   # 暖橙分析主题
│       ├── stripe-executive/    # 翡翠企业主题
│       └── warm-editorial/      # 报纸编辑主题
├── assets/                      # 静态资源（README banner）
├── examples/                    # 示例数据 + 输出样例
├── tools/                       # 工具脚本
├── references/                  # 参考文档
└── docs/                        # 用户文档

---

常见问题

---

与其他工具对比

---

路线图

• [x] v1.0.0 - 首个正式发布（22维度标签 + 双模式 + HTML看板）
• [x] v2.0.0 - Agent 原生版（14章报告 + 6套主题 + 飞书同步 + 共享基座架构）
• [x] v2.1.0 - 异常信号卡 + 卖家精灵数据源 + 测试套件（52 用例）
• [x] v2.2.0 - Agent 自执行模式（打标与报告由宿主 Agent 完成，零 CLI 依赖；测试 59 用例）
• [x] v2.2.1 - description 三段式门面（品牌营销 + 英文概述 + 触发保留）
• [ ] v2.3.0 - Web 端增强（前端模板选择器 + 截图导出）
• [ ] v3.0.0 - 多平台分析（批量 ASIN + 竞品对比报告）

---

许可证

本项目采用 MIT License 开源许可证。

---

致谢

• 感谢 Anthropic 提供 Claude AI
• 感谢 Google 提供 Gemini API
• 灵感源自开源社区的智慧贡献

贡献者

感谢以下社区贡献者对本项目的贡献：

社区贡献者在提交 PR 后，维护团队会进行代码审查。为确保代码质量与稳定性，部分 PR 可能会以改进版本合入，而非直接 merge 原始提交。

---

技术支持

• Issues: GitHub Issues
• 联系Builder，请备注【github】：

---

📖 写在最后