ReviewBridge 技术设计
# ReviewBridge 技术设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 摘要
ReviewBridge 是 kunora-wiki 自研系统的治理桥接层，负责把 ConfigManager、SyncEngine、Display Adapter、Index Adapter、AgentBridge 产生的报告转换为可审查的 GitHub PR、checks、workflow summary 和维护者可读的 ReviewReport。
ReviewBridge 不生成知识内容、不判断文档语义正确性、不调用 RAGFlow 或索引服务。它的职责是保证所有会影响正式内容、发布状态或 agent 迭代结果的变更都进入可审计、可回滚、可人工审批的流程。
2. 模块目标
- 创建或更新 Sync PR、Release PR、Agent PR 等治理入口。
- 根据
SourceChanges、ConfigImpactReport、PublishImpactReport、AgentBridgeReport生成ReviewReport。 - 生成 GitHub checks 或等价检查状态。
- 对冲突、删除、高风险配置、构建失败、索引失败输出阻断或警告状态。
- 保持 PR 创建和 check 更新幂等，避免重复 PR、重复评论和状态抖动。
- 隔离 GitHub API/CLI 细节，只暴露
ReviewProvider契约。
3. 非目标
- 不直接修改 main 分支。
- 不合并 PR，不批准 review。
- 不生成或改写文档正文。
- 不执行同步 diff、展示构建、索引 upsert 或问答。
- 不把 GitHub 私有 API 结构透传给其他自研模块。
- 不绕过 branch protection 或 required checks。
4. 上下文边界
ReviewBridge 位于 L1 Governance 层。它可以依赖 ConfigManager、WorkspaceStore、GitProvider、ReviewProvider，但不能依赖 Answer API 或 Agent Access API 的运行时服务。
5. 输入与输出
5.1 输入
| 输入 | 来源 | 说明 |
|---|---|---|
ConfigImpactReport | ConfigManager | 配置变更影响和风险等级。 |
SourceChanges | SyncEngine | 同步变更、冲突、删除和错误。 |
PublishImpactReport | Display Adapter dry-run | 发布影响、URL 变化、删除页面缓存窗口。 |
SiteManifest / display result | Display Adapter | 构建和站点状态。 |
IndexManifest | Index Adapter | 索引目标状态和部分失败。 |
AgentBridgeReport | AgentBridge | agent 生成的候选 diff、验证结果和证据。 |
| PR options | workflow/manual | PR 类型、目标分支、幂等键、标签策略。 |
5.2 输出
| 输出 | 消费者 | 说明 |
|---|---|---|
ReviewReport | 维护者、workflow | 人类可读审查摘要。 |
CheckReport | GitHub checks、CI | 机器可读检查结果。 |
| PR create/update result | workflow、AgentBridge | PR URL、branch、status。 |
| review comments | GitHub PR | 冲突、删除、高风险配置提示。 |
ErrorObject | workflow、维护者 | PR/check 操作失败。 |
6. 依赖的 common 契约
| 契约 | 用途 |
|---|---|
ConfigImpactReport | 配置变更风险判断。 |
SourceChanges / SyncChange | 生成 Sync PR 内容和 check。 |
PublishImpactReport | 发布变更审查。 |
SiteManifest / IndexManifest | 发布和索引状态 check。 |
AgentBridgeReport | Agent PR 报告和阻断依据。 |
ReviewReport | ReviewBridge 标准输出。 |
CheckReport | check 状态输出。 |
GitProvider | 分支和提交操作。 |
ReviewProvider | PR、check、comment adapter。 |
ErrorObject | 错误和降级输出。 |
7. PR 类型
| PR 类型 | 来源 | 目标 | 默认状态 |
|---|---|---|---|
| Sync PR | SyncEngine SourceChanges | 把来源变更同步到 publish/** | 有冲突时 draft 或 failed check。 |
| Release PR | Display/Index/publish dry-run | 发布 manifest、站点和索引状态封板 | 构建失败时 failed check。 |
| Agent PR | AgentBridge AgentBridgeReport | agent 生成的候选文档改进 | 缺证据或验证失败时 draft/failed。 |
| Config PR Check | ConfigManager ConfigImpactReport | 配置变更审查 | high/blocking 需要人工确认。 |
ReviewBridge 不决定 PR 是否最终合并；它只提供检查和审查材料。
8. 核心流程
8.1 Sync PR 流程
规则：
- 同一个 source run 或同一 dedupe payload 重试时更新已有 PR，不创建重复 PR。
- 冲突文件不进入候选变更，只进入报告和 failed/warning check。
- 删除候选必须在 PR body 中突出显示。
- 部分 source 失败时 PR/check 状态必须标记 partial。
8.2 Release Review 流程
Release Review 聚合展示构建、发布 manifest 和索引 manifest：
- 读取
PublishImpactReport、SiteManifest、IndexManifest。 - 生成页面新增/更新/删除、URL 变化、索引目标状态摘要。
- 对 build failed、index failed、drift failed 输出 failed check。
- 只在所有阻断项通过时允许 Release PR 进入 ready 状态。
8.3 Agent PR 流程
Agent PR 必须满足：
AgentBridgeReport中有明确任务、证据和 diff 摘要。- 所有写入基于最新 expected hash 或已重新验证。
- 缺少 citation、RAGFlow 输出非法、并发冲突时 failed check。
- PR body 必须标明 agent 生成，不伪装成人工提交。
9. Check 状态规则
| 输入状态 | Check 结果 | 说明 |
|---|---|---|
| 无错误、无冲突 | success | 可人工 review。 |
| warning | neutral 或 success with warnings | 不阻断，但 PR body 明示。 |
| conflict | failure | 阻断，需人工处理。 |
| delete candidate | neutral/failure | MVP 默认至少 warning；高风险可 failure。 |
| config high impact | failure 或 required manual | 需要人工确认。 |
| display build failed | failure | 不允许发布成功态。 |
| index partial | neutral 或 failure | 取决于发布策略，必须明示 degraded。 |
| agent validation failed | failure | 不允许作为可合并改进。 |
CheckReport 必须包含：status、summary、blockingItems、warnings、sourceReports、links。
10. 幂等策略
| 对象 | 幂等键 | 行为 |
|---|---|---|
| Sync PR | source changes canonical payload hash | 更新已有 PR 分支和 body。 |
| Release PR | publishRunId 或 release payload hash | 更新 release PR。 |
| Agent PR | taskId + base document hashes | 更新同一任务 PR；base 变化则标记冲突。 |
| Check | check name + head sha | upsert，不重复创建。 |
| Comment | comment marker + section id | 更新 marker 包围内容。 |
ReviewBridge 必须避免重试时刷屏式重复评论。
11. 状态与持久化
ReviewBridge 自身不拥有长期业务状态， 状态主要存在于 Git 分支、PR、checks 和 report 文件中。
| 数据 | 位置 | owner |
|---|---|---|
| PR branch | GitHub/Git | ReviewBridge via GitProvider |
| PR body/comment/check | GitHub | ReviewBridge via ReviewProvider |
ReviewReport | PR body / workflow summary | ReviewBridge |
CheckReport | GitHub checks / workflow summary | ReviewBridge |
| source/publish/index reports | state/** | 对应 producer 模块 |
12. 错误处理
| 错误码 | retryable | 场景 | 处理 |
|---|---|---|---|
review.branch_create_failed | true | 创建或更新分支失败 | 保留 report，提示重试。 |
review.pr_create_failed | true | PR 创建失败 | 保留 branch/report，提示人工处理。 |
review.pr_update_failed | true | PR body 或 metadata 更新失败 | 保留 check/report。 |
review.check_update_failed | true | check 写入失败 | workflow summary 明示人工确认。 |
review.permission_denied | false | token 权限不足 | 阻断并提示授权修复。 |
adapter.github_unavailable | true | GitHub 暂不可用 | 可重试，不改 main。 |
任何 review 操作失败都不得导致直接写 main。
13. 安全与审计
- PR body 和 comments 不输出 secret、token 或未授权内容全文。
- Agent PR 必须标明自动生成来源和任务 ID。
- high impact config 需要显式 check 标记。
- branch protection 是最终合并门禁，ReviewBridge 不能绕过。
- ReviewProvider 只能暴露标准 PR/check/comment 契约，不暴露 GitHub 私有响应给上层模块。
14. 测试要求
| 测试 | Fixture | 预期 |
|---|---|---|
| blocking check | fixtures/common/review/check-report-blocking.json | 生成 failed check。 |
| sync conflict | fixtures/common/sync/add-update-keep-conflict.json | 冲突进入 report，不写候选内容。 |
| delete source page | fixtures/common/sync/delete-source-page.json | PR body 标记删除风险。 |
| site build failed | fixtures/common/manifest/site-manifest-build-failed.json | Release check failed。 |
| index partial | fixtures/common/manifest/index-manifest.partial.json | check/report 标记 partial。 |
| agent invalid output | fixtures/common/agent/ragflow-invalid-output.json | Agent PR failed 或不创建 ready PR。 |
模块验收标准：
- PR 创建重试不会产生重复 PR。
- Check upsert 重试不会产生重复 check 名称。
- marker comment 可更新，不刷屏。
- 所有 failed/partial/warning 状态在 ReviewReport 中可追溯到 producer 报告。
- GitHub adapter mock 不 泄漏私有响应结构。
15. 设计决策
| 决策 | 说明 | 取舍 |
|---|---|---|
| ReviewBridge 只做治理桥接 | 保持内容生成、同步计算、发布构建职责分离。 | 需要从多个 producer 汇总报告。 |
| PR/check/comment 使用 upsert | 保证 workflow 重试可控。 | 需要稳定 marker 和幂等键。 |
| 冲突默认 failed check | 防止自动覆盖人工修改。 | 需要人工介入解决。 |
| GitHub 私有结构隔离在 ReviewProvider | 降低未来替换平台成本。 | adapter 需要维护映射层。 |
16. 待确认问题
- delete candidate 在 MVP 中应统一 failure，还是允许 neutral + manual review。
- Release PR 与 Sync PR 是否使用同一目标分支策略。
- high impact config 是否需要专门的人工确认标签或 comment command。
- CheckReport schema 是否需要拆成 Public Contract 供外部 workflow 读取。