forked from fangtianchen/algonotes_rag
119 lines
3.1 KiB
Markdown
119 lines
3.1 KiB
Markdown
# 📟 CLI 命令行工具
|
||
|
||
> 状态：已完成 | 最后更新：2026-06-25
|
||
|
||
---
|
||
|
||
## 📋 设计目标
|
||
|
||
1. 与 MCP 功能对等，提供脚本化、批量操作的接口
|
||
2. 覆盖笔记管理、语义查询、交互问答等核心场景
|
||
3. 支持 `algonotes` 命令和 `python -m scripts.<module>` 两种调用方式
|
||
|
||
---
|
||
|
||
## 📁 目录结构
|
||
|
||
```tree
|
||
scripts/
|
||
├── __init__.py
|
||
├── cli.py # algonotes 统一入口
|
||
├── ingest.py # 导入笔记
|
||
├── delete.py # 删除笔记
|
||
├── update.py # 更新笔记
|
||
├── query.py # 查询笔记
|
||
├── chat.py # 交互式问答
|
||
│
|
||
└── tui/ # TUI 界面模块（规划中）
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 调用方式
|
||
|
||
**方式 1：`algonotes` 命令（推荐）**
|
||
|
||
```bash
|
||
uv run algonotes ingest -i ./my_notes/
|
||
uv run algonotes query list
|
||
uv run algonotes chat
|
||
```
|
||
|
||
**方式 2：独立模块**
|
||
|
||
```bash
|
||
uv run python -m scripts.ingest -i ./my_notes/
|
||
uv run python -m scripts.query list
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 命令总览
|
||
|
||
| 分类 | 命令 | 用途 | 详见 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| **增** | `ingest` | 导入笔记 | [ingest.md](ingest.md) |
|
||
| **改** | `update content` | 更新笔记内容 | [update.md](update.md) |
|
||
| **改** | `update metadata` | 更新笔记元数据 | [update.md](update.md) |
|
||
| **删** | `delete` | 删除笔记 | [delete.md](delete.md) |
|
||
| **查** | `query show/list/info/search` | 查询笔记 | [query.md](query.md) |
|
||
| **查** | `query export` | 导出笔记（Obsidian） | [query.md](query.md) |
|
||
| **查** | `query ask` | RAG 问答 | [query.md](query.md) |
|
||
|
||
---
|
||
|
||
## ⚙️ 通用参数
|
||
|
||
所有输出类命令（`show`、`list`、`info`、`search`）支持以下参数：
|
||
|
||
| 参数 | 说明 | 默认值 |
|
||
| ------ | ------ | -------- |
|
||
| `--json` | 输出到 JSON 文件（指定文件路径） | 若使用此参数，必须指定文件路径 |
|
||
|
||
**使用示例**：
|
||
|
||
```bash
|
||
# 默认输出到 stdout（人类可读）
|
||
algonotes search "树状数组"
|
||
|
||
# 输出到 JSON 文件
|
||
algonotes search "树状数组" --json results.json
|
||
```
|
||
|
||
**JSON 输出格式**：各命令 JSON 格式详见对应文档
|
||
|
||
| 命令 | JSON 格式 |
|
||
| ------ | ----------- |
|
||
| `show` | [query.md](query.md#show-json-输出格式) |
|
||
| `list` | [query.md](query.md#list-json-输出格式) |
|
||
| `info` | [query.md](query.md#info-json-输出格式) |
|
||
| `search` | [query.md](query.md#search-json-输出格式) |
|
||
|
||
---
|
||
|
||
## 🔄 CLI vs MCP 对照
|
||
|
||
| 功能 | CLI 命令 | MCP 工具 |
|
||
| ------ | ---------- | ---------- |
|
||
| 导入笔记 | `algonotes ingest` | `ingest` |
|
||
| 更新内容 | `algonotes update content` | `update` |
|
||
| 更新元数据 | `algonotes update metadata` | `metadata` |
|
||
| 删除笔记 | `algonotes delete` | `delete` |
|
||
| 查看原文 | `algonotes query show` | `show` |
|
||
| 列出笔记 | `algonotes query list` | `list` |
|
||
| 语义搜索 | `algonotes query search` | `search` |
|
||
| RAG 问答 | `algonotes query ask` | `ask` |
|
||
| 导出笔记 | `algonotes query export` | `export` |
|
||
|
||
---
|
||
|
||
## ⚙️ 配置
|
||
|
||
已在 `pyproject.toml` 中注册：
|
||
|
||
```toml
|
||
[project.scripts]
|
||
algonotes = "scripts.cli:main"
|
||
```
|