npm package: @hangox/popo-doc-reader
Description: POPO 文档自动导出工具 - 基于 Playwright 和 CookieCloud 的自动化文档导出
Author: hangox
Latest version: 1.0.4

# @hangox/popo-doc-reader

[![npm version](https://img.shields.io/npm/v/@hangox/popo-doc-reader.svg)](https://www.npmjs.com/package/@hangox/popo-doc-reader)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 功能特点

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

## 快速开始

### 全局安装(推荐)

```bash
# 全局安装
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
```

### 在项目中使用

```bash
# 安装到项目
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'
);
```

### 本地开发

```bash
# 克隆仓库
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: 系统环境变量(推荐全局安装时使用)

```bash
# 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: 命令行临时设置

```bash
# 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` 文件:

```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。

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

## 使用方法

### CLI 命令行

```bash
# 基本用法(使用默认下载目录)
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 使用

```typescript
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):

```json
{
  "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](./MCP_CONFIGURATION.md)

### npm scripts(本地开发)

```bash
# 编译 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
```

## 支持的导出格式

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

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

## 调试技巧

1. **查看详细日志**: 在 `.env` 中设置 `COOKIE_SYNC_VERBOSE=true`
2. **有头模式**: 设置环境变量 `POPO_EXPORT_DEBUG=true`,可以看到浏览器执行过程
3. **调试截图模式**: 设置环境变量 `POPO_EXPORT_SCREENSHOT=true`
   - 在每个关键步骤自动保存全页截图
   - 截图文件命名格式: `debug-001-时间戳-操作描述.png`
   - 截图保存在输出目录,方便无头模式下调试
4. **检查环境**: 运行 `popo-check-env` 检查配置
5. **查看错误截图**: 失败时会在输出目录保存 `popo-export-error.png`
6. **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 文档的自动化测试:

```bash
# 运行所有测试(后台模式)
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 秒)
- 如果超时,检查网络连接和文档大小
- 可以查看调试截图确认页面状态

## 开发指南

### 添加新的导出格式

1. 在 `src/types.ts` 中添加格式类型:
```typescript
export type ExportFormat = 'excel' | 'csv' | 'pdf' | 'word'; // 添加 word
```

2. 在 `src/config.ts` 中添加格式配置:
```typescript
exportFormats: {
  word: {
    selectors: ['导出Word', 'Export as Word'],
    desc: 'Word 格式',
    extension: '.docx',
  },
  // ...
}
```

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

### 添加新的选择器

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

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

### 修改超时时间

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

```typescript
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

Copyright (c) 2025 hangox

## 贡献

欢迎提交 Issue 和 Pull Request!

### 贡献指南

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

## 链接

- [npm 包](https://www.npmjs.com/package/@hangox/popo-doc-reader)
- [GitHub 仓库](https://github.com/hangox/popo-doc-reader)
- [问题反馈](https://github.com/hangox/popo-doc-reader/issues)

## 致谢

- [Playwright](https://playwright.dev/) - 强大的浏览器自动化工具
- [CookieCloud](https://github.com/easychen/CookieCloud) - Cookie 同步解决方案