claw-code 源码分析：成本追踪（Cost）与 Hook——企业落地时，计量与策略注入该挂在哪一层？

涉及源码rust/crates/runtimeusage.rs、conversation.rs、hooks.rs、config.rs、permissions、rust/crates/api流式Usage、rust/crates/plugins插件HookRunner、rust/crates/claw-cli/cost、流事件Python 侧src/query_engine.py、src/cost_tracker.py、src/costHook.py。1. 先把概念拆开「计量」≠「美元估算」≠「预算截断」本仓库里与「成本」相关的代码至少有三层含义含义主要位置企业用途提供商返回的 token 用量事实数据api::Usage、流事件中的 usage计费分摊、配额、审计日志的原始计量会话内累计与展示runtime::UsageTracker、TokenUsage会话级看板、/cost、JSON 输出美元估算runtime::usage里pricing_for_modelestimate_cost_usd*仅供参考的 rough cost不宜单独作为法务计费依据策略注入则再分两类类型机制典型用途同步、进程内授权PermissionPolicy::authorize允许/拒绝某工具调用可带PermissionPrompter可外置脚本扩展HookRunnerPreToolUse / PostToolUseDLP、审计、在工具执行前后跑组织脚本退出码 2 拒绝下文按源码真实挂载点说明「该挂哪一层」。2. 计量Cost / Usage数据从哪来、在哪聚合2.1 源头API 流里的Usage上游响应类型里携带Usageinput/output/cache 等例如MessageDeltaEvent// 149:164:rust/crates/api/src/types.rs#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]pubstructUsage{pubinput_tokens:u32,#[serde(default)]pubcache_creation_input_tokens:u32,#[serde(default)]pubcache_read_input_tokens:u32,puboutput_tokens:u32,}implUsage{#[must_use]pubconstfntotal_tokens(self)-u32{self.input_tokensself.output_tokens}}企业建议若要做多租户计费或合规报表应在可靠边界上记录「提供商返回的 usage 快照」例如在API 客户端实现层把StreamEvent解析为AssistantEvent::Usage之处或紧接其后的 runtime带上request_id/session_id/tenant_id需自行扩展写入日志或导出管道。不要只在 CLI 打印里存在。2.2 聚合ConversationRuntimeUsageTracker运行时在一次stream后构建 assistant message并把本轮TokenUsage记入 tracker// 178:182:rust/crates/runtime/src/conversation.rsleteventsself.api_client.stream(request)?;let(assistant_message,usage)build_assistant_message(events)?;ifletSome(usage)usage{self.usage_tracker.record(usage);}UsageTracker维护「最近一轮」与「累计」并可从已有Session消息重建便于恢复会话后继续统计// 163:194:rust/crates/runtime/src/usage.rs#[derive(Debug, Clone, Default, PartialEq, Eq)]pubstructUsageTracker{latest_turn:TokenUsage,cumulative:TokenUsage,turns:u32,}implUsageTracker{#[must_use]pubfnfrom_session(session:Session)-Self{letmuttrackerSelf::new();formessageinsession.messages{ifletSome(usage)message.usage{tracker.record(usage);}}tracker}pubfnrecord(mutself,usage:TokenUsage){self.latest_turnusage;self.cumulative.input_tokensusage.input_tokens;...self.turns1;}}企业建议会话级计量的 canonical 挂点即ConversationRuntime内UsageTracker所有经该 runtime 的 turn 都会更新同一套累计。若在HTTP server或LSP等多入口后面复用同一 runtime 模型从这里暴露usage()给外层比在各入口重复解析流更一致。2.3 美元估算挂在usage模块即可不要当唯一真相TokenUsage::estimate_cost_usd*与pricing_for_model使用字符串匹配模型名haiku/sonnet/opus和默认单价用于摘要行与/cost类展示。企业建议财务级计费应使用合同价、折扣、批次价目表放在计费服务或网关仓库内 USD 估算适合开发者可见性与粗略告警与token 原始计量解耦。2.4 Python 移植工作区QueryEnginePort与cost_*占位QueryEngineConfig.max_budget_tokens在submit_message里用投影用量做简单截断语义是「port 模拟」而非真实提供商 usage# 87:94:src/query_engine.pyprojected_usageself.total_usage.add_turn(prompt,output)stop_reasoncompletedifprojected_usage.input_tokensprojected_usage.output_tokensself.config.max_budget_tokens:stop_reasonmax_budget_reached...self.total_usageprojected_usageCostTracker/apply_cost_hook仅为极简占位与 Rust 主路径无运行时耦合# 6:13:src/cost_tracker.pydataclassclassCostTracker:total_units:int0events:list[str]field(default_factorylist)defrecord(self,label:str,units:int)-None:self.total_unitsunits self.events.append(f{label}:{units})结论企业若以Rust runtime 真实 API落地不要把Python 的QueryEnginePort当作计量或预算的权威实现它更适合 parity / 文档与测试镜像。3. Hook策略注入该挂在哪一层3.1 执行顺序硬事实在PermissionOutcome::Allow分支中顺序为PermissionPolicy::authorize可带交互式 prompterhook_runner.run_pre_tool_use可拒绝tool_executor.executehook_runner.run_post_tool_use可标记错误/附加反馈// 201:246:rust/crates/runtime/src/conversation.rsfor(tool_use_id,tool_name,input)inpending_tool_uses{letpermission_outcomeifletSome(prompt)prompter.as_mut(){self.permission_policy.authorize(tool_name,input,Some(*prompt))}else{self.permission_policy.authorize(tool_name,input,None)};letresult_messagematchpermission_outcome{PermissionOutcome::Allow{letpre_hook_resultself.hook_runner.run_pre_tool_use(tool_name,input);ifpre_hook_result.is_denied(){...}else{let(mutoutput,mutis_error)matchself.tool_executor.execute(tool_name,input){Ok(output)(output,false),Err(error)(error.to_string(),true),};...letpost_hook_resultself.hook_runner.run_post_tool_use(tool_name,input,output,is_error);...因此需要保证「未授权绝不执行工具」→ 必须用PermissionPolicy或在其之上封装企业策略不能单靠 hook。需要在执行前后跑外部队列/脚本、扫描输入输出→ 用HookRunner配置见下。3.2 配置挂载RuntimeFeatureConfig→RuntimeHookConfigHook 命令列表挂在特性配置里与插件、MCP 等并列// 47:62:rust/crates/runtime/src/config.rs#[derive(Debug, Clone, PartialEq, Eq, Default)]pubstructRuntimeFeatureConfig{hooks:RuntimeHookConfig,plugins:RuntimePluginConfig,mcp:McpConfigCollection,...}#[derive(Debug, Clone, PartialEq, Eq, Default)]pubstructRuntimeHookConfig{pre_tool_use:VecString,post_tool_use:VecString,}ConversationRuntime::new_with_features用其构造HookRunner// 126:144:rust/crates/runtime/src/conversation.rspubfnnew_with_features(...feature_config:RuntimeFeatureConfig,)-Self{letusage_trackerUsageTracker::from_session(session);Self{...hook_runner:HookRunner::from_feature_config(feature_config),}}企业建议组织级 hook 清单只读挂载、镜像内固定路径适合从合并后的RuntimeFeatureConfig注入例如全局配置 项目配置merged避免每个入口CLI / server各写一份。3.3 拒绝语义退出码 2Runtime 侧子进程 hook0放行2明确拒绝其它非零为 warn默认仍允许继续与插件 crate 行为一致思想// 185:195:rust/crates/runtime/src/hooks.rsmatchoutput.status.code(){Some(0)HookCommandOutcome::Allow{message},Some(2)HookCommandOutcome::Deny{message},Some(code)HookCommandOutcome::Warn{message:format_hook_warning(command,code,message.as_deref(),stderr.as_str(),),},企业建议把「必须拦下」的规则放在exit 2的 pre-hook或PermissionPolicy仅告警用非 0 非 2。3.4 第二套 Hookpluginscrate 的HookRunner插件清单聚合出的PluginHooks也有独立的HookRunnerplugins/src/hooks.rs与runtime 配置型HookRunner是两条线。若企业同时启用插件生态与全局 shell hook需要明确合并顺序与优先级当前架构下应由集成方在组装RuntimeFeatureConfig/ 插件 registry 时统一设计。4. 直接回答企业落地「该挂哪一层」4.1 计量Metering需求推荐挂点原因记录每轮 LLM 的 provider usageAPI 客户端 →AssistantEvent::Usage→UsageTracker::record与对话状态一致避免多入口重复解析会话/用户/租户累计runtime 外露usage()外层server/gateway写审计tracker 不自带 tenant需边界补全上下文美元展示与粗告警usage.rs估算实现已有与合同计费分离硬预算截断建议在 runtime 或 API 前增加策略本仓库无统一max_budget与 Rust runtime 对齐Python port 仅有模拟生产需单独设计4.2 策略注入Policy需求推荐挂点原因工具白名单/黑名单、模式如只读PermissionPolicyPermissionPrompter在 hook 之前执行语义是「授权」组织脚本、DLP、审计流水RuntimeHookConfigHookRunner已有 Pre/Post、stdin JSON 环境变量、exit 2 拒绝与插件包绑定plugins::HookRunner 插件 registry适合分发可版本化的扩展4.3 不建议的挂点仅在 CLI 打印或某一条 HTTP 路由里各自算 usage易与ConversationRuntime累计不一致。仅用 USD 估算做扣费。仅用 PostToolUse 做「绝不能执行」的决策执行已发生强约束应放在Permission或PreToolUse。5. 小结计量以api::Usage为事实来源在ConversationRuntime的UsageTracker做会话聚合企业租户与审计在server/gateway 边界补全上下文并落库。usage.rs的美元数适合展示与粗算不宜单独作为计费真相。策略授权挂在permissions可扩展、可外置脚本挂在RuntimeHookConfig驱动的HookRunner并注意与plugins钩子体系的边界。PythoncostHook/QueryEnginePortparity 与模拟为主不是Rust 企业主路径的计量与策略核心。