docs(workflows): add project bootstrap submission materials

2026-06-04 14:44:22 +08:00 · 2026-06-04 14:44:22 +08:00 · a2fd36b4a6
parent b319c44b02
commit a2fd36b4a6
6 changed files with 351 additions and 3 deletions
--- a/examples/workflows/project-bootstrap-automation/README.md
+++ b/examples/workflows/project-bootstrap-automation/README.md
@ -11,10 +11,13 @@
 - `examples/sample_project.json`：示例项目配置
 - `examples/verification_comment_config.json`：真实回写验证配置
 - `examples/demo_outputs/`：固定示例输出
+- `docs/workflow-spec.md`：工作流说明文档
 - `docs/architecture.md`：架构与流程说明
+- `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 单元测试

@ -67,6 +70,16 @@
 当指定 `-PublishIssueNumber` 时，会额外追加 `issue +comment`，用于把初始化摘要回写到 GitLink Issue。
 当指定 `-CreateRepo` 时，会在检查仓库前追加 `repo +create`。

+## 文档索引
+
+- 工作流说明：`docs/workflow-spec.md`
+- 架构说明与架构图：`docs/architecture.md`
+- 复现指南：`docs/quickstart.md`
+- 运行手册：`docs/runbook.md`
+- 验证记录：`docs/verification.md`
+- 演示视频脚本：`docs/demo-video-script.md`
+- 提交核对清单：`docs/submission-checklist.md`
+
 ## 场景价值

 - 降低新开源项目启动成本，避免 README、License、CI、初始任务缺失。
--- a/examples/workflows/project-bootstrap-automation/docs/architecture.md
+++ b/examples/workflows/project-bootstrap-automation/docs/architecture.md
@ -1,6 +1,8 @@
 # 架构说明

-本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。
+本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。正式架构图见 `docs/assets/bootstrap-architecture.svg`。
+
+![GitLink 项目一键初始化工作流架构](assets/bootstrap-architecture.svg)

 ```mermaid
 flowchart LR
--- a/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg
+++ b/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg
@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="820" viewBox="0 0 1440 820" role="img" aria-labelledby="title desc">
+  <title id="title">GitLink project bootstrap automation architecture</title>
+  <desc id="desc">A five-stage architecture diagram for the GitLink project bootstrap automation workflow.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f8fbff"/>
+      <stop offset="1" stop-color="#eef5f8"/>
+    </linearGradient>
+    <linearGradient id="blue" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0f3d6e"/>
+      <stop offset="1" stop-color="#176b87"/>
+    </linearGradient>
+    <linearGradient id="green" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0e7c66"/>
+      <stop offset="1" stop-color="#29a37a"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="12" stdDeviation="14" flood-color="#17324d" flood-opacity="0.13"/>
+    </filter>
+    <marker id="arrow" markerWidth="13" markerHeight="13" refX="10" refY="6.5" orient="auto">
+      <path d="M0,0 L13,6.5 L0,13 Z" fill="#26384d"/>
+    </marker>
+    <style>
+      text { font-family: Arial, "Microsoft YaHei", sans-serif; fill: #142033; }
+      .title { font-size: 38px; font-weight: 700; }
+      .subtitle { font-size: 18px; fill: #4f6175; }
+      .stage-title { font-size: 22px; font-weight: 700; fill: #ffffff; }
+      .body { font-size: 18px; fill: #253449; }
+      .small { font-size: 15px; fill: #52667a; }
+      .mono { font-family: Consolas, "Courier New", monospace; font-size: 16px; fill: #1d3248; }
+      .caption { font-size: 16px; fill: #345064; }
+    </style>
+  </defs>
+
+  <rect width="1440" height="820" fill="url(#bg)"/>
+  <rect x="52" y="52" width="1336" height="716" rx="28" fill="#ffffff" stroke="#d8e4ed"/>
+
+  <text x="720" y="112" text-anchor="middle" class="title">GitLink Project Bootstrap Automation</text>
+  <text x="720" y="146" text-anchor="middle" class="subtitle">Configuration-driven project initialization, CLI orchestration, GitLink execution, and reproducible evidence</text>
+
+  <g transform="translate(82 210)">
+    <rect width="220" height="330" rx="18" fill="#ffffff" stroke="#cfdce7" filter="url(#shadow)"/>
+    <rect width="220" height="68" rx="18" fill="url(#blue)"/>
+    <text x="110" y="43" text-anchor="middle" class="stage-title">Input</text>
+    <text x="28" y="114" class="body">Project metadata</text>
+    <text x="28" y="154" class="body">Repository target</text>
+    <text x="28" y="194" class="body">Branches</text>
+    <text x="28" y="234" class="body">Initial issues</text>
+    <line x1="28" y1="268" x2="192" y2="268" stroke="#c7d6e1"/>
+    <text x="28" y="302" class="mono">sample_project.json</text>
+  </g>
+
+  <g transform="translate(350 210)">
+    <rect width="220" height="330" rx="18" fill="#ffffff" stroke="#cfdce7" filter="url(#shadow)"/>
+    <rect width="220" height="68" rx="18" fill="#274766"/>
+    <text x="110" y="43" text-anchor="middle" class="stage-title">Assets</text>
+    <text x="28" y="114" class="body">README</text>
+    <text x="28" y="154" class="body">LICENSE</text>
+    <text x="28" y="194" class="body">Go CI</text>
+    <text x="28" y="234" class="body">CONTRIBUTING</text>
+    <text x="28" y="274" class="body">ROADMAP</text>
+  </g>
+
+  <g transform="translate(618 210)">
+    <rect width="250" height="330" rx="18" fill="#ffffff" stroke="#cfdce7" filter="url(#shadow)"/>
+    <rect width="250" height="68" rx="18" fill="url(#green)"/>
+    <text x="125" y="43" text-anchor="middle" class="stage-title">CLI Orchestration</text>
+    <rect x="30" y="96" width="190" height="48" rx="10" fill="#eef6fb" stroke="#cbdce8"/>
+    <text x="125" y="126" text-anchor="middle" class="mono">repo +info</text>
+    <rect x="30" y="158" width="190" height="48" rx="10" fill="#eef6fb" stroke="#cbdce8"/>
+    <text x="125" y="188" text-anchor="middle" class="mono">branch +list</text>
+    <rect x="30" y="220" width="190" height="48" rx="10" fill="#eef6fb" stroke="#cbdce8"/>
+    <text x="125" y="250" text-anchor="middle" class="mono">branch +create</text>
+    <rect x="30" y="282" width="190" height="48" rx="10" fill="#eef6fb" stroke="#cbdce8"/>
+    <text x="125" y="312" text-anchor="middle" class="mono">issue +create</text>
+  </g>
+
+  <g transform="translate(916 210)">
+    <rect width="220" height="330" rx="18" fill="#ffffff" stroke="#cfdce7" filter="url(#shadow)"/>
+    <rect width="220" height="68" rx="18" fill="#40556e"/>
+    <text x="110" y="43" text-anchor="middle" class="stage-title">GitLink</text>
+    <text x="28" y="116" class="body">Repository state</text>
+    <text x="28" y="158" class="body">Collaboration branches</text>
+    <text x="28" y="200" class="body">Bootstrap issues</text>
+    <text x="28" y="242" class="body">Issue comment</text>
+    <line x1="28" y1="278" x2="192" y2="278" stroke="#c7d6e1"/>
+    <text x="28" y="310" class="small">Apply mode only writes remotely</text>
+  </g>
+
+  <g transform="translate(1184 210)">
+    <rect width="220" height="330" rx="18" fill="#ffffff" stroke="#cfdce7" filter="url(#shadow)"/>
+    <rect width="220" height="68" rx="18" fill="#6b7789"/>
+    <text x="110" y="43" text-anchor="middle" class="stage-title">Evidence</text>
+    <text x="28" y="114" class="body">Markdown report</text>
+    <text x="28" y="154" class="body">Issue summary</text>
+    <text x="28" y="194" class="body">manifest.json</text>
+    <text x="28" y="234" class="body">files.json</text>
+    <text x="28" y="274" class="body">command log</text>
+  </g>
+
+  <line x1="314" y1="375" x2="338" y2="375" stroke="#26384d" stroke-width="3" marker-end="url(#arrow)"/>
+  <line x1="582" y1="375" x2="606" y2="375" stroke="#26384d" stroke-width="3" marker-end="url(#arrow)"/>
+  <line x1="880" y1="375" x2="904" y2="375" stroke="#26384d" stroke-width="3" marker-end="url(#arrow)"/>
+  <line x1="1148" y1="375" x2="1172" y2="375" stroke="#26384d" stroke-width="3" marker-end="url(#arrow)"/>
+
+  <path d="M743 555 C743 620, 1260 620, 1260 555" fill="none" stroke="#2f7d6b" stroke-width="3" stroke-dasharray="8 8" marker-end="url(#arrow)"/>
+  <text x="1000" y="650" text-anchor="middle" class="caption">Dry-run records planned commands; apply mode executes and records results</text>
+
+  <g transform="translate(160 690)">
+    <rect width="1120" height="46" rx="23" fill="#f5f9fb" stroke="#d4e1ea"/>
+    <circle cx="42" cy="23" r="10" fill="#24a368"/>
+    <text x="62" y="29" class="small">Go implementation</text>
+    <circle cx="278" cy="23" r="10" fill="#24a368"/>
+    <text x="298" y="29" class="small">7 default CLI calls</text>
+    <circle cx="535" cy="23" r="10" fill="#24a368"/>
+    <text x="555" y="29" class="small">Reproducible dry-run</text>
+    <circle cx="820" cy="23" r="10" fill="#24a368"/>
+    <text x="840" y="29" class="small">Validated on real GitLink repository</text>
+  </g>
+</svg>
--- a/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md
+++ b/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md
@ -0,0 +1,135 @@
+# 演示视频脚本
+
+本文档用于录制参赛演示视频。建议视频时长控制在 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/`。
--- a/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md
+++ b/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md
@ -7,8 +7,9 @@
 | 工作流串联不少于 3 个 CLI 命令或 Skill 调用 | `scripts/bootstrap_project.go` 规划或执行 `repo +info`、`branch +list`、`branch +create`、`issue +create`、`issue +comment` |
 | 提供可复现执行脚本或 Agent 对话记录 | `scripts/run_demo.ps1` |
 | 在至少一个真实 GitLink 项目上运行并展示效果 | 已在 `puygob236/gitlink-bootstrap-demo` 完成仓库读取、分支读取、Issue 创建和 Issue 摘要回写验证 |
-| 提供工作流说明文档 | `README.md`、`docs/quickstart.md`、`docs/runbook.md` |
-| 提供架构图 | `docs/architecture.md` |
+| 提供工作流说明文档 | `README.md`、`docs/workflow-spec.md`、`docs/quickstart.md`、`docs/runbook.md` |
+| 提供架构图 | `docs/architecture.md`、`docs/assets/bootstrap-architecture.svg` |
+| 提供演示材料 | `docs/demo-video-script.md` |
 | 代码开源并托管到 GitLink | 放置于 `examples/workflows/project-bootstrap-automation/` |
 | 提供完整中文 README | `README.md` |

@ -22,5 +23,6 @@
 ## 交付内容

 - `README.md`、`docs/`、`scripts/`、`examples/` 均位于本目录。
+- `docs/demo-video-script.md` 可用于录制演示视频。
 - `outputs/` 为运行时生成目录，评审可通过复现脚本重新生成。
 - `examples/demo_outputs/` 用于保存固定示例产物。
--- a/examples/workflows/project-bootstrap-automation/docs/workflow-spec.md
+++ b/examples/workflows/project-bootstrap-automation/docs/workflow-spec.md
@ -0,0 +1,76 @@
+# 工作流说明
+
+## 场景定位
+
+本工作流面向 GitLink 子赛题三“构建端到端自动化工作流”，选择“项目一键初始化”作为应用场景。目标是在新开源项目创建初期，将项目配置、初始化文件、协作分支、初始 Issue 和执行报告统一串联，形成可复现、可审计的启动流程。
+
+该场景覆盖开源项目常见的启动缺口：
+
+- README、License、CI 配置和协作文档不完整。
+- 初始任务缺少统一模板，Issue 粒度和验收标准不一致。
+- 分支、Issue、报告产物分散，难以复盘初始化过程。
+- 真实写入和演示复现之间缺少安全边界。
+
+## 端到端流程
+
+工作流由 `scripts/bootstrap_project.go` 实现，默认读取 `examples/sample_project.json`，并按以下顺序执行：
+
+1. 解析项目配置，读取项目名称、仓库 owner/name、许可证、初始化分支和初始 Issue。
+2. 生成初始化文件包，包括 README、LICENSE、CI 配置、贡献指南和路线图。
+3. 规划或执行 `repo +info`，检查目标 GitLink 仓库状态。
+4. 规划或执行 `branch +list`，读取分支状态。
+5. 规划或执行 `branch +create`，创建协作分支。
+6. 规划或执行 `issue +create`，创建初始化任务。
+7. 可选执行 `issue +comment`，将初始化摘要回写到指定 Issue。
+8. 生成 Markdown 报告、摘要、manifest、文件包和命令日志。
+
+## 串联的 GitLink CLI 能力
+
+默认 dry-run 配置会生成 7 个 `gitlink-cli` 调用计划：
+
+| 顺序 | CLI 能力 | 用途 |
+| ---: | --- | --- |
+| 1 | `repo +info` | 检查目标仓库信息 |
+| 2 | `branch +list` | 读取当前分支列表 |
+| 3 | `branch +create` | 创建 `develop` 协作分支 |
+| 4 | `branch +create` | 创建 `release/v0.1` 发布分支 |
+| 5 | `issue +create` | 创建 README 与快速开始任务 |
+| 6 | `issue +create` | 创建 CI 检查任务 |
+| 7 | `issue +create` | 创建 v0.1 里程碑任务 |
+
+当传入 `-PublishIssueNumber` 时，会追加 `issue +comment`，用于把初始化摘要发布到指定 GitLink Issue。
+
+## 运行模式
+
+| 模式 | 命令 | 行为 |
+| --- | --- | --- |
+| dry-run | `.\scripts\run_demo.ps1` | 生成材料和命令计划，不写入 GitLink |
+| apply | `.\scripts\run_demo.ps1 -Apply` | 执行真实 GitLink CLI 命令 |
+| apply + create repo | `.\scripts\run_demo.ps1 -Apply -CreateRepo` | 先创建仓库，再执行初始化流程 |
+| apply + comment | `.\scripts\run_demo.ps1 -Apply -PublishIssueNumber 1` | 执行真实命令并回写摘要 |
+
+## 输出产物
+
+运行后会生成以下文件：
+
+| 文件 | 说明 |
+| --- | --- |
+| `*_bootstrap_report.md` | 初始化报告，展示目标项目、生成文件、分支计划和 Issue 计划 |
+| `*_summary.md` | 可发布到 Issue 的初始化摘要 |
+| `*_manifest.json` | 结构化初始化清单 |
+| `*_files.json` | 生成文件内容包 |
+| `command_log_*.json` | gitlink-cli 命令计划或执行结果 |
+
+固定示例输出保存在 `examples/demo_outputs/`，用于评审快速查看产物格式。`outputs/` 是运行时目录，可通过脚本重新生成。
+
+## 工程边界
+
+- 主实现使用 Go，便于与 `gitlink-cli` 主仓库技术栈保持一致。
+- 默认 dry-run，避免演示阶段误写远端仓库。
+- 真实写入必须显式传入 `-Apply`。
+- 命令日志记录每个 CLI 调用的状态，便于复盘和排查。
+- 测试覆盖文件生成、CLI 编排、Issue 内容生成、幂等跳过判断和输出 manifest。
+
+## 赛题价值
+
+该工作流不是单个命令封装，而是面向真实开源项目启动流程的组合式方案。它把 `gitlink-cli` 的仓库、分支、Issue 和评论能力整合为一个可复现闭环，符合子赛题三对“串联多个 CLI 命令或 Skill 调用”“真实项目运行展示”“工作流说明文档和架构图”的要求。