配置模型与完整记忆

快速开始默认通过向导配置完整记忆。本页解释要准备哪些 API、哪些能力需要模型， 以及保存配置后仍要完成的策略和业务检查。

模型连接怎么选

运行 powercontext config init --language zh --output .env，选择完整记忆或自定义能力。 向导根据所选能力询问需要的连接；API 协议描述的是模型服务的接口，不是你正在使用哪个 Coding Agent。

后台能力默认共用配置的 Generation Provider，不会自动复用 Codex/Claude 的订阅会话或登录凭据。 基础记忆不要求独立 Generation API：Agent 可以通过 MCP 显式保存自己整理的内容，但 Server 不会因此自动处理普通 Source。

“OpenAI-compatible Chat Completions”“OpenAI Responses”“Anthropic-compatible Messages”是不同协议； 按模型服务商实际提供的接口选择。OpenAI-compatible 也可以指第三方服务，不表示必须购买某个 Agent 订阅。 向导不会验证 API key、额度、模型可用性或远程连通性；启动后的 ready 和真实处理才会检验这些条件。

Embedding 连接可以与 Generation 共用地址和凭据，但通常使用不同模型。 向量维度必须是所选 Embedding 模型实际支持的输出维度。Embedding Profile ID 是标识这套模型、维度和向量约定的名称， 不是额外 API key。首次使用可接受向导建议；复用已有向量数据时，必须保持其对应关系，不能随意改 ID 或维度来消除报错。

完整能力不等于每条对话都会生成所有制品

Memory、Topic Memory 和 Experience 各有独立检查周期；Profile 使用独立 cron。 向导给出的推荐值会写入本次配置，不是每种制品都固定每 60 秒完成一次。 Generation 单次请求超时、Worker 总超时和检查间隔分别控制不同事情，修改其中一项不会替代另外两项。

配置了完整能力之后，也不要把普通闲聊当作 Experience/Skill 的充分输入。 需要这些能力时，按经验工作流提供任务结果并完成相应审核。 Profile 审核行为见Scope 画像。

启动后检查

在 Server 终端执行：

powercontext config validate --env-file .env
powercontext server run --env-file .env

另一个终端只加载客户端文件：

set -a
. ./.env
set +a
powercontext ready
powercontext capabilities

Readiness 的数据库/Runtime 状态与已配置模型依赖都需要检查。degraded 不代表模型提取正常； 只有 auto, fts 检索而没有 vector, hybrid 时，检查 Embedding 连接、Profile 和维度。 不要在 Agent 终端加载包含模型凭据的 Server .env；客户端文件已经包含所需连接设置。

为 Scope 启用 Profile 策略

先按快速开始创建并绑定真实 Scope，重新加载客户端环境。 以下例子为 Codex 的 Scope 启用“生成后人工审核”；使用 Claude Code 时，将第一行变量换成 POWERCONTEXT_CLAUDE_SCOPE_ID。先读取现有策略版本；仅在策略不存在（404）时使用版本 0：

export POWERCONTEXT_TEST_SCOPE_ID="$POWERCONTEXT_CODEX_SCOPE_ID"
python3 - <<'PY'
import json
import os
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen

base = os.environ["POWERCONTEXT_CLIENT_SERVER_URL"].rstrip("/")
scope = quote(os.environ["POWERCONTEXT_TEST_SCOPE_ID"], safe="")
url = f"{base}/v1/scopes/{scope}/profile-policy"
headers = {
    "Authorization": "Bearer " + os.environ["POWERCONTEXT_CLIENT_API_TOKEN"],
    "Content-Type": "application/json",
}
try:
    with urlopen(Request(url, headers=headers), timeout=30) as response:
        version = json.load(response)["version"]
except HTTPError as error:
    if error.code != 404:
        raise
    version = 0
payload = json.dumps({
    "generation_enabled": True,
    "activation_mode": "review_required",
    "expected_version": version,
}).encode()
with urlopen(Request(url, data=payload, headers=headers, method="PUT"), timeout=30) as response:
    print(json.dumps(json.load(response), indent=2))
PY

如果其他操作同时修改了策略，版本冲突时重新读取后再更新。不要把 expected_version: 0 作为每次更新的固定值。 启用后按配置的 cron 处理有新 Source 的 Scope。审核模式先产生 Candidate，批准前不会替换正式 Profile； 启用策略本身不会立即生成内容。若需立即验证已有输入，可按Scope 画像调用 Profile flush。

验证真实提取与召回

主验收按快速开始完成：

1. Agent 普通输入进入绑定 Scope 的 Source。
2. Topic Memory 出现对应主题和证据。
3. 第二条相关输入进入 Source 后，检查主题内容或修订是否反映更新。
4. 新会话使用同一 Scope 召回并返回 citation。

如果需要单独诊断 Memory 自动提取，可在真实 Source 已入库后，对同一 Scope 调用：

curl -fsS -X POST "$POWERCONTEXT_CLIENT_SERVER_URL/v1/memory/flush" \
  -H "Authorization: Bearer $POWERCONTEXT_CLIENT_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"scope_id\":\"$POWERCONTEXT_CODEX_SCOPE_ID\"}"

核对返回游标是否推进，并查看该 Scope 的 Memory 与 Source 引用。idle 可能表示后台已处理， 不代表没有记忆；Memory flush 也不等于 Topic/Profile/Experience 的全部处理完成。 查看用量可运行 powercontext stats --scope-id "$POWERCONTEXT_CODEX_SCOPE_ID"。

为了让验收记录可复现，在发送测试输入前先分配一个来源标识，再检查返回的条目。列表响应包含 current_cursor， 每个条目包含 position、entry_id、source_refs 和 matched_by；这些字段可以区分采集到的证据与之后生成的制品。

SOURCE_ID="quickstart-$(date +%s)-$$"
echo "请将测试输入标记为来源：$SOURCE_ID"
curl -fsS "$POWERCONTEXT_CLIENT_SERVER_URL/v1/memory/entries/list?scope_id=$POWERCONTEXT_CODEX_SCOPE_ID" \
  -H "Authorization: Bearer $POWERCONTEXT_CLIENT_API_TOKEN"

更多检查见故障排查与完整配置参考。