@zhin.js/agent 0.1.0 → 0.1.2

package/src/discover-skills.ts

@@ -1,325 +0,0 @@
-/**
- * 技能发现（SKILL.md 文件扫描与加载）
- *
- * 加载顺序：Workspace（cwd/skills）> Local（~/.zhin/skills）> data/skills > 已加载插件包 skills/
- * 同名先发现者优先，支持平台/依赖兼容性过滤
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import { Logger, type Plugin } from '@zhin.js/core';
-import { getSkillSearchDirectories, getDataDir } from './discovery-utils.js';
-
-const execAsync = promisify(exec);
-const logger = new Logger(null, 'builtin-tools');
-
-// ============================================================================
-// 类型
-// ============================================================================
-
-export interface SkillMeta {
-  name: string;
-  description: string;
-  keywords?: string[];
-  tags?: string[];
-  /** SKILL.md frontmatter 中声明的关联工具名列表 */
-  toolNames?: string[];
-  filePath: string;
-  /** 是否常驻注入 system prompt（frontmatter always: true） */
-  always?: boolean;
-  /** 当前环境是否满足依赖（bins/env） */
-  available?: boolean;
-  /** 缺失的依赖描述（如 "CLI: ffmpeg", "ENV: API_KEY"） */
-  requiresMissing?: string[];
-}
-
-// ============================================================================
-// 发现
-// ============================================================================
-
-/**
- * 扫描技能目录，发现 SKILL.md 技能文件
- * @param root 根插件（可选）：用于追加插件包内 `skills/` 扫描，与 `activate_skill` 查找路径一致
- */
-export async function discoverWorkspaceSkills(root?: Plugin | null): Promise<SkillMeta[]> {
-  const skills: SkillMeta[] = [];
-  const seenNames = new Set<string>();
-  const dataDir = getDataDir();
-  const skillDirs = getSkillSearchDirectories(root ?? undefined);
-
-  // 确保 data/skills 目录存在
-  const defaultSkillDir = path.join(dataDir, 'skills');
-  if (!fs.existsSync(defaultSkillDir)) {
-    fs.mkdirSync(defaultSkillDir, { recursive: true });
-    logger.debug(`Created skill directory: ${defaultSkillDir}`);
-  }
-
-  for (const skillsDir of skillDirs) {
-    if (!fs.existsSync(skillsDir)) continue;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(skillsDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
-      if (!fs.existsSync(skillMdPath)) continue;
-
-      try {
-        const content = await fs.promises.readFile(skillMdPath, 'utf-8');
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-        if (!match) {
-          logger.debug(`Skill文件 ${skillMdPath} 没有有效的frontmatter格式`);
-          continue;
-        }
-
-        let jsYaml: any;
-        try {
-          jsYaml = await import('js-yaml');
-          if (jsYaml.default) jsYaml = jsYaml.default;
-        } catch (e) {
-          logger.warn(`Unable to import js-yaml module: ${e}`);
-          continue;
-        }
-
-        const metadata = jsYaml.load(match[1]);
-        if (!metadata || !metadata.name || !metadata.description) {
-          logger.debug(`Skill文件 ${skillMdPath} 缺少必需的 name/description 字段`);
-          continue;
-        }
-
-        // 平台兼容检查
-        const compat = metadata.compatibility || {};
-        if (compat.os && Array.isArray(compat.os)) {
-          const currentOs = process.platform === 'darwin' ? 'darwin' : process.platform === 'win32' ? 'windows' : 'linux';
-          if (!compat.os.includes(currentOs)) {
-            logger.debug(`Skipping skill '${metadata.name}' (unsupported OS)`);
-            continue;
-          }
-        }
-
-        // 依赖检查
-        const requiresBins: string[] = metadata.requires?.bins || compat.deps || metadata.deps || [];
-        const requiresEnv: string[] = metadata.requires?.env || [];
-        const binsToCheck = Array.isArray(requiresBins) ? requiresBins : [];
-        const envToCheck = Array.isArray(requiresEnv) ? requiresEnv : [];
-        const requiresMissing: string[] = [];
-        for (const bin of binsToCheck) {
-          try {
-            await execAsync(`which ${bin} 2>/dev/null`);
-          } catch {
-            requiresMissing.push(`CLI: ${bin}`);
-          }
-        }
-        for (const envKey of envToCheck) {
-          if (!process.env[envKey]) {
-            requiresMissing.push(`ENV: ${envKey}`);
-          }
-        }
-        const available = requiresMissing.length === 0;
-
-        if (seenNames.has(metadata.name)) {
-          logger.debug(`Skill '${metadata.name}' 已由先序目录加载，跳过: ${skillMdPath}`);
-          continue;
-        }
-        seenNames.add(metadata.name);
-
-        skills.push({
-          name: metadata.name,
-          description: metadata.description,
-          keywords: metadata.keywords || [],
-          tags: [...(metadata.tags || []), 'workspace-skill'],
-          toolNames: Array.isArray(metadata.tools) ? metadata.tools : [],
-          filePath: skillMdPath,
-          always: Boolean(metadata.always),
-          available,
-          requiresMissing: requiresMissing.length > 0 ? requiresMissing : undefined,
-        });
-        logger.debug(`Skill发现成功: ${metadata.name}, tools: ${JSON.stringify(metadata.tools || [])}`);
-      } catch (e) {
-        logger.warn(`Failed to parse SKILL.md in ${skillMdPath}:`, e);
-      }
-    }
-  }
-
-  return skills;
-}
-
-// ============================================================================
-// 辅助函数
-// ============================================================================
-
-/**
- * 获取 frontmatter 中 always: true 的技能名列表（用于常驻注入 system prompt）
- */
-export function getAlwaysSkillNames(skills: SkillMeta[]): string[] {
-  return skills.filter(s => s.always && s.available).map(s => s.name);
-}
-
-function stripFrontmatter(content: string): string {
-  const match = content.match(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/);
-  if (match) return content.slice(match[0].length).trim();
-  return content.trim();
-}
-
-/**
- * 加载 always 技能的正文内容并拼接为「Active Skills」段
- */
-export async function loadAlwaysSkillsContent(skills: SkillMeta[]): Promise<string> {
-  const always = skills.filter(s => s.always && s.available);
-  if (always.length === 0) return '';
-  const parts: string[] = [];
-  for (const s of always) {
-    try {
-      const content = await fs.promises.readFile(s.filePath, 'utf-8');
-      const body = stripFrontmatter(content);
-      parts.push(`### Skill: ${s.name}\n\n${body}`);
-    } catch (e) {
-      logger.warn(`Failed to load always skill ${s.name}: ${(e as Error).message}`);
-    }
-  }
-  return parts.join('\n\n---\n\n');
-}
-
-function escapeXml(s: string): string {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-/**
- * 构建技能列表的 XML 摘要，供 model 区分可用/不可用及缺失依赖
- */
-export function buildSkillsSummaryXML(skills: SkillMeta[]): string {
-  if (skills.length === 0) return '';
-  const lines = ['<skills>'];
-  for (const s of skills) {
-    const available = s.available !== false;
-    lines.push(`  <skill available="${available}">`);
-    lines.push(`    <name>${escapeXml(s.name)}</name>`);
-    lines.push(`    <description>${escapeXml(s.description)}</description>`);
-    lines.push(`    <location>${escapeXml(s.filePath)}</location>`);
-    if (!available && s.requiresMissing && s.requiresMissing.length > 0) {
-      lines.push(`    <requires>${escapeXml(s.requiresMissing.join(', '))}</requires>`);
-    }
-    lines.push('  </skill>');
-  }
-  lines.push('</skills>');
-  return lines.join('\n');
-}
-
-// ============================================================================
-// 技能内容解析（activate_skill 使用）
-// ============================================================================
-
-/**
- * 检查技能声明的依赖是否在环境中可用；若有缺失返回提示文案，否则返回空字符串
- */
-export async function checkSkillDeps(content: string): Promise<string> {
-  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!fmMatch) return '';
-  let jsYaml: any;
-  try {
-    jsYaml = await import('js-yaml');
-    if (jsYaml.default) jsYaml = jsYaml.default;
-  } catch {
-    return '';
-  }
-  const metadata = jsYaml.load(fmMatch[1]);
-  if (!metadata) return '';
-  const compat = metadata.compatibility || {};
-  const deps = compat.deps || metadata.deps;
-  if (!deps || !Array.isArray(deps)) return '';
-  const missing: string[] = [];
-  for (const dep of deps) {
-    try {
-      await execAsync(`which ${dep} 2>/dev/null`);
-    } catch {
-      missing.push(dep);
-    }
-  }
-  if (missing.length === 0) return '';
-  return `⚠️ 当前环境缺少以下依赖，请先安装后再使用本技能：${missing.join(', ')}`;
-}
-
-/**
- * 从 SKILL.md 全文中提取精简的执行指令
- * 只保留 frontmatter（工具列表）和执行规则，去掉示例、测试场景等冗余内容
- */
-export function extractSkillInstructions(name: string, content: string, maxBodyLen: number = 4000): string {
-  const lines: string[] = [];
-  lines.push(`Skill '${name}' activated. 请立即根据以下指导执行工具调用：`);
-  lines.push('');
-
-  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (fmMatch) {
-    const fmContent = fmMatch[1];
-    const toolsMatch = fmContent.match(/tools:\s*\n((?:\s+-\s+.+\n?)+)/);
-    if (toolsMatch) {
-      lines.push('## 可用工具');
-      lines.push(toolsMatch[0].trim());
-      lines.push('');
-    }
-  }
-
-  const bodyAfterFm = fmMatch && fmMatch.index !== undefined
-    ? content.slice(fmMatch.index + fmMatch[0].length).replace(/^\s+/, '')
-    : content;
-
-  // Priority: "## 快速操作" / "## Quick Actions" summary for small models
-  const quickActionsMatch = bodyAfterFm.match(/## (?:快速操作|Quick\s*Actions)[\s\S]*?(?=\n## [^\s]|$)/i);
-  if (quickActionsMatch && maxBodyLen <= 2000) {
-    lines.push(quickActionsMatch[0].trim());
-    lines.push('');
-    lines.push('## 立即行动');
-    lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
-    return lines.join('\n');
-  }
-
-  const rulesMatch = content.match(/## 执行规则[\s\S]*?(?=\n## [^\s]|$)/);
-  const workflowMatch = content.match(/## (?:Workflow|Instructions|使用说明)[\s\S]*?(?=\n## [^\s]|$)/);
-
-  if (rulesMatch) {
-    lines.push(rulesMatch[0].trim());
-    lines.push('');
-  } else if (workflowMatch) {
-    lines.push(workflowMatch[0].trim());
-    lines.push('');
-  } else if (bodyAfterFm.trim()) {
-    const firstH2 = bodyAfterFm.match(/\n## [^\s]/);
-    const intro = firstH2 ? bodyAfterFm.slice(0, firstH2.index).trim() : bodyAfterFm.trim();
-
-    const quickStartMatch = bodyAfterFm.match(/## (?:快速开始|Quick\s*Start|Getting\s*Started)[\s\S]*?(?=\n## [^\s]|$)/i);
-    const authMatch = bodyAfterFm.match(/## (?:认证|Authentication|Auth)[\s\S]*?(?=\n## [^\s]|$)/i);
-
-    if (quickStartMatch || (intro.length < 200 && bodyAfterFm.length > intro.length)) {
-      lines.push('## 指导');
-      lines.push(intro);
-      lines.push('');
-      const extra: string[] = [];
-      if (quickStartMatch) extra.push(quickStartMatch[0].trim());
-      if (authMatch) extra.push(authMatch[0].trim());
-      if (extra.length > 0) {
-        const joined = extra.join('\n\n');
-        lines.push(joined.length > maxBodyLen ? joined.slice(0, maxBodyLen) + '\n...(truncated)' : joined);
-      } else {
-        const rest = bodyAfterFm.slice(intro.length).trim();
-        lines.push(rest.length > maxBodyLen ? rest.slice(0, maxBodyLen) + '\n...(truncated)' : rest);
-      }
-      lines.push('');
-    } else if (intro) {
-      lines.push('## 指导');
-      lines.push(intro);
-      lines.push('');
-    }
-  }
-
-  lines.push('## 立即行动');
-  lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
-
-  return lines.join('\n');
-}

package/src/discover-tools.ts

@@ -1,302 +0,0 @@
-/**
- * 文件化 Tool 发现（*.tool.md 文件扫描与构建）
- *
- * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
- * 同名先发现者优先
- */
-
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { spawn } from 'child_process';
-import { Logger, type Plugin, type ToolParametersSchema } from '@zhin.js/core';
-import { getDataDir } from './discovery-utils.js';
-
-const logger = new Logger(null, 'builtin-tools');
-
-// ============================================================================
-// 类型
-// ============================================================================
-
-export interface ToolParamShorthand {
-  type: string;
-  description?: string;
-  required?: boolean;
-  enum?: string[];
-  default?: any;
-}
-
-export interface ToolMeta {
-  name: string;
-  description: string;
-  /** 简写参数定义（frontmatter 格式） */
-  parameters?: Record<string, ToolParamShorthand>;
-  /** 命令配置 */
-  command?: {
-    pattern?: string;
-    alias?: string[];
-    examples?: string[];
-  };
-  platforms?: string[];
-  scopes?: string[];
-  permissionLevel?: string;
-  tags?: string[];
-  keywords?: string[];
-  kind?: string;
-  hidden?: boolean;
-  /** handler 文件路径（相对于 .tool.md） */
-  handler?: string;
-  /** *.tool.md 文件的绝对路径 */
-  filePath: string;
-  /** body 内容（无 handler 时作为 prompt 模板） */
-  templateBody?: string;
-}
-
-// ============================================================================
-// 目录收集
-// ============================================================================
-
-/**
- * 从根插件树收集：根插件与直接子插件包目录下的 `tools/`
- */
-export function collectPluginToolSearchRoots(root: Plugin | null | undefined): string[] {
-  if (!root) return [];
-  const dirs: string[] = [];
-  const push = (d: string) => { if (d && !dirs.includes(d)) dirs.push(d); };
-  const fromPlugin = (p: Plugin) => {
-    if (!p?.filePath) return;
-    const dir = path.dirname(p.filePath);
-    push(path.join(dir, 'tools'));
-    const dirName = path.basename(dir);
-    if (dirName === 'src' || dirName === 'lib') {
-      push(path.join(path.dirname(dir), 'tools'));
-    }
-  };
-  fromPlugin(root);
-  for (const child of root.children || []) fromPlugin(child);
-  return dirs;
-}
-
-/**
- * 获取所有 tool 搜索目录（标准目录 + 插件包 tools/）
- */
-export function getToolSearchDirectories(root?: Plugin | null): string[] {
-  const list = [
-    path.join(process.cwd(), 'tools'),
-    path.join(os.homedir(), '.zhin', 'tools'),
-    path.join(getDataDir(), 'tools'),
-  ];
-  for (const d of collectPluginToolSearchRoots(root ?? undefined)) {
-    if (!list.includes(d)) list.push(d);
-  }
-  return list;
-}
-
-// ============================================================================
-// 发现
-// ============================================================================
-
-/**
- * 扫描 tools/ 目录，发现 *.tool.md 文件
- */
-export async function discoverWorkspaceTools(root?: Plugin | null): Promise<ToolMeta[]> {
-  const tools: ToolMeta[] = [];
-  const seenNames = new Set<string>();
-  const toolDirs = getToolSearchDirectories(root);
-
-  for (const toolsDir of toolDirs) {
-    if (!fs.existsSync(toolsDir)) continue;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(toolsDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      let toolMdPath: string | undefined;
-      if (entry.isFile() && entry.name.endsWith('.tool.md')) {
-        toolMdPath = path.join(toolsDir, entry.name);
-      } else if (entry.isDirectory()) {
-        const nested = path.join(toolsDir, entry.name, `${entry.name}.tool.md`);
-        if (fs.existsSync(nested)) toolMdPath = nested;
-      }
-      if (!toolMdPath) continue;
-
-      try {
-        const content = await fs.promises.readFile(toolMdPath, 'utf-8');
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-        if (!match) {
-          logger.debug(`Tool文件 ${toolMdPath} 没有有效的frontmatter格式`);
-          continue;
-        }
-
-        let jsYaml: any;
-        try {
-          jsYaml = await import('js-yaml');
-          if (jsYaml.default) jsYaml = jsYaml.default;
-        } catch (e) {
-          logger.warn(`Unable to import js-yaml module: ${e}`);
-          continue;
-        }
-
-        const metadata = jsYaml.load(match[1]);
-        if (!metadata || !metadata.name || !metadata.description) {
-          logger.debug(`Tool文件 ${toolMdPath} 缺少必需的 name/description 字段`);
-          continue;
-        }
-
-        if (seenNames.has(metadata.name)) {
-          logger.debug(`Tool '${metadata.name}' 已由先序目录加载，跳过: ${toolMdPath}`);
-          continue;
-        }
-        seenNames.add(metadata.name);
-
-        const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, '').trim();
-
-        tools.push({
-          name: metadata.name,
-          description: metadata.description,
-          parameters: metadata.parameters || undefined,
-          command: metadata.command || undefined,
-          platforms: metadata.platforms,
-          scopes: metadata.scopes,
-          permissionLevel: metadata.permissionLevel,
-          tags: metadata.tags || [],
-          keywords: metadata.keywords || [],
-          kind: metadata.kind,
-          hidden: metadata.hidden,
-          handler: metadata.handler,
-          filePath: toolMdPath,
-          templateBody: !metadata.handler && body ? body : undefined,
-        });
-        logger.debug(`Tool发现成功: ${metadata.name}`);
-      } catch (e) {
-        logger.warn(`Failed to parse tool.md in ${toolMdPath}:`, e);
-      }
-    }
-  }
-  return tools;
-}
-
-// ============================================================================
-// 构建
-// ============================================================================
-
-function shorthandToSchema(params: Record<string, ToolParamShorthand>): ToolParametersSchema {
-  const properties: Record<string, any> = {};
-  const required: string[] = [];
-  for (const [key, param] of Object.entries(params)) {
-    properties[key] = {
-      type: param.type || 'string',
-      description: param.description || key,
-    };
-    if (param.enum) properties[key].enum = param.enum;
-    if (param.default !== undefined) properties[key].default = param.default;
-    if (param.required) required.push(key);
-  }
-  return { type: 'object', properties, required: required.length > 0 ? required : undefined };
-}
-
-async function loadToolHandler(handlerPath: string, toolMdPath: string): Promise<((args: any, context?: any) => any) | undefined> {
-  const resolved = path.resolve(path.dirname(toolMdPath), handlerPath);
-  if (!fs.existsSync(resolved)) {
-    logger.warn(`Tool handler 文件不存在: ${resolved}`);
-    return undefined;
-  }
-  const ext = path.extname(resolved).toLowerCase();
-
-  // Python script handler: spawn subprocess, pass args via JSON stdin, return stdout
-  if (ext === '.py') {
-    return async (args: any) => {
-      const input = JSON.stringify(args);
-      const pythonBin = process.env.PYTHON_BIN || 'python3';
-      try {
-        const result = await new Promise<string>((resolve, reject) => {
-          const child = spawn(pythonBin, [resolved], {
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 30_000,
-          });
-          let stdout = '';
-          let stderr = '';
-          child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
-          child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
-          child.on('close', (code) => {
-            if (stderr) logger.debug(`[Python handler] ${resolved} stderr: ${stderr.trim()}`);
-            if (code !== 0) reject(new Error(`Python exited with code ${code}: ${stderr.trim()}`));
-            else resolve(stdout.trim());
-          });
-          child.on('error', reject);
-          child.stdin.write(input);
-          child.stdin.end();
-        });
-        return result;
-      } catch (e: any) {
-        return `Error running Python handler: ${e.message ?? String(e)}`;
-      }
-    };
-  }
-
-  // JS/TS handler: ESM import
-  try {
-    const fileUrl = `file://${resolved}?t=${Date.now()}`;
-    const mod = await import(fileUrl);
-    const fn = mod.default || mod;
-    if (typeof fn !== 'function') {
-      logger.warn(`Tool handler 未导出函数: ${resolved}`);
-      return undefined;
-    }
-    return fn;
-  } catch (e) {
-    logger.warn(`Tool handler 加载失败 (${resolved}): ${e instanceof Error ? e.message : String(e)}`);
-    return undefined;
-  }
-}
-
-function buildTemplateExecute(body: string): (args: Record<string, any>) => string {
-  return (args: Record<string, any>) => body.replace(/\{\{(\w+)\}\}/g, (_, k) => {
-    const val = args[k];
-    return val !== undefined && val !== null ? String(val) : '';
-  });
-}
-
-/**
- * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
- */
-export async function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null> {
-  let execute: ((args: any, context?: any) => any) | undefined;
-
-  if (meta.handler) {
-    execute = await loadToolHandler(meta.handler, meta.filePath);
-    if (!execute) return null;
-  } else if (meta.templateBody) {
-    execute = buildTemplateExecute(meta.templateBody);
-  } else {
-    logger.warn(`Tool '${meta.name}' 既没有 handler 也没有模板 body，跳过`);
-    return null;
-  }
-
-  const parameters = meta.parameters
-    ? shorthandToSchema(meta.parameters)
-    : { type: 'object' as const, properties: {} };
-
-  return {
-    name: meta.name,
-    description: meta.description,
-    parameters,
-    execute,
-    tags: meta.tags,
-    keywords: meta.keywords,
-    platforms: meta.platforms,
-    scopes: meta.scopes as any,
-    permissionLevel: meta.permissionLevel as any,
-    hidden: meta.hidden,
-    kind: meta.kind,
-    command: meta.command ? {
-      pattern: meta.command.pattern,
-      alias: meta.command.alias,
-      examples: meta.command.examples,
-    } : undefined,
-  };
-}