用途
caveman-discover 用于为某个代码仓库标记其 LLM 工作流，供 Caveman Cloud 使用。其目标是把代码实际执行的一项项“工作”（job）识别出来，并在网关请求上写入对应的工作流标签，让 Caveman Cloud 按工作流而非单一未标记桶来分组支出。这里的“工作流”指代码执行的一项任务，例如“回答一张支持工单”“生成夜间摘要”“运行评测套件”，而非某项技术。每个网关请求都可以携带一个工作流标签；未标记的流量全部落入同一个 unlabeled-workflow 桶。
由于该技能会修改代码，因此必须走用户常规的评审流程：先提出标签表格，待用户同意后再应用。对已经标记过的仓库重新运行必须不产生任何变化（幂等）。
该技能由操作者主动调用。未标记流量的 Cave Plan 观察仅供审阅，不会创建建议文件、提案或 Draft PR。不应据此推断遥测选中了某个调用点或授权了修改。需要独立盘点仓库、呈现标签表格，并在修改代码前等待用户批准。
主要能力与步骤
第 1 步 — 盘点工作流
从仓库的入口点而非导入关系出发遍历：
- 调用 LLM（直接或经由多层间接调用）的 HTTP/RPC 处理器
- 定时任务：cron 定义、队列消费者、worker、调用 LLM 代码的 GitHub Actions
- CLI 命令与脚本（scripts/、bin/、package.json scripts）
- 消耗真实 token 的评测/测试工具
- 框架内的独立 agent 或 chain（每个 LangGraph 图、每个 crew、每个 agent 定义通常各自是一个工作流）
一个工作流 = 人类会命名的一项工作。同一个请求处理器内的十个调用点是同一个工作流；一个被三个作业共用的 llm.ts 辅助文件则是三个工作流（在调用方而非共享辅助文件中标记）。
第 2 步 — 命名
Slug 语法（由网关强制）：小写 [a-z0-9_-]，1–96 字符。命名“工作”而非“技术”：
- 好的示例：support-reply、nightly-digest、pr-review、eval-suite、onboarding-email
- 不好的示例：openai-calls（技术名）、main（没有信息）、SupportReply（不合语法）、johns-test-3（不会长期有效）
名称基本是永久的——之后重命名会拆分支出历史。当某个工作的用途无法从代码中看清时，根据文件名推导 slug 并在表格中将其标记为 review，而不是编造用途。
第 3 步 — 先提议，后应用
先呈现如下表格并请求继续：
| workflow | job | where | how it gets labeled |
|---|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |
然后用该调用点可用的最轻量机制接入每个标签：
- @caveman-ai/sdk / caveman_cloud SDK：per-trace workflow 选项，或在单一作业服务构建的客户端上使用 defaultWorkflow。
- 原始 provider SDK（OpenAI/Anthropic/LangChain/LiteLLM/Vercel）：在已经携带 x-cave-api-key 的同一 defaultHeaders / default_headers / extra_headers 块中加入 "x-cave-workflow": "<slug>"。若共享客户端被多个作业使用，则按调用传入该 header（上述每个 SDK 都支持按请求覆盖 header），或给每个作业各自的轻量客户端。
- 被包装的编码 agent（caveman wrap）：在调用位置（cron 行、CI 步骤）使用 --workflow <slug> 标志或 CAVE_WORKFLOW=<slug> 环境变量。
- 原始 HTTP：在请求中加入 x-cave-workflow header。
标记调用方，保持 diff 最小，匹配仓库风格。如果某个调用点根本没有经过 Caveman 网关路由，就不要标记它——在报告的“not wired”中列出（标签只随网关流量传递；接入是 caveman-setup 技能的职责）。
第 4 步 — 验证
运行仓库已有的任何一种方式去实际走通一条已标记路径（一个测试、一个开发脚本、一次 curl）。然后确认：请求仍然成功（网关对无效标签会以 400 cave_invalid_request_header 拒绝——若是则修正 slug）。已标记的支出会在每个工作流下次运行时出现在 /activity?tab=workflows 的控制面板上；按计划运行的任务会在计划触发时出现，这一点值得在报告中说明，而不是假装它们已实时生效。
第 5 步 — 报告
Workflows labeled
| workflow | job | where |
|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 |
- Verified: <实际走通的已标记路径，以及观察到的情况>
- Lands at: <DASHBOARD>/activity?tab=workflows —— 每个工作流下次运行时其行出现。仍然未标记的内容显示为 unlabeled-workflow。
- Not wired (no gateway routing, so no label): <列表或 “none”>
- Marked review: <用途由文件名推断的 slug，或 “none”>
如果完全没有找到 LLM 入口点：如实说明这一点，并指向 setup 技能（<docs origin>/docs/agent-setup.md），而不是编造一张表格。
适用场景
- 用户提出“discover workflows”等需求时
- 需要将仓库中的 LLM 支出按工作流拆分、而非集中在一个桶中时
- 仓库已接入 Caveman 网关、希望为各 LLM 作业打标签时
限制
- 该技能会改动代码，必须经过用户评审：先提出表格，获批后再应用。
- 对已标记仓库重跑必须无变化（幂等）。
- 未经过 Caveman 网关路由的调用点不应标记，只能在报告中列为 “not wired”。
- 未标记流量的 Cave Plan 观察仅供审阅，不会创建建议文件、提案或 Draft PR；不能据此推断遥测选中了调用点或授权了修改。
- 标签仅在网关流量上传递；接入由 caveman-setup 技能负责。
- 无效标签会被网关以 400 cave_invalid_request_header 拒绝。