Skip to content

docs(zh): update Chinese channels and roadmap pages #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
houko merged 3 commits into from
Mar 14, 2026
Merged

docs(zh): update Chinese channels and roadmap pages #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db57b2c
docs(zh): add feature flag guide to channels page
Mar 14, 2026
49343cf
docs(zh): update roadmap with current status
Mar 14, 2026
accee4d
Merge branch 'main' into docs/zh-channels-roadmap-update
houko Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 112 additions & 0 deletions src/app/zh/channels/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,3 +200,115 @@ librefang channel disable telegram
2. **设置速率限制** - 防止滥用
3. **使用覆盖** - 为不同通道定制行为
4. **监控使用** - 定期检查通道统计

---

## 添加 Feature Flag

所有通道适配器都通过 Cargo feature flag 进行条件编译。默认构建包含 12 个常用通道，您可以按需启用其他通道以减小二进制体积。

### Feature Flag 层级

Feature flag 需要在三层 `Cargo.toml` 中逐级转发：

**1. `crates/librefang-channels/Cargo.toml`** — 定义 feature 并绑定可选依赖：

```toml
[features]
default = [
"channel-telegram",
"channel-discord",
"channel-slack",
# ... 共 12 个默认通道
]

all-channels = [
"channel-telegram",
"channel-discord",
# ... 全部 42 个通道
]

# 各通道的 feature 定义
channel-telegram = []
channel-email = ["dep:lettre", "dep:imap", "dep:native-tls", "dep:mailparse"]
channel-qq = ["dep:rustls"]
channel-wecom = ["dep:roxmltree", "dep:aes", "dep:cbc"]
```

**2. `crates/librefang-api/Cargo.toml`** — 转发到 channels crate：

```toml
[features]
channel-telegram = ["librefang-channels/channel-telegram"]
channel-qq = ["librefang-channels/channel-qq"]
all-channels = ["librefang-channels/all-channels"]
```

**3. `crates/librefang-cli/Cargo.toml`** — 转发到 api crate：

```toml
[features]
all-channels = ["librefang-api/all-channels"]
```

### 可选依赖绑定

部分通道需要额外依赖，通过 `dep:` 语法绑定到 feature flag：

| 通道 | 可选依赖 | 用途 |
|------|---------|------|
| Email | `lettre`, `imap`, `native-tls`, `mailparse` | IMAP/SMTP 邮件收发 |
| QQ | `rustls` | TLS 加密连接 |
| WeCom (企业微信) | `roxmltree`, `aes`, `cbc` | XML 解析与消息加解密 |

在源代码中使用 `#[cfg(feature = "channel-xxx")]` 条件编译：

```rust
#[cfg(feature = "channel-telegram")]
pub mod telegram;

#[cfg(feature = "channel-qq")]
pub mod qq;
```

### 构建选项

```bash
# 默认构建（12 个通道）
cargo build --workspace

# 启用全部通道
cargo build --workspace --features all-channels

# 仅启用特定通道
cargo build --workspace --no-default-features --features channel-telegram,channel-slack

# 最小构建（无通道适配器）
cargo build --workspace --no-default-features
```

---

## 贡献新 Channel Adapter

添加新通道适配器的完整步骤：

1. **创建适配器模块** — 在 `crates/librefang-channels/src/` 下新建 `myplatform.rs`，实现 `ChannelAdapter` trait（包含 `name()`、`channel_type()`、`start()`、`send()`、`stop()` 方法）

2. **添加 Feature Flag** — 在 `crates/librefang-channels/Cargo.toml` 中添加 `channel-myplatform = []`（如有特殊依赖则绑定 `dep:`），并将其加入 `all-channels` 列表

3. **转发 Feature Flag** — 在 `crates/librefang-api/Cargo.toml` 中添加 `channel-myplatform = ["librefang-channels/channel-myplatform"]`，并加入其 `all-channels` 列表

4. **注册模块** — 在 `crates/librefang-channels/src/lib.rs` 中添加条件编译模块声明：
```rust
#[cfg(feature = "channel-myplatform")]
pub mod myplatform;
```

5. **接入 Bridge** — 在 `crates/librefang-api/src/channel_bridge.rs` 中添加适配器初始化逻辑

6. **添加配置支持** — 在 `librefang-types` 中添加配置结构体（包含 `token_env`、`default_agent`、`overrides` 字段），并加入 `ChannelsConfig`

7. **添加 CLI 向导** — 在 `crates/librefang-cli/src/main.rs` 的 `cmd_channel_setup` 中添加交互式设置流程

8. **编写测试** — 使用 `ChannelMessage` 类型编写集成测试，无需连接真实平台即可验证适配器逻辑
227 changes: 63 additions & 164 deletions src/app/zh/roadmap/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,180 +1,79 @@
# 发布路线图
# 路线图与状态

LibreFang 竞争差距分析。组织为 4 个冲刺阶段。
LibreFang 当前开发状态与未来计划。

---

## Sprint 1 — 止血 (3-4 天)

这些是阻止性问题。应用会崩溃或显示异常。

### 1.1 修复 Token 膨胀 — ✅ 完成

**状态: 已完成** — 在 compactor.rs, context_overflow.rs, context_budget.rs, agent_loop.rs, kernel.rs, agent.rs 和 prompt_builder.rs 中实现了全部 13 项。

**问题:** 单条聊天消息消耗约 45K 输入 token（工具定义 + 系统提示）。到第 3 条消息时，达到 100K 配额并崩溃。

**完成标准:**
- `cargo test --workspace` 通过
- 启动 Agent，发送 10+ 条消息 — 无 "Token quota exceeded" 错误
- 首条消息 token 数从 ~45K 降至 ~15-20K

### 1.2 品牌与图标资源 — ✅ 完成

**状态: 已完成** — 桌面应用显示 LibreFang 品牌图标。

### 1.3 Tauri 签名密钥对 — ✅ 完成

**状态: 已完成** — 通过 `cargo tauri signer generate --ci` 生成 Ed25519 签名密钥对。

### 1.4 首次运行体验审计 — ✅ 完成

**状态: 已完成** — 完整代码审计验证：全部 8 个向导 API 端点存在并已实现。

---

## Sprint 2 — 竞争对等 (4-5 天)

这些缩小与 OpenClaw 的差距。

### 2.1 浏览器截图渲染 — ✅ 完成

**状态: 已完成** — browser.rs 保存截图到上传目录并返回 JSON 包含 `image_urls`。chat.js 检测 `browser_screenshot` 工具结果并显示内联图像。

### 2.2 聊天消息搜索 — ✅ 完成

**状态: 已完成** — 搜索栏支持 Ctrl+F 快捷键，实时过滤，高亮匹配文本。

### 2.3 技能市场优化 — ✅ 完成

**状态: 已完成** — 技能页面已优化，包含 4 个标签页（已安装、ClawHub、MCP 服务器、快速开始）、实时搜索、分类排序。

### 2.4 安装脚本部署

**问题:** `librefang.ai` 安装端点需要连接。

**完成标准:**
- `curl -fsSL https://librefang.ai/install.sh | sh` 安装最新版本
- `irm https://librefang.ai/install.ps1 | iex` 在 Windows PowerShell 中工作

### 2.5 向导端到端 — ✅ 完成

**状态: 已完成** — 6 步向导（欢迎 → 提供商 → Agent → 试用 → 通道 → 完成）完全连接。
## 已完成功能

### 核心基础设施

- Token 上下文管理 — 自动压缩、70%/90% 阈值守卫、工具按 profile 过滤
- 品牌与图标资源 — 桌面应用、Web UI、favicon 全套品牌素材
- Tauri 签名密钥对 — Ed25519 签名，支持自动更新
- 首次运行向导 — 6 步引导（欢迎 → 提供商 → Agent → 试用 → 通道 → 完成）
- 浏览器截图渲染 — 工具卡片内联显示截图
- 聊天消息搜索 — Ctrl+F 快捷键，实时过滤与高亮
- 技能市场 — 4 个标签页，实时搜索，安装/卸载管理
- 语音输入/输出 — 按住录音、自动转录、TTS 播放
- Canvas 渲染 — iframe 沙箱渲染，CSP 安全策略
- JavaScript/Python SDK — REST 客户端，SSE 流式传输
- Prometheus 指标导出 — `/api/metrics` 端点
- 可视化工作流构建器 — SVG 拖放节点，贝塞尔曲线连接，TOML 导出
- 多会话支持 — 每个 Agent 支持多个独立会话
- 配置热重载 — 30 秒轮询检测 `config.toml` 变化
- 性能优化 — Health p99 = 0.8ms，指标端点 2,792 req/sec

### 平台数据

| 类别 | 数量 |
|------|------|
| 通道适配器 | 41 个（12 个默认，通过 feature flag 按需启用） |
| LLM 提供商 | 27+ 个，130+ 模型 |
| 内置技能 | 60+ 个 |
| 内置工具 | 41 个 |
| Agent 模板 | 30 个预配置 |
| 安全系统 | 16 层防御 |
| 测试覆盖 | 2100+ 个测试 |

---

## Sprint 3 — 差异化 (5-7 天)

这些是 LibreFang 可以超越 OpenClaw 的功能。

### 3.1 语音输入/输出 — ✅ 完成

**状态: 已完成** — 麦克风按钮支持按住录音，MediaRecorder 使用 webm/opus 编解码器，自动上传和转录，TTS 音频播放器。

### 3.2 Canvas 渲染验证 — ✅ 完成

**状态: 已完成** — 修复 CSP 允许 `frame-src 'self' blob:` 和 `media-src 'self' blob:`。

### 3.3 JavaScript/Python SDK — ✅ 完成

**状态: 已完成** — 创建了 `sdk/javascript/` (@librefang/sdk) 和 `sdk/python/librefang_client.py`。

### 3.4 可观测性与指标导出 — ✅ 完成

**状态: 已完成** — 添加 `GET /api/metrics` 端点返回 Prometheus 格式。

### 3.5 可视化工作流构建器 — ✅ 完成

**状态: 已完成** — 添加了基于 SVG canvas 的完整可视化构建器。支持节点拖放、贝塞尔曲线连接、缩放/平移、TOML 导出。
## 功能概览

| 功能 | 说明 |
|------|------|
| 语言/性能 | Rust 编写，~30MB 单二进制文件 |
| 通道 | 41 个消息平台适配器 |
| 内置工具 | 41 个（文件、浏览器、代码、搜索等） |
| 工作流引擎 | 完整 DAG，支持并行/循环/条件 |
| 知识图谱 | 实体关系图谱 |
| P2P 网络 | OFP 线协议 |
| WASM 沙箱 | 双计量 WASM 执行环境 |
| 桌面应用 | Tauri (~30MB)，支持自动更新 |
| 插件 SDK | JavaScript + Python 客户端库 |
| 可视化工作流 | 拖放式构建器 |
| 可观测性 | Prometheus 指标导出 |
| 语音交互 | 麦克风录音 + TTS 播放 |

---

## Sprint 4 — 优化与发布 (3-4 天)

### 4.1 多会话支持 — ✅ 完成

**状态: 已完成** — 每个 Agent 支持多个会话，UI 中有会话下拉切换。

### 4.2 配置热重载 — ✅ 完成

**状态: 已完成** — 添加了基于轮询的配置监视器（每 30 秒），自动检测 `config.toml` 变化。

### 4.3 CHANGELOG 和 README 优化 — ✅ 完成
## 下一步计划

**状态: 已完成** — 更新了 CHANGELOG.md 和 README.md。
### 短期

### 4.4 性能与负载测试 — ✅ 完成
- **安装脚本部署** — 完成 `librefang.ai` 域名安装端点（`curl -fsSL https://librefang.ai/install.sh | sh`）
- **v0.1.0 正式发布** — 打标签、构建发布产物（桌面安装包、CLI 二进制、Docker 镜像）
- **自动更新验证** — 使用 v0.1.1 测试 Tauri 自动更新流程

**状态: 已完成** — 创建了 `load_test.rs` 包含 7 个负载测试。
### 中期

**结果:**
- Health: p99 = 0.8ms
- Agent list: p99 = 0.5ms
- Metrics: 2,792 req/sec
- 并发读取: 1,728 req/sec
- 生成: 97/sec
- **移动端支持** — Web 响应式优化，PWA 支持
- **语音唤醒词** — 离线唤醒词检测
- **A2A 协议扩展** — 完善 Agent-to-Agent 互操作
- **外部模型目录** — 从远程注册表同步模型元数据

### 4.5 最终发布 — ✅ 就绪

**状态: 全部代码完成** — 全部 18 项代码完成。1751 个测试通过。生产审计完成。

---

## 功能对比

| 功能 | OpenClaw | LibreFang | 胜者 |
|------|-----------|-----------|------|
| 语言/性能 | Node.js (~200MB) | Rust (~30MB 单二进制) | **LibreFang** |
| 通道 | ~15 | **40** | **LibreFang** |
| 内置工具 | ~19 | **41** | **LibreFang** |
| 安全系统 | Token + 沙箱 | **16 层防御** | **LibreFang** |
| Agent 模板 | 手动配置 | **30 个预配置** | **LibreFang** |
| Hands (自主) | 无 | **7 个包** | **LibreFang** |
| 工作流引擎 | Cron + webhooks | **完整 DAG** | **LibreFang** |
| 知识图谱 | 平面向量存储 | **实体关系图** | **LibreFang** |
| P2P 网络 | 无 | **OFP 协议** | **LibreFang** |
| WASM 沙箱 | 仅 Docker | **双计量 WASM** | **LibreFang** |
| 桌面应用 | Electron (~200MB) | **Tauri (~30MB)** | **LibreFang** |
| 迁移 | N/A | **`migrate --from openclaw`** | **LibreFang** |
| 技能 | 54 个捆绑 | **60 个捆绑** | **LibreFang** |
| LLM 提供商 | ~15 | **27 提供商, 130+ 模型** | **LibreFang** |
| 插件 SDK | TypeScript | JS + Python SDK | **平局** |
| 本地移动 | iOS + Android + macOS | 仅 Web 响应式 | OpenClaw |
| 语音模式 | 唤醒词 + TTS | 麦克风 + TTS 播放 | OpenClaw (略胜) |
| 浏览器自动化 | Playwright | Playwright + 内联截图 | **平局** |
| 可视化工作流 | 无 | **拖放构建器** | **LibreFang** |

**LibreFang 赢得 15/18 类别。**

---
### 长期

## 快速参考: 状态

```
Sprint 1: 已完成
1.1 Token 膨胀修复 .............. ✅
1.2 品牌资源 ................. ✅
1.3 Tauri 签名密钥 ........... ✅
1.4 首次运行审计 ............ ✅

Sprint 2: 4/5 已完成
2.1 浏览器截图 ............ ✅
2.2 聊天搜索 .............. ✅
2.3 技能市场 .............. ✅
2.4 安装脚本域名 .......... 待定
2.5 向导端到端 ............ ✅

Sprint 3: 已完成
3.1 语音 UI .............. ✅
3.2 Canvas 验证 .......... ✅
3.3 JS/Python SDK ........ ✅
3.4 可观测性 .............. ✅
3.5 可视化工作流构建器 .... ✅

Sprint 4: 已完成
4.1 多会话 ................ ✅
4.2 配置热重载 ........... ✅
4.3 CHANGELOG + README ... ✅
4.4 负载测试 ............. ✅
4.5 最终发布 .............. ✅ 就绪
```
- **原生移动应用** — iOS / Android 客户端
- **联邦学习** — 跨节点隐私安全的模型微调
- **企业级部署** — 多租户、RBAC、审计日志