飞虹 Code API 文档

版本：v8.0.1
基础 URL：http://localhost:8080
认证方式：Bearer Token（FH_WEB_TOKEN）
数据格式：JSON

认证方式

获取 Token

后端启动时自动生成 FH_WEB_TOKEN，输出在启动日志中：

[飞虹 Code] Web 控制台访问令牌 (FH_WEB_TOKEN): xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

也可通过环境变量设置：

$env:FH_WEB_TOKEN = "your-secret-token"
node dist/cli/index.js serve

使用 Token

所有受保护接口需在请求头中携带 Token：

Authorization: Bearer <FH_WEB_TOKEN>
Content-Type: application/json

cURL 示例

curl -X GET http://localhost:8080/api/tasks \
  -H "Authorization: Bearer <FH_WEB_TOKEN>"

公开接口

1. 健康检查

检查后端服务是否正常运行。

请求

GET /api/health

响应 200 OK

{
  "ok": true,
  "product": "飞虹 Code",
  "version": "8.11.0",
  "signature": "晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹",
  "enterprise": true,
  "lang": "zh",
  "wechat": "disabled",
  "feishu": "disabled",
  "yuanbao": "disabled",
  "time": "2026-09-03T03:22:41.905Z"
}

字段说明

字段	类型	说明
ok	boolean	服务是否正常
product	string	产品名称
version	string	当前版本号
signature	string	版权签名
enterprise	boolean	是否企业版
lang	string	语言
wechat	string	微信桥接状态（disabled/enabled）
feishu	string	飞书桥接状态
yuanbao	string	元宝桥接状态
time	string	服务器时间（ISO 8601）

示例

curl http://localhost:8080/api/health

受保护接口

以下接口均需携带 Authorization: Bearer <FH_WEB_TOKEN> 请求头。

2. 版本信息

获取详细的版本和构建信息。

请求

GET /api/version

响应 200 OK

{
  "version": "8.11.0",
  "buildTime": "2026-09-03T10:00:00.000Z",
  "commit": "abc1234",
  "nodeVersion": "v22.23.2",
  "platform": "win32"
}

错误响应 401 Unauthorized

{
  "error": "Unauthorized",
  "code": 401
}

3. 系统状态

获取当前系统运行状态。

请求

GET /api/status

响应 200 OK

{
  "status": "running",
  "uptime": 3600,
  "memory": {
    "rss": 238026752,
    "heapTotal": 104857600,
    "heapUsed": 62914560
  },
  "cpu": {
    "usage": 5.2,
    "cores": 8
  },
  "activeTasks": 3,
  "queuedTasks": 0
}

4. 配置管理

获取或更新系统配置。

获取配置

GET /api/config

更新配置

POST /api/config
Content-Type: application/json

{
  "model": "agnes-2.5-flash",
  "apiBase": "https://api.agnes-ai.cn/v1",
  "temperature": 0.7,
  "maxTokens": 4096
}

响应 200 OK

{
  "success": true,
  "config": { ... }
}

5. 功能特性

获取可用功能特性列表。

请求

GET /api/features

响应 200 OK

{
  "features": [
    { "id": "chat", "name": "AI 对话", "enabled": true },
    { "id": "games", "name": "游戏中心", "enabled": true },
    { "id": "creative", "name": "AI 创作", "enabled": true },
    { "id": "hermes", "name": "Hermes Agent", "enabled": true },
    { "id": "keyless", "name": "免密网络层", "enabled": true },
    { "id": "wechat", "name": "微信桥接", "enabled": false },
    { "id": "feishu", "name": "飞书桥接", "enabled": false }
  ]
}

6. 模型管理

获取可用模型列表。

请求

GET /api/models

响应 200 OK

{
  "models": [
    {
      "id": "agnes-2.5-flash",
      "name": "Agnes 2.5 Flash",
      "provider": "agnes",
      "apiBase": "https://api.agnes-ai.cn/v1",
      "contextWindow": 128000,
      "maxOutput": 8192,
      "supportsStreaming": true,
      "supportsVision": false
    }
  ],
  "defaultModel": "agnes-2.5-flash"
}

添加模型

POST /api/models
Content-Type: application/json

{
  "id": "custom-model",
  "name": "自定义模型",
  "provider": "openai-compatible",
  "apiBase": "https://api.example.com/v1",
  "apiKey": "sk-xxx",
  "contextWindow": 32000
}

7. 模型提供商

获取配置的模型提供商列表。

请求

GET /api/providers

响应 200 OK

{
  "providers": [
    {
      "id": "agnes",
      "name": "Agnes AI",
      "apiBase": "https://api.agnes-ai.cn/v1",
      "models": ["agnes-2.5-flash"],
      "status": "connected"
    },
    {
      "id": "siliconflow",
      "name": "硅基流动",
      "apiBase": "https://api.siliconflow.cn/v1",
      "models": ["deepseek-ai/DeepSeek-OCR"],
      "status": "connected"
    }
  ]
}

8. Agent 管理

管理 AI Agent 实例。

获取 Agent 列表

GET /api/agents

响应 200 OK

{
  "agents": [
    {
      "id": "agent-001",
      "name": "代码助手",
      "type": "solo",
      "status": "idle",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "lastActive": "2026-09-03T08:00:00.000Z"
    }
  ],
  "total": 5
}

创建 Agent

POST /api/agents
Content-Type: application/json

{
  "name": "新 Agent",
  "type": "solo",
  "systemPrompt": "你是一个专业的代码助手",
  "model": "agnes-2.5-flash"
}

获取单个 Agent

GET /api/agents/:id

删除 Agent

DELETE /api/agents/:id

9. 技能管理

管理可复用技能。

获取技能列表

GET /api/skills

响应 200 OK

{
  "skills": [
    {
      "id": "skill-summarize",
      "name": "内容摘要",
      "description": "对长文本进行结构化摘要",
      "trigger": "摘要|总结|概括",
      "tags": ["文本处理", "效率"],
      "useCount": 12,
      "builtin": true,
      "createdAt": "2026-09-01T00:00:00.000Z"
    }
  ],
  "total": 4
}

安装技能

POST /api/skills
Content-Type: application/json

{
  "name": "新技能",
  "description": "技能描述",
  "trigger": "触发词",
  "prompt": "提示词模板，{{content}}表示用户输入",
  "tags": ["自定义"]
}

删除技能

DELETE /api/skills/:id

10. 工具列表

获取可用工具列表。

请求

GET /api/tools

响应 200 OK

{
  "tools": [
    { "name": "web_search", "description": "网页搜索", "enabled": true },
    { "name": "file_read", "description": "文件读取", "enabled": true },
    { "name": "shell_exec", "description": "Shell 执行", "enabled": true },
    { "name": "browser", "description": "浏览器自动化", "enabled": true },
    { "name": "tts", "description": "文字转语音", "enabled": true }
  ],
  "total": 8
}

11. 任务队列

管理异步任务队列。

获取任务列表

GET /api/tasks?status=pending&limit=20&offset=0

查询参数

参数	类型	说明
status	string	筛选状态（pending/running/completed/failed）
limit	number	每页数量（默认20）
offset	number	偏移量（默认0）

响应 200 OK

{
  "tasks": [
    {
      "id": "task-001",
      "type": "chat",
      "status": "completed",
      "progress": 100,
      "createdAt": "2026-09-03T10:00:00.000Z",
      "completedAt": "2026-09-03T10:00:05.000Z",
      "result": { "summary": "任务完成" }
    }
  ],
  "total": 98,
  "pending": 0,
  "running": 0
}

创建任务

POST /api/tasks
Content-Type: application/json

{
  "type": "chat",
  "input": "你好",
  "model": "agnes-2.5-flash"
}

获取任务状态

GET /api/tasks/:id

取消任务

POST /api/tasks/:id/cancel

删除任务

DELETE /api/tasks/:id

12. 知识库

管理知识库文档。

获取文档列表

GET /api/knowledge

响应 200 OK

{
  "documents": [
    {
      "id": "doc-001",
      "title": "飞虹 Code 使用指南",
      "type": "markdown",
      "size": 10240,
      "tags": ["指南", "使用"],
      "createdAt": "2026-09-01T00:00:00.000Z"
    }
  ],
  "total": 14
}

上传文档

POST /api/knowledge
Content-Type: multipart/form-data

file: <文件>
title: 文档标题
tags: ["标签1","标签2"]

搜索知识库

GET /api/knowledge/search?q=关键词

删除文档

DELETE /api/knowledge/:id

13. 插件管理

管理系统插件。

获取插件列表

GET /api/plugins

响应 200 OK

{
  "plugins": [
    {
      "id": "plugin-001",
      "name": "示例插件",
      "version": "1.0.0",
      "description": "插件描述",
      "enabled": true,
      "installedAt": "2026-09-01T00:00:00.000Z"
    }
  ],
  "total": 0
}

启用/禁用插件

POST /api/plugins/:id/toggle

卸载插件

DELETE /api/plugins/:id

14. 自动化任务（Routines）

管理云端 7x24 定时任务。任务分 goal（交AI 智能体真实执行）与 command（shell 命令）两类， 每次执行都会过三级规则引擎门控：硬红线（改密码 / 转账 / 永久删除 / 外发）恒拦截不可放行；命中 ask 时提交审批收件箱挂起，人工放行后才执行。

fhcode serve 启动时调度器常驻（每 60s 检查一次 cron），接口与 CLI 共享同一进程单例。

获取任务列表

GET /api/routines

响应 200 OK

{
  "ok": true,
  "routines": [
    {
      "id": "rt_1759000000000_a3f1",
      "name": "每日代码巡检",
      "trigger": { "kind": "cron", "expr": "0 9 * * *" },
      "action": { "type": "goal", "goal": "巡检 src 目录并输出报告", "tier": "save" },
      "enabled": true,
      "maxRetries": 2,
      "state": { "status": "idle", "lastRunAt": null, "nextRunAt": "2026-10-05T01:00:00.000Z" }
    }
  ]
}

创建任务

POST /api/routines

请求体

{
  "name": "每日代码巡检",
  "cron": "0 9 * * *",
  "goal": "巡检 src 目录并输出报告",
  "tier": "save",
  "enabled": true
}

cron 必填（五字段）；goal 与 command 二选一，优先取 command
tier 可选（light / save / full），缺省按目标复杂度自动分档

响应 201 Created；缺少 cron 或任务内容时 400

{ "ok": false, "error": "缺少 cron 与任务内容（goal 或 command）" }

手动触发一次

POST /api/routines/:id/run

响应 200 OK（任务不存在 404，已停用 409）

{
  "ok": true,
  "result": {
    "ok": true,
    "output": "巡检完成：发现 0 个问题"
  }
}

启用/停用

POST /api/routines/:id/enable

请求体 { "enabled": false } — 省略或 true 即启用。

删除任务

DELETE /api/routines/:id

查询审批收件箱待决项

GET /api/routines/approvals

响应 200 OK（落盘前已脱敏）

{
  "ok": true,
  "approvals": [
    {
      "id": "ap_1759000000000",
      "label": "routine(rt_1759000000000_a3f1/cron) 命中默认 ask，已挂起待审批",
      "status": "pending",
      "createdAt": "2026-10-04T10:00:00.000Z"
    }
  ]
}

审批裁决

POST /api/approvals/:id/decide

请求体（approve 省略或 false 即拒绝）

{ "approve": true, "by": "张三" }

响应 200 OK（收件箱未初始化 503，裁决失败 400）

{ "ok": true, "item": { "id": "ap_1759000000000", "status": "approved", "decidedBy": "张三" } }

裁决仅解除挂起：被挂起的自动化任务需重新 POST /api/routines/:id/run 或等下一个 cron 窗口才会真正执行。与 CLI fhcode approvals approve 同源。

记忆与业务画像

只读接口，供控制台「记忆系统」页与「📊 业务画像」区块使用。与 CLI fhcode memory profile|stats 同源（同一份聚合逻辑）。

业务画像聚合

GET /api/memory/profile

响应 200 OK

{
  "ok": true,
  "profile": {
    "totalTasks": 100,
    "firstAt": "2026-10-04T14:08:12.859Z",
    "lastAt": "2026-10-04T15:35:09.084Z",
    "topDomains": [{ "tag": "任务", "count": 23 }],
    "keyDecisions": [],
    "artifacts": [],
    "userPreferences": [],
    "recentGoals": ["边界测试", "批量任务5"]
  }
}

字段	说明
`totalTasks`	项目记忆累计条目数
`firstAt` / `lastAt`	首末条目时间戳，`null` 表示记忆为空
`topDomains`	高频标签倒序（按出现次数）
`keyDecisions` / `artifacts` / `userPreferences`	从条目中提取的决策 / 产物 / 偏好
`recentGoals`	最近目标（倒序）

分层记忆统计

GET /api/memory/stats

响应 200 OK

{ "ok": true, "shortTermFiles": 1, "longTermNotes": 1, "lastSummarize": null }

记忆条目列表

GET /api/memory/entries?limit=20

参数	类型	默认	说明
`limit`	number	20	返回条数，自动夹在 1~500，防一次拉爆

响应 200 OK（按 timestamp 倒序）

{
  "ok": true,
  "total": 100,
  "entries": [
    {
      "id": "1791128109084-j2mup6",
      "goal": "边界测试",
      "decisions": [], "artifacts": [], "pendingIssues": [], "userPreferences": [],
      "timestamp": "2026-10-04T15:35:09.084Z",
      "tags": ["边界测试"]
    }
  ]
}

三个端点均为 GET 只读，无需 x-fh-ts/x-fh-nonce/x-fh-sig 签名头，但需 Authorization: Bearer <FH_WEB_TOKEN>（缺失返回 401）。

错误响应

错误格式

所有错误响应遵循统一格式：

{
  "error": "错误描述",
  "code": 400,
  "details": {}
}

常见错误码

状态码	说明	原因
400	Bad Request	请求参数错误
401	Unauthorized	未携带或 Token 无效
403	Forbidden	无权限访问
404	Not Found	资源不存在
409	Conflict	资源冲突
429	Too Many Requests	请求频率超限
500	Internal Server Error	服务器内部错误
503	Service Unavailable	服务暂不可用

认证错误示例

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": 401
}

数据模型

Health

interface Health {
  ok: boolean;
  product: string;
  version: string;
  signature: string;
  enterprise: boolean;
  lang: string;
  wechat: 'disabled' | 'enabled';
  feishu: 'disabled' | 'enabled';
  yuanbao: 'disabled' | 'enabled';
  time: string; // ISO 8601
}

Model

interface Model {
  id: string;
  name: string;
  provider: string;
  apiBase: string;
  contextWindow: number;
  maxOutput: number;
  supportsStreaming: boolean;
  supportsVision: boolean;
}

Skill

interface Skill {
  id: string;
  name: string;
  description: string;
  trigger: string; // | 分隔多个触发词
  prompt: string;  // 支持 {{content}} {{变量}}
  tools: string[];
  tags: string[];
  version: string;
  useCount: number;
  builtin?: boolean;
  autoExtracted?: boolean;
  llmExtracted?: boolean;
  createdAt: string;
  improvedAt?: string;
}

Task

interface Task {
  id: string;
  type: string;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
  progress: number; // 0-100
  input: any;
  result?: any;
  error?: string;
  createdAt: string;
  startedAt?: string;
  completedAt?: string;
}

Agent

interface Agent {
  id: string;
  name: string;
  type: 'solo' | 'orchestrator' | 'team';
  status: 'idle' | 'running' | 'error';
  systemPrompt?: string;
  model?: string;
  createdAt: string;
  lastActive?: string;
}

示例代码

Node.js 示例

const BASE_URL = 'http://localhost:8080';
const TOKEN = 'your-fh-web-token';

async function api(path, options = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${TOKEN}`,
      ...options.headers
    }
  });
  if (!res.ok) throw new Error(`API Error: ${res.status}`);
  return res.json();
}

// 健康检查（无需认证）
const health = await fetch(`${BASE_URL}/api/health`).then(r => r.json());
console.log('版本:', health.version);

// 获取任务列表（需认证）
const tasks = await api('/api/tasks?status=completed&limit=10');
console.log('任务数:', tasks.total);

// 创建任务
const newTask = await api('/api/tasks', {
  method: 'POST',
  body: JSON.stringify({ type: 'chat', input: '你好' })
});
console.log('任务ID:', newTask.id);

Python 示例

import requests

BASE_URL = 'http://localhost:8080'
TOKEN = 'your-fh-web-token'
HEADERS = {'Authorization': f'Bearer {TOKEN}'}

# 健康检查
health = requests.get(f'{BASE_URL}/api/health').json()
print(f"版本: {health['version']}")

# 获取模型列表
models = requests.get(f'{BASE_URL}/api/models', headers=HEADERS).json()
print(f"模型数: {len(models['models'])}")

# 创建技能
skill = requests.post(
    f'{BASE_URL}/api/skills',
    headers=HEADERS,
    json={
        'name': '代码优化',
        'description': '优化代码性能和可读性',
        'trigger': '优化代码|代码优化|性能优化',
        'prompt': '请优化以下代码，提升性能和可读性：\n\n{{content}}'
    }
).json()
print(f"技能ID: {skill.get('id')}")

cURL 示例

# 健康检查
curl http://localhost:8080/api/health

# 获取任务列表
curl -X GET http://localhost:8080/api/tasks \
  -H "Authorization: Bearer <TOKEN>"

# 创建任务
curl -X POST http://localhost:8080/api/tasks \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"type":"chat","input":"你好"}'

# 安装技能
curl -X POST http://localhost:8080/api/skills \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"新技能","description":"描述","trigger":"触发词","prompt":"模板"}'

速率限制

接口类型	限制
公开接口（/api/health）	无限制
受保护接口	100 次/分钟
文件上传	10 次/分钟，单文件最大 50MB

超出限制返回 429 Too Many Requests。

变更日志

版本	日期	变更
v7.9.1	2026-09-03	新增 favicon/robots、LLM 辅助技能提炼、集成测试框架
v7.9.0	2026-09-03	Hermes Agent 完整框架（持久记忆+自演化技能+自动化调度+工具集）
v7.8.0	2026-09-02	免密网络层（Keyless Web Tier）+ Hermes 记忆基础
v7.6.0	2026-08-30	基础版本，20个子系统

本文档随版本更新而维护，最新版本以项目仓库 docs/ 目录为准。

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

飞虹 Code API 文档

目录

认证方式

获取 Token

使用 Token

cURL 示例

公开接口

1. 健康检查

受保护接口

2. 版本信息

3. 系统状态

4. 配置管理

5. 功能特性

6. 模型管理

7. 模型提供商

8. Agent 管理

9. 技能管理

10. 工具列表

11. 任务队列

12. 知识库

13. 插件管理

14. 自动化任务（Routines）

记忆与业务画像

业务画像聚合

分层记忆统计

记忆条目列表

错误响应

错误格式

常见错误码

认证错误示例

数据模型

Health

Model

Skill

Task

Agent

示例代码

Node.js 示例

Python 示例

cURL 示例

速率限制

变更日志