first commit

README.md

@@ -0,0 +1,97 @@
+# 新闻工作台
+
+将新闻下载、文章打包、浏览器导入、排版与换号联动整合到本地控制台。
+
+**当前版本：0.1。可完成下载 → 入队 → 导入 → 排版 → 等待人工发表。结果页自动核对按用户决定暂留待接入；人工提交后会记录候选结果并暂停，不会自动计数、换号或处理下一篇。** 换号调度和计数接口已完成离线验证，完整在线链路仍需补齐结果页 HTML 后验证。
+
+## 启动
+
+双击本目录的 `start.command`，或在本目录运行：
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python app.py
+```
+
+默认打开 http://127.0.0.1:8770/ 。保留启动窗口，按 Ctrl+C 停止本地服务。修改端口使用 `--port 8772`；不自动打开浏览器使用 `--no-browser`。首次运行 uv 可能下载 Python 或依赖，后续可以复用缓存。
+
+页面必须通过本地服务打开，不要直接双击 `static/index.html`。Python 依赖仅用于下载和内容处理；浏览器脚本没有远程脚本依赖。
+
+## 浏览器安装与配对
+
+1. 在油猴安装控制台“浏览器连接”区域的两个脚本：
+   - `browser/local-bridge.user.js`：本地连接、配对与常驻终止按钮。
+   - `browser/auto-news.user.js`：导入、排版和任务执行。它由 `importer.js`、`formatter.js`、`runner.js` 构建。
+2. 停用旧的独立导入与排版油猴脚本，避免同一编辑器重复挂载。
+3. 换号插件仍由用户安装，位于项目根目录的 `dww11-account-switch-browser-extension/`，没有复制到本目录。本次在其 `content.js` 中增加了不含凭据的状态属性及终止事件监听。请在浏览器扩展管理页重新加载**这个原安装目录**，再刷新网站。旧 ZIP 未重新打包，不包含本次修改。
+4. 在控制台点击“显示本次连接码”。在论坛左下角“新闻工作台 · 本地连接”展开设置，填写端口和连接码并保存。
+5. 服务重启后连接码会改变，需要重新配对；任务和计数保留，但服务不会自动恢复运行。
+
+本机 HTTP 通信通过油猴特权请求完成，不要求论坛跨域开放本地服务。真实浏览器的脚本管理器配置、本地网络权限和网站编辑器兼容性仍需首次实机验证。配对码保存在油猴存储，不写入页面全局变量。下载 API Key 不进入文章包，不发给论坛。
+
+## 操作流程
+
+1. 填写 Key，获取频道、选择数量并下载。完整保存的文章会自动校验并进入队列；下载失败和入队失败分别显示，已保存的文章不因入队失败而删除。
+2. 也可展开“导入已有文章目录”，填写单篇目录或含多个文章子目录的根目录，点击检查。留空表示扫描本工具的 `downloads/`。扫描只处理根目录的一层文章子目录；文件须已完整落盘。
+3. 填写目标版块 `fid`、每账号最少/最多篇数和处理间隔。先核对历史发帖记录，再勾选确认并保存。版块和篇数不会替用户选择。
+4. 登录论坛，建议只保留一个执行标签。点击控制台“开始 / 继续”。执行器识别账号后领取一篇任务，进入指定新帖页、导入、排版，停止在人工审核阶段。
+5. 在论坛检查账号、版块、标题、图片位置、正文和来源，并亲手点击“发表帖子”。程序不调用发帖提交函数，不发送发帖请求，也不自动保存草稿。
+6. 当前版本会记录人工点击和提交快照，在跳转后的候选页面或等待超时后标记“发布结果待核对”并暂停。**需要补充结果页 HTML 后，才能自动核对受理结果并接续下一篇。**
+
+待补齐结果页自动核对后：审核中算网站已受理一次，但不算已确认公开；达到账号随机目标篇数且仍有待处理文章时，回首页调用插件换号，核对新 UID 与插件空闲状态后创建下一账号批次。没有待处理文章时直接结束，不为达到数量重发。
+
+## 终止、恢复与冲突
+
+- 网站左下角常驻“终止流程”，点击后立即取消本标签可取消的导入，并通知其他安装脚本的标签和换号插件；持久状态禁止继续领取任务。
+- 控制台“终止流程”还会停止下载，浏览器在下一次连接检查时停止（正常轮询约 2 秒）。网络断开时无法承诺固定延迟；网站按钮可立即停止本标签。已到达网站的图片、登录或发帖请求无法撤回。
+- 暂停/终止后必须明确点击“开始 / 继续”。下载停止等待当前网络请求/单篇保存结束，不伪装成已经撤回在途请求。
+- 非空编辑器、人工修改、账号变化、缺图、未知来源或上传失败会停在“需要处理”，不弹自动确认覆盖旧稿。
+- 导入中刷新后不会重新上传。先核对网站附件和草稿，再决定如何处理。若需要换标签，先在控制台暂停，再在目标标签点击“接管已暂停任务”。接管不会自动重新导入内容。
+- 只有人工确认网站**未受理**且已清理编辑器/草稿后，才能通过队列“人工核对 / 处理”重新排队或移出。审核中、已受理和结果不明不应重试。
+- 换号插件暂停后需要通过插件现有“继续未完成流程”恢复，不重复抽号。若账号未发生变化，调度器不会猜测换号成功。
+
+## 文件与数据
+
+```text
+app.py / store.py / articles.py   本地接口、任务队列、文章校验
+modules/downloader/              下载器副本与成功保存回调
+modules/package.py               文章包生成器副本
+browser/                         页面执行器、排版和连接脚本
+static/                          操作前端
+start.command                    启动入口
+build_browser.py                 重建合并油猴脚本
+test/                           离线测试、模拟素材、历史测试截图
+data/queue.sqlite3               运行任务、计数、受理去重记录（本地）
+downloads/                      本工具下载结果（本地）
+```
+
+- `test/history/` 保存从本目录移入的两张演示截图与演示任务 JSON。根目录其他测试文件未搬动。
+- `发布去重记录.json` 是实际受理证据，继续留在原处，并在服务启动时迁入去重库。它不代表完整历史已对账。原文件可找到时还建立内容指纹；原文件丢失时仍保留原 Markdown 摘要。
+- 原始下载文件不改写。长标题生成保守 UTF-16 长度不超过 80 的派生标题并加 `...`，原题仍展示在队列；网站真实计数规则尚需实测。
+- 排版仅处理与文章来源一致的末尾标准尾注，保留正文中的其他“来源”文字。图片顺序、标识改变会回滚排版。
+- WebP/AVIF/SVG 当前明确拦截，需用户另存支持格式并更新 Markdown；没有静默丢图或自动转码。单图须小于 20 MiB，图片 base64 总大小不超过 48 MiB。
+- 本地库含文章内容快照和账号标识，不含账号密码、Cookie 或上传凭据。运行数据和历史截图已加入忽略规则。
+
+## 验证
+
+不连接新闻 API 或真实论坛：
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python -m unittest discover -s test -p 'test_*.py' -v
+node --test test/importer.test.cjs test/bridge.test.cjs
+python3 build_browser.py
+```
+
+浏览器回归需要 Playwright 和本机 Chrome，使用临时独立浏览器，不使用用户配置或账号：
+
+```sh
+# 终端一：临时模拟数据服务，端口 8771
+uv run --no-project --python 3.12 --with-requirements requirements.txt python test/serve_fixture.py
+# 终端二：Node 环境需能加载 playwright；CHROME_PATH 可指定浏览器可执行文件
+node test/browser.test.cjs
+```
+
+浏览器回归拦截所有真实论坛请求，仅使用模拟 HTML。截图输出到 `test/artifacts/`。本轮离线通过不代表已在用户登录态的真实网站上完成上传、换号或发布。
+
+## 下一步需要的页面资料
+
+按用户决定，等待结果页 HTML：帖子标题、首帖作者及 UID 链接、版块及 fid 链接、“审核中”提示、公开帖子与失败提示。不要提供 Cookie、密码或表单令牌。将据此完成 `runner.js` 的结果观察适配，调用已经实现的受理记录接口，联通后续计数和换号。