dsh-deepseek-account 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.3 - 2026-08-30
+
+- Keep the sidebar mounted while switching from a ready Provider to DeepSeek, an unknown Provider fallback, or Codex, instead of rendering the previous Provider's incompatible state shape.
+- Preserve Grok and Codex plugin ownership without changing their authentication, models, settings, or RPC behavior.
+- Refactor the bilingual README and add architecture, maintenance, support, conduct, issue, and pull-request guidance for community ownership.
+
 ## 0.1.2 - 2026-08-30
 
 - Republish the corrected provider-aware sidebar release exclusively through the repository's GitHub Actions Trusted Publisher workflow.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+## Our standard
+
+本项目欢迎不同经验、背景和观点的参与者。请保持友善、具体和以问题为中心：
+
+- 尊重不同意见，批评代码和方案而不是个人；
+- 给出可验证的事实、复现和改进建议；
+- 不骚扰、歧视、威胁、泄露他人隐私或发布未经允许的账户信息；
+- 接受维护者为保护社区安全、隐私和项目范围所做的合理决定。
+
+## Enforcement
+
+不当行为可私下报告给仓库维护者。请提供必要上下文，但不要转发无关的个人或账户数据。维护者可以编辑或删除内容、关闭讨论、拒绝贡献，或临时/永久限制参与。处理报告时会尽量保护报告者隐私并避免利益冲突。
+
+本准则适用于仓库、Issue、Pull Request、评审以及代表本项目参与的其他公共空间。

package/CONTRIBUTING.md

@@ -1,5 +1,77 @@
 # Contributing
 
-Please open an issue before a substantial change. Do not include API keys, cookies, OAuth codes, payment details, account screenshots, or private balance responses in issues, tests, commits, or logs.
+感谢你帮助维护 `dsh-deepseek-account`。小而可验证的改动最容易审查和发布；较大的功能或接口调整请先开 Issue 对齐范围。
 
-Development branches must use the `yukiryou/` prefix. Run `npm run check` before opening a pull request and keep Host credential handling separate from browser code.
+参与本项目即表示你同意遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。一般使用问题请先看 [SUPPORT.md](SUPPORT.md)，安全问题必须按 [SECURITY.md](SECURITY.md) 私下报告。
+
+## 开发环境
+
+- Node.js `>=22.19.0 <25`
+- npm（使用仓库提交的 `package-lock.json`）
+- 不需要真实 DeepSeek、Grok 或 Codex 账户即可运行自动化测试
+
+```sh
+git clone https://github.com/yoshino-xiao7/dsh-deepseek-account.git
+cd dsh-deepseek-account
+npm ci --ignore-scripts --omit=peer
+npm run check
+npm run pack:check
+```
+
+不要为了本地开发提交 `node_modules/`、`dist/`、`*.tgz`、日志或真实账户响应。
+
+## 开始修改
+
+1. 搜索现有 Issue，避免重复工作。
+2. 对新功能、兼容性调整或较大重构先开 Issue；小型文档和明确的缺陷修复可直接提交 PR。
+3. 从最新 `main` 创建以 `yukiryou/` 开头的描述性分支，例如 `yukiryou/fix-stale-balance-label`。
+4. 阅读 [架构说明](docs/ARCHITECTURE.md)，在现有 seam 上修改，避免把 Host 凭据逻辑带入浏览器。
+
+## 改动原则
+
+- Host 是唯一允许解析 `DEEPSEEK_API_KEY` 和构造 Authorization header 的模块。
+- 浏览器只消费经过投影的数据；不要透传上游 DeepSeek、Grok 或 Codex 响应。
+- Grok/Codex 是可选 adapter。它们缺失或 RPC 不兼容时，DeepSeek 功能必须继续工作。
+- 金额保持十进制字符串，不要转换为 JavaScript `number`。
+- 不要扩大固定充值 URL，也不要新增读取 Cookie、密码或支付资料的能力。
+- 不要随意放宽响应大小、缓存、限频、loopback 权限或 schema 校验。
+- 不新增生产依赖，除非现有平台能力无法安全完成需求；PR 中必须说明理由、体积和供应链影响。
+- 用户可见行为同时更新中英文 README、界面文案、测试和 `CHANGELOG.md`。
+
+## 测试要求
+
+先运行最小相关测试，再运行完整检查：
+
+```sh
+node --test test/account-balance.test.mjs
+node --test test/account-rpc.test.mjs
+node --test test/client-bundle.test.mjs
+npm run check
+npm run pack:check
+```
+
+缺陷修复应加入能在修复前失败的聚焦测试。涉及接口的改动至少覆盖：
+
+- 正常结果与畸形响应；
+- 凭据缺失、未授权、限频和网络失败；
+- 可选 Provider 插件缺失；
+- 浏览器产物不包含 Host 凭据逻辑；
+- Linux、macOS、Windows 可重复构建。
+
+自动化测试不得访问真实账户或真实付款流程。若你自愿进行真实账户验证，只在 PR 中记录已脱敏的步骤和结论，不上传 Key、Cookie、完整余额、账户截图或付款信息。
+
+## Pull Request
+
+PR 请保持单一目的，并填写模板中的：
+
+- 问题与改动范围；
+- 用户可见行为和兼容性影响；
+- 安全/隐私影响；
+- 实际执行的验证命令；
+- 未验证的真实账户或平台路径。
+
+提交前检查 diff，确认没有生成物、无关格式化或隐私数据。维护者可能要求拆分过大的 PR，或要求为外部 RPC 变化补充兼容回归。
+
+## 发布
+
+贡献者不需要发布权限，也不要在本地执行 `npm publish`。版本、发布说明、npm Trusted Publisher、GitHub Release 和发布后验证由维护者按 [docs/MAINTAINING.md](docs/MAINTAINING.md) 完成。

package/README.en.md

@@ -1,35 +1,103 @@
 # dsh-deepseek-account
 
-An independent DeepSeek Harness account plugin that:
+[![CI](https://github.com/yoshino-xiao7/dsh-deepseek-account/actions/workflows/ci.yml/badge.svg)](https://github.com/yoshino-xiao7/dsh-deepseek-account/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-deepseek-account.svg)](https://www.npmjs.com/package/dsh-deepseek-account)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-- shows the balance associated with the configured DeepSeek API key when the current conversation selects DeepSeek or an unknown custom Provider;
-- shows the reset time for Grok usage and the five-hour and weekly reset times for Codex usage when either Provider is selected;
-- presents CNY/USD total, granted, and topped-up balances in a dedicated settings page;
-- opens the official DeepSeek Platform for web sign-in and top-up.
+An independent account plugin for DeepSeek Harness. It uses one sidebar entry to show account information for the Provider selected by the current conversation and provides an official top-up entry for DeepSeek.
 
-The sidebar shows exactly one item for the Provider selected by the current conversation. Grok and Codex data is read on demand through their existing local RPCs; this plugin does not change or take over either Provider plugin's authentication, models, settings, or other behavior. If either optional plugin is absent, only that Provider's quota source is unavailable while DeepSeek balance and top-up continue to work independently. Unknown custom Providers fall back to DeepSeek.
+> This plugin only reads account status and opens an official page. It never reads web cookies, account passwords, or payment details, and it never signs in or pays on a user's behalf.
 
-Only DeepSeek has a top-up entry. Grok and Codex show reset times only.
+[中文](README.md) · [Contributing](CONTRIBUTING.md) · [Architecture](docs/ARCHITECTURE.md) · [Security](SECURITY.md)
 
-## Security boundary
+## Capabilities and boundaries
 
-`DEEPSEEK_API_KEY` is resolved only by the Host through the Harness credential service. The browser can request only a validated balance snapshot through a loopback-only RPC. The build fails if the client artifact contains credential resolution or an Authorization header.
+| Current Provider | Sidebar content | Data source | Provider plugin required |
+| --- | --- | --- | --- |
+| DeepSeek | Balance for the configured API key | Official DeepSeek `/user/balance` | No |
+| Grok | Quota reset time | Existing local RPC from the Grok plugin | Yes |
+| Codex | Five-hour and weekly reset times | Existing local RPC from the Codex plugin | Yes |
+| Unknown custom Provider | Falls back to the DeepSeek balance | Official DeepSeek `/user/balance` | No |
 
-The top-up destination is fixed to `https://platform.deepseek.com/balance`; sign-in and payment happen entirely on the official DeepSeek website.
+The sidebar always shows exactly one item for the Provider selected by the current conversation. Grok and Codex are optional data sources; this plugin does not take over their authentication, models, settings, or other behavior. If an optional plugin is missing, its quota source is shown as unavailable while DeepSeek balance and top-up remain independent.
+
+Only DeepSeek has a top-up entry. Grok and Codex show reset times only; this plugin neither shows nor infers remaining quota.
 
 ## Installation
 
-After the formal release, install the exact version:
+Requirements:
+
+- Node.js `>=22.19.0 <25`
+- DeepSeek Harness in the `0.1.1-rc.2` line
+- `DEEPSEEK_API_KEY` configured in Harness model settings when reading a DeepSeek balance
+
+Install the current stable version:
 
 ```sh
-dsh plugin --profile web add dsh-deepseek-account@0.1.2
+dsh plugin --profile web add dsh-deepseek-account@0.1.3
 dsh web
 ```
 
-## Development
+In the current conversation's Web UI:
+
+1. The sidebar footer shows account information for the current Provider; click it to refresh.
+2. The “DeepSeek account” settings page shows CNY/USD total, granted, and topped-up balances.
+3. “Sign in and top up” opens only `https://platform.deepseek.com/balance` in a new page.
+
+Continue to pin an exact version when upgrading so pre-release dependencies cannot drift:
 
 ```sh
+dsh plugin --profile web add dsh-deepseek-account@<version>
+dsh web
+```
+
+## Common states
+
+| UI message | Meaning | Suggested action |
+| --- | --- | --- |
+| Configure an API key | Harness credential service did not resolve `DEEPSEEK_API_KEY` | Configure it in model settings; never post the key in an issue or log |
+| API key rejected | DeepSeek returned 401/403 | Replace or reconfigure the key |
+| Too many requests | DeepSeek returned 429 | Wait before retrying; do not refresh repeatedly |
+| Showing the last verified balance | The current request failed and the plugin retained a marked stale snapshot | Check the network, retry later, and note the timestamp |
+| Quota source unavailable | The Grok/Codex plugin is absent, stopped, or exposes an incompatible local RPC | Check that plugin; DeepSeek remains unaffected |
+
+Automatic reads are cached for up to five minutes, manual refreshes for 30 seconds, and concurrent reads are coalesced into one request.
+
+## Security design
+
+- `DEEPSEEK_API_KEY` is resolved only on the Host through the Harness credential service.
+- The browser receives only a strictly projected balance snapshot over a loopback-only RPC.
+- Upstream responses are limited to 32 KiB and monetary values remain decimal strings.
+- The build rejects client artifacts containing credential resolution or an Authorization header.
+- The top-up destination is fixed to the official DeepSeek page; the plugin has no payment authority.
+
+Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Never put real credentials, cookies, balances, or payment data in public issues, screenshots, or test fixtures.
+
+## Development and contribution
+
+```sh
+git clone https://github.com/yoshino-xiao7/dsh-deepseek-account.git
+cd dsh-deepseek-account
+npm ci --ignore-scripts --omit=peer
 npm run check
+npm run pack:check
 ```
 
-The release branch is `yukiryou/v0.1.2`. `dist/` is generated during build and packaging and is not committed.
+`npm run check` runs the Node.js tests followed by a deterministic build. `dist/` is generated and must not be committed. CI exercises the same interfaces on Node.js 22/24 and Linux, macOS, and Windows.
+
+Read these before changing the project:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) for branches, tests, pull requests, and change boundaries
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the Host, loopback RPC, browser, and optional-Provider seams
+- [docs/MAINTAINING.md](docs/MAINTAINING.md) for triage, compatibility, and trusted releases
+- [SUPPORT.md](SUPPORT.md) to choose the right support channel
+
+## Project status
+
+Automated checks cover response projection, caching/rate limiting, RPC authority, absent optional plugins, Provider selection, client credential isolation, cross-platform builds, and package contents.
+
+These checks are not real-account acceptance. Maintainers do not put real API keys in CI and do not automate web sign-in or payment. Version-specific verification scope is recorded under [docs/releases](docs/releases) and in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,37 +1,103 @@
 # dsh-deepseek-account
 
-DeepSeek Harness 的独立账户插件，负责：
+[![CI](https://github.com/yoshino-xiao7/dsh-deepseek-account/actions/workflows/ci.yml/badge.svg)](https://github.com/yoshino-xiao7/dsh-deepseek-account/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-deepseek-account.svg)](https://www.npmjs.com/package/dsh-deepseek-account)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-- 在当前对话选择 DeepSeek 或无法识别的自定义 provider 时显示 API Key 所属账户余额；
-- 在当前对话选择 Grok 时显示额度重置时间，选择 Codex 时显示 5 小时和每周额度重置时间；
-- 在设置页展示 CNY/USD 总余额、赠送余额和充值余额；
-- 打开 DeepSeek 官方平台完成网页登录与充值。
+DeepSeek Harness 的独立账户插件：在一个侧栏入口中展示当前对话所选 Provider 的账户信息，并为 DeepSeek 提供官方充值入口。
 
-侧栏始终只展示当前对话所选 provider 的一项信息。Grok 和 Codex 数据通过它们已经存在的本地 RPC 按需读取；本插件不修改或接管两个 provider 插件的登录、模型、设置或其他能力。未安装 Grok/Codex 插件时，仅对应额度显示“来源不可用”，DeepSeek 余额和充值仍可独立使用。无法识别的自定义 provider 默认回退到 DeepSeek。
+> 插件只负责“查看”和“跳转”。它不会读取网页 Cookie、账户密码或付款资料，也不会代替用户登录或付款。
 
-只有 DeepSeek 提供充值入口。Grok 和 Codex 仅显示额度重置时间。
+[English](README.en.md) · [贡献指南](CONTRIBUTING.md) · [架构说明](docs/ARCHITECTURE.md) · [安全策略](SECURITY.md)
 
-## 安全边界
+## 能力与边界
 
-`DEEPSEEK_API_KEY` 只在 Host 侧通过 Harness credential service 解析。浏览器侧只能调用 loopback RPC 获取经过校验的余额快照，构建脚本会拒绝包含凭据解析或 Authorization header 的客户端产物。
+| 当前 Provider | 侧栏显示 | 数据来源 | 是否需要对应插件 |
+| --- | --- | --- | --- |
+| DeepSeek | API Key 所属账户余额 | DeepSeek 官方 `/user/balance` | 否 |
+| Grok | 额度重置时间 | Grok 插件已有的本地 RPC | 是 |
+| Codex | 5 小时和每周额度重置时间 | Codex 插件已有的本地 RPC | 是 |
+| 无法识别的自定义 Provider | 回退显示 DeepSeek 余额 | DeepSeek 官方 `/user/balance` | 否 |
 
-充值入口固定为 `https://platform.deepseek.com/balance`，登录和付款完全发生在 DeepSeek 官方网页。
+侧栏始终只显示当前对话所选 Provider 的一项信息。Grok 和 Codex 只是可选数据源；本插件不接管它们的登录、模型、设置或其他能力。缺少可选插件时，对应额度显示“来源不可用”，DeepSeek 余额和充值仍可独立使用。
 
-## 开发
+只有 DeepSeek 提供充值入口。Grok 和 Codex 只显示重置时间，不显示或推断剩余额度。
 
-```bash
-npm run check
+## 安装
+
+运行环境：
+
+- Node.js `>=22.19.0 <25`
+- DeepSeek Harness `0.1.1-rc.2` 系列
+- 已在 Harness 模型设置中配置 `DEEPSEEK_API_KEY`（仅查看 DeepSeek 余额时需要）
+
+安装当前稳定版本：
+
+```sh
+dsh plugin --profile web add dsh-deepseek-account@0.1.3
+dsh web
 ```
 
-仓库开发分支为 `yukiryou/v0.1.2`。`dist/` 由构建和打包流程生成，不提交到 Git。
+打开当前对话的 Web 界面后：
 
-## 安装
+1. 侧栏底部会显示当前 Provider 的账户信息；点击可手动刷新。
+2. 设置页的“DeepSeek 账户”可查看 CNY/USD 的总余额、赠送余额和充值余额。
+3. “登录并充值”只会在新页面打开 `https://platform.deepseek.com/balance`。
 
-正式发布后安装精确版本：
+升级时继续使用精确版本，避免预发布阶段的依赖漂移：
 
 ```sh
-dsh plugin --profile web add dsh-deepseek-account@0.1.2
+dsh plugin --profile web add dsh-deepseek-account@<version>
 dsh web
 ```
 
-英文说明见 [README.en.md](README.en.md)。
+## 常见状态
+
+| 界面提示 | 含义 | 建议 |
+| --- | --- | --- |
+| 请先配置 API Key | Harness credential service 未解析到 `DEEPSEEK_API_KEY` | 在模型设置中配置，不要把 Key 发到 Issue 或日志 |
+| API Key 无效或已失效 | DeepSeek 返回 401/403 | 更换或重新配置 Key |
+| 查询过于频繁 | DeepSeek 返回 429 | 稍后再试，不要连续刷新 |
+| 展示上一次成功读取的余额 | 当前请求失败，插件保留了已标记的旧快照 | 检查网络后重试，并留意数据时间 |
+| 额度来源不可用 | Grok/Codex 插件未安装、未运行或其本地 RPC 不兼容 | 检查对应插件；DeepSeek 功能不受影响 |
+
+自动读取最多缓存 5 分钟，手动刷新最多每 30 秒发起一次请求；并发读取会合并为一次请求。
+
+## 安全设计
+
+- `DEEPSEEK_API_KEY` 只在 Host 侧通过 Harness credential service 解析。
+- 浏览器侧只能通过 loopback RPC 获取经过严格投影的余额快照。
+- 单次上游响应限制为 32 KiB，金额始终按十进制字符串处理。
+- 构建会拒绝包含凭据解析或 Authorization header 的客户端产物。
+- 充值地址固定为 DeepSeek 官方页面；插件没有支付权限。
+
+漏洞请按 [安全策略](SECURITY.md) 私下报告。不要在公开 Issue、截图或测试夹具中提交真实凭据、Cookie、账户余额或付款信息。
+
+## 开发与贡献
+
+```sh
+git clone https://github.com/yoshino-xiao7/dsh-deepseek-account.git
+cd dsh-deepseek-account
+npm ci --ignore-scripts --omit=peer
+npm run check
+npm run pack:check
+```
+
+`npm run check` 依次运行 Node.js 测试和确定性构建；`dist/` 是生成物，不提交到 Git。CI 在 Node.js 22/24 和 Linux、macOS、Windows 上验证同一组接口。
+
+开始修改前请阅读：
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)：分支、测试、PR 和提交边界
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)：Host、loopback RPC、浏览器和可选 Provider 的 seam
+- [docs/MAINTAINING.md](docs/MAINTAINING.md)：分诊、兼容性和可信发布流程
+- [SUPPORT.md](SUPPORT.md)：问题应该发到哪里
+
+## 项目状态
+
+自动化验证覆盖响应投影、缓存/限频、RPC 权限、缺失可选插件、Provider 识别、客户端凭据隔离、跨平台构建和包内容。
+
+这些检查不等于真实账户验收：维护者不会在 CI 中使用真实 API Key，也不会自动执行网页登录或付款。版本级验证范围记录在 [docs/releases](docs/releases) 和 [CHANGELOG.md](CHANGELOG.md) 中。
+
+## 许可证
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -1,5 +1,31 @@
 # Security Policy
 
-Report vulnerabilities privately through GitHub Security Advisories for this repository. Do not open a public issue containing credentials, cookies, account data, payment details, or an exploitable proof of concept.
+## Supported versions
 
-Supported releases receive security fixes on the latest stable version. The plugin intentionally has no payment authority: sign-in and payment remain on the fixed official DeepSeek website.
+安全修复面向 npm 上最新的稳定版本。旧版本通常不会回补；若问题影响多个版本，公告会明确受影响范围和升级版本。
+
+## Reporting a vulnerability
+
+请通过本仓库的 GitHub Security Advisories 私下报告，不要先创建公开 Issue、Discussion 或 Pull Request。
+
+报告中可以包含：
+
+- 受影响的插件、Harness 和 Node.js 版本；
+- 不包含秘密信息的最小复现步骤；
+- 预期影响和已知缓解方式；
+- 脱敏后的日志或响应结构。
+
+请勿提交 API Key、OAuth code、Cookie、密码、完整账户余额、支付资料、私钥或可直接利用生产账户的 PoC。维护者不会要求你把这些内容粘贴到 Issue 或聊天中。
+
+维护者会确认报告、评估影响，并在修复可用后协调披露。由于本项目由社区维护，无法承诺固定 SLA；高风险报告会优先处理。
+
+## Security boundary
+
+- `DEEPSEEK_API_KEY` 仅由 Host 侧 Harness credential service 解析。
+- Host 到浏览器的 `/dsh-deepseek-account` RPC 只允许 loopback，并对请求和响应做严格投影。
+- 浏览器不会收到 API Key、Authorization header 或原始上游响应。
+- 上游余额响应限制为 32 KiB；金额保持十进制字符串。
+- Grok/Codex 数据来自可选插件的本地 RPC，本插件只投影重置时间。
+- 充值入口固定为 `https://platform.deepseek.com/balance`；登录和付款完全发生在 DeepSeek 官方网页，本插件没有支付权限。
+
+构建和测试是纵深防御，不代表真实账户、浏览器会话或付款流程已经通过安全审计。版本级验证限制记录在 `docs/releases/`。

package/SUPPORT.md

@@ -0,0 +1,27 @@
+# Support
+
+## 使用问题
+
+先检查 [README.md](README.md) 的“常见状态”和已存在的 Issues。确认仍是本插件问题后，使用 Bug report 模板创建 Issue，并提供：
+
+- 插件、DeepSeek Harness、Node.js 和操作系统版本；
+- 当前选择的 Provider；
+- 可重复的最小步骤；
+- 已脱敏的错误文本；
+- 是否安装了对应的 Grok/Codex 可选插件。
+
+请勿发布 API Key、Cookie、OAuth code、账户余额截图、支付资料或完整的私有响应。维护者不需要这些信息来开始定位。
+
+## 功能建议
+
+使用 Feature request 模板说明用户场景、期望行为和安全/兼容性影响。较大的设计可能会先在 Issue 中确认 seam，再进入实现。
+
+## 不属于本仓库的问题
+
+- DeepSeek 账户、账单、充值或付款结果：联系 DeepSeek 官方支持。
+- Grok/Codex 登录、模型或设置：提交到对应 Provider 插件。
+- DeepSeek Harness 安装或平台级故障：提交到 Harness 项目。
+
+## 安全问题
+
+疑似凭据泄漏、权限绕过、数据越界或可利用漏洞请按 [SECURITY.md](SECURITY.md) 私下报告，不要创建公开 Issue。

package/dist/client/client.js

@@ -193,7 +193,8 @@ window.__ModuleLoader__.load({
     function SidebarBalance({ wide, ctx, client, t }) {
       const provider = useActiveAccountProvider(ctx)
       const { state, busy, refresh } = useAccount(client, provider)
-      const presentation = sidebarPresentation(provider, state, t)
+      const currentState = state.provider === provider ? state : { provider, status: "loading" }
+      const presentation = sidebarPresentation(provider, currentState, t)
       return React.createElement("button", {
         type: "button", className: wide ? "dsh-deepseek-account-card" : "dsh-deepseek-account-rail",
         disabled: busy, onClick: () => void refresh(true), "aria-label": `${presentation.label} ${presentation.summary}`,

package/docs/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# Architecture
+
+本文描述维护者需要长期保持的模块接口和安全 seam。实现较小，但凭据、可选 Provider 和浏览器注入之间的职责不能混合。
+
+## 数据流
+
+```text
+Harness credential service
+          │ resolve DEEPSEEK_API_KEY (Host only)
+          ▼
+account-balance module ── HTTPS GET ──> api.deepseek.com/user/balance
+          │ projected snapshot
+          ▼
+loopback RPC /dsh-deepseek-account
+          │ validated snapshot
+          ▼
+browser account client ──> sidebar + DeepSeek settings
+          │
+          ├── optional /grok-auth RPC  ──> reset time only
+          └── optional /dsh-codex RPC  ──> 5-hour/weekly reset times only
+```
+
+充值是独立路径：浏览器只打开固定的 `https://platform.deepseek.com/balance`。插件不参与该网页的登录、Cookie 或付款请求。
+
+## Modules and interfaces
+
+### Host entry
+
+`src/host/index.mjs` 是 npm 包的 Host 入口。它的接口只有 Harness 插件约定的 `name`、`inject` 和 `apply(ctx)`，负责组合 credential adapter、余额模块与 connection adapter，不包含浏览器 UI。
+
+### Account balance module
+
+`src/internal/account-balance.mjs` 隐藏 DeepSeek 请求、缓存、并发合并、错误分类和响应投影。它的接口是：
+
+```js
+const balance = createDeepSeekAccountBalance({ credentials, fetchImpl?, now? })
+await balance.read({ force? })
+```
+
+可注入的 `fetchImpl` 和 `now` 是内部测试 seam，不应暴露到插件配置。关键不变量：
+
+- 没有凭据时不访问网络；
+- 自动读取缓存 5 分钟，强制读取缓存 30 秒；
+- 同一时间只有一个上游请求；
+- 响应最大 32 KiB，仅接受 CNY/USD 和有限长度的十进制字符串；
+- 失败时可以返回已明确标记为 `stale` 的最后成功快照；
+- 401/403、429、网络和无效响应保持不同错误原因。
+
+### Loopback RPC adapter
+
+`src/internal/account-rpc.mjs` 在 `/dsh-deepseek-account` 注册唯一的 `read` endpoint，只接受可选布尔值 `force`。authority 必须保持 `loopback`。不要在这里增加通用代理、任意 URL、任意 header 或原始响应透传。
+
+### Browser module
+
+`client.js` 是 Harness 客户端加载器模块。它负责：
+
+- 识别当前会话 Provider；
+- 调用 DeepSeek、Grok 或 Codex 的本地 RPC；
+- 再次校验所有跨 RPC 数据；
+- 注册侧栏与设置页；
+- 注册中英文文案和局部样式。
+
+客户端只依赖投影后的账户状态。`scripts/build.mjs` 会复制确定性产物，并拒绝包含 `DEEPSEEK_API_KEY`、credential resolution 或 Authorization header 特征的客户端文件。
+
+### Optional Provider adapters
+
+Grok 的 `/grok-auth` 和 Codex 的 `/dsh-codex` 是外部、可选 seam。它们不是本插件拥有的接口，因此：
+
+- 调用失败必须降级为 `unavailable`；
+- 只读取显示所需的重置窗口，不保留用量百分比或其他账户数据；
+- 不以 npm 依赖或 Host 注入的方式接管对应插件；
+- 外部 RPC 变化时，通过投影函数和契约测试适配，不能让变化扩散到 UI。
+
+## Provider selection
+
+当前映射是：
+
+- `llm-grok`、`grok` → Grok；
+- `dsh-codex` → Codex；
+- 其他值（包括未知自定义 Provider）→ DeepSeek。
+
+改变默认回退属于用户可见兼容性变化，必须先开 Issue，并同步 README、界面文案、测试、CHANGELOG 和发布说明。
+
+## Test surface
+
+测试应从模块接口验证行为：
+
+| Test | Interface covered |
+| --- | --- |
+| `account-balance.test.mjs` | 上游投影、凭据缺失、缓存/并发和旧快照 |
+| `account-rpc.test.mjs` | loopback 权限、endpoint 与请求 schema |
+| `client-bundle.test.mjs` | manifest、客户端凭据隔离、Provider 映射、可选 RPC 和 UI 注册 |
+
+新增行为优先扩展相应接口测试。只有确实存在第二个 adapter 时才新增 seam；不要为假设中的未来实现扩大公共接口。
+
+## Package layout
+
+```text
+src/host/           Host 入口
+src/internal/       Host 内部深模块和 RPC adapter
+client.js           浏览器模块源文件
+scripts/build.mjs   确定性构建和凭据边界检查
+test/               接口测试
+dist/               生成物，不提交
+docs/releases/      固定版本的双语发布说明
+```

package/docs/MAINTAINING.md

@@ -0,0 +1,100 @@
+# Maintaining
+
+本文面向拥有仓库分诊或发布权限的维护者。贡献者开发流程见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
+
+## Issue triage
+
+1. 先确认问题属于本插件，而不是 DeepSeek 官方账户/付款、Harness 平台或 Grok/Codex 插件。
+2. 删除或隐藏意外公开的凭据、Cookie、账户和付款资料；不要在 Issue 中引用或复制。
+3. 记录插件、Harness、Node.js、操作系统、当前 Provider 和可选插件版本。
+4. 用最小的本地 adapter/fixture 复现，不要求报告者提供真实 Key。
+5. 将真实账户验证与自动化验证分开记录，避免把构建或隔离测试描述成端到端成功。
+
+## Compatibility policy
+
+- `package.json#engines` 和 peer dependency 范围是支持矩阵的来源。
+- Harness 或可选 Provider RPC 升级前，先用公开接口和脱敏 fixture 验证，再调整版本范围。
+- 不认识的 Provider 当前回退 DeepSeek；改变它需要明确的兼容性说明。
+- Grok/Codex 必须保持可选，它们缺失时 DeepSeek 仍可工作。
+- 稳定版只承诺最新版本获得安全修复；破坏性变化需要在 README、CHANGELOG 和发布说明中突出。
+
+## Pull Request review
+
+合并前确认：
+
+- 改动位于正确模块，Host 凭据逻辑没有进入客户端；
+- RPC 输入输出仍然是最小投影，loopback authority 未被放宽；
+- 错误、缺失可选插件和旧快照路径有聚焦测试；
+- 中英文用户文档和界面文案同步；
+- `npm run check` 与 `npm run pack:check` 通过；
+- diff 不包含 `dist/`、tarball、日志、真实响应或秘密信息；
+- 分支以 `yukiryou/` 开头，并通过受保护的 `main` 合并。
+
+## Release preparation
+
+每个版本只发布 `main` 上一个明确的提交和该工作流生成的固定 tarball。
+
+1. 在发布 PR 中更新 `package.json`、`package-lock.json`、`CHANGELOG.md` 和 `docs/releases/v<version>.md`。
+2. 发布说明以中文摘要、精确安装命令、分组变更和兼容性/验证限制开头；完整英文放入 `<details>`。
+3. 在干净依赖环境运行：
+
+   ```sh
+   npm ci --ignore-scripts --omit=peer
+   npm run check
+   npm run pack:check
+   ```
+
+4. 合并到 `main`，记下完整 commit SHA，并等待 CI 全部通过。
+5. 确认 npm 上不存在目标版本；版本一旦存在不可覆盖，也不要重建“同版本修正版”。
+6. 确认 npm Trusted Publisher 仍绑定本仓库的 `.github/workflows/release.yml`，GitHub `npm-release` environment 的保护规则仍生效。
+
+## Trusted release
+
+在 GitHub Actions 手动运行 `Release` workflow：
+
+- Branch：`main`
+- `version`：不带 `v` 的精确版本，必须与 `package.json` 相同
+- `publish`：只有准备正式发布时才选择 `true`
+
+`publish: true` 的同一次 workflow run 会：
+
+1. 验证 `main` 和版本；
+2. 测试、构建并只打包一次候选 tarball；
+3. 保存 SHA-256、SRI 和文件清单；
+4. 在受保护环境中冻结 tag 和草稿 Release；
+5. 通过 npm Trusted Publisher OIDC 发布；
+6. 等待 Registry 可见，下载并逐字节比较 tarball；
+7. 在隔离目录安装并执行 `npm audit signatures`；
+8. 公开已经验证的 GitHub Release。
+
+常规版本不得使用本地 `npm publish`、长期 npm token 或 `NPM_BOOTSTRAP_TOKEN`。bootstrap token 只属于首个包版本的历史兼容路径。
+
+## Post-release verification
+
+在一个全新临时目录中核对 Registry 元数据和可安装性：
+
+```sh
+npm view dsh-deepseek-account@<version> version dist.integrity dist.tarball
+npm pack dsh-deepseek-account@<version>
+npm install --ignore-scripts --legacy-peer-deps --no-audit --no-fund dsh-deepseek-account@<version>
+node --input-type=module -e 'import("dsh-deepseek-account").then((m) => console.log(m.name))'
+```
+
+同时确认 tag、GitHub Release asset、workflow provenance 和 npm 包指向同一版本。不要在包含真实用户配置的 profile 中做发布 smoke test。
+
+Registry 发布后短时间内查询不到版本通常是传播延迟。先等待并重新读取；若 workflow 的验证 job 失败，优先重跑同一次 workflow 中失败的 job，复用原候选工件。绝不能为同一个不可变版本再次发布不同 tarball。
+
+## Release evidence
+
+在 Release 或维护记录中保留：
+
+- `main` commit SHA 和 tag；
+- workflow run；
+- 候选 tarball SHA-256/SRI 与文件清单；
+- Registry tarball 的逐字节比较；
+- npm signature/provenance 结果；
+- GitHub Release asset；
+- 隔离安装/import 结果；
+- 明确未执行的真实账户、浏览器和付款路径。
+
+发布成功不等于真实账户验收。真实余额查询只能在维护者自有测试账户、最小权限和无秘密输出的前提下单独执行；付款不属于自动化发布验证。

package/docs/releases/v0.1.3.md

@@ -0,0 +1,58 @@
+## 中文
+
+`0.1.3` 修复 Provider 切换时侧栏可能消失且无法恢复的问题，并补全社区维护文档与贡献入口。
+
+### 修复
+
+- 从已有额度数据的 Provider 切换到 DeepSeek、未知 Provider 或 Codex 时，不再用上一个 Provider 的状态结构渲染新卡片。
+- Provider 已切换但新数据尚未返回时，侧栏保持挂载并显示新 Provider 的加载状态。
+- 未知自定义 Provider 继续回退 DeepSeek；Grok 和 Codex 的登录、模型、设置、RPC 及其他能力均未修改。
+
+### 社区维护
+
+- 重构中英文 README，集中说明能力矩阵、安装、常见状态、安全边界和验证限制。
+- 新增架构与维护手册、支持和行为准则，以及结构化 Issue/PR 模板。
+- 发布继续限定为 `main` 上固定提交，由仓库绑定的 GitHub Actions Trusted Publisher 工作流通过 OIDC 执行。
+
+### 验证限制
+
+- 自动化验证覆盖 Provider 切换瞬时状态、缺失可选插件、响应投影、跨平台构建和打包。
+- 未执行真实账户余额查询、真实 Harness 浏览器切换或实际充值；插件不会代替用户登录或付款。
+
+安装：
+
+```sh
+dsh plugin --profile web add dsh-deepseek-account@0.1.3
+dsh web
+```
+
+<details>
+<summary>English release notes</summary>
+
+`0.1.3` fixes a sidebar entry that could disappear permanently during Provider switches and completes the project's community-maintenance documentation and contribution paths.
+
+### Fixes
+
+- Stops rendering a newly selected DeepSeek, unknown-Provider fallback, or Codex card with the previous Provider's incompatible state shape.
+- Keeps the sidebar mounted in the new Provider's loading state until its data arrives.
+- Unknown custom Providers continue to fall back to DeepSeek. Grok/Codex authentication, models, settings, RPCs, and other behavior remain unchanged.
+
+### Community maintenance
+
+- Refactors the Chinese and English READMEs around the capability matrix, installation, common states, security boundaries, and verification limits.
+- Adds architecture and maintainer guides, support and conduct policies, and structured issue/pull-request templates.
+- Keeps publication restricted to a fixed commit on `main` through the repository-bound GitHub Actions Trusted Publisher workflow using OIDC.
+
+### Verification limits
+
+- Automated checks cover transient Provider-switch state, absent optional plugins, response projection, cross-platform builds, and packaging.
+- No real-account balance query, live Harness browser switch, or actual top-up was performed. The plugin never signs in or pays on a user's behalf.
+
+Install:
+
+```sh
+dsh plugin --profile web add dsh-deepseek-account@0.1.3
+dsh web
+```
+
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-deepseek-account",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "DeepSeek account balance and official top-up entry for DeepSeek Harness",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,9 @@
     "README.en.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
     "SECURITY.md",
+    "SUPPORT.md",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
   ],