错误与状态模型

# 错误与状态模型

修订记录

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

1. 文档目标

本文定义 kunora-wiki 自研模块共享的错误对象、状态枚举、错误码、重试语义、降级策略和审计要求。

目标是让 CLI、workflow、API、adapter 和 AgentBridge 对失败有一致表达：什么失败可重试，什么失败必须人工处理，什么失败不能继续写入，什么失败只影响外部消费但不影响 Git 内容事实。

2. 通用状态枚举

2.1 OperationStatus

用于单次操作或工具调用。

状态	语义
`passed`	操作完整成功。
`failed`	操作失败，未完成目标。
`partial`	部分成功，必须查看 errors 或 report。
`skipped`	按规则跳过，不是错误。
`denied`	权限或 policy 拒绝。
`pending`	已创建但尚未执行。
`running`	正在执行。
`unknown`	状态无法判断。

2.2 PageStatus

用于页面和 manifest。

状态	语义
`approved`	已审批，可正式展示或消费。
`needs-review`	需要人工审查。
`stale`	可能过期。
`conflict`	存在同步或内容冲突。
`feedback-open`	存在未处理反馈。
`unknown`	状态无法判断，不得默认为 approved。

2.3 IndexTargetStatus

用于索引目标。

状态	语义
`passed`	目标索引完成。
`failed`	目标索引失败。
`partial`	部分文档成功，部分失败。
`skipped`	目标被配置禁用或无变更。

2.4 DriftStatus

用于发布、站点和索引对账。

状态	语义
`in-sync`	状态一致。
`outdated`	目标落后于 Git 或 publish manifest。
`missing`	目标缺失。
`mismatch`	hash、URL 或状态不一致。
`within-cache-window`	删除页仍在缓存窗口内，不算漂移。
`unknown`	无法判断。

3. ErrorObject

所有模块返回错误时必须使用 ErrorObject 或包含兼容字段。

字段	类型	必填	说明
`code`	string	是	机器可读错误码。
`message`	string	是	人类可读说明。
`severity`	enum	是	`info`、`warning`、`error`、`fatal`。
`retryable`	boolean	是	是否可在相同输入下重试。
`module`	string	是	产生错误的模块。
`operation`	string	否	失败操作。
`details`	object	否	结构化上下文。
`cause`	string	否	上游错误摘要，不包含敏感信息。
`remediation`	string	否	建议处理方式。

规则：

message 可以面向人，但不能作为程序判断依据。
code 必须稳定，作为程序判断依据。
details 不得包含 token、secret、完整认证头。
外部产品原始错误必须转换为标准错误码。
fatal 表示当前 run 不应继续执行写入副作用。

4. 错误码命名规则

格式：

&lt;domain&gt;.&lt;reason&gt;

示例：

config.invalid_schema
sync.conflict_detected
access.forbidden_scope
adapter.ragflow_unavailable

Domain 枚举：

Domain	适用范围
`config`	配置加载、schema、配置影响。
`path`	路径规范化和越界。
`workspace`	`publish/**`、state、manifest 读写。
`sync`	三方 diff、source lock、source changes。
`review`	PR、checks、workflow summary。
`display`	展示构建、site manifest、URL。
`index`	RAGFlow/Meilisearch 索引流程。
`answer`	Answer API、RAG 问答标准化。
`access`	Agent Access、scope、policy、tool 授权。
`agent`	AgentBridge、iteration task、RAGFlow 改写结果。
`adapter`	外部产品 adapter。
`runtime`	环境、依赖、超时、未知运行时错误。

5. 通用错误码

错误码	retryable	severity	说明
`runtime.unknown`	false	error	未分类错误。
`runtime.timeout`	true	error	操作超时。
`runtime.dependency_unavailable`	true	error	外部依赖不可用。
`runtime.rate_limited`	true	warning	触发限流。
`runtime.cancelled`	false	warning	操作被取消。
`runtime.invalid_state`	false	error	状态与预期不符。
`path.invalid`	false	error	路径格式非法。
`path.out_of_scope`	false	error	路径越权。
`path.collision`	false	fatal	路径冲突，例如 publishPath 重复或父子嵌套。
`schema.invalid`	false	error	schema 校验失败。
`schema.unsupported_version`	false	error	schemaVersion 不支持。
`hash.mismatch`	false	error	hash 不匹配。
`idempotency.conflict`	false	error	同一 idempotencyKey 对应不同 payload。

6. 模块错误码

6.1 ConfigManager

错误码	retryable	severity	处理
`config.file_missing`	false	error	阻断依赖该配置的流程。
`config.invalid_yaml`	false	error	阻断流程，要求修复配置 PR。
`config.invalid_schema`	false	error	阻断流程。
`config.duplicate_source_id`	false	fatal	阻断流程。
`config.duplicate_publish_path`	false	fatal	阻断流程。
`config.publish_path_nested`	false	fatal	阻断流程。
`config.impact_requires_review`	false	warning	允许生成报告，但不自动同步。

6.2 WorkspaceStore

错误码	retryable	severity	处理
`workspace.read_failed`	true	error	可重试；持续失败则阻断。
`workspace.write_failed`	true	error	可重试；不得 fallback 到非受控路径。
`workspace.path_out_of_scope`	false	fatal	阻断写入。
`workspace.hash_failed`	false	error	阻断依赖 hash 的流程。
`workspace.manifest_invalid`	false	error	报告并尝试重建；不能静默使用。
`workspace.state_not_found`	false	warning	可按首次运行处理，需记录。

6.3 SyncEngine

错误码	retryable	severity	处理
`sync.source_unavailable`	true	error	可重试；失败时不更新 source lock。
`sync.source_ref_not_found`	false	error	阻断该 source。
`sync.conflict_detected`	false	warning	不写冲突文件，生成报告。
`sync.delete_conflict`	false	warning	不删除文件，生成报告。
`sync.lock_update_failed`	true	error	不应标记同步成功。
`sync.partial_source_failed`	true	partial/error	允许其他 source 继续，但 PR 必须标记 partial。

6.4 ReviewBridge

错误码	retryable	severity	处理
`review.branch_create_failed`	true	error	不写 main，保留本地/report。
`review.pr_create_failed`	true	error	保留分支和 report，提示人工处理。
`review.pr_update_failed`	true	error	保留 report。
`review.check_update_failed`	true	warning	不影响 Git 内容，但 PR 状态需人工确认。
`review.permission_denied`	false	fatal	阻断。

6.5 DisplayBackend Adapter

错误码	retryable	severity	处理
`display.build_failed`	false	error	不生成成功态 site manifest。
`display.url_collision`	false	fatal	阻断发布。
`display.page_missing`	false	error	生成漂移报告。
`display.render_hash_mismatch`	false	error	生成漂移报告。
`display.backend_unavailable`	true	error	可重试。

6.6 Index Adapter

错误码	retryable	severity	处理
`index.target_unavailable`	true	error	标记该 target failed，不回滚 Git。
`index.upsert_failed`	true	error	记录失败文档，目标可能 partial。
`index.delete_failed`	true	error	记录失败删除，目标 failed 或 partial。
`index.document_invalid`	false	error	跳过该文档并标记 partial。
`index.outdated`	false	warning	漂移检测报告。

6.7 Answer API

错误码	retryable	severity	处理
`answer.invalid_request`	false	error	返回 400。
`answer.forbidden_scope`	false	error	返回 403。
`answer.dataset_not_allowed`	false	error	返回 403。
`answer.ragflow_unavailable`	true	error	返回错误，不生成虚假答案。
`answer.no_answer`	false	info	返回 noAnswerReason 和 action。
`answer.citation_missing`	false	warning/error	requireCitations 时不能返回确定答案。
`answer.session_forbidden`	false	error	返回 403。
`answer.session_expired`	false	warning	要求创建新 session。

6.8 Agent Access API

错误码	retryable	severity	处理
`access.unauthorized`	false	error	返回 401。
`access.forbidden_tool`	false	error	返回 403。
`access.forbidden_scope`	false	error	返回 403。
`access.dataset_not_allowed`	false	error	返回 403。
`access.idempotency_conflict`	false	error	拒绝请求。
`access.feedback_deduped`	false	info	返回已有 Issue 或反馈记录。
`access.tool_failed`	depends	error	包装底层错误。

6.9 AgentBridge

错误码	retryable	severity	处理
`agent.task_invalid`	false	error	不调用 RAGFlow。
`agent.ragflow_output_invalid`	false	error	不写文件。
`agent.path_out_of_scope`	false	fatal	拒绝 change。
`agent.missing_evidence`	false	error	requireCitations 时拒绝 change。
`agent.concurrent_change`	false	warning	不写文件，生成报告。
`agent.patch_apply_failed`	false	error	不 fallback 整文件覆盖。
`agent.pr_create_failed`	true	error	保留分支和 report。

6.10 Adapter

错误码	retryable	severity	处理
`adapter.github_unavailable`	true	error	可重试。
`adapter.github_permission_denied`	false	fatal	阻断对应操作。
`adapter.ragflow_unavailable`	true	error	问答或索引失败。
`adapter.ragflow_invalid_response`	false	error	不消费该响应。
`adapter.search_unavailable`	true	error	搜索失败。
`adapter.search_invalid_response`	false	error	不消费该响应。
`adapter.docusaurus_build_failed`	false	error	发布失败。

7. HTTP 状态映射

错误类型	HTTP 状态
invalid request / schema	400
unauthorized	401
forbidden tool/scope/dataset	403
not found	404
idempotency conflict	409
rate limited	429
dependency unavailable	503
timeout	504
unexpected server error	500

规则：

HTTP 状态只表达传输/API 层结果，业务错误仍必须放入 ErrorObject。
answer.no_answer 通常返回 HTTP 200，因为它是有效业务结果，不是系统错误。
partial result 可以返回 HTTP 200 或 207；MVP 推荐 HTTP 200 + status=partial，减少客户端兼容复杂度。

8. Retry 策略

错误类别	是否重试	规则
网络超时	是	指数退避，最大重试次数由模块配置。
外部服务 5xx	是	指数退避，记录 attempt。
rate limit	是	尊重 `Retry-After`，否则指数退避。
schema invalid	否	输入问题，重试无意义。
permission denied	否	需要改权限或 token。
path out of scope	否	安全错误，不能重试绕过。
hash mismatch / concurrent change	否	需要重新生成任务或人工处理。
conflict detected	否	需要人工或后续任务处理。
no answer	否	应生成反馈或改进任务。

重试约束：

可重试写入必须有 idempotencyKey 或稳定幂等键。
重试不能改变 request scope。
重试不能绕过权限校验。
workflow 重试必须记录 attempt。

9. 降级策略

场景	降级方式	禁止事项
RAGFlow 不可用	Answer API 返回依赖不可用；可提供反馈入口	不编造答案。
Meilisearch 不可用	Agent Access search 返回错误；可提示使用 ask	不用过期搜索结果伪装成功。
Index 失败	Git 内容保持已审批；index manifest 标记 failed	不回滚 Git 内容。
Docusaurus build 失败	不发布站点；PR/check 标记失败	不生成成功态 site manifest。
Sync source 不可用	不更新 source lock；报告失败	不使用旧来源冒充本次同步成功。
AgentBridge PR 创建失败	保留分支/report，提示人工处理	不直接写 main。

10. 状态传播规则

上游状态	下游处理
`sync.conflict_detected`	Sync PR 必须标记冲突；不能自动发布。
`display.build_failed`	PublishManifest/SiteManifest 不得标记成功。
`index.target_unavailable`	IndexManifest 标记 target failed；Answer API 使用上一版可用索引或返回不可用。
`answer.no_answer`	返回 noAnswerReason 和 create_feedback/create_improvement_task action。
`agent.concurrent_change`	AgentBridgeReport 标记 rejected change，Release PR 不应包含该写入。

11. 审计要求

以下事件必须产生 audit event 或 workflow log：

配置校验失败。
SyncEngine 检测到 conflict / delete_conflict。
ReviewBridge 创建或更新 PR 失败。
Display build 失败或漂移检测失败。
Index target failed / partial。
Answer API 返回 no answer、forbidden 或 dependency unavailable。
Agent Access 拒绝 tool/scope/dataset。
AgentBridge 拒绝 change、检测并发变更或 PR 创建失败。

Audit event 最少包含：

auditId
requestId 或 runId
caller
scope
action
result
timestamp
error.code，如失败

12. 模块接入要求

每个模块设计必须说明：

可能返回哪些错误码。
哪些错误可重试。
哪些错误会阻断写入。
哪些错误只影响外部消费，不影响 Git 内容事实。
错误如何进入 report、manifest、PR body 或 audit log。

未定义错误模型的模块不应进入实现。

13. 验收用例

用例	预期
Agent 越权访问路径	返回 `access.forbidden_scope`，retryable=false，审计记录 denied。
RAGFlow 不可用	返回 `answer.ragflow_unavailable` 或 `adapter.ragflow_unavailable`，不生成答案。
知识库无答案	返回 `answer.no_answer`，HTTP 200，带反馈 action。
Sync 检测冲突	返回/记录 `sync.conflict_detected`，不覆盖 publish 文件。
AgentBridge baseHash 不匹配	返回 `agent.concurrent_change`，不写文件。
Docusaurus build 失败	返回 `display.build_failed`，不生成成功态 site manifest。
Meilisearch upsert 部分失败	IndexManifest target status=`partial` 或 `failed`，Git 内容不回滚。
同一 idempotencyKey 不同 payload	返回 `access.idempotency_conflict`。

14. 后续文档衔接

06-fixtures-and-tests.md 必须为本文定义的错误和状态提供测试夹具：

invalid schema fixture。
forbidden scope fixture。
sync conflict fixture。
dependency unavailable fixture。
idempotency conflict fixture。
no answer fixture。
partial index fixture。
concurrent change fixture。

来源项目	`kunora-wiki`
分支	`docs-publish`
路径	`technology/components/kunora-wiki/development/common/04-error-and-status-model.md`

修订记录​

1. 文档目标​

2. 通用状态枚举​

2.1 OperationStatus​

2.2 PageStatus​

2.3 IndexTargetStatus​

2.4 DriftStatus​

3. ErrorObject​

4. 错误码命名规则​

5. 通用错误码​

6. 模块错误码​

6.1 ConfigManager​

6.2 WorkspaceStore​

6.3 SyncEngine​

6.4 ReviewBridge​

6.5 DisplayBackend Adapter​

6.6 Index Adapter​

6.7 Answer API​

6.8 Agent Access API​

6.9 AgentBridge​

6.10 Adapter​

7. HTTP 状态映射​

8. Retry 策略​

9. 降级策略​

10. 状态传播规则​

11. 审计要求​

12. 模块接入要求​

13. 验收用例​

14. 后续文档衔接​