# https://github.com/HelixDB/helix-db 项目说明书

生成时间：2026-06-10 18:45:36 UTC

## 目录

- [项目概览与快速开始](#page-1)
- [CLI 命令与本地运行时管理](#page-2)
- [Rust / TypeScript / Go SDK 与查询 DSL](#page-3)
- [高级检索特性、云部署与社区路线](#page-4)

<a id='page-1'></a>

## 项目概览与快速开始

### 相关页面

相关主题：[CLI 命令与本地运行时管理](#page-2), [Rust / TypeScript / Go SDK 与查询 DSL](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)
- [helix-cli/README.md](https://github.com/HelixDB/helix-db/blob/main/helix-cli/README.md)
- [helix-cli/src/main.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs)
- [helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)
- [helix-cli/src/commands/mod.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs)
- [helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)
- [helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)
- [helix-cli/src/commands/sync.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/sync.rs)
- [helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)
- [sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)
- [sdks/rust/helix-dsl-macros/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/README.md)
</details>

# 项目概览与快速开始

## 1. 项目定位与核心价值

HelixDB 是一个面向知识图谱与 AI 记忆场景的 **图-向量混合数据库**（graph-vector database），从底层到查询语言均使用 Rust 自研实现。官方在 [README.md](https://github.com/HelixDB/helix-db/blob/main/README.md) 中将其定位为 "a graph-vector database for knowledge graphs and AI memory. Built from scratch in Rust."，并以 RAG/AI Memory 为典型落地形态。当前社区可获取的最新发布版本为 **v3.0.5**。

需要注意的是，社区对仓库的"开源边界"有过讨论（[issue #922](https://github.com/HelixDB/helix-db/issues/922)）：v2 数据库核心代码在合并相关 PR 后已不在主仓公开，团队回复将"在未来的 v2 db 中重新开源"。读者在阅读本文档与源码时，应意识到仓库当前公开的是 CLI、SDK、查询运行时分以及构建配置等周边代码，并不一定包含 v2 数据库的完整实现细节。

## 2. 仓库组成与 CLI 角色

仓库的根目录承担"产品门面 + 工具链入口"的角色：

- **根 README** 介绍品牌、链接到 [docs.helix-db.com](https://docs.helix-db.com) 与 Discord，提供视觉与项目定位信息（[README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)）。
- **`helix-cli/`** 是 v2 项目的统一命令行入口，覆盖本地开发、企业云部署、认证与同步等全生命周期（[helix-cli/README.md](https://github.com/HelixDB/helix-db/blob/main/helix-cli/README.md)）。
- **`sdks/`** 目录提供多语言 SDK：TypeScript SDK 面向 Node.js 20+（[sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)），Rust 端通过 `helix-dsl-macros` 提供过程宏以类型安全的方式声明查询入口（[sdks/rust/helix-dsl-macros/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/README.md)）。

`helix-cli` 的模块化设计使其既能作为终端工具，也能被嵌入其他 Rust 程序复用。入口分发通过 clap 派生宏完成，所有顶层子命令在 [helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs) 中以 `Subcommand` 形式声明，并由 [helix-cli/src/main.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs) 负责 `wants_top_level_help()` 解析、彩色帮助输出与全局版本号注入。命令实现按子模块拆分，统一在 [helix-cli/src/commands/mod.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs) 暴露为 `add / auth / chef / config / delete / enterprise_deploy / feedback / init / logs / metrics / prune / push / query / restart / skills / start / status / stop / sync / update`。

## 3. 快速开始：本地开发与云端部署

CLI 提供两种初始化路径：本地 `init local` 与企业云 `init cloud`（[helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)）。本地实例默认端口由 `config::DEFAULT_LOCAL_PORT` 解析得到，并可通过 `--port` 覆盖；`--disk` 标志会切换为基于本地 MinIO 容器持久化的存储模式（[helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)）。

对希望"开箱即用"的开发者，**`helix chef`** 命令会自动装配技能、文档 MCP、本地运行时、起始查询、种子数据，并启动一个编码代理（[helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)）。它会写入 `CHEF_SNAPSHOT_SCHEMA_VERSION` 标记的快照文件，保留 build intent、rendered prompt、agent 报告与项目文本，便于回放与诊断。日常开发的标准流程可总结为：

```mermaid
flowchart LR
    A[helix init local] --> B[helix run]
    B --> C{需要云端?}
    C -- 否 --> D[迭代 db/ 下的查询]
    C -- 是 --> E[helix push 部署到 Enterprise 集群]
    E --> F[helix sync 同步元数据回 helix.toml]
```

CLI 关键子命令速查如下表所示：

| 命令 | 用途 | 来源 |
|---|---|---|
| `init` | 初始化 v2 项目，生成 `helix.toml` 与示例查询 | [helix-cli/README.md](https://github.com/HelixDB/helix-db/blob/main/helix-cli/README.md) |
| `chef` | 一键搭建首个 Helix 应用并启动编码代理 | [helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs) |
| `run` | 后台运行本地实例，`--foreground` 前台运行，`--disk` 持久化 | [helix-cli/README.md](https://github.com/HelixDB/helix-cli/README.md) |
| `query` | 将动态查询请求 JSON 发送到 `POST /v1/query` | [helix-cli/README.md](https://github.com/Helix-cli/README.md) |
| `push` | 编译并部署 Enterprise 查询项目到云端集群 | [helix-cli/README.md](https://github.com/HelixDB/helix-cli/README.md) |
| `auth / workspace / project / cluster / sync` | 企业云身份、上下文与元数据管理 | [helix-cli/src/commands/sync.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/sync.rs) |

部署过程会与 Helix Cloud 建立 **SSE 长连接**，实时回传 `ValidatingQueries → Building(percentage) → Deploying → Deployed(url, auth_key)` 等阶段事件，超时默认 5 分钟（[helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)）。事件模型既覆盖首次部署，也支持现有实例的 `Redeployed` 与统一 `Done` 事件，方便 CLI 与 Dashboard 对齐。

## 4. 配置、SDK 与常见落点

`helix.toml` 由 `ProjectConfig` 与 `local` / `enterprise` 实例集合组成，项目名、查询目录（默认 `db`）与容器运行时均在配置层校验，缺失 `instances` 会直接报错（[helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)）。`helix workspace config` 与 `helix project switch` 等子命令用于在多团队/多项目场景下切换当前生效的 cloud 上下文。

在查询层：

- **TypeScript SDK** 面向 Node.js 20+，提供 `g` / `readBatch` / `writeBatch` / `defineParams` / `param` 等 DSL 原语；CLI 会在首次使用 `query` 时通过 `npm install @helix-db/helix-db@<spec>` 注入运行时，并用 `SPEC_MARKER` 文件锁定版本以避免重复安装（[helix-cli/src/ts_query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)，[sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)）。
- **Rust DSL 宏** 通过 `query_handler` / `mutation_handler` 将函数包装成 Helix 端点，参数类型被映射为 `Bool / I64 / F32 / F64 / String / Bytes / Value / Object / Array(T)`，但显式拒绝 `async`、泛型、含 `self` 的方法与返回非 `ReadBatch/WriteBatch` 的函数（[sdks/rust/helix-dsl-macros/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/README.md)）。

## 5. 常见失败模式与社区关注点

- **嵌入式 / WASM 模式**：社区多次询问"是否有 SQLite 风格的进程内嵌入"（[issue #848](https://github.com/HelixDB/helix-db/issues/848)）与浏览器内 WASM 支持（[issue #67](https://github.com/HelixDB/helix-db/issues/67)），截至 v3.0.5 暂无内置实现，需要通过 HTTP/SDK 客户端调用远端实例。
- **大量初始数据导入**：[issue #896](https://github.com/HelixDB/helix-db/issues/896) 提议 `POST /bulk_import` 在单一 LMDB 写事务内批量写入节点/边；当前流程仍需通过 query 引擎逐条写入。
- **检索能力扩展**：BM25 模糊匹配（[issue #781](https://github.com/HelixDB/helix-db/issues/781)）、SearchV 预过滤（[issue #834](https://github.com/HelixDB/helix-db/issues/834)）以及多路 SearchV + RRF（[issue #863](https://github.com/HelixDB/helix-db/issues/863)、[issue #828](https://github.com/HelixDB/helix-db/issues/828)）正在被讨论，落地形态尚未在 CLI 与 SDK 中暴露。
- **数据分支与克隆**：[issue #787](https://github.com/HelixDB/helix-db/issues/787) 提议 `helix branch` 通过 LMDB 的 `env copy` 能力复制运行中的数据库；该命令目前尚未在 CLI 子命令列表中出现。

## See Also

- CLI 命令一览：[helix-cli/README.md](https://github.com/HelixDB/helix-db/blob/main/helix-cli/README.md)
- Rust DSL 宏使用指南：[sdks/rust/helix-dsl-macros/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/README.md)
- TypeScript SDK 入口：[sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)
- 部署事件流模型：[helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)
- 项目配置结构：[helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)

---

<a id='page-2'></a>

## CLI 命令与本地运行时管理

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [高级检索特性、云部署与社区路线](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [helix-cli/src/main.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs)
- [helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)
- [helix-cli/src/commands/mod.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs)
- [helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)
- [helix-cli/src/commands/enterprise_deploy.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/enterprise_deploy.rs)
- [helix-cli/src/commands/sync.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/sync.rs)
- [helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)
- [helix-cli/src/ts_query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)
- [helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)
- [helix-cli/src/output.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/output.rs)
- [helix-cli/src/errors.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/errors.rs)
- [helix-cli/README.md](https://github.com/HelixDB/helix-db/blob/main/helix-cli/README.md)
- [README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)
</details>

# CLI 命令与本地运行时管理

## 概述

`helix` CLI 是 HelixDB v2 项目的统一入口，负责管理本地开发实例、企业云部署、项目脚手架与查询运行时。CLI 基于 `clap` 派生宏构建，子命令覆盖 `init`、`chef`、`add`、`run`、`stop`、`restart`、`status`、`logs`、`query`、`push`、`auth`、`workspace`、`project`、`cluster`、`sync`、`prune`、`delete`、`metrics`、`update`、`feedback`。所有子命令通过 `helix-cli/src/commands/mod.rs` 注册并按职责拆分到独立模块。CLI 同时承载两套生命周期：本地容器化运行时（默认无盘，可通过 `--disk` 切换到 MinIO 持久化）与企业云部署（编译 `queries.json` 并通过 SSE 流式回传状态）。`helix query` 子命令通过 `POST /v1/query` 动态执行 HQL/TypeScript DSL 片段。资料来源：[helix-cli/src/commands/mod.rs:1-20]()、[helix-cli/README.md:5-30]()。

## CLI 架构与子命令清单

CLI 入口在 `helix-cli/src/main.rs` 中以 `Cli` 结构体的 `#[derive(Parser)]` 形式声明顶层命令，`AuthAction`、`InitTarget`、`ConfigAction`、`WorkspaceConfigAction`、`ProjectConfigAction`、`ClusterConfigAction` 等枚举在 `helix-cli/src/lib.rs` 中集中定义并通过 `#[derive(Subcommand)]` 注册子命令。这种"单二进制多子命令"模型让本地开发与企业发布共用同一分发渠道。资料来源：[helix-cli/src/lib.rs:23-78]()、[helix-cli/src/main.rs:24-71]()。

| 子命令 | 作用 | 关键模块 |
|---|---|---|
| `init` | 创建 v2 项目，生成 `helix.toml` 与示例查询 | `commands/init.rs` |
| `chef` | 引导首个 Helix 应用：技能、文档 MCP、本地运行时、种子数据 | `commands/chef.rs` |
| `run` / `stop` / `restart` / `status` | 管理本地 v2 实例 | `local_runtime.rs` |
| `query` | 发送动态查询请求 JSON 到 `POST /v1/query` | `ts_query.rs` |
| `push` | 编译并部署到企业云 | `commands/enterprise_deploy.rs` |
| `sync` | 协调企业云项目源码并同步元数据到 `helix.toml` | `commands/sync.rs` |

## 本地运行时管理

本地实例由 `local_runtime` 模块统一编排，默认在后台启动容器；`--foreground` 用于附加前台日志，`--disk` 启用 MinIO 卷实现持久化存储。`start`、`stop`、`restart`、`status` 四个子命令复用同一配置抽象（`HelixConfig::local` 中的 `LocalInstanceConfig`）以避免硬编码端口或路径，并通过 `PathBuf::from("db")` 的默认 `queries` 路径定位查询源码。资料来源：[helix-cli/src/config.rs:115-180]()。

`chef` 子命令在 `helix-cli/src/commands/chef.rs` 中描述了一个完整的"开发者上手"工作流：安装 Agent 技能、文档 MCP、本地运行时、初始查询与种子数据，并启动一个编码 Agent。所有 UI 必须遵循项目根目录的 `DESIGN.md` 品牌指南——暗色主题、橙色 `#FF5C01` 强调色、`rounded-none` 圆角规范以及 `lucide-react` 图标库。前端查询通过 `web/src/lib/helix.ts` 中的 `runQuery()` 调用本地 `HELIX_URL`，保证浏览器不直接连接 `:6969`。资料来源：[helix-cli/src/commands/chef.rs:1-30]()。

## 配置、查询执行与云端同步

`helix-cli/src/config.rs` 定义了 `HelixConfig`、`ProjectConfig`、`LocalInstanceConfig`、`EnterpriseInstanceConfig` 四层结构，并使用 `serde::Serialize/Deserialize` 序列化到 `helix.toml`。`validate()` 会拒绝空项目名、空实例名以及缺少实例的非法配置，每个失败变体都携带原始路径以便定位。资料来源：[helix-cli/src/config.rs:38-95]()、[helix-cli/src/errors.rs:18-58]()。

`helix query` 通过 `ts_query.rs` 加载 `@helix-db/helix-db` SDK，在 Node 子进程中包装动态查询片段并打印 `toDynamicJson()` 结果；如果 SDK 未安装或 `SDK_SPEC` 已升级，则会触发 `npm install` 重装流程，`SDK_SPEC` 通过 `SPEC_MARKER` 文件缓存以避免重复安装。资料来源：[helix-cli/src/ts_query.rs:24-60]()。

企业云部署通过 `enterprise_deploy.rs` 调用 `cargo run` 编译企业查询项目生成 `queries.json`，并通过 `SseClient` 流式消费服务器事件：`ValidatingQueries`、`Building`、`Deploying`、`Deployed`、`Redeployed`、`Done` 等状态会被序列化为 `DeployEvent` 并以日志友好的方式呈现。`sync` 子命令在本地与远程清单之间执行 `sha256` 比较，按 `Pull` 或 `Push` 方向生成 `SyncActionPlan`，支持 `--yes` 与 `--dry-run` 模式。资料来源：[helix-cli/src/commands/enterprise_deploy.rs:1-60]()、[helix-cli/src/sse_client.rs:30-78]()、[helix-cli/src/commands/sync.rs:14-72]()。

## 输出、错误处理与社区关注点

`helix-cli/src/output.rs` 集中处理动词的过去式转换（如 "Building" → "Built"）与时长格式化（`50ms`、`1.2s`），保证 CLI 行为可测试。`errors.rs` 使用 `thiserror` 派生具体错误变体（`ParseHelixConfig`、`WriteHelixConfig`、`EmptyProjectName` 等），每个变体携带原始路径便于定位。资料来源：[helix-cli/src/output.rs:1-50]()、[helix-cli/src/errors.rs:18-58]()。

社区方面，`#922` 提示 v2 数据库核心代码当前仍以闭源形式合并，社区期待后续重新开源；`#848` 与 `#67` 分别讨论 SQLite 风格的嵌入式模式以及浏览器 WASM 支持——这两类能力都会改变本地运行时的交付形态（嵌入式 in-process 或 WASM 沙箱），值得跟踪。此外，`#787` 提议的 `helix branch` 命令以及 `helix query` 配合 TypeScript DSL 的能力，均依赖本文描述的配置/部署/查询通路。资料来源：[issue #922](https://github.com/HelixDB/helix-db/issues/922)、[issue #848](https://github.com/HelixDB/helix-db/issues/848)、[issue #67](https://github.com/HelixDB/helix-db/issues/67)、[issue #787](https://github.com/HelixDB/helix-db/issues/787)。

## See Also

- `helix init` 项目脚手架与 `helix.toml` 字段语义
- HQL 动态查询 DSL（`sdks/rust/src/dsl.rs`）
- 企业云 `push` / `sync` 部署生命周期
- `DESIGN.md` 品牌指南与 `chef` 工作流

---

<a id='page-3'></a>

## Rust / TypeScript / Go SDK 与查询 DSL

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [高级检索特性、云部署与社区路线](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [sdks/rust/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/src/lib.rs)
- [sdks/rust/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/README.md)
- [sdks/rust/helix-dsl-macros/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/src/lib.rs)
- [sdks/rust/helix-dsl-macros/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/helix-dsl-macros/README.md)
- [sdks/typescript/README.md](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/README.md)
- [sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)
- [helix-cli/src/ts_query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)
- [helix-cli/src/commands/query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/query.rs)
- [helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)
- [helix-cli/src/main.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs)
- [helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)
- [README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)
</details>

# Rust / TypeScript / Go SDK 与查询 DSL

## 1. 概述与定位

HelixDB 是以 Rust 从零构建的图向量数据库,面向知识图谱与 AI 记忆场景。围绕核心数据库,项目提供了三套并行的 SDK —— **Rust、TypeScript、Go** —— 它们共享同一套 JSON AST 协议,使不同语言的客户端能够发出结构等价的查询请求。

```mermaid
flowchart LR
  subgraph Client["客户端 SDK"]
    A[Rust DSL<br/>helix_db::dsl]
    B[TypeScript DSL<br/>@helix-db/helix-db]
    C[Go DSL<br/>helix-db-go]
  end
  A -->|toDynamicJson| J[统一 JSON AST]
  B -->|toDynamicJson| J
  C -->|toDynamicJson| J
  J -->|/v1/query| H[HelixDB 实例<br/>:6969]
  H -->|响应 JSON| A
  H -->|响应 JSON| B
  H -->|响应 JSON| C
```

资料来源：[sdks/rust/src/lib.rs:1-25]()、[sdks/typescript/README.md:1-6]()。

**核心契约**:Object 格式与字段顺序不属于协议,但 enum tag、字段名、显式 `null`、bundle 元数据以及 dynamic request payload 必须与 Rust serde 的输出对齐。Go SDK 的 parity 工具链与 Rust/TypeScript 一致(`npm run parity:generate` 包含 `parity:generate:go`)。资料来源：[sdks/typescript/README.md:5-9]()、[sdks/typescript/package.json:9-15]()。

## 2. Rust SDK 与 `#[register]` 宏

Rust SDK 的导入名为 `helix_db`,其 DSL 由两个入口组成:

- `read_batch()` —— 只读事务;
- `write_batch()` —— 可写事务。

链式调用形如 `read_batch() → var_as / var_as_if → returning`,每个 `var_as` 接受一个通常以 `g()` 开头的 traversal 表达式。资料来源：[sdks/rust/README.md:25-39]()。

### 2.1 `#[register]` 宏的参数类型映射

`helix-dsl-macros` 提供了 `#[register]` 过程宏,把函数签名映射成 JSON Schema 风格的参数描述。下表列出当前已支持类型:

| Rust 类型 | 映射结果 |
|---|---|
| `bool` / `i64` / `f32` / `f64` / `String` | `Bool` / `I64` / `F32` / `F64` / `String` |
| `Vec<u8>` | `Bytes` |
| `PropertyValue` / `ParamValue` | `Value` |
| `ParamObject` / `HashMap<String,T>` / `BTreeMap<String,T>` | `Object` |
| `Vec<T>` | `Array(T)`(递归) |

宏拒绝以下函数:`async`、泛型、带 `self` 接收器、参数解构模式、返回类型非 `ReadBatch`/`WriteBatch`。资料来源：[sdks/rust/helix-dsl-macros/README.md:7-30]()、[sdks/rust/helix-dsl-macros/src/lib.rs:30-80]()。

### 2.2 客户端执行

`helix_db::Client` 是配套的异步 HTTP 客户端,负责把 DSL 构造的请求发往运行中的 Helix 实例。文档建议 AI agent 阅读 `sdks/rust/src/lib.rs` 的 doc 注释以掌握 builder 模式与 API 全貌。资料来源：[sdks/rust/src/lib.rs:3-19]()、[sdks/rust/README.md:1-7]()。

## 3. TypeScript SDK

TypeScript 包 `@helix-db/helix-db` 提供与 Rust 同构的 builder API 以及一个镜像 Rust client 的 `Client` 网络对象。

最小示例(摘自 README):

```ts
import { defineParams, g, param, readBatch } from "@helix-db/helix-db";

const params = defineParams({
  tenantId: param.string(),
  limit: param.i64(),
});

function findUsers(p = params) {
  return readBatch()
    .varAs("users", g().nWithLabel("User").limit(p.limit).valueMap(["$id", "name"]))
    .returning(["users"]);
}
```

Builder 是普通函数,调用后返回 `ReadBatch` 或 `WriteBatch`,可以调用 `toJsonString()` / `toDynamicJson()` / `toDynamicRequest()` 三种序列化方法。命名映射遵循 Rust → camelCase:`read_batch()` → `readBatch()`、`var_as(...)` → `varAs(...)`、`NodeRef::var(...)` → `NodeRef.var(...)`、`SourcePredicate::eq(...)` → `SourcePredicate.eq(...)`。资料来源：[sdks/typescript/README.md:8-72]()。

包要求 Node.js ≥ 20,parity 测试由三阶段组成:Rust fixture 生成 → TS fixture 生成 → JSON 比对 → `helix` 端运行验证。资料来源：[sdks/typescript/package.json:7-25]()。

## 4. CLI 集成与查询执行路径

`helix` CLI 把上述 SDK 串成一条完整链路,核心子命令如下:

| 子命令 | 作用 |
|---|---|
| `chef` (alias `cook`) | 用 coding agent 引导式脚手架生成 Helix 应用 |
| `init` (`init local` / `init cloud`) | 创建新项目骨架 |
| `add` | 为已存在项目添加本地或 Cloud 实例 |
| `start` (alias `run`) / `stop` / `restart` | 本地实例的生命周期管理 |
| `query` | 解析并发送动态查询请求 |

资料来源：[helix-cli/src/main.rs:9-65]()。

### 4.1 TypeScript 查询的本地执行

当用户以 `--ts <file>` 提交 TypeScript 片段时,CLI 会在运行时目录写入一个 Node ESM 包装文件 `__helix_query_<pid>_<nanos>.mjs`,其中:

1. 注入 `g`、`readBatch`、`writeBatch`、`defineParams`、`param` 等公共 DSL 导入;
2. 把片段当作表达式求值;
3. 校验结果具备 `toDynamicJson()` 函数;
4. 将序列化的 JSON 打印到 stdout。

`ts_query.rs` 会复用 `node_modules/@helix-db/helix-db` 中的 SDK 安装,只有当包目录或 `SPEC_MARKER` 缺失时才重跑 `npm install`。运行从 `runtime_dir` 启动 Node,以保证 `node_modules` 解析。资料来源：[helix-cli/src/ts_query.rs:1-80]()。

### 4.2 动态请求校验

`helix query` 的请求体必须满足:`request_type` 为小写 `"read"` 或 `"write"`、`query` 字段存在;若传入 `--warm`,则 `request_type` 必须为 `"read"`。资料来源：[helix-cli/src/commands/query.rs:18-35]()。

### 4.3 工作区配置

项目级 `HelixConfig` 包含 `ProjectConfig`(必填 `name`、可选 `queries`、`container_runtime`,默认 `queries = db`)以及 `local`/`enterprise` 实例映射,序列化使用 `toml::to_string_pretty`。资料来源：[helix-cli/src/config.rs:50-80]()。

## 5. 与社区讨论的关联

社区中关于"Hybrid Search with RRF(`SearchBM25 + SearchV`)"、"SearchV prefilter"、"多 SearchV 结果合并"等特性请求(#828、#834、#863)均建立在当前 DSL 的 chain-of-traversal 形态之上 —— `RerankRRF`、`WHERE(...)`、`SearchHybrid` 都在 `var_as` 链上组合,因此理解 read/write batch + `var_as` + `returning` 的核心骨架是使用这些能力的前提。

另需注意,issue #922 提到 "v2 db 在合并 PR #913 后大部分 DB 代码消失,官方承诺未来会开源 v2",所以本页描述的 SDK 协议以当前 main 分支公开代码为准。

---

## See Also

- [Hybrid Search with RRF 设计提案 #828](https://github.com/HelixDB/helix-db/issues/828)
- [SearchV prefilter 设计提案 #834](https://github.com/HelixDB/helix-db/issues/834)
- [多 SearchV 结果合并 #863](https://github.com/HelixDB/helix-db/issues/863)
- [开源状态说明 #922](https://github.com/HelixDB/helix-db/issues/922)

---

<a id='page-4'></a>

## 高级检索特性、云部署与社区路线

### 相关页面

相关主题：[CLI 命令与本地运行时管理](#page-2), [Rust / TypeScript / Go SDK 与查询 DSL](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)
- [helix-cli/src/lib.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)
- [helix-cli/src/main.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs)
- [helix-cli/src/commands/mod.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs)
- [helix-cli/src/commands/sync.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/sync.rs)
- [helix-cli/src/commands/enterprise_deploy.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/enterprise_deploy.rs)
- [helix-cli/src/commands/chef.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)
- [helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)
- [helix-cli/src/ts_query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)
- [helix-cli/src/config.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)
- [helix-cli/src/errors.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/errors.rs)
- [helix-cli/src/output.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/output.rs)
- [sdks/rust/src/dsl.rs](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/src/dsl.rs)
- [sdks/typescript/package.json](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)
</details>

# 高级检索特性、云部署与社区路线

## 项目定位与整体架构

HelixDB 是一个面向知识图谱与 AI 记忆场景的"图-向量"数据库，整体由 Rust 从零实现，配套提供 TypeScript SDK、Rust SDK 以及 `helix` 命令行工具。资料来源：[README.md:1-15](https://github.com/HelixDB/helix-db/blob/main/README.md)。仓库当前最新发布版本为 v3.0.5，社区讨论主要围绕三类主题展开：检索能力扩展、云部署体验、以及开源与运行模式的演进。

CLI 入口位于 `helix-cli/src/main.rs`，通过 `helix` 子命令调度本地与云端两类操作；命令注册表收录于 `helix-cli/src/commands/mod.rs`，覆盖 `init`、`start`、`query`、`push`、`sync`、`auth`、`cluster`、`prune` 等核心动作。资料来源：[helix-cli/src/main.rs:1-30](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/main.rs)、[helix-cli/src/commands/mod.rs:1-20](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs)。Rust SDK 在 `sdks/rust/src/dsl.rs` 中描述了 HQL DSL 暴露的算子集合，包括遍历算子（`Out`、`In`、`Where`）、终止算子（`count`、`id`、`values`）以及写入算子（`AddN`、`AddE`、`SetProperty`）。资料来源：[sdks/rust/src/dsl.rs:1-30](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/src/dsl.rs)。

## 高级检索特性与查询能力

### 向量与关键字检索

HQL DSL 已经把 BM25 关键字搜索与向量搜索（`SearchV`）作为一等公民暴露，TypeScript SDK 在 `sdks/typescript/package.json` 中通过 `test:parity` 系列脚本保证多语言算子一致性。资料来源：[sdks/typescript/package.json:1-25](https://github.com/HelixDB/helix-db/blob/main/sdks/typescript/package.json)。社区在 issue #828、#834、#863 中提出"混合搜索 + RRF 重排序"思路，希望扩展 `SearchHybrid` 与 `RerankRRF` 的组合边界，让多次 `SearchV` 结果能够被统一重排序；同时也希望为 `SearchV` 增加 prefilter，使过滤在 HNSW 遍历阶段就生效。

### 嵌入式与端到端使用形态

issue #848 询问是否存在 SQLite 风格的进程内模式。仓库目前通过 `helix init local --disk` 提供基于容器的本地实例，参数定义见 `helix-cli/src/lib.rs` 的 `InitTarget::Local`，但并未提供嵌入式库模式——该 issue 的 6 条评论表明这是社区的明确诉求。资料来源：[helix-cli/src/lib.rs:1-50](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/lib.rs)。`helix-cli/src/commands/chef.rs` 同时描述了 AI Agent 通过 TypeScript SDK 调用本地 `http://localhost:6969/v1/query` 的端到端数据流，强调所有 Helix 调用都必须在服务端完成。资料来源：[helix-cli/src/commands/chef.rs:1-30](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/chef.rs)。`helix-cli/src/ts_query.rs` 则负责把 HQL 片段注入 Node 运行时并执行 `toDynamicJson()`，便于在本地快速试验查询。资料来源：[helix-cli/src/ts_query.rs:1-30](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)。

## 云部署与 CLI 工作流

### Enterprise Cloud 命令体系

云端部署由 `helix push`、`helix auth`、`helix sync`、`helix cluster` 等命令驱动，定义见 `helix-cli/src/lib.rs`。`helix push` 会通过 `cargo run` 编译查询工程并生成 `queries.json`，具体流程见 `helix-cli/src/commands/enterprise_deploy.rs`，其中会检查 manifest 路径、`queries.json` 是否存在且非空。资料来源：[helix-cli/src/commands/enterprise_deploy.rs:1-40](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/enterprise_deploy.rs)。

### 部署状态流（SSE）

部署过程的实时状态通过 SSE 推送，`helix-cli/src/sse_client.rs` 定义了 `ValidatingQueries`、`Building`、`Deploying`、`Deployed`、`Redeployed`、`Done`、`QueryValidationError` 等事件，配合 `helix-cli/src/output.rs` 的过去时态映射在终端展示进度。资料来源：[helix-cli/src/sse_client.rs:1-50](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)、[helix-cli/src/output.rs:1-20](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/output.rs)。

### 同步与配置

`helix sync` 负责本地 `helix.toml` 与远端的协调，`helix-cli/src/commands/sync.rs` 中 `ManifestEntry`/`ManifestDiff`/`DivergenceAuthority` 三层结构决定了推送或拉取方向；配置文件由 `helix-cli/src/config.rs` 中的 `HelixConfig`、`ProjectConfig`、`LocalInstanceConfig`、`EnterpriseInstanceConfig` 四类结构组成，错误信息在 `helix-cli/src/errors.rs` 中被完整建模。资料来源：[helix-cli/src/commands/sync.rs:1-30](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/sync.rs)、[helix-cli/src/config.rs:1-60](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/config.rs)、[helix-cli/src/errors.rs:1-40](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/errors.rs)。

```mermaid
flowchart LR
  A["helix init local"] --> B["本地 dev 容器"]
  A2["helix push"] --> C["enterprise_deploy.rs 编译"]
  C --> D["生成 queries.json"]
  D --> E["SSE: Validating/Building"]
  E --> F["SSE: Deployed/Done"]
  F --> G["Enterprise Cloud 集群"]
  H["helix sync"] <--> G
```

## 社区关注点与路线图

| 议题 | Issue | 当前状态 / 诉求 |
| --- | --- | --- |
| 开源状态 | #922 | PR #913 后核心 DB 代码被移除，官方答复未来开源 v2 DB |
| 批量导入 | #896 | 请求 `POST /bulk_import`，单事务写入 100K+ 节点、1M+ 边 |
| 模糊关键字搜索 | #781 | 基于 RapidFuzz 增强 BM25，容忍拼写与词形变化 |
| 大规模召回 | #875 | 提出 Rust 原生检索内核，100K 向量下 Recall@10 从 79% 提升至 89% |
| 数据库分支 | #787 | 基于 LMDB `env copy` 的 `helix branch`，克隆数据库并部署新实例 |
| 嵌入式模式 | #848 | 社区请求 SQLite 风格的进程内运行 |
| WASM 支持 | #67 | 浏览器侧 demo，长期路线项 |

这些讨论横跨检索内核、导入吞吐、部署工具链与运行形态四个层面，构成当前社区路线图的主线。

## See Also

- 项目主页与文档：[README.md](https://github.com/HelixDB/helix-db/blob/main/README.md)
- CLI 命令注册：[helix-cli/src/commands/mod.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/commands/mod.rs)
- HQL DSL 算子清单：[sdks/rust/src/dsl.rs](https://github.com/HelixDB/helix-db/blob/main/sdks/rust/src/dsl.rs)
- 部署事件流：[helix-cli/src/sse_client.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/sse_client.rs)
- 本地查询运行时：[helix-cli/src/ts_query.rs](https://github.com/HelixDB/helix-db/blob/main/helix-cli/src/ts_query.rs)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：helixdb/helix-db

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Feature]: Fuzzy Keyword Search (RapidFuzz) to Enhance BM25 in HelixDB。

## 1. 安全/权限坑 · 来源证据：[Feature]: Fuzzy Keyword Search (RapidFuzz) to Enhance BM25 in HelixDB

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Fuzzy Keyword Search (RapidFuzz) to Enhance BM25 in HelixDB
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0c11aafbc9004130b73b57570687726c | https://github.com/HelixDB/helix-db/issues/781 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：[Feature]: Add helix branch command to clone database for new instances

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Add helix branch command to clone database for new instances
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d0ffd160ec924afe9da517ca2c70cf1f | https://github.com/HelixDB/helix-db/issues/787 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：feat: Hybrid Search with RRF (SearchBM25 + SearchV)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Hybrid Search with RRF (SearchBM25 + SearchV)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3740a047826c44fbb0618fb414c2b2bb | https://github.com/HelixDB/helix-db/issues/828 | 来源类型 github_issue 暴露的待验证使用条件。

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

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | host_targets=mcp_host, claude_code, claude

## 5. 配置坑 · 来源证据：[Feature]: Bulk import endpoint for batch node/edge creation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature]: Bulk import endpoint for batch node/edge creation
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5246413a7d6d4e6387802d5337c37a63 | https://github.com/HelixDB/helix-db/issues/896 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 6. 能力坑 · 来源证据：[Feature]: Combining results from multiple SearchV calls into a single RRF-ranked list

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Combining results from multiple SearchV calls into a single RRF-ranked list
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_459459393fb747beb350857e7c23bae6 | https://github.com/HelixDB/helix-db/issues/863 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | README/documentation is current enough for a first validation pass.

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

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | last_activity_observed missing

## 9. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | hn_item:48478148 | https://news.ycombinator.com/item?id=48478148 | release_recency=unknown

<!-- canonical_name: helixdb/helix-db; human_manual_source: deepwiki_human_wiki -->