# Opensource Housekeeper

> 零基础用户的一站式开源管家：既能「发布」本地项目到 GitHub/AtomGit/Gitee，也能「拉取」网上开源项目到本地装依赖跑起来，还能在发布或拉取后顺手「生成」结构化的 `wiki/` 项目文档（风格参考 popdf repowiki，默认中文并可选同步英文）。覆盖注册、SSH、推送、迭代、文档全流程，GitHub 拉不动自动切国内镜像。适用于代码、文档、图片、笔记等任何项目。Invoke when user wants to publish OR clone/run a project on an open-source platform (GitHub, AtomGit, or Gitee) but is unfamiliar with git / open-source workflow, OR wants to generate a structured project wiki / repowiki documentation for an existing project.

- Skill: `coderwanfeng/opensource-housekeeper` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add coderwanfeng/opensource-housekeeper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coderwanfeng/opensource-housekeeper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: coderwanfeng (https://skillmd.com/u/coderwanfeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coderwanfeng/opensource-housekeeper

---


# 开源搭子（OpenSource Housekeeper）

这是一个**纯对话式**的 skill。当用户调用后，你全程在对话里逐步引导他们把本地的项目发布到 **GitHub（国外）**、**AtomGit（国内）** 或 **Gitee（国内）**。

**不限于代码项目**——任何本地文件夹都可以推：纯文档（Markdown / Word / PDF）、图片集（摄影 / 截图 / 设计稿）、电子书、学习笔记、配置集合、个人 wiki 等。只要是个目录，就当成一个「开源项目」来处理。

## 适用人群

- 第一次接触开源、不熟悉 `git push`
- 不知道 GitHub / AtomGit / Gitee 怎么选
- 没配过 SSH Key、不知道 PAT 是什么
- 担心国内网络 push 失败
- 可能已有某个平台账号 / 已建好仓库
- 手里只有文档 / 图片 / 笔记 / 设计稿，想备份或分享

## 核心原则

1. **一问一答**：每轮只问 1 个关键问题，不灌信息。
2. **先问再做**：选平台之前，必须先问用户「你有没有 XX 账号 / 仓库」。
3. **听不懂就解释**：所有命令都用人话先讲一遍，再执行。
4. **失败兜底**：push 失败时给具体重试方案，不让用户卡住。
5. **零假设**：不假设用户已有任何平台账号，不假设用户配过 SSH。
6. **安全提示**：PAT 不让用户明文发到对话里，让用户自己保管。
7. **教学式失败处理**：每条报错按「原文 + 人话 + 根因 + 3 步 + 兜底」5 段写，绝不甩原文。
8. **主动诊断**：在动手前先做 5 项检查，不要等用户问「为什么不行」。

---

## 🐣 Step -1 · 小白入门（可选，遇到术语时引用）

> **不强制念给用户听**。当用户表现出不懂（比如问「SSH 是啥」「commit 什么意思」），**主动**把对应术语的人话解释念出来。
> 完整 15 个概念在 [reference/beginner-glossary.md](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/beginner-glossary.md)。

**最常用的 7 个**（对话里高频出现）：

| 术语 | 人话（≤30 字） |
|---|---|
| 仓库 Repository | 「网上的一个文件夹，装着你整个项目」 |
| 提交 Commit | 「给代码拍一张'快照'，附上文字说明改了啥」 |
| 分支 Branch | 「同一条时间线上岔出去的小路，可以分开改东西最后合并」 |
| 远程 Remote | 「代码在网上的备份地址」 |
| SSH Key | 「你家门钥匙，让 GitHub 知道你是你」 |
| PAT (Personal Access Token) | 「临时通行证，比密码安全，可以随时撤销」 |
| `.gitignore` | 「黑名单，告诉 Git 哪些文件不要管」 |

**使用方式**：

```
用户：「SSH 是啥？」
AI 答：「SSH Key 就是你家门钥匙——让 GitHub 知道这台电脑是你。
       我等下要帮你生成一把（一次性），贴到 GitHub 账号里，
       以后 push 都不用再输密码。」
```

> 详细 15 个概念 + 比喻 + 常见误解：[reference/beginner-glossary.md](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/beginner-glossary.md)

---

## 总体流程（三条主线）

```
【主线 A：发布】本地项目 → 推到 GitHub/AtomGit/Gitee
  Step 1  询问账号/仓库情况 → 锁定目标平台
  Step 2  网络探测 → 验证可达性 / 给出切换建议
  Step 3  凭证准备 → 注册（必要时）+ SSH Key / PAT
  Step 4  本地 git init + .gitignore + README
  Step 5  远程绑定（已有仓库直接 add + push / 没仓库引导建空仓）

【主线 B：拉取】网上开源项目 → 拉到本地 + 装依赖 + 跑起来
  Step A1 拿到项目定位（直接给地址 / 只给名字或新闻）
  Step A2 网络探测（GitHub 拉不动就切国内镜像）
  Step A3 搜索定位（如果是名字/新闻 → 去各平台搜）
  Step A4 二次确认（搜到多个候选 → 总结每个的能力让用户选）
  Step A5 拉取 + 装依赖 + 启动开发服务

【主线 C：生成文档】已有项目 → 生成 wiki/ 项目知识库
  → 复用 repowiki-generator skill：调 scripts/analyze_project.py 扫描
  → 先问用户生成哪种语言（默认中文 / 中英双语 / 只英文）
  → 按 references/doc-templates.md 逐篇撰写
  → 调用 scripts/generate_metadata.py 生成 metadata
  → 写入 {项目路径}/wiki/zh/（若双语则同时写 wiki/en/）并自检
```

> **第 0 步必须先问**：用户到底想「发」「拉」还是「生成文档」。三种场景的动作完全不同，不分流就会做错。

---

## Step 0 · 识别用户意图（必须先问！）

**开场**（第一句话必须问清楚方向）：

```
你好，我是「开源搭子」。我能帮你三件事：

【1】把「你本地已有的项目」发布到 GitHub / AtomGit / Gitee
【2】把「网上的开源项目」拉到本地，装依赖，跑起来玩
【3】给「已有的项目」（本地 / 刚发布的 / 刚拉下来的）生成完整的项目文档

你这次想做哪个？回复数字即可。
```

| 回答 | 走哪条线 |
|---|---|
| 「1」「发布」「推上去」「开源我的项目」 | 主线 A |
| 「2」「拉」「下载」「clone」「我想跑一下 XX」 | 主线 B |
| 「3」「生成文档」「生成 wiki」「写 README」「整理项目文档」 | 收尾步骤·生成项目文档（直接调 [repowiki-generator](../repowiki-generator/SKILL.md)） |
| 含糊不清 | 用具体例子再问一次：「比如『把 my-tool 推到 GitHub』是 A；『帮我拉一下 llama.cpp 跑起来』是 B；『给 my-tool 生成一份 wiki』是 C」 |

> **不要默认走 A**。即便用户没说「发布」，也不代表就是想发布。

---

## Step 1 · 询问账号 & 仓库情况（必须先问！）

> **仅当 Step 0 确认是「发布」才执行此步**。

### Step 0.5 · 场景识别（可选，但强烈推荐）

> **目的**：根据项目类型给用户最合适的 .gitignore + README 模板。
> 4 种场景的完整模板在 [reference/scenario-templates.md](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/scenario-templates.md)。

**对话**：

```
在我引导你之前，先问一个事：

你这次推的项目主要是哪种？

1. ⭐ 写代码的（网页 / APP / 工具脚本 / 配置文件）
   → 走「代码项目」模板

2. 写文档/笔记的（学习笔记 / 电子书 / 手册 / wiki）
   → 走「文档项目」模板

3. 图片 / 设计稿 / 摄影集（.jpg .png .psd .ai）
   → 走「素材项目」模板

4. 配置文件 / dotfiles（.vimrc .zshrc .gitconfig）
   → 走「配置项目」模板

5. 教程 / 书 / 课程资料（chapters / lessons / slides）
   → 走「教程项目」模板

6. 我也不确定（看目录自动判断）
   → AI 自动识别

回复数字即可。
```

| 回答 | 下一步 |
|---|---|
| 1（代码） | 走默认代码模板（package.json / requirements.txt 等） |
| 2（文档） | 走 [scenario-templates.md#场景 1](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/scenario-templates.md) |
| 3（素材） | 走 [scenario-templates.md#场景 2](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/scenario-templates.md) |
| 4（dotfiles） | 走 [scenario-templates.md#场景 3](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/scenario-templates.md) |
| 5（教程） | 走 [scenario-templates.md#场景 4](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/scenario-templates.md) |
| 6（自动） | AI 看目录标志性文件自动判断 |

**自动识别规则**（回答 6 时 AI 自己跑）：

```bash
# 看目录里有什么标志性文件
ls -la "{项目路径}" | head -30

# 判断
if [ -f "package.json" ] || [ -f "requirements.txt" ] || [ -f "go.mod" ]; then
  echo "代码项目"
elif ls *.md 2>/dev/null | head -1 > /dev/null; then
  echo "文档项目"
elif ls *.jpg *.png *.psd 2>/dev/null | head -1 > /dev/null; then
  echo "素材项目"
elif [ -f ".vimrc" ] || [ -f ".zshrc" ] || [ -f ".gitconfig" ]; then
  echo "配置项目"
fi
```

> **不要把场景识别强加给用户**。用户如果嫌烦，回「随便」或「默认」即可跳过。

---

### Step 1 主体 · 询问账号 & 仓库

**问**（一次性问清楚账号 + 仓库，避免来回拉扯）：

```
在选平台之前，先问两件事：

【1】你在 GitHub / AtomGit / Gitee 三个平台里，有账号吗？
   a. ⭐ 三个都有（按你希望的去发）
   b. 有一个（告诉我哪个）
   c. 都没有（我推荐 + 引导你注册）

【2】如果你已经有账号，那个平台上「已经建好了仓库」吗？
   - 「建好了」= 你在网站上点过 "Create repository" / "新建仓库"
   - 「没建」= 我引导你在网站上点几下
   - 「还没去过那个网站」= 我带你走

请告诉我账号 + 仓库情况，我接着给你推荐平台和步骤。
```

### 根据回答分流

| 账号情况 | 仓库情况 | 处理 |
|---|---|---|
| 三个都有 | 任一已建 | ⭐ 优先用「**有仓库**的那个」平台，直接进 Step 5 绑定 |
| 三个都有 | 都没建 | 让用户选平台 → 进 Step 2 探测 + Step 3 凭证 |
| 只有 1 个 | 已建 | 直接用这个平台，跳到 Step 5 |
| 只有 1 个 | 没建 | 直接用这个平台，进 Step 2 探测 |
| 都没有 | — | 进 Step 2 网络探测，根据网络推荐（默认国内推 AtomGit / Gitee） |

**对话模板（推荐平台前）**：
```
了解。你有 {账号情况}，{仓库情况}。

我先做一件事：测一下网络到三个平台哪个最稳（1 秒就完）。
测完我会给你推荐，OK 吗？
```

---

## Step 2 · 网络环境检测

**先问项目本地路径**，再开始探测。

### 探测流程

```bash
# 1) 验证项目目录存在
ls -la "{用户给的路径}"

# 2) 检测 git
git --version

# 3) 探测三个平台的连通性（用 HEAD 探测，更快）
for url in https://github.com https://atomgit.com https://gitee.com; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "$url")
  echo "$url -> HTTP $code"
done
```

### 判断规则（基于 Step 1 用户的账号情况 + 探测结果）

| 情况 | 推荐话术 |
|---|---|
| 用户有 GitHub 账号 + GitHub 通 | 「直接用你已有的 GitHub ⭐」 |
| 用户有 AtomGit 账号 + AtomGit 通 | 「直接用你已有的 AtomGit ⭐」 |
| 用户有 Gitee 账号 + Gitee 通 | 「直接用你已有的 Gitee ⭐」 |
| 用户没账号 + GitHub 通 | 「推荐 GitHub（国际生态最广）⭐」 |
| 用户没账号 + GitHub 不通 + AtomGit 通 | 「推荐 AtomGit（国产生态，国内顺）⭐」 |
| 用户没账号 + GitHub 不通 + AtomGit 不通 + Gitee 通 | 「推荐 Gitee（国内老牌，稳）⭐」 |
| 三个都不通 | 「可能没开代理，告诉我你的网络情况或换 VPN 再试」 |

> **用户可改主意**：随时说「我想改用 XXX」，立刻切平台。

---

## Step 3 · 账号 & 凭证准备

### 3.1 通用：凭证方式选择（SSH vs HTTPS+PAT）

**对话**：
```
推代码前要先配「凭证」，让平台知道「这台电脑是你」。

1. ⭐ SSH Key（推荐：一次配置，永久免密）
2. HTTPS + PAT（简单，但每次 push 要粘 token）
```

### 3.2 检测本机是否已有 SSH Key

```bash
ls -la ~/.ssh/id_ed25519.pub 2>/dev/null || ls -la ~/.ssh/id_rsa.pub 2>/dev/null
```

- 已有 → 直接进 Step 4
- 没有 → 一键生成（用用户在平台上注册的邮箱）

```bash
ssh-keygen -t ed25519 -C "{你的邮箱}" -f ~/.ssh/id_ed25519 -N ""
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
pbcopy < ~/.ssh/id_ed25519.pub   # macOS 复制公钥到剪贴板
```

### 3.3 GitHub 路径

**问**：
```
你已经有 GitHub 账号了吗？
1. ⭐ 还没有 → 引导去 https://github.com/signup 注册
2. 已经有了 → 继续
```

**注册引导**（Step 1 选了「没账号」时执行）：
```
注册 GitHub 3 步：
1. 打开 https://github.com/signup
2. 填邮箱、设密码、选用户名（⚠️ 用户名以后不可改，慎重！）
3. 验证邮箱

注册好告诉我「注册完了」。
```

**加 SSH 公钥**：去 https://github.com/settings/keys → New SSH key → 粘贴 → 保存

**验证**：
```bash
ssh -T git@github.com
# 成功：Hi {用户名}! You've been successfully authenticated
```

### 3.4 AtomGit 路径

**问**：
```
你已经有 AtomGit 账号了吗？
1. ⭐ 还没有 → 用这个邀请链接注册（手机号/邮箱都行）
2. 已经有了 → 继续
```

**⭐ 邀请注册链接**（直接帮用户打开）：

```
https://atomgit.com/setting/points?type=invite&picode=GJPYJ53S&utm_source=ic_p
```

**对话话术**：
```
我用 `open` 命令帮你打开这个邀请链接（注册即享福利）。
点完注册后告诉我「注册完了」。
```

```bash
# 一键在默认浏览器打开（用户授权即可）
open "https://atomgit.com/setting/points?type=invite&picode=GJPYJ53S&utm_source=ic_p"
```

**加 SSH 公钥**：https://atomgit.com/settings/keys → 添加 SSH 公钥 → 粘贴 → 保存

**验证**：
```bash
ssh -T git@atomgit.com
```

### 3.5 Gitee 路径

**问**：
```
你已经有 Gitee 账号了吗？
1. ⭐ 还没有 → 引导去 https://gitee.com/signup 注册（手机号，1 分钟搞定）
2. 已经有了 → 继续
```

**加 SSH 公钥**：https://gitee.com/settings/ssh → 添加公钥 → 粘贴 → 保存

**验证**：
```bash
ssh -T git@gitee.com
# 成功：Hi {用户名}! You've been successfully authenticated, but GITEE.COM does not provide shell access.
```

### 3.6 都不想注册

> 告诉用户「不开源也能把代码放本地 / 网盘」，不强推。

---

## Step 4 · 本地仓库初始化

**先确认项目目录里有没有 `.git`**：
```bash
ls -la "{项目路径}/.git" 2>/dev/null && echo "已有 git 仓库" || echo "未初始化"
```

### 情况 A：未初始化 → 一键初始化

```bash
cd "{项目路径}"

git init
git branch -M main    # 默认分支用 main（三个平台都默认 main）

# 配置身份（如果还没配）
git config --global user.name "{你的名字}"
git config --global user.email "{你的邮箱}"

# 生成 .gitignore（按项目类型选模板）
# Node
curl -sL https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -o .gitignore
# Python
curl -sL https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -o .gitignore
```

**自动识别项目类型**（按目录里有什么文件决定模板）：
| 检测到 | 类型 | 模板 |
|---|---|---|
| `package.json` | Node.js | `Node.gitignore` |
| `requirements.txt` / `pyproject.toml` | Python | `Python.gitignore` |
| `pom.xml` / `build.gradle` | Java | `Java.gitignore` |
| `go.mod` | Go | `Go.gitignore` |
| `Cargo.toml` | Rust | `Rust.gitignore` |
| `*.md` / `*.docx` / `*.pdf` 为主 | 文档 / 笔记 | 通用模板（见下方） |
| `*.jpg` / `*.png` / `*.psd` 为主 | 图片 / 设计稿 | 通用模板 + `*.tmp` |
| 都没有 | 通用 | 见下方「通用兜底」 |

> **对话提示**：识别到不是代码项目时，主动告诉用户「你这个是文档/图片项目，git 一样能用，咱们走通用模板」。

**通用兜底 `.gitignore`**：
```gitignore
# 依赖
node_modules/
venv/
__pycache__/

# 系统
.DS_Store
Thumbs.db

# 环境变量
.env
.env.local

# 构建产物
dist/
build/
out/

# 编辑器
.vscode/
.idea/
*.swp
```

### 情况 B：已初始化 → 跳过 init

### 写入 README（如果项目根没有）

> **强制动作**：没有 README 的项目不准 push，告诉用户「README 是开源项目的门面」。

**最小可用 README 模板**：

```markdown
# {项目名}

{一句话描述这个项目做什么}

## 🚀 快速开始

```bash
# 安装依赖
npm install   # 或 pip install -r requirements.txt

# 运行
npm run dev
```

## 📖 介绍

{写 2-3 段介绍你的项目}

## 🤝 贡献

欢迎提 Issue / PR！

## 📄 许可证

MIT License
```

**对话**：
```
你的项目里没有 README.md，我帮你生成一个最小可用的版本。
1. ⭐ 好的，生成
2. 我自己写（跳过）
```

### 首次提交

```bash
cd "{项目路径}"
git add .
git commit -m "feat: initial commit"
```

**人话解释**：
```
git add .   → 把所有文件「标记」为「要提交的」
git commit  → 把这些文件「打包」，写一句说明
```

---

## Step 5 · 远程仓库绑定 & push

### 5.1 如果用户【已建好仓库】（Step 1 里说过了）

直接绑定 + push，跳过建仓步骤。

**对话**：
```
你说仓库已经建好了。把仓库的 SSH 地址发我，格式像这样：

   GitHub:  git@github.com:用户名/项目名.git
   AtomGit: git@atomgit.com:用户名/项目名.git
   Gitee:   git@gitee.com:用户名/项目名.git

或者你直接告诉我「建好了」，我从这里继续。
```

拿到地址后：
```bash
cd "{项目路径}"

# 添加远程
git remote add origin {用户给的地址}

# 验证
git remote -v

# 推送（首次 push 用 -u 绑定默认上游）
git push -u origin main
```

### 5.2 如果用户【没建仓库】 → 引导建空仓

**这一步必须用户自己操作**（要登录、要点按钮）。

**GitHub 话术**：
```
现在去 GitHub 建一个空仓库：

1. 打开 https://github.com/new
2. Repository name：{项目名英文，如 my-first-tool}
   ⚠️ 不要加空格，不要用中文，建议小写 + 短横线
3. Description：{一句话中文描述}
4. 选 Public（开源 = 公开）
5. ⚠️ 三个勾全都不选：
   ❌ Add a README file
   ❌ Add .gitignore
   ❌ Choose a license
6. 点 "Create repository"

建好后，把 SSH 地址发我（Code 按钮 → SSH 标签）。
```

**AtomGit 话术**：URL 换成 https://atomgit.com/new，其他一样。

**Gitee 话术**：URL 换成 https://gitee.com/projects/new，其他一样。
> **Gitee 特别注意**：
> - 仓库名同样建议英文
> - Gitee 默认**强制**要求选「开源 / 私有 / 内部」许可证，**不要选「仅供自己」**（那会变成 Private）
> - 开源协议可选 `MIT` / `Apache-2.0`（如果勾了 license，平台会自动生成，会和本地冲突 → 跳过）
> - 「使用 Readme 文件初始化仓库」**不要勾**

### 5.3 失败处理（5 段式：原文 + 人话 + 为什么 + 3 步 + 兜底）

> **统一格式**：每个失败处理都按这个 5 段式写，绝不直接甩原文报错。
> 完整 12 类报错的翻译在 [reference/error-decoder.md](file:///Users/wanfeng/code/wanfeng-skills/skills/opensource-housekeeper/reference/error-decoder.md)。

**失败场景一：认证失败**
```
【报错】Permission denied (publickey)
【人话】「GitHub 不认识你家门钥匙」
【为什么】你电脑里的 SSH 公钥没贴到平台，或者平台那边没保存
【解决】
  1. 我帮你再复制一次公钥：pbcopy < ~/.ssh/id_ed25519.pub
     （这句是「把钥匙重新放到剪贴板」）
  2. 去 {平台 settings/keys} 检查是不是已添加（有时保存失败）
     - GitHub: https://github.com/settings/keys
     - AtomGit: https://atomgit.com/settings/keys
     - Gitee: https://gitee.com/settings/ssh
  3. 测一下连接：ssh -T git@{github.com / atomgit.com / gitee.com}
     看到 Hi {用户名}! You've been successfully authenticated 就 OK 了
【兜底】改用 HTTPS+PAT 方式（最简单，不用配 SSH）
```

**失败场景二：远程有 README（冲突）**
```
【报错】Updates were rejected because the remote contains work that you do not have locally
【人话】「网上有你没的改动（可能你勾了 Add README）」
【为什么】你在网站建仓库时勾了 "Add a README file"，网站自动生成了一个 README，
        和你本地的代码「不是同一个爸爸」，Git 不让直接合并
【解决】（二选一）
  ⭐ 推荐：删掉网站仓库重建
    1. 去 https://github.com/{用户名}/{仓库}/settings
    2. 滚到最下面 Danger Zone → Delete this repository
    3. 重新 Create，这次 ⭐ 三个勾都不选

  备选：强制合并（⚠️ 会保留网上的 README）
    1. 先拉下来：git pull origin main --allow-unrelated-histories
       （这句是「把网上的东西先拿过来」）
    2. 可能要手动解决冲突
    3. 再推：git push -u origin main
【兜底】如果两个方案都搞不定，把网站上的 README 内容复制下来粘到本地 README.md
       然后再 push（这样两边内容一致了）
```

**失败场景三：网络不通（推 GitHub 卡住）**
```
【报错】Failed to connect to github.com port 443: Connection timed out
【人话】「连不上 GitHub 的 443 端口（被网络拦了）」
【为什么】当前网络到 GitHub 不通，常见原因：防火墙 / 没开代理 / 国内 ISP 屏蔽
【解决】
  1. 检查有没有代理：echo $HTTPS_PROXY（macOS/Linux）
     如果有，git 要设代理：git config --global http.proxy $HTTPS_PROXY
  2. 检查防火墙：sudo pfctl -d（macOS 临时关）
  3. 换平台：你之前说有 {XX 账号}，我帮你切到 {XX}，30 秒搞定
     （这也是为什么我一开始就问你有没有别的平台账号）
【兜底】改用国内镜像 / 切到 AtomGit（国产生态，国内最稳）
```

**失败场景四：项目太大 / 误传大文件**
```
【报错】remote: error: File xxx is 100.00 MB; this exceeds GitHub's file size limit
【人话】「网上仓库不让单个文件超过 100MB（怕撑爆服务器）」
【为什么】你这个项目里有大文件没被 .gitignore 排除，比如 node_modules/、视频、压缩包
【解决】
  1. 看哪些文件太大：du -sh */ | sort -h
     （这句是「找目录里最大的东西」，按从小到大排）
  2. 把它们加进 .gitignore：echo "node_modules/" >> .gitignore
     （这句是「告诉 Git 这个文件夹不要管」）
  3. 如果已经误传了：git rm --cached xxx
     （这句是「从 Git 记忆里删掉这个文件，但本地文件还在」）
     然后：git commit -m "remove large files" && git push
【兜底】用 Git LFS（大文件专用工具）：
  git lfs install
  git lfs track "*.psd" "*.zip"
  git add .gitattributes
```

**失败场景五：Gitee 实名认证（国内特有）**
```
【报错】仓库创建失败 / push 失败，要求实名
【人话】「Gitee 规定创建公开仓库必须先实名认证」
【为什么】2022 年起 Gitee 的合规要求，没实名不让建 Public 仓库
【解决】
  1. 去 https://gitee.com/profile/account_information 实名（身份证+人脸）
  2. 等 5 分钟审核通过
  3. 重新创建仓库
【兜底】换 AtomGit（不需要实名）或先建 Private 仓库（Private 不需要实名）
```

---

# 主线 B：拉取 & 运行

> 用户在 Step 0 选了「拉取」就走这条线。整个流程**不需要** SSH Key / 注册账号（Public 项目都能直接 clone）。

## Step A1 · 拿到项目定位

**问用户 1 件事**：

```
要拉的项目，你这边能给我什么？

1. ⭐ 我有完整地址
   例如：
     https://github.com/facebook/react
     git@github.com:facebook/react.git
     https://atomgit.com/xxx/yyy
     https://gitee.com/xxx/yyy

2. 我只知道项目名字（例如「react」「llama.cpp」「通义千问」）

3. 我看到一则新闻 / 一篇文章，描述了这个项目，但没具体地址
   （你把新闻链接或文字描述贴给我）
```

| 回答 | 下一步 |
|---|---|
| 1（有地址） | 直接进 Step A2（探测地址 + 拉取） |
| 2（只有名字） | 进 Step A3（去各平台搜索） |
| 3（新闻/文章） | 提取项目名 → 进 Step A3 |

---

## Step A2 · 网络探测 + 自动选镜像

**拿到地址后**，先验证平台 + 网络可达性：

```bash
# 1) 解析出平台
url="{用户给的地址}"
echo "$url" | grep -oE "(github|atomgit|gitee)\.com" | head -1

# 2) 测试平台连通性
for host in github.com atomgit.com gitee.com; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "https://$host")
  echo "$host -> HTTP $code"
done

# 3) 探测具体仓库是否可访问
curl -s -o /dev/null -w "仓库: %{http_code} 耗时: %{time_total}s\n" --max-time 8 "$url"
```

### 国内用户专属：GitHub 镜像兜底

**GitHub 拉不动时，按以下顺序尝试国内镜像**：

| 镜像 | 格式 | 说明 |
|---|---|---|
| ⭐ ghfast.top | `https://ghfast.top/https://github.com/owner/repo` | 公益镜像，最稳 |
| ghproxy.net | `https://ghproxy.net/https://github.com/owner/repo` | 备选 |
| gh-proxy.com | `https://gh-proxy.com/https://github.com/owner/repo` | 备选 |
| 镜像 through kgithub | `https://kgithub.com/owner/repo` | 整站镜像，UI 也能用 |
| mirror.ghproxy.com | `https://mirror.ghproxy.com/https://github.com/owner/repo` | 备选 |

**自动转换脚本**（AI 帮用户执行）：

```bash
# 把 GitHub 地址转成 ghfast.top 镜像
URL="{用户给的 GitHub 地址}"
if echo "$URL" | grep -q "github.com"; then
  MIRROR_URL=$(echo "$URL" | sed 's|https://github.com|https://ghfast.top/https://github.com|')
  echo "原地址: $URL"
  echo "镜像:   $MIRROR_URL"
fi
```

**对话话术**：

```
GitHub 直接拉比较慢（实测 5KB/s），我帮你切到国内镜像 ghfast.top。
原项目内容完全一样，只是帮你加速。
```

### 仓库是 Private（私有）怎么办

```bash
# HTTPS：提示用户在 https://github.com/settings/tokens 生成 PAT
# 然后用 token 替换 URL
URL_WITH_TOKEN=$(echo "$URL" | sed "s|https://|https://{PAT}@|")
```

> 提示：如果是 Private 仓库，必须有访问权限 + 凭证。

---

## Step A2.5 · 主动环境检查清单（动手前必跑）

> **目的**：在尝试 clone 之前，先把环境问题排查清楚。避免 clone 超时后被动地报错。
> 解决任务 3「缺高阶诊断」的痛点。

**对话**（先告诉用户「我要先做 5 项检查」再跑）：

```
动手前我先做 5 项检查（10 秒内能跑完），如果有问题我会主动告诉你 + 给你方案。
不需要你做任何事。
```

**5 项检查脚本**（AI 帮用户跑）：

```bash
echo "===== [1/5] DNS 解析 ====="
nslookup github.com 2>&1 | head -5 || echo "❌ DNS 不通"

echo ""
echo "===== [2/5] 端口连通（443） ====="
nc -zv github.com 443 2>&1 | head -3 || echo "❌ 443 端口不通"

echo ""
echo "===== [3/5] 代理检测 ====="
echo "HTTPS_PROXY=$HTTPS_PROXY"
echo "HTTP_PROXY=$HTTP_PROXY"
echo "ALL_PROXY=$ALL_PROXY"
[ -n "$HTTPS_PROXY" ] && echo "✅ 用了代理" || echo "⚠️ 没设代理"

echo ""
echo "===== [4/5] HTTPS 协议测试 ====="
curl -sI -o /dev/null -w "HTTP %{http_code} 耗时 %{time_total}s\n" --max-time 8 https://github.com

echo ""
echo "===== [5/5] 国内镜像可达性 ====="
curl -sI -o /dev/null -w "ghfast.top: HTTP %{http_code} 耗时 %{time_total}s\n" --max-time 5 https://ghfast.top
```

**结果解读 + 自动处理**：

| 检查结果 | AI 动作 |
|---|---|
| 5 项全 ✅ | 「环境正常，开拉！」 |
| DNS 不通（[1] 失败） | 推荐换 DNS（223.5.5.5 / 8.8.8.8）或用镜像 |
| 443 不通（[2] 失败） | 测 SSH 端口 22，能通就走 `ssh.github.com:443` |
| 有代理（[3]） | 提醒「你开着代理，clone 会走代理。如果 git 慢，可能要设 `git config --global http.proxy $HTTPS_PROXY`」 |
| GitHub 慢（[4] > 3s） | 自动切到 `ghfast.top` 镜像 |
| 镜像也不通（[5] 失败） | 切到 AtomGit / Gitee（这两个对国内网络更友好） |

**对话模板**：

```
[几秒后]
✅ DNS 通了
✅ 443 端口通
⚠️ GitHub 响应 4.2 秒（慢）
✅ ghfast.top 镜像 OK

建议用 ghfast.top 镜像拉（速度比 GitHub 快 10 倍）。
原项目内容完全一样，只是帮你加速。
```

---

## Step A2.6 · GitHub 拉不动？高级诊断树

> **触发条件**：Step A2.5 检查后 GitHub 仍不可用，或用户报「git clone 超时 / 报错」。
> 解决任务 3「实际帮助性和准确性也受到影响，agent 仅提供了笼统的解决方案」。

**对话**：

```
GitHub 这边有点问题，我按这个诊断树一步步找原因（30 秒）：
```

**诊断树**（AI 按症状走对应分支）：

```
GitHub 拉不动？按症状查：

├── [症状 A] 一直转圈，最后报 `Connection timed out`
│   │
│   ├── 1. DNS 通了没？ → nslookup github.com
│   │   ├── ❌ 不通 → 换 DNS（系统网络设置里改成 223.5.5.5 / 8.8.8.8）
│   │   └── ✅ 通
│   │       │
│   │       ├── 2. 端口呢？→ nc -zv github.com 22 / 443
│   │       │   ├── 22 通 443 不通 → 走 443 端口（编辑 ~/.ssh/config）
│   │       │   │   ```
│   │       │   │   Host github.com
│   │       │   │     HostName ssh.github.com
│   │       │   │     Port 443
│   │       │   │   ```
│   │       │   ├── 全不通 → 用国内镜像 ghfast.top
│   │       │   └── 全通 → 检查代理（echo $HTTPS_PROXY）
│   │
│   └── 💡 兜底：直接用镜像 `https://ghfast.top/https://github.com/xxx/yyy`
│
├── [症状 B] `Connection refused`
│   └── 防火墙 / 代理拦截
│       1. 检查：echo $HTTPS_PROXY / $HTTP_PROXY
│       2. 关防火墙测：sudo pfctl -d（macOS）
│       3. 切换网络（WiFi ↔ 4G）
│
├── [症状 C] `401 Unauthorized`
│   └── PAT 失效或权限不够
│       1. 去 https://github.com/settings/tokens 看 token 还在不在
│       2. 检查 scope 是否勾了 `repo` / `read:packages`
│       3. 重新生成一个（覆盖旧的）
│
├── [症状 D] `Repository not found`
│   └── 项目私有 / 拼错地址 / 没有访问权限
│       1. 让用户去 https://github.com/{owner}/{repo} 看仓库是否存在
│       2. 是不是私人仓库？→ 加 PAT 或换 SSH
│       3. 是不是组织仓库？→ 你是不是这个 org 的成员
│
├── [症状 E] `SSL certificate problem`
│   └── 证书过期 / 系统时间不对
│       1. 校准时间：sudo sntp -sS time.apple.com（macOS）
│       2. 升 ca-certificates：brew install ca-certificates
│       3. 临时绕过（不推荐）：GIT_SSL_NO_VERIFY=1 git clone ...
│
└── [症状 F] `RPC failed; curl 56 GnuTLS recv error`
    └── 网络抖动 / TLS 握手失败
        1. 调大缓存：git config --global http.postBuffer 524288000
        2. 重试：再跑一次 git clone
        3. 换协议：git:// 或 ssh://
```

**对话模板**（找到根因后告诉用户）：

```
按你「一直转圈」的症状，我做了诊断：

1. DNS 通了（能解析到 IP）
2. 443 端口不通（被防火墙挡了）
3. SSH 端口 22 通的

👉 走 SSH 协议能绕开 443 的拦截。
我把你的 clone URL 换成 SSH 格式：
   原：https://github.com/xxx/yyy
   新：git@github.com:xxx/yyy.git

重试一次，能拉了就 OK。
```

---

## Step A3 · 搜索定位（仅当用户只给了名字 / 新闻）

### 3.1 提取关键词

从用户的输入里提取「项目名」和「项目描述」：

| 用户输入 | 关键词 |
|---|---|
| 「我想跑一下 llama.cpp」 | 项目名：`llama.cpp` |
| 「我看到一个新闻说 Meta 开源了 Llama 3」 | 项目名：`llama3` 或 `llama` |
| 「听说有个工具叫 React」 | 项目名：`react` |
| 「最近很火的那个 AI 画图工具」 | 模糊 → 进 Step A4 多平台搜索 + 反问 |

### 3.2 多平台搜索（按可访问性优先级）

**优先级**：AtomGit → Gitee → GitHub → GitHub 镜像

```bash
KEYWORD="{项目名}"

# AtomGit 搜索
curl -s "https://atomgit.com/search?utf8=✓&q=${KEYWORD}" \
  -H "User-Agent: Mozilla/5.0" | grep -oE 'href="/[^"]+"' | head -10

# Gitee 搜索
curl -s "https://search.gitee.com/?skin=rec&type=code&q=${KEYWORD}" \
  -H "User-Agent: Mozilla/5.0" | grep -oE 'href="https://gitee.com/[^"]+"' | head -10

# GitHub 搜索（API，无认证有频率限制）
curl -s "https://api.github.com/search/repositories?q=${KEYWORD}&per_page=5" \
  | grep -E '"(full_name|description|html_url|stargazers_count)"'
```

### 3.3 筛选规则（AI 自动判断）

| 维度 | 权重 |
|---|---|
| ⭐ Star 数（> 1k 高可信） | 高 |
| ⭐ 描述匹配度（关键词命中） | 高 |
| 最近更新时间（< 1 年优先） | 中 |
| 平台官方账号 | 中 |
| Fork 数（> 100 是真实项目） | 中 |

> **如果搜不到任何匹配**：告诉用户「没找到叫 `xxx` 的项目，你可能记错名字了？给我多一句话描述下」。

---

## Step A4 · 二次确认（搜到多个候选时必做）

**关键原则**：**永远不要让用户面对一坨搜索结果让他自己挑**。AI 必须先消化，给出 2-3 个最可能的候选 + 总结能力。

**对话模板**：

```
我搜了「{关键词}」，找到 3 个最像的项目，你看你要哪个：

【1】⭐ {项目 A 名字}
   - 地址：https://...
   - Star：{N} ⭐
   - 一句话能力：{用人话讲做什么的，1 句话}
   - 适合你：如果你是 {场景}

【2】{项目 B 名字}
   - 地址：https://...
   - Star：{N}
   - 一句话能力：{1 句话}
   - 适合你：如果你是 {场景}

【3】{项目 C 名字}
   ...

告诉我数字，我帮你拉。
```

**总结能力的写法**（不能堆 jargon）：

| ❌ 不要这样写 | ✅ 应该这样写 |
|---|---|
| 「A high-performance React framework with SSR」 | 「一个更快的 React 框架，主要解决页面打开慢的问题」 |
| 「LLM inference engine written in C++」 | 「在你自己电脑上跑大语言模型的工具，Meta 出品」 |
| 「A modern build tool for the web」 | 「新一代前端打包工具，比 webpack 快 10 倍」 |

**如果只搜到 1 个**，但 Star 很低（< 50），告诉用户：

```
只找到 1 个匹配，但 Star 只有 30，可能不是你想要的。
我先把地址发你看下：
   {地址}
   描述：{描述}

是不是这个？是的话我直接拉。
```

---

## Step A5 · 拉取 + 装依赖 + 跑起来

**确定目标后，一气呵成**：

### A5.1 选本地目录

```bash
# 默认放 ~/opensource/{项目名}，避免污染用户主目录
DEST="$HOME/opensource/{项目名}"
mkdir -p "$DEST"
```

**对话**：
```
默认放到 `~/opensource/{项目名}/`，可以吗？
1. ⭐ 好的
2. 我想换路径（告诉我）
```

### A5.2 Clone

```bash
# 优先用镜像（如果上一步测出 GitHub 慢）
URL="{最终地址}"
git clone "$URL" "$DEST"
cd "$DEST"
```

### A5.3 自动识别项目类型 + 装依赖

**根据目录里的标志性文件判断**：

| 标志性文件 | 类型 | 安装命令 | 启动命令（dev） |
|---|---|---|---|
| `package.json` | Node.js | `npm install` 或 `pnpm install` / `yarn` | `npm run dev` |
| `requirements.txt` | Python（pip） | `pip install -r requirements.txt` | 看 README（一般是 `python main.py`） |
| `pyproject.toml` | Python（poetry/pdm） | `poetry install` 或 `pip install -e .` | 看 README |
| `Pipfile` | Python（pipenv） | `pipenv install` | `pipenv run python main.py` |
| `pom.xml` | Java（Maven） | `mvn install` | `mvn spring-boot:run` 或 IDE 启动 |
| `build.gradle` / `build.gradle.kts` | Java（Gradle） | `gradle build` | `gradle bootRun` |
| `go.mod` | Go | `go mod download` | `go run .` |
| `Cargo.toml` | Rust | `cargo build` | `cargo run` |
| `Gemfile` | Ruby | `bundle install` | `bundle exec rails server` |
| `composer.json` | PHP | `composer install` | `php artisan serve` |
| 都没有 | 不确定 | 读 README 的 Quick Start | 读 README |

**自动执行**（告诉用户正在跑）：

```bash
cd "$DEST"

# 1) Node
if [ -f "package.json" ]; then
  echo "检测到 Node.js 项目，开始装依赖..."
  if [ -f "pnpm-lock.yaml" ]; then
    npm install -g pnpm && pnpm install
  elif [ -f "yarn.lock" ]; then
    npm install -g yarn && yarn install
  else
    npm install
  fi
fi

# 2) Python (pip)
if [ -f "requirements.txt" ]; then
  echo "检测到 Python 项目，开始装依赖..."
  python3 -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt
fi

# 3) Go
if [ -f "go.mod" ]; then
  echo "检测到 Go 项目，开始装依赖..."
  go mod download
fi

# 4) Rust
if [ -f "Cargo.toml" ]; then
  echo "检测到 Rust 项目，开始装依赖..."
  cargo build
fi
```

### A5.4 启动开发服务

```bash
# 读 package.json 的 scripts 段
cat package.json | python3 -c "import json,sys; print(json.load(sys.stdin).get('scripts',{}).get('dev','无 dev 脚本'))"

# 启动（后台跑）
npm run dev &

# 等几秒，看日志
sleep 5
# 提取端口（一般是 3000 / 5173 / 8000）
```

**对话模板**：
```
✅ 依赖装完了。
🚀 正在启动开发服务（默认 http://localhost:3000）...

[几秒后]
服务起来了！我帮你打开浏览器：
   http://localhost:5173

打开看效果。如果停服务，告诉我「停掉」。
```

如果检测到 `OpenPreview` 工具就调用它自动打开。

### A5.5 README 优先原则

> **所有项目的「正确启动方式」几乎都写在 README 里**。如果上面的自动识别失败，永远 fallback 到读 README：

```bash
# 提取 README 里的「Quick Start」「Getting Started」「Usage」章节
head -200 README.md
```

**对话**：
```
我读了下这个项目的 README，它说要这样跑：

{提取出来的命令}

要我直接帮你执行吗？回复「执行」或「yes」。
```

---

## 主线 B · 失败处理（5 段式）

> **统一格式**：和主线 A 一致，每条按「原文 + 人话 + 为什么 + 3 步 + 兜底」写。

**失败 1：clone 超时**
```
【报错】fatal: unable to access '...' Connection timed out
【人话】「连不上 GitHub 仓库（被网络拦了）」
【为什么】当前网络到 GitHub 不通
【解决】
  1. 我已经探测好了，自动转到国内镜像 ghfast.top
     （把 https://github.com 替换成 https://ghfast.top/https://github.com）
  2. 如果镜像也不通，去 Step A2.6 走「高级诊断树」
  3. 还不行就换平台：到 AtomGit / Gitee 找找同名项目
【兜底】手动指定代理：git clone -c http.proxy=$HTTPS_PROXY {url}
```

**失败 2：依赖装失败（Node）**
```
【报错】npm ERR! peer dep missing / gyp ERR! stack Error
【人话】「装依赖时版本对不上（要嘛 Node 太旧，要嘛包之间打架）」
【为什么】项目要求的 Node 版本 ≥ 18，你电脑的可能太旧；或依赖之间版本冲突
【解决】
  1. 查 Node 版本：node --version（≥ 18 才算新）
     旧的话用 nvm 升：nvm install 18 && nvm use 18
     （这句是「装一个 Node 版本管理工具」）
  2. 删干净重装：
     rm -rf node_modules package-lock.json
     npm install
     （这两句是「把之前装的扔掉，重新装一遍」）
  3. 还不行就加 --legacy-peer-deps 绕开严格检查：
     npm install --legacy-peer-deps
【兜底】去 GitHub Issues 搜报错关键词（很可能别人遇到过）
```

**失败 3：依赖装失败（Python）**
```
【报错】pip install 失败 / ERROR: Could not find a version that satisfies...
【人话】「装 Python 包时找不到对应版本」
【为什么】可能是 Python 版本不对 / pip 太旧 / 包名拼错
【解决】
  1. 用虚拟环境（已自动创建 .venv，你直接激活就行）：
     source .venv/bin/activate
     （这句是「进入一个独立的 Python 环境」）
  2. 升 pip：pip install --upgrade pip
  3. 看项目要求的 Python 版本：cat .python-version 或 cat README.md | head -50
【兜底】用 conda 环境（更稳）：conda create -n myenv python=3.11 && conda activate myenv
```

**失败 4：启动报错**
```
【报错】Error: listen EADDRINUSE: address already in use :::3000
【人话】「3000 端口被别的程序占着，你这个项目起不来」
【为什么】上次的服务没关掉 / 有别的项目也用 3000
【解决】
  1. 找占用进程：lsof -i :3000（macOS/Linux）
     （这句是「列出谁在用 3000 端口」）
  2. 杀掉：kill -9 {PID}（把上面的进程号填进去）
  3. 或者改启动端口（找项目里的 .env 或 config 改 PORT=3001）
【兜底】重启电脑（最暴力但 100% 有效）
```

**失败 5：搜不到项目**
```
【报错】（没真正报错，就是搜不到结果）
【人话】「我搜了 {平台}，没找到叫 {关键词} 的项目」
【为什么】可能记错名字 / 项目在另一个平台 / 项目被删了
【解决】
  1. 让我再试一次（可能临时搜不到）：重新搜
  2. 换关键词：同义词、缩写、官方名
     比如「通义千问」→ 「qwen」、「QwenLM」
  3. 给我一篇文章链接，我从文章里提取项目名
【兜底】直接去 https://github.com/trending 看热门项目猜你想找哪个
```

---

## 主线 B · 完成对话

```
🎉 项目跑起来了！

📦 仓库：{地址}
📁 本地：{DEST 路径}
🌐 服务：http://localhost:{端口}
🔧 技术栈：{自动识别出的语言 + 框架}

接下来你可以：
1. 在浏览器打开 http://localhost:{端口} 看看效果
2. 改点代码试试（保存后会自动热更新）
3. 看 README 了解更多功能
4. 想停服务就说「停掉」

想再拉一个项目？直接说项目名或地址就行。
```

---

## 🎉 成功完成对话（主线 A · 发布）

```
🎉 恭喜！你的项目已经成功开源！

📦 仓库地址：{最终的链接}
📁 本地路径：{项目路径}
🌐 平台：{GitHub / AtomGit / Gitee}

接下来你可以：
1. 在仓库页面点 "Star" 收藏自己的项目 ⭐
2. 修改 README.md，加上更详细的项目介绍
3. 去 https://shields.io 生成徽章（build passing、license 等）放到 README 顶部
4. 想被更多人看到：
   - V2EX「分享创造」节点
   - 即刻、Twitter 带 #开源 标签
   - 知乎「开源项目」话题

下次再开新项目，可以直接跟我说「开源搭子」一键搞定！
```

---

## 📚 收尾步骤 · 生成项目文档（可选）

> **触发场景**：用户说「生成文档」「给这个项目生成文档」「生成 wiki」「生成项目知识库」「写 README」「整理项目文档」。
> **目的**：复用 [repowiki-generator](../repowiki-generator/SKILL.md) skill，把刚发布或刚拉下来的项目自动整理成一份结构化的仓库知识库（风格参考 popdf 的 repowiki）。

### 触发检测（每轮对话尾段扫一次）

任意一句满足即触发：

- 「生成文档 / 写文档 / 生成 wiki / 生成知识库」
- 「生成项目 README / 生成快速入门 / 生成 API 文档」
- 「整理项目文档 / 生成 wiki 文档」
- 「analyze and document this project / generate project documentation」
- 「给这个项目做份文档」

### 三种触发方式（按用户当前状态分流）

| 用户当前状态 | 走哪条路 | 说明 |
|---|---|---|
| 刚走完主线 A（已成功 push） | 路 A | 项目已在 `{项目路径}`，直接调 repowiki-generator |
| 刚走完主线 B（已成功 clone） | 路 B | 项目在 `~/opensource/{项目名}/`，直接调 repowiki-generator |
| 单独说「给 XX 项目生成文档」（带路径） | 路 C | 先确认路径存在 → 再调 repowiki-generator |

### 对话模板（开场白）

```
顺便提一句：你刚 {发布/拉下来} 的项目，要不要顺手生成一份完整的项目文档？

我会给你出一份结构化的项目知识库（风格参考 popdf repowiki）：
- 项目概述 / 快速入门 / 安装指南
- 核心功能详解 + mermaid 架构图
- API 参考 / 开发者指南
- 自动收集代码引用 + 章节来源

产物会落到：{项目路径}/wiki/zh/

1. ⭐ 生成
2. 跳过（之后我自己做）
3. 我想改改模板（告诉我改哪里）
```

### 接到「生成」后的执行步骤

> **重要**：这一步是**调用** repowiki-generator skill，不是把它的内容复制过来执行。

1. **明确项目根路径**：
   - 主线 A 后：`{用户在 Step 0 提供的项目路径}`
   - 主线 B 后：`~/opensource/{项目名}`
   - 路 C：用户提供的路径，先 `ls -la` 验证存在

2. **先问生成哪种语言**（默认中文，必须询问一次）：
   ```
   文档要生成哪种语言？
   1. ⭐ 只生成中文（默认）        → wiki/zh/
   2. 中文 + 英文都生成（同步双语）  → wiki/zh/ + wiki/en/
   3. 只生成英文                  → wiki/en/
   ```
   用户不回答就默认只生成中文。

3. **调起 repowiki-generator**：
   ```
   加载 skill：repowiki-generator
   输入参数：
     project_root = {确认的路径}
     lang = zh（默认）/ en / zh+en（按上一步用户选择）
     out_dir = {确认的路径}/wiki/<lang>
     modules / api_groups = 自动推断
   ```

4. **执行 6 阶段流程**（详见 [repowiki-generator/SKILL.md](../repowiki-generator/SKILL.md)）：
   - 阶段 0：读 [references/format-spec.md](../repowiki-generator/references/format-spec.md) 与 [doc-templates.md](../repowiki-generator/references/doc-templates.md)，并确认语言
   - 阶段 1：跑 [analyze_project.py](../repowiki-generator/scripts/analyze_project.py) 扫描项目
   - 阶段 2：按 [output-structure.md](../repowiki-generator/references/output-structure.md) 裁剪文档树
   - 阶段 3：按 [doc-templates.md](../repowiki-generator/references/doc-templates.md) 逐篇撰写（双语则先中文再翻英）
   - 阶段 4：跑 [generate_metadata.py](../repowiki-generator/scripts/generate_metadata.py) 生成 metadata
   - 阶段 5：写入 `wiki/<lang>/` 并按 [format-spec.md](../repowiki-generator/references/format-spec.md) 末尾的校验清单自检

5. **完成后告知用户**：
   ```
   📚 文档已生成！

   📁 位置：{项目路径}/wiki/zh/（双语还会有 wiki/en/）
   📄 文档数：{N} 篇
   📊 代码引用：{M} 条（自动收集）
   🗂️  目录结构：
      ├── meta/repowiki-metadata.json
      └── content/
          ├── 项目概述.md
          ├── 快速入门.md
          ├── 安装指南.md
          ├── 命令行使用.md
          ├── 核心功能详解/
          ├── API参考/
          └── 开发者指南/

   💡 你可以：
   1. 在代码编辑器里打开 wiki/ 看效果
   2. 改改里面不满意的地方（都是纯 Markdown）
   3. 把 wiki/ 加进 git（它本身是文档，可以一并 push）
   ```

### 接到「跳过」的兜底

如果用户暂时不想要，但以后又想做，告诉用户：

```
好的。哪天想生成文档了，直接说「给 {项目路径} 生成文档」我就帮你跑。
（关键词：生成文档 / 生成 wiki / 生成知识库 / generate project documentation）
```

### 注意事项

- **不要强制**：项目文档生成是可选动作，绝不在用户没同意时自动跑（避免给小白增加认知负担）。
- **项目路径必须真实存在**：调起 repowiki-generator 前先 `ls -la {路径}`，路径不存在就反问。
- **不要清空已有 `wiki/`**：如果目标路径已有 wiki 内容，先问用户「保留 / 覆盖 / 合并」。
- **生成失败的兜底**：如果某个文档生成失败（如 mermaid 语法错误），不要全盘放弃，标记失败项让用户单独处理。

---

## 安全 & 边界

| 行为 | 是否执行 | 说明 |
|---|---|---|
| 把项目 push 到公网（Public） | ✅ 默认 | 开源默认公开 |
| 推送到 Private 仓库 | ✅ 支持 | 提醒用户 Private 仓库免费额度有限 |
| 在 README 里写用户真实姓名/邮箱 | ⚠️ 询问 | 默认用 `{作者}` 占位符，提示去改 |
| 帮用户生成 PAT | ❌ 不代生成 | 让用户自己去 settings/tokens 生成，不经手凭据 |
| 帮用户把 PAT 写进文件 | ❌ 不直接写 | 用 `git config credential.helper store`，提示用户第一次 push 自己输 |
| 强制 push（覆盖远程） | ⚠️ 二次确认 | `git push -f` 必须用户明确同意 |

---

## 异常处理

| 情况 | 处理方式 |
|---|---|
| 用户路径不存在 | 询问是否要新建 / 还是给错了 |
| 用户给的路径有空格 / 中文 | 提示用英文路径或转义，告诉用户「建议用英文路径，跨平台兼容」 |
| `git` 命令未安装 | 提示 `xcode-select --install`（macOS）或装 Git for Windows |
| 远程仓库地址格式错 | 教用户看仓库页面绿色的 "Code" 按钮 → SSH 标签 |
| Gitee 强制实名 | 引导用户实名，或推荐换 AtomGit |
| 用户中途放弃 | 礼貌退出，已 commit 的代码保留在本地，远程仓库用户可自己删 |
| 用户不想注册任何平台 | 不强推，告诉用户「本地 git 也能管理代码 + 网盘备份」 |

---

## 重要约定

1. **永远先问账号/仓库**，再问网络，再问路径
2. **每步执行前用人话讲清「这一步在做什么」**
3. **失败要兜底**，不能把用户晾在报错上
4. **不强推 GitHub**——用户有 Gitee 账号就先用 Gitee，开不开心最重要
5. **敏感信息（PAT、邮箱）不写到对话里明文保存**，让用户自己保管
6. **Gitee 提示实名**——国内用户首次推公开仓库时主动提示