# 油猴脚本使用指南

## 📦 安装

### 1. 安装油猴扩展

首先需要在浏览器中安装油猴（Tampermonkey）扩展：

- **Chrome / Edge**: [Chrome Web Store](https://chrome.google.com/webstore/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo)
- **Firefox**: [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/tampermonkey/)
- **Safari**: [App Store](https://apps.apple.com/app/tampermonkey/id1482490089)

### 2. 选择脚本版本

项目提供两个版本的脚本：

| 版本 | 文件路径 | 特点 | 适用场景 |
|------|---------|------|---------|
| **增强版** | `clients/userscript-template.js` | 功能完整，支持高级配置 | 需要定时同步、自动同步等高级功能 |
| **简化版** | `client/userscript-template.js` | 功能精简，易于使用 | 只需基础同步功能 |

### 3. 安装脚本

1. 打开油猴扩展的管理界面
2. 点击"创建新脚本"
3. 复制对应版本的脚本内容
4. 粘贴到编辑器中
5. 保存（Ctrl+S 或 Cmd+S）

## ⚙️ 初次配置

### 必须配置的项目

安装脚本后，**首次使用前必须配置**：

1. 点击页面右侧的 🔄 按钮打开菜单
2. 选择 "⚙️ 配置设置"
3. 配置以下项目：

```
服务器地址: http://47.122.126.244:5001
密码:       admin123123123
```

> ⚠️ **重要**：如果不配置正确的服务器地址和密码，同步将会失败！

### 可选配置项（仅增强版）

- **Tag**: 留空自动检测，或手动指定（格式：`项目名:账号`）
- **数据类型**: 默认 Cookie
- **过期时间**: 默认 604800 秒（7天）
- **自动检测**: 建议保持开启
- **自动同步**: 页面加载后自动同步（不推荐）
- **定时同步**: 定时自动同步间隔，0 表示禁用

## 🚀 使用方法

### 基础使用流程

1. **访问支持的网站**
   - 目前支持：听悟（tingwu.aliyun.com）、微信公众平台（mp.weixin.qq.com）
   - 增强版支持通过 `@match` 添加更多网站

2. **登录账号**
   - 在目标网站正常登录

3. **同步数据**
   - 点击页面右侧的 🔄 按钮
   - 选择 "🔄 立即同步"
   - 等待提示消息

4. **确认结果**
   - ✅ 同步成功：显示 Tag 和时间戳
   - ❌ 同步失败：检查错误信息（密码错误、网络错误等）

### 高级功能（仅增强版）

#### 快捷键操作

```
Ctrl+Shift+S  - 立即同步
Ctrl+Shift+C  - 复制配置到剪贴板
```

#### 复制配置

用于分享或备份配置：

1. 点击 🔄 按钮
2. 选择 "📋 复制配置"
3. 配置信息已复制到剪贴板，格式：

```json
{
  "serverUrl": "http://47.122.126.244:5001",
  "password": "admin123123123",
  "tag": "tingwu:user@email.com",
  "type": "cookie"
}
```

#### 自动同步设置

在配置面板中可以开启：

- **自动同步**: 页面加载 3 秒后自动执行同步
- **定时同步**: 按设定间隔定期同步（例如：每 300 秒同步一次）

> ⚠️ **注意**：频繁自动同步可能影响页面性能，建议手动同步

## 🔍 故障排查

### 问题 1: 提示"同步失败：Invalid password"

**原因**：密码配置错误

**解决方案**：
1. 打开配置面板
2. 确认密码为：`admin123123123`
3. 保存配置后重试

### 问题 2: 提示"网络错误：无法连接到服务器"

**原因**：服务器地址不可达

**解决方案**：
1. 检查服务器地址是否正确：`http://47.122.126.244:5001`
2. 确认服务器是否在运行
3. 检查网络连接
4. 检查浏览器控制台是否有跨域错误（CORS）

### 问题 3: 提示"当前网站不支持自动同步"

**原因**：当前网站不在支持列表中

**解决方案**：

**对于增强版**，可以手动添加项目规则：

编辑脚本，在 `PROJECT_RULES` 中添加：

```javascript
{
    name: '项目名',
    match: (url) => url.includes('目标域名'),
    getAccount: () => {
        // 提取账号的逻辑
        return '账号名';
    },
    loginUrl: 'https://登录页面URL'
}
```

**对于简化版**，需要：

1. 在脚本头部添加 `@match` 规则：
```javascript
// @match        https://目标域名/*
```

2. 在 `PROJECT_PATTERNS` 中添加配置：
```javascript
'目标域名': {
    project: '项目名',
    accountSelector: '.账号选择器',
    loginUrl: 'https://登录页面URL'
}
```

### 问题 4: 未找到 Cookie

**原因**：当前页面没有 Cookie 或 Cookie 为空

**解决方案**：
1. 确认已经登录
2. 刷新页面后重试
3. 检查浏览器是否禁用了 Cookie

### 问题 5: 服务器响应格式错误

**原因**：服务器返回了非 JSON 格式的数据

**解决方案**：
1. 检查服务器是否正常运行
2. 确认 API 端点 `/api/data` 可访问
3. 查看浏览器控制台的详细错误信息

## 🎯 最佳实践

### 1. 安全建议

- ✅ 定期更换密码
- ✅ 不要在公共电脑上使用
- ✅ 配置数据仅存储在本地浏览器
- ❌ 不要将密码分享给他人

### 2. 使用建议

- ✅ 登录后立即同步，确保数据最新
- ✅ 重要账号手动同步，避免自动同步失败
- ✅ 定期检查同步状态
- ❌ 不要开启过于频繁的定时同步

### 3. 数据管理

- 数据保存在服务器的 `/data` 目录
- 文件名格式：`项目名_账号.json`
- 默认保留 7 天，可在配置中修改
- 可通过 Web 界面查看和管理：`http://47.122.126.244:5001`

## 📊 同步数据格式

脚本上传的数据格式：

```json
{
  "tag": "tingwu:user@email.com",
  "type": "cookie",
  "data": {
    "cookies": [
      {
        "name": "cookie名",
        "value": "cookie值",
        "domain": "域名",
        "path": "/"
      }
    ],
    "raw_cookie": "原始cookie字符串",
    "user_agent": "浏览器UA"
  },
  "metadata": {
    "expires_in": 604800,
    "note": "同步备注",
    "login_url": "https://登录页面",
    "created_at": "2026-08-14 10:00:00",
    "updated_at": "2026-08-14 10:00:00"
  }
}
```

## 🆘 技术支持

### 查看日志

1. 打开浏览器控制台（F12）
2. 切换到 Console 标签
3. 查看脚本输出的日志信息

### 常见日志信息

```
🚀 通用数据同步脚本已加载     - 脚本初始化成功
🔍 自动检测结果: {...}        - 显示检测到的项目和账号
✅ 数据同步成功: {...}        - 同步成功
❌ 数据同步失败: {...}        - 同步失败，查看错误信息
❌ 网络错误: {...}            - 网络请求失败
```

### 获取帮助

如遇到问题，请提供以下信息：

1. 脚本版本（增强版 v3.0 或简化版 v2.0.0）
2. 浏览器类型和版本
3. 目标网站 URL
4. 错误提示信息
5. 浏览器控制台的错误日志

## 🔄 更新脚本

### 手动更新

1. 打开油猴管理界面
2. 找到对应的脚本
3. 点击编辑
4. 替换为新版本的代码
5. 保存

### 检查更新

在油猴管理界面中，可以查看脚本的版本号：

- 增强版当前版本：**3.0**
- 简化版当前版本：**2.0.0**

## 📝 附录

### 支持的浏览器

- ✅ Chrome 88+
- ✅ Firefox 85+
- ✅ Edge 88+
- ✅ Safari 14+
- ⚠️ Opera（需要测试）
- ❌ IE（不支持）

### 支持的网站

**默认支持：**
- 听悟（tingwu.aliyun.com）
- 微信公众平台（mp.weixin.qq.com）

**扩展支持：**
可通过修改脚本添加更多网站，参考上文"故障排查 - 问题3"

### API 兼容性

脚本与以下 API 版本兼容：
- ✅ 当前项目的 nginx/nginx.conf 定义的 API
- ✅ POST `/api/data` 接口
- ✅ 支持 CORS 跨域请求
- ✅ 密码验证机制