@hangox/popo-doc-reader

v1.0.4

Published

2 months ago

POPO 文档自动导出工具 - 基于 Playwright 和 CookieCloud 的自动化文档导出

0High
0Medium
0Low

hangox

popo document export playwright cookiecloud automation pdf excel csv mcp model-context-protocol

@hangox/popo-doc-reader

POPO 文档自动导出工具 - 基于 Playwright 和 CookieCloud 的自动化文档导出

功能特点

🚀 自动导出: 自动导出网易 POPO 文档系统中的文档
📄 多格式支持: 支持 PDF、Excel、CSV 格式
🍪 Cookie 同步: 通过 CookieCloud 自动同步登录状态,无需手动登录
🎯 智能检测: 自动检测文档类型并选择最佳导出格式
🔍 错误处理: 详细的错误提示和自动截图调试
🐛 调试模式: 支持有头模式和自动截图调试
🌏 中文优化: 强制使用中文界面,提高选择器匹配率
💻 TypeScript: 完整的类型定义和类型安全
📦 开箱即用: 提供 CLI 命令行工具,也可作为 npm 包使用
🤖 MCP 集成: 支持 Model Context Protocol,可与 Claude Desktop 等 AI 助手集成

快速开始

全局安装(推荐)

# 全局安装
npm install -g @hangox/popo-doc-reader

# 安装 Playwright 浏览器
npx playwright install chromium

# 配置环境变量(见下方配置章节)

# 导出文档
popo-export "https://docs.popo.netease.com/team/pc/xxx/pageDetail/xxx"

# 检查环境配置
popo-check-env

在项目中使用

# 安装到项目
npm install @hangox/popo-doc-reader

# 使用 API
import { exportPOPODoc } from '@hangox/popo-doc-reader';

await exportPOPODoc(
  'https://docs.popo.netease.com/team/pc/xxx/pageDetail/xxx',
  './output/document.pdf'
);

本地开发

# 克隆仓库
git clone https://github.com/hangox/popo-doc-reader.git
cd popo-doc-reader

# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium

# 配置环境变量(见下方配置章节)

# 运行导出
npm run export -- "https://docs.popo.netease.com/..."

配置

环境变量配置

环境变量可以通过以下三种方式配置(按优先级排序):

方式 1: 系统环境变量(推荐全局安装时使用)

# macOS/Linux - 添加到 ~/.zshrc 或 ~/.bashrc
export COOKIE_CLOUD_SERVER=https://your-cookiecloud-server.com
export COOKIE_CLOUD_UUID=your-uuid
export COOKIE_CLOUD_PASSWORD=your-password

# Windows PowerShell
$env:COOKIE_CLOUD_SERVER="https://your-cookiecloud-server.com"
$env:COOKIE_CLOUD_UUID="your-uuid"
$env:COOKIE_CLOUD_PASSWORD="your-password"

# Windows CMD
set COOKIE_CLOUD_SERVER=https://your-cookiecloud-server.com
set COOKIE_CLOUD_UUID=your-uuid
set COOKIE_CLOUD_PASSWORD=your-password

方式 2: 命令行临时设置

# macOS/Linux
COOKIE_CLOUD_SERVER=https://... COOKIE_CLOUD_UUID=xxx popo-export "URL"

# Windows PowerShell
$env:COOKIE_CLOUD_SERVER="https://..."; popo-export "URL"

方式 3: .env 文件(推荐本地开发时使用)

在项目根目录创建 .env 文件:

# CookieCloud 配置(必填)
COOKIE_CLOUD_SERVER=https://your-cookiecloud-server.com
COOKIE_CLOUD_UUID=your-uuid
COOKIE_CLOUD_PASSWORD=your-password

# Cookie 同步配置(可选)
COOKIE_SYNC_STRATEGY=before-each-request
COOKIE_SYNC_VERBOSE=false

# 调试模式(可选)
POPO_EXPORT_DEBUG=false
POPO_EXPORT_SCREENSHOT=false

注意: .env 文件仅在本地开发时有效。如果全局安装使用,请配置系统环境变量。

环境变量说明

| 变量名 | 必填 | 说明 | |-------|------|------| | COOKIE_CLOUD_SERVER | ✅ | CookieCloud 服务器地址 | | COOKIE_CLOUD_UUID | ✅ | CookieCloud UUID | | COOKIE_CLOUD_PASSWORD | ✅ | CookieCloud 密码 | | COOKIE_SYNC_STRATEGY | ❌ | Cookie 同步策略(默认 before-each-request) | | COOKIE_SYNC_VERBOSE | ❌ | 是否显示详细同步日志(默认 false) | | POPO_EXPORT_DEBUG | ❌ | 调试模式,启用有头模式和慢速操作(默认 false) | | POPO_EXPORT_SCREENSHOT | ❌ | 调试截图模式,在每个关键步骤自动截图(默认 false) |

CookieCloud 配置

CookieCloud 是一个跨平台的 Cookie 同步工具,可以让你在不同设备和浏览器之间同步 Cookie。

安装 CookieCloud 浏览器扩展
配置 CookieCloud 服务器(可以使用官方服务器或自建)
获取 UUID 和 Password
在 POPO 文档网站登录一次
CookieCloud 会自动同步登录状态

使用方法

CLI 命令行

# 基本用法(使用默认下载目录)
popo-export "https://docs.popo.netease.com/team/pc/xxx/pageDetail/xxx"

# 指定输出路径
popo-export "https://docs.popo.netease.com/..." "./output/document.pdf"

# 调试模式(显示浏览器窗口)
POPO_EXPORT_DEBUG=true popo-export "https://docs.popo.netease.com/..."

# 调试截图模式(自动截图每个步骤)
POPO_EXPORT_SCREENSHOT=true popo-export "https://docs.popo.netease.com/..."

# 同时启用两种调试模式
POPO_EXPORT_DEBUG=true POPO_EXPORT_SCREENSHOT=true popo-export "https://docs.popo.netease.com/..."

# 检查环境配置
popo-check-env

API 使用

import { exportPOPODoc } from '@hangox/popo-doc-reader';

try {
  const result = await exportPOPODoc(
    'https://docs.popo.netease.com/team/pc/xxx/pageDetail/xxx',
    './output/document.pdf'
  );

  console.log('导出成功!');
  console.log('文件路径:', result.outputPath);
  console.log('文件大小:', result.fileSize);
  console.log('耗时:', result.duration);
} catch (error) {
  console.error('导出失败:', error.message);
}

MCP (Model Context Protocol) 集成

POPO 文档导出工具支持作为 MCP 服务器运行,可以与 Claude Desktop 等 AI 助手集成。

快速配置 Claude Desktop:

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "popo-doc-reader": {
      "command": "npx",
      "args": ["-y", "@hangox/popo-doc-reader", "popo-doc-reader-mcp"],
      "env": {
        "COOKIE_CLOUD_SERVER": "https://your-server.com",
        "COOKIE_CLOUD_UUID": "your-uuid",
        "COOKIE_CLOUD_PASSWORD": "your-password"
      }
    }
  }
}

重启 Claude Desktop 后,可以直接向 Claude 发送请求:

请帮我导出这个 POPO 文档:
https://docs.popo.netease.com/team/pc/xxx/pageDetail/xxx

详细的 MCP 配置说明请参阅 MCP_CONFIGURATION.md

npm scripts(本地开发)

# 编译 TypeScript 代码
npm run build

# 开发模式运行
npm run dev -- "https://docs.popo.netease.com/..."

# 检查环境配置
npm run check-env

# 导出文档
npm run export -- "https://docs.popo.netease.com/..."

# 运行测试
npm test

# 调试模式测试
npm run test:debug

# 清理编译输出
npm run clean

支持的导出格式

工具会自动检测页面支持的格式并按优先级选择:

Excel (.xlsx) - 表格文档优先导出为 Excel
CSV (.csv) - 备选表格格式
PDF (.pdf) - 普通文档默认格式

调试技巧

查看详细日志: 在 .env 中设置 COOKIE_SYNC_VERBOSE=true
有头模式: 设置环境变量 POPO_EXPORT_DEBUG=true,可以看到浏览器执行过程
调试截图模式: 设置环境变量 POPO_EXPORT_SCREENSHOT=true
- 在每个关键步骤自动保存全页截图
- 截图文件命名格式: debug-001-时间戳-操作描述.png
- 截图保存在输出目录,方便无头模式下调试
检查环境: 运行 popo-check-env 检查配置
查看错误截图: 失败时会在输出目录保存 popo-export-error.png
TypeScript 类型检查: 运行 tsc --noEmit 检查类型错误

项目结构

.
├── src/                    # TypeScript 源代码
│   ├── types.ts           # 类型定义
│   ├── config.ts          # 配置(选择器、超时时间等)
│   ├── utils.ts           # 工具函数(文件处理、环境检查等)
│   ├── export.ts          # 核心导出逻辑
│   ├── cli.ts             # CLI 入口文件
│   ├── check-environment.ts  # 环境检查工具
│   └── index.ts           # 模块导出
├── dist/                   # 编译输出(自动生成)
├── tests/                  # 测试文件
├── package.json
├── tsconfig.json
├── .editorconfig          # 编辑器配置
├── .env                    # 环境变量(需要创建)
└── README.md

测试

项目包含了针对不同类型 POPO 文档的自动化测试:

# 运行所有测试(后台模式)
npm test

# 调试模式(显示浏览器窗口)
npm run test:debug

测试结果保存在 test-output/ 目录。

常见问题

CookieCloud cookies 未同步

检查环境变量是否正确配置(系统环境变量、命令行参数或 .env 文件)
全局安装时,推荐使用系统环境变量(添加到 ~/.zshrc 或 ~/.bashrc)
本地开发时,可以使用 .env 文件(需在项目根目录)
确认 CookieCloud 服务器地址和凭据是否正确
运行 popo-check-env 检查配置
确保在浏览器中至少登录过一次 POPO 文档系统

TypeScript 编译错误

确保使用 .js 扩展名导入模块(ESM 规范)
检查类型定义是否完整
运行 npm run clean && npm run build 清理重新编译

浏览器未安装

运行 npx playwright install 安装所有浏览器
或 npx playwright install chromium 只安装 Chromium

导出失败

检查 URL 是否正确(必须是 https://docs.popo.netease.com/ 开头)
确认 Cookie 是否过期(浏览器重新登录并等待 CookieCloud 同步)
查看错误截图确认页面状态
使用调试模式 POPO_EXPORT_DEBUG=true 观察执行过程
使用截图模式 POPO_EXPORT_SCREENSHOT=true 查看每步执行情况

导出提示"正在导出,请稍候..."一直等待

工具会自动等待导出完成(最长 60 秒)
如果超时,检查网络连接和文档大小
可以查看调试截图确认页面状态

开发指南

添加新的导出格式

在 src/types.ts 中添加格式类型:

export type ExportFormat = 'excel' | 'csv' | 'pdf' | 'word'; // 添加 word

在 src/config.ts 中添加格式配置:

exportFormats: {
  word: {
    selectors: ['导出Word', 'Export as Word'],
    desc: 'Word 格式',
    extension: '.docx',
  },
  // ...
}

在 src/export.ts 中的格式检测逻辑会自动支持

添加新的选择器

在 src/config.ts 的 CONFIG.selectors 中添加:

moreButtons: [
  {
    type: 'locator',
    selector: 'your-css-selector',
    desc: '描述',
  },
  // ...
]

修改超时时间

在 src/config.ts 的 CONFIG.timeout 中修改:

timeout: {
  navigation: 30000,  // 页面导航超时
  download: 120000,   // 下载超时
  elementCheck: 300,  // 元素检查间隔
  maxWait: 15000,     // 最大等待时间
}

技术栈

TypeScript: 类型安全的 JavaScript
Playwright: 现代化的浏览器自动化框架
@hangox/playwright-cookie: Playwright + CookieCloud 集成版本
dotenv: 环境变量管理
Node.js: >= 18.0.0

版本历史

v1.0.0 (2025-01-23)

🎉 首次发布
✅ 支持 PDF/Excel/CSV 格式导出
✅ CookieCloud 自动 Cookie 同步
✅ 智能格式检测
✅ 调试模式和截图功能
✅ 中文界面强制设置
✅ 完整的 TypeScript 类型支持

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request!

贡献指南

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

链接

致谢

Playwright - 强大的浏览器自动化工具
CookieCloud - Cookie 同步解决方案

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@hangox/popo-doc-reader

功能特点

快速开始

全局安装(推荐)

在项目中使用

本地开发

配置

环境变量配置

方式 1: 系统环境变量(推荐全局安装时使用)

方式 2: 命令行临时设置

方式 3: .env 文件(推荐本地开发时使用)

环境变量说明

CookieCloud 配置

使用方法

CLI 命令行

API 使用

MCP (Model Context Protocol) 集成

npm scripts(本地开发)

支持的导出格式

调试技巧

项目结构

测试

常见问题

CookieCloud cookies 未同步

TypeScript 编译错误

浏览器未安装

导出失败

导出提示"正在导出,请稍候..."一直等待

开发指南

添加新的导出格式

添加新的选择器

修改超时时间

技术栈

版本历史

v1.0.0 (2025-01-23)

许可证

贡献

贡献指南

链接

致谢