observability

observability

用 debug pipeline 巡检运行中的系统（cloud log / k8s / daemon / DB 切片），异常时开一个 bug task 把证据带回 bugfix 循环（apc/05 S10 · 生命周期矩阵行 11 监控→回流）。触发器 = product205 定时任务后端（已建，缺前端）挂周期巡检——本 skill 是那次巡检真正干的活，不悬空。

承重纪律：

• healthy 扫描不开 task。 没有异常就报"绿"并停手——绝不为了"有产出"造一个假 bug。一个无论系统健不健康都会建 task 的巡检 = 噪声制造机。
• 异常 → bug task 必须带证据 ref。 bug task 的 description 要挂可追溯锚（pod / workspace / task id + debug 切片摘要，或把 bundle 产物 cloud asset upload 后引 asset:<id>）。空口"系统好像有问题"不是 bug task。
• oracle 是真 task 行，不是聊天叙述。 "我建了 bug task" 不算数——cloud task create 返回的真 id + 回读的 task 行才算。

什么时候用：周期巡检（定时任务触发）或收到"系统是不是出问题了"时——先用 debug pipeline 取副作用切片核实，再决定是否回流。

工具契约（签名以此为准，先核后用）

命令	作用	输出/退出码
npx tsx scripts/debug/admin-observability.ts capabilities [--env=local|test|prod]	canonical Admin v1 discovery；读取 principal、capabilities、schema version 与 opaque contract digest	0 成功；不兼容/无权限非零
npx tsx scripts/debug/admin-observability.ts logs --target-kind=service --target-id=prismer-cloud --purpose=<reason> [--since=15m] [--cursor=<opaque>] [--completeness=require-complete|allow-partial]	canonical POST /api/admin/v1/logs:query 只读快照；命令内部必须先 discovery；cursor 只能原样回传	默认 require-complete；置信边界完整 0，不满足 3，请求/合同错误 1，用法错误 2
cloud admin log-targets --kind <service|sandbox|daemon> --purpose <reason> [--workspace-id <id>] [--cursor <opaque>]	daemon-held credential 下发现 DB-resolved logical targets；不接受 namespace/selector	0 完整成功；partial projection 2；请求失败 1
cloud admin logs --target-kind <kind> --target-id <id> --purpose <reason> [--attach-to-task [taskId]]	credentialless loopback 查询 service/sandbox/daemon；可经既有 daemon task-attach 把 JSON 证据绑定到 task	0 完整成功；partial 2；失败 1；attach 要求 daemon dispatch + PRISMER_ARTIFACTS_DIR
npx tsx scripts/debug/inventory.ts [--env=local|test|prod] [--json]	全局索引：running pods / recent workspaces / recent tasks / recent errors	人读 5 段 或 --json
npx tsx scripts/debug/bundle.ts <workspace|task|pod> <id> [--sections=db,system,k8s,daemon] [--stdout] [--since=ISO]	复合切片（DB+system-log+k8s+daemon）	默认写 ./debug-bundle-*.json，--stdout 打屏
npx tsx scripts/debug/snapshot.ts <workspace|task|conversation|container> <id> [--json|--brief]	DB 切片（task 终态行/runs/logs/approvals/assets）	默认 compact，--json raw
npx tsx scripts/debug/logs.ts [--contains=text] [--since=ISO|10m|1h] [--level=...] [--json]	cloud 进程 pino ring buffer	每行一条 或 --json
cloud task create --title <t> --description <d> --kind work_item [--priority high] [--json]	开 bug task（--kind work_item 是 board 投影）	打印 ID: <taskId>（--json 出整行）
cloud task list [--json]	回读 task 行确认落库	0 成功

• --kind 合法值恰好两个：work_item（默认，bug/工作项）/ goal。bug 巡检一律 work_item。
• 鉴权：debug pipeline 走 admin RBAC（--env=local dev 短路免鉴权；--env=test|prod 需 PRISMER_API_KEY_TEST/PRISMER_API_KEY）。coding agent 的 workdir env 不注入高危凭据——test/prod 巡检由平台方持凭发起，不在 agent 的 bash 里裸读（apc/05 §3 凭据可见性边界）。
• 凭据边界：canonical 命令没有 --api-key 参数，也不把 credential 写入 stdout、stderr 或产物；禁止 env、printenv、shell tracing（set -x）和把 Authorization header 拼进命令行。平台执行器在模型不可见边界注入 credential。
• 合同边界：只调用 /api/admin/v1/capabilities 与 /api/admin/v1/logs:query，不猜 403、不回退 legacy route、不猜 digest 算法。若平台固定了本次发布 digest，可由执行器注入 PRISMER_ADMIN_CONTRACT_DIGEST 做 exact match。

Workflow

1. 先落调用回执（见文末 ACK 块），再做 canonical discovery + Cloud 日志快照

APC 自动巡检默认要求完整结果。先调用 capabilities，再由同一命令进程完成 logs query：

mkdir -p .e2e-tmp/apc/observability
npx tsx scripts/debug/admin-observability.ts capabilities \
  > .e2e-tmp/apc/observability/admin-capabilities.json
npx tsx scripts/debug/admin-observability.ts logs \
  --target-kind=service --target-id=prismer-cloud --since=15m \
  --purpose="periodic APC observability sweep" \
  --completeness=require-complete \
  > .e2e-tmp/apc/observability/admin-service-logs.json
admin_logs_exit=$?

admin_logs_exit=3 表示所需置信边界不完整，不得宣布 healthy；读取 JSON 中的 requestId、sources[]、partial、attemptedSourceTiers、availableSourceTiers、 confidenceBoundary.productionRetainedRequirement、contractDigest、evidenceHash 后报告受限结论。 attemptedSourceTiers 只说明服务端尝试过某 tier；只有 availableSourceTiers 才代表可用证据， retained source 为 unavailable 或 error 时严禁把它写成 retained evidence。 只有 human 明确做探索性查询时才可传 allow-partial，且逐 source outcome 仍必须保留。1/2 是请求或 用法失败，同样不能当作“没有 error”。canonical 输出可作为 task-bound evidence，但先确认其中不含凭据； 不要长期保存为 loose file。

生产环境的 require-complete 还有强 gate：必须同时看到 availableSourceTiers 包含 retained、 confidenceBoundary.productionRetainedRequirement.satisfied=true、稳定 ordering/continuity、 完整 coverage、truncated=false、mayDuplicate=false。任一不满足均按退出码 3 处理。 分页时只可把响应 nextCursor 原样作为下一次 --cursor=<opaque>；不得解析、修改或自行生成 cursor。 SLS 当前只提供 offset continuation，服务端会明确标记 continuity=best-effort、mayDuplicate=true 和 partial=true；即使 provider query 返回 Complete 也不得升级成完整证据。Sandbox/Daemon 查询前先用 cloud admin log-targets 发现 logical id，禁止把 Pod、namespace 或 label selector 当 target id 猜测。

2. 拉全局索引，覆盖其余信号面

mkdir -p .e2e-tmp/apc/observability
npx tsx scripts/debug/inventory.ts | tee .e2e-tmp/apc/observability/inventory.md; echo "inventory exit=$?"
npx tsx scripts/debug/inventory.ts --json > .e2e-tmp/apc/observability/inventory.json    # 机器形（可选）

产物落 repo-relative 的 .e2e-tmp/apc/observability/（已在 .gitignore），不要落 /tmp——判据要读回你引用的那一行，/tmp 从仓库根不可解析、跑完即毁的证据等于没有证据（同 test204「证据销毁反 pattern」）。报告前不许删这批产物。

读 5 段：pods（有没有 pending/crash）· workspaces · recent tasks（有没有卡在 pending/running 超时）· recent errors（error/warn 级别）。先索引再下钻——不要一上来 logs.ts --since=30m | grep（那是 v0 习惯）。

3. 锁定可疑目标 → 下钻取副作用切片

对索引里冒出的可疑目标（报错的 pod / 卡死的 task / 异常 workspace）一次拿全套：

# 已知某 task/workspace/pod 可疑 → 复合切片
npx tsx scripts/debug/bundle.ts task <taskId> --sections=db,system,k8s,daemon --stdout > .e2e-tmp/apc/observability/bundle.json
# 或单钻 DB
npx tsx scripts/debug/snapshot.ts task <taskId> --json > .e2e-tmp/apc/observability/snapshot.json
# 关键字检索 cloud log
npx tsx scripts/debug/logs.ts --contains=<taskId> --since=1h > .e2e-tmp/apc/observability/logs.md

4. 判异常（副作用为准，不猜）

观察到的副作用	判定
recent errors 有 level:error（非预期的一次性 warn）· pod crash/pending 超时 · task 卡 running 超 reaper 阈值无心跳 · daemon /healthz 不应答	异常 → 第 4 步开 bug task
全绿：无 error 级、pods running、tasks 正常流转、daemon 健康	healthy → 报绿，不开 task，停手
单条 flaky/预期内 warn（如 [K8sSandbox] pod-status: read failed 这类已知噪声）	非异常——记一句备注，不开 task（造假 bug 比漏报危害大）

canonical query 的服务端 partial=false 不等于生产证据 gate 已满足，更不等于“事实必然完整”； confidenceBoundary.partial=true、truncated=true 或生产 retained gate 不满足时，结论置信边界必须显式 收窄，自动巡检不得据此判 healthy。

拿不准是不是真异常 → 单钻确认（snapshot/logs），证据不足不开 task。开一个假 bug 会污染 bugfix 循环。

5. 异常 → 开 bug task（带证据回流 1b）

cloud task create \
  --title "[observability] <一句话症状: pod X crash / task Y stuck>" \
  --description "Anomaly from periodic sweep.
Target: <pod|task|workspace>:<id>
Evidence: <recent-errors 摘要 / bundle 关键段 / asset:<id>>
Repro: npx tsx scripts/debug/bundle.ts <entity> <id> --stdout" \
  --kind work_item --priority high --json

抓返回的 id（--json 里 data.id，或人读 ID: 行）——这条真 task 行是本 skill 的产出 oracle。可选：cloud asset upload .e2e-tmp/apc/observability/bundle.json 拿 asset:<id> 挂进 description 作持久证据。

6. 回读确认落库

cloud task list --json | grep <newTaskId>   # 或 cloud task get <id>

确认 bug task 真行存在、kind=work_item、带证据。

输出契约（机器判据按这个复验，别自由发挥格式）

旧判据是「正文里出现过 pod/task/error 加个数字」的关键词匹配——一篇没跑过任何命令的报告照样满分，而且只扫了 pods 就宣布全绿也照绿（其余四面静默跳过，判据看不出来）。现在五个信号面各占一行、由 dimension-coverage 逐面复核：某一面没写这行 = 判红，正文里出现那个词不算数。

每行的答案二选一：① 指向你这轮真落盘的巡检产物里的那一行（repo-relative path:line，判据把该行读回磁盘，文件不存在 / 行号越界 / 空行 → 判红）；② 显式 N/A — <理由 ≥20 非空白字符>（这一面本轮确实扫不到，比如没有 daemon 可达）。

- SIGNAL-pods: .e2e-tmp/apc/observability/inventory.md:12
- SIGNAL-workspaces: .e2e-tmp/apc/observability/inventory.md:21
- SIGNAL-tasks: .e2e-tmp/apc/observability/inventory.md:34
- SIGNAL-errors: .e2e-tmp/apc/observability/inventory.md:47
- SIGNAL-daemon: N/A — 本轮 --env=local 无在跑的 sandbox pod，daemon /healthz 无可探测目标

行号照抄 cat -n / rg -n 你自己那份产物的真实输出，不许凭印象写。引用必须 repo-root-relative（/tmp/... 与绝对路径一律判红——这也是上面要求产物落 .e2e-tmp/ 的原因）。报告前不要删产物：判据是在你跑完之后才读盘的。

产物存成可引用的扩展名：引用解析器只认固定后缀集（ts/tsx/js/jsx/mjs/cjs/prisma/sql/md/json/sh/py/yml/yaml）——所以人读产物存 .md、机器产物存 .json。存成 .txt / .log 引用不会被解析，那一面会被判成"没给可复核证据"。

这条判据管的是「每一面都被显式判过」，不替代下面的异常/healthy 判定——它挡的是静默漏扫（只看了一面就宣布全绿），不是替你判异常。

产出（副作用 oracle，报告里必须给）

1. debug 切片真产物：inventory/bundle/snapshot/logs 的结构化输出（含 recent errors / pod 状态 / task 终态字段）——不是"我看了一下感觉没事"。
2. canonical Admin receipt：capabilities + logs query 输出必须包含 contract digest、principal、requestId、attemptedSourceTiers、availableSourceTiers、逐 source outcome、coverage/partial/truncated、production retained gate、redaction ruleset 和 evidence hash；默认置信边界不完整的命令退出码必须为 3。
3. 异常路径：cloud task create --kind work_item 返回的真 task id + 回读的 task 行（kind=work_item）+ description 里的证据 ref（target id / asset）。
4. healthy 路径：明确"无异常、未开 task"，附巡检覆盖了哪些目标（pods/tasks/errors 计数）作为扫过的证明。

不许：healthy 时凭空造 bug task（假阳）· bug task 无证据 ref（空口判红）· 断言聊天文本而非真 task 行 · 拿旧 bundle 当本轮证据 · 把已知噪声 warn 当异常刷 task · 把巡检产物写进 /tmp 或跑完就删（证据必须留到判据读盘之后）· 只扫一两个信号面就宣布全绿（五面各自一行，缺一行判红）。

调用回执（APC 平台方运营纪律 · 自动注入，勿手改）

执行本 skill 的第一步，先落一条调用回执：

cloud skill ack observability --task "$PRISMER_TASK_ID"

按退出码分流（这条命令的退出码是承重信息，禁止用 || 兜底、; true、 set +e 或重定向把它抹掉）：

exit	含义	你要做的
0	回执已落库（im_task_logs.action='skill_ack'）	继续执行本 skill
3	无 task 上下文——本次运行没有 task，产不出回执	继续执行本 skill；但本次运行没有回执，任何报告里都不得声称已 ack
4	你不是该 task 的 assignee，服务端拒绝	停下并上报：回执只能由执行该 task 的 agent 产生
1	其它失败（网络 / 服务端）	重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」

回执只证明本 skill 被调度，不证明执行正确——效果证明由本 skill 自己的 acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。