forked from fangtianchen/algonotes_rag
503 lines
11 KiB
Markdown
503 lines
11 KiB
Markdown
# 🔍 查询命令 (`query`)
|
||
|
||
> [返回目录](README.md)
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
提供笔记查询功能，支持原文查看、元数据查询、语义搜索和 RAG 问答。
|
||
|
||
## 子命令总览
|
||
|
||
| 子命令 | 操作层 | 说明 |
|
||
| --- | --- | --- |
|
||
| `show` | 文件层 | 查看笔记原文 |
|
||
| `list` | 关系层 | 列出笔记列表 |
|
||
| `info` | 关系层 | 查看笔记详情 |
|
||
| `search` | 向量层 | 语义搜索 |
|
||
| `export` | 文件层 | 导出笔记（Obsidian） |
|
||
| `ask` | RAG 层 | RAG 问答 |
|
||
|
||
---
|
||
|
||
## 文件层
|
||
|
||
### 查看笔记原文 (`show`)
|
||
|
||
#### show: 功能
|
||
|
||
查看指定笔记的完整原始内容（Markdown 文本）。
|
||
|
||
#### show: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `filename` | - | 笔记文件名（位置参数） | 必填 |
|
||
| `--lines` | - | 只显示前 N 行 | 全部 |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout（使用时须指定文件路径） |
|
||
|
||
#### show: 使用示例
|
||
|
||
```bash
|
||
# 查看笔记原文
|
||
algonotes query show fenwick.md
|
||
|
||
# 只显示前 50 行
|
||
algonotes query show segment-tree.md --lines 50
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query show dijkstra.md --json output.json
|
||
```
|
||
|
||
#### show: 输出示例
|
||
|
||
```text
|
||
# 树状数组 (Fenwick Tree)
|
||
|
||
## 模板
|
||
|
||
int tree[N];
|
||
void add(int x, int val) {
|
||
for (; x <= n; x += x & -x) tree[x] += val;
|
||
}
|
||
int query(int x) {
|
||
int res = 0;
|
||
for (; x > 0; x -= x & -x) res += tree[x];
|
||
return res;
|
||
}
|
||
|
||
## 应用
|
||
|
||
### 逆序对
|
||
...
|
||
```
|
||
|
||
#### show: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/store/file_store.py` | 文件读取 |
|
||
| `src/store/sql_store.py` | 笔记查找 |
|
||
|
||
#### show: 注意事项
|
||
|
||
1. **笔记不存在**：输出提示信息并退出
|
||
2. **行数限制**：`--lines` 同时限制终端输出和 JSON 输出的行数，`line_count` 为截断后的行数
|
||
|
||
#### show: JSON 输出格式
|
||
|
||
```json
|
||
{
|
||
"filename": "fenwick.md",
|
||
"content": "# 树状数组 (Fenwick Tree)\n\n## 模板\n\n```cpp\n...",
|
||
"line_count": 120
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 关系层
|
||
|
||
### 列出笔记 (`list`)
|
||
|
||
#### list: 功能
|
||
|
||
列出已导入的笔记，支持按标签筛选。
|
||
|
||
#### list: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `--tag` | - | 按标签筛选 | 无 |
|
||
| `--verbose` | `-v` | 显示详细信息 | `False` |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout（使用时须指定文件路径） |
|
||
|
||
#### list: 使用示例
|
||
|
||
```bash
|
||
# 列出所有笔记
|
||
algonotes query list
|
||
|
||
# 按标签筛选
|
||
algonotes query list --tag 树状数组
|
||
|
||
# 显示详细信息
|
||
algonotes query list -v
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query list --json notes.json
|
||
```
|
||
|
||
#### list: 输出示例
|
||
|
||
```text
|
||
笔记列表
|
||
┏━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
|
||
┃ ID ┃ 文件名 ┃ 标签 ┃ 入库时间 ┃
|
||
┡━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
|
||
│ 1 │ fenwick.md │ 树状数组,模板 │ 2026-06-16 │
|
||
│ 2 │ segment-tree.md │ 线段树,数据结构 │ 2026-06-15 │
|
||
│ 3 │ dijkstra.md │ 图论,最短路 │ 2026-06-14 │
|
||
└────┴────────────────────────┴──────────────────┴────────────┘
|
||
```
|
||
|
||
#### list: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/store/sql_store.py` | 笔记列表查询、标签筛选 |
|
||
|
||
#### list: 注意事项
|
||
|
||
1. **无笔记时**：返回空列表，不报错
|
||
|
||
#### list: JSON 输出格式
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"filename": "fenwick.md",
|
||
"filepath": "data/files/fenwick.md",
|
||
"title": "树状数组",
|
||
"tags": "树状数组,模板",
|
||
"source_url": null,
|
||
"content_hash": "a1b2c3d4...",
|
||
"ingested_at": "2026-06-16 14:30:22",
|
||
"updated_at": null,
|
||
"chunk_count": 8,
|
||
"file_size": 4320
|
||
}
|
||
]
|
||
```
|
||
|
||
### 查看笔记详情 (`info`)
|
||
|
||
#### info: 功能
|
||
|
||
查看指定笔记的详细元数据。
|
||
|
||
#### info: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `filename` | - | 笔记文件名（位置参数） | 与 `--id` 二选一 |
|
||
| `--id` | - | 笔记 ID | 与 `filename` 二选一 |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout（使用时须指定文件路径） |
|
||
|
||
#### info: 使用示例
|
||
|
||
```bash
|
||
# 按文件名查看
|
||
algonotes query info fenwick.md
|
||
|
||
# 按 ID 查看
|
||
algonotes query info --id 1
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query info fenwick.md --json info.json
|
||
```
|
||
|
||
#### info: 输出示例
|
||
|
||
```text
|
||
笔记详情：
|
||
ID: 1
|
||
文件名: fenwick.md
|
||
路径: data/files/fenwick.md
|
||
标题: 树状数组
|
||
标签: 树状数组,模板
|
||
分块数: 8
|
||
文件大小: 4.2 KB
|
||
入库时间: 2026-06-16 14:30:22
|
||
```
|
||
|
||
#### info: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/store/sql_store.py` | 元数据查询 |
|
||
| `src/store/file_store.py` | 文件读取 |
|
||
|
||
#### info: 注意事项
|
||
|
||
1. **笔记不存在**：输出提示信息并退出
|
||
2. **参数互斥**：`filename` 和 `--id` 必须提供其一
|
||
|
||
#### info: JSON 输出格式
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"filename": "fenwick.md",
|
||
"filepath": "data/files/fenwick.md",
|
||
"title": "树状数组",
|
||
"tags": "树状数组,模板",
|
||
"source_url": null,
|
||
"content_hash": "a1b2c3d4...",
|
||
"ingested_at": "2026-06-16 14:30:22",
|
||
"updated_at": null,
|
||
"chunk_count": 8,
|
||
"file_size": 4320
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 向量层
|
||
|
||
### 语义搜索 (`search`)
|
||
|
||
#### search: 功能
|
||
|
||
仅执行语义检索，返回相关文档片段。
|
||
|
||
#### search: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `query` | - | 搜索关键词（位置参数） | 必填 |
|
||
| `--top-k` | - | 返回结果数量 | 5 |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout（使用时须指定文件路径） |
|
||
|
||
#### search: 使用示例
|
||
|
||
```bash
|
||
# 语义搜索
|
||
algonotes query search "动态规划优化"
|
||
|
||
# 限制返回数量
|
||
algonotes query search "图论" --top-k 3
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query search "树状数组" --json results.json
|
||
```
|
||
|
||
#### search: 输出示例
|
||
|
||
```text
|
||
找到 3 条相关结果：
|
||
|
||
[1] 来自: dp_optimization.md
|
||
内容: 斜率优化 DP 适用于形如 dp[i] = min(dp[j] + ...) 的转移方程...
|
||
|
||
[2] 来自: knapsack.md
|
||
内容: 01 背包可以用滚动数组优化空间复杂度...
|
||
```
|
||
|
||
#### search: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/store/vector_store.py` | 向量检索 |
|
||
|
||
#### search: 注意事项
|
||
|
||
1. **无匹配结果**：返回空列表，不报错
|
||
|
||
#### search: JSON 输出格式
|
||
|
||
```json
|
||
{
|
||
"query": "动态规划优化",
|
||
"results": [
|
||
{
|
||
"source": "dp_optimization.md",
|
||
"content": "斜率优化 DP 适用于形如 dp[i] = min(dp[j] + ...) 的转移方程...",
|
||
"metadata": {
|
||
"chunk_index": 2,
|
||
"header_h2": "斜率优化"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### RAG 问答 (`ask`)
|
||
|
||
> 以下功能在 `scripts/rag.py` 中已实现，通过 `src/rag/agent.py` 的 RAG Agent 提供。
|
||
|
||
#### ask: 功能
|
||
|
||
调用 RAG Agent 进行单次问答，输出带溯源引用的答案。
|
||
|
||
#### ask: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `question` | - | 查询问题（位置参数） | 必填 |
|
||
| `--top-k` | - | 检索结果数量 | 5 |
|
||
| `--stream` | - | 流式输出 | `False` |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout（使用时须指定文件路径） |
|
||
|
||
#### ask: 使用示例
|
||
|
||
```bash
|
||
# RAG 问答
|
||
algonotes query ask "树状数组如何求逆序对？"
|
||
|
||
# 指定检索数量
|
||
algonotes query ask "最短路算法对比" --top-k 5
|
||
|
||
# 流式输出
|
||
algonotes query ask "线段树懒标记" --stream
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query ask "树状数组" --json result.json
|
||
```
|
||
|
||
#### ask: 输出示例
|
||
|
||
```text
|
||
树状数组可以用来求逆序对，核心思想是利用其前缀和查询能力...
|
||
```
|
||
|
||
#### ask: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
|------|------|
|
||
| `scripts/rag.py` | ask_question 入口 |
|
||
| `src/rag/agent.py` | RAG Agent 编排 |
|
||
| `src/rag/retriever.py` | 检索工具（search_notes / get_file_content / search_by_tags） |
|
||
| `src/rag/generation.py` | 重排序工具（rerank_results） |
|
||
| `src/store/vector_store.py` | 向量检索 |
|
||
| `src/store/sql_store.py` | 标签匹配 |
|
||
| `src/store/file_store.py` | 文件读取 |
|
||
|
||
#### ask: 注意事项
|
||
|
||
1. **笔记不存在**：返回空结果，不报错
|
||
2. **LLM 调用失败**：返回错误信息
|
||
3. **流式输出**：`--stream` 时实时输出 Agent 思考过程
|
||
|
||
#### ask: JSON 输出格式
|
||
|
||
```json
|
||
{
|
||
"question": "树状数组如何求逆序对？",
|
||
"answer": "树状数组可以用来求逆序对...",
|
||
"success": true,
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
#### query: 输出示例
|
||
|
||
```text
|
||
问题：树状数组如何求逆序对？
|
||
|
||
答案：
|
||
树状数组可以用来求逆序对，核心思想是利用其前缀和查询能力...
|
||
|
||
溯源引用：
|
||
- [个人: fenwick.md#逆序对]
|
||
- [个人: inversion.md#树状数组应用]
|
||
```
|
||
|
||
#### query: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/rag/agent.py` | RAG Agent 编排 |
|
||
| `src/rag/retriever.py` | 检索工具（search_notes / get_file_content / search_by_tags） |
|
||
| `src/rag/generation.py` | 重排序工具（rerank_results） |
|
||
| `src/store/vector_store.py` | 向量检索 |
|
||
| `src/store/sql_store.py` | 标签匹配 |
|
||
| `src/store/file_store.py` | 文件读取 |
|
||
|
||
#### query: 注意事项
|
||
|
||
1. **笔记不存在**：返回空结果，不报错
|
||
2. **LLM 调用失败**：返回错误信息
|
||
3. **流式输出**：`--stream` 时实时输出 Agent 思考过程
|
||
|
||
#### query: JSON 输出格式
|
||
|
||
```json
|
||
{
|
||
"question": "树状数组如何求逆序对？",
|
||
"answer": "树状数组可以用来求逆序对，核心思想是利用其前缀和查询能力...",
|
||
"references": [
|
||
{
|
||
"source": "fenwick.md",
|
||
"section": "逆序对",
|
||
"type": "personal"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 文件层
|
||
|
||
### 导出笔记 (`export`)
|
||
|
||
#### export: 功能
|
||
|
||
导出笔记为带 YAML frontmatter 的 Markdown 文件，兼容 Obsidian。
|
||
|
||
#### export: 参数
|
||
|
||
| 参数 | 缩写 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `filename` | - | 笔记文件名（位置参数） | 与 `--all` 二选一 |
|
||
| `--all` | - | 导出所有笔记 | `False` |
|
||
| `-o` | `--output` | 输出目录 | `./export` |
|
||
| `--json` | - | 输出到 JSON 文件 | stdout |
|
||
|
||
#### export: 使用示例
|
||
|
||
```bash
|
||
# 导出单个笔记
|
||
algonotes query export fenwick.md
|
||
|
||
# 导出到指定目录
|
||
algonotes query export fenwick.md -o ./my_exports
|
||
|
||
# 导出所有笔记
|
||
algonotes query export --all
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes query export fenwick.md --json result.json
|
||
```
|
||
|
||
#### export: 输出示例
|
||
|
||
```text
|
||
Exported fenwick.md to ./export/fenwick.md
|
||
```
|
||
|
||
#### export: YAML Frontmatter 格式
|
||
|
||
```yaml
|
||
---
|
||
title: "树状数组"
|
||
type: "note"
|
||
tags: [树状数组, 数据结构, 模板]
|
||
author: "fangtianchen"
|
||
ingested_at: 2026-06-16 14:30:22
|
||
updated_at: 2026-06-20 10:00:00
|
||
source_url: "https://..."
|
||
---
|
||
|
||
# 树状数组 (Fenwick Tree)
|
||
|
||
## 模板
|
||
...
|
||
```
|
||
|
||
#### export: 依赖模块
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `src/store/sql_store.py` | 笔记元数据查询 |
|
||
| `src/store/file_store.py` | 文件读取 |
|
||
|
||
#### export: 注意事项
|
||
|
||
1. **笔记不存在**：输出错误信息
|
||
2. **输出目录**：自动创建不存在的目录
|
||
3. **覆盖文件**：同名文件会被覆盖
|