Files
2026-11-16 17:26:44 -08:00

100 lines
8.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: streamline-retro
description: "回溯调试 Streamline 平台上的某个 Feature / Bugfix / Security 任务:给一个 task id(或粘贴的面板 URL),把该任务的全部产物(记录、TestSpec、ImplReport、session 日志时间线、证据、复核历史、可读性报告)拉到本地并定位原因。Use when the user pastes a streamline/bbbbbbug task uuid, or asks 为什么这个任务失败 / 这个 feature 为什么没实现 / 看下这个任务的日志·证据·报告·复核意见 / 回溯 debug / retro debug a task."
---
# Streamline 任务回溯调试
用户给一个 id 就够了。目标是在**一次抓取**之后,用本地文件回答"当时发生了什么、为什么是这个结果"。
## 前提
- 数据源是控制面的只读 API:`https://streamline-internal-api.bytedance.net`(可用 `STREAMLINE_API` 覆盖)。
需要公司内网;不需要 token、不需要 DB 账号密码、不需要 SSH 到卫星。
- **全程只读**。本 skill 只发 GET。任何写操作(重跑、abort、改 plan、发 MR)都不属于回溯,要做请显式征得用户同意后走面板或另行确认。
## 流程
### 1. 抓取
```bash
bash .claude/skills/streamline-retro/fetch.sh <id> [--out DIR] [--evidence]
```
- `<id>` 接受裸 uuid,也接受粘贴的 URL(`…?task_id=<uuid>`、`…/features/<uuid>`)——脚本自己抠 uuid。
- 脚本自动判定这个 id 是 **feature / task(bug) / security / verification(验证) / prototype(原型)** 中的哪一种(依次探测,404 就换下一个),并按类型选对报告端点(验证另存 `audit-report.json` 结构化报告数据)。
- 每一批的 session / timing / runner 日志都落到 `logs/`。接口把单个文件截在 **8 MB**(尾部),长任务(4 小时的走查有 30–60 MB)会被截断 —— 脚本发现接口给的比节点上的文件短,就用 `scp <节点别名>:<工作区>/logs/<文件>` 只读拷完整的一份(要能 `ssh <节点>`;连不上就保留截断版并在摘要里标出,`--no-ssh` 关掉)。
- `--out` 缺省是 `$TMPDIR/streamline-retro/<id>`。**在 Claude Code 里请显式传 scratchpad 目录**。
- `--evidence` 额外把证据里的**图片**下载到 `evidence/`(最多 40 张),之后可以用 Read 直接看图。视频不下载,用 `evidence.json` 里的 URL。
- stdout 末尾会打印 `OUT=<目录>` 和 `KIND=<features|tasks|security>`,以及每个产物的 HTTP 码(**404 表示该任务本来就没有这个产物,不是故障**)。
### 2. 压缩 session 日志
`session.jsonl` 是 claude stream-json,动辄 3–5 MB,其中 95% 是 thinking 签名和重复的工具输出,**不要直接 Read**。先压成时间线:
```bash
bun .claude/skills/streamline-retro/digest.ts <OUT>/session.jsonl # → session-timeline.md
bun .claude/skills/streamline-retro/digest.ts <OUT>/eval.jsonl # 若存在(评估期日志)
```
产出 `*-timeline.md`(实测 3.5 MB → 59 KB):头部是统计 + **把所有报错的工具调用提到最前面**,然后是按序的 `🔧 工具调用 / ↩︎ 结果摘要 / 💬 助手正文 / ❌ 报错 / 💭 思考`,每条带 `[#N]` 事件序号。
需要看某处完整上下文时,用 `--full` 重跑,或直接 `grep -n` 原始 `session.jsonl` 的第 N 行。
### 2b. 成本与效率画像
```bash
python3 .claude/skills/streamline-retro/stats.py <OUT>/logs/session-rN.log <OUT>/logs/session-rN.timing.jsonl
```
模型、每段会话的上下文起止 / 峰值、token 用量与按标价的估算花费、工具结果按类别的体量占比(截图占多少)、工具执行 vs 思考时长、写死的 sleep、撞 120 秒超时次数。问「这一单花了多少 / 慢在哪 / 上下文为什么这么大」时先跑它。
### 3. 按问题类型选读
抓下来的目录布局:
| 文件 | 内容 | 什么时候读 |
|---|---|---|
| `fetch-summary.txt` | 状态 / 轮次 / 执行节点 / 分支 / MR / failureReason | **永远先读这个** |
| `meta.json` | 完整记录(已剔除 readableReportHtml) | 要看时间戳、watchers、lang、portSourceId 等字段 |
| `OriginalIntro.md` | 原始需求(Meego/PRD 正文已内联) | 判断"是不是理解错了需求" |
| `TestSpec.md` | 人工确认过的实现方案(权威) | 判断"是不是方案本身就有问题" |
| `ImplReport.md` / `FixReport.md` / `SecurityReport.md` | Agent 自述:实现摘要、验收对照、**方案权衡**、**验证局限** | 查"它自己承认哪里没做到"——找原因优先看这两节 |
| `session-timeline.md` | 执行过程 | 查"它到底试了什么、卡在哪一步" |
| `review-history.json` | 历次复核意见(含人工 reviewFeedback) | 查"为什么被打回、打回了几轮" |
| `asking.json` | 执行期人↔Agent 的问答 | 查"中途有没有人给过额外指令" |
| `evidence.json` | 证据文件清单 + TOS 下载 URL | 挑图看;配合 ImplReport 的「测试图清单」对照 |
| `readable-report.html` | 给 PM/复核看的图文报告 | 想快速拿结论而非过程 |
### 4. 常见问法 → 直接去哪儿
- **"为什么没实现 / 为什么失败"** → `fetch-summary.txt` 的 `failure` + `ImplReport.md` 的「验证局限」「方案权衡」+ `session-timeline.md` 头部的报错区。三者交叉。
- **"为什么被打回"** → `review-history.json` + `meta.json` 的 `reviewFeedback`。
- **"它改了什么"** → `ImplReport.md` 的「实现摘要」+ `meta.json` 的 `branchName` / `mrUrl`(要看 diff 就去 MR)。
- **"证据够不够真"** → `ImplReport.md` 的「验收对照」逐条看是否标注了机制级;再对 `evidence.json` 里的 `mech-*` 文件核对。
- **"在哪台机器跑的"** → `fetch-summary.txt` 的 `node`(排查环境类问题时必看:iOS 走 `fei-ios-*`)。
## 已知限制(回答时要如实说明,不要脑补)
- `session.jsonl` 走的是控制面的 **tail** 接口,默认拿到的是**最新一批**。
- **2026-08-13 之后开跑的批次**按批分文件(`session-r{N}.log`),可以逐批取:
`GET /api/{tasks|features|security}/<id>/logs` 列出 `logs/` 下所有文件(含每批的 `critic-N.log`、`task-context-N.json`),
`GET …/logs/<name>?lines=2000` 取其中一份,`GET …/log-file?round=N` 直接取第 N 批。
- **在那之前跑的多轮任务**仍然只剩最后一批(旧代码每批截断重写同一个 `session.log`),早期批次的过程**已经不存在了**,不要脑补,也不要说"在别处"。
- 不依赖节点的那一层是 `GET …/round-digests`:每批的会话摘要(失败过的命令、报错、动过的文件、终止哨兵),存在 DB 里,节点离线/工作区被清也还在。同样只覆盖归档能力上线之后跑的批次。
- `eval.jsonl`(评估期 / TestSpec 生成过程)对**已完成**的任务基本都是 404——`evalLogPath` 跑完就被清空了。只有还在评估中或刚评估完的任务能拿到。新任务的每次评估 / 计划重生成各自落 `eval-r{N}.log`,可以在 `logs` 清单里看到有几次。
- 工作区被清理过 / 任务被删过的老任务,`fix-report`、`log-file`、`evidence` 都会 404,但 `meta.json` 和 `readable-report` 仍在(它们存 DB)。
- 任务硬绑定 home node;节点离线时所有走代理的产物端点都会失败——此时 `fetch-summary.txt` 里 DB 字段仍然正常,别误判成"任务没跑"。
- 跨任务的聚合查询("最近所有 iOS 失败的 feature")REST 给不了,需要直连 PG,见下。
## 需要跨任务聚合时
`/api/features`、`/api/tasks`、`/api/security` 返回全量列表,绝大多数聚合用 `jq` 在本地过滤即可,**优先走这条路**。
注意三者的包装键不同:`{features:[…]}`、`{tasks:[…], eval, currentId}`、`{security:[…]}`。
```bash
curl -sS -m 60 https://streamline-internal-api.bytedance.net/api/features \
| jq '[.features[] | select(.platform=="ios" and .status=="unfixable") | {id,title,failureReason}]'
```
只有列表接口确实不够时才考虑直连生产 PG(`DATABASE_URL` 在仓库 `.env`)。直连的规矩:**只允许 SELECT**,禁止任何 INSERT/UPDATE/DELETE/DDL,且必须先跟用户确认。