foliko 1.1.68 → 1.1.69

package/docs/quick-reference.md

@@ -1,160 +1,160 @@
-# Foliko 快速参考
-
-## 启动框架
-
-```javascript
-const framework = new Framework({ debug: false });
-await framework.bootstrap({
-  agentDir: './.agent',
-  aiConfig: { provider: 'deepseek', model: 'deepseek-chat', apiKey: '...' },
-});
-```
-
-## 创建 Agent
-
-```javascript
-const agent = framework.createAgent({
-  name: 'MyAgent',
-  systemPrompt: '你是一个有帮助的助手。',
-});
-```
-
-## 发送消息
-
-```javascript
-// 流式
-for await (const chunk of agent.chatStream('你好')) {
-  if (chunk.type === 'text') process.stdout.write(chunk.text);
-}
-
-// 非流式
-const result = await agent.chat('你好');
-```
-
-## 常用工具
-
-| 工具                   | 用途         |
-| ---------------------- | ------------ |
-| `list_tools`           | 列出所有工具 |
-| `loadSkill`            | 加载技能     |
-| `reload_plugins`       | 重载插件     |
-| `read_file`            | 读取文件     |
-| `write_file`           | 写入文件     |
-| `execute_command`      | 执行命令     |
-| `schedule_once`        | 定时任务     |
-| `think_now`            | 主动思考     |
-| `email_send`           | 发送邮件     |
-| `email_read`           | 读取邮件     |
-| `enable_plugin`        | 启用插件     |
-| `disable_plugin`       | 禁用插件     |
-| `update_plugin_config` | 更新插件配置 |
-
-## 插件位置
-
-- 内置插件：`plugins/`
-- 用户插件：`.agent/plugins/`
-
-## 插件管理
-
-```javascript
-// 重启插件
-await framework.executeTool('reload_plugins', {});
-await framework.executeTool('reload_plugins', { pluginName: 'telegram' });
-
-// 启用/禁用插件
-await framework.executeTool('enable_plugin', { name: 'telegram' });
-await framework.executeTool('disable_plugin', { name: 'telegram' });
-
-// 更新插件配置（持久化）
-await framework.executeTool('update_plugin_config', {
-  name: 'telegram',
-  config: { allowedChats: ['123'], groupMode: true },
-});
-await framework.executeTool('get_plugin_config', { name: 'telegram' });
-```
-
-## 事件监听
-
-```javascript
-// Framework 事件
-framework.on('framework:ready', (fw) => {});
-framework.on('plugin:loaded', (plugin) => {});
-framework.on('tool:registered', (tool) => {});
-
-// Agent 事件
-agent.on('status', ({ status }) => {}); // idle/busy/error
-agent.on('chunk', (chunk) => {}); // 流式输出
-agent.on('tool-call', ({ name, args }) => {});
-agent.on('tool-result', ({ name, result }) => {});
-
-// 子 Agent 事件
-agent.on('subagent:chat:start', (data) => {});
-agent.on('subagent:chat:end', (data) => {});
-agent.on('subagent:error', (data) => {});
-```
-
-## 子 Agent 注册
-
-```javascript
-const { tool } = require('ai')
-const { z } = require('zod')
-
-// 方式1：配置 agents 数组自动注册
-class MyPlugin extends Plugin {
-  agents = [
-    {
-      name: 'code-agent',
-      role: '代码专家',
-      tools: {
-        compile: tool({
-          description: '编译',
-          parameters: z.object({ language: z.string(), code: z.string() }),
-          execute: async (args) => ({ success: true })
-        })
-      },
-      parentTools: ['read_file', 'write_file']
-    }
-  ]
-}
-
-// 方式2：手动调用
-this.registerSubAgent({ name: 'code-agent', role: '代码专家', tools: {...}, parentTools: [...] })
-```
-
-## 系统提示中的部分
-
-```
-【可用工具】
-- tool1: 描述
-- tool2: 描述
-
-【可用技能】
-- skill1: 描述
-- skill2: 描述
-
-【子 Agent 分配规则】
-- code-agent: 代码专家
-
-【系统能力】
-- ai: AI 对话能力
-- storage: 存储
-```
-
-## 状态管理
-
-```javascript
-agent.getStatus(); // 'idle' | 'busy' | 'error'
-agent.resetStatus(); // 重置状态
-agent.clearHistory(); // 清空历史
-```
-
-## 配置持久化
-
-插件配置自动保存到 `.agent/data/plugins-state.json`
-
-| 文件                              | 用途                |
-| --------------------------------- | ------------------- |
-| `.agent/data/plugins-state.json`  | 插件启用状态和配置  |
-| `.agent/data/storage.json`        | 键值存储数据        |
-| `.agent/data/telegram_images/`    | Telegram 接收的图片 |
-| `.agent/data/telegram_documents/` | Telegram 接收的文档 |
+# Foliko 快速参考
+
+## 启动框架
+
+```javascript
+const framework = new Framework({ debug: false });
+await framework.bootstrap({
+  agentDir: './.foliko',
+  aiConfig: { provider: 'deepseek', model: 'deepseek-chat', apiKey: '...' },
+});
+```
+
+## 创建 Agent
+
+```javascript
+const agent = framework.createAgent({
+  name: 'MyAgent',
+  systemPrompt: '你是一个有帮助的助手。',
+});
+```
+
+## 发送消息
+
+```javascript
+// 流式
+for await (const chunk of agent.chatStream('你好')) {
+  if (chunk.type === 'text') process.stdout.write(chunk.text);
+}
+
+// 非流式
+const result = await agent.chat('你好');
+```
+
+## 常用工具
+
+| 工具                   | 用途         |
+| ---------------------- | ------------ |
+| `list_tools`           | 列出所有工具 |
+| `loadSkill`            | 加载技能     |
+| `reload_plugins`       | 重载插件     |
+| `read_file`            | 读取文件     |
+| `write_file`           | 写入文件     |
+| `execute_command`      | 执行命令     |
+| `schedule_once`        | 定时任务     |
+| `think_now`            | 主动思考     |
+| `email_send`           | 发送邮件     |
+| `email_read`           | 读取邮件     |
+| `enable_plugin`        | 启用插件     |
+| `disable_plugin`       | 禁用插件     |
+| `update_plugin_config` | 更新插件配置 |
+
+## 插件位置
+
+- 内置插件：`plugins/`
+- 用户插件：`.foliko/plugins/`
+
+## 插件管理
+
+```javascript
+// 重启插件
+await framework.executeTool('reload_plugins', {});
+await framework.executeTool('reload_plugins', { pluginName: 'telegram' });
+
+// 启用/禁用插件
+await framework.executeTool('enable_plugin', { name: 'telegram' });
+await framework.executeTool('disable_plugin', { name: 'telegram' });
+
+// 更新插件配置（持久化）
+await framework.executeTool('update_plugin_config', {
+  name: 'telegram',
+  config: { allowedChats: ['123'], groupMode: true },
+});
+await framework.executeTool('get_plugin_config', { name: 'telegram' });
+```
+
+## 事件监听
+
+```javascript
+// Framework 事件
+framework.on('framework:ready', (fw) => {});
+framework.on('plugin:loaded', (plugin) => {});
+framework.on('tool:registered', (tool) => {});
+
+// Agent 事件
+agent.on('status', ({ status }) => {}); // idle/busy/error
+agent.on('chunk', (chunk) => {}); // 流式输出
+agent.on('tool-call', ({ name, args }) => {});
+agent.on('tool-result', ({ name, result }) => {});
+
+// 子 Agent 事件
+agent.on('subagent:chat:start', (data) => {});
+agent.on('subagent:chat:end', (data) => {});
+agent.on('subagent:error', (data) => {});
+```
+
+## 子 Agent 注册
+
+```javascript
+const { tool } = require('ai')
+const { z } = require('zod')
+
+// 方式1：配置 agents 数组自动注册
+class MyPlugin extends Plugin {
+  agents = [
+    {
+      name: 'code-agent',
+      role: '代码专家',
+      tools: {
+        compile: tool({
+          description: '编译',
+          parameters: z.object({ language: z.string(), code: z.string() }),
+          execute: async (args) => ({ success: true })
+        })
+      },
+      parentTools: ['read_file', 'write_file']
+    }
+  ]
+}
+
+// 方式2：手动调用
+this.registerSubAgent({ name: 'code-agent', role: '代码专家', tools: {...}, parentTools: [...] })
+```
+
+## 系统提示中的部分
+
+```
+【可用工具】
+- tool1: 描述
+- tool2: 描述
+
+【可用技能】
+- skill1: 描述
+- skill2: 描述
+
+【子 Agent 分配规则】
+- code-agent: 代码专家
+
+【系统能力】
+- ai: AI 对话能力
+- storage: 存储
+```
+
+## 状态管理
+
+```javascript
+agent.getStatus(); // 'idle' | 'busy' | 'error'
+agent.resetStatus(); // 重置状态
+agent.clearHistory(); // 清空历史
+```
+
+## 配置持久化
+
+插件配置自动保存到 `.foliko/data/plugins-state.json`
+
+| 文件                              | 用途                |
+| --------------------------------- | ------------------- |
+| `.foliko/data/plugins-state.json`  | 插件启用状态和配置  |
+| `.foliko/data/storage.json`        | 键值存储数据        |
+| `.foliko/data/telegram_images/`    | Telegram 接收的图片 |
+| `.foliko/data/telegram_documents/` | Telegram 接收的文档 |