skill-installation

---
name: skill-installation
description: 审查、安装、配置、激活、验证、更新和回滚 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。
version: 1.2.0
---

# Skill Installation

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

## 何时使用

使用本 Skill 处理：

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

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

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

## 核心原则

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

## 标准流程

### 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` 类型；
- 是否必填；
- 用途；
- 缺失时受影响的能力；
- 是否会出现在日志、请求或输出中。

环境值统一保存在：

```text
~/.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. 配置环境变量

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

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

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

### 11. 验证当前激活版本

至少验证：

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

不要只验证源码目录。`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` 通过；
- 环境和私有状态未被安装、更新或回滚错误覆盖。