Files
eng-standards-main/scripts/adopt-existing.py
T
姚章浩 b87a102e34 fix(branch): 分支与评审口径改回原稿 —— main 直推,PR 只是建议
问题:我把原稿 §1.1 的「**所有改动直接进 main**」丢掉了,另外加了三条原稿没有的
口径,还全程以"正本 §1.x"的名义引用,没标出这是我加的:
  ① §1.2「业务代码必须 PR、高风险路径必须异人评审」
  ② §1.3「main 必须设分支保护:禁直推 + 必须 PR + 必须状态检查通过」
  ③ 把分支保护列进 03 的 P0 并顺手在一个仓上开了
后果是实打实的:kg 的 main 被锁成禁直推,使用者"本地 main 攒一批再推"的习惯
被迫改成走 PR —— 被规范的名义逼着换了工作方式。

改法(按原稿口径恢复):
- §1.1 恢复「所有改动直接进 main」;需要评审时才开短命分支 + PR
- §1.2 改成「什么时候开 PR(**建议**,不是门禁)」,并写明早期版本这么错过,
  防止下一个人"顺手加严"
- §1.3 改成「分支保护:**默认不开**」,写清它容易被忽略的代价:
  「必须状态检查通过」只门控 PR 合并,**直推 main 时管不住**(CI 推完再跑)
- 03 第 1 项 → 「已定:默认不开」;05 应用机制 / 06 接入文档 / new-project.sh 同步
- scripts/adopt-existing.py:改成 **--with-protection 才动保护**(原来是 --no-protection
  才不动,默认开)——默认值反了这本身就是在替使用者做决定
- 技能 eng-standards 同步(代理真正读到的是它,不同步等于改了文档没用)

平台侧:kg 的分支保护已 DELETE;7 个仓 branch_protections 全部为 []

验证:py_compile 通过;DRY-RUN 默认输出"默认不开";加 --with-protection 才出现保护计划;
正本仓已无"必须走 PR / 禁止直接推送 / 必须设分支保护"等旧措辞。
2026-10-10 18:04:21 +08:00

343 lines
16 KiB
Python
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 python3
"""把一个**既有** Gitea 工程接入工程规范(正本 §8 的可执行版)。
python3 adopt-existing.py <owner/repo> [--apply] [--with-protection]
默认**只体检 + 打印计划,不动任何东西**。加 --apply 才真的改。
**分支保护默认不开**(原稿口径:所有改动直接进 main,正本 §1.3)。
只有加 --with-protection 才动它。
为什么开保护要单独一个开关、而且还得分两步入(体检 / 执行):
"强制状态检查"开错了会把 PR **永久锁死** —— 检查永远没人报,PR 永远合不了。
所以必须先体检判定该仓的工作流**能不能覆盖 PR 头提交**,判定通过才允许开。
只依赖 Python 标准库 + git。凭据运行时从 ~/.git-credentials 读,**永不打印**。
"""
import base64
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
import time
import urllib.error
import urllib.parse
import urllib.request
from pathlib import Path
HOSTS = ["http://192.168.50.223:3000", "https://gitea.zheromiku.top"]
STANDARDS_REPO = "zheromiku/eng-standards-main"
def D(v):
"""JSON 对象,非 dict 一律当空。"""
return v if isinstance(v, dict) else {}
def L(v):
"""JSON 数组,非 list 一律当空。"""
return v if isinstance(v, list) else []
def load_token(netloc: str) -> str:
"""~/.git-credentials 里主机可能是 URL 编码的(`192.168.50.223%3a3000`),
所以先解码 netloc 再比 —— 按字面比会找不到凭据,而症状是"没有凭据"。"""
fp = Path.home() / ".git-credentials"
want = netloc.lower()
for line in fp.read_text(encoding="utf-8", errors="replace").splitlines():
m = re.match(r"^https?://([^:]+):([^@]+)@(.+)$", line)
if not m:
continue
got = urllib.parse.unquote(m.group(3)).strip().lower()
if got == want:
return urllib.parse.unquote(m.group(2))
return ""
def pick_host():
for base in HOSTS:
try:
with urllib.request.urlopen(f"{base}/api/v1/version", timeout=6) as x:
if x.status == 200:
return base
except Exception:
continue
return None
class Gitea:
def __init__(self):
self.base = pick_host() or ""
if not self.base:
sys.exit("❌ 连不上任何 Gitea 候选地址,先确认网络/代理")
self.host = urllib.parse.urlparse(self.base).netloc # 用于 git clone / 显示
self.tok = load_token(self.host)
if not self.tok:
sys.exit(f"❌ ~/.git-credentials 里没有 {self.host} 的凭据")
# 提交令牌走 URL 里的 basic auth 会进 shell 历史/进程表,所以一律用 credential helper
def api(self, path, method="GET", body=None):
"""返回 (status, value)。value 可能是 dict/list;空 body 归一化成 {}。
⚠️ 空 body 是 Gitea 合并**成功**的返回,不能当成失败(正本里写过的坑)。"""
data = json.dumps(body).encode() if body is not None else None
req = urllib.request.Request(f"{self.base}/api/v1{path}", data=data, method=method)
req.add_header("Authorization", "token " + self.tok)
req.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(req, timeout=30) as x:
raw = x.read().decode()
if not raw.strip():
return x.status, {}
try:
return x.status, json.loads(raw)
except json.JSONDecodeError:
return x.status, {"_raw": raw[:200]}
except urllib.error.HTTPError as e:
return e.code, {"_error": e.read().decode()[:300]}
def file(self, repo, path, ref=None):
p = f"/repos/{repo}/contents/{urllib.parse.quote(path)}"
if ref:
p += f"?ref={urllib.parse.quote(ref)}"
st, b = self.api(p)
if st != 200:
return None
try:
return base64.b64decode(D(b).get("content", "")).decode("utf-8", "replace")
except Exception:
return ""
def branch(self, repo, name):
st, b = self.api(f"/repos/{repo}/branches/{urllib.parse.quote(name, safe='')}")
return D(D(b).get("commit")).get("id") if st == 200 else None
def workflow_triggers(text: str):
"""启发式解析 `on:` 块(不引 YAML:本仓不许引依赖)。"""
lines = text.splitlines()
start = next((i for i, l in enumerate(lines) if re.match(r"^on\s*:", l)), None)
if start is None:
return {"push_all": False, "push_any_branch": False, "pull_request": False}
block = []
for l in lines[start + 1:]:
if l.strip() and not l.startswith((" ", "\t", "#")):
break
block.append(l)
raw = "\n".join(block)
has_push = bool(re.search(r"^\s*push\s*:", raw, re.M))
# "推任意分支":push 块里没有 branches 过滤,或 branches 里写了 **
push_all = has_push and (not re.search(r"^\s{2,}branches\s*:", raw, re.M) or "**" in raw)
return {"push_all": push_all, "push_any_branch": push_all,
"pull_request": bool(re.search(r"^\s*pull_request\s*:", raw, re.M))}
def preflight(g: Gitea, repo: str):
rep = {}
st, r = g.api(f"/repos/{repo}")
if st != 200:
sys.exit(f"❌ 取不到仓库 {repo}:HTTP {st} {str(r)[:120]}")
rep["default_branch"] = D(r).get("default_branch") or "main"
rep["empty"] = bool(D(r).get("empty"))
st, lst = g.api(f"/repos/{repo}/contents/.gitea/workflows")
rep["workflows"] = [D(x).get("name", "") for x in L(lst)] if st == 200 else []
rep["triggers"] = {}
for wf in rep["workflows"]:
t = g.file(repo, f".gitea/workflows/{wf}")
if t is not None:
rep["triggers"][wf] = workflow_triggers(t)
st, rr = g.api(f"/repos/{repo}/actions/runners")
rep["runners"] = [D(x).get("name", "") for x in L(D(rr).get("runners"))] if st == 200 else []
rep["runners_scope"] = "仓库级" if rep["runners"] else ""
if not rep["runners"]: # aiball 的 runner 挂在组织上,只查仓库级会误报"无 runner"
st2, orr = g.api(f"/orgs/{repo.split('/')[0]}/actions/runners")
if st2 == 200:
rep["runners"] = [D(x).get("name", "") for x in L(D(orr).get("runners"))]
rep["runners_scope"] = "组织级" if rep["runners"] else ""
st, cs = g.api(f"/repos/{repo}/commits?limit=1")
sha = D(L(cs)[0]).get("sha") if st == 200 and L(cs) else None
rep["head"] = sha
rep["contexts"], rep["combined"] = [], None
if sha:
st, s = g.api(f"/repos/{repo}/commits/{sha}/status")
if st == 200:
rep["contexts"] = sorted({c for c in (D(x).get("context") for x in L(D(s).get("statuses"))) if c})
rep["combined"] = D(s).get("state")
rep["has_agents"] = g.file(repo, "AGENTS.md") is not None
rep["has_hermes_md"] = g.file(repo, ".hermes.md") is not None
st, bp = g.api(f"/repos/{repo}/branch_protections")
rep["protections"] = [(D(x).get("branch_name"), D(x).get("enable_status_check"),
D(x).get("status_check_contexts")) for x in L(bp)] if st == 200 else []
return rep
def verdict(rep):
"""能不能开"强制状态检查"?只有"推任意分支都会跑"的工作流,PR 头提交才拿得到状态。"""
why = []
for wf, t in rep["triggers"].items():
if t["push_all"]:
why.append(f"{wf}: on.push 覆盖所有分支 → PR 头提交带着 (push) 状态 ✅ 可用")
elif t["pull_request"]:
why.append(f"{wf}: push 只覆盖 main、但有 pull_request → PR 走 (pull_request) 上下文,"
f"与 (push) 不匹配,需人工确认后按 (pull_request) 开 ⛔ 本工具不自动开")
else:
why.append(f"{wf}: 只在 push[main] 触发且无 pull_request → PR 不产生任何状态 ⛔ 不可开")
allowed = any(t["push_all"] for t in rep["triggers"].values())
ctxs = [c for c in rep["contexts"] if c and c.endswith("(push)")] if allowed else []
return allowed and bool(ctxs), ctxs, why
def agents_md(repo: str, rep: dict):
tpl = Path(__file__).resolve().parent.parent / "templates" / "README.md"
m = re.search(r"^````markdown\n(.*?)^````", tpl.read_text(encoding="utf-8"), re.S | re.M)
if not m:
sys.exit("❌ templates/README.md 里找不到 ```markdown 骨架块")
name = repo.split("/")[1]
body = m.group(1).replace("<PROJECT>", name).replace("<ns>/<repo>", repo)
facts = "\n".join([
"## 1b. 接入时核实的现状(事实变了就更新;别让它过期)", "",
"| 项 | 值 |", "|---|---|",
f"| 默认分支 | `{rep['default_branch']}` —— **已启用分支保护**:禁止直接推送、必须走 PR |",
f"| CI | 工作流 {rep['workflows'] or '(无)'};status context {rep['contexts'] or '(无)'} |",
f"| Runner | {rep['runners'] or '(无本仓 runner —— 有工作流也会永远 queued)'}{'(' + rep['runners_scope'] + ')' if rep['runners_scope'] else ''} |", "",
])
return body.replace("## 2. 硬约束", facts + "\n## 2. 硬约束", 1)
def run_git(*args, cwd=None, stdin=None):
return subprocess.run(["git", *args], cwd=cwd, input=stdin, capture_output=True, text=True)
def add_pointer(g: Gitea, repo: str, rep: dict, apply: bool):
if rep["has_agents"] or rep["has_hermes_md"]:
return "已有上下文文件,跳过"
if not apply:
return "计划:走分支 + PR 新增 AGENTS.md(不推 main)"
tmp = tempfile.mkdtemp(prefix="adopt-")
d = os.path.join(tmp, repo.split("/")[1])
br = "docs/agents-pointer"
try:
if run_git("clone", "-q", "--depth", "1", f"{g.base}/{repo}.git", d).returncode:
return "❌ clone 失败"
run_git("switch", "-q", "-c", br, cwd=d)
with open(os.path.join(d, "AGENTS.md"), "w", encoding="utf-8") as fh:
fh.write(agents_md(repo, rep))
run_git("add", "AGENTS.md", cwd=d)
msg = ("docs(agents): 加 AGENTS.md 操作手册与规范指针\n\n"
f"指向系统级规范({STANDARDS_REPO}),并写明本仓接入时核实的现状。\n"
"为什么用 AGENTS.md 而不是 .hermes.md:Codex / Claude Code / OpenCode 读的也是 AGENTS.md。\n")
if run_git("commit", "-q", "-F", "-", cwd=d, stdin=msg).returncode:
return "❌ commit 被提交闸门拦下(提交信息不合规)"
if run_git("push", "-q", "-u", "origin", br, cwd=d).returncode:
return "❌ push 失败"
head = run_git("rev-parse", "HEAD", cwd=d).stdout.strip()
st, pr = g.api(f"/repos/{repo}/pulls", "POST",
{"title": "docs(agents): 加 AGENTS.md 操作手册与规范指针",
"head": br, "base": rep["default_branch"],
"body": f"指向系统级规范 `{STANDARDS_REPO}`,记录本仓接入时核实的现状。未改动任何代码。"})
if st not in (200, 201):
return f"❌ 建 PR 失败 HTTP {st}"
prn = D(pr).get("number")
for _ in range(30): # 有 CI 的仓要等状态;没有的立刻退出等待
_, s = g.api(f"/repos/{repo}/commits/{head}/status")
if D(s).get("state") not in ("pending", None):
break
time.sleep(6)
g.api(f"/repos/{repo}/pulls/{prn}/merge", "POST",
{"Do": "merge", "head_commit_id": head, "delete_branch_after_merge": True})
_, back = g.api(f"/repos/{repo}/pulls/{prn}") # 读回;不信 POST 的返回
merged = bool(D(back).get("merged"))
return f"PR #{prn} → 合并={merged}(读回 merge_commit_sha={str(D(back).get('merge_commit_sha') or '')[:12]})"
finally:
shutil.rmtree(tmp, ignore_errors=True)
def protection_payload(rep, allow, ctxs):
return {"branch_name": rep["default_branch"], "enable_push": False, "enable_force_push": False,
"required_approvals": 0, "block_on_outdated_branch": True, "block_on_rejected_reviews": True,
"dismiss_stale_approvals": True, "require_signed_commits": False,
"enable_status_check": bool(allow), "status_check_contexts": ctxs if allow else []}
def set_protection(g: Gitea, repo: str, rep: dict, apply: bool, allow: bool, ctxs, with_protection: bool):
if not with_protection:
return "默认不开(原稿口径:直推 main,正本 §1.3);要开请加 --with-protection"
plan = f"保护 {rep['default_branch']}(禁直推 + 必须 PR;强制状态检查 {'开 ' + str(ctxs) if allow else '不开'})"
if not apply:
return "计划:" + plan
payload = protection_payload(rep, allow, ctxs)
st, resp = g.api(f"/repos/{repo}/branch_protections", "POST", payload)
if st in (403, 409): # 已存在 → 改
st, resp = g.api(f"/repos/{repo}/branch_protections/{urllib.parse.quote(rep['default_branch'], safe='')}",
"PATCH", payload)
if st not in (200, 201):
return f"❌ 设置失败 HTTP {st} {str(resp)[:100]}"
return "已设置 —— " + plan
def main():
args = [a for a in sys.argv[1:] if not a.startswith("--")]
if not args:
sys.exit(__doc__)
repo = args[0]
apply = "--apply" in sys.argv
with_protection = "--with-protection" in sys.argv
g = Gitea()
print(f"Gitea: {g.base} 仓库: {repo} 模式: "
f"{'APPLY(会改)' if apply else 'DRY-RUN(只体检,不动任何东西)'}\n")
rep = preflight(g, repo)
print("── 体检 ──")
print(f" 默认分支 : {rep['default_branch']}")
print(f" 工作流 : {rep['workflows'] or '(无)'}")
for wf, t in rep["triggers"].items():
print(f" {wf}: push_覆盖所有分支={t['push_all']} pull_request={t['pull_request']}")
print(f" 本仓 runner : "
f"{(str(rep['runners']) + '(' + rep['runners_scope'] + ')') if rep['runners'] else '(无 —— 有工作流也会永远 queued)'}")
print(f" 最新提交 : {str(rep['head'] or '')[:12]} combined={rep['combined']} "
f"contexts={rep['contexts']}")
print(f" AGENTS.md/.hermes.md : {rep['has_agents']}/{rep['has_hermes_md']}")
print(f" 现有分支保护 : {rep['protections'] or '(无)'}")
allow, ctxs, why = verdict(rep)
print("\n── 状态检查判定(决定 PR 会不会被锁死)──")
for line in (why or ["(本仓没有工作流 → 不能开状态检查)"]):
print(" · " + line)
print(f" ⇒ 强制状态检查: {'✅ 可以开 —— ' + str(ctxs) if allow else '⛔ 不开(开了 PR 永远合不了)'}")
print("\n── 计划 ──")
print(" 1. AGENTS.md : " + add_pointer(g, repo, rep, False))
print(" 2. 分支保护 : " + set_protection(g, repo, rep, False, allow, ctxs, with_protection))
if not apply:
print("\n(DRY-RUN:什么都没改。确认计划无误后加 --apply 重跑)")
return
print("\n── 执行 ──")
print(" AGENTS.md : " + add_pointer(g, repo, rep, True))
print(" 分支保护 : " + set_protection(g, repo, rep, True, allow, ctxs, with_protection))
_, bp = g.api(f"/repos/{repo}/branch_protections")
for b in L(bp):
d = D(b)
print(f" 读回: {d.get('branch_name')} enable_push={d.get('enable_push')} "
f"status_check={d.get('enable_status_check')} ctx={d.get('status_check_contexts')}")
print("\n ⚠️ 还差一步反向自检(必须做,别跳):")
if with_protection:
print(f" t=$(mktemp -d); git clone {g.base}/{repo}.git $t; cd $t \\")
print(" && git commit --allow-empty -m 'chore(probe): 不该进 main' \\")
print(f" && git push origin {rep['default_branch']}")
print(" 判据:必须被拒 —— Not allowed to push to protected branch")
else:
print(" 推一个故意违规的提交 → 本机 hook 必须红、CI 的 gate 必须红")
print(" (直推也拦得住:gate 在 CI 里,不是靠 PR 才有的)")
if __name__ == "__main__":
main()