排查问题¶

先执行：

powercontext doctor

该命令检查安装包、Server liveness 和 Server readiness；只有所有检查均为 ok 时才以状态码 0 退出。 degraded 表示仍可使用，但不算完整诊断成功。自动化场景可添加 --json，顶层结果和每个检查都会包含 ok 与 status。可单独检查可选的宿主集成：

powercontext doctor codex
powercontext doctor claude-code
powercontext doctor dsh

安装时无法读取 Git 地址¶

确认 Git 能够读取仓库：

git ls-remote https://github.com/oceanbase/powercontext.git HEAD

如果失败，请配置 Git 使用的 credential helper 或 SSH key，再重新运行 uv tool install。uv 使用 Git 凭据配置；PowerContext 不接收或保存仓库凭据。

找不到 powercontext、codex、claude 或 dsh¶

执行：

uv tool dir --bin
command -v powercontext
command -v codex
command -v claude
command -v dsh

必要时把 uv tool bin 目录加入 PATH。宿主 CLI 不可用时，powercontext setup codex、 powercontext setup claude-code 和 powercontext setup dsh 会报告错误，不会继续安装插件。

插件缺失或版本不一致¶

先在不涉及 Server 的情况下确认集成故障：

powercontext doctor codex

使用与工具一致的 ref 重新安装：

powercontext setup codex --source oceanbase/powercontext --ref <ref>
codex plugin list --json

然后开启新的 Codex 会话。如果提示词恢复和采集没有运行，请检查 /hooks。

对于 Claude Code，执行：

powercontext doctor claude-code
powercontext setup claude-code --source oceanbase/powercontext --ref <ref>
claude plugin list --json

然后开启新的 Claude Code 会话并检查 /hooks 与 /mcp。插件清单应只包含一个 UserPromptSubmit Hook 和一个 powercontext MCP Server。

如果 setup 在创建新的 user scope 对象时失败，它会尝试只删除本次调用创建的插件与 Marketplace 项， setup 前已有的对象会保留。修正命令报告的 Claude CLI 或仓库错误后，重新执行同一个 setup 命令。

对于 DeepSeek Harness，执行：

powercontext doctor dsh
powercontext setup dsh --source oceanbase/powercontext --ref <ref>
dsh --profile web --dump-config

然后开启新的 DeepSeek Harness 会话，并确认 dump-config 含有 id: powercontext-dsh。DSH 插件目录必须包含 lib/index.js。

Server 检查失败¶

启动服务：

powercontext server run

如果 8000 端口已被占用，请停止冲突进程。若 Server 有意使用其他地址，可在检查时传入 base URL：

powercontext doctor --server-url http://127.0.0.1:9000
powercontext --server-url http://127.0.0.1:9000 ready

随附的 Codex 和 Claude Code 插件默认使用 8000 端口。liveness 失败表示进程无法响应健康请求，此时不会继续检查 readiness。HTTP 503 的 not_ready 表示 Runtime 或数据库无法接受工作；HTTP 200 的 degraded 表示已配置的 推理能力异常，但数据库操作仍然可用。Human 与 JSON 输出都会保留 Server 返回的各项检查状态。

Server 无法打开数据库¶

数据库在 Server 启动时创建，而不是在工具安装时创建。先检查 Server 的启动错误，再运行 powercontext doctor。

如需指定位置：

export POWERCONTEXT_HOME=/path/with/write/access
powercontext server run

每次启动或诊断该实例时都应使用同一个环境变量。对于文件型 SQLite 数据库，PowerContext 会创建缺失的父 目录。

推理服务 readiness 检查失败¶

配置 generation 或 embedding 后，Server readiness 会向 provider 发起一次最小化真实请求。这样可以发现只有 实际请求时才能确认的凭据或 endpoint 问题，包括 base URL 遗漏 provider API 前缀。稳定状态包括 ready、 unavailable、timeout 和 misconfigured；响应不会包含凭据、provider 响应正文或已配置 URL。

推理检查失败时，overall readiness 为 HTTP 200 的 degraded，不会使整个 Server 退出流量。ready 和 misconfigured 会缓存 300 秒；临时的 timeout 和 unavailable 会在 30 秒后重试。并发健康请求共用同一次 刷新。修改静态配置后如需立即检查，请重启 Server；否则等待缓存过期。

Memory 可以显式写入，但采集的提示词没有生成 Memory¶

显式 Memory 操作不需要模型；把采集的 Source 证据转换为 Memory 则需要。请配置 generation model 及其 provider 凭据，然后启用 scheduler 或显式 flush 对应 scope。查看 Server 当前提供的能力：

powercontext capabilities

Memory extraction: disabled 表示 Server 没有 generation model。

Server 停止后编程 Agent 仍继续工作¶

这是预期行为。两个 Prompt Hook 都会 fail open，Memory 故障不能阻塞普通 Codex 或 Claude Code 工作。 重启 Server 后即可恢复召回和采集，现有数据库会被自动重新打开。

Codex 没有注入召回上下文¶

查看 Hook 在 stderr 输出的单行 JSON 事件。empty 表示 Runtime 没有为本轮准备上下文。version_mismatch 表示已安装插件要求 POST /v1/context/prepare，但 Server 尚未提供该接口；请从同一个 ref 重新安装插件和工具 并重启 Server。server_unavailable 和 invalid_response 分别表示传输与 contract 问题。诊断事件会刻意 省略 query 与准备好的上下文正文。

执行 powercontext capabilities，确认 Context versions 中包含 powercontext.prepared-context.v1。

Claude Code 没有注入召回上下文¶

先区分安装问题和 Server 健康问题：

powercontext doctor claude-code
powercontext doctor

第一个命令只检查 Claude CLI 和已启用插件，不连接 Server；第二个命令检查 Server liveness 和 readiness。 然后查看 Hook 在 stderr 输出的单行事件。Claude Code 使用与 Codex 相同的 Prepared Context contract， component 为 powercontext.claude_code.recall：

诊断不会记录 token、query、scope、Prepared Context 正文或响应正文。Prompt 采集与召回彼此独立：采集失败 不会抑制有效上下文，召回失败也不会抑制采集。

Claude Code MCP 认证失败¶

Hook 与 MCP headersHelper 都从启动 Claude Code 的进程环境读取 POWERCONTEXT_CLAUDE_AUTHORIZATION。停止当前进程，导出完整 header，再重新启动：

export POWERCONTEXT_CLAUDE_AUTHORIZATION="Bearer $POWERCONTEXT_LOCAL_TOKEN"
claude

不要把 token 加入 .mcp.json、Server URL 或插件选项。重启后使用 /mcp 确认 powercontext Server 已连接。