foliko 1.0.1 → 1.0.2

package/skills/python-plugin-dev/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: python-plugin-dev
+description: Python 插件开发指南。当用户说"创建 Python 插件"、"用 Python 写插件"时立即调用此 skill。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, python_plugin
+---
+
+# Python 插件开发
+
+## 概述
+
+Python 插件允许用 Python 语言开发工具，插件代码运行在 Python 环境中，可以调用所有 Python 库。
+
+## 插件存放位置
+
+`.agent/plugins/*.py`
+
+## 插件结构
+
+```python
+# .agent/plugins/my-plugin.py
+
+plugin_info = {
+    "name": "my-plugin",
+    "version": "1.0.0",
+    "description": "我的 Python 插件",
+    "tools": [
+        {
+            "name": "hello",
+            "description": "问候工具",
+            "params": {"name": "string"}
+        },
+        {
+            "name": "calc",
+            "description": "计算器工具",
+            "params": {"a": "number", "b": "number", "op": "string"}
+        }
+    ]
+}
+
+def execute_tool(tool_name, params):
+    """
+    执行工具 - 框架调用入口
+    tool_name: 工具名称
+    params: 参数字典
+    """
+    if tool_name == "hello":
+        return hello_tool(params)
+    elif tool_name == "calc":
+        return calc_tool(params)
+    else:
+        return {"success": False, "error": f"Unknown tool: {tool_name}"}
+
+# === 工具实现 ===
+
+def hello_tool(params):
+    """简单问候工具"""
+    name = params.get("name", "World")
+    return {
+        "success": True,
+        "result": f"Hello, {name}!"
+    }
+
+def calc_tool(params):
+    """计算器工具"""
+    a = params.get("a", 0)
+    b = params.get("b", 0)
+    op = params.get("op", "add")
+
+    if op == "add":
+        result = a + b
+    elif op == "sub":
+        result = a - b
+    elif op == "mul":
+        result = a * b
+    elif op == "div":
+        if b == 0:
+            return {"success": False, "error": "Division by zero"}
+        result = a / b
+    else:
+        return {"success": False, "error": f"Unknown operation: {op}"}
+
+    return {"success": True, "result": result}
+```
+
+**重要**：`tools` 字段定义了插件提供的所有工具。框架会自动：
+1. 将这些工具注册到系统中
+2. 附加到系统提示词，LLM 可以直接调用
+
+## 工具函数规范
+
+| 规范 | 说明 |
+|------|------|
+| 返回 dict | 必须是 Python 字典 |
+| success 字段 | `true` 或 `false` |
+| result 字段 | 成功时返回的结果 |
+| error 字段 | 失败时返回的错误信息 |
+
+## 返回值格式
+
+```python
+# 成功
+{"success": True, "result": "返回值"}
+
+# 失败
+{"success": False, "error": "错误信息"}
+
+# 返回复杂数据
+{"success": True, "result": {"key": "value", "list": [1, 2, 3]}}
+```
+
+## 使用方式
+
+创建插件后，使用 `python_plugin` 工具调用：
+
+```python
+python_plugin({
+  plugin: "my-plugin",      # 插件名称（不含 .py）
+  tool: "hello",            # 工具名称
+  params: { name: "Foliko" } # 工具参数
+})
+```
+
+## 示例：天气查询插件
+
+```python
+# .agent/plugins/weather.py
+
+plugin_info = {
+    "name": "weather",
+    "version": "1.0.0",
+    "description": "天气查询插件"
+}
+
+def execute_tool(tool_name, params):
+    if tool_name == "get_weather":
+        return get_weather(params)
+    else:
+        return {"success": False, "error": f"Unknown tool: {tool_name}"}
+
+def get_weather(params):
+    import requests
+
+    city = params.get("city", "北京")
+
+    try:
+        # 这里使用免费的天气 API
+        response = requests.get(
+            f"https://wttr.in/{city}?format=j1",
+            timeout=5
+        )
+        data = response.json()
+
+        return {
+            "success": True,
+            "result": {
+                "city": city,
+                "temperature": data["current_condition"][0]["temp_C"],
+                "weather": data["current_condition"][0]["weatherDesc"][0]["value"]
+            }
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+```
+
+## 示例：文件处理插件
+
+```python
+# .agent/plugins/file_processor.py
+
+plugin_info = {
+    "name": "file_processor",
+    "version": "1.0.0",
+    "description": "文件处理插件"
+}
+
+def execute_tool(tool_name, params):
+    if tool_name == "read_file":
+        return read_file_tool(params)
+    elif tool_name == "write_file":
+        return write_file_tool(params)
+    else:
+        return {"success": False, "error": f"Unknown tool: {tool_name}"}
+
+def read_file_tool(params):
+    import os
+
+    filepath = params.get("path")
+    if not filepath:
+        return {"success": False, "error": "path is required"}
+
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+        return {"success": True, "result": content}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+def write_file_tool(params):
+    filepath = params.get("path")
+    content = params.get("content", "")
+
+    if not filepath:
+        return {"success": False, "error": "path is required"}
+
+    try:
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+        return {"success": True, "result": f"Written to {filepath}"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+```
+
+## 依赖管理
+
+如果需要第三方库，可以在插件中用 `pip` 安装：
+
+```python
+def execute_tool(tool_name, params):
+    if tool_name == "install_package":
+        return install_package(params)
+    ...
+
+def install_package(params):
+    import subprocess
+    import sys
+
+    package = params.get("package")
+    if not package:
+        return {"success": False, "error": "package name is required"}
+
+    try:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", package])
+        return {"success": True, "result": f"Installed {package}"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+```
+
+## 注意事项
+
+1. **不要创建目录** - 必须是单个 `.py` 文件
+2. **必须定义 `execute_tool`** - 这是框架调用的入口
+3. **必须定义 `plugin_info`** - 插件元信息
+4. **异常处理** - 所有可能出错的地方都要 try-except
+5. **编码** - 文件使用 UTF-8 编码
+
+## 开发流程
+
+1. **编写插件代码** - 在 `.agent/plugins/` 下创建 `.py` 文件
+2. **调用工具** - 使用 `python_plugin` 工具执行
+3. **调试** - 查看返回的 `success` 和 `error` 信息
+
+## 常用 Python 库
+
+插件中可以使用的常用库：
+
+| 库 | 用途 | 导入方式 |
+|-----|------|---------|
+| requests | HTTP 请求 | `import requests` |
+| json | JSON 处理 | `import json` |
+| os | 系统操作 | `import os` |
+| pathlib | 路径处理 | `from pathlib import Path` |
+| datetime | 日期时间 | `from datetime import datetime` |
+| re | 正则表达式 | `import re` |
+| csv | CSV 处理 | `import csv` |

package/website/docs/api.html

@@ -0,0 +1,159 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API 参考 - Foliko</title>
+  <link rel="stylesheet" href="../styles.css">
+  <style>
+    .sidebar { position: fixed; left: 0; top: 60px; width: 250px; height: calc(100vh - 60px); background: var(--bg-card); border-right: 1px solid var(--border); padding: 2rem 1rem; overflow-y: auto; }
+    .sidebar ul { list-style: none; }
+    .sidebar li { margin-bottom: 0.5rem; }
+    .sidebar a { color: var(--text-secondary); text-decoration: none; display: block; padding: 0.5rem; border-radius: 4px; }
+    .sidebar a:hover, .sidebar a.active { background: rgba(99, 102, 241, 0.2); color: var(--primary); }
+    .main-content { margin-left: 250px; padding: 2rem; max-width: 900px; }
+    .main-content h1 { font-size: 2rem; margin-bottom: 1rem; }
+    .main-content h2 { font-size: 1.5rem; margin: 2rem 0 1rem; color: var(--secondary); }
+    .main-content p { margin-bottom: 1rem; color: var(--text-secondary); }
+    .main-content pre { background: var(--bg-card); padding: 1rem; border-radius: 8px; overflow-x: auto; margin-bottom: 1rem; }
+    .main-content code { font-family: 'Fira Code', monospace; background: var(--bg-dark); padding: 0.2rem 0.4rem; border-radius: 4px; }
+    .tool-card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 1.5rem; margin-bottom: 1rem; }
+    .tool-name { font-size: 1.2rem; color: var(--primary); font-weight: 600; }
+    .tool-desc { color: var(--text-secondary); margin: 0.5rem 0; }
+    .tool-params { font-size: 0.9rem; color: var(--text-secondary); }
+    @media (max-width: 768px) { .sidebar { display: none; } .main-content { margin-left: 0; } }
+  </style>
+</head>
+<body>
+  <header>
+    <nav>
+      <div class="logo">Foliko</div>
+      <ul class="nav-links">
+        <li><a href="../index.html">首页</a></li>
+        <li><a href="../index.html#features">特性</a></li>
+        <li><a href="../index.html#quickstart">快速开始</a></li>
+        <li><a href="../index.html#docs">文档</a></li>
+      </ul>
+    </nav>
+  </header>
+
+  <div class="sidebar">
+    <ul>
+      <li><a href="project-structure.html">项目结构</a></li>
+      <li><a href="configuration.html">配置指南</a></li>
+      <li><a href="plugin-development.html">插件开发</a></li>
+      <li><a href="skill-development.html">技能开发</a></li>
+      <li><a href="api.html" class="active">API 参考</a></li>
+    </ul>
+  </div>
+
+  <div class="main-content">
+    <h1>API 参考</h1>
+
+    <h2>内置工具</h2>
+
+    <div class="tool-card">
+      <div class="tool-name">install</div>
+      <div class="tool-desc">安装 npm 包到 .agent 目录</div>
+      <div class="tool-params">
+        <code>package</code>: string - 包名（如 zod 或 lodash@4.17.21）
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">loadSkill</div>
+      <div class="tool-desc">加载指定技能</div>
+      <div class="tool-params">
+        <code>skill</code>: string - 技能名称
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">shell_execute</div>
+      <div class="tool-desc">执行 Shell 命令</div>
+      <div class="tool-params">
+        <code>command</code>: string - 要执行的命令
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">python_execute</div>
+      <div class="tool-desc">执行 Python 代码</div>
+      <div class="tool-params">
+        <code>code</code>: string - Python 代码
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">mcp_execute</div>
+      <div class="tool-desc">执行 MCP 工具</div>
+      <div class="tool-params">
+        <code>server</code>: string - 服务器名称<br>
+        <code>tool</code>: string - 工具名称<br>
+        <code>arguments</code>: object - 工具参数
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">mcp_reload</div>
+      <div class="tool-desc">重载 MCP 服务器</div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">session_*</div>
+      <div class="tool-desc">会话管理相关工具</div>
+      <div class="tool-params">
+        session_create, session_list, session_load, session_delete 等
+      </div>
+    </div>
+
+    <div class="tool-card">
+      <div class="tool-name">audit_query</div>
+      <div class="tool-desc">查询审计日志</div>
+      <div class="tool-params">
+        <code>query</code>: string - 查询条件
+      </div>
+    </div>
+
+    <h2>占位符</h2>
+    <p>在 sharedPrompt 中使用：</p>
+    <pre><code>{{WORK_DIR}}   # 工作目录
+{{HOME_DIR}}  # 主目录
+{{HOST_NAME}} # 主机名
+{{PLATFORM}}  # 平台
+{{TIME}}      # 当前时间
+{{DATE}}      # 当前日期</code></pre>
+
+    <h2>框架 API</h2>
+    <pre><code>// 创建 Agent
+const agent = framework.createAgent({
+  name: 'MyAgent',
+  systemPrompt: '你是一个助手',
+  sharedPrompt: '工作目录: {{WORK_DIR}}',
+  metadata: {
+    key: 'value'
+  }
+})
+
+// 发送消息
+const response = await agent.chat('你好')
+
+// 流式发送
+for await (const chunk of agent.chatStream('你好')) {
+  console.log(chunk)
+}
+
+// 注册工具
+framework.registerTool({
+  name: 'my_tool',
+  description: '...',
+  inputSchema: z.object({...}),
+  execute: async (args) => {...}
+})
+
+// 重载插件
+await framework.reloadPlugin('plugin-name')
+await framework.reloadAllPlugins()</code></pre>
+  </div>
+</body>
+</html>

package/website/docs/configuration.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>配置指南 - Foliko</title>
+  <link rel="stylesheet" href="../styles.css">
+  <style>
+    .sidebar { position: fixed; left: 0; top: 60px; width: 250px; height: calc(100vh - 60px); background: var(--bg-card); border-right: 1px solid var(--border); padding: 2rem 1rem; overflow-y: auto; }
+    .sidebar ul { list-style: none; }
+    .sidebar li { margin-bottom: 0.5rem; }
+    .sidebar a { color: var(--text-secondary); text-decoration: none; display: block; padding: 0.5rem; border-radius: 4px; }
+    .sidebar a:hover, .sidebar a.active { background: rgba(99, 102, 241, 0.2); color: var(--primary); }
+    .main-content { margin-left: 250px; padding: 2rem; max-width: 900px; }
+    .main-content h1 { font-size: 2rem; margin-bottom: 1rem; }
+    .main-content h2 { font-size: 1.5rem; margin: 2rem 0 1rem; color: var(--secondary); }
+    .main-content p { margin-bottom: 1rem; color: var(--text-secondary); }
+    .main-content pre { background: var(--bg-card); padding: 1rem; border-radius: 8px; overflow-x: auto; margin-bottom: 1rem; }
+    .main-content code { font-family: 'Fira Code', monospace; background: var(--bg-dark); padding: 0.2rem 0.4rem; border-radius: 4px; }
+    table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; }
+    th, td { padding: 0.75rem; text-align: left; border: 1px solid var(--border); }
+    th { background: var(--bg-card); color: var(--secondary); }
+    @media (max-width: 768px) { .sidebar { display: none; } .main-content { margin-left: 0; } }
+  </style>
+</head>
+<body>
+  <header>
+    <nav>
+      <div class="logo">Foliko</div>
+      <ul class="nav-links">
+        <li><a href="../index.html">首页</a></li>
+        <li><a href="../index.html#features">特性</a></li>
+        <li><a href="../index.html#quickstart">快速开始</a></li>
+        <li><a href="../index.html#docs">文档</a></li>
+      </ul>
+    </nav>
+  </header>
+
+  <div class="sidebar">
+    <ul>
+      <li><a href="project-structure.html">项目结构</a></li>
+      <li><a href="configuration.html" class="active">配置指南</a></li>
+      <li><a href="plugin-development.html">插件开发</a></li>
+      <li><a href="skill-development.html">技能开发</a></li>
+      <li><a href="api.html">API 参考</a></li>
+    </ul>
+  </div>
+
+  <div class="main-content">
+    <h1>配置指南</h1>
+
+    <h2>目录结构</h2>
+    <p>在项目根目录创建 <code>.agent</code> 目录：</p>
+    <pre><code>项目目录/
+└── .agent/
+    ├── config              # 配置文件
+    ├── ai.json            # AI 配置
+    ├── mcp_config.json    # MCP 服务器配置
+    ├── plugins/           # 用户插件
+    ├── skills/            # 用户技能
+    └── data/             # 数据目录</code></pre>
+
+    <h2>config 文件</h2>
+    <p>简单的 key=value 格式配置：</p>
+    <pre><code>ai_key: your-api-key
+ai_model: MiniMax-M2.7
+ai_provider: minimax
+ai_base_url: https://api.minimaxi.com/v1</code></pre>
+
+    <h2>ai.json</h2>
+    <p>JSON 格式的 AI 配置：</p>
+    <pre><code>{
+  "provider": "minimax",
+  "model": "MiniMax-M2.7",
+  "apiKey": "your-api-key",
+  "baseURL": "https://api.minimaxi.com/v1"
+}</code></pre>
+
+    <h2>mcp_config.json</h2>
+    <p>MCP 服务器配置：</p>
+    <pre><code>{
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    }
+  }
+}</code></pre>
+
+    <h2>CLI 参数</h2>
+    <table>
+      <tr>
+        <th>参数</th>
+        <th>说明</th>
+      </tr>
+      <tr>
+        <td><code>--model</code></td>
+        <td>指定 AI 模型</td>
+      </tr>
+      <tr>
+        <td><code>--provider</code></td>
+        <td>指定 AI 提供商</td>
+      </tr>
+      <tr>
+        <td><code>--api-key</code></td>
+        <td>指定 API 密钥</td>
+      </tr>
+      <tr>
+        <td><code>--base-url</code></td>
+        <td>指定 API 地址</td>
+      </tr>
+    </table>
+  </div>
+</body>
+</html>