使用示例

本页按 LibreFang 的核心能力组织，覆盖 Agent、Hands、Channels、Workflows、Scheduling、Webhooks、Memory 和 API 的典型用法。示例基于当前源码里的 CLI、REST API 和配置结构编写。

如果你想看字段完整说明，继续读：

LibreFang 能做什么

先看能力边界，再看具体用法。

LibreFang 在当前源码里不是单一“聊天机器人框架”，而是一个 Agent OS，能力大致分成这几层：

Agent：可以生成内置模板 Agent，也可以用 agent.toml 自定义 Agent，然后通过 CLI、Dashboard 或 REST API 给它发消息。
Hands：这是预打包的自主能力模块，比如 researcher、lead、browser、clip、devops。适合“持续工作”而不是只回一条消息。
Channels：可以把 Agent 接到 Telegram、Discord、Slack、WeChat 等外部通道，让用户在外部平台里直接和 Agent 交互。
Workflows：可以把多个 Agent 串成多步骤流水线。当前引擎支持顺序执行、fan-out / collect、conditional、loop 这些模式。
Scheduling：可以用 cron 定时给 Agent 发送 prompt，让它周期性工作。
Webhooks / Triggers：可以让外部 HTTP 回调或系统事件触发 Agent。
Memory：每个 Agent 有自己的 KV 记忆空间，用于跨会话保存状态。
Skills / MCP / Extensions：Agent 可以挂技能，也可以接 MCP server，扩展可用工具。
Control Plane：有 Dashboard、REST API、TUI、审批队列、安全审计这些管理面能力。

这页主要回答两个问题：

LibreFang 能用来做什么？
这些能力在当前源码里该怎么配、怎么跑？

下面按这个顺序展开。

1. 先跑起来

首次运行时，librefang start 会自动执行快速初始化，默认 API 和 Dashboard 地址是 http://127.0.0.1:4545。

# 先配置一个模型供应商的 API Key。下面以 Groq 为例。
export GROQ_API_KEY="gsk_your_key_here"

# 启动守护进程（首次运行会自动 quick init）
librefang start

# 和默认 assistant 对话
librefang chat

# 打开 Dashboard
librefang dashboard

如果你想显式初始化：

librefang init
# 或
librefang init --quick

2. 使用内置 Agent 模板

最直接的用法不是先写复杂配置，而是先生成一个现成模板，然后给它发消息。

# 生成一个内置 coder Agent
librefang agent new coder

# 查看当前运行中的 Agent
librefang agent list

# 给它发一条一次性消息
librefang message coder "Review the error handling in src/main.rs"

# 进入交互式聊天
librefang chat coder

常用模板包括 assistant、coder、researcher、writer、customer-support、meeting-assistant。

这层对应的是 LibreFang 最基础的能力：把一个 Agent 跑起来并让它完成具体任务。如果你的需求是“写代码”“审查 PR”“写文档”“做研究”，通常从这里开始。

3. 从 `agent.toml` 生成自定义 Agent

当前源码里，Agent 提示词应该写在 [model].system_prompt 下，而不是单独的 [system_prompt] 表。

# customer-support.toml
name = "customer-support"
version = "0.1.0"
description = "Customer support agent"
author = "your-name"
module = "builtin:chat"
tags = ["support", "example"]

[model]
provider = "default"
model = "default"
system_prompt = """
You are a customer support agent.

Rules:
- Reply politely and concisely.
- If the user asks about refunds or billing, collect facts first.
- Store important customer facts in memory.
- If you are unsure, say so clearly.
"""

[resources]
max_llm_tokens_per_hour = 50000

[capabilities]
tools = ["file_read", "web_fetch", "memory_recall", "memory_store"]
memory_read = ["customer:*"]
memory_write = ["customer:*"]
network = ["*"]

生成并使用：

librefang agent spawn ./customer-support.toml
librefang message customer-support "A user says their payment failed."

4. 把渠道接到 Agent

渠道配置写在 ~/.librefang/config.toml 的 [channels.<name>] 下，不是 [telegram] 或 [discord] 顶层表。

这层对应的是 LibreFang 的“外部入口”能力：让 Agent 不只在 CLI 里用，而是能在 Telegram、Discord、Slack、WeChat 等地方直接工作。

最简单的方式是交互式配置：

librefang channel setup telegram
librefang channel list

手动配置示例：

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "customer-support"
allowed_users = []

[channels.telegram.overrides]
system_prompt = "Reply as a concise and polite support bot."
rate_limit_per_user = 10

修改完配置后重启：

librefang restart

如果已经有聊天目标，可以做一次联通性检查：

librefang channel test telegram --chat-id 123456789

5. 定时运行 Agent

当前 CLI 里，定时任务是独立的 cron 子命令，不是写在工作流 JSON 的 trigger 里。

这层对应的是“自主运行”能力里最直接的一种：按时间表触发 Agent。

# 每天早上 8 点让 researcher 生成新闻摘要
librefang cron create researcher "0 8 * * *" \
  "Fetch the top AI and tech news and write a 10-bullet digest"

# 查看任务
librefang cron list

如果你已经有自定义 Agent，也可以直接给它设定周期任务：

librefang cron create customer-support "0 */2 * * *" \
  "Summarize unresolved support issues from the last 2 hours"

6. 创建多步骤工作流

当前 /api/workflows 接受的步骤字段是 name、agent_name 或 agent_id、prompt、mode、timeout_secs、error_mode、output_var 等。

这层对应的是“多 Agent 编排”能力。不是单个 Agent 回一段话，而是多个 Agent 分工执行一个流程。

也就是说，下面这些旧写法不是当前工作流格式：

steps[].type = "agent"
steps[].agent = "writer"
steps[].input = "..."
steps[].type = "notification"
顶层 trigger

一个当前源码可用的工作流文件如下：

{
  "name": "review-pipeline",
  "description": "Analyze code and then turn the findings into a review note",
  "steps": [
    {
      "name": "analyze",
      "agent_name": "coder",
      "prompt": "Analyze the following patch for bugs, regressions, and missing tests:\\n\\n{{input}}",
      "mode": "sequential",
      "timeout_secs": 180,
      "error_mode": "fail",
      "output_var": "analysis"
    },
    {
      "name": "summary",
      "agent_name": "writer",
      "prompt": "Turn this analysis into a concise review comment:\\n\\n{{analysis}}",
      "mode": "sequential",
      "timeout_secs": 120,
      "error_mode": "fail"
    }
  ]
}

创建和执行：

librefang workflow create ./review-pipeline.json
librefang workflow list
librefang workflow run <WORKFLOW_ID> "Review this Rust patch for behavioural regressions"

如果你需要“收到 HTTP 请求就触发 Agent”，当前 CLI 用的是独立的 webhook 命令：

librefang webhooks create code-reviewer https://example.com/github-pr
librefang webhooks list

7. 使用 Hands

Hands 是已经打包好的自主能力模块。对于很多场景，直接激活 Hand 比自己拼配置更省事。

这层对应的是 LibreFang 最像“产品能力包”的部分。很多高层场景，比如研究、OSINT、线索挖掘、浏览器自动化、内容生成，更应该先看 Hand，而不是从零拼 Agent。

# 看看有哪些 Hand
librefang hand list

# 激活 researcher
librefang hand activate researcher

# 查看运行状态
librefang hand status researcher

# 查看 / 修改配置
librefang hand settings researcher
librefang hand set researcher max_results 20

# 和 Hand 对话
librefang hand chat researcher

如果缺依赖，可以先检查：

librefang hand check-deps researcher
librefang hand install-deps researcher

8. 使用 Agent Memory

当前 CLI 的 memory 命令是按“某个 Agent 的 KV 存储”来用的，不是全局 --key/--value 风格。

# 写入一条记忆
librefang memory set customer-support customer:alice:last_order "A-1024"

# 读取
librefang memory get customer-support customer:alice:last_order

# 列出这个 Agent 的所有记忆键
librefang memory list customer-support

# 删除
librefang memory delete customer-support customer:alice:last_order

9. 用 REST API 调用 LibreFang

如果你想从外部程序调用，最常见的是创建 Agent 然后发消息。

用模板创建 Agent

curl -X POST http://127.0.0.1:4545/api/agents \
  -H "Content-Type: application/json" \
  -d '{"template": "assistant"}'

给 Agent 发消息

curl -X POST http://127.0.0.1:4545/api/agents/<AGENT_ID>/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the current status of the project."}'

直接上传 manifest 创建 Agent

curl -X POST http://127.0.0.1:4545/api/agents \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "manifest_toml": "name = \"api-agent\"\nmodule = \"builtin:chat\"\n\n[model]\nprovider = \"default\"\nmodel = \"default\"\nsystem_prompt = \"You are a concise API agent.\"\n"
}
JSON

10. 当前源码里的几个关键点

Agent 提示词写在 [model].system_prompt，不是 [system_prompt].prompt。
通道配置写在 [channels.<name>]，例如 [channels.telegram]。
工作流步骤使用 agent_name 或 agent_id 加 prompt，不是 type/agent/input 这一套。
定时任务用 librefang cron ...，Webhook 用 librefang webhooks ...。
当前 CLI 没有 librefang memory search 或 librefang kg query 这两个命令。

如果你想做的是“客服机器人”“定时摘要”“代码审查”“渠道接入”，建议按这条顺序上手：

librefang start
librefang agent new <template> 或 librefang agent spawn ./agent.toml
librefang message <agent> "..."
librefang channel setup <channel> 或编辑 [channels.<name>]
librefang cron create ... / librefang workflow create ...