需要按 LLM 工作流拆分 Caveman Cloud…

在 Caveman Cloud 中把仓库里的 LLM 调用按业务工作流而非单一 `unlabeled-workflow` 桶统计花费时使用。

适用场景

解决思路

1. 先确认这是 operator-invoked 任务；`unlabeled-traffic` Cave Plan observation 只是 review-only，不创建 advisory file、proposal 或 Draft PR；不要推断 telemetry 已选中 callsite 或授权编辑。独立盘点仓库，先展示标签表，等用户批准后再改代码。
2. 把 workflow 定义为代码执行的一项 job（如“answer a support ticket”“build the nightly digest”“run the eval suite”），不是技术；每个 gateway 请求都可携带 workflow label；未标注流量都会落到 `unlabeled-workflow` 桶。
3. 从入口点而不是 imports 遍历仓库。
4. 盘点会调用 LLM（直接或经过多层）的 HTTP/RPC handlers。
5. 盘点 scheduled jobs：cron definitions、queue consumers、workers、会调用 LLM 代码的 GitHub Actions。
6. 盘点 CLI commands 和 scripts（`scripts/`、`bin/`、package.json scripts）。
7. 盘点会消耗真实 token 的 eval / test harnesses。
8. 盘点 framework 内 distinct agents 或 chains：每个 LangGraph graph、每个 crew、每个 agent definition 通常都是自己的 workflow。
9. 划分时一个 workflow = 一个人会命名的一项 job：同一个 request handler 内十个 callsites 是一个 workflow；一个共享 `llm.ts` helper 被三个 job 使用则是三个 workflow（在 callers 处标，绝不在共享 helper 上标）。
10. Slug 必须符合 gateway 语法：小写 `[a-z0-9_-]`，1–96 字符。
11. 命名 job，不命名技术：好例子 `support-reply`、`nightly-digest`、`pr-review`、`eval-suite`、`onboarding-email`；坏例子 `openai-calls`（技术）、`main`（没意义）、`SupportReply`（无效）、`johns-test-3`（不会长久）。
12. 名字几乎永久：以后重命名会拆分花费历史。当 job 目的无法从代码看清时，从文件名推导 slug，并在表中标 `review`，不要杜撰目的。
13. 先呈现表格并询问是否继续，表格列为 `workflow`、`job`、`where`、`how it gets labeled`；示例行包括 `support-reply` 在 `src/bot/reply.ts:41` 使用 reply client 的 `defaultHeaders`，`nightly-digest` 在 `jobs/digest.ts:12` 使用 digest client 的 header，`eval-suite (review)` 在 `scripts/eval.ts:8` 使用 invocation 的 env override。
14. 用户同意后，在各自 callsite 用当时可用的最轻量机制接线 label。
15. `@caveman-ai/sdk` / `caveman_cloud` SDK：使用 per-trace `workflow` option，或在 single-job service 构造的 client 上使用 `defaultWorkflow`。
16. Raw provider SDKs（OpenAI/Anthropic/LangChain/LiteLLM/Vercel）：把 `"x-cave-workflow": "<slug>"` 加到原本已携带 `x-cave-api-key` 的同一个 `defaultHeaders` / `default_headers` / `extra_headers` block。
17. 如果 shared client 被多个 job 使用，则每次调用都传 header（上述每个 SDK 都接受 per-request header overrides），或给每个 job 自己的 thin client。
18. Wrapped coding agents（`caveman wrap`）：在 invocation site（cron line、CI step）使用 `--workflow <slug>` flag 或 `CAVE_WORKFLOW=<slug>` env。
19. Raw HTTP：在 request 中加 `x-cave-workflow` header。
20. 标注 callers，保持 diff 最小，匹配仓库风格。
21. 如果 callsite 根本没有经过 Caveman gateway，就不要标注它；在报告中列到 "not wired" 下（labels 只在 gateway traffic 上传递；wiring 是 caveman-setup skill 的职责）。
22. 验证：运行仓库已有的方式去 exercise 一条已标注路径（一个 test、dev script、一条 curl）。
23. 确认请求仍然成功；如果 gateway 因 invalid label 返回 400 `cave_invalid_request_header`，修正 slug。
24. 确认 labeled spend 出现在 dashboard `/activity?tab=workflows`：每个 workflow 下次运行时出现；定时任务在 schedule 触发时出现；报告中要说明这一点，不要假装它们已 live。
25. 输出报告，包含：`## Workflows labeled` 表格（列为 `workflow`、`job`、`where`）；`Verified:` 实际 exercise 的 labeled path 和观察结果；`Lands at:` `<DASHBOARD>/activity?tab=workflows`，每个 row 在 workflow 下次运行时出现，仍未标注的显示为 `unlabeled-workflow`；`Not wired (no gateway routing, so no label):` 列表或 "none"；`Marked review:` 从文件名推断目的的 slug 或 "none"。
26. 如果完全找不到 LLM entry points：明确说找不到，并指向 setup skill（`<docs origin>/docs/agent-setup.md`），不要制造表格。
27. 这个流程会改代码，必须走用户正常 review：先提议表，用户同意后再应用。
28. 在已标注仓库上重新运行必须不改变任何东西（idempotent）。

适用边界 · 注意事项

• 仓库没有 LLM entry points 时不适用：不要编造 workflow 表，应说明没有，并指向 `<docs origin>/docs/agent-setup.md`。
• 调用点没有经过 Caveman gateway 时不适用：不要给它打 label，只列入报告 "not wired"，接入路由是 caveman-setup skill 的职责。
• 只有 `unlabeled-traffic` Cave Plan observation 时不适用：它是 review-only，不创建 advisory file、proposal 或 Draft PR，不能当作已选中 callsite 或已授权编辑。