8.1 KiB
8.1 KiB
name, description
| name | description |
|---|---|
| streamline-retro | 回溯调试 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 .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。先压成时间线:
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. 成本与效率画像
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 里,节点离线/工作区被清也还在。同样只覆盖归档能力上线之后跑的批次。
- 2026-08-13 之后开跑的批次按批分文件(
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:[…]}。
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,且必须先跟用户确认。