编辑 .env: BASEURL, APIKEY, MODEL

SkillLite

English

一个轻量级的 AI Agent Skills 执行引擎，支持与任意 OpenAI 兼容的 LLM 集成。

🎯 为什么选择 SkillLite？

与 Claude Code Sandbox 的关系

Claude/Anthropic 在 2025 年 10 月发布了 Claude Code Sandbox，采用了与 Claude Code Sandbox 相同的底层技术栈：

• macOS: Seatbelt (sandbox-exec)
• Linux: bubblewrap + namespace

关键差异：

💡 总结：Claude Code Sandbox 验证了"原生系统级沙箱"是 AI Agent 安全执行的正确方向。SkillLite 提供了一个 LLM 无关、Rust 实现、更轻量 的替代方案，适合需要集成多种 LLM 或追求极致性能的场景。

🔐 核心创新：原生系统级安全沙箱

SkillLite 使用 Rust 实现的原生系统级沙箱，而非 Docker 或 WebAssembly：

• macOS: 基于 Seatbelt (sandbox-exec) 的内核级隔离
• Linux: 基于 Namespace + Seccomp 的容器级隔离

与其他方案的本质区别

┌─────────────────────────────────────────────────────────────────┐
│  其他方案                                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Docker    │  │   Pyodide   │  │  云端沙箱   │              │
│  │  (重量级)   │  │ (WebAssembly)│  │ (数据上传)  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  SkillLite 方案                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │              Rust 原生系统级沙箱                             ││
│  │  • 直接调用操作系统安全机制（Seatbelt/Namespace）            ││
│  │  • 零外部依赖，单二进制文件                                  ││
│  │  • 毫秒级冷启动，生产级性能                                  ││
│  │  • 代码和数据永不离开本机                                    ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

安全特性

✨ 特性

• 🔒 原生安全沙箱 - Rust 实现的系统级隔离，非 Docker/WebAssembly
• ⚡ 极致轻量 - 单二进制文件，毫秒级冷启动，零外部依赖
• 🏠 数据主权 - 纯本地执行，代码和数据永不离开本机
• 🔌 通用 LLM 支持 - 兼容所有 OpenAI API 格式的 LLM 提供商
• 📦 Skills 管理 - 自动发现、注册和管理 Skills
• 🧠 智能 Schema 推断 - 自动从 SKILL.md 和脚本代码推断输入参数 Schema
• 🔧 Tool Calls 处理 - 无缝处理 LLM 的工具调用请求
• 📄 丰富的上下文支持 - 支持 references、assets 等扩展资源

🚀 快速开始

1. 安装 Rust 沙箱执行器

本项目使用 Rust 编写的隔离沙箱来安全执行 Skills 脚本，需要先安装 Rust 环境并编译沙箱。

⚠️ 平台支持：目前仅支持 macOS 和 Linux，暂不支持 Windows。

安装 Rust（如果尚未安装）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装完成后，重新加载环境变量
source ~/.cargo/env

# 验证安装
rustc --version
cargo --version

编译沙箱执行器

# 进入 Rust 项目目录并编译
cd skillbox
cargo build --release

# 可选：安装到系统路径（推荐）
cargo install --path .

# 验证安装
skillbox --help

编译完成后，skillbox 二进制文件会位于：

• 如果使用 cargo install：~/.cargo/bin/skillbox
• 如果仅 cargo build：skillbox/target/release/skillbox

2. 环境配置

# 复制环境变量模板并填入 API 配置
cp .env.example .env
# 编辑 .env: BASE_URL, API_KEY, MODEL

3. 运行示例

python3 simple_demo.py

📁 项目结构

skillLite/
├── skillbox/              # Rust 沙箱执行器
├── skilllite/             # Python SDK
│   └── skilllite/
│       ├── manager.py     # SkillManager 核心管理器
│       ├── executor.py    # Skill 执行器
│       ├── loops.py       # Agentic Loop 实现
│       ├── tools.py       # 工具定义
│       └── ...
├── .skills/               # Skills 目录
│   ├── calculator/        # 计算器 Skill
│   ├── data-analyzer/     # 数据分析 Skill
│   ├── http-request/      # HTTP 请求 Skill
│   ├── text-processor/    # 文本处理 Skill
│   ├── weather/           # 天气查询 Skill
│   └── writing-helper/    # 写作助手 Skill
├── simple_demo.py         # 完整示例
├── simple_demo_v2.py      # 简化示例
└── simple_demo_minimal.py # 最小示例

💡 使用方法

基础用法

from openai import OpenAI
from skilllite import SkillManager

# 初始化 OpenAI 兼容客户端
client = OpenAI(base_url="https://api.deepseek.com/v1", api_key="your_key")

# 初始化 SkillManager
manager = SkillManager(
    skills_dir="./.skills",
    llm_client=client,
    llm_model="deepseek-chat"
)

# 获取工具定义（OpenAI 格式）
tools = manager.get_tools()

# 调用 LLM
response = client.chat.completions.create(
    model="deepseek-chat",
    tools=tools,
    messages=[{"role": "user", "content": "帮我计算 15 乘以 27"}]
)

# 处理工具调用
if response.choices[0].message.tool_calls:
    results = manager.handle_tool_calls(response)

支持的 LLM 提供商

🛠️ 创建自定义 Skill

每个 Skill 是一个包含 SKILL.md 的目录：

my-skill/
├── SKILL.md           # Skill 元数据和说明（必需）
├── scripts/           # 脚本目录
│   └── main.py        # 入口脚本
├── references/        # 参考文档（可选）
└── assets/            # 资源文件（可选）

SKILL.md 示例

---
name: my-skill
description: 我的自定义 Skill
version: 1.0.0
entry_point: scripts/main.py
---

# My Skill

这是 Skill 的详细说明...

📦 核心组件

• SkillManager - 管理 Skills 的发现、注册和执行
• SkillInfo - 单个 Skill 的信息封装
• AgenticLoop - 自动化的 Agent 循环执行
• ToolDefinition - OpenAI 兼容的工具定义
• SchemaInferrer - 智能参数 Schema 推断

🔌 OpenCode 集成

SkillLite 可以作为 MCP (Model Context Protocol) 服务器集成到 OpenCode，为其提供安全沙箱执行能力。

一键集成

# 安装 SkillLite（含 MCP 支持）
pip install skilllite[mcp]

# 一键初始化（自动检测最佳配置）
skilllite init-opencode

# 启动 OpenCode
opencode

init-opencode 命令会自动：

• 检测最佳启动方式（uvx、pipx、skilllite 或 python）
• 创建 opencode.json 配置文件
• 生成 .opencode/skills/skilllite/SKILL.md 使用说明
• 发现项目中的预定义技能

可用的 MCP 工具

安全特性

• 系统级沙箱：macOS Seatbelt / Linux Namespace 隔离
• 安全扫描：执行前静态分析代码
• 用户确认：危险代码需要明确批准
• Scan ID 验证：防止扫描和执行之间代码被篡改

详细文档请参阅 OpenCode 集成教程。

📄 License

MIT

本项目包含各种许可证的第三方依赖项。详见 THIRD_PARTY_LICENSES.md。

📚 文档

• 快速入门 - 安装和快速入门指南
• 环境变量参考 - 完整环境变量说明
• 项目架构 - 项目架构和设计
• 贡献指南 - 如何贡献代码