SVP 是一个 "智能上下文网关"（Smart Context Gateway），位于原始代码库和AI Agent之间，负责：
- 摄取（Ingest）：读取源码 + 人类配置的外部上下文
- 体素化（Voxelize）：将代码转换为语义体素空间
- LOD管理（LOD Management）：根据任务动态调整抽象层次
- 暴露（Expose）：通过标准化接口提供给AI Agent
- 反向同步（Sync）：将AI的理解单向同步给IDE/用户
┌─────────────────────────────────────────────────────────────────────────────┐
│ SVP 智能上下文网关 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │
│ │ 原始代码库 │ │ SVP 核心引擎 │ │ AI Agent │ │
│ │ │─────▶│ │─────▶│ (Claude/Cursor │ │
│ │ • 源码文件 │ │ • 体素化引擎 │ │ /Copilot) │ │
│ │ • Git历史 │ │ • LOD管理器 │ │ │ │
│ │ • 依赖关系 │ │ • 上下文聚合器 │ │ 通过MCP/A2A │ │
│ │ │ │ • 虚拟文件系统 │ │ 或原生SDK │ │
│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────┐ │ │
│ │ │ 人类配置层 │ │ │
│ │ │ │ │ │
│ └──────────────▶│ • .svp/config │ │ │
│ │ • 设计文档 │ │ │
│ │ • .env变量 │ │ │
│ │ • 截图/架构图 │ │ │
│ │ • 外部API文档 │ │ │
│ └──────────────────┘ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────┐ ┌─────────────────┐ │
│ │ IDE / CLI │◀─────│ 单向同步通道 │ │
│ │ │ │ │ │
│ │ • 3D可视化视图 │ │ • 高亮代码 │ │
│ │ • LOD导航UI │ │ • 注释标记 │ │
│ │ • 上下文面板 │ │ • 架构图更新 │ │
│ └──────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ IDE (VS Code / JetBrains) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SVP IDE Extension │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ UI Panel │ │ Voxel Engine│ │ MCP Client │ │ │
│ │ │ (3D View) │ │ (In-Proc) │ │ (Comm) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ LSP Adapter │ │ MCP Server │ │ │
│ │ │ (Symbols) │ │ (External) │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 本地进程间通信 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ AI Agent (Claude/Cursor/Copilot) │ │
│ │ (通过MCP连接) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
特点：
- SVP引擎运行在IDE进程内（In-Process）
- 直接访问LSP获取符号信息
- 通过MCP与AI Agent通信
- UI面板提供3D可视化和LOD控制
适用场景：
- 个人开发者
- 小型团队
- 实时交互需求高的场景
┌─────────────────────────────────────────────────────────────────┐
│ 开发者机器 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SVP CLI Service │ │
│ │ (独立进程 / Docker) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ File Watcher│ │ Voxel Engine│ │ HTTP/gRPC │ │ │
│ │ │ (监听变更) │ │ (体素化) │ │ API Server │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 源码缓存 │ │ 体素索引 │ │ 会话管理 │ │ │
│ │ │ (Git+File) │ │ (Octree) │ │ (多项目) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ HTTP/MCP/gRPC │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ AI Agent / IDE / CI/CD │ │
│ │ (多个客户端可以同时连接) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
特点：
- SVP作为独立服务运行（Out-of-Process）
- 支持多项目、多客户端同时连接
- 提供HTTP/gRPC/MCP多种协议
- 可部署在本地或远程服务器
适用场景：
- 企业团队（共享SVP服务）
- CI/CD集成
- 多IDE支持
- 云端部署
interface IngestionConfig {
// 源码配置
source: {
rootPath: string; // 项目根目录
include: string[]; // 包含模式: ['src/**/*', 'lib/**/*']
exclude: string[]; // 排除模式: ['node_modules', '.git', 'dist']
gitIntegration: boolean; // 是否读取Git历史
};
// 人类配置的外部上下文
context: {
configFiles: string[]; // .svp/config.yaml
designDocs: string[]; // docs/architecture.md
envVars: string[]; // .env.production
screenshots: string[]; // assets/architecture.png
apiSpecs: string[]; // openapi.yaml
};
// 实时同步
watch: {
enabled: boolean;
debounceMs: number;
triggerVoxelization: 'immediate' | 'manual' | 'scheduled';
};
}工作流程：
- 读取
.svp/config.yaml获取配置 - 扫描源码文件，建立文件索引
- 读取Git历史，获取变更记录
- 加载人类配置的文档/截图/.env
- 监听文件变更，触发增量体素化
interface VoxelizationEngine {
// 解析层
parser: {
language: 'typescript' | 'python' | 'go' | 'rust' | ...;
astParser: TreeSitterParser;
symbolResolver: LSPSymbolResolver;
};
// 体素生成
generator: {
// 将AST节点转换为语义体素
generateVoxels(ast: ASTNode[]): SemanticVoxel[];
// 构建空间索引（八叉树）
buildOctree(voxels: SemanticVoxel[]): OctreeIndex;
// 建立关系图谱（调用图、数据流）
buildRelationGraph(voxels: SemanticVoxel[]): RelationGraph;
};
// LOD管理
lodManager: {
// 为每个体素预计算5个LOD级别
precomputeLODs(voxel: SemanticVoxel): LODProfile;
// 根据上下文选择LOD
selectLOD(context: TaskContext): LODLevel;
// LOD平滑过渡
transitionLOD(from: LODLevel, to: LODLevel): TransitionAnimation;
};
}工作流程：
- 使用Tree-sitter解析源码为AST
- 使用LSP解析符号和类型信息
- 将AST节点映射为语义体素（3D空间坐标）
- 构建八叉树索引加速查询
- 分析调用关系、数据流关系
- 预计算每个体素的5个LOD级别
这是SVP的核心智能所在，负责决定暴露什么给AI。
interface ContextAggregator {
// 任务理解
taskAnalyzer: {
// 分析用户query，理解意图
analyzeQuery(query: string): TaskIntent;
// 识别相关代码区域
identifyRelevantVoxels(
query: string,
voxelSpace: OctreeIndex
): VoxelRef[];
};
// 上下文组装
contextBuilder: {
// 根据任务组装上下文
buildContext(
task: TaskIntent,
relevantVoxels: VoxelRef[],
lod: LODLevel
): ContextSnapshot;
// 管理上下文窗口（Token预算）
manageTokenBudget(
context: ContextSnapshot,
maxTokens: number
): TrimmedContext;
};
// 外部上下文融合
externalContext: {
// 加载设计文档
loadDesignDocs(voxels: VoxelRef[]): DesignDoc[];
// 加载环境变量
loadEnvVars(relevantModules: string[]): EnvVar[];
// 加载架构截图
loadScreenshots(component: string): Screenshot[];
};
}
// 暴露给AI的上下文快照
interface ContextSnapshot {
// 核心代码上下文（LOD处理后的体素）
codeContext: {
voxels: SemanticVoxel[]; // 相关体素
relations: RelationEdge[]; // 关系边（调用、依赖）
lod: LODLevel; // 当前LOD级别
};
// 外部上下文（人类配置）
externalContext: {
designDocs: DesignDoc[]; // 设计文档
envVars: EnvVar[]; // 环境变量
screenshots: Screenshot[]; // 架构截图
apiSpecs: APISpec[]; // API规范
};
// 元信息
meta: {
projectName: string;
language: string;
totalFiles: number;
totalVoxels: number;
coverage: number; // 上下文覆盖率
};
}工作流程：
- 接收AI的query（如"实现用户登录功能"）
- 分析query意图，识别关键实体（"用户"、"登录"）
- 在体素空间中搜索相关体素
- 根据任务类型选择合适的LOD
- 组装代码上下文（体素+关系）
- 加载相关设计文档、环境变量
- 管理Token预算，裁剪不相关内容
- 生成ContextSnapshot暴露给AI
这是暴露给AI的"沙箱视图"。
interface VirtualFileSystem {
// 虚拟文件夹结构（基于语义，而非物理文件）
virtualFolders: {
// 按功能模块组织
'/auth': {
'login.ts': VoxelRef[]; // 登录相关体素
'register.ts': VoxelRef[]; // 注册相关体素
'token.ts': VoxelRef[]; // Token相关体素
};
'/user': {
'profile.ts': VoxelRef[];
'settings.ts': VoxelRef[];
};
};
// 虚拟文件内容（LOD处理后的代码）
virtualFiles: {
readFile(path: string, lod: LODLevel): string;
readDirectory(path: string): VirtualDirent[];
exists(path: string): boolean;
};
// 沙箱隔离
sandbox: {
// 限制AI只能访问相关目录
restrictAccess(allowedPaths: string[]): void;
// 记录AI的所有文件操作（审计）
auditLog: FileOperation[];
};
}示例：
物理文件系统: 虚拟文件系统（暴露给AI）:
project/ /auth/
├── src/ ├── login.ts (LOD-4: 接口定义)
│ ├── auth/ │ ├── validate() (LOD-3: 算法逻辑)
│ │ ├── login.ts │ └── hashPassword() (LOD-2: 实现细节)
│ │ ├── utils/ └── token.ts
│ │ │ └── hash.ts /user/
│ │ └── token.ts └── profile.ts
│ └── user/
│ └── profile.ts
AI看到：
- 按功能组织的虚拟文件夹
- LOD处理后的代码（不是完整源码）
- 相关的设计文档链接
- 环境变量提示
SVP提供多种接口供AI Agent连接：
// SVP作为MCP Server暴露
class SVP_MCP_Server implements MCPServer {
// Resources: 暴露体素地图
resources = {
'voxel-map': {
uri: 'svp://{project}/voxels',
mimeType: 'application/vnd.svp.voxel+json'
},
'context-snapshot': {
uri: 'svp://{project}/context',
mimeType: 'application/vnd.svp.context+json'
}
};
// Tools: 提供LOD切换、查询等功能
tools = {
'switch-lod': {
description: 'Switch to a different LOD level',
inputSchema: {
level: { type: 'number', enum: [1, 2, 3, 4, 5] }
}
},
'query-voxels': {
description: 'Query voxels by semantic criteria',
inputSchema: {
keywords: { type: 'array', items: 'string' },
semanticType: { type: 'string' },
lod: { type: 'number' }
}
},
'navigate-relation': {
description: 'Navigate call graph or data flow',
inputSchema: {
voxelId: { type: 'string' },
relationType: { type: 'string', enum: ['caller', 'callee', 'data-in', 'data-out'] }
}
}
};
}// TypeScript SDK
import { SVPClient } from '@semanticvoxelprotocol/sdk';
const svp = new SVPClient({
endpoint: 'http://localhost:8080',
project: 'my-project'
});
// 获取上下文快照
const context = await svp.getContext({
query: '实现用户登录功能',
lod: 4,
maxTokens: 8000
});
// AI使用上下文进行推理
const response = await ai.complete({
context: context.codeContext,
prompt: '基于以上代码，实现用户登录功能'
});# 挂载SVP虚拟文件系统
svp mount --project my-project --lod 4 /mnt/svp
# AI可以像访问普通文件一样访问
ls /mnt/svp/auth/
# login.ts register.ts token.ts
cat /mnt/svp/auth/login.ts
# (LOD-4级别的代码，只显示接口定义)这是SVP将AI的理解单向同步给IDE/用户的机制。
interface ReverseSyncChannel {
// AI的关注点高亮
highlight: {
// AI正在查看哪些体素
activeVoxels: VoxelRef[];
// AI建议修改的体素
suggestedChanges: {
voxel: VoxelRef;
change: CodeChange;
confidence: number;
}[];
};
// 架构图更新
architectureView: {
// AI识别出的模块边界
detectedModules: ModuleBoundary[];
// AI建议的架构调整
proposedRefactoring: ArchitectureChange[];
};
// 上下文面板
contextPanel: {
// AI当前使用的上下文摘要
activeContext: string;
// AI请求但缺失的上下文
missingContext: string[];
// Token使用情况
tokenUsage: {
used: number;
total: number;
breakdown: Record<string, number>;
};
};
// 单向流（AI → IDE，不可编辑）
syncDirection: 'ai-to-ide-only';
}工作流程：
- AI在体素空间中导航，SVP记录其轨迹
- AI建议修改某个体素，SVP高亮显示在IDE中
- AI识别出新的模块边界，SVP更新架构图
- AI缺少某些上下文，SVP在面板中提示用户
- 关键：用户只能查看，不能直接编辑AI的理解
┌─────────────────────────────────────────────────────────────────────────────┐
│ 完整数据流 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: 摄取 (Ingest) │
│ ═══════════════════════ │
│ │
│ 源码文件 ──┬──▶ Tree-sitter ──▶ AST ──┐ │
│ Git历史 ───┤ │ │
│ LSP符号 ───┤ ├──▶ 体素化引擎 ──▶ 语义体素空间 │
│ │ │ │
│ .svp/ ───▶ 配置解析器 ──▶ 配置 ───┤ │
│ docs/ ───▶ 文档解析器 ──▶ 文档 ───┤ │
│ assets/ ───▶ 图像识别 ──▶ 截图 ───┘ │
│ │
│ Phase 2: 体素化 (Voxelize) │
│ ═══════════════════════════ │
│ │
│ 语义体素 ──▶ 八叉树索引 ──▶ 关系图谱 ──▶ LOD预计算 ──▶ 体素数据库 │
│ │
│ Phase 3: 查询 (Query) │
│ ═════════════════════ │
│ │
│ 用户Query ──▶ 意图分析 ──▶ 体素搜索 ──▶ LOD选择 ──▶ 上下文组装 │
│ │
│ Phase 4: 暴露 (Expose) │
│ ═══════════════════════ │
│ │
│ 上下文Snapshot ──▶ MCP/HTTP/gRPC ──▶ AI Agent │
│ │
│ Phase 5: 反向同步 (Reverse Sync) │
│ ═════════════════════════════════ │
│ │
│ AI导航轨迹 ──┐ │
│ AI修改建议 ──┼──▶ SVP引擎 ──▶ IDE UI更新（高亮/架构图/面板） │
│ AI缺失上下文─┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
# SVP 项目配置
project:
name: "my-awesome-project"
language: "typescript"
description: "A user authentication service"
# 源码配置
source:
root: "./src"
include:
- "src/**/*"
- "lib/**/*"
exclude:
- "node_modules"
- "dist"
- "**/*.test.ts"
git:
enabled: true
maxHistoryDepth: 100
# 外部上下文配置
context:
designDocs:
- path: "docs/architecture.md"
description: "System architecture overview"
- path: "docs/auth-flow.md"
description: "Authentication flow design"
envVars:
- path: ".env.example"
description: "Environment variables template"
- path: ".env.production"
description: "Production environment (sensitive)"
sensitive: true # 标记为敏感，AI可见但不可泄露
screenshots:
- path: "assets/architecture.png"
description: "High-level architecture diagram"
relatedTo: ["src/auth", "src/user"]
apiSpecs:
- path: "openapi.yaml"
description: "OpenAPI specification"
# LOD配置
lod:
defaultLevel: 4 # 默认LOD级别
# 特定路径的LOD覆盖
overrides:
- path: "src/auth/core/**"
level: 2 # 核心认证逻辑，显示更多细节
- path: "src/utils/**"
level: 5 # 工具函数，只显示接口
# 暴露配置
exposure:
# 虚拟文件夹映射
virtualFolders:
"/auth":
physicalPaths: ["src/auth/**"]
description: "Authentication module"
"/user":
physicalPaths: ["src/user/**"]
description: "User management module"
# 敏感路径（AI不可访问）
restrictedPaths:
- "src/secrets/**"
- ".env.production"
- "**/password.ts"
# Token预算
tokenBudget:
default: 8000
max: 32000
# 同步配置
sync:
# 反向同步到IDE
reverseSync:
enabled: true
highlightActiveVoxels: true
showArchitectureUpdates: true
displayTokenUsage: true
# 实时同步
realtime:
enabled: true
debounceMs: 500用户: "实现用户注册功能，需要邮箱验证"
SVP处理:
1. 分析query，识别关键实体："用户注册"、"邮箱验证"
2. 在体素空间搜索相关体素：
- /auth/register (LOD-4: 接口定义)
- /auth/email (LOD-3: 邮件发送逻辑)
- /user/create (LOD-4: 用户创建接口)
3. 加载相关设计文档：docs/auth-flow.md
4. 加载环境变量：SMTP配置
5. 组装ContextSnapshot (Token: 6500/8000)
6. 暴露给AI
AI响应:
- 基于上下文生成注册逻辑
- 请求访问 /email/template (缺失上下文)
SVP反向同步:
- 在IDE中高亮AI查看的代码路径
- 在架构图中标记新的"邮箱服务"模块
- 在面板显示"AI请求访问: /email/template"
用户: "审查这个PR的安全性"
SVP处理:
1. 获取PR变更的体素
2. 切换到LOD-2（实现细节）进行安全分析
3. 加载安全设计文档：docs/security-guidelines.md
4. 标记敏感路径：src/auth/core/**
5. 暴露给AI安全审查Agent
AI响应:
- 发现潜在SQL注入风险
- 建议在src/auth/login.ts添加参数化查询
SVP反向同步:
- 在IDE中高亮风险代码行
- 显示安全审查报告面板
- 标记需要人工确认的安全边界
用户: "解释这个项目的架构"
SVP处理:
1. 切换到LOD-5（架构意图）
2. 加载架构文档和截图
3. 生成架构级体素视图
4. 暴露给AI
AI响应:
- 生成架构概述
- 解释模块间依赖关系
- 建议学习路径
SVP反向同步:
- 在3D视图中展示架构层次
- 标记关键模块和边界
- 显示学习进度追踪
┌─────────────────────────────────────────────────────────────────┐
│ 安全边界 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 原始代码库（完整访问） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 所有源码文件 │ │
│ │ • 敏感配置（.env.production） │ │
│ │ • 密钥和凭证 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ SVP引擎（配置控制） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 根据.svp/config.yaml过滤 │ │
│ │ • 敏感路径排除 │ │
│ │ • LOD裁剪（隐藏实现细节） │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 暴露给AI的视图（受限访问） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • LOD处理后的代码 │ │
│ │ • 非敏感环境变量 │ │
│ │ • 设计文档（人工审核过） │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 【单向隔离】AI永远无法直接访问原始代码库 │
│ │
└─────────────────────────────────────────────────────────────────┘
interface AuditLog {
timestamp: Date;
aiAgentId: string;
operation: 'read' | 'query' | 'navigate';
target: VoxelRef | string;
lod: LODLevel;
tokenUsage: number;
// 敏感操作记录
sensitive: boolean;
}SVP的核心价值：
- 智能上下文网关：自动决定暴露什么给AI
- LOD动态管理：根据任务调整信息粒度
- 人类配置融合：将设计意图、文档、截图纳入上下文
- 双向隔离：AI通过SVP访问代码，用户通过IDE查看AI的理解
- 虚拟沙箱：AI在受限的虚拟文件系统中工作
SVP不是简单的"代码搜索工具"，而是一个**"AI-人类协作的认知基础设施"**。