sputnicyoji/coderepomap

# coderepomap [](https://pypi.org/project/coderepomap/) [](https://www.python.org/downloads/) [](LICENSE) **English** | **[简体中文](README.zh-CN.md)** | **[日本語](README.ja.md)** `coderepomap` 会扫描代码库并输出三个 Markdown 层级——模块骨架、类签名和引用图——其大小分别约为 1k / 2k / 3k 个 token。AI agent 可以按需读取相应的层级，而无需逐个翻阅每个文件。这样就能将 token 花费在真正重要的代码上，并能捕捉到原本容易遗漏的跨文件引用。 语言支持是基于插件实现的：内置支持 C#、Lua 和 Go。在 Unity + xLua / sLua / ToLua 项目中，Lua 端对 C# 的调用（如 `CS.UnityEngine.GameObject`）会在同一个 L3 图中解析为真实的 C# 符号。Go 语言支持主要针对标准的 `go.mod` 模块，提供包感知的 ID、结构体嵌入、接口声明，以及基于导入别名的调用解析功能。 ## 功能 - **三层结构，同一预算。** L1 骨架 / L2 签名 / L3 关系，每一层都受到可配置的 token 预算限制（精确使用 `tiktoken`，回退策略为每 4 个字符算作 1 个 token）。渲染器会充分利用预算——对于包含 7000 个文件的 Go 项目，其 L1 预算利用率可达约 99%，而不是遇到硬性限制就停止。 - **多语言插件系统。** C# (`tree-sitter-c-sharp`)、Lua (`tree-sitter-lua`) 和 Go (`tree-sitter-go`) 共享同一个 `LanguageParser` 契约；只需添加一个子包即可支持更多语言。 - **跨语言关系图。** 通过项目级的符号索引来解析 Lua 对 C# 的引用，并且会明确展示存在歧义的候选项，而不是默默地将它们合并。 - **基于 PageRank 排名的输出。** 重要的类会浮升至每一层的顶部；可以通过前缀/后缀加权模式对排名进行插件级别的微调。 - **稳定的 Symbol ID。** 感知重载 (`csharp:Ns.Type.Method(int,string)`)，区分实例与静态 (`lua:mod.T#method` 与 `lua:mod.T.f`)，限定在 Go 模块路径下 (`go:example.com/myapp/pkg/service.Service.Run`)。 - **跳过自动生成的代码 (Go)。** 会自动检测并跳过匹配 `*.pb.go` / `*_gen.go` / `*.generated.go` 模式的文件，或者带有 `// Code generated ... DO NOT EDIT.` 标记的文件——仅保留包符号，以确保导入方仍能正确解析。在典型的 Go 服务仓库中，这能减少约 80% 的符号数量。 - **Git hooks。** 开箱即用的 `post-checkout` / `post-merge` 重新生成功能；可选的 Windows toast 通知器。 ## 安装 根据您的项目选择对应的扩展依赖： ``` pip install coderepomap[csharp] # C# / Unity pip install coderepomap[lua] # pure Lua pip install coderepomap[go] # Go pip install coderepomap[csharp,lua,go,tiktoken] # multi-lang + precise tokens ``` ## 快速开始 ``` cd your-project repomap init --lang csharp --preset unity # or --lang lua / --lang go / --preset generic repomap generate ``` 输出文件位于 `.repomap/output/` 目录中： | 文件 | 描述 | |---|---| | `repomap-L1-skeleton.md` | 模块级概览（约 1k token） | | `repomap-L2-signatures.md` | 类 / 函数签名（约 2k token） | | `repomap-L3-relations.md` | 引用图 + 外部引用（约 3k token） | | `repomap-meta.json` | 统计数据、git commit、排名器信息 | 您可以让 AI agent 根据具体问题去参考对应的层级文件。 ## 配置 单语言配置 (`.repomap/config.yaml`)： ``` project_name: My Game lang: csharp # or: lua / go source: root_path: Assets/Scripts exclude_patterns: ["**/Editor/**", "**/Tests/**"] ``` 多语言配置（Unity + Lua）： ``` project_name: Unity + xLua langs: [csharp, lua] sources: csharp: root_path: Assets/Scripts exclude_patterns: ["**/Editor/**"] lua: root_path: Assets/LuaScripts crosslang: enabled: true lua_csharp_call_patterns: - prefix: "CS." # xLua # - prefix: "UnityEngine." # sLua / ToLua ``` `repomap init` 会生成一个初始配置文件；请在运行 `repomap generate` 之前对其进行编辑。 ## 跨语言引用（Lua → C#） Lua 解析器会为 `CS.X.Y.Z` 链以及别名（`local GO = CS.X.Y; GO.Find(...)`）生成 `csharp_call` 引用。解析器会执行以下操作： 1. 去除配置中 Lua 端的前缀（`CS.`、`UnityEngine.` 等）。 2. 尝试与项目级类型索引中的 C# 完全限定名 (FQN) 进行精确匹配。 3. 如果链的末端是方法名，则回退匹配其所属的外围类型。 4. 回退到全项目范围的短名称查找；如果唯一则解析成功；如果有多个候选项，则标记为未解析，并在 L3 中提供 `lang_meta.candidates` 供查阅。 解析成功的边会进入 PageRank 图；未解析的边会在 L3 的 **External References** 下展示。算法细节请参阅：[docs/crosslang.md](docs/crosslang.md)。 ## 语言支持 | 语言 | 解析器 | 标识符方案 | 亮点 | |---|---|---|---| | C# | `tree-sitter-c-sharp` + 正则回退 | `csharp:Ns.Type.Method(paramtypes)` | 命名空间（包括文件作用域）、嵌套类型、感知重载的 ID、Unity 预设 | | Lua | `tree-sitter-lua` + 正则回退 | `lua:mod.T#method` (实例), `lua:mod.T.f` (静态) | xLua / sLua / ToLua、文件作用域别名表、`setmetatable` 继承 | | Go | `tree-sitter-go` + 正则回退 | `go:/..` | 感知 `go.mod` 模块路径、结构体嵌入 → `inherits`、接口声明、文件级导入别名表（包括 `/v2` 语义版本后缀启发式算法）、泛型、通过 `lang_meta` 区分指针与值接收器、`Code generated ... DO NOT EDIT.` 跳过 | | TypeScript | `tree-sitter-typescript` (TS + TSX 方言) + 正则回退 | `typescript:..` | ESM `.js`-后缀说明符解析、`index.ts` 目录导入、按文件的模块 + 按目录的包符号、接口 / 类型别名 / 枚举 / 箭头常量、继承关系 → `inherits` / `implements`、导入绑定调用解析、npm / 内置导入作为 L3 外部引用展示 | ## CLI | 命令 | 参数 | 描述 | |---|---|---| | `repomap init` | `--lang csharp\|lua\|go\|typescript`, `--preset unity\|generic`, `--force` | 写入 `.repomap/config.yaml` | | `repomap generate` | `--verbose`, `--notify`, `--config ` | 解析源码，写入 L1/L2/L3/meta | | `repomap status` | — | 显示上次运行的统计信息 + 已注册的语言解析器 | | `repomap hooks` | `--install` (默认), `--uninstall`, `--with-notify` | 管理 git `post-checkout` / `post-merge` 的重新生成操作 | ## Claude Code skill `skills/repomap/` 内置了一个 [Claude Code](https://claude.com/claude-code) skill，可以通过自然语言提示（"generate code map", "扫一下代码结构 / 生成 repomap"）来驱动此 CLI。按照 [skills/README.md](skills/README.md) 进行安装，该 skill 会自动检测 C# / Lua / Go / 混合项目，运行 `python -m coderepomap generate`，并总结结果。 `python -m coderepomap` 和 `repomap` 可以互换使用。 ## 工作原理 ``` Source roots ─► Parser plugin ─► Symbols + References │ ▼ Cross-language resolver │ ▼ PageRank ranker (Symbol.id keyed) │ ▼ L1 / L2 / L3 markdown + meta JSON ``` 这种分层设计使得每一步都是可替换的——添加一种语言只需要实现一个新的 `LanguageParser` 子类；更改排名策略完全不需要改动解析器。 ## 开发 ``` git clone https://github.com/sputnicyoji/coderepomap cd coderepomap python -m venv .venv && .venv/Scripts/activate # PowerShell: .venv\Scripts\Activate.ps1 pip install -e .[csharp,lua,go,tiktoken,dev] pytest tests/ ``` 测试用例位于 `tests/fixtures/` 中（`csharp/`、`lua/`、`go/`、`u3d_mixed/`）。C# 解析器的基准（快照 + 黄金标准 Markdown）固定记录在 `tests/baseline/` 中，对渲染器或生成器的任何修改都必须保持其字节完全一致——如果确实需要重新生成，请查看 `tests/generate_baseline.py`。共有 206 个测试用例，涵盖了各种语言的解析器插件、排名器、跨语言解析器、CLI、打包冒烟测试以及端到端的生成器运行。

标签：SOC Prime, Tree-sitter, 云安全监控, 人工智能, 代码分析, 代码图谱, 凭证管理, 开发工具, 用户模式Hook绕过, 逆向工具, 防御加固, 静态分析