# Halcyon

**Repository Path**: iuuxx/halcyon

## Basic Information

- **Project Name**: Halcyon
- **Description**: Halcyon（静澜）是面向 OpenCode 的 HALCON 知识库插件，以内嵌 SQLite 知识库的形式为 LLM 提供 HALCON 官方文档的精准检索与上下文注入能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 离线运行, 双路检索, 多库支持, 查询扩展, LLM重排

## README

# Halcyon — HALCON 知识库插件

Halcyon（静澜）是面向 OpenCode 的 HALCON 知识库插件，以内嵌 SQLite 知识库的形式为 LLM 提供 HALCON 官方文档的精准检索与上下文注入能力。

## 特性

- **离线运行**：嵌入模型、sqlite-vec 扩展、知识库全部内嵌，无任何网络请求。
- **双路检索**：FTS5（BM25）全文检索 + sqlite-vec 向量余弦检索，加权融合。
- **多库支持**：手册（manual）、博客（blog）、代码（code）三类知识库独立加载。
- **查询扩展**：调用 LLM 将用户问题改写为 3~5 个检索关键词。
- **LLM 重排**：从候选片段中选出最相关的 3 个并直接给出答案。
- **降级策略**：任一数据库损坏、LLM 超时、模型缺失均不影响整体可用性。

## 安装

### 方式一：从 ZIP 离线包

1. 解压 `halcyon-plugin-win-x64.zip` 到本地目录。
2. 在 OpenCode 的 `opencode.json` 中加载插件：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["./halcyon-plugin-win-x64/plugin.js"]
}
```

3. 重启 OpenCode。加载成功后，工具列表中会出现 `query_halcon_kb`。

### 方式二：项目内源码开发

```bash
cd plugin
npm install
npm run build     # 产出 dist/
```

将 `plugin/config.json` 中 `databases` 路径指向你的 `.sqlite` 文件，`embedding.modelPath` 指向模型目录。

## 配置

`config.json` 关键字段：

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `databases.manual.enabled` | `true` | 是否加载手册库 |
| `databases.blog.enabled` | `false` | 是否加载博客库 |
| `databases.code.enabled` | `false` | 是否加载代码库 |
| `search.topKPerDb` | `30` | 每个库每种检索路径召回数 |
| `search.maxCandidates` | `80` | 合并后候选池上限 |
| `search.ftsWeight` / `vecWeight` | `0.3` / `0.7` | FTS 与向量融合权重 |
| `search.enableQueryExpansion` | `true` | 是否启用 LLM 查询扩展 |
| `search.enableRerank` | `true` | 是否启用 LLM 重排 |
| `embedding.modelPath` | `../models/bge-small-en-v1.5` | 嵌入模型目录 |

## 数据库替换

- 将新的 `.sqlite` 文件覆盖 `data/<type>/halcyon_<type>.sqlite` 后重启插件即可。
- 支持仅启用部分数据库（`enabled: false`），被禁用库的数据不会出现在结果中。

## 使用

在 OpenCode 中向 LLM 提问 HALCON 相关问题，LLM 会自动调用 `query_halcon_kb` 工具检索知识库并作答。也可以直接询问"用 find_shape_model 做形状匹配"等。

## 常见问题

- **插件未出现在工具列表**：确认 `plugin.js` 路径正确、Node 版本 ≥ 18.17.0。
- **向量检索不可用**：检查 `models/bge-small-en-v1.5/onnx/model.onnx` 是否存在；缺失时插件自动降级为仅 FTS5 检索。
- **数据库损坏**：删除损坏的 `.sqlite` 文件，其余库不受影响。

## 构建数据库

参见 [BUILD.md](BUILD.md)（构建器用法与模型转换步骤）。