From 41c16461cfe9b5ff6ec6fc97c16f740cbebff6fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=83=A1=E6=9C=8B?= Date: Sat, 14 Mar 2026 14:36:36 +0900 Subject: [PATCH] docs(zh): add missing Chinese pages (getting-started, changelog, mcp-a2a) --- src/app/zh/changelog/page.mdx | 89 +++++++ src/app/zh/getting-started/page.mdx | 368 ++++++++++++++++++++++++++++ src/app/zh/mcp-a2a/page.mdx | 231 +++++++++++++++++ 3 files changed, 688 insertions(+) create mode 100644 src/app/zh/changelog/page.mdx create mode 100644 src/app/zh/getting-started/page.mdx create mode 100644 src/app/zh/mcp-a2a/page.mdx diff --git a/src/app/zh/changelog/page.mdx b/src/app/zh/changelog/page.mdx new file mode 100644 index 0000000..27e8b85 --- /dev/null +++ b/src/app/zh/changelog/page.mdx @@ -0,0 +1,89 @@ +# 更新日志 + +LibreFang 的所有重要变更记录在此。完整日志请参见 [CHANGELOG.md](https://github.com/librefang/librefang/blob/main/CHANGELOG.md) 和 [GitHub Releases](https://github.com/librefang/librefang/releases)。 + +--- + +## v0.4.1 (2026-03-14) + +### 新增 +- **模型目录同步**：`catalog_sync.rs` 模块，包含 `POST /api/catalog/sync` 和 `GET /api/catalog` 端点、仪表板同步卡片，以及三级模型加载（内置 → 目录 → 运行时）([#227](https://github.com/librefang/librefang/pull/227)) +- **频道 Sidecar 协议**：用于进程外频道适配器的外部 Sidecar 协议 ([#228](https://github.com/librefang/librefang/pull/228)) +- **Cargo Feature Flags**：42 个频道 feature flag，12 个默认频道，可选依赖实现精细构建 ([#223](https://github.com/librefang/librefang/pull/223)) +- **社区组织建设**：DevContainer 支持、good-first-issue 模板、PR 模板和版本同步脚本 ([#212](https://github.com/librefang/librefang/pull/212)) + +### 变更 +- **静态提供商注册表**：用声明式 `PROVIDER_REGISTRY` 数组和新的 `ApiFormat` 枚举替换 400 行的 provider match 代码块 ([#224](https://github.com/librefang/librefang/pull/224)) + +### 修复 +- 修复守护进程子进程未继承环境变量的问题 -- API 密钥（如 `MINIMAX_API_KEY`）现可正确传递 ([#210](https://github.com/librefang/librefang/pull/210)) +- 修复守护进程环境变量、MCP 探测和 SSE 解析问题 ([#211](https://github.com/librefang/librefang/pull/211)) + +### CI +- 升级 GitHub Actions 以兼容 Node.js 24 ([#229](https://github.com/librefang/librefang/pull/229)) + +--- + +## v0.4.0 (2026-03-14) + +### 新增 + +#### 认证与驱动 +- **ChatGPT Session Auth**：基于浏览器的 OAuth 流程，支持 ChatGPT Plus/Ultra 订阅用户，含 PKCE S256、自动模型发现、`librefang auth chatgpt` 子命令和 7 天会话缓存 ([#205](https://github.com/librefang/librefang/pull/205)) +- **MiniMax 双平台支持**：为中国区端点新增独立的 `minimax-cn` 提供商，使用 `MINIMAX_CN_API_KEY` +- **QQ Bot 适配器**：原生支持 QQ Bot 消息频道 ([#208](https://github.com/librefang/librefang/pull/208)) + +#### Web 仪表板与国际化 +- 完整国际化（i18n）支持，包含 `zh-CN` 语言和统一的 `t()` 翻译函数 +- 新侧边栏布局，带主题/语言切换器 +- 高质量内联 SVG 图标替换 emoji 图标 +- 改进 ClawHub 在小屏设备上的响应式表现 + +#### 核心平台 +- 所有 31 个内置 Agent 和子包的版本对齐 +- 增强配置热重载可靠性 + +#### CI/CD +- 优化 Docker 多架构构建，使用原生 ARM runner ([#203](https://github.com/librefang/librefang/pull/203)) + +#### CLI +- `librefang doctor` 现在可检查版本更新和网络连通性 ([#202](https://github.com/librefang/librefang/pull/202)) + +--- + +## v0.3.58 (2026-03-13) + +### 变更 +- 提取频道桥接重试辅助函数并改进错误匹配 ([#198](https://github.com/librefang/librefang/pull/198)) + +### 文档 +- 添加双许可证说明和组织成员政策 ([#197](https://github.com/librefang/librefang/pull/197)) +- 确立 LibreFang 自由身份和贡献者政策 ([#196](https://github.com/librefang/librefang/pull/196)) + +--- + +## v0.3.57 及更早版本 + +### 新增 +- 通用 `http_compat` MCP 传输层 ([#77](https://github.com/librefang/librefang/pull/77)) +- 扩展 CLI 命令覆盖范围和技能发布 ([#34](https://github.com/librefang/librefang/pull/34)) +- 原生内置路由器 ([#33](https://github.com/librefang/librefang/pull/33)) +- 默认守护进程后台启动/重启，支持 `--tail` 参数 ([#31](https://github.com/librefang/librefang/pull/31)) +- 从 OpenFang 移植 i18n 基础设施 ([#29](https://github.com/librefang/librefang/pull/29)) + +--- + +## v0.1.0 (2026-02-24) + +首次发布。完整 v0.1.0 功能列表请参见 [CHANGELOG.md](https://github.com/librefang/librefang/blob/main/CHANGELOG.md)，包括： +- 14 个 crate 的 Rust 工作空间 +- 27 个 LLM 提供商，130+ 个模型 +- 40 个频道适配器 +- 41 个内置工具 +- WASM 沙箱与双重计量 +- 可视化工作流构建器 +- 16 个安全系统 +- JavaScript 和 Python SDK +- Google A2A 协议支持 + +export const sections = []; diff --git a/src/app/zh/getting-started/page.mdx b/src/app/zh/getting-started/page.mdx new file mode 100644 index 0000000..d24f9c9 --- /dev/null +++ b/src/app/zh/getting-started/page.mdx @@ -0,0 +1,368 @@ +# 快速开始 + +本指南将引导你完成 LibreFang 的安装、配置 LLM 提供商、创建 Agent 并与之对话。 + +项目网站：[https://librefang.ai/](https://librefang.ai/) + +## 目录 + +- [安装](#安装) +- [配置](#配置) +- [创建你的第一个 Agent](#创建你的第一个-agent) +- [与 Agent 对话](#与-agent-对话) +- [启动守护进程](#启动守护进程) +- [使用 WebChat 界面](#使用-webchat-界面) +- [下一步](#下一步) + +--- + +## 安装 + +### 方式一：Cargo Install（任意平台） + +LibreFang 目前尚未发布 GitHub Releases，推荐通过以下方式安装： + +```bash +cargo install --git https://github.com/librefang/librefang librefang-cli +``` + +或从源码构建： + +```bash +git clone https://github.com/librefang/librefang.git +cd librefang +cargo install --path crates/librefang-cli +``` + +### 方式二：Shell 安装脚本（Linux / macOS，未来版本） + +```bash +curl -fsSL https://librefang.ai/install.sh | sh +``` + +待 LibreFang 发布 GitHub Releases 后可使用。脚本会将 CLI 二进制文件安装到 `~/.librefang/bin/`。 + +### 方式三：PowerShell 安装脚本（Windows，未来版本） + +```powershell +irm https://librefang.ai/install.ps1 | iex +``` + +待 LibreFang 发布 GitHub Releases 后可使用。脚本会验证 SHA256 校验和并将 CLI 添加到用户 PATH。 + +### 方式四：Docker + +```bash +docker pull ghcr.io/librefang/librefang:latest + +docker run -d \ + --name librefang \ + -p 4545:4545 \ + -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ + -v librefang-data:/data \ + ghcr.io/librefang/librefang:latest +``` + +或使用 Docker Compose： + +```bash +git clone https://github.com/librefang/librefang.git +cd librefang +# 在环境变量或 .env 文件中设置 API 密钥 +docker compose up -d +``` + +### 验证安装 + +```bash +librefang --version +``` + +--- + +## 配置 + +### 初始化 + +运行 init 命令创建 `~/.librefang/` 目录和默认配置文件： + +```bash +librefang init +``` + +这将创建以下结构： + +``` +~/.librefang/ + config.toml # 主配置文件 + data/ # 数据库和运行时数据 + agents/ # Agent 清单（可选） +``` + +### 设置 API 密钥 + +LibreFang 至少需要一个 LLM 提供商的 API 密钥。将其设置为环境变量： + +```bash +# Anthropic (Claude) +export ANTHROPIC_API_KEY=sk-ant-... + +# 或 OpenAI +export OPENAI_API_KEY=sk-... + +# 或 Groq（有免费额度） +export GROQ_API_KEY=gsk_... +``` + +将 export 语句添加到你的 shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）以持久化设置。 + +### 编辑配置 + +默认配置使用 Anthropic。要更改提供商，编辑 `~/.librefang/config.toml`： + +```toml +[default_model] +provider = "groq" # anthropic, openai, groq, ollama 等 +model = "llama-3.3-70b-versatile" # 提供商的模型标识符 +api_key_env = "GROQ_API_KEY" # 存放 API 密钥的环境变量 + +[memory] +decay_rate = 0.05 # 记忆置信度衰减率 + +[network] +listen_addr = "127.0.0.1:4545" # OFP 监听地址 +``` + +### 验证设置 + +```bash +librefang doctor +``` + +此命令检查配置文件是否存在、API 密钥是否已设置以及工具链是否可用。 + +--- + +## 创建你的第一个 Agent + +### 使用内置模板 + +LibreFang 内置 30 个 Agent 模板。创建 hello-world Agent： + +```bash +librefang agent spawn agents/hello-world/agent.toml +``` + +输出： + +``` +Agent spawned successfully! + ID: a1b2c3d4-e5f6-... + Name: hello-world +``` + +### 使用自定义清单 + +创建你自己的 `my-agent.toml`： + +```toml +name = "my-assistant" +version = "0.1.0" +description = "A helpful assistant" +author = "you" +module = "builtin:chat" + +[model] +provider = "groq" +model = "llama-3.3-70b-versatile" + +[capabilities] +tools = ["file_read", "file_list", "web_fetch"] +memory_read = ["*"] +memory_write = ["self.*"] +``` + +然后创建它： + +```bash +librefang agent spawn my-agent.toml +``` + +### 列出运行中的 Agent + +```bash +librefang agent list +``` + +输出： + +``` +ID NAME STATE PROVIDER MODEL +----------------------------------------------------------------------------------------------- +a1b2c3d4-e5f6-... hello-world Running groq llama-3.3-70b-versatile +``` + +--- + +## 与 Agent 对话 + +使用 Agent ID 启动交互式对话： + +```bash +librefang agent chat a1b2c3d4-e5f6-... +``` + +或使用快捷对话命令（自动选择第一个可用 Agent）： + +```bash +librefang chat +``` + +或通过名称指定 Agent： + +```bash +librefang chat hello-world +``` + +对话示例： + +``` +Chat session started (daemon mode). Type 'exit' or Ctrl+C to quit. + +you> Hello! What can you do? + +agent> I'm the hello-world agent running on LibreFang. I can: +- Read files from the filesystem +- List directory contents +- Fetch web pages + +Try asking me to read a file or look up something on the web! + + [tokens: 142 in / 87 out | iterations: 1] + +you> List the files in the current directory + +agent> Here are the files in the current directory: +- Cargo.toml +- Cargo.lock +- README.md +- agents/ +- crates/ +- docs/ +... + +you> exit +Chat session ended. +``` + +--- + +## 启动守护进程 + +如需持久化 Agent、多用户访问和 WebChat 界面，请启动守护进程： + +```bash +librefang start +``` + +输出： + +``` +Starting LibreFang daemon... +LibreFang daemon running on http://127.0.0.1:4545 +Press Ctrl+C to stop. +``` + +守护进程提供： +- **REST API**：`http://127.0.0.1:4545/api/` +- **WebSocket** 端点：`ws://127.0.0.1:4545/api/agents/{id}/ws` +- **WebChat 界面**：`http://127.0.0.1:4545/` +- **OFP 网络**：端口 4545 + +### 检查状态 + +```bash +librefang status +``` + +### 停止守护进程 + +在运行守护进程的终端按 `Ctrl+C`，或： + +```bash +curl -X POST http://127.0.0.1:4545/api/shutdown +``` + +--- + +## 使用 WebChat 界面 + +守护进程运行后，在浏览器中打开： + +``` +http://127.0.0.1:4545/ +``` + +内嵌的 WebChat 界面支持： +- 查看所有运行中的 Agent +- 通过 WebSocket 与任意 Agent 实时对话 +- 查看流式生成的响应 +- 查看每条消息的 token 使用量 + +--- + +## 下一步 + +LibreFang 已经运行起来了，你可以： + +- **探索 Agent 模板**：浏览 `agents/` 目录中的 30 个预置 Agent（编码、研究、写作、运维、分析、安全审计等）。 +- **创建自定义 Agent**：编写自己的 `agent.toml` 清单文件。 +- **设置频道**：连接 40 种消息平台（Telegram、Discord、Slack、WhatsApp、LINE、Mastodon 等）。 +- **使用内置技能**：60 个专业知识技能已预装（GitHub、Docker、Kubernetes、安全审计、提示工程等）。 +- **构建自定义技能**：使用 Python、WASM 或纯提示词扩展 Agent。 +- **使用 API**：76 个 REST/WS/SSE 端点，包含 OpenAI 兼容的 `/v1/chat/completions`。 +- **切换 LLM 提供商**：支持 20 个提供商（Anthropic、OpenAI、Gemini、Groq、DeepSeek、xAI、Ollama 等），支持按 Agent 覆盖模型。 +- **设置工作流**：将多个 Agent 串联。使用 `librefang workflow create` 配合 TOML 工作流定义。 +- **使用 MCP**：通过 Model Context Protocol 连接外部工具。在 `config.toml` 的 `[[mcp_servers]]` 中配置。 +- **从 OpenClaw 迁移**：运行 `librefang migrate --from openclaw`。 +- **桌面应用**：运行 `cargo tauri dev` 获得原生桌面体验。 +- **运行诊断**：`librefang doctor` 检查完整设置。 + +### 常用命令参考 + +```bash +librefang init # 初始化 ~/.librefang/ +librefang start # 启动守护进程 +librefang status # 检查守护进程状态 +librefang doctor # 运行诊断检查 + +librefang agent spawn # 创建 Agent +librefang agent list # 列出所有 Agent +librefang agent chat # 与 Agent 对话 +librefang agent kill # 终止 Agent + +librefang workflow list # 列出工作流 +librefang workflow create # 创建工作流 +librefang workflow run # 运行工作流 + +librefang trigger list # 列出事件触发器 +librefang trigger create # 创建触发器 +librefang trigger delete # 删除触发器 + +librefang skill install # 安装技能 +librefang skill list # 列出已安装技能 +librefang skill search # 搜索 FangHub +librefang skill create # 创建新技能脚手架 + +librefang channel list # 列出频道状态 +librefang channel setup # 交互式设置向导 + +librefang config show # 显示当前配置 +librefang config edit # 在编辑器中打开配置 + +librefang chat [agent] # 快捷对话（别名） +librefang migrate --from openclaw # 从 OpenClaw 迁移 +librefang mcp # 启动 MCP 服务器 (stdio) +``` + +export const sections = []; diff --git a/src/app/zh/mcp-a2a/page.mdx b/src/app/zh/mcp-a2a/page.mdx new file mode 100644 index 0000000..3ef0667 --- /dev/null +++ b/src/app/zh/mcp-a2a/page.mdx @@ -0,0 +1,231 @@ +# MCP 与 A2A 协议 + +LibreFang 支持 MCP (Model Context Protocol) 和 A2A (Agent to Agent) 协议。 + + +**协议对比**： +- **MCP**：用于 LLM 与外部工具/服务连接（1 对多） +- **A2A**：用于 Agent 之间通信（多对多） + + +--- + +## MCP (Model Context Protocol) + +MCP 是一个标准化协议，用于连接 LLM 与外部工具和服务。 + +### 概述 + +``` +┌─────────────┐ MCP ┌─────────────┐ +│ LibreFang │ ◄─────────────► │ MCP Server │ +│ (Client) │ JSON-RPC 2.0 │ (Server) │ +└─────────────┘ └─────────────┘ +``` + +### MCP 服务器配置 + +```toml +[[mcp_servers]] +name = "filesystem" +command = "npx" +args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + +[[mcp_servers]] +name = "github" +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] +env = { GITHUB_TOKEN = "your-token" } +``` + +### MCP 工具命名 + +MCP 工具命名格式： +``` +mcp_{server}_{tool} +``` + +例如： +- `mcp_filesystem_read_file` +- `mcp_github_create_issue` + +### 内置 MCP 服务器 + +LibreFang 包含以下内置 MCP 服务器： + +| 服务器 | 工具 | +|--------|------| +| filesystem | read_file, write_file, list_directory | +| github | create_issue, get_pr, search_repos | +| postgres | query, execute, list_tables | + +### MCP 客户端 + +作为 MCP 客户端连接到外部服务器： + +```toml +[[mcp_servers]] +name = "custom" +command = "python" +args = ["./mcp_server.py"] +``` + +### 开发 MCP 服务器 + +```python +from mcp.server import Server +from mcp.types import Tool, TextContent + +app = Server("my-server") + +@app.list_tools() +async def list_tools(): + return [ + Tool( + name="my_tool", + description="My custom tool", + inputSchema={"type": "object", "properties": {}} + ) + ] + +@app.call_tool() +async def call_tool(name: str, arguments: dict): + return [TextContent(type="text", text="result")] +``` + +--- + +## A2A (Agent to Agent) + +A2A 协议支持 LibreFang Agent 之间的通信。 + +### 概述 + +``` +┌─────────────┐ A2A ┌─────────────┐ +│ Agent A │ ◄─────────────► │ Agent B │ +└─────────────┘ JSON over └─────────────┘ + HTTP/WebSocket +``` + +### Agent Card + +每个 Agent 发布 Agent Card： + +```json +{ + "name": "researcher", + "description": "Deep research agent", + "url": "http://localhost:4545/a2a", + "version": "1.0.0", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { "id": "research", "name": "Research" } + ] +} +``` + +### A2A 端点 + +| 端点 | 方法 | 说明 | +|------|------|------| +| `/.well-known/agent.json` | GET | Agent Card | +| `/a2a/tasks` | POST | 创建任务 | +| `/a2a/tasks/{id}` | GET | 获取任务状态 | +| `/a2a/tasks/{id}/messages` | GET | 获取消息历史 | + +### 发送任务 + +```bash +curl -X POST http://localhost:4545/a2a/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "id": "task-123", + "message": { + "role": "user", + "parts": [{ "type": "text", "text": "Research AI trends" }] + } + }' +``` + +### 接收任务 + +```bash +# 轮询 +curl http://localhost:4545/a2a/tasks/task-123 + +# 或使用 SSE +curl -N http://localhost:4545/a2a/tasks/task-123/events +``` + +--- + +## 对比 + +| 特性 | MCP | A2A | +|------|-----|------| +| 用途 | LLM → 工具 | Agent ↔ Agent | +| 协议 | JSON-RPC 2.0 | HTTP/WebSocket | +| 方向 | 单向 | 双向 | +| 示例 | 文件系统、GitHub | Agent 协作 | + +--- + +## 使用场景 + +### MCP 场景 + +- 文件系统操作 +- 数据库查询 +- GitHub API 调用 +- 自定义工具集成 + +### A2A 场景 + +- 多 Agent 协作 +- 任务委派 +- 跨实例通信 + +--- + +## 配置示例 + +### 完整 MCP 配置 + +```toml +# MCP 服务器 +[[mcp_servers]] +name = "filesystem" +command = "npx" +args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] + +[[mcp_servers]] +name = "github" +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +# A2A 配置 +[a2a] +enabled = true +agent_card_path = "/a2a/agent.json" +``` + +--- + +## CLI 命令 + +```bash +# 列出 MCP 服务器 +librefang mcp list + +# 测试 MCP 服务器 +librefang mcp test filesystem + +# 启动 MCP 模式 +librefang mcp +``` + +export const sections = [];