# 项目一键初始化工作流 — 端到端示例

**场景**：开发者希望快速启动一个新项目：输入一句话描述，自动创建仓库、生成 README/LICENSE/CI 骨架、建立首个里程碑与初始 Issue，5 分钟即可进入协作。

## 前置条件

- `gitlink-cli` 已安装并登录（`gitlink-cli auth status`）
- 目标仓库所有者已确认（示例使用 `z2_cc`）
- `jq` 已安装（用于 JSON 解析）
- `node` 已安装（用于 `skeleton-gen.js` 与 `md-to-html.js`）

## 输入

```bash
export PROJECT_DESC="一个用 Go 编写的 GitLink 命令行工具，MIT 许可证，公开仓库。"
```

## 工作流步骤

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

```bash
# 1.1 AI 解析 PROJECT_DESC，落盘 _output/project-spec.json
#     name        → gitlink-cli（从描述推断，但本次演示仓库名复用参数 gitlink-cli-demo）
#     description → 一个用 Go 编写的 GitLink 命令行工具
#     language    → go
#     license     → MIT
#     private     → false
```

**`_output/project-spec.json` 输出示例：**
```json
{
  "name": "gitlink-cli-demo",
  "description": "一个用 Go 编写的 GitLink 命令行工具",
  "language": "go",
  "license": "MIT",
  "private": false,
  "owner": "z2_cc"
}
```

```bash
# 1.2 创建仓库（dry-run 模式）
DRY_RUN=true
gitlink-cli repo +create --name gitlink-cli-demo \
  --description "一个用 Go 编写的 GitLink 命令行工具" --private false
```

**输出示例：**
```json
{ "ok": true, "data": { "name": "gitlink-cli-demo", "id": 123456, "private": false } }
```

```bash
# 1.3 验证仓库已创建
gitlink-cli repo +info --owner z2_cc --repo gitlink-cli-demo --format json
```

**Expected:** `project-spec.json` 生成；dry-run 模式下 `[DRY-RUN] 将执行 repo +create ...`，不实际建仓。

---

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

```bash
# 2.1 运行骨架生成引擎
node scripts/skeleton-gen.js _output
```

**AI 生成逻辑说明：**
```
读取 _output/project-spec.json
  → language=go   → 生成 Go 风格 .gitignore（bin/、*.exe、vendor/）
  → license=MIT   → 写完整 MIT 正文，版权行 "Copyright (c) 2026 [project author]"
  → name + description → 拼装 README（标题/简介/安装/用法/贡献/许可证）
  → 固定模板       → .devops/构建流水线.yml（最小可用 Go 构建）
落盘到 _output/skeleton/{README.md, LICENSE, .gitignore, .devops/构建流水线.yml}
```

**`_output/skeleton/` 产物清单：**
```
README.md
LICENSE
.gitignore
.devops/构建流水线.yml
```

```bash
# 2.2 推送到新仓库（dry-run 模式）
DRY_RUN=true
# 优先 file +batch（单次 commit），不确定字段时退回逐个 file +create
gitlink-cli file +batch \
  --files '[{"path":"README.md","content":"# ...","action":"create"}, ...]' \
  --message "chore: 初始化项目骨架" --branch master
```

**Expected:** `skeleton/` 下四个文件齐全；dry-run 下 `[DRY-RUN] 将执行 file +batch ...`。

---

### Step 3：创建里程碑 / 标签 / 初始 Issue

```bash
# 3.1 创建里程碑 v0.1.0（due-date = 今天 +30 天）
gitlink-cli milestone +create -t "v0.1.0" \
  -d "首个里程碑：完成核心功能与文档" --due-date 2026-08-01
```

**输出示例：**
```json
{ "ok": true, "data": { "id": 1001, "name": "v0.1.0" } }
```

```bash
# 3.2 创建起始标签
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
```

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

**Expected:** 1 个里程碑、3 个标签、3 个初始 Issue 建议生成；dry-run 下全部 `[DRY-RUN]`。

---

## 完整命令速览

```bash
# Phase 1: 解析 + 建仓
PROJECT_DESC="一个用 Go 编写的 GitLink 命令行工具" \
  bash scripts/01-parse-and-create-repo.sh z2_cc gitlink-cli-demo

# Phase 2: 骨架
bash scripts/02-generate-skeleton.sh z2_cc gitlink-cli-demo

# Phase 3: Issue + 里程碑
bash scripts/03-create-issues-milestones.sh z2_cc gitlink-cli-demo

# 一键全流程
PROJECT_DESC="一个用 Go 编写的 GitLink 命令行工具" \
  bash scripts/project-bootstrap-full.sh z2_cc gitlink-cli-demo
```

## 最终报告

`_output/init-report.md` 含 **综合评分：X/10** 形式的"初始化完成度"，并列表展示已生成的产物（README/LICENSE/.gitignore/CI/里程碑/标签/Issue）。经 `md-to-html.js` 转换后生成可视化 HTML。

## 注意事项

- 所有写操作默认 dry-run，确认后通过 `DRY_RUN=false` 实际执行
- AI 解析出的项目名/许可证/可见性建议人工复核
- 生成 LICENSE 中的 `[year] [project author]` 占位需替换为真实版权人
- 离线/未认证时脚本优雅降级，仍能产出 init-report.md 供审阅
