AAI Protocol

简体中文

English

简体中文

English

Appearance

应用描述文件：aai.json ​

每个支持 AAI 的应用在统一的 AAI 配置目录中提供 aai.json 文件。

文件位置 ​

平台路径
macOS / Linux~/.aai/<appId>/aai.json
Windows%USERPROFILE%\.aai\<appId>\aai.json

示例：

  • macOS: ~/.aai/com.apple.mail/aai.json
  • Windows: C:\Users\Alice\.aai\com.microsoft.outlook\aai.json

优势：

  • 无需修改已签名的应用程序包
  • 无需管理员权限
  • 用户或社区可自由添加、修改、删除配置
  • Gateway 只需扫描单一目录即可发现所有应用

结构示例 ​

json
{
  "schema_version": "1.0",
  "appId": "com.apple.mail",
  "name": "Mail",
  "description": "Apple's native email client",
  "version": "1.0",
  "platforms": {
    "macos": {
      "automation": "applescript",
      "tools": [
        {
          "name": "send_email",
          "description": "Send a new email via Apple Mail",
          "parameters": {
            "type": "object",
            "properties": {
              "to": { "type": "string", "description": "Recipient email address" },
              "subject": { "type": "string", "description": "Email subject" },
              "body": { "type": "string", "description": "Email body content" }
            },
            "required": ["to", "subject", "body"]
          },
          "script": "tell application \"Mail\"\n  set newMessage to make new outgoing message with properties {subject:\"${subject}\", content:\"${body}\", visible:false}\n  tell newMessage\n    make new to recipient at beginning of to recipients with properties {address:\"${to}\"}\n    send\n  end tell\nend tell\nreturn \"{\\\"success\\\":true, \\\"message_id\\\":\\\"generated\\\"}\"",
          "output_parser": "result as text"
        },
        {
          "name": "search_emails",
          "description": "Search emails in mailbox",
          "parameters": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "Search query string" }
            },
            "required": ["query"]
          },
          "script": "tell application \"Mail\"\n  set results to (messages whose subject contains \"${query}\")\nend tell\nreturn \"{\\\"emails\\\":[\\\"result1\\\", \\\"result2\\\"]}\"",
          "output_parser": "result as text"
        }
      ]
    },
    "windows": {
      "automation": "com",
      "progid": "Outlook.Application",
      "tools": [
        {
          "name": "send_email",
          "description": "Send a new email via Microsoft Outlook",
          "parameters": {
            "type": "object",
            "properties": {
              "to": { "type": "string", "description": "Recipient email address" },
              "subject": { "type": "string", "description": "Email subject" },
              "body": { "type": "string", "description": "Email body content" }
            },
            "required": ["to", "subject", "body"]
          },
          "script": [
            { "action": "create", "var": "app", "progid": "Outlook.Application" },
            {
              "action": "call",
              "var": "mail",
              "object": "app",
              "method": "CreateItem",
              "args": [0]
            },
            { "action": "set", "object": "mail", "property": "To", "value": "${to}" },
            { "action": "set", "object": "mail", "property": "Subject", "value": "${subject}" },
            { "action": "set", "object": "mail", "property": "Body", "value": "${body}" },
            { "action": "call", "object": "mail", "method": "Send" },
            { "action": "return", "value": "{\"success\":true, \"message_id\":\"generated\"}" }
          ],
          "output_parser": "last_result"
        }
      ]
    },
    "linux": {
      "automation": "dbus",
      "service": "org.example.Mail",
      "object": "/org/example/Mail",
      "interface": "org.example.Mail",
      "tools": [
        {
          "name": "send_email",
          "description": "Send a new email",
          "parameters": {
            "type": "object",
            "properties": {
              "to": { "type": "string", "description": "Recipient email address" },
              "subject": { "type": "string", "description": "Email subject" },
              "body": { "type": "string", "description": "Email body content" }
            },
            "required": ["to", "subject", "body"]
          },
          "method": "SendEmail",
          "output_parser": "json"
        }
      ]
    },
    "android": {
      "automation": "intent",
      "package": "com.example.mail",
      "tools": [
        {
          "name": "send_email",
          "description": "Send a new email",
          "parameters": {
            "type": "object",
            "properties": {
              "to": { "type": "string", "description": "Recipient email address" },
              "subject": { "type": "string", "description": "Email subject" },
              "body": { "type": "string", "description": "Email body content" }
            },
            "required": ["to", "subject", "body"]
          },
          "action": "com.example.MAIL_SEND",
          "extras": {
            "to": "${to}",
            "subject": "${subject}",
            "body": "${body}"
          },
          "result_type": "content_provider",
          "result_uri": "content://com.example.mail/results"
        }
      ]
    },
    "ios": {
      "automation": "url_scheme",
      "scheme": "mailapp",
      "tools": [
        {
          "name": "send_email",
          "description": "Send a new email",
          "parameters": {
            "type": "object",
            "properties": {
              "to": { "type": "string", "description": "Recipient email address" },
              "subject": { "type": "string", "description": "Email subject" },
              "body": { "type": "string", "description": "Email body content" }
            },
            "required": ["to", "subject", "body"]
          },
          "url_template": "mailapp://send?to=${to}&subject=${subject}&body=${body}",
          "result_type": "app_group",
          "app_group_id": "group.com.example.mail"
        }
      ]
    },
    "web": {
      "automation": "restapi",
      "base_url": "https://api.notion.com/v1",
      "auth": {
        "type": "oauth2",
        "auth_url": "https://api.notion.com/v1/oauth/authorize",
        "token_url": "https://api.notion.com/v1/oauth/token",
        "scopes": ["read_content", "update_content"],
        "token_placement": "header",
        "token_prefix": "Bearer"
      },
      "default_headers": {
        "Notion-Version": "2022-06-28",
        "Content-Type": "application/json"
      },
      "tools": [
        {
          "name": "search",
          "description": "Search pages and databases",
          "parameters": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "Search query text" }
            },
            "required": ["query"]
          },
          "endpoint": "/search",
          "method": "POST",
          "body": { "query": "${query}" },
          "output_parser": "json"
        }
      ]
    }
  }
}

字段说明 ​

通用字段 ​

字段类型描述
schema_versionstringaai.json 的 Schema 版本，用于兼容性检查
appIdstring唯一标识符（建议使用反向 DNS 格式）
namestring应用名称
descriptionstring应用描述
versionstringaai.json 版本号
platformsobject各平台的自动化配置

macOS 专有字段 ​

字段类型描述
platforms.macos.automationstring自动化类型：applescript 或 jxa
platforms.macos.tools[].scriptstring脚本模板，支持 ${param} 占位符
platforms.macos.tools[].output_parserstring输出解析方式：result as text（字符串）、result as record（字典）
platforms.macos.tools[].timeoutinteger超时时间（秒），默认 30

Windows 专有字段 ​

字段类型描述
platforms.windows.automationstring自动化类型：com
platforms.windows.progidstringCOM ProgID（例如 Outlook.Application）
platforms.windows.tools[].scriptarrayCOM 操作序列
platforms.windows.tools[].script[].actionstring操作类型：create（创建对象）、call（调用方法）、set（设置属性）、get（获取属性）、return（返回结果）
platforms.windows.tools[].script[].varstring变量名（用于存储返回值）
platforms.windows.tools[].script[].objectstring对象引用（例如 mail、app）
platforms.windows.tools[].script[].progidstringProgID（仅用于 create 操作）
platforms.windows.tools[].script[].methodstring方法名（仅用于 call 操作）
platforms.windows.tools[].script[].propertystring属性名（仅用于 set/get 操作）
platforms.windows.tools[].script[].valuestring属性值（支持 ${param} 占位符）
platforms.windows.tools[].script[].argsarray方法参数（支持 ${param} 占位符）
platforms.windows.tools[].output_parserstring输出解析方式：last_result（返回最后一个操作的返回值）
platforms.windows.tools[].timeoutinteger超时时间（秒），默认 30

Linux 专有字段 ​

字段类型描述
platforms.linux.automationstring自动化类型：dbus
platforms.linux.servicestringDBus 服务名（例如 org.example.Mail）
platforms.linux.objectstringDBus 对象路径（例如 /org/example/Mail）
platforms.linux.interfacestringDBus 接口名（例如 org.example.Mail）
platforms.linux.tools[].methodstringDBus 方法名（例如 SendEmail）
platforms.linux.tools[].output_parserstring输出解析方式：json（假设返回 JSON）、string
platforms.linux.tools[].timeoutinteger超时时间（秒），默认 30

Android 专有字段 ​

字段类型描述
platforms.android.automationstring自动化类型：intent
platforms.android.packagestringAndroid 包名（例如 com.example.mail）
platforms.android.tools[].actionstringIntent Action（例如 com.example.MAIL_SEND）
platforms.android.tools[].extrasobjectIntent Extra 参数（支持 ${param} 占位符）
platforms.android.tools[].result_typestring结果获取方式：content_provider（Content Provider）、broadcast（广播）
platforms.android.tools[].result_uristringContent Provider URI（仅当 result_type=content_provider 时使用）
platforms.android.tools[].timeoutinteger超时时间（毫秒），默认 5000

iOS 专有字段 ​

字段类型描述
platforms.ios.automationstring自动化类型：url_scheme
platforms.ios.schemestringURL Scheme（例如 mailapp）
platforms.ios.tools[].url_templatestringURL 模板（支持 ${param} 占位符）
platforms.ios.tools[].result_typestring结果获取方式：app_group（App Groups）、clipboard（剪贴板）
platforms.ios.tools[].app_group_idstringApp Group ID（仅当 result_type=app_group 时使用）
platforms.ios.tools[].timeoutinteger超时时间（秒），默认 10

Web / SaaS 专有字段 ​

字段类型描述
platforms.web.automationstring自动化类型：restapi
platforms.web.base_urlstring所有 API 调用的基础 URL（例如 https://api.notion.com/v1）
platforms.web.authobject认证配置
platforms.web.auth.typestring认证类型：oauth2、api_key 或 bearer
platforms.web.auth.auth_urlstringOAuth 授权端点（仅用于 oauth2）
platforms.web.auth.token_urlstringOAuth 令牌端点（仅用于 oauth2）
platforms.web.auth.scopesarray所需的 OAuth 权限范围（仅用于 oauth2）
platforms.web.auth.token_placementstring令牌放置位置：header 或 query
platforms.web.auth.token_prefixstring请求头中的令牌前缀（例如 Bearer）
platforms.web.auth.env_varstring用于存放 API Key / Bearer 令牌的环境变量
platforms.web.auth.key_namestring请求头或查询参数名称（仅用于 api_key）
platforms.web.auth.key_placementstringheader 或 query（仅用于 api_key）
platforms.web.default_headersobject每个请求都会发送的请求头
platforms.web.tools[].endpointstringAPI 端点路径（追加到 base_url 之后）
platforms.web.tools[].methodstringHTTP 方法：GET、POST、PUT、PATCH、DELETE
platforms.web.tools[].bodyobject请求体模板（支持 ${param} 占位符）
platforms.web.tools[].query_paramsobjectURL 查询参数（支持 ${param} 占位符）
platforms.web.tools[].headersobject该工具特有的附加请求头
platforms.web.tools[].output_parserstringjson（默认）或 text
platforms.web.tools[].timeoutinteger超时时间（秒），默认 30

返回规范索引

Released under the Apache 2.0 License.

Copyright 2025-present AAI Protocol Contributors