前言¶

在 DeepSeek Harness（DSH）里长时间跑 Web GUI 时，侧栏页脚往往只关心本机或 DSH 自身的费用视图。若你手头有阿里云代金券（例如云工开物学生专属券），余额和到期时间仍要去控制台「卡券」页核对，和当前工作流是割裂的。dsh-aliyun-coupon 把官方 BSS OpenAPI 的只读查询接到 DSH 侧栏页脚（sidebar.footer.action，与 dsh-cost-meter 图框同类位置），在浏览器里看到剩余余额、已用额度和到期时间，而 AccessKey 只留在宿主进程里签名，不进入前端。

下面介绍插件定位、能力边界，以及从零安装到配凭据的可复现步骤。

这是什么¶

dsh-aliyun-coupon 由 fvvef121-cell 维护，当前 npm 包版本 0.1.1，许可证 MIT，Node >=20，支持 darwin / linux / win32。SkillHub 分类为客户端插件；仓库 dshhub 元数据还标注费用、Web UI、观测等标签。

一句话：用只读 RAM AccessKey 调用阿里云 BSS OpenAPI，在 DSH Web 侧栏页脚显示代金券剩余余额、已用额度与到期时间；面向云工开物类账户券，也适用于一般代金券/抵用券。

核心功能¶

侧栏展示¶

数据来源与汇总规则¶

• 首选 BSS OpenAPI DescribeCoupon（2023-09-30，与新费用中心「卡券」页同源）；失败或空结果时回退 QueryCashCoupons（2017-12-14）。
• 只把 Status === Available 的券计入总计；若无可用券则退回全量列表，避免把已过期券误报成 0。
• 余额按接口原样保留（阿里云可到小数点后 10 位），界面显示两位小数，悬停可见原值。

宿主 API 与交互¶

宿主提供只限回环访问的路由：

• GET /api/dsh-aliyun-coupon/overview
• POST /api/dsh-aliyun-coupon/refresh

带 X-Forwarded-For 等代理头、跨站请求会被拒绝。页面可见时每 60 秒拉一次宿主快照；点击卡片立即刷新（显示「正在刷新…」）。查询失败时保留上次数值并显示错误行，不会突然归零。

安装与启用¶

插件以当前 DSH 宿主进程权限运行；安装前建议在 GitHub 阅读源码与 LICENSE，确认只读 RAM 策略符合你的安全要求。

方式一：插件页（推荐，含 desktop）¶

DSH 的 desktop profile 由桌面 App 独占，CLI 不能改动。桌面端请在 DSH 插件页添加本包（本地目录或 GitHub 源），装好后刷新页面。

方式二：CLI（非 desktop profile）¶

新建的 profile 若只有 @deepseek-ai/dsh-base、没有 webServer，插件会停在 pending (waiting for service: webServer)。需先用 dsh <profile> --from-default-profile web 建出带 Web 层的 profile，再执行：

dsh plugin --profile <profile> add github:fvvef121-cell/dsh-aliyun-coupon

本地开发可链接目录：

dsh plugin --profile <profile> add link:/path/to/dsh-aliyun-coupon

装完重启或刷新后，侧栏页脚会出现图框；尚未配置 AccessKey 时会显示配置提示。

典型用法：凭据与可选配置¶

AccessKey 配置¶

凭据类型是阿里云只读 RAM AccessKey（LTAI…），不是百炼/DashScope 的 sk- Key。优先级：环境变量 → AK 文件；任一路径提供完整的 akId + akSecret 即可。

方式一（默认）：写入 ~/.dsh/aliyun-coupon.json：

{
  "akId": "LTAI5t...",
  "akSecret": "..."
}

可选：stsToken（STS 临时凭据）、endpoint（国际站填 business.ap-southeast-1.aliyuncs.com）。兼容别名包括 aliyunAkId / aliyunAkSecret / AccessKeyId / AccessKeySecret。该文件不要进 git，也不要贴进聊天。

方式二：环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET（别名 ALIYUN_AK_ID / ALIYUN_AK_SECRET），可选 ALIBABA_CLOUD_SECURITY_TOKEN、ALIYUN_BSS_ENDPOINT。

RAM 最小只读权限¶

建议单独建 RAM 用户，自定义策略示例：

{
  "Version": "1",
  "Statement": [
    { "Effect": "Allow", "Action": ["bss:DescribeCoupon", "bss:DescribeCoupons"], "Resource": ["*"] }
  ]
}

也可挂系统策略 AliyunBSSReadOnlyAccess（读权限更广，仍无法开资源或扣费）。若返回 NotApplicable，说明该身份不适用该接口，那种情况才考虑主账号 AccessKey（一般不推荐）。

profile 可选项¶

在 profile 的 cordis.patch.yml 中按 id: aliyun-coupon 覆盖：

- id: aliyun-coupon
  config:
    refreshMinutes: 10
    label: 云工开物券

更完整的首次安装与排错见仓库 docs/usage.zh-CN.md。

适用场景与注意¶

适合谁：在 DSH Web 侧栏常驻查看阿里云代金券余额与到期、又不想把 AK 暴露给浏览器或第三方遥测的开发者；云工开物等学生券用户是典型场景之一。

安全与隐私（仓库自述要点）：

• AccessKey 仅在宿主进程用于对 *.aliyuncs.com BSS 端点签名；浏览器侧主要是掩码 AK ID、余额、脱敏券号、~ 形式文件路径。
• API 路由限制回环、拒绝常见反向代理头与跨站请求；错误信息脱敏，不回显阿里云 Message。
• 插件只联系配置的 BSS 端点，无遥测。

卸载：在插件页停用/移除，或删除 profile 里 aliyun-coupon 配置后重启；~/.dsh/aliyun-coupon.json 不会自动删除，需自行清理。

离线自检（维护者开发用）：

npm test

等价于 node tools/selfcheck.mjs，覆盖签名串、解析、汇总、掩码，不联网。

结尾¶

dsh-aliyun-coupon 把阿里云卡券余额接到 DSH 侧栏页脚：BSS 只读 OpenAPI、凭据留在宿主、前端只看汇总与脱敏明细。DeepSeek Harness 生态强调「一切皆插件」；社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，安装来源以目录页与 GitHub 为准。

• 目录页：https://www.skillhub.cn/plugins/fvvef121-cell/dsh-aliyun-coupon
• 源码与 README：https://github.com/fvvef121-cell/dsh-aliyun-coupon