DSH Connect Agnes Token Plan

dsh-connect-agnes-token-plan

把 Agnes 接进 DSH：Plugins 页的插件卡（三个 tab），外加会话输入框右侧的一枚用量胶囊。DSH 即 DeepSeek Harness；Agnes（爱思）是全模态大模型平台，本插件对接其控制台 API 与推理 API。

第一次读这个仓库？先看这三句。

1. 这是给 DeepSeek Harness 用的插件，不是独立应用；面板入口在 DSH 的 Plugins 页那张卡上（三个 tab，见下），另有一枚会话内的用量胶囊（见「对话框用量胶囊」）。

2. 三种「红」是正常的，不是回归：① test/wiring.test.mjs 等 peer 套件报 cannot resolve the peer dependency —— 那是 DSH runtime 自带的包不在本仓库，属环境问题，先查 test/peer-roots.mjs；② 没装 dsh CLI 时 e2e 会 SKIP，属预期；③ 若在 23:00–00:00 之间单独跑 render.test.mjs 报红，那是历史上的午夜窗口缺陷（已在 0.10.0 修复，见 docs/PITFALLS.md §48），当前安装版本已含，无需升级。

3. 见到「奇怪」的写法先别定罪——本仓多数刻意的取舍都在 docs/PITFALLS.md / docs/ADR.md 有明文出处。动手前先 grep 一遍 docs/。

协作会话的完整纪律见 AGENTS.md（不随 npm 包发布，registry 页面上请从 GitHub 打开）。

• 积分额度——登录后实时查看积分余额、额度窗口与每模型消耗；设了 AGNES_PASSWORD 则令牌到期自动重登，之后无需再管；
• 接入 API——把 Agnes 模型注册为 DSH provider，参与对话、出图与出视频；
• AgnesCode——上游限流较宽松的另一条产品线（爱思办公桌面端），独立账号、独立积分。

面板分三个 tab，按「先看数、再接入、最后可选加桌面端上游」排序：

积分额度

将 Agnes 的 Token Plan 接入 DSH，用超了只能等窗口重置。这个 tab 把数字搬进 DSH，写代码时不用切网页就能盯住：

• 额度窗口：模型请求（5 小时滚动）、每周请求、生图与视频（各 24 小时），平台报出已用量、独立滚动，（含百分比与重置时间）
• 账号累计用量：控制台口径的累计请求 / 文本 Token / 生图 / 视频秒数 / 活跃天数，以及近 N 天的分桶柱图
• 套餐对比：平台公开的套餐目录（六档），无需登录即可读，用来回答"升级能买到什么"

首次使用在「连接 Agnes 控制台」填一次账号和密码。Agnes 不发 refresh token，续期就是拿账号密码自动重登一次——而密码不落盘，环境变量 AGNES_PASSWORD 是它唯一的持久来源（这是显式 opt-in）：设了它，令牌到期 Host 会自己重登；没设，令牌失效后面板会让你重新输一次（面板上那行「自动恢复」状态会直说当前是哪种）。登录失败时表单会直接显示 Agnes 返回的原因；密码错误属于凭据型拒绝，面板绝不自动重试（Agnes 有失败次数锁定）。想清除账号，用面板底部的按钮。

接入 API（可选）

把 Agnes 模型注册为 DSH provider，参与对话与出图。

• 模型清单：在「API Key」卡粘贴 Key 保存AGNES_TOKEN_PLAN_API_KEY，Host 以 agnes-token-plan 之名注册 OpenAI 兼容 provider，模型列表随 /v1/models 自动刷新；
• 语言模型：显示当前 Key 实际能调哪些模型，其中哪些能看图（按平台 input_modalities 判定，不靠名字猜）。
• 出图工具：Host 给 agent 注册 agnes_draw_image ，出图模型按 catalog 的 output_modalities 结构化判定。
• 视频工具：Host 给 agent 注册 agnes_video_generate，按选中模型分派 V2.0 / 2.5 两套互斥参数。
• 开关、勾选与工具挂载都热生效，无需重启：翻一次开关，出图 / 视频工具就地注册或撤下（0.13.x 起；宿主不给卸载句柄时工具对本进程粘性，见 docs/TOOL-HOT-RELOAD.md）。细节见 docs/SETUP.md §3、docs/PROVIDER-HOT-RELOAD.md 与 docs/AGNES-API.md §7.5。

注意：sk- 走 API 按量计费，cpk- 走订阅配额（本 tab 只读订阅配额），两类 Key 有独立限制池，需从官网了解实际限制。

AgnesCode（可选，默认关）

读取 AgnesCode 桌面端 留在本机的加密会话文件，获取登录态，再以 provider id agnescode 注册独立 provider、独立积分池——两条上游凭据互不相通：

1. 接口地址：写在会话文件里、按账号跟随，钉死在 Agnes 域名族内，地址不对就拒绝使用；
2. 显示口径：积分是订阅池（时效 + 永久）；模型清单带「会员」标记而不隐藏——会员门槛是账号状态，不是模型不存在；
3. 约 28 天续期一次：JWT 过期后没有续期端点，重采集是自动的——让桌面 App 重新登录一次，下一次请求就会自己重读会话文件；tab 里的「检测本机登录态」是主动触发（能看分诊结果），不是必须步骤；
4. 本机登录态采集仅支持 Windows：macOS / Linux 的采集路径未实现（面板里也会这么提示）；
5. 读的是桌面 App 的登录态，不是本插件的账号：插件只读、从不写回那个会话文件，也没有「登出」按钮——关开关只是停用（已存的令牌还在，重新打开即可复用）；要真正吊销，请在桌面 App 里登出或改密码。授权与撤销都在 App 那一侧，本插件不代劳（详见 docs/SETUP.md §3）。

协议探针记录见 docs/ROADMAP.md §6.3。

注意：检测不到登录态时，面板会逐条列出探测过哪些文件、各自为什么没成（「没装 App」「解不开密」「会话里没有令牌」是三种不同的处理）；

对话框用量胶囊（自动出现）

输入框右侧会出现一枚用量胶囊，画哪条上游的额度由当前会话选中的模型决定，前缀写明是谁的：选中 agnes-token-plan 的模型显示控制台的 5 小时 / 本周已用百分比（前缀 Token Plan）；选中 agnescode（桌面端）的模型显示那套积分余额（前缀 AgnesCode）。圆点分级（绿 / 黄 / 红 / 灰）。点开余额胶囊是一张只看关键数的卡：余额、时效 / 永久拆分，加一行「经本插件」今日调用次数与 token 用量（只算经本插件 agnescode provider 的请求，不含桌面 App，也不冒充账号总量），以及「为什么没有数字」；账号昵称、平台发放、限流记录、账户流水这些深记录都留在 AgnesCode tab，不塞进这枚 28px 的胶囊。

• 读数与面板同源：控制台百分比优先用平台自己报的 usage_pct、缺失才回落 已用 / 上限，不做钳制（超额窗口就显示 >100%，那是事实）；桌面端画的是存量，所以不造百分比——网关只公布积分，没有「上限」可以当分母；
• 两条上游互不借用：agnescode 的会话只读它自己的路由、绝不画控制台窗口，反之亦然；切到别的 provider（其它插件）的模型时胶囊直接消失，也不再发任何请求；
• 读不到时保留上一次数字并标「上次数据」，不会清零或伪装成 0%；余额里的 0 是「烧完了」的读数（红色告警），— 才是「这次没读到」——这个区别是刻意的；
• 网关新上了模型时，余额胶囊会多一段「· N 新模型」（名字在 tooltip 与展开卡里，最多三个，保留 7 天）。这里的「新」指这台机器第一次见到它，不是上游的上架时间——网关目录没有这个字段。装上新版后的第一次运行只把当时的目录记下来当基线，不会把整张表报成新的。

边界

• 面板不代你操作账务——不改套餐、不代扣额度、不碰 Key 明文；数据来自 Agnes 控制台自己的 API，与网页控制台口径一致。
• 注册 provider、挂出图工具、挂视频工具、接桌面端上游，全部 opt-in 且默认关闭；一个都不打开时，插件退化为纯信息展示。

安装

1. 在 DSH「插件」页搜索 dsh-connect-agnes-token-plan 点击安装，或运行：

dsh plugin --profile web add dsh-connect-agnes-token-plan       # Web 端
   dsh plugin --profile desktop add dsh-connect-agnes-token-plan  # 桌面端

1. 完全退出 DSH（含托盘）再启动。
2. 打开 DSH 的 Plugins 页，找到 dsh-connect-agnes-token-plan 的插件卡（面板是页内的内联卡片，不在侧边栏）。

装到的是哪一版由源决定：安装器会询问 profile 配的 registry，默认含 `registry.npmmirror.com`，刚发布的版本在镜像上可能延迟几分钟，官方源立即可用；要确认拿到了哪一版，对照 npm view dsh-connect-agnes-token-plan version --registry=https://registry.npmjs.org。三种 target 形态（npm 包名 / git 地址 / 本地路径）见 docs/SETUP.md。

它是怎么工作的

登录原理：

• Host 在后台向 {consoleBase}/api/user/login 发一次账号密码 POST 换取 access token（Agnes 没有 OIDC 跳转、没有 refresh token），令牌过期或被拒时用同一路径重登一次；
• /api/cn/user/subscription 直接返回每个窗口的 used / limit / reset_at / usage_pct（控制台「当前用量」那一屏的数据源），面板逐字转写、不做减法。下方的「账号累计用量」统计同理，
• 面板打开时才轮询一个只读本地路由，关掉即停。协议细节（一跳登录、密码明文过 TLS 与「不落盘」纪律、防锁号节流）见 docs/AUTH.md，接口契约见 docs/AGNES-API.md。

运维诊断：这台机器现在挂没挂 provider？

provider / 出图 / 视频 / AgnesCode 开关的生效值存在插件私有状态文件里（$DSH_HOME/state//），不在任何配置或路由上；npm run doctor 只读状态文件、不碰凭据，Host 没起也能跑（人读 / 机器读两个口径见 docs/SETUP.md §6.1）。

文档

• docs/README.md — 全量文档索引（每篇按「内容 / 何时查」路由；本表只列主文档）
• docs/ARCHITECTURE.md — 架构与数据流
• docs/SETUP.md — 配置字段、改动后重启
• docs/TROUBLESHOOTING.md — 排障入口（按面板界面原文查）
• docs/AUTH.md — 登录 / 重登 / 节流设计
• docs/API.md — 路由与控制台端点
• docs/AGNES-API.md — Agnes 接口全集（控制台额度侧 + 推理侧）
• docs/TESTING.md — 测试体系
• docs/PITFALLS.md — 真实踩坑（61 条；数字由 docs.test.mjs 的 PITFALLS_REFS 与文件内编号钉住）
• CHANGELOG.md — 版本变化

AI 协作会话请先读 AGENTS.md（在仓库里，不在 npm 包里）。人类贡献者先读 SETUP.md 与 ARCHITECTURE.md §2 理解结构与改动代价，改代码前再读 AGENTS.md 的红线与 TESTING.md 的 npm test 门禁。

诚实声明

• 面板显示的是控制台自己的口径，与网页控制台一致；GET /v1/models 只区分权限，不计费也不占推理额度；
• 令牌被拒时面板明确提示重新登录，而不是静默显示旧数据；
• 凭据（账号、access token）只经 DSH 凭据服务保存，密码不落盘；本插件不写任何明文凭据文件或调试日志。

许可证

MIT License（Copyright (c) 2026 eghrhegpe），全文见 LICENSE；第三方依赖与合规说明见 THIRD_PARTY_NOTICES.md。