排错

搜不到、页面是空的，或诊断过了还是不行？先对照下面几条。

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

安装参数、接口说明和部署配置，以 官方文档 的最新发布版本为准。这页只帮你判断卡在哪一类问题上。

1. Scope 对不上

   客户端、Dashboard、Agent 环境变量和 --scope-id 必须逐字相同。Scope 是字面值。project:powercontext-101 和 project:powercontext-101:<uuid> 不是同一个 Scope。对照 Scope。

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

   POWERCONTEXT_HOME 或数据库 URL 一变，你看到的是另一套库。这很像 Scope 丢了。先对安装并运行 Server 里的数据目录，再对 Scope。

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

   empty 表示这个 Scope 当前没有可召回内容。401/403 是认证失败。这时不要注入上下文，也不能假装这个 Scope 没有 Memory。见 fail-open 和 MCP。

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

   采集 Source 只表示这件事发生过。它不会自动变成长期 Memory。没有生成模型时，Source 会保持待处理。用 remember_memory 写你已经确认的事实，或读 Source 与 Memory。

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

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

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

   没配 Dashboard 的 Scope 时，页面就是空的。配上和客户端相同的 scope_id，并确认同一个数据库 URL。步骤在用 Dashboard 核对 Scope 统计。

7. Preview 适配器装不上

   Pydantic AI Agent 适配器是 Preview。PyPI 和当前 Git 子目录安装都不可用。第一次接入走 LangGraph 或 LangChain，不要从 Preview 页开始。

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

   project-context 是 Agent 自带说明。powercontext skill export 才是托管 Skill。OpenCode、DSH、Pi、Hermes、OpenClaw 不能导出。见让 Agent 自己扩展能力。

9. 把 Candidate 版本当成 Artifact Revision

   改提案看 Candidate 的 version。批准后看 Artifact 的 Revision。两套号不能混用，混用会出现冲突。对照让 Agent 自己扩展能力。

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

    handoff_current_work 会写一条边界 Source。讨论设计，或说 preview and make no writes，都不要调用它。见 Codex 和 MCP。

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

    自动召回、采集和可选刷新可以 fail-open，原任务应继续。你明确要求写 Memory、提交 Handoff、做 Review 或导出 Skill 时，失败必须看得见。见 fail-open。

自动帮你找回上下文失败时，当前任务还应继续。你明确要求写入 Memory、提交 Handoff、批准或导出时，失败必须能看见。完整说明见 fail-open。

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

​

下一步

跟着学习路径走

按你的目标选一条路。先跑通，再决定要不要看下一条。

打开学习路径

启动本地 Server

先确认本地 Server 和数据目录，再判断是不是 Scope 或库换了。

核对数据目录