@capybara-hq/plugin-sdk 0.0.0-stage → 0.1.0-rc.0

package/dist/tool.js

@@ -0,0 +1,218 @@
+import { checkParamValue } from "./model-params.js";
+import { isHttpUrl } from "./url.js";
+/** Longest {@link ToolSpec.title}, in code points. */
+export const TOOL_TITLE_MAX = 80;
+/** Most {@link ToolSpec.keyArgs}. */
+export const TOOL_KEY_ARGS_MAX = 3;
+/**
+ * Control (Cc) and format (Cf) characters: newlines, C0 / C1 controls, bidi marks, overrides and
+ * isolates (U+061C, U+200E/F, U+202A–202E, U+2066–2069), invisible ones (U+200B, U+2060, U+FEFF)
+ * and tag characters. They could reorder, hide or break a one-line label, so display titles and key
+ * argument names never carry them. ZWNJ (U+200C) and ZWJ (U+200D) are allowed: Persian and other
+ * scripts and emoji sequences need them.
+ */
+const CONTROL_OR_FORMAT = /(?![\u200C\u200D])[\p{Cc}\p{Cf}]/u;
+/**
+ * Checks the display-only {@link ToolSpec.title} and {@link ToolSpec.keyArgs}; returns the problems
+ * (empty = valid). The title is 1–80 code points, not blank and free of control and format
+ * characters (Unicode Cc / Cf); keyArgs are at most 3 unique strings, each a property of
+ * `inputSchema.properties` and free of Cc / Cf characters.
+ */
+export function validateToolPresentation(spec) {
+    const out = [];
+    const title = spec.title;
+    if (title !== undefined &&
+        (typeof title !== "string" || title.trim() === "" || [...title].length > TOOL_TITLE_MAX)) {
+        out.push(`title must be a non-blank string of at most ${TOOL_TITLE_MAX} characters`);
+    }
+    else if (typeof title === "string" && CONTROL_OR_FORMAT.test(title)) {
+        out.push("title must not contain control, bidi or invisible characters");
+    }
+    const keyArgs = spec.keyArgs;
+    if (keyArgs === undefined)
+        return out;
+    if (!Array.isArray(keyArgs) || keyArgs.some((k) => typeof k !== "string")) {
+        out.push("keyArgs must be an array of input property names");
+        return out;
+    }
+    if (keyArgs.length > TOOL_KEY_ARGS_MAX)
+        out.push(`keyArgs must name at most ${TOOL_KEY_ARGS_MAX} input properties`);
+    if (new Set(keyArgs).size !== keyArgs.length)
+        out.push("keyArgs must not repeat a name");
+    if (keyArgs.some((k) => CONTROL_OR_FORMAT.test(k)))
+        out.push("keyArgs names must not contain control, bidi or invisible characters");
+    const schema = spec.inputSchema;
+    const props = typeof schema?.properties === "object" && schema.properties !== null
+        ? schema.properties
+        : {};
+    for (const k of keyArgs) {
+        if (!Object.hasOwn(props, k))
+            out.push(`keyArgs names "${k}", which is not a property of inputSchema`);
+    }
+    return out;
+}
+const DISPLAY_MAX = 200;
+/** 校验 {@link ToolDisplay}，返回问题列表（空 = 合法）；长度按 Unicode 码点计。 */
+export function validateToolDisplay(d) {
+    if (typeof d !== "object" || d === null || Array.isArray(d))
+        return ["display must be an object"];
+    const s = d.summary;
+    if (typeof s !== "object" || s === null || Array.isArray(s))
+        return ["display.summary must be an object with zh and en"];
+    const out = [];
+    for (const k of ["zh", "en"]) {
+        const v = s[k];
+        if (typeof v !== "string" || v === "" || [...v].length > DISPLAY_MAX)
+            out.push(`display.summary.${k} must be a non-empty string of at most ${DISPLAY_MAX} characters`);
+    }
+    return out;
+}
+/** 工具执行失败：message 给模型看，须为英文且可操作。 */
+export class ToolError extends Error {
+    kind;
+    constructor(message, opts) {
+        super(message);
+        this.name = "ToolError";
+        this.kind = opts?.kind ?? "error";
+    }
+}
+/** 插件工具名规则。 */
+export const EXTENSION_TOOL_NAME = /^[a-zA-Z0-9_-]{1,40}$/;
+/** 校验插件注册的工具声明，返回问题列表（空 = 合法）。 */
+export function validateToolSpec(spec) {
+    const out = [];
+    if (typeof spec?.name !== "string" || !EXTENSION_TOOL_NAME.test(spec.name))
+        out.push(`name must match ${EXTENSION_TOOL_NAME}`);
+    if (typeof spec?.description !== "string" || spec.description.trim() === "")
+        out.push("description must be a non-empty string");
+    if (typeof spec?.inputSchema !== "object" || spec.inputSchema === null)
+        out.push("inputSchema must be an object");
+    if (spec?.defaultPolicy !== undefined &&
+        spec.defaultPolicy !== "allow" &&
+        spec.defaultPolicy !== "ask")
+        out.push('defaultPolicy must be "allow" or "ask"');
+    if (typeof spec?.inputSchema === "object" && spec.inputSchema !== null)
+        out.push(...validateToolPresentation(spec));
+    return out;
+}
+const SCHEMA_KEYS = {
+    string: ["type", "enum", "maxLength"],
+    boolean: ["type"],
+    number: ["type", "minimum", "maximum"],
+    integer: ["type", "minimum", "maximum"],
+};
+/** 检查 schema 是否落在 ParamSchema 子集内，返回问题列表。 */
+function schemaProblems(schema) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema))
+        return ["schema must be an object"];
+    const s = schema;
+    const allowed = typeof s.type === "string" ? SCHEMA_KEYS[s.type] : undefined;
+    if (!allowed)
+        return [`unsupported schema type ${JSON.stringify(s.type)}`];
+    const out = [];
+    for (const k of Object.keys(s))
+        if (!allowed.includes(k))
+            out.push(`unsupported schema keyword "${k}"`);
+    if ("enum" in s) {
+        if (!Array.isArray(s.enum) || s.enum.length === 0 || s.enum.some((x) => typeof x !== "string"))
+            out.push("enum must be a non-empty array of strings");
+        if ("maxLength" in s)
+            out.push("enum and maxLength cannot be combined");
+    }
+    if ("maxLength" in s && (!Number.isInteger(s.maxLength) || s.maxLength < 0))
+        out.push("maxLength must be a non-negative integer");
+    for (const k of ["minimum", "maximum"]) {
+        if (k in s && (typeof s[k] !== "number" || !Number.isFinite(s[k])))
+            out.push(`${k} must be a finite number`);
+    }
+    if (typeof s.minimum === "number" && typeof s.maximum === "number" && s.minimum > s.maximum)
+        out.push("minimum must be <= maximum");
+    return out;
+}
+const isEnum = (s) => s.type === "string" && "enum" in s;
+/** 校验交互表单的声明，返回问题列表（空 = 合法）。 */
+export function validateInputForm(form) {
+    const out = [];
+    if (!form || !Array.isArray(form.fields))
+        return ["form.fields must be an array"];
+    if (form.fields.length === 0)
+        out.push("form must have at least one field");
+    if (form.url !== undefined && !isHttpUrl(form.url))
+        out.push("url must be an absolute http(s) URL of at most 2000 characters");
+    const seen = new Set();
+    for (const f of form.fields) {
+        const at = `field ${JSON.stringify(f?.key)}`;
+        if (typeof f?.key !== "string" || f.key === "") {
+            out.push("field key must be a non-empty string");
+            continue;
+        }
+        if (seen.has(f.key))
+            out.push(`${at}: duplicate key`);
+        seen.add(f.key);
+        const probs = schemaProblems(f.schema);
+        for (const p of probs)
+            out.push(`${at}: ${p}`);
+        if (probs.length > 0)
+            continue;
+        if ((f.multiSelect || f.allowOther) && !isEnum(f.schema))
+            out.push(`${at}: multiSelect and allowOther require a string enum schema`);
+    }
+    return out;
+}
+/** 校验用户提交的答案是否符合表单，返回问题列表（空 = 合法）。 */
+export function validateAnswer(form, answer) {
+    const out = [];
+    const byKey = new Map(form.fields.map((f) => [f.key, f]));
+    for (const k of Object.keys(answer))
+        if (!byKey.has(k))
+            out.push(`unknown field ${JSON.stringify(k)}`);
+    for (const f of form.fields) {
+        const at = `field ${JSON.stringify(f.key)}`;
+        // 只认答案自身的键：`toString` / `constructor` 等继承属性不算已回答
+        const v = Object.hasOwn(answer, f.key) ? answer[f.key] : undefined;
+        if (v === undefined) {
+            if (f.required)
+                out.push(`${at}: is required`);
+            continue;
+        }
+        if (f.multiSelect) {
+            if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+                out.push(`${at}: must be an array of strings`);
+                continue;
+            }
+            if (f.required && v.length === 0)
+                out.push(`${at}: is required`);
+            const seen = new Set();
+            for (const item of v) {
+                if (seen.has(item)) {
+                    out.push(`${at}: duplicate value ${JSON.stringify(item)}`);
+                    continue;
+                }
+                seen.add(item);
+                const why = otherOrValue(f, item);
+                if (why)
+                    out.push(`${at}: ${why}`);
+            }
+            continue;
+        }
+        if (Array.isArray(v)) {
+            out.push(`${at}: must not be an array`);
+            continue;
+        }
+        if (f.required && v === "") {
+            out.push(`${at}: is required`);
+            continue;
+        }
+        const why = otherOrValue(f, v);
+        if (why)
+            out.push(`${at}: ${why}`);
+    }
+    return out;
+}
+/** allowOther 的枚举字段接受任意非空文本，其余按 schema 校验。 */
+function otherOrValue(f, v) {
+    if (f.allowOther && isEnum(f.schema)) {
+        return typeof v === "string" && v !== "" ? undefined : "other text must be a non-empty string";
+    }
+    return checkParamValue(f.schema, v);
+}

package/dist/ui.d.ts

@@ -0,0 +1,265 @@
+import type { Locale } from "./cards.js";
+import { type FormAnswer, type InputForm } from "./tool.js";
+/**
+ * Where a ui contribution goes (UI refresh spec §5.3):
+ * - `panel`: a right panel of the conversation page, opened from the extension's icon in the title
+ *   bar (one at a time);
+ * - `section`: a section of the conversation's properties panel;
+ * - `inline`: an inline card in the conversation, hanging off a tool result (`ToolResult.card`);
+ * - `page`: an org page under "Extensions";
+ * - `file-preview`: an embed previewer of `file-preview@1` (embed only, see `FilePreviewer.embed`);
+ * - `conversation`: the old right-side tab; it means `panel` (see {@link normalizePlace}).
+ */
+export type UiPlace = "conversation" | "panel" | "section" | "inline" | "page" | "file-preview";
+/** A place with the old `conversation` mapped to `panel`. */
+export declare function normalizePlace(place: UiPlace): Exclude<UiPlace, "conversation">;
+/**
+ * Icons a contribution may use (design system icon names; `puzzle` is the default and is drawn as
+ * the design `extension` icon). The title-bar button of a panel shows it.
+ */
+export declare const UI_ICONS: readonly ["list-checks", "layout-grid", "file", "chart", "calendar", "users", "bot", "book", "message-square", "puzzle"];
+export type UiIcon = (typeof UI_ICONS)[number];
+/**
+ * An "open" target: a `panel` contribution of the same extension, scrolled to the block or item
+ * whose `id` equals `item` (the panel's render receives it as {@link UiRenderArgs.item}).
+ */
+export interface UiOpen {
+    contribution: string;
+    item?: string;
+}
+/** 界面贡献的种类：`view` = 渲染 schema（由我们的组件画）；`embed` = 插件自己的页面放进 iframe。 */
+export type UiKind = "view" | "embed";
+/**
+ * 插件清单 `ui` 里的一项界面贡献。`id` 必须同时出现在 `permissions.ui.views`（kind view）
+ * 或 `permissions.ui.embeds`（kind embed）里；`embed` 的页面由插件路由提供。
+ */
+export interface UiContribution {
+    id: string;
+    title: {
+        zh: string;
+        en: string;
+    };
+    place: UiPlace;
+    kind: UiKind;
+    /** 仅 embed：插件路由下 `/ui/` 开头的路径，须在 `permissions.http` 中声明为 GET。 */
+    path?: string;
+    /** Icon from {@link UI_ICONS}; default `puzzle`. */
+    icon?: UiIcon;
+    /**
+     * A retired id kept answering for a release: it is not listed, and fetching it renders (or
+     * embeds) the named contribution of the same extension and kind. It still needs its entry in
+     * `permissions.ui`, and no `ctx.ui.view` of its own.
+     */
+    aliasOf?: string;
+}
+/**
+ * 渲染 schema 的块。文本是给人看的、按原样展示（插件自行决定语言，通常取 `locale`）。
+ * `text.markdown` 不支持原生 HTML，链接只允许 http(s) 绝对地址。
+ */
+export type UiBlock = {
+    type: "heading";
+    text: string;
+} | {
+    type: "text";
+    markdown: string;
+} | {
+    type: "checklist";
+    items: {
+        text: string;
+        status: "pending" | "in_progress" | "completed";
+        /** Anchor for an open target's `item`. */
+        id?: string;
+        open?: UiOpen;
+    }[];
+} | {
+    type: "keyValue";
+    items: {
+        label: string;
+        value: string;
+        id?: string;
+        open?: UiOpen;
+    }[];
+} | {
+    type: "table";
+    columns: {
+        key: string;
+        label: string;
+    }[];
+    /**
+     * 每行按列 key 取单元格，可以缺列。渲染时用 `Object.hasOwn(row, key)` 判断单元格是否存在，
+     * 不要用 `row[key]` 或 `in`：列 key 可能是 `constructor` / `toString` 之类，会取到原型链上的值。
+     */
+    rows: Record<string, string>[];
+    /** Per row (same index), an open target or null; never a key inside a row. */
+    open?: (UiOpen | null)[];
+} | {
+    type: "code";
+    language?: string;
+    text: string;
+} | {
+    type: "image";
+    url: string;
+    alt: string;
+} | {
+    type: "chart";
+    kind: "bar" | "line";
+    series: {
+        label: string;
+        value: number;
+    }[];
+} | {
+    type: "actions";
+    buttons: {
+        actionId: string;
+        label: string;
+        payload?: unknown;
+        danger?: boolean;
+    }[];
+} | {
+    type: "form";
+    form: InputForm;
+    actionId: string;
+    submitLabel: string;
+};
+/** 插件视图：有上限的块列表；`badge` 显示在标签上（如「2/4」）。 */
+export interface UiView {
+    badge?: string;
+    /** The ⤢ of an inline card's title row and a properties section's header. */
+    open?: UiOpen;
+    blocks: UiBlock[];
+}
+/**
+ * 视图上限（{@link validateUiView} 统一检查）：
+ * - `blocks`：块数；
+ * - `tableRows`：表格行数，也用作 keyValue 项数、表格列数、图表点数、按钮数的上限；
+ * - `checklistItems`：清单项数；
+ * - `textChars`：整个视图所有文本（含表单 JSON）的字符总数；
+ * - `payloadBytes`：单个按钮 `payload` 的 JSON 序列化后 UTF-8 字节数。
+ */
+export declare const UI_LIMITS: {
+    readonly blocks: 50;
+    readonly tableRows: 200;
+    readonly checklistItems: 100;
+    readonly textChars: 20000;
+    readonly payloadBytes: 2000;
+};
+/**
+ * 校验插件返回的视图，返回问题列表（空 = 合法）。链接与图片只允许 http(s) 绝对地址；
+ * Markdown 的检查是纵深防御，网页渲染时仍须只认 http(s) 链接、不渲染原生 HTML。
+ * 按钮与表单的 `actionId` 在整个视图内唯一（动作回调靠它区分来源）。
+ */
+export declare function validateUiView(v: unknown): string[];
+/**
+ * 调用者在组织内的角色（由高到低 owner / admin / member / guest）。`place: "page"` 的贡献只给 member 以上
+ * （内核对 guest 返回 404，插件收不到 guest 的组织页面请求）；对话位置的贡献给能访问该对话的任何角色。
+ */
+export type UiRole = "owner" | "admin" | "member" | "guest";
+/** 内核调用插件 `render` 时传入的参数（身份由内核鉴权后给出，插件拿不到用户的会话凭据）。 */
+export interface UiRenderArgs {
+    orgId: string;
+    accountId: string;
+    /** 调用者此刻在 `orgId` 的角色（内核按成员关系填，插件可据此收紧按钮等，见 {@link UiRole}）。 */
+    role: UiRole;
+    /** 仅对话视图。 */
+    conversationId?: string;
+    locale: Locale;
+    signal: AbortSignal;
+    /** A panel opened from an open target: the block or item `id` to scroll to. */
+    item?: string;
+    /**
+     * An inline card: the tool call it hangs off and the `key` from `ToolResult.card`. Attested by the
+     * kernel: given only to an `inline` view, and only when a `tool_result` of `conversationId`
+     * recorded this very card (same extension, view and key); scope lookups by `conversationId` too.
+     */
+    card?: {
+        callId: string;
+        key?: string;
+    };
+}
+/** 视图里的按钮或表单提交：`actionId` 来自块；表单提交时带 `answer`。 */
+export interface UiActionArgs extends UiRenderArgs {
+    actionId: string;
+    payload?: unknown;
+    answer?: FormAnswer;
+}
+/** 动作结果：一条提示，或一份新的视图。 */
+export type UiActionResult = {
+    toast?: {
+        zh: string;
+        en: string;
+    };
+} | {
+    view: UiView;
+};
+/** 嵌入令牌里的声明（经 `ctx.ui.verifyEmbedToken` 校验后可信）。`exp` 为 Unix 秒。 */
+export interface EmbedClaims {
+    plugin: string;
+    orgId: string;
+    accountId: string;
+    /** 调用者的角色：签发时写入；`ctx.ui.verifyEmbedToken` 返回校验时刻的当前角色。 */
+    role: UiRole;
+    conversationId?: string;
+    /** Only a `file-preview` embed's token: the one file (of `conversationId`) it previews. */
+    fileId?: string;
+    contribution: string;
+    exp: number;
+}
+/** 外层页面与嵌入 iframe 之间 `postMessage` 协议的版本标识。 */
+export declare const EMBED_PROTOCOL = "capybara-embed/1";
+/** 外层页面发给 iframe 的消息。 */
+export type EmbedParentMessage = {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "init";
+    token: string;
+    locale: Locale;
+    theme: "dark" | "light";
+    tokens: Record<string, string>;
+    context: {
+        orgId: string;
+        conversationId?: string;
+    };
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "token";
+    token: string;
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "theme";
+    theme: "dark" | "light";
+    tokens: Record<string, string>;
+}
+/**
+ * Only to a `file-preview` embed, once, after `init`: the file being previewed. The embed never
+ * gets a URL for it.
+ */
+ | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "file";
+    name: string;
+    contentType: string;
+    size: number;
+    data: ArrayBuffer;
+};
+/** iframe 发给外层页面的消息。 */
+export type EmbedChildMessage = 
+/** 高度为 CSS 像素，0–10000。 */
+{
+    protocol: typeof EMBED_PROTOCOL;
+    type: "resize";
+    height: number;
+}
+/** 只允许站内路径：单个 `/` 开头、没有 `//`、没有 `.` / `..` 段（含 `%2e` 编码）、规范化后不变。 */
+ | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "navigate";
+    path: string;
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "toast";
+    text: string;
+};
+/**
+ * 解析 iframe 发来的消息：协议、类型、字段都对才返回（只留已知字段的新对象），否则返回 null。
+ * 外层页面还须先核对消息来源是这个 iframe。
+ */
+export declare function parseEmbedChildMessage(m: unknown): EmbedChildMessage | null;