# Jd Review Collector

> 京东商品评论本地采集与分析浏览器扩展的使用手册。当用户需要采集京东商品评论、分析商品口碑/差评/正负面、安装或配置这个采集扩展、解释扩展的 AI 设置与 API Key 安全边界、或对已采集的评论结果（JSON / Excel / ZIP）做进一步分析时使用。This skill should be used when the user asks to collect JD.com product reviews, install or configure the JD review collector extension, explain its AI analysis or API key handling, or further analyze collected review results (JSON / Excel / ZIP).

- Skill: `ryan-zhao03/jd-review-collector` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ryan-zhao03/jd-review-collector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryan-zhao03/jd-review-collector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: Ryan-Zhao03 (https://skillmd.com/u/ryan-zhao03)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ryan-zhao03/jd-review-collector

---


# 京东评论本地采集助手

## Overview

本 skill 封装一个完整的 Manifest V3 浏览器扩展（兼容 Microsoft Edge 与 Google Chrome），用于在已登录的京东商品页采集当前筛选条件下的评论，并在浏览器内生成「原始 JSON + 分析 Excel」的 ZIP 分析包（下载到浏览器默认下载目录），可选接入 AI 辅助分析。扩展源码位于 `assets/extension/`（v0.9.3），可直接加载使用。

**关键边界**：浏览器扩展必须由**人**在扩展管理页手动加载（或走企业策略分发），skill 无法让扩展「自动安装」。本 skill 的职责是：引导用户装好扩展、采集评论，并对采集结果做进一步分析。

## When to Use

用户请求命中以下任一场景时使用本 skill：

- 采集京东商品评论、做商品口碑 / 差评 / 正负面分析；
- 安装、加载这个采集扩展；
- 配置扩展的 AI 辅助分析（服务商、模型、API Key），或询问 AI 逻辑与 Key 安全；
- 用户把采集结果（ZIP / JSON / Excel）发回来，或期望 Agent 自动定位采集结果做进一步分析。

## 首次触发引导（Onboarding）

当用户第一次表达「要用 / 要装 / 这是什么」时，**不要只回一句简介**。按以下四步，用自然语言一步步引导用户走完，措辞细节见 `references/install-and-use.md`，但引导骨架必须完整覆盖，不得省略任何一步：

1. **安装**：扩展源码在 `assets/extension/`；Edge 打开 `edge://extensions`、Chrome 打开 `chrome://extensions` → 打开「开发人员模式」→ 「加载解压缩的扩展」→ 选能直接看到 `manifest.json` 的目录 → 固定扩展并刷新京东页面。
2. **采集使用**：登录京东 → 打开商品详情页 → 选评价筛选（全部 / 好评 / 中评 / 差评 / 追评）→ 点扩展图标核对「当前筛选」→ 输目标评论数（1–5000）→ 「开始收集」→ 结束后浏览器自动下载 ZIP（含 JSON + Excel）。
3. **AI 配置**（可选）：点弹窗「打开 AI 设置」→ 选服务商（OpenAI / DeepSeek / 自定义）→ 填自己的 Key → 测试连接 → 保存并启用；同时讲清「采集与 AI 是两件事」「目标评论数 ≠ 每批评论数」。
4. **安全边界**：Key 只存本地浏览器、不随任何交付物流通、换人换电脑换浏览器都要重填（详见 `references/ai-safety.md`）。

## Bundled Resources

- `assets/extension/` — 完整扩展源码（入口 `manifest.json`，v0.9.3），直接作为「加载解压缩的扩展」目录使用。
- `references/install-and-use.md` — 安装、采集使用、AI 配置的完整步骤。
- `references/ai-safety.md` — API Key 作用域、安全边界、三道校验、移交口径。
- `references/result-analysis.md` — 采集结果（ZIP / JSON / Excel）的结构与进一步分析方法。
- `references/acceptance-test.md` — 验收剧本：触发测试用例 + 结构完整性核对。
- `scripts/verify-skill.mjs` — 自动校验 skill 结构与扩展文件完整性（Node 内置模块，无依赖）。
- `scripts/build-package.ps1` — 仅在用户明确要求「安装包」时，把扩展打包成带版本号的 ZIP。

## 工作流

### 1. 安装扩展

读取 `references/install-and-use.md` 的「安装」部分，按 Edge / Chrome 分别给出步骤，引导用户加载 `assets/extension/` 目录。公司禁用开发人员模式时说明需走 IT 企业策略分发。

### 2. 采集使用

读取 `references/install-and-use.md` 的「采集使用」部分，给出从登录到下载 ZIP 的完整链路。

### 3. AI 配置（可选）

读取 `references/install-and-use.md` 的「AI 配置」部分与 `references/ai-safety.md`。讲清：采集与 AI 是两件事；目标评论数（弹窗）与每批评论数（设置页）是不同参数；AI 未配置 / 调用失败 / 校验不过时自动回退本地规则引擎，不丢已采集数据。

### 4. 结果进一步分析

当用户把采集结果发回窗口，或说「帮我看看刚才采集的结果」时，读取 `references/result-analysis.md`。两条路均可：**路径一（推荐）** 先询问用户浏览器下载目录（Agent 无法读浏览器设置，需用户提供），到该目录定位最新 `jd_review_analysis_*` 文件；**路径二** 用户直接拖 ZIP / JSON / XLSX 进对话。拿到 ZIP 后**由 Agent 解压**（`Expand-Archive` / `unzip` / 脚本，无需用户手动解压），优先读 JSON 原始数据，结合用户的具体问题做分析。

### 5. 路径展示规范（隐私保护，强制）

**向用户展示任何本机路径时，禁止展开为含真实用户名的绝对路径**（如 `C:\Users\<真实用户名>\...`），统一使用以下形式：

- 用户主目录用 `~`：如 `~/.workbuddy/skills/jd-review-collector/assets/extension`；
- 不确定用户名的目录用占位符：如 `C:\Users\<用户名>\Downloads`、`D:\<用户名>\下载`；
- 或直接使用相对路径 / 描述性文字（如「skill 内的 `assets/extension` 目录」）。

skill 文档与对话示例一律用占位符，不得把任何具体用户的真实路径、用户名写进 skill 或示例。

## 验收

交付或自测时，先运行 `scripts/verify-skill.mjs` 做结构自动校验，再按 `references/acceptance-test.md` 的触发用例做对话验收，确认 Agent 命中本 skill 后能给出完整引导。

## Changelog

### v0.9.3（2026-09-08）

- 扩展同步至 **v0.9.3**，`assets/extension/` 与源项目逐文件一致（`diff -rq` 零差异）。
- 补齐开源三件套：`LICENSE`（MIT © Yi.Zhao）、`README.md`、`.gitignore`。
- 结构自检 **41/41**、扩展单元测试 **91/91** 通过。
- 安全复核通过：无个人路径硬编码、无密钥硬编码、无 `eval` / `innerHTML` 等危险执行面、无异常外联域名；`page-hook.js` 对 fetch / XHR / JSONP 为只读拦截，不篡改请求；会话存储不含登录凭证。
- 新增路径展示规范（隐私保护，强制）：向用户展示本机路径时禁止展开含真实用户名的绝对路径。