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

package/dist/tools/builtins/skill-write.js

@@ -0,0 +1,244 @@
+import { createHash } from "node:crypto";
+import { isSkillName, parseSkillMd, SKILL_ENTRY_FILE, SKILL_LIMITS, skillInvocation, ToolError, validateSkillPackage, } from "@capybara-hq/plugin-sdk";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { storedInvocation } from "../../skills/package.js";
+import { display } from "./sandbox/common.js";
+/**
+ * 内置工具 `skill_write`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
+ * - 输入 `{ name, description, files: [{ path, content }] }`，只收文本文件，整个技能 ≤ {@link SKILL_WRITE_MAX_BYTES}；
+ * - the kernel generates SKILL.md ({@link buildSkillWrite}): its frontmatter is `name` / `description`
+ *   plus the invocation keys (`disable-model-invocation`, `context`, ... phase D) of the frontmatter
+ *   of the `SKILL.md` entry in `files`, whose other keys are dropped; its body is that entry's body
+ *   (empty without the entry);
+ * - 每次调用写一个完整的新版本（上一版有、这次没给的文件不再属于新版本）；
+ * - 私有 agent 直接生成新版本并立即生效；共享 agent 由触发对话的人先确认这次调用（R3 固定 ask，见 tools/policy.ts），
+ *   再生成变更申请等负责人批准，期间只有本对话试用新版本（见 skills/changes.service.ts）；
+ * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `skill_load`。
+ */
+/** 一个技能（含合成的 SKILL.md）的总大小上限（UTF-8 字节）。 */
+export const SKILL_WRITE_MAX_BYTES = 1024 * 1024;
+/** 一次最多的文件数（含 SKILL.md）。 */
+export const SKILL_WRITE_MAX_FILES = 200;
+const SPEC = {
+    name: "skill_write",
+    description: "Create or update one of this agent's own skills: reusable instructions plus optional text files " +
+        "(scripts, templates, reference notes) that you or later conversations can load with skill_load. " +
+        "Each call writes a complete new version. SKILL.md is generated for you: its frontmatter comes from " +
+        "`name` and `description`, and its body is the content of the `SKILL.md` entry in `files` if you " +
+        "include one (its frontmatter is dropped, except the invocation keys disable-model-invocation, " +
+        "user-invocable, context, agent, argument-hint and arguments, which are kept; with " +
+        "disable-model-invocation: true only a person can invoke the skill and you cannot load it). " +
+        "Every other entry in `files` is stored at " +
+        "/skills/<name>/<path>. Files of the previous version that you leave out are not part of the new " +
+        "version. Text files only, at most 1 MB per skill in total. Use an existing skill's name to update " +
+        "it; an organization skill with the same name is shadowed by this agent's own skill. On a private " +
+        "agent the new version takes effect immediately. On a shared agent the change is sent to the " +
+        "agent's owner for approval and is usable only in this conversation until approved.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                minLength: 1,
+                maxLength: SKILL_LIMITS.nameMaxChars,
+                description: 'Skill name: lowercase letters, digits and single hyphens, e.g. "weekly-report". Also the folder name under /skills/.',
+            },
+            description: {
+                type: "string",
+                minLength: 1,
+                maxLength: SKILL_LIMITS.descriptionMaxChars,
+                description: "What the skill does and when to use it, in one or two sentences (shown in the skills list). No XML tags.",
+            },
+            files: {
+                type: "array",
+                maxItems: SKILL_WRITE_MAX_FILES,
+                description: 'The skill\'s files. Include {"path": "SKILL.md", "content": "<instructions in Markdown>"} for the body; other paths are relative, e.g. "scripts/build.sh".',
+                items: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", minLength: 1, maxLength: SKILL_LIMITS.pathMaxChars },
+                        content: { type: "string", description: "The full text content of the file." },
+                    },
+                    required: ["path", "content"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["name", "description", "files"],
+        additionalProperties: false,
+    },
+};
+/**
+ * Splits off a leading YAML frontmatter (the same rule as `parseSkillMd`: a first line `---`, then a
+ * later `---` line): the body after it and the frontmatter text (null when there is none).
+ */
+function splitFrontmatter(text) {
+    const src = (text.startsWith("\uFEFF") ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+    const lines = src.split("\n");
+    if (lines[0]?.trimEnd() !== "---")
+        return { body: src, front: null };
+    const end = lines.findIndex((l, i) => i > 0 && l.trimEnd() === "---");
+    if (end < 0)
+        return { body: src, front: null };
+    return { body: lines.slice(end + 1).join("\n"), front: lines.slice(1, end).join("\n") };
+}
+/** The invocation keys (phase D) kept from the frontmatter of the `SKILL.md` entry. */
+const INVOCATION_KEYS = [
+    "disable-model-invocation",
+    "user-invocable",
+    "context",
+    "agent",
+    "argument-hint",
+    "arguments",
+];
+/** The invocation keys of a frontmatter text; unparsable YAML or a non-mapping keeps none. */
+function invocationKeysOf(front) {
+    if (front === null)
+        return {};
+    let data;
+    try {
+        data = parseYaml(front, { maxAliasCount: 50 });
+    }
+    catch {
+        return {};
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return {};
+    const out = {};
+    for (const key of INVOCATION_KEYS) {
+        const v = data[key];
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+const enc = new TextEncoder();
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+/**
+ * 由工具输入合成技能文件（纯函数）：
+ * - SKILL.md = `---\n<yaml name/description>---\n\n<正文>\n`，正文为 `files` 里 `SKILL.md` 的内容去掉 frontmatter、
+ *   去掉首尾空行；合成结果再用 `parseSkillMd` 校验（名字规则、描述长度、不含 XML 标签）；
+ * - 其余文件按 `validateSkillPackage` 校验路径（不能越出 `/skills/<name>/`、不能重复、大小写冲突等）；
+ * - 只收文本：内容含 NUL 视为二进制，拒绝；全部文件（含 SKILL.md）的 UTF-8 字节数之和 ≤ {@link SKILL_WRITE_MAX_BYTES}。
+ * 返回合成结果或全部问题（英文，直接给模型）。
+ */
+export function buildSkillWrite(input) {
+    const errors = [];
+    if (!isSkillName(input.name)) {
+        errors.push(`name "${String(input.name).slice(0, 80)}" is invalid: use 1-64 lowercase letters, digits and single hyphens (no leading or trailing hyphen)`);
+    }
+    if (input.description.includes("\u0000")) {
+        errors.push("description: only text is supported (it contains NUL bytes)");
+    }
+    const entries = input.files.filter((f) => f.path === SKILL_ENTRY_FILE);
+    if (entries.length > 1)
+        errors.push(`${SKILL_ENTRY_FILE}: duplicate path`);
+    const split = splitFrontmatter(entries[0]?.content ?? "");
+    const body = split.body.replace(/^\n+|\s+$/g, "");
+    const keys = invocationKeysOf(split.front);
+    const front = stringifyYaml({ name: input.name, description: input.description.trim(), ...keys }, { lineWidth: 0 });
+    const md = `---\n${front}---\n${body === "" ? "" : `\n${body}\n`}`;
+    let invocation;
+    if (errors.length === 0) {
+        const parsed = parseSkillMd(md);
+        if ("errors" in parsed)
+            errors.push(...parsed.errors);
+        else
+            invocation = storedInvocation(skillInvocation(parsed.frontmatter));
+    }
+    const others = input.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
+    const files = [];
+    const mdData = enc.encode(md);
+    files.push({
+        path: SKILL_ENTRY_FILE,
+        data: mdData,
+        size: mdData.byteLength,
+        sha256: sha256(mdData),
+    });
+    for (const f of input.files) {
+        if (!f.content.includes("\u0000"))
+            continue;
+        errors.push(`${f.path.slice(0, 200)}: only text files are supported (the content contains NUL bytes)`);
+    }
+    for (const f of others) {
+        if (f.content.includes("\u0000"))
+            continue;
+        const data = enc.encode(f.content);
+        files.push({ path: f.path, data, size: data.byteLength, sha256: sha256(data) });
+    }
+    errors.push(...validateSkillPackage(files.map((f) => ({ path: f.path, size: f.size }))));
+    const total = files.reduce((n, f) => n + f.size, 0);
+    if (total > SKILL_WRITE_MAX_BYTES) {
+        errors.push(`the skill is ${total} bytes in total, over the 1 MB (${SKILL_WRITE_MAX_BYTES} bytes) limit; shorten the files or move large data out of the skill`);
+    }
+    if (errors.length > 0)
+        return { errors };
+    const description = input.description.trim();
+    return {
+        name: input.name,
+        description,
+        files,
+        manifest: {
+            name: input.name,
+            description,
+            files: files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
+            ...(invocation !== undefined && { invocation }),
+        },
+    };
+}
+/** 内置工具 `skill_write`（见文件头）。 */
+export function skillWriteTool(deps) {
+    return {
+        spec: SPEC,
+        // 私有 agent 不询问；共享 agent 由 R3 固定 ask 把关（tools/policy.ts 的 R3_SHARED_AGENT_ONLY_TOOL_KEYS）
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const built = buildSkillWrite(input);
+            if ("errors" in built) {
+                throw new ToolError(`The skill was not written. Fix these problems and call skill_write again:\n- ${built.errors.slice(0, 20).join("\n- ")}`);
+            }
+            const r = await deps.changes.write({
+                orgId: ctx.orgId,
+                agentId: ctx.agentId,
+                accountId: ctx.accountId,
+                conversationId: ctx.conversationId,
+                ...(ctx.runId !== undefined && { runId: ctx.runId }),
+            }, built);
+            const name = built.name;
+            // A manual-only version (phase D) is not in the model's catalog, so skill_load cannot load it
+            const manualOnly = built.manifest.invocation?.model === false;
+            const manualText = `It is manual-only (disable-model-invocation: true): it is not in your skills catalog and ` +
+                `skill_load cannot load it; a person invokes it with /${name}.`;
+            if (r.kind === "version") {
+                const what = r.created ? "Created" : "Updated";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${what} skill "${name}" (version ${r.version}, ${built.files.length} files). ` +
+                                (manualOnly
+                                    ? `It is in effect now for every conversation with this agent. ${manualText}`
+                                    : "It is in effect now for every conversation with this agent; call skill_load to use it."),
+                        },
+                    ],
+                    display: display(`${r.created ? "新建" : "更新"}技能 ${name}（版本 ${r.version}）`, `${what} skill ${name} (version ${r.version})`),
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Saved skill "${name}" (version ${r.version}, ${built.files.length} files) as a change ` +
+                            "awaiting the owner's approval, because this agent is shared. Until the owner approves it, " +
+                            (manualOnly
+                                ? `the new version applies only in this conversation; other conversations keep the current version. ${manualText} `
+                                : "the new version is usable only in this conversation (call skill_load to use it); other " +
+                                    "conversations keep the current version. ") +
+                            "Tell the user the change needs the owner's approval.",
+                    },
+                ],
+                display: display(`技能 ${name} 的改动（版本 ${r.version}）已提交，等待负责人批准`, `Change to skill ${name} (version ${r.version}) awaits the owner's approval`),
+            };
+        },
+    };
+}

package/dist/tools/builtins/tool-search.d.ts

@@ -0,0 +1,31 @@
+import type { ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type BuiltinTool, type ResolvedTool } from "../registry.js";
+/** 内置工具名。 */
+export declare const TOOL_SEARCH = "tool_search";
+export declare const TOOL_SEARCH_SPEC: ToolSpec;
+/** 目录（system 第二个块）的开头说明（模型可见，英文）。 */
+export declare const CATALOG_HEADER: string;
+/** 调用目录里尚未加载的工具（模型可见，英文；spec 5.5：不自动加载）。 */
+export declare const notLoadedText: (key: string) => string;
+/** 始终完整加载、不进目录的工具（内置工具）。 */
+export declare const isAlwaysLoaded: (key: string) => boolean;
+type CatalogTool = Pick<ResolvedTool, "key" | "spec">;
+/** 分词：切开驼峰，按非字母数字切分，转小写。 */
+export declare function tokenize(text: string): string[];
+/**
+ * 关键词评分（确定性）：对每个不同的查询词，`idf × (key 中出现 ? 2 : 0 + 描述中出现 ? 1 : 0)`，
+ * `idf = ln(1 + N / df)`（df = 含该词的工具数）。只看是否出现、不按长度归一，描述长短不影响排名。
+ * 分数为 0 的不返回；按分数降序，同分按 key 升序。
+ */
+export declare function searchTools<T extends CatalogTool>(query: string, tools: readonly T[], limit: number): T[];
+/** 目录行：`- <key>: <描述的第一行>`（超长截断）。 */
+export declare function catalogLine(t: CatalogTool): string;
+/** 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。 */
+export declare function catalogText(tools: readonly CatalogTool[]): string;
+/**
+ * 内置工具 `tool_search`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
+ * 并在结果里带 `loadedTools`（管线写进 `tool_result.loadedTools`；已加载集合只由日志还原）。
+ * 搜索范围来自管线传入的 `ctx.tools`（本步解析出的工具）；内置工具始终加载，不参与搜索。
+ */
+export declare function toolSearchTool(): BuiltinTool;
+export {};

package/dist/tools/builtins/tool-search.js

@@ -0,0 +1,171 @@
+import { BUILTIN_TOOL_NAMES } from "../registry.js";
+/** 内置工具名。 */
+export const TOOL_SEARCH = "tool_search";
+/** 默认返回的匹配数。 */
+const DEFAULT_LIMIT = 5;
+/** 单次最多返回的匹配数。 */
+const MAX_LIMIT = 10;
+/** 目录行里描述的最大字符数。 */
+const MAX_CATALOG_DESCRIPTION = 200;
+/** key 中的词比描述中的词权重更高（key 是工具最直接的名字）。 */
+const KEY_WEIGHT = 2;
+export const TOOL_SEARCH_SPEC = {
+    name: TOOL_SEARCH,
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["query"],
+    description: "Search the tool catalog by keywords and load the matching tools. Tools listed in the " +
+        "catalog are not loaded: call this tool first with keywords from the task (for example the " +
+        "app, object or action), then call the loaded tools from your next step on. Returns the full " +
+        "definition (name, description, input schema) of the best matches. Do not use it for tools " +
+        "you already have.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                minLength: 1,
+                maxLength: 500,
+                description: "Keywords describing the tool you need, e.g. 'create calendar event'.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: MAX_LIMIT,
+                description: `Maximum number of tools to load. Default ${DEFAULT_LIMIT}.`,
+            },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+};
+/** 目录（system 第二个块）的开头说明（模型可见，英文）。 */
+export const CATALOG_HEADER = "More tools are available but not loaded. To use one, first call tool_search with keywords; " +
+    "it returns the full definitions and loads the matching tools for your next step. " +
+    "Calling a tool that is not loaded returns an error. Tool catalog:";
+/** 调用目录里尚未加载的工具（模型可见，英文；spec 5.5：不自动加载）。 */
+export const notLoadedText = (key) => `Tool "${key}" is not loaded. Call tool_search first with keywords for this tool, then call it in a later step.`;
+/** 始终完整加载、不进目录的工具（内置工具）。 */
+export const isAlwaysLoaded = (key) => BUILTIN_TOOL_NAMES.includes(key);
+/** 分词：切开驼峰，按非字母数字切分，转小写。 */
+export function tokenize(text) {
+    return text
+        .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t !== "");
+}
+/**
+ * 关键词评分（确定性）：对每个不同的查询词，`idf × (key 中出现 ? 2 : 0 + 描述中出现 ? 1 : 0)`，
+ * `idf = ln(1 + N / df)`（df = 含该词的工具数）。只看是否出现、不按长度归一，描述长短不影响排名。
+ * 分数为 0 的不返回；按分数降序，同分按 key 升序。
+ */
+export function searchTools(query, tools, limit) {
+    const terms = [...new Set(tokenize(query))];
+    if (terms.length === 0)
+        return [];
+    const docs = tools.map((t) => ({
+        tool: t,
+        key: new Set(tokenize(t.key)),
+        desc: new Set(tokenize(t.spec.description)),
+    }));
+    const n = docs.length;
+    const idf = new Map();
+    for (const term of terms) {
+        const df = docs.filter((d) => d.key.has(term) || d.desc.has(term)).length;
+        idf.set(term, df === 0 ? 0 : Math.log(1 + n / df));
+    }
+    return docs
+        .map((d) => {
+        let score = 0;
+        for (const term of terms) {
+            const w = (d.key.has(term) ? KEY_WEIGHT : 0) + (d.desc.has(term) ? 1 : 0);
+            score += w * (idf.get(term) ?? 0);
+        }
+        return { tool: d.tool, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score !== a.score
+        ? b.score - a.score
+        : a.tool.key < b.tool.key
+            ? -1
+            : a.tool.key > b.tool.key
+                ? 1
+                : 0)
+        .slice(0, limit)
+        .map((x) => x.tool);
+}
+/** 目录行：`- <key>: <描述的第一行>`（超长截断）。 */
+export function catalogLine(t) {
+    const first = t.spec.description
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l !== "") ?? "";
+    const desc = first.length > MAX_CATALOG_DESCRIPTION
+        ? `${first.slice(0, MAX_CATALOG_DESCRIPTION - 1)}…`
+        : first;
+    return `- ${t.key}: ${desc}`;
+}
+/** 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。 */
+export function catalogText(tools) {
+    const sorted = [...tools].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return [CATALOG_HEADER, ...sorted.map(catalogLine)].join("\n");
+}
+/** 一个工具的完整定义文本（tool_search 的结果）。 */
+function definitionText(t) {
+    return [
+        `Tool: ${t.key}`,
+        `Description: ${t.spec.description}`,
+        `Input schema: ${JSON.stringify(t.spec.inputSchema)}`,
+    ].join("\n");
+}
+/** 显示摘要里的查询词上限（码点）：摘要整体须 ≤ 200 码点（`validateToolDisplay`）。 */
+const DISPLAY_QUERY_MAX = 120;
+/** 摘要里的查询词：压成一行，超长按码点截断加省略号。 */
+function displayQuery(query) {
+    const one = query.replace(/\s+/g, " ").trim();
+    const cps = [...one];
+    return cps.length > DISPLAY_QUERY_MAX ? `${cps.slice(0, DISPLAY_QUERY_MAX - 1).join("")}…` : one;
+}
+/**
+ * 内置工具 `tool_search`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
+ * 并在结果里带 `loadedTools`（管线写进 `tool_result.loadedTools`；已加载集合只由日志还原）。
+ * 搜索范围来自管线传入的 `ctx.tools`（本步解析出的工具）；内置工具始终加载，不参与搜索。
+ */
+export function toolSearchTool() {
+    return {
+        spec: TOOL_SEARCH_SPEC,
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const { query, limit = DEFAULT_LIMIT } = input;
+            const catalog = (ctx.tools ?? []).filter((t) => !isAlwaysLoaded(t.key));
+            const found = searchTools(query, catalog, limit);
+            const q = displayQuery(query);
+            if (found.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No tools matched "${query}". Try other keywords, or check the tool catalog in the system prompt.`,
+                        },
+                    ],
+                    loadedTools: [],
+                    display: {
+                        summary: { zh: `搜索工具「${q}」· 无匹配`, en: `Searched tools for "${q}" · no match` },
+                    },
+                };
+            }
+            const head = `Loaded ${found.length} tool${found.length === 1 ? "" : "s"}. You can call ${found.length === 1 ? "it" : "them"} from your next step.`;
+            return {
+                content: [{ type: "text", text: [head, ...found.map(definitionText)].join("\n\n") }],
+                loadedTools: found.map((t) => t.key),
+                display: {
+                    summary: {
+                        zh: `搜索工具「${q}」· 加载 ${found.length} 个`,
+                        en: `Searched tools for "${q}" · loaded ${found.length}`,
+                    },
+                },
+            };
+        },
+    };
+}

package/dist/tools/connector-content.controller.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { ConnectorContent, ConnectorPromptView, ConnectorResourceView, ConnectorUnavailable } from "./connector-content.js";
+declare const PromptBody: z.ZodObject<{
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+declare const ResourcesQuery: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 连接器内容（`/api/v1/orgs/:orgId/connectors/...`）：网页输入框的 `/` 斜杠命令（prompts）与 `@` 资源引用。
+ * 都是 `connectors.use`、仅限用户主体，以发起人自己的凭据访问连接器（个人连接器须已连接）。
+ * 静态路径 `prompts` / `resources` 优先于 ConnectorsController 的 `:connectorId`。
+ */
+export declare class ConnectorContentController {
+    private readonly content;
+    constructor(content: ConnectorContent);
+    /** 发起人可用的提示模板；缺凭据 / 连不上的连接器列在 `unavailable`。 */
+    prompts(principal: Principal, org: OrgContext): Promise<{
+        prompts: ConnectorPromptView[];
+        unavailable: ConnectorUnavailable[];
+    }>;
+    /** 发起人可用的资源，`query` 按名称 / URI / 描述子串过滤。 */
+    resources(principal: Principal, org: OrgContext, q: z.infer<typeof ResourcesQuery>): Promise<{
+        resources: ConnectorResourceView[];
+        unavailable: ConnectorUnavailable[];
+    }>;
+    /** 按参数渲染一个提示模板为文本（放进输入框，由用户发送）。 */
+    renderPrompt(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof PromptBody>): Promise<{
+        text: string;
+    }>;
+}
+export {};

package/dist/tools/connector-content.controller.js

@@ -0,0 +1,78 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Get, HttpCode, Inject, Param, Post, Query } from "@nestjs/common";
+import { z } from "zod";
+import { CONNECTOR_CONTENT } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+const PromptBody = z
+    .object({
+    arguments: z
+        .record(z.string().min(1).max(200), z.string().max(10_000))
+        .refine((v) => Object.keys(v).length <= 50, { message: "Too many arguments" })
+        .default({}),
+})
+    .strict();
+const ResourcesQuery = z.object({ query: z.string().max(200).optional() });
+/**
+ * 连接器内容（`/api/v1/orgs/:orgId/connectors/...`）：网页输入框的 `/` 斜杠命令（prompts）与 `@` 资源引用。
+ * 都是 `connectors.use`、仅限用户主体，以发起人自己的凭据访问连接器（个人连接器须已连接）。
+ * 静态路径 `prompts` / `resources` 优先于 ConnectorsController 的 `:connectorId`。
+ */
+let ConnectorContentController = class ConnectorContentController {
+    content;
+    constructor(content) {
+        this.content = content;
+    }
+    /** 发起人可用的提示模板；缺凭据 / 连不上的连接器列在 `unavailable`。 */
+    async prompts(principal, org) {
+        const p = requireUser(principal);
+        return this.content.listPrompts(org.orgId, p.account.id);
+    }
+    /** 发起人可用的资源，`query` 按名称 / URI / 描述子串过滤。 */
+    async resources(principal, org, q) {
+        const p = requireUser(principal);
+        return this.content.listResources(org.orgId, p.account.id, q.query);
+    }
+    /** 按参数渲染一个提示模板为文本（放进输入框，由用户发送）。 */
+    async renderPrompt(principal, org, connectorId, name, body) {
+        const p = requireUser(principal);
+        return this.content.getPrompt(org.orgId, connectorId, name, body.arguments, p.account.id);
+    }
+};
+__decorate([
+    Get("prompts"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], ConnectorContentController.prototype, "prompts", null);
+__decorate([
+    Get("resources"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Query(new ZodPipe(ResourcesQuery)))
+], ConnectorContentController.prototype, "resources", null);
+__decorate([
+    Post(":connectorId/prompts/:name"),
+    HttpCode(200),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Param("name")),
+    __param(4, Body(new ZodPipe(PromptBody)))
+], ConnectorContentController.prototype, "renderPrompt", null);
+ConnectorContentController = __decorate([
+    Controller("api/v1/orgs/:orgId/connectors"),
+    __param(0, Inject(CONNECTOR_CONTENT))
+], ConnectorContentController);
+export { ConnectorContentController };

package/dist/tools/connector-content.d.ts

@@ -0,0 +1,104 @@
+import type { Logger, PromptInfo } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { Breaker } from "./breaker.js";
+import { type Credentials } from "./credentials.js";
+import type { ToolRegistry } from "./registry.js";
+/** 每个附件的正文上限（字符）。 */
+export declare const MAX_ATTACHMENT_CHARS = 50000;
+/** 一条消息最多附件数。 */
+export declare const MAX_ATTACHMENTS = 5;
+export interface ConnectorPromptView {
+    connectorId: string;
+    connectorSlug: string;
+    connectorName: string;
+    name: string;
+    title?: string;
+    description?: string;
+    arguments: PromptInfo["arguments"];
+}
+export interface ConnectorResourceView {
+    connectorId: string;
+    connectorSlug: string;
+    connectorName: string;
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+/** 列表时某个连接器不可用：发起人没有连接个人凭据，或连接 / 列出失败（含熔断打开）。 */
+export interface ConnectorUnavailable {
+    connectorId: string;
+    connectorName: string;
+    reason: "not_connected" | "failed";
+}
+/**
+ * 附件元数据（存在 user_message 里，界面据此显示附件而不是正文）。字段名是事件 payload 的一部分，
+ * 改名后仍为 `appId` / `appName`（C27：日志确定性）。
+ */
+export interface AttachmentMeta {
+    appId: string;
+    appName: string;
+    uri: string;
+    name: string;
+}
+export interface ConnectorContentDeps {
+    db: KernelDb;
+    registry: Pick<ToolRegistry, "findConnector">;
+    credentials: Pick<Credentials, "injection" | "onUnauthorized">;
+    breaker: Pick<Breaker, "check">;
+    config: () => KernelConfig;
+    log: Logger;
+}
+export declare class ConnectorContent {
+    private readonly d;
+    constructor(d: ConnectorContentDeps);
+    private activeConnectors;
+    private connectorRow;
+    /**
+     * 读取资源受管理员对该连接器 `read_resource` 工具（`source = 'resources'`）的启停约束（Ruling A23）：
+     * 返回其中该工具为 enabled 的连接器 id。
+     */
+    private resourcesEnabled;
+    /**
+     * 以 `accountId` 的凭据打开连接器会话执行 `work`，结果按本次注入的凭据打码，会话无论成败都关闭。
+     * 缺凭据 → `credential.missing`；熔断打开、连接 / 远端失败 → 502 `connector.connect_failed`（消息打码、限长）。
+     * `work` 返回 undefined 表示该连接器不支持这项能力。
+     */
+    private withSession;
+    /** 对每个 active 连接器并行执行 `work`；缺凭据 / 失败的连接器进 `unavailable`，不支持的（undefined）跳过。 */
+    private acrossConnectors;
+    /** 发起人可用的全部提示模板（按连接器创建顺序，连接器内按远端顺序）。 */
+    listPrompts(orgId: string, accountId: string): Promise<{
+        prompts: ConnectorPromptView[];
+        unavailable: ConnectorUnavailable[];
+    }>;
+    /**
+     * 渲染一个提示模板为文本（供用户放进输入框再发送）：各消息的文本按顺序以空行连接，assistant 消息加
+     * `Assistant:` 前缀；非文本内容给类型说明。连接器不支持 prompts → 404 `connector.not_found`。
+     */
+    getPrompt(orgId: string, connectorId: string, name: string, args: Record<string, string>, accountId: string): Promise<{
+        text: string;
+    }>;
+    /** 发起人可用的资源；`query` 按名称 / URI / 描述的子串过滤（不区分大小写），最多 {@link MAX_RESOURCES} 条。 */
+    listResources(orgId: string, accountId: string, query?: string): Promise<{
+        resources: ConnectorResourceView[];
+        unavailable: ConnectorUnavailable[];
+    }>;
+    /**
+     * 解析消息附件：以发送者的凭据**并行**读取每个资源（打码、每个限 {@link MAX_ATTACHMENT_CHARS} 字符；总时限
+     * min(`tools.timeoutMs`, 30s)），按请求顺序返回要追加在用户消息后的文本块与元数据。名称取资源清单里的 name
+     * （读不到清单时用 URI）。连接器的 `read_resource` 工具被管理员停用 → 409 `connector.resources_disabled`。
+     * 任一附件失败整条消息失败（不写入）。
+     */
+    resolveAttachments(orgId: string, accountId: string, refs: {
+        connectorId: string;
+        uri: string;
+    }[]): Promise<{
+        blocks: {
+            type: "text";
+            text: string;
+        }[];
+        attachments: AttachmentMeta[];
+    }>;
+}