codesight：把代码库编译成 AI 上下文的 CLI

它想解决的其实是会话启动成本

AI 编程助手每开一个新会话，都要先搞清楚这个项目长什么样：路由在哪、模型怎么定义、哪个文件被到处引用。这个过程通常靠模型自己去读文件，README 里把这段开销描述为「每次对话浪费数千 token」。codesight 的思路是提前把结构信息编译成一份静态文档，会话开始时直接喂给模型，跳过探索阶段。

目标用户很明确：一个人或小团队维护一个中等规模仓库，日常在 Claude Code、Cursor、Copilot、Codex、Windsurf、Cline、Aider 之间切换，并且对 token 账单或上下文窗口占用敏感。README 里列出的 14 种语言覆盖面很宽，但真正决定体验的是主力语言是不是 TypeScript，原因在后文展开。

AST 优先，其余语言退回正则

README 给出的机制说明相当直白：TypeScript 项目走完整 AST 精度，其他语言使用「久经考验的正则检测」覆盖同一批 30 多个框架识别器和 14 个 ORM 解析器。这意味着同一份扫描代码在不同语言上得到的可信度并不一样。AST 能拿到真实的导入关系、导出符号和调用位置；正则只能靠模式匹配猜。对 Go 或 Rust 项目，框架识别大概率仍然可用，但涉及跨文件引用、动态导入、宏展开这类结构，正则给不出确定答案。

仓库里还有一个 --native-ast 开关，README 注明它是可选启用，用于为更多语言加载 AST 插件，并指向 docs/wasm-plugins.md。也就是说，非 TypeScript 项目想要更精确的结果，需要额外打开这个选项，而插件体系的具体覆盖范围需要查那份文档才能确认。

数据流大致是：扫描仓库 → 识别框架、ORM、路由、模型、中间件 → 生成 CODESIGHT.md 等上下文文件，或者进一步生成 .codesight/wiki/ 下的分主题文章。wiki 部分 README 特别强调「从 AST 编译，而不是由 LLM 生成，零 API 调用」，并给出 200ms 这个数字。这个设计取舍值得注意：不调用模型意味着没有推理成本，也意味着文章内容是结构化数据的模板化叙述，不是对代码意图的解释。

一条 npx 命令和几个关键开关

安装方式就是直接运行，README 明确写了「不需要配置、不需要初始化、不需要 API key」：

npx codesight

在项目根目录执行即可。常用的几个变体：

npx codesight --init 生成 CLAUDE.md、.cursorrules、codex.md、AGENTS.md 这几个 AI 工具各自的配置文件。

npx codesight --wiki 生成 .codesight/wiki/ 知识库目录，README 展示的结构包含 index.md（约 200 token 的目录）、overview.md（架构与高影响文件，约 500 token），以及 auth.md、payments.md、database.md、users.md、ui.md 这类按主题拆分的文章，外加一个 append-only 的 log.md。

npx codesight --mcp 以 MCP 服务器方式启动，对外暴露 14 个工具。其中三个与 wiki 相关：codesight_get_wiki_index 取目录，codesight_get_wiki_article 按名字读单篇文章，codesight_lint_wiki 做健康检查，README 说它会报告孤立文章、缺失的交叉链接和过期内容。

npx codesight --blast src/lib/db.ts 查看某个文件的爆炸半径，也就是改动会影响哪些地方。

另外还有 --profile claude-code 针对特定 AI 工具生成优化配置，--benchmark 输出 token 节省的详细拆解，--open 在浏览器里打开交互式 HTML 报告，--watch 和 --hook 分别用于持续跟踪和提交时重生成。

知识模式是另一条线：npx codesight --mode knowledge 扫描当前目录的 .md 文件，也可以指向 Obsidian vault 或文档目录，产出 .codesight/KNOWLEDGE.md，把决策记录、会议笔记、ADR 汇总成一份上下文入口。README 展示的输出头部会统计笔记数、决策数和开放问题数。

wiki 的 token 账要自己算

README 用一张对照表说明 wiki 的价值：问「auth 怎么工作」，不用 wiki 时模型要读 8 个以上文件，约 12K token；用 wiki 时读 auth.md，约 300 token。问「有哪些模型」，从完整 CODESIGHT.md 的约 5K token 降到 database.md 的约 400 token。新会话启动从约 5K 降到 index.md 的约 200 token。

这些数字来自项目自己的说明，我没有独立验证过。它们成立的前提是模型确实只读了那一篇文章，而不是读完 index.md 又顺手把整个 .codesight 目录加载进来。分主题拆分的收益取决于拆分粒度是否匹配你的提问习惯：如果一个仓库的 auth 逻辑散在十几个文件里，auth.md 要么变得很长，要么漏掉一部分，两种情况下省下的 token 都会打折扣。README 提到的 codesight_lint_wiki 正是为这类问题准备的，它会检查孤立文章和过期内容。

另一个实际问题是 wiki 提交进 git 之后会持续产生 diff。每次重新生成都可能改动多篇文章，代码评审时这部分噪音需要单独处理。

零依赖、MIT，以及维护成本的现实面

项目标注 0 依赖、Node.js >= 18、MIT 许可。零依赖对 CLI 工具来说是实打实的好处：不会因为某个传递依赖升级而突然跑不起来，审计也简单。MIT 允许商用和修改，把生成的文件提交进仓库在许可层面没有额外约束，不过生成内容里是否包含你自己代码的片段，仍然要按你所在组织对代码外发的规则来判断，这不是许可问题。

维护成本主要落在两处。一是重新生成的时机：代码结构变化后 CODESIGHT.md 和 wiki 会过期，README 提供了 --watch 和 --hook 两种自动化方式，但把它们接进现有工作流需要自己调试。二是版本升级：README 里 v1.6.2 引入 wiki、v1.9.3 引入知识模式，功能在持续增加，MCP 工具数量也从早期版本扩展到 14 个。工具数量变化意味着给 AI 助手的工具描述也会变，如果你的提示词里写死了工具名，升级时要跟着改。

仓库没有检索到 release 记录，所以版本节奏只能从 README 里标注的版本号推断，无法确认发布频率。

什么时候它不是你该用的工具

最明显的一条：主力语言不是 TypeScript，却想要结构化精度。README 自己承认非 TS 语言走正则，这类检测对命名约定和文件布局敏感。如果你们的 Go 服务用了一套自研的依赖注入方式，正则很可能识别不出路由和模型的真实关系，生成出来的上下文反而会误导模型。这种情况下 --native-ast 是否覆盖你的语言，需要先查 docs/wasm-plugins.md。

第二条：仓库规模很小。一个几千行的项目，模型直接读几个文件就够了，引入 codesight 只是多了一层需要维护的生成产物。省 token 的收益在文件多、跨文件引用密集的仓库里才明显。

第三条：把 codesight 当成代码理解工具。它做的是结构提取，不是语义分析。--blast 给出的是引用关系，不是「改这里会不会破坏业务逻辑」的判断。wiki 文章是从 AST 数据编译出来的叙述，不是有人读过代码后写的设计说明。

第四条：monorepo 或代码生成密集的项目。自动生成的代码、构建产物、多包之间的路径别名，都可能让扫描结果失真。跑完之后应该先人工核对一遍框架识别列表，再决定要不要把它提交进仓库。

和 repomap 类工具的区别在哪

Aider 内置的 repo map 是同一问题域里最常被拿来对比的方案。两者的差别在生成时机和产物形态上。

Aider 的 repo map 是运行时按需构建的：它在一次会话里根据当前对话内容，用 tree-sitter 分析代码并按相关性排序，动态挑选要放进上下文的符号，超出预算就裁剪。它不落盘，也不跨会话保留，每次新会话都要重新算一遍。

codesight 走的是另一条路：提前扫描，把结果写成 CODESIGHT.md 和 .codesight/wiki/ 这样的静态文件，提交进 git，跨会话复用。好处是会话启动时零计算，而且产物可以被人工阅读和修改；代价是它有滞后性，代码改了但没重新生成，模型拿到的就是过期信息。

所以选择取决于你的痛点在哪。如果你频繁开新会话、仓库结构稳定，静态产物的复用价值高；如果你在长时间连续会话里反复切换关注点，Aider 那种按需重建的机制更贴合。codesight 也提供 MCP 模式，让 Claude Code 或 Cursor 按需调用工具取数据，这实际上是在静态产物之外补了一条动态路径。

编辑结论

如果你的仓库以 TypeScript 为主，并且团队已经在用 Claude Code 或 Cursor，codesight 值得先跑一次 npx codesight --benchmark 看它报出的 token 节省明细，再决定是否把生成的 CODESIGHT.md 和 .codesight/wiki/ 提交进 git。如果主力语言是 Go、Rust、Java 这类只能走正则检测的栈，或者你无法接受把代码结构摘要写进仓库，那就先别急着接入。动手前要确认三件事：扫描结果里框架和 ORM 识别有没有漏报或误报，wiki 文章是否覆盖了你最常问的那几个模块，以及 --hook 自动重生成会不会和现有提交钩子冲突。

官方来源

1. Houseofmvps/codesight on GitHub
2. Issues
3. License: MIT
4. Project website
5. README