AtomCodeReverseEngineer

Appearance

深度分析 #2: 流式协议、Hook 事件系统与 LSP/CodeGraph 体系 ​

日期: 2026-06-23 | 循环分析第 2 轮

概述 ​

本轮分析发现了多个之前未文档化的核心子系统细节，包括流式协议、Hook 事件生命周期、LSP 语言支持体系、CodeGraph 索引引擎、以及 Headless 模式与抓包调试功能。

1. 流式协议（SSE 事件流） ​

1.1 Streaming Event Types ​

AtomCode 使用与 Anthropic API 兼容的 SSE 流式格式，包含以下事件类型：

事件类型说明
message_start消息开始
message_delta消息增量更新
message_stop消息结束
content_block_start内容块开始
content_block_delta内容块增量
content_block_stop内容块结束
text_delta文本增量（核心内容）
thinking_delta思考过程增量
signature_delta签名增量（用于 extended thinking）

1.2 Streaming 参数 ​

  • stream_options - 流选项
  • include_usage - 包含 token 使用统计
  • protocolVersion: 2024-11-05 - MCP 协议版本
  • anthropic-version: 2023-06-01 - Anthropic API 版本

1.3 Wire Dump 调试 ​

  • 环境变量: ATOMCODE_WIRE_DUMP
  • 输出路径: .atomcode/wire-dump
  • 启用后抓取所有 API 通信的原始数据，用于调试

2. Hook 事件生命周期（完整覆盖） ​

之前文档覆盖了 Hook 系统的概览，但缺少事件触发时序。二进制中发现的完整事件序列：

2.1 Hook 事件类型 ​

事件阶段触发时机
session_start会话会话初始化
session_end会话会话结束
turn_complete回合每回合完成
model_response模型LLM 响应到达
tool_call_start工具LLM 请求调用工具
pre_tool工具执行前工具执行前拦截
post_tool工具执行后工具执行后处理

2.2 Hook 过滤机制 ​

  • PreHookResult::Block (带 1 元素) - 阻止工具执行
  • PreHookResult::Modify (带 1 元素) - 修改参数后放行
  • 钩子按 hook_name 注册，通过 trigger 条件匹配

2.3 CCHookGroup 结构 ​

  • CCHookGroup 包含 2 个字段
  • 钩子组可以批量启用/禁用
  • 关键配置路径: ~/.atomcode/hooks/

3. LSP 语言服务器集成（完整语言支持清单） ​

3.1 支持的语言和对应 LSP 服务器 ​

语言LSP 服务器项目标记文件
Rustrust-analyzerCargo.toml
TypeScript/JavaScripttypescript-language-server --stdiotsconfig.json, package.json
Pythonpylsppyproject.toml
Gogopls servego.mod
Javajdtlspom.xml, build.gradle
Kotlin(Kotlin LSP)build.gradle.kts
C#(C# LSP).csproj
Scala(Scala LSP)build.sbt
Swift(Swift LSP)Package.swift
Vue(Vue LSP)package.json
Svelte(Svelte LSP)package.json

3.2 LSP 客户端架构 ​

  • lsp/client.rs — LSP 客户端实现，处理 JSON-RPC 消息
  • lsp/jsonrpc.rs — JSON-RPC 2.0 协议层
  • lsp/manager.rs — LSP 服务器生命周期管理

3.3 LSP 协议消息 ​

消息方向说明
textDocument/didOpen客户端→服务器文件打开通知
textDocument/didChange客户端→服务器文件变更通知
textDocument/publishDiagnostics服务器→客户端诊断结果发布
initialize客户端→服务器握手初始化
initialized客户端→服务器初始化完成通知

3.4 LSP 配置 ​

toml
[lsp]
auto_detect = true
diagnostics_settle_delay_ms = 500  # 诊断稳定等待时间
  • LspServerConfig 结构体: 3 个字段（含 root_markers）
  • 超时: LSP 请求 30 秒超时

4. CodeGraph / 代码索引引擎 ​

4.1 索引文件 ​

  • 输出文件: graph.bin (位于项目根目录)
  • 触发条件: 需要项目标记文件（.git, Cargo.toml, package.json, pyproject.toml, go.mod, pom.xml, build.gradle）
  • 跳过条件: 父目录有多个项目且没有直接标记文件

4.2 CodeGraph 功能 ​

  • 构建函数调用关系图
  • 支持 BFS 搜索调用链（最多 10 跳）
  • 为 find_references, trace_callees, trace_callers, trace_chain 工具提供数据
  • 支持 ATOMCODE_GRAPH_TOOLS 环境变量（可能控制启用/禁用）

4.3 索引范围 ​

  • 函数/方法定义 (fn pub fn class function func struct type interface)
  • SymbolNode 结构: 8 个字段（符号名称、位置、类型、子符号等）

5. Headless 模式 ​

5.1 工作模式 ​

  • 交互模式 (TUI): 默认启动完整终端 UI
  • Headless 模式: 通过 -p 参数或 headless flag 启用

5.2 Headless 行为 ​

  • [headless] auto-approved — 自动批准所有工具调用（等价于 --dangerously-skip-permissions）
  • WSL 检测: 检查 WSL_DISTRO_NAME, /proc/version, microsoft 关键词
  • CI 检测: GITHUB_ACTIONS, GITLAB_CI, BUILDKITE 环境变量

5.3 Headless 输出 ​

  • stderr verbose: -v / --verbose 显示 tool calls、token 使用、回合摘要
  • stdout: 仅输出助手回复
  • headless 模式下的 open_file: 检测到无 GUI 时拒绝，给出清晰提示

6. 项目类型检测与构建命令 ​

6.1 自动检测的项目类型 ​

框架检测文件构建命令测试命令
Node.jspackage.json, pnpm-lock.yaml, yarn.locknpm install / yarn install / pnpm installnpm test / yarn test / pnpm test
React"react" 依赖(同 Node.js)(同 Node.js)
Vue"vue" 依赖(同 Node.js)(同 Node.js)
Next.js"next" 依赖(同 Node.js)(同 Node.js)
Pythonrequirements.txt, pyproject.tomlpip install -r requirements.txtpytest
Gogo.modgo build ./...go test ./...
Java/Mavenpom.xmlmvn compilemvn test
Java/Gradlebuild.gradle./gradlew build./gradlew test
RustCargo.tomlcargo buildcargo test

6.2 智能构建修复 ​

  • auto_fix.rs 自动捕获编译错误，尝试修复
  • 捕获命令: npm run build 2>&1 | head -30, cargo check 2>&1 | tail -20, mvn compile -q 2>&1 | tail -20, go build ./... 2>&1 | tail -20

7. 架构约束与安全层 ​

7.1 网络访问控制 ​

Only http:// and https:// URLs are allowed; requests to localhost, 
private networks, and cloud metadata endpoints are blocked.

阻止访问:

  • localhost / 127.0.0.0/8
  • private networks (100.64/10, 240.0.0.0/4)
  • cloud metadata endpoints
  • link-local / multicast

7.2 敏感路径保护 ​

阻止写入的系统路径包括 50+ 个，涵盖:

  • /System, /sbin, /private/etc, /var/root
  • ~/.gnupg, ~/.ssh/id_rsa, ~/.ssh/id_ed25519
  • ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.npmrc, ~/.pypirc
  • Windows: \Program Files, \Program Files (x86), \ProgramData

7.3 环境变量验证 ​

变量用途优先级
ATOMCODE_TELEMETRY遥测禁用配置覆盖
DO_NOT_TRACK遥测禁用标准
ATOMCODE_PLATFORM_SERVER平台服务器地址配置覆盖
ATOMCODE_CODINGPLAN_API_BASECodingPlan API配置覆盖
ATOMCODE_CODINGPLAN_LLM_BASE_URLCodingPlan LLM配置覆盖
ATOMCODE_WIRE_DUMP调试抓包调试

8. 新发现的 search_replace 工具细节 ​

之前未文档化的参数:

参数类型说明
searchstring要搜索的文本或正则
replacestring替换内容（支持 $1, $2 等捕获引用）
globstring文件通配符（如 *.vue, *.css）
dirstring搜索目录（默认工作目录）
regexboolean是否使用正则匹配（默认 false）

结论 ​

本轮分析填补了 10 个新的细分领域:

#领域之前状态本次发现
1流式 SSE 事件协议未覆盖10 种事件类型 + 参数
2Hook 事件生命周期部分覆盖7 种触发事件 + Block/Modify 结果
3LSP 语言栈路径已知14+ 语言 + 完整配置
4CodeGraph 索引引擎路径已知graph.bin + 项目标记 + BFS
5Headless 模式协议未覆盖自动批准 + CI 检测
6Wire Dump 抓包未覆盖ATOMCODE_WIRE_DUMP
7search_replace 工具参数未覆盖5 个完整参数
8项目类型自动检测未覆盖7 种 + 构建命令映射
9WebUI 主题系统未覆盖atomcode.theme + atomcode.lang localStorage
10LSP 超时和错误恢复未覆盖30s 超时 + JSON-RPC 层

仍有盲区需要下一轮分析: graph/indexer.rs 索引格式、open_file 平台特定实现、WebUI SPA 的组件树细节、auto_commit 的 staged 升级流程等。

基于 VitePress 构建 · AtomCode v4.25.3 逆向工程分析文档