@xgent-ai/skills 0.6.0 → 0.7.0

package/skills/portal-external-app/references/native-clients.md

@@ -0,0 +1,215 @@
+# 原生客户端（iOS / Android / 桌面）接入
+
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
+> `<portal-origin>` 指门户公开源（与 `PORTAL_BASE_URL` 相同，客户端用）；`<API_BASE_URL>` 是后端拿到的
+> 内部门户 API 地址（服务端调用用）；`<key>` 指你的 listingKey。
+
+原生客户端是**你这个 App 的另一种前端**：它拿到的是和 iframe 前端同一种用户态 TDT，打你
+后端的 `/svc/<key>/…`，后端照常走四道闸（[integration-contract.md](integration-contract.md) §3）。
+区别只在**令牌怎么到手**：iframe 由宿主注入，原生客户端自己走 OAuth。
+
+## 0. 速答
+
+| 问题 | 结论 |
+| --- | --- |
+| 推荐哪种登录方式？ | **授权码 + PKCE（S256），在系统浏览器里完成**，`publicClient: true`，不带任何密钥。门户只提供这一条用户登录路径 |
+| 用户长期凭证能当设备凭证吗？ | **不能**。它是绑定「租户 + 用户 + 目标 App」的 bearer 密钥，没有设备绑定，换不出 TDT / 刷新令牌，资源端默认拒收。设备上的用户用授权码登录；无人值守设备用服务账号 |
+| 用户被移出 / 停用后 60 秒内失效？ | **成立，前提是后端按契约逐请求自省**（SDK 正缓存上限 55 s）。刷新令牌在下一次刷新时被拒并作废，所以客户端以后端 401 为准（§3） |
+| 有不依赖用户登录的成员查询 / 事件推送吗？ | **查询有，成员事件推送没有**。服务账号可逐租户列在职成员、实时查单个成员状态；门户不推送成员加入/移出/停用事件（§4） |
+
+## 1. 登录：授权码 + PKCE
+
+### 1.1 manifest 声明（治理档，首次与每次改动都进「发布审核」）
+
+```jsonc
+"publicClient": true,
+"redirectUrls": ["https://app.example.com/oauth/callback", "com.example.app:/oauth/callback"]
+```
+
+- `publicClient: true` ⇒ 授权端**强制** PKCE，客户端不持有、也不需要 App Secret。**别把 App Secret 打进 IPA/APK/安装包**。
+- `redirectUrls` 是**逐字精确匹配**：不允许通配符、fragment、URL 内用户名口令；`http:` 只允许
+  `localhost` / `127.0.0.1` / `[::1]`。可用 https（Universal Link / App Link，**优先**，域名归属可证明）
+  或自定义 scheme。桌面端回环回调要登记**固定端口**——不支持「任意端口」匹配。
+- TDT 有效期、是否允许刷新、刷新令牌有效期**不是 manifest 字段**，由平台/租户管理员按 App 配置
+  （缺省：TDT 3600 s、允许刷新、刷新令牌 30 天）。客户端一律读响应里的 `expires_in`，别写死。
+
+### 1.2 流程
+
+```
+① 系统浏览器打开
+GET <portal-origin>/oauth/authorize
+    ?response_type=code&client_id=<key>&redirect_uri=<已登记回调>
+    &code_challenge=<BASE64URL(SHA256(verifier))>&code_challenge_method=S256
+    &state=<随机值>[&scope=<空格分隔，只能收窄>]
+→ 302 <redirect_uri>?code=…&state=…          # 未登录先走门户登录（含 2FA / SSO），再回到这里
+
+② 换令牌（表单编码）
+POST <portal-origin>/oauth/token
+    grant_type=authorization_code&code=…&redirect_uri=<同上>&client_id=<key>&code_verifier=…
+→ { "access_token", "token_type": "Bearer", "expires_in", "scope", "refresh_token"? }   # 管理员关了刷新则无 refresh_token
+
+③ 刷新
+POST <portal-origin>/oauth/token
+    grant_type=refresh_token&refresh_token=…&client_id=<key>
+→ 同上，带一枚新的 refresh_token
+
+④ 调自己的后端
+Authorization: Bearer <access_token>  →  <portal-origin>/svc/<key>/…
+```
+
+硬规则：
+
+- **必须用系统浏览器**（iOS `ASWebAuthenticationSession`、Android Custom Tabs、桌面默认浏览器），
+  不用内嵌 WebView：登录依赖门户会话 Cookie 与 2FA/SSO 页面，WebView 里既拿不到已有会话，也违背
+  公开客户端的安全前提。
+- **租户 = 浏览器里门户会话当前所在的租户**，授权端没有租户参数。多租户用户要先在门户切换租户再
+  授权；客户端「切换租户」= 重新走一次 ①②。当前租户以后端自省得到的 `tenant_id` 为准。
+- `code` 一次性、60 s 内有效；**校验回来的 `state`** 与发起时一致。授权端没有额外同意屏，同意在
+  ② 兑换时记录。
+- 错误分两类：`client_id` 不存在或 `redirect_uri` 未登记 ⇒ **停在门户错误页、不会跳回 App**（防止
+  把错误带到未登记地址）；其余可恢复错误跳回 `redirect_uri?error=<code>&state=…`。
+  `/oauth/token` 失败返回 `{ "ok": false, "error": { "code" } }`，**按响应体判，不能只看 HTTP 状态**。
+  常见码：`INVALID_GRANT`（code / verifier / redirect_uri / client_id 不符、令牌已用过、用户已撤销该 App
+  的授权，或成员 / 用户 / 租户已停用）、
+  `SEAT_REQUIRED`（席位制 App 未分配席位）、`APP_DISABLED`、`GRANT_NOT_ALLOWED`（管理员关了刷新）。
+
+### 1.3 刷新令牌：轮换、单飞、本地保管
+
+- **每次刷新都轮换**：旧 `refresh_token` 立即作废，**被拒的那次同样会消耗掉它**。
+- **重复使用 = 整次登录作废**：一枚令牌被用掉 30 秒后又被出示，门户按泄露处理，连同它之后轮换出的
+  最新令牌一起吊销（这样被盗的令牌会在真客户端下一次刷新时失效）。30 秒内的重复出示（自己的并发
+  刷新、网络重试）只拒绝这一次，不连累已经换到新令牌的那个请求。所以：
+  - 同一账号的刷新必须**单飞**（全进程一把锁，并发请求等同一次刷新结果）；没做到时，输掉的那次会
+    拿到 `INVALID_GRANT`，此时应重读本地存储里的新令牌，而不是直接退出。
+  - 先把新 `refresh_token` **原子落盘**，再使用新 `access_token`；响应丢失（断网、进程被杀）后旧令牌
+    已不可用，只能重新登录——把这当成正常分支处理。
+- 刷新窗口是**滑动**的：每次刷新都重置为完整有效期，长期活跃的设备不会被强制重登。
+- `refresh_token` 放 Keychain / Android Keystore 支撑的加密存储；`access_token` 放内存即可。
+- **退出登录**：先吊销刷新令牌，再删本地全部令牌并注销 §1.4 登记的推送设备：
+
+  ```
+  POST <portal-origin>/oauth/revoke
+       Content-Type: application/x-www-form-urlencoded
+       token=<refresh_token>&client_id=<key>
+  → { "revoked": true }
+  ```
+
+  只需 `client_id`，不带密钥；作废的是这次登录的整条刷新链。令牌已失效或不存在同样返回
+  `revoked: true`，可放心重试；`client_id` 与令牌不符返回 `INVALID_GRANT`。`access_token` 公开客户端
+  撤不掉，丢弃即可，剩余有效期内仍能用。需要清掉浏览器里的门户会话时，再引导用户在门户退出。
+- **丢失设备**：用户在门户「已授权应用」里撤销该 App，当前租户里该用户这个 App 的全部刷新链、未兑换的
+  授权码和 TDT 立即作废（所有设备一起下线，重新登录即可）；管理员停用成员同样生效（§3）。
+
+### 1.4 推送设备登记
+
+APNs / FCM 推送令牌登记在门户，**不要自建设备表**（所有原生 App 共用一张，推送凭据集中在平台）：
+
+```
+POST   <portal-origin>/api/me/devices     Bearer <用户 TDT>
+       { "platform": "ios"|"android", "provider": "apns"|"fcm", "token", "appKey": "<key>", "appVersion"?, "locale"? }
+GET    <portal-origin>/api/me/devices
+DELETE <portal-origin>/api/me/devices/:id   # 退出登录时调
+```
+
+响应不回显推送令牌。推送能否送达取决于本环境平台是否已配置对应的 APNs / FCM 渠道，接入前与平台确认。
+
+## 2. 设备凭证：别拿用户长期凭证顶
+
+门户的**用户长期凭证**（`xuak_` 前缀，用户在门户个人资料的「用户凭证」页或经 App 委托签发）是为 CLI、MCP、
+个人自动化这类**机器入口**设计的：
+
+- 绑定**租户 + 用户 + 目标 App**，是纯 bearer 密钥：没有设备字段、没有持有证明，谁拿到谁能用；
+- **换不出** TDT 或刷新令牌，不能顶替登录；
+- 资源端 SDK **默认只收** `tdt` / `service_access_key`，只有显式开放的机器入口才接收
+  `user_access_key`，且必须逐请求按 `credentialId` 核对本 App 自己的绑定记录。
+
+所以按「谁在用这台设备」二选一：
+
+| 场景 | 用什么 | 说明 |
+| --- | --- | --- |
+| **人在设备上用 App**（手机、平板、桌面客户端） | §1 授权码 + PKCE | 每次安装各有一条独立的刷新链，天然按设备区分；身份、席位、ACL 与 Web 端完全一致 |
+| **无人值守设备**（采集器、kiosk、网关、IoT） | **服务账号** | 租户管理员在门户 `/admin/service-accounts` 自助创建，`xsak_` 长期密钥直接 Bearer，或 clientId + secret 换服务态 TDT。令牌 `kind:"service"`、无 `user_id`，只按 scope 授权；可选 scope 只来自你 manifest 的 `scopes`（见 [integration-contract.md §3.1](integration-contract.md)） |
+
+**不要**让用户长期凭证冒充设备身份，也不要让服务账号冒充某个用户——前者绕开设备边界，后者绕开
+成员资格、席位与 ACL。
+
+## 3. 停用 / 移出后多快失效
+
+成员被停用、移出，或租户被停用后，门户**自省**对这位用户的 TDT 与用户长期凭证**立即**返回
+`active:false`：每次自省都实时查成员、用户、租户状态与 App 安装状态，门户侧不缓存用户结果。成员
+停用 / 移出还会同时作废该用户已签出 TDT 的版本号与门户会话。
+
+剩下的延迟全在**你的后端缓存**里，这就是 60 秒预算的构成：
+
+| 你的后端 | 最坏延迟 |
+| --- | --- |
+| 用 `@xgent/portal-server-sdk` 且传了 `cache` 适配器（默认配置） | 30 s（正缓存默认值） |
+| 用 SDK 但不传 `cache` | 0（不做正缓存，每请求直查） |
+| 调大 `positiveCacheMs` | 上限 55 s（SDK 强制截断；加门户 5 s 配置缓存，总预算 60 s） |
+| `strictIntrospection: true` | 0（每请求直查，敏感写操作用这个） |
+| 其他语言自实现 | 按 [integration-contract.md](integration-contract.md) §3 「到期与缓存」实现即同上 |
+
+**保证成立的前提**（任何一条不满足，60 s 都不成立）：
+
+1. **每个请求都经自省**，正缓存 ≤ 55 s。本地验签、只看 `exp`、或用 TDT 换一个自建长会话 ⇒ 延迟变成
+   TDT 剩余寿命（缺省 1 h，最长 24 h）。
+2. 客户端以**后端返回 401（`active:false`）**为「已失去权限」的首要信号；刷新结果要等 TDT 到期才看得到。
+
+**不在 60 秒保证里的**：
+
+- **成员停用不会主动吊销刷新令牌**，只在下一次被使用时拦下：成员停用 / 移出、用户停用或租户停用期间，
+  `/oauth/token` 的授权码兑换与刷新都返回 `INVALID_GRANT`，**所出示的那枚刷新令牌随之作废**，
+  之后成员恢复也不会复活它。停用期间从没刷新过的链，在成员恢复后照常可用。
+  客户端处理：刷新返回 `INVALID_GRANT`，或后端返回 401（`active:false`）⇒ 视为已退出，清本地令牌并
+  回到登录页。两者都要处理：TDT 没到期之前客户端不会去刷新，最先看到的通常是后端的 401。
+- 用户创建的**服务账号 / `xsak_`** 不随成员停用失效：它们属于租户，不属于个人，需要管理员单独处置。
+
+## 4. 不依赖用户登录的服务端能力
+
+### 4.1 成员查询 ✅
+
+服务账号在 manifest 的 `serviceScopes` 里声明 `directory.read`（治理档，审批后授予；租户自助建的服务
+账号勾不到这类平台基础 scope）：
+
+```
+POST <API_BASE_URL>/api/tokens/service              # 每个租户各换一枚，令牌钉死在该租户
+     Authorization: Basic base64(<saClientId>:<saSecret>)
+     grant_type=client_credentials&tenant_id=<租户 UUID>&scope=directory.read
+GET  <API_BASE_URL>/api/v1/directory/users           Bearer <服务态 TDT>
+→ { "users": [{ "id", "name", "role", "email"?, "seat"? }] }
+```
+
+- 只返回**在职**成员（成员与用户状态均 active），停用/移出的人直接不在列表里；`email` 需另加
+  `directory.email.read`；席位制 App 附带 `seat`。加 `?appAccess=caller` 附带每人 `canUseApp`。
+- 目前**没有**分页、增量（`updatedSince`）和按 id 查询。
+
+查**单个用户此刻**的状态，用服务账号 Basic 认证（与自省同一把凭证）调：
+
+```
+POST <API_BASE_URL>/api/v1/acl/check
+     Authorization: Basic base64(<saClientId>:<saSecret>)
+     { "tenant_id", "user_id", "listing_key": "<key>", "pids"?: [...] }
+→ { "membershipActive", "role", "bypass", "seatHeld", "appInstalled", "plan", "results" }
+```
+
+`membershipActive:false` 即不在职。**有副作用的动作之前现查、不缓存**。只能查本服务账号够得着的
+租户：归属租户与租户白名单之内，且你的 App 在该租户**有安装记录**（停用、卸载过的也算，此时
+`appInstalled:false`）；否则返回 `TENANT_NOT_ALLOWED`。
+
+### 4.2 事件推送 ❌（成员事件）
+
+门户**不推送**成员加入、移出、停用事件，也没有 `app.installed` 事件。现有的推送只有：
+
+- 租户管理员在 App 配置里填的 webhook 地址，事件仅 `app.enabled` / `app.disabled` / `app.uninstalled` /
+  `consent.granted` / `consent.revoked`：**无签名、不重试、5 s 超时、payload 不含租户 id**，只能当提示，
+  不能据此做授权决定。
+- App 卸载协调是**拉取式**：App 轮询待处理的卸载操作，门户不回调 App 的地址。
+- 平台业务事件总线由 App 发布、App 订阅，门户自己不往里发成员事实。
+
+### 4.3 推荐组合
+
+| 需求 | 做法 |
+| --- | --- |
+| 用户请求的实时授权 | 每请求自省（§3），这就是唯一权威 |
+| 后台任务要对某人做事（推送、定时任务、代发通知） | 动作前 `acl/check` 现查该用户 |
+| 清理离职者在本 App 的数据 | 逐租户定期拉 `directory/users` 与本地出现过的 user id 比对；**只用来清理，不把通讯录镜像进自己库**当选人数据源（选人用门户的选人组件） |

package/skills/portal-external-app/references/quota-and-seats.md

@@ -101,7 +101,7 @@ metricKey 约定 `<listingKey>.<role>-seats.allocated`（`latestRoleAllocated`
 「未注册 —— 请在 usageMetrics 里声明」，不再是无提示的静默失真）。
 指标注册表 = 内置 `USAGE_METRICS` ∪ 各 listing 的 manifest `usageMetrics` 声明：
 **外部 App 在自己 manifest 的 `usageMetrics` 里声明 gauge 条目**
-（`[{ key, kind: "gauge", unit: "count", label: {zh,…} }]`，key 前缀必须=listingKey、
+（`[{ key, kind: "gauge", unit: "count", label: {"zh-CN",…} }]`，key 前缀必须=listingKey、
 金额单位 microAmount 不开放；治理档，批准后生效）——不再需要门户发版；
 平台内建指标由平台维护，外部 App 无需修改平台代码。
 

package/skills/portal-external-app/references/registration-and-onebox.md

@@ -15,7 +15,7 @@
     `scopeLabels` 同时是那个勾选列表的正文——不写就只显示裸 scope 串。
 - 关系：`dependencies`、`exchangeTargets`、`serviceBaseUrl`（`/svc/<listingKey>`）
 - 服务态与计量：`usageReporter`（true ⇒ SA 得 `client_credentials` + `usage.report`）、`serviceScopes`（服务态 scope；SERVICE_ONLY **永拒**）、`privilegedServiceScopes`（SERVICE_ONLY 的**申请**：`[{scope, reason}]`，reason 必填，最高治理档、审批逐条确认后授予）、`usageMetrics`（用量指标声明：key 前缀必须=listingKey、金额单位不开放；治理档，批准后 ingest 才认这些 key）
-- 部署/运维：`requiredEnv`（部署所需 env 的**键名**清单，值永远由平台配；元素可写 `{ key, renamedFrom }` 表达改名。键集合一变提案转入「发布审核」，且**批准前门户会比对 `descriptor.env ∪ envFile` 的键集合，缺了拒绝生效**（`REQUIRED_ENV_MISSING`，提案留 pending））、`deployDescriptor`（`image` 归自动档、`hostPort` 归平台不算变更，**其余一切属治理档**）、`deployRequirements`（后端要跑在**什么样的机器**上：`{region?, size?, gpu?, network?}`，只写**名字与档位**，网段/IP/URL 提交即拒；批准时按目标环境**当时**的资源池逐维匹配，不满足则拒绝生效、提案留待审，通过则把首次落点固定住；需要 `deployDescriptor`）、`requiredServices`（运行所需的**外部服务** `[{name, kind, note?}]`，身份是 `(kind, name)` 二元组；批准时比对本环境**已登记**的「已具备服务」，未登记或缺条目则拒绝生效 —— 登记表核对已有服务；支持自动供给的类型按选定档案建资源并注入约定键，不收 `envKey`）
+- 部署/运维：`requiredEnvNotes`（`{ 键名: 说明 }`，给 `requiredEnv` 里需要解释的键写一句给审批人看的话，≤200 字；纯展示、自动档）、`requiredEnv`（部署所需 env 的**键名**清单，值永远由平台配；元素可写 `{ key, renamedFrom }` 表达改名。键集合一变提案转入「发布审核」，且**批准前门户会比对 `descriptor.env ∪ envFile` 的键集合，缺了拒绝生效**（`REQUIRED_ENV_MISSING`，提案留 pending））、`deployDescriptor`（`image` 归自动档、`hostPort` 归平台不算变更，**其余一切属治理档**）、`deployRequirements`（后端要跑在**什么样的机器**上：`{region?, size?, gpu?, network?}`，只写**名字与档位**，网段/IP/URL 提交即拒；批准时按目标环境**当时**的资源池逐维匹配，不满足则拒绝生效、提案留待审，通过则把首次落点固定住；需要 `deployDescriptor`）、`requiredServices`（运行所需的**外部服务** `[{name, kind, note?}]`，身份是 `(kind, name)` 二元组；批准时比对本环境**已登记**的「已具备服务」，未登记或缺条目则拒绝生效 —— 登记表核对已有服务；支持自动供给的类型按选定档案建资源并注入约定键，不收 `envKey`）
 
 ⚠️ **`deployDescriptor.hostPort`（宿主机发布口）不归 App 定**：它是部署环境相关的事实——同一份 manifest 会发到一盒与好几套生产门户，各自端口地貌不同，而 App 团队看不见目标机器上谁占了什么。规则三句话：**首次注册**当建议值采纳（撞了自动退让到平台端口池 20000–20999，**不会因此拒掉注册**）；**listing 已存在则一律忽略**（那个口已经写进 Caddy 的 `/svc` map、也是在跑的容器发布出来的口）；发布响应的 `warnings` 会说明实际是哪个口。App 只管 `port`（容器内监听口，约定 8080）。
 **例外**：`extraPorts[].host` **不参与退让**，撞了硬拒——那些是对外契约口（worker 节点连的就是那个数字），静默挪走等于把它们全断掉，且门户侧一条都测不到。
@@ -29,7 +29,7 @@
 | `name` | 纯字符串 | 给对象不报错，但会被**拍平成 zh-CN**，另外两种语言就此丢掉 |
 | `scopeLabels[<scope>]` | 字符串 **或** `{ "zh-CN": …, "zh-TW": …, "en": … }` | 存 jsonb，同意屏按门户当前语言解析；回退链 当前语言 → `zh-CN` → `en` → 键名，所以 **`zh-CN` 是回退终点，必写** |
 | `aclManifest` 内的 `label` / `name` / `desc` | 同上（字符串或多语对象） | 角色矩阵按请求 locale 解析 |
-| `usageMetrics[].label` | **`{ "zh": …, "en"?: …, "tw"?: … }`** —— 键名与上一行**不是同一套** | 缺 `zh` ⇒ 提交即拒 |
+| `usageMetrics[].label` | **只能是对象** `{ "zh-CN": …, "en"?: …, "zh-TW"?: … }`（语言键同上一行；旧形状 `{ "zh", "en", "tw" }` 仍收，落库归一） | 给纯字符串或缺 `zh-CN` ⇒ 提交即拒 |
 
 `scopeLabels` 还有两条静默失效：**键不在 `scopes` 里的在写入时被直接丢弃**（同意屏上那条回落成键名，改 scope 名忘了改文案键就中）；
 **平台基础 scope（`userinfo.read` / `audit.write` / `notification.*` …）的文案不归 App 写** —— 那是平台统一维护的措辞，

package/skills/portal-micro-app/SKILL.md

@@ -22,7 +22,7 @@ description: '用于开发、修改或排查 XGENT Portal 的 iframe 微应用
 
 1. 在 App 自己的仓库新建 Vite + React 前端，配置固定空闲端口并开启 `strictPort`，避免自动换端口后加载错应用。
 2. 安装下述公开分发的 SDK/UI 包，按本地 [SDK 参考](references/sdk-reference.md) 接入握手与路由。
-3. 在自己的 `app.manifest.json` 声明 `navItems` / `scopes` / `aclManifest` / `dashboard.widgets`；租户管理员不能代填开发者声明。
+3. 在自己的 `app.manifest.json` 声明 `navItems` / `scopes` / `aclManifest` / `dashboardWidgets`（顶层数组，见 [Widget 契约](references/open-api-and-extensions.md#3-dashboard-widget应用动态)）；租户管理员不能代填开发者声明。
 4. Vite `base` 设为 `/apps/<key>/`，构建 `dist/`，用 `xgent-app-release` skill 的 `publish --dist` / `publish --manifest` 提交；涉及治理字段等待审批，按本次 proposal 的交付状态核对结果。
 5. 本地联调用 `portal-dev-setup` 的一盒环境。生产优先 `sdk.callService` 与同源托管；需要开发 CORS 白名单时交平台管理员处理。
 6. 在真实浏览器从宿主进入并走通主路径、路由往返与权限边界；不以构建通过代替 UI 验证。
@@ -45,7 +45,8 @@ skill 的「第 0 步」。仓里还没有 `.xgent-registry.env` ⇒ 停下，
 - **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。浏览器验收时检查版头与 App 内容没有重复标题。
 - **帮助页入口 `helpEntry`**：清单里声明一个可空字符串，版头工具条最右侧（全屏与刷新的**左边**）就多一枚帮助按钮；不声明就不出按钮。两种形态：`"/help"` = App 内路由（宿主置 `?r=`，不离开门户，**自动档**）、`"https://docs.example.com"` = 外站文档（新标签 + `noopener`，**走治理审核**，因为门户版头等于替这个域名背书）。`/…` 与 crumb `route` 同一条规则；外站必须 https（`http://` 连回环也拒）、无 fragment。它是**安装期快照**，改了要 bump 自己的 `version`；**租户不可覆盖**（想指向自家知识库去知识库 App 建条目）。门户不托管、不渲染、不翻译帮助正文。
 - **低频入口放版头、不占侧栏**：帮助中心 / 接入指引这类低频页别长期占着侧栏一个位置 —— 用 `helpEntry` 挂到版头，并把这一级显式推进面包屑。
-- 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；高度用 `sdk.resize`；未保存更改 `sdk.setDirty(true)` 让宿主拦离开。
+- 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；未保存更改 `sdk.setDirty(true)` 让宿主拦离开。
+- **iframe 高度二选一**：满高型（编辑器、聊天、带底部输入栏）**不调** `sdk.resize`，外壳 `height: 100dvh`（或 `100%`）+ 内部滚动——软键盘缩小可见区时宿主让 iframe 一起变矮、在 iframe 内触发 `resize`，App 在 `resize` 里把插入点 / 焦点输入框滚回视图，且 iOS 上输入控件计算字号 ≥16px（更小时 Safari 聚焦即放大，宿主不让位）；内容高度型调 `sdk.resize(scrollHeight)`，由宿主滚动区滚动，**调过一次就不再复位为满高、也不再为键盘让位**。没有键盘高度事件，也不需要。详见 [SDK 参考「iframe 高度」](references/sdk-reference.md#iframe-高度满高型与内容高度型软键盘)。
 
 ## Consent 硬规则
 
@@ -62,7 +63,7 @@ skill 的「第 0 步」。仓里还没有 `.xgent-registry.env` ⇒ 停下，
 
 ## 设计红线（平台一致性）
 
-- **不自建**「设置」页/导航（租户配置走平台应用配置页）、**不自建**审计页（写 `POST /api/v1/audit`）。
+- **配置界面别挂进你自己的导航**：全平台可热改的配置做平台级管理页、每租户不同的做租户级管理页，都在清单 `adminPages` 里声明，由门户嵌进应用市场编辑页 / 租户应用配置；应用内的业务设置才做应用内设置页（`aclManifest` 授权）。判断表见 portal-external-app skill「配置放哪一层」。**不自建**审计页（写 `POST /api/v1/audit`）。
 - **不做**「同步通讯录」：成员选择一律用 `@xgent/portal-ui` 的 `UserPicker` 按需 curated。
 - 列表页服务端分页，复用 `Page<T>` 契约与现有 helpers。
 - 复用 `@xgent/portal-ui` 已有组件再造新轮子。

package/skills/portal-micro-app/references/manifest-and-acl.md

@@ -21,15 +21,16 @@ Manifest 的权威载体是一条**市场清单（marketplace listing）**。安
 | `scopeLabels` | App 命名空间 scope 的同意页三语文案 |
 | `navItems` | `{ id, label, icon, path }[]` 贡献到左侧导航 |
 | `helpEntry` | 版头帮助按钮的入口，可空字符串。`"/help"` = App 内路由（宿主置 `?r=`，自动通过档）／`"https://…"` = 外站文档（新标签 + `noopener`，治理档）。不声明就不出这枚按钮 |
-| `dashboard.widgets` | 可展示的 Dashboard Widget 声明 |
-| `extPoints` | 仅 `settings.section` |
+| `dashboardWidgets` | 可加到 Dashboard 的 Widget 声明（**顶层数组**；嵌套的 `dashboard.widgets` 门户从不读取、提交即拒）。契约见 [open-api-and-extensions.md §3](open-api-and-extensions.md#3-dashboard-widget应用动态) |
+| `adminPages` | 你自己的管理页，门户嵌进管理面：`platform`（控制台 › 应用市场编辑页，平台管理员身份）/ `tenant`（租户 › 应用管理 › 配置，租户管理员身份），各 `{ route, label }`。仅 `micro` + `embed` 可声明，治理档；被嵌入时 `init.adminPage` 有值、App 只渲染那一页。放什么配置见 portal-external-app skill「配置放哪一层」 |
 | `dependencies` | 依赖的其他清单（安装按拓扑序补装；卸载被依赖会拦截） |
 | `exchangeTargets` | 经令牌交换读取哪些 App（安装时自动建交换白名单 + consent 共授） |
 | `embedCsp` | 托管前端的精确来源声明；开发版本支持 connectSrc/scriptSrc/styleSrc/fontSrc/imgSrc/mediaSrc，须正式发布并启用 strict/v2 后使用，旧门户只支持 connectSrc |
-| `tdtTtl` | TDT 有效期秒数，60–86400，默认 3600 |
 
 运营字段（租户管理员设，非 Manifest）：`visibility` / `showInCenter` / `pinned` / `enabledNavItemIds` / `webhookUrl` / `allowExchange` / `exchangeWhitelist`。
 
+令牌策略同样归租户管理员（应用配置里设，Manifest 不接受，写了只会让发布进人工审核且不生效）：`tdtTtl`（TDT 有效期秒数，60–86400，缺省 3600）/ `allowRefresh` / `refreshTtl`。App 不要依赖某个固定的 TDT 寿命。
+
 ## 3. ACL Manifest schema
 
 匿名页面可以位于 `/apps/<key>/…`，不应在该路由先强制 SDK 登录；数据授权仍归 App。

package/skills/portal-micro-app/references/open-api-and-extensions.md

@@ -31,31 +31,52 @@ HTTP 非 200 只留传输/认证/路由层：400 参数结构错、401 TDT 缺
 
 ## 3. Dashboard Widget（应用动态）
 
-Manifest `dashboard.widgets[]` 声明 → 用 `widget.write` 往**自己声明过的** Widget 推数据；写未声明的 key 得 `WIDGET_NOT_DECLARED`。
+有用户关心的状态（待办数、最近动态、待处理项）就该暴露至少一个 Widget——用户在工作台「自定义」里才挑得到你。三步：**声明 → 申请 scope → 前端推数据**。
 
-| 类型 | 用途 | `data` 形状 |
+**① 声明**：`app.manifest.json` 的**顶层** `dashboardWidgets` 数组（自动通过档，发版即生效）。
+
+```jsonc
+"dashboardWidgets": [
+  { "key": "my-stats", "source": "app", "owner": "<你的 listingKey>", "type": "metric",
+    "title": "我的待办", "dataMode": "app_push" }
+]
+```
+
+- `owner` **必须等于 listingKey**；`type` 只能是 `metric` / `activity` / `insight` / `topic_grid` / `topic_list`（**下划线**，`topic-list` 提交即拒）。
+- `title` / `subtitle` / `description` 是**纯字符串**（单语；给多语对象不生效，`xgent-app-release` 的 preflight 会报错）。
+- ⚠️ 旧文档写过嵌套的 `dashboard: { widgets: [...] }`——门户从来只读顶层 `dashboardWidgets`，那种写法现在提交即拒。
+
+**② scope**：`scopes` 里加 `widget.write`（平台基础 scope）。
+
+**③ 推数据**：用**用户态令牌**——前端 `sdk.dashboard.putWidgetData(key, data, { staleAfterSec? })` / `clearWidgetData(key)`，即 `PUT|DELETE /api/v1/dashboard/widgets/:key/data`，body `{ data, staleAfterSec? }`。
+
+- 数据**按用户**存：同一 (租户, 用户, App, widgetKey) 一行，重复 PUT 覆盖。某个用户没被推过，他的卡片就是空态——通常在 App 打开 / 数据变化时推一次。
+- `staleAfterSec` 到期后不再展示（上限 7 天）；不传 = 永不过期。
+- 写未声明的 key ⇒ `WIDGET_NOT_DECLARED`。
+
+| 类型 | 用途 | `data` 形状（服务端按类型裁剪） |
 | --- | --- | --- |
-| `metric` | 指标 | `{ value, label?, hint?, trend?: { direction:"up"\|"down"\|"flat", value } }` |
-| `activity` | 动态流 | `{ title?, items: { title, body?, at?, link?, icon? }[] }` |
-| `insight` | 图表 | `{ chart: { kind:"line"\|"bar"\|"area"\|"pie"\|"donut"\|"funnel", x?, series:[{name,data}] }, caption? }` |
-| `topic_grid` / `topic_list` | 入口网格 / 清单 | `{ items: { title, subtitle?, icon?/meta?, link? }[] }` |
+| `metric` | 指标 | `{ value, label?, hint?, trend?: { direction:"up"\|"down"\|"flat", value } }`；value ≤40 字、label ≤60、hint ≤120；**`link` 会被丢弃**（App 推的指标卡不可点） |
+| `activity` | 动态流 | `{ title?, items: { title, body?, at?, link?, icon? }[] }`；最多 20 条 |
+| `insight` | 图表 | `{ chart: { kind:"line"\|"bar"\|"area"\|"pie"\|"donut"\|"funnel", x?, series:[{name,data}] }, caption? }`；≤8 条序列、每条 ≤60 点 |
+| `topic_grid` / `topic_list` | 入口网格 / 清单 | `{ items: { title, subtitle?, icon?/meta?, link? }[] }`；grid ≤24、list ≤30 条 |
 
-规则：数据按用户 upsert（同一 (app,user,widgetKey) 一条，重复 PUT 覆盖）；按类型校验形状；`link` 用 Portal 深链如 `/app/todo?r=/today`。
+`link` 必须是站内深链（`/app/`、`/inbox`、`/settings`、`/dashboard`、`/console/`、`/admin/` 开头），如 `/app/<key>?r=/today`；不合格的链接被静默去掉。
 
-声明示例（listing 内）：
+**用户怎么加上**：工作台 →「自定义」→ 新增一个**与 Widget 类型相同**的分区 → 在选择器里挑你的 Widget → 保存。只有该用户看得见（已启用、有可见性、有席位）的 App 的 Widget 才会出现在选择器里。
 
-```ts
-dashboard: { widgets: [
-  { key: "todo-stats", source: "app", owner: "todo", type: "metric", title: "待办概览",
-    defaultItemsPerRow: 4, minColPx: 220, minH: 1, defaultH: 1, dataMode: "app_push" },
-]}
-```
+**限制（别踩）**：
+
+- **服务态令牌推不了**（端点只收用户态）：纯后端 / 无前端的 App 目前没法给 Widget 供数。
+- `dataMode: "app_query"` 只对平台自带的 pagebuilder 生效，别的 App 声明它卡片永远为空——用 `app_push`。
+- `titleI18n`、`refreshPolicy`、每个 Widget 的尺寸字段（`defaultItemsPerRow` / `minColPx` / `minH` / `defaultH` …）目前**不生效**，尺寸按类型缺省值走。
+- 从 manifest 里把 Widget **全部删掉**不会清掉已安装租户里的声明（空数组被当作「没声明」）。
 
 ## 4. 通知（消息服务）
 
 - 默认**自投**（发给当前用户）：落库 + 铃铛实时推送 + 按偏好发邮件，一个收口。
 - 跨用户投递：传 `userId`（本租户活跃成员）需额外 `notification.send.others` scope；跨租户拒绝；受两道限频（每 actor、每 actor→收件人）；收件人看到「由 <发送者> 经 <App>」强出处。
-- `link` 必须站内深链（白名单前缀 `/app/`、`/inbox`、`/settings`、`/dashboard`）；带协议或 `//host` 一律 `VALIDATION_FAILED`。`title/body/type` 有长度上限。
+- `link` 必须站内深链（白名单前缀 `/app/`、`/inbox`、`/settings`、`/dashboard`、`/console/`、`/admin/`）；带协议或 `//host` 一律 `VALIDATION_FAILED`。`title/body/type` 有长度上限。
 
 ## 5. 计划任务（Scheduler）
 

package/skills/portal-micro-app/references/sdk-reference.md

@@ -34,10 +34,15 @@ interface InitPayload {
   host: string;         // Portal web 源，拼可分享深链用
   theme: "light" | "dark";
   locale: string;       // "zh-CN" | "en" | "zh-TW"
+  localeOrder?: string[]; // 租户语言次序（回退链用）；旧宿主缺省
   user: { id: string; name: string } | null;
+  tenant?: { id: string; name: string; slug: string | null } | null; // 当前租户；旧宿主缺省，判空
   route: string | null; // 深链：地址栏 ?r= 携带的内部路由，用于还原
   fullscreen: boolean;
   acl?: AclInit;        // { bypass, permissions:[{pid,scope}], groups }
+  serviceBinary?: boolean; // 宿主能代理 callServiceBinary；旧宿主缺省，standalone 由 SDK 置 true
+  executableDownloadBase?: string; // 平台配置的可执行文件下载基址（无产品前缀）
+  adminPage?: "platform" | "tenant"; // 被门户嵌成管理页（清单 adminPages）时有值：只渲染那一页，收起自己的侧栏/顶栏
 }
 ```
 
@@ -65,7 +70,7 @@ sdk.acl.scope("myapp:page:items");           // "own" | "team" | "all"
 // 写入 Portal
 await sdk.notify({ title, body, type, link: "/app/your-app" });
 
-// Dashboard Widget（需 Manifest dashboard.widgets[] 声明 + widget.write）
+// Dashboard Widget（需 Manifest 顶层 dashboardWidgets[] 声明 + scopes 含 widget.write；数据按当前用户存）
 await sdk.dashboard.putWidgetData("activity", { title, items: [...] }, { staleAfterSec: 3600 });
 await sdk.dashboard.clearWidgetData("activity");
 
@@ -82,12 +87,15 @@ await sdk.scheduler.update(task.id, { status: "paused" }); await sdk.scheduler.c
 const data = await sdk.callService("myapp", "/api/things", { method: "GET" });
 // sdk.files.* 即 callService("files", …) 的薄封装
 
+// 取自家后端的完整二进制响应（≤ 32 MiB，见 §5.2；需 portal-sdk ≥ 0.5.4）
+const { data, contentType, size } = await sdk.callServiceBinary("myapp", `/exports/${id}/content`, { method: "POST" });
+
 // 下载文件（跨源预签名 URL 唯一安全姿势，见 §5.1）
 import { openDownload } from "@xgent/portal-sdk";
 openDownload(presignedUrl);
 
 // 与宿主 UI 协作
-sdk.resize(document.body.scrollHeight + 8);
+sdk.resize(document.body.scrollHeight + 8);   // 仅内容高度型；满高型不调，见下文「iframe 高度」
 sdk.navigate("/app/another-app");            // 让宿主跳 Portal 内路由
 sdk.routeSync("/detail");                    // 内部路由 → 地址栏 ?r=（可分享/刷新还原）
 sdk.setBreadcrumbs([                         // 页面层级 → 宿主版头面包屑
@@ -156,6 +164,24 @@ sdk.onFullscreen(on => ...);
 版头那枚帮助按钮上，并把这一级显式推进面包屑，进去之后位置依然清楚。范例是研发项目管理
 的帮助中心（指引 + FAQ）。
 
+### iframe 高度：满高型与内容高度型（软键盘）
+
+宿主给 iframe 的高度只有两种模式，按 App 形态二选一：
+
+| | 满高型 | 内容高度型 |
+| --- | --- | --- |
+| 适合 | 编辑器、聊天、带底部输入栏的 App | 文档式页面、短表单 |
+| 写法 | **不调** `sdk.resize()`；外壳 `height: 100dvh`（或 `100%`），内部滚动 | `sdk.resize(document.body.scrollHeight + 8)`，iframe 变成固定像素高，由宿主滚动区滚动 |
+| 软键盘弹出 | iframe 的布局视口随宿主可见区变矮，iframe 内触发 `resize`；收起后恢复 | Android：宿主滚动区随布局视口变矮，浏览器把焦点输入框滚入可视区；iOS：宿主不调整，保持浏览器原生平移 |
+
+- **调过一次 `resize` 就是内容高度型**：宿主不会再把 iframe 恢复为满高，也不再为它让位。满高型 App 不要为了「追可视区」去调 `resize`。
+- **满高型 App 自己负责两件事**：
+  1. 在 `window` 的 `resize` 里让当前插入点或焦点输入框保持可见，例如对焦点输入框 `scrollIntoView({ block: "nearest" })`，或按选区矩形调整内部滚动容器的 `scrollTop`。宿主只改 iframe 尺寸，不动 App 的内部滚动。
+  2. iOS 上输入控件（`input` / `textarea` / `contenteditable`）的**计算字号 ≥16px**。字号更小时 Safari 聚焦即放大页面，宿主检测到缩放就不让位，键盘照旧盖住底部。
+- App 拿不到也不需要键盘高度：没有对应的 SDK 事件，iframe 里的 `100dvh` / `innerHeight` 已经是可见区。
+- **不承诺**：键盘高度数值；与键盘动画逐帧同步（按帧合并，可能滞后一两帧）；捏合缩放与聚焦放大状态下的让位；横屏加键盘时的最小可用高度（可能很矮，甚至为 0）；iPad 浮动 / 分离键盘（不缩小可视区，不触发）；外接 / 硬件键盘（iPad 快捷栏可能触发，不承诺）；键盘打开时拖动期间的短暂闪跳；全屏状态下内容高度型 App 的滚动；门户自身页面在 iOS 上的让位。
+- **standalone**（App 自己就是顶层页面）：门户不介入，App 自己设置 viewport meta（如 `interactive-widget=resizes-content`）并监听自己的 `visualViewport`。
+
 ## 4. Consent（授权与同意）
 
 - `micro` 应用挂载 iframe **之前**宿主先查 consent；未授权渲染"授权屏"列出申请的 scope，用户点授权后才挂载、才签发 TDT。
@@ -188,6 +214,34 @@ openDownload(url);            // ✅ 顶层弹窗不受 frame-src 管，一闪
 - 服务端要保证 URL 带 `Content-Disposition: attachment`（files-server 的 `/:id/download` 默认如此），否则新标签页变成预览而不是落盘。
 - 例外：**blob:/同源** URL（前端自己生成的 CSV 等）用 `<a download>.click()` 没问题，属性生效、不产生导航。
 
+### 5.2 受控字节：`callServiceBinary`
+
+字节不能暴露成签名 URL 时（一次性领取证明、App 自己判领取资格），由你的后端直接返回字节，前端用 `callServiceBinary` 取。它和 `callService` 同一个地址解析与取票，区别在于把**完整**响应读完后以 `ArrayBuffer` 交给你：
+
+```ts
+import { type ServiceBinaryError } from "@xgent/portal-sdk";
+const init = await sdk.ready();
+if (init.serviceBinary !== true) return showHostTooOld();   // iframe 内的旧宿主：HOST_UNSUPPORTED
+try {
+  const { data, size } = await sdk.callServiceBinary("myapp", `/exports/${id}/content`, {
+    method: "POST", headers: { "x-claim-proof": proof }, timeoutMs: 600_000, signal,
+  });
+  if (size !== expected.size || await sdk.files.digest(data) !== expected.sha256) throw new Error("摘要不符");
+  const url = URL.createObjectURL(new Blob([data], { type: "application/zip" }));
+  Object.assign(document.createElement("a"), { href: url, download: expected.fileName }).click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+} catch (error) {
+  const { code, status, details } = error as ServiceBinaryError;   // 两种传输形状相同
+}
+```
+
+- **上限 33,554,432 字节**，整段读完才交付，不交出截断的字节；没有流式、断点续传，也没有进度事件。实测领取 32 MiB 时页面峰值内存增量约为上限的 2 倍。
+- **它不判业务**：你的 `{ok:false}` 信封原样 reject（code / message / details，带 HTTP status）；`{ok:true,data:null}` 是 `EMPTY_RESPONSE`；其他 JSON 是 `UNEXPECTED_RESPONSE` —— **JSON 文件不能经它领取**，二进制接口要返回非 JSON 的 content-type。
+- **其余失败码**：超限 `TOO_LARGE`；跳转、断流、网络失败 `TRANSPORT_FAILED`；长度不符 `TRUNCATED`；非 2xx 且不是信封 `HTTP_ERROR`；路径含 `..` 等为 `INVALID_PATH`；SDK 本地码 `NOT_READY` / `HOST_UNSUPPORTED` / `TIMEOUT` / `ABORTED`。取票失败（如 `EXCHANGE_NOT_ALLOWED`）原样到达，后端收不到请求。
+- ⚠️ **只在 401 时换票重试一次**（`callService` 是 401/403 都重试）：403 可能出现在你已消耗一次性证明之后，重发等于重放。所以后端的 401 只能出现在消耗证明之前。另外，复用的 keep-alive 连接若在你写出任何响应字节前被关闭，Chrome 会自己把同一请求重发一次（任何方法），宿主拦不住 —— **一次性证明的消费方必须拒绝第二次出示**。
+- `timeoutMs` 是从发起到读完的**总期限**，缺省 120 s，慢网下不够下完 32 MiB，按大小放宽。`signal` 可取消；iframe 重载、换代或离开 App 都会让调用得到 `ABORTED`，可用 `setDirty(true)` 让宿主在离开前确认。
+- 响应头只给 `contentType`，不回传 `Content-Disposition`：文件名从你自己的 JSON 里取。存盘用同源 `blob:` 加 `<a download>`（sandbox 已带 `allow-downloads`）。
+
 ## 6. 最小可用例子
 
 ```ts
@@ -202,6 +256,7 @@ async function main() {
   const user = await sdk.userinfo().catch(() => null);
   document.body.innerHTML = `当前用户：${user?.name ?? "—"}`;
   sdk.onTheme(t => document.documentElement.dataset.theme = t);
+  // 这是内容高度型页面：按内容报高度。满高型（编辑器、聊天）不要调，见 §3「iframe 高度」。
   sdk.resize(document.body.scrollHeight + 8);
 }
 main();