@bokutake/dsh-connect-qoder 0.0.0-stage → 1.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/PAT.md ADDED
@@ -0,0 +1,191 @@
1
+ # 获取并配置 PAT(Personal Access Token)
2
+
3
+ 本插件用 **PAT** 接入 Qoder。这份文档只讲三件事:PAT 是什么、从哪拿、怎么填进插件。
4
+
5
+ ## 一、PAT 是什么
6
+
7
+ PAT 是 Qoder 官方发给开发者的**个人访问令牌**,形如 `pt-` 开头的一串字符。你可以把它理解成「给外部程序用的一把钥匙」:谁持有它,谁就能以你的身份调用 Qoder 的接口。
8
+
9
+ 它的两个特点决定了本插件的设计:
10
+
11
+ - **你自己签发、自己吊销**:不需要把账号密码交给任何第三方,随时能在设置页删掉。
12
+ - **等价于你的账号权限**:泄露它等于泄露账号,因此不要提交进代码仓库、也不要贴到聊天窗口或 issue 里。
13
+
14
+ 插件拿到 PAT 之后做的事(这也是它**为什么只需要 PAT**的原因):
15
+
16
+ ```text
17
+ PAT ──(一次性)──> Qoder 网关 /jobToken 交换 ──> jobToken
18
+ │
19
+ ↓
20
+ 之后每次请求带签名会话头
21
+ (PAT 此后不再出现)
22
+ ```
23
+
24
+ PAT 只在**进程内**参与这次交换:DSH 的模型客户端(pi-ai)连的是本机的回环端口,真正的 PAT 一直在插件进程里,不进网络请求、不写进会话记录。
25
+
26
+ ## 二、从哪里拿 PAT
27
+
28
+ 两个区域各发一份,**互不通用**:
29
+
30
+ | 区域 | 服务站点 | 发证入口 |
31
+ | --- | --- | --- |
32
+ | 国内版(通义灵码) | `qoder.com.cn` | 登录 [Qoder CN 控制台](https://www.alibabacloud.com/help/zh/lingma/cloud-agents-cn/api-authentication) → **设置 → API 令牌** → 创建令牌 |
33
+ | 国际版 | `qoder.sh` | 登录 Qoder 控制台 → **Settings → Personal Access Tokens** → 创建(见 [Qoder 官方认证文档](https://docs.qoder.com/cloud-agents/api/conventions/authentication)) |
34
+
35
+ 创建时:
36
+
37
+ 1. 给令牌起一个**名字**(只是给你自己看的备注,比如「DSH 笔记本」)。
38
+ 2. 如果页面要求选**权限范围 / 有效期**,按需选择——本插件只用模型推理能力,选默认即可;有有效期的话注意到期后要重新签发。
39
+ 3. 点创建。**令牌通常只完整显示一次**,当场复制保存(形如 `pt-xxxxxxxx`)。
40
+
41
+ > 注意:这里说的是 Qoder **控制台网页版**里的入口,不是桌面客户端的设置页。
42
+
43
+ ## 三、怎么填进插件
44
+
45
+ 插件侧有两条路,二选一(同时配也没问题,会自动去重合并)。
46
+
47
+ ### 方式 A:在设置卡片里粘贴(推荐,可多账号)
48
+
49
+ ```text
50
+ DSH → 插件 → dsh-connect-qoder → 设置卡片
51
+ → 选对应的 tab(国内版 / 国际版)
52
+ → 点「添加 PAT」
53
+ → 在输入框贴入 pt-…(可顺便填一个显示名,会自动带出真实账号名)
54
+ → 提交
55
+ ```
56
+
57
+ 提交时插件会**立刻拿它去 Qoder 网关做一次真实验证**:能换到 jobToken 才算通过,失败会直接拒绝并报错,不会把一个无效令牌存进去。所以「提交后没反应」以外的情况,都说明令牌本身有问题。
58
+
59
+ 卡片里可以放**多个**账号(每区域一个保险库),换号、删号都在卡片内完成。
60
+
61
+ ### 方式 B:环境变量
62
+
63
+ 适合不想让令牌进 DSH 设置文件、或者希望由密钥管理器注入的场景:
64
+
65
+ ```bash
66
+ # 国际版
67
+ export QODER_PERSONAL_ACCESS_TOKEN=pt-xxxxxxxx
68
+
69
+ # 国内版
70
+ export QODERCN_PERSONAL_ACCESS_TOKEN=pt-xxxxxxxx
71
+ ```
72
+
73
+ 放进 shell 配置(`~/.zshrc` 等)或系统的密钥管理工具(1Password / Bitwarden 等的 shell 插件),DSH 启动时会自动读取。
74
+
75
+ ### 优先级
76
+
77
+ ```text
78
+ 设置卡片的 PAT > 环境变量 PAT > 保险库(vault)账号
79
+ ```
80
+
81
+ 三者按账号去重合并,不是互相覆盖。谁在生效可以用命令行看:
82
+
83
+ ```bash
84
+ dsh-connect-qoder status # 各区域当前凭据来源与上游可达性
85
+ dsh-connect-qoder doctor # PAT 是否就位、指纹派生、账号数(不联网)
86
+ ```
87
+
88
+ ## 四、常见问题
89
+
90
+ **提交后报「验证失败」**
91
+ 令牌与区域不匹配(国内版的令牌不能用在国际版 tab),或复制时带上了空格/换行,或已过期。
92
+
93
+ **「凭据被拒」但令牌明明是新生成的(实测记录)**
94
+ 2026-10 实测到一个值得记下来的现象:同一个 CN 令牌,
95
+
96
+ | 请求 | 结果 |
97
+ | --- | --- |
98
+ | `api.qoder.com.cn/api/v1/cloud/agents` | **200** —— 令牌有效、账号正常 |
99
+ | `openapi.qoder.com.cn/sash/api/v2/me/usage` | 401 `TOKEN_EXPIRE / token is not active` |
100
+ | `openapi.qoder.sh/sash/api/v2/me/usage` | 401 `TOKEN_EXPIRE` |
101
+ | `gateway.qoder.com.cn/algo/api/v2/model/list` | 403 `Signature invalid` |
102
+
103
+ 两个结论:
104
+
105
+ 1. **一张令牌有效与否,不能只看单一端点。** `sash` 系列接口回 `TOKEN_EXPIRE`
106
+ 时,令牌本身可能完全正常——它只是不接受 PAT 直连(那条路径预期的是
107
+ 浏览器会话 cookie:`qoder.com.cn/sash/...` 对缺 cookie 的请求回
108
+ `UNAUTHORIZED / missing cookie header`,与令牌无关)。
109
+ 2. **`gateway.*/algo/*` 必须走 COSY 签名**,裸 `Bearer` 一律 `Signature invalid`。
110
+ 本插件正是走「PAT → jobToken → 签名会话」这条路,所以**聊天与模型列表不受
111
+ 上面那条 401 影响**;受影响的只有用量/积分查询。
112
+
113
+ 因此:卡片上积分显示「—」而对话能正常用,属于「积分端点读不到」,不等于
114
+ 「令牌坏了」。判断令牌真实状态应看对话能否发送,或按上表用 Cloud Agents 端点核对。
115
+ (本插件现在的积分查询已改用 jobToken 的 `jt-` 令牌,实测 200;PAT 直连只作兜底。)
116
+
117
+ **模型列表是空的,但令牌看着没问题**
118
+ 未配置 PAT 的区域**不会列出任何模型**——一个请求都发不出去,列出来只会点到就失败。确认「从 Qoder 刷新」执行过。
119
+
120
+ **不想用 PAT 了**
121
+ 把令牌在 Qoder 控制台里删掉即可;本插件侧用 `dsh-connect-qoder logout [--region cn|global]` 清除本地 vault 账号。
122
+
123
+ **能不能像 WorkBuddy 那样直接读本机登录?**
124
+ 不能。WorkBuddy 桌面端把登录态存在固定路径的明文/可解密文件里,插件可以直接扫描复用;Qoder 桌面端把凭据加密后存进系统钥匙串相关的封装文件,且 CLI 侧的 `.auth/user` 只有登录过 Qoder CLI 才会生成(大多数用户不会)。所以 Qoder 这边只有官方 PAT 这一条稳妥路径——所有第三方 Qoder 接入工具都是这么做的。
125
+
126
+ ## 五、Qoder 每日签到(实测协议,2026-10)
127
+
128
+ **参考实现**:https://github.com/L0NE-6/Qoder-Daily (青龙脚本,CN + Global)
129
+ **官方规则**:https://help.aliyun.com/zh/lingma/daily-check-in-100-credits-reward-program-terms
130
+
131
+ ### 协议(CN 实测通过)
132
+
133
+ 拉活动列表(**v1**,且叫 campaigns,不是 checkin):
134
+
135
+ GET {openapi}/sash/api/v1/me/campaigns?forceRefresh=true
136
+ headers:
137
+ authorization: Bearer {jobToken.securityOauthToken} ← jt- 令牌,与用量同一套
138
+ cosy-clienttype: 10
139
+ accept: application/json
140
+ accept-language: zh-CN
141
+ user-agent: Qoder
142
+
143
+ 响应:
144
+
145
+ {"campaigns":[
146
+ {"campaignId":"01a12102-…","actionType":"CLAIM_BENEFIT","claimStatus":"CLAIMED",
147
+ "benefit":{"kind":"CREDITS","amount":100,
148
+ "modelScope":{"modelSeries":{"key":"ALL_MODELS"}},
149
+ "validity":{"mode":"RELATIVE_DAYS","days":30}}},
150
+ {"campaignId":"01a05bbf-…","actionType":"VIEW_DETAILS","claimStatus":"CLAIMED"}
151
+ ]}
152
+
153
+ 领取:
154
+
155
+ POST {openapi}/sash/api/v1/me/campaigns/{campaignId}/claim
156
+ (同 headers + content-type: application/json + origin)
157
+
158
+ 已领取的判定:HTTP 409,或 body.result === "ALREADY_CLAIMED",或 body.replayed === true。
159
+
160
+ ### 关键事实
161
+
162
+ - 活动名里**没有**「签到」二字,所以照着 checkin / signin / reward 猜路径一律 404
163
+ (我实测猜了 13 个全 404)。真正的词是 **campaigns**(活动/权益)。
164
+ - 状态机:`claimStatus` ∈ {CLAIMABLE, CLAIMED};只有 `actionType === "CLAIM_BENEFIT"`
165
+ 且 `CLAIMABLE` 的才可领。
166
+ - 官方刷新时间:**每天 10:00 (UTC+8)** 开窗(阿里云文档写 0 点,桌面端截图显示 10:00
167
+ ——以桌面端为准)。
168
+ - **国际版**还需要设备风控头 `Cosy-MachineToken` / `Cosy-MachineCode` /
169
+ `Cosy-MachineType`;**CN 不需要**(实测多发这些头在 CN 侧是噪音)。
170
+ 三件套由 Qoder 客户端自带的 UMID 组件在本机生成,插件按区域读取:
171
+
172
+ | 区域 | 优先组件路径 |
173
+ |---|---|
174
+ | 国内版 | `/Applications/Qoder CN.app/Contents/Resources/umid/runtime-info` |
175
+ | 国际版 | `/Applications/Qoder.app/Contents/Resources/umid/runtime-info` |
176
+
177
+ 两侧都装了时各自优先自己那个 —— 设备身份与区域绑定,用错一侧会被风控拒绝。
178
+ 组件不存在时签到**如实报错**(「未找到 Qoder 设备风控组件」),而不是把
179
+ 「取不到设备身份」伪装成「今天没有活动」。也可用 `QODER_UMID_PATH` 显式指定。
180
+
181
+ Windows 上按两层找:
182
+
183
+ 1. `%LOCALAPPDATA%\Programs\Qoder[ CN]\resources\umid\runtime-info.exe` —— **默认**安装位置;
184
+ 2. **卸载登记表**(`HKCU\…\Uninstall` → `HKLM\…\Uninstall` → `HKLM\…\WOW6432Node\…`)里
185
+ `DisplayName` 为 `Qoder` / `Qoder CN` 的项,从 `UninstallString`(或 `DisplayIcon`)
186
+ 反推安装目录 —— 安装器允许改目录:装在别的盘(实测 `D:\…\Programs\Qoder`)时第一层
187
+ 整族落空,只有第二层还知道它在哪儿。
188
+
189
+ `QODER_UMID_PATH` 的优先级在两层之上,且**不是唯一来源**:路径失效时会继续往下找。
190
+ 读取结果按 50 分钟在进程内缓存(参考实现同量级),避免每次签到都 fork 进程。
191
+ - 企业版账号不支持该活动(仅个人用户)。
@@ -0,0 +1,109 @@
1
+ # 隐私与脱敏规则(Privacy Rules)
2
+
3
+ > **这一页是硬约束,不是建议。** 本项目是公开发布的 npm 包 + GitHub 仓库,
4
+ > 凡是进了仓库的东西,用户装一次包就落到他的磁盘上,也永远留在 git 历史与
5
+ > npm 的每一份 tarball 里。**发出去就收不回来。**
6
+ >
7
+ > 早期版本的截图里用过真实数据,已经在 1.19.2 统一换成假值。
8
+ > 这份文档是那次教训的产物。
9
+
10
+ ## 0. 一条判据
11
+
12
+ > **假设这段文字 / 这张图明天会被贴到 issue 里、被搜索引擎索引、被不认识你的人读到。
13
+ > 你愿不愿意让别人知道它对应的是你本人、你的钱包、你的这台机器?**
14
+
15
+ 不愿意的,就不能进仓库。没有「反正只是个昵称」这一档——昵称 + 余额 + 到期时刻
16
+ 拼起来足以定位一个真实账户。
17
+
18
+ ## 1. 绝对禁止进入仓库的内容
19
+
20
+ | 类别 | 具体形态 | 为什么 |
21
+ | --- | --- | --- |
22
+ | 凭据 | PAT(`pt-…`)、`access_token` / `refresh_token` / `security_oauth_token`、jobToken、npm `_authToken`、`ghp_…`、私钥 | 直接就是账户控制权 |
23
+ | 凭据指纹 | `pat-<sha256 前 16 位>` 形式的账号 id | 能确认「这把钥匙对应这个人」,且能跨仓库串起来 |
24
+ | 真实账号标识 | 邮箱、手机号、上游昵称(形如 `nick1234…`)、真实显示名 | 直接是个人信息 |
25
+ | 账户财务状态 | 积分余额、套餐档位、到期时刻、账单周期 | 与账号标识合并即构成可定位画像 |
26
+ | 本机路径 | `/Users/<姓名>/…`、`C:\Users\<姓名>\…`,以及用户主目录下的其它绝对路径 | 泄露操作系统用户名与目录结构 |
27
+ | 凭据库键名 | `~/.dsh/.credentials.yaml` 里的 `QODERCN_ACCOUNT_<id>` 之类 | 指向真实凭据条目 |
28
+ | 设备标识 | UMID、machineId、machineToken、序列号、`MachineGuid` | 设备可被唯一识别 |
29
+
30
+ > 注意:**`dingminhua` 与 `@dmh2002/` 这两个是公开身份**(GitHub 仓库地址、npm
31
+ > 包作用域、MIT 版权人),它们必须留在仓库里,脱敏规则不针对它们。要挡的是
32
+ > **它们之外**的账号数据。
33
+
34
+ ## 2. 截图规则(本项目最容易出事的地方)
35
+
36
+ 截图必须遵守以下四条,缺一条就算没过:
37
+
38
+ 1. **先造数据,再截图。** 不要把真机界面遮一下发上来——遮的那一下常常遮不干净
39
+ (见下条)。用 `scripts/*.preview.tsx` 那套假数据渲染,或者临时把账号名改成
40
+ `acct-demo`、余额改成整数。
41
+ 2. **遮挡必须是不透明的实心块或直接替换成假值。** **模糊 / 马赛克 / 半透明色块都不算**:
42
+ 模糊保留了字符宽度与字距,马赛克保留了亮暗分布,都能反推出「几个字、大概什么形状」;
43
+ 本项目 0.3.0 那两张 README 图用的就是模糊遮罩,1.19.2 一并换掉了。
44
+ 3. **账号名、余额、到期时刻三者同框时,三项都要换成假值。** 只脱名字而把余额与
45
+ 到期时刻留着,等于给出一枚「可以对着时间线比对」的指纹——这正是 1.19.2 第一版
46
+ 修复的失手处:名字换了、数字原样留着,被独立审查当场判为不合格。
47
+ 余额与到期日的假值也要**看得出是假的**(`888`、`01/01/2027`),不要选一个
48
+ 碰巧像真的数字。
49
+ 4. **截图前把窗口标题、侧边栏、浏览器标签一起看一遍**——它们常常带着另一个
50
+ 账号的名字。
51
+
52
+ **新增 / 重拍截图后必须做的事**:看一眼 `docs/assets/` 的实际像素,不要只看
53
+ Markdown 里的 alt 文字。alt 是写给读者的,不是写给你自己核对的。
54
+
55
+ ## 3. 文字规则
56
+
57
+ - 记录「用户实拍」的现象时,用 `account-a` / `account-b` / `account-c` 代替真实昵称,
58
+ 用 `account-a@example.com` 代替真实邮箱。**保留现象,去掉身份**——「第 1 位的号
59
+ 已用尽却被排在最前」这句话本身是有效信息,只有名字需要换。
60
+ - 代码注释同样适用。`src/` 的注释会被打进 `lib/`,随 npm 包分发,等于公开。
61
+ - CHANGELOG 里的历史条目**不回改语义**,只做标识符替换;不要因为脱敏把当时的
62
+ 技术结论改掉。
63
+ - 日志、错误消息、`doctor` 输出已经统一走 `redactUpstreamText`(`src/probe.ts`)
64
+ 脱敏 `token=…` 一类的参数;新增日志路径时沿用同一个函数,不要自己拼字符串。
65
+
66
+ ## 4. 提交前自检(30 秒)
67
+
68
+ ```bash
69
+ # 1) 快速自查。**它不是 `tests/privacy.spec.ts` 的镜像**:下面这条只管
70
+ # 最常用的几类,护栏里还有私钥、令牌本体、Windows 路径等它没写的规则。
71
+ # 两者都要跑——先看这个,再跑第 3 步。
72
+ # 占位值(pat-aaaa… / pat-deadbeef… / pat-0123456789abcdef)被排除在外,
73
+ # 否则输出会被测试夹具淹没,而「看不完的输出」等于没人看。
74
+ grep -rnE 'nick[0-9]{4,}|@[A-Za-z0-9.-]+\.[a-z]{2,}|pat-[0-9a-f]{12,}|/Users/[A-Za-z0-9._-]+|/home/[A-Za-z0-9._-]+|(?<!\d)1[3-9][0-9]{9}(?!\d)|"?(machineId|machineToken|machineType)"?\s*[:=]' \
75
+ --include='*.md' --include='*.ts' --include='*.tsx' --include='*.mjs' --include='*.json' \
76
+ --include='*.yml' --include='*.css' --include='*.reg' . \
77
+ | grep -v node_modules | grep -v example.com \
78
+ | grep -viE 'pat-(0{6,}|a{6,}|b{6,}|c{6,}|d{6,}|e{6,}|f{6,}|deadbeef|cafebabe|deadc0de|feedface|0123456789abcdef|fedcba9876543210)'
79
+
80
+ # 2) 本次改动的图片,逐张打开看一眼(自动化查不了内容)
81
+ git diff --stat -- docs/assets
82
+
83
+ # 3) 自动化护栏(CI 也会跑,且是单独一步)
84
+ pnpm exec vitest run tests/privacy.spec.ts
85
+ ```
86
+
87
+ > **护栏的能力边界,写清楚免得下次误信:**
88
+ > - 它扫的是**已知坏值的黑名单**,不是「未知好值的白名单」。新人名、新邮箱域、
89
+ > 新昵称形态一律漏——这次事故的主体(一个不是邮箱也不像昵称的显示名)它就抓不到。
90
+ > - 它**读不了图片内容**。截图只能靠人打开看。
91
+ > - **它测不了「财务数值」这一整类。** 试过一版「余额…数字…到期」并列的规则,
92
+ > 而测试夹具里 `{ credits: 100, nearestExpiryMs: … }` 一屏十几条,满屏误报,
93
+ > 逼得人加 `allow` 白名单,最后变成「谁改测试谁顺手放宽」——比没有更糟,已撤回。
94
+ > 这一类**只能靠人**:改图时同时改正文里引用那张图的数字(见 §2 第 3 条)。
95
+ > - 护栏会扫 `lib/`(它是 gitignore 的构建产物,却随包发布);但干净 clone 上
96
+ > 还没构建时那部分为空,所以 **CI 把这一步排在 Build 之后**,发布前也必须先 `pnpm build`。
97
+ > - 所以 §2 的第 1 条(先造数据再截图)才是治本的;护栏只防回退。
98
+
99
+ ## 5. 已经泄露了怎么办
100
+
101
+ 1. **先修当前 HEAD**:换图、替换标识符、`pnpm build`(让 `lib/` 里的注释跟着更新)。
102
+ 2. **再判断要不要动历史**:只要旧 commit 还在,`git show <sha>:<path>` 就还能取出旧图。
103
+ 重写历史会改掉所有 commit hash、需要 force push、让所有 fork 失联,**不可逆**,
104
+ 必须维护者明确同意后才做;默认只修当前版本。
105
+ 3. **已发布的 npm 版本撤不回来**:`npm unpublish` 只对 72 小时内、且没被依赖的版本
106
+ 生效。可行的是 `npm deprecate <pkg>@<ver> "含有已泄露的截图,请升级到 X.Y.Z"` +
107
+ 发一个修好的新版本。
108
+ 4. **在 CHANGELOG 里写清楚**:哪一版漏了什么、修在哪一版。别悄悄换图——下一个
109
+ 维护者需要知道这张图为什么长得跟以前不一样。
@@ -0,0 +1,293 @@
1
+ # 活动优惠徽标:取证与判定
2
+
3
+ 模型行上那枚「错峰 4 折」小胶囊。一句话:**上游在模型目录里就给了这枚徽标的文案、
4
+ 时段和规则,插件只负责「此刻该不该画」和「画在哪」。**
5
+
6
+ ## 1. 数据在哪:同一次目录请求,不新增任何请求
7
+
8
+ `/algo/api/v2/model/list?Encode=1` 的每个模型行自带一个 `promotion` 对象。插件本来就
9
+ 为了取目录读这份文档,所以这次改动**没有新增一次上游请求**,只是多了一个解析器
10
+ (`src/promo.ts`)和一个渲染时刻的判定。
11
+
12
+ 2026-10-21 16:2x 本机实测(真凭据、只读 GET、不消耗积分):
13
+
14
+ | 区域 | 主机 | 去重后模型数 | 带 `promotion` 的行 |
15
+ | --- | --- | --- | --- |
16
+ | 国内 | `https://gateway.qoder.com.cn` | 11 | 2(`qmodel_38max`、`qmodel`) |
17
+ | 国际(全部分组) | `https://api1.qoder.sh` | 22 | 5(`ultimate`、`quest-ultimate`、`experts-ultimate`、`qmodel_38max`、`qmodel`) |
18
+ | 国际(插件读的 `chat` 分组) | 同上 | 13 | 3(`ultimate`、`qmodel_38max`、`qmodel`) |
19
+
20
+ 两个区域是**同一套 schema**,只有时区和文案不同:国内 `Asia/Shanghai`,「错峰 4 折」;
21
+ 国际 `Asia/Singapore`,「错峰2折」/`Off-Peak 80% off`。注意上游自己写的也不统一——国内
22
+ `qmodel_38max` 是「错峰 4 折」(有空格),`qmodel` 是「错峰4折」(没空格)。插件原样
23
+ 显示,不做「统一格式」。
24
+
25
+ ## 2. 逐字抓包(国内 `qmodel_38max`)
26
+
27
+ ```json
28
+ "promotion": {
29
+ "active": false,
30
+ "badge": { "en": "Off-Peak 60% off", "zh": "错峰 4 折" },
31
+ "description": {
32
+ "en": "Off-Peak 60% off (10 PM-8 AM UTC+8)",
33
+ "zh": "错峰时段4折优惠(10 PM-8 AM UTC+8)"
34
+ },
35
+ "timezone": "Asia/Shanghai",
36
+ "rule_id": "idle_time_model_credit_discount",
37
+ "discount_factor": 0.4,
38
+ "before_promotion_price_factor": 0.5,
39
+ "link_url": {
40
+ "zh": "https://docs.qoder.cn/product-overview/qwen-3-7-series-model-staggering-discount"
41
+ },
42
+ "window_start": "22:00",
43
+ "window_end": "08:00"
44
+ }
45
+ ```
46
+
47
+ 国际区同一条规则换成了 `discount_factor: 0.2` / `before_promotion_price_factor: 2`,
48
+ `timezone: "Asia/Singapore"`,`link_url` 指向 `https://docs.qoder.com/events/offpeakrate`。
49
+
50
+ 字段三组:**给人看的**(`badge`、`description`)、**规则**(`active`、`rule_id`、
51
+ `discount_factor`、`window_start/end`、`timezone`)、**跳转**(`link_url`)。
52
+
53
+ ## 3. 判定规则(`src/promo.ts`)
54
+
55
+ 1. **只认有文案的规则。** `badge.zh` 与 `badge.en` 都没有 → 一律丢弃。没有可显示的话,
56
+ 插件没有可画的东西,也不自己编。
57
+ 2. **有窗口就看窗口,没有窗口才看 `active`。** 有 `window_start/end` 时,结论只由
58
+ 「此刻在不在窗口内」决定(渲染时刻现算);没声明窗口时才退回上游的 `active`。
59
+ 为什么不是「两者都成立」(理由见 §3.1)。
60
+ 3. **没有窗口声明时只信 `active`。** 上游哪天给了个不带时段的常驻活动,这条路径直接可用;
61
+ `active` 为 false 时整枚不画——没有窗口就没有「几点生效」可说。
62
+ 4. **时段按上游声明的时区算**(`timezone`),不是浏览器时区:`22:00–08:00` 说的是那条
63
+ 记录的时区里的 22:00。起点含、终点不含;跨零点命中 `[22:00, 24:00) ∪ [0, 08:00)`;
64
+ 终点允许写 `24:00`(= 当天结束);`start === end` 视为全天;**声明了窗口但读不懂**
65
+ (越界、只给一端、`HH:MM` 以外的写法)一律不画——不当作全天,也不退回去信 `active`。
66
+ 5. **一个模型只画一枚徽标**,落在模型名**旁边**而不是名字里面——名字是省略号截断的,
67
+ 放进去会被一起裁掉。与倍率、free 标记、测试结论并列,顺序是「倍率 → 徽标」。
68
+ 窗口外的那枚灰显(§3.3),位置与文案不变。
69
+ 6. **文案、悬停都只说上游的话。** 胶囊文字取 `badge.zh`(中文界面)/ `badge.en`;
70
+ 悬停取 `description`,再补上「时段 + 时区」与 `link_url` 原文。插件不翻译、不改写、
71
+ **不从 `discount_factor` 反推「4 折」这类文案**(`rule_id` 因此仍不保留)。
72
+ 但折扣**数字本身**现在保留了——它不进文案,只给「活动实际倍率」用,见 §3.4。
73
+
74
+ ### 3.1 为什么「有窗口时窗口说了算」
75
+
76
+ `active` 是上游**在取目录那一刻**算出来的,而目录是 DSH 进程启动时取的一份内存快照,
77
+ 之后只有点「刷新模型」才会换。把它当成必过的门,会有一个方向永远错:
78
+
79
+ - **窗口开了而进程没重启**:早上启动的进程拿着 07:00 的 `active: true`,到 22:00 窗口
80
+ 重新开启时它仍是同一份快照——徽标该出现却不会出现,对一个整天开着 DSH 的用户,这个
81
+ 功能等于不存在。
82
+ - **窗口关了而 `active` 还是 true**(昨夜取的快照):这方向窗口能纠正。
83
+
84
+ 窗口不是插件的猜测,它是**上游自己声明的时段**(`window_start/end` + `timezone`),
85
+ 按那一刻的时钟重算,不会因为快照旧而说错话。所以:有窗口时它是唯一依据,`active`
86
+ 只在没有窗口可算时兜底。
87
+
88
+ 代价写在 §7:上游若**提前结束**一个活动,插件在窗口内仍会画到下次刷新为止。这比反过来
89
+ (活动开着却整天不显示)轻,而且用户可以点「刷新模型」立刻纠正。
90
+
91
+ ### 3.2 为什么判定必须在渲染时刻
92
+
93
+ `promotion` 会随 `lastCatalog` 一起落盘。**若在解析时就挑定「画 / 不画」,夜里读到的
94
+ 目录会把它冻结到第二天早上**:23:00 拉到的快照判定为「在窗口内」,到早上 9:00 还挂着
95
+ 这枚过期的「错峰 4 折」。
96
+
97
+ 所以解析层只保留**规则**(`QoderPromotion`,不带任何「已判定」的痕迹),卡片每次渲染
98
+ 拿 `new Date()` 现算(`promoDisplayAt` / `promoLiveAt`)。这与 workbuddy
99
+ (`selectPromoBadge`)、Trae(`selectTraePromoBadge`)三处是同一个取舍。
100
+
101
+ ### 3.3 窗口外画成灰的,而不是不画
102
+
103
+ 2026-10-23 用户实拍:14:5x 打开卡片,`Qwen3.8-Max` 行上什么都没有——而它的规则、文案、
104
+ 窗口在目录里全都齐(实探:`qmodel_38max`,`22:00–08:00 Asia/Shanghai`,`active: false`)。
105
+ 当时的实现只在「此刻成立」时画,于是**白天看不见这件事本身成了信息缺口**:一个只在
106
+ 晚上用 DSH 的人能看到折扣,一个白天打开卡片的人完全不知道有这回事。
107
+
108
+ 现在的三态(`promoDisplayAt`):
109
+
110
+ | 结论 | 条件 | 画法 |
111
+ | --- | --- | --- |
112
+ | `live` | 此刻在窗口内(或没有窗口而 `active` 为 true) | 实心胶囊,品牌色 |
113
+ | `pending` | 声明了**读得懂**的窗口,但此刻不在窗口内 | 灰显胶囊:tertiary 灰 + 中性底 + **虚线**描边 |
114
+ | `none` | 没有规则 / 窗口读不懂 / 没有窗口而 `active` 为 false | 不画 |
115
+
116
+ 两处刻意的选择:
117
+
118
+ - **灰显不是只降透明度。** 两种状态挂着同一句上游文案(「错峰 4 折」),只靠颜色深浅
119
+ 区分会被读成「现在就在打折」。所以同时换掉颜色、底色与描边**形状**——虚线是形状
120
+ 差异,不依赖颜色,色觉障碍与高对比度主题下仍然成立。
121
+ - **悬停必须说清状态。** `pending` 的 title 前置一句 `row.promoPending`(「当前未生效,
122
+ 22:00 起生效」),再接上游的 `description` / 时段 / 链接。信息一条不少,只多一句状态。
123
+
124
+ `none` 里那两条不能进 `pending`:读不懂的窗口给不出「几点生效」(说一个猜的时间比不说
125
+ 更糟),没有窗口的常驻活动同理。
126
+
127
+ ### 3.4 活动期的「显示倍率」(issue #41)
128
+
129
+ 徽标之外,活动还有第二个用户可见的后果:**实际计费倍率变了**。上游 `promotion` 里
130
+ `discount_factor`(折后系数,如 `0.4`)与 `before_promotion_price_factor`(折前价,如
131
+ `0.5`)给出了这条规则的数字面。实测 `qmodel_38max` 在窗口内的实际价 `0.20x` =
132
+ 基准价 `0.5 × 0.4`——与 Qoder 官方菜单对得上。但插件此前只显示 `price_factor` 基准价,
133
+ 于是一个「限时免费」(`discount_factor: 0`)的模型,官方写 `x0.00`、插件写 `0.1x`,
134
+ 两个客户端的数字对不上,用户以为计费出错(issue #41)。
135
+
136
+ 修法是一条**只在 UI 显示**的旁路,与徽标共用同一份规则、同一套判定:
137
+
138
+ - `QoderPromotion` 保留 `discountFactor` / `beforePromotionPriceFactor` 两个可选数字
139
+ (`rule_id` 仍丢,插件不给它语义;文案仍不反推数字——「4 折」那句话永远是上游的原话)。
140
+ - `displayMultiplierOf(source, now)`:仅当此刻 `promoDisplayAt === 'live'` 且有可信
141
+ `discountFactor`(有限数、`0 ≤ x ≤ 1`)时,返回「当前基准价 × 折扣系数」(两位小数
142
+ 归一);否则原样返回基准价。它和徽标判定一样是**渲染时刻的纯函数**,不落盘——
143
+ 理由与 §3.2 相同(窗口绑死的值写进 `lastCatalog` 会冻结到第二天早上)。
144
+ - 三个展示面都接它:卡片模型行的 `(N.NNx)`、DSH 内置模型选择器的 `· xN.NN`
145
+ (`modelDisplayName` 增加可选 `now` 参数)、账号池「测试用模型」下拉。倍率与基准价
146
+ 不同时,标签悬停补一句插件写的解释「活动价,基准价 x0.10」(`row.ratePromoHint`),
147
+ 免得用户拿活动价和别处对账。
148
+ - **计费路径一个字符没动**:`priceFactor` / `creditMultiplier` 仍写基准价并照旧落盘;
149
+ `poolModelOf` 把 `promotion` 放在 `creditMultiplier` 之外的独立字段,绝不把活动期的
150
+ `0` 折叠进「免费即 0」判据——否则一个「基准收费、活动免费」的模型会被账号池当成
151
+ 免费模型反复探测,静默烧掉真积分。pi-ai 请求与目标模型 id 也一律按模型 key,不读
152
+ 这个显示倍率。
153
+ - **不拿 `before_promotion_price_factor` 当校验门**:限时免费这类活动里它可能与目录
154
+ 当前 `price_factor` 对不上,用它做等值校验恰好会把该显示的 `x0.00` 压回基准价。
155
+ 折算只取目录当前基准价;折前快照只作记录、供日后复核。
156
+
157
+ ## 4. 与另两个插件的能力对照
158
+
159
+ | 能力 | workbuddy PR #91 | Trae PR #44 | Qoder(本 PR) |
160
+ | --- | --- | --- | --- |
161
+ | 文案来源 | 上游 `badge.label` | 无文案,插件自造「闲时」 | 上游 `badge.zh/en`,原样 |
162
+ | 颜色 | 上游 `badge.color` | 插件自选三色 | 插件自选(上游没给) |
163
+ | 绝对生命周期 | `validFrom/validUntil` | 无 | 无(只有每日时段) |
164
+ | 每日时段 | `schedule.daily`(具名时区) | `off_peak.time_windows`(周几+分钟) | `window_start/end` + `timezone` |
165
+ | 多枚候选 / 优先级 | 有(`priority`、`activeOnly`) | 无(一对一) | 无(一对一) |
166
+ | 服务端「此刻生效」标志 | 无 | `current.discount_type` | `active` |
167
+ | 额外请求 / 换客户端身份 | 需要(`/v3/config` 按通道下发) | 不需要 | **不需要** |
168
+
169
+ Qoder 是三者里唯一「文案自带 + 不需要换身份 + 不需要额外请求」的:最省事,也最贴近
170
+ 「徽标只说上游的话」。
171
+
172
+ ## 5. 实机复核
173
+
174
+ `scripts/probe-promo.mjs` 用真凭据、cosy 签名(与客户端同一条路径)读一次目录,然后跑
175
+ **插件的解析与判定**(`parseUpstreamModel` → `parseQoderPromotion` → `promoLiveAt`):
176
+
177
+ ```
178
+ $ node --experimental-transform-types scripts/probe-promo.mjs --shifts
179
+ account=QODERCN_ACCOUNT_EXAMPLE region=cn uid=<uid 前 6 位>
180
+ GET /algo/api/v2/model/list?Encode=1 → HTTP 200 / 55477 bytes
181
+ chat rows: 11
182
+ parsed models: 11 carrying a rule: 2
183
+ - qmodel_38max active=false 22:00–08:00 Asia/Shanghai badge[zh]="错峰 4 折"
184
+ - qmodel active=false 22:00–08:00 Asia/Shanghai badge[zh]="错峰4折"
185
+
186
+ == badges now (2026-10-21T09:23:24.783Z) ==
187
+ (none)
188
+ +6h (15:23Z = 23:23 Asia/Shanghai): qmodel_38max「错峰 4 折」, qmodel「错峰4折」
189
+ +12h (21:23Z = 05:23 次日): qmodel_38max「错峰 4 折」, qmodel「错峰4折」
190
+ +24h (09:23Z = 17:23 次日): (none)
191
+ +36h (21:23Z = 05:23 第三天): qmodel_38max「错峰 4 折」, qmodel「错峰4折」
192
+ ```
193
+
194
+ 两条规则都被正确读出(时段、时区、中文文案)。此刻 17:23(窗口外)**一枚都不画**,
195
+ 把时钟推进窗口(+6h = 23:23)两枚都出现,推回白天(+24h)又消失——**同一份解析结果**,
196
+ 结论只随「现在几点」变,这正是 §3.2 要的。注意 `active` 一直是 `false`:它停在取目录
197
+ 那一刻,插件不拿它去否决窗口(§3.1),窗口逻辑由 `tests/promo.spec.ts` 用固定时刻锁住。
198
+
199
+ ### 5.1 窗口内真机复跑(2026-10-21 22:2x)
200
+
201
+ 上面的时钟平移是模拟。窗口真开之后又跑了一次**真实时钟**的复核,两件事同时得到确认:
202
+
203
+ 1. **`active` 确实按当前时刻算,且窗口内会翻真。** 22:2x 宿主的 `/usage` 投影里,
204
+ `qmodel_38max` 与 `qmodel` 的 `promotion.active` 都已是 `true`(16:2x 同一批规则是
205
+ `false`)。所以 §3.1 的担忧不是「上游永远不给 true」,而是**这个 true 只在取目录那
206
+ 一刻有效**——白天取到的 `false` 不会因为到了夜里就自己变。
207
+ 2. **两枚徽标在真实时钟下真的画出来了。** 用宿主 `/usage` 的真实返回喂卡片组件渲染
208
+ (数据、组件、CSS 都是生产代码),`Qwen3.8-Max (0.20x)` 旁出现「错峰 4 折」、
209
+ `Qwen3.7-Plus (0.10x)` 旁出现「错峰4折」,位置在名字之外、倍率之后。截图存为
210
+ `docs/assets/dsh-connect-qoder-promo-badge.png`(README 双语引用、`screenshots.json`
211
+ 登记)。
212
+
213
+ > 这张图是**窗口内真机数据 + 真实组件渲染**截的,不是摆拍:`promotion` 取自运行中宿主的
214
+ > `/usage`,启用状态、倍率、上下文都来自同一份真实目录。
215
+
216
+ 顺带确认:`quest-ultimate` / `experts-ultimate` 只出现在 `quest` / `experts` 分组里,
217
+ 而插件目录只读 `chat`,所以国际区实际能画的是 `chat` 分组里的三条:`ultimate`、
218
+ `qmodel_38max`、`qmodel`(同上命令换成 `QODER_ACCOUNT_EXAMPLE` 即可复核)。
219
+
220
+ ## 6. 落地位置
221
+
222
+ | 位置 | 作用 |
223
+ | --- | --- |
224
+ | `src/promo.ts` `parseQoderPromotion` | 上游 snake_case → `QoderPromotion` |
225
+ | `src/promo.ts` `readPromotion` | 落盘形状 → `QoderPromotion`(读回不另写一套解析) |
226
+ | `src/promo.ts` `clockMinute` / `parsePromoWindow` | `HH:MM` → 分钟数(终点接受 `24:00`) |
227
+ | `src/promo.ts` `promoWithinWindow` | 按上游时区判时段(跨零点、起点含终点不含) |
228
+ | `src/promo.ts` `promoLiveAt` | 渲染时刻的「此刻画不画」 |
229
+ | `src/promo.ts` `displayMultiplierOf` | 渲染时刻的「活动实际倍率」(issue #41;只用于 UI,不落盘、不进计费) |
230
+ | `src/client/promo-badge.ts` `rateHint` | 活动价与基准价不同时的「基准价 x0.10」悬停解释 |
231
+ | `src/catalog.ts` `QoderModelInfo.promotion` | 目录条目带规则(`parseUpstreamModel` 里解析) |
232
+ | `src/catalog.ts` `modelDisplayName` | DSH 内置选择器名 `· xN.NN`:显示倍率走 `displayMultiplierOf` |
233
+ | `src/index.ts` `modelConfig.promotion` | `lastCatalog` 持久化 schema(`z.any<QoderPromotion>()`) |
234
+ | `src/status-paths.ts` `QoderWebModel` / `QoderPersistedModel` | 投影给卡片的模型行类型 |
235
+ | `src/web-status.ts` `webModelOf` | 投影时原样带出(对象展开,运行期无需改) |
236
+ | `src/client/promo-badge.ts` `hostLanguage` / `promoBadgeLabel` / `promoBadgeTooltip` | 选中文/英文文案、拼悬停 |
237
+ | `src/client/QoderCard.tsx` `renderModels` | 模型行渲染(名旁一枚胶囊) |
238
+ | `src/model-badge.ts` `modelBadgeOf` | 选择器胶囊的**数据侧**:此刻该挂哪一枚(`live` 才挂)、文案表、16 grapheme 上限 |
239
+ | `src/adapter.ts` `listModels` | 把胶囊挂进 `LlmModelInfo.badge`(展开写法,0.1.x 也能编译) |
240
+ | `src/client/QoderModelLabel.tsx` `createQoderModelLabel` | 选择器里的同一枚胶囊(issue #12;工厂按 fiber 捕获槽位表,非本插件 provider 委托回账本下一位) |
241
+ | `src/client/host-badge.tsx` `ForeignModelLabel` | 别家 provider 的行:名字 + 该模型自带的 `model.badge`(trigger 在前、菜单在后) |
242
+ | `src/client/index.tsx` `registerModelLabel` | `conversation.input.model.label` 注册(`priority: -101`;single 槽同优先级会抛,升序只渲染最低者 ⇒ 实测赢家是 workbuddy 的 `-105`,本组件不渲染,胶囊靠 `listModels()` 的数据通道) |
243
+ | `src/client/styles.ts` `.dsm-qoder-model-promo` / `.dsm-qoder-model-label-host-badge` | 本插件自己的胶囊 / 别家行上复现宿主 `Tag` 的几何 |
244
+ | `scripts/probe-promo.mjs` | 真机只读探针(解析 + 判定 + 时钟平移) |
245
+
246
+ ## 7. 已知限制
247
+
248
+ - **`link_url` 不可点**:胶囊只是提示。卡片里放一个可点外链,会把「用户以为自己要
249
+ 去开通什么」变成一次误点,这一版不做。
250
+ - **没有颜色**:上游只给文案,所以配色是插件自选的品牌蓝(与倍率标签同一色系)。
251
+ - **上游提前结束活动时,徽标会多挂一会儿**:见 §3.1。有窗口时窗口说了算,所以活动被
252
+ 临时取消 / 提前收尾时,插件要等到下次刷新目录(点「刷新模型」或重启)才知道。反向
253
+ 的错(活动开着却整天不显示)更糟,所以选这一边。
254
+ - **不判断账号资格**:`active` 里可能混着「你的账号不符合资格」这一层意思,但走窗口
255
+ 分支后插件看不到它。§5.1 在窗口内实测到的 `true` 说明至少这批账号是符合的;若上游
256
+ 将来只给「符合资格才 active」的常驻活动(没有窗口),那条路径仍然读 `active`,是对的。
257
+ - **分组里看不到的活动**:`quest` / `experts` 分组的模型不进入插件目录,它们的徽标
258
+ 自然也不会出现。这是目录范围的既有事实,不是本功能的选择。
259
+ - **到点变化最多慢一拍**:卡片靠自动刷新轮询(`pollMinutes` 配置,默认 5 分钟;
260
+ 1.22.0 之前是写死的 60 秒)触发重渲染,判定也在
261
+ 那次渲染里重算,所以 22:00 开启、08:00 结束最迟各差一分钟。不另加定时器:为一个
262
+ 提示性胶囊多挂一个每秒的计时器不值得。
263
+ - **选择器里的数据可能比卡片旧至多一分钟**:标签组件读 `detail=fast` 文档(不触发
264
+ 上游重读,只答本地已有状态),行数据按区域共享缓存(同一个 `pollMinutes` 节奏);窗口边界的翻面靠
265
+ 共享分钟时器重读时钟,不依赖新数据到达。徽标本身仍是渲染时刻现算(与卡片同规)。
266
+ - **选择器里的胶囊是目录数据,不是实时状态**:`LlmModelInfo.badge` 随模型目录一起刷新,
267
+ 所以窗口关掉之后那枚胶囊会挂到下一次目录刷新为止(卡片与本插件自己的行不受影响,
268
+ 它们按分钟重算)。要做到分钟级准确得在每次翻面时发 `llm/models-updated`,而宿主收到
269
+ 它会对**每个模型**调一次 `resolveModelInfo()` —— 代价不成比例。文案上限是 16 个
270
+ grapheme、超了整枚不画(不截断),理由见 `src/model-badge.ts` 文件头。
271
+ - **single 槽的跨插件耦合**:`conversation.input.model.label` 只渲染第一条注册。
272
+ 实测优先级 workbuddy `-105` / trae `-102` / 本插件 `-101`:**赢家是 workbuddy**,
273
+ 本插件注册成功但从不渲染,所以「委托」只在它真的赢了那格时才有意义。
274
+ 一旦赢下,就必须把非本插件的 provider **委托**回账本里的下一位
275
+ (workbuddy 的标签),否则对方的倍率后缀与忙闲图标会一起消失。**委托不出去时**
276
+ 的退路是「名字 + 该模型自带的 `model.badge`」(`src/client/host-badge.tsx`),
277
+ 不再是裸名字——0.2.2 宿主的 fallback 就是这个形状,只画名字等于把别家挂在目录里的
278
+ 胶囊一起抹掉。若对方将来也开始委托,理论上存在互委托环 —— 宿主的错误边界会把
279
+ 抛错的 entry 一次性弃权(下一帧换幸存者渲染),不会死循环。
280
+ - **委托必须带上「对方自己命名空间的 `t`」**(issue #23 的教训,此处此前写错过):
281
+ 这段曾断言「当前生态(workbuddy、1017 参考实现)都是终点型组件」,**这条断言是
282
+ 错的**。宿主内置的 `DeepSeekModelLabel`(`locale: deepseek-model-label-1017`)
283
+ 会**无条件**调用 `t("badge.label")`;它平时正常,是因为宿主框架按它注册时声明的
284
+ `locale` 把 `t` 注进了 kit —— 而我们绕过框架直接 `jsx(Other, …)` 时没有这个机会。
285
+ 结果:`TypeError: t is not a function`,宿主边界把**整片** label 槽弃权,触发按钮 /
286
+ 菜单当前值 / 每个列表行一起变成裸名字,用户侧零信号。
287
+ 现在的做法:按 `entry.locale` 用 `ctx.locale.bind(ns)` 替对方绑一个 `t`;绑定不出来
288
+ (没有 locale 面 / 命名空间未注册)就**不委托**、落回裸名字。**不要**转发我们自己的
289
+ `t`——那会把 `settings.qoder` 的字典当成对方的字典用,对方的 key 查不到就回落成
290
+ 字面键名画在界面上。
291
+ 一般化判据:**只要同槽存在任何声明了 `locale` 的组件,无条件委托就必崩**,与是哪家
292
+ 插件无关。
293
+ - **不 bump 版本、不改 `CHANGELOG.md`**:按 `RELEASING.md` §4,那是发版时维护者的动作。