Hercules-debug/huixuan-assistant

慧选助手 (huixuan-assistant)

在 DeepSeek Harness 对话里用 AI 帮你挑商品的插件 —— 搜索、对比、给建议。

它能做什么

你直接说需求：

我想买个充电宝，100 块以内，要能上飞机

插件会：
1. 调用拼多多开放平台官方 API 搜索商品
2. 按价格、销量、服务标签筛选排序
3. 用 LLM 从标题提取特征，生成对比表
4. 给出推荐 + 推广链接（跳转购买）

实测例子：算单价、挑最划算的

你：帮我看看抽纸，算一下每百抽多少钱

插件（搜索 → 逐件对比 → 换算单价 → 展示商品图）：

| # | 商品 | 价格 | 销量 | 规格（从标题读） | 每百抽 |
|---|---|---|---|---|---|
| 7 | 心相印 茶语丝享 110抽×20包 | ¥7.38 | 200万+ | 110抽×20包 | ¥0.336 |
| 8 | 心相印 山茶花 XS码 80抽×30包 | ¥4.06 | 13.7万+ | 80抽×30包 | ¥0.169 🏆 |
| … | （其余 8 件因「按克/按卷卖」或「标题未给规格」无法换算，模型逐条标注了原因） | | | | |

🏆 每抽最便宜：心相印山茶花 3层XS码 80抽×30包

| 项目 | 值 |
|---|---|
| 价格 | ¥4.06（原价 ¥23.5，省 83%） |
| 规格 | 80抽 × 30包 = 2400 抽 |
| 每百抽 | ¥0.169 —— 比第二名便宜 50% |
| 销量 | 13.7万+ |
| 服务 | 正品险 / 七天退换 / 假一赔十 / 48小时内发货 / 未发货可秒退 |
| 购买链接 | 由 shop_promote_url 生成 |

商品图由工具卡片自动显示。

这个例子体现了几个设计点：

- 模型没有硬凑数据 —— 按克/按卷卖的、标题没给规格的，逐条说明「不可算」而不是编一个数
- 主动声明数据来源 —— 明确说「规格是从标题读出的，接口不返回规格字段」
- 图是自动出现的 —— 不需要你开口要

⚠️ 先说清楚它的边界

这不是「全网比价工具」，能力有明确范围：

| 限制 | 说明 |
|---|---|
| 仅覆盖可推广商品 | 联盟 API 不是全量商品库 |
| 没有商品规格参数 | 拼多多 API 实测不返回 productParams 之类的字段，参数靠 LLM 从标题提取 |
| 共享配额约 10 次/分钟 | 零配置模式下所有用户共享开发者额度 |
| 详情/对比按件消耗配额 | shop_search 一次调用返回整页；但 shop_detail 与 shop_compare 每个商品各消耗一次调用。对比 4 件 = 4 次配额 |
| 不做下单/支付 | 不碰交易链路 |

关于配额的实践建议：个人账号约 10 次/分钟，所以插件在工具描述里明确约束了模型 ——
先与用户确认要深入了解的商品，只对 2~4 个调用详情/对比，不要对整页搜索结果逐个调用。
配额用尽时会返回可读提示并引导用户配置自己的凭证（见下文三级凭证）。

| 搜索结果只带前几件的图 | shop_search 为前 3 件附带主图（可配）；一页 15~40 条不会全部带图。单张上限 3MB、超时 8s |

图片说明：商品图经 DSH 附件服务登记后，作为图块放进工具结果的 content，
由工具卡片自动显示，不需要你开口要图。
当前模型是纯文本的，dsh-llm 会在发给模型前把图块投影成占位符
（[image omitted because this model accepts text only; …]），不会浪费 token。
图片获取全程 best-effort：超时、过大、非图片或附件服务不可用时，一律降级为纯文本结果，
不会让商品查询失败。

而且：

不做爬虫。 商品数据一律走官方 API。相关判例已明确（如杭州中院 2025 浙01民初1729号案，批量搬运商品数据 + AI 二次利用被判赔 100 万元），且「用 AI 加工过」不能作为免责理由。

安装

dsh plugin --profile web add github:Hercules-debug/huixuan-assistant

安装后重启 dsh web。

使用

装好直接对话即可，模型会自动调用这些工具：

| 工具 | 作用 |
|---|---|
| shop_search | 搜索商品（支持价格区间、排序） |
| shop_detail | 查单个商品详情 |
| shop_compare | 批量对比多个商品 |
| shop_promote_url | 生成推广链接 |

商品图是自动显示的：搜索结果的卡片里就会带上前几件的主图；想让某件商品出图，
说「看第 N 个」即可。插件不会（也不能）在回答里贴图片链接 —— DSH 对话不渲染远程图片。

凭证配置（可选）

装完即用，零配置。 插件内置了一份共享测试凭证，直接对话就能搜商品。

⚠️ 关于内置凭证，请务必了解：

- 它是公开的（就在本仓库 lib/credentials.mjs 里），没有任何保密性；
- 拼多多个人账号约 10 次/分钟，所有用户共享这一额度，并发时会排队或失败；
- 所有调用记在开发者实名账号上，被滥用只能重置密钥 —— 那会让所有已安装用户同时失效；
- 因此它仅供试用。想稳定使用请配置自己的凭证（见下）。

配置自己的凭证（推荐长期使用）

在 DSH 里打开 设置 → 插件 → 插件配置，找到「慧选助手」卡片，填写三项：

| 字段 | 从哪来 |
|---|---|
| Client ID | open.pinduoduo.com → 控制台 → 应用列表 |
| Client Secret | 同上 |
| 推广位 PID | jinbao.pinduoduo.com → 推广管理 → 推广位管理 |

填满三项后自动切换到独立配额，佣金也归你自己。

⚠️ Client Secret 只保存在本机 DSH 凭据库（~/.dsh/.credentials.yaml），
不经由对话、不写入会话日志、不上传任何地方。
但仍请注意：永远不要把 client_secret 发给任何人，包括 AI 助手。

不想用图形界面？手动配置也行

~/.dsh/settings.yaml —— 非密钥字段
huixuan-assistant:
clientId: "你的 Client ID"
pid: "你的推广位 PID"

~/.dsh/.env —— 密钥（权限建议 600）
HUIXUAN_PDD_CLIENT_SECRET=你的密钥

密钥走 DSH 凭据服务的引用解析，分层顺序为：
进程环境变量 > ~/.dsh/.credentials.yaml > /.env > ~/.dsh/.env。

为什么没有「开发者密钥 + 用户 PID」这一档

早期设计里有 Level 1（用开发者的密钥配用户的 PID，佣金归用户），
但拼多多的 duoId ↔ clientId 绑定校验要求「绑定 clientId 与当前 clientId 一致」，
跨账号组合很可能被拒，且该绑定不支持解绑。

与其让用户撞上一个含义不明的绑定错误，插件只保留两档：

| 级别 | 条件 | 配额 | 佣金 |
|---|---|---|---|
| Level 0 | 什么都不填 | 开发者共享（约 10 次/分钟） | 开发者 |
| Level 2 | 三项齐全 | 独立 | 归你 |

只填了一部分时明确报错并列出缺失项，不会静默降级。

数据来源与合规

本插件：

- 仅使用拼多多开放平台官方 API 获取公开商品数据
- 不抓取网页、不绕过技术措施、不存储原始商品数据
- 不涉及用户隐私信息与交易订单数据
- 所有商品展示后均跳转至原平台完成购买

开发

git clone https://github.com/Hercules-debug/huixuan-assistant
cd huixuan-assistant

本地开发凭证（已被 .gitignore 忽略）
cp .env.example .env
填入 PDD_CLIENT_ID / PDD_CLIENT_SECRET / PDD_PID

准备开发环境：把 DSH 核心包软链到项目，使源码可直接导入测试
node scripts/setup-dev.mjs

集成测试（会真实调用拼多多 API，注意配额）
node scripts/verify/integration.mjs

模块自测（签名 / 限流 / 缓存 / 凭证降级，不调外部 API）
node scripts/verify/smoke.mjs

装到本地 DSH 调试

dsh plugin --profile web add file:/绝对路径/huixuan-assistant
改完代码后重装（pnpm 用硬链接，编辑源码不会自动同步到 profile）
dsh plugin --profile web add file:/绝对路径/huixuan-assistant
重启 dsh web 生效

插件 API 要点

// ✅ 正确：execute 在 defineTool 内部，register 只收一个参数
ctx.tools.register(defineTool({
name: 'my_tool',
description: '...',
parameters: { q: { type: 'string', required: true, description: '...' } },
output: {
schema: {                      // 必填；根节点必须是 object
type: 'object',
additionalProperties: false,
properties: { ok: { type: 'boolean', required: true } },
},
render: (args, value) => [{ type: 'text', text: '...' }],
},
execute: async (args, exec) => ({ ok: true }),
}));

常见坑（都已踩过）：

| 坑 | 症状 |
|---|---|
| patch 缺 insert: | patch: entry "x" not found |
| output.schema 缺失 | schema must be a value schema object |
| 根级 required | schema.required is not supported |
| type: ['a','b'] 数组 | type must be string/number/... or use oneOf |
| 返回 null 字段 | 与 schema 类型冲突，需剔除 |

详细设计见 DESIGN.md。

状态

开发中（v0.1.0） —— 核心 API 客户端与工具已完成并通过实测，UI 设置面板待补。

投稿到插件社区

本插件已准备投稿到 awesome-dsh-plugin（DSH 社区插件目录）。

条目文件与提交步骤见 community/：
- community/awesome-dsh-plugin.yml —— 待提交的条目
- community/SUBMIT.md —— 完整流程与评审要点

当前状态：待提交（指南要求仓库创建满 1 天，CI 自动检查）。

许可

MIT

本仓库同时作为拼多多开放平台应用「慧选助手」的开发者官网地址。