230 lines
6.5 KiB
Markdown
230 lines
6.5 KiB
Markdown
# Aibox 扩展技能格式规范
|
||
|
||
本文档定义扩展技能的文件结构、接口约定和编写规范，供开发者与 AI 智能体参考。
|
||
|
||
## 概览
|
||
|
||
技能存放于 `~/.aibox/skills/` 目录，系统启动时自动扫描加载，运行时可通过 `reload_skills` 热重载。技能分为两种类型：
|
||
|
||
| 类型 | 识别方式 | 用途 |
|
||
|------|---------|------|
|
||
| 可执行技能 | 非 `.md` 文件，具有可执行权限 | 命令行工具，通过 `run_command` 调用 |
|
||
| Markdown 技能 | 以 `.md` 结尾 | 知识文档，AI 直接阅读并遵循 |
|
||
|
||
文件名仅允许字母、数字、下划线 `_` 和连字符 `-`，以 `_` 或 `.` 开头的文件会被忽略。
|
||
|
||
---
|
||
|
||
## 可执行技能
|
||
|
||
可执行技能是标准的命令行程序，系统仅依赖一个接口约定：**必须支持 `--help` 参数**。系统通过执行 `<skill> --help` 获取技能摘要和使用说明，不需要实现 `--description`、`--parameters`、`--execute` 等额外接口。
|
||
|
||
### 接口约定
|
||
|
||
系统按以下规则提取技能信息：
|
||
|
||
1. 执行 `<skill_path> --help`，超时上限 10 秒
|
||
2. 取 stdout 的第一个非空行作为**摘要**（若 stdout 为空则回退到 stderr）
|
||
3. 完整的 `--help` 输出作为技能**内容**，供 `search_skills` 展示
|
||
|
||
因此，`--help` 输出的第一行必须是一句简洁的功能描述，后续内容是完整的参数说明和使用示例。
|
||
|
||
### Python 技能模板
|
||
|
||
```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。
|
||
|
||
```python
|
||
# 正确做法
|
||
print("错误: 参数无效", file=sys.stderr)
|
||
sys.exit(1)
|
||
|
||
# 避免
|
||
print("错误: 参数无效") # 会混入 stdout，污染正常输出
|
||
```
|
||
|
||
**退出码约定**：
|
||
|
||
| 退出码 | 含义 |
|
||
|--------|------|
|
||
| 0 | 执行成功 |
|
||
| 1 | 参数错误或一般性失败 |
|
||
| 其他 | 自定义错误码 |
|
||
|
||
### Shell 技能模板
|
||
|
||
```bash
|
||
#!/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
|
||
一句话功能摘要（首行，# 前缀会被自动去除）
|
||
|
||
## 技能说明
|
||
详细的功能描述、使用场景、操作步骤...
|
||
|
||
## 注意事项
|
||
需要特别关注的点...
|
||
```
|
||
|
||
系统提取第一个非空行作为摘要。若首行以 `#` 开头（如 `# 代码审查指南`），会自动去除 `#` 前缀，取 `代码审查指南` 作为摘要。其余全部内容为技能正文。
|
||
|
||
### 适用场景
|
||
|
||
Markdown 技能适合不需要代码执行的知识型内容：操作规范、审查清单、决策指引、回答模板等。
|
||
|
||
---
|
||
|
||
## 部署流程
|
||
|
||
### 开发阶段
|
||
|
||
源码保存在项目的 `skills/` 目录下，保留文件扩展名（`.py`、`.sh`、`.md`）便于开发维护。
|
||
|
||
### 安装到系统
|
||
|
||
部署到 `~/.aibox/skills/` 时需要去掉可执行技能的扩展名，并赋予执行权限：
|
||
|
||
```bash
|
||
# 手动安装
|
||
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` 使新技能生效，无需重启服务：
|
||
|
||
```json
|
||
{
|
||
"type": "message",
|
||
"content": "使用 reload_skills 重载技能"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 调用方式
|
||
|
||
AI 智能体通过 `search_skills` 搜索技能，通过 `run_command` 执行技能：
|
||
|
||
```json
|
||
// 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)
|
||
```
|
||
|
||
**依赖要自包含**。尽量使用标准库，若需要第三方库，在启动时检测并给出安装提示：
|
||
|
||
```python
|
||
try:
|
||
import requests
|
||
except ImportError:
|
||
print("错误: 需要 requests 库，请执行: pip install requests", file=sys.stderr)
|
||
sys.exit(1)
|
||
```
|
||
|
||
**`--help` 要完备**。包含参数说明和使用示例两部分。AI 通过阅读 `--help` 输出学会如何调用技能，信息越完整，AI 调用越准确。
|