nber-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{nber_cli-0.5.0 → nber_cli-0.6.0}/.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "nber-cli",
   "description": "Claude Code marketplace for NBER-CLI research workflows.",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "owner": {
     "name": "Song Tan",
     "email": "sepinetam@gmail.com",
@@ -12,7 +12,7 @@
     {
       "name": "nber-cli",
       "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
-      "version": "0.4.0",
+      "version": "0.6.0",
       "author": {
         "name": "Song Tan",
         "email": "sepinetam@gmail.com"

{nber_cli-0.5.0 → nber_cli-0.6.0}/CHANGELOG.md

@@ -6,7 +6,21 @@ This file is the canonical release history. The English mirror at `docs/en/chang
 
 ## [Unreleased]
 
-## [0.5.0] - 2026-06-16
+## [0.6.0] - 2026-07-05
+
+### Changed
+- Migrated the database layer from raw `sqlite3` to SQLModel/SQLAlchemy. All tables are now declared as SQLModel models with explicit indexes.
+- `db init --db-path` and `db migrate <new_db_path>` now accept `sqlite:///path/to/nber.db` URLs in addition to file paths.
+- Feed fetching, cache cleanup, query logging, download logging, info logging, and info-cache writes now use explicit SQLAlchemy sessions and commits.
+- `config.schema.json` now describes the database path as a "Path or sqlite:/// URL".
+
+### Added
+- Added `sqlmodel>=0.0.24` and SQLAlchemy to project dependencies.
+- Added CLI tests for `sqlite:///` database path handling.
+- Added release notes for v0.6.0.
+
+### Fixed
+- Updated the version fallback in `cli.py` from `0.4.0` to `0.6.0`.
 
 ### Security
 - RSS feed parsing now uses `defusedxml` to block XML external entity (XXE) and entity expansion attacks.

{nber_cli-0.5.0 → nber_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nber-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: A command-line interface for accessing National Bureau of Economic Research (NBER) papers without a browser.
 Project-URL: Homepage, https://github.com/sepinetam/nber-cli
 Project-URL: Repository, https://github.com/sepinetam/nber-cli
@@ -25,6 +25,7 @@ Requires-Dist: certifi
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: fake-useragent
 Requires-Dist: mcp>=1.27.1
+Requires-Dist: sqlmodel>=0.0.24
 Description-Content-Type: text/markdown
 
 # NBER-CLI
@@ -48,7 +49,7 @@ A command line interface for reaching the National Bureau of Economic Research (
 - Download single papers or batches as PDF files.
 - Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
 - Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
-- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db`, managed through SQLModel/SQLAlchemy and configurable with a filesystem path or `sqlite:///...` URL.
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/README.md

@@ -19,7 +19,7 @@ A command line interface for reaching the National Bureau of Economic Research (
 - Download single papers or batches as PDF files.
 - Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
 - Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
-- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db`, managed through SQLModel/SQLAlchemy and configurable with a filesystem path or `sqlite:///...` URL.
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/README.zh-CN.md

@@ -18,7 +18,7 @@
 - 下载单篇或批量论文 PDF。
 - 通过本地 RSS feed 缓存追踪 NBER 新发布的工作论文（`nber-cli feed fetch` / `feed clean`）。
 - 本地缓存论文元数据（`nber-cli info` 会写入 `info_cache`），采用滑动 TTL；同时为 `search`、`download` 和 `info` 查询记录行为日志。
-- 把缓存、RSS 条目和行为日志统一存放在本地 SQLite 数据库 `~/.nber-cli/nber.db`（路径可通过 `nber-cli db init` / `db migrate` 配置）。
+- 把缓存、RSS 条目和行为日志统一存放在本地 SQLite 数据库 `~/.nber-cli/nber.db`，由 SQLModel/SQLAlchemy 管理，路径可用普通文件路径或 `sqlite:///...` URL 配置。
 - 通过 MCP 工具把核心能力暴露给 AI Agent。
 - 默认输出适合阅读的文本，也支持 JSON 输出用于自动化流程。
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/changelog.md

@@ -6,7 +6,21 @@ This page mirrors the canonical `CHANGELOG.md` at the repository root. The Chine
 
 ## Unreleased
 
-## 0.5.0 - 2026-06-16
+## 0.6.0 - 2026-07-05
+
+### Changed
+- Migrated the database layer from raw `sqlite3` to SQLModel/SQLAlchemy. All tables are now declared as SQLModel models with explicit indexes.
+- `db init --db-path` and `db migrate <new_db_path>` now accept `sqlite:///path/to/nber.db` URLs in addition to file paths.
+- Feed fetching, cache cleanup, query logging, download logging, info logging, and info-cache writes now use explicit SQLAlchemy sessions and commits.
+- `config.schema.json` now describes the database path as a "Path or sqlite:/// URL".
+
+### Added
+- Added `sqlmodel>=0.0.24` and SQLAlchemy to project dependencies.
+- Added CLI tests for `sqlite:///` database path handling.
+- Added release notes for v0.6.0.
+
+### Fixed
+- Updated the version fallback in `cli.py` from `0.4.0` to `0.6.0`.
 
 ### Security
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/cli.md

@@ -239,7 +239,7 @@ When only `--start-date` is provided, NBER-CLI automatically uses the current da
 
 ## feed
 
-`feed` works with NBER's new working papers RSS feed and the local SQLite database. The database tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
+`feed` works with NBER's new working papers RSS feed and the local database. The database tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
 
 ### feed fetch
 
@@ -325,7 +325,7 @@ Only `y` or `Y` continues. Any other response aborts without deleting records.
 
 ## db
 
-`db` manages the local SQLite database used by `info`, `search`, `download`, and `feed` for cache and behavior logs.
+`db` manages the local SQLite database used by `info`, `search`, `download`, and `feed` for cache and behavior logs. The database is stored on the user's machine and accessed through SQLModel/SQLAlchemy; commands accept either a filesystem path or a `sqlite:///...` URL.
 
 ### db init
 
@@ -334,6 +334,7 @@ Initialize the database and write its path to the user config:
 ```bash
 nber-cli db init
 nber-cli db init --db-path ~/.nber-cli/nber.db
+nber-cli db init --db-path sqlite:////Users/name/data/nber.db
 ```
 
 If `--db-path` is omitted, the default database path is `~/.nber-cli/nber.db`.
@@ -346,6 +347,7 @@ Move the database to a new path and update the user config:
 
 ```bash
 nber-cli db migrate ~/data/nber.db
+nber-cli db migrate sqlite:////Users/name/data/nber.db
 ```
 
 Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
@@ -354,8 +356,8 @@ Migration moves the SQLite database file and any SQLite sidecar files such as `-
 
 | Subcommand | Option | Description |
 | --- | --- | --- |
-| `init` | `--db-path` | SQLite database path. Defaults to `~/.nber-cli/nber.db`. |
-| `migrate` | `new_db_path` | New SQLite database path. |
+| `init` | `--db-path` | SQLite database path or `sqlite:///...` URL. Defaults to `~/.nber-cli/nber.db`. |
+| `migrate` | `new_db_path` | New SQLite database path or `sqlite:///...` URL. |
 
 ## mcp-server
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Most NBER-CLI runtime behavior uses built-in defaults. The local database also uses a small user config file to remember the SQLite database path selected by `nber-cli db init` or `nber-cli db migrate`.
+Most NBER-CLI runtime behavior uses built-in defaults. The local database also uses a small user config file to remember the database location selected by `nber-cli db init` or `nber-cli db migrate`.
 
 ## Runtime Defaults
 
@@ -25,7 +25,7 @@ The following list is exhaustive — values not listed here are constants.
 | --- | --- | --- |
 | `info.cache_enabled` | Yes | `~/.nber-cli/config.json`; toggle via `nber-cli info cache --turn-on/--off` |
 | `info.cache_ttl_days` | Yes | `~/.nber-cli/config.json`; set via `nber-cli info cache --set-refresh <N>` |
-| `feed.db-path` (SQLite path) | Yes | `~/.nber-cli/config.json`; set via `nber-cli db init --db-path ...` or `nber-cli db migrate ...` |
+| `feed.db-path` (database path or `sqlite:///...` URL) | Yes | `~/.nber-cli/config.json`; set via `nber-cli db init --db-path ...` or `nber-cli db migrate ...` |
 | Request timeout | **No** | Code constant in `NBERCLIConfig` |
 | Retry count / request attempts | **No** | Code constant in `NBERCLIConfig` |
 | Download connection limits | **No** | Code constant in `NBERCLIConfig` |
@@ -57,7 +57,7 @@ Current schema:
 }
 ```
 
-`feed.db-path` points to the SQLite database used by `info`, `search`, `download`, and `feed`. The historical `feed` key name is preserved for backward compatibility; the database itself is general-purpose.
+`feed.db-path` points to the local database used by `info`, `search`, `download`, and `feed`. It may be a normal filesystem path or a SQLite URL such as `sqlite:///relative/nber.db` or `sqlite:////Users/name/data/nber.db`. The historical `feed` key name is preserved for backward compatibility; the database itself is general-purpose.
 
 `schema_version` records the current database schema version. NBER-CLI updates it after `db init` or schema upgrades.
 
@@ -87,6 +87,12 @@ Initialize at a custom path:
 nber-cli db init --db-path ~/data/nber.db
 ```
 
+Initialize with a SQLite URL:
+
+```bash
+nber-cli db init --db-path sqlite:////Users/name/data/nber.db
+```
+
 Move an existing database and update the config:
 
 ```bash
@@ -101,6 +107,14 @@ The database holds:
 - `info_cache`: paper metadata cache used by `info` and the MCP `get_paper_info` tool. Cache reads are gated by `info.cache_enabled` and respect the `info.cache_ttl_days` TTL.
 - `query_log`, `download_log`, `info_log`: behavior logs for search keywords, download outcomes, and info lookups.
 
+### Storage, Safety, and Extensibility
+
+The database is local-only. NBER-CLI does not send this cache or log database to project infrastructure, and no NBER-CLI server receives a copy. By default it lives under `~/.nber-cli/nber.db`; when `db init` or `db migrate` is used on macOS or Linux, the selected file must stay inside the user's home directory. This keeps the default persistence model predictable and avoids accidental writes into system or shared locations.
+
+The on-disk format is SQLite, so the database is a self-contained file plus standard SQLite sidecar files when WAL or journaling is active. Schema changes are versioned with SQLite's `PRAGMA user_version`; NBER-CLI refuses to write to a database created by a newer schema version, which protects data from accidental downgrade writes. Operations that update cache or log rows use transactions through the SQLModel/SQLAlchemy engine, and non-critical log/cache writes fail soft so a local database problem does not break search, download, or metadata lookup workflows.
+
+The Python access layer is SQLModel on top of SQLAlchemy. Tables are declared as typed SQLModel models, while the public API still returns filesystem `Path` values for compatibility. This gives the current CLI a stable SQLite file today and leaves room for future database work, such as richer typed queries, stricter schema migrations, or additional SQLAlchemy-supported backends, without changing the user-facing commands first.
+
 ## Database Operations
 
 The database is created and upgraded automatically the first time any command that touches it runs. Running `nber-cli db init` is **not** required before using `info`, `search`, `download`, or `feed`; it exists for callers that want to pre-create the file or pin a non-default path. After `db init` (or after the first successful run), the schema version is recorded in `~/.nber-cli/config.json` under `schema_version`.
@@ -124,7 +138,7 @@ The database is created and upgraded automatically the first time any command th
 
 ### Migrate and Reset
 
-`nber-cli db migrate <new_db_path>` moves the database to a new path, including any SQLite `-wal`, `-shm`, and `-journal` sidecar files, and updates `feed.db-path` in the user config. The destination must not already exist; the command refuses to overwrite an existing file.
+`nber-cli db migrate <new_db_path>` moves the database to a new path or SQLite URL, including any SQLite `-wal`, `-shm`, and `-journal` sidecar files, and updates `feed.db-path` in the user config. The destination must not already exist; the command refuses to overwrite an existing file.
 
 There is no built-in command to reset the database to an empty state. The supported ways to start over are:
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/getting-started.md

@@ -97,6 +97,8 @@ Initialize the local database:
 nber-cli db init
 ```
 
+The database is a local SQLite file, managed through SQLModel/SQLAlchemy. By default it is stored at `~/.nber-cli/nber.db`; advanced users can choose another path or a `sqlite:///...` URL with `nber-cli db init --db-path ...`.
+
 Fetch the NBER new working papers RSS feed:
 
 ```bash

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/mcp.md

@@ -119,7 +119,7 @@ The MCP server performs network requests to NBER and can write PDFs to disk thro
 
 ### Local Persistence and Caching
 
-`get_paper_info` honors the same `info_cache` toggle and TTL as the CLI. When the cache is enabled, the tool reads from `info_cache` on a hit and writes a new row on a miss, mirroring the CLI behavior. Every call also appends a row to `info_log` so the local database records the lookup; the local database is shared with the CLI at the path configured in `~/.nber-cli/config.json`. Tool responses do not flag whether the result came from the cache; if the caller needs that signal it must look at its own call history or use the CLI directly.
+`get_paper_info` honors the same `info_cache` toggle and TTL as the CLI. When the cache is enabled, the tool reads from `info_cache` on a hit and writes a new row on a miss, mirroring the CLI behavior. Every call also appends a row to `info_log` so the local database records the lookup; the SQLModel/SQLAlchemy-backed local database is shared with the CLI at the path or `sqlite:///...` URL configured in `~/.nber-cli/config.json`. Tool responses do not flag whether the result came from the cache; if the caller needs that signal it must look at its own call history or use the CLI directly.
 
 ### Differences From the CLI
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/policy.md

@@ -13,7 +13,7 @@ NBER-CLI is a command-line and MCP utility for searching NBER working papers, re
 ## Project Boundaries
 
 - **No project-side storage**: NBER-CLI does not operate servers, caches, mirrors, CDNs, or other infrastructure for storing NBER papers or metadata. Requests go directly from the user's machine or agent runtime to NBER's website.
-- **Default local persistence on the user machine**: NBER-CLI does keep a local SQLite database at `~/.nber-cli/nber.db` (or the path configured by `nber-cli db init` / `db migrate`) and a user config file at `~/.nber-cli/config.json`. By default the following commands and tools write to that database without any extra user input:
+- **Default local persistence on the user machine**: NBER-CLI does keep a local SQLite database at `~/.nber-cli/nber.db` (or the path / `sqlite:///...` URL configured by `nber-cli db init` / `db migrate`) and a user config file at `~/.nber-cli/config.json`. The database is accessed through SQLModel/SQLAlchemy and remains on the user's machine unless the user copies or exports it. By default the following commands and tools write to that database without any extra user input:
   - `nber-cli search` records every query, including the keyword, the applied filters, and the result count, in the `query_log` table.
   - `nber-cli download` records every attempt, including the paper ID, success or failure status, the saved PDF path, and the error message when relevant, in the `download_log` table. Single download and batch download both write one row per attempt.
   - `nber-cli info` and the MCP `get_paper_info` tool each write a row to the `info_log` table for the looked-up paper.

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/en/python-api.md

@@ -2,7 +2,7 @@
 
 NBER-CLI exposes the same core functionality as importable Python functions. The API is asynchronous because lookup, search, and downloads perform network I/O.
 
-Feed cache helpers are synchronous because they perform local SQLite work and a synchronous RSS fetch.
+Feed cache helpers are synchronous because they perform local database work and a synchronous RSS fetch.
 
 ## API Boundaries
 
@@ -113,6 +113,15 @@ db_path = init_database()
 print(db_path)
 ```
 
+Initialize with a SQLite URL:
+
+```python
+from nber_cli import init_database
+
+db_path = init_database("sqlite:////Users/name/data/nber.db")
+print(db_path)
+```
+
 Fetch the NBER RSS feed and display new cached items:
 
 ```python
@@ -237,11 +246,11 @@ The same `clear_info_cache` function also supports `delete_all=True` and `start_
 
 ## Database and Logging Helpers
 
-These helpers are part of the top-level public API and are safe to call from user code. They wrap the SQLite layer that `info`, `search`, `download`, and `feed` use internally. Logging and cache writers fail soft: when a database error occurs, the helper prints a one-line warning to `stderr` and returns `None` (for recorders) instead of raising, so they do not break the calling command. Cache readers return `None` or `0` on partial database errors. Callers that need stronger guarantees should talk to SQLite directly.
+These helpers are part of the top-level public API and are safe to call from user code. They wrap the local SQLite database that `info`, `search`, `download`, and `feed` use internally through SQLModel/SQLAlchemy. Logging and cache writers fail soft: when a database error occurs, the helper prints a one-line warning to `stderr` and returns `None` (for recorders) instead of raising, so they do not break the calling command. Cache readers return `None` or `0` on partial database errors. Callers that need stronger guarantees can inspect the resolved local database path directly.
 
 ### `get_database_path(db_path=None) -> Path`
 
-Return the resolved SQLite database path. When `db_path` is `None`, NBER-CLI uses the path configured in `~/.nber-cli/config.json`, or falls back to the default `~/.nber-cli/nber.db`, or the legacy `~/.nber-cli/feed.db` file when present. The returned path is always absolute. The database file is **not** required to exist.
+Return the resolved SQLite database path. `db_path` may be a `Path`, a filesystem path string, or a `sqlite:///...` URL. When `db_path` is `None`, NBER-CLI uses the location configured in `~/.nber-cli/config.json`, or falls back to the default `~/.nber-cli/nber.db`, or the legacy `~/.nber-cli/feed.db` file when present. The returned path is always absolute, even when the input was a SQLite URL. The database file is **not** required to exist.
 
 ### `get_schema_version(db_path=None) -> int`
 
@@ -324,7 +333,7 @@ Parse raw NBER RSS XML into a list of `NBERFeedItem` objects. Items must carry a
 | Field | Type | Description |
 | --- | --- | --- |
 | `source_url` | `str` | RSS feed URL. |
-| `database_path` | `Path` | SQLite cache database path. |
+| `database_path` | `Path` | Resolved local SQLite cache database path. |
 | `total_fetched` | `int` | Number of RSS items fetched. |
 | `new_count` | `int` | Number of fetched items that were not already in the cache. |
 | `display_all` | `bool` | Whether returned items include all fetched items. |
@@ -335,7 +344,7 @@ Parse raw NBER RSS XML into a list of `NBERFeedItem` objects. Items must carry a
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `database_path` | `Path` | SQLite cache database path. |
+| `database_path` | `Path` | Resolved local SQLite cache database path. |
 | `matched_count` | `int` | Number of cache records matching the clean criteria. |
 | `deleted_count` | `int` | Number of cache records deleted. |
 | `mode` | `str` | Clean mode: `days`, `all`, or `date-range`. |
@@ -348,7 +357,7 @@ Parse raw NBER RSS XML into a list of `NBERFeedItem` objects. Items must carry a
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `database_path` | `Path` | SQLite cache database path. |
+| `database_path` | `Path` | Resolved local SQLite cache database path. |
 | `matched_count` | `int` | Number of cache records matching the clean criteria. |
 | `deleted_count` | `int` | Number of cache records deleted. |
 | `mode` | `str` | Clean mode: `days`, `all`, or `date-range`. |
@@ -451,7 +460,7 @@ Produced by `feed_results(result)`:
 | Field | Type | Notes |
 | --- | --- | --- |
 | `source_url` | `str` | The RSS feed URL that was fetched. |
-| `database_path` | `str` | Absolute path of the SQLite database the items were written to. |
+| `database_path` | `str` | Resolved absolute path of the local SQLite database the items were written to. |
 | `total_fetched` | `int` | Total items parsed from the feed. |
 | `new_count` | `int` | Items that were not already in the local cache. |
 | `display_all` | `bool` | `true` when `results` includes all fetched items, `false` when limited to new ones. |

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/changelog.md

@@ -6,7 +6,24 @@
 
 ## 未发布
 
-## 0.5.0 - 2026-06-16
+## 0.6.0 - 2026-07-05
+
+### Changed
+
+- 数据库层从原生 `sqlite3` 迁移到 SQLModel/SQLAlchemy。所有表均声明为带显式索引的 SQLModel 模型。
+- `db init --db-path` 和 `db migrate <new_db_path>` 除文件路径外，现在也接受 `sqlite:///path/to/nber.db` URL。
+- Feed 拉取、缓存清理、查询日志、下载日志、info 日志和 info 缓存写入现在使用显式的 SQLAlchemy Session 并提交。
+- `config.schema.json` 将数据库路径描述为 "Path or sqlite:/// URL"。
+
+### Added
+
+- 项目依赖中新增 `sqlmodel>=0.0.24` 及其 SQLAlchemy 传递依赖。
+- 新增针对 `sqlite:///` 数据库路径处理的 CLI 测试。
+- 新增 v0.6.0 release notes。
+
+### Fixed
+
+- 将 `cli.py` 中的版本 fallback 从 `0.4.0` 更新为 `0.6.0`。
 
 ### Security
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/cli.md

@@ -239,7 +239,7 @@ nber-cli search "inflation" -f json
 
 ## feed
 
-`feed` 用于处理 NBER 最新工作论文 RSS feed 和本地 SQLite 数据库。数据库会记录哪些 RSS 条目已经见过，因此 `feed fetch` 默认只显示新发现的论文。
+`feed` 用于处理 NBER 最新工作论文 RSS feed 和本地数据库。数据库会记录哪些 RSS 条目已经见过，因此 `feed fetch` 默认只显示新发现的论文。
 
 ### feed fetch
 
@@ -325,7 +325,7 @@ Continue? [y/N]:
 
 ## db
 
-`db` 用于管理本地 SQLite 数据库，`info`、`search`、`download` 和 `feed` 会用这个数据库存放缓存和行为日志。
+`db` 用于管理本地 SQLite 数据库，`info`、`search`、`download` 和 `feed` 会用这个数据库存放缓存和行为日志。数据库保存在用户机器上，并通过 SQLModel/SQLAlchemy 访问；命令参数既接受普通文件路径，也接受 `sqlite:///...` URL。
 
 ### db init
 
@@ -334,6 +334,7 @@ Continue? [y/N]:
 ```bash
 nber-cli db init
 nber-cli db init --db-path ~/.nber-cli/nber.db
+nber-cli db init --db-path sqlite:////Users/name/data/nber.db
 ```
 
 如果省略 `--db-path`，默认数据库路径是 `~/.nber-cli/nber.db`。
@@ -346,6 +347,7 @@ nber-cli db init --db-path ~/.nber-cli/nber.db
 
 ```bash
 nber-cli db migrate ~/data/nber.db
+nber-cli db migrate sqlite:////Users/name/data/nber.db
 ```
 
 迁移会移动 SQLite 数据库文件，以及 `-wal`、`-shm`、`-journal` 等 SQLite sidecar 文件。目标路径不能已经存在。
@@ -354,8 +356,8 @@ nber-cli db migrate ~/data/nber.db
 
 | 子命令 | 选项 | 说明 |
 | --- | --- | --- |
-| `init` | `--db-path` | SQLite 数据库路径，默认是 `~/.nber-cli/nber.db`。 |
-| `migrate` | `new_db_path` | 新的 SQLite 数据库路径。 |
+| `init` | `--db-path` | SQLite 数据库路径或 `sqlite:///...` URL，默认是 `~/.nber-cli/nber.db`。 |
+| `migrate` | `new_db_path` | 新的 SQLite 数据库路径或 `sqlite:///...` URL。 |
 
 ## mcp-server
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 # 配置
 
-NBER-CLI 的大多数运行时行为使用内置默认值。本地数据库还会使用一个小型用户配置文件，用来记住 `nber-cli db init` 或 `nber-cli db migrate` 选择的 SQLite 数据库路径。
+NBER-CLI 的大多数运行时行为使用内置默认值。本地数据库还会使用一个小型用户配置文件，用来记住 `nber-cli db init` 或 `nber-cli db migrate` 选择的数据库位置。
 
 ## 运行时默认值
 
@@ -25,7 +25,7 @@ NBER-CLI 的大多数运行时行为使用内置默认值。本地数据库还
 | --- | --- | --- |
 | `info.cache_enabled` | 是 | `~/.nber-cli/config.json`；用 `nber-cli info cache --turn-on/--off` 切换 |
 | `info.cache_ttl_days` | 是 | `~/.nber-cli/config.json`；用 `nber-cli info cache --set-refresh <N>` 设置 |
-| `feed.db-path`（SQLite 路径） | 是 | `~/.nber-cli/config.json`；用 `nber-cli db init --db-path ...` 或 `nber-cli db migrate ...` 设置 |
+| `feed.db-path`（数据库路径或 `sqlite:///...` URL） | 是 | `~/.nber-cli/config.json`；用 `nber-cli db init --db-path ...` 或 `nber-cli db migrate ...` 设置 |
 | 请求超时 | **否** | `NBERCLIConfig` 中的代码常量 |
 | 重试次数 / 请求尝试次数 | **否** | `NBERCLIConfig` 中的代码常量 |
 | 下载连接上限 | **否** | `NBERCLIConfig` 中的代码常量 |
@@ -57,7 +57,7 @@ NBER-CLI 的大多数运行时行为使用内置默认值。本地数据库还
 }
 ```
 
-`feed.db-path` 指向 `info`、`search`、`download` 和 `feed` 都会使用的 SQLite 数据库。`feed` 这个 key 名称保留以保持向后兼容，数据库本身是通用的。
+`feed.db-path` 指向 `info`、`search`、`download` 和 `feed` 都会使用的本地数据库。它可以是普通文件路径，也可以是 `sqlite:///relative/nber.db` 或 `sqlite:////Users/name/data/nber.db` 这样的 SQLite URL。`feed` 这个 key 名称保留以保持向后兼容，数据库本身是通用的。
 
 `schema_version` 记录当前数据库 schema 的版本。NBER-CLI 在 `db init` 或 schema 升级后更新该字段。
 
@@ -87,6 +87,12 @@ nber-cli db init
 nber-cli db init --db-path ~/data/nber.db
 ```
 
+用 SQLite URL 初始化：
+
+```bash
+nber-cli db init --db-path sqlite:////Users/name/data/nber.db
+```
+
 移动已有数据库并更新配置：
 
 ```bash
@@ -101,6 +107,14 @@ nber-cli db migrate ~/data/nber.db
 - `info_cache`：`info` 和 MCP `get_paper_info` 工具使用的论文元数据缓存。读取行为受 `info.cache_enabled` 控制，并受 `info.cache_ttl_days` 的 TTL 约束。
 - `query_log`、`download_log`、`info_log`：搜索关键词、下载结果和 info 查询的行为日志。
 
+### 存储、安全性与扩展性
+
+数据库只保存在本机。NBER-CLI 不会把这份缓存或日志数据库发送到项目侧基础设施，也没有 NBER-CLI 服务器会接收副本。默认位置是 `~/.nber-cli/nber.db`；在 macOS 或 Linux 上使用 `db init` 或 `db migrate` 时，选择的数据库文件必须位于用户 home 目录内。这样可以让默认持久化位置更可预期，也避免误写到系统目录或共享目录。
+
+磁盘格式仍然是 SQLite，因此数据库是一个自包含文件；启用 WAL 或 journal 时会再带有标准 SQLite sidecar 文件。schema 通过 SQLite 的 `PRAGMA user_version` 记录版本；如果数据库来自更新的 schema 版本，NBER-CLI 会拒绝写入，避免旧版本程序误写新结构。缓存和日志更新通过 SQLModel/SQLAlchemy engine 以事务方式执行；非关键的日志和缓存写入采用软失败策略，所以本地数据库问题不会中断搜索、下载或元数据查询主流程。
+
+Python 访问层使用 SQLModel，并建立在 SQLAlchemy 之上。表结构以带类型的 SQLModel 模型声明，同时公共 API 为了兼容仍返回文件系统 `Path`。这让当前 CLI 继续使用稳定的 SQLite 文件，同时为未来的数据库能力留下空间，例如更丰富的类型化查询、更严格的 schema 迁移，或在不先改变用户命令的情况下接入更多 SQLAlchemy 支持的后端。
+
 ## 数据库操作
 
 数据库会在首次运行任何触及它的命令时自动创建并完成 schema 升级。`info`、`search`、`download` 和 `feed` 的使用者**不必**先执行 `nber-cli db init`；该命令的存在是为了让调用方可以预创建文件或指定非默认路径。`db init` 执行后（或首次成功运行后），schema 版本会写入 `~/.nber-cli/config.json` 的 `schema_version` 字段。
@@ -124,7 +138,7 @@ nber-cli db migrate ~/data/nber.db
 
 ### 迁移与重置
 
-`nber-cli db migrate <new_db_path>` 把数据库移至新路径，包括所有 SQLite `-wal`、`-shm`、`-journal` sidecar 文件，并更新用户配置中的 `feed.db-path`。目标路径不能已经存在；该命令会拒绝覆盖现有文件。
+`nber-cli db migrate <new_db_path>` 把数据库移至新路径或 SQLite URL，包括所有 SQLite `-wal`、`-shm`、`-journal` sidecar 文件，并更新用户配置中的 `feed.db-path`。目标路径不能已经存在；该命令会拒绝覆盖现有文件。
 
 目前没有“直接清空数据库”的内建命令。可行的重置方式有：
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/getting-started.md

@@ -97,6 +97,8 @@ nber-cli info w25000 --all
 nber-cli db init
 ```
 
+数据库是由 SQLModel/SQLAlchemy 管理的本地 SQLite 文件，默认位于 `~/.nber-cli/nber.db`；高级用户可以用 `nber-cli db init --db-path ...` 指定其他路径或 `sqlite:///...` URL。
+
 获取 NBER 最新工作论文 RSS feed：
 
 ```bash

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/mcp.md

@@ -119,7 +119,7 @@ MCP server 会向 NBER 发起网络请求，并可以通过 `download_paper` 写
 
 ### 本地持久化与缓存
 
-`get_paper_info` 遵守与 CLI 相同的 `info_cache` 开关和 TTL。缓存开启时，命中会从 `info_cache` 读取，未命中会写入新行，行为与 CLI 一致。每次调用还会向 `info_log` 追加一行，使本地数据库记录这次查询；该数据库与 CLI 共用，由 `~/.nber-cli/config.json` 中的路径决定。工具的返回值不会标明结果是否来自缓存；调用方需要该信号时，应自己检查调用历史或直接使用 CLI。
+`get_paper_info` 遵守与 CLI 相同的 `info_cache` 开关和 TTL。缓存开启时，命中会从 `info_cache` 读取，未命中会写入新行，行为与 CLI 一致。每次调用还会向 `info_log` 追加一行，使本地数据库记录这次查询；这个由 SQLModel/SQLAlchemy 访问的本地数据库与 CLI 共用，由 `~/.nber-cli/config.json` 中配置的路径或 `sqlite:///...` URL 决定。工具的返回值不会标明结果是否来自缓存；调用方需要该信号时，应自己检查调用历史或直接使用 CLI。
 
 ### 与 CLI 的差异
 

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/policy.md

@@ -11,7 +11,7 @@ NBER-CLI 是一个命令行与 MCP 工具，用于帮助用户搜索 NBER 工作
 ## 项目边界
 
 - **不进行项目侧存储**：NBER-CLI 不运营用于存储 NBER 论文或元数据的服务器、缓存、镜像、CDN 或其他基础设施。请求直接从用户的设备或 Agent 运行环境发往 NBER 网站。
-- **用户机器上的默认本地持久化**：NBER-CLI 会在用户机器上保留一个本地 SQLite 数据库，默认位于 `~/.nber-cli/nber.db`（或 `nber-cli db init` / `db migrate` 配置的路径），并保留一个用户配置文件 `~/.nber-cli/config.json`。下列命令和工具会在没有额外用户输入的情况下默认写入该数据库：
+- **用户机器上的默认本地持久化**：NBER-CLI 会在用户机器上保留一个本地 SQLite 数据库，默认位于 `~/.nber-cli/nber.db`（或 `nber-cli db init` / `db migrate` 配置的路径 / `sqlite:///...` URL），并保留一个用户配置文件 `~/.nber-cli/config.json`。数据库通过 SQLModel/SQLAlchemy 访问，除非用户自行复制或导出，否则它只留在用户机器上。下列命令和工具会在没有额外用户输入的情况下默认写入该数据库：
   - `nber-cli search` 会把每次查询的关键词、筛选条件和结果数量记录到 `query_log` 表。
   - `nber-cli download` 会把每次下载尝试的论文编号、成功或失败状态、保存的 PDF 路径以及失败时的错误信息记录到 `download_log` 表。单篇下载和批量下载都会按尝试次数逐条写入。
   - `nber-cli info` 与 MCP `get_paper_info` 工具会把每次查询的论文编号写入 `info_log` 表。

{nber_cli-0.5.0 → nber_cli-0.6.0}/docs/zh/python-api.md

@@ -2,7 +2,7 @@
 
 NBER-CLI 暴露了与 CLI 相同核心能力的 Python 函数。由于查询、搜索和下载都涉及网络 I/O，这些 API 是异步的。
 
-feed 缓存辅助函数是同步的，因为它们主要执行本地 SQLite 操作和同步 RSS 获取。
+feed 缓存辅助函数是同步的，因为它们主要执行本地数据库操作和同步 RSS 获取。
 
 ## API 边界
 
@@ -113,6 +113,15 @@ db_path = init_database()
 print(db_path)
 ```
 
+使用 SQLite URL 初始化：
+
+```python
+from nber_cli import init_database
+
+db_path = init_database("sqlite:////Users/name/data/nber.db")
+print(db_path)
+```
+
 获取 NBER RSS feed 并显示新的缓存条目：
 
 ```python
@@ -237,11 +246,11 @@ print(f"Deleted: {result.deleted_count}")
 
 ## 数据库与日志辅助函数
 
-这些辅助函数属于顶层公共 API，可以在用户代码中安全调用。它们包装了 `info`、`search`、`download` 和 `feed` 内部使用的 SQLite 层。日志与缓存写入采用“软失败”策略：数据库异常发生时，函数会向 `stderr` 输出一行 warning（对于记录器返回 `None`），而不会抛出异常，因此不会打断调用方的主命令。缓存读取器在数据库局部错误下返回 `None` 或 `0`。需要更强保证的调用方应直接使用 SQLite。
+这些辅助函数属于顶层公共 API，可以在用户代码中安全调用。它们通过 SQLModel/SQLAlchemy 包装了 `info`、`search`、`download` 和 `feed` 内部使用的本地 SQLite 数据库。日志与缓存写入采用“软失败”策略：数据库异常发生时，函数会向 `stderr` 输出一行 warning（对于记录器返回 `None`），而不会抛出异常，因此不会打断调用方的主命令。缓存读取器在数据库局部错误下返回 `None` 或 `0`。需要更强保证的调用方可以直接检查解析后的本地数据库路径。
 
 ### `get_database_path(db_path=None) -> Path`
 
-返回解析后的 SQLite 数据库路径。当 `db_path` 为 `None` 时，NBER-CLI 优先使用 `~/.nber-cli/config.json` 中配置的路径，回退到默认 `~/.nber-cli/nber.db`，在文件存在时回退到旧版 `~/.nber-cli/feed.db`。返回值始终是绝对路径。**不要求**该数据库文件实际存在。
+返回解析后的 SQLite 数据库路径。`db_path` 可以是 `Path`、文件路径字符串，也可以是 `sqlite:///...` URL。当 `db_path` 为 `None` 时，NBER-CLI 优先使用 `~/.nber-cli/config.json` 中配置的位置，回退到默认 `~/.nber-cli/nber.db`，在文件存在时回退到旧版 `~/.nber-cli/feed.db`。即使输入是 SQLite URL，返回值也始终是绝对路径。**不要求**该数据库文件实际存在。
 
 ### `get_schema_version(db_path=None) -> int`
 
@@ -324,7 +333,7 @@ print(f"Deleted: {result.deleted_count}")
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `source_url` | `str` | RSS feed URL。 |
-| `database_path` | `Path` | SQLite 缓存数据库路径。 |
+| `database_path` | `Path` | 解析后的本地 SQLite 缓存数据库路径。 |
 | `total_fetched` | `int` | 本次获取到的 RSS 条目数量。 |
 | `new_count` | `int` | 本次获取到且缓存中原本不存在的条目数量。 |
 | `display_all` | `bool` | 返回条目是否包含所有获取到的条目。 |
@@ -335,7 +344,7 @@ print(f"Deleted: {result.deleted_count}")
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| `database_path` | `Path` | SQLite 缓存数据库路径。 |
+| `database_path` | `Path` | 解析后的本地 SQLite 缓存数据库路径。 |
 | `matched_count` | `int` | 符合清理条件的缓存记录数量。 |
 | `deleted_count` | `int` | 已删除的缓存记录数量。 |
 | `mode` | `str` | 清理模式：`days`、`all` 或 `date-range`。 |
@@ -348,7 +357,7 @@ print(f"Deleted: {result.deleted_count}")
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
-| `database_path` | `Path` | SQLite 缓存数据库路径。 |
+| `database_path` | `Path` | 解析后的本地 SQLite 缓存数据库路径。 |
 | `matched_count` | `int` | 符合清理条件的缓存记录数量。 |
 | `deleted_count` | `int` | 已删除的缓存记录数量。 |
 | `mode` | `str` | 清理模式：`days`、`all` 或 `date-range`。 |
@@ -451,7 +460,7 @@ from nber_cli.formatters import feed_results_text, info_text, search_results_tex
 | 字段 | 类型 | 备注 |
 | --- | --- | --- |
 | `source_url` | `str` | 本次抓取的 RSS feed URL。 |
-| `database_path` | `str` | 写入条目的 SQLite 数据库绝对路径。 |
+| `database_path` | `str` | 写入条目的本地 SQLite 数据库解析后绝对路径。 |
 | `total_fetched` | `int` | 本次从 feed 解析出的条目数。 |
 | `new_count` | `int` | 本地缓存中原本不存在的条目数。 |
 | `display_all` | `bool` | `results` 包含全部条目时为 `true`；只包含新条目时为 `false`。 |

{nber_cli-0.5.0 → nber_cli-0.6.0}/plugins/nber-cli/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "nber-cli",
   "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "author": {
     "name": "Song Tan",
     "email": "sepinetam@gmail.com"

{nber_cli-0.5.0 → nber_cli-0.6.0}/plugins/nber-cli/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nber-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
   "author": {
     "name": "Song Tan",