一到十一的 go test 测的是函数。评测测的是整条 ReAct：终态对不对、调了哪些工具、取消后是否成对。性能先有尺子，再谈优化。这一刀两件事一起做：剧本回放，以及在已有 Trace 上记三个数。

本文对应 go-tiny-claw 提交：

1

8fd935d  feat: 用剧本回放评测 Agent，并在 Trace 上记下延迟尺子

官方 A2A 与 spawn_subagent 在 ee4048b，不在本篇展开。

一、评测不是再写一遍 engine 测试

test/engine 里已经有预算、取消、断档。每份测试自己捏一个假 Provider，证明某一个分支。评测要的是同一套入口、多条固定任务：给一句 prompt，跑完 Engine.Run，对历史和工作区打分。

1
2
3
4
5

任务是否完成
是否调用正确工具
是否越权写入
取消后 Observation 是否成对
Token 超了会不会停

真模型贵、飘、难进 CI。第一刀只用剧本：按轮吐固定的 assistant / ToolCall，工作区是 t.TempDir()。

二、eval 在根上，只调用 internal

评测不是 Engine 的一部分，循环不该 import eval。它和 cmd/claw 一样，是消费方：

1
2
3
4

eval  →  internal/engine
     →  internal/context
     →  internal/tools
     →  internal/observability

放根目录 eval/，一个包，先不分 cases/。go test ./eval 就能跑。以后要 cmd/claw_eval，直接 import 这个包，不必从 test/ 里往外搬。

1
2
3
4
5

eval/script.go     剧本 Provider，可带 Delay
eval/run.go        组 Engine / Session / Gate，调用 Run
eval/assert.go     历史、工具名、Observation
eval/metrics.go    从 Agent.Run 读尺子
eval/cases_test.go 六条任务

Run 自己 StartSpan("Eval")，Engine 再挂上 Agent.Run。评测结束时父 span 还在，尺子从子 span 读，不用改 Run 的返回值。

默认 Registry 只有 read_file / write_file / edit_file，不接 MCP、不拉 Factory。审批默认 AllowOnce；要测拒绝就传入 DenyHandler。

三、六条任务证明什么

预算那条复用阶段九的闸：第一次调用用满额度，第二次 checkRunBudget 直接错。评测断言的是「停了，而且假模型只被叫过一次」，不是再实现一遍预算。

四、尺子写在已有 Trace 上，不另打日志

机制早就有：首 Token 超时 15 秒、Session 累计 Token、工具墙钟。缺的是数字。超时逻辑不动，只在 generate 里记下第一次吐字（或非流式 Generate 成功返回）距开始的毫秒，属性名 ttfb_ms。同一 span 只记一次。

endRunBudget 会把 toolElapsed 清零。所以根 span 的 defer 必须先快照再清：

1
2
3
4

prompt_tokens / completion_tokens
tool_wall_ms
把子 span 上第一个 ttfb_ms 抄到 Agent.Run
然后 endRunBudget、EndSpan、写盘

eval.MetricsFrom 找到 Agent.Run，读这四个数。CI 只跑假 Provider。真模型的「首 Token 800ms」是夜间任务，不要进 go test。

五、阶段十二还没做完的

1
2
3
4
5

真模型评测（同一套断言，分数允许浮动）
Trace 异步写盘
cmd/claw_eval
并发 Run 压测、连接复用
部署：密钥、租户、健康检查、SLO

TotalCostCNY 仍是 0。MCP 工具热刷新也还没做。评测集以后加任务，往 cases_test.go 里加函数即可；框架不必跟着涨。

总结

二十四解决「手和同事从哪来」。二十五解决「怎么知道没回退，以及慢在哪」：

1
2
3
4
5
6
7
8
9

eval/ 单向调用 internal，不进 Engine
    ↓
剧本 Provider + TempDir，六条固定任务
    ↓
同一条 Engine.Run，对历史和工作区打分
    ↓
根 span：ttfb_ms、Token、tool_wall_ms
    ↓
CI 只跑假模型

有回放才能改循环而不瞎；有尺子才知道慢的是模型、工具还是写 Trace。部署治理另开。

MCP 是远程的手：一次函数调用，拿回一段结果。A2A 是远程的同事：整件任务丢过去，对方自己想、自己调工具，回来交一份报告。模型两边都只看见本地 ToolDefinition，不会直接讲 JSON-RPC。

本文对应 go-tiny-claw 两次提交：

1
2

d516575  feat: 将 MCP 工具和 A2A 委派接到本地 Registry
47c256a  feat: 支持 Streamable HTTP MCP，并改用 OpenAI 环境变量

一、外来的手必须进同一道门

路线图写得很死：外部工具及远程 Agent 必须复用同一个 Context、Approval 和 Observability，不能因为来自 MCP 就绕过本地安全边界。

所以这一刀的形状是适配，不是另起一套引擎：

1
2
3
4
5
6
7
8
9
10

.claw/mcp.json
    ↓ command 或 url
MCP Server（stdio 子进程 / HTTP）
    ↓ initialize → tools/list
Adapter（mcp_<server>_<tool>）
    ↓ schema.ToolDefinition + RiskLevel
本地 Registry
    ↓ Approval Gate
    ↓ tools/call
MCP Server

名字加前缀，两个服务器都叫 search 也不会撞。风险写在配置里，不信远端自己报的安全等级；缺省当成 dangerous，默认要审批。

A2A 更简单：Registry 里多一个 delegate_agent，风险同样是危险。参数是 message，外加 url 或 .claw/a2a.json 里的 peer。模型发出去的是「请对方做完这件事」，不是远程那一侧的工具列表。

二、Client 只认三件事

MCP 规范很长。第一刀只做模型真正用得到的：

1
2
3

initialize + notifications/initialized
tools/list
tools/call

resources、prompts、sampling、工具热刷新都没做。启动时列一次，挂到 Registry，进程活着就用这份。某个服务器连不上，整份 MCP 一起失败：与其 silently 少几只手，不如启动时就看见。

Client 本身不读 stdin、不发 HTTP。它只分配 JSON-RPC id，调 Transport：

1
2
3

SendRequest
SendNotification
Close

取消时立刻把错误还给调用方，notifications/cancelled 异步发出去。stdio 底下是 io.Pipe，同步写会堵死：读循环还卡在等响应，写通知没人读。取消测试曾经因此卡满 1 秒。

三、stdio 先通，HTTP 再拆一层

本地调试用 stdio：command + args + env，工作目录就是 Agent 的 workspace，换行分隔 JSON-RPC。子进程跟 Factory 走，factory.Close() 杀掉。

要接托管服务（例如只给 URL 和 Bearer 的 OTA），stdio 不够。第二刀把读写从 Client 里抽走，补上 Streamable HTTP：

1
2
3
4
5
6
7
8

POST JSON-RPC
Accept: application/json, text/event-stream
记下响应头 MCP-Session-Id
initialize 之后带上 MCP-Protocol-Version
SSE 只收匹配当前 id 的 data:
通知接受 202 或 200
Close 时 DELETE 会话
401 / 403 → MCP 鉴权失败

协议版本写死 2025-11-25。GET 挂长连接、会话恢复、断线续传都没做。响应可以是一整段 JSON，也可以是 SSE；扫描到对应 id 就返回，通知事件丢掉。

配置互斥：一个服务器只能有 command 或 url，两个都写或两个都不写直接失败。HTTP 的 headers 支持 ${ENV}。变量不存在或值为空，加载配置失败——密钥不要写进 mcp.json，也不要在缺 Key 时默默连上去。

示例（密钥在环境变量里，不进仓库）：

1
2
3
4
5
6
7
8

{
  "name": "combos-ota",
  "url": "https://ota.combos.fun/mcp",
  "headers": {
    "Authorization": "Bearer ${COMBOS_OTA_MCP_KEY}"
  },
  "risk": "mutating"
}

启动脚本要先 source .env。直接 go run 不会读 .env。缺了 COMBOS_OTA_MCP_KEY，整个 Agent 起不来，这是故意的。

四、连接挂在 Factory 上，不挂在单次 Run

MCP 子进程和 HTTP 会话都贵。Factory 懒创建一份 Manager，每次 NewRuntime 只往新 Registry 上 Register。REPL 多轮、WebSocket 多会话，共用同一批远端。

cmd/claw 和 cmd/claw_server 都 defer factory.Close()。stdio 杀进程，HTTP 发 DELETE。不关就会留下 npx 子进程，或者远端会话一直占着。

Adapter 的 Execute 把 tools/call 的文本块拼起来。远端标了 isError，返回中文错误，走 Recovery，不伪装成功 Observation。

五、A2A 用自己的信封，不假装官方协议

官方 A2A 是另一套 JSON-RPC。这一刀只解决「把任务交给另一个 claw」：

1
2
3

POST /a2a/message
GET  /a2a/agent-card
GET  /.well-known/agent-card.json

响应仍是项目约定的 {code, message, data}。挂在现有 :8081 上，不另开端口。入站走 Manager，Ask 类工具一律 Deny：远端没有人坐在终端前点 y，不能让远程 Agent 改你的磁盘。

出站工具危险，要本地人批。回来的是一段报告，不是对方内部的 ToolCall 轨迹。spawn_subagent 仍是进程内子智能体，这一刀没有把它注册进 Factory。

六、测试要证明什么

MCP：

1. stdio 能 tools/list / tools/call，注册名带 mcp_ 前缀
2. 取消立刻返回，不必等远端做完
3. 没有配置文件等于没有远端，不报错
4. 必须只写 command 或 url 之一
5. HTTP 能握手、列工具、调用，并带上 Session 头
6. ${ENV} 能展开；缺变量或 command/url 同时出现则失败

A2A：

1. 入站空消息拒绝
2. Agent Card 能 GET
3. delegate_agent 能把 peer 解析成 URL
4. 既没有 url 也没有已知 peer 则失败

七、阶段十一还没做完的

1
2
3
4
5
6

MCP resources / prompts / sampling
启动后刷新工具列表
GET SSE 长连接与会话恢复
官方 A2A JSON-RPC / 流式
把 spawn_subagent 挂进 Factory
某个 MCP 失败时跳过而不是整组失败

阶段九留下的 TotalCostCNY 仍是 0。未使用的 Claude Provider 已经删掉，入口改成 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL。费用记账仍不是 MCP 的前置条件。

路线图里的「工具发现和刷新」「远程超时单独治理」「工具版本兼容」都还粗。现在的发现是启动时列一次；超时复用调用方 Context；版本就是握手里那个字符串。

总结

二十三解决「进程没了如何接上」。二十四解决「手和同事从哪来」：

1
2
3
4
5
6
7
8
9

模型只看见本地 ToolDefinition
    ↓
MCP：stdio 或 Streamable HTTP，进同一 Registry / Gate
    ↓
名字加前缀，缺省危险，密钥走 ${ENV}
    ↓
连接挂 Factory，Close 杀进程或 DELETE 会话
    ↓
A2A：自己的信封，入站 Ask 一律拒

阶段十二是评测、性能和部署。MCP 先能调用、A2A 先能交差，就可以停。

路线图里阶段十还写了「当前 Run 状态」「卡在审批 / 工具执行中」。那一刀没做。磁盘上看不出工具做到哪了，重跑 bash / write_file 可能重复副作用。这一篇只收两刀：能读回历史和 Token；断档只补 Observation。

本文对应 go-tiny-claw 两次提交：

1
2

b961e9e  feat: 将会话历史和 Token 累计落到工作区磁盘
626cdfd  feat: 为中断的工具调用补齐 Observation

一、先能接上聊天，不恢复「做到一半」

Grant 早就写在 .claw/grants.json。Session 一直在内存里，REPL 一退就没了。阶段十的第一刀只存这些：

1
2
3

Session 元数据（id、workdir、时间）
Message 历史
Token 累计（费用字段带着，值仍是 0）

不存这些：

1
2
3

正在等模型
正在等审批
工具执行到一半

「等待模型」重启后下一句会再打，没问题。「等待审批」没结果就当没点过 y。「工具执行中」是危险区：文件可能已经写完，Observation 还没 Append。

二、一个会话一个文件，对齐 Grant 的原子写

授权是整份 grants.json。会话按 ID 拆开，避免改一个会话重写全部：

1

.claw/sessions/<id>.json

文件名拒绝 /、\、..，避免 sessionID=../../etc/passwd 写到工作区外面。CLI 现在的 terminal_default 可以直接当文件名。

快照就是 Session 里已经有的字段，外加 history。schema.Message 自带 JSON tag，工具参数里的 json.RawMessage 也能过。写入用 MarshalIndent，嵌套 arguments 会被重新排版，读回来要比语义，不要比原始字节。

写盘抄 Grant：先 .tmp，再 Rename。半截写不会留下半个 JSON。文件不存在或空文件当成新会话；JSON 坏了往上抛，不要假装空会话再覆盖坏文件。

Append / RecordUsage / Clear 在持有 Session.mu 时写盘。先 Unlock 再写，两个 Append 并发时旧快照会盖掉新的。落盘失败第一刀只打日志，不改函数签名；内存仍保留。Clear 本来就不清 Token，落盘后预算也不会因 /clear 归零。

第一次 GetOrCreate 不写空文件，等第一次变更再出现。RunSub 用的是裸 NewSession("run-sub", "")，没有 persistDir，子智能体历史不进磁盘。

三、新建会话必须挂 persistDir，Factory 的 nil 才能走文件

只在 loadSession 里设 persistDir 不够。新建会话的 Append 会看到空目录，直接 return，第一份文件永远出不来：

1
2
3
4
5

GetOrCreate → NewSession（没挂 persistDir）
    ↓
Append / RecordUsage 不写盘
    ↓
重启再 GetOrCreate → 文件不存在 → 又是空会话

GetOrCreate 新建时补上一行：sess.persistDir = sm.persistDir。GlobalSessionMgr 的目录仍是空串，Engine 测试不碰磁盘。

cmd/claw 和 cmd/claw_server 都是 NewRuntimeFactory(..., nil)。以前 nil 会先换成 GlobalSessionMgr，后面的懒创建 FileSessionManager 是死代码。现在 nil 原样进去，sessionManager() 才走到 .claw/sessions。测试里显式传入 GlobalSessionMgr 的，仍然纯内存。

GetOrCreate 改成返回 error。坏文件必须让 NewRuntime 失败。读盘后用调用方 workDir 覆盖文件里的路径：工作区搬家后，工具不要锁死在过期目录。CreatedAt 和 Token 仍用文件里的。

MaxTokens 按 Session 累计。重启后预算接着算，杀进程洗不掉额度。

四、断档只补 Observation，不重跑工具

活着的那一轮，助手带 ToolCalls 入库之后，取消路径已经用 EnsureToolObservations 补「工具调用已取消」。那是当前这一轮的平行数组，不管落盘后的聊天记录。

进程死在这里：

1
2
3

session.Append(助手 + ToolCalls)     // 已落盘
    ↓
审批 / Execute / Append(Observation)  // 还没写上

下次 GetWorkingMemory 会把未配对的 ToolCalls 送给模型。Provider 可能直接拒；模型也可能以为工具已经跑过。

工具重放是按当时的参数再 Execute 一次。磁盘上看起来都一样：助手有调用，后面没有结果。分不清「做完了没记账」和「还没做」：

所以只插入一条「工具调用未完成（上次运行中断）」。文案不和活着的「已取消」混用，模型不应当成已经执行成功，可以自己决定要不要再调。只读的 read_file 重放相对安全，但收益小，模型看见未完成自己会再读。

RecoveryManager 是工具报错提示，不管崩溃。GetWorkingMemory 开头丢掉的是窗口边缘的孤儿结果，不是孤儿调用。

五、插入，不要 Append 到末尾

Runtime.Start 会先把新的用户那一句写进历史，再进 Engine.Run。如果补丁加在末尾：

1
2
3

助手 [call-1]
用户：下一句
用户：工具未完成      ← 错，Observation 必须紧跟助手

RepairIncompleteTools 扫一遍谁已经有 ToolCallID，缺的插到该助手后面、已有 Observation 的后面、下一条非 Observation 的前面。同一助手缺两条，从后往前插，顺序仍是 call-1、call-2。已经成对则不动 UpdatedAt、不写盘。

两处调用：

1
2

GetOrCreate 读盘成功 → Repair（磁盘先合法）
Engine.Run 进循环前 → Repair（测试直调 Run、内存命中也能盖住）

因为是插入，即使 Start 已经写下「下一句」，Observation 仍会插回助手后面。RunSub 不用加：跟父会话时父 Run 已经修过；独立跑是空会话。

活着的取消仍走 EnsureToolObservations。两套不要合成一套。

六、测试要证明什么

落盘：

1. Append + RecordUsage 后换一个 FileSessionManager，历史、Token、费用字段、CreatedAt 还在
2. 第一次 GetOrCreate 不写空文件
3. 工具调用和 ToolCallID 能过 JSON
4. Clear 后历史空、Token 还在
5. 重载时用调用方 workDir
6. 空 workDir、非法 ID、坏 JSON 失败；空文件当新会话
7. GlobalSessionMgr 不创建 .claw/sessions
8. Factory 传 nil，Run("你好") 后新 Factory 再用同一 ID，模型请求里能看到上一句

断档：

1. 两条 ToolCall 只回了一条，只补缺的那条，已有结果不改
2. 助手后面已经是「下一句」，Observation 插在中间
3. 已经成对，不再插入，不改 UpdatedAt
4. 磁盘上只有断档助手，新 Manager GetOrCreate 读回来已经成对
5. Engine.Run 直调：发给模型的 messages 里该 ToolCallID 已有 Observation

七、阶段十还没做完的

1
2
3
4
5

当前 Run 状态（等模型 / 等审批 / 工具执行中）
工具重放或补偿流程
Clear 时连 Token 一起归零
TotalCostCNY 仍是 0（阶段九尾巴）
Claude HTTP 还没套重试（入口没用它）

路线图说「只有状态和 Observation 一致才能继续」。现在的一致是：不一致就标成未完成，让模型重想，不让运行时重做。审批卡在中间同理，不要当成用户点过 y。

真要重放，得先有检查点：执行前写 intent，成功后再写结果。那是另一套设计。阶段十收到「落盘 + 断档修补」就可以停。下一阶段是路线图里的工具生态和 MCP / A2A。

总结

二十二解决「这一发何时停」。二十三解决「进程没了之后如何接上，又不把工具再跑一遍」：

1
2
3
4
5
6
7
8
9

.claw/sessions/<id>.json，tmp + Rename
    ↓
新建会话挂 persistDir；Factory nil 走文件
    ↓
重启后历史和 Token 还在，预算接着算
    ↓
孤儿 ToolCall 插入「未完成」，不 Execute
    ↓
插在助手后面，不要 Append 到新用户消息之后

阶段十一再谈外部工具和远程 Agent。费用记账仍不是前置条件。

1
2
3
4
5
6

Token 超了不会停 Run
CostTracker 只实现 Generate，包上去会丢掉流式
固定 200ms 还不是指数退避
没有单独的模型调用超时
没有首 Token 超时
流式半响应只是普通 error

后来又补上单次 Run Token、派出次数和工具墙钟，并让 RunSub 共用同一本账。

本文对应 go-tiny-claw 这几次提交：

1
2
3
4
5
6
7
8
9

3b430d6  feat: 在主循环与 RunSub 的 trace 中记录 Token 消耗
ce7e757  feat: 在模型调用前检查 Session Token 预算
93d3b76  feat: 为模型重试增加指数退避与单次调用超时
9aa7f78  feat: 为流式模型调用增加首 Token 超时
06682fe  feat: 将流式半响应标成不可重试错误
e3a2701  feat: 增加单次 Run 的 Token 预算并与会话累计分开
24ddcff  feat: 为生产 Engine 设置单次 Run Token 上限
6a7421b  feat: 限制单次运行的工具墙钟时间和 Subagent 派出次数
7e230a6  refactor: 拆分 Engine 循环并让 RunSub 共用运行预算

一、预算放在 Engine，不放在 Provider 外套

二十一提过：不要再做一个只实现 Generate 的 CostTracker 挡在最外层。流式会被它吃掉。记账和停 Run 都应该读 Session 里已经有的 Usage。

最后删掉了那个装饰器。数字进 Session，闸门在 AgentEngine：

1
2
3

checkBudget       每次 generate 之前，读 Session 累计
checkRunBudget    同样在 generate 之前，读本次 Run 增量
recordUsage       这次 generate 成功之后

Session.TotalTokens() 加锁读 TotalPromptTokens + TotalCompletionTokens。MaxTokens <= 0 视为不限，单元测试保持这个默认。工厂里会话上限 200000。

MaxTokens 计量的是 Session，不是单次 Run。GetOrCreate 同一个 ID，账一直加，REPL 下一发不会从零算。报错是「已超过本会话的 Token 预算」。

语义是停 下一次 模型调用，不是把已经打完的最后一句作废。第一次 Action 用满上限、没有工具要跑，应成功。第一次带了工具、累计已经顶到上限，下一轮 Action 前再拦。

Trace 只是把同一份 Usage 写到 Thinking / Action / RunSub 的 span 上，不参与停 Run。

二、单次 Run、派出次数、工具墙钟

只靠会话 Token 挡不住「这一发工具循环把账烧光」。后来加了三道按 一次 Run 计的闸，<= 0 都不限：

单 Turn Token 没做：没开 Thinking 时一轮就是一枪，枪前增量永远是 0。卡一次 Run 比卡一轮更合理。

工具时长不要套在整个 Run 的 ctx 上，否则模型也会被掐。toolBatchContext 只包 Execute。并行同一波只算这一波墙钟，不加总每个 goroutine。审批等待不算。bash 的 30s 仍是单次命令。2 分钟是保险丝，构建/测试多的任务会先撞它。

RunSub 现在接同一套：主循环进行中就写进主 Session、累加主 toolElapsed；单独调用则用临时 Session 和自己的计时。子循环仍最多 10 轮。MaxTurns（主 20）管不着子循环。Retry / CallTimeout / 首 Token 在 Provider 上，子循环同样有效。

循环拆开之后，预算在 budget.go，工具波次在 tools_batch.go，Run / RunSub 共用 runToolBatch。

三、退避按失败次数加倍，封顶 2 秒

Backoff 仍是第一档，默认 200ms。第 n 次失败后等 Backoff * 2^(n-1)，封顶 MaxBackoff（默认 2s）。Backoff == 0 立即重试，旧测试不用睡。

wait 继续用 Timer + select 听父 ctx。Ctrl-C 不必等满退避。

四、两层超时，不要共用一个 ctx

整次尝试用 CallTimeout（默认 60s），包在 attemptContext 里传给底层。这管「这一枪从开打到结束」。

首 Token 不能写进同一个 ctx。字已经出来之后，那个 timeout 一到会把还在流的 HTTP 掐死。所以首 Token（默认 15s）是消费循环上的定时器：

1
2
3
4

attemptCtx = CallTimeout          整次尝试
firstToken 定时器                 通道已开、还没有任何事件
任意事件到达（delta / completed / error） 立刻停表
之后再慢只走 CallTimeout

select 三路：父 ctx、首 Token 表、inner。父 ctx 和定时器同时就绪时，Go 会随机选一条，所以走进 case <-firstToken 还要再看一次 ctx.Err()。否则 Ctrl-C 会被写成「模型首 Token 超时」，还可能按 DeadlineExceeded 再打一次。

同步 Generate 没有「第一个字」和「整段回复」的区别，只保留 CallTimeout。FirstTokenTimeout == 0 关掉首 Token 表，测试默认这么做。

文案分开：模型调用超时 对整次尝试，模型首 Token 超时 对还没出字。两者都包着 DeadlineExceeded，shouldRetry 认它，没出字可以重试。

五、吐字之后再断，是半响应，不是 429

二十一已经规定：转发过 text_delta / completed 不再重试。缺的是类型。吐字后的 429 如果原样往外扔，ClassifyError 仍会说可重试。出字后的 CallTimeout 会变成 canceled。

所以加 PartialResponseError，里面留着原来的原因。ClassifyError 先认半响应，再看取消和 HTTP：

1
2
3
4

PartialResponseError     →  fatal，不重试
Canceled / DeadlineExceeded  →  canceled
HTTP 429 / 5xx / net 超时   →  retryable
其余                     →  fatal

wrapPartial 已经是半响应就不再包一层。

只在用户已经看到字时包装：

1
2
3

forwarded 且收到 StreamError     → wrapPartial（父 ctx 取消除外）
forwarded 且通道空关             → wrapPartial(未返回最终消息)
没出字就结束                    → 普通错误，不是半响应

本仓库工具调用不单独推 delta，只出现在 completed 里，所以 completed 也算「已经转发」。父 ctx 取消仍返回 ctx.Err()，不要写成半响应。

六、测试要证明什么

会话 Token：

1. 第一次 generate 用满上限且还要再打，第二次不准发出去
2. 最后一轮答完、后面没有 generate，用满上限也成功

单次 Run Token：会话里已有 100，本次运行用满 10 会停下一枪；最后一枪答完不再打则成功。文案是「本次运行」，不是「本会话」。

派出次数：MaxSubagents = 1 时第二次 RunSub 失败且不再打模型；新的 Run() 会清零。

工具墙钟：卡住的工具听 toolCtx，30ms 后报「工具时间预算」，不再打下一枪；工具很快结束则跑完第二枪。

RunSub：自己也能顶满 Run Token / 工具时间；从主循环派出时，Token 记进主 Session。

退避：200ms → 400ms，封顶 500ms；Backoff = 0 等待为 0。

整次超时：堵在 ctx.Done() 上的 Generate，CallTimeout = 20ms、两次尝试，报「模型调用超时」。父 ctx 已取消，一次都不打。

首 Token：

1. 开口 1 秒才出字，20ms 超时，重试 2 次，报「模型首 Token 超时」
2. 10ms 出字、200ms 限额，只打一次
3. 先吐 hello 再卡到 CallTimeout：只打一次，错误是「模型调用超时」，不是首 Token

半响应：

1. 半响应包着 429 或 DeadlineExceeded，分类都是 fatal
2. 先 delta 再 429：不重试，外层是 PartialResponseError，仍能 errors.As 出 429
3. 吐字后通道直接关：半响应，不重试
4. 上面第 3 条尾包超时，现在也是半响应，文案里还能看到「模型调用超时」

七、阶段九还没做完的

1
2

TotalCostCNY 一直是 0，recordUsage 第三个参数没算钱
Claude 的 HTTP 状态还没翻译（入口没用它）

可靠性可以停。Token、派出次数、工具墙钟都已能停 Run。费用仍是空账，先跳过计价。

阶段十是 Session 落盘和任务恢复。它依赖「一次 Run 能干净失败」。Token 闸门已经能停，费用闸门不是前置条件。

总结

二十一解决「失败之后怎么办」。二十二补上「什么时候不准再打」和「流式失败分别是什么」：

1
2
3
4
5
6
7
8
9
10
11

Session 累计 Token + 单次 Run 增量，generate 前检查
    ↓
派出次数卡在 RunSub 入口；工具墙钟只套 Execute
    ↓
RunSub 挂在主 Run 上时共用同一本账
    ↓
Backoff 加倍，封顶 2s
    ↓
CallTimeout 管整次；首 Token 只盯还没出字
    ↓
已吐字再断 → PartialResponseError，fatal

下一阶段是 Session 落盘：先能存历史和 Token，先不做「卡在工具执行中」的崩溃恢复。

本文对应 go-tiny-claw 两次提交：

1
2

fa1085b  feat: 为模型调用增加可重试错误分类与重试包装
b1557fa  feat: 将 OpenAI 错误映射为可重试类型并接入 Retry

一、只重试模型，不重试工具

重试必须包在 Provider 外面，不能写进 Engine 的工具循环。

1
2
3
4
5

Engine.generate
    ↓
RetryingProvider
    ↓
OpenAI / Claude

Generate / GenerateStream 失败且可重试，再打一次模型。这一轮已经跑过的工具 Observation 还在 Session 里，不会因为 HTTP 抖动再执行一次。

默认 3 次，间隔 200ms。间隔用 Timer + select 听 ctx，不用 Sleep：Ctrl-C 不必等满退避，定时器用 Stop 拆掉。

取消和截止不重试。context.Canceled / DeadlineExceeded 是 Run 要停，不是瞬时故障。

二、先分类，再决定重不重试

ClassifyError 不认任何一家 SDK。它只看三件事：

1
2
3

Canceled / DeadlineExceeded  →  canceled，不重试
HTTP 429、5xx、net 超时     →  retryable
401、400、普通错误           →  fatal

HTTP 状态收在自己的 HTTPError 里，errors.As 能穿过外层的 %w。这样 fmt.Errorf("OpenAI/Zhipu API 请求失败: %w", httpErr) 仍然能分出 429。

不要把 *openai.Error 写进 ClassifyError。Claude 以后也会失败，分类器不该依赖某一家客户端。

三、流式：没吐字才能重来

RetryingProvider 实现了 StreamingProvider。只实现 Generate 的话，Engine 会走同步路径，终端看不到打字。底层不会流式时，先走带重试的 Generate，再补一条 completed。

流式重试多一条规则：

1
2
3
4
5
6

还没转发 text_delta / completed
    且错误可重试
    → 丢掉这次失败，再开一条流

已经把字发给 Reporter
    → 不再重试，把 StreamError 原样往外传

已经吐出的「你好」不能再打一遍「你好」。半截流标成失败，让 Engine 停，而不是当新请求重放。

generate 在 ctx.Done() 时会立刻返回，不等生产者 goroutine。生产者自己听同一个 ctx：wait、sendStreamEvent、底层 GenerateStream 都会停，然后 defer close。这不是泄漏，是取消后自己收尾。

四、SDK 错误要在出厂时翻译

分类器认 HTTPError，OpenAI SDK 给的是 *openai.Error（带 StatusCode）。翻译放在 openai.go：

1
2
3
4
5
6
7
8
9
10

func WrapOpenAIError(prefix string, err error) error {
if err == nil {
return nil
}
var apiErr *openai.Error
if errors.As(err, &apiErr) {
err = &HTTPError{StatusCode: apiErr.StatusCode, Err: err}
}
return fmt.Errorf("%s: %w", prefix, err)
}

同步 Completions.New 和流式 stream.Err() 都走它。buildParams 失败、工具参数非法 JSON 不走：那是本地问题，再打一次请求没有意义。

不是 API 错误的超时、断连不要改成 Fatal。前缀加上之后，里面的 net.Error 还在，分类器仍能判成可重试。Canceled 包完仍是 canceled。

五、接线包在 main，不包进工厂

1
2
3

llmProvider := provider.NewRetryingProvider(
provider.NewOpenAICompatibleProvider("glm-5-2-260617"),
)

NewRuntimeFactory 继续收任意 LLMProvider。测试里的 fake 不该被强制套上 Retry。也不要把 Retry 写进 NewOpenAICompatibleProvider：客户端和重试策略要分开。

ClaudeProvider 这次没映射、没接线，两个入口都没用它。

六、测试要证明什么

分类：429 / 500 / 包装后的 429 / 网络超时可重试；401 / 400 / 普通错误不可重试；取消和截止是 canceled。

Retry：

1. Generate 连着两次 429，第三次成功，一共 3 次
2. 401 只打 1 次
3. 第一次 500 之后取消，不再打下一次
4. 流式先 StreamError(429) 再成功，外层只看到成功的 delta 和 completed
5. 先 delta 再 429，不重试，错误原样转发

映射：构造带 StatusCode 的 *openai.Error，走 WrapOpenAIError 再 ClassifyError。不打真 API。失败断言不要 %v 打印 SDK 错误：Request / Response 为空时，SDK 的 Error() 会 panic。

七、阶段九还没做完的

1
2
3
4
5
6
7

CostTracker 能记账，但 main 没包，超了也不会停 Run
它只实现了 Generate，包在最外层会丢掉流式
单次 Run / Session 的 Token 与费用上限
首 Token 超时
流式半响应单独标错
固定 200ms 还不是指数退避
Claude 的 HTTP 状态还没翻译

路线图里的工具时长、Subagent 次数可以后做。重试已经保证「只打模型」，预算停 Run 时也不该回头重放工具。

总结

阶段九第一刀是让失败可分类、可重试，并且不碰工具：

1
2
3
4
5
6
7
8
9

ClassifyError 只认 HTTPError / net.Error / context
    ↓
Retry 只包 Generate / GenerateStream
    ↓
流式吐字后不重放
    ↓
openai.go 把 SDK 错误收成 HTTPError
    ↓
两个入口在工厂外面包 NewRetryingProvider

下一刀是预算：超了用中文错误结束当前 Run，记账还要能跟上流式。

1
2
3

符号链接跟随后仍可能逃出工作区
bash 可以 cd .. 或 cat /etc/passwd
Grant 落盘后看不出批了哪次、何时批的

本文对应 go-tiny-claw 三次提交：

1
2
3

f90da50  feat: 在持久化 Grant 中记录审批请求与时间
fd625bc  feat: 解析文件路径时跟随符号链接并拒绝逃出工作区
b3473ba  feat: 拒绝试图访问工作区外路径的 bash 命令

一、词法沙箱挡不住符号链接

ResolveWithinWorkspace 上一篇只做字符串：Abs、Clean、Rel。workDir/link.txt → /etc/passwd 的相对名仍在区内，read_file 又是 RiskSafe，打开时内核会再 follow 一次。

所以要两道检查：

1
2
3

词法 Rel(root, resolved)     挡住 ../outside
    ↓
EvalSymlinks 后再 Rel        挡住区内 link 指向区外

工作区自己也可能是链接。macOS 上 /var 常指向 /private/var。比较真实落点时，两边都要用解开后的根，否则区内路径会被误判成逃逸。

目标文件还不存在时（write_file 先解析、再 MkdirAll），不能对整条路径 EvalSymlinks。从父目录往上走到第一个存在的祖先，再拼回后面的相对段：

1
2
3
4
5

subdir/a.go 且 subdir 不存在
    → 跟到 workDir，拼回 subdir/a.go，区内，通过

out/new.go 且 out → /tmp/outside
    → 跟到 /tmp/outside/new.go，Rel 失败

返回值仍是词法路径，不是 follow 之后的真实路径。调用方写入的是用户给的那个名字；测试也比较 Abs(Join(workDir, ...))。已经确认目标在区内，Open(resolved) 再 follow 一次是安全的。

错误要拆开：真正越界报「路径超出工作区」；权限不够、符号链接环报「解析符号链接失败」。不要把 follow 失败一律收成越界。

文件工具的调用点不用改，它们已经走 ResolveWithinWorkspace。

二、cmd.Dir 不是沙箱

bash 设了 cmd.Dir = workDir，只决定起始目录。cat /etc/passwd 和 cd .. 仍然能跑。

再加一道启发式：CommandEscapesWorkspace 看命令文本，不解析 shell。

1
2
3
4

strings.Fields 切 token
绝对路径          → 拒
任一路径段是 ..   → 拒
cd 无参数 / 绝对路径 / ..  → 拒

foo/bar、cat a.go、go test ./... 放行。./... 里没有名为 .. 的路径段。

判定放在 internal/sandbox，和破坏性命令同一层。Policy 只做映射：破坏性 或 逃逸都是 PolicyDeny，不要问用户「要不要允许 cat /etc/passwd」。Execute 在 CommandContext 之前再拒一次，换掉 Policy 也执行不了。

对外文案统一成「命令试图访问工作区外的路径」。sandbox 回答出没出界，不按绝对路径 / .. / cd 分三种给用户。

这不是 OS 隔离。cat $(echo /etc/passwd)、加引号的绝对路径，Fields 拆不开。v1 只挡明文。

三、Grant 要能回看批了什么

匹配键仍然是：

1

SessionID + WorkDir + ToolName + ArgumentDigest

审计字段不进钥匙。Has 只问「这条授权在不在」，不按 RequestID 查找。

AllowSession 落盘时补上：

1
2
3
4
5

Grant{
    RequestID:  request.ID,
    Decision:   decision,
    ApprovedAt: time.Now(),
}

FileGrantStore 整份 Grant 序列化进 grants.json，重新加载后这三项还在。测试里用第二次 NewFileGrantStore 读回，确认不是只活在内存里。

还没记的是「谁批的」。AllowOnce / Deny 也不落盘，只有会话级允许会留下记录。完整审计日志是下一档，不是改匹配键。

四、测试要证明什么

符号链接：

1. 指向区内文件的 link 解析成功，返回词法路径
2. 指向区外文件的 link 失败，文案是超出工作区
3. 父目录是区外 link、目标文件还不存在，同样失败
4. a → b → a 的环报解析符号链接失败，不报越界

bash：

1. go test ./...、ls -la、cat a.go 通过
2. cat /etc/passwd、cd ..、cd /tmp、ls ../../ 失败，文案含「工作区外」
3. Policy / Gate 对逃逸命令直接 Deny，不叫 Handler
4. BashTool.Execute 在真正 bash -c 之前就返回错误

Grant 审计：落盘后再 New，RequestID、Decision、ApprovedAt 还在。

五、阶段八收到哪里

路线图里的最小权限，现在是：

1
2
3
4
5
6
7
8
9

Grant 认工作区和参数摘要
    ↓
文件路径：词法 + 跟随符号链接
    ↓
破坏性 bash、逃出工作区的 bash → Deny
    ↓
同一工作区一份 grants.json
    ↓
会话级授权带上请求 ID 和批准时间

还不是完整隔离：

1
2
3
4
5

bash 仍是启发式，不是 bwrap / sandbox-exec
命令替换、引号绕过挡不住
检查和使用之间改掉 symlink（TOCTOU）
硬链接没有「指向哪」可 follow
AllowOnce / Deny 没有审计记录

工作区内的 write_file 仍询问，这是产品选择。参数级风险目前覆盖的是「明显破坏、明显逃逸直接拒绝」。

总结

十九做匹配和落盘，二十补硬边界的第二刀，并让磁盘上的 Grant 能回看：

1
2
3
4
5

路径先 Rel，再 follow
    ↓
bash 文本里的绝对路径和 .. 直接拒绝
    ↓
Grant 多记 RequestID / Decision / ApprovedAt

阶段八可以收口。下一阶段是路线图里的 Provider 可靠性与成本预算：超时、429、重试，以及单次 Run 的 Token 上限。

本文对应 go-tiny-claw 四次提交：

1
2
3
4

4604fbf  feat: 将 Grant 匹配从工具名缩小到工作区与参数摘要
908c112  feat: 为文件工具增加工作区路径沙箱
db7b9c6  feat: 拒绝破坏性 bash 命令，不再询问用户
9a9c112  feat: 将会话授权持久化到工作区 Grant 文件

一、原来的 Grant 只认工具名

系列十三的 AllowSession 存的是：

1
2
3
4

g.grants.Save(ctx, Grant{
SessionID: request.SessionID,
ToolName:  request.ToolCall.Name,
})

查找同样只看这两项。Grant 里其实已经有 WorkDir，但 Gate 没填，Engine 构造 Request 时也没带工作区。

于是会出现：

1
2
3
4
5

用户允许 bash("go test")
    ↓
本会话任意 bash 都 Has == true
    ↓
bash("rm -rf /") 不再询问

最小权限的第一刀不是落盘，而是把匹配键改对。磁盘上如果还按工具名存，持久化只会把错误范围写死。

二、匹配键加上工作区和参数摘要

现在的钥匙是：

1

SessionID + WorkDir + ToolName + ArgumentDigest

参数不能直接当 map key：LLM 可能把 {"a":1,"b":2} 写成 {"b":2,"a":1}。DigestArguments 先 Unmarshal 再 Marshal（Go 会对 object 的 key 排序），然后 sha256。空参数当成 {}。非法 JSON 对原始字节做 hash，避免和合法 {} 撞上。

Gate 保存时把四元组写全：

1
2
3
4
5
6
7
8

if decision == AllowSession {
err = g.grants.Save(ctx, Grant{
SessionID:      request.SessionID,
WorkDir:        request.WorkDir,
ToolName:       request.ToolCall.Name,
ArgumentDigest: DigestArguments(request.ToolCall.Arguments),
})
}

Has 用请求现算摘要，不要先取出 Grant 再比。找不到键，说明不是同一条授权。

Engine 构造审批请求时补上 session.WorkDir。测试里如果手动 Save 过期 Grant，也必须带上 ArgumentDigest，否则测到的是「键对不上」，不是「过期删除」。

三、路径沙箱是硬边界

filepath.Join 有两个坑：

1
2

Join("/work", "../etc/passwd")  →  还没清掉 ..
Join("/work", "/etc/passwd")    →  丢掉 workDir

read_file 又是 RiskSafe，这两类请求会自动执行。审批解决不了这件事：逃逸必须在执行前被拒绝。

规则放在 internal/sandbox，不依赖 tools 或 approval：

1
2
3

sandbox
  ↑
tools / approval

ResolveWithinWorkspace 的步骤是：

1. 拒绝空路径、空工作区、绝对路径
2. 对 workDir 和 Join 结果做 Abs + Clean
3. 用 filepath.Rel 看相对路径是不是 .. 开头

不要用 strings.HasPrefix(resolved, root)：/work 会误放行 /work-evil。

read_file、write_file、edit_file 都先走这个函数，失败直接返回，不再问用户。bash 这次没接：cmd.Dir 只是起始目录，命令里仍可以 cd ..。

四、破坏性命令由 sandbox 判定，Policy 只做映射

拒绝表属于「什么命令危险」，和路径逃不逃逸是一类规则。Policy 只回答危险了怎么办。

1
2
3
4
5

sandbox.IsDestructiveCommand(command)  ← 只收 string
        ↑
DefaultPolicy 解析 bash JSON，命中则 PolicyDeny
        ↑
Gate 把 PolicyDeny 映射成 Deny，不问 Handler

匹配是启发式子串，不是完整 shell 解析。空白压扁、转小写之后查：

1

rm -rf / rm -fr / mkfs / dd of=/dev/ / shutdown / reboot / 叉弹

go test ./... 仍会询问。cmd=rm; $cmd -rf 这种绕过挡不住，以后再收。

Grant 测试里「不同参数再问」不能再用 rm -rf / 当第二条命令，否则现在会直接 Deny，测不到摘要是否收窄。

五、授权落到 .claw/grants.json

匹配键稳定之后才落盘。文件在 {workDir}/.claw/grants.json。

FileGrantStore 的 Has / Save / Revoke 和内存版同一把钥匙。写入先写 .tmp 再 Rename；落盘失败把内存里那次改动撤掉。过期条目在 Has 时删除并写回。

工厂不能每个 Runtime New 一份文件 Store：两个 Session 会互相覆盖 JSON。RuntimeFactory 按工作区懒加载一次，SessionID 仍在键里，会话之间不串授权。

单元测试里的 Engine 继续用 MemoryGrantStore。CLI / Channel 才走文件。

六、测试要证明什么

Grant 收窄：

1. 相同参数复用，Handler 只问一次
2. 不同参数再问
3. JSON 键顺序不同视为同一 Grant
4. 不同 WorkDir 不复用
5. 过期 Grant 先命中再删掉

路径沙箱：相对路径成功；..、嵌套 ..、绝对路径、空路径、空工作区失败。

命令拒绝：破坏性命令 IsDestructiveCommand == true；go test 为 false。Gate 对 rm -rf / 不调用 Handler。

文件存储：重新 NewFileGrantStore 后相同参数仍命中；不同参数不命中；过期失效；没有文件也能创建。

七、阶段八还没做完的

1
2
3
4

审计：谁批的、何时、批了哪次调用
bash 限制在工作区内（cd ..、cat /etc/passwd）
符号链接跟随后仍可能逃出工作区
拒绝表不是完整 shell 解析

路线图里的参数级风险，目前只覆盖了「明显破坏性 bash 直接拒绝」。工作区内 write_file 仍询问，这是产品选择，不是漏做。

总结

阶段八先改匹配，再加硬边界，最后才落盘：

1
2
3
4
5
6
7

Grant 认参数摘要和工作区
    ↓
文件路径必须落在工作区内
    ↓
破坏性 bash 由 sandbox 判定，Policy 映射为 Deny
    ↓
同一工作区共享一份 grants.json

授权持久化之前，如果钥匙还是工具名，磁盘上存的也会是错误范围。下一阶段可以补审计，或把 bash 也关进工作区。

工具并发上限限制的是「同时跑几个工具」。事件背压限制的是「事件管道别无限灌」。两者管的不是同一类资源。

本文对应 go-tiny-claw 两次提交：

1
2

bb746e1  feat: 为 Channel EventSink 增加有界队列背压
85904e7  feat: 将 Reporter 错误回传 Engine，关闭时等待 EventSink 写循环退出

落地之后，Channel 侧的事件出口是：

1
2
3
4
5
6
7

有界 queue（默认 64）
唯一 writer goroutine
Publish 尊重 ctx
Close 叫醒阻塞中的 Publish
conn.Close 打断正在进行的 Write
Wait 确认 loop 已退出
Reporter 错误会停掉当前 Run

一、原来的 Publish 直接写连接

改造前，路径是：

1
2
3
4
5
6
7

Engine / Reporter
    ↓
JSONEventSink.Publish
    ↓
MessageWriter.Encode
    ↓
TCP / WebSocket conn

Publish 会先看一眼 ctx，然后同步 Write：

1
2
3
4
5
6

func (s *JSONEventSink) Publish(ctx context.Context, event reporter.Event) error {
if err := ctx.Err(); err != nil {
return err
}
return s.writer.Write(event)
}

慢客户端会把 Write 堵住。更糟的是：堵住之后再按 Ctrl-C，这次 Write 不一定听 ctx，Engine 可能一直卡在某次 OnTextDelta 上。

当时 JSONReporter 还是：

1

_ = r.sink.Publish(ctx, event)

错误被丢掉。背压这一层先让 Publish 自己能阻塞、能取消、能关闭；随后再把错误从 Reporter 传回 Engine。

二、背压是什么

把中间换成有界队列：

1

Publish  ──►  queue(cap=64)  ──►  loop goroutine  ──►  Write(conn)

「满了让上游慢下来」就是背压。没有界的 channel 或无限 goroutine，只是把压力变成内存。

三、为什么不能 for range queue

第一版 writer 是：

1
2
3

for item := range s.queue {
_ = s.writer.Write(item.event)
}

range 一个 channel 会一直等到 channel 被 close。Session 关掉如果不 close(queue)，这条 goroutine 会永远挂着。

但 close(queue) 和 queue <- item 并发会发生 panic。Engine 的 Destroy 和迟到的 Publish 之间做不到绝对无缝。

所以关机信号不能靠 queue，要另开一个 done：

1
2

done：广播「Sink 已关闭」，叫醒所有 select
queue：只承载事件，Close 时不要 close 它

loop 改成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

func (s *JSONEventSink) loop() {
defer s.wg.Done()
for {
select {
case <-s.done:
return
case item := <-s.queue:
if item.ctx.Err() != nil {
continue
}
_ = s.writer.Write(item.event)
}
}
}

Close 只 close(s.done)。select 只能叫醒还在等 done / queue 的 loop。一旦已经进了 Write，done 对它就是空气。

四、Publish 必须同时听三件事

1
2
3
4
5
6
7
8

select {
case <-ctx.Done():
return ctx.Err()
case <-s.done:
return ErrEventSinkClosed
case s.queue <- item:
return nil
}

这就是「尊重 ctx」：可阻塞的等待里，取消和关闭都要能打断入队。

这里有一个 Go 的坑。Close 之后立刻 Publish，若队列还有空位：

1
2

<-s.done        就绪
s.queue <- item 也就绪

同一个 select 会随机挑一个。测试里曾经抽中入队，返回 nil，断言关闭失败。

拆成两个 select（先看 done，再阻塞）能修，但读起来绕。更直接的办法是加一个 closed 标记，先挡关闭后的调用，done 继续负责叫醒已经堵在 select 里的人：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

func (s *JSONEventSink) Publish(ctx context.Context, event reporter.Event) error {
if s.closed.Load() {
return ErrEventSinkClosed
}

select {
case <-ctx.Done():
return ctx.Err()
case <-s.done:
return ErrEventSinkClosed
case s.queue <- item:
return nil
}
}

func (s *JSONEventSink) Close() {
s.closeOnce.Do(func() {
s.closed.Store(true)
close(s.done)
})
}

两个东西不是重复：

1
2

closed：已经关闭了吗？（布尔，查一眼）
done  ：正在等待的人，请醒来（channel，能广播）

只有布尔值，堵在满队列上的 Publish 醒不过来；只有 done 放进同一个 select，关闭后的瞬时调用可能误入队。

五、Close、关连接、Wait 不能写反

Close 立刻返回，只表示「通知已发出」。Wait 返回，才表示写事件的那条 goroutine 已经 return。

因此 Close 不能在内部 Wait：Sink 不拥有连接，等 loop 时 Write 可能还堵着，自己死锁。等待是 Session 的责任，而且必须先把 Write 打断。

ChannelSession.Close 的顺序是：

1
2
3
4

Destroy Runtime     ← Cancel，Engine 停止继续生产
events.Close()      ← closed + close(done)，Publish 立刻失败
conn.Close()        ← 打断正在进行的 Write
events.Wait()       ← 确认 loop 已退出

两处对调会出问题：

1
2
3
4
5

先 Wait 再 conn.Close
    → loop 卡在 Write 上，Wait 永远回不来

先 conn.Close 再 events.Close
    → Publish 仍可能入队，再对已关闭的连接 Write，错误被丢掉

done 解决的是「别再入队 / 别再取下一条」。它解决不了「这一条已经交给内核的 Write」。打断 Write 是连接所有者的责任。

六、把 Publish 错误传回 Engine

有界队列只能让上游变慢。下游已经关掉时，还得让当前 Run 停下来，并且 Session 里的 ToolCall 仍然成对。

Reporter / StreamReporter 现在返回 error。JSONReporter 不再丢掉 Publish 的结果：

1
2
3

func (r *JSONReporter) publish(ctx context.Context, event Event) error {
return r.sink.Publish(ctx, event)
}

Engine 按阶段处理：

工具 goroutine 里用 setReportErr 只保留第一个错误。Wait 之后先看 ctx.Err()，再看 reportErr：用户取消时返回 Canceled，不会被 Sink 错误盖住。

RunSub 用同一套逻辑。它没有持久化 Session，失败时把 Observation 补进局部 contextHistory 再返回。

七、generate 返回时必须取消流式 ctx

只让 Engine 提前 return 不够。GenerateStream 那条 goroutine 可能还堵在往 events 里送。

OnTextDelta 失败时，父 ctx 不一定已经被取消——Channel 正常关闭会先 Destroy，但 Reporter 自己失败时不会。所以 generate 进入时派生一个可取消的 ctx：

1
2

ctx, cancel := context.WithCancel(ctx)
defer cancel()

任何返回路径都会取消这次流。Provider 侧的 sendStreamEvent 已经同时听 ctx.Done()，HTTP stream 也把同一个 ctx 传给 SDK。这样「Run 结束」和「读模型的 goroutine 退出」才是一件事。

八、测试要证明什么

test/channel/event_sink_test.go：

1. 队列有空位，Publish 立刻成功。
2. 用会阻塞的 io.Writer 让 loop 卡在 Write 上，填满容量为 1 的队列，第三次 Publish 在 cancel 后返回 context.Canceled。
3. Close 两次不 panic；之后 Publish 返回 ErrEventSinkClosed。
4. Write 仍阻塞时 Wait 不返回；模拟 conn.Close 让 Write 返回后，Wait 结束。

第二条说明背压：下游不消费时，上游必须能被 ctx 救出来。第四条说明关机契约：Close 叫不醒 Write，Wait 必须发生在连接被关掉之后。

test/engine/reporter_error_test.go：

1. OnMessage 失败时，已入库的 ToolCall 会补 Observation，工具不会执行。
2. OnToolCall 失败时同样跳过 Execute，并补取消 Observation。

test/engine/stream_cancel_test.go：

1. 父 ctx 取消后，流式 Provider 的 goroutine 退出。
2. 只有 Reporter 失败、父 ctx 还活着时，generate 的 defer cancel 仍能让 Provider goroutine 退出。

为了测「满」，构造函数增加了容量参数；生产路径仍走默认 64。相关测试可以在 -race 下通过。

九、阶段七收口

对照系列十的阶段七清单：

阶段八才是 Grant 持久化和参数级权限，不在本篇范围。

总结

事件出口要同时成立五条约束：

1
2
3
4
5
6
7
8
9

队列有界
    ↓
Publish 同时听 ctx 和关闭
    ↓
Close 能叫醒等待入队的人
    ↓
关连接才能打断正在进行的 Write
    ↓
Reporter 错误变成 Run 终态，且 ToolCall 仍然成对

执行侧限制并行数，输出侧限制管道深度，失败时停止当前任务而不是把错误吞掉。到这里，路线图阶段七「资源生命周期和可靠取消」可以收口；下一阶段是审批持久化与最小权限。

本文对应 go-tiny-claw 提交：

1
2

04608aa  fix: 消除终端审批在 Ctrl-C 后的 stdin 读泄漏
7ebceab  refactor: 引入 TerminalSession 对齐 Channel 装配

它补上的是路线图阶段七里被点名的缺口之一：资源生命周期与可靠取消中的「Approval 输入 Goroutine 是否泄漏」。

一、问题从哪里来

系列十三里的终端 Handler 大致是这样写的：

1
2
3
4
5
6
7
8
9
10
11
12
13

inputCh := make(chan string, 1)

go func() {
line, _ := h.reader.ReadString('\n')
inputCh <- strings.TrimSpace(line)
}()

select {
case <-ctx.Done():
return "", ctx.Err()
case input := <-inputCh:
// 解析 y / a / n
}

这段代码能工作，是因为它同时在等两件事：

1
2
3

用户输入一行
    或
Context 被取消

但 ReadString 本身不知道 Context。Ctrl-C 只会取消 runCtx，让 select 走到 ctx.Done() 并返回；后台那条 go 仍然堵在 stdin 上。

于是会出现：

1
2
3
4
5
6
7
8
9

Approve 返回 context.Canceled
    ↓
任务结束，REPL 回到下一轮
    ↓
REPL 再次 ReadString
    ↓
泄漏的审批 goroutine 也在 ReadString
    ↓
两个读者抢同一个 stdin

用户下一行输入可能被泄漏的 goroutine 吃掉，表现为「按了没反应」或输入错乱。更重要的是：每次取消都可能留下一个永远卡住的 goroutine。

系列十三已经写过这个缺口：

1
2
3

ReadString 不能直接被 Context 取消。
中断发生时，Handler 可以返回，
但后台读取 Goroutine 仍可能阻塞。

本篇就是把这句话真正落地。

二、为什么 Channel 没有这个问题

ChannelApprovalHandler 从一开始就没有在 Approve 里读输入：

1
2
3
4
5
6

select {
case <-ctx.Done():
return "", ctx.Err()
case decision := <-response:
return decision, nil
}

输入来自外部协议消息。ChannelSession 读到 MessageApprovalResponse 后再调用：

1

s.approval.Respond(message.RequestID, decision)

取消时只需要注销 pending、结束 Approve，没有不可取消的阻塞 IO 挂在 Handler 内部。

所以正确模型不是「让 ReadString 支持 cancel」，而是：

1
2
3

Approve：只等待 Decision / Context
Respond：由唯一输入所有者注入 Decision
stdin / WebSocket：只允许一个读者

Terminal 应该复用同一套语义，而不是另搞一套可读但会泄漏的实现。

三、把 TerminalApproval 改成 Approve / Respond

终端审批从 internal/approval 挪到 internal/cli。原因和 Channel 对称：

1
2
3
4
5
6
7
8

internal/approval
  └── Gate / Policy / Grant / Handler 接口

internal/cli
  └── Terminal 渠道适配：审批 UI + stdin 分流

internal/channel
  └── WebSocket / TCP 渠道适配

新的 TerminalApprovalHandler 不再持有 bufio.Reader，也不再 go ReadString：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

type TerminalApprovalHandler struct {
out io.Writer

mu       sync.Mutex
response chan approval.Decision
}

func (h *TerminalApprovalHandler) Approve(
ctx context.Context,
request approval.Request,
) (approval.Decision, error) {
response := make(chan approval.Decision, 1)

h.mu.Lock()
if h.response != nil {
h.mu.Unlock()
return "", ErrApprovalAlreadyPending
}
h.response = response
h.mu.Unlock()

defer func() {
h.mu.Lock()
h.response = nil
h.mu.Unlock()
}()

fmt.Fprintf(h.out, "\n需要确认执行工具: %s\n", request.ToolCall.Name)
fmt.Fprintf(h.out, "参数: %s\n", request.ToolCall.Arguments)
fmt.Fprint(h.out, "[y]允许本次 [a]本会话允许 [n]拒绝: ")

select {
case <-ctx.Done():
return "", ctx.Err()
case decision := <-response:
return decision, nil
}
}

Respond 只负责往唯一槽位投递决策：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

func (h *TerminalApprovalHandler) Respond(decision approval.Decision) error {
// 校验 AllowOnce / AllowSession / Deny
h.mu.Lock()
response := h.response
h.mu.Unlock()

if response == nil {
return ErrApprovalRequestNotFound
}

select {
case response <- decision:
return nil
default:
return ErrApprovalAlreadyResolved
}
}

这里用单个 response 而不是 map[requestID]chan，是因为终端交互本身是串行的：同一时刻用户只能回答一个问题，Gate 也会串行 Check。Channel 继续用 map，是因为协议消息自带 RequestID，按 ID 寻址更自然。

清理责任仍然在 Approve 的 defer 上：无论成功还是取消，离开 Approve 都会清空 pending。Respond 不负责 delete。

四、REPL 必须成为 stdin 的唯一读者

若只改 Handler，却仍然在审批时另起 ReadString，泄漏只是换了个地方。

因此 REPL 要同时承担两件事：

1. 空闲时读下一句 Prompt
2. 审批等待时读 y/a/n 并调用 Respond

这要求主循环不能在 task.Wait() 上堵死。旧写法是：

1
2
3
4
5

Start
  ↓
Wait          ← 主循环卡在这里
  ↓
回到 claw>

任务运行期间没人读 stdin，所以旧 Handler 才不得不自己读。新写法对齐 ChannelSession：

1
2
3
4
5

Start 后立刻返回
  ↓
go { Wait; 清理 active; 打印终态 }
  ↓
主循环继续 ReadString

分流逻辑变成：

1
2
3
4

ReadString
  ├── HasPending()      → Respond(y/a/n)
  ├── 有 active Task    → 提示任务进行中
  └── 空闲              → /help、/clear 或 Start 新任务

对应代码骨架：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

if r.approval != nil && r.approval.HasPending() {
decision, ok := parseApprovalDecision(prompt)
if !ok {
fmt.Fprintln(r.out, "请输入 y / a / n")
continue
}
_ = r.approval.Respond(decision)
continue
}

if !r.isIdle() {
fmt.Fprintln(r.out, "当前任务正在执行，请等待任务完成。")
continue
}

并且只在空闲时打印提示符：

1
2
3

if r.isIdle() {
fmt.Fprint(r.out, "\nclaw>")
}

这样审批提示前不会再多打一个 claw>。

Ctrl-C 之后的语义变为：

1
2
3
4
5
6
7
8
9

ctx 取消
  ↓
Approve 从 select 返回
  ↓
defer 清空 pending
  ↓
没有残留 ReadString goroutine
  ↓
REPL 仍是唯一 stdin 读者

五、为什么 main 里曾经要传两次 Handler

Gate 需要的是：

1

Approve(ctx, request) (Decision, error)

REPL 需要的是：

1
2

HasPending() bool
Respond(decision) error

同一个对象，两个角色。Channel 看起来「只传一次」，是因为 ChannelSession 在构造函数内部完成了两次注入：

1
2
3
4
5
6
7
8
9

channelApproval, _ := NewChannelApprovalHandler(eventSink)

bundle, _ := manager.Create(id, runtimepkg.RuntimeOptions{
ApprovalHandler: channelApproval, // 给 Gate
})

return &ChannelSession{
approval: channelApproval, // 留给 Session 自己 Respond
}

Terminal 之前没有对等的 Session，装配落在 main，所以会出现：

1
2

ApprovalHandler: approvalHandler,          // Create
NewREPL(..., approvalHandler)              // REPL

这不是创建了两个 Handler，而是装配归属放错了层。

六、引入 TerminalSession

为了和 Channel 对齐，新增 internal/cli/terminal_session.go：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

func NewTerminalSession(
id string,
manager *runtimepkg.Manager,
reader *bufio.Reader,
out io.Writer,
) (*TerminalSession, error) {
approvalHandler, err := NewTerminalApprovalHandler(out)
if err != nil {
return nil, err
}

runtimeBundle, err := manager.Create(id, runtimepkg.RuntimeOptions{
ApprovalHandler: approvalHandler,
Reporter:        reporter.NewTerminalReporter(out),
})
if err != nil {
return nil, err
}

repl := NewREPL(
reader,
out,
runtimeBundle.Runtime,
runtimeBundle.Reporter,
approvalHandler,
)

return &TerminalSession{
id:       id,
manager:  manager,
runtime:  runtimeBundle.Runtime,
reporter: runtimeBundle.Reporter,
approval: approvalHandler,
repl:     repl,
}, nil
}

cmd/claw/main.go 收成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

session, err := cli.NewTerminalSession(
"terminal_default",
manager,
bufio.NewReader(os.Stdin),
os.Stdout,
)
defer session.Close()

go func() {
for range signals {
session.Interrupt()
}
}()

session.Run(context.Background())

当前 Run / Interrupt 先委托给已有 REPL，目标不是立刻消掉 REPL，而是先把装配边界摆正：

1
2

claw_server  → ChannelSession
claw         → TerminalSession

Close 使用 sync.Once，避免重复 Destroy：

1
2
3
4
5
6
7
8
9
10
11

func (s *TerminalSession) Close() error {
s.closeOnce.Do(func() {
err := s.manager.Destroy(s.id)
if err != nil && !errors.Is(err, runtimepkg.ErrRuntimeNotFound) {
s.closeErr = err
return
}
s.closeErr = nil
})
return s.closeErr
}

若将来在 Create 成功之后还有可能失败的步骤，失败路径应立刻 manager.Destroy(id)，防止半成品 Runtime 留在 Manager 里。

七、这一步完成后的分层

Terminal 渠道现在可以画成：

1
2
3
4
5
6
7
8
9
10

stdin / stdout / Ctrl-C
        ↓
TerminalSession
        ├── TerminalApprovalHandler   Approve / Respond
        ├── TerminalReporter
        └── REPL                      唯一 ReadString
                ↓
Runtime / Task
                ↓
AgentEngine / Approval Gate

和 Channel 对比：

1
2
3
4
5
6
7
8
9
10

WebSocket / TCP
        ↓
ChannelSession
        ├── ChannelApprovalHandler    Approve / Respond
        ├── JSONReporter
        └── MessageReader             唯一读连接
                ↓
Runtime / Task
                ↓
AgentEngine / Approval Gate

两边差异只在输入源和展示方式；审批等待模型已经统一。

八、还没做完的部分

这次修掉的是「取消后 stdin 读泄漏」和「Terminal 装配不对齐」。阶段七到生产级还有几件事：

1
2
3
4
5
6

取消后半截结果是否误写 Session
工具并发上限和事件 Channel 背压
Provider / bash 子进程退出与泄漏测试
Race Detector 覆盖审批取消路径
任务结束后 claw> 提示符可能晚一拍刷新
/exit 时是否应先取消 active Task

再往后才是路线图阶段八及以后：

1
2
3
4
5

Grant 持久化与参数级最小权限
Provider 超时、重试和预算
Session 持久化与任务恢复
MCP / A2A
评测、性能和部署治理

总结

终端审批泄漏的本质，不是「少写了一个 cancel」，而是把不可取消的 stdin 读塞进了本应只等待 Decision 的 Approve。

修复路径也很明确：

1
2
3
4
5
6
7

复用 Channel 的 Approve / Respond
    ↓
REPL 独占 stdin 并负责分流
    ↓
任务异步 Wait，主循环永不因审批停读
    ↓
TerminalSession 收拢装配，与 ChannelSession 对称

到这里，Terminal 和 Channel 在审批与会话边界上已经站在同一套模型上。下一步可以继续补阶段七的其余可靠性项，再进入权限持久化和 Session 恢复。

但系列十五结尾还留下了几个关键问题：

1
2
3
4

TCP 客户端和 Server 之间到底传什么格式？
浏览器为什么不能直接连接 TCP Server？
流式文本、工具调用和审批请求如何传到外部渠道？
一个前端页面如何同时管理多个 Session？

这一篇继续实现这些能力。本文对应当前 go-tiny-claw 中已经落地的连接层：

1
2
3
4
5
6

JSON Line Protocol
Structured Event
JSON Reporter
ChannelSession
WebSocket Server
React Multi-Session Console

一、从 TCP 多连接到浏览器控制台

系列十五中的 TCP 连接可以这样使用：

1
2
3
4
5
6
7
8
9

TCP Client
    ↓
TCPServer
    ↓
ChannelSession
    ↓
Runtime
    ↓
AgentEngine

TCP 是一个字节流。Server 能够读取到字节，但它并不知道这些字节代表什么业务动作。

如果客户端直接发送：

1

帮我读取 README

Server 无法可靠判断这是一条 Prompt，还是一次中断、审批响应或者关闭请求。

因此需要在传输层之上定义应用协议：

1
2
3
4
5

TCP / WebSocket
    ↓
Message Protocol
    ↓
ChannelSession

同时，浏览器还有一个限制：浏览器 JavaScript 不能直接创建原始 TCP 连接。浏览器可以使用 HTTP、WebSocket 等标准 Web 协议，但不能像 Go 客户端一样连接 net.Conn。

所以最终的连接层变成：

1
2
3

TCP Client ─────── TCP :8080 ───────┐
                                    ├── ChannelSession ─── Runtime
React Browser ─ WebSocket :8081 ───┘

TCP 和 WebSocket 使用不同的传输适配器，但进入后面的 ChannelSession、Runtime 和 AgentEngine。

二、先定义连接协议

协议实现位于：

1

internal/channel/protocol.go

当前协议采用 JSON Line 形式。每条消息是一个 JSON 对象，并以换行结束。

1. 消息类型

1
2
3
4
5
6
7
8
9
10

type MessageType string

const (
MessagePrompt           MessageType = "prompt"
MessageInterrupt        MessageType = "interrupt"
MessageClose            MessageType = "close"
MessagePing             MessageType = "ping"
MessagePong             MessageType = "pong"
MessageApprovalResponse MessageType = "approval_response"
)

客户端发送 Prompt：

1

{"type":"prompt","content":"请读取 README"}

客户端请求中断：

1

{"type":"interrupt"}

客户端响应审批：

1

{"type":"approval_response","request_id":"abc123","decision":"allow_once"}

这里的 type 是连接层协议类型。它和 Reporter 发出的 Agent 事件类型不是同一个概念。

1
2
3
4
5

MessageType
  表示客户端要求 Server 做什么

EventType
  表示 Agent 当前发生了什么

2. Message 结构

1
2
3
4
5
6

type Message struct {
Type      MessageType `json:"type"`
Content   string      `json:"content,omitempty"`
RequestID string      `json:"request_id,omitempty"`
Decision  string      `json:"decision,omitempty"`
}

目前的消息结构仍然比较小，但已经覆盖了连续对话所需的控制面：

1
2
3

Content   Prompt 内容
RequestID 审批请求 ID
Decision  审批决策

未来如果需要协议版本、客户端 ID、任务 ID 和请求追踪，可以继续扩展这个结构，或者引入统一的 Envelope。

3. MessageReader 为什么接收 io.Reader

MessageReader 的构造函数不再要求调用方传入 *bufio.Reader：

1
2
3
4
5
6
7

func NewMessageReader(input io.Reader) (*MessageReader, error) {
if input == nil {
return nil, errors.New("消息读取器输入不能为空")
}

return &MessageReader{reader: bufio.NewReader(input)}, nil
}

这个边界很重要：

1
2

外部依赖：io.Reader
内部实现：bufio.Reader

因此以下输入都可以被协议层使用：

1
2
3
4

net.Conn
WebSocket Adapter
bytes.Buffer
测试输入

调用方不需要知道协议层是否使用缓冲。

4. Reader 负责协议校验

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

func (r *MessageReader) Read() (Message, error) {
line, err := r.reader.ReadBytes('\n')

if len(line) > MaxMessageSize {
return Message{}, errors.New("消息长度超过限制")
}

if err != nil {
return Message{}, err
}

line = bytes.TrimSpace(line)

var message Message
if err := json.Unmarshal(line, &message); err != nil {
return Message{}, errors.New("消息格式错误")
}

switch message.Type {
case MessagePrompt:
if message.Content == "" {
return Message{}, errors.New("提示不能为空")
}
case MessageApprovalResponse:
if message.RequestID == "" {
return Message{}, errors.New("审批响应缺少请求 ID")
}
if message.Decision == "" {
return Message{}, errors.New("审批响应缺少决策")
}
default:
return Message{}, errors.New("不支持的消息类型")
}

return message, nil
}

协议层至少应该负责：

1
2
3
4

限制单条消息大小
校验 JSON
校验消息类型
校验必需字段

它不应该负责启动 Agent 或执行工具。协议层只回答“收到了一条什么消息”。

三、MessageWriter 解决并发输出

Server 中一个 Session 可能同时产生多种输出：

1
2
3
4
5
6

模型文本 Delta
工具调用事件
工具结果事件
审批请求
任务完成事件
Ping 响应

这些事件可能来自不同 Goroutine。因此不能让多个 Goroutine 直接对同一个连接调用 json.Encoder。

当前 Writer 使用一个互斥锁：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

type MessageWriter struct {
encoder *json.Encoder
mu      sync.Mutex
}

func NewMessageWriter(output io.Writer) (*MessageWriter, error) {
if output == nil {
return nil, errors.New("消息写入器输出不能为空")
}

return &MessageWriter{encoder: json.NewEncoder(output)}, nil
}

func (w *MessageWriter) Write(value any) error {
w.mu.Lock()
defer w.mu.Unlock()

return w.encoder.Encode(value)
}

这里有两个设计点。

第一，Writer 接收 io.Writer，不和 TCP、WebSocket 绑定。

第二，Write 接收 any，因为它既可能写入连接控制消息：

1

Message{Type: MessagePong}

也可能写入 Agent 事件：

1

reporter.Event{Type: reporter.EventToolCall}

它的真实职责不是“只写 Message”，而是“串行写入 JSON 对象”。

同一个连接内，Writer 保证 JSON 字节不会交错；不同连接之间则因为底层连接不同，天然隔离。
同一个连接内，Writer 保证 JSON 字节不会交错；不同连接之间则因为底层连接不同，天然隔离。

四、从 Reporter 回调到结构化事件

AgentEngine 只依赖 Reporter 接口：

1
2

AgentEngine
    └── reporter.Reporter

它不会直接调用 fmt.Printf，也不会直接写 TCP。

1. Event 定义

文件：

1

internal/reporter/event.go

当前事件类型包括：

1
2
3
4
5
6
7
8
9
10
11
12
13

const (
EventThinking         EventType = "thinking"
EventTextDelta       EventType = "text_delta"
EventTextCompleted   EventType = "text_completed"
EventToolCall        EventType = "tool_call"
EventToolResult      EventType = "tool_result"
EventTaskCompleted   EventType = "task_completed"
EventTaskCanceled    EventType = "task_canceled"
EventTaskFailed      EventType = "task_failed"
EventError           EventType = "error"
EventPong            EventType = "pong"
EventApprovalRequest EventType = "approval_request"
)

事件结构：

1
2
3
4
5
6
7
8
9
10
11
12

type Event struct {
Type      EventType `json:"type"`
Content   string    `json:"content,omitempty"`
ToolName  string    `json:"tool_name,omitempty"`
Result    string    `json:"result,omitempty"`
RequestID string    `json:"request_id,omitempty"`
Decision  string    `json:"decision,omitempty"`
Risk      string    `json:"risk,omitempty"`
Reason    string    `json:"reason,omitempty"`
IsError   bool      `json:"is_error,omitempty"`
Error     string    `json:"error,omitempty"`
}

2. JSONReporter

文件：

1

internal/reporter/json_reporter.go

JSONReporter 把 Engine 的回调转换成 Event：

1
2
3
4
5
6
7
8
9
10
11

func (r *JSONReporter) OnToolCall(
ctx context.Context,
toolName string,
args string,
) {
r.publish(ctx, Event{
Type:     EventToolCall,
ToolName: toolName,
Content:  args,
})
}

最终发送给浏览器的是：

1
2
3
4
5

{
  "type":"tool_call",
  "tool_name":"write_file",
  "content":"{...}"
}

同一个 Engine 可以继续使用 TerminalReporter：

1
2

CLI → TerminalReporter → stdout
WebSocket → JSONReporter → EventSink → MessageWriter

Reporter 的抽象让输出渠道可以替换，而不需要修改 Agent Loop。

3. EventSink

文件：

1

internal/channel/event_sink.go

1
2
3

type EventSink interface {
Publish(ctx context.Context, event Event) error
}

JSONReporter 只依赖 EventSink：

1
2
3
4
5
6
7

JSONReporter
    ↓
EventSink
    ↓
MessageWriter
    ↓
TCP / WebSocket

这样 Reporter 不需要知道底层是字节流还是 WebSocket Frame。

五、ChannelSession：连接和 Runtime 的绑定层

文件：

1

internal/channel/channel_session.go

一个 ChannelSession 的结构是：

1
2
3
4
5
6

外部连接
  ├── MessageReader
  ├── MessageWriter
  ├── JSONReporter
  ├── ChannelApprovalHandler
  └── Runtime

构造时，所有输出共享同一个 MessageWriter：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

writer, err := NewMessageWriter(conn)
if err != nil {
return nil, err
}

eventSink, err := NewJSONEventSinkWithWriter(writer)
if err != nil {
return nil, err
}

bundle, err := manager.Create(id, runtimepkg.RuntimeOptions{
ApprovalHandler: channelApproval,
Reporter:        reporter.NewJSONReporter(eventSink),
})

这里不能分别创建两个 Writer：

1
2
3
4
5

错误做法：
Reporter → Writer A
Ping     → Writer B
             ↓
        同一个连接

两个 Writer 各自持有锁，无法保护彼此，可能导致输出交错。

正确做法是：

1
2
3

Reporter ─┐
          ├── 同一个 MessageWriter
Ping ─────┘

1. 消息循环

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

func (s *ChannelSession) Run(ctx context.Context) error {
for {
message, err := s.reader.Read()
if err != nil {
return err
}

switch message.Type {
case MessagePrompt:
if err := s.startTask(ctx, message.Content); err != nil {
s.publishError(ctx, err)
}
case MessageInterrupt:
s.runtime.Cancel()
case MessageApprovalResponse:
decision := approval.Decision(message.Decision)
if err := s.approval.Respond(message.RequestID, decision); err != nil {
s.publishError(ctx, err)
}
case MessagePing:
if err := s.writer.Write(Message{Type: MessagePong}); err != nil {
return err
}
case MessageClose:
return nil
}
}
}

2. Prompt 必须异步启动

如果 MessagePrompt 直接同步等待：

1
2

task, _ := s.runtime.Start(ctx, prompt, s.reporter)
task.Wait()

那么消息循环会被阻塞。在 Agent 运行期间，下面这些消息都无法处理：

1
2
3
4

interrupt
approval_response
ping
close

当前实现启动 Task 后立即返回消息循环：

1
2
3
4
5
6
7
8
9

task, err := s.runtime.Start(ctx, prompt, s.reporter)
if err != nil {
return err
}

go func() {
err := task.Wait()
// 发布 task_completed、task_canceled 或 task_failed
}()

这就是 Server 能够在 Agent 执行期间响应中断和审批的原因。
这就是 Server 能够在 Agent 执行期间响应中断和审批的原因。

六、通道审批如何工作

终端审批可以直接读取 stdin，但 TCP 或 WebSocket 审批不能再启动一个 Reader 去读取同一连接。

否则会变成：

1
2
3

ChannelSession.Reader ──┐
                        ├── 同一个连接
ApprovalHandler.Reader ─┘

两个 Reader 会竞争输入，导致 Prompt 或审批响应被错误消费。

当前 ChannelApprovalHandler 使用一个 pending Map：

1
2
3
4
5
6

type ChannelApprovalHandler struct {
sink reporter.EventSink

mu      sync.Mutex
pending map[string]chan approval.Decision
}

审批开始时：

1
2
3
4
5
6
7
8
9

Engine
  ↓
ApprovalGate.Check
  ↓
ChannelApprovalHandler.Approve
  ↓
发送 approval_request 事件
  ↓
等待 pending[requestID]

前端收到：

1
2
3
4
5
6

{
  "type":"approval_request",
  "request_id":"request-1",
  "tool_name":"write_file",
  "risk":"mutating"
}

点击允许一次后发送：

1
2
3
4
5

{
  "type":"approval_response",
  "request_id":"request-1",
  "decision":"allow_once"
}

ChannelSession 的唯一输入循环收到响应后，调用：

1

s.approval.Respond(message.RequestID, decision)

pending Channel 被唤醒，ApprovalGate 才会把工具调用交给 Engine 后续执行。

审批响应和 Prompt 使用同一个输入循环，这是多渠道审批能够正确工作的关键。

七、为什么需要 WebSocket Adapter

浏览器使用 WebSocket Frame，而当前 MessageReader 使用 JSON Line：

1
2

MessageReader 期待：{"type":"ping"}\n
WebSocket 实际：一个 Text Frame

因此不能直接把 *websocket.Conn 传给 MessageReader。需要一个适配器，把 Frame 转换成 Reader/Writer 认识的字节流。

文件：

1

internal/server/websocket_conn.go

读取时，适配器从下一条 WebSocket 消息读取内容，并补充换行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

func (c *websocketConn) Read(p []byte) (int, error) {
for c.readOffset >= len(c.readBuffer) {
messageType, reader, err := c.conn.NextReader()
if err != nil {
return 0, err
}

if messageType != websocket.TextMessage && messageType != websocket.BinaryMessage {
return 0, errors.New("只支持文本或二进制消息")
}

message, err := io.ReadAll(reader)
if err != nil {
return 0, err
}

c.readBuffer = append(message[:0:0], message...)
c.readBuffer = append(c.readBuffer, '\n')
c.readOffset = 0
}

count := copy(p, c.readBuffer[c.readOffset:])
c.readOffset += count
return count, nil
}

写入时，适配器把一条 JSON Line 转换成一个 Text Frame：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

func (c *websocketConn) Write(p []byte) (int, error) {
c.writeMu.Lock()
defer c.writeMu.Unlock()

payload := bytes.TrimSpace(p)
if len(payload) == 0 {
return len(p), nil
}

if err := c.conn.WriteMessage(websocket.TextMessage, payload); err != nil {
return 0, err
}

return len(p), nil
}

适配完成后，ChannelSession 不需要知道自己面对的是 TCP 还是 WebSocket：

1
2
3
4
5

TCP Conn ────────────────┐
                         ├── io.ReadWriteCloser
WebSocket Stream Adapter ┘
                         ↓
                   ChannelSession

八、WebSocket Server 如何承载多个 Session

文件：

1

internal/server/websocket_server.go

TCP Server 和 WebSocket Server 的职责类似：

1
2
3
4
5
6
7

监听连接
生成 Session ID
创建 ChannelSession
注册连接
运行消息循环
连接结束后销毁 Runtime
服务关闭时清理所有连接

WebSocket Session ID 使用独立前缀：

1
2

ws-channel-session-1
ws-channel-session-2

TCP 使用：

1
2

tcp-channel-session-1
tcp-channel-session-2

两个 Server 共享同一个 RuntimeManager，但每个连接仍然拥有独立 Runtime：

1
2
3
4
5

RuntimeManager
  ├── tcp-channel-session-1 → Runtime A
  ├── tcp-channel-session-2 → Runtime B
  ├── ws-channel-session-1  → Runtime C
  └── ws-channel-session-2  → Runtime D

启动时，当前 Server 使用两个端口：

1
2

TCP       :8080
WebSocket :8081/ws

这里没有强行把 TCP 和 WebSocket 复用到同一个端口，因为二者的连接握手不同。生产环境可以使用反向代理统一域名，也可以使用连接复用器，但学习阶段使用两个端口更清晰。

九、前端多 Session 控制台

前端目录：

1

web-console

技术栈：

1
2
3
4

Vite
React
TypeScript
WebSocket

1. 一个 Session 一条 WebSocket

前端维护一个 Socket Map：

1

const sockets = useRef<Record<string, WebSocket>>({})

创建 Session 时：

1
2
3
4
5
6
7
8
9
10
11
12

const id = `session-${sequence.current++}`

setSessions((current) => [...current, {
  id,
  status: 'connecting',
  items: [],
  draft: '',
  createdAt: Date.now(),
}])

setActiveID(id)
window.setTimeout(() => connectSession(id), 0)

每个连接的消息事件都带着自己的 Session ID 回到状态更新函数：

1
2
3

socket.onmessage = (message) => {
  handleEvent(id, JSON.parse(message.data))
}

因此连接 A 的事件只会更新 Session A 的消息列表。

2. 流式文本聚合

Server 会连续发送：

1
2
3

{"type":"text_delta","content":"第一段"}
{"type":"text_delta","content":"第二段"}
{"type":"text_completed"}

前端在 Session 内记录当前的 streamItemId：

1
2
3
4
5
6
7
8

if (session.streamItemId) {
  return {
    ...session,
    items: session.items.map((item) => item.id === session.streamItemId
      ? { ...item, content: item.content + (event.content ?? '') }
      : item),
  }
}

这样每个 Delta 都会追加到当前 Agent 消息，而不是生成很多气泡。

3. 审批按钮

收到 approval_request 后，前端生成审批卡片：

1
2
3
4

需要审批 · write_file
risk: mutating

[允许一次] [会话允许] [拒绝]

按钮最终发送：

1
2
3
4
5

socket.send(JSON.stringify({
  type: 'approval_response',
  request_id: requestID,
  decision,
}))

前端不直接执行工具，也不决定工具权限。它只是把用户选择传回 Server，真正的 Policy、GrantStore 和 Gate 仍然在 Runtime 内部。

4. 固定底部输入框

连续对话的输入框不能随着消息增长被推到页面之外。这里不是简单地给输入框设置 position: fixed，而是让工作区成为一个高度受控的 Flex 容器：消息区滚动，输入区不参与滚动。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

html,
#root {
  height: 100%;
}

.workspace {
  display: flex;
  flex: 1;
  flex-direction: column;
  min-height: 0;
  height: 100vh;
  overflow: hidden;
}

.conversation {
  flex: 1 1 auto;
  min-height: 0;
  overflow-x: hidden;
  overflow-y: auto;
}

.composer-wrap {
  flex: 0 0 auto;
}

min-height: 0 很重要。Flex 子元素默认可能按照内容的最小高度撑开父容器，如果省略它，消息列表会把整个页面撑长，输入框仍然会被推走。

十、一次请求的完整时序

把各层连起来后，一条用户消息的生命周期如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

React Session A
  -> WebSocket Text Frame
  -> WebSocketServer
  -> websocketConn.Read
  -> MessageReader
  -> ChannelSession.handleMessage
  -> Runtime.Start
  -> Task goroutine
  -> AgentEngine.Run
  -> JSONReporter.OnTextDelta
  -> EventSink
  -> MessageWriter
  -> WebSocket Text Frame
  -> task_completed