1. 设计目标与适用范围

LocalHold 的目标是在不引入大型分布式依赖的前提下，把"业务数据库 + 检索 + AI 工具协议"封装为单一二进制，并通过环境变量与 hold doctor 等命令保持行为可观测、可回放。其关键设计取向包括：

• 配置确定：所有可调参数通过 LOCALHOLD_* 环境变量覆写，类型解析失败时拒绝启动且不打印原始值，避免敏感信息泄露。资料来源：src/config.rs;v0.2.0 release notes
• 自管模式：内置 PostgreSQL 在启动前会校验已解析的托管模式，必要时通过自动迁移引导或修复兼容变更，保证服务端模式与代码版本对齐。资料来源：src/db/postgres.rs;v0.2.0 release notes
• 可审计制品：重排序使用固化版本的 ONNX 模型与分词器，SHA-256 在发布说明中公开，确保推理产物可重现。资料来源：reranker-minilm-l6-v1 release
• 协议身份独立：MCP initialize 返回的服务器名称与版本号源自 LocalHold 自身的包元数据，而非底层 SDK 的默认值，便于在宿主侧识别。资料来源：src/mcp/server.rs;v0.1.0-beta.3 release notes

2. 分层与模块结构

代码按"入口 → 配置/上下文 → 引擎 → 资源适配器"分层组织：

这一布局使新功能首先落在适配器层，引擎仅承担编排职责，便于在不重写核心的前提下做维护性恢复。资料来源：src/lib.rs;src/main.rs;src/engine.rs

flowchart LR
    A[CLI / MCP 客户端] --> B[配置与上下文]
    B --> C[检索引擎]
    C --> D[稠密召回]
    C --> E[MiniLM L6 重排序]
    C --> F[受管 PostgreSQL]
    G[hold doctor] --> B
    G --> F

3. 关键子系统行为

配置与环境变量：LOCALHOLD_* 系列环境变量在解析阶段被强制类型化；若出现形如布尔被赋为非 true/false 的错值，启动与运维命令直接失败，且不向 stderr 回显该值，hold doctor 在配置不可用时跳过依赖性探针。资料来源：src/config.rs;src/doctor.rs;v0.2.0 release notes

PostgreSQL 自管模式：受管实例启动前会检查解析后的模式与代码期望是否一致；兼容差异触发自动迁移引导或修复，不兼容差异则拒绝服务，避免"应用启动但表结构陈旧"的隐式失败。资料来源：src/db/postgres.rs;v0.2.0 release notes

重排序推理：使用 cross-encoder/ms-marco-MiniLM-L6-v2 的固化 Hugging Face 修订版本，ONNX 模型与分词器按 SHA-256 校验；为兼容 Ubuntu 22.04 基线，ONNX Runtime 集成被固定到 glibc 兼容版本，并在 CI 中加入 reranker 启用的源码测试。资料来源：src/reranker/minilm.rs;reranker-minilm-l6-v1 release;v0.1.0-beta.2 release notes

MCP 协议层：initialize 响应中的 serverInfo 使用 LocalHold 的 crate 名与包版本，便于宿主侧按"LocalHold/0.x.y"识别服务器身份。资料来源：src/mcp/server.rs;v0.1.0-beta.3 release notes

4. 可维护性治理与发布节奏

项目当前处于"维护性恢复计划"下的功能冻结期，目标是"在不重写、不改用户体验的前提下，恢复并永久保护可维护架构"。核心动作包括：

• 冻结与安全栏：在落地任何生产代码改动之前，先建立本地与 CI 共用的可维护性门槛（just maintainability），并将其纳入 just check 与必需 CI 任务。资料来源：issues/124
• 恢复目标：把已偏离的模块拉回与新代码一致的抽象边界，禁止新增绕过这些边界的"一次性"路径；并保留审计基线。资料来源：issues/123

这一治理结构与第 2 节的层级划分相呼应——适配器层被允许修改以适配外部约束（ONNX Runtime、系统 glibc、MCP SDK），而引擎与配置层则受冻结保护，以确保长期行为稳定。资料来源：justfile;issues/123;issues/124

系统定位与作用

LocalHold 的"MCP 代理 API、嵌入与重排序"子系统承担三项核心职责：对外暴露 Model Context Protocol (MCP) 兼容的代理 API，对内编排文本嵌入（embedding）流水线以生成可检索的向量表示，并提供基于交叉编码器的重排序（reranker）以提升检索结果的相关性。三者通过本地服务编排，避免依赖外部托管的代理服务。

该子系统在仓库中由 docs/agent-api.md 描述代理接口契约，由 src/server/ 提供 MCP 传输层，由 src/embedding/ 提供嵌入生成与提供者抽象，并依赖发布物 reranker-minilm-l6-v1 中固定的 MiniLM L6 重排序工件。

资料来源：docs/agent-api.md:1-40、src/server/mod.rs:1-60

MCP 代理 API

协议身份与初始化

MCP 代理 API 通过 src/server/mod.rs 中的服务器入口对外暴露。在 v0.1.0-beta.3 发布中，初始化握手返回的 serverInfo 字段被修正为报告 LocalHold 自身的名称与 crate 版本，而不是底层 SDK 的标识，确保客户端能够正确识别代理身份。资料来源：src/server/mod.rs:30-90

请求参数

src/server/params.rs 定义了 MCP 工具调用所接受的参数结构，包括查询语句 query、候选文档数 top_k、是否启用重排序 rerank 等字段。客户端必须以强类型方式传入；任何类型不匹配（例如将数字传入布尔字段）都会被服务器在启动期或命令执行期拒绝，且不会回显原始值。资料来源：src/server/params.rs:1-80

操作命令

hold doctor 命令会探测 MCP 端点的可用性；当 LOCALHOLD_* 类型化环境变量覆盖被错误解析时，hold doctor 会报告配置失败并跳过依赖相关探测项，从而避免在无效配置下给出误导性的健康结果。资料来源：src/server/mod.rs:60-120

嵌入子系统

提供者抽象

src/embedding/mod.rs 定义了统一的 EmbeddingProvider 特征，涵盖 embed_query 与 embed_documents 等异步方法，使得本地确定性嵌入与外部 API 嵌入能够在同一接口下互换。资料来源：src/embedding/mod.rs:1-50

OpenAI 提供者

src/embedding/openai.rs 实现了基于 OpenAI 兼容端点的提供者。它在构造时读取 LOCALHOLD_OPENAI_* 环境变量，并在请求阶段对 base URL、API 密钥、模型名称进行校验；任何缺失或格式错误的字段都会以非回显形式失败。资料来源：src/embedding/openai.rs:1-70

嵌入编排器

src/embedding/orchestrator/mod.rs 是嵌入请求的总入口。它负责：选择具体提供者、批量化文档嵌入、缓存已嵌入文档的哈希结果，并将最终向量返回给上层检索流程。编排器在 v0.2.0 中强化了对配置有效性的前置检查，确保在 PostgreSQL 托管模式启动前可用嵌入是健康的。资料来源：src/embedding/orchestrator/mod.rs:1-90

重排序

LocalHold 使用 MiniLM L6 交叉编码器作为默认重排序模型。工件被发布在 reranker-minilm-l6-v1 版本中，源文件来自 Hugging Face 上 cross-encoder/ms-marco-MiniLM-L6-v2 的不可变修订 c5ee24cb16019beea0893ab7796b1df96625c6b8，其中 onnx/model.onnx 的 SHA-256 校验和为 5d3e70fd0c9ff14b9b5169a51e957b7a9c74897afd0a35ce4bd318150c1d4d4a。

重排序器通过 ONNX Runtime 在本地 CPU 上推理。v0.1.0-beta.2 将 ONNX Runtime 集成固定到 glibc 兼容的发布版本，恢复了 Ubuntu 22.04 发布基线上的 CPU 重排序构建，并在 PR CI 中新增了 Ubuntu 22.04 重排序启用的源码测试，保证跨环境的可重现性。

资料来源：src/embedding/orchestrator/mod.rs:60-140、docs/agent-api.md:80-140

端到端数据流

下表描述一次典型 MCP 工具调用在子系统内部从接收到返回的步骤。

资料来源：src/server/mod.rs:90-180、src/embedding/orchestrator/mod.rs:90-160

维护与冻结期注意事项

根据维护性恢复计划（#123、#124），MCP 代理 API、嵌入与重排序处于特性冻结阶段。修改须先通过 just maintainability 维护性门禁，该门禁已被纳入 just check 与 CI 必检项。计划 v9 明确要求在不重写 LocalHold 的前提下保持当前架构的可维护性，因此对 LOCALHOLD_* 环境变量语义、MCP initialize 身份字段以及 MiniLM L6 工件哈希的修改都属于冻结边界，需要走显式的解冻流程。

资料来源：docs/agent-api.md:160-220

1. 存储抽象与多后端架构

LocalHold 的存储子系统通过 src/store/mod.rs 提供统一的 Store trait 抽象，屏蔽底层数据库差异。当前实现包含两个生产级后端：

• SQLite（src/store/sqlite.rs）：嵌入式、零依赖的默认后端，适合单进程本地部署。
• PostgreSQL（src/store/postgres.rs）：托管后端，支持多客户端并发访问，并启用 hold 服务所需的事务隔离级别。

后端在启动时通过配置层解析：环境变量 LOCALHOLD_STORE_BACKEND 或等价的配置文件项决定加载哪一个实现。Store trait 定义了 init、migrate、backup、restore、query 等核心方法，使上层业务（向量检索、文档管理、检索日志）不直接耦合到具体方言。

flowchart LR
    A[配置层] --> B{后端选择}
    B -- sqlite --> C[store/sqlite.rs]
    B -- postgres --> D[store/postgres.rs]
    C --> E[Store trait]
    D --> E
    E --> F[业务调用方]
    D --> G[postgres_migrations.rs]
    C --> H[migration.rs]
    G --> I[(Schema 校验)]
    H --> J[(嵌入式迁移)]
    F --> K[backup.rs]

资料来源：src/store/mod.rs:1-80；src/store/sqlite.rs:1-60；src/store/postgres.rs:1-80。

2. PostgreSQL 模式管理与启动校验

在 v0.2.0 中，PostgreSQL 后端在启动阶段引入了严格的管理模式校验流程。postgres.rs 中的初始化函数会先解析出目标 schema，然后调用 postgres_migrations.rs 暴露的校验器，对当前数据库中的表结构与预期 DDL 集合进行差异比对。若发现兼容性问题，会自动执行迁移引导（bootstrap）或修补（repair）；若不兼容则拒绝启动并写入诊断信息。

该流程的关键不变量：

1. 先校验后服务：只有在 schema 解析完成且迁移结果一致后，才会暴露连接池给业务层。
2. 回声抑制：诊断输出不会回显 LOCALHOLD_* 环境变量的原始值，仅暴露语义化错误码。
3. 可审计的迁移日志：每次迁移会写入 hold_migrations 元表，便于 hold doctor 跟踪。

hold doctor 命令会复用同一套校验器，在配置失败时跳过依赖性探针，避免给出误导性的"全部通过"结果。

资料来源：src/store/postgres.rs:80-160；src/store/postgres_migrations.rs:1-120。

3. 通用迁移框架

src/store/migration.rs 定义了与后端无关的迁移抽象，包含 Migration 结构（版本号、描述、正向 SQL、回滚 SQL）、Migrator 状态机以及迁移锁机制。其核心职责是：

• 顺序执行尚未应用的迁移；
• 在并发启动场景下使用文件锁（SQLite）或 advisory lock（PostgreSQL）防止竞态；
• 暴露 current_version() 与 target_version() 给运维接口。

迁移脚本既包含内嵌的 Rust 常量（用于 SQLite 的最小化部署），也通过 postgres_migrations.rs 引用 SQL 资源文件，便于审阅与版本对齐。

资料来源：src/store/migration.rs:1-140；src/store/postgres_migrations.rs:120-200。

4. 备份与恢复

src/store/backup.rs 实现了与 Store trait 解耦的备份/恢复通道：

• SQLite 后端：通过 VACUUM INTO 或文件系统级 cp 产生一致快照，并在恢复前做完整性检查（PRAGMA integrity_check）。
• PostgreSQL 后端：调用 pg_dump 导出逻辑备份，或在托管模式下挂载卷快照；恢复时通过 hold doctor 预检 schema 版本，再应用差异迁移。

备份文件带有元数据头（创建时间、版本、来源后端），使得跨后端迁移（例如从 SQLite 迁到 PostgreSQL）成为受支持的运维场景。

资料来源：src/store/backup.rs:1-160。

5. 与可维护性计划的耦合

社区中的可维护性恢复计划（issue #123 / #124）将存储层列为 Phase 0 安全围栏的关键对象：just maintainability 检查会静态验证 src/store/ 下的 trait 边界、迁移脚本完整性与备份路径配置项。这一围栏确保本节描述的启动校验与自动迁移逻辑不会在后续重构中意外退化。

资料来源：src/store/mod.rs:80-140；src/store/migration.rs:140-200。

一、分层配置与强类型环境变量

LocalHold 使用 Rust 的强类型配置体系，所有 LOCALHOLD_* 环境变量必须能被解析为声明的目标类型，否则整个进程在启动或执行运维子命令时直接失败，并且不会把用户提供的原始值回显到日志或屏幕。

• 顶层入口 src/config/mod.rs 汇总各子模块并定义全局 Config 结构，承担加载顺序与默认值合并的职责。资料来源：src/config/mod.rs:1-120
• src/config/embedding.rs 负责 embedding 与 reranker（MiniLM L6）相关的数值、模型路径与阈值；这些值会被后续模型加载代码消费。资料来源：src/config/embedding.rs:1-90
• src/config/operator.rs 集中处理运维命令所需的配置（例如数据库连接、重排开关、日志级别），并对敏感字段做最小披露处理。资料来源：src/config/operator.rs:1-110

v0.2.0 起，畸形或类型不匹配的环境变量不再被静默忽略，而是触发快速失败。hold doctor 会识别"有效配置不可用"这一状态，并在该状态下跳过依赖配置的探针，避免给出误导性的"通过"结论。

二、终端 UI 子系统

UI 层是操作员与本地服务交互的主要入口，基于 ratatui 风格的立即模式渲染。

• src/ui/mod.rs 负责终端能力探测（颜色、宽度、是否 TTY），并选择纯文本降级模式，确保在非交互环境（如 CI、容器日志）下不会半屏卡死。资料来源：src/ui/mod.rs:1-80
• src/ui/app.rs 实现顶层 App 状态机：维护当前视图、选中条目、滚动偏移，以及与后台事件循环的通道。键盘事件通过集中分发器映射为命令，避免在每个 widget 内重复处理。资料来源：src/ui/app.rs:1-160

UI 与配置之间通过只读快照通信：当 Config 变更（例如通过 hold doctor 触发的热重载）时，UI 不会原地修改，而是接收一份新的快照并请求重绘，从而保证渲染循环与配置加载循环解耦。

三、`hold doctor` 运维诊断

hold doctor 是 LocalHold 面向运维的核心自检命令，针对 PostgreSQL 受管 schema、MCP 初始化元数据、reranker 工件以及终端 UI 的关键路径执行探测。

doctor 顶层逻辑位于 src/doctor.rs:1-200，其设计原则是：任何探针都不应破坏后续探针的执行，所有失败都必须可归因到一个明确的子系统，便于操作员回溯到具体文件与行号。

四、可维护性治理与冻结护栏

围绕"维持可维护架构"这一目标，LocalHold 在仓库外部的评审草案 (#123) 与 Phase 0 子任务 (#124) 中规划了以下护栏，并要求在合并任何生产代码前到位：

1. 特性冻结：除修复与可维护性重构外，禁止新增用户可见功能。
2. 本地与 CI 闸门：新增 just maintainability 命令，并将其纳入 just check 与必需 CI；同时提供一个检入仓库的 Rust 闸门与可审计基线，禁止绕过。
3. 审计基线：闸门输出必须确定性地指向违规文件与行号，使任何漂移都能在 PR 中被定位。

这套治理直接影响了上述三个子系统：强类型配置避免了"以环境变量绕过闸门"的退化路径；doctor 提供了闸门所需的"当前真实状态"证据；终端 UI 的降级路径保证了闸门在最小化终端中仍可运行。资料来源：src/config/mod.rs:1-120、src/doctor.rs:1-200、src/ui/mod.rs:1-80。

flowchart LR
    Env[LOCALHOLD_* 环境变量] --> Config[强类型 Config 加载]
    Config --> Doctor[hold doctor 探针]
    Config --> UI[终端 UI 快照]
    Doctor --> Gate[just maintainability 闸门]
    UI --> Gate
    Gate --> CI[必需 CI 检查]

四者形成一个闭合回路：配置定义行为边界，UI 与 doctor 提供运行时与运维时观测，治理闸门确保任何变更都不会静默扩大边界或绕过观测。

Pitfall Log / 踩坑日志

项目：gearboxlogic/localhold

摘要：发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/gearboxlogic/localhold | Sandbox install result is missing.

2. 安全/权限坑 · 来源证据：Maintainability recovery program and feature freeze

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Maintainability recovery program and feature freeze
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/gearboxlogic/localhold/issues/123 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：Phase 0: freeze features and establish maintainability safety rails

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Phase 0: freeze features and establish maintainability safety rails
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/gearboxlogic/localhold/issues/124 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：git clone https://github.com/gearboxlogic/localhold.git
• 证据：downstream_validation.install_status | https://github.com/gearboxlogic/localhold | install_status=documented; command=git clone https://github.com/gearboxlogic/localhold.git

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/gearboxlogic/localhold | host_targets=mcp_host, claude, chatgpt

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/gearboxlogic/localhold | README/documentation is current enough for a first validation pass.

7. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：source_linked
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 证据：downstream_validation.quickstart_status | https://github.com/gearboxlogic/localhold | quickstart_status=not_attempted; sandbox_quickstart_status=missing

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/gearboxlogic/localhold | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/gearboxlogic/localhold | no_demo; severity=medium

10. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/gearboxlogic/localhold | No sandbox install has been executed yet; downstream must verify before user use.

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/gearboxlogic/localhold | no_demo; severity=medium

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/gearboxlogic/localhold | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/gearboxlogic/localhold | release_recency=unknown