Span

为编码 Agent 提供持久的代码库理解。

Span 是一个本地 MCP 服务，它会将 Agent 对代码库的了解与相关代码关联起来，并在支撑依据发生变化时标记为过时。

快速开始 · 工作原理 · 文档

问题

编码 Agent 要么依赖可能已与代码库不符的文档和记忆，要么每次会话都重新阅读同一份源代码、测试、契约和配置，并重建相同的理解。

笔记变得有误时，通常不会发生任何明显的问题。文件看起来仍然有效，Agent 也会继续读取它，而下一次会话仍从同样的不确定性开始。

Span 为 Agent 提供了第三种选择：将已有的理解与其支撑依据一起保存，并明确说明这些依据是否仍然有效。

看看效果

这是当前构建版本针对一个双文件测试样例进行的真实交互。客户端是一个脚本化的 MCP 客户端，而非模型；它展示的是通信内容和新鲜度行为，而非模型判断。原始记录见当前 MCP 验收证据。

> explain src/alpha.py
Pending cont-1  CQ-01
  "VALUE = 1"

> submit_interpretation cont-1
PURPOSE  alpha computes the value
  CURRENT

> explain src/alpha.py
PURPOSE  alpha computes the value
  CURRENT

# edit src/alpha.py

> status src/alpha.py
PURPOSE  alpha computes the value
  STALE
  evidence changed
  scope: src/alpha.py

> refresh src/alpha.py
Pending cont-6  CQ-01
  "VALUE = 1 # touched"

> submit_interpretation cont-6
PURPOSE  alpha computes the value
  CURRENT
predecessor  STALE

首次调用会挂起并返回一个有界任务。提交内容明确了用途，随后 explain 会读取该内容，并将其报告为当前有效。文件更改后，status 会将该用途报告为过时，并指出已更改的文件以及需要重新检查的范围。刷新操作会重新检查这一个范围；新的结果变为当前有效，同时保留前一条记录并标记为过时。

过时意味着支撑依据发生了变化，并不意味着 Span 已证明旧结论是错误的。

这次编辑没有使整个代码库失效，也没有让旧结论继续看起来有效。Span 不会删除第一次调查；它会确保这项工作不会在会话结束时被丢弃。

工作原理

测试为代码提供反馈循环，而 Span 为代码库理解提供反馈循环。

1. 建立。 Agent 调查一个范围明确的区域。Span 会将结论与所用证据及其权威依据一并保存。
2. 复用。 后续 Agent 可以获取已建立的理解，同时其依据仍然有效。
3. 精确失效。 当支持证据发生变化时，只有依赖该证据的理解会变为 STALE。
4. 重新检查。 Agent 调查受影响的范围并提交新结果。未受影响的理解仍保持有效；前一版本会保留为历史记录。

状态	含义
CURRENT	记录的理解仍得到其所依赖的证据和前提支持。
STALE	相关支持依据在建立该理解后发生了变化。将其视为当前理解之前，请重新检查。
UNVERIFIABLE	存在结论，但无法获取确认该结论所需的支持依据：记录的来源不在清单中、缺少权威种子、无法获取清单指纹，或有界前提遍历未能完成。它既非当前，也不能确定为已过时。提供方或存储故障不属于此状态——此时操作会失败。

快速开始

Span 目前需要 Linux（已验证的安装路径）、Python 3.12 或更高版本，以及带有 npm 的 Node.js。

pipx install span-mcp        # or: pip install span-mcp
span-install --repo /path/to/your/repo

span-install 会创建 Span 的运行时环境、配置受管理的结构化索引器、部署 Agent Skills，并注册受支持的主机。安装后，请重启或重新加载编码 Agent。

验证安装：

span-install --verify-only

如需从源代码检出版本开始操作——例如参与贡献或固定到某个提交——请克隆代码库并从其根目录运行安装程序：

git clone https://github.com/pontivus-com/span.git
cd span
python3 scripts/install-span.py --repo /path/to/your/repo

安装只会建立运行就绪状态，不会建立对代码库的理解。手动 Codex 命令和 OpenCode 入口请参阅安装与连接。

兼容对象

主机	设置
Claude Code	检测到 Claude Code CLI 时，由安装程序管理：用户范围的 MCP 注册、位于 ~/.claude/skills 的技能，以及位于 ~/.claude/settings.json 的仅报告生命周期钩子。手动注册方法请参阅安装与连接。
Codex	检测到 Codex CLI 时，由安装程序管理。手动注册方法请参阅安装与连接。
OpenCode	存在 opencode.json 时由安装程序管理。受支持的手动配置项请参阅安装与连接。
其他 MCP 主机	使用 span-mcp --data-dir <DATA_DIR> --repo <TARGET_REPO> 通过 stdio 连接。

Span 在本地通过 stdio 运行。它不会调用大模型、选择模型或存储提供方凭据。其状态存储在分析对象代码库之外的数据目录中。

它的不同之处

文档记录答案。Agent 记忆会记住。搜索会查找证据。 Span 在它们之间维护解释层：结论、证据、权威性、依赖关系和时效性。

方法	持久保存解读后的理解	跟踪其是否仍有依据	显示变化及其范围	支持限定范围的语义重新检查
传统文档或生成式文档	是	本身不具备	否	否
通用 Agent 记忆	是	本身不具备	否	本身不具备
经引用验证的 Agent 记忆	是	是，逐条事实跟踪	否——不予提供未验证内容	否
代码搜索 / 结构图	目的不同	仅跟踪来源或结构	仅限结构层面	不进行语义重新评估
Span	是	是，逐项、逐前提和逐发现范围跟踪	是，并说明原因	是

详细比较以及验证与限定范围的疑问之间的区别，请参阅范围与边界。

它不是什么

• 不是文档生成器。
• 不是通用 Agent 记忆，无论是否经过验证。
• 不是代码搜索或结构图。
• 不是大模型服务：它绝不会调用模型或存储服务提供商凭据。
• 不是自主运行的：它不会编辑代码、运行测试，也不会自行更新过时的理解。

完整列表请参阅范围与边界。

状态

Span 目前处于 beta 阶段。Linux 是目前已验证的安装方式；macOS 和 Windows 的安装方式已预留，但尚未验证。公开操作接口包含 11 个 MCP 操作；请参阅 MCP 参考。已记录的验收运行结果见验收证据。

如果 Span 对你有用，点个星标有助于其他开发者发现它。欢迎提供反馈和报告问题。

文档

• 仓库概览
• 安装和连接
• 使用 Span
• MCP 参考
• 时效性与刷新
• 证据、权威性与信任
• 范围、边界与差异
• 常见问题
• 架构
• 完整文档索引
• 术语表
• 变更日志

参与贡献

请参阅贡献指南。更改应保留核心约定：只有在所需的支持证据仍然有效时，既有理解才可复用。安全问题通过 SECURITY.md 处理。支持说明见 SUPPORT.md。

注册表

官方 MCP 注册表条目：io.github.pontivus-com/span

mcp-name: io.github.pontivus-com/span

许可证

Span 根据 Apache License 2.0（Apache-2.0）授权。请参阅 LICENSE。

一句话概括

Span 为编码 Agent 提供不会悄然过时的代码库理解：复用仍然有效的内容，只重新检查发生变化的部分。