[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F256RMEEDD96VSS6HCH7DF":3,"skill-same:01M7F256RMEEDD96VSS6HCH7DF":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7F256RMEEDD96VSS6HCH7DF","skill-installation",null,"审查、安装、配置、激活、验证、更新、回滚和卸载 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。","kkda49\u002FAgentDock-Workbench","kkda49","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F87223383?v=4","01M7F24WDCX75FK5HAJB3ZY94B","01M7F24WE679RD64MTCSYTWFVY",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-installation\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: skill-installation\ndescription: 审查、安装、配置、激活、验证、更新、回滚和卸载 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。\nversion: 1.3.0\n---\n\n# Skill Installation\n\n用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证当前激活版本确实可用。Skill 只提供审查和安装流程；真实读取、校验、配置、安装、命令执行、回滚和卸载由工具完成。\n\n## 何时使用\n\n使用本 Skill 处理：\n\n- 安装本地或第三方 Skill；\n- 审查未知 Skill 的代码、权限和数据行为；\n- 配置已安装 Skill 的环境变量；\n- 更新并激活新版本；\n- 验证 Skill 是否已进入索引并可读取；\n- 对当前激活版本运行只读状态检查；\n- 回滚到上一已安装版本；\n- 卸载指定非激活版本或整个非内置 Skill。\n\n不要使用本 Skill 创建新 Skill、重写核心设计、替作者决定业务边界，或大范围修改第三方包。需要修改源码、补测试、升级文档或重新设计时，切换到 `skill-authoring`。\n\n完整安全审查规范见 `skill:\u002F\u002Fskill-installation\u002Freferences\u002Fskill-security-review.md`。\n\n## 核心原则\n\n1. 先审查，后安装；不能把 `skill_package validate` 当作完整安全审计。\n2. 来源、摘要、版本、风险和缺失配置必须可追溯。\n3. 默认只读检查；写入、删除、上传、权限变化和依赖安装必须显式识别。\n4. 不替用户生成、猜测或迁移真实秘密。\n5. 环境变量只通过 AgentDock 的 Skill 独立环境管理能力配置。\n6. 安装成功不等于可用；必须验证当前激活版本、索引、正文、引用和只读状态。\n7. 回滚只切换已安装版本，不删除私有状态，也不覆盖共享环境配置。\n\n## Codex 风格目录布局\n\n新安装使用以下结构：\n\n```text\n~\u002F.agentdock\u002Fskills\u002F\n├── \u003Cskill-name>\u002F                    # 当前激活的用户 Skill\n├── .system\u002F\u003Cskill-name>\u002F            # 当前激活的内置 Skill\n├── .versions\u002F\u003Cskill-name>\u002F\u003Cversion>\u002F# 未激活版本与回滚版本\n├── .state\u002F\u003Cskill-name>.json         # 版本、禁用状态与分类元数据\n├── .cache\u002F                          # 下载与校验缓存\n├── .locks\u002F                          # 安装、激活和卸载锁\n└── .tmp\u002F                            # 同一文件系统内的事务暂存\n```\n\n顶层用户目录与 `.system` 目录刻意兼容 Codex 的 Skill 发现方式；多版本、回滚和事务状态放在隐藏目录中。不要手工拼接这些路径：读取正文使用 `skill:\u002F\u002F\u003Cname>\u002F...`，运行脚本使用绑定了 `skill` 的 `exec_command`，版本管理使用 `skill_package`。\n\n旧的 `~\u002F.agentdock\u002Fskill-store\u002F` 不会被新源码自动迁移或合并。迁移必须作为独立、显式、可回滚的操作处理，不能在普通启动或安装过程中静默执行。\n\n环境变量和私有运行数据继续与安装包隔离：\n\n- `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env`；\n- `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`。\n\n### 插件内 Skill 的边界\n\n自包含重插件中的 Skill 位于 `~\u002F.agentdock\u002Fplugins\u002F\u003Cplugin>\u002Fskills\u002F\u003Cskill-name>`，其安装、更新、删除和启停由插件包与 `plugin_manage` 统一管理。遇到插件内 Skill 时：\n\n- 不要把它再次安装到 `~\u002F.agentdock\u002Fskills\u002F\u003Cskill-name>`；\n- 不要使用独立 `skill_package activate\u002Funinstall\u002Fenable\u002Fdisable` 改写其状态；\n- 更新整个插件时重新审查插件清单、全部 Skill、MCP 定义、脚本和二进制；\n- 环境变量仍通过按 Skill\u002FMCP 名称隔离的正式环境管理能力配置，不写入插件包；\n- `skill:\u002F\u002F\u003Cname>\u002F...` 与绑定 Skill 的 `exec_command` 会解析到插件携带的当前成员目录。\n\n插件目录或 ZIP 的完整审查不能由单个 Skill 的 `skill_package validate` 代替；应先使用 `plugin_manage validate`，再按本 Skill 的安全规则审查每个包含的 Skill。\n\n## 标准流程\n\n### 1. 识别来源\n\n先记录：\n\n- 来源类型：本地目录、本地压缩包或 HTTPS 下载地址；\n- 来源位置和发布者；\n- 目标 Skill 名称和版本；\n- 用户期望安装、更新、验证还是回滚；\n- 是否提供预期 SHA-256 摘要；\n- 是否为首次接触的第三方包。\n\n远程来源优先要求可信发布页和可验证摘要。URL 认证信息、查询参数和片段不得写入报告或日志。\n\n### 2. 在安装前获取静态内容\n\n在隔离的临时审查位置查看包，不直接从未知目录运行脚本。至少读取：\n\n- 根目录文件清单；\n- `SKILL.md`；\n- `references\u002F`；\n- 所有脚本和测试；\n- 依赖清单和锁文件；\n- 包内二进制、压缩包或生成文件；\n- 隐藏文件；\n- 符号链接和特殊文件。\n\n只读检查不应加载包内环境文件、不应执行安装钩子，也不应运行未知脚本。\n\n### 3. 检查结构和 Frontmatter\n\n确认：\n\n- 包根目录存在 `SKILL.md`；\n- Frontmatter 只依赖当前正式字段 `name`、`description`、`version`；\n- `name` 稳定且与安装目标一致；\n- `description` 能明确触发场景；\n- `version` 是语义化版本；\n- 正文非空；\n- 包内引用路径存在且不越界；\n- 没有符号链接逃逸、父目录穿越或绝对路径写入。\n\n发现 `agentdock.yaml`、旧式统一执行协议或旧 Skill Runtime 设计时，至少标记为 `blocked`，不得直接安装。\n\n### 4. 执行安全审查\n\n逐项检查：\n\n- 网络访问目标、协议和上传内容；\n- Shell 命令和子进程；\n- 文件系统读取、写入、覆盖和删除；\n- 权限、启动项、计划任务和持久化变化；\n- 凭据、Cookie、浏览器数据、SSH 配置和主目录敏感文件读取；\n- 外部依赖安装；\n- 下载后执行、动态代码加载和混淆代码；\n- 二进制文件和无法审查的构件；\n- 运行状态和秘密是否被打包；\n- 日志、错误和返回值是否可能泄露秘密；\n- 破坏性动作是否要求用户确认。\n\n风险分类：\n\n| 等级 | 含义 | 默认处理 |\n|---|---|---|\n| `low` | 纯文档或行为明确、只读、无敏感访问 | 可继续校验 |\n| `medium` | 有明确网络、写入或普通依赖，但范围可解释 | 展示风险后继续 |\n| `high` | 涉及敏感凭据、广泛文件访问、上传、删除或持久化 | 未经明确确认不安装 |\n| `blocked` | 存在不可接受或无法解释的危险行为 | 停止安装 |\n\n必须阻止：\n\n- 包内真实密钥、Cookie、私钥或认证缓存；\n- 自动读取浏览器全部 Cookie；\n- 自动读取用户主目录敏感文件；\n- 隐蔽下载并执行；\n- 修改系统权限或持久化配置而未明确说明；\n- 未经确认删除或覆盖数据；\n- 未说明的外部上传；\n- 路径穿越或符号链接逃逸；\n- 无法审查且会被执行的二进制；\n- `agentdock.yaml` 旧清单。\n\n### 5. 检查环境变量需求\n\n从 `SKILL.md` 中提取环境变量表，确认每个变量的：\n\n- 名称；\n- `config` 或 `secret` 类型；\n- 是否必填；\n- 用途；\n- 缺失时受影响的能力；\n- 是否会出现在日志、请求或输出中。\n\n环境值统一保存在：\n\n```text\n~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env\n```\n\n不得在以下位置新建环境文件：\n\n- `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`；\n- Skill 源码目录；\n- 项目根目录；\n- 包内辅助脚本旁；\n- 任何 wrapper 专用目录。\n\n使用：\n\n- `skill_package env_list` 查看变量名称和配置状态；\n- `skill_package env_set` 写入或更新用户明确提供的值；\n- `skill_package env_unset` 删除指定变量。\n\n这些动作不应返回真实值。不要用手工散落环境文件代替正式工具。\n\n### 6. 检查脚本和依赖\n\n辅助脚本应满足：\n\n- stdin 输入是 JSON 对象；\n- 顶层动作字段为 `skill_action`；\n- 密钥只从注入环境读取；\n- 不通过命令行参数接收秘密；\n- 输出结构化 JSON；\n- 错误包含明确 `code` 和 `message`；\n- `status` 默认只读；\n- 写操作和破坏性动作有确认机制；\n- 日志和错误不回显秘密。\n\n对脚本做语法或编译检查，并运行包内测试。首次审查未知脚本时，只有静态审查通过后才允许在受控环境中运行只读检查。\n\n### 7. 使用 skill_package validate\n\n调用 `skill_package validate` 校验来源，必要时同时传入预期摘要。确认：\n\n- `valid: true`；\n- 解析出的名称、描述和版本与审查结果一致；\n- 返回摘要已记录；\n- 没有结构化校验问题。\n\n校验只证明包满足 AgentDock 基础结构和安装约束，不替代前面的安全审查。\n\n### 8. 安装前汇报\n\n正式安装前向用户说明：\n\n- 来源和摘要；\n- Skill 名称和版本；\n- 文件清单摘要；\n- 风险等级和具体依据；\n- 网络、文件、Shell、权限和数据行为；\n- 外部依赖；\n- 必填环境变量中尚未配置的名称；\n- 是否存在无法验证的部分；\n- 是否应在安装后立即激活。\n\n`low` 和可解释的 `medium` 风险可按用户原始安装意图继续。`high` 风险必须获得明确确认。`blocked` 不得继续。\n\n### 9. 安装和激活\n\n使用 `skill_package install`，并遵循：\n\n- 一个 Skill 可以安装多个版本，但任何时刻只有一个激活版本；\n- 需要先审查或试运行新版时，可以只安装而不激活；\n- 需要切换版本时使用 `skill_package activate` 显式激活已安装的目标版本；\n- 默认激活时确认返回的 `Activated` 为真；\n- 同名同版本不同内容不得覆盖；\n- 更新时保留旧版本以支持回滚。\n\n安装完成后记录安装结果中的名称、版本、摘要和激活状态。\n\n### 10. 配置环境变量\n\n只配置用户明确提供或已获授权迁移的值。流程：\n\n1. `skill_package env_list` 获取当前配置状态；\n2. 列出缺失的必填变量名；\n3. 对每个变量调用 `skill_package env_set`；\n4. 再次 `env_list`，只核对 `configured` 状态；\n5. 不读取、展示或记录变量值。\n\n配置动作与安装包版本分离。更新或回滚不应自动覆盖已有 Skill 环境。\n\n### 11. 验证当前激活版本\n\n至少验证：\n\n1. `skill_package install` 返回成功并激活预期版本；\n2. 当前 Skill 状态中的 `active_version` 与预期一致；\n3. `agentdock_context` 中出现正确名称和描述；\n4. `read_file skill:\u002F\u002F\u003Cname>\u002FSKILL.md` 可读取，并显示预期版本正文；\n5. 包内引用可通过 `skill:\u002F\u002F\u003Cname>\u002F...` 读取；\n6. 当前已安装包摘要与审查时源码摘要一致；\n7. `skill_package env_list` 显示必填配置完整；\n8. 没有旧版本错误路径或过期变量名；\n9. 日志和结果没有秘密。\n\n不要只验证源码目录。`skill:\u002F\u002F` 读取的是当前激活版本，是最终验收依据之一。\n\n### 12. 运行只读状态检查\n\n只有包包含辅助脚本和 `status` 能力时才执行：\n\n- 使用 `exec_command` 的 `skill: \"\u003Cskill-name>\"` 绑定当前激活版本的包根目录和独立环境；\n- 命令使用包内相对路径，例如 `python3 run.py`；\n- stdin 使用 `{\"skill_action\":\"status\"}`；\n- 不手工解析安装版本目录，不主动读取或 `source` 环境文件；\n- 不进行写入、删除、上传或权限修改；\n- 检查输出是否结构化、可诊断且不泄露秘密。\n\n纯文档 Skill 没有辅助脚本时，不虚构 `status`，以索引、正文、引用和环境状态验证为准。\n\n### 13. 更新\n\n更新前比较：\n\n- 旧版本与新版本的 Frontmatter；\n- 新增和删除文件；\n- 网络目标、权限和依赖变化；\n- 环境变量新增、删除或含义变化；\n- 私有状态兼容性；\n- 破坏性行为和确认规则；\n- 摘要和发布来源。\n\n对新版本完整执行审查、校验、安装和验收，不因旧版本已可信而跳过差异审查。\n\n### 14. 回滚\n\n使用 `skill_package rollback` 切换到上一已安装版本。回滚前确认旧版本仍存在，并说明回滚原因。\n\n回滚后验证：\n\n- `active_version` 已切回预期版本；\n- `skill:\u002F\u002F\u003Cname>\u002FSKILL.md` 读取的是回滚版本；\n- `agentdock_context` 描述与回滚版本一致；\n- 新版本私有状态没有被误删；\n- `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env` 没有被覆盖；\n- 旧版本的必填环境变量仍完整；\n- 有辅助脚本时只读 `status` 通过。\n\n若新旧版本共享状态格式不兼容，先停止并报告，不擅自删除或迁移数据。\n\n### 15. 卸载\n\n使用 `skill_package uninstall` 管理已安装包：\n\n- 不传 `version` 时卸载整个非内置 Skill，包括全部已安装版本和版本选择状态；\n- 传 `version` 时只卸载指定版本；当前激活版本不能直接卸载，必须先显式激活其他版本；\n- 内置 bundled Skill 不能卸载；\n- 卸载不会自动切换激活版本；\n- 卸载不会删除 `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env` 或 `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`，这些用户配置和运行数据需要独立管理。\n\n卸载后确认目标版本或 Skill 已不再出现在已安装列表中；保留的环境配置和私有运行数据不得被误删。\n\n## 环境变量\n\n本 Skill 自身不需要环境变量。它只负责通过 `skill_package` 管理目标 Skill 的独立环境。\n\n## 完成标准\n\n只有同时满足以下条件才算完成：\n\n- 来源、版本和摘要已记录；\n- 安全审查有明确风险等级和证据；\n- 没有 `blocked` 项；\n- `skill_package validate` 通过；\n- 安装或回滚后的当前激活版本正确；\n- `agentdock_context` 和 `skill:\u002F\u002F` 验证通过；\n- 必填环境配置完整且未泄露值；\n- 有辅助脚本时只读 `status` 通过；\n- 环境和私有状态未被安装、更新或回滚错误覆盖。\n\n## 精确来源与并发读取\n\n选择 workspace、shared 或插件成员时，读取宿主返回的 `file`，执行时使用同一候选的 `skill_ref`。不要在后续步骤按裸名称改选另一来源。独立已安装 Skill 仍由 `skill_package` 负责版本、激活和回滚，插件成员继续由 `plugin_manage` 管理。\n\nmanaged Skill 执行时，宿主可提供保留变量 `SKILL_DATA_DIR` 作为私有持久数据目录。可移植核心不得把它设为用户必填配置或硬编码宿主路径；shared\u002Fworkspace 同名候选不继承 managed 环境和数据。安装包禁止符号链接、FIFO 和其他特殊文件。managed 资源读取及命令执行持有读租约，写入、激活和卸载等待该读取结束。\n","# Skill Installation\n\n用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证当前激活版本确实可用。Skill 只提供审查和安装流程；真实读取、校验、配置、安装、命令执行、回滚和卸载由工具完成。\n\n## 何时使用\n\n使用本 Skill 处理：\n\n- 安装本地或第三方 Skill；\n- 审查未知 Skill 的代码、权限和数据行为；\n- 配置已安装 Skill 的环境变量；\n- 更新并激活新版本；\n- 验证 Skill 是否已进入索引并可读取；\n- 对当前激活版本运行只读状态检查；\n- 回滚到上一已安装版本；\n- 卸载指定非激活版本或整个非内置 Skill。\n\n不要使用本 Skill 创建新 Skill、重写核心设计、替作者决定业务边界，或大范围修改第三方包。需要修改源码、补测试、升级文档或重新设计时，切换到 `skill-authoring`。\n\n完整安全审查规范见 `skill:\u002F\u002Fskill-installation\u002Freferences\u002Fskill-security-review.md`。\n\n## 核心原则\n\n1. 先审查，后安装；不能把 `skill_package validate` 当作完整安全审计。\n2. 来源、摘要、版本、风险和缺失配置必须可追溯。\n3. 默认只读检查；写入、删除、上传、权限变化和依赖安装必须显式识别。\n4. 不替用户生成、猜测或迁移真实秘密。\n5. 环境变量只通过 AgentDock 的 Skill 独立环境管理能力配置。\n6. 安装成功不等于可用；必须验证当前激活版本、索引、正文、引用和只读状态。\n7. 回滚只切换已安装版本，不删除私有状态，也不覆盖共享环境配置。\n\n## Codex 风格目录布局\n\n新安装使用以下结构：\n\n```text\n~\u002F.agentdock\u002Fskills\u002F\n├── \u003Cskill-name>\u002F                    # 当前激活的用户 Skill\n├── .system\u002F\u003Cskill-name>\u002F            # 当前激活的内置 Skill\n├── .versions\u002F\u003Cskill-name>\u002F\u003Cversion>\u002F# 未激活版本与回滚版本\n├── .state\u002F\u003Cskill-name>.json         # 版本、禁用状态与分类元数据\n├── .cache\u002F                          # 下载与校验缓存\n├── .locks\u002F                          # 安装、激活和卸载锁\n└── .tmp\u002F                            # 同一文件系统内的事务暂存\n```\n\n顶层用户目录与 `.system` 目录刻意兼容 Codex 的 Skill 发现方式；多版本、回滚和事务状态放在隐藏目录中。不要手工拼接这些路径：读取正文使用 `skill:\u002F\u002F\u003Cname>\u002F...`，运行脚本使用绑定了 `skill` 的 `exec_command`，版本管理使用 `skill_package`。\n\n旧的 `~\u002F.agentdock\u002Fskill-store\u002F` 不会被新源码自动迁移或合并。迁移必须作为独立、显式、可回滚的操作处理，不能在普通启动或安装过程中静默执行。\n\n环境变量和私有运行数据继续与安装包隔离：\n\n- `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env`；\n- `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`。\n\n### 插件内 Skill 的边界\n\n自包含重插件中的 Skill 位于 `~\u002F.agentdock\u002Fplugins\u002F\u003Cplugin>\u002Fskills\u002F\u003Cskill-name>`，其安装、更新、删除和启停由插件包与 `plugin_manage` 统一管理。遇到插件内 Skill 时：\n\n- 不要把它再次安装到 `~\u002F.agentdock\u002Fskills\u002F\u003Cskill-name>`；\n- 不要使用独立 `skill_package activate\u002Funinstall\u002Fenable\u002Fdisable` 改写其状态；\n- 更新整个插件时重新审查插件清单、全部 Skill、MCP 定义、脚本和二进制；\n- 环境变量仍通过按 Skill\u002FMCP 名称隔离的正式环境管理能力配置，不写入插件包；\n- `skill:\u002F\u002F\u003Cname>\u002F...` 与绑定 Skill 的 `exec_command` 会解析到插件携带的当前成员目录。\n\n插件目录或 ZIP 的完整审查不能由单个 Skill 的 `skill_package validate` 代替；应先使用 `plugin_manage validate`，再按本 Skill 的安全规则审查每个包含的 Skill。\n\n## 标准流程\n\n### 1. 识别来源\n\n先记录：\n\n- 来源类型：本地目录、本地压缩包或 HTTPS 下载地址；\n- 来源位置和发布者；\n- 目标 Skill 名称和版本；\n- 用户期望安装、更新、验证还是回滚；\n- 是否提供预期 SHA-256 摘要；\n- 是否为首次接触的第三方包。\n\n远程来源优先要求可信发布页和可验证摘要。URL 认证信息、查询参数和片段不得写入报告或日志。\n\n### 2. 在安装前获取静态内容\n\n在隔离的临时审查位置查看包，不直接从未知目录运行脚本。至少读取：\n\n- 根目录文件清单；\n- `SKILL.md`；\n- `references\u002F`；\n- 所有脚本和测试；\n- 依赖清单和锁文件；\n- 包内二进制、压缩包或生成文件；\n- 隐藏文件；\n- 符号链接和特殊文件。\n\n只读检查不应加载包内环境文件、不应执行安装钩子，也不应运行未知脚本。\n\n### 3. 检查结构和 Frontmatter\n\n确认：\n\n- 包根目录存在 `SKILL.md`；\n- Frontmatter 只依赖当前正式字段 `name`、`description`、`version`；\n- `name` 稳定且与安装目标一致；\n- `description` 能明确触发场景；\n- `version` 是语义化版本；\n- 正文非空；\n- 包内引用路径存在且不越界；\n- 没有符号链接逃逸、父目录穿越或绝对路径写入。\n\n发现 `agentdock.yaml`、旧式统一执行协议或旧 Skill Runtime 设计时，至少标记为 `blocked`，不得直接安装。\n\n### 4. 执行安全审查\n\n逐项检查：\n\n- 网络访问目标、协议和上传内容；\n- Shell 命令和子进程；\n- 文件系统读取、写入、覆盖和删除；\n- 权限、启动项、计划任务和持久化变化；\n- 凭据、Cookie、浏览器数据、SSH 配置和主目录敏感文件读取；\n- 外部依赖安装；\n- 下载后执行、动态代码加载和混淆代码；\n- 二进制文件和无法审查的构件；\n- 运行状态和秘密是否被打包；\n- 日志、错误和返回值是否可能泄露秘密；\n- 破坏性动作是否要求用户确认。\n\n风险分类：\n\n| 等级 | 含义 | 默认处理 |\n|---|---|---|\n| `low` | 纯文档或行为明确、只读、无敏感访问 | 可继续校验 |\n| `medium` | 有明确网络、写入或普通依赖，但范围可解释 | 展示风险后继续 |\n| `high` | 涉及敏感凭据、广泛文件访问、上传、删除或持久化 | 未经明确确认不安装 |\n| `blocked` | 存在不可接受或无法解释的危险行为 | 停止安装 |\n\n必须阻止：\n\n- 包内真实密钥、Cookie、私钥或认证缓存；\n- 自动读取浏览器全部 Cookie；\n- 自动读取用户主目录敏感文件；\n- 隐蔽下载并执行；\n- 修改系统权限或持久化配置而未明确说明；\n- 未经确认删除或覆盖数据；\n- 未说明的外部上传；\n- 路径穿越或符号链接逃逸；\n- 无法审查且会被执行的二进制；\n- `agentdock.yaml` 旧清单。\n\n### 5. 检查环境变量需求\n\n从 `SKILL.md` 中提取环境变量表，确认每个变量的：\n\n- 名称；\n- `config` 或 `secret` 类型；\n- 是否必填；\n- 用途；\n- 缺失时受影响的能力；\n- 是否会出现在日志、请求或输出中。\n\n环境值统一保存在：\n\n```text\n~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env\n```\n\n不得在以下位置新建环境文件：\n\n- `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`；\n- Skill 源码目录；\n- 项目根目录；\n- 包内辅助脚本旁；\n- 任何 wrapper 专用目录。\n\n使用：\n\n- `skill_package env_list` 查看变量名称和配置状态；\n- `skill_package env_set` 写入或更新用户明确提供的值；\n- `skill_package env_unset` 删除指定变量。\n\n这些动作不应返回真实值。不要用手工散落环境文件代替正式工具。\n\n### 6. 检查脚本和依赖\n\n辅助脚本应满足：\n\n- stdin 输入是 JSON 对象；\n- 顶层动作字段为 `skill_action`；\n- 密钥只从注入环境读取；\n- 不通过命令行参数接收秘密；\n- 输出结构化 JSON；\n- 错误包含明确 `code` 和 `message`；\n- `status` 默认只读；\n- 写操作和破坏性动作有确认机制；\n- 日志和错误不回显秘密。\n\n对脚本做语法或编译检查，并运行包内测试。首次审查未知脚本时，只有静态审查通过后才允许在受控环境中运行只读检查。\n\n### 7. 使用 skill_package validate\n\n调用 `skill_package validate` 校验来源，必要时同时传入预期摘要。确认：\n\n- `valid: true`；\n- 解析出的名称、描述和版本与审查结果一致；\n- 返回摘要已记录；\n- 没有结构化校验问题。\n\n校验只证明包满足 AgentDock 基础结构和安装约束，不替代前面的安全审查。\n\n### 8. 安装前汇报\n\n正式安装前向用户说明：\n\n- 来源和摘要；\n- Skill 名称和版本；\n- 文件清单摘要；\n- 风险等级和具体依据；\n- 网络、文件、Shell、权限和数据行为；\n- 外部依赖；\n- 必填环境变量中尚未配置的名称；\n- 是否存在无法验证的部分；\n- 是否应在安装后立即激活。\n\n`low` 和可解释的 `medium` 风险可按用户原始安装意图继续。`high` 风险必须获得明确确认。`blocked` 不得继续。\n\n### 9. 安装和激活\n\n使用 `skill_package install`，并遵循：\n\n- 一个 Skill 可以安装多个版本，但任何时刻只有一个激活版本；\n- 需要先审查或试运行新版时，可以只安装而不激活；\n- 需要切换版本时使用 `skill_package activate` 显式激活已安装的目标版本；\n- 默认激活时确认返回的 `Activated` 为真；\n- 同名同版本不同内容不得覆盖；\n- 更新时保留旧版本以支持回滚。\n\n安装完成后记录安装结果中的名称、版本、摘要和激活状态。\n\n### 10. 配置环境变量\n\n只配置用户明确提供或已获授权迁移的值。流程：\n\n1. `skill_package env_list` 获取当前配置状态；\n2. 列出缺失的必填变量名；\n3. 对每个变量调用 `skill_package env_set`；\n4. 再次 `env_list`，只核对 `configured` 状态；\n5. 不读取、展示或记录变量值。\n\n配置动作与安装包版本分离。更新或回滚不应自动覆盖已有 Skill 环境。\n\n### 11. 验证当前激活版本\n\n至少验证：\n\n1. `skill_package install` 返回成功并激活预期版本；\n2. 当前 Skill 状态中的 `active_version` 与预期一致；\n3. `agentdock_context` 中出现正确名称和描述；\n4. `read_file skill:\u002F\u002F\u003Cname>\u002FSKILL.md` 可读取，并显示预期版本正文；\n5. 包内引用可通过 `skill:\u002F\u002F\u003Cname>\u002F...` 读取；\n6. 当前已安装包摘要与审查时源码摘要一致；\n7. `skill_package env_list` 显示必填配置完整；\n8. 没有旧版本错误路径或过期变量名；\n9. 日志和结果没有秘密。\n\n不要只验证源码目录。`skill:\u002F\u002F` 读取的是当前激活版本，是最终验收依据之一。\n\n### 12. 运行只读状态检查\n\n只有包包含辅助脚本和 `status` 能力时才执行：\n\n- 使用 `exec_command` 的 `skill: \"\u003Cskill-name>\"` 绑定当前激活版本的包根目录和独立环境；\n- 命令使用包内相对路径，例如 `python3 run.py`；\n- stdin 使用 `{\"skill_action\":\"status\"}`；\n- 不手工解析安装版本目录，不主动读取或 `source` 环境文件；\n- 不进行写入、删除、上传或权限修改；\n- 检查输出是否结构化、可诊断且不泄露秘密。\n\n纯文档 Skill 没有辅助脚本时，不虚构 `status`，以索引、正文、引用和环境状态验证为准。\n\n### 13. 更新\n\n更新前比较：\n\n- 旧版本与新版本的 Frontmatter；\n- 新增和删除文件；\n- 网络目标、权限和依赖变化；\n- 环境变量新增、删除或含义变化；\n- 私有状态兼容性；\n- 破坏性行为和确认规则；\n- 摘要和发布来源。\n\n对新版本完整执行审查、校验、安装和验收，不因旧版本已可信而跳过差异审查。\n\n### 14. 回滚\n\n使用 `skill_package rollback` 切换到上一已安装版本。回滚前确认旧版本仍存在，并说明回滚原因。\n\n回滚后验证：\n\n- `active_version` 已切回预期版本；\n- `skill:\u002F\u002F\u003Cname>\u002FSKILL.md` 读取的是回滚版本；\n- `agentdock_context` 描述与回滚版本一致；\n- 新版本私有状态没有被误删；\n- `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env` 没有被覆盖；\n- 旧版本的必填环境变量仍完整；\n- 有辅助脚本时只读 `status` 通过。\n\n若新旧版本共享状态格式不兼容，先停止并报告，不擅自删除或迁移数据。\n\n### 15. 卸载\n\n使用 `skill_package uninstall` 管理已安装包：\n\n- 不传 `version` 时卸载整个非内置 Skill，包括全部已安装版本和版本选择状态；\n- 传 `version` 时只卸载指定版本；当前激活版本不能直接卸载，必须先显式激活其他版本；\n- 内置 bundled Skill 不能卸载；\n- 卸载不会自动切换激活版本；\n- 卸载不会删除 `~\u002F.agentdock\u002Fenv\u002Fskill\u002F\u003Cskill-name>.env` 或 `~\u002F.agentdock\u002Fskill-data\u002F\u003Cskill-name>\u002F`，这些用户配置和运行数据需要独立管理。\n\n卸载后确认目标版本或 Skill 已不再出现在已安装列表中；保留的环境配置和私有运行数据不得被误删。\n\n## 环境变量\n\n本 Skill 自身不需要环境变量。它只负责通过 `skill_package` 管理目标 Skill 的独立环境。\n\n## 完成标准\n\n只有同时满足以下条件才算完成：\n\n- 来源、版本和摘要已记录；\n- 安全审查有明确风险等级和证据；\n- 没有 `blocked` 项；\n- `skill_package validate` 通过；\n- 安装或回滚后的当前激活版本正确；\n- `agentdock_context` 和 `skill:\u002F\u002F` 验证通过；\n- 必填环境配置完整且未泄露值；\n- 有辅助脚本时只读 `status` 通过；\n- 环境和私有状态未被安装、更新或回滚错误覆盖。\n\n## 精确来源与并发读取\n\n选择 workspace、shared 或插件成员时，读取宿主返回的 `file`，执行时使用同一候选的 `skill_ref`。不要在后续步骤按裸名称改选另一来源。独立已安装 Skill 仍由 `skill_package` 负责版本、激活和回滚，插件成员继续由 `plugin_manage` 管理。\n\nmanaged Skill 执行时，宿主可提供保留变量 `SKILL_DATA_DIR` 作为私有持久数据目录。可移植核心不得把它设为用户必填配置或硬编码宿主路径；shared\u002Fworkspace 同名候选不继承 managed 环境和数据。安装包禁止符号链接、FIFO 和其他特殊文件。managed 资源读取及命令执行持有读租约，写入、激活和卸载等待该读取结束。\n",{"name":5,"version":23,"description":7},"1.3.0","main","538f75a39df62b23ea9c7927bc5afe7741ff05a4","core-skills\u002Fskill-installation","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench","https:\u002F\u002Fgithub.com\u002Fkkda49","2026-10-18 04:59:59",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add kkda49\u002FAgentDock-Workbench --skill skill-installation",{"tool":36,"command":37},"bunx","bunx skills add kkda49\u002FAgentDock-Workbench --skill skill-installation",{"tool":39,"command":40},"pnpm","pnpm dlx skills add kkda49\u002FAgentDock-Workbench --skill skill-installation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-installation\u002FSKILL.md",true,[44],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fskill-security-review.md","REFERENCE","参考文档",8950,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-installation\u002Freferences\u002Fskill-security-review.md",[51,58,65],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":18},"01M7F2596WXYBQMRJSNW1EQMD1","portable-check","Check portable plugin installation without modifying user data.","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Finternal\u002Fplugin\u002Ftestdata\u002Fportable-demo\u002Fskills\u002Fportable-check\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7F252K9C7TJ0PHXTDNSXK6H","skill-authoring","创建、设计、修改、升级、重构和验证 AgentDock Skill 时使用；负责可移植核心、文档、引用、辅助脚本、测试、版本和本地安装验证。","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-authoring\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7F24Y832GFZPH5SCRV86XDM","agentdock-user-guide","当用户询问 AgentDock 是什么、如何使用、配置在哪里、不同平台或安装方式怎样修改配置并生效、如何重启或验证配置、如何发现并配置 Codex\u002FClaude\u002FGrok 等 Coding Agent 的 ACP，以及常见运行问题时使用；覆盖 macOS Desktop、Windows Desktop、Linux 服务、Docker 和直接运行二进制，不用于源码开发与贡献流程。","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002FSKILL.md",[],[]]