配置选项

Windows 支持为 experimental。

PowerContext 进程启动时从环境变量读取配置。当前工作目录存在 .env 时，server run 会自动加载该文件。使用 --env-file <path> 可改为加载指定文件且不再合并 .env；使用 --no-env-file 可禁用文件加载。server run 的配置 优先级为：CLI 参数、进程环境变量、所选环境文件、默认值。Agent 宿主可按自身规则加载环境文件。

生成、脱敏查看、校验和启动配置文件的完整流程见配置 Server 环境。所有环境 文件都应视为包含机密的部署产物。

service install 还要求该文件是当前用户拥有的普通非符号链接文件，且 group 和 other 均无访问权限。服务会记录文件 身份；文件被替换或其 owner、权限、内容发生变化后会拒绝启动。确认修改是预期行为后，请重新执行 service install。

Atomic Memory

创建、搜索、四态和恢复示例见使用 Atomic Memory；已有数据库的升级步骤见 停服迁移。

恢复预览使用显式共享签名密钥。所有可能生成或验证 token 的进程使用相同 secret 和 key ID：

未配置 secret 不会生成随机进程密钥。更换 secret 或 key ID 后，旧 token 无法验证，应重新预览。 带 token 的恢复遇到变化会返回 preview_stale，不会自动重新解释意图；重试预算也不处理提交结果未知的连接失败。

Source 处理先生成候选，再枚举满足权限、标签及检索资格的相关 active 记忆。fts 枚举全部合格匹配，vector 枚举 阈值内全部结果，hybrid 合并两者。总候选不会按 comparison batch size 或 token 限额截断。 比较输入过大时缩小单批，直到所有候选都处理完；连单个对象或完整抽取输入都超预算时窗口失败，不部分提交或推进 cursor。 开启 fallback 会改变相关召回依据，应显式选择；默认错误会保留当前窗口供排查和重试。

Atomic Memory 没有旧集合容量预算或 compact 操作。旧 MEMORY_MAX_ACTIVE_ENTRIES、MEMORY_MAX_MANIFEST_ENTRIES、 MEMORY_MAX_MANIFEST_BYTES 和 MEMORY_COMPACTION_* 设置仍可解析，但不限制新记忆或启用压缩。 MemoryWriteGate 采用 fail-open 策略，只裁决写入，不修改权威历史。若决策请求可能发送到 hosted 后端，必须同时设置 MEMORY_WRITE_GATE_PRIVACY_BOUNDARY=hosted_redacted 和显式的 MEMORY_WRITE_GATE_SANITIZER=known_secrets。 内置 sanitizer 覆盖已知的敏感环境变量/Codex 值及有限的 provider 前缀，不是通用的 PII 或口令检测器。sanitizer 默认是 none；hosted-redacted 组合在未选择 sanitizer 时会以命名配置错误失败。 Atomic Memory 的标签仍遵守每个 Artifact 最多 32 个的限制。合并输入标签的并集超过此上限时，整笔合并失败； Source 抽取窗口也不会部分提交或推进游标。

用户数据

POWERCONTEXT_HOME 可覆盖已安装 Server 使用的数据目录：

export POWERCONTEXT_HOME=/srv/powercontext

未覆盖时，默认目录为：

• Linux：$XDG_DATA_HOME/powercontext，未设置时为 ~/.local/share/powercontext；
• macOS：~/Library/Application Support/powercontext；
• Windows：%LOCALAPPDATA%\\powercontext。

默认 SQLite 数据库是该目录下的 powercontext.db。后台处理器的意图与调度检查点保存在同一数据库中。 已有部署须先完成停机迁移。

内置 SQLite 后端要求 Python 链接的 SQLite 库（sqlite3.sqlite_version）为 3.38.0 或更新版本， 启用 FTS5、JSON 函数，并为向量检索加载 sqlite-vec。这沿用 Memory 设计约定的后端下限，包括原生向量 IN 过滤能力。 旧版本会在初始化数据库或接受写入之前被拒绝。

Server

Server 配置使用 POWERCONTEXT_SERVER_ 前缀。

每个 Server 进程默认最多接纳 64 个并发外部 HTTP 请求，包括 REST、MCP、Dashboard 和健康检查。 从读取请求体到响应结束始终占用一个名额，流式响应同样计入。容量满时立即返回 503、 错误码 server_overloaded 和 Retry-After: 1，不排队，也不读取被拒绝的请求体。异常和取消都会释放名额。 可信的进程内 MCP 到 HTTP 转发沿用外部请求的准入，不重复计数。

Server 在下游解析之前按实际收到的字节限制请求体，默认上限为 16 MiB，分块上传同样受限。 声明的 Content-Length 过大会提前拒绝；缺少该头或声明较小长度都不能绕过实际字节检查。 超限返回 413 和错误码 request_too_large，读取在首个超限 chunk 处停止。这是可配置的部署级上限， 不改变领域字段约束。默认值可容纳当前最大 5 MiB 的 Skill archive，其 base64 最长为 6,990,508 个字符， 并为 JSON envelope 留出空间。调低上限可能拒绝原本符合领域约束的操作。两个 HTTP 上限都必须是正整数。 应按可用内存调整：64 个请求各保留 16 MiB，请求体本身就需要 1 GiB，尚未包括解析和业务开销。 交给下游时会短暂复制一次已接收的请求体，随后释放输入缓冲。 按请求来源设置速率配额、上传超时、连接上限和跨 Server 进程的总额度由反向代理负责。

MCP 使用 stateless Streamable HTTP，每次工具执行都采用当前请求的认证身份，不发放传输 Session ID， 也不保留跨请求恢复的 SSE 会话。从 stateful Server 升级后应重新连接客户端；已持久化的 Scope、Memory 和 Handoff 数据不受影响。长响应在结束前仍占用一个 HTTP 名额，应为并发请求预留其他名额。

召回通道权重表示相对比例，应用于 Atomic Memory 和 Topic Memory，只在 hybrid 候选通过各通道准入下限后生效。 单通道搜索保持无权重行为；auto 只有在选择 hybrid 搜索时才应用权重。Atomic Memory 的 matched_by 和 recall gate 相关度不包含零权重通道；Topic Memory 则为正权重通道选中的 Topic 保留零权重通道的证据。 同比例缩放两个值不会改变结果。将其中一个设为 0 会从 hybrid 融合中排除该通道，但提高权重不能恢复融合前已被拒绝的候选。零权重不会关闭该通道的检索和准入工作： vector 查询仍可能生成 embedding，检索与准入计数也仍包含零权重通道。如果 Topic 或 Atomic Memory Artifact 搜索请求显式提供自己的 fusion 参数，它会完整取代部署级召回权重；只有请求未指定 fusion 时，部署级权重才生效。归一化后，每个非零通道权重必须不低于 IEEE 754 binary64 最小正规数（2.2250738585072014e-308），更小的值会在启动时被拒绝。只有显式配置 0 才表示关闭该通道的融合贡献。调整权重时应同时评估 recall gate 轮次、语义准入下限和历史 Topic 候选选择，不要将这些配置孤立调整。特别是，提高 FTS 权重可能使 Topic 的归一化分数跨过 POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_HISTORY_RRF_THRESHOLD（默认为 70），从而改变传给规划器的历史 Topic 集合。

召回充分性门控默认关闭。启用后，Runtime 在 prepare_context 阶段评估首轮候选的数量、来源家族覆盖、最优候选分数和词法 覆盖；判定为不足时最多追加两轮搜索，并在每轮放宽候选准入的语义相似度下限。门控判断本身不调用模型，追加轮次沿用同一请求的 Scope、家族、条数限制和上下文预算，并复用已经生成的查询向量。第一轮和第二轮的语义相似度下限必须保持递减顺序，违反该顺序 会导致启动失败。启用后可能增加检索次数和延迟，请在自己的数据上评估召回结果和延迟变化。

门控产生 RecallEffort 时，关系型 Runtime 向 pc_recall_effort_daily 累加一次观测，主键为 (scope_id, usage_date, policy_id, assessment)，日期使用 UTC。计数包含已提交的搜索轮数、扩展动作、候选池大小、 搜索报告的额外推理调用，以及最终字节预算造成的截断和丢弃。两个丢弃子类之和等于 dropped_items，非法计数在写库前拒绝。 表中只保存主键维度和计数，不包含条目身份、查询、提示词、引用或正文。该聚合仅供内部使用，不进入统计概览或 HTTP/MCP 响应。

召回工作量记录在 POWERCONTEXT_SERVER_RUNTIME_MODEL_USAGE_WRITE_TIMEOUT_SECONDS 预算内只尝试一次写入。 写入失败时记录安全诊断，保持已经准备好的上下文。请求取消会等待该事务完成原生清理后再传播，保护共享的内存 SQLite 数据库。 调用方显式传入的 recall_effort_sink 替代关系型记录器；关闭门控时两者都不调用。已有 SQLite 和 OceanBase 数据库通过正常的 增量建表路径补建缺失的关系表。

模型用量记账是尽力而为的，且永不阻塞模型调用。每个 Runtime 拥有一个有界记账器：接收记录时不产生任何 I/O，随后在独立的短事务 中写入。因此统计故障、队列写满，或超出该记录自身预算的锁等待，只会丢弃该条记录并留下诊断日志，而不会让产生它的操作失败。 操作完成、读取统计以及关闭时，都会在有界等待内冲刷已经接收的记录。业务写入等待该时长后失败属于设计行为：SQLite 同一时刻只允许一个写入者，并发写入者持锁超过配置值时，等待中的业务写就会 报 database is locked。这正是多写入者部署需要提高 POWERCONTEXT_SERVER_DATABASE_BUSY_TIMEOUT_MS 的原因；同样的锁压力 已不再传到用量记账，用量记录只会被丢弃，而不会让产生它的操作失败。

Topic Worker 对尚未推进的 Scope Cursor 强制使用持久额度：跨全部重试最多 3 次尝试、512 次预留 provider 请求和 64,000,000 个估算 token 容量单位。Window 的 canonical evidence（包含 metadata）最多 4,194,304 个字符，并限制 嵌套复杂度。耗尽后保留 Source、Cursor、Pending 和同 Scope 尾部，停止后续 provider 调用；flush 和重启均不重置。 运维可检查 pc_topic_memory_work_budgets 与结构化错误以明确修复。

Topic generation 只允许有界标量设置：max_tokens、temperature、top_p、top_k、seed、presence_penalty、 frequency_penalty、timeout、openai_reasoning_effort、openai_text_verbosity、service_tier、 openai_service_tier、anthropic_service_tier、anthropic_effort；Topic Embedding 只允许 dimensions 和 truncate。 对于 openai-chat:<model> 生成，extra_body 唯一允许的例外为 {"chat_template_kwargs":{"enable_thinking":false}}，要求严格的布尔值，且两层均不能包含其他字段。 background、隐藏历史、native tools 和其他形式的 extra_body 会使 Topic 处理不可用，普通推理仍可继续；显式配置自动 Topic 调度时 则启动失败。支持的 provider 前缀为 openai、openai-chat、 openai-responses、anthropic、azure、azure-responses、deepseek、openrouter，以及本地 test 模型；Embedding 还必须受其 SDK adapter 支持。Topic 禁用 SDK transport 重试和自动 continuation，非 Topic 推理保留既有设置行为。

未设置 cursor 签名密钥时，使用文件 SQLite 的 Server 会在数据库旁创建权限受限的密钥文件；其他持久化后端会在 PowerContext 用户数据目录创建密钥。内存 SQLite 使用进程内密钥。多副本部署必须为所有副本配置相同的 POWERCONTEXT_SERVER_CURSOR_SIGNING_SECRET，这样重启或下一请求落到其他副本后，已签发 cursor 仍然有效。 在已签发 cursor 仍需有效期间，不要泄漏或轮换该值。

设置 HttpConfig.uds、POWERCONTEXT_SERVER_HTTP_UDS 或 server run --uds /absolute/path/core.sock 可以选择 UDS。 也支持 JSON 形式 POWERCONTEXT_SERVER_HTTP='{"uds":"/absolute/private/core.sock"}'。同一来源中， 扁平的 HTTP_UDS 优先于 JSON；server run 和 Agent 接入采用的进程 HTTP 配置优先于环境文件。 向导和模板会拒绝待编辑文件或进程有效配置中的 UDS， Agent 接入不会为 UDS listener 推断 TCP URL。 CLI 参数优先于环境配置；有效配置已选择 UDS 时，显式传入 --host 或 --port 会被拒绝。UDS 支持 all 和 api role （后者仍要求 OceanBase），不支持 background。个人服务及本机 ops/Desktop 管理要求 TCP。目录 owner、权限、安全重启 和鉴权客户端示例见监听 Unix domain socket。UDS 不会启用设计中的 Rust 网关，也不会改变 API 授权规则。

Access Control 默认关闭。在 enforced 模式下，API 和 MCP 请求必须通过所选 Authentication Provider 建立 Principal； liveness 和 readiness endpoint 仍然公开。内置 static-bearer Provider 接受 Authorization: Bearer <token>，UDS 请求也适用。TCP 上的明文 HTTP 仅在 loopback 地址（localhost、::1 及 127.0.0.0/8 网段内的任意 地址）上受信任。当 Server 绑定到非 loopback 地址且鉴权关闭时会拒绝启动；此时应启用鉴权、改回绑定 loopback，或在 TLS 由上游终止或网络本身受控的场景下， 显式设置 POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true 主动选择接受。通过网络暴露启用鉴权的 Server 前必须配置 TLS。

POWERCONTEXT_SERVER_ACCESS_MODE 是唯一正式开关。disabled 在可信本地边界内跳过授权决策；enforced 启用统一策略执行点、 Binding 和审计。Authorization 默认使用 builtin，实现替换通过 create_server_app(access_control=...) 注入；Authentication 通过 create_server_app(authentication_provider=...) 注入。若没有注入 Authentication Provider，Server 只接受旧 AUTH_TOKEN 作为静态 Bearer 兼容认证，并把固定的 server-token Principal 初始化为内置管理员。两者都没有时拒绝启动。 旧 AUTH_ENABLED=true + AUTH_TOKEN 配置会自动映射为 ACCESS_MODE=enforced。

Authentication 负责建立 Principal，Access Control 负责判断该 Principal 能做什么。Principal ID 是部署内全局唯一且不复用 的标识；description 只用于展示，不参与身份判定。内置静态 token 始终只代表一个 service Principal，因此不能区分 用户 A 和用户 B。兼容静态 token 会为这个 Principal 显式写入 Server 与各 scope 所需的 role。需要让不同用户或 group 获得不同权限时，应注入部署侧 Authentication Provider 与相应的 AccessControlService。

Memory、Topic Memory、Experience、Profile 的 Source 后台处理优先使用 ACCESS_BACKGROUND_PRINCIPAL_ID 指定的 service Principal， 缺省时回退到固定静态 Principal。该身份须在每个被处理的 scope 上拥有 scope.contribute，并拥有被修改的现有 Artifact 的写权限。 新 Entry、Artifact 与 Candidate 的 owner 或 owner attestation 和处理完成确认同事务提交。 enforced 部署启用后台能力时，若身份或授权 provider 无法在子进程重建，启动会失败；关闭自动 schedule 仍需恢复已接受的工作， 因此不能免除此检查。内置 provider 支持重建；注入的 provider 和模型对象仍可用于关闭后台能力 （ARTIFACT_PROCESSING_FAMILIES=[]）的同步 SDK/Server 操作。

Dream 在 Experience/Skill Worker 内重建原请求者的当前权限，Candidate 的归属仍是原请求者。 后台 service Principal 的权限不会替代该身份。OceanBase 分离部署可在无模型的 API 进程声明 ARTIFACT_PROCESSING_FAMILIES=["experience","skill"]，后台声明相同能力并配置模型；各进程的自动周期只能引用已声明的 Family。 SQLite 使用 all。Dream 的模型标识在首次执行时固定，关闭自动周期不会阻止已接受的显式 Dream 请求完成。

未配置 Server 身份的 SDK Worker 不需要 Server 授权依赖。内置后台 Worker 使用内置 Source Definition。 自定义 Source Registry 须为每个启用的 Family 提供自定义 processing binding，或通过 ARTIFACT_PROCESSING_FAMILIES=[] 关闭内置后台 Family；否则启动在接受工作前失败。 仅关闭 schedule 不足以满足要求，因为显式请求仍会启动 Worker。同步 SDK Context 和纯 API 组合仍支持自定义 Source Registry。

受鉴权保护的 /metrics 暴露 powercontext_server_artifact_processing_* 指标，使用有界的 family 标签，并按需增加 state、outcome、category 或 reason，涵盖 Worker 额度、 ready/retry 队列、未确认 Scope 数、发现与调用耗时，以及完成、失败、超时次数。未确认数反映最近一次发现结果；计数器随 Supervisor 实例重建而重置。新鲜度、状态、attempt/确认与告警语义参见日志、指标与 Tracing。

GET /v1/capabilities 的 extraction 对象分别返回配置、后台执行状态和本地观察记录。 读取快照不查询数据库、不调用模型，也不生成整个管道的健康结论。 powercontext capabilities 会打印同样的事实。缺少诊断时输出 unavailable，Supervisor 角色为空时输出 absent，未知值输出 unknown。成功和失败时间是历史观察，不是当前健康结论。--json 仍原样返回 Server 响应。

• configuration 在本地已装配提取模型、自定义管道或已注册本地 Memory worker 时为 configured， 均不可用时为 unconfigured。注册不验证凭证或连通性；外部执行返回 unknown。
• background.location 为 local、external 或 none。本地 Supervisor 的 role（leader 或 standby） 与 state（running、degraded 或 stopped）独立，standby 属于正常状态。Worker 崩溃时，Supervisor 仍可能正常运行并安排重试。automatic_processing_enabled=false 仍允许显式处理请求。 外部执行的运行状态和调度配置未知；没有运行中的本地 Supervisor 时，role 为 null。
• observation.since 标记本次 Runtime 本地观察窗口的起点，包含其 Memory 子进程。 status=unverified 表示尚未观察到执行结果或控制故障，observed 表示已有记录。 last_success_at 记录成功的非空 flush 或已确认的 Worker 调用；last_failure 记录安全的 code、stage 和 occurred_at，例如 inference 阶段的 model_timeout 或 worker 阶段的 worker_crash。 通用错误保留观察到故障的边界（flush 或 worker），不推断为模型故障。

成功与失败记录独立：Scope B 成功不会清除 Scope A 的失败，也不证明 A 已恢复。 历史失败同样不表示故障仍未解决。观察记录在 Runtime 重启后清空，不证明模型连通性或远端 Worker 健康。 通过结构化日志定位具体 Scope 的失败与重试，通过现有指标观察队列和处理进度；本地 ready 数不代表全局 Source 积压量。

远程和多用户部署必须使用 enforced。此模式下，HTTP、MCP 和 metrics 共用同一个 Server PEP。/v1/access/me 返回 server/scope/artifact Resource Kind、Provider 的 batch/list/relationship 能力与 Family profile。Managed Skill 的 导出和安装不再引入单独的 Access action：接收者先获得逻辑 Skill identity 上的 artifact.read，再自行决定是否以及如何 安装一个精确 Revision。

内置 Access schema 使用配置好的 SQLite、seekdb 或 OceanBase，但由 Server 独立持有，不进入 Runtime 领域。自定义部署 可以向 create_server_app 注入 AccessControlService。内置的可写外部 adapter CasbinAuthorizationProvider 使用 embedded Casbin 判定固定 action vocabulary，并把 canonical Binding Store 作为持久化 adapter，因此在不维护第二份影子 策略的前提下支持 point/batch check、safe resource filter、create/revoke、过期和 CAS。组装时将它同时作为 decision provider 与 relationships，relational repository 仍作为 audit store。

AuthZenAuthorizationProvider 是对接 OpenID AuthZEN Authorization API 1.0 evaluation/evaluations endpoint 的 decision-only adapter。其 capability 应配置为 multi_requirement_check=true、relationship_management=false 和 safe_resource_filtering=false；此时 self-service Binding mutation 和授权资源列表会返回 503，而不会虚报不安全的能力。 该 adapter 只接受 HTTPS endpoint 或 loopback HTTP，拒绝 URL 内嵌 credential，也不会把 PDP response body 或原始错误 暴露出去。authentication middleware 仍必须绑定不透明的 PrincipalRef；scope_id 只用于资源分区，不能建立身份。

Python Client 和 CLI 对一般出站请求应用相同规则：配置的明文 http:// Server URL 仅接受 loopback 主机；远端 Skill Receiver 的内部 PoC 显式例外见下文。当代码的 http:// base URL 只是路由标签、实际传输是安全的，例如进程内 ASGI 应用、Unix domain socket 或由代理终止 TLS 时，必须自行传入 http_client 并显式设置 trust_transport_security=True。

安全的 Docker 和远程访问配置见部署 Server。

Server 默认把启动目录作为 workspace，并自动提供两个可写的本机项目级目标：Codex 使用 <workspace>/.agents/skills，Claude Code 使用 <workspace>/.claude/skills。目录不存在时不会报错，只有显式发布操作 才会创建目录。以 systemd、容器或其他不保证工作目录的方式启动时，应设置一次 POWERCONTEXT_SERVER_WORKSPACE。

远端技能接收端需要通过稳定的外部入口连接时，在 Server 上配置 POWERCONTEXT_SERVER_PUBLIC_URL。否则注册命令可以使用远端命令行已经配置的服务地址。

一期 PoC 如果运行在受保护的内部测试网络，可以让 Server 和 Receiver 双端显式同意直连 HTTP：Server 设置 POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true，并用 POWERCONTEXT_SERVER_PUBLIC_URL 公布 http:// 地址； Receiver 注册时同时传入 --allow-insecure-http。 Server 未打开开关时，远端接口仍拒绝非 loopback HTTP；Receiver 未传参数时，CLI 会在发送一次性注册口令之前拒绝 该 URL。许可会写入权限为 owner-only 的 Receiver 配置，因此 remote-watch 和 systemd user service 会沿用同一策略， unit 文件不需要保存凭据或额外参数。该开关不提供 TLS、网络隔离或防窃听能力，不能用于公网或不可信网络；长期部署 应使用 HTTPS。

export POWERCONTEXT_SERVER_HTTP_HOST=0.0.0.0
export POWERCONTEXT_SERVER_PUBLIC_URL=http://powercontext.internal.example:8765
export POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true
export POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true
powercontext server run

# 在远端项目中：
powercontext --server-url http://powercontext.internal.example:8765 \
  skill remote-enroll --workspace "$PWD" --install-service --allow-insecure-http

示例中的非 loopback opt-in 与 Receiver 传输例外彼此独立：它表示操作者接受该监听器上的所有 Server route 在没有 Server 级 Bearer token 时可达。部署条件允许时，应优先启用鉴权，或在仅绑定 loopback 的 Server 前终止 TLS。

Handoff Report API route 独立默认启用。Selection、检查和导出步骤见 使用 Handoff Report。

默认 all 角色会启动 Artifact Processing Supervisor。OceanBase 部署可以拆分 api 和 background； powercontext server run --role background 在启用指标时提供 /metrics 和公开的 /health/live，使用 POWERCONTEXT_SERVER_HTTP_HOST 和 POWERCONTEXT_SERVER_METRICS_BACKGROUND_PORT（默认 8001）， 不提供业务 API、MCP、Dashboard、OpenAPI 或 /health/ready。 /metrics 使用与 API 宿主相同的认证及 server.observe 授权。同机 API 与后台进程应使用不同端口。 POWERCONTEXT_SERVER_METRICS_ENABLED=false 时后台不打开 listener。多个后台候选者通过数据库 Lease 自动选出一个 active Leader。SQLite 与嵌入式 seekdb 只支持单进程 all。未设置正数间隔时，Topic Memory 自动波次 保持关闭；显式 flush 工作的恢复不依赖该间隔。Topic Worker 要求使用文件 SQLite；内存 SQLite 配合 generation model 的配置会在声明处理能力之前被拒绝。请通过 POWERCONTEXT_SERVER_DATABASE_URL 指定持久数据库路径，例如 sqlite+aiosqlite:////srv/powercontext/runtime.db。Memory、Topic Memory、Experience、Profile 均使用统一 Supervisor，OceanBase 拆分角色也可启用其周期。 SQLite 和 embedded seekdb 仍要求单宿主 all。两模式均保留逐 Family 独立额度和总超时，不借用其他 Family 空闲额度。 关闭自动准入仍恢复已接受请求。API 与后台须保持 mode、注册 Family 和可触发能力一致；模型仅在执行端必需。 切换模式须协调停机迁移，不能混用模式启动。 显式同时配置的新旧别名值不同时拒绝启动，同值接受。

普通 Runtime 启动会初始化并恢复所配置的检索索引。Topic Worker 复用该数据库，不再为每个 Window 重建无关的 Memory/Experience 检索投影；Topic 索引校验与发布守卫仍然执行。如果空库切换了 Topic 检索形态或 Embedding profile，应使用相同配置重新打开已有 Runtime；旧 Runtime 会以 retrieval-shape 错误拒绝 Topic 搜索、精确读取和 当前 Head 浏览，而不是读取另一个向量空间。

普通 Runtime 启动会初始化并恢复所配置的检索索引。Topic Worker 复用该数据库，不再为每个 Window 重建无关的 Memory/Experience 检索投影；Topic 索引校验与发布守卫仍然执行。如果空库切换了 Topic 检索形态或 Embedding profile，应使用相同配置重新打开已有 Runtime；旧 Runtime 会以 retrieval-shape 错误拒绝 Topic 搜索、精确读取和 当前 Head 浏览，而不是读取另一个向量空间。

指定 SQLite 路径并启用定时提取的示例：

export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/runtime.db
export POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=30
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
powercontext server run

OPENAI_API_KEY 等 provider 凭据由所配置的推理 provider 读取。不要把密钥放入命令行参数、文档或 Memory。请把 provider:model-name 替换为 Pydantic AI 支持的模型标识。定时提取需要同时配置 generation model 和 POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS；显式 Memory 写入不需要这两项配置。

默认的 coding 抽取 profile 保留跨任务工作上下文，例如偏好、决策、约束、昂贵事实和未完成进度。当产品 需要从对话证据中保留可独立回答的人物事实、关系、事件、精确日期、列表和历史状态时，可选择 conversation：

export POWERCONTEXT_SERVER_RUNTIME_MEMORY_EXTRACTION_PROFILE=conversation

profile 只影响后续 Source 处理，不会重新解释已有的 Memory revision。

当宽范围 Hybrid recall 比一次额外结构化 generation request 的延迟和 token 成本更重要时，可以启用面向回答的 Memory rerank：

export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED=true
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT=30

Rerank 默认关闭。启用后，Runtime 会召回并融合配置的候选池，再使用 temperature 为 0 的 generation model，选择不超过 search request 最终 limit 的结果。它不会修改已存储 Memory 或索引。Provider 与结构化输出失败仍作为 inference error 显式返回；如果搜索必须独立于模型可用性，请关闭 rerank。算法、并发与 API 边界见 RFC 0080。

内置 reranker 是 LLM listwise reranker，不是独立的 cross-encoder protocol。默认复用 generation model 及其 provider settings。设置 POWERCONTEXT_SERVER_INFERENCE_RERANK_MODEL 后，该 LLM operation 可以使用独立的 model、base URL、 headers、settings、timeout 和 request limit。

Python 部署可以把可选的 JevMemoryReranker 通过 open_builtin_runtime(memory_reranker=...) 注入 Runtime，使用 JevRerankConfig 配置独立 API key、System One endpoint 和固定模型版本，例如 jev-1.13.0，并由调用方管理 HTTPX client。适配器限制整个操作的时限、并发数和请求大小；超时、Provider 不可用、无效分数、 缺少用量回执和模型版本不符均按 RFC 0080 显式返回 inference error。 注入的 reranker 默认也会关闭召回扩展，只有现有 RECALL_GATE_ALLOW_WITH_RERANK 配置显式允许时才扩展。上面的 Server 环境变量开关仍选择现有 LLM reranker。 Jev 配置、三组对照评估与实际验证范围见仓库中的 evaluation/memory/locomo/README.md。

同一个 generation model 也控制显式 Experience generation、managed Skill generation，以及语义化的 Skill fork/evolution。External Skill 精确导入和完整 package 上传不使用模型：PowerContext 会校验并保存 canonical package bytes，再创建 package digest 完全相同的 pending Candidate。未配置模型时，语义生成会在持久化 Candidate 前返回 capability error；Review、package 检查与下载、精确导入、usage recording 和 external Skill scan/list/resolve 仍可使用。

Experience 孵化使用独立的 Supervisor binding 和持久化 Source cursor。每次调用按 SOURCE_WINDOW_LIMIT 检查有限 Source 窗口，只把 metadata 包含 "kind": "task-outcome" 的 Content Source 暴露给模型。该 job 会在 Review Inbox 中创建 pending Experience Candidate；它不会自动批准、进入 PreparedContext、创建 managed Skill、将它导出到 Agent target 或执行任何内容。Memory 与 Experience 保持独立的周期、 Worker 额度和业务 Cursor；关闭某一间隔仅停止该 Family 的新自动准入，保留已接受工作。 设置与验证步骤见创建并审核 Experience。

Agent Skill 目标

零配置流程使用上述 workspace 中的 Codex 和 Claude Code 项目级目录。只有需要自定义路径、用户级 target、环境兼容性 事实或显式关闭本机发现时，才需要通过一个 JSON 值覆盖默认的 host-local target。基础 JSON 结构和验证流程见 配置 Agent Skill target。包含兼容性信息的覆盖示例如下：

export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
  "host_id": "workstation-1",
  "targets": [
    {
      "target_id": "codex-project",
      "agent_kind": "codex",
      "installation_scope": "project",
      "path": "/srv/project/.agents/skills",
      "allow_managed_publish": true,
      "environment": {
        "operating_system": "linux",
        "architecture": "x86_64",
        "commands": {"python": "3.13.2", "bash": "5.2"},
        "network_policy": "restricted",
        "writable_roots": ["workspace"],
        "dependency_install_policy": "denied",
        "environment_names": ["CI"]
      }
    },
    {
      "target_id": "claude-project",
      "agent_kind": "claude_code",
      "installation_scope": "project",
      "path": "/srv/project/.claude/skills",
      "allow_managed_publish": true
    }
  ]
}'

显式设置 POWERCONTEXT_SERVER_EXTERNAL_SKILLS 会完整替换自动生成的两个项目级 target；设置为 {"host_id": null, "targets": []} 可以关闭本机发现和发布。每个 target ID 必须唯一；agent_kind 支持 codex 和 claude_code，installation scope 支持 user、project 和 plugin。PowerContext 只扫描默认或显式 target 的直接 Skill package 子目录，不会推断用户 home 目录、安装 package 或授予执行权限。自定义 target 的 allow_managed_publish 默认是 false；设为 true 后，显式发布操作可以把 approved managed Skill 安全创建或更新到该 target。发布操作不能提交任意路径，也不会覆盖外部或已被修改的 package。发布会物化 Review 通过的完整精确 package （包括 scripts 和 references），不会执行其中内容，也不会向 package 注入 sidecar。只有 binding 与 tree digest 仍匹配 时才能安全取消发布；本地漂移和外部内容会保持不动。host_id、locator 和 registration 都是本地环境状态，不是跨 host contract。已有的 codex_roots 配置继续作为 Codex-only 兼容格式被接受；新配置应使用 targets。

可选的 environment object 只包含已观测且不含密钥的兼容性事实。Command value 是版本标签； environment_names 只记录名称，绝不记录值。PowerContext 不会为了构造该 profile 而探测或执行 package script。 未配置时，包含 script 的 package 会显示未知兼容性；配置后，Skills Library 会把已知 script interpreter 与已观测 command name 对比，并返回带原因的 Assessment。Assessment 不会授予 network、filesystem、dependency install 或 environment 访问权。

Server 始终创建 non-recording OpenTelemetry request context，从 inbound span 派生 X-PowerContext-Request-ID。如需为 CLI 管理的 Server 启用 recording 和 export，请安装 powercontext[cli,server,tracing-otlp]、启用 tracing， 并使用 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS 和 OTEL_SERVICE_NAME 等标准 OpenTelemetry 环境变量进行配置。不使用 powercontext command 的 programmatic Server integration 可以省略 cli extra。

启用 tracing 后，PowerContext 自己构造的 generation 与 embedding 调用也会产生 span，且不记录 prompt、模型响应、 Memory 内容或向量。可运行的配置见 用 Phoenix 查看 trace；需要通过 OTEL_EXPORTER_OTLP_HEADERS 为 exporter 鉴权的后端示例见 用 Langfuse 查看 trace。

使用 OceanBase 时，通过环境或 secret manager 提供 URL：

export POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase
export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL"

URL 必须使用 mysql+aoceanbase 驱动、明确的端口，并设置 charset=utf8mb4。省略库名时使用 powercontext， 显式库名保持有效。租户必须使用 MySQL 兼容模式。

seekDB 启动和 OceanBase Python SDK 初始化会先创建缺失的目标库，再初始化表；已有可用库不会执行建库语句。 完整 OceanBase Server 需要先准备数据库并通过显式维护初始化 Server 表结构，再启动服务；自动建库不替代该准入规则。 建库权限不足时会提供手动准备说明，其他连接错误不会触发回退。seekDB 未显式配置库名时，若在旧 test 中检测到 PowerContext 命名的表，会要求先明确选择数据库。两个后端都会在配置校验阶段拒绝包含反引号的库名， 不会产生数据库写入；请改用 team_context 等不含反引号的名称。自定义名称、权限和旧数据处理见 安装与运行。

Embedding 与 SQLite 向量检索

Vector search 需要全部三个 embedding identity 变量：model、稳定 profile ID 和正数 dimension。normalization 默认 为 unit；timeout 和 batch size 是可选控制项。SQLite vector 和 hybrid search 使用内置 sqlite-vec extension。Server 打开数据库时会探测它，已安装的 library 与 platform 或 SQLite build 不兼容时启动会失败。没有 embedding profile 时， full-text search 仍可用。配置和 capability 验证步骤见配置向量检索。

CLI Server 连接

powercontext 为 Server URL 和 timeout 提供对应的单次命令参数。Token 只能通过环境变量提供，避免出现在 命令行参数中。

Agent 集成

各 Agent 的安装、连接、认证和环境变量见对应的集成文档。