[grapedev-bot]

概述

修复新建隧道不返回 status 时的客户端可观测性问题（Issue #56）。本 PR 为客户端侧可独立交付部分，服务端根因单列由后端承接。

改动

• go-sdk/models.go：TunnelStatus 增加 ReportedAt int64 (json:"reportedAt")，字段缺失时兼容为 0。
• cli/cmd/tunnel.go：devbridge show 在 status 缺失时以 - 展示计数/流量并提示“统计状态未上报”；reportedAt 缺失或距今超过 120s 时提示“统计上报时间缺失/统计状态已过期”，不再静默显示误导性 0。正常时额外展示统计上报时间。
• 单测：go-sdk/tunnel_test.go 覆盖 status 正常 / null / reportedAt 缺失；cli/cmd/tunnel_test.go 覆盖 status nil / reportedAt 缺失 / 新鲜 / 120s 边界 / 过期。
• 文档：docs/reference/api.md、docs/zh/reference/api.md、docs/guide/tunnels.md、docs/zh/guide/tunnels.md 同步 status/reportedAt 语义及缺失/过期处理。

服务端承接项（外部，需后端排期）

relay-controller 需修复新建隧道创建时的注册与统计采集器订阅分片/注册表一致性：

1. 新建隧道创建即完成统计采集器注册，新老隧道同源。
2. GET /v1/tunnels/{id} 与 GET /open-api-inner/v1/relay-controller/tunnels/{id} 均返回 status（含 reportedAt）。
3. 新建隧道 host 后 ≤30s hostConnectionCount=1，reportedAt ≤60s。
4. 最终以 SHOW-010~013 全 PASS 为回归判据。

验证

• go test ./...、go vet ./...（go-sdk、cli 均通过）
• gofmt 无差异
• golangci-lint：当前环境未安装，未执行

关联

• Issue [Bug] 新建隧道不产生 status（连接计数/流量统计恒为 0），老隧道正常 #56

Closes #56

[grapedev-bot]

[QA Agent] 审查报告

审查范围

• PR fix(sdk,cli): surface tunnel status reporting gaps (#56) #58 fix(sdk,cli): surface tunnel status reporting gaps (#56) → develop，head e3eca69，10 文件 +167/-11，1 commit
• 关联 Issue：Closes [Bug] 新建隧道不产生 status（连接计数/流量统计恒为 0），老隧道正常 #56

配置检查

• ✅ Title：清晰描述变更范围（sdk/cli，status 上报缺口）
• ✅ Description：包含背景、改动、验证与服务端承接项
• ⚠️ Labels：PR 未设置分类标签（Issue 已有 type/bug、priority/high、area/*）
• ⚠️ Assignee：PR 未设置责任人
• ✅ Issue 关联：body 含 Closes #56
• ✅ PR 链接正确性：Issue 中链接为 markdown /pull/58，格式正确

代码审查

结论：✅ 通过（无阻断问题）

已核对实现与 Spec：

• go-sdk/models.go：TunnelStatus.ReportedAt int64 使用 json:"reportedAt"，缺省为 0，兼容老服务端；文档声明为 Unix 秒，样例值量级一致。
• cli/cmd/tunnel.go：status == nil 时连接数/流量显示 - 并提示“统计状态未上报”；reportedAt == 0 提示上报时间缺失；age > 120s 提示过期；边界 120s 判定与测试一致；未来时间戳按时钟偏差容忍。
• 单测：SDK 覆盖 status 正常/null/reportedAt 缺失；CLI 覆盖 nil/缺失/新鲜/120s 边界/过期/未来时间戳。
• i18n：en/zh 新增文案均已补齐，%s 格式化路径正常。

Optional（非阻断）：docs/guide/tunnels.md 与 docs/zh/guide/tunnels.md 新增段落表述为“status 缺失或 reportedAt 超过 120 秒时以 - 展示不可用值”，但实现仅在 status == nil 时展示 -；reportedAt 过期时仍展示数值并追加过期告警。建议将文档收窄为“status 缺失时用 -；上报过期时保留数值并明确告警”，避免文档与行为不一致。

工作流审查（Agent Work Loop）

结论：✅ 健康（存在可选改进项）

维度	证据状态	严重度	发现	影响	修复	验收
任务理解	✅ 已观察 — Issue #56 含现象/复现/对照/验收标准与 Spec	-	完成定义明确	-	-	-
受控执行	✅ 已观察 — 仓库无 AGENTS.md/CLAUDE.md（VCS API 404），无 skills/ 工作流资产	🟢 Optional	缺少仓库级 Agent 指引与可复用技能	跨 Agent 执行依赖临时上下文，复现性受限	沉淀最小 AGENTS.md 或技能条目	文件存在且覆盖构建/测试/审查命令
变更验证	✅ 已观察 — 新增 SDK/CLI 单测；build-cli.yml PR 触发 goreleaser，before.hooks 执行 go test ./...；build-sdk.yml 执行 build/vet/test	🟢 Optional	实际 CI 运行结果未观察到（当前 API 无 checks/status 读取能力）；PR 声明 golangci-lint 未执行，Spec 验收含 lint	合并前仍需人工确认流水线绿灯与 lint	合并前确认 CI 结果，必要时补 lint 门禁	CI 绿灯 + lint 通过记录
可靠交付	⚠️ 未观察 — 分支保护/必需检查未通过 API 暴露	-	无法确认合并门禁	-	-	-
经验沉淀	✅ 已观察 — en/zh API reference 与 guide 已同步	🟢 Optional	未沉淀为可复用 skill	同类“字段缺失/过期可观测性”问题易重复处理	视需要沉淀为技能或检查清单	复用资产存在

安全扫描

结论：✅ 安全 — 未发现硬编码密钥、敏感信息或外部输入不安全处理。

合并检查

• ✅ 代码审查通过
• ✅ 测试用例已覆盖核心分支
• ⚠️ 实际 CI 运行与 golangci-lint 未确认
• ⚠️ PR 缺 Labels/Assignee，建议人工补齐
• 审查结论：无 Critical/Required 阻断项，本 PR 客户端侧修复可进入合并流程；统计恒 0 的服务端根因仍需 relay-controller 修复，并以 SHOW-010~013 全 PASS 作为最终回归判据。