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

package/dist/skill.js

@@ -0,0 +1,244 @@
+/**
+ * 技能（Agent Skills 格式）的纯解析与校验函数：内核上传技能包、agent 提议技能改动时都用它们。
+ *
+ * 格式依据（2026-10-21 核实）：
+ * - Agent Skills 规范 https://agentskills.io/specification ：`name` 必填，1–64 个字符，只能是小写字母、数字与
+ *   连字符，不能以连字符开头或结尾，不能有连续连字符，须与所在目录同名；`description` 必填，1–1024 个字符；
+ *   可选 `license`、`compatibility`（1–500 个字符）、`metadata`、`allowed-tools`。
+ * - Anthropic 文档 https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ：
+ *   `name` 与 `description` 不能含 XML 标签（另有保留词 "anthropic" / "claude"，那是 Anthropic 平台自己的规则，
+ *   这里不采用）。
+ *
+ * Choices: the description goes into the model's system prompt, so XML tags are refused as Anthropic
+ * does (no forged prompt structure). Keys outside the specification are allowed and ignored, so
+ * existing packages upload unchanged, except Claude Code's invocation keys
+ * (`disable-model-invocation`, `user-invocable`, `context`, `agent`, `argument-hint`, `arguments`),
+ * whose types are checked because the kernel uses them (`skillInvocation`, phase D). Matching the
+ * directory name is not enforced: an uploaded zip's outer directory often has another name (GitHub's
+ * `repo-main/`); the skill's name is always the frontmatter `name`, and its sandbox directory is
+ * `/skills/<name>/`.
+ */
+import { readFrontmatter } from "./frontmatter.js";
+import { hasControlChars } from "./model.js";
+import { validateSandboxPath } from "./sandbox.js";
+import { argumentHintText, SKILL_ARGUMENT_NAME_RE } from "./skill-keys.js";
+/** 技能包的上限。 */
+export const SKILL_LIMITS = {
+    nameMaxChars: 64,
+    descriptionMaxChars: 1024,
+    compatibilityMaxChars: 500,
+    /** 单个文件解压后的上限（字节）。 */
+    fileBytes: 10 * 1024 * 1024,
+    /** 全部文件解压后的总量上限（字节）。 */
+    totalBytes: 50 * 1024 * 1024,
+    /** 文件数上限。 */
+    maxFiles: 1000,
+    /** 包内相对路径的长度上限（字符）。 */
+    pathMaxChars: 512,
+    /** frontmatter（两条 `---` 之间）的长度上限（字符），超过不做 YAML 解析。 */
+    frontmatterMaxChars: 64 * 1024,
+};
+/** Limits of the invocation keys of a SKILL.md (see `SkillInvocation`). */
+export const SKILL_INVOCATION_LIMITS = {
+    /** `argument-hint`, in characters. */
+    argumentHintMaxChars: 200,
+    /** Names in `arguments`. */
+    argumentNames: 20,
+    /** The argument string of one invocation, in characters (after trimming). */
+    argumentsMaxChars: 10_000,
+    /**
+     * The rendered body of one invocation (substitutions and the `ARGUMENTS:` line), in UTF-16 code
+     * units: placeholders copy the arguments again for every occurrence, so this bounds the output.
+     */
+    renderedMaxChars: 200_000,
+};
+/** 技能入口文件（包根目录，大小写敏感）。 */
+export const SKILL_ENTRY_FILE = "SKILL.md";
+/** 沙箱里放技能的根目录：每个技能在 `/skills/<name>/` 下（只读复制）。 */
+export const SKILLS_SANDBOX_ROOT = "/skills";
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const XML_TAG_RE = /<\/?[A-Za-z][^<>]*>/;
+const DRIVE_RE = /^[A-Za-z]:/;
+/** 是否为合法的技能名（见文件头的规范说明）。 */
+export function isSkillName(s) {
+    return typeof s === "string" && s.length <= SKILL_LIMITS.nameMaxChars && NAME_RE.test(s);
+}
+/** 技能文件在沙箱里的路径：`/skills/<name>/<path>`。 */
+export function skillSandboxPath(name, path) {
+    return `${SKILLS_SANDBOX_ROOT}/${name}/${path}`;
+}
+const chars = (s) => [...s].length;
+/**
+ * 解析 SKILL.md：开头是 `---` 行包住的 YAML frontmatter，之后是正文。容忍 BOM 与 CRLF（正文里的 CRLF 换成 LF）。
+ * 返回 name / description / 正文，或全部问题（英文，可直接给模型或管理员看）。
+ */
+export function parseSkillMd(text, options = {}) {
+    const read = readFrontmatter(text, "SKILL.md", SKILL_LIMITS.frontmatterMaxChars);
+    if ("errors" in read)
+        return read;
+    const { frontmatter: fm, body } = read;
+    const errors = [];
+    const name = fm.name;
+    if (name === undefined || name === null)
+        errors.push("name is required");
+    else if (typeof name !== "string")
+        errors.push("name must be a string");
+    else if (!isSkillName(name)) {
+        errors.push("name must be 1-64 lowercase letters, digits and single hyphens, not starting or ending with a hyphen");
+    }
+    const rawDesc = fm.description;
+    let description = "";
+    if (rawDesc === undefined || rawDesc === null)
+        errors.push("description is required");
+    else if (typeof rawDesc !== "string")
+        errors.push("description must be a string");
+    else {
+        description = rawDesc.trim();
+        if (description === "")
+            errors.push("description must not be empty");
+        else if (chars(description) > SKILL_LIMITS.descriptionMaxChars) {
+            errors.push(`description must be at most ${SKILL_LIMITS.descriptionMaxChars} characters`);
+        }
+        else if (XML_TAG_RE.test(description)) {
+            errors.push("description must not contain XML tags");
+        }
+    }
+    const compat = fm.compatibility;
+    if (compat !== undefined &&
+        (typeof compat !== "string" ||
+            compat.length === 0 ||
+            chars(compat) > SKILL_LIMITS.compatibilityMaxChars)) {
+        errors.push(`compatibility must be a string of 1-${SKILL_LIMITS.compatibilityMaxChars} characters`);
+    }
+    if (options.invocationKeys !== false)
+        errors.push(...invocationKeyErrors(fm));
+    if (errors.length > 0)
+        return { errors };
+    return { name: name, description, body, frontmatter: fm };
+}
+const AGENT_MAX_CHARS = 130;
+/** The type errors of the invocation keys (`disable-model-invocation`, `context`, ...). */
+function invocationKeyErrors(fm) {
+    const errors = [];
+    const dmi = fm["disable-model-invocation"];
+    if (dmi !== undefined && typeof dmi !== "boolean") {
+        errors.push("disable-model-invocation must be a boolean");
+    }
+    const ui = fm["user-invocable"];
+    if (ui !== undefined && typeof ui !== "boolean")
+        errors.push("user-invocable must be a boolean");
+    if (fm.context !== undefined && fm.context !== "fork")
+        errors.push('context must be "fork"');
+    const agent = fm.agent;
+    if (agent !== undefined &&
+        (typeof agent !== "string" || agent === "" || chars(agent) > AGENT_MAX_CHARS)) {
+        errors.push(`agent must be a string of 1-${AGENT_MAX_CHARS} characters`);
+    }
+    const hint = fm["argument-hint"];
+    if (hint !== undefined) {
+        const text = argumentHintText(hint);
+        if (text === undefined || chars(text) > SKILL_INVOCATION_LIMITS.argumentHintMaxChars) {
+            errors.push(`argument-hint must be a string of at most ${SKILL_INVOCATION_LIMITS.argumentHintMaxChars} characters`);
+        }
+    }
+    const names = fm.arguments;
+    if (names !== undefined &&
+        (!Array.isArray(names) ||
+            names.length > SKILL_INVOCATION_LIMITS.argumentNames ||
+            !names.every((n) => typeof n === "string" && SKILL_ARGUMENT_NAME_RE.test(n)))) {
+        errors.push(`arguments must be a list of at most ${SKILL_INVOCATION_LIMITS.argumentNames} names`);
+    }
+    if (dmi === true && ui === false) {
+        errors.push("a skill with disable-model-invocation: true and user-invocable: false cannot be used");
+    }
+    return errors;
+}
+/** 给人看的路径：含控制字符时用 JSON 转义。 */
+const show = (p) => (hasControlChars(p) || p === "" ? JSON.stringify(p) : p);
+/** 单个相对路径的问题（第一个），合法时为 null。 */
+function pathProblem(p) {
+    if (typeof p !== "string" || p === "")
+        return "path must be a non-empty string";
+    if (chars(p) > SKILL_LIMITS.pathMaxChars) {
+        return `path must be at most ${SKILL_LIMITS.pathMaxChars} characters`;
+    }
+    if (hasControlChars(p))
+        return "path must not contain control characters";
+    if (p.includes("\\"))
+        return "path must not contain backslashes";
+    if (p.startsWith("/"))
+        return "path must be relative";
+    if (DRIVE_RE.test(p))
+        return "path must not start with a drive letter";
+    if (p.endsWith("/"))
+        return "path must name a file, not a directory";
+    for (const seg of p.split("/")) {
+        if (seg === "")
+            return "path must not contain empty segments";
+        if (seg === "." || seg === "..")
+            return "path must not contain '.' or '..' segments";
+    }
+    // 再按沙箱路径规则核一遍（百分号编码的 `..` 等）
+    const errs = validateSandboxPath(skillSandboxPath("skill", p));
+    return errs[0] ?? null;
+}
+/**
+ * 校验技能包的文件清单（路径相对于包根目录，只含文件、不含目录项）：
+ * 根目录必须有 `SKILL.md`；单文件 ≤ {@link SKILL_LIMITS.fileBytes}；总量 ≤ {@link SKILL_LIMITS.totalBytes}；
+ * 文件数 ≤ {@link SKILL_LIMITS.maxFiles}；路径不能越界（绝对路径、`..`、反斜杠、盘符、控制字符），不能重复
+ * （只差大小写也算重复：大小写不敏感的文件系统上会互相覆盖），文件不能与目录同名。返回问题列表，空数组表示合法。
+ */
+export function validateSkillPackage(files) {
+    if (files.length > SKILL_LIMITS.maxFiles) {
+        return [`package has more than ${SKILL_LIMITS.maxFiles} files`];
+    }
+    const errors = [];
+    if (!files.some((f) => f.path === SKILL_ENTRY_FILE)) {
+        errors.push(`${SKILL_ENTRY_FILE} is required at the root`);
+    }
+    const exact = new Set();
+    const folded = new Set();
+    const fileKeys = new Set();
+    const dirKeys = new Set();
+    let total = 0;
+    for (const f of files) {
+        const p = f.path;
+        const problem = pathProblem(p);
+        if (problem) {
+            errors.push(`${show(String(p))}: ${problem}`);
+            continue;
+        }
+        if (!Number.isSafeInteger(f.size) || f.size < 0) {
+            errors.push(`${show(p)}: size must be a non-negative integer`);
+            continue;
+        }
+        if (f.size > SKILL_LIMITS.fileBytes) {
+            errors.push(`${show(p)}: file is larger than ${SKILL_LIMITS.fileBytes} bytes`);
+        }
+        total += f.size;
+        const key = p.normalize("NFC").toLowerCase();
+        if (exact.has(p)) {
+            errors.push(`${show(p)}: duplicate path`);
+            continue;
+        }
+        exact.add(p);
+        if (folded.has(key)) {
+            errors.push(`${show(p)}: duplicate path (paths differ only in letter case)`);
+            continue;
+        }
+        folded.add(key);
+        const segs = key.split("/");
+        const parents = segs.slice(0, -1).map((_, i) => segs.slice(0, i + 1).join("/"));
+        if (dirKeys.has(key) || parents.some((d) => fileKeys.has(d))) {
+            errors.push(`${show(p)}: a file and a directory have the same path`);
+            continue;
+        }
+        fileKeys.add(key);
+        for (const d of parents)
+            dirKeys.add(d);
+    }
+    if (total > SKILL_LIMITS.totalBytes) {
+        errors.push(`package is larger than ${SKILL_LIMITS.totalBytes} bytes in total`);
+    }
+    return errors;
+}

package/dist/storage.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Object storage contract `object-store@1`: a single-select, brokered extension point (extensions
+ * may not `requires` it; they use it through `ctx.storage`). The provider implements
+ * {@link ObjectStore}; the `ctx.storage` an extension gets ({@link ExtensionStorage}) is wrapped by
+ * the kernel: every method takes a leading `orgId`, and keys get the prefix
+ * `plugins/<extension name>/<orgId>/`.
+ */
+/** Object storage extension point ref. */
+export declare const OBJECT_STORE_EXTENSION_POINT = "object-store@1";
+/** 对象的元数据。 */
+export interface ObjectHead {
+    key: string;
+    /** 字节数。 */
+    size: number;
+    contentType: string;
+    etag?: string;
+    /** ISO 8601 时间。 */
+    lastModified?: string;
+}
+/** `object-store@1` 的实现（由对象存储插件提供，如 S3 兼容存储）。 */
+export interface ObjectStore {
+    /** 写入（覆盖同名键）；`body` 是流时最好给出 `size`。 */
+    put(key: string, body: Uint8Array | ReadableStream<Uint8Array>, opts: {
+        contentType: string;
+        size?: number;
+        signal?: AbortSignal;
+    }): Promise<ObjectHead>;
+    /**
+     * 读取；不存在返回 null。`range` 为闭区间字节范围，缺省 `end` 表示读到末尾。
+     * 带 `range` 时 `head.size` 仍是整个对象的大小；存储忽略 Range 时 body 可能是整个对象。
+     */
+    get(key: string, opts?: {
+        signal?: AbortSignal;
+        range?: {
+            start: number;
+            end?: number;
+        };
+    }): Promise<{
+        head: ObjectHead;
+        body: ReadableStream<Uint8Array>;
+    } | null>;
+    /** 不存在返回 null。 */
+    head(key: string): Promise<ObjectHead | null>;
+    /** 删除；不存在也算成功。 */
+    delete(key: string): Promise<void>;
+    /** 删除前缀下的全部对象，返回删除数（用于组织数据删除）。 */
+    deletePrefix(prefix: string): Promise<number>;
+    /**
+     * 分页列举前缀下的对象；返回的 `cursor` 缺省表示没有下一页。列举结果不带类型时 `contentType` 为空串
+     * （需要时用 `head` 取）。
+     */
+    list(prefix: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: ObjectHead[];
+        cursor?: string;
+    }>;
+    /** 预签名下载 URL（选项见 {@link PresignGetOptions}）。 */
+    presignGet(key: string, opts: PresignGetOptions): Promise<string>;
+    /**
+     * 预签名上传：浏览器按返回的 {@link PresignedUpload} 直传存储。超过 `maxSize` 的上传必须由**存储端**拒绝
+     * （预签名 PUT 无法限制大小，所以 S3 兼容实现用带 `content-length-range` 条件的 POST 策略）。
+     */
+    presignPut(key: string, opts: {
+        contentType: string;
+        maxSize: number;
+        ttlSeconds: number;
+    }): Promise<PresignedUpload>;
+}
+/** 预签名下载的选项。 */
+export interface PresignGetOptions {
+    ttlSeconds: number;
+    /** 下载文件名，进 `Content-Disposition`（RFC 6266，非 ASCII 用 `filename*=UTF-8''…`）。 */
+    downloadName?: string;
+    /**
+     * 浏览器打开方式：`attachment`（缺省，下载）或 `inline`（在页面里显示）。用户上传的内容只应对
+     * 不会执行脚本的类型（图片、PDF）用 `inline`。
+     */
+    disposition?: "attachment" | "inline";
+    /** 覆盖响应的 `Content-Type`（如按核对过的类型返回，而不是存储里记的类型）。 */
+    responseContentType?: string;
+}
+/**
+ * 预签名上传的请求方式：
+ * - `PUT`：请求体就是文件字节，请求头带上 `headers`；
+ * - `POST`：`multipart/form-data` 表单，先按原样放入 `fields` 的每一项，**最后**放文件字段 `file`；
+ *   请求头带上 `headers`（通常为空）。
+ */
+export interface PresignedUpload {
+    method: "PUT" | "POST";
+    url: string;
+    headers: Record<string, string>;
+    /** `POST` 时必有：表单字段（含策略与签名）。 */
+    fields?: Record<string, string>;
+}

package/dist/storage.js

@@ -0,0 +1,9 @@
+/**
+ * Object storage contract `object-store@1`: a single-select, brokered extension point (extensions
+ * may not `requires` it; they use it through `ctx.storage`). The provider implements
+ * {@link ObjectStore}; the `ctx.storage` an extension gets ({@link ExtensionStorage}) is wrapped by
+ * the kernel: every method takes a leading `orgId`, and keys get the prefix
+ * `plugins/<extension name>/<orgId>/`.
+ */
+/** Object storage extension point ref. */
+export const OBJECT_STORE_EXTENSION_POINT = "object-store@1";

package/dist/tool.d.ts

@@ -0,0 +1,154 @@
+import { type ParamSchema } from "./model-params.js";
+/** 工具注解（与 MCP 对齐的提示，用于推导默认策略）。 */
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    requiresUserInteraction?: boolean;
+}
+export interface ToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: ToolAnnotations;
+    /** 仅插件 / 内置工具可声明；缺省按注解推导。 */
+    defaultPolicy?: "allow" | "ask";
+    /**
+     * 仅连接器工具：连接器自己的不透明数据（如 OpenAPI 的方法、路径模板、参数位置、服务器地址），可 JSON 序列化。
+     * 内核把它与定义一起存进快照并计入指纹（变了即漂移、需复核），调用时经 `callTool` 的 `ctx.spec` 原样交回；
+     * 绝不发给模型。
+     */
+    connectorData?: Record<string, unknown>;
+    /**
+     * Display only: a short human title shown on the tool's row instead of its key, e.g. the MCP
+     * `title` ("Search messages"); 1–80 characters, one line, with no control, bidi or invisible
+     * characters (Unicode Cc / Cf). Never sent to the model and not part of the definition
+     * fingerprint, so adding or changing it never triggers drift review.
+     */
+    title?: string;
+    /**
+     * Display only: up to 3 input property names whose values the tool's row shows, in order, e.g.
+     * `["query", "channel"]`. Each must be a property of `inputSchema.properties`. Never sent to the
+     * model and not part of the definition fingerprint.
+     */
+    keyArgs?: string[];
+}
+/** Longest {@link ToolSpec.title}, in code points. */
+export declare const TOOL_TITLE_MAX = 80;
+/** Most {@link ToolSpec.keyArgs}. */
+export declare const TOOL_KEY_ARGS_MAX = 3;
+/**
+ * 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 declare function validateToolPresentation(spec: Pick<ToolSpec, "title" | "keyArgs" | "inputSchema">): string[];
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    mimeType: string;
+    data: string;
+} | {
+    type: "resource_link";
+    uri: string;
+    name?: string;
+    mimeType?: string;
+};
+/** 工具调用的一句话说明，给界面显示（中英文各 ≤ 200 字符）；不进模型上下文。 */
+export interface ToolDisplay {
+    summary: {
+        zh: string;
+        en: string;
+    };
+}
+export interface ToolResult {
+    content: ToolContent[];
+    isError?: boolean;
+    /** 可选：对话流里显示这句说明，代替原样的输入 JSON。 */
+    display?: ToolDisplay;
+    /**
+     * Optional: an inline card under this call in the conversation: `view` is a ui contribution of
+     * the same extension with `place: "inline"`, rendered with `card: { callId, key }`. Display only
+     * (recorded on the `tool_result` event, never in the model's context); an unknown view is dropped
+     * with a warning and the result is kept.
+     */
+    card?: {
+        view: string;
+        key?: string;
+    };
+}
+/** 校验 {@link ToolDisplay}，返回问题列表（空 = 合法）；长度按 Unicode 码点计。 */
+export declare function validateToolDisplay(d: unknown): string[];
+/** Text shown to people: bilingual (`zh` / `en`) or a single string shown as is. */
+export type LocalizedText = {
+    zh: string;
+    en: string;
+} | string;
+/** 交互表单：字段的 schema 只用 M2 的 ParamSchema 子集；枚举字段可设 multiSelect 与 allowOther。 */
+export interface InputForm {
+    /** 插件可给双语；内核内置工具给英文（模型生成的问题原样展示）。 */
+    title: LocalizedText;
+    /**
+     * 可选：需要用户在浏览器里打开的外部页面（如 MCP URL 模式的 elicitation：去对方页面授权 / 付款 / 填敏感信息）。
+     * 界面把它显示为链接（完整地址可见）；只接受 http(s) 绝对地址、≤ 2000 字符。
+     */
+    url?: string;
+    fields: {
+        key: string;
+        label: LocalizedText;
+        description?: LocalizedText;
+        schema: ParamSchema;
+        multiSelect?: boolean;
+        allowOther?: boolean;
+        required?: boolean;
+    }[];
+}
+/**
+ * 工具需要用户输入：内核暂停运行、渲染表单；用户提交后用同一 input 再次调用该工具，
+ * 并在 ctx.resume 中带回 state 与 answer。state ≤ 16 KB，可 JSON 序列化。
+ */
+export interface InputRequired {
+    kind: "input_required";
+    form: InputForm;
+    state?: unknown;
+}
+export type FormAnswer = Record<string, string | number | boolean | string[]>;
+export interface ToolCallContext {
+    orgId: string;
+    accountId: string;
+    agentId: string;
+    conversationId: string;
+    callId: string;
+    signal: AbortSignal;
+    /** null = 用户取消或超时。 */
+    resume?: {
+        state: unknown;
+        answer: FormAnswer | null;
+    };
+}
+export type ToolHandler = (input: unknown, ctx: ToolCallContext) => Promise<ToolResult | InputRequired>;
+/**
+ * 工具错误的类别：
+ * - `error`（缺省）：远端可用、但这次调用失败（参数不对、业务错误、鉴权失败等），不计入连接器熔断；
+ * - `unavailable`：远端不可用（连接 / 传输错误、超时、HTTP 5xx），计入连接器熔断（连接器用它告诉内核）。
+ */
+export type ToolErrorKind = "error" | "unavailable";
+/** 工具执行失败：message 给模型看，须为英文且可操作。 */
+export declare class ToolError extends Error {
+    readonly kind: ToolErrorKind;
+    constructor(message: string, opts?: {
+        kind?: ToolErrorKind;
+    });
+}
+/** 插件工具名规则。 */
+export declare const EXTENSION_TOOL_NAME: RegExp;
+/** 校验插件注册的工具声明，返回问题列表（空 = 合法）。 */
+export declare function validateToolSpec(spec: ToolSpec): string[];
+/** 校验交互表单的声明，返回问题列表（空 = 合法）。 */
+export declare function validateInputForm(form: InputForm): string[];
+/** 校验用户提交的答案是否符合表单，返回问题列表（空 = 合法）。 */
+export declare function validateAnswer(form: InputForm, answer: FormAnswer): string[];