Agent-System/.doc/ops/short-term/2026-09-21-taskrun-error-transparency.md

title, status, created, updated, owner, branch, worktree, mutex

title	status	created	updated	owner	branch	worktree	mutex
任务错误透传：NETWORK_ERROR 误报	done	2026-09-21	2026-09-21	Cursor	fix/taskrun-error-transparency-2026-09-21	-	chat+web

任务错误透传：NETWORK_ERROR 误报

目标

任务失败或 SSE 断线后，界面展示后端真实原因（或明确的业务拒绝），不再把未知失败统一显示为「网络连接异常」。

范围

• internal/taskrun/types.go：RunRecord 补 snake_case json 标签，使 GET /api/v1/tasks/runs/{id} 与前端 status / error_message 对齐
• web/src/hooks/useTaskRunAttempts.ts：failed 透传 error_message；cancelled 单独文案；扩展业务码；未知 HTTP 4xx 不再伪装成网络错误
• 回归测试（Go + 前端）

非目标

• 不晋升、不重建 test 环境（随下次 dev→test 生效）
• 不改 natfrp 隧道
• 不在本次加请求访问日志（见 long-term）

步骤

1. 从 dev 检出 fix/taskrun-error-transparency-2026-09-21
2. RunRecord json 标签 + 序列化回归测试
3. 前端错误透传与用例
4. 占集成槽位合入 dev 并冒烟（槽位空闲后）
5. 验收报告

验收标准

• GET /api/v1/tasks/runs/{id} JSON 含 status、error_message、run_id，不含 Status
• 任务 failed 且有 error_message 时，气泡 code 为 TASK_FAILED，不是 NETWORK_ERROR
• blocked_pending_governance 仍走治理提示
• 未知 4xx 业务码不显示「请检查网络」

相关链接

• 根因：test 环境今晨 natfrp 中继中断是诱因；前端 fallback 与 PascalCase 响应使真实原因不可见
• Long-term: 2026-09-21-http-request-access-log.md
• Test report: 2026-09-21-taskrun-error-transparency-test-report.md

证据 / 备注

• 2026-09-21 实测 test GET /api/v1/tasks/runs/run_1789882153312866054 返回 "Status" / "ErrorMessage"（无 json 标签）
• 前端文案「请检查网络后重试」来自 useTaskRunAttempts.ts 的 buildNetworkErrorInfo，不是 classify.go