拆解 Claude Code 从 npm source map 泄漏中暴露出的智能体主循环、上下文压缩、工具系统、安全模型与未来平台化方向。
1 泄漏始末
1.1 事件本质
Source Map 暴露
npm 发布包中保留了 .map source map 文件。source map 本来用于把压缩或打包后的产物映射回原始 TypeScript/React 源文件，方便调试；但在生产 npm 包中保留它，就等于把内部目录结构、提示词组织、智能体循环、工具调用、权限流程和桥接系统暴露给外界。
泄漏规模
官方仓库看起来像插件壳，主要包含插件系统、Hook 示例、配置模板和示例插件；source map 暴露的内容则是完整厨房：4600+ 源文件、55+ 目录、TypeScript/React 实现、商业许可下的专有核心引擎。
工程判断
这类事故本质是构建链安全问题。核心风险不是运行时代码分支能否被绕过，而是调试制品是否被纳入发布产物。即使二进制已经正确裁剪，source map 也可能泄漏被裁剪前的源代码结构。
1.2 开源差距
官方开放内容更接近插件接口层：插件系统、Hook 示例、配置模板、示例插件。真正决定产品能力的主循环、工具实现、权限判断、API 通信、上下文压缩、MCP 客户端与远程桥接，并不包含在官方仓库中。
2 总体架构
2.1 技术栈
Claude Code 技术栈说明它更像一个完整 TUI 应用。React 18 与 Ink 负责终端 UI 渲染，支撑权限对话框、进度条、多面板布局、Worker Badge 和实时流式输出。
2.2 架构分层
核心引擎
架构中心是 Core Engine：query.ts 智能体循环、权限系统、配置解析、上下文压缩和工具调度都在这里。CLI 层负责终端输入输出和交互控件；Claude API 层负责流式模型响应、工具调用协议和 fallback。
外围系统
工具系统提供 Bash、Read、Write、Edit、Glob、Grep、WebSearch、Agent 等能力；MCP 负责外部工具接入；安全层提供 8 层防护；配置系统合并用户、项目、本地、组织和服务端等规则；Bridge 则指向远程控制能力。
设计重点
这套架构真正解决的是：如何把 LLM API 调用变成可控、可恢复、可审计、可压缩、可并发、可远程扩展的软件工程循环。
3 智能体循环
3.1 生成器流
异步生成器
query.ts 的核心是一个异步生成器式主循环。普通函数只能返回一次结果；异步生成器可以一边等待 API、文件读取或工具执行，一边逐个产出事件。消费侧用 for await 接收流式事件，结束时得到终止原因，异常则自然走 try-catch。
统一三类通道
传统 EventEmitter 或回调模型会把事件、完成、错误拆成不同通道，复杂状态机里很容易漏处理。异步生成器把流式事件、正常结束、异常传播放进同一个函数语义里，非常适合 agentic loop。
3.2 状态迁移
参数不变
QueryParams 表示一轮请求的稳定输入：初始消息、系统提示、工具权限回调、工具上下文、任务预算、最大轮次、fallback 模型和请求来源等。它们不应在循环中被随意改写。
状态可变
State 表示每轮都会变化的运行态：消息列表、工具上下文、自动压缩跟踪、最大输出恢复次数、是否尝试过 reactive compact、待处理工具摘要、stop hook 状态、turnCount 和 transition。
Continue Site
循环中不是逐字段修改状态，而是一次性构造新 state：保留旧字段，替换 messages、turnCount、transition 等关键字段。这类似 React setState 思路，避免改到一半出错的半更新状态。transition 还记录为何进入下一轮，例如 next turn、错误恢复、fallback 模型切换。
3.3 六步管线
请求前压缩
调用模型前先处理上下文，顺序遵循便宜优先：Tool Result Budget、Snip Compact、Microcompact、Context Collapse、Auto Compact。Context Collapse 放在 Auto Compact 前，是为了先用低成本折叠保留细粒度上下文，只有仍超阈值才触发昂贵总结。
流式调用
模型流式生成时，StreamingToolExecutor 可以提前执行并发安全的工具。例如只读文件、Glob、Grep 可以并行；写文件或 Bash 这类会改变环境的工具必须独占。这样能降低用户感知延迟，但不会让互相冲突的工具同时运行。
错误恢复
Prompt Too Long 先尝试 Context Collapse drain，再做 reactive compact，最后才把错误暴露给用户。输出 token 超限则先提升输出上限，再注入继续上次输出的恢复消息，最多重试数次。核心原则是：免费的恢复路径先走，昂贵 API 调用后置。
停止钩子
Stop Hook 用于 Claude 想结束时先验证。例如用户设定测试通过才能停，则 hook 失败信息会被注入上下文，让模型继续修复。Token budget 不只是硬限制，还会检测收益递减：连续多次继续但新增 token 很少，就认为继续无意义并停止。
工具执行
第 2 阶段已开始的流式工具在第 5 阶段收集结果；未流式执行的工具再按批处理执行。UI 通过进度信号刷新 spinner，让用户看到工具正在运行。
下一轮准备
工具结束后，会消费前面预取的技能列表、记忆附件，处理排队命令，并刷新 MCP 工具列表。随后通过 Continue Site 把 assistant 消息和 tool result 追加进历史，回到 while true 顶部。
3.4 退出原因
九类终止原因
3.5 会话主管
QueryEngine
query.ts 管一轮用户输入到工具反馈的闭环；QueryEngine.ts 管整个会话。它维护完整消息历史、权限拒绝记录、累计 token 使用量、文件状态缓存、已发现技能和已加载记忆路径。
不对称持久化
用户消息必须阻塞写入，因为 resume 恢复依赖它；助手消息可以 fire-and-forget，因为即使写入失败也不应阻塞主循环。这是在可靠性和磁盘 I/O 延迟之间做取舍。
4 上下文压缩
4.1 四层压缩
Snip Compact
Snip 是最便宜也最激进的方式：直接剪掉较早消息块，只保留最近上下文。没有模型总结，没有语义理解，因此信息损失高，但不产生 API 成本。它更适合 headless 后台会话，因为用户不直接看完整对话。
Microcompact
Microcompact 针对单个工具结果做选择性清理。例如十轮前读过的大文件内容，模型已吸收其关键信息，可替换为旧工具结果已清理之类的占位。它的难点是不能破坏 prompt cache：如果清理发生在缓存前缀中间，会导致后续缓存全部失效，反而更贵。
Context Collapse
Context Collapse 采用预览/提交两阶段：先标记可折叠块，再在需要时提交折叠。原始消息不被改写，折叠摘要存到单独 store，发送模型时通过 projectView 叠加成读取视图。这很像数据库 view 或 Git 快照。
Auto Compact
Auto Compact 会让模型总结整段会话。它信息保留最好，但要多一次 API 调用，因此是最昂贵的常规手段。阈值逻辑会为系统提示、工具定义和下一轮输出预留约 13K token 缓冲。
4.2 最后手段
断路器
如果自动压缩连续失败，系统不再无限重试，而是把控制权交给后续错误恢复流程。
Full Compaction
Full Compaction 是 Auto Compact 前的预处理：
4.3 告警机制
状态机
Token 告警分为 Normal、Warning、Error、AutoCompact、BlockingLimit。随着剩余窗口从 20K、13K 到 3K 逐步逼近，UI 提示会升级。BlockingLimit 表示自动压缩也不够，只能提示用户手动 /compact。
缓存取舍
四层压缩不是线性越压越强，而是在成本、信息损失和缓存影响之间找平衡。
5 工具体系
5.1 工具接口
统一上下文
所有工具都通过 ToolUseContext 获取运行世界：工具列表、主循环模型、MCP 客户端、预算上限、AbortController、文件读取缓存、AppState 访问器、权限跟踪、内容替换状态、agent ID 等。工具不是孤立函数，而是在可取消、可审计、可计费、可权限控制的环境里运行。
权限上下文
ToolPermissionContext 使用深度不可变类型。普通 Readonly 只能保护对象顶层，深度不可变会连嵌套数组和对象一起锁住。权限规则是安全边界，不允许运行中被任意模块误改。
5.2 注册分层
常驻工具
基础工具约 20 个，包括 Bash、Read、Write、Edit、WebSearch、Agent 等，构成 Claude Code 的核心行动能力。
条件工具
某些工具按环境启用。例如 Windows 下启用 PowerShell；LSP 需要环境变量；内部构建可能使用内置高性能搜索能力，从而替代 JS 实现的 Glob/Grep。
特性门控
WebBrowser、Workflow、Sleep、PushNotification 等未发布工具被 feature() 门控。构建期裁剪、条件激活和服务端 feature flag 一起组成工具能力伸缩机制。
5.3 工具缓存
稳定排序
工具池装配时，内置工具和 MCP 工具分别排序后拼接，而不是全量一起排序。原因是系统提示里的工具定义会进入 prompt cache；若新增 MCP 工具插入内置工具中间，会破坏内置工具区域的稳定前缀，让缓存失效。
动态搜索
Dynamic Tool Search 通过一个搜索工具的工具减少提示词膨胀。模型先看到 ToolSearchTool，需要某类能力时再加载具体工具定义。对拥有几十个 MCP 工具的场景，这能显著降低每轮固定 token 成本。
6 安全防线
6.1 八层模型
构建门
feature() 在构建期求值。未启用分支会被 bundler 删除，外部构建中内部工具代码物理不存在。安全性来自代码根本不在产物里。这次事故的讽刺点是：二进制可被裁剪，但 source map 里仍暴露了源代码映射。
特性开关
GrowthBook 的 tengu_* 开关提供服务端 kill switch。安全事件发生时，不需要客户端升级即可关闭相关功能，例如语音、绕过权限、自动模式、远程桥接或设备认证策略。
配置规则
权限规则来自 8 类来源：用户全局设置、项目设置、本地设置、服务端 flag、组织策略、命令行参数、运行时命令和会话内规则。规则需要合并优先级，但危险模式检测和 kill switch 仍可越过普通 allow 规则。
6.2 分类检测
AI 看 AI
Auto mode 下，Claude 可以不逐次询问用户就执行工具，因此需要额外分类器判断工具使用是否安全。只读工具可走白名单直接放行，危险或不明确操作要由分类器返回 allow 或 deny。
拒绝回退
如果分类器过度保守，连续拒绝 3 次或累计拒绝 20 次后，系统会回退到提示模式，让用户直接决策。若分类器 API 自己失败，也不是自动执行，而是回到询问用户。
危险模式
硬编码危险 Bash 模式会阻止解释器、exec/eval/source、curl/wget/nc、openssl、ssh/scp、sudo/docker、chmod/chown/mount 等高风险入口。尤其是解释器通配符危险，因为 python -c 或 node -e 可以绕过 Bash 字符串级检查执行任意系统命令。
6.3 路径校验
文件系统边界
路径校验文件很大，说明文件访问是核心风险点。系统会做绝对路径归一化、符号链接逃逸防护、安全 glob 展开、CWD-only 与 full access 模式区分、Coordinator scratchpad 支持，以及 Windows/POSIX 双平台处理。
信任对话框
新项目首次运行时，如果 .claude/ 中含设置，Trust Dialog 会展示项目级 MCP、Hook、Bash 权限、API key helper、云命令和 OTEL header 等潜在风险配置，要求用户显式同意。它防止恶意仓库通过项目设置自动放行危险工具。
绕过开关
Bypass permissions 是便利但危险的模式。服务端 kill switch 可阻止进入 bypass，也可把已处于 bypass 的用户强制拉回原模式，并显示诊断信息。
7 未发布功能
7.1 语音浏览
语音模式
Voice mode 依赖 OAuth 鉴权和专用 voice_stream 端点，不适用于 API Key、Bedrock 或 Vertex 路径。它受 GrowthBook kill switch 控制，并使用可能陈旧的缓存开关值，说明不是每次调用都实时查服务端。
浏览器工具
WebFetch 只能取静态 HTML，无法理解依赖 JavaScript 渲染的 SPA。WebBrowserTool 指向真实浏览器自动化能力，可能类似面向终端的 Computer Use：能看到渲染结果并交互，而不是只 fetch 文本。
7.2 多智能体
Coordinator
Coordinator Mode 是元编排器，不直接写代码，而是创建 worker agent、分发任务、接收 task notification、给 worker 追加指令或终止任务。它只允许 AgentTool、TaskStop、SendMessage、SyntheticOutput，不能直接 Bash 或读文件。
最小权限
Coordinator 只管协调，不碰实际文件系统，能降低单点失控风险。worker 在独立上下文里工作，把结果交回 Coordinator，形态接近 AI 微服务编排。
共享草稿区
tengu_scratch 提供 worker 共享目录，允许跨 CWD 交换信息。它需要绕过普通文件权限，因此必须由 feature gate 控制。
7.3 主动代理
Kairos
Kairos 代表从被动问答转向主动行动。相关工具包括发送用户文件、推送通知、订阅 GitHub PR webhook、Sleep 定时等待、多频道集成和状态简报。
触发监控
Agent Triggers 支持 cron 创建、删除和列表；RemoteTrigger 与 Monitor 说明长期 agent 可以有自己的计划任务和消息队列。例如每天检查 CI，或 PR 有新 review 时主动通知用户。
7.4 远程桥接
UDS Inbox
UDS 可能指统一设备栈。Agent 可以发现同账号下的其他设备或 Claude Code 实例，并通过 bridge:// 或 other:// 路由消息。这为让笔记本上的 Claude Code 请求台式机跑测试铺设通信管道。
Workflow
WorkflowTool 指向预置自动化脚本体系。为了避免递归爆炸，子 agent 中禁止递归执行 workflow，防止 workflow 调 workflow 的无限链条。
Bridge
Bridge 是远程控制系统，支持从 Claude.ai Web 控制本地 Claude Code。连接流程包括 OAuth 登录、CCR API 做订阅与 feature gate 校验、本地获取 environment_id 和 secret、建立认证 WebSocket 隧道，再由浏览器经 Bridge API 触发本地工具执行。
隔离认证
Bridge 有标准与增强两档认证：标准使用 OAuth，增强还要求绑定物理设备的 Trusted Device Token。远程会话用 Git worktree 隔离，即使同一项目开多个远程会话，也各自拥有独立工作目录。
8 设计结论
8.1 成本优先
便宜优先
Claude Code 的核心原则是成本感知。压缩先走免费剪裁，再走选择性清理，再折叠，最后才让模型总结；错误恢复先用已有候选或提升 token cap，再重新调用模型；工具定义通过动态搜索延迟加载。每一次 API 调用都被当作成本中心。
缓存优先
Prompt cache 是降低成本和延迟的关键资源。Microcompact 的 pinning、工具池稳定排序、内置工具前缀保护，都说明工程实践中少发 token 和保持缓存命中经常冲突，系统会选择总体更便宜的路径。
8.2 平台演进
最复杂的系统仍可能被最简单的发布配置错误击穿。Claude Code 在用户侧设计了多层安全防线，却因 source map 发布失误暴露了内部结构。对任何 AI 工程团队，这都是构建链安全、产物审计和发布前检查的强警示。这种从源码分析中汲取的教训，也值得所有开发者在云栈社区深入探讨。
参考资料 https://bits-bytes-nn.github.io/insights/agentic-ai/2026/03/31/claude-code-architecture-analysis.html
发表于 昨天 21:06
|
查看: 4|
回复: 0
