@huyooo/ai-chat-core 0.2.44 → 0.3.2

package/src/skills/management/operations.ts

@@ -0,0 +1,256 @@
+/**
+ * Skill 管理核心业务逻辑
+ *
+ * - create / list / inspect / enable / delete 等与 registry、宿主回调协作
+ * - 统一返回 management-results 形状
+ */
+
+import type { SkillMeta } from '../types';
+import type { AssetSource } from '../../governance/types';
+import { splitCommaSeparatedStrings } from '../../internal/management-args';
+import {
+  createActionResult,
+  createCollectionResult,
+  createInspectResult,
+  createToggleResult,
+} from '../../internal/management-results';
+import { createManagedSkillDetail, createManagedSkillSummary } from '../summaries';
+import type { ManagedSkillSummary } from '../types';
+import type { SkillOperationContext } from './types';
+
+interface CreateSkillInput {
+  id: string;
+  name: string;
+  description: string;
+  instructions: string;
+  category: string;
+  tags: string[];
+  icon: string;
+}
+
+interface UpdateSkillInput extends CreateSkillInput {}
+
+interface SkillEnableItem {
+  id: string;
+  enabled: boolean;
+}
+
+function createUserSkillMeta(input: CreateSkillInput): SkillMeta {
+  return {
+    id: input.id,
+    name: input.name,
+    description: input.description,
+    category: input.category,
+    tags: input.tags,
+    icon: input.icon,
+    source: 'user',
+    enabled: true,
+    references: [],
+    scripts: [],
+  };
+}
+
+function ensureMutableUserSkill(
+  ctx: SkillOperationContext,
+  id: string,
+  action: '更新' | '删除',
+): { meta?: SkillMeta; error?: string } {
+  const meta = ctx.registry.get(id);
+  if (!meta) {
+    return {
+      error: `技能 "${id}" 不存在${action === '更新' ? '。如需新建，请使用 skill_create。' : ''}`,
+    };
+  }
+
+  if (meta.source !== 'user') {
+    return { error: `技能 "${id}" 是 ${meta.source} 技能，仅可${action} user 来源的技能` };
+  }
+
+  return { meta };
+}
+
+export function searchManagedSkills(
+  ctx: SkillOperationContext,
+  input: {
+    keyword?: string;
+    category?: string;
+    tags?: string;
+    source?: AssetSource;
+  },
+) {
+  const results = ctx.registry.search({
+    keyword: input.keyword,
+    category: input.category,
+    tags: splitCommaSeparatedStrings(input.tags),
+    source: input.source,
+  });
+
+  if (results.length === 0) {
+    return createCollectionResult('skills', [], {
+      found: 0,
+      hint: '没有匹配的技能。尝试更宽泛的关键词，或省略过滤条件。',
+      categories: ctx.registry.categories(),
+    });
+  }
+
+  return createCollectionResult('skills', results.map(skill => createManagedSkillSummary(skill)), {
+    found: results.length,
+  });
+}
+
+export function listManagedSkills(ctx: SkillOperationContext) {
+  const enabled = ctx.registry.listEnabled();
+  return createCollectionResult('skills', enabled.map(skill => createManagedSkillSummary(skill)));
+}
+
+export async function createManagedSkill(
+  ctx: SkillOperationContext,
+  input: CreateSkillInput,
+) {
+  if (!ctx.onSkillCreate) {
+    return { error: '当前环境未配置技能持久化，无法创建技能' };
+  }
+
+  if (ctx.registry.has(input.id)) {
+    return { error: `技能 "${input.id}" 已存在。如需更新，请使用 skill_update。` };
+  }
+
+  const result = await ctx.onSkillCreate(input);
+  if ('error' in result) {
+    return { error: result.error };
+  }
+
+  const createdMeta = ctx.registry.get(input.id) ?? createUserSkillMeta(input);
+  ctx.registry.add(createdMeta);
+  await ctx.onSkillSetEnabled(input.id, true);
+  const enabledMeta = ctx.registry.get(input.id) ?? { ...createdMeta, enabled: true };
+
+  return createActionResult('created', 'skill', createManagedSkillSummary(enabledMeta), {
+    message: `技能 "${input.name}" 已创建并启用，将在下次对话中生效`,
+  });
+}
+
+export async function updateManagedSkill(
+  ctx: SkillOperationContext,
+  input: UpdateSkillInput,
+) {
+  if (!ctx.onSkillUpdate) {
+    return { error: '当前环境未配置技能持久化，无法更新技能' };
+  }
+
+  const validation = ensureMutableUserSkill(ctx, input.id, '更新');
+  if (validation.error) return { error: validation.error };
+
+  const meta = validation.meta!;
+  const nextMeta: SkillMeta = {
+    ...meta,
+    name: input.name,
+    description: input.description,
+    category: input.category || meta.category,
+    tags: input.tags,
+    icon: input.icon,
+  };
+
+  const result = await ctx.onSkillUpdate({
+    id: input.id,
+    name: nextMeta.name,
+    description: nextMeta.description,
+    instructions: input.instructions,
+    category: nextMeta.category,
+    tags: nextMeta.tags,
+    icon: nextMeta.icon,
+  });
+  if ('error' in result) {
+    return { error: result.error };
+  }
+
+  ctx.registry.add(nextMeta);
+
+  return createActionResult('updated', 'skill', createManagedSkillSummary(nextMeta), {
+    enabled: meta.enabled,
+    message: `技能 "${nextMeta.name}" 已更新${meta.enabled ? '，将在下次对话中生效' : ''}`,
+  });
+}
+
+export async function setManagedSkillsEnabled(
+  ctx: SkillOperationContext,
+  items: SkillEnableItem[],
+) {
+  if (items.length === 0) {
+    return { error: '请传入至少一个技能' };
+  }
+
+  const results: Array<{ id: string; enabled: boolean; error?: string; skill?: ManagedSkillSummary }> = [];
+  for (const item of items) {
+    if (!ctx.registry.has(item.id)) {
+      results.push({ id: item.id, enabled: false, error: `技能不存在: ${item.id}` });
+      continue;
+    }
+
+    ctx.registry.setEnabled(item.id, item.enabled);
+    await ctx.onSkillSetEnabled(item.id, item.enabled);
+    const meta = ctx.registry.get(item.id);
+    results.push({
+      id: item.id,
+      enabled: item.enabled,
+      skill: meta ? createManagedSkillSummary(meta) : undefined,
+    });
+  }
+
+  const updatedCount = results.filter(result => !result.error).length;
+  return createToggleResult(results, {
+    message: `已更新 ${updatedCount} 个技能的状态`,
+  });
+}
+
+export async function deleteManagedSkill(
+  ctx: SkillOperationContext,
+  id: string,
+) {
+  if (!ctx.onSkillDelete) {
+    return { error: '当前环境未配置技能持久化，无法删除技能' };
+  }
+
+  const validation = ensureMutableUserSkill(ctx, id, '删除');
+  if (validation.error) return { error: validation.error };
+
+  const meta = validation.meta!;
+  const result = await ctx.onSkillDelete(id);
+  if (!result.ok) {
+    return { error: result.error ?? '删除失败' };
+  }
+
+  ctx.registry.remove(id);
+
+  return createActionResult('deleted', 'skill', createManagedSkillSummary(meta), {
+    message: `技能 "${meta.name}" 已彻底删除`,
+  });
+}
+
+export async function inspectManagedSkill(
+  ctx: SkillOperationContext,
+  id: string,
+) {
+  const meta = ctx.registry.get(id);
+  if (!meta) {
+    return { error: `技能 "${id}" 不存在` };
+  }
+
+  const content = await ctx.onSkillLoadContent(id);
+  if ('error' in content) {
+    return createInspectResult('skill', createManagedSkillDetail(meta, {
+      instructionsError: content.error,
+    }));
+  }
+
+  return createInspectResult('skill', createManagedSkillDetail(meta, {
+    instructions: content.instructions,
+  }));
+}
+
+export async function loadManagedSkillReference(
+  ctx: SkillOperationContext,
+  input: { id: string; referenceName: string },
+) {
+  return ctx.onSkillLoadReference(input.id, input.referenceName);
+}

package/src/skills/management/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Skill 管理层类型
+ *
+ * - 宿主回调：创建/更新/删除/启用、加载 SKILL.md 正文与参考文档
+ * - Admin / operations 上下文接口
+ */
+
+import type { SkillRegistry } from '../registry';
+
+/** 技能创建回调 */
+export type OnSkillCreate = (params: {
+  id: string;
+  name: string;
+  description: string;
+  instructions: string;
+  category: string;
+  tags: string[];
+  icon: string;
+}) => Promise<{ ok: boolean } | { error: string }>;
+
+/** 技能更新回调：宿主覆盖 SKILL.md 内容 */
+export type OnSkillUpdate = (params: {
+  id: string;
+  name: string;
+  description: string;
+  instructions: string;
+  category: string;
+  tags: string[];
+  icon: string;
+}) => Promise<{ ok: boolean } | { error: string }>;
+
+/** 技能删除回调 */
+export type OnSkillDelete = (id: string) => Promise<{ ok: boolean; error?: string }>;
+
+/** 技能启用状态变更回调（宿主持久化） */
+export type OnSkillSetEnabled = (id: string, enabled: boolean) => Promise<void>;
+
+/** 加载技能内容（SKILL.md body） */
+export type OnSkillLoadContent = (id: string) => Promise<{ name: string; instructions: string } | { error: string }>;
+
+/** 加载技能参考文档 */
+export type OnSkillLoadReference = (id: string, refName: string) => Promise<{ content: string } | { error: string }>;
+
+/** skillManagementPlugin 配置 */
+export interface SkillManagementOptions {
+  registry: SkillRegistry;
+  onSkillSetEnabled: OnSkillSetEnabled;
+  onSkillLoadContent: OnSkillLoadContent;
+  onSkillLoadReference: OnSkillLoadReference;
+  onSkillCreate?: OnSkillCreate;
+  onSkillUpdate?: OnSkillUpdate;
+  onSkillDelete?: OnSkillDelete;
+}
+
+export interface SkillOperationContext extends SkillManagementOptions {}
+
+export interface SkillAdminContext extends SkillOperationContext {}

package/src/skills/registry.ts

@@ -0,0 +1,120 @@
+/**
+ * Skill Registry - 技能注册表
+ *
+ * 纯内存索引，存储 SkillMeta。
+ * 与 ToolRegistry 不同：
+ *   - 没有 lazy loading（Skill 是文本，不需要实例化）
+ *   - 有 enabled 状态（决定是否注入 system prompt）
+ *   - 搜索支持 enabledOnly 过滤
+ */
+
+import type { SkillMeta, SkillSearchQuery } from './types';
+
+export interface SkillRegistry {
+  /** 注册 Skill（完整元数据） */
+  add(meta: SkillMeta): void;
+  /** 移除 Skill */
+  remove(id: string): void;
+  /** 搜索 Skill */
+  search(query?: SkillSearchQuery): SkillMeta[];
+  /** 按 ID 获取 */
+  get(id: string): SkillMeta | undefined;
+  /** 设置启用/禁用 */
+  setEnabled(id: string, enabled: boolean): void;
+  /** 获取所有已启用的 Skill */
+  listEnabled(): SkillMeta[];
+  /** 所有条目 */
+  entries(): SkillMeta[];
+  /** 是否已注册 */
+  has(id: string): boolean;
+  /** 条目总数 */
+  readonly size: number;
+  /** 所有分类 */
+  categories(): Array<{ category: string; count: number }>;
+}
+
+function matchesKeyword(meta: SkillMeta, keyword: string): boolean {
+  const lower = keyword.toLowerCase();
+  if (meta.id.toLowerCase().includes(lower)) return true;
+  if (meta.name.toLowerCase().includes(lower)) return true;
+  if (meta.description.toLowerCase().includes(lower)) return true;
+  if (meta.category.toLowerCase().includes(lower)) return true;
+  if (meta.tags.some(t => t.toLowerCase().includes(lower))) return true;
+  return false;
+}
+
+export function skillRegistry(): SkillRegistry {
+  const store = new Map<string, SkillMeta>();
+
+  return {
+    add(meta) {
+      store.set(meta.id, { ...meta });
+    },
+
+    remove(id) {
+      store.delete(id);
+    },
+
+    search(query) {
+      let results = Array.from(store.values());
+
+      if (query?.keyword) {
+        const kw = query.keyword;
+        results = results.filter(m => matchesKeyword(m, kw));
+      }
+      if (query?.category) {
+        const cat = query.category.toLowerCase();
+        results = results.filter(m => m.category.toLowerCase() === cat);
+      }
+      if (query?.tags?.length) {
+        const required = query.tags.map(t => t.toLowerCase());
+        results = results.filter(m => {
+          const entryTags = m.tags.map(t => t.toLowerCase());
+          return required.every(rt => entryTags.includes(rt));
+        });
+      }
+      if (query?.source) {
+        results = results.filter(m => m.source === query.source);
+      }
+      if (query?.enabledOnly) {
+        results = results.filter(m => m.enabled);
+      }
+
+      return results;
+    },
+
+    get(id) {
+      const meta = store.get(id);
+      return meta ? { ...meta } : undefined;
+    },
+
+    setEnabled(id, enabled) {
+      const meta = store.get(id);
+      if (meta) meta.enabled = enabled;
+    },
+
+    listEnabled() {
+      return Array.from(store.values()).filter(m => m.enabled);
+    },
+
+    entries() {
+      return Array.from(store.values());
+    },
+
+    has(id) {
+      return store.has(id);
+    },
+
+    get size() {
+      return store.size;
+    },
+
+    categories() {
+      const counts = new Map<string, number>();
+      for (const meta of store.values()) {
+        counts.set(meta.category, (counts.get(meta.category) ?? 0) + 1);
+      }
+      return Array.from(counts.entries()).map(([category, count]) => ({ category, count }));
+    },
+  };
+}

package/src/skills/summaries.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill 管理摘要 / 详情构造
+ *
+ * - 从 SkillMeta 派生 ManagedSkillSummary / Detail，带统一治理字段
+ */
+
+import { createAssetSummaryBase, createSkillAssetGovernance } from '../governance';
+import type { ManagedSkillDetail, ManagedSkillSummary, SkillMeta } from './types';
+
+export function createManagedSkillSummary(
+  skill: SkillMeta,
+  extra: Partial<ManagedSkillSummary> = {},
+): ManagedSkillSummary {
+  return {
+    ...createAssetSummaryBase({
+      kind: 'skill',
+      scope: skill.source === 'system' || skill.source === 'bundled' ? 'core' : 'local',
+      runtime: 'prompt-injection',
+      governance: extra.governance ?? createSkillAssetGovernance(),
+    }),
+    ref: skill.id,
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    category: skill.category,
+    tags: skill.tags,
+    icon: skill.icon,
+    source: skill.source,
+    enabled: skill.enabled,
+    references: skill.references,
+    scripts: skill.scripts,
+    dirPath: skill.dirPath,
+    displayName: skill.displayName,
+    shortDescription: skill.shortDescription,
+    defaultPrompt: skill.defaultPrompt,
+    ...extra,
+  };
+}
+
+export function createManagedSkillDetail(
+  skill: SkillMeta,
+  extra: Partial<ManagedSkillDetail> = {},
+): ManagedSkillDetail {
+  return {
+    ...createManagedSkillSummary(skill),
+    ...extra,
+  };
+}

package/src/skills/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Skill 类型定义
+ *
+ * Skill = AI 指令集（Markdown 文件），启用后注入 system prompt。
+ * 与 Tool 的区别：Tool 是可执行代码，Skill 是文本指令。
+ */
+
+import type { AssetSource, ManagedAssetSummaryBase } from '../governance/types';
+
+/** Skill 元数据（注册表中存储的索引信息） */
+export interface SkillMeta {
+  /** 唯一 ID（文件夹名） */
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  tags: string[];
+  icon: string;
+  source: AssetSource;
+  enabled: boolean;
+  /** 可用的 references 文件列表 */
+  references: string[];
+  /** 可用的 scripts 文件列表 */
+  scripts: string[];
+  /** 技能所在目录的绝对路径（宿主提供，用于文件操作） */
+  dirPath?: string;
+  /** UI 展示名称（区别于 ID） */
+  displayName?: string;
+  /** 简短描述（用于列表展示） */
+  shortDescription?: string;
+  /** 推荐触发语 */
+  defaultPrompt?: string;
+}
+
+export interface ManagedSkillSummary extends ManagedAssetSummaryBase {
+  ref: string;
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  tags: string[];
+  icon: string;
+  source: AssetSource;
+  enabled: boolean;
+  references: string[];
+  scripts: string[];
+  dirPath?: string;
+  displayName?: string;
+  shortDescription?: string;
+  defaultPrompt?: string;
+}
+
+export interface ManagedSkillDetail extends ManagedSkillSummary {
+  instructions?: string;
+  instructionsError?: string;
+}
+
+/** Skill 搜索条件 */
+export interface SkillSearchQuery {
+  keyword?: string;
+  category?: string;
+  tags?: string[];
+  source?: AssetSource;
+  enabledOnly?: boolean;
+}

package/src/test-utils/mock-sse.ts

@@ -1,8 +1,9 @@
 /**
  * 测试用：根据 SSE 数据行创建 Response，用于 mock fetch
+ *
+ * Response.ok 由 status 自动决定（200-299 为 true），无需手动传入。
  */
-export function createSSEResponse(sseDataLines: string[], options?: { ok?: boolean; status?: number }): Response {
-  const ok = options?.ok ?? true
+export function createSSEResponse(sseDataLines: string[], options?: { status?: number }): Response {
   const status = options?.status ?? 200
   const body = new ReadableStream<Uint8Array>({
     start(controller) {
@@ -15,7 +16,6 @@ export function createSSEResponse(sseDataLines: string[], options?: { ok?: boole
   })
   return new Response(body, {
     status,
-    ok,
     headers: { 'Content-Type': 'text/event-stream' },
   })
 }