[Feature] 评审门禁发现结构化（文件/行号/修改建议）：返工时完整交回实现节点，并可发布为交付 PR 行级评论

Aperta
  • Qualcosa non va?
#315 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
28/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
git, github, go
Ambito
backend, developer-experience, tooling

Direzione di ricerca

Start with the finding schema in internal/domain/run.go (GateFinding) and the matching inputSchema in internal/gatemcp/server.go, then trace how applyGateResult in internal/engine/gate_submit.go turns a rework into the feedback injected by internal/engine/node_execute.go. The delivery side lives in internal/engine/integrate.go and internal/tracker/github.go, where PR creation and the new review-publishing call would go. Done means the extended findings validate, the rework prompt carries every finding, diff anchoring is tested, and review comments appear only when the repo config enables them.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

背景与借鉴来源

AI 代码评审类系统普遍把评审意见做成定位到文件/行、能直接采纳的结构化建议，同一份结构化数据既交回 Agent 定向修复，也发成 PR 行级评论给人看。参考项目（数据采集于 2026-11-13）：

  • anthropics/claude-code-action：约 9.9k stars，2026-11-12 仍有 push。内置 github-inline-comment-server（src/mcp/github-inline-comment-server.ts），提供 create_inline_comment 工具，参数有 path、line/startLine、side、可整段替换的 suggestion 代码块；不带 confirmed=true 的调用先缓冲，结束时再统一发布，测试/探测用的评论会被丢掉。
  • The-PR-Agent/pr-agent：约 16k stars，2026-11-12 仍有 push，最新 release v0.50.0（2026-11-07）。/review、/improve 输出带行号的建议，支持 committable_code_suggestions（发成可一键提交的 GitHub suggestion）、persistent_comment（同一 PR 只更新一条汇总评论，不刷屏）、suggestions_score_threshold（低分建议不发）。
  • reviewdog/reviewdog：约 9.7k stars，最新 release v0.21.3（2026-11-07）。用统一的 rdjson 诊断格式（Diagnostic{location{path, range{start,end}}, severity, suggestions[]}）承接任意工具输出，-reporter=github-pr-review 发成行级评论；-filter-mode=added|diff_context|file|nofilter 默认只报本次 diff 新增的行，避免对历史代码误报。

借鉴点：评审发现结构化（文件 + 行范围 + 修改建议）→ 按 diff 过滤 → ① 完整交回返工节点 ② 发布到交付 PR 的行级评论 + 一条持续更新的汇总评论。

LoopForge 现状与不足

（代码引用固定到 main a7c6f15）

  1. 返工时评审发现丢失，上游只拿到一句 reason。 Gate 节点调用 submit_gate_result 提交 decision=rework 时，engine/gate_submit.go#L93-L97 的 applyGateResult 只把 result.Reason 拼进 error；engine/node_outcome.go#L85 再以 Reason: "节点失败自动打回：" + err.Error() 调 Reject，engine/run_ops.go#L336 写进上游 NodeRun.Feedback；最后由 engine/node_execute.go#L714-L720 按"上一轮未通过 Agent 门禁…{{feedback}}"注入 prompt。GateResult.Findings 和 ActionRequired 只在 nr.GateResult 上展示（botinteraction 卡片、assistant_run_view 最多 6 条），被打回的实现节点看不到。评审列了 10 条问题，实现节点却只能看到一句概括，只能重新排查，返工轮次和 Token 都被浪费，而且容易漏修。
  2. findings 没有位置信息。 gatemcp/server.go#L23-L58 和 domain/run.go#L164-L168 的 GateFinding 只有 severity/title/evidence 三个自由文本字段，没有 path、startLine/endLine、suggestion。这样既没法校验发现是否落在本次改动里，也没法映射到 PR 的具体行，不同 Agent 写出来的 severity 取值也五花八门。
  3. 交付 PR 上没有评审痕迹。 engine/integrate.go#L158-L164 合入时 PR 描述只有 issue/run/source/target（integrateMRDescription L199-L213）；tracker/github.go#L146-L185 只调用 POST /pulls 和 PUT /pulls/{n}/merge，从未调用 POST /pulls/{n}/reviews。人工 reviewer 打开 PR，看不到 LoopForge 内部评审节点发现过什么、修了什么、还剩哪些低优先级问题。

与已有 issue 的区别：#219 是外部 PR 评审意见流入 LoopForge 触发返工；本 issue 是 LoopForge 内部 Gate 评审结果的结构化、交回返工节点，以及反向发布到 PR，二者可以共用 PR 评论发布模块。#255 是多候选择优，#231 是等 CI，#227 是密钥扫描，均不涉及评审发现的传递。

建议方案

1. 扩展 GateFinding 结构（向后兼容）

  • gatemcp 的 inputSchema 和 domain.GateFinding 增加可选字段：path（相对仓库根）、startLine、endLine、suggestion（建议替换的代码，≤4000 字节）、category（如 correctness/security/test/style）、id（Agent 自定义的稳定 ID，用于跨轮跟踪）。severity 规范为枚举 blocker|major|minor|info，旧的自由文本按关键字归一，归不了的记为 info。engine/gate_submit.go 增加相应的长度/路径校验：path 不得是绝对路径、不得含 ..。
  • appendSubmitGateInstruction 的提示里说明：每条问题尽量带 path/startLine；能给出修改代码时填 suggestion。

2. 按 diff 过滤和锚定（参考 reviewdog filter-mode）

  • 节点提交后，在工作区以 git diff <base>...HEAD 计算本次变更的行区间，给每条 finding 标记 inDiff（added / diff_context / file / outside）。不丢弃 outside 的条目，但在 UI 和 PR 发布里分开展示；path 在工作区不存在的标为 unanchored。

3. 返工时完整交回发现

  • applyGateResult 返回 rework 时，用 GateResult 生成结构化反馈块（Markdown 清单：[blocker] path:L12-L20 标题 / 证据 / 建议代码），按 severity 排序，并附 ActionRequired，写进上游 NodeRun.Feedback，不再只写 err.Error()。总量超过上限（比如 16KB）时截断低优先级条目，并把全文作为 gate-findings.json artifact 让 Agent 自己读。
  • 下一轮该 Gate 再评审时，把上一轮 findings（带 id）注入 Gate 的 prompt，要求逐条标注 resolved / still_open / wontfix；Run 详情显示每轮 findings 的变化（新增、已修、仍未修）。

4. 交付 PR 发布评审结果（按仓库配置，默认关闭）

  • 仓库设置新增 publishReviewFindings：off（默认）/ summary（只发一条汇总评论）/ inline（汇总加行级评论）。另设 minSeverity（默认 major），低于阈值的不发行级评论。
  • 在 tracker 加 githubPublishReview(project, number, commitSHA, summary, comments[])：
    • 汇总评论按 persistent_comment 方式维护：正文带隐藏标记 <!-- loopforge-review:{runId} -->，再次发布时找到后 PATCH 更新，不新增；内容为各轮评审结论、已修复/遗留数量，以及 Run 链接。
    • 行级评论通过 POST /pulls/{n}/reviews（event=COMMENT）一次批量提交，只包含 inDiff=added|diff_context 的条目，有 suggestion 的用 ```suggestion 块，方便一键采纳。
    • 发布时机：工作分支合入集成分支创建/找到 PR 之后、merge 之前（与 #231 的 CI 门禁兼容）；发布失败只记事件，不阻断交付。
  • 工蜂 MR 走同一接口抽象，首期可以只实现 summary。

验收标准

  1. submit_gate_result 接受带 path/startLine/endLine/suggestion/category/id 的 findings，旧格式（只有 title/severity/evidence）仍然能通过；非法 path（绝对路径、..）和超长字段被拒绝，并返回明确错误。有对应单测。
  2. 构造 SOP「实现 → 评审(Gate, rejectTo=实现)」：评审提交 rework 和 3 条 findings 后，实现节点第二轮的实际 prompt（可在 Run 的 prompt artifact 中查看）包含这 3 条完整的 path/行号/证据/建议，以及 ActionRequired；超过上限时有截断提示，且能找到 gate-findings.json artifact。
  3. 第二轮评审的 prompt 包含上一轮 findings 列表；Run 详情页能看到每轮 findings 的新增/已修/仍未修统计。
  4. findings 会按本次 diff 标记 inDiff，有单测覆盖 added、上下文行、改动范围外、文件不存在四种情况。
  5. GitHub 仓库开启 inline 后，交付 PR 上出现 1 条汇总评论，以及只针对改动行、且 ≥minSeverity 的行级评论，有 suggestion 的可以直接 "Commit suggestion"。同一 PR 再次交付时更新汇总评论，不会新增重复评论。off 时不发任何评论。
  6. PR 评论发布失败（403/422 等）时，Run 中有 delivery.review_publish_failed 事件，交付和合入流程照常继续。
  7. 改动符合 AGENTS.md 分层约定：新增配置字段配套 migrations/NNN_*.sql，不在 Store 上新增领域方法。
Lingua principale
Go
Stelle
141
Fork
28
Merge medio
1g 15h
PR unite (30g)
113

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Tencent/LoopForge

Tutte le issue di Tencent/LoopForge

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.