Common 技术设计

# Common 技术设计

修订记录

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

1. 文档目标

development/common 定义 kunora-wiki 自研模块共享的工程基础，包括公共模块、契约、数据结构、错误模型、命名规则、测试夹具和边界约束。

它的目标不是描述 GitHub、Docusaurus、RAGFlow、Meilisearch 等非自研产品如何部署，而是约束自研代码之间如何协作，避免不同模块各自发明字段、状态、错误码和路径规则。

2. 设计边界

2.1 进入 common 的内容

类别	说明	示例
公共类型	多个自研模块共享的数据对象	DocumentRecord、SourceConfig、PageManifestEntry
公共契约	模块之间传递的输入输出协议	SyncChange、AgentBridgeReport、AnswerResult
公共规则	所有模块必须遵守的规则	路径规范化、内容 hash、幂等 key、错误结构
公共适配接口	自研模块访问外部产品时的最小接口	GitProvider、RagflowClient、SearchIndexClient
公共测试夹具	验证协议和边界的样例数据	source fixtures、publish fixtures、manifest fixtures

2.2 不进入 common 的内容

类别	原因	归属
GitHub 常规分支保护配置	产品实施，不是自研契约	product / operations
Docusaurus 常规站点配置	展示产品实施，不是公共代码契约	product / frontend implementation
RAGFlow 常规部署和模型配置	外部产品实施	product / operations
Meilisearch 常规部署	外部产品实施	product / operations
具体业务页面内容	内容资产，不是工程契约	publish/**
模块内部私有算法	不被多个模块共享	对应模块设计文档

2.3 非自研模块进入 development 的条件

非自研模块只有满足以下任一条件时，才进入 development 设计：

• 自研代码需要封装它的 API，并稳定调用契约。
• 自研代码需要转换它的响应为 LLM-WIKI 标准数据结构。
• 自研代码需要处理它的错误、重试、幂等或回滚语义。
• 我们对它做二次开发、插件开发或定制扩展。
• 它的行为会影响 Git 中的正式内容、manifest、索引状态或审计记录。

3. 自研模块地图

模块	是否自研	common 关注点
ConfigManager	是	配置对象、schema 校验、配置影响报告。
WorkspaceStore	是	路径规范化、内容 hash、文件读写边界、manifest 读写。
SyncEngine	是	三方 diff 输入输出、同步状态、冲突结构。
ReviewBridge	是	PR payload、状态检查、报告格式。
Display Adapter	是	publish/** 到展示输入的转换契约、site manifest。
Index Adapter	是	索引文档结构、delete/upsert 幂等、index manifest。
Answer API	是	标准请求、标准响应、引用标准化、无答案结构。
Agent Access API	是	tool contract、scope、policy、audit、反馈幂等。
AgentBridge	是	任务结构、RAGFlow 输出校验、Git diff/PR 报告。
GitHub	否	只通过 GitProvider / ReviewProvider 进入自研契约。
Docusaurus	否	只通过 DisplayBackend adapter 进入自研契约。
RAGFlow	否	只通过 RagflowClient 和标准 answer/iteration 结构进入自研契约。
Meilisearch	否	只通过 SearchIndexClient 进入自研契约。

4. Common 文档规划

文档	目标	状态
README.md	common 范围、边界和文档路线	已创建
01-module-boundaries.md	自研模块边界、依赖方向、禁止依赖	已创建
02-contract-map.md	模块间契约清单、owner、producer、consumer	已创建
03-data-structures.md	核心数据结构字段、版本和兼容规则	已创建
04-error-and-status-model.md	错误码、状态码、失败处理和重试语义	已创建
05-path-hash-and-id.md	路径规范化、hash、documentId、dedupeKey 规则	已创建
06-fixtures-and-tests.md	公共 fixtures、contract tests、golden tests	已创建

5. 契约分层

Common 契约按稳定程度分三层：

层级	稳定性	使用者	变更要求
Public Contract	最高	API 调用方、workflow、外部 agent	必须版本化，破坏性变更需要迁移方案。
Internal Contract	中等	自研模块之间	需要 contract test，字段变更要同步 producer/consumer。
Adapter Contract	中等	自研 adapter 与外部产品	需要隔离外部产品差异，不能泄漏供应商私有结构。

Public Contract 包括：

• Answer API request/response。
• Agent Access tool request/response。
• feedback / improvement task 创建结果。
• 发布和索引 manifest 中对外可消费的字段。

Internal Contract 包括：

• SourceConfig。
• ConfigBundle。
• DocumentRecord。
• SyncChange。
• SourceLock。
• SourceChanges。
• PublishImpactReport。
• PageManifest。
• IndexManifest。
• IterationTask。
• AgentBridgeReport。

Adapter Contract 包括：

• GitProvider。
• ReviewProvider。
• DisplayBackend。
• RagflowClient。
• SearchIndexClient。
• IssueTracker。

6. 设计不变量

• publish/** 是自研模块处理正式文档工作区的唯一受控目录。
• Git 中的已审批内容是正式内容事实源；外部产品不能成为正式内容事实源。
• 所有跨模块对象必须有明确 owner，不能出现多模块各自定义同名字段。
• 所有可重试写入必须有幂等 key 或由 documentId + contentHash 等稳定键约束。
• 所有外部调用结果必须转换为 LLM-WIKI 标准结构后再进入内部流程。
• 所有失败必须可审计：至少包含 requestId 或 runId、模块名、错误码、上下文和可操作建议。
• 调用方声明的 scope 只能作为请求，授权事实必须来自服务端 policy。

7. 当前状态与后续准入

Common 技术设计已完成首版闭环：

1. 01-module-boundaries.md：模块边界和依赖方向已定义。
2. 02-contract-map.md：producer、consumer、owner 和变更规则已定义。
3. 03-data-structures.md：核心数据结构字段和兼容规则已定义。
4. 04-error-and-status-model.md：错误码、状态、降级和重试语义已定义。
5. 05-path-hash-and-id.md：路径、hash、ID、幂等和去重规则已定义。
6. 06-fixtures-and-tests.md：公共 fixture、contract test 和 golden test 要求已定义。

进入实现前，模块设计必须满足以下准入要求：

• 明确引用自己消费和生产的 common 契约。
• 不新增第二套路径、hash、ID、错误码或状态模型。
• 对写入类操作说明幂等和并发冲突处理。
• 对外部产品调用说明 adapter contract 和错误映射。
• 对 Public Contract 和跨模块 Internal Contract 说明对应 fixture / contract test。