foliko 2.0.2 → 2.0.3

package/skills/plugins/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: plugin-dev
+description: JavaScript 插件开发指南。当用户说"创建插件"、"写插件"、"开发插件"时立即调用此 skill。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# JavaScript 插件开发
+
+## 概述
+
+Foliko 支持两种插件开发方式：
+
+| 类型 | 格式 | 存放位置 |
+|------|------|----------|
+| **function(foliko)** | `module.exports = function(foliko) {}` | `.foliko/plugins/*.js` |
+| **类式插件** | `class MyPlugin extends Plugin {}` | `.foliko/plugins/*/index.js` |
+
+推荐使用 **function(foliko)** 方式，更简洁直观。
+
+---
+
+## 快速开始
+
+创建 `.foliko/plugins/my-plugin.js`：
+
+```javascript
+/**
+ * 我的插件
+ */
+module.exports = function (foliko) {
+  console.log('[my-plugin] 加载中...');
+
+  // 注册工具
+  foliko.tools.tool({
+    name: 'hello',
+    description: '打招呼',
+    inputSchema: foliko.z.object({
+      name: foliko.z.string().describe('姓名')
+    }),
+    execute: (args) => ({ message: `Hello, ${args.name}!` })
+  });
+
+  console.log('[my-plugin] 加载完成');
+};
+```
+
+---
+
+## foliko API 速查
+
+### 工具注册
+
+```javascript
+// 注册普通工具（推荐）
+foliko.tools.tool({
+  name: 'my-tool',
+  description: '工具描述',
+  inputSchema: foliko.z.object({
+    arg1: foliko.z.string().describe('参数1'),
+    arg2: foliko.z.number().optional()
+  }),
+  execute: (args) => {
+    // 返回结果
+    return { success: true, result: '...' };
+  }
+});
+
+// 同上
+foliko.tools.register({ name: 'my-tool', ... });
+
+// 注册扩展工具（可被 LLM 通过 ext_call 调用）
+foliko.extension.tool('my-ext', {
+  greet: {
+    description: '打招呼',
+    inputSchema: foliko.z.object({
+      name: foliko.z.string()
+    }),
+    execute: (args) => ({ message: `Hi, ${args.name}!` })
+  }
+});
+```
+
+### 工具执行
+
+```javascript
+// 执行普通工具
+const result = await foliko.tools.execute('my-tool', { arg1: 'value' });
+
+// 执行扩展工具
+const result = await foliko.extension.execute('my-ext', 'greet', { name: 'Alice' });
+```
+
+### 工具查询
+
+```javascript
+// 列出所有普通工具
+foliko.tools.list();
+
+// 检查工具是否存在
+foliko.tools.has('my-tool');
+
+// 获取工具定义
+foliko.tools.get('my-tool');
+```
+
+### 扩展工具查询
+
+```javascript
+// 列出所有扩展插件
+foliko.extension.list();
+
+// 列出扩展插件名称
+foliko.extension.listPlugins();
+
+// 列出指定插件的工具
+foliko.extension.listTools('my-ext');
+
+// 获取指定工具详情
+foliko.extension.getTool('my-ext', 'greet');
+```
+
+### 插件管理
+
+```javascript
+// 获取插件实例
+foliko.plugin('ai');
+foliko.plugins.get('skill-manager');
+
+// 列出所有插件名
+foliko.plugins.list();
+
+// 检查插件是否存在
+foliko.plugins.has('ai');
+```
+
+### 事件
+
+```javascript
+// 监听事件
+foliko.on('framework:ready', (data) => {
+  console.log('框架就绪');
+});
+
+// 发送事件
+foliko.emit('my-event', { data: 'value' });
+
+// 移除监听
+foliko.off('my-event', handler);
+```
+
+### 日志
+
+```javascript
+foliko.logger.info('信息日志');
+foliko.logger.warn('警告日志');
+foliko.logger.error('错误日志');
+foliko.logger.debug('调试日志');
+```
+
+---
+
+## 完整示例
+
+```javascript
+/**
+ * 我的插件 - 完整示例
+ */
+module.exports = function (foliko) {
+  console.log('[my-plugin] 加载中...');
+
+  // ========== 注册普通工具 ==========
+
+  foliko.tools.tool({
+    name: 'hello',
+    description: '打招呼',
+    inputSchema: foliko.z.object({
+      name: foliko.z.string().describe('姓名')
+    }),
+    execute: (args) => ({ message: `Hello, ${args.name}!` })
+  });
+
+  foliko.tools.register({
+    name: 'calc',
+    description: '计算器',
+    inputSchema: foliko.z.object({
+      a: foliko.z.number(),
+      b: foliko.z.number(),
+      op: foliko.z.enum(['add', 'sub', 'mul', 'div']).optional()
+    }),
+    execute: (args) => {
+      const { a, b, op = 'add' } = args;
+      let result;
+      switch (op) {
+        case 'add': result = a + b; break;
+        case 'sub': result = a - b; break;
+        case 'mul': result = a * b; break;
+        case 'div': result = b !== 0 ? a / b : null; break;
+      }
+      return { success: true, result };
+    }
+  });
+
+  // ========== 注册扩展工具 ==========
+
+  foliko.extension.tool('weather', {
+    get: {
+      description: '获取天气',
+      inputSchema: foliko.z.object({
+        city: foliko.z.string().describe('城市名')
+      }),
+      execute: (args) => ({
+        weather: '晴天',
+        city: args.city,
+        temp: 25
+      })
+    }
+  });
+
+  // ========== 监听事件 ==========
+
+  foliko.on('framework:ready', () => {
+    console.log('[my-plugin] 框架就绪');
+  });
+
+  // ========== 获取其他插件 ==========
+
+  const aiPlugin = foliko.plugin('ai');
+  if (aiPlugin) {
+    console.log('[my-plugin] AI 插件已加载');
+  }
+
+  console.log('[my-plugin] 加载完成');
+};
+```
+
+---
+
+## LLM 调用扩展工具
+
+扩展工具通过 `ext_call` 调用：
+
+```javascript
+// 调用扩展工具
+ext_call({
+  plugin: 'weather',     // 插件名
+  tool: 'get',          // 工具名
+  args: { city: '北京' }
+});
+```
+
+系统提示词中会自动显示：
+
+```markdown
+## 【Extensions】扩展插件
+
+**使用流程（必须按顺序执行）：**
+1. 调用 `ext_skill({ plugin: "<plugin_name>" })` 获取技能命令的详细参数
+2. 根据返回的参数定义，使用 `ext_call({ plugin: "<plugin_name>", tool: "<tool_name>", args: {...} })` 调用
+
+### weather
+**工具:** `get`
+```
+
+---
+
+## Zod Schema 用法
+
+```javascript
+// 基础类型
+foliko.z.string()
+foliko.z.number()
+foliko.z.boolean()
+foliko.z.array(foliko.z.string())
+
+// 可选
+foliko.z.string().optional()
+
+// 带默认值
+foliko.z.string().default('World')
+
+// 枚举
+foliko.z.enum(['add', 'sub', 'mul'])
+
+// 描述
+foliko.z.string().describe('参数描述')
+
+// 复杂对象
+foliko.z.object({
+  name: foliko.z.string(),
+  age: foliko.z.number().optional(),
+  tags: foliko.z.array(foliko.z.string()).optional(),
+  address: foliko.z.object({
+    city: foliko.z.string(),
+    zip: foliko.z.string()
+  }).optional()
+})
+```
+
+---
+
+## 注意事项
+
+1. **插件位置** - 放在 `.foliko/plugins/` 目录下
+2. **热重载** - 修改后运行 `foliko reload` 重载插件
+3. **工具名唯一** - 避免与现有工具名冲突
+4. **错误处理** - execute 函数应捕获错误并返回 `{ success: false, error: '...' }`
+5. **异步操作** - execute 支持 async/await
+
+---
+
+## 开发流程
+
+1. **创建插件文件** - `.foliko/plugins/my-plugin.js`
+2. **编写代码** - 使用 `function(foliko)` 方式
+3. **测试** - `foliko reload` 重载插件
+4. **调试** - 查看控制台日志输出

package/skills/skill-guide/SKILL.md

@@ -86,7 +86,7 @@ frontmatter 之后是技能的正文内容，支持 Markdown 格式，包含：
 3. 在正文中详细描述技能的功能和使用方法
 4. **如有命令**，在 SKILL.md 正文中添加 `## 命令` 章节，详细说明每个命令的用法
 5. 创建 `index.js` 文件导出命令（可选）
-6. 调用 `reloadSkills` 工具重载所有技能
+6. 调用 `skill_reload` 工具重载所有技能
 
 ### SKILL.md 命令章节示例
 
@@ -266,17 +266,17 @@ module.exports = [
 
 技能命令会在以下时机自动注册：
 - 框架启动时加载技能
-- 调用 `reloadSkills` 工具重载后
+- 调用 `skill_reload` 工具重载后
 
 注册后即可在所有渠道使用 `/技能名:命令名` 格式调用。
 
 ## 技能重载
 
-创建或修改技能后，需要调用 `reloadSkills` 工具重载：
+创建或修改技能后，需要调用 `skill_reload` 工具重载：
 
 ```json
 {
-  "tool": "reloadSkills",
+  "tool": "skill_reload",
   "args": {}
 }
 ```
@@ -452,6 +452,6 @@ module.exports = [
 
 技能命令会在以下时机自动注册：
 - 框架启动时加载技能
-- 调用 `reloadSkills` 工具重载后
+- 调用 `skill_reload` 工具重载后
 
 注册后即可在所有渠道使用 `/技能名:命令名` 格式调用。

package/skills/{subagent-guide → subagents}/SKILL.md

@@ -176,7 +176,7 @@ You are an expert at finding and fixing bugs through systematic investigation.
 |------|-------|----------|
 | 系统提示词 | 指令和最佳实践 | 完整角色定义 |
 | 工具 | 继承父代理工具 | 可自定义工具集 |
-| 调用方式 | `loadSkill` 工具 | `subagent_call` 工具 |
+| 调用方式 | `skill_load` 工具 | `subagent_call` 工具 |
 | 适用场景 | 专业领域指导 | 独立处理复杂任务 |
 | LLM | 共享父代理 | 可独立配置 |
 

package/skills/{workflow-guide → workflows}/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-guide
 description: 工作流与多步任务指南。当用户说"创建工作流"、"多步任务"、"自动化流程"时立即调用。
-allowed-tools: execute_workflow,reloadWorkflows
+allowed-tools: execute_workflow,workflow_reload
 ---
 
 # 工作流（Workflow）开发指南
@@ -31,11 +31,11 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 ## 重载工作流
 
-创建或修改工作流后，调用 `reloadWorkflows` 重载：
+创建或修改工作流后，调用 `workflow_reload` 重载：
 
 ```json
 {
-  "tool": "reloadWorkflows",
+  "tool": "workflow_reload",
   "args": {}
 }
 ```