annyeong844/lumin-repo-lens

# Lumin Repo Lens    ## 听起来很熟悉？ 😅 你问 AI： AI 欢快地创建了一个新文件 → `lib/cardNewsService.js` ✨ 但你的仓库在 `lib/cardNews/` 中已经有三个类似的文件了。 😱 有了 `lumin-repo-lens` 的辅助，Claude 可以首先说： 来自你实际仓库的真实证据，而不是猜测。 ## 第一次实用运行 **1. 添加市场并在 Claude Code 中安装插件** ``` /plugin marketplace add annyeong844/lumin-repo-lens /plugin install lumin-repo-lens@annyeong844-marketplace /reload-plugins ``` **2. 运行完整的首次检查** ``` /lumin-repo-lens:full ``` → 这会启用那些让 Lumin 不仅仅是一个死代码导出排序器的部分： 形状索引、函数克隆提示、调用图、桶文件规范、拓扑结构、 公共 API 策略以及基于事实的审查配置。 **3. 在你准备更改代码时使用写入关卡** ``` /lumin-repo-lens:pre-write # code the change /lumin-repo-lens:post-write ``` Claude Code 会在内部推断出简洁的意图。你不需要手动编写 意图 JSON。 对于非常大的仓库，不要在每次编辑时自动触发完整配置。在每个分支、 首次检查或大型重构审查时运行一次 `:full`，然后在 agent 循环期间使用 pre-write、post-write 和快速后续检查。 ## 这适合谁？ ### ✅ 非常适合你，如果你 - 与 AI 一起编写代码，并且**你的仓库变得混乱** - 看着 AI **重写已经存在的函数** - 想要**验证重构后发生了什么变化** - 在 TypeScript / JavaScript（包括 monorepo）中工作 ### ❌ 暂时不适合，如果你 - 主要编写 Python / Rust / 等 *（Go 已部分支持）* - 不使用 AI 编程工具 *（这个工具的存在是为了给你的 AI 提供证据）* - 有一个 1-2 个文件的小型项目 *（审计的价值不会体现出来）* ## 核心命令 | 命令 | 何时使用 | |---|---| | `/lumin-repo-lens:full` | 完整的证据配置 — 首次检查、重构后审查、形状/函数克隆/调用/拓扑证据 | | `/lumin-repo-lens:pre-write` | 在编写代码*之前*检查。自然提问；助手会在内部推断出简洁的意图。 | | `/lumin-repo-lens:post-write` | 在编写代码*之后*验证 — *"我的更改是否影响到了其他地方？"* | | `/lumin-repo-lens` | 快速的基线感知仓库透镜检查，用于对新产物进行小型后续检查 | | `/lumin-repo-lens:refactor-plan` | 将证据转化为谨慎的清理计划 | | `/lumin-repo-lens:welcome` | 获取温和的首次使用菜单 | 维护者还可以使用 `/lumin-repo-lens:canon-draft` 和 `/lumin-repo-lens:check-canon` 进行 canon 生命周期工作。 首次检查、过期或缺失的产物、显式审查、尽职调查、 大型重构规划以及重构后审查应运行 `--profile full`。 在全新基线上的小型后续检查可以使用快速路径。

📦 其他安装选项

### 从克隆的仓库运行打包的 CLI 在生成的 skill 包中，使用公共 wrapper： ``` git clone https://github.com/annyeong844/lumin-repo-lens.git cd lumin-repo-lens node skills/lumin-repo-lens/scripts/audit-repo.mjs --root ``` ### 跳过解析器依赖的自动安装 ``` LUMIN_REPO_LENS_NO_AUTO_INSTALL=1 node skills/lumin-repo-lens/scripts/audit-repo.mjs --root ``` 设置此项后，工具会打印确切的安装命令，而不是直接为你运行。 自动安装命令是 `npm ci --omit=dev --ignore-scripts --no-audit --fund=false`。 稳定的验证模式有 `audit`、`pre-write`、`post-write`、`canon-draft` 和 `check-canon`。 ### Codex 原生安装 Codex 用户可以使用 `$lumin-repo-lens-codex` wrapper，它指向共享引擎。 ``` git clone https://github.com/annyeong844/lumin-repo-lens.git ~/.codex/lumin-repo-lens ``` **macOS / Linux** ``` mkdir -p ~/.codex/skills ln -sfn ~/.codex/lumin-repo-lens/skills/lumin-repo-lens-codex ~/.codex/skills/lumin-repo-lens-codex ln -sfn ~/.codex/lumin-repo-lens/skills/lumin-repo-lens ~/.codex/skills/lumin-repo-lens ln -sfn ~/.codex/lumin-repo-lens/skills/lumin-repo-lens-write-gate ~/.codex/skills/lumin-repo-lens-write-gate ln -sfn ~/.codex/lumin-repo-lens/skills/lumin-repo-lens-canon ~/.codex/skills/lumin-repo-lens-canon ``` **Windows PowerShell** ``` git clone https://github.com/annyeong844/lumin-repo-lens.git "$env:USERPROFILE\.codex\lumin-repo-lens" New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" | Out-Null cmd /c mklink /J "%USERPROFILE%\.codex\skills\lumin-repo-lens-codex" "%USERPROFILE%\.codex\lumin-repo-lens\skills\lumin-repo-lens-codex" cmd /c mklink /J "%USERPROFILE%\.codex\skills\lumin-repo-lens" "%USERPROFILE%\.codex\lumin-repo-lens\skills\lumin-repo-lens" cmd /c mklink /J "%USERPROFILE%\.codex\skills\lumin-repo-lens-write-gate" "%USERPROFILE%\.codex\lumin-repo-lens\skills\lumin-repo-lens-write-gate" cmd /c mklink /J "%USERPROFILE%\.codex\skills\lumin-repo-lens-canon" "%USERPROFILE%\.codex\lumin-repo-lens\skills\lumin-repo-lens-canon" ``` 安装后请重启 Codex。在 Codex 中，从 `$lumin-repo-lens-codex` 开始使用。

⚙️ 这个助手是如何工作的？

该工具**仅扫描你的仓库并收集事实（证据）。** *判断*是你的 AI 在*阅读*这些事实后所做的事情。 ``` Your repo → lumin-repo-lens (cold evidence) → AI buddy explains kindly ↑ ↑ machine human ``` 这种两阶段的分离是有意为之的： - AI **不会用猜测来回答** — 它会引用证据 - 你**不必自己阅读 JSON** — 助手会将其翻译过来 - 当你想要时，你可以**直接检查证据** — 它们存放在 `/.audit/` 中

❓ 常见问题

**Q. 我可以不结合 AI，仅将其作为 CLI 使用吗？** 可以 — 从克隆的仓库中运行 `node skills/lumin-repo-lens/scripts/audit-repo.mjs --root `。它会写入 JSON 证据文件、一份摘要 Markdown，以及一个 Mermaid 拓扑图（当存在拓扑数据时）。Mermaid 文件是一个紧凑的人类可视化辅助工具，用于查看跨子模块的流程、循环和核心文件；精确的引用仍需通过 `topology.json` 进行。 **Q. 为什么它在首次运行时会安装 npm 包？** 为了分析你的仓库，它需要解析器库。它们会被自动安装一次并缓存。可以通过设置 `LUMIN_REPO_LENS_NO_AUTO_INSTALL=1` 来禁用。 **Q. 在我的仓库中创建了什么？** 在 `/.audit/` 下会创建 JSON 证据文件、一份摘要 Markdown 和拓扑 Mermaid 图（如果适用）。如果你不想将它们提交到 Git，请将 `.audit/` 添加到 `.gitignore` 中。 这些产物可能包含仓库结构、文件路径、符号名称和分析元数据。 **Q. 我的仓库很大 — 会不会很慢？** 它的耗时随实际扫描的文件和你选择的证据配置而变化。 小型仓库依然很快，但大型 monorepo 可能需要较长的时间， 如果你只期望看到小型仓库的处理速度，可能会觉得它卡住了。 | 扫描大小 | Quick 配置 | Full 配置 | | --- | --- | --- | | 200-500 个文件 | ~10-20 秒 | ~30 秒-1 分钟 | | 1k-2k 个文件 | ~30-60 秒 | ~1-3 分钟 | | 3k-5k 个文件 | ~1-3 分钟 | 数分钟 | 对于一个 4k+ 文件的 monorepo，快速扫描耗时超过一分钟可能是正常的。 请观察进度条并在假定程序挂起之前检查 `manifest.json`。在首次检查、分支级审查和主要重构证据收集时使用 `:full`；在小型后续检查时使用 quick/pre-write/post-write。 **Q. 主要的证据限制是什么？** 函数克隆提示是审查提示，而不是语义等价的声明。它们包括精确函数体、相同结构、相同签名和近似函数的证据，前提是完整配置中包含 `function-clones.json`。形状索引是精确的：例如 `email: string` 与 `email: string | null` 这样的可空或宽泛类型会被有意分到不同的组中。请从 `audit-summary.latest.md`、`manifest.json` 和 `checklist-facts.json` 开始阅读，仅在需要引用具体的声明时才打开原始的 JSON 产物。 **Q. pre-write 能理解语义重复吗？** 不能。pre-write 不会仅凭名称就断言语义等价。它会揭示基于事实的依据，如精确的符号/文件匹配、精确的形状哈希以及精确的函数签名哈希，然后将较弱的 agent 审查提示与被静音的 token 噪音区分开来。 精确的标准化函数体哈希提示将被推迟，直到在查找产物中存在 body-hash lane。当两个辅助函数仅共享一个常见的动词（如 `create`）时，默认的聊天界面会保持安静，而被静音的提示会保留在 JSON 诊断信息中。 **Q. 为什么 post-write 感觉和 quick 扫描一样耗时？** post-write 在将其与匹配的 pre-write 建议进行比较之前，会刷新“更改后”的快照，因此即使是小规模的编辑也可能需要支付遍历整个仓库的成本。重用相同的 `--output` 会将产物集中存放；增量式的 post-write 缓存已在计划中，但目前默认的处理方式是宁可生成全新的对比结果，也不提供过期的干净结果。 **Q. 它自己会调用模型或 subagent 吗？** 不会。Full 和 CI 配置可能会写入 `audit-review-pack.latest.md`，但该文件本身不会调用任何模型或 API。在 Claude Code 中，主助手可以将一个 lane 转化为聚焦的代码库阅读任务。subagent 应该直接检查仓库文件并报告 file:line 级别的证据。

🔧 维护者 / 构建 / 贡献

本节面向检出代码的维护者。如果你是通过插件安装或使用已发布的包，则不需要阅读此处。 ### 构建可部署包 ``` npm run build:plugin # writes dist/lumin-repo-lens-plugin/ (Claude Code plugin root) npm run build:skill # writes the skill-only directory shape ``` ### 维护者检查 skill 触发测试套件仅供维护者使用。 ``` npm run ci # full check pass npm run check:skill-triggering # offline prompt/expectation lint npm run check:behavior # offline answer-level regression check ./test-harness/run-all.sh # live trigger sweeps (requires Claude CLI; opt-in) ``` ### 维护者仓库结构图 - `docs/README.md` — 入口文件 - `docs/product-surface.md` — 用户可见的内容 - `docs/internal-engine.md` — 引擎的内部构造 - `docs/history/README.md`、`docs/spec/README.md`、`docs/lab/README.md` — 阶段历史、规格说明、实验 实验输出（`canonical-draft/`、`output/`、`review-output*/`、`p6-corpus/`、`audit-artifacts/`、`.audit/`、`.claude/`）仅供维护者使用，不属于可部署的 skill 包。 根目录下的同级脚本是内部引擎的入口点。故意不作为首选的用户界面；请从插件命令或 `skills/lumin-repo-lens/scripts/audit-repo.mjs` 开始使用。 ### 保守的证据边界 函数克隆提示是审查提示，而非语义等价的证明；相同签名的分组意味着“相同的导出函数类型契约”，而不是“相同的行为”。形状索引匹配是精确的（`string` 和 `string | null` 字段会被有意分到不同的组中）。有关保持死代码、形状和 barrel 声明基于事实的操作关卡，请参阅 `references/false-positive-index.md` 和 `references/operational-gates.md`。 ### 公测版 Claude Code 市场包在稳定的 `1.0.0` 版本线发布前处于公测阶段。预计会有偶尔的清理提交。引擎和插件接口目前已可正常使用。

## 仓库 / 许可证 - 仓库：[github.com/annyeong844/lumin-repo-lens](https://github.com/annyeong844/lumin-repo-lens) - 许可证：[MIT](./LICENSE) - Bug / 建议：[Issues](https://github.com/annyeong844/lumin-repo-lens/issues)

标签：AI辅助编程, Claude插件, CMS安全, JavaScript, LLM工具, MITM代理, SEO检索词, TypeScript, VS Code, WebSocket, 云安全监控, 仓库结构, 代码审查, 代码结构分析, 代码规范, 代码质量管理, 依赖分析, 函数克隆检测, 威胁情报, 安全插件, 开发者工具, 数据可视化, 自定义脚本, 调用图, 重构工具, 静态分析