慧选助手 (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

---

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