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

package/dist/marketplace.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { CATALOG_ITEM_NAME_RE, isSafePackagePath, NPM_PACKAGE_NAME_RE, SEMVER_VERSION_RE, SHA512_INTEGRITY_RE, } from "./plugin-package.js";
+/**
+ * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
+ * each with one source. One entry is one version: a marketplace that offers several versions lists
+ * the plugin once per version, so `(name, marketplaceEntryVersion)` is unique in a manifest.
+ *
+ * Sources: a same-repo `path`, a `git` repo, an `npm` package (exact version + sha512, downloads
+ * are verified against it, never npm metadata) or an `archive` URL (sha512 or sha256 SRI).
+ *
+ * The committed JSON Schema (`schemas/marketplace.v1.schema.json`) is generated from
+ * {@link MarketplaceManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
+ * `check:package-schemas`. Cross-field rules (unique `(name, version)`, `version` equal to the npm
+ * source's, `sensitive` ⊆ `keys`) are decided only by {@link parseMarketplaceManifest}. Unknown
+ * fields are dropped (forward compatible: a newer manifest does not make an older kernel reject it).
+ */
+/** Manifest format version. */
+export const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
+/** Limits of the marketplace manifest. */
+export const MARKETPLACE_LIMITS = {
+    nameChars: 100,
+    summaryChars: 280,
+    plugins: 5000,
+    permissionKeys: 500,
+    urlChars: 2000,
+};
+const M = MARKETPLACE_LIMITS;
+const MAX_ERRORS = 50;
+/** Kernel permission key format: `<category>[:<value>]`, the category lowercase letters and dots. */
+const PERMISSION_KEY_RE = /^[a-z][a-z.]{0,62}(?::[^\r\n]{1,256})?$/;
+const SHA256_INTEGRITY_RE = /^sha256-[A-Za-z0-9+/]{43}=$/;
+const COMMIT_RE = /^[0-9a-f]{40}$/;
+const HTTPS_URL_RE = /^https:\/\/\S+$/;
+const HTTPS_OR_LOOPBACK_RE = /^(?:https:\/\/\S+|http:\/\/(?:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\])(?::\d{1,5})?(?:\/\S*)?)$/;
+const urlString = (re) => z
+    .string()
+    .max(M.urlChars)
+    .regex(re, { message: "must be an https URL" })
+    .refine((s) => {
+    try {
+        new URL(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "must be a valid URL" });
+const exactVersion = (what) => z
+    .string()
+    .max(256)
+    .regex(SEMVER_VERSION_RE, { message: `${what} must be an exact semver version` });
+/** `./<safe path>` inside the marketplace repo. */
+const repoPath = z
+    .string()
+    .max(512)
+    .refine((p) => p.startsWith("./") && isSafePackagePath(p.slice(2)), {
+    message: 'path must start with "./" and stay inside the repository',
+});
+/** A path inside a git repo: `.` (the root) or a safe relative path with an optional `./`. */
+const gitPath = z
+    .string()
+    .max(512)
+    .refine((p) => p === "." || isSafePackagePath(p.replace(/^\.\//, "")), {
+    message: "path must be . or a relative path inside the repository",
+});
+function buildSchema(opts) {
+    const url = urlString(opts.allowInsecureLoopback ? HTTPS_OR_LOOPBACK_RE : HTTPS_URL_RE);
+    const none = z.never().optional();
+    // Exactly one form: each object declares the other forms' keys as absent.
+    const source = z.union([
+        z.object({ path: repoPath, git: none, npm: none, archive: none }),
+        z.object({
+            git: z.object({
+                url,
+                ref: z.string().min(1).max(256).optional(),
+                commit: z
+                    .string()
+                    .regex(COMMIT_RE, { message: "commit must be 40 hex characters" })
+                    .optional(),
+                path: gitPath.optional(),
+            }),
+            path: none,
+            npm: none,
+            archive: none,
+        }),
+        z.object({
+            npm: z.object({
+                package: z
+                    .string()
+                    .max(214)
+                    .regex(NPM_PACKAGE_NAME_RE, { message: "package must be an npm package name" }),
+                version: exactVersion("version"),
+                integrity: z
+                    .string()
+                    .regex(SHA512_INTEGRITY_RE, { message: "integrity must be sha512-<86 base64 chars>==" }),
+            }),
+            path: none,
+            git: none,
+            archive: none,
+        }),
+        z.object({
+            archive: z.object({
+                url,
+                integrity: z
+                    .string()
+                    .refine((s) => SHA512_INTEGRITY_RE.test(s) || SHA256_INTEGRITY_RE.test(s), {
+                    message: "integrity must be a sha512- or sha256- SRI",
+                }),
+            }),
+            path: none,
+            git: none,
+            npm: none,
+        }),
+    ]);
+    const permissionKey = z.string().max(300).regex(PERMISSION_KEY_RE, {
+        message: "must be a permission key (<category>[:<value>])",
+    });
+    const entry = z.object({
+        name: z
+            .string()
+            .regex(CATALOG_ITEM_NAME_RE, { message: "name must match ^[a-z0-9][a-z0-9-]{0,63}$" }),
+        summary: z.object({
+            en: z.string().min(1).max(M.summaryChars),
+            zh: z.string().min(1).max(M.summaryChars).optional(),
+        }),
+        version: exactVersion("version").optional(),
+        minKernel: exactVersion("minKernel").optional(),
+        permissions: z
+            .object({
+            keys: z.array(permissionKey).max(M.permissionKeys),
+            sensitive: z.array(permissionKey).max(M.permissionKeys),
+        })
+            .optional(),
+        homepage: urlString(HTTPS_URL_RE).optional(),
+        source,
+    });
+    return z
+        .object({
+        $schema: z.string().max(M.urlChars).optional(),
+        schemaVersion: z.literal(MARKETPLACE_MANIFEST_SCHEMA_VERSION),
+        name: z.string().min(1).max(M.nameChars),
+        owner: z
+            .object({
+            name: z.string().min(1).max(M.nameChars),
+            url: urlString(HTTPS_URL_RE).optional(),
+        })
+            .optional(),
+        description: z.string().min(1).max(1024).optional(),
+        plugins: z.array(entry).max(M.plugins),
+    })
+        .superRefine((m, ctx) => {
+        const seen = new Set();
+        m.plugins.forEach((raw, i) => {
+            const e = raw;
+            const v = marketplaceEntryVersion(e);
+            const key = `${e.name} ${v ?? "(no version)"}`;
+            if (seen.has(key)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["plugins", i, "name"],
+                    message: `duplicate entry ${key}`,
+                });
+            }
+            seen.add(key);
+            if ("npm" in e.source &&
+                e.source.npm &&
+                e.version !== undefined &&
+                e.version !== e.source.npm.version) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["plugins", i, "version"],
+                    message: `version ${e.version} must equal source.npm.version ${e.source.npm.version}`,
+                });
+            }
+            if (e.permissions) {
+                const keys = new Set(e.permissions.keys);
+                for (const s of e.permissions.sensitive) {
+                    if (!keys.has(s)) {
+                        ctx.addIssue({
+                            code: "custom",
+                            path: ["plugins", i, "permissions", "sensitive"],
+                            message: `sensitive key "${s}" is not in keys`,
+                        });
+                    }
+                }
+            }
+        });
+    });
+}
+/**
+ * The zod schema of `marketplace.json` (https only; non-strict: unknown fields dropped). The JSON
+ * Schema is generated with `z.toJSONSchema(MarketplaceManifestSchema, { io: "input" })`.
+ */
+export const MarketplaceManifestSchema = buildSchema({});
+const LOOPBACK_SCHEMA = buildSchema({
+    allowInsecureLoopback: true,
+});
+/** Strips the absent-form keys zod leaves as `undefined` on the parsed source. */
+function cleanSource(s) {
+    return Object.fromEntries(Object.entries(s).filter(([, v]) => v !== undefined));
+}
+/**
+ * Validates and parses `marketplace.json` (unknown fields dropped). Invalid input returns
+ * `{ errors }` (`<path>: <reason>`, at most 50); never throws.
+ */
+export function parseMarketplaceManifest(json, opts = {}) {
+    const r = (opts.allowInsecureLoopback ? LOOPBACK_SCHEMA : MarketplaceManifestSchema).safeParse(json);
+    if (r.success) {
+        return {
+            ...r.data,
+            plugins: r.data.plugins.map((e) => ({
+                ...e,
+                source: cleanSource(e.source),
+            })),
+        };
+    }
+    return {
+        errors: r.error.issues
+            .flatMap((i) => explainSource(json, i))
+            .slice(0, MAX_ERRORS)
+            .map((i) => {
+            const path = i.path.map(String).join(".");
+            return path ? `${path}: ${i.message}` : i.message;
+        }),
+    };
+}
+const SOURCE_FORMS = ["path", "git", "npm", "archive"];
+/**
+ * A failed `source` union is reported by zod as a bare "Invalid input"; report the problems of the
+ * form the source uses instead, or that it must use exactly one form.
+ */
+function explainSource(json, issue) {
+    if (issue.code !== "invalid_union" || issue.path[issue.path.length - 1] !== "source") {
+        return [issue];
+    }
+    let v = json;
+    for (const k of issue.path)
+        v = v?.[k];
+    const used = v !== null && typeof v === "object"
+        ? SOURCE_FORMS.filter((f) => v[f] !== undefined)
+        : [];
+    const branch = used.length === 1 ? SOURCE_FORMS.indexOf(used[0]) : -1;
+    const branchIssues = branch >= 0 ? issue.errors[branch] : undefined;
+    if (!branchIssues || branchIssues.length === 0) {
+        return [{ path: issue.path, message: `must have exactly one of ${SOURCE_FORMS.join(", ")}` }];
+    }
+    return branchIssues.map((b) => ({ path: [...issue.path, ...b.path], message: b.message }));
+}
+/** The entry's version: `version`, else the npm source's version, else `null` (the plugin's own). */
+export function marketplaceEntryVersion(e) {
+    if (e.version !== undefined)
+        return e.version;
+    if ("npm" in e.source)
+        return e.source.npm.version;
+    return null;
+}

package/dist/model-params.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `model-provider@2` 的参数声明与校验（纯函数；issue / 错误信息用英文，供日志与 API 返回）。
+ * 每个模型在 `ModelInfo.parameters` 中声明自己支持的参数，取值约束是受限的 JSON Schema 子集。
+ */
+export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * 标准旋钮：平台统一语义，界面专门渲染，换模型或兜底时语义可迁移；插件负责映射到原生参数。
+ * - `effort`：思考深度，`{ type: "string", enum }`，取值是 `low|medium|high|xhigh|max` 的子集；
+ * - `thinking`：思考模式，`{ type: "string", enum }`，取值是 `off|on|summarized` 的子集；
+ * - `temperature`：`{ type: "number" }`（可带范围）；
+ * - `maxOutputTokens`：最大输出 token，`{ type: "integer" }`（可带范围）。
+ */
+export type StandardKnob = "effort" | "thinking" | "temperature" | "maxOutputTokens";
+export declare const STANDARD_KNOBS: readonly StandardKnob[];
+/** `effort` 旋钮允许的取值全集。 */
+export declare const EFFORT_VALUES: readonly Effort[];
+/** `thinking` 旋钮允许的取值全集。 */
+export declare const THINKING_VALUES: readonly string[];
+/** 参数取值约束：受限的 JSON Schema 子集（可序列化后交给界面；内核自行校验，不依赖 ajv）。 */
+export type ParamSchema = {
+    type: "string";
+    enum: string[];
+} | {
+    type: "string";
+    maxLength?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "number" | "integer";
+    minimum?: number;
+    maximum?: number;
+};
+export type ParamValue = string | number | boolean;
+/** 模型声明的一个参数。 */
+export interface ModelParameter {
+    /** 标准旋钮名（见 {@link StandardKnob}），或厂商专有参数 `"<插件名>.<名称>"`。 */
+    key: string;
+    /** key 为标准旋钮时必填且必须等于 key；厂商专有参数不得填写。 */
+    standard?: StandardKnob;
+    schema: ParamSchema;
+    /** 未设置时使用的值；必须满足 schema。 */
+    default?: ParamValue;
+    label: {
+        zh: string;
+        en: string;
+    };
+    description?: {
+        zh: string;
+        en: string;
+    };
+}
+export interface ParamIssue {
+    key: string;
+    message: string;
+}
+/** 值不满足 schema 时返回英文原因，满足时返回 undefined。 */
+export declare function checkParamValue(schema: ParamSchema, v: unknown): string | undefined;
+/**
+ * 严格校验（保存 agent 时用）：未知键、类型不符、枚举越界、超出范围都算错，逐键报告。
+ * 成功时 `value` 为传入的参数，不补默认值；值为 undefined 的键视为未设置。
+ */
+export declare function validateParams(decl: ModelParameter[], params: Record<string, unknown>): {
+    ok: true;
+    value: Record<string, ParamValue>;
+} | {
+    ok: false;
+    issues: ParamIssue[];
+};
+/**
+ * 宽松版（运行时用）：丢弃未知或不合法的项（键记入 `dropped`），再为未设置的已声明参数补默认值。
+ * 用于插件升级后已保存的参数不再合法的情况，不让整轮运行失败。
+ */
+export declare function sanitizeParams(decl: ModelParameter[], params: Record<string, unknown>): {
+    value: Record<string, ParamValue>;
+    dropped: string[];
+};
+/**
+ * 校验插件为一个模型声明的参数：键名是标准旋钮或 `<plugin>.<名称>`、`standard` 与键一致、
+ * schema 属于受支持的子集、标准旋钮符合取值约定、默认值满足 schema、文案齐全、键不重复。
+ * 有问题时抛错，信息点名插件与各个键（英文）。
+ */
+export declare function assertValidDeclarations(plugin: string, decl: ModelParameter[]): void;

package/dist/model-params.js

@@ -0,0 +1,222 @@
+/**
+ * `model-provider@2` 的参数声明与校验（纯函数；issue / 错误信息用英文，供日志与 API 返回）。
+ * 每个模型在 `ModelInfo.parameters` 中声明自己支持的参数，取值约束是受限的 JSON Schema 子集。
+ */
+export const STANDARD_KNOBS = [
+    "effort",
+    "thinking",
+    "temperature",
+    "maxOutputTokens",
+];
+/** `effort` 旋钮允许的取值全集。 */
+export const EFFORT_VALUES = ["low", "medium", "high", "xhigh", "max"];
+/** `thinking` 旋钮允许的取值全集。 */
+export const THINKING_VALUES = ["off", "on", "summarized"];
+const isStandardKnob = (k) => STANDARD_KNOBS.includes(k);
+const VENDOR_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** 值不满足 schema 时返回英文原因，满足时返回 undefined。 */
+export function checkParamValue(schema, v) {
+    switch (schema.type) {
+        case "boolean":
+            return typeof v === "boolean" ? undefined : "must be a boolean";
+        case "string":
+            if (typeof v !== "string")
+                return "must be a string";
+            if ("enum" in schema) {
+                return schema.enum.includes(v)
+                    ? undefined
+                    : `must be one of ${schema.enum.map((x) => JSON.stringify(x)).join(", ")}`;
+            }
+            if (schema.maxLength !== undefined && v.length > schema.maxLength)
+                return `must be at most ${schema.maxLength} characters`;
+            return undefined;
+        case "number":
+        case "integer":
+            if (typeof v !== "number" || !Number.isFinite(v))
+                return "must be a finite number";
+            if (schema.type === "integer" && !Number.isInteger(v))
+                return "must be an integer";
+            if (schema.minimum !== undefined && v < schema.minimum)
+                return `must be >= ${schema.minimum}`;
+            if (schema.maximum !== undefined && v > schema.maximum)
+                return `must be <= ${schema.maximum}`;
+            return undefined;
+        default:
+            return `has unsupported schema type ${JSON.stringify(schema.type)}`;
+    }
+}
+/** 按键查声明（用 Map，避免 `constructor` 等原型属性被当成已声明的键）。 */
+const declMap = (decl) => new Map(decl.map((d) => [d.key, d]));
+/**
+ * 严格校验（保存 agent 时用）：未知键、类型不符、枚举越界、超出范围都算错，逐键报告。
+ * 成功时 `value` 为传入的参数，不补默认值；值为 undefined 的键视为未设置。
+ */
+export function validateParams(decl, params) {
+    const byKey = declMap(decl);
+    const value = {};
+    const issues = [];
+    for (const [key, v] of Object.entries(params)) {
+        if (v === undefined)
+            continue;
+        const d = byKey.get(key);
+        if (!d) {
+            issues.push({ key, message: `unknown parameter "${key}"` });
+            continue;
+        }
+        const why = checkParamValue(d.schema, v);
+        if (why)
+            issues.push({ key, message: `parameter "${key}" ${why}` });
+        else
+            value[key] = v;
+    }
+    return issues.length > 0 ? { ok: false, issues } : { ok: true, value };
+}
+/**
+ * 宽松版（运行时用）：丢弃未知或不合法的项（键记入 `dropped`），再为未设置的已声明参数补默认值。
+ * 用于插件升级后已保存的参数不再合法的情况，不让整轮运行失败。
+ */
+export function sanitizeParams(decl, params) {
+    const byKey = declMap(decl);
+    const value = {};
+    const dropped = [];
+    for (const [key, v] of Object.entries(params)) {
+        if (v === undefined)
+            continue;
+        const d = byKey.get(key);
+        if (!d || checkParamValue(d.schema, v) !== undefined)
+            dropped.push(key);
+        else
+            value[key] = v;
+    }
+    for (const d of decl) {
+        if (!Object.hasOwn(value, d.key) && d.default !== undefined)
+            value[d.key] = d.default;
+    }
+    return { value, dropped };
+}
+function keyProblems(plugin, d, key) {
+    if (isStandardKnob(key)) {
+        return d.standard === key ? [] : [`standard knob "${key}" must set standard: "${key}"`];
+    }
+    const out = [];
+    if (d.standard !== undefined) {
+        out.push(`standard: "${d.standard}" requires key "${d.standard}"`);
+    }
+    const dot = key.indexOf(".");
+    const prefix = dot < 0 ? "" : key.slice(0, dot);
+    const name = dot < 0 ? key : key.slice(dot + 1);
+    if (prefix !== plugin || !VENDOR_NAME.test(name)) {
+        out.push(`vendor parameter key must be "${plugin}.<name>" (or a standard knob: ${STANDARD_KNOBS.join(", ")})`);
+    }
+    return out;
+}
+function schemaProblems(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return ["schema is required"];
+    const s = schema;
+    switch (s.type) {
+        case "boolean":
+            return [];
+        case "string":
+            if ("enum" in s) {
+                const e = s.enum;
+                if (!Array.isArray(e) || e.length === 0 || !e.every((x) => typeof x === "string"))
+                    return ["enum must be a non-empty array of strings"];
+                return new Set(e).size === e.length ? [] : ["enum has duplicate values"];
+            }
+            if (s.maxLength !== undefined && !(Number.isInteger(s.maxLength) && Number(s.maxLength) >= 0))
+                return ["maxLength must be a non-negative integer"];
+            return [];
+        case "number":
+        case "integer": {
+            const out = [];
+            for (const b of ["minimum", "maximum"]) {
+                const v = s[b];
+                if (v !== undefined && !(typeof v === "number" && Number.isFinite(v)))
+                    out.push(`${b} must be a finite number`);
+            }
+            if (typeof s.minimum === "number" && typeof s.maximum === "number" && s.minimum > s.maximum)
+                out.push("minimum must not exceed maximum");
+            return out;
+        }
+        default:
+            return [`unsupported schema type ${JSON.stringify(s.type)}`];
+    }
+}
+/** 标准旋钮的取值约定（schema 本身已合法时才检查）。 */
+function knobProblems(key, schema) {
+    const values = schema.type === "string" && "enum" in schema ? schema.enum : undefined;
+    switch (key) {
+        case "effort":
+            return values?.every((x) => EFFORT_VALUES.includes(x))
+                ? []
+                : [`must be a string enum over a subset of ${EFFORT_VALUES.join("|")}`];
+        case "thinking":
+            return values?.every((x) => THINKING_VALUES.includes(x))
+                ? []
+                : [`must be a string enum over a subset of ${THINKING_VALUES.join("|")}`];
+        case "temperature":
+            return schema.type === "number" ? [] : ['must have schema type "number"'];
+        case "maxOutputTokens":
+            return schema.type === "integer" ? [] : ['must have schema type "integer"'];
+    }
+}
+function textProblems(d) {
+    const out = [];
+    for (const f of ["label", "description"]) {
+        const t = d[f];
+        if (t === undefined && f === "description")
+            continue;
+        const ok = typeof t === "object" &&
+            t !== null &&
+            typeof t.zh === "string" &&
+            typeof t.en === "string" &&
+            t.zh.trim() !== "" &&
+            t.en.trim() !== "";
+        if (!ok)
+            out.push(`${f} must have non-empty zh and en strings`);
+    }
+    return out;
+}
+/** 一个参数声明的全部问题；无问题返回空数组。 */
+function declarationProblems(plugin, d) {
+    if (typeof d !== "object" || d === null)
+        return ["declaration must be an object"];
+    if (typeof d.key !== "string")
+        return ["key must be a string"];
+    const out = [...keyProblems(plugin, d, d.key), ...schemaProblems(d.schema)];
+    if (out.length === 0) {
+        if (isStandardKnob(d.key))
+            out.push(...knobProblems(d.key, d.schema));
+        if (d.default !== undefined) {
+            const why = checkParamValue(d.schema, d.default);
+            if (why)
+                out.push(`default ${why}`);
+        }
+    }
+    out.push(...textProblems(d));
+    return out;
+}
+/**
+ * 校验插件为一个模型声明的参数：键名是标准旋钮或 `<plugin>.<名称>`、`standard` 与键一致、
+ * schema 属于受支持的子集、标准旋钮符合取值约定、默认值满足 schema、文案齐全、键不重复。
+ * 有问题时抛错，信息点名插件与各个键（英文）。
+ */
+export function assertValidDeclarations(plugin, decl) {
+    if (!Array.isArray(decl)) {
+        throw new Error(`model provider ${plugin}: parameters must be an array`);
+    }
+    const problems = [];
+    const seen = new Set();
+    for (const d of decl) {
+        const key = typeof d?.key === "string" ? d.key : "<invalid>";
+        if (seen.has(key))
+            problems.push(`"${key}": duplicate key`);
+        seen.add(key);
+        for (const p of declarationProblems(plugin, d))
+            problems.push(`"${key}": ${p}`);
+    }
+    if (problems.length > 0) {
+        throw new Error(`model provider ${plugin}: invalid parameter declarations: ${problems.join("; ")}`);
+    }
+}