Skip to content

nicholyx/ai-skills / custom/daily/oss-bootstrap

oss-bootstrap

Verified

把一个新项目(或只有代码的裸仓库)落实为符合主流规范的开源项目——CI、治理文件、Issue/PR 模板、仓库自动化、文档体系、看板与发布流程。当用户说「新建开源项目」「给项目加上 CI / 规范」「给这个项目加上开源规范」「按热门开源项目的标准搭基建」时使用。基建就位后的日常迭代请改用 maintain-loop skill。

开源项目 Bootstrap(oss-bootstrap)

把一个裸仓库变成结构完整的开源项目。

与 maintain-loop 的关系

  • 本 skill:从 0 到 1 搭基建(只做一次,或大改时回来对照)
  • maintain-loop skill:基建就位后,日常迭代的闭环(规划 → 实现 → 发布)

搭完基建后,一切开发工作都应切换到 maintain-loop 的流程。


第零步:先探测,再动手

本 skill 不绑定任何具体仓库。 动手前先花几分钟把下面四件事弄清楚—— 判断得出来的就自己判断,只有真正属于用户的决定才需要确认。

1. 项目类型与工具链(决定 CI 里放什么)

ls -a                                    # 有没有 package.json / pyproject.toml / go.mod
git ls-files | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20   # 文件类型分布
形态静态检查测试
bashshellcheck -x、bash -nbats,或内联断言脚本
YAML(Actions)actionlint、yamllint—
Gogolangci-lintgo test
JS/TSeslint、tsc --noEmitvitest / jest
Pythonruffpytest
内容仓库(Markdown/JSON,无构建)结构校验脚本、内部链接校验、编码校验结构断言

没有构建产物不代表没有可检查的东西。 内容仓库(文档站、技能库、模板集、 配置集)最值钱的三类检查是:结构一致性(schema、frontmatter、必填字段)、 内部引用有效性(相对链接指向的文件是否真的存在)、编码卫生(替换字符、 末尾换行、非法字节序列)。这三类都不需要真的「跑」代码,成本极低而收益很高。

2. 仓库现状

gh repo view --json name,visibility,isFork,parent,hasIssuesEnabled,hasDiscussionsEnabled,licenseInfo,viewerPermission
git log --oneline | wc -l
  • 是 fork 吗? fork 仓库的 Issues 默认禁用,且改不了仓库设置。脱离 fork network 只能在网页端 Danger Zone 操作,API 做不了,且不可逆
  • GitHub 认出 LICENSE 了吗? licenseInfo.key 为 null 或显示 NOASSERTION, 多半是许可证文本里被追加了额外段落——必须保持纯许可证文本才能被识别
  • 仓库是空的吗? isEmpty: true 时分支保护等设置无从谈起

3. 权限

gh auth status    # 需要 repo、workflow;操作 Projects 还需要 project, read:project

缺 scope 时请用户执行 gh auth refresh -s project,read:project(这一步要用户自己跑)。

4. 仓库里现在有什么

ls -a && git ls-files | awk -F/ '{print $1}' | sort -u

已经存在的治理文件不要重写,先读一遍再决定补什么。用户可能已经有 LICENSE、 README 或 CLAUDE.md,其中有些判断值得保留。

不要一次性问用户一堆问题

语言与现状自己判断。只有这几类才需要确认:LICENSE 选型、是否已有使用者 (决定要不要留破坏性变更的余地)、仓库是公开还是私有(决定能否用 Scorecard)。

实施节奏

按阶段推进,每个组件独立分支 + 独立 PR,小批量提交,CI 全绿再合并。分支与合并 规范见 maintain-loop。


阶段一:地基 —— CI 与提交规范

这是其他一切的前提:先让「每次改动都被自动检查」跑起来。

1. CI 工作流,骨架固定为四层

  • 静态检查:按语言选工具,固定版本号(可复现)。工具版本写在工作流顶部的 env:,成为唯一真源
  • 测试:冒烟(快、无外部依赖)+ 集成(真实路径,能发现 mock 发现不了的问题)。 没有容器/网络依赖的检查别硬塞进需要它们的那一层
  • 提交信息校验:Conventional Commits,用脚本实现(见下),同时校验 区间内的提交与 PR 标题(squash 后标题即提交信息)
  • ci-summary 汇总 job:needs: [全部检查] + if: always(),把所有检查汇总成 一个结果。分支保护规则只需要盯这一个 check,增删检查项不用改保护规则

2. ci-summary 必须从单一真源派生,并自证完整

汇总 job 最常见的失败模式:needs / 显示名数组 / 结果变量三份手工维护的平行 列表,新增检查时漏改其中一份 —— 于是子 job 失败而汇总仍报成功。

把它写成派生的,并加断言:

declare -a jobs=("job-id:显示名" ...)

# 断言 jobs 数组与 ci.yml 的 needs 是同一个集合(比集合,不比数量——同长度互换也会漏)
cfg_ids="$(grep -m1 '^    needs: \[' .github/workflows/ci.yml \
           | sed 's/.*\[//; s/\].*//' | tr ',' '\n' | tr -d ' ' | grep . | sort)"
arr_ids="$(printf '%s\n' "${jobs[@]}" | cut -d: -f1 | sort)"
[[ "$cfg_ids" == "$arr_ids" ]] || { echo "::error::汇总表与 needs 不一致"; exit 1; }

for spec in "${jobs[@]}"; do
  id="${spec%%:*}"; var="R_$(printf '%s' "$id" | tr 'a-z-' 'A-Z_')"
  result="${!var:-}"
  # 断言:每个 id 都有对应 env,缺了就是「进了 needs 但没进判据」
  [[ -n "$result" ]] || { echo "::error::needs 里有 $id 但没有 env $var"; failed=1; }
  # skipped 只在确实会跳过的 job 上算良性;别处出现 skipped 说明 if 条件写错了
done

注意 tr -d '[],' 会把 needs: 这个前缀也切出来当成一个 id —— 用 sed 's/.*\[//; s/\].*//' 只取方括号内的内容。

3. 本地统一入口 scripts/lint.sh

一条命令跑完 CI 里本地能跑的那些检查。目标是「本地绿 == CI 绿」。

./scripts/lint.sh                 # 跑全部
./scripts/lint.sh --list          # 列出检查项 id 与显示名
./scripts/lint.sh --only links    # 只跑指定项
./scripts/lint.sh --skip zizmor   # 跳过(如需要 docker 的那项)

设计要点:

  • 四个辅助函数:run_check / skip_check / fail_check / note
  • 「工具在但检查跑不起来」算失败,不算跳过 —— 静默跳过与通过无法区分
  • 三个计数器 + 两类附加清单:PASSED/FAILED/SKIPPED 不足以表达 「跑了但不是 CI 同源」(本机工具版本与 CI pin 不一致)与「跑不起来(环境问题)」, 这两类在结尾单独列出
  • 头部注释明确写出「不覆盖什么」,尤其:PR 标题。CI 校验 PR 标题,而标题 在 PR 建立之前不存在,本地任何入口都验不了。本地全绿不等于 commit-messages 会绿
  • 入口脚本必须可执行(chmod +x),并在 CI 里断言可执行位

4. 「本地过 = CI 过」需要有人守:lint-selftest job

lint.sh 是 CI 里被调用为零的脚本,而它的全部价值就是那条等价保证。加一个 job 断言它的行为,断言方向两两相反:

  • 给自建内容注入违规 → lint.sh 必须失败,且失败原因必须是那个违规 (不是环境问题 —— 否则断言是恒真的)
  • 给只读 vendor 区注入同样的违规 → 必须仍然通过,且违规必须出现在输出里
  • 同一份工作区跑两次,输出逐字节相同(防不确定性混进判据)
  • 在不含 .git 的副本里跑 → 必须明确报错退出,不能崩栈
  • lint.sh --list 的 id 集合与 ci.yml 的 needs 集合相同

做这类测试时,副本必须是真正的 git 仓库(git init && git add -A && git commit)。 tar --exclude=.git 复制出来的目录里,所有基于 git 索引的检查器都会 exit 2, 于是「注入违规后失败」这条断言无论注入什么都成立 —— 恒真。

插入行不要用 sed 's/x/y\nz/':\n 在 GNU sed 里是换行、在 BSD sed 里是字面的 n,本地会静默不生效。用 { head -n 1 f; echo '...'; tail -n +2 f; } > tmp && mv tmp f, 并在注入后 grep 确认真的落进去了。

5. 提交信息校验脚本 scripts/check-commit-msg.sh

四种模式:--message <文本>、--file <路径>(给 git hook)、--range <区间>、 --last。类型白名单与 CONTRIBUTING.md 的类型表保持一致。

readonly ALLOWED_TYPES='feat|fix|docs|ci|chore|refactor|perf|test|style|revert|build'
readonly PATTERN="^(${ALLOWED_TYPES})(\([a-z0-9._/-]+\))?!?: .+"

必须保留的四个细节(每一个都是踩出来的):

  • --range 用命令替换捕获,不用进程替换。done < <(git log ...) 的退出码传不进 while,「区间无效」与「区间内没有提交」会混成同一种「读到 0 条」,无效区间被 静默放行成「全部合规(共检查 0 条)」。改成 log_out="$(git log ...)" 后, 命令替换的退出码就是 git 的退出码(实测:ref/SHA 不存在 → 128,区间有效但为空 → 0)
  • 空区间退出 0,但措辞避开「全部合规」。CI 里 BASE..HEAD 为空是合法情形 (例如只有 merge 的 PR),判失败会造假红;但 0 条检查结果什么都没验, 措辞不能说「验过了」
  • 诊断顺序:先试小写化再判类型,否则 Feat: xxx 会被误报成「缺少类型前缀」
  • while 用重定向而非管道:管道会让它落进子 shell,计数器累加传不回父进程

6. 最小权限

CI 顶层声明 permissions: contents: read;需要写权限的工作流在各自文件里单独声明。 所有 run: 块开头 set -euo pipefail,多行脚本加 #!/usr/bin/env bash。


阶段二:治理文件与模板

文件要点
LICENSE用户选型;纯许可证文本,不加附加段落(否则 GitHub 无法识别,显示 NOASSERTION)
CONTRIBUTING.md流程、提交规范、本地检查入口。类型表必须与校验脚本逐字一致
CODE_OF_CONDUCT.mdContributor Covenant 即可
SECURITY.md漏洞报告渠道 + 针对本项目的威胁模型(见下)
SUPPORT.md获取帮助的分流路径:文档 → Discussions Q&A → Bug → 安全报告
.github/CODEOWNERS兜底 * @owner + 敏感路径 + 治理文件本身
Issue 模板用 YAML forms 而非 markdown;至少分 bug / feature / docs 三类;config.yml 关闭空白 Issue 并指向 Discussions
PULL_REQUEST_TEMPLATE.md重点是「为什么」(diff 已经说明了「改了什么」);给「我如何验证」的具体示例,别让人只写「测试通过」
.gitignore语言惯例 + 编辑器目录。别依赖使用者本机的全局 gitignore —— 换机器就会暴露
.editorconfig编码、换行、缩进。*.md 要关掉 trim_trailing_whitespace(中文文档的行尾双空格是有意义的换行标记)
.gitattributes换行符策略,见下
多语言 README顶部互相链接做语言切换;次要语言注明「完整文档以主语言为准」

SECURITY.md 的价值全在「威胁模型」那一节

不要照抄。先回答一个问题:这个仓库持有/分发什么? 答案不同,威胁模型完全不同。

  • 持有凭证的自动化仓库(部署、发布、同步):核心风险是「谁能改工作流,谁就能 读走凭证」。列出手持凭证的 Secrets,说明已采取的防护(仅手动触发、分支保护、 表达式经 env: 中转、CODEOWNERS 强制 review 工作流目录)
  • 分发可执行内容的内容仓库(文档、技能、模板、插件):核心风险是「恶意或误导性 内容随一次 pull 直接进入使用者的环境」。说明内容的生效范围、内容必须可审计的要求、 以及 CI 对内容的校验强度
  • 库/SDK:核心风险是「使用者的输入被当作可信数据」。说明信任边界在哪

然后写出明确不在威胁模型内的情况 —— 这一节比列举防护更有价值,它能挡掉 大量「这算不算安全问题」的无效讨论。

.gitattributes:换行符策略,注意 vendor 区

# 自建内容:统一 LF。规则锚定到仓库根(/ 开头),避免波及 vendor 目录
/scripts/**      text eol=lf
/custom/**       text eol=lf
/docs/**         text eol=lf
/*.md            text eol=lf

# 二进制
*.png  binary

如果仓库里有 vendored 目录(上游代码、生成产物、锁定版本的内容),不要给它写任何 属性规则。 实测教训:给 vendor 目录设 -text 会关掉 core.autocrlf 的归一化。 当 index 里是 LF、工作区是 CRLF 时(autocrlf=input 的正常状态),关掉归一化会让 「改动 vendor 文件」的 diff 显示成整文件都变了——比不加 .gitattributes 还糟。

判断方法:git check-attr text eol -- <vendor 路径> 应为 unspecified。 另外别用 * text=auto eol=lf 这种全局规则,它会匹配到 vendor 路径。


阶段三:仓库自动化

  • labeler.yml:按改动路径自动给 PR 打标签(pull_request_target,因为它不 checkout PR 代码——任何 checkout PR 代码的场景禁止用 pull_request_target)
  • welcome.yml:首次贡献者致意(同样 pull_request_target 且不 checkout 代码)
  • stale.yml:N 天无响应标 stale,再 M 天自动关闭;给高频使用的标签加 exempt; operations-per-run 限流(避免一次刷屏触发滥用检测);schedule 用非整点 cron
  • release.yml:v*.*.* tag 触发。发布说明三段式组装,见下
  • dependabot.yml:每周一次,配 7 天 cooldown(新版本有 bug 或 tag 被改投恶意 代码时,冷却期让它先暴露);用 groups 把同一依赖的 minor/patch 合并成一个 PR

三段式发布说明

人工归纳 + 机器枚举 + 可选润色,三个输入源各自独立降级、任一缺失都不阻断发布:

  1. CHANGELOG 手写段(awk 以 ^## \[ 为分隔提取本版本)
  2. GitHub 原生 releases/generate-notes —— 它返回自上一个 tag 以来的 PR 列表、 贡献者、以及 Full Changelog 对比链接。自己拼这些既麻烦又容易漏
  3. 可选 AI 摘要 —— 配了 key 才启用,任何失败都 exit 0。摘要绝不能成为 发布的单点故障

组装顺序即优先级:摘要(> 引用块)→ 手写正文 → --- 分隔线 → 机器清单。 没有 AI key 时走降级路径,发布照常成功。

tag 过滤器末尾要加 *(如 v[0-9]+.[0-9]+.[0-9]+*),否则预发布 tag 根本不触发工作流,预发布逻辑成死代码。预发布版本(tag 含 -)不标 latest。

创建 Release 走「先查后建」:gh release view 成功后改走 gh release edit。 网络抖动时 git push 可能「显示失败、远端已成功」,重试会重复推 tag、触发两次 工作流,第二次 gh release create 因已存在而 422。

供应链加固(对标 OSSF Scorecard)

加固项做法
Actions pin 到 commit SHAuses: actions/checkout@<40 位 SHA> # v7——tag 可移动而 SHA 不可;注释保留版本,Dependabot 的 PR 照常更新 SHA。用 gh api repos/<owner>/<repo>/commits/<tag> --jq .sha 查真实的 SHA,不要编造
checkout 不留凭证每个 checkout 加 persist-credentials: false
工作流安全扫描CI 加 zizmor job(容器按版本 pin,挂载 :ro)。基线保持 0 findings,豁免集中在 .github/zizmor.yml,每条豁免必须写明可验证的安全依据
CLI 工具按内容固定不用 apt-get、不用 runner 预装版本(它们随镜像更新漂移,是「本地绿 CI 红」的常见来源)。下载 release 后 sha256sum -c 校验;release 不提供校验和文件时,把 sha256 写进工作流顶部固定
OSSF Scorecardossf/scorecard-action + publish_results: true(需要 id-token: write)。仅公开仓库;私有仓库必须设为 false。README 加徽章,供应链安全从「自觉做得好」变成「有公开体检报告」
最小权限每个工作流显式声明 permissions,绝不放任仓库默认(宽)权限

先跑 lint.sh 看 zizmor 实际报什么,再针对真实告警写豁免。 不要预先编造豁免 条目——预先创建的空配置或猜测性豁免,恰恰会让人以为「已经评估过了」。

注意:给 step 插入 with: 块这类结构调整,逐个手工做。批量脚本会算错缩进层级 弄坏 YAML(判断依据:修改对象是「字符」还是「结构」)。

仓库标签体系补齐:在默认标签外建项目标签,gh label create <名> --color <色> --description <说明>。


阶段四:文档体系

  • README:面向使用者。结构:这是什么 / 特性 / 快速开始 / 参数速查 / 常见场景 / 项目结构 / 文档索引 / 路线图 / 贡献 / 许可证
  • docs/ 四件套:
    • USAGE.md:从零跑起来的全部步骤 + 每个参数详解 + 常见场景
    • ARCHITECTURE.md:面向想改代码的人。写「为什么这样设计」并记录被否掉的方案 ——「我们试过 X,因为它会导致 Y,所以选了 Z」比列出目录结构有用得多
    • TROUBLESHOOTING.md:现象(保留报错原文,使用者拿它搜索)/ 原因 / 解决; 写明「什么情况下不该用这个方案」
    • MAINTAINER_GUIDE.md:维护者手册 + 仓库配置清单 + 项目红线
  • CHANGELOG.md:Keep a Changelog 格式,[Unreleased] 段 + 固定六分类 (新增/变更/弃用/移除/修复/安全),不自创分类

写完文档要核对两件事:提到的每个参数/选项/文件是否真实存在、内部相对链接是否 全部有效(写个十几行的脚本扫一遍,或直接复用 lint.sh 的链接检查)。

文档与代码同步演进:改了行为不改文档,等于没有改。


阶段五:仓库设置(gh api / gh 命令)

这些不在代码里,要用 API 落实,并且记录进 MAINTAINER_GUIDE 的「仓库配置清单」 —— 换机器或重建仓库时需要重做。

# 分支保护:要求汇总检查通过、严格同步最新、过期评审自动清除、
# 禁止 force push 与删除、必须解决所有对话
gh api repos/{owner}/{repo}/branches/main/protection -X PUT --input - <<'JSON'
{ "required_status_checks": {"strict": true, "contexts": ["CI 总览"]},
  "required_pull_request_reviews": {"dismiss_stale_reviews": true, "required_approving_review_count": 0},
  "enforce_admins": false, "restrictions": null,
  "allow_force_pushes": false, "allow_deletions": false,
  "required_conversation_resolution": true }
JSON
  • contexts 用的是检查的显示名(汇总 job 的 name:),不是 job id
  • 单人维护的仓库用 required_approving_review_count: 0——不要求别人审批,但 CI 仍是硬门禁
  • enforce_admins: false 让管理员仍可直接推送,是「软门禁」;要硬门禁就设 true
  • 分支保护必须在 CI 落地之后才启用,否则所有 PR 会因缺必需检查而卡死

其余:开启 Discussions(承接使用提问)· Projects 看板 gh project create · Roadmap Issue 作为路线图单一事实来源 · 第一个里程碑 vX.Y.Z · 补齐标签。

需要用户手动配置的(Secrets、网页端开关)列一张清单告知,不要默默跳过。


阶段六:验证与首个发布

  1. 全流程演练:开一个真实的小 PR(哪怕是文档),完整走一遍 分支 → PR → CI → review → squash merge → Issue 自动关闭。 基建只有在第一次真实使用时才算真正搭好
  2. 首个 Release:CHANGELOG 归档 v1.0.0 → 发布 PR → tag 推送 → 验证发布说明三段齐全
  3. 交接:向用户汇报搭建清单(建了什么、在哪、还差什么需要手动配置)

踩坑记录(与 maintain-loop 互补)

  • run-name 里的 #:run-name: 为 PR #${{ ... }} 中 # 前有空格会被 YAML 当注释,表达式被吞掉。含 # 的行要加引号。yamllint 能发现
  • 注释里出现 shellcheck 指令字样会被当成真指令,触发莫名的 SC1072/SC1073。改措辞
  • shellcheck 版本差异:本地新版不报的告警 CI 旧版会报。所以要么两端同版本, 要么按内容哈希 pin
  • set -u 下空数组:"${arr[@]}" 在 bash 3.2(macOS 自带)会抛 unbound variable, bash 4.4+ 才改掉。遍历前先判 ${#arr[@]}
  • pipefail + $(cmd) || return 1:命令输出了有效内容但退出码非零时,会把成功 当失败。判据应该是「有没有拿到内容」,而不是退出码
  • 判断成败禁止管道接 tail/head:if cmd | tail -1; then 判断的是 tail 的退出码。用 if out="$(cmd 2>&1)"; then,输出打印放在判断之后
  • pull_request_target + checkout PR 代码 = 任意代码以可写 token 运行,绝对禁止
  • 所有用户输入(workflow_dispatch inputs 等)经 env: 中转进脚本,${{ }} 不直接 写进 run:——表达式注入
  • gh pr create 的正文用 --body-file <临时文件>,不要用嵌套 heredoc: --body-file - <<'EOF' 放进 $(...) 里、外层又套一个循环时,- 拿到的 stdin 是空的,PR 正文静默丢失
  • gh 只认 origin:分支推在别的 remote 上时 gh pr create 报 you must first push the current branch to a remote。加 --head <owner>:<branch>
  • 每次编辑中文/非 ASCII 内容后全仓扫描 U+FFFD 替换字符。多轮迭代中反复出现 「写入时混入替换字符」,这条必须执行,不要省

完成标准

  • CI 覆盖静态检查、测试、提交规范,且有一个汇总 check
  • 汇总 check 自证完整(needs 与显示名数组是同一集合)
  • 分支保护启用,且只依赖汇总 check
  • scripts/lint.sh 可用,且有一个 lint-selftest job 守它
  • 治理文件齐全,LICENSE 能被 GitHub 识别
  • labeler / welcome / stale / release / dependabot 全部就位且跑过至少一次
  • 供应链基线达标:uses: 全部 pin 到 SHA、checkout 全部 persist-credentials: false、 zizmor 0 findings(豁免有据)
  • docs 四件套 + CHANGELOG 就位,README 的参数与内部链接经过校验
  • 看板、Roadmap Issue、第一个里程碑就位
  • 一个真实 PR 从头到尾走通过,首个 Release 已发布
  • 移交清单已告知用户(需手动配置的 Secrets、网页端开关)

之后的一切迭代,切换到 maintain-loop skill。

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall