> ## 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，卡住时多半不是看不懂报错，而是明明写过却搜不到、页面是空的，或者诊断过了还是不行。下面几条都是 101 里已经出现过的情况。找和你现在最像的一条，按里面的链接继续。

> [!NOTE]
>
> 安装参数、接口说明和部署配置，以 [官方文档](https://oceanbase.github.io/powercontext/) 的最新发布版本为准。这页只帮你判断卡在哪一类问题上。

### 1. Scope 对不上

客户端、Dashboard、Agent 环境变量和 `--scope-id` 必须逐字相同。Scope (决定这次请求读写哪一组数据。设错时通常不报错，只是搜不到。) 是字面值。`project:powercontext-101` 和 `project:powercontext-101:<uuid>` 不是同一个 Scope。对照 [Scope](https://powercontext.mintlify.site/zh/mental-model/scope.md)。

### 2. 换了数据目录或数据库

`POWERCONTEXT_HOME` 或数据库 URL 一变，你看到的是另一套库。这很像 Scope 丢了。先对[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md) 里的数据目录，再对 Scope。

### 3. 把 401/403 当成没有内容

`empty` 表示这个 Scope 当前没有可召回内容。401/403 是认证失败。这时不要注入上下文，也不能假装这个 Scope 没有 Memory (经过选择、以后还会用到的项目知识。)。见 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md) 和 [MCP](https://powercontext.mintlify.site/zh/basic-usage/mcp.md)。

### 4. 采集成功，但搜不到 Memory

采集 Source (记录发生过什么。采集不会自动写成长期知识。) 只表示这件事发生过。它不会自动变成长期 Memory。没有生成模型时，Source 会保持待处理。用 `remember_memory` 写你已经确认的事实，或读 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)。

### 5. 诊断通过，但召回失败

先确认你跑的是哪一条命令。`powercontext doctor` 检查软件包、Server 是否活着、是否就绪。`powercontext doctor <host>` 只检查该 Agent 的 CLI 和有限的安装状态，不会探测 Server，也不会发真实提示词。先用前者确认 Server，再按该 Agent 的页面做一次真实召回。见[通用 Agent 总览](https://powercontext.mintlify.site/zh/common-agents/overview.md)。

### 6. Dashboard 是空的，数据其实在

没配 Dashboard 的 Scope 时，页面就是空的。配上和客户端相同的 `scope_id`，并确认同一个数据库 URL。步骤在[用 Dashboard 核对 Scope 统计](https://powercontext.mintlify.site/zh/basic-usage/dashboard.md)。

### 7. Preview 适配器装不上

Pydantic AI Agent 适配器是 **Preview**。PyPI 和当前 Git 子目录安装都不可用。第一次接入走 [LangGraph](https://powercontext.mintlify.site/zh/frameworks/langgraph.md) 或 [LangChain](https://powercontext.mintlify.site/zh/frameworks/langchain.md)，不要从 Preview 页开始。

### 8. 把内置 Skill 当成可导出 Skill

`project-context` 是 Agent 自带说明。`powercontext skill export` 才是托管 Skill (可复用的能力说明。内置、托管、投影和外部 Skill 不是同一种对象。)。OpenCode、DSH、Pi、Hermes、OpenClaw 不能导出。见[让 Agent 自己扩展能力](https://powercontext.mintlify.site/zh/common-agents/agent-self-extension.md)。

### 9. 把 Candidate 版本当成 Artifact Revision

改提案看 Candidate (待审提案。改提案走它自己的 version，批准后才出现不可变 Revision。) 的 `version`。批准后看 Artifact 的 `Revision`。两套号不能混用，混用会出现冲突。对照[让 Agent 自己扩展能力](https://powercontext.mintlify.site/zh/common-agents/agent-self-extension.md)。

### 10. 只要预览，却调用了 Handoff

`handoff_current_work` 会写一条边界 Source。讨论设计，或说 `preview and make no writes`，都不要调用它。见 [Codex](https://powercontext.mintlify.site/zh/coding-agents/codex.md) 和 [MCP](https://powercontext.mintlify.site/zh/basic-usage/mcp.md)。

### 11. Server 停了，却指望自动召回报错

自动召回、采集和可选刷新可以 fail-open，原任务应继续。你明确要求写 Memory、提交 Handoff (把当前目标、已验证进度、阻塞项和下一步交给接手者。不提交就还是临时包。)、做 Review 或导出 Skill 时，失败必须看得见。见 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)。

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

先处理最像的那一条。不要同时改好几处。

## 下一步

> [card] [跟着学习路径走](https://powercontext.mintlify.site/zh/start/learning-path.md)
>
> 按你的目标选一条路。先跑通，再决定要不要看下一条。

> [card] [启动本地 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)
>
> 先确认本地 Server 和数据目录，再判断是不是 Scope 或库换了。


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