@zhin.js/agent 0.0.17 → 0.0.18

package/src/discover-tools.ts

@@ -0,0 +1,302 @@
+/**
+ * 文件化 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,
+  };
+}

package/src/discovery-utils.ts

@@ -0,0 +1,96 @@
+/**
+ * 发现模块共用的工具函数
+ *
+ * 被 builtin-tools / discover-skills / discover-agents / discover-tools 共同依赖，
+ * 独立出来以避免循环导入。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { Plugin } from '@zhin.js/core';
+
+/** 将 unknown 错误转为字符串 */
+export function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** 获取 data/ 目录路径，自动创建 */
+export function getDataDir(): string {
+  const dir = path.join(process.cwd(), 'data');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** 展开路径中的 ~ 为实际 home 目录 */
+export function expandHome(p: string): string {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/** Workspace / ~/.zhin / data 下 skills 根目录（与 activate_skill 扫描顺序一致的前缀） */
+export function buildStandardSkillDirs(): string[] {
+  return [
+    path.join(process.cwd(), 'skills'),
+    path.join(os.homedir(), '.zhin', 'skills'),
+    path.join(getDataDir(), 'skills'),
+  ];
+}
+
+/**
+ * 从根插件树收集：根插件与**直接子插件**包目录下的 `skills/`（其下为 `<name>/SKILL.md`）
+ */
+export function collectPluginSkillSearchRoots(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, 'skills'));
+    // Also check package root when filePath is under src/ or lib/
+    const dirName = path.basename(dir);
+    if (dirName === 'src' || dirName === 'lib') {
+      push(path.join(path.dirname(dir), 'skills'));
+    }
+  };
+  fromPlugin(root);
+  for (const child of root.children || []) {
+    fromPlugin(child);
+  }
+  return dirs;
+}
+
+/**
+ * 技能发现与 activate_skill 查找共用：标准目录 + 已加载插件包 skills/
+ */
+export function getSkillSearchDirectories(root?: Plugin | null): string[] {
+  const list = [...buildStandardSkillDirs()];
+  for (const d of collectPluginSkillSearchRoots(root ?? undefined)) {
+    if (!list.includes(d)) list.push(d);
+  }
+  return list;
+}
+
+export function mergeSkillDirsWithResolver(resolver?: () => string[]): string[] {
+  const list = [...buildStandardSkillDirs()];
+  for (const d of resolver?.() ?? []) {
+    if (d && !list.includes(d)) list.push(d);
+  }
+  return list;
+}
+
+/** 将 Node 文件错误转为 miniclawd 风格的结构化短句，便于模型区分并重试 */
+export function nodeErrToFileMessage(err: unknown, filePath: string, kind: 'read' | 'write' | 'edit' | 'list'): string {
+  const e = err as NodeJS.ErrnoException;
+  if (e?.code === 'ENOENT') {
+    if (kind === 'list') return `Error: Directory not found: ${filePath}`;
+    return `Error: File not found: ${filePath}`;
+  }
+  if (e?.code === 'EACCES') return `Error: Permission denied: ${filePath}`;
+  const action = kind === 'read' ? 'reading file' : kind === 'write' ? 'writing file' : kind === 'edit' ? 'editing file' : 'listing directory';
+  return `Error ${action}: ${e?.message ?? String(err)}`;
+}

package/src/init/create-zhin-agent.ts

@@ -5,7 +5,8 @@
 import * as path from 'path';
 import { getPlugin, Scheduler, getScheduler, setScheduler, type MessageType, type SendOptions } from '@zhin.js/core';
 import { ZhinAgent } from '../zhin-agent/index.js';
-import { collectPluginSkillSearchRoots, createBuiltinTools } from '../builtin-tools.js';
+import { createBuiltinTools } from '../builtin-tools.js';
+import { collectPluginSkillSearchRoots } from '../discovery-utils.js';
 import { resolveSkillInstructionMaxChars, DEFAULT_CONFIG } from '../zhin-agent/config.js';
 import { PersistentCronEngine, setCronManager } from '../cron-engine.js';
 import type { AIServiceRefs } from './shared-refs.js';

package/src/init/register-builtin-tools.ts

@@ -5,17 +5,12 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { getPlugin, type Tool, type SkillFeature, type AgentPreset } from '@zhin.js/core';
-import {
-  collectPluginSkillSearchRoots,
-  createBuiltinTools,
-  discoverWorkspaceSkills,
-  discoverWorkspaceAgents,
-  discoverWorkspaceTools,
-  buildToolFromMeta,
-  loadAlwaysSkillsContent,
-  buildSkillsSummaryXML,
-} from '../builtin-tools.js';
+import { getPlugin, type Tool, type SkillFeature, type AgentPresetFeature } from '@zhin.js/core';
+import { createBuiltinTools } from '../builtin-tools.js';
+import { collectPluginSkillSearchRoots } from '../discovery-utils.js';
+import { discoverWorkspaceSkills, loadAlwaysSkillsContent, buildSkillsSummaryXML } from '../discover-skills.js';
+import { discoverWorkspaceAgents } from '../discover-agents.js';
+import { discoverWorkspaceTools, buildToolFromMeta } from '../discover-tools.js';
 import { resolveSkillInstructionMaxChars, DEFAULT_CONFIG } from '../zhin-agent/config.js';
 import { loadBootstrapFiles, buildContextFiles, buildBootstrapContextSection } from '../bootstrap.js';
 import { triggerAIHook, createAIHookEvent } from '../hooks.js';
@@ -57,31 +52,39 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
       const existing = skillFeature.getByPlugin(root.name);
       for (const s of existing) skillFeature.remove(s);
       const skills = await discoverWorkspaceSkills(root);
-      if (skills.length === 0) return 0;
-      const allRegisteredTools = toolService.getAll();
-      const toolNameIndex = new Map<string, Tool>();
-      for (const t of allRegisteredTools) {
-        toolNameIndex.set(t.name, t);
-        const parts = t.name.split('_');
-        if (parts.length === 2) toolNameIndex.set(`${parts[1]}_${parts[0]}`, t);
-      }
-      for (const s of skills) {
-        const associatedTools: Tool[] = [];
-        const toolNames = s.toolNames || [];
-        for (const toolName of toolNames) {
-          let tool = toolService.get(toolName) || toolNameIndex.get(toolName);
-          if (tool) associatedTools.push(tool);
+      if (skills.length > 0) {
+        const allRegisteredTools = toolService.getAll();
+        const toolNameIndex = new Map<string, Tool>();
+        for (const t of allRegisteredTools) {
+          toolNameIndex.set(t.name, t);
+          const parts = t.name.split('_');
+          if (parts.length === 2) toolNameIndex.set(`${parts[1]}_${parts[0]}`, t);
         }
-        skillFeature.add({
-          name: s.name,
-          description: s.description,
-          tools: associatedTools,
-          keywords: s.keywords || [],
-          tags: s.tags || [],
-          pluginName: root.name,
-          filePath: s.filePath,
-          always: s.always,
-        }, root.name);
+        for (const s of skills) {
+          const associatedTools: Tool[] = [];
+          const toolNames = s.toolNames || [];
+          for (const toolName of toolNames) {
+            let tool = toolService.get(toolName) || toolNameIndex.get(toolName);
+            if (tool) associatedTools.push(tool);
+          }
+          skillFeature.add({
+            name: s.name,
+            description: s.description,
+            tools: associatedTools,
+            keywords: s.keywords || [],
+            tags: s.tags || [],
+            pluginName: root.name,
+            filePath: s.filePath,
+            always: s.always,
+          }, root.name);
+        }
+      }
+      // Inject always-on skills content + XML summary into agent
+      if (refs.zhinAgent) {
+        const alwaysContent = await loadAlwaysSkillsContent(skills);
+        const skillsXml = buildSkillsSummaryXML(skills);
+        refs.zhinAgent.setActiveSkillsContext(alwaysContent);
+        refs.zhinAgent.setSkillsSummaryXML(skillsXml);
       }
       return skills.length;
     }
@@ -116,15 +119,20 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
       return added;
     }
 
-    // 已发现的 Agent 预设（本地缓存，无需存储到 Plugin 树）
-    const discoveredAgents = new Map<string, AgentPreset>();
-
     /**
-     * Discover *.agent.md files and register agent presets.
+     * Discover *.agent.md files and register agent presets into AgentPresetFeature.
      */
     async function syncWorkspaceAgents(): Promise<number> {
+      const agentPresetFeature = root.inject?.('agentPreset') as AgentPresetFeature | undefined;
+      if (!agentPresetFeature) return 0;
+
+      // Remove previously discovered presets for this plugin
+      const existing = agentPresetFeature.getByPlugin(root.name);
+      for (const p of existing) agentPresetFeature.remove(p);
+
       const agentMetas = await discoverWorkspaceAgents(root);
       if (agentMetas.length === 0) return 0;
+
       const allRegisteredTools = toolService.getAll();
       const toolNameIndex = new Map<string, import('@zhin.js/core').Tool>();
       for (const t of allRegisteredTools) {
@@ -132,7 +140,7 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
       }
       let added = 0;
       for (const meta of agentMetas) {
-        if (discoveredAgents.has(meta.name)) continue;
+        if (agentPresetFeature.get(meta.name)) continue;
         const associatedTools: import('@zhin.js/core').Tool[] = [];
         for (const toolName of meta.toolNames || []) {
           const tool = toolService.get(toolName) || toolNameIndex.get(toolName);
@@ -145,7 +153,7 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
           const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, '').trim();
           if (body) systemPrompt = body;
         } catch { /* ignore */ }
-        discoveredAgents.set(meta.name, {
+        agentPresetFeature.add({
           name: meta.name,
           description: meta.description,
           keywords: meta.keywords,
@@ -156,7 +164,7 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
           provider: meta.provider,
           maxIterations: meta.maxIterations,
           filePath: meta.filePath,
-        });
+        }, root.name);
         added++;
       }
       return added;
@@ -224,19 +232,6 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
         logger.debug(`Bootstrap files not loaded: ${e.message}`);
       }
 
-      // Step 3: inject always-on skills content + XML summary
-      try {
-        const skillsForContext = await discoverWorkspaceSkills(root);
-        const alwaysContent = await loadAlwaysSkillsContent(skillsForContext);
-        const skillsXml = buildSkillsSummaryXML(skillsForContext);
-        if (refs.zhinAgent) {
-          refs.zhinAgent.setActiveSkillsContext(alwaysContent);
-          refs.zhinAgent.setSkillsSummaryXML(skillsXml);
-        }
-      } catch (e: unknown) {
-        logger.debug(`Skills context not set: ${e instanceof Error ? e.message : String(e)}`);
-      }
-
       // Trigger agent:bootstrap hook
       const skillFeature2 = root.inject('skill') as SkillFeature | undefined;
       await triggerAIHook(createAIHookEvent('agent', 'bootstrap', undefined, {
@@ -279,13 +274,6 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
           skillReloadDebounce = null;
           try {
             const count = await syncWorkspaceSkills();
-            const skillsForContext = await discoverWorkspaceSkills(root);
-            const alwaysContent = await loadAlwaysSkillsContent(skillsForContext);
-            const skillsXml = buildSkillsSummaryXML(skillsForContext);
-            if (refs.zhinAgent) {
-              refs.zhinAgent.setActiveSkillsContext(alwaysContent);
-              refs.zhinAgent.setSkillsSummaryXML(skillsXml);
-            }
             await triggerAIHook(createAIHookEvent('agent', 'skills-reloaded', undefined, { skillCount: count }));
             if (count >= 0) logger.info(`[技能热重载] 已更新，工作区技能: ${count}`);
           } catch (e: any) {