> ## 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.

# 心智模型总览

> 先分清三条路，再往下读对象页。

把 PowerContext 只理解成“给 Agent 加记忆”，后面很快会混。一条提示词算不算 Memory (经过选择、以后还会用到的项目知识。)？模型生成的 Skill (已批准的可重复做法。获批后还要显式导出，不自动获得执行权限。) 能不能直接装？Handoff (把当前目标、已验证进度、阻塞项和下一步交给接手者。不提交就还是临时包。) 为什么有时没有最新版本？

答案不在某个 API 参数里。先分清对象边界。

## 先看三条路

PowerContext 同时走三条路。它们可以互相引用，但不会自动并成一件事。

![留下知识、先审再留、交接工作是三条独立路径。](https://mintcdn.com/powercontext/1t_ajifOEOG5YQjP/assets/mental-three-paths-zh.svg?fit=max\&auto=format\&n=1t_ajifOEOG5YQjP\&q=85\&s=457d38b7a573349c1e104e521f356cfb)

留下知识。Source (记录发生过什么。采集不会自动写成长期知识。) 只证明这件事发生过。确认以后还要用，才写成 Memory。下次请求用 PreparedContext (这一次请求用的有界视图。带 Citation，不是长期资产。) 召回。

先审再留。Experience (已批准的判断经验。先作为 Candidate 进入 Review。) 和托管 Skill 先变成 Candidate (尚待 Review 的 Experience 或 Skill 提案。)。模型可以起草，生成成功不等于批准。Review (批准才创建 Artifact Revision。拒绝只记录原因，不创建结果 Artifact。) 批准后才会留下。Skill 还要显式导出。

交接可以先临时。Handoff 先打包给接手者；只有显式提交，才成为持久里程碑。

写入 Memory 不会顺便创建 Handoff。批准 Skill 也不会把它塞进下一次 PreparedContext。

## 六种值，不要混用

这些值的生命周期和权限含义不同。分清它们，才不会把这一次的模型输入当成持久状态，或当成可执行指令。

| 值 | 解决什么问题 | 是否持久 | 是否可直接当成当前指令 |
| - | - | -: | -: |
| `Source` | 记录发生过什么，并提供可定位证据 | 是 | 否 |
| Artifact `Revision` | 保存某个长期资产的不可变历史快照 | 是 | 否 |
| `Candidate` | 保存尚待 Review 的 Experience 或 Skill 提案 | 是 | 否 |
| `PreparedContext` | 为一次请求准备相关、带 Citation 的上下文 | 否 | 否 |
| 已准备 `Handoff` | 临时传递当前工作状态 | 由调用方持有 | 否 |
| Skill 投影 | 把一个已批准 Skill Revision 导出到宿主目录 | 是，可重建 | 仍由宿主决定 |

### Source 是证据

Source 可以保存提示词、任务结果或其他工作材料。它回答“当时发生了什么”。

采集 Source 不等于把内容写进 Memory。自动抽取还需要生成流程。你已经确认要留什么时，直接写 Memory 更简单。

### Artifact Revision 保存历史

Memory、Experience、Skill 和已提交 Handoff 都有 Artifact Revision。Revision 是不可变快照。同一个逻辑资产更新时会产生下一 Revision，旧版本仍然可以按精确引用读取。

精确引用包含类型、Artifact ID 和 Revision：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
family/artifact_id@revision
```

Candidate 有自己的 `version`，它用于 Review 前的并发控制。Candidate 版本 2 和 Artifact Revision 2 没有对应关系。

### PreparedContext 只活一轮

`prepare_context` 根据 Scope、查询和字节预算构造 PreparedContext。结果只有两种正常状态：

* `ready`：有非空内容和 Citation；
* `empty`：没有合适内容，不是故障。

PreparedContext 不会写回长期历史。宿主应把它标成 `untrusted_history`，并只注入当前这一次模型请求。

### Handoff 可以不提交

已准备 Handoff 是可检查、可传递的临时值。你可以直接把它交给接手者，也可以显式提交成 Handoff Revision，作为以后可按精确或最新版本继续的里程碑。

提交是独立动作。没有提交，就没有新的持久 Handoff 头版本。

### Experience 和 Skill 要经过 Review

模型或用户可以提交 Candidate。Review 有两个终态：

* 批准：创建或修订 Artifact，并记录精确 `result_artifact`；
* 拒绝：记录原因，不创建结果 Artifact。

只有已批准当前 Experience 可以进入 PreparedContext。Skill 从不进入 PreparedContext。它需要显式导出，PowerContext 也不会因为导出就授予执行权限。

## 三条边界

### 持久化边界

PreparedContext 和已准备 Handoff 是临时值。Source、Candidate 和 Artifact Revision 会持久化。Skill 投影是 Artifact 的宿主副本，不是新的权威来源。

### Review 边界

生成只负责生成提案。Review 决定是否批准。两者不能合并成“模型生成成功，所以已上线”。

### 执行权限边界

Scope 只选择数据。Citation 只说明来源和版本。Review 只决定是否创建 Artifact。这些机制都不会授予工具权限，也不会证明历史内容仍然符合当前工作区状态。

## 后面都用同一道例题

后面讲 Source、Memory、Handoff、Experience 和 Skill 时，不会换故事，大家都围着同一道例题。这样就能对照：同一件工作会留下哪些不同对象。

例题是：PowerContext 的 OpenAPI 契约改了。接下来要重新生成签入仓库的客户端，再跑契约测试。

同一件事会分开留下这些东西，而且不会自动串起来：

| 做的事 | 留下什么 | 不会自动变成 |
| - | - | - |
| 记下契约已改，客户端和契约测试都要跟上 | Source | Memory |
| 确认以后还要用，写下“跑测试前先重新生成并检查客户端” | Memory | Handoff |
| 下一轮问“改完契约下一步做什么” | PreparedContext | 长期资产 |
| 把当前进度交给下一位 Agent | 已准备 Handoff | 已提交的 `latest` |
| 根据结果提交一条判断经验 | Experience Candidate | 已批准 Experience |
| Experience 获批后，再起草可重复做法 | Skill Candidate | 已批准 Skill |
| 把已批准 Skill 导出到支持的宿主 | Skill 投影 | 执行权限或召回结果 |

对照后面的推演时，看每一步返回的 ID、Citation 或 Revision。

## 常见误解

> [accordion] 捕获提示词后为什么搜索不到 Memory？
>
> 采集只保存 Source。要么配置生成流程并处理 Source 窗口，要么显式调用 Memory 写入接口。

> [accordion] 为什么已批准 Skill 没出现在召回结果里？
>
> 这是设计如此。PreparedContext 可以包含启用状态 Memory 和已批准当前 Experience，不包含 Skill。Skill 要显式导出给宿主。

> [accordion] 为什么 Prepared Handoff 没有成为最新版本？
>
> 已准备 Handoff 尚未提交。它可以用于临时继续，但不会自动成为持久里程碑。

> [accordion] 有 Citation 是否代表内容仍然正确？
>
> Citation 让来源和版本可检查，不保证内容仍然新鲜。接手者仍要检查当前文件、能力和授权。

## 怎么知道分清了

你刚读完这页时，先核这四件事：

1. 采集成功，不等于已经留下 Memory。
2. PreparedContext 只服务这一次请求，不会自动变成长期资产。
3. 已准备 Handoff 不提交，就不会成为 `latest`。
4. Skill 获批后还要显式导出，而且不会进入 PreparedContext。

对不上时，先读对应对象页，不要直接跳进安装。

> [!TIP]
>
> 自动帮你找回上下文失败时，当前任务还应继续。你明确要求写入 Memory、提交 Handoff、批准或导出时，失败必须能看见。完整说明见 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)。

## 下一步

> [card] [先看证据怎么留下](https://powercontext.mintlify.site/zh/mental-model/source.md)
>
> Source 只证明这件事发生过。日志位置、处理游标和 Memory 是后面的不同层。

> [card] [接入前先看 Scope](https://powercontext.mintlify.site/zh/mental-model/scope.md)
>
> 设错 Scope 通常不报错，只是搜不到。准备接宿主前，再读 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)。


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