AgentBridge 技术协议

1. 协议目标

AgentBridge 协议定义 RAGFlow 文档迭代结果如何被安全地转换为 Git diff 和 Release PR。

核心原则：

• RAGFlow 只生成结构化建议或内容草稿。
• AgentBridge 才能写工作分支、生成 diff、创建 Release PR。
• 所有输出必须可审查、可回滚、可追踪。

2. 覆盖产品特性

产品特性	覆盖方式
文档整理	接收 RAGFlow 建议并写入 publish/**
文档补全	要求补全内容附带证据和理由
基于反馈迭代	从 GitHub Issue 或质量事件创建迭代任务
变更说明生成	生成 PR body 的 what/why/risk/citations
Release PR 创建	创建或更新 docs-release/* 分支和 PR
Git 可审查变更	所有改动表现为 Git diff
写入权限边界	只允许写授权路径，不直接写 main

3. 输入

输入	来源	说明
IterationTask	GitHub Issue / 人工触发 / 质量事件	任务目标、scope、约束、期望输出
RagflowIterationResult	RAGFlow Agent	结构化建议、草稿内容、证据、风险
AgentPolicy	config/agent-access.yaml 或运行配置	允许工具、路径、dataset、写入权限
PageManifest	state/page-manifest.json	页面状态、来源、质量和关联任务

4. 输出

输出	载体	说明
Git diff	docs-release/* 分支	只修改授权 publish/** 路径
Release PR	GitHub PR	包含变更说明、证据、风险、影响页面
AgentBridge report	workflow summary / state	记录校验结果和失败原因

5. 数据结构

5.1 IterationTask

{
  "taskId": "...",
  "trigger": "issue|manual|quality-event",
  "goal": "补充 agent memory 配置说明",
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "working"
  },
  "base": {
    "gitCommit": "...",
    "files": {
      "publish/system/components/kunora-kgent/index.md": "..."
    }
  },
  "constraints": {
    "allowedActions": ["update", "add"],
    "requireCitations": true,
    "allowDelete": false
  },
  "relatedIssue": 123
}

5.2 RagflowIterationResult

{
  "summary": "...",
  "changes": [
    {
      "path": "publish/system/components/kunora-kgent/index.md",
      "action": "update",
      "baseHash": "...",
      "reason": "...",
      "evidence": [
        {
          "path": "publish/system/components/kunora-kgent/reference.md",
          "anchor": "..."
        }
      ],
      "draftContent": "...",
      "patch": null,
      "mode": "whole-file",
      "overwrite": false
    }
  ],
  "risk": "low",
  "requiresHumanReview": true
}

5.3 AgentBridgeReport

{
  "taskId": "...",
  "status": "passed|failed",
  "branch": "docs-release/...",
  "pullRequest": 123,
  "validatedChanges": 2,
  "rejectedChanges": [],
  "errors": []
}

6. 校验规则

AgentBridge 必须在写文件前校验：

• path 必须位于授权 publish/** scope 内。
• action 必须在任务允许动作内。
• baseHash 必须和当前文件 hash 匹配，除非 action 是新增且目标不存在。
• draftContent 不能为空，除非 action 是 delete。
• requireCitations=true 时，必须至少有一个 evidence。
• 不允许修改配置、workflow、设计文档或 state 文件，除非任务明确授权。
• 不允许直接写 main。

6.1 action 字段约束

action	必填字段	前置条件	失败处理
add	path、draftContent、reason	目标文件不存在，或 overwrite=true 且任务明确允许覆盖	目标已存在且未允许覆盖时拒绝
update	path、baseHash、draftContent、reason	当前文件存在，且当前 hash 等于 baseHash	hash 不匹配时生成并发冲突
delete	path、baseHash、reason	allowDelete=true，且当前 hash 等于 baseHash	未授权删除或 hash 不匹配时拒绝

6.2 内容修改模式

update 支持两种内容表达方式。

mode	字段	适用场景	约束
patch	patch	局部修改，推荐默认模式	patch 必须能在 baseHash 对应内容上干净应用
whole-file	draftContent	重构、短文档或完整重写	必须通过 baseHash 校验，并在 PR 中标记为整文件改写

规则：

• MVP 可以先实现 whole-file，但协议必须保留 patch 字段。
• 长文档默认应优先使用 patch，减少无关 diff。
• whole-file 模式必须在 PR body 中标记影响范围和整文件改写原因。
• patch 应使用 unified diff 或等价结构化 patch。
• patch 应用失败时，不得 fallback 为整文件覆盖，必须报错。

6.3 并发保护

AgentBridge 必须防止基于旧内容生成的草稿覆盖新内容。

规则：

• IterationTask.base.files 记录任务创建时的文件 hash。
• RagflowIterationResult.changes[].baseHash 必须来自任务基线或 RAGFlow 读取时的页面版本。
• 写入前重新计算当前文件 hash。
• 当前 hash 与 baseHash 不一致时，不写文件，记录 concurrent_change。
• 并发冲突应进入 PR/report 或生成 Issue，由人或后续任务处理。

7. PR 规则

Release PR 必须包含：

• 任务来源。
• 改了什么。
• 为什么改。
• 证据和引用。
• 风险。
• 影响页面。
• 关联 Issue。
• AgentBridge 校验结果。

无结构化说明的 PR 应标记失败或要求重试。

8. 错误处理

错误	处理
RAGFlow 输出非 JSON	标记任务失败，不写文件
路径越权	拒绝该 change，记录安全错误
缺少证据	拒绝该 change 或要求人工确认
baseHash 不匹配	拒绝写入，记录 concurrent_change
Git 分支创建失败	不重试写 main，保留错误报告
PR 创建失败	保留分支和 report，提示人工处理

9. 验收用例

用例	预期
合法 update 带 evidence	写入分支并创建 Release PR
RAGFlow 输出包含越权路径	拒绝越权 change
RAGFlow 输出缺少引用	根据 requireCitations 拒绝或标记需人工确认
Agent 尝试删除文件但任务不允许	拒绝删除
生成期间文件被别人修改	拒绝写入并报告并发冲突
PR 创建后	PR body 包含 what/why/risk/citations/impact