@ct-agents/prompts 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ct-agents/prompts",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "src"
@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@ct-agents/protocol": "0.1.2",
-    "@ct-agents/store": "0.1.2"
+    "@ct-agents/protocol": "0.1.3",
+    "@ct-agents/store": "0.1.3"
   },
   "publishConfig": {
     "access": "public"

package/src/load-skill.ts

@@ -1,11 +1,8 @@
 import { z } from 'zod';
 import type {
   HarnessConfig,
-  HarnessConfigStore,
   RuntimeSkillView,
   SkillResource,
-  SkillStore,
-  SkillView,
   ToolDescriptor,
   ToolDescriptorContext,
   ToolHandler,
@@ -92,62 +89,6 @@ export function resolveHarnessSkillNames(harness: HarnessConfig) {
   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 };
 }

package/src/postgres-skill-store.ts

@@ -1,6 +1,7 @@
 import type { SqlPool } from '@ct-agents/store';
 import type {
   CreateSkillInput,
+  SkillKey,
   SkillListQuery,
   SkillStore,
   SkillView,
@@ -18,6 +19,13 @@ type SkillRow = {
   updated_at?: string | Date | null;
 };
 
+function isUniqueViolation(error: unknown) {
+  return error !== null
+    && typeof error === 'object'
+    && 'code' in error
+    && error.code === '23505';
+}
+
 function toIsoString(value: string | Date | null | undefined) {
   if (!value) return undefined;
   return value instanceof Date ? value.toISOString() : value;
@@ -46,15 +54,19 @@ export class PostgresSkillStore implements SkillStore {
       // 指定 appId 时按 app 精确过滤，includeGlobal 时额外纳入 global（app_id is null）。
       const conditions = ['enabled = true'];
       const params: unknown[] = [];
-      if (query?.appId) {
+      if (query?.appId === null) {
+        conditions.push('app_id is null');
+      } else if (query?.appId) {
         params.push(query.appId);
         conditions.push(query.includeGlobal ? '(app_id = $1 or app_id is null)' : 'app_id = $1');
       }
+      const effective = query?.resolution === 'effective' && Boolean(query.appId);
       const result = await client.query<SkillRow>(`
-        select app_id, version, name, description, instructions, enabled, created_at, updated_at
+        select ${effective ? 'distinct on (name)' : ''}
+          app_id, version, name, description, instructions, enabled, created_at, updated_at
         from agent.agent_skills
         where ${conditions.join(' and ')}
-        order by name asc
+        order by name asc${effective ? ', (app_id = $1) desc' : ', app_id asc nulls first'}
       `, params);
       return result.rows.map(mapSkillRow);
     } finally {
@@ -62,15 +74,15 @@ export class PostgresSkillStore implements SkillStore {
     }
   }
 
-  async get(name: string): Promise<SkillView | null> {
+  async get(key: SkillKey): 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
+        where app_id is not distinct from $1 and name = $2
         limit 1
-      `, [name]);
+      `, [key.appId, key.name]);
       return result.rows[0] ? mapSkillRow(result.rows[0]) : null;
     } finally {
       client.release();
@@ -98,31 +110,37 @@ export class PostgresSkillStore implements SkillStore {
         input.enabled ?? true,
       ]);
       return mapSkillRow(result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new Error(`SKILL_ALREADY_EXISTS: ${input.name.trim()}`);
+      }
+      throw error;
     } finally {
       client.release();
     }
   }
 
   async update(input: UpdateSkillInput): Promise<SkillView> {
-    const current = await this.get(input.name);
+    const current = await this.get({ appId: input.appId, name: input.name });
     if (!current) {
       throw new Error(`Skill not found: ${input.name}`);
     }
 
     const client = await this.pool.connect();
     try {
-      // name 为主键不可改，仅作定位；description/instructions/enabled 可更新。
+      // app_id + name 是稳定管理身份，仅更新内容与启用状态。
       const result = await client.query<SkillRow>(`
         update agent.agent_skills
         set
-          description = $2,
-          instructions = $3,
-          enabled = $4,
+          description = $3,
+          instructions = $4,
+          enabled = $5,
           version = version + 1,
           updated_at = now()
-        where name = $1 and version = $5
+        where app_id is not distinct from $1 and name = $2 and version = $6
         returning app_id, version, name, description, instructions, enabled, created_at, updated_at
       `, [
+        input.appId,
         input.name,
         input.description === undefined ? current.description : input.description.trim(),
         input.instructions === undefined ? current.instructions : input.instructions.trim(),
@@ -140,7 +158,7 @@ export class PostgresSkillStore implements SkillStore {
     }
   }
 
-  async delete(name: string): Promise<void> {
+  async delete(key: SkillKey): Promise<void> {
     const client = await this.pool.connect();
     try {
       await client.query(`
@@ -149,8 +167,8 @@ export class PostgresSkillStore implements SkillStore {
           enabled = false,
           version = version + 1,
           updated_at = now()
-        where name = $1
-      `, [name]);
+        where app_id is not distinct from $1 and name = $2
+      `, [key.appId, key.name]);
     } finally {
       client.release();
     }

package/src/testing.ts

@@ -4,6 +4,8 @@ import type {
   CreateSkillInput,
   PromptFragmentStore,
   PromptFragmentView,
+  SkillKey,
+  SkillListQuery,
   SkillStore,
   SkillView,
   UpdateSkillInput,
@@ -101,22 +103,38 @@ export class InMemoryPromptFragmentStore implements PromptFragmentStore {
 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())
+  private key(appId: string | null | undefined, name: string) {
+    return JSON.stringify([appId ?? null, name]);
+  }
+
+  async list(query?: SkillListQuery) {
+    const filtered = Array.from(this.skills.values())
       .filter((skill) => skill.enabled)
       .filter((skill) => {
+        if (query?.appId === null) {
+          return skill.appId === null;
+        }
         if (!query?.appId) {
           return true;
         }
         return query.includeGlobal
           ? skill.appId === query.appId || skill.appId === null
           : skill.appId === query.appId;
-      })
-      .map((skill) => structuredClone(skill));
+      });
+    const resolved = query?.resolution === 'effective' && query.appId !== undefined
+      ? Array.from(filtered.reduce((byName, skill) => {
+          const current = byName.get(skill.name);
+          if (!current || (current.appId === null && skill.appId !== null)) {
+            byName.set(skill.name, skill);
+          }
+          return byName;
+        }, new Map<string, SkillView>()).values())
+      : filtered;
+    return resolved.map((skill) => structuredClone(skill));
   }
 
-  async get(name: string) {
-    const skill = this.skills.get(name);
+  async get(input: SkillKey) {
+    const skill = this.skills.get(this.key(input.appId, input.name));
     return skill ? structuredClone(skill) : null;
   }
 
@@ -132,12 +150,17 @@ export class InMemorySkillStore implements SkillStore {
       createdAt: now,
       updatedAt: now,
     };
-    this.skills.set(skill.name, skill);
+    const key = this.key(skill.appId, skill.name);
+    if (this.skills.has(key)) {
+      throw new Error(`SKILL_ALREADY_EXISTS: ${skill.name}`);
+    }
+    this.skills.set(key, skill);
     return structuredClone(skill);
   }
 
   async update(input: UpdateSkillInput) {
-    const current = this.skills.get(input.name);
+    const key = this.key(input.appId, input.name);
+    const current = this.skills.get(key);
     if (!current) {
       throw new Error(`Skill not found: ${input.name}`);
     }
@@ -153,16 +176,17 @@ export class InMemorySkillStore implements SkillStore {
       enabled: input.enabled ?? current.enabled,
       updatedAt: new Date().toISOString(),
     };
-    this.skills.set(input.name, next);
+    this.skills.set(key, next);
     return structuredClone(next);
   }
 
-  async delete(name: string) {
-    const current = this.skills.get(name);
+  async delete(input: SkillKey) {
+    const key = this.key(input.appId, input.name);
+    const current = this.skills.get(key);
     if (!current) {
       return;
     }
-    this.skills.set(name, {
+    this.skills.set(key, {
       ...current,
       version: current.version + 1,
       enabled: false,