前言¶

在 DeepSeek Harness（DSH）里长时间跑 Agent 或对话时，阿里云账户余额、学生/活动代金券还剩多少，往往要单独打开控制台或另开脚本查。手工查一次不难，难的是和「今天花了多少 token」放在同一块视野里对照。社区插件 dsh-aliyun-coupon-api（维护者 tacotuesday22）走阿里云官方 OpenAPI 做只读查询，不需要账号密码登录网页；凭证用的是 RAM 子用户的 AccessKey，在侧边栏底部以挂件形式展示余额与券信息。若本机还安装了 dsh-cost-meter，同一卡片会多读一份本地账本，显示「今日消耗」一行。

这是什么¶

dsh-aliyun-coupon-api 是 DeepSeek Harness 的联网类插件（社区目录分类：联网工具）。它通过官方接口 QueryAccountBalance（账户余额）与 DescribeCoupon（优惠券/代金券列表，README 与 package 描述中提及「云工开物」学生券剩余额度等场景）拉取数据，在 DSH 侧边栏底部渲染卡片。数据刷新分两档：今日消耗每 30 秒读本地账本（无网络）；阿里云余额与代金券每 5 分钟请求一次 API；点击卡片可强制刷新两者。未配置 AccessKey 时卡片会提示「未配置」，并可从卡片进入 设置 → 阿里云代金券 完成引导式配置。

核心功能¶

侧边栏展示形态（示例来自仓库 README）：

今日  52.0M tokens        ¥1.93
余额                      ¥0.00
代金券                    ¥276.75
面值 ¥300.00 · 1 张 · 355天后到期

已核实能力如下：

1. 账户余额 / 代金券：调用阿里云 BSS 相关 OpenAPI，只读；推荐 RAM 系统策略 AliyunBSSReadOnlyAccess，或自定义策略限定 bss:DescribeCoupon、bss:DescribeAcccount（官方文档原始拼写）等动作。
2. 今日消耗（可选）：依赖本机 dsh-cost-meter 的本地账本；未安装则自动隐藏该行。
3. 内置设置页：保存 AccessKey 前会做校验；误填模型 API Key（sk- 开头）会提示；保存成功后可显示 AK 末四位。
4. 安全取向：不要求主账号 Key；文档强调子用户仅勾选「使用永久 AccessKey 访问」，不要勾选「使用控制台访问」。

插件当前 package 版本为 1.6.2（MIT 许可证），要求 Node >=20、dsh >=0.1.6，支持 darwin / linux / win32。

安装与启用¶

安装前需确认：向 desktop profile 装插件时，必须使用 DeepSeek Harness 桌面版自带的 dsh CLI；npm i -g @deepseek-ai/dsh 的全局 CLI 无法操作 desktop profile，会被拒绝。

Windows 默认 CLI 路径示例：

%LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd

macOS 示例：

/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh

下文用 <dsh> 表示你机器上可用的完整路径。

获取安装包¶

仓库说明：lib/ 不在 Git 里，需在项目目录执行构建后再打包。在 dsh-aliyun-coupon-api 源码目录中：

npm install          # prepare 会自动生成 lib/
npm pack             # 生成 dsh-aliyun-coupon-api-<版本>.tgz

也可直接使用他人提供的 .tgz，跳过构建。README 建议用 tarball 安装，避免 dsh plugin add . 产生指向源码目录的符号链接（移动或删除目录可能导致插件失效）。

安装到 desktop profile¶

Windows：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
  plugin --profile desktop add .\dsh-aliyun-coupon-api-<版本>.tgz

macOS / Linux：

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add ./dsh-aliyun-coupon-api-<版本>.tgz

若包已发布到 npm，同样必须用桌面版 CLI：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
  plugin --profile desktop add dsh-aliyun-coupon-api

确认安装：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" `
  plugin --profile desktop list

列表中应出现 dsh-aliyun-coupon-api@<版本>。卸载时将 add 改为 remove。

安装后必须完全退出并重启 DeepSeek Harness；仅刷新页面不够，插件在启动时加载。

配置 AccessKey（只读 RAM 子用户）¶

推荐流程：① 建只读子账号 → ② 装插件 → ③ 填 AccessKey → ④ 验证。AccessKey 的创建必须在 阿里云 RAM 控制台 由本人操作，不要把 Secret 交给 Agent 或贴到聊天里。

1. 创建 RAM 用户：勾选 「使用永久 AccessKey 访问」，不要勾选「使用控制台访问」。
2. 授权：最快方式是挂系统策略 AliyunBSSReadOnlyAccess；或按 README 创建自定义策略 DSH-Coupon-ReadOnly。
3. 在 DSH 中：侧边栏卡片点 去设置 ›，在 设置 → 阿里云代金券 填写 AccessKey ID 与 Secret，点 保存并测试（验证失败不会保存）。

可选：在配置前用环境变量在仓库里跑 live 测试（README 提供）：

export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI...
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
npm run test:live

输出中能看到券余额与账户余额，说明权限与 Key 可用。

典型用法¶

安装、重启并完成 AccessKey 配置后，无需额外命令：侧边栏底部卡片会持续刷新。需要立刻对齐阿里云侧数据时，点击卡片 即可强制刷新余额与代金券（今日消耗仍按本地账本节奏更新）。

若与 dsh-cost-meter 同机使用，卡片第一行会显示当日 token 与对应费用估算；两行数据来源不同，刷新间隔也不同，属预期行为。

适用场景与注意¶

适合谁：已在 DSH 桌面版日常开发、使用阿里云 BSS 账户，希望在 IDE 侧边栏一眼看到余额与代金券、并可选对照本地 token 账本的用户。

权限与安全：

• 插件以当前 DSH 进程权限运行；安装前应自行阅读 仓库源码 与 MIT 许可证，评估是否接受将 RAM AccessKey 存入 DSH 插件配置。
• 务必使用 子账号 + 只读策略，不要用主账号 AccessKey；填的是 RAM AccessKey（通常 LTAI 开头），不是 DeepSeek 模型 API Key（sk- 开头）。
• OpenAPI 调用有频率设计（5 分钟缓存）；频繁点击强制刷新会增加请求次数，一般日常使用足够。

社区插件目录由 SkillHub 等站点维护，与 DeepSeek / 幻方无官方从属关系；星标与版本以 GitHub 与目录页为准（撰写时 GitHub 星标为 0）。

结尾¶

dsh-aliyun-coupon-api 把阿里云账户余额、代金券与可选的本地「今日消耗」收进 DSH 侧边栏，用官方 OpenAPI 与 RAM 只读 Key 完成查询，配置路径与校验逻辑在插件设置里已经串好。需要逐步截图式教程或故障排除时，以仓库 README 为准。

• 社区目录：https://www.skillhub.cn/plugins/tacotuesday22/dsh-aliyun-coupon-api
• GitHub：https://github.com/tacotuesday22/dsh-aliyun-coupon-api