【Claude Code-System Prompt实测】请求前缀可观测性：token profile、prefix diff 与 cache miss 归因

非线智能API经验 [Claude Code-System Prompt实测] 第14篇

摘要

请求前缀可观测性的目标不是把完整 prompt 打进日志，而是回答四个工程问题：前缀到底多大，哪一段在变化，为什么缓存没有命中，观测过程中有没有泄露敏感内容。对 Claude Code 跨模型 gateway 来说，这一层和协议转换同样重要；没有可观测性，cache miss、role 400、工具描述膨胀和 MCP 抖动都会变成黑盒问题。

本文聚焦请求前缀可观测性。system prompt token 只是其中一类 segment；还需要统计 Claude Code 内置 prompt token 数、CLAUDE.md / project context token 数、工具定义 token 数、MCP 描述 token 数、cacheable prefix token 数、uncacheable dynamic token 数，以及每轮前缀变化 diff。

数据来源：非线智能Nonlinear 官网

Prefix Profile

每轮请求应生成一份结构化 profile：

{
  "request_id": "req_...",
  "provider": "vllm",
  "model": "qwen3-coder",
  "tokenizer": {
    "provider": "vllm",
    "model_id": "qwen3-coder",
    "count_method": "provider_usage_or_local_estimate"
  },
  "tokens": {
    "total_input": 48231,
    "leaf_segments_sum": 48231,
    "system_total": 12980,
    "claude_code_builtin": 7210,
    "project_context_total": 2840,
    "claude_md": 1630,
    "tools": 15440,
    "mcp": 6150,
    "task_state": 2760,
    "live_window": 11051,
    "dynamic_uncacheable": 20
  },
  "cache": {
    "cacheable_prefix_tokens": 30270,
    "uncacheable_dynamic_tokens": 20,
    "stable_prefix_hmac": "hmac-sha256:...",
    "changed_segments": ["live_window"],
    "expected_hit": true,
    "actual_hit": false,
    "miss_reason": "dynamic_attribution_block"
  },
  "adapter": {
    "role_rewrite_count": 1,
    "stripped_attribution_blocks": 1,
    "reserved_keyword_blocks": 0
  }
}

注意这里使用 HMAC，而不是裸 SHA。生产环境中，固定 prompt、公开工具描述和常见 system prompt 可能被字典攻击反推；带环境 salt 的 HMAC 仍能在同一环境内比较变化，同时降低泄露风险。

token 分桶必须先定义口径。推荐用 leaf segment 作为成本归因基础，total_input 等于 leaf segment 之和；system_total 可以包含 claude_code_builtin 等子维度，但不能再与子维度重复相加；claude_md 通常是 project_context_total 的子集；live_window 包含最新用户消息、工具结果和错误反馈。跨 provider 比较时必须记录 tokenizer.provider、model_id 和 count_method，因为 Anthropic token counting、OpenAI-compatible tokenizer、vLLM / local tokenizer 的计数并不一定一致。

指标分组

实现上应优先记录 segment_tokens[]，再派生这些聚合指标。这样可以避免 system、project_context、CLAUDE.md 等父子维度重复计费。

Prefix diff 不应泄露原文

默认 diff 应只展示 segment 级变化：

{
  "segment": "tools",
  "before_hmac": "hmac:aaa",
  "after_hmac": "hmac:bbb",
  "token_delta": 840,
  "change_type": "tool_added",
  "metadata": {
    "tool_name_hmac": "hmac:...",
    "schema_hmac": "hmac:..."
  }
}

不要默认记录：

• 完整 system prompt。
• 完整 CLAUDE.md。
• 用户 prompt 原文。
• 工具参数原文。
• API key、cookie、authorization header。
• 绝对路径和临时目录。

工具名、路径、MCP server 名也可能泄露内部能力。生产默认应是 hash_only / HMAC-only；名称类 metadata 只有在 allowlist 或本地 debug 模式下输出。本地 debug 可以短期启用脱敏片段，但必须有 TTL、访问控制、secret scan，并禁止写入长期分析仓库。

cache miss 归因

cache miss 不应只记录 hit=false。兼容层应归因到 segment：

这样才能把“缓存没命中”变成可修复的问题。

归因算法建议遵循三条规则。第一，多个 segment 同时变化时，优先归因第一个 cache boundary 之前的变化，因为它会破坏后续所有 prefix reuse。第二，expectedHit=true 但 provider 没有返回 cache metrics 时，不能记作 miss，应记录 actualHit=unknown。第三，区分 gateway cache miss、provider cache miss、cache write 和 cache read；readTokens / writeTokens 必须绑定 provider 字段来源，不能用本地估算冒充 provider 账单字段。与 attribution cache miss 相关的原因见第 10 篇 Claude Code attribution block 与第三方缓存 miss，工具 / MCP 膨胀见第 12 篇 CLAUDE.md、工具定义与 MCP 描述的上下文膨胀，前缀稳定化见第 13 篇 归属指纹块剥离与前缀稳定化。

telemetry schema

type PromptTelemetryEvent = {
  requestId: string;
  provider: string;
  model: string;
  tokenizer: {
    provider: string;
    modelId: string;
    countMethod: "provider_usage" | "provider_count_tokens" | "local_tokenizer" | "diff_estimate";
  };
  segments: Array<{
    id: string;
    type: "system" | "tools" | "mcp" | "project_context" | "task_state" | "live_window" | "metadata";
    tokens: number;
    hmac: string;
    cacheable: boolean;
    stability: "static" | "semi_static" | "dynamic";
    redaction: "hash_only" | "metadata_only" | "redacted_sample";
  }>;
  diff: {
    changedSegments: string[];
    churnTokens: number;
    churnRatio: number;
  };
  cache: {
    expectedHit: boolean;
    actualHit?: boolean | "unknown";
    cacheLayer?: "gateway" | "provider" | "local_kv";
    missReason?: string;
    readTokens?: number;
    writeTokens?: number;
    tokenSource?: string;
  };
  adapter: {
    roleRewriteCount: number;
    strippedAttributionBlocks: number;
    reservedKeywordBlocks: number;
  };
};

稳定性评分

score = 100
  - 40 * cacheable_churn_ratio
  - 20 * dynamic_prefix_ratio
  - 15 * ordering_instability
  - 15 * role_rewrite_risk
  - 10 * cache_boundary_risk

评分解释：

失败模式

验证清单

• 构造 attribution fingerprint 变化，miss reason 应为 dynamic_attribution_block。
• 构造工具顺序变化，canonicalization 后不应产生 diff。
• 构造工具 schema 变化，diff 应定位到具体 tool schema。
• 构造 CLAUDE.md 变化，diff 应定位到 project context，而不是 system builtin。
• 对 telemetry 日志运行 secret scan，确认没有完整 prompt、API key、cookie、authorization header。
• 对生产配置确认 prompt 原文不落盘，只保留 HMAC、token 和结构化 metadata。
• 比较 expected cache hit 与 provider actual cache hit，找出 gateway 与 provider 语义差异。

参考链接

• Anthropic Token Counting
• Anthropic Prompt Caching
• Claude Code Environment Variables
• Claude Code LLM Gateway
• Anthropic Engineering: Effective context engineering for AI agents
• CacheProbe
• Contextual Memory Virtualisation

本文由非线智能API Claude Code 行业专家整理编写