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

8.1 KiB
Raw Permalink Blame History

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 里,节点离线/工作区被清也还在。同样只覆盖归档能力上线之后跑的批次。
  • 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,且必须先跟用户确认。