Agent Skills多平台工程化实战：契约驱动的跨平台能力封装

1. 项目概述：当“Agent Skills”不再只是概念，而是可部署、可验证、可迭代的多平台能力模块

“Agent Skills”这个词最近在技术社区里出现的频率明显高了——不是作为论文里的抽象定义，也不是PPT上一闪而过的 buzzword，而是真实出现在某高校实验室的课程设计文档里、某家智能硬件公司的内部技术评审会上、甚至某位独立开发者的 GitHub 仓库 README 第一行。它指的不是某个具体模型，也不是某套框架，而是一类可复用、可组合、可跨环境调度的原子化能力单元：比如“从 PDF 中精准提取表格并转为 CSV”、“根据用户语音指令调用本地日历 API 创建会议”、“实时监听邮件附件中的发票图片，OCR 后自动填入财务系统”。这些能力本身不依赖大模型推理链路，但能被大模型调用、编排、纠错、重试——它们是 Agent 的“手”和“脚”，而不是“脑”。

我去年带过一个模拟项目X，目标是让一个轻量级本地 Agent 在 Windows 笔记本、树莓派4B 和 macOS M1 三台设备上，统一完成“每日晨会纪要生成”任务。核心难点不在 LLM 选型，而在如何让同一个技能（比如“解析 Zoom 录播字幕文件”）在不同系统上稳定运行：Windows 上路径分隔符是反斜杠，macOS 是正斜杠；树莓派没有 FFmpeg 预编译包，得自己编译；Zoom 字幕格式在不同客户端版本间有细微差异……最后我们没写三套代码，而是把“字幕解析”封装成一个带明确输入输出契约、内置环境自检、失败自动降级的 Skill 模块。上线后，这个模块被复用到另一个“会议录音转知识图谱”的项目中，只改了两行配置。

所以，“Agent Skills 多平台应用实战”这件事，本质是工程化落地的临门一脚：它不挑战模型上限，但直面真实世界的碎片化——操作系统、硬件架构、网络策略、权限模型、用户习惯。它适合三类人：一是刚学完 LangChain/LlamaIndex 想做点真东西的开发者，二是需要快速验证 Agent 落地价值的产品经理，三是正在搭建企业级 AI 工具链的架构师。你不需要从零造轮子，但必须亲手拧紧每一颗螺丝。

2. 核心设计思路：为什么必须放弃“一套代码打天下”，转而拥抱契约驱动的技能分层

2.1 技能不是函数，而是带生命周期的“微服务”

很多初学者一上来就想写个def extract_table_from_pdf(pdf_path)，然后发现：PDF 文件路径在 Windows 是C:\data\report.pdf，在 macOS 是/Users/xxx/report.pdf，在树莓派是/home/pi/data/report.pdf；更麻烦的是，有些 PDF 是扫描件，需要 OCR，而 OCR 引擎（Tesseract vs PaddleOCR）在 ARM64 和 x86_64 上的安装方式、依赖库版本、甚至内存占用都不同。如果硬塞进一个函数，很快就会变成满屏if sys.platform == "win32": ... elif platform.machine() == "aarch64": ...的意大利面条代码。

我们最终采用的方案，是把每个 Skill 定义为一个独立进程+标准化接口+声明式元数据的组合体。以“PDF 表格提取”为例：

• 独立进程：它是一个单独的 Python 脚本（pdf_table_skill.py），启动后监听本地 Unix Socket（Linux/macOS）或 Named Pipe（Windows），不与主 Agent 进程共享内存；
• 标准化接口：所有 Skill 统一接收 JSON 格式请求，字段固定为{"input": {"file_path": "...", "page_range": [0,5]}, "config": {"ocr_enabled": true}}；返回也固定为{"status": "success", "output": {"csv_content": "...", "table_count": 3}, "metadata": {...}}；
• 声明式元数据：每个 Skill 目录下必须有skill.yaml，内容包括：

  name: pdf_table_extractor version: 1.2.0 platforms: ["windows-x64", "darwin-arm64", "linux-aarch64"] dependencies: - python>=3.9 - tabula-py==2.10.0 # 注意：这里指定精确版本，避免 pip install 时自动升级引入不兼容变更 - tesseract>=5.3.0 # 但 tesseract 是系统级依赖，需在 install.sh 中处理 capabilities: input_formats: ["pdf"] output_formats: ["csv", "json"]

这个设计看似多了一层，实则解决了四个关键问题：

1. 环境隔离：Skill 进程崩溃不会拖垮主 Agent，重启成本极低；
2. 版本可控：skill.yaml中的dependencies是真实安装清单，不是 requirements.txt 的模糊描述；
3. 平台感知前置：platforms字段让 Agent 启动时就能过滤掉不支持当前系统的 Skill，避免运行时报错；
4. 契约即文档：前端调用方（无论是 LLM 还是人工测试）只需看skill.yaml和接口定义，无需读源码。

提示：我们曾试过用 Docker 封装 Skill，结果在树莓派上因内核版本太老无法运行 containerd；后来改用pyinstaller打包为单文件可执行程序（.exe/.app/.bin），配合skill.yaml声明依赖，实测下来更轻量、启动更快、兼容性更好。

2.2 多平台适配不是“if-else”，而是“环境指纹 + 预编译二进制”

“多平台”在这里不是指“写一次 Python 代码，到处运行”，而是指同一逻辑，在不同平台上有各自优化的实现路径。比如“音频转文字”这个 Skill：

• 在 macOS 上，我们调用系统自带的speech-to-textCLI 工具（基于 Core ML，离线、快、省电）；
• 在 Windows 上，调用 Windows.Media.SpeechRecognition API（需 .NET 运行时，但精度高）；
• 在树莓派上，由于算力有限，我们用 Whisper.cpp 编译的 ARM64 版本，量化为tiny.en.bin，内存占用压到 120MB 以内。

关键是怎么让 Agent 知道该调哪个？我们设计了一个轻量级环境指纹机制：

# agent_core/environment.py def get_platform_fingerprint(): return { "os": platform.system().lower(), # "windows", "darwin", "linux" "arch": platform.machine().lower(), # "amd64", "arm64", "aarch64" "cpu_cores": os.cpu_count(), "memory_gb": round(psutil.virtual_memory().total / (1024**3)), "has_gpu": is_nvidia_gpu_available(), # 检查 nvidia-smi 是否存在且有可用显存 "disk_free_gb": round(psutil.disk_usage("/").free / (1024**3)) }

Agent 启动时运行此函数，生成指纹（如{"os": "linux", "arch": "aarch64", "cpu_cores": 4, "memory_gb": 3}），再遍历所有已注册 Skill 的skill.yaml中platforms字段，匹配出linux-aarch64。匹配成功后，Agent 不是去执行 Python 源码，而是直接调用预编译好的pdf_table_skill-linux-aarch64二进制文件——这个文件是我们在 CI 流水线中，用 QEMU 模拟树莓派环境，用pyinstaller --onefile打包出来的，确保运行时零依赖。

这种模式彻底规避了“Python 代码跨平台”的幻觉。Python 本身跨平台，但它的生态（尤其是涉及系统调用、硬件加速、GUI 的部分）从来就不是真正跨平台的。我们承认这个事实，然后用工程手段绕过去。

2.3 技能编排不是“写 prompt”，而是“状态机 + 超时熔断”

LLM 调用 Skill 时，最怕什么？不是结果错，而是卡死、无响应、返回格式错乱。比如调用“发送邮件”Skill，如果 SMTP 服务器超时，LLM 不可能自己判断“等了 30 秒还没回，应该重试或换邮箱”，它只会干等或胡说。

我们的解法是：在 Agent 和 Skill 之间加一层技能网关（Skill Gateway），它是一个独立的、轻量的 Go 语言服务（因为 Go 的并发和超时控制极其成熟），职责非常清晰：

• 接收来自 LLM 的结构化调用请求（JSON）；
• 根据skill_name查找对应 Skill 的可执行路径和环境要求；
• 启动 Skill 进程，传入标准输入（stdin）；
• 设置严格超时（默认 15 秒，可 per-skill 配置）；
• 捕获 Skill 的 stdout/stderr，解析 JSON 响应；
• 如果 Skill 进程崩溃、超时、或返回非 JSON，网关立即返回标准化错误：

  {"status": "error", "code": "GATEWAY_TIMEOUT", "message": "Skill 'send_email' timed out after 15s"}

• 记录完整调用日志（含输入、输出、耗时、错误堆栈），供后续分析。

这个网关把“调用 Skill”这个动作，从一个不可控的黑盒，变成了一个有状态、有超时、有日志、可监控的白盒操作。LLM 只需理解GATEWAY_TIMEOUT这个 code，就能触发重试逻辑；运维人员看到日志，能立刻定位是 Skill 本身慢，还是网关配置错了超时时间。

注意：我们禁止 Skill 自行处理网络请求（如直接调用 requests.get）。所有外网访问必须通过网关的代理能力（网关内置 HTTP client，支持设置全局 timeout、retry、user-agent），这样既能统一管控，又能避免 Skill 因网络问题阻塞整个进程。

3. 核心技能拆解与实操：从零构建一个可跨平台运行的“截图识别文字”Skill

3.1 技能需求与边界定义：先画框，再填内容

“截图识别文字”听起来简单，但实际落地时边界模糊极易失控。我们一开始的需求是：“用户按快捷键截屏，Agent 自动识别图中文字，复制到剪贴板”。但很快发现几个陷阱：

• 截图来源多样：可能是全屏截图（prtsc）、活动窗口截图（alt+prtsc）、区域截图（Snip & Sketch / Shift+Cmd+4）、甚至手机投屏后的画面；
• 文字类型复杂：纯英文、中英混排、带数学公式的 PDF 渲染图、低对比度的手写笔记扫描件；
• 输出要求不一：有时要纯文本，有时要保留段落结构，有时要识别后自动搜索关键词。

因此，我们严格定义了这个 Skill 的输入契约和输出契约，写进ocr_screenshot_skill/skill.yaml：

name: ocr_screenshot version: 1.3.0 description: "Extract text from screenshot image files. Supports English and Chinese. Returns plain text with line breaks." platforms: ["windows-x64", "darwin-arm64", "linux-x64"] dependencies: - python>=3.9 - paddlepaddle-gpu==2.4.2 # GPU 版本，仅限 windows/linux；macOS 用 CPU 版本 - paddleocr==2.7.1 - pillow==10.2.0 input_schema: type: object properties: image_path: type: string description: "Absolute path to the screenshot image file (PNG/JPEG only)" language: type: string enum: ["en", "ch", "en_ch"] default: "en_ch" return_format: type: string enum: ["plain", "structured"] default: "plain" output_schema: type: object properties: status: type: string enum: ["success", "error"] text: type: string description: "Extracted text content. Empty if no text found." confidence: type: number description: "Average confidence score of all detected text lines (0.0 ~ 1.0)" metadata: type: object properties: ocr_engine: type: string processing_time_ms: type: integer

这个 YAML 文件就是 Skill 的“宪法”，它强制所有开发者（包括未来的你）必须遵守这个接口。如果你要加“识别公式”功能，不能偷偷改return_format，而要新增一个formula_enabled: boolean字段，并升级version到1.4.0，同时提供向后兼容的 fallback 逻辑。

3.2 平台差异化实现：一份逻辑，三套打包，零运行时分支

基于上述契约，我们为三个平台分别实现核心逻辑，但核心 OCR 算法逻辑完全一致，差异只在初始化和依赖加载：

• Windows 实现 (ocr_screenshot_skill/main_windows.py)：

  import os from paddleocr import PaddleOCR def init_ocr(): # Windows 上优先使用 GPU，显存充足 return PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=True, gpu_mem=2000) # 显存分配 2GB def run_ocr(image_path, lang, return_format): ocr = init_ocr() result = ocr.ocr(image_path, cls=True) # ... 后续文本拼接逻辑（完全跨平台）

• macOS 实现 (ocr_screenshot_skill/main_darwin.py)：

  import os from paddleocr import PaddleOCR def init_ocr(): # macOS M1/M2 的 Metal 加速对 PaddleOCR 支持不完善，强制 CPU # 且降低 batch_size 避免内存爆满 return PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=False, det_batch_size=1, rec_batch_size=1) def run_ocr(image_path, lang, return_format): ocr = init_ocr() result = ocr.ocr(image_path, cls=True) # ... 同样的文本拼接逻辑

• Linux 实现 (ocr_screenshot_skill/main_linux.py)：

  import os from paddleocr import PaddleOCR def init_ocr(): # Linux 服务器通常无 GUI，但可能有 NVIDIA GPU # 检查 CUDA 是否可用，动态选择 if os.path.exists('/usr/local/cuda'): return PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=True) else: return PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=False) def run_ocr(image_path, lang, return_format): ocr = init_ocr() result = ocr.ocr(image_path, cls=True) # ... 同样的文本拼接逻辑

关键点在于：所有平台的run_ocr函数体完全一样，只有init_ocr不同。这意味着业务逻辑（文本清洗、段落合并、空行处理）只需写一次，测试一次，就能保证三端行为一致。我们用 pytest 写了 20+ 个测试用例，覆盖各种截图场景（纯色背景、代码截图、微信聊天记录、PDF 渲染图），全部在 CI 中跑通。

3.3 打包与分发：用 PyInstaller 构建真正开箱即用的二进制

跨平台的核心，是让最终用户不用装 Python、不用 pip install、不用配环境变量。我们用 PyInstaller 实现这一点，但过程远比pyinstaller main.py复杂：

第一步：准备平台专用的虚拟环境

• 在 Windows 机器上，创建venv-win，pip install -r requirements-win.txt（含paddlepaddle-gpu）；
• 在 macOS M1 机器上，创建venv-mac，pip install -r requirements-mac.txt（含paddlepaddleCPU 版）；
• 在 Ubuntu 22.04 x64 机器上，创建venv-linux，pip install -r requirements-linux.txt（含paddlepaddle-gpu）。

第二步：编写平台专用的打包脚本以 macOS 为例（build-mac.sh）：

#!/bin/bash source venv-mac/bin/activate # 关键：告诉 PyInstaller 不要打包整个 site-packages，只打包明确需要的 pyinstaller \ --onefile \ --name ocr_screenshot-darwin-arm64 \ --add-data "models/;models/" \ # PaddleOCR 的模型文件需手动包含 --hidden-import=paddleocr \ --hidden-import=paddlepaddle \ --exclude-module=torch \ --exclude-module=sklearn \ main_darwin.py deactivate

第三步：验证与签名

• 在目标机器上运行生成的ocr_screenshot-darwin-arm64，传入测试截图，检查输出是否符合output_schema；
• macOS 上必须用codesign --sign "Developer ID Application: XXX" ocr_screenshot-darwin-arm64签名，否则 Gatekeeper 会拦截；
• Windows 上用signtool sign /f cert.pfx /p password ocr_screenshot-windows-x64.exe。

最终产出的不是.py文件，而是三个独立的、带签名的、双击即可运行的二进制：

• ocr_screenshot-windows-x64.exe
• ocr_screenshot-darwin-arm64
• ocr_screenshot-linux-x64

它们体积在 120~180MB 之间（主要来自 PaddleOCR 模型），但换来的是极致的易用性——用户下载后，只需把它放到skills/目录下，Agent 就能自动发现并调用。

3.4 Agent 端集成：如何让 LLM “知道”这个 Skill 并正确调用

LLM 不是万能的，它需要被“教育”才能正确使用 Skill。我们采用Tool Description + Example Call的双层提示策略：

Tool Description（写在系统提示词中）：

You are an AI assistant with access to external tools. One available tool is: - ocr_screenshot: Extract text from a screenshot image file. Input must be an absolute file path on the user's machine. Language can be "en", "ch", or "en_ch". Returns plain text. Example call: {"name": "ocr_screenshot", "arguments": {"image_path": "/Users/john/Pictures/Screenshots/Screen Shot 2024-03-15 at 10.22.33.png", "language": "en_ch"}}

Example Call（Few-shot 示例）：

User: 我刚截了一张微信对话图，路径是 C:\Users\Alice\Pictures\wechat.png，请把文字提出来。 Assistant: {"name": "ocr_screenshot", "arguments": {"image_path": "C:\\Users\\Alice\\Pictures\\wechat.png", "language": "en_ch"}}

注意两个细节：

1. 路径格式：在 Windows 示例中，我们用了双反斜杠C:\\Users\\...，这是 Python 字符串转义的要求，LLM 生成时会自动处理；
2. 绝对路径约束：我们严禁 LLM 生成相对路径（如./wechat.png），因为 Skill 进程的工作目录不确定。所有路径必须由 Agent 前端（如桌面应用）在调用前转换为绝对路径并注入。

Agent 收到 LLM 返回的 JSON 后，不直接执行，而是：

• 解析 JSON，校验name是否在已注册 Skill 列表中；
• 校验arguments是否符合skill.yaml中的input_schema（用jsonschema库验证）；
• 如果校验失败，返回错误给 LLM，让它重写；
• 如果校验通过，将请求转发给 Skill Gateway。

这套机制让 LLM 从“自由发挥”变成“按章办事”，大幅降低幻觉调用风险。

4. 实战部署与问题排查：我在三台设备上踩过的 7 个坑及解决方案

4.1 坑1：macOS 上 PyInstaller 打包后，PaddleOCR 报错 “No module named 'paddle'"

现象：在 macOS M1 上打包的ocr_screenshot-darwin-arm64运行时报ModuleNotFoundError: No module named 'paddle'，但在虚拟环境中直接运行python main_darwin.py完全正常。

根因：PyInstaller 默认不会打包paddlepaddle的 C++ 动态库（.so文件），而 PaddleOCR 初始化时会动态加载这些库。paddlepaddle的 wheel 包里，.so文件藏在paddle/fluid/core_avx.so这类路径下，PyInstaller 的自动分析无法识别这种间接引用。

解决方案：在build-mac.sh中显式添加--add-binary参数：

pyinstaller \ --onefile \ --name ocr_screenshot-darwin-arm64 \ --add-binary "venv-mac/lib/python3.9/site-packages/paddle/fluid/core_avx.so:paddle/fluid/" \ --add-binary "venv-mac/lib/python3.9/site-packages/paddle/fluid/core_noavx.so:paddle/fluid/" \ ...

实操心得：我们写了个小脚本find_paddle_so.py，自动扫描site-packages/paddle/fluid/下所有.so文件，并生成对应的--add-binary参数列表，避免手动遗漏。

4.2 坑2：树莓派上 Skill 启动极慢，10 秒才响应第一次调用

现象：在树莓派 4B（4GB RAM）上，ocr_screenshot-linux-aarch64启动后，首次调用耗时 12 秒，后续调用只要 200ms。

根因：PaddleOCR 的模型文件（约 150MB）在首次调用时才从磁盘加载到内存，而树莓派的 microSD 卡顺序读取速度仅 20MB/s，加载 150MB 需 7~8 秒，加上模型初始化，总耗时超 10 秒。

解决方案：在 Skill 进程启动时，就预热模型：

# main_linux.py 开头 if __name__ == "__main__": # 预热：加载模型到内存，但不执行 OCR ocr = init_ocr() print("Model preloaded, ready.") # 然后进入监听循环...

同时，Skill Gateway 启动时，会主动发送一个空请求{"image_path": "/dev/null", "language": "en"}（Skill 内部捕获此路径，直接返回空结果），触发预热。实测后，首次有效调用耗时降至 220ms。

4.3 坑3：Windows 上 Skill 调用失败，错误日志显示 “Access is denied”

现象：Agent 日志显示GATEWAY_ERROR: Skill 'ocr_screenshot' exited with code 1，但 Skill 自身无日志输出。

根因：Windows 权限模型导致。当 Agent 以普通用户权限运行，而 Skill 需要访问某些受保护路径（如C:\Program Files\下的文件）时，会触发 UAC 拦截，进程直接退出。

解决方案：在skill.yaml中增加permissions字段，并在 Skill Gateway 中强制检查：

permissions: - filesystem_read: ["C:\\Users\\*", "D:\\Screenshots\\*"] # 明确声明可读路径 - filesystem_write: ["C:\\Users\\*\\AppData\\Local\\Temp\\*"]

Gateway 启动时，会验证image_path是否在声明的filesystem_read范围内，如果不在，直接拒绝调用，返回PERMISSION_DENIED错误，而非让 Skill 崩溃。

4.4 坑4：多 Skill 并发调用时，GPU 显存溢出，一个 Skill 崩溃导致所有调用失败

现象：同时运行“截图 OCR”和“视频抽帧”两个 Skill，GPU 显存占用飙升至 100%，nvidia-smi显示 OOM，两个进程均退出。

根因：两个 Skill 都使用paddlepaddle-gpu，且都试图独占全部显存。

解决方案：在 Skill 初始化时，显式限制 GPU 显存使用：

# main_linux.py / main_windows.py def init_ocr(): # 为每个 Skill 分配固定显存，避免争抢 os.environ['FLAGS_fraction_of_gpu_memory_to_use'] = '0.3' # 只用 30% return PaddleOCR(..., use_gpu=True)

同时，在skill.yaml中增加resource_limits：

resource_limits: gpu_memory_mb: 2000 # 声明此 Skill 最多用 2GB 显存 cpu_cores: 2 memory_mb: 1500

Gateway 启动 Skill 前，会检查系统剩余资源是否满足resource_limits，不满足则排队或返回RESOURCE_UNAVAILABLE。

4.5 坑5：macOS 上截图路径含中文，Skill 读取文件失败

现象：用户截图保存在~/Desktop/会议纪要-20240315.png，Skill 报错FileNotFoundError。

根因：Python 的open()函数在 macOS 上对 UTF-8 路径的支持有历史问题，尤其当终端 locale 不是UTF-8时。

解决方案：在 Skill 入口处，强制设置 locale：

import locale locale.setlocale(locale.LC_ALL, 'en_US.UTF-8') # 或 'zh_CN.UTF-8'

更彻底的方案是：Agent 前端（桌面应用）在传递image_path前，先用urllib.parse.quote()对路径进行 URL 编码，Skill 接收后再urllib.parse.unquote()解码，确保字节流不丢失。

4.6 坑6：Skill Gateway 日志中大量 “Connection refused”，但 Skill 进程明明在运行

现象：Gateway 日志频繁报dial unix /tmp/skill-ocr.sock: connect: connection refused，但ps aux | grep ocr显示进程存在。

根因：Unix Socket 文件残留。当 Skill 进程异常退出（如被 kill -9），socket 文件/tmp/skill-ocr.sock不会被自动删除，Gateway 尝试连接旧 socket，自然失败。

解决方案：在 Skill 启动时，先清理旧 socket：

import os import socket sock_path = "/tmp/skill-ocr.sock" if os.path.exists(sock_path): os.unlink(sock_path) # 删除旧 socket 文件 # 然后创建新 socket server_socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) server_socket.bind(sock_path)

同时，Gateway 在连接失败后，等待 100ms 后重试最多 3 次，避免瞬时抖动导致失败。

4.7 坑7：LLM 生成的调用参数中，image_path是相对路径，Agent 未做转换直接转发，Skill 找不到文件

现象：LLM 返回{"image_path": "Screenshots/1.png"}，Gateway 转发后，Skill 在自己的工作目录下找，当然找不到。

根因：Agent 前端（如 Electron 桌面应用）未履行“路径标准化”职责。

解决方案：在 Agent 的 Skill 调用入口处，强制将所有image_path转为绝对路径：

import os from pathlib import Path def normalize_path(path_str): p = Path(path_str) if p.is_absolute(): return str(p.resolve()) else: # 假设相对路径基于用户主目录 return str((Path.home() / p).resolve()) # 调用前 args["image_path"] = normalize_path(args["image_path"])

实操心得：我们把这个函数做成 Agent 的通用工具，所有涉及文件路径的 Skill 调用都走这一层，一劳永逸。

5. 技能治理与演进：如何让 Skill 库越用越健壮，而不是越积越多越混乱

5.1 技能注册中心：用 SQLite 替代文件扫描，实现秒级发现

早期我们让 Agent 启动时遍历skills/目录，读取每个子目录下的skill.yaml。当 Skill 数量超过 50 个时，启动时间从 0.8 秒涨到 3.5 秒，因为要打开 50+ 个 YAML 文件。

升级方案：建立一个轻量级Skill Registry，本质是一个 SQLite 数据库skills.db，结构如下：

CREATE TABLE skills ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, version TEXT NOT NULL, platform TEXT NOT NULL, -- 'windows-x64', 'darwin-arm64', etc. binary_path TEXT NOT NULL, yaml_content TEXT NOT NULL, last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

Agent 启动时，只执行SELECT * FROM skills WHERE platform = ?，毫秒级返回所有可用 Skill。skills.db由一个独立的skill-manager工具维护：

• skill-manager register ./path/to/skill/：解析skill.yaml，校验契约，编译二进制（如果需要），插入数据库；
• skill-manager update ocr_screenshot 1.4.0：更新指定 Skill 的版本和二进制；
• skill-manager list --platform darwin-arm64：列出当前平台所有 Skill。

这个设计把“发现 Skill”这个 I/O 密集型操作，变成了一个简单的数据库查询，彻底解决启动慢问题。

5.2 技能健康度监控：不只是“能跑”，还要“跑得好”

一个 Skill “可用”不等于“好用”。我们定义了四个健康度指标，全部由 Skill Gateway 自动采集并上报：

每天凌晨，一个 cron job 会生成《Skill 健康日报》，邮件发送给负责人。例如，某天报告指出pdf_table_extractor的GATEWAY_TIMEOUT错误占比达 8%，进一步分析日志发现，是某批 PDF 文件加密了，而 Skill 没处理密码提示。于是我们快速发布1.2.1版本，增加密码检测和友好错误提示。

5.3 技能版本演进：语义化版本 + 自动迁移脚本

Skill 版本不是随意递增的。我们严格遵循 Semantic Versioning 2.0.0 ：

• MAJOR.MINOR.PATCH（如1.2.0→2.0.0）
• PATCH：仅修复 bug，向后兼容；
• MINOR：新增功能，向后兼容；
• MAJOR：不兼容变更（如修改input_schema）。

当发布MAJOR版本时，必须提供自动迁移脚本。例如，ocr_screenshot从1.2.0升级到2.0.0，input_schema中language字段从枚举["en","ch"]扩展为["en","ch","ja","ko"]，同时return_format新增"markdown"选项。那么2.0.0的发布包中，必须包含migrate-from-1.2.0.py：

# migrate-from-1.2.0.py def migrate_old_args(old_args): # 兼容旧版：如果 old_args 里没有 'return_format'，默认设为 'plain' if 'return_format' not in old_args: old_args['return_format'] = 'plain' # 兼容旧版：如果 'language' 是 'zh'，映射为 'ch' if old_args.get('language') == 'zh': old_args['language'] = 'ch' return old_args

Agent 在加载1.2.0的 Skill 时，如果检测到有2.0.0的迁移脚本，会自动调用它转换参数，再发给2.0.0的 Skill。这保证了用户无需修改任何业务代码，就能平滑升级。

5.4 技能沙箱：防止恶意或失控的 Skill 破坏系统

开放 Skill 生态，必然面临安全风险。我们为每个 Skill 进程启用Linux namespaces + cgroups（Windows/macOS 用等效机制）：

• PID namespace：Skill 进程只能看到自己及其子进程，看不到系统其他进程；
• Mount namespace：Skill 只能访问--ro-bind挂载的指定目录（如/home/user/Pictures），无法访问/etc、/root；
• cgroups v2：限制 Skill 最多使用 2 个 CPU 核心、1.5GB 内存、100MB/s 磁盘 IO；
• seccomp-bpf