社交空间相册

管理社交空间相册，支持扫码登录、浏览、上传、下载照片及创建相册，基于非官方API自动化操作。

Install

openclaw skills install @thcjp/qq-zone-photo

核心功能: 本技能提供自动化配置和灵活的参数设置等能力。

社交空间相册

社交空间相册的自动化管理工具，支持扫码登录、相册浏览、照片上传/下载、相册创建等功能。通过 qzone_photos.py 脚本调用社交空间非官方API实现自动化操作.

参数说明

参数名	类型	必填	说明
input	string	是	社交空间相册处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

付费版进阶功能

能力	免费版	付费版
基础功能	支持	支持
复杂工作流可视化编排	不支持	支持
条件分支与异常重试	不支持	支持
定时触发与事件驱动	不支持	支持
执行日志与审计追踪	不支持	支持
分布式任务调度与负载均衡	不支持	支持

安装与配置

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力矩阵

1. 扫码登录

通过 python3 （请参考skill目录中的脚本文件） --action login --cookies cookies.json 执行扫码登录。生成二维码供用户扫描，登录成功后自动将Cookie保存到指定的cookies文件中。Cookie包含 qq_number、p_skey、skey 和 uin 字段。适用于首次使用或Cookie过期后的重新认证.

2. 列出相册

通过 python3 （请参考skill目录中的脚本文件） --action list --cookies cookies.json 列出当前账号的所有相册。返回相册列表，包含相册ID（album-id）、相册标题、照片数量等信息。可选参数 --qq 指定目标账号。适用于浏览相册结构和获取相册ID。- 验证返回数据的完整性和格式正确性

3. 浏览相册照片

通过 python3 （请参考skill目录中的脚本文件） --action photos --album-id "ALBUM_ID" --cookies cookies.json 浏览指定相册中的照片。必填参数 --album-id 指定目标相册，可选参数 --qq 指定账号。返回照片列表，包含照片URL、缩略图、上传时间等信息。适用于查看相册内容和获取照片下载URL。- 验证返回数据的完整性和格式正确性

4. 上传照片

通过 python3 （请参考skill目录中的脚本文件） --action upload --photo "/path/to/image.jpg" --album-id "ALBUM_ID" --cookies cookies.json 上传照片到指定相册。必填参数 --photo 指定本地图片路径，--album-id 指定目标相册。可选参数 --qq 指定账号。适用于照片备份和迁移场景.

5. 下载单张照片

通过 python3 （请参考skill目录中的脚本文件） --action download --url "PHOTO_URL" --cookies cookies.json 下载单张照片。必填参数 --url 指定照片URL（从 photos action获取），可选参数 --output 指定下载目录。适用于选择性下载特定照片.

6. 下载整个相册

通过 python3 （请参考skill目录中的脚本文件） --action download-album --album-id "ALBUM_ID" --output ./downloads --cookies cookies.json 下载整个相册的所有照片。必填参数 --album-id 指定目标相册，可选参数 --output 指定下载目录（默认当前目录）。适用于相册全量备份场景。- 验证返回数据的完整性和格式正确性

7. 创建相册

通过 python3 （请参考skill目录中的脚本文件） --action create --title "我的新相册" --cookies cookies.json 创建新相册。必填参数 --title 指定相册标题，可选参数 --desc 指定相册描述，--qq 指定账号。创建成功后返回新相册的 album-id。适用于批量上传前的相册准备.

使用方法

首次使用执行扫码登录：python3 （请参考skill目录中的脚本文件） --action login --cookies cookies.json
列出所有相册获取目标 album-id：python3 （请参考skill目录中的脚本文件） --action list --cookies cookies.json
根据需求选择操作：浏览照片（photos）、上传照片（upload）、下载照片（download/download-album）、创建相册（create）
上传照片时指定本地图片路径和目标相册ID
下载照片时先通过 photos action获取照片URL，再执行下载
如遇Cookie过期，重新执行 login action获取新Cookie

结果验证: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤.

应用示例

示例1：扫码登录并备份整个相册

bash

# 扫码登录，Cookie自动保存到cookies.json
python3 （请参考skill目录中的脚本文件） --action login --cookies cookies.json
# 输出: 二维码已生成，请使用社交平台App扫描登录...
# 登录成功后: Cookie已保存到 cookies.json
# ...
# 列出所有相册
python3 （请参考skill目录中的脚本文件） --action list --cookies cookies.json
# 输出示例:
# 相册ID: V0003 | 标题: 旅行 | 照片数: 45
# 相册ID: V0005 | 标题: 2024毕业季 | 照片数: 28
# ...
# 下载整个旅行相册
python3 （请参考skill目录中的脚本文件） --action download-album --album-id "V0003" --output .json

示例2：创建相册并上传多张照片

bash

# 创建新相册
python3 （请参考skill目录中的脚本文件） --action create --title "2024毕业季" --desc "毕业旅行照片" --cookies cookies.json
# 输出: 相册创建成功，album-id: V0007
# ...
# 上传照片到新相册
python3 （请参考skill目录中的脚本文件） --action upload --photo "/path/to/graduation1.jpg" --album-id "V0007" --cookies cookies.json
python3 （请参考skill目录中的脚本文件） --action upload --photo "/path/to/graduation2.json
# ...
# 浏览相册确认上传结果
python3 （请参考skill目录中的脚本文件） --action photos --album-id "V0007" --cookies cookies.json

错误恢复方案

错误场景	原因	处理方式
Cookie过期	`p_skey` 或 `skey` 失效	重新执行 `--action login` 扫码登录获取新Cookie
相册ID无效	`--album-id` 指向不存在的相册	先执行 `--action list` 获取有效的 `album-id`
上传照片路径不存在	`--photo` 指向的文件不存在或路径错误	检查图片文件路径，使用绝对路径确保可访问
下载照片URL无效	`--url` 已过期或格式错误	重新执行 `--action photos` 获取最新的照片URL
创建相册标题为空	`--title` 参数缺失或为空	提供有效的相册标题字符串
Cookie文件格式错误	`cookies.json` JSON格式不正确	确认文件包含 `qq_number`、`p_skey`、`skey`、`uin` 四个字段且JSON格式有效
虚拟环境未激活	未执行 `source .venv/（请参考skill目录中的脚本文件）`	先激活虚拟环境再执行脚本命令
API接口变更	社交平台更新了非官方API	等待工具更新适配新接口，或手动提取Cookie

疑问速查汇总

Q1: 如何扫码登录？

执行 python3 （请参考skill目录中的脚本文件） --action login --cookies cookies.json 命令。脚本会生成二维码，使用社交平台App扫描二维码完成登录。登录成功后Cookie自动保存到指定的cookies文件中，包含 qq_number、p_skey、skey 和 uin 字段.

Q2: Cookie过期怎么办？

Cookie包含的 p_skey 和 skey 有时效性，过期后所有操作会返回认证失败。重新执行 --action login 扫码登录即可获取新的Cookie。建议在脚本中添加Cookie有效性检查，过期时自动触发重新登录.

Q3: 如何获取相册ID？

执行 python3 （请参考skill目录中的脚本文件） --action list --cookies cookies.json 列出所有相册。返回结果包含每个相册的ID（album-id）、标题和照片数量。使用返回的 album-id 进行后续的照片浏览、上传或下载操作.

Q4: 支持哪些图片格式上传？

上传功能支持常见的图片格式，包括JPG、JPEG、PNG、GIF、BMP等。通过 --photo 参数指定本地图片文件路径。建议使用绝对路径（如 /path/to/image.jpg）确保文件可访问。单次上传一张照片，批量上传需多次执行命令.

Q5: 如何批量下载整个相册？

使用 --action download-album 命令下载整个相册的所有照片。指定 --album-id 和 --output（下载目录）参数。例如：python3 （请参考skill目录中的脚本文件） --action download-album --album-id "V0003" --output .json。脚本会自动遍历相册中所有照片并逐一下载.

Q6: Cookie文件包含哪些字段？

Cookie文件（cookies.json）为JSON格式，包含4个字段：qq_number（社交平台账号）、p_skey（认证密钥）、skey（会话密钥）和 uin（用户标识，格式如 o0123456789）。也可手动从浏览器开发者工具（F12 -> Application -> Cookies）提取，但推荐使用扫码登录自动获取.

能力边界

依赖社交空间非官方API，平台接口变更后可能需要适配
Cookie有时效性，过期后需重新扫码登录
上传操作为单张上传，暂不支持批量上传
Cookie文件包含完整访问权限，需妥善保管
需要Python虚拟环境（.venv）已激活

创新特色

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
扫码登录	5分钟	1分钟	4分钟	100%
列出相册	10分钟	30秒	9分30秒	100%
浏览相册照片	30分钟	5分钟	25分钟	100%
上传照片	10分钟	1分钟	9分钟	100%
下载照片	30分钟	5分钟	25分钟	100%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
功能丰富度	高	低	中	高
操作便捷性	高	低	中	高
自动化程度	高	低	高	高
成本效益	高	低	中	高
学习成本	中	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
相册管理效率低	手动操作相册耗时费力，效率低下	个人或团队相册管理	自动化相册管理工具	时间节约50%
照片备份困难	照片备份需要手动操作，容易遗漏或丢失	个人或团队照片备份	自动化照片备份功能	备份成功率提升20%
相册迁移繁琐	相册迁移需要手动操作，过程复杂	相册迁移	自动化相册迁移功能	迁移成功率提升30%

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
扫码登录失败	Cookie过期或无效	检查Cookie文件，重新登录	更新Cookie或重新登录
相册列表为空	Cookie无效或API问题	检查Cookie文件，尝试重新登录	更新Cookie或联系技术支持
照片上传失败	图片格式不支持或文件损坏	检查图片格式和文件完整性	尝试上传其他图片或修复文件
照片下载失败	网络连接问题或文件损坏	检查网络连接，重新下载	检查网络连接或重新下载
下载速度慢	网络带宽限制	检查网络带宽，尝试优化下载策略	优化网络带宽或选择其他下载时间

安全提示

Cookie文件包含社交空间完整访问权限，请勿泄露或分享。
凭证仅存储在本地，不会上传到任何服务器。
会话Cookie有时效性，过期后需重新登录。
本工具使用社交空间非官方API，平台更新接口后可能需要适配。
定期备份Cookie文件，以防数据丢失。

安全风险防范

风险项	等级	防护措施	验证方法
Cookie泄露	高	使用加密存储，限制访问权限	定期检查访问日志
API调用限制	中	限制API调用频率，监控异常调用	监控API调用日志
数据损坏	中	定期备份数据，使用校验机制	定期检查数据完整性
网络攻击	高	使用防火墙，监控网络流量	定期检查网络流量日志
账号被盗	高	使用复杂密码，定期更改密码	定期检查账号登录日志

功能介绍

自动化执行: 管理社交空间相册，支持扫码登录、浏览照片、上传下载。社交空间相册自动化管理工具。支持扫码登录、相册浏览、照片上传/下载、
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果

快速开始

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

帮助文档

Q1: 社交空间相册支持哪些输入格式？

A1: 管理社交空间相册，支持扫码登录、浏览照片、上传下载。社交空间相册自动化管理工具。支持扫码登录、相册浏览、照片上传/下载、相册创建等功能。通过Cookie认证访。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。