wps-doc-scraper

WPS Doc Scraper

概述

以忠实于源内容的方式归档 WPS/KDocs 公开文档。优先使用无需身份验证的数据 API，保留原始负载；如果文档是画布或思维导图，则捕获原始视觉内容，并仅将 Markdown 生成为源内容的结构化表示。

这是一项提取技能，而不是写作技能。除非用户在归档完成后明确要求单独进行分析，否则不要使用 LLM 改写、总结、润色文档内容，也不要推断缺失内容。

工作流决策树

1. 识别 URL 类型。

   • kdocs.cn/view/l/<share_id> 或 kdocs.cn/l/<share_id>：先读取公开链接元数据。
   • wps.processon.com/diagrams/view?...：提取 file_id 和 group_id，然后使用 ProcessOn 数据 API。
   • wps.processon.com/wpsapi/diagrams/view/api?...：直接将其视为源 API。
   • 其他 WPS/KDocs 页面：收集公开元数据，仅在可用时尝试官方公开导出/下载，然后使用浏览器 DOM 捕获作为后备方案。

2. 对于 ProcessOn .pof 思维导图或画布，运行 API 提取器：

   python3 /path/to/wps-doc-scraper/scripts/wps_processon_extract.py \
     --url "https://www.kdocs.cn/view/l/..." \
     --output-dir "/path/to/archive-dir"
   

   预期输出：processon-api.json、processon-definition.json、capture-manifest.json 和 <title>.md。

3. 捕获原始图像。

   • 如果页面提供了渲染后的 SVG，将完整序列化 SVG 保存为 <title>-全画布.svg。
   • 如果 SVG 使用 foreignObject，不要仅依赖 ImageMagick 来渲染文本。使用 scripts/render_svg_tiles.py 通过 macOS Quick Look 方形切片生成 PNG。

   python3 /path/to/wps-doc-scraper/scripts/render_svg_tiles.py \
     --svg "/path/to/<title>-全画布.svg" \
     --output "/path/to/<title>-全画布.png"
   

4. 验证归档内容。

   • Markdown 是结构转换，不是编辑性改写。
   • 可视化文档应包含原始图像。
   • 原始 JSON 和清单应存在。
   • 输出文本中不得包含 Unicode 替换字符 �。
   • 任何失败或受权限限制的路径都应记录在清单或最终回复中。

硬性规则

• 除非用户明确要求，否则绝不登录、保存到帐户、复制到用户的云盘，或修改远程文档。
• 不得绕过 CAPTCHA、付费墙、租户限制或权限墙。需要登录的公开链接属于不可逾越的边界，除非用户提供经过授权的访问权限。
• 不要推断隐藏节点或缺失文本。保留 API 或渲染后的 DOM 实际提供的内容。
• HTTP 200 并不足够。应检测登录墙负载，例如 用户未登录、空定义和占位内容。
• 转换前保留原始来源材料：API JSON、解析后的定义 JSON、序列化 SVG、屏幕截图或 PNG，以及捕获清单。
• 使用浏览器后备方案时，尽可能先捕获 DOM/源数据，再截取屏幕截图；仅有屏幕截图并不能忠实地归档文本。
• 明确报告提取缺失之处。不要基于不完整数据悄悄生成经过润色的 Markdown 文件。

捆绑资源

scripts/

• wps_processon_extract.py：用于提取公开 WPS/KDocs ProcessOn .pof 思维导图的确定性提取器。它会解析 KDocs 分享元数据，下载 ProcessOn 数据 API JSON，解析嵌入的定义，并生成 Markdown 和清单。
• render_svg_tiles.py：基于 macOS Quick Look 的 SVG 转 PNG 渲染器，适用于包含 foreignObject 文本的完整画布 SVG。它会渲染方形纵向切片，并将其拼接为一张 PNG。

references/

• processon-mindmap-api.md：WPS 托管的 ProcessOn 文件的端点模式和负载结构。
• rendered-svg-capture.md：提取渲染后的完整画布 SVG 并生成 PNG 的浏览器端流程。
• capture-manifest.md：清单的最低字段要求和验收检查。
• permission-and-failure-boundaries.md：登录墙、禁止的权限升级操作和失败报告规则。