[docs] Deep-dive: claude-agent-sdk vs codex-sdk adapter comparison

[s2agi]

背景

anet 现在内置 3 个 runtime：

• claude-agent-sdk — Anthropic 官方 @anthropic-ai/claude-agent-sdk
• codex-sdk — OpenAI 官方 @openai/codex-sdk
• claude-code-cli — spawn 本机 claude 二进制（不属于 SDK 范畴）

前两个 SDK 在 anet 里的接入语义、能力边界、session 处理、tool 注册、streaming、token 计费、错误处理等没有专门系统化对比。docs-site/docs/guide/runtimes.md 给的是 user-facing how-to，对"想自己接新 SDK"或"想理解 anet 怎么 wrap SDK"的 contributor 不够深。

目标

通信SDK马 出一份 SDK adapter 深度对比，结论落 docs。

调研维度（建议）

维度	claude-agent-sdk	codex-sdk
package / 版本
API entry（query / thread / etc.）
Session 语义（id 来源 / 持久化 / resume 接口）
Tool 注册（MCP / 内置）
Streaming（SSE / async iterator / Promise）
Token 计费 / 预算（--max-budget 谁实现）
错误处理 + 重试
多 turn 行为 + history 限制
ANTHROPIC_BASE_URL / 等价机制（路由到 MiniMax / DeepSeek / Codex provider）
settingSources / 项目隔离
breaking change cadence + 历史
anet wrapper 关键代码位置	agent-node/src/cli.ts:546 区域	agent-node/src/cli.ts:673 区域

交付物

• 新文件 docs-site/docs/guide/sdk-deep-dive.md + EN 镜像 docs-site/docs/en/guide/sdk-deep-dive.md
• 内容：对比表 + 各 SDK 接入注意事项 + anet wrapper 怎么收敛差异 + 想加新 runtime（gemini-cli / qwen-code 等）应该怎么照葫芦画瓢
• .vitepress/config.ts ZH+EN sidebar 加链接到新文件
• docs-site/docs/guide/runtimes.md 末尾加"想深入？→ SDK Deep-dive"指引

不要做

• 不改 cli.ts / agent-node 源码（纯文档 + 调研）
• 不发新 npm 版本
• 不动 hub / dashboard

流程

• 按 #15 Phase 0 PR pipeline 走 worktree + PR
• worktree 路径：~/anet-work/sdk-deep-dive/
• 分支：docs/sdk-deep-dive
• PR description 用新 template，Closes # 这个 issue

验收

• 文档构建 npm run build 通过无 dead link
• ZH + EN 内容齐
• sidebar 能跳到新文档
• 对比表至少覆盖上方"调研维度"表里列的项

[s2agi]

🔬 Round 1 — SDK 遥测面覆盖率调研（telemetry coverage gap）

/loop 触发的研究滚动更新。本轮聚焦：anet 当前对两个 SDK 流式事件的消费率 + 给未来 loop/goal/日志 功能留下的接入面。不动业务逻辑，只出方案。

发现 1：claude-agent-sdk 暴露 24 种 SDKMessage，anet 当前只消费 2 种

SDKMessage union（sdk.d.ts L2467）覆盖 24 个变体，cli.ts:546-560 的 processWithClaude 主循环只对其中 2 种分支：

类型	当前 anet 处理	含信号	未来用途
SDKSystemMessage{subtype:init}	✅ 拿 session_id	session_id, model	session 写回
SDKResultMessage	✅ 拿 cost/usage/turns	duration_ms, total_cost_usd, num_turns, modelUsage, permission_denials, stop_reason	log/cost
SDKTaskStartedMessage	❌	task_id, tool_use_id, description, task_type, workflow_name	goal 追踪：subagent/workflow 启动事件
SDKTaskProgressMessage	❌	task_id, description, usage, last_tool_name, summary	goal 进度：实时把 "目前在做什么" 推到 dashboard
SDKTaskNotificationMessage	❌	task_id, status('completed'/'failed'/'stopped'), output_file, summary	goal 完成：subagent 终态 + 输出文件路径
SDKToolProgressMessage	❌	tool_use_id, tool_name, parent_tool_use_id, elapsed_time_seconds	日志：长跑工具耗时（Bash/WebFetch 等）
SDKToolUseSummaryMessage	❌	summary, preceding_tool_use_ids	日志：多 tool call 串成 summary（context 节省）
SDKAPIRetryMessage	❌	(重试事件)	日志：rate limit / 429 重试可见性
SDKRateLimitEvent	❌	rate_limit_info{status, resetsAt, rateLimitType, utilization, isUsingOverage}	日志：claude.ai 订阅 rate limit 提前预警（5h/7d/overage）
SDKCompactBoundaryMessage	❌	(历史压缩边界)	goal 长跑：回答 "agent 什么时候 forget 了 X" 的关键 marker
SDKStatusMessage	❌	status('compacting' | null)	日志：节点忙/闲二级状态（区分 LLM 调用 vs 历史压缩）
SDKSessionStateChangedMessage	❌	(session 状态切换)	日志：fork / resume / continue 切换事件
SDKFilesPersistedEvent	❌	(文件检查点持久化)	日志：file checkpoint 落盘（rewind 能力相关）
SDKHookStarted/Progress/ResponseMessage	❌	hook 生命周期	日志：用户自定义 hook 的执行追踪
SDKAuthStatusMessage	❌	(认证状态)	日志：API key 失效/续期事件
SDKAssistantMessage / SDKPartialAssistantMessage	❌	message blocks / stream events	日志：分块 assistant 输出（dashboard 实时流）
SDKLocalCommandOutputMessage	❌	local 斜杠命令输出	日志：/cost /voice 等命令产物
SDKPromptSuggestionMessage	❌	下一个 prompt 建议	UX：预测下一步
SDKElicitationCompleteMessage	❌	MCP elicitation 完成	日志：MCP 表单类交互

结论：claude-agent-sdk 暴露面是 24 种，anet 消费率 8.3%（2/24）。其余 22 种里，至少 9 种（标红任务/工具/速率/压缩相关）是 anet 未来 loop/goal/日志 功能的天然信号源。

发现 2：claude-agent-sdk 暴露 27 种 HookEvent，anet 只挂了 1 个（PreToolUse 只打 log）

HookEvent union（sdk.d.ts L661）：

PreToolUse, PostToolUse, PostToolUseFailure, Notification,
UserPromptSubmit, SessionStart, SessionEnd,
Stop, StopFailure, SubagentStart, SubagentStop,
PreCompact, PostCompact,
PermissionRequest, PermissionDenied, Setup,
TeammateIdle, TaskCreated, TaskCompleted,
Elicitation, ElicitationResult, ConfigChange,
WorktreeCreate, WorktreeRemove,
InstructionsLoaded, CwdChanged, FileChanged

cli.ts:532-537 仅注册 PreToolUse 一条 hook，作用是把 tool_name(args) 写日志。剩下 26 个 event 类型全部未用。其中对 anet 未来功能高价值的：

• PostToolUse / PostToolUseFailure — tool 执行耗时 + 成功率统计（dashboard 节点健康面板的天然数据源）
• PreCompact / PostCompact — 历史压缩前后的 context 快照（对 "loop 模式下 agent 失忆" 的诊断关键）
• TaskCreated / TaskCompleted — 子任务派单/回收的端到端 hook（commhub 派单链路的本地侧镜像）
• Stop / StopFailure — turn 结束/异常的 hook（结合 SDKResultMessage 可做 "为什么停" 的归因）
• RateLimitEvent 上次提到，但作为 hook 还可主动节流而非被动观测
• SubagentStart / SubagentStop — claude-agent-sdk 内部 subagent 切换（agents 字段）的边界

发现 3：codex-sdk ThreadEvent 7 种 item type，anet 当前结构化消费 1 种

processWithCodex（cli.ts:651-669）：

ThreadEvent.item.type	当前 anet	信号	未来用途
agent_message	✅ 当 finalResponse	text	reply 内容
command_execution	🟡 debug log only	command, aggregated_output, exit_code, status	日志：跑过哪些 shell + exit code 统计
reasoning	🟡 debug log only	text	日志：推理链可选记录（隐私敏感）
mcp_tool_call	🟡 debug log only	server, tool, arguments, result, error, status	日志：MCP 工具调用图谱
file_change	❌	changes[{path, kind}], status	日志：单 turn 修改的文件列表（diff 友好）
web_search	❌	query	日志：搜索关键词审计
todo_list	❌	items[{text, completed}]	goal：Codex 自己维护的 to-do list — anet 可直接镜像到 dashboard 当 "任务计划"
error	❌（fatal 走 catch 分支）	message	日志：非 fatal 错误（continue stream 用）

额外结构化事件：

• thread.started → 拿 thread_id（anet 用了，但只在结束后写回）
• turn.completed.usage ✅ 用了，但没有 cost
• turn.failed.error{message} — anet 当前只 catch error，没有结构化 surfaced 给上游

对未来 anet feature 的方案建议（不实施，仅出案）

A. anet 节点遥测层 v1（agent-node 侧）

目标：把两个 SDK 的事件流统一抽象成 anet NodeEvent schema，落到 .anet/nodes/<alias>/events.jsonl，并通过 commhub 选择性推到 dashboard。

// 设计草案 — agent-node/src/events.ts（新文件）
type NodeEvent =
  | { kind: 'session.init', session_id: string, model: string, runtime: 'claude' | 'codex' }
  | { kind: 'turn.start', task_id?: string, prompt_preview: string }
  | { kind: 'tool.start', tool_use_id: string, tool_name: string, args_preview: string }
  | { kind: 'tool.end',   tool_use_id: string, duration_ms: number, ok: boolean, exit_code?: number }
  | { kind: 'todo.update', items: { text: string, completed: boolean }[] }   // codex todo_list
  | { kind: 'rate_limit', status: 'allowed_warning' | 'rejected', resets_at?: number }
  | { kind: 'compact', subtype: 'pre' | 'post', token_count_before?: number, token_count_after?: number }
  | { kind: 'turn.end', ok: boolean, duration_ms: number, tokens_in: number, tokens_out: number, cost_usd?: number };

两个 SDK 各写一个 "adapter → NodeEvent" 翻译层，对外提供同一个 schema。

B. anet CLI goal / loop 子命令的数据基础

• anet node logs <name> --kind tool.end — 跨 runtime 看一致的工具调用日志
• anet node goal <name> — claude-agent-sdk 走 SDKTask*Message，codex-sdk 走 todo_list item.completed 字段，两边都能反推 "agent 目前在做什么"
• anet node loop <name> --until 'todo.empty' — 等 todo_list 清空再退出（codex 友好），claude 走 task_notification.status='completed'

C. commhub session_state / progress REST/MCP 扩展

现状：CommHub 只在节点 reportStatus 里收 working/idle/blocked/error 四态。未来扩 session_state 字段携带：

• current_tool（来自 SDKToolProgress / codex command_execution）
• compacting（来自 SDKStatusMessage）
• rate_limited（来自 SDKRateLimitEvent）
• todo_progress（codex todo_list 完成率）

Dashboard 节点卡片可显示这层 subtle 状态，运营/调试体感大幅提升。

D. RFC 提议

下轮（Round 2+）我将整理 docs/rfcs/RFC-002-node-telemetry-layer.md（中文），把上述 A/B/C 合并成一个可审批的方案文档。RFC 落库需要 Vincent / 通信龙 review，本 issue 后续 round 评论会贴 RFC 草稿链接。

下轮预告（Round 2）

聚焦：claude-agent-sdk 的 agents 字段（subagent definition）+ forkSession + enableFileCheckpointing —— 对 anet "派单链路 " 和 "实验性回滚" 的可挖空间。

---

/loop dynamic-pacing fixed-interval 4m · 自动滚动到 Round 7+

[s2agi]

🧪 Round 1.5 — Dashboard Chat 端到端测试矩阵（设计稿）

Vincent 追加要求：调研要落到 "dash 页面进行 chat 时比较顺利的使用"。本评论是 25 条测试用例的设计稿，不实施只出案，等 N站马 / 测试号接入。

分层（沿用 anet 测试规矩：前一层不过不跑后面）

L0 基础链路   →  L1 chat UX  →  L2 多 Agent 协作
       ↓                 ↓                ↓
   L3 内容边界  →  L4 并发/压力  →  L5 故障/恢复
                                       ↓
                                 L6 跨 runtime parity

每条用例标注 "依赖 SDK 信号"——直接对应 Round 1 的 9 种当前未消费的 SDK 事件，验证 "未来 anet 暴露这些信号后 dashboard 体感会改善多少"。

---

L0 — 基础链路（必须先全绿）

ID	操作	期望	依赖 SDK 信号
L0.1	Dashboard chat 框输入 你好 → 发送	<30s 内 agent reply 渲染；无 console error	当前已有（result message）
L0.2	同 L0.1，连发 3 条	3 条都收到 reply，顺序正确	result message
L0.3	刷新页面后历史聊天可见	messages 持久化（commhub 落 SQLite）	（commhub 侧）
L0.4	关掉 agent-node 进程再发消息	dashboard 显示 "agent offline" 而不是无限等	report_status 心跳
L0.5	重启 agent-node 后续上 session	session_id 持久（claude jsonl / codex thread 都续）	SDKSystemMessage.init / Thread.id

L1 — Chat UX（消息渲染层）

ID	操作	期望	依赖 SDK 信号
L1.1	Agent 回复包含 markdown 代码块 ```python	代码块带语法高亮渲染	（前端 markdown 渲染）
L1.2	Agent 回复包含 GitHub 风格 task list - [ ] / - [x]	复选框 UI 渲染	（前端）
L1.3	Agent 回复 > 2000 字（anet sendReply 当前在 cli.ts:907 截到 2000）	dashboard 显示截断提示，或全文落 SQLite 后展开	cli.ts:907 是个 known limit，需 design
L1.4	Agent 处理 > 30s 的任务	dashboard 显示 "agent 正在工作" 状态而不是静默	SDKToolProgressMessage / Codex command_execution started — Round 1 标的 9 大未消费信号之一
L1.5	Agent 多步推理时显示进度	看得到 "读文件 → 分析 → 回复" 的中间态	SDKTaskProgressMessage / codex todo_list items
L1.6	中文 + emoji + 全角符号混合内容	正常显示，不出现乱码或截断在 emoji 字节中	（前端）

L2 — 多 Agent 协作（mesh 派单链路）

ID	操作	期望	依赖 SDK 信号
L2.1	Chat A："让 B 帮我做 X"	A 通过 commhub MCP 派单给 B，B 完成后 A 整合 reply 给我	parent_task_id chain 已有；future 可加 SDKTaskNotification.summary 摘要展示
L2.2	同 L2.1，但 B 此刻 offline	A 报错 "B offline" 而不是无限等	get_all_status 时间戳
L2.3	A → B → C 三跳 chain	C 完成 reply 经 B 经 A 回到我，链路在 dashboard 可视化（current limitation：chain 树需 dashboard 支持）	parent_task_id 链
L2.4	同时给 A、B 发任务	两条线独立处理，互不阻塞（agent-node 当前是 thinkQueue 单线，cli.ts:782）	已有；评估单线是否需放宽

L3 — 内容边界 / 边角

ID	操作	期望
L3.1	空消息 / 纯空格	dashboard 拒发或 agent 回 "消息为空"
L3.2	仅 emoji（如 👀）	anet 的 isLowValueText（cli.ts:845）过滤，但用户输入应被处理。验证过滤只针对 agent reply，不针对 user task
L3.3	单条 8000+ 字符长消息	agent 能接收；中途不被 commhub 2000 char 截断（注意：截断只在 reply 方向）
L3.4	同一字面量再发一次	agent 不会被 lastReplyTime cooldown 误吞（cli.ts:863 only cools for non-human source）
L3.5	用户输入包含 [alias] 前缀（伪装 agent 自身）	anet 的 own-prefix 过滤（cli.ts:861）保护：用户输入不应被过滤 → 可能现状有问题，需验证

L4 — 并发 / 压力

ID	操作	期望
L4.1	5 秒内连发 10 条消息	都进队列，按序处理，无 race condition
L4.2	同时打开 2 个 dashboard tab 跟同一 agent chat	两边都收到 reply（commhub broadcast）
L4.3	跑长任务时点 "stop" 按钮	任务中断，agent 回到 idle；当前 anet 没暴露 stop — dashboard ↔ commhub ↔ agent-node 的 cancellation channel 设计

L5 — 故障 / 恢复

ID	操作	期望	依赖 SDK 信号
L5.1	Agent 模型 rate limited	dashboard 显示 "rate limit, retry in Xs" 而不是默默卡住	SDKRateLimitEvent / SDKAPIRetryMessage — Round 1 标的高价值信号
L5.2	API key 失效（401）	dashboard 显示 "auth failed, check API key"	SDKAuthStatusMessage
L5.3	Agent 进程崩了再起	session_id 写回 config.json 后续上；dashboard 显示 "agent reconnected"	session 写回机制（cli.ts:202）
L5.4	commhub server 重启	dashboard SSE 自动重连；未送达消息从 inbox 重投	（commhub 侧）
L5.5	Agent 跑到 maxTurns 上限	dashboard 显示 "reached max turns, partial reply"	SDKResultError{subtype:'error_max_turns'} — 当前 anet 已捕获但未结构化暴露
L5.6	Codex thread 进入坏状态（cli.ts:678 catch 分支）	dashboard 显示 "agent restarted thread, history may be lost" 而不是悄悄丢历史	当前 silent，需 surface

L6 — 跨 Runtime Parity（同一测试用例，3 种 runtime 都跑）

ID	runtime	关键差异点
L6.A	claude-code-cli	spawn 本机 claude；用户 jsonl session；MCP via stdio
L6.B	claude-agent-sdk	bundled SDK；settingSources:[] 隔离；MCP via http
L6.C	codex-sdk	全局 codex binary；thread.id；MCP via ~/.codex/config.toml

至少 L0. + L1.1/1.4/1.5 + L5.5 三 runtime 都要绿*，避免 "在 claude-sdk 上工作但切到 codex 就 broken"。

---

接入建议

1. owner：N站马（dashboard repo 主理），通信牛（agent-node 配合），测试号执行
2. 执行环境：本地 hub（localhost:9200）+ 本地 dashboard（localhost:3000）+ 本地 3 个 agent-node（各一 runtime）。禁 prod hub 47.116.5.73。
3. 报告格式：docs/tests/report-dashboard-chat-N.txt（沿用现有约定）
4. 优先级：L0 → L1 → L5（最常见故障路径）→ L2 → L6 → L3 → L4
5. 自动化：Playwright + 一个 "测试用 agent-node" 用 http-api runtime + mock API key（成本可控），核心 L0/L1 可全自动

与 Round 1 调研的呼应

本矩阵里8 条用例（L1.4 / L1.5 / L5.1 / L5.2 / L5.5 / L5.6 / L2.1 / L1.3）直接依赖 Round 1 标的 "22 种未消费 SDK 事件" 里的关键 9 种。这给 RFC-002 "节点遥测层" 提供了具体验收测试：每暴露一种 SDK 信号，对应一条 dashboard chat 用例从 ❌ 转 ✅。

后续 Round 行动

• Round 2：把 L5.1 / L5.2 / L5.5 试装到 mock harness（仅设计，不动 prod）
• Round 3：codex-sdk todo_list → dashboard 进度展示的端到端 mock 流程图
• 等 RFC-002 落地后，回填本矩阵每条用例的 "当前状态 / 目标状态"

---

/loop fixed-interval 4m · 派单 N站马 接入评估

[s2agi]

🎯 Round 2 — 痛点收敛：Dashboard chat 长任务静默根因 + 修复设计

Vincent 明确反馈："现在 codex-sdk 和 claude-agent-sdk 用的不是很顺"，最大痛点是 dashboard 网页 chat 时长任务静默/慢/无进度。本轮不再铺大方案，直接定位根因 + 给最小修复路径。仍是出案不实施。

根因（代码定位 + 数据流追踪）

看 agent-node/src/cli.ts:805-819 processTask：

async function processTask(task, from, taskId) {
  log(`→ processing [${RUNTIME}]: ${task.slice(0, 80)}`);
  await reportStatus("working", task.slice(0, 200)).catch(() => {});   // ← 进任务前推一次
  let text, failed = false;
  try { text = await think(task, from, taskId); }                       // ← 这里可能 30s~10min
  catch (err) { text = `${RUNTIME} 错误: ${err.message}`; failed = true; }
  finally { await reportStatus("idle").catch(() => {}); }                // ← 出任务后推一次
  // ...
}

think() 内部 5 分钟都不会再调一次 reportStatus。Dashboard 拉到的 status='working' / task='<前 200 字>' 一旦设上去就冻结直到任务结束。这是 "chat 静默" 的根本原因。

SDK 侧明明有大量进度信号被忽略

两个 SDK 都在 streaming 里实时吐进度事件，anet 当前都丢了：

claude-agent-sdk — processWithClaude for-await 循环（cli.ts:546-561）只处理 system/init + result，丢了：

• 每次 tool call 的 PreToolUse hook 已经注册（cli.ts:533）但只写本地 log，没推 commhub
• SDKToolProgressMessage{tool_name, elapsed_time_seconds} 直接告诉你 "Bash 跑了 14s"
• SDKTaskProgressMessage{description, last_tool_name, usage.total_tokens} 给细粒度状态
• SDKStatusMessage{status:'compacting'} 告诉你 "在压缩历史不是卡死"

codex-sdk — processWithCodex for-await 循环（cli.ts:655-669）：

• ev.type === 'item.started' 已经写本地 debug log（cli.ts:656-658）但没推 commhub
• command_execution.command / mcp_tool_call.tool / todo_list.items 都能直接镜像到 dashboard

最小修复设计（不动业务逻辑，仅扩遥测面）

Phase 0 — quick win（建议 1 个 patch 内做完）：把已有的 hook / item.started 分支再加一行 reportStatus("working", "<task> [tool: BashRead 14s]")：

// Phase 0 仿写示例（不要 merge，仅设计稿）
// ── claude side ──
hooks: {
  PreToolUse: [{ hooks: [async (input) => {
    log(`[tool] ${input.tool_name}(${JSON.stringify(input.tool_input).slice(0, 80)})`);
    // ↓ 新增 1 行（带 throttle 避免刷屏）
    throttledReport(`[${input.tool_name}] ${JSON.stringify(input.tool_input).slice(0, 100)}`);
    return { continue: true };
  }] }],
},
// ── codex side ──
if (ev.type === "item.started") {
  const it = ev.item as any;
  // ↓ 已有 debug log，再加 1 行
  throttledReport(`[${it.type}] ${it.command?.slice(0, 80) || `${it.server}/${it.tool}` || ""}`);
}
// ── 共享 throttle ──
let lastReport = 0;
function throttledReport(progressText: string) {
  const now = Date.now();
  if (now - lastReport < 2000) return;  // 2s 节流
  lastReport = now;
  reportStatus("working", `${currentTaskPreview} ${progressText}`).catch(() => {});
}

好处：30 行代码，不改 SDK 消费分支，不改 commhub schema，dashboard 现有 status 字段即可承载。当下立刻把 "静默 5 分钟" 缩成 "每 2s 一条 tool 进度"。

坏处 / 待评估：task 字段被复用挂载进度文本，dashboard 现存 UI 可能没准备好 truncate / 区分 "原 task" 和 "current activity"。需要跟 N站马 对一下 dashboard 显示策略（是否需要新增 current_activity 字段而不是覆盖 task）。

Phase 1 — 结构化（RFC-002 范畴，下个迭代）：commhub MCP 加 report_progress 方法，schema：

interface ProgressUpdate {
  alias: string;
  task_id: string;            // 关联当前 inbox message id
  kind: 'tool_call' | 'tool_done' | 'compact' | 'rate_limit' | 'todo_update';
  tool_name?: string;
  elapsed_ms?: number;
  tokens_so_far?: { in: number, out: number };
  todo_items?: { text: string, completed: boolean }[];  // codex todo_list
  detail?: string;            // human-readable summary
}

Dashboard 拿到 progress event 后用专门的 UI 槽展示，不污染 task 主体。

Phase 2 — 失败可见：surface SDKRateLimitEvent / SDKAPIRetryMessage / SDKResultError{subtype:error_max_turns} 为 status='rate_limited' / 'retrying' / 'max_turns_hit' 三个新状态。Dashboard 用黄/红 badge 区分 "还在工作" vs "卡住了"。

谁动什么

模块	改动	谁	时机
agent-node/src/cli.ts	Phase 0 throttledReport + hook/item 分支加一行	通信牛（codex 侧）/ 通信SDK马（claude 侧）	Phase 0 立刻可做
commhub-server report_status 接受	无（Phase 0 复用），Phase 1 加 report_progress method	通信牛	Phase 1
agent-network-dashboard UI	Phase 0 看 task 字段变化触发 re-render；Phase 1 加进度卡	N站马 / N站牛	Phase 0 / Phase 1
docs/rfcs/RFC-002-node-telemetry-layer.md	把 Phase 0/1/2 写成可审批 RFC	通信SDK马（我）	Round 3 / Round 4

验收（呼应 Round 1.5 测试矩阵）

Phase 0 上线后：

• L1.4 "agent 处理 >30s 任务" 从 ❌ 转 ✅
• L1.5 "agent 多步推理显示进度" 从 ❌ 转 ⚠️（有进度但还是 text-only，非结构化）
• L1.5 Phase 1 完成后转 ✅

临时缓解（用户视角，不动代码可用）

在 dashboard 还没改前，用户可在 chat 里说 "做完每一步就用 send_message 给我汇报一条" — 强制 agent 自己 send progress message。这绕过 telemetry 走 commhub message 通道，副作用是消息列表会被 spam。不是长期解，但作为今天就能用的 workaround 写到 troubleshooting.md 合理。

下轮（Round 3）

聚焦：codex-sdk todo_list 端到端流图 — 从 codex CLI 内部 todo 状态 → ThreadEvent → anet 翻译 → commhub → dashboard 渲染。这是 Phase 1 RFC 里最复杂的一条链，先单独证明可行。

---

/loop fixed-interval 4m · 痛点定位：long-task silence · 已派 N站马 + 准备 RFC-002

[s2agi]

🧭 Round 3 — Codex todo_list → Dashboard 端到端流图 + N站马 baseline 整合

本轮收到 N站马（dashboard owner）回复，把 Round 2 "Phase 1 RFC-002 schema" 的盲点补齐 + 落实 codex todo_list 这条最复杂的链路。仍不实施，只设计。

N站马 baseline 关键情报（2026-05-12 收到）

1. dashboard chat 现状：<TaskChatPanel> 仅挂载在 /node 路由 + dispatch 抽屉；message 流走 /api/hub/tasks (poll) + /api/hub/events (SSE)
2. 失败现状：dashboard 拿到 status: 'failed' + result 字段里的 raw error text — 无结构化字段
3. 建议 schema 加 3 段：error_code + error_message + retryable: boolean
4. 遗漏的 substate：dashboard 已显示 "agent 正在工作" (AgentCard / Nodes 列表)，但没有 "正在打字 / 正在思考 / 正在跑命令" 的细粒度子状态 → RFC-002 可以加 substate 字段
5. 自动化能力：dashboard 已有 Playwright + mock route 拦 /api/hub/*，接 L0/L1 测试矩阵成熟
6. 排期：r46–r48 视觉打磨完才能完整 review 测试矩阵

上 SDK 侧的对照：todo / progress 信号在 SDK 里长啥样

codex-sdk —— 有原生 todo_list ThreadItem：

// @openai/codex-sdk 0.118.0 / dist/index.d.ts L97-101
type TodoListItem = {
  id: string;
  type: "todo_list";
  items: { text: string; completed: boolean }[];
};

Codex 内部自管 to-do list，每次更新都发一个 item.updated event，整个推理流就是 "plan → tool → update todo → tool → update todo → ..."。anet 当前在 cli.ts:655-669 已经在循环里见到这些 events，只是没翻译给 commhub。

claude-agent-sdk —— 没有独立的 todo_list message type，但通过两条途径暴露等价信号：

• 内置 TodoWrite 工具（Claude Code 全套工具之一）：走 PreToolUse hook，input 形如 { todos: [{content, status, activeForm}, ...] }
• SDKTaskStartedMessage / SDKTaskProgressMessage —— 当 agent 用 Task 工具派 subagent 时

所以 RFC-002 的统一 schema 必须抽象掉 "todo from where"，让两边都能往同一个 channel 喂。

端到端流图（codex 侧，单 turn 演示）

用户在 dashboard chat 发: "帮我把 docs 改成中文，先列计划"
  │
  ▼
[commhub] /api/hub/tasks POST → inbox
  │
  ▼
[agent-node] cli.ts:879 getInbox → processTask(...)
  │
  ▼
[agent-node] processWithCodex → thread.runStreamed(input)
  │
  │  for await (const ev of events) {
  │     ev.type === 'item.started'   item.type === 'todo_list'   items=[{text:'扫 docs/zh', completed:false}, ...]
  │     ev.type === 'item.updated'   item.type === 'todo_list'   items=[{...,completed:true}, ...]
  │     ev.type === 'item.started'   item.type === 'command_execution'   command='grep -r ...'
  │     ev.type === 'item.completed' item.type === 'command_execution'   exit_code=0
  │     ...repeat...
  │  }
  │
  ▼
[anet 翻译层] (待加) ── NodeEvent.kind='todo.update' / 'tool.start' / 'tool.end' ──┐
                                                                                  │
  ▼                                                                               │
[commhub MCP] (待加 method) report_progress {task_id, kind, ...payload}  ─────────┘
  │
  ▼
[commhub] insert into progress_events (task_id, ts, kind, payload_json)
  │
  ▼
[commhub] SSE /api/hub/events 推 progress 事件
  │
  ▼
[dashboard] <TaskChatPanel> 订阅 events 流 → 触发以下渲染分支:
  - todo.update    →  ProgressChecklist (新 UI 组件)
  - tool.start/end →  ToolActivityChip (现有 AgentCard substate badge 扩展)
  - rate_limit     →  AlertBanner (黄色)
  - max_turns      →  AlertBanner (红色)
  │
  ▼
turn 完成: [agent-node] sendReply → /api/hub/tasks reply
  │
  ▼
[dashboard] poll 拿到 final reply，渲染到 chat 流末尾

RFC-002 schema 草案（整合 N站马 建议）

// agent-node → commhub MCP call
interface ReportProgressRequest {
  alias: string;                        // 现有 report_status 同款
  task_id: string;                      // 当前 inbox message id（来自 CURRENT_TASK_ID env）
  kind: ProgressKind;
  ts_ms: number;                        // 客户端时间戳
  substate?: SubState;                  // 整合 N站马 #4 建议
  payload?: ProgressPayload;
  // 失败专用三段（整合 N站马 #3 建议）— 仅 kind='error' 时设
  error?: {
    code: string;                       // 'rate_limit' / 'max_turns' / 'auth_failed' / 'tool_error' / ...
    message: string;                    // 给用户看的中文/英文短句
    retryable: boolean;                 // dashboard 显示 "重试" 按钮的依据
  };
}

type ProgressKind =
  | 'turn_start'
  | 'thinking'              // claude SDKStatusMessage 'compacting' 或 partial assistant
  | 'tool_start'
  | 'tool_end'
  | 'todo_update'           // codex todo_list / claude TodoWrite hook
  | 'subagent_start'        // claude SDKTaskStartedMessage
  | 'subagent_end'          // claude SDKTaskNotificationMessage
  | 'rate_limit'            // claude SDKRateLimitEvent
  | 'compact'               // claude SDKCompactBoundaryMessage / codex auto-compact
  | 'error'                 // 失败终态
  | 'turn_end';

// 整合 N站马 #4：细粒度子状态，dashboard 用来挂 "打字气泡" / 命令行动画
type SubState =
  | 'planning'              // todo_list 刚生成或 reasoning item 占主导
  | 'tool_running'          // 当前在 command_execution / Bash / WebFetch
  | 'tool_waiting_io'       // 长跑命令 stdout 久无输出（>5s）
  | 'mcp_call'              // 在调 commhub / 其他 MCP server
  | 'compacting'            // 历史压缩中
  | 'rate_limited'          // 被卡，等回放
  | 'idle';                 // turn 结束

type ProgressPayload =
  | { kind: 'tool_start'; tool_name: string; tool_use_id: string; args_preview: string }
  | { kind: 'tool_end';   tool_use_id: string; ok: boolean; duration_ms: number; output_preview?: string; exit_code?: number }
  | { kind: 'todo_update'; items: { text: string; completed: boolean }[]; from: 'codex_native' | 'claude_todowrite' }
  | { kind: 'subagent_start'; sub_task_id: string; description: string; task_type?: string }
  | { kind: 'subagent_end';   sub_task_id: string; status: 'completed' | 'failed' | 'stopped'; summary: string }
  | { kind: 'rate_limit'; resets_at_ms: number; limit_type: string; utilization?: number }
  | { kind: 'compact'; phase: 'pre' | 'post'; tokens_before?: number; tokens_after?: number }
  | { kind: 'thinking'; preview?: string }
  | { kind: 'turn_start' | 'turn_end'; tokens_in?: number; tokens_out?: number; cost_usd?: number };

Dashboard 侧渲染策略（呼应 N站马 baseline）

<TaskChatPanel>
  ├── <ChatMessageList>         # 现有，渲染 message reply
  ├── <ProgressTimeline>        # 新增，订阅 SSE progress events
  │     ├── <SubStateBadge />   # 实时变化的 "正在 X" 子状态（substate 字段）
  │     ├── <ProgressChecklist /> # todo.update 渲染勾选清单
  │     ├── <ToolActivityRow /> # tool_start/end 流水（折叠）
  │     └── <ErrorBanner />     # error.code + message + retryable 按钮
  └── <ChatInput />

关键约束（避免过度工程）：

• ProgressTimeline 当 turn 结束（progress.kind='turn_end' 或 task reply 到达）后自动折叠为一行 summary，避免 chat 流被 dump
• 用户可点击展开看完整进度（取自 progress_events 表）
• 失败的 error banner 不自动折叠，retryable 按钮触发 dashboard 重发同一 task

数据存储（commhub 侧）

新增表 progress_events：

CREATE TABLE progress_events (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  task_id     TEXT NOT NULL,           -- 关联 messages.id
  alias       TEXT NOT NULL,
  kind        TEXT NOT NULL,
  substate    TEXT,
  ts_ms       INTEGER NOT NULL,
  payload     TEXT,                    -- JSON
  error_code  TEXT,
  error_message TEXT,
  retryable   INTEGER,                 -- 0/1
  created_at  TEXT DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_progress_task ON progress_events(task_id, ts_ms);
CREATE INDEX idx_progress_alias_ts ON progress_events(alias, ts_ms);

SSE endpoint /api/hub/events 改成多路：现有 message 事件 + 新 progress 事件，dashboard 用 eventSource.addEventListener('progress', ...) 监听。

Phase 编排（再细化）

Phase	内容	谁	风险
P0（已在 Round 2 提）	cli.ts 加 throttledReport，把 tool 进度借 report_status.task 推给 dashboard。Dashboard 不改 schema 只 trigger re-render	通信牛 / 通信SDK马	低，复用现有 schema
P1a（本 Round 新加）	commhub 加 report_progress MCP method + progress_events 表	通信牛 (commhub)	中，新 method + schema
P1b	agent-node 加 NodeEvent 翻译层（claude SDKMessage / codex ThreadEvent → ProgressKind）	通信SDK马 / 通信牛	中
P1c	dashboard 加 <ProgressTimeline> 组件 + SSE 监听 progress 事件	N站马 (r48 之后)	中
P2	error 三段（code / message / retryable）+ rate_limit/max_turns/auth 三种结构化失败 + 重试按钮	全员	低，schema 已在 P1a 加了字段

测试矩阵更新（Round 1.5 → Round 3 状态回填）

基于 N站马 baseline：

用例	当前状态	P0 后	P1 后
L0.1-0.5 基础链路	✅ 已通过（推测）	✅	✅
L1.4 长任务有进度	❌ 静默	⚠️ task 字段刷新（粗）	✅ ProgressTimeline 渲染
L1.5 多步推理可见	❌ 静默	⚠️ tool 名滚动	✅ checklist + tool 流
L5.1 rate_limit 可见	❌ raw error text	❌	✅ AlertBanner + 重试
L5.5 max_turns	❌ raw error text	❌	✅ structured error
L5.6 codex thread broken	❌ silent	❌	✅ error code='thread_reset'

下轮（Round 4）

聚焦：claude-agent-sdk 的 agents 字段 + Task 工具链路 —— 这是 claude 侧产 "subagent progress" 的来源，和 codex todo_list 对比，写出一份 "claude vs codex 进度信号对照速查表"。这块跟 anet "派单链路" 强耦合（commhub_send_task 当前是网络级派单，但 SDK 内部也能 fork subagent，两层语义需要文档区分）。

---

/loop fixed-interval 4m · N站马 baseline 已整合 · RFC-002 schema 渐成型

[s2agi]

🔀 Round 4 — claude vs codex 进度信号对照速查表 + anet 两层 "派单" 语义

落实 Round 3 预告。本轮一个核心发现 + 一张对照表 + RFC-002 schema 一处 patch。

核心发现：anet 现在混着用两层 "派单" 语义，dashboard 看不到第二层

第一层 — 网络层派单（anet 现有，dashboard 已可见）：

Agent A  ──commhub_send_task(alias='B')──>  Agent B（不同节点、不同进程、不同 SDK session）

B 是独立 agent，跑在独立 process / SDK session 里，parent_task_id 串回链路。dashboard 当前把它们渲染成两个独立 task 卡片，由 parent_task_id 串成树。

第二层 — SDK 内部 subagent（claude-only，anet 完全不暴露）：

claude-agent-sdk query()
  └─ Task tool 触发 fork                       SDKTaskStartedMessage(task_id=X)
       └─ subagent 跑（同一 process，同一 SDK 调用栈）
            ├─ 自己的 assistant messages       parent_tool_use_id=<原 Task 的 tool_use_id>
            ├─ 自己的 tool calls               同上
            └─ 结束                            SDKTaskNotificationMessage(task_id=X, status=...)

Claude SDK 里通过 parent_tool_use_id 字段（出现在 SDKAssistantMessage / SDKUserMessage / SDKPartialAssistantMessage / SDKToolProgressMessage 上）标识层级 —— top-level 为 null，subagent 内为父 Task tool_use_id。

问题：长任务用户在 dashboard 看到 "agent 工作中" 静默 5 分钟，其实里面可能有 3 个 subagent 在跑——agent-node 完全没 surface 这一层。Round 3 设计的 ProgressKind='subagent_start'/'subagent_end' 字段就是为这个准备的，但还要加 parent_progress_id 让 dashboard 能渲染成 nested 列表。

Claude vs Codex "进度信号" 对照速查表

概念	claude-agent-sdk	codex-sdk	anet 暴露?
主线 LLM thinking	SDKPartialAssistantMessage (stream_event)	reasoning item	❌ / 🟡 debug log
工具调用启动	PreToolUse hook + SDKToolProgressMessage	item.started (command_execution / mcp_tool_call)	🟡 PreToolUse hook 已注册仅打 log / 🟡 同
工具调用结束	PostToolUse / PostToolUseFailure hook	item.completed	❌ / 🟡
subagent / 任务委派（SDK 内）	Task tool（Read/Edit/Bash 一样是工具）+ SDKTaskStartedMessage + SubagentStart hook	无原生概念（codex 一个 thread 就是一条线）	❌ / N/A
subagent 进度	SDKTaskProgressMessage (parent task_id, last_tool_name, usage)	N/A	❌
subagent 完成	SDKTaskNotificationMessage (status, summary, output_file) + SubagentStop hook + TaskCompleted hook	N/A	❌
agent 自管 to-do	TodoWrite 内置工具（PreToolUse hook 截获 input.todos[]）	todo_list ThreadItem（item.updated 实时更新）	❌ / ❌
历史压缩	PreCompact / PostCompact hook + SDKCompactBoundaryMessage (compact_metadata.trigger / pre_tokens)	Codex CLI 内部 auto-compact（model_auto_compact_token_limit），无 event 外吐	❌ / ❌（codex 黑盒）
文件变更追踪	FileChanged hook + SDKFilesPersistedEvent（仅 enableFileCheckpointing 开了才发）	file_change ThreadItem（patch kind: add/delete/update + paths）	❌ / ❌
速率限制	SDKRateLimitEvent (rate_limit_info.status='allowed_warning'/'rejected', resetsAt, rateLimitType)	无原生（OpenAI 429 走 throw）	❌ / N/A
API 重试	SDKAPIRetryMessage	无原生（thread 重建走 anet catch）	❌ / 🟡 走 cli.ts:678 catch
用户输入提交	UserPromptSubmit hook	N/A（user input 是参数）	❌ / N/A
Session 边界	SessionStart / SessionEnd hook + SDKSessionStateChangedMessage	thread.started event（thread_id 首帧）	🟡 system.init / 🟡 turn 完结写回
工作目录变更	CwdChanged hook	N/A（thread 启动设 workingDirectory）	❌ / N/A
MCP 弹性认证	Elicitation hook + SDKElicitationCompleteMessage	N/A	❌ / N/A

对照解读：

• 两个 SDK 共有的进度概念：工具调用启停、agent 自管 todo、文件变更、session 边界 → RFC-002 schema 应优先覆盖这 4 项
• Claude 独有：subagent 委派、API 重试、速率限制、用户输入 hook、MCP elicitation → anet wrapper 可以选择性翻译，dashboard 在 codex runtime 下隐藏对应 UI
• Codex 独有：暂无（Codex 几乎所有进度都映射到 claude 的某种 hook 或 message）

RFC-002 schema patch — 增加 nesting + 来源标记

interface ReportProgressRequest {
  alias: string;
  task_id: string;
  // ↓ 本 Round 新增：嵌套支持（仅 claude subagent 场景非空）
  parent_progress_id?: string;        // 上一条 progress event 的 id，构成 tree
  origin: 'claude_sdk' | 'codex_sdk' | 'http_api' | 'claude_cli';
  // 已有字段省略...
  kind: ProgressKind;
  substate?: SubState;
  payload?: ProgressPayload;
  error?: { code: string; message: string; retryable: boolean };
  ts_ms: number;
}

Dashboard <ProgressTimeline> 看到 parent_progress_id 非空时缩进一层渲染 nested checklist；空时挂在 turn 主线上。

Dashboard 视觉草案（呼应 N站马 r48 后接入）

┌─ TaskChatPanel ──────────────────────────────────┐
│ User: 帮我把 docs 改成中文，先列计划                │
│                                                  │
│ 🤖 Agent (claude-agent-sdk):                      │
│   ⏳ planning...   [Task: docs-translator]   ← parent
│       └─ ⏳ tool: Read docs/zh/intro.md     [tool] ← child（parent_progress_id 指向 Task）
│       └─ ✅ tool: Edit docs/zh/intro.md  (1.2s)
│       └─ ⏳ tool: Read docs/zh/cli.md  (8s)         ← substate='tool_running'
│   ✅ subagent docs-translator: 3 files edited       ← turn_end summary 折叠
│                                                  │
│   final: 已完成 docs/zh/{intro,cli,faq}.md 中文化…  ← reply 主体
└──────────────────────────────────────────────────┘

关键交互：

• subagent 进行中：父行 spinner，子行实时刷 substate
• subagent 结束：父子全部折叠为一行 ✅ subagent <name>: <summary>，点击可展开
• turn 结束：整个 timeline 自动折叠为一行 ⏱ 3 subagents · 12 tools · 47s · $0.0234

Phase 编排不变（Round 3 那张表仍有效）

本 Round 只是把 P1c dashboard UI 的 "嵌套渲染" 显式列了出来。Schema 上 parent_progress_id 加进 P1a 的 SQL DDL（progress_events.parent_progress_id TEXT NULL + index）。

测试矩阵新加用例（L2 多 Agent 协作扩）

ID	操作	期望
L2.5	claude agent 用 Task 工具开 subagent，subagent 跑 30s	dashboard 显示 nested 时序，subagent 启停可见
L2.6	subagent 内再开 sub-subagent（理论上可行）	3 层嵌套渲染，turn_end 折叠
L2.7	同一 turn 内并行 2 个 subagent（claude allow）	timeline 显示 2 棵并行子树

下轮（Round 5）预告

聚焦：claude-agent-sdk 的 forkSession + enableFileCheckpointing + Query.rewindFiles() —— 这三个组合起来是 "实验性回滚" 能力。anet 当前完全没用。问题：

• 如果用户在 dashboard chat 里输错 prompt 让 agent 改坏了文件，能否回滚？
• 如果 dashboard 加一个 "undo" 按钮调 rewindFiles，体感如何？

会评估值不值得接，以及 codex 侧有没有等价能力（看起来 codex 没有，差异要写清）。

---

/loop fixed-interval 4m · 两层派单语义已厘清 · RFC-002 schema 加 nesting

[s2agi]

🔍 Round 5 — "派活无回应" 根因 + SDK REPL 模式可行性

Vincent 三连反馈：① 真痛点是 codex / claude-agent-sdk 节点派活后经常静默无回应 ② 案例 视频m马 + 通信牛（都 codex runtime） ③ 存储 SQLite only（RFC-002 schema 设计已契合，无需迁移） ④ 另一个角度：SDK 能不能像 claude code CLI 那样支持互动输入

本 Round 收回 "forkSession 回滚" 计划，把这两个新角度都研究透。

---

A. 失败路径目录 — "派活无回应" 6 大根因（已 log 实证 / 代码定位）

A1. SSE 401 token 失效 → 整个 inbox 通道哑（真案例：通信牛 49 次）

实证：/home/vansin/agent-orchestra/.anet/nodes/通信牛/logs/2026-05-11.log

19:50:40 [ERROR] SSE 401: token 无效或未配置。检查 ~/.anet/config.json 的 token 字段
19:50:43 [ERROR] SSE 401: token 无效或未配置。...
19:50:47 [ERROR] SSE 401: token 无效或未配置。...
...
(连续 49 次直到 21:05)

代码路径：cli.ts:1090-1140 connectSSE()。新任务只靠 SSE new_task 事件触发（cli.ts:1125-1128），没有定时 poll inbox 作 fallback。SSE 一旦 401，新任务就只能 "积压" 在 commhub inbox 里，agent 完全感知不到。

雪上加霜：cli.ts:1182 setInterval(reportStatus("idle"), 3min) 心跳照常跑，agent 在 dashboard 看起来 "健康活着"。用户体感就是 "派单后无回应"。

catch 路径只走一次：cli.ts:1100-1106 reloadNodeToken() 仅在 401 那一次重连尝试时调；若 reload 后的 token 仍是错（hub DB 被重置），就降级到 error() 然后继续以错 token 重连直到天荒地老。

A2. thinkQueue 单线序列化 → 上一个任务阻塞，新任务无限排队

代码：cli.ts:782-803

let thinkQueue = Promise.resolve();
function think(task, from, taskId) {
  const run = async () => { /* dispatch to claude/codex/http */ };
  const next = thinkQueue.then(run, run);    // ← 全部串行
  thinkQueue = next.then(() => {}, () => {});
  return next;
}

Codex thread.runStreamed() 如果 hang（subprocess 卡住、长 command_execution 命令、auth 弹窗未响应），整个 queue 就堵死。Subsequent inbox tasks 进 await think(...) 进入排队，永远不返回。

没有 per-task timeout。建议 RFC-002 加 --task-timeout flag + 超时后强制 thread.abort() + 上报 progress.error.code='task_timeout'。

A3. 8 条 "silent skip" 路径吞任务（用户感受：消息发出去就没了）

cli.ts:859-873 shouldSkipMessage 决定一个消息处理还是丢弃，全部只 debug log 不上报：

跳过原因	代码行	场景
self	cli.ts:860	from === ALIAS（自循环防呆）
own-prefix	cli.ts:861	content 以 [<ALIAS>] 开头
cooldown	cli.ts:864-866	距上次回同一 sender < 5s
low-value-inbound	cli.ts:869	非 task 类型 + 内容是 "ok/收到/嗯" 等
非 task / broadcast 类型	cli.ts:887-890	reply / message 类型直接跳
reply 成功但 low-value	cli.ts:900-902	agent 回答是 "收到" 之类
sendReply 抛错	cli.ts:910	只 warn log，不重试不上报
getInbox 拿空	cli.ts:878	normal，但若 commhub 端 bug 也表现为空

关键：第 3 条 cooldown 5s 的副作用 — 如果用户在 dashboard 5s 内连点两次 "send"，第二条直接被吞，agent 没任何反馈。

A4. Codex thread 重建路径丢历史 + 错误降级

代码：cli.ts:677-690

catch (e) {
  log(`codex thread error: ${e.message}, 重建`);
  const codex = new Codex({ config: CODEX_CONFIG });
  codexThread = codex.startThread({ /* 全新 thread */ });
  const turn = await codexThread.run(input);   // ← 第二次尝试
  return turn.finalResponse || "（无回复）";    // ← 又失败：返回 "（无回复）"
}

第二次尝试再失败，返回字面 "（无回复）"。processTask 的 regex（cli.ts:826-828）不匹配 "（无回复）"，所以 failed=false，被 isLowValueText 判定为低价值（注："无回复" 不在白名单但触发其他过滤），最终结果可能是：dashboard 收到 "（无回复）"。用户体感：派单后只看到 "（无回复）"，不知道实际两次都崩了。

A5. callCommHub 重试耗尽错误被吞

cli.ts:298-337 callCommHub 内部 3 次重试，全部失败抛 lastErr。但 reportStatus / sendReply 调用点（cli.ts:807/818/907）都加了 .catch(() => {}) 或 try/catch (e) { warn(...) }。

最坏 case：sendReply 重试 3 次都失败（commhub 504 / 网络抖动），用户永远收不到 reply。Log 里只有一条 warn。

A6. Codex auth 弹窗 / 升级提示卡 stdin

@openai/codex 二进制启动时若需 codex auth login 重新登录或有版本升级提示，会卡住 stdin 等待。anet wrapper 没强制 --non-interactive 或 input redirect。

症状：thread.runStreamed 永远不 resolve，触发 A2 thinkQueue 死锁。

---

B. 新发现：两个 SDK 都原生支持 "REPL 互动输入"，anet 没暴露

B1. claude-agent-sdk — Query 是完整 REPL primitive

sdk.d.ts:1664+ Query 接口：

export declare interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;                                           // 用户 Ctrl-C
  setPermissionMode(mode: PermissionMode): Promise<void>;               // 提权
  setModel(model?: string): Promise<void>;                              // 切模型
  setMaxThinkingTokens(n: number | null): Promise<void>;                // 调思考预算
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;    // 推新用户输入到运行中的 query
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

再加 query({ prompt: AsyncIterable<SDKUserMessage>, options }) 形式 — prompt 可以是个 async iterable，你可以把用户的 stdin 包装进去，让 claude 在同一个 Query 里多轮对话。这就是 claude 终端命令的工作方式。

B2. codex-sdk — Thread 多 turn 模式

@openai/codex-sdk 一个 Thread 实例可以连续 .run() / .runStreamed() —— 历史持久在 ~/.codex/sessions/，第二次 run 时自动接上前一 turn 上下文。TurnOptions.signal: AbortSignal 提供 cancel。

虽然没有 "中途 push 新输入" 的 streamInput 那么细，但 "用户问 → 等回答 → 用户再问" 的 REPL 节奏完全支持。

B3. 提议：anet node chat <alias> 子命令（仅设计，不实施）

用途：不走 commhub，不走 dashboard，直接在终端跟节点对话 —— 是上面 A 列各种失败路径的最快诊断工具。

$ anet node chat 通信牛
[chat] connecting to local config: .anet/nodes/通信牛/config.json
[chat] runtime=codex-sdk model=gpt-5.5 session=019d7a6c...
[chat] ready. Type 'exit' to quit, '/interrupt' to abort current turn.

> 你好
[agent]: 你好！我是 通信牛 codex agent，请问需要什么帮助？
   ⏳ tool: Read .anet/nodes/通信牛/config.json (0.3s)   ← 实时展示进度（用 Round 2 的 throttledReport 思路 + Round 3 的 progress event 但只渲染本地）
   ✅ tool done.

> /interrupt
[chat] interrupted.

> exit
[chat] bye.

实现骨架：

// anet/src/commands/node-chat.ts （仅设计）
import { query } from "@anthropic-ai/claude-agent-sdk";
import { Codex } from "@openai/codex-sdk";
import * as readline from "readline/promises";

async function chat(alias: string) {
  const cfg = loadNodeConfig(alias);
  const rl = readline.createInterface({ input: stdin, output: stdout });
  if (cfg.runtime === "codex-sdk") {
    const codex = new Codex({ /* ... */ });
    const thread = cfg.session ? codex.resumeThread(cfg.session) : codex.startThread();
    while (true) {
      const line = await rl.question("> ");
      if (line === "exit") break;
      const { events } = await thread.runStreamed(line);
      for await (const ev of events) renderEvent(ev);   // 复用 Round 3 ProgressKind 翻译
      if (thread.id) writebackSession(thread.id);
    }
  } else if (cfg.runtime === "claude-agent-sdk") {
    const userInputs: AsyncIterable<SDKUserMessage> = makeQueue(rl);  // wrap readline → async iterable
    const q = query({ prompt: userInputs, options: { ... } });
    for await (const m of q) renderMessage(m);    // 边读 user 输入边吐 SDK message
  }
}

B4. 跟 dashboard 的关系

• 不替代 dashboard chat —— dashboard 还是多节点协作的中枢
• 是 dashboard chat 的 dev / debug 镜像 —— 同一个 SDK API 路径，但 stdout 出来
• 是 SSE 故障时的逃生口 —— A1 那种 SSE 401 死锁场景，anet node chat 直跑 SDK 不依赖 commhub，agent 立刻可用
• 复用 Round 3 RFC-002 的 ProgressKind 翻译层 —— 同一套事件，终端用 ASCII 渲染，dashboard 用 React 组件渲染

B5. 测试矩阵新加 L7（CLI 互动）

ID	操作	期望
L7.1	anet node chat <alias> 拉一条对话	输入 "你好" → 收到 agent reply，stdout 看得到进度
L7.2	长任务跑一半敲 /interrupt	任务终止，回到 prompt
L7.3	关掉 chat 后用 dashboard 跟同一节点对话	session 续上（claude jsonl / codex thread.id 都续）
L7.4	SSE 401 状态下 chat 仍能用	✅ chat 路径不走 SSE

---

RFC-002 schema 更新（吸收 A + B）

增加 error.code 枚举：

type ErrorCode =
  | 'sse_token_expired'      // A1
  | 'task_timeout'           // A2
  | 'message_skipped'        // A3（带 reason 子字段）
  | 'thread_reset_lost'      // A4（codex 重建）
  | 'commhub_unreachable'    // A5
  | 'codex_stdin_hung'       // A6
  | 'rate_limit'             // 之前提的
  | 'max_turns'              //
  | 'auth_failed'            //
  | 'tool_error';

这些 code 让 dashboard 能给每种失败显示针对性提示 + 针对性 recovery 按钮（A1 → "刷新 token"，A6 → "重启节点"）。

---

下轮（Round 6）预告

聚焦：把 A1（SSE 401 没 fallback）和 A2（thinkQueue 死锁）写成两个独立 RFC stub（RFC-003 / RFC-004），单独可执行的小修方案。然后回头检查 RFC-002 主框架是否已经足够稳定可以提交到 docs/rfcs/ 作 draft。

---

/loop fixed-interval 4m · 案例：通信牛(log 实证) + 视频m马(结构推断) · 新方向：anet node chat REPL

[s2agi]

📚 Round 1-5 研究体系化 → RFC-002 + SaaS Mode Sketch（PR #23）

Vincent 要求：研究体系化存到 doc，给将来 SDK 做 SaaS 化执行固定 skills/任务铺垫。

本评论是 Round 1-5 的索引收口：所有研究材料从 issue 评论沉淀到正式 doc。

落地文件（PR #23 — https://github.com/sleep2agi/agent-network/pull/23）

• docs/rfcs/RFC-002-node-telemetry-layer.md — 356 行草案 RFC
• docs/saas-skills-mode.md — 166 行 SaaS 架构 sketch

各 Round 的最终归宿

Round	主题	沉淀到
Round 1	SDK 24+27+7 事件 anet 消费率统计	RFC-002 §动机 / SDK 暴露面被丢弃的事件清单
Round 1.5	Dashboard chat 25 条测试矩阵	RFC-002 §测试 引用，未来独立 TEST 文档拆出
Round 2	长任务静默根因 + P0/P1/P2 分阶段方案	RFC-002 §设计 + §实施步骤
Round 3	Codex todo_list 端到端流图 + N站马 baseline	RFC-002 §1-§6 schema + UI 设计
Round 4	claude vs codex 进度信号对照速查表 + 两层派单语义	RFC-002 §动机 + ProgressKind/SubState/parent_progress_id
Round 5	派活无回应 6 大根因 + SDK REPL 可行性	RFC-002 §ErrorCode + 即将拆 RFC-003

跟项目方向对齐

• ✅ SQLite-only：progress_events 表设计 single-DB 友好，每 10 万任务 ~1 GB，按 task_id age 归档 cron
• ✅ 不动业务逻辑：本 PR 纯 doc；RFC-002 实施留给后续小 PR
• ✅ SaaS 方向：docs/saas-skills-mode.md 明确 anet 不做托管 / 客户自建 SaaS / RFC-002 是关键前置依赖
• ✅ PR-based 流程：走 issue [feature] 探索一下基于 Pull Request 的研发流水线 #15 立的 PR pipeline（worktree + 分支 + PR + Closes/Refs 引用）
• ✅ 不加 Co-Authored-By Claude footer

接下来 /loop 走向（Round 6+）

本 issue 的研究 loop 继续，但写作目标转移：

• 不再每轮发评论铺新方向
• 改为对 RFC-002 内容做 spike 验证 / 迭代细化，或拆出 RFC-003（anet node chat REPL）等独立 PR
• 评论只在以下场景发：
  1. 收到 review 反馈需要回复
  2. spike 验证有重要发现
  3. 新角度（如 Vincent 提出新需求）

派单

• 通信龙：请 review PR docs(rfc): RFC-003 node telemetry + SaaS skills mode sketch (refs #18) #23 主框架方向 + 给 P0/P1a 实施排期建议
• N站马：r48 视觉打磨告一段落后请 review RFC-002 §6 dashboard UI 设计是否合理
• 通信牛：等 RFC-002 主框架 review 通过后，评估 P0 阶段（30 行 throttledReport）是否值得做 spike

等 review 反馈再继续 round 6。

---

/loop fixed-interval 4m · 研究 → RFC sketch 转换完成 · PR #23 等 review

[s2agi]

🔎 Round 6 — RFC-003 (anet node chat) 成熟度评估 + Vincent 决策点

不再堆新 PR（PR #23 等 review 中）。本 Round 评估 RFC-003 是否成熟可立，给 Vincent 一个 yes/no 决策点。

RFC-003 范围回顾

Vincent 在 Round 5 提出："SDK 能不能像 claude code CLI 那样支持交互输入"。Round 5 已验证：claude-agent-sdk 的 Query.streamInput() + codex-sdk 多 turn Thread.run() 都原生支持 REPL 模式。

核心提议：

anet node chat <alias>

用途：不走 commhub / dashboard / SSE，在终端直接跟节点的 SDK 对话。

三种典型使用场景

1. 节点 SSE 401 死锁时的逃生口 —— Round 5 §A1 通信牛 log 实证场景，dashboard 看不到节点，commhub 派单进黑洞。anet node chat 直接绕 commhub，验节点是否 SDK 层正常
2. 开发期快速验证 —— 新建一个 agent-node 想试它 prompt / model / tools 配置是否对路，不用先起 dashboard 派单
3. SaaS oncall 诊断 —— 客户反馈某个 skill 跑慢，oncall 在节点机器上 anet node chat <alias> 直接复现，省去走客户 API 网关

成熟度自检

维度	状态	备注
SDK 技术可行	✅ 已验	claude Query.streamInput() (sdk.d.ts:1839) + codex Thread.run() 多 turn 都原生支持
代码改动量	🟡 中等	估 200–400 行 TS。新文件：cli/src/commands/node-chat.ts + cli/src/repl/{claude,codex}-driver.ts。零改 agent-node/src/cli.ts 主流程
跟 RFC-002 关系	✅ 互补不阻塞	可以复用 RFC-002 §1 的 NodeEvent + adapter 翻译层（chat 模式渲染到 stdout，dashboard 模式渲染到 React），但不依赖 RFC-002 落地，独立可发
Session 续接	🟡 待确认	计划：chat 退出时把 SDK 给的 session_id / thread.id 写回 .anet/nodes/<alias>/config.json，下次 dashboard / chat 都接同一 session。需 review：用户在 chat 写下的对话会出现在下次 dashboard 续 session 里吗？（claude 是的：jsonl 共享。codex 是的：thread 共享）
权限边界	🟡 待 review	chat 拿到节点 .anet/nodes/<alias>/config.json 的本地权限即可，不消耗 commhub ntok_。但要避免让无 hub 访问权的人通过 chat 滥用 API key
Channel 接入兼容	🟢 不动	Telegram / Feishu / WeChat channels 完全不感知 chat 模式存在
测试	🟡 待补	issue #18 测试矩阵 L7.* 已草拟（Round 5 §B5），还未落具体步骤

实施骨架（sketch）

// @sleep2agi/agent-network/src/commands/node-chat.ts （新文件，sketch）
import * as readline from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { loadNodeConfig } from "../config.js";
import { ClaudeDriver, CodexDriver } from "../repl/index.js";

export async function nodeChat(alias: string, opts: { newSession?: boolean }) {
  const cfg = loadNodeConfig(alias);
  const rl = readline.createInterface({ input: stdin, output: stdout });
  const driver = cfg.runtime === "codex-sdk"
    ? new CodexDriver(cfg, { newSession: opts.newSession })
    : new ClaudeDriver(cfg, { newSession: opts.newSession });

  console.log(`[chat] runtime=${cfg.runtime} model=${cfg.model} session=${cfg.session?.slice(0,8) || "new"}`);
  console.log(`[chat] type 'exit' to quit, '/interrupt' to abort current turn, '/model <id>' to switch (claude only)`);

  while (true) {
    const line = (await rl.question("> ")).trim();
    if (line === "exit") break;
    if (line === "/interrupt") { await driver.interrupt(); continue; }
    if (line.startsWith("/model ")) { await driver.setModel(line.slice(7)); continue; }
    if (!line) continue;

    for await (const ev of driver.send(line)) renderToTty(ev);  // 复用 RFC-002 NodeEvent，stdout 渲染
  }
  driver.close();
  console.log("[chat] bye");
}

// src/repl/claude-driver.ts （sketch）
export class ClaudeDriver {
  private q: Query;                          // ← Query.streamInput()
  private inputQueue: AsyncQueue<SDKUserMessage>;
  constructor(cfg, opts) { /* 起 query() with prompt: this.inputQueue */ }
  async *send(text: string): AsyncIterable<NodeEvent> {
    this.inputQueue.push({ type: "user", message: { role: "user", content: text } });
    for await (const m of this.q) yield translateClaudeSDKMessage(m);
  }
  async interrupt() { await this.q.interrupt(); }
  async setModel(model: string) { await this.q.setModel(model); }
  close() { this.q.close(); writebackSession(...); }
}

// src/repl/codex-driver.ts （sketch）
export class CodexDriver {
  private thread: Thread;
  constructor(cfg, opts) { /* codex.startThread() or resumeThread(cfg.session) */ }
  async *send(text: string): AsyncIterable<NodeEvent> {
    const { events } = await this.thread.runStreamed(text);
    for await (const ev of events) yield translateCodexThreadEvent(ev);
  }
  async interrupt() { this.controller?.abort(); }
  close() { writebackSession(this.thread.id); }
}

推荐决策

建议：等 PR #23 (RFC-002) 收到 review 反馈后再立 RFC-003 PR，避免并行 review 摊薄注意力。RFC-003 的 NodeEvent / adapter 部分可以复用 RFC-002 落地后的成果，串行而非并行对节奏更友好。

如果 Vincent 觉得 RFC-003 比 RFC-002 优先级更高（毕竟它是"chat 静默痛点"的另一条破局路径——绕开 commhub 整链），也可以并行。

Vincent 决策点 ❓

1. RFC-003 (anet node chat <alias>) 立 PR 吗？三选一：
   • A 立刻立 PR，跟 RFC-002 并行 review
   • B 等 PR docs(rfc): RFC-003 node telemetry + SaaS skills mode sketch (refs #18) #23 (RFC-002) merge 后再立
   • C 不立，方向不对
2. 如果立，CLI 命名喜欢哪个？
   • a anet node chat <alias>
   • b anet node repl <alias>
   • c anet chat <alias>（不要 node 中缀）
3. session 续接默认行为：
   • a chat 退出时默认写回 session 到 config.json（dashboard / 下次 chat / channels 全接同一 session）
   • b chat 始终用临时 session（不污染 agent 的主 session）
   • c 提供 --new-session flag，默认接续

下轮（Round 7）

• 如果 Vincent 选 A/B → 起 RFC-003 PR（独立 worktree + 分支）
• 如果选 C 或反向 feedback → 调整方向，可能转向研究 "P0 spike 验证 throttledReport 在 dashboard 体感效果"

---

/loop fixed-interval 4m · 等 PR #23 review + Vincent 对 RFC-003 拍板

[s2agi]

📝 Round 6.1 — RFC 号变更说明 + Vincent 60% 数据点落入 RFC

两个外部信号同时进来，本评论一并 ack：

1. RFC 号冲突修正

通信龙提醒：PR #20 的 docs/rfcs/RFC-002-channel-bind-cli.md（issue #14 telegram bind，比本 PR 早开）已占 RFC-002 号。本 PR #23 按 "先开先占号" 原则改号：

旧	新
RFC-002 (node telemetry layer)	RFC-003 (node telemetry layer)
RFC-003 (anet node chat REPL, 未立)	RFC-004 (anet node chat REPL, 未立)

PR #23 已 force-push 修订（file rename + sed + title 同步）。Round 6 评论 里写的 "RFC-003 (anet node chat REPL)" 应读作 RFC-004。

教训：下个 RFC PR 提交前先 ls docs/rfcs/ 看号占用 + PR title 声明 RFC 号。

2. Vincent 实测数据点：派活成功率 ~60%

Vincent 2026-05-12："派活成功率并成功返回的成功率大概 60%"。

这数据已落进 RFC-003 §动机 / 实测痛点量化 + saas-skills-mode 警告区。

40% 失败的可能构成（按 issue #18 Round 5 §A 六大根因）：

• A1 SSE 401 + 无 poll fallback → inbox 堆积
• A2 thinkQueue 死锁
• A3 8 条 silent skip 路径无感吞消息
• A4 codex thread 重建丢历史 + 降级返回 "（无回复）"
• A5 sendReply 重试耗尽 catch 吞错
• A6 codex auth/升级提示卡 stdin

核心问题：当前无任何遥测能区分这 6 类。RFC-003 落地后 progress_events.error_code 字段第一次让 "60% 是 anecdote" 变 "按 error_code 分布的可度量数字"。

SaaS 含义：60% 是 SaaS-mode 的硬阻塞。客户不可能基于 60% 成功率的后端做产品。RFC-003 既是 SaaS 前置依赖，也是把它从 60% 推到 95%+ 的诊断起点。saas-skills-mode 文档已加 ⚠️ "RFC-003 未落地前不建议基于 anet 启动对外付费 SaaS"。

下轮（Round 7）方向

沿 60% 数据点继续挖：

1. 诊断脚本设计：在 RFC-003 P0 落地前能不能写个轻量 anet doctor --dispatch-success-rate 命令，扫最近 N 个任务的 inbox / log / status 数据，用现有数据估算 6 类失败的分布？（无须改 SDK 消费分支，只是 read-only 工具）
2. A6 codex stdin 卡死专项：codex CLI 升级 / auth 提示卡 stdin 是当前最难诊断的根因，调研 codex CLI 是否暴露 "non-interactive" flag 或 stdout-only 模式
3. 评估 RFC-004 (REPL) 是否还要立（Vincent 反馈"研究优先"+ 60% 数据点强化了诊断需求，REPL 的 oncall 价值上升）

---

/loop fixed-interval 4m · 号已对齐 · 60% 数据点已写进 RFC-003 + SaaS warning