mcpField
C
cawplan-qa-commit

cawplan-qa-commit

github.com/cawcut测试与质量1104 次安装2 天前更新
代码仓库

关于 cawplan-qa-commit

为 QA 日报设计的工作流技能，指导收集会话、分配产品与工单、审核内容并上传。支持单日处理及按月查询缺失日期后逐日补交。

主要功能

  1. 01收集 QA 会话并合并人工输入
  2. 02通过确认页分配产品和工单
  3. 03审核报告内容与数据质量
  4. 04查询月份缺失日期并逐日上传

适用场景

  1. 01整理并上传某一天的 QA 日报
  2. 02补齐指定月份尚未上传的 QA 日报

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cawcut/skill-cawplan --skill cawplan-qa-commit

安装后在 Claude Code 中输入/cawplan-qa-commit确认已加载。

详细介绍

CawPlan QA 提交

初始化

cawplan skill check

工作流

此技能支持两种工作流：

  • 单日工作流： 收集 → 分配 → 审查 → 上传
  • 缺失月份工作流： 查询云端某月缺失的 QA 日期 → 仅收集、分配、审查和上传缺失日期

cawplan session collect --mode qa 会自动合并 HTML Review Human Input 事件。不要读取本地 outbox，也不要手动追加或汇总其中的事件；通过现有的 Data quality notes 呈现任何收集器警告。

此技能不涉及的范围（不要自行处理）：

  • cawplan session backfill — 此命令检查的是编码日报（ai-session-usage），而非 QA。请改用 cawplan session qa-backfill --dry-run。
  • 不带 --dry-run 的 cawplan session qa-backfill — CLI 尚未实现批量上传；运行 qa-backfill 时绝不要省略 --dry-run。
  • 工单进度回写（cawplan tickets update --progress_comment）。
  • cawplan session assign --web（使用 git 仓库映射的编码流程）。
  • 单日上传后自动补录当月内容（没有与步骤 7–11 等效的流程）。

支持的单日参数：

  • 不提供日期、today → 今天的日期
  • yesterday、yestoday → 昨天的日期（接受常见拼写错误 yestoday）
  • YYYY-MM-DD → 指定的确切日期

支持的缺失月份参数：

  • last month → 上一个日历月
  • YYYY-MM → 指定的日历月
  • 要求上传或补齐某个月缺失的 QA 日报的自然语言请求 → 对应的日历月

示例：

  • /cawplan-qa-commit
  • /cawplan-qa-commit yesterday
  • /cawplan-qa-commit 2026-08-20
  • /cawplan-qa-commit last month
  • /cawplan-qa-commit 2026-08

如果用户提供了单日参数，请在步骤 1 之前确定日期，并遵循下方的单日工作流。如果用户提供了缺失月份参数，请跳过单日工作流，并遵循下方的缺失月份工作流。如果用户提供了不受支持的参数，请询问有效的日期或月份，不要猜测。

如果用户在一个请求中同时提及 QA 和编码日报，只询问一次他们需要哪一种（仅 QA / 仅编码 / 两者都要）。默认不要同时运行两种技能。

上传前务必收集并展示审查摘要。用户确认审查后再上传（如果分配后已直接展示审查内容，则立即上传）。

权限最小化

  • 将每个逻辑阶段作为一个 shell 代码块运行，而不是拆成许多小命令。
  • 使用 Cursor Agent shell 工具执行任何收集阶段时，请为整个 shell 代码块一次性申请完整网络访问权限（required_permissions: ["full_network"]），因为收集可能会调用 Cursor Dashboard API（位于 cursor.com）。
  • 将所有生成的 qa-daily-*.json 文件存储在系统临时目录中，而不是当前仓库中。这样可以避免仓库写入提示，并使生成的报告文件不会出现在工作树中。
  • 收集、分配、审查和上传时，重复使用同一个工作流专用临时目录。

收集前，创建一个工作流专用 QA 临时目录（如果省略 --output，该目录与 CLI 在 collect --mode qa 中使用的默认目录一致）：

qa_daily_dir="${TMPDIR:-/tmp}/cawplan-qa-daily"
mkdir -p "$qa_daily_dir"
daily_file="$qa_daily_dir/qa-daily-<YYYY-MM-DD>.json"

后续所有收集、分配、审查和上传步骤都使用 qa_daily_dir 下的绝对路径。除非用户明确指定输出路径，否则不要将生成的 QA 日报 JSON 写入当前工作目录。

Collect 还会在每个日报文件旁写入 qa-daily-<YYYY-MM-DD>.excluded.json；qa-assign 会读取此旁置文件中的补充列表。除非你有意丢弃被排除会话的上下文，否则不要手动编辑或删除此旁置文件。

缺失月份工作流

当用户要求上传／填充某月缺失的 QA 报告，或提供月份参数（如 last month 或 YYYY-MM）时，使用此工作流。

步骤 M1 — 确定月份范围：

  • 对于 last month，使用上一个日历月的第一天和最后一天。
  • 对于过去的 YYYY-MM，使用该月的第一天和最后一天。
  • 对于当前的 YYYY-MM，使用该月第一天至今天。
  • 绝不包含所请求月份之外的日期。

步骤 M2 — 查询云端缺失日期：

cawplan session qa-backfill --from <YYYY-MM-01> --to <YYYY-MM-last-or-today> --dry-run

仅使用此次试运行中的 missing_dates。不要收集或覆盖已上传的日期。如果 missing_dates 为空，请告知用户所请求月份没有缺失的 QA 报告，然后停止。

missing_dates 是日历日期缺口列表（不排除周末和节假日）。向用户展示该列表；用户可以跳过自己未工作的日期。

步骤 M3 — 以有限并发收集缺失日期：

collect_concurrency="${CAWPLAN_COLLECT_CONCURRENCY:-5}"
i=0
for date in <date1> <date2> ...; do
  cawplan session collect --date $date --mode qa --output "$qa_daily_dir/qa-daily-$date.json" &
  i=$((i + 1))
  if [ $((i % collect_concurrency)) -eq 0 ]; then
    wait
  fi
done
wait

使用有限并发，因为每次收集都可能调用 Cursor Dashboard API。默认并发数为 5；仅在网络或 Cursor API 不稳定时降低 CAWPLAN_COLLECT_CONCURRENCY。

步骤 M4 — 分配产品／工单：

按日期顺序，对每个新收集的缺失日期文件运行 产品／工单分配，每次运行一个 qa-assign。等待每条分配命令完成后，再开始处理下一个日期（QA 分配目前每条命令仅支持一个文件）。

步骤 M5 — 审核：

对于将要上传的每个缺失日期，上传前都要展示 审核内容约定 中所述的完整审核内容。不要只展示统计表。

步骤 M6 — 上传缺失报告：

按日期顺序，逐个上传每个新收集的缺失日期文件：

cawplan session qa-upload --file "$qa_daily_dir/qa-daily-<YYYY-MM-DD>.json"

上传后，报告所请求的月份、已上传日期、每份上传报告中的 QA 会话数量，以及每个服务器响应代码。不要跨越月份边界。

单日工作流

步骤 1 — 收集：

daily_file="$qa_daily_dir/qa-daily-<YYYY-MM-DD>.json"
cawplan session collect --date <YYYY-MM-DD> --mode qa --output "$daily_file"

步骤 2 — 产品／工单分配：

从收集生成的文件中打开 QA 分配确认页面（没有 git 项目列，仅显示产品和工单）：

cawplan session qa-assign --file "$daily_file"

将 qa-assign 作为后台／非阻塞 shell 任务运行（例如 Bash run_in_background: true），绝不要以前台调用的方式直接运行——该命令会在等待浏览器输入时空闲最多 10 分钟；如果前台调用一直等待，可能会在用户完成操作前被 shell 的作业控制挂起，留下一个仍占用端口的失效进程。

在用户完成浏览器操作之前，始终只运行一个 qa-assign 命令。用户点击 Save assignments、点击 Close、在终端按 Ctrl+C，或者本地分配服务器达到 10 分钟超时后，命令就会退出。

如果针对同一个 daily_file 的上一个分配命令仍在运行，不要重新运行 qa-assign，即使它已经等待了很长时间也不行。长时间等待意味着页面正在等待用户操作，并不代表命令失败。如果需要告知进度，请让用户在已打开的分配页面中保存或关闭，然后等待现有命令退出或超时后再继续。

如果分配页面无法加载，或者上一次运行似乎卡住了，请先检查是否有已停止的进程（ps aux | grep "session qa-assign"；STAT 为 T 表示进程已挂起，不再提供服务），然后再判断命令是否失败。只有进程确实已停止时才终止并重新启动；不要仅因为进程仍在等待就这样做。

页面允许用户：

  • 确认已收集的 QA 会话（会话 ID、Agent、技能层级——可能为空、测试点数量、需求）
  • 在最右侧的 Action 列中使用 Ignore / Undo。被忽略的会话仍保留在原处，显示为灰色行和灰色状态圆点；其产品／工单控件会被禁用，但不会清除值。更改仅在点击 Save assignments 后持久化，只应用于此每日文件，并会在重新收集时重置。原始会话数据会保留。对于没有 review_stats 的旧每日文件，必须先重新收集才能使用 Ignore；请显示该错误，不要上传过时文件。
  • 通过下拉菜单为每个活跃会话调整一个产品
  • 编辑工单显示 ID
  • 可选地从仅包含提交／空白项的排除列表中添加会话（无需手动输入会话 ID）

步骤 3 — 工单上下文检查：

报告时不要要求用户手动提供工单 ID。cawplan session collect --mode qa 会从会话的 human_inputs 中解析明确的工单引用，包括 CawPlan 问题 URL 和显示 ID；用户保存时，分配页面会将显示 ID 解析为内部 ticket_ids。

检查 $daily_file 时，提及分配完成后已有的任何 sessions[].ticket_ids 和 sessions[].ticket_display_ids。工单上下文必须来自明确的人工输入引用或分配页面编辑；不要通过关键词搜索或猜测工单。

步骤 4 — 审查：

上传前，展示 Review content contract 中描述的完整审查内容。不要只显示统计表。

步骤 5 — 上传：

cawplan session qa-upload --file "$daily_file"

原样输出服务器响应，包括成功时返回的任何 report_id UUID。上传后不要运行当前月份的缺失日期查询，也不要进行额外回填。

Review content contract

ignored: true 的会话会保留在本地以便撤销，但不会上传，包括其中的人工输入和统计数据。在下方的审核中，只使用不含 ignored: true 的会话及其人工输入；另行说明被忽略的会话数量。review_stats 是本地核算元数据，不属于 QA 工作内容。如果没有剩余的活跃会话，请说明将跳过上传；不要上传，也不要更改现有的云端报告。

上传前，请包含：

  • 基本信息：日期、作者、QA 会话总数、Agent、总费用。
  • 总体摘要：用 2–4 句话说明各会话开展了哪些 QA 工作（验证的需求、产出的测试点／用例、涉及的工单）。QA 负载中没有顶层 summary 字段——请根据会话和 human_inputs[].content 推导。
  • 会话审核：对每个重要会话，包含 session_title、Agent、存在时的 display_time_range、费用、skill_layers、需求／测试点／测试用例数量、product_id 和工单显示 ID。用 1–2 句话说明开展了哪些工作；不要只列标题和数量。
  • 分配说明：说明是否从补充列表添加了会话，并确认每个活跃会话都已关联产品。
  • 数据质量说明：skill_layers 为空的会话数量；collect 期间打印的已排除会话（仅限仅有提交记录或为空的会话，如有）以及用户是否在分配页面补充了会话；collect 的 stderr 警告；缺少费用的会话；分配页面上未能解析的工单显示 ID。

不要使用 category 或 topic 等仅适用于编码的字段来总结 human_inputs——QA 负载不包含这些字段。

产品／工单分配

  • 网页确认时，始终使用 cawplan session qa-assign --file <absolute-qa-daily-file>。不要使用 collect --mode qa --assign（这会重新收集），也不要使用 cawplan session assign --web（这是带有 git 项目映射的编码流程）。
  • 产品选择使用与编码洞察相同的 CawPlan 产品目录，但不含 git 项目关联。产品选择器（数据源与 cawplan session products 相同）会排除 controls 数组中不含 coding-insights 的产品——如果用户想要的产品缺失，请告知用户该产品尚未启用编码洞察；不要猜测替代产品，也不要在 JSON 中手动修改 product_id。
  • 一个会话只能关联一个产品。分配页面会阻止保存，直到每个活跃会话都已从列表中选择产品。
  • 保存时，分配页面会通过 Cloud 将工单显示 ID 解析为内部 ticket_ids。无法解析的显示 ID 会导致保存失败并返回错误——请将该错误告知用户，不要上传过期文件。

规则

  • 此技能中的每条收集命令都必须包含 --mode qa。
  • 不得捏造会话数据。只能包含本地 Agent 生成的内容，以及用户在任务页面上明确编辑的内容。
  • 不得将编程临时路径（cawplan-ai-daily / ai-daily-*.json）用于 QA 日报。
  • 如果使用 --file / daily_file，JSON 必须包含 schema: "qa-session.1"、author 和 date。
  • 保留 QA 架构允许的原始 human_inputs 字段（content、assistant_message、session_id、start_time、end_time）。绝不可添加 category、topic 或其他仅供编程使用的键。
  • 绝不可在 JSON 文件中用摘要内容替换原始 human_inputs。摘要只能出现在上传前的对话式审核中。
  • 不得通过关键词搜索或猜测来推断收集命令和任务页面未能确定的工单、产品或需求。
  • 此工作流中不得使用 cawplan session report、cawplan session backfill 或 cawplan session assign --web。
  • 使用 cawplan session qa-backfill 时只能搭配 --dry-run 进行缺口检测。按日期通过 collect → qa-assign → review → qa-upload 上传缺失日期；不得在未指定 --dry-run 的情况下调用 qa-backfill。
  • 上传单日数据后，不得运行当月自动回填。
  • 如果用户只说「提交日报」，且未提及 QA/测试相关内容，不要使用此技能——改用 cawplan-coding-commit。

确认

上传后，显示：

  • 服务器确认的日报日期。
  • 上传文件中的 QA 会话数。
  • 如果服务器返回 report_id，则显示该值。
  • Code 字段（SUCCESS / FAILURE）。
  • 如果为 FAILURE，则原样显示错误消息。

参考资料

  • references/CAWPLAN_OPEN_API.md

评论

支持 Markdown