#!/usr/bin/env bash # 起一个「默认就合规」的新工程(正本 §8 的自动化部分)。 # # 用法: new-project.sh <目标目录> [runner-name] # 例: new-project.sh ~/proj/my-svc Weknora/my-svc runner-weknora-my-01 # # 刻意**不覆盖**任何已有文件:目标目录非空就直接拒绝(半途改主意不会留下半成品)。 # 依赖:正本仓本身(templates/ 与已验证的闸门脚本都在里面)—— 不在正本仓里跑会拒。 set -euo pipefail STANDARDS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" TPL="$STANDARDS_DIR/templates" TARGET="${1:?用法: new-project.sh <目标目录> [runner-name]}" REPO="${2:?缺少 owner/repo,例: Weknora/my-svc}" RUNNER="${3:-${REPO##*/}-runner-01}" [ -d "$TPL" ] || { echo "❌ 找不到 templates/($TPL)—— 本脚本必须在正本仓里运行" >&2; exit 1; } case "$REPO" in */*) ;; *) echo "❌ owner/repo 格式不对: $REPO" >&2; exit 1 ;; esac NAME="${REPO##*/}" DIR="$(cd "$(dirname "$TARGET")" 2>/dev/null && pwd)/$(basename "$TARGET")" if [ -e "$DIR" ] && [ -n "$(ls -A "$DIR" 2>/dev/null)" ]; then echo "❌ 目标目录非空:$DIR(不覆盖任何东西)" >&2; exit 1 fi say() { printf '\n== %s ==\n' "$*"; } say "1/7 目录" mkdir -p "$DIR" cd "$DIR" echo " $DIR" say "2/7 .gitignore / 门禁入口" cp "$TPL/gitignore" .gitignore # 门禁入口:**只有一份实现**(scripts/ci_checks.py),verify.sh 只是转发。 # 为什么不再生成一套 bash 探测逻辑:那会和模板/CI 形成第二套步骤,迟早只改一边。 cat > scripts_verify.tmp <<'SH' #!/usr/bin/env bash # 本地门禁入口:转发给 scripts/ci_checks.py —— **不要**在这里再写一套检查。 # 为什么:CI 调用的是同一条命令(make verify),两边只有一份实现才不会漂移。 set -uo pipefail exec python3 "$(dirname "$0")/ci_checks.py" "$@" SH mkdir -p scripts && mv scripts_verify.tmp scripts/verify.sh && chmod +x scripts/verify.sh cat > Makefile <<'MK' # 本地门禁入口:一条命令跑完(正本 §3.1)。CI 跑的是**同一条命令**。 # 实现只有一份:scripts/ci_checks.py(由 templates/ci-gate.py 生成)。 .PHONY: verify check list verify: python3 scripts/ci_checks.py check: verify list: python3 scripts/ci_checks.py --list MK say "3/7 CI 工作流(只做 CI;**默认不生成 CD 工作流**)" mkdir -p .gitea/workflows .gitea/scripts docs sed "s||$NAME|g" "$TPL/gitea-build.yml" > .gitea/workflows/build.yml echo " build.yml(只此一个:CI 不含部署)" echo " 要 CD 时**显式**拷 templates/gitea-prod-deploy.yml 过去 —— 它的未实现步骤故意是红的" say "4/7 门禁实现、上报、预览、检出脚本" cp "$TPL/ci-gate.py" scripts/ci_checks.py # 权威门禁:唯一一份检查实现 cp "$TPL/check-secrets.py" scripts/check_secrets.py # 密钥扫描(门禁的 security 项会调它) cp "$TPL/ci_gate.py" .gitea/scripts/ci_gate.py # 提交信息闸门(按准确 Git 范围校验) cp "$TPL/ci_report.py" .gitea/scripts/ci_report.py # 核对报告 + 上报(--verify-only 可单独核对) cp "$TPL/ci_preview.py" .gitea/scripts/ci_preview.py # **先核对完整报告,再发预览** cp "$TPL/ci_checkout.sh" .gitea/scripts/ci_checkout.sh # 检出:固定事件 SHA、协议不降级、URL 不放凭据 chmod +x scripts/ci_checks.py scripts/check_secrets.py .gitea/scripts/*.py .gitea/scripts/*.sh # 测试范围声明:门禁的 tests 项要读它("允许跳过哪些用例""前端用什么跑测试")。 # 给一份**合法但空**的骨架 —— 空声明不等于"随便跳",必需用例被跳过照样红。 cat > scripts/test-scope.json <<'JS' { "_doc": [ "测试范围与前端测试框架的声明(门禁的 tests 项读它)。strict schema:", "· optional 条目必须给 package 或 test(至少一个)—— 两个都不给会通配任意跳过,不允许;", "· 每条必须有 reason 与 owner;package 级条目还要给 expected_skips(跳过数不许无声明地涨);", "· review_by 是到期日(YYYY-MM-DD),过期 ⇒ 整份声明失效。", "frontend_runner:前端用什么跑测试(vitest / jest)。不写就按 package.json 依赖认;认不出来 ⇒ 明确失败。" ], "frontend_runner": "vitest", "optional": [] } JS echo " scripts/test-scope.json(空声明骨架:允许跳过哪些用例要在这里写明)" # 合并策略文件:**必须由你填**,不填就等于没有"要求哪些检查" ⇒ 合并会被拒绝。 # 这里不预填一个猜出来的 context —— 猜错了会把没跑过必需检查的 PR 放过去。 cat > .gitea/required-contexts.txt <<'CTX' # 合并前必须在 PR 头提交上 success 的 status context(一行一个,`#` 后是注释)。 # # ⚠️ 这份文件是"要求哪些检查"的**唯一来源**:合并脚本只认它或显式 --require-context, # 不接受"观察到的状态"。文件为空 / 只有注释 ⇒ 视为没有策略 ⇒ 拒绝合并。 # # 怎么填:workflow 跑过一次之后,看那次提交的 status context(Gitea 界面或 # GET /api/v1/repos///commits//status ),把它逐行抄下来。 # 例如:build / build (push) CTX echo " ⚠️ .gitea/required-contexts.txt 还是空的:填上真实 context 之前,--merge-pr 会拒绝合并" say "5/7 AGENTS.md(从 templates/README.md 的骨架抽取并替换)" python3 - "$TPL/README.md" "$NAME" "$REPO" > AGENTS.md <<'PY' import re, sys src, name, repo = sys.argv[1:4] t = open(src, encoding="utf-8").read() m = re.search(r"^````markdown\n(.*?)^````", t, re.S | re.M) if not m: sys.exit("❌ templates/README.md 里找不到 ```markdown 骨架块") body = m.group(1) body = body.replace("", name).replace("/", repo) sys.stdout.write(body) PY echo " AGENTS.md($(wc -c < AGENTS.md) 字节)" say "6/7 docs/提交规范.md" cat > docs/提交规范.md <(): 一句话说清"改了什么" 正文:为什么这么改 / 现象 / 根因 / 怎么验的。 \`\`\` - \`type\`:feat fix docs style refactor perf test build ci chore revert - \`scope\`:本仓库的真实模块名,可选,小写 - 冒号后一个空格;描述 ≥3 字符;标题 **≤72 字符、结尾不加句号** - 放行自动生成的提交:\`Merge \` / \`Revert "\` / \`fixup! \` / \`squash! \` / \`amend! \` - **一件事一个提交**,且每个提交都要能各自编译/构建通过 ## 正文写"为什么",不写"是什么" diff 已经写了"是什么"。正文回答:当时为什么这么改、试过什么、怎么确认它对了。 四种要素:**现象** / **根因**(具体到文件·行·机制)/ **取舍**(为什么不用那个更自然的写法)/ **证据**(跑了什么、量到了什么)。 ## 两条闸门 1. 本机 hook \`~/.githooks/commit-msg\`(\`core.hooksPath\` 全局生效)—— 快速反馈 2. CI \`.gitea/scripts/ci_gate.py\` —— 权威闸门,在**编译之前**执行 ⚠️ \`--no-verify\` 只骗得过第一条。 ## 写法禁忌 不要在提交信息里用反引号与 \`\$()\`:shell 会先做命令替换,轻则信息被改写,重则**执行**了里面的东西, 而退出码仍是 0、没有任何报错。一律用带引号的 heredoc: \`\`\`bash git commit -F - <<'EOF' fix(parser): 修复表格解析越界导致的 500 根因:…… EOF \`\`\` MD say "7/7 git 仓库" git init -q -b main echo " 已初始化(默认分支 main),未提交" cat <