智能与技能 API

记忆系统、技能市场、ClawHub、Hands 自动化、扩展、插件和媒体生成的端点。

记忆端点

LibreFang 提供两套记忆系统：每个 Agent 独立的简单键值存储，以及支持关系图谱和衰减的主动式语义记忆系统（类 mem0 风格）。

GET /api/memory/agents/{id}/kv

列出 Agent 的所有键值对。

响应 200 OK：

{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}

GET /api/memory/agents/{id}/kv/{key}

获取指定的键值对。

响应 200 OK：

{
  "key": "preferences",
  "value": {"theme": "dark"}
}

响应 404 Not Found（键不存在时）：

{
  "error": "Key 'preferences' not found"
}

PUT /api/memory/agents/{id}/kv/{key}

设置键值对。创建或覆盖。

请求体：

{
  "value": {"theme": "dark", "language": "en"}
}

响应 200 OK：

{
  "status": "stored",
  "key": "preferences"
}

DELETE /api/memory/agents/{id}/kv/{key}

删除键值对。

响应 200 OK：

{
  "status": "deleted",
  "key": "preferences"
}

GET /api/memory

列出所有主动式记忆条目（全局，跨 Agent 和用户）。

POST /api/memory

添加新的主动式记忆条目。

请求体：

{
  "content": "User prefers concise answers",
  "agent_id": "a1b2c3d4-...",
  "user_id": "user-1",
  "tags": ["preference"]
}

GET /api/memory/search

使用语义相似性搜索主动式记忆。

查询参数：

• q（必填）：搜索查询字符串
• agent_id（可选）：限制为特定 Agent
• limit（可选）：最大结果数（默认：10）

GET /api/memory/stats

获取主动式记忆存储的聚合统计信息。

POST /api/memory/cleanup

移除过期或陈旧的记忆条目。

POST /api/memory/decay

对记忆条目评分施加时间衰减（降低旧条目的相关性）。

POST /api/memory/bulk-delete

通过 ID 列表批量删除记忆条目。

PUT /api/memory/items/{memory_id}

更新指定的记忆条目。

DELETE /api/memory/items/{memory_id}

删除指定的记忆条目。

GET /api/memory/items/{memory_id}/history

获取指定记忆条目的编辑历史。

GET /api/memory/user/{user_id}

获取与指定用户关联的所有记忆条目。

GET /api/memory/agents/{id}

列出指定 Agent 的所有主动式记忆条目。

DELETE /api/memory/agents/{id}

删除指定 Agent 的所有主动式记忆条目。

GET /api/memory/agents/{id}/search

搜索指定 Agent 的主动式记忆。

GET /api/memory/agents/{id}/stats

获取指定 Agent 的记忆统计信息。

DELETE /api/memory/agents/{id}/level/{level}

清除指定 Agent 在特定重要性级别的所有记忆条目。

GET /api/memory/agents/{id}/duplicates

查找指定 Agent 的重复记忆条目。

POST /api/memory/agents/{id}/consolidate

合并和去重指定 Agent 的记忆条目。

GET /api/memory/agents/{id}/count

获取指定 Agent 的记忆条目总数。

GET /api/memory/agents/{id}/relations

查询指定 Agent 的关系图谱条目。

POST /api/memory/agents/{id}/relations

为指定 Agent 存储新的关系图谱条目。

GET /api/memory/agents/{id}/export

将指定 Agent 的所有主动式记忆条目导出为 JSON。

POST /api/memory/agents/{id}/import

从 JSON 导入指定 Agent 的主动式记忆条目。

技能和市场端点

管理技能注册表。技能通过 Python、Node.js、WASM 或纯提示模块扩展 Agent 的能力。所有技能安装都会经过 SHA256 验证和提示注入扫描。

GET /api/skills

列出所有已安装的技能。

响应 200 OK：

{
  "skills": [
    {
      "name": "github",
      "version": "1.0.0",
      "runtime": "PromptOnly",
      "description": "GitHub integration for issues, PRs, and repos",
      "author": "librefang",
      "tags": ["devtools"],
      "tools_count": 0,
      "enabled": true,
      "has_prompt_context": true,
      "source": {"type": "local"}
    }
  ],
  "total": 60,
  "categories": ["ai-ml", "cloud", "data", "devtools", "general"]
}

POST /api/skills/install

从本地路径或 URL 安装技能。技能清单会经过验证（SHA256 校验和）并在安装前扫描提示注入。

请求体：

{
  "source": "/path/to/skill",
  "verify": true
}

响应 201 Created：

{
  "status": "installed",
  "skill": "my-custom-skill",
  "version": "1.0.0"
}

POST /api/skills/uninstall

移除已安装的技能。内置技能无法被卸载。

请求体：

{
  "name": "my-custom-skill"
}

响应 200 OK：

{
  "status": "uninstalled",
  "skill": "my-custom-skill"
}

POST /api/skills/create

通过 evolution 模块创建一个新的 prompt-only 技能。技能会被校验、安全扫描，并立即热加载到注册表。

请求体：

{
  "name": "csv-analysis",
  "description": "Expert CSV data analysis and cleaning workflows",
  "prompt_context": "# CSV Analysis\n\nWhen analyzing CSV files...",
  "tags": ["data", "csv"]
}

响应 200 OK：

{
  "status": "created",
  "name": "csv-analysis",
  "version": "0.1.0",
  "message": "Skill 'csv-analysis' created successfully"
}

GET /api/skills/{name}

获取某个技能的详细信息，包括演化历史、工具、配套文件以及使用指标。

响应 200 OK：

{
  "name": "csv-analysis",
  "version": "0.1.2",
  "description": "Expert CSV data analysis and cleaning workflows",
  "author": "agent-evolved",
  "license": "",
  "tags": ["data", "csv"],
  "runtime": "PromptOnly",
  "tools": [],
  "has_prompt_context": true,
  "prompt_context_length": 2450,
  "source": "Local",
  "enabled": true,
  "path": "/home/user/.librefang/skills/csv-analysis",
  "linked_files": {
    "references": ["pandas-cheatsheet.md"],
    "templates": ["clean.py"]
  },
  "evolution": {
    "versions": [
      {
        "version": "0.1.0",
        "timestamp": "2026-04-16T12:00:00Z",
        "changelog": "Initial creation by agent",
        "content_hash": "a1b2c3..."
      },
      {
        "version": "0.1.2",
        "timestamp": "2026-04-16T14:30:00Z",
        "changelog": "Added encoding detection step",
        "content_hash": "d4e5f6..."
      }
    ],
    "use_count": 12,
    "evolution_count": 3
  }
}

响应 404 Not Found：

{
  "error": "Skill 'nonexistent' not found"
}

GET /api/marketplace/search

在 FangHub 市场搜索社区技能。

查询参数：

• q（必填）：搜索查询字符串
• page（可选）：页码（默认：1）

响应 200 OK：

{
  "results": [
    {
      "name": "weather-api",
      "author": "community",
      "description": "Real-time weather data integration",
      "downloads": 1250,
      "version": "2.1.0"
    }
  ],
  "total": 1,
  "page": 1
}

ClawHub 端点

浏览和安装 ClawHub（OpenClaw 生态系统兼容）上的技能。所有安装都会经过完整的安全流水线：SHA256 验证、SKILL.md 安全扫描和信任边界执行。

GET /api/clawhub/search

在 ClawHub 搜索兼容的技能。

查询参数：

• q（必填）：搜索查询

GET /api/clawhub/browse

浏览 ClawHub 分类。

查询参数：

• category（可选）：按分类过滤
• page（可选）：页码（默认：1）

GET /api/clawhub/skill/{slug}

获取指定 ClawHub 技能的详细信息。

GET /api/clawhub/skill/{slug}/code

获取 ClawHub 技能的原始源代码。

POST /api/clawhub/install

从 ClawHub 安装技能。下载后验证 SHA256 校验和，扫描提示注入，并自动将 SKILL.md 格式转换为 LibreFang 的 skill.toml。

请求体：

{
  "slug": "data-pipeline"
}

响应 201 Created：

{
  "status": "installed",
  "skill": "data-pipeline",
  "version": "1.2.0",
  "converted_from": "SKILL.md"
}

Hands 端点

Hands 是由内核管理的持久化自动化进程（浏览器自动化、RPA、长期运行的 Bot）。

GET /api/hands

列出所有已安装的 Hand 定义。

POST /api/hands/install

从清单或注册表 slug 安装 Hand。

GET /api/hands/active

列出当前活跃（运行中）的 Hand 实例。

GET /api/hands/{hand_id}

获取指定 Hand 定义的详细信息。

POST /api/hands/{hand_id}/activate

激活 Hand，创建新的运行实例。

POST /api/hands/{hand_id}/check-deps

检查 Hand 所需的所有依赖项是否已安装。

POST /api/hands/{hand_id}/install-deps

安装 Hand 缺失的依赖项。

GET /api/hands/{hand_id}/settings

获取 Hand 的当前设置。

PUT /api/hands/{hand_id}/settings

更新 Hand 的设置。

POST /api/hands/instances/{id}/pause

暂停运行中的 Hand 实例。

POST /api/hands/instances/{id}/resume

恢复已暂停的 Hand 实例。

DELETE /api/hands/instances/{id}

停用并移除 Hand 实例。

GET /api/hands/instances/{id}/stats

获取 Hand 实例的运行时统计信息（运行时长、已处理事件数、错误数）。

GET /api/hands/instances/{id}/browser

获取浏览器自动化 Hand 实例的当前浏览器状态。

扩展端点

扩展可为守护进程本身添加新能力（自定义工具、路由、集成等），无需修改核心代码。

GET /api/extensions

列出所有已安装的扩展。

GET /api/extensions/{name}

获取指定扩展的信息。

POST /api/extensions/install

从路径或注册表安装扩展。

POST /api/extensions/uninstall

按名称卸载扩展。

插件端点

上下文引擎插件扩展上下文组装流水线（RAG、预处理、文档加载器等）。

GET /api/plugins/registries

列出已配置的插件注册表（本地和远程）。

GET /api/plugins

列出所有已安装的插件。

GET /api/plugins/{name}

获取指定插件的信息。

POST /api/plugins/install

从注册表或本地路径安装插件。

POST /api/plugins/uninstall

按名称卸载插件。

POST /api/plugins/scaffold

从模板脚手架创建新的插件项目。Body：{"name": "...", "description": "...", "runtime": "python" | "native" | "v" | "node" | "deno" | "go" | "ruby" | "bash" | "bun" | "php" | "lua"}。按选定语言生成对应的 hook 脚手架。

GET /api/plugins/doctor

扫描主机上所有支持的 runtime，检测每个 runtime 的 launcher 是否在 PATH 上，并和已安装的插件做交叉比对。响应包含每个 runtime 检测到的版本号 + 缺失时的安装提示，并会标出哪些插件的声明 runtime 不可用。插件静默不工作时用这个端点排查。

POST /api/plugins/{name}/install-deps

安装插件的运行时依赖项（例如 Python 包、Node 模块）。

媒体生成端点

跨提供商的媒体生成 -- 图像、文本转语音、视频和音乐。LibreFang 自动检测每种能力对应的首个已配置提供商，也可通过 provider 字段显式指定。

支持的提供商：OpenAI（图像、TTS）、MiniMax（图像、TTS、视频、音乐）。

POST /api/media/image

根据文本提示生成一张或多张图像。

请求体：

{
  "prompt": "A futuristic city skyline at sunset",
  "provider": "openai",
  "model": "gpt-image-1",
  "width": 1024,
  "height": 1024,
  "count": 1
}

除 prompt 外所有字段可选。省略 provider 时自动选择首个支持图像生成的已配置提供商。

响应 200 OK：

{
  "images": [
    { "url": "/api/uploads/550e8400-..." }
  ],
  "model": "gpt-image-1",
  "provider": "openai",
  "revised_prompt": "A detailed futuristic city..."
}

POST /api/media/speech

文本转语音（TTS）。

请求体：

{
  "text": "Hello, welcome to LibreFang.",
  "voice": "alloy",
  "format": "mp3",
  "speed": 1.0
}

除 text 外所有字段可选。

响应 200 OK：

{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "provider": "openai",
  "model": "tts-1",
  "duration_ms": 2400,
  "sample_rate": 24000
}

POST /api/media/video

提交异步视频生成任务。返回用于轮询的 task ID。

请求体：

{
  "prompt": "A cat playing piano in a jazz bar",
  "provider": "minimax",
  "duration_secs": 5
}

除 prompt 外所有字段可选。

响应 202 Accepted：

{
  "task_id": "task-abc123",
  "provider": "minimax"
}

GET /api/media/video/{task_id}?provider=minimax

轮询视频生成任务状态。provider 查询参数必填。

响应 200 OK（处理中）：

{
  "status": "processing",
  "task_id": "task-abc123"
}

响应 200 OK（已完成）：

{
  "status": "completed",
  "result": {
    "file_url": "https://cdn.example.com/video.mp4",
    "width": 1280,
    "height": 720,
    "duration_secs": 5.0,
    "provider": "minimax",
    "model": "T2V-01"
  }
}

POST /api/media/music

根据文本提示和/或歌词生成音乐。

请求体：

{
  "prompt": "Upbeat electronic dance track",
  "lyrics": "",
  "instrumental": true,
  "format": "mp3"
}

prompt 和 lyrics 至少需提供一个。

响应 200 OK：

{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "duration_ms": 180000,
  "provider": "minimax",
  "model": "music-2.5",
  "sample_rate": 44100
}

GET /api/media/providers

列出可用的媒体提供商及其能力和配置状态。

响应 200 OK：

{
  "providers": [
    {
      "name": "openai",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech"]
    },
    {
      "name": "minimax",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech", "VideoGeneration", "MusicGeneration"]
    }
  ]
}