smart-note-assistant 0.3.0

智能笔记助手 CLI

智能笔记助手（OpenAI 兼容 + 多模态 RAG）

一个面向本地笔记管理的智能助理项目，支持：

• OpenAI 兼容接口（/responses 与 /chat/completions）
• 本地多模态 RAG（文本 + 图片）
• 两种运行方式：CLI（main.py）与 Web（app_web.py）

---

1. 你会先用到什么（30 秒上手）

1.1 直接运行（不安装命令）

# 1) 安装依赖
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt

# 2) 初始化 .env
python main.py init

# 3) 做健康检查
python main.py doctor

# 4) 进入交互
python main.py chat -i

1.3 无需源码安装（pipx / PyPI）

# 推荐：隔离安装（无需拉源码）
pipx install smart-note-assistant

# 或：pip 安装
# pip install smart-note-assistant

# 安装后验证
noteai --help
noteai init --dry-run --output json
noteai init
noteai doctor --output json
noteai chat -m "你好" --output json

说明：

• 默认运行目录为 ~/.noteai。
• 若当前目录已存在 .env 或 data/，会沿用当前目录（兼容旧用法）。
• 可通过 AGENT_HOME 显式指定运行目录，例如：

AGENT_HOME=. noteai init
AGENT_HOME=/path/to/agent-home noteai doctor --output json

---

2. 核心能力

2.1 模型调用

• 默认优先走 /responses
• 可切换到 /chat/completions
• 内置超时、重试、退避（网络抖动 / 429 / 5xx）

2.2 本地多模态 RAG

• 扫描 data/ 下：.md/.txt/.png/.jpg/.jpeg/.webp/.bmp
• 文本与图片索引融合检索
• 支持 OCR 与可选 VLM 语义理解入库
• 支持增量更新、索引重建、异常恢复

2.3 安全与治理

• 受限查询（账号/密码类）访问键校验
• 受限查询频控（默认每分钟 3 次）
• 提示词注入防护
• 工具白名单
• 审计事件日志

2.4 可观测

• 结构化事件日志（JSONL）
• 运行时指标（请求数、命中率、错误率、平均延迟）
• 可选 OpenTelemetry

---

3. 安装与运行

3.1 环境要求

• Python 3.10+
• Windows / macOS / Linux
• 可用的 OpenAI 兼容 API Key

3.2 安装依赖

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt

3.3 初始化配置

推荐使用内置命令生成 .env：

python main.py init

常用参数：

python main.py init --dry-run   # 仅预览
python main.py init --force     # 覆盖已有 .env

最小 .env 示例：

API_KEY=sk-xxxx
BASE_URL=https://your-gateway-or-openai/v1
MODEL=gpt-5.3-codex
API_MODE=responses

.env 是本地敏感文件，请勿提交到 git。

3.4 准备笔记数据

把你的笔记放到 data/：

• 文本：.md、.txt
• 图片：.png/.jpg/.jpeg/.webp/.bmp
• 支持子目录递归扫描

3.5 启动 CLI

# 交互模式（推荐）
python main.py chat -i

# 默认入口（无子命令时）
python main.py

3.6 启动 Web

python -m uvicorn app_web:app --host 127.0.0.1 --port 8000 --reload

访问：http://127.0.0.1:8000

3.7 安装 / 使用 / 卸载 noteai 命令

安装

# 进入项目根目录后执行
pip install -e .

# 验证
noteai --version
noteai --help

使用

# 等价于 python main.py chat -i
noteai chat -i

# 单次提问
noteai ask "列出我最近的 TODO"

# 重建索引（文本模式会实时输出过程）
noteai index-rebuild

# JSON 输出（便于脚本调用）
noteai doctor --output json

卸载

pip uninstall smart-note-assistant

可选清理（按需手动删除）：

• 虚拟环境：.venv/
• 本地配置：.env
• 运行日志：observability/events.jsonl
• 索引文件：项目运行后生成的本地索引目录/文件

---

4. CLI 使用教程

4.1 交互模式内命令

进入交互后可用：

• help / h / ?：帮助
• files：列文件
• config：看配置
• metrics：看会话指标
• update：强制重建索引
• q / quit / exit：退出

4.1.1 全屏交互模式

交互模式支持“程序态”体验：进入后切到备用屏，退出后自动恢复原终端内容。

python main.py chat -i --fullscreen-mode auto   # 默认：自动探测
python main.py chat -i --fullscreen-mode on     # 尽量启用全屏
python main.py chat -i --fullscreen-mode off    # 关闭全屏

# 兼容别名
python main.py chat -i --fullscreen
python main.py chat -i --no-fullscreen

策略说明：

• auto：终端能力满足时启用全屏，否则自动降级为普通交互。
• on：优先启用全屏；若不支持，会提示一次并降级为普通交互。
• off：始终使用普通交互。

以下场景会自动不启用全屏：

• 非 TTY（例如重定向输入/输出）
• TERM 不可用或 TERM=dumb
• Windows 下 VT 模式不可用

当前交互前缀：

• 用户：你 ›
• 助手：助手 ›

4.2 子命令（非交互）

方式 A：直接运行源码入口

python main.py chat -m "帮我总结本地笔记"
python main.py chat --stdin
python main.py ask "列出我最近的 TODO"
python main.py files
python main.py config
python main.py metrics
python main.py index-rebuild
python main.py doctor

方式 B：安装后使用 noteai 命令

noteai chat -m "帮我总结本地笔记"
noteai chat --stdin
noteai ask "列出我最近的 TODO"
noteai files
noteai config
noteai metrics
noteai index-rebuild
noteai doctor

别名：

• files = ls
• config = cfg
• metrics = stat
• index-rebuild = reindex

4.3 输出格式

# python main.py 方式
python main.py ask "帮我总结" --output json
python main.py files --output json
python main.py doctor --output json

# noteai 方式
noteai ask "帮我总结" --output json
noteai files --output json
noteai doctor --output json

4.4 全局参数

• --quiet：精简输出
• --verbose：详细输出（含底层日志）
• --color auto|always|never：颜色模式

示例：

# python main.py 方式
python main.py --color always chat -i
python main.py --quiet ask "今天待办"
python main.py --verbose doctor

# noteai 方式
noteai --color always chat -i
noteai --quiet ask "今天待办"
noteai --verbose doctor

---

5. Web 接口概览

主要接口：

• /api/chat
• /api/notes*（列表/读取/新增/修改/删除/重命名/上传）
• /api/index/*（重建与状态）
• /api/config*（读取/更新/测试/重置）
• /api/system/status
• /api/health

---

6. 关键环境变量

• API_KEY：OpenAI 兼容 API Key
• BASE_URL：OpenAI 兼容服务地址（通常以 /v1 结尾）
• MODEL：模型名
• API_MODE：responses 或 chat
• REQUEST_TIMEOUT：超时秒数
• REQUEST_MAX_RETRIES：重试次数
• REQUEST_RETRY_BACKOFF_MS：重试退避毫秒
• ALLOWED_TOOLS：工具白名单（逗号分隔）
• OTEL_ENABLED：是否启用 OpenTelemetry
• LOG_FILE：日志文件路径（默认 observability/events.jsonl）
• RERANKER_ENABLED：是否启用模型级 reranker
• RERANKER_MODEL：reranker 模型名
• IMAGE_EMBEDDING_MODEL：图片向量模型
• VISION_MODEL：图片理解模型（默认跟随 MODEL）
• ENABLE_IMAGE_VLM：是否启用图片语义入库
• ENABLE_IMAGE_OCR：是否启用 OCR 入库
• SECURITY_KEY_HASH：受限查询访问键哈希
• RESTRICTED_QUERY_LIMIT_PER_MINUTE：受限查询频控阈值

---

7. 常见问题

7.1 doctor 失败

优先检查：BASE_URL、API_KEY、MODEL 是否填写正确。

7.2 /responses 调用失败

可在 .env 里切换：

API_MODE=chat

然后重试。

7.3 首次启动较慢

常见原因是模型下载和索引构建，通常属于正常现象。

7.4 更新了 data/ 但检索不到

在交互里执行 update，或直接运行：

python main.py index-rebuild
# 或
agent index-rebuild

---

8. 测试与评测

# 若已安装 pytest
python -m pytest
python -m pytest tests/test_security.py -q
python -m pytest tests/test_integration_agent_flow.py -q

# 评测
python eval/run_eval.py
python eval/compare_reports.py --baseline eval/reports/baseline.json --current eval/reports/current.json --out eval/reports/compare.md

---

9. 项目结构（简版）

Agent/
├── main.py                  # CLI 入口
├── app_web.py               # Web 入口
├── rag_engine.py            # RAG 引擎
├── config/settings.py       # 配置读取与校验
├── workflow/                # LangGraph 编排
├── infra/                   # 模型与检索基础设施
├── core/                    # 安全、可观测、领域逻辑
├── data/                    # 本地笔记数据
├── tests/                   # 测试
├── eval/                    # 评测脚本与报告
└── README.md

---

10. 路线图

• 基础 RAG（本地文档问答）
• OpenAI 兼容双模式（responses/chat）
• CLI 产品化（子命令、JSON、doctor/init、颜色与交互优化）
• Web 形态（FastAPI + 静态页面）
• 更深的 RAG 工具链整合
• 多格式文档支持（PDF/Word/Excel）
• 长期记忆存储（如 SQLite）