@ponydev/dsh-model-usage 1.0.1 → 1.0.3

package/AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md — dsh-model-usage 项目规范（AI / 自动化代理）
+
+本文件是**在这个仓库里工作时必须遵守的项目级规范**。全局规范见 `~/.dsh/AGENTS.md`；本文件只写项目特有约束。
+
+## 0. 一句话
+
+DSH Web 插件：显示模型供应商额度与用量。**只展示真实数据，绝不做金额估算**；UI 必须符合 DSH Web 原生规范。
+
+## 1. 目录与职责
+
+```
+lib/index.js      Host 入口（Cordis 插件、RPC 路由、会话事件、额度缓存）
+lib/adapters.js   供应商额度适配器（只允许写死的白名单域名）
+lib/ledger.js     请求账本（会话日志聚合、观测、历史回填、持久化）
+lib/client.js     浏览器端 bundle（slots、组件、样式、i18n）
+cordis.patch.yml  bundle 补丁（插入 model-usage 行、默认配置）
+assets/logos/     供应商 logo（SVG）
+scripts/smoke.mjs 冒烟测试（不触网）
+docs/             架构文档、截图
+```
+
+**约束**：Host 与 Client 不能互相 import；Client 不得直接读文件/环境变量；所有跨端数据走 RPC（`POST /model-usage/<endpoint>`）。
+
+## 2. 修改前必须做
+
+1. `git status`、`git log --oneline -3` 确认工作区状态
+2. 涉及 UI：先读 `docs/architecture.md` 的 UI 规范章节
+3. 涉及适配器：确认接口域名/字段有可信来源，**不要编造 URL**
+
+## 3. 提交前必须通过
+
+```bash
+for f in lib/*.js; do node --check "$f"; done   # 语法
+node scripts/smoke.mjs                          # 冒烟（16 项断言）
+npm pack --dry-run                              # 发布内容检查
+```
+
+CI 会重复执行以上检查；失败不合并。
+
+## 4. 代码规范
+
+- **ESM only**，无构建步骤，无运行时依赖
+- 命名：camelCase；私有状态放闭包；不引入全局变量
+- 错误：`err(code, msg)`；错误信息必须脱敏（`safeMsg` 打码 `sk-*`/`Bearer *`）
+- 日志：Host 侧可用 `console`，但**禁止打印凭据、请求头、完整响应**
+- 金额：**禁止出现成本/价格估算逻辑**（订阅按额度计费，估算是错的）
+- 数据口径：Tokens = input + cacheRead + cacheWrite + output；缓存命中率 = cacheRead/(cacheRead+input)
+
+## 5. 安全不变量（不可破坏）
+
+1. API Key 只在 Host 内存中使用，**绝不进入浏览器**，任何 RPC 响应不含密钥
+2. 只请求写死的白名单域名；**客户端不能传 URL**
+3. 账本只存聚合数字，不含对话内容
+4. 新增适配器必须：固定 base URL、超时（`fetchT`）、错误脱敏、`needs-credential` 状态
+5. 不新增第三方运行时依赖（保持零依赖）
+
+## 6. UI 规范（DSH 原生）
+
+- 只用官方组件：`Modal` / `Button` / `Pill` / `StateDot` / `Tooltip` / `Menu` / `SegmentedTabs`
+- 颜色/圆角/字号只用 `--dsw-*` token，禁止硬编码色值（fallback 除外）
+- 设置页只放**短标签 + 控件**，不写说明性长文（口径说明放 README/docs）
+- 文案全走 i18n（zh/en 两个字典），不出现硬编码中文/英文
+- 间距节奏：组件内 12px；卡片内边距 13px 15px；弹窗内容 `mbody` 12px
+- 修改 client 后：`open test-render.html` 离线验证 + 0 控制台错误
+
+## 7. 版本与发布
+
+- 语义化版本：`patch` 修 bug / `minor` 新功能 / `major` 破坏性变更
+- **发布只由 tag 触发**，禁止手动 `npm publish`
+- 流程见 `RELEASE.md`；tag 必须与 `package.json` 版本一致
+- **每个版本必须更新 `CHANGELOG.md`**，条目格式 `## <semver> — <YYYY-MM-DD>`；Release workflow 会抽取当前版本条目作为 GitHub Release 正文，缺失则发布失败
+- 发布使用 npm Trusted Publishing（OIDC），**不增加 NPM_TOKEN**
+
+## 8. 提交规范
+
+- Conventional Commits：`feat:` / `fix:` / `docs:` / `ci:` / `chore:` / `refactor:`
+- 一个提交只做一件事；提交信息中文或英文均可，但需说明"为什么"
+- 不要提交：`node_modules/`、`*.tgz`、临时脚本、密钥、截图调试残留
+- 作者身份使用全局 git config（`Pony <205503242+jmaubay7@users.noreply.github.com>`），不要用 `-c user.email=` 覆盖，不要写 AI 署名
+
+## 9. 不要做的事
+
+- 不要引入构建工具/打包器（手写 ModuleLoader bundle 是刻意设计）
+- 不要改 `lib/client.js` 的 bundle 壳（`window.__ModuleLoader__.load`）结构
+- 不要用 `ctx.connection.rpc.handle()`（web composition 下会失败，必须用 `webServer.register` + `connection.admit`）
+- 不要在 `inject` 里放可选服务（`deepseekAccount` 用 `ctx.get` 宽松读取）
+- 不要删除/改写历史 tag

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.0.3 — 2026-10-19
+
+### 修复
+- 前端模块注册名与安装包名不一致导致 DSH Web 启动失败（`__ModuleLoader__` id 改为 `@ponydev/dsh-model-usage`）
+- 账本实时记录的输入/输出/缓存字段修复后重算历史（此前实时记录 token 明细为 0，聚合少算）
+
+### 变更
+- 更新 README 截图（总览 / 弹窗 / 请求日志），与当前 UI 一致
+- 新增请求日志截图 `docs/screenshots/04-request-log.png`
+
+## 1.0.2 — 2026-10-19
+
+### 新增
+- 项目规范文档：`AGENTS.md`（项目级规范）、`CONTRIBUTING.md`（开发指南）、`RELEASE.md`（自动发布规范）
+- Release 正文自动从 CHANGELOG 抽取当前版本条目（`scripts/release-notes.mjs`），缺失版本条目时发布失败
+
+### 变更
+- 文档三件套随 npm 包发布（`files` 白名单）
+
 ## 1.0.1 — 2026-10-19
 
 - 发布链路切换到 npm Trusted Publishing（OIDC），CI 不再依赖 NPM_TOKEN

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# 贡献指南
+
+## 环境要求
+
+- Node.js 24+
+- 已安装 DSH（`@deepseek-ai/dsh` ≥ 0.2.0-rc.2）
+- 本地开发无需构建（ESM 手写 bundle，无打包步骤）
+
+## 本地开发
+
+```bash
+# 1. 链接安装到 DSH profile
+dsh plugin --profile web add link:$PWD
+
+# 2. Host 侧（lib/index.js、lib/adapters.js、lib/ledger.js）改完必须重启宿主
+launchctl kickstart -k gui/$(id -u)/local.deepseek-harness.web
+
+# 3. Client 侧（lib/client.js）改完刷新页面即可（⌘⇧R）
+```
+
+离线 UI 验证（不依赖宿主）：
+
+```bash
+open test-render.html
+```
+
+## 提交前检查
+
+```bash
+for f in lib/*.js; do node --check "$f"; done
+node scripts/smoke.mjs
+npm pack --dry-run
+```
+
+## 代码约定（摘要，完整见 AGENTS.md）
+
+- ESM、零运行时依赖、无构建工具
+- 只展示真实数据；**禁止金额估算**
+- 凭据只在 Host 内存；RPC 不返回密钥；只请求白名单域名
+- UI 只用 DSH 官方组件与 `--dsw-*` token；文案走 zh/en i18n
+- 设置页面不写说明性长文（口径放 README/docs）
+
+## 提交规范
+
+- Conventional Commits：`feat:` `fix:` `docs:` `ci:` `chore:` `refactor:`
+- 一个提交一件事
+- 不要提交 `node_modules/`、`*.tgz`、密钥、临时脚本
+
+## 发布
+
+不手动发布。`npm version patch|minor|major` 后 `git push --follow-tags`，详见 [RELEASE.md](RELEASE.md)。
+
+## Issue / PR
+
+- Bug 请附：DSH 版本、复现步骤、`~/Library/Logs/deepseek-harness/stderr.log` 相关片段
+- 新增供应商适配器请附：接口文档链接、响应示例（脱敏）、凭据引用名
+- PR 描述写清楚：改了什么、为什么、如何验证

package/README.md

@@ -16,6 +16,8 @@
 
 ![统计面板](https://raw.githubusercontent.com/PonyDevAI/dsh-model-usage/main/docs/screenshots/03-settings.png)
 
+![请求日志](https://raw.githubusercontent.com/PonyDevAI/dsh-model-usage/main/docs/screenshots/04-request-log.png)
+
 ## 安装
 
 要求 DSH `>= 0.2.0-rc.2 < 0.3.0`。
@@ -104,17 +106,21 @@ config:
 - 账本只存用量聚合（token 数、窗口百分比），不含对话内容
 - 错误信息脱敏（`sk-*` / `Bearer *` 会被打码）
 
-## 开发
+## 开发与发布
+
+- 开发环境、联调方式、提交前检查：[CONTRIBUTING.md](CONTRIBUTING.md)
+- 项目级规范（AI/自动化代理必读）：[AGENTS.md](AGENTS.md)
+- **发布流程（tag 触发自动发布，OIDC 无 token）**：[RELEASE.md](RELEASE.md)
+- 架构设计：[docs/architecture.md](docs/architecture.md)
 
 ```bash
 # 本地渲染台（离线验证 UI，不依赖宿主）
 open test-render.html
 
-# 宿主侧改动后需要重启 dsh web；client 侧改动刷新页面即可
+# 发版（自动发布到 npm + GitHub Release）
+npm version patch && git push --follow-tags
 ```
 
-架构说明见 [docs/architecture.md](docs/architecture.md)。
-
 ## License
 
 [MIT](LICENSE)

package/RELEASE.md

@@ -0,0 +1,138 @@
+# 发布规范（自动发布 · Tag 触发）
+
+本项目**不手动 `npm publish`**。发布唯一入口是**推送 `v*` tag**，由 GitHub Actions 自动完成。
+
+## 一、链路总览
+
+```
+git push --follow-tags
+        │
+        ▼
+GitHub Actions: .github/workflows/release.yml   (触发: push tags: v*)
+  1. 校验 tag 与 package.json 版本一致（不一致 → 失败，防误发）
+  2. 语法检查 + 冒烟测试（scripts/smoke.mjs）
+  3. npm Trusted Publishing（OIDC）发布，附 SLSA provenance 签名
+     - 版本已存在则跳过（幂等，可安全重跑）
+  4. 创建 GitHub Release（body 取 CHANGELOG.md）
+```
+
+CI（`.github/workflows/ci.yml`）在 push `main` / PR 时只跑检查（语法 + 冒烟 + `npm pack` 内容校验），**不会发布**。
+
+## 一·五、CHANGELOG 与 Release 正文（强制）
+
+- **每个版本必须在 `CHANGELOG.md` 有对应 `## <版本>` 条目**，缺失时 release workflow 直接失败（`scripts/release-notes.mjs`）
+- GitHub Release 正文 = **自动从 CHANGELOG 抽取当前版本条目**（不是全文、不是手写）
+- CHANGELOG 采用 [Keep a Changelog](https://keepachangelog.com/) 风格：
+
+```markdown
+## 1.0.2 — 2026-10-19
+
+### 新增
+- ...
+
+### 修复
+- ...
+
+### 变更 / 移除
+- ...
+```
+
+- 分类固定用：`新增` / `变更` / `修复` / `移除` / `安全`（无内容的分类省略）
+- 语言：与仓库一致用中文；写"用户可感知的变化"，不写实现细节流水账
+- 版本标题格式：`## <semver> — <YYYY-MM-DD>`（工具按 `## <version>` 前缀匹配）
+
+## 二、认证方式（永不过期）
+
+使用 **npm Trusted Publishing（OIDC）**：
+
+- npm 包设置 → Trusted Publisher → GitHub Actions
+  - Organization or user: `PonyDevAI`
+  - Repository: `dsh-model-usage`
+  - Workflow filename: `release.yml`
+- workflow 权限：`id-token: write` + `contents: write`
+- **不需要** `NPM_TOKEN` secret、不需要 OTP、不会过期
+- 发布包自动获得 `dist.attestations.provenance`（SLSA v1）
+
+> 不要退回 granular token：bypass-2FA token 最长 7 天，且 2027 年起禁止直接发布。
+
+## 三、标准发版步骤
+
+```bash
+# 0. 确认工作区干净、检查通过
+git status
+node scripts/smoke.mjs
+
+# 1. 更新 CHANGELOG.md（新增当前版本条目）
+
+# 2. 升版本（自动改 package.json + commit + 本地 tag）
+npm version patch     # 修复：1.0.1 → 1.0.2
+npm version minor     # 新功能：1.0.x → 1.1.0
+npm version major     # 破坏性：1.x → 2.0.0
+
+# 3. 推送（--follow-tags 会带上 tag，触发发布）
+git push --follow-tags
+```
+
+发布完成后验证：
+
+```bash
+npm view @ponydev/dsh-model-usage version          # 应为新版本
+npm view @ponydev/dsh-model-usage@<ver> dist.attestations   # 应有 provenance
+gh run list --limit 3                               # Release workflow success
+gh release view v<ver>                              # Release 已创建
+```
+
+## 四、版本规则
+
+| 变更类型 | 版本 | 示例 |
+|---|---|---|
+| 修 bug / 文案 / 样式 | patch | 1.0.1 → 1.0.2 |
+| 新功能（兼容） | minor | 1.0.2 → 1.1.0 |
+| 破坏性（改配置结构、RPC、插槽、去除功能） | major | 1.1.0 → 2.0.0 |
+
+- `engines.dsh` 兼容范围变化视为 major
+- 每个版本必须在 `CHANGELOG.md` 增加条目（Keep a Changelog 风格）
+
+## 五、手动打 tag（等价方式）
+
+```bash
+# 先把 package.json version 改成目标版本并提交到 main
+git tag -a v1.0.2 -m "dsh-model-usage 1.0.2"
+git push origin v1.0.2
+```
+
+tag 与 `package.json` 不一致会导致 workflow 第一步失败。
+
+## 六、故障处理
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| `tag x != package.json y` | 版本没改或 tag 打错 | 删本地 tag `git tag -d vX`，改版本后重打 |
+| 发布步骤 "already published, skipping" | 该版本已存在 | 正常；要重发请升版本 |
+| `E403 ... trusted publisher` | npm 未配置 OIDC 或 repo/workflow 名不匹配 | 检查 npm Trusted Publisher 三项字段 |
+| npm 页面差几分钟才出现新版本 | registry 同步延迟 | 等待 2–5 分钟，直接查版本接口 |
+| 需要撤回刚发布的版本 | 72 小时内可 unpublish | 见下节（需 2FA/OTP） |
+
+### 撤回/废弃
+
+```bash
+# 72 小时内：删除版本
+npm unpublish @ponydev/dsh-model-usage@<ver> --force --otp=<OTP>
+
+# 超过 72 小时：标记废弃（推荐）
+npm deprecate @ponydev/dsh-model-usage@<ver> "原因，建议升级到 x.y.z"
+```
+
+## 七、GitHub Release
+
+- 自动创建，标题 `v<版本>`，正文取 `CHANGELOG.md` 全文
+- 不手工编辑历史 Release；如需补充说明，在下一个版本体现
+
+## 八、发布前检查清单
+
+- [ ] `node scripts/smoke.mjs` 通过
+- [ ] `npm pack --dry-run` 内容正确（无临时文件/密钥）
+- [ ] `CHANGELOG.md` 已更新
+- [ ] `README.md` 的安装命令/包名正确
+- [ ] 工作量：`docs/screenshots/` 截图与实际 UI 一致（UI 变更时）
+- [ ] `package.json` 的 `version` 与将要打的 tag 一致

package/cordis.patch.yml

@@ -1,6 +1,6 @@
 - insert:
     - id: model-usage
-      name: dsh-model-usage
+      name: '@ponydev/dsh-model-usage'
       config:
         refreshSeconds: 60
         footer: true

package/lib/client.js

@@ -2,7 +2,7 @@
 // 入口：侧边栏底部（原生 42px 行，Codex 式当前供应商）/ 设置 → 模型用量。
 // 组件：官方 dsh-client-ui-primitives（Modal/Button/Pill/StateDot/Tooltip/锚定弹层）。
 window.__ModuleLoader__.load({
-  id: 'dsh-model-usage',
+  id: '@ponydev/dsh-model-usage',
   factory(require) {
     const React = require('react')
     const ReactDOM = require('react-dom')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponydev/dsh-model-usage",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "DSH Web 插件：实时显示模型供应商额度与用量（DeepSeek / GLM Coding Plan / OpenRouter / Kimi Coding Plan + 自定义适配器）",
   "keywords": [
     "dsh",
@@ -32,7 +32,10 @@
     "docs",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENTS.md",
+    "CONTRIBUTING.md",
+    "RELEASE.md"
   ],
   "exports": {
     ".": "./lib/index.js",