AliceLJY/repo-insight

# 仓库 Insight 用于对开源项目进行深度架构分析的 AI 编程 agent 技能。它超越了“使用了哪些技术”，深入回答“为什么这样设计”。 生成包含设计洞察、权衡分析、借鉴价值评估和 Mermaid 图表的专业架构报告。 兼容 [Claude Code](https://claude.ai/claude-code)、[Codex](https://github.com/openai/codex) 以及任何支持技能格式的 AI 编程 agent。当这些工具不可用时，交互式问题和并行子 agent 会优雅降级——参见 SKILL.md 中的“运行环境降级”（运行时降级）部分。 **[中文文档](README.zh.md)**  ## 快速安装 **npx（推荐）** ``` npx skills add AliceLJY/repo-insight ``` **手动（Git Clone + 符号链接）** 该技能位于嵌套的 `skills/repo-insight/` 目录中，因此你可以将代码库 clone 到任意位置，然后将内部目录链接到你的 skills 文件夹中（直接将整个代码库 clone 到 `~/.claude/skills/` 将不起作用 —— Claude Code 要求每个 skill 目录的顶层包含 `SKILL.md`）： ``` # macOS / Linux git clone https://github.com/AliceLJY/repo-insight.git ~/repo-insight ln -s ~/repo-insight/skills/repo-insight ~/.claude/skills/repo-insight # Windows（junction，无需管理员权限） git clone https://github.com/AliceLJY/repo-insight.git %USERPROFILE%\repo-insight mklink /J %USERPROFILE%\.claude\skills\repo-insight %USERPROFILE%\repo-insight\skills\repo-insight ``` **验证**：启动一个新的 Claude Code 会话并运行 `/repo-insight`，或者直接要求 `分析项目 ` —— 该技能应会被激活。 ## 功能 - **Why > What 理念** —— 每一个设计决策都会解释其动机、权衡和替代方案 - **自适应报告结构** —— 没有固定的模板；根据每个项目的特征动态设计章节 - **并行子 agent 分析** —— 启动多个 agent 并发进行模块分析，并带有覆盖率跟踪 - **外部调研** —— 在深入代码之前，进行网络搜索评论 + 爬取官方网站 - **交互式问答** —— 根据项目特征生成有针对性的问题，而非固定的清单 - **质量评分卡** —— 带有评分依据的可视化星级评价卡 - **借鉴价值** —— 明确列出值得学习的、可复用的设计模式和工程实践 - **Mermaid 图表** —— 架构概览、数据流以及各模块的时序图 - **4 个深度级别** —— 从 30 秒快速判断到完整的深度分析 ## 用法 直接要求 Claude Code 分析一个项目： ``` 分析项目 https://github.com/astral-sh/ruff ``` ``` /repo-insight ollama/ollama ``` ``` 对比分析 express vs fastify ``` 该技能支持 `owner/repo` 简写、完整的 GitHub/GitLab/Gitee URL，或本地路径。 ## 分析模式 | 模式 | 核心覆盖率 | 次要覆盖率 | 最适合 | |------|--------------|-------------------|----------| | **快速判断** | 入口 + README | — | 30 秒决定是否继续 | | **快速分析** | >= 30% | >= 10% | 宏观概览 | | **标准**（默认） | >= 60% | >= 30% | 常规架构分析 | | **深度分析** | >= 90% | >= 60% | 研究每一个设计决策 | | **对比** | 不定 | 不定 | 项目之间的横向对比 | ## 工作原理 1. **Clone 与扫描** —— Clone 代码库，按模块统计有效代码行数 2. **规模评估** —— 报告代码库大小，让你选择分析深度 3. **外部调研** —— 网络搜索 + 官网爬取 + 项目文档 4. **自适应问答** —— 基于项目特征生成有针对性的问题 5. **动态报告设计** —— 根据你的回答设计章节结构 6. **并行深度分析** —— 启动子 agent 并发进行模块分析 7. **交叉验证** —— 跨模块的覆盖率检查与结论验证 8. **多源融合** —— 将所有内容合并成一个连贯的叙述，并附带质量评分卡 ## 报告输出 最终报告保存在： ``` ~/repo-analyses/{project-name}-{date}/ANALYSIS_REPORT.md ``` 例外情况：borrowing-audit 模式会写入 `{your_project}/docs/pipeline-audit-{reference-name}.md`，因为其输出属于正在被改进的项目。请注意，`~/repo-analyses/` 默认是一个基于单台机器的本地目录 —— 多机器用户可以将其符号链接到已同步的文件夹（Syncthing、iCloud 等）。工作区仅存储报告；源代码 clone 位于 `~/.cache/repo-insight/` 中，因此同步流量会保持很小。 每份报告包括（根据项目进行调整）： - **问题背景** —— 这解决了什么问题？为什么现有的解决方案不够好？ - **竞争定位** —— 设计理念差异（而非功能清单） - **项目概述** —— 一览架构 - **深度模块分析** —— Why > What，包含权衡和行业对比 - **借鉴价值** —— 可复用的设计模式、工程实践以及需要避免的陷阱 - **质量评分卡** —— 带有评分依据的星级评价卡 - **架构图** —— 贯穿全文的 Mermaid 图表 ## 文件结构 ``` repo-insight/ ├── skills/ │ └── repo-insight/ │ ├── SKILL.md # Main skill definition │ └── references/ │ ├── analysis-guide.md # Analysis philosophy & evaluation framework │ └── module-analysis-guide.md # Module analysis & subagent templates ├── .claude-plugin/ │ └── plugin.json # Plugin metadata ├── package.json # Package manifest ├── README.md # English documentation ├── README.zh.md # Chinese documentation └── LICENSE # MIT License ``` ## 许可证 [MIT](LICENSE)

标签：AI编程助手, Claude Code, 代码分析, 凭证管理, 开源项目分析, 架构分析, 自动化报告