Github project replication

GitHub 开源项目自动化复现

当你收到用户"复现 GitHub 项目"相关的任务时，按照本技能定义的系统化六阶段工作流，从项目理解到稳定运行，全程自动化执行。

---

核心原则

1. 必须先调用 brainstorming — 每次任务执行必须先调用 brainstorming 技能进行前期构思和分析，不得跳过此步骤。这帮助你在动手之前全面理解项目目标和潜在挑战。
2. 必须用 planning-with-files 做追踪 — 调用 planning-with-files 技能进行任务文件化追踪，该技能会创建 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 项目" 相关任务时立即进入此阶段。

执行步骤：

1. 调用 brainstorming — 对目标项目进行初步分析构思。思考：

   • 这个项目做什么的？它的核心价值是什么？
   • 它依赖哪些技术栈和环境？
   • 复现它可能遇到哪些主要挑战？
   • 需要哪些前置条件（如 API 密钥、数据库、特定 OS）？

2. 调用 planning-with-files — 初始化三个追踪文件：

   • 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
   • 格式示例：

     ## 迭代 #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 仓库），同样执行完整工作流。