@eduwork/dsh-oidc 0.2.3 → 0.3.0-dev.1

package/docs/desktop-host.md

@@ -1,67 +1,66 @@
-# 无常驻 Web 服务的桌面宿主
-
-[English](desktop-host.en.md)
-
-本地候选 `0.2.0-dev.20260910.1` 新增 `backend: desktop`。它复用 Web 后端的 OIDC 校验、Host credentials、Key Binding、模型发现协议，只替换登录回调传输。既有 `web` 和 Go 桥 `native` 配置继续可用。
-
-```yaml
-- id: enterprise-oidc
-  name: '@eduwork/dsh-oidc'
-  config:
-    backend: desktop
-    allowEmptyProfiles: true
-    profilePathEnv: EDUWORK_OIDC_PROFILE
-    desktop:
-      callbackPort: 0
-      flowTimeoutMs: 600000
-```
-
-宿主应注册 Cordis `desktopServices` 服务，提供 Host-only 方法：
-
-```ts
-openExternal(url: string): Promise<void>
-// 可选：仅打开宿主预先确定的配置文件或示例目录。
-openConfiguration(target: 'config' | 'examples'): Promise<void>
-```
-
-OIDC 从受信 Profile 对应的 Discovery 构造 HTTP(S) 授权 URL。此 URL 只交给 Host 服务；浏览器侧不能传入自选 URL。外壳负责用系统浏览器打开，拒绝非 HTTP(S)、userinfo URL，并且不得记录授权查询参数。插件不自行执行系统命令，不依赖 Electron/Wails 的 JavaScript 包。服务可以稍后加载；移除服务会取消尚未完成的登录。
-
-发行方提供 `configFile: {path, examplesPath}` 时，企业服务保持只读，由用户编辑文件后重启应用。若宿主提供 `openConfiguration`，设置显示“打开配置文件”和“查看示例”；RPC 只接收 `config` / `examples`，由宿主解析固定路径，不允许 renderer 传路径或命令。`configuration().configFile.canOpen` 声明是否可直接打开；Web 或未提供该能力的宿主显示配置文件位置作为备用。个人 API Key 设置和已配置企业的身份登录继续可用。
-
-资源绑定兼容既有 `worker.user-center.v1`、过渡写法 `worker-user-center/v1` 与 `eduwork-resources/v1`。未知版本或不匹配的 Provider ID 在创建模型凭据前拒绝，保留已完成的身份登录，并提示检查模型资源服务或企业配置；它们不是身份验证失败。
-
-宿主必须提供 `credentials.resolve/set/unset`。本插件没有明文凭据文件或存储失败后的备用路径；桌面发行方负责接入操作系统保险库。模型调用仍使用独立运行 Key，OAuth token 不经 RPC 返回 renderer。`oidcAccounts.authorizedFetch()` 仍是 Host-only 公共授权请求入口。
-
-只有用户点击登录时才监听 `127.0.0.1`。默认随机端口，回调为 `http://127.0.0.1:<port>/oauth/callback`；需在身份提供方注册支持动态 loopback 端口的公共 PKCE 客户端。若身份提供方只接受精确回调端口，可在受信配置固定 `callbackPort`（端口占用时明确失败，不改用未注册端口）。不支持配置其他监听地址。取消、失效、成功、合法回调失败、服务卸载和 Host 退出均清理监听。错误路径、Host、Origin、state 或 HTTP 方法不会消费合法的待登录状态。
-
-RPC 扩展（共用 Host/Client Typert schema）：
-
-| 方法 | 返回 |
-| --- | --- |
-| `begin(profileID)` | 桌面返回 `{mode:'external', loginID, expiresAt}`；Web 仍返回 `redirect`，旧 native 仍可返回 `completed`。 |
-| `loginStatus(loginID)` | `{loginID, profileID, state, expiresAt, status?, errorCode?}`。state 为 pending/completed/cancelled/expired/failed。 |
-| `cancelLogin(loginID)` | 同上；等待正在写入的登录撤回，避免取消后重新出现凭据。 |
-| `openConfiguration(target)` | 文件管理模式下返回 `{opened:true}`；目标仅为 `config` / `examples`。系统打开失败时返回简短提示。 |
-| `selectEnterpriseModel(profileID, {onlyIfMissing?})` | DSH 0.1.5 上返回 `{changed, selection?}`，通过官方 `agentDefaultModel.saveSelection()` 保存企业默认模型。 |
-
-客户端账号快照由登录页、侧栏和企业设置共享。宿主凭据 Provider 应在 set/unset 后按官方契约发出 `credentials/reference-updated`；客户端监听该标准 Remote 事件及 `connection/reset`，不依赖不会由官方 Remote 转发的自定义账号事件。
-
-明确登录并连接 Key 或确认创建 Key 后，自动选择企业目录中第一个可解析模型。还没有会话时也会保存未来会话的默认值；存在主会话时通过官方 `modelDirectories.directoryFor(sessionID).select()` 同步当前选择，不改子代理。宿主应加载官方 `agentDefaultModel` 和可写 `settings` 服务。旧宿主缺少此能力时明确提示从模型菜单选择。
-
-升级后的首次加载使用 `onlyIfMissing:true`：已有有效默认值则保留，缺失或已不能解析才修复；当前会话中可用的个人选择也保留。凭据事件、检查连接和后续状态刷新不会切模型，个人 Key 与其他设置不受影响。
-
-双桌面联调可运行 `node scripts/serve-desktop-oidc-fixture.mjs --config <新的测试配置文件>`。脚本只绑定本机随机端口，生成合成身份、完整 HTTP PKCE/Key/模型/配额服务及公开 JSONC 配置；配置文件必须不存在，不覆盖用户配置。每套外壳使用独立测试数据目录；用 Ctrl+C 关闭服务。服务不接触真实账号，也不消耗模型额度。
-
-`loginID` 是独立随机句柄，不是 OAuth state。响应不包含授权 URL、code、nonce、PKCE verifier 或 token。前端以一秒间隔轮询，显示在浏览器中完成登录与取消按钮；登录最长十分钟，页面卸载取消尚未完成的尝试。关闭外部浏览器无法被跨平台可靠检测，用户可在应用中取消，或等待短时监听过期。
-
-空 Profile 是有效配置，不会监听端口，也不要求机构登录。纯身份 Profile 不要求资源端点；登出仅移除该机构的身份/托管 Key，个人 API Key 保留。身份登录成功后资源接口暂不可用时保留已登录身份，后续可以重试资源连接。
-
-验证入口：`node --test test/desktop.test.js test/desktop-host.test.js`。后者可通过 `DSH_OIDC_PACKAGE_ROOT` 指向安装的冻结包目录，并设置 `DSH_OIDC_EXPECT_DSH=0.1.5-rc.1`，使用该安装目录的真实 DSH 依赖运行无 WebServer 的 Host、可选浏览器服务和 loopback PKCE 验证。所有凭据与用户均为测试合成值；产品主进程保险库、窗口和操作系统浏览器行为仍由发行方联合验收。
-
-`.20260910.6` 的公共侧栏头像显示账户刷新和注销；配额内容由可选机构扩展提供。菜单通过 portal 支持收窄侧栏；支持方向键、Home/End、Escape、外部点击/失焦关闭。注销清理该机构本地身份、模型 Key、模型元数据缓存，序列化保险库写操作并拒绝旧请求写回；个人 Key 不受影响。
-
-临时 HTTP 回调页读取本次 Profile 的 `brand.productName/organizationName/logoURL/mark/primaryColor`，按浏览器 Accept-Language 选择中英文。没有外部字体、脚本或原始错误回显，清楚提示返回应用。普通 Web 验证仍跳回本地应用；不会把生产模型 Key 交给浏览器。
-
+# 无常驻 Web 服务的桌面宿主
+
+[English](desktop-host.en.md)
+
+`backend: desktop` 通过临时 loopback 回调接入桌面登录，复用 Web 后端的 OIDC 校验、Host credentials、Token 刷新和模型发现。支持 web 和 desktop；旧 native 账户桥已移除。
+
+```yaml
+- id: enterprise-oidc
+  name: '@eduwork/dsh-oidc'
+  config:
+    backend: desktop
+    allowEmptyProfiles: true
+    profilePathEnv: EDUWORK_OIDC_PROFILE
+    desktop:
+      callbackPort: 0
+      flowTimeoutMs: 600000
+```
+
+宿主应注册 Cordis `desktopServices` 服务，提供 Host-only 方法：
+
+```ts
+openExternal(url: string): Promise<void>
+// 可选：仅打开宿主预先确定的配置文件或示例目录。
+openConfiguration(target: 'config' | 'examples'): Promise<void>
+```
+
+OIDC 从受信 Profile 对应的 Discovery 构造 HTTP(S) 授权 URL。此 URL 只交给 Host 服务；浏览器侧不能传入自选 URL。外壳负责用系统浏览器打开，拒绝非 HTTP(S)、userinfo URL，并且不得记录授权查询参数。插件不自行执行系统命令，不依赖 Electron/Wails 的 JavaScript 包。服务可以稍后加载；移除服务会取消尚未完成的登录。
+
+发行方提供 `configFile: {path, examplesPath}` 时，企业服务保持只读，由用户编辑文件后重启应用。若宿主提供 `openConfiguration`，设置显示“打开配置文件”和“查看示例”；RPC 只接收 `config` / `examples`，由宿主解析固定路径，不允许 renderer 传路径或命令。`configuration().configFile.canOpen` 声明是否可直接打开；Web 或未提供该能力的宿主显示配置文件位置作为备用。个人 API Key 设置和已配置企业的身份登录继续可用。
+
+
+宿主必须提供 `credentials.resolve/set/unset`。本插件没有明文凭据文件或存储失败后的备用路径；桌面发行方负责接入操作系统保险库。模型调用使用当前 Access Token，OAuth token 不经 RPC 返回 renderer。`oidcAccounts.authorizedFetch()` 仍是 Host-only 公共授权请求入口。
+
+只有用户点击登录时才监听 `127.0.0.1`。默认随机端口，回调为 `http://127.0.0.1:<port>/oauth/callback`；需在身份提供方注册支持动态 loopback 端口的公共 PKCE 客户端。若身份提供方只接受精确回调端口，可在受信配置固定 `callbackPort`（端口占用时明确失败，不改用未注册端口）。不支持配置其他监听地址。取消、失效、成功、合法回调失败、服务卸载和 Host 退出均清理监听。错误路径、Host、Origin、state 或 HTTP 方法不会消费合法的待登录状态。
+
+RPC 扩展（共用 Host/Client Typert schema）：
+
+| 方法 | 返回 |
+| --- | --- |
+| `begin(profileID)` | 桌面返回 `{mode:'external', loginID, expiresAt}`；Web 仍返回 `redirect`。 |
+| `loginStatus(loginID)` | `{loginID, profileID, state, expiresAt, status?, errorCode?}`。state 为 pending/completed/cancelled/expired/failed。 |
+| `cancelLogin(loginID)` | 同上；等待正在写入的登录撤回，避免取消后重新出现凭据。 |
+| `openConfiguration(target)` | 文件管理模式下返回 `{opened:true}`；目标仅为 `config` / `examples`。系统打开失败时返回简短提示。 |
+| `selectEnterpriseModel(profileID, {onlyIfMissing?})` | DSH 0.1.5 上返回 `{changed, selection?}`，通过官方 `agentDefaultModel.saveSelection()` 保存企业默认模型。 |
+
+客户端账号快照由登录页、侧栏和企业设置共享。宿主凭据 Provider 应在 set/unset 后按官方契约发出 `credentials/reference-updated`；客户端监听该标准 Remote 事件及 `connection/reset`，不依赖不会由官方 Remote 转发的自定义账号事件。
+
+明确登录并连接模型后，自动选择企业目录中第一个可解析模型。还没有会话时也会保存未来会话的默认值；存在主会话时通过官方 `modelDirectories.directoryFor(sessionID).select()` 同步当前选择，不改子代理。宿主应加载官方 `agentDefaultModel` 和可写 `settings` 服务。旧宿主缺少此能力时明确提示从模型菜单选择。
+
+升级后的首次加载使用 `onlyIfMissing:true`：已有有效默认值则保留，缺失或已不能解析才修复；当前会话中可用的个人选择也保留。凭据事件、检查连接和后续状态刷新不会切模型，个人 Key 与其他设置不受影响。
+
+双桌面联调可运行 `node scripts/serve-desktop-oidc-fixture.mjs --config <新的测试配置文件>`。脚本只绑定本机随机端口，生成合成身份、完整 HTTP PKCE/Token/模型/配额服务及公开 JSONC 配置；配置文件必须不存在，不覆盖用户配置。每套外壳使用独立测试数据目录；用 Ctrl+C 关闭服务。服务不接触真实账号，也不消耗模型额度。
+
+`loginID` 是独立随机句柄，不是 OAuth state。响应不包含授权 URL、code、nonce、PKCE verifier 或 token。前端以一秒间隔轮询，显示在浏览器中完成登录与取消按钮；登录最长十分钟，页面卸载取消尚未完成的尝试。关闭外部浏览器无法被跨平台可靠检测，用户可在应用中取消，或等待短时监听过期。
+
+空 Profile 是有效配置，不会监听端口，也不要求机构登录。纯身份 Profile 不要求资源端点；登出仅移除该机构的身份/Token，个人 API Key 保留。身份登录成功后资源接口暂不可用时保留已登录身份，后续可以重试资源连接。
+
+验证入口：`node --test test/desktop.test.js test/desktop-host.test.js`。后者可通过 `DSH_OIDC_PACKAGE_ROOT` 指向安装的冻结包目录，并设置 `DSH_OIDC_EXPECT_DSH=0.1.5-rc.1`，使用该安装目录的真实 DSH 依赖运行无 WebServer 的 Host、可选浏览器服务和 loopback PKCE 验证。所有凭据与用户均为测试合成值；产品主进程保险库、窗口和操作系统浏览器行为仍由发行方联合验收。
+
+`.20260910.6` 的公共侧栏头像显示账户刷新和注销；配额内容由可选机构扩展提供。菜单通过 portal 支持收窄侧栏；支持方向键、Home/End、Escape、外部点击/失焦关闭。注销清理该机构本地身份、Token、模型元数据缓存，序列化保险库写操作并拒绝旧请求写回；个人 Key 不受影响。
+
+临时 HTTP 回调页读取本次 Profile 的 `brand.productName/organizationName/logoURL/mark/primaryColor`，按浏览器 Accept-Language 选择中英文。没有外部字体、脚本或原始错误回显，清楚提示返回应用。普通 Web 验证仍跳回本地应用；不会把Token 交给浏览器。
+
 在与目标 DSH 完全一致的隔离依赖树运行 `npm run check`，不要从旧版本根依赖构建后标为新基线。可再运行 `npm run check:browser`：使用该 Runtime 的 `playwright-core` 和本机 Edge 无头浏览器（可用 `DSH_OIDC_BROWSER_CHANNEL` 指定 Chrome），直接加载编译客户端，验证菜单/多个组件共享状态/注销，并生成品牌回调截图。本检查不替代主进程保险库与真实操作系统浏览器联验。
 
 ## macOS 接手验收

package/docs/development.en.md

@@ -1,44 +1,44 @@
-# Development and release preparation
-
-[简体中文](development.md) | **English**
-
-The plugin version is `0.2.0`. Its development baseline is DSH `0.1.5-rc.1`, Cordis `4.0.2`, and pi-ai `0.85.1`. Product versions do not determine plugin versions; consult the registry for npm publication status. This stable-version freeze does not change dev.7 runtime sources or replace earlier frozen artifacts.
-
-## Verify a clean checkout
-
-Use Node.js 22 or 24 in this repository:
-
-```sh
-npm ci
-npm run check
-```
-
-The manifest declares exact development dependencies for the required DSH test closure, and the lock records public-registry URLs and integrity. Upstream prerelease carets may select a later RC, so pinning only direct peers is insufficient. `check:lock` rejects mixed versions, machine paths and missing integrity; `check:dsh` verifies the actually loaded baseline. Do not substitute junctions into a running desktop for a clean installation, or suppress conflicts with `--force` or `--legacy-peer-deps`.
-
-This is the plugin's development/CI closure, not a full desktop product. Consumers still reuse the host through peerDependencies. The [compatibility matrix](compatibility.en.md) distinguishes historical evidence; a historical peer declaration does not mean every old combination was rerun for each commit.
-
-The complete check covers TypeScript, the dependency lock and official contracts, Host/Client builds and loading, Node tests, schemas/examples, document links, sensitive-data/license scans, and package inspection. Optional `npm run check:browser` uses Playwright Core with a locally installed Edge/Chrome; `DSH_OIDC_BROWSER_CHANNEL` selects the installed channel (default `msedge`). It downloads no browser and does not replace real distribution login acceptance.
-
-## Source map
-
-| Path | Responsibility |
-| --- | --- |
-| `src/host/profile.js` | Trusted Profile, bounded branding/models and common credential reference |
-| `src/host/oidc.js` | PKCE, Token/UserInfo, Key Binding, sessions and credential ownership |
-| `src/host/desktop-oidc.js` | Temporary loopback login shared by both desktop shells |
-| `src/host/resources.js` | Conservative model-catalog normalization |
-| `src/host/provider/` | Official PiAi Provider and explicit image-transform boundary |
-| `src/host/index.js`, `typert.*.js` | Host service, official lifecycle and public RPC |
-| `src/client/` | Official settings slots, account/login UI and bounded branding |
-| `test/` | Synthetic IdP/gateway, HTTP, Host, migration and race regressions |
-| `schema/`, `protocol/` | Profile Schema and implemented resource HTTP contracts |
-
-`scripts/build-host.mjs` copies native Host ESM to `lib`; tsdown bundles the Client. Do not edit `lib` by hand. New wire fields require corresponding implementation, Schema/OpenAPI, bilingual documentation and contract tests. Avoid mechanical tests for simple presentation/documentation changes.
-
-## Public scope and remaining release work
-
-The public package owns identity, managed keys, model discovery/inference and their account UI. Quota, heartbeat, campus search and speech business services belong in institution/product plugins. [Account extensions](account-extensions.en.md) are Host transport and slot contracts, not hidden institution-feature switches. Examples contain placeholder domains, public client IDs and no secrets.
-
-CI defines Windows/Linux × Node 22/24. A local Windows result does not cover unexecuted matrix cells. Before joint publication, complete the matrix, deployment acceptance and history/supply-chain review on the selected commit, then freeze the stable version, tag and tarball using the [release checklist](release-checklist.en.md). Existing npm versions and frozen artifacts are not rewritten. Local preparation does not push, release or publish.
-
-Reasoning-field compatibility and its regression checks are documented in [Reasoning replay compatibility](reasoning-replay.en.md). The guide distinguishes a source fix from the installed npm package.
+# Development and release preparation
+
+[简体中文](development.md) | **English**
+
+The plugin version is `0.2.3`. Its development baseline is DSH `0.1.5-rc.1`, Cordis `4.0.2`, and pi-ai `0.85.1`. Product versions do not determine plugin versions; consult the registry for npm publication status. Source is maintained in EduWork; migration does not overwrite published npm packages.
+
+## Verify a clean checkout
+
+Use Node.js 22 or 24 in `EduWork/packages/dsh-oidc`:
+
+```sh
+npm ci
+npm run check
+```
+
+The manifest declares exact development dependencies for the required DSH test closure, and the lock records public-registry URLs and integrity. Upstream prerelease carets may select a later RC, so pinning only direct peers is insufficient. `check:lock` rejects mixed versions, machine paths and missing integrity; `check:dsh` verifies the actually loaded baseline. Do not substitute junctions into a running desktop for a clean installation, or suppress conflicts with `--force` or `--legacy-peer-deps`.
+
+This is the plugin's development/CI closure, not a full desktop product. Consumers still reuse the host through peerDependencies. The [compatibility matrix](compatibility.en.md) distinguishes historical evidence; a historical peer declaration does not mean every old combination was rerun for each commit.
+
+The complete check covers TypeScript, the dependency lock and official contracts, Host/Client builds and loading, Node tests, schemas/examples, document links, sensitive-data/license scans, and package inspection. Optional `npm run check:browser` uses Playwright Core with a locally installed Edge/Chrome; `DSH_OIDC_BROWSER_CHANNEL` selects the installed channel (default `msedge`). It downloads no browser and does not replace real distribution login acceptance.
+
+## Source map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/host/profile.js` | Trusted Profile, bounded branding/models and common credential reference |
+| `src/host/oidc.js` | PKCE, Token/UserInfo, identity sessions and credential writes |
+| `src/host/desktop-oidc.js` | Temporary loopback login shared by both desktop shells |
+| `src/host/resources.js` | Conservative model-catalog normalization |
+| `src/host/provider/` | Official PiAi Provider and explicit image-transform boundary |
+| `src/host/index.js`, `typert.*.js` | Host service, official lifecycle and public RPC |
+| `src/client/` | Official settings slots, account/login UI and bounded branding |
+| `test/` | Synthetic IdP/gateway, HTTP, Host, migration and race regressions |
+| `schema/`, `protocol/` | Profile Schema and implemented resource HTTP contracts |
+
+`scripts/build-host.mjs` copies native Host ESM to `lib`; tsdown bundles the Client. Do not edit `lib` by hand. New wire fields require corresponding implementation, Schema/OpenAPI, bilingual documentation and contract tests. Avoid mechanical tests for simple presentation/documentation changes.
+
+## Extensions and publication
+
+The public package owns identity, token authorization, model discovery/inference and their account UI. Quota, heartbeat, campus search and speech business services belong in institution/product plugins. [Account extensions](account-extensions.en.md) are Host transport and slot contracts, not hidden institution-feature switches. Examples contain placeholder domains, public client IDs and no secrets.
+
+Module checks and publication use the [shared EduWork workflow](https://github.com/ecnu/EduWork/blob/main/docs/PACKAGES_EN.md). Validate deployment-specific sign-in separately; published npm versions are immutable.
+
+Reasoning-field compatibility and its regression checks are documented in [Reasoning replay compatibility](reasoning-replay.en.md). The guide distinguishes a source fix from the installed npm package.

package/docs/development.md

@@ -2,11 +2,11 @@
 
 **简体中文** | [English](development.en.md)
 
-当前插件版本为 `0.2.0`，开发基线是 DSH `0.1.5-rc.1`、Cordis `4.0.2`、pi-ai `0.85.1`。产品版本不决定插件版本；npm 发布状态以 registry 为准。本次稳定版本冻结不改动 dev.7 的运行源码，也不替换既有冻结 tarball。
+当前插件版本为 `0.2.3`，开发基线是 DSH `0.1.5-rc.1`、Cordis `4.0.2`、pi-ai `0.85.1`。产品版本不决定插件版本；npm 发布状态以 registry 为准。源码位于 EduWork 的 `packages/dsh-oidc`。
 
 ## 从干净 checkout 验证
 
-使用 Node.js 22 或 24，在本仓库执行：
+使用 Node.js 22 或 24，在 `EduWork/packages/dsh-oidc` 执行：
 
 ```sh
 npm ci
@@ -24,7 +24,7 @@ npm run check
 | 路径 | 职责 |
 | --- | --- |
 | `src/host/profile.js` | 可信 Profile、受限品牌/模型配置、统一凭据引用 |
-| `src/host/oidc.js` | PKCE、Token/UserInfo、Key Binding、会话与凭据归属 |
+| `src/host/oidc.js` | PKCE、Token/UserInfo、身份会话与凭据写入 |
 | `src/host/desktop-oidc.js` | 两种桌面外壳共用的临时 loopback 登录 |
 | `src/host/resources.js` | 模型目录的保守归一化 |
 | `src/host/provider/` | 官方 PiAi Provider 和显式图像转换边界 |
@@ -37,8 +37,8 @@ Host ESM 由 `scripts/build-host.mjs` 复制至 `lib`，Client 由 tsdown 打包
 
 思考内容的字段兼容与回归入口见[思考内容回传兼容](reasoning-replay.md)。该说明区分源码修复与已安装插件包，避免沿用旧 npm 锁时误判为修复已交付。
 
-## 开源边界与发布待办
+## 扩展与发布
 
-公共包只拥有身份、托管 Key、模型目录/调用及对应账号 UI。配额、心跳、校内检索和语音业务由机构/产品插件负责；[账户扩展](account-extensions.md)是 Host 运输与插槽边界，不是暗中启用机构功能的开关。所有示例均使用占位域名、Public Client ID 与无秘密配置。
+公共包只拥有身份、Token 授权、模型目录/调用及对应账号 UI。配额、心跳、校内检索和语音业务由机构/产品插件负责；[账户扩展](account-extensions.md)是 Host 运输与插槽边界，不是暗中启用机构功能的开关。所有示例均使用占位域名、Public Client ID 与无秘密配置。
 
-CI 声明 Windows/Linux × Node 22/24；本机 Windows 的结果不能代替尚未执行的矩阵单元。下一次共同发行前，应在目标提交上完成矩阵、实际部署联调、历史与供应链审查，再按[发布检查表](release-checklist.md)冻结正式版本、tag 与 tarball。既有 npm 版本和本地冻结包不改写；本地准备不执行 push、release 或 publish。
+模块通过 EduWork 的统一工作流检查和发布，参见[包维护说明](https://github.com/ecnu/EduWork/blob/main/docs/PACKAGES.md)。依赖锁、合成测试与实际部署登录分别验证；发布包使用新版本，不覆盖已有 npm 版本。

package/docs/dsh-integration.en.md

@@ -12,7 +12,7 @@ The plugin uses public package exports rather than copied DSH source:
 | --- | --- |
 | `dsh-typert-protocol` | Host/client RPC descriptors. |
 | `dsh-host-webserver` | Exact `/oauth/callback` route. |
-| `dsh-credentials` | Session and runtime API-key storage. |
+| `dsh-credentials` | Authorization session storage. |
 | `dsh-llm` | Adapter registry, credentials, retry policy, stable errors. |
 | `dsh-llm-pi-ai` | Official `PiAiAdapter`. |
 | `dsh-settings` | Provider directory/readiness facts. |
@@ -23,7 +23,7 @@ The OpenAI-compatible wire implementation comes from `@earendil-works/pi-ai`, wh
 
 ## Why the Provider adapter is inside this package
 
-OIDC authentication alone does not yield a callable enterprise model. A closed-loop integration also needs a stable Provider route whose credential reference matches Key Binding output. Publishing a second organization-specific Provider package would recreate the coupling this repository is meant to remove.
+OIDC authentication alone does not yield a callable enterprise model. A closed-loop integration also needs a stable Provider route whose credential reference matches current token authorization. Publishing a second organization-specific Provider package would recreate the coupling this repository is meant to remove.
 
 The adapter is therefore an internal module of `dsh-oidc`, but its behavior is constrained:
 
@@ -49,12 +49,12 @@ The default export is `OidcAccountService`, a `TypertRemoteService` named `oidcA
 | `loginStatus(loginID)` / `cancelLogin(loginID)` | Poll or cancel the current desktop attempt. |
 | `resources(profileID)` | Model metadata and issues, without quota or secrets. |
 | `selectEnterpriseModel(profileID, options)` | Select a verified connected model through official defaults; no arbitrary Provider destination. |
-| `reconcile(profileID, {allowProvision})` | Bootstrap and resolve/provision/renew. |
+| `reconcile(profileID, {})` | Refresh authorization and model resources. |
 | `logout(profileID)` | Local cleanup and best-effort OIDC revocation. |
 | `management()` | Capability-aware projection consumed by the shared enterprise-model settings UI. |
 | `activate/configure/addCustom/updateCustom/removeProfile/configureModels/restart` | Optional native management operations; Web profiles reject mutation. |
 
-The client descriptor uses strict Zod codecs. Configuration sent to the browser excludes issuer, client ID, Key Binding base, model base URL, tokens, and keys.
+The client descriptor uses strict Zod codecs. Configuration sent to the browser excludes issuer, client ID, , model base URL, tokens, and keys.
 
 ## Web composition
 
@@ -71,8 +71,8 @@ dsh plugin --profile web add @eduwork/dsh-oidc@0.2.0
 For auditing, development, or validating unpublished changes, install a reviewed local checkout instead:
 
 ```bash
-git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
-cd dsh-oidc
+git clone https://github.com/ecnu/EduWork.git
+cd EduWork/packages/dsh-oidc
 npm ci
 npm run check
 dsh plugin --profile web add .
@@ -80,7 +80,7 @@ dsh plugin --profile web add .
 
 The local-path install links the checkout into the Profile, so the source directory must remain available. It does not scan the current workspace. Team deployments should pin a reviewed, exact npm version and must not mix another DSH prerelease line into the same Profile.
 
-The shipped patch mounts exactly one `enterprise-oidc` instance using `EDUWORK_OIDC_PROFILE`. The Web backend requires the DSH WebServer to listen exactly on `127.0.0.1` and builds the fixed `/oauth/callback` from its actual port; no public callback-origin setting is accepted. The patch does not hard-code `agent-default-model`; after explicit login/key binding, the Client selects the connected organization model through official APIs. Restart recovery only repairs an unusable default and preserves personal selections. `DSH_OIDC_ENTERPRISE_PROFILE` remains a fallback.
+The shipped patch mounts exactly one `enterprise-oidc` instance using `EDUWORK_OIDC_PROFILE`. The Web backend requires the DSH WebServer to listen exactly on `127.0.0.1` and builds the fixed `/oauth/callback` from its actual port; no public callback-origin setting is accepted. The patch does not hard-code `agent-default-model`; after explicit gateway login, the Client selects the connected organization model through official APIs. Restart recovery only repairs an unusable default and preserves personal selections. `DSH_OIDC_ENTERPRISE_PROFILE` remains a fallback.
 
 ### Product-owned Bundle
 
@@ -101,50 +101,15 @@ The shipped patch mounts exactly one `enterprise-oidc` instance using `EDUWORK_O
 
 The containing DSH profile/bundle must also include the ordinary Web app, credentials, LLM/Pi adapter dependencies, settings, attachment services, and client surfaces. `dsh-oidc` is not a complete DSH distribution.
 
-See the [getting-started guide](getting-started.en.md) for OIDC registration, Key Binding implementation, environment variables, acceptance, and troubleshooting.
+See the [getting-started guide](getting-started.en.md) for OIDC registration, Token gateway implementation, environment variables, acceptance, and troubleshooting.
 
 ## Desktop composition
 
-New Wails/Electron products use `backend: desktop`: the plugin owns a temporary loopback callback and opens the browser through official `nativeCommand`. Both shells share identity, Key Binding and model behavior. The host still provides credential storage; no new `enterpriseAccounts` bridge is required. See [desktop host integration](desktop-host.en.md).
+New Wails/Electron products use `backend: desktop`: the plugin owns a temporary loopback callback and opens the browser through official `nativeCommand`. Both shells share identity, token lifecycle and model behavior. The host still provides credential storage; no new `enterpriseAccounts` bridge is required. See [desktop host integration](desktop-host.en.md).
 
 ## Legacy native bridge
 
-The following adapter interface is only for existing integrations. It is not required for a new desktop:
-
-```yaml
-- insert:
-    - id: enterprise-oidc
-      name: '@eduwork/dsh-oidc'
-      config:
-        backend: native
-        uiMode: models-only
-        profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
-```
-
-The host supplies Cordis service `enterpriseAccounts`. Any product-owned institution catalog MUST first be converted by the host or assembly layer into a standard Enterprise Profile; `dsh-oidc` does not read or interpret product catalogs:
-
-```ts
-interface EnterpriseAccounts {
-  status(institutionID: string): Promise<NativeStatus>
-  login(institutionID: string, options: { allowProvision: false }): Promise<NativeStatus>
-  reconcile(institutionID: string, options: { allowProvision: boolean }): Promise<NativeStatus>
-  logout(institutionID: string): Promise<NativeStatus>
-  configuration(): Promise<NativeManagement>
-  activate(institutionID: string): Promise<NativeManagement>
-  configure(institutionID: string): Promise<NativeManagement>
-  addCustom(baseURL: string): Promise<NativeManagement>
-  updateCustom(institutionID: string, baseURL: string): Promise<NativeManagement>
-  removeInstitution(institutionID: string): Promise<NativeManagement>
-  configureCustomModels(institutionID: string, mode: 'discovery' | 'manual', models: RuntimeModel[]): Promise<NativeManagement>
-  restart(): Promise<{restarting: true}>
-}
-```
-
-`NativeStatus` may include `displayName`, `organization`, `state`, `userName`, `affiliation`, `accessExpiresAt`, `runtimeCredentialRef`, `credentialReady`, `credentialState`, and `capabilities`. `runtimeCredentialRef` is only a host status assertion; when present, it MUST equal the normalized Enterprise Profile `keyBinding.credentialRef`. Credential naming belongs to the Profile, not to Wails, Electron, or any other host implementation.
-
-Only the first four lifecycle operations are required for a native identity backend. Management operations are capability-detected: when absent, the same UI remains a read-only profile/model viewer. This is a host adapter, not part of OIDC or Key Binding wire standards. It can be implemented by Wails, Electron, Tauri, a mobile bridge, or another local host.
-
-The public browser projection is versioned as `dsh-oidc/management/v1alpha1`. It deliberately excludes tokens and credentials. Web Enterprise Profiles set all mutation capabilities to false; a native adapter may set `manageProfiles`, `manageModels`, and `restart` according to the methods it actually provides.
+backend: native has been removed. Use the shared desktop backend and Host credential/browser services.
 
 ## Model capability transforms
 
@@ -174,7 +139,7 @@ For every DSH release candidate or stable upgrade:
 1. update exact peer versions in a branch;
 2. diff the public exports and relevant types used above;
 3. run unit and package tests;
-4. launch a plain Web DSH profile and complete login, provisioning, model call, refresh, logout;
+4. launch a plain Web DSH profile and complete login, model call, refresh, logout;
 5. launch the desktop/native composition and compare user-visible behavior;
 6. verify client loader format and slot names;
 7. review whether official DSH capability supersedes any local adapter code;
@@ -182,6 +147,6 @@ For every DSH release candidate or stable upgrade:
 
 No semver range should silently opt this security-sensitive plugin into an untested DSH release while DSH remains pre-1.0.
 
-## Credential reads for institution adapters
+## Authorized requests for institution adapters
 
-Explicitly installed local adapters may call `ctx.oidcAccounts.resolveBoundCredential(profileID, { credentialRef: "EDUWORK_API_KEY", runtimeBaseURL })`. The runtime URL must exactly match the reviewed Profile model-service URL. The result is a DSH credential record verified against the session, issuer/client ID, complete resource binding and credential fingerprint, or `undefined`. Use this same snapshot rather than checking status and resolving the name separately, which can race with a login change. This is Host-only, with no Typert/RPC registration and no addition to the server protocol. Adapters remain responsible for restricting request destinations. Desktop/Web support the method; the legacy native bridge does not fall back to an unverified key.
+Installed adapters use `ctx.oidcAccounts.modelResourceFetch(profileID, relativePath)` for requests authorized by the current Token. See [account extensions](account-extensions.en.md). The old `resolveBoundCredential` method has been removed. Host-only `modelAuthorization(profileID, expectedBaseURL)` checks readiness and the discovered API URL, returning only a boolean. The shared Host transport checks the active session, refreshes authorization, and restricts requests to the discovered model API.

package/docs/dsh-integration.md

@@ -12,7 +12,7 @@
 | --- | --- |
 | `dsh-typert-protocol` | Host/Client RPC 描述符。 |
 | `dsh-host-webserver` | 精确 `/oauth/callback` 路由。 |
-| `dsh-credentials` | Session 和运行时 API Key 存储。 |
+| `dsh-credentials` | 授权 Session 存储。 |
 | `dsh-llm` | Adapter 注册、凭据、重试策略和稳定错误。 |
 | `dsh-llm-pi-ai` | 官方 `PiAiAdapter`。 |
 | `dsh-settings` | Provider 目录和就绪状态。 |
@@ -23,7 +23,7 @@ OpenAI-compatible 网络实现来自 `@earendil-works/pi-ai`，它也是 DSH 官
 
 ## 为什么 Provider adapter 位于本包内
 
-只有 OIDC 认证还不能获得可调用的企业模型。闭环集成还需要稳定 Provider 路由，并确保其凭据引用与 Key Binding 输出一致。再发布一个机构特有 Provider 包，会重新制造本仓库要消除的耦合。
+只有 OIDC 认证还不能获得可调用的企业模型。闭环集成还需要稳定 Provider 路由，并确保其凭据引用与 当前 Token 授权一致。再发布一个机构特有 Provider 包，会重新制造本仓库要消除的耦合。
 
 因此 adapter 是 `dsh-oidc` 内部模块，但其行为受到严格约束：
 
@@ -49,12 +49,12 @@ OpenAI-compatible 网络实现来自 `@earendil-works/pi-ai`，它也是 DSH 官
 | `loginStatus(loginID)` / `cancelLogin(loginID)` | 查询或取消当前桌面登录。 |
 | `resources(profileID)` | 模型元数据与问题，不含配额或秘密。 |
 | `selectEnterpriseModel(profileID, options)` | 通过官方默认值选择已验证连接的模型，不接受任意 Provider 目的地。 |
-| `reconcile(profileID, {allowProvision})` | 执行 bootstrap 和 resolve/provision/renew。 |
+| `reconcile(profileID, {})` | 刷新授权和模型资源，不申请模型 Key。 |
 | `logout(profileID)` | 本地清理，并尽力执行 OIDC 撤销。 |
 | `management()` | 共用企业模型设置 UI 使用的宿主能力投影。 |
 | `activate/configure/addCustom/updateCustom/removeProfile/configureModels/restart` | 可选 native 管理操作；Web Profile 拒绝修改。 |
 
-Client 描述符使用严格 Zod codec。发送给浏览器的配置不包含 issuer、client ID、Key Binding base、模型 base URL、Token 或 Key。
+Client 描述符使用严格 Zod codec。发送给浏览器的配置不包含 issuer、client ID、、模型 base URL、Token 或 Key。
 
 ## Web 组合
 
@@ -71,8 +71,8 @@ dsh plugin --profile web add @eduwork/dsh-oidc@0.2.0
 需要审计、开发或验证尚未发布的改动时，可以安装经过审查的本地 checkout：
 
 ```bash
-git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
-cd dsh-oidc
+git clone https://github.com/ecnu/EduWork.git
+cd EduWork/packages/dsh-oidc
 npm ci
 npm run check
 dsh plugin --profile web add .
@@ -101,50 +101,15 @@ dsh plugin --profile web add .
 
 所属 DSH Profile/Bundle 还必须包含普通 Web 应用、credentials、LLM/Pi adapter 依赖、settings、attachment 服务和 Client 界面。`dsh-oidc` 不是完整 DSH 发行版。
 
-OIDC 注册、Key Binding 实现、环境变量、验收和排障见[接入指南](getting-started.md)。
+OIDC 注册、Token 网关实现、环境变量、验收和排障见[接入指南](getting-started.md)。
 
 ## Desktop 组合
 
-新 Wails/Electron 产品使用 `backend: desktop`：插件管理临时 loopback 回调，通过官方 `nativeCommand` 打开浏览器。两壳共享身份、Key Binding 和模型行为；宿主仍提供凭据存储，无需另写 `enterpriseAccounts`。见[桌面 Host 集成](desktop-host.md)。
+新 Wails/Electron 产品使用 `backend: desktop`：插件管理临时 loopback 回调，通过官方 `nativeCommand` 打开浏览器。两壳共享身份、Token 生命周期和模型行为；宿主仍提供凭据存储，无需另写 `enterpriseAccounts`。见[桌面 Host 集成](desktop-host.md)。
 
-## 旧 native 桥兼容
+## 旧 native 桥
 
-以下 adapter 仅用于已有集成，不是新桌面的必做项：
-
-```yaml
-- insert:
-    - id: enterprise-oidc
-      name: '@eduwork/dsh-oidc'
-      config:
-        backend: native
-        uiMode: models-only
-        profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
-```
-
-宿主提供 Cordis 服务 `enterpriseAccounts`。产品自有机构目录必须由宿主或装配层先转换为标准 Enterprise Profile；`dsh-oidc` 不读取或解释产品目录：
-
-```ts
-interface EnterpriseAccounts {
-  status(institutionID: string): Promise<NativeStatus>
-  login(institutionID: string, options: { allowProvision: false }): Promise<NativeStatus>
-  reconcile(institutionID: string, options: { allowProvision: boolean }): Promise<NativeStatus>
-  logout(institutionID: string): Promise<NativeStatus>
-  configuration(): Promise<NativeManagement>
-  activate(institutionID: string): Promise<NativeManagement>
-  configure(institutionID: string): Promise<NativeManagement>
-  addCustom(baseURL: string): Promise<NativeManagement>
-  updateCustom(institutionID: string, baseURL: string): Promise<NativeManagement>
-  removeInstitution(institutionID: string): Promise<NativeManagement>
-  configureCustomModels(institutionID: string, mode: 'discovery' | 'manual', models: RuntimeModel[]): Promise<NativeManagement>
-  restart(): Promise<{restarting: true}>
-}
-```
-
-`NativeStatus` 可以包含 `displayName`、`organization`、`state`、`userName`、`affiliation`、`accessExpiresAt`、`runtimeCredentialRef`、`credentialReady`、`credentialState` 和 `capabilities`。`runtimeCredentialRef` 只是宿主状态回报；若提供，必须等于 Enterprise Profile 规范化后的 `keyBinding.credentialRef`。凭据命名策略属于 Profile，不属于 Wails、Electron 或其他宿主实现。
-
-Native 身份后端只必须实现前四项生命周期操作。管理操作通过能力探测：缺少这些方法时，同一 UI 会保持为只读 Profile/模型查看器。这是宿主 adapter，不属于 OIDC 或 Key Binding 网络标准；Wails、Electron、Tauri、移动桥接或其他本地宿主均可实现。
-
-浏览器公共投影版本为 `dsh-oidc/management/v1alpha1`，有意排除 Token 和凭据。Web Enterprise Profile 的所有修改能力为 false；native adapter 可以根据实际方法声明 `manageProfiles`、`manageModels` 和 `restart`。
+backend: native 已移除。桌面使用共享 desktop 后端及宿主凭据、浏览器服务。
 
 ## 模型能力转换
 
@@ -167,9 +132,9 @@ 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。
+扩展通过 modelResourceFetch(profileID, relativePath) 使用当前 Token 授权，见[账户扩展](account-extensions.md)。旧 resolveBoundCredential 已移除；可用性检查使用 Host-only modelAuthorization(profileID, expectedBaseURL)，只返回布尔值。
 
 ## DSH 升级流程
 
@@ -178,8 +143,8 @@ const dispose = ctx.enterpriseTransforms.register({
 1. 在分支中更新精确 peer version；
 2. 对比上述公开 export 和相关类型；
 3. 运行单元测试和打包测试；
-4. 启动纯 Web DSH Profile，完成登录、provision、模型调用、刷新和退出；
-5. 启动 Desktop/native 组合并比较用户可见行为；
+4. 启动纯 Web DSH Profile，完成登录、模型调用、刷新和退出；
+5. 启动 Desktop 组合并比较用户可见行为；
 6. 验证 Client loader 格式和 slot 名称；
 7. 审查 DSH 官方能力是否已替代任何本地 adapter 代码；
 8. 发布前在 `docs/compatibility.md` 记录结果。

package/docs/ecnu-reference.en.md

@@ -1,66 +1,9 @@
-# ECNU reference composition
+# Institution integration reference
 
 [简体中文](ecnu-reference.md) | **English**
 
-This repository uses East China Normal University / ChatECNU only as a concrete reference for the generic standard. The public example contains placeholders and no production endpoint, OIDC client identifier, API key, token, personal data, or logo asset.
+The public package contains no real institution endpoints, client registrations, accounts or quota data. Start from the [OIDC Token example](../examples/oidc-llm.enterprise-profile.example.json) or [LiteLLM example](../examples/litellm.enterprise-profile.example.json).
 
-The reference file is [`examples/ecnu.enterprise-profile.example.json`](../examples/ecnu.enterprise-profile.example.json).
+Own-account quota follows existing institutional server rules. Optional extensions use shared Host modelResourceFetch with the current Access Token and their existing parser. The public package defines no quota object or RPC.
 
-## Intended composition
-
-EduWork@ECNU composes the public core with institution extensions:
-
-```text
-DeepSeek Harness
-  + dsh-oidc
-      - standard OIDC identity
-      - worker-user-center-v1 Key Binding
-      - ECNU Enterprise Profile
-      - declarative ChatECNU Provider/models
-      - bounded brand/account UI and shared enterprise-model settings UI
-  + ECNU product plugins
-      - image-understanding fallback for text-only ecnu-max
-      - enterprise search route and official DSH result rendering
-      - product presets/skills/resources
-      - legacy native account bridge only (new desktops use the public desktop backend)
-      - quota or institution-specific business UI
-  + desktop shell/packaging/updater
-```
-
-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
-
-The OIDC Provider should return standard UserInfo:
-
-```json
-{
-  "sub": "opaque-stable-subject",
-  "name": "Display Name"
-}
-```
-
-If `name` is absent, UI falls back to `sub`. The plugin does not call an ECNU-private profile endpoint and does not map `data.attributes.XM` or similar paths. This is deliberate: the organization OIDC service should expose the standard claim.
-
-## Model example
-
-The placeholder shows two common facts:
-
-- `ecnu-max`: text-only, large context, selectable reasoning efforts;
-- `ecnu-plus`: native text/image input, thinking enabled but no selectable reasoning-effort parameter.
-
-For `ecnu-plus`, `supportsReasoningEffort: false` removes the unsupported effort while preserving thinking behavior. For `ecnu-max`, a separate ECNU image-understanding plugin can register `enterpriseTransforms` to add an aggregate image capability without altering the profile or replacing the Provider route.
-
-## Before any public release
-
-ECNU maintainers must separately approve:
-
-- the GitHub organization and repository visibility;
-- copyright holder wording;
-- use of university/ChatECNU names and brand values;
-- public support and security contact addresses;
-- publication of the npm package name;
-- removal of every internal endpoint, identifier, log, archive, and credential;
-- the production deployment's privacy/security review.
-
-The existence of this reference document is not authorization to publish institutional infrastructure details or brand assets.
+See [migration](key-binding-protocol.en.md) for old profiles. Real environment configurations and diagnostic records stay outside the public repository.