数据不出本地:SkillPack本地AI Agent隐私安全机制全解析

原创2026-10-13 21:51:291,937 阅读

数据不出本地:SkillPack本地AI Agent隐私安全机制全解析

SkillPack 是一个开源的本地 AI Agent 打包部署工具,它把 AI 技能、提示词和运行时封装成一个可以在自己电脑或服务器上直接运行的 SkillPack 应用。它的核心卖点就是数据不出本地:你的业务资料、聊天记录、API Key 全部留在自己的环境里,团队还能直接从 Slack 和 Telegram 里使用这个 Agent。本文将带你完整拆解它背后的 6 大隐私安全机制。

为什么本地 AI Agent 更值得关注?

把敏感数据丢给第三方 SaaS 的 AI 服务,一直是企业使用大模型最大的顾虑:

  • 客户资料、内部文档会被上传到别人的服务器;
  • API Key、Token 等凭据散落在各处,难以统一管控;
  • 数据流向了哪里、是否被留存,往往无从查证。

SkillPack 的思路很直接:运行时跑在你自己的机器上,Web 界面、会话记录、配置文件全部落在本地磁盘,唯一出站的请求只有你主动配置的模型 API(OpenAI / Anthropic / Gemini)。

SkillPack 的本地运行架构一览

当你解压一个 SkillPack 并执行 start.sh(或双击 start.bat),实际发生的事是:

  1. 启动脚本通过 npx @cremini/skillpack run 拉起本地运行时;
  2. 服务器默认绑定在 127.0.0.1:26313,只接受本机访问;
  3. 浏览器自动打开本地 Web 界面,输入 API Key 即可开始对话;
  4. 配置了 Telegram / Slack Token 后,还能在 IM 里直接与 Agent 对话。

架构细节可以查看 docs/architecture.md 和 docs/runtime/runtime-architecture.md。

机制一:默认只监听 127.0.0.1,局域网都访问不到

在 server.ts 中,监听地址的默认值写得很清楚:

host = process.env.HOST || "127.0.0.1"

这意味着 SkillPack 的 HTTP + WebSocket 服务只回环到本机。同事的电脑即使在同一个办公网络,也无法直接访问你这个 Agent 的管理界面,从网络层面就杜绝了"顺手被扫到"的风险。需要对外提供服务时,必须显式设置 HOST / PORT 环境变量,属于"知情才开放"的设计。

机制二:API Key 与凭据只存本地 config.json

很多团队最头疼的是密钥管理。SkillPack 的做法是把所有凭据收敛到一个本地文件 data/config.json:

  • API Key:在左侧菜单的 "Provide Model Auth" 对话框中填写,由 api-key-dialog.js 负责交互,保存时写入本地文件,不经过任何中转服务;
  • OAuth 凭据:走 OAuth 模式(如 OpenAI Codex)时,凭据同样落到本地 config.json 的 _auth 字段,由 ConfigFileAuthBackend 读写,全部配置"一个文件装下";
  • IM Token:Telegram Bot Token、Slack 的 botToken / appToken、飞书 appId / appSecret 都只存在于本地配置文件中(见 im-adapters.md)。

值得一提的是,config.ts 定义了 SKILLPACK_API_KEY、SKILLPACK_BASE_URL 等环境变量覆盖机制——嵌入式宿主(如 Electron 应用)可以把 Token 注入子进程而不落盘,这在 docs/electron_app_integration.md 中有专门说明。对于想进一步收紧密钥暴露面的用户,这是一个很有价值的选项。

还有一个细节:打包分发时 data/ 目录不会被包含进 zip,也就是说你的 Key 只会跟着你的机器走,发给同事的 SkillPack 包是"净身出户"的。

机制三:会话记录全部本地持久化

你和 Agent 的每一次对话,都被 ConversationService 以结构化形式写入本地的 data/sessions/ 目录,按渠道(web / telegram / slack)分目录存放。

这带来两个好处:

  1. 可审计:所有历史消息就躺在磁盘上,随时可以人工检查、导出或删除;
  2. 无云端同步:不存在"对话被悄悄备份到厂商服务器"的问题,删掉目录就是彻底删除。

机制四:文件访问白名单,防目录穿越

本地 Agent 能读文件,天然存在"路径穿越"隐患。SkillPack 在 Web 端口的文件下载接口上做了严格校验:

  • web.ts 中的 resolveDownloadFilePath 会把请求路径解析后,强制检查它是否仍在 Pack 根目录内;
  • 底层的判定逻辑是 metadata.ts 的 isWithinDirectory,任何指向 ../ 或绝对路径越界的请求直接返回 403 Access denied。

也就是说,即使有人恶意构造 URL,也只能"看到"这个 Agent 工作目录里的文件,无法借机读取你系统上的其他内容。

机制五:系统提示词隔离,Pack 自管自足

agent.ts 在创建新会话时,只读取 Pack 根目录下的 AGENTS.md(策略规则)和 SOUL.md(人格风格),并显式屏蔽宿主机层面的 AGENTS.md、.pi/SYSTEM.md、APPEND_SYSTEM.md 对系统提示词的影响。

这个隔离机制的隐私意义在于:Agent 的行为完全由你自己打包的策略文件决定,不会意外继承宿主机上其他工具残留的提示词上下文,行为可预期、可复核。

机制六:无遥测、无数据上报

通读 src/ 源码可以发现一个"沉默"的事实:SkillPack 里没有任何 telemetry、analytics 或第三方上报 SDK。它不统计你的使用量,不上传对话内容,不收集设备指纹。注册表 registry.ts 记录的"本机正在运行哪些 Pack"信息,也只写在本机的 ~/.skillpack/registry.d/ 目录里,服务于多实例端口的本地发现。

检查项 SkillPack 的做法
网络监听 默认仅 127.0.0.1,不暴露局域网
凭据存储 本地 data/config.json,支持 env 注入不落盘
会话数据 本地 data/sessions/,无云同步
文件读取 限定在 Pack 根目录内,防路径穿越
提示词 Pack 级隔离,不受宿主机干扰
遥测 源码中无任何上报逻辑

Slack / Telegram 集成也会"暴露"吗?

很多人担心接了 IM 就要开公网 Webhook。SkillPack 的两个适配器都刻意避开了这一点:

  • Telegram(telegram.ts):采用主动轮询(polling),从你的机器向 Telegram 服务器拉消息,无需任何公网入口;
  • Slack(slack.ts):采用 Socket Mode,由你的机器与 Slack 建立出站长连接,同样不需要公网 Webhook。

也就是说,即使服务器在 NAT 之后、没有任何公网 IP,IM 集成照常工作——数据流的方向始终是"本地 Agent 主动出站",而不是"外部往你打洞"。

快速开始:5 分钟跑起一个私密 Agent

# 1. 解压示例 Pack 后,一键启动(需要 Node.js 22.19.0+)
./start.sh        # macOS / Linux
start.bat         # Windows

# 2. 浏览器自动打开 http://127.0.0.1:26313,左侧菜单填入 API Key 即可

# 3. 自己从零打包一个
npx @cremini/skillpack create

# 4. 打包分发给同事(不含你的密钥)
npx @cremini/skillpack zip

示例配置可以直接参考 examples/company-deep-research.json、examples/seo-audit-to-ppt.json。

总结

SkillPack 的隐私设计不是"宣称安全",而是一系列可以逐行验证的工程决策:本地回环监听、单一本地配置文件、本地会话存储、文件路径白名单、提示词隔离、零遥测。对希望在 Slack / Telegram 里拥有 AI 助手、又不想让数据离开自己环境的团队来说,它就是目前少数"开箱即私密"的本地 AI Agent 方案。想深入了解运行时内部设计,可以继续阅读 docs/runtime/runtime-architecture.md。

登录后查看全文
skillpack