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 的压缩、工具延迟加载与运行时策略能力接入自己的应用。双语言 SDKTypeScript 与 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/checkpointsTypeScript 侧在index.ts中实现了同名端点。契约变更只有当实现、schema 与测试三方一致时才算完成这一点由packages/sdk/parity下的对齐夹具fixtures.json、runtime-policy.fixtures.json和两侧的 parity 测试来守护。安装、构建与测试TypeScript 包caveman-ai/sdk为零运行时依赖要求 Node.js 22.13见 READMEpnpm --dir packages/sdk/typescript build pnpm --dir packages/sdk/typescript testPython 包发行名为caveman-sdk、导入名为caveman_cloud刻意区分因为caveman这个名字在 PyPI 上已属无关项目见 pyproject.toml仅用标准库实现要求 Python 3.13python -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 inferredPython 侧 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调用方取消、retentionmetadata | zdr | configured以及user作为x-cave-user-hash原样转发的不透明终端用户标识文档明确提示“若原始值是 PII请自行先做哈希”见 index.ts。压缩是 fail-closed 的CompressResult.basis恒为inferredSDK 永不输出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 SDKpackages/agentpackages/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 目录。有两点使用约束需要注意沙箱选择控制的是运行时权限策略不是操作系统隔离。当需要执行不可信代码时它不能替代 OS 级隔离——这一点在该包的 SANDBOX_THREAT_MODEL.md 中有专门的威胁模型说明。运行模式分两档。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-agentpackages/create-caveman-agent 为 Agent SDK 创建严格模式strict的起步项目npm create caveman-ai/agentlatest my-agent cd my-agent npm run doctor npm run dev初始化器的关键行为见 README支持anthropic、openai、google三个 Provider恰好检测到一个 Provider 凭据时静默选定零个或多个凭据则提示一次密钥永不打印、永不落盘--no-install可跳过依赖安装适合由其他工具接管安装的场景非交互用法npm create caveman-ai/agentlatest 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/网关只是 WARNobserve-only 依然可用只有 Node 版本不符、沙箱包含探针失败、配置非法或锁漂移才判 FAIL见 README doctor 输出示例。共享契约packages/shared/contractspackages/shared/contracts 存放 JSON Schema 形式的线协议wire契约。文档列出的当前 schema 集与schemas/目录下的实际文件完全对应文档描述对应 schema 文件适配器一致性 / Agent 运行回执adapter-conformance.schema.json、agent-run-receipt.schema.json缓存守卫 / 规范化 spancache-guard.schema.json、canonical-span.schema.jsonCave Build / Cave Plancave-build.schema.json、cave-plan.schema.json上下文中间表示context-ir.schema.json持续改进报告continuous-improvement-report.schema.json评测用例 / grader 注册表eval-case.schema.json、grader-registry.schema.json测试床事件 / 策略harness-event.schema.json、policy.schema.jsonpracticespractice.schema.json变换能力 / 追踪transform-capability.schema.json、transform-trace.schema.json见 schemas 目录。配套纪律是生成与校验一律走包内脚本而不是手工编辑生成物——package.json的 scripts 与scripts/目录承担这一职责fixtures/提供契约级测试样本。Provider 目录shared/provider-catalogshared/provider-catalog 存放带日期的公开 list-price 记录与生成的目录产物用于本地成本估算。catalog/目录中保留了一份按日期命名的历史快照如 2026-06-02.yaml 至 2026-08-10.yaml以及一个 current.yaml。两条硬规则不支持的模型返回零价并附unpriced标记目录不代表发票数据invoice data目录更新必须齐备四样东西来源日期source date、Provider 单位语义unit semantics、生成产物刷新、测试——校验入口是 validate_catalog.pyGo 侧有 catalog_test.go 兜底。这套“定价证据链”的完整规则见 docs/technical/accounting-and-evidence.md。基准工具packages/subagent-taxpackages/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/sdkNode 22.13或caveman-sdk/caveman_cloudPython 3.13构建生产级 Agent工具、预算、评测、沙箱、适配器→caveman-ai/agent起步用npm create caveman-ai/agentlatest定义/校验线协议字段→packages/shared/contracts只经包脚本生成不手改产物本地成本估算→shared/provider-catalog的带日期 list-price 记录未定价模型显式置零度量 harness 前缀开销→packages/subagent-tax纯本地、零 Provider 调用。所有公开数字遵循同一证据边界SDK 与本地工具的输出要么是观测值要么诚实标记为inferredverified级别的节省只由 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考