微信智能助手（WeChat Assistant）

给登录在本机的微信桌面版加一层"智能值守"：盯聊自动回复 + 群管理。
本地运行、不注入、不破解——账号安全，可随时关掉。

v0.4 更新（试用 + 授权收费）

• v0.4.19 自动授权（付款时长 = 开通时长）：客户付款后自动开通，不用等客服手工发码。
  1) 付款窗口改成「选套餐 → 微信扫码付款 → 点一下『我已付款，申请开通』」三步；
  2) 申请（订单号 / 套餐 / 机器码 / 当前到期）由 scripts/license_apply.py 自动发到客服微信，
  发不出去就复制到剪贴板 + 桌面留 txt，绝不出现"点了按钮没反应"；
  3) 客户机上的助手会自动把客服回过来的授权码领回来并激活
  （scripts/license_claim.py，验签通过才认，伪造的码一律无效）；
  4) 卖家端 tools/license_bot.py（不随包）读客户申请 + 微信「收款到账」通知
  → 自动签发 → 自动回码，全离线、不要服务器、不要商户号；
  到账匹配从严：订单号优先 → 唯一金额 → 同价转人工（绝不猜、不串单）；
  读不到到账通知时自动降级为「--approve <订单号> 一键发卡」，不会漏单；
  5) 时长口径：到期日 = 起算日 + 套餐天数 − 1（1 个月给 30 天、1 年给 365 天）；
  续费以客户当前到期日为基准顺延，剩余时间不被吞掉
• v0.4.18 收费口径调整：试用 10 天；价目 1 个月 ￥60 / 2 个月 ￥100 / 3 个月 ￥150 /
  年卡 ￥199（半年卡、永久卡下架，老客户的卡仍能激活）；档位与价格只有一处数据源
  （seller.json），收款窗口 / 桌面授权提示 / 随包说明文档全部自动同步；
  「未付费 = 发不出消息」补成全链路：自动回复、群发、单发都要过 scripts/license_gate.py，
  而体检 / 查看授权 / 付款 / 激活 / 添加知识不拦（要留给用户付款）
• v0.4.17 付款到"扫码即付"：随包内置微信收款二维码（scripts/pay_qr.png），新增
  「付款续费」收银台窗口（scripts/pay_window.py，纯标准库）——微信扫码付款、套餐价格、
  一键复制机器码、拿到授权码当场粘贴激活，一个窗口完成整个购买（v0.4.19 起升级为付款后自动开通）；
  试用到期未激活时助手自动弹出该窗口（约 6 小时一次，不刷屏），试用最后 1 天先落桌面提醒；
  tkinter 不可用的老系统退化为系统看图打开收款码 + 桌面提示，绝不白屏
• 10 天免费试用：本机首次运行起算，功能全开，不要授权码
• 离线授权码激活：绑定机器码，付款后自动开通（也可手动粘贴授权码；无需重启、无需联网）
• 到期行为可预期：助手仍在运行、仍在监听，但不发送回复——一眼看得出来是"没授权"，不是"坏了"
• 授权状态随时可查（桌面「查看授权.bat」或 --license），激活向导带机器码和购买方式
• 一整套上架物料：tools/package_release.py 一键出干净发布包，含安装脚本与审核说明
• v0.4.1 签名升级：授权码改用 Ed25519 非对称签名——客户端只内置公钥，客户就算拿到整个代码包也伪造不出授权码（早期版本把对称密钥写在随包文件里，等于把签发能力一起送出去了）
• v0.4.1 不再丢单：同一人冷却期内、或每小时回复配额用完时，消息一律排队稍后补回（此前是直接丢弃 —— 客户问「有水果卖吗」可能永远没有回音）。每小时上限与最小间隔可用 config.json 的 max_per_hour / min_interval_s 调整
• v0.4.1 重启不丢消息（启动回扫）：助手停机期间到达、或被旧版丢弃的消息，启动时自动往回捞（默认 4 小时窗口，catchup_window_s 可调），进待回队列合并补回。监听水位文件也从 %TEMP% 挪到 data/listener_watermark.json（%TEMP% 会被磁盘清理清掉，清掉 = 停机消息再次静默丢失）
• v0.4.1 发送自愈（tools/test_send_channel.py 真机实测）：①用户把微信点进
  服务号/订阅号/通讯录等子页面后，助手会自动点回「聊天」标签再发 —— 以前这种
  情况会话列表整个换掉，所有消息都发不出去；②微信最小化/收进托盘时自动恢复窗口
  （不抢焦点）—— 旧版 SetWindowPos 对最小化窗口无效，恢复必然失败；
  ③滚动找到会话后不再滚回顶部（虚拟化列表会把刚找到的元素作废）；
  ④客户区坐标越界时拒绝点击，不再点进虚空
• v0.4.1 更省电：只监听私聊（不再轮询群聊/公众号）+ 轮询间隔放宽到 3 秒
  （listen_interval_s 可调），空闲 CPU 从约 22% 单核降到约 5%。新增运行中回扫（每 60 秒）兜住新会话首条消息
• v0.4.1 全链路不丢消息：模型临时不可用 / 发送失败 / 授权不可用期间，
  消息一律进待回队列指数退避重试（60s→120s→240s…上限 30 分钟），不再静默丢弃。重复提问（如「多少钱」问两遍）也能正常回复（去重只针对 2 分钟内的重复投递）
• v0.4.2 修复「答非所问 / 反复复读」（最关键的一条）：历史上下文里「谁是我」判错了。
  旧代码按 sender_id == 1 判自己，而扫描全部会话实测 1 从未出现（自己=2，对方=4/5/11/12/16）
  —— 于是助手自己发出的每条回复都被标成「对方」，模型把自己的话当成对方的话来接，
  表现就是答非所问、抓着上一句反复复读（真实案例：客户连说「不要不要回复重复的问题」）。
  现在按 sender_id == 2 判自己，并且历史消息按 对方→user / 我→assistant 分派，
  模型能明确分清双方各说了什么
• v0.4.2 上下文不再被自己的话挤爆：以前固定取最近 8 条，助手连发几条就把对方真正的
  问题挤出窗口，模型看不到问题只能瞎答。现在保证上下文里至少含对方最近 3 条提问
• v0.4.2 纯表情不再瞎编：对方发 [抱拳]/[炸弹] 这类表情包（入库存的是 [表情名]
  纯文本占位符，类型仍算「文本」），以前会拿去问模型，模型只能凭空编（实测回过
  「好的，大苹果100斤多少？」）。现在识别为纯表情后走自然短应和（嗯嗯/好嘞/收到…），
  不调模型 —— 更快、更省内存、也更像真人
• v0.4.2 知识库里没填的模板不再被当信息用：资料库里留着的「（示例…）」「（填：…）」
  「XX 元」这类占位行，以前会整段喂给模型，模型会照搬当答案（曾出现回复里带
  「大苹果100斤 XX 元」）。现在按行过滤掉这些占位内容，只保留真正填写过的内容
• v0.4.2 提示词加固：明确要求不重复自己上一句、不凭空提「下午两点见」这类没发生过的
  约定、不说「库存充足/可以的」这类替客户担保的话、不出现 XX 占位符
• v0.4.3 修「把消息发给同名的人」（串号，比不回更严重）：本机实测有两个联系人都叫
  「快乐天使」，它们在微信 UIA 里的会话项 AutomationId 完全相同（session_item_快乐天使），
  旧代码取第一个匹配 → 回复发给了错误的那个人：真正在问「请回答我」的客户永远等不到回音，
  另一个同名人却莫名收到回复（而且发过一次之后错误会话被置顶，之后每次都错）。
  现在发送前用会话项 Name 里的「最后一条消息摘要」精确比对来选中正确会话；
  若对比不出唯一项（或摘要都对不上）就放弃发送并告警，绝不冒险 ——
  启动时也会把重名联系人列出来提醒（建议给其中一个加「备注」彻底区分）。
  文件名不同但昵称相同的场景（备注为空）都能被这个机制兜住
• v0.4.3 修「同名时乱降级，结果还是发错人」：微信聊天输入框的无障碍名字有时读出来是
  「快乐天使按住鼠标 语音输入文字」（微信自己追加的提示语），旧代码用精确等于判断
  「会话是否已打开」，于是误判「点了会话项但没能打开」→ 降级到屏幕通道 ——
  而那条通道按昵称定位，在同名联系人场景下又把消息发给了错误的人（13:16 实测）。
  现在输入框名改用宽松匹配；并明确规定：只要该昵称存在同名联系人，任何失败都不降级
  （宁可晚发，不可发错）。（注：v0.4.12 起屏幕通道已整体下线，不再存在"降级"这条路 —— 这一条只作历史记录。）另外识别会话的线索也扩充为「该会话在库里的真实最新一条消息
  / 我方最近发给它的回复 / 对方原话」三条，按可靠性依次尝试 —— 单独用「对方原话」会
  在「我方已经回过一条、摘要变成我方那一条」时白白匹配不上而放弃发送（13:13 实测）
• v0.4.3 去重改用消息编号（local_id）：以前按「内容相同」判重复，于是客户把同一句
  再问一遍（「在吗」「多少钱」「有货吗」）会被当成重复静默跳过。现在按微信库里的
  消息唯一编号判定 —— 只有同一条消息被重复投递才算重复，真人再问一次一定会回
• v0.4.3 停止词不再误杀正常咨询：以前「关掉」是子串匹配，客户说
  「能帮我关掉自动续费吗」也会被当作停止指令静默吞掉（等于丢单）。
  现在停止词只在「整条消息基本就是它」时才生效
• v0.4.4 用「会话选中态」确认打开的是哪一个会话（最可靠的一招）：微信会话项自带
  选中状态，点谁谁变 selected=True。实测两个同名「快乐天使」的会话项，点 A 后只有 A
  变 True、同名的 B 保持 False —— 于是发送前能精确到「哪一个」确认会话已打开，
  不再依赖易误判的窗口文字
• v0.4.4 输入框名字改精确匹配（防「子串误发」）：上一版为修「带后缀」问题改成了
  「包含即匹配」，但这个口子太宽 —— 本机实测存在联系人「.」与「Z.」，回复「.」时若
  当前开着「Z.」，会被误判成「目标会话已就绪」，把消息写进 Z. 的输入框发出去。
  现在先剥掉微信追加的提示语后缀（按住鼠标 语音输入文字）再要求完全相等
• v0.4.4 非文本消息不再石沉大海：以前 type != "文本" 一律 return —— 客户发
  语音 / 图片 / 视频 / 位置 / 表情包等于完全没有回音（实测本机就有客户发图片没收
  到任何回复）。现在这些类型会转成 [图片]「[语音]」这类占位符，跟普通消息走同一条
  流水线（冷却/配额/去重/待回队列全都照走）并自然应和一声；同时把「只含占位符」的
  消息判为「无需动脑」，不调模型免得多花时间。转账/红包/文件/链接/系统消息仍完全不回复
• v0.4.4 不再拿 XML 污染模型上下文：卡片/图片消息的正文其实是
  <?xml version="1.0"?><msg><appmsg… 这种原始 XML，而上下文构建原先不分类型全塞给
  模型 —— 模型看到一堆标签自然答非所问。现在统一清洗：XML 卡片会被剥成可读文字
  （实测「梦楠轩果品报价 10月7日」），纯标签的直接丢弃
• v0.4.4 「回声」过滤只在自测模式生效：以前正式模式也会把「客户说的话和助手刚说过
  的完全一样」当成回声跳过 —— 客户跟着说一句「好的」「收到」就被静默吞掉。现在只用于
  文件传输助手的自测（那里收发双方都是自己，不挡会自问自答）
• v0.4.4 去重记住最近一批消息编号：以前只记「最后一条」，监听器乱序重投（A A B A）时
  那条更早的 A 会被当成新消息再回一遍，对方就收到重复消息
• v0.4.5 「按收到信息识别，不按名字识别」（识别逻辑的根本性改变）：
  昵称不是身份 —— 本机真实存在两个都叫「快乐天使」的联系人（会话项的 AutomationId
  完全相同），也真实存在名叫「.」和「Z.」的联系人；用户给联系人加备注改名之后，
  旧昵称在会话列表里更是直接定位不到。v0.4.3/v0.4.4 的做法仍是「先按昵称筛，再靠摘要
  在筛选结果里挑」，根子上还站在名字上。v0.4.5 彻底换掉：
• 选址：遍历全部会话项（不按昵称过滤），用每项 Name 里的「最后一条消息」
  当内容指纹，与「我们要回复的那条消息」精确比对，唯一命中即目标。同名联系人、
  备注改名、子串误匹配在这里一并消失；
• 复核：点开会话后再读聊天区气泡正文（mmui::ChatTextItemView.Name 就是消息
  文本），只有聊天记录里真的出现了那条消息，才认定「当前打开的就是目标本人」——
  这是整套逻辑里唯一完全不依赖任何名字的确认手段；
• 真机铁证：给发送端传一个根本不存在的昵称，只給「收到的那条消息」当线索，
  消息依然准确落进了正确的会话（tools/verify_content_identify.py）；
• 指纹太短（「好的」2 字）、或两条会话最后一条内容雷同 → 不碰运气，宁可放弃发送
• v0.4.5 修「回扫把同一条消息反复捞」：配额满/冷却中/发送失败时 replied 不会前进，
  于是同一条消息每过 120 秒就被运行中回扫重新捞一次（真机 14:04→14:18 连刷 8 次
  「捞回 1 条漏掉的消息」，而那条消息早在待回队列里等着）。现在每人一份回扫水位
  (create_time, local_id)，扫过的消息一律推进水位；消息不会丢 —— 捞回后由待回队列负责重试
• v0.4.5 修「待回补发失败 → 客户收到双份内容」：从待回队列补发失败时，旧逻辑会把
  「合并后的整段」当新消息再追加回队列，下一轮合并出「t1；t2；t1；t2」。现在补发路径
  不再回填（原条目本来就在队列里）
• v0.4.5 启动不再卡在「检查模型服务」：ensure_ollama 和保活守护原先用
  taskkill 杀 Ollama/助手进程，而本机 taskkill 会挂死（项目里早记过：杀进程要用
  psutil）—— 表现就是日志永远停在「启动[2/4] 检查模型服务…」，看着像启动卡死。
  现在统一改成 psutil 优先 + taskkill 兜底并限时
• v0.4.6 助手终于能「真正常驻」了（本版最要命的修复）：
  现象是「日志明明显示启动成功，几十秒后进程凭空消失」，而且日志干净得
  没有一行 traceback。根因不是崩溃，是被静默杀死 —— 工具调用 / 自动化任务
  跑在一个 Windows job object 里，任务结束时 job 关闭，job 内的进程会被
  TerminateProcess 整体带走。旧 launch() 用的
  DETACHED_PROCESS | NEW_PROCESS_GROUP | NO_WINDOW 只解决「无窗口 / 独立进程组」，
  并不脱离 job，于是「调用 → guard → 助手」全在同一 job 内，任务一结束就一起死。
  现在启动改走 WMI 的 Win32_Process.Create（由 WmiPrvSE.exe 代创进程），新进程
  的父级不再是本 job，才真的留得住。实测对照：改造前助手活不过 30~50 秒；
  改造后 supervisor / 助手本体 / 锁屏守护连续存活，且 guard.log 每分钟稳定出现
  一条 ok —— 说明 supervisor 正在自动巡检。用地表探针做的对照实验同样证实：
  WMI 启动的进程在启动它的那次调用结束 3 分钟后仍在写日志
• v0.4.6 修「pythonw 下 print 把进程带走」：pythonw.exe 启动时
  sys.stdout 是 None，裸 print() 会抛 AttributeError 直接终止进程。
  assistant_supervisor 正是栽在这里 —— 它由 pythonw 拉起，第一句
  print("supervisor started…") 一执行就退出，而 pid 文件已经先写好了，
  外面看到的现象就是「启动了，但立刻没了」，怎么都活不住。现在 supervisor、
  主程序、锁屏守护的入口都做了流兜底（_fix_streams），print 永远安全
• v0.4.6 修「启动还没完成就宣布成功」：wait_ready() 原来只比心跳时间戳
  大小、不校验写心跳的 pid，于是新助手刚启动时读到的是上一个已死实例留下的
  旧时间戳，紧接着读到新实例的第一条心跳就认为「推进了」——1 秒内就宣布
  「已启动并确认在跑」，实际还在连微信数据库，用户白等一场。现在 pid 一起校验；
  又因为主循环每 5 秒刷一次心跳，返回时机正好等于「已经跑进轮询、真的能收消息了」

• v0.4.6 新增退出码账本：助手改由一层 replier_runner.py 转发启动，它把
  「退出码 / 存活时长 / 启动异常」记到 data/last_exit.json（保留最近 10 次），
  --status 会直接显示「上次退出: pid=… 码=0xC000013A 存活=…s」。以后万一助手
  又死，一眼就能区分是崩溃（码 1）、被内存限制杀（0xC000012D）、还是被外部强杀

• v0.4.8 修「刚才还好好的，忽然就不回了」（2026-10-07 用户实报）：微信 4.x 把
  整棵 Qt 无障碍树藏在一个运行时 gate 字节（Weixin.dll 里那一个 byte）后面。
  这个字节被微信自己重置回 0 之后，UIA 就只剩 Qt 空壳 —— 窗口在、IsWindow 为真、
  句柄有效，但 GetChildren() 什么都返回不了：会话列表和左侧标签栏一起消失。
  日志只留一句「UIA 没找到左侧「微信」标签」，消息全部堆进待回队列，而且永远不会
  自愈（旧 _ensure_window 看到句柄有效就 return True，从不重新物化）。
  因果链实测坐实：19:24 / 19:29 连续两次失败 → 19:37:59 体检进程热写 gate（0 -> 1）
  → 19:39 立刻恢复正常发送。现在 uia_sender 增加 _ensure_materialized()，
  在发送快路径上先确认树的活性：树是好的只是一次轻量检查（实测 0.01s），是空壳就
  热写 gate 并校验（实测 0.24s 恢复）；_back_to_chat_tab() 找不到标签栏时也会
  再兜一次。真机复现验证：人为把 gate 写 0（树物化变 False、而 IsWindow 仍为 True）
  → 走一次发送快路径 → 0.24s 后树恢复、发送正常

• v0.4.8 修「同名联系人串号 · 且会自我锁死」（2026-10-07 用户实报「有信息没有
  回复」，与上一条是同一天、两个独立故障）：本机两个联系人都叫「快乐天使」，
  真机实测 A 连问 6 句只收到 1 条回复，而另一个人 B 被硬塞了 5 条回复。
  根因不是选址 —— 按内容指纹选址是对的；是「已打开」判定错了：
  deliver() 把我方历史回复也当身份线索传给通道，而
  _opened_now() → _chat_body_confirms() 会拿这些线索去比对当前开着的那个
  聊天。一旦某条回复被投给了同名的 B，它就被 _mark_sent 记成「发给 A 的」；
  下一轮它出现在 B 的聊天正文里 → 被判定「目标会话已经开着了」→ 不点击、
  直接往 B 发 → 错误又被记录一次 → 一轮轮自我加固，A 永远收不到。
  日志特征很明显：失败的发送没有「点击开会话」这一行。
  现在线索分强（对方发来的话：库里最新一条入站消息 + 对方原话）/
  弱（我方历史回复）两级 —— 新增 UIASender._split_probes()，
  强线索用于选址 + 打开后复核，弱线索只用于非重名时的选址兜底、
  永不参与复核，重名时完全不用（宁可拒发）。deliver() 同时把
  「库里最新一条」按方向过滤，只取入站消息（原来可能取到我方回复，
  等于把弱线索混进了强线索）。
  真机验证：修复前 A 的 6 条提问只回 1 条、B 收到 5 条；修复后补回的回复
  准确落进 A（点击[开会话:快乐天使] 这一步回来了），B 再无新增。
  tools/test_session_pick.py 回归 31/31 通过

• v0.4.9 让助手「完全不打扰」（2026-10-08 用户问「能不弹窗吗」）：助手原来在
  三个地方会抢用户的前台焦点 / 改动用户的窗口，用户的直观感受就是「弹窗」：

① _ensure_window() 里的隐藏激活：句柄未知时会走库的
ensure_window(wake=True)，而它内部会调 _activate()（AttachThreadInput +
BringWindowToTop + SetForegroundWindow）把微信强行置前。长驻助手只会在
首次绑定句柄时踩到一次，但每次新建发送器的调用（群工具、体检、自测）都会踩。
现在先走新增的 _find_main_window_noactivate()：只读枚举 mmui::MainWindow，
找到就直接用，前台岿然不动；只有窗口彻底找不到 / 树退化成 Qt 空壳，才允许
回落走唤醒通道（并记一条日志说明）。

② _post_click() 点活窗口：微信（Qt）收到我们投递的鼠标消息后会自己
activateWindow() —— 真机实测：点一下会话项，前台立刻从 WorkBuddy 变成微信。
现在 _post_click() 外包一层 _keep_foreground()：只在「微信抢了前台」时
立刻 SetForegroundWindow(原窗口) 还回去（实测直接生效，无需 ALT 技巧），
用户自己切走的窗口则一律不碰。send() 的 finally 还会再兜一次 —— 实测点
「发送」按钮后微信是稍后才激活的，单次点击那 0.3s 的窗口盯不到。

③ _ensure_visible() 改了窗口就不还原：为把最小化 / 收进托盘 / 过窄的窗口
恢复出来（否则 UIA 控件树是空的、什么都做不了），旧代码会把它设成 1280×800 挪到
屏幕左上角，用完不还原 —— 用户看到「微信自己蹦出来、尺寸还变了」。现在恢复前
先 _snapshot_place() 用 GetWindowPlacement 记下原状（含 showCmd，所以连
「原来是最小化」都能记准），发送流程 finally 里 _restore_place() 原样还原；
体检 probe() 与群工具 list 同样会还原。

真机验证：_ensure_window 前后前台都是 WorkBuddy；点会话项触发激活后 0.10s
内恢复、最终前台仍是 WorkBuddy；真发一条消息到「文件传输助手」成功（微信库核实
20:08:42 我 【静默自检2】焦点保持测试）且焦点全程未丢；窗口最小化 → 恢复
1280×800 → 还原 1269x794 @(152,110) showCmd=2，与原状完全一致。

• v0.4.9 群工具改走静默通道：scripts/wechat_group_tools.py 重写。旧版依赖
  wx4py（会擅自重启微信：检查注册表 RunningState 发现是 0 就"修复并重启"）+
  pywinauto（本机未装，一调用就 ModuleNotFoundError），且 ensure_window_visible()
  用 SetForegroundWindow + 模拟按键把微信抢到前台。现在只保留能静默完成的能力：
  list / send / broadcast，全部走 UIASender.send()（PostMessage 点击 +
  ValuePattern.SetValue 写文本，不敲键盘、不需前台）。
  实测：微信的搜索面板在 UIA 树里是空的（纯自绘，读不到任何输入框），所以
  「搜索打开会话」无法静默实现 —— 群必须出现在会话列表里才能一键静默发送
  （微信会把不常看的群折叠进「折叠的聊天」，此时请先在微信里点开它一次，它就会
  回到列表顶部）。相应地，读群成员 / 改群公告 / 改群昵称 / 免打扰 / 置顶这些要点击
  群设置面板（同样自绘）的能力已彻底移除 —— 命令不再存在，输入会被当作未知命令。

• v0.4.10 修「客户发来贴纸后不回」（2026-10-08 事故）：客户发来一个动画表情，
  助手却一直拒发、消息卡在待回队列 —— 根因是 MSG_PLACEHOLDER 把「动画表情」写成
  [表情]，而微信会话列表实际渲染的是 [动画表情]；发送时的「按收到信息识别」
  拿这个占位符去比对会话摘要，自然对不上。落到同名联系人（本机两个「快乐天使」）身上
  就是直接拒发（宁可漏发也不发错人的保护逻辑被触发）。
  改动：占位符与微信渲染文字对齐（[动画表情]）。
  真机验证：客户会话 …q22 收到补回的 20:21:53 我 知道了，另一个同名的 …z22
  无任何新增；补回时日志出现 UIA 点击[开会话:快乐天使]（精确命中带未读角标那一项）。

• v0.4.11 修「加了备注还显示重名」（2026-10-08 用户「加备注」）：用户给同名的其中一个
  联系人加了备注（显示名变为「快乐天使A」），重名其实已经解除、启动日志也不再告警，
  但 state.json 的 ambiguous_nicks 仍写着两个 wxid，看起来像「加备注没用」。
  根因：启动时只在 _amb 非空才写 state，为空时什么都不做 —— 从磁盘读回的旧值清不掉，
  重启也不消失（runtime 的 refresh_targets 同理，只刷新内存集合、不回写 state）。
  改动：解除时即时写回 st["ambiguous_nicks"] = {} 并打「✅ 重名已解除」日志；
  运行期复检发现解除也会写回。真机验证：get_nickname 分别为「快乐天使」/「快乐天使A」。

• v0.4.12 下线「屏幕通道兜底」+ 剔除聚合行 + 三条发送可靠性加固（2026-10-08，发布前全量测试挖出的事故）：
  ① 屏幕通道兜底已彻底停用。旧逻辑是「UIA 不成功就降级到屏幕通道」，但那条通道
  （截图 + 鼠标 + 键盘，guia.WeChatGUI）按昵称定位会话、无法复核开着的到底是谁，
  定位一旦失败就把消息发给当时正开着的会话。日志回看：屏幕通道共 16 次发送，至少 4 次
  发错人（全部发生在重名/改名/聚合行的会话上），而 UIA 通道 114 次发送零串号。
  现在只保留 UIA 一条通道；发不出去就把消息留在待回队列里重试（4 小时内有效），
  日志明写 屏幕通道兜底已停用。自检脚本 scripts/selftest.py 也改走 UIA 通道，
  避免「自检全绿、实际发不出去」。
  ② 会话列表里的聚合行不再参与内容指纹选址（AGGREGATE_SESSION_NAMES）：
  「折叠的聊天 / 服务号 / 公众号 / 订阅号消息」这些行的摘要栏显示的是被折叠进去的
  某个会话的消息正文，别人的话会伪装成它自己的话。这正是一起真实串号事故的根源 ——
  客户「晴天」问「国际注会有几个特评名额…」，内容指纹命中了「折叠的聊天」这一行
  （晴天本人的会话当时不在可视区，聚合行成了唯一命中项），随后点击失败触发降级，
  消息被发进了「张老师」的聊天，而晴天一直没收到回复。
  回归测试：tools/test_session_pick.py 新增 F 节（聚合行判定 / 剔除 / 反证），37/37 通过。
  ③ 修「一键自检阶段 3 永远 FAIL」：ask_llm 自 v0.4.2 起收 (角色, 内容) 元组，
  但 scripts/selftest.py、scripts/keytool.py 仍在传 v0.3 的 "对方: 内容" 字符串，
  于是字符串被当二元组解包 → ValueError: too many values to unpack，自检恒报
  「回复生成链路异常」。现两种格式都收，自检 23/23 全过。
  ④ 发送前给窗口做几何体检（uia_sender._window_usable）：句柄活着 ≠ 窗口可用 ——
  实测缓存句柄的客户区只有 215x28，点击坐标会算成 3 万多，每条消息都被「坐标越界」
  挡下（客户连发 3 条全失败）。现在几何异常就丢掉缓存句柄、重新定位主窗口
  （只读枚举，不抢焦点）。
  ⑤ 「在途发送」不再静默丢失：旧逻辑是「先把回复写进输入框、再点发送」，如果这个
  过程中助手进程被重启/强杀（用户点了重启、或升级），那条回复既没进待回队列、
  也没出现在日志里，客户永远等不到（实测丢了一条「你怎么不回复」）。现在发送前
  先把意图落盘（st["inflight"]），启动时 recover_inflight() 去微信库里查证据：
  库里能看到那条回复 → 判定已发出、不重发；看不到 → 放回待回队列重发；库读不出来 →
  按「宁可漏发不重发」不自动补，并提示人工确认。回归测试见 tools/test_reply_queue.py
  第 17 节（4 个分支 + 源码守卫），113/113 通过。
  ⑥ 修「滚动找回的会话项被丢弃 → 客户永远收不到回复」：_find_session_recovered()
  已经把列表滚到位、把目标会话项返回了，但旧代码把这个返回值丢掉，紧接着又按昵称
  重新枚举一次 —— 而会话列表在这几毫秒里可能已经滚回原位、或被新到的消息顶到顶部
  重排，枚举结果为空，于是日志先写「UIA 滚动第 1 屏后找到会话「快乐天使」」、
  紧接着又写「会话列表里找不到「快乐天使」」，客户连发 5 条条条如此。
  现在非重名时直接采用滚回来的那个控件引用（why="滚动后按昵称找回"）；
  重名（strict）时仍然拒发 —— 按昵称找回的那一项可能是同名的另一个人，
  那正是「把甲的话发给乙」。回归测试见 tools/test_open_session.py F 节
  （含用旧代码复现缺陷的对照组），16/16 通过。
  ⑦ 顺带清掉状态文件里只写不读的历史字段 pending（v0.4.8 起发送失败已统一走
  pending_msgs 排队，那条老队列再没有任何代码读它）。留着它会让排查者误以为
  「还有一条消息没发出去」—— 和「加了备注还显示重名」（v0.4.11）是同一类毛病。

• v0.4.17 完善收费入口 —— 付款到"扫码即付"（2026-10-09；用户原话是
  「完善收费入口，试用期结束提醒交费，可用微信直接支付，加微信收款二维码到技能里」）：

以前到期只有一张桌面 txt 提示，付款还要"先联系客服 → 报机器码 → 等授权码"，
中间每一步都可能流失。现在：

① 随包内置微信收款二维码（scripts/pay_qr.png）—— 换码直接替换图片文件，代码不用动；
② 新增「付款续费」收银台窗口（scripts/pay_window.py，纯标准库 tkinter，无新依赖）：
微信扫码付款、套餐价格、一键复制机器码、拿到授权码当场粘贴激活，一个窗口完成整个购买；
③ 试用到期未激活时助手自动弹出付款窗口（与桌面授权提示同节拍，约 6 小时一次不刷屏）；
试用最后 1 天先落桌面提醒；窗口进程独立于助手（DETACHED），助手停掉窗口也不消失；
④ tkinter 不可用的老系统两级兜底：命令行版 licensing.py pay → 系统看图打开收款码 + 桌面
文字提示，绝不白屏；⑤ 入口铺四处：桌面「付款续费.bat」/ 包内同名启动器（平台包 .py）/
对话直说 / licensing.py pay。
回归测试：tools/test_pay_entry.py 25 项（含真机 Tk 建窗渲染、PNG 解码），全绿。

• v0.4.16 新增「添加知识」入口 —— 不用再手改文件（2026-10-09；用户提的原话是
  「增加一个上传知识信息入口，便于提交相关信息，回复时可以根据知识库提取相关信息」）：

以前加知识只有一条路：打开 knowledge/ 用记事本改。于是反复踩三类坑 —— 存成 ANSI/GBK
（v0.4.14 之前会被整份丢掉）、格式写歪、以及最要命的改完不知道助手到底读到没有。
现在多了 scripts/knowledge_tool.py（客户端双击「添加知识.bat」、平台包运行「添加知识.py」、
也可以直接对助手说「帮我加一条知识：客户问发货时间 → 当天下午5点前下单当天发」）：

① 加一条问答：客户问 X → 你答 Y。同一问句再写会就地更新而不是留两条 ——
两份矛盾的口径都会被模型读到，可能照着旧答案回客户。
② 加一个版块：价格表 / 发货时间 / 售后政策…。已存在则并入并给重复行去重
（反复导入同一张价目表不会越滚越长），也可整节替换，位置保持不变。
③ 导入文件 / 剪贴板：Excel 价目表「另存为 CSV」直接导入 —— 自动识别表头、转成
- 品名 | 规格 | 价格 并补一行列名说明（否则模型不知道「68」是价格还是重量）；
GBK 存的 CSV 也读得进（中文 Excel 默认就是 GBK）。
④ 写完当场复核 —— 这是这个工具存在的理由：它直接 import 助手主程序，用助手本人的
解析规则核对：哪些文件生效/为什么没生效、这次写的内容助手有没有真读到、哪一行会被当成
没填的占位符静默忽略（如含 XX 元，或括号没闭合会连带吞掉后面几行）。有问题当场说清，
不让任何内容无声消失。
⑤ 每次写入自动备份（knowledge/.backup/，留 30 份），可一键恢复；写入是先写临时文件
再原子替换 —— 中途出错卖家整份资料不会没。备份时间戳精确到微秒：只到秒时同一秒内连写
两次会互相覆盖，等于没备份。
⑥ 模拟检索：--check --ask "芒果多少钱" 直接看助手这次会拿到哪几段，卖家能自己验口径，
不用等客户来问。

真机验证：写入 → 复核显示「已被助手读到」→ 检索命中；300 条报价（8840 字）里埋在第 248 行的
「雪莲果」在按需提取下被精准命中，而客户问「在吗」时那 300 条价目表一条都不会被拉进
prompt（不干扰闲聊）。回归测试 tools/test_knowledge_tool.py 41 项全绿。

• v0.4.15 第二轮对抗测试再堵 6 个「静默出错」的坑（2026-10-09）：

① 运行状态被改坏时表情应和会崩：state.json 里 sent_by_us 的条目被手改成
字符串 / 数字 / null（或把 at 写成 "abc"）时，表情应和与自测回声检测会直接
AttributeError / ValueError 崩；现在条目级自愈（散值剔除、at 兜成数字），
应和函数本身也加了双保险。
② 文件中部混入的 BOM 会让该节标题认不出（整节退化成「无标题」，失去常驻与去重身份）
—— 上一版只处理了首部 BOM，这次读入时全局剥离 \ufeff。
③ 常驻小节没有去重：买家贴一整篇 5000 字《回答口径》会被切成十几块全部塞进
prompt，实测吃掉 1600 字预算的 96%，客户问的货号只剩几十字的缝；现在常驻块同样限
「同标题 2 块」，把预算留给真正的问答。
④ 知识库文件名排除规则过宽（startswith("readme")）：买家把资料存成
「readme价格表.md」会被静默忽略（资料无声消失、日志里一条都没有）；现在只排除
恰好叫 readme 的说明文档。
⑤ 停止词误杀：客户问「你那个停止监听的按钮在哪」会被判成停止指令、真消息被
静默吞掉；现在整句带疑问标记（吗/呢/？/怎么/在哪…）时按「在问功能」处理，不放行。
⑥ 同轮把上一版「自愈不能误伤有效内容」的断言修正为合法条目校验（旧断言把
「sent_by_us 里的裸字符串原样保留」当成正确行为，正是 ① 的成因）。
回归测试：知识库 92 项 / 回复队列 149 项全绿。

• v0.4.14 把知识库「静默失效」的路一条条堵上（2026-10-08 对抗性测试挖出 7 个真缺陷，
  共同的坏毛病是出了问题不吭声：卖家看到的现象只有「助手不按我写的答」）：

① GBK / ANSI 保存的资料库以前被整份丢掉。中文 Windows 上「记事本 → 另存为 ANSI」、
写字板、cmd 的 echo xxx > 文件.md 存出来都是 GBK；旧代码读它抛 UnicodeDecodeError，
然后 except: continue —— 整份资料库静默消失，日志还显示「知识库=0字」，
卖家完全无从排查。现在按编码链读（UTF-8 / UTF-8+BOM / GBK / GB18030 / UTF-16），
读不出来的会指名道姓报出来（哪个文件、什么原因、跳过还是降级），不再闷掉。
② UTF-8 带 BOM 会让首节丢掉「常驻」身份。BOM 字符粘在首行 【发货时间】 前面，
标题正则认不出它 → 首节变成「无标题」；而首节通常正是「回答口径」（那一条
「资料里没有的价格不许编造」），一失去常驻就可能被相关性筛掉，模型转头自己去编价格。
改用 utf-8-sig 读，BOM 直接吃掉。
③ 占位过滤误伤真实内容：XX 无边界匹配，把服装尺码「XXL 码卫衣 79 元」整行删掉；
待定 把真实的「秋月梨价格待定，到货后通知」也删了 —— 那是要回给客户的话。
现在 XX 后面跟字母数字就不算占位（XXL / XXXL 安全），待定 从词表移除。
④ 没写右括号的说明行会吃掉整个文件：实测一行「（示例：这里我还没写完」把后面
【售后】【价格】全删了。现在连带删除最多 6 行，且撞到下一节标题立刻收手。
⑤ 一整行几千条报价（Excel 粘贴的常见形态；实测 114876 字挤在一行）：旧写法整行
只算「一节」，注入时又从第 1 个字截断 —— 客户问第 8888 条，模型看到的是第 0~100 条的价，
于是照着别人的货号报了价。现在超长行按长度切成小块（优先切在 ｜、, 这类分隔符后），
并新增长串命中加权（客户原话里 ≥3 个字整段出现在某节时强烈加分）——
实测抽查 9 个货号全部命中。
⑥ 无标题的小块被同一个文件名挤掉：旧写法把「都来自同一个文件」当成「同一个小节」，
一刀只留 2 块；现在只有有名字的小节才共用配额。
⑦ 状态文件被改坏 / 写坏（顶层写成 []、pending_msgs 变成列表、某条变成字符串）
旧代码启动即崩且日志里看不出原因；现在类型自愈，读不出来的坏文件改名留档
（state.json.bad-月日-时分秒）并说明「用全新状态继续」，不再无声无息。
另修：纯表情短应和不再连回同一句 —— 实测客户 10 分钟内发 3 个表情包，收到 3 条
一模一样的「嗯嗯」（7 条候选语都被这个客户说过，旧代码固定回落到第 1 条，而第 1 条
恰恰就是刚说过的那条）；现在按最后一次使用时间挑最久没说的。
回归测试：tools/test_knowledge.py 12/13 两节 + tools/test_reply_queue.py 18/19 两节。

⑧ config.json 写错不再「静默不干活」："targets": "张三" 这种写成字符串的
笔误，过去会被 list("张三") 拆成 ['张','三'] —— 每个单字都匹配不上任何昵称，
助手看着在正常跑、其实一个客户都不回，而且日志里没有任何报错（这一版修的
第 8 个「静默失败」）。现在字符串按逗号/顿号/分号/空格切成多个名字；
另外 "keep_alive": null 会把字符串 "None" 发给模型服务、导致每次调用都失败，
现在退回默认值。回归测试见 tools/test_reply_queue.py 第 20 节。

• v0.4.13 知识库升级为「按需提取」+ 开发者更名（2026-10-08 用户「增加一个知识库，
  回复时可以从知识中提取相关信息」）：

① 知识库不再整份塞进 prompt。旧版把 knowledge/ 整份内容截断在 4000 字后塞给
模型 —— 买家把「价格表 + 常见问答 + 售后条款」都写进去以后，排在 4000 字之后的
内容永远进不了 prompt，等于白写；而且模型每次都要先读一遍无关内容。
现在：资料库 ≤ 1600 字 → 整份注入（与旧版完全一致，零退化）；超过 1600 字 →
按「客户当前这句 + 最近 4 轮对话」做本地字面检索（中文 2-gram + IDF + 标题加权
+ 覆盖率惩罚），只注入最相关的几个小节。检索完全在本机、不联网、不调模型、无第三方依赖。
② 常驻小节（口径/禁忌/语气/规则/说明/重要/注意/不要/禁止/原则/底线，
或 ! 前缀，或正文 [常驻]）无条件注入。这不是可选项：客户问「芒果多少钱」时，
若「资料里没有的价格不许编造」因为跟「芒果」字面不相关被筛掉，模型就会自己编个价 ——
那是知识库功能最容易出的事。tools/test_knowledge.py 把这条钉成了断言。
③ 短小节兜底：命中太少时（注入量不足预算 60%），把 150 字以内的小节一并带上。
字面检索绕不过「同义不同词」—— 客户问「坏了能赔吗」，资料里写的是「坏果包赔」，
bigram 一个都对不上；这类小节只有几十字，成本极低、漏掉的代价却很大。
④ 切分兼容既有写法：【小节名】 / markdown ## / 无标题按空行分段都认。
修了一个真实缺陷：小节名后面跟说明（【当前主推/价格】（在这里维护最新报价））
时旧正则认不出标题，整节被并进上一节、在检索里消失。
超过 400 字的单节会二次切分 —— 否则买家把 60 行价格表写成一节时，那一节比整个
预算还大，选它就等于把别的全挤掉、问「芒果」也只能拿到前几行。
⑤ 日志可核对：每次拟回复前写一行
[张三] 知识库命中：常驻1段+相关1段(133字)：回答口径 —— 重要、发货时间。
⑥ 给买家的模板（references/knowledge-template.md → 打包写进 knowledge/我的资料库.md）：
带「示例 / （填： / 在这里写」的行会被自动忽略，买家没填之前不会污染知识库
（旧版那个空占位文件会被当成知识库内容喂给模型，日志还谎报「知识库=N字」）；
另修「多行括号说明只剔掉第一行」的漏网。
⑦ 开发者名改为「菜恋果」，新增联系邮箱 499435316@qq.com（客服信息里一并展示）。
注册表键名 Software\JiayunNetwork\... 是历史内部标识，故意不改 —— 改了老用户
已激活的授权记录就读不到、会突然变回"试用中"。
回归测试：tools/test_knowledge.py（60 项，含同义不同词、口径必在场、
模板未填写不污染、真实资料库可读）。

试用与授权（收费逻辑）

价格和客服联系方式改 scripts/seller.json 即可，无需改代码。

发卡（卖家操作）：客户发来机器码 → 本地生成授权码 → 发回。

python tools/licensegen.py issue --plan Y1 --machine 0E11-7056-8828-B544 --note "张三"
python tools/licensegen.py list        # 发卡流水（tools/发卡记录.csv）

打包发布

python tools/package_release.py            # 生成客户端包 dist/wechat-assistant-<版本>.zip
python tools/package_release.py --target skillhub   # 生成上传官方技能市场的包（无 .bat）
python tools/package_release.py --out D:\发布

打包前后各跑一次自测（都在 tools/，不随包分发）：

python tools/test_licensing.py    # 授权模块自测：60+ 项断言（签名/伪造/过期/试用/回拨…）
python tools/smoke_test.py        # 发布包冒烟：解压→禁运检查→编译→验签→启动脚本体检

发布包采用白名单拷贝：只打包明确列出的文件，并复查一遍禁止清单
（config.json、data/、deepseek_key.txt、licensegen.py、日志、授权文件一律不放行，
命中即中止打包）。详见 tools/package_release.py 顶部注释。

v0.3 更新（新引擎）

• 消息监听后台化：盯消息改走本地只读数据通道，不抢窗口、不弹前台——你正常聊微信、用电脑完全不受影响（旧版盯消息会反复动窗口）
• 回复更稳更快：发送走精准控件通道（发送前三重对象校验，防误发）；判断+拟回复 1 秒级
• 无人值守更稳：保活守护（进程掉了自动拉起、卡住自动重启、依赖缺失给出明确提示，不擅自联网安装）＋ 自动化保活任务——见「稳定运行」节
• 内置拟人发送节奏（非固定间隔）

能干什么

• AI 自动回复（私聊）：白名单里的人发来消息 → 按"人味"人设拟回复并发送（短句口语、不像AI）；带限频/停止词/干跑模式
• 知识库（让回复「答得对」）：把你的业务信息、常见问答、价格、售后写进 knowledge/我的资料库.md，
  助手回复时自动挑出和客户当前问题最相关的那几节参考 —— 资料库写多长都生效，不用怕被截断
• 群消息（静默）：给「会话列表里可见」的群/人发消息，支持一次发多个群（纯文字）；全程不抢焦点、不弹窗、不改窗口尺寸位置
• 单发工具：给指定联系人发消息/文件

首次配置向导（给 AI 助手执行）

> 如果你是帮用户配置本技能的 AI 助手：按下面步骤逐步执行，每步向用户确认结果。
> 人类用户可直接跳到「快速开始」手动配置。

1. 环境自查
   - 系统：Windows 10 / 11（Windows Server 不支持，先劝退）
   - 微信：桌面版 4.1.12+。检查方式：微信「设置 → 关于」查看版本；或查主程序文件版本（默认路径，实际以安装位置为准）：
   powershell "(Get-Item 'C:\Program Files (x86)\Tencent\Weixin\Weixin.exe').VersionInfo.FileVersion"
   - Python：python --version（需 3.9+；未安装 → 引导下载安装 https://mirrors.huaweicloud.com/python/win/ ，安装时勾选 "Add python.exe to PATH"）

2. 安装依赖（一条命令；python 用 WorkBuddy 自带的，见「环境要求」）
   <workbuddy-python> -m pip install wechatauto-replica wx4py -i https://pypi.tuna.tsinghua.edu.cn/simple
   （镜像源装不上时换官方源：-i https://pypi.org/simple）

3. 问用户要三样东西（帮填到 scripts/wechat_ai_replier.py 顶部）
   - 白名单：要自动回复哪些联系人（填 TARGETS，支持昵称/备注）
   - 主人名：账号主人怎么称呼（填 OWNER，用于回复人设）
   - 知识库：问「你是做什么的 / 常见问题怎么答」，用 knowledge_tool.py 写进去 ——
   --add-q "问" "答" 逐条加，--add-sec 价格表 --body-file 报价.txt 整块加，
   --import 报价.csv 直接导 Excel 导出的价目表（详见「知识库」节的三种方式）

4. 模型密钥
   - 用户已有 DeepSeek Key → 写入 scripts/deepseek_key.txt（一行）
   - 没有 → 引导到 https://platform.deepseek.com 注册并创建 API Key（免费注册，少量充值即可用很久）

5. 干跑验证
   <workbuddy-python> scripts/wechat_ai_replier.py
   → 日志出现 已启动; 模式=干跑; 目标=[...]; 知识库=X字/N小节 即配置成功（只读不回，安全）

6. 正式运行（后台常驻）
   ~~不要用前台窗口跑~~（关掉就停）。用保活守护启动：
   <workbuddy-python> "<技能目录>\scripts\assistant_guard.py"
   它会把助手以无窗口方式拉起来，并负责之后的保活（见「稳定运行」节）。

7. 配置自动保活（做一次，之后就不用管了）
   让助手创建自动化任务，或对用户说一句"帮我配置微信助手的自动保活"——具体见「稳定运行」节。

8. 遇到问题 → 查 references/setup-and-pitfalls.md

知识库（可选，但强烈建议填）

knowledge/ 目录放账号主人的业务信息、常见问答、回复口径（.md/.txt 均可），
自动回复时自动引用——别人问起业务相关的问题，回复更准、更像本人。

v0.4.13 起改为「按需提取」，写多长都不怕：

另有两条保命规则：

• 常驻小节：小节名含「口径/禁忌/语气/规则/说明/重要/注意/不要/禁止/原则/底线」，
  或以 ! 开头，或正文写了 [常驻] → 每次回复都在场。
  这是为了防「客户问芒果多少钱 → 按相关性挑片段时把『不许编造价格』筛掉了 →
  模型自己编一个价格」。
• 短小节兜底：命中的小节太少时，把 150 字以内的短小节一并带上 ——
  字面检索绕不过「同义不同词」（客户问「坏了能赔吗」，资料里写的是「坏果包赔」）。

怎么把资料放进去（三种方式）

不管哪种方式，写完约 1 分钟自动生效，不用重启助手。用工具还有三层保障：

• 写完立刻复核（--check）：文件到底生效没有、这次写的内容助手读到了没有、
  哪一行会被当成没填的占位符静默忽略，当场说清 —— 这是这个工具存在的理由。
• 每次写入前自动备份（knowledge/.backup/，留 30 份，时间戳精确到微秒），
  --restore 1 退回上一版。
• 自己验一句：python scripts/knowledge_tool.py --check --ask "芒果多少钱"
  → 直接看助手这次会拿到哪几段，不用等客户来问。

CSV 是价目表最省的填法：Excel「另存为 CSV」→ --import 报价.csv --sec 价格表，
会自动识别表头、转成 - 品名 | 规格 | 价格（并补一行列名说明，否则模型不知道「68」是价格还是重量）。

小节切分兼容三种写法：【小节名】、markdown 标题 ## 小节名、都没有则按空行分段。
每次拟回复前日志里会写一行命中情况，卖家能核对用了哪几段：

[张三] 知识库命中：常驻1段+相关1段(133字)：回答口径 —— 重要、发货时间

随包发给买家的 knowledge/我的资料库.md 是一份带提示的模板；模板里带
「示例 / （填： / 在这里写」的行会被自动忽略，所以买家没填之前不会污染知识库，
填了哪几行哪几行才生效。改完保存约 1 分钟自动生效，不用重启。

环境要求

• Windows 10/11 + 已登录的微信桌面版（4.1.12+，官网最新版即可）
• Python：优先用 WorkBuddy 自带的（免安装，路径见下）；没有 WorkBuddy 的环境用系统 Python 3.9+（推荐 3.11）
• 依赖：<python> -m pip install wechatauto-replica wx4py -i https://pypi.tuna.tsinghua.edu.cn/simple
• 一个 OpenAI 兼容的大模型 API Key（DeepSeek/硅基流动/任意兼容接口，Key 由使用者自备）

WorkBuddy 自带 Python 路径（下文 <workbuddy-python> 都指它）：

你用户目录\.workbuddy\binaries\python\versions\<版本号>\python.exe

版本号 = versions\current 文件里写的内容（如 3.13.12）；找不到就读 versions 下版本号最大的目录。

快速开始

1. 安装依赖：<workbuddy-python> -m pip install wechatauto-replica wx4py -i https://pypi.tuna.tsinghua.edu.cn/simple
2. 改配置：打开 scripts/wechat_ai_replier.py 顶部填：白名单联系人 TARGETS、账号主人名 OWNER；模型 Key 放 scripts/deepseek_key.txt（或环境变量 DEEPSEEK_KEY）
3. 干跑观察：<workbuddy-python> scripts/wechat_ai_replier.py（只拟回复不发送，安全模式）
4. 正式运行（后台+保活）：在本文件夹执行 <workbuddy-python> scripts\assistant_guard.py
5. 群工具：<workbuddy-python> scripts/wechat_group_tools.py --help

稳定运行（无人值守 · 必做一次）

微信助手要"一直帮着盯"，需要 后台常驻 + 自动保活——本技能已内置，两步配好就不用管：

第一步：保活守护（已就位，无需额外配置）

scripts/assistant_guard.py 跑一轮管四件事：

• 常驻兜底：确保 assistant_supervisor.py 在跑（它每 60 秒回头叫醒 guard）
• 进程保活：助手不在 → 无窗口自动拉起（走 WMI，脱离 job）
• 假死检测：进程在但卡住（心跳 5 分钟没动静）→ 杀掉重启
• 依赖检查：运行库缺失（如平台升级后）→ 只提示、不擅自联网安装

> 为什么强调「走 WMI」：工具调用 / 自动化任务跑在一个 Windows job object 里，
> 任务结束时 job 关闭，job 内的进程会被整体 TerminateProcess 带走。老版本用
> DETACHED_PROCESS | NEW_PROCESS_GROUP | NO_WINDOW 起助手，这三个 flag 只解决
> 「无窗口 / 独立进程组」，并不脱离 job —— 于是现象就是「启动成功几十秒后
> 凭空消失」，而且日志干净得没有一行 traceback。现在改由 WMI 服务
> （WmiPrvSE.exe）代创进程，父级不再是这个 job，助手才真的常驻。

跑法：<workbuddy-python> scripts/assistant_guard.py
输出：正常 = 无输出；有动作 = 一行结果（如"已自动拉起"）。
诊断：加 --status 看详细状态 + 最近日志。

第二步：自动保活（用 WorkBuddy 自动化任务 · 做一次）

让助手创建一条每小时运行的自动化任务（WorkBuddy 自带能力，AI 用 automation 工具建，或引导用户在自动化页面手动建）：

• 名称：微信助手保活
• 频率：每小时（rrule：FREQ=HOURLY;INTERVAL=1）
• 任务内容（prompt）（把 <技能目录> 换成技能实际所在位置，如 D:\微信智能助手）：

执行命令保活微信助手（让它一直运行）： "<workbuddy-python>" "<技能目录>\scripts\assistant_guard.py" - 输出为空 = 一切正常：什么都不要做，不要通知任何人 - 输出以 ✅ 开头 = 一句话告诉用户（例："微信助手刚才掉线，已自动恢复"） - 输出以 ⚠️ 开头 = 把内容转告用户 不要做其它任何事。

注意：命令用绝对路径、直接一条命令执行——不要用 cd / &&（不同环境 shell 语法不一）。

原理：每小时检查一次；掉线/卡住自动恢复，正常完全静默。
（配合脚本内自愈，绝大多数情况无需人工干预。）

出问题怎么看

• 状态：<workbuddy-python> scripts/assistant_guard.py --status
• 日志：scripts/data/logs/——guard.log=保活记录，replier_日期.log=回复记录
• 退出原因：--status 末尾会显示 data/last_exit.json 里的「上次退出码 + 存活时长」，
  一眼区分是崩溃、被内存限制杀（0xC000012D）、还是被外部强杀
• 疑难：查 references/setup-and-pitfalls.md

护栏（默认内置）

• 只回白名单里的人；每人限频（默认 25 秒起）；每小时总限额
• 对方发"停止监听/别回了"即对其实停
• 卡死时宁可不动、绝不乱回；日志全量落盘
• 回复发送走拟人节奏（非均匀间隔），避免机器味

安全与合规

• 建议保持低频、话术带人味（防"一眼AI"）
• 不要用于群发营销/骚扰——高频自动化可能触发平台风控
• 查看消息不需要操作窗口；回复时微信会短暂切到对应聊天（属正常，几秒）
• 数据不出本机：仅读取本机微信数据用于判断回复，不上传任何第三方

文件结构

• scripts/wechat_ai_replier.py — AI 自动回复主程序（后台监听式；v0.3 新引擎；内置监听线程自愈）
• scripts/knowledge_tool.py — 知识库录入（加问答/版块、导入 CSV/剪贴板、写完用助手同一套规则复核、自动备份、模拟检索）。桌面入口「添加知识.bat」/「添加知识.py」调的就是它
• scripts/uia_sender.py — 发送通道（纯控件 UIA + PostMessage，锁屏也能发）。按收到的那条消息（内容指纹）定位会话，不按昵称；打开后还会读聊天区正文复核，防发错人
• scripts/licensing.py — 试用/授权（机器码、离线签名校验、激活向导、付款入口 pay）
• scripts/pay_window.py — 付款/开通窗口（选套餐 + 微信收款码 + 一键申请 + 开通成功自动提示；纯标准库 tkinter）
• scripts/license_order.py — 开通订单的文本协议（客户端与卖家端共用一份格式，改格式两端同时生效）
• scripts/license_apply.py — 付款后把开通申请自动发给客服（发不出去则复制剪贴板 + 桌面留 txt）
• scripts/license_claim.py — 自动领码：在本机微信里找回客服发来的授权码并激活（验签通过才认）
• scripts/pay_qr.png — 微信收款二维码（换码直接替换这个图片文件即可）
• scripts/license_gate.py — 发送前的授权闸门（群发/单发工具共用；未付费则拒绝发送，模块缺失也拒绝，内部报错则放行）
• scripts/seller.json — 卖家信息（品牌 / 客服联系方式 / 价格 / 试用天数），不含密钥，随包发布
• scripts/setup_env.py — 首次安装（挑个有 winsdk 轮子的 Python，建独立 venv、装依赖）
• scripts/assistant_guard.py — 保活守护（一轮式：确保常驻 supervisor 在跑 / 进程保活 / 假死重启 / 检查依赖；自动化任务调用它）。拉起助手时走 WMI，让进程落在调用方的 job 之外 —— 不这么做，任务一结束助手就被回收
• scripts/assistant_supervisor.py — 常驻监督（每 60 秒跑一轮 guard；「启动助手.bat」由它常驻，所以双击一次就够）
• scripts/wmi_launch.py — 用 WMI 的 Win32_Process.Create 在当前 job 之外创建进程。这是「助手能长期存活」的关键一环（详见下方「稳定运行」）
• scripts/replier_runner.py — 转发助手输出到 replier_stdout.log，并把退出码/存活时长记到 data/last_exit.json
• scripts/wechat_group_tools.py — 群消息工具（静默通道：list / send / broadcast，不抢焦点、不动窗口）
• scripts/wechat_uia_send.py — 单发消息/文件工具
• references/setup-and-pitfalls.md — 排坑手册（必读）
• knowledge/ — 知识库（可选，强烈建议填）：我的资料库.md 放业务信息/FAQ（.md/.txt 都行）。
  v0.4.13 起按需提取：小资料库整份用，写长了只取与当前客户问题最相关的几节；
  「回答口径/禁忌」类小节无条件常驻。改完约 1 分钟生效，不用重启
• tools/licensegen.py — 发卡器（仅开发者，绝不打进发布包）；签名私钥也在 tools/ 下，泄露＝把签发能力白送客户
• tools/package_release.py — 一键打包（白名单 + 禁止清单复查）
• docs/ — 授权收费方案、上架审核材料

常见问题

• 试用到期了怎么办 → 在微信里复制好授权码，双击「激活助手.bat」（自动读剪贴板激活）；看状态双击「查看授权.bat」
• 换了台电脑 → 机器码变了，需要把新机器码发给客服重新签发
• 想先看看助手在不在 → 桌面「查看授权.bat」会显示能否回复；一键体检.bat 会给完整结论
• 有两个联系人昵称一模一样，会不会发错人？ → 不会。助手按收到的那条消息
  （会话列表里那条消息摘要）定位会话，跟昵称无关，同名照常发对人；点开之后还会读
  聊天记录正文再复核一遍。只有指纹太短（如「好的」）或两人最后一条消息内容雷同时才会
  放弃发送（宁可晚回，绝不发错）。想彻底省心可以给其中一个加「备注」。
• 联系人改了备注 / 换了昵称，助手还找得到吗？ → 找得到。定位不依赖名字，改备注
  不影响；启动时发现的旧缓存昵称也会在发送前自动刷新。
• 助手启动了，可过一会儿又没了（收不到回复）？ → 这是 v0.4.6 修掉的老毛病，根因是
  启动方式没脱离调用方的 job 对象，任务一结束就被静默回收。现在启动改走 WMI，
  由系统服务代创进程，已能稳定常驻。若仍遇到：双击 一键体检.bat，它会告诉你
  助手在不在、模型服务通不通，--status 还会附上上次退出码（崩溃 / 被内存杀 /
  被外部强杀，一目了然）。
• 想加业务知识（价格表、发货时间、售后口径），怎么弄？ → 双击「添加知识.bat」
  按菜单加即可（平台包运行「添加知识.py」），也可以直接对助手说「帮我加一条知识：
  客户问发货时间 → 当天下午5点前下单当天发」。Excel 价目表「另存为 CSV」后能从
  菜单第 4 项直接导入。写完约 1 分钟自动生效，不用重启。
• 加了知识，怎么确认助手真的用上了？ → python scripts/knowledge_tool.py --check
  会打印「哪个文件生效 / 为什么没生效 / 这次写的内容助手读到了没有」，还能
  --ask "芒果多少钱" 模拟一句客户提问、看助手这次会拿到哪几段。别用「客户问了
  才知道答错」来验证 —— 这个项目最忌讳的就是资料没生效却毫无提示。
• 资料写多了会把 prompt 挤爆吗？ → 不会。≤1600 字整份注入；超过则只挑相关小节
  （见「知识库」节）。所以写长资料时节名要写清楚（【价格表】【发货时间】），
  否则可能挑不中。用 --check --ask 能立刻看出挑没挑对。