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

package/dist/themes/theme-state.d.ts

@@ -6,6 +6,11 @@ import { ApiError } from "../errors.js";
 export interface ThemeRef {
     /** The `platform_themes` id (what settings and picks store). */
     id: string;
+    /**
+     * `"<plugin>/<theme file id>"`: the name the web's `theme=` state token and `useTheme()` carry
+     * (client extensions spec §7.3). Stable across versions, unlike `id`.
+     */
+    key: string;
     /** Its current version. */
     version: string;
     name: LocalizedName;
@@ -19,7 +24,7 @@ export interface ThemeRef {
         wordmark: string | null;
         faviconUrl: string | null;
     } | null;
-    /** `/api/v1/themes/<id>/<version>/theme.css`. */
+    /** `/api/v1/themes/<id>/<version>/r<THEME_CSS_REVISION>/theme.css`. */
     cssUrl: string;
 }
 /** The four colors a theme picker draws per scheme. */
@@ -34,24 +39,40 @@ export type ListedTheme = ThemeRef & {
     swatches: Partial<Record<ThemeScheme, ThemeSwatch>>;
 };
 /**
- * The delivery URL of a theme version (spec §8): its stylesheet, or with `asset` (a path inside the
+ * The render revision of theme stylesheets, a segment of the stylesheet URL (`r<N>/theme.css`).
+ * The stylesheet is cached as immutable for a year, keyed by its URL: bump this whenever
+ * `renderThemeCss`'s output format changes, so no browser keeps an older format under a URL
+ * that now means the new one. The delivery route serves only the current revision (404
+ * `theme.not_found` otherwise). History: (none, `<version>/theme.css`) plain rules; 2: one
+ * `@layer theme { … }` block (client extensions spec §7.2).
+ */
+export declare const THEME_CSS_REVISION = 2;
+/**
+ * The delivery URL of a theme version (spec §8): its stylesheet (with the render revision,
+ * {@link THEME_CSS_REVISION}), or with `asset` (a path inside the
  * plugin as the theme file names it, e.g. `./fonts/MiSans.woff2`) that asset, as one path segment
  * (`assets/fonts%2FMiSans.woff2`; the route decodes it back to the stored path `fonts/MiSans.woff2`).
  * The one builder of these URLs: the listing, the stylesheet and the asset routes all use it.
  */
 export declare function themeUrl(id: string, version: string, asset?: string): string;
-/** The {@link ThemeRef} of version `version` of theme `id`. */
-export declare function themeRefOf(id: string, version: string, def: ParsedTheme): ThemeRef;
+/**
+ * The {@link ThemeRef} of version `version` of theme `id` of plugin `plugin` (null only for a row
+ * without provenance: the key is then the file id alone).
+ */
+export declare function themeRefOf(id: string, version: string, def: ParsedTheme, plugin: string | null): ThemeRef;
 /**
  * The swatches of each scheme the theme defines: its overrides merged onto the current built-in
  * values (a stored definition holds only the theme file's own values, themes spec §6).
  */
 export declare function themeSwatches(def: ParsedTheme): Partial<Record<ThemeScheme, ThemeSwatch>>;
-/** The current definitions of live themes `ids`, by id. */
-export declare function themeDefinitions(db: KernelSchemaDb, ids: readonly string[]): Promise<Map<string, {
+/** A live theme's current definition and its plugin (null: no provenance). */
+export interface ThemeDefinition {
     version: string;
     definition: ParsedTheme;
-}>>;
+    plugin: string | null;
+}
+/** The current definitions of live themes `ids`, by id. */
+export declare function themeDefinitions(db: KernelSchemaDb, ids: readonly string[]): Promise<Map<string, ThemeDefinition>>;
 /** The live themes on in the org, sorted by id. */
 export declare function themesOnIn(db: KernelSchemaDb, orgId: string): Promise<ComponentRow[]>;
 /** The live theme `id` if it can be the platform default, else null. */

package/dist/themes/theme-state.js

@@ -9,7 +9,17 @@ import { packagePath } from "../packages/tgz.js";
 /** The schemes in the order they are listed. */
 const SCHEMES = ["dark", "light"];
 /**
- * The delivery URL of a theme version (spec §8): its stylesheet, or with `asset` (a path inside the
+ * The render revision of theme stylesheets, a segment of the stylesheet URL (`r<N>/theme.css`).
+ * The stylesheet is cached as immutable for a year, keyed by its URL: bump this whenever
+ * `renderThemeCss`'s output format changes, so no browser keeps an older format under a URL
+ * that now means the new one. The delivery route serves only the current revision (404
+ * `theme.not_found` otherwise). History: (none, `<version>/theme.css`) plain rules; 2: one
+ * `@layer theme { … }` block (client extensions spec §7.2).
+ */
+export const THEME_CSS_REVISION = 2;
+/**
+ * The delivery URL of a theme version (spec §8): its stylesheet (with the render revision,
+ * {@link THEME_CSS_REVISION}), or with `asset` (a path inside the
  * plugin as the theme file names it, e.g. `./fonts/MiSans.woff2`) that asset, as one path segment
  * (`assets/fonts%2FMiSans.woff2`; the route decodes it back to the stored path `fonts/MiSans.woff2`).
  * The one builder of these URLs: the listing, the stylesheet and the asset routes all use it.
@@ -17,14 +27,18 @@ const SCHEMES = ["dark", "light"];
 export function themeUrl(id, version, asset) {
     const base = `/api/v1/themes/${encodeURIComponent(id)}/${encodeURIComponent(version)}`;
     return asset === undefined
-        ? `${base}/theme.css`
+        ? `${base}/r${THEME_CSS_REVISION}/theme.css`
         : `${base}/assets/${encodeURIComponent(packagePath(asset))}`;
 }
-/** The {@link ThemeRef} of version `version` of theme `id`. */
-export function themeRefOf(id, version, def) {
+/**
+ * The {@link ThemeRef} of version `version` of theme `id` of plugin `plugin` (null only for a row
+ * without provenance: the key is then the file id alone).
+ */
+export function themeRefOf(id, version, def, plugin) {
     const url = (ref) => (ref === undefined ? null : themeUrl(id, version, ref));
     return {
         id,
+        key: plugin === null ? def.id : `${plugin}/${def.id}`,
         version,
         name: def.name,
         schemes: SCHEMES.filter((s) => def.schemes[s] !== undefined),
@@ -62,12 +76,16 @@ export async function themeDefinitions(db, ids) {
     const rows = await db
         .selectFrom("platform_themes as p")
         .innerJoin("platform_theme_versions as v", (j) => j.onRef("v.theme_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
-        .select(["p.id", "p.current_version", "v.definition"])
+        .select(["p.id", "p.current_version", "p.plugin_name", "v.definition"])
         .where("p.id", "in", [...ids])
         .where("p.deleted_at", "is", null)
         .execute();
     for (const r of rows) {
-        out.set(r.id, { version: String(r.current_version), definition: r.definition });
+        out.set(r.id, {
+            version: String(r.current_version),
+            definition: r.definition,
+            plugin: r.plugin_name,
+        });
     }
     return out;
 }

package/dist/themes/themes-public.controller.d.ts

@@ -10,8 +10,13 @@ import { ThemesService } from "./themes.service.js";
 export declare class ThemeDeliveryController {
     private readonly delivery;
     constructor(delivery: ThemeDeliveryService);
-    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
-    css(id: string, version: string, reply: FastifyReply): Promise<void>;
+    /**
+     * The version's stylesheet: scheme overrides, `@font-face` rules and font stacks, in the render
+     * revision `revision` (`r<THEME_CSS_REVISION>`; only the current one is served). The URL without
+     * a revision (before revision 2) has no route: 404, so a browser's cached unlayered copy is never
+     * answered with the new format under an immutable cache.
+     */
+    css(id: string, version: string, revision: string, reply: FastifyReply): Promise<void>;
     /**
      * A font (`font/woff2`) or logo (`image/svg+xml`, sanitized at import, served under a CSP
      * sandbox; `image/png`) the version names; `file` is its plugin path as one segment

package/dist/themes/themes-public.controller.js

@@ -23,9 +23,14 @@ let ThemeDeliveryController = class ThemeDeliveryController {
     constructor(delivery) {
         this.delivery = delivery;
     }
-    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
-    async css(id, version, reply) {
-        const css = await this.delivery.stylesheet(id, version);
+    /**
+     * The version's stylesheet: scheme overrides, `@font-face` rules and font stacks, in the render
+     * revision `revision` (`r<THEME_CSS_REVISION>`; only the current one is served). The URL without
+     * a revision (before revision 2) has no route: 404, so a browser's cached unlayered copy is never
+     * answered with the new format under an immutable cache.
+     */
+    async css(id, version, revision, reply) {
+        const css = await this.delivery.stylesheet(id, version, revision);
         await reply
             .header("content-type", "text/css; charset=utf-8")
             .header("x-content-type-options", "nosniff")
@@ -51,10 +56,11 @@ let ThemeDeliveryController = class ThemeDeliveryController {
 };
 __decorate([
     Public(),
-    Get("theme.css"),
+    Get(":revision/theme.css"),
     __param(0, Param("id")),
     __param(1, Param("version")),
-    __param(2, Res())
+    __param(2, Param("revision")),
+    __param(3, Res())
 ], ThemeDeliveryController.prototype, "css", null);
 __decorate([
     Public(),

package/dist/themes/themes.service.js

@@ -32,7 +32,7 @@ let ThemesService = class ThemesService {
             if (!d)
                 continue;
             out.push({
-                ...themeRefOf(c.id, d.version, d.definition),
+                ...themeRefOf(c.id, d.version, d.definition, d.plugin),
                 swatches: themeSwatches(d.definition),
             });
         }
@@ -53,7 +53,7 @@ let ThemesService = class ThemesService {
         if (id === null || (await eligiblePlatformDefault(this.db.db, id)) === null)
             return null;
         const d = (await themeDefinitions(this.db.db, [id])).get(id);
-        return d ? themeRefOf(id, d.version, d.definition) : null;
+        return d ? themeRefOf(id, d.version, d.definition, d.plugin) : null;
     }
     /**
      * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one

package/dist/tools/connectors.controller.d.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import type { ConnectionGuideState } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ConnectorAccountPolicies, type MemberToolPolicyView } from "./connector-account-policies.js";
-import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
@@ -169,6 +170,14 @@ declare const UpdateBody: z.ZodObject<{
     }, z.core.$strict>>>;
     allowUnannotated: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/**
+ * A connector as the org's pages show it: with its plugin's icon (`icon`, see `withIcons`), its
+ * template's setup guide and the drift since it was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3, §11).
+ */
+export type ConnectorPage<T extends ConnectorSummary = ConnectorDetail> = T & ConnectionGuideState & {
+    icon: string | null;
+};
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
@@ -185,10 +194,11 @@ export declare class ConnectorsController {
      */
     private withIcons;
     list(org: OrgContext): Promise<{
-        connectors: (ConnectorSummary & {
-            icon: string | null;
-        })[];
+        connectors: ConnectorPage<ConnectorSummary>[];
     }>;
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    private withGuides;
+    private withGuide;
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
      * install wizard offers only these; an empty list means no connector extension is enabled).
@@ -200,7 +210,7 @@ export declare class ConnectorsController {
         }[];
     }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
     }>;
     /**
@@ -209,16 +219,14 @@ export declare class ConnectorsController {
      */
     preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
     get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail & {
-            icon: string | null;
-        };
+        connector: ConnectorPage;
     }>;
     update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
     }>;
     remove(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
     refresh(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
         changes: {
             added: string[];
@@ -228,7 +236,16 @@ export declare class ConnectorsController {
     }>;
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     review(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof ReviewBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
+    }>;
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    ackGuide(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectorGuideAckSchema>): Promise<{
+        connector: ConnectorPage;
     }>;
     setOrgCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
     setMyCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;

package/dist/tools/connectors.controller.js

@@ -17,7 +17,7 @@ import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { can } from "../orgs/roles.js";
 import { ConnectorAccountPolicies, } from "./connector-account-policies.js";
-import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody, } from "./connectors.schemas.js";
 import { ConnectorsService, } from "./connectors.service.js";
 import { publicEndpoint } from "./endpoint.js";
 /**
@@ -88,6 +88,8 @@ class ConnectorCredentialBody extends createZodDto(CredentialValue, "ConnectorCr
 }
 class MemberToolPoliciesDto extends createZodDto(MemberToolPoliciesBody, "MemberToolPoliciesBody") {
 }
+class ConnectorGuideAckBody extends createZodDto(ConnectorGuideAckSchema, "ConnectorGuideAckBody") {
+}
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
@@ -115,8 +117,22 @@ let ConnectorsController = class ConnectorsController {
         }));
     }
     async list(org) {
-        const rows = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
-        return { connectors: await this.withIcons(org, rows) };
+        const list = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
+        return { connectors: await this.withGuides(org, list) };
+    }
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    async withGuides(org, views) {
+        const [withIcons, states] = await Promise.all([
+            this.withIcons(org, views),
+            this.connectors.guideStates(org, views.map((v) => v.id)),
+        ]);
+        return withIcons.map((v) => ({
+            ...v,
+            ...(states.get(v.id) ?? { setupGuide: null, guideDrift: null }),
+        }));
+    }
+    async withGuide(org, view) {
+        return (await this.withGuides(org, [view]))[0];
     }
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
@@ -127,7 +143,8 @@ let ConnectorsController = class ConnectorsController {
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
-        return this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        const r = await this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /**
      * 预览（安装向导）：读端点描述（认证提示、操作清单）并在能认证时列出工具，什么都不写。
@@ -139,15 +156,13 @@ let ConnectorsController = class ConnectorsController {
     }
     async get(principal, org, connectorId) {
         const p = requireUser(principal);
-        const c = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
-        const [connector] = await this.withIcons(org, [c]);
-        return { connector: connector };
+        const view = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
+        return { connector: await this.withGuide(org, view) };
     }
     async update(principal, org, connectorId, body) {
         const p = requireUser(principal);
-        return {
-            connector: await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p)),
-        };
+        const view = await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async remove(principal, org, connectorId) {
         const p = requireUser(principal);
@@ -155,14 +170,25 @@ let ConnectorsController = class ConnectorsController {
     }
     async refresh(principal, org, connectorId) {
         const p = requireUser(principal);
-        return this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        const r = await this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     async review(principal, org, connectorId, name, body) {
         const p = requireUser(principal);
-        return {
-            connector: await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p)),
-        };
+        const view = await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
+    }
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    async ackGuide(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        const view = await this.connectors.ackGuide({ orgId: org.orgId, role: org.role }, connectorId, body.hash, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async setOrgCredential(principal, org, connectorId, body) {
         const p = requireUser(principal);
@@ -263,6 +289,15 @@ __decorate([
     __param(3, Param("name")),
     __param(4, ZBody(ConnectorToolReviewBody))
 ], ConnectorsController.prototype, "review", null);
+__decorate([
+    Post(":connectorId/guide-ack"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, ZBody(ConnectorGuideAckBody))
+], ConnectorsController.prototype, "ackGuide", null);
 __decorate([
     Put(":connectorId/credentials/org"),
     HttpCode(204),

package/dist/tools/connectors.schemas.d.ts

@@ -5,6 +5,10 @@ import type { RouteSchemas } from "../platform/route-schemas.js";
  * echoed); this only bounds its size.
  */
 export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export declare const ConnectorGuideAckSchema: z.ZodObject<{
+    hash: z.ZodString;
+}, z.core.$strict>;
 /** `:connectorId` as the routes take it (`@Param`). */
 export declare const ConnectorPathParams: z.ZodObject<{
     connectorId: z.ZodString;

package/dist/tools/connectors.schemas.js

@@ -6,6 +6,10 @@ import { z } from "zod";
 export const CredentialValue = z
     .record(z.string().max(100), z.unknown())
     .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export const ConnectorGuideAckSchema = z
+    .object({ hash: z.string().regex(/^[0-9a-f]{64}$/) })
+    .strict();
 /** `:connectorId` as the routes take it (`@Param`). */
 export const ConnectorPathParams = z.object({ connectorId: z.string().min(1) });
 export const CONNECTOR_ROUTES = [

package/dist/tools/connectors.service.d.ts

@@ -1,9 +1,11 @@
 import { type AuthHint, type ConnectorOperation, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
+import { type ConnectionGuideState, PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { type ConnectorAuth, type CredentialOwner, Credentials, type StaticSecret } from "./credentials.js";
 import { type DriftChanges, ToolDrift, type ToolIssue } from "./drift.js";
 import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
@@ -212,11 +214,15 @@ export declare class ConnectorsService {
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     private readonly orgLock;
     readonly txHost: TransactionHost;
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    private readonly guides;
     constructor(kdb: KernelDb, registry: ToolRegistry, 
     /** Extension manifests (a slug may not take an extension's name). */
     extensions: Pick<ExtensionRegistry, "manifests">, credentials: Credentials, config: Pick<KernelConfigService, "get">, drift: ToolDrift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock: Pick<OrgLock, "lockAndAuthorize">, txHost: TransactionHost);
+    orgLock: Pick<OrgLock, "lockAndAuthorize">, txHost: TransactionHost, 
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides: Pick<PluginGuides, "templateAck" | "connectorStates">);
     /** The kernel-schema handle of the current context (its transaction, else the pool). */
     private get db();
     /**
@@ -305,7 +311,29 @@ export declare class ConnectorsService {
     private row;
     private summary;
     private detail;
-    /** 本组织未删除的连接器（按创建时间）。 */
+    /**
+     * The setup guide fields of the org's connectors (`setupGuide`, `guideDrift`; spec
+     * 2026-11-09-setup-guides-v2-design.md §9.3, §11): resolved through each connector's platform
+     * template to its item's guide for that template; custom connectors get nulls.
+     */
+    guideStates(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorIds: string[]): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * 「我已更新应用」 for a connector made from a template: records the template's current guide as
+     * the one it is set up with. `hash` is the admin drift hash of the guide the person was shown;
+     * when the plugin moved on since, 409 `connector.guide_changed` (show the new guide first). A
+     * connector without a template guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorId: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ConnectorDetail>;
+    /** The row and audit of {@link ackGuide}, in one transaction under the org lock. */
+    private ackIn;
+    /** The org's connectors that are not deleted (by creation time). */
     list(orgId: string): Promise<ConnectorSummary[]>;
     get(orgId: string, connectorId: string, viewerAccountId: string): Promise<ConnectorDetail>;
     /** 改名、启停连接器、工具启停与默认策略、批量把无注解工具改为 allow（`connectors.manage`）。 */

package/dist/tools/connectors.service.js

@@ -15,6 +15,7 @@ import { z } from "zod";
 import { connectorTemplateState } from "../catalog/component-state.js";
 import { assertItemInstallable } from "../catalog/request-rules.js";
 import { ApiError } from "../errors.js";
+import { PluginGuides, } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
 import { assertCustomAllowed } from "../identity/settings.js";
@@ -93,11 +94,14 @@ let ConnectorsService = class ConnectorsService {
     drift;
     orgLock;
     txHost;
+    guides;
     constructor(kdb, registry, 
     /** Extension manifests (a slug may not take an extension's name). */
     extensions, credentials, config, drift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock, txHost) {
+    orgLock, txHost, 
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides) {
         this.kdb = kdb;
         this.registry = registry;
         this.extensions = extensions;
@@ -106,6 +110,7 @@ let ConnectorsService = class ConnectorsService {
         this.drift = drift;
         this.orgLock = orgLock;
         this.txHost = txHost;
+        this.guides = guides;
     }
     /** The kernel-schema handle of the current context (its transaction, else the pool). */
     get db() {
@@ -366,6 +371,11 @@ let ConnectorsService = class ConnectorsService {
                 return this.credentials.injectionFor(id, auth, secret);
             }, { orgId, slug });
         }
+        // the guide the wizard and 补充配置 showed: the template's current one (spec §11)
+        const tpl = input.template;
+        const guideAck = tpl?.templateId !== undefined
+            ? await this.guides.templateAck(tpl.itemId, tpl.templateId)
+            : null;
         return this.createIn(orgId, actorAccountId, input, actorTokenId, {
             id,
             slug,
@@ -374,6 +384,7 @@ let ConnectorsService = class ConnectorsService {
             secret,
             oauth,
             listed,
+            guideAck,
         });
     }
     /** The org-locked, re-checked insert of {@link create} (the outbound checks ran before). */
@@ -434,6 +445,8 @@ let ConnectorsService = class ConnectorsService {
             catalog_item_id: input.template?.itemId ?? null,
             catalog_version: input.template?.version ?? null,
             platform_template_id: platformTemplate?.id ?? null,
+            // linked to its template only through the platform component (drift is judged there)
+            guide_ack: platformTemplate !== undefined && c.guideAck !== null ? JSON.stringify(c.guideAck) : null,
             // 授权码连接器安装时没有快照：模板的默认策略留到首个快照时应用
             template_tool_policies: input.template?.defaultToolPolicies
                 ? JSON.stringify(input.template.defaultToolPolicies)
@@ -826,7 +839,85 @@ let ConnectorsService = class ConnectorsService {
             credential: { ownership: auth.type === "none" ? null : auth.ownership, status },
         };
     }
-    /** 本组织未删除的连接器（按创建时间）。 */
+    /**
+     * The setup guide fields of the org's connectors (`setupGuide`, `guideDrift`; spec
+     * 2026-11-09-setup-guides-v2-design.md §9.3, §11): resolved through each connector's platform
+     * template to its item's guide for that template; custom connectors get nulls.
+     */
+    async guideStates(org, connectorIds) {
+        if (connectorIds.length === 0)
+            return new Map();
+        const rows = await this.db
+            .selectFrom("connectors as c")
+            .leftJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select(["c.id", "c.guide_ack", "t.catalog_item_id", "t.template_id"])
+            .where("c.org_id", "=", org.orgId)
+            .where("c.id", "in", [...new Set(connectorIds)])
+            .where("c.deleted_at", "is", null)
+            .execute();
+        return this.guides.connectorStates(rows.map((r) => ({
+            id: r.id,
+            itemId: r.catalog_item_id ?? null,
+            templateId: r.template_id ?? null,
+            guideAck: r.guide_ack ?? null,
+        })), org);
+    }
+    /**
+     * 「我已更新应用」 for a connector made from a template: records the template's current guide as
+     * the one it is set up with. `hash` is the admin drift hash of the guide the person was shown;
+     * when the plugin moved on since, 409 `connector.guide_changed` (show the new guide first). A
+     * connector without a template guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    async ackGuide(org, connectorId, hash, actorAccountId, actorTokenId) {
+        const { orgId } = org;
+        const r = await this.db
+            .selectFrom("connectors as c")
+            .leftJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select(["c.id", "t.catalog_item_id", "t.template_id"])
+            .where("c.id", "=", connectorId)
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!r)
+            throw notFound();
+        const ack = r.catalog_item_id && r.template_id
+            ? // the guide read's visibility: an item the org's catalog does not show has no guide
+                await this.guides.templateAck(r.catalog_item_id, r.template_id, org)
+            : null;
+        if (ack === null) {
+            throw new ApiError("catalog.guide_not_found", "The connector has no template setup guide");
+        }
+        if (ack.hash !== hash) {
+            throw new ApiError("connector.guide_changed", "The connector template's setup guide changed since it was shown; review the new guide first");
+        }
+        return this.ackIn(orgId, connectorId, ack, actorAccountId, actorTokenId);
+    }
+    /** The row and audit of {@link ackGuide}, in one transaction under the org lock. */
+    async ackIn(orgId, connectorId, ack, actorAccountId, actorTokenId) {
+        const t = this.db;
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
+        const updated = await t
+            .updateTable("connectors")
+            .set({ guide_ack: JSON.stringify(ack), updated_at: sql `now()` })
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .returning("id")
+            .executeTakeFirst();
+        if (!updated)
+            throw notFound();
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.guide_confirmed",
+            target: connectorId,
+            detail: { guideId: ack.guideId, version: ack.version },
+        });
+        return this.detail(t, orgId, connectorId, actorAccountId);
+    }
+    /** The org's connectors that are not deleted (by creation time). */
     async list(orgId) {
         const rows = await this.db
             .selectFrom("connectors")
@@ -1236,6 +1327,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ConnectorsService.prototype, "applyTemplateIn", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "ackIn", null);
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "update", null);
@@ -1269,6 +1363,7 @@ ConnectorsService = __decorate([
     __param(4, Inject(KernelConfigService)),
     __param(5, Inject(ToolDrift)),
     __param(6, Inject(OrgLock)),
-    __param(7, Inject(TransactionHost))
+    __param(7, Inject(TransactionHost)),
+    __param(8, Inject(PluginGuides))
 ], ConnectorsService);
 export { ConnectorsService };