@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/ui/views.controller.d.ts

@@ -1,61 +1,45 @@
-import { type UiActionResult, type UiView } from "@capybara-hq/plugin-sdk";
+import type { UiActionResult, UiView } from "@capybara-hq/plugin-sdk";
 import type { FastifyReply, FastifyRequest } from "fastify";
-import { z } from "zod";
+import type { z } from "zod";
 import { ApiTokenService } from "../identity/api-tokens.js";
 import { type Principal } from "../identity/principal.js";
 import { SessionService } from "../identity/sessions.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { EmbedTokens } from "./embed-token.js";
+import { ActionBody, ContributionParams, ContributionsQuery, EmbedTokenBody, ViewQuery } from "./ui.schemas.js";
 import { OrgUiStreams } from "./ui-stream.js";
-import { type UiContributionItem, UiViews } from "./views.js";
-/** The contribution named in a view / action / embed path (`:plugin/:id`). */
-declare const ContributionParams: z.ZodObject<{
-    plugin: z.ZodString;
-    id: z.ZodString;
-}, z.core.$strip>;
-declare const ViewQuery: z.ZodObject<{
-    conversationId: z.ZodOptional<z.ZodString>;
-    locale: z.ZodDefault<z.ZodEnum<{
-        en: "en";
-        zh: "zh";
-    }>>;
-    item: z.ZodOptional<z.ZodString>;
-    callId: z.ZodOptional<z.ZodString>;
-    key: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-declare const ActionBody: z.ZodObject<{
-    actionId: z.ZodString;
-    payload: z.ZodOptional<z.ZodUnknown>;
-    answer: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    conversationId: z.ZodOptional<z.ZodString>;
-    locale: z.ZodDefault<z.ZodEnum<{
-        en: "en";
-        zh: "zh";
-    }>>;
-}, z.core.$strip>;
-declare const EmbedTokenBody: z.ZodDefault<z.ZodObject<{
-    conversationId: z.ZodOptional<z.ZodString>;
-    fileId: z.ZodOptional<z.ZodUUID>;
-}, z.core.$strip>>;
+import { type UiArrangementSlot, type UiContributionItem, UiViews } from "./views.js";
+export declare const BEARER_RE: RegExp;
+/** 嵌入页的同源代理前缀（网页 `/plugin-ui/<plugin>/<rest>` → 内核 `/plugins/<plugin>/ui/<rest>`）。 */
+export declare const embedSrc: (plugin: string, path: string) => string;
 /**
  * 插件界面（第一档：渲染 schema；第二档：嵌入应用），会话鉴权、`ui.use`（只给人用，服务令牌 403）：
- * - `GET  /api/v1/orgs/:orgId/ui/contributions` → `{ items: { plugin, id, title, place, legacyPlace?, kind, path?, icon }[] }`
- *   (place normalized: the old `conversation` is `panel` with `legacyPlace`; aliases and file-preview
- *   embeds are not listed)
- *   （`path` 仅 embed）；
- * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&locale=&item=&callId=&key=` → `{ view }`
- *   （`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
- * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`（`{ actionId, payload?, answer?, conversationId?, locale? }`）
- *   → `{ toast }` | `{ view }`；
- * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`）；
- * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId? }`）
+ * - `GET  /api/v1/orgs/:orgId/ui/contributions?slot=` →
+ *   `{ items: { plugin, id, title, slot, after?, kind, path?, icon }[] }`: every org-reachable slot
+ *   (all but `platform.page`) or one slot; `after` is the resolved anchor of a slot with anchors,
+ *   `path` only for an embed; aliases and `file.preview` contributions are not listed; ordered by
+ *   extension name, then manifest order;
+ * - `GET  /api/v1/orgs/:orgId/ui/arrangement` → `{ slots: { slot, source, items }[] }`: every
+ *   org-arrangeable slot with the contributions the caller's role may use, in effective order, each
+ *   marked `hidden` (the listing for the 界面位置 page; the lists above omit hidden ones, the
+ *   view / action / embed routes below ignore the arrangement);
+ * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&agentId=&locale=&item=&callId=&key=`
+ *   → `{ view }`（`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
+ * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`
+ *   （`{ actionId, payload?, answer?, conversationId?, agentId?, locale? }`）→ `{ toast }` | `{ view }`；
+ * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`），
+ *   member and above；
+ * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId?, agentId?, fileId? }`）
  *   → `{ token, src: "/plugin-ui/<plugin>/<path 去掉 /ui/>", expiresAt, expiresIn }`：嵌入令牌
- *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`）。
- *   插件须在组织启用、贡献须是 embed；对话嵌入要求能访问该对话（否则 404）。令牌只给插件路由用，
- *   内核鉴权守卫不认它（它不是 API 令牌）。
+ *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`；`agentId` goes into the claims）。
+ *   令牌只给插件路由用，内核鉴权守卫不认它（它不是 API 令牌）。
  * 对话视图的刷新走现有的会话流 `/conversations/:id/stream`。
- * 角色（A38）：组织页面（`place: "page"`，含组织级刷新流）只给 member 以上，guest 一律 404 `ui.not_found`、
- * 列表里也不出现；对话位置的贡献给能访问该对话的任何成员。插件收到的 `role` 来自 OrgGuard 查出的成员关系。
+ * Access (UI slots spec §7): every route checks the slot of the contribution it names, its
+ * `minRole` (guest for conversation and agent slots, member for `org.page`, admin for
+ * `org.settings.section`; `platform.page` never through these routes), then its scope rule
+ * (conversation: whoever can read it; agent: whoever can read the agent, in this org; org: the
+ * role alone; file: the previewer's read grant). Anything refused is 404 `ui.not_found`, the same
+ * as a contribution that does not exist. 插件收到的 `role` 来自 OrgGuard 查出的成员关系。
  */
 export declare class UiController {
     private readonly views;
@@ -64,9 +48,12 @@ export declare class UiController {
     private readonly tokens;
     private readonly embeds;
     constructor(views: UiViews, streams: OrgUiStreams, sessions: SessionService, tokens: ApiTokenService, embeds: EmbedTokens);
-    contributions(principal: Principal, org: OrgContext): Promise<{
+    contributions(principal: Principal, org: OrgContext, q: z.infer<typeof ContributionsQuery>): Promise<{
         items: UiContributionItem[];
     }>;
+    arrangement(principal: Principal, org: OrgContext): Promise<{
+        slots: UiArrangementSlot[];
+    }>;
     view(principal: Principal, org: OrgContext, { plugin, id }: z.infer<typeof ContributionParams>, q: z.infer<typeof ViewQuery>): Promise<{
         view: UiView;
     }>;
@@ -80,4 +67,3 @@ export declare class UiController {
     /** 组织级刷新流：与会话流一样用 `reply.hijack()` 直接写原始响应；心跳与复核间隔同 `runtime.sse*`。 */
     stream(principal: Principal, org: OrgContext, req: FastifyRequest, reply: FastifyReply): Promise<void>;
 }
-export {};

package/dist/ui/views.controller.js

@@ -7,9 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { UI_LIMITS } from "@capybara-hq/plugin-sdk";
 import { Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
-import { z } from "zod";
 import { ApiTokenService } from "../identity/api-tokens.js";
 import { credentialCheck } from "../identity/credential-check.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
@@ -18,59 +16,14 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { EMBED_TOKEN_TTL_SECONDS, EmbedTokens } from "./embed-token.js";
+import { ActionBody, ContributionParams, ContributionsQuery, EmbedTokenBody, ViewQuery, } from "./ui.schemas.js";
 import { OrgUiStreams } from "./ui-stream.js";
 import { UiViews } from "./views.js";
-const BEARER_RE = /^Bearer\s+(\S+)$/i;
-const Locale = z.enum(["zh", "en"]).default("en");
-const Id = z.string().min(1).max(100);
-/** The contribution named in a view / action / embed path (`:plugin/:id`). */
-const ContributionParams = z.object({ plugin: Id, id: Id });
-const ViewQuery = z
-    .object({
-    conversationId: z.string().min(1).max(100).optional(),
-    locale: Locale,
-    /** A panel opened from an open target: the item to scroll to. */
-    item: z.string().min(1).max(200).optional(),
-    /** An inline card: the tool call it hangs off, and its `ToolResult.card.key`. */
-    callId: z.string().min(1).max(200).optional(),
-    key: z.string().min(1).max(200).optional(),
-})
-    .refine((q) => q.key === undefined || q.callId !== undefined, {
-    message: "key needs callId",
-});
-/**
- * 表单答案（plugin-sdk 的 `FormAnswer`）。SDK 的 InputForm 没有单独的字段数 / 选项数上限，
- * 这里沿用视图的上限：键数与多选数组长度 ≤ `UI_LIMITS.tableRows`，单个文本 ≤ `UI_LIMITS.textChars`。
- */
-const AnswerText = z.string().max(UI_LIMITS.textChars);
-const FormAnswerSchema = z
-    .record(z.string().max(100), z.union([AnswerText, z.number(), z.boolean(), z.array(AnswerText).max(UI_LIMITS.tableRows)]))
-    .refine((a) => Object.keys(a).length <= UI_LIMITS.tableRows, {
-    message: `answer must have at most ${UI_LIMITS.tableRows} fields`,
-});
-/** 按钮 payload 的 JSON 序列化后 UTF-8 字节数（与 `validateUiView` 对按钮 payload 的上限一致）。 */
-const payloadBytes = (v) => Buffer.byteLength(JSON.stringify(v) ?? "", "utf8");
-const ActionBody = z.object({
-    actionId: z.string().min(1).max(200),
-    payload: z
-        .unknown()
-        .optional()
-        .refine((v) => v === undefined || payloadBytes(v) <= UI_LIMITS.payloadBytes, {
-        message: `payload must be at most ${UI_LIMITS.payloadBytes} bytes as JSON`,
-    }),
-    answer: FormAnswerSchema.optional(),
-    conversationId: z.string().min(1).max(100).optional(),
-    locale: Locale,
-});
-const EmbedTokenBody = z
-    .object({
-    conversationId: z.string().min(1).max(100).optional(),
-    /** Only a `file-preview` embed: the file version it previews. */
-    fileId: z.uuid().optional(),
-})
-    .default({});
+export const BEARER_RE = /^Bearer\s+(\S+)$/i;
 /** 嵌入页的同源代理前缀（网页 `/plugin-ui/<plugin>/<rest>` → 内核 `/plugins/<plugin>/ui/<rest>`）。 */
-const embedSrc = (plugin, path) => `/plugin-ui/${plugin}/${path.replace(/^\/ui\//, "")}`;
+export const embedSrc = (plugin, path) => `/plugin-ui/${plugin}/${path.replace(/^\/ui\//, "")}`;
+class UiContributionsQueryDto extends createZodDto(ContributionsQuery, "UiContributionsQuery") {
+}
 class UiContributionParamsDto extends createZodDto(ContributionParams, "UiContributionParams") {
 }
 class UiViewQueryDto extends createZodDto(ViewQuery, "UiViewQuery") {
@@ -81,23 +34,32 @@ class UiEmbedTokenBodyDto extends createZodDto(EmbedTokenBody, "UiEmbedTokenBody
 }
 /**
  * 插件界面（第一档：渲染 schema；第二档：嵌入应用），会话鉴权、`ui.use`（只给人用，服务令牌 403）：
- * - `GET  /api/v1/orgs/:orgId/ui/contributions` → `{ items: { plugin, id, title, place, legacyPlace?, kind, path?, icon }[] }`
- *   (place normalized: the old `conversation` is `panel` with `legacyPlace`; aliases and file-preview
- *   embeds are not listed)
- *   （`path` 仅 embed）；
- * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&locale=&item=&callId=&key=` → `{ view }`
- *   （`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
- * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`（`{ actionId, payload?, answer?, conversationId?, locale? }`）
- *   → `{ toast }` | `{ view }`；
- * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`）；
- * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId? }`）
+ * - `GET  /api/v1/orgs/:orgId/ui/contributions?slot=` →
+ *   `{ items: { plugin, id, title, slot, after?, kind, path?, icon }[] }`: every org-reachable slot
+ *   (all but `platform.page`) or one slot; `after` is the resolved anchor of a slot with anchors,
+ *   `path` only for an embed; aliases and `file.preview` contributions are not listed; ordered by
+ *   extension name, then manifest order;
+ * - `GET  /api/v1/orgs/:orgId/ui/arrangement` → `{ slots: { slot, source, items }[] }`: every
+ *   org-arrangeable slot with the contributions the caller's role may use, in effective order, each
+ *   marked `hidden` (the listing for the 界面位置 page; the lists above omit hidden ones, the
+ *   view / action / embed routes below ignore the arrangement);
+ * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&agentId=&locale=&item=&callId=&key=`
+ *   → `{ view }`（`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
+ * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`
+ *   （`{ actionId, payload?, answer?, conversationId?, agentId?, locale? }`）→ `{ toast }` | `{ view }`；
+ * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`），
+ *   member and above；
+ * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId?, agentId?, fileId? }`）
  *   → `{ token, src: "/plugin-ui/<plugin>/<path 去掉 /ui/>", expiresAt, expiresIn }`：嵌入令牌
- *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`）。
- *   插件须在组织启用、贡献须是 embed；对话嵌入要求能访问该对话（否则 404）。令牌只给插件路由用，
- *   内核鉴权守卫不认它（它不是 API 令牌）。
+ *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`；`agentId` goes into the claims）。
+ *   令牌只给插件路由用，内核鉴权守卫不认它（它不是 API 令牌）。
  * 对话视图的刷新走现有的会话流 `/conversations/:id/stream`。
- * 角色（A38）：组织页面（`place: "page"`，含组织级刷新流）只给 member 以上，guest 一律 404 `ui.not_found`、
- * 列表里也不出现；对话位置的贡献给能访问该对话的任何成员。插件收到的 `role` 来自 OrgGuard 查出的成员关系。
+ * Access (UI slots spec §7): every route checks the slot of the contribution it names, its
+ * `minRole` (guest for conversation and agent slots, member for `org.page`, admin for
+ * `org.settings.section`; `platform.page` never through these routes), then its scope rule
+ * (conversation: whoever can read it; agent: whoever can read the agent, in this org; org: the
+ * role alone; file: the previewer's read grant). Anything refused is 404 `ui.not_found`, the same
+ * as a contribution that does not exist. 插件收到的 `role` 来自 OrgGuard 查出的成员关系。
  */
 let UiController = class UiController {
     views;
@@ -112,9 +74,13 @@ let UiController = class UiController {
         this.tokens = tokens;
         this.embeds = embeds;
     }
-    async contributions(principal, org) {
+    async contributions(principal, org, q) {
         requireUser(principal);
-        return { items: await this.views.contributions(org.orgId, org.role) };
+        return { items: await this.views.contributions(org.orgId, org.role, q.slot) };
+    }
+    async arrangement(principal, org) {
+        requireUser(principal);
+        return { slots: await this.views.arrangementView(org.orgId, org.role) };
     }
     async view(principal, org, { plugin, id }, q) {
         const p = requireUser(principal);
@@ -125,6 +91,7 @@ let UiController = class UiController {
             plugin,
             id,
             ...(q.conversationId !== undefined && { conversationId: q.conversationId }),
+            ...(q.agentId !== undefined && { agentId: q.agentId }),
             locale: q.locale,
             ...(q.item !== undefined && { item: q.item }),
             ...(q.callId !== undefined && {
@@ -142,6 +109,7 @@ let UiController = class UiController {
             plugin,
             id,
             ...(body.conversationId !== undefined && { conversationId: body.conversationId }),
+            ...(body.agentId !== undefined && { agentId: body.agentId }),
             locale: body.locale,
         }, {
             actionId: body.actionId,
@@ -158,14 +126,17 @@ let UiController = class UiController {
             plugin,
             id,
             ...(body.conversationId !== undefined && { conversationId: body.conversationId }),
+            ...(body.agentId !== undefined && { agentId: body.agentId }),
             ...(body.fileId !== undefined && { fileId: body.fileId }),
         });
         const { token, expiresAt } = this.embeds.issue({
             plugin: target.plugin,
+            scope: "org",
             orgId: org.orgId,
             accountId: p.account.id,
             role: org.role,
             ...(target.conversationId !== undefined && { conversationId: target.conversationId }),
+            ...(target.agentId !== undefined && { agentId: target.agentId }),
             ...(target.fileId !== undefined && { fileId: target.fileId }),
             contribution: target.contribution,
         });
@@ -221,8 +192,15 @@ __decorate([
     Get("contributions"),
     OrgAction("ui.use"),
     __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg())
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(UiContributionsQueryDto))
 ], UiController.prototype, "contributions", null);
+__decorate([
+    Get("arrangement"),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], UiController.prototype, "arrangement", null);
 __decorate([
     Get("views/:plugin/:id"),
     OrgAction("ui.use"),

package/dist/ui/views.d.ts

@@ -1,4 +1,4 @@
-import { type FormAnswer, type Logger, type UiActionResult, type UiContribution, type UiIcon, type UiView } from "@capybara-hq/plugin-sdk";
+import { type FormAnswer, type Logger, type UiActionResult, type UiContribution, type UiIcon, type UiSlotId, type UiView } from "@capybara-hq/plugin-sdk";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { EffectiveConfigs } from "../extensions/effective-config.js";
@@ -14,16 +14,24 @@ export interface UiContributionItem {
     plugin: string;
     id: string;
     title: UiContribution["title"];
-    /** Normalized: the old `conversation` is listed as `panel`. */
-    place: Exclude<UiContribution["place"], "conversation" | "file-preview">;
-    /** `"conversation"` when the manifest still says the old place. */
-    legacyPlace?: "conversation";
+    /** The catalog slot the contribution resolved to. */
+    slot: UiSlotId;
+    /** For a slot with anchors: the anchor it goes after (resolved: the slot's first by default). */
+    after?: string;
     kind: UiContribution["kind"];
     /** 仅 embed：插件路由下 `/ui/` 开头的路径（网页经 `/plugin-ui/<plugin>/...` 代理访问）。 */
     path?: string;
     /** From `UI_ICONS`; `puzzle` when the manifest names none. */
     icon: UiIcon;
 }
+/** One slot of an arrangement listing: where its entry comes from and its items in order. */
+export interface UiArrangementSlot {
+    slot: UiSlotId;
+    source: "org" | "platform" | "none";
+    items: (UiContributionItem & {
+        hidden: boolean;
+    })[];
+}
 /** 嵌入应用的签发目标：已核对组织启用与对话访问。 */
 export interface UiEmbedTarget {
     plugin: string;
@@ -31,11 +39,14 @@ export interface UiEmbedTarget {
     /** 清单里的 `path`（`/ui/` 开头）。 */
     path: string;
     conversationId?: string;
-    /** Only a `file-preview` embed: the one file the token is for. */
+    /** Only an agent embed: the agent the token is for. */
+    agentId?: string;
+    /** Only a `file.preview` embed: the one file the token is for. */
     fileId?: string;
 }
-/** 取视图 / 执行动作的调用者与目标（身份来自内核鉴权）。 */
-export interface UiTarget {
+/** 取视图 / 执行动作的调用者与目标（身份来自内核鉴权）: an org route's. */
+export interface UiOrgTarget {
+    scope?: "org";
     orgId: string;
     accountId: string;
     /** 调用者在 `orgId` 的角色（OrgGuard 查出的成员关系）。 */
@@ -43,6 +54,8 @@ export interface UiTarget {
     plugin: string;
     id: string;
     conversationId?: string;
+    /** Only an agent view or embed (`agent.detail.section`). */
+    agentId?: string;
     locale: "zh" | "en";
     /** A panel opened from an open target: the item to scroll to. */
     item?: string;
@@ -52,6 +65,20 @@ export interface UiTarget {
         key?: string;
     };
 }
+/** A super admin's request on the org-less admin UI routes (`platform.page` only). */
+export interface UiPlatformTarget {
+    scope: "platform";
+    accountId: string;
+    plugin: string;
+    id: string;
+    locale: "zh" | "en";
+}
+/** The caller and target of a view, action or embed: an org route's or the platform's. */
+export type UiTarget = UiOrgTarget | UiPlatformTarget;
+/** {@link UiTarget} without `locale`, per variant (what `embed` takes). */
+export type UiEmbedRequest = (Omit<UiOrgTarget, "locale"> & {
+    fileId?: string;
+}) | Omit<UiPlatformTarget, "locale">;
 /**
  * The card a `tool_result` of the conversation recorded for `callId`, or null (the inline-card
  * attestation of {@link UiViewsDeps.recordedCard}). Scans one conversation's tool results.
@@ -69,9 +96,11 @@ export declare function dropForeignOpens(view: UiView, panels: ReadonlySet<strin
 /**
  * 插件视图（第一档：渲染 schema）：列出贡献、调用插件 `render` / `action`。
  * - 只认在该组织已启用、且已在本副本加载的插件（启用状态每次查库）；
- * - 对话视图要求调用者能访问这个对话（与 SSE 流一致），访问不了与不存在一样返回 404 `ui.not_found`；
- * - 组织页面（`place: "page"`，视图与嵌入）只给 member 以上：guest 列表里看不到、取视图 / 动作 / 令牌一律 404；
- * - 组织页面视图不接受 `conversationId`（带了 400，与对话视图缺它一致）；
+ * - every request goes through one gate (`resolve`): the slot's `minRole` (never `platform.page`),
+ *   then its scope rule (conversation: readable, like the SSE stream; agent: readable and in this
+ *   org; org: the role alone); refused is 404 `ui.not_found`, the same as not existing;
+ * - a view takes only the context id of its scope (`conversationId` / `agentId`): a missing one or
+ *   one of another scope is 400 `validation_failed`;
  * - 调用带 5 秒时限与中止信号：render 抛错 502 `ui.render_failed`、action 抛错 502 `ui.action_failed`、
  *   超时 504 `ui.timeout`、返回非法视图 502
  *   `ui.invalid_view`，都记告警日志、不写对话日志（这些不是模型可见的内容）。
@@ -79,16 +108,37 @@ export declare function dropForeignOpens(view: UiView, panels: ReadonlySet<strin
  */
 export declare class UiViews {
     private readonly d;
-    constructor(host: ExtensionHost, conversations: ConversationsService, previewers: PreviewerRegistry, db: KernelDb, log: Pick<Logger, "warn">, effective: Pick<EffectiveConfigs, "get">);
-    /** 该组织、该角色可见的界面贡献：插件已启用且已加载；kind view 的要求插件注册了 render；组织页面要 member 以上。 */
-    contributions(orgId: string, role: OrgRole): Promise<UiContributionItem[]>;
+    constructor(host: ExtensionHost, conversations: ConversationsService, previewers: PreviewerRegistry, db: KernelDb, log: Pick<Logger, "warn">, effective: Pick<EffectiveConfigs, "get" | "platform">);
+    /**
+     * The contributions the role may use in the org, of one slot or of every org-reachable slot:
+     * the extension enabled and loaded, a view's render registered, the slot's `minRole`
+     * ({@link canUseSlot}, so never `platform.page`); no alias, no `file.preview` contribution (the
+     * file previewers list those). Base order (spec §5): extension name, then manifest order.
+     */
+    contributions(orgId: string, role: OrgRole, slot?: UiSlotId): Promise<UiContributionItem[]>;
+    /** {@link contributions} before the arrangement: what the role may use, in base order. */
+    private orgBase;
+    /**
+     * The arrangement page of an org: every org-arrangeable slot with the contributions the role may
+     * use, in effective order with the hidden ones in place, and where the entry comes from.
+     */
+    arrangementView(orgId: string, role: OrgRole): Promise<UiArrangementSlot[]>;
+    /**
+     * The platform's arrangement page: every arrangeable slot with the contributions of every running
+     * extension (whatever its org enablement), ordered by the platform entry, hidden ones in place.
+     */
+    platformArrangementView(): Promise<UiArrangementSlot[]>;
+    /**
+     * The `platform.page` contributions of the running extensions, for the admin console (super
+     * admins; no org enablement applies): no alias, a view's render registered. Base order like
+     * {@link contributions}.
+     */
+    platformContributions(): Promise<UiContributionItem[]>;
     /**
      * 嵌入应用：核对贡献是 embed、插件在该组织启用；对话嵌入要求调用者能访问该对话（否则 404，与视图一致），
      * 组织页面不收 `conversationId`。返回签发令牌所需的目标（令牌由调用方签）。
      */
-    embed(t: Omit<UiTarget, "locale"> & {
-        fileId?: string;
-    }): Promise<UiEmbedTarget>;
+    embed(t: UiEmbedRequest): Promise<UiEmbedTarget>;
     /** 取视图：调用插件 `render`，校验返回的视图。 */
     render(t: UiTarget): Promise<UiView>;
     /** 执行动作：调用插件 `action`（视图里的按钮 / 表单提交），校验返回的提示或新视图。 */
@@ -99,8 +149,24 @@ export declare class UiViews {
     }): Promise<UiActionResult>;
     /** Ids of the extension's live `panel` contributions (aliases of panels included). */
     private panels;
-    /** 找贡献、核对组织启用与对话访问；返回传给插件的参数（不含 signal）。 */
+    /**
+     * The single access gate of the org UI routes (UI slots spec §7): finds the contribution (a
+     * retired alias answers with the one it names), then checks, in order, that its slot is reachable
+     * from an org (not `platform`), the role meets the slot's `minRole`, the extension is enabled in
+     * the org, its effective config is valid, and the slot's scope rule (conversation: readable;
+     * agent: readable and in this org; org: the role alone; file: a conversation the caller reads,
+     * the previewer's grant is checked by `embed`). A platform target (the admin routes) takes the
+     * platform gate instead ({@link platformArgs}): only a `platform.page` contribution. Returns the
+     * args passed to the extension (no signal). Anything refused for a contribution that exists is
+     * 404 `ui.not_found`.
+     */
     private resolve;
+    /**
+     * The platform gate (UI slots spec §7): the contribution is a `platform.page` of a running
+     * extension (no org enablement applies), given the platform's deployment config. The caller is a
+     * super admin (`@SuperAdmin` on the admin routes); anything else is 404 `ui.not_found`.
+     */
+    private platformArgs;
     /** 带时限调用插件：超时中止信号并 504；抛错 502（render / action 各一个码，不回显插件的异常信息）。 */
     private call;
     /** 非法结果：记告警（列出前几条问题）并 502 `ui.invalid_view`。 */