docs(workflows): address project bootstrap review feedback
This commit is contained in:
parent
b884a7478c
commit
60e8ab7768
|
|
@ -13,14 +13,22 @@
|
|||
- `examples/demo_outputs/`：固定示例输出
|
||||
- `docs/workflow-spec.md`：工作流说明文档
|
||||
- `docs/architecture.md`：架构与流程说明
|
||||
- `docs/assets/bootstrap-architecture.png`：架构图
|
||||
- `docs/assets/bootstrap-architecture.svg`：架构图
|
||||
- `docs/quickstart.md`：最短复现路径
|
||||
- `docs/runbook.md`：运行手册
|
||||
- `docs/verification.md`：验证记录
|
||||
- `docs/demo-video-script.md`：演示视频录制脚本
|
||||
- `docs/submission-checklist.md`：赛题要求映射
|
||||
- `scripts/bootstrap_project_test.go`：Go 单元测试
|
||||
|
||||
## 实现语言
|
||||
|
||||
本工作流主实现采用 Go，主要考虑如下：
|
||||
|
||||
- 与 `gitlink-cli` 主仓库技术栈一致，便于维护者阅读、测试和后续集成。
|
||||
- 可直接复用 Go 标准库完成 JSON 配置解析、文件生成、命令编排和单元测试，不引入额外运行时依赖。
|
||||
- Windows、Linux 和 macOS 均可通过 `go run` 复现，便于评审在不同环境中执行。
|
||||
- 对命令执行结果、退出码和结构化日志的处理更接近 `gitlink-cli` 自身工程风格。
|
||||
|
||||
## 运行方式
|
||||
|
||||
进入本目录后执行 dry-run：
|
||||
|
|
@ -37,6 +45,16 @@
|
|||
- `outputs/*_files.json`
|
||||
- `outputs/command_log_*.json`
|
||||
|
||||
输出文件名包含目标仓库和生成时间，格式如下：
|
||||
|
||||
- `{owner}_{repo}_{YYYYMMDD_HHMMSS}_bootstrap_report.md`
|
||||
- `{owner}_{repo}_{YYYYMMDD_HHMMSS}_summary.md`
|
||||
- `{owner}_{repo}_{YYYYMMDD_HHMMSS}_manifest.json`
|
||||
- `{owner}_{repo}_{YYYYMMDD_HHMMSS}_files.json`
|
||||
- `command_log_{YYYYMMDD_HHMMSS}.json`
|
||||
|
||||
例如 `puygob236_gitlink-bootstrap-demo_20260524_080000_bootstrap_report.md`。实际运行时会按当前时间生成新文件名，`examples/demo_outputs/` 中的固定时间戳文件仅作为示例产物。
|
||||
|
||||
如需执行真实 GitLink 写操作，在完成 GitLink 认证并核对目标仓库后使用：
|
||||
|
||||
```powershell
|
||||
|
|
@ -77,7 +95,6 @@
|
|||
- 复现指南：`docs/quickstart.md`
|
||||
- 运行手册：`docs/runbook.md`
|
||||
- 验证记录：`docs/verification.md`
|
||||
- 演示视频脚本：`docs/demo-video-script.md`
|
||||
- 提交核对清单：`docs/submission-checklist.md`
|
||||
|
||||
## 场景价值
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# 架构说明
|
||||
|
||||
本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。正式架构图见 `docs/assets/bootstrap-architecture.png`。
|
||||
本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。正式架构图见 `docs/assets/bootstrap-architecture.svg`。
|
||||
|
||||
|
||||
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 MiB |
|
|
@ -0,0 +1,153 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" width="1672" height="941" viewBox="0 0 1672 941" role="img" aria-labelledby="title desc">
|
||||
<title id="title">GitLink Project Bootstrap Automation</title>
|
||||
<desc id="desc">A vector architecture diagram for a configuration-driven GitLink project bootstrap workflow.</desc>
|
||||
<defs>
|
||||
<filter id="cardShadow" x="-16%" y="-16%" width="132%" height="132%">
|
||||
<feDropShadow dx="0" dy="12" stdDeviation="11" flood-color="#0a1b35" flood-opacity="0.11"/>
|
||||
</filter>
|
||||
<style>
|
||||
text { font-family: Arial, "Microsoft YaHei", sans-serif; fill: #0b1736; }
|
||||
.title { font-size: 72px; font-weight: 800; letter-spacing: 0; }
|
||||
.subtitle { font-size: 27px; fill: #46556b; }
|
||||
.card-title { font-size: 32px; font-weight: 800; }
|
||||
.cli-title { font-size: 28px; font-weight: 800; }
|
||||
.item { font-size: 23px; fill: #101a2f; }
|
||||
.small { font-size: 20px; fill: #314158; }
|
||||
.mono { font-family: Consolas, "Courier New", monospace; font-size: 19px; fill: #101a2f; }
|
||||
.hairline { stroke: #a8b5c4; stroke-width: 1.6; }
|
||||
.bullet-navy { fill: #071449; }
|
||||
.bullet-teal { fill: #075e70; }
|
||||
.bullet-blue { fill: #14579f; }
|
||||
.bullet-slate { fill: #334155; }
|
||||
.valid { fill: #32833f; }
|
||||
</style>
|
||||
</defs>
|
||||
|
||||
<rect width="1672" height="941" fill="#fbfcfe"/>
|
||||
<text x="836" y="93" text-anchor="middle" class="title">GitLink Project Bootstrap Automation</text>
|
||||
<text x="836" y="151" text-anchor="middle" class="subtitle">Configuration-driven project initialization, CLI orchestration, GitLink execution, and reproducible evidence</text>
|
||||
|
||||
<!-- Input -->
|
||||
<g transform="translate(48 208)">
|
||||
<rect width="255" height="505" rx="18" fill="#ffffff" stroke="#071449" stroke-width="2.2" filter="url(#cardShadow)"/>
|
||||
<g transform="translate(86 35)" fill="none" stroke="#071449" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M18 0h46l30 30v72H18z"/>
|
||||
<path d="M64 0v30h30"/>
|
||||
<path d="M42 45c-12 0-12 28 0 28"/>
|
||||
<path d="M70 45c12 0 12 28 0 28"/>
|
||||
<path d="M42 94h28"/>
|
||||
</g>
|
||||
<text x="128" y="194" text-anchor="middle" class="card-title">Input</text>
|
||||
<line x1="23" y1="221" x2="232" y2="221" class="hairline"/>
|
||||
<circle cx="24" cy="259" r="4.5" class="bullet-navy"/><text x="43" y="267" class="item">Project metadata</text>
|
||||
<circle cx="24" cy="305" r="4.5" class="bullet-navy"/><text x="43" y="313" class="item">Repository target</text>
|
||||
<circle cx="24" cy="351" r="4.5" class="bullet-navy"/><text x="43" y="359" class="item">Branches</text>
|
||||
<circle cx="24" cy="397" r="4.5" class="bullet-navy"/><text x="43" y="405" class="item">Initial issues</text>
|
||||
<circle cx="24" cy="443" r="4.5" class="bullet-navy"/><text x="43" y="451" class="mono">sample_project.json</text>
|
||||
</g>
|
||||
|
||||
<!-- Assets -->
|
||||
<g transform="translate(377 208)">
|
||||
<rect width="255" height="505" rx="18" fill="#ffffff" stroke="#075e70" stroke-width="2.2" filter="url(#cardShadow)"/>
|
||||
<g transform="translate(87 35)" fill="none" stroke="#075e70" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M0 26h72l24 24v84H0z"/>
|
||||
<path d="M72 26v24h24"/>
|
||||
<path d="M-18 45h18v70h-18z"/>
|
||||
<path d="M-36 63h18v70h-18z"/>
|
||||
<path d="M25 72h42M25 94h50M25 116h36"/>
|
||||
</g>
|
||||
<text x="128" y="194" text-anchor="middle" class="card-title" fill="#075e70">Assets</text>
|
||||
<line x1="23" y1="221" x2="232" y2="221" class="hairline"/>
|
||||
<circle cx="24" cy="259" r="4.5" class="bullet-teal"/><text x="43" y="267" class="item">README</text>
|
||||
<circle cx="24" cy="305" r="4.5" class="bullet-teal"/><text x="43" y="313" class="item">LICENSE</text>
|
||||
<circle cx="24" cy="351" r="4.5" class="bullet-teal"/><text x="43" y="359" class="item">Go CI</text>
|
||||
<circle cx="24" cy="397" r="4.5" class="bullet-teal"/><text x="43" y="405" class="item">CONTRIBUTING</text>
|
||||
<circle cx="24" cy="443" r="4.5" class="bullet-teal"/><text x="43" y="451" class="item">ROADMAP</text>
|
||||
</g>
|
||||
|
||||
<!-- CLI -->
|
||||
<g transform="translate(705 208)">
|
||||
<rect width="255" height="505" rx="18" fill="#ffffff" stroke="#14579f" stroke-width="2.2" filter="url(#cardShadow)"/>
|
||||
<g transform="translate(81 42)" fill="none" stroke="#14579f" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<rect x="0" y="0" width="94" height="94" rx="7"/>
|
||||
<path d="M0 28h94"/>
|
||||
<circle cx="18" cy="14" r="3"/><circle cx="35" cy="14" r="3"/><circle cx="52" cy="14" r="3"/>
|
||||
<path d="M31 55l18 18-18 18M61 91h26"/>
|
||||
</g>
|
||||
<text x="128" y="194" text-anchor="middle" class="cli-title" fill="#14579f">CLI Orchestration</text>
|
||||
<line x1="23" y1="221" x2="232" y2="221" class="hairline"/>
|
||||
<circle cx="24" cy="259" r="4.5" class="bullet-blue"/><text x="52" y="267" class="mono">repo +info</text>
|
||||
<circle cx="24" cy="305" r="4.5" class="bullet-blue"/><text x="52" y="313" class="mono">branch +list</text>
|
||||
<circle cx="24" cy="351" r="4.5" class="bullet-blue"/><text x="52" y="359" class="mono">branch +create</text>
|
||||
<circle cx="24" cy="397" r="4.5" class="bullet-blue"/><text x="52" y="405" class="mono">issue +create</text>
|
||||
</g>
|
||||
|
||||
<!-- GitLink -->
|
||||
<g transform="translate(1032 208)">
|
||||
<rect width="255" height="505" rx="18" fill="#ffffff" stroke="#334155" stroke-width="2.2" filter="url(#cardShadow)"/>
|
||||
<g transform="translate(73 44)" fill="none" stroke="#334155" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M42 91h-7C13 91 0 76 0 59c0-16 11-29 28-33C36 10 51 0 70 0c25 0 45 17 49 41 18 3 31 17 31 35 0 20-15 35-38 35H42"/>
|
||||
<circle cx="74" cy="34" r="8"/>
|
||||
<circle cx="48" cy="68" r="8"/>
|
||||
<circle cx="100" cy="68" r="8"/>
|
||||
<path d="M69 41L53 61M80 41l15 20"/>
|
||||
</g>
|
||||
<text x="128" y="194" text-anchor="middle" class="card-title" fill="#334155">GitLink</text>
|
||||
<line x1="23" y1="221" x2="232" y2="221" class="hairline"/>
|
||||
<circle cx="24" cy="259" r="4.5" class="bullet-slate"/><text x="43" y="267" class="item">Repository state</text>
|
||||
<circle cx="24" cy="305" r="4.5" class="bullet-slate"/><text x="43" y="302" class="item">Collaboration</text><text x="43" y="330" class="item">branches</text>
|
||||
<circle cx="24" cy="367" r="4.5" class="bullet-slate"/><text x="43" y="375" class="item">Bootstrap issues</text>
|
||||
<circle cx="24" cy="413" r="4.5" class="bullet-slate"/><text x="43" y="421" class="item">Issue comment</text>
|
||||
<circle cx="24" cy="459" r="4.5" class="bullet-slate"/><text x="43" y="453" class="item">Apply mode writes</text><text x="43" y="481" class="item">remotely</text>
|
||||
</g>
|
||||
|
||||
<!-- Evidence -->
|
||||
<g transform="translate(1364 208)">
|
||||
<rect width="255" height="505" rx="18" fill="#ffffff" stroke="#14579f" stroke-width="2.2" filter="url(#cardShadow)"/>
|
||||
<g transform="translate(88 35)" fill="none" stroke="#14579f" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M18 0h52l27 27v101H18z"/>
|
||||
<path d="M70 0v27h27"/>
|
||||
<path d="M39 55h43M39 79h43M39 103h31"/>
|
||||
</g>
|
||||
<text x="128" y="194" text-anchor="middle" class="card-title" fill="#14579f">Evidence</text>
|
||||
<line x1="23" y1="221" x2="232" y2="221" class="hairline"/>
|
||||
<circle cx="24" cy="259" r="4.5" class="bullet-blue"/><text x="43" y="267" class="item">Markdown report</text>
|
||||
<circle cx="24" cy="305" r="4.5" class="bullet-blue"/><text x="43" y="313" class="item">Issue summary</text>
|
||||
<circle cx="24" cy="351" r="4.5" class="bullet-blue"/><text x="43" y="359" class="mono">manifest.json</text>
|
||||
<circle cx="24" cy="397" r="4.5" class="bullet-blue"/><text x="43" y="405" class="mono">files.json</text>
|
||||
<circle cx="24" cy="443" r="4.5" class="bullet-blue"/><text x="43" y="451" class="item">command log</text>
|
||||
</g>
|
||||
|
||||
<polygon points="316,394 343,394 343,376 371,411 343,446 343,428 316,428" fill="#06133a"/>
|
||||
<polygon points="644,394 671,394 671,376 699,411 671,446 671,428 644,428" fill="#06133a"/>
|
||||
<polygon points="972,394 999,394 999,376 1027,411 999,446 999,428 972,428" fill="#06133a"/>
|
||||
<polygon points="1302,394 1329,394 1329,376 1357,411 1329,446 1329,428 1302,428" fill="#06133a"/>
|
||||
|
||||
<g transform="translate(55 777)">
|
||||
<rect width="1562" height="122" rx="14" fill="#f8fbf8" stroke="#a8b8aa" stroke-width="1.8"/>
|
||||
<g transform="translate(32 22)">
|
||||
<rect width="330" height="78" rx="12" fill="#ffffff" stroke="#4f9a57" stroke-width="2"/>
|
||||
<circle cx="49" cy="39" r="23" class="valid"/>
|
||||
<path d="M38 38l8 9 18-20" fill="none" stroke="#ffffff" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="96" y="48" class="small" fill="#0f4d22">Go implementation</text>
|
||||
</g>
|
||||
<g transform="translate(400 22)">
|
||||
<rect width="330" height="78" rx="12" fill="#ffffff" stroke="#4f9a57" stroke-width="2"/>
|
||||
<circle cx="49" cy="39" r="23" class="valid"/>
|
||||
<path d="M38 38l8 9 18-20" fill="none" stroke="#ffffff" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="96" y="48" class="small" fill="#0f4d22">7 default CLI calls</text>
|
||||
</g>
|
||||
<g transform="translate(768 22)">
|
||||
<rect width="330" height="78" rx="12" fill="#ffffff" stroke="#4f9a57" stroke-width="2"/>
|
||||
<circle cx="49" cy="39" r="23" class="valid"/>
|
||||
<path d="M38 38l8 9 18-20" fill="none" stroke="#ffffff" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="96" y="48" class="small" fill="#0f4d22">Reproducible dry-run</text>
|
||||
</g>
|
||||
<g transform="translate(1136 22)">
|
||||
<rect width="370" height="78" rx="12" fill="#ffffff" stroke="#4f9a57" stroke-width="2"/>
|
||||
<circle cx="49" cy="39" r="23" class="valid"/>
|
||||
<path d="M38 38l8 9 18-20" fill="none" stroke="#ffffff" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="96" y="48" class="small" fill="#0f4d22">Validated on real GitLink repo</text>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.8 KiB |
|
|
@ -1,135 +0,0 @@
|
|||
# 演示视频脚本
|
||||
|
||||
本文档用于录制参赛演示视频。建议视频时长控制在 3 到 5 分钟，录屏范围包括终端、项目目录和 GitLink 页面。
|
||||
|
||||
## 录制前准备
|
||||
|
||||
1. 打开终端，进入仓库根目录。
|
||||
2. 切换到 `project-bootstrap-automation-fork` 分支。
|
||||
3. 确认当前目录无未提交运行产物。
|
||||
4. 浏览器打开验证仓库页面：
|
||||
`https://gitlink.org.cn/puygob236/gitlink-bootstrap-demo`
|
||||
5. 如需展示真实回写，提前完成 `gitlink-cli auth login`。
|
||||
|
||||
## 镜头一：项目定位
|
||||
|
||||
展示目录：
|
||||
|
||||
```powershell
|
||||
cd examples\workflows\project-bootstrap-automation
|
||||
Get-ChildItem
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 本项目是 GitLink 子赛题三端到端自动化工作流。
|
||||
- 场景是项目一键初始化与协作启动。
|
||||
- 主实现为 Go，入口是 `scripts/bootstrap_project.go`。
|
||||
|
||||
## 镜头二：架构和交付物
|
||||
|
||||
展示文档：
|
||||
|
||||
```powershell
|
||||
Get-Content docs\workflow-spec.md -TotalCount 40
|
||||
Get-Content docs\architecture.md -TotalCount 35
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 工作流分为配置输入、资产生成、CLI 编排、GitLink 落地、结果归档。
|
||||
- 默认串联 `repo +info`、`branch +list`、`branch +create`、`issue +create`。
|
||||
- 可选追加 `issue +comment` 完成结果回写。
|
||||
|
||||
## 镜头三：单元测试
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
go test -count=1 ./scripts
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 测试覆盖文件生成、CLI 计划、Issue 正文、输出 manifest 和幂等跳过判断。
|
||||
- 测试通过后再进行 dry-run 演示。
|
||||
|
||||
## 镜头四：dry-run 复现
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
.\scripts\run_demo.ps1
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- dry-run 不写入 GitLink，只生成材料和命令计划。
|
||||
- 输出中应显示 7 个 `gitlink-cli` 调用计划。
|
||||
- 该模式适合评审复现和本地检查。
|
||||
|
||||
展示输出：
|
||||
|
||||
```powershell
|
||||
Get-ChildItem outputs
|
||||
Get-Content outputs\command_log_*.json -TotalCount 80
|
||||
```
|
||||
|
||||
## 镜头五：查看生成报告
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
Get-Content outputs\*_bootstrap_report.md -TotalCount 80
|
||||
Get-Content outputs\*_summary.md
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 初始化报告包含目标项目、生成文件、分支计划和 Issue 计划。
|
||||
- 摘要可用于回写到 GitLink Issue。
|
||||
|
||||
## 镜头六：真实仓库验证
|
||||
|
||||
展示 GitLink 页面：
|
||||
|
||||
```text
|
||||
https://gitlink.org.cn/puygob236/gitlink-bootstrap-demo
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 该仓库用于真实运行验证。
|
||||
- 已验证仓库读取、分支读取、Issue 创建和 Issue 摘要回写。
|
||||
- 真实写入命令记录在 `docs/verification.md`。
|
||||
|
||||
可展示命令：
|
||||
|
||||
```powershell
|
||||
Get-Content docs\verification.md
|
||||
```
|
||||
|
||||
## 镜头七：赛题要求映射
|
||||
|
||||
展示命令：
|
||||
|
||||
```powershell
|
||||
Get-Content docs\submission-checklist.md
|
||||
```
|
||||
|
||||
讲解要点：
|
||||
|
||||
- 工作流串联超过 3 个 CLI 调用。
|
||||
- 提供可复现脚本。
|
||||
- 已在真实 GitLink 项目上验证。
|
||||
- 提供说明文档和架构图。
|
||||
|
||||
## 录制后清理
|
||||
|
||||
演示结束后删除运行时输出目录：
|
||||
|
||||
```powershell
|
||||
Remove-Item outputs -Recurse -Force
|
||||
```
|
||||
|
||||
`outputs/` 是可复现运行产物，不作为固定源码提交；固定示例保存在 `examples/demo_outputs/`。
|
||||
|
|
@ -8,8 +8,8 @@
|
|||
| 提供可复现执行脚本或 Agent 对话记录 | `scripts/run_demo.ps1` |
|
||||
| 在至少一个真实 GitLink 项目上运行并展示效果 | 已在 `puygob236/gitlink-bootstrap-demo` 完成仓库读取、分支读取、Issue 创建和 Issue 摘要回写验证 |
|
||||
| 提供工作流说明文档 | `README.md`、`docs/workflow-spec.md`、`docs/quickstart.md`、`docs/runbook.md` |
|
||||
| 提供架构图 | `docs/architecture.md`、`docs/assets/bootstrap-architecture.png` |
|
||||
| 提供演示材料 | `docs/demo-video-script.md` |
|
||||
| 提供架构图 | `docs/architecture.md`、`docs/assets/bootstrap-architecture.svg` |
|
||||
| 提供演示材料 | 演示视频作为比赛平台附件提交；仓库内保留 `scripts/run_demo.ps1`、`docs/verification.md` 和 `examples/demo_outputs/` 作为可复现证据 |
|
||||
| 代码开源并托管到 GitLink | 放置于 `examples/workflows/project-bootstrap-automation/` |
|
||||
| 提供完整中文 README | `README.md` |
|
||||
|
||||
|
|
@ -23,6 +23,5 @@
|
|||
## 交付内容
|
||||
|
||||
- `README.md`、`docs/`、`scripts/`、`examples/` 均位于本目录。
|
||||
- `docs/demo-video-script.md` 可用于录制演示视频。
|
||||
- `outputs/` 为运行时生成目录，评审可通过复现脚本重新生成。
|
||||
- `examples/demo_outputs/` 用于保存固定示例产物。
|
||||
|
|
|
|||
Loading…
Reference in New Issue