diff --git a/CHANGELOG.md b/CHANGELOG.md index 18b02cd..e792cf6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段 +## 1.0.56 + +- 新增第三方交活验收清单 `development/CHECKLIST.md`（观察结果、不重复开发规范） +- 验收报告强制写入仓库根目录 `acceptance-reports/YYYYMMDD-HHMMSS-acceptance.md`，便于技术人员按 FAIL 项整改 + ## 1.0.55 - 模板 `.env.example` 默认 `OPENCLAW_TEST_TARGET=real_rpa`；四档保留；明确 mock 只保单测/CI，mock 通 ≠ 交活 diff --git a/SKILL.md b/SKILL.md index ecab0e7..c4e052c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板（通用业务版） description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.55 +version: 1.0.56 author: 深圳匠厂科技有限公司 metadata: openclaw: diff --git a/acceptance-reports/README.md b/acceptance-reports/README.md new file mode 100644 index 0000000..893a44e --- /dev/null +++ b/acceptance-reports/README.md @@ -0,0 +1,30 @@ +# 验收报告目录（acceptance-reports） + +本目录存放**技能交活验收报告**，供技术人员查看并按未通过项整改。 + +## 谁写、写什么 + +- 验收人（或 AI 编程工具）对照 `development/CHECKLIST.md` 执行验收后，**必须**在本目录落盘报告。 +- 标准与条目定义见：`development/CHECKLIST.md`（含强制输出规则）。 + +## 命名（强制） + +```text +YYYYMMDD-HHMMSS-acceptance.md +``` + +示例：`20260722-175000-acceptance.md` + +- 使用验收执行时的本地时间 +- 不要覆盖旧报告；保留历史便于对比是否修好 + +## 技术人员怎么用 + +1. `git pull` 拉取含报告的最新代码（或验收人推送后的提交） +2. 打开本目录中**时间戳最新**的一份 `*-acceptance.md` +3. 只看文末「给技术人员的修改清单」及所有 `FAIL` / 未通过的 `NEED_MANUAL` +4. 改完后告知验收人复验；新一轮会再生成一份新时间戳报告 + +## 模板仓说明 + +本 `skill-template` 仓库通常不产生业务验收报告；此目录随模板复制到新技能后使用。 diff --git a/development/CHECKLIST.md b/development/CHECKLIST.md new file mode 100644 index 0000000..62915a9 --- /dev/null +++ b/development/CHECKLIST.md @@ -0,0 +1,146 @@ +# 技能交活验收 Checklist（第三方视角） + +checklist_version: 1.0 + +本清单用于**旁人 / 测试 / AI 编程工具**对任意业务技能做交活验收。 +它描述的是「验什么、怎样算过」，**不是**开发规范摘要。写法与实现约束见同目录其他文档。 + +--- + +## 验收输出强制规则（凡执行本清单必须遵守） + +> 面向 AI 与人工验收员：只要开始按本 Checklist 验收，下列规则**全部强制**，无需用户在提示词里再重复。 + +1. **必须落盘报告**，禁止只在对话里给出口头结论。 +2. **报告目录（唯一合法位置）**：技能仓库**根目录**下的 `acceptance-reports/` + （与 `development/`、`scripts/` 平级；**禁止**写到 `development/`、`tests/`、临时目录或其他路径。） +3. **报告文件名（唯一合法格式）**：`YYYYMMDD-HHMMSS-acceptance.md` + 示例：`20260722-175000-acceptance.md` + 时间取验收执行时的本地时间；**禁止**使用 `report.md`、`验收.md`、无时间戳的文件名。 +4. 若 `acceptance-reports/` 不存在，**先创建该目录再写入**。 +5. 报告**开头**必须写明： + - 完整相对路径：`acceptance-reports/YYYYMMDD-HHMMSS-acceptance.md` + - 技能 slug、当前 git 提交短哈希（若可得）、`checklist_version` +6. 报告正文必须**逐条**对应下方条目，每条给出：`PASS` / `FAIL` / `N/A` / `NEED_MANUAL`，并附简短证据（文件路径、命令、观察结果）。 +7. 报告末尾必须有「给技术人员的修改清单」：只列出未通过项（`FAIL` 与未通过的 `NEED_MANUAL`），按 P0 → P1 → P2 排序。 +8. **禁止修改业务代码**来“凑”验收通过；本清单的执行结果是报告，不是改代码。 +9. 若用户只说「按 Checklist 验收」而未指定路径：仍必须遵守本节省略规则，不得省略落盘。 + +**结果取值** + +| 值 | 含义 | +|----|------| +| PASS | 已满足 | +| FAIL | 不满足 | +| N/A | 本技能不适用（须说明原因） | +| NEED_MANUAL | 须人工点选/真机；报告中写清已做或未做 | + +**级别** + +| 级别 | 含义 | +|------|------| +| P0 | 不通过不可交活 | +| P1 | 限期整改 | +| P2 | 体验建议 | + +--- + +## 0. 技能画像（验收前先填，用于裁剪） + +先根据技能实际情况勾选；后续章节不适用则整项标 `N/A` 并注明原因。 + +- [ ] S0-1 交互形态：纯本地 / API / 网页RPA / 桌面RPA / 手机RPA / 编排（调兄弟技能） +- [ ] S0-2 目标站登录策略：required / optional / not_needed / 不适用 +- [ ] S0-3 是否依赖账号会话（account-manager 或等价 Profile）：是 / 否 +- [ ] S0-4 持久化：无 / 仅任务日志 / 另有业务表 +- [ ] S0-5 Skill Action：无 / 仅同步短任务 / 含异步长任务 +- [ ] S0-6 是否需要在任务中心查看进度或结果：是 / 否 + +--- + +## 1. 安装与可运行（所有技能） + +- [ ] A1-1 **P0** 按平台方式加载/安装后，技能可被识别（有名称，能打开详情或执行入口） +- [ ] A1-2 **P0** 健康检查（如 `health`）能跑完且结果可读；缺关键条件时有明确失败提示，而非空白崩溃 +- [ ] A1-3 **P0** 版本查询（如 `version`）返回的版本与对外宣称一致 +- [ ] A1-4 **P1** 若有用户可见配置：说明可读；按说明改关键项后行为符合说明 + +--- + +## 2. 对外说明是否自洽（所有技能） + +- [ ] A2-1 **P0** 市场「说明」能让非开发者理解：做什么、给谁用、开始前准备什么 +- [ ] A2-2 **P0** 「说明/教程」不以开发目录、内部实现细节作为用户主路径 +- [ ] A2-3 **P1** 「教程」可按真实顺序跟做（准备 → 步骤 → 失败怎么办） +- [ ] A2-4 **P1** 「演示」结构完整（有演示信息位；无视频则标明暂无，不假装有） +- [ ] A2-5 **P0** 「更新日志」能对应到当前交付版本 +- [ ] A2-6 **P0** 平台/Agent 侧说明中，常见用户意图的触发方式与真实能力一致（短操作 vs 长任务不混淆） + +--- + +## 3. 主能力行为（所有技能） + +- [ ] A3-1 **P0** 主成功路径能按宣称完成核心动作（至少 1 次完整闭环） +- [ ] A3-2 **P0** 缺参或非法输入时稳定失败（可读错误，不假成功） +- [ ] A3-3 **P1** 失败可诊断：能从任务记录/提示判断失败阶段，而非只有“失败了” +- [ ] A3-4 **P0** 同一能力从已声明的不同入口触发时，业务结果一致（不出现入口分叉成两套逻辑） + +--- + +## 4. 调度与长任务（有 Action 或长任务时适用） + +- [ ] A4-1 **P0** 秒级只读/短操作：不进入任务中心也能完成（若技能提供此类能力） +- [ ] A4-2 **P0** 长耗时/浏览器/需进度或取消的能力：经 Agent 或技能动作触发后进入任务中心（或平台等价异步队列） +- [ ] A4-3 **P0** 异步任务在任务中心能看到进行中与结束状态；结束有成功或失败结论 +- [ ] A4-4 **P1** 进行中的进度/步骤信息对用户可理解 +- [ ] A4-5 **P1** 已对外暴露的动作参数覆盖主路径关键输入（无“命令行能做、动作入口不能做”的关键缺口） + +--- + +## 5. 账号与浏览器会话（网页 RPA 适用；其他形态标 N/A 或改测等价项） + +- [ ] A5-1 **P0** 未准备好账号/浏览器档案时，主路径失败并提示，不会默默用本机默认浏览器身份跑起来 +- [ ] A5-2 **P0** 登录策略为 required 时：未登录不能把做不成的事当成成功 +- [ ] A5-3 **P0** 交付联调默认能看见浏览器窗口（有头）；不能把无头当作唯一可验收形态 +- [ ] A5-4 **P1** 浏览器窗口启动形态满足交付约定（如最大化或可视区域足够操作与人工介入） +- [ ] A5-5 **P1** 验证码或人工确认：有等待与超时；超时后任务失败可理解，不无限挂死或假成功 +- [ ] A5-6 **P0** **NEED_MANUAL** 真实站或约定仿真站主路径至少完整跑通 1 次；仅模拟数据通过不算交活 + +--- + +## 6. 结果落点（按画像裁剪） + +- [ ] A6-1 **P0** 宣称可追溯时：跑完后任务记录中有对应条目（成功/失败均有） +- [ ] A6-2 **P0** 宣称写入业务数据或可在数据管理查看时：成功跑完后能看到新业务数据；仅有任务摘要、业务侧仍空 → **FAIL** +- [ ] A6-3 **P1** 重复执行同一业务键时，结果符合宣称（更新/去重/追加），无莫名脏数据或静默丢数据 +- [ ] A6-4 **P1** 「零结果成功」与「失败」可区分 +- [ ] A6-5 **P1** 若产出文件：落在约定数据位置且可找到，不丢在不明临时路径 + +--- + +## 7. 可观测与安全观感（所有技能） + +- [ ] A7-1 **P0** 失败提示或任务结论不泄露密码、完整 Cookie、明文 token 等敏感信息 +- [ ] A7-2 **P1** 关键步骤有据可查（能对应到开始/关键节点/结束） +- [ ] A7-3 **P1** 若宣称支持录屏或截图存证：打开开关后关键步骤或失败能留下可查看产物；宣称支持却完全无产物 → **FAIL** +- [ ] A7-4 **P2** 用户可见文案偏业务语言，而非大段开发黑话 + +--- + +## 8. 质量门禁与交活底线（所有技能） + +- [ ] A8-1 **P0** 仓库默认测试套件通过（执行技能约定的一键测试命令，如 `python tests/run_tests.py -v`） +- [ ] A8-2 **P0** 不以「仅模拟档通过」作为交活依据（有真实档要求时必须真实跑通或书面阶段性豁免） +- [ ] A8-3 **P0** **NEED_MANUAL** 已声明的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过 +- [ ] A8-4 **P1** 对外版本一致：详情、version、更新日志、发布标签能对上 +- [ ] A8-5 **P1** 开发者按平台规则能安装并测到该技能（若平台有开发者可见性要求） + +--- + +## 9. 报告结尾必填 + +报告末尾固定三块： + +1. **结论**：通过 / 不通过（任意 P0 为 FAIL 或不通过的 NEED_MANUAL → 不通过） +2. **统计**：PASS / FAIL / N/A / NEED_MANUAL 数量；P0 FAIL 列表 +3. **给技术人员的修改清单**：仅未通过项，带条目 ID 与期望现象 diff --git a/development/README.md b/development/README.md index 247ad78..ce6dcd7 100644 --- a/development/README.md +++ b/development/README.md @@ -14,6 +14,7 @@ | 4 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 | | 5 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 | | 6 | 匠厂安装后，按已声明入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) | +| 7 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) | 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。业务仓也可直接从自建 Gitea clone，见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §4 来源 A。 @@ -35,6 +36,7 @@ 10. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读） 11. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读） 12. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定 +13. [`CHECKLIST.md`](CHECKLIST.md) — **交活验收清单（第三方视角）**；报告输出到 [`../acceptance-reports/`](../acceptance-reports/) Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。 diff --git a/scripts/util/constants.py b/scripts/util/constants.py index 1498593..f8ef584 100644 --- a/scripts/util/constants.py +++ b/scripts/util/constants.py @@ -1,6 +1,6 @@ """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。""" SKILL_SLUG = "your-skill-slug" -SKILL_VERSION = "1.0.55" +SKILL_VERSION = "1.0.56" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.2"