qing/blackbird

0 Fork 0

Files

T

qing 1b60ab0a2e 增加运维机器人单元

2026-07-27 21:39:53 +08:00

6.5 KiB

Raw Blame History

Aibox 扩展技能格式规范

本文档定义扩展技能的文件结构、接口约定和编写规范，供开发者与 AI 智能体参考。

概览

技能存放于 ~/.aibox/skills/ 目录，系统启动时自动扫描加载，运行时可通过 reload_skills 热重载。技能分为两种类型：

类型	识别方式	用途
可执行技能	非 `.md` 文件，具有可执行权限	命令行工具，通过 `run_command` 调用
Markdown 技能	以 `.md` 结尾	知识文档，AI 直接阅读并遵循

文件名仅允许字母、数字、下划线 _ 和连字符 -，以 _ 或 . 开头的文件会被忽略。

可执行技能

可执行技能是标准的命令行程序，系统仅依赖一个接口约定：必须支持 --help 参数。系统通过执行 <skill> --help 获取技能摘要和使用说明，不需要实现 --description、--parameters、--execute 等额外接口。

接口约定

系统按以下规则提取技能信息：

执行 <skill_path> --help，超时上限 10 秒
取 stdout 的第一个非空行作为摘要（若 stdout 为空则回退到 stderr）
完整的 --help 输出作为技能内容，供 search_skills 展示

因此，--help 输出的第一行必须是一句简洁的功能描述，后续内容是完整的参数说明和使用示例。

Python 技能模板

#!/usr/bin/env python3
"""
技能模块内部说明（可选，不影响系统识别）
"""

import argparse
import sys


def main():
    parser = argparse.ArgumentParser(
        description="一句话功能摘要 —— 这是 --help 的第一行输出",
        epilog="""
参数说明:
  -x, --xxx    参数含义说明
  -y, --yyy    另一个参数说明

使用示例:
  my_skill -x value           # 基本用法
  my_skill -x value -y 10    # 组合用法
""",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("-x", "--xxx", type=str, required=True, help="参数说明")
    parser.add_argument("-y", "--yyy", type=int, default=10, help="参数说明 (默认 10)")

    args = parser.parse_args()

    # --- 业务逻辑 ---
    print(f"执行结果: xxx={args.xxx}, yyy={args.yyy}")


if __name__ == "__main__":
    main()

关键要素

Shebang 行：Python 脚本使用 #!/usr/bin/env python3，Shell 脚本使用 #!/bin/bash。

argparse description：这是系统识别的技能摘要，必须是一句话，精准概括技能功能。它直接决定 AI 能否在 search_skills 时正确匹配到这个技能。

argparse epilog：包含两部分内容——参数说明和使用示例。使用 RawDescriptionHelpFormatter 保持排版原样输出。

错误处理：向 stderr 输出错误信息，以非零退出码退出。正常结果输出到 stdout。

# 正确做法
print("错误: 参数无效", file=sys.stderr)
sys.exit(1)

# 避免
print("错误: 参数无效")  # 会混入 stdout，污染正常输出

退出码约定：

退出码	含义
0	执行成功
1	参数错误或一般性失败
其他	自定义错误码

Shell 技能模板

#!/bin/bash
# 用法通过 --help 输出

if [ "$1" = "--help" ]; then
    echo "一句话功能摘要"
    echo ""
    echo "用法: my_skill [选项]"
    echo ""
    echo "选项:"
    echo "  -n NAME    指定名称"
    echo "  -h         显示帮助"
    echo ""
    echo "示例:"
    echo "  my_skill -n hello"
    exit 0
fi

# --- 业务逻辑 ---
echo "执行结果"

Markdown 技能

Markdown 技能是纯文档型技能，AI 阅读其内容后按指引行事，无需执行。

格式约定

一句话功能摘要（首行，# 前缀会被自动去除）

## 技能说明
详细的功能描述、使用场景、操作步骤...

## 注意事项
需要特别关注的点...

系统提取第一个非空行作为摘要。若首行以 # 开头（如 # 代码审查指南），会自动去除 # 前缀，取 代码审查指南 作为摘要。其余全部内容为技能正文。

适用场景

Markdown 技能适合不需要代码执行的知识型内容：操作规范、审查清单、决策指引、回答模板等。

部署流程

开发阶段

源码保存在项目的 skills/ 目录下，保留文件扩展名（.py、.sh、.md）便于开发维护。

安装到系统

部署到 ~/.aibox/skills/ 时需要去掉可执行技能的扩展名，并赋予执行权限：

# 手动安装
cp skills/my_skill.py ~/.aibox/skills/my_skill
chmod +x ~/.aibox/skills/my_skill

# 验证
~/.aibox/skills/my_skill --help

Markdown 技能保留 .md 扩展名直接复制。

通过 AI 安装

告诉 AI 使用 install_skill 工具，按指引操作：

使用 install_skill 工具安装 /path/to/my_skill.py

热重载

安装后调用 reload_skills 使新技能生效，无需重启服务：

{
  "type": "message",
  "content": "使用 reload_skills 重载技能"
}

调用方式

AI 智能体通过 search_skills 搜索技能，通过 run_command 执行技能：

// 1. 搜索
{"tool": "search_skills", "args": {"keyword": "邮件"}}

// 2. 执行
{"tool": "run_command", "args": {"command": "163mail --to user@example.com --subject 标题 --body 内容"}}

Markdown 技能不通过命令执行，AI 阅读 search_skills 返回的内容后直接遵循其中的指引。

编写建议

摘要要精准。description 是 AI 匹配技能的唯一线索。"温度转换工具 - 摄氏度转华氏度" 比 "一个转换工具" 好得多，因为 AI 能通过关键词准确命中。

参数命名要直观。优先使用有明确含义的长参数名（--channel、--temperature），短参数名（-c、-t）作为补充。

输出要结构化。结果输出到 stdout，错误输出到 stderr。多字段输出时每行一个字段，便于 AI 解析：

AIN0: +2.500000 V  (2500.000 mV)
AIN1: +1.234000 V  (1234.000 mV)

依赖要自包含。尽量使用标准库，若需要第三方库，在启动时检测并给出安装提示：

try:
    import requests
except ImportError:
    print("错误: 需要 requests 库，请执行: pip install requests", file=sys.stderr)
    sys.exit(1)

--help 要完备。包含参数说明和使用示例两部分。AI 通过阅读 --help 输出学会如何调用技能，信息越完整，AI 调用越准确。

6.5 KiB Raw Blame History Unescape Escape