公共数据结构设计

# 公共数据结构设计

修订记录

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

1. 文档目标

本文定义 kunora-wiki 自研模块共享的数据结构字段、必填性、语义和兼容规则。

本文基于：

• 01-module-boundaries.md
• 02-contract-map.md
• 05-path-hash-and-id.md

本文只定义公共数据结构。模块内部临时对象应放在对应模块设计文档中，不进入 common。

2. 通用字段规则

字段	类型	必填	说明
schemaVersion	string	持久化和 public contract 必填	语义版本或日期版本，MVP 默认 1.0。
createdAt	string	持久化对象建议必填	UTC ISO-8601。
updatedAt	string	可选	UTC ISO-8601。
runId	RunId	workflow/report 类对象必填	关联一次运行。
requestId	RequestId	API response/audit 必填	关联一次请求。
errors	ErrorObject[]	可选	标准错误对象，详见后续错误模型文档。

兼容规则：

• consumer 必须忽略未知可选字段。
• producer 不得删除已发布 contract 的必填字段，除非版本升级。
• 枚举新增值是兼容变更，但 consumer 必须有 unknown fallback。
• 字段名使用 lower camel case。
• 路径、hash、ID 类型必须复用 05-path-hash-and-id.md。

3. 基础类型

类型	运行时表示	规则
NormalizedPath	string	使用 /，无绝对路径，无 ..，具体规则见路径文档。
ContentHash	string	sha256:<hex>。
DocumentId	string	doc:<sha256(normalized publishPath)>。
RunId	string	run:<kind>:<yyyyMMddTHHmmssZ>:<short-random>。
RequestId	string	req:<yyyyMMddTHHmmssZ>:<random>。
PublishRunId	string	pub:<yyyyMMddTHHmmssZ>:<gitShortSha>:<short-random>。
AuditId	string	audit:<yyyyMMddTHHmmssZ>:<random>。
TaskId	string	task:<source>:<external-or-hash>。
DedupeKey	string	dedupe:<eventType>:<sha256(canonical payload)>。
IdempotencyKey	string	idem:<callerId>:<sha256(canonical request payload)>。
SiteUrl	string	站点相对 URL，以 / 开头。
Anchor	string	页面内锚点，可选。

4. 配置结构

4.1 SourceConfig

Owner：ConfigManager。

持久化路径：config/sources.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
sources	SourceEntry[]	是	来源项目列表。

SourceEntry：

字段	类型	必填	说明
id	string	是	source 唯一 ID。
repo	string	是	GitHub repo，例如 owner/name。
ref	string	是	来源 ref，默认建议 docs-publish。
sourcePath	NormalizedPath	是	来源仓库内文档目录或 glob 根。
publishPath	NormalizedPath	是	目标目录，必须位于 publish/**。
include	string[]	否	include glob。
exclude	string[]	否	exclude glob。
deletePolicy	enum	否	sync-if-unmodified、report-only、never。
conflictPolicy	enum	否	MVP 默认 report-only。
enabled	boolean	否	默认 true。

校验规则：

• id 唯一。
• publishPath 唯一。
• 不同 publishPath 不能互为父子目录。
• publishPath 必须以 publish/ 开头。
• sourcePath 不能指向仓库根目录，除非显式允许。

4.2 PublishConfig

Owner：ConfigManager。

持久化路径：config/publish.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
backend	enum	是	MVP 为 docusaurus。
site	PublishSiteConfig	是	展示站 URL、baseUrl 和路由配置。
managedPath	NormalizedPath	是	通常为 publish/。
websitePath	NormalizedPath	是	Docusaurus 项目路径，MVP 默认 website/。
generatedDocsPath	NormalizedPath	是	从 publish/** 生成的 Docusaurus docs 输入目录，MVP 默认 website/docs/。
buildOutputPath	NormalizedPath	是	展示构建产物目录，MVP 默认 website/build/。
editUrlBase	string	是	GitHub 编辑或 PR 入口基础 URL，不得包含 secret。
cacheWindowSeconds	number	否	删除页面缓存窗口。

PublishSiteConfig：

字段	类型	必填	说明
url	string	是	展示站正式域名，例如 https://docs.example.com。
baseUrl	string	是	站点路径前缀，例如 / 或 /wiki/。
routeBasePath	string	是	Docusaurus docs 路由根，例如 / 或 /docs/。

兼容规则：

• site.url + site.baseUrl + PageManifestEntry.url 必须能组成稳定页面 URL。
• generatedDocsPath 不得等于 managedPath，避免 Docusaurus 输入目录成为内容事实源。
• managedPath 必须位于 publish/** 或等于 publish/。
• 旧版顶层 baseUrl 不再作为首选字段；实现阶段如需兼容，只能映射到 site.baseUrl，不得与 site.baseUrl 冲突。

4.3 IndexConfig

Owner：ConfigManager。

持久化路径：config/index.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
targets	IndexTargetConfig[]	是	索引目标。

IndexTargetConfig：

字段	类型	必填	说明
id	string	是	例如 ragflow-approved、meilisearch。
type	enum	是	ragflow 或 meilisearch。
enabled	boolean	否	默认 true。
dataset	string	条件必填	RAGFlow dataset。
indexName	string	条件必填	Meilisearch index。
includeQualityStatus	string[]	否	可索引页面状态。

4.4 RagflowConfig

Owner：ConfigManager。

持久化路径：config/ragflow.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
endpointRef	string	是	RAGFlow endpoint 引用，不保存明文 secret。
datasets	RagflowDatasetConfig[]	是	可用 dataset。
timeoutSeconds	number	否	调用超时。
retry	object	否	重试策略引用。

RagflowDatasetConfig：

字段	类型	必填	说明
id	string	是	内部 dataset ID。
externalDatasetId	string	是	RAGFlow dataset ID 或引用。
purpose	enum	是	qa、index、iteration、working。
enabled	boolean	否	默认 true。

4.5 ModelPolicy

Owner：ConfigManager。

持久化路径：config/model-policy.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
policies	ModelPolicyEntry[]	是	按用途定义模型策略。

ModelPolicyEntry：

字段	类型	必填	说明
purpose	enum	是	answer、iteration、summary、classification。
provider	string	是	模型供应商或 adapter ID。
model	string	是	模型名。
fallbackModels	string[]	否	降级模型列表。
maxTokens	number	否	输出 token 上限。
temperature	number	否	采样温度。

4.6 AgentAccessConfig

Owner：ConfigManager。

持久化路径：config/agent-access.yaml。

字段	类型	必填	说明
schemaVersion	string	是	配置 schema 版本。
agents	AgentPolicy[]	是	agent policy 列表。

AgentPolicy：

字段	类型	必填	说明
agentId	string	是	agent identity。
allowedTools	string[]	是	允许工具集合。
allowedPaths	NormalizedPath[]	是	允许访问路径前缀。
allowedDatasets	string[]	是	允许 dataset。
writePermissions	string[]	否	例如 create_feedback、create_improvement_task。
includeWorkingDocs	boolean	否	默认 false。

4.7 ConfigBundle

Owner：ConfigManager。

运行时对象，不直接持久化。

字段	类型	必填	说明
schemaVersion	string	是	bundle schema 版本。
sources	SourceEntry[]	是	已校验来源配置。
publish	PublishConfig	是	已校验发布配置。
index	IndexConfig	是	已校验索引配置。
ragflow	RagflowConfig	是	已校验 RAGFlow dataset 和连接引用。
agentAccess	AgentAccessConfig	是	已校验 agent access 配置。
modelPolicy	ModelPolicy	是	已校验模型策略。
configHash	ContentHash	是	canonical bundle hash。
warnings	string[]	否	非阻塞配置警告。

4.8 ConfigImpactReport

Owner：ConfigManager。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
reportId	RunId	是	report run id。
baseConfigHash	ContentHash	否	变更前配置 hash。
headConfigHash	ContentHash	是	变更后配置 hash。
impactLevel	enum	是	none、low、medium、high、blocking。
changedFiles	NormalizedPath[]	是	变更配置文件。
changedKeys	string[]	否	变更配置键。
requiresManualReview	boolean	是	是否需要人工确认。
warnings	string[]	否	非阻断警告。
errors	ErrorObject[]	否	阻断错误。

5. 工作区结构

5.1 DocumentRecord

Owner：WorkspaceStore。

字段	类型	必填	说明
documentId	DocumentId	是	基于 publishPath 生成。
publishPath	NormalizedPath	是	publish/** 文件路径。
contentHash	ContentHash	是	规范化 Markdown hash。
title	string	否	从 frontmatter 或 H1 提取。
frontmatter	object	否	解析后的 frontmatter。
sourceId	string	否	来源 ID。
sourceProject	string	否	产品侧展示名或来源项目名。
sourcePath	NormalizedPath	否	来源仓库内路径。
sourceRef	string	否	来源 ref。
sourceCommit	string	否	来源 commit。
siteUrl	SiteUrl	否	展示 URL。
qualityStatus	enum	否	默认 unknown。
qaVisible	boolean	否	是否进入正式问答。
indexable	boolean	否	是否进入索引。
feedbackOpen	number	否	未关闭反馈数量。
hasSourceConflict	boolean	否	是否存在来源同步冲突。
indexStatus	enum	否	not-indexed、indexed、partial、failed、stale。
lastApprovedAt	string	否	最近审批时间，UTC ISO-8601。
relatedIssues	number[]	否	关联 GitHub issue。
relatedPullRequests	number[]	否	关联 GitHub PR。

qualityStatus MVP 枚举：

• approved
• needs-review
• stale
• conflict
• feedback-open
• unknown

6. 同步结构

6.1 SourceLock

Owner：SyncEngine。

持久化路径：state/source-lock.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
updatedAt	string	是	UTC ISO-8601。
sources	map<string, SourceLockEntry>	是	key 为 sourceId。

SourceLockEntry：

字段	类型	必填	说明
repo	string	是	来源 repo。
ref	string	是	来源 ref。
commit	string	否	上次成功同步 commit。
files	map<NormalizedPath, SourceFileLock>	是	key 为 source repo path。

SourceFileLock：

字段	类型	必填	说明
sourceHash	ContentHash	是	来源文件 hash。
sourcePath	NormalizedPath	是	来源文件路径。
publishPath	NormalizedPath	是	目标路径。
lastSyncedAt	string	是	UTC ISO-8601。
deleted	boolean	否	tombstone 标记。

6.2 SyncChange

Owner：SyncEngine。

字段	类型	必填	说明
sourceId	string	是	来源 ID。
sourcePath	NormalizedPath	是	来源文件路径。
publishPath	NormalizedPath	是	目标路径。
action	enum	是	同步动作。
reason	string	是	机器可读原因。
baseHash	ContentHash	否	A hash。
sourceHash	ContentHash	否	B hash。
publishHash	ContentHash	否	C hash。
conflictType	enum	条件必填	action 为 conflict 时必填。
message	string	否	人类可读说明。

action 枚举：

• add
• update
• delete
• unchanged
• keep
• conflict
• delete_conflict
• keep_local
• report_delete

6.3 SourceChanges

Owner：SyncEngine。

持久化路径：state/source-changes.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
runId	RunId	是	sync run id。
createdAt	string	是	UTC ISO-8601。
sources	SourceChangeSet[]	是	按 source 分组。
summary	SyncSummary	是	汇总数量。
errors	ErrorObject[]	否	同步错误。

SourceChangeSet：

字段	类型	必填	说明
sourceId	string	是	来源 ID。
changes	SyncChange[]	是	变更列表。
conflicts	SyncChange[]	否	冲突列表，可从 changes 派生但允许冗余。

7. Manifest 结构

7.1 PageManifest

Owner：WorkspaceStore / DisplayBackend Adapter。

持久化路径：state/page-manifest.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
generatedAt	string	是	UTC ISO-8601。
gitCommit	string	是	生成时 Git commit。
pages	PageManifestEntry[]	是	页面列表。

PageManifestEntry：

字段	类型	必填	说明
documentId	DocumentId	是	文档 ID。
path	NormalizedPath	是	publishPath。
url	SiteUrl	否	展示 URL。
title	string	否	页面标题。
contentHash	ContentHash	是	Markdown 内容 hash。
sourceId	string	否	来源 ID。
sourceProject	string	否	产品侧展示名或来源项目名。
sourceRef	string	否	来源 ref。
sourceCommit	string	否	来源 commit。
qualityStatus	enum	是	页面质量状态。
qaVisible	boolean	是	是否可问答。
indexable	boolean	是	是否可索引。
feedbackOpen	number	否	未关闭反馈数量。
hasSourceConflict	boolean	否	是否存在来源同步冲突。
indexStatus	enum	否	not-indexed、indexed、partial、failed、stale。
lastApprovedAt	string	否	最近审批时间，UTC ISO-8601。
relatedIssues	number[]	否	关联 GitHub issue。
relatedPullRequests	number[]	否	关联 GitHub PR。
editContext	EditContext	否	编辑入口上下文。

7.2 PublishImpactReport

Owner：DisplayBackend Adapter / ReviewBridge。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
reportId	RunId	是	report run id。
publishRunId	PublishRunId	否	发布 run id，PR dry-run 时可为空。
baseRef	string	是	base ref。
headRef	string	是	head ref。
changedPages	ChangedPage[]	是	影响页面。
build	BuildSummary	否	构建 dry-run 结果。
errors	ErrorObject[]	否	错误列表。

ChangedPage：

字段	类型	必填	说明
path	NormalizedPath	是	页面路径。
action	enum	是	add、update、delete、rename。
url	SiteUrl	否	页面 URL。
sourceProject	string	否	来源项目。
affectedIndexes	string[]	否	受影响索引。
relatedIssues	number[]	否	关联 issue。

7.3 EditContext

Owner：WorkspaceStore / DisplayBackend Adapter。

EditContext 是 Docusaurus 编辑入口、Issue 创建和 PR 模板使用的页面上下文。它不是内容事实源，只从 Git、PageManifest、Issue/PR 关系和配置派生。

字段	类型	必填	说明
pagePath	NormalizedPath	是	页面路径。
editUrl	string	是	GitHub 编辑或 PR 入口 URL。
sourceProject	string	否	来源项目展示名。
sourceRef	string	否	来源 ref。
sourceCommit	string	否	来源 commit。
lastApprovedCommit	string	否	最近审批 commit。
relatedPages	PageRef[]	否	相关页面。
relatedIssues	number[]	否	关联 issue。
relatedPullRequests	number[]	否	关联 PR。
qualityStatus	enum	是	页面质量状态。
expectedChangeIntent	enum	否	fix、add、restructure、update-version。

7.4 PublishManifest

Owner：DisplayBackend Adapter。

持久化路径：state/publish-manifest.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
publishRunId	PublishRunId	是	发布 run id。
publishedAt	string	是	UTC ISO-8601。
gitCommit	string	是	发布读取的 commit。
pages	PublishPage[]	是	发布页面。

PublishPage：

字段	类型	必填	说明
documentId	DocumentId	是	文档 ID。
path	NormalizedPath	是	publishPath。
contentHash	ContentHash	是	Markdown 内容 hash。
url	SiteUrl	是	展示 URL。
qualityStatus	enum	是	页面质量状态。
qaVisible	boolean	是	是否可问答。
indexable	boolean	是	是否可索引。

7.5 SiteManifest

Owner：DisplayBackend Adapter。

持久化路径：state/site-manifest.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
publishRunId	PublishRunId	是	发布 run id。
publishedAt	string	是	UTC ISO-8601。
gitCommit	string	是	构建来源 commit。
pages	SitePage[]	是	站点页面。

SitePage：

字段	类型	必填	说明
documentId	DocumentId	是	文档 ID。
path	NormalizedPath	是	publishPath。
url	SiteUrl	是	展示 URL。
sourceHash	ContentHash	是	对应 publish contentHash。
renderedHash	ContentHash	否	渲染产物 hash。
status	enum	是	published、missing、redirected、failed。
httpStatus	number	否	HTTP 状态。
expectedStatus	number	否	期望 HTTP 状态。
redirectTarget	SiteUrl	否	受控重定向目标。
cacheValidUntil	string	否	UTC ISO-8601。

7.6 IndexManifest

Owner：Index Adapter。

持久化路径：state/index-manifest.json。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
publishRunId	PublishRunId	是	发布 run id。
indexedAt	string	是	UTC ISO-8601。
gitCommit	string	是	索引来源 commit。
targets	map<string, IndexTargetStatus>	是	索引目标状态。

IndexTargetStatus：

字段	类型	必填	说明
status	enum	是	passed、failed、partial、skipped。
documents	number	是	成功处理文档数。
failedDocuments	number	否	失败文档数。
documentIds	DocumentId[]	否	成功处理的文档 ID。
failedDocumentIds	DocumentId[]	否	失败文档 ID。
attempt	number	是	第几次尝试。
startedAt	string	是	UTC ISO-8601。
finishedAt	string	否	UTC ISO-8601。
error	ErrorObject	否	失败原因。
errors	ErrorObject[]	否	target 错误列表。

8. Review 结构

8.1 ReviewReport

Owner：ReviewBridge。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
runId	RunId	是	review run id。
reviewType	enum	是	sync、release、agent、config。
title	string	是	review 标题。
summary	string	是	人类可读摘要。
status	enum	是	passed、failed、partial、skipped。
blockingItems	ReviewItem[]	否	阻断项。
warnings	ReviewItem[]	否	警告项。
links	LinkRef[]	否	PR、workflow、artifact 链接。
errors	ErrorObject[]	否	错误列表。

8.2 CheckReport

Owner：ReviewBridge。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
runId	RunId	是	check run id。
name	string	是	check 名称。
status	enum	是	passed、failed、partial、skipped。
summary	string	是	check 摘要。
blockingItems	ReviewItem[]	否	阻断项。
warnings	ReviewItem[]	否	警告项。
sourceReports	LinkRef[]	否	上游报告链接。
links	LinkRef[]	否	外部链接。
errors	ErrorObject[]	否	错误列表。

ReviewItem：

字段	类型	必填	说明
code	string	是	机器可读 item code。
message	string	是	人类可读说明。
path	NormalizedPath	否	关联路径。
severity	enum	是	info、warning、error、fatal。

LinkRef：

字段	类型	必填	说明
label	string	是	链接标签。
url	string	是	URL。
kind	enum	否	pr、workflow、artifact、issue、doc。

9. 索引结构

9.1 IndexDocument

Owner：Index Adapter。

字段	类型	必填	说明
documentId	DocumentId	是	稳定文档 ID。
path	NormalizedPath	是	publishPath。
url	SiteUrl	是	展示 URL。
title	string	否	标题。
content	string	是	可索引正文。
contentHash	ContentHash	是	内容 hash。
sourceId	string	否	来源 ID。
qualityStatus	enum	是	页面质量状态。
tags	string[]	否	标签。
metadata	object	否	adapter 可消费的扩展元数据。

9.2 SearchResult

Owner：Index Adapter / SearchIndexClient。

字段	类型	必填	说明
documentId	DocumentId	是	文档 ID。
path	NormalizedPath	是	publishPath。
url	SiteUrl	否	展示 URL。
title	string	否	标题。
snippet	string	否	命中片段。
score	number	否	搜索得分。
source	enum	是	meilisearch、ragflow、workspace。

10. 访问结构

10.1 Caller

字段	类型	必填	说明
type	enum	是	human、agent、system。
id	string	是	调用者 ID，匿名用户可使用稳定匿名 ID。
purpose	string	否	调用目的。

10.2 Scope

字段	类型	必填	说明
projects	string[]	否	项目范围。
paths	NormalizedPath[]	否	路径范围。
version	enum/string	是	main、working 或具体版本。
includeWorkingDocs	boolean	否	默认 false。
datasets	string[]	否	允许 dataset。

规则：调用方声明的 scope 只是请求，授权事实来自服务端 policy。

10.3 Citation

字段	类型	必填	说明
documentId	DocumentId	否	推荐提供。
path	NormalizedPath	是	引用页面路径。
url	SiteUrl	否	回跳 URL。
title	string	否	页面标题。
anchor	Anchor	否	页面锚点。
chunkId	string	否	自研 chunk ID。
externalChunkId	string	否	RAGFlow 等外部 chunk ID。
sourceProject	string	否	来源项目。
version	string	否	引用版本。

PageRef：

字段	类型	必填	说明
documentId	DocumentId	否	文档 ID。
path	NormalizedPath	是	页面路径。
url	SiteUrl	否	展示 URL。
title	string	否	页面标题。
contentHash	ContentHash	否	页面内容 hash。

SuggestedAction：

字段	类型	必填	说明
type	enum	是	create_feedback、create_improvement_task、retry_later、narrow_scope。
label	string	是	面向用户或 agent 的动作说明。
payload	object	否	可用于后续受控调用的输入草案。

QualitySignal：

字段	类型	必填	说明
path	NormalizedPath	否	关联页面路径。
signal	string	是	质量信号名称。
severity	enum	是	info、warning、error。
message	string	否	人类可读说明。

10.4 AnswerRequest

Owner：Answer API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
requestId	RequestId	否	可由客户端传入；服务端可生成。
caller	Caller	是	调用者。
scope	Scope	是	请求范围。
question	string	是	问题。
requireCitations	boolean	否	默认 true。
sessionId	string	否	多轮会话 ID。

10.5 AnswerResult

Owner：Answer API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
requestId	RequestId	是	请求 ID。
answer	string	否	答案正文。
summary	string	否	简短摘要。
citations	Citation[]	是	引用列表，可为空但无答案时必须说明原因。
confidence	enum	是	high、medium、low。
noAnswerReason	string	否	无答案原因。
relatedPages	PageRef[]	否	相关页面。
actions	SuggestedAction[]	否	反馈或改进动作。
audit	AuditRef	是	审计摘要。
errors	ErrorObject[]	否	错误列表。

10.6 AnswerSession

Owner：Answer API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
sessionId	string	是	会话 ID。
sessionTokenHash	string	是	session token 的 hash，不保存明文 token。
caller	Caller	是	会话创建者。
scope	Scope	是	会话授权 scope，不能被后续请求扩大。
createdAt	string	是	UTC ISO-8601。
expiresAt	string	是	UTC ISO-8601。
turns	AnswerTurn[]	是	会话轮次。
limits	AnswerSessionLimits	是	会话限制。
summary	string	否	会话历史摘要。

AnswerTurn：

字段	类型	必填	说明
requestId	RequestId	是	本轮请求 ID。
question	string	是	本轮问题。
answer	string	否	本轮答案。
citations	Citation[]	是	本轮引用，可为空但必须有无答案原因。
confidence	enum	是	high、medium、low。
noAnswerReason	string	否	无答案原因。
createdAt	string	是	UTC ISO-8601。

AnswerSessionLimits：

字段	类型	必填	说明
maxTurns	number	是	最大轮次。
maxContextTokens	number	是	最大上下文 token。

10.7 AgentToolRequest

Owner：Agent Access API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
requestId	RequestId	否	可选客户端传入。
tool	enum	是	search、ask、get_page、get_context、create_feedback、create_improvement_task。
caller	Caller	是	必须为 agent 或 system。
scope	Scope	是	请求 scope。
input	object	是	工具输入，按 tool 类型校验。
idempotencyKey	IdempotencyKey	写入工具建议必填	请求级幂等键。

10.8 AgentToolResult

Owner：Agent Access API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
requestId	RequestId	是	请求 ID。
tool	string	是	工具名。
status	enum	是	passed、failed、partial。
result	object	否	工具结果。
audit	AuditRef	是	审计摘要。
errors	ErrorObject[]	否	错误列表。

10.9 ContextPack

Owner：Agent Access API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
requestId	RequestId	是	请求 ID。
scope	Scope	是	实际授权后的 scope。
pages	PageRef[]	是	页面引用。
citations	Citation[]	否	片段引用。
qualitySignals	QualitySignal[]	否	质量信号。
limits	object	否	token、页面数量等限制。

11. 反馈与任务结构

11.1 FeedbackRequest

Owner：Agent Access API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
eventType	enum	是	qa_no_answer、qa_low_confidence、search_no_result、page_feedback 等。
dedupeKey	DedupeKey	是	去重键。
idempotencyKey	IdempotencyKey	否	请求级幂等。
caller	Caller	是	反馈来源。
scope	Scope	是	反馈范围。
question	string	否	原问题。
message	string	否	反馈说明。
citations	Citation[]	否	相关引用。

11.2 ImprovementTaskRequest

Owner：Agent Access API。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
dedupeKey	DedupeKey	是	改进任务去重键。
caller	Caller	是	创建者。
scope	Scope	是	任务范围。
goal	string	是	改进目标。
evidence	Citation[]	否	证据引用。
relatedFeedback	DedupeKey[]	否	关联反馈。

12. 迭代结构

12.1 IterationTask

Owner：AgentBridge。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
taskId	TaskId	是	任务 ID。
trigger	enum	是	issue、manual、quality-event。
goal	string	是	任务目标。
scope	Scope	是	任务授权范围。
base	IterationBase	是	任务基线。
constraints	IterationConstraints	是	约束。
relatedIssue	number	否	GitHub issue number。

IterationBase：

字段	类型	必填	说明
gitCommit	string	是	创建任务时 commit。
files	map<NormalizedPath, ContentHash>	是	文件基线 hash。

IterationConstraints：

字段	类型	必填	说明
allowedActions	string[]	是	add、update、delete。
requireCitations	boolean	是	是否要求证据。
allowDelete	boolean	是	是否允许删除。

12.2 RagflowIterationResult

Owner：AgentBridge。

字段	类型	必填	说明
summary	string	是	输出摘要。
changes	IterationChange[]	是	建议变更。
risk	enum	是	low、medium、high。
requiresHumanReview	boolean	是	必须为 true，MVP 不自动发布。

IterationChange：

字段	类型	必填	说明
path	NormalizedPath	是	目标路径。
action	enum	是	add、update、delete。
baseHash	ContentHash	条件必填	update/delete 必填。
reason	string	是	修改原因。
evidence	Citation[]	条件必填	requireCitations 时必填。
mode	enum	是	patch、whole-file。
draftContent	string	条件必填	whole-file 或 add 必填。
patch	string	条件必填	patch 模式必填。
overwrite	boolean	否	默认 false。

12.3 AgentBridgeReport

Owner：AgentBridge。

字段	类型	必填	说明
schemaVersion	string	是	schema 版本。
taskId	TaskId	是	任务 ID。
runId	RunId	是	agent run id。
status	enum	是	passed、failed、partial。
branch	string	否	Release 分支。
pullRequest	number	否	PR number。
validatedChanges	number	是	通过校验数量。
rejectedChanges	RejectedChange[]	否	被拒绝的 change。
errors	ErrorObject[]	否	错误列表。

RejectedChange：

字段	类型	必填	说明
path	NormalizedPath	否	被拒绝变更路径。
action	enum	否	原始 action。
reason	string	是	拒绝原因。
error	ErrorObject	是	标准错误。
baseHash	ContentHash	否	任务基线 hash。
currentHash	ContentHash	否	当前 hash。

13. 审计与错误引用结构

13.1 AuditRef

字段	类型	必填	说明
requestId	RequestId	条件必填	API 调用必填。
runId	RunId	条件必填	workflow 必填。
caller	string	是	caller id。
scope	string	是	简化 scope 表示。

13.2 AuditEvent

字段	类型	必填	说明
auditId	AuditId	是	审计事件 ID。
requestId	RequestId	否	API 请求 ID。
runId	RunId	否	workflow run ID。
caller	Caller	是	调用者。
scope	Scope	否	调用范围。
action	string	是	操作。
result	enum	是	passed、failed、denied、partial。
timestamp	string	是	UTC ISO-8601。
error	ErrorObject	否	错误。

13.3 ErrorObject

完整错误码和状态模型由 04-error-and-status-model.md 定义。本文先固定最小结构。

字段	类型	必填	说明
code	string	是	机器可读错误码。
message	string	是	人类可读说明。
retryable	boolean	否	是否可重试。
details	object	否	结构化上下文。

14. 结构变更规则

• 新增可选字段：兼容。
• 新增必填字段：破坏性变更，必须升级 schemaVersion。
• 删除字段：破坏性变更，必须先 deprecated。
• 枚举新增值：兼容，但 consumer 必须有 unknown fallback。
• 枚举删除或重命名：破坏性变更。
• 字段语义变化：破坏性变更，即使字段名不变。

15. 当前状态

本文已覆盖 contract map 中首版需要稳定的公共数据结构。后续进入实现前，应为本文的 Public Contract、持久化 Internal Contract 和 Adapter Contract 建立 schema、fixture 和 contract tests。