foliko 1.0.0

package/docs/quick-reference.md

@@ -0,0 +1,131 @@
+# VB-Agent 快速参考
+
+## 启动框架
+```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` | 主动思考 |
+
+## 插件位置
+
+- 内置插件：`plugins/`
+- 用户插件：`.agent/plugins/`
+
+## 重启插件
+
+```javascript
+// 调用工具
+await framework.executeTool('reload_plugins', {})
+// 或
+await framework.reloadAllPlugins()
+```
+
+## 事件监听
+
+```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() // 清空历史
+```