89d029108a
上一提交(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. 硬约束';现状表会**静默**插不进去,先修锚点再跑`
362 lines
17 KiB
Python
Executable File
362 lines
17 KiB
Python
Executable File
#!/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() |