@ct-agents/prompts 0.0.1

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ct-agents/prompts",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing.js": "./src/testing.ts"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@ct-agents/protocol": "0.0.1",
+    "@ct-agents/store": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,532 @@
+import { randomUUID } from 'node:crypto';
+import type { SqlPool } from '@ct-agents/store';
+import type {
+  AssemblePromptInput,
+  CreatePromptFragmentInput,
+  GeneratorRegistry,
+  PromptFragmentStore,
+  PromptFragmentView,
+  PromptGenerator,
+  PromptRegistry,
+  ResourceSlots,
+  UpdatePromptFragmentInput,
+} from '@ct-agents/protocol';
+
+type PromptFragmentRow = {
+  app_id?: string | null;
+  id: string;
+  version: number;
+  name: string;
+  description?: string | null;
+  content: string;
+  enabled: boolean;
+  created_at?: string | Date | null;
+  updated_at?: string | Date | null;
+};
+
+function assertFragmentContent(name: string, content: string) {
+  if (!name.trim()) {
+    throw new Error('name 为必填');
+  }
+  if (!content.trim()) {
+    throw new Error('content 为必填');
+  }
+}
+
+function toIsoString(value: string | Date | null | undefined) {
+  if (!value) {
+    return undefined;
+  }
+
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+function mapPromptFragmentRow(row: PromptFragmentRow): PromptFragmentView {
+  return {
+    appId: row.app_id ?? null,
+    id: row.id,
+    version: row.version,
+    name: row.name,
+    ...(row.description?.trim() ? { description: row.description.trim() } : {}),
+    content: row.content,
+    enabled: row.enabled,
+    source: {
+      kind: 'persisted',
+    },
+    createdAt: toIsoString(row.created_at),
+    updatedAt: toIsoString(row.updated_at),
+  };
+}
+
+export type PostgresPromptFragmentStoreOptions = {
+  createId?: () => string;
+};
+
+export class PostgresPromptFragmentStore implements PromptFragmentStore {
+  private readonly createId: () => string;
+
+  constructor(
+    private readonly pool: SqlPool,
+    options: PostgresPromptFragmentStoreOptions = {},
+  ) {
+    this.createId = options.createId ?? (() => `persisted:${randomUUID()}`);
+  }
+
+  async list(query?: { appId?: string; includeGlobal?: boolean }) {
+    const client = await this.pool.connect();
+
+    try {
+      const conditions = ['enabled = true'];
+      const params: unknown[] = [];
+      if (query?.appId) {
+        params.push(query.appId);
+        conditions.push(query.includeGlobal ? '(app_id = $1 or app_id is null)' : 'app_id = $1');
+      }
+      const result = await client.query<PromptFragmentRow>(
+        `
+          select
+            app_id,
+            id,
+            version,
+            name,
+            description,
+            content,
+            enabled,
+            created_at,
+            updated_at
+          from agent.agent_prompt_fragments
+          where ${conditions.join(' and ')}
+          order by updated_at desc, id desc
+        `,
+        params,
+      );
+
+      return result.rows.map(mapPromptFragmentRow);
+    } finally {
+      client.release();
+    }
+  }
+
+  async get(id: string) {
+    const client = await this.pool.connect();
+
+    try {
+      const result = await client.query<PromptFragmentRow>(
+        `
+          select
+            app_id,
+            id,
+            version,
+            name,
+            description,
+            content,
+            enabled,
+            created_at,
+            updated_at
+          from agent.agent_prompt_fragments
+          where id = $1
+          limit 1
+        `,
+        [id],
+      );
+
+      return result.rows[0] ? mapPromptFragmentRow(result.rows[0]) : null;
+    } finally {
+      client.release();
+    }
+  }
+
+  async create(input: CreatePromptFragmentInput) {
+    assertFragmentContent(input.name, input.content);
+    const client = await this.pool.connect();
+
+    try {
+      const result = await client.query<PromptFragmentRow>(
+        `
+          insert into agent.agent_prompt_fragments (
+            app_id,
+            id,
+            name,
+            description,
+            content,
+            enabled
+          )
+          values ($1, $2, $3, $4, $5, $6)
+          returning
+            app_id,
+            id,
+            version,
+            name,
+            description,
+            content,
+            enabled,
+            created_at,
+            updated_at
+        `,
+        [
+          input.appId ?? null,
+          this.createId(),
+          input.name.trim(),
+          input.description?.trim() || null,
+          input.content.trim(),
+          input.enabled ?? true,
+        ],
+      );
+
+      return mapPromptFragmentRow(result.rows[0]);
+    } finally {
+      client.release();
+    }
+  }
+
+  async update(input: UpdatePromptFragmentInput) {
+    const current = await this.get(input.id);
+    if (!current) {
+      throw new Error(`Prompt fragment not found: ${input.id}`);
+    }
+
+    const name = input.name === undefined ? current.name : input.name.trim();
+    const description = input.description === undefined
+      ? current.description ?? null
+      : (input.description.trim() || null);
+    const content = input.content === undefined ? current.content : input.content.trim();
+    assertFragmentContent(name, content);
+    const client = await this.pool.connect();
+
+    try {
+      const result = await client.query<PromptFragmentRow>(
+        `
+          update agent.agent_prompt_fragments
+          set
+            name = $2,
+            description = $3,
+            content = $4,
+            enabled = $5,
+            version = version + 1,
+            updated_at = now()
+          where id = $1 and version = $6
+          returning
+            app_id,
+            id,
+            version,
+            name,
+            description,
+            content,
+            enabled,
+            created_at,
+            updated_at
+        `,
+        [
+          input.id,
+          name,
+          description,
+          content,
+          input.enabled ?? current.enabled,
+          input.baseVersion,
+        ],
+      );
+
+      if (!result.rows[0]) {
+        throw new Error(`VERSION_CONFLICT: Prompt fragment has changed: ${input.id}`);
+      }
+
+      return mapPromptFragmentRow(result.rows[0]);
+    } finally {
+      client.release();
+    }
+  }
+
+  async delete(id: string) {
+    const client = await this.pool.connect();
+
+    try {
+      await client.query(
+        `
+          update agent.agent_prompt_fragments
+          set
+            enabled = false,
+            version = version + 1,
+            updated_at = now()
+          where id = $1
+        `,
+        [id],
+      );
+    } finally {
+      client.release();
+    }
+  }
+}
+
+export type DefaultPromptRegistryDependencies = {
+  store: PromptFragmentStore;
+  generators?: GeneratorRegistry;
+};
+
+export class InMemoryGeneratorRegistry implements GeneratorRegistry {
+  private readonly generators = new Map<string, PromptGenerator>();
+
+  get(id: string) {
+    return this.generators.get(id);
+  }
+
+  register(generator: PromptGenerator) {
+    if (this.generators.has(generator.id)) {
+      throw new Error(`Duplicate generator id: ${generator.id}`);
+    }
+    this.generators.set(generator.id, generator);
+  }
+}
+
+function readContextValue(context: Record<string, unknown>, path: string) {
+  if (path === '.') {
+    return context;
+  }
+
+  return path
+    .split('.')
+    .reduce<unknown>((current, segment) => (
+      current && typeof current === 'object' && !Array.isArray(current)
+        ? (current as Record<string, unknown>)[segment]
+        : undefined
+    ), context);
+}
+
+type TemplateNode =
+  | { type: 'text'; value: string }
+  | { type: 'variable'; key: string }
+  | { type: 'section'; key: string; inverted: boolean; children: TemplateNode[] };
+
+const templateTagPattern = /\{\{\s*([#^/]?)\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+
+function parseTemplate(template: string) {
+  const root: TemplateNode[] = [];
+  const sectionStack: Array<{ key: string; inverted: boolean; children: TemplateNode[] }> = [];
+  let cursor = 0;
+
+  const appendNode = (node: TemplateNode) => {
+    if (sectionStack.length > 0) {
+      sectionStack[sectionStack.length - 1]?.children.push(node);
+      return;
+    }
+    root.push(node);
+  };
+
+  for (const match of template.matchAll(templateTagPattern)) {
+    const fullMatch = match[0];
+    const marker = match[1] ?? '';
+    const key = match[2] ?? '';
+    const matchIndex = match.index ?? 0;
+
+    if (matchIndex > cursor) {
+      appendNode({
+        type: 'text',
+        value: template.slice(cursor, matchIndex),
+      });
+    }
+
+    cursor = matchIndex + fullMatch.length;
+
+    if (marker === '#') {
+      sectionStack.push({
+        key,
+        inverted: false,
+        children: [],
+      });
+      continue;
+    }
+
+    if (marker === '^') {
+      sectionStack.push({
+        key,
+        inverted: true,
+        children: [],
+      });
+      continue;
+    }
+
+    if (marker === '/') {
+      const closed = sectionStack.pop();
+      if (!closed || closed.key !== key) {
+        throw new Error(`Invalid prompt template section close tag: ${key}`);
+      }
+
+      appendNode({
+        type: 'section',
+        key,
+        inverted: closed.inverted,
+        children: closed.children,
+      });
+      continue;
+    }
+
+    appendNode({
+      type: 'variable',
+      key,
+    });
+  }
+
+  if (cursor < template.length) {
+    appendNode({
+      type: 'text',
+      value: template.slice(cursor),
+    });
+  }
+
+  if (sectionStack.length > 0) {
+    throw new Error(`Invalid prompt template: unclosed section ${sectionStack[sectionStack.length - 1]?.key}`);
+  }
+
+  return root;
+}
+
+function readContextValueFromStack(stack: unknown[], key: string): unknown {
+  if (key === '.') {
+    return stack[stack.length - 1];
+  }
+
+  for (let index = stack.length - 1; index >= 0; index -= 1) {
+    const frame = stack[index];
+    if (frame && typeof frame === 'object' && !Array.isArray(frame)) {
+      const value = readContextValue(frame as Record<string, unknown>, key);
+      if (value !== undefined) {
+        return value;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function isTruthySectionValue(value: unknown) {
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  return Boolean(value);
+}
+
+function renderNodes(nodes: TemplateNode[], stack: unknown[]): string {
+  return nodes.map((node) => {
+    if (node.type === 'text') {
+      return node.value;
+    }
+
+    if (node.type === 'variable') {
+      const value = readContextValueFromStack(stack, node.key);
+      return value === undefined || value === null ? '' : String(value);
+    }
+
+    const value = readContextValueFromStack(stack, node.key);
+    if (node.inverted) {
+      return isTruthySectionValue(value) ? '' : renderNodes(node.children, stack);
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((item) => renderNodes(
+        node.children,
+        item && typeof item === 'object' ? [...stack, item] : [...stack, item],
+      )).join('');
+    }
+
+    if (!isTruthySectionValue(value)) {
+      return '';
+    }
+
+    if (value && typeof value === 'object') {
+      return renderNodes(node.children, [...stack, value]);
+    }
+
+    return renderNodes(node.children, stack);
+  }).join('');
+}
+
+function renderTemplate(template: string, context: Record<string, unknown>) {
+  return renderNodes(parseTemplate(template), [context]);
+}
+
+export class DefaultPromptRegistry implements PromptRegistry {
+  private readonly generators: GeneratorRegistry;
+
+  constructor(private readonly dependencies: DefaultPromptRegistryDependencies) {
+    this.generators = dependencies.generators ?? new InMemoryGeneratorRegistry();
+  }
+
+  async assemblePrompt(input: AssemblePromptInput) {
+    const persisted = await this.dependencies.store.list(input.appId
+      ? { appId: input.appId, includeGlobal: true }
+      : undefined);
+    const byId = new Map<string, PromptFragmentView>(
+      persisted.map((fragment) => [`fragment:${fragment.id}`, fragment]),
+    );
+    const context = {
+      ...(input.harnessMetadata ?? {}),
+      ...(input.sessionMetadata ?? {}),
+    };
+    const collected: string[] = [];
+
+    for (const fragmentId of input.promptFragmentIds ?? []) {
+      if (fragmentId.startsWith('fragment:')) {
+        const persistedFragment = byId.get(fragmentId);
+        if (persistedFragment?.enabled) {
+          collected.push(renderTemplate(persistedFragment.content, context));
+        }
+        continue;
+      }
+
+      if (fragmentId.startsWith('generator:')) {
+        const generatorId = fragmentId.slice('generator:'.length);
+        const generator = this.generators.get(generatorId);
+        if (!generator) {
+          continue;
+        }
+
+        const generated = await generator.generate({
+          metadata: context,
+          resources: input.resources ?? {},
+        });
+        if (generated.trim()) {
+          collected.push(generated.trim());
+        }
+      }
+    }
+
+    for (const fragment of input.dynamicFragments ?? []) {
+      if (fragment.trim()) {
+        collected.push(fragment.trim());
+      }
+    }
+
+    return collected
+      .map((fragment) => fragment.trim())
+      .filter(Boolean)
+      .join('\n--------------\n');
+  }
+
+  async listPromptFragments(query?: Parameters<PromptFragmentStore['list']>[0]) {
+    const persisted = await this.dependencies.store.list(query);
+    return [...persisted];
+  }
+
+  async getPromptFragment(id: string) {
+    return this.dependencies.store.get(id);
+  }
+
+  async createPromptFragment(input: CreatePromptFragmentInput) {
+    return this.dependencies.store.create(input);
+  }
+
+  async updatePromptFragment(input: UpdatePromptFragmentInput) {
+    return this.dependencies.store.update(input);
+  }
+
+  async deletePromptFragment(id: string) {
+    return this.dependencies.store.delete(id);
+  }
+
+}
+
+export function createDefaultPromptRegistry(dependencies: DefaultPromptRegistryDependencies) {
+  return new DefaultPromptRegistry(dependencies);
+}
+
+export { PostgresSkillStore } from './postgres-skill-store.js';
+export * from './load-skill.js';

package/src/load-skill.ts

@@ -0,0 +1,287 @@
+import { z } from 'zod';
+import type {
+  HarnessConfig,
+  HarnessConfigStore,
+  RuntimeSkillView,
+  SkillResource,
+  SkillStore,
+  SkillView,
+  ToolDescriptor,
+  ToolDescriptorContext,
+  ToolHandler,
+} from '@ct-agents/protocol';
+
+export const loadSkillToolInputSchema = z.object({
+  skillName: z.string().trim().min(1),
+}).strict();
+
+export type LoadSkillToolInput = z.infer<typeof loadSkillToolInputSchema>;
+
+export type LoadSkillCatalogItem = {
+  name: string;
+  description: string;
+  version: number;
+};
+
+export type LoadedSkill = LoadSkillCatalogItem & {
+  instructions: string;
+};
+
+export type LoadSkillToolResult = {
+  status: 'ok' | 'warning';
+  message?: string;
+  skill?: LoadedSkill;
+};
+
+export type LoadSkillToolDeps = {
+};
+
+const catalogItemSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  version: z.number().int().positive(),
+}).strict();
+
+export const loadSkillToolResultSchema: z.ZodType<LoadSkillToolResult> = z.object({
+  status: z.enum(['ok', 'warning']),
+  message: z.string().optional(),
+  skill: catalogItemSchema.extend({
+    instructions: z.string(),
+  }).strict().optional(),
+}).strict();
+
+function getErrorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function toCatalogItem(skill: Pick<RuntimeSkillView, 'name' | 'description' | 'version'>): LoadSkillCatalogItem {
+  return {
+    name: skill.name,
+    description: skill.description,
+    version: skill.version,
+  };
+}
+
+function toLoadedSkill(skill: RuntimeSkillView): LoadedSkill {
+  return {
+    ...toCatalogItem(skill),
+    instructions: skill.instructions,
+  };
+}
+
+function readHarnessSkillName(value: Record<string, unknown>) {
+  const name = value.name;
+  return typeof name === 'string' && name.trim() ? name.trim() : null;
+}
+
+/** 解析 harness 配置中关联的 skill name（去重、保序）。 */
+export function resolveHarnessSkillNames(harness: HarnessConfig) {
+  const skillNames: string[] = [];
+  const seen = new Set<string>();
+
+  for (const entry of harness.skills) {
+    const skillName = readHarnessSkillName(entry);
+    if (!skillName || seen.has(skillName)) {
+      continue;
+    }
+
+    seen.add(skillName);
+    skillNames.push(skillName);
+  }
+
+  return skillNames;
+}
+
+async function readHarnessConfig(input: {
+  harnessStore: HarnessConfigStore;
+  appId?: string;
+  harnessId: string;
+  harnessVersion: number;
+}) {
+  return input.harnessStore.get({
+    appId: input.appId,
+    id: input.harnessId,
+    version: input.harnessVersion,
+  });
+}
+
+/** 读取 harness 关联且当前启用的 Skill 目录（仅元数据，不含 instructions）。 */
+export async function readAvailableSkills(input: {
+  skillStore: SkillStore;
+  skillNames: string[];
+}) {
+  const enabledSkills = await input.skillStore.list();
+  const enabledByName = new Map(enabledSkills.map((skill) => [skill.name, skill]));
+  return input.skillNames
+    .map((skillName) => enabledByName.get(skillName))
+    .filter((skill): skill is SkillView => Boolean(skill))
+    .map(toCatalogItem);
+}
+
+/**
+ * 构造 harness 关联 Skill 的 markdown 目录，供 {@link createLoadSkillToolHandler} 注入 description。
+ *
+ * 只列关联且启用的 Skill；读取失败或无可用 Skill 时返回空串，让调用方回退静态 description。
+ */
+export async function buildHarnessSkillCatalogMarkdown(input: {
+  harnessStore: HarnessConfigStore;
+  skillStore: SkillStore;
+  appId?: string;
+  harnessId: string;
+  harnessVersion: number;
+}): Promise<string> {
+  const harnessConfig = await readHarnessConfig(input);
+  if (!harnessConfig) {
+    return '';
+  }
+
+  const items = await readAvailableSkills({
+    skillStore: input.skillStore,
+    skillNames: resolveHarnessSkillNames(harnessConfig),
+  });
+  if (items.length === 0) {
+    return '';
+  }
+
+  return items
+    .map((item) => `- ${item.name}：${item.description}`)
+    .join('\n');
+}
+
+function warning(message: string): LoadSkillToolResult {
+  return { status: 'warning', message };
+}
+
+const loadSkillDescriptor: ToolDescriptor = {
+  name: 'load-skill',
+  title: '读取 Skill',
+  description: [
+    '按 skillName 读取一个 Skill 的完整 instructions。',
+    '当前 harness 可用的 Skill 目录已注入本工具说明（见下方）。',
+  ].join('\n'),
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['skillName'],
+    properties: {
+      skillName: {
+        type: 'string',
+        description: '要读取的 Skill 名称（必填，即 Skill 唯一标识）。',
+      },
+    },
+  },
+  resultSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['status'],
+    properties: {
+      status: { enum: ['ok', 'warning'] },
+      message: { type: 'string' },
+      skill: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['name', 'description', 'instructions', 'version'],
+        properties: {
+          name: { type: 'string' },
+          description: { type: 'string' },
+          instructions: { type: 'string' },
+          version: { type: 'integer' },
+        },
+      },
+    },
+  },
+  annotations: {
+    readOnly: true,
+    idempotent: true,
+    openWorld: false,
+    destructive: false,
+  },
+  requiredResources: ['skills'],
+};
+
+/**
+ * 按 skillId 读取当前 harness 关联的 Skill。
+ *
+ * 工具本身只「按 id 读一个 Skill」；可用 Skill 目录由 {@link resolveDescriptor} 注入自身 description。
+ * 读取失败、未关联、禁用或缺失都返回 warning 给模型继续处理，不抛业务错误，
+ * 避免因为可选能力不可用而让整个 session 进入 error。
+ */
+async function buildResourceSkillCatalogMarkdown(skills: SkillResource): Promise<string> {
+  const items = await skills.list();
+  if (items.length === 0) {
+    return '';
+  }
+  return items
+    .map((item) => `- ${item.name}：${item.description}`)
+    .join('\n');
+}
+
+export function createLoadSkillToolHandler(_deps: LoadSkillToolDeps = {}): ToolHandler<LoadSkillToolInput, LoadSkillToolResult> {
+  return {
+    descriptor: loadSkillDescriptor,
+    // 把当前 resource 已过滤的 Skill 目录注入自身 description；读取失败/无可用 Skill 时回退静态 descriptor。
+    async resolveDescriptor(context: ToolDescriptorContext) {
+      const skills = context.resources.skills;
+      if (!skills) {
+        return loadSkillDescriptor;
+      }
+      try {
+        const catalog = await buildResourceSkillCatalogMarkdown(skills);
+        if (!catalog.trim()) {
+          return loadSkillDescriptor;
+        }
+        // 把可用 Skill 目录拼到自身 description 末尾，供模型决定调用哪个 skillId。
+        const heading = '当前 harness 可用 Skill 目录（传 skillName 调 load-skill 读完整 instructions）：';
+        return {
+          ...loadSkillDescriptor,
+          description: [loadSkillDescriptor.description, heading, catalog.trim()].join('\n\n'),
+        };
+      } catch {
+        return loadSkillDescriptor;
+      }
+    },
+    inputSchema: loadSkillToolInputSchema,
+    resultSchema: loadSkillToolResultSchema,
+    async execute(input, context) {
+      const skills = context.resources.skills;
+      if (!skills) {
+        return {
+          status: 'completed',
+          modelResult: warning('load-skill 未配置 skills resource。'),
+        };
+      }
+
+      let skill: RuntimeSkillView | null;
+      try {
+        skill = await skills.get(input.skillName);
+      } catch (error) {
+        return {
+          status: 'completed',
+          modelResult: warning(`读取 Skill 失败：${getErrorMessage(error)}`),
+        };
+      }
+
+      if (!skill) {
+        return {
+          status: 'completed',
+          modelResult: warning(`Skill 不存在：${input.skillName}`),
+        };
+      }
+
+      if (!skill.enabled) {
+        return {
+          status: 'completed',
+          modelResult: warning(`Skill 已禁用：${input.skillName}`),
+        };
+      }
+
+      return {
+        status: 'completed',
+        modelResult: {
+          status: 'ok',
+          skill: toLoadedSkill(skill),
+        },
+      };
+    },
+  };
+}

package/src/markdown-frontmatter.ts

@@ -0,0 +1,78 @@
+/**
+ * 解析 frontmatter 中的单个标量值。
+ *
+ * 只支持当前 agent/prompt 资产需要的布尔、数字、null、JSON 对象/数组和字符串。
+ */
+function parseFrontmatterScalar(value: string): boolean | number | string | null | object | unknown[] {
+  const normalized = value.trim();
+  if (!normalized) {
+    return '';
+  }
+
+  if (normalized === 'true') {
+    return true;
+  }
+
+  if (normalized === 'false') {
+    return false;
+  }
+
+  if (normalized === 'null') {
+    return null;
+  }
+
+  if (
+    normalized.startsWith('{')
+    || normalized.startsWith('[')
+    || normalized.startsWith('"')
+  ) {
+    return JSON.parse(normalized) as object | unknown[];
+  }
+
+  const numericValue = Number(normalized);
+  if (Number.isFinite(numericValue) && String(numericValue) === normalized) {
+    return numericValue;
+  }
+
+  return normalized;
+}
+
+/**
+ * 解析带 YAML 风格 frontmatter 的 Markdown 资产。
+ */
+export function parseMarkdownFrontmatter(content: string) {
+  const normalizedContent = content.replace(/\r\n/g, '\n');
+  if (!normalizedContent.startsWith('---\n')) {
+    throw new Error('Markdown frontmatter 缺失');
+  }
+
+  const closingIndex = normalizedContent.indexOf('\n---\n', 4);
+  if (closingIndex === -1) {
+    throw new Error('Markdown frontmatter 未正确闭合');
+  }
+
+  const rawFrontmatter = normalizedContent.slice(4, closingIndex).trim();
+  const body = normalizedContent.slice(closingIndex + 5).trim();
+  const frontmatter: Record<string, unknown> = {};
+
+  for (const line of rawFrontmatter.split('\n')) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+      continue;
+    }
+
+    const separatorIndex = trimmedLine.indexOf(':');
+    if (separatorIndex === -1) {
+      throw new Error(`无效的 frontmatter 行：${trimmedLine}`);
+    }
+
+    const key = trimmedLine.slice(0, separatorIndex).trim();
+    const value = trimmedLine.slice(separatorIndex + 1).trim();
+    frontmatter[key] = parseFrontmatterScalar(value);
+  }
+
+  return {
+    frontmatter,
+    body,
+  };
+}

package/src/postgres-skill-store.ts

@@ -0,0 +1,158 @@
+import type { SqlPool } from '@ct-agents/store';
+import type {
+  CreateSkillInput,
+  SkillListQuery,
+  SkillStore,
+  SkillView,
+  UpdateSkillInput,
+} from '@ct-agents/protocol';
+
+type SkillRow = {
+  app_id?: string | null;
+  version: number;
+  name: string;
+  description: string;
+  instructions: string;
+  enabled: boolean;
+  created_at?: string | Date | null;
+  updated_at?: string | Date | null;
+};
+
+function toIsoString(value: string | Date | null | undefined) {
+  if (!value) return undefined;
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+function mapSkillRow(row: SkillRow): SkillView {
+  return {
+    appId: row.app_id ?? null,
+    version: row.version,
+    name: row.name,
+    description: row.description,
+    instructions: row.instructions,
+    enabled: row.enabled,
+    createdAt: toIsoString(row.created_at),
+    updatedAt: toIsoString(row.updated_at),
+  };
+}
+
+export class PostgresSkillStore implements SkillStore {
+  constructor(private readonly pool: SqlPool) {}
+
+  async list(query?: SkillListQuery): Promise<SkillView[]> {
+    const client = await this.pool.connect();
+    try {
+      // 与 PostgresPromptFragmentStore 保持一致的 app 归属过滤：
+      // 指定 appId 时按 app 精确过滤，includeGlobal 时额外纳入 global（app_id is null）。
+      const conditions = ['enabled = true'];
+      const params: unknown[] = [];
+      if (query?.appId) {
+        params.push(query.appId);
+        conditions.push(query.includeGlobal ? '(app_id = $1 or app_id is null)' : 'app_id = $1');
+      }
+      const result = await client.query<SkillRow>(`
+        select app_id, version, name, description, instructions, enabled, created_at, updated_at
+        from agent.agent_skills
+        where ${conditions.join(' and ')}
+        order by name asc
+      `, params);
+      return result.rows.map(mapSkillRow);
+    } finally {
+      client.release();
+    }
+  }
+
+  async get(name: string): Promise<SkillView | null> {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query<SkillRow>(`
+        select app_id, version, name, description, instructions, enabled, created_at, updated_at
+        from agent.agent_skills
+        where name = $1
+        limit 1
+      `, [name]);
+      return result.rows[0] ? mapSkillRow(result.rows[0]) : null;
+    } finally {
+      client.release();
+    }
+  }
+
+  async create(input: CreateSkillInput): Promise<SkillView> {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query<SkillRow>(`
+        insert into agent.agent_skills (
+          app_id,
+          name,
+          description,
+          instructions,
+          enabled
+        )
+        values ($1, $2, $3, $4, $5)
+        returning app_id, version, name, description, instructions, enabled, created_at, updated_at
+      `, [
+        input.appId ?? null,
+        input.name.trim(),
+        input.description.trim(),
+        input.instructions.trim(),
+        input.enabled ?? true,
+      ]);
+      return mapSkillRow(result.rows[0]);
+    } finally {
+      client.release();
+    }
+  }
+
+  async update(input: UpdateSkillInput): Promise<SkillView> {
+    const current = await this.get(input.name);
+    if (!current) {
+      throw new Error(`Skill not found: ${input.name}`);
+    }
+
+    const client = await this.pool.connect();
+    try {
+      // name 为主键不可改，仅作定位；description/instructions/enabled 可更新。
+      const result = await client.query<SkillRow>(`
+        update agent.agent_skills
+        set
+          description = $2,
+          instructions = $3,
+          enabled = $4,
+          version = version + 1,
+          updated_at = now()
+        where name = $1 and version = $5
+        returning app_id, version, name, description, instructions, enabled, created_at, updated_at
+      `, [
+        input.name,
+        input.description === undefined ? current.description : input.description.trim(),
+        input.instructions === undefined ? current.instructions : input.instructions.trim(),
+        input.enabled ?? current.enabled,
+        input.baseVersion,
+      ]);
+
+      if (!result.rows[0]) {
+        throw new Error(`VERSION_CONFLICT: Skill has changed: ${input.name}`);
+      }
+
+      return mapSkillRow(result.rows[0]);
+    } finally {
+      client.release();
+    }
+  }
+
+  async delete(name: string): Promise<void> {
+    const client = await this.pool.connect();
+    try {
+      await client.query(`
+        update agent.agent_skills
+        set
+          enabled = false,
+          version = version + 1,
+          updated_at = now()
+        where name = $1
+      `, [name]);
+    } finally {
+      client.release();
+    }
+  }
+}

package/src/testing.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  CreatePromptFragmentInput,
+  CreateSkillInput,
+  PromptFragmentStore,
+  PromptFragmentView,
+  SkillStore,
+  SkillView,
+  UpdateSkillInput,
+  UpdatePromptFragmentInput,
+} from '@ct-agents/protocol';
+import {
+  DefaultPromptRegistry,
+  type DefaultPromptRegistryDependencies,
+} from './index.js';
+
+export class InMemoryPromptFragmentStore implements PromptFragmentStore {
+  private readonly fragments = new Map<string, PromptFragmentView>();
+
+  async list(query?: { appId?: string; includeGlobal?: boolean }) {
+    return Array.from(this.fragments.values())
+      .filter((fragment) => fragment.enabled)
+      .filter((fragment) => {
+        if (!query?.appId) {
+          return true;
+        }
+        return query.includeGlobal
+          ? fragment.appId === query.appId || fragment.appId === null
+          : fragment.appId === query.appId;
+      })
+      .map((fragment) => structuredClone(fragment))
+      .sort((left, right) => (right.updatedAt ?? '').localeCompare(left.updatedAt ?? ''));
+  }
+
+  async get(id: string) {
+    const fragment = this.fragments.get(id);
+    return fragment ? structuredClone(fragment) : null;
+  }
+
+  async create(input: CreatePromptFragmentInput) {
+    const now = new Date().toISOString();
+    const fragment: PromptFragmentView = {
+      appId: input.appId ?? null,
+      id: `persisted:${randomUUID()}`,
+      version: 1,
+      name: input.name.trim(),
+      ...(input.description?.trim() ? { description: input.description.trim() } : {}),
+      content: input.content.trim(),
+      enabled: input.enabled ?? true,
+      source: {
+        kind: 'persisted',
+      },
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.fragments.set(fragment.id, fragment);
+    return structuredClone(fragment);
+  }
+
+  async update(input: UpdatePromptFragmentInput) {
+    const current = this.fragments.get(input.id);
+    if (!current) {
+      throw new Error(`Prompt fragment not found: ${input.id}`);
+    }
+    if (current.version !== input.baseVersion) {
+      throw new Error(`VERSION_CONFLICT: Prompt fragment has changed: ${input.id}`);
+    }
+
+    const name = input.name === undefined ? current.name : input.name.trim();
+    const description = input.description === undefined
+      ? current.description
+      : input.description.trim() || undefined;
+    const content = input.content === undefined ? current.content : input.content.trim();
+    const next: PromptFragmentView = {
+      ...current,
+      version: current.version + 1,
+      name,
+      ...(description !== undefined ? { description } : {}),
+      content,
+      enabled: input.enabled ?? current.enabled,
+      updatedAt: new Date().toISOString(),
+    };
+    this.fragments.set(input.id, next);
+    return structuredClone(next);
+  }
+
+  async delete(id: string) {
+    const current = this.fragments.get(id);
+    if (!current) {
+      return;
+    }
+    this.fragments.set(id, {
+      ...current,
+      version: current.version + 1,
+      enabled: false,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+}
+
+export class InMemorySkillStore implements SkillStore {
+  private readonly skills = new Map<string, SkillView>();
+
+  async list(query?: { appId?: string; includeGlobal?: boolean }) {
+    return Array.from(this.skills.values())
+      .filter((skill) => skill.enabled)
+      .filter((skill) => {
+        if (!query?.appId) {
+          return true;
+        }
+        return query.includeGlobal
+          ? skill.appId === query.appId || skill.appId === null
+          : skill.appId === query.appId;
+      })
+      .map((skill) => structuredClone(skill));
+  }
+
+  async get(name: string) {
+    const skill = this.skills.get(name);
+    return skill ? structuredClone(skill) : null;
+  }
+
+  async create(input: CreateSkillInput) {
+    const now = new Date().toISOString();
+    const skill: SkillView = {
+      appId: input.appId ?? null,
+      name: input.name.trim(),
+      version: 1,
+      description: input.description.trim(),
+      instructions: input.instructions.trim(),
+      enabled: input.enabled ?? true,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.skills.set(skill.name, skill);
+    return structuredClone(skill);
+  }
+
+  async update(input: UpdateSkillInput) {
+    const current = this.skills.get(input.name);
+    if (!current) {
+      throw new Error(`Skill not found: ${input.name}`);
+    }
+    if (current.version !== input.baseVersion) {
+      throw new Error(`VERSION_CONFLICT: Skill has changed: ${input.name}`);
+    }
+
+    const next: SkillView = {
+      ...current,
+      version: current.version + 1,
+      description: input.description === undefined ? current.description : input.description.trim(),
+      instructions: input.instructions === undefined ? current.instructions : input.instructions.trim(),
+      enabled: input.enabled ?? current.enabled,
+      updatedAt: new Date().toISOString(),
+    };
+    this.skills.set(input.name, next);
+    return structuredClone(next);
+  }
+
+  async delete(name: string) {
+    const current = this.skills.get(name);
+    if (!current) {
+      return;
+    }
+    this.skills.set(name, {
+      ...current,
+      version: current.version + 1,
+      enabled: false,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+}
+
+export function createInMemoryPromptRegistry() {
+  return new DefaultPromptRegistry({
+    store: new InMemoryPromptFragmentStore(),
+  } as DefaultPromptRegistryDependencies);
+}
+
+export {
+  createDefaultPromptRegistry,
+  InMemoryGeneratorRegistry,
+} from './index.js';