Metadata-Version: 2.4
Name: smart-note-assistant
Version: 0.3.0
Summary: 智能笔记助手 CLI
Author: 智能笔记助手
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai
Requires-Dist: python-dotenv
Requires-Dist: langchain
Requires-Dist: langchain-openai
Requires-Dist: langchain-community
Requires-Dist: langchain-huggingface
Requires-Dist: faiss-cpu
Requires-Dist: sentence-transformers
Requires-Dist: Pillow
Requires-Dist: numpy
Requires-Dist: rapidocr-onnxruntime
Requires-Dist: huggingface-hub<1.0.0,>=0.33.4
Requires-Dist: transformers<5.0.0
Requires-Dist: bcrypt
Requires-Dist: opentelemetry-api
Requires-Dist: opentelemetry-sdk
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: python-multipart

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

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

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

---

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

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

```bash
# 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）

```bash
# 推荐：隔离安装（无需拉源码）
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` 显式指定运行目录，例如：

```bash
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 安装依赖

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

### 3.3 初始化配置

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

```bash
python main.py init
```

常用参数：

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

最小 `.env` 示例：

```ini
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

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

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

### 3.6 启动 Web

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

访问：`http://127.0.0.1:8000`

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

#### 安装

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

# 验证
noteai --version
noteai --help
```

#### 使用

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

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

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

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

#### 卸载

```bash
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 全屏交互模式

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

```bash
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：直接运行源码入口

```bash
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` 命令

```bash
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 输出格式

```bash
# 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`：颜色模式

示例：

```bash
# 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` 里切换：

```ini
API_MODE=chat
```

然后重试。

### 7.3 首次启动较慢
常见原因是模型下载和索引构建，通常属于正常现象。

### 7.4 更新了 `data/` 但检索不到
在交互里执行 `update`，或直接运行：

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

---

## 8. 测试与评测

```bash
# 若已安装 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. 项目结构（简版）

```text
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. 路线图

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