# Github Project Replication > 自动化复现 GitHub 开源项目的完整工作流。当用户提到"复现"、"复刻"、"重现"、"部署"、"搭建"某个 GitHub 项目，或给出 GitHub 仓库 URL 要求运行/安装/部署时， 务必使用此技能。涵盖从项目理解、环境配置、代码搭建到运行评估与迭代修复的全流程自动化。 即使只是说"帮我跑一下这个项目"、"试试这个 repo"、"部署这个仓库"，也应该触发此技能。 同时会调用 brainstorming 进行前期分析，调用 planning-with-files 进行任务追踪与进度管理。 - Skill: `marecgents/github-project-replication` (Agent Skill) - Install (CLI): `npx skillmds@latest add marecgents/github-project-replication` - Raw SKILL.md: https://api.skillmd.com/api/skills/marecgents/github-project-replication/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: MarecGents (https://skillmd.com/u/marecgents) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/marecgents/github-project-replication --- # GitHub 开源项目自动化复现 当你收到用户"复现 GitHub 项目"相关的任务时，按照本技能定义的系统化六阶段工作流，从项目理解到稳定运行，全程自动化执行。 --- ## 核心原则 1. **必须先调用 brainstorming** — 每次任务执行**必须**先调用 brainstorming 技能进行前期构思和分析，**不得跳过此步骤**。这帮助你在动手之前全面理解项目目标和潜在挑战。 2. **必须用 planning-with-files-zh 做追踪** — 调用 planning-with-files-zh 技能进行任务文件化追踪，该技能会创建 `task_plan.md`、`findings.md`、`progress.md` 三个核心追踪文件，让整个复现过程有迹可循、可回溯。 3. **规范统一由 skill-standard-harness 管理** — 操作层面的公共规范（如 GitHub 仓库获取规范、Markdown 输出规范等）由 skill-standard-harness 统一维护，本技能不再重复定义。 --- ## GitHub 仓库获取规范 复现项目的第一步是获取目标仓库的代码。请调用 `skill-standard-harness` 技能并读取 `references/github-access-standard.md`，按照其中的四级优先级规范执行获取操作。 --- ## 目录说明 ``` github-project-replication/ ├── SKILL.md ← 本文件：六阶段工作流定义 ├── references/ ← 预留：本技能自身的参考文档（当前无内容） └── scripts/ ← 预留：本技能自身的辅助脚本（当前无内容） ``` > **注意**：本技能涉及的公共规范（GitHub 仓库获取、Markdown 输出）统一存放在 `skill-standard-harness/references/`，不在此目录重复维护。 --- ## 六阶段工作流 ``` 阶段一：初始化 → 阶段二：项目理解 → 阶段三：复现搭建 ↓ (循环迭代) 阶段四：运行评估 ←——┘ ↓ 阶段五：循环迭代 ↓ 阶段六：任务收尾 ``` ### 阶段一：技能调用与初始化 **触发条件**：接收到 "复现 GitHub 项目" 相关任务时立即进入此阶段。 **执行步骤：** 1. **调用 brainstorming** — 对目标项目进行初步分析构思。思考： - 这个项目做什么的？它的核心价值是什么？ - 它依赖哪些技术栈和环境？ - 复现它可能遇到哪些主要挑战？ - 需要哪些前置条件（如 API 密钥、数据库、特定 OS）？ 2. **调用 planning-with-files-zh** — 初始化三个追踪文件： - `task_plan.md` — 拆解为可执行的任务清单 - `findings.md` — 预留研究笔记空间 - `progress.md` — 准备记录操作日志 3. **解析用户输入** — 从用户消息中提取： - 目标 GitHub 仓库 URL（如 `https://github.com/user/repo`） - 或本地项目路径 - 任何附加要求（如特定分支、自定义配置） **获取目标仓库代码** — 调用 `skill-standard-harness` 技能，按照 `references/github-access-standard.md` 中的四级优先级规范获取源码。将获取过程和结果记录到 `progress.md`。 ### 阶段二：MCP 服务调用与项目理解 **目标**：快速全面地了解目标项目的代码架构，为复现工作奠定基础。 **执行步骤：** 1. **分析项目代码结构**（如果 CodeGraph MCP 服务可用）： - 索引目标项目的代码库 - 获取项目结构统计信息（实体数量、文件数、模块关系等） - 进行符号搜索和上下文探索 - 分析依赖关系和调用链 - **为什么**：这让你在动手前就对代码的骨架有全局认知，避免在搭建时走弯路 2. **阅读 README.md**（或类似的项目文档），提取关键信息： - **项目功能描述**：这个项目到底做什么的？ - **技术栈与依赖**：语言、框架、数据库、中间件等 - **安装与配置步骤**：README 中给出的安装指南 - **运行与测试命令**：如何启动、如何验证 - **环境要求**：OS、Node 版本、Python 版本、JDK 版本等 3. **将分析结果记录到 `findings.md`** — 包含架构图、关键模块说明、依赖关系。这将成为后续搭建的参考资料。 ### 阶段三：项目复现搭建（核心阶段） **目标**：在指定目录下完整搭建项目，使其达到可运行状态。 **执行步骤：** 1. **目录准备**： - 在用户指定目录或原项目文件夹的**同级目录**下，新建复现文件夹 - 命名格式：`{项目名}-replication` - 例如：原项目在 `~/projects/vue-app/`，则复现目录为 `~/projects/vue-app-replication/` 2. **环境配置（子代理异步执行）**： - 启动一个**独立的子代理**，在后台进行环境配置 - 子代理负责：安装系统依赖、创建虚拟环境、配置环境变量、安装项目依赖等 - **重要：子代理后台运行，不得阻断主进程的复现流程** - 主进程和子代理同步进行，最大化利用时间 3. **主进程持续执行**： - 根据 README 和阶段二的分析，搭建项目文件结构 - 复制或重新生成核心代码文件 - 配置必要的配置文件（`.env`、`config.yaml`、`docker-compose.yml` 等） - **为什么并行**：环境配置（如下载依赖）往往是 IO 密集型任务，让它在后台跑着，同时进行文件搭建，能显著缩短整体耗时 4. **状态检查机制**： - 主进程**每隔 30-60 秒**检查子代理的环境配置进度 - 如果子代理已完成 → 继续下一步 - 如果仍在进行 → 继续执行其他可并行的工作，稍后再次检查 - 记录检查结果到 `progress.md` 5. **实时更新进度**： - 每次完成一个子任务，更新 `task_plan.md`（标记完成项） - 每次执行关键操作，记录到 `progress.md`（含时间戳） ### 阶段四：运行与评估 **目标**：自行运行复现的项目，进行全面评估，判断是否达到可用标准。 **执行步骤：** 1. **启动运行**： - 根据项目类型执行相应的启动命令 - 常见启动方式：`npm start`、`python main.py`、`cargo run`、`docker-compose up`、`go run main.go` 等 - 将启动输出记录到 `progress.md` 2. **自检与评估**，从以下维度检查： - **能否成功启动** — 程序是否正常启动，有无崩溃 - **报错检查** — 控制台有无错误输出、异常堆栈 - **核心功能验证** — 项目的核心功能是否按预期工作（如 API 能响应、页面能渲染、命令能执行） - **行为对比** — 对比原项目的预期行为（README 中描述的功能、示例等），判断复现质量 3. **评估等级**： | 等级 | 标准 | |---|---| | **优秀** | 程序稳定运行，所有核心功能正常，无报错 | | **良好** | 程序运行但有次要功能异常或警告信息 | | **需改进** | 程序能运行但有明显功能缺陷 | | **失败** | 程序无法启动或核心功能不可用 | 4. **记录评估结果**到 `findings.md`（含评估等级、发现的 bugs、性能表现等）和 `progress.md`（含操作日志） ### 阶段五：循环迭代（Loop） **目标**：重复阶段三和阶段四，直到项目稳定运行并达到"优秀"评级。 **执行步骤：** 1. **如果评估结果未达到"优秀"**： - **分析根因**：查看错误日志、堆栈信息，确定失败或不足的原因 - **制定修复方案**：记录到 `findings.md`，明确需要改什么 - **回到阶段三**：实施修复和调整 - **重新评估**：进入阶段四，再次运行和评估 2. **如果评估结果达到"优秀"**： - 结束循环 - 进入阶段六（任务收尾） 3. **记录每次迭代**： - 每次循环的尝试和结果都要记录到 `progress.md` - 格式示例： ```markdown ## 迭代 #1 - 时间：2026-06-27 15:30 - 操作：修复了数据库连接字符串缺失的问题 - 结果：服务成功启动，API 返回 200 - 评估等级：良好（存在一个警告：deprecated API 调用） ``` ### 阶段六：任务收尾 **执行步骤：** 1. **生成任务执行日志文档**： - 基于 `task_plan.md`、`findings.md`、`progress.md` 三份文件 - 整合生成一份完整的日志文档 - 命名格式：`replication-log-{YYYY-MM-DD}.md` - 内容应包含： - 项目概述（名称、URL、技术栈） - 复现过程摘要（各阶段做了什么） - 遇到的问题与解决方案 - 最终评估结果 2. **清理无用文件**： - 删除过程中产生的临时文件（如下载的缓存、编译中间产物等） - 保留项目运行所需的必要文件 - 保留三份追踪文件（`task_plan.md`、`findings.md`、`progress.md`） 3. **输出最终结果摘要** — 用简洁的语言告诉用户： - 复现是否成功 - 项目位置（路径） - 启动方式 - 评估结果 - 遗留问题（如果有） --- ## 错误处理与异常 复现过程中可能遇到各种问题，以下是常见异常的处理策略： | 异常场景 | 处理方式 | |---|---| | **环境配置超时** | 若子代理环境配置超过合理时间（如 10 分钟），主进程应介入诊断。检查子代理的日志，判断是卡在下载还是真有错误 | | **依赖冲突** | 记录冲突的包名和版本到 `findings.md`。尝试调整版本范围（如放宽版本约束），或查找兼容版本组合 | | **代码报错** | 捕获完整的错误信息（堆栈 + 上下文），分析根因。记录到 `findings.md`，在下一轮循环中修复。优先搜索项目的 Issues/PRs 看是否有已知解决方案 | | **网络问题** | 若因网络导致依赖下载失败，应重试（最多 3 次）。如果仍失败，提示用户检查网络连接或提供镜像源 | | **缺少密钥/Token** | 检查是否需要 API 密钥、数据库密码等。列出所有需要的凭据，提示用户提供 | | **无法获取仓库代码** | 调用 `skill-standard-harness` 技能，按 `references/github-access-standard.md` 中的规范执行，所有方式均失败后向用户报告具体情况并请求协助 | --- ## 输出规范 请调用 `skill-standard-harness` 技能并读取 `references/markdown-output-standard.md`，按照统一的 Markdown 输出规范执行（标题层级、时间戳格式、日志文档结构、文件命名规则等）。 本技能特有要求： - `progress.md` 每条记录必须包含时间戳（格式：`YYYY-MM-DD HH:mm`） - 最终日志文档 (`replication-log-*.md`) 必须包含：项目概述、复现过程摘要、遇到的问题与解决方案、最终评估结果（含等级） --- ## 成功标准 复现任务完成时，以下条件应全部满足： - [ ] 项目在目标环境中成功运行 - [ ] 自检评估达到"优秀"等级（所有核心功能正常，无报错） - [ ] 完整的任务执行日志文档已生成 - [ ] 无用文件已清理 --- ## 使用示例 **示例 1：用户给出完整的仓库 URL** > 用户：帮我复现这个项目 https://github.com/vercel/next.js/tree/canary/examples/with-docker 触发此技能后，依次执行阶段一至六：理解项目结构 → 创建复现目录 → 搭建环境并部署 → 验证运行 → 输出日志。 **示例 2：用户描述本地项目** > 用户：我在桌面上有个 python 爬虫项目，你能帮我在另一台机器上配置好运行环境吗？项目路径在 C:\Users\me\Desktop\spider 技能应将其识别为"复现"需求（虽然不是 GitHub 仓库），同样执行完整工作流。