nber-cli 0.3.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. {nber_cli-0.3.0 → nber_cli-0.3.1}/CHANGELOG.md +13 -0
  2. {nber_cli-0.3.0 → nber_cli-0.3.1}/PKG-INFO +1 -1
  3. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/changelog.md +15 -0
  4. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/cli.md +36 -24
  5. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/configuration.md +23 -14
  6. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/getting-started.md +2 -2
  7. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/python-api.md +21 -7
  8. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/changelog.md +15 -0
  9. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/cli.md +36 -24
  10. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/configuration.md +22 -13
  11. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/getting-started.md +2 -2
  12. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/python-api.md +21 -7
  13. {nber_cli-0.3.0 → nber_cli-0.3.1}/pyproject.toml +1 -1
  14. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/__init__.py +24 -2
  15. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/cli.py +45 -18
  16. nber_cli-0.3.1/src/nber_cli/db.py +495 -0
  17. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/feed.py +21 -141
  18. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/mcp.py +8 -1
  19. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/conftest.py +12 -0
  20. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/test_cli.py +28 -28
  21. nber_cli-0.3.1/tests/test_db.py +205 -0
  22. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/test_feed.py +9 -9
  23. nber_cli-0.3.1/tests/test_info_cache.py +148 -0
  24. nber_cli-0.3.1/tests/test_logs.py +121 -0
  25. {nber_cli-0.3.0 → nber_cli-0.3.1}/uv.lock +1 -1
  26. {nber_cli-0.3.0 → nber_cli-0.3.1}/.claude/agents/code-to-docs.md +0 -0
  27. {nber_cli-0.3.0 → nber_cli-0.3.1}/.claude/agents/sync-docs-for-i18n.md +0 -0
  28. {nber_cli-0.3.0 → nber_cli-0.3.1}/.claude/settings.json +0 -0
  29. {nber_cli-0.3.0 → nber_cli-0.3.1}/.claude-plugin/marketplace.json +0 -0
  30. {nber_cli-0.3.0 → nber_cli-0.3.1}/.codex/config.toml +0 -0
  31. {nber_cli-0.3.0 → nber_cli-0.3.1}/.github/workflows/docs.yml +0 -0
  32. {nber_cli-0.3.0 → nber_cli-0.3.1}/.github/workflows/lint.yml +0 -0
  33. {nber_cli-0.3.0 → nber_cli-0.3.1}/.github/workflows/publish.yml +0 -0
  34. {nber_cli-0.3.0 → nber_cli-0.3.1}/.github/workflows/pytest.yml +0 -0
  35. {nber_cli-0.3.0 → nber_cli-0.3.1}/.gitignore +0 -0
  36. {nber_cli-0.3.0 → nber_cli-0.3.1}/.mcp.json +0 -0
  37. {nber_cli-0.3.0 → nber_cli-0.3.1}/.python-version +0 -0
  38. {nber_cli-0.3.0 → nber_cli-0.3.1}/LICENSE +0 -0
  39. {nber_cli-0.3.0 → nber_cli-0.3.1}/README.md +0 -0
  40. {nber_cli-0.3.0 → nber_cli-0.3.1}/README.zh-CN.md +0 -0
  41. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/agents/claude-code.md +0 -0
  42. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/agents/codex.md +0 -0
  43. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/agents/index.md +0 -0
  44. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/agents/openclaw.md +0 -0
  45. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/agents/others.md +0 -0
  46. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/contributing.md +0 -0
  47. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/development.md +0 -0
  48. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/index.md +0 -0
  49. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/mcp.md +0 -0
  50. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/en/policy.md +0 -0
  51. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/agents/claude-code.md +0 -0
  52. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/agents/codex.md +0 -0
  53. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/agents/index.md +0 -0
  54. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/agents/openclaw.md +0 -0
  55. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/agents/others.md +0 -0
  56. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/contributing.md +0 -0
  57. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/development.md +0 -0
  58. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/index.md +0 -0
  59. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/mcp.md +0 -0
  60. {nber_cli-0.3.0 → nber_cli-0.3.1}/docs/zh/policy.md +0 -0
  61. {nber_cli-0.3.0 → nber_cli-0.3.1}/mkdocs.yml +0 -0
  62. {nber_cli-0.3.0 → nber_cli-0.3.1}/plugins/nber-cli/.claude-plugin/plugin.json +0 -0
  63. {nber_cli-0.3.0 → nber_cli-0.3.1}/plugins/nber-cli/.codex-plugin/plugin.json +0 -0
  64. {nber_cli-0.3.0 → nber_cli-0.3.1}/plugins/nber-cli/.mcp.json +0 -0
  65. {nber_cli-0.3.0 → nber_cli-0.3.1}/plugins/nber-cli/skills/NBER-CLI/SKILL.md +0 -0
  66. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/__main__.py +0 -0
  67. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/config.py +0 -0
  68. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/core/__init__.py +0 -0
  69. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/core/models.py +0 -0
  70. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/download.py +0 -0
  71. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/fetcher.py +0 -0
  72. {nber_cli-0.3.0 → nber_cli-0.3.1}/src/nber_cli/formatters.py +0 -0
  73. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/__init__.py +0 -0
  74. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/test_downloader.py +0 -0
  75. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/test_fetcher.py +0 -0
  76. {nber_cli-0.3.0 → nber_cli-0.3.1}/tests/test_main.py +0 -0
@@ -2,6 +2,19 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.3.1] - 2026-06-03
6
+
7
+ ### Added
8
+ - `db init` and `db migrate` top-level subcommands replace `feed init` and `feed migrate`. The database is now general-purpose and stores feed cache, behavior logs, and paper metadata cache.
9
+ - `info_cache` table caches paper metadata fetched via `info` and the MCP `get_paper_info` tool. Subsequent lookups return immediately from the cache.
10
+ - `query_log`, `download_log`, and `info_log` tables record search keywords, download outcomes, and paper info lookups for later auditing.
11
+ - `schema_version` field written to `~/.nber-cli/config.json` so future schema migrations can roll forward safely.
12
+
13
+ ### Changed
14
+ - Default database renamed from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations continue to work without manual steps.
15
+ - Database schema upgraded from `user_version = 1` to `user_version = 2`. Existing v1 databases are upgraded automatically on next CLI invocation; original `feed_items` rows are preserved.
16
+ - Database code consolidated into `nber_cli.db`. The original `init_feed_database`, `migrate_feed_database`, and `get_feed_database_path` helpers are kept as thin compatibility wrappers.
17
+
5
18
  ## [0.3.0] - 2026-06-03
6
19
 
7
20
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: nber-cli
3
- Version: 0.3.0
3
+ Version: 0.3.1
4
4
  Summary: A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
5
5
  Project-URL: Homepage, https://github.com/sepinetam/nber-cli
6
6
  Project-URL: Repository, https://github.com/sepinetam/nber-cli
@@ -2,6 +2,21 @@
2
2
 
3
3
  All notable changes to this project will be documented here.
4
4
 
5
+ ## 0.3.1 - 2026-06-03
6
+
7
+ ### Added
8
+
9
+ - Added `nber-cli db init` and `nber-cli db migrate` for initializing and relocating the local database. These replace `feed init` and `feed migrate`.
10
+ - Added `info_cache` table so repeated `nber-cli info` and MCP `get_paper_info` calls return immediately from cache.
11
+ - Added `query_log`, `download_log`, and `info_log` tables for recording search keywords, download outcomes, and info lookups.
12
+ - Added `schema_version` field in `~/.nber-cli/config.json` for forward-compatible schema upgrades.
13
+
14
+ ### Changed
15
+
16
+ - Renamed default database file from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations keep working without manual steps.
17
+ - Upgraded database schema from version 1 to version 2 with automatic upgrade on next invocation.
18
+ - Consolidated database code into `nber_cli.db`. Old `init_feed_database` and `migrate_feed_database` helpers remain as thin compatibility wrappers.
19
+
5
20
  ## 0.3.0 - 2026-06-03
6
21
 
7
22
  ### Added
@@ -22,6 +22,7 @@ Running `nber-cli` without a subcommand prints the top-level help and exits succ
22
22
  | `download` | Download one or more paper PDFs. |
23
23
  | `info` | Show metadata and abstract for one paper. |
24
24
  | `search` | Search NBER working papers. |
25
+ | `db` | Manage the local SQLite database. |
25
26
  | `feed` | Manage the NBER new working papers RSS feed cache. |
26
27
  | `mcp-server` | Start the MCP server for agents. |
27
28
 
@@ -142,18 +143,7 @@ When only `--start-date` is provided, NBER-CLI automatically uses the current da
142
143
 
143
144
  ## feed
144
145
 
145
- `feed` works with NBER's new working papers RSS feed and a local SQLite cache. The cache tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
146
-
147
- ### feed init
148
-
149
- Initialize the feed cache database and write the database path to the user config:
150
-
151
- ```bash
152
- nber-cli feed init
153
- nber-cli feed init --db-path ~/.nber-cli/feed.db
154
- ```
155
-
156
- If `--db-path` is omitted, the default database path is `~/.nber-cli/feed.db`.
146
+ `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.
157
147
 
158
148
  ### feed fetch
159
149
 
@@ -185,16 +175,6 @@ nber-cli feed fetch --format json
185
175
  nber-cli feed fetch -f json
186
176
  ```
187
177
 
188
- ### feed migrate
189
-
190
- Move the feed cache database to a new path and update the user config:
191
-
192
- ```bash
193
- nber-cli feed migrate ~/data/nber-feed.db
194
- ```
195
-
196
- Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
197
-
198
178
  ### feed clean
199
179
 
200
180
  Clean cached feed database records. This deletes records from the local cache, not from NBER. Deleted cache records may be fetched again as new items if they still appear in the RSS feed.
@@ -235,16 +215,48 @@ Only `y` or `Y` continues. Any other response aborts without deleting records.
235
215
 
236
216
  | Subcommand | Option | Description |
237
217
  | --- | --- | --- |
238
- | `init` | `--db-path` | SQLite cache database path. Defaults to `~/.nber-cli/feed.db`. |
239
218
  | `fetch` | `--display-all [true|false]` | Display all fetched RSS items instead of only new items. |
240
219
  | `fetch` | `--format`, `-f` | Output format: `list` or `json`. Defaults to `list`. |
241
220
  | `fetch` | `--max-items` | Maximum number of feed items to display. |
242
- | `migrate` | `new_db_path` | New SQLite cache database path. |
243
221
  | `clean` | `--days` | Clean cached records not seen for this many days. Defaults to `30`. |
244
222
  | `clean` | `--all` | Clean all cached feed records. |
245
223
  | `clean` | `--start-date` | Clean cached records last seen on or after this date, formatted `YYYY-MM-DD`. |
246
224
  | `clean` | `--end-date` | Clean cached records last seen on or before this date, formatted `YYYY-MM-DD`. |
247
225
 
226
+ ## db
227
+
228
+ `db` manages the local SQLite database used by `info`, `search`, `download`, and `feed` for cache and behavior logs.
229
+
230
+ ### db init
231
+
232
+ Initialize the database and write its path to the user config:
233
+
234
+ ```bash
235
+ nber-cli db init
236
+ nber-cli db init --db-path ~/.nber-cli/nber.db
237
+ ```
238
+
239
+ If `--db-path` is omitted, the default database path is `~/.nber-cli/nber.db`.
240
+
241
+ If an existing `~/.nber-cli/feed.db` from 0.3.0 is present and no `nber.db` exists yet, NBER-CLI uses that legacy file in place. Schema is automatically upgraded from version 1 to version 2 on first use.
242
+
243
+ ### db migrate
244
+
245
+ Move the database to a new path and update the user config:
246
+
247
+ ```bash
248
+ nber-cli db migrate ~/data/nber.db
249
+ ```
250
+
251
+ Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
252
+
253
+ ### db Options
254
+
255
+ | Subcommand | Option | Description |
256
+ | --- | --- | --- |
257
+ | `init` | `--db-path` | SQLite database path. Defaults to `~/.nber-cli/nber.db`. |
258
+ | `migrate` | `new_db_path` | New SQLite database path. |
259
+
248
260
  ## mcp-server
249
261
 
250
262
  Start the default stdio MCP server:
@@ -1,6 +1,6 @@
1
1
  # Configuration
2
2
 
3
- Most NBER-CLI runtime behavior uses built-in defaults. The feed cache also uses a small user config file to remember the SQLite database path selected by `nber-cli feed init` or `nber-cli feed migrate`.
3
+ 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`.
4
4
 
5
5
  ## Runtime Defaults
6
6
 
@@ -23,45 +23,54 @@ The user config file is:
23
23
  ~/.nber-cli/config.json
24
24
  ```
25
25
 
26
- At the moment, the config file is used for feed cache settings:
26
+ Current schema:
27
27
 
28
28
  ```json
29
29
  {
30
+ "schema_version": 2,
30
31
  "feed": {
31
- "db-path": "/Users/name/.nber-cli/feed.db"
32
+ "db-path": "/Users/name/.nber-cli/nber.db"
32
33
  }
33
34
  }
34
35
  ```
35
36
 
36
- `feed.db-path` points to the SQLite database used by `nber-cli feed fetch` and `nber-cli feed clean`.
37
+ `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.
37
38
 
38
- ## Feed Cache Database
39
+ `schema_version` records the current database schema version. NBER-CLI updates it after `db init` or schema upgrades.
39
40
 
40
- Default feed cache database path:
41
+ ## Local Database
42
+
43
+ Default database path:
41
44
 
42
45
  ```text
43
- ~/.nber-cli/feed.db
46
+ ~/.nber-cli/nber.db
44
47
  ```
45
48
 
46
- Initialize the default cache:
49
+ Initialize the default database:
47
50
 
48
51
  ```bash
49
- nber-cli feed init
52
+ nber-cli db init
50
53
  ```
51
54
 
52
- Initialize a cache at a custom path:
55
+ Initialize at a custom path:
53
56
 
54
57
  ```bash
55
- nber-cli feed init --db-path ~/data/nber-feed.db
58
+ nber-cli db init --db-path ~/data/nber.db
56
59
  ```
57
60
 
58
- Move an existing cache and update the config:
61
+ Move an existing database and update the config:
59
62
 
60
63
  ```bash
61
- nber-cli feed migrate ~/data/nber-feed.db
64
+ nber-cli db migrate ~/data/nber.db
62
65
  ```
63
66
 
64
- The feed cache stores RSS items that have already been seen. `feed fetch` uses this cache to decide which items are new. `feed clean` deletes records from this local cache; if deleted records still appear in the RSS feed, they may be fetched again as new items.
67
+ If you upgraded from 0.3.0 and still have `~/.nber-cli/feed.db`, NBER-CLI will keep using that legacy file when no `nber.db` is present. The schema is upgraded automatically on first invocation.
68
+
69
+ The database holds:
70
+
71
+ - `feed_items` and `feed_fetches`: RSS cache used by `feed fetch` and `feed clean`.
72
+ - `info_cache`: paper metadata cache used by `info` and the MCP `get_paper_info` tool.
73
+ - `query_log`, `download_log`, `info_log`: behavior logs for search keywords, download outcomes, and info lookups.
65
74
 
66
75
  ## Output Paths
67
76
 
@@ -75,10 +75,10 @@ nber-cli info w25000 --all
75
75
 
76
76
  ## Follow New Papers with the Feed Cache
77
77
 
78
- Initialize the local RSS feed cache:
78
+ Initialize the local database:
79
79
 
80
80
  ```bash
81
- nber-cli feed init
81
+ nber-cli db init
82
82
  ```
83
83
 
84
84
  Fetch the NBER new working papers RSS feed:
@@ -92,14 +92,14 @@ async def main() -> None:
92
92
  asyncio.run(main())
93
93
  ```
94
94
 
95
- ## Work with the Feed Cache
95
+ ## Work with the Local Database
96
96
 
97
- Initialize the default feed cache:
97
+ Initialize the default database:
98
98
 
99
99
  ```python
100
- from nber_cli import init_feed_database
100
+ from nber_cli import init_database
101
101
 
102
- db_path = init_feed_database()
102
+ db_path = init_database()
103
103
  print(db_path)
104
104
  ```
105
105
 
@@ -123,14 +123,14 @@ from nber_cli import fetch_feed
123
123
  result = fetch_feed(display_all=True, max_items=5)
124
124
  ```
125
125
 
126
- Move the feed cache database:
126
+ Move the database:
127
127
 
128
128
  ```python
129
129
  from pathlib import Path
130
130
 
131
- from nber_cli import migrate_feed_database
131
+ from nber_cli import migrate_database
132
132
 
133
- old_path, new_path = migrate_feed_database(Path("~/data/nber-feed.db"))
133
+ old_path, new_path = migrate_database(Path("~/data/nber.db"))
134
134
  ```
135
135
 
136
136
  Clean cached feed database records:
@@ -147,6 +147,20 @@ print(result.deleted_count)
147
147
 
148
148
  `clean_feed_cache` deletes local cache records only. If deleted records still appear in the RSS feed, a later `fetch_feed` call may return them as new items again.
149
149
 
150
+ Read or write the paper metadata cache directly:
151
+
152
+ ```python
153
+ from nber_cli import read_info_cache, write_info_cache
154
+ from nber_cli import get_nber
155
+ import asyncio
156
+
157
+ paper = read_info_cache(None, "w25000")
158
+ if paper is None:
159
+ paper = asyncio.run(get_nber(25000))
160
+ write_info_cache(None, paper)
161
+ print(paper.title)
162
+ ```
163
+
150
164
  ## Data Models
151
165
 
152
166
  ### NBER
@@ -2,6 +2,21 @@
2
2
 
3
3
  这里记录项目的重要变更。
4
4
 
5
+ ## 0.3.1 - 2026-06-03
6
+
7
+ ### Added
8
+
9
+ - 添加 `nber-cli db init` 和 `nber-cli db migrate`,用于初始化和迁移本地数据库,替代原先的 `feed init` 和 `feed migrate`。
10
+ - 添加 `info_cache` 表,重复执行 `nber-cli info` 或 MCP `get_paper_info` 时直接从缓存返回。
11
+ - 添加 `query_log`、`download_log`、`info_log` 表,记录搜索关键词、下载结果和 info 查询。
12
+ - 在 `~/.nber-cli/config.json` 中写入 `schema_version` 字段,便于后续的 schema 升级。
13
+
14
+ ### Changed
15
+
16
+ - 默认数据库文件从 `feed.db` 改名为 `nber.db`。已经安装了 `~/.nber-cli/feed.db` 的用户无需手动迁移。
17
+ - 数据库 schema 从版本 1 升级到版本 2,下次启动时自动完成升级。
18
+ - 公共数据库代码迁移到 `nber_cli.db`,原先的 `init_feed_database` 和 `migrate_feed_database` 作为薄薄的兼容层保留。
19
+
5
20
  ## 0.3.0 - 2026-06-03
6
21
 
7
22
  ### Added
@@ -22,6 +22,7 @@ nber-cli [--version] <command> [options]
22
22
  | `download` | 下载一篇或多篇论文 PDF。 |
23
23
  | `info` | 显示单篇论文的元数据和摘要。 |
24
24
  | `search` | 搜索 NBER 工作论文。 |
25
+ | `db` | 管理本地 SQLite 数据库。 |
25
26
  | `feed` | 管理 NBER 最新工作论文 RSS feed 的本地缓存。 |
26
27
  | `mcp-server` | 启动给 Agent 使用的 MCP server。 |
27
28
 
@@ -142,18 +143,7 @@ nber-cli search "inflation" -f json
142
143
 
143
144
  ## feed
144
145
 
145
- `feed` 用于处理 NBER 最新工作论文 RSS feed 和本地 SQLite 缓存。缓存会记录哪些 RSS 条目已经见过,因此 `feed fetch` 默认只显示新发现的论文。
146
-
147
- ### feed init
148
-
149
- 初始化 feed 缓存数据库,并把数据库路径写入用户配置:
150
-
151
- ```bash
152
- nber-cli feed init
153
- nber-cli feed init --db-path ~/.nber-cli/feed.db
154
- ```
155
-
156
- 如果省略 `--db-path`,默认数据库路径是 `~/.nber-cli/feed.db`。
146
+ `feed` 用于处理 NBER 最新工作论文 RSS feed 和本地 SQLite 数据库。数据库会记录哪些 RSS 条目已经见过,因此 `feed fetch` 默认只显示新发现的论文。
157
147
 
158
148
  ### feed fetch
159
149
 
@@ -185,16 +175,6 @@ nber-cli feed fetch --format json
185
175
  nber-cli feed fetch -f json
186
176
  ```
187
177
 
188
- ### feed migrate
189
-
190
- 移动 feed 缓存数据库到新路径,并更新用户配置:
191
-
192
- ```bash
193
- nber-cli feed migrate ~/data/nber-feed.db
194
- ```
195
-
196
- 迁移会移动 SQLite 数据库文件,以及 `-wal`、`-shm`、`-journal` 等 SQLite sidecar 文件。目标路径不能已经存在。
197
-
198
178
  ### feed clean
199
179
 
200
180
  清理 feed 缓存数据库记录。这个操作删除的是本地缓存记录,不会影响 NBER。被删除的缓存记录如果仍然出现在 RSS feed 中,后续可能会再次作为新条目被获取。
@@ -235,16 +215,48 @@ Continue? [y/N]:
235
215
 
236
216
  | 子命令 | 选项 | 说明 |
237
217
  | --- | --- | --- |
238
- | `init` | `--db-path` | SQLite 缓存数据库路径,默认是 `~/.nber-cli/feed.db`。 |
239
218
  | `fetch` | `--display-all [true|false]` | 显示所有获取到的 RSS 条目,而不是只显示新条目。 |
240
219
  | `fetch` | `--format`, `-f` | 输出格式:`list` 或 `json`,默认是 `list`。 |
241
220
  | `fetch` | `--max-items` | 最多显示多少个 feed 条目。 |
242
- | `migrate` | `new_db_path` | 新的 SQLite 缓存数据库路径。 |
243
221
  | `clean` | `--days` | 清理这么多天没有再次出现的缓存记录,默认是 `30`。 |
244
222
  | `clean` | `--all` | 清理全部 feed 缓存记录。 |
245
223
  | `clean` | `--start-date` | 清理 last-seen 日期在该日期及之后的缓存记录,格式为 `YYYY-MM-DD`。 |
246
224
  | `clean` | `--end-date` | 清理 last-seen 日期在该日期及之前的缓存记录,格式为 `YYYY-MM-DD`。 |
247
225
 
226
+ ## db
227
+
228
+ `db` 用于管理本地 SQLite 数据库,`info`、`search`、`download` 和 `feed` 会用这个数据库存放缓存和行为日志。
229
+
230
+ ### db init
231
+
232
+ 初始化数据库,并把数据库路径写入用户配置:
233
+
234
+ ```bash
235
+ nber-cli db init
236
+ nber-cli db init --db-path ~/.nber-cli/nber.db
237
+ ```
238
+
239
+ 如果省略 `--db-path`,默认数据库路径是 `~/.nber-cli/nber.db`。
240
+
241
+ 如果用户原来使用 0.3.0 留下的 `~/.nber-cli/feed.db`,并且还没有 `nber.db`,NBER-CLI 会沿用这个旧文件。首次使用时 schema 会自动从版本 1 升级到版本 2。
242
+
243
+ ### db migrate
244
+
245
+ 把数据库移到新路径并更新用户配置:
246
+
247
+ ```bash
248
+ nber-cli db migrate ~/data/nber.db
249
+ ```
250
+
251
+ 迁移会移动 SQLite 数据库文件,以及 `-wal`、`-shm`、`-journal` 等 SQLite sidecar 文件。目标路径不能已经存在。
252
+
253
+ ### db 选项
254
+
255
+ | 子命令 | 选项 | 说明 |
256
+ | --- | --- | --- |
257
+ | `init` | `--db-path` | SQLite 数据库路径,默认是 `~/.nber-cli/nber.db`。 |
258
+ | `migrate` | `new_db_path` | 新的 SQLite 数据库路径。 |
259
+
248
260
  ## mcp-server
249
261
 
250
262
  启动默认 stdio MCP server:
@@ -1,6 +1,6 @@
1
1
  # 配置
2
2
 
3
- NBER-CLI 的大多数运行时行为使用内置默认值。feed 缓存还会使用一个小型用户配置文件,用来记住 `nber-cli feed init` 或 `nber-cli feed migrate` 选择的 SQLite 数据库路径。
3
+ NBER-CLI 的大多数运行时行为使用内置默认值。本地数据库还会使用一个小型用户配置文件,用来记住 `nber-cli db init` 或 `nber-cli db migrate` 选择的 SQLite 数据库路径。
4
4
 
5
5
  ## 运行时默认值
6
6
 
@@ -23,45 +23,54 @@ NBER-CLI 的大多数运行时行为使用内置默认值。feed 缓存还会使
23
23
  ~/.nber-cli/config.json
24
24
  ```
25
25
 
26
- 目前配置文件用于 feed 缓存设置:
26
+ 当前结构:
27
27
 
28
28
  ```json
29
29
  {
30
+ "schema_version": 2,
30
31
  "feed": {
31
- "db-path": "/Users/name/.nber-cli/feed.db"
32
+ "db-path": "/Users/name/.nber-cli/nber.db"
32
33
  }
33
34
  }
34
35
  ```
35
36
 
36
- `feed.db-path` 指向 `nber-cli feed fetch` 和 `nber-cli feed clean` 使用的 SQLite 数据库。
37
+ `feed.db-path` 指向 `info`、`search`、`download` 和 `feed` 都会使用的 SQLite 数据库。`feed` 这个 key 名称保留以保持向后兼容,数据库本身是通用的。
37
38
 
38
- ## Feed 缓存数据库
39
+ `schema_version` 记录当前数据库 schema 的版本。NBER-CLI 在 `db init` 或 schema 升级后更新该字段。
39
40
 
40
- 默认 feed 缓存数据库路径:
41
+ ## 本地数据库
42
+
43
+ 默认数据库路径:
41
44
 
42
45
  ```text
43
- ~/.nber-cli/feed.db
46
+ ~/.nber-cli/nber.db
44
47
  ```
45
48
 
46
- 初始化默认缓存:
49
+ 初始化默认数据库:
47
50
 
48
51
  ```bash
49
- nber-cli feed init
52
+ nber-cli db init
50
53
  ```
51
54
 
52
55
  初始化到自定义路径:
53
56
 
54
57
  ```bash
55
- nber-cli feed init --db-path ~/data/nber-feed.db
58
+ nber-cli db init --db-path ~/data/nber.db
56
59
  ```
57
60
 
58
- 移动已有缓存并更新配置:
61
+ 移动已有数据库并更新配置:
59
62
 
60
63
  ```bash
61
- nber-cli feed migrate ~/data/nber-feed.db
64
+ nber-cli db migrate ~/data/nber.db
62
65
  ```
63
66
 
64
- feed 缓存会存储已经见过的 RSS 条目。`feed fetch` 使用这个缓存判断哪些条目是新的。`feed clean` 删除的是本地缓存记录;如果被删除的记录仍然出现在 RSS feed 中,后续可能会再次作为新条目被获取。
67
+ 如果你从 0.3.0 升级过来,本地还存有 `~/.nber-cli/feed.db`,在没有 `nber.db` 的情况下 NBER-CLI 会继续使用这个旧文件。首次运行时会自动完成 schema 升级。
68
+
69
+ 数据库包含以下内容:
70
+
71
+ - `feed_items` 和 `feed_fetches`:`feed fetch` 和 `feed clean` 使用的 RSS 缓存。
72
+ - `info_cache`:`info` 和 MCP `get_paper_info` 工具使用的论文元数据缓存。
73
+ - `query_log`、`download_log`、`info_log`:搜索关键词、下载结果和 info 查询的行为日志。
65
74
 
66
75
  ## 输出路径
67
76
 
@@ -75,10 +75,10 @@ nber-cli info w25000 --all
75
75
 
76
76
  ## 用 Feed 缓存跟踪新论文
77
77
 
78
- 初始化本地 RSS feed 缓存:
78
+ 初始化本地数据库:
79
79
 
80
80
  ```bash
81
- nber-cli feed init
81
+ nber-cli db init
82
82
  ```
83
83
 
84
84
  获取 NBER 最新工作论文 RSS feed:
@@ -92,14 +92,14 @@ async def main() -> None:
92
92
  asyncio.run(main())
93
93
  ```
94
94
 
95
- ## 使用 Feed 缓存
95
+ ## 使用本地数据库
96
96
 
97
- 初始化默认 feed 缓存:
97
+ 初始化默认数据库:
98
98
 
99
99
  ```python
100
- from nber_cli import init_feed_database
100
+ from nber_cli import init_database
101
101
 
102
- db_path = init_feed_database()
102
+ db_path = init_database()
103
103
  print(db_path)
104
104
  ```
105
105
 
@@ -123,14 +123,14 @@ from nber_cli import fetch_feed
123
123
  result = fetch_feed(display_all=True, max_items=5)
124
124
  ```
125
125
 
126
- 移动 feed 缓存数据库:
126
+ 移动数据库:
127
127
 
128
128
  ```python
129
129
  from pathlib import Path
130
130
 
131
- from nber_cli import migrate_feed_database
131
+ from nber_cli import migrate_database
132
132
 
133
- old_path, new_path = migrate_feed_database(Path("~/data/nber-feed.db"))
133
+ old_path, new_path = migrate_database(Path("~/data/nber.db"))
134
134
  ```
135
135
 
136
136
  清理 feed 缓存数据库记录:
@@ -147,6 +147,20 @@ print(result.deleted_count)
147
147
 
148
148
  `clean_feed_cache` 只会删除本地缓存记录。如果被删除的记录仍然出现在 RSS feed 中,后续调用 `fetch_feed` 时它们可能会再次作为新条目返回。
149
149
 
150
+ 直接读写论文元数据缓存:
151
+
152
+ ```python
153
+ from nber_cli import read_info_cache, write_info_cache
154
+ from nber_cli import get_nber
155
+ import asyncio
156
+
157
+ paper = read_info_cache(None, "w25000")
158
+ if paper is None:
159
+ paper = asyncio.run(get_nber(25000))
160
+ write_info_cache(None, paper)
161
+ print(paper.title)
162
+ ```
163
+
150
164
  ## 数据模型
151
165
 
152
166
  ### NBER
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "nber-cli"
3
- version = "0.3.0"
3
+ version = "0.3.1"
4
4
  description = "A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -13,6 +13,18 @@ from .core.models import (
13
13
  NBERFeedItem,
14
14
  NBERSearchResults,
15
15
  )
16
+ from .db import (
17
+ get_database_path,
18
+ get_schema_version,
19
+ init_database,
20
+ migrate_database,
21
+ read_info_cache,
22
+ record_download,
23
+ record_info,
24
+ record_query,
25
+ touch_info_cache,
26
+ write_info_cache,
27
+ )
16
28
  from .download import download_multiple_papers, download_paper, download_paper_to_file
17
29
  from .feed import (
18
30
  clean_feed_cache,
@@ -25,11 +37,11 @@ from .fetcher import get_nber, search_nber
25
37
  from .formatters import feed_results, info, related, search_results
26
38
 
27
39
  __all__ = [
40
+ "DownloadBatchResult",
41
+ "DownloadFailure",
28
42
  "NBER",
29
43
  "NBERCLIConfig",
30
44
  "NBER_CLI_CONFIG",
31
- "DownloadBatchResult",
32
- "DownloadFailure",
33
45
  "NBERFeedCleanResult",
34
46
  "NBERFeedFetchResult",
35
47
  "NBERFeedItem",
@@ -40,13 +52,23 @@ __all__ = [
40
52
  "download_paper_to_file",
41
53
  "feed_results",
42
54
  "fetch_feed",
55
+ "get_database_path",
43
56
  "get_nber",
57
+ "get_schema_version",
58
+ "init_database",
44
59
  "init_feed_database",
45
60
  "info",
46
61
  "main",
62
+ "migrate_database",
47
63
  "migrate_feed_database",
48
64
  "parse_feed_xml",
65
+ "read_info_cache",
66
+ "record_download",
67
+ "record_info",
68
+ "record_query",
49
69
  "related",
50
70
  "search_nber",
51
71
  "search_results",
72
+ "touch_info_cache",
73
+ "write_info_cache",
52
74
  ]