AI编程实战之API与AI Skill基础

学习目标

这篇笔记主要解决三个问题：

1. API 是什么，一次接口调用通常包含哪些内容；
2. AI Skill 是什么，它与 API 有什么区别；
3. 如何把 API、业务规则和 AI 组合成可重复使用的工作流。

文中以发票识别为例进行说明。示例只展示通用思路，实际开发时仍要以所用平台的接口文档、计费规则和数据合规要求为准。

一、先理解API

API 可以理解为软件对外开放的一套调用规则。调用方按照约定提交数据，服务方完成处理，再按照约定返回结果。

例如，发票识别 API 的过程可以简化为：

上传发票图片
-> 服务端验证身份和文件格式
-> OCR服务识别票面内容
-> 返回发票号码、日期、金额等字段

这里的重点不是“联网调用了某个功能”，而是双方提前约定了输入、输出和错误处理方式。常见内容包括：

• 接口地址：请求发往哪里；
• 请求方法：如 GET、POST；
• 身份验证：如 API Key、Token 或签名；
• 请求参数：提交哪些字段，格式是什么；
• 返回数据：成功时返回什么；
• 错误信息：失败原因及错误码；
• 调用限制：频率、并发量、文件大小和计费方式。

以一个虚构的发票识别接口为例：

POST /v1/invoices/recognize
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "image_url": "https://example.com/invoice.jpg"
}

成功时可能返回：

{
  "success": true,
  "invoice_code": "示例号码",
  "amount": 128.50
}

这只是结构示例，不能直接用于真实服务。开发时要严格按照对应平台的官方文档填写地址、字段和鉴权信息。

二、API返回结果不等于业务完成

接口调用成功，只能说明服务端接受并处理了请求，不代表结果一定满足业务要求。

以发票识别为例，还需要继续检查：

• 文件是否重复上传；
• 票据类型是否受支持；
• 金额、日期等关键字段是否缺失；
• 字段格式是否需要统一；
• 低置信度结果是否需要人工复核；
• 接口超时后能否安全重试；
• 原文件和识别结果怎样保存、脱敏与删除。

因此，一个可用的软件通常还要在 API 外面增加校验、日志、重试和人工复核机制：

用户上传文件
-> 检查格式和大小
-> 调用识别API
-> 校验返回字段
-> 标记异常结果
-> 人工复核
-> 导出Excel

API 提供的是能力，业务程序负责把能力变成可靠的流程。

三、什么是AI Skill

AI Skill 可以理解为交给 AI 使用的一组任务说明和配套资源。它通常会描述：

• 什么情况下使用；
• 需要接收哪些输入；
• 按什么步骤执行；
• 可以调用哪些工具、脚本或 API；
• 输出应采用什么格式；
• 遇到异常时怎样停止、提示或回退。

不同 AI 平台对 Skill 的名称、目录结构和加载方式可能不同，因此它目前不能简单看成一种完全统一的行业格式。有的平台用 Markdown 编写说明，有的平台把它称为工具、插件、函数或工作流。

一个概念化的 Skill 说明可以写成：

# 发票整理

## 适用场景
用户需要批量识别发票并生成Excel汇总表。

## 执行步骤
1. 检查文件类型和数量。
2. 调用发票识别API。
3. 校验号码、日期、金额和税额。
4. 将异常记录交给用户复核。
5. 生成Excel文件。

## 限制
- 不在日志中记录完整密钥。
- 不自动修改无法确认的金额。
- 接口失败时保留原文件并说明原因。

这段说明本身不会产生识别能力。真正执行任务时，它仍然需要程序、工具或 API 的支持。

四、API与Skill有什么区别

对比项	API	AI Skill
核心作用	提供可调用的软件能力	告诉AI怎样完成一类任务
输入方式	结构化参数为主	自然语言、文件或结构化数据
输出方式	按接口协议返回	按任务要求组织最终结果
执行范围	通常完成一个明确操作	可以串联多个步骤和工具
稳定性来源	接口协议、程序校验和服务质量	清晰指令、可靠工具、测试与边界控制
是否可以独立工作	可以被普通程序直接调用	通常依赖AI平台及其可用工具

二者不是替代关系。比较合理的组合是：

自然语言需求
-> AI理解任务
-> Skill提供执行步骤
-> 程序或API完成具体操作
-> Skill检查并整理结果
-> AI向用户说明执行情况

五、用发票识别案例理解两种开发方式

传统软件通常由界面直接触发固定程序：

上传界面
-> Python业务代码
-> 发票识别API
-> 字段校验
-> 导出Excel

加入 AI 和 Skill 后，入口可以更灵活：

用户提出需求并提供文件
-> AI判断任务类型
-> 加载发票整理Skill
-> 调用现有Python程序和识别API
-> 检查异常数据
-> 输出Excel和处理说明

后一种方式并不意味着原来的程序可以删除。恰恰相反，文件解析、接口调用、字段校验和 Excel 导出仍应由可测试的程序完成。AI 更适合负责理解需求、选择流程、解释异常和组织输出。

这也说明，已有的 Python-office自动化办公开源项目学习笔记 中的程序能力，可以继续封装为 AI 可调用的工具；而 发票识别案例 中的校验、成本和合规要求，则应该成为 Skill 的执行边界。

六、怎样设计一个实用的Skill

1. 一次只解决一类问题

“处理所有办公任务”范围太大，AI 很难稳定选择步骤。可以先拆成：

• PDF 转 Word；
• 发票识别并汇总；
• Word 批量替换；
• Excel 数据清洗。

每个 Skill 的职责越明确，越容易测试和维护。

2. 写清输入与输出

不要只写“帮我处理发票”，还要说明支持的文件类型、单次数量、必填字段以及最终输出格式。

输入：PDF、JPG或PNG格式的发票文件
输出：Excel汇总表、异常记录表、处理结果说明

3. 把关键规则交给程序

固定且可判断的规则应尽量写进程序，例如：

• 文件大小不能超过限制；
• 金额必须是合法数字；
• 同一张发票不能重复入表；
• 缺少关键字段时必须标记异常。

AI 可以解释规则，但不应靠临时推理代替所有程序校验。

4. 明确失败边界

Skill 应说明哪些情况可以重试，哪些情况必须停止：

• 网络超时：可以按限制重试；
• 身份验证失败：停止并检查配置；
• 文件损坏：提示用户更换文件；
• 关键字段不确定：保留原值并请求人工复核；
• 导出失败：保留中间结果，避免重复计费调用。

5. 保护密钥和业务数据

API Key 不应直接写入文章、前端代码或 Git 仓库。通常应放在服务端环境变量或专用密钥管理服务中，并限制权限、设置调用额度、定期轮换。

发票、合同等文件可能包含个人或企业敏感信息。上传第三方服务前，应确认数据用途、保存期限、删除机制和服务条款，不使用无权处理的文件进行测试。

七、上下文很长时怎样保持任务稳定

AI 能读取的上下文并不是无限的。把大量文件、规则和历史对话一次性塞入任务，容易让重点被稀释，也会增加处理成本。

更稳妥的办法是分阶段执行：

第一步：确认需求和文件范围
第二步：提取并校验数据
第三步：汇总异常项
第四步：生成最终文件
第五步：记录处理结果

每个阶段只保留下一步真正需要的信息，并把已经确认的结论整理成简短记录。对于长任务，还可以设置检查点：先让用户确认识别字段和样例结果，再继续批量处理。

八、从一个工作步骤开始积累

建设 AI Skill 不需要一开始就设计庞大的自动化系统。更实际的顺序是：

1. 找出每天重复且规则相对明确的工作；
2. 先用 Python 或现有工具把核心操作跑通；
3. 为程序补上输入检查、错误处理和日志；
4. 再写 Skill，告诉 AI 何时以及怎样调用；
5. 用真实但已脱敏的样本测试；
6. 根据失败记录逐步补充规则。

经过多次验证后，一个小工具才会逐渐成为可复用的工作流。Skill 的价值不在于说明写得多，而在于能否让同一类任务被稳定、清楚地重复执行。

九、本篇小结

API 是软件能力的标准化入口，Skill 是 AI 执行任务时使用的说明、步骤和资源集合。API 解决“具体能力怎样调用”，Skill 解决“面对一个任务应该怎样组织这些能力”。

实际开发中，应让程序和 API 承担确定性操作，让 AI 负责理解需求、选择流程和解释结果。同时要保留校验、异常处理、人工复核与数据保护机制。先做好一个小场景，再逐步积累，才能把 AI 自动化从演示变成真正可用的工具。

技术指导来自：Python4Office