受管本地 Server 安装

独立 Ops 工具负责准备固定的 Server 运行环境，并管理当前用户的服务。Ops 使用自己的解释器和依赖，因此修复缺失的 Server 解释器不需要先启动损坏的环境。Desktop 集成通过这一入口完成安装和修复，不要求已有 HTTP 连接。

安装与修复计划

安装与修复使用本地 Server 运维工具中的 preflight、apply、operation_status、cancel 和 resume 协议。调用方先展示完整计划，再取得确认并执行。发起请求时保留 operation ID；中断后先查询已保存的尝试和当前事实，再确认恢复计划。

如果后续停止操作替代了中断的修复，应确认新的修复计划，不再恢复已被替代的旧操作。新计划只有在核验原操作记录、安装与资源身份、精确服务定义以及原生命令已结束后，才能接续原修复保护。它不会重启服务，也不会恢复随后已移除的注册。

随包 Ops 解释器每个进程接收一条 JSON 请求。可信宿主提供受保护的资源目录文件，以及分发包固定的 SHA-256 摘要：

<ops-python> -I -S -B <ops-entry.py> --catalog-file <protected-catalog.json> --catalog-sha256 <trusted-sha256>

例如，将下面这一行写入标准输入，预检首次安装：

{"protocol_version":1,"request_id":"inspect-install","action":"preflight","operation":"install","options":{}}

响应包含固定资源、程序和配置及数据位置、端点、数据库分类、所需空间与启动影响。按共享 Ops 协议，将完整计划原样交给 apply，提供唯一 operation ID，并明确授权该 plan_id。预检同版本修复时使用 "operation":"repair"。受管目录由宿主选择；--state-dir 属于独立的 --target-file 操作者绑定模式，不能覆盖受管安装位置。这些命令要求已有合格生产者目录，不会自行发现或生成公共发布资源。

只有可信资源生产者能够指定下载 URL、可执行文件布局、平台、架构、包版本和文件摘要。渲染层不能提供命令、下载 URL 或任意安装路径。资源先下载到暂存目录，按固定目录校验后才能发布；与不可信下载一起提供的摘要不能建立信任。缓存命中同样需要通过完整性检查。

修复保持同一固定资源身份和版本，保留安装身份、已有配置和用户数据。它不升级到 latest，不重置认证或模型，也不删除已有数据库。替换资源前先停止自有服务，修复完成后不重启；已停止的服务继续停止。对已核验的当前安装重复执行 install，只返回当前事实，不重启服务、不打开数据库。

受管服务定义明确启用隔离运行模式（isolated_runtime=true），目标 Python 使用 -I -B 启动，排除 PYTHONPATH 和用户 site 的导入，并避免生成字节码改变已校验的资源目录。请使用随包 Ops 或匹配版本的服务工具管理这些定义。无法识别该字段的旧版 CLI 会拒绝该定义，不支持用它管理新注册；未包含该字段的已有定义保持原启动行为。

独立安装不会被自动接管。归属未知、控制记录损坏、原生服务定义不一致或原生命令尚未确认结束时，需要先检查再修改。移除服务注册会保留运行环境、配置和数据库，并不删除数据。

新建个人配置

新配置明确设置以下选项：

这是本地免 Token 访问模式，不是一套额外的匿名凭据。监听地址保持 loopback。该策略不改变已有连接或远程连接的认证要求，修复也不会覆盖用户已有选择。选择已有认证安装时，继续引用其受保护配置。

默认数据目录按平台的 powercontext_data_dir() 规则解析，但忽略继承的 POWERCONTEXT_HOME。新配置解析也不继承 POWERCONTEXT_SERVER_*、PYTHONPATH 和 PYTHONHOME，并明确保存选定的数据根和 SQLite 路径。已有安装保留已核验的登记数据目录，程序目录与数据目录分开。

预检通过受保护文件接口读取配置，只返回文件身份及必要的本地摘要。配置正文、Token 和模型凭据不进入计划或操作记录。预检不创建配置文件、数据目录或数据库。

数据库兼容边界

普通检查只观察选定的 SQLite 文件及恢复侧文件，不打开 SQLite，也不启动目标进程；状态中的已有文件仍标记为 existing_unknown。只修复程序时，计划绑定数据库文件身份和目标版本，允许准备资源期间正常写入及 WAL checkpoint，修复完成后保持服务停止。替换数据库会使修复计划过期。

可能启动受管服务的操作会另外执行准入检查，包括 start、restart、服务注册，以及会实际重启运行中服务的配置修改。Ops 先按照固定清单核验自有目标资源，再使用该包中的隔离 Python（-I -B）调用 Server 准入入口。Windows 使用同一资源清单中的控制台 Python。子进程核对已安装包版本是否与选定的 Server 版本完全一致。缺少该入口的旧目标仍不受支持；Ops 自身版本和历史启动成功都不能替代目标准入。

目标检查完整 Server schema 与索引、受支持的版本历史、配置对应的领域和 Embedding profile、SQLite 完整性、原数据库身份对应的维护证据，以及未完成的归档恢复。检查读取主库和 WAL 的私有副本，包含尚未 checkpoint 到主库的已提交数据。准入期间 SQLite 不打开原库；不复制或改动原 SHM，也不创建或删除原侧文件。复制和检查期间，源文件身份和修改证据必须保持稳定。准入不初始化、迁移或恢复数据，不调用模型，也不启动 HTTP 或 worker。

版本标记或局部领域检查不能证明整库可用。所需迁移和恢复仍须按照数据库迁移显式执行。database_migration_required、database_recovery_required 和 database_configuration_mismatch 分别提示这些边界；database_compatibility_unknown 表示精确目标未能证明兼容性。程序修复不会取消这些要求。

准入复制并计算完整主库与 WAL 的摘要，再由 Server 验证器扫描副本。每次预检和 apply 重新核验都会重复这些工作，不是增量检查，也不复用缓存。主库与 WAL 合计上限为 8 GiB；临时文件系统需要其合计大小加 32 MiB 的可用空间；复制和目标验证共用 120 秒时限。超出大小、空间不足或超时分别返回 database_snapshot_too_large、database_snapshot_space_insufficient、database_admission_timeout。每个恢复日志上限为 4 MiB。大型或持续写入的数据库需要由操作者安排维护流程，单纯提高限制不能证明兼容。检查结束后删除临时副本。

正常业务写入也会使已批准的数据库证据过期。如果运行中的 Server 持续写入，或预检与 apply 之间数据发生变化，应先通过 Ops 停止服务，待写入停止后重新获取并批准 start 计划。被拒绝的重启不会改变正在运行的服务。准入不会自动停止写入方或放宽已批准的数据库身份；其他进程对同一数据库的写入也必须暂停。

一次本地 macOS arm64 / CPython 3.12.15 测量使用公开 Memory 接口创建 2,000 条记录、4,000 个修订版本，SQLite 主库为 168.4 MiB。三次准入各耗时 3.78–3.86 秒，其中复制及计算摘要耗时 0.074–0.075 秒；源文件摘要保持不变。该测量不包含资源清单核验和原生服务命令，不能证明其他机器、WAL 大小或接近上限的数据库具有同样性能。

Apply 会重新执行准入，并比较获批计划中的数据库、配置、目标资源及恢复证据；证据变化会在派发服务命令前拒绝旧计划。实际 Server 启动仍执行自己的启动检查。即使目标解释器损坏或缺失，检查、停止、移除注册和保持停止的程序修复仍可使用。原本停止的服务在配置修改后仍保持停止，即使传入 restart=true 也不会启动。独立的已备妥 runtime 操作者绑定保留既有契约。

启动与连接交接

资源完整性、配置有效性、服务注册、进程存活和 readiness 是不同事实。获得首次启动授权后，共享服务控制器执行有界 readiness 验证；本次新启动的自有目标失败时，会恢复保护并确认停止。已完成安装的结果是历史事实，普通状态查询不重新执行 readiness。取消只在支持的安全边界生效，并不承诺回滚。

如果首次注册在创建服务前失败，释放冲突端口或解决报告的问题后，确认新的 install 计划并恢复原操作，安装身份和自有配置会保留。派发检查点本身不能证明注册已经存在。匹配版本的 CLI 和 Ops 在修改原生注册前保存受保护的移除身份，旧安装操作不能撤销之后的明确移除，即使当时尚未创建注册。不含该身份的旧记录仍可读取，但缺少注册证据的旧派发检查点需要先检查，不会自动重放。

取消后的安装可复用已核验暂存资源。如果普通暂存文件损坏，resume 或新批准的 install 操作会核对已记录的目录归属，只清理对应暂存树，再次准备同一固定资源。目录被替换、包含链接或归属不安全时，拒绝操作并保留现场。

安装器返回实际端点和安装、资源身份，这些信息不是 Server 部署或 Principal 身份。连接负责方仍需根据公开身份和兼容契约核验真实端点，才能激活连接并取得默认 Scope。安装不会自造 Scope ID、任意选择一个 Scope，也不证明 Memory 操作已成功。

发布与平台验收

实现要求生产者提供固定资源。候选生产器为 Windows x86_64 和 macOS arm64/x86_64 原生构建固定的 Server/Ops 资源，并通过真实消费者回读；其 catalog 仍未资格验收。正式平台资源目录及合格产物归 #2112 负责；实现不提供公共生产下载 URL，也不会根据版本号猜测地址。 开发 fixture 和本地构建包验证的是实现行为，不能证明生产分发可信。

Windows 预检会根据实际最终目录和固定暂存路径预算检查资源布局，获取资源时还会在下载前核对本次暂存目录。普通路径必须满足 Windows 文件和目录长度限制，不支持的布局返回 resource_path_unsupported。Ops 不修改系统长路径设置，也不假定 Task Scheduler 支持扩展路径形式的可执行文件名。生产者需提供适合目标用户目录的合格布局；完整开发包在较短测试目录中启动成功，不能证明默认安装布局可用。

发布验收需使用实际下载产物，在未预装 Python、uv、Git 或编译工具的干净普通用户 Windows 11 x64、macOS arm64 和 macOS x86_64 环境执行。分别验证签名与 macOS notarization、独立 Ops 启动、真实 Task Scheduler 或 LaunchAgent 行为、登录与重启，以及修复和移除后的配置与数据保留。Fake 服务适配器和仓库 runtime 的 SQLite 测试不能替代这些平台证据。