自主 Hands
LibreFang 的核心创新——预构建的自主能力包，独立运行，通过 LLM Agent 执行任务，无需人工干预。
提示: Hands 通过 CLI 或 REST API 激活。每个 Hand 会生成一个或多个 Agent，支持交互式对话。
概述
Hands 是 LibreFang 的独特功能，它们是自主工作的 Agent，可以：
- 通过 LLM 驱动的 Agent 自动执行任务
- 处理复杂的多步骤工作流
- 通过 settings 配置（提供者、模型、API Key 等）
- 支持单 Agent 或多 Agent 模式
内置 Hands
| Hand | 功能 | 类型 |
|---|---|---|
| Clip | YouTube 视频下载、剪辑、字幕生成 | 多 Agent |
| Creator | AI 媒体工作室 — 图像、视频、音乐和语音生成 | 多 Agent |
| Lead | 每日潜在客户发现、信息丰富、0-100 评分、去重 | 多 Agent |
| Collector | OSINT 情报收集、变更检测、知识图谱 | 多 Agent |
| Predictor | 超级预测引擎、置信区间、反向模式 | 单 Agent |
| Researcher | 深度自主研究、CRAAP 可信度评估、APA 引用 | 多 Agent |
| 自主 X/Twitter 账号管理、多种内容格式、审批队列 | 多 Agent | |
| Browser | Web 自动化、Playwright、强制购买审批 | 单 Agent |
| Analytics | 业务分析、KPI 追踪、自动化报告 | 多 Agent |
| ApiTester | 自动化 API 测试、合约验证、回归检测 | 单 Agent |
| DevOps | CI/CD 监控、部署自动化、基础设施告警、自动进化（PR review + BMAD bug/feature 流水线） | 多 Agent |
| LinkedIn 档案监控、外展自动化 | 多 Agent | |
| Reddit 社区监控、帖子排期、情感追踪 | 多 Agent | |
| Strategist | 战略分析、竞争情报、场景规划 | 多 Agent |
| Trader | 市场数据监控、信号生成、投资组合追踪 | 多 Agent |
CLI 命令
Hand 管理
# 列出所有可用的 Hands
librefang hand list
# 显示当前活跃的 Hand 实例
librefang hand active
# 查看指定 Hand 的状态
librefang hand status clip
# 查看 Hand 详细信息
librefang hand info clip
# 从磁盘重新加载 Hand 定义
librefang hand reload
激活生命周期
# 激活 Hand
librefang hand activate clip
# 暂停运行中的 Hand
librefang hand pause clip
# 恢复已暂停的 Hand
librefang hand resume clip
# 停用 Hand
librefang hand deactivate clip
配置
# 查看 Hand 当前设置
librefang hand settings clip
# 设置配置值
librefang hand set clip stt_provider groq
交互
# 与活跃的 Hand 进行交互式对话
librefang hand chat clip
依赖管理
# 检查依赖状态
librefang hand check-deps clip
# 安装缺失的依赖
librefang hand install-deps clip
本地安装
# 从本地目录安装 Hand
librefang hand install ./my-hand
Hand 状态
| 状态 | 说明 |
|---|---|
| Active | 运行中，Agent 已生成 |
| Paused | 已暂停，可恢复 |
| Error | 发生错误，需要干预 |
| Inactive | 未激活 |
HAND.toml 格式
单 Agent Hand
id = "my-hand"
version = "1.0.0"
name = "My Hand"
description = "这个 Hand 做什么"
category = "content"
icon = "M"
tools = ["shell_exec", "web_fetch"]
[[requires]]
key = "ffmpeg"
label = "FFmpeg must be installed"
requirement_type = "binary"
check_value = "ffmpeg"
[[settings]]
key = "quality"
label = "Output Quality"
setting_type = "select"
default = "high"
[[settings.options]]
value = "high"
label = "High (1080p)"
[[settings.options]]
value = "low"
label = "Low (480p)"
[agent]
name = "my-hand-agent"
description = "Processes tasks"
system_prompt = "You are a task processing agent."
[agent.model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 4096
temperature = 0.7
[dashboard]
metrics = []
[routing]
aliases = ["my-hand", "process"]
weak_aliases = ["task", "automate"]
多 Agent Hand
id = "research"
version = "2.0.0"
name = "Research Hand"
description = "多 Agent 研究系统"
category = "content"
tools = ["web_fetch"]
[agents.planner]
coordinator = true
invoke_hint = "Use planner for task decomposition"
name = "planner-agent"
description = "Plans research tasks"
model = "default"
system_prompt = "You plan and coordinate research tasks."
[agents.analyst]
name = "analyst-agent"
description = "Analyzes and synthesizes data"
provider = "groq"
model = "llama-3.3-70b-versatile"
system_prompt = "You analyze data and produce insights."
[dashboard]
metrics = []
旧版扁平格式（向后兼容）
单 Agent Hand 可以使用扁平字段代替 [agent.model]：
[agent]
name = "my-agent"
description = "Simple agent"
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 4096
temperature = 0.7
system_prompt = "You are a helpful agent."
调度
只有角色自己的配置段明确声明，该角色才会自行唤醒，且只有以下两种写法。 其余角色一律保持 reactive：收到消息或事件时才运行，绝不按定时器唤醒。
显式的 schedule 优先级最高，原样生效。
它也是取得 cron（periodic）或条件驱动（proactive）调度的唯一途径。
ScheduleMode 使用外部标签（externally tagged）序列化，因此结构体变体必须写成子表——裸的 schedule = "continuous" 字符串无法解析，而单元变体 schedule = "reactive" 可以。
[agents.monitor.schedule.continuous]
check_interval_secs = 1800
显式的 [autonomous] 配置块会让角色按该块自己的 heartbeat_interval_secs 唤醒（该块未写时为 30 秒）：
[agents.monitor.autonomous]
max_iterations = 40
heartbeat_interval_secs = 900
两者同时写是允许的，此时节奏由 schedule 决定，[autonomous] 只提供角色唤醒后运行所依据的护栏。
若想保留这些护栏但关掉唤醒周期，在该块旁边写上 schedule = "reactive"。
max_iterations 本身只是循环深度上限——单轮对话内工具调用迭代次数的上限——不产生任何调度效果：
[agents.main]
name = "main-agent"
# 限制单轮的工具循环深度。
# 该角色仍然只在被消息触发时运行。
max_iterations = 80
[metadata] frequency 是市场列表用的展示元数据，不控制调度：
[metadata]
# continuous | hourly | daily | periodic | on-demand
# 默认值是 "on-demand"；"reactive" 是它的另一种写法。
frequency = "continuous"
Shell 执行策略
tools 列表中包含 shell_exec（或 * 通配符）的 Hand，会继承守护进程的全局 [exec_policy]，mode 也一并继承。
激活流程绝不会授予比运维人员配置更宽松的 mode。
全局默认 mode 是 allowlist，且 allowed_commands 为空、safe_bins 只含只读工具，因此需要执行真实命令的 Hand 要么依赖运维侧的 allowed_commands 条目，要么自己声明：
[agents.main.exec_policy]
mode = "allowlist"
allowed_commands = ["git", "cargo"]
timeout_secs = 600
Hand 自己声明的策略会被原样采纳，这样提权后的执行姿态就写在 Hand 自己的 manifest 里，而不是激活时一次不可见的授权。
执行策略在激活该 Hand 时解析，因此对它的修改会在下一次激活时生效。
调度的解析更早，发生在 HAND.toml 被解析进注册表的时刻——即守护进程启动时以及调用 POST /api/hands/reload 时——因此对 schedule 或 [autonomous] 的修改需要先经过这一次重新加载（或者重启守护进程，届时所有定义都会重新解析、所有持久化的 Hand 都会重新激活），之后的激活才能读到新值。
REST API 端点
Hand 发现
| 端点 | 方法 | 说明 |
|---|---|---|
/api/hands | GET | 列出所有已注册的 Hands 及状态 |
/api/hands/active | GET | 列出当前活跃的 Hand 实例 |
/api/hands/{hand_id} | GET | 获取指定 Hand 的详情 |
/api/hands/{hand_id}/activate | POST | 激活 Hand（生成 Agent） |
/api/hands/{hand_id}/check-deps | POST | 检查依赖可用性 |
/api/hands/{hand_id}/install-deps | POST | 安装缺失的依赖 |
/api/hands/reload | POST | 从磁盘重新加载 Hand 定义 |
Hand 配置
| 端点 | 方法 | 说明 |
|---|---|---|
/api/hands/{hand_id}/settings | GET | 获取当前 Hand 配置 |
/api/hands/{hand_id}/settings | PUT | 更新 Hand 配置 |
实例生命周期
| 端点 | 方法 | 说明 |
|---|---|---|
/api/hands/instances/{id}/pause | POST | 暂停运行中的 Hand 实例 |
/api/hands/instances/{id}/resume | POST | 恢复已暂停的 Hand 实例 |
/api/hands/instances/{id} | DELETE | 停用并移除 Hand 实例 |
/api/hands/instances/{id}/message | POST | 向 Hand 实例发送消息 |
示例：激活并对话
# 激活
curl -X POST http://127.0.0.1:4545/api/hands/clip/activate
# 发送消息
curl -X POST http://127.0.0.1:4545/api/hands/instances/<instance-id>/message \
-H "Content-Type: application/json" \
-d '{"message": "下载这个视频并生成字幕"}'