SkillLite 多入口架构实战：CLI / Python SDK / MCP / Desktop / Swarm 一页理清

摘要

SkillLite 是轻量级 AI Agent Skills 执行引擎：同一套 Rust workspace 拆分多 crate，向上提供「开箱即用的 Agent 产品」与「可嵌入的安全执行内核」。集成方既可通过终端 CLI 与 MCP 接入 IDE，也可在 Python 中调用 scan_code、execute_code、run_skill 等 API。本文用双层产品架构图与 Python 调用时序图建立心智模型，并给出可直接运行的 SDK 示例代码，帮助读者在 10 分钟内判断该用哪条入口、依赖哪些组件。

---

目录

• 一、为什么需要「多入口」
• [二、双层产品：Agent 与 Core](#二、双层产品：Agent 与 Core)
• 三、五类入口对照表
• [四、Workspace 与依赖方向](#四、Workspace 与依赖方向)
• [五、Python 集成：执行路径与示例代码](#五、Python 集成：执行路径与示例代码)
• [六、MCP 与 Desktop、Swarm 的选型](#六、MCP 与 Desktop、Swarm 的选型)
• 七、小结
• 参考与链接

---

一、为什么需要「多入口」

AI 应用集成场景差异很大：

• 个人开发者需要终端里一条命令跑通 chat 与技能；
• IDE 用户希望用 MCP 把「列技能、跑技能、扫代码」暴露给编辑器里的模型；
• Python 服务要把沙箱执行嵌进现有后端，而不必重写 Rust；
• 桌面用户偏好图形界面与托盘常驻；
• 多机协作需要发现邻居节点并路由任务。

若每种场景都单独造轮子，安全策略与技能协议又会分裂。SkillLite 的做法是 一个二进制能力集 + 多种薄入口：共享同一套沙箱、扫描与 Skills 语义，按场景选择 CLI、stdio MCP、Python 子进程或 IPC、Tauri 外壳、Swarm 守护进程。

---

二、双层产品：Agent 与 Core

官方文档用一张图区分上层 Agent 与底层 Core（引用自 docs/zh/ARCHITECTURE.md 的表述）：
SkillLite Core（底层引擎）
沙箱执行 + 安全扫描 + Skills + MCP 等
定位：可被任意 agent 框架集成
编译：skilllite-sandbox（轻量 binary）
SkillLite Agent（上层产品）
chat / planning / memory / tools
定位：开箱即用的 AI 助手
编译：skilllite（full binary）

一句话：Agent 是 Core 的「第一个客户」与参考实现；第三方框架也可以只集成 Core，自研对话与规划层。

---

三、五类入口对照表

下表与 docs/zh/ENTRYPOINTS-AND-DOMAINS.md 一致，便于选型时快速扫描：

入口	是什么	依赖的组件（概要）	适用场景
CLI	主二进制 skilllite	core、sandbox、commands；可选 executor、agent、swarm	终端、脚本、CI、全功能本地使用
Python	python-sdk + IPC 或子进程	本机已安装的 skilllite；可选 skilllite serve	Python 应用、框架桥接、自动化
MCP	skilllite mcp	与主二进制相同（skilllite 包内 MCP 模块）	Cursor、VS Code 等 MCP 客户端
Desktop	skilllite-assistant（Tauri）	编译时 core；运行时 需系统已有 skilllite	非命令行用户、托盘与图形会话
Swarm	skilllite swarm	skilllite-swarm；可与 agent 能力配合	mDNS 发现、P2P 任务路由、技能 Gossip

冷知识 ：轻量 skilllite-sandbox 二进制适合「只要沙箱 + MCP、不要完整 agent」的嵌入场景；与全量 skilllite 的 feature 组合见仓库 Cargo.toml 与架构文档。

---

四、Workspace 与依赖方向

用文字版依赖链帮助读者建立「调用下去会经过谁」的印象（摘自架构文档的归纳）：

CLI / MCP / stdio_rpc
  → skilllite-commands
  → skilllite-agent（启用 agent 时）
  → skilllite-executor
  → skilllite-sandbox
  → skilllite-core

原则 ：Core 不依赖上层；Sandbox 提供执行隔离；Agent 在 Core 之上叠加对话、规划与工具扩展。Python SDK 不链接 Rust，运行时通过子进程或 JSON-RPC 调用已安装的二进制，从而降低语言生态耦合。

---

五、Python 集成：执行路径与示例代码

5.1 时序图（IPC 优先 vs 子进程回退）

execute_code 在设置 SKILLLITE_USE_IPC=1 且 skilllite serve 可用时，可走长连接减少重复冷启动；否则回退为对 skilllite exec 的子进程调用（逻辑见 python-sdk/skilllite/api.py）。
skilllite 二进制 skilllite serve（可选） skilllite SDK Python 应用 skilllite 二进制 skilllite serve（可选） skilllite SDK Python 应用 alt [IPC 客户端可用] [子进程回退] execute_code(language, code, sandbox_level=3) client.exec(tmpdir, script_name, ...) JSON-RPC output, exit_code skilllite exec ... --sandbox-level N stdout / stderr dict(success, text, exit_code, ...)

5.2 最小可运行示例

安装与 PATH 配置请遵循项目 README.md 与 docs/zh/GETTING_STARTED.md。示例如下：

from skilllite import execute_code, scan_code

# 典型：先扫描再执行（生产环境应按 SDK 约定处理 confirmed / scan_id）
snippet = """
x = 1 + 2
print("result:", x)
"""

scan_result = scan_code(language="python", code=snippet)
print("scan:", scan_result.get("success"), scan_result.get("scan_id"))

exec_result = execute_code(
    language="python",
    code=snippet,
    confirmed=False,
    scan_id=None,
    sandbox_level=3,  # 1=无沙箱, 2=仅沙箱, 3=沙箱+扫描
)
print("exec success:", exec_result["success"])
print("exit_code:", exec_result["exit_code"])
print("output:", exec_result["text"])

5.3 sandbox_level 语义（与源码 docstring 一致）

值	含义
1	无沙箱
2	仅沙箱
3	沙箱 + 扫描（默认较安全）

run_skill 同样接受 sandbox_level、allow_network 等参数，适合「整包 SKILL.md 技能」而非单文件脚本，具体见 python-sdk/skilllite/api.py 中的函数说明。

5.4 与 LangChain 的衔接

仓库提供独立包 langchain-skilllite/ （SkillManager、SkillLiteTool 等），便于把技能列表与执行封装成 Agent 工具；版本与用法以该目录内 pyproject.toml 与源码为准。

---

六、MCP、Desktop、Swarm 的选型

• MCP ：在 Cursor 等客户端中配置启动命令为 skilllite mcp（stdio），即可暴露 list_skills、run_skill、scan_code、execute_code 等工具，适合「模型驱动开发」工作流。
• Desktop ：适合需要图片附件 、会话管理与图形界面的用户；注意运行时仍依赖本机 skilllite 二进制。
• Swarm ：监听地址默认多为回环（如 127.0.0.1:7700），局域网暴露需显式绑定并配置 SKILLLITE_SWARM_TOKEN ，客户端携带 Authorization: Bearer，避免未授权访问。

---

七、小结

• SkillLite 用 双层产品 + 多入口 覆盖从「个人终端」到「Python 服务」再到「IDE / 桌面 / 组网」的路径。
• 依赖方向清晰 ：集成方应优先理解 sandbox → core 边界，再决定是否使用完整 Agent。
• Python SDK 是薄桥接：能力来自本机二进制；IPC 可优化高频调用路径。

---

参考与链接

• 架构详解：docs/zh/ARCHITECTURE.md
• 入口与能力域：docs/zh/ENTRYPOINTS-AND-DOMAINS.md
• 快速开始：docs/zh/GETTING_STARTED.md
• 开源仓库：https://github.com/EXboys/skilllite