Analyze GitHub — 项目工作流分析与实现蓝图生成

输入 GitHub 仓库 URL 或本地目录路径，自动检测技术栈和架构模式，输出端到端工作流文档和实现蓝图。

Step -2: 解析输入（第一步必须执行）

判断用户输入属于哪种情形，按对应分支处理：

分支 A：已有 GitHub URL

输入包含 https://github.com/ → 直接记录为 REPO_URL，跳到 Step -1。

分支 B：已有本地目录路径

输入是以 / 或 ~/ 开头的路径，或用户明确说"本地目录" → 记为 PROJECT_DIR，跳到 Step -1。

分支 C：仅有关键词（无 URL、无路径）

当用户只给出项目名、描述或关键词时，执行以下步骤查找 GitHub URL：

构造搜索查询：将关键词拼成 site:github.com <keywords> 搜索字符串。
执行 WebSearch：搜索并读取前几条结果。
提取候选 URL：从搜索结果中筛选出 https://github.com/<owner>/<repo> 格式的链接（非 issues/pulls/blob 子路径），整理出 1-3 个最相关的候选项。
确认：
- 若只有 1 个高置信度候选项，直接使用并告知用户："找到仓库 <URL>，开始分析。"
- 若有多个候选项，列出供用户选择，等待确认后继续。
- 若未找到任何候选项，告知用户并请求提供更具体的关键词或直接粘贴 URL，停止执行后续步骤。
确认后将选中的 URL 记为 REPO_URL，继续 Step -1。

Step -1: 确定输出文件名（第一步必须执行）

1. 提取项目名：从 URL 或路径取最后一段作为 PROJECT_NAME（如 https://github.com/Foo/hermes-agent → hermes-agent）。

2. 用 Bash 获取当前时间戳（精确到分钟）：

date +"%Y-%m-%d-%H%M"

3. 确定输出路径：

OUTPUT_FILE={当前工作目录}/{PROJECT_NAME}-workflow-analysis-{yyyy-mm-dd-HHmm}.md

示例：hermes-agent-workflow-analysis-2026-04-16-1430.md

时间戳精确到分钟，天然避免冲突，无需版本号后缀。

将确定好的路径记为 OUTPUT_FILE，后续 Step 直接使用。

⚠️ 禁止：

不得以"已有分析足够"为由跳过分析
写入前用 Glob 再次确认 OUTPUT_FILE 路径不存在，确认后再调 Write

Step 0: 获取项目源码

若输入是 GitHub URL（以 https://github.com/ 开头）：

REPO_URL="<用户输入的URL>"
REPO_NAME=$(basename "$REPO_URL" .git)
TARGET_DIR="$HOME/temp/$REPO_NAME"

if [ -d "$TARGET_DIR" ]; then
  echo "Already cloned: $TARGET_DIR"
else
  mkdir -p "$HOME/temp"
  gh repo clone "$REPO_URL" "$TARGET_DIR" -- --depth=1 2>/dev/null || \
  git clone --depth=1 "$REPO_URL" "$TARGET_DIR"
fi
echo "Project dir: $TARGET_DIR"

若输入是本地目录路径： 直接使用该路径作为 PROJECT_DIR，跳过克隆步骤。

Step 1: 自动检测阶段

扫描项目结构，识别以下信息并记录到分析上下文：

技术栈检测

查找 .csproj/.sln → .NET
查找 pom.xml/build.gradle + @SpringBootApplication → Java/Spring
查找 package.json + React/Next.js → Node.js/React
查找 go.mod → Go
查找 requirements.txt/pyproject.toml → Python
查找 Cargo.toml → Rust

架构模式检测

目录含 controllers/+services/+repositories/ → Layered
目录含 Commands/+Queries/+Handlers/ → CQRS
目录含 domain/+application/+infrastructure/ → Clean Architecture
docker-compose.yml 含多服务 → Microservices
目录含 resolvers/+schema/ → GraphQL

入口点检测

API Controller / Router 文件
GraphQL Resolver 文件
前端组件发起网络请求的位置
Message Handler / Event Subscriber
Scheduled Job 定义

持久化层检测

ORM 配置文件（DbContext, JPA Entity, GORM Model 等）
Repository 实现
数据库连接配置
外部 API 客户端

社区信号扫描（快速）

扫描以下信息源，补充代码层看不到的背景：

Issues（Top 10 高赞）：反映用户核心痛点和未满足需求
Discussions：社区对设计方向的争议或疑问
Release Notes（最近 3 个版本）：解决了什么实际问题
README 的 "Compared to" / "Why not X"：作者自陈的定位

若 GitHub Issues/Discussions 无法访问，跳过本节。

Step 1.5: 架构层级图（必须输出）

在进入工作流文档化之前，根据 Step 1 的检测结果，用 ASCII 框图绘制各架构层之间的调用关系和数据流。

格式要求：

每层用 ┌─┐ │ └─┘ 框住，标注层名称和该层的核心类/模块
层间用 │ 和 ▼ 表示调用方向
在箭头旁标注传递的数据类型或对象名（如 MemorizeRequest、SearchRequest）

示例格式：

┌─────────────────────────────────────────────┐
│         HTTP API Layer                      │
│  XxxController                              │
└──────────────────┬──────────────────────────┘
                   │ RequestDTO
┌──────────────────▼──────────────────────────┐
│         Service Layer                       │
│  XxxService                                 │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         Repository / Data Access Layer      │
│  XxxRepository                              │
└─────────────────────────────────────────────┘

层数和层名称按实际架构调整（如 Agentic/Business/Memory/Infrastructure 等）。

Step 1.7: 关键设计决策分析

对项目中 3-5 个最重要的架构/技术选型，逐一输出决策背后的动机。

识别方法（优先选择以下类型）：

非主流选型：用 SQLite 而不是 PostgreSQL、用 Markdown 文件代替数据库存配置
自研 vs. 成熟库：为什么自己实现 X 而不是用 library Y
架构模式选择：策略模式 vs. 硬编码 if/else、插件系统 vs. 静态注册
存储格式：JSON vs. YAML vs. 数据库
并发模型：事件循环 vs. 多线程 vs. goroutine

每个决策输出格式：

字段	内容
问题	为什么用 X 而不是 Y？
结论	简短的选择答案（1 句话）
原因	2-3 句：性能、成本、可维护性、兼容性、迁移路径等
代价	为此牺牲了什么（灵活性？生态？可维护性？迁移成本？）

Step 2: 工作流文档化

选取 1-3 个最具代表性的端到端工作流（CRUD 操作、核心业务流程），对每个工作流输出以下内容：

2.1 工作流概览

名称与业务用途描述
触发动作或事件
涉及的所有文件/类列表

2.2 入口点实现

根据检测到的入口类型输出：

API 入口：

Controller 类和接收请求的方法（含完整签名、注解/特性）
请求 DTO/Model 类定义
校验属性和自定义验证器
认证/授权属性和检查

GraphQL 入口：

Resolver 类和方法
Schema 定义（Query/Mutation）
Input 类型定义

前端入口：

发起 API 调用的组件和事件处理器
API 客户端 Service 方法
状态管理相关代码

消息消费者入口：

Message Handler 类和方法
消息订阅配置
消息模型定义与反序列化逻辑

2.3 Service 层实现

每个 Service 类及其依赖
完整方法签名（含参数和返回类型）
关键业务逻辑的实际实现
接口定义（如有）
依赖注入注册方式

CQRS 模式时包含：Command/Query Handler 完整实现 Clean 架构时包含：Use Case/Interactor 实现

2.4 数据映射

DTO → Domain Model 映射代码
Object Mapper 配置或手动映射方法
映射过程中的验证逻辑
映射时触发的 Domain Event（如有）

2.5 数据访问实现

Repository 接口及其实现
完整查询实现（含 ORM 语句或原生 SQL）
Entity/Model 类定义（含全部属性）
事务处理方式

SQL 数据库时包含：ORM 配置、Fluent API、实际 SQL NoSQL 时包含：文档结构定义、查询/更新操作

2.6 响应构造

响应 DTO/Model 类定义
Domain/Entity → Response 映射
HTTP 状态码选择逻辑
错误响应结构与生成方式

2.7 错误处理

工作流中使用的异常类型
各层的 try/catch 模式
全局异常处理器配置
错误日志实现
重试策略或熔断器模式
失败补偿操作

2.8 异步处理（如有）

后台任务调度代码
事件发布实现
消息队列发送模式
异步操作追踪与监控

Step 3: 技术栈专项模式

根据检测结果输出对应专项模式：

.NET： Controller 特性与过滤器、Startup/Program.cs 注册、EF Core DbContext 配置、AutoMapper Profile、中间件实现、Options 模式、ILogger 日志

Spring： Controller 注解与依赖注入、Service 事务边界、JPA Entity 与关系映射、DTO 实现、Bean 配置、ExceptionHandler、自定义校验器

React/Node.js： 组件结构（Props/State）、Hook 实现模式、API Service 实现、状态管理（Context/Redux）、表单处理、路由配置

Go： Handler 函数与中间件、Repository 接口、GORM/sqlx 查询、错误包装惯例、goroutine 使用模式

Step 4: 实现蓝图输出

4.1 实现模板

提供可复用的代码模板：

新建 API Endpoint 的完整骨架
新建 Service 方法的结构
新建 Repository 方法的结构
新建 Domain Model 类
正确的错误处理实现

4.2 命名约定文档

记录一致的命名规范：

Controller 命名（如 EntityNameController）
Service 命名（如 EntityNameService）
Repository 命名（如 IEntityNameRepository）
DTO 命名（如 EntityNameRequest/EntityNameResponse）
CRUD 方法命名模式
变量命名约定
文件组织模式

4.3 实现指引

从哪里开始：添加类似功能的起点
实现顺序：model → repository → service → controller（按实际栈调整）
集成横切关注点：日志、认证、缓存等的接入方式
常见陷阱：易错区域、性能考虑、常见 Bug

4.4 扩展机制

现有扩展点的接入方式
如何在不修改现有代码的情况下添加新行为
配置驱动特性模式

Step 4.5: 应用场景评估

从"学会了这个项目，我能做什么"的视角，输出三层应用场景：

Tier A — 直接使用

2-3 个该项目开箱即用能解决的真实问题，每条包含：

场景：谁在什么情况下遇到什么问题
用法：直接调用哪个 API / CLI / 模块

Tier B — 组合使用

1-2 个非显而易见的组合：将此项目与其他工具结合，产生单独使用时不具备的能力：

组合方：与哪个工具/框架结合
产生的新能力：组合后能做到什么原来做不到的事

Tier C — 借鉴模式

1-2 个可跨项目移植的设计思想（不依赖此库，只借用思路）：

模式名称：简短命名这个设计思路
如何迁移：在其他语言/场景中怎么复现这个思路

Step 5: 市场定位与竞品视角（工具/产品类项目专项）

判断是否执行此步骤：

✅ 执行：项目是面向用户的 CLI 工具、Agent 框架、开发平台、SaaS SDK
❌ 跳过：项目是纯库（utility library）、语言绑定、数据集、Demo

输出内容：

5.1 核心价值主张

用一句话描述：该项目独特解决的问题是什么？用户用了它之后，哪件以前做不到的事现在做到了？

5.2 解决前 vs. 解决后

没有此项目时	有了此项目后
痛点 1	解决方式
痛点 2	解决方式
痛点 3	解决方式

5.3 同类项目对比

列出 2-4 个最接近的竞品/替代方案：

项目	相似点	核心差异	适用场景
竞品 A	...	...	...
竞品 B	...	...	...

识别竞品的方法： README 中的"compared to"章节、GitHub Topics 同标签项目、文档中提到的迁移来源（"migrating from X"）

5.4 核心差异化因素

该项目相比竞品，最独特的 1-2 个核心能力（不是功能列表，是真正做到而竞品没做到的）。

输出格式

将分析结果保存为 Markdown 文件：

文件名：{项目名}-workflow-analysis-{yyyy-mm-dd-HHmm}.md（时间精确到分钟，由 Step -1 的 OUTPUT_FILE 确定）
保存位置：当前工作目录（或用户指定路径）

文档结构：

项目概览（技术栈、架构模式、入口类型、目录结构树）
架构层级图（Step 1.5 的 ASCII 框图）
关键设计决策（Step 1.7，"为什么 X 而不是 Y"，含代价分析）
各工作流详细文档（Step 2 全部小节）
技术栈专项模式（Step 3）
实现蓝图（Step 4）
应用场景三层框架（Step 4.5：直接用 / 组合用 / 借鉴模式）
常见坑点
可迁移心智模型：读完此项目，带走哪 3-5 条跨项目可用的设计原则（不是项目内部约定的总结，而是可迁移的洞察）
市场定位与竞品视角（Step 5，仅工具/产品类项目）

输出路径使用 Step -1 确定的 OUTPUT_FILE，写入前再次 Glob 确认路径为空，然后调用 Write 工具。

每次输出必须是完整独立文档（禁止仅写增量）： 即使存在同名旧文件，新文件也必须覆盖所有章节，不得以"基于 vN 增量补充"为由省略已有章节。若需对比版本差异，可在文档末尾添加"与上版本的主要变化"小节，但前面各章节必须完整。

analyze-github