jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-10-31 14:27:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(qq): 发送类端点用长超时客户端 + 校验 OneBot retcode，消除「已发出却报失败」

Browse Source 
## 真实故障（2026-10-13，生产日志实证）

从 `<data>/log/week_2026-W41.tar.gz` 解出的历史日志 + `memory/context.json`
拿到完整错误文本：

    napcat send_private_msg: Post "http://192.168.2.106:25570/send_private_msg":
      context deadline exceeded (Client.Timeout exceeded while awaiting headers)

对应日志时序（~30s 恰好撞上客户端超时）：

    17:50:07 executing tool: output_send__qq
    17:50:47 result: 通过 [qq] 通道发送失败: ... Post "...": ...   ← 40s
    21:47:15 → 21:47:47                                            ← 32s
    08:17:39 → 08:18:09                                            ← 30s

**消息其实发出去了**，证据有二：
  ① agent 自己在上下文里总结（memory/context.json 原文）：
     「其余几次 send 是 napcat 的 25570 接口超时重试，用户只收到一份，不会刷屏」
     「napcat 这会儿接口有点不稳（好几次 context deadline exceeded），
       不过关键的那一发是成功的」
  ② 同一内容重试后用户只收到一份 —— 那是 qq 循环保险拦住的，属侥幸而非正确行为。

根因：`httpClient.Timeout = 30s` 被**查询与发送共用**。而 QQ 发送要经
NapCat 的 `NodeIKernelMsgService/sendMsg`，慢时响应头 30s 回不来 ⇒
把已送达的消息报成失败 ⇒ 模型重试。

## 另一个独立缺陷：不校验 OneBot retcode

`napcat()` 原来只看 HTTP 通不通、JSON 能不能解，**从不看响应体里的
成败字段**。而 OneBot v11 的成败在 body 里：

    成功 {"status":"ok","retcode":0,"data":{"message_id":...}}
    失败 {"status":"failed","retcode":100,"message":"..."}
        或 {"data":null,"message":"Timeout: NTEvent ...sendMsg","status":"failed"}

历史日志里实测到 NapCat 返回 `data:null` + `sendMsg Timeout`（真失败）
却被当作发送成功。两个方向都错，必须靠 retcode 判定。

## 改动

- 新增 `sendClient`（120s + Transport 显式配 `IdleConnTimeout`/`ResponseHeaderTimeout`）。
  发送类端点（send_private_msg / send_group_msg / send_msg）走它；查询类
  保持 30s（幂等，快速失败更利于排查）。
- `Transport.IdleConnTimeout=30s`：默认 Transport 的空闲连接无上限等待，
  复用对端已单向关闭的 keep-alive 连接会得到"请求已写入/对端已处理，
  本地读响应 EOF"——又一种「已发送却报失败」。
- `napcat()` 校验 OneBot `retcode`/`status`，失败转 error。
- 超时单独包 `errNapcatTimeout`，错误文案明写「**可能已送达并已发出，
  不要盲目重发**」——只说"失败"会诱发模型重发 → 重复消息。

## 判据（4 条，两条经变异测试修正）

- `TestOneBotError_FailedResponses`：7 组 retcode/status 组合的判定
- `TestNapcatConvertsOneBotFailureToError`：**端到端**——napcat() 必须把
  OneBot 失败转 error。★ 变异（删掉 napcat() 里的 oneBotError 调用）
  实测发现：只测 oneBotError 的判据照样全绿（判据没穿过调用链）
  ⇒ 补这条才咬住。
- `TestNapcatSendUsesSendClient`：**真的验证路由**（用 Transport 重写 host
  观测哪个 client 实际发了请求）。★ 变异（删掉路由分支）实测发现：
  只断言两个 client 的 Timeout 字段值照样全绿 ⇒ 重写为观测实际请求。
- `TestNapcatTimeoutErrorIsActionable`：超时错误必须含「可能已送达」
  与「不要盲目重发」

27 条判据全绿（含既有 23 条）。
This commit is contained in:
JianFeeeee
2026-10-13 08:02:45 +08:00
parent 777c3a0ad3
commit bd26c2a402
2 changed files with 278 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
example/qq/plugin_test.go
View File

@ -2,10 +2,13 @@ package main
import (
"encoding/json"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"net/url"
"strings"
"sync/atomic"
"testing"
"time"
@ -541,3 +544,170 @@ func TestFrameIdentityBeatsGlobalIdentity(t *testing.T) {
t.Fatalf("帧上 owner 调硬私工具应放行（2026-10-12 owner 被误拒的故障场景）: %s", *ctx2.Response)
}
}
// ── napcat 响应判定与超时语义（2026-10-13 真实故障的判据）────────────
// 真实故障：QQ 发送经 NapCat 的 NodeIKernelMsgService 慢时响应头 30s 回不来，
// 旧实现共用 30s 客户端 ⇒ 消息**已发出**（NapCat 已返回 message_id、用户真收到）
// 却报 "context deadline exceeded"，模型据此重试。
//
// 判据（不变量，不是"函数被调过"）：
// 1. OneBot 失败响应（retcode!=0 / status=failed）必须报错
// 2. OneBot 成功响应（retcode=0,status=ok）必须放行
// 旧实现不校验 retcode ⇒ NapCat 明确报失败（data:null + sendMsg Timeout）
// 也会被当成发送成功
// 3. 发送类端点必须走 sendClient（更长超时），查询类走 httpClient
// 4. 超时错误必须带"可能已送达，不要盲目重发"的提示
// （只说"失败"会诱发模型重发 → 重复消息）
func TestOneBotError_FailedResponses(t *testing.T) {
cases := []struct {
name string
body string
want bool // 期望判为失败
}{
{"retcode 非0", `{"status":"failed","retcode":100,"message":"bad","wording":""}`, true},
{"retcode 非0 带 wording", `{"status":"failed","retcode":1400,"wording":"群号不存在","data":null}`, true},
{"status failed 无 retcode", `{"status":"failed","message":"oops"}`, true},
{"status error", `{"status":"error","message":"boom"}`, true},
{"成功 retcode0", `{"status":"ok","retcode":0,"data":{"message_id":713138214},"wording":""}`, false},
{"非对象（数组）", `[{"a":1}]`, false},
{"无成败字段", `{"data":{"message_id":1}}`, false},
}
for _, c := range cases {
err := oneBotError(json.RawMessage(c.body))
if c.want && err == nil {
t.Errorf("%s：应判失败却放行 → NapCat 报失败会被当成发送成功", c.name)
}
if !c.want && err != nil {
t.Errorf("%s：应放行却报错（%v）→ 会把正常结果误报失败，诱发重复发送", c.name, err)
}
}
}
// 发送类端点必须真的走 sendClient（更长超时），而不是查询类的 httpClient。
//
// ★ 为何要真的验证路由（变异测试实测发现）：只断言两个客户端的 Timeout
//
// 字段值，把 napcat() 里的路由分支删掉判据照样全绿——判据必须观测
// "哪个客户端实际发了请求"，否则"接线断了"测不出来。
func TestNapcatSendUsesSendClient(t *testing.T) {
var sendHits, otherHits atomic.Int64
sendSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
sendHits.Add(1)
_, _ = w.Write([]byte(`{"status":"ok","retcode":0,"data":{"message_id":1}}`))
}))
defer sendSrv.Close()
otherSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
otherHits.Add(1)
_, _ = w.Write([]byte(`{"status":"ok","retcode":0}`))
}))
defer otherSrv.Close()
p := newPermissionTestPlugin(t)
p.napcatURL = otherSrv.URL // 查询类客户端指向这里
p.sendClient = sendSrv.Client() // 发送类客户端指向 sendSrv
p.sendClient.Timeout = 120 * time.Second
// 让 sendClient 的请求打到 sendSrv：直接改 napcatURL 不可行（两者共用），
// 所以用 Transport 层重写 host —— 只有 sendClient 带这个 Transport。
p.sendClient.Transport = rewriteHostTransport(sendSrv.URL)
p.httpClient = otherSrv.Client()
p.httpClient.Timeout = 30 * time.Second
if _, err := p.napcat("send_private_msg", map[string]interface{}{"user_id": 1, "message": "x"}); err != nil {
t.Fatalf("send_private_msg 应成功: %v", err)
}
if sendHits.Load() != 1 {
t.Errorf("发送类端点未走 sendClient（sendHits=%d）—— 30s 客户端会把已发出的消息报成超时失败", sendHits.Load())
}
if otherHits.Load() != 0 {
t.Errorf("发送类端点误用了 httpClient（otherHits=%d）", otherHits.Load())
}
}
// rewriteHostTransport 返回一个把所有请求重定向到 baseURL 的 Transport。
// 仅测试用：让"哪个 client 发的"可观测。
func rewriteHostTransport(baseURL string) http.RoundTripper {
target, _ := url.Parse(baseURL)
return roundTripFunc(func(req *http.Request) (*http.Response, error) {
req.URL.Scheme = target.Scheme
req.URL.Host = target.Host
return http.DefaultTransport.RoundTrip(req)
})
}
type roundTripFunc func(*http.Request) (*http.Response, error)
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
// 超时错误必须写明「可能已送达，不要盲目重发」。
func TestNapcatTimeoutErrorIsActionable(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
time.Sleep(300 * time.Millisecond) // 故意超过客户端超时
_, _ = w.Write([]byte(`{"status":"ok","retcode":0}`))
}))
defer srv.Close()
p := newPermissionTestPlugin(t)
p.napcatURL = srv.URL
p.httpClient = &http.Client{Timeout: 50 * time.Millisecond}
p.sendClient = &http.Client{Timeout: 50 * time.Millisecond}
_, err := p.napcat("send_private_msg", map[string]interface{}{"user_id": 1, "message": "x"})
if err == nil {
t.Fatal("超时应报错")
}
if !errors.Is(err, errNapcatTimeout) {
t.Errorf("超时应包装 errNapcatTimeout，实为 %v", err)
}
msg := err.Error()
if !strings.Contains(msg, "不要盲目重发") {
t.Errorf("超时错误必须提示不要盲目重发（否则模型会重发→重复消息），实为: %s", msg)
}
if !strings.Contains(msg, "可能已送达") {
t.Errorf("超时错误必须说明可能已送达，实为: %s", msg)
}
}
// napcat() 端到端必须把 OneBot 失败响应转成 error。
//
// ★ 为何单测 oneBotError 不够（变异测试实测发现）：把 napcat() 里的
//
// oneBotError 调用删掉，只测 oneBotError 的判据照样全绿——判据必须
// 穿过真实调用链，否则"接线断了"测不出来（正是本仓踩过的同款坑：
// 单测全绿而生产链路断开）。
func TestNapcatConvertsOneBotFailureToError(t *testing.T) {
for _, body := range []string{
`{"status":"failed","retcode":100,"wording":"群号不存在"}`,
`{"status":"failed","retcode":1400,"message":"send failed"}`,
`{"data":null,"echo":null,"message":"Timeout: NTEvent serviceAndMethod:NodeIKernelMsgService/sendMsg timed out","retcode":-1,"status":"failed"}`,
} {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(body))
}))
p := newPermissionTestPlugin(t)
p.napcatURL = srv.URL
p.httpClient = srv.Client()
p.sendClient = srv.Client()
_, err := p.napcat("send_private_msg", map[string]interface{}{"user_id": 1, "message": "x"})
srv.Close()
if err == nil {
t.Errorf("OneBot 失败响应必须转成 error，否则「发送失败」会被当成成功: %s", body)
}
}
// 对照：成功响应必须放行（否则正常发送被误报失败 → 模型重发）
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write([]byte(`{"status":"ok","retcode":0,"data":{"message_id":713138214},"wording":""}`))
}))
defer srv.Close()
p := newPermissionTestPlugin(t)
p.napcatURL = srv.URL
p.httpClient = srv.Client()
p.sendClient = srv.Client()
if _, err := p.napcat("send_private_msg", map[string]interface{}{"user_id": 1, "message": "x"}); err != nil {
t.Errorf("正常成功响应被误报失败（会诱发重复发送）: %v", err)
}
}