diff --git a/examples/workflows/project-bootstrap-automation/README.md b/examples/workflows/project-bootstrap-automation/README.md index be12237..70da85e 100644 --- a/examples/workflows/project-bootstrap-automation/README.md +++ b/examples/workflows/project-bootstrap-automation/README.md @@ -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` ## 场景价值 diff --git a/examples/workflows/project-bootstrap-automation/docs/architecture.md b/examples/workflows/project-bootstrap-automation/docs/architecture.md index ac4a575..164be7a 100644 --- a/examples/workflows/project-bootstrap-automation/docs/architecture.md +++ b/examples/workflows/project-bootstrap-automation/docs/architecture.md @@ -1,8 +1,8 @@ # 架构说明 -本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。正式架构图见 `docs/assets/bootstrap-architecture.png`。 +本工作流采用“配置输入 -> 资产生成 -> CLI 编排 -> GitLink 落地 -> 结果归档”的五段式架构。正式架构图见 `docs/assets/bootstrap-architecture.svg`。 -![GitLink 项目一键初始化工作流架构](assets/bootstrap-architecture.png) +![GitLink 项目一键初始化工作流架构](assets/bootstrap-architecture.svg) ```mermaid flowchart LR diff --git a/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.png b/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.png deleted file mode 100644 index 8791309..0000000 Binary files a/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.png and /dev/null differ 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..5686149 --- /dev/null +++ b/examples/workflows/project-bootstrap-automation/docs/assets/bootstrap-architecture.svg @@ -0,0 +1,153 @@ + + GitLink Project Bootstrap Automation + A vector architecture diagram for a configuration-driven GitLink project bootstrap 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 + Collaborationbranches + Bootstrap issues + Issue comment + Apply mode writesremotely + + + + + + + + + + + Evidence + + Markdown report + Issue summary + manifest.json + files.json + command log + + + + + + + + + + + + + + Go implementation + + + + + + 7 default CLI calls + + + + + + Reproducible dry-run + + + + + + Validated on real GitLink repo + + + diff --git a/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md b/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md deleted file mode 100644 index a6967ae..0000000 --- a/examples/workflows/project-bootstrap-automation/docs/demo-video-script.md +++ /dev/null @@ -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/`。 diff --git a/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md b/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md index 6941fbb..9019003 100644 --- a/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md +++ b/examples/workflows/project-bootstrap-automation/docs/submission-checklist.md @@ -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/` 用于保存固定示例产物。