@eduwork/dsh-oidc 0.1.0 → 0.2.0

package/docs/dsh-integration.md

@@ -4,7 +4,7 @@
 
 ## 支持的宿主基线
 
-当前兼容基线为 DeepSeek Harness `0.1.2-rc.1`，上游 commit `a66e4702047846cdaa10c66c9d3df3951f5ea70d`。DSH 仍处于预发布阶段，因此本包把完整 DSH peer 闭包固定到该精确版本，并在检查中拒绝混入其他 DSH 版本。
+当前 `0.2.0`以 npm 已发布的 DSH `0.1.5-rc.1` 闭包作为开发/CI 基线。历史稳定版 `0.1.0` 对应 `0.1.2-rc.1`；其他旧候选证据分别记在[兼容性矩阵](compatibility.md)。不要混装 DSH 版本。干净安装见[开发准备](development.md)。
 
 插件只使用公开 package export，不复制 DSH 源码：
 
@@ -43,8 +43,12 @@ OpenAI-compatible 网络实现来自 `@earendil-works/pi-ai`，它也是 DSH 官
 | 方法 | 结果 |
 | --- | --- |
 | `configuration()` | 删除秘密和 endpoint 基址后的公开 Profile。 |
+| `openConfiguration(target)` | 通过宿主打开配置/示例；不返回文件内容或秘密。 |
 | `status(profileID)` | 本地 session/凭据状态。 |
-| `begin(profileID)` | Web 返回重定向 URL，native 返回完成状态。 |
+| `begin(profileID)` | Web 重定向、临时 desktop 登录 ID 或旧 native 完成状态。 |
+| `loginStatus(loginID)` / `cancelLogin(loginID)` | 查询或取消当前桌面登录。 |
+| `resources(profileID)` | 模型元数据与问题，不含配额或秘密。 |
+| `selectEnterpriseModel(profileID, options)` | 通过官方默认值选择已验证连接的模型，不接受任意 Provider 目的地。 |
 | `reconcile(profileID, {allowProvision})` | 执行 bootstrap 和 resolve/provision/renew。 |
 | `logout(profileID)` | 本地清理，并尽力执行 OIDC 撤销。 |
 | `management()` | 共用企业模型设置 UI 使用的宿主能力投影。 |
@@ -56,10 +60,12 @@ Client 描述符使用严格 Zod codec。发送给浏览器的配置不包含 is
 
 ### 直接安装
 
-`dsh-oidc` 自带默认的 Web-first Bundle patch，可以直接从 npm 安装到官方 Web Profile，无需再编写 wrapper Bundle：
+`dsh-oidc` 自带默认的 local-Web Bundle patch，可以直接从 npm 安装到官方 Web Profile，无需再编写 wrapper Bundle：
+
+安装精确的 `0.2.0`，宿主 DSH 依赖应统一为 `0.1.5-rc.1`。发布准备期间若 registry 尚未提供该版本，使用下方源码或已核验的冻结产物。
 
 ```bash
-dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0
+dsh plugin --profile web add @eduwork/dsh-oidc@0.2.0
 ```
 
 需要审计、开发或验证尚未发布的改动时，可以安装经过审查的本地 checkout：
@@ -74,7 +80,7 @@ dsh plugin --profile web add .
 
 本地路径安装会把 checkout 链接到 Profile，因此源码目录必须持续存在。它不会扫描当前工作区。团队部署应固定经过复核的 npm 精确版本；不要在同一 Profile 中混装其他 DSH 预发布线。
 
-随包 patch 使用 `DSH_OIDC_ENTERPRISE_PROFILE` 挂载且只挂载一个 `enterprise-oidc` 实例。Web backend 要求 DSH WebServer 精确监听 `127.0.0.1`，并从实际端口构造固定 `/oauth/callback`；不接受公网回调源配置。它有意不设置 `agent-default-model`，因为 Provider 和模型 ID 属于部署方 Enterprise Profile，用户可在 DSH 中选择可用企业模型。
+随包 patch 使用 `EDUWORK_OIDC_PROFILE` 挂载且只挂载一个 `enterprise-oidc` 实例。Web backend 要求 DSH WebServer 精确监听 `127.0.0.1`，并从实际端口构造固定 `/oauth/callback`；不接受公网回调源配置。patch 不硬编码 `agent-default-model`；完成显式登录/Key 绑定后，Client 使用官方选择接口应用已连接机构默认模型。重启后的恢复仅修复不可用默认值，不覆盖个人模型选择。旧 `DSH_OIDC_ENTERPRISE_PROFILE` 环境变量仍兼容。
 
 ### 产品自有 Bundle
 
@@ -88,7 +94,7 @@ dsh plugin --profile web add .
     - id: enterprise-oidc
       name: '@eduwork/dsh-oidc'
       config:
-        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        profilePathEnv: EDUWORK_OIDC_PROFILE
         web:
           returnPath: /
 ```
@@ -97,7 +103,13 @@ dsh plugin --profile web add .
 
 OIDC 注册、Key Binding 实现、环境变量、验收和排障见[接入指南](getting-started.md)。
 
-## Desktop/native 组合
+## Desktop 组合
+
+新 Wails/Electron 产品使用 `backend: desktop`：插件管理临时 loopback 回调，通过官方 `nativeCommand` 打开浏览器。两壳共享身份、Key Binding 和模型行为；宿主仍提供凭据存储，无需另写 `enterpriseAccounts`。见[桌面 Host 集成](desktop-host.md)。
+
+## 旧 native 桥兼容
+
+以下 adapter 仅用于已有集成，不是新桌面的必做项：
 
 ```yaml
 - insert:
@@ -155,6 +167,10 @@ const dispose = ctx.enterpriseTransforms.register({
 
 转换是可执行本地插件，必须单独审查，绝不会从 Enterprise Profile 加载。
 
+## 机构适配器的凭据读取
+
+显式安装的本地适配器可调用 `ctx.oidcAccounts.resolveBoundCredential(profileID, { credentialRef: "EDUWORK_API_KEY", runtimeBaseURL })`。`runtimeBaseURL` 必须精确等于该 Profile 已审查的模型服务基址；返回已同时验证 session、issuer/client ID、完整资源绑定和 Key 指纹的 DSH credential record，未满足条件则返回 `undefined`。适配器直接使用这份 record，不应在检查状态后另行解析同名 Key，避免两个读操作之间发生账户切换。此方法只在 Host 存在，没有 Typert/RPC 注册，也不属于服务端协议。适配器仍负责限制其请求目的地址；当前桌面/Web 后端支持该方法，旧 native 桥不会降级返回未经验证的 Key。
+
 ## DSH 升级流程
 
 每次升级 DSH release candidate 或 stable 版本时：

package/docs/ecnu-reference.en.md

@@ -8,7 +8,7 @@ The reference file is [`examples/ecnu.enterprise-profile.example.json`](../examp
 
 ## Intended composition
 
-The existing ChatECNU Work product can be expressed as a composition rather than a monolith:
+EduWork@ECNU composes the public core with institution extensions:
 
 ```text
 DeepSeek Harness
@@ -22,12 +22,12 @@ DeepSeek Harness
       - image-understanding fallback for text-only ecnu-max
       - enterprise search route and official DSH result rendering
       - product presets/skills/resources
-      - native desktop account adapter and OS credential vault
+      - legacy native account bridge only (new desktops use the public desktop backend)
       - quota or institution-specific business UI
   + desktop shell/packaging/updater
 ```
 
-Pure Web DSH uses the Web backend and a host-appropriate Credential Provider. ChatECNU Work desktop uses the native backend and keeps its existing Wails implementation behind `enterpriseAccounts`. Both render the enterprise-model section through `dsh-oidc`; the desktop adapter merely advertises additional mutation/restart capabilities. Neither mode changes OIDC or Key Binding server contracts.
+New desktop compositions use the public `desktop` backend and host browser service for temporary loopback login; local functional validation uses `web`. The older Wails `native`/`enterpriseAccounts` bridge is a migration compatibility path, not a requirement for another institution. Trusted files manage organization configuration, while UI shows status and sign-in. Explicit institution plugins own quota, heartbeat and campus search; the public package does not request them. All modes follow the `EDUWORK_API_KEY` rules and complete deployment-binding checks without changing the existing OIDC/Key Binding wire.
 
 ## Identity expectation
 

package/docs/ecnu-reference.md

@@ -8,7 +8,7 @@
 
 ## 预期组合
 
-现有 ChatECNU Work 产品可以表达为组合结构，而不是单体实现：
+EduWork@ECNU 使用公共核心加机构扩展的组合：
 
 ```text
 DeepSeek Harness
@@ -22,12 +22,12 @@ DeepSeek Harness
       - 面向纯文本 ecnu-max 的图像理解回退
       - 企业搜索通路和 DSH 官方结果渲染
       - 产品预设、Skill 和资源
-      - native 桌面账号 adapter 与操作系统凭据保险库
+      - 仅旧版需要的 native 账号桥（新桌面使用公共 desktop 后端）
       - 配额或机构特有业务 UI
   + 桌面外壳、打包与更新器
 ```
 
-纯 Web DSH 使用 Web 后端和适合宿主的 Credential Provider。ChatECNU Work 桌面端使用 native 后端，并把现有 Wails 实现保留在 `enterpriseAccounts` 后面。两者都通过 `dsh-oidc` 渲染企业模型区域；桌面 adapter 只额外声明可变配置和重启能力。两种模式都不改变 OIDC 或 Key Binding 服务端契约。
+新桌面组合使用公共 `desktop` 后端，通过宿主浏览器服务完成临时 loopback 登录；本机功能验证用 `web` 后端。旧 Wails 发行版的 `native`/`enterpriseAccounts` 桥属于迁移兼容路径，不是新机构接入要求。企业配置由可信文件管理，界面负责展示和登录。配额、心跳、校内搜索由明确安装的机构插件提供；公版不请求这些服务。所有模式共用 `EDUWORK_API_KEY` 规则和完整部署绑定校验，不改变现有 OIDC/Key Binding wire。
 
 ## 身份预期
 

package/docs/enterprise-profile.en.md

@@ -1,10 +1,12 @@
 # Enterprise Profile specification (`dsh-oidc/v1alpha1`)
 
+> Candidate extension: omit both keyBinding/provider for identity-only OIDC; brand is optional. Resource mode accepts keyBinding.type=eduwork-resources-v1 (default worker-user-center-v1). provider.modelSource=discovery may omit models; normal profile mode requires models. See [Public resource protocol](public-resource-protocol.en.md).
+
 [简体中文](enterprise-profile.md) | **English**
 
 ## Status and conformance
 
-This document specifies the data contract consumed by `dsh-oidc` `0.1.x`. The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, and **MAY** are interpreted as described by RFC 2119 and RFC 8174.
+This document specifies the data contract consumed by `dsh-oidc` `0.2.x`. The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, and **MAY** are interpreted as described by RFC 2119 and RFC 8174.
 
 The canonical machine-readable schema is [`schema/enterprise-profile.v1alpha1.schema.json`](../schema/enterprise-profile.v1alpha1.schema.json). Runtime validation is intentionally stricter in several security-sensitive URL cases. A conforming profile MUST pass both JSON Schema validation and `normalizeEnterpriseProfile()`.
 
@@ -15,7 +17,7 @@ Profiles are trusted deployment configuration, not user input. Nevertheless, the
 - unknown keys are rejected at the root and at every executable-relevant nested object;
 - total serialized profile size is limited to 512 KiB;
 - production URLs require HTTPS;
-- development HTTP is accepted only for explicit loopback hosts;
+- development HTTP needs an explicit loopback allowance or exact development-origin allowlist;
 - URL credentials, fragments, and endpoint-base query strings are rejected;
 - only the built-in `openai-compatible` adapter can be selected;
 - Key Binding accepts only its protocol base and an optional local DSH credential reference; network paths and fields remain fixed;
@@ -34,10 +36,10 @@ A remote administration system MAY distribute profile JSON only if the host auth
 | `nativeInstitutionID` | no | Identifier passed only to a native backend; defaults to `id`. |
 | `allowInsecureDevelopment` | no | Enables loopback HTTP for local development. Network HTTP additionally requires `insecureDevelopmentOrigin`. |
 | `insecureDevelopmentOrigin` | no | Exact non-TLS development origin. It is accepted only together with `allowInsecureDevelopment: true`, and every HTTP OIDC/key-binding/provider endpoint must use this exact origin. Never ship it in a production profile. |
-| `brand` | yes | Bounded presentational values. |
+| `brand` | no | Bounded presentational values. |
 | `oidc` | yes | OIDC public-client facts. |
-| `keyBinding` | yes | Key Binding base URL and optional local DSH credential reference. |
-| `provider` | yes | One local OpenAI-compatible Provider route and model list. |
+| `keyBinding` | resource mode | Key Binding base URL and optional local DSH credential reference. |
+| `provider` | resource mode | One local OpenAI-compatible Provider route and model list. |
 
 ## Branding
 
@@ -79,7 +81,7 @@ The Web redirect URI is fixed to `http://127.0.0.1:<DSH-port>/oauth/callback`. T
 ```json
 {
   "baseURL": "https://ai.example.edu/api/worker/v1",
-  "credentialRef": "EXAMPLE_AI_TEST_API_KEY"
+  "credentialRef": "EDUWORK_API_KEY"
 }
 ```
 
@@ -88,9 +90,11 @@ The Web redirect URI is fixed to `http://127.0.0.1:<DSH-port>/oauth/callback`. T
 | `baseURL` | yes | Base URL of the `worker-user-center-v1` Key Binding interface group. |
 | `credentialRef` | no | Local DSH Credential Provider name under which the bound model API key is stored. It must match `^[A-Za-z_][A-Za-z0-9_]*$` and is limited to 128 characters. |
 
-The protocol type is fixed to `worker-user-center-v1`, and the Provider ID sent on the wire is always `provider.id`. When `credentialRef` is omitted, the parser preserves the backward-compatible default: uppercase the Provider ID, replace non-alphanumerics with `_`, and append `_API_KEY`. For example, `example-ai` defaults to `EXAMPLE_AI_API_KEY`.
+The Provider ID sent on the wire is always `provider.id`. An omitted `credentialRef` now defaults to `EDUWORK_API_KEY`. Legacy automatic references derived from this Profile’s `id` or `provider.id` (uppercase, non-alphanumerics replaced with `_`, followed by `_API_KEY`) normalize to this common name. Other explicit references remain unchanged.
+
+`credentialRef` names a local secret-store entry; it is not a key and is never sent over the network. Normal deployments use `EDUWORK_API_KEY`; explicit independent overrides such as `MY_TEST_MODEL_KEY` remain supported. With a shared reference, only a verified login whose bound credential fingerprint matches the current key may read it. Rebinding leaves other profiles disconnected from that key, and their logout cannot delete a key written by another login. Independently configured personal model credentials are unaffected.
 
-`credentialRef` is only the name of a local secret-store entry. It is not an API key and is never sent to OIDC, Key Binding, or the model service. A normal single-environment deployment SHOULD omit it. Deployments that reuse one Provider ID across production and test MUST configure distinct references, for example `EXAMPLE_AI_API_KEY` and `EXAMPLE_AI_TEST_API_KEY`, so one environment cannot resolve another environment's key.
+An upgrade imports an old key only when issuer, client ID, management URL, runtime URL and Provider ID all match and only the automatic reference changed. It neither overwrites nor adopts an occupied target. Unproven ownership retains identity but requires reconnecting model resources. Pre-fingerprint sessions are accepted only with an identical complete binding and unambiguous reference ownership.
 
 Endpoint paths, request/response fields, and Provider ID semantics are protocol facts and MUST NOT be customized by profiles. If a native host returns `runtimeCredentialRef`, it MUST equal the normalized profile value or the plugin fails closed.
 
@@ -100,7 +104,7 @@ The Provider object is data interpreted by a local audited adapter.
 
 | Field | Required | Meaning |
 | --- | --- | --- |
-| `id` | yes | DSH route ID and source of the default credential reference. Must be unique across loaded profiles. |
+| `id` | yes | DSH route ID, independent of the shared default credential reference. Must be unique across loaded profiles. |
 | `displayName` | no | User-facing Provider name. |
 | `adapter` | yes | Exact string `openai-compatible`. |
 | `baseURL` | yes | HTTPS OpenAI-compatible API base. |
@@ -113,7 +117,8 @@ The Provider object is data interpreted by a local audited adapter.
 | `streamIdleTimeoutMs` | no | Positive idle timeout, default 300000. |
 | `retryPolicy` | no | DSH provider-owned retry policy; default normal/2 retries. |
 | `compat` | no | Bounded pi-ai OpenAI compatibility facts. |
-| `models` | yes | 1–128 unique model entries. |
+| `modelSource` | no | `profile` (default) or `discovery`; discovery requests `/models` with the managed key. |
+| `models` | profile mode | 1–128 unique entries; discovery may omit them, and configured entries supply reviewed capabilities. |
 
 `retryPolicy.mode` is `normal` or `always`. `always` can retry indefinitely until success, cancellation, or disposal and SHOULD NOT be enabled without an explicit product decision. The policy is validated again by DSH.
 
@@ -129,8 +134,11 @@ Each model has:
 - optional positive `contextWindow` and `maxTokens`;
 - optional `reasoning` boolean;
 - optional `reasoningEfforts` object, or `false`; object keys are limited to `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, and only `off` may have a null wire value;
+- optional `defaultReasoningEffort`, which must name an effort declared by that model; when omitted, the historical provider-level `reasoning` preference falls back to the nearest supported effort, choosing the lower effort on a tie;
 - optional bounded `compat` overrides.
 
+Once `reasoningEfforts` is declared, every omitted effort is explicitly unsupported. Effort IDs and wire values remain distinct, so `xhigh` is never silently rewritten as `max`. For thinking without a user-selectable effort, set only `compat.supportsReasoningEffort` to `false`; for a model with no thinking capability, set `reasoning` or `reasoningEfforts` to `false`.
+
 If a model supports thinking but not selectable reasoning effort, set:
 
 ```json
@@ -139,7 +147,7 @@ If a model supports thinking but not selectable reasoning effort, set:
 }
 ```
 
-The adapter then enables the profile's thinking behavior while removing an unsupported user-selected effort before validation and transport. The request is not rejected merely because the provider lacks an effort parameter.
+The adapter preserves the profile's thinking behavior: historical user-selected efforts are ignored, the profile default is resolved against that model's supported levels, and only an internal enabling signal is passed to PiAi. `compat.supportsReasoningEffort: false` keeps `reasoning_effort` out of the HTTP request. This signal does not create selectable UI efforts; a profile default of `off` still disables models that support it. The request is not rejected merely because the provider lacks an effort parameter.
 
 ## Secret prohibition
 

package/docs/enterprise-profile.md

@@ -1,10 +1,12 @@
 # Enterprise Profile 规范（`dsh-oidc/v1alpha1`）
 
+> 当前候选扩展：纯身份模式同时省略 keyBinding/provider；brand 可省略。资源模式支持 keyBinding.type=eduwork-resources-v1，默认兼容 worker-user-center-v1。provider.modelSource=discovery 时 models 可省略；默认 profile 模式仍要求模型列表。见 [公共资源协议](public-resource-protocol.md)。
+
 **简体中文** | [English](enterprise-profile.en.md)
 
 ## 状态与符合性
 
-本文规定 `dsh-oidc` `0.1.x` 使用的数据契约。关键词 **必须（MUST）**、**不得（MUST NOT）**、**必需（REQUIRED）**、**应该（SHOULD）**、**不应该（SHOULD NOT）** 和 **可以（MAY）** 按 RFC 2119 与 RFC 8174 解释。
+本文规定 `dsh-oidc` `0.2.x` 使用的数据契约。关键词 **必须（MUST）**、**不得（MUST NOT）**、**必需（REQUIRED）**、**应该（SHOULD）**、**不应该（SHOULD NOT）** 和 **可以（MAY）** 按 RFC 2119 与 RFC 8174 解释。
 
 权威机器可读 Schema 为 [`schema/enterprise-profile.v1alpha1.schema.json`](../schema/enterprise-profile.v1alpha1.schema.json)。运行时对若干安全敏感 URL 的校验有意比 JSON Schema 更严格。符合规范的 Profile 必须同时通过 JSON Schema 和 `normalizeEnterpriseProfile()` 校验。
 
@@ -34,10 +36,10 @@ Profile 是受信任的部署配置，不是用户输入。即便如此，解析
 | `nativeInstitutionID` | 否 | 仅传给 native 后端的标识符；默认使用 `id`。 |
 | `allowInsecureDevelopment` | 否 | 为本地开发启用 loopback HTTP。网络 HTTP 还必须配置 `insecureDevelopmentOrigin`。 |
 | `insecureDevelopmentOrigin` | 否 | 精确的非 TLS 开发 origin。只有与 `allowInsecureDevelopment: true` 一起使用时才有效，且所有 HTTP OIDC/Key Binding/Provider endpoint 必须使用该 origin。不得放入生产 Profile。 |
-| `brand` | 是 | 有边界的展示配置。 |
+| `brand` | 否 | 有边界的展示配置。 |
 | `oidc` | 是 | OIDC public client 配置事实。 |
-| `keyBinding` | 是 | Key Binding 基础 URL，以及可选的本地 DSH 凭据引用。 |
-| `provider` | 是 | 一个本地 OpenAI-compatible Provider 路由和模型列表。 |
+| `keyBinding` | 资源模式 | Key Binding 基础 URL，以及可选的本地 DSH 凭据引用。 |
+| `provider` | 资源模式 | 一个本地 OpenAI-compatible Provider 路由和模型列表。 |
 
 ## 品牌替换
 
@@ -79,7 +81,7 @@ Web 重定向地址固定为 `http://127.0.0.1:<DSH端口>/oauth/callback`。hos
 ```json
 {
   "baseURL": "https://ai.example.edu/api/worker/v1",
-  "credentialRef": "EXAMPLE_AI_TEST_API_KEY"
+  "credentialRef": "EDUWORK_API_KEY"
 }
 ```
 
@@ -88,9 +90,11 @@ Web 重定向地址固定为 `http://127.0.0.1:<DSH端口>/oauth/callback`。hos
 | `baseURL` | 是 | `worker-user-center-v1` Key Binding 接口组的基址。 |
 | `credentialRef` | 否 | 保存绑定后模型 API Key 的本地 DSH Credential Provider 名称。必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`，最长 128 字符。 |
 
-协议类型固定为 `worker-user-center-v1`，请求中的 Provider ID 固定取 `provider.id`。如果省略 `credentialRef`，解析器保持向后兼容：将 Provider ID 转为大写、把非字母数字替换为 `_`，再追加 `_API_KEY`。例如 `example-ai` 默认对应 `EXAMPLE_AI_API_KEY`。
+请求中的 Provider ID 固定取 `provider.id`。`credentialRef` 省略时统一为 `EDUWORK_API_KEY`。旧配置中按本 Profile 的 `id` 或 `provider.id` 大写、非字母数字替换为 `_` 后追加 `_API_KEY` 的引用，按兼容别名规范化到同一默认值，不再按企业生成名称。其他显式引用原样保留。
+
+`credentialRef` 只是本地秘密存储的引用名，不是 API Key，不发送给 OIDC、Key Binding 或模型服务。常规部署使用 `EDUWORK_API_KEY`；需要额外独立管理的显式引用仍可使用例如 `MY_TEST_MODEL_KEY`。默认槽位记录当前绑定的企业 Key；多个 Profile 共用时，仅凭据指纹与当前 Key 匹配的已验证登录可以读取它。重新绑定后，其他 Profile 不会借用该 Key，登出也不会删除其他登录写入的新 Key。个人模型使用的独立引用不受影响。
 
-`credentialRef` 只是本地秘密存储的引用名，不是 API Key，不发送给 OIDC、Key Binding 或模型服务。普通单环境部署应该省略它并使用默认值；同一 Provider ID 在生产和测试部署间复用时，必须为不同环境配置不同引用，例如 `CHATECNU_API_KEY` 与 `CHATECNU_QUOTA_TEST_API_KEY`，避免一个环境读取另一环境的 Key。
+升级只在同一 issuer、client ID、资源管理基址、模型服务基址、Provider ID 且仅旧自动引用改名时迁移原 Key。新槽位已有值时既不覆盖也不自动接管；无法证明归属时保留身份并重新连接模型资源。旧会话缺少指纹时，仅完整绑定相同且引用归属无歧义才兼容。
 
 Endpoint 路径、请求/响应字段和 Provider ID 语义属于协议事实，不得由 Profile 自定义。Native 宿主若返回 `runtimeCredentialRef`，其值必须与本字段规范化后的结果一致，否则插件失败关闭。
 
@@ -100,7 +104,7 @@ Provider 对象是由本地、经过审查的 adapter 解释的数据。
 
 | 字段 | 必需 | 含义 |
 | --- | --- | --- |
-| `id` | 是 | DSH 路由 ID，也是默认凭据引用的来源；在所有已加载 Profile 中必须唯一。 |
+| `id` | 是 | DSH 路由 ID；在所有已加载 Profile 中必须唯一。 |
 | `displayName` | 否 | 面向用户的 Provider 名称。 |
 | `adapter` | 是 | 精确字符串 `openai-compatible`。 |
 | `baseURL` | 是 | HTTPS OpenAI-compatible API 基址。 |
@@ -113,7 +117,8 @@ Provider 对象是由本地、经过审查的 adapter 解释的数据。
 | `streamIdleTimeoutMs` | 否 | 正数空闲超时，默认 300000。 |
 | `retryPolicy` | 否 | 由 DSH Provider 管理的重试策略；默认 normal/重试 2 次。 |
 | `compat` | 否 | 有边界的 pi-ai OpenAI 兼容事实。 |
-| `models` | 是 | 1–128 个唯一模型条目。 |
+| `modelSource` | 否 | `profile`（默认）或 `discovery`；后者通过受管 Key 请求 `/models`。 |
+| `models` | `profile` 模式 | 1–128 个唯一模型条目；`discovery` 可省略，已配置条目作为能力声明。 |
 
 `retryPolicy.mode` 可以是 `normal` 或 `always`。`always` 可能一直重试，直到成功、取消或销毁；没有明确产品决策时不应启用。该策略还会由 DSH 再次校验。
 
@@ -129,8 +134,11 @@ Provider 对象是由本地、经过审查的 adapter 解释的数据。
 - 可选的正数 `contextWindow` 和 `maxTokens`；
 - 可选 `reasoning` 布尔值；
 - 可选 `reasoningEfforts` 对象或 `false`；对象键限于 `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`，且只有 `off` 的过线值可以为 `null`；
+- 可选 `defaultReasoningEffort`，且必须是该模型在 `reasoningEfforts` 中声明的档位；若省略，旧的 Provider 级 `reasoning` 会就近回落到模型的有效档位，同距时取较低档；
 - 可选的受限 `compat` 覆盖。
 
+声明 `reasoningEfforts` 后，未列出的档位会被显式标记为不支持；档位 ID 与过线值分开保存，因此 `xhigh` 不会被静默改成 `max`。若模型支持 thinking 但不支持用户选择档位，可只将 `compat.supportsReasoningEffort` 设为 `false`；若模型完全不支持 thinking，则将 `reasoning` 或 `reasoningEfforts` 设为 `false`。
+
 若模型支持 thinking，但不支持选择 reasoning effort，请设置：
 
 ```json
@@ -139,7 +147,7 @@ Provider 对象是由本地、经过审查的 adapter 解释的数据。
 }
 ```
 
-Adapter 会保留 Profile 的 thinking 行为，并在校验和传输前移除不支持的用户所选 effort。不会因为 Provider 不支持 effort 参数而拒绝整个请求。
+Adapter 会保留 Profile 的 thinking 行为：忽略历史会话中用户选择的 effort，按该模型可用档位解析 Profile 默认值，仅向 PiAi 传递内部启用信号；`compat.supportsReasoningEffort: false` 保证 HTTP 请求不包含 `reasoning_effort`。该信号不会变成用户可选档位，Profile 的 `off` 仍可关闭支持关闭的模型。不会因为 Provider 不支持 effort 参数而拒绝整个请求。
 
 ## 禁止写入的秘密
 

package/docs/getting-started.en.md

@@ -4,14 +4,14 @@
 
 This guide is for operators integrating `dsh-oidc` into their own DeepSeek Harness deployment. The result is a closed loop: users sign in through the organization's OIDC Provider, explicitly bind a revocable model runtime credential, inspect the enterprise Provider and model catalog, and call those models from ordinary DSH Web.
 
-`dsh-oidc` is Web-first and does not require Wails or ChatECNU Work. ECNU is only a reference deployment.
+The same OIDC implementation supports both desktop shells and local Web validation. It does not require Wails or an ECNU service. This guide uses Web commands; new desktop compositions use `backend: desktop` as described in [desktop integration](desktop-host.en.md).
 
 ## 1. Prerequisites
 
 | Component | Minimum requirement |
 | --- | --- |
-| DSH Host | DeepSeek Harness `0.1.2-rc.1` on Node.js 22+. |
-| Institutional enterprise-model integration service | One accountable owner jointly delivers the OIDC Provider, fixed Key Binding API, and OpenAI-compatible model gateway; all three are required. |
+| DSH Host | This candidate targets DeepSeek Harness `0.1.5-rc.1` on Node.js 22+; do not mix it with the historical stable package. |
+| Institutional enterprise-model integration service | Identity-only mode needs OIDC. Managed models additionally require the fixed Key Binding API and OpenAI-compatible gateway. |
 | Enterprise Profile | Trusted local JSON containing public configuration only. |
 | Credential Provider | The current Web backend supports trusted single-user local storage only. |
 
@@ -25,13 +25,13 @@ Register a public client without a client secret. Its redirect URI must exactly
 http://127.0.0.1:3080/oauth/callback
 ```
 
-`127.0.0.1` and `/oauth/callback` are fixed. `3080` is the recommended DSH port; if the DSH WebServer port changes, the registered URI must use the same port. Do not register `localhost`, a LAN address, or a public address. Discovery must publish `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and `userinfo_endpoint`. UserInfo must contain a non-empty `sub` matching the ID Token; provide the standard `name` claim for a human-readable label. The current release accepts RS256 ID Tokens only.
+This fixed-port example is for local Web validation. New desktops default to a temporary random port; see [desktop integration](desktop-host.en.md) for fixed-port IdPs. `127.0.0.1` and `/oauth/callback` are fixed. `3080` is the recommended DSH port; if the DSH WebServer port changes, the registered URI must use the same port. Do not register `localhost`, a LAN address, or a public address. Discovery must publish `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and `userinfo_endpoint`. UserInfo must contain a non-empty `sub` matching the ID Token; provide the standard `name` claim for a human-readable label. The current release accepts RS256 ID Tokens only.
 
 See the complete [OIDC interoperability profile](oidc-interoperability.en.md).
 
 ## 3. Implement the complete institutional service
 
-One institutional delivery must provide the OIDC interface group above, the Key Binding interface group below, and an OpenAI-compatible model gateway that accepts the bound credentials. Internal systems may host different interfaces, but versioning, security, and operations have one accountable integration boundary. See the [server API specification](server-integration-contract.en.md).
+For managed enterprise models, provide OIDC, the Key Binding group below and an OpenAI-compatible gateway accepting the bound key. Identity-only deployments may skip this section. Internal systems may host different interfaces, but versioning, security, and operations have one accountable integration boundary. See the [server API specification](server-integration-contract.en.md).
 
 The configured `keyBinding.baseURL` has four fixed operations:
 
@@ -42,7 +42,7 @@ POST /runtime-credential/resolve
 POST /runtime-credential/renew
 ```
 
-The Profile may additionally use optional `keyBinding.credentialRef` to isolate entries in the local DSH Credential Provider. It is not sent over the network and does not alter these operations. Omit it for an ordinary single-environment deployment; use distinct references when production and test reuse the same Provider ID.
+The Profile may additionally use optional `keyBinding.credentialRef` to isolate entries in the local DSH Credential Provider. It is not sent over the network and does not alter these operations. Its default is `EDUWORK_API_KEY`; explicit use of that name is also accepted. Use another reference only for independently managed credentials. See the [Profile specification](enterprise-profile.en.md) for legacy migration and ownership checks.
 
 Every request carries the OIDC Access Token as a Bearer credential. The service must validate issuer, audience, expiry, scopes, subject, and organization authorization. It must not trust `provider_id` by itself. Credential responses are `no-store`, and `api_key` must never enter logs, metrics labels, or error details.
 
@@ -56,10 +56,10 @@ The Profile is trusted deployment data, not a secret store. It must not contain
 
 ## 5. Install into ordinary DSH Web
 
-The package is itself an installable DSH Bundle. Team deployments should install the reviewed, exact version from npm:
+The package is an installable DSH Bundle. Pin `0.2.0` with a coherent DSH `0.1.5-rc.1` host. Consult the npm registry for publication status; during release preparation use a frozen candidate or source checkout if the version is unavailable:
 
 ```bash
-dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0
+dsh plugin --profile web add @eduwork/dsh-oidc@0.2.0
 ```
 
 For auditing, development, or testing unpublished changes, install from a local checkout instead:
@@ -83,7 +83,7 @@ DSH links the checkout into `$DSH_HOME/profiles/web`; it does not scan or copy t
 Set the trusted local Profile path and start DSH on the fixed loopback host:
 
 ```bash
-export DSH_OIDC_ENTERPRISE_PROFILE=/etc/dsh/enterprise-profile.json
+export EDUWORK_OIDC_PROFILE=/etc/dsh/enterprise-profile.json
 dsh --profile web --host 127.0.0.1 --port 3080 --no-open
 ```
 
@@ -100,12 +100,12 @@ A product-owned Bundle may mount the plugin explicitly instead of using the defa
     - id: enterprise-oidc
       name: '@eduwork/dsh-oidc'
       config:
-        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        profilePathEnv: EDUWORK_OIDC_PROFILE
         web:
           returnPath: /
 ```
 
-Desktop products may use `backend: native`, point `profilePathEnv` at the same standard Enterprise Profile used by Web, and supply the capability-detected `enterpriseAccounts` service. Product-owned institution, tenant, or account catalogs MUST be converted to an Enterprise Profile by the product assembly layer before `dsh-oidc` reads them. Wails, Electron, Tauri, and other hosts can implement that boundary; the plugin depends on neither a desktop framework nor a product catalog format. See [DSH integration](dsh-integration.en.md).
+New desktop products should use `backend: desktop`, sharing the temporary loopback callback and official `nativeCommand`; see [desktop integration](desktop-host.en.md). Legacy hosts may still use `backend: native`, point `profilePathEnv` at the same standard Enterprise Profile used by Web, and supply the capability-detected `enterpriseAccounts` service. Product-owned institution, tenant, or account catalogs MUST be converted to an Enterprise Profile by the product assembly layer before `dsh-oidc` reads them. Wails, Electron, Tauri, and other hosts can implement that boundary; the plugin depends on neither a desktop framework nor a product catalog format. See [DSH integration](dsh-integration.en.md).
 
 ## 7. Acceptance checklist
 
@@ -130,4 +130,4 @@ The current Web backend does not support shared Web. A shared scenario needs a n
 - **A subject string is shown instead of a name:** return a non-empty standard `name` from UserInfo under the `profile` scope; private JSON-path mappings are intentionally unsupported.
 - **Login works but models do not:** inspect `/bootstrap`, explicit provisioning state, exact `provider_id` equality, and whether the model gateway accepts the bound key.
 - **Thinking works but selectable effort does not:** set model `compat.supportsReasoningEffort` to `false`; thinking remains enabled while the unsupported effort parameter is removed.
-- **Why the enterprise controls are inside Models:** DSH `0.1.2-rc.1` exposes the official `settings.models.footer` extension slot. `dsh-oidc` mounts its management UI there and leaves the upstream Models page enabled; no product-private Models-page fork is required.
+- **Where enterprise controls live:** the official `settings.models.footer` slot displays configured institutions while keeping personal API keys in the upstream Models settings. Institutions come from trusted distribution files; products may offer a file-opening action. The plugin does not expose a form for arbitrary endpoint changes.

package/docs/getting-started.md

@@ -16,8 +16,8 @@
 
 | 组件 | 谁提供 | 最低要求 |
 | --- | --- | --- |
-| DSH Host | 部署方 | DeepSeek Harness `0.1.2-rc.1`，Node.js 22+。 |
-| 机构企业模型集成服务 | 同一服务所有者 | 共同提供 OIDC Provider、固定 Key Binding 和 OpenAI-compatible 模型网关；三者全部必需。 |
+| DSH Host | 部署方 | 本版基线 DeepSeek Harness `0.1.5-rc.1`，Node.js 22+；不要与历史稳定包混用。 |
+| 机构企业模型集成服务 | 同一服务所有者 | 纯身份档提供 OIDC；托管模型档再联合提供固定 Key Binding 与 OpenAI-compatible 模型网关。 |
 | Enterprise Profile | 部署方 | 一份受信任的本地 JSON，只存公开配置，不存密钥或个人信息。 |
 | Credential Provider | DSH Host | 当前 Web backend 仅支持可信单用户本机存储。 |
 
@@ -31,7 +31,7 @@
 http://127.0.0.1:3080/oauth/callback
 ```
 
-`127.0.0.1` 和 `/oauth/callback` 固定不可配置。`3080` 是推荐的 DSH 端口；若修改 DSH WebServer 端口，OIDC 注册值必须使用相同端口。不要登记 `localhost`、局域网地址或公网地址。
+以下固定端口用于本机 Web 验证。新桌面默认临时随机端口，固定端口 IdP 的配置方法见 [桌面宿主接入](desktop-host.md)。`127.0.0.1` 和 `/oauth/callback` 固定不可配置。`3080` 是推荐的 DSH 端口；若修改 DSH WebServer 端口，OIDC 注册值必须使用相同端口。不要登记 `localhost`、局域网地址或公网地址。
 
 OIDC Provider 必须通过 Discovery 发布 `authorization_endpoint`、`token_endpoint`、`jwks_uri` 和 `userinfo_endpoint`，支持 PKCE `S256`，并返回：
 
@@ -43,7 +43,7 @@ OIDC Provider 必须通过 Discovery 发布 `authorization_endpoint`、`token_en
 
 ## 3. 实现完整机构服务端
 
-同一机构服务交付必须完整提供上一节的 OIDC、下面的 Key Binding，以及接受绑定凭据的 OpenAI-compatible 模型网关。它们可以由内部不同系统承载，但必须有统一的版本、安全和运维责任。接口定义见[服务端接口规范](server-integration-contract.md)。
+本节针对托管企业模型能力：需要上一节的 OIDC、下面的 Key Binding，以及接受绑定凭据的 OpenAI-compatible 模型网关。纯身份档可跳过本节。它们可以由内部不同系统承载，但必须有统一的版本、安全和运维责任。接口定义见[服务端接口规范](server-integration-contract.md)。
 
 Key Binding 不是 OIDC 标准的一部分，而是 `dsh-oidc` 定义的企业模型凭据协议。Enterprise Profile 用 `baseURL` 指定接口组基址，插件固定调用：
 
@@ -54,7 +54,7 @@ POST {baseURL}/runtime-credential/resolve
 POST {baseURL}/runtime-credential/renew
 ```
 
-Profile 还可以用可选的 `keyBinding.credentialRef` 隔离本地 DSH Credential Provider 中的秘密条目。它不参与网络请求，也不改变下列接口；普通单环境部署省略即可。生产/测试复用相同 Provider ID 时，应使用不同的引用名。
+Profile 还可以用可选的 `keyBinding.credentialRef` 隔离本地 DSH Credential Provider 中的秘密条目。它不参与网络请求，也不改变下列接口；默认统一为 `EDUWORK_API_KEY`，也接受同名显式配置；只有需要独立管理的自定义引用才另行指定。旧自动名称兼容迁移和身份归属校验见 [Profile 规范](enterprise-profile.md)。
 
 每个请求都携带 OIDC Access Token：
 
@@ -117,12 +117,14 @@ Authorization: Bearer <oidc-access-token>
 
 Profile 是部署配置，不是用户输入。它可以声明模型事实和有限品牌 token，但不能加载脚本、CSS、工具、Skill 或远程 Provider adapter。字段全集和安全限制见 [Enterprise Profile 规范](enterprise-profile.md)。
 
-## 5. 安装到普通 DSH Web
+## 5. 安装到本机 DSH Web
+
+本版采用精确的 `0.2.0` 与统一 DSH `0.1.5-rc.1`。发布状态以 npm registry 为准；若准备期间尚未发布，使用本地冻结候选或下方源码方式，不混装旧 DSH 依赖。
 
 `dsh-oidc` 本身是可直接安装的 DSH Bundle。团队部署应从 npm 安装经过复核的精确版本：
 
 ```bash
-dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0
+dsh plugin --profile web add @eduwork/dsh-oidc@0.2.0
 ```
 
 需要审计、开发或测试尚未发布的改动时，再从本地 checkout 安装：
@@ -146,14 +148,14 @@ DSH 会把本地 checkout 链接到 `$DSH_HOME/profiles/web`，不会扫描或
 设置 Enterprise Profile 路径，并让 DSH 监听固定 loopback host：
 
 ```bash
-export DSH_OIDC_ENTERPRISE_PROFILE=/etc/dsh/enterprise-profile.json
+export EDUWORK_OIDC_PROFILE=/etc/dsh/enterprise-profile.json
 dsh --profile web --host 127.0.0.1 --port 3080 --no-open
 ```
 
 PowerShell 示例：
 
 ```powershell
-$env:DSH_OIDC_ENTERPRISE_PROFILE = 'C:\dsh-config\enterprise-profile.json'
+$env:EDUWORK_OIDC_PROFILE = 'C:\dsh-config\enterprise-profile.json'
 dsh --profile web --host 127.0.0.1 --port 3080 --no-open
 ```
 
@@ -170,12 +172,12 @@ dsh --profile web --host 127.0.0.1 --port 3080 --no-open
     - id: enterprise-oidc
       name: '@eduwork/dsh-oidc'
       config:
-        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        profilePathEnv: EDUWORK_OIDC_PROFILE
         web:
           returnPath: /
 ```
 
-桌面宿主可以切换到 native backend：
+仅为兼容旧宿主，仍保留以下 native backend 示例：
 
 ```yaml
 - insert:
@@ -187,7 +189,7 @@ dsh --profile web --host 127.0.0.1 --port 3080 --no-open
         profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
 ```
 
-native backend 必须提供 `enterpriseAccounts` 服务，并与 Web 一样传入标准 Enterprise Profile。产品自有目录、租户或账号配置必须先由产品装配层转换为该 Profile，不能交给 `dsh-oidc` 解释。宿主可以由 Wails、Electron、Tauri 或其他技术实现；插件本身不依赖任何桌面框架或产品目录格式。接口和能力探测见 [DSH 集成说明](dsh-integration.md)。
+上面是旧版 `native` 桥接示例；新 Wails/Electron 组合应使用 `backend: desktop`，共用临时 loopback 回调与官方 `nativeCommand`，无需另写认证桥。见 [桌面 Host 集成](desktop-host.md)。旧 native backend 必须提供 `enterpriseAccounts` 服务，并与 Web 一样传入标准 Enterprise Profile。产品自有目录、租户或账号配置必须先由产品装配层转换为该 Profile，不能交给 `dsh-oidc` 解释。宿主可以由 Wails、Electron、Tauri 或其他技术实现；插件本身不依赖任何桌面框架或产品目录格式。接口和能力探测见 [DSH 集成说明](dsh-integration.md)。
 
 ## 7. 上线前验收
 
@@ -230,6 +232,6 @@ native backend 必须提供 `enterpriseAccounts` 服务，并与 Web 一样传
 
 插件会保留 thinking 行为并移除不受支持的 effort 参数，不会因此拒绝调用。
 
-### 为什么企业服务是单独的设置页
+### 企业服务设置在哪里
 
-当前 DSH `0.1.2-rc.1` 提供正式的 `settings.models.footer` 插槽。插件直接把企业模型管理能力挂载到官方“模型”页，并保持官方模型页启用，不再依赖产品私有的模型页 fork。
+插件通过官方 `settings.models.footer` 插槽显示已配置机构，保留官方“模型”设置页和个人 API Key。机构配置来自发行方的可信文件；产品可以提供打开配置文件的入口，插件不提供任意创建或修改机构端点的表单。

package/docs/key-binding-protocol.en.md

@@ -6,7 +6,7 @@
 
 This document defines `worker-user-center-v1`, the enterprise management protocol used by `dsh-oidc` to bind an OIDC-authenticated subject to a model runtime API key. It is not part of OIDC.
 
-It is a required part of the [server API specification](server-integration-contract.en.md). An implementation must also provide the OIDC Provider and model gateway required by that specification; implementing only the API below is not a complete `dsh-oidc` server.
+It is part of the managed-model tier of the [server API specification](server-integration-contract.en.md), delivered together with the OIDC Provider and model gateway. Identity-only Profiles do not require Key Binding.
 
 The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and **OPTIONAL** are interpreted as described by RFC 2119 and RFC 8174.
 
@@ -105,7 +105,7 @@ Valid `runtime_credential.status` values are:
 
 `subject` MAY carry informational management-plane display data. The client MUST NOT use it to replace OIDC `sub` or `name`.
 
-`protocol_version`, if present, MUST be `worker-user-center/v1`. It is optional during v1 adoption; a future major protocol can require explicit negotiation.
+`protocol_version`, if present, MUST be `worker.user-center.v1`, `worker-user-center/v1` or `eduwork-resources/v1` (aliases of the same v1 wire; unknown versions are rejected). It is optional during v1 adoption; a future major protocol can require explicit negotiation.
 
 ## 6. Provision
 

package/docs/key-binding-protocol.md

@@ -6,7 +6,7 @@
 
 本文定义 `worker-user-center-v1`：`dsh-oidc` 用它把经 OIDC 认证的 subject 与模型运行时 API Key 绑定。这是企业管理协议，不属于 OIDC 标准。
 
-它是[服务端接口规范](server-integration-contract.md)的必需组成部分。实现方必须同时提供该规范要求的 OIDC Provider 与模型网关；只实现以下 API 不构成完整的 `dsh-oidc` 服务端。
+它是[服务端接口规范](server-integration-contract.md)中托管模型能力档的组成部分，需与 OIDC Provider 和模型网关共同实现。纯身份 Profile 不要求 Key Binding。
 
 关键词 **必须（MUST）**、**不得（MUST NOT）**、**必需（REQUIRED）**、**应该（SHOULD）**、**不应该（SHOULD NOT）**、**建议（RECOMMENDED）**、**不建议（NOT RECOMMENDED）**、**可以（MAY）** 和 **可选（OPTIONAL）** 按 RFC 2119 与 RFC 8174 解释。
 
@@ -105,7 +105,7 @@ Accept: application/json
 
 `subject` 可以携带仅供管理面显示的信息。客户端不得用它替换 OIDC `sub` 或 `name`。
 
-若返回 `protocol_version`，其值必须是 `worker-user-center/v1`。该字段在 v1 采用阶段可选；未来 major 协议可以要求显式协商。
+若返回 `protocol_version`，其值必须是 `worker.user-center.v1`、`worker-user-center/v1` 或 `eduwork-resources/v1`（三个别名共享同一组 v1 字段与路径，未知版本拒绝）。该字段在 v1 采用阶段可选；未来 major 协议可以要求显式协商。
 
 ## 6. Provision
 

package/docs/oidc-interoperability.en.md

@@ -2,7 +2,7 @@
 
 [简体中文](oidc-interoperability.md) | **English**
 
-OIDC is one part of the [server API specification](server-integration-contract.en.md). A conforming integration also requires the same accountable service owner to jointly deliver fixed Key Binding and the model gateway; implementing this document alone is not complete.
+OIDC is the identity tier of the [server API specification](server-integration-contract.en.md). An identity-only Profile may implement this tier alone. Managed enterprise keys and automatic model setup additionally require Key Binding and the model gateway.
 
 ## Standards
 
@@ -93,8 +93,8 @@ The plugin intentionally has no JSON path mapping or private profile endpoint. O
 
 ## Refresh and logout
 
-If the access token is within 90 seconds of expiry and a refresh token exists, the plugin refreshes it. On `invalid_grant`, the stored OIDC session and local model credential are removed and login is required. A rotated refresh token replaces the previous one. An expired session without a refresh token is handled the same way when an active session is next required.
+If the access token is within 90 seconds of expiry and a refresh token exists, the plugin refreshes it. On `invalid_grant`, the stored OIDC session and its still-owned local model credential are removed and login is required. A rotated refresh token replaces the previous one. An expired session without a refresh token is handled the same way when an active session is next required.
 
-Logout attempts RFC 7009 revocation when Discovery publishes `revocation_endpoint`, then removes both the OIDC session record and the derived model credential locally. Remote revocation failure is logged without blocking local cleanup.
+Logout attempts RFC 7009 revocation when Discovery publishes `revocation_endpoint`, then removes the OIDC session record and only a model credential still owned by that session. A key written by another profile into the shared reference is preserved. Remote revocation failure is logged without blocking local cleanup.
 
 The plugin does not implement RP-Initiated Logout or front/back-channel logout in this version.

package/docs/oidc-interoperability.md

@@ -2,7 +2,7 @@
 
 **简体中文** | [English](oidc-interoperability.en.md)
 
-OIDC 是[服务端接口规范](server-integration-contract.md)的一部分。合格的机构接入还必须由同一服务所有者联合提供固定 Key Binding 和模型网关能力；只实现本文件并不构成完整接入。
+OIDC 是[服务端接口规范](server-integration-contract.md)的身份能力档，纯身份 Profile 可只实现本文件。只有需要托管模型 Key 和自动配置企业模型时，才必须同时提供 Key Binding 和模型网关。
 
 ## 标准依据
 
@@ -95,6 +95,6 @@ TLS 信任和 DNS 解析仍由 Node.js 宿主和操作系统负责。
 
 当 access token 距离过期不足 90 秒且存在 refresh token 时，插件会刷新会话。若收到 `invalid_grant`，会删除已存 OIDC 会话和本地模型凭据，并要求重新登录。轮换后的 refresh token 会替换旧值。没有 refresh token 的过期会话在下次需要活动会话时按同样方式处理。
 
-退出登录时，如果 Discovery 发布 `revocation_endpoint`，插件会尝试按 RFC 7009 撤销 token；随后在本地删除 OIDC 会话记录和派生模型凭据。远程撤销失败会被记录，但不阻止本地清理。
+退出登录时，如果 Discovery 发布 `revocation_endpoint`，插件会尝试按 RFC 7009 撤销 token；随后在本地删除该 Profile 的 OIDC 会话与归属于它的托管模型凭据；共享引用已被其他登录改写时不会删除另一方的 Key。远程撤销失败会被记录，但不阻止本地清理。
 
 当前版本不实现 RP-Initiated Logout、front-channel logout 或 back-channel logout。