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

# 安装并运行 Server

> 先把最小 Server 跑起来。第一次不要接模型。

先把最小 Server 跑起来。它没有生成或嵌入模型，但已经能保存你写下的 Memory (经过选择、以后还会用到的项目知识。)，做全文搜索，并通过 HTTP、Python Client 和 MCP 读写同一套数据。

第一次不要接模型。这样卡住时，只需要查安装、数据目录、Scope (决定这次请求读写哪一组数据。设错时通常不报错，只是搜不到。) 和连接。这条闭环通了，再加推理。否则模型提供方出问题，很容易被看成数据库或接入坏了。

![第一条闭环：写出 Memory，搜到它，再拿到带 Citation 的 PreparedContext。](https://mintcdn.com/powercontext/1t_ajifOEOG5YQjP/assets/basic-first-loop-zh.svg?fit=max\&auto=format\&n=1t_ajifOEOG5YQjP\&q=85\&s=dcaffb0b9aafe944300998e3d8c083d8)

> [!NOTE]
>
> 安装参数、接口说明和部署配置，以 [官方文档](https://oceanbase.github.io/powercontext/) 的最新发布版本为准。这页只帮你把本地 Server 跑起来，并确认它现在能做什么。

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

## 前置条件

当前写清的安装环境是：

* macOS 或 Linux；
* Python 3.11 及以上；
* Git；
* [`uv`](https://docs.astral.sh/uv/)。

PowerContext 支持 Python `<4.0`。

## 安装 CLI 和 Server

从当前 `master` 安装：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
```

`uv tool` 使用隔离环境，不会在当前目录留下仓库检出。`--force` 也用于更新：如果同一个 Git 依赖声明已安装，它会重新获取所选版本引用，而不是直接报告已安装。

本地学习可以跟着你正在读的那一页里的版本引用走。本页和通用 / 编程 Agent 安装配置用 `@master`，方便跟上当前教程。

可复现部署不要跟 `master`。先选定一个经过验证的提交，再让 CLI、Server 和宿主插件使用同一个版本引用。需要固定版本时写成完整提交哈希，不要在同一组命令里混用短哈希和长哈希。

> [!NOTE]
>
> `uv tool` 里的 `powercontext[client]` 不能被另一个 Python 项目直接导入。需要写客户端代码时，稍后还要把客户端附加依赖安装到那个项目自己的环境中。

## 启动本地 Server

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext server run
```

默认配置如下：

| 项目 | 默认行为 |
| - | - |
| 地址 | `http://127.0.0.1:8000` |
| Dashboard | `/` |
| Streamable HTTP MCP | `/mcp`；用法见[用 MCP 连接 Server](https://powercontext.mintlify.site/zh/basic-usage/mcp.md) |
| 数据库 | 用户数据目录中的持久 SQLite |
| Bearer 认证 | 关闭，仅适合默认本机回环地址使用 |
| 生成 / 嵌入 | 未配置 |
| 搜索 | `auto`、`fts` |

macOS 上，数据库通常位于：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
~/Library/Application Support/powercontext/powercontext.db
```

Linux 通常位于：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
~/.local/share/powercontext/powercontext.db
```

设置 `POWERCONTEXT_HOME` 后，默认数据库会放到该目录。换了数据目录或数据库 URL，你看到的是另一套库。这很像 Scope 丢了。

`Ctrl-C` 会正常关闭 Server。再次运行命令会打开同一个数据库。

## 检查运行状态

另开一个终端：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext doctor
powercontext ready
powercontext capabilities
```

三条命令问的不是同一件事。

### `doctor`

检查当前软件包、Server 存活状态和就绪状态。全部为 `ok` 时退出码才是 0。

如果存活状态失败，就绪状态会标为已跳过。`degraded` 也会让诊断返回非零，因为至少一个已配置推理检查没通过；这不等于数据库必然不可用。

### `ready`

区分：

* `ready`：所有已配置检查通过；
* `degraded`：可选推理检查失败，HTTP 仍为 200；
* `not_ready`：运行时或数据库不可用，就绪状态端点返回 HTTP 503。当前 CLI 会把这个 503 打印成 Server 错误，而不是完整展开 `not_ready` 响应；用 `doctor` 或直接检查 `/health/ready` 诊断依赖项。

### `capabilities`

最小 Server 应显示类似：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Source types: content
Artifact families: memory, experience, skill, handoff
Memory extraction: disabled
Experience generation: disabled
Managed Skill generation: disabled
External Skill Registry: disabled
Handoff generation: disabled
Search modes: auto, fts
Context versions: powercontext.prepared-context.v1
```

能力列表中出现某类 Artifact，不代表相应的模型生成功能已经开启。请以对应的能力布尔值为准。

打开 Dashboard：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
http://127.0.0.1:8000/
```

没配 Dashboard 的 Scope 时，页面就是空的。Dashboard 初始化失败只会记一条警告；HTTP API 和 MCP 还能继续用。要核对同一 Scope 的数字，按[用 Dashboard 核对 Scope 统计](https://powercontext.mintlify.site/zh/basic-usage/dashboard.md) 配上相同的 `scope_id`。

## 先验证不接模型时能做什么

最小 Server 可以完成：

* 采集 Source；
* 显式 Memory 记住、搜索、修订和停用；
* FTS；
* 类型化 Experience / Skill 提案与 Candidate Review；
* 已准备 Handoff 定稿、提交和继续；
* `PreparedContext` 构造，只要当前 Scope 有可召回内容。

它不能完成：

* Source 到 Memory 的模型抽取；
* Experience / Skill / Handoff 的模型生成；
* 向量 / 混合搜索；
* 模型驱动的重排序。

所以第一条闭环从你已经确认的 Memory 开始：写下来，用 `search_memory` 找到它，再通过 `prepare_context` 得到带 Citation 的 `PreparedContext`。先确认数据还在、Scope 对、Citation 在，再把模型提供方加进来。从 Source 抽取 Memory，以及用模型生成 Handoff，留到后面的页。

## 为 Python 项目安装客户端

在要运行示例的 Python 项目中：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv add \
  "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"
```

确认该项目使用 Python 3.11 或以上：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv run python --version
```

下一页的示例通过：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from powercontext.client import PowerContextClient
from powercontext.http import RememberMemoryRequest
```

导入公共 API。不要从 `powercontext.http._generated` 导入内部生成模块。

## `.env` 不会自动加载

PowerContext CLI 不会搜索当前目录的 `.env`。需要显式传入：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext server run --env-file .env
```

完整能力可以从配置生成器开始：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext config init --output .env
powercontext config show --env-file .env
powercontext config validate --env-file .env
powercontext server run --env-file .env
```

生成和调度器要分开配。配了生成模型，抽取能力会打开，但定时调度器不会自动开。你仍可以手动调用 `flush_memory`。

嵌入必须把模型、配置档 ID 和维度成组配齐。缺任何一项，配置校验应失败，而不是启动一套说不清的半向量模式。

## 认证与远程访问

默认配置只监听本机回环地址，所以关闭认证是可接受的本地开发设置。

绑定非本机回环地址时，Server 默认要求认证；否则必须显式启用不安全选项。Python Client 也拒绝访问非本机回环地址的明文 HTTP。生产和远程部署应使用 TLS 和 Bearer 令牌，不要把令牌放进 URL。

开启认证后，客户端从环境读取裸令牌：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_CLIENT_API_TOKEN="replace-with-token"
```

它会构造：

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer replace-with-token
```

## 启动时常见卡点

### `doctor` 显示 Server 不可达

确认 `powercontext server run` 还在跑，并检查 8000 端口有没有被占用。若用了自定义地址，把 `doctor` 自己的选项放在子命令后：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext doctor \
  --server-url http://127.0.0.1:9000
```

根命令的 `--server-url` 用于客户端内容命令，不会替代 `doctor` 的独立地址参数。

### 创建了 `.env`，能力仍没变化

启动命令有没有带 `--env-file .env`？CLI 不会自己去读它。

### `capabilities` 只有 `auto, fts`

Server 在只做全文搜索的模式下是正常的。向量或混合搜索的前提还没配齐。

### `ready` 是降级

看具体是哪一项依赖没过。不依赖那项推理能力的数据库操作可能还能用；需要该模型提供方的操作仍会失败。

### 重启后看不到旧数据

检查 `POWERCONTEXT_HOME`、数据库类型和数据库 URL 有没有变，再检查 `scope_id`。这三处都会换掉你看到的数据。对不上时，先看[排错](https://powercontext.mintlify.site/zh/start/troubleshooting.md)。

## 怎么知道跑通了

继续前确认这几件事：

* `powercontext doctor` 在最小配置下通过。
* `powercontext capabilities` 显示 `auto, fts`。
* Dashboard 能打开，或你已经明确关掉它。
* 示例 Python 项目能导入 `PowerContextClient`。
* 本教程用的稳定 Scope 是 `project:powercontext-101`。
* 下一条要做的事是：写出 Memory，用 `search_memory` 找到它，再通过 `prepare_context` 拿到带 Citation 的 `PreparedContext`。

## 下一步

> [card] [常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md)
>
> 用 Python Client 写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

> [card] [卡住时先对排错](https://powercontext.mintlify.site/zh/start/troubleshooting.md)
>
> 搜不到、页面是空的，或诊断过了还是不行，先打开排错。


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