cortico-world-workbuddy 0.1.7 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,219 @@
 # 更新日志
 
+## 0.3.4
+
+按复核结论做减法：移除反复「假开启」的「中转站优先」功能，只保留可确认的事实。
+
+### 删掉的功能
+
+- **「中转站优先」整体移除**：详情页页签与复选框、`worlds.workbuddy.prefer` 配置、
+  `priority` 面板方法（`state` / `set` / `process`）、环境提示词里的「每轮先 `wb_chat`」强制规则、
+  第三盏「中转站优先」灯，以及主进程退出时自动熄灯的逻辑全部删除。`wb_*` 工具改为按需调用：
+  Coo 在用户点名 WorkBuddy 或明显更合适时才调用，不再每轮强制消耗积分。
+- **`storage: [{ key: 'workbuddy-catalog' }]` 声明删除**：宿主不再为本扩展生成空的「数据清理」页签。
+- **死代码**：`world.js` 的 `canRelay`、未使用的 `dailyWindowText` / `DEFAULT_SAFE_MODEL` /
+  `SAFE_MODEL_IDS` 导入，`wbproc.js` 的 `describeProc`，`upstream.js` 里永远为空的
+  `X-User-Id` / `X-Domain` 请求头，一并删除。
+
+### 修正
+
+- **主进程状态改为只读**：放在「模型目录」面板顶部（6 秒轮询，状态翻转才推送），不再参与任何开关。
+- **优惠状态判定**：`wb_list_models` 的「生效中 / 即将生效」改用 `promoActiveAt()`，
+  只有徽标、不改价的促销不再被误标成「即将生效」。
+- **环境提示词收敛**：倍率说明改成「模型自身价格 + 本桥接此刻能核实的限时改价（含免费窗口）」，
+  并明确「只挂徽标的优惠可能不改价」；`{{workbuddy.priority}}` 变量与其段落删除。
+- 契约与 UI 验证同步更新：断言没有 `priority` 面板、只有两盏灯、无 `storage`、配置无 `prefer`；
+  UI 脚本改为断言页签不含「是否启用 WorkBuddy」与「数据清理」。
+
+## 0.3.3
+
+按 0.3.2 审查结果修复现有功能，不新增模型、面板或上游能力。
+
+- **折扣时间**：纯日期 `validFrom` / `validUntil` 按 `schedule.timezone` 的当地午夜解释，
+  `validUntil` 包含所写日期的整日；`daily` 省略时区时默认 `Asia/Shanghai`，非法时区仍回退 UTC。
+- **用量准确性**：分段 SSE `usage` 改为逐字段合并，末帧只有 `credit` 时不再丢 token；
+  未回传积分与明确 0 积分分开统计，面板以 `+ ?` 标出未知缺口；账本补记折扣前倍率，
+  并在响应完成时取倍率，避免跨折扣窗口写旧值。
+- **只做减法**：删除未接线的 `usageState(days)`、`spanDays` / `windowDays`；按模型表固定为
+  近 30 天并明确标注，与概览同口径。
+- **开关就绪**：环境提示词与第三盏灯同时检查主进程、登录态和已选模型，模型为空时不再假开启。
+- **卸载清理**：新增显式 `scripts/clean-workbuddy.mjs --check | --clean`，只清本扩展的配置块、
+  三份数据文件与 `.env` 的 `accessToken` 行。普通 `stop()` / 重启不删数据；宿主界面卸载后
+  执行该脚本即可无残留，其他配置和密钥不受影响。
+- 文案只称“本机已登录的 WorkBuddy 客户端”，删除多余的区域版本区分。
+
+## 0.3.2
+
+只桥接本机已登录的 WorkBuddy 桌面端，不再提供区域切换；同时把「用量」面板对齐宿主的
+「用量与成本」口径。仍然只在本机验证，未推送 / 未发布。
+
+### 删掉的功能
+
+- **区域（region）配置整体移除**：`worlds.workbuddy.region`、`WB_REGION_BASE`、区域枚举与
+  对应的上游 / 计费域切换全部删除。扩展现在固定走
+  `copilot.tencent.com`（目录 / 对话）与 `www.codebuddy.cn`（积分）；自定义 `baseUrl` 仍可用，
+  它同时替换这两个域。README、SECURITY、CHANGELOG、`describe.json`、环境提示词里的相关文案同步删除。
+- 环境提示词不再输出 `workbuddy.region` 变量；`catalog.json` 与账本里也不再写 `region` 字段
+  （旧文件里的该字段读入后直接忽略）。
+
+### 修正
+
+- **开关可以「假开启」**：`priority/set` 以前只检查主进程，登录态失效或没选模型时也能点亮，
+  结果每轮 `wb_chat` 都失败。现在开启前依次校验主进程、登录态、模型目录，分别返回
+  `no-process` / `no-auth` / `no-model`，面板按原因提示；没有选过模型时自动落到
+  `preferredSafeModel(safeModelIds())` 并持久化。
+- **环境提示词与实际状态脱节**：`workbuddy.priority` 只有在「开关开 + 主进程在跑 + 已登录」
+  时才输出 `on`，避免提示词命令桌宠调用一个必然失败的通道。
+- `loadTokens()` / `setToken()` 成功时清空 `lastError`，登录态恢复后面板不再挂着旧错误。
+- `usageState(days)` 支持区间参数（0/1/7/30/90，默认 30）；`summarize().spanDays` 不再恒为 1。
+- 面板「用量」改名「用量与成本」：区间概览新增失败数、缓存命中、合计 token 与「全部」一行，
+  按模型聚合同样补上失败数与合计 token；数据仍全部来自账本，不新增任何存储。
+- `world.js` 构造器补上漏声明的 `_procConfirm`，删掉 0.3.0 遗留的孤儿 JSDoc。
+
+## 0.3.1
+
+按 0.3.0 审查报告复核并修复（仍只在本机验证，未推送 / 未发布）。
+
+### 高 / 中优先级
+
+- **`/v3/config` 401/403 的错误分类（最严重）**：`upstream.js` 把 `kind` 字符串当成
+  `WbUpstreamError` 的第二参（`info` 对象）传，错误恒为 `kind='server'`、`status=0`；
+  连锁导致 `models.refresh` 不返回 `noAuth`、`toolChat` 不清 token、前端不提示重新登录。
+  现在传 `{ status: 401|403, kind: 'session_dead' }`；`fetchCatalog` 每次重置认证标记，
+  `fetchModelsLegacy` 的 403 也判 `session_dead`。
+- **`dailyUnusable` 恒为 false**：`parseSchedule` 过滤后 `daily` 是 `[]` 而不是 `undefined`，
+  写错的时段会被当成「全天打折」。现在按「上游给了时段但一条都解析不出来」判定，
+  并让该促销按「不生效」处理（宁可少报一次折扣）。
+- **`rediscover` 静默覆盖手动 token**：手动粘贴 token 后点「重新检测」，0.3.0 仍写
+  `wb-auto` 把密钥库里的真 token 覆盖掉，重启后丢失。现在只有密钥库里确实是
+  `wb-cleared` 登出哨兵、且探测成功时才改写。
+- **「今日积分」跨午夜不归零**：新增 `localDay()` / `rollTodayIfNeeded()`，
+  `envPromptVars()` / `webUi()` / `toolChat()` 累加前都翻篇；详情页徽标、环境提示词与
+  用量面板 `summary.totals.today` 从此一致。
+- **发布流程**：Release 不再与 CI 各自监听 `v*` tag。现在 `release.yml` 里 `publish`
+  `needs: verify`（同一条流水线跑 contract / 构建 / dist 一致性），CI 校验没过就不会发布；
+  `ci.yml` 只负责 push/PR，tag 触发交给 Release。
+- **0.2.x 升级残留**：新增 `scripts/clean-legacy-injection.mjs`（`--check` / `--clean`，
+  幂等、只删本扩展留下的三样东西、绝不覆盖 `index.html` 其他内容）。扩展本体仍
+  **一个字节都不改宿主文件**，清理是用户主动跑的一次性迁移工具。
+- **SECURITY.md 自相矛盾**：删掉「下次启动会重新注入」的残句，写清 0.3.0 起不碰宿主、
+  自定义 `baseUrl` 时 token 会发往该主机、可执行文件覆盖两种安装形态。
+- **`refresh()` 死代码**：`WbUpstream.refresh()` 与 `/v2/auth/refresh` 全仓库无调用点，
+  README 原理图却列了它。现在删掉未接入的实现与原理图那一行，如实写明
+  「登录态失效 → 重新从本机凭据发现」；`credentials.js` 仍解析 `refreshToken`（不外发），
+  chat 请求绝不携带它。
+- **`candidateAppExecutables()` 漏 `WorkBuddy AI.exe`**：桌面端两种安装形态的目录名与
+  exe 名都覆盖，另一种形态也能自动解封 at-rest 密钥。
+
+### 低优先级 / 一致性
+
+- `wb_chat` 描述补回 "Requires the WorkBuddy desktop app to be running"（`WB_TOOL_DECLS`、
+  `definition.js`，`describe.json` 重新生成）。
+- 英文面板不再写已删除的「开始页 Relay first 按钮」；`dist/webui.js` 重新构建。
+- `writeBalance()` 走与账本同一条写队列、临时文件名带 pid；`usageState()` 只在确有
+  超期行时才整文件重写账本。
+- `clearToken` 当下就写 `lastError`（可操作提示不必等重启）；`tools()` handler 不再假设
+  `args` 一定存在；`offlineChecks()` 与 CI 语法检查覆盖 `scripts/lib/*.mjs`；
+  `reinstall.ps1` 删掉空 `if` 死代码。
+- README 统一：CI 是「改跑离线检查」而非「跳过」、三个域名口径、版本号与安装示例。
+- `reinstall.ps1` 的 `npm pack` 不再被误判：Windows PowerShell 5.1 在
+  `$ErrorActionPreference='Stop'` 下把 npm 的 stderr `notice` 当 `NativeCommandError` 抛出，
+  于是静默退回手工 tar、绕过 `prepack`（审查报告第 6 条的真正触发点）。现在临时降为
+  `Continue` 并按真实退出码判断，打包必走 `prepack`。
+- `contract.mjs` 从 68 条扩到 95 条（+27）：新增 `scripts/contract-regression.mjs`
+  承载 0.3.1 回归防线（session_dead 分类与不降级、无效时段不打折、
+  rediscover 不覆盖手动 token、跨日归零、两种安装形态、余额快照并发写），
+  并修掉 0.3.0 的断言数量口径（声称「补 25 条」，实际 55→68 只 +13）。
+
+## 0.3.0
+
+**撤除主界面注入，并按复检报告修掉 9 处中优先级问题。**
+
+### 删掉的功能（以及随之消失的冗余）
+
+- 不再往 Coopanion 主界面「开始」页注入「中转站优先」按钮：删除 `src/host.js`、
+  `scripts/host-inject.mjs`、`assets/workbuddy-home.js`；`world.js` 去掉 `syncHostUi()`、
+  `hostInjectorSource()`、`removeHostUi()`、`hostUiLine()` 与 60 秒自检定时器。
+- 四盏灯回到三盏（WorkBuddy / 主进程 / 中转站优先），`hostInject` 配置项删除，
+  `priority` 面板不再有 `host` / `repair` 方法，面板里的「重新注入」按钮与相关文案一并移除。
+- 扩展现在**不改写宿主任何文件**，卸载不需要还原；装过 0.2.x 的机器按 README
+  的「旧版本残留」一段手工清一次 `build\console` 即可。
+
+### 按复检报告修复
+
+- `rediscover` 之后不再残留「已登出」哨兵：新增 `TOKEN_AUTO = 'wb-auto'`，探测成功即改写，
+  重启后不会又变回未登录。
+- `/v3/config` 返回 401/403 时直接判 `session_dead`，不再降级去读没有促销的旧目录。
+- 自定义 `baseUrl` 时积分查询跟着走同一出口（以前固定打到 `www.codebuddy.cn`）。
+- 构建可复现：`package-lock.json` 锁 esbuild 0.24.2；`build-web.mjs` 新增 `--strict`，
+  `prepack` 用它——找不到 esbuild 时直接失败，不再静默沿用旧 `dist`。
+- 数量口径统一为 22 个安全模型（代码 / 配置描述 / README 一致），并注明只精确放行
+  `hy4-preview`（同前缀的新实验号仍需人工复核）。
+- `describe.json` 生成化后补回 `wb_chat` / `wb_credits` 的「Requires the WorkBuddy desktop app
+  to be running」前提。
+- `contract.mjs` 扩容到 68 条断言，新增复检点名缺口的回归项：哨兵语义、计费域选择、
+  429 软硬区分、面板方法白名单、账本并发（`append` 与 `prune` 串行）、SSE 尾行 flush、
+  `start()` 兜底、本地日期；同时修掉一条恒真断言。
+- 顺手修：`recent` 按时间倒序（以前 `slice(-15).reverse()` 会先取到最旧那条）、
+  `wb-cleared` 时给出可操作提示、`selfcheck` 失败路径清理临时目录、`gen-describe` 英文语法。
+
+## 0.2.0
+
+按 hy4-preview 的审查报告把 17 类问题逐个修掉，并把 `hy4-preview` 纳入安全清单（仍只在本机，未推送 / 未发布）。
+
+- **新模型**：`hy4-preview` 进入安全清单（0.1.7 探测时它正好繁忙、误判为不可用），同时标为「谨慎」
+  —— 预览档，不要把高频自动化打到它身上。
+- **`worlds.workbuddy.hostInject` 真正生效**：关掉后 `start()` 与 60 秒巡检都不再改写宿主
+  `build\console\index.html`，并会主动清掉上一次留下的注入与备份；`stop()` 也先于开关判断执行还原
+  （装完再关掉的场景以前会漏还原）。
+- **promo 计算改成同一条促销说了算**：原来「生效倍率」取自真正打折的那条，「徽标 / 时段 / promoId」
+  取自优先级最高的生效项，两者可能不是同一条，导致面板写着 A 的名字、收着 B 的价。现在
+  `selectPromoDiscount()` 一次挑出「真正改价」的促销，`priceViewOf()` 的
+  `effective / promoId / windowText / discount` 全部来自它，并新增 `discounted` 布尔。
+- **促销时间解析**：`validFrom` / `validUntil` 现在同时接受 ISO 字符串与数字时间戳（<1e12 视为 Unix 秒
+  —— 以前数字时间戳被静默丢弃，过期活动会一直生效）；`daily` 时段在时区无法识别时退回 UTC
+  （以前 `catch` 里 `return 0`，等于把所有活动当成 00:00 生效）；`24:00` 与跨零点窗口照旧。
+- **`base` 倍率不再误读**：`multiplierOfText()` 同时剥前缀与后缀的 `x`。
+- **用量账本并发安全**：`append()` / `prune()` / `clear()` 共用一条串行队列，`prune` 与 `clear` 改成
+  写临时文件再 `rename` —— 以前 `prune()` 的整体重写会覆盖并发进行中的 `append()`。
+- **用量面板 token 列修好**：账本字段名是 `total / prompt / completion`，面板却按
+  `totalTokens / promptTokens / completionTokens` 读，所以「最近调用」的 token 列一直是 0。
+- **宿主注入自愈更彻底**：`inspectHostInjection()` 会真实比对注入脚本内容（新增 `fileStale` 与
+  `reason: injector-stale`），`ensureHostInjection()` 无论当前是否「看起来正常」都会把脚本更新到本版本
+  —— 以前脚本写进 `if (!state.ok)` 里，升级扩展后宿主跑的还是旧脚本。
+- **`--restore` 不再用备份覆盖宿主**：`scripts/host-inject.mjs --restore` 改调 `removeHostInjection()`
+  （只剥引用行、删注入脚本与备份），与「绝不用旧备份覆盖、避免把宿主降级」的原则一致；
+  `--check` 也把「注入脚本过期」算作失败。
+- **换行风格不再被改坏**：`stripInjection()` 按原文件的换行风格重建（以前会把 CRLF 全改成 LF）。
+- **`clearToken` 真的清得掉**：写不清空时返回失败不再是「假成功」；清空后写哨兵 `wb-cleared`，
+  `loadTokens()` 见到哨兵就当作已登出（`rediscover` 才回落到本机凭据库）。
+- **`/v3/config` 失败不再静默**：非 2xx、空数据、无模型条目分别打警告，方便判断是不是被降级到旧接口。
+- **计费域固定**：`WbUpstream` 的 `billingUrl()` 使用 `WB_BILLING_BASE`
+  （早期版本按域名子串猜，自定义 `baseUrl` 时会掉到错误的计费域）。
+- **SSE 收尾不再丢 usage**：流结束时 `decoder.decode()` 冲刷残留字节，并把最后一段没有换行的 `data:`
+  交给同一解析器 —— 以前末尾那段（正好带 `usage`）会被丢掉。
+- **429 两种性质分开**：`classifyHttpFailure()` 按文案把「额度耗尽」判成 `hard_credit`，其余 429 才是
+  `soft_rate`（以前两支返回同一个值）。
+- **解封密钥失败不再永久缓存**：`resolveTokensWithKey()` 的成功结果只复用 60 秒，失败也按 TTL 重试
+  —— 以前一次取密钥失败后，即使用户随后装了 WorkBuddy 桌面端也要重启扩展才能恢复。
+- **`pgrep` 缺失不再算「没在跑」**：`probePosix()` 识别 `command not found` / 退出码 127，返回
+  `via: 'error'`，不写进「未运行」的缓存。
+- **启动流程兜底**：`start()` 全程包 try/catch/finally，`pushEvent` 失败只警告；任何一步抛错都不会让
+  四盏灯永远停在「正在读取登录态…」。
+- **面板方法白名单**：`handleInvoke()` 先校验 `panel`/`method`（`PANEL_METHODS`），未知组合直接拒绝
+  —— 以前任意 panel 都能触发 `setToken` / `clearToken` 写密钥库。
+- **「今日」按本地日期**：`refreshToday()` 不再用 `toISOString()` 取日期（UTC+8 下会把 today 算成前一天）。
+- **`describe.json` 变成生成物**：新增 `scripts/gen-describe.mjs`，工具名 / 描述 / 参数 / tags 来自
+  `WB_TOOL_DECLS`，环境提示词来自 `src/ENV_PROMPT.md`，摘要与事件写在生成器里；`--check` 可验一致性。
+  删掉包里那份 724 字节的旧 `ENV_PROMPT.md` 模板（真正的模板是 `src/ENV_PROMPT.md`）。
+- **新增 `scripts/contract.mjs`**：静态契约 + 单元断言（describe 与源码一致、版本与 CHANGELOG 对齐、
+  提示词占位符都有对应变量、夜间/白天促销、数字时间戳、时区回退、安全清单、账本聚合、CRLF 保留），
+  没装 Coopanion 的机器上也能跑；`selfcheck.mjs` 找不到宿主时改为跑它。
+- **`reinstall.ps1` 不再往作者机器路径写**：默认输出到 `$env:LOCALAPPDATA\cortico-world-workbuddy\build`，
+  优先 `npm pack`（会走 `prepack` 重建构建产物），手工 `tar` 只作兜底。
+- **CI 补上真正的校验**：`npm run build:web` + `git diff --exit-code -- dist` + `node scripts/contract.mjs`；
+  Release 工作流与 CI 统一用 `npm ci`。
+
 ## 0.1.7
 
 按 WorkBuddy 官方对话给出的合规口径，给桥接加「安全清单」闸门（仍只在本机，未推送 / 未发布）。

package/README.md

@@ -1,10 +1,10 @@
 # cortico-world-workbuddy
 
-把 **本机已登录的 WorkBuddy 客户端**（国内版 / 国际版）的模型桥接进
+把 **本机已登录的 WorkBuddy 客户端**的模型桥接进
 [Coopanion](https://github.com/Pal-AI-Lab/Coopanion) 桌宠：Coo 可以直接调用你
 WorkBuddy 账号里的模型，World 面板里可以浏览模型目录、查看每个模型的
-**默认积分倍率**（如 `x0.79`）并点选要用的模型；「开始」页有一个「中转站优先」按钮，
-打开后桌宠每轮对话都先问 WorkBuddy。
+**默认积分倍率**（如 `x0.79`）并点选要用的模型；World 详情页有一个「是否启用Workbuddy」
+开关，打开后桌宠每轮对话都先问 WorkBuddy。
 
 这是一个 Cortico 的 World 扩展（`kind: world`，`api: 6`），纯 ESM JS、零运行时依赖，
 面板产物已随包构建好（`dist/webui.js`）。
@@ -14,12 +14,12 @@ WorkBuddy 账号里的模型，World 面板里可以浏览模型目录、查看
 > 按上游给出的倍率真实扣费；扩展不提供账号、不共享凭据、不绕过计费。
 > 请自行评估账号风险，官方 WorkBuddy 客户端始终是最安全的选择。
 
-## 安装（0.1.5，Coopanion 0.2.17 实机验证）
+## 安装（0.3.4，Coopanion 0.2.17 实机验证）
 
-一条命令（推荐，脚本会做完打包、装卸、哈希与版本校验、开始页注入）：
+一条命令（推荐，脚本会做完打包、装卸、哈希与版本校验）：
 
 ```powershell
-pwsh -File scripts/reinstall.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/reinstall.ps1
 ```
 
 手工装的话，三步：
@@ -32,7 +32,7 @@ pwsh -File scripts/reinstall.ps1
    cd "C:\Users\<你>\AppData\Local\Programs\Coopanion\data\extensions"
    node "C:\Users\<你>\AppData\Local\Programs\Coopanion\resources\app\node_modules\pnpm\bin\pnpm.cjs" remove cortico-world-workbuddy
    node "C:\Users\<你>\AppData\Local\Programs\Coopanion\resources\app\node_modules\pnpm\bin\pnpm.cjs" `
-     add "F:\coo-connect-wb\cortico-world-workbuddy-0.1.4.tgz" `
+     add "$env:LOCALAPPDATA\cortico-world-workbuddy\build\cortico-world-workbuddy-0.3.4.tgz" `
      --config.strict-dep-builds=false `
      --store-dir "C:\Users\<你>\AppData\Local\Programs\Coopanion\data\pnpm\store\v11"
    ```
@@ -43,29 +43,16 @@ pwsh -File scripts/reinstall.ps1
 
    ```json
    "workbuddy": {
-     "enabled": true, "region": "cn", "model": "deepseek-v4.1-flash",
+     "enabled": true, "model": "deepseek-v4.1-flash",
      "credentialsDir": "", "baseUrl": "", "maxTokens": 2048,
-     "envPrompt": true, "prefer": false
+     "envPrompt": true
    }
    ```
 
-3. 装「开始」页按钮（0.1.3 起脚本化，幂等）：
+3. 重启 Coopanion（ESM 模块缓存不支持热换代码），用带环境清理的启动器：
 
    ```powershell
-   node scripts/host-inject.mjs            # 检查 + 修复
-   node scripts/host-inject.mjs --check    # 只检查（退出码：0=正常，1=缺注入）
-   node scripts/host-inject.mjs --restore  # 从备份还原，彻底移除注入
-   ```
-
-   它把 `assets/workbuddy-home.js` 复制到 `<Coopanion>\resources\app\build\console\`，并在
-   `index.html` 里 `<script type="module" src="./index.js"></script>` **之前**插一行；首次
-   改动前自动把 `index.html` 备份成 `index.html.workbuddy-backup`，注入脚本头部带
-   `/* bundled:<version> */` 便于核对。
-
-4. 重启 Coopanion（ESM 模块缓存不支持热换代码），用带环境清理的启动器：
-
-   ```powershell
-   pwsh -File scripts/launch-coopanion.ps1
+   powershell -NoProfile -ExecutionPolicy Bypass -File scripts/launch-coopanion.ps1
    ```
 
    > **为什么要有启动器**：终端里残留 `ELECTRON_RUN_AS_NODE=1`（比如跑过 Node 子进程）时，
@@ -73,22 +60,28 @@ pwsh -File scripts/reinstall.ps1
    > 打印 `v24.x`（node 版本）、`--enable-logging` 报 `bad option`。这不是二进制损坏，
    > 是环境变量被继承。启动器只清本进程树里的这个变量，不动用户/机器级设置。
 
-> 宿主升级会覆盖 `build\console`，注入随之消失——但扩展每 60 秒自检一次，发现缺失会自动
-> 重注入；「是否启用 WorkBuddy」面板里有「重新注入开始页按钮」按钮可手动触发；
-> 四盏灯里的「开始页按钮」会直接显示状态（在线 / 需要修复）。`wb_*` 工具不受影响。
 
 ## 卸载与还原
 
-- **只卸扩展**：在「World 扩展」里卸载 / 或 `pnpm remove cortico-world-workbuddy`。
-  之后开始页那一行会在 3 秒内自动消失（脚本检测到 `/api/worlds` 里没有 `workbuddy`），
-  详情页入口随之消失，桌宠工具表里也不再有 `wb_*`——Coopanion 主体不受影响。
-- **注入会自动清**：停用 World、卸扩展、退出 Coopanion 时 `stop()` 都会调用
-  `removeHostInjection()`，把 `index.html` 的引用行剥掉并删掉注入脚本与备份——
-  宿主目录回到「没装过这个扩展」的样子，不会留下永久改动。
-- **想手动清**：`node scripts/host-inject.mjs --restore`（或手工删
-  `build\console\workbuddy-home.js` 并去掉 `index.html` 里那行）。
-- **开关状态**：`worlds.workbuddy.prefer` 留在 `data\home\companion\config.json` 里；
-  扩展不在时没人读它，重新装回来会恢复上次的状态。
+1. 在「World 扩展」里卸载，或执行 `pnpm remove cortico-world-workbuddy`，然后重启 Coopanion。
+   详情页入口与 `wb_*` 工具随之消失，Coopanion 主体和其他 World 不受影响。
+2. 宿主的卸载接口只删除扩展包，不会调用扩展清理逻辑，也不会删除部署配置和账本。
+   因此在源码目录再执行一次显式清理（先检查、后清理）：
+
+   ```bash
+   node scripts/clean-workbuddy.mjs --check
+   node scripts/clean-workbuddy.mjs --clean
+   ```
+
+   清理范围只有：`config.json` 的 `worlds.workbuddy` 块、`.env` 的 `accessToken` 行
+   （真实 token 或 `wb-cleared` / `wb-auto` 哨兵），以及数据目录里的
+   `workbuddy-usage.jsonl`、`workbuddy-catalog.json`、`workbuddy-balance.json`。
+   其他配置、其他密钥和宿主文件不动，命令输出也不会显示 token。
+- **不碰宿主程序文件**：0.3.0 起扩展不再往 Coopanion 主界面注入脚本或按钮，
+  `resources\app` 不会被改写。普通 `stop()` / 重启不会删除账本；只有上面的显式卸载清理会删。
+- **旧版本残留（0.2.x → 0.3.x）**：装过 0.2.x 的机器，另外执行
+  `node scripts/clean-legacy-injection.mjs --check` 并按结果使用 `--clean`，清除旧版留在
+  `build\console\` 的注入行、脚本与备份；脚本不覆盖 `index.html` 的其他内容。
 
 ## 工作原理
 
@@ -99,12 +92,11 @@ Coopanion (Coo)
        ├─ 凭据发现   %LOCALAPPDATA%\CodeBuddyExtension\Data\Public\auth\workbuddy-desktop.info
        │              （$wbEncrypted 信封 → 用桌面端自己的二进制自动解封）
        ├─ 上游客户端 copilot.tencent.com（对话）/ www.codebuddy.cn（计费）
-       │    ├─ GET  /v2/enterprises/personal/models          模型目录（credits = 积分倍率）
+       │    ├─ GET  /v3/config                              模型目录 + 促销（models / modelPromotions / modelTiers）
        │    ├─ POST /v2/chat/completions                     对话（SSE 流式）
-       │    ├─ POST /v2/auth/refresh                         刷新 token（X-Refresh-Token）
        │    └─ POST /v2/billing/meter/get-user-resource      积分余额（只读）
        ├─ 工具        wb_list_models / wb_select_model / wb_chat / wb_credits
-       └─ WebUI 面板  模型目录、账号、是否启用 WorkBuddy（中转站优先）
+       └─ WebUI 面板  模型目录（含只读主进程状态）、账号、用量与成本
 ```
 
 - **主进程检测**：桌面端的渲染进程都是主进程的子进程，所以「有 `WorkBuddy.exe`」等价于
@@ -117,32 +109,31 @@ Coopanion (Coo)
   token 只经 `ctx.storeSecret()` 进部署的密钥库，**不写配置、不进日志、面板只显示掩码**。
 - **积分倍率**：完全来自上游目录的 `credits` 字段，扩展不写死；刷新后缓存到
   `workbuddy-catalog.json`，重启不丢。
-- **区域**：国内版 `copilot.tencent.com` 与国际版 `www.workbuddy.ai` 是两个上游；
-  计费域国内是 `www.codebuddy.cn`。切 `worlds.workbuddy.region` 后重新刷新目录。
-
-## 「中转站优先」开关
+- **登录态失效**：`/v3/config` 返回 401/403 时直接判 `session_dead` 并清掉本次 token；
+  下一次调用重新从本机凭据发现（桌面端自行刷新落盘）。本扩展不调用刷新接口，
+  chat 请求也绝不携带 refresh token。
+- **上游**：目录与对话固定走 `copilot.tencent.com`，积分余额走 `www.codebuddy.cn`。
+  本扩展只支持这一套上游（本机已登录的 WorkBuddy 桌面端）；配了自定义 `baseUrl` 时两个域都由它替换。
 
-一份状态（`worlds.workbuddy.prefer`），两个入口，默认都是**关**：
+## 主进程状态与按需调用
 
-| 入口 | 位置 | 行为 |
-|---|---|---|
-| 开始页按钮 | 主界面「开始」→「可选择的模型：」下一排「中转站优先：」+ WorkBuddy 图标 | 点击高亮＝开；再点熄灭＝关 |
-| 详情页开关 | 「World 扩展」→ WorkBuddy 桥接 →「是否启用Workbuddy」 | 与按钮同步，任一入口改两处都变 |
+0.3.4 起没有「中转站优先」开关，也没有任何「每轮强制走 WorkBuddy」的行为：
 
-- 开 → 环境提示词告诉 Coo：每轮对话先 `wb_chat`（用 `worlds.workbuddy.model`），
-  再把回答用自己的话讲出来并说明是哪个模型答的。
-- 关 → Coo 完全不碰 `wb_*`（用户明确点名 WorkBuddy 时除外）。
-- 点按钮时若没检测到主进程：按钮保持熄灭 + 弹「未检测到Workbuddy」，不会把开关打开。
-- 主进程在 6 秒轮询里退出时，开关自动熄灭，避免亮着却调不通。
+- 「模型目录」面板顶部只读显示 WorkBuddy 主进程是否在跑（6 秒轮询，翻转时才推送）；
+  勾选框已删除，状态不参与任何开关逻辑。
+- `wb_*` 工具由 Coo 按需调用：用户点名 WorkBuddy、或某个 WorkBuddy 模型明显更合适时才用。
+  不调用就不花积分——这是「每个调用都真实扣积分」的默认前提。
+- 环境提示词只描述事实（登录态、模型、倍率、主进程状态、今日用量）和工具用法，
+  不再命令「每轮先 `wb_chat`」。
+- 主进程退出时面板状态会变成「未检测到」，工具调用直接返回明确错误，不需要切换任何开关。
 
 ## 面板
 
 | 面板 | 内容 |
 |---|---|
-| 模型目录 | 刷新目录；逐模型一行：名称/id、**合规档位**、**此刻倍率**（含限时折扣时显示 `x0.5 ← x0.79 23:00–07:50`，x0 标「免费」）、上下文、推理档、「选用」按钮；默认只列安全清单，勾选「显示全部模型（含不建议项）」才展开其余项 |
+| 模型目录 | 顶部只读显示 WorkBuddy 主进程状态；刷新目录；逐模型一行：名称/id、**合规档位**、**此刻倍率**（含限时折扣时显示 `x0.5 ← x0.79 23:00–07:50`，x0 标「免费」）、上下文、推理档、「选用」按钮；默认只列安全清单，勾选「显示全部模型（含不建议项）」才展开其余项 |
 | 账号 | 登录态来源（本机发现 / 手动）、掩码 token、积分余额查询、重新检测、手动 token 存取 |
-| 是否启用 WorkBuddy | 「中转站优先」开关 + 主进程状态，与开始页按钮同步 |
-| 用量 | 区间概览（今天 / 近 7 天 / 近 30 天）、按模型聚合、积分包明细、限时优惠清单、最近调用；带「刷新余额」「清空本地账本」 |
+| 用量与成本 | 区间概览（今天 / 近 7 天 / 近 30 天 / 全部，列：调用、失败、积分、输入/输出/缓存命中/合计 token）、按模型近 30 天聚合、积分包明细、限时优惠清单、最近调用；带「刷新余额」「清空本地账本」 |
 
 ### 安全清单（合规闸门）
 
@@ -150,14 +141,15 @@ WorkBuddy 官方对话给出的口径是：只调用「官方公开目录里、
 `disabled`、内部路由别名、媒体/代码补全与状态不明的模型都不要经外部软件调用，否则有风控/封号风险。
 这里把它落成代码：
 
-- 白名单 21 个（`src/safety.js` 的 `SAFE_MODEL_IDS`，按 DeepSeek / GLM / 混元 / Kimi / 其他分组）：
+- 白名单 22 个（`src/safety.js` 的 `SAFE_MODEL_IDS`，按 DeepSeek / GLM / 混元 / Kimi / 其他分组）：
   `deepseek-v4.1-flash`、`deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-v3-2-volc`、
   `glm-5.3-flash`、`glm-5.3`、`glm-5.2`、`hy3`、`hy3-b`、`hy3-c`、`hy3-x`、`hunyuan-chat`、
-  `kimi-k2.5`、`kimi-k2.8-preview`、`kimi-k3-1`、`kimi-k3.1-pro`、`minimax-m2.7`、
+  `hy4-preview`、`kimi-k2.5`、`kimi-k2.8-preview`、`kimi-k3-1`、`kimi-k3.1-pro`、`minimax-m2.7`、
   `minimax-m3.1-flash`、`mimo-v2.6-pro`、`space-bunny`、`step-5-preview`。
-  其中 `hy3*` 与 `*preview` 标为「谨慎」（免费试用/预览，别做高频自动化）。
+  其中 `hy3*` 与 `*preview`（含 `hy4-preview`）标为「谨慎」（免费试用/预览，别做高频自动化）。
 - 其余全部**拒绝**：`wb-lite`（目录 `disabled:true`）、`auto` / `fast-model` / `balanced-model` /
-  `deep-model`（内部路由别名）、4 个媒体模型、`codewise-*`、`hy4-preview*`、19 个已下架的、
+  `deep-model`（内部路由别名）、4 个媒体模型、`codewise-*`、其他 `hy4-preview*` 变体（只精确放行
+  `hy4-preview`）、19 个已下架的、
   `glm-5.0-turbo`（11150 请求格式不符）。
 - 闸门是 `worlds.workbuddy.safeOnly`（默认 `true`）。开着时 `wb_chat` / `wb_select_model` / 面板「选用」
   三处一致拒绝，并说明「判定档位 + 理由 + 怎么解除」；关掉才放行，属于明示的风险自负。
@@ -168,8 +160,9 @@ WorkBuddy 官方对话给出的口径是：只调用「官方公开目录里、
 
 - 目录来自 `GET /v3/config`（应用身份 UA）：一次同时拿到 `models`、`modelPromotions`、`modelTiers`。
   用 CLI 身份只能读到精简目录，促销字段会整段缺失——这是「倍率永远显示原价」的根因。
-- 一条促销的生效条件是 `schedule`：`timezone`（默认按条目给的时区算）、`validFrom`/`validUntil`、
-  `daily` 时段（支持 `23:00`→`07:50` 这类跨零点窗口）。命中的条目按 `priority` 取最高；平手时促销优先于档位。
+- 一条促销的生效条件是 `schedule`：`timezone`（省略时按 `Asia/Shanghai`）、`validFrom`/`validUntil`、
+  `daily` 时段（支持 `23:00`→`07:50` 这类跨零点窗口）。纯日期按当地自然日解释，`validUntil` 包含当天；
+  命中的条目按 `priority` 取最高，平手时促销优先于档位。
 - `discount.discountedCredits`（如 `0.50x`）**就是生效倍率本身**，不是相对原价的系数。
   `displayMode: "replace"` 直接替换显示，`"strikethrough"` 表示「划线原价 + 新价」并排。
 - `badge.display: "activeOnly"` 的徽标只在生效时段出现（如「限时免费」试用）。
@@ -177,8 +170,9 @@ WorkBuddy 官方对话给出的口径是：只调用「官方公开目录里、
 ### 用量统计口径
 
 - 每次 `wb_chat` 记一行到 `%APPDATA%\..\Coopanion\data\home\companion\data\workbuddy-usage.jsonl`
-  （实机路径；实际就是 `ctx.dataDir`）：`ts/model/region/ok/promptTokens/completionTokens/totalTokens/cachedTokens/reasoningTokens/credit/multiplier/promoId/source/durationMs`。
-- `credit` 取 SSE 最后一段的 `usage.credit`，即**上游真实扣费**；倍率 0.11 的模型单次请求不足 1 分时上游就是 0，这里照抄不折算。
+  （实机路径；实际就是 `ctx.dataDir`）：`ts/model/ok/promptTokens/completionTokens/totalTokens/cachedTokens/reasoningTokens/credit/multiplier/baseMultiplier/promoId/source/durationMs`。
+- `credit` 取 SSE 各段合并后的 `usage.credit`，即**上游真实扣费**；倍率 0.11 的模型单次请求不足 1 分时上游就是 0，这里照抄不折算。
+  上游未回传时记为未知，概览用 `+ ?` 标出缺口，绝不当成 0；`multiplier` 是响应完成时的生效倍率，`baseMultiplier` 是目录原价。
 - 积分包余额另存 `workbuddy-balance.json`（`POST /v2/billing/meter/get-user-resource` 的 `*Precise` 字段求和），
   面板上的「刷新余额」会重取一次。
 - 账本只保留 90 天，读的时候顺带裁掉；「清空本地账本」会把它清成空文件，服务端数据不受影响。
@@ -196,31 +190,36 @@ WorkBuddy 官方对话给出的口径是：只调用「官方公开目录里、
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `region` | `cn` | `cn` / `global` |
 | `model` | `""` | 当前模型 id（面板点选即写这里） |
 | `credentialsDir` | `""` | 自定义凭据目录，留空自动发现（重启生效） |
 | `baseUrl` | `""` | 自定义上游地址，代理/中转用（重启生效） |
 | `maxTokens` | `2048` | `wb_chat` 单次输出上限 |
-| `envPrompt` | `true` | 是否把桥接状态写进 system 前缀（关掉后「中转站优先」也不生效） |
-| `prefer` | `false` | 「中转站优先」，由开始页按钮 / 详情页开关写入 |
-| `hostInject` | `true` | 是否注入「开始」页按钮（关掉后不碰宿主文件，只用详情页开关） |
+| `envPrompt` | `true` | 是否把桥接状态写进 system 前缀 |
 | `safeOnly` | `true` | 只允许调用安全清单内的公开对话模型；关掉会放行 disabled / 别名 / 预览等项，风险自负 |
 
 ## 开发与校验
 
 ```bash
 # 重新构建面板产物（改了 src/webui/client.js 后）
-node <Coopanion>/resources/app/node_modules/esbuild/bin/esbuild \
-  src/webui/client.js --bundle --format=esm --outfile=dist/webui.js
+# 优先用本地 devDependency（锁在 package-lock.json 的 0.24.2），没装则退回宿主自带的 esbuild；
+# `prepack` 走 `--strict`：两条路都没有就直接失败，绝不静默发布过期 dist。
+node scripts/build-web.mjs
+
+# 契约检查（不依赖宿主，CI 必跑）：describe.json 与源码一致、版本号与 CHANGELOG 对齐、
+# 促销/安全清单/账本断言，以及哨兵、计费域、429 软硬、面板白名单、并发、SSE flush 等回归断言；
+# 0.3.1 另加 session_dead 分类、无效时段、rediscover 覆盖、跨日归零等防线（contract-regression.mjs）
+node scripts/contract.mjs
+
+# 由源码重新生成 describe.json（改过工具声明或 ENV_PROMPT.md 之后）
+node scripts/gen-describe.mjs
 
 # 框架契约自检（dry-mount：定义、工具、envPrompt、webUi）
+# 缺宿主时（CI）自动改跑「离线检查」：全部文件 node --check + contract，不再无条件成功
 node scripts/selfcheck.mjs
 
 # 真实窗口 UI 验证（headless Chrome + CDP，连跑 5 轮；需 Coopanion 正在运行）
 node scripts/verify-ui.mjs --runs 5
 
-# 宿主注入状态
-node scripts/host-inject.mjs --check
 ```
 
 UI 验证脚本的两个约定（踩过坑，别再用固定 sleep）：每轮导航都带 `?t=<时间戳>` 整页重载
@@ -228,7 +227,7 @@ UI 验证脚本的两个约定（踩过坑，别再用固定 sleep）：每轮
 并把「路由挂载」与「面板渲染」拆成两条断言——否则一次产物没加载就会被误判成「按钮没了」。
 
 版本号规范：任何改动都 bump `package.json` 的 `version`，备份目录按版本命名
-（`F:\coo-connect-wb\0.1.4\`），再用 `scripts/reinstall.ps1` 装；它会在装完后逐文件比对哈希，
+（`F:\coo-connect-wb\0.3.4\`），再用 `scripts/reinstall.ps1` 装；它先把 tgz 解出来，再拿**解出来的内容**与安装目录逐文件比对哈希，
 不一致直接非零退出。
 
 打包注意：**不要用 PowerShell 的 `Get-Content -Raw | Set-Content` 改 `package.json`**
@@ -236,38 +235,31 @@ UI 验证脚本的两个约定（踩过坑，别再用固定 sleep）：每轮
 用 node 读写 JSON；tgz 必须以 `package/` 为前缀：
 
 ```bash
-tar -czf cortico-world-workbuddy-0.1.4.tgz -C <stage> package
+tar -czf cortico-world-workbuddy-0.3.4.tgz -C <stage> package
 ```
 
 协议细节参照 [dsh-connect-workbuddy](https://github.com/dingminhua/dsh-connect-workbuddy)
 （MIT）的实测结论；扩展框架契约见 Cortico 的 `docs/extensions.md` / `docs/worlds.md` /
 `docs/webui.md`。
 
-## 它改了宿主程序的哪些文件（以及怎么还原）
+## 宿主文件：一个字节都不改
 
-> 这是本扩展唯一会碰到 Coopanion 安装目录的地方，装之前请务必看完。
+0.3.0 起本扩展**不再往 Coopanion 主界面注入任何东西**——详情页只有三个只读/配置面板，
+没有开关勾选框，`resources\app` 下不会有任何改动；部署配置、账本与手动 token 按上一节的显式步骤清理。
 
-「开始」页的「中转站优先：」按钮没有官方扩展点（Cortico 的 WebUI 只给每个 World 提供自己的
-面板，主页没有插槽），所以只能用一行注入实现：
-
-| 文件 | 改动 | 还原 |
-|---|---|---|
-| `<app>\build\console\index.html` | 在 `<script type="module" src="./index.js">` 前插入一行 `<script type="module" src="./workbuddy-home.js">` | 用备份 `index.html.workbuddy-backup` 覆盖，或删掉那一行 |
-| `<app>\build\console\workbuddy-home.js` | 新增注入脚本（约 11 KB，自包含，内嵌图标 data URL） | 删除该文件 |
-| `<app>\build\console\index.html.workbuddy-backup` | 首次注入前的原件备份 | 手动删掉即可 |
+如果你装过 0.2.x，宿主 `build\console\` 里可能还留着三处痕迹。扩展本体不会自动改
+宿主文件（这正是 0.3.0 起的承诺），请用一次性迁移脚本清理：
 
-```powershell
-node scripts/host-inject.mjs --check     # 查：缺注入时退出码 1
-node scripts/host-inject.mjs            # 补：幂等，顺带补齐备份
-node scripts/host-inject.mjs --restore  # 还原：有备份用备份，没有就地剥掉那一行
+```bash
+node scripts/clean-legacy-injection.mjs --check   # 只列出会动的项
+node scripts/clean-legacy-injection.mjs --clean   # 执行清理（幂等）
 ```
 
-- 注入脚本自带 try/catch：查不到 `workbuddy` World（比如扩展被卸载）时整行按钮自动消失，
-  不会在主页留下死按钮，也不会抛异常影响主界面。
-- Coopanion 更新（换 `app.asar` / 重装）会把 `build/console` 覆盖回出厂状态 —— 注入随之消失，
-  扩展下次启动时 60 秒内自己补回来，四盏灯里的「开始页按钮」会告诉你当前状态。
-- 卸载扩展：`stop()` 会自动还原（无需手动 `--restore`），然后把包从 `data/extensions` 里
-  `pnpm remove` 掉即可；想直接禁止改写宿主文件，把 `worlds.workbuddy.hostInject` 设为 `false`。
+| 文件 | 脚本会做什么 |
+|---|---|
+| `<app>\build\console\index.html` | 只剥掉 `<script type="module" src="./workbuddy-home.js"></script>` 这一行，保留原有换行风格与其余内容 |
+| `<app>\build\console\workbuddy-home.js` | 删除旧的注入脚本 |
+| `<app>\build\console\index.html.workbuddy-backup` | 删除首次注入前的原件备份 |
 
 ## 发布（GitHub / npm / 扩展市场）
 
@@ -275,7 +267,7 @@ Cortico 的扩展**从 npm 安装**；GitHub 是源码与申请的入口，官
 [cortico-extensions](https://github.com/Pal-AI-Lab/cortico-extensions) 只放标签词表、认证与覆盖项。
 Action 定时扫 npm 生成市场目录，所以发版顺序是：**先 npm publish，再 `[sync]` 催收录**。
 
-本包发布元数据（0.1.4 起）：
+本包发布元数据：
 
 | 项 | 值 | 为什么 |
 |---|---|---|
@@ -289,12 +281,12 @@ Action 定时扫 npm 生成市场目录，所以发版顺序是：**先 npm publ
 
 ```bash
 # 1. 发版前三连检（需要本机真实宿主）
-node scripts/selfcheck.mjs
-node scripts/host-inject.mjs --check
+node scripts/contract.mjs        # 不依赖宿主，全部断言
+node scripts/selfcheck.mjs       # dry-mount 框架契约
 node scripts/verify-ui.mjs --runs 3
 
 # 2. 提交并打 tag
-git tag v0.1.4 && git push --tags
+git tag v0.3.4 && git push --tags
 
 # 3. 发布（prepack 会自动重建 dist/webui.js）
 npm publish --access public
@@ -306,13 +298,15 @@ gh issue create -R Pal-AI-Lab/cortico-extensions --title "[sync] cortico-world-w
 对标签有异议用 `[tags]`、申请蓝标认证用 `[certify]`、被拉黑申诉用 `[appeal]`，
 正文一行一项 `键: 值`（`package` / `add` / `remove` / `reason` / `evidence`）。
 
-CI 里没有 Coopanion，自检会跳过而不是红叉：
+CI 里没有 Coopanion：自检改跑离线检查（全部源码 `node --check` + `contract`），
+不会红叉，也不会无条件算通过：
 
 ```bash
 node scripts/selfcheck.mjs --allow-missing-host   # 找不到宿主 → 警告 + 退出码 0
 ```
 
-凭据读取范围与网络出口见 [SECURITY.md](./SECURITY.md)：读哪些文件、只发给哪两个域名、哪些从不写盘。
+凭据读取范围与网络出口见 [SECURITY.md](./SECURITY.md)：读哪些文件、默认只发给哪两个官方域名
+（配了自定义 `baseUrl` 时从该出口走）、哪些从不写盘。
 
 ## 免责