maestro-flow 0.5.33 → 0.5.35

package/README.zh-CN.md

@@ -2,22 +2,58 @@
 
 # Maestro-Flow
 
-### 多智能体时代的编排层
+### 多智能体时代的意图驱动工作流编排
 
-**不仅是执行，更是编排。**
+**描述你想要什么，Maestro 负责搞定。**
 
+<br/>
+
+[![npm version](https://img.shields.io/npm/v/maestro-flow?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/maestro-flow)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-≥18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](README.md)&nbsp;&nbsp;|&nbsp;&nbsp;[简体中文](README.zh-CN.md)
 
 </div>
 
----
+<br/>
+
+> 大多数 AI 编程工具只能让一个 agent 做一件事。
+> Maestro-Flow 编排**多个 agent 横跨整个开发生命周期** — 从头脑风暴到部署上线 — 通过自适应决策引擎、自增强知识图谱和实时可视化仪表盘。
+
+<br/>
+
+## 两大支柱
+
+Maestro-Flow 建立在两个相互增强的系统之上：
+
+```
+                         ┌─────────────────────────────────────┐
+                         │         Maestro-Flow                │
+                         │                                     │
+          ┌──────────────┴──────────────┐  ┌──────────────────┴───────────────┐
+          │      工作流编排              │  │         知识系统                  │
+          │                             │  │                                  │
+          │  意图路由                    │  │  MaestroGraph (SQLite)            │
+          │    └─ 40+ 链类型            │  │    └─ 代码 + 知识统一存储        │
+          │  Ralph 决策引擎             │  │  Spec 注入 (Hooks)               │
+          │    └─ 11 状态 FSM           │  │    └─ 自动注入 agent 提示词      │
+          │  质量管线                    │  │  Wiki + BM25 搜索               │
+          │    └─ verify → review → test│  │    └─ 反向链接 + 健康评分        │
+          │  多智能体调度                │  │  学习循环                        │
+          │    └─ Claude, Gemini, Codex │  │    └─ 复盘 → 持久化 → 注入      │
+          │                             │  │                                  │
+          └─────────────┬───────────────┘  └──────────────────┬───────────────┘
+                        │          ▲              │            ▲
+                        │          │  知识注入    │            │
+                        │          └──────────────┘            │
+                        │     执行结果                          │
+                        └──────────────────────────────────────┘
+```
 
-Maestro-Flow 是一个面向 Claude Code、Codex、Gemini 等多智能体的工作流编排框架。你只需描述意图，Maestro-Flow 自动路由到最优命令链，驱动多个 AI 智能体并行执行，通过自适应决策节点、实时仪表盘和知识图谱形成完整的项目交付闭环。
+**工作流产生知识，知识改善未来的工作流。** Agent 从每次会话中学习，将发现持久化为 spec 和 knowhow，未来的 agent 通过 hook 注入自动获取这些上下文 — 形成自增强循环。
 
 ---
 
@@ -28,19 +64,23 @@ npm install -g maestro-flow
 maestro install
 ```
 
-**前置条件**：Node.js >= 18，Claude Code CLI。可选：Codex CLI、Gemini CLI 用于多智能体工作流。
+**前置条件**：Node.js ≥ 18，Claude Code CLI。可选：Codex CLI、Gemini CLI 用于多智能体工作流。
+
+`maestro install` 提供交互式组件选择器 — 可选择安装哪些资产（命令、Hook、MCP、Agent）。使用 `maestro workspace link` 跨多个项目共享知识（spec、knowhow、domain）。
 
 ---
 
 ## 快速开始
 
-**`/maestro-ralph`** 是主推入口 — 闭环生命周期引擎，自动读取项目状态、推断当前位置、构建自适应命令链并驱动执行：
+### Ralph 引擎
+
+**`/maestro-ralph`** 是主推入口 — 闭环生命周期引擎，自动读取项目状态，推断你在开发生命周期中的位置，构建自适应命令链：
 
 ```bash
 /maestro-ralph "实现基于 OAuth2 的用户认证，带 refresh token"
 ```
 
-Ralph 自动判断你在生命周期中的位置（brainstorm → blueprint → analyze → roadmap → plan → execute → verify → review → test → milestone-complete）并构建相应命令链。上游起源命令（brainstorm、blueprint）和 roadmap 均为可选 — Ralph 根据项目状态和范围自动跳过。关键检查点的 decision 节点根据实际执行结果，动态插入 debug → fix → retry 循环。
+Ralph 自动判断你在哪个阶段（brainstorm → plan → execute → verify → review → test → milestone），构建相应命令链。关键检查点的 decision 节点根据实际结果，动态插入 debug → fix → retry 循环。
 
 ```bash
 /maestro-ralph status              # 查看会话进度
@@ -54,92 +94,185 @@ Ralph 自动判断你在生命周期中的位置（brainstorm → blueprint →
 |------|---------|
 | `/maestro "..."` | 描述意图，AI 自动路由最优命令链 |
 | `/maestro-quick` | 快速修复、小功能（analyze → plan → execute） |
-| `/maestro-*` | 逐步执行：init、brainstorm、blueprint、analyze、roadmap、plan、execute、verify |
+| `/maestro-*` | 逐步执行：brainstorm、blueprint、analyze、plan、execute、verify |
+
+### Odyssey — 长周期迭代循环
+
+Odyssey 命令运行扩展的自校正循环，组合考古式分析、诊断、修复、验证和知识持久化，直到满足验收标准：
+
+| 命令 | 聚焦场景 |
+|------|---------|
+| `odyssey-debug` | 调试循环 — 考古分析、诊断、修复、确认、泛化 |
+| `odyssey-planex` | 需求驱动循环 — 计划、执行、严格验证、修复迭代 |
+| `odyssey-improve` | 代码库改进 — 多维审计、定向修复、验证 |
+| `odyssey-review-test-fix` | 深度审查 + 修复 — 多维审查、定向修复、泛化 |
+| `odyssey-ui` | UI 优化 — 视觉巡检、审计、发散探索、修复 |
 
 ---
 
-## 核心特性
+## 工作流编排
 
-### 1. 自适应生命周期引擎（`maestro-ralph`）
+### 自适应生命周期引擎
 
-读取项目状态 → 推断生命周期位置 → 构建含 decision 节点的命令链。每个检查点读取实际执行结果，决定继续还是插入 debug → fix → retry 循环。链在运行中动态增长/收缩。
+Ralph 是一个 11 状态有限状态机，**只做决策，不做执行**。它读取项目状态，推断生命周期位置，构建带质量门的命令链，将执行交给 `maestro-ralph-execute`。在每个 decision 节点（`◆`），Ralph 评估实际结果并决定：继续前进，还是插入 debug → fix → retry 循环。
 
 ```
 brainstorm → blueprint(可选) → init → analyze(宏观) → roadmap(可选) → analyze(微观) → plan → execute → verify
-                                                                                                       ◆ post-verify
-                                              business-test
-                                              ◆ post-business-test
-                                              review
-                                              ◆ post-review
-                                              test
-                                              ◆ post-test
-                                              milestone-audit → milestone-complete
-                                              ◆ post-milestone → 下一里程碑
+                                                                                                 ◆ decision
+                                              review ─── ◆ ─── test ─── ◆ ─── milestone-audit → milestone-complete
+                                                                                                 ◆ → 下一里程碑
+```
+
+**三种质量模式**控制质量深度：
+
+| 模式 | 管线 | 适用场景 |
+|------|------|---------|
+| `full` | verify → business-test → review → test-gen → test | 生产环境、安全关键代码 |
+| `standard` | verify → review → test | 默认，平衡质量 |
+| `quick` | verify → CLI-review | 原型开发、快速修复 |
+
+### 意图驱动路由
+
+你不需要编写 pipeline YAML。用自然语言描述意图，Maestro 将其分类到 **40+ 链类型**中，每种都是预组合的命令序列。同一意图在不同项目状态下产生不同的链：
+
+```bash
+/maestro "添加用户个人资料页"
+# → 新项目:     brainstorm → blueprint → analyze → plan → execute → verify
+# → 已有项目:    analyze → plan → execute → verify
+# → 快速修复:    plan → execute → verify
 ```
 
-三种质量模式：`full`（verify + business-test + review + test）、`standard`（verify + review + test）、`quick`（verify + CLI-review）。
+### 分层命令拓扑
 
-### 2. 完整质量管线
+命令按四层组织：
 
-每个 `◆` decision 节点是一个质量门禁，根据实际结果动态调整链路：
+| 层级 | 用途 | 命令 |
+|------|------|------|
+| **起源层** | 发散创意，收敛方向 | brainstorm、blueprint |
+| **理解层** | 探索范围（宏观）+ 深入研究（微观） | analyze（双模式） |
+| **编排层** | 组织为里程碑和阶段 | roadmap |
+| **执行层** | 计划、实现、验证 | plan、execute、verify、review、test |
 
-1. **verify** — 目标回溯验证：检查所有 plan 需求是否实现、架构约束校验、反模式扫描、Nyquist 测试覆盖率
-2. **business-test** — PRD 前向业务测试：需求追溯、fixture 生成、验收标准多层执行
-3. **review** — 多维度代码审查：正确性、可读性、性能、安全、测试、架构
-4. **test-gen** — 覆盖率缺口分析 + 自动测试生成（TDD/E2E 分类，L0-L3 渐进层）
-5. **test** — 交互式 UAT：探索性测试，会话持久化，缺口闭环
+6 条规范路径（A–F）覆盖从全新项目到单行修复的所有场景。
 
-### 3. 分层命令拓扑
+### 多智能体调度
 
-命令按四层组织：**上游起源层**（brainstorm 发散、blueprint 收敛）、**理解层**（analyze 双层模式：宏观探索影响面 + 微观 Phase 级深入）、**编排层**（roadmap — 可选，纯 Milestone > Phase 分解）、**执行层**（plan → execute → verify）。6 条规范路径（Path A–F）覆盖从全新项目到小修复的所有场景。50 个斜杠命令覆盖 7 大类别，所有产物存放于 `.workflow/scratch/`，由 `state.json` 追踪。
+Maestro 通过四种可组合的编排模式协调 **Claude Code、Codex、Gemini、Qwen、OpenCode**：
 
-### 4. Issue 闭环
+| 模式 | 工作方式 |
+|------|---------|
+| **Delegate** | 通过 `maestro delegate` 派发到任意 CLI 工具，SQLite 任务中介管理异步执行，支持消息注入和链式调用 |
+| **Team** | 协调器-工人架构 — 协调器生成角色规格，并行派生 `team-worker` agent，由常驻质量观察者监督 |
+| **Wave** | 任务拓扑排序为依赖波次，波次内独立任务并行执行 |
+| **Swarm** | ACO 蚁群驱动的多智能体探索，信息素引导收敛 |
+
+这些模式可以**组合**：团队协调器可将子任务委托给不同的 LLM 后端，波次执行并行化独立工作，仪表盘提供实时监控 — 所有模式共享中介和消息总线作为协调原语。
+
+---
 
-Issue 是自修复管线：discover → analyze → plan → execute → close。质量命令自动为发现的问题创建 Issue，修复代码回流到阶段管线。
+## 知识系统
 
-### 5. 可视化仪表盘
+### 知识图谱（MaestroGraph）
 
-实时看板 `http://127.0.0.1:3001`，React 19 + Tailwind CSS 4 + WebSocket 实时更新。Kanban 看板、甘特时间线、可排序表格、指挥中心。在 Issue 卡片上选择智能体，一键派发。
+**MaestroGraph** 是统一的代码索引引擎，替代了原有的 CodeGraph 外部依赖。基于 `web-tree-sitter` 实现 AST 级提取，将**代码结构**（函数、类、调用链）和**项目知识**（spec、knowhow、领域术语、issue）存储在同一个 SQLite 图数据库中，配备双 FTS5 索引。
 
 ```bash
-maestro serve                  # → http://127.0.0.1:3001
-maestro view                   # 终端 TUI 替代方案
-maestro command-help           # 在浏览器中打开交互式命令参考（别名: ch）
+maestro kg search <symbol>        # 查找节点
+maestro kg context <node>         # 获取上下文
+maestro kg callers <function>     # 追溯调用链
+maestro kg callees <function>     # 追溯依赖
+```
+
+### Spec 注入
+
+项目规则（编码规范、架构约束、质量标准）以带关键词标签的 `<spec-entry>` 格式存储。**Hook 自动将相关 spec 注入每个 agent 的提示词** — agent 无需手动加载即可获得项目专属规则。
+
+### 自增强学习循环
+
 ```
+Agent 执行任务
+    → 发现模式/陷阱/决策
+    → 持久化为 spec 条目或 knowhow 文档
+    → Hook 系统索引新知识
+    → 未来 agent 通过提示词注入自动获取
+    → 更好的执行 → 更多发现 → ...
+```
+
+四个学习工具驱动这个循环：`learn-retro`（复盘）、`learn-follow`（模式学习）、`learn-decompose`（架构拆解）、`learn-investigate`（深度探究）。
 
-### 6. 多智能体引擎
+### 领域知识
 
-并行协调 Claude Code、Codex、Gemini、Qwen、OpenCode。波次执行 — 独立任务并行，依赖任务等待前置完成。
+语义词汇表层，定义项目中**事物的含义**。Domain 术语（`maestro domain`）标准化命名、映射概念关系，并作为 MaestroGraph 的知识源之一 — 桥接代码级符号与业务级概念。
 
-### 7. 智能知识库
+### Wiki 与搜索
 
-Wiki 知识图谱支持 BM25 搜索、反向链接遍历、健康评分。学习工具箱（retro、follow、decompose、investigate、second-opinion）汇入统一的 `lessons.jsonl` 知识库。
+WikiIndexer 遍历 `.workflow/` 目录，解析 frontmatter，构建反向链接图，并创建 **BM25 倒排索引**用于全文搜索 — 覆盖所有项目知识：spec、knowhow、issue 以及 KG 节点的虚拟条目。
 
 ---
 
-## 命令与 Agent
+## Issue 闭环
 
-| 类别 | 数量 | 前缀 | 用途 |
-|------|------|------|------|
-| **核心工作流** | 19 | `maestro-*` | 全生命周期 — ralph、init、brainstorm、blueprint、analyze、roadmap、plan、execute、verify、milestones、overlays |
-| **管理** | 12 | `manage-*` | Issue 生命周期、代码库文档、知识捕获、记忆管理、状态 |
-| **质量** | 9 | `quality-*` | review、test、debug、test-gen、integration-test、business-test、refactor、sync |
-| **学习** | 5 | `learn-*` | 复盘、跟读、模式拆解、探究、多视角 |
-| **规范** | 3 | `spec-*` | setup、add、load |
-| **知识图谱** | 2 | `wiki-*` | 连接发现、知识摘要 |
+Issue 不仅是工单，更是自修复管线：
 
-`.claude/agents/` 下 21 个专业化 Agent 定义，Claude Code 按需加载。
+```
+discover → analyze → plan → execute → close
+    ▲                                    │
+    └────── 质量命令自动创建 ──────────────┘
+```
+
+质量命令（review、test、verify）自动为发现的问题创建 Issue，修复代码回流到阶段管线。
 
 ---
 
-## 架构
+## 可视化仪表盘
+
+实时仪表盘 `http://127.0.0.1:3001` — Kanban 看板、甘特时间线、可排序表格、指挥中心。在 Issue 卡片上选择智能体，一键派发。
+
+```bash
+maestro serve                  # 启动 Web 仪表盘
+maestro view                   # 终端 TUI 替代方案
+maestro command-help           # 交互式命令参考（别名: ch）
+```
+
+基于 React 19、Zustand、Tailwind CSS 4、Framer Motion、Hono、WebSocket 构建。
+
+---
+
+## 项目概览
+
+| 指标 | 数量 |
+|------|------|
+| 源文件 (TypeScript) | 454 |
+| 代码行数 | ~111,000 |
+| 斜杠命令 | 64 |
+| 工作流定义 | 115 |
+| 技能包 | 45 |
+| Agent 定义 | 23 |
+| CLI 命令 | 32 |
+| 模板 | 92 |
+| 指南（双语） | 67 |
+
+### 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| CLI | Commander.js, TypeScript, ESM |
+| MCP | @modelcontextprotocol/sdk (stdio) |
+| 知识图谱 | better-sqlite3, Drizzle ORM, web-tree-sitter |
+| 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
+| 后端 | Hono, WebSocket, SSE |
+| 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
+| 构建 | Vite 6, TypeScript 5.7, Vitest |
+
+### 架构
 
 ```
 maestro/
 ├── bin/                     # CLI 入口
 ├── src/                     # 核心 CLI (Commander.js + MCP SDK)
-│   ├── commands/            # 11 个 CLI 命令 (serve, run, cli, ext, tool, ...)
+│   ├── commands/            # 32 个 CLI 命令
 │   ├── mcp/                 # MCP 服务器 (stdio 传输)
+│   ├── graph/               # 知识图谱 (SQLite + tree-sitter)
 │   └── core/                # 工具注册、扩展加载器
 ├── dashboard/               # 实时 Web 仪表盘
 │   └── src/
@@ -147,38 +280,46 @@ maestro/
 │       ├── server/          # Hono API + WebSocket + SSE
 │       └── shared/          # 共享类型
 ├── .claude/
-│   ├── commands/            # 50 个斜杠命令 (.md)
-│   └── agents/              # 21 个 Agent 定义 (.md)
-├── workflows/               # 45 个工作流实现 (.md)
-├── templates/               # JSON 模板 (task, plan, issue, ...)
+│   ├── commands/            # 64 个斜杠命令 (.md)
+│   ├── agents/              # 23 个 Agent 定义 (.md)
+│   └── skills/              # 45 个技能包
+├── workflows/               # 115 个工作流定义 (.md)
+├── templates/               # 92 个 JSON 模板
 └── extensions/              # 插件系统
 ```
 
-| 层级 | 技术 |
-|------|------|
-| CLI | Commander.js, TypeScript, ESM |
-| MCP | @modelcontextprotocol/sdk (stdio) |
-| 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
-| 后端 | Hono, WebSocket, SSE |
-| 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
-| 构建 | Vite 6, TypeScript 5.7, Vitest |
-
 ---
 
 ## 文档
 
-- **[Maestro Ralph 指南](guide/maestro-ralph-guide.md)** — 自适应生命周期引擎：位置推断、decision 节点、质量模式、重试升级
-- **[命令使用指南](guide/command-usage-guide.md)** — 全部 53 个命令，含工作流图表、管线衔接、Issue 闭环
-- **[命令参考 (HTML)](guide/command-usage-guide.html)** — 交互式 HTML 版本，支持搜索、卡片网格、工作流示例（`maestro command-help` 打开）
-- **[CLI 命令参考](guide/cli-commands-guide.en.md)** — 全部 21 个终端命令：install、delegate、coordinate、wiki、hooks、overlay、collab
-- **[Spec 系统指南](guide/spec-system-guide.md)** — `<spec-entry>` 格式、keyword 加载、验证 Hook、session dedup 注入
-- **[Delegate 异步执行指南](guide/delegate-async-guide.md)** — 异步任务委派：CLI & MCP 用法、消息注入、链式调用
-- **[Overlay 系统指南](guide/overlay-guide.md)** — 非侵入式命令扩展：格式、section 注入、bundle 打包/导入
-- **[Hook 系统指南](guide/hooks-guide.md)** — Hook 系统架构、11 个 Hook、Spec 注入、上下文预算
-- **[Worktree 并行开发指南](guide/worktree-guide.md)** — 里程碑级 worktree 并行：fork、sync、merge、dashboard 集成
-- **[Collab 协作 — 使用指南](guide/team-lite-guide.md)** — 2-8 人小团队协作
-- **[Collab 协作 — 设计文档](guide/team-lite-design.md)** — 架构、数据模型、命名空间边界
-- **[MCP 工具参考](guide/mcp-tools-guide.en.md)** — 全部 9 个 MCP 端点工具
+**快速入门**
+- **[快速开始指南](guide/quick-start-guide.md)** — 安装、第一个工作流、核心概念
+- **[安装指南](guide/install-guide.md)** — 分步安装、组件选择、工作空间配置
+- **[Maestro Ralph 指南](guide/maestro-ralph-guide.md)** — 自适应生命周期引擎、decision 节点、质量模式
+
+**工作流**
+- **[命令使用指南](guide/command-usage-guide.md)** — 全部 64 个命令，含工作流图表和管线衔接
+- **[CLI 命令参考](guide/cli-commands-guide.md)** — 全部 32 个终端命令
+- **[工作流结构指南](guide/workflow-structure-guide.md)** — 命令拓扑、链组合
+- **[质量管线指南](guide/quality-pipeline-guide.md)** — verify、review、test 管线
+- **[Maestro 协调器指南](guide/maestro-coordinator-guide.md)** — 多智能体协调模式
+
+**知识系统**
+- **[知识管理指南](guide/knowledge-management-guide.md)** — KG、spec、knowhow、wiki
+- **[搜索系统指南](guide/search-system-guide.md)** — 统一 BM25F 搜索、MaestroGraph 集成、类型过滤
+- **[MaestroGraph 设计文档](guide/plan-maestrograph.md)** — 统一 KG 引擎设计、CodeGraph 替代、tree-sitter 集成
+- **[领域知识设计文档](guide/plan-domain-knowledge.md)** — 语义词汇表、术语关系、概念层
+- **[Spec 系统指南](guide/spec-system-guide.md)** — spec 条目、关键词加载、验证 Hook
+- **[Hook 系统指南](guide/hooks-guide.md)** — 17 个 Hook、Spec 注入、上下文预算
+- **[学习工具指南](guide/learn-tools-guide.md)** — 复盘、跟读、拆解、探究
+
+**进阶**
+- **[Delegate 异步执行指南](guide/delegate-async-guide.md)** — 多 CLI 委派、消息注入、链式调用
+- **[Overlay 系统指南](guide/overlay-guide.md)** — 非侵入式命令扩展
+- **[Worktree 并行开发指南](guide/worktree-guide.md)** — 里程碑级并行开发
+- **[跨工作空间指南](guide/workspace-guide.md)** — 跨项目知识共享、link/unlink
+- **[MCP 工具参考](guide/mcp-tools-guide.md)** — 全部 9 个 MCP 端点工具
+- **[Collab 协作指南](guide/team-lite-guide.md)** — 2-8 人团队协作
 
 ---
 
@@ -186,6 +327,7 @@ maestro/
 
 - **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** by TACHES — 规格驱动开发模型和上下文工程理念。
 - **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — 前身项目，开创了多 CLI 编排和 skill 路由工作流。
+- **[Impeccable](https://github.com/pbakaus/impeccable)** by [@pbakaus](https://github.com/pbakaus) — UI 设计技能，集成为 `maestro-impeccable`。基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可。
 
 ## 贡献者
 

package/dashboard/dist-server/dashboard/src/server/wiki/embedding.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Embedding-based semantic search using @huggingface/transformers (ONNX backend).
+ *
+ * Features:
+ * - Smart device detection: auto-benchmarks CPU vs GPU (DirectML), picks fastest
+ * - Batch inference: processes documents in configurable batch sizes (4-5x faster)
+ * - Incremental indexing: only re-embeds new or changed documents
+ * - Graceful degradation: falls back to pure BM25 when transformers is unavailable
+ */
+export interface EmbeddingIndex {
+    modelId: string;
+    dimension: number;
+    docIds: string[];
+    vectors: Float32Array[];
+    contentHashes?: string[];
+    builtAt: number;
+    deviceUsed?: string;
+    buildTimeMs?: number;
+}
+export interface VectorSearchResult {
+    docId: string;
+    score: number;
+}
+export type DeviceType = 'cpu' | 'gpu';
+export type DtypeType = 'fp32' | 'fp16' | 'q8' | 'q4';
+export interface DeviceConfig {
+    device: DeviceType;
+    dtype: DtypeType;
+    batchSize: number;
+}
+export interface RankedResult {
+    docId: string;
+    score: number;
+}
+export interface RRFSignal {
+    name: string;
+    weight: number;
+    results: RankedResult[];
+}
+export declare function mergeRRFSignals(signals: RRFSignal[], limit: number, k?: number): RankedResult[];
+export declare function mergeRRF(bm25Results: RankedResult[], vectorResults: RankedResult[], limit: number, k?: number, bm25Weight?: number, vectorWeight?: number): RankedResult[];
+/**
+ * Hybrid fusion: RRF for ordering stability + BM25 magnitude for score discrimination.
+ * finalScore = alpha * rrfNorm + (1-alpha) * bm25Norm
+ */
+export declare function mergeHybrid(bm25Results: RankedResult[], vectorResults: RankedResult[], limit: number, options?: {
+    k?: number;
+    alpha?: number;
+    bm25Weight?: number;
+    vectorWeight?: number;
+}): RankedResult[];
+interface BackendInfo {
+    name: string;
+    bundled: boolean;
+}
+export declare function detectDevice(): Promise<DeviceConfig>;
+export declare function getDeviceSummary(): string;
+export interface HardwareInfo {
+    backends: BackendInfo[];
+    gpuAvailable: boolean;
+    selectedDevice: DeviceConfig;
+    reason: string;
+}
+export declare function getHardwareInfo(): Promise<HardwareInfo>;
+export declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+export declare function isAvailable(): Promise<boolean>;
+export declare function getUnavailableReason(): string | null;
+export declare function embedTexts(texts: string[]): Promise<Float32Array[]>;
+export declare function embedQuery(query: string): Promise<Float32Array>;
+export declare function vectorSearch(queryVector: Float32Array, index: EmbeddingIndex, limit: number): VectorSearchResult[];
+export declare function saveEmbeddingIndex(index: EmbeddingIndex, dir: string): void;
+export declare function loadEmbeddingIndex(dir: string): EmbeddingIndex | null;
+export interface DocForEmbedding {
+    id: string;
+    title: string;
+    summary: string;
+    tags: string[];
+    body?: string;
+}
+export declare function hashDocContent(d: DocForEmbedding): string;
+export declare function buildEmbeddingIndex(docs: DocForEmbedding[], existingIndex?: EmbeddingIndex | null): Promise<EmbeddingIndex>;
+export {};