124 lines
8.3 KiB
Markdown
124 lines
8.3 KiB
Markdown
# 广谈大湾网本地文章导入
|
||
|
||
主脚本：`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 图片/链接暂不支持，会报错。
|
||
- 图片必须用 `` 这类相对路径引用；支持子目录、空格及常见括号路径。远程图片、目录外路径、缺图、空文件、达到 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": [
|
||
{
|
||
"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、编辑器代码编写，上传参数在运行时从当前页面读取，未写入账号或凭证。本次未安装油猴脚本，也未进行真实网站上传；最终在线兼容性需由你首次测试确认。如果网站以后更换编辑器或上传协议，应更新适配部分。
|