⬇️ 下载文件

wolai-sync 完整集成指南

✅ 集成完成确认

1. AppId 和 AppSecret 配置

App ID: x4EaDyDbuh1Jkd7wrQcLXe
App Secret: 07995fd63d13d4b96dc54580430c2f8d792a054b0f3370c74e60669e7accfbd8

Token 已生成: ead0a034f8174564bd98... (完整 Token 保存在 ~/.wolai_token)

2. 成功验证

✅ Token 创建成功
✅ 响应格式正确解析
✅ Token 已保存到 ~/.wolai_token
✅ 测试数据已创建

📦 完整工具集

1. Token 管理工具

文件: scripts/wolai_token_manager.py

功能:

创建 Token (POST /token)
刷新 Token (PUT /token)
加载/保存 Token 到文件
安全存储，权限控制

使用示例:

# 创建 Token 并保存
python3 scripts/wolai_token_manager.py \
  --app-id x4EaDyDbuh1Jkd7wrQcLXe \
  --app-secret 07995fd63d13d4b96dc54580430c2f8d792a054b0f3370c74e60669e7accfbd8 \
  --action create \
  --save

# 从文件加载 Token
python3 scripts/wolai_token_manager.py --action load

# 刷新 Token
python3 scripts/wolai_token_manager.py \
  --app-id x4EaDyDbuh1Jkd7wrQcLXe \
  --app-secret 07995fd63d13d4b96dc54580430c2f8d792a054b0f3370c74e60669e7accfbd8 \
  --action refresh \
  --save

2. 完整版对话同步工具

文件: scripts/sync_conversation_full.py

功能:

基于真实 API 的对话同步
支持三种显示格式（detailed/compact/minimal）
分批创建块（避免 API 限制）
智能内容摘要
完整错误处理

使用示例:

# 方式 1: 直接指定 Token
python3 scripts/sync_conversation_full.py \
  --token YOUR_TOKEN \
  --page-id YOUR_PAGE_ID \
  --conversation-file conversation.json \
  --format detailed \
  --batch-size 10

# 方式 2: 从 Token 文件加载（推荐）
python3 scripts/sync_conversation_full.py \
  --token-file ~/.wolai_token \
  --page-id YOUR_PAGE_ID \
  --conversation-file conversation.json \
  --format detailed

3. 配置验证工具

文件: scripts/validate_config.py

功能:

验证 AppId 和 AppSecret
测试 Token 生成
创建测试数据

使用示例:

# 使用内置配置
python3 scripts/validate_config.py

# 或指定配置
python3 scripts/validate_config.py <APP_ID> <APP_SECRET>

4. 增强版 API 客户端

文件: scripts/wolai_api_enhanced.py

5. 修正版 API 客户端（严格遵循文档）

文件: scripts/wolai_api_corrected.py

6. 自动通知脚本

文件: scripts/sync_auto_notify.py

🚀 快速开始（3步完成）

第一步：验证配置（已完成 ✅）

Token 已生成并保存：

# 可以直接使用
python3 scripts/sync_conversation_full.py \
  --token-file ~/.wolai_token \
  --page-id YOUR_PAGE_ID \
  --conversation-file conv.json

第二步：创建测试页面

在 wolai 中：

创建一个新页面（或在现有页面中测试）
复制页面ID（URL 最后一部分，如 abc123xyz）

第三步：同步测试对话

# 测试同步（使用已创建的测试数据）
python3 scripts/sync_conversation_full.py \
  --token-file ~/.wolai_token \
  --page-id YOUR_PAGE_ID \
  --conversation-file /tmp/test_conversation.json \
  --format detailed

预期结果: 成功创建多个内容块，页面显示格式化对话记录

📊 对话数据格式

{
  "user": {
    "name": "用户昵称",
    "id": "用户ID"
  },
  "messages": [
    {
      "role": "user",
      "content": "用户输入的内容"
    },
    {
      "role": "assistant",
      "content": "助手回复的内容，可以包含代码块等"
    }
  ],
  "tags": ["标签1", "标签2", "分类"]
}

示例文件

测试数据: /tmp/test_conversation.json

🎨 三种显示格式

detailed（详细格式 - 推荐）

包含用户头像图标 👤 🤖
完整元数据（时间、ID）
标签显示为 标签 格式
助手回复使用引用框
适合重要对话记录

compact（紧凑格式）

简洁显示，适合频繁同步
角色简写和简短内容
减少页面占用空间
适合日常快速记录

minimal（极简格式）

最小化存储空间
U:/A: 简写格式
适合大规模归档

⚠️ API 限制与最佳实践

已知的 API 限制

Rate Limiting（速率限制）
- 错误码 17007：请求过于频繁
- 默认实现：自动重试 + 指数退避
- 建议：批量操作间隔 0.5-1 秒
Request Size（请求大小）
- 错误码 17008：请求体过大
- 已优化：分批创建（默认每批10个块）
- 单个块内容限制：建议 < 2000 字符
Authentication（认证）
- Token 有效期：expire_time 为 -1 表示长期有效
- Token 泄露：立即刷新并更新
- App Secret 泄露：在应用管理页面重置

最佳实践

Token 管理
- 使用 ~/.wolai_token 文件存储（权限 600）
- 定期刷新 Token（建议每 30 天）
- 生产环境使用环境变量
内容组织
- 重要对话：detailed + 添加标签
- 快速记录：compact + 批量同步
- 归档数据：minimal + 定期清理
错误处理
- 自动重试（3次）
- 详细错误日志
- 失败通知机制
页面权限
- 团队空间：在每个页面添加应用
- 个人空间：已自动授权
- 权限不足：错误码 17011

🔧 完整示例工作流

场景 1：日常对话记录

#!/bin/bash
# daily_sync.sh

# 配置
PAGE_ID="your-daily-page-id"
CONV_FILE="/tmp/daily_conv.json"

# 准备对话数据
cat > $CONV_FILE << 'EOF'
{
  "user": {"name": "张三", "id": "user_123"},
  "messages": [
    {"role": "user", "content": "今天的工作进展"},
    {"role": "assistant", "content": "完成了以下任务..."}
  ],
  "tags": ["工作日志", "2026-02-25"]
}
EOF

# 同步到 wolai
python3 scripts/sync_conversation_full.py \
  --token-file ~/.wolai_token \
  --page-id $PAGE_ID \
  --conversation-file $CONV_FILE \
  --format detailed

# 清理
rm $CONV_FILE

场景 2：项目讨论归档

#!/bin/bash
# project_sync.sh

PROJECT_PAGE_ID="your-project-page-id"
CONV_FILE="project_discussion.json"

# 同步项目讨论
python3 scripts/sync_conversation_full.py \
  --token-file ~/.wolai_token \
  --page-id $PROJECT_PAGE_ID \
  --conversation-file $CONV_FILE \
  --format detailed \
  --batch-size 5  # 小批量，更稳定

🐛 常见问题排查

问题 1：Token 无效（错误码 17003）

# 重新生成 Token
python3 scripts/wolai_token_manager.py \
  --app-id x4EaDyDbuh1Jkd7wrQcLXe \
  --app-secret 07995fd63d13d4b96dc54580430c2f8d792a054b0f3370c74e60669e7accfbd8 \
  --action create \
  --save

问题 2：权限不足（错误码 17011）

解决方案:

在 wolai 中打开目标页面
右上角菜单 → "页面协作"
"应用权限" → "添加应用"
选择你的应用

问题 3：请求过于频繁（错误码 17007）

解决方案:

增加批次间隔（默认 0.5 秒）
减少每批数量（默认 10）
已实现自动重试，无需手动处理

问题 4：请求体过大（错误码 17008）

解决方案:

减少每批数量（--batch-size 5）
缩短消息内容（智能摘要已处理）

📚 文档索引

文档	说明
`SKILL.md`	主要使用文档
`api_guide.md`	API 详细参考
`API_CORRECTION_NOTES.md`	API 修正说明
`OPTIMIZATION_SUMMARY.md`	优化总结
`README.md`	项目主文档

🎯 后续建议

测试验证
- 先使用测试页面验证
- 检查格式是否符合预期
- 确认权限配置正确
集成到工作流
- 创建每日自动同步
- 添加标签分类系统
- 设置重要对话提醒
性能优化
- 根据 API 限制调整批次大小
- 添加增量同步（避免重复）
- 实现失败重试通知
功能扩展
- 支持图片同步
- 添加对话搜索功能
- 实现多页面管理

✅ 检查清单

Token 生成成功
AppId 和 AppSecret 验证通过
完整工具链就绪
文档齐全
测试同步（需要 page-id）
生产环境配置
定期备份设置

状态: 🎉 集成完成，等待测试验证

下一步: 提供 page-id 进行首次同步测试！

📄 INTEGRATION_GUIDE.md

wolai-sync 完整集成指南

✅ 集成完成确认

1. AppId 和 AppSecret 配置

2. 成功验证

📦 完整工具集

1. Token 管理工具

2. 完整版对话同步工具

3. 配置验证工具

4. 增强版 API 客户端

5. 修正版 API 客户端（严格遵循文档）

6. 自动通知脚本

🚀 快速开始（3步完成）

第一步：验证配置（已完成 ✅）

第二步：创建测试页面

第三步：同步测试对话

📊 对话数据格式

示例文件

🎨 三种显示格式

detailed（详细格式 - 推荐）

compact（紧凑格式）

minimal（极简格式）

⚠️ API 限制与最佳实践

已知的 API 限制

最佳实践

🔧 完整示例工作流

场景 1：日常对话记录

场景 2：项目讨论归档

🐛 常见问题排查

问题 1：Token 无效（错误码 17003）

问题 2：权限不足（错误码 17011）

问题 3：请求过于频繁（错误码 17007）

问题 4：请求体过大（错误码 17008）

📚 文档索引

🎯 后续建议

✅ 检查清单