docs(iit): Add IIT Manager Agent V2.9 development plan with multi-agent architecture

Features: - Add V2.9 enhancements: Cron Skill, User Profiling, Feedback Loop, Multi-Intent Handling - Create modular development plan documents (database, engines, services, memory, tasks) - Add V2.5/V2.6/V2.8/V2.9 design documents for architecture evolution - Add system design white papers and implementation guides Architecture: - Dual-Brain Architecture (SOP + ReAct engines) - Three-layer memory system (Flow Log, Hot Memory, History Book) - ProfilerService for personalized responses - SchedulerService with Cron Skill support Also includes: - Frontend nginx config updates - Backend test scripts for WeChat signature - Database backup files Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-05 22:33:26 +08:00
parent 4b9b90ffb8
commit 0c590854b5
27 changed files with 7279 additions and 7 deletions
--- a/Agent/05-测试文档/微信开发技术问题咨询.md
+++ b/Agent/05-测试文档/微信开发技术问题咨询.md
@@ -0,0 +1,169 @@
+
+
+**第二章 微信服务号集成与Error 200002根因深度剖析**
+
+用户提到的“配置消息推送失败: invalid args, 200002”且“后端无日志”，是微信开发中极其典型且令人抓狂的现象。这通常不是单一的代码错误，而是网络层、网关层与应用层叠加的系统性故障。
+
+### **2.1 现象解码：“无日志”的恐怖**
+
+当微信后台提示配置失败，而您的服务器访问日志（Access Log）空空如也时，这意味着**请求根本没有到达您的应用服务器**。
+
+#### **2.1.1 网络层的隐形墙：防火墙与安全组**
+
+微信服务器位于腾讯的公网IP池中。当它发起HTTP/HTTPS请求时，如果您的服务器部署在阿里云、腾讯云或AWS等云平台，\*\*安全组（Security Group）\*\*是第一道关卡。
+
+* **诊断**：大多数云服务器默认只开放22端口（SSH）。  
+* **排查**：检查云控制台的入站规则。必须允许0.0.0.0/0对TCP 80（HTTP）和443（HTTPS）的访问。  
+* **误区**：不要试图将微信的IP加入白名单。微信的出口IP是不定期的海量IP池，必须全量开放。
+
+#### **2.1.2 接入层的黑洞：Nginx配置错误**
+
+如果您使用了Nginx作为反向代理，请求可能在Nginx层被丢弃，导致后端Java/Python应用收不到日志。
+
+* **Server Name匹配**：如果Nginx配置了server\_name www.example.com，而您在微信后台填写的是直接IP地址，Nginx可能因为找不到匹配的Host而直接拒绝连接。  
+* **SSL握手失败**：如果配置的是HTTPS URL，但服务器的SSL证书不完整（如缺少中间证书）或协议版本过旧（TLS 1.0），微信服务器会终止握手，请求甚至不会进入Nginx日志。
+
+### **2.2 Error 200002 “invalid args” 的代码级解剖**
+
+如果请求成功到达服务器（可以通过Nginx日志确认），但微信仍然报200002，则问题出在**握手协议的实现**上。这是最考验开发者基本功的环节。
+
+#### **2.2.1 握手协议的三大铁律**
+
+微信在验证服务器有效性时，发送signature, timestamp, nonce, echostr四个参数。开发者必须完成以下步骤：
+
+1. **字典序排序（Lexicographical Sorting）**：  
+   * **错误高发点**：很多开发者将数字类型的timestamp直接参与排序，或者使用了错误的排序算法。  
+   * **正确逻辑**：将\[token, timestamp, nonce\]放入一个字符串数组，调用标准的字符串排序方法（如Python的list.sort()，Java的Arrays.sort()）。  
+2. **SHA1哈希（Hashing）**：  
+   * **错误高发点**：编码问题。在Python 3中，hashlib.sha1()接受的是字节流（bytes），必须先对拼接后的字符串进行.encode('utf-8')。  
+3. **返回值的纯净性（Response Purity）**：  
+   * **错误高发点**：这是导致200002最隐蔽的原因。微信要求**原样返回**echostr的明文。  
+   * **忌讳**：  
+     * 不能返回JSON格式（如{"ret": "success", "echo": "..."}）。  
+     * 不能包含引号（如"abc..."）。  
+     * 不能包含换行符或空格。  
+   * **Content-Type**：虽然微信不强制，但最佳实践是设置Response Header为text/plain。
+
+#### **2.2.2 深度调试代码示例（Python Flask版）**
+
+以下是一个通过了生产环境验证的标准校验代码，用于替换可能存在缺陷的逻辑：
+
+Python
+
+import hashlib  
+from flask import Flask, request, make\_response
+
+app \= Flask(\_\_name\_\_)
+
+@app.route('/wechat', methods=)  
+def check\_signature():  
+    \# 1\. 获取参数  
+    token \= "YOUR\_TOKEN"  \# 必须与微信后台填写的完全一致  
+    signature \= request.args.get('signature')  
+    timestamp \= request.args.get('timestamp')  
+    nonce \= request.args.get('nonce')  
+    echostr \= request.args.get('echostr')
+
+    \# 2\. 空值校验（防御性编程）  
+    if not all(\[signature, timestamp, nonce, token\]):  
+        return "Invalid Request", 400
+
+    \# 3\. 字典序排序  
+    li \= \[token, timestamp, nonce\]  
+    li.sort()
+
+    \# 4\. 拼接与哈希  
+    temp\_str \= "".join(li)  
+    hash\_str \= hashlib.sha1(temp\_str.encode('utf-8')).hexdigest()
+
+    \# 5\. 对比与返回  
+    if hash\_str \== signature:  
+        \# 关键：使用make\_response确保返回的是纯文本，不受框架序列化影响  
+        response \= make\_response(echostr)  
+        response.headers\['content-type'\] \= 'text/plain'  
+        return response  
+    else:  
+        \# 记录错误日志以便排查  
+        app.logger.error(f"Sig check failed. Calc: {hash\_str}\!= Req: {signature}")  
+        return "Signature Failed", 403
+
+if \_\_name\_\_ \== '\_\_main\_\_':  
+    app.run(port=80)
+
+### **2.3 “我很痛苦”的终结方案：抓包与模拟**
+
+如果依然失败，请停止盲目修改代码，采用**证据驱动调试**。
+
+1. **自测脚本**：编写一个Python脚本，模拟微信的逻辑，生成签名并发送GET请求给自己的服务器。如果自测通过但微信不通过，问题一定在网络层（防火墙/CDN/WAF）。  
+2. **网络抓包**：在服务器上使用tcpdump \-i eth0 port 80 \-w wechat\_debug.pcap。在微信后台点击提交后，停止抓包并用Wireshark分析。  
+   * 如果抓不到包 \-\> 网络不通。  
+   * 如果抓到包但应用没日志 \-\> Nginx配置错误。  
+   * 如果应用返回了200但微信报错 \-\> 检查Response Body是否有隐藏字符（BOM头、换行符）。
+
+## ---
+
+**第三章 全场景调试指南：工具链与最佳实践**
+
+对于“如何调试”、“本地还是远程”的疑问，行业内的最佳范式是\*\*“本地隧道调试”\*\*（Local Tunnel Debugging）。直接在远程服务器上修改代码并重启服务来调试微信接口，效率极低且风险极高。
+
+### **3.1 本地调试的核心逻辑：内网穿透**
+
+微信服务器无法直接访问你笔记本电脑上的localhost:8080。因此，需要一个“隧道”，将公网请求转发到本地。
+
+#### **3.1.1 工具选型与配置**
+
+针对中国网络环境，推荐以下工具链：
+
+| 工具名称 | 适用场景 | 优点 | 缺点 | 推荐指数 |
+| :---- | :---- | :---- | :---- | :---- |
+| **ngrok** | 快速验证 | 命令简单，全球通用 | 免费版域名随机变化，国内连接有时不稳定 | ⭐⭐⭐ |
+| **frp** | 长期开发 | **国内标准**。需一台公网VPS。稳定，域名固定 | 配置稍繁琐，需维护服务端 | ⭐⭐⭐⭐⭐ |
+| **cpolar/Natapp** | 无VPS用户 | 专为国内优化，速度快 | 免费版有限制，自定义域名需付费 | ⭐⭐⭐⭐ |
+
+#### **3.1.2 FRP实战配置SOP**
+
+假设您有一台腾讯云/阿里云服务器（IP: 1.2.3.4），这是最稳定的方案。
+
+1. **服务端（VPS）配置 frps.ini**：  
+   Ini, TOML  
+   \[common\]  
+   bind\_port \= 7000        \# 用于frp内部通信  
+   vhost\_http\_port \= 8080  \# 微信访问的端口
+
+   启动：./frps \-c frps.ini  
+2. **客户端（本地电脑）配置 frpc.ini**：  
+   Ini, TOML  
+   \[common\]  
+   server\_addr \= 1.2.3.4  
+   server\_port \= 7000
+
+   \[wechat-debug\]  
+   type \= http  
+   local\_port \= 5000       \# 本地Python/Java服务的端口  
+   custom\_domains \= wechat.your-startup.com \# 解析到1.2.3.4的域名
+
+   启动：./frpc \-c frpc.ini  
+3. **调试闭环**：  
+   * 在微信后台配置URL为：http://wechat.your-startup.com:8080/callback  
+   * 当微信发送请求时，流量路径为：微信 \-\> VPS(7000) \-\> 隧道 \-\> 本地电脑(5000)。  
+   * **效果**：您可以在本地IDE（PyCharm/VSCode）中打断点，实时查看微信发来的XML数据包，单步调试每一行代码。这是解决“痛苦”的根本途径。
+
+### **3.2 微信官方调试工具的使用**
+
+除了内网穿透，腾讯提供了**微信开发者工具**（主要用于小程序，但也包含公众号调试）和**在线接口调试工具**。
+
+* **在线接口调试工具** 6：  
+  * 地址：[https://developers.weixin.qq.com/apiExplorer](https://developers.weixin.qq.com/apiExplorer)  
+  * 用途：当您的Token配置成功，但消息推送失败时，可以用它模拟微信服务器向您的URL发送POST请求。它会详细显示您的服务器返回了什么（HTTP Code, Body），帮助快速定位“回包格式错误”。
+
+### **3.3 行业最佳实践范式**
+
+1. **TraceID全链路追踪**：在入口处生成一个UUID作为TraceID，贯穿Nginx日志、应用日志和数据库日志。当某个课题组反馈机器人不回话时，通过TraceID可秒级定位问题环节。  
+2. **日志分级与脱敏**：  
+   * **DEBUG级**：打印完整的XML/JSON请求体（注意：生产环境需对患者姓名、ID进行掩码脱敏）。  
+   * **INFO级**：记录核心链路节点（收到消息 \-\> 开始推理 \-\> 推送完成）。  
+   * **ERROR级**：记录所有的API调用非200状态码及异常堆栈。  
+3. **容错与重试**：微信接口偶尔会出现网络抖动。在调用send接口时，务必封装重试逻辑（Exponential Backoff），遇到超时或5xx错误时自动重试3次。
+
+## ---
+