Repository navigation
中文 / Chinese
v1.9.3:稳定性与中断语义、截断可见、SFTP 吞吐
- 稳定性:工具 handler panic 就地转成该次调用的错误响应,并记录工具名/耗时/结果,不再让客户端等到超时;HTTP 传输增加头读取/空闲超时、头大小上限与 /mcp 请求体上限。
- 后台日志有界:新配置 backgroundLogMaxBytes(默认 8 MiB,-1 不裁剪,$global 可设默认)。超过上限从最早处裁剪并计数,输出开头 64 KiB 另行保留;session action=read 的 offset/totalBytes 为绝对字节,命中裁剪区间时一次返回「保留开头 + 省略标记 + 最新输出」,并报 droppedBytes/logMaxBytes。
- 中断语义:CommandResult 新增 executionState(started = 命令已开始、结果未知;unknown = 断线,可能没开始/在跑/已结束)与 guidance;超时、输出上限、取消、断线都会说明远端可能处于什么状态,并置 replaySafe=false。
- 截断可见:命中 maxOutputBytes 的结果带 truncated/clippedBytes,错误消息与文本尾部明确写「返回内容不完整」;轻压缩正文标注省略行数并说明不完整;落盘预览标注「不是完整输出」;session action=read 被 maxBytes 截断时返回 truncated/remainingBytes,并用返回的 offset 提示续读。
- SFTP 吞吐:下载对超过一个 chunk 的文件走 pkg/sftp 的 WriteTo 流水线读,小文件保留顺序读;上传/续传只要超过一个 chunk 就并发;MaxConcurrentRequestsPerFile 接到 sftpConcurrency;目录传输新增 sftpFileConcurrency(默认 4),大量小文件不再逐文件串行;新增 sftpVerifyChecksum(默认 true)可省掉单文件双端 sha256 的额外远端整文件读取。
- 上下文与修复:session action=read/list 与 list-servers 按 resultFormat 只发一份(默认文本),spill 预览改为头 8 行+尾 4 行;initialize 增加跨工具 instructions;修复 object 形式配置的 resultFormat 从未生效、后台任务 1 秒内跑完被误报启动失败。
- 行为变化:resultFormat 现在真正生效;后台日志默认有 8 MiB 上限;session action=read 的 offset/totalBytes 为绝对字节;单文件校验可用 sftpVerifyChecksum=false 关闭。无破坏性变更。
- 验证:WSL Ubuntu-22.04 下 go test -race ./... 全绿;golangci-lint run ./... 0 issues;go vet -tags integration ./... 干净;完整集成测试通过(含后台读取截断、校验开关、目录并发用例);MCP stdio 端到端验证截断文案与 JSON 字段;localhost 基准无回退,高延迟链路的实际提速尚未实测。
English
v1.9.3: stability and interruption semantics, visible truncation, SFTP throughput
- Stability: a panicking tool handler becomes that call's error response instead of a request the client waits out, and each call logs tool name, duration and outcome; the HTTP transport bounds header read time, idle time, header size and the /mcp request body.
- Bounded background logs: new backgroundLogMaxBytes (default 8 MiB, -1 keeps everything, $global supported). Past the cap the oldest bytes are trimmed and counted while the first 64 KiB are kept aside; session action=read now uses absolute offset/totalBytes, and a read landing in the trimmed region returns the kept beginning, an omission marker and the newest bytes in one answer, plus droppedBytes/logMaxBytes.
- Interruption semantics: CommandResult gains executionState (started = the command ran, outcome unknown; unknown = the connection dropped, so it may never have started, may still be running, or may have finished) and guidance; timeout, output limit, cancellation and connection loss all state what the remote side may have done and set replaySafe=false.
- Visible truncation: hitting maxOutputBytes carries truncated/clippedBytes, and both the error message and the text result say the returned output is incomplete; compressed output names the omitted line count and says it is incomplete; a spill preview says it is not the complete output; a session action=read cut by maxBytes returns truncated/remainingBytes and points at the returned offset for the next read.
- SFTP throughput: downloads larger than one chunk use pkg/sftp's pipelined WriteTo, small files keep the sequential read; uploads and resumes overlap any transfer larger than one chunk; MaxConcurrentRequestsPerFile follows sftpConcurrency; directory transfers gain sftpFileConcurrency (default 4) so a tree of small files is no longer serialized; sftpVerifyChecksum (default true) can skip the extra full remote read of a single-file sha256 check.
- Context and fixes: session action=read/list and list-servers send one payload per resultFormat (text by default); the spill preview is head 8 + tail 4 lines; initialize carries cross-tool instructions; fixes resultFormat being ignored in object-form configs and a background job finishing within one second being reported as a failed start.
- Behaviour changes: resultFormat now takes effect; background logs are capped at 8 MiB by default; session action=read offset/totalBytes are absolute bytes; sftpVerifyChecksum=false disables single-file verification. No breaking changes.
- Verification: go test -race ./... is green on WSL Ubuntu-22.04; golangci-lint run ./... reports 0 issues; go vet -tags integration ./... is clean; the full integration suite passes (including the new background-read truncation, checksum toggle and directory concurrency cases); MCP stdio end-to-end checks cover the truncation text and JSON fields; the local benchmark shows no regression, while the high-latency speedup remains unmeasured.