> ## 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，不必整站读完。先分清几个对象，再选一条和你现在工作有关的路径。不要同时走几条路，本地 API、Python 框架和 Agent 插件验证的是不同事情。先跑通一条，再决定要不要看下一条。

### 1. 先把对象分清

从[心智模型总览](https://powercontext.mintlify.site/zh/mental-model/overview.md)开始，再读 [Scope](https://powercontext.mintlify.site/zh/mental-model/scope.md) 和 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)。至少分清 Source (记录发生过什么。采集不会自动写成长期知识。)、Memory (经过选择、以后还会用到的项目知识。)、PreparedContext (这一次请求用的有界视图。带 Citation，不是长期资产。) 和 Handoff (把当前目标、已验证进度、阻塞项和下一步交给接手者。不提交就还是临时包。)。

### 2. 启动本地 Server

按[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)做最小配置。只写 Memory、用全文搜索时，不需要推理模型。

### 3. 只选一条路径

按下面的目标选一条。先跑通，再看其他框架和 Agent。

### 4. 需要细节时看官方文档

安装参数、接口说明和部署配置，以 [官方文档](https://oceanbase.github.io/powercontext/) 的最新发布版本为准。101 帮你判断该走哪条路、怎样验证结果。

> [!WARNING]
>
> 当前写清的安装路径是 macOS 或 Linux，Python 3.11 及以上。本教程不提供未经验证的 Windows 变通方案。

## 按你的目标选择

> [tab] 第一次接触
>
> 先按这个顺序读：
>
> 1. [心智模型总览](https://powercontext.mintlify.site/zh/mental-model/overview.md)
> 2. [Scope](https://powercontext.mintlify.site/zh/mental-model/scope.md)
> 3. [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)
> 4. [安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)
> 5. [常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md)
>
> 怎么知道跑通了？按上面第 4、5 步做。先在[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md) 把本地 Server 拉起来，再打开[常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md)，照着脚本写出一条 Memory。
>
> 终端里应能看到三件事：`search_memory` 命中刚才那条；`prepare_context` 返回非空内容；结果里带 Citation。对不上时，先对[排错](https://powercontext.mintlify.site/zh/start/troubleshooting.md)。
>
> 框架、Agent 宿主，以及后面的 Source / Handoff 教程，可以先不看。
>
> 还想多看一点时（可选）：
>
> 对象还容易混，再读 [Source](https://powercontext.mintlify.site/zh/mental-model/source.md)、[Memory](https://powercontext.mintlify.site/zh/mental-model/memory.md)、[Handoff](https://powercontext.mintlify.site/zh/mental-model/handoff.md) 和 [Experience 与 Skill](https://powercontext.mintlify.site/zh/mental-model/experience-and-skill.md)。第一条闭环跑通后，需要时再做 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)、[Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md) 和 [Experience / Skill Review](https://powercontext.mintlify.site/zh/basic-usage/experience-skill-review.md)。要用 MCP 客户端连同一套数据，看[用 MCP 连接 Server](https://powercontext.mintlify.site/zh/basic-usage/mcp.md)。要核对同一 Scope 的启用和停用统计，看[用 Dashboard 核对 Scope 统计](https://powercontext.mintlify.site/zh/basic-usage/dashboard.md)。Memory 正文仍通过客户端、HTTP 或 MCP 读取。

> [tab] 我写 Python Agent
>
> 先分清对象，再[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)，走完[常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md)，然后看[框架集成](https://powercontext.mintlify.site/zh/frameworks/overview.md)。
>
> 怎么知道跑通了？先把[常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md) 的脚本跑出三次结果：写入成功、搜索命中、`prepare_context` 带 Citation。再进[框架集成总览](https://powercontext.mintlify.site/zh/frameworks/overview.md)，按 LangGraph 或 LangChain 页把同一条 Memory 接到 Agent 里。新会话还能问到你刚写下的结论，才算接上。
>
> 第一次接入选 LangGraph 或 LangChain，不要先走 Server 推理，也不要先走预览适配器。Pydantic AI Agent 适配器目前是 **Preview**，普通安装路径不可用，不要作为第一次接入。
>
> 如果只要自动找回上下文，Handoff 和 Skill 可以后看。
>
> 还想多看一点时（可选）
>
> 接上 LangGraph 或 LangChain 之后，再看[框架技巧](https://powercontext.mintlify.site/zh/frameworks/tricks.md)。需要 Source 抽取、Handoff 或 Skill 时，走 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)、[Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md) 和 [Experience / Skill Review](https://powercontext.mintlify.site/zh/basic-usage/experience-skill-review.md)。Server 推理和预览适配器只在需要时再读。

> [tab] 我用 Hermes / OpenClaw
>
> 先分清对象，再[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)，然后看[通用 Agent 总览](https://powercontext.mintlify.site/zh/common-agents/overview.md)，再进 [Hermes](https://powercontext.mintlify.site/zh/common-agents/hermes.md) 或 [OpenClaw](https://powercontext.mintlify.site/zh/common-agents/openclaw.md)。
>
> 怎么知道跑通了？打开对应的 [Hermes](https://powercontext.mintlify.site/zh/common-agents/hermes.md) 或 [OpenClaw](https://powercontext.mintlify.site/zh/common-agents/openclaw.md) 页，按页上的安装和 `powercontext doctor <host>` 做完。`doctor` 通过只说明插件装好了。再开一个新会话，问你刚明确保存的那条 Memory；问得到，才算跑通。
>
> Hermes 在 `powercontext setup hermes` 后，还要运行 `hermes memory setup` 并选择 PowerContext。OpenClaw 要确认插件占用了 Memory 插槽。WorkBuddy 走独立的 `setup workbuddy` 路径。便携 Agent Plugin 没有安装配置命令；加载它的软件包目录，再验证明确的 MCP 操作。安装、凭证和持久写入仍由你授权。
>
> 还想多看一点时（可选）
>
> 召回跑通后再读 [Handoff](https://powercontext.mintlify.site/zh/mental-model/handoff.md)、[Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md) 和 [Experience / Skill Review](https://powercontext.mintlify.site/zh/basic-usage/experience-skill-review.md)。[Agent 自扩展](https://powercontext.mintlify.site/zh/common-agents/agent-self-extension.md) 只覆盖托管 Skill 导出。Hermes 和 OpenClaw 导不出去，要换 Codex 或 Claude Code。

> [tab] 我用编程 Agent
>
> 先分清对象，再[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)，然后看[编程 Agent 总览](https://powercontext.mintlify.site/zh/coding-agents/overview.md)，再进对应宿主页。
>
> 选择 Codex、Claude Code、DSH、OpenCode 或 Pi。它们连同一套 Server，但生命周期、注入位置和权限确认并不相同。
>
> 怎么知道跑通了？先打开[编程 Agent 总览](https://powercontext.mintlify.site/zh/coding-agents/overview.md) 选宿主，再按那一页的安装和验证做。停掉 Server 后再写一段普通代码，任务还应继续。你明确写入 Memory 或提交 Handoff 失败时，页面或终端里必须能看见错误。各宿主页会用它自己的工具写出这几步。
>
> 还想多看一点时（可选）
>
> 宿主页跑通后再读 [Hook 与插件](https://powercontext.mintlify.site/zh/coding-agents/hooks-and-plugins.md) 和[扩展 Hook](https://powercontext.mintlify.site/zh/coding-agents/extend-hooks.md)。对象细节看 [Source](https://powercontext.mintlify.site/zh/mental-model/source.md)、[Memory](https://powercontext.mintlify.site/zh/mental-model/memory.md)、[Handoff](https://powercontext.mintlify.site/zh/mental-model/handoff.md) 和 [Experience 与 Skill](https://powercontext.mintlify.site/zh/mental-model/experience-and-skill.md)。需要时再跑 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)、[Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md) 和 [Experience / Skill Review](https://powercontext.mintlify.site/zh/basic-usage/experience-skill-review.md)。

> [tab] 我在写新集成
>
> 先完成 [Hook 与插件](https://powercontext.mintlify.site/zh/coding-agents/hooks-and-plugins.md)，比较至少两个现有宿主，再读[扩展 Hook](https://powercontext.mintlify.site/zh/coding-agents/extend-hooks.md)。
>
> 要交的不是一段能调用 `prepare_context` 的代码，而是一份能验证的接入说明。Scope、临时注入、Source 采集、权限、诊断、安装和真实宿主端到端验证，都要有明确行为。
>
> Handoff 和 Skill 教程可以等召回和采集主链稳定后再补。
>
> 还想多看一点时（可选）
>
> 主链稳定后再补 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)、[Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md)、[Experience / Skill Review](https://powercontext.mintlify.site/zh/basic-usage/experience-skill-review.md) 和[框架技巧](https://powercontext.mintlify.site/zh/frameworks/tricks.md)。对象页用来对照行为，不是立项门槛：[Source](https://powercontext.mintlify.site/zh/mental-model/source.md)、[Memory](https://powercontext.mintlify.site/zh/mental-model/memory.md)、[Handoff](https://powercontext.mintlify.site/zh/mental-model/handoff.md)、[Experience 与 Skill](https://powercontext.mintlify.site/zh/mental-model/experience-and-skill.md)。

## 用同一件事验收

不管选哪条路，都用这件事检查有没有跑通。第一次接触时，在[常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md) 里做；接了 Agent 之后，到你选的那一页用它自己的工具重做。

你刚写下一条以后还要用的结论。换一次请求，还能不能找到它？

1. 在固定 Scope 里明确写下来。
2. 换一个请求或新会话再问。
3. 检查召回内容有没有 Citation，并且只进入这一次模型输入。
4. 停掉 Server 再问一次。自动找回可以失败，手头工作还应继续。
5. 再试一次明确写入。失败必须能看见，不能假装保存成功。

不要只在这里打勾。对不上时，先看[排错](https://powercontext.mintlify.site/zh/start/troubleshooting.md)。

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

> [!NOTE]
>
> 101 目前不为 Bub 单独写路径。它的说明主要在集成目录的 README 里。

## 下一步

> [card] [先把对象分清](https://powercontext.mintlify.site/zh/mental-model/overview.md)
>
> Source、Memory 和 PreparedContext 还会混在一起时，从这里开始。

> [card] [启动本地 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)
>
> 对象已经清楚时，直接写出一条 Memory，搜到它，再拿到带 Citation 的 `PreparedContext`。


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