chore: import zh skill release-openclaw-plugin-testing

2026-07-13 21:36:37 +08:00
commit 2c30b33596
3 changed files with 221 additions and 0 deletions
@@ -0,0 +1,9 @@
+# WeHub 来源说明
+
+- Skill 名称：`release-openclaw-plugin-testing`
+- 中文类目：由功能规格/PRD 生成测试策略与 QA 计划
+- 上游仓库：`steipete__clawdis`
+- 上游路径：`.agents/skills/release-openclaw-plugin-testing/SKILL.md`
+- 上游链接：https://github.com/steipete/clawdis/blob/HEAD/.agents/skills/release-openclaw-plugin-testing/SKILL.md
+- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
+- 原作者、版权和许可证信息以上游仓库为准
@@ -0,0 +1,208 @@
+---
+name: release-openclaw-plugin-testing
+description: 规划并执行 OpenClaw 插件的发布前验证，涵盖捆绑插件、包制品、生命周期命令、doctor/fix、配置往返、网关启动、SDK 兼容性、Docker E2E、包验收以及 Testbox 验证。
+---
+
+# OpenClaw 发布前插件测试
+
+当用户询问插件发布信心、插件生命周期全面检查、包制品插件验证，或「发布前我们还应该测试什么？」时使用本技能。它是对 `openclaw-testing` 的补充；在选择最经济的安全运行器或调试失败的流水线时，也应同时使用那个技能。
+
+## 目标
+
+将插件系统作为产品表面来验证，而不仅仅是源码测试：
+
+- 捆绑插件生命周期：安装、查看、启用、禁用、卸载
+- 从干净的 `HOME` 环境测试包制品行为
+- doctor/fix/配置验证及其幂等性
+- 配置发现与配置往返
+- 状态/日志可见性及诊断
+- 网关启动/引导及插件元数据快照
+- 面向真实外部插件的公共 SDK 兼容性
+- 仅在存在安全凭证时进行准实时 provider/channel 探测
+
+## 前置检查
+
+在 OpenClaw 仓库根目录下执行：
+
+```bash
+pnpm docs:list
+git status --short --branch
+readlink node_modules
+pnpm changed:lanes --json
+```
+
+在 `.codex/worktrees` 下的 Codex 工作树中，`node_modules` 必须是指向主 OpenClaw 检出目录的符号链接。请勿在此处运行 `pnpm install`。对于大规模或包密集型的验证，请使用 Blacksmith Testbox 或 GitHub Actions。
+
+## 运行器选择
+
+优先按以下顺序选择：
+
+1. **GitHub Package Acceptance** —— 用于可安装包的产品验证。
+2. **`ci-build-artifacts-testbox.yml` Testbox** —— 当 Docker/包流水线需要预先填充的 `dist`、`dist-runtime` 及包缓存时使用。
+3. **`ci-check-testbox.yml` Testbox** —— 用于源码检查、定向 Vitest、包边界检查或聚焦的 Docker 流水线。
+4. **仅本地定向命令** —— 用于小规模格式/静态/单元探测。
+
+避免在陈旧的稀疏工作树上运行耗时的包 Docker 流水线。如果 Testbox 同步报告数百个文件变更或开始删除包输入，请停止并从当前 `main` 分支预热一个新盒子，或切换到 Package Acceptance。
+
+## 现有基线
+
+在编写新的覆盖率之前，先运行或验证以下内容：
+
+```bash
+OPENCLAUB_TESTBOX=1 pnpm check:changed
+pnpm run test:extensions:package-boundary:canary
+pnpm run test:extensions:package-boundary:compile
+pnpm test:docker:plugins
+OPENCLAW_PLUGINS_E2E_CLAWHUB=0 pnpm test:docker:plugins
+pnpm test:docker:plugin-update
+pnpm test:docker:bundled-channel-deps:fast
+```
+
+如需完整的捆绑安装/卸载验证，请对打包的全面检查进行分片：
+
+```bash
+OPENCLAW_BUNDLED_PLUGIN_SWEEP_TOTAL=8 \
+OPENCLAW_BUNDLED_PLUGIN_SWEEP_INDEX=<0-7> \
+pnpm test:docker:bundled-plugin-install-uninstall
+```
+
+当前预期的打包范围：分片 `0-7` 共 116 个公共捆绑插件。私有 QA 插件仅以源码模式存在，除非包显式包含它们。
+
+## 信心矩阵
+
+使用此矩阵进行发布前签字确认。记录通过/失败、运行 URL/Testbox ID、包 SHA/版本，以及跳过的实时测试原因。
+
+| 测试面 | 验证方式 | 首选运行器 |
+| --- | --- | --- |
+| 包制品 | Package Acceptance `suite_profile=package` 或自定义流水线 | GitHub Actions |
+| 捆绑生命周期 | 8 分片 `test:docker:bundled-plugin-install-uninstall` | Testbox 或发布 Docker |
+| 外部插件 | `test:docker:plugins` 和 `plugins-offline` | Testbox/包验收 |
+| 更新无操作 | `test:docker:plugin-update` | Testbox/包验收 |
+| 通道运行时依赖 | `test:docker:bundled-channel-deps:fast` 加关键通道 | Testbox/包验收 |
+| Doctor/fix | 预置错误配置 + `doctor --fix --non-interactive` | 新建 Docker/Testbox 测试框架 |
+| 配置往返 | `config set/get`、inspect、doctor、reload、对比哈希 | 新建 Docker/Testbox 测试框架 |
+| 网关引导 | 干净 `HOME`、插件组启用/禁用、JSON 状态 | 新建 Docker/Testbox 测试框架 |
+| SDK 兼容性 | 使用 SDK 子路径的目录、tgz 及 `file:` 外部插件 | `test:docker:plugins` 加新的冒烟测试 |
+| 准实时 | 仅对当前环境存在的凭据执行脱敏后的 provider/channel 探测 | Testbox 实时流水线 |
+
+## Package Acceptance 计划
+
+在验证发布分支、测试版或候选包时使用：
+
+```bash
+gh workflow run package-acceptance.yml \
+  --repo openclaw/openclaw \
+  --ref main \
+  -f workflow_ref=main \
+  -f source=ref \
+  -f package_ref=<branch-or-sha> \
+  -f suite_profile=custom \
+  -f docker_lanes='plugins-offline plugin-update bundled-channel-deps-compat doctor-switch update-channel-switch config-reload mcp-channels npm-onboard-channel-agent' \
+  -f telegram_mode=mock-openai
+```
+
+对已发布的测试版验证使用 `source=npm -f package_spec=openclaw@beta`。除非发布流程另有说明，否则将 `workflow_ref` 保持为当前可信的测试框架代码。
+
+## 新的 Testbox 测试框架计划
+
+如果需要更高的确定性，可以添加或运行一个 `plugin-lifecycle-matrix` Docker 流水线，该流水线使用一个包 tarball 和分片后的插件列表。每个插件：
+
+1. 从干净的 `HOME` 开始。
+2. 捕获 `plugins list --json`。
+3. `plugins install <id>`。
+4. `plugins inspect <id> --json`。
+5. `plugins disable <id>`，然后断言已禁用状态可见。
+6. `plugins enable <id>`（配置必需的插件若无配置则跳过）。
+7. `plugins registry --refresh`。
+8. `doctor --non-interactive`。
+9. `plugins uninstall <id> --force`。
+10. 断言没有残留的配置项、allow/deny 记录、安装记录、托管目录或捆绑的 `dist/extensions/...` 加载路径。
+11. 断言诊断信息不包含 `level: "error"`，且输出对疑似秘密值进行了脱敏处理。
+
+将 `memory-lancedb` 特殊处理：它是配置必需的。首先断言安装时若没有嵌入配置则不会启用它，然后再运行一个配置后的用例。
+
+## Doctor/Fix 矩阵
+
+预置错误状态，要求 `doctor --fix --non-interactive` 修复它们，然后再次运行 doctor 并要求幂等性：
+
+- 过时的 `plugins.allow`
+- 过时的 `plugins.entries`
+- 指向缺失通道插件的过时通道配置
+- 无效的 `plugins.entries.<id>.config`
+- `plugins.load.paths` 中的打包捆绑路径
+- 过时的 `plugins.installs`
+- 禁用的通道/插件配置不应暂存运行时依赖
+- root 拥有的全局包树应保持不变
+
+## 网关引导矩阵
+
+在 Docker 中以干净状态启动打包的 OpenClaw：
+
+- 启用 provider 插件，无凭据：就绪但带警告，不崩溃
+- 通道插件配置为禁用：不暂存运行时依赖
+- 启用启动激活插件：就绪并反映在状态中
+- 单个无效插件配置：坏插件被跳过/隔离，其余插件正常工作
+
+断言：
+
+- 网关达到就绪状态
+- `openclaw status --json` 包含插件诊断信息
+- `openclaw plugins inspect --all --json` 可解析
+- 包树未被修改
+- 日志中不包含原始令牌
+
+## 配置往返代表
+
+使用有代表性的插件家族进行深度配置往返测试，而非每个插件：
+
+- providers：`openai`、`anthropic`、`mistral`、`openrouter`
+- channels：`telegram`、`discord`、`slack`、`whatsapp`
+- memory：`memory-lancedb`
+- 功能/运行时：`browser`、`acpx`、`tokenjuice`
+
+对每个代表：
+
+1. 尽可能通过 CLI 写入配置。
+2. 通过 `config get` 或 JSON 读回配置。
+3. 运行 `plugins inspect`。
+4. 运行 `doctor --non-interactive`。
+5. 如适用，触发网关配置重载。
+6. 比较无操作命令前后的配置哈希。
+
+## 外部 SDK 冒烟测试
+
+在包 Docker 流水线中，创建小型外部插件并通过以下方式安装：
+
+- 本地目录
+- `.tgz`
+- `file:` npm 规范
+
+覆盖 CJS 和 ESM 两种格式，以及至少一个导入了 `openclaw/plugin-sdk/*` 子路径的插件。断言 `plugins inspect` 能够看到其工具、网关方法、CLI 命令或服务。
+
+## 准实时探测规则
+
+在进行准实时工作之前，在 Testbox 中获取允许的环境变量并生成一份脱敏的可用性矩阵：仅标记存在/缺失，绝不暴露值。
+
+仅对已存在的凭据运行探测。优先使用 auth/catalog/status 探测，而非发送用户可见的消息。如果探测可能联系到外部用户、频道或工作空间，请停止并向用户询问。
+
+## 报告
+
+按以下格式报告：
+
+```text
+package/ref:
+tbx ids / run urls:
+matrix:
+  bundled lifecycle:
+  package acceptance:
+  doctor/fix:
+  gateway bootstrap:
+  config round-trip:
+  sdk external:
+  live-ish:
+failures:
+skips:
+next highest-value gap:
+```
+
+当失败源于 Testbox 同步/环境损坏而非产品行为时，应明确指出，并通过干净的重新运行或与当前 main 分支对比来证明。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenClaw Plugin Pre-Release Testing"
+  short_description: "Plan plugin release validation"
+  default_prompt: "Use $release-openclaw-plugin-testing to plan or run pre-release OpenClaw plugin validation across package, lifecycle, doctor, gateway, SDK, and live-ish proof."