first commit

README.md

@@ -0,0 +1,57 @@
+# 探数新闻下载器
+
+在本机浏览器中填写 API Key、获取频道、选择数量，下载新闻正文和图片。所有项目文件与下载结果都位于本目录，不修改微信下载器。
+
+## 启动
+
+安装 `uv` 后，macOS 可以双击 `start.command`。也可以在本目录运行：
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python app.py
+```
+
+启动后自动打开 http://127.0.0.1:8765 。保留启动窗口，退出时按 Ctrl+C。端口被占用时加 `--port 8766`；不自动打开浏览器时加 `--no-browser`。
+
+1. 填写探数 API Key，点击「获取新闻频道」。频道来自真实接口，不使用写死的列表。
+2. 选择频道、输入目标数量，点击「开始下载」。
+3. 页面显示成功保存的数量、百分比、重复数、失败数和最近 300 条日志。日志固定高度，可滚动；向上查看时不会强制滚回底部。
+4. 下载结果保存在本目录的 `downloads` 文件夹。点击「停止下载」后，等待当前请求或文章保存结束。
+5. 「调试终端」默认折叠，支持频道查询以及列表查询的 `type`、`num`、`start` 参数。测试请求只显示响应，不保存文章；同样消耗 API 调用额度。输出最多保留 100000 字符。
+
+密钥仅在页面和服务运行内存中使用，不保存到配置、历史数据库或浏览器存储。服务仅监听本机地址。刷新页面可查看当前任务进度，开始新任务需重新填写密钥。单个服务同时只运行一个下载任务，请勿同时启动多个实例操作同一下载目录。
+
+## 保存格式
+
+沿用 `wechat_official_acc_article_downloader` 的格式和图片处理规则：
+
+```text
+downloads/
+├── .history.sqlite3
+└── 新闻标题/
+    ├── 新闻标题.md
+    ├── image001.jpg
+    └── image002.png
+```
+
+Markdown 开头是一级标题，空行后直接接由接口 `content` 转换的正文，不额外添加接口 `time` 对应的发布时间或分隔线。末尾为 `来源：{src}，如有侵权，请联系删除。`，来源为空时使用「未知作者」。不在开头添加原文链接或作者。正文中的图片下载到同一目录、使用相对引用、按真实文件类型命名，同一图片地址只下载一次。接口的 `pic` 封面不单独插入正文。
+
+标题中的不合法字符会替换；不同文章碰巧同名时添加 ` (2)` 等后缀，目录和 Markdown 文件保持同名。任何正文图片下载失败，该篇不计入完成数，并清理半成品，再继续其他新闻；下次任务可以重试。
+
+## 去重与分页
+
+- 下载图片前，检查原文 URL / PC URL（移除常见跟踪参数和片段）及规范化正文指纹。任一匹配即跳过，标题相同但正文和网址不同不会单凭标题去重。
+- SQLite 保存成功文章的指纹，跨任务、跨频道和服务重启后继续去重。被删除的文章目录不会阻止重新下载。不要删除 `.history.sqlite3`，否则会失去对应历史记录。
+- 每次任务从最新位置 `start=0` 开始，按返回数量推进，每页最多 40 条；重复和失败不计入成功数量，并继续后面的新闻。
+- 接口限制 `start ≤ 400`，一次任务最多覆盖约 440 条，具体还受返回数量和实时更新影响。达到分页边界或收到空列表时停止，未达目标就显示「未达到目标」，不会伪装成 100%。
+- 列表接口不自动重试，防止隐蔽消耗计费额度。API 业务错误、网络错误或响应格式错误会中断任务，已成功保存的文章保留。图片请求沿用原下载器的重试策略。
+- 新闻列表会实时变化，无法保证服务器在不同请求中不返回同一新闻；本工具在保存前去重，尽量避免重复图片下载与文件保存。
+
+接口依据：[探数官方新闻 API 文档](https://www.tanshuapi.com/market/detail-85)。
+
+## 验证
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python -m unittest discover -s tests -v
+```
+
+测试使用模拟新闻响应与临时目录，不消耗真实 API 额度。覆盖格式与图片引用、图片失败清理、历史去重、分页边界、失败重试、取消、日志上限和本地 HTTP 接口。真实账号权限、余额、返回内容与远程图片可达性，需要在页面填入有效 Key 后验证。