FlowyAIPC 第三方智能能力接入标准（第一版）
版本：0.1.0
状态：草案
适用对象：第三方能力开发者、FlowyAIPC 集成开发者、产品与测试同学
说明：本文档是第一版精简标准，用于快速统一接入分类、交付物、资源、权限、隐私与验收要求。完整版见spec.md。安装包格式规范见manifest-spec/index.md。
1. 目的
本文档定义第三方智能能力接入 FlowyAIPC 的基本标准。
第三方能力可以是会话型 Agent、API 服务、CLI 工具、MCP Server 或本地托管服务。并非所有接入对象都应被称为 Agent。
本标准的目标是：
- 明确第三方能力的接入类型。
- 明确第三方必须提供的交付物。
- 明确 FlowyAIPC 如何启动、调用、鉴权、限制和展示第三方能力。
- 明确资源、权限、隐私和生命周期的最低要求。
- 明确什么情况下可以通过接入验收。
本文是能力接入总览，不是安装包 manifest schema。若第三方以 zip + manifest.yaml 交付安装包，应同时参考 manifest-spec/index.md 及目标平台 Profile。
2. 术语
| 术语 | 说明 |
|---|---|
| Capability（能力） | FlowyAIPC 可调用或编排的第三方功能。 |
| Agent（智能体） | 具备会话、推理、上下文管理或任务执行能力的运行时。 |
| Tool（工具） | 执行有界操作并返回结构化结果的服务或函数。 |
| Skill | OpenClaw 兼容的指令包，用于教 Agent 如何调用第三方能力。 |
| ACP Agent | 通过 Agent Client Protocol 接入的外部 Agent 运行时。 |
| API Skill | 通过 Skill 包装 HTTP、gRPC 或 WebSocket API 的接入方式。 |
| CLI Skill | 通过 Skill 包装命令行程序的接入方式。 |
| MCP Tool | 通过 MCP Server 暴露的标准工具能力。 |
| Managed Service | 由 FlowyAIPC 安装、配置、启动、停止和监控的本地服务。 |
| Manifest | 机器可读的接入声明。能力接入总标准中可泛指接入声明；安装包规范中具体指包根目录下的 manifest.yaml。 |
3. 接入类型决策树
FlowyAIPC 按能力本质分类，而不是按第三方自称的名称分类。
该能力是否提供多轮会话或任务执行运行时？
是 → 是否支持 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，优先使用 MCP Tool，而不是重复包装 API 或 CLI。
4. 支持的接入类型
| 接入类型 | 适用对象 | 第三方必须提供 |
|---|---|---|
| ACP Agent | 会话型 Agent、编码 Agent、桌面 Agent、任务执行 Agent | ACP 可执行文件、启动命令、模型与认证说明、权限说明、健康检查方式。 |
| API Skill | REST、gRPC、WebSocket 工具服务 | API 文档、接口示例、健康检查、认证方式、错误码、资源与隐私声明。 |
| CLI Skill | 本地 CLI 工具、批处理程序 | CLI 文档、非交互模式、JSON 输出、退出码、配置方式、日志位置。 |
| MCP Tool | 标准 MCP Server | MCP Server 启动命令、工具 Schema、认证方式、权限与数据访问说明。 |
| Managed Service | 需要 FlowyAIPC 托管的本地服务 | 安装包、启动命令、停止方式、健康检查、日志路径、清理策略。 |
5. 必需交付物
每个第三方接入必须提供以下材料：
| 交付物 | 必须 | 说明 |
|---|---|---|
| 接入类型说明 | 是 | 按决策树说明为什么选择该类型。 |
| 机器可读接入声明 | 是 | 可由 manifest.yaml、平台接入配置或其他 Profile 约定的声明文件承载。安装包交付时使用 manifest.yaml。 |
| 协议文档 | 是 | ACP、API、CLI 或 MCP 文档。 |
| 启动说明 | 是 | 如何手动启动，如何被 FlowyAIPC 启动。 |
| 健康检查 | 是 | FlowyAIPC 如何判断服务是否存活。 |
| Readiness 检查 | 条件必填 | 模型加载、索引构建等异步服务必须提供。 |
| 认证说明 | 是 | 无认证、Bearer Token、API Key、OAuth 或外部认证。 |
| 资源声明 | 是 | GPU、内存、磁盘、端口、模型大小。 |
| 权限声明 | 是 | 文件、屏幕、音频、网络、进程、GPU 等权限。 |
| 隐私声明 | 是 | 读取、生成、存储、返回哪些用户数据。 |
| 错误码文档 | 是 | 稳定错误分类与恢复建议。 |
| 测试说明 | 是 | 冒烟测试与验收测试步骤。 |
6. Manifest 最小规范
每个接入必须提供机器可读接入声明。安装包交付场景使用 manifest.yaml，具体 schema 见 manifest-spec/index.md。
示例：
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
runtime:
mode: managed
os:
- win32
executable: highlight.exe
start_command:
- highlight.exe
- --config
- "{config_dir}/highlight/config.json"
resources:
scheduling_class: gpu-exclusive
gpu:
required: true
vendor: intel
min_vram_gb: 8
memory:
min_gb: 16
disk:
min_free_gb: 20
growth_hint: "3.6 GB/hour"
ports:
- 8088
permissions:
screen_capture: required
audio_capture: required
file_write:
- "{app_data}/highlight/output"
network:
local_only: true
privacy:
local_processing: true
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
model:
mode: external
provider: openai-compatible
endpoint_env: VENDOR_MODEL_BASE_URL
api_key_env: VENDOR_MODEL_API_KEY
compatibility:
flowyaipc_min_version: 0.8.0
protocol_version: api-v17. 资源、权限、隐私与生命周期要求
7.1 资源要求
资源调度等级：
| 等级 | 含义 | FlowyAIPC 策略 |
|---|---|---|
light | 轻量任务，不明显占用 GPU 或磁盘 | 可并发。 |
cpu-heavy | 高 CPU 使用 | 可限流。 |
gpu-shared | 短时使用 GPU | 限流或排队。 |
gpu-exclusive | 长时间或独占 GPU | 与其他独占 GPU 任务互斥。 |
background-heavy | 长时间后台处理 | 启动前需要用户感知。 |
接入必须声明：
- 是否需要 GPU。
- 最小显存要求。
- 是否支持 CPU fallback。
- 最小内存要求。
- 最小磁盘空间要求。
- 磁盘增长速度。
- 固定端口。
- 模型文件大小。
- 如果依赖模型推理，必须声明模型运行模式：本地绑定模型、外部模型服务或混合模式。
7.2 权限要求
本节使用 dot notation 表达权限概念。安装包 manifest 使用 YAML snake_case 字段，例如 file_read、file_write、screen_capture、process_spawn。
敏感权限必须显式声明：
| 权限 | 说明 |
|---|---|
file.read | 读取用户文件或目录。 |
file.write | 写入索引、缓存、日志或输出文件。 |
screen.capture | 捕获屏幕内容。 |
audio.capture | 捕获麦克风或系统音频。 |
network.local | 监听或访问本地端口。 |
network.remote | 访问公网或远程 API。 |
process.spawn | 启动本地可执行文件。 |
gpu.compute | 使用 GPU 推理或编码。 |
model.download | 下载模型文件。 |
录屏、录音、摄像头、用户目录读取必须有用户可见授权。权限必须可撤销。
7.3 隐私要求
数据分级：
| 数据类型 | 示例 | 默认是否允许进入云端 LLM 上下文 |
|---|---|---|
safe_summary | 数量、状态、简短摘要 | 允许。 |
sensitive_metadata | 文件名、路径、时间、地点、人物描述 | 需要过滤或用户授权。 |
raw_private_data | 图片、截图、视频帧、音频、完整文档 | 默认禁止。 |
规则：
- 工具原始结果必须先经过隐私过滤，再进入 Agent 上下文。
- 本地绝对路径、截图、视频帧、音频、缩略图默认不得进入云端 LLM 上下文。
- 第三方必须声明哪些字段允许进入 LLM 上下文，哪些字段必须本地保留。
7.4 生命周期要求
FlowyAIPC 支持 3 种运行时模式：
| 模式 | 说明 | 适用阶段 |
|---|---|---|
manual | 用户或第三方手动启动，FlowyAIPC 只检查连通性 | MVP、联调。 |
managed | FlowyAIPC 安装、配置、启动、停止和监控 | 正式集成。 |
external | 服务由外部系统管理，FlowyAIPC 只连接 endpoint | 企业或私有部署。 |
托管服务在完整运行时集成中必须支持：安装、配置、启动、健康检查、就绪检查、停止、日志、清理、升级和卸载。具体平台 Profile 可以声明只支持其中一部分。例如 Electron v0.1 安装器只负责安装、配置生成和 Skill 注册，不负责启动服务或探活。
7.5 Skill metadata 与环境准备
第三方可以自带 OpenClaw 兼容 Skills。FlowyAIPC 可以从 SKILL.md 的 metadata.openclaw 中解析依赖和环境信息，用于提示缺失项、准备环境或辅助安装。具体是否执行安装、是否注入环境变量，由目标平台 Profile 决定。
常用 metadata 字段：
| 字段 | 说明 |
|---|---|
metadata.openclaw.requires.bins | 所需 CLI 二进制。 |
metadata.openclaw.requires.env | 所需环境变量，例如 token、外部模型服务地址。 |
metadata.openclaw.requires.config | 所需 FlowyAIPC 配置项。 |
metadata.openclaw.os | 支持的操作系统。 |
metadata.openclaw.install | 可选安装声明。 |
metadata.openclaw.primaryEnv | 主要密钥环境变量。 |
如果第三方未提供 Skills，FlowyAIPC 可根据 api.spec.md 或 cli.spec.md 生成或半自动生成 Skills。该能力不是所有平台 Profile 的必选能力。
8. 验收清单
提交接入前必须完成：
- [ ] 已按决策树选择接入类型。
- [ ] 已提供机器可读接入声明。安装包交付时应提供
manifest.yaml。 - [ ] 已提供协议文档。
- [ ] 已提供启动命令。
- [ ] 已提供健康检查。
- [ ] 已提供 Readiness 检查，或说明不需要。
- [ ] 已提供认证说明。
- [ ] 已提供资源声明。
- [ ] 已提供权限声明。
- [ ] 已提供隐私声明。
- [ ] 已提供错误码文档。
- [ ] 已提供日志或诊断方式。
- [ ] 已提供版本兼容说明。
- [ ] 已提供冒烟测试步骤。
- [ ] 已提供验收测试步骤。
- [ ] 已提供 Windows 兼容性说明，若仅支持其他系统则需明确说明。