forked from Gitlink/gitlink-cli
165 lines
5.2 KiB
Markdown
165 lines
5.2 KiB
Markdown
# 项目一键初始化工作流 — 端到端示例
|
||
|
||
**场景**：开发者希望快速启动一个新项目：输入一句话描述，自动创建仓库、生成 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 供审阅
|