自研模块边界设计
# 自研模块边界设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 文档目标
本文定义 kunora-wiki 自研模 块的边界、依赖方向和禁止依赖。
它解决的问题是：后续模块级设计和实现时，不能因为方便调用而让模块互相穿透、重复定义状态、绕过 Git 治理，或让外部产品成为正式内容事实源。
本文不定义字段级 schema。字段、版本和兼容规则由后续 03-data-structures.md 统一定义。
2. 边界原则
| 原则 | 约束 |
|---|---|
| 单一 owner | 每个核心对象只能有一个模块 owner，其他模块只能读取或消费。 |
| 依赖向下 | 上层业务编排可以依赖底层公共能力，底层模块不能反向依赖上层流程。 |
| 外部隔离 | GitHub、Docusaurus、RAGFlow、Meilisearch 只能通过 adapter/client 接口进入自研模块。 |
| Git 治理不可绕过 | 任何影响正式内容的写入都必须形成 Git diff 和 PR。 |
| 状态可重建 | manifest 和 state 是可审计状态，不是正式内容事实源。 |
| 失败显式化 | 模块不能吞掉失败，必须返回标准错误或报告。 |
| 不共享私有结构 | 模块之间不能消费彼此的内部临时对象，只能消费 common contract。 |
3. 模块层级
层级规则：
| 层级 | 模块 | 规则 |
|---|---|---|
| L0 | ConfigManager、WorkspaceStore | 只提供配置、路径、内容、state/manifest 基础能力，不调用上层模块。 |
| L1 | SyncEngine、ReviewBridge | 负责同步判断和 GitHub 治理桥接，不调用问答或智能体。 |
| L2 | DisplayBackend Adapter、Index Adapter | 只消费已审批或可发布内容，生成展示/索引产物和 manifest。 |
| L3 | Answer API、Agent Access API | 只通过标准索引、manifest 和 policy 提供访问，不写正式内容。 |
| L4 | AgentBridge | 只把任务和 agent 输出转成 Git diff/Release PR，不直接发布。 |
4. 模块边界总表
| 模块 | Owner 对象 | 主要输入 | 主要输出 | 禁止事项 |
|---|---|---|---|---|
| ConfigManager | ConfigBundle、配置影响报告 | config/*.yaml | 已校验配置、影响报告 | 不读取或写入 publish/** 内容；不调用外部产品。 |
| WorkspaceStore | DocumentRecord、路径/hash 工具、manifest 读写 | publish/**、state/** | 标准化文档记录、内容 hash、manifest 文件 | 不执行同步决策；不创建 PR；不调用 RAGFlow/Meilisearch。 |
| SyncEngine | SyncChange、SourceLock、SourceChanges | SourceConfig、来源文件、当前 publish、source lock | 同步变更、冲突报告、更新后的 publish/state | 不自动解决冲突；不触发发布；不调用智能体。 |
| ReviewBridge | PR payload、review report、check report | sync/release 变更报告、影响报告 | Sync PR、Release PR、workflow summary/checks | 不判 断文档语义正确性；不直接改内容。 |
| DisplayBackend Adapter | display input、SiteManifest | publish/**、page/publish manifest | Docusaurus 输入、sidebar、site manifest | 不保存正式内容；不作为编辑入口事实源。 |
| Index Adapter | index document、IndexManifest | publish/page manifest、approved documents | RAGFlow dataset 同步、Meilisearch index 同步、index manifest | 不生成答案；不修改 Git 内容。 |
| Answer API | AnswerResult、AnswerSession | question、scope、caller、RAGFlow answer、manifest | 标准答案、引用、无答案动作、审计记录 | 不实现第二套 RAG；不越权扩大 scope。 |
| Agent Access API | tool request/response、policy、audit、ContextPack、FeedbackBridge | agent token、tool request、scope、manifest/index | tool 响应、反馈/任务请求、IssueTracker payload、审计记录 | 不直接生成事实答案；不直接写 publish/**。 |
| AgentBridge | IterationTask、AgentBridgeReport | Issue/人工任务、RAGFlow 迭代输出、workspace state | Git diff、Release PR、校验报告 | 不批准/合并 PR；不允许无证据事实补全。 |
5. 允许依赖
5.1 ConfigManager
允许被以下模块依赖：
- SyncEngine
- WorkspaceStore
- ReviewBridge
- DisplayBackend Adapter
- Index Adapter
- Answer API
- Agent Access API
- AgentBridge
ConfigManager 自身只依赖文件系统和 schema 校验能力。
5.2 WorkspaceStore
允许被以下模块依赖：
- SyncEngine
- ReviewBridge
- DisplayBackend Adapter
- Index Adapter
- Answer API
- Agent Access API
- AgentBridge
WorkspaceStore 可以读取和写入受控目录：
publish/**state/**- 后续约定的 generated manifest 目录
WorkspaceStore 不允许直接访问外部产品。
5.3 SyncEngine
允许依赖：
- ConfigManager
- WorkspaceStore
- GitProvider 或 SourceReader adapter
允许被依赖：
- ReviewBridge
- workflow command
SyncEngine 不允许依赖：
- ReviewBridge
- DisplayBackend Adapter
- Index Adapter
- Answer API
- Agent Access API
- AgentBridge
5.4 ReviewBridge
允许依赖：
- ConfigManager
- WorkspaceStore
- GitProvider
- ReviewProvider
允许被依赖：
- Sync workflow
- AgentBridge
- publish dry-run workflow
ReviewBridge 是 GitHub 治理边界，不是内容判断模块。
5.5 DisplayBackend Adapter
允许依赖：
- ConfigManager
- WorkspaceStore
- DisplayBackend adapter interface
允许被依赖：
- publish workflow
- ReviewBridge 的影响报告输入
DisplayBackend Adapter 不允许依赖 Answer API 或 Agent Access API。页面内问答挂载点只能消费已稳定的 endpoint 配置，不能调用问答服务生成内容。
5.6 Index Adapter
允许依赖：
- ConfigManager
- WorkspaceStore
- RagflowClient
- SearchIndexClient
允许被依赖：
- publish/index workflow
- Answer API
- Agent Access API
Index Adapter 只负责索引同步状态，不提供业务问答。
5.7 Answer API
允许依赖：
- ConfigManager
- WorkspaceStore
- RagflowClient
- manifest reader
- policy reader
允许被依赖：
- Docusaurus 页面问答组件
- Agent Access API 的
ask工具
Answer API 不允许依赖 AgentBridge。无答案只能生成反馈动作或任务请求，不能直接触发文档修改。
5.8 Agent Access API
允许依赖：
- ConfigManager
- WorkspaceStore
- Answer API
- Index Adapter 的查询接口或 SearchIndexClient
- IssueTracker
- policy reader
允许被依赖：
- 外部智能体
- 内部 agent workflow
Agent Access API 的写入类工具只能通过内部 FeedbackBridge 创建反馈、Issue、改进任务或 PR 草稿请求，不能直接写正式内容。GitHub Issues API 细节必须由 IssueTracker adapter 隔离。
5.9 AgentBridge
允许依赖：
- ConfigManager
- WorkspaceStore
- ReviewBridge
- RagflowClient
- IssueTracker
允许被依赖：
- agent iteration workflow
- 人工触发命令
AgentBridge 不允许依赖 Answer API 来生成待写入内容。它可以消费引用、manifest 和任务上下文，但文档改写建议必须来自明确的 iteration result，并通过校验后进入 PR。
6. 禁止依赖矩阵
| 禁止依赖 | 原因 |
|---|---|
| WorkspaceStore -> SyncEngine | 会让基础存储层包含同步策略，破坏可复用性。 |
| WorkspaceStore -> ReviewBridge | 会让文件读写隐式创建 PR，破坏显式治理。 |
| SyncEngine -> AgentBridge | 同步阶段不能触发智能体改写。 |
| SyncEngine -> DisplayBackend Adapter | 同步不负责展示发布。 |
| SyncEngine -> Index Adapter | 同步不负责索引。 |
| DisplayBackend Adapter -> Answer API | 展示构建不能依赖问答服务可用性。 |
| Index Adapter -> Answer API | 索引不生成答案。 |
| Answer API -> AgentBridge | 问答失败不能直接改文档，只能产生反馈或任务。 |
| Agent Access API -> WorkspaceStore direct write | 智能体访问层不能绕过 ReviewBridge 和 AgentBridge 写内容。 |
| AgentBridge -> main branch direct write | 智能体迭代结果必须进入 Release PR。 |
| 任意模块 -> 外部产品 SDK 私有结构 | 外部差异必须被 adapter contract 隔离。 |
7. 外部产品边界
| 外部产品 | 进入自研系统的唯一方式 | 自研侧标准化对象 |
|---|---|---|
| GitHub | GitProvider、ReviewProvider、IssueTracker | PR payload、Issue payload、check report、review report |
| Docusaurus | DisplayBackend adapter | display input、site manifest、page URL mapping |
| RAGFlow | RagflowClient | answer result、citation、iteration result、dataset sync result |
| Meilisearch | SearchIndexClient | search document、search result、index sync result |
| 商业 LLM API | RAGFlow 优先管理；控制面直连时需独立 ModelClient ADR | model call result、usage、error |
默认规则：非自研产品的原始响应不能跨模块传播。adapter 必须在边界处转 换成 common contract。
8. 内容与状态边界
| 对象 | 事实源 | 可写模块 | 可读模块 |
|---|---|---|---|
| 正式文档内容 | Git main 上的 publish/** | SyncEngine、AgentBridge、人工 PR，经 ReviewBridge 治理 | 所有需要读取文档的模块 |
| source lock | state/source-lock.json | SyncEngine | SyncEngine、WorkspaceStore、ReviewBridge |
| source changes | state/source-changes.json | SyncEngine | ReviewBridge、维护者、测试 |
| page manifest | state/page-manifest.json | WorkspaceStore / Display Adapter | Display、Index、Answer、Agent Access、AgentBridge |
| publish manifest | state/publish-manifest.json | publish workflow / Display Adapter | Index、Answer、Agent Access、drift check |
| site manifest | state/site-manifest.json | DisplayBackend Adapter | ReviewBridge、drift check |
| index manifest | state/index-manifest.json | Index Adapter | Answer、Agent Access、drift check |
| audit log | 对应服务或 workflow | Answer API、Agent Access API、AgentBridge | 运维、审计、debug |
状态文件不是正式内容事实源。状态文件丢失时，系统应能从 Git 内容、配置和外部服务状态尽量重建或重新生成。
9. PR 治理边界
所有影响正式内容的变更必须满足：
- 变更表现为 Git diff。
- 变更进入非 main 分支。
- ReviewBridge 创建或更新 PR。
- PR body 包含来源、原因、风险、影响范围和验证结果。
- 合并后才允许发布、展示、索引和问答正式消费。
以下行为禁止：
- 同步任务直接 push
main。 - AgentBridge 直接 push
main。 - Answer API 或 Agent Access API 直接修改
publish/**。 - Docusaurus 后台编辑受管页面。
- RAGFlow 直接关闭 GitHub Issue 或标记文档已发布。
10. 模块设计检查清单
后续每个模块设计必须回答：
- 本模块 owner 哪些对象？
- 本模块读取哪些对象？
- 本模块写入哪些对象？
- 本模块依赖哪些 common contract？
- 本模块可以调用哪些 adapter？
- 本模块不能调用哪些模块？
- 本模块失败时返回什么错误或报告？
- 本模块如何保证幂等和可重试？
- 本模块如何证明没有绕过 Git 治理？
如果模块设计无法回答以上问题，不应进入实现。