client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
72817f6cdde474d3d6372ca1a4627e2cf98d4c9f
skill-template/development/CHECKLIST.md
chendelian 72817f6cdd
All checks were successful
技能自动化发布 / release (push) Successful in 6s
Details
Release v1.0.123: document cron empty-selection branch for selectionMode optional
2026-10-07 14:33:01 +08:00

20 KiB
Raw Blame History

技能交活验收 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 是否需要在任务中心查看进度或结果：是 / 否
  • S0-7 外部系统账号、数据、设备与操作权限的授权来源：
  • S0-8 是否包含提交、付款、删除、审批、发布、发送等不可逆副作用：是 / 否
  • S0-9 入口定位表（见 PRODUCT_SURFACES.md / REQUIREMENTS §0.1）：已填写 / 未填写
  • S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）
  • S0-11 业务行生命周期（见 references/WORK_ITEM_STATUS.md / REQUIREMENTS §0.3）：有处理队列且已声明状态→角色映射 / 不适用
  • S0-12 HTML 页面报告（见 references/ACTIONS.md「HTML 页面报告」）：壳子页 assets/html/pages/*.html / 快照 html/*.html + render-html / 不适用

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 「教程」可按真实顺序跟做（准备 → 分入口步骤 → 失败怎么办）；结构见 TUTORIAL_SURFACES.md
  • A2-4 P1 「演示」结构完整（有演示信息位；无视频则标明暂无，不假装有）
  • A2-5 P0 「更新日志」能对应到当前交付版本
  • A2-6 P0 平台/Agent 侧说明中，常见用户意图的触发方式与真实能力一致（短操作 vs 长任务不混淆）
  • A2-7 P0 「说明」Tab（README.md）不含分步操作（1/2/3）、Agent 话术块、「入口一/二」专章；操作指引指向「使用教程」
  • A2-8 P0 「教程」Tab 覆盖 REQUIREMENTS §0.1 / actions.json 中所有「挂」的入口（数据管理 / 对话；结构见 TUTORIAL_SURFACES.md）
  • A2-9 P0 无 cron 时教程有「不需要定时」+ 理由；有 cron 时教程写清如何配置
  • A2-10 P1 教程主能力对照表与 actions.json 的 label 一致
  • A2-11 P1 若有数据管理主路径：准备/载入/导入类能力在对应表 toolbar 可见；教程不以 skill-detail 为唯一主路径
  • A2-12 P0 说明/教程正文不以 # 技能名 或 # 技能名 · 使用教程 开篇（宿主页头/Tab 已有）；主分节用 ##，不要把原 ## 升成 #（见 TUTORIAL_SURFACES.md §0.1）

3. 主能力行为（所有技能）

  • A3-1 P0 主成功路径能按宣称完成核心动作（至少 1 次完整闭环）
  • A3-2 P0 缺参或非法输入时稳定失败（可读错误，不假成功）
  • A3-3 P1 失败可诊断：能从任务记录/提示判断失败阶段，而非只有“失败了”
  • A3-4 P0 同一能力从已声明的不同入口触发时，业务结果一致（不出现入口分叉成两套逻辑）
  • A3-5 P0 REQUIREMENTS 入口定位表已填写；定位为「挂」的入口在 actions.json（及必要表元数据）中有对应声明
  • A3-6 P1 定位为「不挂」的入口有书面理由（不是空白遗漏）

4. 调度与长任务（有 Action 或长任务时适用）

  • A4-1 P0 秒级只读/短操作：不进入任务中心也能完成（若技能提供此类能力）
  • A4-2 P0 长耗时/浏览器/需进度或取消的能力：经 Agent 或技能动作触发后进入任务中心（或平台等价异步队列）
  • A4-3 P0 异步任务在任务中心能看到进行中与结束状态；结束有成功或失败结论
  • A4-4 P1 进行中的进度/步骤信息对用户可理解
  • A4-5 P1 已对外暴露的动作参数覆盖主路径关键输入（无“命令行能做、动作入口不能做”的关键缺口）
  • A4-6 P0 若 Action 需引用业务行（话术/平台/账号等）：参数为 Lookup 下拉（不是手填内部编号）；同库用 local_sql（内联或绑列），跨技能用 skill_cli（勿在本库造镜像缓存表）；可选「自动」可留空提交（见 references/ACTIONS.md）
  • A4-7 P1 若 Action 有互斥采集/操作模式（如「按关键词 / 按主页」）：用 inputSchema 字段级 visibleWhen 联动显隐，勿只靠 description 灰字说明「仅某某时填写」（见 references/ACTIONS.md；勿与 bind.visibleWhen 行菜单、Policy L3 混淆）
  • A4-8 P1 行内/勾选打开的 form：有「已选择」时参数区不应再重复映射主键（inputMapping + readOnly）；需要强制露出时用 revealInForm，禁止用表单 visibleWhen 藏主键（会不提交）
  • A4-9 P1 若同一能力既支持「勾选处理」又支持「按数量从队列领取」：用一个 Action + bind.selectionMode: "optional"（勿拆两个同义顶栏 / cron 按钮）；无勾选可点、有勾选显示「已选择」、空选数量字段用 pickCount 等约定名；定时任务配置页只应出现数量字段、不应出现空的「编号列表」（见 references/ACTIONS.md）
  • A4-10 P0 数据管理弹窗与任务失败文案：全中文产品用语；禁止在 description / confirmation.message / 参数 description / 用户向 message 写英文字段名、CLI 子命令、async/pending/status= 等（Agent 路由放 SKILL.md；见 references/ACTIONS.md「用户可见文案」）
  • A4-11 P1 若行操作应按业务状态显隐（如仅待确认可「采用」、仅已采用可「加入待写」）：用 bind.visibleWhen（对当前行列值求值；存库原始值如 approved）；勿指望 Policy L3；CLI 侧仍须校验状态（见 references/ACTIONS.md「行菜单显隐」）
  • A4-12 P1 若要在表单里翻页勾选一批业务行（文章、平台等）：用 Lookup presentation: "paged_table"（仍是 display_type: lookup，勿新造类型）；skill_cli 的 stdout 为一行 {"items","total"}，0 条也成功退出；该列表命令不要在入口加载整包 platform-kit 或 Playwright（见 references/ACTIONS.md「分页勾选小表」）
  • A4-13 P1 若 Action 有固定小枚举（状态/船司/优先级等）需中文展示：用 enum + enumNames，或绑列复用列 options_json 数组；宿主优先序为绑列 options → enumNames → 纯 enum；禁止为中文展示造假 Lookup（见 references/ACTIONS.md「静态枚举 label」）

5. 账号与浏览器会话（网页 RPA 适用；其他形态标 N/A 或改测等价项）

  • A5-1 P0 未准备好账号/浏览器档案时，主路径失败并提示，不会默默用本机默认浏览器身份跑起来
  • A5-2 P0 登录策略为 required 时：未登录不能把做不成的事当成成功
  • A5-3 P0 交付联调默认能看见浏览器窗口（有头）；不能把无头当作唯一可验收形态
  • A5-4 P1 浏览器窗口启动形态满足交付约定（如最大化或可视区域足够操作与人工介入）；no_viewport=True + --start-maximized，无「先小后大」或右侧留白/scrollbar 后遗症（见 RPA.md §1.2.1）
  • A5-5 P1 验证码或人工确认：有等待与超时；超时后任务失败可理解，不无限挂死或假成功
  • A5-6 P0 NEED_MANUAL 真实站或约定仿真站主路径至少完整跑通 1 次；仅模拟数据通过不算交活
  • A5-7 P0 账号创建后可在宿主数据管理和 account list/get 查到，返回的 profile_dir 在当前用户数据目录真实存在
  • A5-8 P0 每个账号使用独立且稳定的 Profile；不同账号不共用，本机日常浏览器目录不参与运行
  • A5-9 P0 指定账号 ID、指定登录标识和自动选择均取得非空租约；成功、失败、取消和异常路径最终释放；finally 先释租约再关浏览器
  • A5-10 P0 NEED_MANUAL 登录后关闭浏览器并释放租约，再取同一账号重开，登录状态仍有效；失效时明确提示重新登录
  • A5-11 P1 至少两个账号连续或轮换测试通过，Profile、登录态、结果和失败互不污染
  • A5-12 P1 租约冲突、残留租约和账号登录失效能按文档自助定位，不通过删库、删 Profile 或自动换号处理
  • A5-13 P0 NEED_MANUAL 任务中心运行中点「中断」：技能响应 JobStopped 并释放租约（数据管理「账号租约」为 released / 无 active）；立即再跑不因残留租约失败；进度 emit 不得用裸 except Exception 吞掉停止

6. 结果落点（按画像裁剪）

  • A6-1 P0 宣称可追溯时：跑完后任务记录中有对应条目（成功/失败均有）
  • A6-2 P0 宣称写入业务数据或可在数据管理查看时：成功跑完后能看到新业务数据；仅有任务摘要、业务侧仍空 → FAIL
  • A6-3 P1 重复执行同一业务键时，结果符合宣称（更新/去重/追加），无莫名脏数据或静默丢数据
  • A6-4 P1 「零结果成功」与「失败」可区分
  • A6-5 P1 若产出文件：落在约定数据位置且可找到，不丢在不明临时路径
  • A6-6 P0 有业务表时：sqlite_master 中业务表 DDL 不得含 SQLite FOREIGN KEY / REFERENCES；跨表只存业务 id，关联与级联在 repository/service；界面名称用 lookup（见 references/SCHEMA.md）；可跑 validate_template_database / init-db 后自检
  • A6-7 P0 有「处理业务行」类 Action 时（见 WORK_ITEM_STATUS.md）：默认只处理可操作角色状态；成功/失败/跳过/进行中再点处理应拒绝或跳过且不产生重复副作用；重做须人工改回可操作。无处理队列 → N/A
  • A6-8 P0 同上适用时：开始处理后业务表进入进行中；成功回写成功类终态；失败回写失败类终态且失败原因可读（任务成功但业务行仍停在可操作/进行中 → FAIL）
  • A6-9 P1 同上适用时：REQUIREMENTS §0.3（或等价）已填写本技能状态→角色映射；处理类 Action 确认文案写清仅可操作态
  • A6-10 P1 有 HTML 侧栏预览时（S0-12）：预览区横向铺满、无横向滚动条；重新生成后内容与页头时间更新；布局符合 references/ACTIONS.md「宿主预览布局」。无 HTML 报告 → N/A
  • A6-11 P1 业务状态 / 启用类列若用户需要筛表或顶栏搜中文：searchable: 1 且 options_json（或 boolean + options_json）的 value 与存库一致；仅 searchable: 0 则宿主不提供列筛与全局搜索。见 references/SCHEMA.md「列筛选与全局搜索」
  • A6-12 P2 display_type: boolean 的展示列推荐同时配置 options_json 中文 label（如 停用/启用），避免仅靠宿主默认「是/否」；无 boolean 列 → N/A
  • A6-13 P2 账期/月份/生效月等 YYYY-MM 字段用 display_type: year_month（或 Action 同义 format），不要只用 description 写格式却留纯文本框；完整日才用 date
  • A6-13 P0 新技能不得创建 task_logs；过程/进度/业务结果走运行日志、任务中心、业务表（见 LOGGING.md、SCHEMA.md）
  • A6-14 P0 废弃用户可见表时：drop_deprecated_user_table 物理删表 + 清元数据；禁止只删元数据留物理表；有迁移时须提供旧库回归测试（见 SCHEMA.md、tests/samples/test_table_deprecation_migration.py.sample）
  • A6-15 P1 若启用 cellPresentation：旁路表不得出现在数据管理侧栏；整行着色不得铺到详情每个字段；禁止 all×all；tone 闭集。未启用 → N/A（见 references/CELL_PRESENTATION.md）
  • A6-16 P0 若走 MySQL 云库：用户目录 data-sources.json + .env DSN 已配置；Host ≥ 6.9.28；CLI / Action 与数据管理 UI 读写同一库（抽测 list/create）；业务 DDL 支持所选后端。纯 SQLite → N/A（见 references/DATA_SOURCES.md）

7. 可观测与安全观感（所有技能）

  • A7-1 P0 失败提示或任务结论不泄露密码、完整 Cookie、明文 token 等敏感信息
  • A7-2 P0 统一文件日志（运行日志 / jiangchang.log）能定位失败阶段：可见 task_start 与 task_failed|task_success；失败含 error_code=；不只 cli_start
  • A7-3 P0 故意失败一条时，文件日志先有 task_failed/warning，再有 ERROR:CODE 或任务中心失败态
  • A7-4 P1 关键步骤有据可查（能对应到开始/关键节点/结束；RPA 宜有多个 stage=）
  • A7-5 P1 若宣称支持录屏或截图存证：打开开关后关键步骤或失败能留下可查看产物；宣称支持却完全无产物 → FAIL
  • A7-6 P2 用户可见文案偏业务语言，而非大段开发黑话（数据管理弹窗 / 任务失败见 A4-10，更高优先级）
  • A7-7 P2 数据管理技能按钮（toolbar / row / batch）中文名对照 references/ACTIONS.md「Action 按钮中文名」；不与宿主「查看 / 编辑 / 删除」抢名；打开类成功不弹成功条。行业专有按钮名可自创

8. AI + RPA 合规与工业级风控（外部系统技能适用）

  • A8-1 P0 已确认账号、数据、设备和业务操作均在用户或企业授权范围内；边界不明不能以“默认允许”通过
  • A8-2 P0 代码与运行路径不包含破解、反编译、逆向、未授权私有协议、抓包拼隐藏接口、Hook / 注入、验证码破解、设备指纹伪造、撞库、养号、自动换号或代理池规避限制
  • A8-3 P0 验证码、人脸、指纹、短信、U盾、频控、账号风险和权限不足能转人工或安全停止，不自动硬闯
  • A8-4 P0 付款、删除、审批、发布、发送等不可逆动作执行前有明确对象、范围和用户确认
  • A8-5 P1 页面 / 控件加载、保存和业务成功由真实状态判断，不以固定等待代替成功判定
  • A8-6 P1 真实 RPA 两个正常业务动作之间采用约 1～3 秒随机节奏；输入、鼠标和滚动符合正常人工操作方式
  • A8-7 P1 同一账号、Profile 或设备默认串行；批量、频率和运行时长有上限
  • A8-8 P1 只对明确可重试错误做有限重试与递增退避；风险、封禁、权限和结果不明确时不盲目重试
  • A8-9 P1 流程结束先核验业务结果并完成日志 / 截图 / 可选视频，再保留合理结束缓冲后关闭会话
  • A8-10 P1 Agent 能区分成功、部分成功、失败、等待人工、等待确认和主动停止，并用业务语言解释结果
  • A8-11 P0 关键元素均有真实拾取证据和 element map；没有真实 DOM/UIA/XML 时未由 AI 猜 selector
  • A8-12 P0 不可逆动作定位器在目标作用域内唯一；没有用 .first / hwnds[0] / instance=0 掩盖歧义
  • A8-13 P1 页面、窗口、弹窗、iframe、Native/WebView 等作用域明确；列表先定位业务行再定位动作元素
  • A8-14 P1 重启浏览器/软件/App 后关键定位复测通过；动态列表顺序变化不会误点
  • A8-15 P1 定位失败保存截图和 DOM/UIA/XML、候选数量、作用域及目标版本；结构变化时停止而非在线猜新定位器
  • A8-16 P1 所有 fallback 均经过人工验证；图像/OCR/坐标仅在控件树确认不可用后使用

9. 质量门禁与交活底线（所有技能）

  • A9-1 P0 仓库默认测试套件通过（执行技能约定的一键测试命令，如 python tests/run_tests.py -v）
  • A9-2 P0 不以「仅模拟档通过」作为交活依据（有真实档要求时必须真实跑通或书面阶段性豁免）
  • A9-3 P0 NEED_MANUAL 入口定位表中定为「挂」的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过；未在定位表中规划且未声明的入口可标 N/A（须引用定位表理由），禁止用「未声明」掩盖「从未做入口定位」
  • A9-4 P0 对外版本一致（POLICY-RELEASE-001）：SKILL.md version = SKILL_VERSION = 发布 git tag（无前缀）；release.ps1 打 tag 前会硬校验，漏改不得发布；CHANGELOG 有对应小节
  • A9-4b P1 本机宿主验收用根目录 .\sync.ps1 覆盖已安装明文；市场上的最新版本和加密包仍走 .\release.ps1。同步后退出资料管理再打开，不要点技能市场「更新」
  • A9-5 P1 开发者按平台规则能安装并测到该技能（若平台有开发者可见性要求）

10. 报告结尾必填

报告末尾固定三块：

  1. 结论：通过 / 不通过（任意 P0 为 FAIL 或不通过的 NEED_MANUAL → 不通过）
  2. 统计：PASS / FAIL / N/A / NEED_MANUAL 数量；P0 FAIL 列表
  3. 给技术人员的修改清单：仅未通过项，带条目 ID 与期望现象
Reference in New Issue View Git Blame Copy Permalink