@huyooo/ai-chat-core 0.2.44 → 0.3.2

package/src/runtime.ts

@@ -0,0 +1,167 @@
+/**
+ * 扩展运行时框架
+ *
+ * 仅包含扩展生命周期类型和 defineExtension 入口。
+ * 平台工具（路径、Safari 自动化）见 @huyooo/ai-chat-core/platform。
+ */
+import type { Tool } from './types'
+
+/* ------------------------------------------------------------------ */
+/*  扩展生命周期类型                                                    */
+/* ------------------------------------------------------------------ */
+
+/** SQLite 数据库迁移定义 */
+export interface Migration {
+  version: number
+  name: string
+  up: (db: import('better-sqlite3').Database) => void
+}
+
+/** 扩展声明一个数据库所需的全部信息 */
+export interface DatabaseDeclaration {
+  description: string
+  workspaceKey?: string | null
+  customScope?: Record<string, unknown> | null
+  queryHint: string
+  migrations: Migration[]
+}
+
+/**
+ * 宿主注入的环境路径
+ *
+ * 扩展自包含原则：
+ *   - extensionDir 是只读的，包含扩展自带的所有静态资源（代码、二进制、预置模型等）
+ *   - dataDir 是可写的，存放运行时产物（拷贝后的二进制、下载的模型、缓存等）
+ *
+ * 二进制约定：扩展打包 bin/ 在 extensionDir 内，运行时拷贝到 dataDir/bin/
+ */
+export interface ExtensionPaths {
+  /** 扩展安装目录（只读：含代码、bin/、models/ 等静态资源） */
+  extensionDir: string
+  /** 扩展数据目录（可写：运行时二进制、下载模型、缓存） */
+  dataDir: string
+  /** 用户下载目录 */
+  downloadsDir: string
+}
+
+/** 扩展 AI 输入附件 */
+export interface AiAttachment {
+  mimeType: string
+  /** 本地文件路径。由宿主决定是否以内联或文件上传方式发送，扩展不会接触 API key。 */
+  filePath?: string
+  /** 已由宿主或上游返回的文件 URI。仅支持对应协议显式处理的场景。 */
+  fileUri?: string
+}
+
+/** 扩展 AI 消息 */
+export interface AiMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+  attachments?: AiAttachment[]
+}
+
+/** 扩展 AI 输出片段 */
+export type AiOutputPart =
+  | { type: 'text'; text: string }
+  | { type: 'binary'; mimeType: string; data: string }
+
+/** 扩展 AI 调用结果 */
+export interface AiGenerateResult {
+  text: string
+  parts: AiOutputPart[]
+  finishReason?: 'stop' | 'tool_calls' | 'length' | 'error'
+  usage?: {
+    promptTokens?: number
+    completionTokens?: number
+    totalTokens?: number
+    reasoningTokens?: number
+    cachedTokens?: number
+  }
+}
+
+/** 扩展 AI 生成参数 */
+export interface AiGenerateInput {
+  model: string
+  messages: AiMessage[]
+  enableThinking?: boolean
+  signal?: AbortSignal
+}
+
+/** 单厂商 AI 入口 */
+export interface ExtensionAiProvider {
+  generate(input: AiGenerateInput): Promise<AiGenerateResult>
+}
+
+/** 扩展可用的宿主 AI 能力 */
+export interface ExtensionAi {
+  gemini: ExtensionAiProvider
+  doubao: ExtensionAiProvider
+  deepseek: ExtensionAiProvider
+  qwen: ExtensionAiProvider
+  glm: ExtensionAiProvider
+  moonshot: ExtensionAiProvider
+  minimax: ExtensionAiProvider
+  openai: ExtensionAiProvider
+  anthropic: ExtensionAiProvider
+  grok: ExtensionAiProvider
+}
+
+export type ExtensionRecoveryTargetKind = 'file' | 'directory' | 'resource'
+
+export interface ExtensionRecoveryTargetInput {
+  id?: string
+  kind: ExtensionRecoveryTargetKind
+  path: string
+  displayName: string
+  workspaceKey?: string | null
+  customScope?: Record<string, unknown> | null
+  tags?: Record<string, string>
+}
+
+export interface ExtensionRecoveryTarget {
+  id: string
+  kind: ExtensionRecoveryTargetKind
+  path: string
+  displayName: string
+  workspaceKey: string | null
+  customScope: Record<string, unknown> | null
+  tags: Record<string, string>
+}
+
+export interface ExtensionRecovery {
+  registerTarget(input: ExtensionRecoveryTargetInput): ExtensionRecoveryTarget
+  listTargets(): ExtensionRecoveryTarget[]
+}
+
+/** 宿主注入给扩展 activate 的上下文 */
+export interface ExtensionContext {
+  /** 获取已声明的数据库连接（已完成 WAL 配置 + migration） */
+  getDatabase(name: string): import('better-sqlite3').Database
+  /** 宿主提供的环境路径 */
+  paths: ExtensionPaths
+  /** 宿主提供的 AI 能力（按厂商分组，调用方式统一） */
+  ai: ExtensionAi
+  /** 宿主提供的恢复目标注册能力（支持时注入） */
+  recovery?: ExtensionRecovery
+}
+
+/** defineExtension 的输入定义 */
+export interface ExtensionDefinition {
+  /** 数据库声明（可选，无 DB 需求的扩展不填） */
+  databases?: Record<string, DatabaseDeclaration>
+  /** 激活：接收宿主注入的上下文，返回工具数组 */
+  activate(ctx: ExtensionContext): Tool[]
+}
+
+/** defineExtension 返回的带标记对象，宿主据此识别完整扩展 */
+export type ExtensionDefinitionMarked = ExtensionDefinition & { __isExtension: true }
+
+/**
+ * 定义一个完整扩展（数据库 + 生命周期 + 工具）。
+ *
+ * 宿主加载模块后检查 default export 是否携带 __isExtension 标记，
+ * 有则走 defineExtension 流程（注册 DB → 注入上下文 → activate 返回工具）。
+ */
+export function defineExtension(definition: ExtensionDefinition): ExtensionDefinitionMarked {
+  return { ...definition, __isExtension: true as const }
+}

package/src/skills/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Skills 子系统导出（barrel）
+ *
+ * - registry：内存索引与启用状态
+ * - management：skillManagementPlugin 与宿主回调
+ * - summaries：管理 API 用摘要构造
+ */
+
+export type {
+  SkillMeta,
+  SkillSearchQuery,
+  ManagedSkillSummary,
+  ManagedSkillDetail,
+} from './types';
+
+export { skillRegistry } from './registry';
+export type { SkillRegistry } from './registry';
+export { createManagedSkillSummary, createManagedSkillDetail } from './summaries';
+
+export { skillManagementPlugin } from './management';
+export type {
+  SkillManagementOptions,
+  OnSkillCreate,
+  OnSkillUpdate,
+  OnSkillDelete,
+  OnSkillSetEnabled,
+  OnSkillLoadContent,
+  OnSkillLoadReference,
+} from './management';

package/src/skills/management/admin.ts

@@ -0,0 +1,170 @@
+/**
+ * Skill 管理命令装配
+ *
+ * - 将解析后的输入与 operations 绑定为具体 Tool 定义列表
+ * - 供 skillManagementPlugin 注册到 Agent
+ */
+
+import type { Tool } from '../../types';
+import type { SkillAdminContext } from './types';
+import {
+  parseSkillCreateInput,
+  parseSkillEnableItems,
+  parseSkillIdInput,
+  parseSkillReferenceInput,
+  parseSkillSearchInput,
+  parseSkillUpdateInput,
+} from './inputs';
+import {
+  createManagedSkill,
+  deleteManagedSkill,
+  inspectManagedSkill,
+  listManagedSkills,
+  loadManagedSkillReference,
+  searchManagedSkills,
+  setManagedSkillsEnabled,
+  updateManagedSkill,
+} from './operations';
+
+export function createSkillAdminTools(ctx: SkillAdminContext): Tool[] {
+  return [
+    {
+      name: 'skill_search',
+      description:
+        '搜索可用技能。按关键词/分类/标签/来源查找，返回匹配技能的名称和描述。' +
+        '找到后用 skill_enable 启用，或用 skill_inspect 查看详情。',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '关键词（匹配名称、描述、标签）' },
+          category: { type: 'string', description: '按分类过滤' },
+          tags: { type: 'string', description: '按标签过滤（逗号分隔，AND 逻辑）' },
+          source: { type: 'string', description: '按来源过滤：system | bundled | market | user' },
+        },
+      },
+      execute: async args => searchManagedSkills(ctx, parseSkillSearchInput(args)),
+    },
+    {
+      name: 'skill_list',
+      description: '列出当前已启用的技能，这些技能的指令会被注入到系统提示中。',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => listManagedSkills(ctx),
+    },
+    {
+      name: 'skill_create',
+      description:
+        '创建一个新技能。传入结构化参数，系统自动完成持久化和注册。' +
+        '创建成功后默认启用。' +
+        '当需求只是沉淀策略、约束和知识，而不需要执行逻辑或渲染 UI 时，优先创建 skill。' +
+        (ctx.onSkillCreate ? '' : '（当前环境未配置技能持久化，此功能不可用）'),
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '技能 ID（kebab-case，全局唯一，如 "my-skill"）' },
+          name: { type: 'string', description: '技能名称' },
+          description: { type: 'string', description: '一句话描述' },
+          instructions: { type: 'string', description: '技能指令内容（Markdown 格式）' },
+          category: { type: 'string', description: '分类，默认 "通用"' },
+          tags: {
+            type: 'array',
+            description: '标签列表',
+            items: { type: 'string' },
+          },
+          icon: { type: 'string', description: 'Emoji 图标，默认 "✨"' },
+        },
+        required: ['id', 'name', 'description', 'instructions'],
+      },
+      execute: async args => createManagedSkill(ctx, parseSkillCreateInput(args)),
+    },
+    {
+      name: 'skill_update',
+      description:
+        '原地更新已存在的技能。覆盖指令内容和元数据，保留当前启用状态。' +
+        (ctx.onSkillUpdate ? '' : '（当前环境未配置技能持久化，此功能不可用）'),
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '要更新的技能 ID（必须已存在）' },
+          name: { type: 'string', description: '新的技能名称' },
+          description: { type: 'string', description: '新的一句话描述' },
+          instructions: { type: 'string', description: '新的技能指令内容（Markdown 格式）' },
+          category: { type: 'string', description: '新的分类' },
+          tags: {
+            type: 'array',
+            description: '新的标签列表',
+            items: { type: 'string' },
+          },
+          icon: { type: 'string', description: '新的 Emoji 图标' },
+        },
+        required: ['id', 'name', 'description', 'instructions'],
+      },
+      execute: async args => {
+        const id = parseSkillIdInput(args).id;
+        return updateManagedSkill(ctx, parseSkillUpdateInput(args, ctx.registry.get(id)));
+      },
+    },
+    {
+      name: 'skill_enable',
+      description:
+        '批量设置技能的启用/禁用状态。启用的技能会被注入系统提示。',
+      parameters: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            description: '每项包含 id 和 enabled',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', description: '技能 ID' },
+                enabled: { type: 'boolean', description: 'true 启用，false 禁用' },
+              },
+              required: ['id', 'enabled'],
+            },
+          },
+        },
+        required: ['items'],
+      },
+      execute: async args => setManagedSkillsEnabled(ctx, parseSkillEnableItems(args)),
+    },
+    {
+      name: 'skill_delete',
+      description:
+        '彻底删除技能（从注册表和持久化存储中移除）。仅可删除 user 来源的技能。' +
+        (ctx.onSkillDelete ? '' : '（当前环境未配置技能持久化，此功能不可用）'),
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '要删除的技能 ID' },
+        },
+        required: ['id'],
+      },
+      execute: async args => deleteManagedSkill(ctx, parseSkillIdInput(args).id),
+    },
+    {
+      name: 'skill_inspect',
+      description: '查看技能的完整指令内容和元数据。',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '技能 ID' },
+        },
+        required: ['id'],
+      },
+      execute: async args => inspectManagedSkill(ctx, parseSkillIdInput(args).id),
+    },
+    {
+      name: 'skill_load_reference',
+      description: '读取技能的某个参考文档内容。',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '技能 ID' },
+          referenceName: { type: 'string', description: '参考文档文件名（从 skill_inspect 返回的 references 列表中获取）' },
+        },
+        required: ['id', 'referenceName'],
+      },
+      execute: async args => loadManagedSkillReference(ctx, parseSkillReferenceInput(args)),
+    },
+  ];
+}

package/src/skills/management/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Skill 管理插件入口（skillManagementPlugin）
+ *
+ * - 分层：types（回调） / inputs（解析） / operations（业务） / admin（装配 Tool）
+ * - 宿主注入 registry 与持久化回调后即可挂载
+ */
+import type { ToolPlugin } from '../../types';
+import type { SkillManagementOptions } from './types';
+import { createSkillAdminTools } from './admin';
+
+export type {
+  SkillManagementOptions,
+  SkillAdminContext,
+  SkillOperationContext,
+  OnSkillCreate,
+  OnSkillUpdate,
+  OnSkillDelete,
+  OnSkillSetEnabled,
+  OnSkillLoadContent,
+  OnSkillLoadReference,
+} from './types';
+
+export function skillManagementPlugin(options: SkillManagementOptions): ToolPlugin {
+  return {
+    tools: createSkillAdminTools(options),
+  };
+}

package/src/skills/management/inputs.ts

@@ -0,0 +1,79 @@
+/**
+ * Skill 管理插件 — 命令参数解析
+ *
+ * - 将未知 JSON args 转为强类型 Create/Update/Search 等结构
+ * - 校验 AssetSource、启用项等约束
+ */
+
+import {
+  getOptionalString,
+  getRequiredString,
+  getStringArray,
+} from '../../internal/management-args';
+import type { AssetSource } from '../../governance/types';
+import type { SkillMeta } from '../types';
+
+function isAssetSource(value: unknown): value is AssetSource {
+  return value === 'system' || value === 'bundled' || value === 'market' || value === 'user';
+}
+
+function isEnableItem(value: unknown): value is { id: string; enabled: boolean } {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const item = value as { id?: unknown; enabled?: unknown };
+  return typeof item.id === 'string' && typeof item.enabled === 'boolean';
+}
+
+export function parseSkillSearchInput(args: Record<string, unknown>) {
+  return {
+    keyword: getOptionalString(args.keyword),
+    category: getOptionalString(args.category),
+    tags: getOptionalString(args.tags),
+    source: isAssetSource(args.source) ? args.source : undefined,
+  };
+}
+
+export function parseSkillCreateInput(args: Record<string, unknown>) {
+  return {
+    id: getRequiredString(args.id),
+    name: getRequiredString(args.name),
+    description: getRequiredString(args.description),
+    instructions: getRequiredString(args.instructions),
+    category: getOptionalString(args.category) ?? '通用',
+    tags: getStringArray(args.tags) ?? [],
+    icon: getOptionalString(args.icon) ?? '✨',
+  };
+}
+
+export function parseSkillUpdateInput(
+  args: Record<string, unknown>,
+  existingMeta?: SkillMeta,
+) {
+  return {
+    id: getRequiredString(args.id),
+    name: getRequiredString(args.name),
+    description: getRequiredString(args.description),
+    instructions: getRequiredString(args.instructions),
+    category: getOptionalString(args.category) ?? existingMeta?.category ?? '通用',
+    tags: getStringArray(args.tags) ?? existingMeta?.tags ?? [],
+    icon: getOptionalString(args.icon) ?? existingMeta?.icon ?? '✨',
+  };
+}
+
+export function parseSkillEnableItems(args: Record<string, unknown>) {
+  return Array.isArray(args.items)
+    ? args.items.filter(isEnableItem)
+    : [];
+}
+
+export function parseSkillReferenceInput(args: Record<string, unknown>) {
+  return {
+    id: getRequiredString(args.id),
+    referenceName: getRequiredString(args.referenceName),
+  };
+}
+
+export function parseSkillIdInput(args: Record<string, unknown>) {
+  return {
+    id: getRequiredString(args.id),
+  };
+}