@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/validation/eval/report-commands.md

@@ -0,0 +1,220 @@
+# QoderWork 命令自动化测试框架 — 成果报告
+
+> 把 QoderWork 当被测系统:通过 CDP 自动注入命令、自动代答 AskUserQuestion、
+> 等 turn.finished、用 transcript 遥测出耗时构成报告。
+> 让 `/wl-*` 命令的"首回延迟 / 工具耗时 / 模型推理占比"可量化、可回归。
+
+## 组件
+
+| 文件 | 作用 | 状态 |
+|------|------|------|
+| `transcript_timing.py` | 解析 QoderWork transcript jsonl,算每轮命令耗时构成 | ✅ 真实 jsonl 验证通过 |
+| `qwork_harness.py` | CDP 注入命令 → 轮询提问自动代答 → 出报告 | ✅ 端到端实测通过 |
+
+两个文件都在 `.qoder/scripts/eval/` 下,纯 Python 3 + websocket-client,零其它依赖。
+
+---
+
+## transcript_timing.py — 计时引擎
+
+解析 `~/.qoderwork/logs/sessions/**/segments/*.jsonl`(QoderWork 遥测事件流),
+按 turn 聚合,产出每条命令的耗时构成:
+
+```
+[/wl-search    ]    61.4s  (首回12.41s, 工具3.28s/5.3%, 模型59.23s, 10次调用, 4轮迭代)
+  └ /wl-search 考勤
+```
+
+### 指标定义(对齐 QoderWork 遥测事件)
+
+| 指标 | 来源事件 | 含义 |
+|------|---------|------|
+| `duration_ms` | `turn.finished.data.duration_ms` | 权威总耗时(框架自报) |
+| `first_reply_s` | prompt → 首个 `model.response.completed` | 首次回复延迟 |
+| `tool_total_s` | Σ `tool.requested` ↔ `tool.execution.finished`(按工具名配对) | 工具执行总耗时 |
+| `model_total_s` | Σ `model.request.started` ↔ `.completed`(按 request_index) | 模型推理窗口 |
+| `by_tool` | 同上,按 tool_name 分桶 | 哪个工具最慢 |
+| `other_s` | duration - tool - model | 排队/框架开销 |
+
+### 关键事件类型(实测确认)
+
+```
+input.prompt.submitted   用户发命令 (data.text_preview 含命令文本)
+turn.started / .finished 一轮对话 (finished.duration_ms = 权威耗时)
+model.request.started    开始请求模型 (data.request_index)
+model.response.completed 模型返回 (data.request_index, data.stop_reason)
+tool.requested           模型请求调工具 (data.tool_name, data.args)
+tool.execution.finished  工具执行完 (data.tool_name, data.status)
+permission.requested     权限确认 (AskUserQuestion 在此渲染选项)
+permission.resolved      权限已决 (updated_args.answers 含用户答案)
+loop.iteration.started/finished  agent 内部迭代
+```
+
+### 用法
+
+```bash
+# 分析单个 jsonl
+python transcript_timing.py <jsonl文件>
+python transcript_timing.py <jsonl文件> --json      # 机器可读
+
+# 扫目录下所有 jsonl 汇总
+python transcript_timing.py <dir>
+```
+
+也被 harness 实时调用:`from transcript_timing import analyze`。
+
+---
+
+## qwork_harness.py — 自动化驱动
+
+### 流程
+
+```
+连 CDP(6529) → 清洗命令(修MSYS污染) → focus输入框 → Input.insertText注入
+  → Enter提交 → 等落盘 → 锁定session jsonl → 轮询:
+      ├─ find_unanswered_questions: 检测待答 AskUserQuestion
+      │     └─ pick_answer_option: 关键词打分选最全/最安全项
+      │     └─ answer_via_dom(点选项) / answer_via_text(兜底注入)
+      └─ turn.finished 出现 → analyze() 出报告
+```
+
+### AskUserQuestion 代答机制(实测 seq 验证)
+
+AskUserQuestion 在 transcript 里的真实生命周期:
+
+| seq | type | 含义 | harness 动作 |
+|-----|------|------|-------------|
+| N | `tool.requested` | 模型发起,args.questions=完整问题+选项 | — |
+| N+1 | `permission.requested` | UI 渲染选项卡 | **在此代答** |
+| N+2 | `permission.resolved` | answers 已填 | 表示已答,跳过 |
+| N+3 | `tool.execution.finished` | 工具结束 | — |
+
+- **tool_name 精确等于 `"AskUserQuestion"`**(大写驼峰),不是含 "ask"
+- 一个 AskUserQuestion 可含**多个 question**,每个都要答
+- `multiSelect: true` 的可多选
+- 答案在 `permission.resolved.data.updated_args.answers`(以 question 文本为 key)
+
+### 代答选择策略
+
+`pick_answer_option`:对每个 option 的 label+description 关键词打分
+
+- **PREFER**(加分):整体/全部/概览/web/管理端/默认/推荐/确认/继续
+- **AVOID**(减分):取消/否/cancel/停止
+- 兜底:偏第一项(通常是推荐项)
+- 可 `--auto-answer=N` 强制指定
+
+### 已修复的实战 bug
+
+1. **MSYS 路径污染** ⚠️ 关键
+   Git bash 会把 `/wl-search 考勤` 转成 `D:/.../Git/wl-search 考勤`(斜杠被吃成路径分隔)。
+   harness 内置清洗:检测到命令不以 `/wl-` 开头但含 `wl-` → 截断还原成 `/wl-xxx`。
+   **根因规避**:调用时不要让命令经过 bash argv,用文件/环境变量传。
+
+2. **session 切换失锁**
+   注入命令可能创建新 jsonl,harness 原先固定用注入前抓的 baseline jsonl → 永远等不到 turn.finished。
+   修复:提交后等落盘,重新锁定当前最新 session 作为监控目标;
+   轮询中检测到更新的 session 文件自动切换跟踪。
+
+3. **代答事件误判**
+   原先用 `tool_name 含 "ask"` + tool.execution.finished 判定,与真实事件名不符。
+   修复:改用 `permission.requested`(tool_name=="AskUserQuestion")检测待答,
+   `permission.resolved.updated_args.answers` 非空判定已答。
+
+4. **后台 review turn 干扰** ⚠️ P3 实测发现
+   QoderWork 每条用户命令跑完后,自动追加 `[SYSTEM: automated background review]`
+   后台审核 turn(也产生 turn.finished)。旧的 `baseline+1` 计数法把它误判成"命令完成",
+   导致命令还没真跑完就注入下一条 → 队列堆积、串台。
+   修复:turn 完成判定改为"匹配我注入命令的 prompt + 跳过系统后台 turn"
+   (`_is_system_prompt` 识别 SYSTEM/automated background/must be fulfilled)。
+
+5. **队列堆积保护** ⚠️ P3 实测发现
+   连续注入时若 QoderWork 正忙,命令进队列而非立即执行。
+   修复:注入前 `_ui_is_busy` 双重检测(UI 文字"处理中/队列" + transcript turn 配对),
+   忙则等待最多 120s,空闲才注入。
+
+6. **完成后空转不退出** ⚠️ P3 实测发现
+   检测到 turn.finished 后只 break 内层 for,没跳出外层 while → 每 2s 重复打印直到超时。
+   修复:完成判定后 `if new_turn_finished: break` 跳出 while。
+
+### 用法
+
+```bash
+# 基本(注意:命令含 / 在 bash 下会被 MSYS 污染, 见上)
+python qwork_harness.py "/wl-search 考勤"
+
+# 强制选项序号(0-based)
+python qwork_harness.py "/wl-prd-full 用户管理" --auto-answer=0
+
+# 只跑不代答(遇到提问就停)
+python qwork_harness.py "/wl-search 考勤" --no-answer
+
+# JSON 输出
+python qwork_harness.py "/wl-search 考勤" --json
+```
+
+---
+
+## 实测结果(2026-06-24)
+
+### 干净 session 单条验证 ✓
+
+```
+[harness] 注入命令: /wl-search 用电导入
+[harness][7s] 锁定我的命令 prompt: ...17:56:43...
+[harness][62s] ✓ 我的命令 turn.finished! (dur=55226ms)
+[result] wall=65.5s status=completed
+  命令耗时=55.23s 工具=1.3s 模型=54.0s
+```
+命令完成即退出,不再空转。核心链路全部验证通过。
+
+### 批量测试发现的问题(P3)
+
+批量跑只读命令时暴露了 QoderWork 的两类行为,harness 已针对修复:
+
+| 现象 | 根因 | 修复 |
+|------|------|------|
+| 命令进队列堆积 | 后台 review turn 的 finished 被误判为命令完成,提前注入下一条 | turn 判定跳过后台 turn(bug #4) |
+| harness 永久超时 | 完成后没跳出 while 循环 | 完成即 break(bug #6) |
+| 注入被挡 | QoderWork 正忙时新命令进队列 | 注入前等空闲(bug #5) |
+
+### 性能画像(来自真实 transcript)
+
+`/wl-search` 系列典型耗时构成:
+- 总耗时 12~118s(视关键词),其中**模型推理占 ~95%+**,工具 <5%
+- 首回延迟 ~12s,4 轮 agent 迭代,10 次 MCP 工具调用
+- 瓶颈在模型推理(连读多个文件 + 拼结果),不在工具执行
+
+---
+
+## 已知限制(P3 遗留)
+
+1. **污染 session 的 turn 归属判定**
+   单个 session 累积过多 turn(测试塞入 20+ 个)后,用户命令 turn 与后台 review turn
+   时序交织,`_is_system_prompt` 启发式可能误判归属,导致等不到 turn.finished 超时。
+   **规避**:测试用干净 session(新建对话);生产用单条注入。
+   **后续**:改用 turn.started↔finished 的 seq 严格配对替代"最近 prompt"启发式。
+
+2. **AskUserQuestion 选项卡 DOM 点击不生效**
+   QoderWork 选项卡是 React 组件,监听 pointer/mousedown 而非 click。
+   JS `.click()` 和 CDP `mousePressed` 都无法触发选择。
+   **影响**:代答的 DOM 策略(answer_via_dom)失效,会回退到文本注入(也未必生效)。
+   **后续**:研究 QoderWork 选项卡事件绑定,或用 CDP `Input.dispatchMouseEvent`
+   的完整 pointer 事件序列(mouseMoved+pointerDown+pointerUp)。
+
+3. **命令经 bash argv 会被 MSYS 污染**
+   `/wl-search` 在 Git bash 下被转成路径。harness 内置清洗能还原,但最稳是绕过 argv
+   (命令写在调用脚本里,或用环境变量)。
+
+---
+
+## 用法
+
+```bash
+# 推荐: 命令写在脚本里调用(避开 bash argv 污染)
+# 或直接 python qwork_harness.py "/wl-search 考勤" (注意 / 在 bash 下的转义)
+
+python qwork_harness.py "/wl-search 考勤"
+python qwork_harness.py "/wl-prd-full 用户管理" --auto-answer=0   # 强制选项序号
+python qwork_harness.py "/wl-search 考勤" --no-answer              # 不代答
+python qwork_harness.py "/wl-search 考勤" --json                   # JSON 输出
+```

package/templates/qoder/scripts/validation/eval/transcript_timing.py

@@ -0,0 +1,386 @@
+"""
+transcript_timing.py — QoderWork transcript jsonl 计时引擎 (P1)
+
+解析 ~/.qoderwork/logs/sessions/**/segments/*.jsonl, 算出每条命令(turn)的耗时构成:
+  - 首次回复延迟 (prompt.submitted → 首个 model.response.completed)
+  - 工具执行总耗时 (Σ tool.requested ↔ tool.execution.finished, 按 turn 内序号配对)
+  - AI 推理窗口 (model.request.started ↔ model.response.completed, 按 request_index)
+  - 按工具名分桶 (哪个工具最慢)
+  - 直接读 turn.finished.data.duration_ms 作为权威总耗时
+
+QoderWork transcript 是遥测事件流, 每行: {ts, seq, level, type, data}
+关键事件类型:
+  input.prompt.submitted   用户真正发出一条命令 (data.text_preview 含命令文本)
+  turn.started / .finished 一轮 agent 对话 (finished.data.duration_ms = 权威耗时)
+  tool.requested           模型请求调用工具 (data.tool_name, data.args)
+  tool.execution.finished  工具执行完 (data.tool_name, data.status)
+  model.request.started    开始请求模型 (data.request_index)
+  model.response.completed 模型返回 (data.request_index, data.stop_reason)
+
+纯函数, 零外部依赖。既能分析历史 transcript, 也被 harness 实时调用。
+
+用法:
+  python transcript_timing.py <jsonl文件路径>
+  python transcript_timing.py <jsonl文件路径> --json     # 机器可读
+  python transcript_timing.py <dir>                       # 扫目录下所有 jsonl 汇总
+  from transcript_timing import analyze; analyze(path)
+"""
+import json
+import re
+import sys
+import os
+import glob
+from datetime import datetime
+
+
+# ── 时间戳解析: QoderWork ts 为 ISO-8601 字符串 (带时区) ─────────────
+def _parse_ts(ts):
+    if ts is None:
+        return None
+    if isinstance(ts, (int, float)):
+        # epoch-ms?
+        if ts > 1e12:
+            return float(ts) / 1000.0
+        return float(ts)
+    if isinstance(ts, str):
+        s = ts.strip()
+        if not s:
+            return None
+        try:
+            return datetime.fromisoformat(s.replace("Z", "+00:00")).timestamp()
+        except ValueError:
+            try:
+                return datetime.fromisoformat(s).timestamp()
+            except ValueError:
+                return None
+    return None
+
+
+def _dur(a, b):
+    """安全算时差(秒), 任一为空返回 None; b<a 时返回 0。"""
+    if a is None or b is None:
+        return None
+    d = b - a
+    return d if d >= 0 else 0.0
+
+
+# ── 命令名提取 ────────────────────────────────────────────────────────
+# QoderWork 的命令有两种出现形式:
+#   1) 用户直接输入:  /wl-search 考勤         → /wl-search
+#   2) skill 包装文本: "wl-search" skill ...   → /wl-search (补斜杠归一化)
+_CMD_SLASH_RE = re.compile(r"/wl-[a-z][a-z-]*")
+_CMD_QUOTED_RE = re.compile(r"[\"']wl-([a-z][a-z-]*)[\"']")
+
+
+def _extract_command(text):
+    if not text:
+        return None
+    # 优先斜杠形式
+    m = _CMD_SLASH_RE.search(text)
+    if m:
+        return m.group(0)
+    # 再认引号包裹的 "wl-xxx"
+    m = _CMD_QUOTED_RE.search(text)
+    if m:
+        return "/wl-" + m.group(1)
+    return None
+
+
+def _short_text(text, n=60):
+    if not text:
+        return ""
+    text = text.replace("\n", " ").strip()
+    return text[:n] + ("…" if len(text) > n else "")
+
+
+# ── 核心分析 ────────────────────────────────────────────────────────
+def analyze(path, command_hint=None):
+    """分析单个 transcript jsonl, 返回耗时报告 dict。
+
+    一个 jsonl 可能含多个 turn(多条命令), 按 turn 聚合返回 per_turn 列表 + 汇总。
+
+    Returns:
+        {
+            "file": "...",
+            "turns": [
+                {
+                    "command": "/wl-search",
+                    "prompt_preview": "用电导入...",
+                    "submitted_ts": "...",
+                    "duration_ms": 247859,         # turn.finished 权威值
+                    "duration_s": 247.86,
+                    "first_reply_s": 8.18,         # prompt→首个模型返回
+                    "tool_total_s": 12.3,
+                    "model_total_s": 100.5,        # Σ 推理窗口
+                    "tool_pct": 4.9,
+                    "model_pct": 40.5,
+                    "tool_calls": 33,
+                    "by_tool": {"Bash": {"count":20,"total_s":8.1,"max_s":2.3}},
+                    "num_turns": 33,               # agent 内部迭代次数
+                    "input_tokens": ..., "output_tokens": ...,
+                },
+                ...
+            ],
+            "summary": { ... 跨 turn 汇总 ... }
+        }
+    """
+    events = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    if not events:
+        return {"file": path, "turns": [], "summary": {"error": "空文件", "events": 0}}
+
+    # ── 1. 找所有 prompt.submitted 作为每轮起点 ─────────────────────
+    prompts = [e for e in events if e.get("type") == "input.prompt.submitted"]
+
+    # ── 2. 找所有 turn.finished 作为每轮权威终点 ────────────────────
+    turn_finished = [e for e in events if e.get("type") == "turn.finished"]
+    turn_started = [e for e in events if e.get("type") == "turn.started"]
+
+    turns = []
+    # 配对: 第 i 个 prompt 对应第 i 个 turn.started/finished (时序一致)
+    n_turns = min(len(prompts), len(turn_finished))
+
+    # 预收集工具 & 模型事件, 按时间窗口归到对应 turn
+    tool_req = [e for e in events if e.get("type") == "tool.requested"]
+    tool_fin = [e for e in events if e.get("type") == "tool.execution.finished"]
+    model_req = [e for e in events if e.get("type") == "model.request.started"]
+    model_fin = [e for e in events if e.get("type") == "model.response.completed"]
+
+    for i in range(n_turns):
+        p = prompts[i]
+        p_data = p.get("data", {}) or {}
+        p_ts = _parse_ts(p.get("ts"))
+
+        tf = turn_finished[i]
+        tf_data = tf.get("data", {}) or {}
+        tf_ts = _parse_ts(tf.get("ts"))
+
+        ts_start = turn_started[i].get("ts") if i < len(turn_started) else None
+        start_ts = _parse_ts(ts_start)
+
+        # 命令名
+        cmd = command_hint or _extract_command(p_data.get("text_preview", ""))
+
+        # 本 turn 时间窗口 [p_ts, tf_ts]
+        win_lo = p_ts
+        win_hi = tf_ts
+
+        # ── 工具配对: 窗口内的 tool.requested ↔ 同 turn 的 execution.finished ──
+        # 同名连续: 用栈式配对(先进先出)
+        req_queue = {}  # {tool_name: [ts,...]}
+        by_tool = {}
+        tool_calls = 0
+        tool_total = 0.0
+
+        for e in tool_req:
+            t = _parse_ts(e.get("ts"))
+            if win_lo is not None and (t is None or t < win_lo):
+                continue
+            if win_hi is not None and t is not None and t > win_hi:
+                break
+            d = e.get("data", {}) or {}
+            name = d.get("tool_name", "?")
+            req_queue.setdefault(name, []).append(t)
+
+        for e in tool_fin:
+            t = _parse_ts(e.get("ts"))
+            if win_lo is not None and (t is None or t < win_lo):
+                continue
+            if win_hi is not None and t is not None and t > win_hi:
+                break
+            d = e.get("data", {}) or {}
+            name = d.get("tool_name", "?")
+            q = req_queue.get(name)
+            if not q:
+                continue
+            req_ts = q.pop(0)
+            dur = _dur(req_ts, t)
+            if dur is None:
+                continue
+            b = by_tool.setdefault(name, {"count": 0, "total_s": 0.0, "max_s": 0.0})
+            b["count"] += 1
+            b["total_s"] += dur
+            b["max_s"] = max(b["max_s"], dur)
+            tool_calls += 1
+            tool_total += dur
+
+        # ── 模型推理窗口: request.started ↔ response.completed (按 request_index) ──
+        model_total = 0.0
+        first_reply = None
+        # 窗口内按 request_index 配对
+        req_idx_ts = {}
+        for e in model_req:
+            t = _parse_ts(e.get("ts"))
+            if win_lo is not None and (t is None or t < win_lo):
+                continue
+            if win_hi is not None and t is not None and t > win_hi:
+                break
+            d = e.get("data", {}) or {}
+            ri = d.get("request_index")
+            if ri is not None:
+                req_idx_ts[ri] = t
+        for e in model_fin:
+            t = _parse_ts(e.get("ts"))
+            if win_lo is not None and (t is None or t < win_lo):
+                continue
+            if win_hi is not None and t is not None and t > win_hi:
+                break
+            d = e.get("data", {}) or {}
+            ri = d.get("request_index")
+            if ri in req_idx_ts:
+                dur = _dur(req_idx_ts[ri], t)
+                if dur is not None:
+                    model_total += dur
+                    if first_reply is None:
+                        first_reply = dur  # 首个模型返回 = 首次回复
+
+        # 若没有 model 窗口数据, 回退: prompt→首个 tool.requested
+        if first_reply is None and tool_req:
+            for e in tool_req:
+                t = _parse_ts(e.get("ts"))
+                if win_lo is not None and (t is None or t < win_lo):
+                    continue
+                if win_hi is not None and t is not None and t > win_hi:
+                    break
+                first_reply = _dur(p_ts, t)
+                break
+
+        # 权威总耗时
+        dur_ms = tf_data.get("duration_ms")
+        dur_s = dur_ms / 1000.0 if dur_ms is not None else _dur(p_ts, tf_ts)
+
+        # AI 排队/其它 = 总 - 工具 - 模型推理
+        other_s = None
+        if dur_s is not None:
+            other_s = dur_s - tool_total - model_total
+            if other_s < 0:
+                other_s = 0.0
+
+        by_tool_clean = {
+            name: {"count": b["count"], "total_s": round(b["total_s"], 2), "max_s": round(b["max_s"], 2)}
+            for name, b in sorted(by_tool.items(), key=lambda x: -x[1]["total_s"])
+        }
+
+        turns.append({
+            "command": cmd or "(未知)",
+            "prompt_preview": _short_text(p_data.get("text_preview", "")),
+            "submitted_ts": p.get("ts"),
+            "finished_ts": tf.get("ts"),
+            "duration_ms": dur_ms,
+            "duration_s": round(dur_s, 2) if dur_s is not None else None,
+            "first_reply_s": round(first_reply, 2) if first_reply is not None else None,
+            "tool_total_s": round(tool_total, 2),
+            "model_total_s": round(model_total, 2),
+            "other_s": round(other_s, 2) if other_s is not None else None,
+            "tool_pct": round(tool_total / dur_s * 100, 1) if dur_s else None,
+            "model_pct": round(model_total / dur_s * 100, 1) if dur_s else None,
+            "tool_calls": tool_calls,
+            "by_tool": by_tool_clean,
+            "num_turns": tf_data.get("num_turns"),
+            "reason": tf_data.get("reason"),
+            "input_tokens": tf_data.get("input_tokens"),
+            "output_tokens": tf_data.get("output_tokens"),
+            "model": (turn_started[i].get("data", {}) or {}).get("model") if i < len(turn_started) else None,
+        })
+
+    # ── 汇总 ────────────────────────────────────────────────────────
+    summary = {
+        "events": len(events),
+        "turns": len(turns),
+        "total_duration_s": round(sum(t["duration_s"] for t in turns if t["duration_s"]), 2),
+        "total_tool_s": round(sum(t["tool_total_s"] for t in turns), 2),
+        "total_model_s": round(sum(t["model_total_s"] for t in turns), 2),
+        "avg_turn_s": None,
+        "slowest_turn": None,
+    }
+    if turns:
+        ds = [t["duration_s"] for t in turns if t["duration_s"]]
+        if ds:
+            summary["avg_turn_s"] = round(sum(ds) / len(ds), 2)
+            slow = max(turns, key=lambda t: t["duration_s"] or 0)
+            summary["slowest_turn"] = {
+                "command": slow["command"],
+                "duration_s": slow["duration_s"],
+                "prompt_preview": slow["prompt_preview"],
+            }
+        # 跨 turn 工具汇总
+        agg_tool = {}
+        for t in turns:
+            for name, b in t["by_tool"].items():
+                a = agg_tool.setdefault(name, {"count": 0, "total_s": 0.0, "max_s": 0.0})
+                a["count"] += b["count"]
+                a["total_s"] += b["total_s"]
+                a["max_s"] = max(a["max_s"], b["max_s"])
+        summary["by_tool"] = {
+            name: {**b, "total_s": round(b["total_s"], 2), "max_s": round(b["max_s"], 2)}
+            for name, b in sorted(agg_tool.items(), key=lambda x: -x[1]["total_s"])
+        }
+
+    return {"file": os.path.basename(path), "turns": turns, "summary": summary}
+
+
+# ── 人类可读报告 ──────────────────────────────────────────────────────
+def _format_report(r):
+    lines = []
+    s = r["summary"]
+    if "error" in s:
+        return f"[错误] {s['error']}"
+    lines.append(f"文件: {r['file']}")
+    lines.append(f"事件数: {s['events']}  |  turn数: {s['turns']}")
+    lines.append(f"总耗时: {s['total_duration_s']}s  |  平均/turn: {s.get('avg_turn_s')}s")
+    if s.get("slowest_turn"):
+        st = s["slowest_turn"]
+        lines.append(f"最慢turn: {st['command']} {st['duration_s']}s — {st['prompt_preview']}")
+    lines.append(f"工具耗时合计: {s['total_tool_s']}s  |  模型推理合计: {s['total_model_s']}s")
+    if s.get("by_tool"):
+        lines.append("")
+        lines.append("工具分桶(全部turn):")
+        for name, b in list(s["by_tool"].items())[:12]:
+            lines.append(f"  {name:25s} ×{b['count']:3d}  共{b['total_s']:7.1f}s  最慢{b['max_s']:6.1f}s")
+    lines.append("")
+    lines.append("各 turn 明细:")
+    for t in r["turns"]:
+        lines.append(f"  [{t['command']:14s}] {t['duration_s']:7.1f}s  "
+                     f"(首回{t['first_reply_s']}s, 工具{t['tool_total_s']}s/{t.get('tool_pct')}%, "
+                     f"模型{t['model_total_s']}s, {t['tool_calls']}次调用, {t['num_turns']}轮迭代)")
+        lines.append(f"    └ {t['prompt_preview']}")
+    return "\n".join(lines)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("用法: python transcript_timing.py <jsonl|dir> [--json]")
+        sys.exit(1)
+    target = sys.argv[1]
+    as_json = "--json" in sys.argv
+
+    if os.path.isdir(target):
+        files = sorted(glob.glob(os.path.join(target, "**", "*.jsonl"), recursive=True))
+        results = [analyze(f) for f in files]
+        if as_json:
+            print(json.dumps(results, ensure_ascii=False, indent=2))
+        else:
+            for r in results:
+                if r["summary"].get("turns"):
+                    print(_format_report(r))
+                    print("\n" + "=" * 70 + "\n")
+        return
+
+    r = analyze(target)
+    if as_json:
+        print(json.dumps(r, ensure_ascii=False, indent=2))
+    else:
+        print(_format_report(r))
+
+
+if __name__ == "__main__":
+    main()