dsh-aliyun-coupon

在 DeepSeek Harness（DSH）Web GUI 的侧栏页脚（sidebar.footer.action，即 dsh-cost-meter 余额/预算图框原来的位置）显示 阿里云卡券（代金券）的剩余余额、已用额度与到期时间。面向云工开物学生专属代金券这类账户券，也适用于任意阿里云代金券/抵用券。

• 数据源：阿里云官方 BSS OpenAPI 只读接口——首选 DescribeCoupon（2023-09-30，新费用中心「卡券」页同源数据）， 失败或返回空结果时自动回退 QueryCashCoupons（2017-12-14）。
• 凭据：只读 RAM AccessKey（LTAI…，不是百炼/DashScope 的 sk- Key），只在宿主进程里用于签名， 浏览器拿到的只有掩码 ID（LTAI5t...IjKl）与汇总数字。
• 路由：GET /api/dsh-aliyun-coupon/overview、POST /api/dsh-aliyun-coupon/refresh，仅回环地址可访问。

第一次装？ 从零到出数大约 5 分钟。建只读 RAM 用户、写 AK 文件、配置项、常见问题排查， 全在 使用说明（docs/usage.zh-CN.md） 里，本文只讲重点。

它显示什么

位置	内容
标题行	图框标题（默认「阿里云代金券」，可用 label 改）＋剩余余额，如 ¥123.46
进度条	已用 / 面值
第二行	面值 ¥500 · 已用 ¥376.54
第三行	到期 2027-12-31 ＋ 刷新提示 / 错误行
悬停	券号、券类型、面值、余额、到期时间；多张券逐条列出
侧栏收起态	只显示金额（¥123.5）

安装

方式一：插件页安装（推荐，桌面端也能用）

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

方式二：CLI（非 desktop profile）

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

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

本地开发

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

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

配置 AccessKey

优先级：环境变量 → AK 文件。任一路径给全 akId + akSecret 即可。

方式一（默认，推荐）：写进 ~/.dsh/aliyun-coupon.json

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

可选字段：stsToken（STS 临时凭据）、endpoint（国际站填 business.ap-southeast-1.aliyuncs.com）。 兼容别名：aliyunAkId / aliyunAkSecret / AccessKeyId / AccessKeySecret。 记事本保存的 UTF-8 BOM 会被自动削掉；该文件不要进 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 用户，只挂下面两个只读 Action（自定义策略即可），不要用主账号 AccessKey：

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

调用	Action
DescribeCoupon	bss:DescribeCoupon
QueryCashCoupons	bss:DescribeCoupons

嫌麻烦也可以直接挂系统策略 AliyunBSSReadOnlyAccess（读权限更多，但一样花不了钱、开不了资源）。 若返回 NotApplicable，说明该身份不适用于此接口——那种情况才需要主账号 AccessKey。

可选配置

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

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

键	默认	含义
refreshMinutes	10	宿主轮询间隔（1–1440 分钟）
akFile	~/.dsh/aliyun-coupon.json	AK 文件路径
endpoint	business.aliyuncs.com	BSS 端点（国际站换 business.ap-southeast-1.aliyuncs.com）
label	空	图框标题

数据与接口

• DescribeCoupon（BssOpenApi 2023-09-30，business.aliyuncs.com，ACS3-HMAC-SHA256 签名）： 返回 Amount（面值）、RemainAmount（余额）、Status、EndTime、Currency、ItemNames。
• QueryCashCoupons（2017-12-14，RPC 签名 V1.0，HMAC-SHA1）：返回 NominalValue、Balance、Status、ExpiryTime。
• 只把 Status === Available 的券计入总计；一张可用的都没有时退回全量，避免把「已过期」误报成 0。
• 余额按接口原样保留（阿里云给到小数点后 10 位），界面显示两位小数，悬停可见原值。

交互

• 卡片每 60 秒（页面可见时）拉一次宿主快照；点击卡片立即触发一次查询（刷新中显示「正在刷新…」）。
• 查询失败时保留上一次的数值，并在卡片上显示错误行，不会突然变成 0。

隐私与安全

• AccessKey 只留在宿主进程，用于对阿里云一个端点签名；不写日志、不进响应体。
• 浏览器只收到掩码 ID 与汇总数字；路由仅回环地址可访问，非本机请求 403。
• 插件只联系 business.aliyuncs.com（或你配置的 BSS 端点），没有任何遥测。

卸载

在「插件」页停用/移除，或删掉 profile 里的 aliyun-coupon 行后重启 DSH。AK 文件不会被自动删除——要清干净请自行删除 ~/.dsh/aliyun-coupon.json。

开发自检

npm test        # 等价于 node tools/selfcheck.mjs：签名串、解析、汇总、掩码，不联网

许可

MIT，见 LICENSE。