Aurora Grimoire

奥罗拉Grimoire

用于Aurora OS文档RAG的CLI+MCP服务器。

该项目涵盖了整个管道：

• 获取HTML文档；
• 标准化为Markdown；
• 块内容；
• 生成嵌入；
• 将矢量上传到Qdrant；
• 搜索来源(cli search_docs);
• 通过MCP工具公开搜索 search_docs.

特性

• 通过CLI实现完全离线友好的RAG管道。
• 混合检索：密集（Qdrant）+BM25。
• 文档版本过滤(--doc-version).
• 知识充足阈值(--knowledge-threshold).
• 通过捆绑在机器之间传输工件。
• MCP服务器(stdio 以及HTTP传输）。

需求

• Rust/Cargo（通过安装CLI cargo install --path .).
• 对于 rag embed：Ollama用嵌入模型。
• 对于 rag deploy 搜索：Qdrant。

对于本地开发堆栈：

• rag dev up 启动Docker服务（Qdrant+Ollama）。

安装

安装CLI二进制文件：

cargo install --path .

检查安装：

aurora-grimoire --version

如果找不到命令，请确保货舱在 PATH:

export PATH="$HOME/.cargo/bin:$PATH"

配置是必需的

除以下命令外的所有命令 rag config init 需要现有 config.toml.

创建配置：

aurora-grimoire rag config init

覆盖现有配置：

aurora-grimoire rag config init --force

自定义配置路径：

AURORA_GRIMOIRE_CONFIG=/path/to/config.toml aurora-grimoire rag config init

配置模板： config.example.toml

快速入门（端到端）

1. 初始化配置：

aurora-grimoire rag config init

1. 启动本地堆栈：

aurora-grimoire rag dev up --build --gpu --verbose

1. 获取并准备数据：

aurora-grimoire rag fetch-web -v
aurora-grimoire rag struct -v
aurora-grimoire rag chunk -v

1. 生成嵌入并部署到Qdrant：

aurora-grimoire rag embed -v
aurora-grimoire rag deploy -v --recreate

1. 验证搜索：

aurora-grimoire cli search_docs "how to build project with mb2" --doc-version 5.2.0 --json

将工件转移给另一个用户

rag bundle create 总是创建一个 dual 捆绑(chunks + vectors).

创建捆绑包：

aurora-grimoire rag bundle create --out ~/.aurora-grimoire/bundles/aurora-dual.tar.zst

检查管束：

aurora-grimoire rag bundle inspect --file ~/.aurora-grimoire/bundles/aurora-dual.tar.zst

在另一台机器上：

aurora-grimoire rag config init
aurora-grimoire rag bundle extract --file /path/aurora-dual.tar.zst
aurora-grimoire rag deploy --input ~/.aurora-grimoire/vectors_data --recreate -v

主控程序

启动MCP服务器：

aurora-grimoire mcp start --stdio

或HTTP：

aurora-grimoire mcp start --http --host 127.0.0.1 --port 8080

MCP烟雾测试：

aurora-grimoire mcp smoke --doc-version 5.2.0 --query "how to build project with mb2"

MCP公开了一个工具：

• search_docs

代理集成

确保 aurora-grimoire 已安装并可用于 PATH. 如果你需要绝对二进制路径：

AURORA_GRIMOIRE_BIN="$(command -v aurora-grimoire)"

在下面的示例中使用该绝对路径。

克劳德代码

标准运输：

claude mcp add aurora-grimoire -- $AURORA_GRIMOIRE_BIN mcp start --stdio

HTTP传输：

aurora-grimoire mcp start --http --host 127.0.0.1 --port 8080
claude mcp add --transport http aurora-grimoire-http http://127.0.0.1:8080/mcp

法典

标准运输：

codex mcp add aurora-grimoire -- $AURORA_GRIMOIRE_BIN mcp start --stdio

HTTP传输：

aurora-grimoire mcp start --http --host 127.0.0.1 --port 8080
codex mcp add aurora-grimoire-http --url http://127.0.0.1:8080/mcp

检查：

codex mcp list

OpenCode

OpenCode通过交互式向导添加MCP服务器：

opencode mcp add

对于本地模式设置：

• name: aurora-grimoire
• transport/type: local/stdio
• command: $AURORA_GRIMOIRE_BIN
• args: mcp start --stdio

对于远程模式设置：

• transport/type: remote/http
• url: http://127.0.0.1:8080/mcp

检查：

opencode mcp list

其他MCP客户端

如果您的客户端支持stdio mcpServers 配置，使用：

{
  "mcpServers": {
    "aurora-grimoire": {
      "command": "$AURORA_GRIMOIRE_BIN",
      "args": ["mcp", "start", "--stdio"]
    }
  }
}

如果您的客户端支持流式HTTP，请启动服务器：

aurora-grimoire mcp start --http --host 127.0.0.1 --port 8080

并连接URL http://127.0.0.1:8080/mcp.

安装代理技能/命令模板

CLI包括安装程序命令：

aurora-grimoire agents install --runtime all --scope global --verbose

旗帜：

• --runtime （默认值： all)
• --scope （默认值： local)
• `--config-dir

` （仅限单次运行时）

• --force （覆盖现有文件）

已安装目标：

• 克劳德代码： commands/aurora/search-docs.md （援引： /aurora:search-docs ...)
• OpenCode： command/aurora-search-docs.md （援引： /aurora-search-docs ...)
• 食品法典： skills/aurora-search-docs/SKILL.md （援引： $aurora-search-docs ...)

主要命令

aurora-grimoire
├─ agents
│  └─ install
├─ rag
│  ├─ config init
│  ├─ fetch-web
│  ├─ struct
│  ├─ chunk
│  ├─ embed
│  ├─ deploy
│  ├─ bundle (create/inspect/extract)
│  ├─ dev (up/down/status/logs)
│  ├─ test-e2e
│  └─ clear
├─ cli
│  └─ search_docs
└─ mcp
   ├─ start
   └─ smoke

带有标志的完整和当前命令树： docs/architecture.md

有用的命令

检查开发堆栈状态：

aurora-grimoire rag dev status

日志：

aurora-grimoire rag dev logs -f

清除伪影：

aurora-grimoire rag clear --all