@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,83 @@
+---
+name: portal-micro-app
+description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型 App，iframe + @xgent/portal-sdk，即 apps/*-app）。凡任务涉及新建一个 App 前端、给某 App 加页面/导航项/Dashboard Widget、SDK 握手/getToken/callService、consent 授权屏、或 iframe 内的 UI 异常（弹窗无效/菜单点不动/主题/路由同步/全屏/剪贴板）时，务必先用本 skill——即使用户没提"微应用"三个字。Use when building or changing any micro-app frontend embedded in the portal (apps/*-app), the portal SDK handshake, navItems, dashboard widgets, or iframe-specific UI issues.'
+---
+
+# portal-micro-app · 嵌入式微应用（iframe + SDK）开发
+
+微应用是被 Portal 以沙箱 iframe 嵌入的普通 Web 页面：**不自己实现登录、不持有 App Secret**，身份由宿主经 postMessage 握手注入。本文件是工作流与红线；具体契约按需读 `references/`（为本 skill 提炼的自包含参考，可整目录拷到任何 repo 使用；权威源是门户仓库 `docs/SSO与App开发指引.md`，冲突以门户仓库为准）。
+
+
+> **路径约定（先读这条，能省一次白找）**：本 skill 里出现的 `apps/…` `packages/…` `docs/…`
+> `deploy/…` 这类路径**都在门户仓**。在 App 自己的 repo 里它们**不存在** —— 它们标注的是
+> 「门户侧要做什么」或某段内容的出处，**不是让你去打开的文件**。找不到不是配置错误：
+> 别去创建、别去全局搜、别把它当缺失依赖报出来。你需要的一切都在本 skill 的
+> `references/`（自包含）。若你正在门户仓里工作，那这些路径就是可以直接打开的真实文件。
+>
+> ⚠️ 一个例外：`/apps/<key>/`（带前导斜杠）是**线上 URL 路径**——微应用产物的挂载点，
+> 与仓内的 `apps/<key>-app/` 目录无关，别混。
+
+## 按任务读参考
+
+| 任务 | 读 |
+| --- | --- |
+| 握手 / SDK API / 令牌与 consent / callService | [references/sdk-reference.md](references/sdk-reference.md) |
+| 声明导航、scope、ACL、Widget、依赖 | [references/manifest-and-acl.md](references/manifest-and-acl.md) |
+| 调 Open API / Widget 推送 / 通知 / 内容 / 计划任务 / 审计 / 错误码 | [references/open-api-and-extensions.md](references/open-api-and-extensions.md) |
+
+门户 monorepo 内工作时的活教材：`apps/sample-app/src/main.ts`（SDK 每个能力的端到端演示）、`apps/spms-app`（重业务）、`packages/portal-sdk`（SDK 源码）。外部项目没有这些路径，以 references 为准。
+
+## 新建一个 micro App 前端的最小闭环（门户 monorepo 内）
+
+1. 新建 `apps/<key>-app`（Vite + React，复制最接近的现有 app 骨架），包名 `@xgent/<key>-app`，端口取当前空闲的 53xx（看根 `package.json` 的 `dev:all` 已占端口）。
+2. 挂进根 `package.json` 的 `dev:all`（concurrently 一把起齐）。**绝不**单独叠跑 `dev:<key>`——Vite 端口被占会自增抢相邻端口，导致别的 App iframe 加载错页面。
+3. 清单声明：`navItems` / `scopes` / `aclManifest` / `dashboard.widgets` 只能由应用自身声明（`apps/api/src/modules/acl/manifests.ts` + `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS`），租户管理员不能手填。改完重新 `db:seed` 或走清单同步更新。
+4. dev 直连 Open API 需 CORS：把 app 源加进 api 的 CORS 白名单 env；生产优先 `sdk.callService`/同源托管，前端完全不碰跨域。
+5. UI 开发遵守 CLAUDE.md 强制两步：设计用 `impeccable` skill，验证用 Chrome extension 真浏览器走通主路径。
+
+**你的 App 不在门户 monorepo 里（代码在自己的 repo）** ⇒ 上面 1–3 步一条都不适用：没有
+`apps/<key>-app` 目录、没有 `dev:all`、清单也不在 `LISTING_DEFS` 里。你的闭环是另一条：
+vite `base` 设成 `/apps/<key>/` → build 出 `dist/` → 用 `xgent-app-release` skill 的
+`publish --dist` 交上去（清单同理走 `publish --manifest`，你 repo 里那份 `app.manifest.json`
+就是唯一事实源）；想在真门户里先看一眼，把 `dist` 绝对路径挂进一盒（`portal-external-app`
+skill 的 `references/registration-and-onebox.md` §4）。**本文件其余部分（SDK 硬规则、consent、
+iframe 坑、设计红线、三份 references）与你在哪个 repo 无关，照用。**
+
+## SDK 硬规则
+
+- 私有页面从 `const sdk = createPortalClient(); const init = await sdk.ready();` 开始。SDK 0.4.0 支持 iframe 与同源 standalone 共用自举；声明 `openModes` 后从 `/open/<key>` 进入。顶层必须处理 `ready()` typed error 和 `onContextChanged()`，失效时卸载私有视图与应用缓存，并提供显式 `openGate()`；不要自动跳登录。匿名页可不调用 `ready()`。生产从 `/apps/<key>/` 推导 key，开发的 appKey/host/apiBase 来自构建配置，不能读 URL 配认证主机。详见门户 SDK README 与 SSO §5.9。
+- `sdk.getToken()` 自动缓存、到期前 30s 续签——**不要**自己存 TDT、不要写 localStorage。
+- 用户长期凭证由本 App 后端委托门户签发。前端只将新建/迁移响应保存在当前一次性展示组件；不要用 Query/Mutation 缓存保存含 secret/token 的响应。关闭后清除，复制失败提供选中文本和重试。门户集中管理入口是 `/me?tab=keys`；App 保留项目/能力/路由配置、旧密钥停用与远端撤销重试。
+- 全局平台管理员不在 TDT JWT / `InitPayload` 里；`sdk.acl.bypass` 和 `sdk.userinfo().role` 只表示当前租户。前端即使拿到 session-only `/auth/me.isPlatformAdmin` 也只能做展示，不能转发给后端授权；跨租户后端只认 TDT 自省返回的 `isPlatformAdmin`。
+- 调自己的独立后端一律 `sdk.callService("<listingKey>", path, opts)`（宿主代转发、零跨域、401/403 自动重铸重试一次）。iframe 直接跨域 `fetch` 独立后端是错误姿势。
+- 权限：`sdk.acl.can(pid)` / `sdk.acl.scope(pid)` 只做**隐藏按钮/入口**的 UX 门；真正拦截靠后端。前端判过 ≠ 安全。
+- 路由：内部路由变化调 `sdk.routeSync(path)` 同步到 `?r=`；同时**必须**订阅 `sdk.onRoute` 处理宿主推回的路由（浏览器后退、同 App 多导航项切换）。只写单向 routeSync 会出现"同一 App 两个菜单点了不切换"的 bug。二级详情页把完整路径（如 `/items/<id>`）routeSync 出去，刷新/分享才能还原。
+- 版头面包屑：调 `sdk.setBreadcrumbs(crumbs)` 上报页面层级（宿主最左恒为「应用图标 + 应用名」= 应用首页，你报的是其后那几级；首页推 `[]`，每次是整条 trail 的**全量覆盖**）。四条规矩：① 挂在**视图驱动的 effect** 上，**不要**散在各个 `routeSync()` 调用点——宿主发起的路由变化只走 `onRoute`，挂错的症状是"侧栏切页后面包屑空着"；② `onRoute("")`（空路由）必须落到首页视图，版头最左那一级靠它工作；③ 标签要异步查询才知道时**宁可少一级**，不推 id 占位、不推"加载中…"，数据回来再整条覆盖（`FR-12` 这种展示 key 可以推，内部 UUID 不可以）；④ `label` 用**自己当前的语言**解析好（宿主不翻译），切语言在 `onLocale` 里重推。上限 6 级 / label 120 字符 / route 512 字符且必须 `/` 开头（不得以 `//` 开头），超限被静默截断；末级不带 `route`。
+- **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。回归门 `apps/api/scripts/verify-app-chrome.ts`。
+- **帮助页入口 `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)` 让宿主拦离开。
+
+## Consent 硬规则
+
+- 宿主挂 iframe 前有 consent 门；mint 会把**本次签发的 scope 记为用户的同意范围**。用子集 scope mint 会**收窄**已有同意，之后更宽的 mint 触发 `CONSENT_REQUIRED`。日常 getToken 不要传裁剪过的 scopes。
+- 声明了 `exchangeTargets` 的 App，用户首次进入时 consent 门会**共授**跨应用交换同意——跨应用读数据为空时先想到这个（详见 portal-app-exchange skill）。
+
+## iframe 已知坑（都真实踩过）
+
+- `window.prompt` / `window.confirm` / `window.alert` 在跨源沙箱 iframe 里**被静默忽略**——一律用应用内 DOM 模态框。
+- Tailwind 的 `/alpha` 颜色修饰符（如 `bg-primary/50`）在主题的普通 `var()` 颜色上**静默失效**——用 `opacity-NN` 或预算好的色值。
+- Radix 菜单/Popover 触发器放在模态 Dialog 里"点了没反应"：触发器组件必须 `forwardRef`，且弹层 z-index 要高于 dialog overlay。
+- 跨源 iframe 里剪贴板 API 受限；Chrome extension 也看不进跨源 iframe（验证时从宿主页面操作）。
+- `.xg-md` markdown 渲染若用 `@xgent/file-preview` 的 `./markdown` 子路径，宿主需映射 hsl 通道 CSS 变量。
+
+## 设计红线（平台一致性）
+
+- **不自建**「设置」页/导航（租户配置走平台应用配置页）、**不自建**审计页（写 `POST /api/v1/audit`）。
+- **不做**「同步通讯录」：成员选择一律用 `@xgent/portal-ui` 的 `UserPicker` 按需 curated。
+- 列表页服务端分页，复用 `Page<T>` 契约与现有 helpers。
+- 复用 `packages/portal-ui` 已有组件再造新轮子。
+
+## 完成标准
+
+类型检查/单测只证明代码对，不证明功能对。微应用改动必须在真浏览器（Chrome extension）里从宿主进入、走通主路径与关键边界后才算完成；环境起不来就显式说明"未在浏览器中验证"。

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

@@ -0,0 +1,79 @@
+# Manifest 与 ACL 声明（微应用视角）
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §4/§13.2（2026-07）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+
+## 1. 模型：开发者字段快照
+
+Manifest 的权威载体是一条**市场清单（marketplace listing）**。安装 = 把开发者字段快照复制进该租户的 `apps` 行；清单升级后租户「同步更新」重拷开发者字段（运营字段不动）。`listingKey` 就是 TDT 的 `aud`，不可改。
+
+⚠️ **ACL Manifest 和 navItems 只能由应用自身声明**（代码注册表 / 市场清单），租户管理员不能在注册表单手填。门户 monorepo 内的声明位置：ACL → `apps/api/src/modules/acl/manifests.ts`；listing → `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS`；改完重新 seed / 发布清单 / 租户同步更新。
+
+## 2. 微应用相关的开发者字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `listingKey` | `^[a-z0-9-]+$`，2–40。= TDT `aud`，不可改 |
+| `name` / `tagline` / `desc` / `icon` / `color` / `cat` | 展示信息 |
+| `type` | `micro`（iframe 嵌入，本 skill 场景）/ `link` / `native` / `service` |
+| `embedUrl` | iframe 源。生产同源托管为 `/apps/<key>/` |
+| `allowedOrigins` | postMessage 握手来源白名单 |
+| `scopes` | 申请的权限范围（最小够用——授权屏逐条展示，越多越劝退） |
+| `scopeLabels` | App 命名空间 scope 的同意页三语文案 |
+| `navItems` | `{ id, label, icon, path }[]` 贡献到左侧导航 |
+| `helpEntry` | 版头帮助按钮的入口，可空字符串。`"/help"` = App 内路由（宿主置 `?r=`，自动通过档）／`"https://…"` = 外站文档（新标签 + `noopener`，治理档）。不声明就不出这枚按钮 |
+| `dashboard.widgets` | 可展示的 Dashboard Widget 声明 |
+| `extPoints` | 仅 `settings.section` |
+| `dependencies` | 依赖的其他清单（安装按拓扑序补装；卸载被依赖会拦截） |
+| `exchangeTargets` | 经令牌交换读取哪些 App（安装时自动建交换白名单 + consent 共授） |
+| `embedCsp.connectSrc` | 同源托管下的额外 connect-src（如直传对象存储） |
+| `tdtTtl` | TDT 有效期秒数，60–86400，默认 3600 |
+
+运营字段（租户管理员设，非 Manifest）：`visibility` / `showInCenter` / `pinned` / `enabledNavItemIds` / `webhookUrl` / `allowExchange` / `exchangeWhitelist`。
+
+## 3. ACL Manifest schema
+
+```ts
+interface AclManifest {
+  version: string;          // reconcile 基准
+  landingPageKey?: string;  // 应用可见性判定页（缺省第一个 page）
+  groups?: AclGroup[];
+  pages: AclPage[];
+  actions: AclAction[];
+  roleTemplates?: AclRoleTemplate[]; // 管理员可"从模板克隆"角色（克隆后脱钩）
+}
+interface AclPage {
+  key: string;               // 稳定 id，进 PID
+  path: string;              // 路由 pattern，匹配运行时 ?r=
+  label: I18nText;           // 字符串或 { "zh-CN", "en" }
+  parentKey?: string;        // 页面树（矩阵分组 + 前缀通配）
+  navItemId?: string;        // 关联 navItems[].id
+  supportedScopes?: DataScope[]; // 缺省 ["all"]
+  defaultForMember?: boolean;    // 授予内置 member 基线
+}
+interface AclAction {
+  key: string; label: I18nText; pageKey?: string;
+  supportedScopes?: DataScope[]; dangerous?: boolean; defaultForMember?: boolean;
+}
+```
+
+**PID 语法** `<appKey>:<kind>:<key>`，`kind ∈ {page, action}`；通配由粗到细：
+
+```
+<appKey>:*  >  <appKey>:page:*  >  <appKey>:page:projects.*  >  <appKey>:page:projects
+```
+
+**DataScope（ABAC-lite）** `own` < `team` < `all`：`own` 行的 ownerUserId==当前用户；`team` 行属于用户所在组；`all` 无行级过滤。同一 PID 命中多条授予时最宽范围胜出。
+
+**模型**：纯加法 RBAC——角色只授予不拒绝、有效权限=所有角色授予并集、默认拒绝、租户 `admin` bypass 一切、`member` 基线自动获得各应用的 `defaultForMember` 项。
+
+## 4. 运行时两道门
+
+1. **前端 UX 门**：握手注入 `init.acl` → `sdk.acl.can(pid)` / `sdk.acl.scope(pid)` 隐藏入口/按钮。**仅 UX，不可信。**
+2. **后端安全门**：独立后端从自省结果拿 `bypass`/`permissions`/`groups` 真正拦截。前端判过 ≠ 安全。
+
+## 5. navItems 生命周期
+
+- 市场安装时 `navItems` 快照到 `apps.navItems`，默认全部启用（`enabledNavItemIds`）；管理员之后只能启停声明项，不能手填新项。
+- Shell 经 `GET /api/apps/nav` 聚合可见应用的已启用项；点击打开 `/app/:appKey?r=<path>`，SDK 握手时 `init.route` 就是这个 path。
+- `navItems[].id` 绑定 `AclPage.navItemId` 后，侧栏按用户 ACL 隐藏无权入口——但应用前端仍要 `sdk.acl` 做 UX 门、后端仍做安全门。
+- 约定：`id` 应用内稳定（改 id = 删旧菜单加新菜单，租户启用状态受影响）；`path` 用应用内部路由（`/` 开头）；`icon` 用 Portal 支持的图标名。

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

@@ -0,0 +1,86 @@
+# Open API 与扩展点（微应用视角）
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §8/§13/附录 B（2026-07）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+
+## 1. 统一响应信封
+
+业务状态**不走 HTTP 状态码**：
+
+```jsonc
+{ "ok": true, "data": { ... } }                                  // 成功
+{ "ok": false, "error": { "code": "INSUFFICIENT_SCOPE", "message": "...", "details": {} } }  // 业务失败，HTTP 仍 200
+```
+
+HTTP 非 200 只留传输/认证/路由层：400 参数结构错、401 TDT 缺失/无效/过期/撤销、403 scope 或权限不足、404 路由不存在（**数据不存在不是 404**，是 `200 + data:null`）、429 限流、5xx 真故障。SDK 已封装：非 ok 把 error 作为异常抛出，`try/catch` 即可。
+
+## 2. 用户态端点一览（`Authorization: Bearer <TDT>`，基址 = init.apiBase + `/api/v1`）
+
+| 端点 | scope | 说明 |
+| --- | --- | --- |
+| `GET /userinfo` | `userinfo.read` | 当前用户资料 + 本次 scopes |
+| `GET /directory/users` | `directory.read`（+`directory.email.read` 才含邮箱） | 租户成员基础资料（默认不含邮箱，PII） |
+| `POST /notifications` | `notification.send`（跨用户需 `notification.send.others`） | 见 §4 |
+| `PUT /dashboard/widgets/:key/data` | `widget.write` | 推送 Widget 数据（须先声明，见 §3） |
+| `DELETE /dashboard/widgets/:key/data` | `widget.write` | 清除 Widget 数据 |
+| `POST /audit` | `audit.write` | 关键操作写平台统一审计（不自建审计） |
+| `GET/PUT /settings/me` | `settings.read/write` | 当前用户偏好 |
+| `GET /content-types`、`/content/:type` CRUD | `content.read/write` | 内容服务，见 §6 |
+| `/scheduler/tasks` CRUD | `scheduler.read/write` | 计划任务，见 §5 |
+
+限流：按 `(appKey, tenant)` 每分钟，额度随租户套餐（旗舰 600 / 专业 300 / 标准 120）。超额 `RATE_LIMITED`。
+
+## 3. Dashboard Widget（应用动态）
+
+Manifest `dashboard.widgets[]` 声明 → 用 `widget.write` 往**自己声明过的** Widget 推数据；写未声明的 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? }[] }` |
+
+规则：数据按用户 upsert（同一 (app,user,widgetKey) 一条，重复 PUT 覆盖）；按类型校验形状；`link` 用 Portal 深链如 `/app/todo?r=/today`。
+
+声明示例（listing 内）：
+
+```ts
+dashboard: { widgets: [
+  { key: "todo-stats", source: "app", owner: "todo", type: "metric", title: "待办概览",
+    defaultItemsPerRow: 4, minColPx: 220, minH: 1, defaultH: 1, dataMode: "app_push" },
+]}
+```
+
+## 4. 通知（消息服务）
+
+- 默认**自投**（发给当前用户）：落库 + 铃铛实时推送 + 按偏好发邮件，一个收口。
+- 跨用户投递：传 `userId`（本租户活跃成员）需额外 `notification.send.others` scope；跨租户拒绝；受两道限频（每 actor、每 actor→收件人）；收件人看到「由 <发送者> 经 <App>」强出处。
+- `link` 必须站内深链（白名单前缀 `/app/`、`/inbox`、`/settings`、`/dashboard`）；带协议或 `//host` 一律 `VALIDATION_FAILED`。`title/body/type` 有长度上限。
+
+## 5. 计划任务（Scheduler）
+
+- 任务归属 `(应用, 用户)`，每对上限 10 个；`cron` + `tz`（默认 `Asia/Shanghai`）。
+- 触发时：应用配了 `webhookUrl` → 调 webhook（payload 带 userId）；否则给任务主人发收件箱提醒。
+- 取消务必走应用（SDK→DELETE）；直接删库行不会停掉内存里的调度器。
+
+## 6. 内容服务（headless CMS）
+
+应用声明内容类型（代码定义，按 listingKey 归属）+ `content.read/write` scope，即可 CRUD，**不用自建表/后端**。`recordScope:"user"` 记录按 (应用,用户) 隔离；`"tenant"` 租户内共享。字段类型 `text/textarea/number/boolean/date/datetime/enum/json`，支持 required/default/maxLength/min/max/options，写入按 schema 校验。内部表名 `${owner}__${key}`，应用间不碰撞。
+
+## 7. 审计
+
+关键操作（建/改/删配置、密钥等）POST `/api/v1/audit`：`{ event, object, detail, result, diff }`。best-effort，失败不阻断业务本身。需声明 `audit.write` scope。
+
+## 8. 常见错误码（前端只认 code 不认文案）
+
+| code | 场景 |
+| --- | --- |
+| `CONSENT_REQUIRED` | 宿主注入前用户未授权（或同意被子集 mint 收窄过） |
+| `EXCHANGE_CONSENT_REQUIRED` / `EXCHANGE_NOT_ALLOWED` | 跨应用调用未获用户授权 / 缺布线 |
+| `INSUFFICIENT_SCOPE` / `INSUFFICIENT_PERMISSION` | scope / ACL 不足（HTTP 403） |
+| `WIDGET_NOT_DECLARED` / `EXT_POINT_NOT_DECLARED` | 未声明该 Widget / 扩展点 |
+| `SCHEDULER_LIMIT` / `TASK_NOT_OWNED` | 计划任务超限 / 越权 |
+| `VALIDATION_FAILED` | 参数校验失败（含通知 link 非站内深链、超长） |
+| `RATE_LIMITED` | 限流（HTTP 429） |
+| `APP_NOT_FOUND` / `APP_DISABLED` / `APP_NOT_EMBEDDABLE` | 应用不存在/停用/不可嵌入 |
+| `CONTENT_TYPE_NOT_FOUND` / `CONTENT_ENTRY_NOT_FOUND` | 内容类型/记录不存在 |

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

@@ -0,0 +1,208 @@
+# SDK 与令牌参考（微应用视角）
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §5/§7.4/§8.1/§10（2026-08）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库原文为准。
+
+## 1. 握手与令牌注入
+
+你的页面被 Portal 以沙箱 iframe 嵌入（`sandbox="allow-scripts allow-same-origin allow-forms allow-popups ..."`，`referrerPolicy=no-referrer`）。流程：
+
+```
+Portal 宿主 (MicroAppHost)                你的 iframe (portal-sdk)
+   │ ① 先过 consent 门（§4）                  │
+   │───────────── 挂载 iframe ──────────────►│ ② createPortalClient()
+   │◄──────── req: ready ───────────────────│
+   │ ③ event: init {appKey,apiBase,host,     │
+   │    theme,locale,user,route,fullscreen,  │
+   │    acl} ────────────────────────────────►│ ready() 返回 InitPayload
+   │◄──────── req: getToken {scopes?} ───────│ ④ getToken()
+   │ ⑤ 宿主用用户会话 POST /api/tokens/mint    │
+   │    → {access_token,...} ────────────────►│ 拿到 TDT（SDK 自动缓存）
+   │                                          │ ⑥ 用 TDT 调 /api/v1/* 或 callService
+```
+
+要点：
+- 宿主只接受来源在 `embedUrl` + `allowedOrigins` 白名单内的 postMessage。
+- 应用**全程拿不到 App Secret**；TDT 由 SDK 自动缓存、到期前 30s 才重新申请——不要自己持久化令牌。
+- TDT 是 HS256 JWT，`aud` = 你的 appKey，`tenant_id`/`user_id`/`scopes` 都在 claims 里；短期有效（默认 3600s）、可即时吊销。**`isPlatformAdmin` 不在 JWT 里**，它是 Portal 资源服务器自省时实时派生的字段。
+
+## 2. InitPayload
+
+```ts
+interface InitPayload {
+  appKey: string;
+  apiBase: string;      // Open API 绝对地址，拼 /api/v1/* 用
+  host: string;         // Portal web 源，拼可分享深链用
+  theme: "light" | "dark";
+  locale: string;       // "zh-CN" | "en" | "zh-TW"
+  user: { id: string; name: string } | null;
+  route: string | null; // 深链：地址栏 ?r= 携带的内部路由，用于还原
+  fullscreen: boolean;
+  acl?: AclInit;        // { bypass, permissions:[{pid,scope}], groups }
+}
+```
+
+### 2.1 平台管理员的前后端边界
+
+- `InitPayload` 不含 `isPlatformAdmin`；`acl.bypass` 代表**当前租户 admin**，`sdk.userinfo().role` 也只是 TDT 当前租户的角色，都不是全局平台管理员判据。
+- 当 micro App 以 `/apps/<key>/` **同源部署**时，前端可调 session-only `GET /auth/me` 取 `data.isPlatformAdmin` 做菜单/文案展示；该端点是 Portal shell 会话面，不是 TDT Open API/SDK 稳定契约，独立后端无 Cookie 也不应调它。非同源/dev 环境不要假设它可用。
+- 前端值**绝不参与授权**：不发 `X-Is-Platform-Admin`，不把 body 里的布尔传给后端当判据，不转发 Cookie 让后端代调 `/auth/me`。如资源服务器有平台级跨租户路由，它必须以 SA Basic 自省 TDT，并校验自省返回的 `claims.isPlatformAdmin === true`（服务态恒为 `false`）。
+
+## 3. SDK API 速查
+
+```ts
+import { createPortalClient } from "@xgent/portal-sdk";
+const sdk = createPortalClient();            // 必须运行在 Portal 的 iframe 内
+const init = await sdk.ready();
+
+// 身份与令牌
+const token = await sdk.getToken();          // 原始 TDT（一般不用，便捷方法已内置）
+const me    = await sdk.userinfo();          // GET /api/v1/userinfo
+
+// 权限 UX 门（真正的安全门在后端）
+sdk.acl.can("myapp:action:item.delete");     // boolean
+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）
+await sdk.dashboard.putWidgetData("activity", { title, items: [...] }, { staleAfterSec: 3600 });
+await sdk.dashboard.clearWidgetData("activity");
+
+// 内容服务（headless CMS，需 content.read/write + 声明内容类型）
+await sdk.content.types(); await sdk.content.list("note", { limit: 20 });
+await sdk.content.create("note", {...}); await sdk.content.update("note", id, {...});
+await sdk.content.remove("note", id);
+
+// 计划任务（需 scheduler.read/write）
+const task = await sdk.scheduler.create({ name, cron: "0 9 * * *", params });
+await sdk.scheduler.update(task.id, { status: "paused" }); await sdk.scheduler.cancel(task.id);
+
+// 调你自己的独立后端（宿主代理，零跨域）
+const data = await sdk.callService("myapp", "/api/things", { method: "GET" });
+// sdk.files.* 即 callService("files", …) 的薄封装
+
+// 下载文件（跨源预签名 URL 唯一安全姿势，见 §5.1）
+import { openDownload } from "@xgent/portal-sdk";
+openDownload(presignedUrl);
+
+// 与宿主 UI 协作
+sdk.resize(document.body.scrollHeight + 8);
+sdk.navigate("/app/another-app");            // 让宿主跳 Portal 内路由
+sdk.routeSync("/detail");                    // 内部路由 → 地址栏 ?r=（可分享/刷新还原）
+sdk.setBreadcrumbs([                         // 页面层级 → 宿主版头面包屑
+  { label: "需求池", route: "/requirements" },
+  { label: "FR-12 登录页改造" },             // 末级不带 route（它就是当前页）
+]);                                          // 首页推 []；整条 trail 全量覆盖
+sdk.setDirty(true);                          // 未保存更改 → 宿主拦截离开
+sdk.requestFullscreen(true);
+
+// 订阅宿主事件
+sdk.onTheme(t => ...); sdk.onLocale(l => ...);
+sdk.onRoute(p => ...);                       // ?r= 变化（后退 / 同 App 多导航切换）
+                                             // p === "" ⇒ 宿主点了「回应用首页」
+sdk.onFullscreen(on => ...);
+```
+
+### `setBreadcrumbs` 的四条规矩
+
+⚠️ 它需要 `@xgent/portal-sdk` **≥ 0.2.1**。`0.x` 上 `^` 只放行 patch —— 依赖范围写
+`^0.1.0` 的仓**不会**自动吃到它（症状：`sdk.setBreadcrumbs is not a function`）。
+把 `package.json` 里的范围显式提上去再装。
+
+宿主版头最左恒为「应用图标 + 应用名」（= 应用首页），你上报的是**其后**那几级。
+
+1. **不含应用本身那一级**；首页推 `[]`。每次调用是**整条 trail 的全量覆盖**，不是追加。
+2. **挂在视图驱动的 effect 上**（与决定路由的是同一份 state），**别**散在各个
+   `routeSync()` / `navigate()` 调用点 —— 宿主发起的路由变化只走 `onRoute`（且不许在
+   `onRoute` 里 echo `routeSync`），挂错的症状是「侧栏切页后面包屑空着」。
+3. **`onRoute("")` 必须落到首页视图** —— 用户点最左那一级时宿主就是把 `?r=` 清空再推给你。
+4. **标签要异步查询才知道时宁可少一级**，不推 id 占位、不推「加载中…」；数据回来再整条
+   覆盖一次（两段式，谁后到谁生效）。`FR-12` 这种**展示 key** 是已知事实可以推，
+   `a3f9…` 这种内部 UUID 不可以。
+
+`label` 由你用**自己当前的语言**解析好（宿主不翻译），切语言要在 `onLocale` 里重推。
+上限 6 级 / label 120 字符 / `route` 512 字符且必须 `/` 开头（不得以 `//` 开头），
+超限被宿主静默截断。fire-and-forget：旧宿主收不到也不会报错，版头退化成「图标 + 名字」。
+
+### App 内部不要自绘图标与名称
+
+**App 内部不得渲染自己的图标与名称。** 版头最左那一级恒为「应用图标 + 应用名」，且它是
+可点的应用首页；App 再画一份 = 同屏两处说同一句话，而且租户改过 App 名之后两处会说得
+不一样（`apps.icon` / `apps.name` 租户可改，App 内的 i18n 词条改不了）。**tagline / 副标题**
+同理（应用中心已展示过）。**可以留**：角色、工作区、当前对象这类运行期事实；以及
+`main.tsx` 里 App 脱离门户打开时的 standalone 提示页（那一屏没有版头）。
+
+### `helpEntry`：在清单里声明帮助页入口
+
+清单里加一个可空字符串 `helpEntry`，版头工具条最右侧（全屏与刷新的**左边**）就多一枚
+帮助按钮；不声明就不出按钮（不渲染，不是禁用）。
+
+```jsonc
+"helpEntry": "/help"                      // App 内路由：宿主置 ?r=，用户不离开门户
+"helpEntry": "https://docs.example.com"   // 外站文档：新标签打开（noopener）
+```
+
+- `/…` 与 crumb 的 `route` **同一条规则**（`/` 开头、不得 `//` 开头、无控制字符、≤512）；
+  `https://…` 必须可解析、必须 https（`http://` 连回环也拒）、无 fragment、无通配符。
+- **内页路由自动档，外链走治理审核**（门户版头替一个域名背书）。
+- 它是**安装期快照**：改了内容要 bump 自己的 `version`。**租户不可覆盖** —— 想指向自家
+  知识库的诉求去知识库 App 实现。
+- 门户**不托管、不渲染、不翻译**帮助正文，这个字段只是一个入口。
+
+### 低频入口放版头，不占侧栏
+
+帮助中心、接入指引这类低频页面不该长期占着 App 侧栏一个位置：声明 `helpEntry` 让它挂在
+版头那枚帮助按钮上，并把这一级显式推进面包屑，进去之后位置依然清楚。范例是研发项目管理
+的帮助中心（指引 + FAQ）。
+
+## 4. Consent（授权与同意）
+
+- `micro` 应用挂载 iframe **之前**宿主先查 consent；未授权渲染"授权屏"列出申请的 scope，用户点授权后才挂载、才签发 TDT。
+- `POST /api/tokens/mint` 内部同一道门：未授权抛 `CONSENT_REQUIRED`（带 appName + 缺失 scopes）。
+- ⚠️ **同意即窄化**：mint 会把本次签发的 scope **记为**用户的同意范围。用子集 scope mint 会收窄已有同意，之后更宽的 mint 触发 `CONSENT_REQUIRED`。需要更宽 scope 前先重新走 consent；日常 getToken 不要传裁剪过的 scopes。
+- 用户在「个人中心 › 已授权应用」可撤销（撤销即 bump (user,app) 版本，旧 TDT 立即失效）。
+- 声明了 `exchangeTargets` 的 App，consent 门会**共授**跨应用交换同意。
+
+## 5. callService vs 直连 CORS
+
+- 浏览器里 iframe 直接 `fetch` Open API / 独立后端受 CORS 限制；后端 CORS 白名单是环境变量维护的有限源列表。
+- 首选 `sdk.callService`：宿主为该应用铸/复用 host-proxy TDT、代为 `fetch`、回传响应；你的后端只需信任 Portal web 源一个跨域来源。401/403 时宿主自动重铸令牌重试一次。
+- ⚠️ **目标不是你自己时走的是令牌交换，不是 mint**：`callService("<别的 App>", …)`（`sdk.files.*` 就是它的薄封装）由宿主换一张 `aud=<目标>` 的票，所以**清单里必须有 `exchangeTargets` + 目标命名空间 scope**，用户也要同意过。漏声明的症状是 iframe 里这类调用全挂——不是 CORS，查 portal-app-exchange skill。
+- `callService` 不替后端做授权——后端仍要自省校验 aud/scope（这不是前端的事，但别以为走了代理就"安全了"）。
+
+### 5.1 下载文件：只用 `openDownload`，别自己写 `<a href>.click()`（BUG-48）
+
+预签名下载 URL 指向**对象存储源**，跟 App 前端不同源。`<a href=url>.click()` 于是不是"下载"，而是让 App 的 iframe **自己导航**过去——门户 CSP 的 `frame-src` 只放行 App 前端源，Chrome 会把**整个 App** 换成拦截页：「该内容被屏蔽了。请联系网站所有者以解决此问题。」控制台是 `Framing '…' violates … "frame-src …"`。
+
+```ts
+import { openDownload } from "@xgent/portal-sdk";
+const { url } = await sdk.callService("myapp", `/attachments/${id}/download`);
+openDownload(url);            // ✅ 顶层弹窗不受 frame-src 管，一闪即落盘
+```
+
+三个反直觉点：
+
+- 加 `a.download = name` **救不回来**——该属性对跨源 URL 会被浏览器忽略，照样导航、照样被拦。
+- 宿主 sandbox 的 `allow-downloads` 是**另一半**（已有）：缺它，弹窗会开但文件被静默丢弃。它治不了上面那个导航拦截，两件事别混。
+- 服务端要保证 URL 带 `Content-Disposition: attachment`（files-server 的 `/:id/download` 默认如此），否则新标签页变成预览而不是落盘。
+- 例外：**blob:/同源** URL（前端自己生成的 CSV 等）用 `<a download>.click()` 没问题，属性生效、不产生导航。
+
+## 6. 最小可用例子
+
+```ts
+import { createPortalClient } from "@xgent/portal-sdk";
+async function main() {
+  if (window.parent === window) {
+    document.body.textContent = "请在 XGENT Portal 内打开本应用（需要宿主握手）。";
+    return;
+  }
+  const sdk = createPortalClient();
+  const init = await sdk.ready();
+  const user = await sdk.userinfo().catch(() => null);
+  document.body.innerHTML = `当前用户：${user?.name ?? "—"}`;
+  sdk.onTheme(t => document.documentElement.dataset.theme = t);
+  sdk.resize(document.body.scrollHeight + 8);
+}
+main();
+```