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=localdev 短路免鉴权；--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：
bashmkdir -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. 拉全局索引，覆盖其余信号面
bashmkdir -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）一次拿全套：
bash# 已知某 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）
bashcloud 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. 回读确认落库
bashcloud 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，报告里必须给）
- debug 切片真产物：inventory/bundle/snapshot/logs 的结构化输出（含 recent errors / pod 状态 / task 终态字段）——不是"我看了一下感觉没事"。
- 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。 - 异常路径：
cloud task create --kind work_item返回的真 task id + 回读的 task 行（kind=work_item）+ description 里的证据 ref（target id / asset）。 - healthy 路径：明确"无异常、未开 task"，附巡检覆盖了哪些目标（pods/tasks/errors 计数）作为扫过的证明。
不许：healthy 时凭空造 bug task（假阳）· bug task 无证据 ref（空口判红）· 断言聊天文本而非真 task 行 · 拿旧 bundle 当本轮证据 · 把已知噪声 warn 当异常刷 task · 把巡检产物写进 /tmp 或跑完就删（证据必须留到判据读盘之后）· 只扫一两个信号面就宣布全绿（五面各自一行，缺一行判红）。
调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
执行本 skill 的第一步，先落一条调用回执：
bashcloud 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 诚实标注）。
