fail-open 与 PreparedContext

自动找回失败时，手头工作还应继续。你明确要求写入时，失败必须看得见。

PowerContext 是宿主任务旁边的一层上下文能力。Server 暂时不可用时，写代码、回答问题或继续工作不应该一起停下。

自动找回上下文失败时，手头工作还应继续。fail-open 只覆盖这类辅助路径。用户明确要求保存、批准、提交或导出时，失败不能被藏起来。

​

PreparedContext 是一次请求的临时值

宿主调用 prepare_context 时会带上 scope_id、当前查询和 max_bytes 字节预算。

Server 从当前启用状态 Memory 和已批准当前 Experience 中选择相关内容，再返回一个 PreparedContext。

正常结果有两种。

状态	含义	宿主行为
ready	有非空内容，且 content_bytes 与实际 UTF-8 字节数一致	将内容作为不可信历史证据临时注入
empty	没有合适内容	不注入，继续原任务

empty 不是 Server 故障，也不是认证失败。

PreparedContext 带精确 Citation，并使用明确的信任标记。

BEGIN_POWERCONTEXT_PREPARED_CONTEXT_V1
{"trust":"untrusted_history","items":[...]}
END_POWERCONTEXT_PREPARED_CONTEXT_V1

宿主不能因为这段内容来自 PowerContext，就把它提升为系统指令。Citation 说明来源与版本，不保证内容仍然符合当前文件、能力和授权。

​

哪些路径可以 fail-open

​

自动召回

Server 停止、超时、模式不认识或响应过大时，宿主跳过注入，继续原来的模型请求。它应记录有界诊断，但不能输出查询、Scope、准备好的内容、令牌或响应体。

​

自动提示词或轮次采集

采集失败不应中止宿主任务。它也不能删除已经准备好的有效上下文。

反过来也一样。召回失败时，支持采集的宿主仍可尝试保存 Source。这两条路径不是一个事务。

​

可选边界刷新

有些宿主会在采集后或会话边界尝试刷新，帮助新 Source 尽快进入抽取流程。刷新追不上游标或 Server 暂时不可用时，当前轮次仍可继续。

​

统计和 telemetry

统计失败不应让已经成功的领域写入回滚。

​

哪些操作必须明确失败

这些操作会改变或发布状态。静默继续会让调用方误以为修改已经发生。

操作	为什么不能静默继续
remember、修订或停用	调用者明确要求改变长期 Memory
Handoff 提交	失败后不存在新的持久里程碑
Candidate 修订、批准或拒绝	Review 必须绑定已检查的 Candidate 版本
Skill 导出或发布	冲突或本地漂移时不能覆盖宿主目录
鉴权与传输层检查	fail-open 不能绕过访问控制或把令牌发给其他地址

显式操作失败后，宿主的对话本身可以继续，但必须说明这次动作没有完成。

不要写“已保存”再在日志里记录失败。对于显式修改操作，用户看到的结果必须和持久状态一致。

​

一次对照实验

假设 Claude Code 收到下面这条问题。

What should I do after changing the OpenAPI contract?

Hook 会分别尝试召回和提示词采集。

​

召回失败，采集成功

这时不注入 PreparedContext。原提示词继续交给 Claude Code。提示词 Source 仍可能保存成功。诊断标记 server_unavailable 或对应的失败类别。

​

召回成功，采集失败

已验证的 additionalContext 仍然注入。采集错误不会抹掉召回结果。当前任务继续。

​

显式停用失败

用户随后通过 MCP 要求停用一条精确 Memory。此时 Server 已停止。MCP 操作返回不可用或错误。宿主不能声称 Memory 已停用。用户可以继续其他工作，等 Server 恢复后重试。

这三种情况都不中断宿主，但只有前两种属于自动 fail-open。

​

安全边界仍然失败时关闭

​

认证失败不是空召回

401 或 403 表示配置或授权有问题。把它当成 empty 会掩盖故障，也可能让用户误以为当前 Scope 没有历史。

​

不跟随重定向

Hook 不应携带授权信息请求头跟随 30x 到另一个宿主。重定向目标拿不到凭证，比尽量完成召回更重要。

​

不接受未知模式

响应能解析成 JSON，不代表宿主理解它。模式版本不匹配时跳过注入，记录 version_mismatch 或 invalid_response。

​

不接受无限响应

Hook 对响应大小和总墙钟时间设上限。超过限制就中止自动路径，不读取到内存后再处理。

​

不放行不安全传输层

PowerContext 客户端拒绝非本机回环地址的明文 HTTP。Server 绑定非本机回环地址时，默认也要求认证。否则必须显式启用不安全选项。fail-open 不能取消这些检查。

​

degraded 不等于 not_ready

就绪探测把数据库故障和可选推理故障分开。数据库或运行时不可用时返回 not_ready，HTTP 503。已配置的生成或嵌入探测失败时返回 degraded，HTTP 200。不依赖故障推理能力的数据库操作仍可继续。需要该生成或嵌入模型提供方的具体操作仍可能失败。

看到 degraded 时先检查具体能力，不要把整个 Server 当成离线。

​

诊断应告诉你什么

好的自动路径诊断只包含排错所需的元数据。

{
  "component": "powercontext.claude_code.recall",
  "event": "context_prepare",
  "outcome": "server_unavailable",
  "http_status": 503
}

它不应包含提示词、Scope、Memory 文本、Citation、令牌或模型提供方响应体。

常见 outcome 包括 empty、authentication_failed、version_mismatch、server_unavailable 和 invalid_response。

​

判断规则

遇到失败时，先问两个问题。这是宿主自动尝试的辅助操作，还是用户明确要求的持久动作？跳过它会不会让用户误以为状态已经改变？

自动辅助路径通常可以继续。任何会改变长期状态、批准内容或发布文件的动作，都必须返回真实结果。

​

怎么知道分清了

1. empty 不是故障，也不是 401 或 403。
2. 自动召回失败时，原任务还能继续。
3. 你明确写入 Memory、提交 Handoff、批准或导出时，失败看得见。
4. degraded 不是整个 Server 离线。

下一步进入安装并运行 Server。启动后分别观察 ready、degraded 和 Server 完全不可用时的行为。

​

下一步

启动本地 Server

先写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

开始第一条闭环

对上最像的那条故障

Server 停了却指望自动召回报错，或把 401/403 当成没有内容？先对照已经出现过的情况。

打开排错