antoinevalentinHA/ha-archive-search

# ha-archive-search 搜索 [](https://github.com/antoinevalentinHA/ha-archive-search/pkgs/container/ha-archive-search) [](https://github.com/antoinevalentinHA/ha-archive-search/actions/workflows/tests.yml) [](https://github.com/antoinevalentinHA/ha-archive-search/actions/workflows/publish-ghcr.yml) 用于 Home Assistant 配置快照的基础设施侧搜索、导出和审计工具。 `ha-archive-search` 是一个搜索、检查和导出工具包，操作对象是提取后存储在 Home Assistant 本身之外的 Home Assistant 配置语料库。 该项目提供： - 一个语料库搜索引擎； - 一个 CLI 搜索界面； - 一个轻量级 Web 应用程序； - Markdown 导出功能（紧凑模式和上下文模式）； - Docker 部署支持。 该系统操作的是在外部基础设施（如 NAS 系统）上生成并保留的、不可变的提取快照。它不直接访问 Home Assistant 运行时。 ## 快速入门 从 GitHub Container Registry 拉取官方容器镜像： ``` docker pull ghcr.io/antoinevalentinha/ha-archive-search:latest ``` 使用 Docker 运行： ``` docker run -p 8099:8099 \ ghcr.io/antoinevalentinha/ha-archive-search:latest ``` Docker Compose 示例： ``` services: ha-archive-search: image: ghcr.io/antoinevalentinha/ha-archive-search:latest ports: - "8099:8099" ``` ## 截图 ### 结构化搜索 UI 按版本、文件和匹配项进行分组渲染。  ### 紧凑型 Markdown 导出 确定性 Markdown 导出，适用于审计、共享和 AI 辅助审查。  ### 上下文 Markdown 导出 扩展导出，包含匹配项周围的配置上下文，针对 AI 辅助工作流和深度检查进行了优化。  ### JSONL 导出示例 ``` {"type":"header","format":"ha-archive-search-machine","version":"v1","emitted_at":"2026-05-20T14:45:40Z","query":{"text":"ha_shutdown_ups","text_raw":"ha_shutdown_ups","mode":"compact","grammar_version":null,"filters":{"version_range":null,"last_n":null,"date_prefix":null}}} {"type":"match","version":"2026-05-20_12-12_Arsenal_v15.5_7ea5ab74","version_index":0,"file":"00_documentation_arsenal/changelog/changelogs/v12/v12_3.md","line_number":50,"content":"Le nouvel automatisme `ha_shutdown_ups` ferme la boucle qui manquait : quand","match_span":null} {"type":"footer","match_count":1,"version_count":1,"file_count":1,"truncated":false,"elapsed_ms":1270} ``` ## 理念 Home Assistant 擅长实时自动化和运营仪表板。 `ha-archive-search` 解决的是不同的问题领域： - 基础设施侧检查； - 离线配置分析； - 跨提取快照的大规模文本搜索； - 以审计为导向的工作流； - AI 辅助的配置审查； - 便携式 Markdown 导出。 该搜索系统有意设计在 Home Assistant 基础设施之外运行。历史探索仍然可行，但不再是主要定位。 ## 操作模型 `ha-archive-search` 位于从 Home Assistant 内部开始的流水线末端： ``` Home Assistant ↓ encrypted backups ha-state-archive ↓ immutable extracted snapshots ha-archive-search ``` `ha-archive-search` 不直接访问 Home Assistant 运行时。它仅操作提取的快照语料库。这个边界是有意且不可协商的。 ## 典型用例 - 在快照版本间定位实体引用； - 检查仪表板和自动化使用模式； - 为审计或事件审查导出配置上下文； - 对照先前快照调查升级后的回归问题； - 为 AI 辅助的配置审查工作流提供输入； - 离线分析不可变的提取 HA 语料库。 ## 治理与路线图 项目的长期方向记录在 [`docs/roadmap.md`](docs/roadmap.md)。 该路线图不是待办列表。它定义了： - 项目的定位； - 架构层次； - 明确的非目标； - 已接受的发布顺序； - 已知风险； - 包括配置考古在内的未来方向。 功能提议和架构更改在实施前应参照本文档进行评估。 ## 紧凑协议 紧凑引擎的输出是正式版本化和经过验证的。 当前协议标记： ``` # ha-archive-search compact v1 ``` 紧凑协议定义了： - 流语法； - 兼容性保证； - 解析器职责； - 偏移策略； - 破坏性变更预期。 该协议保持： - 人类可读； - 可用 grep 搜索； - Shell 友好； - 依赖轻量； - 面向基础设施。 通过尽力解析器行为，仍然有意地支持遗留兼容性。 ## 集成契约 `ha-archive-search` 操作由 [`ha-state-archive`](https://github.com/antoinevalentinHA/ha-state-archive) 生成的存档。 集成契约是存档语料库的布局，而非 Python API。 引擎期望： - 一个 `versions/` 目录，包含提取的 Home Assistant 快照； - 每个快照一个目录； - 快照目录命名为 `YYYY-MM-DD_HH-MM_<后缀>`。 支持的文件类型： ``` .yaml .yml .json .txt .j2 .jinja .jinja2 .md .py .js .ts .css .html ``` 不存在对 `ha-state-archive` Python 代码的直接依赖。 ## 架构 ``` Archive corpus │ ▼ Engine (compact protocol v1) │ ▼ Parser (ParsedResults) │ ├── HTML renderer ├── Compact Markdown renderer ├── Context Markdown renderer └── Machine-oriented JSONL export ``` 架构是故意分层的。 - 引擎拥有搜索语义。 - 解析器拥有紧凑协议契约。 - 渲染器仅执行结构化呈现。 - 没有渲染器执行语义推断。 ## Markdown 导出 `POST /export` 生成一个从引擎输出派生的结构化 Markdown 文档。 ### 紧凑导出 默认导出模式。布局： - `## 查询` — 搜索参数和导出时间戳。 - `## 摘要` — 结果计数、版本计数、耗时（引擎页脚）。始终存在：如果引擎页脚无法解析，该块将发出一个 `摘要解析：失败` 的诊断行。 - `## 结果` — 按版本分节、按文件分子节（包含匹配次数）、按匹配项列表。 ### 上下文导出 扩展导出模式。为每个匹配项生成周围的配置上下文，针对 AI 辅助审查和深度检查工作流进行了优化。 上下文模式在 `## 结果` 下回退为一个原始代码块。`## 摘要` 块遵循相同的诊断规则。 ### JSONL 导出 面向机器的导出可通过 `/export` 路由使用 `format=jsonl` 获得。 示例： ``` curl -X POST http://localhost:8099/export \ -d "query=ha_shutdown_ups" \ -d "format=jsonl" ``` 导出格式是行导向的 JSONL (`application/x-ndjson`)，并受 `docs/contrat_machine_export.md` 管辖。 当前 v0.5.0 实现范围： - 紧凑的单术语导出； - 从 `ParsedResults` 到确定性渲染器； - RFC3339 UTC 时间戳； - 黄金快照覆盖。 布尔语法、过滤器和 `/stats` 仍待契约化，用于未来实现。 文件命名：`ha_archive_search__.md`。 Markdown 导出作为 `text/markdown; charset=utf-8` 进行流式传输。 JSONL 导出作为 `application/x-ndjson` 进行流式传输。 主机上不写入任何文件。 空结果：在 `## 结果` 下显示单行 `_无结果._`。`## 摘要` 仍会被发出，如果引擎生成了零结果页脚，则正常显示，否则使用诊断行。 ## 验证 该项目包含： - 解析器兼容性测试； - 引擎契约测试； - 渲染器黄金测试； - 学说偏移验证； - 多版本 CI 验证。 紧凑协议契约有意地在以下方面进行验证： - 引擎发出； - 解析器消费； - HTML 渲染； - Markdown 渲染。 ## 功能 ### 当前功能 - 递归文件系统搜索； - 版本感知的存档遍历； - 紧凑协议 v1； - 基于文本的过滤，带文档范围控制； - 紧凑型 Markdown 导出； - 上下文型 Markdown 导出； - 面向机器的 JSONL 导出； - Docker 部署； - 学说验证； - 渲染器黄金验证。 ### 计划功能 计划的演进受 [`docs/roadmap.md`](docs/roadmap.md) 管辖。 当前路线图方向包括： - 有界布尔搜索； - 版本过滤器； - `/stats` 可选观测性； - 版本范围过滤； - 可配置的审计工作流； - 配置考古。 路线图还记录了被拒绝的方向，如项目内的持久化索引、MQTT 集成以及平台式 API 扩展。 ## 部署 Web 应用程序作为 Docker 容器运行在存档语料库所在的相同基础设施上（通常是 NAS 系统）。它可通过局域网和 VPN 访问。不支持或不打算进行公开暴露。 ## 官方容器镜像 官方镜像通过 GitHub Container Registry (GHCR) 发布： ``` ghcr.io/antoinevalentinha/ha-archive-search ``` GHCR 镜像是生产使用的官方部署方法。 本地 Docker 构建主要面向开发、调试和贡献工作流。 可用的标签包括： - `latest` - 版本化发布（`v0.6.2` 等） ## Synology DSM 部署 提供了一个专用的 Synology compose 示例： ``` docker/docker-compose.synology.yml ``` ### 为何存在 Synology 特定的 compose 文件 许多 Synology DSM 共享文件夹使用限制性的 ACL，这阻止了非 root 的容器用户遍历挂载路径。 典型错误： ``` [ha-archive-search] perimeter error: [Errno 13] Permission denied: '/versions' ``` Synology compose 示例明确以 root 用户运行容器： ``` user: "0:0" ``` 这避免了在 DSM 挂载的共享文件夹上发生遍历失败。 高级用户可以将其替换为自定义的 UID:GID 映射。 ## 仓库结构 ``` src/ source code docker/ Dockerfile and Docker Compose configuration docs/ domain vision, roadmap, and implementation contracts tests/ protocol, parser, renderer, and doctrine validation ``` 文档契约和治理文档位于 `docs/`。 ## 许可证 GPL-3.0-only

标签：Docker, Home Assistant, Markdown 导出, NAS 存储, Web 应用, 基础设施工具, 安全防御评估, 审计工具, 家庭自动化, 导出工具, 归档搜索, 快照工具, 搜索工具, 搜索引擎, 文档结构分析, 杀软绕过, 语料库搜索, 请求拦截, 轻量级应用, 逆向工具, 配置快照