AgentBridge 技术设计
# AgentBridge 技术设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 摘要
AgentBridge 是 kunora-wiki 的智能体迭代桥接层，负责把受控改进任务转换为 agent/RAGFlow 可执行上下文，校验 agent 输出，生成候选 diff、报告和 Release PR。它是 L4 Iteration 层模块，必须依赖前置的配置、工作区、访问、索引、问答和 review 契约。
AgentBridge 不直接写 main，不自动批准或合并 PR，不允许无证据事实补全。所有 agent 产出的文档变更必须经过路径授权、base hash 校验、证据校验、patch 校验和 ReviewBridge 治理。
2. 模块目标
- 接收
ImprovementTaskRequest、Issue 或人工触发，生成IterationTask。 - 通过 Agent Access API 获取授权后的
ContextPack。 - 调用 RAGFlow 或其他 agent 执行受控文档改进。
- 校验
RagflowIterationResult的结构、scope、证据、风险和变更合法性。 - 使用 WorkspaceStore 在候选分支上应用安全 diff。
- 生成
AgentBridgeReport，交给 ReviewBridge 创建或更新 Agent PR / Release PR。 - 对并发变更、缺少证据、patch 失败和越权路径输出标准错误。
3. 非目标
- 不直接写 main 分支。
- 不合并 PR，不批准 review。
- 不绕过 Agent Access API 获取上下文。
- 不在 RAGFlow 输出非法时尝试猜测修复。
- 不在 patch 失败时自动 fallback 为整文件覆盖。
- 不修改 ConfigManager、SyncEngine、Display Adapter、Index Adapter 的状态事实。
- 不把 RAGFlow 私有响应结构透传给 ReviewBridge 或 PR body。
4. 上下文边界
AgentBridge 位于 L4 Iteration 层。它可以依赖 ConfigManager、WorkspaceStore、Agent Access API、ReviewBridge、RagflowClient 和 IssueTracker，但不能被 L0-L3 模块依赖形成反向调用。
5. 输入与输出
5.1 输入
| 输入 | 来源 | 说明 |
|---|---|---|
ImprovementTaskRequest | Agent Access API / IssueTracker | 用户、agent 或系统创建的改进任务。 |
IterationTask | AgentBridge | 标准化后的迭代任务。 |
ContextPack | Agent Access API | 授权后的上 下文和引用。 |
RagflowIterationResult | RagflowClient | agent 生成的候选修改。 |
current DocumentRecord[] | WorkspaceStore | 当前文档状态和 contentHash。 |
| Review options | workflow/manual | PR 类型、目标分支、dry-run、retry。 |
5.2 输出
| 输出 | 消费者 | 说明 |
|---|---|---|
AgentBridgeReport | ReviewBridge、维护者 | 验证结果、候选变更和拒绝原因。 |
| candidate diff | ReviewBridge / GitProvider | Agent PR 分支内容。 |
| rejected changes | 维护者、agent 调试 | 越权、并发冲突、缺证据等被拒绝项。 |
ErrorObject[] | workflow、ReviewBridge | 标准错误。 |
| audit/workflow log | 运维、审计 | agent run 记录。 |
6. 依赖的 common 契约
| 契约 | 用途 |
|---|---|
ImprovementTaskRequest | 任务来源。 |
IterationTask | agent 迭代标准输入。 |
ContextPack | 授权上下文。 |
RagflowIterationResult | 外部 agent 输出标准化结果。 |
IterationChange | 单个候选变更。 |
AgentBridgeReport | 模块输出 报告。 |
Citation | 证据校验。 |
DocumentRecord / ContentHash | base 校验和并发冲突检测。 |
NormalizedPath | path scope 校验。 |
ReviewReport / CheckReport | ReviewBridge PR 治理输入。 |
ErrorObject | 错误输出。 |
7. 核心流程
7.1 任务准备
任务准备规则：
IterationTask.scope必须来自有效授权，不接受未校验 scope。base.files必须记录目标文件当前contentHash。constraints.requireCitations默认 true。allowDelete默认 false。- 任务目标和上下文必须能追溯到 issue、feedback 或人工触发来源。
7.2 Agent 输出执行与校验
校验失败的 change 必须进入 rejectedChanges；不得静默丢弃。
8. 变更校验规则
| 校验 | 规则 | 失败错误 |
|---|---|---|
| schema | RagflowIterationResult 必填字段完整 | agent.ragflow_output_invalid |
| scope | change.path 位于 task scope 内 | agent.path_out_of_scope |
| action | action 属于 allowedActions | agent.task_invalid |
| delete | delete 需要 allowDelete=true | agent.task_invalid |
| baseHash | update/delete 当前 hash 必须等于 baseHash | agent.concurrent_change |
| evidence | requireCitations 时每个事实性 change 必须有 citation | agent.missing_evidence |
| patch | patch 必须可应用且只影响目标 path | agent.patch_apply_failed |
| overwrite | overwrite=true 默认拒绝，除非任务显式允许 | agent.task_invalid |
| risk | high risk 必须进入 ReviewBridge failed/manual check | agent.task_invalid 或 warning |
9. Diff 应用规则
- add：目标 path 不存在，且 path 在 scope 内。
- update：目标 path 存在，baseHash 必须匹配当前 hash。
- delete：必须
allowDelete=true且 baseHash 匹配。 - patch 模式：只允许修改目标文件，不允许跨文件 patch。
- whole-file 模式：必须重新计算 contentHash，并保留必要 frontmatter。
- patch apply 失败不得 fallback 为 whole-file 覆盖。
- 所有写入只发生在候选分支或临时工作区，不直接写 main。
10. RAGFlow 输出隔离
RAGFlow 只作为 agent 执行后端。AgentBridge 必须把 RAGFlow 原始响应转换为 RagflowIterationResult 后再处理。
隔离规则：
- 不把 RAGFlow 私有字段写入
AgentBridgeReport。 - 不信任 RAGFlow 返回的 path、scope、权限声明。
- 不信任 RAGFlow 自称的 evidence，必须验证 citation 可回跳且在 scope 内。
- RAGFlow 不可用时不创建改进 PR。
- RAGFlow 输出缺字段时不写文件。
11. PR 与 ReviewBridge 边界
AgentBridge 只生成候选 diff 和 AgentBridgeReport，PR 治理由 ReviewBridge 完成。
| 事项 | Owner |
|---|---|
| 生成候选 diff | AgentBridge |
| 校验变更合法性 | AgentBridge |
| 创建/更新 PR | ReviewBridge |
| PR body/check/comment | ReviewBridge |
| 合并或批准 PR | 人工维护者 / GitHub 规则 |
| 发布成功态 | DisplayBackend Adapter / Release workflow |
Agent PR body 必须包含 agent 生成声明、taskId、runId、证据摘要、风险和 rejected changes。
12. 状态与持久化
| 数据 | 位置 | owner |
|---|---|---|
IterationTask | workflow state / issue payload | AgentBridge |
ContextPack | transient / run artifact | Agent Access API / AgentBridge |
| candidate diff | PR branch | AgentBridge via ReviewBridge/GitProvider |
AgentBridgeReport | PR body / workflow summary / state artifact | AgentBridge |
| audit log | workflow/service log | AgentBridge |
AgentBridge 不拥有长期内容状态；正式内容仍以 Git main 的 publish/** 为事实源。
13. 幂等与重试
| 场景 | 幂等依据 | 行为 |
|---|---|---|
| 同一 task 重试 | taskId + base files hash | 生成同一候选 diff 或标记并发冲突。 |
| PR 创建重试 | taskId + run payload hash | 由 ReviewBridge upsert PR。 |
| RAGFlow 调用失败重试 | runId 或 retry policy | 不写文件，重试后重新校验全部输出。 |
| partial changes | validated/rejected change list | 只提交 validated changes，rejected 必须报告。 |
| base 变化 | current hash != baseHash | 拒绝 change，不自动 rebase 改写。 |
AgentBridge 不能因为重试而扩大 scope、放宽证据要求或覆盖人工修改。
14. 错误处理
| 错误码 | retryable | 场景 | 处理 |
|---|---|---|---|
agent.task_invalid | false | 任务缺字段、action 不允许、delete 不允许 | 不调用或停止处理。 |
agent.ragflow_output_invalid | false | RAGFlow 输出缺字段或结构非法 | 不写文件。 |
agent.path_out_of_scope | false | change path 越权 | 拒绝该 change。 |
agent.missing_evidence | false | requireCitations 但无证据 | 拒绝该 change。 |
agent.concurrent_change | false | baseHash 与当前 hash 不一致 | 拒绝该 change，报告冲突。 |
agent.patch_apply_failed | false | patch 无法应用 | 拒绝该 change。 |
agent.pr_create_failed | true | ReviewBridge PR 创建失败 | 保留 report，提示重试。 |
adapter.ragflow_unavailable | true | RAGFlow 不可用 | 不创建改进 PR。 |
错误详情必须包含 taskId、runId、path、action；不得包含未授权上下文全文或外部私有响应。
15. 安全与审计
必须审计：
- IterationTask 创建和来源。
- ContextPack 请求和 effective scope。
- RAGFlow 调用成功/失败。
- 每个 accepted/rejected change。
- PR 创建或更新结果。
- 并发冲突、越权路径、缺少证据。
安全规则：
- 默认不允许 delete。
- 默认要求 citation。
- 默认不允许 working docs，除非 task scope 和 policy 显式允许。
- 不允许 agent 修改
config/**或敏感state/**。 - 不允许 agent 输出的事实性内容缺少证据。
- 不允许自动合并 agent PR。
16. 测试要求
| 测试 | Fixture | 预期 |
|---|---|---|
| concurrent change | fixtures/common/agent/concurrent-change.json | 返回 agent.concurrent_change，不覆盖正式内容。 |
| invalid RAGFlow output | fixtures/common/agent/ragflow-invalid-output.json | 返回 agent.ragflow_output_invalid，不创建 ready PR。 |
| forbidden scope | fixtures/common/access/forbidden-scope.json | change 越权被拒绝。 |
| missing evidence | future agent missing evidence fixture | requireCitations 时拒绝 change。 |
| patch apply failed | future agent patch failure fixture | 不 fallback whole-file。 |
| PR report | fixtures/common/review/check-report-blocking.json | ReviewBridge 可生成 failed check。 |
模块验收标准：
IterationTask、RagflowIterationResult、AgentBridgeReport有 schema contract test。- 每个 accepted change 都有 path/scope/baseHash/evidence 校验。
- rejected changes 不静默丢弃。
- 并发冲突不写候选 diff。
- RAGFlow 私有结构不进入公共报告。
17. 设计决策
| 决 策 | 说明 | 取舍 |
|---|---|---|
| AgentBridge 放在 L4 | 避免基础链路依赖 agent，降低复杂度。 | agent 迭代能力必须等待前置契约稳定。 |
| 默认 requireCitations | 降低无证据事实补全风险。 | 对纯格式类任务可能需要显式豁免。 |
| patch 失败不 fallback whole-file | 防止大范围意外覆盖。 | 部分可修复输出需要人工或重新生成。 |
| baseHash 不匹配即拒绝 | 保护人工变更。 | 需要重新触发任务获得最新上下文。 |
| PR 治理交给 ReviewBridge | 保持生成和治理分离。 | 需要稳定 AgentBridgeReport 契约。 |
18. 待确认问题
- 纯格式化或重排类任务是否可以
requireCitations=false。 - AgentBridge 是否支持批量任务，还是 MVP 一次只处理一个 ImprovementTask。
- working docs 迭代是否进入 MVP，还是只允许 main 版本内容。
- high risk change 是否统一阻断 PR，还是允许 draft PR 供人工审查。