From 32b457b6deeebb65fd6771acab7d1a11103e4185 Mon Sep 17 00:00:00 2001 From: stack Date: Sun, 5 Jul 2026 20:13:07 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=8F=AF=E7=A7=BB=E6=A4=8D?= =?UTF-8?q?=E6=80=A7=E4=B8=8E=E7=A4=BE=E5=8C=BA=E7=94=9F=E6=80=81=E6=8F=90?= =?UTF-8?q?=E5=8D=87=E6=96=B9=E6=B3=95=E8=AE=BA=20Playbook?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/playbooks/portability-ecosystem.md: P0-P3 完整方法论 - 问题诊断清单 / 优先级与 ROI 矩阵 / 里程碑模板 - 每阶段实施指南（含代码示例） - 常见反模式与适用场景判断 - docs/.vitepress/config.ts: 导航栏加入 Playbooks - .gitignore: 忽略 VitePress dist + .temp 构建产物 --- .gitignore | 5 + docs/.vitepress/config.ts | 10 + docs/playbooks/portability-ecosystem.md | 236 ++++++++++++++++++++++++ 3 files changed, 251 insertions(+) create mode 100644 docs/playbooks/portability-ecosystem.md diff --git a/.gitignore b/.gitignore index f4aa597..454c9f4 100644 --- a/.gitignore +++ b/.gitignore @@ -15,5 +15,10 @@ env/secrets.json .codex/ .claude/ node_modules/ + +# VitePress build output (generated by CI) +docs/.vitepress/dist/ +docs/.vitepress/.temp/ + skills-engineering/ios-engineer/evolution/usage/* !skills-engineering/ios-engineer/evolution/usage/usage.jsonl diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index bbca95a..7ccd9a0 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -23,6 +23,7 @@ export default defineConfig({ nav: [ { text: 'Home', link: '/' }, { text: 'iOS Engineer', link: '/ios-engineer/' }, + { text: 'Playbooks', link: '/playbooks/portability-ecosystem' }, { text: 'GitHub', link: 'https://github.com/i-stack/ai-coding-kit' }, ], @@ -38,6 +39,15 @@ export default defineConfig({ ], }, ], + '/playbooks/': [ + { + text: 'Playbooks', + collapsed: false, + items: [ + { text: '可移植性与社区生态提升', link: '/playbooks/portability-ecosystem' }, + ], + }, + ], }, socialLinks: [ diff --git a/docs/playbooks/portability-ecosystem.md b/docs/playbooks/portability-ecosystem.md new file mode 100644 index 0000000..a79995d --- /dev/null +++ b/docs/playbooks/portability-ecosystem.md @@ -0,0 +1,236 @@ +# 可移植性与社区生态提升方法论 + +> 本文档记录了 ai-coding-kit 从「内部工具」到「社区可复用项目」的 4 阶段实践（P0–P3）。 +> 其他项目可直接复用「优先级与 ROI 矩阵」「问题诊断清单」「里程碑模板」。 + +--- + +## 问题诊断清单 + +在开始改造前，用以下清单快速扫描项目薄弱点： + +| 维度 | 检查项 | 诊断手段 | +|------|--------|----------| +| **平台覆盖** | 支持几个 AI 编码平台？目标用户用哪些？ | 统计 `SYNC_TARGETS` 或平台配置数 | +| **语言锁定** | 内容是否强制单一语言？是否阻断了非母语用户？ | grep 输出语言相关规则 | +| **安装体验** | 用户如何安装？是否有包管理器支持？ | 检查是否存在 `brew`/`npm`/`pip` 等入口 | +| **版本管理** | 是否有 Git Tag / Release Notes？用户能否 pin 版本？ | `git tag --list` | +| **CI/CD** | 是否有自动化质量门禁？每次变更是否自动校验？ | 检查 `.github/workflows/` | +| **贡献体系** | 外部贡献者是否知道如何参与？ | 检查 `CONTRIBUTING.md` / `CODEOWNERS` | +| **文档可发现性** | 用户能否通过搜索引擎找到文档？ | Google 搜索项目名 | +| **硬编码路径** | 是否存在个人机器路径？其他人 clone 后能否直接运行？ | `grep -r '/Users/' --include="*.sh"` | + +--- + +## 优先级与 ROI 矩阵 + +| 优先级 | 任务 | 工作量 | 影响面 | ROI | 适用于 | +|--------|------|--------|--------|-----|--------| +| **P0** | CI 自动验证流水线（规则一致性 / 场景校验 / 新鲜度审计 / 硬编码扫查） | 2h | 每次 PR 自动拦截回归 | 🔴 极高 | 所有含自动化脚本的项目 | +| **P0** | 清理硬编码路径 + CI grep 守卫 | 0.5h | 消除"clone 后报错" | 🔴 极高 | 存在 shell 脚本或个人路径配置的项目 | +| **P1** | CONTRIBUTING.md + CODEOWNERS | 1h | 打通社区参与通道 | 🟠 高 | 所有公开仓库 | +| **P1** | i18n 分层：元指令层英文化 + 治理层翻译 | 4h | 解锁国际用户 | 🟠 高 | 内容驱动型项目（Agent Skill / 文档 / 规则体系） | +| **P2** | Git Tag + Release Notes + CHANGELOG | 1h | 外部可 pin 版本 | 🟡 中 | 所有发布型项目 | +| **P2** | Homebrew Formula / npm package / 包管理器分发 | 2h | 扩大安装渠道 | 🟡 中 | CLI 工具 / 可安装技能包 | +| **P3** | VitePress / Docusaurus 文档站 + GitHub Pages 部署 | 3h | 搜索引擎可发现，降低学习曲线 | 🟢 锦上添花 | 含技术文档的公开仓库 | +| **P3** | 多语言文档站（中/英） | 2h | 覆盖非英语开发群体 | 🟢 锦上添花 | 文档量大的项目 | + +### ROI 计算逻辑 + +- **P0（立即止血）**：不改则持续漏血。CI 缺失 → 每个合并都可能引入回归；硬编码路径 → 每个新贡献者 clone 后第一步就失败。 +- **P1（快速见效）**：改动小但打开流量入口。国际化让潜在用户数放大 10–100 倍；CONTRIBUTING 让外部开发者从"看了不会做"变为"照着文档即可提交 PR"。 +- **P2（基础设施）**：不是紧急项但一旦上线就会持续产生价值（每个新用户都会走包管理器安装）。 +- **P3（放大收益）**：锦上添花，适合 P0+P1 完成后再做。文档站让内容可被 Google 索引，带来有机用户增长。 + +--- + +## 实施指南 + +### P0 — CI 自动验证 + +**核心原则**：每次 PR 都应触发自动化校验，无需人工介入。 + +```yaml +# .github/workflows/validate.yml 关键 Job +validate: + - 规则 ID 双向一致性（定义文件 ↔ 入口文件） + - 场景规格校验（JSON/Markdown schema） + - 参考文件新鲜度审计（last-verified 日期扫描） + - 使用台账校验 + - 演进流水线完整校验（跳过需运行时环境的步骤） + +hardcoded-paths: + - 扫描所有提交文件，正则匹配 '/Users/' 个人路径 + - 白名单排除模板路径（如 '/Users/you/...'） +``` + +**适用条件**：项目有自动化脚本（shell/python）即可，不挑语言栈。 + +### P0 — 硬编码路径清理 + +**常见硬编码模式**： + +```bash +# ❌ 坏 +PROJECT_PATH="/Users/song/Desktop/iOS/MyApp" +# ✅ 好 +PROJECT_PATH="${PROJECT_PATH:-~/path/to/your/project}" +``` + +**CI 挡板**： + +```bash +find . -type f -not -path './.git/*' -print0 \ + | xargs -0 grep -n '/Users/' \ + | grep -v '/Users/you/' \ + | grep -v '/Users/YourName/' +``` + +### P1 — i18n 分层架构 + +**核心设计**：不移动现有文件，以镜像层叠加。 + +``` +project/ +├── SKILL.md # 元指令层 → 英文（路由/优先级/判据） +├── references/ # 中文源文件（不移动） +│ └── rule_index.md +└── i18n/ + └── en-US/ # 英文镜像层 + └── references/ + └── rule_index.md +``` + +**翻译优先级**： +1. 治理层文件（rule_index / self_evolution / cognitive_adversary_mode）—— 理解体系运作的入口 +2. 架构概述（architecture_and_network / architecture_analysis）—— 高频引用 +3. 其余领域 reference —— 按引用频率排序 + +**IR-001 语义升级**： +``` +旧: 强制中文输出 +新: 输出语言与用户输入语言一致（auto-match） +``` + +### P1 — 贡献指南 + +`CONTRIBUTING.md` 必备板块： + +```markdown +## 新增 Reference（提案驱动） +1. 创建 proposal +2. 实现 + 校验 +3. 提交 PR + +## 翻译贡献 +1. 在 i18n/{locale}/ 创建对应文件 +2. 保持结构一致 +3. CI 自动校验中英文件数量 + +## Commit 规范 +feat / fix / ref / evolve / chore / docs +``` + +### P2 — 包管理器分发 + +**Homebrew Formula 要素**： + +```ruby +class MyProject < Formula + desc "One-line description" + homepage "https://github.com/user/repo" + url "https://github.com/user/repo/archive/refs/tags/v1.0.0.tar.gz" + license "MIT" + + def install + prefix.install Dir["*"] + bin.install_symlink prefix/"run.sh" => "myproject" + end +end +``` + +**npm package.json 要素**： + +```json +{ + "name": "@scope/pkg", + "version": "1.0.0", + "bin": { "myproject": "./run.sh" }, + "files": ["src/", "run.sh", "README.md"], + "keywords": ["relevant", "search", "terms"] +} +``` + +### P3 — 文档站 + +**VitePress 最小启动**： + +```bash +mkdir docs && cd docs +# 创建 .vitepress/config.ts + index.md +npm install -D vitepress +npm run docs:dev # 本地预览 +npm run docs:build # 构建静态站 +``` + +**GitHub Pages 自动部署**： + +```yaml +# .github/workflows/deploy-docs.yml +on: + push: + paths: ['docs/**', 'package.json'] + +jobs: + build: + steps: + - uses: actions/setup-node@v4 + with: { node-version: 22 } + - run: npm ci && npm run docs:build + - uses: actions/upload-pages-artifact@v3 + + deploy: + needs: build + steps: + - uses: actions/deploy-pages@v4 +``` + +**前置条件**：GitHub 仓库 Settings → Pages → Source → GitHub Actions（启用一次）。 + +--- + +## 里程碑模板 + +| 周 | 目标 | 产出 | +|----|------|------| +| **W1 — 止住出血点** | CI + 硬编码清理 + CONTRIBUTING | 每次 PR 自动校验 + 任何人 clone 后可直接运行 | +| **W2 — 打开国际通道** | i18n 分层 + SKILL.md 英文化 | 非母语用户可直接使用 | +| **W3 — 正式发布** | Git Tag + CHANGELOG + Homebrew + 文档站上线 | 通过 `brew install` 或 `npm i` 安装，文档可被搜索 | + +--- + +## 常见反模式 + +| 反模式 | 为什么不行 | 正确做法 | +|--------|-----------|----------| +| 先做文档站再做 CI | 文档站引流的用户看到 broken 项目就流失了 | CI 先于文档站 | +| 翻译全部 references 再发布 | 30+ 份文件翻译周期长，阻塞发布 | 先翻治理层 3 份，其余渐进 | +| 只打 Tag 无 Release Notes | 用户不知道新版本有什么变化 | Tag + CHANGELOG 同时发布 | +| Homebrew Formula 含硬编码 sha256 | 每个版本都要手动更新 | 首次留空，提示用户 `shasum` 补填 | + +--- + +## 适用场景判断 + +| 项目特征 | 适用优先级 | +|----------|-----------| +| 只有 README 没有文档站 | **P3** 文档站，P3 多语言 | +| 只有英文内容没有中文 | **P1** i18n 分层（反方向：en-US → zh-CN） | +| 有 CI 但没有规则校验 | **P0** 补充业务规则校验 Job | +| 无 CHANGELOG 无版本号 | **P2** Git Tag + CHANGELOG | +| 有 shell 脚本但无包管理器 | **P2** Homebrew / npm | +| 公开仓库无贡献指南 | **P1** CONTRIBUTING + CODEOWNERS | + +--- + +> 最后更新：2026-07-05 · ai-coding-kit v3.0.0 From 67547bb7c49deb0bd36964b790891b14d2a517a3 Mon Sep 17 00:00:00 2001 From: stack Date: Sun, 5 Jul 2026 20:20:41 +0800 Subject: [PATCH 2/2] docs: enhance portability playbook with implementation guides and templates - Updated docs/playbooks/portability-ecosystem.md to include comprehensive implementation guides, milestone templates, and common anti-patterns. - Adjusted navigation in .vitepress/config.ts to feature the new playbooks section. - Updated .gitignore to exclude VitePress build artifacts. --- .gitignore | 1 + docs/.vitepress/config.ts | 11 -- docs/playbooks/portability-ecosystem.md | 236 ------------------------ tools/cleanup-github-deployments.sh | 134 ++++++++++++++ 4 files changed, 135 insertions(+), 247 deletions(-) delete mode 100644 docs/playbooks/portability-ecosystem.md create mode 100755 tools/cleanup-github-deployments.sh diff --git a/.gitignore b/.gitignore index 454c9f4..0d974fd 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ docs/.vitepress/.temp/ skills-engineering/ios-engineer/evolution/usage/* !skills-engineering/ios-engineer/evolution/usage/usage.jsonl +templates/portability-ecosystem.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 7ccd9a0..441bcea 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -17,13 +17,11 @@ export default defineConfig({ ], themeConfig: { - logo: false, siteTitle: 'ai-coding-kit', nav: [ { text: 'Home', link: '/' }, { text: 'iOS Engineer', link: '/ios-engineer/' }, - { text: 'Playbooks', link: '/playbooks/portability-ecosystem' }, { text: 'GitHub', link: 'https://github.com/i-stack/ai-coding-kit' }, ], @@ -39,15 +37,6 @@ export default defineConfig({ ], }, ], - '/playbooks/': [ - { - text: 'Playbooks', - collapsed: false, - items: [ - { text: '可移植性与社区生态提升', link: '/playbooks/portability-ecosystem' }, - ], - }, - ], }, socialLinks: [ diff --git a/docs/playbooks/portability-ecosystem.md b/docs/playbooks/portability-ecosystem.md deleted file mode 100644 index a79995d..0000000 --- a/docs/playbooks/portability-ecosystem.md +++ /dev/null @@ -1,236 +0,0 @@ -# 可移植性与社区生态提升方法论 - -> 本文档记录了 ai-coding-kit 从「内部工具」到「社区可复用项目」的 4 阶段实践（P0–P3）。 -> 其他项目可直接复用「优先级与 ROI 矩阵」「问题诊断清单」「里程碑模板」。 - ---- - -## 问题诊断清单 - -在开始改造前，用以下清单快速扫描项目薄弱点： - -| 维度 | 检查项 | 诊断手段 | -|------|--------|----------| -| **平台覆盖** | 支持几个 AI 编码平台？目标用户用哪些？ | 统计 `SYNC_TARGETS` 或平台配置数 | -| **语言锁定** | 内容是否强制单一语言？是否阻断了非母语用户？ | grep 输出语言相关规则 | -| **安装体验** | 用户如何安装？是否有包管理器支持？ | 检查是否存在 `brew`/`npm`/`pip` 等入口 | -| **版本管理** | 是否有 Git Tag / Release Notes？用户能否 pin 版本？ | `git tag --list` | -| **CI/CD** | 是否有自动化质量门禁？每次变更是否自动校验？ | 检查 `.github/workflows/` | -| **贡献体系** | 外部贡献者是否知道如何参与？ | 检查 `CONTRIBUTING.md` / `CODEOWNERS` | -| **文档可发现性** | 用户能否通过搜索引擎找到文档？ | Google 搜索项目名 | -| **硬编码路径** | 是否存在个人机器路径？其他人 clone 后能否直接运行？ | `grep -r '/Users/' --include="*.sh"` | - ---- - -## 优先级与 ROI 矩阵 - -| 优先级 | 任务 | 工作量 | 影响面 | ROI | 适用于 | -|--------|------|--------|--------|-----|--------| -| **P0** | CI 自动验证流水线（规则一致性 / 场景校验 / 新鲜度审计 / 硬编码扫查） | 2h | 每次 PR 自动拦截回归 | 🔴 极高 | 所有含自动化脚本的项目 | -| **P0** | 清理硬编码路径 + CI grep 守卫 | 0.5h | 消除"clone 后报错" | 🔴 极高 | 存在 shell 脚本或个人路径配置的项目 | -| **P1** | CONTRIBUTING.md + CODEOWNERS | 1h | 打通社区参与通道 | 🟠 高 | 所有公开仓库 | -| **P1** | i18n 分层：元指令层英文化 + 治理层翻译 | 4h | 解锁国际用户 | 🟠 高 | 内容驱动型项目（Agent Skill / 文档 / 规则体系） | -| **P2** | Git Tag + Release Notes + CHANGELOG | 1h | 外部可 pin 版本 | 🟡 中 | 所有发布型项目 | -| **P2** | Homebrew Formula / npm package / 包管理器分发 | 2h | 扩大安装渠道 | 🟡 中 | CLI 工具 / 可安装技能包 | -| **P3** | VitePress / Docusaurus 文档站 + GitHub Pages 部署 | 3h | 搜索引擎可发现，降低学习曲线 | 🟢 锦上添花 | 含技术文档的公开仓库 | -| **P3** | 多语言文档站（中/英） | 2h | 覆盖非英语开发群体 | 🟢 锦上添花 | 文档量大的项目 | - -### ROI 计算逻辑 - -- **P0（立即止血）**：不改则持续漏血。CI 缺失 → 每个合并都可能引入回归；硬编码路径 → 每个新贡献者 clone 后第一步就失败。 -- **P1（快速见效）**：改动小但打开流量入口。国际化让潜在用户数放大 10–100 倍；CONTRIBUTING 让外部开发者从"看了不会做"变为"照着文档即可提交 PR"。 -- **P2（基础设施）**：不是紧急项但一旦上线就会持续产生价值（每个新用户都会走包管理器安装）。 -- **P3（放大收益）**：锦上添花，适合 P0+P1 完成后再做。文档站让内容可被 Google 索引，带来有机用户增长。 - ---- - -## 实施指南 - -### P0 — CI 自动验证 - -**核心原则**：每次 PR 都应触发自动化校验，无需人工介入。 - -```yaml -# .github/workflows/validate.yml 关键 Job -validate: - - 规则 ID 双向一致性（定义文件 ↔ 入口文件） - - 场景规格校验（JSON/Markdown schema） - - 参考文件新鲜度审计（last-verified 日期扫描） - - 使用台账校验 - - 演进流水线完整校验（跳过需运行时环境的步骤） - -hardcoded-paths: - - 扫描所有提交文件，正则匹配 '/Users/' 个人路径 - - 白名单排除模板路径（如 '/Users/you/...'） -``` - -**适用条件**：项目有自动化脚本（shell/python）即可，不挑语言栈。 - -### P0 — 硬编码路径清理 - -**常见硬编码模式**： - -```bash -# ❌ 坏 -PROJECT_PATH="/Users/song/Desktop/iOS/MyApp" -# ✅ 好 -PROJECT_PATH="${PROJECT_PATH:-~/path/to/your/project}" -``` - -**CI 挡板**： - -```bash -find . -type f -not -path './.git/*' -print0 \ - | xargs -0 grep -n '/Users/' \ - | grep -v '/Users/you/' \ - | grep -v '/Users/YourName/' -``` - -### P1 — i18n 分层架构 - -**核心设计**：不移动现有文件，以镜像层叠加。 - -``` -project/ -├── SKILL.md # 元指令层 → 英文（路由/优先级/判据） -├── references/ # 中文源文件（不移动） -│ └── rule_index.md -└── i18n/ - └── en-US/ # 英文镜像层 - └── references/ - └── rule_index.md -``` - -**翻译优先级**： -1. 治理层文件（rule_index / self_evolution / cognitive_adversary_mode）—— 理解体系运作的入口 -2. 架构概述（architecture_and_network / architecture_analysis）—— 高频引用 -3. 其余领域 reference —— 按引用频率排序 - -**IR-001 语义升级**： -``` -旧: 强制中文输出 -新: 输出语言与用户输入语言一致（auto-match） -``` - -### P1 — 贡献指南 - -`CONTRIBUTING.md` 必备板块： - -```markdown -## 新增 Reference（提案驱动） -1. 创建 proposal -2. 实现 + 校验 -3. 提交 PR - -## 翻译贡献 -1. 在 i18n/{locale}/ 创建对应文件 -2. 保持结构一致 -3. CI 自动校验中英文件数量 - -## Commit 规范 -feat / fix / ref / evolve / chore / docs -``` - -### P2 — 包管理器分发 - -**Homebrew Formula 要素**： - -```ruby -class MyProject < Formula - desc "One-line description" - homepage "https://github.com/user/repo" - url "https://github.com/user/repo/archive/refs/tags/v1.0.0.tar.gz" - license "MIT" - - def install - prefix.install Dir["*"] - bin.install_symlink prefix/"run.sh" => "myproject" - end -end -``` - -**npm package.json 要素**： - -```json -{ - "name": "@scope/pkg", - "version": "1.0.0", - "bin": { "myproject": "./run.sh" }, - "files": ["src/", "run.sh", "README.md"], - "keywords": ["relevant", "search", "terms"] -} -``` - -### P3 — 文档站 - -**VitePress 最小启动**： - -```bash -mkdir docs && cd docs -# 创建 .vitepress/config.ts + index.md -npm install -D vitepress -npm run docs:dev # 本地预览 -npm run docs:build # 构建静态站 -``` - -**GitHub Pages 自动部署**： - -```yaml -# .github/workflows/deploy-docs.yml -on: - push: - paths: ['docs/**', 'package.json'] - -jobs: - build: - steps: - - uses: actions/setup-node@v4 - with: { node-version: 22 } - - run: npm ci && npm run docs:build - - uses: actions/upload-pages-artifact@v3 - - deploy: - needs: build - steps: - - uses: actions/deploy-pages@v4 -``` - -**前置条件**：GitHub 仓库 Settings → Pages → Source → GitHub Actions（启用一次）。 - ---- - -## 里程碑模板 - -| 周 | 目标 | 产出 | -|----|------|------| -| **W1 — 止住出血点** | CI + 硬编码清理 + CONTRIBUTING | 每次 PR 自动校验 + 任何人 clone 后可直接运行 | -| **W2 — 打开国际通道** | i18n 分层 + SKILL.md 英文化 | 非母语用户可直接使用 | -| **W3 — 正式发布** | Git Tag + CHANGELOG + Homebrew + 文档站上线 | 通过 `brew install` 或 `npm i` 安装，文档可被搜索 | - ---- - -## 常见反模式 - -| 反模式 | 为什么不行 | 正确做法 | -|--------|-----------|----------| -| 先做文档站再做 CI | 文档站引流的用户看到 broken 项目就流失了 | CI 先于文档站 | -| 翻译全部 references 再发布 | 30+ 份文件翻译周期长，阻塞发布 | 先翻治理层 3 份，其余渐进 | -| 只打 Tag 无 Release Notes | 用户不知道新版本有什么变化 | Tag + CHANGELOG 同时发布 | -| Homebrew Formula 含硬编码 sha256 | 每个版本都要手动更新 | 首次留空，提示用户 `shasum` 补填 | - ---- - -## 适用场景判断 - -| 项目特征 | 适用优先级 | -|----------|-----------| -| 只有 README 没有文档站 | **P3** 文档站，P3 多语言 | -| 只有英文内容没有中文 | **P1** i18n 分层（反方向：en-US → zh-CN） | -| 有 CI 但没有规则校验 | **P0** 补充业务规则校验 Job | -| 无 CHANGELOG 无版本号 | **P2** Git Tag + CHANGELOG | -| 有 shell 脚本但无包管理器 | **P2** Homebrew / npm | -| 公开仓库无贡献指南 | **P1** CONTRIBUTING + CODEOWNERS | - ---- - -> 最后更新：2026-07-05 · ai-coding-kit v3.0.0 diff --git a/tools/cleanup-github-deployments.sh b/tools/cleanup-github-deployments.sh new file mode 100755 index 0000000..61fd80b --- /dev/null +++ b/tools/cleanup-github-deployments.sh @@ -0,0 +1,134 @@ +#!/bin/bash +# ============================================================================= +# 删除 GitHub Deployments 工具 +# ============================================================================= +# 用途：清理 GitHub 仓库中失败的或不活跃的 Deployments +# 依赖：需要安装 gh CLI 并已登录 (gh auth login) +# +# 用法： +# ./cleanup-github-deployments.sh [--dry-run] [--all] +# +# 参数： +# --dry-run 仅查看，不实际删除 +# --all 删除所有 Deployment（包括成功的），默认只删除非 success 的 +# +# 示例： +# # 预览将要删除的部署（不实际删除） +# ./cleanup-github-deployments.sh i-stack ai-coding-kit --dry-run +# +# # 删除所有失败的/非活跃的部署 +# ./cleanup-github-deployments.sh i-stack ai-coding-kit +# +# # 删除所有部署（包括成功的） +# ./cleanup-github-deployments.sh i-stack ai-coding-kit --all +# ============================================================================= + +set -euo pipefail + +# ---- 参数解析 ---- +OWNER="${1:-}" +REPO="${2:-}" +DRY_RUN=false +DELETE_ALL=false + +shift 2 2>/dev/null || true +for arg in "$@"; do + case "$arg" in + --dry-run) DRY_RUN=true ;; + --all) DELETE_ALL=true ;; + *) echo "未知参数: $arg"; exit 1 ;; + esac +done + +if [ -z "$OWNER" ] || [ -z "$REPO" ]; then + echo "用法: $0 [--dry-run] [--all]" + exit 1 +fi + +# ---- 检查 gh CLI ---- +if ! command -v gh &> /dev/null; then + echo "错误: 需要安装 gh CLI (brew install gh)" + exit 1 +fi + +if ! gh auth status &> /dev/null; then + echo "错误: 请先登录 gh (gh auth login)" + exit 1 +fi + +echo "============================================" +echo " GitHub Deployments 清理工具" +echo " 仓库: $OWNER/$REPO" +echo " 模式: $(if $DRY_RUN; then echo '预览 (不删除)'; elif $DELETE_ALL; then echo '删除全部'; else echo '删除非成功'; fi)" +echo "============================================" +echo "" + +# ---- 获取所有部署并逐个处理 ---- +DELETED=0 +SKIPPED=0 + +gh api "/repos/$OWNER/$REPO/deployments" --jq '.[].id' | while read -r id; do + # 获取最新状态 + state=$(gh api "/repos/$OWNER/$REPO/deployments/$id/statuses" --jq '.[0].state // "pending"' 2>/dev/null || echo "unknown") + created=$(gh api "/repos/$OWNER/$REPO/deployments/$id" --jq '.created_at' 2>/dev/null || echo "unknown") + env_name=$(gh api "/repos/$OWNER/$REPO/deployments/$id" --jq '.environment // "unknown"' 2>/dev/null || echo "unknown") + + # 判断是否需要删除 + should_delete=false + if $DELETE_ALL; then + should_delete=true + elif [ "$state" != "success" ]; then + should_delete=true + fi + + if $should_delete; then + if $DRY_RUN; then + echo "[预览] 将删除: id=$id state=$state env=$env_name created=$created" + else + echo -n "删除 deployment $id (state=$state)... " + gh api -X DELETE "/repos/$OWNER/$REPO/deployments/$id" --silent 2>/dev/null && echo "完成" || echo "失败" + fi + else + echo "保留: id=$id state=$state env=$env_name created=$created" + fi +done + +echo "" +echo "============================================" +if $DRY_RUN; then + echo " 预览结束（未实际删除）。移除 --dry-run 以执行删除。" +else + echo " 清理完成！" +fi +echo "============================================" + +# ============================================================================= +# 手动操作参考（不使用脚本时） +# ============================================================================= +# +# 1. 列出所有 Deployments: +# gh api /repos/{owner}/{repo}/deployments --jq '.[].id' +# +# 2. 查看某个 Deployment 的最新状态: +# gh api /repos/{owner}/{repo}/deployments/{id}/statuses --jq '.[0].state' +# +# 3. 查看某个 Deployment 详情: +# gh api /repos/{owner}/{repo}/deployments/{id} --jq '{id, environment, ref, created_at, description}' +# +# 4. 删除单个 Deployment: +# gh api -X DELETE /repos/{owner}/{repo}/deployments/{id} +# +# 5. 批量删除所有失败的 Deployment: +# gh api /repos/{owner}/{repo}/deployments --jq '.[].id' | while read id; do +# state=$(gh api /repos/{owner}/{repo}/deployments/$id/statuses --jq '.[0].state // empty') +# if [ "$state" != "success" ]; then +# echo "Deleting $id..." +# gh api -X DELETE /repos/{owner}/{repo}/deployments/$id +# fi +# done +# +# 注意： +# - GitHub Web UI 中没有直接删除 Deployment 的按钮，只能通过 API/CLI 操作 +# - 删除 Deployment 不会删除对应的 Actions workflow run +# - 建议先使用 --dry-run 预览再执行实际删除 +# =============================================================================