obs-code

给 AI 装上代码地图，从「瞎改」变成「手术刀」

AI 改代码最大的问题不是写不好——而是不知道改哪里、改了会牵连什么。
obs-code 为你的代码库建立知识图谱，让 AI 在动手之前先知道全貌。

---

真实痛点

你让 AI 修一个登录 bug。它扫了 200 个文件，上下文爆了，最后改了 handleLogin——但完全不知道 authRouter 也调了它。上线，炸了。

这不是 AI 不够聪明，是它没有地图。

---

装上 obs-code 之后

你：修复用户登录的 bug

AI（接入 obs-code）：
  ① obs_plan("修复用户登录") → 精准定位 5 个相关文件
  ② obs_impact("handleLogin") → 发现 3 个调用方、2 个被调用方
  ③ 只读这 5 个文件，全部看懂
  ④ 改完，不漏，安全上线 🚀

耗时：2 分钟   遗漏率：极低   上下文消耗：-80%

❌ 没有 obs-code 需求 → 读 200 个文件 → 上下文爆 → 凭感觉猜 → 改了 A，B 炸了 💥 正确率：40-60% 遗漏率：高 耗时：30 min+

✅ 有 obs-code 需求 → obs_plan → 精准文件清单 → obs_impact → 知道牵连 → 只读相关文件 → 改对，不漏 🚀 正确率：85-95% 遗漏率：极低 耗时：2 min

---

30 秒上手

# 一键安装
curl -fsSL https://raw.githubusercontent.com/xiaoletian64/obs-code/main/install.sh | bash

# 接入你的 AI 工具
obs install --tool claude    # Claude Code
obs install --tool cursor    # Cursor
obs install --tool codex     # OpenAI Codex
obs install --tool opencode  # OpenCode
obs install --tool all       # 全部接入

# 建图（首次）
obs index /你的项目路径

# 用起来
# 在 AI 对话框直接说：用 obs 分析一下用户登录流程

---

核心工具（30 个 MCP 工具）

场景	工具	一句话
我要改 X	obs_plan	自然语言 → 精准文件清单 + 绝对路径
改 X 安不安全	obs_impact	BFS 遍历调用图，列出所有牵连方
X 在哪里	obs_find	5 级降级搜索，精确→模糊→中文→多维
理解 X 功能	obs_feature_map	功能 → 分阶段阅读链路
快速摸清项目	obs_thread	入口 → 路由 → 目标，比全量索引快 10×
项目有哪些接口	obs_routes	HTTP 路由表 + 调用链
清理死代码	obs_deadcode	零调用函数一览
30秒看懂项目	llm_wiki_generator	自动生成 project/arch/connections.md
识别业务域	obs_domain	业务域 + 流程 + 步骤
引导式学习	obs_tour	按依赖顺序逐步了解架构
语义搜索	obs_semantic_search	按意图搜，不只是关键词
评估变更风险	obs_diff	变更影响 + 风险等级预测
架构分层图	obs_layers	自动分层 + 层间连接分析
解释编程模式	obs_concepts	12 种常见模式，结合上下文解释

---

知识图谱长什么样

.obs-code/wiki/
├── AGENTS.md          ←  AI 首先读这个：什么时候用哪个工具
├── project.md         ←  项目概览：语言、规模、关键文件
├── architecture.md    ←  架构：分层、模式、入口点
├── connections.md     ←  热点：Hub 函数 / 跨层 Bridge / 主调用链
└── manifest.json      ←  元数据：索引时间、扫描范围

connections.md 自动识别调用热点：

## Hubs（高扇入 — 改这里影响最大）
  exec          ← 被 30 处调用
  parse         ← 被 20 处调用
  searchByName  ← 被 11 处调用

## Bridges（跨层调用 — 集成测试重点）
  feature-map → store    88 次调用
  graph-sync  → store    12 次调用

## Main Paths（主调用链）
  buildFeatureMap → readCandidates → getById → rowToNode

---

性能

项目	规模	节点	边	索引速度
Express	简单	376	6	15 f/s
Axios	中等	636	1,224	267 f/s
NestJS	复杂	5,977	11,580	244 f/s
Vitest	大型	10,054	6,143	33 f/s

• 增量更新：文件监听（chokidar），改一个文件只重解析一个文件
• SQLite WAL + FTS5：搜索延迟 < 10ms
• 异步索引：obs_index 立即返回 taskId，后台建图，不阻塞 AI 对话

---

架构

┌──────────────────────────────────────────────────┐
│           AI 工具层（MCP 协议）                   │
│   Claude Code · Cursor · Codex · OpenCode        │
├──────────────────────────────────────────────────┤
│  obs_find  obs_impact  obs_plan  obs_feature_map  │
│  obs_thread  obs_routes  obs_deadcode  +22 more   │
│          ↕ 多策略搜索链（5 级降级）               │
│    精确 → 模糊 → FTS5 → 中文同义词 → 多维组合    │
├──────────────────────────────────────────────────┤
│           图谱引擎 + BFS 影响传播                 │
├──────────────────────────────────────────────────┤
│           SQLite（WAL + FTS5）                    │
│      nodes · edges · nodes_fts · file_hashes     │
├──────────────────────────────────────────────────┤
│           解析层（Tree-sitter + 增强正则）         │
│   15 种语言 · 文件监听 · 增量重解析               │
└──────────────────────────────────────────────────┘

---

支持语言

TypeScript · JavaScript · Python · Go · Rust · Java · Swift · Kotlin · PHP · Ruby · C# · Dart · C/C++ · Lua · 以及更多

---

Web 可视化

obs web /你的项目路径
# 打开 http://localhost:3456

力导向图谱动画 · 节点 hover 高亮 · 点击聚焦 · AI 解释面板 · 索引证据面板（扫描范围、跳过目录）

---

让 AI 改代码从「盲人摸象」变成「精准手术」