paperless-ngx-tools

# Paperless-ngx

通过 Paperless-ngx REST API 进行文档管理。

## 配置

在 `~/.clawdbot/clawdbot.json` 中设置环境变量：

```json { "env": { "PAPERLESS_URL": "http://your-paperless-host:8000", "PAPERLESS_TOKEN": "your-api-token" } } ```

或者通过 skills 条目进行配置（允许使用 `apiKey` 简写）：

```json { "skills": { "entries": { "paperless-ngx": { "env": { "PAPERLESS_URL": "http://your-paperless-host:8000" }, "apiKey": "your-api-token" } } } } ```

从 Paperless web UI 获取您的 API 令牌：Settings → Users & Groups → [用户] → Generate Token。

## 快速参考

| 任务 | 命令 | |------|---------| | 搜索文档 | `node {baseDir}/scripts/search.mjs "query"` | | 列出最近项目 | `node {baseDir}/scripts/list.mjs [--limit N]` | | 获取文档 | `node {baseDir}/scripts/get.mjs <id> [--content]` | | 上传文档 | `node {baseDir}/scripts/upload.mjs <file> [--title "..."] [--tags "a,b"]` | | 下载 PDF | `node {baseDir}/scripts/download.mjs <id> [--output path]` | | 列出标签 | `node {baseDir}/scripts/tags.mjs` | | 列出类型 | `node {baseDir}/scripts/types.mjs` | | 列出通讯人 | `node {baseDir}/scripts/correspondents.mjs` |

所有脚本均位于 `{baseDir}/scripts/`。

## 常用工作流

### 查找文档

```bash # Full-text search node {baseDir}/scripts/search.mjs "electricity bill december"

# Filter by tag node {baseDir}/scripts/search.mjs --tag "tax-deductible"

# Filter by document type node {baseDir}/scripts/search.mjs --type "Invoice"

# Filter by correspondent node {baseDir}/scripts/search.mjs --correspondent "AGL"

# Combine filters node {baseDir}/scripts/search.mjs "2025" --tag "unpaid" --type "Invoice" ```

### 获取文档详情

```bash # Metadata only node {baseDir}/scripts/get.mjs 28

# Include OCR text content node {baseDir}/scripts/get.mjs 28 --content

# Full content (no truncation) node {baseDir}/scripts/get.mjs 28 --content --full ```

### 上传文档

```bash # Basic upload (title auto-detected) node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf

# With metadata node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf \ --title "AGL Electricity Jan 2026" \ --tags "unpaid,utility" \ --type "Invoice" \ --correspondent "AGL" \ --created "2026-01-15" ```

### 下载文档

```bash # Download to current directory node {baseDir}/scripts/download.mjs 28

# Specify output path node {baseDir}/scripts/download.mjs 28 --output ~/Downloads/document.pdf

# Get original (not archived/OCR'd version) node {baseDir}/scripts/download.mjs 28 --original ```

### 管理元数据

```bash # List all tags node {baseDir}/scripts/tags.mjs

# List document types node {baseDir}/scripts/types.mjs

# List correspondents node {baseDir}/scripts/correspondents.mjs

# Create new tag node {baseDir}/scripts/tags.mjs --create "new-tag-name"

# Create new correspondent node {baseDir}/scripts/correspondents.mjs --create "New Company Name" ```

## 输出格式

所有脚本均输出 JSON 以便于解析。使用 `jq` 进行格式化：

```bash node {baseDir}/scripts/search.mjs "invoice" | jq '.results[] | {id, title, created}' ```

## 高级用法

对于复杂查询或批量操作，请参阅 [references/api.md](references/api.md) 了解直接 API 访问模式。

## 故障排除

**"PAPERLESS_URL not set"** — 添加到 `~/.clawdbot/clawdbot.json` 的 env 部分或在 shell 中导出。

**"401 Unauthorized"** — 检查 PAPERLESS_TOKEN 是否有效。如有需要，请在 Paperless UI 中重新生成。

**"Connection refused"** — 确认 Paperless 正在运行且 URL 正确（包括端口）。

**Upload fails silently** — 检查 Paperless 日志；文件可能是重复的或格式不受支持。