Skill: cat-xierluo/repo-research (version 0.7.0)

--- name: repo-research homepage: https://github.com/cat-xierluo/legal-skills author: 杨卫薪律师（微信ywxlaw） version: "0.7.0" license: MIT description: GitHub 仓库深度研究与整合分析工具。支持单个/多个仓库研究、与本地项目对比分析、启发式整合建议。支持主题驱动搜索模式：自动搜索相关仓库、克隆、分析并生成报告。克隆远程仓库到本地 research/ 目录，进行深度代码分析、架构评估、依赖解析，并生成结构化研究报告。触发条件：用户提供 GitHub URL 请求研究/分析/整合/对比时，或提供主题关键词请求搜索并研究相关仓库时。 --- # Repo Research GitHub 仓库深度研究工具，核心目标是从**外部项目中获取启发**，为用户自己的项目提供可操作的改进建议。 > **适用范围**：本技能适用于研究任何类型的 GitHub 仓库，不仅限于 Claude Skills。可用于研究开源项目、库、框架、工具等。 ## 依赖管理 本技能的核心功能（单仓库/多仓库研究）**不需要**任何前置技能。 只有使用**主题驱动搜索模式**时，才需要以下可选依赖： | 依赖技能 | 用途 | 安装源 | 必需性 | |:---------|:-----|:-------|:-------| | **find-skills** | 按主题搜索 GitHub 上的相关仓库 | `https://skills.sh/vercel-labs/skills/find-skills` | 可选 | **使用说明**： - 如果您直接提供 GitHub URL，本技能会直接使用现有的单/多仓库研究模式 - 如果您提供主题关键词（如"研究 OCR 相关项目"），本技能会： 1. 首先检测 `find-skills` 是否已安装 2. 如未安装，会提示您安装后再继续 3. 安装后自动调用 `find-skills` 进行搜索 --- ## 配置 本技能支持通过配置文件自定义输出目录和其他设置。 ### 配置文件位置 ``` skills/repo-research/assets/config.yaml ``` ### 快速配置 1. 复制示例配置： ```bash cp skills/repo-research/assets/config.example.yaml skills/repo-research/assets/config.yaml ``` 2. 编辑 `config.yaml`，设置你的输出目录： ```yaml research: output_dir: "~/Documents/研究笔记" # 支持绝对路径、相对路径、~ 展开 ``` ### 配置项说明 | 配置项 | 说明 | 默认值 | |:-------|:-----|:-------| | `research.output_dir` | 研究报告输出目录 | `./research` | | `research.report_format` | 报告格式 | `markdown` | | `research.shallow_clone` | 使用浅克隆 | `true` | | `security.enabled` | 启用安全分析 | `true` | | `security.prompt_analysis` | 提示词安全检测 | `true` | ### 配置读取逻辑 ``` 1. 检查 skills/repo-research/assets/config.yaml 是否存在 2. 如果存在，读取配置 3. 如果 output_dir 为空或不存在，使用默认值 ./research 4. 支持路径展开： - `~` 展开为用户目录 - 相对路径基于当前工作目录 ``` ### 默认行为（无配置文件） 如果没有配置文件或 `output_dir` 为空，将使用默认行为： - **输出目录**：`./research`（当前工作目录下的 research 文件夹） - **报告格式**：Markdown - **安全分析**：启用 --- ## 快速开始 ```bash # 单个仓库研究 /repo-research https://github.com/user/repo # 多仓库对比研究 /repo-research https://github.com/user/repo-a https://github.com/user/repo-b # 指定分析重点 /repo-research https://github.com/user/repo --focus=architecture # 与现有技能整合 /repo-research https://github.com/user/repo --integrate-with=de-ai-polish ``` **对话中触发**：当用户提到"研究一下这个仓库"、"对比分析这些项目"、"对我项目有什么启发"等类似表述时自动激活。 --- ## 配置 ### 配置文件 本技能支持通过配置文件自定义输出目录等设置。 #### 配置文件位置 ``` ~/.openclaw/skills/repo-research/assets/config.yaml ``` #### 配置示例 ```yaml # 研究报告输出目录 # 支持绝对路径、相对路径和 ~ 展开 output_dir: "/Users/yourname/Desktop/Clawd/99 - 🦐 大虾研究/09 - 📋 研究报告" # 报告格式：markdown 或 json report_format: markdown # 是否自动打开报告（生成后） auto_open_report: false # 克隆深度：1 = 浅克隆（更快），0 = 完整克隆 clone_depth: 1 ``` #### 环境变量覆盖 配置也可通过环境变量设置（优先级高于配置文件）： | 环境变量 | 说明 | |:---------|:-----| | `REPO_RESEARCH_OUTPUT_DIR` | 输出目录 | | `REPO_RESEARCH_FORMAT` | 报告格式 | | `REPO_RESEARCH_AUTO_OPEN` | 是否自动打开 | | `REPO_RESEARCH_CLONE_DEPTH` | 克隆深度 | #### 输出目录结构 ``` output_dir/ └── research/ └── YYYYMMDD-topic-slug/ ├── repo-name/ # 克隆的仓库 ├── repo-name-2/ # 多仓库时有多个 └── topic-slug-report.md # 研究报告（如：twitter-skills-report.md） ``` --- ## 工作流程 ### 模式选择 根据输入自动选择研究模式： | 输入类型 | 研究模式 | 输出 | |:---------|:---------|:-----| | 单个 GitHub URL | **单仓库深度研究** | 单仓库分析报告 + 启发建议 | | 多个 GitHub URL | **多仓库对比研究** | 对比分析报告 + 共性启发 | | GitHub URL + 本地路径 | **对比启发模式** | 差异分析 + 改进建议 | | 主题/关键词 | **主题驱动搜索研究** | 搜索结果 + 多仓库综合分析报告 | --- ## 主题驱动搜索研究模式 当用户提供主题关键词而非具体 GitHub URL 时，使用此模式。 ### 触发条件 用户表达以下需求时自动激活： - "帮我找关于 X 的相关项目" - "搜索研究一下主题 X" - "找一些关于 X 的开源项目" - "主题 X 有什么值得研究的仓库" ### 工作流程 #### Step 0: 依赖检查 ```bash # 检查 find-skills 是否已安装 if ! /find-skills --help >/dev/null 2>&1; then echo "⚠️ 主题驱动搜索模式需要 find-skills 技能" echo "正在为您安装..." /skill-manager install https://skills.sh/vercel-labs/skills/find-skills fi ``` **对话提示**： > "检测到您需要使用主题搜索功能。正在检查依赖..." #### Step 1: 使用 find-skills 搜索相关仓库 调用 find-skills 技能进行搜索： ```bash /find-skills <主题关键词> ``` 示例： - `/find-skills pdf converter` - 搜索 PDF 转换相关技能 - `/find-skills video transcription` - 搜索视频转录相关技能 - `/find-skills ocr` - 搜索 OCR 相关技能 #### Step 2: 整理搜索结果 从 find-skills 的返回中提取： 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 方式（推荐）**： ```python from scripts.config import get_research_dir # 自动读取配置文件，返回研究目录路径 RESEARCH_DIR = get_research_dir(topic_slug) ``` **Bash 方式（向后兼容）**： ```bash # 优先使用配置文件中的 output_dir，否则使用当前目录 SKILL_DIR="$HOME/.openclaw/skills/repo-research" CONFIG_FILE="$SKILL_DIR/assets/config.yaml" # 尝试从配置文件读取 output_dir if [ -f "$CONFIG_FILE" ] && command -v python3 &> /dev/null; then OUTPUT_DIR=$(python3 -c " from pathlib import Path import sys sys.path.insert(0, '$SKILL_DIR/scripts') from config import get_output_dir print(get_output_dir()) " 2>/dev/null) else OUTPUT_DIR="${PWD}" fi RESEARCH_DATE=$(date +%Y%m%d) # 将主题转换为 slug 格式（小写、空格替换为连字符） TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-') # 使用绝对路径确保在正确位置 RESEARCH_DIR="${OUTPUT_DIR}/research/${RESEARCH_DATE}-${TOPIC_SLUG}" mkdir -p "${RESEARCH_DIR}" cd "${RESEARCH_DIR}" ``` ##### 4.2 批量克隆 ```bash for url in "${SELECTED_URLS[@]}"; do repo_name=$(basename "$url" .git) echo "正在克隆: $repo_name" git clone --depth 1 "$url" "$repo_name" done ``` ##### 4.3 并行分析 对每个克隆的仓库执行基础分析（参见"Step 2: 基础分析"）。 #### Step 5: 生成主题综合报告 使用 `assets/topic-research-template.md` 作为模板。 ##### 报告结构 ```markdown # [主题] 综合研究报告 > **研究日期**：YYYY-MM-DD > **搜索主题**：[主题关键词] > **研究仓库数**：[N] 个 > **报告路径**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md` --- ## 执行摘要 ### 研究概述 [用一段话概括：基于主题搜索了哪些类型的仓库，主要发现了什么] ### 一句话总结 [用一句话概括最关键的发现] ### 核心指标 | 指标 | 数值 | |:-----|:-----| | 搜索结果总数 | [N] 个仓库 | | 深度研究数量 | [M] 个仓库 | | 相关技术栈 | [列举主要技术] | | 活跃项目占比 | [X%] | --- ## 搜索结果概览 ### 仓库清单 | # | 仓库名 | 描述 | 语言 | Stars | 活跃度 | |:-|:-------|:-----|:-----|:-----|:-------| | 1 | [name] | [描述] | [lang] | [★] | 🟢 活跃 | | 2 | [name] | [描述] | [lang] | [★] | 🟡 中等 | ### 分类汇总 **按技术类型**： - [技术1]: [数量] 个项目 - [技术2]: [数量] 个项目 **按功能类型**： - [功能1]: [数量] 个项目 - [功能2]: [数量] 个项目 --- ## 技术栈分析 ### 主流技术选择 | 技术 | 使用项目数 | 占比 | 代表项目 | |:-----|-----------|:-----|:---------| | [技术1] | [N] | [X%] | [项目A, 项目B] | | [技术2] | [N] | [X%] | [项目C] | ### 技术趋势洞察 - **趋势1**：[描述观察到的技术趋势] - **趋势2**：[描述观察到的技术趋势] --- ## 共性模式识别 ### 架构共性 多个项目共同采用的架构模式： 1. **[模式名称]**：[描述] - 采用项目：[列举] - 优势分析：[分析] ### 功能共性 多个项目都实现的核心功能： 1. **[功能名称]**：[描述] - 实现方式差异：[对比] ### 文档共性 文档编写的共同特点： - [观察到的文档模式] --- ## 项目对比分析 ### 功能对比矩阵 | 功能 | 项目1 | 项目2 | 项目3 | 最优实现 | |:-----|:-----|:-----|:-----|:---------| | [功能1] | ✅ | ✅ | ❌ | [分析] | | [功能2] | ✅ | ❌ | ✅ | [分析] | ### 架构对比 | 维度 | 项目1 | 项目2 | 项目3 | 值得学习 | |:-----|:-----|:-----|:-----|:---------| | 目录结构 | [描述] | [描述] | [描述] | [推荐] | | 模块化 | [描述] | [描述] | [描述] | [推荐] | ### 代码质量对比 | 项目 | 代码组织 | 文档 | 测试 | 综合评分 | |:-----|:---------|:-----|:-----|:---------| | 项目1 | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | ⭐⭐☆☆☆ | B+ | | 项目2 | ⭐⭐⭐☆☆ | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | B | --- ## 深度剖析（精选项目） ### 项目 A: [仓库名] #### 为什么值得深入研究 [说明选择这个项目进行深度剖析的原因] #### 架构亮点 - [亮点1] - [亮点2] #### 可借鉴的设计 1. **[设计点1]**：[描述可借鉴之处] 2. **[设计点2]**：[描述可借鉴之处] ### 项目 B: [仓库名] [同上结构] --- ## 启发与建议 ### 对本地项目的启发 #### 可直接借鉴 1. **[方面1]** - **来源**：[项目A/项目B] - **做法**：[描述具体做法] - **本地应用**：[如何应用到本地项目] - **优先级**：🔴 高 / 🟡 中 / 🟢 低 - **预计工作量**：[X 小时] #### 需要进一步探索 1. **[技术/模式]** - **为什么**：[说明价值] - **调研方式**：[如何调研] - **预期收益**：[说明] ### 最佳实践总结 从多个项目中提炼的最佳实践： 1. **[实践1]**：[描述] 2. **[实践2]**：[描述] --- ## 项目推荐 ### 不同场景推荐 | 场景 | 推荐项目 | 理由 | |:-----|:---------|:-----| | 学习参考 | [项目名] | [理由] | | 生产使用 | [项目名] | [理由] | | 二次开发 | [项目名] | [理由] | | 特定需求 | [项目名] | [理由] | ### 快速决策指南 - **如果你需要 X** → 推荐 [项目A] - **如果你需要 Y** → 推荐 [项目B] - **如果你需要 Z** → 推荐 [项目C] --- ## 附录 ### 完整仓库列表 #### 深度研究的项目 1. **[项目名]** - [GitHub URL] - 描述：[描述] - 技术栈：[列举] - 最后更新：[日期] #### 仅浏览的项目 1. **[项目名]** - [GitHub URL] - 相关度：⭐⭐☆☆☆ ### 参考资源 - [相关文档链接] - [相关文章链接] --- **报告生成时间**：YYYY-MM-DD HH:MM **研究者**：Claude Code + repo-research skill **搜索工具**：find-skills skill ``` #### Step 6: 会话汇报 ```markdown ## 主题研究完成 **搜索主题**：[主题关键词] **搜索结果**：找到 [N] 个相关仓库，深度分析了 [M] 个 **核心发现**： 1. [发现1] 2. [发现2] 3. [发现3] **推荐项目**： - 学习参考：[项目A] - 生产使用：[项目B] **详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md` ``` --- ## 原有研究模式 （以下保持原有内容不变...） ### Step 1: 准备研究环境 #### 1.0 读取配置文件 **⚠️ 重要**：首先读取配置文件确定输出目录。 ```python # 读取配置文件逻辑（在开始研究前执行） import yaml from pathlib import Path def get_output_dir(): """获取输出目录，优先使用配置文件中的设置""" # 默认输出目录 default_output = "./research" # 配置文件路径 skill_dir = Path(__file__).parent # skill 所在目录 config_path = skill_dir / "assets" / "config.yaml" if not config_path.exists(): return default_output try: with open(config_path, 'r', encoding='utf-8') as f: config = yaml.safe_load(f) output_dir = config.get('research', {}).get('output_dir', '') if not output_dir or output_dir.strip() == '': return default_output # 展开 ~ 和环境变量 output_dir = Path(output_dir).expanduser() # 如果是相对路径，基于当前工作目录 if not output_dir.is_absolute(): output_dir = Path.cwd() / output_dir return str(output_dir) except Exception: return default_output ``` #### 1.1 创建研究目录 **统一目录结构**： ```bash research/ └── YYYYMMDD-[topic]/ # 日期+主题目录 ├── repo-name/ # 研究的仓库（即使是单个仓库也在子目录中） ├── repo-b/ # 多仓库时会有多个子目录 └── [topic-slug]-report.md # 研究报告 # 单仓库示例： # ~/Documents/研究笔记/20260213-vibe-working-tutorial/ # └── vibe-working-tutorial/ <- 仓库内容 # └── [topic-slug]-report.md # 多仓库示例： # ./research/20260213-pdf-tools-comparison/ # ├── pdf-lib/ # └── pdfkit/ # └── [topic-slug]-report.md ``` > **设计原则**：无论研究多少个仓库，都保持 `${OUTPUT_DIR}/日期-主题/仓库名/` 的统一结构，便于后续管理和扩展。 **命名格式**：`YYYYMMDD-[topic-slug]` - `topic-slug`：主题关键词，用连字符连接，小写 - 示例：`20260211-pdf-ocr-comparison`、`20260212-transcription-study` **主题来源**（优先级从高到低）： 1. **用户指定**：调用时通过 `--topic` 参数提供 2. **对话询问**：自动询问用户输入简短的主题描述 3. **自动推断**：从仓库名称或研究内容推断（备选） 使用 Bash 工具执行： **⚠️ 重要**： 1. 首先读取 `skills/repo-research/assets/config.yaml` 获取 `output_dir` 2. 如果配置文件不存在或 `output_dir` 为空，使用默认值 `./research` 3. 路径支持 `~` 展开和相对路径 ```bash # Step 1: 读取配置文件获取输出目录 # 默认输出目录 OUTPUT_DIR="./research" # 检查配置文件是否存在 CONFIG_FILE="skills/repo-research/assets/config.yaml" if [ -f "$CONFIG_FILE" ]; then # 使用 grep 简单提取 output_dir（避免依赖 Python/yaml） CONFIG_OUTPUT=$(grep -E "^\s*output_dir:" "$CONFIG_FILE" | head -1 | sed 's/.*output_dir:[[:space:]]*//') # 移除引号 CONFIG_OUTPUT=$(echo "$CONFIG_OUTPUT" | tr -d "\"'") # 如果非空，使用配置值 if [ -n "$CONFIG_OUTPUT" ] && [ "$CONFIG_OUTPUT" != '""' ]; then # 展开 ~ 为用户目录 OUTPUT_DIR="${CONFIG_OUTPUT/#\~/$HOME}" fi fi # Step 2: 如果是相对路径，基于当前工作目录 if [[ "$OUTPUT_DIR" != /* ]]; then OUTPUT_DIR="${PWD}/${OUTPUT_DIR}" fi # Step 3: 创建研究目录 REPO_DATE=$(date +%Y%m%d) TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-') RESEARCH_DIR="${OUTPUT_DIR}/${REPO_DATE}-${TOPIC_SLUG}" mkdir -p "${RESEARCH_DIR}" cd "${RESEARCH_DIR}" echo "研究目录已创建: ${RESEARCH_DIR}" ``` **对话询问主题**： > "请为本次研究提供一个简短的主题描述（用于目录命名，如 `pdf-ocr`、`agent-framework`）：" #### 1.2 克隆仓库 **⚠️ 重要**：无论是单仓库还是多仓库，都统一克隆到子目录中，保持目录结构一致。 ```bash # 统一方式：所有仓库都克隆到子目录 # 这样可以保持 research/日期-主题/ 目录结构的一致性 # 单仓库和多仓库的区别只在于克隆的次数 for url in "${URLS[@]}"; do repo_name=$(basename "$url" .git) git clone --depth 1 "$url" "$repo_name" done # 单仓库示例（实际也是克隆到子目录）： # research/20260213-vibe-working-tutorial/ # └── vibe-working-tutorial/ <- 仓库内容 # └── [topic-slug]-report.md <- 研究报告 # 多仓库示例： # research/20260213-pdf-tools-comparison/ # └── pdf-lib/ <- 仓库A # └── pdfkit/ <- 仓库B # └── [topic-slug]-report.md <- 研究报告 ``` --- ### Step 2: 基础分析（对每个仓库） #### 2.1 识别项目类型 | 特征 | 项目类型 | 分析重点 | |:-----|:---------|:---------| | `package.json` | Node.js/前端 | 依赖、脚本、构建配置 | | `requirements.txt`/`pyproject.toml` | Python | 虚拟环境、依赖管理 | | `go.mod` | Go | 模块结构、依赖 | | `Cargo.toml` | Rust | Edition、特性、依赖 | | `SKILL.md` | Claude Skill | 技能定义、frontmatter | #### 2.2 核心文件优先阅读 ```bash # 必读文件（按优先级） README.md # 项目说明、快速开始 LICENSE # 许可证 package.json/pyproject.toml/go.mod # 依赖元数据 ``` #### 2.3 项目结构分析 使用 Glob 工具探索： ```bash glob "**/*" # 所有文件 glob "**/*.md" # 文档 glob "src/**/*.ts" # 源代码 glob "tests/**/*" # 测试 ``` #### 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` - 本地技能 - `./skills/xxx` - 现有技能 - `./test/yyy` - 测试项目 #### 4.2 差异分析框架 | 分析项 | 外部仓库 | 本地项目 | 差异 | 启发 | |:-------|:---------|:---------|:-----|:-----| | **目录结构** | [描述] | [描述] | [差异点] | [可借鉴之处] | | **核心功能** | [描述] | [描述] | [差异点] | [可补充之处] | | **文档方式** | [描述] | [描述] | [差异点] | [可改进之处] | | **检测规则** | [列举] | [列举] | [差异点] | [可学习之处] | #### 4.3 启发式问题 在对比时回答以下问题： 1. **功能方面** - 外部仓库有哪些功能是我没有的？ - 我有哪些功能是外部仓库没有的？ - 哪些功能可以整合进来？ 2. **架构方面** - 外部仓库的目录结构是否更清晰？ - 模块划分方式是否值得借鉴？ - 配置方式是否更灵活？ 3. **实现方面** - 检测规则的组织方式有什么不同？ - 报告生成的格式有什么优劣？ - 用户交互方式有什么可学习之处？ 4. **文档方面** - README 的结构是否更易理解？ - 示例是否更丰富？ - API 文档是否更完整？ --- ### Step 5: 生成报告 #### 5.1 单仓库报告结构 使用 `assets/report-template.md` 作为模板。 #### 5.2 多仓库对比报告结构 使用 `assets/comparison-template.md` 作为模板。 #### 5.3 启发式报告结构 ```markdown # [研究主题] 启发式分析报告 > 研究日期：YYYY-MM-DD > 研究仓库：[列出所有仓库] > 对比项目：[本地项目路径] > 报告路径：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md` --- ## 核心发现 ### 一句话总结 [用一句话概括最关键的启发] --- ## 对比分析 ### 功能对比 | 功能 | 仓库A | 仓库B | 本地项目 | 启发 | |:-----|:------|:------|:---------|:-----| | [功能1] | ✅ | ✅ | ❌ | [建议] | | [功能2] | ✅ | ❌ | ✅ | [分析] | ### 架构对比 | 维度 | 仓库A | 仓库B | 本地项目 | 启发 | |:-----|:------|:------|:---------|:-----| | 目录结构 | [描述] | [描述] | [描述] | [建议] | | 模块划分 | [描述] | [描述] | [描述] | [建议] | ### 规则/检测方式对比 | 检测项 | 仓库A | 仓库B | 本地项目 | 启发 | |:-------|:------|:------|:---------|:-----| | [规则1] | [实现] | [实现] | [实现] | [可学习] | --- ## 具体启发 ### 可直接借鉴的方面 1. **[方面1]** - **外部做法**：[描述] - **本地现状**：[描述] - **改进建议**：[具体建议] - **优先级**：高/中/低 2. **[方面2]** - **外部做法**：[描述] - **本地现状**：[描述] - **改进建议**：[具体建议] - **优先级**：高/中/低 ### 需要进一步探索的方面 1. **[方面1]**：[为什么值得探索] 2. **[方面2]**：[为什么值得探索] --- ## 行动建议 ### 立即可做的改进 - [ ] [改进1] - 预计时间：[X小时] - [ ] [改进2] - 预计时间：[X小时] ### 需要进一步调研的 - [ ] [调研项1] - 调研方式：[如何调研] - [ ] [调研项2] - 调研方式：[如何调研] --- ## 附录 ### 仓库详细信息 - **仓库A**：[名称](URL) - [一句话描述] - **仓库B**：[名称](URL) - [一句话描述] ### 参考链接 - [相关文档] - [相关文章] ``` #### 5.4 会话汇报格式 ```markdown ## 研究完成 **研究仓库**： - [仓库名A]：[一句话描述] - [仓库名B]：[一句话描述] **对比项目**：[本地项目路径] **核心启发**： 1. [启发1] 2. [启发2] 3. [启发3] **立即可做的改进**： - [ ] [改进1] - [ ] [改进2] **详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md` ``` --- ## 最佳实践 ### 研究策略 1. **启发优先**：研究的最终目的是"对我有什么帮助" 2. **对比驱动**：通过对比发现差异，通过差异获得启发 3. **具体可操作**：启发必须转化为具体的改进建议 ### 启发提炼原则 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` 参数 #### 使用方法 ```bash # 搜索函数定义 /repo-research https://github.com/user/repo --search="function:parse*" # 搜索类定义 /repo-research https://github.com/user/repo --search="class:*Handler" # 搜索导入 /repo-research https://github.com/user/repo --search="import:react" # 搜索特定模式 /repo-research https://github.com/user/repo --search="pattern:console\.log" ``` #### 内部实现 调用 `scripts/search.py` 中的 `CodeSearcher` 类： - 使用 Grep 工具进行模式匹配 - 支持多种语言：Python, JavaScript, TypeScript, Go, Rust, Java - 支持多种模式：function, class, import, doc, pattern --- ### 2. 深度代码分析 超越基础分析，提供架构和质量层面的深度洞察。 #### 分析类型 | 类型 | 描述 | 触发参数 | |:-----|:-----|:---------| | **架构分析** | 目录结构、模块划分、入口文件、架构模式 | `--analyze=architecture` | | **质量分析** | 代码统计、注释率、技术债务、潜在问题 | `--analyze=quality` | | **完整分析** | 包含架构和质量两个维度 | `--analyze=full` | #### 使用方法 ```bash # 架构分析 /repo-research https://github.com/user/repo --analyze=architecture # 质量分析 /repo-research https://github.com/user/repo --analyze=quality # 完整分析 /repo-research https://github.com/user/repo --analyze=full ``` #### 内部实现 - **架构分析器** (`scripts/analyzer/architecture.py`): - 目录结构分析 - 入口文件识别 - 模块/包结构识别 - 配置文件检测 - 架构模式检测（MVC、微服务、插件、monorepo） - **质量分析器** (`scripts/analyzer/quality.py`): - 代码统计（行数、语言分布） - 注释覆盖率分析 - 技术债务检测（TODO、FIXME、deprecated） - 问题检测（硬编码密钥、console.log、大文件） --- ### 3. 智能问答 利用 Claude Code 的 LLM 能力，回答关于仓库的自然语言问题。 #### 触发方式 用户表达以下需求时激活： - "这个项目是做什么的？" - "如何使用这个项目？" - "架构是怎样的？" - "有哪些主要模块？" - 直接使用 `--ask` 参数 #### 使用方法 ```bash # 询问项目概述 /repo-research https://github.com/user/repo --ask="这个项目是做什么的？" # 询问使用方法 /repo-research https://github.com/user/repo --ask="如何使用这个项目？" # 询问架构 /repo-research https://github.com/user/repo --ask="架构是怎样的？" ``` #### 内部实现 1. **问题分类** (`scripts/qa.py` 中的 `QuestionClassifier`): - 意图识别：overview, architecture, usage, api, dependencies - 实体提取：功能名、组件名、文件名 - 上下文确定：需要读取哪些文件 2. **回答生成**: - 使用 Grep/Glob 搜索相关代码 - 使用 read_file 读取关键文件 - 结合 Claude Code 的 LLM 能力生成自然语言回答 --- ### 4. 组合使用 高级功能可以组合使用，实现更强大的分析能力： ```bash # 搜索 + 分析 /repo-research https://github.com/user/repo --search="function:parse*" --analyze=architecture # 问答 + 报告 /repo-research https://github.com/user/repo --ask="这个项目如何使用？" --output=report ``` --- ### scripts/ 目录结构 ``` scripts/ ├── __init__.py # 模块导出 ├── search.py # 语义搜索 ├── qa.py # 智能问答 ├── architecture.py # 架构分析 ├── quality.py # 质量分析 └── security.py # 安全分析 (v0.5.0 新增) ``` --- ## 安全分析模块 (v0.5.0) 基于 OWASP Agentic AI Top 10 和常见漏洞模式设计，用于识别 skill 中可能存在的恶意代码或安全隐患。 ### 触发方式 ```bash # 安全分析模式 /repo-research https://github.com/user/skill --analyze=security # 完整分析（包含安全） /repo-research https://github.com/user/skill --analyze=full ``` ### 检测能力 | 类别 | 检测内容 | 风险等级 | |:-----|:---------|:---------| | **命令执行** | `os.system`, `subprocess`, `eval()`, `exec()` | 🔴 高 | | **敏感文件访问** | 读写 `~/.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** | 仅低危或无发现 | 可安全使用 | ### 使用示例 ```bash # 分析一个 skill 的安全性 /repo-research https://github.com/example/skill --analyze=security # 在研究报告对话框中，会自动包含安全分析章节 # 如果检测到高风险，会有明显的警告提示 ``` ### 未来计划 - [ ] 依赖分析模块 (dependency analysis) - [ ] 性能分析模块 (performance analysis) - [ ] 更智能的问答系统

path: CHANGELOG.md
content: # 变更日志

## [0.7.0] - 2026-02-21

### 新增功能

- **配置文件支持**: 支持通过 YAML 配置文件自定义输出目录和其他设置
  - 新增 `assets/config.example.yaml` 示例配置文件
  - 支持 `output_dir` 自定义输出目录
  - 支持 `~` 展开、相对路径、绝对路径
  - 配置文件不存在或 `output_dir` 为空时使用默认值 `./research`

### 改进优化

- SKILL.md 添加"配置"章节，说明配置文件使用方法
- 工作流程 Step 1 增加配置读取逻辑
- 报告和目录结构支持自定义输出位置

### 文件变更

- 新增: `assets/config.example.yaml` - 配置文件示例
- 更新: `SKILL.md` - 添加配置章节和工作流程更新

---

## [0.6.0] - 2026-02-21

### 新增功能

- **提示词安全检测**: 专门针对 SKILL.md 和 Markdown 文件的安全分析
  - 检测 9 类提示词安全风险
  - **提示注入**: ignore instructions、DAN mode、jailbreak 等越狱尝试
  - **数据收集指令**: collect password、send to external、exfiltrate 等
  - **执行指令**: execute shell、download and run 等隐藏执行逻辑
  - **权限提升指令**: run with sudo、grant root access 等
  - **欺骗性描述**: harmless tool、for educational only 等可疑描述
  - **网络通信指令**: phone home、reverse shell、beacon 等外泄指令
  - **持久化指令**: cron job、startup、auto-run 等驻留机制
  - **隐藏指令**: 控制字符、Unicode 转义、零宽字符等
  - **社会工程学**: urgent update、verify account 等欺骗模式

### 改进优化

- 报告模板增加"提示词安全分析"章节
- 提示词发现与代码发现统一汇总到风险等级计算
- 所有 Markdown 文件均纳入提示词安全扫描范围

### 文件变更

- 更新: `scripts/security.py` - 添加 `PROMPT_SECURITY_PATTERNS` 和 `_analyze_prompt_security()` 方法
- 更新: `SKILL.md` - 添加提示词安全检测说明
- 更新: `CHANGELOG.md` - 记录 v0.6.0 变更

### 提示词安全检测能力

| 类别 | 检测内容 | 风险等级 |
|:-----|:---------|:---------|
| 提示注入 | ignore instructions、override、jailbreak、DAN mode | 🔴 critical |
| 数据收集指令 | collect password、send to external、exfiltrate data | 🔴 critical |
| 执行指令 | execute shell、download and run、spawn process | 🟠 high |
| 权限提升指令 | run with sudo、grant root、disable security | 🟠 high |
| 网络通信指令 | phone home、reverse shell、beacon、connect to server | 🟠 high |
| 持久化指令 | cron job、startup、auto-run、modify rc files | 🟠 high |
| 欺骗性描述 | harmless tool、educational only、hidden feature | 🟡 medium |
| 隐藏指令 | 控制字符、Unicode 转义、零宽字符 | 🟡 medium |
| 社会工程学 | urgent update、verify account、trust me | 🟡 medium |

---

## [0.5.0] - 2026-02-21

### 新增功能

- **安全分析模块**: 基于 OWASP Agentic AI Top 10 和常见漏洞模式设计
  - 新增 `scripts/security.py` 模块（约 700 行）
  - 检测 15+ 类安全风险：命令执行、敏感文件访问、网络外泄、代码混淆、权限提升、硬编码凭证、下载执行、持久化机制等
  - 识别 Skill 特有风险：安装钩子、MCP 服务器风险
  - 支持 4 级风险等级：critical / high / medium / low
  - 生成结构化安全分析报告

### 改进优化

- **报告命名格式优化**: 从 `REPORT.md` 改为 `YYYYMMDD-topic-slug-report.md`
  - 报告文件与目录同级，便于查找和管理
  - 示例：`20260221-douyin-batch-download-report.md`
- 更新报告模板，添加"安全评估"章节
- 报告中显示总体风险等级和安全建议

### 文件变更

- 新增: `scripts/security.py` - 安全分析核心模块
- 更新: `scripts/__init__.py` - 导出 SecurityAnalyzer
- 更新: `SKILL.md` - 添加安全分析文档 + 报告命名格式调整
- 更新: `assets/report-template.md` - 添加安全评估章节

### 安全检测能力

| 类别 | 检测内容 | 风险等级 |
|:-----|:---------|:---------|
| 命令执行 | `os.system`, `subprocess`, `eval()`, `exec()` | 🔴 高 |
| 敏感文件访问 | `~/.ssh/`, `~/.aws/`, `.env`, `.pem`, `.key` | 🔴 高 |
| 网络外泄 | HTTP POST、WebSocket、数据上传 | 🟡 中 |
| 代码混淆 | `base64`, `chr()` 拼接、hex escape | 🔴 高 |
| 权限提升 | `sudo`, `chmod 777`, `setuid` | 🔴 高 |
| 硬编码凭证 | API Key、Token、AWS/GitHub 凭证 | 🔴 高 |
| 下载执行 | `curl | bash`, `wget | sh` 模式 | 🔴 高 |
| Skill 特有 | 安装钩子、MCP 服务器风险 | 🟡 中 |

---

## [0.4.0] - 2026-02-14

### 新增功能

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

- **代码语义搜索**: 支持搜索函数、类、导入、文档等多种模式
  - 新增 `scripts/search.py` 模块
  - 支持 Python, JavaScript, TypeScript, Go, Rust, Java
  - 使用 Grep 工具进行模式匹配

- **深度代码分析**: 超越基础分析，提供架构和质量层面的深度洞察
  - 新增 `scripts/analyzer/` 模块
  - **架构分析**: 目录结构、模块划分、入口文件、架构模式检测（MVC、微服务、插件、monorepo）
  - **质量分析**: 代码统计、注释覆盖率、技术债务检测（TODO、FIXME）、问题检测（硬编码密钥、console.log）

- **智能问答**: 利用 Claude Code 的 LLM 能力，回答关于仓库的自然语言问题
  - 新增 `scripts/qa.py` 模块
  - 问题意图分类: overview, architecture, usage, api, dependencies
  - 结构化回答模板

### 改进优化

- 更新 SKILL.md，添加高级功能章节
- 文档完善：详细说明各功能的使用方法和触发条件

### 文件变更

- 新增: `scripts/__init__.py`
- 新增: `scripts/search.py`
- 新增: `scripts/qa.py`
- 新增: `scripts/analyzer/__init__.py`
- 新增: `scripts/analyzer/architecture.py`
- 新增: `scripts/analyzer/quality.py`
- 更新: `SKILL.md`

---

## [0.3.0] - 2026-02-11

### 新增功能

- 主题驱动搜索研究模式：支持用户提供主题关键词，自动使用 find-skills 搜索相关 GitHub 仓库
- 依赖管理章节：说明核心功能无需前置技能，find-skills 仅在主题搜索模式下可选使用
- 新增主题研究报告模板：`assets/topic-research-template.md`

### 改进优化

- 更新模式选择表格，添加主题驱动搜索研究模式（第 4 种模式）
- 完善触发条件说明，包含主题搜索相关触发场景
- 添加主题研究模式的完整工作流程（Step 0-6）：依赖检查、搜索、筛选、克隆、分析、报告

### 文档完善

- 更新 Resources 章节，添加新模板文件引用
- 创建配套文档：DECISIONS.md、TASKS.md、LICENSE.txt
- 记录 3 个重要技术决策：主题搜索模式设计、目录结构设计、报告模板设计原则

---

## [0.2.0] - 2026-02-10

### 新增功能

- 对比启发模式：支持外部仓库与本地项目进行对比分析
- 启发式分析框架：差异分析框架 + 启发式问题清单
- 本地项目识别：自动识别常见本地项目类型（技能目录、测试项目等）

### 改进优化

- 扩展模式选择表格，添加对比启发模式（第 3 种模式）
- 新增多仓库对比报告模板：`assets/comparison-template.md`
- 完善报告结构，添加"对比分析"和"具体启发"章节

### 文档完善

- 添加对比启发模式的完整工作流程（Step 4）
- 定义启发式问题清单：功能、架构、实现、文档 4 个维度

---

## [0.1.0] - 2026-02-09

### 新增功能

- 基础研究框架：支持单个和多个 GitHub 仓库的深度研究
- 两种研究模式：
  - 单仓库深度研究：全面分析单个仓库的架构、功能、代码质量
  - 多仓库对比研究：对比多个仓库的共性、差异、优劣
- 基础分析流程：项目类型识别、核心文件阅读、项目结构分析、技术栈识别
- 单仓库报告模板：`assets/report-template.md`

### 功能特性

- 智能克隆：使用 `--depth 1` 浅克隆，节省时间和空间
- 目录结构设计：`research/YYYYMMDD/{repo-name|comparison}/` 模式化组织
- 项目类型识别：自动识别 Node.js、Python、Go、Rust、Claude Skill 等项目类型

### 文档完善

- 定义技能触发条件和使用场景
- 编写完整工作流程文档（Step 1-5）
- 创建报告模板和会话汇报格式


path: CLAUDE.md
content: <claude-mem-context>
# Recent Activity

<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->

### Feb 13, 2026

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #18270 | 12:27 PM | ✅ | Force push rewrote remote git history | ~226 |
| #18269 | " | 🟣 | Repository cleanup completed with clean commits | ~257 |
| #18267 | " | ✅ | Documentation changes restored via new commit | ~177 |
| #18266 | " | ✅ | Files unstaged after git reset HEAD | ~233 |
| #18263 | 12:26 PM | ✅ | Repository state shows divergence from remote | ~267 |
| #18262 | " | ✅ | Repository reset to origin/main state | ~221 |
| #18260 | " | ✅ | Repository reset to sync with origin/main | ~243 |
| #18259 | " | ✅ | Soft reset re-stages all changes for clean commit | ~239 |
| #18257 | 12:25 PM | 🔵 | Git diff reveals unexpected file state between origin/main and HEAD | ~287 |
| #18256 | " | ✅ | Git hard reset removes commits with pyc contamination | ~247 |
| #18255 | " | 🔵 | HEAD commit actually contains detailed message | ~278 |
| #18253 | 12:24 PM | 🔵 | HEAD commit still contains pyc binary change despite gitignore update | ~306 |
| #18252 | " | ✅ | Repository state diverged from origin | ~243 |
| #18250 | 12:23 PM | ✅ | Git reset executed - commits undone, changes restored to staging | ~234 |
| #18249 | " | ✅ | Git soft reset to combine 3 commits | ~236 |
| #18246 | " | 🔵 | Git batch commit missing detailed messages | ~239 |
| #18245 | 12:21 PM | ✅ | Changes pushed to remote repository | ~167 |
| #18244 | " | ✅ | Git batch commit completed successfully | ~221 |
| #18243 | 12:20 PM | ✅ | All repository changes staged for commit | ~204 |
| #18238 | 12:18 PM | ✅ | Git status reveals pending changes in legal-skills repository | ~221 |

### Mar 24, 2026

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19717 | 4:17 PM | 🔵 | New skills found that need allowlist entries | ~215 |
</claude-mem-context>

path: DECISIONS.md
content: # 决策记录

本文档记录 repo-research 技能开发过程中的重要技术决策和设计取舍。

## [DEC-001] - 2026-02-11 - 主题驱动搜索模式设计

### 背景

用户希望能够提供主题关键词而非具体 GitHub URL，自动搜索并分析相关仓库。

### 选项

1. **直接调用 GitHub API**：使用 GitHub Search API 直接搜索仓库
   - 优点：无外部依赖，响应快速
   - 缺点：需要 API Token，有请求限制，搜索结果可能不够精准

2. **使用 find-skills 技能**：调用现有的 find-skills 技能进行搜索
   - 优点：复用已有技能，搜索结果针对 Claude Skills 优化
   - 缺点：需要额外依赖，find-skills 主要面向 Skills 搜索

3. **混合模式**：优先使用 find-skills，如未安装则提示用户安装
   - 优点：兼顾便利性和功能性
   - 缺点：增加用户操作步骤

### 决策

选择**选项 3：混合模式**，但将 find-skills 设为**可选依赖**。

### 理由

1. **核心功能不受影响**：直接提供 GitHub URL 的用户无需任何前置技能
2. **渐进增强**：主题搜索是高级功能，可以要求用户安装额外依赖
3. **技能协作**：find-skills 已有成熟的搜索逻辑，复用优于重写
4. **灵活性**：用户可根据需求选择是否使用主题搜索功能

### 影响

- 核心功能（单/多仓库研究）无依赖，开箱即用
- 主题搜索功能需要 find-skills，技能会自动检测并提示安装
- 文档需明确说明依赖的必需性

---

## [DEC-002] - 2026-02-11 - 研究目录结构设计

### 背景

需要设计合理的研究目录结构，支持不同研究模式的文件组织。

### 选项

1. **扁平结构**：所有研究放在 `research/` 目录下，按仓库名命名
   - 优点：简单直观
   - 缺点：多仓库对比时难以区分归属

2. **日期分层**：`research/YYYYMMDD/repo-name/`
   - 优点：按时间组织，便于归档
   - 缺点：多仓库对比时文件分散

3. **模式分层**：`research/YYYYMMDD/{mode}/`
   - 优点：不同模式分开管理，结构清晰
   - 缺点：目录层级较多

### 决策

选择**选项 3：模式分层**。

### 理由

1. **清晰区分**：单仓库、多仓库对比、主题搜索的研究产物分开存放
2. **便于查找**：按研究类型和时间双重索引
3. **报告集中**：对比研究和主题搜索的报告统一放在对应目录下

### 目录结构

```
research/
└── YYYYMMDD/
    ├── repo-name/              # 单仓库研究
    │   ├── repo-code/
    │   └── REPORT.md
    ├── comparison/             # 多仓库对比
    │   ├── repo-a/
    │   ├── repo-b/
    │   └── REPORT.md
    └── topic-{slug}/           # 主题搜索
        ├── repo-a/
        ├── repo-b/
        └── REPORT.md
```

---

## [DEC-003] - 2026-02-11 - 报告模板设计原则

### 背景

需要设计结构化报告模板，确保输出的一致性和可读性。

### 设计原则

1. **金字塔结构**：从概述到细节，从结论到论据
2. **对比驱动**：通过表格对比突出差异和启发
3. **可操作建议**：每个发现都要转化为具体行动建议
4. **灵活复用**：模板支持不同研究场景

### 模板类型

| 模板 | 用途 | 重点 |
|:-----|:-----|:-----|
| `report-template.md` | 单仓库深度研究 | 全面分析、架构解读 |
| `comparison-template.md` | 多仓库对比 | 差异分析、共性提取 |
| `topic-research-template.md` | 主题搜索 | 综合分析、项目推荐 |

### 报告核心章节

1. **执行摘要**：一句话总结 + 核心指标
2. **概览**：项目信息、目录结构
3. **分析**：架构、功能、代码质量
4. **对比**：功能矩阵、技术栈对比
5. **启发**：可直接借鉴的方面、行动建议
6. **推荐**：不同场景下的项目推荐

---

## [DEC-004] - 2026-02-21 - 安全分析模块设计

### 背景

用户希望对研究的 GitHub 仓库（尤其是 Skills）进行安全风险检测，识别潜在的恶意代码或安全隐患。

### 选项

1. **集成外部工具**：使用 Semgrep、Bandit 等专业安全扫描工具
   - 优点：检测能力强，规则丰富
   - 缺点：需要用户安装额外依赖，增加使用门槛

2. **内置检测规则**：在 skill 内部实现安全检测
   - 优点：开箱即用，无外部依赖
   - 缺点：检测能力可能不如专业工具全面

3. **混合模式**：内置基础检测 + 可选外部工具增强
   - 优点：兼顾易用性和功能性
   - 缺点：实现复杂度较高

### 决策

选择**选项 2：内置检测规则**，后续可扩展为混合模式。

### 理由

1. **开箱即用**：用户无需安装任何外部工具即可使用安全分析功能
2. **轻量级**：基于正则模式匹配，实现简单，性能开销小
3. **针对性强**：针对 AI Agent/Skill 的特有风险设计检测规则
4. **可扩展**：预留接口，未来可集成外部工具

### 检测范围

| 类别 | 检测内容 | 风险等级 |
|:-----|:---------|:---------|
| 命令执行 | `os.system`, `subprocess`, `eval()` | 🔴 高 |
| 敏感文件访问 | `~/.ssh/`, `~/.aws/`, `.env` | 🔴 高 |
| 网络外泄 | HTTP POST、WebSocket | 🟡 中 |
| 代码混淆 | `base64`, `chr()` 拼接 | 🔴 高 |
| 权限提升 | `sudo`, `chmod 777` | 🔴 高 |
| 硬编码凭证 | API Key、Token | 🔴 高 |
| Skill 特有 | 安装钩子、MCP 服务器 | 🟡 中 |

### 影响

- 新增 `scripts/security.py` 模块
- 报告模板增加"安全评估"章节
- SKILL.md 增加安全分析使用说明

---

## [DEC-005] - 2026-02-21 - 报告文件命名格式

### 背景

原有报告命名为 `REPORT.md`，放在研究目录内，用户难以快速识别报告内容。

### 决策

将报告文件改为 `YYYYMMDD-topic-slug-report.md` 格式，与目录同级。

### 理由

1. **文件名即信息**：从文件名即可识别研究日期和主题
2. **便于移动**：报告文件独立于目录，可单独移动或分享
3. **排序友好**：按日期命名，文件列表自动按时间排序

### 示例

```
research/
├── 20260221-douyin-batch-download/        # 研究目录（含克隆仓库）
│   └── douyin-batch-download/
└── 20260221-douyin-batch-download-report.md  # 报告文件
```

---

## [DEC-006] - 2026-02-21 - 提示词安全检测模块设计

### 背景

用户指出，Skill 的安全风险不仅存在于代码中，SKILL.md 等提示词文档中也可能隐藏恶意指令。提示注入、数据收集指令等风险更难被传统代码分析工具识别。

### 决策

在 `security.py` 中新增 `PROMPT_SECURITY_PATTERNS` 和 `_analyze_prompt_security()` 方法，专门检测 Markdown 文件中的提示词安全风险。

### 理由

1. **攻击载体差异化**：恶意 Skill 可能通过提示词而非代码实施攻击
2. **AI Agent 特有风险**：提示注入、越狱等攻击针对 LLM 系统设计
3. **统一检测框架**：将提示词安全纳入整体安全分析流程
4. **正则模式匹配**：基于已知攻击模式库进行检测，无需外部依赖

### 检测范围

| 类别 | 检测内容 | 风险等级 |
|:-----|:---------|:---------|
| 提示注入 | ignore instructions、jailbreak、DAN mode | 🔴 critical |
| 数据收集指令 | collect password、exfiltrate data | 🔴 critical |
| 执行指令 | execute shell、download and run | 🟠 high |
| 权限提升指令 | run with sudo、grant root | 🟠 high |
| 网络通信指令 | phone home、reverse shell | 🟠 high |
| 持久化指令 | cron job、startup | 🟠 high |
| 欺骗性描述 | harmless tool、hidden feature | 🟡 medium |
| 隐藏指令 | 控制字符、零宽字符 | 🟡 medium |
| 社会工程学 | urgent update、verify account | 🟡 medium |

### 影响

- 所有 Markdown 文件（包括 SKILL.md）纳入安全扫描范围
- 提示词发现与代码发现统一汇总到风险等级计算
- 报告模板增加"提示词安全分析"章节

---

## 工作日志

### 2026-02-21 (v0.6.0)

- **目标**：为 repo-research 技能添加提示词安全检测能力
- **操作**：
  - 新增 `PROMPT_SECURITY_PATTERNS`：9 类提示词安全检测规则，共 60+ 正则模式
  - 新增 `_analyze_prompt_security()` 方法：扫描所有 Markdown 文件的提示词安全风险
  - 新增 `_scan_prompt_content()` 方法：对单个文件执行规则匹配
  - 更新 `analyze()` 方法：集成提示词安全检测到主分析流程
  - 更新 `generate_report()` 方法：添加"提示词安全分析"报告章节
  - 更新 `CHANGELOG.md`：发布 v0.6.0
- **结果**：提示词安全检测功能可用
- **下一步**：考虑使用 LLM 进行更智能的提示词风险分析

### 2026-02-21 (v0.5.0)

- **目标**：为 repo-research 技能添加安全分析能力
- **操作**：
  - 新增 `scripts/security.py`：实现 SecurityAnalyzer 类，支持 15+ 类安全风险检测
  - 更新 `scripts/__init__.py`：导出 SecurityAnalyzer
  - 更新 `SKILL.md`：添加安全分析文档 + 调整报告命名格式
  - 更新 `assets/report-template.md`：添加安全评估章节
  - 更新 `CHANGELOG.md`：发布 v0.5.0
  - 更新 `TASKS.md`：标记安全分析模块为已完成
- **结果**：安全分析功能可用，测试通过
- **下一步**：考虑集成外部安全扫描工具（Semgrep、Bandit）

### 2026-02-11

- **目标**：扩展 repo-research 技能，添加主题驱动搜索研究模式
- **操作**：
  - 更新 SKILL.md：添加依赖管理章节、主题搜索工作流程
  - 创建 topic-research-template.md：主题研究报告模板
  - 创建配套文档：CHANGELOG.md、TASKS.md、DECISIONS.md、LICENSE.txt
- **结果**：技能支持 4 种研究模式，文档符合 AGENTS.md 规范
- **下一步**：考虑添加搜索结果缓存和增量报告更新功能


path: LICENSE.txt
content: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International

Copyright (c) 2026 杨卫薪律师（微信ywxlaw）

=======================================================================

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material

Under the following terms:
- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
- NonCommercial — You may not use the material for commercial purposes.
- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license.

No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

To view a copy of this license, visit:
http://creativecommons.org/licenses/by-nc-sa/4.0/

=======================================================================

Commercial License

For commercial use licenses, please contact:
Email: [REDACTED_SECRET]
WeChat: ywxlaw (微信)

=======================================================================

The full text of the CC BY-NC-SA 4.0 license is reproduced below:

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING
FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.

Section 1 – Definitions.

Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.

Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.

BY-NC-SA Compatible License means a license licensed by You under the terms of this Public License that meets the following conditions: (i) is listed at https://creativecommons.org/compatiblelicenses; (ii) includes the same elements as this Public License; and (iii) complies with the conditions of this Public License.

Copyright and Similar Rights means copyright and/or similar rights closely related to copyright, including without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.

Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.

Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.

License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution, NonCommercial, and ShareAlike.

Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.

Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.

Licensor means the individual(s) or entity(ies) granting rights under this Public License.

NonCommercial means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange.

Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.

Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.

You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.

Section 2 – Scope.

Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:

 reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and
 produce, reproduce, and Share Adapted Material for NonCommercial purposes only.

Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.

Term. The term of this Public License is specified in Section 6(a).

Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.

Downstream recipients. Each recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.

No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated as receiving attribution as provided in Section 3(a)(1)(A)(i).

Other rights. Moral rights, rights against unfair competition, rights to protect publicity, privacy, or personality rights, and any other rights other than Copyright and Similar Rights are not subject to this Public License. Additional rights may apply to the Licensed Material, such as patent, trademark, or other intellectual property rights.

Section 3 – License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the following conditions.

Attribution.

If You Share the Licensed Material (including in modified form), You must:

retain the following if it is supplied by the Licensor with the Licensed Material:
   identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
   a copyright notice;
   a notice that refers to this Public License;
   a notice that refers to the disclaimer of warranties;
   a URI or hyperlink to the Licensed Material to the extent reasonably practicable;

indicate if You modified the Licensed Material and retain an indication of any previous modifications; and

indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.

For the avoidance of doubt, You do not have permission under this Public License to Share Adapted Material.

You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.

If requested by the Licensor, You must remove any of the information required by Section 3(a)(1) to the extent reasonably practicable.

NonCommercial. You may not exercise the Licensed Rights for commercial purposes.

ShareAlike.

In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.

The Adapter's License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-NC-SA Compatible License.

You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.

You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.

Section 4 – Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:

for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only;

if You include all or a substantial portion of the database contents in a database to which You applied the Adapter's License, then the database to which You applied the Adapter's License (but not its individual contents) is Adapted Material; and

You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.

Section 5 – Disclaimer of Warranties and Limitation of Liability.

Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available to make no representation or warranty of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.

To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.

The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

Section 6 – Term and Termination.

Term. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.

Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:

automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
upon express reinstatement by the Licensor.

For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.

Section 7 – Other Terms and Conditions.

The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.

Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.

Section 8 – Interpretation.

For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.

To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.

No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.

Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.

=======================================================================

Creative Commons may be contacted at creativecommons.org.


path: TASKS.md
content: # 任务清单

## 进行中

- [ ] 优化主题搜索结果筛选机制：支持更多筛选条件（如语言、Stars、活跃度）
- [ ] 添加搜索结果缓存：避免重复搜索相同主题
- [ ] 实现增量报告更新：支持在已有报告基础上添加新的仓库分析

## 已完成

- [x] 创建基础技能框架：定义单仓库/多仓库/对比启发三种研究模式
- [x] 创建报告模板：单仓库报告、多仓库对比报告模板
- [x] 添加主题驱动搜索研究模式
- [x] 创建主题研究报告模板
- [x] 添加依赖管理说明
- [x] 创建配套文档文件（CHANGELOG.md、TASKS.md、DECISIONS.md、LICENSE.txt）
- [x] **v0.5.0** 添加安全分析模块：检测 15+ 类安全风险，支持 4 级风险等级
- [x] **v0.5.0** 优化报告命名格式：从 `REPORT.md` 改为 `YYYYMMDD-topic-slug-report.md`
- [x] **v0.6.0** 添加提示词安全检测：检测 9 类 Markdown 提示词安全风险
- [x] **v0.7.0** 添加配置文件支持：支持自定义输出目录和其他设置

## 待规划

- [ ] 考虑添加非 GitHub 仓库支持（如 GitLab、Gitee）
- [ ] 考虑添加本地目录分析模式
- [ ] 考虑添加报告导出功能（PDF、HTML）
- [ ] 考虑添加交互式报告（支持折叠、筛选、排序）
- [ ] 考虑集成外部安全扫描工具（Semgrep、Bandit）


path: assets/comparison-template.md
content: # [研究主题] 启发式分析报告

> **研究日期**：YYYY-MM-DD
> **研究仓库**：[列出所有仓库]
> **对比项目**：[本地项目路径]
> **报告路径**：`./research/YYYYMMDD/comparison/REPORT.md`

---

## 核心发现

### 一句话总结

[用一句话概括最关键的启发]

---

## 仓库概览

### 项目信息对比

| 项目 | 名称 | 描述 | 语言 | 许可证 | Stars |
|:-----|:-----|:-----|:-----|:-------|:-----|
| **仓库A** | [name] | [描述] | [语言] | [LICENSE] | [数量] |
| **仓库B** | [name] | [描述] | [语言] | [LICENSE] | [数量] |
| **本地项目** | [name] | [描述] | [语言] | [LICENSE] | - |

### 一句话描述

- **仓库A**：[一句话概括]
- **仓库B**：[一句话概括]
- **本地项目**：[一句话概括]

---

## 对比分析

### 功能对比

| 功能 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| **[功能1]** | ✅ 有 | ✅ 有 | ❌ 无 | [建议] |
| **[功能2]** | ✅ 有 | ❌ 无 | ✅ 有 | [分析] |
| **[功能3]** | ❌ 无 | ✅ 有 | ❌ 无 | [建议] |

### 架构对比

| 维度 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| **目录结构** | [描述] | [描述] | [描述] | [可借鉴之处] |
| **模块划分** | [描述] | [描述] | [描述] | [可借鉴之处] |
| **配置方式** | [描述] | [描述] | [描述] | [可借鉴之处] |
| **入口设计** | [描述] | [描述] | [描述] | [可借鉴之处] |

### 检测/处理规则对比

| 规则类别 | 仓库A | 仓库B | 本地项目 | 启发 |
|:---------|:------|:------|:---------|:-----|
| **[类别1]** | [列举/描述] | [列举/描述] | [列举/描述] | [可学习] |
| **[类别2]** | [列举/描述] | [列举/描述] | [列举/描述] | [可学习] |
| **[类别3]** | [列举/描述] | [列举/描述] | [列举/描述] | [可学习] |

### 技术选型对比

| 技术 | 仓库A | 仓库B | 本地项目 | 分析 |
|:-----|:------|:------|:---------|:-----|
| **运行时** | [版本] | [版本] | [版本] | [差异分析] |
| **框架** | [名称] | [名称] | [名称] | [差异分析] |
| **测试框架** | [名称] | [名称] | [名称] | [差异分析] |
| **代码质量** | [工具] | [工具] | [工具] | [差异分析] |

---

## 具体启发

### 可直接借鉴的方面

#### 1. [方面名称]

- **外部做法**：
  - 仓库A：[具体描述]
  - 仓库B：[具体描述]
- **本地现状**：[具体描述]
- **改进建议**：[具体的改进建议]
- **优先级**：🔴 高 / 🟡 中 / 🟢 低
- **预计工作量**：[X 小时]

#### 2. [方面名称]

- **外部做法**：
  - 仓库A：[具体描述]
  - 仓库B：[具体描述]
- **本地现状**：[具体描述]
- **改进建议**：[具体的改进建议]
- **优先级**：🔴 高 / 🟡 中 / 🟢 低
- **预计工作量**：[X 小时]

#### 3. [方面名称]

- **外部做法**：
  - 仓库A：[具体描述]
  - 仓库B：[具体描述]
- **本地现状**：[具体描述]
- **改进建议**：[具体的改进建议]
- **优先级**：🔴 高 / 🟡 中 / 🟢 低
- **预计工作量**：[X 小时]

### 需要进一步探索的方面

#### 1. [方面名称]

- **为什么值得探索**：[说明]
- **调研方式**：[如何调研]
- **预期收益**：[说明]

#### 2. [方面名称]

- **为什么值得探索**：[说明]
- **调研方式**：[如何调研]
- **预期收益**：[说明]

### 本地项目的独特优势

[列出本地项目有而外部仓库没有的优势，说明为什么不需要改变]

---

## 行动建议

### 立即可做的改进

按优先级排序：

- [ ] **[改进1]**
  - 预计时间：[X 小时]
  - 涉及文件：[列出文件]
  - 实施方式：[简述]

- [ ] **[改进2]**
  - 预计时间：[X 小时]
  - 涉及文件：[列出文件]
  - 实施方式：[简述]

- [ ] **[改进3]**
  - 预计时间：[X 小时]
  - 涉及文件：[列出文件]
  - 实施方式：[简述]

### 需要进一步调研的

- [ ] **[调研项1]**
  - 调研方式：[如何调研]
  - 预计时间：[X 小时]
  - 输出物：[预期产出]

- [ ] **[调研项2]**
  - 调研方式：[如何调研]
  - 预计时间：[X 小时]
  - 输出物：[预期产出]

---

## 附录

### 仓库详细信息

#### 仓库A：[名称]

- **地址**：[GitHub URL]
- **描述**：[从 README 提取]
- **核心功能**：[列举]
- **目录结构**：
  ```
  [列出主要目录]
  ```

#### 仓库B：[名称]

- **地址**：[GitHub URL]
- **描述**：[从 README 提取]
- **核心功能**：[列举]
- **目录结构**：
  ```
  [列出主要目录]
  ```

### 参考链接

- **仓库A 文档**：[URL]
- **仓库B 文档**：[URL]
- **相关文章**：[URL]
- **相关讨论**：[URL]

### 研究笔记

[记录研究过程中的发现、疑问、想法等]

---

**报告生成时间**：YYYY-MM-DD HH:MM
**研究者**：Claude Code + repo-research skill


path: assets/config.example.yaml
content: # Repo Research 配置文件
# 复制此文件为 config.yaml 并根据需要修改

research:
  # 输出目录
  # 支持绝对路径、相对路径（相对于当前工作目录）、~ 展开
  # 留空则使用默认值 ./research
  output_dir: ""

  # 示例：
  # output_dir: "~/Documents/研究笔记"
  # output_dir: "/Users/maoking/research-output"
  # output_dir: "./my-research"

  # 报告格式
  # markdown: 生成 .md 文件
  # html: 生成 .html 文件（未来支持）
  report_format: "markdown"

  # 克隆设置
  shallow_clone: true  # 使用 --depth 1 浅克隆，节省时间和空间

# 安全分析设置
security:
  # 是否启用安全分析
  enabled: true

  # 是否包含提示词安全检测
  prompt_analysis: true

  # 风险等级阈值
  # 当风险等级达到此值时会在报告中突出显示
  # 可选: critical, high, medium, low
  warning_threshold: "high"

# 注意：
# 1. config.yaml 可能包含本地路径信息，建议添加到 .gitignore
# 2. 如果 config.yaml 不存在，将使用默认配置
# 3. 配置优先级：config.yaml > 默认值


path: assets/config.yaml
content: # repo-research 配置文件

# 研究报告输出目录
output_dir: "/Users/maoking/Desktop/Clawd/99 - 🦐 大虾研究/09 - 📋 研究报告"

# 报告格式
report_format: markdown

# 是否自动打开报告
auto_open_report: false

# 克隆深度
clone_depth: 1


path: assets/report-template.md
content: # [仓库名] 研究报告

> **研究日期**：YYYY-MM-DD
> **仓库地址**：https://github.com/user/repo
> **本地路径**：`./research/YYYYMMDD-topic-slug/repo-name/`（相对当前工作目录）
> **报告路径**：`./research/YYYYMMDD-topic-slug-report.md`
> **许可证**：[LICENSE 类型]

---

## 快速概览

### 项目信息

| 项目 | 内容 |
|:-----|:-----|
| **名称** | [repo-name] |
| **描述** | [从 README 提取] |
| **作者** | [GitHub 用户名] |
| **语言** | [主要编程语言] |
| **许可证** | [LICENSE] |
| **Stars** | [数量] |
| **最后更新** | [日期] |

### 一句话总结

[用一句话概括这个项目的核心价值和定位]

---

## 安全评估

> **总体风险等级**：[🔴 高 / 🟡 中 / 🟢 低 / ✅ 无]

### 发现摘要

| 问题类型 | 数量 | 最高风险等级 |
|:---------|:-----|:-------------|
| [类型1] | N | 🔴 高 |
| [类型2] | N | 🟡 中 |

### 安全建议

- [ ] [建议1]
- [ ] [建议2]

> 💡 **提示**：如果风险等级为 🔴 高，建议在沙箱环境中运行或进行完整代码审计后再使用。

---

## 架构分析

### 目录结构

```
repo-name/
├── [列出主要目录和文件]
├── [按层级展示]
└── [突出重要文件]
```

### 技术栈

| 类型 | 技术 |
|:-----|:-----|
| **运行时** | [Node.js/Python/Go/等] |
| **框架** | [React/Express/FastAPI/等] |
| **主要依赖** | [列出关键依赖] |
| **构建工具** | [Vite/Webpack/esbuild/等] |
| **测试框架** | [Jest/Pytest/go test/等] |

### 设计模式

- [描述使用的架构模式，如 MVC、微服务、插件系统等]
- [描述关键设计决策]

---

## 核心功能

### 功能清单

1. **[功能1]**：[描述]
2. **[功能2]**：[描述]
3. **[功能3]**：[描述]

### 关键代码路径

| 模块 | 路径 | 说明 |
|:-----|:-----|:-----|
| **入口点** | `[文件路径]` | [说明] |
| **核心逻辑** | `[文件路径]` | [说明] |
| **配置** | `[文件路径]` | [说明] |
| **工具函数** | `[文件路径]` | [说明] |

---

## 代码质量评估

| 指标 | 评分 | 说明 |
|:-----|:-----|:-----|
| **代码组织** | ⭐⭐⭐⭐☆ | [具体评价] |
| **文档完整性** | ⭐⭐⭐☆☆ | [具体评价] |
| **测试覆盖** | ⭐⭐☆☆☆ | [具体评价] |
| **依赖健康** | ⭐⭐⭐⭐☆ | [具体评价] |
| **代码风格** | ⭐⭐⭐☆☆ | [具体评价] |

### 详细评价

#### 代码组织

[评价代码的模块化程度、职责划分是否清晰等]

#### 文档完整性

[评价 README、API 文档、代码注释的质量]

#### 测试覆盖

[评价测试的完整性、测试类型等]

#### 依赖健康

[列出依赖数量、是否有未使用的依赖、是否有安全风险]

---

## 整合建议

### 可借鉴的方面

1. **[方面1]**：[具体说明如何借鉴]
2. **[方面2]**：[具体说明如何借鉴]
3. **[方面3]**：[具体说明如何借鉴]

### 潜在整合点

#### 与 [现有技能A] 的整合

- **整合方式**：[描述如何整合]
- **收益**：[说明整合后的好处]
- **风险**：[说明潜在风险]

#### 与 [现有技能B] 的整合

- **整合方式**：[描述如何整合]
- **收益**：[说明整合后的好处]
- **风险**：[说明潜在风险]

### 风险提示

| 风险 | 等级 | 说明 |
|:-----|:-----|:-----|
| **[风险1]** | 🟡 中 | [说明] |
| **[风险2]** | 🔴 高 | [说明] |
| **[风险3]** | 🟢 低 | [说明] |

---

## 附录

### 依赖清单

```
[列出所有生产依赖]
```

### 参考链接

- **官方文档**：[URL]
- **API 文档**：[URL]
- **相关文章**：[URL]
- **相关问题**：[URL]

### 研究笔记

[记录研究过程中的发现、疑问、想法等]

---

**报告生成时间**：YYYY-MM-DD HH:MM
**研究者**：Claude Code + repo-research skill


path: assets/topic-research-template.md
content: # [主题] 综合研究报告

> **研究日期**：YYYY-MM-DD
> **搜索主题**：[主题关键词]
> **研究仓库数**：[N] 个
> **报告路径**：`./research/YYYYMMDD/topic-[slug]/REPORT.md`

---

## 执行摘要

### 研究概述

[用一段话概括：基于主题搜索了哪些类型的仓库，主要发现了什么]

### 一句话总结

[用一句话概括最关键的发现]

### 核心指标

| 指标 | 数值 |
|:-----|:-----|
| 搜索结果总数 | [N] 个仓库 |
| 深度研究数量 | [M] 个仓库 |
| 相关技术栈 | [列举主要技术] |
| 活跃项目占比 | [X%] |

---

## 搜索结果概览

### 仓库清单

| # | 仓库名 | 描述 | 语言 | Stars | 活跃度 |
|:-|:-------|:-----|:-----|:-----|:-------|
| 1 | [name] | [描述] | [lang] | [★] | 🟢 活跃 |
| 2 | [name] | [描述] | [lang] | [★] | 🟡 中等 |

### 分类汇总

**按技术类型**：
- [技术1]: [数量] 个项目
- [技术2]: [数量] 个项目

**按功能类型**：
- [功能1]: [数量] 个项目
- [功能2]: [数量] 个项目

---

## 技术栈分析

### 主流技术选择

| 技术 | 使用项目数 | 占比 | 代表项目 |
|:-----|-----------|:-----|:---------|
| [技术1] | [N] | [X%] | [项目A, 项目B] |
| [技术2] | [N] | [X%] | [项目C] |

### 技术趋势洞察

- **趋势1**：[描述观察到的技术趋势]
- **趋势2**：[描述观察到的技术趋势]

---

## 共性模式识别

### 架构共性

多个项目共同采用的架构模式：
1. **[模式名称]**：[描述]
   - 采用项目：[列举]
   - 优势分析：[分析]

### 功能共性

多个项目都实现的核心功能：
1. **[功能名称]**：[描述]
   - 实现方式差异：[对比]

### 文档共性

文档编写的共同特点：
- [观察到的文档模式]

---

## 项目对比分析

### 功能对比矩阵

| 功能 | 项目1 | 项目2 | 项目3 | 最优实现 |
|:-----|:-----|:-----|:-----|:---------|
| [功能1] | ✅ | ✅ | ❌ | [分析] |
| [功能2] | ✅ | ❌ | ✅ | [分析] |

### 架构对比

| 维度 | 项目1 | 项目2 | 项目3 | 值得学习 |
|:-----|:-----|:-----|:-----|:---------|
| 目录结构 | [描述] | [描述] | [描述] | [推荐] |
| 模块化 | [描述] | [描述] | [描述] | [推荐] |

### 代码质量对比

| 项目 | 代码组织 | 文档 | 测试 | 综合评分 |
|:-----|:---------|:-----|:-----|:---------|
| 项目1 | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | ⭐⭐☆☆☆ | B+ |
| 项目2 | ⭐⭐⭐☆☆ | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | B |

---

## 深度剖析（精选项目）

### 项目 A: [仓库名]

#### 为什么值得深入研究

[说明选择这个项目进行深度剖析的原因]

#### 架构亮点

- [亮点1]
- [亮点2]

#### 可借鉴的设计

1. **[设计点1]**：[描述可借鉴之处]
2. **[设计点2]**：[描述可借鉴之处]

### 项目 B: [仓库名]

[同上结构]

---

## 启发与建议

### 对本地项目的启发

#### 可直接借鉴

1. **[方面1]**
   - **来源**：[项目A/项目B]
   - **做法**：[描述具体做法]
   - **本地应用**：[如何应用到本地项目]
   - **优先级**：🔴 高 / 🟡 中 / 🟢 低
   - **预计工作量**：[X 小时]

#### 需要进一步探索

1. **[技术/模式]**
   - **为什么**：[说明价值]
   - **调研方式**：[如何调研]
   - **预期收益**：[说明]

### 最佳实践总结

从多个项目中提炼的最佳实践：
1. **[实践1]**：[描述]
2. **[实践2]**：[描述]

---

## 项目推荐

### 不同场景推荐

| 场景 | 推荐项目 | 理由 |
|:-----|:---------|:-----|
| 学习参考 | [项目名] | [理由] |
| 生产使用 | [项目名] | [理由] |
| 二次开发 | [项目名] | [理由] |
| 特定需求 | [项目名] | [理由] |

### 快速决策指南

- **如果你需要 X** → 推荐 [项目A]
- **如果你需要 Y** → 推荐 [项目B]
- **如果你需要 Z** → 推荐 [项目C]

---

## 附录

### 完整仓库列表

#### 深度研究的项目

1. **[项目名]** - [GitHub URL]
   - 描述：[描述]
   - 技术栈：[列举]
   - 最后更新：[日期]

#### 仅浏览的项目

1. **[项目名]** - [GitHub URL]
   - 相关度：⭐⭐☆☆☆

### 参考资源

- [相关文档链接]
- [相关文章链接]

---

**报告生成时间**：YYYY-MM-DD HH:MM
**研究者**：Claude Code + repo-research skill
**搜索工具**：find-skills skill


path: scripts/__init__.py
content: """
repo-research 技能脚本模块
"""

from .search import CodeSearcher
from .qa import QuestionClassifier, QAGenerator, generate_question_prompt
from .architecture import ArchitectureAnalyzer
from .quality import QualityAnalyzer
from .security import SecurityAnalyzer

__all__ = [
    'CodeSearcher',
    'QuestionClassifier',
    'QAGenerator',
    'generate_question_prompt',
    'ArchitectureAnalyzer',
    'QualityAnalyzer',
    'SecurityAnalyzer',
]


path: scripts/config.py
content: #!/usr/bin/env python3
"""
repo-research 配置管理
统一管理所有配置项
"""

import os
from pathlib import Path

try:
    import yaml
    HAS_YAML = True
except ImportError:
    HAS_YAML = False

# 默认配置
DEFAULT_CONFIG = {
    "output_dir": "",  # 空字符串表示使用当前工作目录
    "report_format": "markdown",
    "auto_open_report": False,
    "clone_depth": 1,
}

# 配置文件路径
CONFIG_FILE = Path(__file__).parent.parent / "assets" / "config.yaml"
EXAMPLE_CONFIG_FILE = Path(__file__).parent.parent / "assets" / "config.yaml.example"


def load_config():
    """
    加载配置文件
    
    优先级：
    1. 环境变量
    2. 配置文件 (config.yaml)
    3. 默认值
    """
    config = DEFAULT_CONFIG.copy()
    
    # 1. 尝试加载配置文件
    if CONFIG_FILE.exists():
        try:
            if HAS_YAML:
                with open(CONFIG_FILE, 'r', encoding='utf-8') as f:
                    file_config = yaml.safe_load(f)
                    if file_config:
                        # 递归更新配置
                        def deep_update(base, update):
                            for key, value in update.items():
                                if isinstance(value, dict) and key in base and isinstance(base[key], dict):
                                    deep_update(base[key], value)
                                else:
                                    base[key] = value
                        deep_update(config, file_config)
        except Exception as e:
            print(f"⚠️  加载配置文件失败: {e}")
            print("   使用默认配置")
    
    # 2. 环境变量覆盖
    env_overrides = {
        'REPO_RESEARCH_OUTPUT_DIR': 'output_dir',
        'REPO_RESEARCH_FORMAT': 'report_format',
        'REPO_RESEARCH_AUTO_OPEN': 'auto_open_report',
        'REPO_RESEARCH_CLONE_DEPTH': 'clone_depth',
    }
    
    for env_var, key in env_overrides.items():
        value = os.environ.get(env_var)
        if value:
            # 类型转换
            if key in ['clone_depth']:
                value = int(value)
            elif key in ['auto_open_report']:
                value = value.lower() in ('true', '1', 'yes')
            
            config[key] = value
    
    return config


def get_output_dir():
    """
    获取输出目录
    
    优先级：
    1. 配置文件中的 output_dir
    2. 环境变量 REPO_RESEARCH_OUTPUT_DIR
    3. 当前工作目录
    """
    config = load_config()
    output_dir = config.get('output_dir', '')
    
    if output_dir and str(output_dir).strip():
        # 支持 ~ 展开和相对路径
        output_dir = Path(output_dir).expanduser()
        
        # 如果是相对路径，相对于 skill 目录
        if not output_dir.is_absolute():
            skill_dir = Path(__file__).parent.parent
            output_dir = skill_dir / output_dir
        
        return output_dir
    
    # 回退到当前工作目录
    return Path.cwd()


def get_report_format():
    """获取报告格式"""
    config = load_config()
    return config.get('report_format', 'markdown')


def should_auto_open():
    """是否自动打开报告"""
    config = load_config()
    return config.get('auto_open_report', False)


def get_clone_depth():
    """获取克隆深度"""
    config = load_config()
    return config.get('clone_depth', 1)


def get_research_dir(topic_slug: str) -> Path:
    """
    获取研究目录路径
    
    Args:
        topic_slug: 主题 slug（用于目录命名）
    
    Returns:
        完整的研究目录路径
    """
    from datetime import datetime
    
    base_dir = get_output_dir()
    date_prefix = datetime.now().strftime('%Y%m%d')
    
    return base_dir / 'research' / f'{date_prefix}-{topic_slug}'


def get_report_filename(topic_slug: str) -> str:
    """
    获取报告文件名
    
    Args:
        topic_slug: 主题 slug
    
    Returns:
        报告文件名，如：twitter-skills-investigation-report.md
    """
    return f'{topic_slug}-report.md'


def ensure_config_exists():
    """
    确保配置文件存在
    
    如果 config.yaml 不存在，提示用户复制 example 文件
    """
    if not CONFIG_FILE.exists() and EXAMPLE_CONFIG_FILE.exists():
        print("📝 配置文件不存在")
        print(f"   请复制 {EXAMPLE_CONFIG_FILE.name} 为 config.yaml 并修改配置")
        print(f"   路径: {CONFIG_FILE}")


# 导出便捷函数
__all__ = [
    'load_config',
    'get_output_dir',
    'get_report_format',
    'should_auto_open',
    'get_clone_depth',
    'get_research_dir',
    'ensure_config_exists',
]


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (HIGH)