caveman-discover

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are labeling this repository's LLM workflows for Caveman Cloud. A workflow is a job the code performs — "answer a support ticket", "build the nightly digest", "run the eval suite" — not a technology. Every gateway request can carry a workflow label; unlabeled traffic all lands in one

unlabeled-workflow

bucket. Your job: find the workflows, name them well, wire the labels, and verify nothing broke.

This changes code, so it goes through the user's normal review: propose the table first, apply after the user agrees. Re-running on an already-labeled repo must change nothing (idempotent).

This skill is operator-invoked. An

unlabeled-traffic

Cave Plan observation is review-only and does not create an advisory file, proposal, or Draft PR. Do not infer that telemetry selected a callsite or authorized an edit. Independently inventory the repository, present the labeling table, and wait for the user's approval before changing code.

你正在为Caveman Cloud标记此仓库的LLM工作流。工作流指代码执行的任务——例如“回复支持工单”“生成夜间摘要”“运行评估套件”——而非某项技术。每个网关请求都可携带工作流标签；未标记的流量将全部归入

unlabeled-workflow

类别。你的任务是：找出所有工作流、为其合理命名、配置标签并验证未出现任何问题。

此操作会修改代码，因此需遵循用户的常规审核流程：先提交表格提案，经用户同意后再执行。在已标记过的仓库中重新运行此操作必须不会产生任何变更（幂等性）。

此技能由操作员触发。

unlabeled-traffic

的Cave Plan观测仅用于审核，不会生成建议文件、提案或草稿PR。请勿推断遥测数据已选定调用站点或授权编辑。需独立完成仓库盘点、提交标签表格，并等待用户批准后再修改代码。

Step 1 — Inventory the workflows

步骤1 — 盘点工作流

Walk the repo from its entry points, not from its imports:

HTTP/RPC handlers that call an LLM (directly or through layers)
Scheduled jobs: cron definitions, queue consumers, workers, GitHub Actions that invoke LLM code
CLI commands and scripts (
```
scripts/
```
,
```
bin/
```
, package.json scripts)
Eval / test harnesses that burn real tokens
Distinct agents or chains inside a framework (each LangGraph graph, each crew, each agent definition is usually its own workflow)

One workflow = one job a human would name. Ten callsites inside the same request handler are one workflow; one shared

llm.ts

helper used by three jobs is three workflows (label at the callers, never the shared helper).

从仓库的入口点而非导入项开始梳理：

调用LLM的HTTP/RPC处理器（直接调用或通过多层调用）
定时任务：调用LLM代码的cron定义、队列消费者、工作进程、GitHub Actions
CLI命令与脚本（
```
scripts/
```
、
```
bin/
```
、package.json中的脚本）
消耗真实令牌的评估/测试工具
框架内的独立Agent或链（每个LangGraph图、每个crew、每个Agent定义通常都是独立的工作流）

一个工作流对应一个人类可命名的任务。同一请求处理器中的十个调用站点属于同一个工作流；被三个任务共用的

llm.ts

辅助工具对应三个工作流（需在调用方添加标签，而非在共用辅助工具上添加）。

Step 2 — Name them

步骤2 — 命名工作流

Slug grammar (the gateway enforces this): lowercase

[a-z0-9_-]

, 1–96 chars. Name the job, not the tech:

Good:

support-reply

nightly-digest

pr-review

eval-suite

onboarding-email

Bad:
```
openai-calls
```
(tech),
```
main
```
(says nothing),
```
SupportReply
```
(invalid),
```
johns-test-3
```
(won't age)

Names are forever-ish — renaming later splits the spend history. When a job's purpose isn't clear from the code, derive the slug from the file name and mark it

review

in the table rather than inventing a purpose.

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

，而非凭空编造用途。

Step 3 — Propose, then apply

步骤3 — 提交提案，然后执行

Present this table and ask to proceed:

| 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 |

Then wire each label with the lightest mechanism available at that callsite:

@caveman-ai/sdk / caveman_cloud SDK: per-trace
```
workflow
```
option, or
```
defaultWorkflow
```
on the client a single-job service constructs.
Raw provider SDKs (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): add
```
"x-cave-workflow": "<slug>"
```
to the same
```
defaultHeaders
```
/
```
default_headers
```
/
```
extra_headers
```
block that already carries
```
x-cave-api-key
```
. Shared client used by several jobs → pass the header per call (every SDK above accepts per-request header overrides), or give each job its own thin client.
Wrapped coding agents (
```
caveman wrap
```
):
```
--workflow <slug>
```
flag or
```
CAVE_WORKFLOW=<slug>
```
env at the invocation site (cron line, CI step).
Raw HTTP: add the
```
x-cave-workflow
```
header to the request.

Label the callers, keep the diff minimal, match the repo's style. If a callsite is not routed through the Caveman gateway at all, don't label it — list it under "not wired" in the report (labels only travel on gateway traffic; wiring is the caveman-setup skill's job).

提交以下表格并请求继续：

| 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均支持按请求覆盖头部），或为每个任务单独创建轻量客户端。
封装的编码Agent（
```
caveman wrap
```
）：在调用站点（cron行、CI步骤）添加
```
--workflow <slug>
```
标志或设置
```
CAVE_WORKFLOW=<slug>
```
环境变量。
原生HTTP：在请求中添加
```
x-cave-workflow
```
头部。

在调用方添加标签，尽量减少代码差异，匹配仓库的编码风格。若调用站点未通过Caveman网关路由，则无需为其添加标签——在报告中将其列在“未配置路由”下（标签仅随网关流量传递；路由配置由caveman-setup技能负责）。

Step 4 — Verify

步骤4 — 验证

Run whatever the repo already uses to exercise one labeled path (a test, a dev script, one curl). Then confirm: the request still succeeds (the gateway rejects an invalid label with 400

cave_invalid_request_header

— fix the slug if so). Labeled spend appears on the dashboard at

/activity?tab=workflows

as each workflow next runs; jobs on a schedule show up when the schedule fires, and that's worth saying in the report rather than pretending they're live.

使用仓库中已有的方式测试一条已标记的路径（如测试用例、开发脚本、curl命令）。然后确认：请求仍能成功执行（网关会以400

cave_invalid_request_header

拒绝无效标签——若出现此情况需修正slug）。当每个工作流下次运行时，标记后的支出数据会显示在仪表板的

/activity?tab=workflows

页面；定时任务的数据会在任务触发时显示，这一点需在报告中说明，而非假装数据已实时显示。

Step 5 — Report

步骤5 — 生成报告

undefined

undefined

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">


If you found no LLM entry points at all: say exactly that, and point at the
setup skill (`<docs origin>/docs/agent-setup.md`) instead of manufacturing a
table.

workflow	job	where
support-reply	answers inbound tickets	src/bot/reply.ts:41
nightly-digest	02:00 summary job	jobs/digest.ts:12

验证情况：<你实际测试的标记路径及观测结果> 数据展示位置：<DASHBOARD>/activity?tab=workflows — 每个工作流下次运行时会显示对应行。未标记的流量会显示为

unlabeled-workflow

。未配置路由（无网关路由，故未添加标签）：<列表或“无”> 标记为需审核：<从文件名推断用途的slug，或“无”>


若未找到任何LLM入口点：需明确说明此情况，并引导用户查看设置技能文档（`<docs origin>/docs/agent-setup.md`），而非编造表格。