personal-wechat

通过 Wisdom 使用个人微信

使用用户自托管的 Wisdom 服务操作其个人微信账号。当前部署使用容器中的原生 Linux 微信，并提供 HTTP API 和用于登录及诊断的 VNC 桌面。

凭据由 personalwechat BYOC 连接器注入：

• PERSONALWECHAT_BASE_URL — Wisdom 服务的基础 URL，例如 http://203.0.113.10:8000。
• PERSONALWECHAT_API_TOKEN — Wisdom API_TOKEN。这是机密，绝不要回显、打印或记录。

辅助脚本会将令牌作为 Authorization: Bearer ... 发送；绝不会把令牌放进 URL。对于每个由 UI 驱动的操作（搜索、发送、朋友圈、群组），Wisdom 都会返回 202 和一个任务 ID；辅助脚本会为你轮询 /api/tasks/{id}，并且只打印最终结果。

这是用户的真实个人微信账号。读取操作会直接执行。每项写入操作——发送、分享、朋友圈、群组变更——都会先进行试运行，只有在用户明确批准该确切内容后才会执行。

CLI

该技能附带一个仅使用标准库的辅助脚本。在下面每个 Bash 代码块的开头运行此解析器——每次 Bash 调用都会启动一个新 shell，而且 $SKILL_DIR 指向本轮最后加载的技能，因此请以我们自己的脚本为准：

WX="$SKILL_DIR/scripts/personal_wechat.py"; [ -f "$WX" ] || WX=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/personal_wechat.py' 2>/dev/null | head -1)
[ -f "$WX" ] || { echo "personal-wechat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

首先验证连接

用户要求使用微信时，始终先查看状态：

python3 $WX status

预期的健康状态结构：

{"status":"ready","since":"…","wechat_running":true,"logged_in":true,"error":null}

/api/status 是唯一的连接状态依据。根据 status、wechat_running 和 logged_in 判断，除此之外不看其他内容。

现象	含义
status: "ready"，logged_in: true	状态正常，可继续。
status: "qr_scan" / logged_in: false	请用户打开 Wisdom 网页 UI / VNC，并用手机扫描微信二维码。
status: "preparing"	解密后的数据库快照仍在构建中。请等待并重试；完成前读取操作可能会失败。
status: "error"	向用户报告 error.code / error.message。
HTTP 401	请用户使用当前 Wisdom API 令牌重新连接 Personal WeChat 连接器。
连接被拒绝 / 超时	检查已连接的 Wisdom 实例 URL 和部署状态。

在原生 Linux 上，假设有可用的写入模式之前，先读取状态中的 weixin_client.capabilities。ready 表示已登录且数据已准备就绪，并不代表所有旧版 Windows API 都可用。特别是，当前原生部署支持 moments.read，但在微信的新设备安全限制解除之前，会以 HTTP 409 拒绝发布或删除朋友圈。

绝不要根据其他路径返回 404 就推断“微信已离线”——404 表示此 Wisdom 版本不存在该路由，并不表示账号已退出登录。

读取工作流

当前账号

python3 $WX account

联系人

python3 $WX contacts --limit 50
python3 $WX contacts --type group --limit 100
python3 $WX contacts --limit 100 --offset 100

--limit 每页上限为 200（Wisdom 的上限）。如需翻页，请使用 --offset，而不是要求更大的 limit。

会话

python3 $WX conversations --limit 20

每个条目的 id 都是 messages 所需的 conversation_id。此操作直接读取已解密的微信数据库，已经涵盖完整历史记录——无需单独的“历史记录”端点。

会话中的消息

python3 $WX messages "CONVERSATION_ID" --limit 50 --order asc
python3 $WX messages "CONVERSATION_ID" --limit 50 --offset 50

输出包含 mentions、quoted_text 和 conversation_type，因此你可以查看哪些人被 @ 提及，以及引用回复针对的内容。

某个时间戳之后的新消息

python3 $WX poll --since 1785000000 --limit 100

--since 是以秒为单位的 Unix 时间戳。间隔一段时间后，用它来查看新消息，无需重新读取整个会话。

朋友圈

python3 $WX moments --limit 30
python3 $WX moments --limit 30 --self-only

这是同步视图缓存，因此刚删除的帖子可能会一直显示，直到微信重新同步。

任务

如果写入操作似乎卡住，请检查排队中或已完成的 UI 任务：

python3 $WX tasks --limit 20
python3 $WX task TASK_ID

搜索

python3 $WX search "Alice"

搜索会驱动微信 UI，因此速度比上述本地数据库读取慢。发送前请使用搜索确认目标存在。

写入 — 全部需要确认

以下每条写入命令默认都会先进行试运行，并打印准备提交的确切载荷。只有使用 --confirm，或 AceDataCloud 定时任务已预先授权此 Skill 时使用 --unattended-confirm，才会执行。

向用户展示试运行结果，明确征得用户对确切目标和内容的批准，然后使用 --confirm 重新运行。首次尝试时绝不使用 --confirm。绝不能根据含糊的文字推断用户已同意。

发送消息

python3 $WX send "Alice" "今晚 8 点开会吗？"
# -> {"dry_run": true, "action": "send", ...}
python3 $WX send "Alice" "今晚 8 点开会吗？" --confirm

群聊中的真实 @提及。 使用 --mention（可重复指定）——Wisdom 会调用 WeChat 自带的提及弹出框，生成真正的 @通知。不要在消息文本中输入 @Name 并寄希望于此；那只是不会通知任何人的普通文本。

python3 $WX send "项目群" "记得今天交周报" --mention "Doms Jay" --confirm
python3 $WX send "项目群" "记得今天交周报" --mention "Alice" --mention "Bob" --confirm
python3 $WX send "项目群" "全员通知" --mention-all --confirm     # owner/admin only

发送结果会回显 mentions。如果你传入 --mention 后返回的值是 null，说明提及未生效——请告知用户，不要声称 @成功了。

引用回复。 回复该聊天中最新一条文本匹配以下内容的消息：

python3 $WX send "Alice" "这个我来跟" --quote-text "这个 bug 谁跟一下" --confirm

--quote-text 的优先级高于提及；如果没有找到匹配的消息，则退回为普通发送。

媒体。 Wisdom 会在其容器中下载 URL 并发送文件：

python3 $WX send "Alice" --type image --image-url https://example.com/a.png --confirm
python3 $WX send "Alice" --type video --video-url https://example.com/a.mp4 --confirm
python3 $WX send "Alice" --type file  --file-url  https://example.com/a.pdf --confirm

重试。 你未能看到结果的发送操作可能已经送达。重试时，传入相同的 --idempotency-key，这样 Wisdom 会返回原任务，而不是重复发送：

python3 $WX send "Alice" "hi" --idempotency-key daily-2026-08-04 --confirm

分享网页

share 会在 WeChat 浏览器中打开一个公开的 HTTP(S) 页面，并将其原生链接卡片发送给一个或多个联系人或群聊。--text 会为卡片添加消息。首先检查 status，确认其为 ready 且 logged_in: true，然后先对确切的 URL、文本和目标进行试运行，再确认：

python3 $WX share "https://example.com/article" "Alice" "项目群" --text "供参考"
python3 $WX share "https://example.com/article" "Alice" "项目群" --text "供参考" --key article-20261004 --confirm

该命令只调用 POST /api/share，并等待任务结果。检查每个目标的 succeeded、failed 或 not_attempted 结果以及 shared_url；任务成功本身并不能证明接收者收到了或阅读了卡片。页面在 WeChat 浏览器中重定向后，实际 URL 可能会发生变化。分享前会先在该账号自己的文件传输助手中留下一条 URL 消息。只有在同一 Wisdom 进程仍保留任务时，才使用 --key 进行去重；如果结果不确定或进程已重启，请先检查任务和聊天记录，再重新提交，以免重复发送。

朋友圈

首先检查状态能力。如果缺少 moments.write 或 moments.delete，请说明限制，不要声称已发布或删除。目前的原生 Linux 部署会对这些写入操作返回 HTTP 409。

python3 $WX moment-post "今天上线了新功能"
python3 $WX moment-post "看看这张图" --image-url https://example.com/a.png --visibility public --confirm

--visibility 可设为 public / private / partial / exclude（公开 / 私密 / 部分可见 / 不给谁看），默认值为 public。

删除操作不可撤销。match 必须是用户自己某条朋友圈中具有辨识度的子字符串；Wisdom 会拒绝有歧义的匹配，而不会猜测：

python3 $WX moment-delete "Veo Videos Generation API"
python3 $WX moment-delete "Veo Videos Generation API" --confirm

群聊

其他人可以看到这些操作——务必先确认确切的成员名单。

python3 $WX group-create "Alice" "Bob" --name "项目群" --confirm   # needs >= 2 members
python3 $WX group-invite "项目群" "Carol" --confirm
python3 $WX group-remove "项目群" "Carol" --confirm                # kicks; visible to the group
python3 $WX group-rename "项目群" "项目群 2026" --confirm           # renames for everyone

定时任务的无人值守确认

在 AceDataCloud 定时任务中运行时，平台可能会预先授权特定 Skill 以便无人值守执行。若以下条件全部满足：

• AICHAT_UNATTENDED_MODE=true
• AICHAT_ACTIVE_SKILL 为 personal-wechat 或 acedatacloud/personal-wechat
• AICHAT_ACTIVE_SKILL 出现在 AICHAT_UNATTENDED_ALLOWED_SKILLS 中

则表示用户已为该定时任务预先授权此 Skill。在这种情况下，使用 --unattended-confirm 代替 --confirm：

python3 $WX send "Alice" "今晚 8 点开会吗？" --unattended-confirm

如果 helper 返回 unattended_confirmation_denied，不要改用 --confirm 重试；请报告试运行结果，并说明需要在该任务的无人值守授权设置中选择此 Skill。

安全规则

• 切勿输出 PERSONALWECHAT_API_TOKEN。
• 将 PERSONALWECHAT_BASE_URL + API_TOKEN 视为对用户微信的完全控制权限。
• 执行任何写入操作前，都先试运行并征求用户明确批准，然后使用 --confirm 重新运行。
• 只有当平台环境变量表明此 Skill 已预先授权时，才使用 --unattended-confirm。
• 群聊和朋友圈的写入操作会对其他人可见；moment-delete 不可撤销。
• 如实报告实际发生的情况。如果 mentions 返回 null，则 @ 未生效。
• 除非用户明确要求修复服务，否则不要调用重启或注销端点。
• 仅通过 python3 $WX status 判断连接状态。其他路径返回 404，表示该路由不存在，而非微信已离线。

端点映射

此辅助程序封装了以下 Wisdom 端点：

命令	端点
status	GET /api/status
account	GET /api/account
contacts	GET /api/contacts
conversations	GET /api/conversations
messages	GET /api/messages
poll	GET /api/messages/poll
moments	GET /api/moments
tasks / task	GET /api/tasks、GET /api/tasks/{id}
search	POST /api/search
send	POST /api/messages/send
share	POST /api/share
moment-post / moment-delete	POST /api/moments、DELETE /api/moments
group-create / -invite / -remove / -rename	POST /api/groups、/invite、/remove、/rename

从 search 开始的所有命令都会排入 UI 任务队列（202 + 任务 ID）；其中写入操作还需要 --confirm 或经过验证的 --unattended-confirm。