Files
eng-standards-main/scripts/adopt-existing.py
T
姚章浩 89d029108a fix(adopt): 锚点写错导致现状表静默插不进去;顺带修健壮性与验证方式
上一提交(d80b30e)正文里那句"验证:对两种 rep 各生成一次…分别正确"**不成立** ——
验证脚本当场 IndexError。同一会话里我第二次把提交信息写在验证之前(bcdeb7f 也犯了),
如实纠正:这一段的每一条都是先跑出来、再写进来的。

根因:`agents_md` 用 `body.replace("## 2. 硬约束", …)` 插入"接入时核实的现状"表,
而骨架里的实际标题是 `## 1. 硬约束`。`str.replace` 找不到时**静默返回原文** ——
不抛错、不警告,于是那张表**从来没有被插进去过**,而工具一路"成功"。
这正是正本 §3.2-3 那条:断言校验器真的作用在目标上。

改法:
- 锚点改成真实的 `## 1. 硬约束`;小节改名 `## 0b.`(插在 §0 与 §1 之间,不动骨架编号)
- 插入前**显式断言锚点存在**,不存在就带说明退出,不再静默
- CI / Runner 行改用 `rep.get()`:缺 key 抛的 KeyError 会**掩盖**真正要报的错
  (实测:夹具少一个 key,"锚点坏了"的自检报的却是 KeyError,等于没验)

验证(输出即证据):
- 没开保护 → `| 默认分支 | main —— **直推**(默认不开分支保护,正本 §1.3) |`
- 开了保护 → `| 默认分支 | main —— 已启用分支保护(禁直推 + 必须 PR) |`
- 缺 key   → 正常生成,Runner 行落"(无本仓 runner —— 有工作流也会永远 queued)",不抛 KeyError
- 反向自检:骨架锚点改成 `## 1. 约束(锚点被改坏)` → 报错退出:
  `❌ AGENTS 骨架里找不到锚点 '## 1. 硬约束';现状表会**静默**插不进去,先修锚点再跑`
2026-10-10 18:07:32 +08:00

362 lines
17 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)
# 如实写:默认**不开**分支保护(正本 §1.3)。别把模板里的假设写进别人的仓库 ——
# 一行"已启用分支保护"在没开保护时就是假的,而下一个人会信它。
branch_line = (f"| 默认分支 | `{rep['default_branch']}` —— 已启用分支保护(禁直推 + 必须 PR) |"
if rep.get("protections")
else f"| 默认分支 | `{rep['default_branch']}` —— **直推**(默认不开分支保护,正本 §1.3) |")
# 用 .get() 而不是下标:缺 key 时抛 KeyError 会**掩盖**下面那条真正要报的错
# (实测:夹具少一个 key,于是"锚点坏了"的自检报的是 KeyError,等于没验)。
_wf = "、".join(rep.get("workflows") or []) or "(无)"
_ctx = "、".join(rep.get("contexts") or []) or "(无)"
_rn = "、".join(rep.get("runners") or []) or "(无本仓 runner —— 有工作流也会永远 queued)"
if rep.get("runners_scope"):
_rn += f"({rep['runners_scope']})"
facts = "\n".join([
"## 0b. 接入时核实的现状(事实变了就更新;别让它过期)", "",
"| 项 | 值 |", "|---|---|",
branch_line,
f"| CI | 工作流 {_wf};status context {_ctx} |",
f"| Runner | {_rn} |", "",
])
# ⚠️ 锚点必须真的存在。`str.replace` 找不到时**静默返回原文**,不会报错 ——
# 实测踩过:锚点写成 `## 2. 硬约束`(骨架里其实是 `## 1. 硬约束`),
# 于是这张现状表从来没被插进去,而工具一切正常地"成功"了。
# 所以这里显式断言锚点存在(正本 §3.2-3:断言校验器真的作用在目标上)。
anchor = "## 1. 硬约束"
if anchor not in body:
sys.exit(f"❌ AGENTS 骨架里找不到锚点 {anchor!r};现状表会**静默**插不进去,先修锚点再跑")
return body.replace(anchor, facts + "\n" + anchor, 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()