Skip to content

fix: 会话过期恢复体系增强(callTool 重试/404 识别/前端句柄)+ 本地部署与 E2E 验证工具链 - #7

Merged
kugouming merged 4 commits into
mainfrom
fix/calltool-session-expiry-retry
Sep 2, 2026
Merged

fix: 会话过期恢复体系增强(callTool 重试/404 识别/前端句柄)+ 本地部署与 E2E 验证工具链#7
kugouming merged 4 commits into
mainfrom
fix/calltool-session-expiry-retry

Conversation

@kugouming

Copy link
Copy Markdown
Contributor

Summary

延续 #2([MERC-3] 后台 server 模式连接断开问题)的修复,补全会话过期恢复体系的剩余缺口,并建立本地部署与端到端验证机制。

恢复体系增强

  • 新增 src/routing/session-error.ts:统一会话过期(-32001 / 规范型 HTTP 404)与可重连连接错误(stdio 进程退出、SSE 断流、RESPONSE_STREAM_ENDED 等)分类,路由与 TUI 共用
  • callTool 与发现路径重试扩展:可重连错误首调即透明恢复(失效 → respawn/重连 → 重放);超时与网络不可达保持快速失败(避免延迟翻倍或副作用重复)
  • 404 过期识别修正doSend 会将 HTTP_REQUEST_FAILED 二次包装为 HTTP_SEND_FAILED,按真实传播形态匹配(E2E 实测发现)
  • findTool 复用发现缓存(60s TTL):每次调用减少一次后端 tools/list 往返,过期重建频率减半
  • 前端会话句柄语义(server 模式):失效/被回收的 Mcp-Session-Id 同 id 透明重建,客户端无需重新握手;TTL 5→30 分钟降级为 GC;会话数 10k 上限护栏
  • TUI discovery-worker:会话过期自动重试(懒重建)+ HTTP 404 识别

本地部署与 E2E 验证工具链

  • npm run deploy:local:clean+build → npm pack → tarball 全局真实安装(install-shape 硬校验,防软链式假安装)→ 安全重启 daemon → 冒烟
  • npm run verify:local:自包含端到端回归,10 场景 15 断言
    • 正常 N1-N6:HTTP 连接复用 / stdio / SSE / 标签过滤 / ping+DELETE / 诊断端点
    • 恢复 F1-F4:HTTP -32001 与 404 过期重建(/__expire 控制端点触发)、stdio 崩溃 respawn、前端会话句柄重启重建
  • build 显式前置 clean + 产物新鲜度断言,杜绝历史产物残留

文档

  • CLAUDE.md 收敛为唯一 AI 规范源,新增「E2E 场景回归规则」专节;删除 AGENTS.md;README 更新场景清单

关联 Issue

验证结果

  • vitest:988/988 通过(新增 37:错误分类 / 崩溃重试 / 404 恢复 / discovery-worker / 会话上限等)
  • verify:local:15/15 断言通过(连续两轮稳定)
  • deploy:local:真实 tarball 安装 + 形态校验通过,:5625 冒烟正常
  • typecheck / lint / format:全绿

Test plan

  • npm test 全量回归
  • npm run deploy:local 本地部署冒烟
  • npm run verify:local 端到端 10 场景回归
  • 真实 jymcp 后端:Inspector 工具页长停留后调用工具无 -32001

- tool-router 的 callTool 遇到 -32001 会话过期错误时作废连接并重试(最多 maxConnections+1 次),非会话错误与工具级错误仍快速失败
- server-mode 将失效的 mcp-session-id 视为句柄按原 id 重建会话,不再返回 404/-32001;会话清理空闲超时调整为 30 分钟
- session-manager 支持 createSession 传入显式 id 重建会话
- 补充 tool-router / session-manager 单元测试及集成测试,改用全局 fetch mock 替代 node-fetch
- 新增 src/routing/session-error.ts:统一会话过期(-32001/规范型 HTTP 404)
  与可重连连接错误的分类,供路由与 TUI 共用
- callTool 与发现路径重试条件扩展至可重连错误(stdio 崩溃、SSE 断流、
  RESPONSE_STREAM_ENDED),首调即透明恢复;超时/网络不可达保持快速失败
- 修正 404 过期识别:doSend 会将 HTTP_REQUEST_FAILED 二次包装为
  HTTP_SEND_FAILED,按真实传播形态匹配
- findTool 复用发现缓存(60s TTL),每次调用减少一次后端 tools/list 往返
- TUI discovery-worker:会话过期自动重试(懒重建)+ HTTP 404 识别
- SessionManager 会话数上限护栏(10k,最旧空闲驱逐)
- 新增单测 13 个、集成用例 3 个(404 恢复 / discovery-worker 三场景)
- deploy:local:clean+build → npm pack → tarball 全局真实安装(install-shape
  硬校验,防软链式假安装)→ 安全重启 :5625 daemon → initialize 冒烟
- verify:local:自包含 E2E 回归,10 场景 15 断言
  - 正常 N1-N6:HTTP 连接复用 / stdio / SSE / 标签过滤 / ping+DELETE / 诊断端点
  - 恢复 F1-F4:HTTP -32001 与 404 过期重建(/__expire 控制端点触发)、
    stdio 崩溃 respawn、前端会话句柄重启重建
- 共享安装管道 scripts/lib/install-local.mjs(构建产物新鲜度断言)
- build 脚本显式前置 clean,杜绝历史产物残留
- 文档:CLAUDE.md 收敛为唯一规范源并新增 E2E 场景回归规则;删除 AGENTS.md;
  README 更新场景清单
@kugouming
kugouming merged commit e4d92f7 into main Sep 2, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant