first commit

本地文章导入脚本使用说明.md

@@ -0,0 +1,123 @@
+# 广谈大湾网本地文章导入
+
+主脚本：`dww11-article-importer.user.js`，版本 1.0.0。单文件、无第三方运行依赖，可本地安装，也可自行提交到 Greasy Fork。本次没有替你安装或提交到 Greasy Fork。
+
+## 安装和首次测试
+
+1. 在 Chrome 中准备好 Tampermonkey（油猴）扩展。
+2. 打开 Tampermonkey 的管理面板，选择“添加新脚本”，删除默认模板，把 `dww11-article-importer.user.js` 的全部内容粘贴进去并保存。也可以使用扩展自身的文件导入功能导入这个 `.user.js` 文件。
+3. 打开或刷新 `https://www.dww11.com/forum.php?mod=post&action=newthread&fid=95`，保持登录状态。右下角应出现“本地文章导入 · 1.0”面板。
+4. 点击“选择文章目录”，选择整个 `为什么年轻人爱玩手机，背后的真相太无奈！` 文件夹。这个文件夹里应同时包含 `.md` 文件和三张 JPG，不要只选 Markdown。
+5. 面板会显示标题、正文原文预览、三张图片缩略图。这一步只读取本地文件，不上传图片、不填写网页。
+6. 点击“上传配图并填写”。这一步才会向广谈大湾网上传被正文引用的图片，随后填写标题、正文，尽可能切回网站富文本模式显示配图。
+7. 检查正文三处图片位置和末尾来源说明。脚本不点击“发表帖子”或“保存草稿”。实际发表仍由你操作。
+
+浏览器若提示将所选文件夹的文件提供给网页，这是目录选择器的正常提示。脚本只发送被正文引用且通过检查的图片，不会将整个目录打包上传到网站。
+
+如果看不到面板，先检查扩展是否已启用、是否允许在该网站运行脚本，以及当前页是否为 `action=newthread` 的新发帖页面。本版不在编辑旧帖或快速回复页运行。Tampermonkey/Chrome 若提示启用用户脚本支持，按扩展界面中的指引设置。
+
+## 支持范围和失败处理
+
+- 支持整个目录和子目录；一个目录中有多个 Markdown 时出现下拉选择框。
+- 标题取 Markdown 开头第一个 `# 标题`；无标题时取文件名。开头标题不会再插入正文。上限 80 字，超限会停止。
+- 支持正文段落、内联本地图片、常见加粗/斜体/删除线、链接、标题、基本列表、引用和代码块。内联代码保留文字；多层列表会简化为一层。表格和原始 HTML 按文字保留并给出提示，复杂公众号视觉样式不复刻。引用式 Markdown 图片/链接暂不支持，会报错。
+- 图片必须用 `![](image001.jpg)` 这类相对路径引用；支持子目录、空格及常见括号路径。远程图片、目录外路径、缺图、空文件、达到 20 MB 或网站不支持的后缀会在上传前拦截。当前站点支持 JPG/JPEG/PNG/GIF。
+- 只上传被当前文章引用的图片。相同内容按 SHA-256 去重，即使文件名不同也复用附件编号，正文每个引用位置仍然保留。
+- 这篇测试文章有三个图片引用，其中 `image001.jpg` 与 `image003.jpg` 的文件内容相同，因此预计只需要上传两个独立文件，但正文应显示三处图片。
+- 当前编辑器已有内容时先询问是否替换。上传期间又修改正文时，在填写前再询问。导入期间临时禁用网页提交按钮。
+- 图片上传或网站图片列表加载失败时，标题与正文不会被替换；已上传的图片仍在网站上。当前页面内重试会复用已成功返回附件编号的图片。刷新页面后缓存失效；上传超时可能是“服务器成功、客户端未收到结果”，此时先检查网站图片列表，避免重复上传。
+- 网站自带的编辑器自动保存可能在填写后继续运行。本脚本不关闭或改动网站自动保存设置，也不承诺页面完全无草稿痕迹。
+- “导出诊断”生成本地 JSON，包含阶段、文件路径、标题和附件编号等排错信息，不包含 Cookie、上传凭证或正文。需要反馈时可把这个文件交给维护者。
+
+## 给下载程序的接口
+
+浏览器页面提供 `window.DWW11Importer`，接口版本 1。读取文章、上传适配和面板各自分开，后续可替换输入来源；无需重写 Markdown 与附件插入逻辑。
+
+```javascript
+// 暂存浏览器已获准读取的文件。只检查与预览，不上传。
+await window.DWW11Importer.stageFiles(fileList);
+// 多个 Markdown 时可直接指定其 webkitRelativePath：
+await window.DWW11Importer.stageFiles(fileList, {
+  markdownPath: '文章目录/文章.md'
+});
+
+// 暂存文章包，同样不上传。推荐外部程序对接此接口。
+await window.DWW11Importer.stagePackage(articlePackage);
+
+// 显式执行“上传配图并填写”；不会发布。
+const result = await window.DWW11Importer.importPrepared();
+// result: { title, images: { 'image001.jpg': '附件编号' }, completedAt }
+// 取消替换时返回 { cancelled: true }；失败时 Promise reject。
+
+window.DWW11Importer.getState();  // busy / ready / title / imageCount / warnings / result
+window.DWW11Importer.getBackup(); // 最近一次填写前的标题、正文及模式（仅存在内存）
+window.DWW11Importer.openPicker(); // 应从用户点击事件调用，打开目录选择器
+
+window.addEventListener('dww11-importer:progress', event => {
+  console.log(event.detail); // { phase, message, completed?, total? }
+});
+```
+
+`stageFiles` 返回准备完成的摘要；目录有多个 Markdown 且未指定文件时返回 `{ candidates: [...] }` 并等待选择。`stagePackage` 返回摘要。`getBackup()` 的 `mode: 0` 表示论坛纯文本格式，`mode: 1` 表示编辑器 HTML；不要直接当 Markdown 使用。
+
+没有提供自动监听外部网页消息、后台轮询本地目录、直接读取任意本地路径或自动发表接口。其他本地程序需通过文章包文件、浏览器扩展或自动化工具把文件内容送进上述接口。浏览器普通网页不能凭一个本地路径字符串读取硬盘。
+
+### 文章包格式
+
+```json
+{
+  "schemaVersion": 1,
+  "markdownPath": "文章.md",
+  "markdown": "# 标题\n\n正文\n\n![](images/01.jpg)",
+  "images": [
+    {
+      "path": "images/01.jpg",
+      "mime": "image/jpeg",
+      "base64": "这里是文件的纯Base64内容，不含data前缀"
+    }
+  ]
+}
+```
+
+所有路径相对于所选文章目录，图片相对于 Markdown 文件位置解析。可选 `title` 显式指定标题。浏览器内直接调用时，图片条目也可传 `{ path, blob: File或Blob }` 代替 Base64。
+
+### 本地打包工具
+
+`dww11_make_package.py` 使用 Python 标准库，无需额外安装依赖。
+
+在 `dww11自动化` 目录执行：
+
+```sh
+python3 dww11_make_package.py \
+  'tests/fixtures/article' \
+  -o '测试文章.dww11.json'
+```
+
+再点击油猴面板的“导入文章包”，选择输出的 JSON。此功能是未来程序对接的补充；日常操作仍推荐直接选择整个文章目录。
+
+- 不加 `-o` 时，标准输出就是文章包 JSON，方便其他程序解析。
+- 加 `-o` 时，标准输出为 `{ "ok": true, "package": "绝对路径" }`；不覆盖已有文件。
+- 多个 Markdown 时，用 `--markdown '子目录/文章.md'` 指定。
+- 文件打包失败退出码为 1；参数用法错误为 2。
+
+现有下载程序返回的 `directory` 可以直接传给打包工具：
+
+```python
+from dww11_make_package import make_package
+
+# download_result 是原下载器返回的结果对象
+article_package = make_package(download_result.directory)
+# 后续由调用方保存为 JSON，或把 article_package 交给浏览器 stagePackage。
+```
+
+这个工具仅打包本地数据，不会自动连接浏览器或发表文章。包文件含完整正文和图片，保留在你自己的电脑上即可。
+
+## 验证记录与边界
+
+离线测试使用项目自有测试文章，覆盖正文逐字保留、三处图片顺序、去重、缺图与路径检查、文章包接口、上传失败、富文本转换失败回滚，以及“只有图片上传请求、没有发表请求”。运行：
+
+```sh
+node --test test-dww11-importer.cjs
+```
+
+网站适配依据当前页面和网站公开的 WebUploader、编辑器代码编写，上传参数在运行时从当前页面读取，未写入账号或凭证。本次未安装油猴脚本，也未进行真实网站上传；最终在线兼容性需由你首次测试确认。如果网站以后更换编辑器或上传协议，应更新适配部分。