企业官网建设流程全解析

Caveman SDK 与公开包全景：TypeScript/Python SDK、Agent SDK、共享契约与 Provider 目录

【免费下载链接】caveman🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman

在 Caveman 仓库中，packages/与shared/目录下沉淀了一组面向应用集成的独立公开包：TypeScript 与 Python 双语言 SDK、用于构建和运行工具型 Agent 的 Agent SDK、JSON Schema 线协议契约、带日期的 Provider 目录，以及本地基准工具。读完本文，你可以掌握双语言 SDK 的八大核心能力与/sdk/v1/*线协议的对应关系、Agent 初始化的完整命令流程、共享契约的生成与校验纪律，以及 Provider 目录“未定价即零价”的计费原则，从而把 Caveman 的压缩、工具延迟加载与运行时策略能力接入自己的应用。

双语言 SDK：TypeScript 与 Python

仓库在 packages/sdk/typescript 和 packages/sdk/python 中维护两套能力对齐的高层客户端。二者实现的操作面一致，覆盖以下场景：

• 创建 Caveman 客户端；
• 配置 Provider 调用；
• 定义、延迟加载（defer）和检索工具；
• 压缩符合条件的上下文；
• 从上下文部件组装请求；
• 创建并消费上下文包（context pack）；
• 输出追踪（traces）与 OpenTelemetry 数据；
• 应用运行时策略（runtime policy）。

两个 SDK 的字段命名与/sdk/v1/*请求契约必须保持一致。从源码看，Python 客户端实际打到网关的端点包括/sdk/v1/runtime-policy、/sdk/v1/shared-context、/sdk/v1/events、/sdk/v1/artifacts和/sdk/v1/checkpoints；TypeScript 侧在index.ts中实现了同名端点。契约变更只有当实现、schema 与测试三方一致时才算完成，这一点由packages/sdk/parity下的对齐夹具（fixtures.json、runtime-policy.fixtures.json）和两侧的 parity 测试来守护。

安装、构建与测试

TypeScript 包@caveman-ai/sdk为零运行时依赖，要求 Node.js 22.13+（见 README）：

pnpm --dir packages/sdk/typescript build pnpm --dir packages/sdk/typescript test

Python 包发行名为caveman-sdk、导入名为caveman_cloud（刻意区分，因为caveman这个名字在 PyPI 上已属无关项目，见 pyproject.toml），仅用标准库实现，要求 Python 3.13+：

python -m pytest -q packages/sdk/python

核心 API 面

以 TypeScript 为例，README 示例 展示了最简用法：

import { Cave } from "@caveman-ai/sdk"; const cave = new Cave({ apiKey: process.env.CAVE_API_KEY!, baseURL: "http://127.0.0.1:8787", agent: "support-agent", }); const result = await cave.compress("large payload"); console.log(result.output, result.basis); // basis is inferred

Python 侧 API 完全镜像（见 caveman_cloud/core.py 与 README）。两套 SDK 共同暴露的主要能力面包括：Provider 客户端、compress、延迟工具检索（deferred tool search）、可逆检查点与工件（checkpoints and artifacts）、重试环路中断（retry-loop interruption）、运行时策略，以及一个零依赖的 OTLP/JSON exporter。

几个从源码中可以确认的行为细节值得注意：

• CaveOptions参数：除apiKey/baseURL/agent外，还支持timeoutMs（所有 SDK HTTP 请求的有限截止时间，默认 30 秒）、signal（调用方取消）、retention（"metadata" | "zdr" | "configured"）以及user（作为x-cave-user-hash原样转发的不透明终端用户标识，文档明确提示“若原始值是 PII，请自行先做哈希”，见 index.ts）。
• 压缩是 fail-closed 的：CompressResult.basis恒为"inferred"，SDK 永不输出verified；任何传输或解析问题都会退化为直通（output即原始输入、ratio为0、无recoveryHandle），详见 CompressResult 定义。
• 重试环路熔断器：RetryLoopBreaker以“工具名 + 排序键 JSON 参数”作为签名，同一调用连续重复超过threshold（默认 3）次时抛出RetryLoopError，防止 Agent 卡在相同工具调用上烧 token；两侧实现字段与阈值语义一致，Python 侧还特意处理了与 Go/JS 舍入行为对齐的细节（core.py）。
• 异步作业是保留位：异步作业接口已预留形状，但当前会在本地直接以cave_async_jobs_unavailable失败，不发送任何请求。
• 连接类调用需要一个 Caveman 网关 key；本地 Engine 压缩则不依赖账户，走独立的 Caveman 运行时分发。

定价纪律：未知模型保持零价

两个 SDK 都遵守同一条规则：不得为未知模型猜测成本。未知定价保持为零，并被显式标记为“未定价”（unpriced），而不是外推或套用邻近模型的价格。这条纪律在 Python 源码的严格整数校验（_strict_non_negative_int）与工具检索结果的非负截断（saved_tokens对负值归零）中都有体现，保证了 SDK 输出的每一个数字要么是观测值、要么是诚实的inferred估算。

Agent SDK：packages/agent

packages/agent 是一个 TypeScript 运行时，用于构建和运行使用工具的 Agent。它导出 Agent 定义、run 与 stream 接口、子代理（subagent）支持、工具、记忆与上下文组装及输出处理、评测钩子和沙箱模式。构建与测试：

pnpm --dir packages/agent build pnpm --dir packages/agent test

从源码结构看，src/下的模块划分与文档描述一一对应：execution-kernel.ts/runtime.ts负责执行，breakers.ts承载环路熔断，budget.ts承载预算，context-ir.ts对应共享契约中的上下文中间表示，sandbox-*.ts对应沙箱能力，adapters.ts提供框架适配层（见 src 目录）。

有两点使用约束需要注意：

1. 沙箱选择控制的是运行时权限策略，不是操作系统隔离。当需要执行不可信代码时，它不能替代 OS 级隔离——这一点在该包的 SANDBOX_THREAT_MODEL.md 中有专门的威胁模型说明。
2. 运行模式分两档。Agent README 说明：安装并启动本地 Engine 后运行走mode: "optimized"（经本地网关、启用符合条件的变换与上下文遥测）；没有 Engine 时则自动进入observe-only模式——直连 Provider 的 base URL、无变换、无网关遥测，但仍保留 Provider 用量和本地上下文估算，且不宣称任何效率收益。网关代理anthropic、openai、google三家，其他 Provider 直连并报告 observe-only。携带 Cave Build 锁或候选计划的运行若被要求静默降级，会以cave_gateway_required_for_locked_plan拒绝。

Agent 初始化器：packages/create-caveman-agent

packages/create-caveman-agent 为 Agent SDK 创建严格模式（strict）的起步项目：

npm create @caveman-ai/agent@latest my-agent cd my-agent npm run doctor npm run dev

初始化器的关键行为（见 README）：

• 支持anthropic、openai、google三个 Provider；
• 恰好检测到一个 Provider 凭据时静默选定，零个或多个凭据则提示一次；
• 密钥永不打印、永不落盘；
• --no-install可跳过依赖安装（适合由其他工具接管安装的场景）；
• 非交互用法：npm create @caveman-ai/agent@latest my-agent -- --provider anthropic；
• 生成的评测（eval）初始为未批准状态，需要人工审阅期望行为、把approved置为true后才能执行锁定构建（locked build）；本地证据保持inferred，验证过的节省（verified savings）在活跃生产流量通过相应门槛前保持为$0。

npm run doctor（等价于npx caveman-agent doctor，加--json可出机器可读报告）做一次零 Provider 调用的就绪检查：Node 版本、沙箱包含探针、Engine、运行时 CLI、网关可达性等项目依次给出 PASS/WARN/FAIL；缺少 Engine/CLI/网关只是 WARN（observe-only 依然可用），只有 Node 版本不符、沙箱包含探针失败、配置非法或锁漂移才判 FAIL（见 README doctor 输出示例）。

共享契约：packages/shared/contracts

packages/shared/contracts 存放 JSON Schema 形式的线协议（wire）契约。文档列出的当前 schema 集与schemas/目录下的实际文件完全对应：

（见 schemas 目录）。配套纪律是：生成与校验一律走包内脚本，而不是手工编辑生成物——package.json的 scripts 与scripts/目录承担这一职责，fixtures/提供契约级测试样本。

Provider 目录：shared/provider-catalog

shared/provider-catalog 存放带日期的公开 list-price 记录与生成的目录产物，用于本地成本估算。catalog/目录中保留了一份按日期命名的历史快照（如 2026-06-02.yaml 至 2026-08-10.yaml）以及一个 current.yaml。两条硬规则：

1. 不支持的模型返回零价并附unpriced标记，目录不代表发票数据（invoice data）；
2. 目录更新必须齐备四样东西：来源日期（source date）、Provider 单位语义（unit semantics）、生成产物刷新、测试——校验入口是 validate_catalog.py，Go 侧有 catalog_test.go 兜底。

这套“定价证据链”的完整规则见 docs/technical/accounting-and-evidence.md。

基准工具：packages/subagent-tax

packages/subagent-tax 在不向 Provider 发任何请求的前提下，测量本地上下文与委派（delegation）夹具。其工作原理（见 README）：本地 sink 冒充 Provider 端点，每个已安装的 coding harness 向它发送一条真实请求，工具据此报告该 harness 每次调用实际重发的完整前缀（系统提示 + 全部工具 schema）有多大。产物是“针对精确夹具与计数实现”的基准证据，而不是通用的节省声明——这正是文档中“not a general savings claim”一语的落地。测试夹具包括 anthropic-first-request.json 与 example-report.json，核心逻辑在lib/下按tokens/harnesses/report等模块拆分。

包的发布模型

Registry 包与原生二进制走两条独立发布线：

• Registry 包：通过带作用域（scoped）的 workflow inputs 独立发布，流程细节见 docs/PACKAGE_RELEASES.md；
• 原生二进制：走单独的签名流程，安装与更新方式见 docs/technical/install-and-update.md。

理解这条分工有助于回答一个常见问题：为什么@caveman-ai/sdk这类 npm 包可以独立升级，而cavemanCLI 的二进制更新却涉及校验与签名——两者属于不同的发布轨道，互不阻塞。

小结：各包在集成中的位置

• 接入网关能力（压缩、工具检索、检查点、运行时策略、OTLP 导出）→@caveman-ai/sdk（Node 22.13+）或caveman-sdk/caveman_cloud（Python 3.13+）；
• 构建生产级 Agent（工具、预算、评测、沙箱、适配器）→@caveman-ai/agent，起步用npm create @caveman-ai/agent@latest；
• 定义/校验线协议字段→packages/shared/contracts，只经包脚本生成，不手改产物；
• 本地成本估算→shared/provider-catalog的带日期 list-price 记录，未定价模型显式置零；
• 度量 harness 前缀开销→packages/subagent-tax，纯本地、零 Provider 调用。

所有公开数字遵循同一证据边界：SDK 与本地工具的输出要么是观测值，要么诚实标记为inferred；verified级别的节省只由 Cloud active 路径与独立的 rollout/ledger 门槛产生，仓库内本地结果一律保持inferred。

【免费下载链接】caveman🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman