本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

语义层

状态：生效范围：当前状态最近审阅：2026-05-03 负责人：ax-code 运行时

本文描述 AX Code 中今天存在的语义层。它是当前状态契约，不是路线图。

事实来源

本页记录已发行的语义行为，而不是未来的代码图谱抱负。行为变化时，请对照以下来源核验：

packages/ax-code/src/tool/lsp.ts 及相关 LSP 模块，用于实时语义操作。
packages/ax-code/src/code-intelligence/，用于已索引的图谱行为。
packages/ax-code-reason/，用于由图谱支持的调试/重构分析（影响、缺陷路径、竞态、生命周期、重复、硬编码值、安全发现，以及受门控的重构应用）。
在声称持久来源保证之前，先看回放、导出和审计测试。

如果某项能力是计划中的或实验性的，请把该状态写明确。

目的

AX Code 通过两个显式来源暴露语义答案：

lsp：实时语言服务器查询
graph：持久的代码智能查询

系统不会悄悄把一个路由到另一个。调用方根据新鲜度、延迟和确定性要求选择表面。

当前语义表面

表面	支撑来源	当前角色
`lsp` 工具	实时 LSP 客户端	最新的语义答案，显式的实时查询表面
`code_intelligence` 工具	已索引的 SQLite 代码图谱	针对已索引符号、引用和调用关系的确定性图谱查询

lsp 工具是实时语义接口。code_intelligence 工具是已索引语义接口。两者都不是对方的隐藏回退。

当前门控：

code_intelligence 默认启用，但可以用功能标志禁用
lsp 目前需要实验性 LSP 工具标志

信封契约

语义答案携带来源元数据，以便下游消费者推理信任和新鲜度。

公共字段：

source：lsp、graph 或 cache
completeness：full、partial 或 empty
timestamp：底层答案被解析的时间
degraded：可选信号，表示答案应谨慎对待

由 LSP 支撑的信封还可以包括：

serverIDs：哪些语言服务器作了贡献
cacheKey：对 LSP 响应缓存行的稳定引用

审计与回放

当前行为：

通过 lsp 工具的实时语义调用写入 audit_semantic_call 行
工具回放现在保留 tool.result.metadata，这意味着由图谱支撑的语义元数据在回放/导出期间不会丢失
确定性回放比较的是决策路径元数据，而不是每个返回符号列表的语义相等

这使由 LSP 支撑和由图谱支撑的语义答案具有可比的审计可见性，尽管它们仍来自不同的存储/运行时路径。

当前暴露的操作

`lsp`

实时 lsp 表面包括带信封的操作，用于：

定义
引用
悬停
文档符号
工作区符号
实现
调用层次
聚合诊断

当时效比可重复性更重要时，这是合适的表面。

`code_intelligence`

图谱表面包括：

符号查找
文件符号
引用
调用方
被调用方

当可重复性和更低延迟比编辑器状态的即时新鲜度更重要时，这是合适的表面。

第三个可选知识表面是位于 .ax-wiki/ 下的原生语义仓库 Wiki，由 ax-code wiki 编译。它不是上面结构图谱/LSP 信封契约的一部分。

表面	角色
`lsp` / `code_intelligence`	结构精度（本文档）
`.ax-wiki/`	面向智能体的、以源为据的架构叙述

CLI、路由和非目标见 AX Wiki。Wiki 综合不得被当作调用方/被调用方/引用的替代。

重要的非目标

当前语义层不做这些事：

没有隐藏的图谱优先路由加自动 LSP 回退
不声称图谱新鲜度等于实时 LSP 新鲜度
不声称每个内部语义辅助函数都通过 HTTP 或 SDK 暴露
当前实现中没有 Rust 语义运行时拆分
不声称 AX Wiki 的 markdown 是结构事实来源（见 AX Wiki）

集成指引

编写文档、SDK 绑定或更高层工作流时：

把 lsp 和 code_intelligence 描述为分开的语义表面
区分公共工具操作和内部辅助函数
只描述当前模式中实际保留的审计/回放保证
当某个语义表面并非总是启用时，提及标志
提到 AX Wiki 时，明确 Wiki 与图谱的职责

语义层