commit 2c30b33596a18b201143031216c239a28a93c986 Author: wehub-skill-sync Date: Mon Jul 13 21:36:37 2026 +0800 chore: import zh skill release-openclaw-plugin-testing diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..9d7a10e --- /dev/null +++ b/README.wehub.md @@ -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 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..b92e052 --- /dev/null +++ b/SKILL.md @@ -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= \ + -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 `。 +4. `plugins inspect --json`。 +5. `plugins disable `，然后断言已禁用状态可见。 +6. `plugins enable `（配置必需的插件若无配置则跳过）。 +7. `plugins registry --refresh`。 +8. `doctor --non-interactive`。 +9. `plugins uninstall --force`。 +10. 断言没有残留的配置项、allow/deny 记录、安装记录、托管目录或捆绑的 `dist/extensions/...` 加载路径。 +11. 断言诊断信息不包含 `level: "error"`，且输出对疑似秘密值进行了脱敏处理。 + +将 `memory-lancedb` 特殊处理：它是配置必需的。首先断言安装时若没有嵌入配置则不会启用它，然后再运行一个配置后的用例。 + +## Doctor/Fix 矩阵 + +预置错误状态，要求 `doctor --fix --non-interactive` 修复它们，然后再次运行 doctor 并要求幂等性： + +- 过时的 `plugins.allow` +- 过时的 `plugins.entries` +- 指向缺失通道插件的过时通道配置 +- 无效的 `plugins.entries..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 分支对比来证明。 diff --git a/agents/openai.yaml b/agents/openai.yaml new file mode 100644 index 0000000..0c73371 --- /dev/null +++ b/agents/openai.yaml @@ -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."