Houseofmvps/codesight
GitHub: Houseofmvps/codesight
一个零依赖的 AI 上下文生成器，通过 AST 与正则解析代码并生成持久化知识库，显著减少 AI 交互中的令牌消耗。
Stars: 890 | Forks: 87
### 你的 AI 助手每次对话浪费数千个令牌来理解你的项目，codesight 一条命令解决此问题。
**4000+ 下载并持续增长。**
**零依赖。 AST 精准。 30+ 框架检测器。 13 个 ORM 解析器。 13 个 MCP 工具。一个 `npx` 调用。**
**支持 TypeScript、JavaScript、Python、Go、Ruby、Elixir、Java、Kotlin、Rust、PHP、Dart、Swift 和 C#。** TypeScript 项目获得完整的 AST 精准度；其他项目均使用经过验证的 regex 检测，覆盖相同的 30+ 框架。
[](https://www.npmjs.com/package/codesight)
[](https://www.npmjs.com/package/codesight)
[](https://www.npmjs.com/package/codesight)
[](https://github.com/Houseofmvps/codesight/stargazers)
[](LICENSE)
[](https://x.com/kaileskkhumar)
[](https://www.linkedin.com/in/kailesk-khumar)
[](https://houseofmvps.com)
**由 [Kailesk Khumar](https://www.linkedin.com/in/kailesk-khumar) 构建，houseofmvps.com 的单人创始人**
*另外：[ultraship](https://github.com/Houseofmvps/ultraship)（适用于 Claude Code 的 39 项专家技能）· [claude-rank](https://github.com/Houseofmvps/claude-rank)（适用于 Claude Code 的 SEO/GEO/AEO 插件）*
```
0 dependencies · Node.js >= 18 · 27 tests · 13 MCP tools · MIT · tested on 25+ OSS projects across 14 languages
```
## 适用环境
**Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Windsurf、Cline、Aider**，以及任何能读取 Markdown 的工具。
## 安装
```
npx codesight
```
仅此而已。在任意项目根目录运行即可。无需配置、无需设置、无需 API 密钥。
```
npx codesight --wiki # Generate wiki knowledge base (.codesight/wiki/)
npx codesight --init # Generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
npx codesight --open # Open interactive HTML report in browser
npx codesight --mcp # Start as MCP server (13 tools) for Claude Code / Cursor
npx codesight --blast src/lib/db.ts # Show blast radius for a file
npx codesight --profile claude-code # Generate optimized config for a specific AI tool
npx codesight --benchmark # Show detailed token savings breakdown
npx codesight --mode knowledge # Map knowledge base (.md notes → KNOWLEDGE.md)
npx codesight --mode knowledge ~/vault # Map Obsidian vault, ADRs, meeting notes, retros
```
## 维基知识库（v1.6.2）
灵感来自 [Karpathy 的 LLM 维基模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) —— 但由 AST 编译，而非 LLM。零 API 调用。 200ms。
```
npx codesight --wiki
```
生成 `.codesight/wiki/` —— 一个持久化的代码库知识库，跨会话保持存在：
```
.codesight/wiki/
index.md — catalog of all articles (~200 tokens) — read this at session start
overview.md — architecture, subsystems, high-impact files (~500 tokens)
auth.md — auth routes, middleware, session flow
payments.md — payment routes, webhook handling, billing flow
database.md — all models, fields, relations, high-impact DB files
users.md — user management routes and related models
ui.md — UI components with props
log.md — append-only record of every wiki operation
```
**为何这能进一步减少令牌使用：**
无需每次对话都加载完整的 5K 令牌上下文映射，你的 AI 只需读取一个针对性文章：
| 问题 | 无维基 | 有维基 |
|---|---|---|
| “认证如何工作？” | ~12K 令牌（读取 8+ 个文件） | ~300 令牌（`auth.md`） |
| “存在哪些模型？” | ~5K 令牌（`CODESIGHT.md`） | ~400 令牌（`database.md`） |
| 新会话启动 | ~5K 令牌（完整重载） | ~200 令牌（`index.md`） |
**跨会话持久化。** 维基位于 `.codesight/wiki/` 并提交至 Git。每个新的 Claude Code、Cursor 或 Codex 会话都会从第一条消息开始拥有完整的代码库知识。
**自动再生。** 使用 `--watch` 随时保持维基最新；使用 `--hook` 在每次提交时自动再生。
**3 个新的 MCP 工具用于访问维基：**
| 工具 | 功能 |
|---|---|
| `codesight_get_wiki_index` | 获取维基目录（~200 令牌），会话启动时读取 |
| `codesight_get_wiki_article` | 按名称读取一篇文章：`auth`、`database`、`payments` 等 |
| `codesight_lint_wiki` | 健康检查：孤立文章、缺失交叉链接、陈旧内容 |
与通用维基工具的关键区别：codesight 已通过 AST 知晓你的路由、架构、爆炸半径和中间件 —— 无需 LLM 提取代码结构。维基是建立在数据之上的叙事层，而这些数据本就存在于你的代码库中。
## 知识模式（v1.9.3）
不仅是代码 —— 你的决策、会议记录、ADR 和回顾同样承载与代码库一样多的上下文。`--mode knowledge` 以与 codesight 映射代码相同的方式映射它们。
```
npx codesight --mode knowledge # Scan current directory for .md files
npx codesight --mode knowledge ~/vault # Scan an Obsidian vault
npx codesight --mode knowledge ./docs # Scan a project docs folder
```
输出 `.codesight/KNOWLEDGE.md` —— 一个紧凑的 AI 上下文预热文件：
```
# 知识图谱 — my-project
> 47 notes · 12 decisions · 8 open questions · 2025-09-01 → 2026-04-01
## 关键决策 (12)
- [2026-03-20] Going with Polar.sh over Stripe Connect — simpler global payments
- [2026-03-15] Decided to use PostgreSQL — better JSON support and Drizzle compatibility
- [2026-02-10] Will use Redis for rate limiting — BullMQ already in stack
## 待解决的问题 (8)
- Should we support PayPal later?
- When do we start the Stripe marketplace application?
## 笔记索引 (47)
### 决策记录 (8)
- `decisions/adr-002-payments.md` — 2026-03-20 — Going with Polar.sh over Stripe Connect
- `decisions/adr-001-database.md` — 2026-03-15 — We need a relational database...
### 会议笔记 (14)
### 回顾 (6)
### 规格与产品需求文档 (5)
### 研究 (4)
```
**自动检测的内容：**
| 笔记类型 | 信号 |
|---|---|
| 决策记录 | ADR 格式（`## Decision`）、“decided to”、“going with”、“chose X over Y” |
| 会议记录 | `Attendees:`、`Action items:`，文件名：`standup`、`sync`、`1on1` |
| 回顾 | “What went well”、“Stop doing”，文件名：`retro`、`retrospective` |
| 规格 / PRD | `## Goals`、`## Requirements`，文件名：`prd`、`spec`、`roadmap` |
| 研究 | 文件名：`research`、`analysis`、`benchmark`、`comparison` |
| 会话日志 | 文件名：`session`、`daily`、`weekly` |
**支持：**
- Obsidian 仓库（YAML 前置事项、`[[backlinks]]`、`#tags`）
- Notion 导出（带前置事项的 `.md` 文件）
- ADR 工具（`adr-tools`、`Log4brains`、原始 Markdown）
- 任意 Markdown 文件集合
**协同使用：**
```
Read .codesight/CODESIGHT.md → what the code does
Read .codesight/KNOWLEDGE.md → why decisions were made
```
CI：在现有 codesight 步骤旁添加 `npx codesight --mode knowledge`。两个文件在每次推送后保持更新。
## 基准测试（真实项目）
以下每个数字均来自在真实生产代码库上运行 codesight 的结果 —— 涵盖小型 SaaS 项目（v1.6.2）以及拥有 4K–10K+ 文件的大型开源平台（v1.6.4）。输出令牌按实际文件大小（字符 / 4）测量，探索令牌为估算值（路由 × 400、模型 × 300、组件 × 250 等）。路由和模型数量经过源码文件交叉验证。
### 三层令牌减少
codesight 在两个层级上节省令牌。维基（v1.6.2）在基础节省之上增加第二层：
| 项目 | 手动探索 | codesight 扫描 | codesight --wiki（定向） | **总计减少** |
|---|---|---|---|---|
| **SaaS A** | 46,020 令牌 | 3,936 令牌（11.7x） | ~550 令牌 | **83.7x** |
| **SaaS B** | 26,130 令牌 | 3,629 令牌（7.2x） | ~440 令牌 | **59.4x** |
| **SaaS C** | 47,450 令牌 | 4,162 令牌（11.4x） | ~360 令牌 | **131.8x** |
**平均综合减少：91x。** “定向”维基的数值 = 读取 `index.md`（~200 令牌）加上一篇相关文章（~160–350 令牌，视项目而定）。你的 AI 从不加载完整的上下文映射以回答定向问题。
这两层节省相互独立且可叠加：
**第一层 — codesight 扫描** 消除手动文件探索。无需让 AI 运行 glob/grep/read 40–138 个文件来理解项目，它只需读取一个预编译的映射。
**第二层 — `--wiki`** 消除为每个问题加载完整映射。无需在会话启动时加载 K–5K 令牌的全部上下文，而是读取 200 令牌索引并提取每问所需的一篇文章（~160–350 令牌）。
```
Without codesight: AI reads 26K-47K tokens per session exploring files
With codesight: AI reads ~3K-5K tokens (the compiled map)
With --wiki: AI reads ~200 tokens at start + ~300 per targeted question
```
### 基础扫描结果
| 项目 | 技术栈 | 文件数 | 路由数 | 模型数 | 组件数 | 输出令牌 | 探索令牌 | 节省倍数 | 扫描耗时 |
|---|---|---|---|---|---|---|---|---|---|
| **SaaS A** | Hono + Drizzle | 138 | 38 | 12 | 0 | 3,936 | 46,020 | **11.7x** | 186ms |
| **SaaS B** | Hono + Drizzle，3 个工作区 | 53 | 17 | 8 | 10 | 3,629 | 26,130 | **7.2x** | 201ms |
| **SaaS C** | FastAPI + MongoDB | 40 | 56 | 0 | 0 | 4,162 | 47,450 | **11.4x** | 890ms |
SaaS C 拥有 0 个模型，因为它使用 MongoDB —— codesight 正确识别（无需 SQL ORM 声明）。这并非误判。 SaaS C 估算漏掉了 3 条 FastAPI 路由。零误报。
### 多语言开源基准测试（v1.6.7）
针对覆盖所有支持语言与框架的真实开源代码库进行测试。输出令牌基于实际文件大小，探索令牌为估算值（路由 × 400 + 模型 × 300 + 组件 × 250 + 重新访问乘数）。零误报。
| 语言 | 技术栈 | 文件数 | 路由数 | 模型数 | 组件数 | 输出令牌 | 估算探索 | 节省倍数 |
|---|---|---|---|---|---|---|---|---|
| **TypeScript · Next.js** | Next.js + tRPC + Prisma · 110+ 工作区 | 7,509 | 479 | 173 | 1,309 | 158,660 | ~1,485,000 | **~9x** |
| **TypeScript · NestJS** | NestJS + TypeORM + Mongoose | 162 | 19 | 8 | 0 | 5,300 | ~67,500 | **~12.7x** |
| **TypeScript · Hono** | Hono | — | 8 | 0 | 0 | — | — | ✓ |
| **TypeScript · Remix** | Remix + Prisma | 36 | 11 | 0 | 9 | — | — | ✓ |
| **TypeScript · SvelteKit** | SvelteKit | — | 0³ | 0 | 23 | — | — | ✓ |
| **TypeScript · Nuxt** | Nuxt | 141 | 8 | 0 | 64 | — | — | ✓ |
| **JavaScript · Express** | Express + Mongoose | 51 | 10 | 5 | 0 | 1,241 | ~20,800 | **~17x** |
| **Ruby · Rails** | Rails + ActiveRecord | 4,172 | 607 | 116 | 0 | 21,711 | ~386,100 | **~17.8x** |
| **PHP · Laravel** | Laravel + Eloquent | 3,896 | 652 | 59 | 0 | 30,739 | ~493,285 | **~16x** |
| **Python · Django** | Django + pyproject.toml | 4,232 | 7¹ | 56 | 0 | 83,842 | ~631,020 | **~7.5x** |
| **Python · Flask** | Flask + SQLAlchemy | 30 | 12 | 5 | 0 | 1,148 | ~16,705 | **~14.5x** |
| **Python · FastAPI** | FastAPI + SQLModel（单体） | 143 | 21 | 2 | 36 | 2,487 | ~38,090 | **~15.3x** |
| **Elixir · Phoenix** | Phoenix + Ecto | 1,406 | 198 | 54 | 0 | 9,589 | ~152,100 | **~15.9x** |
| **Go · Gin** | Gin + GORM（企业应用） | 388 | 202 | 169 | 0 | 15,266 | ~262,730 | **~17.2x** |
| **Go · Echo** | Echo | — | 7 | 0 | 0 | — | — | ✓ |
| **Go · Fiber** | Fiber | — | 5 | 0 | 0 | — | — | ✓ |
| **Rust · Actix** | actix-web | 528 | 30 | 0 | 0 | 1,355 | ~27,170 | **~20x** |
| **Rust · Axum** | Axum | — | 6 | 0 | 0 | — | — | ✓ |
| **C# · ASP.NET** | ASP.NET Core + Entity Framework Core | 256 | 13 | 7 | 0 | 5,126 | ~63,570 | **~12.4x** |
| **Java · Spring** | Spring Boot + Java（Maven） | 47 | 16 | 0 | 0 | 319 | ~13,208 | **~41x²** |
| **Swift · SwiftUI** | SwiftUI | 388 | 0 | 0 | 62 | 7,499 | ~76,830 | **~10.2x** |
| **Swift · Vapor** | Vapor 后端 | 294 | 81 | 0 | 0 | 6,146 | ~95,160 | **~15.5x** |
| **Dart · Flutter** | Flutter + go_router | 204 | 10 | 0 | 89 | 8,500 | ~86,125 | **~10.1x** |
¹ Django 项目采用 GraphQL 优先 —— 准确检测到 7 个 REST 工具端点，0 误报。
² 小型样板项目在 Spring Boot 上比率较高，因其路由元数据压缩率高。
³ SvelteKit 的 RealWorld 应用使用页面路由（`+page.svelte`），而非 JSON API 端点（`+server.ts`）；0 路由为正确结果。
**探索令牌估算方式：** `路由 × 400 + 模型 × 300 + 组件 × 250 + 热文件 × 150 + 环境变量 × 30`，再乘以 1.3 的重新访问系数。这些数值为保守估计。开发者手动验证表明，Claude Code 探索同类项目需 40–70K 令牌，而 codesight 仅用 3–5K 令牌即可汇总。
### 维基分解（v1.6.2）
| 项目 | 完整 CODESIGHT.md | 仅维基索引 | 索引 + 1 篇文章 | 生成的维基文章数 |
|---|---|---|---|---|
**SaaS A** | 3,936 令牌 | ~200 令牌 | ~550 令牌 | 9 |
| **SaaS B** | 3,629 令牌 | ~200 令牌 | ~440 令牌 | 11 |
| **SaaS C** | 4,162 令牌 | ~200 令牌 | ~360 令牌 | 17 |
“认证如何工作？”——无维基时：加载 3,945 令牌。启用维基后：读取 `auth.md`（~350 令牌）。**针对单个问题的提升达 11 倍，整体相比手动方式提升 84 倍。**
### 检测准确率
对照实际源码文件验证。路由数量与路由定义交叉核对；模型与 ORM 表声明核对。
| 项目 | 路由召回率 | 架构召回率 | 误报数 | 检测方法 |
|---|---|---|---|---|
| **SaaS A** | 38/43 (88%) | 12/12 (100%) | 0 | 架构：AST（Drizzle），路由：AST（Hono） |
| **SaaS B** | 17/17 (100%) | 8/8 (100%) | 0 | 完整 AST（Hono + Drizzle + React） |
| **SaaS C** | 56/59 (~95%) | 0/0（正确） | 0 | AST（FastAPI + MongoDB） |
SaaS A 的 5 条漏检路由使用了动态 `url.match(/pattern/)` 编写在请求处理器内 —— 这是静态分析无法解析的开发者模式，并非框架缺陷。SaaS C 估算漏掉 3 条 FastAPI 路由。零误报。
### 爆炸半径准确度
在生产 SaaS 上测试：修改数据库模块正确识别：
- **5 个受影响文件**，跨越 API、认证与服务器层
- **所有访问数据库的路由**
- **12 个受影响模型**（完整架构）
- **BFS 深度：** 3 跳通过导入图
### 检测内容
在三个基准项目上测量：
| 检测器 | SaaS A（138 文件） | SaaS B（53 文件） | SaaS C（40 文件） |
|---|---|---|---|
| **路由** | 38 | 17 | 56 |
| **架构模型** | 12 | 8 | 0 |
| **组件** | 0 | 10 | 0 |
| **环境变量** | 12 | 7 | 15 |
| **热文件** | 20 | 20 | 20 |
---
## 工作原理
codesight 并行运行全部 8 个检测器，然后将结果写入结构化的 Markdown。输出设计为单文件加载即可被 AI 读取。
## 生成内容
```
.codesight/
CODESIGHT.md Combined context map (one file, full project understanding)
routes.md Every API route with method, path, params, and what it touches
schema.md Every database model with fields, types, keys, and relations
components.md Every UI component with its props
libs.md Every library export with function signatures
config.md Every env var (required vs default), config files, key deps
middleware.md Auth, rate limiting, CORS, validation, logging, error handlers
graph.md Which files import what and which break the most things if changed
report.html Interactive visual dashboard (with --html or --open)
```
## AST 精准度
当被扫描项目安装了 TypeScript 时，codesight 使用实际的 TypeScript 编译器 API 进行结构化解析。无正则猜测。
| AST 能实现而正则不能 | 仅正则 |
|---|---|
| 跟踪 `router.use('/prefix', subRouter)` 链式路由 | 漏掉嵌套路由 |
| 合并 `@Controller('users')` + `@Get(':id')` 为 `/users/:id` | 可能漏掉前缀 |
| 解析 `router({ users: userRouter })` 的 tRPC 嵌套 | 行级匹配 |
| 从 `.primaryKey().notNull()` 链提取精确的 Drizzle 字段类型 | 模式匹配 |
| 从 TypeScript 接口与解构获取 React 属性 | 正则匹配 `{ prop }` |
| 检测路由链中的中间件：`app.get('/path', auth, handler)` | 未捕获 |
| 过滤非路由调用如 `c.get('userId')` | 可能误报 |
AST 检测结果会体现在输出中：
```
Analyzing... done (AST: 60 routes, 18 models, 16 components)
```
无需配置。如果项目中有 TypeScript，AST 会自动启用。支持 npm、yarn 和 pnpm（包括严格模式）。对非 TypeScript 项目或不支持 AST 的框架回退至正则。
**支持 AST 的框架：** Express、Hono、Fastify、Koa、Elysia（路由链 + 中间件）、NestJS（装饰器组合 + 守卫）、tRPC（路由嵌套 + 过程类型）、Drizzle（字段链 + 关系）、TypeORM（实体装饰器）、React（属性来自接口 + 解构 + forwardRef/memo）。
## 路由
不只是路径。还包括方法、 URL 参数、每条路由涉及的内容（认证、数据库、缓存、支付、AI、邮件、队列）以及处理器位置。自动检测 25+ 框架的路由。
示例输出：
```
- `GET` `/api/users/me` [auth, db, cache]
- `PUT` `/api/users/me` [auth, db]
- `POST` `/api/projects` [auth, db, payment]
- `GET` `/api/projects/:id` params(id) [auth, db]
- `POST` `/webhooks/stripe` [db, payment]
- `GET` `/health`
```
## 架构
模型、字段、类型、主键、外键、唯一约束、关系。直接从 ORM 定义解析，无需打开迁移文件。
示例输出：
```
### 用户
- id: text (pk)
- name: text (required)
- email: text (unique, required)
- role: text (default, required)
- stripeCustomerId: text (fk)
### 项目
- id: uuid (default, pk)
- ownerId: text (fk, required)
- name: text (required)
- settings: jsonb (required)
- _relations_: ownerId -> user.id
```
## 依赖图
导入最多的文件是变更时最容易破坏的部分。codesight 找到它们并告知你的 AI 需要小心。
示例输出：
```
## 最重要导入文件 (请谨慎修改)
- `src/types/index.ts` — imported by **20** files
- `src/db/index.ts` — imported by **12** files
- `src/lib/auth.ts` — imported by **8** files
- `src/lib/cache.ts` — imported by **6** files
- `src/lib/env.ts` — imported by **5** files
```
## 爆炸半径
通过导入图进行 BFS，找到所有传递影响的文件、路由、模型和中间件。
```
npx codesight --blast src/db/index.ts
```
示例输出：
你的 AI 还可通过 MCP 服务器在修改文件前查询爆炸半径。
## 环境审计
项目中的每个环境变量，无论必需与否，均已标记并标注其所在的确切文件。
示例输出：
```
- `DATABASE_URL` **required** — .env.example
- `REDIS_URL` (has default) — .env.example
- `STRIPE_SECRET_KEY` **required** — src/lib/payments.ts
- `STRIPE_WEBHOOK_SECRET` **required** — .env.example
- `RESEND_API_KEY` **required** — .env.example
- `JWT_SECRET` **required** — src/lib/auth.ts
```
## 令牌基准
明确了解你的令牌节省来源：
```
npx codesight --benchmark
```
示例输出（SaaS A — 138 文件，Hono + Drizzle）：
```
Token Savings Breakdown:
┌──────────────────────────────────────────────────┐
│ What codesight found │ Exploration cost │
├──────────────────────────────┼────────────────────┤
│ 38 routes │ ~15,200 tokens │
│ 12 schema models │ ~ 3,600 tokens │
│ 0 components │ 0 tokens │
│ 30 library files │ ~ 6,000 tokens │
│ 12 env vars │ ~ 1,200 tokens │
│ 5 middleware │ ~ 1,000 tokens │
│ 20 hot files │ ~ 3,000 tokens │
│ 138 files (search overhead) │ ~11,040 tokens │
├──────────────────────────────┼────────────────────┤
│ codesight output │ ~ 3,936 tokens │
│ Manual exploration (1.3x) │ ~46,020 tokens │
│ SAVED PER CONVERSATION │ ~42,084 tokens │
└──────────────────────────────┴────────────────────┘
```
### 令牌节省计算方式
每种检测器类型对应一个测量过的令牌开销，代表 AI 手动获取相同信息所需的成本：
| codesight 发现的内容 | 每项节省令牌 | 原因 |
|---|---|---|
| 每条路由 | ~400 令牌 | AI 读取处理器文件、搜索路径、读取中间件 |
| 每个架构模型 | ~300 令牌 | AI 打开迁移/ORM 文件、手动解析字段 |
| 每个组件 | ~250 令牌 | AI 打开组件文件、读取属性类型 |
| 每个库导出 | ~200 令牌 | AI 搜索导出、读取签名 |
| 每个环境变量 | ~100 令牌 | AI 搜索 `process.env`、读取 `.env` 文件 |
| 每个扫描文件 | ~80 令牌 | AI 执行 glob/grep 操作以查找相关文件 |
1.3 倍系数考虑了 AI 在多轮对话中重新访问文件的情况。这些估计较为保守。开发者手动验证表明，Claude Code 在探索同类项目时消耗 40–70K 令牌，而 codesight 仅用 3–5K 令牌即可汇总。
## 支持的技术栈
| 类别 | 支持 |
|---|---|
| **路由** | Hono、Express、Fastify、Next.js（App + Pages）、Koa、NestJS、tRPC、Elysia、AdonisJS、SvelteKit、Remix、Nuxt、FastAPI、Flask、Django、Go（net/http、Gin、Fiber、Echo、Chi）、Rails、Phoenix、Spring Boot、Ktor、Actix、Axum、Laravel、ASP.NET Core（控制器 + Minimal API）、Vapor、Flutter（go_router）、原生 `http.create` |
| **架构** | Drizzle、Prisma、TypeORM、Mongoose、Sequelize、SQLAlchemy、Django ORM、ActiveRecord、Ecto、Eloquent、Entity Framework、Exposed（13 种 ORM） |
| **组件** | React、Vue、Svelte、Flutter 小部件（StatelessWidget、StatefulWidget、ConsumerWidget）、SwiftUI 视图（自动过滤 shadcn/ui 和 Radix 基础组件） |
| **库** | TypeScript、JavaScript、Python、Go、Dart、Swift、C#（带函数签名的导出） |
| **中间件** | 认证、速率限制、CORS、校验、日志、错误处理 |
| **依赖** | 导入图与热文件检测（最导入的文件 = 最高爆炸半径） |
| **合约** | URL 参数、请求类型、响应类型（从路由处理器提取） |
| **单体仓库** | pnpm、npm、yarn 工作区 + 多语言单体仓库（例如 Next.js + Laravel、SwiftUI + Vapor） |
| **语言** | TypeScript、JavaScript、Python、Go、Ruby、Elixir、Java、Kotlin、Rust、PHP、Dart、Swift、C# |
## AI 配置生成
```
npx codesight --init
```
一次性生成所有主流 AI 工具的即用配置文件：
| 文件 | 工具 |
|---|---|
| `CLAUDE.md` | Claude Code |
| `.cursorrules` | Cursor |
| `.github/copilot-instructions.md` | GitHub Copilot |
| `codex.md` | OpenAI Codex CLI |
| `AGENTS.md` | OpenAI Codex agents |
每个文件均已预填充你的项目技术栈、架构、高影响文件及所需环境变量。你的 AI 在启动时读取该文件即可从第一条消息开始拥有完整上下文。
## MCP 服务器（13 个工具）
```
npx codesight --mcp
```
作为模型上下文协议服务器运行。Claude Code 和 Cursor 直接调用它以按需获取项目上下文。
```
{
"mcpServers": {
"codesight": {
"command": "npx",
"args": ["codesight", "--mcp"]
}
}
}
```
**OpenAI Codex CLI**（`~/.codex/config.toml`）：
```
[mcp_servers.codesight]
command = "npx"
args = ["codesight", "--mcp"]
startup_timeout_sec = 60
```
| 工具 | 功能 |
|---|---|
| `codesight_get_wiki_index` | 维基目录（~200 令牌）——会话启动时读取 |
| `codesight_get_wiki_article` | 按名称读取一篇文章：`auth`、`database`、`payments` 等 |
| `codesight_lint_wiki` | 健康检查：孤立文章、缺失交叉链接、陈旧内容 |
| `codesight_scan` | 完整项目扫描（~3K–5K 令牌） |
| `codesight_get_summary` | 紧凑概览（~500 令牌） |
| `codesight_get_routes` | 按前缀、标签或方法过滤路由 |
| `codesight_get_schema` | 按模型名称过滤架构 |
| `codesight_get_blast_radius` | 变更影响分析（变更前使用） |
| `codesight_get_env` | 环境变量（仅必需） |
| `codesight_get_hot_files` | 最常导入文件，可配置上限 |
| `codesight_get_events` | 后台事件：BullMQ 队列、Kafka 主题、Redis 发布/订阅、EventEmitter |
| `codesight_get_coverage` | 测试覆盖图：哪些路由和模型有测试文件 |
| `codesight_refresh` | 强制重新扫描（结果按会话缓存） |
你的 AI 按需请求精确内容，而非加载整个上下文映射。会话缓存意味着首次调用会扫描，后续调用立即返回。
## AI 工具配置文件
```
npx codesight --profile claude-code
npx codesight --profile cursor
npx codesight --profile codex
npx codesight --profile copilot
npx codesight --profile windsurf
```
为特定 AI 工具生成优化配置。每个配置文件包含项目摘要、技术栈信息、高影响文件、所需环境变量，以及针对该工具使用 codesight 输出的说明。对于 Claude Code，包含 MCP 工具使用说明；对于 Cursor，指向正确的 codesight 文件。每个配置文件写入对应工具的正确位置。
## 可视化报告
```
npx codesight --open
```
在浏览器中打开交互式 HTML 仪表板。包含路由表（带方法徽章和标签）、架构卡片（含字段与关系）、依赖热文件（影响条）、环境变量审计、令牌节省分解。适用于 onboarding 或从整体审视项目。
## GitHub 动作
```
name: codesight
on: [push]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g codesight && codesight
- uses: actions/upload-artifact@v4
with:
name: codesight
path: .codesight/
```
## 监听模式与 Git 钩子
**监听模式** 在代码变更时自动重新扫描：
```
npx codesight --watch
```
仅针对源码与配置文件（`.ts`、`.js`、`.py`、`.go`、`.prisma`、`.env` 等）触发。忽略 `node_modules`、构建输出和非代码文件。每次重新扫描显示变更文件。你的配置（禁用检测器、插件）会在重新扫描中保留。
**Git 钩子** 在每次提交时自动再生上下文：
```
npx codesight --hook
```
上下文始终保持最新，无需手动操作。
## 全部选项
```
npx codesight # Scan current directory
npx codesight ./my-project # Scan specific directory
npx codesight --wiki # Generate wiki knowledge base
npx codesight --init # Generate AI config files
npx codesight --open # Open visual HTML report
npx codesight --html # Generate HTML report without opening
npx codesight --mcp # Start MCP server (13 tools)
npx codesight --blast src/lib/db.ts # Show blast radius for a file
npx codesight --profile claude-code # Optimized config for specific tool
npx codesight --watch # Watch mode (add --wiki to auto-regenerate wiki)
npx codesight --wiki --watch # Watch + auto-regenerate wiki on changes
npx codesight --hook # Install git pre-commit hook (includes wiki)
npx codesight --benchmark # Detailed token savings breakdown
npx codesight --json # Output as JSON
npx codesight --mode knowledge # Map .md knowledge base → KNOWLEDGE.md
npx codesight --mode knowledge ~/vault # Map Obsidian vault or any .md folder
npx codesight --max-tokens 50000 # Trim output to fit token budget
npx codesight --since HEAD~5 # Show routes from last 5 commits only
npx codesight -o .ai-context # Custom output directory
npx codesight -d 5 # Limit directory depth
```
## 与其他工具的对比
| | codesight | 文件拼接工具 | 基于 AST 的工具（如 code-review-graph） |
|---|---|---|---|
| **解析** | AST（TypeScript 编译器）+ 正则回退 | 无 | Tree-sitter + SQLite |
| **令牌减少** | 7x–12x 基础扫描； 60–131x 搭配定向维基 | 1x（导出全部） | 8x 报告 |
| **路由检测** | 25+ 框架，自动识别 | 无 | 有限 |
| **架构解析** | 8 种 ORM，带字段类型与关系 | 无 | 各有不同 |
| **爆炸半径** | 通过导入图进行 BFS | 无 | 是 |
| **AI 工具配置** | 5 款工具（Claude、Cursor、Codex、GitHub Copilot、Windsurf） | 无 | 自动识别 |
| **MCP 工具** | 11 个专用工具，带会话缓存 | 无 | 22 个工具 |
| **设置** | `npx codesight`（零依赖、零配置） | 复制粘贴 | `pip install` 加上可选依赖 |
| **依赖** | 零（借用项目自身的 TypeScript） | 各有不同 | Tree-sitter、SQLite、网络库等 |
| **语言** | TypeScript（零运行时依赖） | 各有不同 | Python |
| **扫描耗时** | 小项目 185–290ms；大项目 0.9–2.8s（10K 文件） | 各有不同 | 报告 <2s |
codesight 专为解决实际问题而设计：让 AI 助手在无需遍历大量文件的情况下获得足够上下文。专注于结构化提取（路由、架构、组件、依赖关系），而非通用代码图谱分析。
## 贡献
```
git clone https://github.com/Houseofmvps/codesight.git
cd codesight
pnpm install
pnpm dev # Run locally
pnpm build # Compile TypeScript
pnpm test # Run 27 tests
```
欢迎提交 PR。重大变更请先开 issue 讨论。
## 许可证
MIT
---
如果 codesight 为你节省了令牌，请在 GitHub 上给它一颗星 🌟，让更多人发现它。
[](https://github.com/Houseofmvps/codesight/stargazers)
标签：AI上下文生成, AST解析, Claude Code, CMS安全, Codex, Copilot, Cursor, Dart, Elixir, Go, IPv6支持, JavaScript, Kotlin, MCP工具, MITM代理, npx一键使用, OpenVAS, ORM解析, PHP, Python, Ruby, Ruby工具, Rust, SEO优化, Swift, Token节省, TypeScript, 上下文管理, 二进制发布, 代码智能, 代码理解, 代码生成, 威胁情报, 安全插件, 开发者工具, 开源工具, 无后门, 框架检测, 正则检测, 渗透测试工具, 知识库, 网络流量审计, 自动化攻击, 跨语言支持, 零依赖