@zhin.js/agent 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/agent",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Zhin AI Agent — session, ZhinAgent, init; composes @zhin.js/core providers and tools",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,8 +14,8 @@
   },
   "dependencies": {
     "js-yaml": "^4.1.0",
-    "@zhin.js/ai": "1.0.13",
-    "@zhin.js/core": "1.0.52"
+    "@zhin.js/ai": "1.0.15",
+    "@zhin.js/core": "1.0.54"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/builtin-tools.ts

@@ -62,7 +62,13 @@ export function collectPluginSkillSearchRoots(root: Plugin | null | undefined):
   };
   const fromPlugin = (p: Plugin) => {
     if (!p?.filePath) return;
-    push(path.join(path.dirname(p.filePath), 'skills'));
+    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 || []) {
@@ -120,6 +126,11 @@ export interface BuiltinToolsOptions {
    * 返回额外技能根目录（每个根下为 `<skillName>/SKILL.md`），通常为已加载插件的 `.../skills`
    */
   pluginSkillRootsResolver?: () => string[];
+  /**
+   * 按名称查找 SkillFeature 中已注册技能的 filePath
+   * 返回 SKILL.md 的绝对路径，或 undefined 表示未找到
+   */
+  skillFileLookup?: (name: string) => string | undefined;
 }
 
 /**
@@ -129,6 +140,7 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
   const DATA_DIR = getDataDir();
   const skillMaxChars = options?.skillInstructionMaxChars ?? 4000;
   const skillDirList = () => mergeSkillDirsWithResolver(options?.pluginSkillRootsResolver);
+  const skillFileLookup = options?.skillFileLookup;
 
   const tools: ZhinTool[] = [];
 
@@ -535,12 +547,19 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       .param('name', { type: 'string', description: '技能名称' }, true)
       .execute(async (args) => {
         try {
-          // 与 discoverWorkspaceSkills / getSkillSearchDirectories 顺序一致
+          // 优先查找 SkillFeature 中已注册技能的 filePath
+          const registeredPath = skillFileLookup?.(args.name);
+          if (registeredPath && fs.existsSync(registeredPath)) {
+            const fullContent = await fs.promises.readFile(registeredPath, 'utf-8');
+            const depWarning = await checkSkillDeps(fullContent);
+            const instructions = extractSkillInstructions(args.name, fullContent, skillMaxChars);
+            return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
+          }
+          // 回退到目录扫描（与 discoverWorkspaceSkills 顺序一致）
           for (const dir of skillDirList()) {
             const skillPath = path.join(dir, args.name, 'SKILL.md');
             if (fs.existsSync(skillPath)) {
               const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
-              // 5.3 可执行环境检查：若 SKILL 声明了 deps，再次检查；缺失则在返回内容中提示
               const depWarning = await checkSkillDeps(fullContent);
               const instructions = extractSkillInstructions(args.name, fullContent, skillMaxChars);
               return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
@@ -912,3 +931,424 @@ export function buildSkillsSummaryXML(skills: SkillMeta[]): string {
   lines.push('</skills>');
   return lines.join('\n');
 }
+
+// ============================================================================
+// Agent 预设发现（*.agent.md 文件）
+// ============================================================================
+
+/**
+ * Agent 预设元数据（从 *.agent.md frontmatter 解析）
+ */
+export interface AgentMeta {
+  name: string;
+  description: string;
+  keywords?: string[];
+  tags?: string[];
+  /** frontmatter 中声明的工具名列表 */
+  toolNames?: string[];
+  /** *.agent.md 文件的绝对路径 */
+  filePath: string;
+  /** 首选模型名 */
+  model?: string;
+  /** 首选 Provider 名 */
+  provider?: string;
+  /** 最大工具调用迭代次数 */
+  maxIterations?: number;
+}
+
+/**
+ * 扫描 agents/ 目录，发现 *.agent.md 文件
+ * 加载顺序与 skills 一致：Workspace > ~/.zhin > data > 插件包
+ * 同名先发现者优先
+ */
+export async function discoverWorkspaceAgents(root?: Plugin | null): Promise<AgentMeta[]> {
+  const agents: AgentMeta[] = [];
+  const seenNames = new Set<string>();
+
+  // 构建扫描目录：标准目录的 agents/ + 插件包的 agents/
+  const agentDirs: string[] = [
+    path.join(process.cwd(), 'agents'),
+    path.join(os.homedir(), '.zhin', 'agents'),
+    path.join(getDataDir(), 'agents'),
+  ];
+  if (root) {
+    const addPluginDir = (p: Plugin) => {
+      if (!p?.filePath) return;
+      const dir = path.dirname(p.filePath);
+      const d = path.join(dir, 'agents');
+      if (!agentDirs.includes(d)) agentDirs.push(d);
+      // Also check package root when filePath is under src/ or lib/
+      const dirName = path.basename(dir);
+      if (dirName === 'src' || dirName === 'lib') {
+        const d2 = path.join(path.dirname(dir), 'agents');
+        if (!agentDirs.includes(d2)) agentDirs.push(d2);
+      }
+    };
+    addPluginDir(root);
+    for (const child of root.children || []) {
+      addPluginDir(child);
+    }
+  }
+
+  for (const agentsDir of agentDirs) {
+    if (!fs.existsSync(agentsDir)) continue;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(agentsDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      // 支持两种结构：
+      // 1. agents/<name>.agent.md（扁平文件）
+      // 2. agents/<name>/<name>.agent.md（目录结构）
+      let agentMdPath: string | undefined;
+      if (entry.isFile() && entry.name.endsWith('.agent.md')) {
+        agentMdPath = path.join(agentsDir, entry.name);
+      } else if (entry.isDirectory()) {
+        const nested = path.join(agentsDir, entry.name, `${entry.name}.agent.md`);
+        if (fs.existsSync(nested)) {
+          agentMdPath = nested;
+        }
+      }
+      if (!agentMdPath) continue;
+
+      try {
+        const content = await fs.promises.readFile(agentMdPath, 'utf-8');
+        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
+        if (!match) {
+          logger.debug(`Agent文件 ${agentMdPath} 没有有效的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(`Agent文件 ${agentMdPath} 缺少必需的 name/description 字段`);
+          continue;
+        }
+
+        if (seenNames.has(metadata.name)) {
+          logger.debug(`Agent '${metadata.name}' 已由先序目录加载，跳过: ${agentMdPath}`);
+          continue;
+        }
+        seenNames.add(metadata.name);
+
+        agents.push({
+          name: metadata.name,
+          description: metadata.description,
+          keywords: metadata.keywords || [],
+          tags: metadata.tags || [],
+          toolNames: Array.isArray(metadata.tools) ? metadata.tools : [],
+          filePath: agentMdPath,
+          model: metadata.model,
+          provider: metadata.provider,
+          maxIterations: typeof metadata.maxIterations === 'number' ? metadata.maxIterations : undefined,
+        });
+        logger.debug(`Agent发现成功: ${metadata.name}`);
+      } catch (e) {
+        logger.warn(`Failed to parse agent.md in ${agentMdPath}:`, e);
+      }
+    }
+  }
+
+  if (agents.length > 0) {
+    logger.info(`发现 ${agents.length} 个工作区 Agent 预设: ${agents.map(a => a.name).join(', ')}`);
+  }
+
+  return agents;
+}
+
+// ============================================================================
+// Tool 发现（*.tool.md 文件）
+// ============================================================================
+
+/**
+ * 简写参数定义（*.tool.md frontmatter 中使用）
+ */
+export interface ToolParamShorthand {
+  type: string;
+  description?: string;
+  required?: boolean;
+  enum?: string[];
+  default?: any;
+}
+
+/**
+ * Tool 元数据（从 *.tool.md frontmatter 解析）
+ */
+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'));
+    // 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), '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;
+}
+
+/**
+ * 将简写参数定义转换为 ToolParametersSchema
+ */
+function shorthandToSchema(params: Record<string, ToolParamShorthand>): import('@zhin.js/core').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 };
+}
+
+/**
+ * 加载 handler 文件（动态 import）
+ * @returns execute 函数, 或 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;
+  }
+  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}): ${errMsg(e)}`);
+    return undefined;
+  }
+}
+
+/**
+ * 从 body 构建 prompt 模板执行函数
+ */
+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) : '';
+  });
+}
+
+/**
+ * 扫描 tools/ 目录，发现 *.tool.md 文件
+ * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
+ * 同名先发现者优先
+ */
+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) {
+      // 支持两种结构：
+      // 1. tools/<name>.tool.md（扁平文件）
+      // 2. tools/<name>/<name>.tool.md（目录结构，允许放 handler.ts）
+      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);
+
+        // 提取 body（frontmatter 之后的内容）
+        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);
+      }
+    }
+  }
+
+  if (tools.length > 0) {
+    logger.info(`发现 ${tools.length} 个工作区 Tool: ${tools.map(t => t.name).join(', ')}`);
+  }
+
+  return tools;
+}
+
+/**
+ * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
+ */
+export async function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null> {
+  // 构建 execute 函数
+  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;
+  }
+
+  // 构建参数 schema
+  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/init/register-ai-trigger.ts

@@ -5,7 +5,7 @@ import './types.js';
 import { getPlugin, Message, shouldTriggerAI, inferSenderPermissions, parseRichMediaContent, mergeAITriggerConfig } from '@zhin.js/core';
 import type { Tool, ToolContext } from '@zhin.js/core';
 import type { ContentPart } from '@zhin.js/core';
-import type { OutputElement } from '../output.js';
+import type { OutputElement } from '@zhin.js/ai';
 import type { AIServiceRefs } from './shared-refs.js';
 
 /**