开放核心

Heldar 以开放核心平台的形式发布：Apache-2.0 内核和一组通用参考应用程序对外公开，而垂直行业及客户专属产品则作为独立的私有 crate 存放在私有仓库中。这一分界线在 crate 边界处强制执行，而非通过单一代码库内的功能标志实现。

开放部分（Apache-2.0）

公开的 heldar 仓库包含：

• heldar-kernel - 领域无关的平台：媒体/DVR、感知采集与帧采样器、区域引擎、auth/RBAC、可观测性、数据保留，以及公共接缝（DetectionConsumer 特征、Router<AppState> 合并、自安装 schema 模式和认证原语）。
• 通用参考应用，每个应用均仅基于内核的公共接缝构建：
  • heldar-entry - 通用门禁控制。车牌授权（一个 DetectionConsumer）、车辆/访客/黑名单注册表、保安确认/拒绝工作流，以及进出记录/异常/审计报告。领域中立：任何门控入口部署均可直接使用。
  • heldar-movement - 跨摄像头关联。多信号 ReID 候选提议器和限制区域违规规则引擎，均以受监督的后台循环方式运行，基于已存储的内核事实。可选且默认关闭的 appearance_score（CLIP 裁剪图相似度）可作为附加的 ReID 信号，次于车牌锚点。
  • heldar-search - 语义搜索。一个只读查询层，将自然语言问题转换为结构化执行计划，确定性地在已存储的事件事实上执行，并将结果行作为答案返回。现在还包含基于内核存储的裁剪图嵌入的 CLIP 相似度检索（支持文本与图像查询）——仍然只读，仍然不返回模型生成的答案。
• heldar-server - 参考组合二进制文件，链接内核和通用应用程序。
• apps/ai - 参考 Python AI 工作进程。
• apps/web - React + Vite + TypeScript 仪表板。
• 文档、基础设施（MediaMTX 配置）和脚本。

私有部分

垂直行业和客户专属产品以独立 crate 的形式存放在各自的私有仓库中（每个产品一个仓库，使其发布周期互不影响）。它们依赖于开放 crate（通过 crates.io，以及用于并行开发的本地路径补丁），并在其之上叠加各自的领域细节。它们不会被合并进本仓库，内核也不会引用它们。

组合服务器本身是一个库：heldar_server::run(impl Verticals) 接受一个包含四个钩子的组合 trait，因此私有产品只需针对这些 crate（内核与应用来自 crates.io，组合 crate 通过 git 标签引用）编写几十行代码即可构建自己的二进制文件——无需 fork 本仓库，也无需替换文件。本仓库的 heldar-core 二进制文件组合了开放应用和一个无操作的 Verticals，因此参考构建不链接任何私有代码。

为何采用此架构

拥有内核意味着拥有元数据模型、事件引擎和产品逻辑，而接缝使应用程序与内核保持解耦。一个部署由内核加上客户所需的任意应用程序组成（每个部署单租户），因此开放通用应用和任何私有垂直应用只是链接到服务器构建中的 crate。对内核接缝的破坏性变更将触发主版本号升级，应用程序可选择是否接受。

许可证

内核和通用应用程序采用 Apache-2.0 许可证。私有垂直应用程序单独授权。请参阅 LICENSING.md 了解边界划分。