idxoid/surgical_context

# Surgical Context **Surgical Context 是一个本地优先、与模型无关的上下文引擎**，用于代码理解和变更影响分析 —— 这是一个基于 FastAPI 的 context_engine，运行在本地 Neo4j 图数据库、LanceDB 向量和 SQLite 历史记录之上，提供 `Ask / Inspect / Impact` 检索 API。`extension/` 下的 VS Code 扩展是该 API 的一个前端，而不是产品本身。 本仓库包含以引擎优先开发路线的当前产品和技术文档。 ## 快速导航 ### **了解系统** - **[architectura.md](docs/architectura.md)** — 各个部分如何协同工作（从这里开始） - **[DOCS_STYLE_GUIDE.md](docs/DOCS_STYLE_GUIDE.md)** — 文档类型（Spec / Architecture / Concept / Design draft） - **[concept.md](docs/concept.md)** — 简明产品标识（指针文档） - **[idea_summary.md](docs/idea_summary.md)** — 单屏推介摘要（指针文档） ### **实现指南** **本地开发：** - **[local_development.md](docs/local_development.md)** — 本地设置、引导、context_engine 和扩展开发宿主 **代码索引：** - **[spec_indexer.md](docs/spec_indexer.md)** — 代码提取、调用类型确定、AFFECTS 重构 - **[spec_parser.md](docs/spec_parser.md)** — 语言适配器、符号提取 - **[role_catalog.md](docs/role_catalog.md)** — 结构角色词汇表（Pass 1） - **[role_predicates.md](docs/role_predicates.md)** — L1/L2 断言规则 (`role_cascade.py`) - **[role_clustering_architecture.md](docs/role_clustering_architecture.md)** — Pass-1 设计决策 **文档索引：** - **[spec_doc_indexer.md](docs/spec_doc_indexer.md)** — 分块、嵌入、DocAnchor 链接 - **[spec_doc_anchor.md](docs/spec_doc_anchor.md)** — FROM/COVERS 关系 **上下文组装：** - **[architectura.md](docs/architectura.md)** — 当前的端到端架构和检索流程 - **[axis_terminology.md](docs/axis_terminology.md)** — 轴检索（axis retrieval）、角色和遍历层的词汇表 - **[file_tier_signal.md](docs/file_tier_signal.md)** — 用于种子检索的结构化文件层级降级/提升 - **[walker_consolidation_plan.md](docs/walker_consolidation_plan.md)** — 轴图遍历统一（已实现） - **[spec_prompt_contract_observability.md](docs/spec_prompt_contract_observability.md)** — prompt contract 字段、trace metadata 和可观测性 **API 与基础设施：** - **[spec_sidecar_api.md](docs/spec_sidecar_api.md)** — FastAPI endpoints - **[mcp_server/README.md](mcp_server/README.md)** — 用于 LLM 聊天宿主的 MCP stdio server - **[spec_storage.md](docs/spec_storage.md)** — 当前的 Neo4j/LanceDB/SQLite 存储行为 - **[spec_storage_connectors.md](docs/spec_storage_connectors.md)** — 计划中的 Graph/Vector/History 提供者连接器层 - **[spec_language_adapter.md](docs/spec_language_adapter.md)** — 插件架构 (ADR-005) - **[spec_overlay.md](docs/spec_overlay.md)** — 内存中的脏状态（dirty state） - **[spec_tenant_api_graph.md](docs/spec_tenant_api_graph.md)** — 未来的 Team/Enterprise 租户级 API contract 图谱 **进阶主题：** - **[spec_eval_harness.md](docs/spec_eval_harness.md)** — 轴基准测试工具（axis benchmark harness）、问题包和 CI 门控 - **[question_structural_role_profiles.md](docs/question_structural_role_profiles.md)** — 黄金标准问题结构概况（设计草案） - **[logical_roles_structural_closure.md](docs/logical_roles_structural_closure.md)** — 逻辑角色与结构闭包值 - **[spec_embedding_versioning.md](docs/spec_embedding_versioning.md)** — 管理 embedding 模型版本 - **[spec_affects_index.md](docs/spec_affects_index.md)** — 反向依赖索引 ### **规划与审查** - **[road_map.md](docs/road_map.md)** — 阶段和时间表 ## 当前事实 此分支的目标是**本地、单租户配置**：引擎及其 VS Code 前端完全在单个开发者的机器上运行 —— 本地 Neo4j 图、本地 LanceDB 向量、本地 SQLite 历史记录，以及本地优先的 LLM 默认设置。访问接口是可互换的：同一个 context_engine API 可以为 VS Code 扩展、编程式/CLI 客户端以及 QA/基准测试工具提供服务。此配置是开源候选版本。 范围被刻意缩小：代码理解和变更影响分析 —— **而**不是通用的 AI 编码平台或多租户服务。 本仓库以引擎优先的方式组织：context_engine、默认 Neo4j/LanceDB 客户端、parser/indexer/axis 检索模块、结构角色检索、prompt-context 适配器、测试、QA 基准测试工具、指标、反馈遥测、持久化索引作业和有界索引队列构成了引擎；`extension/` 下的 VS Code 扩展是基于 context_engine API 的一个前端。 近期的强化工作增加了基于请求的 Neo4j 客户端视图（位于一个共享驱动程序之上）、类型化的 API 响应、JSON 安全的 SSE 框架、稳定的 UID v2、作用域调用解析、工作区作用域图查询、感知配置文件的索引命名空间、Git 增量失效助手、统一搜索、检索缓存、反馈令牌、context_engine API 的 endpoint 覆盖率，以及有界/合并的增量索引队列。当前活跃的 axis 路径现在包含结构角色检索、代码内的 docstring/JSDoc 锚点种子、邻接关系物化，以及用于分数、来源、剪枝、路由和 trace metadata 的 prompt-contract schema 字段。它还强制执行**工作区路径沙箱化**（调用者路径位于已索引的 `project_path` 下）、**有界的 API 限制**（`limit` 1–50，`token_budget` 400–32k），以及**本地优先的 LLM** 默认设置（`ALLOW_CLOUD_LLM=false`，默认 Anthropic 模型为 `claude-sonnet-4-6`）。请参阅 [spec_sidecar_api.md](docs/spec_sidecar_api.md) 和 [road_map.md](docs/road_map.md)。 本地设置和冒烟测试路径位于 **[local_development.md](docs/local_development.md)** 和 `scripts/local_dev.py` 中。基准测试包含了跨 Python 和 TypeScript/JavaScript 的 13 个仓库的工作区映射，包括内部测试（dogfood）仓库；运行这些测试仍然需要预先对这些工作区进行索引。目前最重要的未解决问题在引擎侧：提升困难的真实仓库案例的召回率，改善在宽泛/文档密集型路径上的精确度，校准 DocAnchor 的置信度/类型，并将更丰富的 axis 排序/剪枝/文档证据带入活跃的 `PromptContext` 中，而不是将序列化字段保留为默认值。VS Code 前端仍然需要请求选择的持久化和无障碍优化，但与引擎工作相比这是次要的。租户级 API 图谱发布/链接、备用数据库连接器、LLM 代理网关、RBAC 和服务拆分仍然是未来 Team/Enterprise 的规划方向。请参阅 **[road_map.md](docs/road_map.md)** 获取标准的待办事项。 **相关实验（外部仓库，非子模块）：** [context-deduplicator](https://github.com/idxoid/context-deduplicator) 和 [marginal-utility-selector](https://github.com/idxoid/marginal-utility-selector) 是早期的独立原型。生产环境的检索逻辑现在位于 `context_engine/axis/` 中，共享的 prompt contract 位于 `context_engine/context_types.py`。 ## MCP Server `mcp_server/` 包通过 Model Context Protocol (MCP) stdio transport 为 Claude Code、Codex、Cursor 和 Claude Desktop 等聊天宿主公开了 Surgical Context 的检索功能。它是 `context_engine.axis.pipeline.run_axis_retrieval` 的进程内适配器，因此 MCP 调用使用与 `/ask/axis` 和 `QA/axis_benchmark` 工具相同的 axis 读取路径。 服务器返回的是**上下文，而不是最终答案**：宿主 LLM 请求代码或影响数据，接收经过排序和图扩展的上下文，并自行根据该上下文进行推理。主要工具包括： | 工具 | 用途 | |---|---| | `ask_code` | 自然语言问题 → 排序后的代码包。 | | `impact` | 符号变更的下游波及范围（blast radius）。 | | `list_workspaces`, `list_files` | 发现已索引的仓库和文件。 | | `find_definition`, `file_outline`, `read_symbol` | 精确定位/读取/导航的原语。 | | `callers`, `callees`, `path` | 跨调用和其他耦合边的图导航。 | | `set_overlay`, `clear_overlay` | 检查未提交的缓冲区更改，而无需写入索引。 | | `batch` | 在一次 MCP 往返中运行多个读取/导航操作。 | 前置条件与本地引擎路径相同：必须可用 Neo4j 和 LanceDB，并且目标仓库必须在 `axis_python_v1` 下进行索引。 内部测试（dogfood）工作区是 `qa_repo/surgical_context@main`；MCP 配置通过 `SURGICAL_CONTEXT_WORKSPACE` 传递该基础 ID，服务器会自动附加 `+axis_python_v1` 后缀。 请参阅 **[mcp_server/README.md](mcp_server/README.md)** 获取安装命令、Claude Code/Codex 连接方式、冒烟测试和当前限制。 ## 编写文档 在编写或更新文档之前，请阅读 **[DOCS_STYLE_GUIDE.md](docs/DOCS_STYLE_GUIDE.md)**。 快速规则： - **清晰明了** — 在 2 分钟或更短的时间内解释清楚 - **展示示例** — 可直接复制粘贴的代码 - **使用表格** 展示数据结构 - **链接所有内容** — 指向相关规范的内部链接 - **列出限制** — 目前无法使用的功能 - **添加权衡** — 为什么选择此设计而非其他替代方案 ## 文档状态说明 - ✅ **已实现** — 已合并到此分支中，并由测试/基准测试覆盖 - 🚧 **进行中** — 正在积极开发 - 📋 **已计划** — 已列入路线图，尚未开始 - ⚠️ **已知问题** — 可以工作，但有注意事项 - ❌ **未实现** — 已推迟 - 🔄 **重构中** — 正在进行重新设计（新路径可能会暂时共存） 请在规范文档的主要章节和算法块中直接使用这些标记。 ## 文档如何保持同步 每个 pull request 都应包含文档更新： - **新功能？** 添加 Spec 或更新 Concept - **设计更改？** 更新 architectura.md 和受影响的 Specs - **Bug 修复？** 如果是已知约束，请将其添加到 Limitations 中 - **阶段完成？** 更新 road_map.md 过时的文档比没有文档更糟糕 —— 如有疑问，请在代码审查中提出。 ## 有疑问？ - 关于架构 → 请在 [architectura.md](docs/architectura.md) 中提问 - 关于组件 → 找到对应的 `spec_*.md` - 关于如何贡献 → 阅读 [DOCS_STYLE_GUIDE.md](docs/DOCS_STYLE_GUIDE.md)

标签：LanceDB, Neo4j, RAG检索增强生成, SOC Prime, 上下文引擎, 代码理解, 变更影响分析, 开发工具, 数据可视化, 逆向工具