dsh-keys-manager 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BT.Wood(Tang Bo Hao)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# DSH Keys Manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm downloads](https://img.shields.io/npm/dm/dsh-keys-manager)](https://www.npmjs.com/package/dsh-keys-manager)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](https://www.npmjs.com/package/dsh-keys-manager)
+[![DSH](https://img.shields.io/badge/DSH-%5E0.2.1--rc.2-0969DA)](https://www.npmjs.com/package/@deepseek-ai/dsh-llm)
+
+**English** | [简体中文](README.zh-CN.md)
+
+Docs: [Development](docs/development.md) · [Release](docs/release.md) · [Known limits](docs/known-limits.md) — Documentation in Chinese: [开发](docs/development.zh-CN.md) · [发布](docs/release.zh-CN.md) · [已知限制](docs/known-limits.zh-CN.md)
+
+A DeepSeek Harness plugin that turns one provider API key into a managed pool.
+It extends the Models page rather than replacing it: providers, models, and the
+model picker stay where they are; only the API-key source moves behind the
+manager.
+
+## Features
+
+- Several keys per provider, each with an alias and health state.
+- One key pinned to a session, with round-robin selection for new sessions.
+- Bounded retry on the same key, then automatic failover to another key.
+- Exponential cooldown recovery, capped at seven days.
+- A search-driven Keys Manager page on the plugin's own detail page.
+- A "managed by Keys Manager" badge inside the existing Models provider cards.
+- Extra built-in providers installed as ordinary `llm-pi-ai` routes.
+
+### Extra providers
+
+`src/providers.ts` contains a curated catalog of 34 extra providers (21 from
+the original catalog plus 13 added in this release, for example SiliconFlow,
+Zhipu coding plan, Cline Pass, Ollama Cloud, and Alibaba Token Plan (CN)),
+derived from
+[oh-my-pi](https://github.com/can1357/oh-my-pi)'s provider catalog (MIT).
+An extra id is added only when the shipped DSH catalog does not already
+declare that route id (for example, `meta` and `typesafe` are not
+duplicated); same-endpoint providers with distinct credential identities
+are kept by design.
+
+## Quick start
+
+### Install — published package
+
+```sh
+dsh plugin --profile web add dsh-keys-manager
+```
+
+### Install — local checkout
+
+```sh
+git clone https://github.com/btspoony/dsh-keys-manager
+cd dsh-keys-manager
+pnpm i
+dsh plugin --profile web link .
+```
+
+Refresh the Web page after installing so the browser half is fetched.
+
+## Usage
+
+Open **Plugins → Keys Manager → View** (rendered as
+`Plugins → 密钥管理 → 查看` in the Chinese locale). The manager renders on the
+plugin's detail page, between its description and its included rows, matching
+the shipped plugin configuration cards.
+
+1. Search for a provider. Existing DSH providers appear first; the plugin also
+   ships the curated extra catalog described above.
+2. Adopt a provider. For an existing provider the manager imports the
+   currently resolved credential, writes a broker reference into the provider
+   profile, and leaves the original key in the credential store so release can
+   restore it.
+3. Add more keys with an alias. Every key is stored in the Harness credential
+   store under its own reference; the manager state document never contains a
+   key literal.
+4. Manage a key from the three-dot menu: rename, pause/resume, delete. A key
+   row shows status, last use, and the recovery time while cooling.
+5. Tune retry count (1–3), base cooldown, and recovery grace in the settings
+   card.
+
+### Selection and failure policy
+
+- **Sticky session**: the first request of a session selects a key and binds
+  it for that session/provider pair. Later requests reuse it.
+- **Round robin**: a new session advances the provider cursor and takes the
+  next healthy key.
+- **Retry**: a failing request is retried on the same key `retryCount` times.
+- **Switch**: after the retry budget is spent, the failing key is marked
+  cooling, and the session is rebound to another healthy key.
+- **Cooldown**: the first failure cools a key for `baseCooldownMs`. A failure
+  while cooling, or within `recoveryGraceMs` after recovery, doubles the
+  next cooldown. A long healthy gap resets the escalation. The hard cap is
+  seven days.
+- **Recovery**: the key is automatically selectable again when its cooldown
+  expires; no manual reset is required.
+- **Delegation**: request-shaped failures such as
+  `CONTEXT_WINDOW_EXCEEDED` and cancellation never cool a key. When no
+  alternate key exists, the manager delegates to the composition's normal
+  retry/fallback policy.
+
+## Configuration & data
+
+Manager metadata lives at:
+
+```text
+$DSH_HOME/keys-manager/state.json
+```
+
+with owner-only permissions. It contains aliases, credential references,
+health counters, session bindings, and provider adoption facts. API key
+literals live only in the Harness credential store. The file is written
+atomically through a temporary file and a rename.
+
+Each managed provider profile points its `apiKeyEnv` at a broker reference
+such as `KEYSMGR_ZAI_CODING_CN_3FA2C1`. The Host credential layer answers that
+reference per request with the session's selected key. The Models page sees
+the profile as configured; writing directly to the broker reference is
+refused with a pointer to the manager.
+
+### OAuth2 extension point
+
+The state shape already distinguishes `kind: "api-key"` from `kind: "oauth"`
+and keeps a nullable `oauth` object beside the credential reference. A future
+account flow can add records under `keys-manager/<provider>/<key>` without
+rewriting existing rows. Providers whose only authentication is OAuth are
+reported as unsupported in this version rather than being treated as API-key
+providers.
+
+## Provider classification
+
+Every provider card carries its origin:
+
+- **DSH built-in** (`DSH 内置`) — a route from the shipped DSH pi-ai catalog.
+- **Plugin built-in** (`插件内置`) — a route from this plugin's extra catalog
+  in `src/providers.ts`.
+- **Custom** (`自定义`) — a hand-declared route in the active profile.
+
+The following DSH built-ins are explicitly outside single-key pool management:
+
+| Provider | Why |
+|---|---|
+| `amazon-bedrock` | AWS credential chain (profile, IAM keys, ECS/IRSA/EC2), not one API key |
+| `cloudflare-ai-gateway` | API key plus a Cloudflare account ID and gateway ID |
+| `cloudflare-workers-ai` | API key plus a Cloudflare account ID |
+| `openai-codex` | ChatGPT OAuth sign-in only; no API-key credential |
+
+All other DSH catalog routes expose an API-key credential. Providers that also
+support OAuth (Anthropic, GitHub Copilot, Kimi, OpenRouter, xAI, Radius) remain
+manageable through their API-key path; OAuth accounts are tracked separately
+in the roadmap issue.
+
+## Documentation
+
+| Doc | Content |
+|---|---|
+| [Development](docs/development.md) | build and dev workflow, repository layout |
+| [Release](docs/release.md) | CI checks and the npm release flow |
+| [Known limits](docs/known-limits.md) | current design boundaries, including deferred providers |
+
+Chinese versions: [README.zh-CN.md](README.zh-CN.md) and the `*.zh-CN.md`
+files in `docs/`. Current design boundaries at a glance:
+[Known limits](docs/known-limits.md).
+
+## License
+
+Released under the [MIT License](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# DSH Keys Manager
+
+[![npm downloads](https://img.shields.io/npm/dm/dsh-keys-manager)](https://www.npmjs.com/package/dsh-keys-manager)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](https://www.npmjs.com/package/dsh-keys-manager)
+[![DSH](https://img.shields.io/badge/DSH-%5E0.2.1--rc.2-0969DA)](https://www.npmjs.com/package/@deepseek-ai/dsh-llm)
+
+[English](README.md) | **简体中文**
+
+文档：[开发](docs/development.zh-CN.md) · [发布](docs/release.zh-CN.md) · [已知限制](docs/known-limits.zh-CN.md) — English docs: [Development](docs/development.md) · [Release](docs/release.md) · [Known limits](docs/known-limits.md)
+
+DSH Keys Manager 是一个 DeepSeek Harness 插件，把一个提供商 API key 变成托管密钥池。它扩展而非替换 Models 页面：提供商、模型和模型选择器都在原处，只有 API key 来源移到管理器之后。
+
+## 特性
+
+- 每个提供商可配多把 key，每把有别名和健康状态。
+- 一把 key 粘滞绑定到会话，新会话按轮询选择。
+- 同一把 key 上有界重试，预算耗尽后自动切换到另一把 key。
+- 指数升级的冷却恢复，上限七天。
+- 插件详情页上提供可搜索的 Keys Manager 页面。
+- 既有 Models 提供商卡片内出现"由 Keys Manager 托管"徽标。
+- 额外内置提供商以普通 `llm-pi-ai` 路由安装。
+
+### 额外提供商
+
+`src/providers.ts` 收录 34 个精选提供商（原有 21 个加本次发布新增 13 个，例如 SiliconFlow、智谱编码套餐、Cline Pass、Ollama Cloud、Alibaba Token Plan (CN)），目录源自 [oh-my-pi](https://github.com/can1357/oh-my-pi)（MIT）。只有当随附 DSH 目录尚未声明该 route id 时才会新增条目（例如 `meta`、`typesafe` 不会重复提供）；与既有端点共享 base URL、但凭据身份不同的提供商会按设计保留。
+
+## 快速开始
+
+### 安装 —— 已发布包
+
+```sh
+dsh plugin --profile web add dsh-keys-manager
+```
+
+### 安装 —— 本地检出
+
+```sh
+git clone https://github.com/btspoony/dsh-keys-manager
+cd dsh-keys-manager
+pnpm i
+dsh plugin --profile web link .
+```
+
+安装完成后刷新 Web 页面，让浏览器侧代码被取到。
+
+## 使用
+
+打开 **Plugins → 密钥管理 → 查看**（英文 locale 下显示为 `Plugins → Keys Manager → View`）。管理器渲染在插件详情页上，位于描述与包含行之间，与随附的插件配置卡片一致。
+
+1. 搜索提供商。既有 DSH 提供商排在前面；插件同时附带上述精选扩展目录。
+2. 接管提供商。对既有提供商，管理器导入当前解析出的凭据、把 broker 引用写进提供商档案，并把原 key 留在凭据存储里，以便停止接管时还原。
+3. 用别名添加更多 key。每把 key 都以自己的引用存进 Harness 凭据存储；管理器状态文档从不包含 key 字面量。
+4. 在三点菜单中管理 key：重命名、暂停/恢复、删除。key 行显示状态、最近使用，以及冷却中的恢复时间。
+5. 在设置卡片中调整重试次数（1–3）、基础冷却与恢复宽限。
+
+### 选择与故障策略
+
+- **会话粘滞**：会话的首次请求选出一把 key 并为该会话/提供商对绑定，后续请求复用。
+- **轮询**：新会话推进提供商游标，取下一把健康 key。
+- **重试**：失败请求在同一把 key 上重试 `retryCount` 次。
+- **切换**：重试预算耗尽后，失败 key 标记为冷却，会话重新绑定到另一把健康 key。
+- **冷却**：首次失败使 key 冷却 `baseCooldownMs`。冷却中再次失败，或恢复后 `recoveryGraceMs` 内失败，下一次冷却翻倍；长时间健康运行会重置升级。硬上限七天。
+- **恢复**：冷却到期后 key 自动恢复可选，无需手动重置。
+- **委托**：请求形态的失败（如 `CONTEXT_WINDOW_EXCEEDED`）与取消从不冷却 key。没有备用 key 时，管理器委托给组合层常规的重试/回退策略。
+
+## 配置与数据
+
+管理器元数据位于：
+
+```text
+$DSH_HOME/keys-manager/state.json
+```
+
+权限为仅属主可读写。内容包含别名、凭据引用、健康计数、会话绑定和提供商接管事实。API key 字面量只存在于 Harness 凭据存储。文件通过临时文件加重命名原子写入。
+
+每个受管提供商档案的 `apiKeyEnv` 指向 broker 引用，例如 `KEYSMGR_ZAI_CODING_CN_3FA2C1`。Host 凭据层按请求用该会话选中的 key 应答这个引用。Models 页面视该档案为已配置；直接写 broker 引用会被拒绝并指向管理器。
+
+### OAuth2 扩展点
+
+状态结构已区分 `kind: "api-key"` 与 `kind: "oauth"`，并在凭据引用旁保留可空的 `oauth` 对象。未来的账号流程可以在 `keys-manager/<provider>/<key>` 下追加记录而不改写既有行。本版本中，只有 OAuth 认证的提供商会按不支持上报，而不会被当作 API key 提供商处理。
+
+## 提供商分类
+
+每个提供商卡片标注来源：
+
+- **DSH 内置**（英文界面显示 `DSH built-in`）——随附 DSH pi-ai 目录的路由。
+- **插件内置**（`Plugin built-in`）——来自本插件 `src/providers.ts` 扩展目录的路由。
+- **自定义**（`Custom`）——当前档案中手工声明的路由。
+
+以下 DSH 内置提供商明确不在单 key 池管理范围内：
+
+| 提供商 | 原因 |
+|---|---|
+| `amazon-bedrock` | AWS 凭据链（profile、IAM 密钥、ECS/IRSA/EC2），不是单一 API key |
+| `cloudflare-ai-gateway` | API key 之外还需 Cloudflare 账号 ID 与网关 ID |
+| `cloudflare-workers-ai` | API key 之外还需 Cloudflare 账号 ID |
+| `openai-codex` | 仅支持 ChatGPT OAuth 登录，无 API key 凭据 |
+
+其余 DSH 目录路由都提供 API key 凭据。同时支持 OAuth 的提供商（Anthropic、GitHub Copilot、Kimi、OpenRouter、xAI、Radius）仍可经其 API key 路径管理；OAuth 账号在路线图 issue 中单独跟踪。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [开发](docs/development.zh-CN.md) | 构建与开发工作流、仓库布局 |
+| [发布](docs/release.zh-CN.md) | CI 检查与 npm 发布流程 |
+| [已知限制](docs/known-limits.zh-CN.md) | 当前设计边界，含延后提供商 |
+
+英文版本：[README.md](README.md) 及 `docs/` 下的 `*.md`。当前设计边界速览：[已知限制](docs/known-limits.zh-CN.md)。
+
+## 许可证
+
+基于 [MIT 许可证](LICENSE) 发布。

package/bundle/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Mounts the Keys Manager Host plugin. The Client half is declared by
+# package.json#dsh.client and is served from lib/client.js.
+- insert:
+    - id: dsh-keys-manager
+      name: 'dsh-keys-manager'

package/icon.svg

@@ -0,0 +1,12 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="dsh-keys-manager-icon-bg" x1="6" y1="4" x2="30" y2="33" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#5B9BFF"/>
+      <stop offset="1" stop-color="#315BE6"/>
+    </linearGradient>
+  </defs>
+  <rect x="2.5" y="2.5" width="31" height="31" rx="9" fill="url(#dsh-keys-manager-icon-bg)"/>
+  <circle cx="18" cy="13.1" r="4.1" stroke="#F9FAFB" stroke-width="2.2"/>
+  <path d="M18 17.2V26.6" stroke="#F9FAFB" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M18 21.8H22.2M18 24.7H21.2" stroke="#F9FAFB" stroke-width="2.2" stroke-linecap="round"/>
+</svg>

package/lib/client/format.d.ts

@@ -0,0 +1,8 @@
+/** Exact millisecond/minute conversions used by the policy form. */
+export declare function cooldownMinutes(ms: number): number;
+/** Convert a user-entered base cooldown to milliseconds without rounding. */
+export declare function cooldownMs(minutes: number): number;
+/** Convert a user-entered recovery grace to minutes. */
+export declare function graceMinutes(ms: number): number;
+/** Convert a user-entered recovery grace to milliseconds without rounding. */
+export declare function graceMs(minutes: number): number;

package/lib/client/index.d.ts

@@ -0,0 +1,3 @@
+import type { ClientContext } from './types';
+export declare const inject: string[];
+export declare function apply(ctx: ClientContext): void;

package/lib/client/locales.d.ts

@@ -0,0 +1,4 @@
+/** Locale dictionaries for the Keys Manager plugin surface. */
+import type { LocaleDicts } from './types';
+/** Dictionaries registered under the plugin's locale namespace. */
+export declare const LOCALE_DICTS: LocaleDicts;

package/lib/client/runtime.d.ts

@@ -0,0 +1,21 @@
+/** React runtime context and hooks shared by the Client plugin body. */
+import React from 'react';
+import type { ClientContext, ClientSnapshot, Runtime } from './types';
+/** Context installed by every wrapped slot entry. */
+export declare const RuntimeContext: React.Context<Runtime | null>;
+/** Read the plugin runtime; a component outside the wrapper is a wiring bug. */
+export declare function useRuntime(): Runtime;
+/** Translate through the plugin locale namespace, re-rendering on locale changes. */
+export declare function useT(): (key: string, params?: Record<string, string | number>) => string;
+/** Active locale id, used by date/time formatting. */
+export declare function useLocaleId(): string;
+/** Subscribe to the shared manager store. */
+export declare function useStore(): ClientSnapshot;
+/** Current wall clock from the store's 30-second tick. */
+export declare function useNow(): number;
+/** Install the plugin stylesheet once per mounted surface. */
+export declare function useStyles(): void;
+/** Wrap a slot component with the runtime provider and the stylesheet. */
+export declare function wrapComponent(Component: React.ComponentType<any>, runtime: Runtime): React.ComponentType<any>;
+/** Re-export for callers that want the raw context value. */
+export type { ClientContext, Runtime };

package/lib/client/store.d.ts

@@ -0,0 +1,4 @@
+/** State store shared by the plugin-detail card and the Models badges. */
+import type { ClientContext, ClientStore } from './types';
+/** Create the store bound to one connected Client context. */
+export declare function createStore(ctx: ClientContext): ClientStore;

package/lib/client/styles.d.ts

@@ -0,0 +1,2 @@
+/** Stylesheet owned by the Keys Manager client surface. */
+export declare const CSS = "\n.km-page{max-width:920px;margin:0 auto;padding:0 0 8px;color:var(--dsw-alias-label-primary);font-size:13.5px;line-height:1.5}\n.km-embedded-head{display:flex;align-items:flex-start;justify-content:space-between;gap:16px;margin:0 0 16px}\n.km-summary{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin:0 0 16px;flex:1;min-width:0}\n.km-embedded-head .km-summary{margin:0}\n.km-embedded-actions{display:flex;gap:8px;flex-shrink:0;padding-top:2px}\n.km-summary-line{color:var(--dsw-alias-label-secondary);font-size:12.5px;line-height:1.5}\n.km-stat{display:flex;flex-direction:column;gap:2px;padding:11px 14px;border:1px solid var(--dsw-alias-border-l1);border-radius:10px;background:var(--dsw-alias-bg-layer-1)}\n.km-stat strong{font-size:19px;line-height:1.15;font-weight:650;font-variant-numeric:tabular-nums}\n.km-stat span{color:var(--dsw-alias-label-secondary);font-size:12px}\n.km-search{position:relative;display:flex;align-items:center;margin:0 0 20px}\n.km-search-icon{position:absolute;left:12px;color:var(--dsw-alias-label-secondary);pointer-events:none}\n.km-search-input{width:100%;box-sizing:border-box;padding:10px 38px 10px 36px;border:1px solid var(--dsw-alias-border-l1);border-radius:10px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;outline:none}\n.km-search-input:focus{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 2px color-mix(in srgb,var(--dsw-alias-state-business-primary) 20%,transparent)}\n.km-search-clear{position:absolute;right:8px;display:inline-flex;align-items:center;justify-content:center;width:26px;height:26px;border:0;border-radius:6px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer}\n.km-search-clear:hover{background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary)}\n.km-section{margin:0 0 22px}\n.km-section-head{display:flex;align-items:baseline;gap:8px;margin:0 0 9px}\n.km-section-title{font-size:14px;font-weight:650;margin:0;letter-spacing:.01em}\n.km-section-count{font-size:12px;color:var(--dsw-alias-label-secondary)}\n.km-provider-list{display:flex;flex-direction:column;gap:8px}\n.km-show-more{display:flex;justify-content:center;padding:8px 0 0}\n.km-card{border:1px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-alias-bg-layer-1);overflow:hidden}\n.km-provider-managed{border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 26%,var(--dsw-alias-border-l1))}\n.km-provider-open{overflow:visible}\n.km-provider-head{display:flex;align-items:center;gap:12px;width:100%;padding:12px 14px;border:0;background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer}\n.km-provider-head:hover{background:color-mix(in srgb,var(--dsw-alias-label-primary) 3%,transparent)}\n.km-avatar{display:inline-flex;align-items:center;justify-content:center;width:32px;height:32px;flex:0 0 32px;border-radius:9px;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);font-weight:650;font-size:13px;color:var(--dsw-alias-label-secondary)}\n.km-provider-main{display:flex;flex-direction:column;gap:3px;min-width:0;flex:1}\n.km-provider-title-line{display:flex;align-items:center;gap:6px;flex-wrap:wrap;min-width:0}\n.km-provider-name{font-weight:650;font-size:13.5px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:360px}\n.km-provider-meta{display:flex;align-items:center;gap:7px;flex-wrap:wrap;color:var(--dsw-alias-label-secondary);font-size:11.5px;min-width:0}\n.km-provider-side{display:flex;align-items:center;gap:9px;flex-shrink:0}\n.km-count{font-size:11.5px;color:var(--dsw-alias-label-secondary);white-space:nowrap}\n.km-chevron{color:var(--dsw-alias-label-secondary);transition:transform .16s ease}\n.km-chevron-open{transform:rotate(180deg)}\n.km-provider-body{border-top:1px solid var(--dsw-alias-border-l1);padding:13px 14px 14px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-2) 40%,transparent)}\n.km-adopt{display:flex;flex-direction:column;gap:12px}\n.km-adopt-copy{display:flex;flex-direction:column;gap:5px;color:var(--dsw-alias-label-secondary);font-size:12.5px}\n.km-adopt-title{color:var(--dsw-alias-label-primary);font-size:12.5px}\n.km-adopt-actions{display:flex;gap:8px;align-items:center}\n.km-meta-line{display:flex;gap:6px;align-items:baseline;flex-wrap:wrap;font-size:11.5px}\n.km-managed-body{display:flex;flex-direction:column;gap:10px}\n.km-managed-toolbar{display:flex;justify-content:space-between;align-items:flex-start;gap:12px;flex-wrap:wrap}\n.km-managed-summary{display:flex;flex-direction:column;gap:2px;min-width:0;font-size:11.5px}\n.km-managed-actions{display:flex;gap:6px;align-items:center;flex-shrink:0}\n.km-keys{display:flex;flex-direction:column;border:1px solid var(--dsw-alias-border-l1);border-radius:9px;background:var(--dsw-alias-bg-layer-1);overflow:visible}\n.km-key-row{position:relative;display:grid;grid-template-columns:minmax(0,1.35fr) minmax(150px,.8fr) minmax(150px,.9fr) 32px;gap:10px;align-items:center;padding:10px 11px;border-top:1px solid var(--dsw-alias-border-l1)}\n.km-key-row:first-child{border-top:0}\n.km-key-identity{min-width:0;display:flex;flex-direction:column;gap:2px}\n.km-key-alias-line{display:flex;align-items:center;gap:6px;min-width:0}\n.km-key-alias{font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:220px}\n.km-key-sub{display:flex;align-items:center;gap:8px;font-size:11px;color:var(--dsw-alias-label-secondary);flex-wrap:wrap}\n.km-key-status{display:flex;flex-direction:column;gap:2px;align-items:flex-start}\n.km-key-last{display:flex;flex-direction:column;gap:2px;min-width:0}\n.km-key-time{font-size:11.5px;color:var(--dsw-alias-label-secondary);font-variant-numeric:tabular-nums}\n.km-key-time.km-warn{color:var(--dsw-alias-state-warn-primary)}\n.km-key-actions{position:relative;display:flex;justify-content:flex-end}\n.km-status{display:inline-flex;align-items:center;gap:5px;padding:2px 7px;border-radius:999px;border:1px solid var(--dsw-alias-border-l1);background:var(--dsw-alias-bg-layer-2);font-size:11px;white-space:nowrap;color:var(--dsw-alias-label-secondary)}\n.km-status-success{color:var(--dsw-alias-state-success-primary);border-color:color-mix(in srgb,var(--dsw-alias-state-success-primary) 26%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-success-primary) 8%,transparent)}\n.km-status-warn{color:var(--dsw-alias-state-warn-primary);border-color:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 30%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 8%,transparent)}\n.km-status-error{color:var(--dsw-alias-state-error-primary);border-color:color-mix(in srgb,var(--dsw-alias-state-error-primary) 30%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 8%,transparent)}\n.km-status-idle{color:var(--dsw-alias-state-idle-primary)}\n.km-dot{display:inline-block;width:6px;height:6px;border-radius:50%;flex:0 0 6px;background:var(--dsw-alias-state-idle-primary)}\n.km-dot-success{background:var(--dsw-alias-state-success-primary)}\n.km-dot-warn{background:var(--dsw-alias-state-warn-primary)}\n.km-dot-error{background:var(--dsw-alias-state-error-primary)}\n.km-dot-idle{background:var(--dsw-alias-state-idle-primary)}\n.km-dot-sep{color:var(--dsw-alias-label-secondary)}\n.km-tag{display:inline-flex;align-items:center;padding:1px 6px;border-radius:5px;font-size:10.5px;line-height:1.45;color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);white-space:nowrap}\n.km-tag-accent{color:var(--dsw-alias-state-business-primary);border-color:color-mix(in srgb,var(--dsw-alias-state-business-primary) 34%,var(--dsw-alias-border-l1));background:var(--dsw-alias-state-business-tertiary)}\n.km-tag-warn{color:var(--dsw-alias-state-warn-primary);border-color:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 30%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 8%,transparent)}\n.km-icon-btn{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border:1px solid transparent;border-radius:7px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;flex:0 0 auto}\n.km-icon-btn:hover{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-border-l1);color:var(--dsw-alias-label-primary)}\n.km-icon-btn:disabled{opacity:.5;cursor:default}\n.km-menu{position:absolute;top:32px;right:0;z-index:20;min-width:138px;padding:4px;border:1px solid var(--dsw-alias-border-l2);border-radius:9px;background:var(--dsw-alias-bg-overlay);box-shadow:0 7px 22px color-mix(in srgb,var(--dsw-alias-label-primary) 14%,transparent)}\n.km-menu-item{display:flex;align-items:center;gap:8px;width:100%;padding:7px 9px;border:0;border-radius:6px;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:12.5px;text-align:left;cursor:pointer}\n.km-menu-item:hover{background:var(--dsw-alias-bg-layer-2)}\n.km-menu-item:disabled{opacity:.5;cursor:default}\n.km-menu-danger{color:var(--dsw-alias-state-error-primary)}\n.km-menu-sep{height:1px;margin:4px 2px;background:var(--dsw-alias-border-l1)}\n.km-btn{display:inline-flex;align-items:center;justify-content:center;gap:6px;padding:7px 11px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-size:12.5px;font-weight:550;line-height:1.2;cursor:pointer;white-space:nowrap;transition:opacity .15s ease,background .15s ease}\n.km-btn:hover{background:var(--dsw-alias-bg-layer-2)}\n.km-btn:disabled{opacity:.5;cursor:default}\n.km-btn-primary{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-base);border-color:transparent}\n.km-btn-primary:hover{opacity:.9;background:var(--dsw-alias-label-primary)}\n.km-btn-ghost{background:transparent;border-color:transparent;color:var(--dsw-alias-label-secondary)}\n.km-btn-ghost:hover{background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary)}\n.km-btn-danger{background:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-bg-base);border-color:transparent}\n.km-btn-danger:hover{opacity:.9;background:var(--dsw-alias-state-error-primary)}\n.km-btn-small{padding:5px 8px;font-size:12px;border-radius:7px}\n.km-input{width:100%;box-sizing:border-box;padding:8px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;outline:none}\n.km-input:focus{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 2px color-mix(in srgb,var(--dsw-alias-state-business-primary) 18%,transparent)}\n.km-input:disabled{opacity:.6}\nselect.km-input{appearance:auto}\n.km-form{display:flex;flex-direction:column;gap:10px;padding:12px;border:1px solid var(--dsw-alias-border-l1);border-radius:9px;background:var(--dsw-alias-bg-layer-1)}\n.km-form-lead{display:flex;flex-direction:column;gap:2px}\n.km-form-title{font-weight:650;font-size:12.5px}\n.km-form-grid{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.4fr);gap:10px}\n.km-field{display:flex;flex-direction:column;gap:5px;min-width:0}\n.km-field-wide{min-width:0}\n.km-field-label{font-size:11.5px;font-weight:550;color:var(--dsw-alias-label-secondary)}\n.km-field-hint{font-size:11px;color:var(--dsw-alias-label-secondary);line-height:1.45}\n.km-secret{position:relative;display:flex;align-items:center}\n.km-secret-input{padding-right:38px}\n.km-secret-toggle{position:absolute;right:4px;display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border:0;border-radius:6px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer}\n.km-secret-toggle:hover{background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary)}\n.km-form-actions{display:flex;justify-content:flex-end;gap:8px}\n.km-rename{display:flex;align-items:center;gap:4px;min-width:0;flex:1 1 auto;max-width:100%}\n.km-rename-input{flex:1 1 auto;width:auto;min-width:60px;padding:4px 7px;font-size:12.5px}\n.km-inline-error{padding:7px 9px;border:1px solid color-mix(in srgb,var(--dsw-alias-state-error-primary) 35%,var(--dsw-alias-border-l1));border-radius:7px;background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 8%,transparent);color:var(--dsw-alias-state-error-primary);font-size:12px;word-break:break-word}\n.km-key-error{grid-column:1/-1;margin-top:-2px}\n.km-notice{display:flex;align-items:flex-start;gap:8px;padding:9px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-secondary);font-size:12px}\n.km-notice-icon{flex:0 0 auto;margin-top:1px}\n.km-notice-warn{border-color:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 32%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 7%,transparent)}\n.km-notice-error{border-color:color-mix(in srgb,var(--dsw-alias-state-error-primary) 32%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 7%,transparent)}\n.km-notice-body{display:flex;flex-direction:column;gap:2px;min-width:0}\n.km-notice-title{color:var(--dsw-alias-label-primary);font-weight:600;font-size:12px}\n.km-notice-text{line-height:1.5}\n.km-notice-action{flex:0 0 auto}\n.km-empty-keys{padding:12px;border:1px dashed var(--dsw-alias-border-l2);border-radius:8px;color:var(--dsw-alias-label-secondary);font-size:12px}\n.km-empty{display:flex;align-items:center;gap:8px;padding:14px;border:1px dashed var(--dsw-alias-border-l2);border-radius:10px;color:var(--dsw-alias-label-secondary);font-size:12.5px}\n.km-provider-foot{display:flex;justify-content:space-between;gap:10px;align-items:center;margin-top:10px;padding-top:9px;border-top:1px dashed var(--dsw-alias-border-l1);font-size:11px;min-height:15px}\n.km-settings{padding:14px}\n.km-settings-head{display:flex;align-items:flex-start;justify-content:space-between;gap:12px;margin-bottom:12px}\n.km-settings-title{font-size:14px;font-weight:650;margin:0 0 3px}\n.km-settings-intro{margin:0;color:var(--dsw-alias-label-secondary);font-size:12px}\n.km-settings-icon{display:inline-flex;align-items:center;justify-content:center;width:34px;height:34px;border-radius:9px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-brand-primary);border:1px solid var(--dsw-alias-border-l1)}\n.km-settings-grid{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr) minmax(0,1fr);gap:12px;align-items:start}\n.km-field-note{grid-column:1/-1}\n.km-policy-note{padding:9px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:var(--dsw-alias-bg-layer-2)}\n.km-policy-title{display:flex;align-items:center;gap:6px;font-size:11.5px;font-weight:600;color:var(--dsw-alias-label-primary);margin-bottom:2px}\n.km-policy-note p{margin:0;font-size:11.5px;line-height:1.5}\n.km-settings-actions{display:flex;align-items:center;justify-content:flex-end;gap:10px;margin-top:12px}\n.km-saved{display:inline-flex;align-items:center;gap:4px;color:var(--dsw-alias-state-success-primary);font-size:11.5px}\n.km-banner{display:flex;align-items:flex-start;gap:8px;padding:9px 10px;border-radius:8px;margin:0 0 12px;font-size:12px;line-height:1.5;border:1px solid var(--dsw-alias-border-l1);background:var(--dsw-alias-bg-layer-1)}\n.km-banner-error{border-color:color-mix(in srgb,var(--dsw-alias-state-error-primary) 32%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 7%,transparent)}\n.km-banner-warn{border-color:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 32%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 7%,transparent)}\n.km-banner-text{flex:1;min-width:0;word-break:break-word}\n.km-banner-close{display:inline-flex;align-items:center;justify-content:center;width:22px;height:22px;border:0;border-radius:5px;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer}\n.km-banner-close:hover{background:var(--dsw-alias-bg-layer-2)}\n.km-loading{display:flex;align-items:center;gap:8px;padding:20px 0;color:var(--dsw-alias-label-secondary);font-size:12.5px}\n.km-load-failure{display:flex;flex-direction:column;gap:10px;align-items:flex-start;padding:18px;border:1px dashed var(--dsw-alias-border-l2);border-radius:10px;color:var(--dsw-alias-label-secondary);font-size:12.5px}\n.km-empty-title{font-weight:600;color:var(--dsw-alias-label-primary)}\n.km-footer{display:flex;align-items:flex-start;gap:6px;padding-top:4px;color:var(--dsw-alias-label-secondary);font-size:11px;line-height:1.5}\n.km-muted{color:var(--dsw-alias-label-secondary)}\n.km-warn{color:var(--dsw-alias-state-warn-primary)}\n.km-mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px}\n.km-truncate{max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.km-spin{animation:km-spin 1s linear infinite}\n.km-models-note{display:flex;align-items:center;gap:7px;flex-wrap:wrap;margin:8px 0 0;padding:7px 9px;border:1px solid color-mix(in srgb,var(--dsw-alias-brand-primary) 24%,var(--dsw-alias-border-l1));border-radius:7px;background:color-mix(in srgb,var(--dsw-alias-brand-primary) 6%,transparent);font-size:11.5px;color:var(--dsw-alias-label-primary)}\n.km-models-note-warn{border-color:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 30%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-warn-primary) 7%,transparent)}\n.km-models-note-text{font-weight:600}\n.km-models-note-hint{color:var(--dsw-alias-label-secondary);font-weight:400}\n.km-modal-backdrop{position:fixed;inset:0;z-index:80;display:flex;align-items:center;justify-content:center;padding:24px;background:color-mix(in srgb,var(--dsw-alias-label-primary) 26%,transparent)}\n.km-modal{width:min(440px,100%);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;background:var(--dsw-alias-bg-overlay);padding:16px;box-shadow:0 18px 48px color-mix(in srgb,var(--dsw-alias-label-primary) 20%,transparent)}\n.km-modal-title{font-weight:650;font-size:14px;margin-bottom:7px}\n.km-modal-body{color:var(--dsw-alias-label-secondary);font-size:12.5px}\n.km-modal-copy{margin:0;line-height:1.55}\n.km-modal-footer{display:flex;justify-content:flex-end;gap:8px;margin-top:16px}\n@keyframes km-spin{to{transform:rotate(360deg)}}\n@media(max-width:720px){\n  .km-summary{grid-template-columns:repeat(2,minmax(0,1fr))}\n  .km-key-row{grid-template-columns:minmax(0,1fr) 32px;gap:6px}\n  .km-key-status,.km-key-last{grid-column:1;padding-left:0}\n  .km-key-actions{grid-column:2;grid-row:1}\n  .km-settings-grid{grid-template-columns:1fr}\n  .km-form-grid{grid-template-columns:1fr}\n  .km-provider-side .km-status{display:none}\n  .km-embedded-head{flex-direction:column;gap:10px}\n  .km-embedded-actions{padding-top:0}\n}\n";

package/lib/client/types.d.ts

@@ -0,0 +1,87 @@
+/** Browser-half domain and service contracts for the Keys Manager. */
+import type * as React from 'react';
+import type { KeyStatus, KeyView, ManagerSettings, ProviderStatus, ProviderView, StateView } from '../domain';
+export type { KeyStatus, KeyView, ManagerSettings, ProviderStatus, ProviderView, StateView };
+/** Locale dictionaries registered under the plugin namespace. */
+export interface LocaleDicts {
+    zh: Record<string, string>;
+    en: Record<string, string>;
+}
+/** Successful or failed `keysManager/*` Remote answer. */
+export type RpcResult = {
+    ok: true;
+    value: StateView;
+} | {
+    ok: false;
+    error: {
+        message: string;
+    };
+};
+/** One unary result surfaced by the client store. */
+export type ActionOutcome = {
+    ok: true;
+    value: StateView;
+} | {
+    ok: false;
+    error: string;
+};
+/** Immutable UI snapshot. */
+export interface ClientSnapshot {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    state: StateView | null;
+    error: string | null;
+    busy: string | null;
+    now: number;
+}
+/** Store shared by the plugin-detail card and the Models badges. */
+export interface ClientStore {
+    getSnapshot(): ClientSnapshot;
+    subscribe(listener: () => void): () => void;
+    load(options?: {
+        keepError?: boolean;
+    }): Promise<void>;
+    call(method: string, args: Record<string, unknown>): Promise<ActionOutcome>;
+    tick(): void;
+    dismissError(): void;
+}
+/** Locale snapshot exposed by the Client locale service. */
+export interface LocaleSnapshot {
+    active: string;
+    locales: readonly unknown[];
+    revision: number;
+}
+/** Slot registration options, narrowed to the fields this plugin uses. */
+export interface SlotRegistrationOptions {
+    name: string;
+    key?: string;
+    id?: string;
+    order?: number;
+    label?: () => string;
+}
+/** Services required by the browser half. */
+export interface ClientContext {
+    connection: {
+        rpc: {
+            call(channel: string, endpoint: string, payload: {
+                args: Record<string, unknown>;
+            }): Promise<RpcResult>;
+        };
+    };
+    locale: {
+        register(ns: string, dicts: LocaleDicts): () => void;
+        bind(ns: string): (key: string, params?: Record<string, string | number>) => string;
+        subscribe(listener: () => void): () => void;
+        getSnapshot(): LocaleSnapshot;
+    };
+    slots: {
+        inject(key: string, callback: () => undefined | (() => void)): () => void;
+        register(options: SlotRegistrationOptions, component: React.ComponentType<any>): () => void;
+    };
+    on(name: string, listener: (...args: any[]) => void): () => void;
+    effect(effect: () => undefined | (() => void), label?: string): () => void;
+}
+/** Runtime value threaded through the generated React context. */
+export interface Runtime {
+    ctx: ClientContext;
+    store: ClientStore;
+}

package/lib/client/ui.d.ts

@@ -0,0 +1,18 @@
+/** Keys Manager browser components, rendered from the plugin-detail card and
+ * the Models provider-card extension slot. */
+import React from 'react';
+declare function KeysManagerBody(): React.ReactElement;
+interface KeysManagerCardProps {
+    view?: 'summary' | 'page';
+    form?: unknown;
+}
+declare function KeysManagerCard({ view }: KeysManagerCardProps): React.ReactElement | null;
+interface ManagedProviderBadgeProps {
+    provider?: {
+        provider?: string;
+    };
+    view?: 'summary' | 'page';
+}
+declare function ManagedProviderBadge(props: ManagedProviderBadgeProps): React.ReactElement | null;
+export { KeysManagerCard, ManagedProviderBadge, KeysManagerBody };
+export type { KeysManagerCardProps, ManagedProviderBadgeProps };