FlowyAIPC 第三方智能能力接入标准
版本：1.0.0
状态：草案
适用对象：第三方能力开发者、FlowyAIPC 集成开发者、产品、测试、交付与安全评审同学
目标：定义第三方智能能力接入 FlowyAIPC 的分类标准、交付契约、运行治理、资源调度、权限、隐私、认证、错误处理、版本兼容和验收要求。
1. 目的
本文档定义第三方智能能力接入 FlowyAIPC 的完整标准。
第三方能力可以是会话型 Agent、API 服务、CLI 工具、MCP Server 或本地托管服务。并非所有能力都应被称为 Agent。
本标准用于解决以下问题：
- 第三方能力应走 ACP、Skill、MCP、CLI 还是 Sub-agent。
- 第三方开发者必须交付哪些文档、接口、配置和测试材料。
- FlowyAIPC 如何安装、启动、停止、调用、鉴权、限制和展示第三方能力。
- 第三方能力如何声明资源、权限和隐私边界。
- 如何处理 GPU、端口、磁盘和后台任务带来的产品化风险。
- 如何定义版本兼容、错误码、日志和验收标准。
本标准遵循以下原则：
- 按能力本质分类，而不是按营销名称分类。
- 会话型智能体走 ACP，工具型服务走 Skill 或 MCP。
- 第三方可以自带 OpenClaw 兼容 Skills；如果未提供，FlowyAIPC 将依据 API 或 CLI 文档生成 Skills。
- 资源、权限、隐私和生命周期必须显式声明。
- 原始用户数据默认不得进入云端 LLM 上下文。
- 正式集成必须可诊断、可停止、可升级、可卸载。
2. 术语定义
2.1 Capability（能力）
FlowyAIPC 可调用或编排的第三方功能。能力可以是 Agent、工具服务、CLI、MCP Server 或托管本地服务。
2.2 Agent（智能体）
具备会话、推理、上下文管理或任务执行能力的运行时。Agent 可以持续处理用户输入，维护会话状态，并执行多步任务。
2.3 Tool（工具）
执行有界操作并返回结构化结果的服务或函数。Tool 不拥有用户会话，也不负责长期推理流程。
2.4 Skill
OpenClaw 兼容的指令包，用于告诉 Agent 如何调用第三方 API、CLI、MCP Server 或工作流。
2.5 ACP Agent
通过 Agent Client Protocol（ACP）与 FlowyAIPC 通信的外部 Agent 运行时。
2.6 API Skill
通过 Skill 包装 HTTP、gRPC 或 WebSocket API 的接入方式。
2.7 CLI Skill
通过 Skill 包装命令行程序的接入方式。
2.8 MCP Tool
通过 MCP Server 暴露的标准工具能力。
2.9 Managed Service（托管服务）
由 FlowyAIPC 安装、配置、启动、停止、监控、升级和清理的本地服务。
2.10 Manifest（接入声明）
机器可读的接入声明。本文中的 Manifest 是能力接入总标准概念；安装包交付场景中的具体文件为包根目录下的 manifest.yaml，schema 见 manifest-spec/index.md。
2.11 Readiness（就绪状态）
服务进程已经启动，不代表能力已经可用。模型加载、索引构建、数据库连接完成后，才视为 ready。
3. 接入类型决策树
FlowyAIPC 按能力本质分类第三方能力，而不是按第三方自称的名称分类。
text
该能力是否提供多轮会话或任务执行运行时？
是 → 是否支持 ACP？
是 → ACP Agent
否 → 建议优先补 ACP；临时阶段可用 API Skill 或 CLI Skill 包装
否 → 是否提供 MCP Server？
是 → MCP Tool
→ 是否提供稳定 HTTP、gRPC 或 WebSocket API？
是 → API Skill
→ 是否提供稳定、非交互式 CLI？
是 → CLI Skill
→ 否则暂不接入，直到提供稳定协议分类规则：
- 只有具备会话状态、推理流程或任务执行能力的对象，才应称为 Agent。
- 搜索、上传、录屏、索引、OCR、媒体处理等有界能力，应作为 Tool 接入。
- MCP Server 优先于重复包装 API 或 CLI。
- 如果第三方能力需要长期运行但不拥有会话，它是 Managed Service，不是 Agent。
- FlowyAIPC 原生 Sub-agent 主要用于内部任务拆分，不是第三方服务的默认接入方式。
4. 支持的接入类型
4.1 ACP Agent
适用于真正的 Agent 运行时。
典型场景：
- 编码 Agent。
- 研究 Agent。
- 桌面自动化 Agent。
- 多轮任务执行 Agent。
- 支持会话恢复的外部 harness。
第三方必须交付：
| 交付物 | 说明 |
|---|---|
| ACP 兼容可执行文件 | 启动 ACP session 的入口。 |
| 启动命令 | 完整命令、参数和环境变量。 |
| 运行环境说明 | OS、模型、推理框架、必需依赖。 |
| 认证配置 | API Key、OAuth、设备登录或本地登录。 |
| 模型配置说明 | 支持模型、默认模型、模型切换方式。 |
| 权限模式说明 | 审批策略、文件权限、命令执行权限。 |
| 工作目录行为 | 默认 cwd、是否可指定 cwd、访问边界。 |
| 会话恢复说明 | 是否支持恢复，恢复标识如何管理。 |
| 健康检查或诊断命令 | 等价于 doctor 的能力。 |
| 版本兼容声明 | ACP 版本、FlowyAIPC 最低版本。 |
4.2 API Skill
适用于暴露本地或远程 API 的工具服务。
典型场景：
- 图片或视频搜索服务。
- OCR 服务。
- 本地模型推理服务。
- 知识库服务。
- 屏幕录制服务。
- 视频处理服务。
第三方必须交付：
| 交付物 | 说明 |
|---|---|
| API 文档 | 接口列表、请求参数、响应字段。 |
| OpenAPI 规范 | 强烈建议提供。 |
| Base URL 与端口 | 本地服务默认绑定 127.0.0.1。 |
| 认证方式 | 无认证、Bearer Token、API Key 等。 |
| 健康检查 endpoint | 必填。 |
| Readiness 检查 | 模型加载、索引构建等异步场景必填。 |
| 错误码规范 | 稳定错误分类与处理建议。 |
| 超时说明 | 各类操作的预期耗时。 |
| 异步任务接口 | 状态查询、取消、进度。 |
| 示例请求与响应 | 每个核心接口至少 1 个示例。 |
| 资源与隐私声明 | GPU、内存、磁盘、端口、数据边界。 |
4.3 CLI Skill
适用于通过命令行操作的第三方能力。
第三方开发者可以参考 Lark CLI 的设计方式来组织 CLI 和 Skills：稳定命令、结构化输出、领域化命令分组、shared Skill、领域 Skill、references/ 工作流文档和 skill-template/。参考项目：https://github.com/larksuite/cli。
第三方必须交付：
| 交付物 | 说明 |
|---|---|
| CLI 可执行文件 | 单文件或安装包。 |
| 非交互使用文档 | 子命令、参数、配置文件。 |
稳定 --help 输出 | 参数变更需要版本声明。 |
| JSON 输出模式 | 强烈建议必填。 |
| 退出码规范 | 成功、输入错误、认证失败、超时、内部错误。 |
| stdout/stderr 约定 | stdout 输出结构化结果，stderr 输出日志或错误。 |
| 超时与取消行为 | 进程终止后是否会残留子进程。 |
| 日志位置 | 便于排障。 |
| Windows 兼容说明 | 路径、中文、空格、编码。 |
| Skills | 可选。若不提供，支持该能力的平台可根据 CLI 文档生成或半自动生成。 |
4.4 MCP Tool
适用于已经提供 MCP Server 的第三方工具集合。
第三方必须交付：
| 交付物 | 说明 |
|---|---|
| MCP Server 启动命令 | 命令、参数、环境变量。 |
| 工具 Schema | 工具名称、参数、返回格式。 |
| 认证设置 | API Key、token、OAuth 等。 |
| 权限说明 | 文件、网络、进程等访问边界。 |
| 示例工具调用 | 核心工具调用样例。 |
4.5 FlowyAIPC 原生 Sub-agent
适用于 FlowyAIPC 内部可控的专业子 Agent，不是第三方服务的默认接入路径。
原生 Sub-agent 由 FlowyAIPC 配置模型、工具、Skill allowlist、并发、超时和上下文模式。
4.6 第三方自带 Skills
API Skill 和 CLI Skill 都允许第三方直接提供 OpenClaw 兼容 Skills。
第三方自带 Skills 时，应至少包含：
| 内容 | 说明 |
|---|---|
SKILL.md | Skill 主说明文件。 |
description | 明确触发条件和能力边界。 |
metadata.openclaw.requires | CLI 二进制、环境变量、配置项、平台或 endpoint 依赖。 |
metadata.openclaw.install | 可选。依赖安装方式，FlowyAIPC 可据此提示、安装或准备环境；具体是否执行由平台 Profile 决定。 |
metadata.openclaw.primaryEnv | 可选。主要密钥环境变量。 |
| 调用规则 | 何时调用哪些命令或接口。 |
| 错误处理 | 常见错误与恢复动作。 |
| 隐私规则 | 哪些输出字段不得进入 LLM 上下文。 |
| 工作流文档 | 复杂或高风险操作应放入 references/。 |
如果第三方未提供 Skills，FlowyAIPC 可根据 api.spec.md 或 cli.spec.md 要求的文档自动或半自动生成 Skills。该能力不是所有平台 Profile 的必选能力，因此 API/CLI 文档必须足够结构化，能够支撑人工编写或平台生成 Skill。
OpenClaw Skill metadata 可以作为依赖和环境准备声明。FlowyAIPC 可从 metadata.openclaw.requires、metadata.openclaw.install、metadata.openclaw.primaryEnv 中解析：
- 需要哪些 CLI 二进制。
- 需要哪些环境变量。
- 需要哪些配置项。
- 支持哪些操作系统。
- 是否提供可安装依赖。
- 哪个环境变量对应主要密钥。
示例：
markdown
---
name: vendor-tool
description: "通过 vendor-tool CLI 调用第三方能力。"
metadata:
{
"openclaw": {
"os": ["win32"],
"requires": {
"bins": ["vendor-tool"],
"env": ["VENDOR_MODEL_BASE_URL"],
"config": ["vendorTool.outputDir"]
},
"primaryEnv": "VENDOR_API_KEY",
"install": [
{
"id": "download-win32",
"kind": "download",
"os": ["win32"],
"url": "https://example.com/vendor-tool.zip",
"archive": "zip",
"bins": ["vendor-tool"]
}
]
}
}
---5. 接入类型对照表
| 接入类型 | 协议 | 是否拥有会话 | 适合对象 | 不适合对象 |
|---|---|---|---|---|
| ACP Agent | ACP | 是 | 外部 Agent runtime、编码 Agent、任务执行 Agent | 简单 REST 服务。 |
| API Skill | HTTP、gRPC、WebSocket | 否 | 搜索、录屏、OCR、知识库、推理服务 | 需要多轮会话的 Agent。 |
| CLI Skill | CLI | 否 | 命令行工具、批处理工具 | 需要交互式会话的 CLI。 |
| MCP Tool | MCP | 否 | 标准工具集合 | 没有 MCP Server 的服务。 |
| Managed Service | 本地进程 | 否 | 后台服务、模型服务、数据库 | 真正的对话 Agent。 |
6. 必需交付物
每个第三方接入必须提供以下材料：
| 交付物 | 必须 | 说明 |
|---|---|---|
| 接入类型说明 | 是 | 按决策树说明选择理由。 |
| 机器可读接入声明 | 是 | 可由 manifest.yaml、平台接入配置或其他 Profile 约定的声明文件承载。安装包交付时使用 manifest.yaml。 |
| 协议文档 | 是 | ACP、API、CLI 或 MCP 文档。 |
| 启动说明 | 是 | 手动启动与托管启动方式。 |
| 健康检查 | 是 | 判断进程或服务是否存活。 |
| Readiness 检查 | 条件必填 | 模型加载、索引构建等异步服务必须提供。 |
| 认证说明 | 是 | token、API Key、OAuth 或无认证声明。 |
| 资源声明 | 是 | GPU、内存、磁盘、端口、模型大小。 |
| 权限声明 | 是 | 文件、屏幕、音频、网络、进程、GPU 等权限。 |
| 隐私声明 | 是 | 读取、生成、存储、返回哪些用户数据。 |
| 错误码文档 | 是 | 稳定错误分类与恢复建议。 |
| 日志和诊断说明 | 是 | 日志路径、诊断命令或诊断 API。 |
| 版本兼容声明 | 是 | 能力版本、协议版本、FlowyAIPC 最低版本。 |
| 测试说明 | 是 | 冒烟测试与验收测试。 |
7. 接入声明与 Manifest 安装包规范
每个接入必须提供机器可读接入声明。安装包交付场景使用 manifest.yaml，具体 schema 见 manifest-spec/index.md。
Manifest 是以下能力的基础：
- 安装与升级。
- 启动与停止。
- 健康检查与就绪检查。
- 资源调度。
- 权限展示。
- 隐私过滤。
- 错误诊断。
本文是能力接入总标准，覆盖安装、运行、调用、治理和验收。manifest-spec/ 是 zip + manifest.yaml 安装包格式规范。平台可以声明实现 Profile，例如 Electron v0.1：只安装、生成配置、注册 Skill 和维护 registry；不执行脚本，不写 openclaw.json，不启动第三方服务，不做 health / ready。
- 验收测试。
7.1 完整示例
yaml
id: highlight
name: Highlight
version: 1.0.0
type: api-skill
protocol:
kind: http
base_url: http://127.0.0.1:8088
api_version: v1
health_check:
method: GET
path: /health
readiness_check:
method: GET
path: /health
ready_field: ready
runtime:
mode: managed
os:
- win32
executable: highlight.exe
working_directory: "{install_dir}/highlight"
start_command:
- "{install_dir}/highlight/highlight.exe"
- --config
- "{config_dir}/highlight/config.json"
readiness_timeout_seconds: 60
stop:
kind: api
method: DELETE
path: /api/v1/sessions/{session_id}
resources:
scheduling_class: gpu-exclusive
gpu:
required: true
vendor: intel
min_vram_gb: 8
cpu_fallback: false
memory:
min_gb: 16
idle_gb: 4
disk:
min_free_gb: 20
growth_hint: "3.6 GB/hour"
ports:
- port: 8088
protocol: tcp
required: true
purpose: api
- port: 18080
protocol: tcp
required: true
purpose: internal_llm_server
model_files:
- name: gemma-3-4b-q4
size_gb: 3.0
format: gguf
- name: mmproj
size_gb: 0.5
format: gguf
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
permissions:
screen_capture: required
audio_capture: required
file_read:
- user_selected_source
file_write:
- "{app_data}/highlight/output"
- "{app_data}/highlight/logs"
network:
local_only: true
process_spawn: required
gpu_compute: required
privacy:
local_processing: true
reads:
- screen_content
- system_audio
stores:
- video_clips
- session_metadata
llm_allowed_fields:
- event_count
- event_timestamp
- short_summary
llm_blocked_fields:
- raw_frame
- screenshot
- full_video
- absolute_file_path
auth:
type: bearer_token
token_source: flowyaipc_generated
observability:
logs:
- "{app_data}/highlight/logs/highlight.log"
diagnostic_command:
- "{install_dir}/highlight/highlight.exe"
- doctor
compatibility:
flowyaipc_min_version: 0.8.0
protocol_version: api-v1
breaking_change_policy: semver
deprecation_notice_days: 307.2 字段要求
| 字段 | 必须 | 说明 |
|---|---|---|
id | 是 | 唯一标识，使用小写字母、数字和连字符。 |
name | 是 | 展示名称。 |
version | 是 | 第三方能力版本。 |
type | 是 | acp-agent、api-skill、cli-skill、mcp-tool 或 managed-service。 |
protocol | 是 | 协议类型、版本、健康检查。 |
runtime | 是 | 运行时模式、启动、停止和工作目录。 |
resources | 是 | 资源需求与调度等级。 |
model | 条件必填 | 如果依赖模型推理，声明本地模型、外部模型服务或混合模式。 |
permissions | 是 | 权限需求。 |
privacy | 是 | 数据边界与 LLM 可见字段。 |
auth | 条件必填 | 如果需要认证，则必须提供。 |
observability | 是 | 日志与诊断方式。 |
compatibility | 是 | 版本兼容声明。 |
8. 协议要求
8.1 ACP 要求
ACP 集成必须满足：
- 可通过确定命令启动。
- 支持非交互式启动。
- 明确认证配置方式。
- 明确模型配置方式。
- 明确工作目录行为。
- 明确会话生命周期。
- 支持取消，或明确声明不支持取消。
- 支持健康检查或诊断命令。
- 如果支持会话恢复，必须说明恢复标识、上下文边界和失败行为。
8.2 API 要求
API 集成必须满足：
- 本地服务默认绑定
127.0.0.1，不得默认绑定0.0.0.0。 - 提供健康检查 endpoint。
- 模型加载、索引构建等异步场景必须提供 readiness 信息。
- 使用版本化路径，如
/api/v1。 - 返回结构化 JSON 错误。
- 说明每类请求的超时预期。
- 说明操作是同步还是异步。
- 异步任务必须提供状态查询。
- 长任务建议提供取消接口。
- 每个核心接口必须提供请求与响应示例。
8.3 CLI 要求
CLI 集成必须满足：
- 支持非交互执行。
- 支持机器可读输出，推荐 JSON。
- stdout 用于结构化结果，stderr 用于日志或错误。
- 返回稳定退出码。
- FlowyAIPC 调用期间不得弹出交互提示。
- 支持显式配置文件路径。
- 支持通过进程终止或文档化命令取消。
- Windows 下必须正确处理中文路径、空格和编码。
8.4 MCP 要求
MCP 集成必须满足：
- 提供 MCP Server 启动命令。
- 提供工具 Schema。
- 明确每个工具的输入、输出和错误。
- 明确认证、权限和数据边界。
- 提供至少 1 个核心工具调用示例。
9. 运行时与生命周期要求
9.1 运行时模式
| 模式 | 说明 | 适用阶段 |
|---|---|---|
manual | 用户或第三方手动启动，FlowyAIPC 只检查连通性 | MVP、联调。 |
managed | FlowyAIPC 安装、配置、启动、停止和监控 | 正式产品。 |
external | 服务由外部系统管理，FlowyAIPC 只连接 endpoint | 企业或私有部署。 |
每个接入必须声明支持的运行时模式。
9.2 生命周期阶段
托管集成必须覆盖以下阶段：
| 阶段 | 要求 |
|---|---|
| install | 下载、解压、SHA256 校验、版本记录。 |
| configure | 写入配置、生成 token、配置端口、模型路径。 |
| start | 非交互启动，带工作目录和环境变量。 |
| health | 判断进程或服务是否存活。 |
| ready | 判断模型、索引、数据库等是否可用。 |
| run | 提供运行状态、日志、资源占用信息。 |
| stop | 优雅停止，避免数据损坏。 |
| cleanup | 清理临时文件、缓存、过期输出。 |
| upgrade | 保持配置兼容，必要时迁移数据。 |
| uninstall | 删除程序文件，并明确用户数据保留策略。 |
9.3 生命周期行为要求
正式托管集成必须满足：
- 启动无需人工交互。
- 健康检查失败时能给出明确错误。
- Readiness 超时后能清理半启动状态。
- 停止后不残留孤儿进程。
- 崩溃后记录日志，不无限重启。
- 升级失败时能回滚或保留旧版本。
- 卸载时不得默认删除用户数据。
10. 资源要求与调度
10.1 调度等级
| 等级 | 含义 | FlowyAIPC 策略 |
|---|---|---|
light | 轻量任务，不明显占用 GPU 或磁盘 | 可并发。 |
cpu-heavy | 高 CPU 使用 | 可限流。 |
gpu-shared | 短时使用 GPU | 限流或排队。 |
gpu-exclusive | 长时间或独占 GPU | 与其他独占 GPU 任务互斥。 |
background-heavy | 长时间后台处理 | 启动前需要用户感知。 |
10.2 资源声明要求
第三方必须声明：
- 是否需要 GPU。
- GPU 厂商要求。
- 最小显存要求。
- 是否支持 CPU fallback。
- 最小内存要求。
- 空闲内存占用。
- 最小磁盘空间。
- 磁盘增长速度。
- 固定端口。
- 模型文件大小和格式。
- 是否可能长期后台运行。
10.3 模型运行模式
API Skill 和 CLI Skill 不要求绑定固定模型。第三方能力如果依赖模型推理，可以声明以下模式：
| 模式 | 说明 | 要求 |
|---|---|---|
local | 使用本地绑定模型 | 声明模型名称、格式、大小、下载方式、硬件要求。 |
external | 使用外部模型服务 | 声明 endpoint、认证、兼容协议、超时、隐私边界。 |
hybrid | 本地模型和外部模型服务混合 | 声明优先级、fallback、失败处理。 |
Manifest 示例：
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 或其他协议。
- 需要哪些环境变量或配置项。
- 模型服务不可用时的错误码。
- 是否会接收用户原始数据。
- 用户是否可以在 FlowyAIPC 配置页替换 endpoint 或模型名。
10.4 资源调度规则
gpu-exclusive任务不得与其他gpu-exclusive任务并发。- 录屏、视频编码、长时间推理任务默认应使用
gpu-exclusive。 - 批量索引、批量嵌入、视频分析任务至少应使用
gpu-shared。 - 端口冲突必须在启动前检测。
- 磁盘空间不足时不得启动长时间写入任务。
- 如果 CPU fallback 性能不可接受，应声明为不支持 fallback。
11. 权限要求
11.1 权限分类
| 权限 | 说明 |
|---|---|
file.read | 读取用户文件或目录。 |
file.write | 写入生成文件、索引、缓存或日志。 |
screen.capture | 捕获屏幕内容。 |
audio.capture | 捕获麦克风或系统音频。 |
camera.access | 访问摄像头。 |
clipboard.read | 读取剪贴板。 |
clipboard.write | 写入剪贴板。 |
network.local | 监听或访问本地端口。 |
network.remote | 访问公网或远程 API。 |
process.spawn | 启动本地可执行文件。 |
gpu.compute | 使用 GPU 推理、编码或计算。 |
model.download | 下载模型文件。 |
11.2 权限规则
- 敏感权限必须在 Manifest 中显式声明。
- 录屏、录音、摄像头和用户目录读取必须有用户可见授权。
- 文件访问必须限定到声明的目录范围。
- 本地服务默认只能绑定
127.0.0.1。 - 远程网络访问必须声明目标地址和用途。
- 权限必须可撤销。
- 禁止声明未使用权限。
12. 隐私与数据边界
12.1 数据分类
| 数据类型 | 示例 | 默认是否允许进入云端 LLM 上下文 |
|---|---|---|
safe_summary | 数量、状态、简短摘要 | 允许。 |
sensitive_metadata | 文件名、路径、时间、地点、人物描述 | 需要过滤或用户授权。 |
raw_private_data | 图片、截图、视频帧、音频、完整文档 | 默认禁止。 |
12.2 隐私规则
- 原始用户数据默认不得发送到云端 LLM。
- 工具输出进入 Agent 上下文前必须最小化。
- 本地绝对路径默认不得进入云端 LLM 上下文。
- 截图、视频帧、音频、缩略图默认禁止进入 LLM 上下文。
- Base64、临时文件路径、引用 ID 等间接方式也不得绕过隐私规则。
- 第三方必须声明哪些字段允许进入 LLM 上下文。
- 第三方必须声明哪些字段必须本地保留。
- 用户必须能删除索引、缓存、视频片段和日志等派生数据。
12.3 隐私过滤流程
text
工具原始结果 → 隐私过滤器 → 最小化摘要 → Agent 上下文 → 用户可见结果示例：
json
{
"display_name": "birthday.jpg",
"summary": "找到一张与生日场景相关的照片，相似度较高",
"local_ref": "hs_result_001"
}上例中，真实路径、缩略图和完整图像描述应保留在本地，不直接进入云端 LLM 上下文。
13. 认证与密钥管理
13.1 支持的认证类型
| 类型 | 说明 |
|---|---|
none | 无认证，仅允许本地 127.0.0.1 服务。 |
bearer_token | 静态 Bearer Token，可由 FlowyAIPC 生成。 |
api_key | 用户配置或密钥存储管理的 API Key。 |
oauth | 第三方 OAuth 或设备登录。 |
external | 认证由外部系统管理。 |
13.2 密钥规则
- 密钥不得出现在 Agent prompt 中。
- 密钥不得写入 Skill 指令。
- 密钥不得输出到普通日志。
- FlowyAIPC 生成的 token 应存储在配置或密钥存储中。
- token 应通过环境变量或配置文件注入。
- 第三方必须说明 token 生成、轮换和失效方式。
14. 错误处理与可观察性
14.1 标准错误分类
| 错误类别 | 说明 |
|---|---|
not_installed | 可执行文件、依赖或模型文件缺失。 |
not_running | 服务未启动。 |
not_ready | 服务已启动，但模型、索引或数据库未就绪。 |
auth_failed | token、API Key 或登录状态无效。 |
resource_unavailable | GPU、内存、磁盘或端口不可用。 |
permission_denied | 系统权限或用户授权不足。 |
invalid_request | 输入参数无效。 |
operation_failed | 操作执行失败。 |
timeout | 操作超时。 |
internal_error | 第三方服务内部错误。 |
unsupported | 当前平台、模型或功能不支持。 |
14.2 可观察性要求
每个接入必须提供：
- 健康检查。
- Readiness 检查，若适用。
- 日志文件路径。
- 诊断命令或诊断 API。
- 稳定错误码。
- 人类可读错误信息。
- 恢复建议。
15. 版本兼容
15.1 版本字段
yaml
version: 1.0.0
compatibility:
flowyaipc_min_version: 0.8.0
protocol_version: api-v1
breaking_change_policy: semver
deprecation_notice_days: 3015.2 版本规则
- API 或 CLI 破坏性变更必须升级主版本。
- API 集成应使用版本化路径，如
/api/v1。 - CLI 集成在同一主版本内必须保持 JSON 输出 Schema 稳定。
- 模型升级必须与可执行文件升级分开声明。
- FlowyAIPC 必须能在调用前检测不兼容版本。
- 废弃接口或参数应至少提前 30 天声明。
16. 测试与验收标准
16.1 冒烟测试
冒烟测试证明 FlowyAIPC 能检测并调用该能力。
必须验证：
- 可执行文件存在或 endpoint 可达。
- 健康检查通过。
- 认证有效。
- 最小操作成功。
- 失败状态返回结构化错误。
- 服务未启动时有明确恢复建议。
16.2 验收测试
正式接入必须覆盖：
| 场景 | 要求 |
|---|---|
| 正常操作 | 核心能力可端到端调用。 |
| 服务不可用 | 返回 not_running 或等价错误。 |
| 认证失败 | 返回 auth_failed。 |
| 无效输入 | 返回 invalid_request。 |
| 超时 | 返回 timeout，且不残留僵尸任务。 |
| 资源不可用 | GPU、磁盘、端口不足时有明确错误。 |
| 权限不足 | 返回 permission_denied。 |
| 异步任务 | 状态轮询、完成、失败路径正确。 |
| 隐私过滤 | 敏感字段不会进入 Agent 上下文。 |
| 生命周期 | 启动、停止、清理流程正常。 |
17. 接入提交清单
第三方提交接入前必须完成：
- [ ] 已按决策树选择接入类型。
- [ ] 已提供机器可读接入声明。安装包交付时应提供
manifest.yaml。 - [ ] 已提供协议文档。
- [ ] 已提供启动命令。
- [ ] 已提供健康检查。
- [ ] 已提供 Readiness 检查，或说明不需要。
- [ ] 已提供认证说明。
- [ ] 已提供资源声明。
- [ ] 已提供权限声明。
- [ ] 已提供隐私声明。
- [ ] 已提供错误码文档。
- [ ] 已提供日志或诊断方式。
- [ ] 已提供版本兼容说明。
- [ ] 已提供冒烟测试步骤。
- [ ] 已提供验收测试步骤。
- [ ] 已提供 Windows 兼容性说明，若仅支持其他系统则需明确说明。
18. 示例：HeliconSearch
分类：API Skill。
原因：HeliconSearch 通过 REST API 提供媒体搜索、知识库管理、上传和索引能力。它不拥有用户会话，也不负责长期推理流程。
建议：
| 维度 | 标准 |
|---|---|
| 接入类型 | API Skill。 |
| 运行时模式 | MVP 使用 manual，正式集成使用 managed。 |
| 资源等级 | gpu-shared，批量索引时可提升为 background-heavy。 |
| 权限 | 用户选择媒体目录，只允许访问授权目录。 |
| 隐私 | 图片路径、视频路径、语义描述属于 sensitive_metadata。 |
| LLM 可见字段 | 数量、模糊摘要、相似度、局部文件名。 |
| LLM 禁止字段 | 绝对路径、缩略图、原始图片、完整人物描述。 |
19. 示例：Highlight
分类：API Skill + Managed Service。
原因：Highlight 提供录屏、进球检测、会话管理和视频片段生成能力，有长时间后台任务，但不拥有用户对话会话。
建议：
| 维度 | 标准 |
|---|---|
| 接入类型 | API Skill。 |
| 运行时模式 | 正式集成使用 managed。 |
| 资源等级 | gpu-exclusive。 |
| 权限 | screen.capture、audio.capture、file.write、gpu.compute。 |
| 隐私 | 原始屏幕、视频和音频默认本地保留。 |
| LLM 可见字段 | 进球数量、时间点、简短摘要。 |
| LLM 禁止字段 | 截图帧、视频文件、系统音频、绝对路径。 |
| 生命周期 | 必须支持停止录制、等待 finalizing、获取结果和清理旧片段。 |
20. 附录：快速决策表
| 问题 | 结果 |
|---|---|
| 是否有多轮会话和任务执行？ | 是则优先 ACP Agent。 |
| 是否已有 MCP Server？ | 是则优先 MCP Tool。 |
| 是否提供稳定 API？ | 是则 API Skill。 |
| 是否只有 CLI？ | CLI Skill，必须支持非交互和结构化输出。 |
| 是否需要 FlowyAIPC 启停进程？ | 同时声明为 Managed Service。 |
| 是否读取屏幕、音频、照片或视频？ | 必须声明权限和隐私边界。 |
| 是否使用 GPU 或大量磁盘？ | 必须声明资源调度等级。 |