# SkillShelf 安全与信任边界

本说明适用于当前 10 包 `0.2.1` 本地候选。公开目标为 npm `@llx17669475` 与 [Lilongxi0507/skillshelf](https://github.com/Lilongxi0507/skillshelf)；本候选仍未发布。本文不是 npm 已上架、独立安全审计或跨平台验收的证明。

## 三条独立的信任边界

1. **取得 CLI**：npm/npx 获取你选择的 CLI 及依赖。你仍需信任发布账号、npm 供应链和本机执行环境。SkillShelf CLI 不提供安装生命周期脚本，不在安装时配置 Agent、下载技能或运行技能代码。
2. **取得技能**：CLI 只把审定命名空间下、目录或项目锁固定确切版本的 tarball 当作数据。它校验整个包的 SHA-512，并检查逐文件路径、大小、SHA-256 与执行位；不执行内容包 hooks，不解析或安装技能 npm 依赖，不自动 pip 安装。
3. **使用技能**：Agent 读取的指令和执行的脚本拥有你实际授予的权限。下载不会执行脚本，但随后使用技能仍需审查其内容、服务访问与写入范围。第一方 `run` 有额外来源、入口与配置限制，**不构成操作系统沙箱**。

摘要只能证明内容与预期一致，不证明作者身份、代码无恶意或服务商可信。只读文件、虚拟环境和校验和也不是沙箱。本预览提供内容摘要验证，不声称已验证 npm 签名或 attestation。

## 来源与压缩包

技能与目录获取固定使用 HTTPS npm registry，不从源码仓库临时下载技能，不接受自定义镜像或重定向。npm 自己取得 CLI 时的 registry 设置属于 npm 的行为，与 CLI 内部获取内容的来源策略不同。

压缩包处理拒绝路径穿越、包内符号/硬链接、特殊文件、重名或大小写冲突、保留名称、非法权限及超限内容。验证失败应停止并报告，不通过降低验证规则“修复”未知包。

`--catalog` 是显式信任本地目录快照的入口，只应用于已审核的开发交付或离线验证。不要把不明来源的目录当成公共发布渠道。bundle 中自报的来源和摘要也不能自行授予作者或第一方执行身份。

## 本机文件与 Agent 可见性

内容保存于持久 home，不链接 npm `_npx` 缓存或 `node_modules`。Agent 技能目录使用受管链接/junction 或完整副本；安装器创建的顶层链接不同于被禁止的包内链接。

- 默认只管理当前系统用户的文件，不自动给其他用户或服务账号扩大权限。
- home 与 Agent 扫描根必须分离，不能互相包含。备份及临时内容不应被放进扫描根。
- 多个 Agent 若扫描同一个兼容根，可能同时看到技能。`--agent` 管理接入目标，不是访问控制，也不限制其他同用户进程读取文件。
- 未知同名文件、本地编辑及被换向的链接不会自动覆盖或删除。需要改动技能时，用 `fork` 写入独立目录。
- `agents detect` 只检查候选路径；目录存在不能证明 Agent 已加载。SkillShelf 不替 Agent 授予项目信任，未实测的目标保留 `unverified` 状态。

## 中断、恢复与清理

多个 Agent 目录、多个磁盘不能一次原子交换。SkillShelf 对并发写入加锁并保留恢复记录和备份，但打开的文件、文件系统差异或外部程序并发改动仍可能阻止恢复。

操作中断后先运行 `status`、`verify` 和 `repair --recover --dry-run`。确认方案后再恢复；若恢复拒绝未知状态，保留现场并人工核查，不直接删除恢复记录、备份或受管目录。不要把“有恢复机制”解释为任意断电都不会丢文件。

`gc` 是显式、可预览的保守清理，不隐式删除已记录的历史版本、项目引用或备份。`remove` 移除当前范围选择，不等于抹除所有已下载数据。长期备份应使用独立 bundle，而不是依赖 npm 缓存。

## 服务商凭据与运行

推荐只保存环境变量名，例如使用 `--key-env TAVILY_API_KEY`，实际 Key 由用户安全设置。自动化参数不接受明文 Key；明文落盘必须在向导中明确选择，并通过本机私有权限检查。

凭据不应出现在命令行、URL、技能正文、Agent 目录、npm 包、项目锁、导出文件或问题报告中。环境变量引用也不是密钥保险箱：同用户高权限程序、被入侵的终端或脚本仍可能接触实际值。

`run` 只允许来源和原始包验证通过的第一方搜索/媒体工具，把本次必要的服务资源放入私有临时配置，隔离无关环境，并在正常结束时清理临时配置。强制终止或断电可能留下文件；不要将整个 home 当成可公开日志或备份附件。

输出对已知 Key 及常见编码做去敏，但不能保证恶意子进程不会通过其他途径泄漏。不要让不可信代码取得服务配置。fork、第三方或本地迁移内容不能仅靠同名获得第一方 `run` 授权。

服务请求直连用户配置的服务商，可能传输提示词、查询、参考媒体并产生费用。`providers add` 和 `doctor` 不发送服务商计费请求；真正的搜索/生成必须由用户显式发起。结果未知不自动重放；先到服务商核对任务状态与账单。

删除本地配置只删除本机记录，**不会撤销服务商凭据**。若凭据可能泄漏，必须由用户在服务商处撤销或轮换，再更新本机配置。

## 预览升级与旧数据

公开预览使用 `@llx17669475`、`latest` 通道，只有确切已审版本与摘要才是内容身份。CLI 升级交给 npm；版本检查不自行覆盖程序。

旧 `@skillshelf-local` 是不同的开发包身份。建议新版本使用新的 home，保留旧 home 和自定义内容；不会静默修改旧锁、账本或来源字段。不要通过字符串替换把旧占位包伪装为新 scope 的已验证包，也不要强行覆盖旧 Agent 投影。

独立源码及 npm 包都不得包含运行凭据、个人 home、工作数据或未审查配置；具体白名单见[发布门禁](release.md)。原始版权、第三方 LICENSE/NOTICE 和必要许可记录必须保留。

## 离线与平台限制

本地 list/search/read/status/verify 不需要服务商连接。未缓存的新技能或版本需要网络；离线比较只能说明与现有目录的差异，不能声称已取得最新内容。`npx` 首次获取 CLI 不受 CLI 的 `--offline` 控制。

联网型技能依赖服务商授权和网络，不包含远端模型权重。`--offline` 拒绝实际联网/计费任务，不让缺失内容自动换到未审查来源。

测试 CI 配置覆盖 Linux/macOS/Windows、Node.js 22/24；配置存在不表示本版本已通过，结果见公开验证记录。Windows SID ACL、链接权限、打开文件的恢复行为，以及各 Agent 原生加载仍需实机验证。词法路径测试不是操作系统权限验收。

## 报告安全问题

请优先使用[源码仓库的 Security 页面](https://github.com/Lilongxi0507/skillshelf/security)中可用的私密报告渠道。若该渠道尚未开放，只提交不含漏洞细节的联系请求，等待维护者提供私密方式；不要公开可利用细节或真实凭据。

报告可以包含版本、Node.js/系统版本、复现步骤与脱敏后的文件路径。不要上传 provider 配置、完整 home、环境变量转储、令牌或用户媒体；使用最小合成样例替代真实数据。尚无承诺的响应时限或漏洞奖励计划。