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

package/dist/identity/settings.js

@@ -7,6 +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 { EXTENSION_NAME_RE } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
@@ -74,6 +75,47 @@ export const UI_THEME_SETTING = "uiTheme";
  * {@link SettingsService.get}, both parsing with this schema.
  */
 export const UiThemeSetting = z.object({ id: z.string().min(1).max(200).nullable() });
+/** The deployment setting key of the client code kill switch (client extensions spec §10.2). */
+export const CLIENT_EXTENSIONS_SETTING = "clientExtensions";
+/** The plugins listed in `clientExtensions.disabled`: at most this many. */
+export const CLIENT_DISABLED_MAX = 200;
+const ClientDisabledList = z
+    .array(z.string().regex(EXTENSION_NAME_RE, "must be an extension name"))
+    .max(CLIENT_DISABLED_MAX);
+/**
+ * The client code kill switch (client extensions spec §10.2): `enabled: false` stops every plugin's
+ * client code (the shell reads list nothing, delivery is 404); `disabled` names the plugins whose
+ * client code alone is stopped while their server side keeps running. Every reader goes through
+ * {@link readClientExtensions} or {@link SettingsService.get}.
+ */
+export const ClientExtensionsSetting = z.object({
+    enabled: z.boolean(),
+    disabled: ClientDisabledList,
+});
+/** The kill switch's default (and what a missing or invalid stored value reads as): everything on. */
+export const clientExtensionsDefault = () => ({
+    enabled: true,
+    disabled: [],
+});
+/**
+ * Parses a stored `clientExtensions` value (the `deployment_settings` row's `value`, undefined when
+ * the row is missing): the default when missing; when invalid the default too, with a warning naming
+ * the key (a kill switch that fails open is worth a log line, as {@link SettingsService.get} logs
+ * every other invalid key). The one parser of the setting: the settings service and every access
+ * check read through it.
+ */
+export function parseClientExtensions(value, log) {
+    if (value === undefined)
+        return clientExtensionsDefault();
+    const parsed = ClientExtensionsSetting.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    log?.warn("invalid deployment setting; using default", {
+        key: CLIENT_EXTENSIONS_SETTING,
+        issues: parsed.error.issues.map((i) => i.message),
+    });
+    return clientExtensionsDefault();
+}
 export const DEPLOYMENT_SETTINGS = z.object({
     orgCreation: z.enum(["anyone", "super_admin"]).default("anyone"),
     /** 按组织覆盖运行并发上限（orgId → 上限）；未列出的组织用 `runtime.orgConcurrency`。 */
@@ -101,8 +143,13 @@ export const DEPLOYMENT_SETTINGS = z.object({
     orgMarketplaceBrowse: z.boolean().default(true),
     /** The platform default theme (themes spec §7); `{ id: null }`: the built-in theme. */
     uiTheme: UiThemeSetting.default({ id: null }),
-    /** The platform default arrangement of UI slots (UI slots spec §5); orgs override per slot. */
+    /**
+     * The platform default arrangement of UI slots (UI slots spec §5): `{ hidden, order }` per list
+     * slot, `{ use }` per single slot (client extensions spec §6.3); orgs override per slot.
+     */
     uiArrangement: UiArrangementSchema.default({}),
+    /** The client code kill switch (client extensions spec §10.2). */
+    clientExtensions: ClientExtensionsSetting.default(clientExtensionsDefault),
 });
 const DEFAULTS = DEPLOYMENT_SETTINGS.parse({});
 /**
@@ -134,8 +181,22 @@ export const DEPLOYMENT_SETTINGS_PATCH = z
      * disabled (else 400 `theme.not_available`), or `{ id: null }` for the built-in theme.
      */
     uiTheme: UiThemeSetting.strict().optional(),
-    /** Per slot, the entry to hide / order contributions with; null removes a slot's entry. */
+    /**
+     * Per slot, the entry to hide / order contributions with (`{ use }` on a single slot); null
+     * removes a slot's entry.
+     */
     uiArrangement: UiArrangementPatchSchema.optional(),
+    /**
+     * The client code kill switch: each given field replaces the stored one (`disabled` is the
+     * whole list, stored sorted without duplicates); at least one field.
+     */
+    clientExtensions: z
+        .object({ enabled: z.boolean().optional(), disabled: ClientDisabledList.optional() })
+        .strict()
+        .refine((o) => o.enabled !== undefined || o.disabled !== undefined, {
+        message: "give enabled, disabled or both",
+    })
+        .optional(),
 })
     .strict();
 /**
@@ -258,6 +319,19 @@ export async function readUiArrangement(db) {
     const parsed = UiArrangementSchema.safeParse(row?.value);
     return parsed.success ? parsed.data : {};
 }
+/**
+ * The client code kill switch, read live from PG on every request (in the caller's transaction when
+ * there is one; never cached: every replica sees a change at once), through
+ * {@link parseClientExtensions} (missing or invalid -> everything on; invalid also warns on `log`).
+ */
+export async function readClientExtensions(db, log) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", CLIENT_EXTENSIONS_SETTING)
+        .executeTakeFirst();
+    return parseClientExtensions(row?.value, log);
+}
 /** 按组织合并覆盖：值为 null 删除该组织，其余整项替换；未列出的组织不变。 */
 function mergeByOrg(current, patch) {
     const merged = { ...current };
@@ -349,12 +423,21 @@ let SettingsService = class SettingsService {
             }
             next.uiTheme = { id: patch.uiTheme.id };
         }
-        const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, uiArrangement: arrangementPatch, } = patch;
+        const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, uiArrangement: arrangementPatch, clientExtensions: clientPatch, } = patch;
         if (runPatch !== undefined ||
             sandboxPatch !== undefined ||
             subagentPatch !== undefined ||
-            arrangementPatch !== undefined) {
+            arrangementPatch !== undefined ||
+            clientPatch !== undefined) {
             const current = await this.get();
+            if (clientPatch !== undefined) {
+                next.clientExtensions = {
+                    enabled: clientPatch.enabled ?? current.clientExtensions.enabled,
+                    disabled: clientPatch.disabled === undefined
+                        ? current.clientExtensions.disabled
+                        : [...new Set(clientPatch.disabled)].sort(),
+                };
+            }
             if (arrangementPatch !== undefined) {
                 next.uiArrangement = mergeArrangement(current.uiArrangement, arrangementPatch);
             }

package/dist/infra/throttler/named-throttlers.d.ts

@@ -29,6 +29,10 @@ export interface NamedThrottler {
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
  * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
  *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
  * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`

package/dist/infra/throttler/named-throttlers.js

@@ -30,6 +30,10 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
  * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
  *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
  * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
@@ -153,6 +157,16 @@ export const NAMED_THROTTLERS = [
         message: "Too many device code attempts; try again later",
         getTracker: (req) => sha256(principalAccountId(req)),
     },
+    // client code crash reports per signed-in account (counted before the handler): 20 / minute
+    {
+        name: "client-reports",
+        group: "client-reports",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: 60_000,
+        message: "Too many client reports; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
     // setup check runs per signed-in person (setup guides v2 §10.5): 30 a minute, every request
     // counts (@Throttled); a cached answer costs no third-party call but still counts, as the page
     // asks at most once per row and stale result. The edge of the route (with `retry-after`): the

package/dist/kernel.module.js

@@ -9,6 +9,7 @@ import { Global, Module } from "@nestjs/common";
 import { APP_INTERCEPTOR } from "@nestjs/core";
 import { CatalogModule } from "./catalog/catalog.module.js";
 import { ChannelsModule } from "./channels/channels.module.js";
+import { ClientModule } from "./client/client.module.js";
 import { TitlesModule } from "./conversations/titles.js";
 import { ExtensionsModule } from "./extensions/extensions.module.js";
 import { ApiModule } from "./http/api.module.js";
@@ -111,6 +112,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // client extensions: the client builds stored with extension packages
+                ClientModule,
                 // the @local sandbox provider, registered on every role (any replica may relay to a machine)
                 LocalDevicesModule,
                 // the Platform tool's operation registry and actor facts

package/dist/orgs/settings.service.d.ts

@@ -87,19 +87,7 @@ export declare const OrgSettingsSchema: z.ZodObject<{
             locked: "locked";
         }>;
     }, z.core.$strict>>>;
-    uiArrangement: z.ZodCatch<z.ZodOptional<z.ZodRecord<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.$partial, z.ZodObject<{
-        hidden: z.ZodArray<z.ZodString>;
-        order: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>>;
+    uiArrangement: z.ZodCatch<z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown>>>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -137,19 +125,7 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
             locked: "locked";
         }>;
     }, z.core.$strict>>>;
-    uiArrangement: z.ZodOptional<z.ZodRecord<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.$partial, z.ZodNullable<z.ZodObject<{
-        hidden: z.ZodArray<z.ZodString>;
-        order: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>>;
+    uiArrangement: z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown>>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
 /** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */

package/dist/platform/exclusions.js

@@ -714,9 +714,35 @@ export const PLATFORM_EXCLUSIONS = [
         category: "transport",
         reason: "Server-sent event stream of UI invalidations",
     },
+    // client extensions (client extensions spec §9.2-§9.3)
+    {
+        route: "GET /api/v1/client/:plugin/:build/*",
+        category: "transport",
+        reason: "Serves a plugin's client code, stylesheets and assets to the browser that runs them",
+    },
+    {
+        route: "GET /api/v1/orgs/:orgId/ui/client",
+        category: "internal",
+        reason: "The web shell's list of client code to load (file URLs and integrity); nothing an agent acts on",
+    },
+    {
+        route: "GET /api/v1/admin/ui/client",
+        category: "internal",
+        reason: "The admin console's list of platform page client code to load; nothing an agent acts on",
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/ui/client/reports",
+        category: "transport",
+        reason: "Fire-and-forget crash report sent by the browser that ran the client code",
+    },
+    {
+        route: "POST /api/v1/admin/ui/client/reports",
+        category: "transport",
+        reason: "Fire-and-forget crash report sent by the admin console that ran the client code",
+    },
     // themes (themes spec §8-§9)
     {
-        route: "GET /api/v1/themes/:id/:version/theme.css",
+        route: "GET /api/v1/themes/:id/:version/:revision/theme.css",
         category: "transport",
         reason: "Serves a theme version's stylesheet to the browser; an agent reads themes.list",
     },

package/dist/platform/ops/admin.ops.js

@@ -41,6 +41,7 @@ const SettingsInput = DEPLOYMENT_SETTINGS_PATCH.pick({
     orgMarketplaceBrowse: true,
     uiTheme: true,
     uiArrangement: true,
+    clientExtensions: true,
 }).strict();
 const ProviderId = ModelProviderParams.shape.provider.describe("The model provider (models.platform-list), e.g. the plugin name of its extension.");
 /** `provider/model` of a purpose target, or null. */
@@ -122,7 +123,7 @@ let AdminOperations = class AdminOperations {
             }),
             defineOperation({
                 id: "admin.update-settings",
-                description: "Change deployment settings (super admin); give only the keys to change: orgCreation (anyone or super_admin), priceCurrency (ISO 4217 code), customConnectors / customSkills (allow or deny: whether orgs may create their own instead of installing from the catalog), orgMarketplaceBrowse (true or false), uiTheme ({ id }: the platform default theme, a platform theme whose scope is all, or null for the built-in theme; it is what every org falls back to and what the sign-in pages show), uiArrangement ({ <slot>: { hidden, order } }: the platform default arrangement of UI slots, with contribution keys <extension>/<contribution>; hidden ones are not listed but still open by URL; null for a slot removes its entry). Per-org limits are orgs.set-limits.",
+                description: "Change deployment settings (super admin); give only the keys to change: orgCreation (anyone or super_admin), priceCurrency (ISO 4217 code), customConnectors / customSkills (allow or deny: whether orgs may create their own instead of installing from the catalog), orgMarketplaceBrowse (true or false), uiTheme ({ id }: the platform default theme, a platform theme whose scope is all, or null for the built-in theme; it is what every org falls back to and what the sign-in pages show), uiArrangement ({ <slot>: { hidden, order } } for a list slot, { <slot>: { use } } for a single slot: the platform default arrangement of UI slots, with contribution keys <extension>/<contribution>; hidden ones are not listed but still open by URL; use names the contribution that replaces the built-in, null for the built-in; null for a slot removes its entry), clientExtensions ({ enabled?, disabled? }: the kill switch of plugin client code; enabled false stops every plugin's interface code in every browser, disabled is the whole list of plugins whose interface code alone is stopped while their tools keep working; read the current list from admin.settings first). Per-org limits are orgs.set-limits.",
                 input: SettingsInput.refine((b) => Object.keys(b).length > 0, {
                     message: "at least one setting is required",
                 }),
@@ -149,7 +150,7 @@ let AdminOperations = class AdminOperations {
                         : { ok: false, code: "validation_failed", message: r.error.issues[0]?.message ?? "" };
                 },
                 summary: async (i) => {
-                    const { uiTheme, uiArrangement, ...rest } = i;
+                    const { uiTheme, uiArrangement, clientExtensions, ...rest } = i;
                     const parts = Object.entries(rest).map(([k, v]) => `${k}=${String(v)}`);
                     const zh = [...parts];
                     const en = [...parts];
@@ -164,6 +165,20 @@ let AdminOperations = class AdminOperations {
                         zh.push(`uiArrangement（${slots}）`);
                         en.push(`uiArrangement (${slots})`);
                     }
+                    if (clientExtensions !== undefined) {
+                        const { enabled, disabled } = clientExtensions;
+                        if (enabled !== undefined) {
+                            zh.push(enabled ? "开启插件界面代码" : "停用全部插件界面代码");
+                            en.push(enabled ? "plugin interface code on" : "all plugin interface code stopped");
+                        }
+                        if (disabled !== undefined) {
+                            const list = disabled.length === 0 ? null : disabled.join(", ");
+                            zh.push(list === null ? "不再单独停用任何插件的界面代码" : `停用界面代码的插件：${list}`);
+                            en.push(list === null
+                                ? "no plugin's interface code stopped on its own"
+                                : `interface code stopped for: ${list}`);
+                        }
+                    }
                     return {
                         zh: `修改平台部署设置：${zh.join("，")}`,
                         en: `Change the deployment settings: ${en.join(", ")}`,

package/dist/platform/ops/catalog-admin.ops.d.ts

@@ -1,8 +1,10 @@
 import { type OnModuleInit } from "@nestjs/common";
+import { type AppearanceResult, AppearanceService } from "../../catalog/appearance.service.js";
 import { CatalogService } from "../../catalog/catalog.service.js";
 import { CatalogScopeService } from "../../catalog/catalog-scope.service.js";
 import { PluginImport, type PluginReview } from "../../catalog/plugin-import.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ThemesService } from "../../themes/themes.service.js";
 import { PlatformOperations } from "../registry.js";
 /** `plugins.set-shown` on a plugin an org owns. */
 export declare const ORG_OWNED = "An org owns this plugin and manages who sees it; the super admin changes that in the admin console, not here.";
@@ -41,6 +43,20 @@ export declare const reviewBrief: (r: PluginReview) => {
         resolved: string | null;
     }[];
 };
+/**
+ * The card of an "apply this plugin's appearance" operation (client extensions spec §6.5), from the
+ * route's dry run: the theme it sets (its name), the slots it replaces and how many were skipped.
+ */
+export declare function appearanceSummary(level: "platform" | "org", plugin: {
+    zh: string;
+    en: string;
+}, r: AppearanceResult, theme: {
+    zh: string;
+    en: string;
+} | null): {
+    zh: string;
+    en: string;
+};
 /**
  * The super admin's platform catalog operations of the `Platform` tool (spec §14.2, §14.5 item
  * 1): prepare an import from npm or git and read its review (a person confirms it on the web: the
@@ -55,7 +71,9 @@ export declare class CatalogAdminOperations implements OnModuleInit {
     private readonly scope;
     private readonly pluginImport;
     private readonly kdb;
-    constructor(registry: PlatformOperations, catalog: CatalogService, scope: CatalogScopeService, pluginImport: PluginImport, kdb: KernelDb);
+    private readonly appearance;
+    private readonly themes;
+    constructor(registry: PlatformOperations, catalog: CatalogService, scope: CatalogScopeService, pluginImport: PluginImport, kdb: KernelDb, appearance: AppearanceService, themes: ThemesService);
     /** The precheck refusal of another org's private plugin (the phase-1 rule), else null. */
     private otherOrgs;
     /** Whether an org owns the item (its owner org manages it, not the super admin's agent). */

package/dist/platform/ops/catalog-admin.ops.js

@@ -11,11 +11,13 @@ import { ToolError } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { CatalogDisabledBody, CatalogGitImportBody, CatalogIdPathParams, CatalogNpmImportBody, CatalogScope, CatalogScopeBody, CatalogScopeOrgs, CatalogShownBody, CatalogStagingPathParams, } from "../../catalog/admin-catalog.schemas.js";
+import { AppearanceService } from "../../catalog/appearance.service.js";
 import { CatalogService } from "../../catalog/catalog.service.js";
 import { CatalogScopeService } from "../../catalog/catalog-scope.service.js";
 import { PluginImport } from "../../catalog/plugin-import.js";
 import { ApiError } from "../../errors.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ThemesService } from "../../themes/themes.service.js";
 import { defineOperation } from "../operation.js";
 import { PlatformOperations } from "../registry.js";
 import { precheckBy, viaAgent } from "./errors.js";
@@ -64,6 +66,37 @@ export const reviewBrief = (r) => ({
 const conflictText = (cs) => cs
     .map((c) => `skill "${c.name}" is already used in org ${c.orgName} (${c.plugins.length > 0 ? `${c.plugins.length} plugin(s)` : "its own skill"})`)
     .join("; ");
+/**
+ * The card of an "apply this plugin's appearance" operation (client extensions spec §6.5), from the
+ * route's dry run: the theme it sets (its name), the slots it replaces and how many were skipped.
+ */
+export function appearanceSummary(level, plugin, r, theme) {
+    const zh = [];
+    const en = [];
+    if (r.theme !== null && theme !== null) {
+        zh.push(`${level === "platform" ? "平台" : "本组织"}默认主题改为「${theme.zh}」`);
+        en.push(`${level === "platform" ? "platform" : "org"} default theme becomes "${theme.en}"`);
+    }
+    if (r.replacements.length > 0) {
+        const slots = r.replacements.map((x) => x.slot).join(", ");
+        zh.push(`替换 ${slots}`);
+        en.push(`replaces ${slots}`);
+    }
+    if (r.skipped.length > 0) {
+        zh.push(`跳过 ${r.skipped.length} 项`);
+        en.push(`${r.skipped.length} skipped`);
+    }
+    if (zh.length === 0) {
+        return {
+            zh: `插件「${plugin.zh}」的外观已经应用，没有改动`,
+            en: `The appearance of plugin "${plugin.en}" is applied already; nothing changes`,
+        };
+    }
+    return {
+        zh: `应用插件「${plugin.zh}」的外观：${zh.join("；")}`,
+        en: `Apply the appearance of plugin "${plugin.en}": ${en.join("; ")}`,
+    };
+}
 /** A scope preview as the admin console shows it (orgs named); conflicting plugins counted. */
 const previewBrief = (p) => ({
     affected: p.affected,
@@ -93,12 +126,16 @@ let CatalogAdminOperations = class CatalogAdminOperations {
     scope;
     pluginImport;
     kdb;
-    constructor(registry, catalog, scope, pluginImport, kdb) {
+    appearance;
+    themes;
+    constructor(registry, catalog, scope, pluginImport, kdb, appearance, themes) {
         this.registry = registry;
         this.catalog = catalog;
         this.scope = scope;
         this.pluginImport = pluginImport;
         this.kdb = kdb;
+        this.appearance = appearance;
+        this.themes = themes;
     }
     /** The precheck refusal of another org's private plugin (the phase-1 rule), else null. */
     async otherOrgs(itemId, orgId) {
@@ -585,6 +622,50 @@ let CatalogAdminOperations = class CatalogAdminOperations {
                     return { deleted: input.itemId };
                 },
             }),
+            defineOperation({
+                id: "plugins.platform-apply-appearance",
+                description: "Apply a platform plugin's suggested appearance (super admin; the admin console's 应用此插件的外观): in one step, its theme becomes the platform default theme and each component it suggests replaces the built-in block of its slot (shell.brand, conversation.empty, conversation.composer.frame) in the platform arrangement; orgs that set their own keep theirs. The card shows exactly what changes; a theme that cannot be the platform default (scope not all, or off in an org) refuses the whole call, a component that is not available is skipped. Asked every time, never remembered.",
+                input: z.object({ itemId: ItemId }).strict(),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
+                authz: { superAdmin: true },
+                mirrors: ["POST /api/v1/admin/catalog/items/:id/appearance"],
+                renames: { itemId: "id" },
+                // the route's dry run is this operation's card and precheck, never a confirmed call
+                omits: ["dryRun"],
+                confirm: "platform",
+                rememberable: false,
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "Check the plugin id with plugins.platform-list; only a plugin whose plugin.json has suggestedAppearance can be applied.",
+                    },
+                    {
+                        code: "theme.not_available",
+                        next: "The plugin's theme cannot be the platform default: give it scope all (plugins.component-scope-preview, then plugins.set-component-scope) and make sure no org switched it off, then apply again.",
+                    },
+                ],
+                precheck: async (i, ctx) => {
+                    const other = await this.otherOrgs(i.itemId, ctx.orgId);
+                    if (other !== null)
+                        return other;
+                    return precheckBy(() => this.appearance.apply({ platform: true }, i.itemId, { accountId: ctx.actorAccountId }, true));
+                },
+                summary: async (i, ctx) => {
+                    const [n, r] = await Promise.all([
+                        this.names(i.itemId),
+                        this.appearance.apply({ platform: true }, i.itemId, { accountId: ctx.actorAccountId }, true),
+                    ]);
+                    const theme = r.theme && localized(await this.themes.nameOf(r.theme.to), r.theme.to);
+                    return appearanceSummary("platform", n, r, theme);
+                },
+                run: async (input, ctx) => {
+                    await assertNotOtherOrgs(this.kdb.db, input.itemId, ctx.orgId);
+                    return this.appearance.apply({ platform: true }, input.itemId, {
+                        accountId: ctx.actorAccountId,
+                        auditDetail: viaAgent("plugins.platform-apply-appearance", ctx),
+                    }, false);
+                },
+            }),
         ]);
     }
 };
@@ -594,6 +675,8 @@ CatalogAdminOperations = __decorate([
     __param(1, Inject(CatalogService)),
     __param(2, Inject(CatalogScopeService)),
     __param(3, Inject(PluginImport)),
-    __param(4, Inject(KernelDb))
+    __param(4, Inject(KernelDb)),
+    __param(5, Inject(AppearanceService)),
+    __param(6, Inject(ThemesService))
 ], CatalogAdminOperations);
 export { CatalogAdminOperations };

package/dist/platform/ops/org-plugins.ops.d.ts

@@ -1,10 +1,12 @@
 import { type OnModuleInit } from "@nestjs/common";
+import { AppearanceService } from "../../catalog/appearance.service.js";
 import { CatalogScopeService } from "../../catalog/catalog-scope.service.js";
 import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
 import { OrgPluginUploads } from "../../catalog/org-plugin-uploads.js";
 import { OwnedItems } from "../../catalog/owned-items.js";
 import { PluginInstaller } from "../../catalog/plugin-install.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ThemesService } from "../../themes/themes.service.js";
 import { PlatformOperations } from "../registry.js";
 /**
  * The org's own plugin operations of the `Platform` tool (spec §14.2): the org's plugin installs
@@ -20,7 +22,11 @@ export declare class OrgPluginsOperations implements OnModuleInit {
     private readonly owned;
     private readonly scope;
     private readonly kdb;
-    constructor(registry: PlatformOperations, installer: PluginInstaller, orgCatalog: OrgCatalogService, uploads: OrgPluginUploads, owned: OwnedItems, scope: CatalogScopeService, kdb: KernelDb);
+    private readonly appearance;
+    private readonly themes;
+    constructor(registry: PlatformOperations, installer: PluginInstaller, orgCatalog: OrgCatalogService, uploads: OrgPluginUploads, owned: OwnedItems, scope: CatalogScopeService, kdb: KernelDb, appearance: AppearanceService, themes: ThemesService);
+    /** The display name of the live plugin of `extension`, or the name when it cannot be read. */
+    private pluginNames;
     /** The org's own live plugin `id`, or null (another org's, a platform one, deleted, unknown). */
     private ownedItem;
     /** The precheck refusal of a plugin the org does not own. */

package/dist/platform/ops/org-plugins.ops.js

@@ -9,20 +9,23 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
+import { AppearanceService } from "../../catalog/appearance.service.js";
 import { CatalogScopeService } from "../../catalog/catalog-scope.service.js";
 import { PluginInstallPathParams } from "../../catalog/org-catalog.schemas.js";
 import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
+import { OrgExtensionParams } from "../../catalog/org-extension.schemas.js";
 import { OrgPluginUploads } from "../../catalog/org-plugin-uploads.js";
 import { OrgOwnedDeleteBody, OrgOwnedPluginParams, OrgOwnedShareableBody, OrgUploadStagingParams, } from "../../catalog/org-plugin-uploads.schemas.js";
 import { OwnedItems } from "../../catalog/owned-items.js";
 import { PluginInstaller } from "../../catalog/plugin-install.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ThemesService } from "../../themes/themes.service.js";
 import { defineOperation } from "../operation.js";
 import { PlatformOperations } from "../registry.js";
-import { reviewBrief } from "./catalog-admin.ops.js";
+import { appearanceSummary, reviewBrief } from "./catalog-admin.ops.js";
 import { precheckBy, viaAgent } from "./errors.js";
 import { Cursor, pageOf, startOf } from "./paging.js";
-import { named } from "./summary.js";
+import { localized, named, orElse } from "./summary.js";
 const InstallId = PluginInstallPathParams.shape.installId.max(100);
 /** An org-owned plugin's catalog item id (`:id` of the owned-plugins routes). */
 const OwnedId = OrgOwnedPluginParams.shape.id;
@@ -51,7 +54,9 @@ let OrgPluginsOperations = class OrgPluginsOperations {
     owned;
     scope;
     kdb;
-    constructor(registry, installer, orgCatalog, uploads, owned, scope, kdb) {
+    appearance;
+    themes;
+    constructor(registry, installer, orgCatalog, uploads, owned, scope, kdb, appearance, themes) {
         this.registry = registry;
         this.installer = installer;
         this.orgCatalog = orgCatalog;
@@ -59,6 +64,20 @@ let OrgPluginsOperations = class OrgPluginsOperations {
         this.owned = owned;
         this.scope = scope;
         this.kdb = kdb;
+        this.appearance = appearance;
+        this.themes = themes;
+    }
+    /** The display name of the live plugin of `extension`, or the name when it cannot be read. */
+    pluginNames(extension) {
+        return orElse(async () => {
+            const row = await this.kdb.db
+                .selectFrom("catalog_items")
+                .select("display_name")
+                .where("name", "=", extension)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            return localized(row?.display_name, extension);
+        }, { zh: named(extension), en: named(extension) });
     }
     /** The org's own live plugin `id`, or null (another org's, a platform one, deleted, unknown). */
     async ownedItem(orgId, id) {
@@ -313,6 +332,44 @@ let OrgPluginsOperations = class OrgPluginsOperations {
                     return { withdrawn: input.itemId };
                 },
             }),
+            defineOperation({
+                id: "plugins.apply-appearance",
+                description: "Apply a plugin's suggested appearance in this org (org admins; the 扩展 page's 应用此插件的外观), for a plugin whose extension is on here: in one step, its theme becomes the org's default theme (whether members may pick their own stays as it is) and each component it suggests replaces the built-in block of its slot (shell.brand, conversation.empty, conversation.composer.frame) in the org's arrangement. The card shows exactly what changes; a theme that is not on in the org refuses the whole call, a component that is not available is skipped. Asked every time, never remembered.",
+                input: z.object({ extension: OrgExtensionParams.shape.extension }).strict(),
+                example: { extension: "theme-cyberpunk" },
+                authz: { orgAction: "org.update" },
+                mirrors: ["POST /api/v1/orgs/:orgId/extensions/:extension/appearance"],
+                // the route's dry run is this operation's card and precheck, never a confirmed call
+                omits: ["dryRun"],
+                confirm: "org",
+                rememberable: false,
+                errors: [
+                    {
+                        code: "extension.not_found",
+                        next: "Check the extension with extensions.list: it must be on in this org and its plugin must suggest an appearance.",
+                    },
+                    {
+                        code: "theme.not_available",
+                        next: {
+                            orgAdmin: "The plugin's theme is not on in this org: switch it on in the org's appearance settings on the web, or ask the super admin to offer it to this org, then apply again.",
+                            member: "Ask an org admin to switch the plugin's theme on in this org first.",
+                        },
+                    },
+                ],
+                precheck: (i, ctx) => precheckBy(() => this.appearance.apply({ orgId: ctx.orgId }, i.extension, { accountId: ctx.actorAccountId }, true)),
+                summary: async (i, ctx) => {
+                    const [n, r] = await Promise.all([
+                        this.pluginNames(i.extension),
+                        this.appearance.apply({ orgId: ctx.orgId }, i.extension, { accountId: ctx.actorAccountId }, true),
+                    ]);
+                    const theme = r.theme && localized(await this.themes.nameIn(ctx.orgId, r.theme.to), r.theme.to);
+                    return appearanceSummary("org", n, r, theme);
+                },
+                run: async (input, ctx) => this.appearance.apply({ orgId: ctx.orgId }, input.extension, {
+                    accountId: ctx.actorAccountId,
+                    auditDetail: viaAgent("plugins.apply-appearance", ctx),
+                }, false),
+            }),
         ]);
     }
 };
@@ -324,6 +381,8 @@ OrgPluginsOperations = __decorate([
     __param(3, Inject(OrgPluginUploads)),
     __param(4, Inject(OwnedItems)),
     __param(5, Inject(CatalogScopeService)),
-    __param(6, Inject(KernelDb))
+    __param(6, Inject(KernelDb)),
+    __param(7, Inject(AppearanceService)),
+    __param(8, Inject(ThemesService))
 ], OrgPluginsOperations);
 export { OrgPluginsOperations };