nav/ClawSpec

Fork 0

Files

nav 6ba9110f07 docs: rewrite project plan in chinese

2026-04-06 17:55:53 +00:00

18 KiB

Raw Blame History

ClawSpec 项目规划

1. 项目概述

ClawSpec 是一个面向 OpenClaw 插件自动化测试 的框架。

它的目标不是替代插件仓库内部已有的单元测试，而是为 插件在真实 OpenClaw 运行时中的集成行为 提供一套可重复、可编排、可验证的自动化测试方案。

ClawSpec 的核心思路是：

使用配置文件声明测试场景
启动一个或多个 OpenClaw 测试实体（claw unit）
自动安装并配置目标插件
使用一个规则驱动的假模型服务替代真实 LLM
通过规则控制模型回复、工具调用和测试终止时机
在测试结束或超时后自动执行断言与验证脚本
输出稳定、可复现的测试结果和调试产物

它要解决的问题，本质上是：

如何在不依赖真实大模型、不手工搭环境、不靠人工点点点观察日志的前提下，对 OpenClaw 插件做稳定的集成测试。

2. 要解决的问题

目前 OpenClaw 插件测试存在几个现实问题：

插件行为很多不是纯函数，而是依赖 OpenClaw 运行时上下文
插件经常要和模型调用、工具调用、消息路由、配置项共同工作
使用真实 LLM 会引入不确定性、成本和复现困难
手工搭建测试环境成本高，流程不统一
缺少统一的方式描述测试环境、测试输入和预期结果

因此，ClawSpec 需要提供一套标准化能力：

用声明式配置描述测试环境和测试用例
用假模型替代真实 LLM，保证测试稳定性
自动拉起 OpenClaw 运行环境并完成插件安装与配置
支持单实体和多实体协作场景
在测试结束后自动校验结果并生成报告

3. 项目目标

3.1 核心目标

定义一个测试配置文件格式，用于描述 OpenClaw 测试场景
根据配置自动创建一个或多个 OpenClaw 测试实体
自动安装和配置测试所需插件
提供规则驱动的假模型服务，不接真实 LLM
支持单轮和多轮对话测试
支持基于断言和脚本的结果验证
输出稳定、可重现、便于排查的测试产物

3.2 次级目标

在需要时支持不同 OpenClaw 版本的兼容性测试
支持多个 OpenClaw 实体之间的协作测试
为插件开发者提供可复用的示例测试配置
让日常本地插件集成测试足够轻量、足够快

3.3 非目标（至少不在 V1）

替代插件仓库内部单元测试
一上来做图形化管理界面
一上来做分布式大规模并发执行
一上来做性能压测、压力测试、模糊测试
一上来模拟所有模型供应商的全部协议细节

4. 产品定位

ClawSpec 不是一个通用测试框架，也不是一个纯单元测试工具。

它更准确的定位是：

一个面向 OpenClaw 插件生态的、基于场景编排的、确定性集成测试框架。

它关注的对象是以下整体行为：

OpenClaw runtime 本身
已安装插件的行为
模型请求与回复边界
工具调用链路
消息输出
插件对外部系统产生的可观察副作用

所以它测试的不是“某个函数返回值对不对”，而是：

当 OpenClaw + 插件 + 模型交互 + 工具链路一起工作时，最终表现是否符合预期。

5. 核心设计原则

5.1 确定性优先

自动化测试尽量不依赖真实 LLM 的随机性。假模型服务必须成为测试过程中的受控变量。

5.2 运行时真实性

测试目标是接近真实 OpenClaw 运行时，而不是只 mock 插件内部函数。

5.3 声明式配置

测试环境、测试输入、模型规则、断言条件都应尽可能通过配置描述，而不是散落在脚本里。

5.4 默认简单，按需扩展

大部分插件测试只需要一个 claw unit，因此单实体测试应当是默认路径；多实体协作应当支持，但不应让单实体测试变复杂。

5.5 可调试性

每次测试都要尽量留下足够的产物用于排查，比如日志、规则命中记录、工具调用轨迹、验证脚本输出等。

6. claw unit 的定位

这里需要明确一个关键概念：

clawUnits 的存在，主要不是为了同时测试多个版本或多个配置，而是为了支持：

一个插件要作用于多个 OpenClaw 实体
插件行为依赖多个 agent / runtime 协作
测试场景本身需要多个 OpenClaw 节点参与

例如：

A 实体发送消息，B 实体响应
一个插件监听另一个实体的行为
多 agent 协作场景中的插件联动

因此：

绝大多数插件测试应当只需要一个 clawUnit
multi-unit 是为了协作测试，而不是为了把所有变化都塞进一个场景里
如果只是测试版本兼容性或配置差异，更适合通过多个测试场景分别执行，而不是默认依赖多个 unit 同时运行

7. 总体架构

ClawSpec 可以拆成四个核心模块。

7.1 Spec Loader（配置加载器）

负责：

读取测试配置文件
校验配置结构是否合法
标准化字段
生成内部执行计划

7.2 Environment Orchestrator（环境编排器）

负责：

创建 OpenClaw 测试环境
生成和管理 Docker Compose 运行定义
准备工作目录、挂载目录、产物目录
安装插件
写入插件配置
启动和销毁测试环境

7.3 Fake Model Service（假模型服务）

负责：

提供一个供 OpenClaw 调用的模型接口
接收 OpenClaw 发来的模型请求
根据配置规则决定返回什么
生成稳定的文本回复或工具调用
在满足终止条件时调用 test-finished
记录请求、规则命中和输出结果

7.4 Test Runner（测试执行器）

负责：

选择测试用例
注入输入事件或测试消息
收集输出消息、工具调用、日志和事件
判断测试何时结束
执行断言与外部验证脚本
汇总结果并输出报告

8. 测试配置的整体思路

ClawSpec 需要一个统一的配置文件来描述以下内容：

测试环境
一个或多个 claw unit
各 unit 使用的 OpenClaw 版本或镜像
需要安装的插件及配置
测试输入
假模型行为规则
断言和验证脚本

一个建议中的配置结构如下：

{
  "version": "v1",
  "environment": {
    "networkName": "clawspec-net",
    "workspaceRoot": "./.clawspec/workspaces",
    "artifactsRoot": "./.clawspec/artifacts"
  },
  "clawUnits": [
    {
      "unitId": "calendar-agent",
      "openClawVersion": "0.5.0",
      "image": "ghcr.io/openclaw/openclaw:0.5.0",
      "plugins": [
        {
          "pluginName": "harborforge-calendar",
          "installCommand": "openclaw plugins add harborforge-calendar",
          "configs": {
            "backendUrl": "http://fake-backend:8080",
            "agentId": "calendar-test-agent"
          }
        }
      ]
    }
  ],
  "testCases": [
    {
      "testId": "calendar-reminder-basic",
      "targetUnitId": "calendar-agent",
      "timeout": 15000,
      "input": {
        "channel": "discord",
        "chatType": "direct",
        "message": "明天下午3点提醒我开会"
      },
      "modelRules": [
        {
          "receive": ".*明天下午3点提醒我开会.*",
          "action": {
            "type": "tool_call_then_respond",
            "toolName": "harborforge_calendar_create",
            "toolParameters": {
              "title": "开会",
              "time": "tomorrow 15:00"
            },
            "text": "已经帮你记下了"
          }
        },
        {
          "receive": ".*已经帮你记下了.*",
          "action": {
            "type": "tool_call",
            "toolName": "test-finished",
            "toolParameters": {
              "reason": "expected final response observed"
            }
          }
        }
      ],
      "expected": [
        {
          "type": "tool_called",
          "toolName": "harborforge_calendar_create"
        },
        {
          "type": "message_contains",
          "value": "已经帮你记下了"
        }
      ],
      "verifier": {
        "type": "script",
        "path": "./verifiers/calendar-reminder-basic.sh"
      }
    }
  ]
}

这只是方向草案，后续需要再细化为正式 schema。

9. 假模型服务设计

假模型服务是 ClawSpec 的关键能力之一。

如果没有它，测试就会依赖真实模型，带来以下问题：

结果不稳定
工具调用行为不可预测
成本上升
失败难以复现

因此 ClawSpec 里的假模型不应该只是“随便返回一句话”，而应是一个 规则驱动的测试模型。

9.1 假模型的职责

接收 OpenClaw 发来的模型请求
读取当前 test case 对应的规则集
按规则顺序或匹配优先级决定响应动作
返回文本回复、工具调用，或两者组合
在满足结束条件时触发 test-finished
输出详细日志，记录每次命中的规则与返回动作

9.2 规则支持的动作方向

至少应支持：

纯文本回复
工具调用
先工具调用再回复文本
明确结束测试（调用 test-finished）
不匹配时的默认行为（例如返回空结果、报错或记录未命中）

9.3 多轮对话支持

这里也要明确：

多轮对话本身不难，没必要一开始就把它设计成复杂状态机。

一个足够实用且容易落地的规则是：

每个 test case 都必须定义 timeout
每个 test case 的 modelRules 中都必须包含一个测试结束规则
当结束规则被命中时，假模型调用工具 test-finished
只要 test-finished 被观察到，测试就可以进入结果检查阶段
如果在 timeout 时间内没有观察到 test-finished，也应自动停止等待并开始检查结果

这样带来的好处：

可以天然支持多轮对话
不需要一开始就做复杂状态机
测试终止条件明确
超时处理简单统一

换句话说，ClawSpec 的多轮测试机制，第一版完全可以建立在：

规则匹配
显式结束信号 test-finished
统一 timeout

这三件事上。

10. 测试结束机制

ClawSpec 中每个测试用例都应该具备两个结束维度：

10.1 显式结束

由假模型通过工具调用：

test-finished

来表示测试已经到达预期终点。

这代表：

测试逻辑已经跑到设计的结束条件
可以停止继续等待新一轮交互
可以开始执行断言和验证脚本

10.2 超时结束

每个 test case 必须提供 timeout 字段。

如果在超时时间内没有观察到 test-finished，则：

runner 停止继续等待
将当前收集到的日志、消息、工具调用作为测试结果输入
自动开始执行断言和验证脚本

这样做的意义是：

防止测试无限挂起
允许一些“不要求明确结束工具”的场景仍可评估结果
给开发者提供统一的失败诊断入口

11. 验证模型

ClawSpec 至少需要支持两层验证方式。

11.1 内建断言

适合高频常见场景，例如：

message_contains
message_equals
tool_called
tool_called_with
log_contains
exit_code

这些断言由框架直接执行，适合大多数常见插件测试。

11.2 外部验证脚本

适合复杂或高度项目定制的检查，例如：

数据库状态是否正确
某个文件是否生成
某个 HTTP 回调是否发生
某个外部服务状态是否变化

这类场景可以通过：

{
  "verifier": {
    "type": "script",
    "path": "./verifiers/check-result.sh"
  }
}

来执行。

内建断言负责覆盖通用场景，脚本验证负责保留扩展性。

12. 执行流程

一次典型的 ClawSpec 测试流程应当如下：

读取并校验测试配置
准备 workspace、artifacts 等目录
根据配置生成运行环境定义
启动假模型服务
启动目标 OpenClaw unit（单个或多个）
安装并配置目标插件
向目标 unit 注入测试输入
让 OpenClaw 与假模型进行一轮或多轮交互
持续观察是否出现 test-finished
若命中结束信号，则进入结果验证
若超时，则停止等待并进入结果验证
收集日志、消息、工具调用记录和事件轨迹
执行内建断言
如有需要，执行外部验证脚本
输出 pass/fail、摘要和产物路径
按配置决定是否销毁环境

13. 推荐目录结构

ClawSpec/
├── README.md
├── PROJECT_PLAN.md
├── docs/
│   ├── architecture.md
│   ├── spec-schema.md
│   ├── fake-model.md
│   └── runner.md
├── schema/
│   └── clawspec.schema.json
├── examples/
│   ├── basic.json
│   └── multi-unit.json
├── docker/
│   ├── compose.template.yml
│   └── fake-model.Dockerfile
├── src/
│   ├── cli/
│   ├── spec/
│   ├── orchestrator/
│   ├── model/
│   ├── runner/
│   └── report/
├── verifiers/
│   └── examples/
└── .clawspec/
    ├── workspaces/
    └── artifacts/

14. 技术选型建议

14.1 推荐语言

推荐优先使用 TypeScript / Node.js。

理由：

与 OpenClaw 生态更贴近
处理 JSON / schema / CLI 更顺手
实现假模型 HTTP 服务成本低
调用 Docker、OpenClaw CLI、外部脚本都比较方便

14.2 推荐基础库方向

ajv：schema 校验
commander 或 yargs：CLI
execa：子进程与命令调度
fastify 或 express：假模型服务
yaml：未来支持 YAML 配置
vitest：框架自身测试

15. V1 范围建议

第一版应该先打通最小闭环，而不是过早扩张。

15.1 V1 必须具备

读取一个 spec 文件
校验基础 schema
启动一个 OpenClaw test unit
在该 unit 中安装一个或多个插件
应用插件配置项
启动一个假模型服务
注入一条测试输入
支持单轮和多轮交互
要求每个 test case 包含 timeout
要求每个 test case 定义显式结束规则，并通过 test-finished 结束
支持规则驱动文本回复
支持规则驱动工具调用
支持基础断言：
- message_contains
- tool_called
- script verifier
输出日志和 pass/fail 摘要

15.2 V1 可以先不做

图形界面
分布式执行
性能测试
高级 provider 协议仿真
复杂矩阵测试展开
过度复杂的对话状态机

换句话说，V1 只要把：

环境起来
插件装好
假模型能按规则回
测试能结束
结果能校验

这条链路打通，就已经有实际价值。

16. 里程碑建议

Milestone 0：项目初始化

初始化仓库结构
建立基础工程
写 README 和项目规划
明确技术栈

Milestone 1：配置定义

明确 spec 字段设计
编写 docs/spec-schema.md
编写基础 schema 文件
提供一个最小示例

Milestone 2：假模型服务

定义规则结构
实现规则匹配
实现文本和工具调用响应
实现 test-finished 结束机制
实现请求与规则命中日志

Milestone 3：环境编排

启动 OpenClaw 容器或运行实例
安装插件
写入插件配置
管理测试生命周期

Milestone 4：测试执行器

注入测试输入
收集输出和工具调用轨迹
处理 timeout 与结束规则
执行断言和验证脚本
输出报告

Milestone 5：真实插件验证

选一个真实 OpenClaw 插件做端到端样例
验证框架设计是否足够支撑真实需求
记录限制和下一步演进方向

17. 风险与待确认问题

17.1 OpenClaw 模型接入接口

假模型服务想顺利工作，前提是要足够清楚 OpenClaw 调用模型时的接口约定。这一点必须尽早验证。

17.2 插件安装流程差异

不同插件可能需要不同安装方式、初始化步骤、配置项和额外依赖。ClawSpec 需要决定哪些做成通用能力，哪些交给 setup hook 或脚本。

17.3 可观察结果边界

有些插件的结果体现在消息里，有些体现在工具调用里，有些体现在外部系统副作用里。框架需要定义清楚“什么是结果来源”。

17.4 Docker / 镜像策略

需要明确：

基础镜像怎么选
OpenClaw 版本怎么管理
本地开发时插件源码如何挂载
如何兼顾快速迭代和环境稳定性

17.5 规则表达能力

如果规则太简单，复杂插件测不了；如果规则太复杂，配置会很难写。需要在表达能力和可维护性之间找平衡。

18. 成功标准

在第一阶段，ClawSpec 可以被认为成功，如果它满足以下条件：

插件开发者不需要写框架代码就能描述一个测试场景
同样配置在相同环境下能重复得到相同结果
插件集成行为可以在不依赖真实 LLM 的情况下验证
测试失败时能留下足够产物用于定位问题
至少有一个真实插件能够通过 ClawSpec 完成端到端自动化测试

19. 下一步建议产物

在这份项目规划之后，最值得继续补的文档有：

README.md
- 用简洁语言说明项目是什么、解决什么问题、怎么快速开始
docs/spec-schema.md
- 把配置结构正式写清楚
- 明确 clawUnits、testCases、modelRules、timeout、test-finished 等字段
schema/clawspec.schema.json
- 提供一份可以直接用于校验的机器可读 schema
docs/fake-model.md
- 明确假模型服务的输入输出协议、规则匹配方式、结束机制
TASKLIST.md
- 把里程碑拆成可执行任务

20. 总结

ClawSpec 的目标可以概括成一句话：

在真实 OpenClaw 运行时中，用规则驱动的假模型替代真实 LLM，对插件进行稳定、可重复的自动化集成测试。

它的关键价值在于：

用真实 runtime 测集成行为
用假模型消除 LLM 随机性
用声明式配置统一测试场景
用显式结束规则 test-finished + timeout 解决多轮测试收口问题
用断言和脚本验证兼顾通用性与扩展性

如果这个框架做成，它会非常适合作为 OpenClaw 插件开发中的基础测试设施。

18 KiB Raw Blame History Unescape Escape