你正在为 Caveman Cloud 标记此仓库的LLM工作流。一个工作流是代码执行的一件“工作”——例如“回复支持工单”、“构建夜间摘要”、“运行评估套件”——而不是某个技术名称。每个网关请求都可以携带一个工作流标签;未标记的流量会全部落入一个 unlabeled-workflow 桶中。你的任务:找到工作流,起好名字,连接标签,并验证一切正常。
这会修改代码,因此必须通过用户的正常评审流程:先提出表格,用户同意后再应用。 在已经标记过的仓库上重新运行必须不产生任何更改(幂等)。
此技能由操作者触发。一个 unlabeled-traffic Cave Plan观察报告仅用于查看,不会创建建议文件、提案或草稿PR。不要推断遥测数据选择了某个调用点或授权了编辑。独立盘点仓库,呈现标签表格,等待用户批准后再修改代码。
步骤1 — 盘点工作流
从仓库的入口点遍历,而不是从其导入开始:
- 调用LLM的HTTP/RPC处理器(直接调用或通过中间层)
- 定时任务:cron定义、队列消费者、Worker、调用LLM代码的GitHub Actions
- CLI命令和脚本(
scripts/、bin/、package.json脚本) - 真正消耗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:使用每次跟踪的
workflow选项,或者单任务服务构造的客户端上的defaultWorkflow。 - 原生提供商SDK(OpenAI/Anthropic/LangChain/LiteLLM/Vercel):在已经携带
x-cave-api-key的defaultHeaders/default_headers/extra_headers块中添加"x-cave-workflow": "<slug>"。被多个任务共享的客户端 → 在每次调用时传递请求头(上述所有SDK都支持按请求覆盖请求头),或者为每个任务创建自己的独立客户端。 - 包装后的编码代理(
caveman wrap):在调用点(cron行、CI步骤)使用--workflow <slug>标志或CAVE_WORKFLOW=<slug>环境变量。 - 原始HTTP:将
x-cave-workflow请求头添加到请求中。
在调用方处标记,保持diff最小化,与仓库风格一致。如果某个调用点根本没有通过Caveman网关路由,不要为其打标签——在报告的“未连接”部分列出(标签仅随网关流量传输;连接是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: <the labeled path you actually exercised, and what you observed>
Lands at: <DASHBOARD>/activity?tab=workflows — each row appears as that workflow
next runs. Anything still unlabeled shows as `unlabeled-workflow`.
Not wired (no gateway routing, so no label): <list or "none">
Marked review: <slugs whose purpose was inferred from filenames, or "none">
如果完全没有找到任何LLM入口点:直接说明,并指向设置技能(<docs origin>/docs/agent-setup.md),而不是编造一个表格。