Repo Research

GitHub 仓库深度研究工具，核心目标是从外部项目中获取启发，为用户自己的项目提供可操作的改进建议。

适用范围：本技能适用于研究任何类型的 GitHub 仓库，不仅限于 Claude Skills。可用于研究开源项目、库、框架、工具等。

依赖管理

本技能的核心功能（单仓库/多仓库研究）不需要任何前置技能。

只有使用主题驱动搜索模式时，才需要以下可选依赖：

依赖技能	用途	安装源	必需性
find-skills	按主题搜索 GitHub 上的相关仓库	INLINECODE0	可选

使用说明：

• - 如果您直接提供 GitHub URL，本技能会直接使用现有的单/多仓库研究模式
• 如果您提供主题关键词（如"研究 OCR 相关项目"），本技能会：

1. 首先检测 find-skills 是否已安装
2. 如未安装，会提示您安装后再继续
3. 安装后自动调用 find-skills 进行搜索

---

配置

本技能支持通过配置文件自定义输出目录和其他设置。

配置文件位置

CODEBLOCK0

快速配置

1. 1. 复制示例配置：

CODEBLOCK1

1. 2. 编辑 config.yaml，设置你的输出目录：

CODEBLOCK2

配置项说明

配置项	说明	默认值
INLINECODE4	研究报告输出目录	INLINECODE5
INLINECODE6

报告格式 | markdown | | research.shallow_clone | 使用浅克隆 | true | | security.enabled | 启用安全分析 | true | | security.prompt_analysis | 提示词安全检测 | true |

配置读取逻辑

CODEBLOCK3

默认行为（无配置文件）

如果没有配置文件或 output_dir 为空，将使用默认行为：

• - 输出目录：./research（当前工作目录下的 research 文件夹）
• 报告格式：Markdown
• 安全分析：启用

---

快速开始

CODEBLOCK4

对话中触发：当用户提到"研究一下这个仓库"、"对比分析这些项目"、"对我项目有什么启发"等类似表述时自动激活。

---

配置

配置文件

本技能支持通过配置文件自定义输出目录等设置。

配置文件位置

CODEBLOCK5

配置示例

CODEBLOCK6

环境变量覆盖

配置也可通过环境变量设置（优先级高于配置文件）：

环境变量	说明
INLINECODE16	输出目录
INLINECODE17

报告格式 |
| REPO_RESEARCH_AUTO_OPEN | 是否自动打开 |
| REPO_RESEARCH_CLONE_DEPTH | 克隆深度 |

输出目录结构

CODEBLOCK7

---

工作流程

模式选择

根据输入自动选择研究模式：

输入类型	研究模式	输出
单个 GitHub URL	单仓库深度研究	单仓库分析报告 + 启发建议
多个 GitHub URL

多仓库对比研究 | 对比分析报告 + 共性启发 |
| GitHub URL + 本地路径 | 对比启发模式 | 差异分析 + 改进建议 |
| 主题/关键词 | 主题驱动搜索研究 | 搜索结果 + 多仓库综合分析报告 |

---

主题驱动搜索研究模式

当用户提供主题关键词而非具体 GitHub URL 时，使用此模式。

触发条件

用户表达以下需求时自动激活：

• - "帮我找关于 X 的相关项目"
• "搜索研究一下主题 X"
• "找一些关于 X 的开源项目"
• "主题 X 有什么值得研究的仓库"

工作流程

Step 0: 依赖检查

CODEBLOCK8

对话提示：

"检测到您需要使用主题搜索功能。正在检查依赖..."

Step 1: 使用 find-skills 搜索相关仓库

调用 find-skills 技能进行搜索：

CODEBLOCK9

示例：

• - /find-skills pdf converter - 搜索 PDF 转换相关技能
• INLINECODE21 - 搜索视频转录相关技能
• INLINECODE22 - 搜索 OCR 相关技能

Step 2: 整理搜索结果

从 find-skills 的返回中提取：

1. 1. 仓库名称
2. GitHub URL
3. 简要描述
4. 相关度评分

搜索结果整理格式：

#	仓库名	URL	描述	相关度
1	[name]	[url]	[描述]	⭐⭐⭐⭐⭐
2

[name] | [url] | [描述] | ⭐⭐⭐⭐☆ |

Step 3: 用户确认筛选

对话询问：

"找到 [N] 个相关仓库。请选择要深入研究的项目："

"1. 研究全部 [N] 个仓库"

"2. 选择特定编号（如：1,3,5）"

"3. 只研究前 [K] 个最相关的"

"4. 自定义选择"

根据用户选择确定最终研究列表。

Step 4: 批量克隆与并行分析

4.1 创建研究目录

⚠️ 重要：优先使用配置文件中的 output_dir，如果未配置则使用当前工作目录。

Python 方式（推荐）：

CODEBLOCK10

Bash 方式（向后兼容）：

CODEBLOCK11

4.2 批量克隆

CODEBLOCK12

4.3 并行分析

对每个克隆的仓库执行基础分析（参见"Step 2: 基础分析"）。

Step 5: 生成主题综合报告

使用 assets/topic-research-template.md 作为模板。

报告结构

CODEBLOCK13

Step 6: 会话汇报

CODEBLOCK14

---

原有研究模式

（以下保持原有内容不变...）

Step 1: 准备研究环境

1.0 读取配置文件

⚠️ 重要：首先读取配置文件确定输出目录。

CODEBLOCK15

1.1 创建研究目录

统一目录结构：

CODEBLOCK16

设计原则：无论研究多少个仓库，都保持 ${OUTPUT_DIR}/日期-主题/仓库名/ 的统一结构，便于后续管理和扩展。

命名格式：YYYYMMDD-[topic-slug]

• - topic-slug：主题关键词，用连字符连接，小写
• 示例：20260211-pdf-ocr-comparison、INLINECODE29

主题来源（优先级从高到低）：

1. 1. 用户指定：调用时通过 --topic 参数提供
2. 对话询问：自动询问用户输入简短的主题描述
3. 自动推断：从仓库名称或研究内容推断（备选）

使用 Bash 工具执行：

⚠️ 重要：

1. 1. 首先读取 skills/repo-research/assets/config.yaml 获取 INLINECODE32
2. 如果配置文件不存在或 output_dir 为空，使用默认值 INLINECODE34
3. 路径支持 ~ 展开和相对路径

CODEBLOCK17

对话询问主题：

"请为本次研究提供一个简短的主题描述（用于目录命名，如 pdf-ocr、agent-framework）："

1.2 克隆仓库

⚠️ 重要：无论是单仓库还是多仓库，都统一克隆到子目录中，保持目录结构一致。

CODEBLOCK18

---

Step 2: 基础分析（对每个仓库）

2.1 识别项目类型

特征	项目类型	分析重点
INLINECODE38	Node.js/前端	依赖、脚本、构建配置
INLINECODE39/INLINECODE40

Python | 虚拟环境、依赖管理 | | go.mod | Go | 模块结构、依赖 | | Cargo.toml | Rust | Edition、特性、依赖 | | SKILL.md | Claude Skill | 技能定义、frontmatter |

2.2 核心文件优先阅读

CODEBLOCK19

2.3 项目结构分析

使用 Glob 工具探索：

CODEBLOCK20

2.4 技术栈识别

• - 前端：React/Vue/Svelte/Next.js/Nuxt + 状态管理 + 样式方案
• 后端：Node.js/Python/Go/Rust + 框架 + ORM
• 工具链：Vite/Webpack + Jest/Pytest + ESLint/Prettier

---

Step 3: 多仓库对比分析（多仓库模式）

3.1 对比维度

维度	对比内容	启发点
架构设计	目录结构、模块划分	有哪些组织方式值得借鉴
功能实现

核心功能、API 设计 | 同类功能的不同实现方式 | | 技术选型 | 框架、依赖、工具链 | 为什么选择这些技术 | | 文档质量 | README、注释、API 文档 | 文档写法的差异 | | 代码风格 | 命名、结构、模式 | 哪种风格更清晰 |

3.2 共性提取

识别多个仓库的共同点：

• - 共同的技术选择（如都用 Markdown 作为格式）
• 共同的设计模式（如都用插件架构）
• 共同的问题解决方式

3.3 差异分析

识别关键差异及其原因：

• - 为什么 A 用 Markdown 而 B 用 JSON
• 为什么 A 有测试而 B 没有
• 不同实现方式的优劣

---

Step 4: 本地项目对比（启发模式）

4.1 识别本地项目

对话中询问：

"是否需要与本地项目进行对比？如果有，请提供项目路径（相对或绝对）。"

常见本地项目类型：

• - ./test/de-ai-polish - 本地技能
• INLINECODE45 - 现有技能
• INLINECODE46 - 测试项目

4.2 差异分析框架

分析项	外部仓库	本地项目	差异	启发
目录结构	[描述]	[描述]	[差异点]	[可借鉴之处]
核心功能

[描述] | [描述] | [差异点] | [可补充之处] | | 文档方式 | [描述] | [描述] | [差异点] | [可改进之处] | | 检测规则 | [列举] | [列举] | [差异点] | [可学习之处] |

4.3 启发式问题

在对比时回答以下问题：

1. 1. 功能方面

- 外部仓库有哪些功能是我没有的？ - 我有哪些功能是外部仓库没有的？ - 哪些功能可以整合进来？

1. 2. 架构方面

- 外部仓库的目录结构是否更清晰？ - 模块划分方式是否值得借鉴？ - 配置方式是否更灵活？

1. 3. 实现方面

- 检测规则的组织方式有什么不同？ - 报告生成的格式有什么优劣？ - 用户交互方式有什么可学习之处？

1. 4. 文档方面

- README 的结构是否更易理解？ - 示例是否更丰富？ - API 文档是否更完整？

---

Step 5: 生成报告

5.1 单仓库报告结构

使用 assets/report-template.md 作为模板。

5.2 多仓库对比报告结构

使用 assets/comparison-template.md 作为模板。

5.3 启发式报告结构

CODEBLOCK21

5.4 会话汇报格式

CODEBLOCK22

---

最佳实践

研究策略

1. 1. 启发优先：研究的最终目的是"对我有什么帮助"
2. 对比驱动：通过对比发现差异，通过差异获得启发
3. 具体可操作：启发必须转化为具体的改进建议

启发提炼原则

1. 1. 从差异中学习：不同的实现方式往往有不同的考量
2. 从共性中总结：多个仓库的共同选择往往有其原因
3. 从细节中洞察：小细节可能反映设计理念

---

Resources

assets/

• - report-template.md: 单仓库报告模板
• comparison-template.md: 多仓库对比报告模板
• topic-research-template.md: 主题驱动搜索研究报告模板（新增）

---

高级功能 (v0.4.0)

借鉴 Zread MCP 的实现思路，增强本地分析能力。

1. 代码语义搜索

利用本地已克隆的仓库，进行深度代码搜索。

触发方式

用户表达以下需求时激活：

• - "搜索函数 X"
• "查找类 Y"
• "看看这个项目怎么实现 Z 的"
• 直接使用 --search 参数

使用方法

CODEBLOCK23

内部实现

调用 scripts/search.py 中的 CodeSearcher 类：

• - 使用 Grep 工具进行模式匹配
• 支持多种语言：Python, JavaScript, TypeScript, Go, Rust, Java
• 支持多种模式：function, class, import, doc, pattern

---

2. 深度代码分析

超越基础分析，提供架构和质量层面的深度洞察。

分析类型

类型	描述	触发参数
架构分析	目录结构、模块划分、入口文件、架构模式	INLINECODE52
质量分析

代码统计、注释率、技术债务、潜在问题 | --analyze=quality | | 完整分析 | 包含架构和质量两个维度 | --analyze=full |

使用方法

CODEBLOCK24

内部实现

• - 架构分析器 (scripts/analyzer/architecture.py):

- 目录结构分析 - 入口文件识别 - 模块/包结构识别 - 配置文件检测 - 架构模式检测（MVC、微服务、插件、monorepo）

• - 质量分析器 (scripts/analyzer/quality.py):

- 代码统计（行数、语言分布） - 注释覆盖率分析 - 技术债务检测（TODO、FIXME、deprecated） - 问题检测（硬编码密钥、console.log、大文件）

---

3. 智能问答

利用 Claude Code 的 LLM 能力，回答关于仓库的自然语言问题。

触发方式

用户表达以下需求时激活：

• - "这个项目是做什么的？"
• "如何使用这个项目？"
• "架构是怎样的？"
• "有哪些主要模块？"
• 直接使用 --ask 参数

使用方法

CODEBLOCK25

内部实现

1. 1. 问题分类 (scripts/qa.py 中的 QuestionClassifier):

- 意图识别：overview, architecture, usage, api, dependencies - 实体提取：功能名、组件名、文件名 - 上下文确定：需要读取哪些文件

1. 2. 回答生成:

- 使用 Grep/Glob 搜索相关代码 - 使用 read_file 读取关键文件 - 结合 Claude Code 的 LLM 能力生成自然语言回答

---

4. 组合使用

高级功能可以组合使用，实现更强大的分析能力：

CODEBLOCK26

---

scripts/ 目录结构

CODEBLOCK27

---

安全分析模块 (v0.5.0)

基于 OWASP Agentic AI Top 10 和常见漏洞模式设计，用于识别 skill 中可能存在的恶意代码或安全隐患。

触发方式

CODEBLOCK28

检测能力

类别	检测内容	风险等级
命令执行	INLINECODE60, subprocess, eval(), INLINECODE63	🔴 高
敏感文件访问

读写 ~/.ssh/, ~/.aws/, .env 等 | 🔴 高 | | 网络外泄 | HTTP POST、WebSocket、数据上传 | 🟡 中 | | 代码混淆 | base64.b64decode, chr() 拼接等 | 🔴 高 | | 权限提升 | sudo, chmod 777, 修改 PATH | 🔴 高 | | 硬编码凭证 | API Key、Token、Password | 🔴 高 | | 下载执行 | curl | bash, wget | sh 模式 | 🔴 高 | | 持久化 | crontab, systemd, LaunchAgents | 🟡 中 | | Skill 特有 | 安装钩子、MCP 服务器风险 | 🟡 中 |

风险等级

等级	条件	建议
🔴 critical	存在命令执行、下载执行等	强烈不建议使用，需完整审计
🟠 high

多个高危发现或硬编码凭证 | 审计后使用，限制权限 | | 🟡 medium | 少量中危发现 | 使用前检查，测试环境验证 | | 🟢 low | 仅低危或无发现 | 可安全使用 |

使用示例

CODEBLOCK29

未来计划

• - [ ] 依赖分析模块 (dependency analysis)
• [ ] 性能分析模块 (performance analysis)
• [ ] 更智能的问答系统