codesight-ai-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeSight — AI Context Generator

CodeSight — AI 上下文生成器

Skill by ara.so — Daily 2026 Skills collection.

CodeSight compiles your codebase into a compact, structured context map (routes, models, components, dependencies) that AI coding assistants can read in one shot — eliminating thousands of tokens spent on manual file exploration. Supports 14 languages, 30+ frameworks, 13 ORM parsers, and an MCP server with 13 tools.

由 ara.so 开发的Skill — 2026年度技能合集收录项目。

CodeSight 可将你的代码库编译为紧凑的结构化上下文映射（包含路由、模型、组件、依赖），AI编码助手可以一次性读取，省去了手动探索文件消耗的数千token。支持14种语言、30+框架、13种ORM解析器，以及自带13个工具的MCP服务器。

Installation

安装

No installation required. Run directly with

npx

bash

npx codesight

Or install globally:

bash

npm install -g codesight
codesight

Requirements: Node.js >= 18, no API keys, no config files needed.

无需安装，直接通过

npx

运行：

bash

npx codesight

或者全局安装：

bash

npm install -g codesight
codesight

要求： Node.js >= 18，无需API密钥，无需配置文件。

Core Commands

核心命令

bash

undefined

bash

undefined

Generate context map (default — outputs .codesight/CODESIGHT.md)

生成上下文映射（默认输出到 .codesight/CODESIGHT.md）

npx codesight

Generate persistent wiki knowledge base (.codesight/wiki/)

生成持久化Wiki知识库（.codesight/wiki/）

npx codesight --wiki

Generate AI tool config files (CLAUDE.md, .cursorrules, codex.md, AGENTS.md)

生成AI工具配置文件（CLAUDE.md、.cursorrules、codex.md、AGENTS.md）

npx codesight --init

Open interactive HTML report in browser

在浏览器中打开交互式HTML报告

npx codesight --open

Start as MCP server (13 tools) for Claude Code / Cursor

作为MCP服务器启动（包含13个工具），供Claude Code / Cursor使用

npx codesight --mcp

Show blast radius for a specific file

展示指定文件的影响范围

npx codesight --blast src/lib/db.ts

Generate optimized config for a specific AI tool

为指定AI工具生成优化配置

npx codesight --profile claude-code npx codesight --profile cursor npx codesight --profile copilot npx codesight --profile codex

Show token savings breakdown

展示Token节省明细

npx codesight --benchmark

Map markdown knowledge base (ADRs, meeting notes, Obsidian vault)

映射Markdown知识库（架构决策记录、会议记录、Obsidian vault）

npx codesight --mode knowledge npx codesight --mode knowledge ~/vault npx codesight --mode knowledge ./docs

Watch mode — regenerate on file changes

监听模式 — 文件变更时自动重新生成

npx codesight --watch

Git hook — regenerate on every commit

Git钩子 — 每次提交时自动重新生成

npx codesight --hook

undefined

npx codesight --hook

undefined

What Gets Generated

生成内容说明

Default Scan (

npx codesight

)

默认扫描（

npx codesight

）

Outputs

.codesight/CODESIGHT.md

— a structured map including:

Project metadata (stack, language, framework, package manager)
All routes with HTTP methods and handler locations
Database models with fields and relations
UI components with props
High-impact files ranked by dependency count
Framework and ORM detection results

输出

.codesight/CODESIGHT.md

— 结构化映射包含：

项目元数据（技术栈、语言、框架、包管理器）
所有路由，包含HTTP方法和处理函数位置
数据库模型，包含字段和关联关系
UI组件，包含props定义
按依赖数量排序的高影响文件
框架和ORM检测结果

Wiki Knowledge Base (

--wiki

)

Wiki知识库（

--wiki

）

Outputs

.codesight/wiki/

directory:

.codesight/wiki/
  index.md      — catalog of all articles (~200 tokens)
  overview.md   — architecture, subsystems, high-impact files
  auth.md       — auth routes, middleware, session flow
  payments.md   — payment routes, webhook handling, billing flow
  database.md   — all models, fields, relations
  users.md      — user management routes and models
  ui.md         — UI components with props
  log.md        — append-only operation log

输出

.codesight/wiki/

.codesight/wiki/
  index.md      — 所有文档的目录（约200 token）
  overview.md   — 架构、子系统、高影响文件说明
  auth.md       — 认证路由、中间件、会话流程
  payments.md   — 支付路由、Webhook处理、计费流程
  database.md   — 所有模型、字段、关联关系
  users.md      — 用户管理路由和模型
  ui.md         — 带props的UI组件说明
  log.md        — 仅追加的操作日志

AI Tool Config Files (

--init

)

AI工具配置文件（

--init

）

Generates project-root files for each AI tool:

```
CLAUDE.md
```
— Claude Code project instructions
```
.cursorrules
```
— Cursor rules file
```
codex.md
```
— OpenAI Codex context
```
AGENTS.md
```
— general agent instructions

为每个AI工具在项目根目录生成对应文件：

```
CLAUDE.md
```
— Claude Code项目说明
```
.cursorrules
```
— Cursor规则文件
```
codex.md
```
— OpenAI Codex上下文
```
AGENTS.md
```
— 通用Agent说明

MCP Server Mode

MCP服务器模式

Start CodeSight as an MCP server to give Claude Code or Cursor direct tool access:

bash

npx codesight --mcp

将CodeSight作为MCP服务器启动，让Claude Code或Cursor可以直接调用工具：

bash

npx codesight --mcp

MCP Tool Reference

MCP工具参考

Tool	Description
`codesight_get_context`	Full codebase context map
`codesight_get_routes`	All API routes with methods and handlers
`codesight_get_models`	All database models and schema
`codesight_get_components`	UI components with props
`codesight_get_blast_radius`	Impact analysis for a specific file
`codesight_get_high_impact_files`	Files ranked by dependency count
`codesight_get_framework_info`	Detected frameworks and ORMs
`codesight_get_wiki_index`	Wiki catalog (~200 tokens) for session start
`codesight_get_wiki_article`	Read one wiki article by name
`codesight_lint_wiki`	Wiki health check (orphans, stale, missing links)
`codesight_get_knowledge`	Knowledge map from markdown notes
`codesight_benchmark`	Token savings analysis
`codesight_get_overview`	Project overview summary

工具	描述
`codesight_get_context`	完整代码库上下文映射
`codesight_get_routes`	所有API路由，包含方法和处理函数
`codesight_get_models`	所有数据库模型和Schema
`codesight_get_components`	带props的UI组件
`codesight_get_blast_radius`	指定文件的影响分析
`codesight_get_high_impact_files`	按依赖数量排序的文件列表
`codesight_get_framework_info`	检测到的框架和ORM信息
`codesight_get_wiki_index`	会话启动用的Wiki目录（约200 token）
`codesight_get_wiki_article`	按名称读取单篇Wiki文档
`codesight_lint_wiki`	Wiki健康检查（孤立文档、过期内容、缺失链接）
`codesight_get_knowledge`	从Markdown笔记生成的知识映射
`codesight_benchmark`	Token节省分析
`codesight_get_overview`	项目概览摘要

Configuring MCP in Claude Code

在Claude Code中配置MCP

Add to your Claude Code MCP config (

~/.claude/mcp_settings.json

or project

.mcp.json

json

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

添加到你的Claude Code MCP配置（

~/.claude/mcp_settings.json

或项目级

.mcp.json

）：

json

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Configuring MCP in Cursor

在Cursor中配置MCP

Add to

.cursor/mcp.json

in your project root:

json

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"]
    }
  }
}

添加到项目根目录的

.cursor/mcp.json

：

json

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"]
    }
  }
}

Language & Framework Support

语言与框架支持

Language	AST Precision	Frameworks Detected
TypeScript	✅ Full AST	Next.js, NestJS, Hono, Remix, SvelteKit, Nuxt, Express, Fastify
JavaScript	Regex	Express, Fastify, Koa, Hapi
Python	Regex	Django, FastAPI, Flask, SQLAlchemy
Go	Regex	Gin, Echo, Fiber, Chi
Ruby	Regex	Rails, Sinatra
PHP	Regex	Laravel, Symfony
Elixir	Regex	Phoenix
Java	Regex	Spring Boot
Kotlin	Regex	Ktor, Spring Boot
Rust	Regex	Axum, Actix
Dart	Regex	Flutter
Swift	Regex	Vapor
C#	Regex	ASP.NET Core

语言	AST精度	支持检测的框架
TypeScript	✅ 完整AST	Next.js、NestJS、Hono、Remix、SvelteKit、Nuxt、Express、Fastify
JavaScript	正则匹配	Express、Fastify、Koa、Hapi
Python	正则匹配	Django、FastAPI、Flask、SQLAlchemy
Go	正则匹配	Gin、Echo、Fiber、Chi
Ruby	正则匹配	Rails、Sinatra
PHP	正则匹配	Laravel、Symfony
Elixir	正则匹配	Phoenix
Java	正则匹配	Spring Boot
Kotlin	正则匹配	Ktor、Spring Boot
Rust	正则匹配	Axum、Actix
Dart	正则匹配	Flutter
Swift	正则匹配	Vapor
C#	正则匹配	ASP.NET Core

ORM / Database Support

ORM/数据库支持

Drizzle, Prisma, TypeORM, Sequelize, Mongoose, MikroORM, SQLAlchemy, Django ORM, ActiveRecord, Eloquent, Ecto, GORM, and more (13 total).

Drizzle、Prisma、TypeORM、Sequelize、Mongoose、MikroORM、SQLAlchemy、Django ORM、ActiveRecord、Eloquent、Ecto、GORM等（共13种）。

Real Usage Patterns

实际使用场景

Pattern 1: Session Start with Wiki

场景1：会话启动时加载Wiki

At the beginning of every AI session, load the wiki index instead of the full context map:

undefined

每次AI会话开始时，加载Wiki目录而非完整上下文映射：

undefined

In Claude Code or Cursor, at session start:

在Claude Code或Cursor中，会话开始时执行：

Use codesight_get_wiki_index to get project overview, then codesight_get_wiki_article for "auth" to understand authentication.

undefined

使用codesight_get_wiki_index获取项目概览，然后调用codesight_get_wiki_article获取"auth"相关内容了解认证逻辑。

undefined

Pattern 2: Blast Radius Before Refactoring

场景2：重构前查询影响范围

Before modifying a shared file, check what breaks:

bash

npx codesight --blast src/lib/database.ts

Output shows every file that imports the target, ranked by impact — critical before refactoring database connections, shared utilities, or types.

修改共享文件前，检查会影响哪些内容：

bash

npx codesight --blast src/lib/database.ts

输出会展示所有导入目标文件的文件，按影响程度排序 — 在重构数据库连接、共享工具函数或类型定义前非常重要。

Pattern 3: CI/CD Integration

场景3：CI/CD集成

Keep context fresh on every push:

yaml

undefined

每次推送时更新上下文，保持内容新鲜：

yaml

undefined

.github/workflows/codesight.yml

name: Update AI Context on: push: branches: [main]

jobs: update-context: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - name: Generate context map run: npx codesight - name: Generate wiki run: npx codesight --wiki - name: Generate knowledge map run: npx codesight --mode knowledge ./docs - name: Commit updated context run: | git config --local user.email "action@github.com" git config --local user.name "GitHub Action" git add .codesight/ git diff --staged --quiet || git commit -m "chore: update AI context [skip ci]" git push

undefined

name: Update AI Context on: push: branches: [main]

undefined

Pattern 4: Git Hook for Local Freshness

场景4：本地Git钩子保持内容新鲜

bash

npx codesight --hook

This installs a post-commit hook that regenerates

.codesight/CODESIGHT.md

automatically after every commit.

bash

npx codesight --hook

该命令会安装一个post-commit钩子，每次提交后自动重新生成

.codesight/CODESIGHT.md

。

Pattern 5: Knowledge Mapping for Decision Records

场景5：架构决策记录的知识映射

bash

undefined

bash

undefined

Map ADRs and architecture docs

映射ADR和架构文档

npx codesight --mode knowledge ./docs/decisions

Map full Obsidian vault

映射完整Obsidian vault

npx codesight --mode knowledge ~/vault

Outputs .codesight/KNOWLEDGE.md with:

输出.codesight/KNOWLEDGE.md，包含：

- Key decisions extracted from ADR files

- 从ADR文件提取的关键决策

- Open questions surfaced from notes

- 从笔记中发现的未解决问题

- Meeting notes indexed by date

- 按日期索引的会议记录

- Specs and PRDs cataloged

- 分类整理的规范和产品需求文档

undefined

undefined

Consuming the Output in AI Sessions

在AI会话中使用生成的内容

Loading Context in Claude Code (manual)

在Claude Code中手动加载上下文

Read .codesight/CODESIGHT.md for project context before answering questions.

回答问题前先读取.codesight/CODESIGHT.md获取项目上下文。

Loading Wiki at Session Start

会话启动时加载Wiki

Read .codesight/wiki/index.md first. 
Then read the relevant article (e.g. .codesight/wiki/auth.md) 
only when questions about that domain arise.

首先读取.codesight/wiki/index.md。
只有当问题涉及对应领域时，再读取相关文档（例如.codesight/wiki/auth.md）。

Loading Combined Context

加载组合上下文

Read .codesight/CODESIGHT.md for code structure and 
.codesight/KNOWLEDGE.md for architectural decisions.

读取.codesight/CODESIGHT.md了解代码结构，读取.codesight/KNOWLEDGE.md了解架构决策。

Token Savings Reference

Token节省参考

Approach	Tokens per session	Savings vs baseline
Manual file exploration	26K–47K	baseline
`npx codesight` (context map)	3K–5K	7x–12x
`--wiki` targeted article	~200 + ~300/question	60x–130x

Real benchmark results from production codebases:

Project	Stack	Files	Output Tokens	Exploration Tokens	Savings
SaaS A	Hono + Drizzle	138	3,936	46,020	11.7x
SaaS B	Hono + Drizzle (monorepo)	53	3,629	26,130	7.2x
SaaS C	FastAPI + MongoDB	40	4,162	47,450	11.4x
Rails app	Rails + ActiveRecord	4,172	21,711	386,100	17.8x
Laravel app	Laravel + Eloquent	3,896	30,739	493,285	16x

方案	每次会话Token消耗	较基准的节省比例
手动探索文件	26K–47K	基准
`npx codesight` （上下文映射）	3K–5K	7倍–12倍
`--wiki` 定向读取文档	~200 + ~300/每个问题	60倍–130倍

生产代码库的实测基准结果：

项目	技术栈	文件数	输出Token数	探索消耗Token数	节省比例
SaaS A	Hono + Drizzle	138	3,936	46,020	11.7倍
SaaS B	Hono + Drizzle（ monorepo）	53	3,629	26,130	7.2倍
SaaS C	FastAPI + MongoDB	40	4,162	47,450	11.4倍
Rails应用	Rails + ActiveRecord	4,172	21,711	386,100	17.8倍
Laravel应用	Laravel + Eloquent	3,896	30,739	493,285	16倍

.codesight Directory Structure

.codesight 目录结构

.codesight/
  CODESIGHT.md       — main context map (commit this)
  KNOWLEDGE.md       — knowledge/decision map (commit this)
  wiki/
    index.md         — wiki catalog (commit this)
    overview.md
    auth.md
    database.md
    payments.md
    users.md
    ui.md
    log.md

Add

.codesight/

to git to persist context across sessions and team members. The wiki survives session restarts — every new conversation starts with full codebase knowledge from the first message.

.codesight/
  CODESIGHT.md       — 主上下文映射（建议提交到Git）
  KNOWLEDGE.md       — 知识/决策映射（建议提交到Git）
  wiki/
    index.md         — Wiki目录（建议提交到Git）
    overview.md
    auth.md
    database.md
    payments.md
    users.md
    ui.md
    log.md

将

.codesight/

添加到Git中，可在会话和团队成员之间同步上下文。Wiki内容会在会话重启后保留 — 每次新对话从第一条消息开始就具备完整的代码库知识。

Troubleshooting

故障排查

Routes not detected:

Ensure you're running from the project root (where
```
package.json
```
or equivalent lives)
TypeScript projects get full AST parsing; other languages use regex — check that route files follow standard framework conventions
For Python FastAPI, ensure router files use standard
```
@app.get()
```
/
```
@router.post()
```
decorators

Models showing 0 for MongoDB:

This is correct behavior — codesight parses SQL ORM declarations. MongoDB collections without Mongoose schemas won't appear. Define Mongoose schemas explicitly to get model detection.

Wiki articles missing:

Run
```
npx codesight --wiki
```
first to generate the wiki directory

Use

codesight_lint_wiki

MCP tool or check

.codesight/wiki/log.md

for generation errors

Large monorepos (10K+ files) are slow:

Add a
```
.codesightignore
```
file (same syntax as
```
.gitignore
```
) to exclude build artifacts, generated files, and
```
node_modules
```
subdirectories
Typical scan time: 186ms–890ms for projects under 5K files

MCP server not connecting:

Verify Node.js >= 18:
```
node --version
```
Check
```
cwd
```
in MCP config points to the actual project root
Run
```
npx codesight --mcp
```
manually first to confirm it starts without errors

--init
overwrites existing CLAUDE.md:

Back up existing files before running
```
--init
```
on a project with custom AI instructions
Generated files are additive starting points — merge with your existing content manually

路由未检测到：

确保你在项目根目录运行命令（即
```
package.json
```
或等效文件所在目录）
TypeScript项目支持完整AST解析；其他语言使用正则匹配 — 请确保路由文件遵循标准框架约定
Python FastAPI项目请确保路由文件使用标准的
```
@app.get()
```
/
```
@router.post()
```
装饰器

MongoDB模型显示为0：

这是正常行为 — codesight仅解析SQL ORM声明。没有Mongoose Schema的MongoDB集合不会被检测到。显式定义Mongoose Schema即可实现模型检测。

Wiki文档缺失：

先运行
```
npx codesight --wiki
```
生成Wiki目录
使用
```
codesight_lint_wiki
```
MCP工具或查看
```
.codesight/wiki/log.md
```
排查生成错误

大型Monorepo（10K+文件）扫描缓慢：

添加
```
.codesightignore
```
文件（语法与
```
.gitignore
```
一致）排除构建产物、生成文件和
```
node_modules
```
子目录
典型扫描速度：5K文件以下的项目耗时186ms–890ms

MCP服务器连接失败：

确认Node.js版本 >= 18：
```
node --version
```
检查MCP配置中的
```
cwd
```
是否指向实际项目根目录
先手动运行
```
npx codesight --mcp
```
确认可以正常启动无报错

--init
覆盖了现有CLAUDE.md：

如果你项目有自定义AI指令，运行
```
--init
```
前先备份现有文件
生成的文件是增量的起点 — 请手动与你现有内容合并

codesight-ai-context

Original

Translation

CodeSight — AI Context Generator

CodeSight — AI 上下文生成器

Installation

安装

Core Commands

核心命令

Generate context map (default — outputs .codesight/CODESIGHT.md)

生成上下文映射（默认输出到 .codesight/CODESIGHT.md）

Generate persistent wiki knowledge base (.codesight/wiki/)

生成持久化Wiki知识库（.codesight/wiki/）

Generate AI tool config files (CLAUDE.md, .cursorrules, codex.md, AGENTS.md)

生成AI工具配置文件（CLAUDE.md、.cursorrules、codex.md、AGENTS.md）

Open interactive HTML report in browser

在浏览器中打开交互式HTML报告

Start as MCP server (13 tools) for Claude Code / Cursor

作为MCP服务器启动（包含13个工具），供Claude Code / Cursor使用

Show blast radius for a specific file

展示指定文件的影响范围

Generate optimized config for a specific AI tool

为指定AI工具生成优化配置

Show token savings breakdown

展示Token节省明细

Map markdown knowledge base (ADRs, meeting notes, Obsidian vault)

映射Markdown知识库（架构决策记录、会议记录、Obsidian vault）

Watch mode — regenerate on file changes

监听模式 — 文件变更时自动重新生成

Git hook — regenerate on every commit

Git钩子 — 每次提交时自动重新生成

What Gets Generated

生成内容说明

Default Scan (npx codesight)

默认扫描（npx codesight）

Wiki Knowledge Base (--wiki)

Wiki知识库（--wiki）

AI Tool Config Files (--init)

AI工具配置文件（--init）

MCP Server Mode

MCP服务器模式

MCP Tool Reference

MCP工具参考

Configuring MCP in Claude Code

在Claude Code中配置MCP

Configuring MCP in Cursor

在Cursor中配置MCP

Language & Framework Support

语言与框架支持

ORM / Database Support

ORM/数据库支持

Real Usage Patterns

实际使用场景

Pattern 1: Session Start with Wiki

场景1：会话启动时加载Wiki

In Claude Code or Cursor, at session start:

在Claude Code或Cursor中，会话开始时执行：

Pattern 2: Blast Radius Before Refactoring

场景2：重构前查询影响范围

Pattern 3: CI/CD Integration

场景3：CI/CD集成

.github/workflows/codesight.yml

.github/workflows/codesight.yml

Pattern 4: Git Hook for Local Freshness

场景4：本地Git钩子保持内容新鲜

Pattern 5: Knowledge Mapping for Decision Records

场景5：架构决策记录的知识映射

Map ADRs and architecture docs

映射ADR和架构文档

Map full Obsidian vault

映射完整Obsidian vault

Outputs .codesight/KNOWLEDGE.md with:

输出.codesight/KNOWLEDGE.md，包含：

- Key decisions extracted from ADR files

- 从ADR文件提取的关键决策

- Open questions surfaced from notes

- 从笔记中发现的未解决问题

- Meeting notes indexed by date

- 按日期索引的会议记录

- Specs and PRDs cataloged

Default Scan (
`npx codesight`
)

默认扫描（
`npx codesight`
）

Wiki Knowledge Base (
`--wiki`
)

Wiki知识库（
`--wiki`
）

AI Tool Config Files (
`--init`
)

AI工具配置文件（
`--init`
）