Hatchdoor 是一个自托管、以 Web 为先的 Obsidian Vault 阅读与编辑平台。它将一个 Markdown 知识库（Vault）以响应式 PWA 前端的方式呈现在浏览器中，同时通过 Rust 后端提供本地 API、缓存、嵌入（embedding）以及 MCP（Model Context Protocol）集成，使外部 LLM 代理能够以语义检索与结构化读写的方式访问 Vault。

1. 项目定位与核心能力

Hatchdoor 在 v1.0.0 首次发布时被定位为「Rust 后端 + PWA 前端的自托管 Obsidian Vault 阅读器」，随后逐步演进为兼具阅读、写入、搜索与代理接口的完整知识库网关。其核心项目括：

资料来源：README.md:1-60

资料来源：CHANGELOG.md:1-40

资料来源：CHANGELOG.md:40-80

资料来源：CHANGELOG.md:80-120

• Vault 浏览与渲染：支持 Obsidian 风格的 Wikilink、双链解析以及 Markdown 笔记的浏览器内渲染。
• 写入模式（Write Mode，自 v2.2.0 起）：通过 Web UI 与 MCP 工具完成笔记的创建、更新、追加、移动、重命名与删除；同时提供附件的导入、移动、重命名与删除。
• 混合检索：结合关键词与基于 Nomic Embed Text v1.5 的语义分块检索，向 MCP 客户端暴露结构化搜索结果。
• 附件支持：通过 import_attachment 等 MCP 工具支持图片与文档类附件的入库（v2.4.0 已移除旧的 inbox 暂存路径机制）。

2. 技术架构

Hatchdoor 的运行时由单一 Rust 可执行进程承担 HTTP 服务、静态前端分发与本地数据管道；前端作为 PWA 由构建产物直接托管在同一进程中。下表概括了主要组件及其职责：

资料来源：Dockerfile:1-40 · Cargo.toml:1-30 · frontend/package.json:1-40 · CHANGELOG.md:20-100

3. 版本演进里程碑

Hatchdoor 遵循语义化版本，当前主线已发布至 v2.4.0。关键里程碑如下：

资料来源：CHANGELOG.md:1-20

资料来源：CHANGELOG.md:20-60

资料来源：CHANGELOG.md:60-80

资料来源：CHANGELOG.md:80-100

资料来源：CHANGELOG.md:100-120

资料来源：CHANGELOG.md:120-140

资料来源：CHANGELOG.md:140-170 · docker-compose.yml:1-40

• v1.0.0：首个稳定版本，Rust + PWA 阅读器，支持 Wikilink 与桌面/移动端浏览。
• v1.1.0 / v1.1.1：新增 Download .md 操作与服务端下载端点 GET /api/note/{slug}/download，改善 iOS/PWA 文件落地体验。
• v2.0.0：引入 MCP 写入工具集（笔记与附件的完整 CRUD）与持久化 SQLite 缓存层。
• v2.1.0 / v2.1.1：MCP Git 同步、安全审计硬化与 iOS PWA 下载修复。
• v2.2.0：发布 写入模式，将 Web UI 与 MCP 工具升级为可创建/编辑笔记；同时加入只读演示模式。
• v2.3.0：切换至 Nomic Embed Text v1.5（1,024-token 输入窗口），首次启动触发完整缓存重建。
• v2.4.0：移除旧的 MCP 附件收件箱暂存系统，引入持久化的 models 挂载；要求容器部署同步更新环境变量与绑定卷。

4. 部署与运行形态

Hatchdoor 支持两种典型运行方式：

资料来源：Dockerfile:1-60 · docker-compose.yml:1-40

资料来源：frontend/README.md:1-30 · eval/README.md:1-30 · Cargo.toml:1-30

• 容器化部署（推荐）：通过 Dockerfile 构建单一镜像，在 docker-compose.yml 中将 Vault 目录、模型目录与缓存目录作为持久化卷挂载。v2.4.0 起，models 挂载成为必需项，旧的 HATCHDOOR_MCP_ATTACHMENT_STAGING_PATH 环境变量相关机制已被移除。
• 本地开发：Rust 工作区在仓库根目录提供后端源码；frontend/README.md 中给出前端开发服务器与构建指令，eval/README.md 提供评估脚本与基准说明。

社区中仍有若干公开讨论与改进提案值得关注，包括Vault 文件/目录排除规则（#22）、事件钩子系统（#23）、Open Knowledge Format (OKF) v0.1 校验（#26）、MCP 搜索暴露 frontmatter/标签元数据（#19）以及附件内联导入而非仅暂存文件名（#32）。这些提案勾勒了 Hatchdoor 在 Vault 治理、代理可观测性与生态互操作方向的下一步演进空间。 资料来源：README.md:1-60 · CHANGELOG.md:1-170

模块定位与作用

frontend/src/lib/ 是 Hatchdoor 前端工程中存放与 UI 框架无关的纯工具函数（utility helpers）的目录。该目录下的代码被设计为可独立测试、可在多个组件/页面中复用的最小功能单元，向上服务于组件层（components/）和页面层（pages/），向下不依赖任何特定的 React/Vue 等视图库，便于在不同视图层之间迁移或单独在 Node 环境中运行测试。

该目录遵循"单一职责 + 配对测试"的组织约定：每个工具模块都有一个同名 .test.ts 文件用于 Vitest/Jest 等单元测试，确保核心逻辑（路径处理、剪贴板读写、上传参数构造等）在重构时仍保持行为一致。v1.1.1 发布说明中提到的"将仓库路径辅助函数的再导出门控到测试中，以消除运行时警告"也表明 lib/ 中的纯函数被刻意限制为只在测试或受控上下文中暴露，避免污染生产 bundle。

资料来源：frontend/src/lib/clipboard.ts、frontend/src/lib/folderPaths.ts

核心工具模块

剪贴板工具（clipboard）

clipboard.ts 封装了浏览器剪贴板 API 的异步读写操作，对外暴露简化的 copy/paste 风格的函数。该模块主要解决两个常见前端痛点：

• 在不同浏览器对 navigator.clipboard.writeText/readText 的支持差异下提供降级路径；
• 把"复制成功/失败"事件从组件中抽离，便于在通知系统、动作菜单等场景统一处理。

其配对测试文件 clipboard.test.ts 通过对 happy path 与异常分支（如权限被拒绝、空字符串、非文本 MIME）进行覆盖，确保上层 UI 不会因剪贴板 API 的细微差异出现闪烁或未捕获异常。资料来源：frontend/src/lib/clipboard.test.ts、frontend/src/lib/clipboard.ts

文件夹路径工具（folderPaths）

folderPaths.ts 提供与 Obsidian vault 目录结构相关的纯函数，典型职责包括：

• 在"以 / 分隔的 vault 相对路径"与"前端展示用的层级数组"之间相互转换；
• 处理 slug、目录前缀规范化，以及空段、相对段（./..）等边界情况；
• 为浏览视图、面包屑、搜索过滤等场景提供统一的路径表示。

由于该模块只处理字符串而不接触文件系统，可以被安全地用于 SSR、客户端路由以及单元测试中。folderPaths.test.ts 用大量路径样本锁定其行为，避免在 v2.0.0 引入的"SQLite 持久化缓存"或后续写模式中对路径规则做隐式修改时引入回归。资料来源：frontend/src/lib/folderPaths.test.ts、frontend/src/lib/folderPaths.ts

图片上传工具（imageUpload）

imageUpload.ts 是与社区讨论高度相关的模块：Issue #7「Improve attachment UX」要求支持拖拽与 + 按钮上传附件（PDF/图片），而该 issue 在最新进展中已明确"后端就绪、前端成为主要工作"。imageUpload.ts 因此承担了把 File/Blob 转换为可上传载荷的工作，包括：

• 校验 MIME 类型是否落在后端允许列表（png/jpg/jpeg/gif/webp/avif 等）中；
• 生成客户端可读的预览对象 URL；
• 构造与 Hatchdoor 后端写入 API 对齐的 multipart/form-data 请求体。

配对的 imageUpload.test.ts 在浏览器 API 不可用的 Node 测试环境下，使用注入的 fake File 工厂来验证参数构造逻辑，使前端上传策略可以独立于 UI 迭代。资料来源：frontend/src/lib/imageUpload.test.ts、frontend/src/lib/imageUpload.ts

模块协作关系

资料来源：frontend/src/lib/clipboard.ts、frontend/src/lib/folderPaths.ts、frontend/src/lib/imageUpload.ts

设计原则与演进

lib/ 模块整体遵循三项原则：

1. 纯函数优先：避免在工具层持有可变全局状态，使缓存（v2.0.0 引入的 SQLite 层）成为唯一的"可变真相源"，前端只做派生计算。
2. 测试与实现一一对应：每个 .ts 都伴随同名 .test.ts，覆盖率达到行为锁定的程度，符合 v1.1.1 强调的"测试覆盖、构建可靠性"目标。
3. 紧贴社区需求：随着 v2.2.0 的写模式、v2.4.0 的附件摄取重构等演进，imageUpload.ts 等模块会被持续调整以匹配新的后端契约，而纯函数边界让这类调整局部化、可回滚。

资料来源：frontend/src/lib/clipboard.test.ts、frontend/src/lib/folderPaths.test.ts、frontend/src/lib/imageUpload.test.ts

模块概览

frontend/src/api/ 目录是 Hatchdoor 前端与 Rust 后端之间的 HTTP 通信层。该模块封装了全部面向 Web UI 的 REST 调用，提供强类型的请求/响应模型，并在统一的错误处理模式下进行异常传播，使上层 React 组件可以以同步函数的方式使用异步 API。

模块由三个核心文件组成，按职责拆分如下：

配套的 *.test.ts 文件提供针对每个接口的单元测试覆盖。

资料来源：frontend/src/api/api.ts:1-40 frontend/src/api/writeApi.ts:1-40 frontend/src/api/apiError.ts:1-30

读取接口（api.ts）

api.ts 暴露了 Hatchdoor 全部只读浏览能力，是最早随 v1.0.0 上线的接口集合。其行为与官方发布说明中的功能一致：

• Vault 浏览：返回目录树、标签列表与笔记元数据，用于侧边栏与索引视图。
• Note 详情：按 slug 拉取单条 Markdown 笔记，包括正文字符串、frontmatter 与 wikilink 解析结果。
• 搜索：基于关键词 / 语义向量的 chunk 检索；社区中 issue #19 提出希望在搜索响应里暴露结构化 frontmatter 与标签元数据，相关讨论涉及该接口的扩展。
• 附件下载：从 v1.1.0 起，新增 GET /api/note/{slug}/download，把 Markdown 直接通过服务端响应交付，便于移动端原生下载。

api.ts 内部使用 fetch 并通过 apiError.fromFetch 把任何非 2xx 响应转化为抛出异常的错误对象，确保调用方无需自行处理 Response.ok。

资料来源：frontend/src/api/api.ts:40-120 frontend/src/api/apiError.ts:30-90

写入接口（writeApi.ts）

writeApi.ts 自 v2.0.0 起加入，对应发布说明中描述的“Write Mode”。它集中提供全部会修改 vault 文件系统的接口：

• 笔记维度：createNote、updateNote、appendNote、moveNote、renameNote、deleteNote。
• 附件维度：importAttachment、moveAttachment、renameAttachment、deleteAttachment。
• 提交选项：可选的 Git 同步字段，由 v2.1.0 引入的 MCP git sync 链路使用。

每个写入函数都包含服务端已实现的硬约束镜像：拒绝空内容、空路径、以及越界目录。客户端在拼装请求体时也会预先校验，避免产生注定失败的请求。

针对 issue #32 中讨论的“远端 MCP 客户端无法访问 Hatchdoor 本地 staging 目录”这一痛点，writeApi.ts 与 importAttachment 配套的请求模型定义了 staged_filename 字段；任何仅可在 Hatchdoor 文件系统上取得的附件都需要先落入 HATCHDOOR_MCP_ATTACHMENT_STAGING_PATH 后再被导入。

资料来源：frontend/src/api/writeApi.ts:1-180 frontend/src/api/writeApi.test.ts:1-60

错误模型（apiError.ts）

apiError.ts 抽象出统一的错误类型，便于在 React 组件、React Query 与全局 toast 通知之间复用同一种错误传播路径：

• ApiError：承载 HTTP 状态码、后端错误码与可读消息。
• fromFetch(response)：把 fetch 返回的 Response 解析为 ApiError 或返回原 Response；被 api.ts 与 writeApi.ts 共用。
• isApiError(value)：类型守卫，供 instanceof 替代方案使用。

错误模型与后端的错误响应结构对齐（JSON 体里通常包含 code 与 message），因此前端可以针对不同错误码显示不同提示，例如“vault 路径非法”或“附件类型不允许”。

资料来源：frontend/src/api/apiError.ts:30-110 frontend/src/api/apiError.test.ts:1-50

测试与维护

每个核心文件都配对了一份 *.test.ts：

• api.test.ts 覆盖读取类接口的请求拼装、URL 编码与响应解析；
• writeApi.test.ts 覆盖写入路径上的边界条件（空内容、路径合法性、附件元数据）；
• apiError.test.ts 覆盖错误对象在非 2xx 响应、JSON 解析失败等场景下的行为。

测试文件与运行时实现使用相同的请求工厂函数，保证契约在两端一致；当后端调整错误结构时，仅需修改 apiError.fromFetch 与对应测试即可全链路生效。

资料来源：frontend/src/api/api.test.ts:1-40 frontend/src/api/writeApi.test.ts:1-60 frontend/src/api/apiError.test.ts:1-50

社区关注点

• Issue #19：希望在搜索响应中暴露 frontmatter / 标签结构化元数据，会影响 api.ts 中搜索接口的返回类型。
• Issue #32：importAttachment 目前仅支持文件系统 staging，社区希望支持内联内容（base64 或 URL）以便跨主机场景使用。
• Issue #26：OKF v0.1 校验与现有 api.ts 的 vault 列举接口相邻，是潜在的扩展点。

这些讨论表明 Api 模块 的稳定性是社区采纳的关键：读取与写入 API 的契约变更都需要在三个实现文件与三份测试中同步更新。

模块定位与职责

App 模块是 Hatchdoor 前端单页应用的根级 UI 容器，位于 frontend/src/app/ 目录下，承载了从仓库加载、目录浏览、笔记查看、搜索到写模式操作的整条交互链路。该模块采用 React 函数组件 + 局部状态存储（Zustand）的结构，对外通过 REST/MCP 接口与 Rust 后端通信，对内组织 Topbar、ExplorerPane、NoteView 等子组件形成桌面与 PWA 共用的主视图壳。资料来源：frontend/src/app/AppMainShell.tsx:1-80

模块的设计目标是：

• 以一个常驻壳层包裹所有路由级别视图，避免每次切换都重新初始化全局监听器（事件、快捷键、缓存）。资料来源：frontend/src/app/AppMainShell.tsx:42-78
• 将仓库（vault）的导航状态集中到 vaultSelectionStore，使侧边栏、面包屑、笔记视图能够共享同一份"当前选中笔记 / 路径"快照。资料来源：frontend/src/app/state/vaultSelectionStore.ts:1-60
• 通过 useVaultNavigation 钩子封装键盘导航与历史记录回退，使顶层组件不必关心 DOM 焦点细节。资料来源：frontend/src/app/hooks/useVaultNavigation.ts:12-58

主要组件层级

App 模块的视图树可以抽象为三栏壳层加顶部条形区域，常量定义集中于 constants.ts，包含布局尺寸、断点与存储键名等。资料来源：frontend/src/app/constants.ts:1-45

AppTopbar 通过读取 vaultSelectionStore 中的 currentSlug 渲染上下文相关动作，并暴露搜索输入；它同时负责触发 useVaultNavigation 提供的快捷键（j/k/Enter/Esc）绑定。资料来源：frontend/src/app/AppTopbar.tsx:30-120

ExplorerPane 接收来自 Rust 后端的目录快照，使用 types.ts 中定义的 VaultNode/VaultLeaf 类型渲染可折叠树，并通过 store 的 selectPath 方法与中央视图同步。资料来源：frontend/src/app/ExplorerPane.tsx:18-96 ExplorerPane 还承担附件与图像缩略区的入口占位，对应社区中关于"改进附件 UX"的诉求（Issue #7）。资料来源：frontend/src/app/ExplorerPane.tsx:100-145

状态流与数据流

模块内部以 Zustand store 作为单一可信来源，组件通过订阅对应切片避免整树重渲染。下列时序图展示了从用户点击树节点到 Markdown 渲染完成的关键路径：

sequenceDiagram
    participant U as 用户
    participant EP as ExplorerPane
    participant ST as vaultSelectionStore
    participant NV as NoteView
    participant API as 后端 API
    U->>EP: 点击文件节点
    EP->>ST: selectPath(slug)
    ST-->>NV: 触发 currentSlug 变化
    NV->>API: GET /api/note/{slug}
    API-->>NV: 返回 markdown + 元数据
    NV-->>U: 渲染并高亮命中

useVaultNavigation 在挂载时订阅 keydown 事件，识别方向键后调用 selectPath 的相邻条目，保持与点击行为一致的状态写入。资料来源：frontend/src/app/hooks/useVaultNavigation.ts:30-72 类型契约由 types.ts 中的 VaultSelection、NavDirection 等统一约束，避免散落的字符串字面量。资料来源：frontend/src/app/types.ts:1-50

与写模式及 MCP 的衔接

自 v2.2.0 引入写模式后，App 模块成为写操作的视觉中枢：保存、删除、重命名等动作在 AppTopbar 中以受控按钮呈现，按钮的可用性由 vaultSelectionStore 派生。资料来源：frontend/src/app/AppTopbar.tsx:122-180 写操作最终通过 MCP 工具（create_note、update_note、delete_note 等）落库，对应后端的 /api/mcp 端点；前端并不直接耦合 MCP 协议，而是经由统一的请求封装调用。资料来源：frontend/src/app/constants.ts:46-90

针对社区提出的"在 MCP 搜索中暴露结构化 frontmatter/标签元数据"（Issue #19），App 模块在 ExplorerPane 与搜索结果面板共用同一份 VaultNode 派生类型，便于未来在不改壳层的前提下透出元数据字段。资料来源：frontend/src/app/ExplorerPane.tsx:147-180 此外，constants.ts 中定义的存储键（如最近访问草稿、上次选中目录）会被写模式下的冲突检测复用，从而在并发编辑场景给出提示。资料来源：frontend/src/app/constants.ts:20-44

Pitfall Log / 踩坑日志

项目：BatterWorks/Hatchdoor

摘要：发现 16 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Improvement: configurable event hooks for vault changes。

1. 安装坑 · 来源证据：Improvement: configurable event hooks for vault changes

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Improvement: configurable event hooks for vault changes
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/BatterWorks/Hatchdoor/issues/23 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 来源证据：Add Open Knowledge Format (OKF) v0.1 validation for Markdown vaults

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Open Knowledge Format (OKF) v0.1 validation for Markdown vaults
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/BatterWorks/Hatchdoor/issues/26 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

4. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker compose up -d
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker compose up -d
• 证据：identity.distribution | https://github.com/BatterWorks/Hatchdoor | docker compose up -d

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

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

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

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

7. 配置坑 · 来源证据：[Feature Request] Expose structured frontmatter/tag metadata in MCP search

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature Request] Expose structured frontmatter/tag metadata in MCP search
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/BatterWorks/Hatchdoor/issues/19 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

10. 运行坑 · 来源证据：MCP: support attachment import via inline content, not just filesystem staging

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：MCP: support attachment import via inline content, not just filesystem staging
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/BatterWorks/Hatchdoor/issues/32 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

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

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

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

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

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

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

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