# 使用示例

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

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

- [Agent 模板目录](/zh/agent/templates)
- [工作流引擎指南](/zh/agent/workflows)
- [自主 Hands](/zh/agent/hands)
- [通道配置](/zh/configuration/channels)

---

## 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、审批队列、安全审计这些管理面能力。

这页主要回答两个问题：

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

下面按这个顺序展开。

---

## 1. 先跑起来

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

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

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

# 和默认 assistant 对话
librefang chat

# 打开 Dashboard
librefang dashboard
```

如果你想显式初始化：

```bash
librefang init
# 或
librefang init --quick
```

---

## 2. 使用内置 Agent 模板

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

```bash
# 生成一个内置 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]` 表。

```toml
# 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 = ["*"]
```

生成并使用：

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

---

## 4. 把渠道接到 Agent

渠道配置写在 `~/.librefang/config.toml` 的 `[[sidecar_channels]]` array-of-tables 条目里。每条条目声明一个独立进程的 sidecar adapter（`name` / `command` / `args` / `channel_type`，加上 `[sidecar_channels.env]` 子表存放非 secret 环境变量）。Secret 类的环境变量写到 `~/.librefang/secrets.env`。

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

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

```bash
librefang channel setup telegram
librefang channel list
```

手动配置示例（Telegram 使用 sidecar 适配器）：

```toml
[[sidecar_channels]]
name = "telegram"
command = "python3"
args = ["-m", "librefang.sidecar.adapters.telegram"]
channel_type = "telegram"
[sidecar_channels.env]
TELEGRAM_BOT_TOKEN = "..."
```

修改完配置后重启：

```bash
librefang restart
```

要确认 sidecar 已起、能连上 Telegram，热加载后 tail 一下 sidecar 自己的日志（sidecar 把结构化状态打到 stdout）：

```bash
curl -X POST http://127.0.0.1:4545/api/channels/reload
librefang logs --filter sidecar/telegram --tail 50
```

---

## 5. 定时运行 Agent

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

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

```bash
# 每天早上 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，也可以直接给它设定周期任务：

```bash
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`

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

```json
{
  "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"
    }
  ]
}
```

创建和执行：

```bash
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 命令：

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

---

## 7. 使用 Hands

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

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

```bash
# 看看有哪些 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
```

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

```bash
librefang hand check-deps researcher
librefang hand install-deps researcher
```

---

## 8. 使用 Agent Memory

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

```bash
# 写入一条记忆
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

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

### 给 Agent 发消息

```bash
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

```bash
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.discord]`。Telegram 现已改为 sidecar 模式，使用 `[[sidecar_channels]]` 而非 `[channels.telegram]`。
- 工作流步骤使用 `agent_name` 或 `agent_id` 加 `prompt`，不是 `type/agent/input` 这一套。
- 定时任务用 `librefang cron ...`，Webhook 用 `librefang webhooks ...`。
- 当前 CLI 没有 `librefang memory search` 或 `librefang kg query` 这两个命令。

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

1. `librefang start`
2. `librefang agent new <template>` 或 `librefang agent spawn ./agent.toml`
3. `librefang message <agent> "..."`
4. `librefang channel setup <channel>` 或者直接编辑一条 `[[sidecar_channels]]`
5. `librefang cron create ...` / `librefang workflow create ...`
