gitlink-cli/竞赛提交文档以及演示视频相关图片/子赛题三——工作流说明文档.md

子赛题三 · 端到端自动化工作流说明（详版）

交付要求：工作流串联 ≥3 个 CLI 命令或 Skill · 可复现执行脚本 · 真实 GitLink 项目运行 · 说明文档 + 架构图 · Agent 兼容。 架构图见 工作流架构图.png / 工作流架构图.drawio（drawio 可自行调整）。

本项目交付 三个端到端自动化工作流，全部满足「≥3 步串联」，分别覆盖代码质量门禁 / 策略化裁决 / 社区运营三类场景，底层 Skill 可相互复用。

一、三个工作流总览

工作流	场景	串联步骤	涉及命令域/Skill	可复现脚本	Agent 形态
A · pr-guard	代码质量看门人（采集→审查→CI→评论→判定/合并）	5 步	pr / code-review / ci / api	demo/pr-guard-workflow.sh	Claude Code 读 SKILL.md
B · pr-quality-gatekeeper	Policy-as-Code 评分卡（多路信号→0-100 分→三态裁决）	9 步	pr / ci / api / label + code-review	examples/pr-quality-gatekeeper	Claude Code 读 SKILL.md
C · community-ops-sweep	社区运营增量对账（5 项事件一次处理）	5 项事件	issue / pr / wiki / release + Raw API	workflows/community-ops-sweep/（含 18 单测）	原生 Claude Code Workflow（.wf.js）

---

二、工作流 A · pr-guard 代码质量看门人

A.1 背景与目标

PR 合并前要做的事——审查代码、查 CI、给反馈、决定合不合——本可自动化，却常靠人工东拼西凑。pr-guard 把它做成一条端到端流水线：PR 一进来，自动采集、审查、查 CI、发评审、给出可解释的「通过/拒绝」判定。区别于 code-review Skill 只产出主观评论，pr-guard 是会下结论、可执行合并的完整闭环。

A.2 适用场景

• 团队想给 PR 加一道最低质量门槛（0 Critical + CI 通过才放行）。
• 希望 AI 把分散的 pr/ci/api 命令自动串起来，而非人工逐条跑。

A.3 架构（5 步流水线，串联 4 个命令域）

PR 提交
  │
  ▼
①采集        pr +diff / +files         （pr 域）
  │
  ▼
②AI Review   code-review Skill          （分级 Critical/Warning/Suggestion）
  │
  ▼
③CI 检查     ci +builds                 （ci 域）
  │
  ▼
④汇总评论    api POST /reviews          （api 域）
  │
  ▼
⑤质量判定/合并  pr +merge（仅满足门禁时） （pr 域）

A.4 详细步骤

步	动作	命令 / Skill	输入	输出
①	采集 PR 变更	pr +diff -i <PR> / pr +files -i <PR>	PR 编号	文件清单 + diff 内容
②	AI 审查分级	code-review Skill	diff	Critical/Warning/Suggestion 发现列表
③	查 CI 状态	ci +builds	仓库	构建结果（通过/失败/未知）
④	汇总评审评论	api POST /:o/:r/pulls/<id>/reviews	发现 + CI	结构化 Review 评论
⑤	质量判定	门禁规则 + pr +merge -i <PR> --method squash	Critical 数 + CI	通过→合并 / 拒绝→附问题清单

A.5 门禁规则（硬性、可解释）

0 Critical + CI success  →  ✅ 建议合并（pr +merge）
否则                       →  🔴 拒绝，附 Critical/Warning 问题清单

A.6 触发方式

脚本（可复现）：demo/pr-guard-workflow.sh <owner> <repo> <pr_id>——把 5 步采集命令串起来自动跑，AI 审查/判定在 Claude Code 里做。 Agent 提示词（Claude Code 直接粘）：

读 skills/gitlink-pr-guard/SKILL.md，把关 <owner>/<repo> 的 PR #： 采集 diff/files → 按 code-review 分级找 Critical/Warning → 查 ci +builds → 汇总成评审评论回写 → 按「0 Critical + CI 通过 → 合并」门禁给判定。 合并/评论等写操作前先向我确认。

A.7 真实运行效果

目标 whale_hihihi/gitlink-cli：脚本采集真实 PR 列表与 CI 状态；现场可在 http://121.41.222.73:8000 的 pr-guard 区点「用真实 PR 跑」看真实数据流入 5 步气泡。

A.8 与 code-review 的区别

code-review 只产出 Review 评论（找问题、无结论）；pr-guard 在其之上加了 CI 检查 + 门禁判定 + 可选合并，是完整闭环。两者共享审查逻辑，pr-guard 复用 code-review 的分级输出。

---

三、工作流 B · pr-quality-gatekeeper（Policy-as-Code 评分卡）

B.1 背景与目标

pr-guard 的门禁是「0 Critical + CI 通过」二元的；真实团队往往要多维度量化（测试覆盖率、提交规范、PR 卫生…），且标准要随仓库演进、可审计。gatekeeper 把合并标准写进版本化的 gatekeeper.yaml，对 PR 算出透明的 0-100 评分卡与三态裁决——同一策略 + 同一 PR → 同一裁决（可裁决、可审计、可复现）。

B.2 五维加权评分（满分 100，确定性计算）

维度	权重	算法要点	信号来源
review_findings	40	权重 × max(0, 1 - Σ扣分/40)；blocker 单条清零本维	code-review 的 Critical/Warning 数
test_coverage	20	改源码无测试→0；有测试按 0.5+0.5×ratio	变更文件中的 source/test 文件比
pr_hygiene	15	描述≥30字 / 关联 Issue / 体量适中，各 1/3	PR 元信息
commit_quality	15	符合 Conventional Commits 的比例	commit 列表
ci_status	10	通过=10 / 失败=0 / 未知=5	ci +builds

扣分表：blocker 100、major 25、minor 5、nit 1（累计达本维权重即扣到 0）。

B.3 五项硬门禁（命中任一即拦截→REQUEST_CHANGES）

门禁	命中条件
forbid_blocker_findings	存在 blocker 级发现（如硬编码密钥、注入、路径遍历）
require_ci_pass	CI 明确失败（未知/无记录不触发）
require_tests_for_src_changes	改了源码却没加测试
require_linked_issue	未关联 Issue（可选）
max_changed_files	改动文件数超上限（默认 80）

B.4 三态裁决逻辑

命中硬门禁                        → ❌ REQUEST_CHANGES（打 gatekeeper:needs-changes）
total ≥ pass（默认 85）           → ✅ PASS（打 gatekeeper:pass）
total < request_changes（默认 60）→ ❌ REQUEST_CHANGES
其余                              → 💬 COMMENT（打 gatekeeper:review，人工定）

裁决以 common 评论回写（评分卡标题标注三态），强语义的 approved/rejected 留给人工——避免 AI 越权批准。状态由标签承载。

B.5 九步工作流

①加载策略（gatekeeper.yaml，校验权重和=100、阈值合法）→ ②采集 PR 上下文（pr +view/+files/+diff + api GET .../commits + ci +builds）→ ③AI 按 severity 分级产出发现 → ④逐维确定性评分 → ⑤硬门禁评估 → ⑥裁决 → ⑦渲染 Markdown 评分卡 → ⑧回写（受 --apply）→ ⑨安全规则（默认 dry-run、绝不默认合并）。

B.6 评分卡输出样例（回写到 PR）

## 🛡️ Gatekeeper Report — PR #42 feat: add rate limiter
Verdict: ❌ REQUEST_CHANGES · Score: 58/100 · policy: gatekeeper.yaml@v1
| Dimension | W | Score | Notes |
| Review findings | 40 | 20/40 | 0 blocker / 2 major / 3 minor |
| Test coverage   | 20 | 0/20  | 3 src / 0 test → 触发硬门禁 |
| PR hygiene      | 15 | 10/15 | 描述OK / 无关联Issue |
| Commit quality  | 15 | 15/15 | 4/4 conventional |
| CI status       | 10 | 10/10 | passing |
⛔ Hard gate failures (1): require_tests_for_src_changes
🔴 Must fix (2): …   🟡 Should fix (3): …   ✅ Strengths: …

B.7 触发方式

默认 dry-run（安全）：不传 --apply 只打印评分卡；--apply 才回写评论 + 打标签；合并需「裁决=PASS + 策略 auto_merge=true + 显式 --apply」三条件齐备且二次确认。 Agent 提示词：

读 skills/gitlink-gatekeeper/SKILL.md，按 gatekeeper.yaml 对 <owner>/<repo> PR # 出评分卡：采集→分级→五维评分→硬门禁→裁决→渲染评分卡。先 dry-run 给我看，确认后再 --apply 回写。

B.8 真实验证

对仓库 113 个历史 PR 全仓批扫，均分 88.5——验证评分卡对真实 PR 有良好区分度（低分 PR 普遍缺测试或 CI 失败）。

B.9 策略预设（examples/）

预设	阈值	适用
gatekeeper.yaml	pass 85 / rc 60	默认平衡，大多数仓库
gatekeeper.strict.yaml	高阈值 + require_linked_issue	核心库 / 发布分支
gatekeeper.lenient.yaml	低阈值 + 关部分门禁	早期项目 / 文档仓库

---

四、工作流 C · community-ops-sweep 社区运营增量对账

C.1 背景与目标

维护一个开源仓库的社区运营，散落在一堆动作里：新 Issue 要分诊、要找人负责、定期出周报、发版要写 Release Notes、PR 还得关联到对应 Issue。community-ops-sweep 把这些做成一次调用、增量对账：给定时间窗（since 或读 checkpoint），处理该窗口内所有新 Issue + 合并 PR，5 项事件一网打尽。Claude Code Workflow 实现（workflows/community-ops-sweep/）。

C.2 五项事件（一次调用）

R1 新 Issue triage（分类/打标）→ R2 建议 owner（路由规则）→ R3 生成社区周报
   → R4 发布 Release Notes → R5 PR→Issue 关联闭环

C.3 三层架构（判断与计算分离，JSON 文件交接）

层	职责	实现
CC Workflow (JS)	编排：按 phase 调度	community-ops-sweep.wf.js
LLM agent 层	只做判断（Issue 分类、PR 关联、owner 建议、散文增强）	Claude Code agent
Python 引擎	只做计算（采集/归一化/id 解析/合并/守卫/渲染/写回）	scripts/community_ops_sweep.py

这种分离让确定性引擎可单独跑、可单测（18 个单测），LLM 只负责需要语义判断的部分——可复现、可回归。

C.4 子命令（确定性引擎）

python scripts/community_ops_sweep.py collect  --owner <o> --repo <r> --since 2026-06-01T00:00:00Z  # 采集窗口内新 issue + 合并 PR
python scripts/community_ops_sweep.py plan     --candidates c.json --triage t.json --owners o.json --links l.json  # 读 LLM 决策 → 写计划
python scripts/community_ops_sweep.py apply    --plan plan.json --owner <o> --repo <r> [--apply]      # dry-run 预览，--apply 才真写
python scripts/community_ops_sweep.py checkpoint --owner <o> --repo <r>                              # 推进 .last-sweep + 追加 triage-log

C.5 触发方式

原生 Claude Code Workflow：/community-ops-sweep owner=<o> repo=<r>（若放入 .claude/workflows/），或经 Workflow 工具带入 since（可选，留空读 .last-sweep）、apply（默认 false）。 路由规则：routing-rules.example.yaml 配置 R2 的 owner 建议（opt-in auto_assign）。

C.6 真实运行 + 测试

字段名实测自真实 API（baoerjun/gitlink-cli 等）；18 个确定性逻辑回归测试（tests/test_sweep.py）保证引擎可复现。

C.7 安全

默认 dry-run（--apply 才写）· 标签整体替换（发期望全集，不丢标签）· 关 Issue 前守卫（已关跳过）· 绝不自动合并 PR · 写操作可逆（关可 reopen、release 可 edit）。

---

五、三个工作流的对比与协同

维度	pr-guard	gatekeeper	community-ops-sweep
解决问题	PR 合不合（二元门禁）	PR 合不合（多维量化裁决）	社区运营批量自动化
裁决粒度	0 Critical + CI 通过	0-100 分 + 三态	5 项事件分别处理
策略化	固定门禁	可版本化 gatekeeper.yaml	路由规则 yaml
触发	PR 事件	PR 事件	时间窗增量
可复现	脚本	脚本 + 确定性评分	CC Workflow + 18 单测

三者可叠加：community-ops-sweep 处理出的代码类 Issue → 贡献者提 PR → gatekeeper 出评分卡 → 满足 pr-guard 门禁 → 合并。

六、可复现性与 Agent 兼容

• 可复现：pr-guard/gatekeeper 提供 shell 脚本与确定性算法（同输入同输出）；community-ops-sweep 提供 CC Workflow + 18 单测 + checkpoint 增量机制。
• Agent 兼容：pr-guard / gatekeeper 兼容 Claude Code（读 SKILL.md 编排）；community-ops-sweep 为原生 Claude Code Workflow（.wf.js）。

七、与子赛题二的区别

子赛题二交付独立可复用的单 Skill（SKILL.md + examples）；子赛题三交付串联多步的完整解决方案：pr-guard 串 4 域、gatekeeper 9 步聚合 5 维、community-ops-sweep 串 5 项事件。三者的底层 Skill（code-review / ci / issue / pr 等）即子赛题二的产物，复用于本工作流。