---
name: gitlink-project-bootstrap
version: 1.0.0
description: "项目一键初始化：输入描述 → 创建仓库 → 生成 README/LICENSE/CI → 创建初始 Issue 和里程碑。"
metadata:
  requires:
    bins: ["gitlink-cli", "jq"]
  cliHelp: "gitlink-cli repo +create --help / gitlink-cli file +create --help / gitlink-cli milestone +create --help"
---

# gitlink-project-bootstrap（项目一键初始化）

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证、全局参数和 API 注意事项。
>
> **CRITICAL — 所有 GitLink 操作必须使用 `gitlink-cli`，禁止使用 `gh`（GitHub CLI）操作 GitLink 资源。**

## 说明

本 Skill 串联 **三个阶段** 完成一个新项目的"开箱即用"初始化：从一句自然语言项目描述出发，自动创建仓库、生成骨架文件、创建里程碑与初始 Issue，让项目在几分钟内即可进入协作状态。

1. **解析需求 + 创建仓库** — 从 `PROJECT_DESC` 用 AI 提取项目名/一句话简介/主语言/许可证偏好/可见性，调用 `gitlink-cli repo +create` 创建仓库
2. **生成项目骨架** — 生成 README.md / LICENSE / .gitignore / CI 配置，通过 `gitlink-cli file +batch`（或逐个 `file +create`）推送到新仓库
3. **创建初始 Issue 和里程碑** — 创建 v0.1.0 里程碑、起始标签（good-first-issue/enhancement/bug）和 2-3 个初始 Issue

---

## 三阶段工作流总览

```mermaid
flowchart LR
    A[项目描述 PROJECT_DESC] --> B[Phase 1: 解析 + 建仓]
    B --> C[Phase 2: 骨架文件]
    C --> D[Phase 3: Issue + 里程碑]

    subgraph B[Phase 1: 解析 + 建仓]
        B1[读取 PROJECT_DESC] --> B2[AI 提取结构化 spec]
        B2 --> B3[落盘 project-spec.json]
        B3 --> B4[repo +create]
    end

    subgraph C[Phase 2: 骨架]
        C1[读取 project-spec.json] --> C2[README/LICENSE/.gitignore/CI]
        C2 --> C3[file +batch 推送]
    end

    subgraph D[Phase 3: Issue + 里程碑]
        D1[milestone v0.1.0] --> D2[label 起始标签]
        D2 --> D3[issue +create ×N]
    end
```

---

## Phase 1：解析需求 + 创建仓库

### AI 解析逻辑

输入（环境变量 `PROJECT_DESC` 或脚本第一个额外参数）是一段自然语言描述，例如：

> 一个用 Go 编写的 GitLink 命令行工具，MIT 许可证，公开仓库。

AI（脚本运行时由 Agent 执行）按以下规则提取结构化字段，落盘到 `_output/project-spec.json`：

| 字段 | 提取规则 | 兜底默认 |
|------|----------|----------|
| `name` | 项目名（英文小写连字符） | `my-project` |
| `description` | 一句话简介 | 取描述前 40 字 |
| `language` | 主语言（go/node/python/...） | `go` |
| `license` | MIT / Apache-2.0 / GPL-3.0 | `MIT` |
| `private` | 公开/私有（true/false） | `false` |

### 命令

```bash
# 1. 创建仓库（dry-run 优先）
gitlink-cli repo +create --name <name> --description "<description>" --private true|false

# 2. 验证仓库已创建
gitlink-cli repo +info --owner <owner> --repo <name> --format json
```

---

## Phase 2：生成项目骨架文件

### 生成产物（由 `skeleton-gen.js` 驱动）

| 文件 | 内容 | 依据 |
|------|------|------|
| `README.md` | 标题/简介/安装/用法/贡献/许可证 | `project-spec.json` |
| `LICENSE` | 完整许可证正文（MIT/Apache-2.0/GPL-3.0 任选其一写全） | `license` 字段 |
| `.gitignore` | 按主语言给出合理模板（Go/Node/Python） | `language` 字段 |
| `.devops/构建流水线.yml` | 最小可用的 GitLink CI 流水线片段 | 固定模板 |

LICENSE 内嵌**完整正文**，版权行使用 `[year] [project author]` / `<owner>` 占位，便于人工替换。

### 推送命令

```bash
# 方式 A：逐个创建（最稳）
gitlink-cli file +create --path README.md --content "$(cat README.md)" --message "docs: 初始化 README"

# 方式 B：批量提交（推荐，单次 commit）
# files 是 JSON 数组：[{"path":"README.md","content":"...","action":"create"}, ...]
gitlink-cli file +batch --files '<JSON数组>' --message "chore: 初始化项目骨架" --branch master

# 可选：列出平台内置模板
gitlink-cli util +licenses
gitlink-cli util +ignores
```

> 不确定 `file +batch` 字段名时，先 `file +batch --help` 确认；不确定就退回逐个 `file +create`。

---

## Phase 3：创建初始 Issue 和里程碑

### 命令

```bash
# 1. 创建里程碑 v0.1.0（due-date 用今天 +30 天）
gitlink-cli milestone +create -t "v0.1.0" -d "首个里程碑：完成核心功能与文档" --due-date YYYY-MM-DD

# 2. 创建起始标签（color 为 hex 无 #）
gitlink-cli label +create --name "good-first-issue" --color 7057ff
gitlink-cli label +create --name "enhancement"     --color a2eeef
gitlink-cli label +create --name "bug"             --color d73a4a

# 3. 创建初始 Issue（关联里程碑和标签）
gitlink-cli issue +create -t "完善 README 文档"   -b "补充安装、用法、贡献指南" --milestone <id> --label <id>
gitlink-cli issue +create -t "配置 CI 流水线"      -b "确保 push/PR 触发构建与测试" --milestone <id> --label <id>
gitlink-cli issue +create -t "撰写贡献指南 CONTRIBUTING.md" -b "说明提交流程、代码规范" --milestone <id> --label <id>
```

所有写操作在 `DRY_RUN=true` 时只打印 `[DRY-RUN] 将执行 ...`，不真正调用；`DRY_RUN=false` 才真正执行。

---

## 可复现脚本

本 Skill 提供可直接执行的 Bash 脚本，位于 `scripts/` 目录：

| 脚本 | 功能 | 使用方式 |
|------|------|----------|
| `01-parse-and-create-repo.sh` | Phase 1 解析需求 + 建仓 | `bash 01-parse-and-create-repo.sh <owner> <repo>` |
| `02-generate-skeleton.sh` | Phase 2 生成骨架文件 | `bash 02-generate-skeleton.sh <owner> <repo>` |
| `03-create-issues-milestones.sh` | Phase 3 里程碑/标签/Issue | `bash 03-create-issues-milestones.sh <owner> <repo>` |
| `project-bootstrap-full.sh` | 全流程串联 | `bash project-bootstrap-full.sh <owner> <repo>` |
| `skeleton-gen.js` | Phase 2 文件生成引擎（被 02 调用） | `node skeleton-gen.js <_output_dir>` |

**所有脚本默认 dry-run 模式**（不会实际修改数据），确认无误后通过环境变量切换：

```bash
# Dry-run（默认，安全）
PROJECT_DESC="一个用 Go 编写的 GitLink 命令行工具" \
  DRY_RUN=true bash scripts/project-bootstrap-full.sh z2_cc gitlink-cli

# 实际执行
PROJECT_DESC="一个用 Go 编写的 GitLink 命令行工具" \
  DRY_RUN=false bash scripts/project-bootstrap-full.sh z2_cc gitlink-cli
```

---

## 注意事项

1. **dry-run 优先**：所有写操作（`repo +create`、`file +create`、`milestone +create`、`label +create`、`issue +create`）默认不应实际执行
2. **Token 有效**：运行前确认 `gitlink-cli auth status` 返回正常；离线/未认证时脚本用 `|| echo "[WARN] ..."` 优雅降级，不中途退出
3. **AI 解析需复核**：项目名/许可证/可见性的自动提取建议人工确认后再 `DRY_RUN=false`
4. **LICENSE 占位**：生成的 LICENSE 含 `[year] [project author]` 占位，需人工替换为真实版权人
5. **`file +batch` 字段名**：先用 `--help` 确认，不确定就退回逐个 `file +create`
6. **输出文件**：所有产物保存到 `scripts/_output/`（含 `project-spec.json`、`skeleton/` 子目录、`init-report.md` 及对应 HTML）供审计
