FlowyAIPC API 类型第三方能力文档标准

版本：1.0.0
状态：草案
适用对象：以 HTTP、gRPC、WebSocket 等 API 方式接入 FlowyAIPC 的第三方能力开发者
目标：确保 FlowyAIPC 开发者可以根据 API 文档直接编写 Skill、处理错误、执行验收测试，并完成隐私过滤与运行诊断。

1. 总体要求

API 类型第三方能力必须提供可集成、可测试、可诊断、可长期兼容的文档。

第三方可以选择随 API 服务一并提供 OpenClaw 兼容的 Skills。如果第三方未提供 Skills，FlowyAIPC 可根据本标准要求的 API 文档生成或半自动生成对应 Skills。该能力是否可用由目标平台 Profile 决定。因此，API 文档不仅面向人类开发者，也应能支撑人工编写或平台生成 Skill。

第三方不应只提供接口列表，还必须说明：

服务如何启动和检查。
如何鉴权。
接口如何调用。
错误如何分类。
长任务如何查询状态和取消。
返回字段的隐私级别。
FlowyAIPC 应如何处理异常、超时和未就绪状态。

推荐交付物：

交付物	要求
`api.md`	面向人阅读的 API 文档。
`openapi.yaml`	面向工具解析的 OpenAPI 规范，推荐必填。
`skills/`	可选。第三方自带的 OpenClaw 兼容 Skills。
`skill-template/`	可选。第三方自带的 Skill 模板或生成说明。
`examples/`	请求和响应样例。
`errors.md`	错误码与恢复建议。
`privacy.md`	返回字段的隐私级别说明。
`smoke-test.md`	冒烟测试步骤。

2. API 文档推荐结构

markdown

# <能力名称> API 文档

## 1. 基本信息

## 2. 认证方式

## 3. 服务启动与健康检查

## 4. Readiness 检查

## 5. 通用请求约定

## 6. 通用响应格式

## 7. 错误码规范

## 8. 接口列表

## 9. 异步任务约定

## 10. 超时与重试策略

## 11. 资源与权限说明

## 12. 隐私字段说明

## 13. 示例请求与响应

## 14. 冒烟测试

## 15. 版本兼容

## 16. Skill 交付或生成说明

3. Skill 交付或生成要求

API 类型能力有两种 Skill 接入方式。

方式	说明	要求
第三方自带 Skills	第三方随 API 服务一并提供 OpenClaw 兼容 Skills	必须包含 `SKILL.md`、触发说明、接口调用规则、认证、错误处理和隐私规则。
FlowyAIPC 生成 Skills	第三方不提供 Skills，由支持该能力的平台根据 API 文档生成或半自动生成	API 文档必须完整描述接口、参数、响应、错误码、异步任务、隐私字段和典型工作流。

3.1 自带 Skills 的建议结构

text

skills/
  <vendor>-shared/
    SKILL.md
  <vendor>-<domain>/
    SKILL.md
    references/
      <workflow>.md
      <endpoint>.md
skill-template/
  skill-template.md
  master-skill-template.md

其中：

shared Skill 用于认证、通用错误处理、权限说明和全局约束。
领域 Skill 用于描述某一业务域的核心场景、接口、Shortcut 和注意事项。
references/ 用于放置复杂工作流、长接口说明和高风险操作规则。
skill-template/ 可用于自动生成多个业务域的 Skill。

3.2 Skill 必须包含的内容

如果第三方自带 Skills，每个 Skill 至少应包含：

内容	说明
`name`	Skill 名称，建议使用 `<vendor>-<domain>`。
`description`	清晰说明适用场景和触发条件。
`metadata.openclaw.requires`	声明 endpoint、token、配置项、系统平台或二进制依赖。
`metadata.openclaw.install`	可选。声明依赖安装方式，FlowyAIPC 可据此提示、安装或准备环境；具体是否执行由平台 Profile 决定。
`metadata.openclaw.primaryEnv`	可选。声明主要密钥环境变量，便于 FlowyAIPC 绑定密钥配置。
认证说明	如何配置 token、如何处理认证失败。
接口调用规则	使用哪些 endpoint、参数如何填写、何时调用异步任务接口。
错误处理	常见错误码与恢复动作。
隐私规则	哪些响应字段不得进入 LLM 上下文。
工作流约束	高风险或多步骤操作的固定流程。

OpenClaw Skill metadata 示例：

markdown

---
name: vendor-media-search
description: "通过 Vendor Media Search API 搜索本地图片和视频。"
metadata:
  {
    "openclaw": {
      "os": ["win32"],
      "requires": {
        "env": ["VENDOR_API_TOKEN"],
        "config": ["vendorMediaSearch.endpoint"]
      },
      "primaryEnv": "VENDOR_API_TOKEN"
    }
  }
---

FlowyAIPC 可以从 metadata.openclaw.requires 中解析依赖信息，用于：

判断 Skill 是否可加载。
提示用户缺少哪些环境变量或配置项。
检查当前平台是否支持。
根据 install 元数据安装依赖或准备环境。
通过环境变量、配置文件、marker、registry 或其他平台约定方式提供 endpoint、token、模型服务地址等配置发现入口。

3.3 文档到 Skill 的生成要求

如果第三方不提供 Skills，FlowyAIPC 可根据 API 文档生成或半自动生成 Skills。为了保证人工编写或平台生成质量，API 文档必须满足：

接口按业务域分组。
每个接口有稳定路径、参数表、成功响应和失败响应。
响应字段标注隐私级别。
错误码可映射到用户提示和恢复动作。
长任务有任务创建、状态查询、取消和结果获取接口。
常用场景有推荐接口组合或 Shortcut。
高风险操作有明确前置确认要求。

4. 基本信息

API 文档必须说明：

字段	示例
服务名称	`HeliconSearch`
API 版本	`v1`
默认 Base URL	`http://127.0.0.1:5001`
默认端口	`5001`
协议	HTTP、HTTPS、gRPC、WebSocket
数据格式	JSON、`multipart/form-data`
是否本地服务	是 / 否
是否允许绑定公网	默认不允许
默认超时	例如 30 秒
模型运行模式	本地绑定模型 / 外部模型服务 / 混合模式

示例：

markdown

## 基本信息

- 服务名称：HeliconSearch
- API 版本：v1
- 默认地址：`http://127.0.0.1:5001`
- 默认绑定地址：`127.0.0.1`
- 数据格式：JSON；文件上传使用 `multipart/form-data`
- 默认超时：30 秒
- 长任务超时：由异步任务状态接口管理
- 模型运行模式：外部模型服务

5. 认证方式

API 文档必须明确认证方式。

项	要求
是否需要认证	必填。
认证类型	`none`、Bearer Token、API Key、OAuth。
Header 名称	例如 `Authorization: Bearer <token>`。
token 来源	用户配置、FlowyAIPC 自动生成或第三方生成。
token 是否可轮换	必须说明。
认证失败错误码	必须说明。

Bearer Token 示例：

markdown

## 认证方式

本服务使用 Bearer Token 认证。

请求 Header：

```http
Authorization: Bearer <token>

Token 由 FlowyAIPC 安装服务时自动生成，并写入服务配置文件。第三方服务不得将 token 输出到日志。


无认证示例：

```markdown
本服务默认无认证，仅允许绑定 `127.0.0.1`。如果服务绑定到 `0.0.0.0` 或远程地址，必须启用认证。

6. 模型运行模式

API 类型能力如果依赖模型推理，必须说明模型运行模式。

支持 3 种模式：

模式	说明	FlowyAIPC 处理方式
本地绑定模型	第三方服务自带或固定依赖某个本地模型	需要声明模型名称、格式、大小、下载方式和硬件要求。
外部模型服务	第三方服务通过外部 LLM、VLM、Embedding 或 Rerank 服务完成推理	需要声明 endpoint、认证方式、模型兼容协议和超时。
混合模式	支持本地模型和外部模型服务二选一或同时使用	需要声明优先级、fallback 行为和配置方式。

配置示例：

yaml

model:
  mode: external
  provider: openai-compatible
  endpoint_env: VENDOR_MODEL_BASE_URL
  api_key_env: VENDOR_MODEL_API_KEY
  default_model: qwen-vl
  timeout_seconds: 60

文档必须说明：

是否绑定固定模型。
是否允许用户配置外部模型服务。
外部模型服务是否兼容 OpenAI API、Ollama、vLLM、llama.cpp server 或其他协议。
需要哪些环境变量或配置项。
模型服务不可用时的错误码和恢复建议。
外部模型服务是否会接收用户原始数据，以及对应隐私边界。

7. 健康检查

每个 API 服务都必须提供健康检查。

项	要求
endpoint	必填。
是否需要认证	建议不需要认证。
返回格式	JSON。
成功状态码	`200`。
失败状态码	`503` 或明确错误码。
是否代表 ready	必须说明。

示例：

markdown

## 健康检查

### GET /health

用于判断服务进程是否存活。该接口不代表模型或索引已经就绪。

#### 响应示例

```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptime_seconds": 120
}


---

## 8. Readiness 检查

模型服务、索引服务、数据库服务必须提供 Readiness 检查。

健康检查表示服务活着，Readiness 表示服务可处理请求。

示例：

```markdown
## Readiness 检查

### GET /ready

用于判断服务是否可以处理请求。

#### 响应示例：已就绪

```json
{
  "ready": true,
  "components": {
    "model": "ready",
    "database": "ready",
    "index": "ready"
  }
}

响应示例：未就绪

json

{
  "ready": false,
  "components": {
    "model": "loading",
    "database": "ready",
    "index": "building"
  },
  "retry_after_seconds": 10
}


---

## 9. 通用请求约定

API 文档必须说明通用请求约定。

| 项 | 要求 |
|---|---|
| `Content-Type` | 必填。 |
| 字符编码 | `UTF-8`。 |
| 时间格式 | ISO 8601 或 Unix timestamp。 |
| 路径格式 | Windows 路径如何传递。 |
| 文件上传方式 | multipart、path 或 base64。 |
| 大文件限制 | 必填。 |
| 幂等性 | 哪些接口可重复调用。 |
| 请求 ID | 推荐支持 `X-Request-Id`。 |

建议约定：

```markdown
所有 JSON 请求使用 UTF-8 编码。

时间字段使用 ISO 8601 格式，例如：

```json
{
  "created_at": "2026-05-22T10:30:00+08:00"
}

Windows 文件路径必须使用普通字符串传递，服务端需要正确处理反斜杠、空格和中文路径。


---

## 10. 通用响应格式

建议 API 统一响应 envelope。

成功响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}

错误响应：

json

{
  "code": "not_ready",
  "message": "Model is still loading",
  "details": {
    "component": "vlm",
    "retry_after_seconds": 10
  },
  "request_id": "req_abc123"
}

标准字段：

字段	必填	说明
`code`	是	业务状态码，成功为 `0` 或 `success`。
`message`	是	人类可读信息。
`data`	成功时必填	成功结果。
`details`	失败时推荐	结构化错误详情。
`request_id`	推荐	便于日志追踪。

11. 错误码规范

API 文档必须定义稳定错误码。

建议统一错误类别：

错误码	含义	FlowyAIPC 处理方式
`not_installed`	依赖、模型或组件缺失	提示安装或修复。
`not_running`	服务未运行	提示启动服务。
`not_ready`	服务未就绪	等待或稍后重试。
`auth_failed`	认证失败	检查 token。
`permission_denied`	权限不足	提示授权。
`resource_unavailable`	GPU、内存、磁盘、端口不可用	提示资源不足。
`invalid_request`	请求参数错误	修正 Skill 调用。
`not_found`	资源不存在	向用户说明未找到。
`conflict`	状态冲突	提示当前已有任务。
`timeout`	操作超时	建议重试或取消。
`internal_error`	服务内部错误	展示诊断信息。

每个错误码必须说明：

项	要求
HTTP 状态码	必填。
业务错误码	必填。
是否可重试	必填。
用户可见提示	必填。
开发者排查建议	必填。

12. 单个接口文档模板

每个 API 接口都应按以下模板编写。

markdown

## 搜索媒体 / Search Media

### 基本信息

- 请求方式：POST
- 请求路径：`/api/v1/search`
- 鉴权方式：Bearer Token
- Content-Type：application/json
- 超时时间：30 秒
- 是否异步：否

### 功能说明

根据自然语言查询图片或视频内容。

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---:|---|---|
| query | string | 是 | - | 自然语言查询。 |
| kb_id | string | 否 | default | 知识库 ID。 |
| limit | integer | 否 | 10 | 返回数量，范围 1 到 50。 |
| mode | integer | 否 | 2 | 搜索模式：0 语义，1 视觉，2 混合。 |

### 请求示例

```json
{
  "query": "找一张海边日落的照片",
  "kb_id": "default",
  "limit": 5,
  "mode": 2
}

响应参数

参数	类型	隐私级别	说明
results	array	sensitive_metadata	搜索结果。
results[].id	string	safe_summary	本地结果 ID。
results[].display_name	string	sensitive_metadata	文件名。
results[].path	string	raw_private_data	本地绝对路径，默认不得进入 LLM 上下文。
results[].summary	string	sensitive_metadata	媒体内容摘要。
results[].score	number	safe_summary	相似度分数。

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "results": [
      {
        "id": "media_001",
        "display_name": "sunset.jpg",
        "path": "D:/Photos/2026/sunset.jpg",
        "summary": "海边日落场景",
        "score": 0.92
      }
    ]
  }
}

错误码

错误码	HTTP 状态码	是否可重试	说明
not_ready	503	是	索引尚未完成。
invalid_request	400	否	query 为空。
internal_error	500	是	服务内部错误。

FlowyAIPC 集成说明

path 字段不得直接进入 LLM 上下文。
summary 字段进入 LLM 前应做最小化摘要。
如果返回 not_ready，Skill 应提示用户稍后再试或等待索引完成。


---

## 13. 异步任务标准

如果 API 有上传、索引、录制、视频分析等长任务，必须使用异步任务模型。

推荐接口：

| 接口 | 说明 |
|---|---|
| `POST /api/v1/tasks` | 创建任务。 |
| `GET /api/v1/tasks/{task_id}` | 查询任务状态。 |
| `DELETE /api/v1/tasks/{task_id}` | 取消任务。 |
| `GET /api/v1/tasks/{task_id}/result` | 获取结果。 |

任务状态建议：

| 状态 | 含义 |
|---|---|
| `queued` | 已排队。 |
| `running` | 执行中。 |
| `paused` | 已暂停。 |
| `succeeded` | 成功。 |
| `failed` | 失败。 |
| `cancelled` | 已取消。 |

响应示例：

```json
{
  "task_id": "task_001",
  "state": "running",
  "progress": 0.42,
  "message": "Indexing media files",
  "started_at": "2026-05-22T10:30:00+08:00",
  "estimated_remaining_seconds": 120
}

14. 超时与重试策略

API 文档必须说明每类操作的超时和重试建议。

操作类型	默认超时	是否可重试	说明
健康检查	3 秒	是	可快速重试。
普通查询	30 秒	条件允许	避免重复产生副作用。
文件上传	依文件大小决定	条件允许	需说明是否支持断点续传。
长任务创建	30 秒	否或幂等	避免重复创建任务。
任务状态查询	5 秒	是	可轮询。

接口文档必须标明幂等性。非幂等接口不得被 FlowyAIPC 自动重试，除非提供幂等键。

15. 资源与权限说明

API 文档必须说明服务运行所需资源和权限。

项	示例
GPU	Intel Arc，最小显存 8 GB。
内存	最小 16 GB。
磁盘	最小剩余空间 20 GB。
端口	`5001`、`5003`、`6333`。
文件读取	用户选择的媒体目录。
文件写入	索引目录、缓存目录、日志目录。
网络	默认仅本地访问。

16. 隐私字段说明

API 响应字段必须标注隐私级别。

推荐隐私级别：

级别	含义
`safe_summary`	可以进入 LLM 上下文。
`sensitive_metadata`	需要过滤或用户授权。
`raw_private_data`	默认不得进入 LLM 上下文。
`secret`	永远不得进入 LLM 上下文或日志。

字段隐私标注示例：

字段	隐私级别	处理要求
`display_name`	`sensitive_metadata`	可展示给用户，进入 LLM 前需最小化。
`path`	`raw_private_data`	不得进入 LLM 上下文。
`thumbnail_base64`	`raw_private_data`	不得进入 LLM 上下文。
`auth_token`	`secret`	不得记录日志，不得返回给 Agent。

17. 冒烟测试

API 文档必须提供可执行冒烟测试步骤。

示例：

powershell

$base = "http://127.0.0.1:5001"
Invoke-RestMethod -Method GET -Uri "$base/health"
Invoke-RestMethod -Method GET -Uri "$base/ready"
Invoke-RestMethod -Method POST -Uri "$base/api/v1/search" -ContentType "application/json" -Body '{"query":"猫","limit":1}'

冒烟测试必须覆盖：

endpoint 可达。
健康检查通过。
Readiness 通过，若适用。
认证正常，若适用。
最小核心调用成功。
服务不可用时有明确错误。

18. 版本兼容

API 文档必须说明版本兼容策略。

yaml

api_version: v1
compatibility:
  flowyaipc_min_version: 0.8.0
  breaking_change_policy: semver
  deprecation_notice_days: 30

规则：

破坏性变更必须升级主版本。
API 路径应使用版本前缀，例如 /api/v1。
废弃字段或接口应至少提前 30 天声明。
响应字段新增应保持向后兼容。
字段删除、类型变更、语义变更都属于破坏性变更。

19. API 文档验收标准

API 文档合格标准：

检查项	必须
有 Base URL、端口、协议版本	是
有认证说明	是
有健康检查	是
有 Readiness 检查，若服务异步加载	是
每个接口都有请求和响应示例	是
每个接口都有错误码	是
有超时与重试说明	是
有模型运行模式说明，若依赖模型推理	是
有隐私字段标注	是
有异步任务状态约定，若存在长任务	是
有资源与权限说明	是
有冒烟测试步骤	是
有版本兼容说明	是
如未自带 Skills，文档可支撑人工编写或平台生成 Skills	是

如果达不到以上要求，不建议进入正式产品集成，只能进入临时联调或实验性接入。

FlowyAIPC API 类型第三方能力文档标准 ​

1. 总体要求 ​

2. API 文档推荐结构 ​

3. Skill 交付或生成要求 ​

3.1 自带 Skills 的建议结构 ​

3.2 Skill 必须包含的内容 ​

3.3 文档到 Skill 的生成要求 ​

4. 基本信息 ​

5. 认证方式 ​

6. 模型运行模式 ​

7. 健康检查 ​

响应示例：未就绪 ​

11. 错误码规范 ​

12. 单个接口文档模板 ​

响应参数 ​

响应示例 ​

错误码 ​

FlowyAIPC 集成说明 ​

14. 超时与重试策略 ​

15. 资源与权限说明 ​

16. 隐私字段说明 ​

17. 冒烟测试 ​

18. 版本兼容 ​

19. API 文档验收标准 ​

FlowyAIPC API 类型第三方能力文档标准

1. 总体要求

2. API 文档推荐结构

3. Skill 交付或生成要求

3.1 自带 Skills 的建议结构

3.2 Skill 必须包含的内容

3.3 文档到 Skill 的生成要求

4. 基本信息

5. 认证方式

6. 模型运行模式

7. 健康检查

响应示例：未就绪

11. 错误码规范

12. 单个接口文档模板

响应参数

响应示例

错误码

FlowyAIPC 集成说明

14. 超时与重试策略

15. 资源与权限说明

16. 隐私字段说明

17. 冒烟测试

18. 版本兼容

19. API 文档验收标准