创建适配器

适配器把一个实用动作注册为可搜索的 Uni-CLI 操作。默认使用 YAML，在同一文件中声明元数据、参数和流水线步骤。

创建文件

unicli init example search

生成文件位于 src/adapters/example/search.yaml。-o 可以选择目录，-t 可以选择 web-api、browser、desktop、bridge 或 service。

描述操作

下面是一份简短的公开 HTTP 适配器。

site: hackernews
name: top
description: Hacker News top stories
type: web-api
strategy: public
target_surface: web
execution_operator: structured-api
operation_family: list
operation_effect: read
args:
  - name: limit
    type: int
    default: 20
pipeline:
  - fetch:
      url: https://news.ycombinator.com/
  - select:
      selector: .athing
      fields:
        title: .titleline > a
        url: .titleline > a@href
  - limit: ${{ args.limit }}
capabilities: ["http.fetch"]
minimum_capability: http.fetch
trust: public
confidentiality: public
quarantine: false
schema_version: v2

描述应贴近用户想完成的任务。契约字段帮助搜索、权限策略和 Agent 客户端在执行前判断操作是否适用。

选择类型

类型	适用场景
web-api	HTTP API、feed 与结构化网页响应
browser	登录页面、DOM action 与 browser network capture
desktop	本机 App 与可执行程序
bridge	gh、docker 等已有 CLI
service	本机或远程 HTTP、WebSocket 服务

类型字段说明集成方式，execution_operator 记录实际执行接口。

定义参数

args:
  - name: query
    type: str
    required: true
    positional: true
    description: Search terms
  - name: limit
    type: int
    default: 10
    minimum: 1
    maximum: 100

参数支持 JSON Schema 约束，以及路径、ID、选择器和 URL 等 Uni-CLI 参数类别。完整字段见适配器格式。

编写 pipeline

流水线步骤接收当前上下文，并可通过模板表达式引用参数。

pipeline:
  - fetch:
      url: https://example.com/search?q=${{ args.query }}
  - select:
      selector: article
      fields:
        title: h2
        url: a@href
  - limit: ${{ args.limit }}

可用动作见 Pipeline steps。

本地运行

unicli dev src/adapters/example/search.yaml
unicli describe example search
unicli example search "test" --limit 3 -f json
unicli test example

行为稳定后，加入覆盖实际执行路径的行为场景或复用已有测试数据。

自定义流程使用 TypeScript

SDK、流式协议、有状态服务和复杂控制流更适合 TypeScript 适配器。它们注册相同的操作元数据，并返回相同的响应结构。

TypeScript 契约见适配器格式。