@onco-foundry/agent-template 0.6.1 → 0.7.0

package/dist/agent_spec_executor.js

@@ -1,4 +1,4 @@
-import { defineAgent } from 'agent-lattice';
+import { defineAgent, skill } from 'agent-lattice';
 import { createTypedAgentTool } from '@onco-foundry/agent-runtime';
 import { createTracer } from '@onco-foundry/trace-port';
 import { clampThinkingBudgetTokens } from './agent_template.js';
@@ -12,6 +12,9 @@ export const createAgentSpecExecutor = (declaration) => ({
     },
     task: declaration.task,
     async createSpec(input) {
+        if (input.skills?.some(item => Object.keys(item.files).some(path => path !== 'SKILL.md'))) {
+            throw new Error('通用执行器不挂载 Skill 资源文件；请使用提供只读工作区的执行器');
+        }
         const memberTools = await Promise.all(input.members.map(async (member) => createTypedAgentTool(await member.agent.createCapability({
             tracer: input.tracer,
             modelClient: input.modelClient,
@@ -30,6 +33,7 @@ export const createAgentSpecExecutor = (declaration) => ({
             ...(input.model.apiKey === undefined ? {} : { apiKey: input.model.apiKey }),
             modelClient: input.modelClient,
             systemPrompt: input.systemPrompt,
+            ...(input.skills === undefined ? {} : { skills: input.skills.map(item => skill({ name: item.name, description: item.description, instructions: item.instructions })) }),
             outputSchema: declaration.output,
             tools: [...input.tools, ...memberTools],
             ...(maxTokens === undefined ? {} : { maxTokens }),

package/dist/agent_version.d.ts

@@ -4,9 +4,13 @@ import type { Capability } from '@onco-foundry/capability-registry';
 import type { CapabilityDelegation } from '@onco-foundry/agent-runtime';
 import type { Tracer } from '@onco-foundry/trace-port';
 import type { AgentTemplateCard, TemplateToolDefinition } from './agent_template.ts';
+import type { ResolvedSkillPackage, SkillPackageReference, SkillPackageSummary } from './skill_packages.ts';
 export declare const agentResourceVersionSchema: z.ZodString;
 export declare const agentVersionSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<"agent-config-v1">;
+    schemaVersion: z.ZodEnum<{
+        "agent-config-v1": "agent-config-v1";
+        "agent-config-v2": "agent-config-v2";
+    }>;
     executor: z.ZodObject<{
         id: z.ZodString;
         version: z.ZodString;
@@ -44,6 +48,10 @@ export declare const agentVersionSchema: z.ZodObject<{
         id: z.ZodString;
         version: z.ZodString;
     }, z.core.$strict>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>>>;
     limits: z.ZodOptional<z.ZodObject<{
         maxTurns: z.ZodOptional<z.ZodNumber>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -74,6 +82,7 @@ export type ResolvedAgentVersion = {
     }>;
     tools: AgentVersionToolReference[];
     members: AgentVersionMemberReference[];
+    skills?: SkillPackageSummary[];
     limits?: AgentVersion['limits'];
 };
 export type ResolvedAgentSnapshot = {
@@ -102,6 +111,7 @@ export type ResolvedAgent = {
         version: string;
     };
     readSnapshot(): ResolvedAgentSnapshot;
+    readSkills(): ResolvedSkillPackage[];
 };
 export type ResolvedAgentMember = {
     id: string;
@@ -116,6 +126,7 @@ export type AgentExecutorSpecInput<C> = {
     tools: TemplateToolDefinition[];
     members: ResolvedAgentMember[];
     context: C;
+    skills?: ResolvedSkillPackage[];
     tracer?: Tracer;
     modelClient?: ModelClient;
     submitOutputEndTurn?: boolean;
@@ -137,11 +148,12 @@ export type AgentVersionPorts<C = unknown> = {
     readPrompt(reference: AgentVersionPromptReference): Promise<{
         content: string;
     }>;
-    readCommonPrompt(reference: AgentVersionCommonPromptReference): Promise<{
+    readCommonPrompt(reference: AgentVersionCommonPromptReference, agentId: string): Promise<{
         content: string;
     }>;
     createTool(reference: AgentVersionToolReference, context: C): TemplateToolDefinition | Promise<TemplateToolDefinition>;
     resolveExecutor(reference: AgentVersionExecutorReference): AgentVersionExecutor<C>;
+    readSkill?(reference: SkillPackageReference): Promise<ResolvedSkillPackage>;
 };
 export type ResolveAgentVersionInput<C = unknown> = {
     agentId: string;

package/dist/agent_version.js

@@ -27,7 +27,7 @@ const memberReferenceSchema = z.object({
     version: agentResourceVersionSchema,
 }).strict();
 export const agentVersionSchema = z.object({
-    schemaVersion: z.literal('agent-config-v1'),
+    schemaVersion: z.enum(['agent-config-v1', 'agent-config-v2']),
     executor: executorReferenceSchema,
     model: z.object({
         configVersion: z.string().min(1),
@@ -41,9 +41,15 @@ export const agentVersionSchema = z.object({
     commonPrompts: z.array(commonPromptReferenceSchema),
     tools: z.array(localToolReferenceSchema),
     members: z.array(memberReferenceSchema),
+    skills: z.array(z.object({ id: z.string().regex(/^[a-z][a-z0-9-]{0,79}$/), version: agentResourceVersionSchema }).strict()).max(32).optional(),
     limits: z.object({
         maxTurns: z.number().int().positive().optional(),
         maxTokens: z.number().int().min(2).optional(),
         thinkingBudgetTokens: z.number().int().positive().optional(),
     }).strict().optional(),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    if (value.schemaVersion === 'agent-config-v1' && value.skills !== undefined)
+        ctx.addIssue({ code: 'custom', path: ['skills'], message: 'Skill 引用需要 agent-config-v2' });
+    if (value.schemaVersion === 'agent-config-v2' && value.skills === undefined)
+        ctx.addIssue({ code: 'custom', path: ['skills'], message: 'agent-config-v2 必须声明 skills' });
+});

package/dist/agent_version_resolver.js

@@ -41,6 +41,7 @@ export const createAgentVersionResolver = (ports) => {
                     commonPrompts: record.commonPrompts.map(({ content: _content, ...part }) => ({ ...part })),
                     tools: record.config.tools.map(tool => ({ ...tool })),
                     members: record.config.members.map(member => ({ ...member })),
+                    ...(record.skills === undefined ? {} : { skills: record.skills.map(({ id, version, name, description, checksum }) => ({ id, version, name, description, checksum })) }),
                     ...(record.config.limits === undefined ? {} : { limits: { ...record.config.limits } }),
                 };
                 for (const member of record.config.members)
@@ -85,6 +86,23 @@ export const createAgentVersionResolver = (ports) => {
             try {
                 const executor = ports.resolveExecutor(loaded.config.executor);
                 executor.validate?.({ agentId, config: loaded.config });
+                const skills = loaded.config.skills === undefined ? undefined : [];
+                const skillNames = new Set();
+                const skillIds = new Set();
+                for (const reference of loaded.config.skills ?? []) {
+                    if (!ports.readSkill)
+                        throw new AppError('当前宿主未提供 Skill 读取端口');
+                    if (skillIds.has(reference.id))
+                        throw new AppError(`重复的 Skill 引用：${reference.id}`);
+                    const skill = await ports.readSkill(reference);
+                    if (skill.id !== reference.id || skill.version !== reference.version || !/^[a-f0-9]{64}$/.test(skill.checksum))
+                        throw new AppError(`Skill 解析结果与精确引用不符：${reference.id}`);
+                    if (skillNames.has(skill.name))
+                        throw new AppError(`Skill 名称冲突：${skill.name}`);
+                    skillIds.add(reference.id);
+                    skillNames.add(skill.name);
+                    skills.push(structuredClone(skill));
+                }
                 const promptVersion = agentId === input.agentId
                     ? input.promptVersion
                     : input.memberPromptVersions?.[agentId];
@@ -97,7 +115,7 @@ export const createAgentVersionResolver = (ports) => {
                     ports.resolveModel(loaded.config.model),
                 ]);
                 const commonPrompts = await Promise.all(loaded.config.commonPrompts.map(async (reference) => {
-                    const { content } = await ports.readCommonPrompt(reference);
+                    const { content } = await ports.readCommonPrompt(reference, agentId);
                     return { ...reference, content, checksum: checksum(content) };
                 }));
                 const ordered = [...commonPrompts].sort((a, b) => a.placement === b.placement
@@ -121,6 +139,7 @@ export const createAgentVersionResolver = (ports) => {
                     commonPrompts,
                     systemPrompt,
                     systemPromptChecksum: checksum(systemPrompt),
+                    ...(skills === undefined ? {} : { skills }),
                 };
                 records.set(agentId, record);
                 const createSpec = async (options = {}) => {
@@ -135,6 +154,7 @@ export const createAgentVersionResolver = (ports) => {
                         config: record.config,
                         model: record.model,
                         systemPrompt: record.systemPrompt,
+                        ...(record.skills === undefined ? {} : { skills: structuredClone(record.skills) }),
                         tools,
                         members: await Promise.all(record.config.members.map(async (member) => ({
                             id: member.id,
@@ -172,6 +192,7 @@ export const createAgentVersionResolver = (ports) => {
                     },
                     readSystemPrompt: () => ({ content: record.systemPrompt, version: record.prompt.version }),
                     readSnapshot: () => structuredClone(snapshotFor(agentId)),
+                    readSkills: () => structuredClone(record.skills ?? []),
                 };
                 record.agent = agent;
                 for (const member of record.config.members)

package/dist/fake_agent_version_ports.d.ts

@@ -1,4 +1,5 @@
 import type { TemplateToolDefinition } from './agent_template.ts';
+import { type SkillPackageFiles, type SkillPackageReference } from './skill_packages.ts';
 import type { AgentVersion, AgentVersionCommonPromptReference, AgentVersionExecutor, AgentVersionPorts, AgentVersionPromptReference } from './agent_version.ts';
 export declare const createFakeAgentVersionPorts: <C>(options: {
     executors: Record<string, AgentVersionExecutor<C>>;
@@ -9,4 +10,5 @@ export declare const createFakeAgentVersionPorts: <C>(options: {
     activateAgentVersion(agentId: string, version: string): Promise<void>;
     setPrompt(reference: AgentVersionPromptReference, content: string): void;
     setCommonPrompt(reference: AgentVersionCommonPromptReference, content: string): void;
+    writeSkill(reference: SkillPackageReference, files: SkillPackageFiles): Promise<void>;
 };

package/dist/fake_agent_version_ports.js

@@ -1,5 +1,6 @@
 import { AppError } from '@onco-foundry/errors';
 import { activateVersion, createFakeVersionedResourceStore, createVersionedResource, } from '@onco-foundry/resource-versioning';
+import { createSkillPackages } from './skill_packages.js';
 const promptKey = (reference) => `${reference.resource}@${reference.version}`;
 const commonPromptKey = (reference) => `${reference.source}:${reference.id}@${reference.version}`;
 const executorKey = (reference) => `${reference.id}@${reference.version}`;
@@ -8,6 +9,12 @@ export const createFakeAgentVersionPorts = (options) => {
     const stores = new Map();
     const prompts = new Map();
     const commonPrompts = new Map();
+    const skillStores = new Map();
+    const skills = createSkillPackages({ storeFor: id => {
+            if (!skillStores.has(id))
+                skillStores.set(id, createFakeVersionedResourceStore());
+            return skillStores.get(id);
+        } });
     const ports = {
         storeFor(agentId) {
             let store = stores.get(agentId);
@@ -17,6 +24,8 @@ export const createFakeAgentVersionPorts = (options) => {
             }
             return store;
         },
+        readSkill: reference => skills.read(reference),
+        async writeSkill(reference, files) { await skills.publish({ ...reference, files }); },
         resolveModel: async () => options.modelApiKey === undefined ? {} : { apiKey: options.modelApiKey },
         readPrompt: async (reference) => {
             const content = prompts.get(promptKey(reference));

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export { createAgentSpecExecutor, type AgentSpecExecutorDeclaration } from './ag
 export { agentResourceVersionSchema, agentVersionSchema, type AgentVersion, type AgentVersionCommonPromptReference, type AgentVersionExecutor, type AgentVersionExecutorReference, type AgentVersionMemberReference, type AgentVersionModel, type AgentVersionPorts, type AgentVersionPromptReference, type AgentVersionToolReference, type CreateResolvedAgentSpecOptions, type ResolveAgentVersionInput, type ResolvedAgent, type ResolvedAgentMember, type ResolvedAgentModel, type ResolvedAgentSnapshot, type ResolvedAgentVersion, } from './agent_version.ts';
 export { createAgentVersionResolver } from './agent_version_resolver.ts';
 export { createFakeAgentVersionPorts } from './fake_agent_version_ports.ts';
+export { createSkillPackages, type SkillPackageFiles, type SkillPackageReference, type SkillPackageSummary, type ResolvedSkillPackage } from './skill_packages.ts';

package/dist/index.js

@@ -3,3 +3,4 @@ export { createAgentSpecExecutor } from './agent_spec_executor.js';
 export { agentResourceVersionSchema, agentVersionSchema, } from './agent_version.js';
 export { createAgentVersionResolver } from './agent_version_resolver.js';
 export { createFakeAgentVersionPorts } from './fake_agent_version_ports.js';
+export { createSkillPackages } from './skill_packages.js';

package/dist/skill_packages.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type VersionedResourceStore } from '@onco-foundry/resource-versioning';
+declare const filesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    encoding: z.ZodEnum<{
+        base64: "base64";
+        utf8: "utf8";
+    }>;
+    content: z.ZodString;
+}, z.core.$strict>>;
+export type SkillPackageFiles = z.infer<typeof filesSchema>;
+export type SkillPackageReference = {
+    id: string;
+    version: string;
+};
+export type SkillPackageSummary = SkillPackageReference & {
+    name: string;
+    description: string;
+    checksum: string;
+};
+export type ResolvedSkillPackage = SkillPackageSummary & {
+    instructions: string;
+    files: SkillPackageFiles;
+};
+/** 文件是数据，不接收文件系统路径或链接；实际只读挂载由宿主运行器负责。 */
+export declare const createSkillPackages: (deps: {
+    storeFor(id: string): VersionedResourceStore;
+}) => {
+    publish(input: SkillPackageReference & {
+        files: SkillPackageFiles;
+    }): Promise<ResolvedSkillPackage>;
+    read: (reference: SkillPackageReference) => Promise<ResolvedSkillPackage>;
+};
+export {};

package/dist/skill_packages.js

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+import { parse } from 'yaml';
+import { z } from 'zod';
+import { createVersionedResource, loadActiveVersionedResource } from '@onco-foundry/resource-versioning';
+import { AppError } from '@onco-foundry/errors';
+const idSchema = z.string().regex(/^[a-z][a-z0-9-]{0,79}$/);
+const versionSchema = z.string().regex(/^v[1-9]\d{0,8}$/);
+const fileSchema = z.object({ encoding: z.enum(['utf8', 'base64']), content: z.string().max(24 * 1024 * 1024) }).strict();
+const filesSchema = z.record(z.string(), fileSchema);
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+/** 文件是数据，不接收文件系统路径或链接；实际只读挂载由宿主运行器负责。 */
+export const createSkillPackages = (deps) => {
+    const inspect = (input) => {
+        const files = filesSchema.parse(input);
+        const paths = Object.keys(files).sort();
+        if (paths.length === 0 || paths.length > 128)
+            throw new AppError('技能包文件数必须为 1 到 128');
+        let size = 0;
+        for (const path of paths) {
+            const parts = path.split('/');
+            if (path.length > 240 || parts.some(part => !part || part === '.' || part === '..' || /[\\:\x00-\x1f\x7f]/.test(part))) {
+                throw new AppError(`技能包文件路径非法：${path}`);
+            }
+            if (parts.at(-1) === 'SKILL.md' && path !== 'SKILL.md')
+                throw new AppError('技能包只能在根目录包含一个 SKILL.md');
+            for (let count = 1; count < parts.length; count++) {
+                if (Object.hasOwn(files, parts.slice(0, count).join('/')))
+                    throw new AppError(`技能包文件与目录冲突：${path}`);
+            }
+            const file = files[path];
+            const bytes = Buffer.from(file.content, file.encoding === 'utf8' ? 'utf8' : 'base64');
+            if (file.encoding === 'base64' && bytes.toString('base64') !== file.content)
+                throw new AppError(`技能包 base64 非法：${path}`);
+            size += bytes.byteLength;
+            if (size > 16 * 1024 * 1024)
+                throw new AppError('技能包解码后不能超过 16 MiB');
+        }
+        const skill = files['SKILL.md'];
+        if (!skill || skill.encoding !== 'utf8' || Buffer.byteLength(skill.content) > 100_000)
+            throw new AppError('技能包必须包含 UTF-8 SKILL.md，且不能超过 100000 字节');
+        const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]+)$/.exec(skill.content);
+        if (!match)
+            throw new AppError('SKILL.md 必须包含 YAML frontmatter 和正文');
+        const metadata = z.object({ name: idSchema, description: z.string().trim().min(1).max(2048) }).passthrough().parse(parse(match[1], { maxAliasCount: 0, uniqueKeys: true }));
+        const instructions = match[2].trim();
+        if (!instructions)
+            throw new AppError('SKILL.md 正文不能为空');
+        return { name: metadata.name, description: metadata.description, instructions, files: Object.fromEntries(paths.map(path => [path, files[path]])) };
+    };
+    const read = async (reference) => {
+        idSchema.parse(reference.id);
+        versionSchema.parse(reference.version);
+        const loaded = await loadActiveVersionedResource({ store: deps.storeFor(reference.id), versionOverride: reference.version });
+        const content = loaded.files.get('skill.json');
+        if (content === undefined || Buffer.byteLength(content) > 24 * 1024 * 1024)
+            throw new AppError('技能包缺少 skill.json 或内容过大');
+        const bundle = z.object({ schemaVersion: z.literal('skill-package-v1'), files: filesSchema }).strict().parse(JSON.parse(content));
+        return { ...reference, ...inspect(bundle.files), checksum: hash(content) };
+    };
+    return {
+        async publish(input) {
+            idSchema.parse(input.id);
+            versionSchema.parse(input.version);
+            const inspected = inspect(input.files);
+            const content = JSON.stringify({ schemaVersion: 'skill-package-v1', files: inspected.files });
+            if (Buffer.byteLength(content) > 24 * 1024 * 1024)
+                throw new AppError('技能包编码后不能超过 24 MiB');
+            await createVersionedResource({ store: deps.storeFor(input.id), version: input.version,
+                files: { 'skill.json': content } });
+            return await read({ id: input.id, version: input.version });
+        },
+        read,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onco-foundry/agent-template",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "files": [
     "dist"
@@ -13,12 +13,13 @@
   },
   "dependencies": {
     "agent-lattice": "0.26.0",
+    "yaml": "^2.9.1",
     "zod": "^4.4.3",
     "@onco-foundry/agent-runtime": "0.3.0",
+    "@onco-foundry/errors": "0.1.1",
     "@onco-foundry/capability-registry": "0.1.1",
     "@onco-foundry/resource-versioning": "0.3.0",
-    "@onco-foundry/trace-port": "0.3.3",
-    "@onco-foundry/errors": "0.1.1"
+    "@onco-foundry/trace-port": "0.3.3"
   },
   "publishConfig": {
     "access": "public"