Skill Installation

Skill Installation

用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证当前激活版本确实可用。Skill 只提供审查和安装流程；真实读取、校验、配置、安装、命令执行和回滚由工具完成。

何时使用

使用本 Skill 处理：

• 安装本地或第三方 Skill；
• 审查未知 Skill 的代码、权限和数据行为；
• 配置已安装 Skill 的环境变量；
• 更新并激活新版本；
• 验证 Skill 是否已进入索引并可读取；
• 对当前激活版本运行只读状态检查；
• 回滚到上一已安装版本。

不要使用本 Skill 创建新 Skill、重写核心设计、替作者决定业务边界，或大范围修改第三方包。需要修改源码、补测试、升级文档或重新设计时，切换到 skill-authoring。

完整安全审查规范见 skill://skill-installation/references/skill-security-review.md。

核心原则

• 先审查，后安装；不能把 skill_package validate 当作完整安全审计。
• 来源、摘要、版本、风险和缺失配置必须可追溯。
• 默认只读检查；写入、删除、上传、权限变化和依赖安装必须显式识别。
• 不替用户生成、猜测或迁移真实秘密。
• 环境变量只通过 AgentDock 的 Skill 独立环境管理能力配置。
• 安装成功不等于可用；必须验证当前激活版本、索引、正文、引用和只读状态。
• 回滚只切换已安装版本，不删除私有状态，也不覆盖共享环境配置。

标准流程

1. 识别来源

先记录：

• 来源类型：本地目录、本地压缩包或 HTTPS 下载地址；
• 来源位置和发布者；
• 目标 Skill 名称和版本；
• 用户期望安装、更新、验证还是回滚；
• 是否提供预期 SHA-256 摘要；
• 是否为首次接触的第三方包。

远程来源优先要求可信发布页和可验证摘要。URL 认证信息、查询参数和片段不得写入报告或日志。

2. 在安装前获取静态内容

在隔离的临时审查位置查看包，不直接从未知目录运行脚本。至少读取：

• 根目录文件清单；
• SKILL.md；
• references/；
• 所有脚本和测试；
• 依赖清单和锁文件；
• 包内二进制、压缩包或生成文件；
• 隐藏文件；
• 符号链接和特殊文件。

只读检查不应加载包内环境文件、不应执行安装钩子，也不应运行未知脚本。

3. 检查结构和 Frontmatter

确认：

• 包根目录存在 SKILL.md；
• Frontmatter 只依赖当前正式字段 name、description、version；
• name 稳定且与安装目标一致；
• description 能明确触发场景；
• version 是语义化版本；
• 正文非空；
• 包内引用路径存在且不越界；
• 没有符号链接逃逸、父目录穿越或绝对路径写入。

发现 agentdock.yaml、旧式统一执行协议或旧 Skill Runtime 设计时，至少标记为 blocked，不得直接安装。

4. 执行安全审查

逐项检查：

• 网络访问目标、协议和上传内容；
• Shell 命令和子进程；
• 文件系统读取、写入、覆盖和删除；
• 权限、启动项、计划任务和持久化变化；
• 凭据、Cookie、浏览器数据、SSH 配置和主目录敏感文件读取；
• 外部依赖安装；
• 下载后执行、动态代码加载和混淆代码；
• 二进制文件和无法审查的构件；
• 运行状态和秘密是否被打包；
• 日志、错误和返回值是否可能泄露秘密；
• 破坏性动作是否要求用户确认。

风险分类：

| 等级 | 含义 | 默认处理 |

|---|---|---|

| low | 纯文档或行为明确、只读、无敏感访问 | 可继续校验 |

| medium | 有明确网络、写入或普通依赖，但范围可解释 | 展示风险后继续 |

| high | 涉及敏感凭据、广泛文件访问、上传、删除或持久化 | 未经明确确认不安装 |

| blocked | 存在不可接受或无法解释的危险行为 | 停止安装 |

必须阻止：

• 包内真实密钥、Cookie、私钥或认证缓存；
• 自动读取浏览器全部 Cookie；
• 自动读取用户主目录敏感文件；
• 隐蔽下载并执行；
• 修改系统权限或持久化配置而未明确说明；
• 未经确认删除或覆盖数据；
• 未说明的外部上传；
• 路径穿越或符号链接逃逸；
• 无法审查且会被执行的二进制；
• agentdock.yaml 旧清单。

5. 检查环境变量需求

从 SKILL.md 中提取环境变量表，确认每个变量的：

• 名称；
• config 或 secret 类型；
• 是否必填；
• 用途；
• 缺失时受影响的能力；
• 是否会出现在日志、请求或输出中。

环境值统一保存在：

~/.agentdock/env/skill/<skill-name>.env

不得在以下位置新建环境文件：

• ~/.agentdock/skill-data/<skill-name>/；
• Skill 源码目录；
• 项目根目录；
• 包内辅助脚本旁；
• 任何 wrapper 专用目录。

使用：

• skill_package env_list 查看变量名称和配置状态；
• skill_package env_set 写入或更新用户明确提供的值；
• skill_package env_unset 删除指定变量。

这些动作不应返回真实值。不要用手工散落环境文件代替正式工具。

6. 检查脚本和依赖

辅助脚本应满足：

• stdin 输入是 JSON 对象；
• 顶层动作字段为 skill_action；
• 密钥只从注入环境读取；
• 不通过命令行参数接收秘密；
• 输出结构化 JSON；
• 错误包含明确 code 和 message；
• status 默认只读；
• 写操作和破坏性动作有确认机制；
• 日志和错误不回显秘密。

对脚本做语法或编译检查，并运行包内测试。首次审查未知脚本时，只有静态审查通过后才允许在受控环境中运行只读检查。

7. 使用 skill_package validate

调用 skill_package validate 校验来源，必要时同时传入预期摘要。确认：

• valid: true；
• 解析出的名称、描述和版本与审查结果一致；
• 返回摘要已记录；
• 没有结构化校验问题。

校验只证明包满足 AgentDock 基础结构和安装约束，不替代前面的安全审查。

8. 安装前汇报

正式安装前向用户说明：

• 来源和摘要；
• Skill 名称和版本；
• 文件清单摘要；
• 风险等级和具体依据；
• 网络、文件、Shell、权限和数据行为；
• 外部依赖；
• 必填环境变量中尚未配置的名称；
• 是否存在无法验证的部分；
• 是否应在安装后立即激活。

low 和可解释的 medium 风险可按用户原始安装意图继续。high 风险必须获得明确确认。blocked 不得继续。

9. 安装和激活

使用 skill_package install，并遵循：

• 一个 Skill 可以安装多个版本，但任何时刻只有一个激活版本；
• 需要先审查或试运行新版时，可以只安装而不激活；
• 需要切换版本时使用 skill_package activate 显式激活已安装的目标版本；
• 默认激活时确认返回的 Activated 为真；
• 同名同版本不同内容不得覆盖；
• 更新时保留旧版本以支持回滚。

安装完成后记录安装结果中的名称、版本、摘要和激活状态。

10. 配置环境变量

只配置用户明确提供或已获授权迁移的值。流程：

• skill_package env_list 获取当前配置状态；
• 列出缺失的必填变量名；
• 对每个变量调用 skill_package env_set；
• 再次 env_list，只核对 configured 状态；
• 不读取、展示或记录变量值。

配置动作与安装包版本分离。更新或回滚不应自动覆盖已有 Skill 环境。

11. 验证当前激活版本

至少验证：

• skill_package install 返回成功并激活预期版本；
• 当前 Skill 状态中的 active_version 与预期一致；
• agentdock_context 中出现正确名称和描述；
• read_file skill://<name>/SKILL.md 可读取，并显示预期版本正文；
• 包内引用可通过 skill://<name>/... 读取；
• 当前已安装包摘要与审查时源码摘要一致；
• skill_package env_list 显示必填配置完整；
• 没有旧版本错误路径或过期变量名；
• 日志和结果没有秘密。

不要只验证源码目录。skill:// 读取的是当前激活版本，是最终验收依据之一。

12. 运行只读状态检查

只有包包含辅助脚本和 status 能力时才执行：

• 使用 exec_command 的 skill: "<skill-name>" 绑定当前激活版本的包根目录和独立环境；
• 命令使用包内相对路径，例如 python3 run.py；
• stdin 使用 {"skill_action":"status"}；
• 不手工解析安装版本目录，不主动读取或 source 环境文件；
• 不进行写入、删除、上传或权限修改；
• 检查输出是否结构化、可诊断且不泄露秘密。

纯文档 Skill 没有辅助脚本时，不虚构 status，以索引、正文、引用和环境状态验证为准。

13. 更新

更新前比较：

• 旧版本与新版本的 Frontmatter；
• 新增和删除文件；
• 网络目标、权限和依赖变化；
• 环境变量新增、删除或含义变化；
• 私有状态兼容性；
• 破坏性行为和确认规则；
• 摘要和发布来源。

对新版本完整执行审查、校验、安装和验收，不因旧版本已可信而跳过差异审查。

14. 回滚

使用 skill_package rollback 切换到上一已安装版本。回滚前确认旧版本仍存在，并说明回滚原因。

回滚后验证：

• active_version 已切回预期版本；
• skill://<name>/SKILL.md 读取的是回滚版本；
• agentdock_context 描述与回滚版本一致；
• 新版本私有状态没有被误删；
• ~/.agentdock/env/skill/<skill-name>.env 没有被覆盖；
• 旧版本的必填环境变量仍完整；
• 有辅助脚本时只读 status 通过。

若新旧版本共享状态格式不兼容，先停止并报告，不擅自删除或迁移数据。

环境变量

本 Skill 自身不需要环境变量。它只负责通过 skill_package 管理目标 Skill 的独立环境。

完成标准

只有同时满足以下条件才算完成：

• 来源、版本和摘要已记录；
• 安全审查有明确风险等级和证据；
• 没有 blocked 项；
• skill_package validate 通过；
• 安装或回滚后的当前激活版本正确；
• agentdock_context 和 skill:// 验证通过；
• 必填环境配置完整且未泄露值；
• 有辅助脚本时只读 status 通过；
• 环境和私有状态未被安装、更新或回滚错误覆盖。