@eduwork/dsh-oidc 0.1.0-alpha.11

package/docs/enterprise-profile.md

@@ -0,0 +1,159 @@
+# Enterprise Profile 规范（`dsh-oidc/v1alpha1`）
+
+**简体中文** | [English](enterprise-profile.en.md)
+
+## 状态与符合性
+
+本文规定 `dsh-oidc` `0.1.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()` 校验。
+
+## 信任模型
+
+Profile 是受信任的部署配置，不是用户输入。即便如此，解析器仍以失败关闭方式工作：
+
+- 根对象和所有涉及可执行行为的嵌套对象都会拒绝未知字段；
+- 序列化后的 Profile 总大小不超过 512 KiB；
+- 生产 URL 必须使用 HTTPS；
+- 只有显式 loopback 主机可以在开发环境使用 HTTP；
+- 拒绝 URL 凭据、fragment 和 endpoint-base query string；
+- 只能选择内置的 `openai-compatible` adapter；
+- Key Binding 只接受协议基址和可选的本地 DSH 凭据引用，不能改写网络路径或字段；
+- logo data URL 只接受 PNG/WebP，不接受 SVG。
+
+远程管理系统只有在宿主能够认证来源、校验完整性并通过审查流程暂存变更时，才可以分发 Profile JSON。下载的 JSON 不会仅仅因为不包含 JavaScript 就自动变得安全。
+
+## 根对象
+
+| 字段 | 必需 | 含义 |
+| --- | --- | --- |
+| `schemaVersion` | 是 | 精确字符串 `dsh-oidc/v1alpha1`。 |
+| `id` | 是 | 匹配 `^[a-z][a-z0-9-]{0,63}$` 的 Profile ID。 |
+| `displayName` | 是 | 面向用户的集成名称。 |
+| `organization` | 否 | 机构名称；默认使用 `displayName`。 |
+| `nativeInstitutionID` | 否 | 仅传给 native 后端的标识符；默认使用 `id`。 |
+| `allowInsecureDevelopment` | 否 | 为本地开发启用 loopback HTTP。网络 HTTP 还必须配置 `insecureDevelopmentOrigin`。 |
+| `insecureDevelopmentOrigin` | 否 | 精确的非 TLS 开发 origin。只有与 `allowInsecureDevelopment: true` 一起使用时才有效，且所有 HTTP OIDC/Key Binding/Provider endpoint 必须使用该 origin。不得放入生产 Profile。 |
+| `brand` | 是 | 有边界的展示配置。 |
+| `oidc` | 是 | OIDC public client 配置事实。 |
+| `keyBinding` | 是 | Key Binding 基础 URL，以及可选的本地 DSH 凭据引用。 |
+| `provider` | 是 | 一个本地 OpenAI-compatible Provider 路由和模型列表。 |
+
+## 品牌替换
+
+品牌配置只修改经过批准的展示表面，不改变认证或可执行行为。
+
+| 字段 | 限制/行为 |
+| --- | --- |
+| `productName` | 最多 80 字符；用于页面标题和侧栏名称。 |
+| `organizationName` | 最多 120 字符。 |
+| `mark` | 未提供 Logo 时使用的 1–4 个字符。 |
+| `logoURL` | HTTPS URL 或 base64 PNG/WebP；文本最多 128 KiB。远程图片使用 `referrerPolicy=no-referrer`。 |
+| `primaryColor` | 六位十六进制颜色；只覆盖一组受限 DSH 主题 token。 |
+| `loginTitle` | 最多 120 字符。 |
+| `loginDescription` | 最多 500 字符。 |
+| `supportURL` | 使用 `noopener noreferrer` 打开的绝对 HTTPS URL。 |
+
+没有权利人的许可，Profile 不得包含其 Logo 或名称。担心远程图片跟踪的部署方应该打包 base64 PNG/WebP，或在受控 origin 上托管资产并配置严格 CSP。
+
+## OIDC 对象
+
+```json
+{
+  "issuer": "https://id.example.edu/oidc",
+  "clientId": "dsh-web-public-client",
+  "scopes": ["openid", "profile", "offline_access"]
+}
+```
+
+- `issuer` 是 OIDC Issuer Identifier。支持路径，不允许 query 和 fragment；必须与 Discovery 元数据逐字符一致。
+- `clientId` 标识 public client。Profile 和本插件都不应包含 client secret。
+- `scopes` 必须包含 `openid` 和 `profile`；每项内部不得包含空白，且不得重复。
+- 当 Provider 会签发 refresh token 且策略允许时，应该请求 `offline_access`。
+- Key Binding 授权 scope 由部署决定，但建议使用参考示例中的名称。
+
+Web 重定向地址固定为 `http://127.0.0.1:<DSH端口>/oauth/callback`。host 和 path 不可配置；端口取 DSH WebServer 的实际监听端口。
+
+## Key Binding 对象
+
+```json
+{
+  "baseURL": "https://ai.example.edu/api/worker/v1",
+  "credentialRef": "EXAMPLE_AI_TEST_API_KEY"
+}
+```
+
+| 字段 | 必需 | 含义 |
+| --- | --- | --- |
+| `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`。
+
+`credentialRef` 只是本地秘密存储的引用名，不是 API Key，不发送给 OIDC、Key Binding 或模型服务。普通单环境部署应该省略它并使用默认值；同一 Provider ID 在生产和测试部署间复用时，必须为不同环境配置不同引用，例如 `CHATECNU_API_KEY` 与 `CHATECNU_QUOTA_TEST_API_KEY`，避免一个环境读取另一环境的 Key。
+
+Endpoint 路径、请求/响应字段和 Provider ID 语义属于协议事实，不得由 Profile 自定义。Native 宿主若返回 `runtimeCredentialRef`，其值必须与本字段规范化后的结果一致，否则插件失败关闭。
+
+## Provider 对象
+
+Provider 对象是由本地、经过审查的 adapter 解释的数据。
+
+| 字段 | 必需 | 含义 |
+| --- | --- | --- |
+| `id` | 是 | DSH 路由 ID，也是默认凭据引用的来源；在所有已加载 Profile 中必须唯一。 |
+| `displayName` | 否 | 面向用户的 Provider 名称。 |
+| `adapter` | 是 | 精确字符串 `openai-compatible`。 |
+| `baseURL` | 是 | HTTPS OpenAI-compatible API 基址。 |
+| `reasoning` | 否 | 默认 DSH/pi-ai reasoning level，默认为 `high`。 |
+| `defaultContextWindow` | 否 | 正安全整数，默认 262144。 |
+| `defaultMaxTokens` | 否 | 正安全整数，默认 32768。 |
+| `maxRequestImageBytes` | 否 | 单次原生图片请求的累计大小预算。 |
+| `requestImagePixelBudget` | 否 | 图片归一化像素预算。 |
+| `requestImageMaxBytes` | 否 | 单张归一化图片大小预算。 |
+| `streamIdleTimeoutMs` | 否 | 正数空闲超时，默认 300000。 |
+| `retryPolicy` | 否 | 由 DSH Provider 管理的重试策略；默认 normal/重试 2 次。 |
+| `compat` | 否 | 有边界的 pi-ai OpenAI 兼容事实。 |
+| `models` | 是 | 1–128 个唯一模型条目。 |
+
+`retryPolicy.mode` 可以是 `normal` 或 `always`。`always` 可能一直重试，直到成功、取消或销毁；没有明确产品决策时不应启用。该策略还会由 DSH 再次校验。
+
+`compat` 只接受 JSON Schema 中列出的字段。部署方必须准确描述 Provider 事实；兼容性覆盖可能改变请求语义，但不能执行代码。
+
+## 模型条目
+
+每个模型包含：
+
+- 必需的 `id`；
+- 可选显示名称 `name`；
+- `input` 可包含 `text`、`image` 或两者，默认 `text`；
+- 可选的正数 `contextWindow` 和 `maxTokens`；
+- 可选 `reasoning` 布尔值；
+- 可选 `reasoningEfforts` 对象或 `false`；
+- 可选的受限 `compat` 覆盖。
+
+若模型支持 thinking，但不支持选择 reasoning effort，请设置：
+
+```json
+{
+  "compat": { "supportsReasoningEffort": false }
+}
+```
+
+Adapter 会保留 Profile 的 thinking 行为，并在校验和传输前移除不支持的用户所选 effort。不会因为 Provider 不支持 effort 参数而拒绝整个请求。
+
+## 禁止写入的秘密
+
+Profile 不得包含：
+
+- OIDC client secret；
+- access、refresh 或 ID token；
+- 模型 API Key；
+- 私有签名密钥；
+- session cookie；
+- 个人身份数据。
+
+OIDC 客户端是 public client。运行时秘密在登录后创建，并且只由当前 DSH Credential Provider 保存。
+
+## 版本管理
+
+未知 `schemaVersion` 会被拒绝。Alpha 阶段字段可能在 `v1alphaN` 之间变化。稳定 `v1` 的 minor 版本只增加可选字段；不兼容变更使用新 Schema 版本。详见[兼容性与发布策略](compatibility.md)。

package/docs/getting-started.en.md

@@ -0,0 +1,137 @@
+# Getting started: connect enterprise OIDC and models to DSH
+
+[简体中文](getting-started.md) | **English**
+
+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.
+
+## 1. Prerequisites
+
+| Component | Minimum requirement |
+| --- | --- |
+| DSH Host | DeepSeek Harness `0.1.2-alpha.2` 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. |
+| Enterprise Profile | Trusted local JSON containing public configuration only. |
+| Credential Provider | The current Web backend supports trusted single-user local storage only. |
+
+Have the identity and model-platform teams jointly review the [server API specification](server-integration-contract.en.md). OIDC alone establishes identity; without Key Binding and the model gateway it does not safely complete model authorization. Do not place a shared model API key in an Enterprise Profile.
+
+## 2. Register the OIDC Public Client
+
+Register a public client without a client secret. Its redirect URI must exactly equal:
+
+```text
+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.
+
+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).
+
+The configured `keyBinding.baseURL` has four fixed operations:
+
+```text
+GET  /bootstrap
+POST /runtime-credential/provision
+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.
+
+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.
+
+Use the normative [Key Binding protocol](key-binding-protocol.en.md) and machine-readable [`protocol/openapi.yaml`](../protocol/openapi.yaml). OIDC and the model gateway use their established interfaces, so this project does not duplicate them in another OpenAPI document.
+
+## 4. Create an Enterprise Profile
+
+Copy [`examples/enterprise-profile.example.json`](../examples/enterprise-profile.example.json) and replace the organization, bounded brand values, OIDC public-client facts, Key Binding base URL, OpenAI-compatible Provider base URL, and model catalog. Configure optional `keyBinding.credentialRef` only when local keys must be isolated across environments.
+
+The Profile is trusted deployment data, not a secret store. It must not contain client secrets, tokens, API keys, signing keys, cookies, or personal records. See the full [Enterprise Profile specification](enterprise-profile.en.md).
+
+## 5. Install into ordinary DSH Web
+
+The package is itself an installable DSH Bundle. Team deployments should install the reviewed, exact version from npm:
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+For auditing, development, or testing unpublished changes, install from a local checkout instead:
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
+cd dsh-oidc
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+From the parent directory, the equivalent explicit relative-path command is:
+
+```bash
+dsh plugin --profile web add ./dsh-oidc
+```
+
+DSH links the checkout into `$DSH_HOME/profiles/web`; it does not scan or copy the invoking directory. Keep the checkout in place and pin a reviewed commit for source-based deployments. To intentionally follow alpha updates, use:
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@alpha
+```
+
+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
+dsh --profile web --host 127.0.0.1 --port 3080 --no-open
+```
+
+The plugin constructs `http://127.0.0.1:<port>/oauth/callback` from the DSH WebServer port. It does not accept `publicBaseURL` and does not infer an address from proxy headers. If the startup port changes, update the OIDC Public Client registration to the same port.
+
+The package's `cordis.patch.yml` mounts one `enterprise-oidc` plugin instance. It does not traverse the current workspace or replace DSH Web, sessions, Workspace, LLM services, the Credential Provider, or other official capabilities. The invoking directory matters only when resolving a relative package path such as `.` or `./dsh-oidc`.
+
+## 6. Advanced product composition
+
+A product-owned Bundle may mount the plugin explicitly instead of using the default package patch:
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_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).
+
+## 7. Acceptance checklist
+
+Before production, verify at least:
+
+1. `dsh --profile web --dump-config` contains exactly one `enterprise-oidc` instance;
+2. login and the exact `/oauth/callback` succeed while invalid state and duplicate callback parameters fail;
+3. the UI displays standard UserInfo `name`, falling back to stable `sub`;
+4. provisioning requires explicit user confirmation;
+5. a provisioned model completes a streaming conversation;
+6. no API key appears in the Profile, browser configuration, logs, or exported sessions;
+7. refresh, expiry, revocation, authorization denial, rate limiting, and backend outage behavior are understandable;
+8. logout clears local OIDC and model credentials and attempts standard token revocation;
+9. the DSH WebServer listens only on `127.0.0.1` and is not exposed as a shared site through a proxy or port mapping;
+10. OIDC, all four Key Binding operations, and the model gateway jointly pass the [server API specification](server-integration-contract.en.md).
+
+The current Web backend does not support shared Web. A shared scenario needs a new host backend with per-user isolation; do not simply relax the loopback restriction. See the [security model](security-model.en.md) and [public release checklist](release-checklist.en.md).
+
+## 8. Troubleshooting
+
+- **Callback fails:** compare the registered URI with `http://127.0.0.1:<DSH-port>/oauth/callback` character for character. Confirm the DSH host is `127.0.0.1` and its actual port matches the registration; do not use `localhost`, a LAN address, or a public address.
+- **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-alpha.2` 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.

package/docs/getting-started.md

@@ -0,0 +1,239 @@
+# 接入指南：把企业 OIDC 与模型服务接入 DSH
+
+**简体中文** | [English](getting-started.en.md)
+
+这份指南面向准备在自己机构部署 `dsh-oidc` 的管理员和开发者。完成后，用户可以在普通 DSH Web 中：
+
+1. 使用机构 OIDC 登录；
+2. 明确确认创建或绑定模型运行凭据；
+3. 在“企业服务”设置页查看账号、Provider 和模型；
+4. 直接选择企业模型开始对话；
+5. 刷新登录、检查连接或退出登录，而模型 API Key 不进入浏览器配置。
+
+`dsh-oidc` 不要求 Wails，也不要求使用 ChatECNU Work。华东师范大学只是参考实现。
+
+## 1. 先确认你需要准备什么
+
+| 组件 | 谁提供 | 最低要求 |
+| --- | --- | --- |
+| DSH Host | 部署方 | DeepSeek Harness `0.1.2-alpha.2`，Node.js 22+。 |
+| 机构企业模型集成服务 | 同一服务所有者 | 共同提供 OIDC Provider、固定 Key Binding 和 OpenAI-compatible 模型网关；三者全部必需。 |
+| Enterprise Profile | 部署方 | 一份受信任的本地 JSON，只存公开配置，不存密钥或个人信息。 |
+| Credential Provider | DSH Host | 当前 Web backend 仅支持可信单用户本机存储。 |
+
+先把[服务端接口规范](server-integration-contract.md)交给身份平台与模型平台共同确认。只有 OIDC 时，插件只能证明“用户是谁”；没有 Key Binding 和模型网关，就无法安全完成“这个用户可以调用哪些企业模型”的闭环。不要把全局模型 API Key 写进 Enterprise Profile。
+
+## 2. 注册 OIDC Public Client
+
+在机构身份平台登记一个不带 Client Secret 的 Public Client。回调地址必须逐字符匹配：
+
+```text
+http://127.0.0.1:3080/oauth/callback
+```
+
+`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`，并返回：
+
+- ID Token：至少包含正确的 `iss`、`aud`、`sub`、`iat`、`exp` 和 `nonce`；当前版本只支持带 `kid` 的 RS256；
+- UserInfo：必须包含与 ID Token 相同的非空 `sub`；建议提供标准 `name` 作为用户显示名；
+- Access Token：可以是 JWT 或 opaque token，但 Key Binding 服务必须能验证 issuer、audience、有效期、scope 和 subject。
+
+插件只读取标准 `userinfo.name`，缺失时显示 `userinfo.sub`。它不会读取私有人员接口，也不支持 JSON Path 姓名映射。完整兼容要求见 [OIDC 兼容规范](oidc-interoperability.md)。
+
+## 3. 实现完整机构服务端
+
+同一机构服务交付必须完整提供上一节的 OIDC、下面的 Key Binding，以及接受绑定凭据的 OpenAI-compatible 模型网关。它们可以由内部不同系统承载，但必须有统一的版本、安全和运维责任。接口定义见[服务端接口规范](server-integration-contract.md)。
+
+Key Binding 不是 OIDC 标准的一部分，而是 `dsh-oidc` 定义的企业模型凭据协议。Enterprise Profile 用 `baseURL` 指定接口组基址，插件固定调用：
+
+```text
+GET  {baseURL}/bootstrap
+POST {baseURL}/runtime-credential/provision
+POST {baseURL}/runtime-credential/resolve
+POST {baseURL}/runtime-credential/renew
+```
+
+Profile 还可以用可选的 `keyBinding.credentialRef` 隔离本地 DSH Credential Provider 中的秘密条目。它不参与网络请求，也不改变下列接口；普通单环境部署省略即可。生产/测试复用相同 Provider ID 时，应使用不同的引用名。
+
+每个请求都携带 OIDC Access Token：
+
+```http
+Authorization: Bearer <oidc-access-token>
+```
+
+服务端必须验证 Access Token 和用户授权，不得只相信请求里的 `provider_id`。`provision` 与 `renew` 还必须支持 `Idempotency-Key`。返回的 `api_key` 只能通过 TLS 响应一次性交给插件，必须带 `Cache-Control: no-store`，不得进入日志、监控标签或错误详情。
+
+规范文本见 [Key Binding 协议](key-binding-protocol.md)，可直接交给后端研发的机器可读契约是 [`protocol/openapi.yaml`](../protocol/openapi.yaml)。OIDC 和模型网关分别遵循其既有标准，因此本项目不复制另一份 OpenAPI。
+
+## 4. 创建 Enterprise Profile
+
+复制 [`examples/enterprise-profile.example.json`](../examples/enterprise-profile.example.json)，至少替换：
+
+- `id`、`displayName`、`organization`；
+- `brand` 中有权使用的名称、颜色和支持地址；
+- `oidc.issuer`、Public `clientId` 与 scopes；
+- `keyBinding.baseURL`；
+- 跨环境需要隔离本地 Key 时，可选配置 `keyBinding.credentialRef`；
+- `provider.id`、OpenAI-compatible `baseURL` 和模型列表。
+
+典型结构如下：
+
+```json
+{
+  "schemaVersion": "dsh-oidc/v1alpha1",
+  "id": "example-university",
+  "displayName": "Example University AI",
+  "organization": "Example University",
+  "brand": {
+    "productName": "Example AI Work",
+    "organizationName": "Example University",
+    "mark": "E",
+    "primaryColor": "#5157af",
+    "loginTitle": "使用机构账号登录",
+    "loginDescription": "登录后绑定企业模型运行凭据。",
+    "supportURL": "https://support.example.edu/ai"
+  },
+  "oidc": {
+    "issuer": "https://id.example.edu/oidc",
+    "clientId": "dsh-web-public-client",
+    "scopes": ["openid", "profile", "offline_access"]
+  },
+  "keyBinding": {
+    "baseURL": "https://ai.example.edu/api/worker/v1"
+  },
+  "provider": {
+    "id": "example-ai",
+    "displayName": "Example AI",
+    "adapter": "openai-compatible",
+    "baseURL": "https://ai.example.edu/open/api/v1",
+    "models": [
+      { "id": "example-max", "name": "Example Max", "input": ["text"] },
+      { "id": "example-plus", "name": "Example Plus", "input": ["text", "image"] }
+    ]
+  }
+}
+```
+
+Profile 是部署配置，不是用户输入。它可以声明模型事实和有限品牌 token，但不能加载脚本、CSS、工具、Skill 或远程 Provider adapter。字段全集和安全限制见 [Enterprise Profile 规范](enterprise-profile.md)。
+
+## 5. 安装到普通 DSH Web
+
+`dsh-oidc` 本身是可直接安装的 DSH Bundle。团队部署应从 npm 安装经过复核的精确版本：
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+需要审计、开发或测试尚未发布的改动时，再从本地 checkout 安装：
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
+cd dsh-oidc
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+也可以在项目父目录中显式传入相对路径：
+
+```bash
+dsh plugin --profile web add ./dsh-oidc
+```
+
+DSH 会把本地 checkout 链接到 `$DSH_HOME/profiles/web`，不会扫描或复制当前目录；安装完成后不要移动或删除 checkout。源码部署应固定经过审核的 commit。若明确希望持续跟随 alpha 更新，也可以使用：
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@alpha
+```
+
+设置 Enterprise Profile 路径，并让 DSH 监听固定 loopback host：
+
+```bash
+export DSH_OIDC_ENTERPRISE_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'
+dsh --profile web --host 127.0.0.1 --port 3080 --no-open
+```
+
+插件会从 DSH WebServer 的端口构造 `http://127.0.0.1:<port>/oauth/callback`，不接受 `publicBaseURL`，也不会从代理 header 推断地址。若启动参数改变端口，必须同步修改 OIDC Public Client 的登记值。
+
+安装命令会把 `dsh-oidc` 作为 Bundle 加到 Profile，并由包内 `cordis.patch.yml` 挂载插件。它不会遍历当前工作目录，也不会替换 DSH 的 Web、会话、Workspace、LLM、Credential Provider 或其他官方能力；当前目录只用于解析 `.`、`./dsh-oidc` 等相对安装路径。
+
+## 6. 高级组合：自定义 Bundle 或桌面宿主
+
+如果产品已有自己的 Bundle，可以不使用包内默认 patch，而是在产品 patch 中显式插入：
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        web:
+          returnPath: /
+```
+
+桌面宿主可以切换到 native backend：
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        backend: native
+        uiMode: models-only
+        profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
+```
+
+native backend 必须提供 `enterpriseAccounts` 服务，并与 Web 一样传入标准 Enterprise Profile。产品自有目录、租户或账号配置必须先由产品装配层转换为该 Profile，不能交给 `dsh-oidc` 解释。宿主可以由 Wails、Electron、Tauri 或其他技术实现；插件本身不依赖任何桌面框架或产品目录格式。接口和能力探测见 [DSH 集成说明](dsh-integration.md)。
+
+## 7. 上线前验收
+
+至少完成以下真实链路：
+
+1. `dsh --profile web --dump-config` 中只有一个 `enterprise-oidc` 实例；
+2. 登录跳转和 `/oauth/callback` 成功，错误 state、重复参数和过期 code 会失败；
+3. 设置页显示标准 UserInfo `name`，没有 `name` 时显示稳定 `sub`；
+4. 未创建运行凭据时先显示用户确认，不自动静默 provision；
+5. provision/resolve 后企业模型可完成流式对话；
+6. API Key 不出现在 Profile、浏览器配置、日志和导出的会话中；
+7. refresh、过期、撤销、权限不足、限流和 Key Binding 不可用均有可理解的失败结果；
+8. logout 清理本地 OIDC 会话和模型凭据，并尽力调用标准 revocation endpoint；
+9. DSH WebServer 只监听 `127.0.0.1`，没有通过反向代理或端口映射暴露为共享站点；
+10. OIDC、全部四个 Key Binding 操作和模型网关按[服务端接口规范](server-integration-contract.md)联合通过验收。
+
+当前 Web backend 不支持共享 Web。需要共享场景时必须由具备每用户隔离的新宿主 backend 承担，不能直接放宽 loopback 约束。详见 [安全模型](security-model.md) 和 [公开发布检查表](release-checklist.md)。
+
+## 8. 常见问题
+
+### 回调失败或跳回后仍未登录
+
+核对 OIDC 注册值是否与 `http://127.0.0.1:<DSH端口>/oauth/callback` 完全一致。确认 DSH 实际监听 host 为 `127.0.0.1`，登记端口与启动端口相同；不要使用 `localhost`、局域网地址或公网地址。
+
+### 页面显示一串 subject，而不是姓名
+
+这是标准降级行为。让 OIDC UserInfo 在 `profile` scope 下返回非空标准 `name`，并保证 `sub` 与 ID Token 完全一致。
+
+### 登录成功但模型不可用
+
+检查 Key Binding 的 `/bootstrap` 状态、用户是否确认 provision、返回的 `provider_id` 是否等于 Enterprise Profile 的 `provider.id`，以及模型网关是否接受绑定后的 API Key。
+
+### 模型支持 thinking，但不支持 reasoning effort
+
+在模型 `compat` 中设置：
+
+```json
+{ "supportsReasoningEffort": false }
+```
+
+插件会保留 thinking 行为并移除不受支持的 effort 参数，不会因此拒绝调用。
+
+### 为什么企业服务是单独的设置页
+
+当前 DSH `0.1.2-alpha.2` 已提供正式的 `settings.models.footer` 插槽。插件直接把企业模型管理能力挂载到官方“模型”页，并保持官方模型页启用，不再依赖产品私有的模型页 fork。