SkillPack架构深度解析：从CLI到运行时，本地AI Agent如何被打包分发

SkillPack 是一个开源的本地 AI Agent 打包分发框架：它把 AI 技能（Skills）、提示词和内置运行时组装成一个可运行的本地 Agent 应用，让团队用几分钟就能打包并部署属于自己的本地 AI Agent。本文将带你完整走读 SkillPack 的三层架构——CLI 命令层、skillpack.json数据模型、多适配器运行时，以及最终如何压缩成一个 zip 分发给团队。

🗺️ 全局架构：三层结构一览

SkillPack 的架构可以概括为"一个数据模型 + 三层职责"：

┌──────────────────┐ │ server.ts │ 加载配置、启动适配器 └────────┬─────────┘ ┌──────────────────┼──────────────────┬──────────────────┐ ▼ ▼ ▼ ▼ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ ┌────────────────┐ │ WebAdapter │ │TelegramAdapter│ │ SlackAdapter │ │SchedulerAdapter│ └──────┬───────┘ └───────┬───────┘ └──────┬───────┘ └────────┬───────┘ └────────┬─────────┴──────────────────┴──────────────────┘ ▼ ┌────────────────┐ │ PackAgent │ 平台无关的 Agent 核心层 └────────────────┘

这套"中心 Agent + 多适配器"的星型结构是 SkillPack 架构最核心的设计：所有通道最终都汇聚到同一个PackAgent实例，Agent 本身完全不感知消息来自浏览器、Slack 还是 Telegram。

完整架构说明见 docs/architecture.md，运行时细节见 docs/runtime/runtime-architecture.md。

🧩 CLI 层：三个命令搞定创建、运行与打包

CLI 入口在 src/cli.ts，基于commander注册了三个子命令，覆盖了本地 AI Agent 从"出生"到"分发"的全生命周期：

skillpack create：交互式生成新 Pack

create命令走一条清晰的流水线（见 src/commands/create.ts）：

1. 解析目标目录，若已存在skillpack.json会先征求确认；
2. 若传入--config <path-or-url>，直接拉取本地或远程配置并校验（替代了旧版init命令）；
3. 否则交互式收集名称、描述、技能来源与提示词；
4. 保存skillpack.json，安装声明的技能，并把技能描述回写同步；
5. 复制 templates/start.sh 与 templates/start.bat 一键启动脚本。

技能来源支持三种格式：仓库简写（owner/repo）、完整仓库 URL、本地路径（./skills/my-skill），同一来源可一次性列出多个技能名。

skillpack run：一键启动运行时

run的行为设计得很"懒人友好"：

• 目标目录缺少skillpack.json时，会交互式补全并生成默认配置；
• 自动检测并安装缺失的远程技能（本地./skills/来源会跳过）；
• 调用startServer({ rootDir })启动运行时，成功后自动打开浏览器（默认http://127.0.0.1:26313）。

skillpack zip：轻量打包分发

zip命令的打包逻辑在 src/commands/zip.ts。它有一个关键取舍：不把运行时打进 zip。默认会先刷新安装配置中的技能（单个失败不阻塞其余），再同步描述后压缩；--skip-skill-install可跳过重装、直接打包现有skills/快照。

📦 核心数据模型：skillpack.json如何定义一个 Agent

skillpack.json是整个 Pack 的"根配置"，由 src/pack-config.ts 负责读写与校验。以仓库内置示例 examples/comic-explainer.json 为例：

{ "name": "Comic Explainer", "description": "Explains complex concepts to children through educational comics.", "version": "1.0.0", "prompts": [ "请生成一部 4-6 页的科普漫画，输出 PDF……" ], "skills": [ { "name": "baoyu-comic", "source": "……", "description": "知识漫画创作技能……" } ] }

各字段的实际作用比表面更"有戏"：

• prompts不只是文档：它是被打包的用户体验。只有一条时会预填进输入框；有多条时，前端首页会渲染成可点击的提示词卡片。
• skills[].source分两类：远程来源指向外部技能仓库，本地来源（./skills/开头）指向 Pack 内部目录，适合自定义技能开发测试。
• description会自动同步：技能安装后，src/skill-manager.ts 会递归扫描skills/目录下的SKILL.md，读取 frontmatter 中的name与description并回写进skillpack.json，保证元数据与真实技能一致。

安装环节，CLI 实际执行的是形如npx -y skills add <source> --agent openclaw --copy -y --skill <name>的子进程（见 src/skill-manager.ts），同来源的多个技能会被分组批量安装，安装目标固定为工作目录下的skills/。

⚙️ 运行时：PackAgent + 适配器多通道接入

运行时源码位于 src/runtime/，经tsup编译进 npm 包的dist/，不再有独立的服务端子项目。

startServer：服务器的总装车间

入口函数startServer在 src/runtime/server.ts，它依次完成：

1. 读取data/config.json运行时私有配置，环境变量OPENAI_API_KEY/ANTHROPIC_API_KEY具有更高优先级；
2. 构建 Express 应用并托管web/静态资源（优先 Pack 根目录，回退到 npm 包自带的 web/）；
3. 创建共享的PackAgent实例；
4. 按配置启动各适配器：Web 恒开，Telegram 配置了 token 才启动，Slack 需同时具备botToken与appToken，最后加载job.json启动调度器；
5. 监听HOST:PORT（默认127.0.0.1:26313，端口冲突时自动递增）。

API Key 的优先级链为：SKILLPACK_*环境变量 >data/config.json> 厂商默认环境变量（OPENAI_API_KEY等），这套设计让嵌入式宿主（如 Electron 应用）可以注入凭据而不落盘。

PackAgent：平台无关的 Agent 核心层

PackAgent（src/runtime/agent.ts）实现了IPackAgent接口，是架构的中枢：

• 内部维护Map<channelId, ChannelSession>，会话按通道懒创建——收到第一条消息才建会话，且完全隔离；
• 底层由@earendil-works/pi-coding-agent执行打包技能，PackAgent订阅其事件流并转发为标准化的AgentEvent（text_delta、tool_start、tool_end等 8 种类型）；
• 支持abort中断正在运行的会话、dispose销毁会话；
• 显式控制 System Prompt：新建会话时会读取 Pack 根目录的AGENTS.md（行为策略）与SOUL.md（人格语气），以固定结构注入最终 system prompt，优先级为"用户指令 > AGENTS.md > SOUL.md"，同时屏蔽宿主机器上的AGENTS.md、.pi/SYSTEM.md等文件——Pack 的行为完全由包内文件决定，与运行在哪台电脑上无关。这一机制详见 docs/agent-and-soul.md。

适配器层：一个接口接入四个通道

所有适配器统一实现PlatformAdapter接口（name/start(ctx)/stop()），定义在 src/runtime/adapters/types.ts：

细节上很有"本地部署"思维：Telegram 与 Slack 都选择长轮询 / Socket Mode 而非 webhook，无需任何公网入口；IM 侧只回传最终结果（Markdown 会转成平台语法），而 Web 端则完整流式渲染推理过程与工具调用卡片（由 web/ 前端通过持久 WebSocket 呈现）。

附件与文件交付也是多通道统一的：入站附件下载到data/sessions/<channelId>/attachments/，图片以 base64 直传模型"看图"；出站则注册了send_file自定义工具（src/runtime/tools/send-file-tool.ts），Agent 生成文件后各适配器分别以sendDocument、files.uploadV2、下载端点的方式送达用户。

📤 打包分发：一个 zip 如何在团队电脑上跑起来

SkillPack 的分发产物刻意做得"极简"：

<pack-name>/ ├── skillpack.json # Pack 配置 ├── job.json # 可选：随包分发的定时任务 ├── AGENTS.md # 可选：Pack 行为策略 ├── SOUL.md # 可选：Pack 人格 ├── skills/ # 已安装的技能 ├── start.sh # macOS / Linux 一键启动 └── start.bat # Windows 一键启动

启动脚本只有一行核心逻辑（见 templates/start.sh）：

npx -y @cremini/skillpack run .

这就是 SkillPack 分发架构的精妙之处：zip 里不含任何服务端代码，运行时在启动瞬间从 npm 现取。唯一前置条件是 Node.js ≥ 22.19.0。这意味着包体保持轻小、版本永远最新，而团队数据（API Key 存在本地data/config.json，不会被打进 zip）始终留在自己的机器上。

⏰ 定时任务：job.json让 Agent 按时上班

SkillPack 把定时任务单独拆到 Pack 根目录的job.json（而非运行时配置），因为它是可随包分发的——一个 zip 里可以预置好定时任务。结构示例（完整说明见 docs/cron/scheduled_task.md）：

{ "jobs": [ { "id": "morning-briefing", "cron": "0 9 * * 1-5", "prompt": "生成今日市场早报。", "notify": { "adapter": "telegram", "channelId": "telegram-1234567890" }, "enabled": true, "timezone": "Asia/Shanghai" } ] }

SchedulerAdapter在服务启动时加载这些任务，到点执行 prompt，并通过notify指定的通道把结果推送到指定 IM 会话。这也解释了为什么调度器被实现为一个"适配器"——它与 IM 通道共享同一套 Agent 事件通道，只是触发源从用户消息变成了时间。

🔌 扩展架构：四步接入新的 IM 平台

适配器模式让扩展成本极低，官方文档 docs/runtime/im-adapters.md 给出的步骤：

1. 新建src/runtime/adapters/xxx.ts；
2. 实现PlatformAdapter接口（name、start(ctx)、stop()）；
3. 在 src/runtime/server.ts 的适配器启动逻辑中按dataConfig.adapters.xxx条件启动；
4. 执行npm run build重新编译。

新适配器天然获得：会话隔离、统一命令系统（/clear、/restart、/shutdown）、附件下载、send_file出站文件等全部能力，只需关心"消息怎么进、结果怎么出"。

✅ 小结：这套架构好在哪

回顾 SkillPack 从 CLI 到运行时的完整链路，它回答了一个实际工程问题：如何让 AI Agent 像应用一样被打包、分发和信任。

• 数据模型收敛：skillpack.json一个文件声明一切，SKILL.md元数据自动同步保证声明与实现一致；
• 核心与通道解耦：PackAgent不感知平台，新增 IM 只需四步；
• 行为可移植：AGENTS.md/SOUL.md随包走，屏蔽宿主环境影响，在任何电脑上行为一致;
• 轻量分发：zip 不打包运行时，npx现取 + 本地 API Key，兼顾了轻量与隐私。

如果你想动手读源码，可以从 CLI 入口 src/cli.ts 追到 src/runtime/server.ts，再顺PackAgent到适配器目录走一圈，一两个小时就能把整条链路摸透。更多实战示例可参考 examples/ 目录下的多个 Pack 配置，以及 docs/development.md 中的开发指南。