cawplan-coding-commit

CawPlan 编码提交

初始化

cawplan skill check

工作流

此技能支持两种工作流：

• 单日工作流： 收集 → 分配 → 审查 → 上传 → 回填当月数据
• 缺失月份工作流： 查询云端某个月份缺失的日期 → 仅收集并上传缺失日期的数据

支持的单日参数：

• 不指定日期、today → 今天的日期
• yesterday、yestoday → 昨天的日期（yestoday 是常见拼写错误的可接受写法）
• YYYY-MM-DD → 指定的报告日期
• 要求上传昨天的日报的自然语言请求 → 昨天的日期
• 要求上传指定 YYYY-MM-DD 日期日报的自然语言请求 → 指定日期

支持的缺失月份参数：

• last month → 上一个日历月
• YYYY-MM → 指定的日历月
• 要求上传／补全指定月份缺失日报的自然语言请求 → 指定的日历月

示例：

• /cawplan-coding-commit
• /cawplan-coding-commit yesterday
• /cawplan-coding-commit 2026-06-20
• /cawplan-coding-commit last month
• /cawplan-coding-commit 2026-06

如果用户提供了单日参数，请在步骤 1 之前解析该参数，并在以下所有命令中使用该日期。如果用户提供了缺失月份参数，请跳过单日工作流，并遵循下方的缺失月份工作流。如果用户提供了不受支持的参数，请要求其提供有效日期或月份，不要猜测。

上传前务必收集并呈现 AI 总结的审查结果。审查后无需等待用户再次确认；应立即继续上传。

尽量减少权限请求

尽量减少收集报告时的权限请求：

• 每个逻辑阶段使用一个 shell 块运行，不要拆成许多细小命令。
• 使用 Cursor Agent shell 工具进行任何收集阶段时，为整个 shell 块一次性请求完整网络访问权限（required_permissions: ["full_network"]），因为收集过程可能会调用 cursor.com 上的 Cursor Dashboard API。
• 将生成的每个 ai-daily-*.json 报告存放在系统临时目录中，而不是当前仓库。这样可以避免仓库写入权限提示，并防止生成的报告文件进入工作树。
• 在收集、分配、审查和上传过程中重复使用同一个工作流专用临时目录。
• 对 Web 分配，请在单条 cawplan session assign --web --files ... 命令中批量处理所有文件。不要为每份报告分别启动分配命令。

收集报告之前，通过 CLI 创建一个工作流专用临时目录，以便在 macOS、Linux 和 Windows 上使用相同的命令：

report_dir="$(cawplan session temp-dir)"

后续每个收集、分配、审查和上传步骤中，都使用该目录下的绝对文件路径：

report_file="$report_dir/ai-daily-<YYYY-MM-DD>.json"

除非用户明确提供输出路径，否则不要将生成的日报 JSON 文件写入当前工作目录。

按月份补齐工作流

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

步骤 M1 — 确定月份范围：

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

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

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

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

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

collect_concurrency="${CAWPLAN_COLLECT_CONCURRENCY:-5}"
i=0
for date in <date1> <date2> ...; do
  cawplan session collect --date $date --output "$report_dir/ai-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 — 产品／仓库／工单分配：

对所有新收集的文件运行产品／仓库／工单分配。

步骤 M5 — 工单进度回写：

对每份新收集的缺失日期报告运行下文的工单进度回写，前提是其包含 sessions[].ticket_ids。

步骤 M6 — 上传缺失报告：

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

cawplan session report --file "$report_dir/ai-daily-<YYYY-MM-DD>.json"

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

单日工作流

步骤 1 — 收集：

report_file="$report_dir/ai-daily-<YYYY-MM-DD>.json"
cawplan session collect --date <YYYY-MM-DD> --output "$report_file"

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

对 $report_file 运行 产品／仓库／工单分配，然后完成审核再继续，以便检查或编辑产品、仓库和工单的显示 ID。

步骤 3 — 与用户一起审核报告：

展示 审核内容规范 中所述的完整审核内容。不要只展示统计表。

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

报告过程中不要要求用户手动提供工单 ID。cawplan session collect 会自动解析会话 human_inputs 中明确引用的工单，包括 ticket_id、ticket_display_id、CawPlan 工单 URL 和显示 ID。已解析的工单会保留在 Web 分配页面中供审核；分配时允许选择所选产品的工单，也允许选择同一产品线中其他产品的工单。

审核 $report_file 时，提及已有的任何 sessions[].ticket_ids 和 sessions[].ticket_display_ids。工单上下文应来自明确的人类输入引用或分配页面编辑；不要通过关键词搜索或猜测工单。

步骤 5 — 回写工单进度：

如果 $report_file 中有任何 sessions[].ticket_ids，请运行下方的 工单进度回写。此步骤属于技能工作流，不属于 cawplan session assign --web；分配操作只会将产品／仓库／工单链接保存到每日报告中。

步骤 6 — 上传：

cawplan session report --file "$report_file"

步骤 7 — 查询本月缺失的报告：

cawplan session backfill --from <YYYY-MM-01> --to <YYYY-MM-DD> --dry-run

将报告所属月份的第一天用作 --from，将报告日期用作 --to。向用户展示返回的 missing_dates。如果没有缺失日期，请说明并停止。

步骤 8 — 以有限并发收集每个缺失日期的数据：

以较小的并发上限启动缺失日期的收集：

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

每个日期彼此独立，但不受限制的并行收集可能会使 Cursor Dashboard API 过载并导致超时。默认并发数为 5；网络不稳定时，将 CAWPLAN_COLLECT_CONCURRENCY 降至 1 或 2。

步骤 9 — 为缺失报告分配产品／仓库／工单：

对所有新收集的文件运行 产品／仓库／工单分配。

步骤 10 — 为缺失报告回写工单进度：

对每个包含 sessions[].ticket_ids 的新收集文件，运行下方的 工单进度回写。

步骤 11 — 上传缺失报告：

按日期顺序逐个上传文件：

cawplan session report --file "$report_dir/ai-daily-<YYYY-MM-DD>.json"

补录范围必须限定在已上传报告所属的月份内，不得跨越月份边界。

---

工单进展回写

仅在产品／仓库／工单分配已审核并保存后，才执行此步骤。请勿依赖 cawplan session assign --web 更新工单详情；此回写由本技能负责。

1. 读取报告 JSON 文件，并扫描 sessions[].ticket_ids。

2. 按 ticket_id 对会话分组。

3. 通过 Cloud 解析所有分组工单：

   cawplan tickets search --unique_ids "<ticket_id_1>,<ticket_id_2>" --page_size 100
   

4. 对每个分组，只有当 Cloud 结果包含 unique_id、product_id 和 version_id，且分组中每个会话的 product_id 都与返回工单的 product_id 匹配时，才回写。跳过无法解析的工单、缺少 product_id／version_id 的工单，以及产品不匹配的工单。

5. 总结分组会话的 human_inputs，生成精简的 HTML progress_comment。不要照搬原始提示词，也不要只罗列分类后的主题。对每个工单分组：

   • 从报告级别的 human_inputs[] 中收集与分组 session_id 匹配的内容，并收集分组中每个 session.human_inputs[] 的内容。
   • 对每条收集到的人工输入，只读取 content；不要读取或总结用于工单进展回写的 assistant_message。
   • 仅用 1-3 条简短要点总结最重要的变更结果、决策／方向和尚未解决的后续事项。
   • 每条要点应简洁，最好为一句话且少于 120 个字符。
   • 仅将会话元数据（如标题、Agent、项目、文件数量和代码行数变化）用作辅助背景。
   • 不要单独添加“更新自……”段落；让评论内容保持紧凑。
   • 最终 HTML 中不要插入空行。相邻标签应紧密衔接；<p>、<ul> 和 <li> 元素之间不要留空行。
   • 如果分组会话没有人工输入，则跳过工单回写，并说明没有可供回写的人工输入依据。

   使用以下格式：

   <p><strong>AI session progress CWP-14471</strong> (2026-07-09)</p><ul><li><strong>Guardrails:</strong> only attach Cloud-resolved tickets that match the session product.</li><li><strong>Write-back:</strong> summarize human inputs in this skill before uploading the report.</li></ul>
   

   如果有 sessions[].ticket_display_ids，请在标题中使用其中的显示 ID。将用户／会话文本放入 HTML 前先进行转义。要点应根据 human_inputs[].content 总结为易读文字，而不是照搬原始输入文本。

6. 使用 CLI 将 HTML 写入 progress_comment，不要直接通过 HTTP 写入：

   cawplan tickets update "<product_id>" "<version_id>" "<ticket_id>" --progress_comment "$progress_comment"
   

   优先使用步骤 3 搜索结果中的 unique_id。CLI 也接受工单 display_id（例如 CAWP-20544），并会自动解析后再执行 PUT；若未经解析便在原始 HTTP 请求中使用 display_id，即使是产品负责人也会触发 RBAC INSUFFICIENT_PERMISSIONS。

回写后，报告哪些工单显示 ID 已更新、哪些已跳过。不要因某个工单回写被跳过或失败就中断上传工作流；请说明失败情况，并继续上传报告。

---

审核内容要求

在请求确认上传前，必须包含以下部分：

• 基本信息：日期、作者、各 Agent 的会话总数、总费用、变更文件数、涉及的仓库。
• 整体摘要：如果报告中有 summary 字段，则使用该字段；否则根据会话、仓库和人工输入撰写 2-4 句话。
• 会话审核：对每个重要会话，列出标题／名称、Agent、时间范围、费用、已变更的仓库／文件，并用 1-2 句话说明完成了哪些工作。不要只列标题／时间／费用。
• 人工输入重点：按类别（decision、direction、correction、planning）总结重要的 human_inputs，必要时附上有代表性的提示词。
• 数据质量备注：说明缺失／估算费用、API 警告、没有费用的会话或空模型。

如有帮助，可用精简表格列出数字，但始终要包含叙述性摘要和会话审核文本。

产品／仓库／工单分配

每份报告在收集或检查后、审核／上传前，都要按此流程处理，无论会话是否已有 product_id。Web 分配页面也可用于检查或编辑工单显示 ID。 不要询问用户选择哪种分配模式。始终使用本地 Web 分配流程。如果报告中的每个会话都已有产品（例如，已根据现有映射自动分配），cawplan session assign --web 会显示提示并立即退出，而不会打开页面；请直接继续审核。只有在用户明确要求仍要打开页面时（例如要编辑工单），才传入 --force。

对于一份报告，运行：

cawplan session assign --file <absolute-ai-daily-file> --web

对于多份报告，优先使用：

cawplan session assign --web --files <absolute-ai-daily-file-1> --files <absolute-ai-daily-file-2>

在 Agent shell 中运行一条命令，包含所有待处理的报告文件，这样本地分配页面就会自动在浏览器中打开，并且所有报告会一起处理。始终将此命令作为后台／非阻塞 shell 任务启动（例如，Bash 中使用 run_in_background: true），绝不能以前台普通调用的方式运行——该命令会空等浏览器输入，最长可达 10 分钟；如果前台调用一直等待，可能会在用户完成操作前被 shell 的作业控制挂起，留下仍占用端口的失效进程。在用户完成浏览器操作前，始终只运行一条 cawplan session assign --web 命令。用户点击 Save assignments、点击 Close、在终端按 Ctrl+C，或本地分配服务达到 10 分钟超时后，命令就会退出。

要等待命令退出，启动时记录 PID，并轮询该 PID（绝不能轮询命令行）。bash/zsh/Git Bash 示例，使用 kill -0：cawplan session assign --web --files ... > "$dir/assign.log" 2>&1 & echo $! > "$dir/assign.pid"，然后执行 pid=$(cat "$dir/assign.pid"); for i in $(seq 1 58); do kill -0 "$pid" 2>/dev/null || { echo exited; break; }; sleep 10; done; tail -5 "$dir/assign.log"。绝不要使用 pgrep -f "session assign" 或 ps | grep "session assign" 进行轮询：轮询 shell 自身的命令行包含该字符串，因此会匹配自身，循环就无法检测到命令退出（即使用户已经保存，循环也会运行至完整超时）。在 PowerShell 等其他 shell 中，使用等效的 PID 检查方式（例如 Get-Process -Id $pid -ErrorAction SilentlyContinue），并采用相同的循环结构。如果轮询循环结束时 PID 仍然存活，请继续轮询；不要假定命令已完成。

启动后台分配命令后，只要命令仍在运行，就不要结束 Agent 轮次或返回最终回复。通过短间隔轮询，让同一轮 Agent 任务持续运行。如果用户需要与页面交互，请将 URL 作为中间更新发送，并继续轮询；不得将用户输入视为工作流已完成。命令退出后，检查其退出代码，并在同一轮任务中继续完成审核、工单进度回写、上传以及当月回填检查。只有在这些步骤完成后，或在报告确实发生分配错误后，才能结束此轮任务。后台 shell 进程本身不会唤醒后续 Agent 轮次，因此仅返回 URL 并结束此轮任务是无效的。

分配命令因页面已保存、关闭、被中断或超时而退出后，请自动使用磁盘上的报告文件继续完成审核、工单进度回写和上传。分配页面关闭后，不要再次要求用户确认。如果页面关闭时未进行编辑，请保留采集器已有的产品／仓库／工单映射并继续；只有报告文件缺失或分配命令报告了实际错误时才停止。如果 Agent 轮次在分配命令退出前被中断，下一轮必须先检查现有进程和报告文件，然后从分配命令已退出的状态继续；不要声称已自动完成上传。 当同一份或多份报告已有分配命令正在运行时，不要再次运行 cawplan session assign --web，即使它已经等待了很长时间也不行。长时间等待意味着页面正在等待用户操作，而不是命令失败。如果需要报告进度，请告知用户保存或关闭已经打开的分配页面以完成操作，然后等待现有命令退出或超时，再继续。

如果分配页面加载失败，或之前的运行似乎卡住了，请先检查进程是否已停止（使用记录的 PID 运行 ps -o pid,stat,cmd -p "$pid"；STAT 为 T 表示进程已挂起，不再提供服务），再判断命令是否失败。只有进程确实已停止时，才终止并重新启动；如果进程仍在等待，则不要这样做。

页面会显示 session / human inputs / product / repo / tickets，要求选择产品，支持仅分配产品，可编辑工单显示 ID，还可以按 https://github.com/owner/repo 格式关联新的 GitHub 仓库 URL。

产品选择器（以及 cawplan session products）已排除 controls 数组不包含 coding-insights 的任何产品——这类产品无法保存会话数据，因此不会被提供为分配目标。不要通过分配到其他产品或直接编辑 JSON 的 product_id 来绕过此限制；如果用户想要的产品未列出，请告知他们该产品尚未启用 coding insights，不要猜测替代产品。

规则

• 如果未提供 --date，则默认为今天。
• 不要捏造会话数据。只能报告 Agent 在本地生成的内容。
• 如果在采集期间出现产品/仓库分配提示，只能使用用户明确选择的选项或现有映射。
• Web 分配流程要求为每个会话选择产品；仓库选择为可选项。
• 除非用户明确选择或确认了确切的产品和 GitHub 仓库 URL，否则绝不要创建新的产品-仓库映射。
• 如果使用了 --file，文件必须包含 author（Git 用户名）和 date（YYYY-MM-DD）字段。
• 单日上传成功后，按照步骤 7–11 执行：使用 --dry-run 查询该报告当前月份中缺失的日期，然后针对每个缺失日期分别采集 → 分配 → 上传。不要在不带 --dry-run 的情况下使用 cawplan session backfill。
• 单日工作流期间，不要自动回填之前月份或跨月范围。只有用户明确提供月份参数，或要求上传/补齐该月份缺失的报告时，才使用按月查缺工作流。
• 保留 human_inputs 中的原始字段（例如 start_time、end_time、assistant_message、files_changed、lines_added、lines_deleted）。
• 绝不要用摘要内容替换原始 human_inputs。在此工作流的任何环节，都应原样保留每个 human_inputs[].assistant_message 和 human_inputs[].category/topic/topic_confidence/topic_reason/topic_source，不得重新分类、改写或总结。

确认

上传后，报告：

• 服务器确认的报告日期。
• 已审核文件摘要中每个 Agent 的会话数量。
• Code 字段（SUCCESS / FAILURE）。
• 如果为 FAILURE，请显示错误消息。

参考资料

• references/CAWPLAN_OPEN_API.md