Gh Bootstrap

1. Ask user for communication language and template language preference. Also ask for the desired mode: quick (sensible defaults, minimal interaction), custom (choose specific templates), or full (all available templates). See phases/02.1-quick-mode.md, phases/02.2-custom-mode.md, and phases/02.3-full-mode.md for mode-specific behavior. 2. Detect languages, frameworks, and existing GitHub files with python "$SKILL_DIR/scripts/gh_bootstrap_runtime.py" detect "$ARGUMENTS" before planning. If detection returns no languages (empty project or unrecognized stack), ask the user to specify the primary language manually instead of guessing. 3. Call AskUserQuestion to collect necessary configuration variables. 4. Scan for existing config files and plan conflict resolution (see references/RULES.md). Never overwrite existing files without explicit user approval. 5. Read specs/template-catalog.md to map required files to repository URLs, then use python "$SKILL_DIR/scripts/gh_bootstrap_runtime.py" fetch-template ... to download the chosen template sources. If a template download fails (network error, 404, timeout), report which template failed and offer to skip it or retry. 6. Render files with python "$SKILL_DIR/scripts/gh_bootstrap_runtime.py" render-template ... so placeholder replacement is deterministic. Keep phases/ and specs/ as reference material, not the execution engine. 7. Validate the generated tree with python "$SKILL_DIR/scripts/gh_bootstrap_runtime.py" validate-tree <target-root> and refuse completion if unreplaced {{placeholders}} remain. 8. If rtk is available, prefer it for project scanning, template inspection, and post-generation diff review. Keep template download and file rendering on the raw script path.

Mandatory Rules

• NEVER write config files from memory; MUST use downloaded templates.
• ALWAYS replace all variable placeholders (e.g., {{projectName}}).
• See references/RULES.md for detailed architecture and constraints.

Phase 1: 智能项目检测

自动扫描项目，识别语言、框架、包管理器和现有 GitHub 配置。

📋 参考文档

• [specs/detection-rules.md](../specs/detection-rules.md) - 检测规则详细定义

Objective

• 识别项目主要语言和框架
• 检测包管理器类型
• 扫描现有 GitHub 配置
• 生成检测结果 JSON

Prerequisites

• 用户在项目根目录执行 /gh:bootstrap

---

Execution Steps

Step 1: 扫描项目根目录

[ROLE]
项目分析器

[TASK]
扫描项目根目录，识别特征文件

[RULE REFERENCE]
详见 specs/detection-rules.md → 语言检测规则

[ACTIONS]
1. 使用 Glob 列出根目录文件
2. 检查特征文件是否存在：
   - package.json, tsconfig.json → Node.js/TypeScript
   - pyproject.toml, requirements.txt → Python
   - Cargo.toml → Rust
   - go.mod → Go
   - pom.xml, build.gradle → Java
3. 记录检测到的特征文件

[TOOL CALL]
Glob: pattern="*.*" (根目录)
Glob: pattern="*.json" (配置文件)

[OUTPUT]
{
  "featureFiles": ["package.json", "tsconfig.json", ...],
  "detectedLanguages": [{"language": "typescript", "confidence": "high"}]
}

Step 2: 检测包管理器

[ROLE]
依赖分析器

[TASK]
通过锁文件识别包管理器

[RULE REFERENCE]
详见 specs/detection-rules.md → 包管理器检测规则

[ACTIONS]
1. 检查锁文件存在性：
   - package-lock.json → npm
   - yarn.lock → yarn
   - pnpm-lock.yaml → pnpm
   - bun.lockb → bun
   - poetry.lock → poetry
   - Cargo.lock → cargo
2. 确定包管理器类型

[TOOL CALL]
Glob: pattern="*lock*"
Glob: pattern="*.lock"

[OUTPUT]
{
  "packageManager": "pnpm",
  "lockFile": "pnpm-lock.yaml"
}

Step 3: 检测框架

[ROLE]
框架识别器

[TASK]
解析依赖文件识别框架

[RULE REFERENCE]
详见 specs/detection-rules.md → 框架检测规则

[ACTIONS]
1. 读取 package.json 的 dependencies/devDependencies
2. 匹配框架特征：
   - next → Next.js
   - vue → Vue.js
   - react → React
   - express → Express.js
   - fastapi → FastAPI
   - django → Django
3. 检测版本号用于 CI 配置

[TOOL CALL]
Read: package.json (如存在)
Read: pyproject.toml (如存在)

[OUTPUT]
{
  "framework": "next.js",
  "frameworkVersion": "14.0.0",
  "runtimeVersion": "20"
}

Step 4: 扫描 GitHub 配置

[ROLE]
配置扫描器

[TASK]
检测 .github/ 目录现有配置

[ACTIONS]
1. 检查 .github/ 目录是否存在
2. 列出 .github/workflows/*.yml
3. 检查 .github/ISSUE_TEMPLATE/
4. 检查 PULL_REQUEST_TEMPLATE.md
5. 检查 dependabot.yml, CODEOWNERS
6. 检查根目录社区文件 (README, LICENSE, CONTRIBUTING)

[TOOL CALL]
Glob: pattern=".github/**/*"
Glob: pattern="README*"
Glob: pattern="LICENSE*"
Glob: pattern="CONTRIBUTING*"

[OUTPUT]
{
  "existingConfigs": {
    "workflows": ["ci.yml"],
    "issueTemplates": ["bug_report.md"],
    "prTemplate": true,
    "dependabot": false,
    "codeowners": false
  },
  "communityFiles": {
    "readme": true,
    "license": "MIT",
    "contributing": false
  }
}

Step 5: 生成检测结果

[ROLE]
结果汇总器

[TASK]
汇总检测结果为 JSON 结构

[ACTIONS]
1. 合并所有检测结果
2. 计算置信度
3. 确定需要用户输入的字段
4. 生成最终 JSON

[OUTPUT FORMAT]
{
  "detected": {
    "language": "typescript",
    "languages": ["typescript", "javascript"],
    "framework": "next.js",
    "frameworkVersion": "14.0.0",
    "runtimeVersion": "20",
    "packageManager": "pnpm",
    "monorepo": null,
    "existingConfigs": {
      "workflows": [],
      "issueTemplates": [],
      "prTemplate": false,
      "dependabot": false,
      "codeowners": false
    },
    "communityFiles": {
      "readme": false,
      "license": null,
      "contributing": false
    }
  },
  "confidence": {
    "language": "high",
    "framework": "high",
    "packageManager": "high"
  },
  "needsUserInput": ["projectName", "description", "author", "owner", "repo"]
}

---

Output

• Format: JSON 检测结果（内存保持，不写入文件）
• Usage: 传递给 Phase 2 作为配置收集的基础

Quality Checklist

• [ ] 已参考 specs/detection-rules.md
• [ ] 语言检测完成
• [ ] 包管理器识别
• [ ] 框架检测（如适用）
• [ ] 版本号检测
• [ ] GitHub 配置扫描
• [ ] 社区文件扫描
• [ ] 检测结果 JSON 生成

Next Phase

检测完成后，进入 Phase 2: 配置收集，向用户展示检测结果并收集配置偏好。

Phase 2: 配置收集

通过交互式问答收集用户配置偏好，提供教育性说明帮助用户理解每个组件的作用。

⚠️ CRITICAL: 完整信息收集

在进入 Phase 4 执行之前，必须收集所有必要的变量！

模板中的变量占位符不能留空，必须在本阶段全部确定：

• 项目基本信息（名称、描述、作者）
• GitHub 信息（用户名/组织名、仓库名）
• 组件特定变量（根据用户选择的组件动态收集）

Objective

• 展示 Phase 1 检测结果
• 引导用户选择配置模式
• 根据模式路由到对应子阶段
• 生成最终配置 JSON

Prerequisites

• Phase 1 检测结果 JSON

Sub-Phases

本阶段根据用户选择的模式，路由到不同的子阶段：

所有模式最终都进入 02.9-finalize-config.md 生成配置 JSON。

---

Execution Steps

Step 1: 展示检测结果

[ROLE] 检测结果展示专家

[TASK]
向用户展示检测结果，确认准确性

[INPUT]
- Phase 1 检测结果 JSON

[OUTPUT FORMAT]
## 🔍 项目检测结果

| 项目 | 检测值 |
|------|--------|
| 语言 | TypeScript |
| 框架 | React + Vite |
| 包管理器 | pnpm |
| Node 版本 | 20 |
| 现有配置 | README.md, .gitignore |

检测结果是否正确？如有问题请告诉我。

Step 2: 模式选择

[ROLE] 配置模式引导专家

[TASK]
使用 AskUserQuestion 引导用户选择配置模式

[TOOL CALL]
AskUserQuestion({
  "question": "请选择配置模式",
  "header": "配置模式",
  "options": [
    {
      "label": "🚀 快速模式 (推荐新手)",
      "description": "智能推荐最佳实践配置，只需确认即可"
    },
    {
      "label": "🎯 自定义模式",
      "description": "逐个选择每个组件，了解每个功能的作用"
    },
    {
      "label": "📦 全量模式",
      "description": "启用所有可用组件，适合企业级项目"
    }
  ],
  "multiSelect": false
})

[OUTPUT]
用户选择的模式: quick | custom | full

Step 3: 路由到子阶段

[ROLE] 流程路由专家

[TASK]
根据用户选择的模式，路由到对应的子阶段

[ROUTING RULES]
- 快速模式 → 执行 Phase 2.1
- 自定义模式 → 执行 Phase 2.2
- 全量模式 → 执行 Phase 2.3

[ACTIONS]
1. 读取对应的子阶段文件
2. 按照子阶段流程执行
3. 完成后进入 Phase 2.9 生成配置

---

Output

• Format: 配置 JSON（内存保持）
• Usage: 传递给 Phase 3 进行冲突检测

Quality Checklist

Completeness (完整性)

• [ ] 检测结果已展示
• [ ] 配置模式已选择
• [ ] 子阶段已完成
• [ ] 配置 JSON 已生成

Validation (验证)

• [ ] 所有必需变量已收集
• [ ] GitHub 信息已确认
• [ ] 组件特定变量已收集

Reference Documents

Next Phase

配置收集完成后，进入 Phase 3: 冲突检测，检查现有配置与目标配置的冲突。

Phase 2.1: 快速模式流程

快速模式的完整交互流程，智能推荐配置，最少交互。

Prerequisites

• Phase 2 主流程已选择"快速模式"
• Phase 1 检测结果 JSON

Execution Steps

Step 1: 展示推荐配置

[ROLE] 配置推荐专家

[TASK]
展示智能推荐的配置，让用户确认

[OUTPUT FORMAT]
## 🚀 快速模式 - 推荐配置

根据项目检测结果，我为你推荐以下配置：

### 📁 基础设施
- ✅ README.md - 项目说明文档
- ✅ LICENSE (MIT) - 开源许可证
- ✅ .gitignore - Git 忽略规则

### 🔄 CI/CD
- ✅ 基础 CI 工作流 - 自动运行测试和构建

### 📝 协作模板
- ✅ Issue 模板 - Bug 报告、功能请求
- ✅ PR 模板 - 规范 Pull Request 格式
- ✅ Labels - 标签系统

### 🔒 安全
- ✅ Dependabot - 自动检测依赖漏洞

[TOOL CALL]
AskUserQuestion({
  "question": "是否使用推荐配置？",
  "header": "确认配置",
  "options": [
    {
      "label": "使用推荐配置",
      "description": "直接使用上述配置开始生成"
    },
    {
      "label": "切换到自定义模式",
      "description": "我想自己选择组件"
    }
  ],
  "multiSelect": false
})

Step 2: 收集基本信息

[ROLE] 信息收集专家

[TASK]
收集项目基本信息（如果无法自动检测）

[AUTO-DETECT SOURCES]
- projectName: package.json > name
- authorName: git config user.name
- license: package.json > license 或默认 MIT
- description: package.json > description

[ACTIONS]
1. 尝试从项目文件自动检测
2. 检测失败时使用 AskUserQuestion 收集

[TOOL CALL - 仅当无法自动检测时]
AskUserQuestion({
  "question": "请提供项目基本信息\n\n项目名称: {detected_name}\n作者: {detected_author}\n许可证: MIT\n\n以上信息是否正确？",
  "header": "项目信息",
  "options": [
    {
      "label": "信息正确",
      "description": "使用检测到的信息"
    },
    {
      "label": "需要修改",
      "description": "我想修改部分信息"
    }
  ],
  "multiSelect": false
})

[OUTPUT]
{
  "project": {
    "name": "detected-name",
    "description": "detected-description",
    "author": {"name": "Author", "email": "email@example.com"},
    "license": "MIT"
  }
}

Step 3: 收集 GitHub 仓库信息 [MANDATORY]

[ROLE] GitHub 信息收集专家

[TASK]
收集 GitHub 用户名/组织名和仓库名（用于 badges、链接、工作流配置）

[AUTO-DETECT SOURCES]
- 从 git remote 解析: git remote get-url origin
- 格式: https://github.com/{owner}/{repo}.git 或 git@github.com:{owner}/{repo}.git

[ACTIONS]
1. 执行 git remote get-url origin
2. 解析 owner 和 repo
3. 如果检测失败或用户想修改，使用 AskUserQuestion 收集

[TOOL CALL - 检测成功时]
AskUserQuestion({
  "question": "检测到 GitHub 仓库信息：\n\n👤 用户名/组织: {detected_owner}\n📦 仓库名: {detected_repo}\n\n这些信息将用于：\n• README 中的 badges 链接\n• 工作流中的仓库引用\n• Issue/PR 模板中的链接",
  "header": "GitHub 信息",
  "options": [
    {
      "label": "信息正确",
      "description": "使用检测到的 GitHub 信息"
    },
    {
      "label": "需要修改",
      "description": "我想修改用户名或仓库名"
    }
  ],
  "multiSelect": false
})

[TOOL CALL - 检测失败或需要修改时]
输出提示：
"请提供 GitHub 仓库信息：

1. **GitHub 用户名/组织名**: (例如: octocat, microsoft, facebook)
2. **仓库名**: (例如: my-project)

这些信息将用于生成正确的 badges 链接和工作流配置。
如果还没有创建 GitHub 仓库，请先创建后再运行此工具。"

[OUTPUT]
{
  "github": {
    "owner": "username-or-org",
    "repo": "repo-name"
  }
}

Output

• Format: 部分配置 JSON（内存保持）
• Usage: 传递给 Phase 2.9 生成最终配置

Quick Mode Components

快速模式默认启用的组件（共 8 个）：

Next Phase

完成后进入 Phase 2.9: 生成配置

Phase 2.2: 自定义模式流程

自定义模式的完整交互流程，逐项选择组件，完全控制配置。

Prerequisites

• Phase 2 主流程已选择"自定义模式"
• Phase 1 检测结果 JSON

Execution Steps

Step 1: 基础设施选择

[ROLE] 组件选择引导专家

[TASK]
展示基础设施组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择基础设施组件\n\nℹ️ 这些是每个项目都应该有的基础文件：\n• README.md - 当别人访问你的仓库时首先看到的文件\n• LICENSE - 定义别人可以如何使用你的代码\n• .gitignore - 防止 node_modules 等文件被提交",
  "header": "📁 基础设施",
  "options": [
    {
      "label": "README.md (推荐)",
      "description": "项目说明文档，第一印象"
    },
    {
      "label": "LICENSE",
      "description": "开源许可证，定义使用权限"
    },
    {
      "label": ".gitignore",
      "description": "Git 忽略规则，避免提交不必要文件"
    },
    {
      "label": "CHANGELOG.md",
      "description": "版本变更记录"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的基础设施组件

Step 2: CI/CD 工作流选择

[ROLE] CI/CD 配置专家

[TASK]
展示 CI/CD 组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择 CI/CD 工作流组件\n\nℹ️ CI (持续集成) 是什么？\n每次推送代码时，GitHub 会自动运行测试，确保新代码没有破坏现有功能。这是现代软件开发的标准实践。",
  "header": "🔄 CI/CD",
  "options": [
    {
      "label": "基础 CI (推荐)",
      "description": "自动运行测试和构建，每次推送都会检查"
    },
    {
      "label": "发布工作流",
      "description": "创建 Release 时自动发布到 npm/PyPI"
    },
    {
      "label": "多平台测试",
      "description": "同时在 Windows/macOS/Linux 上测试"
    },
    {
      "label": "GitHub Pages",
      "description": "自动部署静态站点到 GitHub Pages"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的 CI/CD 组件

Step 3: 协作模板选择

[ROLE] 协作配置专家

[TASK]
展示协作模板组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择协作模板组件\n\nℹ️ 为什么需要模板？\n当用户报告 Bug 时，模板会引导他们提供环境信息、复现步骤等，减少来回沟通。PR 模板则提醒贡献者描述改动内容、关联 Issue。",
  "header": "📝 协作模板",
  "options": [
    {
      "label": "Issue 模板 (推荐)",
      "description": "帮助用户提交结构化的 Bug 报告和功能请求"
    },
    {
      "label": "PR 模板 (推荐)",
      "description": "规范 Pull Request 提交格式"
    },
    {
      "label": "Labels",
      "description": "标签系统，用颜色分类管理 Issue 和 PR"
    },
    {
      "label": "CODEOWNERS",
      "description": "定义代码所有者，自动分配 PR 审核人"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的协作模板组件

Step 4: 安全组件选择

[ROLE] 安全配置专家

[TASK]
展示安全组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择安全组件\n\nℹ️ 为什么安全很重要？\n依赖库可能存在安全漏洞，Dependabot 会自动检测并创建 PR 更新到安全版本。CodeQL 则能检测你代码中的安全问题。",
  "header": "🔒 安全",
  "options": [
    {
      "label": "Dependabot (推荐)",
      "description": "自动检测依赖漏洞并更新"
    },
    {
      "label": "CodeQL",
      "description": "GitHub 官方代码安全扫描"
    },
    {
      "label": "Dependency Review",
      "description": "PR 中检查新依赖的安全性"
    },
    {
      "label": "SECURITY.md",
      "description": "安全政策，告诉用户如何报告漏洞"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的安全组件

Step 5: 社区组件选择

[ROLE] 社区配置专家

[TASK]
展示社区组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择社区组件\n\nℹ️ 建设开源社区\n如果你希望其他人参与贡献，CONTRIBUTING.md 能降低贡献门槛。CODE_OF_CONDUCT.md 则定义社区行为准则，营造友好氛围。",
  "header": "👥 社区",
  "options": [
    {
      "label": "CONTRIBUTING.md",
      "description": "贡献指南，告诉贡献者如何参与"
    },
    {
      "label": "CODE_OF_CONDUCT.md",
      "description": "行为准则，定义社区行为规范"
    },
    {
      "label": "SUPPORT.md",
      "description": "支持文档，告诉用户如何获取帮助"
    },
    {
      "label": "FUNDING.yml",
      "description": "赞助链接，在仓库显示赞助按钮"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的社区组件

Step 6: 自动化组件选择

[ROLE] 自动化配置专家

[TASK]
展示自动化组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择自动化组件\n\nℹ️ 减少重复工作\n这些工具能自动处理日常维护任务：自动生成发布说明、关闭过期 Issue、欢迎新贡献者等。",
  "header": "🤖 自动化",
  "options": [
    {
      "label": "release-drafter",
      "description": "根据 PR 标签自动生成发布说明"
    },
    {
      "label": "stale",
      "description": "自动关闭长期无响应的 Issue"
    },
    {
      "label": "greetings",
      "description": "欢迎首次贡献者"
    },
    {
      "label": "auto-merge",
      "description": "Dependabot PR 自动合并"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的自动化组件

Step 7: 代码质量组件选择

[ROLE] 代码质量配置专家

[TASK]
展示代码质量组件，带教育性说明

[TOOL CALL]
AskUserQuestion({
  "question": "选择代码质量组件\n\nℹ️ 保持代码质量\nSuper-Linter 能一次性检查多种语言的代码风格。Codecov 则追踪测试覆盖率，防止覆盖率下降。",
  "header": "🔧 代码质量",
  "options": [
    {
      "label": "Super-Linter",
      "description": "GitHub 官方多语言 Linter，支持 50+ 种语言"
    },
    {
      "label": "Codecov",
      "description": "测试覆盖率追踪，在 PR 中显示覆盖率变化"
    },
    {
      "label": "Semantic PR",
      "description": "检查 PR 标题是否符合规范"
    },
    {
      "label": "Commitlint",
      "description": "检查 commit 消息格式"
    }
  ],
  "multiSelect": true
})

[OUTPUT]
记录用户选择的代码质量组件

Step 8: 参考仓库选择

[ROLE] 模板来源选择专家

[TASK]
对于选中的组件，让用户选择参考仓库

[CONDITION]
仅当用户选择了 issue-templates 时执行

[TOOL CALL]
AskUserQuestion({
  "question": "选择 Issue 模板的参考仓库\n\nℹ️ Issue 模板是什么？\n当用户在你的仓库创建 Issue 时，会看到预设表单，帮助他们提供结构化的 Bug 报告或功能请求。\n\n不同仓库提供不同风格的模板：",
  "header": "📝 Issue 模板来源",
  "options": [
    {
      "label": "stevemao/github-issue-templates (推荐)",
      "description": "8 种风格可选：简洁、清单、对话式等，适合各类项目"
    },
    {
      "label": "dec0dOS/amazing-github-template",
      "description": "一站式模板，包含 Bug/Feature/Improvement，设计精美"
    },
    {
      "label": "使用内置默认模板",
      "description": "使用 gh-bootstrap 内置的通用模板"
    }
  ],
  "multiSelect": false
})

[OUTPUT]
记录用户选择的模板来源

Step 9: Issue 模板风格选择

[ROLE] 模板风格选择专家

[TASK]
如果用户选择了 stevemao/github-issue-templates，让用户选择风格

[CONDITION]
仅当用户选择了 stevemao/github-issue-templates 时执行

[TOOL CALL]
AskUserQuestion({
  "question": "选择 Issue 模板风格\n\nℹ️ 不同风格适合不同项目：\n• 简洁风格 - 适合小型项目\n• 清单风格 - 适合需要详细信息的项目\n• 对话风格 - 适合社区项目",
  "header": "📝 模板风格",
  "options": [
    {
      "label": "checklist (推荐)",
      "description": "清单风格，引导用户提供完整信息"
    },
    {
      "label": "simple",
      "description": "简洁风格，适合小型项目"
    },
    {
      "label": "conversational",
      "description": "对话风格，更友好的语气"
    },
    {
      "label": "bugs-only",
      "description": "仅 Bug 报告，适合应用程序"
    }
  ],
  "multiSelect": false
})

[OUTPUT]
记录用户选择的模板风格

Step 10: 收集基本信息

[ROLE] 信息收集专家

[TASK]
收集项目基本信息

[REFERENCE]
参考 Phase 2.1 Step 2 的流程

Step 11: 收集 GitHub 仓库信息

[ROLE] GitHub 信息收集专家

[TASK]
收集 GitHub 用户名/组织名和仓库名

[REFERENCE]
参考 Phase 2.1 Step 3 的流程

Step 12: 收集组件特定变量

[ROLE] 变量收集专家

[TASK]
根据用户选择的组件，收集该组件需要的特定变量

[COMPONENT → REQUIRED VARIABLES MAPPING]

| 组件 | 需要收集的变量 | 说明 |
|------|---------------|------|
| funding | funding_platforms, funding_usernames | 赞助平台和对应用户名 |
| codeowners | codeowners_rules | 代码所有者规则 |
| pages | pages_source | 部署来源配置 |
| docker-publish | docker_registry | Docker 仓库选择 |

[CONDITIONAL TOOL CALLS]

--- 如果选择了 funding ---
AskUserQuestion({
  "question": "配置赞助信息\n\nℹ️ FUNDING.yml 会在仓库页面显示 Sponsor 按钮\n\n请选择你使用的赞助平台：",
  "header": "💰 赞助配置",
  "options": [
    {
      "label": "GitHub Sponsors",
      "description": "GitHub 官方赞助平台，无手续费"
    },
    {
      "label": "Open Collective",
      "description": "适合团队/组织，财务透明"
    },
    {
      "label": "Patreon",
      "description": "按月订阅模式"
    },
    {
      "label": "Buy Me a Coffee",
      "description": "一次性小额赞助"
    }
  ],
  "multiSelect": true
})

--- 如果选择了 codeowners ---
输出提示：
"配置代码所有者规则

ℹ️ CODEOWNERS 文件定义谁负责审核哪些代码

请提供代码所有者规则，格式如下：
• `* @default-owner` - 默认所有者
• `src/frontend/ @frontend-team` - 前端目录

默认将使用 @{github_owner} 作为所有文件的所有者。"

--- 如果选择了 pages ---
AskUserQuestion({
  "question": "配置 GitHub Pages\n\nℹ️ 自动部署静态站点到 GitHub Pages",
  "header": "📄 Pages 配置",
  "options": [
    {
      "label": "使用 GitHub Actions 部署 (推荐)",
      "description": "通过工作流构建后部署"
    },
    {
      "label": "从 main 分支部署",
      "description": "直接从主分支的指定目录部署"
    },
    {
      "label": "从 gh-pages 分支部署",
      "description": "使用独立的 gh-pages 分支"
    }
  ],
  "multiSelect": false
})

[OUTPUT]
{
  "componentVariables": {
    "funding": {...},
    "codeowners": {...},
    "pages": {...}
  }
}

Output

• Format: 部分配置 JSON（内存保持）
• Usage: 传递给 Phase 2.9 生成最终配置

Next Phase

完成后进入 Phase 2.9: 生成配置

Phase 2.3: 全量模式流程

全量模式的完整交互流程，启用所有组件，适合企业级项目。

Prerequisites

• Phase 2 主流程已选择"全量模式"
• Phase 1 检测结果 JSON

Execution Steps

Step 1: 展示完整配置

[ROLE] 配置展示专家

[TASK]
展示将生成的完整文件列表

[OUTPUT FORMAT]
## 📦 全量模式 - 完整配置

将为你生成以下所有配置文件：

### 📁 基础设施
- README.md - 项目说明文档
- LICENSE - 开源许可证
- .gitignore - Git 忽略规则
- CHANGELOG.md - 版本变更记录

### 🔄 CI/CD 工作流
- .github/workflows/ci.yml - 基础 CI
- .github/workflows/release.yml - 发布工作流
- .github/workflows/codeql.yml - 安全扫描
- .github/workflows/lint.yml - 代码检查
- .github/workflows/stale.yml - 过期管理
- .github/workflows/greetings.yml - 欢迎消息
- .github/workflows/auto-merge.yml - 自动合并
- .github/workflows/lock.yml - 锁定讨论

### 📝 协作模板
- .github/ISSUE_TEMPLATE/bug_report.md
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/ISSUE_TEMPLATE/config.yml
- .github/PULL_REQUEST_TEMPLATE.md
- .github/labels.yml
- .github/labeler.yml
- .github/CODEOWNERS

### 🔒 安全
- .github/dependabot.yml
- .github/workflows/dependency-review.yml
- SECURITY.md

### 👥 社区
- CONTRIBUTING.md
- CODE_OF_CONDUCT.md
- SUPPORT.md
- .github/FUNDING.yml

### 🤖 自动化
- .github/release-drafter.yml

共计 25+ 个文件

[TOOL CALL]
AskUserQuestion({
  "question": "确认生成全量配置？",
  "header": "确认",
  "options": [
    {
      "label": "确认生成",
      "description": "开始生成所有配置文件"
    },
    {
      "label": "切换到自定义模式",
      "description": "我想自己选择组件"
    }
  ],
  "multiSelect": false
})

Step 2: 收集基本信息

[ROLE] 信息收集专家

[TASK]
收集项目基本信息（同快速模式）

[REFERENCE]
参考 Phase 2.1 Step 2 的流程

Step 3: 收集 GitHub 仓库信息

[ROLE] GitHub 信息收集专家

[TASK]
收集 GitHub 用户名/组织名和仓库名

[REFERENCE]
参考 Phase 2.1 Step 3 的流程

Step 4: 收集全量模式特定变量

[ROLE] 变量收集专家

[TASK]
收集全量模式需要的额外变量

[REQUIRED VARIABLES]
由于全量模式启用所有组件，需要收集：

1. **FUNDING 配置**
   - 赞助平台选择
   - 对应平台用户名

2. **CODEOWNERS 配置**
   - 默认代码所有者
   - 目录级别所有者（可选）

[TOOL CALL - FUNDING]
AskUserQuestion({
  "question": "配置赞助信息\n\nℹ️ FUNDING.yml 会在仓库页面显示 Sponsor 按钮",
  "header": "💰 赞助配置",
  "options": [
    {
      "label": "GitHub Sponsors",
      "description": "GitHub 官方赞助平台，无手续费"
    },
    {
      "label": "Open Collective",
      "description": "适合团队/组织，财务透明"
    },
    {
      "label": "跳过赞助配置",
      "description": "暂时不配置赞助链接"
    }
  ],
  "multiSelect": true
})

[TOOL CALL - CODEOWNERS]
输出提示：
"配置代码所有者

ℹ️ CODEOWNERS 文件定义谁负责审核哪些代码

默认配置将使用 @{github_owner} 作为所有文件的所有者。
如需自定义，请提供规则，格式如下：
• `* @default-owner` - 默认所有者
• `src/frontend/ @frontend-team` - 前端目录
• `docs/ @docs-team` - 文档目录

是否使用默认配置？"

[OUTPUT]
{
  "componentVariables": {
    "funding": {
      "platforms": ["github"],
      "usernames": {"github": "username"}
    },
    "codeowners": {
      "rules": ["* @{owner}"]
    }
  }
}

Output

• Format: 部分配置 JSON（内存保持）
• Usage: 传递给 Phase 2.9 生成最终配置

Full Mode Components

全量模式启用的组件（共 40+ 个）：

Next Phase

完成后进入 Phase 2.9: 生成配置

Phase 2.9: 生成配置 JSON

汇总所有收集的配置，生成最终配置 JSON。

Prerequisites

• Phase 2.1/2.2/2.3 中的一个已完成
• 所有必需变量已收集

Execution Steps

Step 1: 验证必需变量

[ROLE] 配置验证专家

[TASK]
验证所有必需变量已收集完成

[REQUIRED VARIABLES CHECKLIST]
- [ ] project.name - 项目名称
- [ ] project.description - 项目描述
- [ ] project.author.name - 作者名称
- [ ] project.author.email - 作者邮箱
- [ ] project.license - 许可证类型
- [ ] github.owner - GitHub 用户名/组织名
- [ ] github.repo - 仓库名称

[ACTIONS]
1. 检查每个必需变量是否已填充
2. 如有缺失，返回对应的收集步骤
3. 验证格式（邮箱、URL 等）

[OUTPUT]
{
  "validation": {
    "passed": true,
    "missing": [],
    "invalid": []
  }
}

Step 2: 汇总配置

[ROLE] 配置汇总专家

[TASK]
将所有收集的配置汇总为最终 JSON

[OUTPUT FORMAT]
{
  "version": "2.0.0",
  "mode": "quick | custom | full",
  "project": {
    "name": "my-project",
    "description": "Project description",
    "author": {
      "name": "Author Name",
      "email": "email@example.com"
    },
    "license": "MIT"
  },
  "github": {
    "owner": "username-or-org",
    "repo": "repo-name"
  },
  "detected": {
    "language": "typescript",
    "languages": ["typescript", "javascript"],
    "framework": "react",
    "frameworks": ["react", "vite"],
    "packageManager": "pnpm",
    "nodeVersion": "20",
    "monorepo": null
  },
  "components": {
    "infrastructure": ["readme", "license", "gitignore"],
    "workflows": ["ci-basic"],
    "collaboration": ["issue-templates", "pr-template", "labels"],
    "security": ["dependabot"],
    "community": [],
    "automation": [],
    "quality": []
  },
  "templateSources": {
    "issue-templates": {
      "repo": "stevemao/github-issue-templates",
      "style": "checklist"
    },
    "readme": {
      "repo": "othneildrew/Best-README-Template"
    },
    "ci-workflow": {
      "repo": "actions/starter-workflows"
    }
  },
  "componentVariables": {
    "funding": {
      "platforms": ["github"],
      "usernames": {"github": "username"}
    },
    "codeowners": {
      "rules": ["* @owner"]
    },
    "pages": {
      "source": "actions"
    }
  },
  "variables": {
    "year": "2026",
    "nodeVersion": "20",
    "pythonVersion": "3.11",
    "mainBranch": "main"
  }
}

Step 3: 展示配置摘要

[ROLE] 配置展示专家

[TASK]
向用户展示配置摘要，确认无误

[OUTPUT FORMAT]
## 📋 配置摘要

### 项目信息
- **名称**: {project.name}
- **描述**: {project.description}
- **作者**: {project.author.name} <{project.author.email}>
- **许可证**: {project.license}

### GitHub 信息
- **仓库**: {github.owner}/{github.repo}

### 检测结果
- **语言**: {detected.language}
- **框架**: {detected.framework}
- **包管理器**: {detected.packageManager}

### 启用的组件
- **基础设施**: {components.infrastructure.join(', ')}
- **CI/CD**: {components.workflows.join(', ')}
- **协作**: {components.collaboration.join(', ')}
- **安全**: {components.security.join(', ')}
- **社区**: {components.community.join(', ') || '无'}
- **自动化**: {components.automation.join(', ') || '无'}

### 模板来源
{templateSources 列表}

---

配置是否正确？如有问题请告诉我。

[TOOL CALL - 可选]
AskUserQuestion({
  "question": "配置是否正确？",
  "header": "确认配置",
  "options": [
    {
      "label": "配置正确，继续执行",
      "description": "开始检测冲突并生成文件"
    },
    {
      "label": "需要修改",
      "description": "返回修改部分配置"
    }
  ],
  "multiSelect": false
})

Output

• Format: 完整配置 JSON（内存保持）
• Location: 传递给 Phase 3
• Usage: 作为后续阶段的输入

Output Schema

interface ConfigJSON {
  version: string;
  mode: 'quick' | 'custom' | 'full';
  project: {
    name: string;
    description: string;
    author: { name: string; email: string };
    license: string;
  };
  github: {
    owner: string;
    repo: string;
  };
  detected: {
    language: string;
    languages: string[];
    framework: string | null;
    frameworks: string[];
    packageManager: string;
    nodeVersion?: string;
    pythonVersion?: string;
    monorepo: string | null;
  };
  components: {
    infrastructure: string[];
    workflows: string[];
    collaboration: string[];
    security: string[];
    community: string[];
    automation: string[];
    quality: string[];
  };
  templateSources: Record<string, {
    repo: string;
    style?: string;
  }>;
  componentVariables: Record<string, any>;
  variables: Record<string, string>;
}

Quality Checklist

Completeness (完整性)

• [ ] 所有必需变量已填充
• [ ] 所有启用组件已记录
• [ ] 模板来源已指定

Consistency (一致性)

• [ ] 变量命名统一
• [ ] 组件 ID 与 specs/presets.md 一致

Validation (验证)

• [ ] JSON 格式有效
• [ ] 邮箱格式正确
• [ ] GitHub 信息格式正确

Next Phase

配置生成完成后，进入 Phase 3: 冲突检测

Phase 3: 冲突检测

检测现有配置与目标配置的冲突，制定处理策略。

📋 参考文档

• [specs/execution-rules.md](../specs/execution-rules.md) - 备份和文件操作规则

Objective

• 扫描目标文件是否已存在
• 识别配置冲突类型
• 制定冲突处理策略
• 获取用户确认

Prerequisites

• Phase 2 配置 JSON
• 已启用的组件列表

---

Execution Steps

Step 1: 扫描目标文件

[ROLE]
文件扫描器

[TASK]
检查所有目标文件是否已存在

[ACTIONS]
1. 根据启用的组件，列出所有目标文件路径
2. 使用 Glob 检查每个文件是否存在
3. 对于存在的文件，读取内容摘要

[TARGET FILES BY COMPONENT]
- readme: README.md
- license: LICENSE
- gitignore: .gitignore
- ci-workflow: .github/workflows/ci.yml
- issue-templates: .github/ISSUE_TEMPLATE/*.md
- pr-template: .github/PULL_REQUEST_TEMPLATE.md
- dependabot: .github/dependabot.yml
- labels: .github/labels.yml
- codeowners: .github/CODEOWNERS
- funding: .github/FUNDING.yml

[TOOL CALL]
Glob: pattern=".github/**/*"
Glob: pattern="README*"
Glob: pattern="LICENSE*"

[OUTPUT]
{
  "existing": ["README.md", ".github/workflows/ci.yml"],
  "new": [".github/ISSUE_TEMPLATE/bug_report.md", ...]
}

Step 2: 分析冲突类型

[ROLE]
冲突分析器

[TASK]
对每个已存在的文件分析冲突类型

[CONFLICT TYPES]
| 类型 | 说明 | 默认策略 |
|------|------|----------|
| IDENTICAL | 内容完全相同 | skip |
| SIMILAR | 结构相似，可合并 | backup |
| DIFFERENT | 内容不同 | backup |
| CUSTOM | 用户自定义内容 | skip |

[ACTIONS]
1. 读取现有文件内容
2. 与模板内容比较（如可能）
3. 判断冲突类型
4. 记录文件大小和修改时间

[TOOL CALL]
Read: README.md (如存在)
Read: .github/workflows/ci.yml (如存在)

[OUTPUT]
{
  "conflicts": [
    {
      "file": "README.md",
      "type": "DIFFERENT",
      "existingSize": 1024,
      "recommendation": "backup"
    },
    {
      "file": ".github/workflows/ci.yml",
      "type": "SIMILAR",
      "recommendation": "backup"
    }
  ]
}

Step 3: 制定处理策略

[ROLE]
策略制定器

[TASK]
为每个冲突制定处理策略

[STRATEGIES]
| 策略 | 说明 | 适用场景 |
|------|------|----------|
| skip | 跳过，保留现有文件 | IDENTICAL, CUSTOM |
| overwrite | 覆盖现有文件 | 用户明确要求 |
| backup | 备份后覆盖（.bak 后缀） | DIFFERENT, SIMILAR |
| rename | 重命名新文件 | 特殊情况 |

[ACTIONS]
1. 根据冲突类型应用默认策略
2. 考虑文件重要性调整策略
3. 生成策略列表

[OUTPUT]
{
  "strategies": [
    {"file": "README.md", "strategy": "backup", "reason": "内容不同"},
    {"file": ".github/workflows/ci.yml", "strategy": "skip", "reason": "已有 CI 配置"}
  ]
}

Step 4: 用户确认

[ROLE]
交互协调器

[TASK]
展示冲突列表，获取用户确认

[ACTIONS]
1. 格式化冲突报告
2. 展示每个冲突的推荐策略
3. 询问用户确认或修改

[DISPLAY FORMAT]
## 检测到文件冲突

| 文件 | 冲突类型 | 推荐策略 |
|------|----------|----------|
| README.md | 内容不同 | 备份后覆盖 |
| .github/workflows/ci.yml | 已存在 | 跳过 |

[TOOL CALL]
AskUserQuestion({
  "question": "如何处理文件冲突？",
  "header": "冲突处理",
  "options": [
    {"label": "使用推荐策略", "description": "按上述推荐方式处理"},
    {"label": "全部跳过", "description": "保留所有现有文件"},
    {"label": "全部覆盖", "description": "覆盖所有冲突文件（会备份）"},
    {"label": "逐个确认", "description": "为每个文件单独选择"}
  ],
  "multiSelect": false
})

[ON "逐个确认"]
对每个冲突文件单独询问：
AskUserQuestion({
  "question": "如何处理 {filename}？",
  "header": "文件处理",
  "options": [
    {"label": "跳过", "description": "保留现有文件"},
    {"label": "备份后覆盖", "description": "备份为 .bak 后覆盖"},
    {"label": "直接覆盖", "description": "不备份直接覆盖"}
  ],
  "multiSelect": false
})

Step 5: 生成执行计划

[ROLE]
计划生成器

[TASK]
生成最终执行计划

[ACTIONS]
1. 汇总所有文件操作
2. 按操作类型分组
3. 生成摘要统计

[OUTPUT FORMAT]
{
  "plan": {
    "create": [
      ".github/ISSUE_TEMPLATE/bug_report.md",
      ".github/ISSUE_TEMPLATE/feature_request.md",
      ".github/PULL_REQUEST_TEMPLATE.md",
      ".github/dependabot.yml"
    ],
    "overwrite": [],
    "backup": [
      {"file": "README.md", "backupTo": "README.md.bak"}
    ],
    "skip": [
      ".github/workflows/ci.yml"
    ]
  },
  "summary": {
    "totalFiles": 10,
    "create": 6,
    "overwrite": 0,
    "backup": 2,
    "skip": 2
  }
}

---

Output

• Format: 执行计划 JSON
• Usage: 传递给 Phase 4 执行

Quality Checklist

• [ ] 所有目标文件已扫描
• [ ] 冲突类型已识别
• [ ] 处理策略已制定
• [ ] 用户已确认
• [ ] 执行计划已生成

Next Phase

冲突处理策略确认后，进入 Phase 4: 执行，执行文件生成和部署。

Phase 4: 执行

根据执行计划下载模板并直接复制生成配置文件。

📋 强制参考文档

执行前必须读取：

• [specs/execution-rules.md](../specs/execution-rules.md) - 执行规则和约束
• [specs/template-catalog.md](../specs/template-catalog.md) - 模板路径映射

Objective

• 按需下载推荐模板仓库
• 读取模板文件并直接复制
• 仅替换变量占位符
• 部署到目标位置

Prerequisites

• Phase 2 配置 JSON
• Phase 3 执行计划

---

Execution Steps

Step 1: 准备工作目录

[TASK]
确保目标目录结构存在

[ACTIONS]
1. 创建 .github/ 目录（如不存在）
2. 创建 .github/workflows/ 目录
3. 创建 .github/ISSUE_TEMPLATE/ 目录
4. 创建临时缓存目录 .gh-bootstrap-cache/

[TOOL CALL]
Bash: mkdir -p .github/workflows .github/ISSUE_TEMPLATE .gh-bootstrap-cache

Step 2: 执行备份

[TASK]
对需要备份的文件执行备份操作

[ACTIONS]
1. 遍历 plan.backup 列表
2. 复制文件到 .bak 后缀
3. 记录备份结果

[TOOL CALL]
Bash: cp README.md README.md.bak

[OUTPUT]
{
  "backups": [
    {"original": "README.md", "backup": "README.md.bak", "status": "success"}
  ]
}

Step 3: 下载模板 [MANDATORY]

[TASK]
根据组件需求从 template-catalog.md 下载对应仓库

[PREREQUISITE]
必须先 Read: specs/template-catalog.md

[ACTIONS]
1. 读取 template-catalog.md 获取精确路径
2. 遍历需要的组件列表
3. git clone 到 .gh-bootstrap-cache/{component}/
4. 记录每个组件的必读文件路径

[TOOL CALL]
Bash: git clone --depth 1 https://github.com/{owner}/{repo} .gh-bootstrap-cache/{component}

[OUTPUT]
{
  "downloads": [
    {
      "component": "ci-workflow",
      "repo": "actions/starter-workflows",
      "files_to_read": ["ci/node.js.yml"],
      "status": "success"
    }
  ]
}

Step 4: 读取模板并直接复制 [MANDATORY]

[TASK]
读取下载的模板文件，直接复制内容（仅替换变量）

[RULE REFERENCE]
详见 specs/execution-rules.md:
- 直接复制规则
- 变量替换规则
- 禁止操作列表

[ACTIONS]
1. 使用 Read 工具读取模板文件
2. 原样复制读取到的内容
3. 仅替换变量占位符
4. 保持所有其他内容不变

[TOOL CALL]
Read: .gh-bootstrap-cache/ci-workflow/ci/node.js.yml
→ 获取完整 YAML 内容
→ 直接复制，仅调整 node-version
→ Write 到 .github/workflows/ci.yml

Step 5: 写入目标文件

[TASK]
将生成的配置写入目标位置

[ACTIONS]
1. 使用 Write 工具创建文件
2. 确保文件格式正确（YAML/Markdown）
3. 记录创建的文件

[TOOL CALL]
Write: .github/workflows/ci.yml

[OUTPUT]
{
  "created": [
    ".github/workflows/ci.yml",
    ".github/ISSUE_TEMPLATE/bug_report.md",
    ".github/ISSUE_TEMPLATE/feature_request.md",
    ".github/PULL_REQUEST_TEMPLATE.md",
    ".github/dependabot.yml"
  ]
}

Step 6: 验证生成结果

[TASK]
验证所有文件已正确生成

[ACTIONS]
1. 检查每个目标文件是否存在
2. 验证文件内容非空
3. 检查 YAML 文件语法
4. 检查变量替换是否完成

[VALIDATION CHECKS]
- 文件存在性检查
- 文件大小 > 0
- 无遗留 {{placeholder}}
- YAML 语法验证（workflows）

[OUTPUT]
{
  "validation": {
    "passed": ["ci.yml", "bug_report.md"],
    "failed": [],
    "warnings": []
  }
}

Step 7: 清理临时目录

[TASK]
清理下载的临时文件

[ACTIONS]
1. 删除 .gh-bootstrap-cache/ 目录
2. 确认清理完成

[TOOL CALL]
Bash: rm -rf .gh-bootstrap-cache

[NOTE]
可选步骤，用户可选择保留以供参考

Step 8: 记录执行结果

[TASK]
汇总执行结果

[OUTPUT FORMAT]
{
  "execution": {
    "status": "success",
    "files": {
      "created": [...],
      "backed_up": [...],
      "skipped": [],
      "failed": []
    },
    "templates_used": [
      {"component": "ci-workflow", "source": "actions/starter-workflows"}
    ],
    "errors": []
  }
}

---

Error Handling

详见 specs/execution-rules.md 的错误处理规则部分。

[ON DOWNLOAD ERROR]
1. 记录下载失败的仓库
2. 尝试使用内置默认模板
3. 通知用户哪些组件使用了默认配置

[ON GENERATION ERROR]
1. 记录错误详情
2. 跳过该组件
3. 继续处理其他组件

[ROLLBACK STRATEGY]
- 删除新创建的文件
- 从备份恢复原文件
- 清理临时文件

Output

• Format: 执行结果 JSON
• Usage: 传递给 Phase 5 生成报告

Quality Checklist

• [ ] 已读取 specs/template-catalog.md
• [ ] 目录结构已创建
• [ ] 备份已完成
• [ ] 模板已下载
• [ ] 配置已直接复制（非重写）
• [ ] 变量已替换
• [ ] 验证通过
• [ ] 临时文件已清理
• [ ] 结果已记录

Next Phase

执行完成后，进入 Phase 5: 报告，生成执行报告和后续建议。

Phase 5: 执行报告与审查

生成执行结果报告，让用户审查生成的文件，提供后续建议和操作指引。

⚠️ CRITICAL: 必须包含审查环节

在完成文件生成后，必须让用户审查关键文件！

用户需要确认：

• 工作流配置是否正确（版本号、命令、触发条件）
• 变量是否已正确替换（无遗留的 {{placeholder}}）
• GitHub 信息是否正确（badges URL、仓库链接）
• 组件特定配置是否符合预期

Objective

• 汇总执行结果
• 展示关键文件内容供用户审查
• 询问用户是否需要修改
• 生成可读报告
• 提供后续建议
• 输出操作指引

Prerequisites

• Phase 4 执行结果

Execution Steps

Step 1: 汇总执行结果

[TASK]
收集 Phase 4 的执行结果

[INPUT]
- 创建的文件列表
- 跳过的文件列表
- 备份的文件列表
- 错误信息（如有）

[OUTPUT]
{
  "summary": {
    "total": 10,
    "created": 6,
    "skipped": 2,
    "backed_up": 2,
    "failed": 0
  },
  "files": {
    "created": [...],
    "skipped": [...],
    "backed_up": [...]
  }
}

Step 2: 生成报告

[TASK]
格式化执行报告

[OUTPUT FORMAT]
## 执行报告

### 执行摘要

| 操作 | 数量 |
|------|------|
| 创建 | {created} |
| 跳过 | {skipped} |
| 备份 | {backed_up} |
| 失败 | {failed} |

### 创建的文件

✅ .github/workflows/ci.yml
✅ .github/ISSUE_TEMPLATE/bug_report.md
✅ .github/ISSUE_TEMPLATE/feature_request.md
✅ .github/PULL_REQUEST_TEMPLATE.md
✅ .github/dependabot.yml
✅ .github/labels.yml

### 跳过的文件

⏭️ README.md (已存在)
⏭️ LICENSE (已存在)

### 备份的文件

📦 .gitignore → .gitignore.bak

Step 3: 用户审查环节 [MANDATORY]

[TASK]
展示关键文件内容，让用户审查并确认

[CRITICAL FILES TO REVIEW]
按优先级展示以下文件（如果生成了的话）：

1. **CI 工作流** (.github/workflows/ci.yml)
   - 检查 Node/Python 版本是否正确
   - 检查测试命令是否与项目一致
   - 检查触发条件是否合适

2. **README.md**
   - 检查 badges URL 是否正确 (owner/repo)
   - 检查项目描述是否准确
   - 检查安装/使用说明是否正确

3. **FUNDING.yml** (如果生成)
   - 检查赞助平台用户名是否正确

4. **dependabot.yml**
   - 检查包管理器类型是否正确
   - 检查更新频率是否合适

[OUTPUT FORMAT]
## 📋 请审查生成的文件

以下是关键配置文件，请确认内容是否正确：

### 1. CI 工作流 (.github/workflows/ci.yml)

\`\`\`yaml
{ci.yml 内容}
\`\`\`

**请确认：**
- [ ] Node.js 版本 `{version}` 是否正确？
- [ ] 测试命令 `npm test` 是否与项目一致？
- [ ] 触发分支 `main` 是否正确？

### 2. README.md (关键部分)

\`\`\`markdown
{README badges 和项目信息部分}
\`\`\`

**请确认：**
- [ ] 仓库链接 `github.com/{owner}/{repo}` 是否正确？
- [ ] 项目描述是否准确？

---

[TOOL CALL]
AskUserQuestion({
  "question": "请审查上述生成的文件内容。\n\n如果发现问题，请告诉我需要修改的地方。",
  "header": "审查确认",
  "options": [
    {
      "label": "✅ 全部正确",
      "description": "文件内容无误，可以完成"
    },
    {
      "label": "⚠️ 需要修改",
      "description": "我发现了一些问题需要修正"
    },
    {
      "label": "🔍 查看更多文件",
      "description": "我想查看其他生成的文件"
    }
  ],
  "multiSelect": false
})

[ON "需要修改"]
1. 询问用户具体需要修改什么
2. 执行修改
3. 重新展示修改后的内容
4. 再次询问确认

[ON "查看更多文件"]
展示其他生成的文件内容，然后再次询问确认

Step 4: 后续建议

[TASK]
根据配置生成后续操作建议

[SUGGESTIONS BY COMPONENT]

**CI/CD 工作流**:
- 检查 `.github/workflows/ci.yml` 中的 Node.js 版本是否正确
- 确认测试命令 `npm test` 与项目实际配置一致
- 如需添加部署步骤，参考 GitHub Actions 文档

**Issue 模板**:
- 可根据项目需求自定义模板内容
- 添加更多模板类型：`docs`, `question`, `security`

**Dependabot**:
- 首次运行后会自动创建依赖更新 PR
- 可在 GitHub 仓库设置中调整更新频率

**Labels**:
- 运行 `gh label sync` 同步标签到仓库
- 或手动在 GitHub 仓库设置中导入

[OUTPUT FORMAT]
### 后续建议

1. **验证 CI 工作流**
   - 推送代码后检查 Actions 是否正常运行
   - 确认测试命令与项目配置一致

2. **自定义模板**
   - Issue 模板可根据项目需求调整
   - PR 模板可添加更多检查项

3. **同步标签**

gh label sync --force

4. **启用 Dependabot**
   - 在仓库 Settings → Security → Dependabot 中启用

Step 5: 输出最终报告

[TASK]
向用户展示完整报告

[ACTIONS]
1. 输出执行摘要
2. 列出所有文件操作
3. 展示后续建议
4. 提供相关文档链接

[DISPLAY FORMAT]
---
## ✅ gh-bootstrap 执行完成

{执行摘要}

{文件操作列表}

{后续建议}

### 相关文档

- [GitHub Actions 文档](https://docs.github.com/en/actions)
- [Issue 模板文档](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests)
- [Dependabot 文档](https://docs.github.com/en/code-security/dependabot)
---

Output

• Format: Markdown 报告（直接输出到用户）
• Usage: 用户参考执行结果和后续操作

Quality Checklist

• [ ] 执行结果已汇总
• [ ] 报告格式清晰
• [ ] 后续建议实用
• [ ] 文档链接有效

Completion

Phase 5 完成后，整个 /gh:bootstrap 流程结束。用户可根据报告进行后续操作。

gh-bootstrap System Rules & Architecture

Architecture Overview

1. Phase 1: Detection: Scan project for languages/frameworks. 2. Phase 2: Collection: interactive discovery via AskUserQuestion. 3. Phase 3: Conflict: Manage pre-existing files. 4. Phase 4: Execution: Download templates and perform variable substitution. 5. Phase 5: Report: Final summary.

Critical Constraints

• NO MEMORY GENERATION: Must git clone from URLs in specs/template-catalog.md.
• EXACT CLOPY: Do not rewrite logic; only replace {{variables}}.
• LANGUAGE: Ask user for preferred communication and template language at the start.

Output Structure

Targets .github/workflows/, Issue templates, PR templates, README, and LICENSE.

项目检测规则

本文档定义 gh-bootstrap 的智能项目检测规则，用于 Phase 1 检测阶段。

When to Use

• Phase 1 检测阶段：执行项目环境检测时必须参考
• 语言识别：确定项目主要编程语言
• 包管理器识别：确定依赖管理工具
• 框架检测：识别使用的框架以选择合适的 CI 模板
• 版本检测：获取运行时版本用于工作流配置

---

语言检测规则

通过检测项目根目录中的特征文件来识别编程语言。

多语言项目处理

当检测到多个语言特征文件时： 1. 优先选择置信度最高的语言 2. 如果置信度相同，按以下优先级排序：TypeScript > JavaScript > Python > Go > Rust > Java 3. 记录所有检测到的语言，供用户确认

包管理器检测规则

通过检测锁文件来识别包管理器。

无锁文件时的推断

如果没有锁文件，根据配置文件推断：

• package.json 存在 → 默认 npm
• pyproject.toml 存在且包含 [tool.poetry] → poetry
• pyproject.toml 存在且包含 [project] → pip/uv

框架检测规则

Node.js/TypeScript 框架

Python 框架

Go 框架

Rust 框架

Monorepo 检测规则

GitHub 配置检测规则

目录结构检测

.github/
├── workflows/           # GitHub Actions 工作流
│   └── *.yml
├── ISSUE_TEMPLATE/      # Issue 模板
│   ├── *.md
│   └── config.yml
├── PULL_REQUEST_TEMPLATE.md  # PR 模板
├── CODEOWNERS           # 代码所有者
├── dependabot.yml       # Dependabot 配置
├── renovate.json        # Renovate 配置
├── FUNDING.yml          # 赞助配置
└── SECURITY.md          # 安全策略

检测项目

架构文档检测规则

常见位置

按优先级排序： 1. ARCHITECTURE.md (项目根目录) 2. architecture.md (项目根目录) 3. docs/architecture.md 4. docs/ARCHITECTURE.md 5. docs/architecture/ (目录) 6. .github/ARCHITECTURE.md 7. doc/architecture.md

相关文档

检测结果数据结构

{
  "detected": {
    "language": "typescript",
    "languages": ["typescript", "javascript"],
    "framework": "next.js",
    "frameworks": ["next.js", "react"],
    "packageManager": "pnpm",
    "monorepo": "turborepo",
    "hasGitHub": true,
    "existingConfigs": {
      "workflows": ["ci.yml", "release.yml"],
      "issueTemplates": ["bug_report.md", "feature_request.md"],
      "prTemplate": true,
      "codeowners": false,
      "dependabot": true,
      "renovate": false
    },
    "hasArchDocs": true,
    "archDocPath": "docs/architecture.md"
  },
  "confidence": {
    "language": "high",
    "framework": "high",
    "packageManager": "high"
  },
  "needsUserInput": [
    "projectName",
    "authorName",
    "license"
  ]
}

检测流程

1. 扫描项目根目录

• 列出所有文件和目录
• 识别特征文件

2. 语言检测

• 匹配语言特征文件
• 确定主要语言和次要语言

3. 包管理器检测

• 检查锁文件
• 推断包管理器

4. 框架检测

• 解析依赖文件
• 匹配框架特征

5. Monorepo 检测

• 检查 monorepo 配置文件
• 识别工作区结构

6. GitHub 配置检测

• 扫描 .github/ 目录
• 记录现有配置

7. 架构文档检测

• 搜索架构文档
• 提取关键信息

8. 生成检测报告

• 汇总检测结果
• 标记需要用户确认的项目

Execution Rules Specification

执行阶段的强制规则和约束条件。

When to Use

• Phase 4 执行文件生成时必须遵守
• 任何涉及模板下载和文件写入的操作
• 变量替换和内容验证时参考

---

1. 模板下载规则 [MANDATORY]

强制步骤

在写入任何文件之前，必须完成：

1. 必须先读取 specs/template-catalog.md 获取精确文件路径 2. 必须执行 git clone 下载模板仓库到 .gh-bootstrap-cache/ 3. 必须使用 Read 工具读取下载的模板文件 4. 只有在读取模板后，才能基于模板内容生成配置

禁止行为

---

2. 直接复制规则 [MANDATORY]

正确流程

1. Read 模板文件 → 获取完整内容
2. 原样复制内容 → 不做任何"理解"或"优化"
3. 仅替换变量 → {{projectName}}, node-version 等
4. Write 到目标 → 内容 = 模板原文 + 变量替换

禁止操作

❌ "理解模板意图"
❌ "根据最佳实践重新编写"
❌ "优化/简化/重构模板"
❌ "添加额外的步骤"
❌ "删除看起来不需要的步骤"

为什么必须直接复制

1. GitHub 官方模板经过验证: actions/starter-workflows 被数百万仓库使用 2. 自行编写容易出错: 工作流语法复杂，细微错误会导致完全失效 3. 版本兼容性: 官方模板使用最新的 Action 版本和最佳实践 4. 减少调试时间: 直接复制的模板开箱即用

---

3. 变量替换规则

必须替换的变量

绝对不要替换

以下是 GitHub Actions 语法，必须保持原样：

${{ secrets.GITHUB_TOKEN }}  # 保持原样
${{ github.* }}              # 保持原样
${{ steps.* }}               # 保持原样
@v4                          # Action 版本保持原样

替换验证

替换完成后检查：

• [ ] 无遗留的 {{placeholder}} 占位符
• [ ] 所有 ${{ }} 表达式保持不变
• [ ] Action 版本号未被修改

---

4. 文件操作规则

目录创建

# 必须创建的目录
mkdir -p .github/workflows
mkdir -p .github/ISSUE_TEMPLATE
mkdir -p .gh-bootstrap-cache  # 临时缓存

备份策略

[BACKUP RULE]
对于 plan.backup 中的文件：
1. 复制到 .bak 后缀
2. 记录备份结果
3. 备份失败则中止该文件的覆盖操作

清理策略

[CLEANUP RULE]
执行完成后：
1. 删除 .gh-bootstrap-cache/ 目录
2. 保留 .bak 备份文件供用户参考
3. 可选：用户可选择保留缓存以供调试

---

5. 错误处理规则

下载错误

[ON DOWNLOAD ERROR]
1. 记录下载失败的仓库和错误信息
2. 尝试使用内置默认模板（如有）
3. 通知用户哪些组件使用了默认配置
4. 继续处理其他组件

生成错误

[ON GENERATION ERROR]
1. 记录错误详情（文件、行号、原因）
2. 跳过该组件
3. 继续处理其他组件
4. 在最终报告中标记失败项

回滚策略

[ROLLBACK STRATEGY]
当发生严重错误时：
1. 删除本次新创建的所有文件
2. 从 .bak 恢复原文件
3. 清理临时文件
4. 报告回滚结果

---

6. 验证规则

文件验证

验证输出格式

{
  "validation": {
    "passed": ["ci.yml", "bug_report.md"],
    "failed": [],
    "warnings": ["dependabot.yml: 建议检查更新频率"]
  }
}

---

Quick Reference

执行前检查清单

• [ ] 已读取 specs/template-catalog.md
• [ ] 已创建必要目录结构
• [ ] 已完成需要备份的文件备份
• [ ] 已下载所需模板仓库

执行中检查清单

• [ ] 每个文件都从模板读取
• [ ] 仅执行变量替换，无内容重写
• [ ] 保留所有 GitHub Actions 语法
• [ ] 记录每个操作的结果

执行后检查清单

• [ ] 所有目标文件已创建
• [ ] 验证通过或警告已记录
• [ ] 临时文件已清理
• [ ] 执行结果已汇总

用户手动操作规范

本文档定义 gh-bootstrap 执行完成后，需要用户手动完成的配置项。

>

⚠️ CRITICAL: Phase 5 报告阶段必须生成此验收清单，确保用户知道需要手动配置哪些内容。

When to Use

• Phase 5 报告阶段：生成后续操作指引时必须参考
• Secrets 配置：告知用户需要配置哪些 GitHub Secrets
• 仓库设置：指导用户启用 Pages、Dependabot 等功能
• 验证清单：提供配置完成后的验证方法

---

设计原则

1. 透明性: 明确告知用户哪些配置无法自动完成 2. 可操作性: 提供具体的操作步骤和链接 3. 优先级: 按重要性排序，关键配置优先 4. 验证性: 提供验证方法确认配置成功

---

组件 → 手动操作映射

快速索引

---

详细配置指南

1. NPM_TOKEN (ci-release - npm 发布)

适用组件: ci-release (发布到 npm)

为什么需要: GitHub Actions 需要 npm 访问令牌才能发布包到 npm registry。

配置步骤:

1. 获取 npm 令牌:

• 登录 npmjs.com
• 点击头像 → Access Tokens
• 点击 "Generate New Token" → "Classic Token"
• 选择 "Automation" 类型（用于 CI/CD）
• 复制生成的令牌

2. 添加到 GitHub Secrets:

• 打开仓库 → Settings → Secrets and variables → Actions
• 点击 "New repository secret"
• Name: NPM_TOKEN
• Secret: 粘贴 npm 令牌
• 点击 "Add secret"

验证方法:

# 创建一个 Release，检查 Actions 是否成功发布
gh release create v0.0.1-test --notes "Test release"

相关链接:

• npm 创建访问令牌
• GitHub 加密 Secrets

---

2. PYPI_TOKEN (ci-release - PyPI 发布)

适用组件: ci-release (发布到 PyPI)

为什么需要: GitHub Actions 需要 PyPI API 令牌才能发布包到 PyPI。

配置步骤:

1. 获取 PyPI 令牌:

• 登录 pypi.org
• 点击头像 → Account settings
• 滚动到 "API tokens" 部分
• 点击 "Add API token"
• Scope: 选择 "Entire account" 或特定项目
• 复制生成的令牌（以 pypi- 开头）

2. 添加到 GitHub Secrets:

• 打开仓库 → Settings → Secrets and variables → Actions
• 点击 "New repository secret"
• Name: PYPI_TOKEN
• Secret: 粘贴 PyPI 令牌
• 点击 "Add secret"

验证方法:

# 创建一个 Release，检查 Actions 是否成功发布
gh release create v0.0.1-test --notes "Test release"

相关链接:

• PyPI API 令牌

---

3. CODECOV_TOKEN (codecov)

适用组件: codecov

为什么需要: Codecov 需要令牌来接收和显示覆盖率报告。

配置步骤:

1. 获取 Codecov 令牌:

• 登录 codecov.io（使用 GitHub 登录）
• 选择你的仓库
• 进入 Settings → General
• 复制 "Repository Upload Token"

2. 添加到 GitHub Secrets:

• 打开仓库 → Settings → Secrets and variables → Actions
• 点击 "New repository secret"
• Name: CODECOV_TOKEN
• Secret: 粘贴 Codecov 令牌
• 点击 "Add secret"

验证方法:

• 推送代码触发 CI
• 检查 Codecov 是否收到覆盖率报告
• 在 PR 中查看覆盖率评论

相关链接:

• Codecov 快速入门

---

4. Docker 凭证 (docker-publish)

适用组件: docker-publish

为什么需要: 推送 Docker 镜像到 Docker Hub 需要认证。

注意: 如果使用 GitHub Container Registry (ghcr.io)，则不需要额外配置，GITHUB_TOKEN 已自动可用。

配置步骤 (Docker Hub):

1. 获取 Docker Hub 令牌:

• 登录 hub.docker.com
• 点击头像 → Account Settings → Security
• 点击 "New Access Token"
• 描述: GitHub Actions
• 权限: Read, Write, Delete
• 复制生成的令牌

2. 添加到 GitHub Secrets:

• DOCKER_USERNAME: Docker Hub 用户名
• DOCKER_PASSWORD: Docker Hub 访问令牌

验证方法:

# 推送代码或创建 Release，检查 Docker 镜像是否发布
docker pull your-username/your-repo:latest

相关链接:

• Docker Hub 访问令牌

---

5. GitHub Pages 启用 (pages)

适用组件: pages

为什么需要: GitHub Pages 需要在仓库设置中手动启用。

配置步骤:

1. 打开仓库 → Settings → Pages 2. Source: 选择 "GitHub Actions" 3. 保存设置

验证方法:

• 推送代码触发 Pages 工作流
• 访问 https://{username}.github.io/{repo}/

相关链接:

• GitHub Pages 文档

---

6. 分支保护规则 (branch-protection)

适用组件: branch-protection

为什么需要: 防止直接推送到主分支，要求 PR 审核和 CI 通过。

配置步骤:

1. 打开仓库 → Settings → Branches 2. 点击 "Add branch protection rule" 3. Branch name pattern: main 或 master 4. 推荐启用的选项:

• ✅ Require a pull request before merging
• ✅ Require status checks to pass before merging
• ✅ Require branches to be up to date before merging
• ✅ Include administrators

验证方法:

# 尝试直接推送到 main，应该被拒绝
git push origin main  # 应该失败

相关链接:

• 分支保护规则

---

7. 标签同步 (labels)

适用组件: labels

为什么需要: .github/labels.yml 文件需要同步到仓库的实际标签。

配置步骤:

# 使用 GitHub CLI 同步标签
gh label sync --force

# 或者使用 github-label-sync 工具
npx github-label-sync --access-token $GITHUB_TOKEN --labels .github/labels.yml owner/repo

验证方法:

• 打开仓库 → Issues → Labels
• 检查标签是否与 .github/labels.yml 一致

---

8. Dependabot 启用 (dependabot)

适用组件: dependabot

为什么需要: 虽然 dependabot.yml 已创建，但可能需要在仓库设置中启用。

配置步骤:

1. 打开仓库 → Settings → Code security and analysis 2. 启用 "Dependabot alerts" 3. 启用 "Dependabot security updates" 4. 启用 "Dependabot version updates"

验证方法:

• 打开仓库 → Insights → Dependency graph → Dependabot
• 检查是否有待处理的更新

---

9. Code Scanning 启用 (codeql)

适用组件: codeql

为什么需要: CodeQL 工作流已创建，但可能需要在仓库设置中启用。

配置步骤:

1. 打开仓库 → Settings → Code security and analysis 2. 启用 "Code scanning" 3. 选择 "Set up" → "Advanced"（如果工作流已存在则跳过）

验证方法:

• 打开仓库 → Security → Code scanning alerts
• 推送代码后检查是否有扫描结果

---

验收清单模板

Phase 5 报告阶段必须生成以下格式的验收清单：

## 📋 用户手动操作清单

以下配置需要您手动完成才能使工作流正常运行：

### 🔴 必须配置（否则工作流会失败）

| 配置项 | 操作 | 状态 |
|--------|------|------|
| NPM_TOKEN | [添加到 Secrets](../../settings/secrets/actions/new) | ⬜ 待完成 |
| CODECOV_TOKEN | [添加到 Secrets](../../settings/secrets/actions/new) | ⬜ 待完成 |

### 🟡 推荐配置（提升项目质量）

| 配置项 | 操作 | 状态 |
|--------|------|------|
| 分支保护 | [配置规则](../../settings/branches) | ⬜ 待完成 |
| 标签同步 | 运行 `gh label sync --force` | ⬜ 待完成 |

### 🟢 可选配置

| 配置项 | 操作 | 状态 |
|--------|------|------|
| GitHub Pages | [启用 Pages](../../settings/pages) | ⬜ 待完成 |

---

**完成上述配置后，您的 GitHub 仓库将完全就绪！**

---

组件 → 必需 Secrets 映射

---

更新记录

预设配置定义

本文档定义 gh-bootstrap 支持的预设配置方案和组件分类。

设计原则: gh-bootstrap 专注于 GitHub 生态系统（.github/ 文件夹），不涉及项目级工具（如 ESLint、Jest、Husky 等）。

When to Use

• Phase 2 配置收集阶段：展示组件选项和预设方案时参考
• 模式选择：确定用户使用快速/自定义/全量模式
• 组件分类：了解各组件的功能和适用场景
• 默认配置：获取各模式下的默认组件列表
• 用户教育：向用户解释各组件的作用

---

⚠️ CRITICAL: 模板使用规则

所有组件配置必须基于模板直接复制，禁止自行编写！

1. 直接复制: 从 template-catalog.md 指定的仓库下载模板，原样复制内容 2. 仅替换变量: 只修改 {{projectName}}、node-version 等明确的变量占位符 3. 禁止重写: 不允许"参考模板后重新编写"或"根据最佳实践优化" 4. 保留结构: 不得删除、重排或"简化"模板中的步骤

详细规则请参考: template-catalog.md 和 04-execution.md

配置模式

gh-bootstrap 提供 3 种配置模式：

---

组件分类

📁 基础设施 (Infrastructure)

每个项目都应该有的基础文件，帮助他人了解和使用你的项目。

教育说明:

• README.md: 当别人访问你的 GitHub 仓库时，首先看到的就是这个文件。好的 README 能让人快速了解项目是什么、怎么用。
• LICENSE: 没有许可证的代码默认是"保留所有权利"，别人不能合法使用。MIT 是最宽松的选择。
• .gitignore: 防止 node_modules、.env 等文件被提交到仓库，保持仓库整洁。
• CHANGELOG.md: 记录每个版本的变更内容，帮助用户了解更新了什么。

---

🔄 CI/CD 工作流 (Workflows)

自动化测试、构建、部署流程，确保代码质量。

教育说明:

• CI (持续集成): 每次推送代码时，GitHub 会自动运行测试，确保新代码没有破坏现有功能。
• 发布工作流: 当你创建 Release 时，自动将包发布到 npm 或 PyPI。
• 多平台测试: 同时在 Windows、macOS、Linux 上测试，确保跨平台兼容性。
• GitHub Pages: 自动将文档或静态站点部署到 username.github.io/repo。
• Docker 发布: 自动构建 Docker 镜像并推送到 GitHub Container Registry 或 Docker Hub。

---

📝 协作模板 (Collaboration)

规范化 Issue 和 PR 提交，提高协作效率。

教育说明:

• Issue 模板: 当用户报告 Bug 时，模板会引导他们提供环境信息、复现步骤等，减少来回沟通。
• Issue 配置: 可以添加外部链接（如 Stack Overflow）、禁用空白 Issue 等。
• PR 模板: 提醒贡献者描述改动内容、关联 Issue、添加测试等。
• Discussion 模板: 为 GitHub Discussions 提供结构化模板，如 Q&A、Ideas 等。
• Labels: 用颜色标签分类 Issue（如 bug、enhancement、help wanted），方便筛选和管理。
• Labeler: 当 PR 修改 src/ 目录时自动添加 area/core 标签，修改 docs/ 时添加 documentation 标签。
• CODEOWNERS: 定义哪些人负责哪些目录，PR 修改相关文件时自动请求他们审核。

---

🔒 安全 (Security)

保护项目免受安全漏洞威胁。

教育说明:

• Dependabot: GitHub 会自动扫描你的依赖，发现有安全漏洞时创建 PR 更新到安全版本。
• Renovate: Dependabot 的替代品，提供更多定制选项，如更新分组、自定义时间表。
• CodeQL: GitHub 的代码分析引擎，能检测 SQL 注入、XSS 等常见安全漏洞。
• 依赖审查: 在 PR 中自动检查新添加的依赖是否有已知漏洞。
• SECURITY.md: 告诉安全研究人员如何负责任地报告漏洞，而不是公开披露。

---

👥 社区健康文件 (Community Health)

GitHub 官方支持的社区健康文件，建设健康的开源社区。

教育说明:

• CONTRIBUTING.md: 说明如何设置开发环境、代码风格要求、PR 流程等，降低贡献门槛。
• CODE_OF_CONDUCT.md: 定义社区行为准则，营造友好包容的氛围。Contributor Covenant 是最流行的选择。
• SUPPORT.md: 告诉用户在哪里获取帮助：Issue、Discussions、Stack Overflow、Discord 等。
• GOVERNANCE.md: 说明项目如何做决策、谁有什么权限、如何成为维护者等。
• FUNDING.yml: 在仓库页面显示 "Sponsor" 按钮，支持 GitHub Sponsors、Open Collective、Patreon 等。

---

🤖 自动化 (Automation)

减少重复性工作，提高维护效率。

教育说明:

• release-drafter: 根据 PR 标签自动生成发布说明，如 "### 🚀 Features" "### 🐛 Bug Fixes"。
• auto-changelog: 根据 Conventional Commits 自动生成 CHANGELOG.md。
• stale: 对 60 天无活动的 Issue 添加 "stale" 标签，再过 7 天自动关闭，保持 Issue 列表整洁。
• greetings: 当有人首次提交 Issue 或 PR 时，自动发送欢迎消息。
• auto-merge: Dependabot 的安全更新 PR 通过 CI 后自动合并，减少手动操作。
• auto-assign: 根据 CODEOWNERS 或配置自动分配 PR 审核人。
• pr-labeler: 根据分支名（如 feature/*）或修改的文件自动添加标签。

---

🔧 代码质量 (Quality)

保持代码风格一致，提高代码质量。

教育说明:

• Super-Linter: GitHub 官方的多语言 Linter，支持 50+ 种语言和格式，一个 Action 搞定所有检查。
• Codecov: 在 PR 中显示测试覆盖率变化，防止覆盖率下降。
• 语义化 PR: 确保 PR 标题符合 Conventional Commits 规范，便于自动生成 changelog。
• Commitlint: 检查 commit 消息是否符合规范（如 feat:, fix:, docs: 等）。

---

📊 仓库配置 (Repository Settings)

GitHub 仓库级别的配置文件。

教育说明:

• 分支保护: 防止直接推送到 main 分支，要求 PR 审核和 CI 通过。
• 仓库设置: 使用 probot/settings 应用，通过 YAML 文件管理仓库设置。
• .gitattributes: 定义行尾处理、二进制文件识别、语言统计等。

---

预设定义

🚀 快速模式 (Quick)

智能推荐配置，适合快速启动。

包含组件 (共 8 个):

• 基础设施: readme, license, gitignore
• CI/CD: ci-basic
• 协作: issue-templates, pr-template, labels
• 安全: dependabot

交互流程: 1. 展示检测结果 2. 确认推荐配置 3. 收集必要变量（项目名、描述、作者等） 4. 执行

---

🎯 自定义模式 (Custom)

逐项选择，完全控制。

交互流程: 1. 展示检测结果 2. 分类展示所有组件（带教育说明） 3. 用户逐类选择 4. 对于选中的组件，选择参考仓库/风格 5. 收集必要变量 6. 确认并执行

---

📦 全量模式 (Full)

启用所有组件，适合企业级项目。

包含组件 (共 40+ 个):

交互流程: 1. 展示检测结果 2. 展示将生成的完整文件列表（40+ 个文件） 3. 收集必要变量 4. 确认执行

---

模板变量定义

重要: 所有模板变量必须在 Phase 2 收集阶段确定，不允许留空。

必需变量 (Required)

可选变量 (Optional)

变量收集规则

1. 优先自动检测: 尽可能从项目文件和 git 配置中自动获取 2. 检测失败时询问: 无法自动检测的必需变量，通过 AskUserQuestion 收集 3. 提供默认值: 可选变量提供合理默认值，用户可选择修改 4. 验证格式: 对邮箱、URL 等进行格式验证

---

组件 → 参考仓库映射

每个组件可以有多个参考仓库供用户选择：

issue-templates

ci-workflow

release-drafter

readme

contributing

code-of-conduct

labels

labeler

---

AskUserQuestion 模板

模式选择

{
  "question": "请选择配置模式",
  "header": "配置模式",
  "options": [
    {
      "label": "🚀 快速模式 (推荐新手)",
      "description": "智能推荐 8 个核心组件，只需确认即可"
    },
    {
      "label": "🎯 自定义模式",
      "description": "从 40+ 组件中逐个选择，了解每个功能的作用"
    },
    {
      "label": "📦 全量模式",
      "description": "启用所有 40+ 组件，适合企业级项目"
    }
  ],
  "multiSelect": false
}

分类组件选择（自定义模式）

{
  "question": "选择 CI/CD 工作流组件\n\nℹ️ CI (持续集成) 是什么？\n每次推送代码时，GitHub 会自动运行测试，确保新代码没有破坏现有功能。",
  "header": "🔄 CI/CD",
  "options": [
    {
      "label": "基础 CI (推荐)",
      "description": "自动运行测试和构建，每次推送都会检查"
    },
    {
      "label": "发布工作流",
      "description": "创建 Release 时自动发布到 npm/PyPI"
    },
    {
      "label": "多平台测试",
      "description": "同时在 Windows/macOS/Linux 上测试"
    },
    {
      "label": "GitHub Pages",
      "description": "自动部署静态站点到 GitHub Pages"
    }
  ],
  "multiSelect": true
}

参考仓库选择

{
  "question": "选择 Issue 模板的参考仓库\n\nℹ️ Issue 模板是什么？\n当用户在你的仓库创建 Issue 时，会看到预设表单，帮助他们提供结构化的 Bug 报告或功能请求。",
  "header": "📝 Issue 模板",
  "options": [
    {
      "label": "stevemao/github-issue-templates (推荐)",
      "description": "8 种风格可选：简洁、清单、对话式等，适合各类项目"
    },
    {
      "label": "dec0dOS/amazing-github-template",
      "description": "一站式模板，包含 Bug/Feature/Improvement，设计精美"
    },
    {
      "label": "使用内置默认模板",
      "description": "使用 gh-bootstrap 内置的通用模板（基于官方模板精简）"
    }
  ],
  "multiSelect": false
}

许可证选择

{
  "question": "选择开源许可证\n\nℹ️ 许可证决定了别人可以如何使用你的代码。",
  "header": "📜 许可证",
  "options": [
    {
      "label": "MIT (推荐)",
      "description": "最宽松，允许任何用途，只需保留版权声明"
    },
    {
      "label": "Apache 2.0",
      "description": "类似 MIT，但包含专利授权条款"
    },
    {
      "label": "GPL 3.0",
      "description": "要求衍生作品也必须开源"
    },
    {
      "label": "BSD 3-Clause",
      "description": "类似 MIT，禁止使用作者名字做推广"
    }
  ],
  "multiSelect": false
}

赞助平台选择

{
  "question": "选择赞助平台（可多选）\n\nℹ️ 在仓库页面显示 Sponsor 按钮，让支持者可以赞助你的项目。",
  "header": "💰 赞助平台",
  "options": [
    {
      "label": "GitHub Sponsors",
      "description": "GitHub 官方赞助平台，无手续费"
    },
    {
      "label": "Open Collective",
      "description": "适合团队/组织，财务透明"
    },
    {
      "label": "Patreon",
      "description": "按月订阅模式"
    },
    {
      "label": "Buy Me a Coffee",
      "description": "一次性小额赞助"
    }
  ],
  "multiSelect": true
}

Templates Directory

本目录存放 gh-bootstrap 的内置模板文件。

When to Use

• 内置组件：无需从外部仓库下载的组件模板
• 默认配置：当外部模板下载失败时的回退方案
• 快速参考：常用配置的标准格式

目录结构

templates/
├── README.md              # 本文件
├── workflows/             # GitHub Actions 工作流模板
├── issue-templates/       # Issue 模板
├── community/             # 社区文件模板
└── configs/               # 配置文件模板

使用原则

1. 优先使用外部模板：template-catalog.md 中定义的外部仓库模板优先 2. 内置模板作为回退：仅当外部下载失败时使用内置模板 3. 保持同步更新：定期与上游模板同步

相关文档

• specs/template-catalog.md - 外部模板目录
• specs/execution-rules.md - 执行规则
• phases/04-execution.md - 执行阶段