docs: record public edge stream diagnostics

.agents/skills/unidesk-sub2api/SKILL.md

@@ -75,6 +75,9 @@ bun scripts/cli.ts platform-infra sub2api codex-pool runtime events --target PK0
 - `ops diagnosis` 的指标来自原生 admin/ops API；v0.1.155 没有独立 diagnosis/advice endpoint，CLI 必须把官方前端投影建议与 API 已验证事实分开呈现。
 - `ops channels` 使用原生渠道监控的 `7d`、`15d`、`30d` 窗口，支持平台、渠道和模型下钻；渠道历史固定分页并用 `--page-token <record-id>` 向更早记录翻页，`--record <record-id>` 精确下钻，不提供手工 `--limit`；原生响应未提供刷新倒计时时必须显示 unsupported。
 - Codex pool、统一 API key、master `~/.codex` 配置、FRP/Caddy 暴露、账号增删都必须走本技能的受控 CLI。
+- NC01 共享 public-edge 的流式错误：
+  - 必须先区分 Caddy response-header timeout、下游 `context canceled` 和主机资源压力；
+  - 具体证据链、全站 timeout owning YAML 与非核心进程处置规则见 [references/troubleshooting-public.md](references/troubleshooting-public.md)。
 - `api.pikapython.com` 异常先按 YAML target 区分 PK01 local edge/app、k3s FRP target 和账号池调度；用 `status`、`validate`、受控 apply/sync 以及最小 `/v1/responses` smoke 做分层恢复。完整步骤见 [references/troubleshooting.md](references/troubleshooting.md) 和 [references/public-exposure.md](references/public-exposure.md)。
 
 ## SuperAPI 全量捕获验收

.agents/skills/unidesk-sub2api/references/troubleshooting-public.md

@@ -1,5 +1,27 @@
 ## 公开暴露排障
 
+- NC01 共享 public-edge 的排障入口：
+  - 先用一次 `bun scripts/cli.ts platform-infra public-edge status --target NC01 --site <site-id>`；
+  - 再按 `installed/desired sourceCommit`、managed Caddy 指纹和 `matchesDesired` 判断运行面是否已经收敛；
+  - 不要从单个 Sub2API Pod 的 `/health` 推断公网流式链路正常。
+- 共享 public-edge 的超时配置：
+  - 默认 `response_header_timeout` 只由 `config/platform-infra/public-edge.yaml#targets.NC01.runtime.responseHeaderTimeoutSeconds` 控制；
+  - 产品 YAML 中的 Sub2API 本地 HTTPS timeout 不会自动覆盖共享 Caddy；
+  - 长耗时流式 API 应由共享 edge 的 owning YAML 统一声明，避免只修一个站点。
+- Caddy `context canceled` 的判定：
+  - `aborting with incomplete response` 且错误为 `context canceled`，表示下游客户端或前置代理已经取消连接；
+  - 该日志不能单独证明 Caddy 主动超时；
+  - 只有固定耗时接近实际 `response_header_timeout`，且存在 Caddy timeout 和对应请求状态证据，才归类为 edge response-header timeout；
+  - 同时对齐 Sub2API 是否记录 `status_code=200`、`latency_ms` 和同一请求的 `context canceled`。
+- 多账号、多分组同时断流的主机检查：
+  - Sub2API 的 `/models` 或调度缓存同时出现 `context canceled` 时，先检查 NC01 主机负载、内存压力和非核心遗留测试进程；
+  - 只停止能明确证明为遗留测试或一次性任务的进程；
+  - 不停止 k3s、containerd、Sub2API、Redis、数据库、egress proxy 或其他运行面基础设施。
+- public-edge 自动交付判定：
+  - host-only reconcile 成功但通用 CI closeout 报 `pac-gitops-missing` 时，以唯一 PipelineRun 的 TaskRun 状态和 `public-edge status` provenance 为准；
+  - 不人工执行 reconcile、Argo sync 或 Caddy patch；
+  - 失败只显示空的 `trans sh -- 失败` 时，登记 CLI 可见性问题，并下钻该 PipelineRun 的 bounded TaskRun 日志。
+
 - FRP 不通：先看 `codex-pool expose --confirm` 输出的 `masterFrps`、`masterCaddy`、`sub2api-frpc` 和 public 401 probe；需要低层证据时只用 `trans G14:k3s` 做 bounded 查询。
 - k3s external-active target 的 public URL 不通：先区分 DNS/TLS/Caddy/FRP/Sub2API。DNS 未解析到 YAML 声明的 PK01 地址时，Caddy ACME 会失败，HTTPS 不能算完成；可用 PK01 loopback FRP 端口和 PK01 公网 remotePort 证明 FRP 数据路径，但最终仍要等 DNS 生效后重跑 HTTPS health、`/v1/models` 和 `/v1/responses`。PK01 host-Docker local target 不走 FRP，不能用 FRP 端口探针替代本机 loopback/Caddy/app 验证。
 - D601 external-active apply 后其他 PK01 HTTPS 服务消失：优先怀疑共享 Caddy managed block 合并失败或旧整文件写入路径复现。用受控 Sub2API apply 输出和 PK01 Caddy managed block markers 取证，再通过各服务自己的 YAML apply/public-exposure 入口恢复；不要手工复制某一份 Caddyfile 作为长期修复。