@zhin.js/agent 0.0.15 → 0.0.17

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zhin.js/agent
 
+## 0.0.17
+
+### Patch Changes
+
+- 16c8f92: fix: 统一发一次版
+- Updated dependencies [16c8f92]
+  - @zhin.js/ai@1.0.15
+  - @zhin.js/core@1.0.54
+
+## 0.0.16
+
+### Patch Changes
+
+- @zhin.js/core@1.0.53
+- @zhin.js/ai@1.0.14
+
 ## 0.0.15
 
 ### Patch Changes

package/lib/builtin-tools.d.ts

@@ -31,6 +31,11 @@ export interface BuiltinToolsOptions {
      * 返回额外技能根目录（每个根下为 `<skillName>/SKILL.md`），通常为已加载插件的 `.../skills`
      */
     pluginSkillRootsResolver?: () => string[];
+    /**
+     * 按名称查找 SkillFeature 中已注册技能的 filePath
+     * 返回 SKILL.md 的绝对路径，或 undefined 表示未找到
+     */
+    skillFileLookup?: (name: string) => string | undefined;
 }
 /**
  * 创建所有内置系统工具
@@ -71,4 +76,92 @@ export declare function loadAlwaysSkillsContent(skills: SkillMeta[]): Promise<st
  * 构建技能列表的 XML 摘要，供 model 区分可用/不可用及缺失依赖
  */
 export declare function buildSkillsSummaryXML(skills: SkillMeta[]): string;
+/**
+ * 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 declare function discoverWorkspaceAgents(root?: Plugin | null): Promise<AgentMeta[]>;
+/**
+ * 简写参数定义（*.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 declare function collectPluginToolSearchRoots(root: Plugin | null | undefined): string[];
+/**
+ * 获取所有 tool 搜索目录（标准目录 + 插件包 tools/）
+ */
+export declare function getToolSearchDirectories(root?: Plugin | null): string[];
+/**
+ * 扫描 tools/ 目录，发现 *.tool.md 文件
+ * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
+ * 同名先发现者优先
+ */
+export declare function discoverWorkspaceTools(root?: Plugin | null): Promise<ToolMeta[]>;
+/**
+ * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
+ */
+export declare function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null>;
 //# sourceMappingURL=builtin-tools.d.ts.map

package/lib/builtin-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../src/builtin-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA2BnF;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAevF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAMxE;AAiCD,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;OAEG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;CAC3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,QAAQ,EAAE,CA0d5E;AAmHD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA+GxF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAEjE;AAaD;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAclF;AAOD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAgBjE"}
+{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../src/builtin-tools.ts"],"names":[],"mappings":"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"}

package/lib/builtin-tools.js

@@ -58,7 +58,13 @@ export function collectPluginSkillSearchRoots(root) {
     const fromPlugin = (p) => {
         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 || []) {
@@ -113,6 +119,7 @@ export function createBuiltinTools(options) {
     const DATA_DIR = getDataDir();
     const skillMaxChars = options?.skillInstructionMaxChars ?? 4000;
     const skillDirList = () => mergeSkillDirsWithResolver(options?.pluginSkillRootsResolver);
+    const skillFileLookup = options?.skillFileLookup;
     const tools = [];
     // ── read_file（清晰描述 + 强关键词） ──
     tools.push(new ZhinTool('read_file')
@@ -487,12 +494,19 @@ export function createBuiltinTools(options) {
         .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;
@@ -835,4 +849,345 @@ export function buildSkillsSummaryXML(skills) {
     lines.push('</skills>');
     return lines.join('\n');
 }
+/**
+ * 扫描 agents/ 目录，发现 *.agent.md 文件
+ * 加载顺序与 skills 一致：Workspace > ~/.zhin > data > 插件包
+ * 同名先发现者优先
+ */
+export async function discoverWorkspaceAgents(root) {
+    const agents = [];
+    const seenNames = new Set();
+    // 构建扫描目录：标准目录的 agents/ + 插件包的 agents/
+    const agentDirs = [
+        path.join(process.cwd(), 'agents'),
+        path.join(os.homedir(), '.zhin', 'agents'),
+        path.join(getDataDir(), 'agents'),
+    ];
+    if (root) {
+        const addPluginDir = (p) => {
+            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;
+        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;
+            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;
+                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;
+}
+/**
+ * 从根插件树收集：根插件与直接子插件包目录下的 `tools/`
+ */
+export function collectPluginToolSearchRoots(root) {
+    if (!root)
+        return [];
+    const dirs = [];
+    const push = (d) => {
+        if (d && !dirs.includes(d))
+            dirs.push(d);
+    };
+    const fromPlugin = (p) => {
+        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) {
+    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) {
+    const properties = {};
+    const required = [];
+    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, toolMdPath) {
+    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) {
+    return (args) => 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) {
+    const tools = [];
+    const seenNames = new Set();
+    const toolDirs = getToolSearchDirectories(root);
+    for (const toolsDir of toolDirs) {
+        if (!fs.existsSync(toolsDir))
+            continue;
+        let entries;
+        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;
+            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;
+                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) {
+    // 构建 execute 函数
+    let execute;
+    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', properties: {} };
+    return {
+        name: meta.name,
+        description: meta.description,
+        parameters,
+        execute,
+        tags: meta.tags,
+        keywords: meta.keywords,
+        platforms: meta.platforms,
+        scopes: meta.scopes,
+        permissionLevel: meta.permissionLevel,
+        hidden: meta.hidden,
+        kind: meta.kind,
+        command: meta.command ? {
+            pattern: meta.command.pattern,
+            alias: meta.command.alias,
+            examples: meta.command.examples,
+        } : undefined,
+    };
+}
 //# sourceMappingURL=builtin-tools.js.map