RAGFlow 实施方案

# RAGFlow 实施方案

修订记录

版本	日期	修订说明
v0.1	2026-05-01	建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。

1. 文档目标

本文定义 kunora-docs 中 RAGFlow 的产品侧实施方案。RAGFlow 是非自研问答和迭代上下文产品，负责承载 approved/working 两类 dataset；自研系统只通过 RagflowClient adapter 调用它。

2. 核心契约

main/publish/** + publish/page manifest -> Index Adapter -> llm-wiki-approved
working context / task scope -> Index Adapter or AgentBridge -> llm-wiki-working
Answer API -> RagflowClient -> approved dataset
AgentBridge -> RagflowClient -> working dataset

规则：

• 正式问答默认只使用 llm-wiki-approved。
• AgentBridge 只能在授权 scope 内使用 llm-wiki-working。
• RAGFlow dataset 不是内容事实源，不能反向覆盖 publish/**。
• 所有 RAGFlow 写入结果必须进入 state/index-manifest.json。

3. 配置契约

config/ragflow.yaml 必须包含：

字段	要求
schemaVersion	必填。
endpointRef	指向 secret/variable，不保存明文 endpoint token。
datasets[]	必须至少包含 approved 和 working。
datasets[].id	内部 ID，例如 llm-wiki-approved。
datasets[].externalDatasetId	RAGFlow 外部 dataset 引用。
datasets[].purpose	qa、index、iteration 或 working。
timeoutSeconds	可选。
retry	可选。

GitHub Secrets / Variables：

名称	用途
RAGFLOW_API_KEY	RAGFlow API 调用。
RAGFLOW_APPROVED_DATASET	approved dataset 外部 ID 或引用。
RAGFLOW_WORKING_DATASET	working dataset 外部 ID 或引用。

4. Dataset 语义

Dataset	内容来源	消费者	失败影响
llm-wiki-approved	已审批、qaVisible=true、可索引的正式文档	Answer API、正式 ask 工具	阻断正式问答新索引；可降级到上一版成功 manifest。
llm-wiki-working	允许迭代的工作区文档、任务上下文、冲突处理材料	AgentBridge、受控 agent 工具	只阻断对应迭代任务，不影响正式问答。

禁止：

• 用 working dataset 回答正式用户问题。
• 用 RAGFlow 返回内容直接修改 publish/**。
• 把 RAGFlow 外部 chunk ID 当作 LLM-WIKI 主 ID。

5. Workflow 落地

RAGFlow 写入归入 docs-index.yml。

步骤	输入	输出
validate config	config/ragflow.yaml、Secrets/Variables	config check。
build approved documents	publish/page/publish manifest	approved IndexDocument[]。
upsert/delete approved	approved target	target operation report。
build working documents	task/workspace scope	working IndexDocument[]。
upsert/delete working	working target	target operation report。
write manifest	target reports	state/index-manifest.json。

6. 失败处理

场景	处理
RAGFlow config 无效	阻断 docs-index.yml。
approved target 不可用	target failed，Answer API 使用上一版成功索引或返回索引不可用。
approved 部分文档失败	target partial，失败文档不得用于正式问答。
working target 失败	阻断对应 AgentBridge 任务，不阻断正式发布。
delete 失败	target partial，必须在 ReviewBridge summary 中列出。

7. 完成定义

1. config/ragflow.yaml 能区分 approved 和 working dataset。
2. docs-index.yml 能写入 approved dataset 并生成 target status。
3. docs-index.yml 能写入 working dataset，且不污染正式问答。
4. state/index-manifest.json 记录两个 dataset 的状态。
5. Answer API 默认只读取 approved dataset。
6. AgentBridge 读取 working dataset 后，输出只能进入 Release PR。
7. RAGFlow token 不出现在日志、manifest、PR body 或 Issue。