契约地图设计

# 契约地图设计

修订记录

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

1. 文档目标

本文定义 kunora-wiki 自研模块之间共享契约的地图，包括契约名称、稳定级别、owner、producer、consumer、持久化位置和变更规则。

本文只定义契约关系，不定义字段明细。字段、类型、版本和兼容策略由 03-data-structures.md 统一定义。

2. 契约分类

分类	说明	典型使用者	变更要求
Public Contract	对前端、外部 agent、workflow 或运维可见的稳定契约	Docusaurus、外部 agent、GitHub workflow、维护者	必须版本化；破坏性变更需要迁移方案和兼容窗口。
Internal Contract	自研模块之间传递的内部契约	ConfigManager、WorkspaceStore、SyncEngine、AgentBridge 等	需要 owner 审批和 contract test；producer/consumer 必须同步更新。
Adapter Contract	自研系统访问外部产品时的隔离契约	GitHub、Docusaurus、RAGFlow、Meilisearch adapter	不能泄漏外部 SDK 私有结构；外部变化必须在 adapter 内吸收。

3. 契约生命周期

生命周期规则：

状态	进入条件	允许使用
Draft	只在设计讨论中出现	不允许实现依赖。
Proposed	已进入本文档，但字段尚未完整定义	允许模块设计引用，不允许实现硬依赖。
Design-Stable	已在 03-data-structures.md 完成字段定义，owner/producer/consumer 清晰，但 schema/fixture 仍待实现	允许作为实现基线和代码生成输入；实现 PR 必须补 schema/fixture 或声明延后原因。
Stable	已有字段定义、fixture、contract test 或 golden case	允许实现依赖和生产使用。
Deprecated	有替代契约，并保留兼容窗口	不允许新增依赖。
Removed	兼容窗口结束	不允许引用。

4. Public Contract 地图

契约	Owner	Producer	Consumer	持久化/入口	状态
AnswerRequest	Answer API	Docusaurus / Agent Access API / 外部调用方	Answer API	POST /answer/ask	Design-Stable
AnswerResult	Answer API	Answer API	Docusaurus、Agent Access API、外部 agent	HTTP response、audit log	Design-Stable
AnswerSession	Answer API	Answer API	Answer API、调用方	session store / short-lived state	Design-Stable
EditContext	WorkspaceStore / DisplayBackend Adapter	WorkspaceStore / DisplayBackend Adapter	Docusaurus、ReviewBridge、IssueTracker	page manifest / Docusaurus metadata	Design-Stable
AgentToolRequest	Agent Access API	外部 agent	Agent Access API	POST /agent/tools/*	Design-Stable
AgentToolResult	Agent Access API	Agent Access API	外部 agent	HTTP response、audit log	Design-Stable
ContextPack	Agent Access API	Agent Access API	外部 agent、AgentBridge	HTTP response / task input	Design-Stable
FeedbackRequest	Agent Access API	Answer API、Agent Access API、前端	Agent Access API FeedbackBridge、IssueTracker	HTTP request / Issue payload	Design-Stable
ImprovementTaskRequest	Agent Access API	Agent Access API、Answer API	IssueTracker、AgentBridge	HTTP request / Issue payload	Design-Stable
PublishImpactReport	DisplayBackend Adapter / ReviewBridge	publish dry-run	ReviewBridge、维护者	state/publish-impact-report.json、PR body	Design-Stable
PageManifest	WorkspaceStore / DisplayBackend Adapter	publish workflow	Docusaurus、Index Adapter、Answer API、Agent Access API	state/page-manifest.json	Design-Stable
PublishManifest	DisplayBackend Adapter	publish workflow	Index Adapter、Answer API、Agent Access API、drift check	state/publish-manifest.json	Design-Stable
SiteManifest	DisplayBackend Adapter	DisplayBackend Adapter	ReviewBridge、drift check、维护者	state/site-manifest.json	Design-Stable
IndexManifest	Index Adapter	Index Adapter	Answer API、Agent Access API、drift check、维护者	state/index-manifest.json	Design-Stable

Public Contract 规则：

• HTTP 契约必须带 schemaVersion 或等价版本标识。
• 对外 response 必须包含可追踪字段，例如 requestId 或 runId。
• 对外错误必须使用标准错误结构，不能直接暴露底层异常。
• manifest 必须记录生成它的 Git commit 或 publish run id。

5. Internal Contract 地图

契约	Owner	Producer	Consumer	持久化/入口	状态
SourceConfig	ConfigManager	ConfigManager	SyncEngine、WorkspaceStore、ReviewBridge	config/sources.yaml	Design-Stable
PublishConfig	ConfigManager	ConfigManager	DisplayBackend Adapter、ReviewBridge	config/publish.yaml	Design-Stable
IndexConfig	ConfigManager	ConfigManager	Index Adapter、Answer API、Agent Access API	config/index.yaml	Design-Stable
RagflowConfig	ConfigManager	ConfigManager	Index Adapter、Answer API、AgentBridge	config/ragflow.yaml	Design-Stable
AgentAccessConfig	ConfigManager	ConfigManager	Agent Access API、Answer API、AgentBridge	config/agent-access.yaml	Design-Stable
ModelPolicy	ConfigManager	ConfigManager	RAGFlow adapter、Answer API、AgentBridge	config/model-policy.yaml	Design-Stable
ConfigBundle	ConfigManager	ConfigManager	所有自研模块	in-memory / validation report	Design-Stable
ConfigImpactReport	ConfigManager	ConfigManager	ReviewBridge、维护者	workflow summary / PR body	Design-Stable
DocumentRecord	WorkspaceStore	WorkspaceStore	SyncEngine、Display、Index、Answer、AgentBridge	in-memory / manifest derivation	Design-Stable
NormalizedPath	WorkspaceStore	WorkspaceStore	所有处理路径的模块	in-memory	Design-Stable
ContentHash	WorkspaceStore	WorkspaceStore	SyncEngine、Index、Display、AgentBridge	state/manifest	Design-Stable
SourceLock	SyncEngine	SyncEngine	SyncEngine、ReviewBridge	state/source-lock.json	Design-Stable
SyncChange	SyncEngine	SyncEngine	ReviewBridge、workflow、tests	state/source-changes.json	Design-Stable
SourceChanges	SyncEngine	SyncEngine	ReviewBridge、维护者	state/source-changes.json	Design-Stable
ReviewReport	ReviewBridge	ReviewBridge	workflow、维护者	PR body / workflow summary	Design-Stable
CheckReport	ReviewBridge	ReviewBridge	GitHub checks、维护者	workflow summary / checks	Design-Stable
FeedbackBridge	Agent Access API	Agent Access API	IssueTracker、AgentBridge、Answer API	in-memory / Issue payload	Design-Stable
IndexDocument	Index Adapter	Index Adapter	RagflowClient、SearchIndexClient	external upsert payload	Design-Stable
SearchResult	Index Adapter / SearchIndexClient	Meilisearch adapter	Agent Access API、Docusaurus search UI	HTTP response / tool result	Design-Stable
IterationTask	AgentBridge	AgentBridge	RAGFlow adapter、AgentBridge	Issue payload / workflow input	Design-Stable
RagflowIterationResult	AgentBridge	RAGFlow adapter	AgentBridge	workflow state / report	Design-Stable
AgentBridgeReport	AgentBridge	AgentBridge	ReviewBridge、维护者	workflow summary / PR body	Design-Stable
AuditEvent	Answer API / Agent Access API / AgentBridge	各调用入口	运维、审计、debug	service log / workflow log	Design-Stable

Internal Contract 规则：

• 每个契约只能有一个 owner。
• producer 负责输出合法性，consumer 负责输入校验和错误处理。
• 持久化契约必须有 schema 和 fixture。
• in-memory 契约也必须有类型定义或等价 schema，不能只靠隐式对象。
• 契约字段变更必须先更新本文档，再更新数据结构文档和测试夹具。

6. Adapter Contract 地图

契约	Owner	Producer	Consumer	外部产品	状态
GitProvider	ReviewBridge / SyncEngine	Git adapter	SyncEngine、ReviewBridge、AgentBridge	GitHub / git CLI	Design-Stable
SourceReader	SyncEngine	source adapter	SyncEngine	GitHub source repos	Design-Stable
ReviewProvider	ReviewBridge	GitHub adapter	ReviewBridge、AgentBridge	GitHub Pull Requests / Checks	Design-Stable
IssueTracker	Agent Access API / AgentBridge	GitHub Issues adapter	Agent Access API、AgentBridge、Answer API	GitHub Issues	Design-Stable
DisplayBackend	DisplayBackend Adapter	Docusaurus adapter	DisplayBackend Adapter	Docusaurus	Design-Stable
RagflowClient	Index Adapter / Answer API / AgentBridge	RAGFlow adapter	Index Adapter、Answer API、AgentBridge	RAGFlow	Design-Stable
SearchIndexClient	Index Adapter / Agent Access API	Meilisearch adapter	Index Adapter、Agent Access API	Meilisearch	Design-Stable
ModelClient	未启用，需 ADR	TBD	TBD	商业 LLM API	Draft

Adapter Contract 规则：

• adapter 返回值必须转换为 common 契约，不允许把外部 SDK response 传给上层模块。
• adapter 错误必须转换为标准错误模型。
• adapter 必须声明幂等策略、重试策略和超时策略。
• adapter 不拥有正式内容状态，只拥有外部调用结果和同步报告。

7. 契约依赖图

8. 契约变更规则

变更类型	示例	要求
Additive	新增可选字段	更新数据结构文档和 fixture；consumer 不得因未知字段失败。
Tightening	可选字段变必填、枚举值收窄	视为破坏性变更，需要版本升级和迁移说明。
Rename	字段改名	视为破坏性变更，必须保留兼容字段或提供迁移。
Semantic Change	字段名不变但含义变化	视为破坏性变更，必须新增字段或版本。
Removal	删除字段或枚举值	必须先 deprecated，再移除。
Producer Change	producer 从 A 模块变成 B 模块	必须更新 contract map、边界设计和测试。
Persistence Change	从 in-memory 变为持久化，或路径变化	必须更新数据结构、路径规则和运维说明。

9. Owner 职责

契约 owner 必须负责：

• 定义契约字段和语义。
• 维护 schema 或类型定义。
• 维护最小 fixture。
• 明确兼容性规则。
• 审核破坏性变更。
• 保证 producer 输出符合契约。

consumer 必须负责：

• 校验输入契约版本。
• 对未知可选字段保持兼容。
• 对缺失必填字段返回标准错误。
• 不依赖未文档化字段。

10. 持久化契约清单

契约	路径	写入模块	读取模块
SourceConfig	config/sources.yaml	人工 PR	ConfigManager
PublishConfig	config/publish.yaml	人工 PR	ConfigManager
IndexConfig	config/index.yaml	人工 PR	ConfigManager
RagflowConfig	config/ragflow.yaml	人工 PR	ConfigManager
AgentAccessConfig	config/agent-access.yaml	人工 PR	ConfigManager
ModelPolicy	config/model-policy.yaml	人工 PR	ConfigManager
SourceLock	state/source-lock.json	SyncEngine	SyncEngine、ReviewBridge
SourceChanges	state/source-changes.json	SyncEngine	ReviewBridge、维护者
PageManifest	state/page-manifest.json	WorkspaceStore / DisplayBackend Adapter	Display、Index、Answer、Agent Access、AgentBridge
EditContext	state/page-manifest.json / Docusaurus metadata	WorkspaceStore / DisplayBackend Adapter	Docusaurus、ReviewBridge、IssueTracker
PublishImpactReport	state/publish-impact-report.json	publish dry-run	ReviewBridge、维护者
PublishManifest	state/publish-manifest.json	publish workflow	Index、Answer、Agent Access、drift check
SiteManifest	state/site-manifest.json	DisplayBackend Adapter	ReviewBridge、drift check
IndexManifest	state/index-manifest.json	Index Adapter	Answer、Agent Access、drift check

持久化契约规则：

• 路径必须由 common 统一定义，模块不能私自换路径。
• 持久化文件必须可被 schema 校验。
• state/manifest 文件必须可重建或可重新生成，不能成为正式内容事实源。
• 配置文件变更必须走 PR。

11. 契约测试要求

每个 Stable 契约至少需要：

• 一个最小合法 fixture。
• 一个包含可选字段的完整 fixture。
• 一个非法 fixture，用于验证错误处理。
• producer golden output。
• consumer contract test。

Public Contract 额外需要：

• 版本兼容测试。
• 标准错误响应测试。
• 未知字段兼容测试。

Adapter Contract 额外需要：

• 外部服务失败映射测试。
• 超时和重试测试。
• 幂等重复调用测试。

12. 实现准入状态

首版 development 文档已经完成 contract map 中核心契约的字段定义，因此这些契约标记为 Design-Stable，可以作为实施基线。

实现阶段必须继续补齐：

1. schemas/** 中的 JSON/YAML schema。
2. fixtures/common/** 中的 valid/invalid fixture。
3. producer/consumer contract test。
4. adapter mock 和错误映射测试。

未完成 schema/fixture 前，契约可以用于代码结构、CLI、workflow 和 adapter 骨架实现；但不能宣称达到生产稳定状态，也不能跳过实现 PR 中的 contract test 任务。