--- 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 [--out DIR] [--evidence] ``` - `` 接受裸 uuid,也接受粘贴的 URL(`…?task_id=`、`…/features/`)——脚本自己抠 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/`。**在 Claude Code 里请显式传 scratchpad 目录**。 - `--evidence` 额外把证据里的**图片**下载到 `evidence/`(最多 40 张),之后可以用 Read 直接看图。视频不下载,用 `evidence.json` 里的 URL。 - stdout 末尾会打印 `OUT=<目录>` 和 `KIND=`,以及每个产物的 HTTP 码(**404 表示该任务本来就没有这个产物,不是故障**)。 ### 2. 压缩 session 日志 `session.jsonl` 是 claude stream-json,动辄 3–5 MB,其中 95% 是 thinking 签名和重复的工具输出,**不要直接 Read**。先压成时间线: ```bash bun .claude/skills/streamline-retro/digest.ts /session.jsonl # → session-timeline.md bun .claude/skills/streamline-retro/digest.ts /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 /logs/session-rN.log /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}//logs` 列出 `logs/` 下所有文件(含每批的 `critic-N.log`、`task-context-N.json`), `GET …/logs/?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,且必须先跟用户确认。