App Skill 协议：让 App 主动暴露能力给 AI Agent

摘要

当 AI Agent 越来越强大时，我们面临一个核心问题：Agent 如何调用手机或电脑上的各种 App？本文提出了一种 App Skill 协议，模拟了如何让 App 主动暴露自己的能力给 Agent 调用，并以一个待办事项 App + Agent 作为实践案例。

---

1. 背景：Agent 与 App 的割裂

1.1 当前 Agent 的能力困境

现代 AI Agent 通常具备强大的内在能力：

• 代码编写与调试
• 互联网搜索
• 文件系统操作
• 浏览器自动化

但这些能力都是 Agent 自身携带的，而非与设备上的 App 深度集成。

1.2 现实需求

当我们对 Agent 说：

• "帮我设置明天早上9点的会议提醒" → 需要调用日历/待办 App
• "给老婆发封生日邮件" → 需要调用邮件 App
• "查看上周的会议记录" → 需要调用笔记/文档 App

这些看似简单的需求，实际上需要 Agent 与 数十个系统 App 进行交互。

1.3 现有方案的局限

方案	优点	缺点
URL Scheme	简单易用	碎片化，每个 App 自己定义
Shortcuts	系统级支持	需要用户手动配置
App API	功能完整	门槛高，需要开发者对接
Apple Intelligence	系统级集成	生态封闭

核心问题：缺乏一个 App 主动暴露能力、Agent 动态发现调用 的统一协议。

---

2. 核心思路：App Skill 协议

2.1 设计理念

我们模拟一种理想的调用模式：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Agent     │────▶│  Skill注册   │────▶│    App      │
│  (调用方)   │     │  (发现层)    │     │  (暴露方)    │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │  能力清单    │
                    │ (Manifest)  │
                    └─────────────┘

核心原则：

1. App 主动暴露：每个 App 声明自己有哪些能力
2. 标准化描述：统一格式描述能力、参数、返回值
3. Agent 动态发现：Agent 启动时从 App 获取可用能力

2.2 协议设计

能力清单 (App Manifest)

每个 App 暴露一个 JSON 清单，描述自己的能力：

{
  "app": {
    "id": "com.todoapp",
    "name": "待办事项",
    "version": "1.0"
  },
  "skills": [
    {
      "id": "add_todo",
      "name": "添加待办",
      "description": "创建一个新的待办事项",
      "parameters": {
        "title": {
          "type": "string",
          "required": true,
          "description": "待办标题"
        },
        "dueDate": {
          "type": "datetime",
          "required": false,
          "description": "截止日期"
        },
        "reminder": {
          "type": "datetime",
          "required": false,
          "description": "提醒时间"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "todoId": { "type": "string" }
        }
      }
    },
    {
      "id": "list_todos",
      "name": "列出待办",
      "description": "获取所有待办事项列表",
      "parameters": {},
      "returns": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "title": { "type": "string" },
            "dueDate": { "type": "datetime" },
            "isCompleted": { "type": "boolean" }
          }
        }
      }
    },
    {
      "id": "complete_todo",
      "name": "完成待办",
      "description": "标记待办事项为已完成",
      "parameters": {
        "id": {
          "type": "string",
          "required": true,
          "description": "待办事项ID"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" }
        }
      }
    },
    {
      "id": "delete_todo",
      "name": "删除待办",
      "description": "删除指定的待办事项",
      "parameters": {
        "id": {
          "type": "string",
          "required": true,
          "description": "待办事项ID"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" }
        }
      }
    }
  ]
}

调用协议

Agent 调用 App 能力时，通过统一的协议：

POST todoai://invoke
Content-Type: application/json

{
  "skill": "add_todo",
  "parameters": {
    "title": "跑步",
    "dueDate": "2026-03-22T21:00:00+08:00"
  }
}

---

3. 实践案例：待办 App + Agent

3.1 项目概述

我们构建了一个完整的 Demo：

• 待办 App (SwiftUI) ：macOS 原生应用，提供 CRUD 功能
• 本地 Agent (TypeScript) ：调用 LLM，理解自然语言，执行 App 能力 !

3.2 技术实现

App 端：URL Scheme 处理

// TodoApp.swift
struct TodoAppApp: App {
    @StateObject private var todoStore = TodoStore()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(todoStore)
                .onOpenURL { url in
                    handleSkillInvocation(url)
                }
        }
    }

    private func handleSkillInvocation(_ url: URL) {
        guard url.scheme == "todoai" else { return }

        switch url.host {
        case "invoke":
            // 解析 skill 名称和参数
            let skill = url.queryItem("skill")
            let params = url.queryItems // JSON 参数字典

            // 执行对应逻辑
            switch skill {
            case "add_todo":
                let title = params["title"]
                let dueDate = parseDate(params["dueDate"])
                todoStore.addTodo(TodoItem(title: title, dueDate: dueDate))
            // ...
            }
        }
    }
}

Agent 端：Skill 注册与调用

// todoTools.ts
const appSkills = [
  {
    name: "add_todo",
    description: "创建一个新的待办事项",
    parameters: {
      title: { type: "string", required: true },
      dueDate: { type: "string", required: false },
      reminder: { type: "string", required: false }
    }
  },
  // ...
];

async function invokeSkill(skillName: string, args: any): Promise<string> {
  const url = buildSkillURL("todoai://invoke", skillName, args);
  await execAsync(`open "${url}"`);
  return "执行成功";
}

3.3 效果演示

用户: "帮我创建明天晚上9点的跑步提醒"

Agent: (调用 LLM 解析意图)
🔧 执行技能: add_todo
   参数: {"title":"跑步","dueDate":"2026-03-22T21:00:00+08:00"}

结果: 待办 App 自动打开并创建待办

---

4. 协议优势

4.1 对 App 开发者

• 零门槛集成：只需声明能力清单，无需复杂 API
• 一次声明：App 更新时同步更新能力描述
• 权限控制：可定义哪些能力需要用户授权

4.2 对 Agent 开发者

• 动态发现：无需硬编码每个 App 的接口
• 标准化：统一的调用范式
• 可扩展：新增 App 只需读取其 manifest

4.3 对用户

• 自然交互：用自然语言指挥 App
• 跨 App 协作：Agent 可以组合多个 App 的能力
• 隐私可控：清晰的权限请求

---

5. 未来展望

5.1 系统级支持

未来操作系统可以内置这种协议：

• App 安装时自动注册 skill manifest
• 系统提供统一的发现 API
• Agent 可以查询设备上所有可用能力

5.2 生态演进

第一阶段：开发者手动集成 (当前 Demo)
    │
    ▼
第二阶段：App 内置 Manifest，系统解析注册
    │
    ▼
第三阶段：App Store 要求每 App 提供 Skill 清单
    │
    ▼
第四阶段：用户授权 + Agent 自主调用

5.3 竞品对标

方案	描述
Apple Intelligence	系统级，但生态封闭
Google Assistant	基于 intent，需开发者适配
Alexa Skills	语音为主，移动端弱
本协议 (App Skill)	通用协议，开放生态

---

6. 技术要点总结

1. URL Scheme：作为调用的传输层，简单可靠
2. JSON Manifest：标准化能力描述
3. 时区处理：统一使用 UTC+8 本地时间
4. Function Calling 兼容：通过 prompt 引导 LLM 输出 JSON 格式

---

7. 源码与扩展

本 Demo 完整源码：

• todo-app/ - 待办事项 App (SwiftUI)
• todo-agent/ - 本地 Agent (TypeScript)
• github.com/jhon353/App…

扩展方向：

• 支持更多 App（日历、邮件、文件）
• 实现系统级 Skill 注册中心
• 添加权限控制和用户授权流程

---

结语

App Skill 协议可能是未来 AI Agent 与设备 App 交互的重要范式。本文通过一个简单的待办 Demo，模拟了这一协议的核心理念：让 App 主动暴露能力，让 Agent 动态发现功能用。

这不仅是技术方案，更是我们对 AI 时代人机交互的一次思考。