> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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，不是长期资产。) 带精确 Citation，并使用明确的信任标记。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 不能绕过访问控制或把令牌发给其他地址 |

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

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

## 一次对照实验

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 当成离线。

## 诊断应告诉你什么

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)。启动后分别观察 `ready`、`degraded` 和 Server 完全不可用时的行为。

## 下一步

> [card] [启动本地 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)
>
> 先写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

> [card] [对上最像的那条故障](https://powercontext.mintlify.site/zh/start/troubleshooting.md)
>
> Server 停了却指望自动召回报错，或把 401/403 当成没有内容？先对照已经出现过的情况。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.