给 AI 装上代码地图，从「瞎改」变成「手术刀」
AI 改代码最大的问题不是写不好——而是不知道改哪里、改了会牵连什么。
obs-code 为代码库建立知识图谱，让 AI 在动手之前先看清全貌，
并把「理解 → 定位 → 影响分析 → 规划 → 改动 → 验证」串成一个可自动运行的闭环。
obs-code 不是简单的代码搜索工具，它构建了一个完整的代码知识图谱：
源代码 → tree-sitter 解析 → 符号节点 + 调用边 → SQLite 存储 → MCP 协议暴露
技术栈：
- tree-sitter：增量解析 15 种语言，支持增量更新
- SQLite + FTS5：高性能存储和全文搜索
- MCP 协议：标准化的 AI 工具接口
- chokidar：文件监听，自动增量索引
obs-code 生成的 wiki 完全兼容 Obsidian：
---
tags: [obs-code, feature, payment]
created: 2026-06-24
source: obs-code
project: MyProject
---
# 支付模块（Payment）
> 📄 `src/services/payment/PaymentService.java`
## 大白话
处理支付请求，对接第三方支付网关
## 启动时间轴
```mermaid
stateDiagram-v2
[*] --> 待支付
待支付 --> 支付中 : 发起支付
支付中 --> 已完成 : 支付成功
支付中 --> 已失败 : 支付失败- [[PaymentGateway]] — 支付网关
- [[OrderService]] — 订单服务
**特性**：
- YAML frontmatter（标签、元数据）
- `[[wikilink]]` 双链导航
- Mermaid 图表（状态机、流程图、消息传递图）
- 大白话描述（纯规则引擎，0 token 消耗）
### 3. 三层符号组织
文件级页面（~302） ├── 类级页面（~92） │ ├── 方法列表（内联展示） │ └── ... └── Hub 方法页面（~30，被调用 5+ 次）
**从 1115 → 124 页，每页更有意义**。
### 4. 自动刷新机制
代码修改 → watcher 检测 → 2s 防抖 → 增量索引 → full 模式刷新 wiki ↓ Obsidian 自动更新
**用户只需修改代码，wiki 自动保持最新**。
---
## 真实痛点
> 你让 AI 修一个登录 bug。它扫了 200 个文件，上下文爆了，最后改了 `handleLogin`——但完全不知道 `authRouter` 也调了它。上线，炸了。
**这不是 AI 不够聪明，是它没有地图。**
---
## 开发全流程闭环
obs-code 不只是「查代码」的工具，它覆盖一次代码改动的**完整生命周期**——每一环都有对应工具，且能首尾相接自动运行：
┌──────────────────────────────────────────────────────┐
│ │
① 理解项目 ② 定位需求 ③ 影响分析 │ obs_feature_map obs_find obs_impact │ obs_chat obs_plan obs_scope_change │ llm_wiki_generator obs_sg trace │ │ │ │ ▼ ▼ │ ⑨ 自进化 ◀─── ⑧ 知识沉淀 ◀─── ⑦ 验证 ◀─── ④ 生成计划 │ obs_self_* obs_wiki_* obs_validate obs_plan │ llm_wiki_gen obs_diff obs_analyze obs_deadcode │ │ ▲ ▼ │ └── ⑤⑥ 改动+落地 ──┘ obs_apply_change (写入工作区 → 测试门禁 → 通过提交/失败回滚)
| 阶段 | 工具 | 说明 |
|------|------|------|
| ① 理解项目 | `obs_feature_map` `obs_chat` `obs_analyze` `llm_wiki_generator` `obs_business` | 陌生项目 30 秒摸清架构、入口、分层 |
| ② 定位需求代码 | `obs_find` `obs_plan` `obs_sg` `obs_routes` | 自然语言 → 精准文件清单 |
| ③ 改前影响分析 | `obs_impact` `obs_scope_change` `trace` | BFS 遍历调用图，列出所有牵连方 |
| ④ 生成改动计划 | `obs_plan` `obs_analyze` | 需求 → files_to_read + 符号范围 |
| ⑤⑥ 改动 + 安全落地 | **`obs_apply_change`** | 写入工作区 → git 分支隔离 → 测试门禁 → 通过提交 / 失败 `reset --hard` 回滚 |
| ⑦ 改后验证 | `obs_validate` `obs_diff` `obs_deadcode` `obs_status` | 图完整性 + 变更扩散 + 死代码检查 |
| ⑧ 知识沉淀 | `obs_wiki_*`（8 个）`llm_wiki_generator` | 把理解写回 wiki，下次直接用 |
| ⑨ 自进化 | `obs_self_audit/improve/apply/execute/...` | obs 自己审计、改进、安全落地 |
**两种闭环用法：**
- **配对闭环（推荐）**：obs 负责①②③④⑦⑧（眼睛+大脑），Claude Code 等 agent 负责⑤⑥执行（手）。最灵活、最安全。
- **自动闭环**：`obs_apply_change` 直接在安全闸内应用改动并验证——`obs_plan` 出计划 → `obs_apply_change` 落地（默认 dry-run，`apply=true` 才执行，测试不过自动回滚），无需外部 agent。
---
## 装上 obs-code 之后
你：修复订单状态同步的 bug
AI（接入 obs-code）： ① obs_plan("修复订单状态同步") → 精准定位 5 个相关文件 + 符号范围 ② obs_impact("syncOrderStatus") → 发现 3 个调用方、2 个被调用方 ③ 只读这 5 个文件，全部看懂 ④ obs_apply_change(...) → 改动写入隔离分支 → 跑测试门禁 → ✅ 通过提交 ⑤ obs_diff → 确认无意外扩散
耗时：2 分钟 遗漏率：极低 上下文消耗：-80% 失败自动回滚
<table>
<tr>
<td width="50%" valign="top">
### ❌ 没有 obs-code
需求 → 读 200 个文件 → 上下文爆 → 凭感觉猜 → 改了 A，B 炸了 💥
正确率：40-60% 遗漏率：高 耗时：30 min+
</td>
<td width="50%" valign="top">
### ✅ 有 obs-code
需求 → obs_plan 精准定位 → obs_impact 看清牵连 → 只读相关文件 → obs_apply_change 落地+回滚
正确率：高 遗漏率：极低 耗时：2 min
</td>
</tr>
</table>
---
## 30 秒上手
```bash
# 一键安装
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 zed # Zed Editor
obs install --tool all # 全部接入
# 建图（首次）
obs index /你的/项目路径
# 用起来：在 AI 对话框直接说
# 「用 obs 分析一下用户登录流程」
# 「用 obs_plan 规划这个需求，然后 obs_apply_change 落地」
# 一键用 Obsidian 打开 wiki
obs open /你的/项目路径
| 场景 | 工具 | 一句话 |
|---|---|---|
| 我要改 X | obs_plan |
自然语言 → 精准文件清单 + 绝对路径 |
| 改 X 安不安全 | obs_impact |
BFS 遍历调用图，列出所有牵连方（支持分页） |
| X 在哪里 | obs_find |
搜索符号，支持中文、模糊匹配 |
| 理解 X 功能 | obs_feature_map |
功能 → 分阶段阅读链路（支持 precision_mode 精准过滤） |
| 大 monorepo 里找功能 | obs_feature_map + path_prefix |
多子项目仓库（如 RobotPackages）传 path_prefix="OverSea_Meal" 收敛到单个子项目；或在 feature 写明子项目名自动识别；调用链证据加权提升精度 |
| 项目有哪些接口 | obs_routes |
HTTP 路由表 + 调用链 |
| 清理死代码 | obs_deadcode |
零调用函数一览 |
| 30 秒看懂项目 | llm_wiki_generator |
自动生成 project/arch/connections.md |
| 结构化搜索 | obs_sg |
ast-grep AST 模式匹配，不只是查名字 |
| 图数据库查询 | obs_cypher_query |
Cypher 语法查询代码图谱 |
| 场景 | 工具 | 一句话 |
|---|---|---|
| 安全地改代码 | obs_apply_change |
接收编辑指令 → 写入工作区 → git 分支隔离 + 测试门禁 + 失败自动回滚 |
默认 dry-run 只校验；
apply=true才真正执行。测试通过 → 提交到隔离分支等待人工合并；测试失败 →git reset --hard回滚，工作区恢复基线。
| 工具 | 一句话 |
|---|---|
obs_wiki_create |
创建文档页面，支持 [[wikilinks]] 交叉引用 |
obs_wiki_edit / obs_wiki_append |
查找替换编辑 / 追加内容 |
obs_wiki_read / obs_wiki_search / obs_wiki_list |
读取 / 搜索 / 列出页面 |
obs_wiki_delete |
删除页面（系统文件受保护） |
obs_wiki_lint |
检查悬空链接、孤立页面 |
| 工具 | 一句话 |
|---|---|
obs_chat |
自然语言问答：搜索相关符号 + 1-hop 邻居 |
obs_analyze |
一键全量分析：统计 + 核心 API + 入口 + 架构分层 |
obs_business |
代码 → 业务流程描述 + 术语映射 |
| 工具 | 一句话 |
|---|---|
obs_self_audit |
图健康检查 + deadcode 分级 |
obs_self_improve |
根据审计生成可执行改进计划 |
obs_self_apply |
安全闸：git 分支隔离 + 测试门禁 + 自动回滚 |
obs_self_execute |
受限执行低风险产物写入 |
.obs-code/wiki/
├── AGENTS.md ← AI 首先读这个：什么时候用哪个工具
├── project.md ← 项目概览：语言、规模、关键文件
├── architecture.md ← 架构：分层、模式、入口点
├── connections.md ← 热点：Hub 函数 / 跨层 Bridge / 主调用链
├── features/ ← 功能页面（带状态机、流程图、消息传递图）
│ ├── 支付模块.md
│ ├── 订单服务.md
│ └── ...
├── symbols/ ← 符号页面（文件级 + 类级 + Hub 方法）
│ ├── PaymentGateway.md
│ ├── PaymentGateway.process.md
│ └── ...
├── terms.md ← 学习到的中英术语映射（自动从代码注释学习）
└── manifest.json ← 元数据：索引时间、扫描范围
connections.md 自动识别调用热点：
## Hubs（高扇入 — 改这里影响最大）
exec ← 被 54 处调用
parse ← 被 32 处调用
## Bridges（跨层调用 — 集成测试重点）
controller → data 192 次调用
## Main Paths（主调用链）
buildFeatureMap → readCandidates → getById → rowToNode
中文搜索零配置： 索引时自动从代码注释/变量名学习中英术语映射，直接用中文描述需求即可。
你：修改桌号显示逻辑
AI：obs_plan("修改桌号显示") → 自动找到 TableNum 相关文件
| 项目 | 规模 | 节点 | 边 | 索引速度 |
|---|---|---|---|---|
| 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）+ content-hash(sha256) 校验，改一个文件只重解析一个
- SQLite WAL + FTS5：搜索延迟 < 10ms
- 异步索引：
obs_index立即返回 taskId，后台建图，不阻塞 AI 对话 - Token 零消耗：wiki 生成和大白话描述都是纯本地规则引擎，不调用 AI
- 650+ 本地词典：覆盖动词、状态词、业务词、技术词、编译器术语，纯本地拼接翻译
TypeScript · JavaScript · Python · Java · Go · Rust · C/C++ · Swift · Kotlin · PHP · Ruby · C# · Dart · Lua 等 15 种语言（tree-sitter 解析）。
obs-code 一次安装可接入 Claude Code、Cursor、Codex、OpenCode、Zed、Windsurf、Cline、Roo Code、Gemini CLI、MiMo Code、ZCode 等，配置自动写入各自的 MCP 设置文件，模型选择不影响图谱功能。
@software{obs-code2026,
title={obs-code: Code Knowledge Graph for AI-Assisted Software Engineering},
author={obs-code contributors},
year={2026},
url={https://github.com/xiaoletian64/obs-code},
version={3.0.1}
}- 代码知识图谱构建：基于 tree-sitter 的增量解析 + SQLite 图存储 + MCP 协议暴露
- Obsidian 原生集成：YAML frontmatter + wikilink 双链 + Mermaid 图表 + 大白话描述（650+ 本地词典）
- 三层符号组织：文件级 → 类级 → Hub 方法，按需展开
- 自动刷新机制：watcher 检测 → 增量索引 → full 模式刷新 wiki
- 安全代码执行：git 分支隔离 + 测试门禁 + 失败自动回滚
- 自进化能力：obs 自己审计、改进、安全落地
obs-code = 代码库的「眼睛 + 大脑」，让动手改代码的那个 AI 先有地图再下刀。
MIT License