diff --git a/examples/workflows/project-bootstrap-automation/README.md b/examples/workflows/project-bootstrap-automation/README.md index df6f5dd..2e309ed 100644 --- 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、初始任务缺失。 diff --git a/examples/workflows/project-bootstrap-automation/docs/architecture.md b/examples/workflows/project-bootstrap-automation/docs/architecture.md index 440f328..851735d 100644 --- 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 diff --git a/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg b/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg new file mode 100644 index 0000000..df0dbd9 --- /dev/null +++ b/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg @@ -0,0 +1,120 @@ + + GitLink project bootstrap automation architecture + A five-stage architecture diagram for the GitLink project bootstrap automation workflow. + + + + + + + + + + + + + + + + + + + + + + + + + + GitLink Project Bootstrap Automation + Configuration-driven project initialization, CLI orchestration, GitLink execution, and reproducible evidence + + + + + Input + Project metadata + Repository target + Branches + Initial issues + + sample_project.json + + + + + + Assets + README + LICENSE + Go CI + CONTRIBUTING + ROADMAP + + + + + + CLI Orchestration + + repo +info + + branch +list + + branch +create + + issue +create + + + + + + GitLink + Repository state + Collaboration branches + Bootstrap issues + Issue comment + + Apply mode only writes remotely + + + + + + Evidence + Markdown report + Issue summary + manifest.json + files.json + command log + + + + + + + + + Dry-run records planned commands; apply mode executes and records results + + + + + Go implementation + + 7 default CLI calls + + Reproducible dry-run + + Validated on real GitLink repository + + diff --git a/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md b/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md new file mode 100644 index 0000000..a6967ae --- /dev/null +++ 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/`。 diff --git a/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md b/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md index e68df41..b0d5233 100644 --- 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/` 用于保存固定示例产物。 diff --git a/examples/workflows/project-bootstrap-automation/docs/workflow-spec.md b/examples/workflows/project-bootstrap-automation/docs/workflow-spec.md new file mode 100644 index 0000000..d688a78 --- /dev/null +++ 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 调用”“真实项目运行展示”“工作流说明文档和架构图”的要求。