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

版本：1.0.0
状态：草案
适用对象：以 CLI 方式接入 FlowyAIPC 的第三方能力开发者
目标：确保 FlowyAIPC 开发者可以根据 CLI 文档直接编写 Skill、解析输出、处理错误、控制超时，并完成诊断与验收。

1. 总体要求

CLI 类型第三方能力必须提供稳定、非交互、可解析、可诊断的命令行接口。

第三方开发者可以参考 Lark CLI 的设计方式来组织 CLI 和 Skills：Lark CLI 通过稳定命令、结构化输出、领域化命令分组和配套 Skills，让 AI Agent 可以可靠调用复杂业务能力。参考项目：https://github.com/larksuite/cli。

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

CLI 文档不能只列出命令参数，还必须说明：

如何安装和运行。
是否支持非交互模式。
如何输出结构化结果。
退出码如何定义。
长任务如何超时和取消。
日志和诊断如何获取。
命令输出中哪些字段属于敏感数据。

推荐交付物：

交付物	要求
`cli.md`	面向人阅读的 CLI 文档。
`commands.json`	命令、参数、输出 Schema，推荐提供。
`skills/`	可选。第三方自带的 OpenClaw 兼容 Skills。
`skill-template/`	可选。第三方自带的 Skill 模板或生成说明。
`examples/`	示例输入输出。
`errors.md`	退出码和错误输出。
`smoke-test.md`	冒烟测试步骤。

2. CLI 文档推荐结构

markdown

# <能力名称> CLI 文档

## 1. 基本信息

## 2. 安装与运行环境

## 3. 全局参数

## 4. 配置文件

## 5. 环境变量

## 6. 命令列表

## 7. 单个命令说明

## 8. 输出格式

## 9. 退出码

## 10. 超时与取消

## 11. 日志与诊断

## 12. 权限与隐私

## 13. 冒烟测试

## 14. 版本兼容

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

3. Skill 交付或生成要求

第三方 CLI 能力有两种 Skill 接入方式。

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

3.1 自带 Skills 的建议结构

第三方可以参考 Lark CLI 的组织方式：

text

skills/
  <vendor>-shared/
    SKILL.md
  <vendor>-<domain>/
    SKILL.md
    references/
      <workflow>.md
      <shortcut>.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.bins`	声明所需 CLI 可执行文件。
`metadata.openclaw.requires.env`	可选。声明 token、endpoint、外部模型服务等环境变量。
`metadata.openclaw.requires.config`	可选。声明 endpoint、模型服务地址等配置项。
`metadata.openclaw.install`	可选。声明依赖安装方式，FlowyAIPC 可据此提示、安装或准备环境；具体是否执行由平台 Profile 决定。
`metadata.openclaw.primaryEnv`	可选。声明主要密钥环境变量，便于 FlowyAIPC 绑定密钥配置。
`cliHelp`	指向对应 CLI 帮助命令，如 `<cli> <domain> --help`。
认证说明	如何登录、如何配置 token、如何处理认证失败。
命令调用规则	使用哪些命令、参数如何填写、何时使用 Shortcut。
错误处理	常见错误码与恢复动作。
隐私规则	哪些输出字段不得进入 LLM 上下文。
工作流约束	高风险或多步骤操作的固定流程。

OpenClaw Skill metadata 示例：

markdown

---
name: vendor-highlight
description: "通过 vendor-highlight CLI 管理录屏、检测和视频片段生成。"
metadata:
  {
    "openclaw": {
      "os": ["win32"],
      "requires": {
        "bins": ["vendor-highlight"],
        "env": ["VENDOR_MODEL_BASE_URL"],
        "config": ["vendorHighlight.outputDir"]
      },
      "install": [
        {
          "id": "download-win32",
          "kind": "download",
          "os": ["win32"],
          "url": "https://example.com/vendor-highlight.zip",
          "archive": "zip",
          "bins": ["vendor-highlight"]
        }
      ]
    }
  }
---

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

判断 Skill 是否可加载。
检查 CLI 二进制是否存在。
提示用户缺少哪些环境变量或配置项。
检查当前平台是否支持。
为用户提示或安装 CLI，或准备运行目录；具体是否执行由平台 Profile 决定。
通过环境变量、配置文件、marker、registry 或其他平台约定方式提供外部模型服务地址、token、输出目录等配置发现入口。

3.3 文档到 Skill 的生成要求

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

命令按领域分组。
每个命令有稳定名称、参数表、成功输出和失败输出。
输出字段标注隐私级别。
错误码可映射到用户提示和恢复动作。
长任务有状态查询或进度输出。
常用场景有推荐命令组合或 Shortcut。
高风险操作有明确前置确认要求。

4. 基本信息

CLI 文档必须说明：

字段	示例
CLI 名称	`highlight-cli`
可执行文件	`highlight.exe`
支持系统	`win32`
默认编码	UTF-8
是否支持非交互	必须支持
是否支持 JSON 输出	强烈建议必填
是否需要模型	是 / 否
模型运行模式	本地绑定模型 / 外部模型服务 / 混合模式
是否需要 GPU	是 / 否

示例：

markdown

## 基本信息

- CLI 名称：highlight
- 可执行文件：`highlight.exe`
- 支持平台：Windows 10 / Windows 11
- 默认编码：UTF-8
- 支持非交互模式：是
- 支持 JSON 输出：是，使用 `--json`
- 模型运行模式：混合模式，默认本地模型，允许配置外部 OpenAI-compatible 服务

5. 安装与运行环境

CLI 文档必须说明运行环境。

项	要求
OS	必填。
CPU / GPU	必填。
内存	必填。
磁盘	必填。
模型文件	如有则必填。
依赖程序	如 FFmpeg、OpenVINO。
PATH 要求	必填。
管理员权限	如需要必须说明。
外部模型服务	如支持则必填。

示例：

markdown

## 运行环境

- OS：Windows 10 或 Windows 11
- GPU：Intel Arc，显存不少于 8 GB
- 依赖：FFmpeg >= 6.0，必须包含 Intel QSV 支持
- 模型：默认使用 `gemma-3-4b-q4.gguf`，也允许通过配置使用外部模型服务
- 管理员权限：通常不需要；部分 DXGI 场景可能需要

6. 模型运行模式

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

支持 3 种模式：

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

配置文件示例：

yaml

model:
  mode: external
  provider: openai-compatible
  endpoint: "${VENDOR_MODEL_BASE_URL}"
  api_key: "${VENDOR_MODEL_API_KEY}"
  default_model: qwen-vl
  timeout_seconds: 60

文档必须说明：

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

7. 全局参数

所有 CLI 都应支持以下参数。

参数	必须	说明
`--help`	是	输出帮助信息。
`--version`	是	输出版本。
`--config <path>`	推荐	指定配置文件。
`--json`	强烈推荐	输出 JSON。
`--log-level <level>`	推荐	日志级别。
`--no-color`	推荐	禁用彩色输出，便于解析。
`--quiet`	推荐	减少非结构化输出。

8. 非交互要求

FlowyAIPC 调用 CLI 时，CLI 必须能在无人值守环境中运行。

禁止行为：

禁止行为	原因
等待用户输入 `y/n`	会导致 Agent 卡死。
弹出 GUI 窗口要求确认	无法自动化。
输出非结构化进度覆盖 JSON	破坏解析。
把错误混入 JSON stdout	破坏解析。
未设置超时时长时永久运行	难以治理。

必须满足：

text

命令 + 参数 + 配置文件 → 执行 → 输出结构化结果 → 返回退出码

9. 配置文件标准

CLI 应支持配置文件，并说明格式。

示例：

yaml

server:
  port: 8088
  bind: 127.0.0.1

auth:
  token: "${HIGHLIGHT_AUTH_TOKEN}"

runtime:
  model_path: "models/gemma-3-4b-q4.gguf"
  output_dir: "video"

文档必须说明：

项	要求
配置文件格式	JSON、YAML 或 TOML。
默认路径	必填。
是否支持 `--config`	推荐。
环境变量是否可覆盖	推荐。
token 是否允许写入配置	必须说明。
路径是否支持相对路径	必须说明。

10. 环境变量标准

文档必须列出所有环境变量。

模板：

环境变量	必填	默认值	说明
`HIGHLIGHT_AUTH_TOKEN`	是	无	API 认证 token。
`HIGHLIGHT_FFMPEG_PATH`	否	PATH 中查找	FFmpeg 路径。
`HIGHLIGHT_MODEL_DIR`	否	`models/`	模型目录。

11. 命令列表

CLI 文档必须提供命令总览。

示例：

命令	说明	是否长任务	是否输出 JSON
`highlight doctor`	诊断环境。	否	是
`highlight serve`	启动服务。	是	是
`highlight session start`	开始录制。	是	是
`highlight session status`	查询状态。	否	是
`highlight session stop`	停止录制。	否	是

12. 单个命令文档模板

每个命令应按以下模板编写。

markdown

## highlight session start

### 功能说明

启动一个录制会话。

### 命令格式

```powershell
highlight session start --config .\config.json --json

参数

参数	类型	必填	默认值	说明
--config	path	是	-	配置文件路径。
--json	boolean	是	false	输出 JSON。
--region	string	否	auto	录制区域。
--timeout	integer	否	60	启动超时，单位：秒。

成功输出

json

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "sid_001",
    "state": "recording"
  }
}

失败输出

json

{
  "code": "resource_unavailable",
  "message": "FFmpeg with Intel QSV support was not found",
  "details": {
    "dependency": "ffmpeg",
    "required": ">= 6.0 with qsv"
  }
}

退出码

退出码	含义
0	成功。
2	参数错误。
10	认证失败。
20	资源不可用。
30	权限不足。
40	超时。
50	内部错误。

FlowyAIPC 集成说明

必须带 --json。
如果返回 resource_unavailable，FlowyAIPC 应提示用户检查 FFmpeg 或 GPU。
命令超时时，FlowyAIPC 可以终止进程。


---

## 13. 输出格式标准

CLI 必须支持结构化输出。推荐所有命令统一输出格式。

成功：

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

失败：

json

{
  "code": "invalid_request",
  "message": "Missing required argument: --config",
  "details": {
    "argument": "--config"
  }
}

要求：

项	要求
stdout	只输出 JSON 结果。
stderr	输出日志、警告、诊断信息。
彩色输出	JSON 模式必须禁用。
进度输出	使用 stderr 或 JSON Lines，不得破坏最终 JSON。
编码	UTF-8。

长任务推荐使用 JSON Lines：

jsonl

{"type":"progress","progress":0.1,"message":"Loading model"}
{"type":"progress","progress":0.5,"message":"Processing video"}
{"type":"result","code":0,"data":{"output":"clip.mp4"}}

14. 退出码标准

建议统一退出码：

退出码	错误码	含义
0	`success`	成功。
1	`internal_error`	未分类错误。
2	`invalid_request`	参数错误。
3	`unsupported`	平台或功能不支持。
10	`auth_failed`	认证失败。
20	`resource_unavailable`	资源不可用。
30	`permission_denied`	权限不足。
40	`timeout`	超时。
50	`not_ready`	服务或模型未就绪。
60	`operation_failed`	操作失败。

文档必须说明每个退出码是否可重试，以及用户可见提示。

15. 超时与取消

CLI 文档必须说明：

项	要求
默认超时	必填。
长任务是否支持 `--timeout`	推荐。
取消方式	进程终止、子命令取消或 API 取消。
取消后是否清理临时文件	必填。
是否会残留子进程	必填。

标准要求：

markdown

当 FlowyAIPC 终止 CLI 进程时，CLI 必须终止其子进程，释放文件锁和 GPU 资源。若无法保证，必须提供显式取消命令。

16. 日志与诊断

CLI 必须提供诊断命令，建议命名为 doctor。

示例：

powershell

highlight doctor --json

输出：

json

{
  "code": 0,
  "data": {
    "ffmpeg": {
      "status": "ok",
      "version": "6.1",
      "qsv": true
    },
    "gpu": {
      "status": "ok",
      "vendor": "intel",
      "vram_gb": 8
    },
    "model": {
      "status": "ok",
      "path": "models/gemma.gguf"
    }
  }
}

文档必须说明日志路径：

日志	路径	说明
主日志	`%APPDATA%/FlowyAIPC/highlight/logs/highlight.log`	运行日志。
错误日志	`%APPDATA%/FlowyAIPC/highlight/logs/error.log`	错误日志。

17. 权限与隐私

CLI 文档必须声明权限和隐私，不得只写命令参数。

必须说明：

项	示例
读取哪些文件	用户选择的视频目录。
写入哪些文件	输出视频、索引、缓存。
是否录屏	是 / 否。
是否录音	是 / 否。
是否访问网络	仅下载模型。
是否调用外部模型服务	是 / 否。
是否调用 GPU	是 / 否。
stdout 是否包含敏感数据	是 / 否。
哪些字段不得进入 LLM 上下文	绝对路径、截图、视频帧。

推荐隐私级别：

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

18. 冒烟测试

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

示例：

powershell

highlight --version
highlight --help
highlight doctor --json
highlight session start --config .\config.json --json
highlight session status --session-id sid_001 --json
highlight session stop --session-id sid_001 --json

冒烟测试必须覆盖：

可执行文件存在。
--version 正常。
--help 正常。
诊断命令正常。
JSON 输出可解析。
最小核心命令成功。
失败命令返回稳定退出码和结构化错误。

19. 版本兼容

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

yaml

cli_version: 1.0.0
compatibility:
  flowyaipc_min_version: 0.8.0
  breaking_change_policy: semver
  deprecation_notice_days: 30

规则：

破坏性变更必须升级主版本。
同一主版本内必须保持 JSON 输出 Schema 稳定。
新增参数必须保持默认行为兼容。
删除参数、改变字段类型、改变退出码语义都属于破坏性变更。
废弃命令或参数应至少提前 30 天声明。

20. CLI 文档验收标准

CLI 文档合格标准：

检查项	必须
有安装与运行环境说明	是
有非交互模式说明	是
有 `--help` 和 `--version`	是
有 JSON 输出说明	是
有模型运行模式说明，若依赖模型推理	是
每个命令都有参数表	是
每个命令都有成功和失败输出示例	是
有退出码规范	是
有超时与取消说明	是
有日志与诊断命令	是
有权限与隐私说明	是
有冒烟测试步骤	是
有版本兼容说明	是
如未自带 Skills，文档可支撑人工编写或平台生成 Skills	是

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

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

1. 总体要求 ​

2. CLI 文档推荐结构 ​

3. Skill 交付或生成要求 ​

3.1 自带 Skills 的建议结构 ​

3.2 Skill 必须包含的内容 ​

3.3 文档到 Skill 的生成要求 ​

4. 基本信息 ​

5. 安装与运行环境 ​

6. 模型运行模式 ​

7. 全局参数 ​

8. 非交互要求 ​

9. 配置文件标准 ​

10. 环境变量标准 ​

11. 命令列表 ​

12. 单个命令文档模板 ​

参数 ​

成功输出 ​

失败输出 ​

退出码 ​

FlowyAIPC 集成说明 ​

14. 退出码标准 ​

15. 超时与取消 ​

16. 日志与诊断 ​

17. 权限与隐私 ​

18. 冒烟测试 ​

19. 版本兼容 ​

20. CLI 文档验收标准 ​

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

1. 总体要求

2. CLI 文档推荐结构

3. Skill 交付或生成要求

3.1 自带 Skills 的建议结构

3.2 Skill 必须包含的内容

3.3 文档到 Skill 的生成要求

4. 基本信息

5. 安装与运行环境

6. 模型运行模式

7. 全局参数

8. 非交互要求

9. 配置文件标准

10. 环境变量标准

11. 命令列表

12. 单个命令文档模板

参数

成功输出

失败输出

退出码

FlowyAIPC 集成说明

14. 退出码标准

15. 超时与取消

16. 日志与诊断

17. 权限与隐私

18. 冒烟测试

19. 版本兼容

20. CLI 文档验收标准