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

package/dist/ui/registry.d.ts

@@ -1,13 +1,13 @@
-import type { ExtensionManifest, UiActionArgs, UiActionResult, UiContribution, UiRenderArgs, UiView } from "@capybara-hq/plugin-sdk";
+import type { ExtensionManifest, UiActionArgs, UiActionResult, UiRenderArgs, UiSlotSpec, UiView } from "@capybara-hq/plugin-sdk";
 import { type OrgRole } from "../orgs/roles.js";
 /** 会话 id 的格式（UUID）。 */
 export declare const UUID_RE: RegExp;
-/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
-export declare const PAGE_MIN_ROLE: OrgRole;
-/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
-export declare const isConversationPlace: (place: UiContribution["place"]) => boolean;
-/** 该角色能否使用这个位置的贡献。 */
-export declare const canUsePlace: (place: UiContribution["place"], role: OrgRole) => boolean;
+/**
+ * Whether an org role may use contributions in this slot (UI slots spec §7): never a `superAdmin`
+ * slot (`platform.page` is served only by the org-less platform routes), else the slot's
+ * `minRole`. The slot's scope rule (conversation, agent, file) is checked after this.
+ */
+export declare function canUseSlot(slot: UiSlotSpec, role: OrgRole): boolean;
 /** 插件视图的 render 函数（`ctx.ui.view` 注册）。 */
 export type UiRender = (args: UiRenderArgs) => Promise<UiView>;
 /** 插件视图的动作处理函数（`ctx.ui.action` 注册）。 */
@@ -17,7 +17,22 @@ export type UiActionHandler = (args: UiActionArgs) => Promise<UiActionResult>;
  * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
  */
 export declare const orgUiTopic: (orgId: string) => string;
-/** 界面刷新消息：`conv.<id>` 与 `org-ui.<orgId>` 上的 `{ kind: "ui", plugin, contribution }`。 */
+/**
+ * The kernel bus topic of the platform refresh (namespace `kernel`): `ctx.ui.invalidate` of a
+ * `platform.page` contribution (no `orgId`), read by `GET /api/v1/admin/ui/stream`.
+ */
+export declare const PLATFORM_UI_TOPIC = "platform-ui";
+/** A checked `ui.invalidate` target: an org's (optionally one conversation's) or the platform's. */
+export type UiInvalidateTarget = {
+    scope: "org";
+    orgId: string;
+    conversationId?: string;
+    contribution: string;
+} | {
+    scope: "platform";
+    contribution: string;
+};
+/** 界面刷新消息：`conv.<id>`、`org-ui.<orgId>` 与 `platform-ui` 上的 `{ kind: "ui", plugin, contribution }`。 */
 export interface UiBusMessage {
     kind: "ui";
     plugin: string;
@@ -48,11 +63,11 @@ export declare class PluginUiRegistration {
     seal(): void;
     view(id: string, render: UiRender): void;
     action(id: string, handler: UiActionHandler): void;
-    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
-    target(t: unknown): {
-        orgId: string;
-        conversationId?: string;
-        contribution: string;
-    };
+    /**
+     * 校验 invalidate 的目标。A contribution in `platform` (the ids of the extension's `platform.page`
+     * contributions) takes no `orgId` and no `conversationId`; every other contribution needs an
+     * `orgId`.
+     */
+    target(t: unknown, platform: ReadonlySet<string>): UiInvalidateTarget;
     private register;
 }

package/dist/ui/registry.js

@@ -1,17 +1,24 @@
 import { roleAtLeast } from "../orgs/roles.js";
 /** 会话 id 的格式（UUID）。 */
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
-export const PAGE_MIN_ROLE = "member";
-/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
-export const isConversationPlace = (place) => place !== "page";
-/** 该角色能否使用这个位置的贡献。 */
-export const canUsePlace = (place, role) => place !== "page" || roleAtLeast(role, PAGE_MIN_ROLE);
+/**
+ * Whether an org role may use contributions in this slot (UI slots spec §7): never a `superAdmin`
+ * slot (`platform.page` is served only by the org-less platform routes), else the slot's
+ * `minRole`. The slot's scope rule (conversation, agent, file) is checked after this.
+ */
+export function canUseSlot(slot, role) {
+    return slot.minRole !== "superAdmin" && roleAtLeast(role, slot.minRole);
+}
 /**
  * 组织级界面刷新的内核 bus 主题（命名空间 `kernel`）：`org-ui.<orgId>`。
  * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
  */
 export const orgUiTopic = (orgId) => `org-ui.${orgId}`;
+/**
+ * The kernel bus topic of the platform refresh (namespace `kernel`): `ctx.ui.invalidate` of a
+ * `platform.page` contribution (no `orgId`), read by `GET /api/v1/admin/ui/stream`.
+ */
+export const PLATFORM_UI_TOPIC = "platform-ui";
 /** 是否为界面刷新消息（bus 上的消息来自其他副本，按形状核对）。 */
 export function isUiBusMessage(m) {
     if (typeof m !== "object" || m === null)
@@ -52,13 +59,15 @@ export class PluginUiRegistration {
     action(id, handler) {
         this.register("action", this.actions, id, handler);
     }
-    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
-    target(t) {
+    /**
+     * 校验 invalidate 的目标。A contribution in `platform` (the ids of the extension's `platform.page`
+     * contributions) takes no `orgId` and no `conversationId`; every other contribution needs an
+     * `orgId`.
+     */
+    target(t, platform) {
         const name = this.manifest.name;
         const x = (typeof t === "object" && t !== null ? t : {});
         const id = (v) => typeof v === "string" && v !== "" && v.length <= 200;
-        if (!id(x.orgId))
-            throw new Error(`plugin ${name}: ui.invalidate needs a non-empty orgId`);
         if (x.conversationId !== undefined &&
             (typeof x.conversationId !== "string" || !UUID_RE.test(x.conversationId))) {
             throw new Error(`plugin ${name}: ui.invalidate conversationId must be a UUID`);
@@ -66,7 +75,19 @@ export class PluginUiRegistration {
         if (typeof x.contribution !== "string" || !this.contributions.has(x.contribution)) {
             throw new Error(`plugin ${name}: ui.invalidate: ${JSON.stringify(x.contribution)} is not a ui contribution in the manifest`);
         }
+        if (platform.has(x.contribution)) {
+            if (x.orgId !== undefined) {
+                throw new Error(`plugin ${name}: ui.invalidate: ${x.contribution} is a platform page; omit orgId`);
+            }
+            if (x.conversationId !== undefined) {
+                throw new Error(`plugin ${name}: ui.invalidate: ${x.contribution} is a platform page; omit conversationId`);
+            }
+            return { scope: "platform", contribution: x.contribution };
+        }
+        if (!id(x.orgId))
+            throw new Error(`plugin ${name}: ui.invalidate needs a non-empty orgId`);
         return {
+            scope: "org",
             orgId: x.orgId,
             ...(x.conversationId !== undefined && { conversationId: x.conversationId }),
             contribution: x.contribution,

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

@@ -0,0 +1,11 @@
+import { type UiSlotSpec } from "@capybara-hq/plugin-sdk";
+/**
+ * The slot catalog (UI slots spec §3): every slot an extension can contribute to, verbatim from
+ * the SDK. Static, so any signed-in person may read it; no org is involved.
+ */
+export declare class SlotsController {
+    /** `GET /api/v1/ui/slots` → `{ slots }`. */
+    slots(): {
+        slots: readonly UiSlotSpec[];
+    };
+}

package/dist/ui/slots.controller.js

@@ -0,0 +1,25 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { UI_SLOTS } from "@capybara-hq/plugin-sdk";
+import { Controller, Get } from "@nestjs/common";
+/**
+ * The slot catalog (UI slots spec §3): every slot an extension can contribute to, verbatim from
+ * the SDK. Static, so any signed-in person may read it; no org is involved.
+ */
+let SlotsController = class SlotsController {
+    /** `GET /api/v1/ui/slots` → `{ slots }`. */
+    slots() {
+        return { slots: UI_SLOTS };
+    }
+};
+__decorate([
+    Get("slots")
+], SlotsController.prototype, "slots", null);
+SlotsController = __decorate([
+    Controller("api/v1/ui")
+], SlotsController);
+export { SlotsController };

package/dist/ui/ui-stream.d.ts

@@ -6,20 +6,37 @@ import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.j
 import { type OrgRole } from "../orgs/roles.js";
 import { type SseOutput, type StreamBus, type StreamHandle } from "../runtime/stream.js";
 export interface OrgUiStreamParams {
+    scope?: "org";
     orgId: string;
     viewerAccountId: string;
     credential: CredentialCheck;
 }
+/** The platform refresh stream (`GET /api/v1/admin/ui/stream`): a super admin's, no org. */
+export interface PlatformUiStreamParams {
+    scope: "platform";
+    viewerAccountId: string;
+    credential: CredentialCheck;
+}
+export type UiStreamParams = OrgUiStreamParams | PlatformUiStreamParams;
 /** The org role the org UI stream re-checks. */
 export declare class UiStreamMembership {
     private readonly db;
     constructor(db: KernelDb);
     /** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
     role(orgId: string, accountId: string): Promise<OrgRole | undefined>;
+    /** Whether the account is an active super admin (one query). */
+    superAdmin(accountId: string): Promise<boolean>;
 }
+/**
+ * The org refresh stream is member and above (UI slots spec §7): it carries `org.page` and
+ * `org.settings.section` refreshes; an `agent.detail.section` a guest views refreshes on navigation.
+ */
+export declare const ORG_STREAM_MIN_ROLE: OrgRole;
 /**
  * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
- * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。The platform variant subscribes
+ * `platform-ui` (`invalidate` of a `platform.page`, no org) for a super admin, re-checked on the
+ * same interval (losing super admin ends it with `event: error`, code `forbidden`).跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
 export declare class OrgUiStreams {
@@ -33,9 +50,9 @@ export declare class OrgUiStreams {
      * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
      * streams end with their connections.
      */
-    constructor(bus: StreamBus, membership: Pick<UiStreamMembership, "role">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
+    constructor(bus: StreamBus, membership: Pick<UiStreamMembership, "role" | "superAdmin">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
     /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
-    open(p: OrgUiStreamParams, out: SseOutput): Promise<StreamHandle>;
+    open(p: UiStreamParams, out: SseOutput): Promise<StreamHandle>;
     /** Closes every stream of this process (at shutdown) and latches, like `ConversationStreams`. */
     closeAll(): void;
     get size(): number;

package/dist/ui/ui-stream.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable, Optional } from "@nestjs/common";
+import { currentPlatformAccount } from "../ctx/create-ctx.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -15,7 +16,9 @@ import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.j
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { endedStream, } from "../runtime/stream.js";
-import { isUiBusMessage, orgUiTopic, PAGE_MIN_ROLE, uiFrame } from "./registry.js";
+import { isUiBusMessage, orgUiTopic, PLATFORM_UI_TOPIC, uiFrame } from "./registry.js";
+/** The log field naming the stream: its org, or the platform scope. */
+const whereOf = (p) => p.scope === "platform" ? { scope: "platform" } : { orgId: p.orgId };
 /** The org role the org UI stream re-checks. */
 let UiStreamMembership = class UiStreamMembership {
     db;
@@ -36,26 +39,39 @@ let UiStreamMembership = class UiStreamMembership {
             .executeTakeFirst();
         return row?.role;
     }
+    /** Whether the account is an active super admin (one query). */
+    superAdmin(accountId) {
+        return currentPlatformAccount(this.db.db, accountId);
+    }
 };
 UiStreamMembership = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb))
 ], UiStreamMembership);
 export { UiStreamMembership };
+/**
+ * The org refresh stream is member and above (UI slots spec §7): it carries `org.page` and
+ * `org.settings.section` refreshes; an `agent.detail.section` a guest views refreshes on navigation.
+ */
+export const ORG_STREAM_MIN_ROLE = "member";
 async function authorize(d, p) {
     const denied = await p.credential();
     if (denied !== null)
         return denied;
+    if (p.scope === "platform")
+        return (await d.superAdmin(p.viewerAccountId)) ? null : "forbidden";
     const role = await d.memberRole(p.orgId, p.viewerAccountId);
     if (role === undefined)
         return "org.not_found";
-    return roleAtLeast(role, PAGE_MIN_ROLE) ? null : "ui.not_found";
+    return roleAtLeast(role, ORG_STREAM_MIN_ROLE) ? null : "ui.not_found";
 }
 /** 慢客户端的积压上限（刷新帧很小，超过即说明客户端不读了）。 */
 const MAX_BACKLOG_BYTES = 1024 * 1024;
 /**
  * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
- * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。The platform variant subscribes
+ * `platform-ui` (`invalidate` of a `platform.page`, no org) for a super admin, re-checked on the
+ * same interval (losing super admin ends it with `event: error`, code `forbidden`).跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
 let OrgUiStreams = class OrgUiStreams {
@@ -73,6 +89,7 @@ let OrgUiStreams = class OrgUiStreams {
         this.d = {
             bus,
             memberRole: (orgId, accountId) => membership.role(orgId, accountId),
+            superAdmin: (accountId) => membership.superAdmin(accountId),
             config,
             log,
         };
@@ -140,7 +157,8 @@ class OrgUiConnection {
         this.onClosed = onClosed;
     }
     async subscribe() {
-        const un = await this.d.bus.subscribe(orgUiTopic(this.p.orgId), (m) => {
+        const topic = this.p.scope === "platform" ? PLATFORM_UI_TOPIC : orgUiTopic(this.p.orgId);
+        const un = await this.d.bus.subscribe(topic, (m) => {
             // begin() 之前（响应头还没写）到达的刷新丢掉：网页连上后会先取一次视图
             if (this.begun && isUiBusMessage(m))
                 this.write(uiFrame(m));
@@ -166,7 +184,7 @@ class OrgUiConnection {
         this.timers = [];
         const un = this.unsubscribe;
         this.unsubscribe = undefined;
-        un?.().catch((err) => this.d.log.warn("org ui stream unsubscribe failed", { orgId: this.p.orgId, err }));
+        un?.().catch((err) => this.d.log.warn("org ui stream unsubscribe failed", { ...whereOf(this.p), err }));
         if (this.begun) {
             try {
                 if (mode === "abort")
@@ -191,7 +209,7 @@ class OrgUiConnection {
             return;
         }
         if (this.out.backlog() > MAX_BACKLOG_BYTES) {
-            this.d.log.warn("org ui stream client too slow; closing", { orgId: this.p.orgId });
+            this.d.log.warn("org ui stream client too slow; closing", whereOf(this.p));
             this.close("abort");
         }
     }
@@ -206,7 +224,7 @@ class OrgUiConnection {
         }
         catch (err) {
             this.d.log.warn("org ui stream access re-check failed; closing", {
-                orgId: this.p.orgId,
+                ...whereOf(this.p),
                 err,
             });
             code = "internal";

package/dist/ui/ui.schemas.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** The contribution named in a view / action / embed path (`:plugin/:id`). */
+export declare const ContributionParams: z.ZodObject<{
+    plugin: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `GET contributions?slot=`: one catalog slot, or every org-reachable slot when omitted. */
+export declare const ContributionsQuery: z.ZodObject<{
+    slot: z.ZodOptional<z.ZodEnum<{
+        "agent.detail.section": "agent.detail.section";
+        "conversation.panel": "conversation.panel";
+        "conversation.properties.section": "conversation.properties.section";
+        "conversation.tool-result.card": "conversation.tool-result.card";
+        "file.preview": "file.preview";
+        "org.page": "org.page";
+        "org.settings.section": "org.settings.section";
+        "platform.page": "platform.page";
+    }>>;
+}, z.core.$strip>;
+export declare const ViewQuery: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    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>;
+export 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>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+export declare const EmbedTokenBody: z.ZodDefault<z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    fileId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strip>>;
+/** `GET /api/v1/admin/ui/views/:plugin/:id?locale=`: a platform page takes no context id. */
+export declare const PlatformViewQuery: z.ZodObject<{
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+/** `POST /api/v1/admin/ui/actions/:plugin/:id`: an action of a platform page (no context id). */
+export declare const PlatformActionBody: 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>]>>>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+/** The slot catalog route the Platform operation `ui.slots` mirrors (`check:platform-ops` key). */
+export declare const UI_ROUTES: readonly RouteSchemas[];

package/dist/ui/ui.schemas.js

@@ -0,0 +1,65 @@
+import { UI_LIMITS, UI_SLOT_IDS } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas of the org UI routes (`views.controller.ts`). */
+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`). */
+export const ContributionParams = z.object({ plugin: Id, id: Id });
+/** `GET contributions?slot=`: one catalog slot, or every org-reachable slot when omitted. */
+export const ContributionsQuery = z.object({ slot: z.enum(UI_SLOT_IDS).optional() });
+export const ViewQuery = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only an agent view (`agent.detail.section`). */
+    agentId: z.uuid().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");
+export 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(),
+    /** Only an agent view (`agent.detail.section`). */
+    agentId: z.uuid().optional(),
+    locale: Locale,
+});
+export const EmbedTokenBody = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only an agent embed (`agent.detail.section`). */
+    agentId: z.uuid().optional(),
+    /** Only a `file.preview` embed: the file version it previews. */
+    fileId: z.uuid().optional(),
+})
+    .default({});
+/** `GET /api/v1/admin/ui/views/:plugin/:id?locale=`: a platform page takes no context id. */
+export const PlatformViewQuery = z.object({ locale: Locale });
+/** `POST /api/v1/admin/ui/actions/:plugin/:id`: an action of a platform page (no context id). */
+export const PlatformActionBody = ActionBody.omit({ conversationId: true, agentId: true });
+/** The slot catalog route the Platform operation `ui.slots` mirrors (`check:platform-ops` key). */
+export const UI_ROUTES = [{ route: "GET /api/v1/ui/slots" }];

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 {};