Files
eng-standards-main/scripts/new-project.sh
T
姚章浩 cb5985ff9e feat(apply): 应用机制 + 新工程生成器,让规范默认生效
问题:规范此前只是文档,只有"有人去读"一个渠道 —— 实测 7 个仓 0 个有
AGENTS.md 指针、分支保护全空,起新工程时不会自动带上规范。

落地三件:
- scripts/new-project.sh:一条命令生成 9 个默认合规文件(提交闸门、CI、
  本地门禁、指针、提交规范 docs)。已端到端测过:空目录成功、非空拒绝、
  生成物 YAML 合法、无构建入口时门禁 exit 1(不静默通过)、默认分支 main。
- templates/ 收进 ci_gate.py / ci_report.py 的逐字节副本(cmp 校验通过),
  正本仓自此自包含,生成器不再依赖别的仓。
- 05-应用机制.md:写清 Hermes 的实际注入机制与两个必须避开的坑
  (每会话只加载一个上下文文件且有 20k 上限;不要把规则放 ~/.hermes/AGENTS.md
  —— 它只在 cwd 恰好是 ~/.hermes 时加载)。
- README / 03 加索引与交叉引用。

顺带修一个自己踩的坑:生成出来的 scripts/verify.sh 日志夹具只建不删,
正是正本 §3.2-5 自己写的陷阱($TMPDIR 会攒到几万条)。改成成功时删除、
失败时保留并打印路径。
2026-10-10 14:44:50 +08:00

184 lines
7.3 KiB
Bash
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env bash
# 起一个「默认就合规」的新工程(正本 §8 的自动化部分)。
#
# 用法: new-project.sh <目标目录> <owner/repo> [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 <目标目录> <owner/repo> [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
# verify.sh:本地门禁 —— 必须与 CI 的 build 作业同一条命令、串行、失败即停(正本 §3.1)
cat > scripts_verify.tmp <<'SH'
#!/usr/bin/env bash
# 本地门禁:一条命令跑完、串行、失败即停、末尾汇总(正本 §3.1)。
# 与 CI 的 build 作业**同一套步骤**,只允许两处刻意差异(正本 §3.1):外部环境对拍在 CI 跳过、对拍单独一步。
set -uo pipefail
LOG="$(mktemp)"; fail=0; n=0; ran=""
step() { n=$((n+1)); echo ""; echo "── [$n] $* ──"; "$@" 2>&1 | tee -a "$LOG"; return "${PIPESTATUS[0]}"; }
export PATH="/opt/citools/go/bin:/opt/citools/bin:$PATH"
if [ -f go.mod ]; then
ran="go"
step gofmt -l . || fail=1 # 格式:CI 会因为这一条红
step go vet ./... || fail=1 # 静态检查:类型错了后面全是噪声
step go build ./... || fail=1 # 构建:会清空产物目录,必须排在测试之前
step go test ./... || fail=1 # 单测跑的是构建产物,不是源码
fi
if [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then
ran="$ran python"
step ruff format --check . || fail=1
step ruff check . || fail=1
step uv run pytest -q || fail=1
fi
if [ -f package.json ]; then
ran="$ran node"
step npm run format:check || fail=1
step npm run build || fail=1
step npm test || fail=1
fi
if [ -z "$ran" ]; then echo ""; echo "⚠️ 未识别到构建入口(go.mod / pyproject.toml / package.json 都没有)—— 入口待补,不算全绿"; fail=1; fi
echo ""; echo "════════════════════════════════════════"
if [ "$fail" -eq 0 ]; then
echo "✅ 本地门禁全过"
rm -f "$LOG" # 夹具要打扫(正本 §3.2-5):成功时不留日志,否则 $TMPDIR 会攒到几万条
else
echo "❌ 门禁未通过 —— 先修它,再提交"
echo "(完整日志留在:$LOG)"
fi
exit "$fail"
SH
mkdir -p scripts && mv scripts_verify.tmp scripts/verify.sh && chmod +x scripts/verify.sh
cat > Makefile <<'MK'
# 本地门禁入口:一条命令跑完(正本 §3.1)。CI 的 build 作业跑同一套步骤。
.PHONY: check
check:
bash scripts/verify.sh
MK
say "3/7 CI 工作流"
mkdir -p .gitea/workflows .gitea/scripts docs
sed "s|<PROJECT>|$NAME|g" "$TPL/gitea-build.yml" > .gitea/workflows/build.yml
sed "s|<PROJECT>|$NAME|g" "$TPL/gitea-prod-deploy.yml" > .gitea/workflows/deploy-production.yml
say "4/7 闸门与上报脚本(从正本仓逐字节复制)"
cp "$TPL/ci_gate.py" .gitea/scripts/ci_gate.py
cp "$TPL/ci_report.py" .gitea/scripts/ci_report.py
chmod +x .gitea/scripts/*.py
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("<PROJECT>", name).replace("<ns>/<repo>", repo)
sys.stdout.write(body)
PY
echo " AGENTS.md($(wc -c < AGENTS.md) 字节)"
say "6/7 docs/提交规范.md"
cat > docs/提交规范.md <<MD
# 提交规范
正本:Git / 提交 / CI-CD 规范(Gitea 版)—— 仓库 \`zheromiku/eng-standards-main\`,本机工作副本 \`~/eng-standards/\`。
## 格式
\`\`\`
<type>(<scope>): 一句话说清"改了什么"
正文:为什么这么改 / 现象 / 根因 / 怎么验的。
\`\`\`
- \`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 <<EOF
== 下一步 ==
1) cd "$DIR" && git add -A
git commit -F - <<'MSG'
chore(init): 初始化工程骨架(CI + 门禁 + 提交规范)
由 ~/eng-standards/scripts/new-project.sh 生成:提交信息闸门、编译自检、
静态产物预览与微信上报(ci-bridge)。正本见 zheromiku/eng-standards-main。
MSG
2) 建远端并在网页建仓:$REPO(**不要**勾"初始化仓库")
git remote add origin https://gitea.zheromiku.top/$REPO.git && git push -u origin main
3) 挂仓库级 Runner + bridge 变量(幂等):
bash /srv/aiball/runner/attach_repo.sh $REPO $RUNNER
4) main 分支保护(网页:Settings → Branches):禁止直接推送 + 必须 PR + 必须 CI 通过
5) **反向自检**(正本 §3.2-3):推一个故意违规的提交,确认 gate 红、且 build 没跑
6) TODO:填 .gitea/workflows/build.yml 里 deploy:test 的 <TEST_HOST> 与读回断言
EOF