符号三角分类账
AI编码代理的卡片优先代码上下文
停止将整个文件送入上下文窗口。
开始为特工提供他们所需的代码情报。
有什么问题吗?
每次AI编码代理读取文件以回答问题时,它都会消耗数千个令牌。这些令牌中的大多数与任务无关。代理不需要500行文件就能知道 validateToken 需要a string 并返回a Promise --但无论如何,它都会阅读它们,因为这就是它的全部。
将其乘以一个调试会话,涉及20个文件,仅在上下文收集上就消耗了40000多个令牌。
SDL-MCP解决了这个问题。它将你的代码库索引到一个可搜索的 符号图 并且通过受控的升级路径精确地提供适量的上下文。使用SDL-MCP的代理在消耗一小部分令牌的同时更好地理解您的代码。
它是如何工作的——30秒内```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
Codebase["Your Codebase"]
Indexer["Indexer
12 languages
Rust native or Tree-sitter fallback"]
Graph["LadybugDB graph
symbols, edges, metrics, versions"]
MCP["Current MCP surfaces
33 flat, 6 gateway, 4 Code Mode"]
CLI["13 CLI commands"]
HTTP["HTTP API and graph UI"]
Agent["AI coding agent
Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]
Codebase e1@--> Indexer
Indexer e2@--> Graph
Graph e3@--> MCP
Graph e4@--> CLI
Graph e5@--> HTTP
MCP e6@--> Agent
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5,e6 animate;
1. **索引一次** --SDL-MCP解析存储库中的每个符号,并将其作为压缩元数据记录(“符号卡”)存储在图形数据库中
1. **高效查询** --代理使用MCP工具来搜索、切片和检索他们所需的上下文
1. **仅在必要时升级** --一个四级阶梯控制代理看到的代码量,从100个令牌卡到完整源代码(需要说明理由)
______________________________________________________________________
## 先决条件
- **Node.js 24+** 是必需的(下载).SDL-MCP使用早期版本中不可用的Node.js功能。跑 `node -v` 检查。
> **安装过程中是否出现对等依赖警告?** 树保姆语法包可能会生成 `ERESOLVE` 关于对等依赖的警告。这些都是无害的——安装成功,一切正常。添加 `--legacy-peer-deps` 为了抑制它们: `npm install -g sdl-mcp --legacy-peer-deps`.SDL-MCP的后安装还验证树保姆语法绑定,并在修剪源之前重建缺失的语法绑定;安装该用途 `--ignore-scripts` 应该跑 `npm rebuild tree-sitter tree-sitter-kotlin` 如果语法不可用。
______________________________________________________________________
## 快速开始```bash
# Install (requires Node.js 24+)
npm install -g sdl-mcp
# Initialize, auto-detect languages, index your repo, and run health checks
sdl-mcp init -y --auto-index
# Start the MCP server for your coding agent
sdl-mcp serve --stdio
将MCP客户端指向服务器,代理就可以访问SDL-MCP当前配置的表面。默认为独占代码模式;集 codeMode.exclusive: false 当您希望在一个会话中使用代码模式和常规平面或网关工具时。
> npx用户: 替换 sdl-mcp 随着 npx --yes sdl-mcp@latest 在上述所有命令中。
完整入门指南→
鸢尾门梯子
核心创新。Iris Gate Ladder以控制光学系统中光流的可调光圈命名,它允许代理将其上下文“光圈”从针孔调到全开。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TB
R1["~100 tokens
Rung 1: Symbol Card
Name, signature, summary, dependencies, metrics"]
R2["~300 tokens
Rung 2: Skeleton IR
Signatures and control flow with bodies elided"]
R3["~600 tokens
Rung 3: Hot-Path Excerpt
Identifier-focused lines with context"]
R4["~2,000 tokens
Rung 4: Raw Code Window
Policy-gated full source"]
R1 e1@--> R2
R2 e2@--> R3
R3 e3@--> R4
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3 animate;
> **大多数问题在第1-2级得到回答** 无需阅读原始代码。这就是代币储蓄的来源。
|场景|读取文件|使用阶梯|节省|
| :----------------------------------- | :--------------: | :--------------: | :-----: |
|“什么 `parseConfig` 接受?“|~2000托|~100托| **20倍** |
|“给我看看它的形状 `AuthService`“|~4000托|~300托| **13x** |
|“在哪里 `this.cache` 设置?“|~2000托|~500托| **4x** |
**为什么重要:**
- **4-20倍代币储蓄** 典型代码理解查询
- 在第一至第二阶段,大多数问题都是在没有阅读原始代码的情况下回答的
- 受控升级可防止代理过度消耗上下文
- 策略门控的原始访问确保代理证明他们需要完整的源代码
Iris Gate梯子深潜→
______________________________________________________________________
## 特色之旅
### 符号卡——理解的原子
每个函数、类、接口、类型和变量都成为 **符号卡**:一个紧凑的元数据记录(约100个令牌),包含代理所需的一切 _理解_ 不读取代码的符号。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TB
Card["Symbol Card: validateToken"]
Kind["Kind: function (exported)"]
File["File: src/auth/jwt.ts:42-67"]
Signature["Signature: (token: string, opts?: ValidateOpts) -> Promise"]
Summary["Summary: validates JWT signature and expiration"]
Invariants["Invariants: throws on expired token"]
SideEffects["Side effects: logs to audit trail"]
Deps["Dependencies: verifySignature, checkExpiry, jsonwebtoken, AuditLogger"]
Metrics["Metrics: fan-in 12, fan-out 4, churn 3/30d"]
Context["Context: auth-module, request-pipeline, auth.test.ts"]
ETag["ETag: a7f3c2..."]
Card e1@--> Kind
Kind e2@--> File
File e3@--> Signature
Signature e4@--> Summary
Summary e5@--> Invariants
Invariants e6@--> SideEffects
SideEffects e7@--> Deps
Deps e8@--> Metrics
Metrics e9@--> Context
Context e10@--> ETag
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;
卡片包括 信心评分呼叫解决 (pass-2解析器跟踪导入、别名、桶再导出和标记模板,以产生准确的依赖关系边), 社区发现 (集群成员资格),以及 呼叫链追踪 (具有进入/中间/退出角色的流程参与)。
为什么重要:
- 每个符号约100个代币 与读取完整文件的约2000个令牌相比
- 置信度评分的依赖关系边跟踪跨文件的真实调用关系
- 社区检测和呼叫链追踪揭示了架构结构
- 基于ETag的条件请求避免重新获取未更改的符号
- 工作流ETag缓存现在种子
slice.build随着knownCardEtags因此,重复的切片构建可以跳过未更改的卡片
索引和语言支持Deep Dive→
图切片——每个任务的正确上下文
SDL-MCP遵循以下步骤,而不是读取同一目录中的文件 依赖图。从与任务相关的符号开始,它遍历加权边(调用:1.0,配置:0.8,导入:0.6),根据相关性对每个符号进行评分,并返回令牌预算内最重要的N个符号。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
Task["Task: Fix the auth middleware"] e1@--> Slice["sdl.slice.build"]
Slice e2@--> Auth["authenticate"]
Slice e3@--> Validate["validateToken"]
Slice e4@--> Config["JwtConfig"]
Auth e5@--> Hash["hashPassword"]
Validate e6@--> User["getUserById"]
Config e7@--> Env["envLoader"]
Env e8@-. frontier outside budget .-> Frontier["spillover frontier"]
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5,e6,e7,e8 animate;
切片具有句柄、租约、刷新(仅增量更新)和溢出(分页溢出)。您还可以完全跳过符号搜索——传递一个 `taskText` string和SDL-MCP自动发现相关的条目符号。
**为什么重要:**
- 跟随 **依赖图**,而不是目录边界,用于跨领域上下文
- 加权边缘评分(调用>配置>导入)优先考虑最相关的符号
- 代币预算:只返回符合您预算的内容(约800个代币,而原始文件约16000个)
- 自然语言任务文本自动发现条目符号——不需要符号ID
图形切片深度学习→
______________________________________________________________________
### 增量包和爆炸半径——语义变化智能
`git diff` 告诉你哪些线路变了。SDL-MCP告诉您发生了什么变化 _手段_ 以及谁受到了影响。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
Change["Modified validateToken() signature"]
Sig["signatureDiff
added options?: object"]
Inv["invariantDiff
added throws on expired"]
Fx["sideEffectDiff
added logs to audit trail"]
Blast["Blast radius"]
A1["authenticate()
distance 1"]
A2["refreshSession()
distance 1"]
A3["AuthMiddleware
distance 2"]
A4["auth.test.ts
re-run recommended"]
Change e1@--> Sig
Change e2@--> Inv
Change e3@--> Fx
Sig e4@--> Blast
Inv e5@--> Blast
Fx e6@--> Blast
Blast e7@--> A1
Blast e8@--> A2
Blast e9@--> A3
Blast e10@--> A4
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;
公关风险分析 (sdl.pr.risk.analyze)将其打包成一个带有发现、证据和测试建议的评分评估。 趋势分析中的风扇 检测“放大器”符号,其依赖性计数的增长意味着波纹会随着时间的推移而进一步变化。
为什么重要:
- 语义差异显示了什么变化 手段,而不仅仅是移动了哪些线条
- 分级爆炸半径标识了哪些相关符号最具风险
- Fan-in趋势分析检测到“放大器”符号,其变化会随着时间的推移而进一步波动
- 公关风险评分产生可操作的发现,并提出重新运行测试的建议
三角洲和爆炸半径深潜→
实时索引——实时代码智能
SDL-MCP不会等待您进行保存。当您在编辑器中键入时,缓冲区更新会被推送到内存中的覆盖存储中,在后台解析,并与持久数据库合并。搜索、卡片和切片反映了您的 当前的 代码,而不是上次保存。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
Editor["Editor keystrokes"] e1@--> Push["sdl.buffer.push"]
Push e2@--> Overlay["Overlay store"]
Overlay e3@--> Reads["Merged reads
search, cards, slices"]
Overlay e4@--> Persist["save / idle checkpoint"]
Persist e5@--> DB["LadybugDB durable graph"]
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5 animate;
**为什么重要:**
- 搜索、卡片和切片反映 **未保存的编辑器更改** 实时
- 在主动开发过程中不需要手动重新索引
- 后台AST解析和内存覆盖使查询速度更快
实时索引深度学习→
______________________________________________________________________
### 治理与政策——受控访问
原始代码访问(第4级)为 **政策封闭**。代理商必须提供:
- A. **原因** 解释为什么他们需要原始代码
- **标识符** 他们希望在代码中找到
- 一 **预期行数** 在配置的限制范围内
不符合政策的请求将被拒绝,并提供可操作的指导(“尝试 `getHotPath` 用这些标识符代替“)。每次访问都会被审计记录。
沙盒运行时执行工具(`sdl.runtime.execute`)有自己的治理层:默认启用,但仍由可执行文件分配、CWD监禁、环境清理、并发限制和超时强制保护。这 `outputMode` 参数(`"minimal"` · `"summary"` · `"intent"`)默认为 `"minimal"` 节省约95%的代币 `sdl.runtime.queryOutput` 在需要时启用按需输出检索。
**为什么重要:**
- 需求证明门控可防止代理浪费时间读取原始代码
- 被拒绝的请求包括 **可操作的次优行动** 指导
- 对每个代码访问决策进行完整的审计日志记录
- 沙盒运行时,具有可执行文件分配、CWD监禁和环境清理功能
治理与政策深度探讨→
______________________________________________________________________
### 代理上下文——任务型检索
`sdl.context` 是SDL-MCP的任务型上下文引擎。给它一个任务类型(`debug`, `review`, `implement`, `explain`)、描述和预算——它选择正确的Iris Gate梯级,收集证据,并返回与工作相匹配的上下文。在代码模式下, `sdl.context` 提供相同的检索界面,而不会掉入 `sdl.workflow`.
默认情况下,未处理的自然语言上下文调用使用置信门控混合检索。精确的符号提及和明确 `focusPaths` / `focusSymbols` 坚持走捷径;低置信度词汇结果可以升级为有界FTS+向量检索。集 `options.semantic: true` 强制混合检索,或 `options.semantic: false` 为了确保确定性调试,仅保留词法行为。
反馈回路(`sdl.agent.feedback`)记录哪些符号有用,哪些符号缺失,以提高未来的切片质量。
对于可移植的导出,如票证和PR描述,请使用CLI `sdl-mcp summary` 命令。它以markdown、JSON或剪贴板格式生成令牌约束的上下文简报,供MCP环境之外使用。
**为什么重要:**
- 任务型上下文检索计划 **右侧虹膜门路径** 在代币预算范围内
- 置信门控混合检索在不减慢已知目标查找速度的情况下改进了发现
- 反馈循环记录有用/缺失的内容,提高未来的切片质量
- 可移植的上下文摘要导出结果,供MCP环境外使用
Agent上下文深度学习→ · 上下文模式→
______________________________________________________________________
### 沙盒运行时执行
通过SDL-MCP的治理层运行测试、linter和脚本,而不是不受控制的shell访问。16个运行时(Node.js、Python、Go、Java、Rust、Shell等)、代码模式或args模式、带有关键字匹配摘录的智能输出摘要和gzip工件持久性。
**为什么重要:**
- 运行测试、linter和脚本 **治理之下** 而不是不受控制的shell访问
- 支持16个运行时(Node、Python、Go、Java、Rust、Shell等)
- 可执行文件分配、CWD监禁、超时执行和环境清理
- 具有关键字匹配摘录和gzip工件持久性的智能输出摘要
运行时执行深度学习→
______________________________________________________________________
### 发展记忆——跨会话知识持久性(选择加入)
特工在两次会议之间会忘记一切。SDL-MCP使用 **选择加入图形支持的内存系统** 它允许代理存储直接链接到它们所关联的符号和文件的决策、错误修复上下文和任务注释。内存是 **默认情况下禁用** 并且必须在配置中明确启用。启用后,内存既存储在图形数据库中(用于快速查询),也存储在markdown文件中(用于版本控制和团队共享)。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
Session1["Agent session 1
records bugfix memory"] e1@--> Store["sdl.memory.store"]
Store e2@--> Graph["LadybugDB memory node"]
Store e3@--> Files[".sdl-memory/bugfixes/.md"]
Graph e4@--> Link1["MEMORY_OF -> authenticate()"]
Graph e5@--> Link2["HAS_MEMORY -> repo"]
Session2["Agent session 2"] e6@--> Surface["sdl.memory.surface"]
Surface e7@--> Graph
Graph e8@--> Recall["Relevant memory surfaced
race condition fix in authenticate()"]
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5,e6,e7,e8 animate;
启用后,存储器 自动浮出水面 在图切片内部——当一个代理构建一个带有链接记忆的触摸符号的切片时,这些记忆会出现在卡片旁边。在重新索引期间,与更改的符号链接的内存 标记为陈旧,提示代理审查和更新它们。四种MCP工具(store, query, remove, surface)提供完整的CRUD以及基于置信度、新近度和符号重叠的智能排名。内存工具仅在配置中启用内存时可用。
为什么重要:
- 结构化知识 跨会话持续,直接链接到符号和文件
- 默认情况下选择加入并禁用--通过启用
"memory": { "enabled": true }在配置中 - 启用后,当触摸相关符号时,会自动出现在图形切片内
- 在重新索引过程中,当链接的符号发生变化时,标记陈旧的记忆
- 双存储:用于快速查询的图形数据库+用于版本控制和团队共享的标记文件
发展记忆深潜→
SCIP集成——编译器级交叉引用
Tree sitter为SDL-MCP提供了跨支持的Types/JavaScript、Python、Go、Java、C#、C/C++、PHP、Rust、Kotlin和Shell表面的快速语法级符号提取。SCIP(源代码智能协议)对此进行了补充 编译器级交叉引用 来自scip-typescript、scip-go和锈迹分析仪等工具。生成一个 .scip 索引文件,指向SDL-MCP,启发式边升级为精确的编译器验证边,外部依赖符号成为一级图节点,新的 implements 边缘揭示了语法分析无法发现的界面/特征关系。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
Compiler["Compiler / Type Checker"] e1@--> SCIP[".scip index file"]
SCIP e2@--> Ingest["sdl.scip.ingest"]
Ingest e3@--> Upgrade["Heuristic edges → exact edges"]
Ingest e4@--> External["External dependency nodes"]
Ingest e5@--> Implements["implements edges"]
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2,e3,e4,e5 animate;
**为什么重要:**
- 将启发式呼叫解析升级为 **编译器验证了精确边** (置信度0.95)
- 外部依赖(npm包、Go模块、crate-deps)成为可搜索的图节点
- 通过以下方式跟踪接口/特性实现 `implements` 边缘
- 自动摄取开启 `sdl.index.refresh` 以零手动步骤保持SCIP数据的最新状态
- 补充:树保姆提供结构,SCIP提供语义精度
SCIP集成深度挖掘→
______________________________________________________________________
### CLI工具访问--不需要MCP服务器
访问SDL-MCP直接操作别名以及低风险 `action.search` 和 `manual` 使用命令行中的元数据代理 `sdl-mcp tool`。不需要MCP服务器、传输或SDK。```bash
# Search for symbols
sdl-mcp tool symbol.search --query "handleAuth" --output-format pretty
# Build a task-scoped slice
sdl-mcp tool slice.build --task-text "debug auth flow" --max-cards 50
# Pipe JSON args, chain commands
echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"
# Apply a single-file targeted write
sdl-mcp tool file.write --repo-id my-repo --file-path config/app.json \
--json-path server.port --json-value 8080
# Discover and inspect metadata without opening the graph DB
sdl-mcp tool action.search --query manual --summary-only
sdl-mcp tool manual --actions action.search --format json
功能包括类型化参数强制(字符串、数字、布尔值、字符串[]、json)、预算标志合并、具有CLI标志优先级的stdin json管道、自动解析 repoId 从cwd for graph操作中,有四种输出格式(json、json-compact、pretty、table)、拼写建议和每个操作 --help直接图动作通过与MCP服务器相同的网关路由器和Zod模式进行调度; action.search 和 manual 在进程中对MCP注册使用的相同元数据处理程序运行。
为什么重要:
- 36个直接图形/动作别名
action.search和manual可从以下位置访问元数据代理 任何终端 -无需服务器、传输或SDK - 直接图动作保持网关路由器/Zod奇偶校验;元数据代理共享相同的MCP注册处理程序
- 脚本和CI管道的四种输出格式(json、json-compact、pretty、table)
- 自动解析cwd中的repoId,支持stdin JSON管道和每次操作
--help
CLI工具访问深度学习→
工具网关——紧凑型工具注册
工具网关将35个网关可路由的SDL操作投影到 4个命名空间范围的工具 (sdl.query, sdl.code, sdl.repo, sdl.agent),减少 tools/list 从完全平坦的模式表面到紧凑的网关表面的开销。```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
Before["Flat mode
38 tools
2 universal + 36 flat"] e1@--> After["Gateway mode
6 tools
2 universal + 4 gateway"]
After e2@--> Savings["Smaller tools/list payload
lower agent startup overhead"]
classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
class e1,e2 animate;
每个网关工具都接受一个 `action` 鉴别器字段(例如。, `{ action: "symbol.search", repoId: "x", query: "auth" }`)并通过双重Zod验证路由到相同的处理程序。中的细线模式 `tools/list` 在服务器端进行完全验证时,保持注册紧凑。仅限公寓 `sdl.file.write` 今天,行动仍处于网关模式之外。
**为什么重要:**
- 大幅减少 `tools/list` 网关优先代理的开销
- 35个网关可路由操作合并到4个命名空间范围的工具中,以简化代理选择
- 更少的工具选择意味着代理可以更快、更准确地分发工具
- 首先选择任务型检索的编码模式;当您还需要常规的平面或网关工具时,选择退出独占代码模式
工具网关深潜→
______________________________________________________________________
### 观察性仪表板
内置的只读仪表板显示诊断SDL-MCP行为所需的每个指标,而无需解析stderr日志。GlitterKill深色用户界面 `/ui/observability` 仅在HTTP传输或环回上 `sdl-mcp serve --stdio --dashboard-port ` sidecar,加上REST+SSE API(`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`)用于程序化访问。表面缓存命中率、混合检索故障(FTS/向量/PPR/RRF)、波束搜索决策跟踪、索引管道度量、写池和漏极饱和、打包线令牌效率和运行时CPU/内存/事件循环探测。看 可观测性仪表板深潜.
______________________________________________________________________
## 当前刀具表面概览
|模式|刀具计数|组成|
| :------------------ | :--------- | :--------------------------------------------------------------- |
|公寓| `38` | `2` 普遍性+ `36` 扁平工具|
|网关| `6` | `2` 普遍性+ `4` 网关工具|
|网关+传统| `42` | `2` 普遍性+ `4` 网关+ `36` 扁平工具|
|代码模式独占| `5` | `sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow` |
真理的来源是 `docs/generated/tool-inventory.md`.
Category · Tool · One-Line Description
Repository · sdl.repo.register · Register a codebase for indexing
sdl.repo.status · Health, versions, watcher, prefetch, live-index stats
sdl.repo.overview · Codebase summary: stats, directories, hotspots, clusters, with conditional ETag fetch support
sdl.index.refresh · Trigger full or incremental re-indexing
Live Buffer · sdl.buffer.push · Push unsaved editor content for real-time indexing
sdl.buffer.checkpoint · Force-write pending buffers to the durable database
sdl.buffer.status · Live indexing diagnostics and queue depth
Symbols · sdl.symbol.search · Search symbols by name (with optional semantic reranking)
sdl.symbol.getCard · Get one card or batch-fetch up to 100 cards with ETag-based conditional support
sdl.symbol.edit · Preview/apply one symbol-scoped edit with AST, range, file, and draft preconditions
Slices · sdl.slice.build · Build a task-scoped dependency subgraph
sdl.slice.refresh · Delta-only update of an existing slice
sdl.slice.spillover.get · Page through overflow symbols beyond the budget
Code Access · sdl.code.getSkeleton · Signatures + control flow, bodies elided, with conditional ETag fetch support
sdl.code.getHotPath · Lines matching specific identifiers + context, with conditional ETag fetch support
sdl.code.needWindow · Full source code (policy-gated, requires justification)
Deltas · sdl.delta.get · Semantic diff + blast radius between versions
Policy · sdl.policy.get · Read current gating policy
sdl.policy.set · Update line/token limits and identifier requirements
Risk · sdl.pr.risk.analyze · Scored PR risk with findings and test recommendations
Agent · sdl.agent.feedback · Record which symbols were useful or missing
sdl.agent.feedback.query · Query aggregated feedback statistics
Runtime · sdl.runtime.execute · Sandboxed subprocess execution with outputMode (minimal/summary/intent)
sdl.runtime.queryOutput · On-demand retrieval and keyword search of stored output artifacts
Memory · sdl.memory.store · Store or update a development memory with symbol/file links
sdl.memory.query · Search memories by text, type, tags, or linked symbols
sdl.memory.remove · Soft-delete a memory from graph and optionally from disk
sdl.memory.surface · Auto-surface relevant memories for a task context
Code Mode · sdl.context · Code Mode task-shaped context retrieval for explain/debug/review/implement work
sdl.workflow · Multi-step operations with budget tracking, ETag caching, and transforms
sdl.manual · Self-documentation — query usage guide, action schemas, output format reference
SCIP · sdl.scip.ingest · Ingest a pre-built SCIP index for compiler-grade cross-references (with dry-run support)
File · sdl.file.read · Read non-indexed files (configs, docs, templates) with line-range, search, or JSON-path modes
sdl.file.write · Policy-aware write helper for non-indexed files and templates
Meta · sdl.info · Runtime diagnostics — version, Node.js, platform, database, config paths
sdl.usage.stats · Session and lifetime token savings statistics
sdl.action.search · Search SDL action catalog to discover the right tool for a task
完整的MCP工具参考(详细参数和响应)→
______________________________________________________________________
## CLI命令
|命令|描述|
| :------------------ | :------------------------------------------------------------------------------------- |
| `sdl-mcp init` |Bootstrap配置,检测仓库/语言,可选自动索引|
| `sdl-mcp doctor` |验证运行时、配置、数据库、语法、仓库访问|
| `sdl-mcp index` |索引存储库(可选 `--watch` 模式)|
| `sdl-mcp serve` |启动MCP服务器(`--stdio` 或 `--http`) |
| `sdl-mcp tool` |访问36个直接操作别名(文档) |
| `sdl-mcp info` |运行时诊断——版本、Node.js、平台、数据库、配置|
| `sdl-mcp summary` |从CLI生成复制/粘贴上下文摘要|
| `sdl-mcp health` |使用徽章/JSON输出计算复合健康评分|
| `sdl-mcp benchmark` |运行CI回归基准测试|
| `sdl-mcp export` |导出同步工件|
| `sdl-mcp import` |导入同步工件|
| `sdl-mcp pull` |按版本拉取/回退提交|
| `sdl-mcp version` |显示版本和环境信息|
CLI参考→ · 配置参考→
______________________________________________________________________
## 兼容
SDL-MCP适用于任何兼容MCP的客户端:
|客户端|传输|设置|
| :----------------- | :----------- | :---------------------------------- |
| **克劳德代码** |站立 | `sdl-mcp init --client claude-code` |
| **克劳德桌面版** |站立 | `sdl-mcp init --client claude-code` |
| **光标** |stdio |标准MCP服务器配置|
| **帆板运动** |stdio |标准MCP服务器配置|
| **Codex CLI** |站立 | `sdl-mcp init --client codex` |
| **Gemini CLI** |站立 | `sdl-mcp init --client gemini` |
| **开源代码** |站立 | `sdl-mcp init --client opencode` |
| **任何MCP客户端** |stdio/http| `sdl-mcp serve --stdio` 或 `--http` |
A. **VSCode扩展** (`sdl-mcp-vscode/`)提供实时缓冲区集成,用于对未保存的编辑进行实时索引。
______________________________________________________________________
## 技术栈
|组件|技术|
| :----------------- | :----------------------------------------- |
|运行时| Node.js 24+/TypeScript 5.9+(严格的ESM)|
|图形数据库|LadybugDB(嵌入式,单文件)|
|索引器(默认)|通过napi-rs进行Rust(多线程)|
|索引器(后备)|树保姆+树保姆打字脚本|
|MCP SDK |@modelcontextprotocol/SDK|
|验证|所有有效载荷的Zod模式|
|传输|stdio(代理)·HTTP(开发/网络)|
______________________________________________________________________
## 系统架构```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
Clients["MCP clients
Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]
Gateway["Tool gateway
sdl.query, sdl.code, sdl.repo, sdl.agent"]
Flat["Flat tools and optional code-mode surfaces"]
Policy["Policy engine
proof-of-need, budgets, audit logging"]
Graph["LadybugDB graph
symbols, edges, files, versions, memories"]
Indexer["Indexer pipeline
Rust native or Tree-sitter fallback
pass 1, pass 2, semantic enrichment"]
Clients e1@--> Gateway
Clients e2@--> Flat
Gateway e3@--> Policy
Flat e4@--> Policy
Policy e5@--> Graph
Indexer e6@--> Graph
…(正文过长,页面只展示前面部分,完整内容见仓库)
