Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

feat(agent-observability): add local observability dashboard for devflow runs (#12)

Luchen Hao0d7ef7974dea
diff --git a/.claude/skills/agent-observability/SKILL.md b/.claude/skills/agent-observability/SKILL.md
new file mode 100644
index 00000000..8bff9f0c
--- /dev/null
+++ b/.claude/skills/agent-observability/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: agent-observability
+description: Add or maintain CodeBuddy hook observability for projects that need local metrics for tool latency, transcript token usage, session cost, and multi-agent trace attribution. Use when wiring hook-based telemetry, debugging missing usage events, and validating AgentLens state.
+---
+
+## Workflow
+
+1. Merge `templates/settings-hook.json` into the user or project `settings.json`.
+2. Keep hook entries command-only and keep timeouts around 5 to 10 seconds.
+3. Run a normal CodeBuddy session and inspect `logs/metrics.ndjson`.
+4. Inspect `logs/.state.json` when usage replay, offsets, or AgentLens turn state look wrong.
+5. Keep the runtime generic and verify output from `metrics.ndjson` and `.state.json`.
+
+## Read Next
+
+- Read `references/quickstart.md` for setup and smoke-test steps.
+- Read `references/schema-v2.md` when you need field definitions or sidecar state shape.
+## Key Files
+
+- `scripts/main.py`: hook entrypoint for `session-start`, `user-prompt-submit`, `pre`, `post`, and `stop`
+- `scripts/run_hook.sh`: stable shell wrapper for CodeBuddy hook commands
+- `scripts/core/collector.py`: transcript parsing, pre/post pairing, and session usage recording
+- `scripts/core/agentlens.py`: AgentLens trace emission and agent or step grouping
+- `scripts/core/state.py`: persisted hook state, offsets, and AgentLens sidecar state
+- `scripts/core/devflow.py`: optional devflow-awareness — detects a `multi-agents-devflow-*` team, reads `workflow-state.json`, and emits `stage_transition` events. No-ops entirely on non-devflow projects.
+- `templates/settings-hook.json`: hook wiring template
+
+## Output Contract
+
+- Always emit `event`, `sid`, and `ts`.
+- Emit `tool` for per-call latency and `usage` for transcript-derived token and cost events.
+- Emit `stop` for end-of-session flush.
+- Never block the main hook flow; hook exits must stay `0`.
diff --git a/.claude/skills/agent-observability/config/pricing.json b/.claude/skills/agent-observability/config/pricing.json
new file mode 100644
index 00000000..59d8e58c
--- /dev/null
+++ b/.claude/skills/agent-observability/config/pricing.json
@@ -0,0 +1,39 @@
+{
+ "claude-opus-4.8": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.7": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.6": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-sonnet-4.6": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4.5": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-7-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-5-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-haiku-4.5": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-3-5-haiku": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-haiku-4": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "gpt-5.5-fast": {"input": 12.5, "output": 75.0, "cache_read": 1.25, "cache_write": 12.5},
+ "gpt-5.5": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4-fast": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4": {"input": 2.5, "output": 15.0, "cache_read": 0.25, "cache_write": 2.5},
+ "gpt-5.3-codex": {"input": 1.75, "output": 14.0, "cache_read": 0.175, "cache_write": 1.75},
+ "gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25, "cache_write": 2.5},
+ "gpt-4o-mini": {"input": 0.15, "output": 0.6, "cache_read": 0.075, "cache_write": 0.15},
+ "gemini-3.5-flash": {"input": 1.5, "output": 9.0, "cache_read": 0.15, "cache_write": 1.5},
+ "gemini-3.1-pro": {"input": 2.0, "output": 12.0, "cache_read": 0.2, "cache_write": 2.0},
+ "gemini-3.1-flash-lite": {"input": 0.25, "output": 1.5, "cache_read": 0.025, "cache_write": 0.25},
+ "gemini-3-flash": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "gemini-2": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "glm-5.1": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "glm-5v-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "kimi-k2.6": {"input": 0.929, "output": 3.857, "cache_read": 0.157, "cache_write": 0.929},
+ "kimi-k2.5": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "kimi": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "deepseek-v4-pro": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek-v4-flash": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "deepseek-v4": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "minimax-m2.7": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3},
+ "minimax": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3}
+}
diff --git a/.claude/skills/agent-observability/logs/.gitkeep b/.claude/skills/agent-observability/logs/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/.claude/skills/agent-observability/references/quickstart.md b/.claude/skills/agent-observability/references/quickstart.md
new file mode 100644
index 00000000..4a667772
--- /dev/null
+++ b/.claude/skills/agent-observability/references/quickstart.md
@@ -0,0 +1,195 @@
+## Quickstart
+
+### 安装
+
+将 `templates/settings-hook.json` 合并到 `~/.claude/settings.json` 或 `<project>/.claude/settings.json`。
+
+必须启用 hooks:`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`。
+
+### 查看输出
+
+完成一次正常会话后检查:
+- `.claude/skills/agent-observability/logs/metrics.ndjson`
+- `.claude/skills/agent-observability/logs/.state.json`
+
+### 指定数据源路径(可选)
+
+`build_dashboard_data.py` 默认从 `<skill_root>/logs/metrics.ndjson` 与 `<skill_root>/logs/.state.json` 读取,**不传参数时行为完全不变**。
+
+如需从其它位置读取,可用 `--metrics-path` / `--state-path` 覆盖:
+
+```bash
+python3 scripts/build_dashboard_data.py \
+ --metrics-path ~/Downloads/metrics.ndjson \
+ --state-path ~/Downloads/.state.json \
+ --out dashboard/dashboard-data.json
+```
+
+注意:
+
+- 两个参数都留空(或省略)时回退到 `<skill_root>/logs/` 下的默认文件。
+- 路径支持 `~` 展开(如上例的 `~/Downloads/...`)。
+- 输出 `dashboard-data.json` 的 `source.metrics_ndjson` / `source.state_json` 会**如实反映实际读取到的路径**,覆盖后自然指向你给定的文件,便于核对数据来源。
+
+重点字段:
+- `event=tool`:工具耗时、`skill`、`rule`
+- `event=usage`:`tokens`、`model`、`cost_usd`
+- `event=stop`:会话尾部 flush 与总成本
+
+### 导出最慢的工具调用(可选)
+
+`--top-slow N` 会在生成 `dashboard-data.json` 的同时,额外在**终端**打印耗时最长的 N 次 `event=tool` 调用(工具名 + 耗时 ms,按耗时降序)。排查"哪次工具调用拖慢了会话"时不用再去翻原始 ndjson。
+
+```bash
+python3 scripts/build_dashboard_data.py --top-slow 5
+```
+
+输出示例(排在 `wrote ...` 之后):
+
+```
+top-slow 5 tool calls (by ms):
+ 1. Bash 4820ms
+ 2. Grep 1230ms
+ 3. Read 310ms
+```
+
+注意:
+
+- **默认不开启**:不传该参数时不会打印任何额外内容,原有输出一字不变。
+- **只读**:结果只打印到终端,不会写进 `dashboard-data.json`——输出结构与不开时完全一致,看板不受影响。
+- 只统计 `event=tool` 事件;`ms` 缺失或非数字时按 `0` 兜底,与看板其它统计口径一致。
+- `N` 大于实际 tool 事件数时取全部,不报错;没有任何 tool 事件时不打印该段。
+
+### 自定义模型定价覆盖(可选)
+
+内置价格表 `config/pricing.json` 覆盖不到的模型(自部署模型、内部代号、刚发布还没来得及收录的模型),
+`cost_usd` 会算不出来。给这些模型补单价不用改内置文件——写一份**只含差异**的覆盖文件即可。
+
+**放哪**:默认 `<project_root>/.claude/agent-observability/pricing.overrides.json`
+(`<project_root>` 是 `.claude/` 所在的那一层,例如 `/Users/me/my-project`)。
+
+刻意放在 `skills/` 树**之外**,原因有三:
+
+- `scripts/build-classic-hosts.py` 会整棵同步 `.claude/skills` 到 `.claude/` `.cursor/`,
+ 放树内会让每次改动都产生 `--check` drift,还会把你的单价复制进生成的宿主包;
+- `config/pricing.json` 属于 skill 自带资产,后续更新会把它冲掉,覆盖文件不会;
+- 它是纯数据文件,删除或改名即可停用,不需要重启任何东西(hook 每次都是新进程)。
+
+**格式**:键是模型名(匹配时忽略大小写与首尾空格),值是要覆盖的字段。
+单位与 `config/pricing.json` 完全一致——**USD / 1M tokens**,可用字段只有四个:
+`input`、`output`、`cache_read`、`cache_write`。
+
+```json
+{
+ "my-model": { "output": 9.0 },
+ "gpt-4o": { "output": 99.0 }
+}
+```
+
+**合并是字段级的**:上面这份只改 `output`——`my-model` 的 `input`/`cache_read`/`cache_write`
+沿用内置值(内置表里没有 `my-model` 时,未覆盖的字段按 0 计),`gpt-4o` 的 `input` 仍是内置的 `2.5`。
+可以新增内置表里不存在的模型,但**不能删除**内置的模型或字段(合并只能加不能减)。
+
+**两个环境变量**(都支持 `~` 展开):
+
+| 环境变量 | 作用 | 优先级 |
+|---|---|---|
+| `AOBS_PRICES_PATH` | **替换**整张基础表(不再读内置 `config/pricing.json`) | 低 |
+| `AOBS_PRICING_OVERRIDES_PATH` | 在上面那张基础表之上**叠加**一份补丁,指向任意路径 | 高 |
+
+两者同时设置时,覆盖文件里的字段最终生效。
+
+> ⚠️ **只对新事件生效,不回溯**:`cost_usd` 在 hook 期就写进了 `metrics.ndjson`,
+> 补价之后只有**之后新产生**的 usage 事件按新价格计算,已经落盘的历史成本不会被重算。
+
+**出问题会静默降级**:覆盖文件不存在、JSON 非法、顶层不是对象、字段值不是数字,
+四种情况都自动退回纯内置价格表——不报错、不打印、hook 照常退出 0
+(否则一个手误的格式问题会让整条 hook 链路不可用)。所以"改了没生效"通常意味着文件没被读到,
+先跑一次诊断:
+
+```bash
+python3 - <<'PY'
+import sys
+sys.path.insert(0, "scripts")
+from core import emitter
+print("path :", emitter.resolve_overrides_path())
+print("loaded :", emitter.load_price_overrides())
+print("gpt-4o :", emitter.load_prices().get("gpt-4o"))
+PY
+```
+
+`path` 是实际读取的位置(不是你以为的那个),`loaded` 为空说明文件没读到或全被判为坏字段。
+
+**看板上的提示**:「建议关注」卡片第 4 条「模型定价」会列出**完全没命中价格表**的模型
+(模型名 + 缺少成本的 usage 事件数)。模糊匹配(最长子串)命中的模型能算出成本,不会出现在里面。
+处置方式就是把该模型写进覆盖文件;所有模型都有价时这条显示 green。
+
+### 常见问题
+
+- 没有日志:检查 hook 命令路径。
+- `ms` 为空:通常是 pre/post 未配对。
+- 没有 `usage`:`transcript_path` 缺失、tail 无 usage,或增量已去重。
+- AgentLens 未启用:检查 `.state.json` 的 `_agentlens.enabled` / `last_error`。
+
+### 已知问题(未修复)
+
+- **工具失败事件的 `raw_response` 经常缺失(PostToolUse 与 transcript 落盘之间的时序竞争)**:
+ 真实 CodeBuddy CLI 场景下实测复现过——一次会故意制造失败的 `Bash` 调用(`exitCode=1`,
+ transcript 里 `function_call_result.providerData.toolResult.rawResponse` 确实带了
+ `is_error:true`/`exitCode:1`/`tool_error_code`),但最终写进 `metrics.ndjson` 的
+ `tool` 事件的 `tool_details` 里完全没有 `raw_response` 字段。
+ 用实测时间戳定位到根因:PostToolUse hook 记录这次调用的时间是 `ts=...396.524`,
+ 但 transcript 里 `function_call_result` 真正落盘的时间是 `timestamp=...396.609`——
+ **晚了 85ms**。hook 触发时去扫 transcript 文件的那一刻,CLI 还没来得及把执行结果
+ 那条记录写盘,`find_current_tool_context()`(`core/collector.py`)只能看到
+ `function_call`(请求),看不到 `function_call_result`(结果)。已经单独验证过
+ `merge_tool_records()` / `tool_details_from_record()` 的合并逻辑本身没问题——
+ 只要数据真的已经在文件里,能正确解析出完整 `raw_response`;问题纯粹是读的时机
+ 比 CLI 写盘早了一步。`collect_transcript_entries()` 用的是持久化的增量字节 offset
+ 游标,错过这次窗口后不会在后续调用里回头补扫,所以这次机会永久丢失,直接后果是
+ `build_dashboard_data.py` 的 `tool_call_failed()`(无论怎么改判定逻辑)都拿不到
+ 数据,"工具失败率"/`failures` 列表对这类快速失败调用会漏检。
+ 复现方式:让 CodeBuddy 执行一个必然快速失败的命令(如 `ls /path/does/not/exist`,
+ 越快的命令越容易复现,因为 hook 触发与 transcript 落盘之间的竞争窗口更紧张),
+ 对比 `metrics.ndjson` 里该 `tool` 事件的 `tool_details.raw_response` 是否存在,
+ 和对应 transcript `.jsonl` 里 `function_call`/`function_call_result` 两条记录各自
+ 的 `timestamp` 先后。
+
+ **影响范围(已精确定位,不是猜测)**:`raw_response` 在 `build_dashboard_data.py`
+ 里只有两处消费者——`tool_call_failed()`(喂给 `build_daily_and_sessions()` 的
+ `day.failures` 计数和 `session.status`)和 `build_failures()`("工具失败面板"的
+ 数据源)。真实数据统计过:107 次 tool 事件里只有 2 次带 `raw_response`,且只有
+ `Bash` 调用会带这个字段(Read/Edit/Write/SendMessage 等其它工具从不带,不受
+ 此问题影响)。缺失时 `tool_call_failed()` 默认判"未失败",所以效果是**恒定
+ 漏报,不会误报**——工具失败率/失败面板/会话状态列显示的"正常"可能掩盖了真实
+ 发生过的 Bash 失败。turns、duration、dispatch、cost、token、skill/rule 命中、
+ devflow 阶段耗时、会话列表本身完全不受影响,是纯观测盲区,不影响 devflow 实际
+ 执行行为。
+
+ **三次修复尝试均已失败,均已回滚(详见下方"已尝试且已放弃的修复方向")**:
+ 真正阻塞方向 A 的证据很反常——三次独立测试里,预算从 160ms 加到 500ms 再加到
+ 2000ms,实测缺口每次都精确地"比预算多几十到一百多毫秒"(206/564/2151ms),
+ 不像是在等一个独立发生的固定延迟,更像是**hook 自己的同步等待在阻塞 CLI 落盘**
+ ——等得越久,结果来得越晚。这个因果关系还没验证清楚,在验证清楚之前,继续在
+ hook 里加同步等待大概率是死路,不建议再尝试。
+
+### 已尝试且已放弃的修复方向(供以后参考,避免重复踩坑)
+
+1. **方向 A:PostToolUse 里同步有界重试**(`claim=False` 轮询直到等到 `raw_response`
+ 或超时,只对 `tool_name=="Bash"` 生效)。三次真实端到端验证,预算 160ms/500ms/
+ 2000ms 全部失败,且"缺口≈预算+常数"的规律强烈暗示等待本身可能在拖慢 CLI
+ 落盘(见上文)。不建议在搞清楚这层因果关系之前继续加大预算。
+2. **方向 B:推迟到 `pending_tool_emits` 重试队列,下次 hook 触发或 session Stop
+ 时再补**(`claim=False` 探测 + 延后 `claim=True`,避免过早消费掉 call_id)。
+ 逻辑和单元测试都通过,但端到端验证暴露了一个更深的、独立于这次修复的既有
+ 架构问题:`find_current_tool_context()`(工具上下文查询)和
+ `emit_transcript_events()`(usage token 扫描)共用同一个持久化字节偏移游标
+ (`core/state.py` 里只按 `(sid, transcript_path)` 区分,不分用途)。
+ `emit_transcript_events()` 每次 `handle_post()` 都无条件推进这个游标,一旦
+ 推过某段内容,后续任何工具上下文重试在这段范围内都会**彻底找不到任何数据**
+ (不只是缺 `raw_response`,连 `call_id`/`arguments` 都没了)——比不修复更糟。
+ 真实验证过两次:两条端到端测试调用最终落盘时 `tool_details`完全是空的。
+ 要让方向 B 真正可行,必须先给工具上下文查询一个独立于 usage 扫描的游标,
+ 这是范围更大、需要认真设计的改动,还没有细化方案。
+
+以上两个方向的实现和回滚记录详见会话 memory(`project-agent-observability-raw-response-race`)。
diff --git a/.claude/skills/agent-observability/references/schema-v2.md b/.claude/skills/agent-observability/references/schema-v2.md
new file mode 100644
index 00000000..43b84e1c
--- /dev/null
+++ b/.claude/skills/agent-observability/references/schema-v2.md
@@ -0,0 +1,282 @@
+## Schema v2.3
+
+`agent-observability` 输出 `ndjson`,每行一个事件对象。
+
+> 以下字段表基于当前 `logs/metrics.ndjson` 的实际输出整理;其中“可选字段”只会在特定场景出现。
+
+### 通用字段
+
+- `event`: `start | user_prompt_submit | tool | usage | stop | error | stage_transition`
+- `sid`: session id
+- `ts`: 秒级时间戳(float)
+- `turn_id`: 可选;由 `UserPromptSubmit` 生成,贯穿本轮事件
+
+### Devflow 感知字段(可选,见 `core/devflow.py`)
+
+只有当前项目正在跑 `.claude/runtime` 描述的 multi-agents-devflow 工作流(存在
+`.claude/teams/multi-agents-devflow-{task_slug}/` team 目录)时才会出现,非
+devflow 项目完全不受影响:
+
+- `tool` / `usage` / `stop` 事件上会附带 `task_slug`(devflow 需求标识,用于把
+ main + 最多 7 个常驻角色跨事件串成"同一次运行";⚠️ `/resume-devflow` 中断恢复
+ 可能发生在新的 CodeBuddy 顶层 session 里,因此**聚合一次 devflow 运行要按
+ `task_slug` 分组,不能按 `sid` 分组**)与 `stage`(`workflow-state.json` 的
+ `current_stage`,如 `TASK-03`/`CODE-REVIEW`)。
+- `tool` 事件在能从 subagent transcript 文件名识别出并行 sub-developer 轨道时
+ (`sub-developer-PT-01` 这类命名)会额外带 `pt_id`(如 `"PT-01"`)。按事件自己的
+ transcript_path 推断,不依赖任何 session 级共享状态——并行轨道是真并发,不能
+ 用一个可变指针记"当前是哪条轨道"。
+
+### 事件字段
+
+| event | 实际顶层字段 | 说明 |
+|---|---|---|
+| `start` | `event`, `sid`, `agent`, `ts` | 会话开始 |
+| `user_prompt_submit` | `event`, `sid`, `agent`, `turn_id`, `prompt_len`, `ts` | 新 turn 边界;AgentLens 侧按 `1 Trace = 1 Turn` 生成 trace |
+| `tool` | `event`, `sid`, `agent`, `tool`, `ms`, `transcript_path`, `turn_id`, `ts`, `skill`, `rule`, `cwd`, `call_id`, `message_id`, `tool_details`, `task_slug`?, `stage`?, `pt_id`? | 工具调用与耗时 |
+| `usage` | `event`, `sid`, `agent`, `tool`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | transcript 增量 token / 模型 / 消息归属 |
+| `stop` | `event`, `sid`, `agent`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | 会话尾部 flush |
+| `error` | `event`, `sid`, `phase`, `error`, `x_traceback`, `ts` | hook 自身异常记录 |
+| `stage_transition` | `event`, `sid`, `task_slug`, `stage`, `status`?, `executor`?, `retry_count`?, `review_result`?, `ts` | devflow `workflow-state.json` 某个 stage 的 status/retry_count/review_result 发生变化时触发(仅 devflow 项目) |
+
+### 可选字段说明
+
+- `tool.ms`: Pre/Post 未成功配对时可能为 `null`
+- `tool.call_id`: 仅当工具调用存在 call id 时出现
+- `tool.message_id`: 仅当成功和 transcript 中的 message 关联上时出现
+- `tool.tool_details`: 仅当 transcript 中能还原出更细工具上下文时出现
+- `usage.message_id`: 仅当 usage 对应的 transcript message 可识别时出现
+- `usage.model`: transcript 中能识别模型名时出现
+- `usage.cost_usd`: 只有模型价格命中价格表时才会出现。价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认 `<project_root>/.claude/agent-observability/pricing.overrides.json`,可用 `AOBS_PRICING_OVERRIDES_PATH` 指定)的字段级合并结果;覆盖只对该文件写入**之后**产生的新事件生效,不回溯重算历史成本(见 `quickstart.md` 的「自定义模型定价覆盖」)
+- `stop.cost_usd`: 只有当前 stop 事件对应 usage 能估算成本时才会出现
+- `stop.cost_session_usd`: 只有 stop 汇总阶段能反算出整个 session 成本时才会出现
+
+### 完整示例
+
+换成更容易读的多行 JSON。下面仍然是当前 `metrics.ndjson` 里的实际数据,只是长文本字段做了截断。
+
+`start`
+
+```json
+{
+ "event": "start",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "ts": 1784015331.87806
+}
+```
+
+`user_prompt_submit`
+
+```json
+{
+ "event": "user_prompt_submit",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "turn_id": "turn-1784015342075",
+ "prompt_len": 136,
+ "ts": 1784015342.076438
+}
+```
+
+`usage`
+
+```json
+{
+ "event": "usage",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "tokens": {
+ "input": 31110,
+ "output": 594,
+ "cache_read": 3072,
+ "total": 31704
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.claude/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 17423,
+ "turn_id": "turn-1784015342075",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "ts": 1784015355.413464
+}
+```
+
+`tool` 调用参数型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "ms": null,
+ "transcript_path": "/Users/rachel/.claude/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015355.412617,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/Users/rachel/skillhub-tokentrack-mr/assets/devflow.defaults.yaml\"}",
+ "arguments_display_text": "assets/devflow.defaults.yaml"
+ }
+}
+```
+
+`tool` 返回结果型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 759,
+ "transcript_path": "/Users/rachel/.claude/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015356.071573,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "result_content": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .claude/teams/ ...<truncated>",
+ "raw_response": {
+ "exitCode": 1,
+ "signal": null,
+ "interrupted": false,
+ "sandboxDenied": false,
+ "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0,
+ "tool_error_code": "8002",
+ "is_error": true,
+ "error": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .claude/teams/ ...<truncated>"
+ },
+ "output_text": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .claude/teams/ ...<truncated>",
+ "original_message_id": "d187771c6eef4520a530564dd2a73e38",
+ "next_message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "message_id_reassigned": true
+ }
+}
+```
+
+`stop`
+
+```json
+{
+ "event": "stop",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "test-engineer",
+ "tokens": {
+ "input": 128290,
+ "output": 665,
+ "cache_read": 128192,
+ "total": 128955
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.claude/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 1157291,
+ "turn_id": "turn-1784015342075",
+ "message_id": "51e4fae9553d4d0995e7a599f3b2ef2d",
+ "ts": 1784018405.467215
+}
+```
+
+`error`
+
+```json
+{
+ "event": "error",
+ "sid": "6e8cd633-1a2f-4488-b1df-1eef168009c3",
+ "phase": "post",
+ "error": "AttributeError: module 'core.transcript_runtime' has no attribute 'transcript_path'",
+ "x_traceback": "Traceback ...<truncated>",
+ "ts": 1784183163.4314518
+}
+```
+
+`stage_transition`(仅 devflow 项目;见 `core/devflow.py`)
+
+```json
+{
+ "event": "stage_transition",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "task_slug": "fix-token-bypass_20260911_0900",
+ "stage": "CODE-REVIEW",
+ "status": "failed",
+ "executor": "code-reviewer",
+ "retry_count": 1,
+ "review_result": "failed",
+ "ts": 1784015412.223
+}
+```
+
+### tokens
+
+```json
+{"input": 1200, "output": 180, "cache_read": 9000, "cache_creation": 0, "total": 1380}
+```
+
+- `total`: 统一按 `input + output` 计算
+- `cache_read` / `cache_creation`: 保留给成本估算和缓存命中分析使用
+
+### tool_details
+
+`tool` 事件里的 `tool_details` 是一个可选嵌套对象,当前实现里可能包含:
+
+- `call_id`
+- `arguments`
+- `arguments_display_text`
+- `result_content`
+- `raw_response`
+- `output_text`
+- `original_message_id`
+- `next_message_id`
+- `message_id_reassigned`
+
+常见示例:
+
+```json
+{
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/path/to/file\"}",
+ "arguments_display_text": "path/to/file"
+}
+```
+
+### AgentLens sidecar
+
+`.state.json[sid]._agentlens` 只作为内部状态使用,核心字段:
+
+- `enabled`: AgentLens 上报是否可用
+- `last_error`: 最近一次降级原因
+- `current_turn.carrier.traceparent`: 当前 turn 的 trace context
+- `current_turn.subagent_spans`: 同一 turn 下的子 agent span carrier
+- `current_turn.agent_spans`: 同一 turn 下按 agent 聚合的 span carrier 与累计统计
+- `current_turn.step_spans`: `(agent, message_id)` 级 step span registry
+- `turn_history`: 已结束 turn 的摘要
+
+### Hook 接入
+
+参考 `templates/settings-hook.json`,必须启用:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+### 兼容
+
+- 旧日志若在 `tool` 事件里直接携带 `tokens` / `cost_usd`,按 legacy usage 处理。
+- 不理解 `turn_id` 的下游消费者可安全忽略。
diff --git a/.claude/skills/agent-observability/scripts/__init__.py b/.claude/skills/agent-observability/scripts/__init__.py
new file mode 100644
index 00000000..52073be9
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/__init__.py
@@ -0,0 +1 @@
+"""agent-observability 的脚本包。"""
diff --git a/.claude/skills/agent-observability/scripts/build_dashboard_data.py b/.claude/skills/agent-observability/scripts/build_dashboard_data.py
new file mode 100644
index 00000000..e33f816a
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/build_dashboard_data.py
@@ -0,0 +1,624 @@
+#!/usr/bin/env python3
+"""把 `logs/metrics.ndjson` + `artifacts/*/workflow-state.json` + `.state.json` +
+`hooks/logs/auto-dispatch.log` 聚合成看板需要的一份 `dashboard-data.json` 快照。
+
+这是本地看板的数据源,不是 hook 链路的一部分——hook 只管往 metrics.ndjson 追加事件,
+这个脚本单独、按需运行(比如每次想看一眼看板之前手动跑一次,或者配合文件监听器)。
+复用 core.devflow 的 stage_snapshot 做 workflow-state.json 的 schema 归一化,
+不在这里重新实现一遍 Classic/Portable 的字段差异。
+
+用法:
+ python3 build_dashboard_data.py --project-root <项目根目录> --out dashboard/dashboard-data.json
+ python3 build_dashboard_data.py --metrics-path ~/other/metrics.ndjson --state-path ~/other/.state.json
+ python3 build_dashboard_data.py --top-slow 5
+
+不传 --metrics-path / --state-path 时,仍从 <skill_root>/logs/ 下的默认文件读取;
+两者均支持 ~ 展开,输出 source 会如实反映实际读取路径。
+
+--top-slow N 默认不开启,开启后只在终端额外打印耗时最长的 N 次 tool 事件,
+不写入 dashboard-data.json(输出结构与不开时完全一致)。
+
+没有任何真实数据时(hook 刚接上、还没跑过 session),会输出一份全空但结构合法的快照,
+不会报错、也不会伪造数据。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import devflow as dv # type: ignore
+
+try: # emitter 只在"未定价模型"统计里用到,导入失败只让这一项退化为 []
+ from core import emitter as em # type: ignore
+except Exception: # pragma: no cover - 目标机缺依赖时的兜底
+ em = None # type: ignore
+
+# devflow 两套 schema 的 stage 名 -> 展示用 (label, name)。取不到的 stage 用 key 本身兜底。
+STAGE_META: dict[str, tuple[str, str]] = {
+ "PHASE-0": ("P0", "初始化 + 判定大小"),
+ "SOLO": ("SOLO", "单 agent 全流程"),
+ "TASK-01": ("T01", "需求分析 + 澄清"),
+ "REQUIREMENT": ("REQ", "需求分析 + 澄清"),
+ "TASK-02": ("T02", "技术方案"),
+ "DESIGN": ("DES", "技术方案"),
+ "TASK-03": ("T03", "代码实现"),
+ "IMPLEMENT": ("IMPL", "代码实现"),
+ "CODE-REVIEW": ("CR", "代码审查"),
+ "REVIEW": ("REV", "代码审查"),
+ "TASK-04": ("T04", "E2E 测试"),
+ "TEST": ("TEST", "E2E 测试"),
+ "TASK-05": ("T05", "知识沉淀"),
+ "KNOWLEDGE": ("KNOW", "知识沉淀"),
+ "SUMMARY": ("汇总", "最终汇总"),
+}
+# 两套 schema 各自的阶段顺序,用来按正确顺序渲染 stepper(不能直接遍历 dict,顺序不保证)。
+CLASSIC_ORDER = ["PHASE-0", "TASK-01", "TASK-02", "TASK-03", "CODE-REVIEW", "TASK-04", "TASK-05"]
+# SOLO 完成后,small 任务会由 solo-developer 合并执行 TASK-05 知识沉淀(真实运行验证过,
+# 不是理论上可选的分支);stepper 顺序必须把它列进去,否则会把已完成的阶段悄悄漏掉。
+CLASSIC_SOLO_ORDER = ["PHASE-0", "SOLO", "TASK-05"]
+PORTABLE_ORDER = ["PHASE-0", "REQUIREMENT", "DESIGN", "IMPLEMENT", "REVIEW", "TEST", "KNOWLEDGE", "SUMMARY"]
+PORTABLE_SOLO_ORDER = ["PHASE-0", "SOLO", "SUMMARY"]
+
+
+def read_ndjson(path: Path) -> list[dict[str, Any]]:
+ records: list[dict[str, Any]] = []
+ if not path.is_file():
+ return records
+ with path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ obj = json.loads(line)
+ except Exception:
+ continue
+ if isinstance(obj, dict):
+ records.append(obj)
+ return records
+
+
+def safe_load_json(path: Path) -> Any:
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def day_of(ts: float) -> str:
+ from datetime import datetime, timezone
+ return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+
+
+def tool_call_failed(raw_response: Any) -> bool:
+ """判断一次工具调用是否失败。
+
+ 真实 CodeBuddy CLI 的 transcript(`function_call_result.providerData.toolResult.
+ rawResponse`)里从来没有 `is_error` 这个布尔字段——实际信号是 `exitCode`(非 0
+ 即失败)和/或 `tool_error_code`(非 "0"/空即失败)。之前只认 `is_error`,导致
+ 失败统计在这个宿主上永远是 0,不管命令是否真的失败(复合命令比如
+ `cmd; echo ...` 会把失败进一步掩盖成 exitCode=0,那种情况下这里也如实判定为
+ 未失败——判断整条工具调用本身有没有失败,不追究命令内部的子步骤)。
+ 仍然保留 `is_error` 判断,兼容其它可能真的写这个字段的宿主。
+ """
+ if not isinstance(raw_response, dict):
+ return False
+ if raw_response.get("is_error"):
+ return True
+ exit_code = raw_response.get("exitCode")
+ if isinstance(exit_code, (int, float)) and exit_code != 0:
+ return True
+ tool_error_code = raw_response.get("tool_error_code")
+ if isinstance(tool_error_code, str) and tool_error_code.strip() not in ("", "0"):
+ return True
+ return False
+
+
+def build_daily_and_sessions(events: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ by_day: dict[str, dict[str, Any]] = {}
+ by_sid: dict[str, dict[str, Any]] = {}
+ by_sid_turn: dict[tuple[str, str], dict[str, Any]] = {}
+ # AgentLens(写 state.current_turn 的那套 tracing)默认关闭时,tool/usage 事件
+ # 自身的 turn_id 永远是 None——但 user_prompt_submit 事件不依赖 AgentLens,
+ # 始终携带真实 turn_id(见 emitter.build_prompt_submit_event)。按 ts 排序后,
+ # 把它当作 turn 边界,让后续没有自带 turn_id 的 tool/usage 事件归入"当前 sid
+ # 最近一次打开的 turn",而不是全部塌缩进同一个 "?" 占位桶。
+ current_turn_by_sid: dict[str, str] = {}
+
+ def day_bucket(iso: str) -> dict[str, Any]:
+ return by_day.setdefault(iso, {
+ "iso": iso, "sessionCount": 0, "input": 0, "output": 0, "cache": 0,
+ "cost": 0.0, "toolCalls": 0, "failures": 0, "skillHits": defaultdict(int),
+ "_sids": set(),
+ })
+
+ def sess_bucket(sid: str) -> dict[str, Any]:
+ return by_sid.setdefault(sid, {
+ "id": sid, "date": None, "agents": set(), "turns": set(), "toolCalls": 0,
+ "tokens": 0, "cost": 0.0, "first_ts": None, "last_ts": None, "models": defaultdict(int),
+ "status": "ok", "timeline": {},
+ })
+
+ for rec in sorted(events, key=lambda r: r.get("ts") if isinstance(r.get("ts"), (int, float)) else 0):
+ event = rec.get("event")
+ sid = str(rec.get("sid") or "")
+ ts = rec.get("ts")
+ if not sid or not isinstance(ts, (int, float)):
+ continue
+ iso = day_of(ts)
+ sess = sess_bucket(sid)
+ sess["_seen_day"] = iso
+ # 不管事件类型,只要这天有这个 sid 的任何事件就算一次"当日活跃会话"。
+ # 之前只在 tool/usage 分支里 add,纯对话(只有 user_prompt_submit,没有
+ # 触发任何工具调用也没有 usage)的会话永远不会被计入任何一天的
+ # sessionCount——总览页的"会话数"会比"会话浏览"tab 里实际展开的会话数少
+ # (真实数据复现过:5 个 session 只统计出 4 个 sessionCount)。
+ day_bucket(iso)["_sids"].add(sid)
+ if sess["first_ts"] is None or ts < sess["first_ts"]:
+ sess["first_ts"] = ts
+ sess["date"] = iso
+ if sess["last_ts"] is None or ts > sess["last_ts"]:
+ sess["last_ts"] = ts
+ agent = rec.get("agent")
+ if agent:
+ sess["agents"].add(str(agent))
+ raw_turn_id = rec.get("turn_id")
+ if event == "user_prompt_submit" and raw_turn_id:
+ current_turn_by_sid[sid] = str(raw_turn_id)
+ # 提前建桶——纯对话轮次(没有触发任何工具调用,只有 usage 都没有)
+ # 之前只在 tool/usage 分支里 setdefault,这种轮次永远不会出现在
+ # timeline 里,导致 turns 计数和时间线展开的分组数对不上。
+ by_sid_turn.setdefault(
+ (sid, str(raw_turn_id)),
+ {"turn": raw_turn_id, "agent": agent or "main", "events": []},
+ )
+ turn_id = raw_turn_id or current_turn_by_sid.get(sid)
+ if turn_id:
+ sess["turns"].add(str(turn_id))
+
+ if event == "tool":
+ day = day_bucket(iso)
+ day["toolCalls"] += 1
+ sess["toolCalls"] += 1
+ for s in rec.get("skill") or []:
+ day["skillHits"][str(s)] += 1
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ is_err = tool_call_failed(raw_response)
+ if is_err:
+ day["failures"] += 1
+ sess["status"] = "error"
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "tool", "tool": rec.get("tool"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ "err": is_err,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "usage":
+ day = day_bucket(iso)
+ tokens = rec.get("tokens") or {}
+ day["input"] += int(tokens.get("input") or 0)
+ day["output"] += int(tokens.get("output") or 0)
+ day["cache"] += int(tokens.get("cache_read") or 0)
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ day["cost"] += float(cost)
+ sess["cost"] += float(cost)
+ total_tok = int(tokens.get("input") or 0) + int(tokens.get("output") or 0)
+ sess["tokens"] += total_tok
+ model = rec.get("model")
+ if model:
+ sess["models"][str(model)] += 1
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "usage", "tokens": total_tok,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "error":
+ sess["status"] = "error"
+
+ for (sid, _turn_key), turn in by_sid_turn.items():
+ sess = by_sid.setdefault(sid, sess_bucket(sid))
+ sess["timeline"].setdefault(_turn_key, turn)
+
+ daily = []
+ for iso in sorted(by_day.keys()):
+ d = by_day[iso]
+ daily.append({
+ "iso": iso, "sessionCount": len(d["_sids"]), "input": d["input"], "output": d["output"],
+ "cache": d["cache"], "cost": round(d["cost"], 4), "toolCalls": d["toolCalls"],
+ "failures": d["failures"], "skillHits": dict(d["skillHits"]),
+ })
+
+ sessions = []
+ for sid, s in by_sid.items():
+ if s["first_ts"] is None:
+ continue
+ duration = int((s["last_ts"] or s["first_ts"]) - s["first_ts"])
+ model = max(s["models"].items(), key=lambda kv: kv[1])[0] if s["models"] else None
+ timeline_sorted = sorted(s["timeline"].values(), key=lambda t: str(t.get("turn") or ""))
+ for idx, t in enumerate(timeline_sorted, start=1):
+ t["turn"] = idx
+ sessions.append({
+ "id": sid, "date": s["date"], "agent": ", ".join(sorted(s["agents"])) or "main",
+ "turns": len(s["turns"]) or len(timeline_sorted), "toolCalls": s["toolCalls"],
+ "tokens": s["tokens"], "cost": round(s["cost"], 4), "duration": duration,
+ "model": model, "status": s["status"], "timeline": timeline_sorted,
+ })
+ sessions.sort(key=lambda s: s["date"] or "", reverse=True)
+ return daily, sessions
+
+
+def build_model_costs(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ cost = rec.get("cost_usd")
+ if model and isinstance(cost, (int, float)):
+ totals[str(model)] += float(cost)
+ rows = [{"name": name, "cost": round(cost, 4)} for name, cost in totals.items()]
+ rows.sort(key=lambda r: r["cost"], reverse=True)
+ return rows
+
+
+def build_unpriced_models(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """聚合"完全没命中价格表"的模型(D4:`emitter.is_unpriced(model)` 为 True)。
+
+ 只**统计**不重算:`cost_usd` 在 hook 期就写进事件了,这里不会(也不该)回头
+ 按新价格补算历史事件(D3:覆盖只对新事件生效)。判定入口复用 emitter,
+ 不在本文件里重写一套模型名匹配逻辑,避免与 hook 期的口径分叉。
+
+ 模型名缺失/为空的 usage 事件无法归因到某个模型,直接跳过不计数。
+ """
+ if em is None:
+ return []
+ counts: dict[str, int] = defaultdict(int)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ if not model or not str(model).strip():
+ continue
+ name = str(model)
+ try:
+ if em.is_unpriced(name):
+ counts[name] += 1
+ except Exception:
+ continue
+ rows = [{"name": name, "usageEvents": count} for name, count in counts.items()]
+ # 按 (-事件数, 名字) 排序:避免看板顺序抖动,两次生成的快照可直接逐字节比对。
+ rows.sort(key=lambda r: (-r["usageEvents"], r["name"]))
+ return rows
+
+
+def build_failures(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ agg: dict[tuple[str, str], dict[str, Any]] = {}
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ if not tool_call_failed(raw_response):
+ continue
+ tool = str(rec.get("tool") or "unknown")
+ code = str(raw_response.get("tool_error_code") or raw_response.get("exitCode") or "error")
+ key = (tool, code)
+ row = agg.setdefault(key, {"tool": tool, "code": code, "count": 0, "last": None, "_last_ts": 0.0})
+ row["count"] += 1
+ ts = rec.get("ts")
+ if isinstance(ts, (int, float)) and ts > row["_last_ts"]:
+ row["_last_ts"] = ts
+ row["last"] = day_of(ts)
+ rows = list(agg.values())
+ for row in rows:
+ row.pop("_last_ts", None)
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_top_slow(events: list[dict[str, Any]], limit: int | None = None) -> list[dict[str, Any]]:
+ """取耗时最长的 N 次 tool 事件,按 ms 降序。
+
+ 只做"读":不改动 events,也不参与 dashboard-data.json 的任何字段——调用方拿
+ 结果去打印即可。`ms` 的兜底口径与 build_daily_and_sessions 保持一致(缺失或
+ 非数字按 0 计),否则同一份日志会得出两个互相矛盾的工具耗时视图。
+ """
+ if not isinstance(limit, int) or limit <= 0:
+ return []
+ rows: list[dict[str, Any]] = []
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ rows.append({
+ "tool": str(rec.get("tool") or "unknown"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ })
+ rows.sort(key=lambda r: r["ms"], reverse=True)
+ return rows[:limit]
+
+
+def format_top_slow(rows: list[dict[str, Any]]) -> str:
+ """把 top-slow 结果渲染成终端文本;没有可展示的行时返回空串(由调用方决定
+ 是否打印,避免没有任何 tool 事件时空打一个表头)。"""
+ if not rows:
+ return ""
+ width = max(len(str(r["tool"])) for r in rows)
+ lines = [f"top-slow {len(rows)} tool calls (by ms):"]
+ for idx, row in enumerate(rows, start=1):
+ lines.append(f" {idx}. {str(row['tool']):<{width}} {row['ms']}ms")
+ return "\n".join(lines)
+
+
+def build_skills(state: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ totals: dict[str, int] = defaultdict(int)
+ never_used: dict[str, dict[str, Any]] = {}
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for name, rec in (sess.get("skills") or {}).items():
+ if not isinstance(rec, dict):
+ continue
+ totals[name] += int(rec.get("count") or 0)
+ for name, rec in (sess.get("rules") or {}).items():
+ if not isinstance(rec, dict) or int(rec.get("count") or 0) > 0:
+ continue
+ never_used[name] = {"name": name, "reason": "no_paths", "detail": "从未被路径推断或 active-rule 命中"}
+ for name, count in totals.items():
+ if count == 0:
+ never_used.setdefault(name, {"name": name, "reason": "no_paths", "detail": "静态扫描到,但从未被任何工具调用命中"})
+ skill_rows = [{"name": name, "count": count} for name, count in totals.items() if count > 0]
+ skill_rows.sort(key=lambda r: r["count"], reverse=True)
+ return skill_rows, sorted(never_used.values(), key=lambda r: r["name"])
+
+
+
+# "team-lead" 是 CodeBuddy 原生 team 基础设施里 lead/orchestrator session 自己的
+# mailbox 名字,语义上就是 main(core/agent_identity.py::normalize_role_name 把它
+# 和 "main" 归为同一类);不是一个真实存在的子 agent,不应出现在"派发目标"里。
+_DISPATCH_EXCLUDE_AGENTS = {"main", "team-lead"}
+
+
+def build_dispatch(state: dict[str, Any]) -> list[dict[str, Any]]:
+ totals: dict[str, int] = defaultdict(int)
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for entry in sess.get("agent_history") or []:
+ if not isinstance(entry, dict):
+ continue
+ evidence = str(entry.get("evidence") or "")
+ agent = entry.get("agent")
+ if not agent or agent in _DISPATCH_EXCLUDE_AGENTS:
+ continue
+ # 只统计真正代表"新派发"的证据:工具调用直接触发的 dispatch@,
+ # 或 inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)。
+ # 排除 inbox@report:*/inbox@handoff:*——那是子 agent 上报/移交,
+ # 不是 main 发起的新派发,计进来会把"派发次数"虚高(同一次真实
+ # 派发经常先触发 dispatch@,随后又在 inbox 里被自己的上报回声一次)。
+ is_dispatch = evidence.startswith("dispatch@") or evidence.startswith("inbox@dispatch:")
+ if is_dispatch:
+ totals[str(agent)] += 1
+ rows = [{"agent": agent, "count": count} for agent, count in totals.items()]
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_auto_dispatch_stats(project_root: Path) -> dict[str, int]:
+ log_path = project_root / ".codebuddy" / "hooks" / "logs" / "auto-dispatch.log"
+ stats = {"auto_dispatch": 0, "fallback_to_main": 0, "passthrough": 0}
+ if not log_path.is_file():
+ return stats
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ decision = str(rec.get("decision") or "")
+ if decision == "auto_dispatch":
+ stats["auto_dispatch"] += 1
+ elif decision == "fallback_to_main":
+ stats["fallback_to_main"] += 1
+ elif decision in {"passthrough"}:
+ stats["passthrough"] += 1
+ return stats
+
+
+def build_cost_by_task_slug(events: list[dict[str, Any]]) -> dict[str, float]:
+ """按 task_slug 汇总 usage/stop 事件的 cost_usd——workflow-state.json 自己不知道成本,
+ 这是唯一能把 devflow 运行和真实花费对上的地方(需要 emitter 已经把 task_slug 挂到事件上,
+ 见 core/runtime.py 的 devflow 接入)。"""
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") not in {"usage", "stop"}:
+ continue
+ task_slug = rec.get("task_slug")
+ cost = rec.get("cost_usd")
+ if task_slug and isinstance(cost, (int, float)):
+ totals[str(task_slug)] += float(cost)
+ return dict(totals)
+
+
+def build_devflow_runs(project_root: Path, cost_by_slug: dict[str, float] | None = None) -> list[dict[str, Any]]:
+ artifacts_root = project_root / "artifacts"
+ runs: list[dict[str, Any]] = []
+ cost_by_slug = cost_by_slug or {}
+ if not artifacts_root.is_dir():
+ return runs
+ for child in sorted(artifacts_root.iterdir()):
+ state_path = child / "workflow-state.json"
+ raw = dv.read_workflow_state(str(state_path))
+ if not isinstance(raw, dict) or not isinstance(raw.get("stages"), dict):
+ continue
+ snap = dv.stage_snapshot(raw)
+ size_class = str(snap.get("size_class") or "medium")
+ # medium/large 的 workflow-state.json 也会带着 SOLO key(模板固定写入,
+ # 状态停在 "pending" 或 "skipped",从未被真正执行)——不能只看 key 存不存在,
+ # 必须看 SOLO 阶段是不是真的跑过,否则每个 medium/large 任务都会被误判成
+ # solo 路径,阶段视图漏掉 TASK-01/02/03/CODE-REVIEW/TASK-04。
+ solo_info = snap["stages"].get("SOLO")
+ solo_status = str(solo_info.get("status") or "") if isinstance(solo_info, dict) else ""
+ solo_actually_ran = solo_status not in {"", "pending", "skipped"}
+ is_solo = size_class == "small" or (size_class not in {"small", "medium", "large"} and solo_actually_ran)
+ if snap.get("schema_version") == "2.0":
+ order = PORTABLE_SOLO_ORDER if is_solo else PORTABLE_ORDER
+ else:
+ order = CLASSIC_SOLO_ORDER if is_solo else CLASSIC_ORDER
+ stages_out = []
+ total_cost = cost_by_slug.get(child.name, 0.0)
+ run_start = None
+ run_end = None
+ overall = "completed"
+ for key in order:
+ info = snap["stages"].get(key)
+ if info is None:
+ # PHASE-0 在两套 schema 里都不会出现在 stages{} 里(它是隐式完成的:
+ # workflow-state.json 一旦存在,就说明 Phase 0 已经跑完了),
+ # 不能用"没有条目"直接兜底成 pending,那样会把已完成的阶段显示错。
+ info = {"status": "completed", "retry_count": 0, "executor": None} if key == "PHASE-0" \
+ else {"status": "pending", "retry_count": 0, "executor": None}
+ label, name = STAGE_META.get(key, (key[:4], key))
+ status = str(info.get("status") or "pending")
+ retry_count = int(info.get("retry_count") or 0)
+ raw_stage = raw.get("stages", {}).get(key) if isinstance(raw.get("stages"), dict) else {}
+ duration = 0
+ if isinstance(raw_stage, dict):
+ started = raw_stage.get("started_at")
+ completed = raw_stage.get("completed_at")
+ if isinstance(started, str) and isinstance(completed, str):
+ try:
+ from datetime import datetime
+ t0 = datetime.fromisoformat(started.replace("Z", "+00:00"))
+ t1 = datetime.fromisoformat(completed.replace("Z", "+00:00"))
+ duration = max(0, int((t1 - t0).total_seconds()))
+ if run_start is None or t0 < run_start:
+ run_start = t0
+ if run_end is None or t1 > run_end:
+ run_end = t1
+ except Exception:
+ duration = 0
+ if status == "failed":
+ overall = "paused"
+ elif status == "in_progress" and overall != "paused":
+ overall = "running"
+ stages_out.append({
+ "key": key, "label": label, "name": name,
+ "exec": info.get("executor") or "-", "status": status,
+ "retry_count": retry_count, "duration": duration,
+ })
+ # 按真实起止时间跨度算总时长(而不是逐阶段 duration 相加)——阶段之间可能
+ # 有重叠(比如 TASK-05 的 started_at 早于 SOLO 的 completed_at),相加会
+ # 把重叠部分重复计入,虚高于源数据本身反映的运行时长。
+ total_duration = int((run_end - run_start).total_seconds()) if run_start and run_end else 0
+ runs.append({
+ "slug": child.name, "size": size_class, "stages": stages_out,
+ "cost": round(total_cost, 4), "duration": total_duration, "overall": overall,
+ })
+ runs.sort(key=lambda r: r["slug"], reverse=True)
+ return runs
+
+
+def resolve_input_paths(
+ skill_root: Path,
+ metrics_path: str | None = None,
+ state_path: str | None = None,
+) -> tuple[Path, Path]:
+ """解析 metrics.ndjson 与 .state.json 的实际读取路径。
+
+ 任一参数为 None 时回退到 ``<skill_root>/logs/`` 下的默认路径,保证未传参时
+ 行为与旧版本完全一致(向后兼容,不会破坏现有看板数据源)。
+
+ 非 None 时按用户给定路径(支持 ``~`` 展开)取绝对路径,便于看板从非默认
+ 位置(如其它会话/项目的日志目录)聚合数据。
+ """
+ default_metrics = skill_root / "logs" / "metrics.ndjson"
+ default_state = skill_root / "logs" / ".state.json"
+ if metrics_path:
+ metrics = Path(metrics_path).expanduser().absolute()
+ else:
+ metrics = default_metrics
+ if state_path:
+ state = Path(state_path).expanduser().absolute()
+ else:
+ state = default_state
+ return metrics, state
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--project-root", default=".", help="devflow 项目根目录(含 .codebuddy/ 和 artifacts/)")
+ parser.add_argument("--out", default=None, help="输出路径,默认 <skill_root>/scripts/dashboard/dashboard-data.json")
+ parser.add_argument("--metrics-path", default=None, help="覆盖 metrics.ndjson 的读取路径(默认 <skill_root>/logs/metrics.ndjson,支持 ~ 展开)")
+ parser.add_argument("--state-path", default=None, help="覆盖 .state.json 的读取路径(默认 <skill_root>/logs/.state.json,支持 ~ 展开)")
+ parser.add_argument("--top-slow", type=int, default=None, help="额外在终端打印耗时最长的 N 次 tool 事件(工具名 + 耗时 ms),默认不打印;只打印不写入 dashboard-data.json")
+ args = parser.parse_args()
+
+ project_root = Path(args.project_root).expanduser().resolve()
+ skill_root = SCRIPTS_DIR.parent
+ log_path, state_path = resolve_input_paths(skill_root, args.metrics_path, args.state_path)
+
+ # 价格表带 lru_cache:本脚本可能长期驻留(配合文件监听器),单测也会同进程多次
+ # 调 main(),每次都先清一次缓存,保证覆盖文件的改动当场生效。
+ if em is not None:
+ try:
+ em.clear_price_cache()
+ except Exception:
+ pass
+
+ events = read_ndjson(log_path)
+ state = safe_load_json(state_path) or {}
+ if not isinstance(state, dict):
+ state = {}
+
+ daily, sessions = build_daily_and_sessions(events)
+ model_costs = build_model_costs(events)
+ unpriced = build_unpriced_models(events)
+ failures = build_failures(events)
+ skills, never_used = build_skills(state)
+ dispatch = build_dispatch(state)
+ auto_dispatch_stats = build_auto_dispatch_stats(project_root)
+ cost_by_slug = build_cost_by_task_slug(events)
+ devflow_runs = build_devflow_runs(project_root, cost_by_slug)
+
+ from datetime import datetime, timezone
+ out_data = {
+ "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+ "source": {
+ "metrics_ndjson": str(log_path), "state_json": str(state_path),
+ "project_root": str(project_root), "event_count": len(events),
+ },
+ "daily": daily, "sessions": sessions, "modelCosts": model_costs, "unpricedModels": unpriced,
+ "failures": failures,
+ "skills": skills, "neverUsed": never_used, "dispatch": dispatch,
+ "autoDispatchStats": auto_dispatch_stats, "devflowRuns": devflow_runs,
+ }
+
+ out_path = Path(args.out).expanduser().resolve() if args.out else (SCRIPTS_DIR / "dashboard" / "dashboard-data.json")
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+ out_path.write_text(json.dumps(out_data, ensure_ascii=False, indent=2), encoding="utf-8")
+ print(f"wrote {out_path} ({len(events)} events, {len(sessions)} sessions, {len(devflow_runs)} devflow runs)")
+ # top-slow 放在原输出之后:先保证不传参时的终端输出与 JSON 行为完全不变。
+ top_slow_block = format_top_slow(build_top_slow(events, args.top_slow))
+ if top_slow_block:
+ print(top_slow_block)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.claude/skills/agent-observability/scripts/core/__init__.py b/.claude/skills/agent-observability/scripts/core/__init__.py
new file mode 100644
index 00000000..1d6ad5e9
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/__init__.py
@@ -0,0 +1,8 @@
+"""agent-observability 的核心运行时模块集合。
+
+这里放的是 hook 主流程真正依赖的内部实现:
+- 采集与 transcript 解析
+- 状态读写与去重
+- skill/rule 扫描
+- AgentLens trace 镜像
+"""
diff --git a/.claude/skills/agent-observability/scripts/core/agent_identity.py b/.claude/skills/agent-observability/scripts/core/agent_identity.py
new file mode 100644
index 00000000..270ff904
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agent_identity.py
@@ -0,0 +1,587 @@
+"""Agent 身份解析层。
+
+这一层负责统一解析“当前是谁在工作、又把任务派给了谁”:
+- 从 tool 调用参数里提取 agent 线索
+- 从 team inbox / mailbox 中补偿推断 agent 身份
+- 把解析结果写回 session state,供后续日志归因复用
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+from . import scanner, state as st
+
+AGENT_PATH_RE = re.compile(r"\.codebuddy/agents/([a-zA-Z0-9_\-]+)(?:\.md)?", re.I)
+DISPATCH_TOOLS = {"Task", "task", "Agent", "DeferExecuteTool"}
+MESSAGE_TOOLS = {"send_message", "SendMessage"}
+TEAM_PREFIX = "multi-agents-devflow-"
+ROLE_INSTANCE_RE = re.compile(r"^(?P<base>[a-z0-9][a-z0-9\-]*?)-\d+$", re.I)
+INITIAL_ASSIGNMENT_RE = re.compile(
+ r"Initial task assignment for (?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+ROLE_DECLARATION_RE = re.compile(
+ r"角色[::]\s*(?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+# devflow TASK-03 并行 fan-out 时,developer 会以 Task(name="sub-developer-PT-01", ...)
+# 派发多条并行轨道。轨道号只在 transcript 文件名(= Task 的 name 参数)里出现,
+# 按 subagent_name 归一化后会被折成同一个 "developer" —— 这是有意的(用于按角色汇总),
+# 轨道号需要单独提取,见 pt_id_from_transcript_path。
+PT_TRACK_RE = re.compile(r"-((?:PT|pt)-\d+)$")
+
+
+def normalize_role_name(name: str | None) -> Optional[str]:
+ """把角色名归一化成稳定标识,例如把实例名折叠回基础角色名。"""
+ if not isinstance(name, str):
+ return None
+ cand = name.strip().lower()
+ if not cand:
+ return None
+ if cand.endswith(".json"):
+ cand = cand[:-5]
+ if "@" in cand:
+ cand = cand.split("@", 1)[0]
+ if cand in {"team-lead", "main"}:
+ return "main"
+ match = ROLE_INSTANCE_RE.match(cand)
+ if match:
+ cand = match.group("base")
+ return cand or None
+
+
+def resolve_teams_root() -> Path:
+ """解析 CodeBuddy team inbox 的根目录。"""
+ config_dir = (os.environ.get("CODEBUDDY_CONFIG_DIR") or "").strip()
+ if config_dir:
+ return Path(config_dir).expanduser() / "teams"
+ return Path.home() / ".codebuddy" / "teams"
+
+
+def resolve_team_dir(cwd: str, sid: str, cached_team_dir: str | None = None) -> Path | None:
+ """根据 session id 和 cwd 找到当前会话对应的 team 目录。"""
+ if cached_team_dir:
+ cached = Path(cached_team_dir).expanduser()
+ if (cached / "config.json").is_file():
+ cfg = _load_json(cached / "config.json")
+ if isinstance(cfg, dict) and sid and str(cfg.get("leadSessionId") or "") == sid:
+ return cached
+
+ if not sid:
+ return None
+
+ teams_root = resolve_teams_root()
+ if not teams_root.is_dir():
+ return None
+
+ best_dir: Path | None = None
+ best_created = -1
+ for team_dir in teams_root.iterdir():
+ if not team_dir.is_dir() or not team_dir.name.startswith(TEAM_PREFIX):
+ continue
+ config = _load_json(team_dir / "config.json")
+ if not isinstance(config, dict):
+ continue
+ if str(config.get("leadSessionId") or "") != sid:
+ continue
+ if not _config_matches_cwd(config, cwd):
+ continue
+
+ created_at = _safe_int(config.get("createdAt"))
+ if created_at <= 0:
+ try:
+ created_at = int(team_dir.stat().st_mtime * 1000)
+ except Exception:
+ created_at = 0
+ if created_at > best_created:
+ best_dir = team_dir
+ best_created = created_at
+ return best_dir
+
+
+def read_recent_messages(
+ team_dir: Path,
+ offsets: dict[str, int] | None = None,
+ *,
+ max_per_mailbox: int = 30,
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+ """按 mailbox 增量读取最近消息,并返回新的 offset 游标。"""
+ inbox_dir = team_dir / "inboxes"
+ if not inbox_dir.is_dir():
+ return [], offsets or {}
+
+ prev_offsets = offsets or {}
+ new_offsets: dict[str, int] = {}
+ messages: list[dict[str, Any]] = []
+
+ for inbox_file in sorted(inbox_dir.glob("*.json")):
+ raw = _load_json(inbox_file)
+ if not isinstance(raw, list):
+ raw = []
+
+ total = len(raw)
+ prev = _safe_int(prev_offsets.get(inbox_file.name))
+ if prev < 0 or prev > total:
+ prev = 0
+
+ start = prev
+ if start == 0 and total > max_per_mailbox:
+ start = total - max_per_mailbox
+
+ mailbox_name = inbox_file.stem
+ mailbox_role = normalize_role_name(mailbox_name)
+ for idx, item in enumerate(raw[start:], start=start):
+ norm = _normalize_message(item, mailbox_name, mailbox_role, idx)
+ if norm:
+ messages.append(norm)
+
+ new_offsets[inbox_file.name] = total
+
+ messages.sort(key=lambda x: (x.get("ts") or 0.0, x.get("mailbox_name") or "", x.get("index") or 0))
+ return messages, new_offsets
+
+
+def infer_identity_from_messages(messages: list[dict[str, Any]]) -> tuple[Optional[str], Optional[str], dict[str, Any]]:
+ """根据 inbox 消息流推断当前 agent 与派发目标。"""
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ evidence: Optional[str] = None
+
+ for msg in messages:
+ mailbox_name = str(msg.get("mailbox_name") or "")
+ mailbox_role = normalize_role_name(msg.get("mailbox_role"))
+ from_role = normalize_role_name(msg.get("from_role"))
+ payload = msg.get("payload") if isinstance(msg.get("payload"), dict) else {}
+ next_target = _extract_next_target(payload)
+
+ if from_role == "main" and mailbox_role and mailbox_role != "main":
+ if not msg.get("is_shutdown"):
+ current = mailbox_role
+ dispatched = mailbox_role
+ evidence = f"dispatch:{mailbox_name}"
+ continue
+
+ if mailbox_name == "team-lead" and from_role and from_role not in {"main", "system"}:
+ report_role = normalize_role_name(
+ payload.get("from_role") if isinstance(payload, dict) else None
+ ) or from_role
+ if next_target:
+ current = next_target
+ dispatched = next_target
+ evidence = f"handoff:{report_role}->{next_target}"
+ else:
+ current = report_role
+ evidence = f"report:{report_role}"
+
+ meta: dict[str, Any] = {"messages_seen": len(messages)}
+ if evidence:
+ meta["evidence"] = evidence
+ return current, dispatched, meta
+
+
+def safe_agent_from_provider(record: dict[str, Any]) -> str | None:
+ """当 transcript 自己带有 providerData 时,直接读取其中的 agent。"""
+ provider = record.get("providerData")
+ if not isinstance(provider, dict):
+ return None
+ agent = provider.get("agent")
+ if isinstance(agent, str) and agent.strip():
+ return normalize_role_name(agent.strip())
+ return None
+
+
+def role_from_content_items(content: Any) -> str | None:
+ """从 transcript content 文本中提取更具体的业务角色名。"""
+ if not isinstance(content, list):
+ return None
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ text = item.get("text")
+ if not isinstance(text, str):
+ continue
+ for regex in (INITIAL_ASSIGNMENT_RE, ROLE_DECLARATION_RE):
+ match = regex.search(text)
+ if not match:
+ continue
+ role = normalize_role_name(match.group("role"))
+ if role:
+ return role
+ return None
+
+
+@lru_cache(maxsize=256)
+def role_for_subagent_transcript(transcript_path: str) -> str | None:
+ """从 subagent transcript 前几行推断更准确的角色名。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(6):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+
+ # 对 subagent transcript,优先信任务分配文本里的具体角色,
+ # 再回退到 providerData.agent,避免 general-purpose 覆盖业务角色。
+ content_role = role_from_content_items(record.get("content"))
+ if content_role:
+ return content_role
+
+ provider_agent = safe_agent_from_provider(record)
+ if provider_agent:
+ return provider_agent
+ except Exception:
+ return None
+ return None
+
+
+def agent_for_transcript_path(transcript_path: str, fallback: str | None = None) -> str:
+ """把 transcript 路径映射回实际对应的 agent 身份。"""
+ parts = Path(transcript_path).parts
+ if "subagents" in parts:
+ return role_for_subagent_transcript(transcript_path) or Path(transcript_path).stem
+ return fallback or "main"
+
+
+def pt_id_from_transcript_path(transcript_path: str) -> str | None:
+ """从并行 sub-developer 的 transcript 文件名里提取 PT 轨道号(如 "PT-01")。
+
+ 按事件自己的 transcript_path 推断,而不是写一个共享的 session 级"当前 PT"指针——
+ devflow 一次可以并行派发最多 6 条 sub-developer 轨道,它们在同一个 sid 下
+ 真·并发运行,任何"当前是哪条轨道"的可变共享状态在并发场景下都是错的。
+ """
+ parts = Path(transcript_path).parts
+ if "subagents" not in parts:
+ return None
+ match = PT_TRACK_RE.search(Path(transcript_path).stem)
+ return match.group(1).upper() if match else None
+
+
+def merge_agent_identity_from_inbox(
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str | None,
+ dispatched: str | None,
+) -> tuple[str, str | None]:
+ """在基于 tool 的推断之上,再叠加 mailbox/inbox 的证据。"""
+
+ def _update(state: dict[str, Any]) -> tuple[str, str | None]:
+ sess = st.ensure_session(state, sid)
+ cached_team_dir = str(sess.get("_team_dir") or "").strip() or None
+ offsets = sess.get("_inbox_offsets")
+ if not isinstance(offsets, dict):
+ offsets = {}
+
+ effective_agent = active_agent or str(sess.get("current_agent") or "main")
+ effective_dispatched = dispatched
+ team_dir = resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is None:
+ return effective_agent, effective_dispatched
+
+ sess["_team_dir"] = str(team_dir)
+ messages, new_offsets = read_recent_messages(team_dir, offsets)
+ sess["_inbox_offsets"] = new_offsets
+ inferred_current, inferred_dispatched, meta = infer_identity_from_messages(messages)
+ if inferred_current:
+ effective_agent = inferred_current
+ if inferred_dispatched:
+ effective_dispatched = inferred_dispatched
+ if inferred_current or inferred_dispatched:
+ target_agent = inferred_current or inferred_dispatched
+ if target_agent:
+ sess["current_agent"] = target_agent
+ hist = sess.setdefault("agent_history", [])
+ hist.append({
+ "ts": time.time(),
+ "agent": target_agent,
+ "evidence": f"inbox@{meta.get('evidence') or 'inbox'}",
+ })
+ return effective_agent, effective_dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+
+def resolve_active_agent_for_event(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ data: dict[str, Any],
+) -> tuple[str, str | None]:
+ """优先用 tool 线索、其次用 inbox 线索,解析事件对应的 agent。"""
+ tracker = AgentIdentityResolver()
+ active_agent, dispatched = tracker.track(state_path, sid, data)
+ if scanner.is_brainstorming_call(data):
+
+ def _update(state_data: dict[str, Any]) -> None:
+ sess = st.ensure_session(state_data, sid)
+ sess["current_agent"] = "main"
+
+ st.update_state_locked(state_path, _update)
+ return "main", dispatched
+ return merge_agent_identity_from_inbox(
+ state_path,
+ sid,
+ cwd,
+ active_agent,
+ dispatched,
+ )
+
+
+class AgentIdentityResolver:
+ """基于 tool 调用内容做一轮 agent 身份推断。"""
+ def __init__(self, known_agents: set[str] | None = None):
+ self.known_agents = known_agents or set()
+
+ def extract_identity(self, data: dict) -> tuple[Optional[str], Optional[str]]:
+ tool = data.get("tool_name", "")
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ tool_input = {}
+
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+
+ if tool in MESSAGE_TOOLS:
+ extracted_current, extracted_dispatched = self._extract_from_message(tool_input)
+ if extracted_current and not current:
+ current = extracted_current
+ if extracted_dispatched and not dispatched:
+ dispatched = extracted_dispatched
+
+ if tool in DISPATCH_TOOLS and not dispatched:
+ dispatched = self._extract_from_task(tool_input)
+
+ if not current:
+ current = self._extract_from_path(data, tool_input)
+
+ if self.known_agents:
+ if current and current not in self.known_agents:
+ current = None
+ if dispatched and dispatched not in self.known_agents:
+ dispatched = None
+
+ return current, dispatched
+
+ def track(self, state_path: Path, sid: str, data: dict) -> tuple[str, Optional[str]]:
+ tool = data.get("tool_name", "")
+ cur_agent, dispatched = self.extract_identity(data)
+
+ def _update(state: dict[str, Any]) -> tuple[str, Optional[str]]:
+ sess = st.ensure_session(state, sid)
+ hist = sess.setdefault("agent_history", [])
+ prev_agent = sess.get("current_agent") or "main"
+
+ if cur_agent and cur_agent != prev_agent:
+ sess["current_agent"] = cur_agent
+ hist.append({"ts": time.time(), "agent": cur_agent, "evidence": f"from_role@{tool}"})
+ active_agent = cur_agent
+ else:
+ active_agent = prev_agent
+
+ if dispatched and dispatched != active_agent:
+ dis = sess.setdefault("dispatched", {})
+ if not isinstance(dis, dict):
+ dis = {}
+ sess["dispatched"] = dis
+ dis[dispatched] = dis.get(dispatched, 0) + 1
+ sess["current_agent"] = dispatched
+ hist.append({"ts": time.time(), "agent": dispatched, "evidence": f"dispatch@{tool}<-{active_agent}"})
+
+ if len(hist) > 100:
+ sess["agent_history"] = hist[-100:]
+
+ return active_agent, dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+ def _extract_from_message(self, tool_input: dict) -> tuple[Optional[str], Optional[str]]:
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ content = tool_input.get("content")
+
+ if isinstance(content, str) and content.strip().startswith("{"):
+ try:
+ payload = json.loads(content)
+ current = self._extract_str(payload, "from_role")
+ next_target = payload.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+ except Exception:
+ pass
+ elif isinstance(content, dict):
+ current = self._extract_str(content, "from_role")
+ next_target = content.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+
+ if not dispatched:
+ recipient = tool_input.get("recipient")
+ if isinstance(recipient, str):
+ normalized = recipient.strip().lower()
+ if normalized and normalized != "main":
+ dispatched = normalized
+
+ return current, dispatched
+
+ def _extract_from_task(self, tool_input: dict) -> Optional[str]:
+ sub = (
+ # Claude Code 的 Agent 工具(非 CodeBuddy 原生 Task/team_create)用的是
+ # subagent_type 字段,不是 subagent_name——不认这个字段会导致 dispatch
+ # 统计漏掉所有走 Agent 工具派发的场景。
+ tool_input.get("subagent_type")
+ or tool_input.get("subagent_name")
+ or tool_input.get("name")
+ or tool_input.get("agent")
+ or tool_input.get("role")
+ )
+ if isinstance(sub, str) and sub.strip():
+ candidate = sub.strip().lower()
+ if "/" in candidate:
+ candidate = candidate.rsplit("/", 1)[1].replace(".md", "")
+ return candidate
+ return None
+
+ def _extract_from_path(self, data: dict, tool_input: dict) -> Optional[str]:
+ text = json.dumps(tool_input, ensure_ascii=False) + " " + (data.get("cwd") or "")
+ match = AGENT_PATH_RE.search(text)
+ if match:
+ return match.group(1).lower()
+ return None
+
+ @staticmethod
+ def _extract_str(payload: dict, key: str) -> Optional[str]:
+ value = payload.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip().lower()
+ return None
+
+
+def _config_matches_cwd(config: dict[str, Any], cwd: str) -> bool:
+ """判断 team 配置中的成员 cwd 是否覆盖当前工作目录。"""
+ members = config.get("members")
+ if not isinstance(members, list):
+ return False
+ for member in members:
+ if not isinstance(member, dict):
+ continue
+ member_cwd = member.get("cwd")
+ if isinstance(member_cwd, str) and _paths_equal(member_cwd, cwd):
+ return True
+ return False
+
+
+def _paths_equal(a: str, b: str) -> bool:
+ """按归一化绝对路径语义比较两个路径是否相等。"""
+ try:
+ return Path(a).expanduser().resolve() == Path(b).expanduser().resolve()
+ except Exception:
+ return os.path.abspath(os.path.expanduser(a)) == os.path.abspath(os.path.expanduser(b))
+
+
+def _normalize_message(item: Any, mailbox_name: str, mailbox_role: str | None, index: int) -> dict[str, Any] | None:
+ """把原始 inbox 消息归一化成统一可推断的结构。"""
+ if not isinstance(item, dict):
+ return None
+
+ text = item.get("text")
+ payload = _coerce_payload(text)
+ summary = item.get("summary") if isinstance(item.get("summary"), str) else ""
+ from_raw = item.get("from") if isinstance(item.get("from"), str) else None
+ from_role = normalize_role_name((payload.get("from") if isinstance(payload, dict) else None) or from_raw)
+ ts = _parse_timestamp(item.get("timestamp"))
+
+ return {
+ "mailbox_name": mailbox_name,
+ "mailbox_role": mailbox_role,
+ "from": from_raw,
+ "from_role": from_role,
+ "text": text if isinstance(text, str) else "",
+ "summary": summary,
+ "payload": payload,
+ "timestamp": item.get("timestamp"),
+ "ts": ts,
+ "index": index,
+ "is_shutdown": _is_shutdown_message(payload, summary, text),
+ }
+
+
+def _extract_next_target(payload: dict[str, Any] | None) -> Optional[str]:
+ """从 payload 中提取下一跳要派发给的角色。"""
+ if not isinstance(payload, dict):
+ return None
+ next_target = payload.get("next_target") or {}
+ if not isinstance(next_target, dict):
+ return None
+ return normalize_role_name(next_target.get("role_name") or next_target.get("subagent_name"))
+
+
+def _coerce_payload(text: Any) -> dict[str, Any] | None:
+ """把文本内容尽量解析成 JSON 字典。"""
+ if isinstance(text, dict):
+ return text
+ if not isinstance(text, str):
+ return None
+ stripped = text.strip()
+ if not stripped.startswith("{"):
+ return None
+ try:
+ data = json.loads(stripped)
+ if isinstance(data, dict):
+ return data
+ except Exception:
+ return None
+ return None
+
+
+def _is_shutdown_message(payload: dict[str, Any] | None, summary: str, text: Any) -> bool:
+ """识别一条 inbox 消息是否表示 agent 关闭或退出。"""
+ if isinstance(payload, dict) and str(payload.get("type") or "").lower() == "shutdown_request":
+ return True
+ summary_low = summary.lower() if isinstance(summary, str) else ""
+ text_low = text.lower() if isinstance(text, str) else ""
+ return "shutdown" in summary_low or "shutdown request" in text_low
+
+
+def _parse_timestamp(value: Any) -> float:
+ """把消息时间字段解析成 Unix 时间戳。"""
+ if not isinstance(value, str) or not value.strip():
+ return datetime.now(timezone.utc).timestamp()
+ try:
+ return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+ except Exception:
+ return datetime.now(timezone.utc).timestamp()
+
+
+def _load_json(path: Path) -> Any:
+ """安全读取 JSON 文件,失败时返回 ``None``。"""
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def _safe_int(value: Any) -> int:
+ """把任意值尽量转成整数,失败时返回 0。"""
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
diff --git a/.claude/skills/agent-observability/scripts/core/agentlens/__init__.py b/.claude/skills/agent-observability/scripts/core/agentlens/__init__.py
new file mode 100644
index 00000000..2fea21d6
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agentlens/__init__.py
@@ -0,0 +1,9 @@
+"""可选的 AgentLens sink,用于实时镜像 trace。"""
+from .runtime import emit_post_step, emit_session_start, emit_session_stop, emit_turn_start
+
+__all__ = [
+ "emit_post_step",
+ "emit_session_start",
+ "emit_session_stop",
+ "emit_turn_start",
+]
diff --git a/.claude/skills/agent-observability/scripts/core/agentlens/bootstrap.py b/.claude/skills/agent-observability/scripts/core/agentlens/bootstrap.py
new file mode 100644
index 00000000..d6fc970e
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agentlens/bootstrap.py
@@ -0,0 +1,229 @@
+from __future__ import annotations
+"""AgentLens 启动辅助层。
+
+这一层负责“读入与初始化”:
+- 解析项目配置与环境变量
+- 延迟加载可选的 zhiyan 运行时
+- 缓存初始化结果,避免重复 init
+- 处理调试落盘与失败状态写回
+"""
+
+import getpass
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+
+DEFAULT_APP_NAME = "skillhub.codebuddy-hooks"
+DEFAULT_BUSINESS_SCENARIO = "codebuddy-hook"
+
+_RUNTIME: dict[str, Any] | None = None
+_INIT_SIGNATURE: tuple[str, str, str] | None = None
+
+
+@dataclass(frozen=True)
+class AgentLensConfig:
+ """从环境变量与 env 文件归一化得到的 AgentLens 配置。"""
+ endpoint: str | None
+ api_key: str | None
+ app_name: str
+ business_scenario: str
+ user: str
+
+ @property
+ def enabled(self) -> bool:
+ return bool(self.endpoint and self.api_key)
+
+
+def project_root(cwd: str | None = None) -> Path:
+ """解析用于查找 `.env` 的项目根目录。"""
+ if cwd:
+ return Path(cwd).expanduser().resolve()
+ env_cwd = str(os.environ.get("CODEBUDDY_PROJECT_DIR") or "").strip()
+ if env_cwd:
+ return Path(env_cwd).expanduser().resolve()
+ return Path.cwd().resolve()
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+ """以轻量方式解析 shell 风格的 env 文件,不做 source。"""
+ values: dict[str, str] = {}
+ if not path.is_file():
+ return values
+ try:
+ lines = path.read_text("utf-8").splitlines()
+ except Exception:
+ return values
+
+ for raw_line in lines:
+ line = raw_line.strip()
+ if not line or line.startswith("#"):
+ continue
+ if line.startswith("export "):
+ line = line[7:].strip()
+ if "=" not in line:
+ continue
+ key, value = line.split("=", 1)
+ key = key.strip()
+ value = value.strip()
+ if not key:
+ continue
+ if value and value[0] == value[-1] and value[0] in {"'", '"'}:
+ value = value[1:-1]
+ values[key] = value
+ return values
+
+
+def load_config(project_root_path: Path) -> AgentLensConfig:
+ """按优先级加载配置:进程环境变量 > `.env.local` > `.env`。"""
+ env_file = read_env_file(project_root_path / ".env")
+ env_local_file = read_env_file(project_root_path / ".env.local")
+
+ def _value(name: str, default: str | None = None) -> str | None:
+ env_value = os.environ.get(name)
+ if env_value is not None and str(env_value).strip():
+ return str(env_value).strip()
+ if name in env_local_file and str(env_local_file[name]).strip():
+ return str(env_local_file[name]).strip()
+ if name in env_file and str(env_file[name]).strip():
+ return str(env_file[name]).strip()
+ return default
+
+ user = _value("ZHIYANLLM_USER")
+ if not user:
+ user = (
+ str(os.environ.get("USER") or "").strip()
+ or str(os.environ.get("USERNAME") or "").strip()
+ or getpass.getuser()
+ )
+
+ return AgentLensConfig(
+ endpoint=_value("ZHIYANLLM_API_ENDPOINT"),
+ api_key=_value("ZHIYANLLM_API_KEY"),
+ app_name=_value("ZHIYANLLM_APP_NAME", DEFAULT_APP_NAME) or DEFAULT_APP_NAME,
+ business_scenario=_value("ZHIYANLLM_BUSINESS_SCENARIO", DEFAULT_BUSINESS_SCENARIO)
+ or DEFAULT_BUSINESS_SCENARIO,
+ user=user or "unknown",
+ )
+
+
+def load_runtime() -> dict[str, Any] | None:
+ """延迟导入可选的 zhiyan 运行时组件。
+
+ 即使本地没有安装 AgentLens 依赖,hook 主链路也必须继续工作,
+ 所以这里返回 ``None``,而不是把导入异常抛出去。
+ """
+ global _RUNTIME
+ if _RUNTIME is not None:
+ return _RUNTIME
+ try:
+ from zhiyanllm import Zhiyanllm
+ from zhiyanllm.opentelemetry.instrumentation.semconv_ai import (
+ SpanAttributes as ZhiyanSpanAttributes,
+ ZhiyanllmSpanKindValues,
+ )
+ from zhiyanllm.tracing.context_manager import get_tracer
+ from zhiyanllm.tracing.manual import track_llm_call, track_task_server_call
+ from zhiyanllm.tracing.tracing import TracerWrapper
+ from opentelemetry.context import attach as otel_attach, detach as otel_detach
+ except Exception:
+ _RUNTIME = None
+ return None
+
+ _RUNTIME = {
+ "Zhiyanllm": Zhiyanllm,
+ "track_llm_call": track_llm_call,
+ "track_task_server_call": track_task_server_call,
+ "TracerWrapper": TracerWrapper,
+ "get_tracer": get_tracer,
+ "ZhiyanSpanAttributes": ZhiyanSpanAttributes,
+ "ZhiyanllmSpanKindValues": ZhiyanllmSpanKindValues,
+ "otel_attach": otel_attach,
+ "otel_detach": otel_detach,
+ }
+ return _RUNTIME
+
+
+def ensure_initialized(config: AgentLensConfig) -> dict[str, Any] | None:
+ """仅当有效配置签名发生变化时才重新初始化 zhiyan。"""
+ global _INIT_SIGNATURE
+ if not config.enabled:
+ return None
+ runtime = load_runtime()
+ if runtime is None:
+ return None
+ signature = (str(config.endpoint), str(config.api_key), str(config.app_name))
+ if _INIT_SIGNATURE == signature:
+ return runtime
+ runtime["Zhiyanllm"].init(
+ app_name=str(config.app_name),
+ api_endpoint=str(config.endpoint),
+ api_key=str(config.api_key),
+ disable_batch=True,
+ )
+ _INIT_SIGNATURE = signature
+ return runtime
+
+
+def project_root_from_state_path(state_path: Path) -> Path:
+ """尽力从 `logs/.state.json` 反推出项目根目录。"""
+ try:
+ current = state_path.resolve().parent
+ for parent in [current, *current.parents]:
+ if parent.name == ".codebuddy":
+ return parent.parent
+ return state_path.resolve().parents[4]
+ except Exception:
+ return Path.cwd().resolve()
+
+
+def debug_enabled(state_path: Path) -> bool:
+ """判断是否要把 span 调试信息镜像写入 `agentlens-push-debug.ndjson`。"""
+ root = project_root_from_state_path(state_path)
+ env_file = read_env_file(root / ".env")
+ env_local_file = read_env_file(root / ".env.local")
+ raw = (
+ os.environ.get("AGENTLENS_PUSH_DEBUG")
+ or env_local_file.get("AGENTLENS_PUSH_DEBUG")
+ or env_file.get("AGENTLENS_PUSH_DEBUG")
+ or ""
+ )
+ return str(raw).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def debug_write_span(
+ state_path: Path | None,
+ sid: str | None,
+ payload: dict[str, Any],
+ *,
+ sanitizer,
+) -> None:
+ """在开启 AgentLens 调试模式时追加写入清洗后的调试记录。"""
+ if state_path is None or not sid:
+ return
+ try:
+ if not debug_enabled(state_path):
+ return
+ debug_path = state_path.parent / "agentlens-push-debug.ndjson"
+ record = {"sid": sid, **sanitizer(payload)}
+ with debug_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+ except Exception:
+ return
+
+
+def set_failure(state_path: Path, sid: str, message: str) -> None:
+ """记录最近一次 AgentLens 失败,但不打断 hook 主流程。"""
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": False, "last_error": str(message)},
+ )
+
+
+def get_session_context(state_path: Path, sid: str) -> dict[str, Any]:
+ """从共享状态里读取 AgentLens sidecar 的 session payload。"""
+ return st.load_agentlens_session(state_path, sid)
diff --git a/.claude/skills/agent-observability/scripts/core/agentlens/normalize.py b/.claude/skills/agent-observability/scripts/core/agentlens/normalize.py
new file mode 100644
index 00000000..2b730f06
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agentlens/normalize.py
@@ -0,0 +1,323 @@
+from __future__ import annotations
+"""AgentLens 负载清洗层。
+
+这一层负责“清洗与整形”:
+- 在发送或调试前把任意 payload 转成安全的 JSON 结构
+- 把本地 token 结构归一化成类似 OpenAI 的 usage 结构
+- 从 transcript 中重建轻量的 message / tool-call 上下文
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig
+
+
+def sanitize_payload(value: Any) -> Any:
+ """把任意 Python 值转换成适合调试/打点的 JSON 安全结构。"""
+ try:
+ return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+ except Exception:
+ return str(value)
+
+
+def association_properties(config: AgentLensConfig, sid: str, state_path: Path | None = None) -> dict[str, str]:
+ """构造 trace 级关联属性,并允许按 turn 覆盖业务场景。"""
+ scenario = config.business_scenario
+ if state_path:
+ try:
+ session_ctx = st.load_agentlens_session(state_path, sid)
+ turn_scenario = session_ctx.get("_turn_business_scenario")
+ if isinstance(turn_scenario, str) and turn_scenario.strip():
+ scenario = turn_scenario.strip()
+ except Exception:
+ pass
+ return {
+ "session_id": sid,
+ "business_scenario": scenario,
+ "user": config.user,
+ }
+
+
+def to_openai_usage(tokens: dict[str, Any] | None) -> dict[str, int]:
+ """把本地 token 结构转换成 zhiyan 期望的 usage 形状。"""
+ if not isinstance(tokens, dict):
+ return {}
+
+ def _int(v: Any) -> int:
+ try:
+ return int(v or 0)
+ except Exception:
+ return 0
+
+ prompt = _int(tokens.get("input"))
+ completion = _int(tokens.get("output"))
+ if prompt <= 0 and completion <= 0:
+ return {}
+ return {"prompt_tokens": prompt, "completion_tokens": completion, "total_tokens": prompt + completion}
+
+
+def infer_vendor(model: str | None) -> str:
+ """根据模型名推断一个粗粒度的 provider/vendor 标签。"""
+ text = str(model or "").strip().lower()
+ if not text:
+ return "unknown"
+ if "gpt" in text or "openai" in text:
+ return "openai"
+ if "claude" in text or "anthropic" in text:
+ return "anthropic"
+ if "gemini" in text or "google" in text:
+ return "google"
+ if text.startswith("hy") or "hunyuan" in text:
+ return "tencent"
+ return text.split("/", 1)[0].split("-", 1)[0] or "unknown"
+
+
+def extract_message_text(content: Any) -> str:
+ """把嵌套的 transcript message 内容压平成纯文本。"""
+ if content is None:
+ return ""
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts: list[str] = []
+ for item in content:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif item.get("type") == "tool_use":
+ parts.append(f"[tool_use {item.get('name', '')}]")
+ elif item.get("type") == "tool_result":
+ parts.append(extract_message_text(item.get("content")))
+ else:
+ parts.append(str(item))
+ return "\n".join(p for p in parts if p)
+ if isinstance(content, dict):
+ return extract_message_text(content.get("text") or content.get("content"))
+ return str(content)
+
+
+def find_message_id_in_record(obj: Any) -> str | None:
+ """在 transcript 记录里递归查找稳定的 message 标识。"""
+ message_id_keys = ("messageId", "responseId", "requestId")
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in message_id_keys:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in message_id_keys:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in message_id_keys:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for value in obj.values():
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ elif isinstance(obj, list):
+ for value in obj:
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ return None
+
+
+def collect_tool_calls_for_message(transcript_path: str, message_id: str) -> list[dict[str, Any]]:
+ """为指定 assistant message 重建它挂载的 tool-call 摘要。"""
+ if not transcript_path or not message_id or not os.path.isfile(transcript_path):
+ return []
+ try:
+ with open(transcript_path, "rb") as fp:
+ blob = fp.read()
+ except Exception:
+ return []
+
+ tool_calls: list[dict[str, Any]] = []
+ for raw_line in blob.splitlines(keepends=True):
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("type") or "").strip().lower() != "function_call":
+ continue
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid != message_id:
+ continue
+ call_id = str(rec.get("callId") or "").strip()
+ name = str(rec.get("name") or "").strip()
+ arguments = rec.get("arguments")
+ entry: dict[str, Any] = {"id": call_id, "name": name}
+ if arguments is not None:
+ entry["arguments"] = arguments if isinstance(arguments, str) else json.dumps(arguments, ensure_ascii=False)
+ tool_calls.append(entry)
+ return tool_calls
+
+
+def find_tool_usage_event(tool_event: dict[str, Any], usage_events: list[dict[str, Any]]) -> dict[str, Any] | None:
+ """从 usage 列表里挑出最可能属于当前 tool 事件的那一条。"""
+ tool_name = str(tool_event.get("tool") or "")
+ transcript_path = str(tool_event.get("transcript_path") or "")
+ agent = str(tool_event.get("agent") or "main")
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ if tool_name and str(usage_event.get("tool") or "") not in {tool_name, "model_request"}:
+ continue
+ if str(usage_event.get("message_id") or "").strip():
+ return usage_event
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ return usage_event
+ return None
+
+
+def build_llm_io_from_transcript(
+ *,
+ transcript_path: str,
+ source_offset: int,
+ tokens: dict[str, Any] | None,
+ model: str | None,
+ start_offset: int = 0,
+ current_message_id: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], str]:
+ """从 transcript 历史中构造紧凑版的 LLM 输入/输出负载。"""
+ input_data: dict[str, Any] = {"model": str(model or "unknown"), "messages": []}
+ output_data: dict[str, Any] = {"choices": [], "usage": to_openai_usage(tokens)}
+ if not transcript_path or not os.path.isfile(transcript_path):
+ return input_data, output_data, ""
+ try:
+ with open(transcript_path, "rb") as fp:
+ fp.seek(0)
+ blob = fp.read(source_offset) if source_offset else fp.read()
+ except Exception:
+ return input_data, output_data, ""
+
+ messages: list[dict[str, Any]] = []
+ system_prompts: list[str] = []
+ cursor = 0
+ last_asst_text: str | None = None
+
+ def _truncate(text: str, limit: int = 4000) -> str:
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ for raw_line in blob.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+
+ rec_type = str(rec.get("type") or "").strip().lower()
+ is_incremental = cursor > start_offset
+
+ # 重建 prompt 上下文时要跳过“当前正在发出的 assistant message”,
+ # 否则同一段回复会同时出现在 input 和 output 两边。
+ if current_message_id and is_incremental:
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid == current_message_id:
+ if rec_type == "message" and rec.get("role") == "assistant":
+ text = extract_message_text(rec.get("content"))
+ if text:
+ last_asst_text = text
+ continue
+
+ if rec_type == "message":
+ role = rec.get("role")
+ text = extract_message_text(rec.get("content"))
+ if not text:
+ continue
+ if role == "system":
+ system_prompts.append(text)
+ elif is_incremental:
+ if role == "user":
+ messages.append({"role": "user", "content": _truncate(text, 8000)})
+ last_asst_text = None
+ elif role == "assistant":
+ messages.append({"role": "assistant", "content": _truncate(text, 4000)})
+ last_asst_text = text
+ elif is_incremental:
+ # 把 function call / result 记录转换成 Chat Completions 风格的
+ # assistant/tool message,方便 tracing UI 按对话链路展示。
+ if rec_type == "function_call":
+ name = str(rec.get("name") or "").strip()
+ call_id = str(rec.get("callId") or "").strip()
+ arguments = rec.get("arguments", "")
+ if isinstance(arguments, dict):
+ arguments = json.dumps(arguments, ensure_ascii=False)
+ tool_call: dict[str, Any] = {"type": "function", "function": {"name": name}}
+ if name and arguments:
+ tool_call["function"]["arguments"] = _truncate(str(arguments), 2000)
+ if call_id:
+ tool_call["id"] = call_id
+ if (
+ messages
+ and messages[-1].get("role") == "assistant"
+ and "tool_calls" not in messages[-1]
+ and messages[-1].get("content")
+ ):
+ messages[-1]["tool_calls"] = [tool_call]
+ else:
+ msg: dict[str, Any] = {"role": "assistant", "content": ""}
+ msg["tool_calls"] = [tool_call]
+ messages.append(msg)
+ elif rec_type == "function_call_result":
+ call_id = str(rec.get("callId") or "").strip()
+ provider = rec.get("providerData", {})
+ result_content = ""
+ if isinstance(provider, dict):
+ tool_result = provider.get("toolResult", {})
+ if isinstance(tool_result, dict):
+ result_content = extract_message_text(tool_result.get("content"))
+ if not result_content:
+ output = rec.get("output")
+ result_content = str(output.get("text", "")) if isinstance(output, dict) else ""
+ tool_msg: dict[str, Any] = {"role": "tool", "content": _truncate(result_content, 2000)}
+ if call_id:
+ tool_msg["tool_call_id"] = call_id
+ messages.append(tool_msg)
+
+ final_messages: list[dict[str, Any]] = []
+ for prompt in system_prompts[-2:]:
+ if prompt:
+ final_messages.append({"role": "system", "content": _truncate(prompt, 2000)})
+ final_messages.extend(messages)
+ input_data["messages"] = final_messages
+
+ if last_asst_text is not None:
+ output_data["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": last_asst_text[:8000]},
+ }]
+
+ return input_data, output_data, ""
diff --git a/.claude/skills/agent-observability/scripts/core/agentlens/runtime.py b/.claude/skills/agent-observability/scripts/core/agentlens/runtime.py
new file mode 100644
index 00000000..321f45a9
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agentlens/runtime.py
@@ -0,0 +1,761 @@
+"""AgentLens 运行时编排层。
+
+这一层保留对外暴露的 4 个入口:
+- `emit_session_start`
+- `emit_turn_start`
+- `emit_post_step`
+- `emit_session_stop`
+
+它本身不负责底层清洗或 carrier 生成,而是把调用编排到
+`bootstrap / normalize / tracing` 三层上。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from opentelemetry import trace as _otel_trace
+
+from .. import state as st
+from .bootstrap import (
+ debug_write_span as _debug_write_span,
+ ensure_initialized as _ensure_initialized,
+ get_session_context as _get_session_context,
+ load_config,
+ project_root as _project_root,
+ set_failure as _set_failure,
+)
+from .normalize import (
+ association_properties as _association_properties,
+ build_llm_io_from_transcript as _build_llm_io_from_transcript,
+ find_tool_usage_event as _find_tool_usage_event,
+ infer_vendor as _infer_vendor,
+ sanitize_payload as _sanitize_payload,
+ to_openai_usage as _to_openai_usage,
+)
+from .tracing import (
+ annotate as _annotate,
+ emit_assistant_span as _emit_assistant_span,
+ emit_tool_span as _emit_tool_span,
+ generate_subagent_carrier as _generate_subagent_carrier,
+ generate_turn_carrier as _generate_turn_carrier,
+ resolve_agent_carrier as _resolve_agent_carrier,
+ resolve_step_carrier as _resolve_step_carrier,
+ set_agent_aggregate_on_span as _set_agent_aggregate_on_span,
+ span_context_ids as _span_context_ids,
+ traceparent_parts as _traceparent_parts,
+)
+
+
+def emit_session_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ agent: str = "main",
+) -> None:
+ """初始化 v2 版本的 `_agentlens` session payload。
+
+ 在 turn-centric 模型下,这里**不再**生成 trace_id。
+ 它只负责记录 session 级元数据(如 `enabled`、`session_id`、`app_name`),
+ 并清理上一次运行遗留的 carrier / error 状态。
+ 真正的新 trace 会在第一次 `UserPromptSubmit` 时由 `emit_turn_start` 打开。
+ """
+ _ = agent
+ config = load_config(_project_root(cwd))
+ # 注意:这里不要清空 current_turn / turn_history。
+ # 同一个 sid 下 SessionStart 可能多次触发(例如 subagent 启动、IDE 刷新、
+ # workspace 切换)。如果这里清空,会把进行中的 turn 擦掉,后续 PostToolUse
+ # 会全部看到 no_active_turn,最终把这一轮观测链路打断。
+ base_updates: dict[str, Any] = {
+ "session_id": sid,
+ "app_name": config.app_name,
+ }
+ if not config.enabled:
+ base_updates["enabled"] = False
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ base_updates["enabled"] = True
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_turn_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ turn_id: str,
+ prompt_meta: dict[str, Any] | None = None,
+ business_scenario: str | None = None,
+) -> None:
+ """打开一个新的 turn,生成新的 trace_id 并写入 `_agentlens.current_turn`。
+
+ 这是当前实现里**唯一**允许生成新 trace_id 的地方。
+ `emit_post_step` / `emit_session_stop` 都不会重新造 carrier;
+ 找不到时只会优雅降级,不会私自开新链路。
+ """
+ _ = prompt_meta
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ # 先把 per-turn business scenario 写进 state,
+ # 这样 `_generate_turn_carrier -> _association_properties`
+ # 才能在生成 trace 时把这次 turn 的业务场景烘焙进去。
+ if business_scenario:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name, "_turn_business_scenario": business_scenario},
+ clear_keys=["last_error"],
+ )
+ else:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name},
+ clear_keys=["last_error", "_turn_business_scenario"],
+ )
+ carrier = _generate_turn_carrier(runtime, config=config, sid=sid, turn_id=turn_id, state_path=state_path)
+ st.begin_turn(state_path, sid, turn_id, carrier)
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_post_step(
+ *,
+ state_path: Path,
+ sid: str,
+ tool_event: dict[str, Any] | None,
+ usage_events: list[dict[str, Any]],
+) -> None:
+ """发出扁平化的 LLM span,只保留最小 TASK 包装层来传播 carrier 上下文。
+
+ 面向 turn 的 v2 约束:
+ - 活跃的 ``current_turn.carrier`` 是唯一的 trace 上下文来源。
+ - 如果不存在 ``current_turn``(例如 UserPromptSubmit hook 还没触发),
+ 这里只会记录 ``last_error`` 并返回,不会私自生成新的 trace_id。
+ - subagent(``active_agent != "main"``)会拿到当前 turn 下的
+ ``invoke_agent`` 子 span,后续 chat span 都挂到这个子 span 下,
+ 以保持因果链路连续。
+ """
+ if not isinstance(tool_event, dict) and not usage_events:
+ return
+
+ cwd_hint = ""
+ if isinstance(tool_event, dict):
+ cwd_hint = str(tool_event.get("cwd") or "")
+ config = load_config(_project_root(cwd_hint))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ # 快路径:尊重 SessionStart 阶段已经写入的 enabled 标记。
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ parent_carrier = current_turn.get("carrier")
+ if not isinstance(parent_carrier, dict) or not parent_carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ tool_name = str((tool_event or {}).get("tool") or "unknown_tool")
+ active_agent = str((tool_event or {}).get("agent") or "main")
+ transcript_path = str((tool_event or {}).get("transcript_path") or "")
+ skills = (tool_event or {}).get("skill") or []
+ rules = (tool_event or {}).get("rule") or []
+
+ # 解析这次事件真正要用的 carrier。
+ # main agent 直接使用 turn 根 carrier;subagent 则使用按角色拆分的
+ # 子 span carrier,并在当前 turn 下做幂等注册。
+ carrier = dict(parent_carrier)
+ if active_agent and active_agent != "main":
+ existing = None
+ subs = current_turn.get("subagent_spans")
+ if isinstance(subs, dict):
+ rec = subs.get(active_agent)
+ if isinstance(rec, dict) and isinstance(rec.get("carrier"), dict):
+ existing = rec["carrier"]
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ carrier = dict(existing)
+ else:
+ # 原子化的 get-or-create:只有确认 subagent span 不存在时,
+ # 才会在写锁内部调用 carrier_factory。
+ # 这样可以避免并发 hook 进程之间的 TOCTOU 竞争,产生孤儿
+ # invoke_agent.TASK span。
+ def _factory() -> dict[str, str]:
+ return _generate_subagent_carrier(
+ runtime, parent_carrier=parent_carrier, role=active_agent
+ )
+
+ registered = st.upsert_subagent_span_atomic(
+ state_path, sid, active_agent, carrier_factory=_factory
+ )
+ if isinstance(registered, dict) and registered.get("traceparent"):
+ carrier = dict(registered)
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ # 静默挂载 carrier 上下文(不额外创建 TASK span),让内部 span
+ # 继承正确的 trace_id / parent_id。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ preferred_tool_message_id = str((tool_event or {}).get("message_id") or "").strip() or None
+ _assistant_emitted_mids: set[str] = set()
+ pre_bumped_steps: set[tuple[str, str]] = set()
+ committed_steps: set[tuple[str, str]] = set()
+
+ if isinstance(tool_event, dict):
+ if preferred_tool_message_id and st.get_step_span_carrier(
+ state_path, sid, active_agent, preferred_tool_message_id
+ ) is None:
+ pre_bumped_steps.add((active_agent, preferred_tool_message_id))
+ for usage_event in usage_events:
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ if event_message_id:
+ step_key = (event_agent, event_message_id)
+ if (
+ step_key not in pre_bumped_steps
+ and st.get_step_span_carrier(state_path, sid, event_agent, event_message_id) is None
+ ):
+ pre_bumped_steps.add(step_key)
+ if not usage_events and isinstance(tool_event, dict):
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if preferred_tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=preferred_tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=preferred_tool_message_id,
+ step_grouping="message_id" if preferred_tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if (
+ preferred_tool_message_id
+ and (active_agent, preferred_tool_message_id) in pre_bumped_steps
+ and (active_agent, preferred_tool_message_id) not in committed_steps
+ ):
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add((active_agent, preferred_tool_message_id))
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ return
+
+ matched_usage = _find_tool_usage_event(tool_event, usage_events) if isinstance(tool_event, dict) else None
+ tool_message_id = preferred_tool_message_id or str((matched_usage or {}).get("message_id") or "").strip() or None
+ if isinstance(tool_event, dict):
+ # 先构造 assistant 预览,再打开 agent/step 父 span。
+ # 这样即便 transcript 重建失败,也不会留下空的分组 TASK。
+ _assistant_preview_content: str | None = None
+ _assistant_preview_transcript = transcript_path
+ _assistant_preview_model = ""
+ if tool_message_id:
+ for _ue in usage_events:
+ if str(_ue.get("message_id") or "").strip() != tool_message_id:
+ continue
+ _ue_transcript = str(_ue.get("transcript_path") or transcript_path)
+ _ue_offset = int(_ue.get("source_offset") or 0)
+ _, _llm_out_pre, _ = _build_llm_io_from_transcript(
+ transcript_path=_ue_transcript,
+ source_offset=_ue_offset,
+ tokens=_ue.get("tokens"),
+ model=str(_ue.get("model") or ""),
+ )
+ _pre_content = ""
+ if _llm_out_pre.get("choices"):
+ _pre_msg = _llm_out_pre["choices"][0].get("message") or {}
+ _pre_content = str(_pre_msg.get("content") or "")
+ if _pre_content and _pre_content.strip():
+ _assistant_preview_content = _pre_content
+ _assistant_preview_transcript = _ue_transcript
+ _assistant_preview_model = str(_ue.get("model") or "")
+ break
+
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ if _assistant_preview_content and tool_message_id:
+ _emit_assistant_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ assistant_text=_assistant_preview_content,
+ model=_assistant_preview_model,
+ transcript_path=_assistant_preview_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ _assistant_emitted_mids.add(tool_message_id)
+
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=tool_message_id,
+ step_grouping="message_id" if tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if tool_message_id and (active_agent, tool_message_id) in pre_bumped_steps:
+ step_key = (active_agent, tool_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+
+ _prev_llm_offsets: dict[str, int] = {}
+ for usage_event in usage_events:
+ model = str(usage_event.get("model") or "")
+ ev_transcript = str(usage_event.get("transcript_path") or transcript_path)
+ ev_offset = int(usage_event.get("source_offset") or 0)
+ raw_tokens = usage_event.get("tokens") or {}
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ start_offset = _prev_llm_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_llm_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset)
+ # --- 把 skill/rule/agent 作为独立消息标签注入 input_data ---
+ _meta_messages: list[dict[str, str]] = []
+ _ev_agent = str(usage_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ _meta_messages.append({"role": "agent", "content": _ev_agent})
+ if skills:
+ _meta_messages.append({"role": "skill", "content": ", ".join(skills)})
+ if rules:
+ _meta_messages.append({"role": "rule", "content": ", ".join(rules)})
+ if _meta_messages:
+ llm_input.setdefault("messages", [])
+ for msg in reversed(_meta_messages):
+ llm_input["messages"].insert(0, msg)
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 只附带成本细节来构造 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": usage_event.get("cost_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ if event_message_id:
+ event_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 先累计聚合值,再发 LLM span,这样 span 上带的是最新累计属性。
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ usage_event=usage_event,
+ )
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(usage_event.get("cost_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if event_message_id and (event_agent, event_message_id) in pre_bumped_steps:
+ step_key = (event_agent, event_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+ if _existing_content and _existing_content.strip() and event_message_id not in _assistant_emitted_mids:
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_session_stop(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str,
+ transcript_path: str,
+ stop_events: list[dict[str, Any]],
+) -> None:
+ """在 session stop 阶段发出扁平化 LLM span,只保留最小 TASK 包装层传播上下文。"""
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ carrier = current_turn.get("carrier")
+ if not isinstance(carrier, dict) or not carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ if not stop_events:
+ return
+ # 静默挂载 carrier 上下文(不额外创建 TASK span)。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ _prev_stop_offsets: dict[str, int] = {}
+ for stop_event in stop_events:
+ model = str(stop_event.get("model") or "")
+ ev_transcript = str(stop_event.get("transcript_path") or transcript_path)
+ ev_offset = int(stop_event.get("source_offset") or 0)
+ raw_tokens = stop_event.get("tokens") or {}
+ event_message_id = str(stop_event.get("message_id") or "").strip() or None
+ event_agent = str(stop_event.get("agent") or active_agent or "main")
+ start_offset = _prev_stop_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_stop_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset_stop(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset_stop)
+ # --- 把 agent 作为独立消息标签注入 input_data ---
+ _ev_agent = str(stop_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ llm_input.setdefault("messages", []).insert(0, {"role": "agent", "content": _ev_agent})
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 构造带上下文和成本细节的 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": stop_event.get("cost_usd"),
+ "cost_session_usd": stop_event.get("cost_session_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ # 先解析 agent carrier,让 step 挂在 agent 的 react_agent span 下,
+ # 而不是直接挂在 turn 根 span 下。
+ if event_agent and event_agent != "main":
+ agent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ if isinstance(agent_carrier, dict) and agent_carrier.get("traceparent"):
+ event_parent_carrier = dict(agent_carrier)
+ if event_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 这里不要再 bump,emit_post_step 已经累计过这条 usage_event。
+ # SessionStop 会为同一次调用补发一个重复的 LLM span,再累加就会双算。
+ # 因此这里只读取当前聚合值。
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(stop_event.get("cost_usd") or "-"),
+ "cost_session_usd": str(stop_event.get("cost_session_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if _existing_content and _existing_content.strip():
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
diff --git a/.claude/skills/agent-observability/scripts/core/agentlens/tracing.py b/.claude/skills/agent-observability/scripts/core/agentlens/tracing.py
new file mode 100644
index 00000000..afb678ad
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/agentlens/tracing.py
@@ -0,0 +1,504 @@
+from __future__ import annotations
+"""AgentLens trace 拓扑层。
+
+这一层负责“trace 结构本身”:
+- 创建或派生 carrier
+- 生成 agent / step / assistant / tool span
+- 把后续聚合需要的 span 元数据写回 state
+"""
+
+import json
+import secrets
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig, debug_write_span
+from .normalize import association_properties, collect_tool_calls_for_message, sanitize_payload
+
+
+def annotate(runtime: dict[str, Any], *, span: Any | None = None, input_data: Any = None, output_data: Any = None, tags: dict[str, Any] | None = None) -> None:
+ """在调用 zhiyan annotate 前,先统一清洗 payload。"""
+ _ = span
+ runtime["Zhiyanllm"].annotate(
+ input_data=sanitize_payload(input_data),
+ output_data=sanitize_payload(output_data),
+ tags=sanitize_payload(tags) if tags else None,
+ )
+
+
+def traceparent_parts(carrier: dict[str, str] | None) -> dict[str, str]:
+ """把 W3C `traceparent` 拆成调试日志里常用的几个字段。"""
+ traceparent = str((carrier or {}).get("traceparent") or "").strip()
+ parts = traceparent.split("-")
+ if len(parts) >= 4:
+ return {
+ "traceparent": traceparent,
+ "trace_id": parts[1],
+ "span_id": parts[2],
+ "flags": parts[3],
+ }
+ return {"traceparent": traceparent}
+
+
+def span_context_ids(span: Any) -> dict[str, str]:
+ """从 OTel span 对象中提取十六进制的 trace/span id。"""
+ try:
+ ctx = span.get_span_context()
+ return {
+ "trace_id": f"{int(ctx.trace_id):032x}",
+ "span_id": f"{int(ctx.span_id):016x}",
+ }
+ except Exception:
+ return {}
+
+
+def ensure_traceparent(carrier: dict[str, str]) -> None:
+ """当上游没有成功注入时,补一个最小可用的 `traceparent`。"""
+ if str(carrier.get("traceparent") or "").strip():
+ return
+ trace_id = secrets.token_hex(16)
+ parent_id = secrets.token_hex(8)
+ carrier["traceparent"] = f"00-{trace_id}-{parent_id}-01"
+
+
+def carrier_from_span(parent_carrier: dict[str, str], span: Any) -> dict[str, str]:
+ """基于父 carrier 和当前 span 生成一个仍在同一 trace 上的子 carrier。"""
+ try:
+ span_ctx = span.get_span_context()
+ trace_id = f"{int(span_ctx.trace_id):032x}"
+ span_id = f"{int(span_ctx.span_id):016x}"
+ except Exception:
+ return {}
+ parent_tp = str((parent_carrier or {}).get("traceparent") or "").strip()
+ flags = "01"
+ if parent_tp:
+ parts = parent_tp.split("-")
+ if len(parts) >= 4 and parts[3]:
+ flags = parts[3]
+ child_carrier: dict[str, str] = dict(parent_carrier or {})
+ child_carrier["traceparent"] = f"00-{trace_id}-{span_id}-{flags}"
+ return child_carrier
+
+
+def carrier_from_task_span(parent_carrier: dict[str, str], task_span: Any) -> dict[str, str]:
+ """兼容包装过的 task span 和原始 OTel span 两种形态。"""
+ span = getattr(task_span, "_span", None)
+ if span is None and hasattr(task_span, "get_span_context"):
+ span = task_span
+ if span is None:
+ return {}
+ return carrier_from_span(parent_carrier, span)
+
+
+def zhiyan_attr(runtime: dict[str, Any], name: str, fallback: str) -> str:
+ """防御式读取 zhiyan 语义约定常量。"""
+ return str(getattr(runtime.get("ZhiyanSpanAttributes"), name, fallback))
+
+
+def generate_turn_carrier(
+ runtime: dict[str, Any],
+ *,
+ config: AgentLensConfig,
+ sid: str,
+ turn_id: str,
+ state_path: Path | None = None,
+) -> dict[str, str]:
+ """为一个用户 turn 生成根 carrier。"""
+ from opentelemetry import trace
+
+ carrier: dict[str, str] = {}
+ span = trace.get_tracer(__name__).start_span(f"turn.{sid}.{turn_id}")
+ try:
+ runtime["Zhiyanllm"].set_association_properties(association_properties(config, sid, state_path))
+ runtime["Zhiyanllm"].inject_context(carrier)
+ finally:
+ span.end()
+ ensure_traceparent(carrier)
+ return carrier
+
+
+def generate_subagent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], role: str) -> dict[str, str]:
+ """在当前 turn 下面创建 `invoke_agent` 子 carrier。"""
+ try:
+ with runtime["track_task_server_call"]("invoke_agent", carrier=parent_carrier) as task_span:
+ annotate(runtime, input_data={"agent": role}, output_data={"result": "dispatched"}, tags={"agent": role})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_step_carrier(
+ runtime: dict[str, Any],
+ *,
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str,
+ transcript_path: str,
+) -> dict[str, str]:
+ """创建用于归并同一条 message 工作的 synthetic step span。"""
+ try:
+ with runtime["track_task_server_call"]("react_step", carrier=parent_carrier) as task_span:
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id},
+ output_data={"result": "grouped"},
+ tags={"message_id": message_id, "agent": agent, "transcript_path": transcript_path or ""},
+ )
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_agent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], agent: str) -> dict[str, str]:
+ """在当前 turn 下创建稳定的 per-agent 聚合 span。"""
+ try:
+ with runtime["track_task_server_call"]("react_agent", carrier=parent_carrier) as task_span:
+ span = getattr(task_span, "_span", None)
+ if span is not None and hasattr(span, "set_attribute"):
+ span.set_attribute("agent.name", agent)
+ annotate(runtime, input_data={"agent": agent}, output_data={"agent": agent}, tags={"agent": agent})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def resolve_agent_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+) -> dict[str, str]:
+ """从共享状态里获取或创建持久化的 agent 聚合 carrier。"""
+ normalized_agent = str(agent or "main").strip() or "main"
+ existing = st.get_agent_span_carrier(state_path, sid, normalized_agent)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_agent_carrier(runtime, parent_carrier=parent_carrier, agent=normalized_agent)
+
+ effective_carrier = st.upsert_agent_span_atomic(state_path, sid, normalized_agent, carrier_factory=_factory)
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return dict(parent_carrier)
+ agent_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "agent",
+ "span_name": "react_agent",
+ "agent": normalized_agent,
+ "trace_id": agent_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": agent_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def resolve_step_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ transcript_path: str,
+) -> dict[str, str] | None:
+ """获取或创建按 message 分组使用的 step carrier。"""
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return None
+ existing = st.get_step_span_carrier(state_path, sid, agent, normalized_message_id)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_step_carrier(
+ runtime,
+ parent_carrier=parent_carrier,
+ agent=agent,
+ message_id=normalized_message_id,
+ transcript_path=transcript_path,
+ )
+
+ effective_carrier = st.upsert_step_span_atomic(
+ state_path,
+ sid,
+ agent,
+ normalized_message_id,
+ carrier_factory=_factory,
+ transcript_path=transcript_path,
+ )
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return None
+ step_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "step",
+ "span_name": "react_step",
+ "message_id": normalized_message_id,
+ "agent": agent,
+ "trace_id": step_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": step_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": transcript_path or "",
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def set_agent_aggregate_on_span(span: Any, aggregate: dict[str, Any] | None) -> None:
+ """把 agent 的累计指标投影成当前 span 的属性。"""
+ if span is None or not hasattr(span, "set_attribute") or not isinstance(aggregate, dict):
+ return
+ tokens = aggregate.get("tokens") or {}
+ if isinstance(tokens, dict):
+ for key in ("input", "output", "cache_read", "cache_creation", "total"):
+ if key in tokens:
+ span.set_attribute(f"agent.cumulative_tokens.{key}", int(tokens.get(key) or 0))
+ for key in ("cost_usd", "tool_duration_ms", "llm_call_count", "tool_call_count", "step_count", "event_count"):
+ if key in aggregate:
+ try:
+ span.set_attribute(f"agent.cumulative.{key}", int(aggregate.get(key) or 0))
+ except (TypeError, ValueError):
+ span.set_attribute(f"agent.cumulative.{key}", str(aggregate.get(key)))
+
+
+def emit_assistant_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ assistant_text: str,
+ model: str | None = None,
+ transcript_path: str | None = None,
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出一个轻量 assistant span,并按需补上 tool calls。"""
+ if not assistant_text or not assistant_text.strip():
+ return
+ tool_calls: list[dict[str, Any]] = []
+ if message_id and transcript_path:
+ tool_calls = collect_tool_calls_for_message(transcript_path, message_id)
+ output_data: dict[str, Any] = {"role": "assistant", "content": assistant_text[:8000]}
+ if tool_calls:
+ output_data["tool_calls"] = tool_calls
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name="assistant_message") as span:
+ span.set_attribute(runtime["ZhiyanSpanAttributes"].LLM_SPAN_KIND, runtime["ZhiyanllmSpanKindValues"].LLM.value)
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "assistant",
+ "span_name": "assistant_message",
+ "message_id": str(message_id or ""),
+ "agent": agent,
+ "model": str(model or ""),
+ "tool_call_count": len(tool_calls),
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id or "", "model": model or ""},
+ output_data=output_data,
+ tags={"message_id": str(message_id or ""), "agent": agent},
+ )
+ finally:
+ runtime["otel_detach"](token)
+
+
+def emit_tool_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ tool_name: str,
+ active_agent: str,
+ skills: list[str],
+ rules: list[str],
+ duration_ms: int | None = None,
+ tool_details: dict[str, Any] | None = None,
+ message_id: str | None = None,
+ step_grouping: str = "fallback",
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出 tool span,并以受控大小挂载 tool payload。"""
+ def _truncate(value: Any, limit: int = 1200) -> Any:
+ text = value if isinstance(value, str) else None
+ if text is None:
+ return value
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ def _maybe_parse_json_text(value: Any) -> Any:
+ if not isinstance(value, str):
+ return value
+ text = value.strip()
+ if not text or text[0] not in "{[":
+ return value
+ try:
+ return json.loads(text)
+ except Exception:
+ return value
+
+ def _parse_bash_result_content(value: Any) -> dict[str, Any] | None:
+ if not isinstance(value, str) or "Command:" not in value:
+ return None
+ normalized_value = value.replace("\\n", "\n")
+ markers = [
+ ("Command:", "command"),
+ ("Stdout:", "stdout"),
+ ("Stderr:", "stderr"),
+ ("Exit Code:", "exit_code"),
+ ("Signal:", "signal"),
+ ]
+ parsed: dict[str, Any] = {}
+ for idx, (marker, key) in enumerate(markers):
+ start = normalized_value.find(marker)
+ if start < 0:
+ continue
+ start += len(marker)
+ end = len(normalized_value)
+ for next_marker, _ in markers[idx + 1:]:
+ pos = normalized_value.find(next_marker, start)
+ if pos >= 0:
+ end = min(end, pos)
+ segment = normalized_value[start:end].strip()
+ if not segment:
+ continue
+ parsed[key] = _truncate(segment, 1200 if key in {"command", "stdout", "stderr"} else 200)
+ return parsed or None
+
+ tool_input: dict[str, Any] = {"tool": tool_name, "agent": active_agent}
+ if skills:
+ tool_input["skill"] = ", ".join(skills)
+ if rules:
+ tool_input["rule"] = ", ".join(rules)
+ if message_id:
+ tool_input["message_id"] = message_id
+ details = dict(tool_details or {})
+ call_id = str(details.get("call_id") or "").strip() or None
+ if call_id:
+ tool_input["call_id"] = call_id
+ arguments_display_text = details.get("arguments_display_text")
+ if arguments_display_text:
+ tool_input["arguments_display_text"] = _truncate(arguments_display_text, 600)
+ arguments = details.get("arguments")
+ if arguments:
+ parsed_arguments = _maybe_parse_json_text(arguments)
+ tool_input["arguments"] = _truncate(parsed_arguments, 1200)
+ if isinstance(parsed_arguments, dict):
+ if parsed_arguments.get("command"):
+ tool_input["command"] = _truncate(parsed_arguments.get("command"), 1200)
+ if parsed_arguments.get("description"):
+ tool_input["description"] = _truncate(parsed_arguments.get("description"), 400)
+
+ tool_output: dict[str, Any] = {"result": "executed"}
+ result_content = details.get("result_content")
+ if result_content is not None:
+ structured_result = _parse_bash_result_content(result_content)
+ if structured_result:
+ tool_output["result"] = structured_result
+ else:
+ tool_output["result_content"] = _truncate(result_content, 1600)
+ output_text = details.get("output_text")
+ if output_text:
+ tool_output["output_text"] = _truncate(output_text, 1600)
+ raw_response = details.get("raw_response")
+ if isinstance(raw_response, dict):
+ tool_output["raw_response"] = {
+ "exitCode": raw_response.get("exitCode"),
+ "signal": raw_response.get("signal"),
+ "interrupted": raw_response.get("interrupted"),
+ "sandboxDenied": raw_response.get("sandboxDenied"),
+ "tool_error_code": raw_response.get("tool_error_code"),
+ }
+
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name=f"{tool_name}.TOOL") as span:
+ span_kind_value = runtime["ZhiyanllmSpanKindValues"].TOOL.value
+ span.set_attribute(zhiyan_attr(runtime, "LLM_SPAN_KIND", "gen_ai.span.kind"), span_kind_value)
+ span.set_attribute("gen_ai.span.kind", span_kind_value)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_NAME", "tool.name"), tool_name)
+ if isinstance(tool_details, dict):
+ desc = tool_details.get("description") or tool_details.get("tool_description")
+ if isinstance(desc, str) and desc.strip():
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_DESCRIPTION", "tool.description"), desc.strip())
+ tool_params = tool_input.get("arguments")
+ if tool_params is not None:
+ if not isinstance(tool_params, str):
+ tool_params = json.dumps(tool_params, ensure_ascii=False, default=str)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_PARAMETERS", "tool.parameters"), tool_params)
+ if duration_ms is not None:
+ span.set_attribute("tool.duration_ms", int(duration_ms))
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "tool",
+ "span_name": f"{tool_name}.TOOL",
+ "tool": tool_name,
+ "message_id": str(message_id or ""),
+ "call_id": call_id or "",
+ "step_grouping": step_grouping,
+ "agent": active_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data=tool_input,
+ output_data=tool_output,
+ tags={"step_grouping": step_grouping, "message_id": str(message_id or "")},
+ )
+ finally:
+ runtime["otel_detach"](token)
diff --git a/.claude/skills/agent-observability/scripts/core/cls_sink.py b/.claude/skills/agent-observability/scripts/core/cls_sink.py
new file mode 100644
index 00000000..6525f6ed
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/cls_sink.py
@@ -0,0 +1,470 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import struct
+import subprocess
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .agentlens import bootstrap
+
+
+
+@dataclass(frozen=True)
+class CLSConfig:
+ enabled: bool
+ endpoint: str
+ topic_id: str
+ secret_id: str
+ secret_key: str
+ secret_token: str
+ service_name: str
+ timeout_seconds: int
+ helper_path: Path
+ sdk_entry_path: Path
+
+ @property
+ def ready(self) -> bool:
+ return bool(
+ self.enabled
+ and self.endpoint
+ and self.topic_id
+ and self.secret_id
+ and self.secret_key
+ and self.helper_path.is_file()
+ and self.sdk_entry_path.is_file()
+ )
+
+
+def repo_root() -> Path:
+ return Path(__file__).resolve().parents[5]
+
+
+def helper_path() -> Path:
+ return Path(__file__).with_name("cls_uploader.mjs")
+
+
+def sdk_entry_path() -> Path:
+ return (
+ repo_root()
+ / "cls-codebuddy"
+ / "tencentcloud-cls-sdk-codebuddy"
+ / "node_modules"
+ / "tencentcloud-cls-sdk-js"
+ / "dist"
+ / "index.js"
+ )
+
+
+def debug_log_path() -> Path:
+ return Path(__file__).resolve().parents[2] / "logs" / "cls-push-debug.ndjson"
+
+
+def _value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: str = "",
+ aliases: tuple[str, ...] = (),
+) -> str:
+ keys = (name, *aliases)
+ for key in keys:
+ raw = os.environ.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_local.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_file.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ return default
+
+
+def _enabled_flag(*, env_local: dict[str, str], env_file: dict[str, str]) -> bool:
+ raw = _value(
+ "CLS_CODINGAGENT_ENABLED",
+ env_local=env_local,
+ env_file=env_file,
+ default="1",
+ )
+ return str(raw).strip().lower() not in {"0", "false", "off", "no"}
+
+
+def _debug_write(payload: dict[str, Any]) -> None:
+ try:
+ path = debug_log_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(payload, ensure_ascii=False) + "\n")
+ except Exception:
+ return
+
+
+# ---- CLS PutLogs 的 protobuf 编码 ----
+# CLS 使用了简化版 protobuf:
+# LogGroup { repeated Log logs = 1; optional string filename = 2; }
+# Log { optional uint32 time = 1; repeated Content contents = 2; }
+# Content { optional string key = 1; optional string value = 2; }
+
+def _encode_varint(value: int) -> bytes:
+ result = b""
+ while value > 0x7F:
+ result += bytes([(value & 0x7F) | 0x80])
+ value >>= 7
+ result += bytes([value & 0x7F])
+ return result
+
+def _encode_field(field_number: int, wire_type: int, data: bytes) -> bytes:
+ tag = (field_number << 3) | wire_type
+ return _encode_varint(tag) + data
+
+def _encode_string_field(field_number: int, value: str) -> bytes:
+ encoded = value.encode("utf-8")
+ return _encode_field(field_number, 2, _encode_varint(len(encoded)) + encoded)
+
+def _encode_uint32_field(field_number: int, value: int) -> bytes:
+ return _encode_field(field_number, 0, _encode_varint(value))
+
+def _encode_content(key: str, value: str) -> bytes:
+ msg = b""
+ if key:
+ msg += _encode_string_field(1, key)
+ if value:
+ msg += _encode_string_field(2, value)
+ return msg
+
+def _encode_log(record: dict[str, Any], service_name: str) -> bytes:
+ ts = record.get("ts")
+ if isinstance(ts, (int, float)):
+ log_time = int(ts) if ts < 1_000_000_000_000 else int(ts / 1000)
+ else:
+ log_time = int(time.time())
+
+ msg = _encode_uint32_field(1, log_time)
+
+ merged = {"service_name": service_name, **record}
+ for key, value in merged.items():
+ if value is None:
+ continue
+ if isinstance(value, (dict, list)):
+ value = json.dumps(value, ensure_ascii=False)
+ else:
+ value = str(value)
+ msg += _encode_field(2, 2, _encode_varint(len(_encode_content(key, value))) + _encode_content(key, value))
+
+ return msg
+
+def _encode_log_group(records: list[dict[str, Any]], service_name: str) -> bytes:
+ msg = b""
+ for record in records:
+ log_bytes = _encode_log(record, service_name)
+ msg += _encode_field(1, 2, _encode_varint(len(log_bytes)) + log_bytes)
+ if service_name:
+ msg += _encode_string_field(2, service_name)
+ return msg
+
+def _encode_log_group_list(records: list[dict[str, Any]], service_name: str) -> bytes:
+ """编码 LogGroupList protobuf:`message LogGroupList { repeated LogGroup logGroupList = 1; }`。"""
+ log_group_bytes = _encode_log_group(records, service_name)
+ return _encode_field(1, 2, _encode_varint(len(log_group_bytes)) + log_group_bytes)
+
+
+# ---- CLS API v3 使用的 TC3-HMAC-SHA256 签名 ----
+
+def _hmac_sha256(key: bytes, data: str) -> bytes:
+ return hmac.new(key, data.encode("utf-8"), hashlib.sha256).digest()
+
+def _sha256_hex(data: str) -> str:
+ return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+def _put_logs_via_api(
+ endpoint: str,
+ topic_id: str,
+ secret_id: str,
+ secret_key: str,
+ log_group_bytes: bytes,
+ region: str = "ap-guangzhou",
+ timeout: int = 20,
+) -> tuple[bool, str]:
+ """通过 CLS API v3 发送 UploadLog,并使用 TC3-HMAC-SHA256 签名。
+
+ `log_group_bytes` 应该是一个 LogGroupList protobuf。
+ """
+ host = endpoint
+ service = "cls"
+ action = "UploadLog"
+ version = "2020-10-16"
+ algorithm = "TC3-HMAC-SHA256"
+ content_type = "application/octet-stream"
+
+ timestamp = int(time.time())
+ date_str = time.strftime("%Y-%m-%d", time.gmtime(timestamp))
+
+ # 请求体就是原始 protobuf 字节串(LogGroupList)
+ payload = log_group_bytes
+ hashed_payload = hashlib.sha256(payload).hexdigest()
+
+ # 规范化请求串
+ canonical_headers = f"content-type:{content_type}\nhost:{host}\nx-tc-action:{action.lower()}\n"
+ signed_headers = "content-type;host;x-tc-action"
+ canonical_request = f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+
+ # 待签名字符串
+ credential_scope = f"{date_str}/{service}/tc3_request"
+ hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
+ string_to_sign = f"{algorithm}\n{timestamp}\n{credential_scope}\n{hashed_canonical_request}"
+
+ # 签名结果
+ secret_date = _hmac_sha256(("TC3" + secret_key).encode("utf-8"), date_str)
+ secret_service = _hmac_sha256(secret_date, service)
+ secret_signing = _hmac_sha256(secret_service, "tc3_request")
+ signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+ authorization = f"{algorithm} Credential={secret_id}/{credential_scope}, SignedHeaders={signed_headers}, Signature={signature}"
+
+ # 构造 HTTP 请求
+ url = f"https://{host}"
+ headers = {
+ "Authorization": authorization,
+ "Content-Type": content_type,
+ "Host": host,
+ "X-TC-Action": action,
+ "X-TC-Timestamp": str(timestamp),
+ "X-TC-Version": version,
+ "X-TC-Region": region,
+ "X-CLS-TopicId": topic_id,
+ "Content-Length": str(len(payload)),
+ }
+
+ req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ body = resp.read().decode("utf-8", errors="replace")
+ if resp.status == 200:
+ return True, body
+ else:
+ return False, f"HTTP {resp.status}: {body}"
+ except urllib.error.HTTPError as e:
+ body = e.read().decode("utf-8", errors="replace")[:500]
+ return False, f"HTTP {e.code}: {body}"
+ except Exception as e:
+ return False, f"{type(e).__name__}: {e}"
+
+
+def _int_value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: int,
+ aliases: tuple[str, ...] = (),
+) -> int:
+ raw = _value(name, env_local=env_local, env_file=env_file, default=str(default), aliases=aliases)
+ try:
+ parsed = int(raw)
+ except Exception:
+ return default
+ return parsed if parsed > 0 else default
+
+
+def load_config(cwd: str | None = None) -> CLSConfig:
+ project_root = bootstrap.project_root(cwd)
+ env_file = bootstrap.read_env_file(project_root / ".env")
+ env_local = bootstrap.read_env_file(project_root / ".env.local")
+ return CLSConfig(
+ enabled=_enabled_flag(env_local=env_local, env_file=env_file),
+ endpoint=_value(
+ "CLS_ENDPOINT",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ topic_id=_value(
+ "CLS_TOPIC_ID",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ secret_id=_value(
+ "CLS_SECRET_ID",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID_438167613",
+ ),
+ ),
+ secret_key=_value(
+ "CLS_SECRET_KEY",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY_438167613",
+ ),
+ ),
+ secret_token=_value(
+ "CLS_SECRET_TOKEN",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=("TC_SECRET_TOKEN", "TC_SESSION_TOKEN", "CLS_SESSION_TOKEN"),
+ ),
+ service_name=_value(
+ "CLS_SERVICE_NAME",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ timeout_seconds=_int_value(
+ "CLS_UPLOAD_TIMEOUT_SECONDS",
+ env_local=env_local,
+ env_file=env_file,
+ default=0,
+ aliases=("CLS_TIMEOUT_SECONDS",),
+ ),
+ helper_path=helper_path(),
+ sdk_entry_path=sdk_entry_path(),
+ )
+
+
+def mirror_record(record: dict[str, Any], *, cwd: str | None = None) -> bool:
+ config = load_config(cwd)
+ if not config.ready:
+ _debug_write(
+ {
+ "stage": "config_not_ready",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "secret_id_present": bool(config.secret_id),
+ "secret_key_present": bool(config.secret_key),
+ "secret_token_present": bool(config.secret_token),
+ "timeout_seconds": config.timeout_seconds,
+ "helper_exists": config.helper_path.is_file(),
+ "sdk_exists": config.sdk_entry_path.is_file(),
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_start",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 先尝试 Python 原生 API v3 上报(兼容内网 endpoint)
+ try:
+ log_group_bytes = _encode_log_group_list([record], config.service_name)
+ success, detail = _put_logs_via_api(
+ endpoint=config.endpoint,
+ topic_id=config.topic_id,
+ secret_id=config.secret_id,
+ secret_key=config.secret_key,
+ log_group_bytes=log_group_bytes,
+ timeout=config.timeout_seconds,
+ )
+ if success:
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "method": "python_api_v3",
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
+ else:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "method": "python_api_v3",
+ "error": detail[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "method": "python_api_v3",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 回退方案:使用 node SDK uploader
+ payload = {
+ "endpoint": config.endpoint,
+ "topicId": config.topic_id,
+ "secretId": config.secret_id,
+ "secretKey": config.secret_key,
+ "secretToken": config.secret_token,
+ "serviceName": config.service_name,
+ "records": [record],
+ }
+ try:
+ completed = subprocess.run(
+ ["node", str(config.helper_path), str(config.sdk_entry_path)],
+ input=json.dumps(payload, ensure_ascii=False),
+ text=True,
+ capture_output=True,
+ check=False,
+ timeout=config.timeout_seconds,
+ )
+ if completed.returncode != 0:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "returncode": completed.returncode,
+ "stdout": (completed.stdout or "")[:2000],
+ "stderr": (completed.stderr or "")[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
diff --git a/.claude/skills/agent-observability/scripts/core/cls_uploader.mjs b/.claude/skills/agent-observability/scripts/core/cls_uploader.mjs
new file mode 100644
index 00000000..5c5dccc8
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/cls_uploader.mjs
@@ -0,0 +1,96 @@
+import { createRequire } from 'node:module';
+
+const MAX_FIELD_LENGTH = 32 * 1024;
+
+function truncate(value) {
+ if (value.length <= MAX_FIELD_LENGTH) {
+ return value;
+ }
+ return `${value.slice(0, MAX_FIELD_LENGTH)}...[truncated]`;
+}
+
+function stringifyValue(value) {
+ if (value === null || value === undefined) {
+ return '';
+ }
+ if (typeof value === 'string') {
+ return truncate(value);
+ }
+ if (typeof value === 'number' || typeof value === 'boolean') {
+ return String(value);
+ }
+ try {
+ return truncate(JSON.stringify(value));
+ } catch {
+ return truncate(String(value));
+ }
+}
+
+function timestampSeconds(record) {
+ const raw = Number(record?.ts);
+ if (!Number.isFinite(raw) || raw <= 0) {
+ return Math.floor(Date.now() / 1000);
+ }
+ return raw > 1_000_000_000_000 ? Math.floor(raw / 1000) : Math.floor(raw);
+}
+
+async function readStdin() {
+ const chunks = [];
+ for await (const chunk of process.stdin) {
+ chunks.push(chunk);
+ }
+ return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+ const sdkPath = process.argv[2];
+ if (!sdkPath) {
+ process.exitCode = 2;
+ process.stderr.write('missing sdk path\n');
+ return;
+ }
+
+ const require = createRequire(import.meta.url);
+ const { AsyncClient, LogItem, Content, LogGroup, PutLogsRequest } = require(sdkPath);
+
+ const raw = await readStdin();
+ const payload = JSON.parse(raw || '{}');
+ const records = Array.isArray(payload.records) ? payload.records : [];
+ if (!payload.endpoint || !payload.topicId || !payload.secretId || !payload.secretKey || records.length === 0) {
+ process.exitCode = 0;
+ return;
+ }
+
+ const client = new AsyncClient({
+ endpoint: payload.endpoint,
+ secretId: payload.secretId,
+ secretKey: payload.secretKey,
+ secretToken: payload.secretToken || '',
+ sourceIp: '127.0.0.1',
+ retry_times: 3,
+ });
+
+ const logGroup = new LogGroup();
+ logGroup.setFilename(payload.serviceName || 'agent-observability');
+
+ for (const record of records) {
+ const item = new LogItem();
+ const merged = {
+ service_name: payload.serviceName || 'agent-observability',
+ ...record,
+ };
+ for (const [key, value] of Object.entries(merged)) {
+ item.pushBack(new Content(key, stringifyValue(value)));
+ }
+ item.setTime(timestampSeconds(record));
+ logGroup.addLogs(item);
+ }
+
+ const request = new PutLogsRequest(payload.topicId, logGroup);
+ await client.PutLogs(request);
+}
+
+main().catch((error) => {
+ process.exitCode = 1;
+ process.stderr.write(`${error?.message || String(error)}\n`);
+});
diff --git a/.claude/skills/agent-observability/scripts/core/collector.py b/.claude/skills/agent-observability/scripts/core/collector.py
new file mode 100644
index 00000000..cfd681b2
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/collector.py
@@ -0,0 +1,1008 @@
+"""通用采集层。
+
+这一层负责最基础的观测数据采集:
+- 维护 Pre/PostToolUse 的配对关系,计算工具耗时
+- 解析 transcript 增量,提取 usage / model / tool 记录
+- 把 skill/rule 命中情况写入 session state
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, scanner, state as st
+
+# 需要从 transcript 中提取的 token 字段
+TOKEN_KEYS = (
+ "input_tokens", "output_tokens", "cache_read_input_tokens",
+ "cache_creation_input_tokens", "total_tokens",
+)
+
+# transcript 记录里可能携带模型名的字段
+MODEL_KEYS = ("model", "requestModelName", "requestModelId")
+MESSAGE_ID_KEYS = ("messageId", "responseId", "requestId")
+
+
+def transcript_path(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取 transcript 路径字段。"""
+ return str(data.get("transcript_path") or "")
+
+
+def read_stdin_json() -> dict:
+ """从 stdin 读取 JSON;失败时返回空字典。"""
+ import sys
+ try:
+ raw = sys.stdin.read()
+ if raw.strip():
+ d = json.loads(raw)
+ if isinstance(d, dict):
+ return d
+ return {}
+ except Exception as e:
+ return {"_parse_error": str(e)}
+
+
+def record_pre(pending_path: Path, data: dict) -> None:
+ """记录一条 PreToolUse,供后续 PostToolUse 计算耗时。"""
+ pending = st.load_pending(pending_path)
+ sid = data.get("session_id", "?")
+ tool = data.get("tool_name", "?")
+ key = f"{sid}::{tool}::{time.time_ns()}"
+ pending[key] = {
+ "start": time.time(),
+ "tool_name": tool,
+ "session_id": sid,
+ }
+ # 只保留最近 20 条 pending 记录
+ if len(pending) > 20:
+ for k in list(pending.keys())[:-20]:
+ pending.pop(k, None)
+ st.save_pending(pending_path, pending)
+
+
+def record_post(pending_path: Path, data: dict) -> int | None:
+ """把 PostToolUse 与之前的 PreToolUse 配对,并返回耗时毫秒数。"""
+ pending = st.load_pending(pending_path)
+ tool = data.get("tool_name")
+ sid = data.get("session_id", "?")
+ candidates = [(k, v) for k, v in pending.items()
+ if v.get("session_id") == sid and v.get("tool_name") == tool]
+ if not candidates:
+ return None
+ candidates.sort(key=lambda kv: kv[1]["start"])
+ key, item = candidates[-1]
+ duration_ms = int((time.time() - item["start"]) * 1000)
+ pending.pop(key, None)
+ st.save_pending(pending_path, pending)
+ return duration_ms
+
+
+def parse_transcript_tail(
+ path: str,
+ max_lines: int = 50,
+ last_offset: int = 0,
+) -> dict[str, Any]:
+ """解析 transcript 的增量 JSONL 内容,提取 usage、model 与 tool 元数据。
+
+ 返回结构:
+ {
+ "tokens": {...} or None, # 最新累计 usage
+ "prev_tokens": {...} or None, # 倒数第二条累计 usage(兼容字段)
+ "model": str or None,
+ "offset": int, # 当前 EOF
+ "tool_records": [
+ {"offset": int, "timestamp_ms": int | None, "tool": str, "call_id": str | None, "message_id": str | None, "kind": str},
+ ...
+ ],
+ "usage_records": [
+ {"offset": int, "tokens": {...}, "model": str | None, "message_id": str | None},
+ ...
+ ],
+ }
+
+ ``usage_records`` 会保留 ``last_offset`` 之后发现的全部 usage 项,
+ 这样调用方可以回放窗口内每一次模型请求,而不只是最后一个快照。
+ """
+ summary: dict[str, Any] = {
+ "tokens": None,
+ "prev_tokens": None,
+ "model": None,
+ "offset": 0,
+ "tool_records": [],
+ "usage_records": [],
+ }
+ if not path or not os.path.isfile(path):
+ return summary
+
+ try:
+ file_size = os.path.getsize(path)
+ summary["offset"] = file_size
+ if file_size <= last_offset:
+ return summary
+
+ with open(path, "rb") as fp:
+ read_start = max(0, int(last_offset or 0))
+ fp.seek(read_start)
+ tail_bytes = fp.read()
+ except Exception:
+ return summary
+
+ last_model_seen: str | None = None
+ usage_history: list[dict[str, Any]] = []
+ pending_tool_records: list[dict[str, Any]] = []
+ cursor = max(0, int(last_offset or 0))
+
+ for raw_line in tail_bytes.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ obj = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+
+ rec_type = str(obj.get("type") or "").strip().lower() if isinstance(obj, dict) else ""
+ message_id = _find_message_id(obj)
+ m = _find_model(obj)
+ if m:
+ last_model_seen = m
+ line_tool_records = _find_tool_records(obj)
+ if message_id and rec_type not in {"function_call", "function_call_result"}:
+ for pending_record in pending_tool_records:
+ pending_record["next_message_id"] = message_id
+ pending_tool_records = []
+ for tool_record in line_tool_records:
+ tool_record["offset"] = cursor
+ tool_record["timestamp_ms"] = _find_timestamp_ms(obj)
+ tool_record["message_id"] = message_id
+ summary["tool_records"].append(tool_record)
+ pending_tool_records.append(tool_record)
+ usage = _find_usage(obj)
+ if not usage:
+ continue
+
+ usage_history.append({
+ "offset": cursor,
+ "tokens": usage,
+ "model": m or last_model_seen,
+ "message_id": message_id,
+ })
+ if m:
+ summary["model"] = m
+
+ if usage_history:
+ summary["usage_records"] = usage_history
+ summary["tokens"] = usage_history[-1]["tokens"]
+ if len(usage_history) >= 2:
+ summary["prev_tokens"] = usage_history[-2]["tokens"]
+
+ if not summary.get("model") and last_model_seen:
+ summary["model"] = last_model_seen
+ return summary
+
+
+def record_tool_usage(
+ state_path: Path,
+ sid: str,
+ data: dict,
+ skills_meta: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+ collect_skills: bool = False,
+) -> tuple[list[str], list[str]]:
+ """把一次 tool 调用命中的 skill/rule 写入 session state。
+
+ Returns:
+ (used_skills, used_rules): 本次工具调用命中的 skill/rule 名称列表。
+ """
+ tool = data.get("tool_name")
+
+ def _update(state: dict[str, Any]) -> tuple[list[str], list[str]]:
+ sess = st.ensure_session(state, sid)
+ agent = active_agent or sess.get("current_agent") or "main"
+
+ used_skills: set[str] = set()
+ used_rules: set[str] = set()
+
+ # 1) 可选的 skill 收集
+ if collect_skills:
+ # 直接 use_skill 调用
+ direct = scanner.extract_skill_from_tool_call(data)
+ if direct:
+ st.bump_skill(sess, direct, via="use_skill", tool=tool,
+ meta=skills_meta.get(direct), agent=agent)
+ used_skills.add(direct)
+
+ # 路径推断
+ path_skills, _ = scanner.extract_paths_from_tool_call(data)
+ for s in path_skills:
+ st.bump_skill(sess, s, via="path-inferred", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 子模块命中
+ for hit in scanner.extract_submodule_hits(data):
+ skill_name = hit["skill"]
+ # unknown 仅代表“命中子模块但无法确定 skill 名称”,不写入实时 skill 字段
+ if not skill_name or skill_name == "unknown":
+ continue
+ st.bump_skill(sess, skill_name, via="submodule", tool=tool,
+ meta=skills_meta.get(skill_name),
+ submodule=hit["submodule"], agent=agent)
+ used_skills.add(skill_name)
+
+ # Bash skill 脚本
+ for s in scanner.extract_bash_skill_scripts(data):
+ st.bump_skill(sess, s, via="bash-script", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 2) 基于路径推断的 rule(始终开启)
+ _, path_rules = scanner.extract_paths_from_tool_call(data)
+ for r in path_rules:
+ st.bump_rule(sess, r, via="path-inferred", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ # 3) 当前激活的 rule(始终开启)
+ for r in scanner.active_rules_for_call(data, rules_meta, active_agent=agent):
+ st.bump_rule(sess, r, via="active-rule", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ st.prune_sessions(state)
+ return sorted(used_skills), sorted(used_rules)
+
+ return st.update_state_locked(state_path, _update)
+
+
+
+def cache_inventory(
+ state_path: Path,
+ sid: str,
+ skills_meta: dict,
+ rules_meta: dict,
+) -> None:
+ """把完整的 skill/rule inventory 缓存在 session state 中(在 SessionStart 调用)。"""
+ def _update(state: dict[str, Any]) -> None:
+ sess = st.ensure_session(state, sid)
+ sess["_skills_meta"] = skills_meta
+ sess["_rules_meta"] = rules_meta
+ sess["_inventory_scanned_at"] = time.time()
+
+ # 为所有已知 skill/rule 预先初始化 count=0 的 usage 记录
+ for name, meta in skills_meta.items():
+ rec = sess["skills"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"],
+ "source": meta.get("source"), "version": meta.get("version"),
+ })
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+
+ for name, meta in rules_meta.items():
+ rec = sess["rules"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"], "source": meta.get("source"),
+ })
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+
+ st.prune_sessions(state)
+
+ st.update_state_locked(state_path, _update)
+
+
+def load_cached_inventory(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """从 state 中读取缓存的 skill/rule inventory,避免在热路径里执行 rglob。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return (
+ sess.get("_skills_meta") or {},
+ sess.get("_rules_meta") or {},
+ )
+
+
+def get_session_usage(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """返回某个 session 的 skill/rule usage 字典。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return sess.get("skills", {}) or {}, sess.get("rules", {}) or {}
+
+def related_transcript_paths(sid: str, transcript_path: str) -> list[str]:
+ """收集当前 session 的主 transcript 以及所有 subagent transcript。"""
+ paths: list[Path] = []
+ current = Path(transcript_path).expanduser() if transcript_path else None
+ if current and current.is_file():
+ paths.append(current)
+
+ bundle_dir: Path | None = None
+ if current:
+ if current.name == f"{sid}.jsonl":
+ candidate = current.with_suffix("")
+ if candidate.is_dir():
+ bundle_dir = candidate
+ else:
+ for parent in [current.parent, *current.parents]:
+ if parent.name == sid and parent.is_dir():
+ bundle_dir = parent
+ break
+
+ if bundle_dir is None and current:
+ candidate = current.parent / sid
+ if candidate.is_dir():
+ bundle_dir = candidate
+
+ if bundle_dir is not None:
+ main_transcript = bundle_dir.with_suffix(".jsonl")
+ if main_transcript.is_file():
+ paths.append(main_transcript)
+ subagents_dir = bundle_dir / "subagents"
+ if subagents_dir.is_dir():
+ paths.extend(sorted(path for path in subagents_dir.glob("*.jsonl") if path.is_file()))
+
+ out: list[str] = []
+ seen: set[str] = set()
+ for path in paths:
+ resolved = str(path.resolve())
+ if resolved in seen:
+ continue
+ seen.add(resolved)
+ out.append(resolved)
+ return out
+
+
+def _transcript_size_signature(paths: list[str]) -> tuple[tuple[str, int], ...]:
+ """基于路径和文件大小生成 transcript 稳定性签名。"""
+ signature: list[tuple[str, int]] = []
+ for path in paths:
+ try:
+ size = Path(path).stat().st_size
+ except Exception:
+ size = -1
+ signature.append((path, int(size)))
+ return tuple(signature)
+
+
+def settled_related_transcript_paths(
+ sid: str,
+ transcript_path: str,
+ *,
+ max_wait_s: float = 2.0,
+ interval_s: float = 0.4,
+ stable_rounds: int = 2,
+) -> list[str]:
+ """在 replay 前短暂等待 transcript 文件停止增长。"""
+ deadline = time.monotonic() + max(0.0, max_wait_s)
+ previous: tuple[tuple[str, int], ...] | None = None
+ stable_count = 0
+ paths = related_transcript_paths(sid, transcript_path)
+
+ while True:
+ paths = related_transcript_paths(sid, transcript_path)
+ current = _transcript_size_signature(paths)
+ if current == previous:
+ stable_count += 1
+ else:
+ previous = current
+ stable_count = 0
+ if stable_count >= stable_rounds or time.monotonic() >= deadline:
+ return paths
+ sleep_for = min(interval_s, max(0.0, deadline - time.monotonic()))
+ if sleep_for <= 0:
+ return paths
+ time.sleep(sleep_for)
+
+
+def session_id_for_transcript_path(transcript_path: str) -> str | None:
+ """从 transcript 文件内容中反查 session id。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(8):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+ session_id = record.get("sessionId")
+ if isinstance(session_id, str) and session_id.strip():
+ return session_id.strip()
+ except Exception:
+ return None
+ return None
+
+
+def resolve_transcript_path_alias(sid: str, transcript_path: str) -> str:
+ """把别名 transcript 路径解析成当前 session 下的真实文件路径。"""
+ if not transcript_path:
+ return ""
+ current = Path(transcript_path).expanduser()
+ if current.is_file():
+ return str(current.resolve())
+
+ alias_session_id = current.stem if current.suffix == ".jsonl" else ""
+ if not alias_session_id or alias_session_id == sid:
+ return str(current)
+
+ for candidate in related_transcript_paths(sid, transcript_path):
+ if session_id_for_transcript_path(candidate) == alias_session_id:
+ return candidate
+ return str(current)
+
+def compute_usage_delta(current: dict[str, int], prev: dict[str, int] | None) -> dict[str, int]:
+ """把一条 usage 记录归一化成当前要发出的 event payload。"""
+ _ = prev
+ out = dict(current)
+ out["total"] = int(out.get("input", 0) or 0) + int(out.get("output", 0) or 0)
+ return out
+
+
+def normalize_tokens(tokens: dict[str, Any] | None) -> dict[str, int] | None:
+ """兼容多种 token 字段命名,并统一折叠成一套 schema。"""
+ if not isinstance(tokens, dict):
+ return None
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ input_t = _int(tokens.get("input") if "input" in tokens else tokens.get("input_tokens"))
+ output_t = _int(tokens.get("output") if "output" in tokens else tokens.get("output_tokens"))
+ cache_read = _int(tokens.get("cache_read") if "cache_read" in tokens else tokens.get("cache_read_input_tokens"))
+ cache_creation = _int(tokens.get("cache_creation") if "cache_creation" in tokens else tokens.get("cache_creation_input_tokens"))
+ total = input_t + output_t
+ if input_t <= 0 and output_t <= 0 and total <= 0:
+ return None
+ out = {"input": input_t, "output": output_t, "cache_read": cache_read, "total": total}
+ if cache_creation > 0:
+ out["cache_creation"] = cache_creation
+ return out
+
+
+def collect_transcript_entries(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ *,
+ max_lines: int,
+) -> dict[str, Any]:
+ """读取 transcript 增量,并返回带 source offset 的解析结果。"""
+ state_data = st.load_state(state_path)
+ last_offset = st.get_transcript_offset(state_data, sid, transcript_path)
+ tail = parse_transcript_tail(transcript_path, max_lines=max_lines, last_offset=last_offset)
+ new_offset = int(tail.get("offset", 0) or 0)
+
+ entries: list[dict[str, Any]] = []
+ tool_records: list[dict[str, Any]] = []
+ last_cumulative = st.get_last_cumulative_usage(state_data, sid, transcript_path) or None
+ usage_records = tail.get("usage_records") if isinstance(tail, dict) else None
+ if not isinstance(usage_records, list):
+ usage_records = []
+ raw_tool_records = tail.get("tool_records") if isinstance(tail, dict) else None
+ if not isinstance(raw_tool_records, list):
+ raw_tool_records = []
+
+ for raw_entry in usage_records:
+ if not isinstance(raw_entry, dict):
+ continue
+ current = normalize_tokens(raw_entry.get("tokens"))
+ if not current:
+ continue
+ delta = compute_usage_delta(current, last_cumulative)
+ entries.append({
+ "offset": int(raw_entry.get("offset", 0) or 0),
+ "tokens": delta,
+ "model": str(raw_entry.get("model") or tail.get("model") or "") or None,
+ "message_id": str(raw_entry.get("message_id") or "").strip() or None,
+ })
+ last_cumulative = current
+
+ for raw_tool_record in raw_tool_records:
+ if not isinstance(raw_tool_record, dict):
+ continue
+ tool_name = str(raw_tool_record.get("tool") or "").strip()
+ if not tool_name:
+ continue
+ tool_records.append({
+ "offset": int(raw_tool_record.get("offset", 0) or 0),
+ "timestamp_ms": int(raw_tool_record.get("timestamp_ms", 0) or 0) or None,
+ "tool": tool_name,
+ "call_id": str(raw_tool_record.get("call_id") or "").strip() or None,
+ "kind": str(raw_tool_record.get("kind") or "").strip() or None,
+ "message_id": str(raw_tool_record.get("message_id") or "").strip() or None,
+ "next_message_id": str(raw_tool_record.get("next_message_id") or "").strip() or None,
+ "arguments": raw_tool_record.get("arguments"),
+ "arguments_display_text": raw_tool_record.get("arguments_display_text"),
+ "result_content": raw_tool_record.get("result_content"),
+ "raw_response": raw_tool_record.get("raw_response"),
+ "output_text": raw_tool_record.get("output_text"),
+ })
+
+ return {
+ "entries": entries,
+ "tool_records": tool_records,
+ "new_offset": new_offset,
+ "last_cumulative": last_cumulative,
+ }
+
+
+def find_current_tool_message_id(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ max_lines: int = 80,
+) -> str | None:
+ """找到当前 tool 事件应该归属的 message id。"""
+ if not transcript_path or not tool_name:
+ return None
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ max_lines=max_lines,
+ )
+ tool_records = scan.get("tool_records") or []
+ latest_message_id: str | None = None
+ latest_offset = -1
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ if offset >= latest_offset:
+ latest_offset = offset
+ latest_message_id = message_id
+ return latest_message_id
+
+
+def tool_details_from_record(rec: dict[str, Any]) -> dict[str, Any]:
+ """把原始 tool 记录投影成日志里使用的紧凑 detail 结构。"""
+ details: dict[str, Any] = {}
+ call_id = str(rec.get("call_id") or "").strip() or None
+ if call_id:
+ details["call_id"] = call_id
+ arguments = rec.get("arguments")
+ if arguments is not None:
+ details["arguments"] = arguments
+ arguments_display_text = rec.get("arguments_display_text")
+ if arguments_display_text is not None:
+ details["arguments_display_text"] = arguments_display_text
+ result_content = rec.get("result_content")
+ if result_content is not None:
+ details["result_content"] = result_content
+ raw_response = rec.get("raw_response")
+ if isinstance(raw_response, dict) and raw_response:
+ details["raw_response"] = raw_response
+ output_text = rec.get("output_text")
+ if output_text is not None:
+ details["output_text"] = output_text
+ next_message_id = str(rec.get("next_message_id") or "").strip() or None
+ original_message_id = str(rec.get("message_id") or "").strip() or None
+ if next_message_id and original_message_id:
+ details["original_message_id"] = original_message_id
+ if next_message_id:
+ details["next_message_id"] = next_message_id
+ if original_message_id and next_message_id and original_message_id != next_message_id:
+ details["message_id_reassigned"] = True
+ return details
+
+
+def tool_record_merge_key(rec: dict[str, Any]) -> str:
+ """为一条 tool record 生成去重合并时使用的稳定 key。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"call_id:{call_id}"
+ offset = int(rec.get("offset", 0) or 0)
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ return f"fallback:{tool}:{message_id}:{timestamp_ms}:{offset}"
+
+
+def merge_tool_records(tool_records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """对指向同一次调用的 tool 记录做去重合并。"""
+ merged: dict[str, dict[str, Any]] = {}
+ order: list[str] = []
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ key = tool_record_merge_key(rec)
+ if key not in merged:
+ merged[key] = {
+ "offset": int(rec.get("offset", 0) or 0),
+ "timestamp_ms": int(rec.get("timestamp_ms", 0) or 0) or None,
+ "tool": str(rec.get("tool") or "").strip(),
+ "call_id": str(rec.get("call_id") or "").strip() or None,
+ "kind": str(rec.get("kind") or "").strip() or None,
+ "message_id": str(rec.get("message_id") or "").strip() or None,
+ "next_message_id": str(rec.get("next_message_id") or "").strip() or None,
+ "arguments": rec.get("arguments"),
+ "arguments_display_text": rec.get("arguments_display_text"),
+ "result_content": rec.get("result_content"),
+ "raw_response": rec.get("raw_response"),
+ "output_text": rec.get("output_text"),
+ }
+ order.append(key)
+ continue
+
+ current = merged[key]
+ current["offset"] = max(int(current.get("offset", 0) or 0), int(rec.get("offset", 0) or 0))
+ current_ts = int(current.get("timestamp_ms", 0) or 0)
+ rec_ts = int(rec.get("timestamp_ms", 0) or 0)
+ if current_ts <= 0 and rec_ts > 0:
+ current["timestamp_ms"] = rec_ts
+ for field in ("tool", "call_id", "kind", "message_id", "next_message_id", "arguments", "arguments_display_text", "result_content", "raw_response", "output_text"):
+ if current.get(field) is None and rec.get(field) is not None:
+ current[field] = rec.get(field)
+ if rec.get("arguments") is not None:
+ current["arguments"] = rec.get("arguments")
+ if rec.get("arguments_display_text") is not None:
+ current["arguments_display_text"] = rec.get("arguments_display_text")
+ if rec.get("result_content") is not None:
+ current["result_content"] = rec.get("result_content")
+ if rec.get("raw_response") is not None:
+ current["raw_response"] = rec.get("raw_response")
+ if rec.get("output_text") is not None:
+ current["output_text"] = rec.get("output_text")
+
+ return [merged[key] for key in order]
+
+
+def tool_context_claim_key(rec: dict[str, Any]) -> str:
+ """为 tool context 生成 claim 去重键,避免重复消费。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"tool_call|{call_id}"
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ offset = int(rec.get("offset", 0) or 0)
+ return f"tool_call|{tool}|{message_id}|{timestamp_ms}|{offset}"
+
+
+def find_current_tool_context(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ call_id: str | None = None,
+ event_ts: float | None = None,
+ max_lines: int = 80,
+ claim: bool = False,
+) -> dict[str, Any] | None:
+ """为当前 tool 调用解析最合适的 transcript 上下文块。"""
+ if not tool_name:
+ return None
+ event_ts_ms = int(float(event_ts) * 1000) if event_ts else None
+ normalized_call_id = str(call_id or "").strip() or None
+
+ resolved_path = resolve_transcript_path_alias(sid, transcript_path)
+ candidate_paths: list[str] = []
+ if resolved_path:
+ candidate_paths.append(resolved_path)
+ for path in related_transcript_paths(sid, transcript_path):
+ if path not in candidate_paths:
+ candidate_paths.append(path)
+
+ candidates: list[tuple[tuple[int, int, int], dict[str, Any]]] = []
+ for path in candidate_paths:
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ tool_records = merge_tool_records(scan.get("tool_records") or [])
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ rec_call_id = str(rec.get("call_id") or "").strip() or None
+ if normalized_call_id and rec_call_id != normalized_call_id:
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ if normalized_call_id:
+ score = (0, 0, -offset)
+ elif event_ts_ms and timestamp_ms > 0:
+ delta = timestamp_ms - event_ts_ms
+ score = (abs(delta), 0 if delta >= 0 else 1, -offset)
+ else:
+ score = (10**12, 1, -offset)
+ candidates.append((
+ score,
+ {
+ "message_id": message_id,
+ "transcript_path": path,
+ "agent": agent_identity.agent_for_transcript_path(path, "main"),
+ "pt_id": agent_identity.pt_id_from_transcript_path(path),
+ "tool_details": tool_details_from_record(rec),
+ "_claim_key": tool_context_claim_key(rec),
+ },
+ ))
+
+ candidates.sort(key=lambda item: item[0])
+ saw_duplicate = False
+ for _, candidate in candidates:
+ if not claim:
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ if st.claim_transcript_event(
+ state_path,
+ sid,
+ str(candidate.get("_claim_key") or ""),
+ str(candidate.get("transcript_path") or "") or None,
+ ):
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ saw_duplicate = True
+
+ if saw_duplicate:
+ return {"duplicate": True}
+ return None
+
+
+def extract_tool_call_id(data: dict[str, Any]) -> str | None:
+ """从事件 payload 或 tool_input 中提取 tool call id。"""
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId"):
+ value = data.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+
+ tool_input = data.get("tool_input")
+ if isinstance(tool_input, dict):
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId", "id"):
+ value = tool_input.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return None
+
+
+def find_fallback_usage_event(
+ tool_event: dict[str, Any],
+ usage_events: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+ """当找不到直接匹配的 tool usage 时,为 AgentLens 选一条兜底 usage。"""
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ agent = str(tool_event.get("agent") or "main").strip() or "main"
+
+ strong_matches: list[dict[str, Any]] = []
+ weak_matches: list[dict[str, Any]] = []
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if (str(usage_event.get("agent") or "main").strip() or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "").strip() != transcript_path:
+ continue
+ if not str(usage_event.get("message_id") or "").strip():
+ continue
+
+ weak_matches.append(usage_event)
+ event_tool = str(usage_event.get("tool") or "").strip()
+ if tool_name and event_tool in {tool_name, "model_request"}:
+ strong_matches.append(usage_event)
+
+ if strong_matches:
+ return strong_matches[-1]
+ if weak_matches:
+ return weak_matches[-1]
+ return None
+
+
+def build_transcript_event_key(*, kind: str, tool: str, entry: dict[str, Any]) -> str:
+ """为 transcript 重放出的事件生成幂等键。"""
+ _ = (kind, tool)
+ return "|".join(["model_request", str(entry.get("offset", 0) or 0)])
+
+def _find_usage(obj: Any, _depth: int = 0) -> dict | None:
+ """递归查找 JSON 对象里的 token usage。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ if "usage" in obj and isinstance(obj["usage"], dict):
+ u = obj["usage"]
+ picked = {k: u[k] for k in TOKEN_KEYS if k in u}
+ if picked:
+ return picked
+ for v in obj.values():
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_model(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找 JSON 对象里的非空模型名。
+
+ 优先使用 `providerData.model` 或顶层 `model`,
+ 其次回退到 `requestModelName` / `requestModelId`。
+ """
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ for k in MODEL_KEYS:
+ v = obj.get(k)
+ if isinstance(v, str) and v.strip():
+ return v.strip()
+ for v in obj.values():
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_message_id(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找稳定的 message/request 分组标识。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in MESSAGE_ID_KEYS:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for v in obj.values():
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_timestamp_ms(obj: Any, _depth: int = 0) -> int | None:
+ """递归查找 transcript 中的毫秒级时间戳。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ value = obj.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ value = provider.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ for v in obj.values():
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_tool_records(obj: Any) -> list[dict[str, Any]]:
+ """从 transcript 记录里提取 tool 调用与 tool 结果片段。"""
+ out: list[dict[str, Any]] = []
+ if not isinstance(obj, dict):
+ return out
+
+ rec_type = str(obj.get("type") or "").strip().lower()
+ provider = obj.get("providerData") if isinstance(obj.get("providerData"), dict) else {}
+ if rec_type in {"function_call", "function_call_result"}:
+ tool_name = str(obj.get("name") or "").strip()
+ if tool_name:
+ record = {
+ "tool": tool_name,
+ "call_id": str(obj.get("callId") or "").strip() or None,
+ "kind": rec_type,
+ }
+ if rec_type == "function_call":
+ arguments = obj.get("arguments")
+ if isinstance(arguments, str) and arguments.strip():
+ record["arguments"] = arguments
+ arguments_display_text = provider.get("argumentsDisplayText")
+ if isinstance(arguments_display_text, str) and arguments_display_text.strip():
+ record["arguments_display_text"] = arguments_display_text.strip()
+ if rec_type == "function_call_result":
+ tool_result = provider.get("toolResult")
+ if isinstance(tool_result, dict):
+ content = tool_result.get("content")
+ if content is not None:
+ record["result_content"] = content
+ raw_response = tool_result.get("rawResponse")
+ if isinstance(raw_response, dict):
+ record["raw_response"] = raw_response
+ output = obj.get("output")
+ if isinstance(output, dict):
+ output_text = output.get("text")
+ if output_text is not None:
+ record["output_text"] = output_text
+ out.append(record)
+
+ content = obj.get("content")
+ if isinstance(content, list):
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ if str(item.get("type") or "").strip().lower() != "tool_use":
+ continue
+ tool_name = str(item.get("name") or "").strip()
+ if not tool_name:
+ continue
+ out.append({
+ "tool": tool_name,
+ "call_id": str(item.get("callId") or "").strip() or None,
+ "kind": "tool_use",
+ })
+
+ return out
diff --git a/.claude/skills/agent-observability/scripts/core/devflow.py b/.claude/skills/agent-observability/scripts/core/devflow.py
new file mode 100644
index 00000000..ab7ef794
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/devflow.py
@@ -0,0 +1,234 @@
+"""Devflow 感知层(可选增强,不属于通用采集核心)。
+
+这一层只在项目实际跑着 `.codebuddy/runtime` 描述的 multi-agents-devflow 工作流时才生效:
+- 判断当前 session 是否属于某个 devflow team(`multi-agents-devflow-{task_slug}`)
+- 读取该 team 对应的 `workflow-state.json`,投影成精简 stage 快照
+- 和上一次观测到的快照 diff,只把真正变化的 stage 产出为事件
+
+任何解析失败(team 目录不存在 / workflow-state.json 缺失或损坏 / 字段缺失)都必须
+优雅降级为 None / 空列表,绝不能让不跑 devflow 的普通项目因为这一层报错。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, state as st
+
+
+def task_slug_from_team_dir(team_dir: Path) -> str | None:
+ """从 devflow team 目录名里剥离出 task_slug(固定前缀 `multi-agents-devflow-`)。"""
+ name = team_dir.name
+ prefix = agent_identity.TEAM_PREFIX
+ if not name.startswith(prefix):
+ return None
+ slug = name[len(prefix):].strip()
+ return slug or None
+
+
+def resolve_devflow_context(cwd: str, sid: str, cached_team_dir: str | None = None) -> dict[str, Any] | None:
+ """判断当前 session 是否处于某次 devflow 运行中;不是则返回 None。
+
+ 优先复用 `agent_identity.resolve_team_dir` 做 team 发现(Classic 全部场景,以及
+ Portable 在 `topology: team` 宿主——目前是 CodeBuddy——下也走同一套
+ `multi-agents-devflow-{task_slug}` 命名,可以直接复用,不用区分 edition)。
+
+ `topology: spawn` 的宿主(Codex/Claude/Cursor 的 Portable 适配器)不创建 team
+ 目录,找不到时退化成 `_scan_artifacts_for_active_run` 直接扫 `artifacts/` 目录。
+ 这个兜底本身就是尽力而为的启发式,不保证唯一/精确,见该函数的说明。
+
+ `artifacts_dir` 按 `devflow.defaults.yaml` 的默认值 `{project_root}/artifacts/{task_slug}`
+ 推算——项目若覆写了 `artifacts.root_dir`,这里暂不感知,读取 workflow-state.json
+ 找不到文件会安全返回 None,不会误报。
+ """
+ team_dir = agent_identity.resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is not None:
+ task_slug = task_slug_from_team_dir(team_dir)
+ if task_slug:
+ artifacts_dir = Path(cwd).expanduser() / "artifacts" / task_slug
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ return {
+ "task_slug": task_slug,
+ "team_dir": str(team_dir),
+ "artifacts_dir": str(artifacts_dir),
+ "workflow_state_path": str(workflow_state_path),
+ }
+ return _scan_artifacts_for_active_run(cwd)
+
+
+def _scan_artifacts_for_active_run(cwd: str) -> dict[str, Any] | None:
+ """没有 team 目录时的兜底发现:直接扫 `{cwd}/artifacts/*/workflow-state.json`。
+
+ 用于 `topology: spawn` 的宿主(没有 `.codebuddy/teams/` 这类目录可以反查),以及
+ Classic 没有真正暴露 `team_create` 时的降级场景。这是启发式,不是精确匹配:
+ 多个 task_slug 存在时,优先选"还没跑完"的那个;都跑完或都没跑完时选
+ `workflow-state.json` 文件 mtime 最新的一个。"跑完"的判定要兼容两套 schema——
+ Classic(v1.3)没有顶层 `status` 字段,看 `last_event == "workflow_completed"`;
+ Portable(v2.0)看顶层 `status in {"completed", "failed"}`。项目里如果同时有多个
+ 真正并发、都还没跑完的 devflow 运行,这个兜底可能选错——已知限制,不在这次范围内解决。
+ """
+ artifacts_root = Path(cwd).expanduser() / "artifacts"
+ if not artifacts_root.is_dir():
+ return None
+ candidates: list[tuple[tuple[int, float], str, Path]] = []
+ try:
+ children = list(artifacts_root.iterdir())
+ except Exception:
+ return None
+ for child in children:
+ if not child.is_dir():
+ continue
+ state_path = child / "workflow-state.json"
+ state = read_workflow_state(str(state_path))
+ if not isinstance(state, dict) or not isinstance(state.get("stages"), dict):
+ continue
+ try:
+ mtime = state_path.stat().st_mtime
+ except Exception:
+ mtime = 0.0
+ finished = (
+ str(state.get("last_event") or "") == "workflow_completed"
+ or str(state.get("status") or "") in {"completed", "failed"}
+ )
+ not_finished = 0 if finished else 1
+ candidates.append(((not_finished, mtime), child.name, state_path))
+ if not candidates:
+ return None
+ candidates.sort(key=lambda item: item[0], reverse=True)
+ _, task_slug, state_path = candidates[0]
+ return {
+ "task_slug": task_slug,
+ "team_dir": None,
+ "artifacts_dir": str(state_path.parent),
+ "workflow_state_path": str(state_path),
+ }
+
+
+def read_workflow_state(path: str) -> dict[str, Any] | None:
+ """安全读取 workflow-state.json;文件不存在或解析失败都返回 None。"""
+ try:
+ p = Path(path)
+ if not p.is_file():
+ return None
+ data = json.loads(p.read_text("utf-8"))
+ return data if isinstance(data, dict) else None
+ except Exception:
+ return None
+
+
+def stage_snapshot(workflow_state: dict[str, Any] | None) -> dict[str, Any]:
+ """把 workflow-state.json 投影成精简快照,供比对和事件输出使用。
+
+ 兼容两套 schema:Classic(v1.3,字段名 `executor`,有 `review_result`)和
+ Portable(v2.0,字段名 `executor_role`,没有 `review_result`,但顶层多了
+ `execution_mode`/`host_adapter`/`run_id`/`team_name` 这些 Classic 没有的上下文)。
+ 按 `version` 字段区分,取不到就都尝试取一遍,不强制要求调用方先判断是哪个 edition。
+ """
+ if not isinstance(workflow_state, dict):
+ return {}
+ stages_raw = workflow_state.get("stages")
+ stages: dict[str, Any] = {}
+ if isinstance(stages_raw, dict):
+ for name, info in stages_raw.items():
+ if not isinstance(info, dict):
+ continue
+ stages[name] = {
+ "status": info.get("status"),
+ "executor": info.get("executor") or info.get("executor_role"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ }
+ return {
+ "current_stage": workflow_state.get("current_stage"),
+ "size_class": workflow_state.get("size_class"),
+ "run_mode": workflow_state.get("run_mode"),
+ "schema_version": workflow_state.get("version"),
+ "execution_mode": workflow_state.get("execution_mode"),
+ "host_adapter": workflow_state.get("host_adapter"),
+ "run_id": workflow_state.get("run_id"),
+ "stages": stages,
+ }
+
+
+def diff_stage_changes(prev: dict[str, Any] | None, curr: dict[str, Any]) -> list[dict[str, Any]]:
+ """比较两次 stage 快照,只返回 status/retry_count/review_result 真正变化的阶段。
+
+ 首次观测(`prev` 为 None,即这个 session 第一次检测到 devflow)不产出任何变更——
+ 避免刚接入 observability 时,把一个已经跑了大半的 devflow 运行的全部历史阶段
+ 当成"新事件"一次性炸出来。之后每次变化都会被正常捕获。
+ """
+ if not isinstance(curr, dict) or prev is None:
+ return []
+ curr_stages = curr.get("stages") or {}
+ prev_stages = prev.get("stages") if isinstance(prev, dict) else {}
+ if not isinstance(prev_stages, dict):
+ prev_stages = {}
+ changes: list[dict[str, Any]] = []
+ for name, info in curr_stages.items():
+ if not isinstance(info, dict):
+ continue
+ before = prev_stages.get(name)
+ before = before if isinstance(before, dict) else {}
+ fields = ("status", "retry_count", "review_result")
+ if any(before.get(f) != info.get(f) for f in fields):
+ changes.append({
+ "stage": name,
+ "status": info.get("status"),
+ "executor": info.get("executor"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ })
+ return changes
+
+
+def resolve_and_diff(state_path: Path, sid: str, cwd: str) -> dict[str, Any] | None:
+ """解析当前 session 归属的 devflow 上下文,返回上下文 + 本次观测到的 stage 变更。
+
+ **不缓存"当前归属哪个 task_slug"这个结论本身**——同一个 sid 在其生命周期内可能
+ 先后归属不同的 devflow 运行。这不是理论场景:当运行时没有暴露真正的
+ `team_create`/`send_message`(因此没有独立的 team 成员 sid),devflow 会退化成
+ 在同一个长生命周期 session 里,先后跑好几次 `/start-devflow`;每次都必须重新判定
+ "现在最合适的 task_slug 是哪个",而不能沿用第一次探测到的那个——沿用旧结论会把
+ 第二次运行的所有事件都错误地归到第一次的 task_slug 下。
+
+ 重新判定的代价很低:`resolve_devflow_context` 对团队目录的探测会用上一次找到的
+ `team_dir` 做快速校验(只在真正失效时才重新扫描 `.codebuddy/teams/`);
+ `artifacts/` 兜底扫描也只是一次浅层 `iterdir()`,不是全量遍历。
+
+ 真正跨调用持久化的只有**按 task_slug 分别保存的 stage 快照历史**——切换到另一个
+ task_slug 不会污染对方的 diff 基线,也不会因为切回旧 task_slug 而把它已经观测过的
+ 历史重新当成"首次观测"。
+
+ 返回 None 表示这次调用没有探测到任何 devflow 上下文;否则返回
+ `{task_slug, artifacts_dir, workflow_state_path, current_stage, size_class, changes}`。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any] | None:
+ dv = st.get_devflow_state(state, sid)
+ cached_team_dir = (dv.get("context") or {}).get("team_dir") if isinstance(dv.get("context"), dict) else None
+ context = resolve_devflow_context(cwd, sid, cached_team_dir)
+ if not isinstance(context, dict):
+ st.set_devflow_state(state, sid, {"context": None})
+ return None
+
+ task_slug = str(context.get("task_slug") or "")
+ workflow_state = read_workflow_state(context.get("workflow_state_path", ""))
+ curr = stage_snapshot(workflow_state)
+ snapshots = dv.get("snapshots")
+ if not isinstance(snapshots, dict):
+ snapshots = {}
+ prev = snapshots.get(task_slug)
+ changes = diff_stage_changes(prev if isinstance(prev, dict) else None, curr)
+ snapshots[task_slug] = curr
+ st.set_devflow_state(state, sid, {"context": context, "snapshots": snapshots})
+
+ result = dict(context)
+ result["current_stage"] = curr.get("current_stage")
+ result["size_class"] = curr.get("size_class")
+ result["schema_version"] = curr.get("schema_version")
+ result["execution_mode"] = curr.get("execution_mode")
+ result["changes"] = changes
+ return result
+
+ return st.update_state_locked(state_path, _update)
diff --git a/.claude/skills/agent-observability/scripts/core/emitter.py b/.claude/skills/agent-observability/scripts/core/emitter.py
new file mode 100644
index 00000000..a41dfc05
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/emitter.py
@@ -0,0 +1,578 @@
+"""ndjson 发射层。
+
+只输出当前真正需要的核心字段:
+- common: data_source
+- tool: event, sid, ts, agent, tool, ms, skill, rule, transcript_path
+- usage: event, sid, ts, agent, tool, tokens, model, cost_usd, transcript_path
+- start: event, sid, ts, agent
+- stop: event, sid, ts, agent, tokens, model, cost_usd, cost_session_usd, transcript_path
+- error: event, sid, ts, phase, error
+
+历史 x_* 扩展字段、stop skill/rule 汇总、schema 版本号等都不再生成。
+
+`cost_usd` 的价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认
+`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`,可用
+`AOBS_PRICING_OVERRIDES_PATH` 改路径)的字段级合并结果,详见 `load_prices()`。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from . import cls_sink
+from . import state as st
+
+DEFAULT_PRICES_PATH = Path(__file__).resolve().parents[2] / "config" / "pricing.json"
+DEFAULT_DATA_SOURCE = "codebuddy-cli"
+
+
+def _default_overrides_path() -> Path | None:
+ """用户定价覆盖文件的默认位置:`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`。
+
+ 刻意放在 `skills/` 树**外**:`scripts/build-classic-hosts.py` 会整棵同步
+ `.codebuddy/skills`,放树内会 (a) 每次改动都产生 `--check` drift,(b) 把用户的
+ 自定义价格复制进 `.claude`/`.cursor` 宿主包;放树外则既不参与同步,也不会被
+ `config/pricing.json` 的后续更新冲掉。
+ """
+ try:
+ project_root = Path(__file__).resolve().parents[5]
+ except IndexError:
+ return None
+ return project_root / ".codebuddy" / "agent-observability" / "pricing.overrides.json"
+
+
+# None 表示"拿不到项目根",此时等同于"没有覆盖文件"(纯内置价格表)。
+DEFAULT_OVERRIDES_PATH: Path | None = _default_overrides_path()
+
+
+def get_log_path(base_dir: Path) -> Path:
+ """返回 metrics 日志路径,并确保目录已存在。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / "metrics.ndjson"
+
+
+def _first_record_ts(log_path: Path, sid: str) -> float | None:
+ """从 metrics.ndjson 中找到某个 session 的最早 ts。
+
+ state 只保留最近几个 session,长流程或历史 session 可能被 prune 后重建,
+ 因此 `started_at` 不能作为唯一权威。日志里的首条 ts 更接近
+ session/workflow 的真实起点。
+ """
+ if not sid or not log_path.exists():
+ return None
+ first_ts: float | None = None
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid:
+ continue
+ try:
+ ts = float(rec.get("ts"))
+ except Exception:
+ continue
+ if first_ts is None or ts < first_ts:
+ first_ts = ts
+ except Exception:
+ return None
+ return first_ts
+
+
+def _inject_session_duration(record: dict[str, Any], log_path: Path) -> None:
+ """从 state 文件读取 session started_at,计算 session_duration_sec 注入 record。
+ 同时扫描 metrics.ndjson 累计 session 级别 token 总量。"""
+ sid = record.get("sid")
+ if not sid or "session_duration_sec" in record:
+ return
+ try:
+ now = float(record.get("ts") or time.time())
+ started_candidates: list[float] = []
+ state_path = log_path.parent / ".state.json"
+ state = st.load_state(state_path)
+ sess = state.get(sid)
+ if isinstance(sess, dict):
+ try:
+ state_started_at = float(sess.get("started_at") or 0)
+ except Exception:
+ state_started_at = 0.0
+ if state_started_at > 0:
+ started_candidates.append(state_started_at)
+ log_started_at = _first_record_ts(log_path, str(sid))
+ if log_started_at is not None and log_started_at > 0:
+ started_candidates.append(log_started_at)
+ if not started_candidates:
+ started_candidates.append(now)
+ started_at = min(started_candidates)
+ record["session_duration_sec"] = round(max(0.0, now - started_at), 3)
+ except Exception:
+ return
+
+ # 累计 session 级别 token(扫描 metrics.ndjson 尾部)
+ try:
+ total_input = 0
+ total_output = 0
+ total_cache = 0
+ if log_path.exists():
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") != "usage":
+ continue
+ tokens = rec.get("tokens")
+ if not isinstance(tokens, dict):
+ continue
+ total_input += int(tokens.get("input") or 0)
+ total_output += int(tokens.get("output") or 0)
+ total_cache += int(tokens.get("cache_read") or 0)
+ record["session_total_tokens"] = total_input + total_output
+ record["session_input_tokens"] = total_input
+ record["session_output_tokens"] = total_output
+ record["session_cache_tokens"] = total_cache
+ except Exception:
+ return
+
+
+def emit(log_path: Path, record: dict[str, Any]) -> None:
+ """向 ndjson 日志追加一条记录。"""
+ record.setdefault("data_source", DEFAULT_DATA_SOURCE)
+ record.setdefault("ts", time.time())
+ _inject_session_duration(record, log_path)
+ with log_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False) + "\n")
+ try:
+ cls_sink.mirror_record(record)
+ except Exception:
+ return
+
+
+def build_tool_event(
+ sid: str,
+ tool: str | None,
+ duration_ms: int | None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+ pt_id: str | None = None,
+) -> dict[str, Any]:
+ """构造 tool 事件记录,只包含调用信息与耗时。
+
+ `task_slug` / `stage` / `pt_id` 只有在检测到 devflow 运行时才会出现(见
+ `core/devflow.py`),非 devflow 项目不受影响。
+ """
+ record = {
+ "event": "tool",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "ms": duration_ms,
+ }
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if turn_id:
+ record["turn_id"] = turn_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ if pt_id:
+ record["pt_id"] = pt_id
+ return record
+
+
+def build_usage_event(
+ sid: str,
+ tool: str | None,
+ tokens: dict[str, Any],
+ active_agent: str | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造 LLM usage 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "usage",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "tokens": tokens,
+ }
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_start_event(
+ sid: str,
+ agent: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 start 事件记录。
+
+ 初始化阶段没有明确角色时,统一记为 ``main``。
+ """
+ return {
+ "event": "start",
+ "sid": sid,
+ "agent": agent or "main",
+ }
+
+
+def build_prompt_submit_event(
+ sid: str,
+ turn_id: str,
+ agent: str | None = None,
+ prompt_len: int | None = None,
+) -> dict[str, Any]:
+ """构造 `user_prompt_submit` 事件,作为 turn 边界标记。
+
+ 这条记录会落到 metrics.ndjson,方便下游把 turn 和 AgentLens trace 对上。
+ """
+ record: dict[str, Any] = {
+ "event": "user_prompt_submit",
+ "sid": sid,
+ "agent": agent or "main",
+ "turn_id": turn_id,
+ }
+ if prompt_len is not None:
+ record["prompt_len"] = int(prompt_len)
+ return record
+
+
+def build_stop_event(
+ sid: str,
+ tokens: dict | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ cost_session_usd: float | None = None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 stop 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "stop",
+ "sid": sid,
+ "agent": active_agent or "main",
+ }
+ if tokens:
+ record["tokens"] = tokens
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if cost_session_usd is not None:
+ record["cost_session_usd"] = cost_session_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_error_event(
+ phase: str,
+ error: str,
+ sid: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 error 事件记录。"""
+ return {
+ "event": "error",
+ "sid": sid or "",
+ "phase": phase,
+ "error": error,
+ }
+
+
+def build_stage_transition_event(
+ sid: str,
+ task_slug: str,
+ stage: str,
+ status: str | None = None,
+ executor: str | None = None,
+ retry_count: int = 0,
+ review_result: str | None = None,
+) -> dict[str, Any]:
+ """构造 devflow stage 变更事件(只在检测到 devflow 运行、且 stage 真的变化时发出)。
+
+ 对应 `workflow-state.json` 里某个 stage 的 `status`/`retry_count`/`review_result`
+ 发生变化——retry_count 上升或 review_result="failed" 是 devflow 里最值得关注的
+ 信号(返工/打回循环),比 hook 自身的 `error` 事件更贴近业务语义。
+ """
+ record: dict[str, Any] = {
+ "event": "stage_transition",
+ "sid": sid,
+ "task_slug": task_slug,
+ "stage": stage,
+ }
+ if status:
+ record["status"] = status
+ if executor:
+ record["executor"] = executor
+ if retry_count:
+ record["retry_count"] = int(retry_count)
+ if review_result:
+ record["review_result"] = review_result
+ return record
+
+
+def resolve_overrides_path() -> Path | None:
+ """返回当前生效的覆盖文件路径:`AOBS_PRICING_OVERRIDES_PATH` 优先,否则默认路径。
+
+ 返回 `None` 表示"不加载任何覆盖"(纯内置价格表)。支持 `~` 展开。
+ """
+ raw = os.environ.get("AOBS_PRICING_OVERRIDES_PATH", "").strip()
+ if raw:
+ return Path(raw).expanduser()
+ return DEFAULT_OVERRIDES_PATH
+
+
+def _coerce_price_table(data: Any) -> dict[str, dict[str, float]]:
+ """把任意 JSON 结果规整成 `{model: {field: float}}`,坏数据按字段/按模型跳过。
+
+ 与内置表加载的差别只有一处:内置表遇到非数字会整体抛错降级,这里逐字段跳过——
+ 用户的补丁文件里写错一个字段不应该把其余正确的覆盖一起丢掉,更不应该让 hook 挂掉。
+ """
+ if not isinstance(data, dict):
+ return {}
+ table: dict[str, dict[str, float]] = {}
+ for raw_key, raw_value in data.items():
+ if not isinstance(raw_value, dict):
+ continue
+ key = str(raw_key).strip().lower()
+ if not key:
+ continue
+ row: dict[str, float] = {}
+ for price_key, price_value in raw_value.items():
+ # bool 是 int 的子类,True 会被 float() 变成 1.0,这里按"不是价格"处理。
+ if price_value is None or isinstance(price_value, bool):
+ continue
+ try:
+ row[str(price_key).strip().lower()] = float(price_value)
+ except (TypeError, ValueError):
+ continue
+ # 全是坏字段的模型不落表:否则它会被 `lookup_price` 命中成 {},
+ # 既算不出成本又不算"未定价",看板上会变成一个查不到原因的空洞。
+ if row:
+ table[key] = row
+ return table
+
+
+def load_price_overrides(path: Path | None = None) -> dict[str, dict[str, float]]:
+ """加载用户定价覆盖文件;任何异常都静默降级为空覆盖(纯内置价格表)。
+
+ 静默是刻意的:这个文件是给人手写的常驻配置,hook 每次都是新进程,
+ 一旦因格式问题抛异常/打印,会让整条 hook 链路变得不可用。
+ """
+ try:
+ target = path if path is not None else resolve_overrides_path()
+ if not target:
+ return {}
+ with Path(target).expanduser().open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ return _coerce_price_table(data)
+
+
+def merge_prices(
+ base: dict[str, dict[str, float]] | None,
+ overrides: dict[str, dict[str, float]] | None,
+) -> dict[str, dict[str, float]]:
+ """字段级合并价格表:覆盖里写出的字段替换内置值,没写的字段沿用内置值。
+
+ 可以新增内置表里不存在的模型;**不支持删除**内置模型或字段(合并只能加不能减)。
+ """
+ merged: dict[str, dict[str, float]] = {}
+ for model, row in (base or {}).items():
+ if isinstance(row, dict):
+ merged[model] = dict(row)
+ for model, patch in (overrides or {}).items():
+ if not isinstance(patch, dict):
+ continue
+ merged.setdefault(model, {}).update(patch)
+ return merged
+
+
+def _load_builtin_prices() -> dict[str, dict[str, float]]:
+ """从 `config/pricing.json` 中一次性加载内置模型价格配置(不含用户覆盖)。"""
+ path = os.environ.get("AOBS_PRICES_PATH", "").strip()
+ prices_path = Path(path).expanduser() if path else DEFAULT_PRICES_PATH
+ try:
+ with prices_path.open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ return {
+ str(key).lower(): {price_key: float(price_value) for price_key, price_value in value.items()}
+ for key, value in data.items()
+ if isinstance(value, dict)
+ }
+
+
+@lru_cache(maxsize=1)
+def load_prices() -> dict[str, dict[str, float]]:
+ """内置价格表 + 用户覆盖文件的合并结果(字段级)。
+
+ 结果带 `lru_cache`:hook 是短命进程,一次会话里只该读一次盘;长驻进程或单测里
+ 改了覆盖文件/环境变量后,调 `clear_price_cache()` 让下一次调用重新加载。
+ """
+ return merge_prices(_load_builtin_prices(), load_price_overrides())
+
+
+def clear_price_cache() -> None:
+ """丢弃 `load_prices()` 的缓存,让下一次调用重读磁盘与环境变量。"""
+ load_prices.cache_clear()
+
+
+def lookup_price(model: str | None) -> dict[str, float] | None:
+ """为一个具体模型名找到最匹配的价格配置项。"""
+ if not model or not isinstance(model, str):
+ return None
+ normalized = model.lower().strip()
+ if not normalized:
+ return None
+ prices = load_prices()
+ if normalized in prices:
+ return prices[normalized]
+ best_key: str | None = None
+ for key in prices:
+ if key in normalized and (best_key is None or len(key) > len(best_key)):
+ best_key = key
+ if best_key is None:
+ return None
+ return prices[best_key]
+
+
+def is_unpriced(model: str | None) -> bool:
+ """模型是否完全没命中价格表(含模糊匹配)。
+
+ "未定价"的唯一口径就是 `lookup_price(...) is None`(D4):模糊(最长子串)命中的
+ 模型能算出成本,就不该出现在看板的"建议补价"提示里。
+ """
+ return lookup_price(model) is None
+
+
+def estimate_cost(tokens: dict | None, model: str | None) -> dict[str, Any] | None:
+ """根据归一化后的 token 总量估算单条 usage 事件的成本。"""
+ if not isinstance(tokens, dict):
+ return None
+ rates = lookup_price(model)
+ if not rates:
+ return None
+
+ def _int(key: str) -> int:
+ try:
+ return int(tokens.get(key) or 0)
+ except Exception:
+ return 0
+
+ output = _int("output")
+ cache_read = _int("cache_read")
+ cache_write = _int("cache_creation")
+ raw_input = _int("input")
+ fresh_input = raw_input - cache_read - cache_write if raw_input and raw_input >= (cache_read + cache_write) else raw_input
+ cost = (
+ fresh_input * rates.get("input", 0.0)
+ + cache_read * rates.get("cache_read", 0.0)
+ + cache_write * rates.get("cache_write", 0.0)
+ + output * rates.get("output", 0.0)
+ ) / 1_000_000.0
+
+ matched_key = None
+ normalized = (model or "").lower()
+ for key in load_prices():
+ if key in normalized and (matched_key is None or len(key) > len(matched_key)):
+ matched_key = key
+ if matched_key is None and normalized in load_prices():
+ matched_key = normalized
+
+ return {
+ "usd": round(cost, 6),
+ "model_matched": matched_key,
+ "rates": rates,
+ }
+
+
+def cost_of(tokens: dict | None, model: str | None) -> float | None:
+ """只返回美元成本值的便捷封装。"""
+ if not tokens or not model:
+ return None
+ info = estimate_cost(tokens, model)
+ if not info:
+ return None
+ return info.get("usd")
+
+
+def sum_session_cost(log_path: Path, sid: str) -> float | None:
+ """尽力根据已发出的事件反算整个 session 的总成本。"""
+ if not log_path.exists() or not sid:
+ return None
+ total = 0.0
+ seen = False
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") not in {"usage", "tool"}:
+ continue
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ total += float(cost)
+ seen = True
+ except Exception:
+ return None
+ return round(total, 6) if seen else None
diff --git a/.claude/skills/agent-observability/scripts/core/runtime.py b/.claude/skills/agent-observability/scripts/core/runtime.py
new file mode 100644
index 00000000..9c647bc0
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/runtime.py
@@ -0,0 +1,598 @@
+from __future__ import annotations
+"""Hook 主编排入口。
+
+这一层负责把外部 hook phase 分发到内部能力:
+- session-start / user-prompt-submit / pre / post / stop
+- 组装统一运行时路径
+- 串联 collector / emitter / agentlens,并承担 transcript 运行时编排
+"""
+
+import os
+import re
+import time
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, agentlens, collector, devflow, emitter, scanner, state as st
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+ """运行时常用路径集合,避免每个分支重复计算。"""
+ base_dir: Path
+ state_path: Path
+ pending_path: Path
+ log_path: Path
+
+
+def base_dir() -> Path:
+ """返回 hook 运行时使用的根目录。"""
+ # 运行时产物统一写到 skill 根目录下的 logs/,保持与旧路径兼容。
+ return Path(__file__).resolve().parents[2]
+
+
+def build_runtime_paths() -> RuntimePaths:
+ """构造本次 hook 运行要用到的路径集合。"""
+ base = base_dir()
+ return RuntimePaths(
+ base_dir=base,
+ state_path=st.get_state_path(base),
+ pending_path=st.get_pending_path(base),
+ log_path=emitter.get_log_path(base),
+ )
+
+
+def session_id_of(data: dict[str, Any]) -> str:
+ """兼容不同字段名,提取 session id。"""
+ return str(data.get("session_id") or data.get("sid") or "")
+
+
+def cwd(data: dict[str, Any]) -> str:
+ """解析当前项目工作目录。"""
+ return str(data.get("cwd") or os.environ.get("CODEBUDDY_PROJECT_DIR") or os.getcwd())
+
+
+def normalize_phase(raw: str | None) -> str:
+ """把多种 phase 写法折叠成统一内部枚举。"""
+ phase = (raw or "").strip().lower()
+ return {
+ "sessionstart": "session-start",
+ "session_start": "session-start",
+ "session-start": "session-start",
+ "pretooluse": "pre",
+ "pre": "pre",
+ "posttooluse": "post",
+ "post": "post",
+ "stop": "stop",
+ "userpromptsubmit": "user-prompt-submit",
+ "user_prompt_submit": "user-prompt-submit",
+ "user-prompt-submit": "user-prompt-submit",
+ "prompt": "user-prompt-submit",
+ }.get(phase, phase)
+
+
+def emit_error(phase: str, sid: str, err: Exception) -> None:
+ """把运行时异常写成 error 事件,而不是直接中断 hook。"""
+ rec = emitter.build_error_event(phase=phase, error=f"{type(err).__name__}: {err}", sid=sid)
+ rec["x_traceback"] = traceback.format_exc(limit=5)[-1200:]
+ emitter.emit(build_runtime_paths().log_path, rec)
+
+
+def derive_turn_id(data: dict[str, Any]) -> str:
+ """优先复用外部已有 id,否则生成一个本地 turn id。"""
+ for key in ("turn_id", "prompt_id", "request_id", "message_id"):
+ raw = data.get(key)
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ if isinstance(raw, (int, float)) and raw:
+ return str(raw)
+ return f"turn-{int(time.time() * 1000)}"
+
+
+def prompt_text_length(data: dict[str, Any]) -> int | None:
+ """统计用户 prompt 的文本长度,用于 turn 边界指标。"""
+ for key in ("prompt", "user_prompt", "message", "content", "text"):
+ val = data.get(key)
+ if isinstance(val, str):
+ return len(val)
+ if isinstance(val, list):
+ total = 0
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ total += len(txt)
+ elif isinstance(item, str):
+ total += len(item)
+ if total:
+ return total
+ return None
+
+
+def extract_prompt_text(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取可读的 prompt 文本。"""
+ for key in ("prompt", "user_prompt", "message", "text"):
+ val = data.get(key)
+ if isinstance(val, str) and val.strip():
+ return val.strip()
+ if isinstance(val, list):
+ parts = []
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif isinstance(item, str):
+ parts.append(item)
+ if parts:
+ return "\n".join(parts).strip()
+ return ""
+
+
+def derive_business_scenario(prompt_text: str) -> str | None:
+ """从 prompt 文本中派生一个简短业务场景标识。"""
+ if not prompt_text:
+ return None
+
+ m = re.search(r"标题[::]\s*(.+?)(?:\s*描述[::]|\s*$)", prompt_text, re.DOTALL)
+ if m:
+ title = m.group(1).strip()[:60]
+ else:
+ title = prompt_text[:50].strip()
+
+ sanitized = re.sub(r"[^\w\u4e00-\u9fff\-]", "-", title)
+ sanitized = re.sub(r"-{2,}", "-", sanitized).strip("-")
+ return sanitized if sanitized else None
+
+
+def handle_session_start(data: dict[str, Any]) -> None:
+ """处理 SessionStart:预热 inventory,写 start 事件,初始化 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+ emitter.emit(paths.log_path, emitter.build_start_event(sid=current_sid, agent="main"))
+ agentlens.emit_session_start(state_path=paths.state_path, sid=current_sid, cwd=cwd_value, agent="main")
+
+
+def handle_user_prompt_submit(data: dict[str, Any]) -> None:
+ """处理 UserPromptSubmit:建立 turn 边界,并打开 AgentLens turn。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ turn_id = derive_turn_id(data)
+ prompt_len = prompt_text_length(data)
+ prompt_text = extract_prompt_text(data)
+ business_scenario = derive_business_scenario(prompt_text)
+
+ emitter.emit(
+ paths.log_path,
+ emitter.build_prompt_submit_event(sid=current_sid, turn_id=turn_id, agent="main", prompt_len=prompt_len),
+ )
+ agentlens.emit_turn_start(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ turn_id=turn_id,
+ prompt_meta={"prompt_len": prompt_len} if prompt_len is not None else None,
+ business_scenario=business_scenario,
+ )
+
+
+def handle_pre(data: dict[str, Any]) -> None:
+ """处理 PreToolUse:仅记录 pending,等待 post 配对。"""
+ collector.record_pre(build_runtime_paths().pending_path, data)
+
+
+def handle_post(data: dict[str, Any]) -> None:
+ """处理 PostToolUse:计算耗时、归因 agent、发 tool/usage 事件。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ duration_ms = collector.record_post(paths.pending_path, data)
+
+ skills_meta, rules_meta = collector.load_cached_inventory(paths.state_path, current_sid)
+ if not skills_meta and not rules_meta:
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ used_skills, used_rules = collector.record_tool_usage(
+ state_path=paths.state_path,
+ sid=current_sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent=active_agent,
+ collect_skills=True,
+ )
+
+ tool_name = str(data.get("tool_name") or "")
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ event_ts = time.time()
+ tool_call_id = collector.extract_tool_call_id(data)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ )
+ tool_context = collector.find_current_tool_context(
+ state_path=paths.state_path,
+ sid=current_sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=tool_call_id,
+ event_ts=event_ts,
+ claim=True,
+ )
+ duplicate_tool_context = bool(isinstance(tool_context, dict) and tool_context.get("duplicate"))
+ if duplicate_tool_context:
+ tool_context = None
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ transcript_path = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ active_agent = resolved_agent
+
+ tool_pt_id = str(tool_context.get("pt_id") or "").strip() if isinstance(tool_context, dict) else None
+ tool_event = emitter.build_tool_event(
+ sid=current_sid,
+ tool=tool_name,
+ duration_ms=duration_ms,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ pt_id=tool_pt_id,
+ )
+ tool_event["ts"] = event_ts
+ tool_event["skill"] = used_skills
+ tool_event["rule"] = used_rules
+ tool_event["cwd"] = cwd_value
+ if tool_call_id:
+ tool_event["call_id"] = tool_call_id
+ if isinstance(tool_context, dict):
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+
+ usage_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name=tool_name,
+ event_kind="usage",
+ max_lines=80,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ if duplicate_tool_context:
+ if not usage_events:
+ return
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=None,
+ usage_events=usage_events,
+ )
+ return
+ if str(tool_event.get("message_id") or "").strip():
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ fallback_usage = collector.find_fallback_usage_event(tool_event, usage_events)
+ fallback_usage_mid = str((fallback_usage or {}).get("message_id") or "").strip() or None
+ if fallback_usage_mid:
+ tool_event["message_id"] = fallback_usage_mid
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ st.append_pending_tool_emit(paths.state_path, current_sid, tool_event)
+
+
+def handle_stop(data: dict[str, Any]) -> None:
+ """处理 Stop:补发 transcript 事件、汇总 session 成本并关闭 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ stop_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.settled_related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name="__stop__",
+ event_kind="stop",
+ max_lines=200,
+ cost_session=emitter.sum_session_cost(paths.log_path, current_sid),
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ force_emit_fallback=True,
+ )
+ agentlens.emit_session_stop(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ stop_events=stop_events,
+ )
+
+
+def resolve_devflow(state_path: Path, sid: str, cwd_value: str, log_path: Path) -> dict[str, Any] | None:
+ """解析 devflow 上下文,并把本次观测到的 stage 变更立即发成 `stage_transition` 事件。
+
+ 任何异常都吞掉、返回 None——devflow 感知是可选增强,绝不能让不跑 devflow 的
+ 项目或 workflow-state.json 格式变化导致 hook 报错。
+ """
+ try:
+ dv_ctx = devflow.resolve_and_diff(state_path, sid, cwd_value)
+ except Exception:
+ return None
+ if not isinstance(dv_ctx, dict):
+ return None
+ task_slug = str(dv_ctx.get("task_slug") or "").strip()
+ if not task_slug:
+ return None
+ for change in dv_ctx.get("changes") or []:
+ if not isinstance(change, dict):
+ continue
+ event = emitter.build_stage_transition_event(
+ sid=sid,
+ task_slug=task_slug,
+ stage=str(change.get("stage") or ""),
+ status=change.get("status"),
+ executor=change.get("executor"),
+ retry_count=int(change.get("retry_count") or 0),
+ review_result=change.get("review_result"),
+ )
+ emitter.emit(log_path, event)
+ return dv_ctx
+
+
+def current_turn_id(state_path: Path, sid: str) -> str | None:
+ """从 state 中读取当前 session 激活中的 turn id。"""
+ try:
+ turn = st.get_current_turn(state_path, sid)
+ except Exception:
+ turn = None
+ if isinstance(turn, dict):
+ raw = turn.get("turn_id")
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ return None
+
+
+def flush_pending_tool_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ force_emit_fallback: bool = False,
+) -> None:
+ """强制 flush 延迟的 tool 事件,常用于 stop/replay 路径。"""
+ pending = st.get_pending_tool_emits(state_path, sid)
+ if not pending:
+ return
+
+ remaining: list[dict[str, Any]] = []
+ for tool_event in pending:
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ call_id = str(tool_event.get("call_id") or "").strip() or None
+ event_ts = tool_event.get("ts")
+ try:
+ event_ts_float = float(event_ts) if event_ts is not None else None
+ except Exception:
+ event_ts_float = None
+
+ tool_context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=call_id,
+ event_ts=event_ts_float,
+ claim=True,
+ )
+ if isinstance(tool_context, dict) and tool_context.get("duplicate"):
+ continue
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ tool_event["transcript_path"] = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ tool_event["agent"] = resolved_agent
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ if force_emit_fallback:
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ remaining.append(tool_event)
+
+ st.replace_pending_tool_emits(state_path, sid, remaining)
+
+
+def emit_transcript_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ transcript_paths: list[str],
+ current_transcript_path: str,
+ active_agent: str,
+ tool_name: str,
+ event_kind: str,
+ max_lines: int,
+ cost_session: float | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> list[dict[str, Any]]:
+ """发出基于 transcript 增量重建得到的 usage/stop 事件。"""
+ emitted_events: list[dict[str, Any]] = []
+ current_resolved = str(Path(current_transcript_path).resolve()) if current_transcript_path else ""
+ for path in transcript_paths:
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ entries = scan.get("entries", []) or []
+ event_tool = tool_name if event_kind == "usage" and path == current_resolved else "model_request"
+ event_agent = active_agent if path == current_resolved else agent_identity.agent_for_transcript_path(path, active_agent)
+
+ for idx, entry in enumerate(entries):
+ event_key = collector.build_transcript_event_key(kind=event_kind, tool=event_tool, entry=entry)
+ if not st.claim_transcript_event(state_path, sid, event_key, path):
+ continue
+ tokens = entry.get("tokens")
+ model = entry.get("model")
+ if event_kind == "stop":
+ event = emitter.build_stop_event(
+ sid=sid,
+ tokens=tokens,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ cost_session_usd=cost_session if idx == len(entries) - 1 else None,
+ active_agent=event_agent,
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ else:
+ event = emitter.build_usage_event(
+ sid=sid,
+ tool=event_tool,
+ tokens=tokens,
+ active_agent=event_agent,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ emitter.emit(log_path, event)
+ emitted_events.append(event)
+
+ st.commit_transcript_progress(
+ state_path,
+ sid,
+ path,
+ offset=int(scan.get("new_offset", 0) or 0),
+ last_cumulative_usage=scan.get("last_cumulative"),
+ )
+ return emitted_events
+
+
+def main(argv: list[str]) -> int:
+ """读取 stdin 输入并按 phase 执行对应 hook 处理分支。"""
+ phase = normalize_phase(argv[0] if argv else "")
+ current_sid = ""
+ try:
+ data = collector.read_stdin_json()
+ current_sid = session_id_of(data)
+ if phase == "session-start":
+ handle_session_start(data)
+ elif phase == "user-prompt-submit":
+ handle_user_prompt_submit(data)
+ elif phase == "pre":
+ handle_pre(data)
+ elif phase == "post":
+ handle_post(data)
+ elif phase == "stop":
+ handle_stop(data)
+ else:
+ emitter.emit(
+ build_runtime_paths().log_path,
+ emitter.build_error_event(phase=phase or "unknown", error=f"Unsupported phase: {phase!r}", sid=current_sid),
+ )
+ except Exception as exc:
+ emit_error(phase=phase or "unknown", sid=current_sid, err=exc)
+ return 0
diff --git a/.claude/skills/agent-observability/scripts/core/scanner.py b/.claude/skills/agent-observability/scripts/core/scanner.py
new file mode 100644
index 00000000..86b5305e
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/scanner.py
@@ -0,0 +1,496 @@
+"""Skill / Rule 静态扫描层。
+
+这一层只负责扫描项目里的 `.codebuddy/skills` 与 `.codebuddy/rules`:
+- 识别有哪些可用 skill / rule
+- 提取它们的基础元数据与 frontmatter
+- 提供 path-based 命中推断依赖的 inventory 信息
+
+它不依赖具体 workflow 语义,本身是通用层。
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# --- 用于解析 SKILL.md / RULE.mdc frontmatter 的正则 ---
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.S)
+NAME_FIELD_RE = re.compile(r"^name:\s*(.+)$", re.M)
+VERSION_FIELD_RE = re.compile(r"^version:\s*(.+)$", re.M)
+AUTHOR_FIELD_RE = re.compile(r"^author:\s*(.+)$", re.M)
+TAGS_FIELD_RE = re.compile(r"^tags:\s*\[([^\]]+)\]", re.M)
+DESC_FIELD_RE = re.compile(r"^description:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+ALWAYS_APPLY_RE = re.compile(r"^alwaysApply:\s*(true|false)\s*$", re.M | re.I)
+ENABLED_RE = re.compile(r"^enabled:\s*(true|false)\s*$", re.M | re.I)
+GLOBS_RE = re.compile(r"^globs:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+APPLY_AGENTS_RE = re.compile(r"^applyAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+EXCLUDE_AGENTS_RE = re.compile(r"^excludeAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+
+# 固定的 inventory 根目录(仅限项目内)
+PROJECT_SKILLS_REL = Path(".codebuddy/skills")
+PROJECT_RULES_REL = Path(".codebuddy/rules")
+
+# 支持识别的 skill 子模块根目录
+SUBMODULE_DIRS = {"references", "scripts", "templates", "examples", "checklists", "roles"}
+
+# 允许严格提取的路径类字段键名(不扫描自由文本)
+PATH_VALUE_KEYS = {
+ "file_path", "filePath", "path", "target_file", "target_directory",
+ "cwd", "rule", "rule_path", "skill_path",
+}
+PATH_LIST_KEYS = {"paths", "files", "rules", "skills"}
+
+# 扫描时要跳过的目录
+SKIP_DIR_PARTS = {"skills-by-node", "node_modules", ".git", "__pycache__", "dist"}
+
+# 可能触发 skill 的工具名
+USE_SKILL_TOOLS = {"use_skill", "UseSkill", "load_skill", "Skill", "skill"}
+
+
+def _is_skipped_path(p: Path) -> bool:
+ """判断路径是否命中扫描时应跳过的目录集合。"""
+ parts = set(p.parts)
+ return bool(parts & SKIP_DIR_PARTS)
+
+
+def _parse_frontmatter(path: Path) -> dict[str, Any]:
+ """解析 `SKILL.md` 或 `RULE.mdc` 中的 frontmatter。"""
+ try:
+ text = path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ def _grab(regex, key, post=None):
+ mm = regex.search(block)
+ if mm:
+ v = mm.group(1).strip().strip('"\'').strip()
+ info[key] = post(v) if post else v
+
+ _grab(NAME_FIELD_RE, "name")
+ _grab(VERSION_FIELD_RE, "version")
+ _grab(AUTHOR_FIELD_RE, "author")
+ _grab(TAGS_FIELD_RE, "tags",
+ lambda v: [t.strip().strip('"\'') for t in v.split(",") if t.strip()])
+ _grab(DESC_FIELD_RE, "description", lambda v: v.strip().replace("\n", " ")[:200])
+ return info
+
+
+def _parse_list_field(block: str, regex: re.Pattern[str]) -> list[str]:
+ """从 frontmatter 文本块中解析一个逗号分隔的列表字段。"""
+ mm = regex.search(block)
+ if not mm:
+ return []
+ raw = mm.group(1).strip().strip('"\'')
+ if raw.startswith("["):
+ raw = raw.strip("[]")
+ return [g.strip().strip('"\'').lower() for g in raw.split(",") if g.strip()]
+
+
+def _parse_rule_frontmatter(rule_path: Path) -> dict[str, Any]:
+ """解析 `RULE.mdc` 中和规则生效相关的 frontmatter 字段。"""
+ try:
+ text = rule_path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ mm = ALWAYS_APPLY_RE.search(block)
+ if mm:
+ info["alwaysApply"] = mm.group(1).lower() == "true"
+ mm = ENABLED_RE.search(block)
+ if mm:
+ info["enabled"] = mm.group(1).lower() == "true"
+ globs = _parse_list_field(block, GLOBS_RE)
+ if globs:
+ info["globs"] = globs
+
+ apply_agents = _parse_list_field(block, APPLY_AGENTS_RE)
+ if apply_agents:
+ info["applyAgents"] = apply_agents
+
+ exclude_agents = _parse_list_field(block, EXCLUDE_AGENTS_RE)
+ if exclude_agents:
+ info["excludeAgents"] = exclude_agents
+
+ mm = DESC_FIELD_RE.search(block)
+ if mm:
+ info["description"] = mm.group(1).strip().strip('"\'').replace("\n", " ")[:200]
+ return info
+
+
+def _classify_source(path: Path, cwd: Path | None) -> str:
+ """识别来源类型;当前只支持项目内 `.codebuddy` 路径。"""
+ if not cwd:
+ return "unknown"
+ try:
+ path_str = str(path.resolve())
+ cwd_str = str(cwd.resolve())
+ except Exception:
+ return "unknown"
+ if path_str.startswith(cwd_str + "/.codebuddy/"):
+ return "project"
+ return "unknown"
+
+
+def _collect_submodules(skill_dir: Path) -> dict[str, list]:
+ """收集一个 skill 内部的子模块目录,如 references/scripts/templates。"""
+ sub: dict = {}
+ if not skill_dir.is_dir():
+ return sub
+ for kind in ("references", "scripts", "templates", "examples", "checklists", "roles"):
+ d = skill_dir / kind
+ if d.is_dir():
+ files = [str(f.relative_to(skill_dir))
+ for f in d.rglob("*") if f.is_file()]
+ if files:
+ sub[kind] = sorted(files)[:30]
+ return sub
+
+
+def scan_skills_and_rules(cwd: str) -> tuple[dict[str, Any], dict[str, Any]]:
+ """扫描项目固定根目录:`.codebuddy/skills` 与 `.codebuddy/rules`。"""
+ skills: dict = {}
+ rules: dict = {}
+ cwd_path = Path(cwd) if cwd else None
+ if not cwd_path or not cwd_path.exists():
+ return skills, rules
+
+ skills_root = (cwd_path / PROJECT_SKILLS_REL).resolve()
+ rules_root = (cwd_path / PROJECT_RULES_REL).resolve()
+
+ if skills_root.is_dir() and not _is_skipped_path(skills_root):
+ for p in skills_root.rglob("SKILL.md"):
+ if _is_skipped_path(p):
+ continue
+ skill_dir = p.parent
+ name = skill_dir.name
+ if not name or name in skills:
+ continue
+ meta = _parse_frontmatter(p)
+ skills[name] = {
+ "source": _classify_source(skill_dir, cwd_path),
+ "path": str(skill_dir),
+ "has_skill_md": True,
+ "version": meta.get("version"),
+ "author": meta.get("author"),
+ "description": meta.get("description"),
+ "submodules": _collect_submodules(skill_dir),
+ }
+
+ if rules_root.is_dir() and not _is_skipped_path(rules_root):
+ for p in rules_root.rglob("*.mdc"):
+ if _is_skipped_path(p):
+ continue
+ name = p.parent.name if p.name == "RULE.mdc" else p.stem
+ if not name or name in rules:
+ continue
+ meta = _parse_rule_frontmatter(p)
+ rules[name] = {
+ "source": _classify_source(p.parent, cwd_path),
+ "path": str(p),
+ "alwaysApply": meta.get("alwaysApply", False),
+ "enabled": meta.get("enabled", True),
+ "globs": meta.get("globs") or [],
+ "applyAgents": meta.get("applyAgents") or [],
+ "excludeAgents": meta.get("excludeAgents") or [],
+ "description": meta.get("description"),
+ }
+
+ return skills, rules
+
+
+def lookup_skill_meta(skills_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 skill 元数据。"""
+ meta = (skills_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def lookup_rule_meta(rules_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 rule 元数据。"""
+ meta = (rules_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def _collect_path_strings(obj: Any) -> list[str]:
+ """只收集结构化路径字段,绝不解析自由文本。"""
+ out: list[str] = []
+
+ def _walk(x: Any) -> None:
+ if isinstance(x, dict):
+ for k, v in x.items():
+ if k in PATH_VALUE_KEYS and isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif k in PATH_LIST_KEYS:
+ if isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif isinstance(v, list):
+ out.extend([
+ s.strip() for s in v
+ if isinstance(s, str) and s.strip()
+ ])
+ elif isinstance(v, (dict, list)):
+ _walk(v)
+ elif isinstance(x, list):
+ for it in x:
+ if isinstance(it, (dict, list)):
+ _walk(it)
+
+ _walk(obj)
+ return list(dict.fromkeys(out))
+
+
+def _path_parts(path_str: str) -> list[str]:
+ """把路径拆成标准化片段列表,便于后续命中判断。"""
+ p = path_str.replace("\\", "/").strip()
+ return [part for part in p.split("/") if part]
+
+
+def _extract_skill_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 skill 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ name = parts[i + 2]
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _extract_rule_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 rule 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "rules":
+ name = parts[i + 2]
+ if name.lower().endswith(".mdc"):
+ name = Path(name).stem
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _is_rule_allowed_for_agent(name: str, meta: dict[str, Any], active_agent: str | None) -> bool:
+ """按角色判断 rule 是否可用;`global` 永远保持可选。"""
+ if str(name).strip().lower() == "global":
+ return True
+
+ agent = str(active_agent or "").strip().lower()
+ if not agent:
+ return True
+
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+
+ if apply_agents and agent not in apply_agents:
+ return False
+ if exclude_agents and agent in exclude_agents:
+ return False
+ return True
+
+
+def _glob_matches_any_path(globs: list[str], paths_to_check: list[str]) -> bool:
+ """判断配置的 glob 是否命中任一收集到的路径。"""
+ if not globs or not paths_to_check:
+ return False
+ import fnmatch
+
+ for p in paths_to_check:
+ basename = os.path.basename(p)
+ if any(fnmatch.fnmatch(p, g) or fnmatch.fnmatch(basename, g) for g in globs):
+ return True
+ return False
+
+
+def evaluate_rules_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """评估当前工具调用下所有已知 rule,并保留未命中的原因。"""
+ if not rules_meta:
+ return {}
+
+ tool_input = data.get("tool_input") or {}
+ paths_to_check = _collect_path_strings(tool_input)
+ _, path_rules = extract_paths_from_tool_call(data)
+ path_rule_set = set(path_rules)
+
+ evaluations: dict[str, dict[str, Any]] = {}
+ for name, meta in (rules_meta or {}).items():
+ if not isinstance(meta, dict):
+ continue
+
+ globs = [str(g).strip() for g in (meta.get("globs") or []) if str(g).strip()]
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+ evaluation: dict[str, Any] = {"matched": False}
+
+ if name in path_rule_set:
+ evaluation["matched"] = True
+ evaluation["via"] = "path_inferred"
+ elif meta.get("enabled") is False:
+ evaluation["reason"] = "disabled"
+ elif not _is_rule_allowed_for_agent(name, meta, active_agent):
+ evaluation["reason"] = "agent_filtered"
+ if apply_agents:
+ evaluation["applyAgents"] = apply_agents
+ if exclude_agents:
+ evaluation["excludeAgents"] = exclude_agents
+ elif meta.get("alwaysApply"):
+ evaluation["matched"] = True
+ evaluation["via"] = "always_apply"
+ elif globs:
+ evaluation["globs"] = globs
+ evaluation["paths_checked"] = len(paths_to_check)
+ if not paths_to_check:
+ evaluation["reason"] = "no_paths"
+ elif _glob_matches_any_path(globs, paths_to_check):
+ evaluation["matched"] = True
+ evaluation["via"] = "glob"
+ else:
+ evaluation["reason"] = "glob_not_matched"
+ evaluation["paths_sample"] = paths_to_check[:3]
+ else:
+ evaluation["reason"] = "no_globs"
+
+ evaluations[name] = evaluation
+
+ return evaluations
+
+
+def unmatched_rule_diagnostics_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """返回当前工具调用下未命中的 rule 的精简诊断信息。"""
+ diagnostics: dict[str, dict[str, Any]] = {}
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched"):
+ continue
+ item: dict[str, Any] = {"reason": evaluation.get("reason") or "unknown"}
+ for key in ("globs", "paths_checked", "paths_sample", "applyAgents", "excludeAgents"):
+ value = evaluation.get(key)
+ if value is not None and value != []:
+ item[key] = value
+ diagnostics[name] = item
+ return diagnostics
+
+
+def filtered_rules_for_agent(rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """列出因 agent 过滤而被排除的 rule(仅看已启用项)。"""
+ filtered: list[str] = []
+ for name, evaluation in evaluate_rules_for_call({}, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("reason") == "agent_filtered":
+ filtered.append(name)
+ return sorted(set(filtered))
+
+
+def active_rules_for_call(data: dict, rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """判断给定工具调用下哪些 rule 处于生效状态。"""
+ active: list[str] = []
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched") and evaluation.get("via") != "path_inferred":
+ active.append(name)
+ return sorted(set(active))
+
+
+def extract_skill_from_tool_call(data: dict) -> str | None:
+ """从类似 use_skill 的工具调用里提取 skill 名称。"""
+ tool = data.get("tool_name", "")
+ if tool not in USE_SKILL_TOOLS:
+ return None
+ tool_input = data.get("tool_input") or {}
+ if isinstance(tool_input, dict):
+ return tool_input.get("command") or tool_input.get("name") or tool_input.get("skill")
+ return None
+
+
+def is_brainstorming_call(data: dict) -> bool:
+ """判断当前工具调用是否正在激活或使用 brainstorming skill。"""
+ direct = extract_skill_from_tool_call(data)
+ if isinstance(direct, str) and direct.strip().lower() == "brainstorming":
+ return True
+
+ path_skills, _ = extract_paths_from_tool_call(data)
+ return any(str(s).strip().lower() == "brainstorming" for s in path_skills)
+
+
+def extract_paths_from_tool_call(data: dict) -> tuple[list[str], list[str]]:
+ """只根据 `.codebuddy` 根目录下的结构化路径推断 skill/rule。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return [], []
+
+ skills: list[str] = []
+ rules: list[str] = []
+ for p in _collect_path_strings(tool_input):
+ s = _extract_skill_from_path(p)
+ if s:
+ skills.append(s)
+ r = _extract_rule_from_path(p)
+ if r:
+ rules.append(r)
+
+ return list(dict.fromkeys(skills)), list(dict.fromkeys(rules))
+
+
+def extract_submodule_hits(data: dict) -> list[dict[str, str]]:
+ """仅从结构化 skill 路径中提取子模块命中结果,不扫描自由文本。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+
+ seen: set[tuple[str, str]] = set()
+ hits: list[dict[str, str]] = []
+ path_values = _collect_path_strings(tool_input)
+
+ for p in path_values:
+ parts = _path_parts(p)
+ for i in range(len(parts) - 3):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ skill_name = parts[i + 2]
+ sub_root = parts[i + 3]
+ if not re.fullmatch(r"[a-zA-Z0-9_\-]+", skill_name):
+ continue
+ if sub_root not in SUBMODULE_DIRS:
+ continue
+ sub_path = "/".join(parts[i + 3:]).rstrip("/")
+ key = (skill_name, sub_path)
+ if key in seen:
+ continue
+ seen.add(key)
+ hits.append({"skill": skill_name, "submodule": sub_path})
+ break
+
+ return hits
+
+
+def extract_bash_skill_scripts(data: dict) -> list[str]:
+ """从命令文本中的显式 `.codebuddy/skills` 路径识别 skill 脚本。"""
+ if data.get("tool_name") not in ("Bash", "bash", "execute_command"):
+ return []
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+ cmd = tool_input.get("command") or ""
+ if not isinstance(cmd, str) or not cmd.strip():
+ return []
+
+ skills: list[str] = []
+ for token in cmd.split():
+ t = token.strip("\"'`;,()[]{}")
+ s = _extract_skill_from_path(t)
+ if s:
+ skills.append(s)
+ return list(dict.fromkeys(skills))
diff --git a/.claude/skills/agent-observability/scripts/core/state.py b/.claude/skills/agent-observability/scripts/core/state.py
new file mode 100644
index 00000000..5e7d33e9
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/core/state.py
@@ -0,0 +1,1222 @@
+"""持久化状态层。
+
+这一层负责跨 hook 调用保存与协调状态:
+- session 级 skill/rule 使用统计
+- 当前 agent、派发关系与历史
+- transcript offset、去重 claim、pending emits
+- AgentLens sidecar 状态
+"""
+from __future__ import annotations
+
+import json
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+try:
+ import fcntl
+except Exception: # pragma: no cover - non-posix fallback
+ fcntl = None # type: ignore
+
+
+def get_state_path(base_dir: Path) -> Path:
+ """返回主状态文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".state.json"
+
+
+def get_pending_path(base_dir: Path) -> Path:
+ """返回 Pre/PostToolUse 配对使用的 pending 文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".pending_calls.json"
+
+
+def load_state(state_path: Path) -> dict[str, Any]:
+ """从磁盘加载状态;任何异常都回退为空字典。"""
+ if state_path.exists():
+ try:
+ return json.loads(state_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_state(state_path: Path, state: dict[str, Any]) -> None:
+ """把状态写回磁盘。"""
+ state_path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+
+
+def get_state_lock_path(state_path: Path) -> Path:
+ """返回状态写锁文件路径。"""
+ return state_path.parent / ".state.lock"
+
+
+def get_transcript_seen_path(state_path: Path) -> Path:
+ """返回 transcript usage 事件 claim 的 sidecar 台账文件。
+
+ 这部分单独存放,不混进 `.state.json`,是为了避免并发 hook 写状态时,
+ 旧 state 覆盖掉已经 claim 过的 transcript offset。
+ """
+ return state_path.parent / ".transcript_events_seen.json"
+
+
+@contextmanager
+def state_lock(state_path: Path):
+ """为状态修改提供跨进程建议锁(独占)。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_EX)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def state_read_lock(state_path: Path):
+ """为状态一致性读取提供跨进程共享读锁。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_SH)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+def update_state_locked(state_path: Path, updater):
+ """在跨进程锁保护下完成 load -> mutate -> save。"""
+ with state_lock(state_path):
+ state = load_state(state_path)
+ result = updater(state)
+ save_state(state_path, state)
+ return result
+
+
+def load_pending(pending_path: Path) -> dict[str, Any]:
+ """加载待配对的 pre/post 数据。"""
+ if pending_path.exists():
+ try:
+ return json.loads(pending_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_pending(pending_path: Path, data: dict[str, Any]) -> None:
+ """保存待配对的 pre/post 数据。"""
+ pending_path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def ensure_session(state: dict, sid: str) -> dict:
+ """确保某个 session 的状态结构存在,并返回该 session 字典。
+
+ Session 结构:
+ {
+ "skills": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "rules": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "started_at": float,
+ "current_agent": str,
+ "agent_history": [{ts, agent, evidence}],
+ "dispatched": {agent_name: count},
+ "_skills_meta": {...}, # SessionStart 时缓存的 inventory
+ "_rules_meta": {...},
+ }
+ """
+ if sid not in state:
+ state[sid] = {
+ "skills": {},
+ "rules": {},
+ "started_at": time.time(),
+ "current_agent": "main",
+ "agent_history": [],
+ "dispatched": {},
+ }
+ sess = state[sid]
+ # 保证字段类型正确,兼容旧数据
+ if not isinstance(sess.get("skills"), dict):
+ sess["skills"] = {}
+ if not isinstance(sess.get("rules"), dict):
+ sess["rules"] = {}
+ sess.setdefault("current_agent", "main")
+ sess.setdefault("agent_history", [])
+ sess.setdefault("dispatched", {})
+ if not isinstance(sess.get("_pending_tool_emits"), list):
+ sess["_pending_tool_emits"] = []
+ return sess
+
+
+def get_devflow_state(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 缓存的 devflow 上下文与最近一次 stage 快照(见 devflow.py)。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ dv = sess.get("_devflow")
+ return dv if isinstance(dv, dict) else {}
+
+
+def set_devflow_state(state: dict[str, Any], sid: str, updates: dict[str, Any]) -> None:
+ """合并写入某个 session 的 devflow 缓存字段(`checked` / `context` / `last_snapshot`)。"""
+ sess = ensure_session(state, sid)
+ dv = sess.get("_devflow")
+ if not isinstance(dv, dict):
+ dv = {}
+ sess["_devflow"] = dv
+ dv.update(updates)
+
+
+def get_agentlens_session(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 的 AgentLens sidecar payload。"""
+ sess = ensure_session(state, sid)
+ payload = sess.setdefault("_agentlens", {})
+ if not isinstance(payload, dict):
+ payload = {}
+ sess["_agentlens"] = payload
+ return payload
+
+
+AGENTLENS_SCHEMA_VERSION = 2
+_TURN_HISTORY_MAX = 5
+
+
+def _migrate_agentlens_v1_to_v2(payload: dict[str, Any], sess: dict[str, Any] | None) -> dict[str, Any]:
+ """把 v1 版 ``_agentlens`` payload 转成以 turn 为中心的 v2 布局。
+
+ v1 布局(pre-turn):
+ {"carrier": {...}, "enabled": bool, "session_id": "...", "app_name": "..."}
+ v2 布局(turn-centric):
+ {
+ "version": 2,
+ "session_id": "...",
+ "enabled": bool,
+ "app_name": "...",
+ "current_turn": {"turn_id": "legacy", "started_at": ..., "carrier": {...}, "subagent_spans": {}, "agent_spans": {}, "step_spans": {}},
+ "turn_history": [],
+ }
+
+ 幂等约束:如果已经带有 ``version``,就原样返回。
+ """
+ if not isinstance(payload, dict):
+ return {"version": AGENTLENS_SCHEMA_VERSION, "enabled": False, "current_turn": None, "turn_history": []}
+ if payload.get("version") == AGENTLENS_SCHEMA_VERSION:
+ payload.setdefault("current_turn", None)
+ payload.setdefault("turn_history", [])
+ current = payload.get("current_turn")
+ if isinstance(current, dict):
+ current.setdefault("subagent_spans", {})
+ current.setdefault("agent_spans", {})
+ current.setdefault("step_spans", {})
+ return payload
+
+ migrated: dict[str, Any] = {
+ "version": AGENTLENS_SCHEMA_VERSION,
+ "session_id": payload.get("session_id"),
+ "enabled": bool(payload.get("enabled", False)),
+ }
+ if "app_name" in payload:
+ migrated["app_name"] = payload.get("app_name")
+ if "last_error" in payload:
+ migrated["last_error"] = payload.get("last_error")
+
+ legacy_carrier = payload.get("carrier")
+ if isinstance(legacy_carrier, dict) and legacy_carrier:
+ started_at = None
+ if isinstance(sess, dict):
+ try:
+ started_at = float(sess.get("started_at") or 0) or None
+ except Exception:
+ started_at = None
+ migrated["current_turn"] = {
+ "turn_id": "legacy",
+ "started_at": started_at or time.time(),
+ "carrier": dict(legacy_carrier),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ else:
+ migrated["current_turn"] = None
+ migrated["turn_history"] = []
+ return migrated
+
+
+def load_agentlens_session(state_path: Path, sid: str) -> dict[str, Any]:
+ """加载某个 session 已持久化的 AgentLens sidecar payload。
+
+ 这里使用共享读锁,避免并发 ``update_agentlens_session`` 写入时读到撕裂数据。
+ 返回值会透明地把 v1 payload 迁移成 v2 副本;真正落盘迁移会在下一次写入时完成。
+ """
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ payload = sess.get("_agentlens")
+ if not isinstance(payload, dict):
+ return {}
+ # 先给调用方返回迁移后的副本,真正持久化迁移留到后续写入时完成。
+ return _migrate_agentlens_v1_to_v2(dict(payload), sess)
+
+
+def update_agentlens_session(
+ state_path: Path,
+ sid: str,
+ updates: dict[str, Any],
+ *,
+ clear_keys: list[str] | None = None,
+) -> dict[str, Any]:
+ """原子地持久化某个 session 的 AgentLens sidecar 字段。
+
+ 在合并 updates 之前会先做 v1→v2 迁移,这样磁盘上的 payload 会随着写入自然收敛到 v2。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ # 如果仍是 v1,就原地迁移。
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+ for key in clear_keys or []:
+ payload.pop(key, None)
+ for key, value in updates.items():
+ if value is None:
+ payload.pop(key, None)
+ else:
+ payload[key] = value
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(payload)
+
+ return update_state_locked(state_path, _update)
+
+
+def begin_turn(
+ state_path: Path,
+ sid: str,
+ turn_id: str,
+ carrier: dict[str, str],
+ *,
+ started_at: float | None = None,
+ max_history: int = _TURN_HISTORY_MAX,
+) -> dict[str, Any]:
+ """在独占锁下打开一个新的 turn。
+
+ 语义:
+ - 如果存在 ``current_turn``,先把它归档进有上限的 ``turn_history``。
+ - 为新 turn 重置 ``subagent_spans`` / ``agent_spans`` / ``step_spans``。
+ - 对相同 ``turn_id`` 保持幂等:重复调用直接返回已有 ``current_turn``,
+ 不重新生成 trace_id。
+
+ 返回最终生成的 ``current_turn`` 字典。
+ """
+ ts = float(started_at if started_at is not None else time.time())
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+
+ current = payload.get("current_turn")
+ # 幂等:如果同一个 turn_id 还在处理中,就原样返回。
+ if isinstance(current, dict) and str(current.get("turn_id") or "") == str(turn_id):
+ return dict(current)
+
+ # 归档上一个 turn。
+ if isinstance(current, dict) and current.get("turn_id"):
+ history = payload.setdefault("turn_history", [])
+ if not isinstance(history, list):
+ history = []
+ payload["turn_history"] = history
+ archived = {
+ "turn_id": current.get("turn_id"),
+ "started_at": current.get("started_at"),
+ "ended_at": ts,
+ "carrier_traceparent": (current.get("carrier") or {}).get("traceparent"),
+ }
+ history.append(archived)
+ if len(history) > max_history:
+ del history[: len(history) - max_history]
+
+ new_turn = {
+ "turn_id": str(turn_id),
+ "started_at": ts,
+ "carrier": dict(carrier or {}),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ payload["current_turn"] = new_turn
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_turn)
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span(
+ state_path: Path,
+ sid: str,
+ role: str,
+ carrier: dict[str, str],
+) -> dict[str, str]:
+ """在当前 turn 下登记 subagent 的 ``invoke_agent`` 子 span carrier。
+
+ 对 `(turn, role)` 维度保持幂等:如果活跃 turn 下已经记录了该角色的 carrier,
+ 就直接返回已有值,不再重复创建。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ # 没有活跃 turn,无法登记 subagent span。
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ subs[role] = {"carrier": dict(carrier or {}), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span_atomic(
+ state_path: Path,
+ sid: str,
+ role: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建 subagent 的 ``invoke_agent`` carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_subagent_carrier`` 先产生了不可逆的 zhiyanllm ``invoke_agent`` span,
+ 随后另一个 hook 进程已经写入同一角色,导致本次创建变成孤儿。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ subs[role] = {"carrier": dict(new_carrier), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_current_turn(state_path: Path, sid: str) -> dict[str, Any] | None:
+ """返回当前活跃的 turn 字典;如果没有打开 turn,就返回 None。"""
+ payload = load_agentlens_session(state_path, sid)
+ current = payload.get("current_turn")
+ return current if isinstance(current, dict) else None
+
+
+def get_subagent_span_carrier(state_path: Path, sid: str, role: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 subagent span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ subs = turn.get("subagent_spans")
+ if not isinstance(subs, dict):
+ return None
+ rec = subs.get(role)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def _empty_agent_aggregate() -> dict[str, Any]:
+ """创建一份空的 agent 聚合指标骨架。"""
+ return {
+ "tokens": {
+ "input": 0,
+ "output": 0,
+ "cache_read": 0,
+ "cache_creation": 0,
+ "total": 0,
+ },
+ "event_count": 0,
+ "cost_usd": 0.0,
+ "tool_duration_ms": 0,
+ "llm_call_count": 0,
+ "tool_call_count": 0,
+ "step_count": 0,
+ }
+
+
+def _normalize_agent(agent: str | None) -> str:
+ """把 agent 名归一化,空值统一落到 ``main``。"""
+ return str(agent or "main").strip() or "main"
+
+
+def _ensure_turn_agent_spans(current: dict[str, Any]) -> dict[str, Any]:
+ """确保当前 turn 下存在 `agent_spans` 容器。"""
+ agent_spans = current.setdefault("agent_spans", {})
+ if not isinstance(agent_spans, dict):
+ agent_spans = {}
+ current["agent_spans"] = agent_spans
+ return agent_spans
+
+
+def _ensure_agent_span_rec(current: dict[str, Any], agent: str) -> dict[str, Any]:
+ """确保指定 agent 在当前 turn 下有一条完整聚合记录。"""
+ agent_spans = _ensure_turn_agent_spans(current)
+ rec = agent_spans.get(agent)
+ if not isinstance(rec, dict):
+ rec = {}
+ agent_spans[agent] = rec
+ carrier = rec.get("carrier")
+ if not isinstance(carrier, dict):
+ rec["carrier"] = {}
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ rec["aggregate"] = _empty_agent_aggregate()
+ return rec
+
+
+def get_agent_span_carrier(state_path: Path, sid: str, agent: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 agent 分组 span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(agent))
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def upsert_agent_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """原子地获取或创建 agent 分组 span carrier。"""
+ now = time.time()
+ normalized_agent = _normalize_agent(agent)
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ existing = rec.get("carrier")
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ rec["carrier"] = dict(new_carrier)
+ rec.setdefault("opened_at", now)
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def bump_agent_aggregate(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ usage_event: dict[str, Any] | None = None,
+ tool_event: dict[str, Any] | None = None,
+ step_created: bool = False,
+) -> dict[str, Any]:
+ """增加活跃 turn 下按 agent 聚合的统计指标。"""
+ normalized_agent = _normalize_agent(agent)
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ def _float(value: Any) -> float:
+ try:
+ return float(value or 0)
+ except Exception:
+ return 0.0
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ aggregate = _empty_agent_aggregate()
+ rec["aggregate"] = aggregate
+ tokens = aggregate.setdefault("tokens", {})
+ if not isinstance(tokens, dict):
+ tokens = {}
+ aggregate["tokens"] = tokens
+
+ if step_created:
+ aggregate["step_count"] = _int(aggregate.get("step_count")) + 1
+
+ if isinstance(tool_event, dict):
+ aggregate["tool_call_count"] = _int(aggregate.get("tool_call_count")) + 1
+ ms = tool_event.get("ms")
+ if ms is not None:
+ aggregate["tool_duration_ms"] = _int(aggregate.get("tool_duration_ms")) + _int(ms)
+
+ if isinstance(usage_event, dict):
+ raw_tokens = usage_event.get("tokens")
+ if isinstance(raw_tokens, dict):
+ # 聚合 agent 摘要里需要暴露的字段。
+ for key in ("input", "output", "cache_read", "cache_creation"):
+ tokens[key] = _int(tokens.get(key)) + _int(raw_tokens.get(key))
+ # total = input + output,其中 input 已经包含 cache_read。
+ tokens["total"] = _int(tokens.get("input")) + _int(tokens.get("output"))
+ aggregate["llm_call_count"] = _int(aggregate.get("llm_call_count")) + 1
+ aggregate["event_count"] = _int(aggregate.get("event_count")) + 1
+ aggregate["cost_usd"] = round(_float(aggregate.get("cost_usd")) + _float(usage_event.get("cost_usd")), 10)
+
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+ return update_state_locked(state_path, _update)
+
+
+def get_subagent_aggregate(state_path: Path, sid: str, role: str) -> dict[str, Any] | None:
+ """返回活跃 turn 下当前 agent 的聚合摘要。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(role))
+ if not isinstance(rec, dict):
+ return None
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ return None
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+
+def _step_span_key(agent: str, message_id: str) -> str:
+ """为 step span 生成按 agent 与 message_id 唯一定位的 key。"""
+ return f"{agent}|{message_id}"
+
+
+def upsert_step_span(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ carrier: dict[str, str],
+ *,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在当前 turn 下登记一个 step span carrier,并对 `(turn, agent, message_id)` 保持幂等。"""
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ steps[key] = {
+ "carrier": dict(carrier or {}),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_step_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ *,
+ carrier_factory: Any,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建一个 step span carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_step_carrier`` 已经先产生了不可逆的 zhiyanllm span,
+ 但随后另一个 hook 进程已经写入同一 step,导致本次创建失去归属。
+ """
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ steps[key] = {
+ "carrier": dict(new_carrier),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_step_span_carrier(state_path: Path, sid: str, agent: str, message_id: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 step span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ steps = turn.get("step_spans")
+ if not isinstance(steps, dict):
+ return None
+ key = _step_span_key(str(agent or "main").strip() or "main", str(message_id or "").strip())
+ rec = steps.get(key)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def get_latest_session_id(state: dict[str, Any]) -> str | None:
+ """返回 state 中最近启动的 session id。"""
+ latest_sid: str | None = None
+ latest_started_at = -1.0
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ started_at = float(sess.get("started_at", 0) or 0)
+ if started_at >= latest_started_at:
+ latest_started_at = started_at
+ latest_sid = sid
+ return latest_sid
+
+
+def get_pending_tool_emits(state_path: Path, sid: str) -> list[dict[str, Any]]:
+ """返回等待与 transcript/message_id 关联的缓冲 tool 事件。"""
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return []
+ pending = sess.get("_pending_tool_emits")
+ if not isinstance(pending, list):
+ return []
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+
+def append_pending_tool_emit(state_path: Path, sid: str, tool_event: dict[str, Any]) -> list[dict[str, Any]]:
+ """缓存一条 tool 事件,延后再做 message_id 关联。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ pending = sess.setdefault("_pending_tool_emits", [])
+ if not isinstance(pending, list):
+ pending = []
+ sess["_pending_tool_emits"] = pending
+ pending.append(dict(tool_event))
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+ return update_state_locked(state_path, _update)
+
+
+def replace_pending_tool_emits(state_path: Path, sid: str, tool_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """覆盖某个 session 的缓冲 tool 事件队列。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ normalized = [dict(item) for item in tool_events if isinstance(item, dict)]
+ sess["_pending_tool_emits"] = normalized
+ return [dict(item) for item in normalized]
+
+ return update_state_locked(state_path, _update)
+
+def bump_skill(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ submodule: str | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 skill 使用计数,并按需记录子模块与 agent 维度。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["skills"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "version": None,
+ "submodule_hits": {},
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta:
+ if meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if meta.get("version") and not rec.get("version"):
+ rec["version"] = meta["version"]
+ # 子模块命中统计
+ if submodule:
+ sub_dict = rec.setdefault("submodule_hits", {})
+ if not isinstance(sub_dict, dict):
+ sub_dict = {}
+ rec["submodule_hits"] = sub_dict
+ sh = sub_dict.setdefault(submodule, {
+ "count": 0, "first_ts": now, "last_ts": now, "tools": [],
+ })
+ sh["count"] += 1
+ sh["last_ts"] = now
+ if tool and tool not in sh["tools"]:
+ sh["tools"].append(tool)
+ # 按 agent 维度统计
+ if agent:
+ ag_dict = rec.setdefault("by_agent", {})
+ if not isinstance(ag_dict, dict):
+ ag_dict = {}
+ rec["by_agent"] = ag_dict
+ ar = ag_dict.setdefault(agent, {
+ "count": 0, "first_ts": now, "last_ts": now,
+ "tools": [], "submodules": [],
+ })
+ ar["count"] += 1
+ ar["last_ts"] = now
+ if tool and tool not in ar["tools"]:
+ ar["tools"].append(tool)
+ if submodule and submodule not in ar["submodules"]:
+ ar["submodules"].append(submodule)
+
+
+def bump_rule(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 rule 使用计数。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["rules"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta and meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if agent:
+ ag = rec.setdefault("by_agent", {})
+ if not isinstance(ag, dict):
+ ag = {}
+ rec["by_agent"] = ag
+ ar = ag.setdefault(agent, {"count": 0, "last_ts": now})
+ ar["count"] += 1
+ ar["last_ts"] = now
+
+
+def prune_sessions(state: dict, max_sessions: int = 5) -> None:
+ """在 state 中只保留最近的 N 个 session。"""
+ # 先过滤掉非 session 键(以下划线开头)
+ session_keys = [k for k in state if not k.startswith("_")]
+ if len(session_keys) > max_sessions:
+ to_remove = sorted(
+ session_keys,
+ key=lambda s: state[s].get("started_at", 0) if isinstance(state[s], dict) else 0,
+ )[:len(session_keys) - max_sessions]
+ for k in to_remove:
+ del state[k]
+
+
+def _transcript_scope_key(transcript_path: str | None = None) -> str:
+ """把 transcript 路径归一化成内部 scope key。"""
+ path = str(transcript_path or "").strip()
+ return path or "__session__"
+
+
+def _ensure_transcript_scopes(sess: dict) -> dict[str, dict[str, Any]]:
+ """确保 session 下存在 transcript scope 容器,并兼容旧字段迁移。"""
+ scopes = sess.setdefault("_transcripts", {})
+ if not isinstance(scopes, dict):
+ scopes = {}
+ sess["_transcripts"] = scopes
+
+ legacy_scope = scopes.get("__session__")
+ if not isinstance(legacy_scope, dict):
+ legacy_scope = {}
+ scopes["__session__"] = legacy_scope
+
+ if "offset" not in legacy_scope and "_transcript_offset" in sess:
+ legacy_scope["offset"] = int(sess.get("_transcript_offset", 0) or 0)
+
+ legacy_usage = sess.get("_last_cumulative_usage")
+ if "last_cumulative_usage" not in legacy_scope and isinstance(legacy_usage, dict) and legacy_usage:
+ legacy_scope["last_cumulative_usage"] = legacy_usage
+
+ legacy_dedup = sess.get("_last_usage_event")
+ if "last_usage_event" not in legacy_scope and isinstance(legacy_dedup, dict) and legacy_dedup:
+ legacy_scope["last_usage_event"] = legacy_dedup
+
+ return scopes
+
+
+def _get_transcript_scope(
+ sess: dict,
+ transcript_path: str | None = None,
+ *,
+ create: bool = False,
+) -> dict[str, Any] | None:
+ """获取指定 transcript 的 scope;必要时按需创建。"""
+ scopes = _ensure_transcript_scopes(sess)
+ key = _transcript_scope_key(transcript_path)
+ scope = scopes.get(key)
+ if isinstance(scope, dict):
+ return scope
+ if create:
+ scope = {}
+ scopes[key] = scope
+ return scope
+ return None
+
+
+def get_transcript_offset(state: dict, sid: str, transcript_path: str | None = None) -> int:
+ """获取某个 session/transcript 最近一次上报的 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ return int(scope.get("offset", 0) or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ return int(sess.get("_transcript_offset", 0) or 0)
+ return 0
+
+
+def set_transcript_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """在成功上报后持久化 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["offset"] = int(offset or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = int(offset or 0)
+
+
+def get_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, int]:
+ """获取某个 transcript 最近一次上报的累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ v = sess.get("_last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+ return {}
+
+
+def get_last_llm_offset(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> int:
+ """获取最近一次处理到的 LLM source_offset,用于增量构建 I/O。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_llm_offset")
+ if isinstance(v, (int, float)):
+ return int(v)
+ return 0
+
+
+def set_last_llm_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近处理到的 LLM source_offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_llm_offset"] = int(offset or 0)
+
+
+def set_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ usage: dict[str, int],
+ transcript_path: str | None = None,
+) -> None:
+ """在处理完一个 turn 后持久化累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_cumulative_usage"] = usage
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = usage
+
+
+def get_last_usage_event(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, Any] | None:
+ """获取某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return None
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ event = scope.get("last_usage_event")
+ if isinstance(event, dict):
+ return event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ event = sess.get("_last_usage_event")
+ if isinstance(event, dict):
+ return event
+ return None
+
+
+def set_last_usage_event(
+ state: dict,
+ sid: str,
+ usage_event: dict[str, Any],
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_usage_event"] = usage_event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_usage_event"] = usage_event
+
+
+def claim_transcript_event(
+ state_path: Path,
+ sid: str,
+ event_key: str,
+ transcript_path: str | None = None,
+ *,
+ max_seen_keys: int = 512,
+) -> bool:
+ """跨进程原子地声明一个 transcript 作用域内的事件键。"""
+ seen_path = get_transcript_seen_path(state_path)
+ scope_key = f"{sid}|{_transcript_scope_key(transcript_path)}"
+
+ with state_lock(state_path):
+ if seen_path.exists():
+ try:
+ ledger = json.loads(seen_path.read_text("utf-8"))
+ except Exception:
+ ledger = {}
+ else:
+ ledger = {}
+ if not isinstance(ledger, dict):
+ ledger = {}
+
+ seen = ledger.setdefault(scope_key, {})
+ if not isinstance(seen, dict):
+ seen = {}
+ ledger[scope_key] = seen
+ if event_key in seen:
+ return False
+ seen[event_key] = time.time()
+ if len(seen) > max_seen_keys:
+ stale_keys = sorted(seen, key=lambda k: float(seen.get(k, 0) or 0))[:-max_seen_keys]
+ for key in stale_keys:
+ seen.pop(key, None)
+ seen_path.write_text(json.dumps(ledger, ensure_ascii=False), encoding="utf-8")
+ return True
+
+
+def commit_transcript_progress(
+ state_path: Path,
+ sid: str,
+ transcript_path: str | None = None,
+ *,
+ offset: int | None = None,
+ last_cumulative_usage: dict[str, int] | None = None,
+) -> None:
+ """在处理完一个窗口后,原子地持久化 transcript 解析进度。"""
+
+ def _update(state: dict[str, Any]) -> None:
+ sess = ensure_session(state, sid)
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if not isinstance(scope, dict):
+ return
+ if offset is not None:
+ current_offset = int(scope.get("offset", 0) or 0)
+ next_offset = int(offset or 0)
+ if next_offset > current_offset:
+ scope["offset"] = next_offset
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = next_offset
+ if isinstance(last_cumulative_usage, dict) and last_cumulative_usage:
+ scope["last_cumulative_usage"] = last_cumulative_usage
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = last_cumulative_usage
+
+ update_state_locked(state_path, _update)
diff --git a/.claude/skills/agent-observability/scripts/dashboard/index.html b/.claude/skills/agent-observability/scripts/dashboard/index.html
new file mode 100644
index 00000000..8c391f5c
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/dashboard/index.html
@@ -0,0 +1,1086 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent Observability</title>
+<style>
+:root{
+ --surface-page:#f9f9f7; --surface-card:#fcfcfb; --surface-sunken:#f2f1ec;
+ --text-primary:#0b0b0b; --text-secondary:#52514e; --text-muted:#898781;
+ --grid:#e1e0d9; --axis:#c3c2b7; --border:rgba(11,11,11,0.10);
+ --series-blue:#2a78d6; --series-orange:#eb6834; --series-aqua:#1baf7a; --series-yellow:#eda100;
+ --series-blue-wash:rgba(42,120,214,0.10); --series-orange-wash:rgba(235,104,52,0.10);
+ --seq-100:#cde2fb; --seq-200:#9ec5f4; --seq-350:#5598e7; --seq-450:#2a78d6; --seq-600:#184f95;
+ --status-good:#0ca30c; --status-warning:#b8790a; --status-critical:#d03b3b;
+ --status-good-bg:rgba(12,163,12,0.10); --status-warning-bg:rgba(184,121,10,0.12); --status-critical-bg:rgba(208,59,59,0.10);
+ --accent-ring:rgba(42,120,214,0.35);
+}
+@media (prefers-color-scheme: dark){
+ :root:not([data-theme="light"]){
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+ }
+}
+:root[data-theme="dark"]{
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+}
+*{box-sizing:border-box;}
+body{background:var(--surface-page); color:var(--text-primary); font-family:"IBM Plex Sans","Segoe UI",system-ui,sans-serif; margin:0;}
+.mono{font-family:"IBM Plex Mono","SFMono-Regular",ui-monospace,monospace;}
+.tab-nums{font-variant-numeric:tabular-nums;}
+h1,h2,h3{text-wrap:balance; margin:0;}
+.app{max-width:1180px; margin:0 auto; padding:28px 24px 64px;}
+
+/* header */
+.app-header{display:flex; flex-wrap:wrap; align-items:flex-end; justify-content:space-between; gap:16px; margin-bottom:6px;}
+.app-title{font-size:22px; font-weight:600; letter-spacing:-0.01em;}
+.app-sub{color:var(--text-secondary); font-size:13.5px; margin-top:4px; max-width:60ch;}
+.sample-badge{display:inline-flex; align-items:center; gap:6px; font-family:"IBM Plex Mono",monospace; font-size:11px; letter-spacing:.04em; text-transform:uppercase; color:var(--status-warning); background:var(--status-warning-bg); border:1px solid var(--border); border-radius:5px; padding:4px 8px; white-space:nowrap;}
+
+/* filter row */
+.filter-row{display:flex; align-items:center; gap:8px; margin:18px 0 22px; padding-bottom:14px; border-bottom:1px solid var(--grid);}
+.filter-label{font-size:12px; color:var(--text-muted); text-transform:uppercase; letter-spacing:.05em; margin-right:4px;}
+.range-btn{font-family:inherit; font-size:13px; color:var(--text-secondary); background:transparent; border:1px solid transparent; border-radius:6px; padding:6px 11px; cursor:pointer;}
+.range-btn:hover{background:var(--surface-sunken);}
+.range-btn[aria-pressed="true"]{background:var(--surface-card); border-color:var(--border); color:var(--text-primary); font-weight:600;}
+.range-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:1px;}
+
+/* KPI strip */
+.kpis{display:grid; grid-template-columns:repeat(5,1fr); gap:1px; background:var(--border); border:1px solid var(--border); border-radius:10px; overflow:hidden; margin-bottom:24px;}
+.kpi{background:var(--surface-card); padding:16px 18px;}
+.kpi-label{font-size:12px; color:var(--text-muted);}
+.kpi-value{font-size:24px; font-weight:600; margin-top:6px; letter-spacing:-0.01em;}
+.kpi-delta{font-size:12px; margin-top:4px;}
+.kpi-delta.up{color:var(--status-critical);}
+.kpi-delta.down{color:var(--status-good);}
+.kpi-delta.flat{color:var(--text-muted);}
+
+/* tabs */
+.tabs{display:flex; gap:4px; border-bottom:1px solid var(--grid); margin-bottom:22px;}
+.tab-btn{font-family:inherit; font-size:13.5px; color:var(--text-secondary); background:transparent; border:none; border-bottom:2px solid transparent; padding:10px 4px; margin-right:22px; cursor:pointer;}
+.tab-btn:hover{color:var(--text-primary);}
+.tab-btn[aria-selected="true"]{color:var(--text-primary); border-bottom-color:var(--series-blue); font-weight:600;}
+.tab-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:2px;}
+.tab-panel[hidden]{display:none;}
+
+/* cards */
+.card{background:var(--surface-card); border:1px solid var(--border); border-radius:10px; padding:18px 20px;}
+.card + .card{margin-top:16px;}
+.card-head{display:flex; align-items:baseline; justify-content:space-between; margin-bottom:14px; gap:12px; flex-wrap:wrap;}
+.card-title{font-size:14px; font-weight:600;}
+.card-note{font-size:12px; color:var(--text-muted);}
+.grid-2{display:grid; grid-template-columns:1.3fr 1fr; gap:16px;}
+/* .card + .card 的 margin-top 是给"同一列里纵向堆叠的卡片"留间距用的;grid 的两个
+ 格子在 DOM 里也是相邻兄弟,会被同一条规则误伤,导致右边格子的卡片顶部被顶低
+ 16px、和左边对不齐。grid 行内的卡片间距已经由 .grid-2 的 gap 负责,这里清零。 */
+.grid-2 > .card + .card{margin-top:0;}
+/* Token 构成只画两根竖条,不需要宽度;按模型的成本占比要给模型名留横向空间,
+ 反过来分配才对得上两张图各自的实际需要。 */
+.grid-2.grid-2--cost{grid-template-columns:1fr 1.3fr;}
+/* 按模型的成本占比条数不固定(1~5 行),卡片天然高矮不一;Token 构成固定只有一张
+ 图,让它的图表区跟着 grid 拉伸出来的实际卡片高度走,而不是停在自己内容的高度、
+ 底下空出一大截。 */
+.grid-2--cost .card--fill-h{display:flex; flex-direction:column;}
+.grid-2--cost .card--fill-h .chart-wrap{flex:1 1 auto; min-height:160px;}
+.grid-2--cost .card--fill-h .chart-wrap svg.chart{height:100%;}
+@media(max-width:860px){.grid-2{grid-template-columns:1fr;} .grid-2.grid-2--cost{grid-template-columns:1fr;} .kpis{grid-template-columns:repeat(2,1fr);}}
+
+/* legend */
+.legend{display:flex; gap:14px; flex-wrap:wrap; font-size:12px; color:var(--text-secondary);}
+.legend-item{display:flex; align-items:center; gap:6px;}
+.legend-swatch{width:10px; height:10px; border-radius:2px; flex:none;}
+.legend-line{width:14px; height:2px; border-radius:1px; flex:none;}
+
+/* chart chrome */
+.chart-wrap{position:relative;}
+svg.chart{width:100%; height:auto; display:block; overflow:visible;}
+.axis-text{font-size:10.5px; fill:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.gridline{stroke:var(--grid); stroke-width:1;}
+.crosshair{stroke:var(--axis); stroke-width:1; pointer-events:none;}
+.tooltip{position:absolute; pointer-events:none; background:var(--surface-card); border:1px solid var(--border); border-radius:8px; padding:9px 11px; font-size:12px; box-shadow:0 6px 20px rgba(0,0,0,.16); opacity:0; transition:opacity .08s ease; z-index:5; min-width:132px;}
+.tooltip.show{opacity:1;}
+.tooltip-date{color:var(--text-muted); font-size:11px; margin-bottom:5px;}
+.tooltip-row{display:flex; align-items:center; gap:6px; justify-content:space-between; margin-top:3px;}
+.tooltip-key{display:flex; align-items:center; gap:6px; color:var(--text-secondary);}
+.tooltip-swatch{width:10px; height:2px; border-radius:1px;}
+.tooltip-val{font-family:"IBM Plex Mono",monospace; font-weight:600; color:var(--text-primary);}
+.hit-target{fill:transparent; cursor:crosshair;}
+.mark-lift{transition:opacity .08s ease;}
+
+/* stat / hero */
+.hero-row{display:flex; align-items:flex-end; gap:10px;}
+.hero-figure{font-size:30px; font-weight:600; letter-spacing:-0.01em;}
+.hero-unit{font-size:13px; color:var(--text-muted); padding-bottom:5px;}
+
+/* reminders */
+.reminders{display:grid; grid-template-columns:repeat(3,1fr); gap:12px;}
+@media(max-width:860px){.reminders{grid-template-columns:1fr;}}
+.reminder{border-radius:9px; padding:13px 14px; border:1px solid var(--border); display:flex; gap:10px;}
+.reminder.crit{background:var(--status-critical-bg);}
+.reminder.warn{background:var(--status-warning-bg);}
+.reminder.good{background:var(--status-good-bg);}
+.reminder-icon{flex:none; width:20px; height:20px; border-radius:5px; display:flex; align-items:center; justify-content:center; font-size:12px; font-weight:700; color:#fff; margin-top:1px;}
+.reminder.crit .reminder-icon{background:var(--status-critical);}
+.reminder.warn .reminder-icon{background:var(--status-warning); color:#3a2600;}
+.reminder.good .reminder-icon{background:var(--status-good);}
+.reminder-label{font-size:11px; text-transform:uppercase; letter-spacing:.04em; font-weight:700;}
+.reminder.crit .reminder-label{color:var(--status-critical);}
+.reminder.warn .reminder-label{color:var(--status-warning);}
+.reminder.good .reminder-label{color:var(--status-good);}
+.reminder-text{font-size:12.5px; color:var(--text-secondary); margin-top:3px; line-height:1.5;}
+.reminder-text b{color:var(--text-primary); font-weight:600;}
+
+/* tables */
+.table-scroll{overflow-x:auto;}
+table{width:100%; border-collapse:collapse; font-size:12.8px; min-width:640px;}
+th{text-align:left; font-size:11px; text-transform:uppercase; letter-spacing:.04em; color:var(--text-muted); font-weight:600; padding:8px 10px; border-bottom:1px solid var(--grid); white-space:nowrap;}
+td{padding:9px 10px; border-bottom:1px solid var(--grid); color:var(--text-secondary); white-space:nowrap;}
+tr.data-row{cursor:pointer;}
+tr.data-row:hover td{background:var(--surface-sunken);}
+td.strong{color:var(--text-primary); font-weight:600;}
+.chip{display:inline-flex; align-items:center; gap:5px; font-size:11px; font-weight:600; padding:3px 8px; border-radius:99px;}
+.chip.good{color:var(--status-good); background:var(--status-good-bg);}
+.chip.crit{color:var(--status-critical); background:var(--status-critical-bg);}
+.chip-dot{width:6px; height:6px; border-radius:50%; background:currentColor;}
+.expand-row td{background:var(--surface-sunken); padding:0;}
+.timeline{padding:14px 16px 16px;}
+.timeline-turn{margin-bottom:14px;}
+.timeline-turn:last-child{margin-bottom:0;}
+.timeline-turn-head{display:flex; align-items:baseline; justify-content:space-between; gap:10px; margin-bottom:6px;}
+.timeline-turn-label{font-size:11px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.timeline-turn-count{font-size:11px; color:var(--text-muted); white-space:nowrap;}
+.timeline-scroll{overflow-x:auto; padding-bottom:3px;}
+.timeline-track{display:flex; gap:2px; align-items:stretch; height:26px; width:max-content; min-width:100%;}
+.timeline-seg{flex:0 0 auto; border-radius:4px; display:flex; align-items:center; justify-content:center; font-size:10.5px; color:#fff; font-family:"IBM Plex Mono",monospace; white-space:nowrap; padding:0 6px; overflow:hidden; text-overflow:ellipsis; box-sizing:border-box;}
+.timeline-seg.ok{background:var(--series-blue);}
+.timeline-seg.err{background:var(--status-critical);}
+.timeline-seg.usage{background:var(--series-aqua);}
+.timeline-seg.merged{background:var(--seq-350);}
+/* 派发给非 main 的 agent(比如 solo-developer、architect)执行的调用,顶部加一条
+ 高亮边框——同一个 turn 里经常混着 main 自己做的调用和转派出去的调用,光看
+ 颜色(ok/err/merged)分不出"这段到底是谁做的"。*/
+.timeline-seg.subagent{border-top:3px solid var(--series-yellow);}
+
+/* skill list */
+.bar-list{display:flex; flex-direction:column; gap:10px;}
+.bar-row{display:grid; grid-template-columns:150px 1fr 64px; gap:10px; align-items:center; font-size:12.5px;}
+.bar-row .name{color:var(--text-primary); overflow:hidden; text-overflow:ellipsis; white-space:nowrap;}
+.bar-track{height:16px; background:var(--surface-sunken); border-radius:4px; position:relative; overflow:hidden;}
+.bar-fill{height:100%; border-radius:4px;}
+.bar-row .val{text-align:right; color:var(--text-secondary);}
+.unused-list{display:flex; flex-direction:column; gap:8px; margin-top:4px;}
+.unused-item{display:flex; align-items:center; justify-content:space-between; gap:10px; font-size:12.5px; padding:8px 10px; background:var(--surface-sunken); border-radius:7px;}
+.unused-name{color:var(--text-primary); font-family:"IBM Plex Mono",monospace; font-size:12px;}
+.reason-chip{font-size:10.5px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace; background:var(--surface-card); border:1px solid var(--border); padding:2px 7px; border-radius:5px;}
+
+/* devflow health */
+.health-row{display:flex; gap:22px; flex-wrap:wrap; align-items:center;}
+.health-stat{display:flex; flex-direction:column; gap:2px;}
+.health-stat .v{font-size:20px; font-weight:600;}
+.health-stat .l{font-size:11px; color:var(--text-muted);}
+.health-bar{flex:1 1 260px; min-width:220px;}
+.health-bar-track{height:10px; border-radius:5px; background:var(--surface-sunken); overflow:hidden; display:flex;}
+.health-bar-seg{height:100%;}
+.health-legend{display:flex; gap:14px; margin-top:8px; font-size:11.5px; color:var(--text-secondary);}
+
+/* devflow runs */
+.run-card{border:1px solid var(--border); border-radius:9px; padding:14px 16px; background:var(--surface-sunken);}
+.run-card + .run-card{margin-top:12px;}
+.run-head{display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:8px; margin-bottom:12px;}
+.run-title{font-family:"IBM Plex Mono",monospace; font-size:12.5px; color:var(--text-primary); font-weight:600;}
+.run-meta{display:flex; align-items:center; gap:8px; font-size:11.5px; color:var(--text-muted);}
+.size-chip{font-size:10.5px; text-transform:uppercase; letter-spacing:.03em; font-weight:700; padding:2px 7px; border-radius:5px; background:var(--surface-card); border:1px solid var(--border); color:var(--text-secondary);}
+.run-status-chip{font-size:11px; font-weight:600; padding:3px 9px; border-radius:99px; display:inline-flex; align-items:center; gap:5px;}
+.stepper{display:flex; align-items:center; overflow-x:auto; padding-bottom:4px;}
+.step{flex:0 0 auto; display:flex; flex-direction:column; align-items:center; width:68px; position:relative;}
+.step-dot{width:26px; height:26px; border-radius:50%; display:flex; align-items:center; justify-content:center; font-family:"IBM Plex Mono",monospace; font-size:9.5px; font-weight:700; color:#fff; border:2px solid var(--surface-sunken); position:relative; z-index:1;}
+.step-dot.pending{background:var(--surface-card); color:var(--text-muted); border-color:var(--axis);}
+.step-dot.in_progress{background:var(--series-blue);}
+.step-dot.completed{background:var(--status-good);}
+.step-dot.failed{background:var(--status-critical);}
+.step-dot.skipped{background:var(--surface-card); color:var(--text-muted); border-style:dashed;}
+.step-label{font-size:10px; color:var(--text-secondary); margin-top:5px; text-align:center; line-height:1.3;}
+.step-connector{position:absolute; top:13px; left:-34px; width:68px; height:2px; background:var(--axis); z-index:0;}
+.step:first-child .step-connector{display:none;}
+.step-retry{position:absolute; top:-8px; right:6px; background:var(--status-critical); color:#fff; font-size:9px; font-weight:700; border-radius:99px; padding:1px 5px; z-index:2;}
+
+/* heatmap */
+.heatmap-wrap{overflow-x:auto;}
+.heatmap-legend{display:flex; align-items:center; gap:5px; font-size:11px; color:var(--text-muted); margin-top:10px;}
+.heatmap-legend .sq{width:10px; height:10px; border-radius:2px;}
+
+footer.note{margin-top:30px; font-size:11.5px; color:var(--text-muted); line-height:1.7; border-top:1px solid var(--grid); padding-top:14px;}
+footer.note code{font-family:"IBM Plex Mono",monospace; background:var(--surface-sunken); padding:1px 5px; border-radius:4px;}
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap">
+</head>
+<body>
+
+<div class="app">
+ <div class="app-header">
+ <div>
+ <div class="app-title">Agent Observability</div>
+ <div class="app-sub">读取本地 <span class="mono">dashboard-data.json</span>(由 <span class="mono">build_dashboard_data.py</span> 从 metrics.ndjson / workflow-state.json 聚合而成)&middot; LoopForge 项目</div>
+ </div>
+ <div class="sample-badge" id="dataStatusBadge">加载中…</div>
+ </div>
+
+ <div class="filter-row">
+ <span class="filter-label">时间范围</span>
+ <button class="range-btn" data-range="7">近 7 天</button>
+ <button class="range-btn" data-range="30">近 30 天</button>
+ <button class="range-btn" data-range="90" aria-pressed="true">近 90 天</button>
+ </div>
+
+ <div class="kpis" id="kpiStrip"></div>
+
+ <div class="tabs" role="tablist">
+ <button class="tab-btn" role="tab" aria-selected="true" data-tab="overview">总览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="sessions">会话浏览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="skills">Skill · Rule</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="agents">Agent 协作</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="devflow">Devflow 运行</button>
+ </div>
+
+ <section class="tab-panel" id="panel-overview">
+ <div class="card">
+ <div class="card-head"><span class="card-title">建议关注</span><span class="card-note">按当前范围内的阈值规则实时算出,不是固定文案</span></div>
+ <div class="reminders" id="reminders"></div>
+ </div>
+
+ <div class="card">
+ <div class="card-head">
+ <span class="card-title">每日成本</span>
+ <div class="legend"><div class="legend-item"><span class="legend-line" style="background:var(--series-orange)"></span>cost_usd(按 <span class="mono">config/pricing.json</span> 估算)</div></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="costChart" viewBox="0 0 1080 220"></svg><div class="tooltip" id="costTooltip"></div></div>
+ </div>
+
+ <div class="grid-2 grid-2--cost">
+ <div class="card card--fill-h">
+ <div class="card-head">
+ <span class="card-title">Token 构成</span>
+ <div class="legend" id="tokenLegend"></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="tokenChart" viewBox="0 0 560 270"></svg><div class="tooltip" id="tokenTooltip"></div></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">按模型的成本占比</span><span class="card-note">Top 4 + 其他</span></div>
+ <div class="chart-wrap"><svg class="chart" id="modelChart" viewBox="0 0 460 210"></svg><div class="tooltip" id="modelTooltip"></div></div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">数据表</span><span class="card-note">图表的完整数值备份</span></div>
+ <div class="table-scroll"><table id="dailyTable"><thead><tr><th>日期</th><th>会话数</th><th>成本 (USD)</th><th>input</th><th>output</th><th>cache_read</th><th>工具失败</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-sessions" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近会话</span><span class="card-note">点击一行展开该会话按 turn 的工具调用时间线</span></div>
+ <div class="table-scroll"><table id="sessionTable">
+ <thead><tr><th>Session</th><th>日期</th><th>Agent</th><th>Turns</th><th>工具调用</th><th>Tokens</th><th>成本</th><th>时长</th><th>状态</th></tr></thead>
+ <tbody></tbody>
+ </table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-skills" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 触发热力图</span><span class="card-note">按天统计 <span class="mono">scanner.py</span> 命中的 skill 次数</span></div>
+ <div class="heatmap-wrap"><svg class="chart" id="heatmap" viewBox="0 0 900 118"></svg><div class="tooltip" id="heatmapTooltip"></div></div>
+ <div class="heatmap-legend">少<span class="sq" style="background:var(--seq-100)"></span><span class="sq" style="background:var(--seq-200)"></span><span class="sq" style="background:var(--seq-350)"></span><span class="sq" style="background:var(--seq-450)"></span><span class="sq" style="background:var(--seq-600)"></span>多</div>
+ </div>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 使用排行</span><span class="card-note">按范围内触发次数</span></div>
+ <div class="bar-list" id="skillBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">从未命中的 Skill / Rule</span><span class="card-note">来自 <span class="mono">unmatched_rule_diagnostics_for_call</span> 的未命中原因</span></div>
+ <div class="unused-list" id="unusedList"></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-agents" hidden>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Main → 子 Agent 派发次数</span><span class="card-note">来自 <span class="mono">.state.json</span> 的 agent_history</span></div>
+ <div class="bar-list" id="dispatchBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">工具失败面板</span><span class="card-note">tool_details.raw_response.is_error</span></div>
+ <div class="table-scroll"><table id="failTable"><thead><tr><th>工具</th><th>错误码</th><th>次数</th><th>最近一次</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-devflow" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Auto-Dispatch 健康度</span><span class="card-note">来自 <span class="mono">hooks/logs/auto-dispatch.log</span> 的派发决策统计</span></div>
+ <div class="health-row">
+ <div class="health-stat"><span class="v tab-nums" id="hDispatch">–</span><span class="l">auto_dispatch(零 token 直达)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallback">–</span><span class="l">fallback_to_main(唤醒 main)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallbackRate">–</span><span class="l">fallback 率</span></div>
+ <div class="health-bar">
+ <div class="health-bar-track" id="hBar"></div>
+ <div class="health-legend">
+ <span><span class="legend-swatch" style="background:var(--status-good);display:inline-block"></span> auto_dispatch</span>
+ <span><span class="legend-swatch" style="background:var(--status-warning);display:inline-block"></span> fallback_to_main</span>
+ <span><span class="legend-swatch" style="background:var(--text-muted);display:inline-block"></span> passthrough(*_failed 等本就该回 main)</span>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近 Devflow 运行</span><span class="card-note">按 task_slug 分组,串起 main + 最多 7 个 team member 的跨 session 归因</span></div>
+ <div id="devflowRuns"></div>
+ </div>
+ </section>
+
+ <footer class="note">
+ 数据来源:<code>python3 ../build_dashboard_data.py --project-root &lt;devflow 项目根目录&gt;</code> 会读取该项目下
+ <code>.codebuddy/skills/agent-observability/logs/metrics.ndjson</code>、<code>.state.json</code>、
+ <code>artifacts/*/workflow-state.json</code>(Classic/Portable 两种 schema 自动识别)与
+ <code>.codebuddy/hooks/logs/auto-dispatch.log</code>,聚合成同目录下的 <code>dashboard-data.json</code>。
+ 这个页面只读那份快照,不直接碰任何日志/状态文件——重新生成快照后刷新页面即可看到最新数据。
+ 全部处理在本机完成,不发往任何外部服务。
+ </footer>
+</div>
+
+<script>
+(function(){
+ "use strict";
+
+ var css = getComputedStyle(document.documentElement);
+ function tok(name){ return css.getPropertyValue(name).trim(); }
+
+ /* ---------- state populated by loadData() from ./dashboard-data.json (real data, no mock) ---------- */
+ var daily = [], sessions = [], dispatch = [], failures = [];
+ var SKILLS = [], NEVER_USED = [], modelCosts = [], unpricedModels = [];
+ var devflowRuns = [], autoDispatchStats = {auto_dispatch:0, fallback_to_main:0, passthrough:0};
+ var currentRange = 90;
+
+ function sliced(){ return daily.slice(daily.length-currentRange); }
+ function fmtUSD(v){ return "$"+v.toLocaleString(undefined,{minimumFractionDigits:2,maximumFractionDigits:2}); }
+ function fmtCompact(v){
+ if(v>=1e6) return (v/1e6).toFixed(1)+"M";
+ if(v>=1e3) return (v/1e3).toFixed(1)+"K";
+ return String(v);
+ }
+ function fmtDur(sec){
+ var m = Math.floor(sec/60), s = sec%60;
+ if(m>=60){ var h=Math.floor(m/60); m=m%60; return h+"h "+m+"m"; }
+ return m+"m "+s+"s";
+ }
+ function fmtDate(iso){ var p = iso.split("-"); return p[1]+"/"+p[2]; }
+
+ /* ================= KPI strip ================= */
+ function renderKPIs(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalTokens = d.reduce(function(a,x){return a+x.input+x.output;},0);
+ var totalSessions = d.reduce(function(a,x){return a+x.sessionCount;},0);
+ var totalCalls = d.reduce(function(a,x){return a+x.toolCalls;},0);
+ var totalFail = d.reduce(function(a,x){return a+x.failures;},0);
+ var failRate = totalCalls ? (totalFail/totalCalls*100) : 0;
+ var avgDur = sessions.length ? sessions.reduce(function(a,x){return a+x.duration;},0)/sessions.length : 0;
+
+ var items = [
+ {label:"会话数", value:totalSessions.toLocaleString(), delta:null},
+ {label:"累计成本", value:fmtUSD(totalCost), delta:null},
+ {label:"总 Token", value:fmtCompact(totalTokens), delta:null},
+ {label:"平均会话时长", value:fmtDur(Math.round(avgDur)), delta:null},
+ {label:"工具失败率", value:failRate.toFixed(1)+"%", delta:failRate>3?"up":"down"}
+ ];
+ var el = document.getElementById("kpiStrip");
+ el.innerHTML = "";
+ items.forEach(function(it){
+ var deltaHtml = "";
+ if(it.delta){
+ var cls = it.delta==="up" ? "up" : "down";
+ var arrow = it.delta==="up" ? "&#8593;" : "&#8595;";
+ deltaHtml = '<div class="kpi-delta '+cls+'">'+arrow+' vs 前一周期</div>';
+ }
+ var card = document.createElement("div");
+ card.className = "kpi";
+ var vEl = document.createElement("div"); vEl.className="kpi-value tab-nums";
+ var lEl = document.createElement("div"); lEl.className="kpi-label";
+ lEl.textContent = it.label; vEl.textContent = it.value;
+ card.appendChild(lEl); card.appendChild(vEl);
+ if(deltaHtml){ var dWrap=document.createElement("div"); dWrap.innerHTML=deltaHtml; card.appendChild(dWrap.firstChild); }
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= Reminders ================= */
+ /* 模型名来自日志(模型名是外部输入),插入 innerHTML 前必须转义。 */
+ function esc(s){
+ return String(s==null?"":s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;");
+ }
+
+ function renderReminders(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalInput = d.reduce(function(a,x){return a+x.input;},0);
+ var totalCache = d.reduce(function(a,x){return a+x.cache;},0);
+ var cacheRate = totalInput ? (totalCache/totalInput*100) : 0;
+ var budget = 40;
+ var el = document.getElementById("reminders");
+ el.innerHTML = "";
+ var items = [];
+ items.push({
+ level: totalCost > budget ? "crit" : (totalCost > budget*0.75 ? "warn" : "good"),
+ label: "成本预算",
+ text: "近 "+currentRange+" 天累计花费 <b>"+fmtUSD(totalCost)+"</b>,预算阈值 "+fmtUSD(budget)+"("+(totalCost>budget?"已超出":(Math.round(totalCost/budget*100)+"% 已用"))+")。"
+ });
+ items.push({
+ level: cacheRate < 30 ? "warn" : "good",
+ label: "Prompt Cache 命中",
+ text: "cache_read 占 input 的 <b>"+cacheRate.toFixed(0)+"%</b>"+(cacheRate<30 ? ",偏低,可能是 system prompt 频繁变化导致缓存失效,白花了 input 成本。" : ",处于正常区间。")
+ });
+ var unusedCount = NEVER_USED.length;
+ items.push({
+ level: unusedCount>0 ? "warn" : "good",
+ label: "Skill 维护",
+ text: unusedCount>0 ? ("有 <b>"+unusedCount+"</b> 个 skill/rule 在范围内从未被命中,建议检查 description 或 globs。") : "所有已扫描的 skill/rule 近期均被命中过。"
+ });
+ /* 第 4 条:模型定价。unpricedModels 由 build_dashboard_data.py 聚合,
+ 只列"完全没命中价格表"的模型(模糊命中的不算,见 emitter.is_unpriced)。 */
+ var unpricedCount = (unpricedModels||[]).length;
+ var unpricedEvents = (unpricedModels||[]).reduce(function(a,x){return a+(x.usageEvents||0);},0);
+ var unpricedNames = (unpricedModels||[]).slice(0,3).map(function(x){return esc(x.name);}).join("、");
+ items.push({
+ level: unpricedCount>0 ? "warn" : "good",
+ label: "模型定价",
+ text: unpricedCount>0
+ ? ("有 <b>"+unpricedCount+"</b> 个模型未命中价格表(<b>"+unpricedEvents+"</b> 条 usage 事件缺少成本):"
+ +unpricedNames+(unpricedCount>3 ? " 等 "+unpricedCount+" 个" : "")
+ +"。可写入 <code>.codebuddy/agent-observability/pricing.overrides.json</code>,"
+ +"或用 <code>AOBS_PRICING_OVERRIDES_PATH</code> 指定覆盖文件补充单价;"
+ +"补充后只影响之后的新事件,不回溯已落盘的历史成本。")
+ : "所有出现的模型都已命中价格表,成本估算完整。"
+ });
+ items.forEach(function(it){
+ var card = document.createElement("div");
+ card.className = "reminder "+it.level;
+ var icon = it.level==="crit" ? "!" : (it.level==="warn" ? "!" : "✓");
+ card.innerHTML =
+ '<div class="reminder-icon">'+icon+'</div>'+
+ '<div><div class="reminder-label">'+(it.level==="crit"?"critical":it.level==="warn"?"warning":"good")+'</div>'+
+ '<div style="font-size:12.5px;font-weight:600;margin-top:2px;">'+it.label+'</div>'+
+ '<div class="reminder-text">'+it.text+'</div></div>';
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= tooltip helper ================= */
+ function positionTooltip(tipEl, wrapEl, x, y){
+ var wrapRect = wrapEl.getBoundingClientRect();
+ var left = x, top = y - 14;
+ var maxLeft = wrapRect.width - 150;
+ if(left > maxLeft) left = maxLeft;
+ if(left < 4) left = 4;
+ tipEl.style.left = left + "px";
+ tipEl.style.top = Math.max(0, top - tipEl.offsetHeight) + "px";
+ }
+
+ var SVGNS = "http://www.w3.org/2000/svg";
+ function el(tag, attrs){
+ var e = document.createElementNS(SVGNS, tag);
+ for(var k in attrs){ e.setAttribute(k, attrs[k]); }
+ return e;
+ }
+
+ /* SVG <text> 没有 CSS text-overflow:ellipsis 那一套,长文本(比如自定义模型名)
+ 会原样溢出、被同一行后面画的柱子盖住。textEl 必须已经挂到 DOM 上(在真实渲染的
+ svg 里)才能拿到准确的 getComputedTextLength()。 */
+ function truncateSvgText(textEl, fullText, maxWidth){
+ textEl.textContent = fullText;
+ if(maxWidth<=0 || textEl.getComputedTextLength()<=maxWidth) return;
+ var lo=0, hi=fullText.length;
+ while(lo<hi){
+ var mid=(lo+hi+1)>>1;
+ textEl.textContent = fullText.slice(0,mid)+"…";
+ if(textEl.getComputedTextLength()<=maxWidth) lo=mid; else hi=mid-1;
+ }
+ textEl.textContent = lo>0 ? fullText.slice(0,lo)+"…" : "…";
+ }
+
+ /* ================= Cost trend (line + area, crosshair tooltip) ================= */
+ function renderCostChart(){
+ var svg = document.getElementById("costChart");
+ svg.innerHTML = "";
+ var W=1080,H=220, padL=44, padR=12, padT=14, padB=26;
+ var d = sliced();
+ if(d.length===0){
+ var empty0 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty0.textContent = "暂无数据 · 等真实会话跑起来后重新生成 dashboard-data.json";
+ svg.appendChild(empty0);
+ return;
+ }
+ var maxCost = Math.max.apply(null, d.map(function(x){return x.cost;})) || 1;
+ var niceMax = Math.ceil(maxCost*1.15/5)*5 || 5;
+ var plotW = W-padL-padR, plotH = H-padT-padB;
+ function xAt(i){ return padL + (d.length<=1?0:(i/(d.length-1))*plotW); }
+ function yAt(v){ return padT + plotH - (v/niceMax)*plotH; }
+
+ // gridlines + y labels
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g;
+ var y = yAt(v);
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"});
+ t.textContent = "$"+v.toFixed(0); svg.appendChild(t);
+ }
+ // x labels (sparse)
+ var step = Math.max(1, Math.round(d.length/7));
+ d.forEach(function(pt,i){
+ if(i%step===0 || i===d.length-1){
+ var t = el("text",{class:"axis-text",x:xAt(i),y:H-6,"text-anchor":"middle"});
+ t.textContent = fmtDate(pt.iso); svg.appendChild(t);
+ }
+ });
+
+ // area path
+ var top = d.map(function(pt,i){ return xAt(i)+","+yAt(pt.cost); }).join(" L ");
+ var areaD = "M "+xAt(0)+","+yAt(0)+" L "+top+" L "+xAt(d.length-1)+","+yAt(0)+" Z";
+ svg.appendChild(el("path",{d:areaD, fill:tok("--series-orange"), opacity:0.10, stroke:"none"}));
+ var lineD = "M "+top;
+ svg.appendChild(el("path",{d:lineD, fill:"none", stroke:tok("--series-orange"), "stroke-width":2, "stroke-linejoin":"round","stroke-linecap":"round"}));
+
+ // emphasized endpoint
+ var lastI = d.length-1;
+ svg.appendChild(el("circle",{cx:xAt(lastI), cy:yAt(d[lastI].cost), r:4.5, fill:tok("--series-orange"), stroke:tok("--surface-card"), "stroke-width":2}));
+ var endLabel = el("text",{class:"axis-text",x:xAt(lastI)-4,y:yAt(d[lastI].cost)-10,"text-anchor":"end", fill:tok("--text-primary")});
+ endLabel.setAttribute("font-weight","600");
+ endLabel.textContent = "$"+d[lastI].cost.toFixed(2);
+ svg.appendChild(endLabel);
+
+ // crosshair + hover
+ var crosshair = el("line",{class:"crosshair",x1:0,x2:0,y1:padT,y2:H-padB, opacity:0});
+ svg.appendChild(crosshair);
+ var hitRect = el("rect",{class:"hit-target",x:padL,y:padT,width:plotW,height:plotH});
+ svg.appendChild(hitRect);
+ var wrap = svg.parentNode, tip = document.getElementById("costTooltip");
+ function onMove(evt){
+ var rect = svg.getBoundingClientRect();
+ var mx = (evt.clientX-rect.left) * (W/rect.width);
+ var idx = Math.round(((mx-padL)/plotW)*(d.length-1));
+ idx = Math.max(0, Math.min(d.length-1, idx));
+ var px = xAt(idx);
+ crosshair.setAttribute("x1",px); crosshair.setAttribute("x2",px); crosshair.setAttribute("opacity",1);
+ var pt = d[idx];
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+tok("--series-orange")+'"></span>成本</span><span class="tooltip-val">'+fmtUSD(pt.cost)+'</span></div><div class="tooltip-row"><span class="tooltip-key">会话数</span><span class="tooltip-val">'+pt.sessionCount+'</span></div>';
+ tip.classList.add("show");
+ var screenX = px/(W/rect.width), screenY = yAt(pt.cost)/(H/rect.height);
+ positionTooltip(tip, wrap, screenX, screenY);
+ }
+ hitRect.addEventListener("pointermove", onMove);
+ hitRect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); crosshair.setAttribute("opacity",0); });
+ }
+
+ /* ================= Token composition (stacked bars) ================= */
+ function renderTokenChart(){
+ var svg = document.getElementById("tokenChart"); svg.innerHTML="";
+ var legend = document.getElementById("tokenLegend");
+ var series = [
+ {key:"input", label:"input", color:tok("--series-blue")},
+ {key:"output", label:"output", color:tok("--series-aqua")},
+ {key:"cache", label:"cache_read", color:tok("--series-yellow")}
+ ];
+ legend.innerHTML = series.map(function(s){ return '<div class="legend-item"><span class="legend-swatch" style="background:'+s.color+'"></span>'+s.label+'</div>'; }).join("");
+
+ // 按模型的成本占比条数不固定(1~5 行),两张图挨着放的时候卡片高矮天然不一样。
+ // .card--fill-h 让这张图的 .chart-wrap 跟着 grid 拉伸出来的实际卡片高度走(CSS),
+ // 这里直接读它撑开后的真实像素尺寸当 viewBox,而不是猜一个写死的高宽比——
+ // renderModelChart() 必须先跑完把内容插进 DOM,这个测量才反映得出最终高度
+ // (见 renderAll() / 时间范围切换 / resize 三处调用顺序)。560x270 只是量不到时
+ // (比如面板还没显示)的兜底默认值。
+ var wrapRect = svg.parentNode.getBoundingClientRect();
+ var W = Math.round(wrapRect.width) || 560;
+ var H = Math.max(160, Math.round(wrapRect.height) || 270);
+ svg.setAttribute("viewBox","0 0 "+W+" "+H);
+ var padL=46,padR=10,padT=10,padB=24;
+ var d = sliced().slice(-30); // cap bars for legibility
+ if(d.length===0){
+ var empty1 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty1.textContent = "暂无数据";
+ svg.appendChild(empty1);
+ return;
+ }
+ var maxTotal = Math.max.apply(null, d.map(function(x){return x.input+x.output+x.cache;})) || 1;
+ var niceMax = Math.ceil(maxTotal*1.1/10000)*10000 || 10000;
+ var plotW=W-padL-padR, plotH=H-padT-padB;
+ var bw = Math.min(28, plotW/d.length*0.62);
+ var gap = plotW/d.length;
+
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g, y = padT+plotH-(v/niceMax)*plotH;
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"}); t.textContent=fmtCompact(v); svg.appendChild(t);
+ }
+ var wrap = svg.parentNode, tip = document.getElementById("tokenTooltip");
+ d.forEach(function(pt,i){
+ var x = padL + i*gap + (gap-bw)/2;
+ var vals = [pt.input, pt.output, pt.cache];
+ var yCursor = padT+plotH;
+ var bar = el("g",{});
+ vals.forEach(function(v,si){
+ var hgt = (v/niceMax)*plotH;
+ if(hgt<=0) return;
+ var yTop = yCursor - hgt;
+ bar.appendChild(el("rect",{x:x,y:yTop+1,width:bw,height:Math.max(0,hgt-2),rx:2,fill:series[si].color}));
+ yCursor = yTop;
+ });
+ var hit = el("rect",{class:"hit-target",x:x-2,y:padT,width:bw+4,height:plotH});
+ svg.appendChild(bar); svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(pt,x){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[0].color+'"></span>input</span><span class="tooltip-val">'+pt.input.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[1].color+'"></span>output</span><span class="tooltip-val">'+pt.output.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[2].color+'"></span>cache_read</span><span class="tooltip-val">'+pt.cache.toLocaleString()+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(W/rect.width), padT);
+ };}(pt,x));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ var t2 = el("text",{class:"axis-text",x:padL,y:H-6}); t2.textContent = fmtDate(d[0].iso); svg.appendChild(t2);
+ var t3 = el("text",{class:"axis-text",x:W-padR,y:H-6,"text-anchor":"end"}); t3.textContent = fmtDate(d[d.length-1].iso); svg.appendChild(t3);
+ }
+
+ /* ================= Model cost breakdown (horizontal bars) ================= */
+ function renderModelChart(){
+ var svg = document.getElementById("modelChart"); svg.innerHTML="";
+ // modelCosts 是索引器按 usage 事件的真实 model/cost_usd 汇总出来的(全量,不随时间范围筛选——
+ // 按天切分模型成本需要索引器额外输出 daily×model 的交叉表,这版先给全量占比)。
+ var rows = modelCosts.slice().sort(function(a,b){return b.cost-a.cost;});
+ var top = rows.slice(0,4);
+ var restCost = rows.slice(4).reduce(function(a,x){return a+x.cost;},0);
+ if(restCost>0) top.push({name:"其他", cost:restCost, other:true});
+ if(top.length===0){
+ var empty = el("text",{class:"axis-text",x:12,y:30,fill:tok("--text-muted")});
+ empty.textContent = "暂无数据";
+ svg.appendChild(empty);
+ return;
+ }
+
+ var W=460,H=210,padL=12,padR=54,padT=8,padB=8;
+ var rowH = (H-padT-padB)/top.length;
+ var maxV = Math.max.apply(null, top.map(function(x){return x.cost;})) || 1;
+ var colors = [tok("--series-blue"),tok("--series-orange"),tok("--series-aqua"),tok("--series-yellow"),tok("--axis")];
+ var wrap = svg.parentNode, tip = document.getElementById("modelTooltip");
+
+ // 第一遍:把每行的完整模型名挂到 DOM 上量出真实渲染宽度(getComputedTextLength
+ // 要素材已经在 DOM 里才准),取最长的一个决定标签列该留多宽——而不是像之前那样
+ // 写死 84px、名字一长就被柱子盖住。上限按图表总宽的 55% 封顶,避免某一个特别长
+ // 的名字把柱子全挤没了;封顶之后仍放不下的极端情况,靠 truncateSvgText 兜底截断。
+ var geoms = top.map(function(row,i){
+ var y = padT + i*rowH;
+ var barH = Math.min(22, rowH*0.55);
+ var barY = y + (rowH-barH)/2;
+ var label = el("text",{class:"axis-text",x:padL,y:barY+barH/2+3, fill:tok("--text-secondary")});
+ label.setAttribute("font-size","11");
+ label.textContent = row.name;
+ svg.appendChild(label);
+ return {row:row, i:i, y:y, barH:barH, barY:barY, label:label};
+ });
+ var maxLabelW = Math.max.apply(null, geoms.map(function(g){return g.label.getComputedTextLength();}));
+ var labelColW = Math.min(Math.max(maxLabelW+10, 70), W*0.55);
+ var barX = padL+labelColW;
+ var maxW = W-padL-padR-labelColW;
+
+ geoms.forEach(function(g){
+ var row=g.row, i=g.i, y=g.y, barH=g.barH, barY=g.barY, label=g.label;
+ truncateSvgText(label, row.name, labelColW-6);
+ label.appendChild(el("title",{})).textContent = row.name;
+ var w = Math.max(2,(row.cost/maxV)*maxW);
+ var bar = el("rect",{x:barX,y:barY,width:w,height:barH,rx:4,fill:row.other?tok("--axis"):colors[i]});
+ svg.appendChild(bar);
+ var val = el("text",{class:"axis-text",x:barX+w+6,y:barY+barH/2+3, fill:tok("--text-primary")});
+ val.setAttribute("font-weight","600"); val.textContent = fmtUSD(row.cost);
+ svg.appendChild(val);
+ var hit = el("rect",{class:"hit-target",x:0,y:y,width:W,height:rowH});
+ svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(row,y){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-row"><span class="tooltip-key">'+row.name+'</span><span class="tooltip-val">'+fmtUSD(row.cost)+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, (W-40)/(W/rect.width), y/(H/rect.height));
+ };}(row,y));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ }
+
+ /* ================= Daily data table (accessibility fallback) ================= */
+ function renderDailyTable(){
+ var tbody = document.querySelector("#dailyTable tbody");
+ tbody.innerHTML = "";
+ sliced().slice().reverse().forEach(function(pt){
+ var tr = document.createElement("tr");
+ [pt.iso, pt.sessionCount, fmtUSD(pt.cost), pt.input.toLocaleString(), pt.output.toLocaleString(), pt.cache.toLocaleString(), pt.failures]
+ .forEach(function(v,i){
+ var td = document.createElement("td");
+ td.textContent = v; td.classList.add("tab-nums");
+ if(i===0) td.classList.add("strong");
+ tr.appendChild(td);
+ });
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= Sessions tab ================= */
+ function renderSessions(){
+ var tbody = document.querySelector("#sessionTable tbody");
+ tbody.innerHTML = "";
+ if(sessions.length===0){
+ tbody.innerHTML = '<tr><td colspan="9" style="color:var(--text-muted);">暂无会话记录</td></tr>';
+ return;
+ }
+ sessions.forEach(function(s){
+ var tr = document.createElement("tr");
+ tr.className = "data-row";
+ var statusChip = s.status==="error"
+ ? '<span class="chip crit"><span class="chip-dot"></span>有失败</span>'
+ : '<span class="chip good"><span class="chip-dot"></span>正常</span>';
+ tr.innerHTML =
+ '<td class="strong mono">'+s.id+'</td>'+
+ '<td class="tab-nums">'+s.date+'</td>'+
+ '<td>'+s.agent+'</td>'+
+ '<td class="tab-nums">'+s.turns+'</td>'+
+ '<td class="tab-nums">'+s.toolCalls+'</td>'+
+ '<td class="tab-nums">'+s.tokens.toLocaleString()+'</td>'+
+ '<td class="tab-nums">'+fmtUSD(s.cost)+'</td>'+
+ '<td class="tab-nums">'+fmtDur(s.duration)+'</td>'+
+ '<td>'+statusChip+'</td>';
+ tbody.appendChild(tr);
+
+ var expandTr = document.createElement("tr");
+ expandTr.className = "expand-row";
+ expandTr.hidden = true;
+ var td = document.createElement("td");
+ td.colSpan = 9;
+ // 把同一 turn 里连续且工具名相同的调用合并成一段(累加耗时、记次数),
+ // 这样"循环调用同一个工具 N 次"不会被渲染成 N 个几乎看不清的窄条。
+ function mergeTurnEvents(events){
+ var merged = [];
+ events.forEach(function(ev){
+ var last = merged[merged.length-1];
+ var agent = ev.agent || "main";
+ // 只合并连续且 agent 也相同的调用——否则 main 调 Bash、转派给
+ // solo-developer 又调一次 Bash,会被错误地合并成一段"Bash ×2",
+ // 看不出中间其实发生了一次 agent 切换。
+ if(ev.kind==="tool" && last && last.kind==="tool" && last.tool===ev.tool && last.agent===agent){
+ last.ms += ev.ms; last.count += 1; last.err = last.err || ev.err;
+ } else if(ev.kind==="tool"){
+ merged.push({kind:"tool", tool:ev.tool, ms:ev.ms, count:1, err:ev.err, agent:agent});
+ } else {
+ merged.push({kind:"usage", tokens:ev.tokens, agent:agent});
+ }
+ });
+ return merged;
+ }
+ var timelineHtml = s.timeline.map(function(turn){
+ var toolRaw = turn.events.filter(function(e){ return e.kind==="tool"; }).length;
+ var segsData = mergeTurnEvents(turn.events);
+ var toolMerged = segsData.filter(function(e){ return e.kind==="tool"; }).length;
+ // 段宽是真实像素(不是 flex-grow 权重),行外层带 overflow-x:auto——
+ // 调用数再多,也只是这一行变宽可横向滚动,不会撑破卡片或挤压其它内容。
+ var segs = segsData.map(function(seg){
+ var isSubagent = seg.agent && seg.agent !== "main";
+ if(seg.kind==="tool"){
+ var cls = (seg.err ? "err" : (seg.count>1 ? "merged" : "ok")) + (isSubagent ? " subagent" : "");
+ var label = seg.count>1 ? (seg.tool+' ×'+seg.count) : seg.tool;
+ var titleText = seg.tool + (seg.count>1 ? (' × '+seg.count+' 次,合计 '+seg.ms+'ms') : (' · '+seg.ms+'ms')) + ' · agent='+(seg.agent||"main");
+ // 段宽取"按耗时算出的宽度"和"能放下标签文字的最小宽度"两者较大值——
+ // 本地工具调用常常只有几百 ms,纯按 ms*0.05 算出来的宽度几乎总是不到
+ // 文字下限,标签会被整段隐藏,只能靠悬浮 title 才看得到工具名。
+ var labelW = Math.min(140, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(140, seg.ms*0.05));
+ return '<div class="timeline-seg '+cls+'" style="width:'+w+'px" title="'+titleText+'">'+label+'</div>';
+ }
+ var label = seg.tokens+' tok';
+ var labelW = Math.min(130, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(130, seg.tokens*0.008));
+ var usageCls = "usage"+(isSubagent ? " subagent" : "");
+ return '<div class="timeline-seg '+usageCls+'" style="width:'+w+'px" title="usage · '+seg.tokens+' tok · agent='+(seg.agent||"main")+'">'+label+'</div>';
+ }).join("");
+ var countNote = (toolMerged!==toolRaw)
+ ? ('共 '+toolRaw+' 次工具调用 · 合并连续重复为 '+toolMerged+' 段')
+ : (toolRaw+' 次工具调用');
+ return '<div class="timeline-turn"><div class="timeline-turn-head"><span class="timeline-turn-label">turn '+turn.turn+' &middot; agent='+turn.agent+'</span><span class="timeline-turn-count">'+countNote+'</span></div><div class="timeline-scroll"><div class="timeline-track">'+segs+'</div></div></div>';
+ }).join("");
+ td.innerHTML = '<div class="timeline">'+timelineHtml+'</div>';
+ expandTr.appendChild(td);
+ tbody.appendChild(expandTr);
+
+ tr.addEventListener("click", function(expandTr){ return function(){ expandTr.hidden = !expandTr.hidden; }; }(expandTr));
+ });
+ }
+
+ /* ================= Skills tab ================= */
+ function renderHeatmap(){
+ var svg = document.getElementById("heatmap"); svg.innerHTML="";
+ var d = daily; // full 90d regardless of range filter, like a contribution calendar
+ var cell=11, gap=3, padL=26, padT=14;
+ var weeks = Math.ceil(d.length/7);
+ var maxHit = Math.max.apply(null, d.map(function(x){
+ return Object.keys(x.skillHits).reduce(function(a,k){return a+x.skillHits[k];},0);
+ })) || 1;
+ var ramp = ["--seq-100","--seq-200","--seq-350","--seq-450","--seq-600"];
+ var dow = ["一","三","五"];
+ [1,3,5].forEach(function(row,ix){
+ var t = el("text",{class:"axis-text",x:padL-8,y:padT+row*(cell+gap)+9,"text-anchor":"end"});
+ t.textContent = dow[ix]; svg.appendChild(t);
+ });
+ var wrap = svg.parentNode, tip = document.getElementById("heatmapTooltip");
+ for(var i=0;i<d.length;i++){
+ var pt = d[i];
+ var jsDow = pt.date.getDay(); // 0=Sun
+ var col = Math.floor(i/7), row = jsDow;
+ var total = Object.keys(pt.skillHits).reduce(function(a,k){return a+pt.skillHits[k];},0);
+ var level = total===0 ? -1 : Math.min(4, Math.floor((total/maxHit)*5));
+ var color = level<0 ? tok("--grid") : tok("--"+ramp[level].slice(2));
+ var x = padL + col*(cell+gap), y = padT + row*(cell+gap);
+ var rect = el("rect",{x:x,y:y,width:cell,height:cell,rx:2,fill:color});
+ svg.appendChild(rect);
+ rect.addEventListener("pointermove", function(pt,total,x,y){ return function(evt){
+ var rect2 = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key">skill 命中</span><span class="tooltip-val">'+total+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(900/rect2.width), y/(118/rect2.height));
+ };}(pt,total,x,y));
+ rect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ }
+ }
+
+ function renderSkillBars(){
+ var el2 = document.getElementById("skillBars");
+ var totals = {};
+ SKILLS.forEach(function(s){ totals[s]=0; });
+ daily.forEach(function(pt){ SKILLS.forEach(function(s){ totals[s]+=pt.skillHits[s]; }); });
+ var rows = SKILLS.map(function(s){ return {name:s, count:totals[s]}; }).sort(function(a,b){return b.count-a.count;});
+ var maxV = rows[0] ? rows[0].count : 1;
+ el2.innerHTML = "";
+ rows.forEach(function(r,i){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">'+r.name+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-blue")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderUnused(){
+ var el2 = document.getElementById("unusedList");
+ el2.innerHTML = "";
+ NEVER_USED.forEach(function(u){
+ var div = document.createElement("div");
+ div.className = "unused-item";
+ div.innerHTML = '<div><div class="unused-name">'+u.name+'</div><div style="font-size:11.5px;color:var(--text-muted);margin-top:2px;">'+u.detail+'</div></div><span class="reason-chip">'+u.reason+'</span>';
+ el2.appendChild(div);
+ });
+ }
+
+ /* ================= Agents tab ================= */
+ function renderDispatch(){
+ var el2 = document.getElementById("dispatchBars");
+ el2.innerHTML = "";
+ if(dispatch.length===0){
+ el2.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无派发记录</div>';
+ return;
+ }
+ var maxV = dispatch[0].count;
+ dispatch.forEach(function(r){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">main → '+r.agent+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-aqua")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderFailTable(){
+ var tbody = document.querySelector("#failTable tbody");
+ tbody.innerHTML = "";
+ failures.forEach(function(f){
+ var tr = document.createElement("tr");
+ tr.innerHTML = '<td class="strong">'+f.tool+'</td><td class="mono">'+f.code+'</td><td class="tab-nums">'+f.count+'</td><td class="tab-nums">'+f.last+'</td>';
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= devflow ================= */
+ function renderDevflowHealth(){
+ var d = autoDispatchStats;
+ var total = d.auto_dispatch + d.fallback_to_main + d.passthrough;
+ document.getElementById("hDispatch").textContent = d.auto_dispatch.toLocaleString();
+ document.getElementById("hFallback").textContent = d.fallback_to_main.toLocaleString();
+ var rate = total ? (d.fallback_to_main/total*100) : 0;
+ document.getElementById("hFallbackRate").textContent = rate.toFixed(1)+"%";
+ var bar = document.getElementById("hBar");
+ bar.innerHTML = "";
+ [["auto_dispatch",tok("--status-good")],["fallback_to_main",tok("--status-warning")],["passthrough",tok("--text-muted")]].forEach(function(pair){
+ var seg = document.createElement("div");
+ seg.className = "health-bar-seg";
+ seg.style.width = (total? d[pair[0]]/total*100 : 0)+"%";
+ seg.style.background = pair[1];
+ seg.title = pair[0]+": "+d[pair[0]];
+ bar.appendChild(seg);
+ });
+ }
+
+ function renderDevflowRuns(){
+ var wrap = document.getElementById("devflowRuns");
+ wrap.innerHTML = "";
+ if(devflowRuns.length===0){
+ wrap.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无 devflow 运行记录(没有 artifacts/*/workflow-state.json,或者项目还没跑过 /start-devflow)</div>';
+ return;
+ }
+ devflowRuns.forEach(function(run){
+ var card = document.createElement("div");
+ card.className = "run-card";
+ var statusChip = run.overall==="completed"
+ ? '<span class="run-status-chip" style="background:var(--status-good-bg);color:var(--status-good)"><span class="chip-dot"></span>已完成</span>'
+ : run.overall==="running"
+ ? '<span class="run-status-chip" style="background:var(--series-blue-wash);color:var(--series-blue)"><span class="chip-dot"></span>进行中</span>'
+ : '<span class="run-status-chip" style="background:var(--status-critical-bg);color:var(--status-critical)"><span class="chip-dot"></span>已暂停 · 待人工介入</span>';
+ var head = document.createElement("div");
+ head.className = "run-head";
+ head.innerHTML =
+ '<div class="run-title">'+run.slug+'</div>'+
+ '<div class="run-meta"><span class="size-chip">'+run.size+'</span>'+statusChip+
+ '<span class="tab-nums">'+fmtUSD(run.cost)+'</span><span class="tab-nums" title="按真实起止跨度(最早 started_at 到最晚 completed_at)计算;阶段之间有重叠时,会小于各阶段耗时直接相加">'+fmtDur(run.duration)+'</span></div>';
+ card.appendChild(head);
+
+ var stepper = document.createElement("div");
+ stepper.className = "stepper";
+ run.stages.forEach(function(s){
+ var step = document.createElement("div");
+ step.className = "step";
+ var retryBadge = s.retry_count>0 ? '<div class="step-retry">&#8635;'+s.retry_count+'</div>' : "";
+ var titleText = s.name+" · executor="+s.exec+(s.status!=="pending"?(" · "+fmtDur(s.duration)):"")+(s.retry_count>0?(" · retry_count="+s.retry_count):"");
+ step.innerHTML =
+ '<div class="step-connector"></div>'+
+ '<div class="step-dot '+s.status+'" title="'+titleText+'">'+s.label+retryBadge+'</div>'+
+ '<div class="step-label">'+s.name+'</div>';
+ stepper.appendChild(step);
+ });
+ card.appendChild(stepper);
+ wrap.appendChild(card);
+ });
+ }
+
+ /* ================= render all ================= */
+ function renderAll(){
+ renderKPIs();
+ renderReminders();
+ renderCostChart();
+ renderModelChart();
+ renderTokenChart();
+ renderDailyTable();
+ renderSessions();
+ renderHeatmap();
+ renderSkillBars();
+ renderUnused();
+ renderDispatch();
+ renderFailTable();
+ renderDevflowHealth();
+ renderDevflowRuns();
+ }
+
+ /* ================= load real data from ./dashboard-data.json ================= */
+ function setBadge(text, tone){
+ var badge = document.getElementById("dataStatusBadge");
+ badge.textContent = text;
+ badge.style.color = tone==="good" ? tok("--status-good") : tone==="crit" ? tok("--status-critical") : tok("--status-warning");
+ badge.style.background = tone==="good" ? tok("--status-good-bg") : tone==="crit" ? tok("--status-critical-bg") : tok("--status-warning-bg");
+ }
+ function loadData(){
+ fetch("./dashboard-data.json", {cache:"no-store"})
+ .then(function(resp){
+ if(!resp.ok) throw new Error("HTTP "+resp.status);
+ return resp.json();
+ })
+ .then(function(data){
+ daily = (data.daily||[]).map(function(d){ d.date = new Date(d.iso+"T00:00:00"); return d; });
+ sessions = data.sessions||[];
+ dispatch = data.dispatch||[];
+ failures = data.failures||[];
+ SKILLS = (data.skills||[]).map(function(s){return s.name;});
+ NEVER_USED = data.neverUsed||[];
+ modelCosts = data.modelCosts||[];
+ unpricedModels = data.unpricedModels||[];
+ devflowRuns = data.devflowRuns||[];
+ autoDispatchStats = data.autoDispatchStats||{auto_dispatch:0, fallback_to_main:0, passthrough:0};
+
+ var total = (data.source && data.source.event_count) || 0;
+ if(total===0){
+ setBadge("还没有数据 · 见页脚生成说明", "warn");
+ } else {
+ var genAt = data.generated_at ? data.generated_at.replace("T"," ").replace("+00:00"," UTC") : "";
+ setBadge("真实数据 · "+total+" 条事件 · 生成于 "+genAt, "good");
+ }
+ renderAll();
+ })
+ .catch(function(err){
+ setBadge("加载 dashboard-data.json 失败", "crit");
+ var note = document.querySelector("footer.note");
+ if(note){
+ var warn = document.createElement("div");
+ warn.style.cssText = "margin-top:10px;color:"+tok("--status-critical")+";";
+ warn.textContent = "错误详情:" + err.message + "(先运行 build_dashboard_data.py 生成这份快照,再用本地 HTTP server 打开本页——直接双击用 file:// 打开会因为浏览器禁止本地 fetch 而失败)。";
+ note.appendChild(warn);
+ }
+ renderAll();
+ });
+ }
+ loadData();
+
+ /* ================= wiring: range buttons ================= */
+ document.querySelectorAll(".range-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".range-btn").forEach(function(b){ b.setAttribute("aria-pressed","false"); });
+ btn.setAttribute("aria-pressed","true");
+ currentRange = parseInt(btn.dataset.range,10);
+ renderKPIs(); renderReminders(); renderCostChart(); renderModelChart(); renderTokenChart(); renderDailyTable();
+ });
+ });
+
+ /* ================= wiring: tabs ================= */
+ var panels = {overview:"panel-overview", sessions:"panel-sessions", skills:"panel-skills", agents:"panel-agents", devflow:"panel-devflow"};
+ document.querySelectorAll(".tab-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".tab-btn").forEach(function(b){ b.setAttribute("aria-selected","false"); });
+ btn.setAttribute("aria-selected","true");
+ Object.keys(panels).forEach(function(k){ document.getElementById(panels[k]).hidden = (k!==btn.dataset.tab); });
+ });
+ });
+
+ window.addEventListener("resize", function(){
+ renderCostChart(); renderModelChart(); renderTokenChart(); renderHeatmap();
+ });
+})();
+</script>
+</body>
+</html>
diff --git a/.claude/skills/agent-observability/scripts/main.py b/.claude/skills/agent-observability/scripts/main.py
new file mode 100644
index 00000000..4ca24812
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/main.py
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""agent-observability 的 hook 入口。"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+if __package__ in (None, ""):
+ _SCRIPTS_DIR = Path(__file__).resolve().parent
+ if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+ from core.runtime import main as runtime_main # type: ignore
+else:
+ from .core.runtime import main as runtime_main
+
+
+def main() -> int:
+ return runtime_main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.claude/skills/agent-observability/scripts/run_hook.sh b/.claude/skills/agent-observability/scripts/run_hook.sh
new file mode 100644
index 00000000..d476810f
--- /dev/null
+++ b/.claude/skills/agent-observability/scripts/run_hook.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+PROJECT_DIR="${CODEBUDDY_PROJECT_DIR:-$(cd "$(dirname "$0")"/../../../.. && pwd -P)}"
+PYTHON_BIN="$PROJECT_DIR/.venv/bin/python"
+MAIN_PY="$PROJECT_DIR/.codebuddy/skills/agent-observability/scripts/main.py"
+
+# 只有当 .venv 里可用 zhiyanllm 时才优先使用该解释器;
+# 否则回退到已安装 zhiyanllm 的系统 python3。
+if [ -x "$PYTHON_BIN" ]; then
+ if "$PYTHON_BIN" -c "import zhiyanllm" 2>/dev/null; then
+ exec "$PYTHON_BIN" "$MAIN_PY" "$@"
+ fi
+fi
+
+exec python3 "$MAIN_PY" "$@"
diff --git a/.claude/skills/agent-observability/templates/settings-hook.json b/.claude/skills/agent-observability/templates/settings-hook.json
new file mode 100644
index 00000000..6da0900a
--- /dev/null
+++ b/.claude/skills/agent-observability/templates/settings-hook.json
@@ -0,0 +1,62 @@
+{
+ "_comment": "将本文件合并到 ~/.claude/settings.json 或 <project>/.claude/settings.json",
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.claude/skills/agent-observability/scripts/run_hook.sh session-start",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.claude/skills/agent-observability/scripts/run_hook.sh user-prompt-submit",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.claude/skills/agent-observability/scripts/run_hook.sh pre",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.claude/skills/agent-observability/scripts/run_hook.sh post",
+ "timeout": 30
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.claude/skills/agent-observability/scripts/run_hook.sh stop",
+ "timeout": 30
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.claude/skills/agent-observability/tests/fixtures/transcript.jsonl b/.claude/skills/agent-observability/tests/fixtures/transcript.jsonl
new file mode 100644
index 00000000..a5ea47dd
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/fixtures/transcript.jsonl
@@ -0,0 +1,10 @@
+{"type":"system","subtype":"init","session_id":"demo-001","content":"<rules>\n<security_rules>do not exec</security_rules>\n</rules>\n<available_skills>\n<skill><name>pdf</name></skill>\n<skill><name>hermes-devflow</name></skill>\n</available_skills>"}
+{"type":"assistant","providerData":{"messageId":"msg-001"},"content":[{"type":"tool_use","name":"read_file","input":{"filePath":"README.md"}}],"usage":{"input_tokens":1820,"output_tokens":42,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"function_call_result","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"assistant","providerData":{"messageId":"msg-002"},"content":[{"type":"tool_use","name":"use_skill","input":{"command":"pdf"}}],"usage":{"input_tokens":2100,"output_tokens":58,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"assistant","providerData":{"messageId":"msg-003"},"content":"完成","usage":{"input_tokens":2240,"output_tokens":120,"cache_read_input_tokens":15300}}
diff --git a/.claude/skills/agent-observability/tests/test_agent_identity.py b/.claude/skills/agent-observability/tests/test_agent_identity.py
new file mode 100644
index 00000000..664cc1dd
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_agent_identity.py
@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core.agent_identity import AgentIdentityResolver # type: ignore
+from core import state as st # type: ignore
+
+
+class AgentIdentityResolverTests(unittest.TestCase):
+ def test_extract_identity_from_send_message_json(self):
+ resolver = AgentIdentityResolver()
+ data = {
+ "tool_name": "send_message",
+ "tool_input": {
+ "content": '{"from_role":"developer","next_target":{"role_name":"leader"}}'
+ },
+ }
+ current, dispatched = resolver.extract_identity(data)
+ self.assertEqual(current, "developer")
+ self.assertEqual(dispatched, "leader")
+
+ def test_track_returns_active_and_dispatched(self):
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s2"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "developer")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("current_agent"), "developer")
+ self.assertEqual(sess.get("dispatched", {}).get("developer"), 1)
+
+ def test_track_recognizes_agent_tool_subagent_type(self):
+ """Claude Code 的 Agent 工具用 subagent_type(不是 CodeBuddy 原生 Task 的
+ subagent_name)标识派发目标;这条路径之前没有测试覆盖,_extract_from_task
+ 漏认这个字段会导致 dispatch 统计对所有 Agent 工具派发的场景失明。"""
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s3"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Agent",
+ "tool_input": {"subagent_type": "worker", "description": "spawn a team"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "worker")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("dispatched", {}).get("worker"), 1)
+ hist = sess.get("agent_history") or []
+ self.assertTrue(any(
+ h.get("agent") == "worker" and str(h.get("evidence") or "").startswith("dispatch")
+ for h in hist
+ ))
+
+ def test_extract_from_task_prefers_subagent_type_over_subagent_name(self):
+ resolver = AgentIdentityResolver()
+ result = resolver._extract_from_task({"subagent_type": "explorer", "subagent_name": "developer"})
+ self.assertEqual(result, "explorer")
diff --git a/.claude/skills/agent-observability/tests/test_build_dashboard_data.py b/.claude/skills/agent-observability/tests/test_build_dashboard_data.py
new file mode 100644
index 00000000..53b031c1
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_build_dashboard_data.py
@@ -0,0 +1,603 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+
+
+class ToolCallFailedTests(unittest.TestCase):
+ """真实 CodeBuddy CLI transcript 里从没出现过 `is_error` 这个键——实测抓到的
+ rawResponse 形如 {"exitCode": 0, "tool_error_code": "0", ...}(成功)或非 0
+ exitCode(失败)。之前只认 is_error,导致这个宿主上失败统计永远是 0。"""
+
+ def test_real_success_shape_from_codebuddy_is_not_a_failure(self):
+ # 实测数据:ls 一个不存在的路径,但命令写成了 `ls ...; echo "EXIT_CODE=$?"`,
+ # 复合命令整体 exitCode 被内层 echo 冲成了 0——工具调用本身没有失败。
+ raw_response = {
+ "exitCode": 0, "signal": None, "interrupted": False,
+ "sandboxDenied": False, "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0, "tool_error_code": "0",
+ }
+ self.assertFalse(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_exit_code_is_a_failure(self):
+ raw_response = {"exitCode": 1, "tool_error_code": "1"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_tool_error_code_without_exit_code_is_a_failure(self):
+ raw_response = {"tool_error_code": "127"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_legacy_is_error_flag_still_recognized(self):
+ self.assertTrue(bdd.tool_call_failed({"is_error": True}))
+
+ def test_missing_or_non_dict_raw_response_is_not_a_failure(self):
+ self.assertFalse(bdd.tool_call_failed(None))
+ self.assertFalse(bdd.tool_call_failed("not a dict"))
+ self.assertFalse(bdd.tool_call_failed({}))
+
+ def test_build_failures_and_session_status_use_exit_code(self):
+ events = [
+ {
+ "event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash",
+ "tool_details": {"raw_response": {"exitCode": 1, "tool_error_code": "1"}},
+ },
+ ]
+ failures = bdd.build_failures(events)
+ self.assertEqual(len(failures), 1)
+ self.assertEqual(failures[0]["tool"], "Bash")
+ self.assertEqual(failures[0]["code"], "1")
+
+ _, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(sessions[0]["status"], "error")
+
+
+class ResolveInputPathsTests(unittest.TestCase):
+ def setUp(self):
+ self.skill_root = Path("/tmp/fake-skill-root")
+
+ def test_defaults_fall_back_to_skill_root_logs(self):
+ metrics, state = bdd.resolve_input_paths(self.skill_root)
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_none_args_equivalent_to_empty_args(self):
+ m1, s1 = bdd.resolve_input_paths(self.skill_root, None, None)
+ m2, s2 = bdd.resolve_input_paths(self.skill_root, "", "")
+ self.assertEqual((m1, s1), (m2, s2))
+
+ def test_both_args_override(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_metrics_only_override_keeps_default_state(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", None
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_state_only_override_keeps_default_metrics(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, None, "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_tilde_expansion(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "~/x/metrics.ndjson", "~/y/.state.json"
+ )
+ self.assertEqual(metrics, (Path.home() / "x" / "metrics.ndjson").absolute())
+ self.assertEqual(state, (Path.home() / "y" / ".state.json").absolute())
+
+
+class MainEndToEndTests(unittest.TestCase):
+ def _run_main(self, argv: list[str]) -> None:
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ try:
+ self.assertEqual(bdd.main(), 0)
+ finally:
+ sys.argv = old_argv
+
+ def test_default_paths_unchanged_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ out = Path(td) / "dashboard-data.json"
+ self._run_main(["--project-root", td, "--out", str(out)])
+ self.assertTrue(out.is_file())
+ data = json.loads(out.read_text("utf-8"))
+ expected_metrics = str(bdd.SCRIPTS_DIR.parent / "logs" / "metrics.ndjson")
+ expected_state = str(bdd.SCRIPTS_DIR.parent / "logs" / ".state.json")
+ self.assertEqual(data["source"]["metrics_ndjson"], expected_metrics)
+ self.assertEqual(data["source"]["state_json"], expected_state)
+
+ def test_overridden_paths_read_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics_file = root / "metrics.ndjson"
+ state_file = root / ".state.json"
+ metrics_file.write_text(
+ '{"event":"usage","sid":"s1","ts":1,"tokens":{"input":10,"output":20}}\n',
+ encoding="utf-8",
+ )
+ state_file.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ out = root / "dashboard-data.json"
+
+ self._run_main([
+ "--project-root", td,
+ "--out", str(out),
+ "--metrics-path", str(metrics_file),
+ "--state-path", str(state_file),
+ ])
+ self.assertTrue(out.is_file())
+
+ data = json.loads(out.read_text("utf-8"))
+ # resolve_input_paths 对覆盖路径执行 .expanduser().absolute(),断言需对齐(macOS 下不用 .resolve() 以避免 /tmp → /private/tmp 符号链接错位)。
+ self.assertEqual(data["source"]["metrics_ndjson"], str(metrics_file.absolute()))
+ self.assertEqual(data["source"]["state_json"], str(state_file.absolute()))
+ # 覆盖文件确实被读取:metrics 行被解析进了 event_count。
+ self.assertEqual(data["source"]["event_count"], 1)
+
+
+class TopSlowTests(unittest.TestCase):
+ """`--top-slow N` 是纯增量能力:默认不开启,开启后也只往终端打印,绝不改动
+ dashboard-data.json 的结构(看板前端按字段取值,多一个字段或少一个字段都会
+ 直接影响渲染)。这些用例把"降序取前 N""非 tool 事件排除""ms 兜底""只读"
+ 四条边界钉住,避免后续有人顺手把结果写进 JSON 或改了排序方向。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 300, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Bash", "ms": 900, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 120, "agent": "main"},
+ ]
+
+ def _write_metrics(self, root: Path) -> Path:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text(
+ "\n".join(json.dumps(e) for e in self._events()) + "\n",
+ encoding="utf-8",
+ )
+ return metrics
+
+ def _run_main(self, argv: list[str]) -> str:
+ """跑一次 main() 并返回捕获到的 stdout——top-slow 的产出只体现在终端上,
+ 不体现在 JSON 里,所以断言必须落在 stdout。"""
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ return buf.getvalue()
+
+ def _printed_tools(self, stdout: str) -> list[str]:
+ tools = []
+ for line in stdout.splitlines():
+ line = line.strip()
+ if not line or not line[0].isdigit():
+ continue
+ tools.append(line.split(". ", 1)[1].split()[0])
+ return tools
+
+ def test_returns_n_slowest_tool_events_descending(self):
+ rows = bdd.build_top_slow(self._events(), 2)
+ self.assertEqual([(r["tool"], r["ms"]) for r in rows], [("Bash", 900), ("Read", 300)])
+
+ def test_limit_greater_than_event_count_returns_all_without_error(self):
+ events = [{"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 10}]
+ rows = bdd.build_top_slow(events, 99)
+ self.assertEqual(len(rows), 1)
+ self.assertEqual(rows[0]["tool"], "Bash")
+
+ def test_non_tool_events_are_excluded(self):
+ rows = bdd.build_top_slow(self._events(), 10)
+ self.assertEqual([r["tool"] for r in rows], ["Bash", "Read", "Grep"])
+ # usage 事件即使带 ms 也不能混进来。
+ self.assertTrue(all(isinstance(r["ms"], (int, float)) for r in rows))
+
+ def test_missing_or_non_numeric_ms_falls_back_to_zero(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": "120"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Grep", "ms": None},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Edit", "ms": 1},
+ ]
+ rows = bdd.build_top_slow(events, 4)
+ self.assertEqual(len(rows), 4)
+ # 非数字/缺失的 ms 一律按 0 计,不会把字符串 "120" 排到最前面。
+ self.assertEqual(sum(r["ms"] for r in rows), 1)
+
+ def test_disabled_by_default_prints_nothing_extra(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertNotIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), [])
+
+ def test_enabled_prints_tool_and_ms_descending(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ "--top-slow", "2",
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), ["Bash", "Read"])
+ self.assertIn("900ms", stdout)
+ self.assertNotIn("120ms", stdout) # N=2,第三名的 Grep 不该出现
+
+ def test_enabled_does_not_change_dashboard_data_structure(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ state = root / ".state.json"
+ state.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ # 输出到两个不同文件再比对,避免"第二次跑覆盖了第一次"导致对比失真。
+ out_on = root / "on.json"
+ out_off = root / "off.json"
+ self._run_main([
+ "--project-root", td, "--out", str(out_on),
+ "--metrics-path", str(metrics), "--state-path", str(state), "--top-slow", "5",
+ ])
+ self._run_main([
+ "--project-root", td, "--out", str(out_off),
+ "--metrics-path", str(metrics), "--state-path", str(state),
+ ])
+ data_on = json.loads(out_on.read_text("utf-8"))
+ data_off = json.loads(out_off.read_text("utf-8"))
+ data_on.pop("generated_at")
+ data_off.pop("generated_at")
+ self.assertEqual(data_on, data_off)
+ # 兜底断言:结果没有以任何形式渗进 JSON(不只是"结构相同")。
+ self.assertNotIn("topSlow", json.dumps(data_on))
+ self.assertNotIn("top-slow", json.dumps(data_on))
+
+
+class BuildDailyAndSessionsTurnAttributionTests(unittest.TestCase):
+ """真实场景复现过:AgentLens(写 state.current_turn 的那套 tracing)关闭时,
+ tool/usage 事件自己的 turn_id 永远是 None,只有 user_prompt_submit 事件带真实
+ turn_id。修复前所有没有 turn_id 的事件会被塌缩进同一个 "?" 占位桶,看起来
+ 像"整个会话只有 1 个 turn",哪怕实际发了好几轮 prompt。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t2", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 6.0, "tool": "Edit", "ms": 80, "agent": "main"},
+ ]
+
+ def test_turns_reflect_prompt_boundaries_not_a_single_bucket(self):
+ daily, sessions = bdd.build_daily_and_sessions(self._events())
+ self.assertEqual(len(sessions), 1)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 2)
+ self.assertEqual(sess["toolCalls"], 3)
+ self.assertEqual(len(sess["timeline"]), 2)
+ turn1_tools = [e["tool"] for e in sess["timeline"][0]["events"] if e["kind"] == "tool"]
+ turn2_tools = [e["tool"] for e in sess["timeline"][1]["events"] if e["kind"] == "tool"]
+ self.assertEqual(turn1_tools, ["Bash"])
+ self.assertEqual(turn2_tools, ["Read", "Edit"])
+
+ def test_events_before_first_prompt_fall_back_to_unknown_bucket(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 2.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Read", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ # 没有归属到任何真实 turn 的事件仍然单独成桶,不会被错误地并入第一个真实 turn。
+ self.assertEqual(len(sess["timeline"]), 2)
+ self.assertEqual(sess["timeline"][0]["turn"], 1)
+
+ def test_prompt_only_turn_with_no_tool_calls_still_appears_in_timeline(self):
+ """真实数据复现过:纯对话轮次(用户发了 prompt,但助手没有调用任何工具,
+ 也没有产生 usage 事件)之前完全不会在 timeline 里建桶——turns 计数是对的
+ (来自 user_prompt_submit 自带的 turn_id),但展开的时间线分组数会比 turns
+ 少,二者对不上。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 3.0, "turn_id": "t2", "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t3", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 3)
+ self.assertEqual(len(sess["timeline"]), 3)
+ self.assertEqual(sess["timeline"][1]["events"], [])
+
+ def test_prompt_only_session_still_counted_in_daily_session_count(self):
+ """真实数据复现过(TC5 当天 5 个 session,"总览"页汇总出的会话数却是 4):
+ daily["_sids"]("会话浏览"总览卡片"会话数"的数据源)之前只在 tool/usage
+ 分支里 add,一个全程只发了 prompt、没有触发任何工具调用也没有 usage 事件
+ 的 session(比如用户发了消息但被拒绝/打断,没有真正执行)会被这天的
+ sessionCount 完全漏掉——尽管 sessions 列表("会话浏览"tab)里它确实在,
+ 导致总览页"会话数"比实际能展开看到的会话数少。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s2", "ts": 3.0, "turn_id": "t1", "agent": "main"},
+ ]
+ daily, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(len(sessions), 2)
+ self.assertEqual(len(daily), 1)
+ self.assertEqual(daily[0]["sessionCount"], 2)
+
+
+class BuildDevflowRunsClassicSoloTests(unittest.TestCase):
+ """真实运行验证过:Classic small 任务会经过 PHASE-0 -> SOLO -> TASK-05
+ (knowledge 由 solo-developer 合并执行),不是只有 PHASE-0/SOLO 两步。"""
+
+ def test_solo_run_includes_task05_and_marks_phase0_completed(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "solo-with-knowledge_20260914_0600"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "solo-with-knowledge_20260914_0600",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ # 注意:真实 schema 里 stages{} 不含 PHASE-0 —— Phase 0 是隐式完成的。
+ "stages": {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-02": {"status": "skipped", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "skipped", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "skipped", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "skipped", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-05", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-05"], "completed")
+ self.assertEqual(stage_by_key["PHASE-0"], "completed")
+ self.assertNotIn("TASK-01", stage_by_key) # SOLO 路径不该混进 medium/large 的阶段
+
+
+class BuildDevflowRunsMediumWithLingeringSoloKeyTests(unittest.TestCase):
+ """用户反馈复现:workflow-state.json 模板固定给每次运行都写一份 SOLO stage
+ (见 assets/workflow-state-template.json 里 SOLO.description 的说明:
+ "仅当 size_class==small 时启用,否则保持 skipped"),medium/large 任务从不会
+ 真正执行它,状态停在 "pending" 或 "skipped"。修复前 `"SOLO" in stages` 只看
+ key 存不存在,不看状态,导致这类 medium 任务被误判成 solo 路径,阶段视图会用
+ CLASSIC_SOLO_ORDER 渲染,把 TASK-01/TASK-02/TASK-03/CODE-REVIEW/TASK-04 全部
+ 从 stepper 里漏掉。"""
+
+ def _run(self, solo_status: str):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "medium-with-lingering-solo_20260915_0900"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "medium-with-lingering-solo_20260915_0900",
+ "size_class": "medium",
+ "current_stage": "TASK-03",
+ "last_event": "TASK-02_completed",
+ "stages": {
+ "SOLO": {"status": solo_status, "executor": "solo-developer", "retry_count": 0},
+ "TASK-01": {"status": "completed", "executor": "main", "retry_count": 0},
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "pending", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "pending", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "pending", "executor": "knowledge-engineer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+ return bdd.build_devflow_runs(project_root)
+
+ def test_medium_run_with_skipped_solo_key_uses_full_classic_order(self):
+ runs = self._run("skipped")
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ # 修复前:这里会走 CLASSIC_SOLO_ORDER,TASK-01/02/03/CODE-REVIEW/TASK-04 全部消失。
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("TASK-02", stage_by_key)
+ self.assertIn("TASK-03", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+ self.assertIn("TASK-04", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-02"], "completed")
+ self.assertEqual(stage_by_key["TASK-03"], "in_progress")
+
+ def test_medium_run_with_pending_solo_key_uses_full_classic_order(self):
+ # 模板初始状态是 "pending"(不是所有实现都会显式改成 "skipped"),同样不该被判成 solo。
+ runs = self._run("pending")
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+
+
+class BuildDevflowRunsDurationTests(unittest.TestCase):
+ """真实数据复现过:TASK-05 的 started_at 可能早于 SOLO 的 completed_at
+ (同一次 solo-developer 执行内部的子步骤,不是真正先后发生的两个阶段)。
+ total_duration 必须按真实起止跨度算,不能对逐阶段 duration 求和——否则会把
+ 重叠部分重复计入,虚高于源数据本身反映的运行时长(这次修复前是 600s,
+ 真实跨度只有 540s)。"""
+
+ def _write_state(self, project_root: Path, stages: dict) -> None:
+ run_dir = project_root / "artifacts" / "overlap-run_20260914_0620"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "overlap-run_20260914_0620",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ "stages": stages,
+ }), encoding="utf-8")
+
+ def test_total_duration_uses_true_span_not_sum_of_overlapping_stages(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ "started_at": "2026-09-14T06:20:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ "TASK-05": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ # 早于 SOLO 的 completed_at —— 真实数据里观测到的重叠场景。
+ "started_at": "2026-09-14T06:28:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ # 真实跨度是 06:20~06:29 = 540s,不是 540+60=600s。
+ self.assertEqual(runs[0]["duration"], 540)
+ stage_by_key = {s["key"]: s["duration"] for s in runs[0]["stages"]}
+ # 单个阶段自身的 duration 不受影响,仍然如实反映各自的起止跨度。
+ self.assertEqual(stage_by_key["SOLO"], 540)
+ self.assertEqual(stage_by_key["TASK-05"], 60)
+
+ def test_total_duration_is_zero_when_no_stage_has_valid_timestamps(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(runs[0]["duration"], 0)
+
+
+class BuildDailyAndSessionsPerEventAgentTests(unittest.TestCase):
+ """真实数据复现过(TC5,size_class=small 但走了真实 team_create/send_message
+ 派发):同一个 sid 下,metrics.ndjson 的 tool/usage 事件本来就各自带着准确的
+ agent 字段(一次真实会话里 66 条 main、64 条 solo-developer),但展开进
+ timeline 的每条 event 字典只有 kind/tool/ms/err,从不写回 agent —— 时间线里
+ 完全看不出某次工具调用到底是 main 自己做的还是派发给 solo-developer 后做的,
+ 等于白白丢弃了上游已经采集到的数据。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Agent", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Bash", "ms": 100, "agent": "solo-developer"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "tokens": {"input": 10, "output": 5}, "agent": "solo-developer"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "SendMessage", "ms": 30, "agent": "main"},
+ ]
+
+ def test_timeline_events_carry_the_agent_that_actually_ran_them(self):
+ _, sessions = bdd.build_daily_and_sessions(self._events())
+ sess = sessions[0]
+ events = sess["timeline"][0]["events"]
+ by_tool = {e.get("tool"): e for e in events if e["kind"] == "tool"}
+ self.assertEqual(by_tool["Agent"]["agent"], "main")
+ self.assertEqual(by_tool["Bash"]["agent"], "solo-developer")
+ self.assertEqual(by_tool["SendMessage"]["agent"], "main")
+ usage_events = [e for e in events if e["kind"] == "usage"]
+ self.assertEqual(usage_events[0]["agent"], "solo-developer")
+
+ def test_missing_agent_on_raw_event_falls_back_to_main(self):
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 10},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["timeline"][0]["events"][0]["agent"], "main")
+
+
+class BuildDispatchTests(unittest.TestCase):
+ """真实数据复现过(TC5 的 dashboard-data-top-slow 会话,sid 01a09ef5...):
+ 修复前 build_dispatch() 把 agent_history 里所有 evidence 以 "dispatch" 或
+ "inbox" 开头的条目一律计数,导致两个真实问题——
+ 1) solo-developer 被上报回声(inbox@report:*)重复计入,真实派发只有 2 次,
+ 却显示成 5;
+ 2) team-lead 显示成一个"被 main 派发的子 agent",但 team-lead 在
+ core/agent_identity.py::normalize_role_name 里本来就和 main 归为一类
+ (它是 CodeBuddy 原生 team 基础设施里 lead session 自己的 mailbox 名,
+ 不是真实存在的子 agent),面板标题明明叫"Main → 子 Agent 派发次数",
+ 混进一个其实等价于 main 自己的假子 agent。"""
+
+ def _real_tc5_agent_history(self):
+ # 逐条取自真实会话 01a09ef5-1c6b-7928-870e-a5056ff360e1 的 .state.json。
+ return [
+ {"ts": 1.0, "agent": "solo-developer", "evidence": "dispatch@Agent<-main"},
+ {"ts": 2.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 3.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ {"ts": 4.0, "agent": "solo-developer", "evidence": "inbox@dispatch:solo-developer"},
+ {"ts": 5.0, "agent": "main", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 6.0, "agent": "main", "evidence": "inbox@handoff:solo-developer->main"},
+ {"ts": 7.0, "agent": "solo-developer", "evidence": "dispatch@SendMessage<-main"},
+ {"ts": 8.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ ]
+
+ def test_real_tc5_history_excludes_team_lead_and_report_echoes(self):
+ state = {"01a09ef5": {"agent_history": self._real_tc5_agent_history()}}
+ rows = bdd.build_dispatch(state)
+ # team-lead(main 的别名)完全不出现;solo-developer 只数真正代表新派发的
+ # 3 条证据(2 条工具触发的 dispatch@ + 1 条 inbox 独立确认的 dispatch:),
+ # 2 条上报回声(inbox@report:*)不计入。
+ self.assertEqual(rows, [{"agent": "solo-developer", "count": 3}])
+
+ def test_inbox_dispatch_evidence_alone_is_still_counted(self):
+ """inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)是原生 team
+ 基础设施里唯一能感知到、但没有经过 Agent/Task 工具调用拦截到的派发方式
+ (例如 team-lead 用 mailbox 直接投递任务),必须保留,不能因为过滤
+ report/handoff 回声就连这类真实派发信号也一起丢掉。"""
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "architect", "evidence": "inbox@dispatch:architect"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [{"agent": "architect", "count": 1}])
+
+ def test_report_and_handoff_evidence_alone_are_not_dispatches(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "developer", "evidence": "inbox@report:developer"},
+ {"ts": 2.0, "agent": "test-engineer", "evidence": "inbox@handoff:developer->test-engineer"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+ def test_team_lead_is_excluded_even_without_report_noise(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-main"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.claude/skills/agent-observability/tests/test_cls_sink.py b/.claude/skills/agent-observability/tests/test_cls_sink.py
new file mode 100644
index 00000000..2da9d6a1
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_cls_sink.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import cls_sink, emitter # type: ignore
+
+
+class CLSSinkTests(unittest.TestCase):
+ def _write_cls_env(self, root: Path, *extra_lines: str) -> None:
+ lines = [
+ "CLS_TOPIC_ID=test-topic-id",
+ "CLS_ENDPOINT=cls.internal.tencentcloudapi.com",
+ "CLS_SERVICE_NAME=agent-observability",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=20",
+ *extra_lines,
+ ]
+ (root / ".env").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+ def test_load_config_supports_cls_and_tc_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "TC_SECRET_ID=test-secret-id",
+ "TC_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertTrue(config.enabled)
+ self.assertEqual(config.endpoint, "cls.internal.tencentcloudapi.com")
+ self.assertEqual(config.topic_id, "test-topic-id")
+ self.assertEqual(config.secret_id, "test-secret-id")
+ self.assertEqual(config.secret_key, "test-secret-key")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.service_name, "agent-observability")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_load_config_supports_tencentcloud_scoped_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(
+ os.environ,
+ {
+ "TENCENTCLOUD_SECRET_ID_438167613": "scoped-secret-id",
+ "TENCENTCLOUD_SECRET_KEY_438167613": "scoped-secret-key",
+ },
+ clear=True,
+ ):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "scoped-secret-id")
+ self.assertEqual(config.secret_key, "scoped-secret-key")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_mirror_record_invokes_node_uploader(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=0, stdout="", stderr="")) as run, \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-1"}, cwd=td)
+
+ self.assertTrue(ok)
+ run.assert_called_once()
+ payload = json.loads(run.call_args.kwargs["input"])
+ self.assertEqual(payload["records"][0]["event"], "tool")
+ self.assertEqual(payload["topicId"], "test-topic-id")
+ self.assertEqual(payload["secretToken"], "")
+
+ def test_load_config_requires_credentials_from_env(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "")
+ self.assertEqual(config.secret_key, "")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertFalse(config.ready)
+
+ def test_load_config_reads_secret_token_aliases(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "TC_SESSION_TOKEN=test-session-token",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_token, "test-session-token")
+
+ def test_load_config_supports_timeout_override(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=45",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.timeout_seconds, 45)
+
+ def test_mirror_record_writes_debug_when_uploader_fails(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=1, stdout="", stderr="boom")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-2"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertFalse(ok)
+ self.assertEqual(entries[-1]["stage"], "uploader_failed")
+ self.assertEqual(entries[-1]["stderr"], "boom")
+ self.assertEqual(entries[-1]["timeout_seconds"], 20)
+
+ def test_mirror_record_writes_success_debug_when_uploader_succeeds(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(True, "ok")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-3"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertTrue(ok)
+ self.assertEqual(entries[0]["stage"], "uploader_start")
+ self.assertEqual(entries[-1]["stage"], "uploader_ok")
+ self.assertEqual(entries[-1]["method"], "python_api_v3")
+
+ def test_emit_keeps_local_log_when_cls_push_raises(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+ with mock.patch.object(emitter.cls_sink, "mirror_record", side_effect=RuntimeError("boom")):
+ emitter.emit(log_path, {"event": "start", "sid": "s-emit"})
+
+ records = [json.loads(line) for line in log_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0]["event"], "start")
+ self.assertEqual(records[0]["sid"], "s-emit")
diff --git a/.claude/skills/agent-observability/tests/test_collector.py b/.claude/skills/agent-observability/tests/test_collector.py
new file mode 100644
index 00000000..05547f06
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_collector.py
@@ -0,0 +1,715 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, agentlens, collector, emitter, runtime, state as st # type: ignore
+
+
+class CollectorTests(unittest.TestCase):
+ def test_cost_of_uses_known_model_price_table(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ cost = emitter.cost_of(tokens, "gpt-4o")
+ self.assertIsNotNone(cost)
+ self.assertGreaterEqual(cost, 0.0)
+
+ def test_cost_of_returns_none_for_unknown_model(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ self.assertIsNone(emitter.cost_of(tokens, "unknown-model"))
+
+ def test_emit_adds_codebuddy_cli_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "codebuddy-cli")
+
+ def test_emit_preserves_explicit_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source", "data_source": "manual"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "manual")
+
+ def test_emit_session_duration_uses_first_log_ts_when_state_was_recreated(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ log_path = root / "metrics.ndjson"
+ state_path = root / ".state.json"
+ log_path.write_text(
+ json.dumps({"event": "start", "sid": "s-duration", "ts": 100.0}) + "\n",
+ encoding="utf-8",
+ )
+ state_path.write_text(
+ json.dumps({"s-duration": {"started_at": 190.0}}, ensure_ascii=False),
+ encoding="utf-8",
+ )
+
+ emitter.emit(log_path, {"event": "usage", "sid": "s-duration", "ts": 200.0, "tokens": {"input": 1, "output": 2}})
+
+ records = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
+ self.assertEqual(records[-1]["session_duration_sec"], 100.0)
+
+ def test_emit_session_duration_starts_at_zero_without_prior_log_or_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-new", "ts": 100.0})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["session_duration_sec"], 0.0)
+
+ def test_parse_transcript_tail_extracts_tokens(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ out = collector.parse_transcript_tail(str(transcript), max_lines=20)
+ self.assertIsInstance(out, dict)
+ self.assertIsInstance(out.get("tokens"), dict)
+ self.assertEqual(out["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(out["tokens"].get("output_tokens"), 120)
+ usage_records = out.get("usage_records") or []
+ tool_records = out.get("tool_records") or []
+ self.assertEqual(len(usage_records), 3)
+ self.assertEqual(usage_records[0]["tokens"].get("input_tokens"), 1820)
+ self.assertEqual(usage_records[-1]["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(usage_records[0].get("message_id"), "msg-001")
+ self.assertEqual(usage_records[-1].get("message_id"), "msg-003")
+ self.assertLess(usage_records[0]["offset"], usage_records[-1]["offset"])
+ self.assertEqual(len(tool_records), 8)
+ self.assertEqual(tool_records[0]["tool"], "read_file")
+ self.assertEqual(tool_records[0]["message_id"], "msg-001")
+ self.assertEqual(tool_records[0]["next_message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["tool"], "Bash")
+ self.assertEqual(tool_records[-1]["message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["next_message_id"], "msg-003")
+
+ def test_realtime_usage_is_request_level_and_dedupes_across_phase(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-transcript"
+
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=str(transcript),
+ max_lines=20,
+ )
+ entries = scan.get("entries") or []
+
+ self.assertEqual(len(entries), 3)
+ self.assertEqual(entries[0]["tokens"]["input"], 1820)
+ self.assertGreater(entries[0]["offset"], 0)
+ self.assertEqual(entries[0]["message_id"], "msg-001")
+ self.assertEqual(entries[1]["tokens"]["input"], 2100)
+ self.assertEqual(entries[1]["tokens"]["total"], 2158)
+ self.assertEqual(len(scan.get("tool_records") or []), 8)
+
+ usage_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Read",
+ entry=entries[0],
+ )
+ stop_key = collector.build_transcript_event_key(
+ kind="stop",
+ tool="__stop__",
+ entry=entries[0],
+ )
+ other_tool_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Bash",
+ entry=entries[0],
+ )
+
+ self.assertEqual(usage_key, stop_key)
+ self.assertEqual(usage_key, other_tool_key)
+ self.assertTrue(st.claim_transcript_event(state_path, sid, usage_key, str(transcript)))
+ self.assertFalse(st.claim_transcript_event(state_path, sid, stop_key, str(transcript)))
+
+ def test_find_current_tool_message_id_prefers_transcript_tool_records(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool-mid"
+
+ read_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Read",
+ )
+ bash_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Bash",
+ )
+
+ self.assertEqual(read_mid, "msg-002")
+ self.assertEqual(bash_mid, "msg-003")
+
+ def test_resolve_subagent_transcript_alias_and_tool_context(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ alias_session_id = "subagent-session-1"
+ subagent = subagents / "agent-a.jsonl"
+ main.write_text("", encoding="utf-8")
+ subagent.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "type": "message",
+ "sessionId": alias_session_id,
+ "providerData": {"agent": "Explore"},
+ }
+ ),
+ json.dumps(
+ {
+ "type": "function_call",
+ "sessionId": alias_session_id,
+ "name": "Grep",
+ "callId": "call-1",
+ "providerData": {
+ "agent": "Explore",
+ "messageId": "msg-sub-001",
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ aliased_path = str(root / f"{alias_session_id}.jsonl")
+ resolved = collector.resolve_transcript_path_alias(sid, aliased_path)
+ self.assertEqual(resolved, str(subagent.resolve()))
+
+ state_path = root / ".state.json"
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=aliased_path,
+ tool_name="Grep",
+ )
+ self.assertEqual(
+ context,
+ {
+ "message_id": "msg-sub-001",
+ "transcript_path": str(subagent.resolve()),
+ "agent": "explore",
+ "tool_details": {"call_id": "call-1"},
+ },
+ )
+
+ def test_find_current_tool_context_prefers_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ early = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=1.2,
+ )
+ late = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(early["message_id"], "msg-early")
+ self.assertEqual(late["message_id"], "msg-late")
+
+ def test_find_current_tool_context_claims_distinct_call_ids_with_same_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "arguments": "{\"command\":\"echo one\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "arguments": "{\"command\":\"echo two\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result one"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result two"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ first = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ second = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ third = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+
+ self.assertEqual(first["message_id"], "msg-shared")
+ self.assertEqual(second["message_id"], "msg-shared")
+ self.assertNotEqual(first["tool_details"]["call_id"], second["tool_details"]["call_id"])
+ self.assertIn("arguments", first["tool_details"])
+ self.assertIn("result_content", first["tool_details"])
+ self.assertEqual(third, {"duplicate": True})
+
+ def test_find_fallback_usage_event_prefers_latest_matching_usage(self):
+ tool_event = {
+ "tool": "Bash",
+ "agent": "main",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ usage_events = [
+ {
+ "agent": "main",
+ "tool": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-old",
+ "source_offset": 100,
+ },
+ {
+ "agent": "main",
+ "tool": "Bash",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-current",
+ "source_offset": 200,
+ },
+ ]
+
+ matched = collector.find_fallback_usage_event(tool_event, usage_events)
+ self.assertIsNotNone(matched)
+ self.assertEqual(matched["message_id"], "msg-current")
+
+ def test_find_current_tool_context_prefers_explicit_call_id_over_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {
+ "messageId": "msg-early",
+ "toolResult": {"content": "early result"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {
+ "messageId": "msg-late",
+ "toolResult": {"content": "late result"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-call-id-priority",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ call_id="call-early",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(context["message_id"], "msg-early")
+ self.assertEqual(context["tool_details"]["call_id"], "call-early")
+ self.assertEqual(context["tool_details"]["result_content"], "early result")
+
+ def test_find_current_tool_context_uses_next_message_id_when_available(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-tool"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-tool",
+ "toolResult": {"content": "<tool_use_error>missing</tool_use_error>"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 2000,
+ "type": "assistant",
+ "providerData": {"messageId": "msg-next"},
+ "content": "next step",
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-next-mid",
+ transcript_path=str(transcript),
+ tool_name="Read",
+ call_id="call-1",
+ )
+
+ self.assertEqual(context["message_id"], "msg-next")
+ self.assertEqual(context["tool_details"]["original_message_id"], "msg-tool")
+ self.assertEqual(context["tool_details"]["next_message_id"], "msg-next")
+ self.assertTrue(context["tool_details"]["message_id_reassigned"])
+
+ def test_flush_pending_tool_events_emits_after_transcript_catches_up(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ state_path = root / ".state.json"
+ log_path = root / "metrics.ndjson"
+ transcript = root / "session.jsonl"
+ transcript.write_text("", encoding="utf-8")
+ sid = "s-pending"
+
+ tool_event = {
+ "event": "tool",
+ "sid": sid,
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 42,
+ "transcript_path": str(transcript),
+ "turn_id": "turn-1",
+ "ts": 1.2,
+ "skill": [],
+ "rule": [],
+ "cwd": str(ROOT),
+ }
+ st.append_pending_tool_emit(state_path, sid, tool_event)
+
+ transcript.write_text(
+ json.dumps(
+ {
+ "timestamp": 1300,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-later"},
+ }
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ emitted_calls: list[dict[str, object]] = []
+ original_emit_post_step = agentlens.emit_post_step
+ try:
+ agentlens.emit_post_step = lambda **kwargs: emitted_calls.append(kwargs)
+ runtime.flush_pending_tool_events(
+ state_path=state_path,
+ log_path=log_path,
+ sid=sid,
+ )
+ finally:
+ agentlens.emit_post_step = original_emit_post_step
+
+ self.assertEqual(st.get_pending_tool_emits(state_path, sid), [])
+ lines = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines() if line.strip()]
+ self.assertEqual(len(lines), 1)
+ self.assertEqual(lines[0]["message_id"], "msg-later")
+ self.assertEqual(len(emitted_calls), 1)
+ self.assertEqual(emitted_calls[0]["tool_event"]["message_id"], "msg-later")
+
+ def test_related_transcript_paths_include_subagents(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ sub_a = subagents / "agent-a.jsonl"
+ sub_b = subagents / "agent-b.jsonl"
+ for path in (main, sub_a, sub_b):
+ path.write_text("", encoding="utf-8")
+
+ paths = collector.related_transcript_paths(sid, str(main))
+
+ self.assertEqual(
+ paths,
+ [
+ str(main.resolve()),
+ str(sub_a.resolve()),
+ str(sub_b.resolve()),
+ ],
+ )
+
+ def test_subagent_transcript_maps_to_role_name(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-27e41af0.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for knowledge-engineer\\">"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "knowledge-engineer",
+ )
+
+ def test_subagent_transcript_prefers_assignment_role_over_general_provider_agent(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-165e361f.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"type":"message","providerData":{"agent":"general-purpose"},"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for developer\\">\\n待命。\\n你在本 devflow 中的角色:developer(开发角色)"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "developer",
+ )
+
+ def test_inbox_standby_assignment_does_not_switch_current_agent(self):
+ messages = [
+ {
+ "mailbox_name": "architect",
+ "mailbox_role": "architect",
+ "from_role": "main",
+ "summary": "Initial task assignment for architect",
+ "text": "待命,监听 main 唤醒。",
+ "payload": None,
+ "is_shutdown": False,
+ "is_standby": True,
+ }
+ ]
+ current, dispatched, meta = agent_identity.infer_identity_from_messages(messages)
+ self.assertIsNone(current)
+ self.assertIsNone(dispatched)
+ self.assertEqual(meta["messages_seen"], 1)
+
+ def test_record_pre_post_duration(self):
+ with tempfile.TemporaryDirectory() as td:
+ pending = Path(td) / ".pending.json"
+ pre = {"session_id": "s1", "tool_name": "read_file"}
+ post = {"session_id": "s1", "tool_name": "read_file"}
+ collector.record_pre(pending, pre)
+ time.sleep(0.02)
+ ms = collector.record_post(pending, post)
+ self.assertIsInstance(ms, int)
+ self.assertGreaterEqual(ms, 0)
+
+ def test_record_tool_usage_counts_skill_and_rule(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool"
+ # 先确保 session 结构
+ s = st.load_state(state_path)
+ st.ensure_session(s, sid)
+ st.save_state(state_path, s)
+
+ data = {
+ "tool_name": "use_skill",
+ "tool_input": {"command": "pdf", "filePath": "README.md"},
+ }
+ skills_meta = {"pdf": {"source": "user", "version": "1.0.0"}}
+ rules_meta = {
+ "security": {"source": "project", "alwaysApply": True, "enabled": True, "globs": []}
+ }
+ collector.record_tool_usage(
+ state_path=state_path,
+ sid=sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent="main",
+ collect_skills=True,
+ )
+
+ skills_usage, rules_usage = collector.get_session_usage(state_path, sid)
+ self.assertEqual(skills_usage.get("pdf", {}).get("count"), 1)
+ self.assertEqual(rules_usage.get("security", {}).get("count"), 1)
+
+ def test_step_span_registry_is_idempotent(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-step"
+ carrier = {"traceparent": "00-" + ("1" * 32) + "-" + ("2" * 16) + "-01"}
+ st.begin_turn(state_path, sid, "turn-1", carrier)
+
+ first = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("3" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+ second = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("4" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+
+ self.assertEqual(first, second)
+ self.assertEqual(st.get_step_span_carrier(state_path, sid, "main", "msg-001"), first)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.claude/skills/agent-observability/tests/test_devflow.py b/.claude/skills/agent-observability/tests/test_devflow.py
new file mode 100644
index 00000000..9ad0a7fd
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_devflow.py
@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, devflow, state as st # type: ignore
+
+
+def _write_team_config(team_dir: Path, *, lead_session_id: str, member_cwd: str) -> None:
+ team_dir.mkdir(parents=True, exist_ok=True)
+ (team_dir / "config.json").write_text(
+ json.dumps({
+ "leadSessionId": lead_session_id,
+ "createdAt": 1,
+ "members": [{"cwd": member_cwd}],
+ }),
+ encoding="utf-8",
+ )
+
+
+class TaskSlugFromTeamDirTests(unittest.TestCase):
+ def test_strips_fixed_prefix(self):
+ team_dir = Path("/tmp/.codebuddy/teams/multi-agents-devflow-my-task_20260911_1200")
+ self.assertEqual(devflow.task_slug_from_team_dir(team_dir), "my-task_20260911_1200")
+
+ def test_returns_none_for_non_devflow_team_dir(self):
+ team_dir = Path("/tmp/.codebuddy/teams/some-other-team")
+ self.assertIsNone(devflow.task_slug_from_team_dir(team_dir))
+
+
+class StageSnapshotTests(unittest.TestCase):
+ def test_projects_expected_fields_and_ignores_non_dict_stage(self):
+ workflow_state = {
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "run_mode": "auto",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0, "review_result": None},
+ "CODE-REVIEW": {"status": "failed", "executor": "code-reviewer", "retry_count": 1, "review_result": "failed"},
+ "garbage": "not-a-dict",
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["current_stage"], "TASK-03")
+ self.assertEqual(snap["size_class"], "medium")
+ self.assertNotIn("garbage", snap["stages"])
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["retry_count"], 1)
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["review_result"], "failed")
+
+ def test_handles_missing_or_malformed_input(self):
+ self.assertEqual(devflow.stage_snapshot(None), {})
+ self.assertEqual(devflow.stage_snapshot({"stages": "not-a-dict"}), {
+ "current_stage": None, "size_class": None, "run_mode": None,
+ "schema_version": None, "execution_mode": None, "host_adapter": None, "run_id": None,
+ "stages": {},
+ })
+
+
+class DiffStageChangesTests(unittest.TestCase):
+ def test_first_observation_produces_no_changes(self):
+ curr = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(None, curr), [])
+
+ def test_detects_retry_count_increase_as_a_change(self):
+ prev = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "in_progress", "retry_count": 0}}})
+ curr = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "failed", "retry_count": 1, "review_result": "failed"}}})
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "CODE-REVIEW")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["review_result"], "failed")
+
+ def test_unchanged_stage_produces_no_entry(self):
+ snap = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(snap, snap), [])
+
+
+class PtIdFromTranscriptPathTests(unittest.TestCase):
+ def test_extracts_pt_track_from_subagent_transcript_name(self):
+ path = "/tmp/session-123/subagents/sub-developer-PT-01.jsonl"
+ self.assertEqual(agent_identity.pt_id_from_transcript_path(path), "PT-01")
+
+ def test_returns_none_for_non_subagent_or_non_pt_transcript(self):
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123.jsonl"))
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123/subagents/architect.jsonl"))
+
+
+class ResolveAndDiffTests(unittest.TestCase):
+ def test_returns_none_when_no_devflow_team_found(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ result = devflow.resolve_and_diff(state_path, "sid-1", "/tmp/some-project")
+ self.assertIsNone(result)
+ state = st.load_state(state_path)
+ self.assertIsNone(state["sid-1"]["_devflow"]["context"])
+
+ def test_late_appearing_devflow_run_is_discovered_on_a_later_call(self):
+ """真实 bug 回归测试:同一个长生命周期 sid,会话开始时探测不到 devflow
+ (此时既没有 team 目录也没有 artifacts/),之后才真正跑起 devflow
+ (比如通过 Agent 工具后台 spawn,而不是从一开始就是独立 team 成员 sid)。
+ 早期的"没找到"不能被永久缓存,必须在 artifacts/ 出现之后的下一次调用里发现它。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ project_dir.mkdir()
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-long-lived"
+
+ # 会话早期:还没有任何 devflow 痕迹。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNone(first)
+
+ # 同一个 sid,会话中途才出现 devflow 产物(没有 team 目录,走 artifacts 扫描兜底)。
+ artifacts_dir = project_dir / "artifacts" / "late-appearing-task_20260914_1200"
+ artifacts_dir.mkdir(parents=True)
+ (artifacts_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "current_stage": "SOLO", "size_class": "small",
+ "stages": {"SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(second)
+ self.assertEqual(second["task_slug"], "late-appearing-task_20260914_1200")
+
+ def test_end_to_end_with_fake_team_and_workflow_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ project_dir = root / "project"
+ project_dir.mkdir()
+ config_home = root / "codebuddy-home"
+ teams_root = config_home / "teams"
+ team_dir = teams_root / "multi-agents-devflow-fix-token-bypass_20260911_0900"
+ _write_team_config(team_dir, lead_session_id="sid-42", member_cwd=str(project_dir))
+
+ artifacts_dir = project_dir / "artifacts" / "fix-token-bypass_20260911_0900"
+ artifacts_dir.mkdir(parents=True)
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(config_home)
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-42"
+
+ # 第一次调用:发现 devflow 上下文,但因为是首次观测不产出 changes。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "fix-token-bypass_20260911_0900")
+ self.assertEqual(first["current_stage"], "TASK-03")
+ self.assertEqual(first["changes"], [])
+
+ # workflow-state.json 更新:TASK-03 打回重试。
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "failed", "executor": "developer", "retry_count": 1},
+ },
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["stage"], "TASK-03")
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+
+ # 没有变化时,第三次调用应该不再产出 changes。
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["changes"], [])
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+class PortableSchemaStageSnapshotTests(unittest.TestCase):
+ """Portable(v2.0)用 `executor_role` 而不是 `executor`,且没有 `review_result`。"""
+
+ def test_reads_executor_role_and_top_level_execution_context(self):
+ workflow_state = {
+ "version": "2.0",
+ "current_stage": "IMPLEMENT",
+ "size_class": "medium",
+ "execution_mode": "isolated",
+ "host_adapter": "codebuddy",
+ "run_id": "run-abc",
+ "stages": {
+ "DESIGN": {"status": "completed", "executor_role": "devflow-architect", "retry_count": 0},
+ "IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1},
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["schema_version"], "2.0")
+ self.assertEqual(snap["execution_mode"], "isolated")
+ self.assertEqual(snap["stages"]["DESIGN"]["executor"], "devflow-architect")
+ self.assertEqual(snap["stages"]["IMPLEMENT"]["retry_count"], 1)
+ self.assertIsNone(snap["stages"]["IMPLEMENT"]["review_result"])
+
+ def test_diff_detects_retry_on_portable_shape_same_as_classic(self):
+ prev = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "in_progress", "executor_role": "devflow-developer", "retry_count": 0}},
+ })
+ curr = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1}},
+ })
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "IMPLEMENT")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["executor"], "devflow-developer")
+
+
+class ArtifactsScanFallbackTests(unittest.TestCase):
+ """`topology: spawn` 宿主没有 team 目录,靠扫 artifacts/ 兜底发现 task_slug。"""
+
+ def test_no_artifacts_dir_returns_none(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.assertIsNone(devflow._scan_artifacts_for_active_run(td))
+
+ def test_ignores_non_devflow_json_and_picks_in_progress_run(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ # 不是 devflow 产物的 JSON(没有 stages 字段),不能被误当成一次运行。
+ noise_dir = artifacts / "not-a-devflow-run"
+ noise_dir.mkdir(parents=True)
+ (noise_dir / "workflow-state.json").write_text(json.dumps({"hello": "world"}), encoding="utf-8")
+
+ done_dir = artifacts / "finished-task_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "completed", "stages": {"DESIGN": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "active-task_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "in_progress", "stages": {"IMPLEMENT": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "active-task_20260911_1000")
+ self.assertIsNone(result["team_dir"])
+
+ def test_finished_detection_works_for_classic_schema_without_top_level_status(self):
+ """Classic(v1.3)没有顶层 status 字段,"跑完没跑完"只能看 last_event。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ done_dir = artifacts / "classic-done_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed",
+ "stages": {"SOLO": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "classic-active_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "TASK-02_completed",
+ "stages": {"TASK-02": {"status": "completed"}, "TASK-03": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "classic-active_20260911_1000")
+
+ def test_resolve_and_diff_switches_task_slug_when_a_newer_run_appears(self):
+ """真实 bug 回归测试:同一个长生命周期 sid 先后归属两次不同的 devflow 运行
+ (没有真正 team_create 时的降级场景——第二次 `/start-devflow` 复用了同一个
+ session)。第一次探测缓存下的 task_slug 不能在第二次运行开始后继续沿用;
+ 必须切换到新的那个,而且两个 task_slug 各自的 diff 历史不能互相污染。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-reused-across-two-runs"
+
+ first_dir = project_dir / "artifacts" / "first-task_20260914_0900"
+ first_dir.mkdir(parents=True)
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(first["task_slug"], "first-task_20260914_0900")
+
+ # 同一个 sid,第二次运行出现,且比第一次更新(mtime 更新)。
+ import time
+ time.sleep(0.01)
+ second_dir = project_dir / "artifacts" / "second-task_20260914_1100"
+ second_dir.mkdir(parents=True)
+ (second_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(second["task_slug"], "second-task_20260914_1100")
+ self.assertEqual(second["changes"], []) # 对 second 是首次观测,不产出变更
+
+ # 第一个 task_slug 的历史没有被污染:如果它重新变成"最新"(比如被再次修改),
+ # 应该正确切回,并且不会把 second 的历史错当成 first 的基线。
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+ time.sleep(0.01)
+ first_dir.joinpath("workflow-state.json").touch()
+
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["task_slug"], "first-task_20260914_0900")
+ # first 上一次被观测到时 retry_count 还是 0,现在变成 1——应该被识别为变化,
+ # 而不是被 second 的快照历史污染成"首次观测"或者对不上的 diff。
+ self.assertEqual(len(third["changes"]), 1)
+ self.assertEqual(third["changes"][0]["retry_count"], 1)
+
+ def test_resolve_and_diff_end_to_end_via_artifacts_scan_no_team(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ artifacts_dir = project_dir / "artifacts" / "portable-task_20260911_1100"
+ artifacts_dir.mkdir(parents=True)
+ state_file = artifacts_dir / "workflow-state.json"
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "in_progress", "executor_role": "devflow-code-reviewer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(Path(td) / "empty-codebuddy-home")
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-spawn-1"
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "portable-task_20260911_1100")
+ self.assertEqual(first["schema_version"], "2.0")
+ self.assertEqual(first["execution_mode"], "isolated")
+ self.assertEqual(first["changes"], [])
+
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "failed", "executor_role": "devflow-code-reviewer", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.claude/skills/agent-observability/tests/test_pricing_overrides.py b/.claude/skills/agent-observability/tests/test_pricing_overrides.py
new file mode 100644
index 00000000..75615a36
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_pricing_overrides.py
@@ -0,0 +1,394 @@
+"""自定义模型定价覆盖 + 看板未定价模型提示。
+
+覆盖文件是**人手写的常驻配置**,而且加载失败要静默降级——这类"错了也不许
+报错"的代码最容易在半年后被悄悄改坏(比如有人顺手把 try/except 去掉、把合并
+改成整 key 覆盖、或让降级路径开始 print)。这里把字段级合并、四种/五种降级
+路径、缓存语义、未定价口径、看板聚合与"不重算历史成本"逐条钉住。
+
+两个容易踩的隔离坑,本文件统一在 setUp/tearDown 处理:
+1. `load_prices()` 带 `lru_cache`,不 `clear_price_cache()` 用例之间会串味;
+2. `AOBS_PRICING_OVERRIDES_PATH` 是进程级环境变量,不还原会污染同进程里
+ 其它测试模块(尤其是会真的去读默认覆盖文件的 hook 链路)。
+
+真实日志对账(hy4-preview-ioa / hy3-ioa 的计数)不写进单测:日志会持续增长,
+写死数字会变成 flaky 用例。那部分以人工冒烟的方式在 TASK-04 报告里记录。
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+from core import emitter # type: ignore
+
+OVERRIDES_ENV = "AOBS_PRICING_OVERRIDES_PATH"
+
+
+class _OverridesTestCase(unittest.TestCase):
+ """统一处理环境变量与 `load_prices()` 缓存的隔离。"""
+
+ def setUp(self):
+ self._env_backup = os.environ.get(OVERRIDES_ENV)
+ os.environ.pop(OVERRIDES_ENV, None)
+ emitter.clear_price_cache()
+ self._tmp = tempfile.TemporaryDirectory()
+ self.tmp = Path(self._tmp.name)
+
+ def tearDown(self):
+ # 顺序要紧:先还原 env,再清缓存,最后清目录,避免留下一个指向已删除
+ # 目录的环境变量给下一个用例。
+ if self._env_backup is None:
+ os.environ.pop(OVERRIDES_ENV, None)
+ else:
+ os.environ[OVERRIDES_ENV] = self._env_backup
+ emitter.clear_price_cache()
+ self._tmp.cleanup()
+
+ def use_overrides(self, payload, name: str = "overrides.json") -> Path:
+ """把 payload 写成覆盖文件并指向它(JSON 文本原样写入,便于构造非法输入)。"""
+ path = self.tmp / name
+ text = payload if isinstance(payload, str) else json.dumps(payload)
+ path.write_text(text, encoding="utf-8")
+ os.environ[OVERRIDES_ENV] = str(path)
+ emitter.clear_price_cache()
+ return path
+
+ def pure_builtin(self) -> dict:
+ """"纯内置表"的唯一权威来源——不把 pricing.json 的内容抄进断言里,
+ 否则内置表一调整这里就假红;但内置表本身必须是非空的,否则下面的
+ "降级后 == 纯内置表" 断言会退化成空表比空表。"""
+ builtin = emitter._load_builtin_prices()
+ self.assertTrue(builtin, "内置价格表不应为空,否则降级断言失去意义")
+ self.assertIn("gpt-4o", builtin)
+ return builtin
+
+
+class OverridesPathResolutionTests(_OverridesTestCase):
+ """AC4:路径可覆盖。默认位置刻意放在 skills 树**外**——
+ `scripts/build-classic-hosts.py` 会整棵同步 `.codebuddy/skills`,放树内会让
+ 用户每次改价都产生一次 `--check` drift,并被复制进 .claude/.cursor 宿主包。"""
+
+ def test_env_var_wins_over_default(self):
+ path = self.use_overrides({"zz-model": {"output": 1.0}})
+ self.assertEqual(emitter.resolve_overrides_path(), path)
+
+ def test_tilde_is_expanded(self):
+ os.environ[OVERRIDES_ENV] = "~/aobs-overrides-test.json"
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), Path.home() / "aobs-overrides-test.json")
+
+ def test_unset_falls_back_to_default_path(self):
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_blank_env_falls_back_to_default(self):
+ # 空字符串/纯空白都等同于"没设置",不能变成指向 CWD 的相对路径。
+ os.environ[OVERRIDES_ENV] = " "
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_default_path_is_outside_the_skills_tree(self):
+ default = emitter.DEFAULT_OVERRIDES_PATH
+ self.assertIsNotNone(default)
+ self.assertEqual(
+ default,
+ ROOT.parents[2] / ".codebuddy" / "agent-observability" / "pricing.overrides.json",
+ )
+ self.assertNotIn("skills", default.parts[-3:])
+ self.assertFalse(str(default).startswith(str(ROOT)))
+
+
+class MergePricesTests(unittest.TestCase):
+ """AC2:字段级合并。整 key 覆盖被刻意否决过——漏写字段会把该字段按 0 计,
+ 静默把成本算没,风险高于收益。"""
+
+ def test_explicit_field_overrides_builtin_while_others_are_kept(self):
+ merged = emitter.merge_prices(
+ {"gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25}},
+ {"gpt-4o": {"output": 99.0}},
+ )
+ self.assertEqual(merged["gpt-4o"]["output"], 99.0)
+ self.assertEqual(merged["gpt-4o"]["input"], 2.5)
+ self.assertEqual(merged["gpt-4o"]["cache_read"], 1.25)
+
+ def test_new_model_can_be_added(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-new": {"output": 9.0}})
+ self.assertEqual(merged["zz-new"], {"output": 9.0})
+
+ def test_merge_does_not_mutate_its_arguments(self):
+ base = {"gpt-4o": {"input": 2.5, "output": 10.0}}
+ overrides = {"gpt-4o": {"output": 99.0}}
+ merged = emitter.merge_prices(base, overrides)
+ merged["gpt-4o"]["input"] = 0.0
+ # 内置表是模块级共享数据(lru_cache 之外还有调用方持有引用),
+ # 被就地改过的话一次合并会污染整条 hook 链路。
+ self.assertEqual(base["gpt-4o"], {"input": 2.5, "output": 10.0})
+ self.assertEqual(overrides["gpt-4o"], {"output": 99.0})
+
+ def test_empty_or_none_overrides_return_base_copy(self):
+ base = {"gpt-4o": {"output": 10.0}}
+ self.assertEqual(emitter.merge_prices(base, None), base)
+ self.assertEqual(emitter.merge_prices(base, {}), base)
+
+ def test_none_base_returns_overrides_only(self):
+ self.assertEqual(emitter.merge_prices(None, {"zz-new": {"output": 1.0}}), {"zz-new": {"output": 1.0}})
+
+ def test_non_dict_rows_are_ignored(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-bad": 9.0, "zz-ok": {"output": 2.0}})
+ self.assertNotIn("zz-bad", merged)
+ self.assertEqual(merged["zz-ok"], {"output": 2.0})
+
+
+class LoadPricesOverrideTests(_OverridesTestCase):
+ """AC2 + AC3:加载与降级。"""
+
+ def test_override_applies_field_level_and_adds_model(self):
+ self.use_overrides({"zz-custom": {"input": 1.0, "output": 9.0}, "gpt-4o": {"output": 99.0}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["zz-custom"], {"input": 1.0, "output": 9.0})
+ self.assertEqual(prices["gpt-4o"]["output"], 99.0)
+ self.assertEqual(prices["gpt-4o"]["input"], self.pure_builtin()["gpt-4o"]["input"])
+
+ def test_missing_file_degrades_to_builtin(self):
+ os.environ[OVERRIDES_ENV] = str(self.tmp / "does-not-exist.json")
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_invalid_json_degrades_to_builtin(self):
+ self.use_overrides('{"gpt-4o": {"output": 99.0}')
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_top_level_non_dict_degrades_to_builtin(self):
+ self.use_overrides("[1, 2, 3]")
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_non_numeric_field_is_skipped_but_siblings_apply(self):
+ self.use_overrides({"gpt-4o": {"output": "abc", "input": 3.0}})
+ prices = emitter.load_prices()
+ # 写错一个字段不该把同模型其它字段、其它模型的正确覆盖一起丢掉。
+ self.assertEqual(prices["gpt-4o"]["input"], 3.0)
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_model_with_only_bad_fields_is_dropped_and_stays_unpriced(self):
+ """计划外决策(已在 code review 接受):全坏字段的模型不落表。
+ 若落表成 `{}`,它既算不出成本又不算"未定价",看板上会变成一个查不到
+ 原因的空洞;丢弃后至少能在"模型定价"提醒里暴露出来。"""
+ self.use_overrides({"zz-all-bad": {"output": "abc"}})
+ prices = emitter.load_prices()
+ self.assertNotIn("zz-all-bad", prices)
+ self.assertTrue(emitter.is_unpriced("zz-all-bad"))
+
+ def test_bool_is_not_treated_as_a_price(self):
+ # bool 是 int 的子类,float(True) == 1.0 会静默变成"单价 1 美元"。
+ self.use_overrides({"gpt-4o": {"output": True}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_every_degradation_path_is_silent(self):
+ """静默是刻意的:hook 每次都是新进程,一旦因格式问题 print/抛异常,
+ 整条 hook 链路都会变得不可用。"""
+ for payload in ('{"broken": ', "[1,2,3]", '{"gpt-4o": {"output": "abc"}}', '{"gpt-4o": 1}'):
+ with self.subTest(payload=payload):
+ self.use_overrides(payload)
+ out, err = io.StringIO(), io.StringIO()
+ with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+ prices = emitter.load_prices()
+ self.assertEqual(prices, self.pure_builtin())
+ self.assertEqual(out.getvalue(), "")
+ self.assertEqual(err.getvalue(), "")
+
+ def test_load_prices_is_cached_until_cleared(self):
+ path = self.use_overrides({"zz-cache-model": {"output": 1.0}})
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ path.write_text(json.dumps({"zz-cache-model": {"output": 2.0}}), encoding="utf-8")
+ # 未清缓存:同进程内仍是旧值(hook 是短命进程,这个行为是可接受的)。
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 2.0)
+
+ def test_clear_price_cache_picks_up_env_change(self):
+ self.assertTrue(hasattr(emitter.load_prices, "cache_clear"))
+ self.use_overrides({"zz-a": {"output": 1.0}})
+ self.assertIn("zz-a", emitter.load_prices())
+ self.use_overrides({"zz-b": {"output": 2.0}}, name="second.json")
+ emitter.clear_price_cache()
+ prices = emitter.load_prices()
+ self.assertIn("zz-b", prices)
+ self.assertNotIn("zz-a", prices)
+
+
+class IsUnpricedTests(_OverridesTestCase):
+ """D4:未定价的唯一口径是 `lookup_price(...) is None`。
+ `lookup_price` 会做"最长子串"模糊兜底,所以 `gpt-4o-2024-11-20` 能算出成本,
+ 不该出现在"建议补价"里——口径一旦漂移,用户会去给明明已经命中的模型补价。"""
+
+ def test_unknown_model_is_unpriced(self):
+ self.assertTrue(emitter.is_unpriced("zz-totally-unknown"))
+
+ def test_fuzzy_substring_match_is_not_unpriced(self):
+ self.assertFalse(emitter.is_unpriced("gpt-4o-2024-11-20"))
+
+ def test_missing_or_blank_model_is_unpriced(self):
+ for model in (None, "", " "):
+ with self.subTest(model=model):
+ self.assertTrue(emitter.is_unpriced(model))
+
+ def test_override_makes_a_model_priced(self):
+ self.assertTrue(emitter.is_unpriced("zz-then-priced"))
+ self.use_overrides({"zz-then-priced": {"output": 9.0}})
+ self.assertFalse(emitter.is_unpriced("zz-then-priced"))
+
+
+class BuildUnpricedModelsTests(_OverridesTestCase):
+ """AC5:只看板**统计**,绝不回头重算 cost_usd(D3:覆盖只对新事件生效)。"""
+
+ def _usage(self, model, ts=1.0):
+ return {"event": "usage", "sid": "s1", "ts": ts, "model": model, "tokens": {"input": 1, "output": 1}}
+
+ def test_counts_only_unpriced_usage_events(self):
+ events = [
+ self._usage("zz-unpriced-a", 1.0),
+ self._usage("zz-unpriced-a", 2.0),
+ self._usage("zz-unpriced-b", 3.0),
+ self._usage("gpt-4o-2024-11-20", 4.0), # 模糊命中,不算未定价
+ {"event": "usage", "sid": "s1", "ts": 5.0, "tokens": {"input": 1}}, # model 缺失
+ self._usage(" ", 6.0), # model 空白
+ {"event": "tool", "sid": "s1", "ts": 7.0, "tool": "Bash", "ms": 1}, # 非 usage
+ ]
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [
+ {"name": "zz-unpriced-a", "usageEvents": 2},
+ {"name": "zz-unpriced-b", "usageEvents": 1},
+ ])
+
+ def test_empty_input_returns_empty_list(self):
+ self.assertEqual(bdd.build_unpriced_models([]), [])
+
+ def test_sorted_by_event_count_desc_then_name(self):
+ events = (
+ [self._usage("zz-b", float(i)) for i in range(2)]
+ + [self._usage("zz-a", 9.0)]
+ + [self._usage("zz-c", float(i)) for i in range(2)]
+ )
+ rows = bdd.build_unpriced_models(events)
+ # 计数相同的 zz-b / zz-c 必须按名字定序,否则两次生成的快照无法逐字节比对。
+ self.assertEqual([(r["name"], r["usageEvents"]) for r in rows],
+ [("zz-b", 2), ("zz-c", 2), ("zz-a", 1)])
+
+ def test_pricing_a_model_removes_it_from_the_list(self):
+ events = [self._usage("zz-unpriced-a", 1.0), self._usage("zz-unpriced-b", 2.0)]
+ self.assertEqual(len(bdd.build_unpriced_models(events)), 2)
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [{"name": "zz-unpriced-b", "usageEvents": 1}])
+
+ def test_emitter_import_failure_degrades_to_empty_list(self):
+ """目标机可能没装 emitter 的间接依赖;此时只该退化"未定价"这一项,
+ 看板仍要能出片。"""
+ with mock.patch.object(bdd, "em", None):
+ self.assertEqual(bdd.build_unpriced_models([self._usage("zz-unpriced-a")]), [])
+
+
+class MainSnapshotTests(_OverridesTestCase):
+ """main() 级别:键位、空列表、不重算成本、无覆盖时与改动前一致(AC1)。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 2.0, "model": "gpt-4o-2024-11-20",
+ "tokens": {"input": 100, "output": 10}, "cost_usd": 0.0035, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ ]
+
+ def _run_main(self, root: Path, out_name: str) -> tuple[dict, str]:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text("\n".join(json.dumps(e) for e in self._events()) + "\n", encoding="utf-8")
+ state = root / ".state.json"
+ state.write_text("{}", encoding="utf-8")
+ out = root / out_name
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py", "--project-root", str(root),
+ "--out", str(out), "--metrics-path", str(metrics), "--state-path", str(state)]
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ self.assertIn("wrote ", buf.getvalue())
+ return json.loads(out.read_text("utf-8")), buf.getvalue()
+
+ def test_snapshot_exposes_unpriced_models_right_after_model_costs(self):
+ with tempfile.TemporaryDirectory() as td:
+ data, _ = self._run_main(Path(td), "out.json")
+ keys = list(data.keys())
+ self.assertEqual(keys[keys.index("modelCosts") + 1], "unpricedModels")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual([m["name"] for m in data["modelCosts"]], ["gpt-4o-2024-11-20"])
+
+ def test_no_unpriced_models_yields_empty_list_not_null(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ data, _ = self._run_main(Path(td), "out.json")
+ self.assertEqual(data["unpricedModels"], [])
+
+ def test_override_never_recomputes_already_written_costs(self):
+ """D3 的回归护栏:给未定价模型补价后,只有 unpricedModels 会变,
+ modelCosts / daily / sessions 必须逐字节不变(历史成本不回溯)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ before, _ = self._run_main(root, "before.json")
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ after, _ = self._run_main(root, "after.json")
+ before.pop("generated_at")
+ after.pop("generated_at")
+ self.assertEqual(before["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual(after["unpricedModels"], [])
+ before.pop("unpricedModels")
+ after.pop("unpricedModels")
+ self.assertEqual(before, after)
+
+ def test_broken_override_file_keeps_cli_at_exit_zero_and_silent(self):
+ """AC3 的 CLI 层护栏:覆盖文件坏掉时看板仍然出片(exit 0、stderr 为空),
+ 而不是把整条构建链路搞挂。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self.use_overrides('{"gpt-4o": {"output": 99.0}') # 故意截断的非法 JSON
+ err = io.StringIO()
+ with contextlib.redirect_stderr(err):
+ data, _ = self._run_main(root, "out.json")
+ self.assertEqual(err.getvalue(), "")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+ def test_no_override_file_matches_nonexistent_override_path(self):
+ """AC1 的核心回归:不传覆盖文件时价格表就是纯内置表,
+ 与"指向一个不存在的路径"的输出完全一致(忽略 generated_at)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ unset, _ = self._run_main(root, "unset.json")
+ os.environ[OVERRIDES_ENV] = str(root / "nope.json")
+ emitter.clear_price_cache()
+ missing, _ = self._run_main(root, "missing.json")
+ unset.pop("generated_at")
+ missing.pop("generated_at")
+ self.assertEqual(unset, missing)
+ self.assertEqual(unset["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.claude/skills/agent-observability/tests/test_runtime_flow.py b/.claude/skills/agent-observability/tests/test_runtime_flow.py
new file mode 100644
index 00000000..7bd143ba
--- /dev/null
+++ b/.claude/skills/agent-observability/tests/test_runtime_flow.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import runtime # type: ignore
+
+
+class RuntimeFlowTests(unittest.TestCase):
+ def test_resolve_active_agent_prefers_inbox_inferred_agent_when_available(self):
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ with mock.patch.object(runtime.agent_identity, "merge_agent_identity_from_inbox", return_value=("qa", "developer")) as merge_identity:
+ active, dispatched = runtime.agent_identity.resolve_active_agent_for_event(
+ state_path=state_path,
+ sid="s-inbox",
+ cwd=td,
+ data=data,
+ )
+
+ self.assertEqual(active, "qa")
+ self.assertEqual(dispatched, "developer")
+ merge_identity.assert_called_once()
+
+ def test_handle_post_routes_through_expected_collaborators(self):
+ data = {
+ "session_id": "s-runtime",
+ "cwd": "/tmp/demo",
+ "tool_name": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ with tempfile.TemporaryDirectory() as td:
+ with mock.patch.object(runtime, "build_runtime_paths") as mock_paths, \
+ mock.patch.object(runtime.collector, "record_post", return_value=12), \
+ mock.patch.object(runtime.collector, "load_cached_inventory", return_value=({}, {})), \
+ mock.patch.object(runtime.scanner, "scan_skills_and_rules", return_value=({}, {})), \
+ mock.patch.object(runtime.collector, "cache_inventory"), \
+ mock.patch.object(runtime.collector, "record_tool_usage", return_value=([], [])), \
+ mock.patch.object(runtime.agent_identity, "resolve_active_agent_for_event", return_value=("main", None)), \
+ mock.patch.object(runtime, "current_turn_id", return_value="turn-1"), \
+ mock.patch.object(runtime.collector, "extract_tool_call_id", return_value=None), \
+ mock.patch.object(runtime, "flush_pending_tool_events"), \
+ mock.patch.object(runtime.collector, "find_current_tool_context", return_value=None), \
+ mock.patch.object(runtime.collector, "related_transcript_paths", return_value=["/tmp/demo.jsonl"]), \
+ mock.patch.object(runtime, "emit_transcript_events", return_value=[]), \
+ mock.patch.object(runtime.collector, "find_fallback_usage_event", return_value=None), \
+ mock.patch.object(runtime.st, "append_pending_tool_emit"), \
+ mock.patch.object(runtime.agentlens, "emit_post_step"):
+ mock_paths.return_value = runtime.RuntimePaths(
+ base_dir=Path(td),
+ state_path=Path(td) / ".state.json",
+ pending_path=Path(td) / ".pending.json",
+ log_path=Path(td) / "metrics.ndjson",
+ )
+ runtime.handle_post(data)
+
+ def test_main_dispatches_supported_phase_to_handler(self):
+ with mock.patch.object(runtime, "handle_post") as handle_post, \
+ mock.patch.object(runtime.collector, "read_stdin_json", return_value={"session_id": "s1"}):
+ rc = runtime.main(["post"])
+ self.assertEqual(rc, 0)
+ handle_post.assert_called_once()
diff --git a/.codebuddy/runtime/workflow-state-spec.md b/.codebuddy/runtime/workflow-state-spec.md
index a826c2eb..264e306a 100644
--- a/.codebuddy/runtime/workflow-state-spec.md
+++ b/.codebuddy/runtime/workflow-state-spec.md
@@ -118,6 +118,8 @@ failed → in_progress(重试)
**Leader 汇总时**:`summary.status="completed"` + `summary.report_path` + `summary.completed_at=now`
+**任一角色判定自身失败时** ⭐:`status="failed"` + `stages[当前阶段].retry_count = (原值 or 0) + 1` + `last_error=<失败原因>` + `completed_at=now` + `last_event="TASK-XX_failed"`。`retry_count` 只能由失败角色自己在这一步递增,不得由 Main Agent 代写;Main Agent 在调度自检时只读取该值判断重试或暂停(见"调度自检"章节),不修改它。
+
## 初始化协议
Main Agent 从模板创建 → 填充 `task_id`/`task_slug`/`run_mode`/`runtime_mode`/`project_config` → Phase 0 3 维度打分写入 `size_class` → `current_stage="PHASE-0"` → `last_event="workflow_initialized"`
diff --git a/.codebuddy/settings.json b/.codebuddy/settings.json
index 84f2a6ae..a1238c1f 100644
--- a/.codebuddy/settings.json
+++ b/.codebuddy/settings.json
@@ -1,5 +1,27 @@
{
"hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh session-start",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh user-prompt-submit",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
"PreToolUse": [
{
"matcher": "Bash",
@@ -12,7 +34,7 @@
]
},
{
- "matcher": "send_message",
+ "matcher": "SendMessage",
"hooks": [
{
"type": "command",
@@ -20,6 +42,39 @@
"timeout": 10
}
]
+ },
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh pre",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh post",
+ "timeout": 30
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh stop",
+ "timeout": 30
+ }
+ ]
}
]
}
diff --git a/.codebuddy/skills/agent-observability/SKILL.md b/.codebuddy/skills/agent-observability/SKILL.md
new file mode 100644
index 00000000..8bff9f0c
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: agent-observability
+description: Add or maintain CodeBuddy hook observability for projects that need local metrics for tool latency, transcript token usage, session cost, and multi-agent trace attribution. Use when wiring hook-based telemetry, debugging missing usage events, and validating AgentLens state.
+---
+
+## Workflow
+
+1. Merge `templates/settings-hook.json` into the user or project `settings.json`.
+2. Keep hook entries command-only and keep timeouts around 5 to 10 seconds.
+3. Run a normal CodeBuddy session and inspect `logs/metrics.ndjson`.
+4. Inspect `logs/.state.json` when usage replay, offsets, or AgentLens turn state look wrong.
+5. Keep the runtime generic and verify output from `metrics.ndjson` and `.state.json`.
+
+## Read Next
+
+- Read `references/quickstart.md` for setup and smoke-test steps.
+- Read `references/schema-v2.md` when you need field definitions or sidecar state shape.
+## Key Files
+
+- `scripts/main.py`: hook entrypoint for `session-start`, `user-prompt-submit`, `pre`, `post`, and `stop`
+- `scripts/run_hook.sh`: stable shell wrapper for CodeBuddy hook commands
+- `scripts/core/collector.py`: transcript parsing, pre/post pairing, and session usage recording
+- `scripts/core/agentlens.py`: AgentLens trace emission and agent or step grouping
+- `scripts/core/state.py`: persisted hook state, offsets, and AgentLens sidecar state
+- `scripts/core/devflow.py`: optional devflow-awareness — detects a `multi-agents-devflow-*` team, reads `workflow-state.json`, and emits `stage_transition` events. No-ops entirely on non-devflow projects.
+- `templates/settings-hook.json`: hook wiring template
+
+## Output Contract
+
+- Always emit `event`, `sid`, and `ts`.
+- Emit `tool` for per-call latency and `usage` for transcript-derived token and cost events.
+- Emit `stop` for end-of-session flush.
+- Never block the main hook flow; hook exits must stay `0`.
diff --git a/.codebuddy/skills/agent-observability/config/pricing.json b/.codebuddy/skills/agent-observability/config/pricing.json
new file mode 100644
index 00000000..59d8e58c
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/config/pricing.json
@@ -0,0 +1,39 @@
+{
+ "claude-opus-4.8": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.7": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.6": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-sonnet-4.6": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4.5": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-7-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-5-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-haiku-4.5": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-3-5-haiku": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-haiku-4": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "gpt-5.5-fast": {"input": 12.5, "output": 75.0, "cache_read": 1.25, "cache_write": 12.5},
+ "gpt-5.5": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4-fast": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4": {"input": 2.5, "output": 15.0, "cache_read": 0.25, "cache_write": 2.5},
+ "gpt-5.3-codex": {"input": 1.75, "output": 14.0, "cache_read": 0.175, "cache_write": 1.75},
+ "gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25, "cache_write": 2.5},
+ "gpt-4o-mini": {"input": 0.15, "output": 0.6, "cache_read": 0.075, "cache_write": 0.15},
+ "gemini-3.5-flash": {"input": 1.5, "output": 9.0, "cache_read": 0.15, "cache_write": 1.5},
+ "gemini-3.1-pro": {"input": 2.0, "output": 12.0, "cache_read": 0.2, "cache_write": 2.0},
+ "gemini-3.1-flash-lite": {"input": 0.25, "output": 1.5, "cache_read": 0.025, "cache_write": 0.25},
+ "gemini-3-flash": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "gemini-2": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "glm-5.1": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "glm-5v-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "kimi-k2.6": {"input": 0.929, "output": 3.857, "cache_read": 0.157, "cache_write": 0.929},
+ "kimi-k2.5": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "kimi": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "deepseek-v4-pro": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek-v4-flash": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "deepseek-v4": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "minimax-m2.7": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3},
+ "minimax": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3}
+}
diff --git a/.codebuddy/skills/agent-observability/logs/.gitkeep b/.codebuddy/skills/agent-observability/logs/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/.codebuddy/skills/agent-observability/references/quickstart.md b/.codebuddy/skills/agent-observability/references/quickstart.md
new file mode 100644
index 00000000..72ea7bfb
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/references/quickstart.md
@@ -0,0 +1,195 @@
+## Quickstart
+
+### 安装
+
+将 `templates/settings-hook.json` 合并到 `~/.codebuddy/settings.json` 或 `<project>/.codebuddy/settings.json`。
+
+必须启用 hooks:`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`。
+
+### 查看输出
+
+完成一次正常会话后检查:
+- `.codebuddy/skills/agent-observability/logs/metrics.ndjson`
+- `.codebuddy/skills/agent-observability/logs/.state.json`
+
+### 指定数据源路径(可选)
+
+`build_dashboard_data.py` 默认从 `<skill_root>/logs/metrics.ndjson` 与 `<skill_root>/logs/.state.json` 读取,**不传参数时行为完全不变**。
+
+如需从其它位置读取,可用 `--metrics-path` / `--state-path` 覆盖:
+
+```bash
+python3 scripts/build_dashboard_data.py \
+ --metrics-path ~/Downloads/metrics.ndjson \
+ --state-path ~/Downloads/.state.json \
+ --out dashboard/dashboard-data.json
+```
+
+注意:
+
+- 两个参数都留空(或省略)时回退到 `<skill_root>/logs/` 下的默认文件。
+- 路径支持 `~` 展开(如上例的 `~/Downloads/...`)。
+- 输出 `dashboard-data.json` 的 `source.metrics_ndjson` / `source.state_json` 会**如实反映实际读取到的路径**,覆盖后自然指向你给定的文件,便于核对数据来源。
+
+重点字段:
+- `event=tool`:工具耗时、`skill`、`rule`
+- `event=usage`:`tokens`、`model`、`cost_usd`
+- `event=stop`:会话尾部 flush 与总成本
+
+### 导出最慢的工具调用(可选)
+
+`--top-slow N` 会在生成 `dashboard-data.json` 的同时,额外在**终端**打印耗时最长的 N 次 `event=tool` 调用(工具名 + 耗时 ms,按耗时降序)。排查"哪次工具调用拖慢了会话"时不用再去翻原始 ndjson。
+
+```bash
+python3 scripts/build_dashboard_data.py --top-slow 5
+```
+
+输出示例(排在 `wrote ...` 之后):
+
+```
+top-slow 5 tool calls (by ms):
+ 1. Bash 4820ms
+ 2. Grep 1230ms
+ 3. Read 310ms
+```
+
+注意:
+
+- **默认不开启**:不传该参数时不会打印任何额外内容,原有输出一字不变。
+- **只读**:结果只打印到终端,不会写进 `dashboard-data.json`——输出结构与不开时完全一致,看板不受影响。
+- 只统计 `event=tool` 事件;`ms` 缺失或非数字时按 `0` 兜底,与看板其它统计口径一致。
+- `N` 大于实际 tool 事件数时取全部,不报错;没有任何 tool 事件时不打印该段。
+
+### 自定义模型定价覆盖(可选)
+
+内置价格表 `config/pricing.json` 覆盖不到的模型(自部署模型、内部代号、刚发布还没来得及收录的模型),
+`cost_usd` 会算不出来。给这些模型补单价不用改内置文件——写一份**只含差异**的覆盖文件即可。
+
+**放哪**:默认 `<project_root>/.codebuddy/agent-observability/pricing.overrides.json`
+(`<project_root>` 是 `.codebuddy/` 所在的那一层,例如 `/Users/me/my-project`)。
+
+刻意放在 `skills/` 树**之外**,原因有三:
+
+- `scripts/build-classic-hosts.py` 会整棵同步 `.codebuddy/skills` 到 `.claude/` `.cursor/`,
+ 放树内会让每次改动都产生 `--check` drift,还会把你的单价复制进生成的宿主包;
+- `config/pricing.json` 属于 skill 自带资产,后续更新会把它冲掉,覆盖文件不会;
+- 它是纯数据文件,删除或改名即可停用,不需要重启任何东西(hook 每次都是新进程)。
+
+**格式**:键是模型名(匹配时忽略大小写与首尾空格),值是要覆盖的字段。
+单位与 `config/pricing.json` 完全一致——**USD / 1M tokens**,可用字段只有四个:
+`input`、`output`、`cache_read`、`cache_write`。
+
+```json
+{
+ "my-model": { "output": 9.0 },
+ "gpt-4o": { "output": 99.0 }
+}
+```
+
+**合并是字段级的**:上面这份只改 `output`——`my-model` 的 `input`/`cache_read`/`cache_write`
+沿用内置值(内置表里没有 `my-model` 时,未覆盖的字段按 0 计),`gpt-4o` 的 `input` 仍是内置的 `2.5`。
+可以新增内置表里不存在的模型,但**不能删除**内置的模型或字段(合并只能加不能减)。
+
+**两个环境变量**(都支持 `~` 展开):
+
+| 环境变量 | 作用 | 优先级 |
+|---|---|---|
+| `AOBS_PRICES_PATH` | **替换**整张基础表(不再读内置 `config/pricing.json`) | 低 |
+| `AOBS_PRICING_OVERRIDES_PATH` | 在上面那张基础表之上**叠加**一份补丁,指向任意路径 | 高 |
+
+两者同时设置时,覆盖文件里的字段最终生效。
+
+> ⚠️ **只对新事件生效,不回溯**:`cost_usd` 在 hook 期就写进了 `metrics.ndjson`,
+> 补价之后只有**之后新产生**的 usage 事件按新价格计算,已经落盘的历史成本不会被重算。
+
+**出问题会静默降级**:覆盖文件不存在、JSON 非法、顶层不是对象、字段值不是数字,
+四种情况都自动退回纯内置价格表——不报错、不打印、hook 照常退出 0
+(否则一个手误的格式问题会让整条 hook 链路不可用)。所以"改了没生效"通常意味着文件没被读到,
+先跑一次诊断:
+
+```bash
+python3 - <<'PY'
+import sys
+sys.path.insert(0, "scripts")
+from core import emitter
+print("path :", emitter.resolve_overrides_path())
+print("loaded :", emitter.load_price_overrides())
+print("gpt-4o :", emitter.load_prices().get("gpt-4o"))
+PY
+```
+
+`path` 是实际读取的位置(不是你以为的那个),`loaded` 为空说明文件没读到或全被判为坏字段。
+
+**看板上的提示**:「建议关注」卡片第 4 条「模型定价」会列出**完全没命中价格表**的模型
+(模型名 + 缺少成本的 usage 事件数)。模糊匹配(最长子串)命中的模型能算出成本,不会出现在里面。
+处置方式就是把该模型写进覆盖文件;所有模型都有价时这条显示 green。
+
+### 常见问题
+
+- 没有日志:检查 hook 命令路径。
+- `ms` 为空:通常是 pre/post 未配对。
+- 没有 `usage`:`transcript_path` 缺失、tail 无 usage,或增量已去重。
+- AgentLens 未启用:检查 `.state.json` 的 `_agentlens.enabled` / `last_error`。
+
+### 已知问题(未修复)
+
+- **工具失败事件的 `raw_response` 经常缺失(PostToolUse 与 transcript 落盘之间的时序竞争)**:
+ 真实 CodeBuddy CLI 场景下实测复现过——一次会故意制造失败的 `Bash` 调用(`exitCode=1`,
+ transcript 里 `function_call_result.providerData.toolResult.rawResponse` 确实带了
+ `is_error:true`/`exitCode:1`/`tool_error_code`),但最终写进 `metrics.ndjson` 的
+ `tool` 事件的 `tool_details` 里完全没有 `raw_response` 字段。
+ 用实测时间戳定位到根因:PostToolUse hook 记录这次调用的时间是 `ts=...396.524`,
+ 但 transcript 里 `function_call_result` 真正落盘的时间是 `timestamp=...396.609`——
+ **晚了 85ms**。hook 触发时去扫 transcript 文件的那一刻,CLI 还没来得及把执行结果
+ 那条记录写盘,`find_current_tool_context()`(`core/collector.py`)只能看到
+ `function_call`(请求),看不到 `function_call_result`(结果)。已经单独验证过
+ `merge_tool_records()` / `tool_details_from_record()` 的合并逻辑本身没问题——
+ 只要数据真的已经在文件里,能正确解析出完整 `raw_response`;问题纯粹是读的时机
+ 比 CLI 写盘早了一步。`collect_transcript_entries()` 用的是持久化的增量字节 offset
+ 游标,错过这次窗口后不会在后续调用里回头补扫,所以这次机会永久丢失,直接后果是
+ `build_dashboard_data.py` 的 `tool_call_failed()`(无论怎么改判定逻辑)都拿不到
+ 数据,"工具失败率"/`failures` 列表对这类快速失败调用会漏检。
+ 复现方式:让 CodeBuddy 执行一个必然快速失败的命令(如 `ls /path/does/not/exist`,
+ 越快的命令越容易复现,因为 hook 触发与 transcript 落盘之间的竞争窗口更紧张),
+ 对比 `metrics.ndjson` 里该 `tool` 事件的 `tool_details.raw_response` 是否存在,
+ 和对应 transcript `.jsonl` 里 `function_call`/`function_call_result` 两条记录各自
+ 的 `timestamp` 先后。
+
+ **影响范围(已精确定位,不是猜测)**:`raw_response` 在 `build_dashboard_data.py`
+ 里只有两处消费者——`tool_call_failed()`(喂给 `build_daily_and_sessions()` 的
+ `day.failures` 计数和 `session.status`)和 `build_failures()`("工具失败面板"的
+ 数据源)。真实数据统计过:107 次 tool 事件里只有 2 次带 `raw_response`,且只有
+ `Bash` 调用会带这个字段(Read/Edit/Write/SendMessage 等其它工具从不带,不受
+ 此问题影响)。缺失时 `tool_call_failed()` 默认判"未失败",所以效果是**恒定
+ 漏报,不会误报**——工具失败率/失败面板/会话状态列显示的"正常"可能掩盖了真实
+ 发生过的 Bash 失败。turns、duration、dispatch、cost、token、skill/rule 命中、
+ devflow 阶段耗时、会话列表本身完全不受影响,是纯观测盲区,不影响 devflow 实际
+ 执行行为。
+
+ **三次修复尝试均已失败,均已回滚(详见下方"已尝试且已放弃的修复方向")**:
+ 真正阻塞方向 A 的证据很反常——三次独立测试里,预算从 160ms 加到 500ms 再加到
+ 2000ms,实测缺口每次都精确地"比预算多几十到一百多毫秒"(206/564/2151ms),
+ 不像是在等一个独立发生的固定延迟,更像是**hook 自己的同步等待在阻塞 CLI 落盘**
+ ——等得越久,结果来得越晚。这个因果关系还没验证清楚,在验证清楚之前,继续在
+ hook 里加同步等待大概率是死路,不建议再尝试。
+
+### 已尝试且已放弃的修复方向(供以后参考,避免重复踩坑)
+
+1. **方向 A:PostToolUse 里同步有界重试**(`claim=False` 轮询直到等到 `raw_response`
+ 或超时,只对 `tool_name=="Bash"` 生效)。三次真实端到端验证,预算 160ms/500ms/
+ 2000ms 全部失败,且"缺口≈预算+常数"的规律强烈暗示等待本身可能在拖慢 CLI
+ 落盘(见上文)。不建议在搞清楚这层因果关系之前继续加大预算。
+2. **方向 B:推迟到 `pending_tool_emits` 重试队列,下次 hook 触发或 session Stop
+ 时再补**(`claim=False` 探测 + 延后 `claim=True`,避免过早消费掉 call_id)。
+ 逻辑和单元测试都通过,但端到端验证暴露了一个更深的、独立于这次修复的既有
+ 架构问题:`find_current_tool_context()`(工具上下文查询)和
+ `emit_transcript_events()`(usage token 扫描)共用同一个持久化字节偏移游标
+ (`core/state.py` 里只按 `(sid, transcript_path)` 区分,不分用途)。
+ `emit_transcript_events()` 每次 `handle_post()` 都无条件推进这个游标,一旦
+ 推过某段内容,后续任何工具上下文重试在这段范围内都会**彻底找不到任何数据**
+ (不只是缺 `raw_response`,连 `call_id`/`arguments` 都没了)——比不修复更糟。
+ 真实验证过两次:两条端到端测试调用最终落盘时 `tool_details`完全是空的。
+ 要让方向 B 真正可行,必须先给工具上下文查询一个独立于 usage 扫描的游标,
+ 这是范围更大、需要认真设计的改动,还没有细化方案。
+
+以上两个方向的实现和回滚记录详见会话 memory(`project-agent-observability-raw-response-race`)。
diff --git a/.codebuddy/skills/agent-observability/references/schema-v2.md b/.codebuddy/skills/agent-observability/references/schema-v2.md
new file mode 100644
index 00000000..98179404
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/references/schema-v2.md
@@ -0,0 +1,282 @@
+## Schema v2.3
+
+`agent-observability` 输出 `ndjson`,每行一个事件对象。
+
+> 以下字段表基于当前 `logs/metrics.ndjson` 的实际输出整理;其中“可选字段”只会在特定场景出现。
+
+### 通用字段
+
+- `event`: `start | user_prompt_submit | tool | usage | stop | error | stage_transition`
+- `sid`: session id
+- `ts`: 秒级时间戳(float)
+- `turn_id`: 可选;由 `UserPromptSubmit` 生成,贯穿本轮事件
+
+### Devflow 感知字段(可选,见 `core/devflow.py`)
+
+只有当前项目正在跑 `.codebuddy/runtime` 描述的 multi-agents-devflow 工作流(存在
+`.codebuddy/teams/multi-agents-devflow-{task_slug}/` team 目录)时才会出现,非
+devflow 项目完全不受影响:
+
+- `tool` / `usage` / `stop` 事件上会附带 `task_slug`(devflow 需求标识,用于把
+ main + 最多 7 个常驻角色跨事件串成"同一次运行";⚠️ `/resume-devflow` 中断恢复
+ 可能发生在新的 CodeBuddy 顶层 session 里,因此**聚合一次 devflow 运行要按
+ `task_slug` 分组,不能按 `sid` 分组**)与 `stage`(`workflow-state.json` 的
+ `current_stage`,如 `TASK-03`/`CODE-REVIEW`)。
+- `tool` 事件在能从 subagent transcript 文件名识别出并行 sub-developer 轨道时
+ (`sub-developer-PT-01` 这类命名)会额外带 `pt_id`(如 `"PT-01"`)。按事件自己的
+ transcript_path 推断,不依赖任何 session 级共享状态——并行轨道是真并发,不能
+ 用一个可变指针记"当前是哪条轨道"。
+
+### 事件字段
+
+| event | 实际顶层字段 | 说明 |
+|---|---|---|
+| `start` | `event`, `sid`, `agent`, `ts` | 会话开始 |
+| `user_prompt_submit` | `event`, `sid`, `agent`, `turn_id`, `prompt_len`, `ts` | 新 turn 边界;AgentLens 侧按 `1 Trace = 1 Turn` 生成 trace |
+| `tool` | `event`, `sid`, `agent`, `tool`, `ms`, `transcript_path`, `turn_id`, `ts`, `skill`, `rule`, `cwd`, `call_id`, `message_id`, `tool_details`, `task_slug`?, `stage`?, `pt_id`? | 工具调用与耗时 |
+| `usage` | `event`, `sid`, `agent`, `tool`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | transcript 增量 token / 模型 / 消息归属 |
+| `stop` | `event`, `sid`, `agent`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | 会话尾部 flush |
+| `error` | `event`, `sid`, `phase`, `error`, `x_traceback`, `ts` | hook 自身异常记录 |
+| `stage_transition` | `event`, `sid`, `task_slug`, `stage`, `status`?, `executor`?, `retry_count`?, `review_result`?, `ts` | devflow `workflow-state.json` 某个 stage 的 status/retry_count/review_result 发生变化时触发(仅 devflow 项目) |
+
+### 可选字段说明
+
+- `tool.ms`: Pre/Post 未成功配对时可能为 `null`
+- `tool.call_id`: 仅当工具调用存在 call id 时出现
+- `tool.message_id`: 仅当成功和 transcript 中的 message 关联上时出现
+- `tool.tool_details`: 仅当 transcript 中能还原出更细工具上下文时出现
+- `usage.message_id`: 仅当 usage 对应的 transcript message 可识别时出现
+- `usage.model`: transcript 中能识别模型名时出现
+- `usage.cost_usd`: 只有模型价格命中价格表时才会出现。价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认 `<project_root>/.codebuddy/agent-observability/pricing.overrides.json`,可用 `AOBS_PRICING_OVERRIDES_PATH` 指定)的字段级合并结果;覆盖只对该文件写入**之后**产生的新事件生效,不回溯重算历史成本(见 `quickstart.md` 的「自定义模型定价覆盖」)
+- `stop.cost_usd`: 只有当前 stop 事件对应 usage 能估算成本时才会出现
+- `stop.cost_session_usd`: 只有 stop 汇总阶段能反算出整个 session 成本时才会出现
+
+### 完整示例
+
+换成更容易读的多行 JSON。下面仍然是当前 `metrics.ndjson` 里的实际数据,只是长文本字段做了截断。
+
+`start`
+
+```json
+{
+ "event": "start",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "ts": 1784015331.87806
+}
+```
+
+`user_prompt_submit`
+
+```json
+{
+ "event": "user_prompt_submit",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "turn_id": "turn-1784015342075",
+ "prompt_len": 136,
+ "ts": 1784015342.076438
+}
+```
+
+`usage`
+
+```json
+{
+ "event": "usage",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "tokens": {
+ "input": 31110,
+ "output": 594,
+ "cache_read": 3072,
+ "total": 31704
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.codebuddy/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 17423,
+ "turn_id": "turn-1784015342075",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "ts": 1784015355.413464
+}
+```
+
+`tool` 调用参数型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "ms": null,
+ "transcript_path": "/Users/rachel/.codebuddy/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015355.412617,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/Users/rachel/skillhub-tokentrack-mr/assets/devflow.defaults.yaml\"}",
+ "arguments_display_text": "assets/devflow.defaults.yaml"
+ }
+}
+```
+
+`tool` 返回结果型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 759,
+ "transcript_path": "/Users/rachel/.codebuddy/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015356.071573,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "result_content": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .codebuddy/teams/ ...<truncated>",
+ "raw_response": {
+ "exitCode": 1,
+ "signal": null,
+ "interrupted": false,
+ "sandboxDenied": false,
+ "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0,
+ "tool_error_code": "8002",
+ "is_error": true,
+ "error": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .codebuddy/teams/ ...<truncated>"
+ },
+ "output_text": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .codebuddy/teams/ ...<truncated>",
+ "original_message_id": "d187771c6eef4520a530564dd2a73e38",
+ "next_message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "message_id_reassigned": true
+ }
+}
+```
+
+`stop`
+
+```json
+{
+ "event": "stop",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "test-engineer",
+ "tokens": {
+ "input": 128290,
+ "output": 665,
+ "cache_read": 128192,
+ "total": 128955
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.codebuddy/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 1157291,
+ "turn_id": "turn-1784015342075",
+ "message_id": "51e4fae9553d4d0995e7a599f3b2ef2d",
+ "ts": 1784018405.467215
+}
+```
+
+`error`
+
+```json
+{
+ "event": "error",
+ "sid": "6e8cd633-1a2f-4488-b1df-1eef168009c3",
+ "phase": "post",
+ "error": "AttributeError: module 'core.transcript_runtime' has no attribute 'transcript_path'",
+ "x_traceback": "Traceback ...<truncated>",
+ "ts": 1784183163.4314518
+}
+```
+
+`stage_transition`(仅 devflow 项目;见 `core/devflow.py`)
+
+```json
+{
+ "event": "stage_transition",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "task_slug": "fix-token-bypass_20260911_0900",
+ "stage": "CODE-REVIEW",
+ "status": "failed",
+ "executor": "code-reviewer",
+ "retry_count": 1,
+ "review_result": "failed",
+ "ts": 1784015412.223
+}
+```
+
+### tokens
+
+```json
+{"input": 1200, "output": 180, "cache_read": 9000, "cache_creation": 0, "total": 1380}
+```
+
+- `total`: 统一按 `input + output` 计算
+- `cache_read` / `cache_creation`: 保留给成本估算和缓存命中分析使用
+
+### tool_details
+
+`tool` 事件里的 `tool_details` 是一个可选嵌套对象,当前实现里可能包含:
+
+- `call_id`
+- `arguments`
+- `arguments_display_text`
+- `result_content`
+- `raw_response`
+- `output_text`
+- `original_message_id`
+- `next_message_id`
+- `message_id_reassigned`
+
+常见示例:
+
+```json
+{
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/path/to/file\"}",
+ "arguments_display_text": "path/to/file"
+}
+```
+
+### AgentLens sidecar
+
+`.state.json[sid]._agentlens` 只作为内部状态使用,核心字段:
+
+- `enabled`: AgentLens 上报是否可用
+- `last_error`: 最近一次降级原因
+- `current_turn.carrier.traceparent`: 当前 turn 的 trace context
+- `current_turn.subagent_spans`: 同一 turn 下的子 agent span carrier
+- `current_turn.agent_spans`: 同一 turn 下按 agent 聚合的 span carrier 与累计统计
+- `current_turn.step_spans`: `(agent, message_id)` 级 step span registry
+- `turn_history`: 已结束 turn 的摘要
+
+### Hook 接入
+
+参考 `templates/settings-hook.json`,必须启用:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+### 兼容
+
+- 旧日志若在 `tool` 事件里直接携带 `tokens` / `cost_usd`,按 legacy usage 处理。
+- 不理解 `turn_id` 的下游消费者可安全忽略。
diff --git a/.codebuddy/skills/agent-observability/scripts/__init__.py b/.codebuddy/skills/agent-observability/scripts/__init__.py
new file mode 100644
index 00000000..52073be9
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/__init__.py
@@ -0,0 +1 @@
+"""agent-observability 的脚本包。"""
diff --git a/.codebuddy/skills/agent-observability/scripts/build_dashboard_data.py b/.codebuddy/skills/agent-observability/scripts/build_dashboard_data.py
new file mode 100644
index 00000000..e33f816a
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/build_dashboard_data.py
@@ -0,0 +1,624 @@
+#!/usr/bin/env python3
+"""把 `logs/metrics.ndjson` + `artifacts/*/workflow-state.json` + `.state.json` +
+`hooks/logs/auto-dispatch.log` 聚合成看板需要的一份 `dashboard-data.json` 快照。
+
+这是本地看板的数据源,不是 hook 链路的一部分——hook 只管往 metrics.ndjson 追加事件,
+这个脚本单独、按需运行(比如每次想看一眼看板之前手动跑一次,或者配合文件监听器)。
+复用 core.devflow 的 stage_snapshot 做 workflow-state.json 的 schema 归一化,
+不在这里重新实现一遍 Classic/Portable 的字段差异。
+
+用法:
+ python3 build_dashboard_data.py --project-root <项目根目录> --out dashboard/dashboard-data.json
+ python3 build_dashboard_data.py --metrics-path ~/other/metrics.ndjson --state-path ~/other/.state.json
+ python3 build_dashboard_data.py --top-slow 5
+
+不传 --metrics-path / --state-path 时,仍从 <skill_root>/logs/ 下的默认文件读取;
+两者均支持 ~ 展开,输出 source 会如实反映实际读取路径。
+
+--top-slow N 默认不开启,开启后只在终端额外打印耗时最长的 N 次 tool 事件,
+不写入 dashboard-data.json(输出结构与不开时完全一致)。
+
+没有任何真实数据时(hook 刚接上、还没跑过 session),会输出一份全空但结构合法的快照,
+不会报错、也不会伪造数据。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import devflow as dv # type: ignore
+
+try: # emitter 只在"未定价模型"统计里用到,导入失败只让这一项退化为 []
+ from core import emitter as em # type: ignore
+except Exception: # pragma: no cover - 目标机缺依赖时的兜底
+ em = None # type: ignore
+
+# devflow 两套 schema 的 stage 名 -> 展示用 (label, name)。取不到的 stage 用 key 本身兜底。
+STAGE_META: dict[str, tuple[str, str]] = {
+ "PHASE-0": ("P0", "初始化 + 判定大小"),
+ "SOLO": ("SOLO", "单 agent 全流程"),
+ "TASK-01": ("T01", "需求分析 + 澄清"),
+ "REQUIREMENT": ("REQ", "需求分析 + 澄清"),
+ "TASK-02": ("T02", "技术方案"),
+ "DESIGN": ("DES", "技术方案"),
+ "TASK-03": ("T03", "代码实现"),
+ "IMPLEMENT": ("IMPL", "代码实现"),
+ "CODE-REVIEW": ("CR", "代码审查"),
+ "REVIEW": ("REV", "代码审查"),
+ "TASK-04": ("T04", "E2E 测试"),
+ "TEST": ("TEST", "E2E 测试"),
+ "TASK-05": ("T05", "知识沉淀"),
+ "KNOWLEDGE": ("KNOW", "知识沉淀"),
+ "SUMMARY": ("汇总", "最终汇总"),
+}
+# 两套 schema 各自的阶段顺序,用来按正确顺序渲染 stepper(不能直接遍历 dict,顺序不保证)。
+CLASSIC_ORDER = ["PHASE-0", "TASK-01", "TASK-02", "TASK-03", "CODE-REVIEW", "TASK-04", "TASK-05"]
+# SOLO 完成后,small 任务会由 solo-developer 合并执行 TASK-05 知识沉淀(真实运行验证过,
+# 不是理论上可选的分支);stepper 顺序必须把它列进去,否则会把已完成的阶段悄悄漏掉。
+CLASSIC_SOLO_ORDER = ["PHASE-0", "SOLO", "TASK-05"]
+PORTABLE_ORDER = ["PHASE-0", "REQUIREMENT", "DESIGN", "IMPLEMENT", "REVIEW", "TEST", "KNOWLEDGE", "SUMMARY"]
+PORTABLE_SOLO_ORDER = ["PHASE-0", "SOLO", "SUMMARY"]
+
+
+def read_ndjson(path: Path) -> list[dict[str, Any]]:
+ records: list[dict[str, Any]] = []
+ if not path.is_file():
+ return records
+ with path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ obj = json.loads(line)
+ except Exception:
+ continue
+ if isinstance(obj, dict):
+ records.append(obj)
+ return records
+
+
+def safe_load_json(path: Path) -> Any:
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def day_of(ts: float) -> str:
+ from datetime import datetime, timezone
+ return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+
+
+def tool_call_failed(raw_response: Any) -> bool:
+ """判断一次工具调用是否失败。
+
+ 真实 CodeBuddy CLI 的 transcript(`function_call_result.providerData.toolResult.
+ rawResponse`)里从来没有 `is_error` 这个布尔字段——实际信号是 `exitCode`(非 0
+ 即失败)和/或 `tool_error_code`(非 "0"/空即失败)。之前只认 `is_error`,导致
+ 失败统计在这个宿主上永远是 0,不管命令是否真的失败(复合命令比如
+ `cmd; echo ...` 会把失败进一步掩盖成 exitCode=0,那种情况下这里也如实判定为
+ 未失败——判断整条工具调用本身有没有失败,不追究命令内部的子步骤)。
+ 仍然保留 `is_error` 判断,兼容其它可能真的写这个字段的宿主。
+ """
+ if not isinstance(raw_response, dict):
+ return False
+ if raw_response.get("is_error"):
+ return True
+ exit_code = raw_response.get("exitCode")
+ if isinstance(exit_code, (int, float)) and exit_code != 0:
+ return True
+ tool_error_code = raw_response.get("tool_error_code")
+ if isinstance(tool_error_code, str) and tool_error_code.strip() not in ("", "0"):
+ return True
+ return False
+
+
+def build_daily_and_sessions(events: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ by_day: dict[str, dict[str, Any]] = {}
+ by_sid: dict[str, dict[str, Any]] = {}
+ by_sid_turn: dict[tuple[str, str], dict[str, Any]] = {}
+ # AgentLens(写 state.current_turn 的那套 tracing)默认关闭时,tool/usage 事件
+ # 自身的 turn_id 永远是 None——但 user_prompt_submit 事件不依赖 AgentLens,
+ # 始终携带真实 turn_id(见 emitter.build_prompt_submit_event)。按 ts 排序后,
+ # 把它当作 turn 边界,让后续没有自带 turn_id 的 tool/usage 事件归入"当前 sid
+ # 最近一次打开的 turn",而不是全部塌缩进同一个 "?" 占位桶。
+ current_turn_by_sid: dict[str, str] = {}
+
+ def day_bucket(iso: str) -> dict[str, Any]:
+ return by_day.setdefault(iso, {
+ "iso": iso, "sessionCount": 0, "input": 0, "output": 0, "cache": 0,
+ "cost": 0.0, "toolCalls": 0, "failures": 0, "skillHits": defaultdict(int),
+ "_sids": set(),
+ })
+
+ def sess_bucket(sid: str) -> dict[str, Any]:
+ return by_sid.setdefault(sid, {
+ "id": sid, "date": None, "agents": set(), "turns": set(), "toolCalls": 0,
+ "tokens": 0, "cost": 0.0, "first_ts": None, "last_ts": None, "models": defaultdict(int),
+ "status": "ok", "timeline": {},
+ })
+
+ for rec in sorted(events, key=lambda r: r.get("ts") if isinstance(r.get("ts"), (int, float)) else 0):
+ event = rec.get("event")
+ sid = str(rec.get("sid") or "")
+ ts = rec.get("ts")
+ if not sid or not isinstance(ts, (int, float)):
+ continue
+ iso = day_of(ts)
+ sess = sess_bucket(sid)
+ sess["_seen_day"] = iso
+ # 不管事件类型,只要这天有这个 sid 的任何事件就算一次"当日活跃会话"。
+ # 之前只在 tool/usage 分支里 add,纯对话(只有 user_prompt_submit,没有
+ # 触发任何工具调用也没有 usage)的会话永远不会被计入任何一天的
+ # sessionCount——总览页的"会话数"会比"会话浏览"tab 里实际展开的会话数少
+ # (真实数据复现过:5 个 session 只统计出 4 个 sessionCount)。
+ day_bucket(iso)["_sids"].add(sid)
+ if sess["first_ts"] is None or ts < sess["first_ts"]:
+ sess["first_ts"] = ts
+ sess["date"] = iso
+ if sess["last_ts"] is None or ts > sess["last_ts"]:
+ sess["last_ts"] = ts
+ agent = rec.get("agent")
+ if agent:
+ sess["agents"].add(str(agent))
+ raw_turn_id = rec.get("turn_id")
+ if event == "user_prompt_submit" and raw_turn_id:
+ current_turn_by_sid[sid] = str(raw_turn_id)
+ # 提前建桶——纯对话轮次(没有触发任何工具调用,只有 usage 都没有)
+ # 之前只在 tool/usage 分支里 setdefault,这种轮次永远不会出现在
+ # timeline 里,导致 turns 计数和时间线展开的分组数对不上。
+ by_sid_turn.setdefault(
+ (sid, str(raw_turn_id)),
+ {"turn": raw_turn_id, "agent": agent or "main", "events": []},
+ )
+ turn_id = raw_turn_id or current_turn_by_sid.get(sid)
+ if turn_id:
+ sess["turns"].add(str(turn_id))
+
+ if event == "tool":
+ day = day_bucket(iso)
+ day["toolCalls"] += 1
+ sess["toolCalls"] += 1
+ for s in rec.get("skill") or []:
+ day["skillHits"][str(s)] += 1
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ is_err = tool_call_failed(raw_response)
+ if is_err:
+ day["failures"] += 1
+ sess["status"] = "error"
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "tool", "tool": rec.get("tool"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ "err": is_err,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "usage":
+ day = day_bucket(iso)
+ tokens = rec.get("tokens") or {}
+ day["input"] += int(tokens.get("input") or 0)
+ day["output"] += int(tokens.get("output") or 0)
+ day["cache"] += int(tokens.get("cache_read") or 0)
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ day["cost"] += float(cost)
+ sess["cost"] += float(cost)
+ total_tok = int(tokens.get("input") or 0) + int(tokens.get("output") or 0)
+ sess["tokens"] += total_tok
+ model = rec.get("model")
+ if model:
+ sess["models"][str(model)] += 1
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "usage", "tokens": total_tok,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "error":
+ sess["status"] = "error"
+
+ for (sid, _turn_key), turn in by_sid_turn.items():
+ sess = by_sid.setdefault(sid, sess_bucket(sid))
+ sess["timeline"].setdefault(_turn_key, turn)
+
+ daily = []
+ for iso in sorted(by_day.keys()):
+ d = by_day[iso]
+ daily.append({
+ "iso": iso, "sessionCount": len(d["_sids"]), "input": d["input"], "output": d["output"],
+ "cache": d["cache"], "cost": round(d["cost"], 4), "toolCalls": d["toolCalls"],
+ "failures": d["failures"], "skillHits": dict(d["skillHits"]),
+ })
+
+ sessions = []
+ for sid, s in by_sid.items():
+ if s["first_ts"] is None:
+ continue
+ duration = int((s["last_ts"] or s["first_ts"]) - s["first_ts"])
+ model = max(s["models"].items(), key=lambda kv: kv[1])[0] if s["models"] else None
+ timeline_sorted = sorted(s["timeline"].values(), key=lambda t: str(t.get("turn") or ""))
+ for idx, t in enumerate(timeline_sorted, start=1):
+ t["turn"] = idx
+ sessions.append({
+ "id": sid, "date": s["date"], "agent": ", ".join(sorted(s["agents"])) or "main",
+ "turns": len(s["turns"]) or len(timeline_sorted), "toolCalls": s["toolCalls"],
+ "tokens": s["tokens"], "cost": round(s["cost"], 4), "duration": duration,
+ "model": model, "status": s["status"], "timeline": timeline_sorted,
+ })
+ sessions.sort(key=lambda s: s["date"] or "", reverse=True)
+ return daily, sessions
+
+
+def build_model_costs(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ cost = rec.get("cost_usd")
+ if model and isinstance(cost, (int, float)):
+ totals[str(model)] += float(cost)
+ rows = [{"name": name, "cost": round(cost, 4)} for name, cost in totals.items()]
+ rows.sort(key=lambda r: r["cost"], reverse=True)
+ return rows
+
+
+def build_unpriced_models(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """聚合"完全没命中价格表"的模型(D4:`emitter.is_unpriced(model)` 为 True)。
+
+ 只**统计**不重算:`cost_usd` 在 hook 期就写进事件了,这里不会(也不该)回头
+ 按新价格补算历史事件(D3:覆盖只对新事件生效)。判定入口复用 emitter,
+ 不在本文件里重写一套模型名匹配逻辑,避免与 hook 期的口径分叉。
+
+ 模型名缺失/为空的 usage 事件无法归因到某个模型,直接跳过不计数。
+ """
+ if em is None:
+ return []
+ counts: dict[str, int] = defaultdict(int)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ if not model or not str(model).strip():
+ continue
+ name = str(model)
+ try:
+ if em.is_unpriced(name):
+ counts[name] += 1
+ except Exception:
+ continue
+ rows = [{"name": name, "usageEvents": count} for name, count in counts.items()]
+ # 按 (-事件数, 名字) 排序:避免看板顺序抖动,两次生成的快照可直接逐字节比对。
+ rows.sort(key=lambda r: (-r["usageEvents"], r["name"]))
+ return rows
+
+
+def build_failures(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ agg: dict[tuple[str, str], dict[str, Any]] = {}
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ if not tool_call_failed(raw_response):
+ continue
+ tool = str(rec.get("tool") or "unknown")
+ code = str(raw_response.get("tool_error_code") or raw_response.get("exitCode") or "error")
+ key = (tool, code)
+ row = agg.setdefault(key, {"tool": tool, "code": code, "count": 0, "last": None, "_last_ts": 0.0})
+ row["count"] += 1
+ ts = rec.get("ts")
+ if isinstance(ts, (int, float)) and ts > row["_last_ts"]:
+ row["_last_ts"] = ts
+ row["last"] = day_of(ts)
+ rows = list(agg.values())
+ for row in rows:
+ row.pop("_last_ts", None)
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_top_slow(events: list[dict[str, Any]], limit: int | None = None) -> list[dict[str, Any]]:
+ """取耗时最长的 N 次 tool 事件,按 ms 降序。
+
+ 只做"读":不改动 events,也不参与 dashboard-data.json 的任何字段——调用方拿
+ 结果去打印即可。`ms` 的兜底口径与 build_daily_and_sessions 保持一致(缺失或
+ 非数字按 0 计),否则同一份日志会得出两个互相矛盾的工具耗时视图。
+ """
+ if not isinstance(limit, int) or limit <= 0:
+ return []
+ rows: list[dict[str, Any]] = []
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ rows.append({
+ "tool": str(rec.get("tool") or "unknown"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ })
+ rows.sort(key=lambda r: r["ms"], reverse=True)
+ return rows[:limit]
+
+
+def format_top_slow(rows: list[dict[str, Any]]) -> str:
+ """把 top-slow 结果渲染成终端文本;没有可展示的行时返回空串(由调用方决定
+ 是否打印,避免没有任何 tool 事件时空打一个表头)。"""
+ if not rows:
+ return ""
+ width = max(len(str(r["tool"])) for r in rows)
+ lines = [f"top-slow {len(rows)} tool calls (by ms):"]
+ for idx, row in enumerate(rows, start=1):
+ lines.append(f" {idx}. {str(row['tool']):<{width}} {row['ms']}ms")
+ return "\n".join(lines)
+
+
+def build_skills(state: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ totals: dict[str, int] = defaultdict(int)
+ never_used: dict[str, dict[str, Any]] = {}
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for name, rec in (sess.get("skills") or {}).items():
+ if not isinstance(rec, dict):
+ continue
+ totals[name] += int(rec.get("count") or 0)
+ for name, rec in (sess.get("rules") or {}).items():
+ if not isinstance(rec, dict) or int(rec.get("count") or 0) > 0:
+ continue
+ never_used[name] = {"name": name, "reason": "no_paths", "detail": "从未被路径推断或 active-rule 命中"}
+ for name, count in totals.items():
+ if count == 0:
+ never_used.setdefault(name, {"name": name, "reason": "no_paths", "detail": "静态扫描到,但从未被任何工具调用命中"})
+ skill_rows = [{"name": name, "count": count} for name, count in totals.items() if count > 0]
+ skill_rows.sort(key=lambda r: r["count"], reverse=True)
+ return skill_rows, sorted(never_used.values(), key=lambda r: r["name"])
+
+
+
+# "team-lead" 是 CodeBuddy 原生 team 基础设施里 lead/orchestrator session 自己的
+# mailbox 名字,语义上就是 main(core/agent_identity.py::normalize_role_name 把它
+# 和 "main" 归为同一类);不是一个真实存在的子 agent,不应出现在"派发目标"里。
+_DISPATCH_EXCLUDE_AGENTS = {"main", "team-lead"}
+
+
+def build_dispatch(state: dict[str, Any]) -> list[dict[str, Any]]:
+ totals: dict[str, int] = defaultdict(int)
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for entry in sess.get("agent_history") or []:
+ if not isinstance(entry, dict):
+ continue
+ evidence = str(entry.get("evidence") or "")
+ agent = entry.get("agent")
+ if not agent or agent in _DISPATCH_EXCLUDE_AGENTS:
+ continue
+ # 只统计真正代表"新派发"的证据:工具调用直接触发的 dispatch@,
+ # 或 inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)。
+ # 排除 inbox@report:*/inbox@handoff:*——那是子 agent 上报/移交,
+ # 不是 main 发起的新派发,计进来会把"派发次数"虚高(同一次真实
+ # 派发经常先触发 dispatch@,随后又在 inbox 里被自己的上报回声一次)。
+ is_dispatch = evidence.startswith("dispatch@") or evidence.startswith("inbox@dispatch:")
+ if is_dispatch:
+ totals[str(agent)] += 1
+ rows = [{"agent": agent, "count": count} for agent, count in totals.items()]
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_auto_dispatch_stats(project_root: Path) -> dict[str, int]:
+ log_path = project_root / ".codebuddy" / "hooks" / "logs" / "auto-dispatch.log"
+ stats = {"auto_dispatch": 0, "fallback_to_main": 0, "passthrough": 0}
+ if not log_path.is_file():
+ return stats
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ decision = str(rec.get("decision") or "")
+ if decision == "auto_dispatch":
+ stats["auto_dispatch"] += 1
+ elif decision == "fallback_to_main":
+ stats["fallback_to_main"] += 1
+ elif decision in {"passthrough"}:
+ stats["passthrough"] += 1
+ return stats
+
+
+def build_cost_by_task_slug(events: list[dict[str, Any]]) -> dict[str, float]:
+ """按 task_slug 汇总 usage/stop 事件的 cost_usd——workflow-state.json 自己不知道成本,
+ 这是唯一能把 devflow 运行和真实花费对上的地方(需要 emitter 已经把 task_slug 挂到事件上,
+ 见 core/runtime.py 的 devflow 接入)。"""
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") not in {"usage", "stop"}:
+ continue
+ task_slug = rec.get("task_slug")
+ cost = rec.get("cost_usd")
+ if task_slug and isinstance(cost, (int, float)):
+ totals[str(task_slug)] += float(cost)
+ return dict(totals)
+
+
+def build_devflow_runs(project_root: Path, cost_by_slug: dict[str, float] | None = None) -> list[dict[str, Any]]:
+ artifacts_root = project_root / "artifacts"
+ runs: list[dict[str, Any]] = []
+ cost_by_slug = cost_by_slug or {}
+ if not artifacts_root.is_dir():
+ return runs
+ for child in sorted(artifacts_root.iterdir()):
+ state_path = child / "workflow-state.json"
+ raw = dv.read_workflow_state(str(state_path))
+ if not isinstance(raw, dict) or not isinstance(raw.get("stages"), dict):
+ continue
+ snap = dv.stage_snapshot(raw)
+ size_class = str(snap.get("size_class") or "medium")
+ # medium/large 的 workflow-state.json 也会带着 SOLO key(模板固定写入,
+ # 状态停在 "pending" 或 "skipped",从未被真正执行)——不能只看 key 存不存在,
+ # 必须看 SOLO 阶段是不是真的跑过,否则每个 medium/large 任务都会被误判成
+ # solo 路径,阶段视图漏掉 TASK-01/02/03/CODE-REVIEW/TASK-04。
+ solo_info = snap["stages"].get("SOLO")
+ solo_status = str(solo_info.get("status") or "") if isinstance(solo_info, dict) else ""
+ solo_actually_ran = solo_status not in {"", "pending", "skipped"}
+ is_solo = size_class == "small" or (size_class not in {"small", "medium", "large"} and solo_actually_ran)
+ if snap.get("schema_version") == "2.0":
+ order = PORTABLE_SOLO_ORDER if is_solo else PORTABLE_ORDER
+ else:
+ order = CLASSIC_SOLO_ORDER if is_solo else CLASSIC_ORDER
+ stages_out = []
+ total_cost = cost_by_slug.get(child.name, 0.0)
+ run_start = None
+ run_end = None
+ overall = "completed"
+ for key in order:
+ info = snap["stages"].get(key)
+ if info is None:
+ # PHASE-0 在两套 schema 里都不会出现在 stages{} 里(它是隐式完成的:
+ # workflow-state.json 一旦存在,就说明 Phase 0 已经跑完了),
+ # 不能用"没有条目"直接兜底成 pending,那样会把已完成的阶段显示错。
+ info = {"status": "completed", "retry_count": 0, "executor": None} if key == "PHASE-0" \
+ else {"status": "pending", "retry_count": 0, "executor": None}
+ label, name = STAGE_META.get(key, (key[:4], key))
+ status = str(info.get("status") or "pending")
+ retry_count = int(info.get("retry_count") or 0)
+ raw_stage = raw.get("stages", {}).get(key) if isinstance(raw.get("stages"), dict) else {}
+ duration = 0
+ if isinstance(raw_stage, dict):
+ started = raw_stage.get("started_at")
+ completed = raw_stage.get("completed_at")
+ if isinstance(started, str) and isinstance(completed, str):
+ try:
+ from datetime import datetime
+ t0 = datetime.fromisoformat(started.replace("Z", "+00:00"))
+ t1 = datetime.fromisoformat(completed.replace("Z", "+00:00"))
+ duration = max(0, int((t1 - t0).total_seconds()))
+ if run_start is None or t0 < run_start:
+ run_start = t0
+ if run_end is None or t1 > run_end:
+ run_end = t1
+ except Exception:
+ duration = 0
+ if status == "failed":
+ overall = "paused"
+ elif status == "in_progress" and overall != "paused":
+ overall = "running"
+ stages_out.append({
+ "key": key, "label": label, "name": name,
+ "exec": info.get("executor") or "-", "status": status,
+ "retry_count": retry_count, "duration": duration,
+ })
+ # 按真实起止时间跨度算总时长(而不是逐阶段 duration 相加)——阶段之间可能
+ # 有重叠(比如 TASK-05 的 started_at 早于 SOLO 的 completed_at),相加会
+ # 把重叠部分重复计入,虚高于源数据本身反映的运行时长。
+ total_duration = int((run_end - run_start).total_seconds()) if run_start and run_end else 0
+ runs.append({
+ "slug": child.name, "size": size_class, "stages": stages_out,
+ "cost": round(total_cost, 4), "duration": total_duration, "overall": overall,
+ })
+ runs.sort(key=lambda r: r["slug"], reverse=True)
+ return runs
+
+
+def resolve_input_paths(
+ skill_root: Path,
+ metrics_path: str | None = None,
+ state_path: str | None = None,
+) -> tuple[Path, Path]:
+ """解析 metrics.ndjson 与 .state.json 的实际读取路径。
+
+ 任一参数为 None 时回退到 ``<skill_root>/logs/`` 下的默认路径,保证未传参时
+ 行为与旧版本完全一致(向后兼容,不会破坏现有看板数据源)。
+
+ 非 None 时按用户给定路径(支持 ``~`` 展开)取绝对路径,便于看板从非默认
+ 位置(如其它会话/项目的日志目录)聚合数据。
+ """
+ default_metrics = skill_root / "logs" / "metrics.ndjson"
+ default_state = skill_root / "logs" / ".state.json"
+ if metrics_path:
+ metrics = Path(metrics_path).expanduser().absolute()
+ else:
+ metrics = default_metrics
+ if state_path:
+ state = Path(state_path).expanduser().absolute()
+ else:
+ state = default_state
+ return metrics, state
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--project-root", default=".", help="devflow 项目根目录(含 .codebuddy/ 和 artifacts/)")
+ parser.add_argument("--out", default=None, help="输出路径,默认 <skill_root>/scripts/dashboard/dashboard-data.json")
+ parser.add_argument("--metrics-path", default=None, help="覆盖 metrics.ndjson 的读取路径(默认 <skill_root>/logs/metrics.ndjson,支持 ~ 展开)")
+ parser.add_argument("--state-path", default=None, help="覆盖 .state.json 的读取路径(默认 <skill_root>/logs/.state.json,支持 ~ 展开)")
+ parser.add_argument("--top-slow", type=int, default=None, help="额外在终端打印耗时最长的 N 次 tool 事件(工具名 + 耗时 ms),默认不打印;只打印不写入 dashboard-data.json")
+ args = parser.parse_args()
+
+ project_root = Path(args.project_root).expanduser().resolve()
+ skill_root = SCRIPTS_DIR.parent
+ log_path, state_path = resolve_input_paths(skill_root, args.metrics_path, args.state_path)
+
+ # 价格表带 lru_cache:本脚本可能长期驻留(配合文件监听器),单测也会同进程多次
+ # 调 main(),每次都先清一次缓存,保证覆盖文件的改动当场生效。
+ if em is not None:
+ try:
+ em.clear_price_cache()
+ except Exception:
+ pass
+
+ events = read_ndjson(log_path)
+ state = safe_load_json(state_path) or {}
+ if not isinstance(state, dict):
+ state = {}
+
+ daily, sessions = build_daily_and_sessions(events)
+ model_costs = build_model_costs(events)
+ unpriced = build_unpriced_models(events)
+ failures = build_failures(events)
+ skills, never_used = build_skills(state)
+ dispatch = build_dispatch(state)
+ auto_dispatch_stats = build_auto_dispatch_stats(project_root)
+ cost_by_slug = build_cost_by_task_slug(events)
+ devflow_runs = build_devflow_runs(project_root, cost_by_slug)
+
+ from datetime import datetime, timezone
+ out_data = {
+ "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+ "source": {
+ "metrics_ndjson": str(log_path), "state_json": str(state_path),
+ "project_root": str(project_root), "event_count": len(events),
+ },
+ "daily": daily, "sessions": sessions, "modelCosts": model_costs, "unpricedModels": unpriced,
+ "failures": failures,
+ "skills": skills, "neverUsed": never_used, "dispatch": dispatch,
+ "autoDispatchStats": auto_dispatch_stats, "devflowRuns": devflow_runs,
+ }
+
+ out_path = Path(args.out).expanduser().resolve() if args.out else (SCRIPTS_DIR / "dashboard" / "dashboard-data.json")
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+ out_path.write_text(json.dumps(out_data, ensure_ascii=False, indent=2), encoding="utf-8")
+ print(f"wrote {out_path} ({len(events)} events, {len(sessions)} sessions, {len(devflow_runs)} devflow runs)")
+ # top-slow 放在原输出之后:先保证不传参时的终端输出与 JSON 行为完全不变。
+ top_slow_block = format_top_slow(build_top_slow(events, args.top_slow))
+ if top_slow_block:
+ print(top_slow_block)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.codebuddy/skills/agent-observability/scripts/core/__init__.py b/.codebuddy/skills/agent-observability/scripts/core/__init__.py
new file mode 100644
index 00000000..1d6ad5e9
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/__init__.py
@@ -0,0 +1,8 @@
+"""agent-observability 的核心运行时模块集合。
+
+这里放的是 hook 主流程真正依赖的内部实现:
+- 采集与 transcript 解析
+- 状态读写与去重
+- skill/rule 扫描
+- AgentLens trace 镜像
+"""
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agent_identity.py b/.codebuddy/skills/agent-observability/scripts/core/agent_identity.py
new file mode 100644
index 00000000..270ff904
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agent_identity.py
@@ -0,0 +1,587 @@
+"""Agent 身份解析层。
+
+这一层负责统一解析“当前是谁在工作、又把任务派给了谁”:
+- 从 tool 调用参数里提取 agent 线索
+- 从 team inbox / mailbox 中补偿推断 agent 身份
+- 把解析结果写回 session state,供后续日志归因复用
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+from . import scanner, state as st
+
+AGENT_PATH_RE = re.compile(r"\.codebuddy/agents/([a-zA-Z0-9_\-]+)(?:\.md)?", re.I)
+DISPATCH_TOOLS = {"Task", "task", "Agent", "DeferExecuteTool"}
+MESSAGE_TOOLS = {"send_message", "SendMessage"}
+TEAM_PREFIX = "multi-agents-devflow-"
+ROLE_INSTANCE_RE = re.compile(r"^(?P<base>[a-z0-9][a-z0-9\-]*?)-\d+$", re.I)
+INITIAL_ASSIGNMENT_RE = re.compile(
+ r"Initial task assignment for (?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+ROLE_DECLARATION_RE = re.compile(
+ r"角色[::]\s*(?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+# devflow TASK-03 并行 fan-out 时,developer 会以 Task(name="sub-developer-PT-01", ...)
+# 派发多条并行轨道。轨道号只在 transcript 文件名(= Task 的 name 参数)里出现,
+# 按 subagent_name 归一化后会被折成同一个 "developer" —— 这是有意的(用于按角色汇总),
+# 轨道号需要单独提取,见 pt_id_from_transcript_path。
+PT_TRACK_RE = re.compile(r"-((?:PT|pt)-\d+)$")
+
+
+def normalize_role_name(name: str | None) -> Optional[str]:
+ """把角色名归一化成稳定标识,例如把实例名折叠回基础角色名。"""
+ if not isinstance(name, str):
+ return None
+ cand = name.strip().lower()
+ if not cand:
+ return None
+ if cand.endswith(".json"):
+ cand = cand[:-5]
+ if "@" in cand:
+ cand = cand.split("@", 1)[0]
+ if cand in {"team-lead", "main"}:
+ return "main"
+ match = ROLE_INSTANCE_RE.match(cand)
+ if match:
+ cand = match.group("base")
+ return cand or None
+
+
+def resolve_teams_root() -> Path:
+ """解析 CodeBuddy team inbox 的根目录。"""
+ config_dir = (os.environ.get("CODEBUDDY_CONFIG_DIR") or "").strip()
+ if config_dir:
+ return Path(config_dir).expanduser() / "teams"
+ return Path.home() / ".codebuddy" / "teams"
+
+
+def resolve_team_dir(cwd: str, sid: str, cached_team_dir: str | None = None) -> Path | None:
+ """根据 session id 和 cwd 找到当前会话对应的 team 目录。"""
+ if cached_team_dir:
+ cached = Path(cached_team_dir).expanduser()
+ if (cached / "config.json").is_file():
+ cfg = _load_json(cached / "config.json")
+ if isinstance(cfg, dict) and sid and str(cfg.get("leadSessionId") or "") == sid:
+ return cached
+
+ if not sid:
+ return None
+
+ teams_root = resolve_teams_root()
+ if not teams_root.is_dir():
+ return None
+
+ best_dir: Path | None = None
+ best_created = -1
+ for team_dir in teams_root.iterdir():
+ if not team_dir.is_dir() or not team_dir.name.startswith(TEAM_PREFIX):
+ continue
+ config = _load_json(team_dir / "config.json")
+ if not isinstance(config, dict):
+ continue
+ if str(config.get("leadSessionId") or "") != sid:
+ continue
+ if not _config_matches_cwd(config, cwd):
+ continue
+
+ created_at = _safe_int(config.get("createdAt"))
+ if created_at <= 0:
+ try:
+ created_at = int(team_dir.stat().st_mtime * 1000)
+ except Exception:
+ created_at = 0
+ if created_at > best_created:
+ best_dir = team_dir
+ best_created = created_at
+ return best_dir
+
+
+def read_recent_messages(
+ team_dir: Path,
+ offsets: dict[str, int] | None = None,
+ *,
+ max_per_mailbox: int = 30,
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+ """按 mailbox 增量读取最近消息,并返回新的 offset 游标。"""
+ inbox_dir = team_dir / "inboxes"
+ if not inbox_dir.is_dir():
+ return [], offsets or {}
+
+ prev_offsets = offsets or {}
+ new_offsets: dict[str, int] = {}
+ messages: list[dict[str, Any]] = []
+
+ for inbox_file in sorted(inbox_dir.glob("*.json")):
+ raw = _load_json(inbox_file)
+ if not isinstance(raw, list):
+ raw = []
+
+ total = len(raw)
+ prev = _safe_int(prev_offsets.get(inbox_file.name))
+ if prev < 0 or prev > total:
+ prev = 0
+
+ start = prev
+ if start == 0 and total > max_per_mailbox:
+ start = total - max_per_mailbox
+
+ mailbox_name = inbox_file.stem
+ mailbox_role = normalize_role_name(mailbox_name)
+ for idx, item in enumerate(raw[start:], start=start):
+ norm = _normalize_message(item, mailbox_name, mailbox_role, idx)
+ if norm:
+ messages.append(norm)
+
+ new_offsets[inbox_file.name] = total
+
+ messages.sort(key=lambda x: (x.get("ts") or 0.0, x.get("mailbox_name") or "", x.get("index") or 0))
+ return messages, new_offsets
+
+
+def infer_identity_from_messages(messages: list[dict[str, Any]]) -> tuple[Optional[str], Optional[str], dict[str, Any]]:
+ """根据 inbox 消息流推断当前 agent 与派发目标。"""
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ evidence: Optional[str] = None
+
+ for msg in messages:
+ mailbox_name = str(msg.get("mailbox_name") or "")
+ mailbox_role = normalize_role_name(msg.get("mailbox_role"))
+ from_role = normalize_role_name(msg.get("from_role"))
+ payload = msg.get("payload") if isinstance(msg.get("payload"), dict) else {}
+ next_target = _extract_next_target(payload)
+
+ if from_role == "main" and mailbox_role and mailbox_role != "main":
+ if not msg.get("is_shutdown"):
+ current = mailbox_role
+ dispatched = mailbox_role
+ evidence = f"dispatch:{mailbox_name}"
+ continue
+
+ if mailbox_name == "team-lead" and from_role and from_role not in {"main", "system"}:
+ report_role = normalize_role_name(
+ payload.get("from_role") if isinstance(payload, dict) else None
+ ) or from_role
+ if next_target:
+ current = next_target
+ dispatched = next_target
+ evidence = f"handoff:{report_role}->{next_target}"
+ else:
+ current = report_role
+ evidence = f"report:{report_role}"
+
+ meta: dict[str, Any] = {"messages_seen": len(messages)}
+ if evidence:
+ meta["evidence"] = evidence
+ return current, dispatched, meta
+
+
+def safe_agent_from_provider(record: dict[str, Any]) -> str | None:
+ """当 transcript 自己带有 providerData 时,直接读取其中的 agent。"""
+ provider = record.get("providerData")
+ if not isinstance(provider, dict):
+ return None
+ agent = provider.get("agent")
+ if isinstance(agent, str) and agent.strip():
+ return normalize_role_name(agent.strip())
+ return None
+
+
+def role_from_content_items(content: Any) -> str | None:
+ """从 transcript content 文本中提取更具体的业务角色名。"""
+ if not isinstance(content, list):
+ return None
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ text = item.get("text")
+ if not isinstance(text, str):
+ continue
+ for regex in (INITIAL_ASSIGNMENT_RE, ROLE_DECLARATION_RE):
+ match = regex.search(text)
+ if not match:
+ continue
+ role = normalize_role_name(match.group("role"))
+ if role:
+ return role
+ return None
+
+
+@lru_cache(maxsize=256)
+def role_for_subagent_transcript(transcript_path: str) -> str | None:
+ """从 subagent transcript 前几行推断更准确的角色名。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(6):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+
+ # 对 subagent transcript,优先信任务分配文本里的具体角色,
+ # 再回退到 providerData.agent,避免 general-purpose 覆盖业务角色。
+ content_role = role_from_content_items(record.get("content"))
+ if content_role:
+ return content_role
+
+ provider_agent = safe_agent_from_provider(record)
+ if provider_agent:
+ return provider_agent
+ except Exception:
+ return None
+ return None
+
+
+def agent_for_transcript_path(transcript_path: str, fallback: str | None = None) -> str:
+ """把 transcript 路径映射回实际对应的 agent 身份。"""
+ parts = Path(transcript_path).parts
+ if "subagents" in parts:
+ return role_for_subagent_transcript(transcript_path) or Path(transcript_path).stem
+ return fallback or "main"
+
+
+def pt_id_from_transcript_path(transcript_path: str) -> str | None:
+ """从并行 sub-developer 的 transcript 文件名里提取 PT 轨道号(如 "PT-01")。
+
+ 按事件自己的 transcript_path 推断,而不是写一个共享的 session 级"当前 PT"指针——
+ devflow 一次可以并行派发最多 6 条 sub-developer 轨道,它们在同一个 sid 下
+ 真·并发运行,任何"当前是哪条轨道"的可变共享状态在并发场景下都是错的。
+ """
+ parts = Path(transcript_path).parts
+ if "subagents" not in parts:
+ return None
+ match = PT_TRACK_RE.search(Path(transcript_path).stem)
+ return match.group(1).upper() if match else None
+
+
+def merge_agent_identity_from_inbox(
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str | None,
+ dispatched: str | None,
+) -> tuple[str, str | None]:
+ """在基于 tool 的推断之上,再叠加 mailbox/inbox 的证据。"""
+
+ def _update(state: dict[str, Any]) -> tuple[str, str | None]:
+ sess = st.ensure_session(state, sid)
+ cached_team_dir = str(sess.get("_team_dir") or "").strip() or None
+ offsets = sess.get("_inbox_offsets")
+ if not isinstance(offsets, dict):
+ offsets = {}
+
+ effective_agent = active_agent or str(sess.get("current_agent") or "main")
+ effective_dispatched = dispatched
+ team_dir = resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is None:
+ return effective_agent, effective_dispatched
+
+ sess["_team_dir"] = str(team_dir)
+ messages, new_offsets = read_recent_messages(team_dir, offsets)
+ sess["_inbox_offsets"] = new_offsets
+ inferred_current, inferred_dispatched, meta = infer_identity_from_messages(messages)
+ if inferred_current:
+ effective_agent = inferred_current
+ if inferred_dispatched:
+ effective_dispatched = inferred_dispatched
+ if inferred_current or inferred_dispatched:
+ target_agent = inferred_current or inferred_dispatched
+ if target_agent:
+ sess["current_agent"] = target_agent
+ hist = sess.setdefault("agent_history", [])
+ hist.append({
+ "ts": time.time(),
+ "agent": target_agent,
+ "evidence": f"inbox@{meta.get('evidence') or 'inbox'}",
+ })
+ return effective_agent, effective_dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+
+def resolve_active_agent_for_event(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ data: dict[str, Any],
+) -> tuple[str, str | None]:
+ """优先用 tool 线索、其次用 inbox 线索,解析事件对应的 agent。"""
+ tracker = AgentIdentityResolver()
+ active_agent, dispatched = tracker.track(state_path, sid, data)
+ if scanner.is_brainstorming_call(data):
+
+ def _update(state_data: dict[str, Any]) -> None:
+ sess = st.ensure_session(state_data, sid)
+ sess["current_agent"] = "main"
+
+ st.update_state_locked(state_path, _update)
+ return "main", dispatched
+ return merge_agent_identity_from_inbox(
+ state_path,
+ sid,
+ cwd,
+ active_agent,
+ dispatched,
+ )
+
+
+class AgentIdentityResolver:
+ """基于 tool 调用内容做一轮 agent 身份推断。"""
+ def __init__(self, known_agents: set[str] | None = None):
+ self.known_agents = known_agents or set()
+
+ def extract_identity(self, data: dict) -> tuple[Optional[str], Optional[str]]:
+ tool = data.get("tool_name", "")
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ tool_input = {}
+
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+
+ if tool in MESSAGE_TOOLS:
+ extracted_current, extracted_dispatched = self._extract_from_message(tool_input)
+ if extracted_current and not current:
+ current = extracted_current
+ if extracted_dispatched and not dispatched:
+ dispatched = extracted_dispatched
+
+ if tool in DISPATCH_TOOLS and not dispatched:
+ dispatched = self._extract_from_task(tool_input)
+
+ if not current:
+ current = self._extract_from_path(data, tool_input)
+
+ if self.known_agents:
+ if current and current not in self.known_agents:
+ current = None
+ if dispatched and dispatched not in self.known_agents:
+ dispatched = None
+
+ return current, dispatched
+
+ def track(self, state_path: Path, sid: str, data: dict) -> tuple[str, Optional[str]]:
+ tool = data.get("tool_name", "")
+ cur_agent, dispatched = self.extract_identity(data)
+
+ def _update(state: dict[str, Any]) -> tuple[str, Optional[str]]:
+ sess = st.ensure_session(state, sid)
+ hist = sess.setdefault("agent_history", [])
+ prev_agent = sess.get("current_agent") or "main"
+
+ if cur_agent and cur_agent != prev_agent:
+ sess["current_agent"] = cur_agent
+ hist.append({"ts": time.time(), "agent": cur_agent, "evidence": f"from_role@{tool}"})
+ active_agent = cur_agent
+ else:
+ active_agent = prev_agent
+
+ if dispatched and dispatched != active_agent:
+ dis = sess.setdefault("dispatched", {})
+ if not isinstance(dis, dict):
+ dis = {}
+ sess["dispatched"] = dis
+ dis[dispatched] = dis.get(dispatched, 0) + 1
+ sess["current_agent"] = dispatched
+ hist.append({"ts": time.time(), "agent": dispatched, "evidence": f"dispatch@{tool}<-{active_agent}"})
+
+ if len(hist) > 100:
+ sess["agent_history"] = hist[-100:]
+
+ return active_agent, dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+ def _extract_from_message(self, tool_input: dict) -> tuple[Optional[str], Optional[str]]:
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ content = tool_input.get("content")
+
+ if isinstance(content, str) and content.strip().startswith("{"):
+ try:
+ payload = json.loads(content)
+ current = self._extract_str(payload, "from_role")
+ next_target = payload.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+ except Exception:
+ pass
+ elif isinstance(content, dict):
+ current = self._extract_str(content, "from_role")
+ next_target = content.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+
+ if not dispatched:
+ recipient = tool_input.get("recipient")
+ if isinstance(recipient, str):
+ normalized = recipient.strip().lower()
+ if normalized and normalized != "main":
+ dispatched = normalized
+
+ return current, dispatched
+
+ def _extract_from_task(self, tool_input: dict) -> Optional[str]:
+ sub = (
+ # Claude Code 的 Agent 工具(非 CodeBuddy 原生 Task/team_create)用的是
+ # subagent_type 字段,不是 subagent_name——不认这个字段会导致 dispatch
+ # 统计漏掉所有走 Agent 工具派发的场景。
+ tool_input.get("subagent_type")
+ or tool_input.get("subagent_name")
+ or tool_input.get("name")
+ or tool_input.get("agent")
+ or tool_input.get("role")
+ )
+ if isinstance(sub, str) and sub.strip():
+ candidate = sub.strip().lower()
+ if "/" in candidate:
+ candidate = candidate.rsplit("/", 1)[1].replace(".md", "")
+ return candidate
+ return None
+
+ def _extract_from_path(self, data: dict, tool_input: dict) -> Optional[str]:
+ text = json.dumps(tool_input, ensure_ascii=False) + " " + (data.get("cwd") or "")
+ match = AGENT_PATH_RE.search(text)
+ if match:
+ return match.group(1).lower()
+ return None
+
+ @staticmethod
+ def _extract_str(payload: dict, key: str) -> Optional[str]:
+ value = payload.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip().lower()
+ return None
+
+
+def _config_matches_cwd(config: dict[str, Any], cwd: str) -> bool:
+ """判断 team 配置中的成员 cwd 是否覆盖当前工作目录。"""
+ members = config.get("members")
+ if not isinstance(members, list):
+ return False
+ for member in members:
+ if not isinstance(member, dict):
+ continue
+ member_cwd = member.get("cwd")
+ if isinstance(member_cwd, str) and _paths_equal(member_cwd, cwd):
+ return True
+ return False
+
+
+def _paths_equal(a: str, b: str) -> bool:
+ """按归一化绝对路径语义比较两个路径是否相等。"""
+ try:
+ return Path(a).expanduser().resolve() == Path(b).expanduser().resolve()
+ except Exception:
+ return os.path.abspath(os.path.expanduser(a)) == os.path.abspath(os.path.expanduser(b))
+
+
+def _normalize_message(item: Any, mailbox_name: str, mailbox_role: str | None, index: int) -> dict[str, Any] | None:
+ """把原始 inbox 消息归一化成统一可推断的结构。"""
+ if not isinstance(item, dict):
+ return None
+
+ text = item.get("text")
+ payload = _coerce_payload(text)
+ summary = item.get("summary") if isinstance(item.get("summary"), str) else ""
+ from_raw = item.get("from") if isinstance(item.get("from"), str) else None
+ from_role = normalize_role_name((payload.get("from") if isinstance(payload, dict) else None) or from_raw)
+ ts = _parse_timestamp(item.get("timestamp"))
+
+ return {
+ "mailbox_name": mailbox_name,
+ "mailbox_role": mailbox_role,
+ "from": from_raw,
+ "from_role": from_role,
+ "text": text if isinstance(text, str) else "",
+ "summary": summary,
+ "payload": payload,
+ "timestamp": item.get("timestamp"),
+ "ts": ts,
+ "index": index,
+ "is_shutdown": _is_shutdown_message(payload, summary, text),
+ }
+
+
+def _extract_next_target(payload: dict[str, Any] | None) -> Optional[str]:
+ """从 payload 中提取下一跳要派发给的角色。"""
+ if not isinstance(payload, dict):
+ return None
+ next_target = payload.get("next_target") or {}
+ if not isinstance(next_target, dict):
+ return None
+ return normalize_role_name(next_target.get("role_name") or next_target.get("subagent_name"))
+
+
+def _coerce_payload(text: Any) -> dict[str, Any] | None:
+ """把文本内容尽量解析成 JSON 字典。"""
+ if isinstance(text, dict):
+ return text
+ if not isinstance(text, str):
+ return None
+ stripped = text.strip()
+ if not stripped.startswith("{"):
+ return None
+ try:
+ data = json.loads(stripped)
+ if isinstance(data, dict):
+ return data
+ except Exception:
+ return None
+ return None
+
+
+def _is_shutdown_message(payload: dict[str, Any] | None, summary: str, text: Any) -> bool:
+ """识别一条 inbox 消息是否表示 agent 关闭或退出。"""
+ if isinstance(payload, dict) and str(payload.get("type") or "").lower() == "shutdown_request":
+ return True
+ summary_low = summary.lower() if isinstance(summary, str) else ""
+ text_low = text.lower() if isinstance(text, str) else ""
+ return "shutdown" in summary_low or "shutdown request" in text_low
+
+
+def _parse_timestamp(value: Any) -> float:
+ """把消息时间字段解析成 Unix 时间戳。"""
+ if not isinstance(value, str) or not value.strip():
+ return datetime.now(timezone.utc).timestamp()
+ try:
+ return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+ except Exception:
+ return datetime.now(timezone.utc).timestamp()
+
+
+def _load_json(path: Path) -> Any:
+ """安全读取 JSON 文件,失败时返回 ``None``。"""
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def _safe_int(value: Any) -> int:
+ """把任意值尽量转成整数,失败时返回 0。"""
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agentlens/__init__.py b/.codebuddy/skills/agent-observability/scripts/core/agentlens/__init__.py
new file mode 100644
index 00000000..2fea21d6
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agentlens/__init__.py
@@ -0,0 +1,9 @@
+"""可选的 AgentLens sink,用于实时镜像 trace。"""
+from .runtime import emit_post_step, emit_session_start, emit_session_stop, emit_turn_start
+
+__all__ = [
+ "emit_post_step",
+ "emit_session_start",
+ "emit_session_stop",
+ "emit_turn_start",
+]
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agentlens/bootstrap.py b/.codebuddy/skills/agent-observability/scripts/core/agentlens/bootstrap.py
new file mode 100644
index 00000000..d6fc970e
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agentlens/bootstrap.py
@@ -0,0 +1,229 @@
+from __future__ import annotations
+"""AgentLens 启动辅助层。
+
+这一层负责“读入与初始化”:
+- 解析项目配置与环境变量
+- 延迟加载可选的 zhiyan 运行时
+- 缓存初始化结果,避免重复 init
+- 处理调试落盘与失败状态写回
+"""
+
+import getpass
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+
+DEFAULT_APP_NAME = "skillhub.codebuddy-hooks"
+DEFAULT_BUSINESS_SCENARIO = "codebuddy-hook"
+
+_RUNTIME: dict[str, Any] | None = None
+_INIT_SIGNATURE: tuple[str, str, str] | None = None
+
+
+@dataclass(frozen=True)
+class AgentLensConfig:
+ """从环境变量与 env 文件归一化得到的 AgentLens 配置。"""
+ endpoint: str | None
+ api_key: str | None
+ app_name: str
+ business_scenario: str
+ user: str
+
+ @property
+ def enabled(self) -> bool:
+ return bool(self.endpoint and self.api_key)
+
+
+def project_root(cwd: str | None = None) -> Path:
+ """解析用于查找 `.env` 的项目根目录。"""
+ if cwd:
+ return Path(cwd).expanduser().resolve()
+ env_cwd = str(os.environ.get("CODEBUDDY_PROJECT_DIR") or "").strip()
+ if env_cwd:
+ return Path(env_cwd).expanduser().resolve()
+ return Path.cwd().resolve()
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+ """以轻量方式解析 shell 风格的 env 文件,不做 source。"""
+ values: dict[str, str] = {}
+ if not path.is_file():
+ return values
+ try:
+ lines = path.read_text("utf-8").splitlines()
+ except Exception:
+ return values
+
+ for raw_line in lines:
+ line = raw_line.strip()
+ if not line or line.startswith("#"):
+ continue
+ if line.startswith("export "):
+ line = line[7:].strip()
+ if "=" not in line:
+ continue
+ key, value = line.split("=", 1)
+ key = key.strip()
+ value = value.strip()
+ if not key:
+ continue
+ if value and value[0] == value[-1] and value[0] in {"'", '"'}:
+ value = value[1:-1]
+ values[key] = value
+ return values
+
+
+def load_config(project_root_path: Path) -> AgentLensConfig:
+ """按优先级加载配置:进程环境变量 > `.env.local` > `.env`。"""
+ env_file = read_env_file(project_root_path / ".env")
+ env_local_file = read_env_file(project_root_path / ".env.local")
+
+ def _value(name: str, default: str | None = None) -> str | None:
+ env_value = os.environ.get(name)
+ if env_value is not None and str(env_value).strip():
+ return str(env_value).strip()
+ if name in env_local_file and str(env_local_file[name]).strip():
+ return str(env_local_file[name]).strip()
+ if name in env_file and str(env_file[name]).strip():
+ return str(env_file[name]).strip()
+ return default
+
+ user = _value("ZHIYANLLM_USER")
+ if not user:
+ user = (
+ str(os.environ.get("USER") or "").strip()
+ or str(os.environ.get("USERNAME") or "").strip()
+ or getpass.getuser()
+ )
+
+ return AgentLensConfig(
+ endpoint=_value("ZHIYANLLM_API_ENDPOINT"),
+ api_key=_value("ZHIYANLLM_API_KEY"),
+ app_name=_value("ZHIYANLLM_APP_NAME", DEFAULT_APP_NAME) or DEFAULT_APP_NAME,
+ business_scenario=_value("ZHIYANLLM_BUSINESS_SCENARIO", DEFAULT_BUSINESS_SCENARIO)
+ or DEFAULT_BUSINESS_SCENARIO,
+ user=user or "unknown",
+ )
+
+
+def load_runtime() -> dict[str, Any] | None:
+ """延迟导入可选的 zhiyan 运行时组件。
+
+ 即使本地没有安装 AgentLens 依赖,hook 主链路也必须继续工作,
+ 所以这里返回 ``None``,而不是把导入异常抛出去。
+ """
+ global _RUNTIME
+ if _RUNTIME is not None:
+ return _RUNTIME
+ try:
+ from zhiyanllm import Zhiyanllm
+ from zhiyanllm.opentelemetry.instrumentation.semconv_ai import (
+ SpanAttributes as ZhiyanSpanAttributes,
+ ZhiyanllmSpanKindValues,
+ )
+ from zhiyanllm.tracing.context_manager import get_tracer
+ from zhiyanllm.tracing.manual import track_llm_call, track_task_server_call
+ from zhiyanllm.tracing.tracing import TracerWrapper
+ from opentelemetry.context import attach as otel_attach, detach as otel_detach
+ except Exception:
+ _RUNTIME = None
+ return None
+
+ _RUNTIME = {
+ "Zhiyanllm": Zhiyanllm,
+ "track_llm_call": track_llm_call,
+ "track_task_server_call": track_task_server_call,
+ "TracerWrapper": TracerWrapper,
+ "get_tracer": get_tracer,
+ "ZhiyanSpanAttributes": ZhiyanSpanAttributes,
+ "ZhiyanllmSpanKindValues": ZhiyanllmSpanKindValues,
+ "otel_attach": otel_attach,
+ "otel_detach": otel_detach,
+ }
+ return _RUNTIME
+
+
+def ensure_initialized(config: AgentLensConfig) -> dict[str, Any] | None:
+ """仅当有效配置签名发生变化时才重新初始化 zhiyan。"""
+ global _INIT_SIGNATURE
+ if not config.enabled:
+ return None
+ runtime = load_runtime()
+ if runtime is None:
+ return None
+ signature = (str(config.endpoint), str(config.api_key), str(config.app_name))
+ if _INIT_SIGNATURE == signature:
+ return runtime
+ runtime["Zhiyanllm"].init(
+ app_name=str(config.app_name),
+ api_endpoint=str(config.endpoint),
+ api_key=str(config.api_key),
+ disable_batch=True,
+ )
+ _INIT_SIGNATURE = signature
+ return runtime
+
+
+def project_root_from_state_path(state_path: Path) -> Path:
+ """尽力从 `logs/.state.json` 反推出项目根目录。"""
+ try:
+ current = state_path.resolve().parent
+ for parent in [current, *current.parents]:
+ if parent.name == ".codebuddy":
+ return parent.parent
+ return state_path.resolve().parents[4]
+ except Exception:
+ return Path.cwd().resolve()
+
+
+def debug_enabled(state_path: Path) -> bool:
+ """判断是否要把 span 调试信息镜像写入 `agentlens-push-debug.ndjson`。"""
+ root = project_root_from_state_path(state_path)
+ env_file = read_env_file(root / ".env")
+ env_local_file = read_env_file(root / ".env.local")
+ raw = (
+ os.environ.get("AGENTLENS_PUSH_DEBUG")
+ or env_local_file.get("AGENTLENS_PUSH_DEBUG")
+ or env_file.get("AGENTLENS_PUSH_DEBUG")
+ or ""
+ )
+ return str(raw).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def debug_write_span(
+ state_path: Path | None,
+ sid: str | None,
+ payload: dict[str, Any],
+ *,
+ sanitizer,
+) -> None:
+ """在开启 AgentLens 调试模式时追加写入清洗后的调试记录。"""
+ if state_path is None or not sid:
+ return
+ try:
+ if not debug_enabled(state_path):
+ return
+ debug_path = state_path.parent / "agentlens-push-debug.ndjson"
+ record = {"sid": sid, **sanitizer(payload)}
+ with debug_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+ except Exception:
+ return
+
+
+def set_failure(state_path: Path, sid: str, message: str) -> None:
+ """记录最近一次 AgentLens 失败,但不打断 hook 主流程。"""
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": False, "last_error": str(message)},
+ )
+
+
+def get_session_context(state_path: Path, sid: str) -> dict[str, Any]:
+ """从共享状态里读取 AgentLens sidecar 的 session payload。"""
+ return st.load_agentlens_session(state_path, sid)
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agentlens/normalize.py b/.codebuddy/skills/agent-observability/scripts/core/agentlens/normalize.py
new file mode 100644
index 00000000..2b730f06
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agentlens/normalize.py
@@ -0,0 +1,323 @@
+from __future__ import annotations
+"""AgentLens 负载清洗层。
+
+这一层负责“清洗与整形”:
+- 在发送或调试前把任意 payload 转成安全的 JSON 结构
+- 把本地 token 结构归一化成类似 OpenAI 的 usage 结构
+- 从 transcript 中重建轻量的 message / tool-call 上下文
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig
+
+
+def sanitize_payload(value: Any) -> Any:
+ """把任意 Python 值转换成适合调试/打点的 JSON 安全结构。"""
+ try:
+ return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+ except Exception:
+ return str(value)
+
+
+def association_properties(config: AgentLensConfig, sid: str, state_path: Path | None = None) -> dict[str, str]:
+ """构造 trace 级关联属性,并允许按 turn 覆盖业务场景。"""
+ scenario = config.business_scenario
+ if state_path:
+ try:
+ session_ctx = st.load_agentlens_session(state_path, sid)
+ turn_scenario = session_ctx.get("_turn_business_scenario")
+ if isinstance(turn_scenario, str) and turn_scenario.strip():
+ scenario = turn_scenario.strip()
+ except Exception:
+ pass
+ return {
+ "session_id": sid,
+ "business_scenario": scenario,
+ "user": config.user,
+ }
+
+
+def to_openai_usage(tokens: dict[str, Any] | None) -> dict[str, int]:
+ """把本地 token 结构转换成 zhiyan 期望的 usage 形状。"""
+ if not isinstance(tokens, dict):
+ return {}
+
+ def _int(v: Any) -> int:
+ try:
+ return int(v or 0)
+ except Exception:
+ return 0
+
+ prompt = _int(tokens.get("input"))
+ completion = _int(tokens.get("output"))
+ if prompt <= 0 and completion <= 0:
+ return {}
+ return {"prompt_tokens": prompt, "completion_tokens": completion, "total_tokens": prompt + completion}
+
+
+def infer_vendor(model: str | None) -> str:
+ """根据模型名推断一个粗粒度的 provider/vendor 标签。"""
+ text = str(model or "").strip().lower()
+ if not text:
+ return "unknown"
+ if "gpt" in text or "openai" in text:
+ return "openai"
+ if "claude" in text or "anthropic" in text:
+ return "anthropic"
+ if "gemini" in text or "google" in text:
+ return "google"
+ if text.startswith("hy") or "hunyuan" in text:
+ return "tencent"
+ return text.split("/", 1)[0].split("-", 1)[0] or "unknown"
+
+
+def extract_message_text(content: Any) -> str:
+ """把嵌套的 transcript message 内容压平成纯文本。"""
+ if content is None:
+ return ""
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts: list[str] = []
+ for item in content:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif item.get("type") == "tool_use":
+ parts.append(f"[tool_use {item.get('name', '')}]")
+ elif item.get("type") == "tool_result":
+ parts.append(extract_message_text(item.get("content")))
+ else:
+ parts.append(str(item))
+ return "\n".join(p for p in parts if p)
+ if isinstance(content, dict):
+ return extract_message_text(content.get("text") or content.get("content"))
+ return str(content)
+
+
+def find_message_id_in_record(obj: Any) -> str | None:
+ """在 transcript 记录里递归查找稳定的 message 标识。"""
+ message_id_keys = ("messageId", "responseId", "requestId")
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in message_id_keys:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in message_id_keys:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in message_id_keys:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for value in obj.values():
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ elif isinstance(obj, list):
+ for value in obj:
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ return None
+
+
+def collect_tool_calls_for_message(transcript_path: str, message_id: str) -> list[dict[str, Any]]:
+ """为指定 assistant message 重建它挂载的 tool-call 摘要。"""
+ if not transcript_path or not message_id or not os.path.isfile(transcript_path):
+ return []
+ try:
+ with open(transcript_path, "rb") as fp:
+ blob = fp.read()
+ except Exception:
+ return []
+
+ tool_calls: list[dict[str, Any]] = []
+ for raw_line in blob.splitlines(keepends=True):
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("type") or "").strip().lower() != "function_call":
+ continue
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid != message_id:
+ continue
+ call_id = str(rec.get("callId") or "").strip()
+ name = str(rec.get("name") or "").strip()
+ arguments = rec.get("arguments")
+ entry: dict[str, Any] = {"id": call_id, "name": name}
+ if arguments is not None:
+ entry["arguments"] = arguments if isinstance(arguments, str) else json.dumps(arguments, ensure_ascii=False)
+ tool_calls.append(entry)
+ return tool_calls
+
+
+def find_tool_usage_event(tool_event: dict[str, Any], usage_events: list[dict[str, Any]]) -> dict[str, Any] | None:
+ """从 usage 列表里挑出最可能属于当前 tool 事件的那一条。"""
+ tool_name = str(tool_event.get("tool") or "")
+ transcript_path = str(tool_event.get("transcript_path") or "")
+ agent = str(tool_event.get("agent") or "main")
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ if tool_name and str(usage_event.get("tool") or "") not in {tool_name, "model_request"}:
+ continue
+ if str(usage_event.get("message_id") or "").strip():
+ return usage_event
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ return usage_event
+ return None
+
+
+def build_llm_io_from_transcript(
+ *,
+ transcript_path: str,
+ source_offset: int,
+ tokens: dict[str, Any] | None,
+ model: str | None,
+ start_offset: int = 0,
+ current_message_id: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], str]:
+ """从 transcript 历史中构造紧凑版的 LLM 输入/输出负载。"""
+ input_data: dict[str, Any] = {"model": str(model or "unknown"), "messages": []}
+ output_data: dict[str, Any] = {"choices": [], "usage": to_openai_usage(tokens)}
+ if not transcript_path or not os.path.isfile(transcript_path):
+ return input_data, output_data, ""
+ try:
+ with open(transcript_path, "rb") as fp:
+ fp.seek(0)
+ blob = fp.read(source_offset) if source_offset else fp.read()
+ except Exception:
+ return input_data, output_data, ""
+
+ messages: list[dict[str, Any]] = []
+ system_prompts: list[str] = []
+ cursor = 0
+ last_asst_text: str | None = None
+
+ def _truncate(text: str, limit: int = 4000) -> str:
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ for raw_line in blob.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+
+ rec_type = str(rec.get("type") or "").strip().lower()
+ is_incremental = cursor > start_offset
+
+ # 重建 prompt 上下文时要跳过“当前正在发出的 assistant message”,
+ # 否则同一段回复会同时出现在 input 和 output 两边。
+ if current_message_id and is_incremental:
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid == current_message_id:
+ if rec_type == "message" and rec.get("role") == "assistant":
+ text = extract_message_text(rec.get("content"))
+ if text:
+ last_asst_text = text
+ continue
+
+ if rec_type == "message":
+ role = rec.get("role")
+ text = extract_message_text(rec.get("content"))
+ if not text:
+ continue
+ if role == "system":
+ system_prompts.append(text)
+ elif is_incremental:
+ if role == "user":
+ messages.append({"role": "user", "content": _truncate(text, 8000)})
+ last_asst_text = None
+ elif role == "assistant":
+ messages.append({"role": "assistant", "content": _truncate(text, 4000)})
+ last_asst_text = text
+ elif is_incremental:
+ # 把 function call / result 记录转换成 Chat Completions 风格的
+ # assistant/tool message,方便 tracing UI 按对话链路展示。
+ if rec_type == "function_call":
+ name = str(rec.get("name") or "").strip()
+ call_id = str(rec.get("callId") or "").strip()
+ arguments = rec.get("arguments", "")
+ if isinstance(arguments, dict):
+ arguments = json.dumps(arguments, ensure_ascii=False)
+ tool_call: dict[str, Any] = {"type": "function", "function": {"name": name}}
+ if name and arguments:
+ tool_call["function"]["arguments"] = _truncate(str(arguments), 2000)
+ if call_id:
+ tool_call["id"] = call_id
+ if (
+ messages
+ and messages[-1].get("role") == "assistant"
+ and "tool_calls" not in messages[-1]
+ and messages[-1].get("content")
+ ):
+ messages[-1]["tool_calls"] = [tool_call]
+ else:
+ msg: dict[str, Any] = {"role": "assistant", "content": ""}
+ msg["tool_calls"] = [tool_call]
+ messages.append(msg)
+ elif rec_type == "function_call_result":
+ call_id = str(rec.get("callId") or "").strip()
+ provider = rec.get("providerData", {})
+ result_content = ""
+ if isinstance(provider, dict):
+ tool_result = provider.get("toolResult", {})
+ if isinstance(tool_result, dict):
+ result_content = extract_message_text(tool_result.get("content"))
+ if not result_content:
+ output = rec.get("output")
+ result_content = str(output.get("text", "")) if isinstance(output, dict) else ""
+ tool_msg: dict[str, Any] = {"role": "tool", "content": _truncate(result_content, 2000)}
+ if call_id:
+ tool_msg["tool_call_id"] = call_id
+ messages.append(tool_msg)
+
+ final_messages: list[dict[str, Any]] = []
+ for prompt in system_prompts[-2:]:
+ if prompt:
+ final_messages.append({"role": "system", "content": _truncate(prompt, 2000)})
+ final_messages.extend(messages)
+ input_data["messages"] = final_messages
+
+ if last_asst_text is not None:
+ output_data["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": last_asst_text[:8000]},
+ }]
+
+ return input_data, output_data, ""
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agentlens/runtime.py b/.codebuddy/skills/agent-observability/scripts/core/agentlens/runtime.py
new file mode 100644
index 00000000..321f45a9
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agentlens/runtime.py
@@ -0,0 +1,761 @@
+"""AgentLens 运行时编排层。
+
+这一层保留对外暴露的 4 个入口:
+- `emit_session_start`
+- `emit_turn_start`
+- `emit_post_step`
+- `emit_session_stop`
+
+它本身不负责底层清洗或 carrier 生成,而是把调用编排到
+`bootstrap / normalize / tracing` 三层上。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from opentelemetry import trace as _otel_trace
+
+from .. import state as st
+from .bootstrap import (
+ debug_write_span as _debug_write_span,
+ ensure_initialized as _ensure_initialized,
+ get_session_context as _get_session_context,
+ load_config,
+ project_root as _project_root,
+ set_failure as _set_failure,
+)
+from .normalize import (
+ association_properties as _association_properties,
+ build_llm_io_from_transcript as _build_llm_io_from_transcript,
+ find_tool_usage_event as _find_tool_usage_event,
+ infer_vendor as _infer_vendor,
+ sanitize_payload as _sanitize_payload,
+ to_openai_usage as _to_openai_usage,
+)
+from .tracing import (
+ annotate as _annotate,
+ emit_assistant_span as _emit_assistant_span,
+ emit_tool_span as _emit_tool_span,
+ generate_subagent_carrier as _generate_subagent_carrier,
+ generate_turn_carrier as _generate_turn_carrier,
+ resolve_agent_carrier as _resolve_agent_carrier,
+ resolve_step_carrier as _resolve_step_carrier,
+ set_agent_aggregate_on_span as _set_agent_aggregate_on_span,
+ span_context_ids as _span_context_ids,
+ traceparent_parts as _traceparent_parts,
+)
+
+
+def emit_session_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ agent: str = "main",
+) -> None:
+ """初始化 v2 版本的 `_agentlens` session payload。
+
+ 在 turn-centric 模型下,这里**不再**生成 trace_id。
+ 它只负责记录 session 级元数据(如 `enabled`、`session_id`、`app_name`),
+ 并清理上一次运行遗留的 carrier / error 状态。
+ 真正的新 trace 会在第一次 `UserPromptSubmit` 时由 `emit_turn_start` 打开。
+ """
+ _ = agent
+ config = load_config(_project_root(cwd))
+ # 注意:这里不要清空 current_turn / turn_history。
+ # 同一个 sid 下 SessionStart 可能多次触发(例如 subagent 启动、IDE 刷新、
+ # workspace 切换)。如果这里清空,会把进行中的 turn 擦掉,后续 PostToolUse
+ # 会全部看到 no_active_turn,最终把这一轮观测链路打断。
+ base_updates: dict[str, Any] = {
+ "session_id": sid,
+ "app_name": config.app_name,
+ }
+ if not config.enabled:
+ base_updates["enabled"] = False
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ base_updates["enabled"] = True
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_turn_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ turn_id: str,
+ prompt_meta: dict[str, Any] | None = None,
+ business_scenario: str | None = None,
+) -> None:
+ """打开一个新的 turn,生成新的 trace_id 并写入 `_agentlens.current_turn`。
+
+ 这是当前实现里**唯一**允许生成新 trace_id 的地方。
+ `emit_post_step` / `emit_session_stop` 都不会重新造 carrier;
+ 找不到时只会优雅降级,不会私自开新链路。
+ """
+ _ = prompt_meta
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ # 先把 per-turn business scenario 写进 state,
+ # 这样 `_generate_turn_carrier -> _association_properties`
+ # 才能在生成 trace 时把这次 turn 的业务场景烘焙进去。
+ if business_scenario:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name, "_turn_business_scenario": business_scenario},
+ clear_keys=["last_error"],
+ )
+ else:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name},
+ clear_keys=["last_error", "_turn_business_scenario"],
+ )
+ carrier = _generate_turn_carrier(runtime, config=config, sid=sid, turn_id=turn_id, state_path=state_path)
+ st.begin_turn(state_path, sid, turn_id, carrier)
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_post_step(
+ *,
+ state_path: Path,
+ sid: str,
+ tool_event: dict[str, Any] | None,
+ usage_events: list[dict[str, Any]],
+) -> None:
+ """发出扁平化的 LLM span,只保留最小 TASK 包装层来传播 carrier 上下文。
+
+ 面向 turn 的 v2 约束:
+ - 活跃的 ``current_turn.carrier`` 是唯一的 trace 上下文来源。
+ - 如果不存在 ``current_turn``(例如 UserPromptSubmit hook 还没触发),
+ 这里只会记录 ``last_error`` 并返回,不会私自生成新的 trace_id。
+ - subagent(``active_agent != "main"``)会拿到当前 turn 下的
+ ``invoke_agent`` 子 span,后续 chat span 都挂到这个子 span 下,
+ 以保持因果链路连续。
+ """
+ if not isinstance(tool_event, dict) and not usage_events:
+ return
+
+ cwd_hint = ""
+ if isinstance(tool_event, dict):
+ cwd_hint = str(tool_event.get("cwd") or "")
+ config = load_config(_project_root(cwd_hint))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ # 快路径:尊重 SessionStart 阶段已经写入的 enabled 标记。
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ parent_carrier = current_turn.get("carrier")
+ if not isinstance(parent_carrier, dict) or not parent_carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ tool_name = str((tool_event or {}).get("tool") or "unknown_tool")
+ active_agent = str((tool_event or {}).get("agent") or "main")
+ transcript_path = str((tool_event or {}).get("transcript_path") or "")
+ skills = (tool_event or {}).get("skill") or []
+ rules = (tool_event or {}).get("rule") or []
+
+ # 解析这次事件真正要用的 carrier。
+ # main agent 直接使用 turn 根 carrier;subagent 则使用按角色拆分的
+ # 子 span carrier,并在当前 turn 下做幂等注册。
+ carrier = dict(parent_carrier)
+ if active_agent and active_agent != "main":
+ existing = None
+ subs = current_turn.get("subagent_spans")
+ if isinstance(subs, dict):
+ rec = subs.get(active_agent)
+ if isinstance(rec, dict) and isinstance(rec.get("carrier"), dict):
+ existing = rec["carrier"]
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ carrier = dict(existing)
+ else:
+ # 原子化的 get-or-create:只有确认 subagent span 不存在时,
+ # 才会在写锁内部调用 carrier_factory。
+ # 这样可以避免并发 hook 进程之间的 TOCTOU 竞争,产生孤儿
+ # invoke_agent.TASK span。
+ def _factory() -> dict[str, str]:
+ return _generate_subagent_carrier(
+ runtime, parent_carrier=parent_carrier, role=active_agent
+ )
+
+ registered = st.upsert_subagent_span_atomic(
+ state_path, sid, active_agent, carrier_factory=_factory
+ )
+ if isinstance(registered, dict) and registered.get("traceparent"):
+ carrier = dict(registered)
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ # 静默挂载 carrier 上下文(不额外创建 TASK span),让内部 span
+ # 继承正确的 trace_id / parent_id。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ preferred_tool_message_id = str((tool_event or {}).get("message_id") or "").strip() or None
+ _assistant_emitted_mids: set[str] = set()
+ pre_bumped_steps: set[tuple[str, str]] = set()
+ committed_steps: set[tuple[str, str]] = set()
+
+ if isinstance(tool_event, dict):
+ if preferred_tool_message_id and st.get_step_span_carrier(
+ state_path, sid, active_agent, preferred_tool_message_id
+ ) is None:
+ pre_bumped_steps.add((active_agent, preferred_tool_message_id))
+ for usage_event in usage_events:
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ if event_message_id:
+ step_key = (event_agent, event_message_id)
+ if (
+ step_key not in pre_bumped_steps
+ and st.get_step_span_carrier(state_path, sid, event_agent, event_message_id) is None
+ ):
+ pre_bumped_steps.add(step_key)
+ if not usage_events and isinstance(tool_event, dict):
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if preferred_tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=preferred_tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=preferred_tool_message_id,
+ step_grouping="message_id" if preferred_tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if (
+ preferred_tool_message_id
+ and (active_agent, preferred_tool_message_id) in pre_bumped_steps
+ and (active_agent, preferred_tool_message_id) not in committed_steps
+ ):
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add((active_agent, preferred_tool_message_id))
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ return
+
+ matched_usage = _find_tool_usage_event(tool_event, usage_events) if isinstance(tool_event, dict) else None
+ tool_message_id = preferred_tool_message_id or str((matched_usage or {}).get("message_id") or "").strip() or None
+ if isinstance(tool_event, dict):
+ # 先构造 assistant 预览,再打开 agent/step 父 span。
+ # 这样即便 transcript 重建失败,也不会留下空的分组 TASK。
+ _assistant_preview_content: str | None = None
+ _assistant_preview_transcript = transcript_path
+ _assistant_preview_model = ""
+ if tool_message_id:
+ for _ue in usage_events:
+ if str(_ue.get("message_id") or "").strip() != tool_message_id:
+ continue
+ _ue_transcript = str(_ue.get("transcript_path") or transcript_path)
+ _ue_offset = int(_ue.get("source_offset") or 0)
+ _, _llm_out_pre, _ = _build_llm_io_from_transcript(
+ transcript_path=_ue_transcript,
+ source_offset=_ue_offset,
+ tokens=_ue.get("tokens"),
+ model=str(_ue.get("model") or ""),
+ )
+ _pre_content = ""
+ if _llm_out_pre.get("choices"):
+ _pre_msg = _llm_out_pre["choices"][0].get("message") or {}
+ _pre_content = str(_pre_msg.get("content") or "")
+ if _pre_content and _pre_content.strip():
+ _assistant_preview_content = _pre_content
+ _assistant_preview_transcript = _ue_transcript
+ _assistant_preview_model = str(_ue.get("model") or "")
+ break
+
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ if _assistant_preview_content and tool_message_id:
+ _emit_assistant_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ assistant_text=_assistant_preview_content,
+ model=_assistant_preview_model,
+ transcript_path=_assistant_preview_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ _assistant_emitted_mids.add(tool_message_id)
+
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=tool_message_id,
+ step_grouping="message_id" if tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if tool_message_id and (active_agent, tool_message_id) in pre_bumped_steps:
+ step_key = (active_agent, tool_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+
+ _prev_llm_offsets: dict[str, int] = {}
+ for usage_event in usage_events:
+ model = str(usage_event.get("model") or "")
+ ev_transcript = str(usage_event.get("transcript_path") or transcript_path)
+ ev_offset = int(usage_event.get("source_offset") or 0)
+ raw_tokens = usage_event.get("tokens") or {}
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ start_offset = _prev_llm_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_llm_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset)
+ # --- 把 skill/rule/agent 作为独立消息标签注入 input_data ---
+ _meta_messages: list[dict[str, str]] = []
+ _ev_agent = str(usage_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ _meta_messages.append({"role": "agent", "content": _ev_agent})
+ if skills:
+ _meta_messages.append({"role": "skill", "content": ", ".join(skills)})
+ if rules:
+ _meta_messages.append({"role": "rule", "content": ", ".join(rules)})
+ if _meta_messages:
+ llm_input.setdefault("messages", [])
+ for msg in reversed(_meta_messages):
+ llm_input["messages"].insert(0, msg)
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 只附带成本细节来构造 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": usage_event.get("cost_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ if event_message_id:
+ event_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 先累计聚合值,再发 LLM span,这样 span 上带的是最新累计属性。
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ usage_event=usage_event,
+ )
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(usage_event.get("cost_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if event_message_id and (event_agent, event_message_id) in pre_bumped_steps:
+ step_key = (event_agent, event_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+ if _existing_content and _existing_content.strip() and event_message_id not in _assistant_emitted_mids:
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_session_stop(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str,
+ transcript_path: str,
+ stop_events: list[dict[str, Any]],
+) -> None:
+ """在 session stop 阶段发出扁平化 LLM span,只保留最小 TASK 包装层传播上下文。"""
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ carrier = current_turn.get("carrier")
+ if not isinstance(carrier, dict) or not carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ if not stop_events:
+ return
+ # 静默挂载 carrier 上下文(不额外创建 TASK span)。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ _prev_stop_offsets: dict[str, int] = {}
+ for stop_event in stop_events:
+ model = str(stop_event.get("model") or "")
+ ev_transcript = str(stop_event.get("transcript_path") or transcript_path)
+ ev_offset = int(stop_event.get("source_offset") or 0)
+ raw_tokens = stop_event.get("tokens") or {}
+ event_message_id = str(stop_event.get("message_id") or "").strip() or None
+ event_agent = str(stop_event.get("agent") or active_agent or "main")
+ start_offset = _prev_stop_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_stop_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset_stop(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset_stop)
+ # --- 把 agent 作为独立消息标签注入 input_data ---
+ _ev_agent = str(stop_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ llm_input.setdefault("messages", []).insert(0, {"role": "agent", "content": _ev_agent})
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 构造带上下文和成本细节的 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": stop_event.get("cost_usd"),
+ "cost_session_usd": stop_event.get("cost_session_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ # 先解析 agent carrier,让 step 挂在 agent 的 react_agent span 下,
+ # 而不是直接挂在 turn 根 span 下。
+ if event_agent and event_agent != "main":
+ agent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ if isinstance(agent_carrier, dict) and agent_carrier.get("traceparent"):
+ event_parent_carrier = dict(agent_carrier)
+ if event_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 这里不要再 bump,emit_post_step 已经累计过这条 usage_event。
+ # SessionStop 会为同一次调用补发一个重复的 LLM span,再累加就会双算。
+ # 因此这里只读取当前聚合值。
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(stop_event.get("cost_usd") or "-"),
+ "cost_session_usd": str(stop_event.get("cost_session_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if _existing_content and _existing_content.strip():
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
diff --git a/.codebuddy/skills/agent-observability/scripts/core/agentlens/tracing.py b/.codebuddy/skills/agent-observability/scripts/core/agentlens/tracing.py
new file mode 100644
index 00000000..afb678ad
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/agentlens/tracing.py
@@ -0,0 +1,504 @@
+from __future__ import annotations
+"""AgentLens trace 拓扑层。
+
+这一层负责“trace 结构本身”:
+- 创建或派生 carrier
+- 生成 agent / step / assistant / tool span
+- 把后续聚合需要的 span 元数据写回 state
+"""
+
+import json
+import secrets
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig, debug_write_span
+from .normalize import association_properties, collect_tool_calls_for_message, sanitize_payload
+
+
+def annotate(runtime: dict[str, Any], *, span: Any | None = None, input_data: Any = None, output_data: Any = None, tags: dict[str, Any] | None = None) -> None:
+ """在调用 zhiyan annotate 前,先统一清洗 payload。"""
+ _ = span
+ runtime["Zhiyanllm"].annotate(
+ input_data=sanitize_payload(input_data),
+ output_data=sanitize_payload(output_data),
+ tags=sanitize_payload(tags) if tags else None,
+ )
+
+
+def traceparent_parts(carrier: dict[str, str] | None) -> dict[str, str]:
+ """把 W3C `traceparent` 拆成调试日志里常用的几个字段。"""
+ traceparent = str((carrier or {}).get("traceparent") or "").strip()
+ parts = traceparent.split("-")
+ if len(parts) >= 4:
+ return {
+ "traceparent": traceparent,
+ "trace_id": parts[1],
+ "span_id": parts[2],
+ "flags": parts[3],
+ }
+ return {"traceparent": traceparent}
+
+
+def span_context_ids(span: Any) -> dict[str, str]:
+ """从 OTel span 对象中提取十六进制的 trace/span id。"""
+ try:
+ ctx = span.get_span_context()
+ return {
+ "trace_id": f"{int(ctx.trace_id):032x}",
+ "span_id": f"{int(ctx.span_id):016x}",
+ }
+ except Exception:
+ return {}
+
+
+def ensure_traceparent(carrier: dict[str, str]) -> None:
+ """当上游没有成功注入时,补一个最小可用的 `traceparent`。"""
+ if str(carrier.get("traceparent") or "").strip():
+ return
+ trace_id = secrets.token_hex(16)
+ parent_id = secrets.token_hex(8)
+ carrier["traceparent"] = f"00-{trace_id}-{parent_id}-01"
+
+
+def carrier_from_span(parent_carrier: dict[str, str], span: Any) -> dict[str, str]:
+ """基于父 carrier 和当前 span 生成一个仍在同一 trace 上的子 carrier。"""
+ try:
+ span_ctx = span.get_span_context()
+ trace_id = f"{int(span_ctx.trace_id):032x}"
+ span_id = f"{int(span_ctx.span_id):016x}"
+ except Exception:
+ return {}
+ parent_tp = str((parent_carrier or {}).get("traceparent") or "").strip()
+ flags = "01"
+ if parent_tp:
+ parts = parent_tp.split("-")
+ if len(parts) >= 4 and parts[3]:
+ flags = parts[3]
+ child_carrier: dict[str, str] = dict(parent_carrier or {})
+ child_carrier["traceparent"] = f"00-{trace_id}-{span_id}-{flags}"
+ return child_carrier
+
+
+def carrier_from_task_span(parent_carrier: dict[str, str], task_span: Any) -> dict[str, str]:
+ """兼容包装过的 task span 和原始 OTel span 两种形态。"""
+ span = getattr(task_span, "_span", None)
+ if span is None and hasattr(task_span, "get_span_context"):
+ span = task_span
+ if span is None:
+ return {}
+ return carrier_from_span(parent_carrier, span)
+
+
+def zhiyan_attr(runtime: dict[str, Any], name: str, fallback: str) -> str:
+ """防御式读取 zhiyan 语义约定常量。"""
+ return str(getattr(runtime.get("ZhiyanSpanAttributes"), name, fallback))
+
+
+def generate_turn_carrier(
+ runtime: dict[str, Any],
+ *,
+ config: AgentLensConfig,
+ sid: str,
+ turn_id: str,
+ state_path: Path | None = None,
+) -> dict[str, str]:
+ """为一个用户 turn 生成根 carrier。"""
+ from opentelemetry import trace
+
+ carrier: dict[str, str] = {}
+ span = trace.get_tracer(__name__).start_span(f"turn.{sid}.{turn_id}")
+ try:
+ runtime["Zhiyanllm"].set_association_properties(association_properties(config, sid, state_path))
+ runtime["Zhiyanllm"].inject_context(carrier)
+ finally:
+ span.end()
+ ensure_traceparent(carrier)
+ return carrier
+
+
+def generate_subagent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], role: str) -> dict[str, str]:
+ """在当前 turn 下面创建 `invoke_agent` 子 carrier。"""
+ try:
+ with runtime["track_task_server_call"]("invoke_agent", carrier=parent_carrier) as task_span:
+ annotate(runtime, input_data={"agent": role}, output_data={"result": "dispatched"}, tags={"agent": role})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_step_carrier(
+ runtime: dict[str, Any],
+ *,
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str,
+ transcript_path: str,
+) -> dict[str, str]:
+ """创建用于归并同一条 message 工作的 synthetic step span。"""
+ try:
+ with runtime["track_task_server_call"]("react_step", carrier=parent_carrier) as task_span:
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id},
+ output_data={"result": "grouped"},
+ tags={"message_id": message_id, "agent": agent, "transcript_path": transcript_path or ""},
+ )
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_agent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], agent: str) -> dict[str, str]:
+ """在当前 turn 下创建稳定的 per-agent 聚合 span。"""
+ try:
+ with runtime["track_task_server_call"]("react_agent", carrier=parent_carrier) as task_span:
+ span = getattr(task_span, "_span", None)
+ if span is not None and hasattr(span, "set_attribute"):
+ span.set_attribute("agent.name", agent)
+ annotate(runtime, input_data={"agent": agent}, output_data={"agent": agent}, tags={"agent": agent})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def resolve_agent_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+) -> dict[str, str]:
+ """从共享状态里获取或创建持久化的 agent 聚合 carrier。"""
+ normalized_agent = str(agent or "main").strip() or "main"
+ existing = st.get_agent_span_carrier(state_path, sid, normalized_agent)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_agent_carrier(runtime, parent_carrier=parent_carrier, agent=normalized_agent)
+
+ effective_carrier = st.upsert_agent_span_atomic(state_path, sid, normalized_agent, carrier_factory=_factory)
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return dict(parent_carrier)
+ agent_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "agent",
+ "span_name": "react_agent",
+ "agent": normalized_agent,
+ "trace_id": agent_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": agent_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def resolve_step_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ transcript_path: str,
+) -> dict[str, str] | None:
+ """获取或创建按 message 分组使用的 step carrier。"""
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return None
+ existing = st.get_step_span_carrier(state_path, sid, agent, normalized_message_id)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_step_carrier(
+ runtime,
+ parent_carrier=parent_carrier,
+ agent=agent,
+ message_id=normalized_message_id,
+ transcript_path=transcript_path,
+ )
+
+ effective_carrier = st.upsert_step_span_atomic(
+ state_path,
+ sid,
+ agent,
+ normalized_message_id,
+ carrier_factory=_factory,
+ transcript_path=transcript_path,
+ )
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return None
+ step_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "step",
+ "span_name": "react_step",
+ "message_id": normalized_message_id,
+ "agent": agent,
+ "trace_id": step_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": step_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": transcript_path or "",
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def set_agent_aggregate_on_span(span: Any, aggregate: dict[str, Any] | None) -> None:
+ """把 agent 的累计指标投影成当前 span 的属性。"""
+ if span is None or not hasattr(span, "set_attribute") or not isinstance(aggregate, dict):
+ return
+ tokens = aggregate.get("tokens") or {}
+ if isinstance(tokens, dict):
+ for key in ("input", "output", "cache_read", "cache_creation", "total"):
+ if key in tokens:
+ span.set_attribute(f"agent.cumulative_tokens.{key}", int(tokens.get(key) or 0))
+ for key in ("cost_usd", "tool_duration_ms", "llm_call_count", "tool_call_count", "step_count", "event_count"):
+ if key in aggregate:
+ try:
+ span.set_attribute(f"agent.cumulative.{key}", int(aggregate.get(key) or 0))
+ except (TypeError, ValueError):
+ span.set_attribute(f"agent.cumulative.{key}", str(aggregate.get(key)))
+
+
+def emit_assistant_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ assistant_text: str,
+ model: str | None = None,
+ transcript_path: str | None = None,
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出一个轻量 assistant span,并按需补上 tool calls。"""
+ if not assistant_text or not assistant_text.strip():
+ return
+ tool_calls: list[dict[str, Any]] = []
+ if message_id and transcript_path:
+ tool_calls = collect_tool_calls_for_message(transcript_path, message_id)
+ output_data: dict[str, Any] = {"role": "assistant", "content": assistant_text[:8000]}
+ if tool_calls:
+ output_data["tool_calls"] = tool_calls
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name="assistant_message") as span:
+ span.set_attribute(runtime["ZhiyanSpanAttributes"].LLM_SPAN_KIND, runtime["ZhiyanllmSpanKindValues"].LLM.value)
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "assistant",
+ "span_name": "assistant_message",
+ "message_id": str(message_id or ""),
+ "agent": agent,
+ "model": str(model or ""),
+ "tool_call_count": len(tool_calls),
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id or "", "model": model or ""},
+ output_data=output_data,
+ tags={"message_id": str(message_id or ""), "agent": agent},
+ )
+ finally:
+ runtime["otel_detach"](token)
+
+
+def emit_tool_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ tool_name: str,
+ active_agent: str,
+ skills: list[str],
+ rules: list[str],
+ duration_ms: int | None = None,
+ tool_details: dict[str, Any] | None = None,
+ message_id: str | None = None,
+ step_grouping: str = "fallback",
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出 tool span,并以受控大小挂载 tool payload。"""
+ def _truncate(value: Any, limit: int = 1200) -> Any:
+ text = value if isinstance(value, str) else None
+ if text is None:
+ return value
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ def _maybe_parse_json_text(value: Any) -> Any:
+ if not isinstance(value, str):
+ return value
+ text = value.strip()
+ if not text or text[0] not in "{[":
+ return value
+ try:
+ return json.loads(text)
+ except Exception:
+ return value
+
+ def _parse_bash_result_content(value: Any) -> dict[str, Any] | None:
+ if not isinstance(value, str) or "Command:" not in value:
+ return None
+ normalized_value = value.replace("\\n", "\n")
+ markers = [
+ ("Command:", "command"),
+ ("Stdout:", "stdout"),
+ ("Stderr:", "stderr"),
+ ("Exit Code:", "exit_code"),
+ ("Signal:", "signal"),
+ ]
+ parsed: dict[str, Any] = {}
+ for idx, (marker, key) in enumerate(markers):
+ start = normalized_value.find(marker)
+ if start < 0:
+ continue
+ start += len(marker)
+ end = len(normalized_value)
+ for next_marker, _ in markers[idx + 1:]:
+ pos = normalized_value.find(next_marker, start)
+ if pos >= 0:
+ end = min(end, pos)
+ segment = normalized_value[start:end].strip()
+ if not segment:
+ continue
+ parsed[key] = _truncate(segment, 1200 if key in {"command", "stdout", "stderr"} else 200)
+ return parsed or None
+
+ tool_input: dict[str, Any] = {"tool": tool_name, "agent": active_agent}
+ if skills:
+ tool_input["skill"] = ", ".join(skills)
+ if rules:
+ tool_input["rule"] = ", ".join(rules)
+ if message_id:
+ tool_input["message_id"] = message_id
+ details = dict(tool_details or {})
+ call_id = str(details.get("call_id") or "").strip() or None
+ if call_id:
+ tool_input["call_id"] = call_id
+ arguments_display_text = details.get("arguments_display_text")
+ if arguments_display_text:
+ tool_input["arguments_display_text"] = _truncate(arguments_display_text, 600)
+ arguments = details.get("arguments")
+ if arguments:
+ parsed_arguments = _maybe_parse_json_text(arguments)
+ tool_input["arguments"] = _truncate(parsed_arguments, 1200)
+ if isinstance(parsed_arguments, dict):
+ if parsed_arguments.get("command"):
+ tool_input["command"] = _truncate(parsed_arguments.get("command"), 1200)
+ if parsed_arguments.get("description"):
+ tool_input["description"] = _truncate(parsed_arguments.get("description"), 400)
+
+ tool_output: dict[str, Any] = {"result": "executed"}
+ result_content = details.get("result_content")
+ if result_content is not None:
+ structured_result = _parse_bash_result_content(result_content)
+ if structured_result:
+ tool_output["result"] = structured_result
+ else:
+ tool_output["result_content"] = _truncate(result_content, 1600)
+ output_text = details.get("output_text")
+ if output_text:
+ tool_output["output_text"] = _truncate(output_text, 1600)
+ raw_response = details.get("raw_response")
+ if isinstance(raw_response, dict):
+ tool_output["raw_response"] = {
+ "exitCode": raw_response.get("exitCode"),
+ "signal": raw_response.get("signal"),
+ "interrupted": raw_response.get("interrupted"),
+ "sandboxDenied": raw_response.get("sandboxDenied"),
+ "tool_error_code": raw_response.get("tool_error_code"),
+ }
+
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name=f"{tool_name}.TOOL") as span:
+ span_kind_value = runtime["ZhiyanllmSpanKindValues"].TOOL.value
+ span.set_attribute(zhiyan_attr(runtime, "LLM_SPAN_KIND", "gen_ai.span.kind"), span_kind_value)
+ span.set_attribute("gen_ai.span.kind", span_kind_value)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_NAME", "tool.name"), tool_name)
+ if isinstance(tool_details, dict):
+ desc = tool_details.get("description") or tool_details.get("tool_description")
+ if isinstance(desc, str) and desc.strip():
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_DESCRIPTION", "tool.description"), desc.strip())
+ tool_params = tool_input.get("arguments")
+ if tool_params is not None:
+ if not isinstance(tool_params, str):
+ tool_params = json.dumps(tool_params, ensure_ascii=False, default=str)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_PARAMETERS", "tool.parameters"), tool_params)
+ if duration_ms is not None:
+ span.set_attribute("tool.duration_ms", int(duration_ms))
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "tool",
+ "span_name": f"{tool_name}.TOOL",
+ "tool": tool_name,
+ "message_id": str(message_id or ""),
+ "call_id": call_id or "",
+ "step_grouping": step_grouping,
+ "agent": active_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data=tool_input,
+ output_data=tool_output,
+ tags={"step_grouping": step_grouping, "message_id": str(message_id or "")},
+ )
+ finally:
+ runtime["otel_detach"](token)
diff --git a/.codebuddy/skills/agent-observability/scripts/core/cls_sink.py b/.codebuddy/skills/agent-observability/scripts/core/cls_sink.py
new file mode 100644
index 00000000..6525f6ed
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/cls_sink.py
@@ -0,0 +1,470 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import struct
+import subprocess
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .agentlens import bootstrap
+
+
+
+@dataclass(frozen=True)
+class CLSConfig:
+ enabled: bool
+ endpoint: str
+ topic_id: str
+ secret_id: str
+ secret_key: str
+ secret_token: str
+ service_name: str
+ timeout_seconds: int
+ helper_path: Path
+ sdk_entry_path: Path
+
+ @property
+ def ready(self) -> bool:
+ return bool(
+ self.enabled
+ and self.endpoint
+ and self.topic_id
+ and self.secret_id
+ and self.secret_key
+ and self.helper_path.is_file()
+ and self.sdk_entry_path.is_file()
+ )
+
+
+def repo_root() -> Path:
+ return Path(__file__).resolve().parents[5]
+
+
+def helper_path() -> Path:
+ return Path(__file__).with_name("cls_uploader.mjs")
+
+
+def sdk_entry_path() -> Path:
+ return (
+ repo_root()
+ / "cls-codebuddy"
+ / "tencentcloud-cls-sdk-codebuddy"
+ / "node_modules"
+ / "tencentcloud-cls-sdk-js"
+ / "dist"
+ / "index.js"
+ )
+
+
+def debug_log_path() -> Path:
+ return Path(__file__).resolve().parents[2] / "logs" / "cls-push-debug.ndjson"
+
+
+def _value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: str = "",
+ aliases: tuple[str, ...] = (),
+) -> str:
+ keys = (name, *aliases)
+ for key in keys:
+ raw = os.environ.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_local.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_file.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ return default
+
+
+def _enabled_flag(*, env_local: dict[str, str], env_file: dict[str, str]) -> bool:
+ raw = _value(
+ "CLS_CODINGAGENT_ENABLED",
+ env_local=env_local,
+ env_file=env_file,
+ default="1",
+ )
+ return str(raw).strip().lower() not in {"0", "false", "off", "no"}
+
+
+def _debug_write(payload: dict[str, Any]) -> None:
+ try:
+ path = debug_log_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(payload, ensure_ascii=False) + "\n")
+ except Exception:
+ return
+
+
+# ---- CLS PutLogs 的 protobuf 编码 ----
+# CLS 使用了简化版 protobuf:
+# LogGroup { repeated Log logs = 1; optional string filename = 2; }
+# Log { optional uint32 time = 1; repeated Content contents = 2; }
+# Content { optional string key = 1; optional string value = 2; }
+
+def _encode_varint(value: int) -> bytes:
+ result = b""
+ while value > 0x7F:
+ result += bytes([(value & 0x7F) | 0x80])
+ value >>= 7
+ result += bytes([value & 0x7F])
+ return result
+
+def _encode_field(field_number: int, wire_type: int, data: bytes) -> bytes:
+ tag = (field_number << 3) | wire_type
+ return _encode_varint(tag) + data
+
+def _encode_string_field(field_number: int, value: str) -> bytes:
+ encoded = value.encode("utf-8")
+ return _encode_field(field_number, 2, _encode_varint(len(encoded)) + encoded)
+
+def _encode_uint32_field(field_number: int, value: int) -> bytes:
+ return _encode_field(field_number, 0, _encode_varint(value))
+
+def _encode_content(key: str, value: str) -> bytes:
+ msg = b""
+ if key:
+ msg += _encode_string_field(1, key)
+ if value:
+ msg += _encode_string_field(2, value)
+ return msg
+
+def _encode_log(record: dict[str, Any], service_name: str) -> bytes:
+ ts = record.get("ts")
+ if isinstance(ts, (int, float)):
+ log_time = int(ts) if ts < 1_000_000_000_000 else int(ts / 1000)
+ else:
+ log_time = int(time.time())
+
+ msg = _encode_uint32_field(1, log_time)
+
+ merged = {"service_name": service_name, **record}
+ for key, value in merged.items():
+ if value is None:
+ continue
+ if isinstance(value, (dict, list)):
+ value = json.dumps(value, ensure_ascii=False)
+ else:
+ value = str(value)
+ msg += _encode_field(2, 2, _encode_varint(len(_encode_content(key, value))) + _encode_content(key, value))
+
+ return msg
+
+def _encode_log_group(records: list[dict[str, Any]], service_name: str) -> bytes:
+ msg = b""
+ for record in records:
+ log_bytes = _encode_log(record, service_name)
+ msg += _encode_field(1, 2, _encode_varint(len(log_bytes)) + log_bytes)
+ if service_name:
+ msg += _encode_string_field(2, service_name)
+ return msg
+
+def _encode_log_group_list(records: list[dict[str, Any]], service_name: str) -> bytes:
+ """编码 LogGroupList protobuf:`message LogGroupList { repeated LogGroup logGroupList = 1; }`。"""
+ log_group_bytes = _encode_log_group(records, service_name)
+ return _encode_field(1, 2, _encode_varint(len(log_group_bytes)) + log_group_bytes)
+
+
+# ---- CLS API v3 使用的 TC3-HMAC-SHA256 签名 ----
+
+def _hmac_sha256(key: bytes, data: str) -> bytes:
+ return hmac.new(key, data.encode("utf-8"), hashlib.sha256).digest()
+
+def _sha256_hex(data: str) -> str:
+ return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+def _put_logs_via_api(
+ endpoint: str,
+ topic_id: str,
+ secret_id: str,
+ secret_key: str,
+ log_group_bytes: bytes,
+ region: str = "ap-guangzhou",
+ timeout: int = 20,
+) -> tuple[bool, str]:
+ """通过 CLS API v3 发送 UploadLog,并使用 TC3-HMAC-SHA256 签名。
+
+ `log_group_bytes` 应该是一个 LogGroupList protobuf。
+ """
+ host = endpoint
+ service = "cls"
+ action = "UploadLog"
+ version = "2020-10-16"
+ algorithm = "TC3-HMAC-SHA256"
+ content_type = "application/octet-stream"
+
+ timestamp = int(time.time())
+ date_str = time.strftime("%Y-%m-%d", time.gmtime(timestamp))
+
+ # 请求体就是原始 protobuf 字节串(LogGroupList)
+ payload = log_group_bytes
+ hashed_payload = hashlib.sha256(payload).hexdigest()
+
+ # 规范化请求串
+ canonical_headers = f"content-type:{content_type}\nhost:{host}\nx-tc-action:{action.lower()}\n"
+ signed_headers = "content-type;host;x-tc-action"
+ canonical_request = f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+
+ # 待签名字符串
+ credential_scope = f"{date_str}/{service}/tc3_request"
+ hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
+ string_to_sign = f"{algorithm}\n{timestamp}\n{credential_scope}\n{hashed_canonical_request}"
+
+ # 签名结果
+ secret_date = _hmac_sha256(("TC3" + secret_key).encode("utf-8"), date_str)
+ secret_service = _hmac_sha256(secret_date, service)
+ secret_signing = _hmac_sha256(secret_service, "tc3_request")
+ signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+ authorization = f"{algorithm} Credential={secret_id}/{credential_scope}, SignedHeaders={signed_headers}, Signature={signature}"
+
+ # 构造 HTTP 请求
+ url = f"https://{host}"
+ headers = {
+ "Authorization": authorization,
+ "Content-Type": content_type,
+ "Host": host,
+ "X-TC-Action": action,
+ "X-TC-Timestamp": str(timestamp),
+ "X-TC-Version": version,
+ "X-TC-Region": region,
+ "X-CLS-TopicId": topic_id,
+ "Content-Length": str(len(payload)),
+ }
+
+ req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ body = resp.read().decode("utf-8", errors="replace")
+ if resp.status == 200:
+ return True, body
+ else:
+ return False, f"HTTP {resp.status}: {body}"
+ except urllib.error.HTTPError as e:
+ body = e.read().decode("utf-8", errors="replace")[:500]
+ return False, f"HTTP {e.code}: {body}"
+ except Exception as e:
+ return False, f"{type(e).__name__}: {e}"
+
+
+def _int_value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: int,
+ aliases: tuple[str, ...] = (),
+) -> int:
+ raw = _value(name, env_local=env_local, env_file=env_file, default=str(default), aliases=aliases)
+ try:
+ parsed = int(raw)
+ except Exception:
+ return default
+ return parsed if parsed > 0 else default
+
+
+def load_config(cwd: str | None = None) -> CLSConfig:
+ project_root = bootstrap.project_root(cwd)
+ env_file = bootstrap.read_env_file(project_root / ".env")
+ env_local = bootstrap.read_env_file(project_root / ".env.local")
+ return CLSConfig(
+ enabled=_enabled_flag(env_local=env_local, env_file=env_file),
+ endpoint=_value(
+ "CLS_ENDPOINT",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ topic_id=_value(
+ "CLS_TOPIC_ID",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ secret_id=_value(
+ "CLS_SECRET_ID",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID_438167613",
+ ),
+ ),
+ secret_key=_value(
+ "CLS_SECRET_KEY",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY_438167613",
+ ),
+ ),
+ secret_token=_value(
+ "CLS_SECRET_TOKEN",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=("TC_SECRET_TOKEN", "TC_SESSION_TOKEN", "CLS_SESSION_TOKEN"),
+ ),
+ service_name=_value(
+ "CLS_SERVICE_NAME",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ timeout_seconds=_int_value(
+ "CLS_UPLOAD_TIMEOUT_SECONDS",
+ env_local=env_local,
+ env_file=env_file,
+ default=0,
+ aliases=("CLS_TIMEOUT_SECONDS",),
+ ),
+ helper_path=helper_path(),
+ sdk_entry_path=sdk_entry_path(),
+ )
+
+
+def mirror_record(record: dict[str, Any], *, cwd: str | None = None) -> bool:
+ config = load_config(cwd)
+ if not config.ready:
+ _debug_write(
+ {
+ "stage": "config_not_ready",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "secret_id_present": bool(config.secret_id),
+ "secret_key_present": bool(config.secret_key),
+ "secret_token_present": bool(config.secret_token),
+ "timeout_seconds": config.timeout_seconds,
+ "helper_exists": config.helper_path.is_file(),
+ "sdk_exists": config.sdk_entry_path.is_file(),
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_start",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 先尝试 Python 原生 API v3 上报(兼容内网 endpoint)
+ try:
+ log_group_bytes = _encode_log_group_list([record], config.service_name)
+ success, detail = _put_logs_via_api(
+ endpoint=config.endpoint,
+ topic_id=config.topic_id,
+ secret_id=config.secret_id,
+ secret_key=config.secret_key,
+ log_group_bytes=log_group_bytes,
+ timeout=config.timeout_seconds,
+ )
+ if success:
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "method": "python_api_v3",
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
+ else:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "method": "python_api_v3",
+ "error": detail[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "method": "python_api_v3",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 回退方案:使用 node SDK uploader
+ payload = {
+ "endpoint": config.endpoint,
+ "topicId": config.topic_id,
+ "secretId": config.secret_id,
+ "secretKey": config.secret_key,
+ "secretToken": config.secret_token,
+ "serviceName": config.service_name,
+ "records": [record],
+ }
+ try:
+ completed = subprocess.run(
+ ["node", str(config.helper_path), str(config.sdk_entry_path)],
+ input=json.dumps(payload, ensure_ascii=False),
+ text=True,
+ capture_output=True,
+ check=False,
+ timeout=config.timeout_seconds,
+ )
+ if completed.returncode != 0:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "returncode": completed.returncode,
+ "stdout": (completed.stdout or "")[:2000],
+ "stderr": (completed.stderr or "")[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
diff --git a/.codebuddy/skills/agent-observability/scripts/core/cls_uploader.mjs b/.codebuddy/skills/agent-observability/scripts/core/cls_uploader.mjs
new file mode 100644
index 00000000..5c5dccc8
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/cls_uploader.mjs
@@ -0,0 +1,96 @@
+import { createRequire } from 'node:module';
+
+const MAX_FIELD_LENGTH = 32 * 1024;
+
+function truncate(value) {
+ if (value.length <= MAX_FIELD_LENGTH) {
+ return value;
+ }
+ return `${value.slice(0, MAX_FIELD_LENGTH)}...[truncated]`;
+}
+
+function stringifyValue(value) {
+ if (value === null || value === undefined) {
+ return '';
+ }
+ if (typeof value === 'string') {
+ return truncate(value);
+ }
+ if (typeof value === 'number' || typeof value === 'boolean') {
+ return String(value);
+ }
+ try {
+ return truncate(JSON.stringify(value));
+ } catch {
+ return truncate(String(value));
+ }
+}
+
+function timestampSeconds(record) {
+ const raw = Number(record?.ts);
+ if (!Number.isFinite(raw) || raw <= 0) {
+ return Math.floor(Date.now() / 1000);
+ }
+ return raw > 1_000_000_000_000 ? Math.floor(raw / 1000) : Math.floor(raw);
+}
+
+async function readStdin() {
+ const chunks = [];
+ for await (const chunk of process.stdin) {
+ chunks.push(chunk);
+ }
+ return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+ const sdkPath = process.argv[2];
+ if (!sdkPath) {
+ process.exitCode = 2;
+ process.stderr.write('missing sdk path\n');
+ return;
+ }
+
+ const require = createRequire(import.meta.url);
+ const { AsyncClient, LogItem, Content, LogGroup, PutLogsRequest } = require(sdkPath);
+
+ const raw = await readStdin();
+ const payload = JSON.parse(raw || '{}');
+ const records = Array.isArray(payload.records) ? payload.records : [];
+ if (!payload.endpoint || !payload.topicId || !payload.secretId || !payload.secretKey || records.length === 0) {
+ process.exitCode = 0;
+ return;
+ }
+
+ const client = new AsyncClient({
+ endpoint: payload.endpoint,
+ secretId: payload.secretId,
+ secretKey: payload.secretKey,
+ secretToken: payload.secretToken || '',
+ sourceIp: '127.0.0.1',
+ retry_times: 3,
+ });
+
+ const logGroup = new LogGroup();
+ logGroup.setFilename(payload.serviceName || 'agent-observability');
+
+ for (const record of records) {
+ const item = new LogItem();
+ const merged = {
+ service_name: payload.serviceName || 'agent-observability',
+ ...record,
+ };
+ for (const [key, value] of Object.entries(merged)) {
+ item.pushBack(new Content(key, stringifyValue(value)));
+ }
+ item.setTime(timestampSeconds(record));
+ logGroup.addLogs(item);
+ }
+
+ const request = new PutLogsRequest(payload.topicId, logGroup);
+ await client.PutLogs(request);
+}
+
+main().catch((error) => {
+ process.exitCode = 1;
+ process.stderr.write(`${error?.message || String(error)}\n`);
+});
diff --git a/.codebuddy/skills/agent-observability/scripts/core/collector.py b/.codebuddy/skills/agent-observability/scripts/core/collector.py
new file mode 100644
index 00000000..cfd681b2
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/collector.py
@@ -0,0 +1,1008 @@
+"""通用采集层。
+
+这一层负责最基础的观测数据采集:
+- 维护 Pre/PostToolUse 的配对关系,计算工具耗时
+- 解析 transcript 增量,提取 usage / model / tool 记录
+- 把 skill/rule 命中情况写入 session state
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, scanner, state as st
+
+# 需要从 transcript 中提取的 token 字段
+TOKEN_KEYS = (
+ "input_tokens", "output_tokens", "cache_read_input_tokens",
+ "cache_creation_input_tokens", "total_tokens",
+)
+
+# transcript 记录里可能携带模型名的字段
+MODEL_KEYS = ("model", "requestModelName", "requestModelId")
+MESSAGE_ID_KEYS = ("messageId", "responseId", "requestId")
+
+
+def transcript_path(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取 transcript 路径字段。"""
+ return str(data.get("transcript_path") or "")
+
+
+def read_stdin_json() -> dict:
+ """从 stdin 读取 JSON;失败时返回空字典。"""
+ import sys
+ try:
+ raw = sys.stdin.read()
+ if raw.strip():
+ d = json.loads(raw)
+ if isinstance(d, dict):
+ return d
+ return {}
+ except Exception as e:
+ return {"_parse_error": str(e)}
+
+
+def record_pre(pending_path: Path, data: dict) -> None:
+ """记录一条 PreToolUse,供后续 PostToolUse 计算耗时。"""
+ pending = st.load_pending(pending_path)
+ sid = data.get("session_id", "?")
+ tool = data.get("tool_name", "?")
+ key = f"{sid}::{tool}::{time.time_ns()}"
+ pending[key] = {
+ "start": time.time(),
+ "tool_name": tool,
+ "session_id": sid,
+ }
+ # 只保留最近 20 条 pending 记录
+ if len(pending) > 20:
+ for k in list(pending.keys())[:-20]:
+ pending.pop(k, None)
+ st.save_pending(pending_path, pending)
+
+
+def record_post(pending_path: Path, data: dict) -> int | None:
+ """把 PostToolUse 与之前的 PreToolUse 配对,并返回耗时毫秒数。"""
+ pending = st.load_pending(pending_path)
+ tool = data.get("tool_name")
+ sid = data.get("session_id", "?")
+ candidates = [(k, v) for k, v in pending.items()
+ if v.get("session_id") == sid and v.get("tool_name") == tool]
+ if not candidates:
+ return None
+ candidates.sort(key=lambda kv: kv[1]["start"])
+ key, item = candidates[-1]
+ duration_ms = int((time.time() - item["start"]) * 1000)
+ pending.pop(key, None)
+ st.save_pending(pending_path, pending)
+ return duration_ms
+
+
+def parse_transcript_tail(
+ path: str,
+ max_lines: int = 50,
+ last_offset: int = 0,
+) -> dict[str, Any]:
+ """解析 transcript 的增量 JSONL 内容,提取 usage、model 与 tool 元数据。
+
+ 返回结构:
+ {
+ "tokens": {...} or None, # 最新累计 usage
+ "prev_tokens": {...} or None, # 倒数第二条累计 usage(兼容字段)
+ "model": str or None,
+ "offset": int, # 当前 EOF
+ "tool_records": [
+ {"offset": int, "timestamp_ms": int | None, "tool": str, "call_id": str | None, "message_id": str | None, "kind": str},
+ ...
+ ],
+ "usage_records": [
+ {"offset": int, "tokens": {...}, "model": str | None, "message_id": str | None},
+ ...
+ ],
+ }
+
+ ``usage_records`` 会保留 ``last_offset`` 之后发现的全部 usage 项,
+ 这样调用方可以回放窗口内每一次模型请求,而不只是最后一个快照。
+ """
+ summary: dict[str, Any] = {
+ "tokens": None,
+ "prev_tokens": None,
+ "model": None,
+ "offset": 0,
+ "tool_records": [],
+ "usage_records": [],
+ }
+ if not path or not os.path.isfile(path):
+ return summary
+
+ try:
+ file_size = os.path.getsize(path)
+ summary["offset"] = file_size
+ if file_size <= last_offset:
+ return summary
+
+ with open(path, "rb") as fp:
+ read_start = max(0, int(last_offset or 0))
+ fp.seek(read_start)
+ tail_bytes = fp.read()
+ except Exception:
+ return summary
+
+ last_model_seen: str | None = None
+ usage_history: list[dict[str, Any]] = []
+ pending_tool_records: list[dict[str, Any]] = []
+ cursor = max(0, int(last_offset or 0))
+
+ for raw_line in tail_bytes.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ obj = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+
+ rec_type = str(obj.get("type") or "").strip().lower() if isinstance(obj, dict) else ""
+ message_id = _find_message_id(obj)
+ m = _find_model(obj)
+ if m:
+ last_model_seen = m
+ line_tool_records = _find_tool_records(obj)
+ if message_id and rec_type not in {"function_call", "function_call_result"}:
+ for pending_record in pending_tool_records:
+ pending_record["next_message_id"] = message_id
+ pending_tool_records = []
+ for tool_record in line_tool_records:
+ tool_record["offset"] = cursor
+ tool_record["timestamp_ms"] = _find_timestamp_ms(obj)
+ tool_record["message_id"] = message_id
+ summary["tool_records"].append(tool_record)
+ pending_tool_records.append(tool_record)
+ usage = _find_usage(obj)
+ if not usage:
+ continue
+
+ usage_history.append({
+ "offset": cursor,
+ "tokens": usage,
+ "model": m or last_model_seen,
+ "message_id": message_id,
+ })
+ if m:
+ summary["model"] = m
+
+ if usage_history:
+ summary["usage_records"] = usage_history
+ summary["tokens"] = usage_history[-1]["tokens"]
+ if len(usage_history) >= 2:
+ summary["prev_tokens"] = usage_history[-2]["tokens"]
+
+ if not summary.get("model") and last_model_seen:
+ summary["model"] = last_model_seen
+ return summary
+
+
+def record_tool_usage(
+ state_path: Path,
+ sid: str,
+ data: dict,
+ skills_meta: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+ collect_skills: bool = False,
+) -> tuple[list[str], list[str]]:
+ """把一次 tool 调用命中的 skill/rule 写入 session state。
+
+ Returns:
+ (used_skills, used_rules): 本次工具调用命中的 skill/rule 名称列表。
+ """
+ tool = data.get("tool_name")
+
+ def _update(state: dict[str, Any]) -> tuple[list[str], list[str]]:
+ sess = st.ensure_session(state, sid)
+ agent = active_agent or sess.get("current_agent") or "main"
+
+ used_skills: set[str] = set()
+ used_rules: set[str] = set()
+
+ # 1) 可选的 skill 收集
+ if collect_skills:
+ # 直接 use_skill 调用
+ direct = scanner.extract_skill_from_tool_call(data)
+ if direct:
+ st.bump_skill(sess, direct, via="use_skill", tool=tool,
+ meta=skills_meta.get(direct), agent=agent)
+ used_skills.add(direct)
+
+ # 路径推断
+ path_skills, _ = scanner.extract_paths_from_tool_call(data)
+ for s in path_skills:
+ st.bump_skill(sess, s, via="path-inferred", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 子模块命中
+ for hit in scanner.extract_submodule_hits(data):
+ skill_name = hit["skill"]
+ # unknown 仅代表“命中子模块但无法确定 skill 名称”,不写入实时 skill 字段
+ if not skill_name or skill_name == "unknown":
+ continue
+ st.bump_skill(sess, skill_name, via="submodule", tool=tool,
+ meta=skills_meta.get(skill_name),
+ submodule=hit["submodule"], agent=agent)
+ used_skills.add(skill_name)
+
+ # Bash skill 脚本
+ for s in scanner.extract_bash_skill_scripts(data):
+ st.bump_skill(sess, s, via="bash-script", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 2) 基于路径推断的 rule(始终开启)
+ _, path_rules = scanner.extract_paths_from_tool_call(data)
+ for r in path_rules:
+ st.bump_rule(sess, r, via="path-inferred", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ # 3) 当前激活的 rule(始终开启)
+ for r in scanner.active_rules_for_call(data, rules_meta, active_agent=agent):
+ st.bump_rule(sess, r, via="active-rule", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ st.prune_sessions(state)
+ return sorted(used_skills), sorted(used_rules)
+
+ return st.update_state_locked(state_path, _update)
+
+
+
+def cache_inventory(
+ state_path: Path,
+ sid: str,
+ skills_meta: dict,
+ rules_meta: dict,
+) -> None:
+ """把完整的 skill/rule inventory 缓存在 session state 中(在 SessionStart 调用)。"""
+ def _update(state: dict[str, Any]) -> None:
+ sess = st.ensure_session(state, sid)
+ sess["_skills_meta"] = skills_meta
+ sess["_rules_meta"] = rules_meta
+ sess["_inventory_scanned_at"] = time.time()
+
+ # 为所有已知 skill/rule 预先初始化 count=0 的 usage 记录
+ for name, meta in skills_meta.items():
+ rec = sess["skills"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"],
+ "source": meta.get("source"), "version": meta.get("version"),
+ })
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+
+ for name, meta in rules_meta.items():
+ rec = sess["rules"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"], "source": meta.get("source"),
+ })
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+
+ st.prune_sessions(state)
+
+ st.update_state_locked(state_path, _update)
+
+
+def load_cached_inventory(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """从 state 中读取缓存的 skill/rule inventory,避免在热路径里执行 rglob。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return (
+ sess.get("_skills_meta") or {},
+ sess.get("_rules_meta") or {},
+ )
+
+
+def get_session_usage(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """返回某个 session 的 skill/rule usage 字典。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return sess.get("skills", {}) or {}, sess.get("rules", {}) or {}
+
+def related_transcript_paths(sid: str, transcript_path: str) -> list[str]:
+ """收集当前 session 的主 transcript 以及所有 subagent transcript。"""
+ paths: list[Path] = []
+ current = Path(transcript_path).expanduser() if transcript_path else None
+ if current and current.is_file():
+ paths.append(current)
+
+ bundle_dir: Path | None = None
+ if current:
+ if current.name == f"{sid}.jsonl":
+ candidate = current.with_suffix("")
+ if candidate.is_dir():
+ bundle_dir = candidate
+ else:
+ for parent in [current.parent, *current.parents]:
+ if parent.name == sid and parent.is_dir():
+ bundle_dir = parent
+ break
+
+ if bundle_dir is None and current:
+ candidate = current.parent / sid
+ if candidate.is_dir():
+ bundle_dir = candidate
+
+ if bundle_dir is not None:
+ main_transcript = bundle_dir.with_suffix(".jsonl")
+ if main_transcript.is_file():
+ paths.append(main_transcript)
+ subagents_dir = bundle_dir / "subagents"
+ if subagents_dir.is_dir():
+ paths.extend(sorted(path for path in subagents_dir.glob("*.jsonl") if path.is_file()))
+
+ out: list[str] = []
+ seen: set[str] = set()
+ for path in paths:
+ resolved = str(path.resolve())
+ if resolved in seen:
+ continue
+ seen.add(resolved)
+ out.append(resolved)
+ return out
+
+
+def _transcript_size_signature(paths: list[str]) -> tuple[tuple[str, int], ...]:
+ """基于路径和文件大小生成 transcript 稳定性签名。"""
+ signature: list[tuple[str, int]] = []
+ for path in paths:
+ try:
+ size = Path(path).stat().st_size
+ except Exception:
+ size = -1
+ signature.append((path, int(size)))
+ return tuple(signature)
+
+
+def settled_related_transcript_paths(
+ sid: str,
+ transcript_path: str,
+ *,
+ max_wait_s: float = 2.0,
+ interval_s: float = 0.4,
+ stable_rounds: int = 2,
+) -> list[str]:
+ """在 replay 前短暂等待 transcript 文件停止增长。"""
+ deadline = time.monotonic() + max(0.0, max_wait_s)
+ previous: tuple[tuple[str, int], ...] | None = None
+ stable_count = 0
+ paths = related_transcript_paths(sid, transcript_path)
+
+ while True:
+ paths = related_transcript_paths(sid, transcript_path)
+ current = _transcript_size_signature(paths)
+ if current == previous:
+ stable_count += 1
+ else:
+ previous = current
+ stable_count = 0
+ if stable_count >= stable_rounds or time.monotonic() >= deadline:
+ return paths
+ sleep_for = min(interval_s, max(0.0, deadline - time.monotonic()))
+ if sleep_for <= 0:
+ return paths
+ time.sleep(sleep_for)
+
+
+def session_id_for_transcript_path(transcript_path: str) -> str | None:
+ """从 transcript 文件内容中反查 session id。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(8):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+ session_id = record.get("sessionId")
+ if isinstance(session_id, str) and session_id.strip():
+ return session_id.strip()
+ except Exception:
+ return None
+ return None
+
+
+def resolve_transcript_path_alias(sid: str, transcript_path: str) -> str:
+ """把别名 transcript 路径解析成当前 session 下的真实文件路径。"""
+ if not transcript_path:
+ return ""
+ current = Path(transcript_path).expanduser()
+ if current.is_file():
+ return str(current.resolve())
+
+ alias_session_id = current.stem if current.suffix == ".jsonl" else ""
+ if not alias_session_id or alias_session_id == sid:
+ return str(current)
+
+ for candidate in related_transcript_paths(sid, transcript_path):
+ if session_id_for_transcript_path(candidate) == alias_session_id:
+ return candidate
+ return str(current)
+
+def compute_usage_delta(current: dict[str, int], prev: dict[str, int] | None) -> dict[str, int]:
+ """把一条 usage 记录归一化成当前要发出的 event payload。"""
+ _ = prev
+ out = dict(current)
+ out["total"] = int(out.get("input", 0) or 0) + int(out.get("output", 0) or 0)
+ return out
+
+
+def normalize_tokens(tokens: dict[str, Any] | None) -> dict[str, int] | None:
+ """兼容多种 token 字段命名,并统一折叠成一套 schema。"""
+ if not isinstance(tokens, dict):
+ return None
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ input_t = _int(tokens.get("input") if "input" in tokens else tokens.get("input_tokens"))
+ output_t = _int(tokens.get("output") if "output" in tokens else tokens.get("output_tokens"))
+ cache_read = _int(tokens.get("cache_read") if "cache_read" in tokens else tokens.get("cache_read_input_tokens"))
+ cache_creation = _int(tokens.get("cache_creation") if "cache_creation" in tokens else tokens.get("cache_creation_input_tokens"))
+ total = input_t + output_t
+ if input_t <= 0 and output_t <= 0 and total <= 0:
+ return None
+ out = {"input": input_t, "output": output_t, "cache_read": cache_read, "total": total}
+ if cache_creation > 0:
+ out["cache_creation"] = cache_creation
+ return out
+
+
+def collect_transcript_entries(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ *,
+ max_lines: int,
+) -> dict[str, Any]:
+ """读取 transcript 增量,并返回带 source offset 的解析结果。"""
+ state_data = st.load_state(state_path)
+ last_offset = st.get_transcript_offset(state_data, sid, transcript_path)
+ tail = parse_transcript_tail(transcript_path, max_lines=max_lines, last_offset=last_offset)
+ new_offset = int(tail.get("offset", 0) or 0)
+
+ entries: list[dict[str, Any]] = []
+ tool_records: list[dict[str, Any]] = []
+ last_cumulative = st.get_last_cumulative_usage(state_data, sid, transcript_path) or None
+ usage_records = tail.get("usage_records") if isinstance(tail, dict) else None
+ if not isinstance(usage_records, list):
+ usage_records = []
+ raw_tool_records = tail.get("tool_records") if isinstance(tail, dict) else None
+ if not isinstance(raw_tool_records, list):
+ raw_tool_records = []
+
+ for raw_entry in usage_records:
+ if not isinstance(raw_entry, dict):
+ continue
+ current = normalize_tokens(raw_entry.get("tokens"))
+ if not current:
+ continue
+ delta = compute_usage_delta(current, last_cumulative)
+ entries.append({
+ "offset": int(raw_entry.get("offset", 0) or 0),
+ "tokens": delta,
+ "model": str(raw_entry.get("model") or tail.get("model") or "") or None,
+ "message_id": str(raw_entry.get("message_id") or "").strip() or None,
+ })
+ last_cumulative = current
+
+ for raw_tool_record in raw_tool_records:
+ if not isinstance(raw_tool_record, dict):
+ continue
+ tool_name = str(raw_tool_record.get("tool") or "").strip()
+ if not tool_name:
+ continue
+ tool_records.append({
+ "offset": int(raw_tool_record.get("offset", 0) or 0),
+ "timestamp_ms": int(raw_tool_record.get("timestamp_ms", 0) or 0) or None,
+ "tool": tool_name,
+ "call_id": str(raw_tool_record.get("call_id") or "").strip() or None,
+ "kind": str(raw_tool_record.get("kind") or "").strip() or None,
+ "message_id": str(raw_tool_record.get("message_id") or "").strip() or None,
+ "next_message_id": str(raw_tool_record.get("next_message_id") or "").strip() or None,
+ "arguments": raw_tool_record.get("arguments"),
+ "arguments_display_text": raw_tool_record.get("arguments_display_text"),
+ "result_content": raw_tool_record.get("result_content"),
+ "raw_response": raw_tool_record.get("raw_response"),
+ "output_text": raw_tool_record.get("output_text"),
+ })
+
+ return {
+ "entries": entries,
+ "tool_records": tool_records,
+ "new_offset": new_offset,
+ "last_cumulative": last_cumulative,
+ }
+
+
+def find_current_tool_message_id(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ max_lines: int = 80,
+) -> str | None:
+ """找到当前 tool 事件应该归属的 message id。"""
+ if not transcript_path or not tool_name:
+ return None
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ max_lines=max_lines,
+ )
+ tool_records = scan.get("tool_records") or []
+ latest_message_id: str | None = None
+ latest_offset = -1
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ if offset >= latest_offset:
+ latest_offset = offset
+ latest_message_id = message_id
+ return latest_message_id
+
+
+def tool_details_from_record(rec: dict[str, Any]) -> dict[str, Any]:
+ """把原始 tool 记录投影成日志里使用的紧凑 detail 结构。"""
+ details: dict[str, Any] = {}
+ call_id = str(rec.get("call_id") or "").strip() or None
+ if call_id:
+ details["call_id"] = call_id
+ arguments = rec.get("arguments")
+ if arguments is not None:
+ details["arguments"] = arguments
+ arguments_display_text = rec.get("arguments_display_text")
+ if arguments_display_text is not None:
+ details["arguments_display_text"] = arguments_display_text
+ result_content = rec.get("result_content")
+ if result_content is not None:
+ details["result_content"] = result_content
+ raw_response = rec.get("raw_response")
+ if isinstance(raw_response, dict) and raw_response:
+ details["raw_response"] = raw_response
+ output_text = rec.get("output_text")
+ if output_text is not None:
+ details["output_text"] = output_text
+ next_message_id = str(rec.get("next_message_id") or "").strip() or None
+ original_message_id = str(rec.get("message_id") or "").strip() or None
+ if next_message_id and original_message_id:
+ details["original_message_id"] = original_message_id
+ if next_message_id:
+ details["next_message_id"] = next_message_id
+ if original_message_id and next_message_id and original_message_id != next_message_id:
+ details["message_id_reassigned"] = True
+ return details
+
+
+def tool_record_merge_key(rec: dict[str, Any]) -> str:
+ """为一条 tool record 生成去重合并时使用的稳定 key。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"call_id:{call_id}"
+ offset = int(rec.get("offset", 0) or 0)
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ return f"fallback:{tool}:{message_id}:{timestamp_ms}:{offset}"
+
+
+def merge_tool_records(tool_records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """对指向同一次调用的 tool 记录做去重合并。"""
+ merged: dict[str, dict[str, Any]] = {}
+ order: list[str] = []
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ key = tool_record_merge_key(rec)
+ if key not in merged:
+ merged[key] = {
+ "offset": int(rec.get("offset", 0) or 0),
+ "timestamp_ms": int(rec.get("timestamp_ms", 0) or 0) or None,
+ "tool": str(rec.get("tool") or "").strip(),
+ "call_id": str(rec.get("call_id") or "").strip() or None,
+ "kind": str(rec.get("kind") or "").strip() or None,
+ "message_id": str(rec.get("message_id") or "").strip() or None,
+ "next_message_id": str(rec.get("next_message_id") or "").strip() or None,
+ "arguments": rec.get("arguments"),
+ "arguments_display_text": rec.get("arguments_display_text"),
+ "result_content": rec.get("result_content"),
+ "raw_response": rec.get("raw_response"),
+ "output_text": rec.get("output_text"),
+ }
+ order.append(key)
+ continue
+
+ current = merged[key]
+ current["offset"] = max(int(current.get("offset", 0) or 0), int(rec.get("offset", 0) or 0))
+ current_ts = int(current.get("timestamp_ms", 0) or 0)
+ rec_ts = int(rec.get("timestamp_ms", 0) or 0)
+ if current_ts <= 0 and rec_ts > 0:
+ current["timestamp_ms"] = rec_ts
+ for field in ("tool", "call_id", "kind", "message_id", "next_message_id", "arguments", "arguments_display_text", "result_content", "raw_response", "output_text"):
+ if current.get(field) is None and rec.get(field) is not None:
+ current[field] = rec.get(field)
+ if rec.get("arguments") is not None:
+ current["arguments"] = rec.get("arguments")
+ if rec.get("arguments_display_text") is not None:
+ current["arguments_display_text"] = rec.get("arguments_display_text")
+ if rec.get("result_content") is not None:
+ current["result_content"] = rec.get("result_content")
+ if rec.get("raw_response") is not None:
+ current["raw_response"] = rec.get("raw_response")
+ if rec.get("output_text") is not None:
+ current["output_text"] = rec.get("output_text")
+
+ return [merged[key] for key in order]
+
+
+def tool_context_claim_key(rec: dict[str, Any]) -> str:
+ """为 tool context 生成 claim 去重键,避免重复消费。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"tool_call|{call_id}"
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ offset = int(rec.get("offset", 0) or 0)
+ return f"tool_call|{tool}|{message_id}|{timestamp_ms}|{offset}"
+
+
+def find_current_tool_context(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ call_id: str | None = None,
+ event_ts: float | None = None,
+ max_lines: int = 80,
+ claim: bool = False,
+) -> dict[str, Any] | None:
+ """为当前 tool 调用解析最合适的 transcript 上下文块。"""
+ if not tool_name:
+ return None
+ event_ts_ms = int(float(event_ts) * 1000) if event_ts else None
+ normalized_call_id = str(call_id or "").strip() or None
+
+ resolved_path = resolve_transcript_path_alias(sid, transcript_path)
+ candidate_paths: list[str] = []
+ if resolved_path:
+ candidate_paths.append(resolved_path)
+ for path in related_transcript_paths(sid, transcript_path):
+ if path not in candidate_paths:
+ candidate_paths.append(path)
+
+ candidates: list[tuple[tuple[int, int, int], dict[str, Any]]] = []
+ for path in candidate_paths:
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ tool_records = merge_tool_records(scan.get("tool_records") or [])
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ rec_call_id = str(rec.get("call_id") or "").strip() or None
+ if normalized_call_id and rec_call_id != normalized_call_id:
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ if normalized_call_id:
+ score = (0, 0, -offset)
+ elif event_ts_ms and timestamp_ms > 0:
+ delta = timestamp_ms - event_ts_ms
+ score = (abs(delta), 0 if delta >= 0 else 1, -offset)
+ else:
+ score = (10**12, 1, -offset)
+ candidates.append((
+ score,
+ {
+ "message_id": message_id,
+ "transcript_path": path,
+ "agent": agent_identity.agent_for_transcript_path(path, "main"),
+ "pt_id": agent_identity.pt_id_from_transcript_path(path),
+ "tool_details": tool_details_from_record(rec),
+ "_claim_key": tool_context_claim_key(rec),
+ },
+ ))
+
+ candidates.sort(key=lambda item: item[0])
+ saw_duplicate = False
+ for _, candidate in candidates:
+ if not claim:
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ if st.claim_transcript_event(
+ state_path,
+ sid,
+ str(candidate.get("_claim_key") or ""),
+ str(candidate.get("transcript_path") or "") or None,
+ ):
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ saw_duplicate = True
+
+ if saw_duplicate:
+ return {"duplicate": True}
+ return None
+
+
+def extract_tool_call_id(data: dict[str, Any]) -> str | None:
+ """从事件 payload 或 tool_input 中提取 tool call id。"""
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId"):
+ value = data.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+
+ tool_input = data.get("tool_input")
+ if isinstance(tool_input, dict):
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId", "id"):
+ value = tool_input.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return None
+
+
+def find_fallback_usage_event(
+ tool_event: dict[str, Any],
+ usage_events: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+ """当找不到直接匹配的 tool usage 时,为 AgentLens 选一条兜底 usage。"""
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ agent = str(tool_event.get("agent") or "main").strip() or "main"
+
+ strong_matches: list[dict[str, Any]] = []
+ weak_matches: list[dict[str, Any]] = []
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if (str(usage_event.get("agent") or "main").strip() or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "").strip() != transcript_path:
+ continue
+ if not str(usage_event.get("message_id") or "").strip():
+ continue
+
+ weak_matches.append(usage_event)
+ event_tool = str(usage_event.get("tool") or "").strip()
+ if tool_name and event_tool in {tool_name, "model_request"}:
+ strong_matches.append(usage_event)
+
+ if strong_matches:
+ return strong_matches[-1]
+ if weak_matches:
+ return weak_matches[-1]
+ return None
+
+
+def build_transcript_event_key(*, kind: str, tool: str, entry: dict[str, Any]) -> str:
+ """为 transcript 重放出的事件生成幂等键。"""
+ _ = (kind, tool)
+ return "|".join(["model_request", str(entry.get("offset", 0) or 0)])
+
+def _find_usage(obj: Any, _depth: int = 0) -> dict | None:
+ """递归查找 JSON 对象里的 token usage。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ if "usage" in obj and isinstance(obj["usage"], dict):
+ u = obj["usage"]
+ picked = {k: u[k] for k in TOKEN_KEYS if k in u}
+ if picked:
+ return picked
+ for v in obj.values():
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_model(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找 JSON 对象里的非空模型名。
+
+ 优先使用 `providerData.model` 或顶层 `model`,
+ 其次回退到 `requestModelName` / `requestModelId`。
+ """
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ for k in MODEL_KEYS:
+ v = obj.get(k)
+ if isinstance(v, str) and v.strip():
+ return v.strip()
+ for v in obj.values():
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_message_id(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找稳定的 message/request 分组标识。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in MESSAGE_ID_KEYS:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for v in obj.values():
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_timestamp_ms(obj: Any, _depth: int = 0) -> int | None:
+ """递归查找 transcript 中的毫秒级时间戳。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ value = obj.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ value = provider.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ for v in obj.values():
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_tool_records(obj: Any) -> list[dict[str, Any]]:
+ """从 transcript 记录里提取 tool 调用与 tool 结果片段。"""
+ out: list[dict[str, Any]] = []
+ if not isinstance(obj, dict):
+ return out
+
+ rec_type = str(obj.get("type") or "").strip().lower()
+ provider = obj.get("providerData") if isinstance(obj.get("providerData"), dict) else {}
+ if rec_type in {"function_call", "function_call_result"}:
+ tool_name = str(obj.get("name") or "").strip()
+ if tool_name:
+ record = {
+ "tool": tool_name,
+ "call_id": str(obj.get("callId") or "").strip() or None,
+ "kind": rec_type,
+ }
+ if rec_type == "function_call":
+ arguments = obj.get("arguments")
+ if isinstance(arguments, str) and arguments.strip():
+ record["arguments"] = arguments
+ arguments_display_text = provider.get("argumentsDisplayText")
+ if isinstance(arguments_display_text, str) and arguments_display_text.strip():
+ record["arguments_display_text"] = arguments_display_text.strip()
+ if rec_type == "function_call_result":
+ tool_result = provider.get("toolResult")
+ if isinstance(tool_result, dict):
+ content = tool_result.get("content")
+ if content is not None:
+ record["result_content"] = content
+ raw_response = tool_result.get("rawResponse")
+ if isinstance(raw_response, dict):
+ record["raw_response"] = raw_response
+ output = obj.get("output")
+ if isinstance(output, dict):
+ output_text = output.get("text")
+ if output_text is not None:
+ record["output_text"] = output_text
+ out.append(record)
+
+ content = obj.get("content")
+ if isinstance(content, list):
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ if str(item.get("type") or "").strip().lower() != "tool_use":
+ continue
+ tool_name = str(item.get("name") or "").strip()
+ if not tool_name:
+ continue
+ out.append({
+ "tool": tool_name,
+ "call_id": str(item.get("callId") or "").strip() or None,
+ "kind": "tool_use",
+ })
+
+ return out
diff --git a/.codebuddy/skills/agent-observability/scripts/core/devflow.py b/.codebuddy/skills/agent-observability/scripts/core/devflow.py
new file mode 100644
index 00000000..ab7ef794
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/devflow.py
@@ -0,0 +1,234 @@
+"""Devflow 感知层(可选增强,不属于通用采集核心)。
+
+这一层只在项目实际跑着 `.codebuddy/runtime` 描述的 multi-agents-devflow 工作流时才生效:
+- 判断当前 session 是否属于某个 devflow team(`multi-agents-devflow-{task_slug}`)
+- 读取该 team 对应的 `workflow-state.json`,投影成精简 stage 快照
+- 和上一次观测到的快照 diff,只把真正变化的 stage 产出为事件
+
+任何解析失败(team 目录不存在 / workflow-state.json 缺失或损坏 / 字段缺失)都必须
+优雅降级为 None / 空列表,绝不能让不跑 devflow 的普通项目因为这一层报错。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, state as st
+
+
+def task_slug_from_team_dir(team_dir: Path) -> str | None:
+ """从 devflow team 目录名里剥离出 task_slug(固定前缀 `multi-agents-devflow-`)。"""
+ name = team_dir.name
+ prefix = agent_identity.TEAM_PREFIX
+ if not name.startswith(prefix):
+ return None
+ slug = name[len(prefix):].strip()
+ return slug or None
+
+
+def resolve_devflow_context(cwd: str, sid: str, cached_team_dir: str | None = None) -> dict[str, Any] | None:
+ """判断当前 session 是否处于某次 devflow 运行中;不是则返回 None。
+
+ 优先复用 `agent_identity.resolve_team_dir` 做 team 发现(Classic 全部场景,以及
+ Portable 在 `topology: team` 宿主——目前是 CodeBuddy——下也走同一套
+ `multi-agents-devflow-{task_slug}` 命名,可以直接复用,不用区分 edition)。
+
+ `topology: spawn` 的宿主(Codex/Claude/Cursor 的 Portable 适配器)不创建 team
+ 目录,找不到时退化成 `_scan_artifacts_for_active_run` 直接扫 `artifacts/` 目录。
+ 这个兜底本身就是尽力而为的启发式,不保证唯一/精确,见该函数的说明。
+
+ `artifacts_dir` 按 `devflow.defaults.yaml` 的默认值 `{project_root}/artifacts/{task_slug}`
+ 推算——项目若覆写了 `artifacts.root_dir`,这里暂不感知,读取 workflow-state.json
+ 找不到文件会安全返回 None,不会误报。
+ """
+ team_dir = agent_identity.resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is not None:
+ task_slug = task_slug_from_team_dir(team_dir)
+ if task_slug:
+ artifacts_dir = Path(cwd).expanduser() / "artifacts" / task_slug
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ return {
+ "task_slug": task_slug,
+ "team_dir": str(team_dir),
+ "artifacts_dir": str(artifacts_dir),
+ "workflow_state_path": str(workflow_state_path),
+ }
+ return _scan_artifacts_for_active_run(cwd)
+
+
+def _scan_artifacts_for_active_run(cwd: str) -> dict[str, Any] | None:
+ """没有 team 目录时的兜底发现:直接扫 `{cwd}/artifacts/*/workflow-state.json`。
+
+ 用于 `topology: spawn` 的宿主(没有 `.codebuddy/teams/` 这类目录可以反查),以及
+ Classic 没有真正暴露 `team_create` 时的降级场景。这是启发式,不是精确匹配:
+ 多个 task_slug 存在时,优先选"还没跑完"的那个;都跑完或都没跑完时选
+ `workflow-state.json` 文件 mtime 最新的一个。"跑完"的判定要兼容两套 schema——
+ Classic(v1.3)没有顶层 `status` 字段,看 `last_event == "workflow_completed"`;
+ Portable(v2.0)看顶层 `status in {"completed", "failed"}`。项目里如果同时有多个
+ 真正并发、都还没跑完的 devflow 运行,这个兜底可能选错——已知限制,不在这次范围内解决。
+ """
+ artifacts_root = Path(cwd).expanduser() / "artifacts"
+ if not artifacts_root.is_dir():
+ return None
+ candidates: list[tuple[tuple[int, float], str, Path]] = []
+ try:
+ children = list(artifacts_root.iterdir())
+ except Exception:
+ return None
+ for child in children:
+ if not child.is_dir():
+ continue
+ state_path = child / "workflow-state.json"
+ state = read_workflow_state(str(state_path))
+ if not isinstance(state, dict) or not isinstance(state.get("stages"), dict):
+ continue
+ try:
+ mtime = state_path.stat().st_mtime
+ except Exception:
+ mtime = 0.0
+ finished = (
+ str(state.get("last_event") or "") == "workflow_completed"
+ or str(state.get("status") or "") in {"completed", "failed"}
+ )
+ not_finished = 0 if finished else 1
+ candidates.append(((not_finished, mtime), child.name, state_path))
+ if not candidates:
+ return None
+ candidates.sort(key=lambda item: item[0], reverse=True)
+ _, task_slug, state_path = candidates[0]
+ return {
+ "task_slug": task_slug,
+ "team_dir": None,
+ "artifacts_dir": str(state_path.parent),
+ "workflow_state_path": str(state_path),
+ }
+
+
+def read_workflow_state(path: str) -> dict[str, Any] | None:
+ """安全读取 workflow-state.json;文件不存在或解析失败都返回 None。"""
+ try:
+ p = Path(path)
+ if not p.is_file():
+ return None
+ data = json.loads(p.read_text("utf-8"))
+ return data if isinstance(data, dict) else None
+ except Exception:
+ return None
+
+
+def stage_snapshot(workflow_state: dict[str, Any] | None) -> dict[str, Any]:
+ """把 workflow-state.json 投影成精简快照,供比对和事件输出使用。
+
+ 兼容两套 schema:Classic(v1.3,字段名 `executor`,有 `review_result`)和
+ Portable(v2.0,字段名 `executor_role`,没有 `review_result`,但顶层多了
+ `execution_mode`/`host_adapter`/`run_id`/`team_name` 这些 Classic 没有的上下文)。
+ 按 `version` 字段区分,取不到就都尝试取一遍,不强制要求调用方先判断是哪个 edition。
+ """
+ if not isinstance(workflow_state, dict):
+ return {}
+ stages_raw = workflow_state.get("stages")
+ stages: dict[str, Any] = {}
+ if isinstance(stages_raw, dict):
+ for name, info in stages_raw.items():
+ if not isinstance(info, dict):
+ continue
+ stages[name] = {
+ "status": info.get("status"),
+ "executor": info.get("executor") or info.get("executor_role"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ }
+ return {
+ "current_stage": workflow_state.get("current_stage"),
+ "size_class": workflow_state.get("size_class"),
+ "run_mode": workflow_state.get("run_mode"),
+ "schema_version": workflow_state.get("version"),
+ "execution_mode": workflow_state.get("execution_mode"),
+ "host_adapter": workflow_state.get("host_adapter"),
+ "run_id": workflow_state.get("run_id"),
+ "stages": stages,
+ }
+
+
+def diff_stage_changes(prev: dict[str, Any] | None, curr: dict[str, Any]) -> list[dict[str, Any]]:
+ """比较两次 stage 快照,只返回 status/retry_count/review_result 真正变化的阶段。
+
+ 首次观测(`prev` 为 None,即这个 session 第一次检测到 devflow)不产出任何变更——
+ 避免刚接入 observability 时,把一个已经跑了大半的 devflow 运行的全部历史阶段
+ 当成"新事件"一次性炸出来。之后每次变化都会被正常捕获。
+ """
+ if not isinstance(curr, dict) or prev is None:
+ return []
+ curr_stages = curr.get("stages") or {}
+ prev_stages = prev.get("stages") if isinstance(prev, dict) else {}
+ if not isinstance(prev_stages, dict):
+ prev_stages = {}
+ changes: list[dict[str, Any]] = []
+ for name, info in curr_stages.items():
+ if not isinstance(info, dict):
+ continue
+ before = prev_stages.get(name)
+ before = before if isinstance(before, dict) else {}
+ fields = ("status", "retry_count", "review_result")
+ if any(before.get(f) != info.get(f) for f in fields):
+ changes.append({
+ "stage": name,
+ "status": info.get("status"),
+ "executor": info.get("executor"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ })
+ return changes
+
+
+def resolve_and_diff(state_path: Path, sid: str, cwd: str) -> dict[str, Any] | None:
+ """解析当前 session 归属的 devflow 上下文,返回上下文 + 本次观测到的 stage 变更。
+
+ **不缓存"当前归属哪个 task_slug"这个结论本身**——同一个 sid 在其生命周期内可能
+ 先后归属不同的 devflow 运行。这不是理论场景:当运行时没有暴露真正的
+ `team_create`/`send_message`(因此没有独立的 team 成员 sid),devflow 会退化成
+ 在同一个长生命周期 session 里,先后跑好几次 `/start-devflow`;每次都必须重新判定
+ "现在最合适的 task_slug 是哪个",而不能沿用第一次探测到的那个——沿用旧结论会把
+ 第二次运行的所有事件都错误地归到第一次的 task_slug 下。
+
+ 重新判定的代价很低:`resolve_devflow_context` 对团队目录的探测会用上一次找到的
+ `team_dir` 做快速校验(只在真正失效时才重新扫描 `.codebuddy/teams/`);
+ `artifacts/` 兜底扫描也只是一次浅层 `iterdir()`,不是全量遍历。
+
+ 真正跨调用持久化的只有**按 task_slug 分别保存的 stage 快照历史**——切换到另一个
+ task_slug 不会污染对方的 diff 基线,也不会因为切回旧 task_slug 而把它已经观测过的
+ 历史重新当成"首次观测"。
+
+ 返回 None 表示这次调用没有探测到任何 devflow 上下文;否则返回
+ `{task_slug, artifacts_dir, workflow_state_path, current_stage, size_class, changes}`。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any] | None:
+ dv = st.get_devflow_state(state, sid)
+ cached_team_dir = (dv.get("context") or {}).get("team_dir") if isinstance(dv.get("context"), dict) else None
+ context = resolve_devflow_context(cwd, sid, cached_team_dir)
+ if not isinstance(context, dict):
+ st.set_devflow_state(state, sid, {"context": None})
+ return None
+
+ task_slug = str(context.get("task_slug") or "")
+ workflow_state = read_workflow_state(context.get("workflow_state_path", ""))
+ curr = stage_snapshot(workflow_state)
+ snapshots = dv.get("snapshots")
+ if not isinstance(snapshots, dict):
+ snapshots = {}
+ prev = snapshots.get(task_slug)
+ changes = diff_stage_changes(prev if isinstance(prev, dict) else None, curr)
+ snapshots[task_slug] = curr
+ st.set_devflow_state(state, sid, {"context": context, "snapshots": snapshots})
+
+ result = dict(context)
+ result["current_stage"] = curr.get("current_stage")
+ result["size_class"] = curr.get("size_class")
+ result["schema_version"] = curr.get("schema_version")
+ result["execution_mode"] = curr.get("execution_mode")
+ result["changes"] = changes
+ return result
+
+ return st.update_state_locked(state_path, _update)
diff --git a/.codebuddy/skills/agent-observability/scripts/core/emitter.py b/.codebuddy/skills/agent-observability/scripts/core/emitter.py
new file mode 100644
index 00000000..a41dfc05
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/emitter.py
@@ -0,0 +1,578 @@
+"""ndjson 发射层。
+
+只输出当前真正需要的核心字段:
+- common: data_source
+- tool: event, sid, ts, agent, tool, ms, skill, rule, transcript_path
+- usage: event, sid, ts, agent, tool, tokens, model, cost_usd, transcript_path
+- start: event, sid, ts, agent
+- stop: event, sid, ts, agent, tokens, model, cost_usd, cost_session_usd, transcript_path
+- error: event, sid, ts, phase, error
+
+历史 x_* 扩展字段、stop skill/rule 汇总、schema 版本号等都不再生成。
+
+`cost_usd` 的价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认
+`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`,可用
+`AOBS_PRICING_OVERRIDES_PATH` 改路径)的字段级合并结果,详见 `load_prices()`。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from . import cls_sink
+from . import state as st
+
+DEFAULT_PRICES_PATH = Path(__file__).resolve().parents[2] / "config" / "pricing.json"
+DEFAULT_DATA_SOURCE = "codebuddy-cli"
+
+
+def _default_overrides_path() -> Path | None:
+ """用户定价覆盖文件的默认位置:`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`。
+
+ 刻意放在 `skills/` 树**外**:`scripts/build-classic-hosts.py` 会整棵同步
+ `.codebuddy/skills`,放树内会 (a) 每次改动都产生 `--check` drift,(b) 把用户的
+ 自定义价格复制进 `.claude`/`.cursor` 宿主包;放树外则既不参与同步,也不会被
+ `config/pricing.json` 的后续更新冲掉。
+ """
+ try:
+ project_root = Path(__file__).resolve().parents[5]
+ except IndexError:
+ return None
+ return project_root / ".codebuddy" / "agent-observability" / "pricing.overrides.json"
+
+
+# None 表示"拿不到项目根",此时等同于"没有覆盖文件"(纯内置价格表)。
+DEFAULT_OVERRIDES_PATH: Path | None = _default_overrides_path()
+
+
+def get_log_path(base_dir: Path) -> Path:
+ """返回 metrics 日志路径,并确保目录已存在。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / "metrics.ndjson"
+
+
+def _first_record_ts(log_path: Path, sid: str) -> float | None:
+ """从 metrics.ndjson 中找到某个 session 的最早 ts。
+
+ state 只保留最近几个 session,长流程或历史 session 可能被 prune 后重建,
+ 因此 `started_at` 不能作为唯一权威。日志里的首条 ts 更接近
+ session/workflow 的真实起点。
+ """
+ if not sid or not log_path.exists():
+ return None
+ first_ts: float | None = None
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid:
+ continue
+ try:
+ ts = float(rec.get("ts"))
+ except Exception:
+ continue
+ if first_ts is None or ts < first_ts:
+ first_ts = ts
+ except Exception:
+ return None
+ return first_ts
+
+
+def _inject_session_duration(record: dict[str, Any], log_path: Path) -> None:
+ """从 state 文件读取 session started_at,计算 session_duration_sec 注入 record。
+ 同时扫描 metrics.ndjson 累计 session 级别 token 总量。"""
+ sid = record.get("sid")
+ if not sid or "session_duration_sec" in record:
+ return
+ try:
+ now = float(record.get("ts") or time.time())
+ started_candidates: list[float] = []
+ state_path = log_path.parent / ".state.json"
+ state = st.load_state(state_path)
+ sess = state.get(sid)
+ if isinstance(sess, dict):
+ try:
+ state_started_at = float(sess.get("started_at") or 0)
+ except Exception:
+ state_started_at = 0.0
+ if state_started_at > 0:
+ started_candidates.append(state_started_at)
+ log_started_at = _first_record_ts(log_path, str(sid))
+ if log_started_at is not None and log_started_at > 0:
+ started_candidates.append(log_started_at)
+ if not started_candidates:
+ started_candidates.append(now)
+ started_at = min(started_candidates)
+ record["session_duration_sec"] = round(max(0.0, now - started_at), 3)
+ except Exception:
+ return
+
+ # 累计 session 级别 token(扫描 metrics.ndjson 尾部)
+ try:
+ total_input = 0
+ total_output = 0
+ total_cache = 0
+ if log_path.exists():
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") != "usage":
+ continue
+ tokens = rec.get("tokens")
+ if not isinstance(tokens, dict):
+ continue
+ total_input += int(tokens.get("input") or 0)
+ total_output += int(tokens.get("output") or 0)
+ total_cache += int(tokens.get("cache_read") or 0)
+ record["session_total_tokens"] = total_input + total_output
+ record["session_input_tokens"] = total_input
+ record["session_output_tokens"] = total_output
+ record["session_cache_tokens"] = total_cache
+ except Exception:
+ return
+
+
+def emit(log_path: Path, record: dict[str, Any]) -> None:
+ """向 ndjson 日志追加一条记录。"""
+ record.setdefault("data_source", DEFAULT_DATA_SOURCE)
+ record.setdefault("ts", time.time())
+ _inject_session_duration(record, log_path)
+ with log_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False) + "\n")
+ try:
+ cls_sink.mirror_record(record)
+ except Exception:
+ return
+
+
+def build_tool_event(
+ sid: str,
+ tool: str | None,
+ duration_ms: int | None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+ pt_id: str | None = None,
+) -> dict[str, Any]:
+ """构造 tool 事件记录,只包含调用信息与耗时。
+
+ `task_slug` / `stage` / `pt_id` 只有在检测到 devflow 运行时才会出现(见
+ `core/devflow.py`),非 devflow 项目不受影响。
+ """
+ record = {
+ "event": "tool",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "ms": duration_ms,
+ }
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if turn_id:
+ record["turn_id"] = turn_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ if pt_id:
+ record["pt_id"] = pt_id
+ return record
+
+
+def build_usage_event(
+ sid: str,
+ tool: str | None,
+ tokens: dict[str, Any],
+ active_agent: str | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造 LLM usage 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "usage",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "tokens": tokens,
+ }
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_start_event(
+ sid: str,
+ agent: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 start 事件记录。
+
+ 初始化阶段没有明确角色时,统一记为 ``main``。
+ """
+ return {
+ "event": "start",
+ "sid": sid,
+ "agent": agent or "main",
+ }
+
+
+def build_prompt_submit_event(
+ sid: str,
+ turn_id: str,
+ agent: str | None = None,
+ prompt_len: int | None = None,
+) -> dict[str, Any]:
+ """构造 `user_prompt_submit` 事件,作为 turn 边界标记。
+
+ 这条记录会落到 metrics.ndjson,方便下游把 turn 和 AgentLens trace 对上。
+ """
+ record: dict[str, Any] = {
+ "event": "user_prompt_submit",
+ "sid": sid,
+ "agent": agent or "main",
+ "turn_id": turn_id,
+ }
+ if prompt_len is not None:
+ record["prompt_len"] = int(prompt_len)
+ return record
+
+
+def build_stop_event(
+ sid: str,
+ tokens: dict | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ cost_session_usd: float | None = None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 stop 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "stop",
+ "sid": sid,
+ "agent": active_agent or "main",
+ }
+ if tokens:
+ record["tokens"] = tokens
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if cost_session_usd is not None:
+ record["cost_session_usd"] = cost_session_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_error_event(
+ phase: str,
+ error: str,
+ sid: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 error 事件记录。"""
+ return {
+ "event": "error",
+ "sid": sid or "",
+ "phase": phase,
+ "error": error,
+ }
+
+
+def build_stage_transition_event(
+ sid: str,
+ task_slug: str,
+ stage: str,
+ status: str | None = None,
+ executor: str | None = None,
+ retry_count: int = 0,
+ review_result: str | None = None,
+) -> dict[str, Any]:
+ """构造 devflow stage 变更事件(只在检测到 devflow 运行、且 stage 真的变化时发出)。
+
+ 对应 `workflow-state.json` 里某个 stage 的 `status`/`retry_count`/`review_result`
+ 发生变化——retry_count 上升或 review_result="failed" 是 devflow 里最值得关注的
+ 信号(返工/打回循环),比 hook 自身的 `error` 事件更贴近业务语义。
+ """
+ record: dict[str, Any] = {
+ "event": "stage_transition",
+ "sid": sid,
+ "task_slug": task_slug,
+ "stage": stage,
+ }
+ if status:
+ record["status"] = status
+ if executor:
+ record["executor"] = executor
+ if retry_count:
+ record["retry_count"] = int(retry_count)
+ if review_result:
+ record["review_result"] = review_result
+ return record
+
+
+def resolve_overrides_path() -> Path | None:
+ """返回当前生效的覆盖文件路径:`AOBS_PRICING_OVERRIDES_PATH` 优先,否则默认路径。
+
+ 返回 `None` 表示"不加载任何覆盖"(纯内置价格表)。支持 `~` 展开。
+ """
+ raw = os.environ.get("AOBS_PRICING_OVERRIDES_PATH", "").strip()
+ if raw:
+ return Path(raw).expanduser()
+ return DEFAULT_OVERRIDES_PATH
+
+
+def _coerce_price_table(data: Any) -> dict[str, dict[str, float]]:
+ """把任意 JSON 结果规整成 `{model: {field: float}}`,坏数据按字段/按模型跳过。
+
+ 与内置表加载的差别只有一处:内置表遇到非数字会整体抛错降级,这里逐字段跳过——
+ 用户的补丁文件里写错一个字段不应该把其余正确的覆盖一起丢掉,更不应该让 hook 挂掉。
+ """
+ if not isinstance(data, dict):
+ return {}
+ table: dict[str, dict[str, float]] = {}
+ for raw_key, raw_value in data.items():
+ if not isinstance(raw_value, dict):
+ continue
+ key = str(raw_key).strip().lower()
+ if not key:
+ continue
+ row: dict[str, float] = {}
+ for price_key, price_value in raw_value.items():
+ # bool 是 int 的子类,True 会被 float() 变成 1.0,这里按"不是价格"处理。
+ if price_value is None or isinstance(price_value, bool):
+ continue
+ try:
+ row[str(price_key).strip().lower()] = float(price_value)
+ except (TypeError, ValueError):
+ continue
+ # 全是坏字段的模型不落表:否则它会被 `lookup_price` 命中成 {},
+ # 既算不出成本又不算"未定价",看板上会变成一个查不到原因的空洞。
+ if row:
+ table[key] = row
+ return table
+
+
+def load_price_overrides(path: Path | None = None) -> dict[str, dict[str, float]]:
+ """加载用户定价覆盖文件;任何异常都静默降级为空覆盖(纯内置价格表)。
+
+ 静默是刻意的:这个文件是给人手写的常驻配置,hook 每次都是新进程,
+ 一旦因格式问题抛异常/打印,会让整条 hook 链路变得不可用。
+ """
+ try:
+ target = path if path is not None else resolve_overrides_path()
+ if not target:
+ return {}
+ with Path(target).expanduser().open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ return _coerce_price_table(data)
+
+
+def merge_prices(
+ base: dict[str, dict[str, float]] | None,
+ overrides: dict[str, dict[str, float]] | None,
+) -> dict[str, dict[str, float]]:
+ """字段级合并价格表:覆盖里写出的字段替换内置值,没写的字段沿用内置值。
+
+ 可以新增内置表里不存在的模型;**不支持删除**内置模型或字段(合并只能加不能减)。
+ """
+ merged: dict[str, dict[str, float]] = {}
+ for model, row in (base or {}).items():
+ if isinstance(row, dict):
+ merged[model] = dict(row)
+ for model, patch in (overrides or {}).items():
+ if not isinstance(patch, dict):
+ continue
+ merged.setdefault(model, {}).update(patch)
+ return merged
+
+
+def _load_builtin_prices() -> dict[str, dict[str, float]]:
+ """从 `config/pricing.json` 中一次性加载内置模型价格配置(不含用户覆盖)。"""
+ path = os.environ.get("AOBS_PRICES_PATH", "").strip()
+ prices_path = Path(path).expanduser() if path else DEFAULT_PRICES_PATH
+ try:
+ with prices_path.open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ return {
+ str(key).lower(): {price_key: float(price_value) for price_key, price_value in value.items()}
+ for key, value in data.items()
+ if isinstance(value, dict)
+ }
+
+
+@lru_cache(maxsize=1)
+def load_prices() -> dict[str, dict[str, float]]:
+ """内置价格表 + 用户覆盖文件的合并结果(字段级)。
+
+ 结果带 `lru_cache`:hook 是短命进程,一次会话里只该读一次盘;长驻进程或单测里
+ 改了覆盖文件/环境变量后,调 `clear_price_cache()` 让下一次调用重新加载。
+ """
+ return merge_prices(_load_builtin_prices(), load_price_overrides())
+
+
+def clear_price_cache() -> None:
+ """丢弃 `load_prices()` 的缓存,让下一次调用重读磁盘与环境变量。"""
+ load_prices.cache_clear()
+
+
+def lookup_price(model: str | None) -> dict[str, float] | None:
+ """为一个具体模型名找到最匹配的价格配置项。"""
+ if not model or not isinstance(model, str):
+ return None
+ normalized = model.lower().strip()
+ if not normalized:
+ return None
+ prices = load_prices()
+ if normalized in prices:
+ return prices[normalized]
+ best_key: str | None = None
+ for key in prices:
+ if key in normalized and (best_key is None or len(key) > len(best_key)):
+ best_key = key
+ if best_key is None:
+ return None
+ return prices[best_key]
+
+
+def is_unpriced(model: str | None) -> bool:
+ """模型是否完全没命中价格表(含模糊匹配)。
+
+ "未定价"的唯一口径就是 `lookup_price(...) is None`(D4):模糊(最长子串)命中的
+ 模型能算出成本,就不该出现在看板的"建议补价"提示里。
+ """
+ return lookup_price(model) is None
+
+
+def estimate_cost(tokens: dict | None, model: str | None) -> dict[str, Any] | None:
+ """根据归一化后的 token 总量估算单条 usage 事件的成本。"""
+ if not isinstance(tokens, dict):
+ return None
+ rates = lookup_price(model)
+ if not rates:
+ return None
+
+ def _int(key: str) -> int:
+ try:
+ return int(tokens.get(key) or 0)
+ except Exception:
+ return 0
+
+ output = _int("output")
+ cache_read = _int("cache_read")
+ cache_write = _int("cache_creation")
+ raw_input = _int("input")
+ fresh_input = raw_input - cache_read - cache_write if raw_input and raw_input >= (cache_read + cache_write) else raw_input
+ cost = (
+ fresh_input * rates.get("input", 0.0)
+ + cache_read * rates.get("cache_read", 0.0)
+ + cache_write * rates.get("cache_write", 0.0)
+ + output * rates.get("output", 0.0)
+ ) / 1_000_000.0
+
+ matched_key = None
+ normalized = (model or "").lower()
+ for key in load_prices():
+ if key in normalized and (matched_key is None or len(key) > len(matched_key)):
+ matched_key = key
+ if matched_key is None and normalized in load_prices():
+ matched_key = normalized
+
+ return {
+ "usd": round(cost, 6),
+ "model_matched": matched_key,
+ "rates": rates,
+ }
+
+
+def cost_of(tokens: dict | None, model: str | None) -> float | None:
+ """只返回美元成本值的便捷封装。"""
+ if not tokens or not model:
+ return None
+ info = estimate_cost(tokens, model)
+ if not info:
+ return None
+ return info.get("usd")
+
+
+def sum_session_cost(log_path: Path, sid: str) -> float | None:
+ """尽力根据已发出的事件反算整个 session 的总成本。"""
+ if not log_path.exists() or not sid:
+ return None
+ total = 0.0
+ seen = False
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") not in {"usage", "tool"}:
+ continue
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ total += float(cost)
+ seen = True
+ except Exception:
+ return None
+ return round(total, 6) if seen else None
diff --git a/.codebuddy/skills/agent-observability/scripts/core/runtime.py b/.codebuddy/skills/agent-observability/scripts/core/runtime.py
new file mode 100644
index 00000000..9c647bc0
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/runtime.py
@@ -0,0 +1,598 @@
+from __future__ import annotations
+"""Hook 主编排入口。
+
+这一层负责把外部 hook phase 分发到内部能力:
+- session-start / user-prompt-submit / pre / post / stop
+- 组装统一运行时路径
+- 串联 collector / emitter / agentlens,并承担 transcript 运行时编排
+"""
+
+import os
+import re
+import time
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, agentlens, collector, devflow, emitter, scanner, state as st
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+ """运行时常用路径集合,避免每个分支重复计算。"""
+ base_dir: Path
+ state_path: Path
+ pending_path: Path
+ log_path: Path
+
+
+def base_dir() -> Path:
+ """返回 hook 运行时使用的根目录。"""
+ # 运行时产物统一写到 skill 根目录下的 logs/,保持与旧路径兼容。
+ return Path(__file__).resolve().parents[2]
+
+
+def build_runtime_paths() -> RuntimePaths:
+ """构造本次 hook 运行要用到的路径集合。"""
+ base = base_dir()
+ return RuntimePaths(
+ base_dir=base,
+ state_path=st.get_state_path(base),
+ pending_path=st.get_pending_path(base),
+ log_path=emitter.get_log_path(base),
+ )
+
+
+def session_id_of(data: dict[str, Any]) -> str:
+ """兼容不同字段名,提取 session id。"""
+ return str(data.get("session_id") or data.get("sid") or "")
+
+
+def cwd(data: dict[str, Any]) -> str:
+ """解析当前项目工作目录。"""
+ return str(data.get("cwd") or os.environ.get("CODEBUDDY_PROJECT_DIR") or os.getcwd())
+
+
+def normalize_phase(raw: str | None) -> str:
+ """把多种 phase 写法折叠成统一内部枚举。"""
+ phase = (raw or "").strip().lower()
+ return {
+ "sessionstart": "session-start",
+ "session_start": "session-start",
+ "session-start": "session-start",
+ "pretooluse": "pre",
+ "pre": "pre",
+ "posttooluse": "post",
+ "post": "post",
+ "stop": "stop",
+ "userpromptsubmit": "user-prompt-submit",
+ "user_prompt_submit": "user-prompt-submit",
+ "user-prompt-submit": "user-prompt-submit",
+ "prompt": "user-prompt-submit",
+ }.get(phase, phase)
+
+
+def emit_error(phase: str, sid: str, err: Exception) -> None:
+ """把运行时异常写成 error 事件,而不是直接中断 hook。"""
+ rec = emitter.build_error_event(phase=phase, error=f"{type(err).__name__}: {err}", sid=sid)
+ rec["x_traceback"] = traceback.format_exc(limit=5)[-1200:]
+ emitter.emit(build_runtime_paths().log_path, rec)
+
+
+def derive_turn_id(data: dict[str, Any]) -> str:
+ """优先复用外部已有 id,否则生成一个本地 turn id。"""
+ for key in ("turn_id", "prompt_id", "request_id", "message_id"):
+ raw = data.get(key)
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ if isinstance(raw, (int, float)) and raw:
+ return str(raw)
+ return f"turn-{int(time.time() * 1000)}"
+
+
+def prompt_text_length(data: dict[str, Any]) -> int | None:
+ """统计用户 prompt 的文本长度,用于 turn 边界指标。"""
+ for key in ("prompt", "user_prompt", "message", "content", "text"):
+ val = data.get(key)
+ if isinstance(val, str):
+ return len(val)
+ if isinstance(val, list):
+ total = 0
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ total += len(txt)
+ elif isinstance(item, str):
+ total += len(item)
+ if total:
+ return total
+ return None
+
+
+def extract_prompt_text(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取可读的 prompt 文本。"""
+ for key in ("prompt", "user_prompt", "message", "text"):
+ val = data.get(key)
+ if isinstance(val, str) and val.strip():
+ return val.strip()
+ if isinstance(val, list):
+ parts = []
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif isinstance(item, str):
+ parts.append(item)
+ if parts:
+ return "\n".join(parts).strip()
+ return ""
+
+
+def derive_business_scenario(prompt_text: str) -> str | None:
+ """从 prompt 文本中派生一个简短业务场景标识。"""
+ if not prompt_text:
+ return None
+
+ m = re.search(r"标题[::]\s*(.+?)(?:\s*描述[::]|\s*$)", prompt_text, re.DOTALL)
+ if m:
+ title = m.group(1).strip()[:60]
+ else:
+ title = prompt_text[:50].strip()
+
+ sanitized = re.sub(r"[^\w\u4e00-\u9fff\-]", "-", title)
+ sanitized = re.sub(r"-{2,}", "-", sanitized).strip("-")
+ return sanitized if sanitized else None
+
+
+def handle_session_start(data: dict[str, Any]) -> None:
+ """处理 SessionStart:预热 inventory,写 start 事件,初始化 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+ emitter.emit(paths.log_path, emitter.build_start_event(sid=current_sid, agent="main"))
+ agentlens.emit_session_start(state_path=paths.state_path, sid=current_sid, cwd=cwd_value, agent="main")
+
+
+def handle_user_prompt_submit(data: dict[str, Any]) -> None:
+ """处理 UserPromptSubmit:建立 turn 边界,并打开 AgentLens turn。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ turn_id = derive_turn_id(data)
+ prompt_len = prompt_text_length(data)
+ prompt_text = extract_prompt_text(data)
+ business_scenario = derive_business_scenario(prompt_text)
+
+ emitter.emit(
+ paths.log_path,
+ emitter.build_prompt_submit_event(sid=current_sid, turn_id=turn_id, agent="main", prompt_len=prompt_len),
+ )
+ agentlens.emit_turn_start(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ turn_id=turn_id,
+ prompt_meta={"prompt_len": prompt_len} if prompt_len is not None else None,
+ business_scenario=business_scenario,
+ )
+
+
+def handle_pre(data: dict[str, Any]) -> None:
+ """处理 PreToolUse:仅记录 pending,等待 post 配对。"""
+ collector.record_pre(build_runtime_paths().pending_path, data)
+
+
+def handle_post(data: dict[str, Any]) -> None:
+ """处理 PostToolUse:计算耗时、归因 agent、发 tool/usage 事件。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ duration_ms = collector.record_post(paths.pending_path, data)
+
+ skills_meta, rules_meta = collector.load_cached_inventory(paths.state_path, current_sid)
+ if not skills_meta and not rules_meta:
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ used_skills, used_rules = collector.record_tool_usage(
+ state_path=paths.state_path,
+ sid=current_sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent=active_agent,
+ collect_skills=True,
+ )
+
+ tool_name = str(data.get("tool_name") or "")
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ event_ts = time.time()
+ tool_call_id = collector.extract_tool_call_id(data)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ )
+ tool_context = collector.find_current_tool_context(
+ state_path=paths.state_path,
+ sid=current_sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=tool_call_id,
+ event_ts=event_ts,
+ claim=True,
+ )
+ duplicate_tool_context = bool(isinstance(tool_context, dict) and tool_context.get("duplicate"))
+ if duplicate_tool_context:
+ tool_context = None
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ transcript_path = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ active_agent = resolved_agent
+
+ tool_pt_id = str(tool_context.get("pt_id") or "").strip() if isinstance(tool_context, dict) else None
+ tool_event = emitter.build_tool_event(
+ sid=current_sid,
+ tool=tool_name,
+ duration_ms=duration_ms,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ pt_id=tool_pt_id,
+ )
+ tool_event["ts"] = event_ts
+ tool_event["skill"] = used_skills
+ tool_event["rule"] = used_rules
+ tool_event["cwd"] = cwd_value
+ if tool_call_id:
+ tool_event["call_id"] = tool_call_id
+ if isinstance(tool_context, dict):
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+
+ usage_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name=tool_name,
+ event_kind="usage",
+ max_lines=80,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ if duplicate_tool_context:
+ if not usage_events:
+ return
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=None,
+ usage_events=usage_events,
+ )
+ return
+ if str(tool_event.get("message_id") or "").strip():
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ fallback_usage = collector.find_fallback_usage_event(tool_event, usage_events)
+ fallback_usage_mid = str((fallback_usage or {}).get("message_id") or "").strip() or None
+ if fallback_usage_mid:
+ tool_event["message_id"] = fallback_usage_mid
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ st.append_pending_tool_emit(paths.state_path, current_sid, tool_event)
+
+
+def handle_stop(data: dict[str, Any]) -> None:
+ """处理 Stop:补发 transcript 事件、汇总 session 成本并关闭 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ stop_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.settled_related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name="__stop__",
+ event_kind="stop",
+ max_lines=200,
+ cost_session=emitter.sum_session_cost(paths.log_path, current_sid),
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ force_emit_fallback=True,
+ )
+ agentlens.emit_session_stop(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ stop_events=stop_events,
+ )
+
+
+def resolve_devflow(state_path: Path, sid: str, cwd_value: str, log_path: Path) -> dict[str, Any] | None:
+ """解析 devflow 上下文,并把本次观测到的 stage 变更立即发成 `stage_transition` 事件。
+
+ 任何异常都吞掉、返回 None——devflow 感知是可选增强,绝不能让不跑 devflow 的
+ 项目或 workflow-state.json 格式变化导致 hook 报错。
+ """
+ try:
+ dv_ctx = devflow.resolve_and_diff(state_path, sid, cwd_value)
+ except Exception:
+ return None
+ if not isinstance(dv_ctx, dict):
+ return None
+ task_slug = str(dv_ctx.get("task_slug") or "").strip()
+ if not task_slug:
+ return None
+ for change in dv_ctx.get("changes") or []:
+ if not isinstance(change, dict):
+ continue
+ event = emitter.build_stage_transition_event(
+ sid=sid,
+ task_slug=task_slug,
+ stage=str(change.get("stage") or ""),
+ status=change.get("status"),
+ executor=change.get("executor"),
+ retry_count=int(change.get("retry_count") or 0),
+ review_result=change.get("review_result"),
+ )
+ emitter.emit(log_path, event)
+ return dv_ctx
+
+
+def current_turn_id(state_path: Path, sid: str) -> str | None:
+ """从 state 中读取当前 session 激活中的 turn id。"""
+ try:
+ turn = st.get_current_turn(state_path, sid)
+ except Exception:
+ turn = None
+ if isinstance(turn, dict):
+ raw = turn.get("turn_id")
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ return None
+
+
+def flush_pending_tool_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ force_emit_fallback: bool = False,
+) -> None:
+ """强制 flush 延迟的 tool 事件,常用于 stop/replay 路径。"""
+ pending = st.get_pending_tool_emits(state_path, sid)
+ if not pending:
+ return
+
+ remaining: list[dict[str, Any]] = []
+ for tool_event in pending:
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ call_id = str(tool_event.get("call_id") or "").strip() or None
+ event_ts = tool_event.get("ts")
+ try:
+ event_ts_float = float(event_ts) if event_ts is not None else None
+ except Exception:
+ event_ts_float = None
+
+ tool_context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=call_id,
+ event_ts=event_ts_float,
+ claim=True,
+ )
+ if isinstance(tool_context, dict) and tool_context.get("duplicate"):
+ continue
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ tool_event["transcript_path"] = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ tool_event["agent"] = resolved_agent
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ if force_emit_fallback:
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ remaining.append(tool_event)
+
+ st.replace_pending_tool_emits(state_path, sid, remaining)
+
+
+def emit_transcript_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ transcript_paths: list[str],
+ current_transcript_path: str,
+ active_agent: str,
+ tool_name: str,
+ event_kind: str,
+ max_lines: int,
+ cost_session: float | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> list[dict[str, Any]]:
+ """发出基于 transcript 增量重建得到的 usage/stop 事件。"""
+ emitted_events: list[dict[str, Any]] = []
+ current_resolved = str(Path(current_transcript_path).resolve()) if current_transcript_path else ""
+ for path in transcript_paths:
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ entries = scan.get("entries", []) or []
+ event_tool = tool_name if event_kind == "usage" and path == current_resolved else "model_request"
+ event_agent = active_agent if path == current_resolved else agent_identity.agent_for_transcript_path(path, active_agent)
+
+ for idx, entry in enumerate(entries):
+ event_key = collector.build_transcript_event_key(kind=event_kind, tool=event_tool, entry=entry)
+ if not st.claim_transcript_event(state_path, sid, event_key, path):
+ continue
+ tokens = entry.get("tokens")
+ model = entry.get("model")
+ if event_kind == "stop":
+ event = emitter.build_stop_event(
+ sid=sid,
+ tokens=tokens,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ cost_session_usd=cost_session if idx == len(entries) - 1 else None,
+ active_agent=event_agent,
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ else:
+ event = emitter.build_usage_event(
+ sid=sid,
+ tool=event_tool,
+ tokens=tokens,
+ active_agent=event_agent,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ emitter.emit(log_path, event)
+ emitted_events.append(event)
+
+ st.commit_transcript_progress(
+ state_path,
+ sid,
+ path,
+ offset=int(scan.get("new_offset", 0) or 0),
+ last_cumulative_usage=scan.get("last_cumulative"),
+ )
+ return emitted_events
+
+
+def main(argv: list[str]) -> int:
+ """读取 stdin 输入并按 phase 执行对应 hook 处理分支。"""
+ phase = normalize_phase(argv[0] if argv else "")
+ current_sid = ""
+ try:
+ data = collector.read_stdin_json()
+ current_sid = session_id_of(data)
+ if phase == "session-start":
+ handle_session_start(data)
+ elif phase == "user-prompt-submit":
+ handle_user_prompt_submit(data)
+ elif phase == "pre":
+ handle_pre(data)
+ elif phase == "post":
+ handle_post(data)
+ elif phase == "stop":
+ handle_stop(data)
+ else:
+ emitter.emit(
+ build_runtime_paths().log_path,
+ emitter.build_error_event(phase=phase or "unknown", error=f"Unsupported phase: {phase!r}", sid=current_sid),
+ )
+ except Exception as exc:
+ emit_error(phase=phase or "unknown", sid=current_sid, err=exc)
+ return 0
diff --git a/.codebuddy/skills/agent-observability/scripts/core/scanner.py b/.codebuddy/skills/agent-observability/scripts/core/scanner.py
new file mode 100644
index 00000000..86b5305e
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/scanner.py
@@ -0,0 +1,496 @@
+"""Skill / Rule 静态扫描层。
+
+这一层只负责扫描项目里的 `.codebuddy/skills` 与 `.codebuddy/rules`:
+- 识别有哪些可用 skill / rule
+- 提取它们的基础元数据与 frontmatter
+- 提供 path-based 命中推断依赖的 inventory 信息
+
+它不依赖具体 workflow 语义,本身是通用层。
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# --- 用于解析 SKILL.md / RULE.mdc frontmatter 的正则 ---
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.S)
+NAME_FIELD_RE = re.compile(r"^name:\s*(.+)$", re.M)
+VERSION_FIELD_RE = re.compile(r"^version:\s*(.+)$", re.M)
+AUTHOR_FIELD_RE = re.compile(r"^author:\s*(.+)$", re.M)
+TAGS_FIELD_RE = re.compile(r"^tags:\s*\[([^\]]+)\]", re.M)
+DESC_FIELD_RE = re.compile(r"^description:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+ALWAYS_APPLY_RE = re.compile(r"^alwaysApply:\s*(true|false)\s*$", re.M | re.I)
+ENABLED_RE = re.compile(r"^enabled:\s*(true|false)\s*$", re.M | re.I)
+GLOBS_RE = re.compile(r"^globs:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+APPLY_AGENTS_RE = re.compile(r"^applyAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+EXCLUDE_AGENTS_RE = re.compile(r"^excludeAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+
+# 固定的 inventory 根目录(仅限项目内)
+PROJECT_SKILLS_REL = Path(".codebuddy/skills")
+PROJECT_RULES_REL = Path(".codebuddy/rules")
+
+# 支持识别的 skill 子模块根目录
+SUBMODULE_DIRS = {"references", "scripts", "templates", "examples", "checklists", "roles"}
+
+# 允许严格提取的路径类字段键名(不扫描自由文本)
+PATH_VALUE_KEYS = {
+ "file_path", "filePath", "path", "target_file", "target_directory",
+ "cwd", "rule", "rule_path", "skill_path",
+}
+PATH_LIST_KEYS = {"paths", "files", "rules", "skills"}
+
+# 扫描时要跳过的目录
+SKIP_DIR_PARTS = {"skills-by-node", "node_modules", ".git", "__pycache__", "dist"}
+
+# 可能触发 skill 的工具名
+USE_SKILL_TOOLS = {"use_skill", "UseSkill", "load_skill", "Skill", "skill"}
+
+
+def _is_skipped_path(p: Path) -> bool:
+ """判断路径是否命中扫描时应跳过的目录集合。"""
+ parts = set(p.parts)
+ return bool(parts & SKIP_DIR_PARTS)
+
+
+def _parse_frontmatter(path: Path) -> dict[str, Any]:
+ """解析 `SKILL.md` 或 `RULE.mdc` 中的 frontmatter。"""
+ try:
+ text = path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ def _grab(regex, key, post=None):
+ mm = regex.search(block)
+ if mm:
+ v = mm.group(1).strip().strip('"\'').strip()
+ info[key] = post(v) if post else v
+
+ _grab(NAME_FIELD_RE, "name")
+ _grab(VERSION_FIELD_RE, "version")
+ _grab(AUTHOR_FIELD_RE, "author")
+ _grab(TAGS_FIELD_RE, "tags",
+ lambda v: [t.strip().strip('"\'') for t in v.split(",") if t.strip()])
+ _grab(DESC_FIELD_RE, "description", lambda v: v.strip().replace("\n", " ")[:200])
+ return info
+
+
+def _parse_list_field(block: str, regex: re.Pattern[str]) -> list[str]:
+ """从 frontmatter 文本块中解析一个逗号分隔的列表字段。"""
+ mm = regex.search(block)
+ if not mm:
+ return []
+ raw = mm.group(1).strip().strip('"\'')
+ if raw.startswith("["):
+ raw = raw.strip("[]")
+ return [g.strip().strip('"\'').lower() for g in raw.split(",") if g.strip()]
+
+
+def _parse_rule_frontmatter(rule_path: Path) -> dict[str, Any]:
+ """解析 `RULE.mdc` 中和规则生效相关的 frontmatter 字段。"""
+ try:
+ text = rule_path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ mm = ALWAYS_APPLY_RE.search(block)
+ if mm:
+ info["alwaysApply"] = mm.group(1).lower() == "true"
+ mm = ENABLED_RE.search(block)
+ if mm:
+ info["enabled"] = mm.group(1).lower() == "true"
+ globs = _parse_list_field(block, GLOBS_RE)
+ if globs:
+ info["globs"] = globs
+
+ apply_agents = _parse_list_field(block, APPLY_AGENTS_RE)
+ if apply_agents:
+ info["applyAgents"] = apply_agents
+
+ exclude_agents = _parse_list_field(block, EXCLUDE_AGENTS_RE)
+ if exclude_agents:
+ info["excludeAgents"] = exclude_agents
+
+ mm = DESC_FIELD_RE.search(block)
+ if mm:
+ info["description"] = mm.group(1).strip().strip('"\'').replace("\n", " ")[:200]
+ return info
+
+
+def _classify_source(path: Path, cwd: Path | None) -> str:
+ """识别来源类型;当前只支持项目内 `.codebuddy` 路径。"""
+ if not cwd:
+ return "unknown"
+ try:
+ path_str = str(path.resolve())
+ cwd_str = str(cwd.resolve())
+ except Exception:
+ return "unknown"
+ if path_str.startswith(cwd_str + "/.codebuddy/"):
+ return "project"
+ return "unknown"
+
+
+def _collect_submodules(skill_dir: Path) -> dict[str, list]:
+ """收集一个 skill 内部的子模块目录,如 references/scripts/templates。"""
+ sub: dict = {}
+ if not skill_dir.is_dir():
+ return sub
+ for kind in ("references", "scripts", "templates", "examples", "checklists", "roles"):
+ d = skill_dir / kind
+ if d.is_dir():
+ files = [str(f.relative_to(skill_dir))
+ for f in d.rglob("*") if f.is_file()]
+ if files:
+ sub[kind] = sorted(files)[:30]
+ return sub
+
+
+def scan_skills_and_rules(cwd: str) -> tuple[dict[str, Any], dict[str, Any]]:
+ """扫描项目固定根目录:`.codebuddy/skills` 与 `.codebuddy/rules`。"""
+ skills: dict = {}
+ rules: dict = {}
+ cwd_path = Path(cwd) if cwd else None
+ if not cwd_path or not cwd_path.exists():
+ return skills, rules
+
+ skills_root = (cwd_path / PROJECT_SKILLS_REL).resolve()
+ rules_root = (cwd_path / PROJECT_RULES_REL).resolve()
+
+ if skills_root.is_dir() and not _is_skipped_path(skills_root):
+ for p in skills_root.rglob("SKILL.md"):
+ if _is_skipped_path(p):
+ continue
+ skill_dir = p.parent
+ name = skill_dir.name
+ if not name or name in skills:
+ continue
+ meta = _parse_frontmatter(p)
+ skills[name] = {
+ "source": _classify_source(skill_dir, cwd_path),
+ "path": str(skill_dir),
+ "has_skill_md": True,
+ "version": meta.get("version"),
+ "author": meta.get("author"),
+ "description": meta.get("description"),
+ "submodules": _collect_submodules(skill_dir),
+ }
+
+ if rules_root.is_dir() and not _is_skipped_path(rules_root):
+ for p in rules_root.rglob("*.mdc"):
+ if _is_skipped_path(p):
+ continue
+ name = p.parent.name if p.name == "RULE.mdc" else p.stem
+ if not name or name in rules:
+ continue
+ meta = _parse_rule_frontmatter(p)
+ rules[name] = {
+ "source": _classify_source(p.parent, cwd_path),
+ "path": str(p),
+ "alwaysApply": meta.get("alwaysApply", False),
+ "enabled": meta.get("enabled", True),
+ "globs": meta.get("globs") or [],
+ "applyAgents": meta.get("applyAgents") or [],
+ "excludeAgents": meta.get("excludeAgents") or [],
+ "description": meta.get("description"),
+ }
+
+ return skills, rules
+
+
+def lookup_skill_meta(skills_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 skill 元数据。"""
+ meta = (skills_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def lookup_rule_meta(rules_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 rule 元数据。"""
+ meta = (rules_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def _collect_path_strings(obj: Any) -> list[str]:
+ """只收集结构化路径字段,绝不解析自由文本。"""
+ out: list[str] = []
+
+ def _walk(x: Any) -> None:
+ if isinstance(x, dict):
+ for k, v in x.items():
+ if k in PATH_VALUE_KEYS and isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif k in PATH_LIST_KEYS:
+ if isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif isinstance(v, list):
+ out.extend([
+ s.strip() for s in v
+ if isinstance(s, str) and s.strip()
+ ])
+ elif isinstance(v, (dict, list)):
+ _walk(v)
+ elif isinstance(x, list):
+ for it in x:
+ if isinstance(it, (dict, list)):
+ _walk(it)
+
+ _walk(obj)
+ return list(dict.fromkeys(out))
+
+
+def _path_parts(path_str: str) -> list[str]:
+ """把路径拆成标准化片段列表,便于后续命中判断。"""
+ p = path_str.replace("\\", "/").strip()
+ return [part for part in p.split("/") if part]
+
+
+def _extract_skill_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 skill 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ name = parts[i + 2]
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _extract_rule_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 rule 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "rules":
+ name = parts[i + 2]
+ if name.lower().endswith(".mdc"):
+ name = Path(name).stem
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _is_rule_allowed_for_agent(name: str, meta: dict[str, Any], active_agent: str | None) -> bool:
+ """按角色判断 rule 是否可用;`global` 永远保持可选。"""
+ if str(name).strip().lower() == "global":
+ return True
+
+ agent = str(active_agent or "").strip().lower()
+ if not agent:
+ return True
+
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+
+ if apply_agents and agent not in apply_agents:
+ return False
+ if exclude_agents and agent in exclude_agents:
+ return False
+ return True
+
+
+def _glob_matches_any_path(globs: list[str], paths_to_check: list[str]) -> bool:
+ """判断配置的 glob 是否命中任一收集到的路径。"""
+ if not globs or not paths_to_check:
+ return False
+ import fnmatch
+
+ for p in paths_to_check:
+ basename = os.path.basename(p)
+ if any(fnmatch.fnmatch(p, g) or fnmatch.fnmatch(basename, g) for g in globs):
+ return True
+ return False
+
+
+def evaluate_rules_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """评估当前工具调用下所有已知 rule,并保留未命中的原因。"""
+ if not rules_meta:
+ return {}
+
+ tool_input = data.get("tool_input") or {}
+ paths_to_check = _collect_path_strings(tool_input)
+ _, path_rules = extract_paths_from_tool_call(data)
+ path_rule_set = set(path_rules)
+
+ evaluations: dict[str, dict[str, Any]] = {}
+ for name, meta in (rules_meta or {}).items():
+ if not isinstance(meta, dict):
+ continue
+
+ globs = [str(g).strip() for g in (meta.get("globs") or []) if str(g).strip()]
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+ evaluation: dict[str, Any] = {"matched": False}
+
+ if name in path_rule_set:
+ evaluation["matched"] = True
+ evaluation["via"] = "path_inferred"
+ elif meta.get("enabled") is False:
+ evaluation["reason"] = "disabled"
+ elif not _is_rule_allowed_for_agent(name, meta, active_agent):
+ evaluation["reason"] = "agent_filtered"
+ if apply_agents:
+ evaluation["applyAgents"] = apply_agents
+ if exclude_agents:
+ evaluation["excludeAgents"] = exclude_agents
+ elif meta.get("alwaysApply"):
+ evaluation["matched"] = True
+ evaluation["via"] = "always_apply"
+ elif globs:
+ evaluation["globs"] = globs
+ evaluation["paths_checked"] = len(paths_to_check)
+ if not paths_to_check:
+ evaluation["reason"] = "no_paths"
+ elif _glob_matches_any_path(globs, paths_to_check):
+ evaluation["matched"] = True
+ evaluation["via"] = "glob"
+ else:
+ evaluation["reason"] = "glob_not_matched"
+ evaluation["paths_sample"] = paths_to_check[:3]
+ else:
+ evaluation["reason"] = "no_globs"
+
+ evaluations[name] = evaluation
+
+ return evaluations
+
+
+def unmatched_rule_diagnostics_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """返回当前工具调用下未命中的 rule 的精简诊断信息。"""
+ diagnostics: dict[str, dict[str, Any]] = {}
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched"):
+ continue
+ item: dict[str, Any] = {"reason": evaluation.get("reason") or "unknown"}
+ for key in ("globs", "paths_checked", "paths_sample", "applyAgents", "excludeAgents"):
+ value = evaluation.get(key)
+ if value is not None and value != []:
+ item[key] = value
+ diagnostics[name] = item
+ return diagnostics
+
+
+def filtered_rules_for_agent(rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """列出因 agent 过滤而被排除的 rule(仅看已启用项)。"""
+ filtered: list[str] = []
+ for name, evaluation in evaluate_rules_for_call({}, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("reason") == "agent_filtered":
+ filtered.append(name)
+ return sorted(set(filtered))
+
+
+def active_rules_for_call(data: dict, rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """判断给定工具调用下哪些 rule 处于生效状态。"""
+ active: list[str] = []
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched") and evaluation.get("via") != "path_inferred":
+ active.append(name)
+ return sorted(set(active))
+
+
+def extract_skill_from_tool_call(data: dict) -> str | None:
+ """从类似 use_skill 的工具调用里提取 skill 名称。"""
+ tool = data.get("tool_name", "")
+ if tool not in USE_SKILL_TOOLS:
+ return None
+ tool_input = data.get("tool_input") or {}
+ if isinstance(tool_input, dict):
+ return tool_input.get("command") or tool_input.get("name") or tool_input.get("skill")
+ return None
+
+
+def is_brainstorming_call(data: dict) -> bool:
+ """判断当前工具调用是否正在激活或使用 brainstorming skill。"""
+ direct = extract_skill_from_tool_call(data)
+ if isinstance(direct, str) and direct.strip().lower() == "brainstorming":
+ return True
+
+ path_skills, _ = extract_paths_from_tool_call(data)
+ return any(str(s).strip().lower() == "brainstorming" for s in path_skills)
+
+
+def extract_paths_from_tool_call(data: dict) -> tuple[list[str], list[str]]:
+ """只根据 `.codebuddy` 根目录下的结构化路径推断 skill/rule。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return [], []
+
+ skills: list[str] = []
+ rules: list[str] = []
+ for p in _collect_path_strings(tool_input):
+ s = _extract_skill_from_path(p)
+ if s:
+ skills.append(s)
+ r = _extract_rule_from_path(p)
+ if r:
+ rules.append(r)
+
+ return list(dict.fromkeys(skills)), list(dict.fromkeys(rules))
+
+
+def extract_submodule_hits(data: dict) -> list[dict[str, str]]:
+ """仅从结构化 skill 路径中提取子模块命中结果,不扫描自由文本。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+
+ seen: set[tuple[str, str]] = set()
+ hits: list[dict[str, str]] = []
+ path_values = _collect_path_strings(tool_input)
+
+ for p in path_values:
+ parts = _path_parts(p)
+ for i in range(len(parts) - 3):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ skill_name = parts[i + 2]
+ sub_root = parts[i + 3]
+ if not re.fullmatch(r"[a-zA-Z0-9_\-]+", skill_name):
+ continue
+ if sub_root not in SUBMODULE_DIRS:
+ continue
+ sub_path = "/".join(parts[i + 3:]).rstrip("/")
+ key = (skill_name, sub_path)
+ if key in seen:
+ continue
+ seen.add(key)
+ hits.append({"skill": skill_name, "submodule": sub_path})
+ break
+
+ return hits
+
+
+def extract_bash_skill_scripts(data: dict) -> list[str]:
+ """从命令文本中的显式 `.codebuddy/skills` 路径识别 skill 脚本。"""
+ if data.get("tool_name") not in ("Bash", "bash", "execute_command"):
+ return []
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+ cmd = tool_input.get("command") or ""
+ if not isinstance(cmd, str) or not cmd.strip():
+ return []
+
+ skills: list[str] = []
+ for token in cmd.split():
+ t = token.strip("\"'`;,()[]{}")
+ s = _extract_skill_from_path(t)
+ if s:
+ skills.append(s)
+ return list(dict.fromkeys(skills))
diff --git a/.codebuddy/skills/agent-observability/scripts/core/state.py b/.codebuddy/skills/agent-observability/scripts/core/state.py
new file mode 100644
index 00000000..5e7d33e9
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/core/state.py
@@ -0,0 +1,1222 @@
+"""持久化状态层。
+
+这一层负责跨 hook 调用保存与协调状态:
+- session 级 skill/rule 使用统计
+- 当前 agent、派发关系与历史
+- transcript offset、去重 claim、pending emits
+- AgentLens sidecar 状态
+"""
+from __future__ import annotations
+
+import json
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+try:
+ import fcntl
+except Exception: # pragma: no cover - non-posix fallback
+ fcntl = None # type: ignore
+
+
+def get_state_path(base_dir: Path) -> Path:
+ """返回主状态文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".state.json"
+
+
+def get_pending_path(base_dir: Path) -> Path:
+ """返回 Pre/PostToolUse 配对使用的 pending 文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".pending_calls.json"
+
+
+def load_state(state_path: Path) -> dict[str, Any]:
+ """从磁盘加载状态;任何异常都回退为空字典。"""
+ if state_path.exists():
+ try:
+ return json.loads(state_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_state(state_path: Path, state: dict[str, Any]) -> None:
+ """把状态写回磁盘。"""
+ state_path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+
+
+def get_state_lock_path(state_path: Path) -> Path:
+ """返回状态写锁文件路径。"""
+ return state_path.parent / ".state.lock"
+
+
+def get_transcript_seen_path(state_path: Path) -> Path:
+ """返回 transcript usage 事件 claim 的 sidecar 台账文件。
+
+ 这部分单独存放,不混进 `.state.json`,是为了避免并发 hook 写状态时,
+ 旧 state 覆盖掉已经 claim 过的 transcript offset。
+ """
+ return state_path.parent / ".transcript_events_seen.json"
+
+
+@contextmanager
+def state_lock(state_path: Path):
+ """为状态修改提供跨进程建议锁(独占)。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_EX)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def state_read_lock(state_path: Path):
+ """为状态一致性读取提供跨进程共享读锁。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_SH)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+def update_state_locked(state_path: Path, updater):
+ """在跨进程锁保护下完成 load -> mutate -> save。"""
+ with state_lock(state_path):
+ state = load_state(state_path)
+ result = updater(state)
+ save_state(state_path, state)
+ return result
+
+
+def load_pending(pending_path: Path) -> dict[str, Any]:
+ """加载待配对的 pre/post 数据。"""
+ if pending_path.exists():
+ try:
+ return json.loads(pending_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_pending(pending_path: Path, data: dict[str, Any]) -> None:
+ """保存待配对的 pre/post 数据。"""
+ pending_path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def ensure_session(state: dict, sid: str) -> dict:
+ """确保某个 session 的状态结构存在,并返回该 session 字典。
+
+ Session 结构:
+ {
+ "skills": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "rules": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "started_at": float,
+ "current_agent": str,
+ "agent_history": [{ts, agent, evidence}],
+ "dispatched": {agent_name: count},
+ "_skills_meta": {...}, # SessionStart 时缓存的 inventory
+ "_rules_meta": {...},
+ }
+ """
+ if sid not in state:
+ state[sid] = {
+ "skills": {},
+ "rules": {},
+ "started_at": time.time(),
+ "current_agent": "main",
+ "agent_history": [],
+ "dispatched": {},
+ }
+ sess = state[sid]
+ # 保证字段类型正确,兼容旧数据
+ if not isinstance(sess.get("skills"), dict):
+ sess["skills"] = {}
+ if not isinstance(sess.get("rules"), dict):
+ sess["rules"] = {}
+ sess.setdefault("current_agent", "main")
+ sess.setdefault("agent_history", [])
+ sess.setdefault("dispatched", {})
+ if not isinstance(sess.get("_pending_tool_emits"), list):
+ sess["_pending_tool_emits"] = []
+ return sess
+
+
+def get_devflow_state(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 缓存的 devflow 上下文与最近一次 stage 快照(见 devflow.py)。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ dv = sess.get("_devflow")
+ return dv if isinstance(dv, dict) else {}
+
+
+def set_devflow_state(state: dict[str, Any], sid: str, updates: dict[str, Any]) -> None:
+ """合并写入某个 session 的 devflow 缓存字段(`checked` / `context` / `last_snapshot`)。"""
+ sess = ensure_session(state, sid)
+ dv = sess.get("_devflow")
+ if not isinstance(dv, dict):
+ dv = {}
+ sess["_devflow"] = dv
+ dv.update(updates)
+
+
+def get_agentlens_session(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 的 AgentLens sidecar payload。"""
+ sess = ensure_session(state, sid)
+ payload = sess.setdefault("_agentlens", {})
+ if not isinstance(payload, dict):
+ payload = {}
+ sess["_agentlens"] = payload
+ return payload
+
+
+AGENTLENS_SCHEMA_VERSION = 2
+_TURN_HISTORY_MAX = 5
+
+
+def _migrate_agentlens_v1_to_v2(payload: dict[str, Any], sess: dict[str, Any] | None) -> dict[str, Any]:
+ """把 v1 版 ``_agentlens`` payload 转成以 turn 为中心的 v2 布局。
+
+ v1 布局(pre-turn):
+ {"carrier": {...}, "enabled": bool, "session_id": "...", "app_name": "..."}
+ v2 布局(turn-centric):
+ {
+ "version": 2,
+ "session_id": "...",
+ "enabled": bool,
+ "app_name": "...",
+ "current_turn": {"turn_id": "legacy", "started_at": ..., "carrier": {...}, "subagent_spans": {}, "agent_spans": {}, "step_spans": {}},
+ "turn_history": [],
+ }
+
+ 幂等约束:如果已经带有 ``version``,就原样返回。
+ """
+ if not isinstance(payload, dict):
+ return {"version": AGENTLENS_SCHEMA_VERSION, "enabled": False, "current_turn": None, "turn_history": []}
+ if payload.get("version") == AGENTLENS_SCHEMA_VERSION:
+ payload.setdefault("current_turn", None)
+ payload.setdefault("turn_history", [])
+ current = payload.get("current_turn")
+ if isinstance(current, dict):
+ current.setdefault("subagent_spans", {})
+ current.setdefault("agent_spans", {})
+ current.setdefault("step_spans", {})
+ return payload
+
+ migrated: dict[str, Any] = {
+ "version": AGENTLENS_SCHEMA_VERSION,
+ "session_id": payload.get("session_id"),
+ "enabled": bool(payload.get("enabled", False)),
+ }
+ if "app_name" in payload:
+ migrated["app_name"] = payload.get("app_name")
+ if "last_error" in payload:
+ migrated["last_error"] = payload.get("last_error")
+
+ legacy_carrier = payload.get("carrier")
+ if isinstance(legacy_carrier, dict) and legacy_carrier:
+ started_at = None
+ if isinstance(sess, dict):
+ try:
+ started_at = float(sess.get("started_at") or 0) or None
+ except Exception:
+ started_at = None
+ migrated["current_turn"] = {
+ "turn_id": "legacy",
+ "started_at": started_at or time.time(),
+ "carrier": dict(legacy_carrier),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ else:
+ migrated["current_turn"] = None
+ migrated["turn_history"] = []
+ return migrated
+
+
+def load_agentlens_session(state_path: Path, sid: str) -> dict[str, Any]:
+ """加载某个 session 已持久化的 AgentLens sidecar payload。
+
+ 这里使用共享读锁,避免并发 ``update_agentlens_session`` 写入时读到撕裂数据。
+ 返回值会透明地把 v1 payload 迁移成 v2 副本;真正落盘迁移会在下一次写入时完成。
+ """
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ payload = sess.get("_agentlens")
+ if not isinstance(payload, dict):
+ return {}
+ # 先给调用方返回迁移后的副本,真正持久化迁移留到后续写入时完成。
+ return _migrate_agentlens_v1_to_v2(dict(payload), sess)
+
+
+def update_agentlens_session(
+ state_path: Path,
+ sid: str,
+ updates: dict[str, Any],
+ *,
+ clear_keys: list[str] | None = None,
+) -> dict[str, Any]:
+ """原子地持久化某个 session 的 AgentLens sidecar 字段。
+
+ 在合并 updates 之前会先做 v1→v2 迁移,这样磁盘上的 payload 会随着写入自然收敛到 v2。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ # 如果仍是 v1,就原地迁移。
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+ for key in clear_keys or []:
+ payload.pop(key, None)
+ for key, value in updates.items():
+ if value is None:
+ payload.pop(key, None)
+ else:
+ payload[key] = value
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(payload)
+
+ return update_state_locked(state_path, _update)
+
+
+def begin_turn(
+ state_path: Path,
+ sid: str,
+ turn_id: str,
+ carrier: dict[str, str],
+ *,
+ started_at: float | None = None,
+ max_history: int = _TURN_HISTORY_MAX,
+) -> dict[str, Any]:
+ """在独占锁下打开一个新的 turn。
+
+ 语义:
+ - 如果存在 ``current_turn``,先把它归档进有上限的 ``turn_history``。
+ - 为新 turn 重置 ``subagent_spans`` / ``agent_spans`` / ``step_spans``。
+ - 对相同 ``turn_id`` 保持幂等:重复调用直接返回已有 ``current_turn``,
+ 不重新生成 trace_id。
+
+ 返回最终生成的 ``current_turn`` 字典。
+ """
+ ts = float(started_at if started_at is not None else time.time())
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+
+ current = payload.get("current_turn")
+ # 幂等:如果同一个 turn_id 还在处理中,就原样返回。
+ if isinstance(current, dict) and str(current.get("turn_id") or "") == str(turn_id):
+ return dict(current)
+
+ # 归档上一个 turn。
+ if isinstance(current, dict) and current.get("turn_id"):
+ history = payload.setdefault("turn_history", [])
+ if not isinstance(history, list):
+ history = []
+ payload["turn_history"] = history
+ archived = {
+ "turn_id": current.get("turn_id"),
+ "started_at": current.get("started_at"),
+ "ended_at": ts,
+ "carrier_traceparent": (current.get("carrier") or {}).get("traceparent"),
+ }
+ history.append(archived)
+ if len(history) > max_history:
+ del history[: len(history) - max_history]
+
+ new_turn = {
+ "turn_id": str(turn_id),
+ "started_at": ts,
+ "carrier": dict(carrier or {}),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ payload["current_turn"] = new_turn
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_turn)
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span(
+ state_path: Path,
+ sid: str,
+ role: str,
+ carrier: dict[str, str],
+) -> dict[str, str]:
+ """在当前 turn 下登记 subagent 的 ``invoke_agent`` 子 span carrier。
+
+ 对 `(turn, role)` 维度保持幂等:如果活跃 turn 下已经记录了该角色的 carrier,
+ 就直接返回已有值,不再重复创建。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ # 没有活跃 turn,无法登记 subagent span。
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ subs[role] = {"carrier": dict(carrier or {}), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span_atomic(
+ state_path: Path,
+ sid: str,
+ role: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建 subagent 的 ``invoke_agent`` carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_subagent_carrier`` 先产生了不可逆的 zhiyanllm ``invoke_agent`` span,
+ 随后另一个 hook 进程已经写入同一角色,导致本次创建变成孤儿。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ subs[role] = {"carrier": dict(new_carrier), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_current_turn(state_path: Path, sid: str) -> dict[str, Any] | None:
+ """返回当前活跃的 turn 字典;如果没有打开 turn,就返回 None。"""
+ payload = load_agentlens_session(state_path, sid)
+ current = payload.get("current_turn")
+ return current if isinstance(current, dict) else None
+
+
+def get_subagent_span_carrier(state_path: Path, sid: str, role: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 subagent span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ subs = turn.get("subagent_spans")
+ if not isinstance(subs, dict):
+ return None
+ rec = subs.get(role)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def _empty_agent_aggregate() -> dict[str, Any]:
+ """创建一份空的 agent 聚合指标骨架。"""
+ return {
+ "tokens": {
+ "input": 0,
+ "output": 0,
+ "cache_read": 0,
+ "cache_creation": 0,
+ "total": 0,
+ },
+ "event_count": 0,
+ "cost_usd": 0.0,
+ "tool_duration_ms": 0,
+ "llm_call_count": 0,
+ "tool_call_count": 0,
+ "step_count": 0,
+ }
+
+
+def _normalize_agent(agent: str | None) -> str:
+ """把 agent 名归一化,空值统一落到 ``main``。"""
+ return str(agent or "main").strip() or "main"
+
+
+def _ensure_turn_agent_spans(current: dict[str, Any]) -> dict[str, Any]:
+ """确保当前 turn 下存在 `agent_spans` 容器。"""
+ agent_spans = current.setdefault("agent_spans", {})
+ if not isinstance(agent_spans, dict):
+ agent_spans = {}
+ current["agent_spans"] = agent_spans
+ return agent_spans
+
+
+def _ensure_agent_span_rec(current: dict[str, Any], agent: str) -> dict[str, Any]:
+ """确保指定 agent 在当前 turn 下有一条完整聚合记录。"""
+ agent_spans = _ensure_turn_agent_spans(current)
+ rec = agent_spans.get(agent)
+ if not isinstance(rec, dict):
+ rec = {}
+ agent_spans[agent] = rec
+ carrier = rec.get("carrier")
+ if not isinstance(carrier, dict):
+ rec["carrier"] = {}
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ rec["aggregate"] = _empty_agent_aggregate()
+ return rec
+
+
+def get_agent_span_carrier(state_path: Path, sid: str, agent: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 agent 分组 span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(agent))
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def upsert_agent_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """原子地获取或创建 agent 分组 span carrier。"""
+ now = time.time()
+ normalized_agent = _normalize_agent(agent)
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ existing = rec.get("carrier")
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ rec["carrier"] = dict(new_carrier)
+ rec.setdefault("opened_at", now)
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def bump_agent_aggregate(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ usage_event: dict[str, Any] | None = None,
+ tool_event: dict[str, Any] | None = None,
+ step_created: bool = False,
+) -> dict[str, Any]:
+ """增加活跃 turn 下按 agent 聚合的统计指标。"""
+ normalized_agent = _normalize_agent(agent)
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ def _float(value: Any) -> float:
+ try:
+ return float(value or 0)
+ except Exception:
+ return 0.0
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ aggregate = _empty_agent_aggregate()
+ rec["aggregate"] = aggregate
+ tokens = aggregate.setdefault("tokens", {})
+ if not isinstance(tokens, dict):
+ tokens = {}
+ aggregate["tokens"] = tokens
+
+ if step_created:
+ aggregate["step_count"] = _int(aggregate.get("step_count")) + 1
+
+ if isinstance(tool_event, dict):
+ aggregate["tool_call_count"] = _int(aggregate.get("tool_call_count")) + 1
+ ms = tool_event.get("ms")
+ if ms is not None:
+ aggregate["tool_duration_ms"] = _int(aggregate.get("tool_duration_ms")) + _int(ms)
+
+ if isinstance(usage_event, dict):
+ raw_tokens = usage_event.get("tokens")
+ if isinstance(raw_tokens, dict):
+ # 聚合 agent 摘要里需要暴露的字段。
+ for key in ("input", "output", "cache_read", "cache_creation"):
+ tokens[key] = _int(tokens.get(key)) + _int(raw_tokens.get(key))
+ # total = input + output,其中 input 已经包含 cache_read。
+ tokens["total"] = _int(tokens.get("input")) + _int(tokens.get("output"))
+ aggregate["llm_call_count"] = _int(aggregate.get("llm_call_count")) + 1
+ aggregate["event_count"] = _int(aggregate.get("event_count")) + 1
+ aggregate["cost_usd"] = round(_float(aggregate.get("cost_usd")) + _float(usage_event.get("cost_usd")), 10)
+
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+ return update_state_locked(state_path, _update)
+
+
+def get_subagent_aggregate(state_path: Path, sid: str, role: str) -> dict[str, Any] | None:
+ """返回活跃 turn 下当前 agent 的聚合摘要。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(role))
+ if not isinstance(rec, dict):
+ return None
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ return None
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+
+def _step_span_key(agent: str, message_id: str) -> str:
+ """为 step span 生成按 agent 与 message_id 唯一定位的 key。"""
+ return f"{agent}|{message_id}"
+
+
+def upsert_step_span(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ carrier: dict[str, str],
+ *,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在当前 turn 下登记一个 step span carrier,并对 `(turn, agent, message_id)` 保持幂等。"""
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ steps[key] = {
+ "carrier": dict(carrier or {}),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_step_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ *,
+ carrier_factory: Any,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建一个 step span carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_step_carrier`` 已经先产生了不可逆的 zhiyanllm span,
+ 但随后另一个 hook 进程已经写入同一 step,导致本次创建失去归属。
+ """
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ steps[key] = {
+ "carrier": dict(new_carrier),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_step_span_carrier(state_path: Path, sid: str, agent: str, message_id: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 step span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ steps = turn.get("step_spans")
+ if not isinstance(steps, dict):
+ return None
+ key = _step_span_key(str(agent or "main").strip() or "main", str(message_id or "").strip())
+ rec = steps.get(key)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def get_latest_session_id(state: dict[str, Any]) -> str | None:
+ """返回 state 中最近启动的 session id。"""
+ latest_sid: str | None = None
+ latest_started_at = -1.0
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ started_at = float(sess.get("started_at", 0) or 0)
+ if started_at >= latest_started_at:
+ latest_started_at = started_at
+ latest_sid = sid
+ return latest_sid
+
+
+def get_pending_tool_emits(state_path: Path, sid: str) -> list[dict[str, Any]]:
+ """返回等待与 transcript/message_id 关联的缓冲 tool 事件。"""
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return []
+ pending = sess.get("_pending_tool_emits")
+ if not isinstance(pending, list):
+ return []
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+
+def append_pending_tool_emit(state_path: Path, sid: str, tool_event: dict[str, Any]) -> list[dict[str, Any]]:
+ """缓存一条 tool 事件,延后再做 message_id 关联。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ pending = sess.setdefault("_pending_tool_emits", [])
+ if not isinstance(pending, list):
+ pending = []
+ sess["_pending_tool_emits"] = pending
+ pending.append(dict(tool_event))
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+ return update_state_locked(state_path, _update)
+
+
+def replace_pending_tool_emits(state_path: Path, sid: str, tool_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """覆盖某个 session 的缓冲 tool 事件队列。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ normalized = [dict(item) for item in tool_events if isinstance(item, dict)]
+ sess["_pending_tool_emits"] = normalized
+ return [dict(item) for item in normalized]
+
+ return update_state_locked(state_path, _update)
+
+def bump_skill(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ submodule: str | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 skill 使用计数,并按需记录子模块与 agent 维度。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["skills"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "version": None,
+ "submodule_hits": {},
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta:
+ if meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if meta.get("version") and not rec.get("version"):
+ rec["version"] = meta["version"]
+ # 子模块命中统计
+ if submodule:
+ sub_dict = rec.setdefault("submodule_hits", {})
+ if not isinstance(sub_dict, dict):
+ sub_dict = {}
+ rec["submodule_hits"] = sub_dict
+ sh = sub_dict.setdefault(submodule, {
+ "count": 0, "first_ts": now, "last_ts": now, "tools": [],
+ })
+ sh["count"] += 1
+ sh["last_ts"] = now
+ if tool and tool not in sh["tools"]:
+ sh["tools"].append(tool)
+ # 按 agent 维度统计
+ if agent:
+ ag_dict = rec.setdefault("by_agent", {})
+ if not isinstance(ag_dict, dict):
+ ag_dict = {}
+ rec["by_agent"] = ag_dict
+ ar = ag_dict.setdefault(agent, {
+ "count": 0, "first_ts": now, "last_ts": now,
+ "tools": [], "submodules": [],
+ })
+ ar["count"] += 1
+ ar["last_ts"] = now
+ if tool and tool not in ar["tools"]:
+ ar["tools"].append(tool)
+ if submodule and submodule not in ar["submodules"]:
+ ar["submodules"].append(submodule)
+
+
+def bump_rule(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 rule 使用计数。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["rules"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta and meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if agent:
+ ag = rec.setdefault("by_agent", {})
+ if not isinstance(ag, dict):
+ ag = {}
+ rec["by_agent"] = ag
+ ar = ag.setdefault(agent, {"count": 0, "last_ts": now})
+ ar["count"] += 1
+ ar["last_ts"] = now
+
+
+def prune_sessions(state: dict, max_sessions: int = 5) -> None:
+ """在 state 中只保留最近的 N 个 session。"""
+ # 先过滤掉非 session 键(以下划线开头)
+ session_keys = [k for k in state if not k.startswith("_")]
+ if len(session_keys) > max_sessions:
+ to_remove = sorted(
+ session_keys,
+ key=lambda s: state[s].get("started_at", 0) if isinstance(state[s], dict) else 0,
+ )[:len(session_keys) - max_sessions]
+ for k in to_remove:
+ del state[k]
+
+
+def _transcript_scope_key(transcript_path: str | None = None) -> str:
+ """把 transcript 路径归一化成内部 scope key。"""
+ path = str(transcript_path or "").strip()
+ return path or "__session__"
+
+
+def _ensure_transcript_scopes(sess: dict) -> dict[str, dict[str, Any]]:
+ """确保 session 下存在 transcript scope 容器,并兼容旧字段迁移。"""
+ scopes = sess.setdefault("_transcripts", {})
+ if not isinstance(scopes, dict):
+ scopes = {}
+ sess["_transcripts"] = scopes
+
+ legacy_scope = scopes.get("__session__")
+ if not isinstance(legacy_scope, dict):
+ legacy_scope = {}
+ scopes["__session__"] = legacy_scope
+
+ if "offset" not in legacy_scope and "_transcript_offset" in sess:
+ legacy_scope["offset"] = int(sess.get("_transcript_offset", 0) or 0)
+
+ legacy_usage = sess.get("_last_cumulative_usage")
+ if "last_cumulative_usage" not in legacy_scope and isinstance(legacy_usage, dict) and legacy_usage:
+ legacy_scope["last_cumulative_usage"] = legacy_usage
+
+ legacy_dedup = sess.get("_last_usage_event")
+ if "last_usage_event" not in legacy_scope and isinstance(legacy_dedup, dict) and legacy_dedup:
+ legacy_scope["last_usage_event"] = legacy_dedup
+
+ return scopes
+
+
+def _get_transcript_scope(
+ sess: dict,
+ transcript_path: str | None = None,
+ *,
+ create: bool = False,
+) -> dict[str, Any] | None:
+ """获取指定 transcript 的 scope;必要时按需创建。"""
+ scopes = _ensure_transcript_scopes(sess)
+ key = _transcript_scope_key(transcript_path)
+ scope = scopes.get(key)
+ if isinstance(scope, dict):
+ return scope
+ if create:
+ scope = {}
+ scopes[key] = scope
+ return scope
+ return None
+
+
+def get_transcript_offset(state: dict, sid: str, transcript_path: str | None = None) -> int:
+ """获取某个 session/transcript 最近一次上报的 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ return int(scope.get("offset", 0) or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ return int(sess.get("_transcript_offset", 0) or 0)
+ return 0
+
+
+def set_transcript_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """在成功上报后持久化 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["offset"] = int(offset or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = int(offset or 0)
+
+
+def get_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, int]:
+ """获取某个 transcript 最近一次上报的累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ v = sess.get("_last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+ return {}
+
+
+def get_last_llm_offset(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> int:
+ """获取最近一次处理到的 LLM source_offset,用于增量构建 I/O。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_llm_offset")
+ if isinstance(v, (int, float)):
+ return int(v)
+ return 0
+
+
+def set_last_llm_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近处理到的 LLM source_offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_llm_offset"] = int(offset or 0)
+
+
+def set_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ usage: dict[str, int],
+ transcript_path: str | None = None,
+) -> None:
+ """在处理完一个 turn 后持久化累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_cumulative_usage"] = usage
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = usage
+
+
+def get_last_usage_event(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, Any] | None:
+ """获取某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return None
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ event = scope.get("last_usage_event")
+ if isinstance(event, dict):
+ return event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ event = sess.get("_last_usage_event")
+ if isinstance(event, dict):
+ return event
+ return None
+
+
+def set_last_usage_event(
+ state: dict,
+ sid: str,
+ usage_event: dict[str, Any],
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_usage_event"] = usage_event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_usage_event"] = usage_event
+
+
+def claim_transcript_event(
+ state_path: Path,
+ sid: str,
+ event_key: str,
+ transcript_path: str | None = None,
+ *,
+ max_seen_keys: int = 512,
+) -> bool:
+ """跨进程原子地声明一个 transcript 作用域内的事件键。"""
+ seen_path = get_transcript_seen_path(state_path)
+ scope_key = f"{sid}|{_transcript_scope_key(transcript_path)}"
+
+ with state_lock(state_path):
+ if seen_path.exists():
+ try:
+ ledger = json.loads(seen_path.read_text("utf-8"))
+ except Exception:
+ ledger = {}
+ else:
+ ledger = {}
+ if not isinstance(ledger, dict):
+ ledger = {}
+
+ seen = ledger.setdefault(scope_key, {})
+ if not isinstance(seen, dict):
+ seen = {}
+ ledger[scope_key] = seen
+ if event_key in seen:
+ return False
+ seen[event_key] = time.time()
+ if len(seen) > max_seen_keys:
+ stale_keys = sorted(seen, key=lambda k: float(seen.get(k, 0) or 0))[:-max_seen_keys]
+ for key in stale_keys:
+ seen.pop(key, None)
+ seen_path.write_text(json.dumps(ledger, ensure_ascii=False), encoding="utf-8")
+ return True
+
+
+def commit_transcript_progress(
+ state_path: Path,
+ sid: str,
+ transcript_path: str | None = None,
+ *,
+ offset: int | None = None,
+ last_cumulative_usage: dict[str, int] | None = None,
+) -> None:
+ """在处理完一个窗口后,原子地持久化 transcript 解析进度。"""
+
+ def _update(state: dict[str, Any]) -> None:
+ sess = ensure_session(state, sid)
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if not isinstance(scope, dict):
+ return
+ if offset is not None:
+ current_offset = int(scope.get("offset", 0) or 0)
+ next_offset = int(offset or 0)
+ if next_offset > current_offset:
+ scope["offset"] = next_offset
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = next_offset
+ if isinstance(last_cumulative_usage, dict) and last_cumulative_usage:
+ scope["last_cumulative_usage"] = last_cumulative_usage
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = last_cumulative_usage
+
+ update_state_locked(state_path, _update)
diff --git a/.codebuddy/skills/agent-observability/scripts/dashboard/index.html b/.codebuddy/skills/agent-observability/scripts/dashboard/index.html
new file mode 100644
index 00000000..8c391f5c
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/dashboard/index.html
@@ -0,0 +1,1086 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent Observability</title>
+<style>
+:root{
+ --surface-page:#f9f9f7; --surface-card:#fcfcfb; --surface-sunken:#f2f1ec;
+ --text-primary:#0b0b0b; --text-secondary:#52514e; --text-muted:#898781;
+ --grid:#e1e0d9; --axis:#c3c2b7; --border:rgba(11,11,11,0.10);
+ --series-blue:#2a78d6; --series-orange:#eb6834; --series-aqua:#1baf7a; --series-yellow:#eda100;
+ --series-blue-wash:rgba(42,120,214,0.10); --series-orange-wash:rgba(235,104,52,0.10);
+ --seq-100:#cde2fb; --seq-200:#9ec5f4; --seq-350:#5598e7; --seq-450:#2a78d6; --seq-600:#184f95;
+ --status-good:#0ca30c; --status-warning:#b8790a; --status-critical:#d03b3b;
+ --status-good-bg:rgba(12,163,12,0.10); --status-warning-bg:rgba(184,121,10,0.12); --status-critical-bg:rgba(208,59,59,0.10);
+ --accent-ring:rgba(42,120,214,0.35);
+}
+@media (prefers-color-scheme: dark){
+ :root:not([data-theme="light"]){
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+ }
+}
+:root[data-theme="dark"]{
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+}
+*{box-sizing:border-box;}
+body{background:var(--surface-page); color:var(--text-primary); font-family:"IBM Plex Sans","Segoe UI",system-ui,sans-serif; margin:0;}
+.mono{font-family:"IBM Plex Mono","SFMono-Regular",ui-monospace,monospace;}
+.tab-nums{font-variant-numeric:tabular-nums;}
+h1,h2,h3{text-wrap:balance; margin:0;}
+.app{max-width:1180px; margin:0 auto; padding:28px 24px 64px;}
+
+/* header */
+.app-header{display:flex; flex-wrap:wrap; align-items:flex-end; justify-content:space-between; gap:16px; margin-bottom:6px;}
+.app-title{font-size:22px; font-weight:600; letter-spacing:-0.01em;}
+.app-sub{color:var(--text-secondary); font-size:13.5px; margin-top:4px; max-width:60ch;}
+.sample-badge{display:inline-flex; align-items:center; gap:6px; font-family:"IBM Plex Mono",monospace; font-size:11px; letter-spacing:.04em; text-transform:uppercase; color:var(--status-warning); background:var(--status-warning-bg); border:1px solid var(--border); border-radius:5px; padding:4px 8px; white-space:nowrap;}
+
+/* filter row */
+.filter-row{display:flex; align-items:center; gap:8px; margin:18px 0 22px; padding-bottom:14px; border-bottom:1px solid var(--grid);}
+.filter-label{font-size:12px; color:var(--text-muted); text-transform:uppercase; letter-spacing:.05em; margin-right:4px;}
+.range-btn{font-family:inherit; font-size:13px; color:var(--text-secondary); background:transparent; border:1px solid transparent; border-radius:6px; padding:6px 11px; cursor:pointer;}
+.range-btn:hover{background:var(--surface-sunken);}
+.range-btn[aria-pressed="true"]{background:var(--surface-card); border-color:var(--border); color:var(--text-primary); font-weight:600;}
+.range-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:1px;}
+
+/* KPI strip */
+.kpis{display:grid; grid-template-columns:repeat(5,1fr); gap:1px; background:var(--border); border:1px solid var(--border); border-radius:10px; overflow:hidden; margin-bottom:24px;}
+.kpi{background:var(--surface-card); padding:16px 18px;}
+.kpi-label{font-size:12px; color:var(--text-muted);}
+.kpi-value{font-size:24px; font-weight:600; margin-top:6px; letter-spacing:-0.01em;}
+.kpi-delta{font-size:12px; margin-top:4px;}
+.kpi-delta.up{color:var(--status-critical);}
+.kpi-delta.down{color:var(--status-good);}
+.kpi-delta.flat{color:var(--text-muted);}
+
+/* tabs */
+.tabs{display:flex; gap:4px; border-bottom:1px solid var(--grid); margin-bottom:22px;}
+.tab-btn{font-family:inherit; font-size:13.5px; color:var(--text-secondary); background:transparent; border:none; border-bottom:2px solid transparent; padding:10px 4px; margin-right:22px; cursor:pointer;}
+.tab-btn:hover{color:var(--text-primary);}
+.tab-btn[aria-selected="true"]{color:var(--text-primary); border-bottom-color:var(--series-blue); font-weight:600;}
+.tab-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:2px;}
+.tab-panel[hidden]{display:none;}
+
+/* cards */
+.card{background:var(--surface-card); border:1px solid var(--border); border-radius:10px; padding:18px 20px;}
+.card + .card{margin-top:16px;}
+.card-head{display:flex; align-items:baseline; justify-content:space-between; margin-bottom:14px; gap:12px; flex-wrap:wrap;}
+.card-title{font-size:14px; font-weight:600;}
+.card-note{font-size:12px; color:var(--text-muted);}
+.grid-2{display:grid; grid-template-columns:1.3fr 1fr; gap:16px;}
+/* .card + .card 的 margin-top 是给"同一列里纵向堆叠的卡片"留间距用的;grid 的两个
+ 格子在 DOM 里也是相邻兄弟,会被同一条规则误伤,导致右边格子的卡片顶部被顶低
+ 16px、和左边对不齐。grid 行内的卡片间距已经由 .grid-2 的 gap 负责,这里清零。 */
+.grid-2 > .card + .card{margin-top:0;}
+/* Token 构成只画两根竖条,不需要宽度;按模型的成本占比要给模型名留横向空间,
+ 反过来分配才对得上两张图各自的实际需要。 */
+.grid-2.grid-2--cost{grid-template-columns:1fr 1.3fr;}
+/* 按模型的成本占比条数不固定(1~5 行),卡片天然高矮不一;Token 构成固定只有一张
+ 图,让它的图表区跟着 grid 拉伸出来的实际卡片高度走,而不是停在自己内容的高度、
+ 底下空出一大截。 */
+.grid-2--cost .card--fill-h{display:flex; flex-direction:column;}
+.grid-2--cost .card--fill-h .chart-wrap{flex:1 1 auto; min-height:160px;}
+.grid-2--cost .card--fill-h .chart-wrap svg.chart{height:100%;}
+@media(max-width:860px){.grid-2{grid-template-columns:1fr;} .grid-2.grid-2--cost{grid-template-columns:1fr;} .kpis{grid-template-columns:repeat(2,1fr);}}
+
+/* legend */
+.legend{display:flex; gap:14px; flex-wrap:wrap; font-size:12px; color:var(--text-secondary);}
+.legend-item{display:flex; align-items:center; gap:6px;}
+.legend-swatch{width:10px; height:10px; border-radius:2px; flex:none;}
+.legend-line{width:14px; height:2px; border-radius:1px; flex:none;}
+
+/* chart chrome */
+.chart-wrap{position:relative;}
+svg.chart{width:100%; height:auto; display:block; overflow:visible;}
+.axis-text{font-size:10.5px; fill:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.gridline{stroke:var(--grid); stroke-width:1;}
+.crosshair{stroke:var(--axis); stroke-width:1; pointer-events:none;}
+.tooltip{position:absolute; pointer-events:none; background:var(--surface-card); border:1px solid var(--border); border-radius:8px; padding:9px 11px; font-size:12px; box-shadow:0 6px 20px rgba(0,0,0,.16); opacity:0; transition:opacity .08s ease; z-index:5; min-width:132px;}
+.tooltip.show{opacity:1;}
+.tooltip-date{color:var(--text-muted); font-size:11px; margin-bottom:5px;}
+.tooltip-row{display:flex; align-items:center; gap:6px; justify-content:space-between; margin-top:3px;}
+.tooltip-key{display:flex; align-items:center; gap:6px; color:var(--text-secondary);}
+.tooltip-swatch{width:10px; height:2px; border-radius:1px;}
+.tooltip-val{font-family:"IBM Plex Mono",monospace; font-weight:600; color:var(--text-primary);}
+.hit-target{fill:transparent; cursor:crosshair;}
+.mark-lift{transition:opacity .08s ease;}
+
+/* stat / hero */
+.hero-row{display:flex; align-items:flex-end; gap:10px;}
+.hero-figure{font-size:30px; font-weight:600; letter-spacing:-0.01em;}
+.hero-unit{font-size:13px; color:var(--text-muted); padding-bottom:5px;}
+
+/* reminders */
+.reminders{display:grid; grid-template-columns:repeat(3,1fr); gap:12px;}
+@media(max-width:860px){.reminders{grid-template-columns:1fr;}}
+.reminder{border-radius:9px; padding:13px 14px; border:1px solid var(--border); display:flex; gap:10px;}
+.reminder.crit{background:var(--status-critical-bg);}
+.reminder.warn{background:var(--status-warning-bg);}
+.reminder.good{background:var(--status-good-bg);}
+.reminder-icon{flex:none; width:20px; height:20px; border-radius:5px; display:flex; align-items:center; justify-content:center; font-size:12px; font-weight:700; color:#fff; margin-top:1px;}
+.reminder.crit .reminder-icon{background:var(--status-critical);}
+.reminder.warn .reminder-icon{background:var(--status-warning); color:#3a2600;}
+.reminder.good .reminder-icon{background:var(--status-good);}
+.reminder-label{font-size:11px; text-transform:uppercase; letter-spacing:.04em; font-weight:700;}
+.reminder.crit .reminder-label{color:var(--status-critical);}
+.reminder.warn .reminder-label{color:var(--status-warning);}
+.reminder.good .reminder-label{color:var(--status-good);}
+.reminder-text{font-size:12.5px; color:var(--text-secondary); margin-top:3px; line-height:1.5;}
+.reminder-text b{color:var(--text-primary); font-weight:600;}
+
+/* tables */
+.table-scroll{overflow-x:auto;}
+table{width:100%; border-collapse:collapse; font-size:12.8px; min-width:640px;}
+th{text-align:left; font-size:11px; text-transform:uppercase; letter-spacing:.04em; color:var(--text-muted); font-weight:600; padding:8px 10px; border-bottom:1px solid var(--grid); white-space:nowrap;}
+td{padding:9px 10px; border-bottom:1px solid var(--grid); color:var(--text-secondary); white-space:nowrap;}
+tr.data-row{cursor:pointer;}
+tr.data-row:hover td{background:var(--surface-sunken);}
+td.strong{color:var(--text-primary); font-weight:600;}
+.chip{display:inline-flex; align-items:center; gap:5px; font-size:11px; font-weight:600; padding:3px 8px; border-radius:99px;}
+.chip.good{color:var(--status-good); background:var(--status-good-bg);}
+.chip.crit{color:var(--status-critical); background:var(--status-critical-bg);}
+.chip-dot{width:6px; height:6px; border-radius:50%; background:currentColor;}
+.expand-row td{background:var(--surface-sunken); padding:0;}
+.timeline{padding:14px 16px 16px;}
+.timeline-turn{margin-bottom:14px;}
+.timeline-turn:last-child{margin-bottom:0;}
+.timeline-turn-head{display:flex; align-items:baseline; justify-content:space-between; gap:10px; margin-bottom:6px;}
+.timeline-turn-label{font-size:11px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.timeline-turn-count{font-size:11px; color:var(--text-muted); white-space:nowrap;}
+.timeline-scroll{overflow-x:auto; padding-bottom:3px;}
+.timeline-track{display:flex; gap:2px; align-items:stretch; height:26px; width:max-content; min-width:100%;}
+.timeline-seg{flex:0 0 auto; border-radius:4px; display:flex; align-items:center; justify-content:center; font-size:10.5px; color:#fff; font-family:"IBM Plex Mono",monospace; white-space:nowrap; padding:0 6px; overflow:hidden; text-overflow:ellipsis; box-sizing:border-box;}
+.timeline-seg.ok{background:var(--series-blue);}
+.timeline-seg.err{background:var(--status-critical);}
+.timeline-seg.usage{background:var(--series-aqua);}
+.timeline-seg.merged{background:var(--seq-350);}
+/* 派发给非 main 的 agent(比如 solo-developer、architect)执行的调用,顶部加一条
+ 高亮边框——同一个 turn 里经常混着 main 自己做的调用和转派出去的调用,光看
+ 颜色(ok/err/merged)分不出"这段到底是谁做的"。*/
+.timeline-seg.subagent{border-top:3px solid var(--series-yellow);}
+
+/* skill list */
+.bar-list{display:flex; flex-direction:column; gap:10px;}
+.bar-row{display:grid; grid-template-columns:150px 1fr 64px; gap:10px; align-items:center; font-size:12.5px;}
+.bar-row .name{color:var(--text-primary); overflow:hidden; text-overflow:ellipsis; white-space:nowrap;}
+.bar-track{height:16px; background:var(--surface-sunken); border-radius:4px; position:relative; overflow:hidden;}
+.bar-fill{height:100%; border-radius:4px;}
+.bar-row .val{text-align:right; color:var(--text-secondary);}
+.unused-list{display:flex; flex-direction:column; gap:8px; margin-top:4px;}
+.unused-item{display:flex; align-items:center; justify-content:space-between; gap:10px; font-size:12.5px; padding:8px 10px; background:var(--surface-sunken); border-radius:7px;}
+.unused-name{color:var(--text-primary); font-family:"IBM Plex Mono",monospace; font-size:12px;}
+.reason-chip{font-size:10.5px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace; background:var(--surface-card); border:1px solid var(--border); padding:2px 7px; border-radius:5px;}
+
+/* devflow health */
+.health-row{display:flex; gap:22px; flex-wrap:wrap; align-items:center;}
+.health-stat{display:flex; flex-direction:column; gap:2px;}
+.health-stat .v{font-size:20px; font-weight:600;}
+.health-stat .l{font-size:11px; color:var(--text-muted);}
+.health-bar{flex:1 1 260px; min-width:220px;}
+.health-bar-track{height:10px; border-radius:5px; background:var(--surface-sunken); overflow:hidden; display:flex;}
+.health-bar-seg{height:100%;}
+.health-legend{display:flex; gap:14px; margin-top:8px; font-size:11.5px; color:var(--text-secondary);}
+
+/* devflow runs */
+.run-card{border:1px solid var(--border); border-radius:9px; padding:14px 16px; background:var(--surface-sunken);}
+.run-card + .run-card{margin-top:12px;}
+.run-head{display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:8px; margin-bottom:12px;}
+.run-title{font-family:"IBM Plex Mono",monospace; font-size:12.5px; color:var(--text-primary); font-weight:600;}
+.run-meta{display:flex; align-items:center; gap:8px; font-size:11.5px; color:var(--text-muted);}
+.size-chip{font-size:10.5px; text-transform:uppercase; letter-spacing:.03em; font-weight:700; padding:2px 7px; border-radius:5px; background:var(--surface-card); border:1px solid var(--border); color:var(--text-secondary);}
+.run-status-chip{font-size:11px; font-weight:600; padding:3px 9px; border-radius:99px; display:inline-flex; align-items:center; gap:5px;}
+.stepper{display:flex; align-items:center; overflow-x:auto; padding-bottom:4px;}
+.step{flex:0 0 auto; display:flex; flex-direction:column; align-items:center; width:68px; position:relative;}
+.step-dot{width:26px; height:26px; border-radius:50%; display:flex; align-items:center; justify-content:center; font-family:"IBM Plex Mono",monospace; font-size:9.5px; font-weight:700; color:#fff; border:2px solid var(--surface-sunken); position:relative; z-index:1;}
+.step-dot.pending{background:var(--surface-card); color:var(--text-muted); border-color:var(--axis);}
+.step-dot.in_progress{background:var(--series-blue);}
+.step-dot.completed{background:var(--status-good);}
+.step-dot.failed{background:var(--status-critical);}
+.step-dot.skipped{background:var(--surface-card); color:var(--text-muted); border-style:dashed;}
+.step-label{font-size:10px; color:var(--text-secondary); margin-top:5px; text-align:center; line-height:1.3;}
+.step-connector{position:absolute; top:13px; left:-34px; width:68px; height:2px; background:var(--axis); z-index:0;}
+.step:first-child .step-connector{display:none;}
+.step-retry{position:absolute; top:-8px; right:6px; background:var(--status-critical); color:#fff; font-size:9px; font-weight:700; border-radius:99px; padding:1px 5px; z-index:2;}
+
+/* heatmap */
+.heatmap-wrap{overflow-x:auto;}
+.heatmap-legend{display:flex; align-items:center; gap:5px; font-size:11px; color:var(--text-muted); margin-top:10px;}
+.heatmap-legend .sq{width:10px; height:10px; border-radius:2px;}
+
+footer.note{margin-top:30px; font-size:11.5px; color:var(--text-muted); line-height:1.7; border-top:1px solid var(--grid); padding-top:14px;}
+footer.note code{font-family:"IBM Plex Mono",monospace; background:var(--surface-sunken); padding:1px 5px; border-radius:4px;}
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap">
+</head>
+<body>
+
+<div class="app">
+ <div class="app-header">
+ <div>
+ <div class="app-title">Agent Observability</div>
+ <div class="app-sub">读取本地 <span class="mono">dashboard-data.json</span>(由 <span class="mono">build_dashboard_data.py</span> 从 metrics.ndjson / workflow-state.json 聚合而成)&middot; LoopForge 项目</div>
+ </div>
+ <div class="sample-badge" id="dataStatusBadge">加载中…</div>
+ </div>
+
+ <div class="filter-row">
+ <span class="filter-label">时间范围</span>
+ <button class="range-btn" data-range="7">近 7 天</button>
+ <button class="range-btn" data-range="30">近 30 天</button>
+ <button class="range-btn" data-range="90" aria-pressed="true">近 90 天</button>
+ </div>
+
+ <div class="kpis" id="kpiStrip"></div>
+
+ <div class="tabs" role="tablist">
+ <button class="tab-btn" role="tab" aria-selected="true" data-tab="overview">总览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="sessions">会话浏览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="skills">Skill · Rule</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="agents">Agent 协作</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="devflow">Devflow 运行</button>
+ </div>
+
+ <section class="tab-panel" id="panel-overview">
+ <div class="card">
+ <div class="card-head"><span class="card-title">建议关注</span><span class="card-note">按当前范围内的阈值规则实时算出,不是固定文案</span></div>
+ <div class="reminders" id="reminders"></div>
+ </div>
+
+ <div class="card">
+ <div class="card-head">
+ <span class="card-title">每日成本</span>
+ <div class="legend"><div class="legend-item"><span class="legend-line" style="background:var(--series-orange)"></span>cost_usd(按 <span class="mono">config/pricing.json</span> 估算)</div></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="costChart" viewBox="0 0 1080 220"></svg><div class="tooltip" id="costTooltip"></div></div>
+ </div>
+
+ <div class="grid-2 grid-2--cost">
+ <div class="card card--fill-h">
+ <div class="card-head">
+ <span class="card-title">Token 构成</span>
+ <div class="legend" id="tokenLegend"></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="tokenChart" viewBox="0 0 560 270"></svg><div class="tooltip" id="tokenTooltip"></div></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">按模型的成本占比</span><span class="card-note">Top 4 + 其他</span></div>
+ <div class="chart-wrap"><svg class="chart" id="modelChart" viewBox="0 0 460 210"></svg><div class="tooltip" id="modelTooltip"></div></div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">数据表</span><span class="card-note">图表的完整数值备份</span></div>
+ <div class="table-scroll"><table id="dailyTable"><thead><tr><th>日期</th><th>会话数</th><th>成本 (USD)</th><th>input</th><th>output</th><th>cache_read</th><th>工具失败</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-sessions" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近会话</span><span class="card-note">点击一行展开该会话按 turn 的工具调用时间线</span></div>
+ <div class="table-scroll"><table id="sessionTable">
+ <thead><tr><th>Session</th><th>日期</th><th>Agent</th><th>Turns</th><th>工具调用</th><th>Tokens</th><th>成本</th><th>时长</th><th>状态</th></tr></thead>
+ <tbody></tbody>
+ </table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-skills" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 触发热力图</span><span class="card-note">按天统计 <span class="mono">scanner.py</span> 命中的 skill 次数</span></div>
+ <div class="heatmap-wrap"><svg class="chart" id="heatmap" viewBox="0 0 900 118"></svg><div class="tooltip" id="heatmapTooltip"></div></div>
+ <div class="heatmap-legend">少<span class="sq" style="background:var(--seq-100)"></span><span class="sq" style="background:var(--seq-200)"></span><span class="sq" style="background:var(--seq-350)"></span><span class="sq" style="background:var(--seq-450)"></span><span class="sq" style="background:var(--seq-600)"></span>多</div>
+ </div>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 使用排行</span><span class="card-note">按范围内触发次数</span></div>
+ <div class="bar-list" id="skillBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">从未命中的 Skill / Rule</span><span class="card-note">来自 <span class="mono">unmatched_rule_diagnostics_for_call</span> 的未命中原因</span></div>
+ <div class="unused-list" id="unusedList"></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-agents" hidden>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Main → 子 Agent 派发次数</span><span class="card-note">来自 <span class="mono">.state.json</span> 的 agent_history</span></div>
+ <div class="bar-list" id="dispatchBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">工具失败面板</span><span class="card-note">tool_details.raw_response.is_error</span></div>
+ <div class="table-scroll"><table id="failTable"><thead><tr><th>工具</th><th>错误码</th><th>次数</th><th>最近一次</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-devflow" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Auto-Dispatch 健康度</span><span class="card-note">来自 <span class="mono">hooks/logs/auto-dispatch.log</span> 的派发决策统计</span></div>
+ <div class="health-row">
+ <div class="health-stat"><span class="v tab-nums" id="hDispatch">–</span><span class="l">auto_dispatch(零 token 直达)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallback">–</span><span class="l">fallback_to_main(唤醒 main)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallbackRate">–</span><span class="l">fallback 率</span></div>
+ <div class="health-bar">
+ <div class="health-bar-track" id="hBar"></div>
+ <div class="health-legend">
+ <span><span class="legend-swatch" style="background:var(--status-good);display:inline-block"></span> auto_dispatch</span>
+ <span><span class="legend-swatch" style="background:var(--status-warning);display:inline-block"></span> fallback_to_main</span>
+ <span><span class="legend-swatch" style="background:var(--text-muted);display:inline-block"></span> passthrough(*_failed 等本就该回 main)</span>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近 Devflow 运行</span><span class="card-note">按 task_slug 分组,串起 main + 最多 7 个 team member 的跨 session 归因</span></div>
+ <div id="devflowRuns"></div>
+ </div>
+ </section>
+
+ <footer class="note">
+ 数据来源:<code>python3 ../build_dashboard_data.py --project-root &lt;devflow 项目根目录&gt;</code> 会读取该项目下
+ <code>.codebuddy/skills/agent-observability/logs/metrics.ndjson</code>、<code>.state.json</code>、
+ <code>artifacts/*/workflow-state.json</code>(Classic/Portable 两种 schema 自动识别)与
+ <code>.codebuddy/hooks/logs/auto-dispatch.log</code>,聚合成同目录下的 <code>dashboard-data.json</code>。
+ 这个页面只读那份快照,不直接碰任何日志/状态文件——重新生成快照后刷新页面即可看到最新数据。
+ 全部处理在本机完成,不发往任何外部服务。
+ </footer>
+</div>
+
+<script>
+(function(){
+ "use strict";
+
+ var css = getComputedStyle(document.documentElement);
+ function tok(name){ return css.getPropertyValue(name).trim(); }
+
+ /* ---------- state populated by loadData() from ./dashboard-data.json (real data, no mock) ---------- */
+ var daily = [], sessions = [], dispatch = [], failures = [];
+ var SKILLS = [], NEVER_USED = [], modelCosts = [], unpricedModels = [];
+ var devflowRuns = [], autoDispatchStats = {auto_dispatch:0, fallback_to_main:0, passthrough:0};
+ var currentRange = 90;
+
+ function sliced(){ return daily.slice(daily.length-currentRange); }
+ function fmtUSD(v){ return "$"+v.toLocaleString(undefined,{minimumFractionDigits:2,maximumFractionDigits:2}); }
+ function fmtCompact(v){
+ if(v>=1e6) return (v/1e6).toFixed(1)+"M";
+ if(v>=1e3) return (v/1e3).toFixed(1)+"K";
+ return String(v);
+ }
+ function fmtDur(sec){
+ var m = Math.floor(sec/60), s = sec%60;
+ if(m>=60){ var h=Math.floor(m/60); m=m%60; return h+"h "+m+"m"; }
+ return m+"m "+s+"s";
+ }
+ function fmtDate(iso){ var p = iso.split("-"); return p[1]+"/"+p[2]; }
+
+ /* ================= KPI strip ================= */
+ function renderKPIs(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalTokens = d.reduce(function(a,x){return a+x.input+x.output;},0);
+ var totalSessions = d.reduce(function(a,x){return a+x.sessionCount;},0);
+ var totalCalls = d.reduce(function(a,x){return a+x.toolCalls;},0);
+ var totalFail = d.reduce(function(a,x){return a+x.failures;},0);
+ var failRate = totalCalls ? (totalFail/totalCalls*100) : 0;
+ var avgDur = sessions.length ? sessions.reduce(function(a,x){return a+x.duration;},0)/sessions.length : 0;
+
+ var items = [
+ {label:"会话数", value:totalSessions.toLocaleString(), delta:null},
+ {label:"累计成本", value:fmtUSD(totalCost), delta:null},
+ {label:"总 Token", value:fmtCompact(totalTokens), delta:null},
+ {label:"平均会话时长", value:fmtDur(Math.round(avgDur)), delta:null},
+ {label:"工具失败率", value:failRate.toFixed(1)+"%", delta:failRate>3?"up":"down"}
+ ];
+ var el = document.getElementById("kpiStrip");
+ el.innerHTML = "";
+ items.forEach(function(it){
+ var deltaHtml = "";
+ if(it.delta){
+ var cls = it.delta==="up" ? "up" : "down";
+ var arrow = it.delta==="up" ? "&#8593;" : "&#8595;";
+ deltaHtml = '<div class="kpi-delta '+cls+'">'+arrow+' vs 前一周期</div>';
+ }
+ var card = document.createElement("div");
+ card.className = "kpi";
+ var vEl = document.createElement("div"); vEl.className="kpi-value tab-nums";
+ var lEl = document.createElement("div"); lEl.className="kpi-label";
+ lEl.textContent = it.label; vEl.textContent = it.value;
+ card.appendChild(lEl); card.appendChild(vEl);
+ if(deltaHtml){ var dWrap=document.createElement("div"); dWrap.innerHTML=deltaHtml; card.appendChild(dWrap.firstChild); }
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= Reminders ================= */
+ /* 模型名来自日志(模型名是外部输入),插入 innerHTML 前必须转义。 */
+ function esc(s){
+ return String(s==null?"":s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;");
+ }
+
+ function renderReminders(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalInput = d.reduce(function(a,x){return a+x.input;},0);
+ var totalCache = d.reduce(function(a,x){return a+x.cache;},0);
+ var cacheRate = totalInput ? (totalCache/totalInput*100) : 0;
+ var budget = 40;
+ var el = document.getElementById("reminders");
+ el.innerHTML = "";
+ var items = [];
+ items.push({
+ level: totalCost > budget ? "crit" : (totalCost > budget*0.75 ? "warn" : "good"),
+ label: "成本预算",
+ text: "近 "+currentRange+" 天累计花费 <b>"+fmtUSD(totalCost)+"</b>,预算阈值 "+fmtUSD(budget)+"("+(totalCost>budget?"已超出":(Math.round(totalCost/budget*100)+"% 已用"))+")。"
+ });
+ items.push({
+ level: cacheRate < 30 ? "warn" : "good",
+ label: "Prompt Cache 命中",
+ text: "cache_read 占 input 的 <b>"+cacheRate.toFixed(0)+"%</b>"+(cacheRate<30 ? ",偏低,可能是 system prompt 频繁变化导致缓存失效,白花了 input 成本。" : ",处于正常区间。")
+ });
+ var unusedCount = NEVER_USED.length;
+ items.push({
+ level: unusedCount>0 ? "warn" : "good",
+ label: "Skill 维护",
+ text: unusedCount>0 ? ("有 <b>"+unusedCount+"</b> 个 skill/rule 在范围内从未被命中,建议检查 description 或 globs。") : "所有已扫描的 skill/rule 近期均被命中过。"
+ });
+ /* 第 4 条:模型定价。unpricedModels 由 build_dashboard_data.py 聚合,
+ 只列"完全没命中价格表"的模型(模糊命中的不算,见 emitter.is_unpriced)。 */
+ var unpricedCount = (unpricedModels||[]).length;
+ var unpricedEvents = (unpricedModels||[]).reduce(function(a,x){return a+(x.usageEvents||0);},0);
+ var unpricedNames = (unpricedModels||[]).slice(0,3).map(function(x){return esc(x.name);}).join("、");
+ items.push({
+ level: unpricedCount>0 ? "warn" : "good",
+ label: "模型定价",
+ text: unpricedCount>0
+ ? ("有 <b>"+unpricedCount+"</b> 个模型未命中价格表(<b>"+unpricedEvents+"</b> 条 usage 事件缺少成本):"
+ +unpricedNames+(unpricedCount>3 ? " 等 "+unpricedCount+" 个" : "")
+ +"。可写入 <code>.codebuddy/agent-observability/pricing.overrides.json</code>,"
+ +"或用 <code>AOBS_PRICING_OVERRIDES_PATH</code> 指定覆盖文件补充单价;"
+ +"补充后只影响之后的新事件,不回溯已落盘的历史成本。")
+ : "所有出现的模型都已命中价格表,成本估算完整。"
+ });
+ items.forEach(function(it){
+ var card = document.createElement("div");
+ card.className = "reminder "+it.level;
+ var icon = it.level==="crit" ? "!" : (it.level==="warn" ? "!" : "✓");
+ card.innerHTML =
+ '<div class="reminder-icon">'+icon+'</div>'+
+ '<div><div class="reminder-label">'+(it.level==="crit"?"critical":it.level==="warn"?"warning":"good")+'</div>'+
+ '<div style="font-size:12.5px;font-weight:600;margin-top:2px;">'+it.label+'</div>'+
+ '<div class="reminder-text">'+it.text+'</div></div>';
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= tooltip helper ================= */
+ function positionTooltip(tipEl, wrapEl, x, y){
+ var wrapRect = wrapEl.getBoundingClientRect();
+ var left = x, top = y - 14;
+ var maxLeft = wrapRect.width - 150;
+ if(left > maxLeft) left = maxLeft;
+ if(left < 4) left = 4;
+ tipEl.style.left = left + "px";
+ tipEl.style.top = Math.max(0, top - tipEl.offsetHeight) + "px";
+ }
+
+ var SVGNS = "http://www.w3.org/2000/svg";
+ function el(tag, attrs){
+ var e = document.createElementNS(SVGNS, tag);
+ for(var k in attrs){ e.setAttribute(k, attrs[k]); }
+ return e;
+ }
+
+ /* SVG <text> 没有 CSS text-overflow:ellipsis 那一套,长文本(比如自定义模型名)
+ 会原样溢出、被同一行后面画的柱子盖住。textEl 必须已经挂到 DOM 上(在真实渲染的
+ svg 里)才能拿到准确的 getComputedTextLength()。 */
+ function truncateSvgText(textEl, fullText, maxWidth){
+ textEl.textContent = fullText;
+ if(maxWidth<=0 || textEl.getComputedTextLength()<=maxWidth) return;
+ var lo=0, hi=fullText.length;
+ while(lo<hi){
+ var mid=(lo+hi+1)>>1;
+ textEl.textContent = fullText.slice(0,mid)+"…";
+ if(textEl.getComputedTextLength()<=maxWidth) lo=mid; else hi=mid-1;
+ }
+ textEl.textContent = lo>0 ? fullText.slice(0,lo)+"…" : "…";
+ }
+
+ /* ================= Cost trend (line + area, crosshair tooltip) ================= */
+ function renderCostChart(){
+ var svg = document.getElementById("costChart");
+ svg.innerHTML = "";
+ var W=1080,H=220, padL=44, padR=12, padT=14, padB=26;
+ var d = sliced();
+ if(d.length===0){
+ var empty0 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty0.textContent = "暂无数据 · 等真实会话跑起来后重新生成 dashboard-data.json";
+ svg.appendChild(empty0);
+ return;
+ }
+ var maxCost = Math.max.apply(null, d.map(function(x){return x.cost;})) || 1;
+ var niceMax = Math.ceil(maxCost*1.15/5)*5 || 5;
+ var plotW = W-padL-padR, plotH = H-padT-padB;
+ function xAt(i){ return padL + (d.length<=1?0:(i/(d.length-1))*plotW); }
+ function yAt(v){ return padT + plotH - (v/niceMax)*plotH; }
+
+ // gridlines + y labels
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g;
+ var y = yAt(v);
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"});
+ t.textContent = "$"+v.toFixed(0); svg.appendChild(t);
+ }
+ // x labels (sparse)
+ var step = Math.max(1, Math.round(d.length/7));
+ d.forEach(function(pt,i){
+ if(i%step===0 || i===d.length-1){
+ var t = el("text",{class:"axis-text",x:xAt(i),y:H-6,"text-anchor":"middle"});
+ t.textContent = fmtDate(pt.iso); svg.appendChild(t);
+ }
+ });
+
+ // area path
+ var top = d.map(function(pt,i){ return xAt(i)+","+yAt(pt.cost); }).join(" L ");
+ var areaD = "M "+xAt(0)+","+yAt(0)+" L "+top+" L "+xAt(d.length-1)+","+yAt(0)+" Z";
+ svg.appendChild(el("path",{d:areaD, fill:tok("--series-orange"), opacity:0.10, stroke:"none"}));
+ var lineD = "M "+top;
+ svg.appendChild(el("path",{d:lineD, fill:"none", stroke:tok("--series-orange"), "stroke-width":2, "stroke-linejoin":"round","stroke-linecap":"round"}));
+
+ // emphasized endpoint
+ var lastI = d.length-1;
+ svg.appendChild(el("circle",{cx:xAt(lastI), cy:yAt(d[lastI].cost), r:4.5, fill:tok("--series-orange"), stroke:tok("--surface-card"), "stroke-width":2}));
+ var endLabel = el("text",{class:"axis-text",x:xAt(lastI)-4,y:yAt(d[lastI].cost)-10,"text-anchor":"end", fill:tok("--text-primary")});
+ endLabel.setAttribute("font-weight","600");
+ endLabel.textContent = "$"+d[lastI].cost.toFixed(2);
+ svg.appendChild(endLabel);
+
+ // crosshair + hover
+ var crosshair = el("line",{class:"crosshair",x1:0,x2:0,y1:padT,y2:H-padB, opacity:0});
+ svg.appendChild(crosshair);
+ var hitRect = el("rect",{class:"hit-target",x:padL,y:padT,width:plotW,height:plotH});
+ svg.appendChild(hitRect);
+ var wrap = svg.parentNode, tip = document.getElementById("costTooltip");
+ function onMove(evt){
+ var rect = svg.getBoundingClientRect();
+ var mx = (evt.clientX-rect.left) * (W/rect.width);
+ var idx = Math.round(((mx-padL)/plotW)*(d.length-1));
+ idx = Math.max(0, Math.min(d.length-1, idx));
+ var px = xAt(idx);
+ crosshair.setAttribute("x1",px); crosshair.setAttribute("x2",px); crosshair.setAttribute("opacity",1);
+ var pt = d[idx];
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+tok("--series-orange")+'"></span>成本</span><span class="tooltip-val">'+fmtUSD(pt.cost)+'</span></div><div class="tooltip-row"><span class="tooltip-key">会话数</span><span class="tooltip-val">'+pt.sessionCount+'</span></div>';
+ tip.classList.add("show");
+ var screenX = px/(W/rect.width), screenY = yAt(pt.cost)/(H/rect.height);
+ positionTooltip(tip, wrap, screenX, screenY);
+ }
+ hitRect.addEventListener("pointermove", onMove);
+ hitRect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); crosshair.setAttribute("opacity",0); });
+ }
+
+ /* ================= Token composition (stacked bars) ================= */
+ function renderTokenChart(){
+ var svg = document.getElementById("tokenChart"); svg.innerHTML="";
+ var legend = document.getElementById("tokenLegend");
+ var series = [
+ {key:"input", label:"input", color:tok("--series-blue")},
+ {key:"output", label:"output", color:tok("--series-aqua")},
+ {key:"cache", label:"cache_read", color:tok("--series-yellow")}
+ ];
+ legend.innerHTML = series.map(function(s){ return '<div class="legend-item"><span class="legend-swatch" style="background:'+s.color+'"></span>'+s.label+'</div>'; }).join("");
+
+ // 按模型的成本占比条数不固定(1~5 行),两张图挨着放的时候卡片高矮天然不一样。
+ // .card--fill-h 让这张图的 .chart-wrap 跟着 grid 拉伸出来的实际卡片高度走(CSS),
+ // 这里直接读它撑开后的真实像素尺寸当 viewBox,而不是猜一个写死的高宽比——
+ // renderModelChart() 必须先跑完把内容插进 DOM,这个测量才反映得出最终高度
+ // (见 renderAll() / 时间范围切换 / resize 三处调用顺序)。560x270 只是量不到时
+ // (比如面板还没显示)的兜底默认值。
+ var wrapRect = svg.parentNode.getBoundingClientRect();
+ var W = Math.round(wrapRect.width) || 560;
+ var H = Math.max(160, Math.round(wrapRect.height) || 270);
+ svg.setAttribute("viewBox","0 0 "+W+" "+H);
+ var padL=46,padR=10,padT=10,padB=24;
+ var d = sliced().slice(-30); // cap bars for legibility
+ if(d.length===0){
+ var empty1 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty1.textContent = "暂无数据";
+ svg.appendChild(empty1);
+ return;
+ }
+ var maxTotal = Math.max.apply(null, d.map(function(x){return x.input+x.output+x.cache;})) || 1;
+ var niceMax = Math.ceil(maxTotal*1.1/10000)*10000 || 10000;
+ var plotW=W-padL-padR, plotH=H-padT-padB;
+ var bw = Math.min(28, plotW/d.length*0.62);
+ var gap = plotW/d.length;
+
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g, y = padT+plotH-(v/niceMax)*plotH;
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"}); t.textContent=fmtCompact(v); svg.appendChild(t);
+ }
+ var wrap = svg.parentNode, tip = document.getElementById("tokenTooltip");
+ d.forEach(function(pt,i){
+ var x = padL + i*gap + (gap-bw)/2;
+ var vals = [pt.input, pt.output, pt.cache];
+ var yCursor = padT+plotH;
+ var bar = el("g",{});
+ vals.forEach(function(v,si){
+ var hgt = (v/niceMax)*plotH;
+ if(hgt<=0) return;
+ var yTop = yCursor - hgt;
+ bar.appendChild(el("rect",{x:x,y:yTop+1,width:bw,height:Math.max(0,hgt-2),rx:2,fill:series[si].color}));
+ yCursor = yTop;
+ });
+ var hit = el("rect",{class:"hit-target",x:x-2,y:padT,width:bw+4,height:plotH});
+ svg.appendChild(bar); svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(pt,x){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[0].color+'"></span>input</span><span class="tooltip-val">'+pt.input.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[1].color+'"></span>output</span><span class="tooltip-val">'+pt.output.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[2].color+'"></span>cache_read</span><span class="tooltip-val">'+pt.cache.toLocaleString()+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(W/rect.width), padT);
+ };}(pt,x));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ var t2 = el("text",{class:"axis-text",x:padL,y:H-6}); t2.textContent = fmtDate(d[0].iso); svg.appendChild(t2);
+ var t3 = el("text",{class:"axis-text",x:W-padR,y:H-6,"text-anchor":"end"}); t3.textContent = fmtDate(d[d.length-1].iso); svg.appendChild(t3);
+ }
+
+ /* ================= Model cost breakdown (horizontal bars) ================= */
+ function renderModelChart(){
+ var svg = document.getElementById("modelChart"); svg.innerHTML="";
+ // modelCosts 是索引器按 usage 事件的真实 model/cost_usd 汇总出来的(全量,不随时间范围筛选——
+ // 按天切分模型成本需要索引器额外输出 daily×model 的交叉表,这版先给全量占比)。
+ var rows = modelCosts.slice().sort(function(a,b){return b.cost-a.cost;});
+ var top = rows.slice(0,4);
+ var restCost = rows.slice(4).reduce(function(a,x){return a+x.cost;},0);
+ if(restCost>0) top.push({name:"其他", cost:restCost, other:true});
+ if(top.length===0){
+ var empty = el("text",{class:"axis-text",x:12,y:30,fill:tok("--text-muted")});
+ empty.textContent = "暂无数据";
+ svg.appendChild(empty);
+ return;
+ }
+
+ var W=460,H=210,padL=12,padR=54,padT=8,padB=8;
+ var rowH = (H-padT-padB)/top.length;
+ var maxV = Math.max.apply(null, top.map(function(x){return x.cost;})) || 1;
+ var colors = [tok("--series-blue"),tok("--series-orange"),tok("--series-aqua"),tok("--series-yellow"),tok("--axis")];
+ var wrap = svg.parentNode, tip = document.getElementById("modelTooltip");
+
+ // 第一遍:把每行的完整模型名挂到 DOM 上量出真实渲染宽度(getComputedTextLength
+ // 要素材已经在 DOM 里才准),取最长的一个决定标签列该留多宽——而不是像之前那样
+ // 写死 84px、名字一长就被柱子盖住。上限按图表总宽的 55% 封顶,避免某一个特别长
+ // 的名字把柱子全挤没了;封顶之后仍放不下的极端情况,靠 truncateSvgText 兜底截断。
+ var geoms = top.map(function(row,i){
+ var y = padT + i*rowH;
+ var barH = Math.min(22, rowH*0.55);
+ var barY = y + (rowH-barH)/2;
+ var label = el("text",{class:"axis-text",x:padL,y:barY+barH/2+3, fill:tok("--text-secondary")});
+ label.setAttribute("font-size","11");
+ label.textContent = row.name;
+ svg.appendChild(label);
+ return {row:row, i:i, y:y, barH:barH, barY:barY, label:label};
+ });
+ var maxLabelW = Math.max.apply(null, geoms.map(function(g){return g.label.getComputedTextLength();}));
+ var labelColW = Math.min(Math.max(maxLabelW+10, 70), W*0.55);
+ var barX = padL+labelColW;
+ var maxW = W-padL-padR-labelColW;
+
+ geoms.forEach(function(g){
+ var row=g.row, i=g.i, y=g.y, barH=g.barH, barY=g.barY, label=g.label;
+ truncateSvgText(label, row.name, labelColW-6);
+ label.appendChild(el("title",{})).textContent = row.name;
+ var w = Math.max(2,(row.cost/maxV)*maxW);
+ var bar = el("rect",{x:barX,y:barY,width:w,height:barH,rx:4,fill:row.other?tok("--axis"):colors[i]});
+ svg.appendChild(bar);
+ var val = el("text",{class:"axis-text",x:barX+w+6,y:barY+barH/2+3, fill:tok("--text-primary")});
+ val.setAttribute("font-weight","600"); val.textContent = fmtUSD(row.cost);
+ svg.appendChild(val);
+ var hit = el("rect",{class:"hit-target",x:0,y:y,width:W,height:rowH});
+ svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(row,y){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-row"><span class="tooltip-key">'+row.name+'</span><span class="tooltip-val">'+fmtUSD(row.cost)+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, (W-40)/(W/rect.width), y/(H/rect.height));
+ };}(row,y));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ }
+
+ /* ================= Daily data table (accessibility fallback) ================= */
+ function renderDailyTable(){
+ var tbody = document.querySelector("#dailyTable tbody");
+ tbody.innerHTML = "";
+ sliced().slice().reverse().forEach(function(pt){
+ var tr = document.createElement("tr");
+ [pt.iso, pt.sessionCount, fmtUSD(pt.cost), pt.input.toLocaleString(), pt.output.toLocaleString(), pt.cache.toLocaleString(), pt.failures]
+ .forEach(function(v,i){
+ var td = document.createElement("td");
+ td.textContent = v; td.classList.add("tab-nums");
+ if(i===0) td.classList.add("strong");
+ tr.appendChild(td);
+ });
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= Sessions tab ================= */
+ function renderSessions(){
+ var tbody = document.querySelector("#sessionTable tbody");
+ tbody.innerHTML = "";
+ if(sessions.length===0){
+ tbody.innerHTML = '<tr><td colspan="9" style="color:var(--text-muted);">暂无会话记录</td></tr>';
+ return;
+ }
+ sessions.forEach(function(s){
+ var tr = document.createElement("tr");
+ tr.className = "data-row";
+ var statusChip = s.status==="error"
+ ? '<span class="chip crit"><span class="chip-dot"></span>有失败</span>'
+ : '<span class="chip good"><span class="chip-dot"></span>正常</span>';
+ tr.innerHTML =
+ '<td class="strong mono">'+s.id+'</td>'+
+ '<td class="tab-nums">'+s.date+'</td>'+
+ '<td>'+s.agent+'</td>'+
+ '<td class="tab-nums">'+s.turns+'</td>'+
+ '<td class="tab-nums">'+s.toolCalls+'</td>'+
+ '<td class="tab-nums">'+s.tokens.toLocaleString()+'</td>'+
+ '<td class="tab-nums">'+fmtUSD(s.cost)+'</td>'+
+ '<td class="tab-nums">'+fmtDur(s.duration)+'</td>'+
+ '<td>'+statusChip+'</td>';
+ tbody.appendChild(tr);
+
+ var expandTr = document.createElement("tr");
+ expandTr.className = "expand-row";
+ expandTr.hidden = true;
+ var td = document.createElement("td");
+ td.colSpan = 9;
+ // 把同一 turn 里连续且工具名相同的调用合并成一段(累加耗时、记次数),
+ // 这样"循环调用同一个工具 N 次"不会被渲染成 N 个几乎看不清的窄条。
+ function mergeTurnEvents(events){
+ var merged = [];
+ events.forEach(function(ev){
+ var last = merged[merged.length-1];
+ var agent = ev.agent || "main";
+ // 只合并连续且 agent 也相同的调用——否则 main 调 Bash、转派给
+ // solo-developer 又调一次 Bash,会被错误地合并成一段"Bash ×2",
+ // 看不出中间其实发生了一次 agent 切换。
+ if(ev.kind==="tool" && last && last.kind==="tool" && last.tool===ev.tool && last.agent===agent){
+ last.ms += ev.ms; last.count += 1; last.err = last.err || ev.err;
+ } else if(ev.kind==="tool"){
+ merged.push({kind:"tool", tool:ev.tool, ms:ev.ms, count:1, err:ev.err, agent:agent});
+ } else {
+ merged.push({kind:"usage", tokens:ev.tokens, agent:agent});
+ }
+ });
+ return merged;
+ }
+ var timelineHtml = s.timeline.map(function(turn){
+ var toolRaw = turn.events.filter(function(e){ return e.kind==="tool"; }).length;
+ var segsData = mergeTurnEvents(turn.events);
+ var toolMerged = segsData.filter(function(e){ return e.kind==="tool"; }).length;
+ // 段宽是真实像素(不是 flex-grow 权重),行外层带 overflow-x:auto——
+ // 调用数再多,也只是这一行变宽可横向滚动,不会撑破卡片或挤压其它内容。
+ var segs = segsData.map(function(seg){
+ var isSubagent = seg.agent && seg.agent !== "main";
+ if(seg.kind==="tool"){
+ var cls = (seg.err ? "err" : (seg.count>1 ? "merged" : "ok")) + (isSubagent ? " subagent" : "");
+ var label = seg.count>1 ? (seg.tool+' ×'+seg.count) : seg.tool;
+ var titleText = seg.tool + (seg.count>1 ? (' × '+seg.count+' 次,合计 '+seg.ms+'ms') : (' · '+seg.ms+'ms')) + ' · agent='+(seg.agent||"main");
+ // 段宽取"按耗时算出的宽度"和"能放下标签文字的最小宽度"两者较大值——
+ // 本地工具调用常常只有几百 ms,纯按 ms*0.05 算出来的宽度几乎总是不到
+ // 文字下限,标签会被整段隐藏,只能靠悬浮 title 才看得到工具名。
+ var labelW = Math.min(140, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(140, seg.ms*0.05));
+ return '<div class="timeline-seg '+cls+'" style="width:'+w+'px" title="'+titleText+'">'+label+'</div>';
+ }
+ var label = seg.tokens+' tok';
+ var labelW = Math.min(130, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(130, seg.tokens*0.008));
+ var usageCls = "usage"+(isSubagent ? " subagent" : "");
+ return '<div class="timeline-seg '+usageCls+'" style="width:'+w+'px" title="usage · '+seg.tokens+' tok · agent='+(seg.agent||"main")+'">'+label+'</div>';
+ }).join("");
+ var countNote = (toolMerged!==toolRaw)
+ ? ('共 '+toolRaw+' 次工具调用 · 合并连续重复为 '+toolMerged+' 段')
+ : (toolRaw+' 次工具调用');
+ return '<div class="timeline-turn"><div class="timeline-turn-head"><span class="timeline-turn-label">turn '+turn.turn+' &middot; agent='+turn.agent+'</span><span class="timeline-turn-count">'+countNote+'</span></div><div class="timeline-scroll"><div class="timeline-track">'+segs+'</div></div></div>';
+ }).join("");
+ td.innerHTML = '<div class="timeline">'+timelineHtml+'</div>';
+ expandTr.appendChild(td);
+ tbody.appendChild(expandTr);
+
+ tr.addEventListener("click", function(expandTr){ return function(){ expandTr.hidden = !expandTr.hidden; }; }(expandTr));
+ });
+ }
+
+ /* ================= Skills tab ================= */
+ function renderHeatmap(){
+ var svg = document.getElementById("heatmap"); svg.innerHTML="";
+ var d = daily; // full 90d regardless of range filter, like a contribution calendar
+ var cell=11, gap=3, padL=26, padT=14;
+ var weeks = Math.ceil(d.length/7);
+ var maxHit = Math.max.apply(null, d.map(function(x){
+ return Object.keys(x.skillHits).reduce(function(a,k){return a+x.skillHits[k];},0);
+ })) || 1;
+ var ramp = ["--seq-100","--seq-200","--seq-350","--seq-450","--seq-600"];
+ var dow = ["一","三","五"];
+ [1,3,5].forEach(function(row,ix){
+ var t = el("text",{class:"axis-text",x:padL-8,y:padT+row*(cell+gap)+9,"text-anchor":"end"});
+ t.textContent = dow[ix]; svg.appendChild(t);
+ });
+ var wrap = svg.parentNode, tip = document.getElementById("heatmapTooltip");
+ for(var i=0;i<d.length;i++){
+ var pt = d[i];
+ var jsDow = pt.date.getDay(); // 0=Sun
+ var col = Math.floor(i/7), row = jsDow;
+ var total = Object.keys(pt.skillHits).reduce(function(a,k){return a+pt.skillHits[k];},0);
+ var level = total===0 ? -1 : Math.min(4, Math.floor((total/maxHit)*5));
+ var color = level<0 ? tok("--grid") : tok("--"+ramp[level].slice(2));
+ var x = padL + col*(cell+gap), y = padT + row*(cell+gap);
+ var rect = el("rect",{x:x,y:y,width:cell,height:cell,rx:2,fill:color});
+ svg.appendChild(rect);
+ rect.addEventListener("pointermove", function(pt,total,x,y){ return function(evt){
+ var rect2 = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key">skill 命中</span><span class="tooltip-val">'+total+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(900/rect2.width), y/(118/rect2.height));
+ };}(pt,total,x,y));
+ rect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ }
+ }
+
+ function renderSkillBars(){
+ var el2 = document.getElementById("skillBars");
+ var totals = {};
+ SKILLS.forEach(function(s){ totals[s]=0; });
+ daily.forEach(function(pt){ SKILLS.forEach(function(s){ totals[s]+=pt.skillHits[s]; }); });
+ var rows = SKILLS.map(function(s){ return {name:s, count:totals[s]}; }).sort(function(a,b){return b.count-a.count;});
+ var maxV = rows[0] ? rows[0].count : 1;
+ el2.innerHTML = "";
+ rows.forEach(function(r,i){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">'+r.name+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-blue")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderUnused(){
+ var el2 = document.getElementById("unusedList");
+ el2.innerHTML = "";
+ NEVER_USED.forEach(function(u){
+ var div = document.createElement("div");
+ div.className = "unused-item";
+ div.innerHTML = '<div><div class="unused-name">'+u.name+'</div><div style="font-size:11.5px;color:var(--text-muted);margin-top:2px;">'+u.detail+'</div></div><span class="reason-chip">'+u.reason+'</span>';
+ el2.appendChild(div);
+ });
+ }
+
+ /* ================= Agents tab ================= */
+ function renderDispatch(){
+ var el2 = document.getElementById("dispatchBars");
+ el2.innerHTML = "";
+ if(dispatch.length===0){
+ el2.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无派发记录</div>';
+ return;
+ }
+ var maxV = dispatch[0].count;
+ dispatch.forEach(function(r){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">main → '+r.agent+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-aqua")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderFailTable(){
+ var tbody = document.querySelector("#failTable tbody");
+ tbody.innerHTML = "";
+ failures.forEach(function(f){
+ var tr = document.createElement("tr");
+ tr.innerHTML = '<td class="strong">'+f.tool+'</td><td class="mono">'+f.code+'</td><td class="tab-nums">'+f.count+'</td><td class="tab-nums">'+f.last+'</td>';
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= devflow ================= */
+ function renderDevflowHealth(){
+ var d = autoDispatchStats;
+ var total = d.auto_dispatch + d.fallback_to_main + d.passthrough;
+ document.getElementById("hDispatch").textContent = d.auto_dispatch.toLocaleString();
+ document.getElementById("hFallback").textContent = d.fallback_to_main.toLocaleString();
+ var rate = total ? (d.fallback_to_main/total*100) : 0;
+ document.getElementById("hFallbackRate").textContent = rate.toFixed(1)+"%";
+ var bar = document.getElementById("hBar");
+ bar.innerHTML = "";
+ [["auto_dispatch",tok("--status-good")],["fallback_to_main",tok("--status-warning")],["passthrough",tok("--text-muted")]].forEach(function(pair){
+ var seg = document.createElement("div");
+ seg.className = "health-bar-seg";
+ seg.style.width = (total? d[pair[0]]/total*100 : 0)+"%";
+ seg.style.background = pair[1];
+ seg.title = pair[0]+": "+d[pair[0]];
+ bar.appendChild(seg);
+ });
+ }
+
+ function renderDevflowRuns(){
+ var wrap = document.getElementById("devflowRuns");
+ wrap.innerHTML = "";
+ if(devflowRuns.length===0){
+ wrap.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无 devflow 运行记录(没有 artifacts/*/workflow-state.json,或者项目还没跑过 /start-devflow)</div>';
+ return;
+ }
+ devflowRuns.forEach(function(run){
+ var card = document.createElement("div");
+ card.className = "run-card";
+ var statusChip = run.overall==="completed"
+ ? '<span class="run-status-chip" style="background:var(--status-good-bg);color:var(--status-good)"><span class="chip-dot"></span>已完成</span>'
+ : run.overall==="running"
+ ? '<span class="run-status-chip" style="background:var(--series-blue-wash);color:var(--series-blue)"><span class="chip-dot"></span>进行中</span>'
+ : '<span class="run-status-chip" style="background:var(--status-critical-bg);color:var(--status-critical)"><span class="chip-dot"></span>已暂停 · 待人工介入</span>';
+ var head = document.createElement("div");
+ head.className = "run-head";
+ head.innerHTML =
+ '<div class="run-title">'+run.slug+'</div>'+
+ '<div class="run-meta"><span class="size-chip">'+run.size+'</span>'+statusChip+
+ '<span class="tab-nums">'+fmtUSD(run.cost)+'</span><span class="tab-nums" title="按真实起止跨度(最早 started_at 到最晚 completed_at)计算;阶段之间有重叠时,会小于各阶段耗时直接相加">'+fmtDur(run.duration)+'</span></div>';
+ card.appendChild(head);
+
+ var stepper = document.createElement("div");
+ stepper.className = "stepper";
+ run.stages.forEach(function(s){
+ var step = document.createElement("div");
+ step.className = "step";
+ var retryBadge = s.retry_count>0 ? '<div class="step-retry">&#8635;'+s.retry_count+'</div>' : "";
+ var titleText = s.name+" · executor="+s.exec+(s.status!=="pending"?(" · "+fmtDur(s.duration)):"")+(s.retry_count>0?(" · retry_count="+s.retry_count):"");
+ step.innerHTML =
+ '<div class="step-connector"></div>'+
+ '<div class="step-dot '+s.status+'" title="'+titleText+'">'+s.label+retryBadge+'</div>'+
+ '<div class="step-label">'+s.name+'</div>';
+ stepper.appendChild(step);
+ });
+ card.appendChild(stepper);
+ wrap.appendChild(card);
+ });
+ }
+
+ /* ================= render all ================= */
+ function renderAll(){
+ renderKPIs();
+ renderReminders();
+ renderCostChart();
+ renderModelChart();
+ renderTokenChart();
+ renderDailyTable();
+ renderSessions();
+ renderHeatmap();
+ renderSkillBars();
+ renderUnused();
+ renderDispatch();
+ renderFailTable();
+ renderDevflowHealth();
+ renderDevflowRuns();
+ }
+
+ /* ================= load real data from ./dashboard-data.json ================= */
+ function setBadge(text, tone){
+ var badge = document.getElementById("dataStatusBadge");
+ badge.textContent = text;
+ badge.style.color = tone==="good" ? tok("--status-good") : tone==="crit" ? tok("--status-critical") : tok("--status-warning");
+ badge.style.background = tone==="good" ? tok("--status-good-bg") : tone==="crit" ? tok("--status-critical-bg") : tok("--status-warning-bg");
+ }
+ function loadData(){
+ fetch("./dashboard-data.json", {cache:"no-store"})
+ .then(function(resp){
+ if(!resp.ok) throw new Error("HTTP "+resp.status);
+ return resp.json();
+ })
+ .then(function(data){
+ daily = (data.daily||[]).map(function(d){ d.date = new Date(d.iso+"T00:00:00"); return d; });
+ sessions = data.sessions||[];
+ dispatch = data.dispatch||[];
+ failures = data.failures||[];
+ SKILLS = (data.skills||[]).map(function(s){return s.name;});
+ NEVER_USED = data.neverUsed||[];
+ modelCosts = data.modelCosts||[];
+ unpricedModels = data.unpricedModels||[];
+ devflowRuns = data.devflowRuns||[];
+ autoDispatchStats = data.autoDispatchStats||{auto_dispatch:0, fallback_to_main:0, passthrough:0};
+
+ var total = (data.source && data.source.event_count) || 0;
+ if(total===0){
+ setBadge("还没有数据 · 见页脚生成说明", "warn");
+ } else {
+ var genAt = data.generated_at ? data.generated_at.replace("T"," ").replace("+00:00"," UTC") : "";
+ setBadge("真实数据 · "+total+" 条事件 · 生成于 "+genAt, "good");
+ }
+ renderAll();
+ })
+ .catch(function(err){
+ setBadge("加载 dashboard-data.json 失败", "crit");
+ var note = document.querySelector("footer.note");
+ if(note){
+ var warn = document.createElement("div");
+ warn.style.cssText = "margin-top:10px;color:"+tok("--status-critical")+";";
+ warn.textContent = "错误详情:" + err.message + "(先运行 build_dashboard_data.py 生成这份快照,再用本地 HTTP server 打开本页——直接双击用 file:// 打开会因为浏览器禁止本地 fetch 而失败)。";
+ note.appendChild(warn);
+ }
+ renderAll();
+ });
+ }
+ loadData();
+
+ /* ================= wiring: range buttons ================= */
+ document.querySelectorAll(".range-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".range-btn").forEach(function(b){ b.setAttribute("aria-pressed","false"); });
+ btn.setAttribute("aria-pressed","true");
+ currentRange = parseInt(btn.dataset.range,10);
+ renderKPIs(); renderReminders(); renderCostChart(); renderModelChart(); renderTokenChart(); renderDailyTable();
+ });
+ });
+
+ /* ================= wiring: tabs ================= */
+ var panels = {overview:"panel-overview", sessions:"panel-sessions", skills:"panel-skills", agents:"panel-agents", devflow:"panel-devflow"};
+ document.querySelectorAll(".tab-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".tab-btn").forEach(function(b){ b.setAttribute("aria-selected","false"); });
+ btn.setAttribute("aria-selected","true");
+ Object.keys(panels).forEach(function(k){ document.getElementById(panels[k]).hidden = (k!==btn.dataset.tab); });
+ });
+ });
+
+ window.addEventListener("resize", function(){
+ renderCostChart(); renderModelChart(); renderTokenChart(); renderHeatmap();
+ });
+})();
+</script>
+</body>
+</html>
diff --git a/.codebuddy/skills/agent-observability/scripts/main.py b/.codebuddy/skills/agent-observability/scripts/main.py
new file mode 100644
index 00000000..4ca24812
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/main.py
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""agent-observability 的 hook 入口。"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+if __package__ in (None, ""):
+ _SCRIPTS_DIR = Path(__file__).resolve().parent
+ if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+ from core.runtime import main as runtime_main # type: ignore
+else:
+ from .core.runtime import main as runtime_main
+
+
+def main() -> int:
+ return runtime_main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.codebuddy/skills/agent-observability/scripts/run_hook.sh b/.codebuddy/skills/agent-observability/scripts/run_hook.sh
new file mode 100755
index 00000000..d476810f
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/scripts/run_hook.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+PROJECT_DIR="${CODEBUDDY_PROJECT_DIR:-$(cd "$(dirname "$0")"/../../../.. && pwd -P)}"
+PYTHON_BIN="$PROJECT_DIR/.venv/bin/python"
+MAIN_PY="$PROJECT_DIR/.codebuddy/skills/agent-observability/scripts/main.py"
+
+# 只有当 .venv 里可用 zhiyanllm 时才优先使用该解释器;
+# 否则回退到已安装 zhiyanllm 的系统 python3。
+if [ -x "$PYTHON_BIN" ]; then
+ if "$PYTHON_BIN" -c "import zhiyanllm" 2>/dev/null; then
+ exec "$PYTHON_BIN" "$MAIN_PY" "$@"
+ fi
+fi
+
+exec python3 "$MAIN_PY" "$@"
diff --git a/.codebuddy/skills/agent-observability/templates/settings-hook.json b/.codebuddy/skills/agent-observability/templates/settings-hook.json
new file mode 100644
index 00000000..7646ee78
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/templates/settings-hook.json
@@ -0,0 +1,62 @@
+{
+ "_comment": "将本文件合并到 ~/.codebuddy/settings.json 或 <project>/.codebuddy/settings.json",
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh session-start",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh user-prompt-submit",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh pre",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh post",
+ "timeout": 30
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.codebuddy/skills/agent-observability/scripts/run_hook.sh stop",
+ "timeout": 30
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.codebuddy/skills/agent-observability/tests/fixtures/transcript.jsonl b/.codebuddy/skills/agent-observability/tests/fixtures/transcript.jsonl
new file mode 100644
index 00000000..a5ea47dd
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/fixtures/transcript.jsonl
@@ -0,0 +1,10 @@
+{"type":"system","subtype":"init","session_id":"demo-001","content":"<rules>\n<security_rules>do not exec</security_rules>\n</rules>\n<available_skills>\n<skill><name>pdf</name></skill>\n<skill><name>hermes-devflow</name></skill>\n</available_skills>"}
+{"type":"assistant","providerData":{"messageId":"msg-001"},"content":[{"type":"tool_use","name":"read_file","input":{"filePath":"README.md"}}],"usage":{"input_tokens":1820,"output_tokens":42,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"function_call_result","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"assistant","providerData":{"messageId":"msg-002"},"content":[{"type":"tool_use","name":"use_skill","input":{"command":"pdf"}}],"usage":{"input_tokens":2100,"output_tokens":58,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"assistant","providerData":{"messageId":"msg-003"},"content":"完成","usage":{"input_tokens":2240,"output_tokens":120,"cache_read_input_tokens":15300}}
diff --git a/.codebuddy/skills/agent-observability/tests/test_agent_identity.py b/.codebuddy/skills/agent-observability/tests/test_agent_identity.py
new file mode 100644
index 00000000..664cc1dd
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_agent_identity.py
@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core.agent_identity import AgentIdentityResolver # type: ignore
+from core import state as st # type: ignore
+
+
+class AgentIdentityResolverTests(unittest.TestCase):
+ def test_extract_identity_from_send_message_json(self):
+ resolver = AgentIdentityResolver()
+ data = {
+ "tool_name": "send_message",
+ "tool_input": {
+ "content": '{"from_role":"developer","next_target":{"role_name":"leader"}}'
+ },
+ }
+ current, dispatched = resolver.extract_identity(data)
+ self.assertEqual(current, "developer")
+ self.assertEqual(dispatched, "leader")
+
+ def test_track_returns_active_and_dispatched(self):
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s2"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "developer")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("current_agent"), "developer")
+ self.assertEqual(sess.get("dispatched", {}).get("developer"), 1)
+
+ def test_track_recognizes_agent_tool_subagent_type(self):
+ """Claude Code 的 Agent 工具用 subagent_type(不是 CodeBuddy 原生 Task 的
+ subagent_name)标识派发目标;这条路径之前没有测试覆盖,_extract_from_task
+ 漏认这个字段会导致 dispatch 统计对所有 Agent 工具派发的场景失明。"""
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s3"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Agent",
+ "tool_input": {"subagent_type": "worker", "description": "spawn a team"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "worker")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("dispatched", {}).get("worker"), 1)
+ hist = sess.get("agent_history") or []
+ self.assertTrue(any(
+ h.get("agent") == "worker" and str(h.get("evidence") or "").startswith("dispatch")
+ for h in hist
+ ))
+
+ def test_extract_from_task_prefers_subagent_type_over_subagent_name(self):
+ resolver = AgentIdentityResolver()
+ result = resolver._extract_from_task({"subagent_type": "explorer", "subagent_name": "developer"})
+ self.assertEqual(result, "explorer")
diff --git a/.codebuddy/skills/agent-observability/tests/test_build_dashboard_data.py b/.codebuddy/skills/agent-observability/tests/test_build_dashboard_data.py
new file mode 100644
index 00000000..53b031c1
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_build_dashboard_data.py
@@ -0,0 +1,603 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+
+
+class ToolCallFailedTests(unittest.TestCase):
+ """真实 CodeBuddy CLI transcript 里从没出现过 `is_error` 这个键——实测抓到的
+ rawResponse 形如 {"exitCode": 0, "tool_error_code": "0", ...}(成功)或非 0
+ exitCode(失败)。之前只认 is_error,导致这个宿主上失败统计永远是 0。"""
+
+ def test_real_success_shape_from_codebuddy_is_not_a_failure(self):
+ # 实测数据:ls 一个不存在的路径,但命令写成了 `ls ...; echo "EXIT_CODE=$?"`,
+ # 复合命令整体 exitCode 被内层 echo 冲成了 0——工具调用本身没有失败。
+ raw_response = {
+ "exitCode": 0, "signal": None, "interrupted": False,
+ "sandboxDenied": False, "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0, "tool_error_code": "0",
+ }
+ self.assertFalse(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_exit_code_is_a_failure(self):
+ raw_response = {"exitCode": 1, "tool_error_code": "1"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_tool_error_code_without_exit_code_is_a_failure(self):
+ raw_response = {"tool_error_code": "127"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_legacy_is_error_flag_still_recognized(self):
+ self.assertTrue(bdd.tool_call_failed({"is_error": True}))
+
+ def test_missing_or_non_dict_raw_response_is_not_a_failure(self):
+ self.assertFalse(bdd.tool_call_failed(None))
+ self.assertFalse(bdd.tool_call_failed("not a dict"))
+ self.assertFalse(bdd.tool_call_failed({}))
+
+ def test_build_failures_and_session_status_use_exit_code(self):
+ events = [
+ {
+ "event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash",
+ "tool_details": {"raw_response": {"exitCode": 1, "tool_error_code": "1"}},
+ },
+ ]
+ failures = bdd.build_failures(events)
+ self.assertEqual(len(failures), 1)
+ self.assertEqual(failures[0]["tool"], "Bash")
+ self.assertEqual(failures[0]["code"], "1")
+
+ _, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(sessions[0]["status"], "error")
+
+
+class ResolveInputPathsTests(unittest.TestCase):
+ def setUp(self):
+ self.skill_root = Path("/tmp/fake-skill-root")
+
+ def test_defaults_fall_back_to_skill_root_logs(self):
+ metrics, state = bdd.resolve_input_paths(self.skill_root)
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_none_args_equivalent_to_empty_args(self):
+ m1, s1 = bdd.resolve_input_paths(self.skill_root, None, None)
+ m2, s2 = bdd.resolve_input_paths(self.skill_root, "", "")
+ self.assertEqual((m1, s1), (m2, s2))
+
+ def test_both_args_override(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_metrics_only_override_keeps_default_state(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", None
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_state_only_override_keeps_default_metrics(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, None, "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_tilde_expansion(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "~/x/metrics.ndjson", "~/y/.state.json"
+ )
+ self.assertEqual(metrics, (Path.home() / "x" / "metrics.ndjson").absolute())
+ self.assertEqual(state, (Path.home() / "y" / ".state.json").absolute())
+
+
+class MainEndToEndTests(unittest.TestCase):
+ def _run_main(self, argv: list[str]) -> None:
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ try:
+ self.assertEqual(bdd.main(), 0)
+ finally:
+ sys.argv = old_argv
+
+ def test_default_paths_unchanged_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ out = Path(td) / "dashboard-data.json"
+ self._run_main(["--project-root", td, "--out", str(out)])
+ self.assertTrue(out.is_file())
+ data = json.loads(out.read_text("utf-8"))
+ expected_metrics = str(bdd.SCRIPTS_DIR.parent / "logs" / "metrics.ndjson")
+ expected_state = str(bdd.SCRIPTS_DIR.parent / "logs" / ".state.json")
+ self.assertEqual(data["source"]["metrics_ndjson"], expected_metrics)
+ self.assertEqual(data["source"]["state_json"], expected_state)
+
+ def test_overridden_paths_read_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics_file = root / "metrics.ndjson"
+ state_file = root / ".state.json"
+ metrics_file.write_text(
+ '{"event":"usage","sid":"s1","ts":1,"tokens":{"input":10,"output":20}}\n',
+ encoding="utf-8",
+ )
+ state_file.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ out = root / "dashboard-data.json"
+
+ self._run_main([
+ "--project-root", td,
+ "--out", str(out),
+ "--metrics-path", str(metrics_file),
+ "--state-path", str(state_file),
+ ])
+ self.assertTrue(out.is_file())
+
+ data = json.loads(out.read_text("utf-8"))
+ # resolve_input_paths 对覆盖路径执行 .expanduser().absolute(),断言需对齐(macOS 下不用 .resolve() 以避免 /tmp → /private/tmp 符号链接错位)。
+ self.assertEqual(data["source"]["metrics_ndjson"], str(metrics_file.absolute()))
+ self.assertEqual(data["source"]["state_json"], str(state_file.absolute()))
+ # 覆盖文件确实被读取:metrics 行被解析进了 event_count。
+ self.assertEqual(data["source"]["event_count"], 1)
+
+
+class TopSlowTests(unittest.TestCase):
+ """`--top-slow N` 是纯增量能力:默认不开启,开启后也只往终端打印,绝不改动
+ dashboard-data.json 的结构(看板前端按字段取值,多一个字段或少一个字段都会
+ 直接影响渲染)。这些用例把"降序取前 N""非 tool 事件排除""ms 兜底""只读"
+ 四条边界钉住,避免后续有人顺手把结果写进 JSON 或改了排序方向。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 300, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Bash", "ms": 900, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 120, "agent": "main"},
+ ]
+
+ def _write_metrics(self, root: Path) -> Path:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text(
+ "\n".join(json.dumps(e) for e in self._events()) + "\n",
+ encoding="utf-8",
+ )
+ return metrics
+
+ def _run_main(self, argv: list[str]) -> str:
+ """跑一次 main() 并返回捕获到的 stdout——top-slow 的产出只体现在终端上,
+ 不体现在 JSON 里,所以断言必须落在 stdout。"""
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ return buf.getvalue()
+
+ def _printed_tools(self, stdout: str) -> list[str]:
+ tools = []
+ for line in stdout.splitlines():
+ line = line.strip()
+ if not line or not line[0].isdigit():
+ continue
+ tools.append(line.split(". ", 1)[1].split()[0])
+ return tools
+
+ def test_returns_n_slowest_tool_events_descending(self):
+ rows = bdd.build_top_slow(self._events(), 2)
+ self.assertEqual([(r["tool"], r["ms"]) for r in rows], [("Bash", 900), ("Read", 300)])
+
+ def test_limit_greater_than_event_count_returns_all_without_error(self):
+ events = [{"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 10}]
+ rows = bdd.build_top_slow(events, 99)
+ self.assertEqual(len(rows), 1)
+ self.assertEqual(rows[0]["tool"], "Bash")
+
+ def test_non_tool_events_are_excluded(self):
+ rows = bdd.build_top_slow(self._events(), 10)
+ self.assertEqual([r["tool"] for r in rows], ["Bash", "Read", "Grep"])
+ # usage 事件即使带 ms 也不能混进来。
+ self.assertTrue(all(isinstance(r["ms"], (int, float)) for r in rows))
+
+ def test_missing_or_non_numeric_ms_falls_back_to_zero(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": "120"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Grep", "ms": None},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Edit", "ms": 1},
+ ]
+ rows = bdd.build_top_slow(events, 4)
+ self.assertEqual(len(rows), 4)
+ # 非数字/缺失的 ms 一律按 0 计,不会把字符串 "120" 排到最前面。
+ self.assertEqual(sum(r["ms"] for r in rows), 1)
+
+ def test_disabled_by_default_prints_nothing_extra(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertNotIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), [])
+
+ def test_enabled_prints_tool_and_ms_descending(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ "--top-slow", "2",
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), ["Bash", "Read"])
+ self.assertIn("900ms", stdout)
+ self.assertNotIn("120ms", stdout) # N=2,第三名的 Grep 不该出现
+
+ def test_enabled_does_not_change_dashboard_data_structure(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ state = root / ".state.json"
+ state.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ # 输出到两个不同文件再比对,避免"第二次跑覆盖了第一次"导致对比失真。
+ out_on = root / "on.json"
+ out_off = root / "off.json"
+ self._run_main([
+ "--project-root", td, "--out", str(out_on),
+ "--metrics-path", str(metrics), "--state-path", str(state), "--top-slow", "5",
+ ])
+ self._run_main([
+ "--project-root", td, "--out", str(out_off),
+ "--metrics-path", str(metrics), "--state-path", str(state),
+ ])
+ data_on = json.loads(out_on.read_text("utf-8"))
+ data_off = json.loads(out_off.read_text("utf-8"))
+ data_on.pop("generated_at")
+ data_off.pop("generated_at")
+ self.assertEqual(data_on, data_off)
+ # 兜底断言:结果没有以任何形式渗进 JSON(不只是"结构相同")。
+ self.assertNotIn("topSlow", json.dumps(data_on))
+ self.assertNotIn("top-slow", json.dumps(data_on))
+
+
+class BuildDailyAndSessionsTurnAttributionTests(unittest.TestCase):
+ """真实场景复现过:AgentLens(写 state.current_turn 的那套 tracing)关闭时,
+ tool/usage 事件自己的 turn_id 永远是 None,只有 user_prompt_submit 事件带真实
+ turn_id。修复前所有没有 turn_id 的事件会被塌缩进同一个 "?" 占位桶,看起来
+ 像"整个会话只有 1 个 turn",哪怕实际发了好几轮 prompt。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t2", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 6.0, "tool": "Edit", "ms": 80, "agent": "main"},
+ ]
+
+ def test_turns_reflect_prompt_boundaries_not_a_single_bucket(self):
+ daily, sessions = bdd.build_daily_and_sessions(self._events())
+ self.assertEqual(len(sessions), 1)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 2)
+ self.assertEqual(sess["toolCalls"], 3)
+ self.assertEqual(len(sess["timeline"]), 2)
+ turn1_tools = [e["tool"] for e in sess["timeline"][0]["events"] if e["kind"] == "tool"]
+ turn2_tools = [e["tool"] for e in sess["timeline"][1]["events"] if e["kind"] == "tool"]
+ self.assertEqual(turn1_tools, ["Bash"])
+ self.assertEqual(turn2_tools, ["Read", "Edit"])
+
+ def test_events_before_first_prompt_fall_back_to_unknown_bucket(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 2.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Read", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ # 没有归属到任何真实 turn 的事件仍然单独成桶,不会被错误地并入第一个真实 turn。
+ self.assertEqual(len(sess["timeline"]), 2)
+ self.assertEqual(sess["timeline"][0]["turn"], 1)
+
+ def test_prompt_only_turn_with_no_tool_calls_still_appears_in_timeline(self):
+ """真实数据复现过:纯对话轮次(用户发了 prompt,但助手没有调用任何工具,
+ 也没有产生 usage 事件)之前完全不会在 timeline 里建桶——turns 计数是对的
+ (来自 user_prompt_submit 自带的 turn_id),但展开的时间线分组数会比 turns
+ 少,二者对不上。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 3.0, "turn_id": "t2", "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t3", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 3)
+ self.assertEqual(len(sess["timeline"]), 3)
+ self.assertEqual(sess["timeline"][1]["events"], [])
+
+ def test_prompt_only_session_still_counted_in_daily_session_count(self):
+ """真实数据复现过(TC5 当天 5 个 session,"总览"页汇总出的会话数却是 4):
+ daily["_sids"]("会话浏览"总览卡片"会话数"的数据源)之前只在 tool/usage
+ 分支里 add,一个全程只发了 prompt、没有触发任何工具调用也没有 usage 事件
+ 的 session(比如用户发了消息但被拒绝/打断,没有真正执行)会被这天的
+ sessionCount 完全漏掉——尽管 sessions 列表("会话浏览"tab)里它确实在,
+ 导致总览页"会话数"比实际能展开看到的会话数少。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s2", "ts": 3.0, "turn_id": "t1", "agent": "main"},
+ ]
+ daily, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(len(sessions), 2)
+ self.assertEqual(len(daily), 1)
+ self.assertEqual(daily[0]["sessionCount"], 2)
+
+
+class BuildDevflowRunsClassicSoloTests(unittest.TestCase):
+ """真实运行验证过:Classic small 任务会经过 PHASE-0 -> SOLO -> TASK-05
+ (knowledge 由 solo-developer 合并执行),不是只有 PHASE-0/SOLO 两步。"""
+
+ def test_solo_run_includes_task05_and_marks_phase0_completed(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "solo-with-knowledge_20260914_0600"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "solo-with-knowledge_20260914_0600",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ # 注意:真实 schema 里 stages{} 不含 PHASE-0 —— Phase 0 是隐式完成的。
+ "stages": {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-02": {"status": "skipped", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "skipped", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "skipped", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "skipped", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-05", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-05"], "completed")
+ self.assertEqual(stage_by_key["PHASE-0"], "completed")
+ self.assertNotIn("TASK-01", stage_by_key) # SOLO 路径不该混进 medium/large 的阶段
+
+
+class BuildDevflowRunsMediumWithLingeringSoloKeyTests(unittest.TestCase):
+ """用户反馈复现:workflow-state.json 模板固定给每次运行都写一份 SOLO stage
+ (见 assets/workflow-state-template.json 里 SOLO.description 的说明:
+ "仅当 size_class==small 时启用,否则保持 skipped"),medium/large 任务从不会
+ 真正执行它,状态停在 "pending" 或 "skipped"。修复前 `"SOLO" in stages` 只看
+ key 存不存在,不看状态,导致这类 medium 任务被误判成 solo 路径,阶段视图会用
+ CLASSIC_SOLO_ORDER 渲染,把 TASK-01/TASK-02/TASK-03/CODE-REVIEW/TASK-04 全部
+ 从 stepper 里漏掉。"""
+
+ def _run(self, solo_status: str):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "medium-with-lingering-solo_20260915_0900"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "medium-with-lingering-solo_20260915_0900",
+ "size_class": "medium",
+ "current_stage": "TASK-03",
+ "last_event": "TASK-02_completed",
+ "stages": {
+ "SOLO": {"status": solo_status, "executor": "solo-developer", "retry_count": 0},
+ "TASK-01": {"status": "completed", "executor": "main", "retry_count": 0},
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "pending", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "pending", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "pending", "executor": "knowledge-engineer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+ return bdd.build_devflow_runs(project_root)
+
+ def test_medium_run_with_skipped_solo_key_uses_full_classic_order(self):
+ runs = self._run("skipped")
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ # 修复前:这里会走 CLASSIC_SOLO_ORDER,TASK-01/02/03/CODE-REVIEW/TASK-04 全部消失。
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("TASK-02", stage_by_key)
+ self.assertIn("TASK-03", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+ self.assertIn("TASK-04", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-02"], "completed")
+ self.assertEqual(stage_by_key["TASK-03"], "in_progress")
+
+ def test_medium_run_with_pending_solo_key_uses_full_classic_order(self):
+ # 模板初始状态是 "pending"(不是所有实现都会显式改成 "skipped"),同样不该被判成 solo。
+ runs = self._run("pending")
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+
+
+class BuildDevflowRunsDurationTests(unittest.TestCase):
+ """真实数据复现过:TASK-05 的 started_at 可能早于 SOLO 的 completed_at
+ (同一次 solo-developer 执行内部的子步骤,不是真正先后发生的两个阶段)。
+ total_duration 必须按真实起止跨度算,不能对逐阶段 duration 求和——否则会把
+ 重叠部分重复计入,虚高于源数据本身反映的运行时长(这次修复前是 600s,
+ 真实跨度只有 540s)。"""
+
+ def _write_state(self, project_root: Path, stages: dict) -> None:
+ run_dir = project_root / "artifacts" / "overlap-run_20260914_0620"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "overlap-run_20260914_0620",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ "stages": stages,
+ }), encoding="utf-8")
+
+ def test_total_duration_uses_true_span_not_sum_of_overlapping_stages(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ "started_at": "2026-09-14T06:20:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ "TASK-05": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ # 早于 SOLO 的 completed_at —— 真实数据里观测到的重叠场景。
+ "started_at": "2026-09-14T06:28:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ # 真实跨度是 06:20~06:29 = 540s,不是 540+60=600s。
+ self.assertEqual(runs[0]["duration"], 540)
+ stage_by_key = {s["key"]: s["duration"] for s in runs[0]["stages"]}
+ # 单个阶段自身的 duration 不受影响,仍然如实反映各自的起止跨度。
+ self.assertEqual(stage_by_key["SOLO"], 540)
+ self.assertEqual(stage_by_key["TASK-05"], 60)
+
+ def test_total_duration_is_zero_when_no_stage_has_valid_timestamps(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(runs[0]["duration"], 0)
+
+
+class BuildDailyAndSessionsPerEventAgentTests(unittest.TestCase):
+ """真实数据复现过(TC5,size_class=small 但走了真实 team_create/send_message
+ 派发):同一个 sid 下,metrics.ndjson 的 tool/usage 事件本来就各自带着准确的
+ agent 字段(一次真实会话里 66 条 main、64 条 solo-developer),但展开进
+ timeline 的每条 event 字典只有 kind/tool/ms/err,从不写回 agent —— 时间线里
+ 完全看不出某次工具调用到底是 main 自己做的还是派发给 solo-developer 后做的,
+ 等于白白丢弃了上游已经采集到的数据。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Agent", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Bash", "ms": 100, "agent": "solo-developer"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "tokens": {"input": 10, "output": 5}, "agent": "solo-developer"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "SendMessage", "ms": 30, "agent": "main"},
+ ]
+
+ def test_timeline_events_carry_the_agent_that_actually_ran_them(self):
+ _, sessions = bdd.build_daily_and_sessions(self._events())
+ sess = sessions[0]
+ events = sess["timeline"][0]["events"]
+ by_tool = {e.get("tool"): e for e in events if e["kind"] == "tool"}
+ self.assertEqual(by_tool["Agent"]["agent"], "main")
+ self.assertEqual(by_tool["Bash"]["agent"], "solo-developer")
+ self.assertEqual(by_tool["SendMessage"]["agent"], "main")
+ usage_events = [e for e in events if e["kind"] == "usage"]
+ self.assertEqual(usage_events[0]["agent"], "solo-developer")
+
+ def test_missing_agent_on_raw_event_falls_back_to_main(self):
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 10},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["timeline"][0]["events"][0]["agent"], "main")
+
+
+class BuildDispatchTests(unittest.TestCase):
+ """真实数据复现过(TC5 的 dashboard-data-top-slow 会话,sid 01a09ef5...):
+ 修复前 build_dispatch() 把 agent_history 里所有 evidence 以 "dispatch" 或
+ "inbox" 开头的条目一律计数,导致两个真实问题——
+ 1) solo-developer 被上报回声(inbox@report:*)重复计入,真实派发只有 2 次,
+ 却显示成 5;
+ 2) team-lead 显示成一个"被 main 派发的子 agent",但 team-lead 在
+ core/agent_identity.py::normalize_role_name 里本来就和 main 归为一类
+ (它是 CodeBuddy 原生 team 基础设施里 lead session 自己的 mailbox 名,
+ 不是真实存在的子 agent),面板标题明明叫"Main → 子 Agent 派发次数",
+ 混进一个其实等价于 main 自己的假子 agent。"""
+
+ def _real_tc5_agent_history(self):
+ # 逐条取自真实会话 01a09ef5-1c6b-7928-870e-a5056ff360e1 的 .state.json。
+ return [
+ {"ts": 1.0, "agent": "solo-developer", "evidence": "dispatch@Agent<-main"},
+ {"ts": 2.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 3.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ {"ts": 4.0, "agent": "solo-developer", "evidence": "inbox@dispatch:solo-developer"},
+ {"ts": 5.0, "agent": "main", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 6.0, "agent": "main", "evidence": "inbox@handoff:solo-developer->main"},
+ {"ts": 7.0, "agent": "solo-developer", "evidence": "dispatch@SendMessage<-main"},
+ {"ts": 8.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ ]
+
+ def test_real_tc5_history_excludes_team_lead_and_report_echoes(self):
+ state = {"01a09ef5": {"agent_history": self._real_tc5_agent_history()}}
+ rows = bdd.build_dispatch(state)
+ # team-lead(main 的别名)完全不出现;solo-developer 只数真正代表新派发的
+ # 3 条证据(2 条工具触发的 dispatch@ + 1 条 inbox 独立确认的 dispatch:),
+ # 2 条上报回声(inbox@report:*)不计入。
+ self.assertEqual(rows, [{"agent": "solo-developer", "count": 3}])
+
+ def test_inbox_dispatch_evidence_alone_is_still_counted(self):
+ """inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)是原生 team
+ 基础设施里唯一能感知到、但没有经过 Agent/Task 工具调用拦截到的派发方式
+ (例如 team-lead 用 mailbox 直接投递任务),必须保留,不能因为过滤
+ report/handoff 回声就连这类真实派发信号也一起丢掉。"""
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "architect", "evidence": "inbox@dispatch:architect"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [{"agent": "architect", "count": 1}])
+
+ def test_report_and_handoff_evidence_alone_are_not_dispatches(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "developer", "evidence": "inbox@report:developer"},
+ {"ts": 2.0, "agent": "test-engineer", "evidence": "inbox@handoff:developer->test-engineer"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+ def test_team_lead_is_excluded_even_without_report_noise(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-main"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.codebuddy/skills/agent-observability/tests/test_cls_sink.py b/.codebuddy/skills/agent-observability/tests/test_cls_sink.py
new file mode 100644
index 00000000..2da9d6a1
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_cls_sink.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import cls_sink, emitter # type: ignore
+
+
+class CLSSinkTests(unittest.TestCase):
+ def _write_cls_env(self, root: Path, *extra_lines: str) -> None:
+ lines = [
+ "CLS_TOPIC_ID=test-topic-id",
+ "CLS_ENDPOINT=cls.internal.tencentcloudapi.com",
+ "CLS_SERVICE_NAME=agent-observability",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=20",
+ *extra_lines,
+ ]
+ (root / ".env").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+ def test_load_config_supports_cls_and_tc_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "TC_SECRET_ID=test-secret-id",
+ "TC_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertTrue(config.enabled)
+ self.assertEqual(config.endpoint, "cls.internal.tencentcloudapi.com")
+ self.assertEqual(config.topic_id, "test-topic-id")
+ self.assertEqual(config.secret_id, "test-secret-id")
+ self.assertEqual(config.secret_key, "test-secret-key")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.service_name, "agent-observability")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_load_config_supports_tencentcloud_scoped_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(
+ os.environ,
+ {
+ "TENCENTCLOUD_SECRET_ID_438167613": "scoped-secret-id",
+ "TENCENTCLOUD_SECRET_KEY_438167613": "scoped-secret-key",
+ },
+ clear=True,
+ ):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "scoped-secret-id")
+ self.assertEqual(config.secret_key, "scoped-secret-key")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_mirror_record_invokes_node_uploader(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=0, stdout="", stderr="")) as run, \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-1"}, cwd=td)
+
+ self.assertTrue(ok)
+ run.assert_called_once()
+ payload = json.loads(run.call_args.kwargs["input"])
+ self.assertEqual(payload["records"][0]["event"], "tool")
+ self.assertEqual(payload["topicId"], "test-topic-id")
+ self.assertEqual(payload["secretToken"], "")
+
+ def test_load_config_requires_credentials_from_env(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "")
+ self.assertEqual(config.secret_key, "")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertFalse(config.ready)
+
+ def test_load_config_reads_secret_token_aliases(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "TC_SESSION_TOKEN=test-session-token",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_token, "test-session-token")
+
+ def test_load_config_supports_timeout_override(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=45",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.timeout_seconds, 45)
+
+ def test_mirror_record_writes_debug_when_uploader_fails(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=1, stdout="", stderr="boom")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-2"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertFalse(ok)
+ self.assertEqual(entries[-1]["stage"], "uploader_failed")
+ self.assertEqual(entries[-1]["stderr"], "boom")
+ self.assertEqual(entries[-1]["timeout_seconds"], 20)
+
+ def test_mirror_record_writes_success_debug_when_uploader_succeeds(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(True, "ok")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-3"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertTrue(ok)
+ self.assertEqual(entries[0]["stage"], "uploader_start")
+ self.assertEqual(entries[-1]["stage"], "uploader_ok")
+ self.assertEqual(entries[-1]["method"], "python_api_v3")
+
+ def test_emit_keeps_local_log_when_cls_push_raises(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+ with mock.patch.object(emitter.cls_sink, "mirror_record", side_effect=RuntimeError("boom")):
+ emitter.emit(log_path, {"event": "start", "sid": "s-emit"})
+
+ records = [json.loads(line) for line in log_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0]["event"], "start")
+ self.assertEqual(records[0]["sid"], "s-emit")
diff --git a/.codebuddy/skills/agent-observability/tests/test_collector.py b/.codebuddy/skills/agent-observability/tests/test_collector.py
new file mode 100644
index 00000000..05547f06
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_collector.py
@@ -0,0 +1,715 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, agentlens, collector, emitter, runtime, state as st # type: ignore
+
+
+class CollectorTests(unittest.TestCase):
+ def test_cost_of_uses_known_model_price_table(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ cost = emitter.cost_of(tokens, "gpt-4o")
+ self.assertIsNotNone(cost)
+ self.assertGreaterEqual(cost, 0.0)
+
+ def test_cost_of_returns_none_for_unknown_model(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ self.assertIsNone(emitter.cost_of(tokens, "unknown-model"))
+
+ def test_emit_adds_codebuddy_cli_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "codebuddy-cli")
+
+ def test_emit_preserves_explicit_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source", "data_source": "manual"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "manual")
+
+ def test_emit_session_duration_uses_first_log_ts_when_state_was_recreated(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ log_path = root / "metrics.ndjson"
+ state_path = root / ".state.json"
+ log_path.write_text(
+ json.dumps({"event": "start", "sid": "s-duration", "ts": 100.0}) + "\n",
+ encoding="utf-8",
+ )
+ state_path.write_text(
+ json.dumps({"s-duration": {"started_at": 190.0}}, ensure_ascii=False),
+ encoding="utf-8",
+ )
+
+ emitter.emit(log_path, {"event": "usage", "sid": "s-duration", "ts": 200.0, "tokens": {"input": 1, "output": 2}})
+
+ records = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
+ self.assertEqual(records[-1]["session_duration_sec"], 100.0)
+
+ def test_emit_session_duration_starts_at_zero_without_prior_log_or_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-new", "ts": 100.0})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["session_duration_sec"], 0.0)
+
+ def test_parse_transcript_tail_extracts_tokens(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ out = collector.parse_transcript_tail(str(transcript), max_lines=20)
+ self.assertIsInstance(out, dict)
+ self.assertIsInstance(out.get("tokens"), dict)
+ self.assertEqual(out["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(out["tokens"].get("output_tokens"), 120)
+ usage_records = out.get("usage_records") or []
+ tool_records = out.get("tool_records") or []
+ self.assertEqual(len(usage_records), 3)
+ self.assertEqual(usage_records[0]["tokens"].get("input_tokens"), 1820)
+ self.assertEqual(usage_records[-1]["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(usage_records[0].get("message_id"), "msg-001")
+ self.assertEqual(usage_records[-1].get("message_id"), "msg-003")
+ self.assertLess(usage_records[0]["offset"], usage_records[-1]["offset"])
+ self.assertEqual(len(tool_records), 8)
+ self.assertEqual(tool_records[0]["tool"], "read_file")
+ self.assertEqual(tool_records[0]["message_id"], "msg-001")
+ self.assertEqual(tool_records[0]["next_message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["tool"], "Bash")
+ self.assertEqual(tool_records[-1]["message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["next_message_id"], "msg-003")
+
+ def test_realtime_usage_is_request_level_and_dedupes_across_phase(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-transcript"
+
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=str(transcript),
+ max_lines=20,
+ )
+ entries = scan.get("entries") or []
+
+ self.assertEqual(len(entries), 3)
+ self.assertEqual(entries[0]["tokens"]["input"], 1820)
+ self.assertGreater(entries[0]["offset"], 0)
+ self.assertEqual(entries[0]["message_id"], "msg-001")
+ self.assertEqual(entries[1]["tokens"]["input"], 2100)
+ self.assertEqual(entries[1]["tokens"]["total"], 2158)
+ self.assertEqual(len(scan.get("tool_records") or []), 8)
+
+ usage_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Read",
+ entry=entries[0],
+ )
+ stop_key = collector.build_transcript_event_key(
+ kind="stop",
+ tool="__stop__",
+ entry=entries[0],
+ )
+ other_tool_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Bash",
+ entry=entries[0],
+ )
+
+ self.assertEqual(usage_key, stop_key)
+ self.assertEqual(usage_key, other_tool_key)
+ self.assertTrue(st.claim_transcript_event(state_path, sid, usage_key, str(transcript)))
+ self.assertFalse(st.claim_transcript_event(state_path, sid, stop_key, str(transcript)))
+
+ def test_find_current_tool_message_id_prefers_transcript_tool_records(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool-mid"
+
+ read_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Read",
+ )
+ bash_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Bash",
+ )
+
+ self.assertEqual(read_mid, "msg-002")
+ self.assertEqual(bash_mid, "msg-003")
+
+ def test_resolve_subagent_transcript_alias_and_tool_context(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ alias_session_id = "subagent-session-1"
+ subagent = subagents / "agent-a.jsonl"
+ main.write_text("", encoding="utf-8")
+ subagent.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "type": "message",
+ "sessionId": alias_session_id,
+ "providerData": {"agent": "Explore"},
+ }
+ ),
+ json.dumps(
+ {
+ "type": "function_call",
+ "sessionId": alias_session_id,
+ "name": "Grep",
+ "callId": "call-1",
+ "providerData": {
+ "agent": "Explore",
+ "messageId": "msg-sub-001",
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ aliased_path = str(root / f"{alias_session_id}.jsonl")
+ resolved = collector.resolve_transcript_path_alias(sid, aliased_path)
+ self.assertEqual(resolved, str(subagent.resolve()))
+
+ state_path = root / ".state.json"
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=aliased_path,
+ tool_name="Grep",
+ )
+ self.assertEqual(
+ context,
+ {
+ "message_id": "msg-sub-001",
+ "transcript_path": str(subagent.resolve()),
+ "agent": "explore",
+ "tool_details": {"call_id": "call-1"},
+ },
+ )
+
+ def test_find_current_tool_context_prefers_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ early = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=1.2,
+ )
+ late = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(early["message_id"], "msg-early")
+ self.assertEqual(late["message_id"], "msg-late")
+
+ def test_find_current_tool_context_claims_distinct_call_ids_with_same_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "arguments": "{\"command\":\"echo one\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "arguments": "{\"command\":\"echo two\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result one"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result two"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ first = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ second = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ third = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+
+ self.assertEqual(first["message_id"], "msg-shared")
+ self.assertEqual(second["message_id"], "msg-shared")
+ self.assertNotEqual(first["tool_details"]["call_id"], second["tool_details"]["call_id"])
+ self.assertIn("arguments", first["tool_details"])
+ self.assertIn("result_content", first["tool_details"])
+ self.assertEqual(third, {"duplicate": True})
+
+ def test_find_fallback_usage_event_prefers_latest_matching_usage(self):
+ tool_event = {
+ "tool": "Bash",
+ "agent": "main",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ usage_events = [
+ {
+ "agent": "main",
+ "tool": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-old",
+ "source_offset": 100,
+ },
+ {
+ "agent": "main",
+ "tool": "Bash",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-current",
+ "source_offset": 200,
+ },
+ ]
+
+ matched = collector.find_fallback_usage_event(tool_event, usage_events)
+ self.assertIsNotNone(matched)
+ self.assertEqual(matched["message_id"], "msg-current")
+
+ def test_find_current_tool_context_prefers_explicit_call_id_over_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {
+ "messageId": "msg-early",
+ "toolResult": {"content": "early result"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {
+ "messageId": "msg-late",
+ "toolResult": {"content": "late result"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-call-id-priority",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ call_id="call-early",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(context["message_id"], "msg-early")
+ self.assertEqual(context["tool_details"]["call_id"], "call-early")
+ self.assertEqual(context["tool_details"]["result_content"], "early result")
+
+ def test_find_current_tool_context_uses_next_message_id_when_available(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-tool"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-tool",
+ "toolResult": {"content": "<tool_use_error>missing</tool_use_error>"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 2000,
+ "type": "assistant",
+ "providerData": {"messageId": "msg-next"},
+ "content": "next step",
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-next-mid",
+ transcript_path=str(transcript),
+ tool_name="Read",
+ call_id="call-1",
+ )
+
+ self.assertEqual(context["message_id"], "msg-next")
+ self.assertEqual(context["tool_details"]["original_message_id"], "msg-tool")
+ self.assertEqual(context["tool_details"]["next_message_id"], "msg-next")
+ self.assertTrue(context["tool_details"]["message_id_reassigned"])
+
+ def test_flush_pending_tool_events_emits_after_transcript_catches_up(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ state_path = root / ".state.json"
+ log_path = root / "metrics.ndjson"
+ transcript = root / "session.jsonl"
+ transcript.write_text("", encoding="utf-8")
+ sid = "s-pending"
+
+ tool_event = {
+ "event": "tool",
+ "sid": sid,
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 42,
+ "transcript_path": str(transcript),
+ "turn_id": "turn-1",
+ "ts": 1.2,
+ "skill": [],
+ "rule": [],
+ "cwd": str(ROOT),
+ }
+ st.append_pending_tool_emit(state_path, sid, tool_event)
+
+ transcript.write_text(
+ json.dumps(
+ {
+ "timestamp": 1300,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-later"},
+ }
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ emitted_calls: list[dict[str, object]] = []
+ original_emit_post_step = agentlens.emit_post_step
+ try:
+ agentlens.emit_post_step = lambda **kwargs: emitted_calls.append(kwargs)
+ runtime.flush_pending_tool_events(
+ state_path=state_path,
+ log_path=log_path,
+ sid=sid,
+ )
+ finally:
+ agentlens.emit_post_step = original_emit_post_step
+
+ self.assertEqual(st.get_pending_tool_emits(state_path, sid), [])
+ lines = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines() if line.strip()]
+ self.assertEqual(len(lines), 1)
+ self.assertEqual(lines[0]["message_id"], "msg-later")
+ self.assertEqual(len(emitted_calls), 1)
+ self.assertEqual(emitted_calls[0]["tool_event"]["message_id"], "msg-later")
+
+ def test_related_transcript_paths_include_subagents(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ sub_a = subagents / "agent-a.jsonl"
+ sub_b = subagents / "agent-b.jsonl"
+ for path in (main, sub_a, sub_b):
+ path.write_text("", encoding="utf-8")
+
+ paths = collector.related_transcript_paths(sid, str(main))
+
+ self.assertEqual(
+ paths,
+ [
+ str(main.resolve()),
+ str(sub_a.resolve()),
+ str(sub_b.resolve()),
+ ],
+ )
+
+ def test_subagent_transcript_maps_to_role_name(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-27e41af0.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for knowledge-engineer\\">"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "knowledge-engineer",
+ )
+
+ def test_subagent_transcript_prefers_assignment_role_over_general_provider_agent(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-165e361f.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"type":"message","providerData":{"agent":"general-purpose"},"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for developer\\">\\n待命。\\n你在本 devflow 中的角色:developer(开发角色)"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "developer",
+ )
+
+ def test_inbox_standby_assignment_does_not_switch_current_agent(self):
+ messages = [
+ {
+ "mailbox_name": "architect",
+ "mailbox_role": "architect",
+ "from_role": "main",
+ "summary": "Initial task assignment for architect",
+ "text": "待命,监听 main 唤醒。",
+ "payload": None,
+ "is_shutdown": False,
+ "is_standby": True,
+ }
+ ]
+ current, dispatched, meta = agent_identity.infer_identity_from_messages(messages)
+ self.assertIsNone(current)
+ self.assertIsNone(dispatched)
+ self.assertEqual(meta["messages_seen"], 1)
+
+ def test_record_pre_post_duration(self):
+ with tempfile.TemporaryDirectory() as td:
+ pending = Path(td) / ".pending.json"
+ pre = {"session_id": "s1", "tool_name": "read_file"}
+ post = {"session_id": "s1", "tool_name": "read_file"}
+ collector.record_pre(pending, pre)
+ time.sleep(0.02)
+ ms = collector.record_post(pending, post)
+ self.assertIsInstance(ms, int)
+ self.assertGreaterEqual(ms, 0)
+
+ def test_record_tool_usage_counts_skill_and_rule(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool"
+ # 先确保 session 结构
+ s = st.load_state(state_path)
+ st.ensure_session(s, sid)
+ st.save_state(state_path, s)
+
+ data = {
+ "tool_name": "use_skill",
+ "tool_input": {"command": "pdf", "filePath": "README.md"},
+ }
+ skills_meta = {"pdf": {"source": "user", "version": "1.0.0"}}
+ rules_meta = {
+ "security": {"source": "project", "alwaysApply": True, "enabled": True, "globs": []}
+ }
+ collector.record_tool_usage(
+ state_path=state_path,
+ sid=sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent="main",
+ collect_skills=True,
+ )
+
+ skills_usage, rules_usage = collector.get_session_usage(state_path, sid)
+ self.assertEqual(skills_usage.get("pdf", {}).get("count"), 1)
+ self.assertEqual(rules_usage.get("security", {}).get("count"), 1)
+
+ def test_step_span_registry_is_idempotent(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-step"
+ carrier = {"traceparent": "00-" + ("1" * 32) + "-" + ("2" * 16) + "-01"}
+ st.begin_turn(state_path, sid, "turn-1", carrier)
+
+ first = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("3" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+ second = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("4" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+
+ self.assertEqual(first, second)
+ self.assertEqual(st.get_step_span_carrier(state_path, sid, "main", "msg-001"), first)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.codebuddy/skills/agent-observability/tests/test_devflow.py b/.codebuddy/skills/agent-observability/tests/test_devflow.py
new file mode 100644
index 00000000..9ad0a7fd
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_devflow.py
@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, devflow, state as st # type: ignore
+
+
+def _write_team_config(team_dir: Path, *, lead_session_id: str, member_cwd: str) -> None:
+ team_dir.mkdir(parents=True, exist_ok=True)
+ (team_dir / "config.json").write_text(
+ json.dumps({
+ "leadSessionId": lead_session_id,
+ "createdAt": 1,
+ "members": [{"cwd": member_cwd}],
+ }),
+ encoding="utf-8",
+ )
+
+
+class TaskSlugFromTeamDirTests(unittest.TestCase):
+ def test_strips_fixed_prefix(self):
+ team_dir = Path("/tmp/.codebuddy/teams/multi-agents-devflow-my-task_20260911_1200")
+ self.assertEqual(devflow.task_slug_from_team_dir(team_dir), "my-task_20260911_1200")
+
+ def test_returns_none_for_non_devflow_team_dir(self):
+ team_dir = Path("/tmp/.codebuddy/teams/some-other-team")
+ self.assertIsNone(devflow.task_slug_from_team_dir(team_dir))
+
+
+class StageSnapshotTests(unittest.TestCase):
+ def test_projects_expected_fields_and_ignores_non_dict_stage(self):
+ workflow_state = {
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "run_mode": "auto",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0, "review_result": None},
+ "CODE-REVIEW": {"status": "failed", "executor": "code-reviewer", "retry_count": 1, "review_result": "failed"},
+ "garbage": "not-a-dict",
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["current_stage"], "TASK-03")
+ self.assertEqual(snap["size_class"], "medium")
+ self.assertNotIn("garbage", snap["stages"])
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["retry_count"], 1)
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["review_result"], "failed")
+
+ def test_handles_missing_or_malformed_input(self):
+ self.assertEqual(devflow.stage_snapshot(None), {})
+ self.assertEqual(devflow.stage_snapshot({"stages": "not-a-dict"}), {
+ "current_stage": None, "size_class": None, "run_mode": None,
+ "schema_version": None, "execution_mode": None, "host_adapter": None, "run_id": None,
+ "stages": {},
+ })
+
+
+class DiffStageChangesTests(unittest.TestCase):
+ def test_first_observation_produces_no_changes(self):
+ curr = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(None, curr), [])
+
+ def test_detects_retry_count_increase_as_a_change(self):
+ prev = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "in_progress", "retry_count": 0}}})
+ curr = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "failed", "retry_count": 1, "review_result": "failed"}}})
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "CODE-REVIEW")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["review_result"], "failed")
+
+ def test_unchanged_stage_produces_no_entry(self):
+ snap = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(snap, snap), [])
+
+
+class PtIdFromTranscriptPathTests(unittest.TestCase):
+ def test_extracts_pt_track_from_subagent_transcript_name(self):
+ path = "/tmp/session-123/subagents/sub-developer-PT-01.jsonl"
+ self.assertEqual(agent_identity.pt_id_from_transcript_path(path), "PT-01")
+
+ def test_returns_none_for_non_subagent_or_non_pt_transcript(self):
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123.jsonl"))
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123/subagents/architect.jsonl"))
+
+
+class ResolveAndDiffTests(unittest.TestCase):
+ def test_returns_none_when_no_devflow_team_found(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ result = devflow.resolve_and_diff(state_path, "sid-1", "/tmp/some-project")
+ self.assertIsNone(result)
+ state = st.load_state(state_path)
+ self.assertIsNone(state["sid-1"]["_devflow"]["context"])
+
+ def test_late_appearing_devflow_run_is_discovered_on_a_later_call(self):
+ """真实 bug 回归测试:同一个长生命周期 sid,会话开始时探测不到 devflow
+ (此时既没有 team 目录也没有 artifacts/),之后才真正跑起 devflow
+ (比如通过 Agent 工具后台 spawn,而不是从一开始就是独立 team 成员 sid)。
+ 早期的"没找到"不能被永久缓存,必须在 artifacts/ 出现之后的下一次调用里发现它。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ project_dir.mkdir()
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-long-lived"
+
+ # 会话早期:还没有任何 devflow 痕迹。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNone(first)
+
+ # 同一个 sid,会话中途才出现 devflow 产物(没有 team 目录,走 artifacts 扫描兜底)。
+ artifacts_dir = project_dir / "artifacts" / "late-appearing-task_20260914_1200"
+ artifacts_dir.mkdir(parents=True)
+ (artifacts_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "current_stage": "SOLO", "size_class": "small",
+ "stages": {"SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(second)
+ self.assertEqual(second["task_slug"], "late-appearing-task_20260914_1200")
+
+ def test_end_to_end_with_fake_team_and_workflow_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ project_dir = root / "project"
+ project_dir.mkdir()
+ config_home = root / "codebuddy-home"
+ teams_root = config_home / "teams"
+ team_dir = teams_root / "multi-agents-devflow-fix-token-bypass_20260911_0900"
+ _write_team_config(team_dir, lead_session_id="sid-42", member_cwd=str(project_dir))
+
+ artifacts_dir = project_dir / "artifacts" / "fix-token-bypass_20260911_0900"
+ artifacts_dir.mkdir(parents=True)
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(config_home)
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-42"
+
+ # 第一次调用:发现 devflow 上下文,但因为是首次观测不产出 changes。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "fix-token-bypass_20260911_0900")
+ self.assertEqual(first["current_stage"], "TASK-03")
+ self.assertEqual(first["changes"], [])
+
+ # workflow-state.json 更新:TASK-03 打回重试。
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "failed", "executor": "developer", "retry_count": 1},
+ },
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["stage"], "TASK-03")
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+
+ # 没有变化时,第三次调用应该不再产出 changes。
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["changes"], [])
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+class PortableSchemaStageSnapshotTests(unittest.TestCase):
+ """Portable(v2.0)用 `executor_role` 而不是 `executor`,且没有 `review_result`。"""
+
+ def test_reads_executor_role_and_top_level_execution_context(self):
+ workflow_state = {
+ "version": "2.0",
+ "current_stage": "IMPLEMENT",
+ "size_class": "medium",
+ "execution_mode": "isolated",
+ "host_adapter": "codebuddy",
+ "run_id": "run-abc",
+ "stages": {
+ "DESIGN": {"status": "completed", "executor_role": "devflow-architect", "retry_count": 0},
+ "IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1},
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["schema_version"], "2.0")
+ self.assertEqual(snap["execution_mode"], "isolated")
+ self.assertEqual(snap["stages"]["DESIGN"]["executor"], "devflow-architect")
+ self.assertEqual(snap["stages"]["IMPLEMENT"]["retry_count"], 1)
+ self.assertIsNone(snap["stages"]["IMPLEMENT"]["review_result"])
+
+ def test_diff_detects_retry_on_portable_shape_same_as_classic(self):
+ prev = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "in_progress", "executor_role": "devflow-developer", "retry_count": 0}},
+ })
+ curr = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1}},
+ })
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "IMPLEMENT")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["executor"], "devflow-developer")
+
+
+class ArtifactsScanFallbackTests(unittest.TestCase):
+ """`topology: spawn` 宿主没有 team 目录,靠扫 artifacts/ 兜底发现 task_slug。"""
+
+ def test_no_artifacts_dir_returns_none(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.assertIsNone(devflow._scan_artifacts_for_active_run(td))
+
+ def test_ignores_non_devflow_json_and_picks_in_progress_run(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ # 不是 devflow 产物的 JSON(没有 stages 字段),不能被误当成一次运行。
+ noise_dir = artifacts / "not-a-devflow-run"
+ noise_dir.mkdir(parents=True)
+ (noise_dir / "workflow-state.json").write_text(json.dumps({"hello": "world"}), encoding="utf-8")
+
+ done_dir = artifacts / "finished-task_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "completed", "stages": {"DESIGN": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "active-task_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "in_progress", "stages": {"IMPLEMENT": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "active-task_20260911_1000")
+ self.assertIsNone(result["team_dir"])
+
+ def test_finished_detection_works_for_classic_schema_without_top_level_status(self):
+ """Classic(v1.3)没有顶层 status 字段,"跑完没跑完"只能看 last_event。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ done_dir = artifacts / "classic-done_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed",
+ "stages": {"SOLO": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "classic-active_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "TASK-02_completed",
+ "stages": {"TASK-02": {"status": "completed"}, "TASK-03": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "classic-active_20260911_1000")
+
+ def test_resolve_and_diff_switches_task_slug_when_a_newer_run_appears(self):
+ """真实 bug 回归测试:同一个长生命周期 sid 先后归属两次不同的 devflow 运行
+ (没有真正 team_create 时的降级场景——第二次 `/start-devflow` 复用了同一个
+ session)。第一次探测缓存下的 task_slug 不能在第二次运行开始后继续沿用;
+ 必须切换到新的那个,而且两个 task_slug 各自的 diff 历史不能互相污染。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-reused-across-two-runs"
+
+ first_dir = project_dir / "artifacts" / "first-task_20260914_0900"
+ first_dir.mkdir(parents=True)
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(first["task_slug"], "first-task_20260914_0900")
+
+ # 同一个 sid,第二次运行出现,且比第一次更新(mtime 更新)。
+ import time
+ time.sleep(0.01)
+ second_dir = project_dir / "artifacts" / "second-task_20260914_1100"
+ second_dir.mkdir(parents=True)
+ (second_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(second["task_slug"], "second-task_20260914_1100")
+ self.assertEqual(second["changes"], []) # 对 second 是首次观测,不产出变更
+
+ # 第一个 task_slug 的历史没有被污染:如果它重新变成"最新"(比如被再次修改),
+ # 应该正确切回,并且不会把 second 的历史错当成 first 的基线。
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+ time.sleep(0.01)
+ first_dir.joinpath("workflow-state.json").touch()
+
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["task_slug"], "first-task_20260914_0900")
+ # first 上一次被观测到时 retry_count 还是 0,现在变成 1——应该被识别为变化,
+ # 而不是被 second 的快照历史污染成"首次观测"或者对不上的 diff。
+ self.assertEqual(len(third["changes"]), 1)
+ self.assertEqual(third["changes"][0]["retry_count"], 1)
+
+ def test_resolve_and_diff_end_to_end_via_artifacts_scan_no_team(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ artifacts_dir = project_dir / "artifacts" / "portable-task_20260911_1100"
+ artifacts_dir.mkdir(parents=True)
+ state_file = artifacts_dir / "workflow-state.json"
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "in_progress", "executor_role": "devflow-code-reviewer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(Path(td) / "empty-codebuddy-home")
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-spawn-1"
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "portable-task_20260911_1100")
+ self.assertEqual(first["schema_version"], "2.0")
+ self.assertEqual(first["execution_mode"], "isolated")
+ self.assertEqual(first["changes"], [])
+
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "failed", "executor_role": "devflow-code-reviewer", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.codebuddy/skills/agent-observability/tests/test_pricing_overrides.py b/.codebuddy/skills/agent-observability/tests/test_pricing_overrides.py
new file mode 100644
index 00000000..75615a36
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_pricing_overrides.py
@@ -0,0 +1,394 @@
+"""自定义模型定价覆盖 + 看板未定价模型提示。
+
+覆盖文件是**人手写的常驻配置**,而且加载失败要静默降级——这类"错了也不许
+报错"的代码最容易在半年后被悄悄改坏(比如有人顺手把 try/except 去掉、把合并
+改成整 key 覆盖、或让降级路径开始 print)。这里把字段级合并、四种/五种降级
+路径、缓存语义、未定价口径、看板聚合与"不重算历史成本"逐条钉住。
+
+两个容易踩的隔离坑,本文件统一在 setUp/tearDown 处理:
+1. `load_prices()` 带 `lru_cache`,不 `clear_price_cache()` 用例之间会串味;
+2. `AOBS_PRICING_OVERRIDES_PATH` 是进程级环境变量,不还原会污染同进程里
+ 其它测试模块(尤其是会真的去读默认覆盖文件的 hook 链路)。
+
+真实日志对账(hy4-preview-ioa / hy3-ioa 的计数)不写进单测:日志会持续增长,
+写死数字会变成 flaky 用例。那部分以人工冒烟的方式在 TASK-04 报告里记录。
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+from core import emitter # type: ignore
+
+OVERRIDES_ENV = "AOBS_PRICING_OVERRIDES_PATH"
+
+
+class _OverridesTestCase(unittest.TestCase):
+ """统一处理环境变量与 `load_prices()` 缓存的隔离。"""
+
+ def setUp(self):
+ self._env_backup = os.environ.get(OVERRIDES_ENV)
+ os.environ.pop(OVERRIDES_ENV, None)
+ emitter.clear_price_cache()
+ self._tmp = tempfile.TemporaryDirectory()
+ self.tmp = Path(self._tmp.name)
+
+ def tearDown(self):
+ # 顺序要紧:先还原 env,再清缓存,最后清目录,避免留下一个指向已删除
+ # 目录的环境变量给下一个用例。
+ if self._env_backup is None:
+ os.environ.pop(OVERRIDES_ENV, None)
+ else:
+ os.environ[OVERRIDES_ENV] = self._env_backup
+ emitter.clear_price_cache()
+ self._tmp.cleanup()
+
+ def use_overrides(self, payload, name: str = "overrides.json") -> Path:
+ """把 payload 写成覆盖文件并指向它(JSON 文本原样写入,便于构造非法输入)。"""
+ path = self.tmp / name
+ text = payload if isinstance(payload, str) else json.dumps(payload)
+ path.write_text(text, encoding="utf-8")
+ os.environ[OVERRIDES_ENV] = str(path)
+ emitter.clear_price_cache()
+ return path
+
+ def pure_builtin(self) -> dict:
+ """"纯内置表"的唯一权威来源——不把 pricing.json 的内容抄进断言里,
+ 否则内置表一调整这里就假红;但内置表本身必须是非空的,否则下面的
+ "降级后 == 纯内置表" 断言会退化成空表比空表。"""
+ builtin = emitter._load_builtin_prices()
+ self.assertTrue(builtin, "内置价格表不应为空,否则降级断言失去意义")
+ self.assertIn("gpt-4o", builtin)
+ return builtin
+
+
+class OverridesPathResolutionTests(_OverridesTestCase):
+ """AC4:路径可覆盖。默认位置刻意放在 skills 树**外**——
+ `scripts/build-classic-hosts.py` 会整棵同步 `.codebuddy/skills`,放树内会让
+ 用户每次改价都产生一次 `--check` drift,并被复制进 .claude/.cursor 宿主包。"""
+
+ def test_env_var_wins_over_default(self):
+ path = self.use_overrides({"zz-model": {"output": 1.0}})
+ self.assertEqual(emitter.resolve_overrides_path(), path)
+
+ def test_tilde_is_expanded(self):
+ os.environ[OVERRIDES_ENV] = "~/aobs-overrides-test.json"
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), Path.home() / "aobs-overrides-test.json")
+
+ def test_unset_falls_back_to_default_path(self):
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_blank_env_falls_back_to_default(self):
+ # 空字符串/纯空白都等同于"没设置",不能变成指向 CWD 的相对路径。
+ os.environ[OVERRIDES_ENV] = " "
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_default_path_is_outside_the_skills_tree(self):
+ default = emitter.DEFAULT_OVERRIDES_PATH
+ self.assertIsNotNone(default)
+ self.assertEqual(
+ default,
+ ROOT.parents[2] / ".codebuddy" / "agent-observability" / "pricing.overrides.json",
+ )
+ self.assertNotIn("skills", default.parts[-3:])
+ self.assertFalse(str(default).startswith(str(ROOT)))
+
+
+class MergePricesTests(unittest.TestCase):
+ """AC2:字段级合并。整 key 覆盖被刻意否决过——漏写字段会把该字段按 0 计,
+ 静默把成本算没,风险高于收益。"""
+
+ def test_explicit_field_overrides_builtin_while_others_are_kept(self):
+ merged = emitter.merge_prices(
+ {"gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25}},
+ {"gpt-4o": {"output": 99.0}},
+ )
+ self.assertEqual(merged["gpt-4o"]["output"], 99.0)
+ self.assertEqual(merged["gpt-4o"]["input"], 2.5)
+ self.assertEqual(merged["gpt-4o"]["cache_read"], 1.25)
+
+ def test_new_model_can_be_added(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-new": {"output": 9.0}})
+ self.assertEqual(merged["zz-new"], {"output": 9.0})
+
+ def test_merge_does_not_mutate_its_arguments(self):
+ base = {"gpt-4o": {"input": 2.5, "output": 10.0}}
+ overrides = {"gpt-4o": {"output": 99.0}}
+ merged = emitter.merge_prices(base, overrides)
+ merged["gpt-4o"]["input"] = 0.0
+ # 内置表是模块级共享数据(lru_cache 之外还有调用方持有引用),
+ # 被就地改过的话一次合并会污染整条 hook 链路。
+ self.assertEqual(base["gpt-4o"], {"input": 2.5, "output": 10.0})
+ self.assertEqual(overrides["gpt-4o"], {"output": 99.0})
+
+ def test_empty_or_none_overrides_return_base_copy(self):
+ base = {"gpt-4o": {"output": 10.0}}
+ self.assertEqual(emitter.merge_prices(base, None), base)
+ self.assertEqual(emitter.merge_prices(base, {}), base)
+
+ def test_none_base_returns_overrides_only(self):
+ self.assertEqual(emitter.merge_prices(None, {"zz-new": {"output": 1.0}}), {"zz-new": {"output": 1.0}})
+
+ def test_non_dict_rows_are_ignored(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-bad": 9.0, "zz-ok": {"output": 2.0}})
+ self.assertNotIn("zz-bad", merged)
+ self.assertEqual(merged["zz-ok"], {"output": 2.0})
+
+
+class LoadPricesOverrideTests(_OverridesTestCase):
+ """AC2 + AC3:加载与降级。"""
+
+ def test_override_applies_field_level_and_adds_model(self):
+ self.use_overrides({"zz-custom": {"input": 1.0, "output": 9.0}, "gpt-4o": {"output": 99.0}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["zz-custom"], {"input": 1.0, "output": 9.0})
+ self.assertEqual(prices["gpt-4o"]["output"], 99.0)
+ self.assertEqual(prices["gpt-4o"]["input"], self.pure_builtin()["gpt-4o"]["input"])
+
+ def test_missing_file_degrades_to_builtin(self):
+ os.environ[OVERRIDES_ENV] = str(self.tmp / "does-not-exist.json")
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_invalid_json_degrades_to_builtin(self):
+ self.use_overrides('{"gpt-4o": {"output": 99.0}')
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_top_level_non_dict_degrades_to_builtin(self):
+ self.use_overrides("[1, 2, 3]")
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_non_numeric_field_is_skipped_but_siblings_apply(self):
+ self.use_overrides({"gpt-4o": {"output": "abc", "input": 3.0}})
+ prices = emitter.load_prices()
+ # 写错一个字段不该把同模型其它字段、其它模型的正确覆盖一起丢掉。
+ self.assertEqual(prices["gpt-4o"]["input"], 3.0)
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_model_with_only_bad_fields_is_dropped_and_stays_unpriced(self):
+ """计划外决策(已在 code review 接受):全坏字段的模型不落表。
+ 若落表成 `{}`,它既算不出成本又不算"未定价",看板上会变成一个查不到
+ 原因的空洞;丢弃后至少能在"模型定价"提醒里暴露出来。"""
+ self.use_overrides({"zz-all-bad": {"output": "abc"}})
+ prices = emitter.load_prices()
+ self.assertNotIn("zz-all-bad", prices)
+ self.assertTrue(emitter.is_unpriced("zz-all-bad"))
+
+ def test_bool_is_not_treated_as_a_price(self):
+ # bool 是 int 的子类,float(True) == 1.0 会静默变成"单价 1 美元"。
+ self.use_overrides({"gpt-4o": {"output": True}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_every_degradation_path_is_silent(self):
+ """静默是刻意的:hook 每次都是新进程,一旦因格式问题 print/抛异常,
+ 整条 hook 链路都会变得不可用。"""
+ for payload in ('{"broken": ', "[1,2,3]", '{"gpt-4o": {"output": "abc"}}', '{"gpt-4o": 1}'):
+ with self.subTest(payload=payload):
+ self.use_overrides(payload)
+ out, err = io.StringIO(), io.StringIO()
+ with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+ prices = emitter.load_prices()
+ self.assertEqual(prices, self.pure_builtin())
+ self.assertEqual(out.getvalue(), "")
+ self.assertEqual(err.getvalue(), "")
+
+ def test_load_prices_is_cached_until_cleared(self):
+ path = self.use_overrides({"zz-cache-model": {"output": 1.0}})
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ path.write_text(json.dumps({"zz-cache-model": {"output": 2.0}}), encoding="utf-8")
+ # 未清缓存:同进程内仍是旧值(hook 是短命进程,这个行为是可接受的)。
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 2.0)
+
+ def test_clear_price_cache_picks_up_env_change(self):
+ self.assertTrue(hasattr(emitter.load_prices, "cache_clear"))
+ self.use_overrides({"zz-a": {"output": 1.0}})
+ self.assertIn("zz-a", emitter.load_prices())
+ self.use_overrides({"zz-b": {"output": 2.0}}, name="second.json")
+ emitter.clear_price_cache()
+ prices = emitter.load_prices()
+ self.assertIn("zz-b", prices)
+ self.assertNotIn("zz-a", prices)
+
+
+class IsUnpricedTests(_OverridesTestCase):
+ """D4:未定价的唯一口径是 `lookup_price(...) is None`。
+ `lookup_price` 会做"最长子串"模糊兜底,所以 `gpt-4o-2024-11-20` 能算出成本,
+ 不该出现在"建议补价"里——口径一旦漂移,用户会去给明明已经命中的模型补价。"""
+
+ def test_unknown_model_is_unpriced(self):
+ self.assertTrue(emitter.is_unpriced("zz-totally-unknown"))
+
+ def test_fuzzy_substring_match_is_not_unpriced(self):
+ self.assertFalse(emitter.is_unpriced("gpt-4o-2024-11-20"))
+
+ def test_missing_or_blank_model_is_unpriced(self):
+ for model in (None, "", " "):
+ with self.subTest(model=model):
+ self.assertTrue(emitter.is_unpriced(model))
+
+ def test_override_makes_a_model_priced(self):
+ self.assertTrue(emitter.is_unpriced("zz-then-priced"))
+ self.use_overrides({"zz-then-priced": {"output": 9.0}})
+ self.assertFalse(emitter.is_unpriced("zz-then-priced"))
+
+
+class BuildUnpricedModelsTests(_OverridesTestCase):
+ """AC5:只看板**统计**,绝不回头重算 cost_usd(D3:覆盖只对新事件生效)。"""
+
+ def _usage(self, model, ts=1.0):
+ return {"event": "usage", "sid": "s1", "ts": ts, "model": model, "tokens": {"input": 1, "output": 1}}
+
+ def test_counts_only_unpriced_usage_events(self):
+ events = [
+ self._usage("zz-unpriced-a", 1.0),
+ self._usage("zz-unpriced-a", 2.0),
+ self._usage("zz-unpriced-b", 3.0),
+ self._usage("gpt-4o-2024-11-20", 4.0), # 模糊命中,不算未定价
+ {"event": "usage", "sid": "s1", "ts": 5.0, "tokens": {"input": 1}}, # model 缺失
+ self._usage(" ", 6.0), # model 空白
+ {"event": "tool", "sid": "s1", "ts": 7.0, "tool": "Bash", "ms": 1}, # 非 usage
+ ]
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [
+ {"name": "zz-unpriced-a", "usageEvents": 2},
+ {"name": "zz-unpriced-b", "usageEvents": 1},
+ ])
+
+ def test_empty_input_returns_empty_list(self):
+ self.assertEqual(bdd.build_unpriced_models([]), [])
+
+ def test_sorted_by_event_count_desc_then_name(self):
+ events = (
+ [self._usage("zz-b", float(i)) for i in range(2)]
+ + [self._usage("zz-a", 9.0)]
+ + [self._usage("zz-c", float(i)) for i in range(2)]
+ )
+ rows = bdd.build_unpriced_models(events)
+ # 计数相同的 zz-b / zz-c 必须按名字定序,否则两次生成的快照无法逐字节比对。
+ self.assertEqual([(r["name"], r["usageEvents"]) for r in rows],
+ [("zz-b", 2), ("zz-c", 2), ("zz-a", 1)])
+
+ def test_pricing_a_model_removes_it_from_the_list(self):
+ events = [self._usage("zz-unpriced-a", 1.0), self._usage("zz-unpriced-b", 2.0)]
+ self.assertEqual(len(bdd.build_unpriced_models(events)), 2)
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [{"name": "zz-unpriced-b", "usageEvents": 1}])
+
+ def test_emitter_import_failure_degrades_to_empty_list(self):
+ """目标机可能没装 emitter 的间接依赖;此时只该退化"未定价"这一项,
+ 看板仍要能出片。"""
+ with mock.patch.object(bdd, "em", None):
+ self.assertEqual(bdd.build_unpriced_models([self._usage("zz-unpriced-a")]), [])
+
+
+class MainSnapshotTests(_OverridesTestCase):
+ """main() 级别:键位、空列表、不重算成本、无覆盖时与改动前一致(AC1)。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 2.0, "model": "gpt-4o-2024-11-20",
+ "tokens": {"input": 100, "output": 10}, "cost_usd": 0.0035, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ ]
+
+ def _run_main(self, root: Path, out_name: str) -> tuple[dict, str]:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text("\n".join(json.dumps(e) for e in self._events()) + "\n", encoding="utf-8")
+ state = root / ".state.json"
+ state.write_text("{}", encoding="utf-8")
+ out = root / out_name
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py", "--project-root", str(root),
+ "--out", str(out), "--metrics-path", str(metrics), "--state-path", str(state)]
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ self.assertIn("wrote ", buf.getvalue())
+ return json.loads(out.read_text("utf-8")), buf.getvalue()
+
+ def test_snapshot_exposes_unpriced_models_right_after_model_costs(self):
+ with tempfile.TemporaryDirectory() as td:
+ data, _ = self._run_main(Path(td), "out.json")
+ keys = list(data.keys())
+ self.assertEqual(keys[keys.index("modelCosts") + 1], "unpricedModels")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual([m["name"] for m in data["modelCosts"]], ["gpt-4o-2024-11-20"])
+
+ def test_no_unpriced_models_yields_empty_list_not_null(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ data, _ = self._run_main(Path(td), "out.json")
+ self.assertEqual(data["unpricedModels"], [])
+
+ def test_override_never_recomputes_already_written_costs(self):
+ """D3 的回归护栏:给未定价模型补价后,只有 unpricedModels 会变,
+ modelCosts / daily / sessions 必须逐字节不变(历史成本不回溯)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ before, _ = self._run_main(root, "before.json")
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ after, _ = self._run_main(root, "after.json")
+ before.pop("generated_at")
+ after.pop("generated_at")
+ self.assertEqual(before["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual(after["unpricedModels"], [])
+ before.pop("unpricedModels")
+ after.pop("unpricedModels")
+ self.assertEqual(before, after)
+
+ def test_broken_override_file_keeps_cli_at_exit_zero_and_silent(self):
+ """AC3 的 CLI 层护栏:覆盖文件坏掉时看板仍然出片(exit 0、stderr 为空),
+ 而不是把整条构建链路搞挂。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self.use_overrides('{"gpt-4o": {"output": 99.0}') # 故意截断的非法 JSON
+ err = io.StringIO()
+ with contextlib.redirect_stderr(err):
+ data, _ = self._run_main(root, "out.json")
+ self.assertEqual(err.getvalue(), "")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+ def test_no_override_file_matches_nonexistent_override_path(self):
+ """AC1 的核心回归:不传覆盖文件时价格表就是纯内置表,
+ 与"指向一个不存在的路径"的输出完全一致(忽略 generated_at)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ unset, _ = self._run_main(root, "unset.json")
+ os.environ[OVERRIDES_ENV] = str(root / "nope.json")
+ emitter.clear_price_cache()
+ missing, _ = self._run_main(root, "missing.json")
+ unset.pop("generated_at")
+ missing.pop("generated_at")
+ self.assertEqual(unset, missing)
+ self.assertEqual(unset["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.codebuddy/skills/agent-observability/tests/test_runtime_flow.py b/.codebuddy/skills/agent-observability/tests/test_runtime_flow.py
new file mode 100644
index 00000000..7bd143ba
--- /dev/null
+++ b/.codebuddy/skills/agent-observability/tests/test_runtime_flow.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import runtime # type: ignore
+
+
+class RuntimeFlowTests(unittest.TestCase):
+ def test_resolve_active_agent_prefers_inbox_inferred_agent_when_available(self):
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ with mock.patch.object(runtime.agent_identity, "merge_agent_identity_from_inbox", return_value=("qa", "developer")) as merge_identity:
+ active, dispatched = runtime.agent_identity.resolve_active_agent_for_event(
+ state_path=state_path,
+ sid="s-inbox",
+ cwd=td,
+ data=data,
+ )
+
+ self.assertEqual(active, "qa")
+ self.assertEqual(dispatched, "developer")
+ merge_identity.assert_called_once()
+
+ def test_handle_post_routes_through_expected_collaborators(self):
+ data = {
+ "session_id": "s-runtime",
+ "cwd": "/tmp/demo",
+ "tool_name": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ with tempfile.TemporaryDirectory() as td:
+ with mock.patch.object(runtime, "build_runtime_paths") as mock_paths, \
+ mock.patch.object(runtime.collector, "record_post", return_value=12), \
+ mock.patch.object(runtime.collector, "load_cached_inventory", return_value=({}, {})), \
+ mock.patch.object(runtime.scanner, "scan_skills_and_rules", return_value=({}, {})), \
+ mock.patch.object(runtime.collector, "cache_inventory"), \
+ mock.patch.object(runtime.collector, "record_tool_usage", return_value=([], [])), \
+ mock.patch.object(runtime.agent_identity, "resolve_active_agent_for_event", return_value=("main", None)), \
+ mock.patch.object(runtime, "current_turn_id", return_value="turn-1"), \
+ mock.patch.object(runtime.collector, "extract_tool_call_id", return_value=None), \
+ mock.patch.object(runtime, "flush_pending_tool_events"), \
+ mock.patch.object(runtime.collector, "find_current_tool_context", return_value=None), \
+ mock.patch.object(runtime.collector, "related_transcript_paths", return_value=["/tmp/demo.jsonl"]), \
+ mock.patch.object(runtime, "emit_transcript_events", return_value=[]), \
+ mock.patch.object(runtime.collector, "find_fallback_usage_event", return_value=None), \
+ mock.patch.object(runtime.st, "append_pending_tool_emit"), \
+ mock.patch.object(runtime.agentlens, "emit_post_step"):
+ mock_paths.return_value = runtime.RuntimePaths(
+ base_dir=Path(td),
+ state_path=Path(td) / ".state.json",
+ pending_path=Path(td) / ".pending.json",
+ log_path=Path(td) / "metrics.ndjson",
+ )
+ runtime.handle_post(data)
+
+ def test_main_dispatches_supported_phase_to_handler(self):
+ with mock.patch.object(runtime, "handle_post") as handle_post, \
+ mock.patch.object(runtime.collector, "read_stdin_json", return_value={"session_id": "s1"}):
+ rc = runtime.main(["post"])
+ self.assertEqual(rc, 0)
+ handle_post.assert_called_once()
diff --git a/.cursor/skills/agent-observability/SKILL.md b/.cursor/skills/agent-observability/SKILL.md
new file mode 100644
index 00000000..8bff9f0c
--- /dev/null
+++ b/.cursor/skills/agent-observability/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: agent-observability
+description: Add or maintain CodeBuddy hook observability for projects that need local metrics for tool latency, transcript token usage, session cost, and multi-agent trace attribution. Use when wiring hook-based telemetry, debugging missing usage events, and validating AgentLens state.
+---
+
+## Workflow
+
+1. Merge `templates/settings-hook.json` into the user or project `settings.json`.
+2. Keep hook entries command-only and keep timeouts around 5 to 10 seconds.
+3. Run a normal CodeBuddy session and inspect `logs/metrics.ndjson`.
+4. Inspect `logs/.state.json` when usage replay, offsets, or AgentLens turn state look wrong.
+5. Keep the runtime generic and verify output from `metrics.ndjson` and `.state.json`.
+
+## Read Next
+
+- Read `references/quickstart.md` for setup and smoke-test steps.
+- Read `references/schema-v2.md` when you need field definitions or sidecar state shape.
+## Key Files
+
+- `scripts/main.py`: hook entrypoint for `session-start`, `user-prompt-submit`, `pre`, `post`, and `stop`
+- `scripts/run_hook.sh`: stable shell wrapper for CodeBuddy hook commands
+- `scripts/core/collector.py`: transcript parsing, pre/post pairing, and session usage recording
+- `scripts/core/agentlens.py`: AgentLens trace emission and agent or step grouping
+- `scripts/core/state.py`: persisted hook state, offsets, and AgentLens sidecar state
+- `scripts/core/devflow.py`: optional devflow-awareness — detects a `multi-agents-devflow-*` team, reads `workflow-state.json`, and emits `stage_transition` events. No-ops entirely on non-devflow projects.
+- `templates/settings-hook.json`: hook wiring template
+
+## Output Contract
+
+- Always emit `event`, `sid`, and `ts`.
+- Emit `tool` for per-call latency and `usage` for transcript-derived token and cost events.
+- Emit `stop` for end-of-session flush.
+- Never block the main hook flow; hook exits must stay `0`.
diff --git a/.cursor/skills/agent-observability/config/pricing.json b/.cursor/skills/agent-observability/config/pricing.json
new file mode 100644
index 00000000..59d8e58c
--- /dev/null
+++ b/.cursor/skills/agent-observability/config/pricing.json
@@ -0,0 +1,39 @@
+{
+ "claude-opus-4.8": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.7": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4.6": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-opus-4": {"input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25},
+ "claude-sonnet-4.6": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4.5": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-sonnet-4": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-7-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-3-5-sonnet": {"input": 3.0, "output": 15.0, "cache_read": 0.3, "cache_write": 3.75},
+ "claude-haiku-4.5": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-3-5-haiku": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "claude-haiku-4": {"input": 1.0, "output": 5.0, "cache_read": 0.1, "cache_write": 1.25},
+ "gpt-5.5-fast": {"input": 12.5, "output": 75.0, "cache_read": 1.25, "cache_write": 12.5},
+ "gpt-5.5": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4-fast": {"input": 5.0, "output": 30.0, "cache_read": 0.5, "cache_write": 5.0},
+ "gpt-5.4": {"input": 2.5, "output": 15.0, "cache_read": 0.25, "cache_write": 2.5},
+ "gpt-5.3-codex": {"input": 1.75, "output": 14.0, "cache_read": 0.175, "cache_write": 1.75},
+ "gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25, "cache_write": 2.5},
+ "gpt-4o-mini": {"input": 0.15, "output": 0.6, "cache_read": 0.075, "cache_write": 0.15},
+ "gemini-3.5-flash": {"input": 1.5, "output": 9.0, "cache_read": 0.15, "cache_write": 1.5},
+ "gemini-3.1-pro": {"input": 2.0, "output": 12.0, "cache_read": 0.2, "cache_write": 2.0},
+ "gemini-3.1-flash-lite": {"input": 0.25, "output": 1.5, "cache_read": 0.025, "cache_write": 0.25},
+ "gemini-3-flash": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "gemini-2": {"input": 0.5, "output": 3.0, "cache_read": 0.05, "cache_write": 0.5},
+ "glm-5.1": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "glm-5v-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5-turbo": {"input": 0.714, "output": 3.143, "cache_read": 0.171, "cache_write": 0.714},
+ "glm-5": {"input": 0.857, "output": 3.429, "cache_read": 0.186, "cache_write": 0.857},
+ "kimi-k2.6": {"input": 0.929, "output": 3.857, "cache_read": 0.157, "cache_write": 0.929},
+ "kimi-k2.5": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "kimi": {"input": 0.571, "output": 3.0, "cache_read": 0.1, "cache_write": 0.571},
+ "deepseek-v4-pro": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek-v4-flash": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "deepseek-v4": {"input": 0.429, "output": 0.857, "cache_read": 0.004, "cache_write": 0.429},
+ "deepseek": {"input": 0.143, "output": 0.286, "cache_read": 0.003, "cache_write": 0.143},
+ "minimax-m2.7": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3},
+ "minimax": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.3}
+}
diff --git a/.cursor/skills/agent-observability/logs/.gitkeep b/.cursor/skills/agent-observability/logs/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/.cursor/skills/agent-observability/references/quickstart.md b/.cursor/skills/agent-observability/references/quickstart.md
new file mode 100644
index 00000000..7a30ef68
--- /dev/null
+++ b/.cursor/skills/agent-observability/references/quickstart.md
@@ -0,0 +1,195 @@
+## Quickstart
+
+### 安装
+
+将 `templates/settings-hook.json` 合并到 `~/.cursor/settings.json` 或 `<project>/.cursor/settings.json`。
+
+必须启用 hooks:`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`。
+
+### 查看输出
+
+完成一次正常会话后检查:
+- `.cursor/skills/agent-observability/logs/metrics.ndjson`
+- `.cursor/skills/agent-observability/logs/.state.json`
+
+### 指定数据源路径(可选)
+
+`build_dashboard_data.py` 默认从 `<skill_root>/logs/metrics.ndjson` 与 `<skill_root>/logs/.state.json` 读取,**不传参数时行为完全不变**。
+
+如需从其它位置读取,可用 `--metrics-path` / `--state-path` 覆盖:
+
+```bash
+python3 scripts/build_dashboard_data.py \
+ --metrics-path ~/Downloads/metrics.ndjson \
+ --state-path ~/Downloads/.state.json \
+ --out dashboard/dashboard-data.json
+```
+
+注意:
+
+- 两个参数都留空(或省略)时回退到 `<skill_root>/logs/` 下的默认文件。
+- 路径支持 `~` 展开(如上例的 `~/Downloads/...`)。
+- 输出 `dashboard-data.json` 的 `source.metrics_ndjson` / `source.state_json` 会**如实反映实际读取到的路径**,覆盖后自然指向你给定的文件,便于核对数据来源。
+
+重点字段:
+- `event=tool`:工具耗时、`skill`、`rule`
+- `event=usage`:`tokens`、`model`、`cost_usd`
+- `event=stop`:会话尾部 flush 与总成本
+
+### 导出最慢的工具调用(可选)
+
+`--top-slow N` 会在生成 `dashboard-data.json` 的同时,额外在**终端**打印耗时最长的 N 次 `event=tool` 调用(工具名 + 耗时 ms,按耗时降序)。排查"哪次工具调用拖慢了会话"时不用再去翻原始 ndjson。
+
+```bash
+python3 scripts/build_dashboard_data.py --top-slow 5
+```
+
+输出示例(排在 `wrote ...` 之后):
+
+```
+top-slow 5 tool calls (by ms):
+ 1. Bash 4820ms
+ 2. Grep 1230ms
+ 3. Read 310ms
+```
+
+注意:
+
+- **默认不开启**:不传该参数时不会打印任何额外内容,原有输出一字不变。
+- **只读**:结果只打印到终端,不会写进 `dashboard-data.json`——输出结构与不开时完全一致,看板不受影响。
+- 只统计 `event=tool` 事件;`ms` 缺失或非数字时按 `0` 兜底,与看板其它统计口径一致。
+- `N` 大于实际 tool 事件数时取全部,不报错;没有任何 tool 事件时不打印该段。
+
+### 自定义模型定价覆盖(可选)
+
+内置价格表 `config/pricing.json` 覆盖不到的模型(自部署模型、内部代号、刚发布还没来得及收录的模型),
+`cost_usd` 会算不出来。给这些模型补单价不用改内置文件——写一份**只含差异**的覆盖文件即可。
+
+**放哪**:默认 `<project_root>/.cursor/agent-observability/pricing.overrides.json`
+(`<project_root>` 是 `.cursor/` 所在的那一层,例如 `/Users/me/my-project`)。
+
+刻意放在 `skills/` 树**之外**,原因有三:
+
+- `scripts/build-classic-hosts.py` 会整棵同步 `.cursor/skills` 到 `.claude/` `.cursor/`,
+ 放树内会让每次改动都产生 `--check` drift,还会把你的单价复制进生成的宿主包;
+- `config/pricing.json` 属于 skill 自带资产,后续更新会把它冲掉,覆盖文件不会;
+- 它是纯数据文件,删除或改名即可停用,不需要重启任何东西(hook 每次都是新进程)。
+
+**格式**:键是模型名(匹配时忽略大小写与首尾空格),值是要覆盖的字段。
+单位与 `config/pricing.json` 完全一致——**USD / 1M tokens**,可用字段只有四个:
+`input`、`output`、`cache_read`、`cache_write`。
+
+```json
+{
+ "my-model": { "output": 9.0 },
+ "gpt-4o": { "output": 99.0 }
+}
+```
+
+**合并是字段级的**:上面这份只改 `output`——`my-model` 的 `input`/`cache_read`/`cache_write`
+沿用内置值(内置表里没有 `my-model` 时,未覆盖的字段按 0 计),`gpt-4o` 的 `input` 仍是内置的 `2.5`。
+可以新增内置表里不存在的模型,但**不能删除**内置的模型或字段(合并只能加不能减)。
+
+**两个环境变量**(都支持 `~` 展开):
+
+| 环境变量 | 作用 | 优先级 |
+|---|---|---|
+| `AOBS_PRICES_PATH` | **替换**整张基础表(不再读内置 `config/pricing.json`) | 低 |
+| `AOBS_PRICING_OVERRIDES_PATH` | 在上面那张基础表之上**叠加**一份补丁,指向任意路径 | 高 |
+
+两者同时设置时,覆盖文件里的字段最终生效。
+
+> ⚠️ **只对新事件生效,不回溯**:`cost_usd` 在 hook 期就写进了 `metrics.ndjson`,
+> 补价之后只有**之后新产生**的 usage 事件按新价格计算,已经落盘的历史成本不会被重算。
+
+**出问题会静默降级**:覆盖文件不存在、JSON 非法、顶层不是对象、字段值不是数字,
+四种情况都自动退回纯内置价格表——不报错、不打印、hook 照常退出 0
+(否则一个手误的格式问题会让整条 hook 链路不可用)。所以"改了没生效"通常意味着文件没被读到,
+先跑一次诊断:
+
+```bash
+python3 - <<'PY'
+import sys
+sys.path.insert(0, "scripts")
+from core import emitter
+print("path :", emitter.resolve_overrides_path())
+print("loaded :", emitter.load_price_overrides())
+print("gpt-4o :", emitter.load_prices().get("gpt-4o"))
+PY
+```
+
+`path` 是实际读取的位置(不是你以为的那个),`loaded` 为空说明文件没读到或全被判为坏字段。
+
+**看板上的提示**:「建议关注」卡片第 4 条「模型定价」会列出**完全没命中价格表**的模型
+(模型名 + 缺少成本的 usage 事件数)。模糊匹配(最长子串)命中的模型能算出成本,不会出现在里面。
+处置方式就是把该模型写进覆盖文件;所有模型都有价时这条显示 green。
+
+### 常见问题
+
+- 没有日志:检查 hook 命令路径。
+- `ms` 为空:通常是 pre/post 未配对。
+- 没有 `usage`:`transcript_path` 缺失、tail 无 usage,或增量已去重。
+- AgentLens 未启用:检查 `.state.json` 的 `_agentlens.enabled` / `last_error`。
+
+### 已知问题(未修复)
+
+- **工具失败事件的 `raw_response` 经常缺失(PostToolUse 与 transcript 落盘之间的时序竞争)**:
+ 真实 CodeBuddy CLI 场景下实测复现过——一次会故意制造失败的 `Bash` 调用(`exitCode=1`,
+ transcript 里 `function_call_result.providerData.toolResult.rawResponse` 确实带了
+ `is_error:true`/`exitCode:1`/`tool_error_code`),但最终写进 `metrics.ndjson` 的
+ `tool` 事件的 `tool_details` 里完全没有 `raw_response` 字段。
+ 用实测时间戳定位到根因:PostToolUse hook 记录这次调用的时间是 `ts=...396.524`,
+ 但 transcript 里 `function_call_result` 真正落盘的时间是 `timestamp=...396.609`——
+ **晚了 85ms**。hook 触发时去扫 transcript 文件的那一刻,CLI 还没来得及把执行结果
+ 那条记录写盘,`find_current_tool_context()`(`core/collector.py`)只能看到
+ `function_call`(请求),看不到 `function_call_result`(结果)。已经单独验证过
+ `merge_tool_records()` / `tool_details_from_record()` 的合并逻辑本身没问题——
+ 只要数据真的已经在文件里,能正确解析出完整 `raw_response`;问题纯粹是读的时机
+ 比 CLI 写盘早了一步。`collect_transcript_entries()` 用的是持久化的增量字节 offset
+ 游标,错过这次窗口后不会在后续调用里回头补扫,所以这次机会永久丢失,直接后果是
+ `build_dashboard_data.py` 的 `tool_call_failed()`(无论怎么改判定逻辑)都拿不到
+ 数据,"工具失败率"/`failures` 列表对这类快速失败调用会漏检。
+ 复现方式:让 CodeBuddy 执行一个必然快速失败的命令(如 `ls /path/does/not/exist`,
+ 越快的命令越容易复现,因为 hook 触发与 transcript 落盘之间的竞争窗口更紧张),
+ 对比 `metrics.ndjson` 里该 `tool` 事件的 `tool_details.raw_response` 是否存在,
+ 和对应 transcript `.jsonl` 里 `function_call`/`function_call_result` 两条记录各自
+ 的 `timestamp` 先后。
+
+ **影响范围(已精确定位,不是猜测)**:`raw_response` 在 `build_dashboard_data.py`
+ 里只有两处消费者——`tool_call_failed()`(喂给 `build_daily_and_sessions()` 的
+ `day.failures` 计数和 `session.status`)和 `build_failures()`("工具失败面板"的
+ 数据源)。真实数据统计过:107 次 tool 事件里只有 2 次带 `raw_response`,且只有
+ `Bash` 调用会带这个字段(Read/Edit/Write/SendMessage 等其它工具从不带,不受
+ 此问题影响)。缺失时 `tool_call_failed()` 默认判"未失败",所以效果是**恒定
+ 漏报,不会误报**——工具失败率/失败面板/会话状态列显示的"正常"可能掩盖了真实
+ 发生过的 Bash 失败。turns、duration、dispatch、cost、token、skill/rule 命中、
+ devflow 阶段耗时、会话列表本身完全不受影响,是纯观测盲区,不影响 devflow 实际
+ 执行行为。
+
+ **三次修复尝试均已失败,均已回滚(详见下方"已尝试且已放弃的修复方向")**:
+ 真正阻塞方向 A 的证据很反常——三次独立测试里,预算从 160ms 加到 500ms 再加到
+ 2000ms,实测缺口每次都精确地"比预算多几十到一百多毫秒"(206/564/2151ms),
+ 不像是在等一个独立发生的固定延迟,更像是**hook 自己的同步等待在阻塞 CLI 落盘**
+ ——等得越久,结果来得越晚。这个因果关系还没验证清楚,在验证清楚之前,继续在
+ hook 里加同步等待大概率是死路,不建议再尝试。
+
+### 已尝试且已放弃的修复方向(供以后参考,避免重复踩坑)
+
+1. **方向 A:PostToolUse 里同步有界重试**(`claim=False` 轮询直到等到 `raw_response`
+ 或超时,只对 `tool_name=="Bash"` 生效)。三次真实端到端验证,预算 160ms/500ms/
+ 2000ms 全部失败,且"缺口≈预算+常数"的规律强烈暗示等待本身可能在拖慢 CLI
+ 落盘(见上文)。不建议在搞清楚这层因果关系之前继续加大预算。
+2. **方向 B:推迟到 `pending_tool_emits` 重试队列,下次 hook 触发或 session Stop
+ 时再补**(`claim=False` 探测 + 延后 `claim=True`,避免过早消费掉 call_id)。
+ 逻辑和单元测试都通过,但端到端验证暴露了一个更深的、独立于这次修复的既有
+ 架构问题:`find_current_tool_context()`(工具上下文查询)和
+ `emit_transcript_events()`(usage token 扫描)共用同一个持久化字节偏移游标
+ (`core/state.py` 里只按 `(sid, transcript_path)` 区分,不分用途)。
+ `emit_transcript_events()` 每次 `handle_post()` 都无条件推进这个游标,一旦
+ 推过某段内容,后续任何工具上下文重试在这段范围内都会**彻底找不到任何数据**
+ (不只是缺 `raw_response`,连 `call_id`/`arguments` 都没了)——比不修复更糟。
+ 真实验证过两次:两条端到端测试调用最终落盘时 `tool_details`完全是空的。
+ 要让方向 B 真正可行,必须先给工具上下文查询一个独立于 usage 扫描的游标,
+ 这是范围更大、需要认真设计的改动,还没有细化方案。
+
+以上两个方向的实现和回滚记录详见会话 memory(`project-agent-observability-raw-response-race`)。
diff --git a/.cursor/skills/agent-observability/references/schema-v2.md b/.cursor/skills/agent-observability/references/schema-v2.md
new file mode 100644
index 00000000..a04d4d09
--- /dev/null
+++ b/.cursor/skills/agent-observability/references/schema-v2.md
@@ -0,0 +1,282 @@
+## Schema v2.3
+
+`agent-observability` 输出 `ndjson`,每行一个事件对象。
+
+> 以下字段表基于当前 `logs/metrics.ndjson` 的实际输出整理;其中“可选字段”只会在特定场景出现。
+
+### 通用字段
+
+- `event`: `start | user_prompt_submit | tool | usage | stop | error | stage_transition`
+- `sid`: session id
+- `ts`: 秒级时间戳(float)
+- `turn_id`: 可选;由 `UserPromptSubmit` 生成,贯穿本轮事件
+
+### Devflow 感知字段(可选,见 `core/devflow.py`)
+
+只有当前项目正在跑 `.cursor/runtime` 描述的 multi-agents-devflow 工作流(存在
+`.cursor/teams/multi-agents-devflow-{task_slug}/` team 目录)时才会出现,非
+devflow 项目完全不受影响:
+
+- `tool` / `usage` / `stop` 事件上会附带 `task_slug`(devflow 需求标识,用于把
+ main + 最多 7 个常驻角色跨事件串成"同一次运行";⚠️ `/resume-devflow` 中断恢复
+ 可能发生在新的 CodeBuddy 顶层 session 里,因此**聚合一次 devflow 运行要按
+ `task_slug` 分组,不能按 `sid` 分组**)与 `stage`(`workflow-state.json` 的
+ `current_stage`,如 `TASK-03`/`CODE-REVIEW`)。
+- `tool` 事件在能从 subagent transcript 文件名识别出并行 sub-developer 轨道时
+ (`sub-developer-PT-01` 这类命名)会额外带 `pt_id`(如 `"PT-01"`)。按事件自己的
+ transcript_path 推断,不依赖任何 session 级共享状态——并行轨道是真并发,不能
+ 用一个可变指针记"当前是哪条轨道"。
+
+### 事件字段
+
+| event | 实际顶层字段 | 说明 |
+|---|---|---|
+| `start` | `event`, `sid`, `agent`, `ts` | 会话开始 |
+| `user_prompt_submit` | `event`, `sid`, `agent`, `turn_id`, `prompt_len`, `ts` | 新 turn 边界;AgentLens 侧按 `1 Trace = 1 Turn` 生成 trace |
+| `tool` | `event`, `sid`, `agent`, `tool`, `ms`, `transcript_path`, `turn_id`, `ts`, `skill`, `rule`, `cwd`, `call_id`, `message_id`, `tool_details`, `task_slug`?, `stage`?, `pt_id`? | 工具调用与耗时 |
+| `usage` | `event`, `sid`, `agent`, `tool`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | transcript 增量 token / 模型 / 消息归属 |
+| `stop` | `event`, `sid`, `agent`, `tokens`, `model`, `transcript_path`, `source_offset`, `turn_id`, `message_id`, `ts`, `task_slug`?, `stage`? | 会话尾部 flush |
+| `error` | `event`, `sid`, `phase`, `error`, `x_traceback`, `ts` | hook 自身异常记录 |
+| `stage_transition` | `event`, `sid`, `task_slug`, `stage`, `status`?, `executor`?, `retry_count`?, `review_result`?, `ts` | devflow `workflow-state.json` 某个 stage 的 status/retry_count/review_result 发生变化时触发(仅 devflow 项目) |
+
+### 可选字段说明
+
+- `tool.ms`: Pre/Post 未成功配对时可能为 `null`
+- `tool.call_id`: 仅当工具调用存在 call id 时出现
+- `tool.message_id`: 仅当成功和 transcript 中的 message 关联上时出现
+- `tool.tool_details`: 仅当 transcript 中能还原出更细工具上下文时出现
+- `usage.message_id`: 仅当 usage 对应的 transcript message 可识别时出现
+- `usage.model`: transcript 中能识别模型名时出现
+- `usage.cost_usd`: 只有模型价格命中价格表时才会出现。价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认 `<project_root>/.cursor/agent-observability/pricing.overrides.json`,可用 `AOBS_PRICING_OVERRIDES_PATH` 指定)的字段级合并结果;覆盖只对该文件写入**之后**产生的新事件生效,不回溯重算历史成本(见 `quickstart.md` 的「自定义模型定价覆盖」)
+- `stop.cost_usd`: 只有当前 stop 事件对应 usage 能估算成本时才会出现
+- `stop.cost_session_usd`: 只有 stop 汇总阶段能反算出整个 session 成本时才会出现
+
+### 完整示例
+
+换成更容易读的多行 JSON。下面仍然是当前 `metrics.ndjson` 里的实际数据,只是长文本字段做了截断。
+
+`start`
+
+```json
+{
+ "event": "start",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "ts": 1784015331.87806
+}
+```
+
+`user_prompt_submit`
+
+```json
+{
+ "event": "user_prompt_submit",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "turn_id": "turn-1784015342075",
+ "prompt_len": 136,
+ "ts": 1784015342.076438
+}
+```
+
+`usage`
+
+```json
+{
+ "event": "usage",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "tokens": {
+ "input": 31110,
+ "output": 594,
+ "cache_read": 3072,
+ "total": 31704
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.cursor/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 17423,
+ "turn_id": "turn-1784015342075",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "ts": 1784015355.413464
+}
+```
+
+`tool` 调用参数型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Read",
+ "ms": null,
+ "transcript_path": "/Users/rachel/.cursor/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015355.412617,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "message_id": "d187771c6eef4520a530564dd2a73e38",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/Users/rachel/skillhub-tokentrack-mr/assets/devflow.defaults.yaml\"}",
+ "arguments_display_text": "assets/devflow.defaults.yaml"
+ }
+}
+```
+
+`tool` 返回结果型
+
+```json
+{
+ "event": "tool",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 759,
+ "transcript_path": "/Users/rachel/.cursor/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "turn_id": "turn-1784015342075",
+ "ts": 1784015356.071573,
+ "skill": [],
+ "rule": [
+ "global"
+ ],
+ "cwd": "/Users/rachel/skillhub-tokentrack-mr",
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "tool_details": {
+ "call_id": "chatcmpl-tool-898d45e0999b3e3c",
+ "result_content": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .cursor/teams/ ...<truncated>",
+ "raw_response": {
+ "exitCode": 1,
+ "signal": null,
+ "interrupted": false,
+ "sandboxDenied": false,
+ "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0,
+ "tool_error_code": "8002",
+ "is_error": true,
+ "error": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .cursor/teams/ ...<truncated>"
+ },
+ "output_text": "Command: cd /Users/rachel/skillhub-tokentrack-mr && ls -la .cursor/teams/ ...<truncated>",
+ "original_message_id": "d187771c6eef4520a530564dd2a73e38",
+ "next_message_id": "93b617ceebaa49458169b89b4ecae17b",
+ "message_id_reassigned": true
+ }
+}
+```
+
+`stop`
+
+```json
+{
+ "event": "stop",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "agent": "test-engineer",
+ "tokens": {
+ "input": 128290,
+ "output": 665,
+ "cache_read": 128192,
+ "total": 128955
+ },
+ "model": "hy3-ioa",
+ "transcript_path": "/Users/rachel/.cursor/projects/Users-rachel-skillhub-tokentrack-mr/f6435d63-b4d5-44f2-b4d6-ae73d6c140fd.jsonl",
+ "source_offset": 1157291,
+ "turn_id": "turn-1784015342075",
+ "message_id": "51e4fae9553d4d0995e7a599f3b2ef2d",
+ "ts": 1784018405.467215
+}
+```
+
+`error`
+
+```json
+{
+ "event": "error",
+ "sid": "6e8cd633-1a2f-4488-b1df-1eef168009c3",
+ "phase": "post",
+ "error": "AttributeError: module 'core.transcript_runtime' has no attribute 'transcript_path'",
+ "x_traceback": "Traceback ...<truncated>",
+ "ts": 1784183163.4314518
+}
+```
+
+`stage_transition`(仅 devflow 项目;见 `core/devflow.py`)
+
+```json
+{
+ "event": "stage_transition",
+ "sid": "f6435d63-b4d5-44f2-b4d6-ae73d6c140fd",
+ "task_slug": "fix-token-bypass_20260911_0900",
+ "stage": "CODE-REVIEW",
+ "status": "failed",
+ "executor": "code-reviewer",
+ "retry_count": 1,
+ "review_result": "failed",
+ "ts": 1784015412.223
+}
+```
+
+### tokens
+
+```json
+{"input": 1200, "output": 180, "cache_read": 9000, "cache_creation": 0, "total": 1380}
+```
+
+- `total`: 统一按 `input + output` 计算
+- `cache_read` / `cache_creation`: 保留给成本估算和缓存命中分析使用
+
+### tool_details
+
+`tool` 事件里的 `tool_details` 是一个可选嵌套对象,当前实现里可能包含:
+
+- `call_id`
+- `arguments`
+- `arguments_display_text`
+- `result_content`
+- `raw_response`
+- `output_text`
+- `original_message_id`
+- `next_message_id`
+- `message_id_reassigned`
+
+常见示例:
+
+```json
+{
+ "call_id": "chatcmpl-tool-9e50f7ec1d7e4a27",
+ "arguments": "{\"file_path\": \"/path/to/file\"}",
+ "arguments_display_text": "path/to/file"
+}
+```
+
+### AgentLens sidecar
+
+`.state.json[sid]._agentlens` 只作为内部状态使用,核心字段:
+
+- `enabled`: AgentLens 上报是否可用
+- `last_error`: 最近一次降级原因
+- `current_turn.carrier.traceparent`: 当前 turn 的 trace context
+- `current_turn.subagent_spans`: 同一 turn 下的子 agent span carrier
+- `current_turn.agent_spans`: 同一 turn 下按 agent 聚合的 span carrier 与累计统计
+- `current_turn.step_spans`: `(agent, message_id)` 级 step span registry
+- `turn_history`: 已结束 turn 的摘要
+
+### Hook 接入
+
+参考 `templates/settings-hook.json`,必须启用:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+### 兼容
+
+- 旧日志若在 `tool` 事件里直接携带 `tokens` / `cost_usd`,按 legacy usage 处理。
+- 不理解 `turn_id` 的下游消费者可安全忽略。
diff --git a/.cursor/skills/agent-observability/scripts/__init__.py b/.cursor/skills/agent-observability/scripts/__init__.py
new file mode 100644
index 00000000..52073be9
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/__init__.py
@@ -0,0 +1 @@
+"""agent-observability 的脚本包。"""
diff --git a/.cursor/skills/agent-observability/scripts/build_dashboard_data.py b/.cursor/skills/agent-observability/scripts/build_dashboard_data.py
new file mode 100644
index 00000000..e33f816a
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/build_dashboard_data.py
@@ -0,0 +1,624 @@
+#!/usr/bin/env python3
+"""把 `logs/metrics.ndjson` + `artifacts/*/workflow-state.json` + `.state.json` +
+`hooks/logs/auto-dispatch.log` 聚合成看板需要的一份 `dashboard-data.json` 快照。
+
+这是本地看板的数据源,不是 hook 链路的一部分——hook 只管往 metrics.ndjson 追加事件,
+这个脚本单独、按需运行(比如每次想看一眼看板之前手动跑一次,或者配合文件监听器)。
+复用 core.devflow 的 stage_snapshot 做 workflow-state.json 的 schema 归一化,
+不在这里重新实现一遍 Classic/Portable 的字段差异。
+
+用法:
+ python3 build_dashboard_data.py --project-root <项目根目录> --out dashboard/dashboard-data.json
+ python3 build_dashboard_data.py --metrics-path ~/other/metrics.ndjson --state-path ~/other/.state.json
+ python3 build_dashboard_data.py --top-slow 5
+
+不传 --metrics-path / --state-path 时,仍从 <skill_root>/logs/ 下的默认文件读取;
+两者均支持 ~ 展开,输出 source 会如实反映实际读取路径。
+
+--top-slow N 默认不开启,开启后只在终端额外打印耗时最长的 N 次 tool 事件,
+不写入 dashboard-data.json(输出结构与不开时完全一致)。
+
+没有任何真实数据时(hook 刚接上、还没跑过 session),会输出一份全空但结构合法的快照,
+不会报错、也不会伪造数据。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import devflow as dv # type: ignore
+
+try: # emitter 只在"未定价模型"统计里用到,导入失败只让这一项退化为 []
+ from core import emitter as em # type: ignore
+except Exception: # pragma: no cover - 目标机缺依赖时的兜底
+ em = None # type: ignore
+
+# devflow 两套 schema 的 stage 名 -> 展示用 (label, name)。取不到的 stage 用 key 本身兜底。
+STAGE_META: dict[str, tuple[str, str]] = {
+ "PHASE-0": ("P0", "初始化 + 判定大小"),
+ "SOLO": ("SOLO", "单 agent 全流程"),
+ "TASK-01": ("T01", "需求分析 + 澄清"),
+ "REQUIREMENT": ("REQ", "需求分析 + 澄清"),
+ "TASK-02": ("T02", "技术方案"),
+ "DESIGN": ("DES", "技术方案"),
+ "TASK-03": ("T03", "代码实现"),
+ "IMPLEMENT": ("IMPL", "代码实现"),
+ "CODE-REVIEW": ("CR", "代码审查"),
+ "REVIEW": ("REV", "代码审查"),
+ "TASK-04": ("T04", "E2E 测试"),
+ "TEST": ("TEST", "E2E 测试"),
+ "TASK-05": ("T05", "知识沉淀"),
+ "KNOWLEDGE": ("KNOW", "知识沉淀"),
+ "SUMMARY": ("汇总", "最终汇总"),
+}
+# 两套 schema 各自的阶段顺序,用来按正确顺序渲染 stepper(不能直接遍历 dict,顺序不保证)。
+CLASSIC_ORDER = ["PHASE-0", "TASK-01", "TASK-02", "TASK-03", "CODE-REVIEW", "TASK-04", "TASK-05"]
+# SOLO 完成后,small 任务会由 solo-developer 合并执行 TASK-05 知识沉淀(真实运行验证过,
+# 不是理论上可选的分支);stepper 顺序必须把它列进去,否则会把已完成的阶段悄悄漏掉。
+CLASSIC_SOLO_ORDER = ["PHASE-0", "SOLO", "TASK-05"]
+PORTABLE_ORDER = ["PHASE-0", "REQUIREMENT", "DESIGN", "IMPLEMENT", "REVIEW", "TEST", "KNOWLEDGE", "SUMMARY"]
+PORTABLE_SOLO_ORDER = ["PHASE-0", "SOLO", "SUMMARY"]
+
+
+def read_ndjson(path: Path) -> list[dict[str, Any]]:
+ records: list[dict[str, Any]] = []
+ if not path.is_file():
+ return records
+ with path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ obj = json.loads(line)
+ except Exception:
+ continue
+ if isinstance(obj, dict):
+ records.append(obj)
+ return records
+
+
+def safe_load_json(path: Path) -> Any:
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def day_of(ts: float) -> str:
+ from datetime import datetime, timezone
+ return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+
+
+def tool_call_failed(raw_response: Any) -> bool:
+ """判断一次工具调用是否失败。
+
+ 真实 CodeBuddy CLI 的 transcript(`function_call_result.providerData.toolResult.
+ rawResponse`)里从来没有 `is_error` 这个布尔字段——实际信号是 `exitCode`(非 0
+ 即失败)和/或 `tool_error_code`(非 "0"/空即失败)。之前只认 `is_error`,导致
+ 失败统计在这个宿主上永远是 0,不管命令是否真的失败(复合命令比如
+ `cmd; echo ...` 会把失败进一步掩盖成 exitCode=0,那种情况下这里也如实判定为
+ 未失败——判断整条工具调用本身有没有失败,不追究命令内部的子步骤)。
+ 仍然保留 `is_error` 判断,兼容其它可能真的写这个字段的宿主。
+ """
+ if not isinstance(raw_response, dict):
+ return False
+ if raw_response.get("is_error"):
+ return True
+ exit_code = raw_response.get("exitCode")
+ if isinstance(exit_code, (int, float)) and exit_code != 0:
+ return True
+ tool_error_code = raw_response.get("tool_error_code")
+ if isinstance(tool_error_code, str) and tool_error_code.strip() not in ("", "0"):
+ return True
+ return False
+
+
+def build_daily_and_sessions(events: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ by_day: dict[str, dict[str, Any]] = {}
+ by_sid: dict[str, dict[str, Any]] = {}
+ by_sid_turn: dict[tuple[str, str], dict[str, Any]] = {}
+ # AgentLens(写 state.current_turn 的那套 tracing)默认关闭时,tool/usage 事件
+ # 自身的 turn_id 永远是 None——但 user_prompt_submit 事件不依赖 AgentLens,
+ # 始终携带真实 turn_id(见 emitter.build_prompt_submit_event)。按 ts 排序后,
+ # 把它当作 turn 边界,让后续没有自带 turn_id 的 tool/usage 事件归入"当前 sid
+ # 最近一次打开的 turn",而不是全部塌缩进同一个 "?" 占位桶。
+ current_turn_by_sid: dict[str, str] = {}
+
+ def day_bucket(iso: str) -> dict[str, Any]:
+ return by_day.setdefault(iso, {
+ "iso": iso, "sessionCount": 0, "input": 0, "output": 0, "cache": 0,
+ "cost": 0.0, "toolCalls": 0, "failures": 0, "skillHits": defaultdict(int),
+ "_sids": set(),
+ })
+
+ def sess_bucket(sid: str) -> dict[str, Any]:
+ return by_sid.setdefault(sid, {
+ "id": sid, "date": None, "agents": set(), "turns": set(), "toolCalls": 0,
+ "tokens": 0, "cost": 0.0, "first_ts": None, "last_ts": None, "models": defaultdict(int),
+ "status": "ok", "timeline": {},
+ })
+
+ for rec in sorted(events, key=lambda r: r.get("ts") if isinstance(r.get("ts"), (int, float)) else 0):
+ event = rec.get("event")
+ sid = str(rec.get("sid") or "")
+ ts = rec.get("ts")
+ if not sid or not isinstance(ts, (int, float)):
+ continue
+ iso = day_of(ts)
+ sess = sess_bucket(sid)
+ sess["_seen_day"] = iso
+ # 不管事件类型,只要这天有这个 sid 的任何事件就算一次"当日活跃会话"。
+ # 之前只在 tool/usage 分支里 add,纯对话(只有 user_prompt_submit,没有
+ # 触发任何工具调用也没有 usage)的会话永远不会被计入任何一天的
+ # sessionCount——总览页的"会话数"会比"会话浏览"tab 里实际展开的会话数少
+ # (真实数据复现过:5 个 session 只统计出 4 个 sessionCount)。
+ day_bucket(iso)["_sids"].add(sid)
+ if sess["first_ts"] is None or ts < sess["first_ts"]:
+ sess["first_ts"] = ts
+ sess["date"] = iso
+ if sess["last_ts"] is None or ts > sess["last_ts"]:
+ sess["last_ts"] = ts
+ agent = rec.get("agent")
+ if agent:
+ sess["agents"].add(str(agent))
+ raw_turn_id = rec.get("turn_id")
+ if event == "user_prompt_submit" and raw_turn_id:
+ current_turn_by_sid[sid] = str(raw_turn_id)
+ # 提前建桶——纯对话轮次(没有触发任何工具调用,只有 usage 都没有)
+ # 之前只在 tool/usage 分支里 setdefault,这种轮次永远不会出现在
+ # timeline 里,导致 turns 计数和时间线展开的分组数对不上。
+ by_sid_turn.setdefault(
+ (sid, str(raw_turn_id)),
+ {"turn": raw_turn_id, "agent": agent or "main", "events": []},
+ )
+ turn_id = raw_turn_id or current_turn_by_sid.get(sid)
+ if turn_id:
+ sess["turns"].add(str(turn_id))
+
+ if event == "tool":
+ day = day_bucket(iso)
+ day["toolCalls"] += 1
+ sess["toolCalls"] += 1
+ for s in rec.get("skill") or []:
+ day["skillHits"][str(s)] += 1
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ is_err = tool_call_failed(raw_response)
+ if is_err:
+ day["failures"] += 1
+ sess["status"] = "error"
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "tool", "tool": rec.get("tool"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ "err": is_err,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "usage":
+ day = day_bucket(iso)
+ tokens = rec.get("tokens") or {}
+ day["input"] += int(tokens.get("input") or 0)
+ day["output"] += int(tokens.get("output") or 0)
+ day["cache"] += int(tokens.get("cache_read") or 0)
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ day["cost"] += float(cost)
+ sess["cost"] += float(cost)
+ total_tok = int(tokens.get("input") or 0) + int(tokens.get("output") or 0)
+ sess["tokens"] += total_tok
+ model = rec.get("model")
+ if model:
+ sess["models"][str(model)] += 1
+ key = (sid, str(turn_id or "?"))
+ turn = by_sid_turn.setdefault(key, {"turn": turn_id or "?", "agent": agent or "main", "events": []})
+ turn["events"].append({
+ "kind": "usage", "tokens": total_tok,
+ "agent": str(agent) if agent else "main",
+ })
+ elif event == "error":
+ sess["status"] = "error"
+
+ for (sid, _turn_key), turn in by_sid_turn.items():
+ sess = by_sid.setdefault(sid, sess_bucket(sid))
+ sess["timeline"].setdefault(_turn_key, turn)
+
+ daily = []
+ for iso in sorted(by_day.keys()):
+ d = by_day[iso]
+ daily.append({
+ "iso": iso, "sessionCount": len(d["_sids"]), "input": d["input"], "output": d["output"],
+ "cache": d["cache"], "cost": round(d["cost"], 4), "toolCalls": d["toolCalls"],
+ "failures": d["failures"], "skillHits": dict(d["skillHits"]),
+ })
+
+ sessions = []
+ for sid, s in by_sid.items():
+ if s["first_ts"] is None:
+ continue
+ duration = int((s["last_ts"] or s["first_ts"]) - s["first_ts"])
+ model = max(s["models"].items(), key=lambda kv: kv[1])[0] if s["models"] else None
+ timeline_sorted = sorted(s["timeline"].values(), key=lambda t: str(t.get("turn") or ""))
+ for idx, t in enumerate(timeline_sorted, start=1):
+ t["turn"] = idx
+ sessions.append({
+ "id": sid, "date": s["date"], "agent": ", ".join(sorted(s["agents"])) or "main",
+ "turns": len(s["turns"]) or len(timeline_sorted), "toolCalls": s["toolCalls"],
+ "tokens": s["tokens"], "cost": round(s["cost"], 4), "duration": duration,
+ "model": model, "status": s["status"], "timeline": timeline_sorted,
+ })
+ sessions.sort(key=lambda s: s["date"] or "", reverse=True)
+ return daily, sessions
+
+
+def build_model_costs(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ cost = rec.get("cost_usd")
+ if model and isinstance(cost, (int, float)):
+ totals[str(model)] += float(cost)
+ rows = [{"name": name, "cost": round(cost, 4)} for name, cost in totals.items()]
+ rows.sort(key=lambda r: r["cost"], reverse=True)
+ return rows
+
+
+def build_unpriced_models(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """聚合"完全没命中价格表"的模型(D4:`emitter.is_unpriced(model)` 为 True)。
+
+ 只**统计**不重算:`cost_usd` 在 hook 期就写进事件了,这里不会(也不该)回头
+ 按新价格补算历史事件(D3:覆盖只对新事件生效)。判定入口复用 emitter,
+ 不在本文件里重写一套模型名匹配逻辑,避免与 hook 期的口径分叉。
+
+ 模型名缺失/为空的 usage 事件无法归因到某个模型,直接跳过不计数。
+ """
+ if em is None:
+ return []
+ counts: dict[str, int] = defaultdict(int)
+ for rec in events:
+ if rec.get("event") != "usage":
+ continue
+ model = rec.get("model")
+ if not model or not str(model).strip():
+ continue
+ name = str(model)
+ try:
+ if em.is_unpriced(name):
+ counts[name] += 1
+ except Exception:
+ continue
+ rows = [{"name": name, "usageEvents": count} for name, count in counts.items()]
+ # 按 (-事件数, 名字) 排序:避免看板顺序抖动,两次生成的快照可直接逐字节比对。
+ rows.sort(key=lambda r: (-r["usageEvents"], r["name"]))
+ return rows
+
+
+def build_failures(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ agg: dict[tuple[str, str], dict[str, Any]] = {}
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ tool_details = rec.get("tool_details") or {}
+ raw_response = tool_details.get("raw_response") if isinstance(tool_details, dict) else None
+ if not tool_call_failed(raw_response):
+ continue
+ tool = str(rec.get("tool") or "unknown")
+ code = str(raw_response.get("tool_error_code") or raw_response.get("exitCode") or "error")
+ key = (tool, code)
+ row = agg.setdefault(key, {"tool": tool, "code": code, "count": 0, "last": None, "_last_ts": 0.0})
+ row["count"] += 1
+ ts = rec.get("ts")
+ if isinstance(ts, (int, float)) and ts > row["_last_ts"]:
+ row["_last_ts"] = ts
+ row["last"] = day_of(ts)
+ rows = list(agg.values())
+ for row in rows:
+ row.pop("_last_ts", None)
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_top_slow(events: list[dict[str, Any]], limit: int | None = None) -> list[dict[str, Any]]:
+ """取耗时最长的 N 次 tool 事件,按 ms 降序。
+
+ 只做"读":不改动 events,也不参与 dashboard-data.json 的任何字段——调用方拿
+ 结果去打印即可。`ms` 的兜底口径与 build_daily_and_sessions 保持一致(缺失或
+ 非数字按 0 计),否则同一份日志会得出两个互相矛盾的工具耗时视图。
+ """
+ if not isinstance(limit, int) or limit <= 0:
+ return []
+ rows: list[dict[str, Any]] = []
+ for rec in events:
+ if rec.get("event") != "tool":
+ continue
+ rows.append({
+ "tool": str(rec.get("tool") or "unknown"),
+ "ms": rec.get("ms") if isinstance(rec.get("ms"), (int, float)) else 0,
+ })
+ rows.sort(key=lambda r: r["ms"], reverse=True)
+ return rows[:limit]
+
+
+def format_top_slow(rows: list[dict[str, Any]]) -> str:
+ """把 top-slow 结果渲染成终端文本;没有可展示的行时返回空串(由调用方决定
+ 是否打印,避免没有任何 tool 事件时空打一个表头)。"""
+ if not rows:
+ return ""
+ width = max(len(str(r["tool"])) for r in rows)
+ lines = [f"top-slow {len(rows)} tool calls (by ms):"]
+ for idx, row in enumerate(rows, start=1):
+ lines.append(f" {idx}. {str(row['tool']):<{width}} {row['ms']}ms")
+ return "\n".join(lines)
+
+
+def build_skills(state: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ totals: dict[str, int] = defaultdict(int)
+ never_used: dict[str, dict[str, Any]] = {}
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for name, rec in (sess.get("skills") or {}).items():
+ if not isinstance(rec, dict):
+ continue
+ totals[name] += int(rec.get("count") or 0)
+ for name, rec in (sess.get("rules") or {}).items():
+ if not isinstance(rec, dict) or int(rec.get("count") or 0) > 0:
+ continue
+ never_used[name] = {"name": name, "reason": "no_paths", "detail": "从未被路径推断或 active-rule 命中"}
+ for name, count in totals.items():
+ if count == 0:
+ never_used.setdefault(name, {"name": name, "reason": "no_paths", "detail": "静态扫描到,但从未被任何工具调用命中"})
+ skill_rows = [{"name": name, "count": count} for name, count in totals.items() if count > 0]
+ skill_rows.sort(key=lambda r: r["count"], reverse=True)
+ return skill_rows, sorted(never_used.values(), key=lambda r: r["name"])
+
+
+
+# "team-lead" 是 CodeBuddy 原生 team 基础设施里 lead/orchestrator session 自己的
+# mailbox 名字,语义上就是 main(core/agent_identity.py::normalize_role_name 把它
+# 和 "main" 归为同一类);不是一个真实存在的子 agent,不应出现在"派发目标"里。
+_DISPATCH_EXCLUDE_AGENTS = {"main", "team-lead"}
+
+
+def build_dispatch(state: dict[str, Any]) -> list[dict[str, Any]]:
+ totals: dict[str, int] = defaultdict(int)
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ for entry in sess.get("agent_history") or []:
+ if not isinstance(entry, dict):
+ continue
+ evidence = str(entry.get("evidence") or "")
+ agent = entry.get("agent")
+ if not agent or agent in _DISPATCH_EXCLUDE_AGENTS:
+ continue
+ # 只统计真正代表"新派发"的证据:工具调用直接触发的 dispatch@,
+ # 或 inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)。
+ # 排除 inbox@report:*/inbox@handoff:*——那是子 agent 上报/移交,
+ # 不是 main 发起的新派发,计进来会把"派发次数"虚高(同一次真实
+ # 派发经常先触发 dispatch@,随后又在 inbox 里被自己的上报回声一次)。
+ is_dispatch = evidence.startswith("dispatch@") or evidence.startswith("inbox@dispatch:")
+ if is_dispatch:
+ totals[str(agent)] += 1
+ rows = [{"agent": agent, "count": count} for agent, count in totals.items()]
+ rows.sort(key=lambda r: r["count"], reverse=True)
+ return rows
+
+
+def build_auto_dispatch_stats(project_root: Path) -> dict[str, int]:
+ log_path = project_root / ".codebuddy" / "hooks" / "logs" / "auto-dispatch.log"
+ stats = {"auto_dispatch": 0, "fallback_to_main": 0, "passthrough": 0}
+ if not log_path.is_file():
+ return stats
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ line = line.strip()
+ if not line.startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ decision = str(rec.get("decision") or "")
+ if decision == "auto_dispatch":
+ stats["auto_dispatch"] += 1
+ elif decision == "fallback_to_main":
+ stats["fallback_to_main"] += 1
+ elif decision in {"passthrough"}:
+ stats["passthrough"] += 1
+ return stats
+
+
+def build_cost_by_task_slug(events: list[dict[str, Any]]) -> dict[str, float]:
+ """按 task_slug 汇总 usage/stop 事件的 cost_usd——workflow-state.json 自己不知道成本,
+ 这是唯一能把 devflow 运行和真实花费对上的地方(需要 emitter 已经把 task_slug 挂到事件上,
+ 见 core/runtime.py 的 devflow 接入)。"""
+ totals: dict[str, float] = defaultdict(float)
+ for rec in events:
+ if rec.get("event") not in {"usage", "stop"}:
+ continue
+ task_slug = rec.get("task_slug")
+ cost = rec.get("cost_usd")
+ if task_slug and isinstance(cost, (int, float)):
+ totals[str(task_slug)] += float(cost)
+ return dict(totals)
+
+
+def build_devflow_runs(project_root: Path, cost_by_slug: dict[str, float] | None = None) -> list[dict[str, Any]]:
+ artifacts_root = project_root / "artifacts"
+ runs: list[dict[str, Any]] = []
+ cost_by_slug = cost_by_slug or {}
+ if not artifacts_root.is_dir():
+ return runs
+ for child in sorted(artifacts_root.iterdir()):
+ state_path = child / "workflow-state.json"
+ raw = dv.read_workflow_state(str(state_path))
+ if not isinstance(raw, dict) or not isinstance(raw.get("stages"), dict):
+ continue
+ snap = dv.stage_snapshot(raw)
+ size_class = str(snap.get("size_class") or "medium")
+ # medium/large 的 workflow-state.json 也会带着 SOLO key(模板固定写入,
+ # 状态停在 "pending" 或 "skipped",从未被真正执行)——不能只看 key 存不存在,
+ # 必须看 SOLO 阶段是不是真的跑过,否则每个 medium/large 任务都会被误判成
+ # solo 路径,阶段视图漏掉 TASK-01/02/03/CODE-REVIEW/TASK-04。
+ solo_info = snap["stages"].get("SOLO")
+ solo_status = str(solo_info.get("status") or "") if isinstance(solo_info, dict) else ""
+ solo_actually_ran = solo_status not in {"", "pending", "skipped"}
+ is_solo = size_class == "small" or (size_class not in {"small", "medium", "large"} and solo_actually_ran)
+ if snap.get("schema_version") == "2.0":
+ order = PORTABLE_SOLO_ORDER if is_solo else PORTABLE_ORDER
+ else:
+ order = CLASSIC_SOLO_ORDER if is_solo else CLASSIC_ORDER
+ stages_out = []
+ total_cost = cost_by_slug.get(child.name, 0.0)
+ run_start = None
+ run_end = None
+ overall = "completed"
+ for key in order:
+ info = snap["stages"].get(key)
+ if info is None:
+ # PHASE-0 在两套 schema 里都不会出现在 stages{} 里(它是隐式完成的:
+ # workflow-state.json 一旦存在,就说明 Phase 0 已经跑完了),
+ # 不能用"没有条目"直接兜底成 pending,那样会把已完成的阶段显示错。
+ info = {"status": "completed", "retry_count": 0, "executor": None} if key == "PHASE-0" \
+ else {"status": "pending", "retry_count": 0, "executor": None}
+ label, name = STAGE_META.get(key, (key[:4], key))
+ status = str(info.get("status") or "pending")
+ retry_count = int(info.get("retry_count") or 0)
+ raw_stage = raw.get("stages", {}).get(key) if isinstance(raw.get("stages"), dict) else {}
+ duration = 0
+ if isinstance(raw_stage, dict):
+ started = raw_stage.get("started_at")
+ completed = raw_stage.get("completed_at")
+ if isinstance(started, str) and isinstance(completed, str):
+ try:
+ from datetime import datetime
+ t0 = datetime.fromisoformat(started.replace("Z", "+00:00"))
+ t1 = datetime.fromisoformat(completed.replace("Z", "+00:00"))
+ duration = max(0, int((t1 - t0).total_seconds()))
+ if run_start is None or t0 < run_start:
+ run_start = t0
+ if run_end is None or t1 > run_end:
+ run_end = t1
+ except Exception:
+ duration = 0
+ if status == "failed":
+ overall = "paused"
+ elif status == "in_progress" and overall != "paused":
+ overall = "running"
+ stages_out.append({
+ "key": key, "label": label, "name": name,
+ "exec": info.get("executor") or "-", "status": status,
+ "retry_count": retry_count, "duration": duration,
+ })
+ # 按真实起止时间跨度算总时长(而不是逐阶段 duration 相加)——阶段之间可能
+ # 有重叠(比如 TASK-05 的 started_at 早于 SOLO 的 completed_at),相加会
+ # 把重叠部分重复计入,虚高于源数据本身反映的运行时长。
+ total_duration = int((run_end - run_start).total_seconds()) if run_start and run_end else 0
+ runs.append({
+ "slug": child.name, "size": size_class, "stages": stages_out,
+ "cost": round(total_cost, 4), "duration": total_duration, "overall": overall,
+ })
+ runs.sort(key=lambda r: r["slug"], reverse=True)
+ return runs
+
+
+def resolve_input_paths(
+ skill_root: Path,
+ metrics_path: str | None = None,
+ state_path: str | None = None,
+) -> tuple[Path, Path]:
+ """解析 metrics.ndjson 与 .state.json 的实际读取路径。
+
+ 任一参数为 None 时回退到 ``<skill_root>/logs/`` 下的默认路径,保证未传参时
+ 行为与旧版本完全一致(向后兼容,不会破坏现有看板数据源)。
+
+ 非 None 时按用户给定路径(支持 ``~`` 展开)取绝对路径,便于看板从非默认
+ 位置(如其它会话/项目的日志目录)聚合数据。
+ """
+ default_metrics = skill_root / "logs" / "metrics.ndjson"
+ default_state = skill_root / "logs" / ".state.json"
+ if metrics_path:
+ metrics = Path(metrics_path).expanduser().absolute()
+ else:
+ metrics = default_metrics
+ if state_path:
+ state = Path(state_path).expanduser().absolute()
+ else:
+ state = default_state
+ return metrics, state
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--project-root", default=".", help="devflow 项目根目录(含 .codebuddy/ 和 artifacts/)")
+ parser.add_argument("--out", default=None, help="输出路径,默认 <skill_root>/scripts/dashboard/dashboard-data.json")
+ parser.add_argument("--metrics-path", default=None, help="覆盖 metrics.ndjson 的读取路径(默认 <skill_root>/logs/metrics.ndjson,支持 ~ 展开)")
+ parser.add_argument("--state-path", default=None, help="覆盖 .state.json 的读取路径(默认 <skill_root>/logs/.state.json,支持 ~ 展开)")
+ parser.add_argument("--top-slow", type=int, default=None, help="额外在终端打印耗时最长的 N 次 tool 事件(工具名 + 耗时 ms),默认不打印;只打印不写入 dashboard-data.json")
+ args = parser.parse_args()
+
+ project_root = Path(args.project_root).expanduser().resolve()
+ skill_root = SCRIPTS_DIR.parent
+ log_path, state_path = resolve_input_paths(skill_root, args.metrics_path, args.state_path)
+
+ # 价格表带 lru_cache:本脚本可能长期驻留(配合文件监听器),单测也会同进程多次
+ # 调 main(),每次都先清一次缓存,保证覆盖文件的改动当场生效。
+ if em is not None:
+ try:
+ em.clear_price_cache()
+ except Exception:
+ pass
+
+ events = read_ndjson(log_path)
+ state = safe_load_json(state_path) or {}
+ if not isinstance(state, dict):
+ state = {}
+
+ daily, sessions = build_daily_and_sessions(events)
+ model_costs = build_model_costs(events)
+ unpriced = build_unpriced_models(events)
+ failures = build_failures(events)
+ skills, never_used = build_skills(state)
+ dispatch = build_dispatch(state)
+ auto_dispatch_stats = build_auto_dispatch_stats(project_root)
+ cost_by_slug = build_cost_by_task_slug(events)
+ devflow_runs = build_devflow_runs(project_root, cost_by_slug)
+
+ from datetime import datetime, timezone
+ out_data = {
+ "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+ "source": {
+ "metrics_ndjson": str(log_path), "state_json": str(state_path),
+ "project_root": str(project_root), "event_count": len(events),
+ },
+ "daily": daily, "sessions": sessions, "modelCosts": model_costs, "unpricedModels": unpriced,
+ "failures": failures,
+ "skills": skills, "neverUsed": never_used, "dispatch": dispatch,
+ "autoDispatchStats": auto_dispatch_stats, "devflowRuns": devflow_runs,
+ }
+
+ out_path = Path(args.out).expanduser().resolve() if args.out else (SCRIPTS_DIR / "dashboard" / "dashboard-data.json")
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+ out_path.write_text(json.dumps(out_data, ensure_ascii=False, indent=2), encoding="utf-8")
+ print(f"wrote {out_path} ({len(events)} events, {len(sessions)} sessions, {len(devflow_runs)} devflow runs)")
+ # top-slow 放在原输出之后:先保证不传参时的终端输出与 JSON 行为完全不变。
+ top_slow_block = format_top_slow(build_top_slow(events, args.top_slow))
+ if top_slow_block:
+ print(top_slow_block)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.cursor/skills/agent-observability/scripts/core/__init__.py b/.cursor/skills/agent-observability/scripts/core/__init__.py
new file mode 100644
index 00000000..1d6ad5e9
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/__init__.py
@@ -0,0 +1,8 @@
+"""agent-observability 的核心运行时模块集合。
+
+这里放的是 hook 主流程真正依赖的内部实现:
+- 采集与 transcript 解析
+- 状态读写与去重
+- skill/rule 扫描
+- AgentLens trace 镜像
+"""
diff --git a/.cursor/skills/agent-observability/scripts/core/agent_identity.py b/.cursor/skills/agent-observability/scripts/core/agent_identity.py
new file mode 100644
index 00000000..270ff904
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agent_identity.py
@@ -0,0 +1,587 @@
+"""Agent 身份解析层。
+
+这一层负责统一解析“当前是谁在工作、又把任务派给了谁”:
+- 从 tool 调用参数里提取 agent 线索
+- 从 team inbox / mailbox 中补偿推断 agent 身份
+- 把解析结果写回 session state,供后续日志归因复用
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+from . import scanner, state as st
+
+AGENT_PATH_RE = re.compile(r"\.codebuddy/agents/([a-zA-Z0-9_\-]+)(?:\.md)?", re.I)
+DISPATCH_TOOLS = {"Task", "task", "Agent", "DeferExecuteTool"}
+MESSAGE_TOOLS = {"send_message", "SendMessage"}
+TEAM_PREFIX = "multi-agents-devflow-"
+ROLE_INSTANCE_RE = re.compile(r"^(?P<base>[a-z0-9][a-z0-9\-]*?)-\d+$", re.I)
+INITIAL_ASSIGNMENT_RE = re.compile(
+ r"Initial task assignment for (?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+ROLE_DECLARATION_RE = re.compile(
+ r"角色[::]\s*(?P<role>[a-z0-9][a-z0-9\-]*)",
+ re.I,
+)
+# devflow TASK-03 并行 fan-out 时,developer 会以 Task(name="sub-developer-PT-01", ...)
+# 派发多条并行轨道。轨道号只在 transcript 文件名(= Task 的 name 参数)里出现,
+# 按 subagent_name 归一化后会被折成同一个 "developer" —— 这是有意的(用于按角色汇总),
+# 轨道号需要单独提取,见 pt_id_from_transcript_path。
+PT_TRACK_RE = re.compile(r"-((?:PT|pt)-\d+)$")
+
+
+def normalize_role_name(name: str | None) -> Optional[str]:
+ """把角色名归一化成稳定标识,例如把实例名折叠回基础角色名。"""
+ if not isinstance(name, str):
+ return None
+ cand = name.strip().lower()
+ if not cand:
+ return None
+ if cand.endswith(".json"):
+ cand = cand[:-5]
+ if "@" in cand:
+ cand = cand.split("@", 1)[0]
+ if cand in {"team-lead", "main"}:
+ return "main"
+ match = ROLE_INSTANCE_RE.match(cand)
+ if match:
+ cand = match.group("base")
+ return cand or None
+
+
+def resolve_teams_root() -> Path:
+ """解析 CodeBuddy team inbox 的根目录。"""
+ config_dir = (os.environ.get("CODEBUDDY_CONFIG_DIR") or "").strip()
+ if config_dir:
+ return Path(config_dir).expanduser() / "teams"
+ return Path.home() / ".codebuddy" / "teams"
+
+
+def resolve_team_dir(cwd: str, sid: str, cached_team_dir: str | None = None) -> Path | None:
+ """根据 session id 和 cwd 找到当前会话对应的 team 目录。"""
+ if cached_team_dir:
+ cached = Path(cached_team_dir).expanduser()
+ if (cached / "config.json").is_file():
+ cfg = _load_json(cached / "config.json")
+ if isinstance(cfg, dict) and sid and str(cfg.get("leadSessionId") or "") == sid:
+ return cached
+
+ if not sid:
+ return None
+
+ teams_root = resolve_teams_root()
+ if not teams_root.is_dir():
+ return None
+
+ best_dir: Path | None = None
+ best_created = -1
+ for team_dir in teams_root.iterdir():
+ if not team_dir.is_dir() or not team_dir.name.startswith(TEAM_PREFIX):
+ continue
+ config = _load_json(team_dir / "config.json")
+ if not isinstance(config, dict):
+ continue
+ if str(config.get("leadSessionId") or "") != sid:
+ continue
+ if not _config_matches_cwd(config, cwd):
+ continue
+
+ created_at = _safe_int(config.get("createdAt"))
+ if created_at <= 0:
+ try:
+ created_at = int(team_dir.stat().st_mtime * 1000)
+ except Exception:
+ created_at = 0
+ if created_at > best_created:
+ best_dir = team_dir
+ best_created = created_at
+ return best_dir
+
+
+def read_recent_messages(
+ team_dir: Path,
+ offsets: dict[str, int] | None = None,
+ *,
+ max_per_mailbox: int = 30,
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+ """按 mailbox 增量读取最近消息,并返回新的 offset 游标。"""
+ inbox_dir = team_dir / "inboxes"
+ if not inbox_dir.is_dir():
+ return [], offsets or {}
+
+ prev_offsets = offsets or {}
+ new_offsets: dict[str, int] = {}
+ messages: list[dict[str, Any]] = []
+
+ for inbox_file in sorted(inbox_dir.glob("*.json")):
+ raw = _load_json(inbox_file)
+ if not isinstance(raw, list):
+ raw = []
+
+ total = len(raw)
+ prev = _safe_int(prev_offsets.get(inbox_file.name))
+ if prev < 0 or prev > total:
+ prev = 0
+
+ start = prev
+ if start == 0 and total > max_per_mailbox:
+ start = total - max_per_mailbox
+
+ mailbox_name = inbox_file.stem
+ mailbox_role = normalize_role_name(mailbox_name)
+ for idx, item in enumerate(raw[start:], start=start):
+ norm = _normalize_message(item, mailbox_name, mailbox_role, idx)
+ if norm:
+ messages.append(norm)
+
+ new_offsets[inbox_file.name] = total
+
+ messages.sort(key=lambda x: (x.get("ts") or 0.0, x.get("mailbox_name") or "", x.get("index") or 0))
+ return messages, new_offsets
+
+
+def infer_identity_from_messages(messages: list[dict[str, Any]]) -> tuple[Optional[str], Optional[str], dict[str, Any]]:
+ """根据 inbox 消息流推断当前 agent 与派发目标。"""
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ evidence: Optional[str] = None
+
+ for msg in messages:
+ mailbox_name = str(msg.get("mailbox_name") or "")
+ mailbox_role = normalize_role_name(msg.get("mailbox_role"))
+ from_role = normalize_role_name(msg.get("from_role"))
+ payload = msg.get("payload") if isinstance(msg.get("payload"), dict) else {}
+ next_target = _extract_next_target(payload)
+
+ if from_role == "main" and mailbox_role and mailbox_role != "main":
+ if not msg.get("is_shutdown"):
+ current = mailbox_role
+ dispatched = mailbox_role
+ evidence = f"dispatch:{mailbox_name}"
+ continue
+
+ if mailbox_name == "team-lead" and from_role and from_role not in {"main", "system"}:
+ report_role = normalize_role_name(
+ payload.get("from_role") if isinstance(payload, dict) else None
+ ) or from_role
+ if next_target:
+ current = next_target
+ dispatched = next_target
+ evidence = f"handoff:{report_role}->{next_target}"
+ else:
+ current = report_role
+ evidence = f"report:{report_role}"
+
+ meta: dict[str, Any] = {"messages_seen": len(messages)}
+ if evidence:
+ meta["evidence"] = evidence
+ return current, dispatched, meta
+
+
+def safe_agent_from_provider(record: dict[str, Any]) -> str | None:
+ """当 transcript 自己带有 providerData 时,直接读取其中的 agent。"""
+ provider = record.get("providerData")
+ if not isinstance(provider, dict):
+ return None
+ agent = provider.get("agent")
+ if isinstance(agent, str) and agent.strip():
+ return normalize_role_name(agent.strip())
+ return None
+
+
+def role_from_content_items(content: Any) -> str | None:
+ """从 transcript content 文本中提取更具体的业务角色名。"""
+ if not isinstance(content, list):
+ return None
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ text = item.get("text")
+ if not isinstance(text, str):
+ continue
+ for regex in (INITIAL_ASSIGNMENT_RE, ROLE_DECLARATION_RE):
+ match = regex.search(text)
+ if not match:
+ continue
+ role = normalize_role_name(match.group("role"))
+ if role:
+ return role
+ return None
+
+
+@lru_cache(maxsize=256)
+def role_for_subagent_transcript(transcript_path: str) -> str | None:
+ """从 subagent transcript 前几行推断更准确的角色名。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(6):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+
+ # 对 subagent transcript,优先信任务分配文本里的具体角色,
+ # 再回退到 providerData.agent,避免 general-purpose 覆盖业务角色。
+ content_role = role_from_content_items(record.get("content"))
+ if content_role:
+ return content_role
+
+ provider_agent = safe_agent_from_provider(record)
+ if provider_agent:
+ return provider_agent
+ except Exception:
+ return None
+ return None
+
+
+def agent_for_transcript_path(transcript_path: str, fallback: str | None = None) -> str:
+ """把 transcript 路径映射回实际对应的 agent 身份。"""
+ parts = Path(transcript_path).parts
+ if "subagents" in parts:
+ return role_for_subagent_transcript(transcript_path) or Path(transcript_path).stem
+ return fallback or "main"
+
+
+def pt_id_from_transcript_path(transcript_path: str) -> str | None:
+ """从并行 sub-developer 的 transcript 文件名里提取 PT 轨道号(如 "PT-01")。
+
+ 按事件自己的 transcript_path 推断,而不是写一个共享的 session 级"当前 PT"指针——
+ devflow 一次可以并行派发最多 6 条 sub-developer 轨道,它们在同一个 sid 下
+ 真·并发运行,任何"当前是哪条轨道"的可变共享状态在并发场景下都是错的。
+ """
+ parts = Path(transcript_path).parts
+ if "subagents" not in parts:
+ return None
+ match = PT_TRACK_RE.search(Path(transcript_path).stem)
+ return match.group(1).upper() if match else None
+
+
+def merge_agent_identity_from_inbox(
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str | None,
+ dispatched: str | None,
+) -> tuple[str, str | None]:
+ """在基于 tool 的推断之上,再叠加 mailbox/inbox 的证据。"""
+
+ def _update(state: dict[str, Any]) -> tuple[str, str | None]:
+ sess = st.ensure_session(state, sid)
+ cached_team_dir = str(sess.get("_team_dir") or "").strip() or None
+ offsets = sess.get("_inbox_offsets")
+ if not isinstance(offsets, dict):
+ offsets = {}
+
+ effective_agent = active_agent or str(sess.get("current_agent") or "main")
+ effective_dispatched = dispatched
+ team_dir = resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is None:
+ return effective_agent, effective_dispatched
+
+ sess["_team_dir"] = str(team_dir)
+ messages, new_offsets = read_recent_messages(team_dir, offsets)
+ sess["_inbox_offsets"] = new_offsets
+ inferred_current, inferred_dispatched, meta = infer_identity_from_messages(messages)
+ if inferred_current:
+ effective_agent = inferred_current
+ if inferred_dispatched:
+ effective_dispatched = inferred_dispatched
+ if inferred_current or inferred_dispatched:
+ target_agent = inferred_current or inferred_dispatched
+ if target_agent:
+ sess["current_agent"] = target_agent
+ hist = sess.setdefault("agent_history", [])
+ hist.append({
+ "ts": time.time(),
+ "agent": target_agent,
+ "evidence": f"inbox@{meta.get('evidence') or 'inbox'}",
+ })
+ return effective_agent, effective_dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+
+def resolve_active_agent_for_event(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ data: dict[str, Any],
+) -> tuple[str, str | None]:
+ """优先用 tool 线索、其次用 inbox 线索,解析事件对应的 agent。"""
+ tracker = AgentIdentityResolver()
+ active_agent, dispatched = tracker.track(state_path, sid, data)
+ if scanner.is_brainstorming_call(data):
+
+ def _update(state_data: dict[str, Any]) -> None:
+ sess = st.ensure_session(state_data, sid)
+ sess["current_agent"] = "main"
+
+ st.update_state_locked(state_path, _update)
+ return "main", dispatched
+ return merge_agent_identity_from_inbox(
+ state_path,
+ sid,
+ cwd,
+ active_agent,
+ dispatched,
+ )
+
+
+class AgentIdentityResolver:
+ """基于 tool 调用内容做一轮 agent 身份推断。"""
+ def __init__(self, known_agents: set[str] | None = None):
+ self.known_agents = known_agents or set()
+
+ def extract_identity(self, data: dict) -> tuple[Optional[str], Optional[str]]:
+ tool = data.get("tool_name", "")
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ tool_input = {}
+
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+
+ if tool in MESSAGE_TOOLS:
+ extracted_current, extracted_dispatched = self._extract_from_message(tool_input)
+ if extracted_current and not current:
+ current = extracted_current
+ if extracted_dispatched and not dispatched:
+ dispatched = extracted_dispatched
+
+ if tool in DISPATCH_TOOLS and not dispatched:
+ dispatched = self._extract_from_task(tool_input)
+
+ if not current:
+ current = self._extract_from_path(data, tool_input)
+
+ if self.known_agents:
+ if current and current not in self.known_agents:
+ current = None
+ if dispatched and dispatched not in self.known_agents:
+ dispatched = None
+
+ return current, dispatched
+
+ def track(self, state_path: Path, sid: str, data: dict) -> tuple[str, Optional[str]]:
+ tool = data.get("tool_name", "")
+ cur_agent, dispatched = self.extract_identity(data)
+
+ def _update(state: dict[str, Any]) -> tuple[str, Optional[str]]:
+ sess = st.ensure_session(state, sid)
+ hist = sess.setdefault("agent_history", [])
+ prev_agent = sess.get("current_agent") or "main"
+
+ if cur_agent and cur_agent != prev_agent:
+ sess["current_agent"] = cur_agent
+ hist.append({"ts": time.time(), "agent": cur_agent, "evidence": f"from_role@{tool}"})
+ active_agent = cur_agent
+ else:
+ active_agent = prev_agent
+
+ if dispatched and dispatched != active_agent:
+ dis = sess.setdefault("dispatched", {})
+ if not isinstance(dis, dict):
+ dis = {}
+ sess["dispatched"] = dis
+ dis[dispatched] = dis.get(dispatched, 0) + 1
+ sess["current_agent"] = dispatched
+ hist.append({"ts": time.time(), "agent": dispatched, "evidence": f"dispatch@{tool}<-{active_agent}"})
+
+ if len(hist) > 100:
+ sess["agent_history"] = hist[-100:]
+
+ return active_agent, dispatched
+
+ return st.update_state_locked(state_path, _update)
+
+ def _extract_from_message(self, tool_input: dict) -> tuple[Optional[str], Optional[str]]:
+ current: Optional[str] = None
+ dispatched: Optional[str] = None
+ content = tool_input.get("content")
+
+ if isinstance(content, str) and content.strip().startswith("{"):
+ try:
+ payload = json.loads(content)
+ current = self._extract_str(payload, "from_role")
+ next_target = payload.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+ except Exception:
+ pass
+ elif isinstance(content, dict):
+ current = self._extract_str(content, "from_role")
+ next_target = content.get("next_target") or {}
+ if isinstance(next_target, dict):
+ dispatched = (
+ self._extract_str(next_target, "role_name")
+ or self._extract_str(next_target, "subagent_name")
+ )
+
+ if not dispatched:
+ recipient = tool_input.get("recipient")
+ if isinstance(recipient, str):
+ normalized = recipient.strip().lower()
+ if normalized and normalized != "main":
+ dispatched = normalized
+
+ return current, dispatched
+
+ def _extract_from_task(self, tool_input: dict) -> Optional[str]:
+ sub = (
+ # Claude Code 的 Agent 工具(非 CodeBuddy 原生 Task/team_create)用的是
+ # subagent_type 字段,不是 subagent_name——不认这个字段会导致 dispatch
+ # 统计漏掉所有走 Agent 工具派发的场景。
+ tool_input.get("subagent_type")
+ or tool_input.get("subagent_name")
+ or tool_input.get("name")
+ or tool_input.get("agent")
+ or tool_input.get("role")
+ )
+ if isinstance(sub, str) and sub.strip():
+ candidate = sub.strip().lower()
+ if "/" in candidate:
+ candidate = candidate.rsplit("/", 1)[1].replace(".md", "")
+ return candidate
+ return None
+
+ def _extract_from_path(self, data: dict, tool_input: dict) -> Optional[str]:
+ text = json.dumps(tool_input, ensure_ascii=False) + " " + (data.get("cwd") or "")
+ match = AGENT_PATH_RE.search(text)
+ if match:
+ return match.group(1).lower()
+ return None
+
+ @staticmethod
+ def _extract_str(payload: dict, key: str) -> Optional[str]:
+ value = payload.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip().lower()
+ return None
+
+
+def _config_matches_cwd(config: dict[str, Any], cwd: str) -> bool:
+ """判断 team 配置中的成员 cwd 是否覆盖当前工作目录。"""
+ members = config.get("members")
+ if not isinstance(members, list):
+ return False
+ for member in members:
+ if not isinstance(member, dict):
+ continue
+ member_cwd = member.get("cwd")
+ if isinstance(member_cwd, str) and _paths_equal(member_cwd, cwd):
+ return True
+ return False
+
+
+def _paths_equal(a: str, b: str) -> bool:
+ """按归一化绝对路径语义比较两个路径是否相等。"""
+ try:
+ return Path(a).expanduser().resolve() == Path(b).expanduser().resolve()
+ except Exception:
+ return os.path.abspath(os.path.expanduser(a)) == os.path.abspath(os.path.expanduser(b))
+
+
+def _normalize_message(item: Any, mailbox_name: str, mailbox_role: str | None, index: int) -> dict[str, Any] | None:
+ """把原始 inbox 消息归一化成统一可推断的结构。"""
+ if not isinstance(item, dict):
+ return None
+
+ text = item.get("text")
+ payload = _coerce_payload(text)
+ summary = item.get("summary") if isinstance(item.get("summary"), str) else ""
+ from_raw = item.get("from") if isinstance(item.get("from"), str) else None
+ from_role = normalize_role_name((payload.get("from") if isinstance(payload, dict) else None) or from_raw)
+ ts = _parse_timestamp(item.get("timestamp"))
+
+ return {
+ "mailbox_name": mailbox_name,
+ "mailbox_role": mailbox_role,
+ "from": from_raw,
+ "from_role": from_role,
+ "text": text if isinstance(text, str) else "",
+ "summary": summary,
+ "payload": payload,
+ "timestamp": item.get("timestamp"),
+ "ts": ts,
+ "index": index,
+ "is_shutdown": _is_shutdown_message(payload, summary, text),
+ }
+
+
+def _extract_next_target(payload: dict[str, Any] | None) -> Optional[str]:
+ """从 payload 中提取下一跳要派发给的角色。"""
+ if not isinstance(payload, dict):
+ return None
+ next_target = payload.get("next_target") or {}
+ if not isinstance(next_target, dict):
+ return None
+ return normalize_role_name(next_target.get("role_name") or next_target.get("subagent_name"))
+
+
+def _coerce_payload(text: Any) -> dict[str, Any] | None:
+ """把文本内容尽量解析成 JSON 字典。"""
+ if isinstance(text, dict):
+ return text
+ if not isinstance(text, str):
+ return None
+ stripped = text.strip()
+ if not stripped.startswith("{"):
+ return None
+ try:
+ data = json.loads(stripped)
+ if isinstance(data, dict):
+ return data
+ except Exception:
+ return None
+ return None
+
+
+def _is_shutdown_message(payload: dict[str, Any] | None, summary: str, text: Any) -> bool:
+ """识别一条 inbox 消息是否表示 agent 关闭或退出。"""
+ if isinstance(payload, dict) and str(payload.get("type") or "").lower() == "shutdown_request":
+ return True
+ summary_low = summary.lower() if isinstance(summary, str) else ""
+ text_low = text.lower() if isinstance(text, str) else ""
+ return "shutdown" in summary_low or "shutdown request" in text_low
+
+
+def _parse_timestamp(value: Any) -> float:
+ """把消息时间字段解析成 Unix 时间戳。"""
+ if not isinstance(value, str) or not value.strip():
+ return datetime.now(timezone.utc).timestamp()
+ try:
+ return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+ except Exception:
+ return datetime.now(timezone.utc).timestamp()
+
+
+def _load_json(path: Path) -> Any:
+ """安全读取 JSON 文件,失败时返回 ``None``。"""
+ try:
+ return json.loads(path.read_text("utf-8"))
+ except Exception:
+ return None
+
+
+def _safe_int(value: Any) -> int:
+ """把任意值尽量转成整数,失败时返回 0。"""
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
diff --git a/.cursor/skills/agent-observability/scripts/core/agentlens/__init__.py b/.cursor/skills/agent-observability/scripts/core/agentlens/__init__.py
new file mode 100644
index 00000000..2fea21d6
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agentlens/__init__.py
@@ -0,0 +1,9 @@
+"""可选的 AgentLens sink,用于实时镜像 trace。"""
+from .runtime import emit_post_step, emit_session_start, emit_session_stop, emit_turn_start
+
+__all__ = [
+ "emit_post_step",
+ "emit_session_start",
+ "emit_session_stop",
+ "emit_turn_start",
+]
diff --git a/.cursor/skills/agent-observability/scripts/core/agentlens/bootstrap.py b/.cursor/skills/agent-observability/scripts/core/agentlens/bootstrap.py
new file mode 100644
index 00000000..d6fc970e
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agentlens/bootstrap.py
@@ -0,0 +1,229 @@
+from __future__ import annotations
+"""AgentLens 启动辅助层。
+
+这一层负责“读入与初始化”:
+- 解析项目配置与环境变量
+- 延迟加载可选的 zhiyan 运行时
+- 缓存初始化结果,避免重复 init
+- 处理调试落盘与失败状态写回
+"""
+
+import getpass
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+
+DEFAULT_APP_NAME = "skillhub.codebuddy-hooks"
+DEFAULT_BUSINESS_SCENARIO = "codebuddy-hook"
+
+_RUNTIME: dict[str, Any] | None = None
+_INIT_SIGNATURE: tuple[str, str, str] | None = None
+
+
+@dataclass(frozen=True)
+class AgentLensConfig:
+ """从环境变量与 env 文件归一化得到的 AgentLens 配置。"""
+ endpoint: str | None
+ api_key: str | None
+ app_name: str
+ business_scenario: str
+ user: str
+
+ @property
+ def enabled(self) -> bool:
+ return bool(self.endpoint and self.api_key)
+
+
+def project_root(cwd: str | None = None) -> Path:
+ """解析用于查找 `.env` 的项目根目录。"""
+ if cwd:
+ return Path(cwd).expanduser().resolve()
+ env_cwd = str(os.environ.get("CODEBUDDY_PROJECT_DIR") or "").strip()
+ if env_cwd:
+ return Path(env_cwd).expanduser().resolve()
+ return Path.cwd().resolve()
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+ """以轻量方式解析 shell 风格的 env 文件,不做 source。"""
+ values: dict[str, str] = {}
+ if not path.is_file():
+ return values
+ try:
+ lines = path.read_text("utf-8").splitlines()
+ except Exception:
+ return values
+
+ for raw_line in lines:
+ line = raw_line.strip()
+ if not line or line.startswith("#"):
+ continue
+ if line.startswith("export "):
+ line = line[7:].strip()
+ if "=" not in line:
+ continue
+ key, value = line.split("=", 1)
+ key = key.strip()
+ value = value.strip()
+ if not key:
+ continue
+ if value and value[0] == value[-1] and value[0] in {"'", '"'}:
+ value = value[1:-1]
+ values[key] = value
+ return values
+
+
+def load_config(project_root_path: Path) -> AgentLensConfig:
+ """按优先级加载配置:进程环境变量 > `.env.local` > `.env`。"""
+ env_file = read_env_file(project_root_path / ".env")
+ env_local_file = read_env_file(project_root_path / ".env.local")
+
+ def _value(name: str, default: str | None = None) -> str | None:
+ env_value = os.environ.get(name)
+ if env_value is not None and str(env_value).strip():
+ return str(env_value).strip()
+ if name in env_local_file and str(env_local_file[name]).strip():
+ return str(env_local_file[name]).strip()
+ if name in env_file and str(env_file[name]).strip():
+ return str(env_file[name]).strip()
+ return default
+
+ user = _value("ZHIYANLLM_USER")
+ if not user:
+ user = (
+ str(os.environ.get("USER") or "").strip()
+ or str(os.environ.get("USERNAME") or "").strip()
+ or getpass.getuser()
+ )
+
+ return AgentLensConfig(
+ endpoint=_value("ZHIYANLLM_API_ENDPOINT"),
+ api_key=_value("ZHIYANLLM_API_KEY"),
+ app_name=_value("ZHIYANLLM_APP_NAME", DEFAULT_APP_NAME) or DEFAULT_APP_NAME,
+ business_scenario=_value("ZHIYANLLM_BUSINESS_SCENARIO", DEFAULT_BUSINESS_SCENARIO)
+ or DEFAULT_BUSINESS_SCENARIO,
+ user=user or "unknown",
+ )
+
+
+def load_runtime() -> dict[str, Any] | None:
+ """延迟导入可选的 zhiyan 运行时组件。
+
+ 即使本地没有安装 AgentLens 依赖,hook 主链路也必须继续工作,
+ 所以这里返回 ``None``,而不是把导入异常抛出去。
+ """
+ global _RUNTIME
+ if _RUNTIME is not None:
+ return _RUNTIME
+ try:
+ from zhiyanllm import Zhiyanllm
+ from zhiyanllm.opentelemetry.instrumentation.semconv_ai import (
+ SpanAttributes as ZhiyanSpanAttributes,
+ ZhiyanllmSpanKindValues,
+ )
+ from zhiyanllm.tracing.context_manager import get_tracer
+ from zhiyanllm.tracing.manual import track_llm_call, track_task_server_call
+ from zhiyanllm.tracing.tracing import TracerWrapper
+ from opentelemetry.context import attach as otel_attach, detach as otel_detach
+ except Exception:
+ _RUNTIME = None
+ return None
+
+ _RUNTIME = {
+ "Zhiyanllm": Zhiyanllm,
+ "track_llm_call": track_llm_call,
+ "track_task_server_call": track_task_server_call,
+ "TracerWrapper": TracerWrapper,
+ "get_tracer": get_tracer,
+ "ZhiyanSpanAttributes": ZhiyanSpanAttributes,
+ "ZhiyanllmSpanKindValues": ZhiyanllmSpanKindValues,
+ "otel_attach": otel_attach,
+ "otel_detach": otel_detach,
+ }
+ return _RUNTIME
+
+
+def ensure_initialized(config: AgentLensConfig) -> dict[str, Any] | None:
+ """仅当有效配置签名发生变化时才重新初始化 zhiyan。"""
+ global _INIT_SIGNATURE
+ if not config.enabled:
+ return None
+ runtime = load_runtime()
+ if runtime is None:
+ return None
+ signature = (str(config.endpoint), str(config.api_key), str(config.app_name))
+ if _INIT_SIGNATURE == signature:
+ return runtime
+ runtime["Zhiyanllm"].init(
+ app_name=str(config.app_name),
+ api_endpoint=str(config.endpoint),
+ api_key=str(config.api_key),
+ disable_batch=True,
+ )
+ _INIT_SIGNATURE = signature
+ return runtime
+
+
+def project_root_from_state_path(state_path: Path) -> Path:
+ """尽力从 `logs/.state.json` 反推出项目根目录。"""
+ try:
+ current = state_path.resolve().parent
+ for parent in [current, *current.parents]:
+ if parent.name == ".codebuddy":
+ return parent.parent
+ return state_path.resolve().parents[4]
+ except Exception:
+ return Path.cwd().resolve()
+
+
+def debug_enabled(state_path: Path) -> bool:
+ """判断是否要把 span 调试信息镜像写入 `agentlens-push-debug.ndjson`。"""
+ root = project_root_from_state_path(state_path)
+ env_file = read_env_file(root / ".env")
+ env_local_file = read_env_file(root / ".env.local")
+ raw = (
+ os.environ.get("AGENTLENS_PUSH_DEBUG")
+ or env_local_file.get("AGENTLENS_PUSH_DEBUG")
+ or env_file.get("AGENTLENS_PUSH_DEBUG")
+ or ""
+ )
+ return str(raw).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def debug_write_span(
+ state_path: Path | None,
+ sid: str | None,
+ payload: dict[str, Any],
+ *,
+ sanitizer,
+) -> None:
+ """在开启 AgentLens 调试模式时追加写入清洗后的调试记录。"""
+ if state_path is None or not sid:
+ return
+ try:
+ if not debug_enabled(state_path):
+ return
+ debug_path = state_path.parent / "agentlens-push-debug.ndjson"
+ record = {"sid": sid, **sanitizer(payload)}
+ with debug_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+ except Exception:
+ return
+
+
+def set_failure(state_path: Path, sid: str, message: str) -> None:
+ """记录最近一次 AgentLens 失败,但不打断 hook 主流程。"""
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": False, "last_error": str(message)},
+ )
+
+
+def get_session_context(state_path: Path, sid: str) -> dict[str, Any]:
+ """从共享状态里读取 AgentLens sidecar 的 session payload。"""
+ return st.load_agentlens_session(state_path, sid)
diff --git a/.cursor/skills/agent-observability/scripts/core/agentlens/normalize.py b/.cursor/skills/agent-observability/scripts/core/agentlens/normalize.py
new file mode 100644
index 00000000..2b730f06
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agentlens/normalize.py
@@ -0,0 +1,323 @@
+from __future__ import annotations
+"""AgentLens 负载清洗层。
+
+这一层负责“清洗与整形”:
+- 在发送或调试前把任意 payload 转成安全的 JSON 结构
+- 把本地 token 结构归一化成类似 OpenAI 的 usage 结构
+- 从 transcript 中重建轻量的 message / tool-call 上下文
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig
+
+
+def sanitize_payload(value: Any) -> Any:
+ """把任意 Python 值转换成适合调试/打点的 JSON 安全结构。"""
+ try:
+ return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+ except Exception:
+ return str(value)
+
+
+def association_properties(config: AgentLensConfig, sid: str, state_path: Path | None = None) -> dict[str, str]:
+ """构造 trace 级关联属性,并允许按 turn 覆盖业务场景。"""
+ scenario = config.business_scenario
+ if state_path:
+ try:
+ session_ctx = st.load_agentlens_session(state_path, sid)
+ turn_scenario = session_ctx.get("_turn_business_scenario")
+ if isinstance(turn_scenario, str) and turn_scenario.strip():
+ scenario = turn_scenario.strip()
+ except Exception:
+ pass
+ return {
+ "session_id": sid,
+ "business_scenario": scenario,
+ "user": config.user,
+ }
+
+
+def to_openai_usage(tokens: dict[str, Any] | None) -> dict[str, int]:
+ """把本地 token 结构转换成 zhiyan 期望的 usage 形状。"""
+ if not isinstance(tokens, dict):
+ return {}
+
+ def _int(v: Any) -> int:
+ try:
+ return int(v or 0)
+ except Exception:
+ return 0
+
+ prompt = _int(tokens.get("input"))
+ completion = _int(tokens.get("output"))
+ if prompt <= 0 and completion <= 0:
+ return {}
+ return {"prompt_tokens": prompt, "completion_tokens": completion, "total_tokens": prompt + completion}
+
+
+def infer_vendor(model: str | None) -> str:
+ """根据模型名推断一个粗粒度的 provider/vendor 标签。"""
+ text = str(model or "").strip().lower()
+ if not text:
+ return "unknown"
+ if "gpt" in text or "openai" in text:
+ return "openai"
+ if "claude" in text or "anthropic" in text:
+ return "anthropic"
+ if "gemini" in text or "google" in text:
+ return "google"
+ if text.startswith("hy") or "hunyuan" in text:
+ return "tencent"
+ return text.split("/", 1)[0].split("-", 1)[0] or "unknown"
+
+
+def extract_message_text(content: Any) -> str:
+ """把嵌套的 transcript message 内容压平成纯文本。"""
+ if content is None:
+ return ""
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts: list[str] = []
+ for item in content:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif item.get("type") == "tool_use":
+ parts.append(f"[tool_use {item.get('name', '')}]")
+ elif item.get("type") == "tool_result":
+ parts.append(extract_message_text(item.get("content")))
+ else:
+ parts.append(str(item))
+ return "\n".join(p for p in parts if p)
+ if isinstance(content, dict):
+ return extract_message_text(content.get("text") or content.get("content"))
+ return str(content)
+
+
+def find_message_id_in_record(obj: Any) -> str | None:
+ """在 transcript 记录里递归查找稳定的 message 标识。"""
+ message_id_keys = ("messageId", "responseId", "requestId")
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in message_id_keys:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in message_id_keys:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in message_id_keys:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for value in obj.values():
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ elif isinstance(obj, list):
+ for value in obj:
+ found = find_message_id_in_record(value)
+ if found:
+ return found
+ return None
+
+
+def collect_tool_calls_for_message(transcript_path: str, message_id: str) -> list[dict[str, Any]]:
+ """为指定 assistant message 重建它挂载的 tool-call 摘要。"""
+ if not transcript_path or not message_id or not os.path.isfile(transcript_path):
+ return []
+ try:
+ with open(transcript_path, "rb") as fp:
+ blob = fp.read()
+ except Exception:
+ return []
+
+ tool_calls: list[dict[str, Any]] = []
+ for raw_line in blob.splitlines(keepends=True):
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("type") or "").strip().lower() != "function_call":
+ continue
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid != message_id:
+ continue
+ call_id = str(rec.get("callId") or "").strip()
+ name = str(rec.get("name") or "").strip()
+ arguments = rec.get("arguments")
+ entry: dict[str, Any] = {"id": call_id, "name": name}
+ if arguments is not None:
+ entry["arguments"] = arguments if isinstance(arguments, str) else json.dumps(arguments, ensure_ascii=False)
+ tool_calls.append(entry)
+ return tool_calls
+
+
+def find_tool_usage_event(tool_event: dict[str, Any], usage_events: list[dict[str, Any]]) -> dict[str, Any] | None:
+ """从 usage 列表里挑出最可能属于当前 tool 事件的那一条。"""
+ tool_name = str(tool_event.get("tool") or "")
+ transcript_path = str(tool_event.get("transcript_path") or "")
+ agent = str(tool_event.get("agent") or "main")
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ if tool_name and str(usage_event.get("tool") or "") not in {tool_name, "model_request"}:
+ continue
+ if str(usage_event.get("message_id") or "").strip():
+ return usage_event
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if str(usage_event.get("agent") or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "") != transcript_path:
+ continue
+ return usage_event
+ return None
+
+
+def build_llm_io_from_transcript(
+ *,
+ transcript_path: str,
+ source_offset: int,
+ tokens: dict[str, Any] | None,
+ model: str | None,
+ start_offset: int = 0,
+ current_message_id: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], str]:
+ """从 transcript 历史中构造紧凑版的 LLM 输入/输出负载。"""
+ input_data: dict[str, Any] = {"model": str(model or "unknown"), "messages": []}
+ output_data: dict[str, Any] = {"choices": [], "usage": to_openai_usage(tokens)}
+ if not transcript_path or not os.path.isfile(transcript_path):
+ return input_data, output_data, ""
+ try:
+ with open(transcript_path, "rb") as fp:
+ fp.seek(0)
+ blob = fp.read(source_offset) if source_offset else fp.read()
+ except Exception:
+ return input_data, output_data, ""
+
+ messages: list[dict[str, Any]] = []
+ system_prompts: list[str] = []
+ cursor = 0
+ last_asst_text: str | None = None
+
+ def _truncate(text: str, limit: int = 4000) -> str:
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ for raw_line in blob.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ rec = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+ if not isinstance(rec, dict):
+ continue
+
+ rec_type = str(rec.get("type") or "").strip().lower()
+ is_incremental = cursor > start_offset
+
+ # 重建 prompt 上下文时要跳过“当前正在发出的 assistant message”,
+ # 否则同一段回复会同时出现在 input 和 output 两边。
+ if current_message_id and is_incremental:
+ rec_mid = find_message_id_in_record(rec)
+ if rec_mid == current_message_id:
+ if rec_type == "message" and rec.get("role") == "assistant":
+ text = extract_message_text(rec.get("content"))
+ if text:
+ last_asst_text = text
+ continue
+
+ if rec_type == "message":
+ role = rec.get("role")
+ text = extract_message_text(rec.get("content"))
+ if not text:
+ continue
+ if role == "system":
+ system_prompts.append(text)
+ elif is_incremental:
+ if role == "user":
+ messages.append({"role": "user", "content": _truncate(text, 8000)})
+ last_asst_text = None
+ elif role == "assistant":
+ messages.append({"role": "assistant", "content": _truncate(text, 4000)})
+ last_asst_text = text
+ elif is_incremental:
+ # 把 function call / result 记录转换成 Chat Completions 风格的
+ # assistant/tool message,方便 tracing UI 按对话链路展示。
+ if rec_type == "function_call":
+ name = str(rec.get("name") or "").strip()
+ call_id = str(rec.get("callId") or "").strip()
+ arguments = rec.get("arguments", "")
+ if isinstance(arguments, dict):
+ arguments = json.dumps(arguments, ensure_ascii=False)
+ tool_call: dict[str, Any] = {"type": "function", "function": {"name": name}}
+ if name and arguments:
+ tool_call["function"]["arguments"] = _truncate(str(arguments), 2000)
+ if call_id:
+ tool_call["id"] = call_id
+ if (
+ messages
+ and messages[-1].get("role") == "assistant"
+ and "tool_calls" not in messages[-1]
+ and messages[-1].get("content")
+ ):
+ messages[-1]["tool_calls"] = [tool_call]
+ else:
+ msg: dict[str, Any] = {"role": "assistant", "content": ""}
+ msg["tool_calls"] = [tool_call]
+ messages.append(msg)
+ elif rec_type == "function_call_result":
+ call_id = str(rec.get("callId") or "").strip()
+ provider = rec.get("providerData", {})
+ result_content = ""
+ if isinstance(provider, dict):
+ tool_result = provider.get("toolResult", {})
+ if isinstance(tool_result, dict):
+ result_content = extract_message_text(tool_result.get("content"))
+ if not result_content:
+ output = rec.get("output")
+ result_content = str(output.get("text", "")) if isinstance(output, dict) else ""
+ tool_msg: dict[str, Any] = {"role": "tool", "content": _truncate(result_content, 2000)}
+ if call_id:
+ tool_msg["tool_call_id"] = call_id
+ messages.append(tool_msg)
+
+ final_messages: list[dict[str, Any]] = []
+ for prompt in system_prompts[-2:]:
+ if prompt:
+ final_messages.append({"role": "system", "content": _truncate(prompt, 2000)})
+ final_messages.extend(messages)
+ input_data["messages"] = final_messages
+
+ if last_asst_text is not None:
+ output_data["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": last_asst_text[:8000]},
+ }]
+
+ return input_data, output_data, ""
diff --git a/.cursor/skills/agent-observability/scripts/core/agentlens/runtime.py b/.cursor/skills/agent-observability/scripts/core/agentlens/runtime.py
new file mode 100644
index 00000000..321f45a9
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agentlens/runtime.py
@@ -0,0 +1,761 @@
+"""AgentLens 运行时编排层。
+
+这一层保留对外暴露的 4 个入口:
+- `emit_session_start`
+- `emit_turn_start`
+- `emit_post_step`
+- `emit_session_stop`
+
+它本身不负责底层清洗或 carrier 生成,而是把调用编排到
+`bootstrap / normalize / tracing` 三层上。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from opentelemetry import trace as _otel_trace
+
+from .. import state as st
+from .bootstrap import (
+ debug_write_span as _debug_write_span,
+ ensure_initialized as _ensure_initialized,
+ get_session_context as _get_session_context,
+ load_config,
+ project_root as _project_root,
+ set_failure as _set_failure,
+)
+from .normalize import (
+ association_properties as _association_properties,
+ build_llm_io_from_transcript as _build_llm_io_from_transcript,
+ find_tool_usage_event as _find_tool_usage_event,
+ infer_vendor as _infer_vendor,
+ sanitize_payload as _sanitize_payload,
+ to_openai_usage as _to_openai_usage,
+)
+from .tracing import (
+ annotate as _annotate,
+ emit_assistant_span as _emit_assistant_span,
+ emit_tool_span as _emit_tool_span,
+ generate_subagent_carrier as _generate_subagent_carrier,
+ generate_turn_carrier as _generate_turn_carrier,
+ resolve_agent_carrier as _resolve_agent_carrier,
+ resolve_step_carrier as _resolve_step_carrier,
+ set_agent_aggregate_on_span as _set_agent_aggregate_on_span,
+ span_context_ids as _span_context_ids,
+ traceparent_parts as _traceparent_parts,
+)
+
+
+def emit_session_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ agent: str = "main",
+) -> None:
+ """初始化 v2 版本的 `_agentlens` session payload。
+
+ 在 turn-centric 模型下,这里**不再**生成 trace_id。
+ 它只负责记录 session 级元数据(如 `enabled`、`session_id`、`app_name`),
+ 并清理上一次运行遗留的 carrier / error 状态。
+ 真正的新 trace 会在第一次 `UserPromptSubmit` 时由 `emit_turn_start` 打开。
+ """
+ _ = agent
+ config = load_config(_project_root(cwd))
+ # 注意:这里不要清空 current_turn / turn_history。
+ # 同一个 sid 下 SessionStart 可能多次触发(例如 subagent 启动、IDE 刷新、
+ # workspace 切换)。如果这里清空,会把进行中的 turn 擦掉,后续 PostToolUse
+ # 会全部看到 no_active_turn,最终把这一轮观测链路打断。
+ base_updates: dict[str, Any] = {
+ "session_id": sid,
+ "app_name": config.app_name,
+ }
+ if not config.enabled:
+ base_updates["enabled"] = False
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ base_updates["enabled"] = True
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ base_updates,
+ clear_keys=["carrier", "last_error"],
+ )
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_turn_start(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ turn_id: str,
+ prompt_meta: dict[str, Any] | None = None,
+ business_scenario: str | None = None,
+) -> None:
+ """打开一个新的 turn,生成新的 trace_id 并写入 `_agentlens.current_turn`。
+
+ 这是当前实现里**唯一**允许生成新 trace_id 的地方。
+ `emit_post_step` / `emit_session_stop` 都不会重新造 carrier;
+ 找不到时只会优雅降级,不会私自开新链路。
+ """
+ _ = prompt_meta
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+ # 先把 per-turn business scenario 写进 state,
+ # 这样 `_generate_turn_carrier -> _association_properties`
+ # 才能在生成 trace 时把这次 turn 的业务场景烘焙进去。
+ if business_scenario:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name, "_turn_business_scenario": business_scenario},
+ clear_keys=["last_error"],
+ )
+ else:
+ st.update_agentlens_session(
+ state_path,
+ sid,
+ {"enabled": True, "session_id": sid, "app_name": config.app_name},
+ clear_keys=["last_error", "_turn_business_scenario"],
+ )
+ carrier = _generate_turn_carrier(runtime, config=config, sid=sid, turn_id=turn_id, state_path=state_path)
+ st.begin_turn(state_path, sid, turn_id, carrier)
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_post_step(
+ *,
+ state_path: Path,
+ sid: str,
+ tool_event: dict[str, Any] | None,
+ usage_events: list[dict[str, Any]],
+) -> None:
+ """发出扁平化的 LLM span,只保留最小 TASK 包装层来传播 carrier 上下文。
+
+ 面向 turn 的 v2 约束:
+ - 活跃的 ``current_turn.carrier`` 是唯一的 trace 上下文来源。
+ - 如果不存在 ``current_turn``(例如 UserPromptSubmit hook 还没触发),
+ 这里只会记录 ``last_error`` 并返回,不会私自生成新的 trace_id。
+ - subagent(``active_agent != "main"``)会拿到当前 turn 下的
+ ``invoke_agent`` 子 span,后续 chat span 都挂到这个子 span 下,
+ 以保持因果链路连续。
+ """
+ if not isinstance(tool_event, dict) and not usage_events:
+ return
+
+ cwd_hint = ""
+ if isinstance(tool_event, dict):
+ cwd_hint = str(tool_event.get("cwd") or "")
+ config = load_config(_project_root(cwd_hint))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ # 快路径:尊重 SessionStart 阶段已经写入的 enabled 标记。
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ parent_carrier = current_turn.get("carrier")
+ if not isinstance(parent_carrier, dict) or not parent_carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ tool_name = str((tool_event or {}).get("tool") or "unknown_tool")
+ active_agent = str((tool_event or {}).get("agent") or "main")
+ transcript_path = str((tool_event or {}).get("transcript_path") or "")
+ skills = (tool_event or {}).get("skill") or []
+ rules = (tool_event or {}).get("rule") or []
+
+ # 解析这次事件真正要用的 carrier。
+ # main agent 直接使用 turn 根 carrier;subagent 则使用按角色拆分的
+ # 子 span carrier,并在当前 turn 下做幂等注册。
+ carrier = dict(parent_carrier)
+ if active_agent and active_agent != "main":
+ existing = None
+ subs = current_turn.get("subagent_spans")
+ if isinstance(subs, dict):
+ rec = subs.get(active_agent)
+ if isinstance(rec, dict) and isinstance(rec.get("carrier"), dict):
+ existing = rec["carrier"]
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ carrier = dict(existing)
+ else:
+ # 原子化的 get-or-create:只有确认 subagent span 不存在时,
+ # 才会在写锁内部调用 carrier_factory。
+ # 这样可以避免并发 hook 进程之间的 TOCTOU 竞争,产生孤儿
+ # invoke_agent.TASK span。
+ def _factory() -> dict[str, str]:
+ return _generate_subagent_carrier(
+ runtime, parent_carrier=parent_carrier, role=active_agent
+ )
+
+ registered = st.upsert_subagent_span_atomic(
+ state_path, sid, active_agent, carrier_factory=_factory
+ )
+ if isinstance(registered, dict) and registered.get("traceparent"):
+ carrier = dict(registered)
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ # 静默挂载 carrier 上下文(不额外创建 TASK span),让内部 span
+ # 继承正确的 trace_id / parent_id。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ preferred_tool_message_id = str((tool_event or {}).get("message_id") or "").strip() or None
+ _assistant_emitted_mids: set[str] = set()
+ pre_bumped_steps: set[tuple[str, str]] = set()
+ committed_steps: set[tuple[str, str]] = set()
+
+ if isinstance(tool_event, dict):
+ if preferred_tool_message_id and st.get_step_span_carrier(
+ state_path, sid, active_agent, preferred_tool_message_id
+ ) is None:
+ pre_bumped_steps.add((active_agent, preferred_tool_message_id))
+ for usage_event in usage_events:
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ if event_message_id:
+ step_key = (event_agent, event_message_id)
+ if (
+ step_key not in pre_bumped_steps
+ and st.get_step_span_carrier(state_path, sid, event_agent, event_message_id) is None
+ ):
+ pre_bumped_steps.add(step_key)
+ if not usage_events and isinstance(tool_event, dict):
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if preferred_tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=preferred_tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=preferred_tool_message_id,
+ step_grouping="message_id" if preferred_tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if (
+ preferred_tool_message_id
+ and (active_agent, preferred_tool_message_id) in pre_bumped_steps
+ and (active_agent, preferred_tool_message_id) not in committed_steps
+ ):
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add((active_agent, preferred_tool_message_id))
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ return
+
+ matched_usage = _find_tool_usage_event(tool_event, usage_events) if isinstance(tool_event, dict) else None
+ tool_message_id = preferred_tool_message_id or str((matched_usage or {}).get("message_id") or "").strip() or None
+ if isinstance(tool_event, dict):
+ # 先构造 assistant 预览,再打开 agent/step 父 span。
+ # 这样即便 transcript 重建失败,也不会留下空的分组 TASK。
+ _assistant_preview_content: str | None = None
+ _assistant_preview_transcript = transcript_path
+ _assistant_preview_model = ""
+ if tool_message_id:
+ for _ue in usage_events:
+ if str(_ue.get("message_id") or "").strip() != tool_message_id:
+ continue
+ _ue_transcript = str(_ue.get("transcript_path") or transcript_path)
+ _ue_offset = int(_ue.get("source_offset") or 0)
+ _, _llm_out_pre, _ = _build_llm_io_from_transcript(
+ transcript_path=_ue_transcript,
+ source_offset=_ue_offset,
+ tokens=_ue.get("tokens"),
+ model=str(_ue.get("model") or ""),
+ )
+ _pre_content = ""
+ if _llm_out_pre.get("choices"):
+ _pre_msg = _llm_out_pre["choices"][0].get("message") or {}
+ _pre_content = str(_pre_msg.get("content") or "")
+ if _pre_content and _pre_content.strip():
+ _assistant_preview_content = _pre_content
+ _assistant_preview_transcript = _ue_transcript
+ _assistant_preview_model = str(_ue.get("model") or "")
+ break
+
+ tool_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=active_agent,
+ )
+ if tool_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ transcript_path=transcript_path,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ tool_parent_carrier = dict(step_carrier)
+ if _assistant_preview_content and tool_message_id:
+ _emit_assistant_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ agent=active_agent,
+ message_id=tool_message_id,
+ assistant_text=_assistant_preview_content,
+ model=_assistant_preview_model,
+ transcript_path=_assistant_preview_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ _assistant_emitted_mids.add(tool_message_id)
+
+ _emit_tool_span(
+ runtime,
+ carrier=tool_parent_carrier,
+ tool_name=tool_name,
+ active_agent=active_agent,
+ skills=skills,
+ rules=rules,
+ duration_ms=tool_event.get("ms") if isinstance(tool_event.get("ms"), (int, float)) else None,
+ tool_details=tool_event.get("tool_details") if isinstance(tool_event.get("tool_details"), dict) else None,
+ message_id=tool_message_id,
+ step_grouping="message_id" if tool_message_id else "fallback",
+ state_path=state_path,
+ sid=sid,
+ )
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ tool_event=tool_event,
+ )
+ if tool_message_id and (active_agent, tool_message_id) in pre_bumped_steps:
+ step_key = (active_agent, tool_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ active_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+
+ _prev_llm_offsets: dict[str, int] = {}
+ for usage_event in usage_events:
+ model = str(usage_event.get("model") or "")
+ ev_transcript = str(usage_event.get("transcript_path") or transcript_path)
+ ev_offset = int(usage_event.get("source_offset") or 0)
+ raw_tokens = usage_event.get("tokens") or {}
+ event_message_id = str(usage_event.get("message_id") or "").strip() or None
+ event_agent = str(usage_event.get("agent") or active_agent or "main")
+ start_offset = _prev_llm_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_llm_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset)
+ # --- 把 skill/rule/agent 作为独立消息标签注入 input_data ---
+ _meta_messages: list[dict[str, str]] = []
+ _ev_agent = str(usage_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ _meta_messages.append({"role": "agent", "content": _ev_agent})
+ if skills:
+ _meta_messages.append({"role": "skill", "content": ", ".join(skills)})
+ if rules:
+ _meta_messages.append({"role": "rule", "content": ", ".join(rules)})
+ if _meta_messages:
+ llm_input.setdefault("messages", [])
+ for msg in reversed(_meta_messages):
+ llm_input["messages"].insert(0, msg)
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 只附带成本细节来构造 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": usage_event.get("cost_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ if event_message_id:
+ event_parent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 先累计聚合值,再发 LLM span,这样 span 上带的是最新累计属性。
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ usage_event=usage_event,
+ )
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(usage_event.get("cost_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if event_message_id and (event_agent, event_message_id) in pre_bumped_steps:
+ step_key = (event_agent, event_message_id)
+ if step_key not in committed_steps:
+ st.bump_agent_aggregate(
+ state_path,
+ sid,
+ event_agent,
+ step_created=True,
+ )
+ committed_steps.add(step_key)
+ if _existing_content and _existing_content.strip() and event_message_id not in _assistant_emitted_mids:
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
+
+
+def emit_session_stop(
+ *,
+ state_path: Path,
+ sid: str,
+ cwd: str,
+ active_agent: str,
+ transcript_path: str,
+ stop_events: list[dict[str, Any]],
+) -> None:
+ """在 session stop 阶段发出扁平化 LLM span,只保留最小 TASK 包装层传播上下文。"""
+ config = load_config(_project_root(cwd))
+ if not config.enabled:
+ return
+
+ session_ctx = _get_session_context(state_path, sid)
+ if session_ctx.get("enabled") is False:
+ return
+
+ current_turn = session_ctx.get("current_turn")
+ if not isinstance(current_turn, dict):
+ _set_failure(state_path, sid, "no_active_turn")
+ return
+ carrier = current_turn.get("carrier")
+ if not isinstance(carrier, dict) or not carrier.get("traceparent"):
+ _set_failure(state_path, sid, "no_active_turn_carrier")
+ return
+
+ try:
+ runtime = _ensure_initialized(config)
+ if runtime is None:
+ _set_failure(state_path, sid, "zhiyanllm runtime unavailable")
+ return
+
+ runtime["Zhiyanllm"].set_association_properties(_association_properties(config, sid, state_path))
+ if not stop_events:
+ return
+ # 静默挂载 carrier 上下文(不额外创建 TASK span)。
+ _ctx = runtime["TracerWrapper"].extract_context(carrier)
+ _token = runtime["otel_attach"](_ctx)
+ try:
+ _prev_stop_offsets: dict[str, int] = {}
+ for stop_event in stop_events:
+ model = str(stop_event.get("model") or "")
+ ev_transcript = str(stop_event.get("transcript_path") or transcript_path)
+ ev_offset = int(stop_event.get("source_offset") or 0)
+ raw_tokens = stop_event.get("tokens") or {}
+ event_message_id = str(stop_event.get("message_id") or "").strip() or None
+ event_agent = str(stop_event.get("agent") or active_agent or "main")
+ start_offset = _prev_stop_offsets.get(ev_transcript) or st.get_last_llm_offset(
+ st.load_state(state_path), sid, ev_transcript
+ )
+ llm_input, llm_output, _turn_title = _build_llm_io_from_transcript(
+ transcript_path=ev_transcript,
+ source_offset=ev_offset,
+ start_offset=int(start_offset or 0),
+ current_message_id=event_message_id,
+ tokens=raw_tokens,
+ model=model or None,
+ )
+ _prev_stop_offsets[ev_transcript] = ev_offset
+ # 原子写回 state,供跨进程增量跟踪复用
+ def _update_llm_offset_stop(state: dict[str, Any], _ev=ev_transcript, _off=ev_offset) -> None:
+ st.set_last_llm_offset(state, sid, _off, _ev)
+ st.update_state_locked(state_path, _update_llm_offset_stop)
+ # --- 把 agent 作为独立消息标签注入 input_data ---
+ _ev_agent = str(stop_event.get("agent") or active_agent)
+ if _ev_agent and _ev_agent != "main":
+ llm_input.setdefault("messages", []).insert(0, {"role": "agent", "content": _ev_agent})
+ # --- 构造 usage ---
+ llm_output["usage"] = _to_openai_usage(raw_tokens)
+ # --- 构造带上下文和成本细节的 output 内容 ---
+ _cost_info = {
+ "input_tokens": raw_tokens.get("input"),
+ "output_tokens": raw_tokens.get("output"),
+ "cache_read": raw_tokens.get("cache_read"),
+ "cache_creation": raw_tokens.get("cache_creation"),
+ "total_tokens": raw_tokens.get("total"),
+ "cost_usd": stop_event.get("cost_usd"),
+ "cost_session_usd": stop_event.get("cost_session_usd"),
+ }
+ _cost_info = {k: v for k, v in _cost_info.items() if v is not None}
+ _existing_content = ""
+ if llm_output.get("choices"):
+ _msg = llm_output["choices"][0].get("message") or {}
+ _existing_content = str(_msg.get("content") or "")
+ _output_content = _existing_content
+ if _cost_info:
+ _cost_line = " | ".join(f"{k}: {v}" for k, v in _cost_info.items())
+ _output_content = f"[{_cost_line}]\n{_existing_content}" if _existing_content else f"[{_cost_line}]"
+ llm_output["choices"] = [{
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": _output_content},
+ }]
+ event_parent_carrier = carrier
+ # 先解析 agent carrier,让 step 挂在 agent 的 react_agent span 下,
+ # 而不是直接挂在 turn 根 span 下。
+ if event_agent and event_agent != "main":
+ agent_carrier = _resolve_agent_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=carrier,
+ agent=event_agent,
+ )
+ if isinstance(agent_carrier, dict) and agent_carrier.get("traceparent"):
+ event_parent_carrier = dict(agent_carrier)
+ if event_message_id:
+ step_carrier = _resolve_step_carrier(
+ state_path=state_path,
+ sid=sid,
+ runtime=runtime,
+ parent_carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ transcript_path=ev_transcript,
+ )
+ if isinstance(step_carrier, dict) and step_carrier.get("traceparent"):
+ event_parent_carrier = dict(step_carrier)
+ ev_ctx = runtime["TracerWrapper"].extract_context(event_parent_carrier)
+ ev_token = runtime["otel_attach"](ev_ctx)
+ # 这里不要再 bump,emit_post_step 已经累计过这条 usage_event。
+ # SessionStop 会为同一次调用补发一个重复的 LLM span,再累加就会双算。
+ # 因此这里只读取当前聚合值。
+ _current_agg = st.get_subagent_aggregate(state_path, sid, event_agent)
+ try:
+ with runtime["track_llm_call"](_infer_vendor(model), "model_request") as llm_span:
+ # track_llm_call 已经设置了 gen_ai.span.kind/system/operation.name。
+ # 下方 _annotate 会通过 handle_llm_response 设置 gen_ai.usage.*。
+ # LLMSpan 包装层没有 set_attribute,所以这里改用原生 span 写 ID。
+ _native_span = _otel_trace.get_current_span()
+ _set_agent_aggregate_on_span(_native_span, _current_agg)
+ span_ids = _span_context_ids(_native_span)
+ parent_parts = _traceparent_parts(event_parent_carrier)
+ _debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "llm",
+ "span_name": "model_request",
+ "model": model,
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ "agent": event_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": ev_transcript,
+ "source_offset": ev_offset,
+ },
+ sanitizer=_sanitize_payload,
+ )
+ _annotate(
+ runtime,
+ span=llm_span,
+ input_data=llm_input,
+ output_data=llm_output,
+ tags={
+ "cost_usd": str(stop_event.get("cost_usd") or "-"),
+ "cost_session_usd": str(stop_event.get("cost_session_usd") or "-"),
+ "input_tokens": str(raw_tokens.get("input", "-")),
+ "output_tokens": str(raw_tokens.get("output", "-")),
+ "cache_read": str(raw_tokens.get("cache_read", "-")),
+ "cache_creation": str(raw_tokens.get("cache_creation", "-")),
+ "total_tokens": str(raw_tokens.get("total", "-")),
+ "message_id": str(event_message_id or ""),
+ "step_grouping": "message_id" if event_message_id else "fallback",
+ },
+ )
+ finally:
+ runtime["otel_detach"](ev_token)
+ if _existing_content and _existing_content.strip():
+ _emit_assistant_span(
+ runtime,
+ carrier=event_parent_carrier,
+ agent=event_agent,
+ message_id=event_message_id,
+ assistant_text=_existing_content,
+ model=model,
+ transcript_path=ev_transcript,
+ state_path=state_path,
+ sid=sid,
+ )
+ finally:
+ runtime["otel_detach"](_token)
+ st.update_agentlens_session(state_path, sid, {"enabled": True}, clear_keys=["last_error"])
+ except Exception as exc:
+ _set_failure(state_path, sid, str(exc))
diff --git a/.cursor/skills/agent-observability/scripts/core/agentlens/tracing.py b/.cursor/skills/agent-observability/scripts/core/agentlens/tracing.py
new file mode 100644
index 00000000..afb678ad
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/agentlens/tracing.py
@@ -0,0 +1,504 @@
+from __future__ import annotations
+"""AgentLens trace 拓扑层。
+
+这一层负责“trace 结构本身”:
+- 创建或派生 carrier
+- 生成 agent / step / assistant / tool span
+- 把后续聚合需要的 span 元数据写回 state
+"""
+
+import json
+import secrets
+from pathlib import Path
+from typing import Any
+
+from .. import state as st
+from .bootstrap import AgentLensConfig, debug_write_span
+from .normalize import association_properties, collect_tool_calls_for_message, sanitize_payload
+
+
+def annotate(runtime: dict[str, Any], *, span: Any | None = None, input_data: Any = None, output_data: Any = None, tags: dict[str, Any] | None = None) -> None:
+ """在调用 zhiyan annotate 前,先统一清洗 payload。"""
+ _ = span
+ runtime["Zhiyanllm"].annotate(
+ input_data=sanitize_payload(input_data),
+ output_data=sanitize_payload(output_data),
+ tags=sanitize_payload(tags) if tags else None,
+ )
+
+
+def traceparent_parts(carrier: dict[str, str] | None) -> dict[str, str]:
+ """把 W3C `traceparent` 拆成调试日志里常用的几个字段。"""
+ traceparent = str((carrier or {}).get("traceparent") or "").strip()
+ parts = traceparent.split("-")
+ if len(parts) >= 4:
+ return {
+ "traceparent": traceparent,
+ "trace_id": parts[1],
+ "span_id": parts[2],
+ "flags": parts[3],
+ }
+ return {"traceparent": traceparent}
+
+
+def span_context_ids(span: Any) -> dict[str, str]:
+ """从 OTel span 对象中提取十六进制的 trace/span id。"""
+ try:
+ ctx = span.get_span_context()
+ return {
+ "trace_id": f"{int(ctx.trace_id):032x}",
+ "span_id": f"{int(ctx.span_id):016x}",
+ }
+ except Exception:
+ return {}
+
+
+def ensure_traceparent(carrier: dict[str, str]) -> None:
+ """当上游没有成功注入时,补一个最小可用的 `traceparent`。"""
+ if str(carrier.get("traceparent") or "").strip():
+ return
+ trace_id = secrets.token_hex(16)
+ parent_id = secrets.token_hex(8)
+ carrier["traceparent"] = f"00-{trace_id}-{parent_id}-01"
+
+
+def carrier_from_span(parent_carrier: dict[str, str], span: Any) -> dict[str, str]:
+ """基于父 carrier 和当前 span 生成一个仍在同一 trace 上的子 carrier。"""
+ try:
+ span_ctx = span.get_span_context()
+ trace_id = f"{int(span_ctx.trace_id):032x}"
+ span_id = f"{int(span_ctx.span_id):016x}"
+ except Exception:
+ return {}
+ parent_tp = str((parent_carrier or {}).get("traceparent") or "").strip()
+ flags = "01"
+ if parent_tp:
+ parts = parent_tp.split("-")
+ if len(parts) >= 4 and parts[3]:
+ flags = parts[3]
+ child_carrier: dict[str, str] = dict(parent_carrier or {})
+ child_carrier["traceparent"] = f"00-{trace_id}-{span_id}-{flags}"
+ return child_carrier
+
+
+def carrier_from_task_span(parent_carrier: dict[str, str], task_span: Any) -> dict[str, str]:
+ """兼容包装过的 task span 和原始 OTel span 两种形态。"""
+ span = getattr(task_span, "_span", None)
+ if span is None and hasattr(task_span, "get_span_context"):
+ span = task_span
+ if span is None:
+ return {}
+ return carrier_from_span(parent_carrier, span)
+
+
+def zhiyan_attr(runtime: dict[str, Any], name: str, fallback: str) -> str:
+ """防御式读取 zhiyan 语义约定常量。"""
+ return str(getattr(runtime.get("ZhiyanSpanAttributes"), name, fallback))
+
+
+def generate_turn_carrier(
+ runtime: dict[str, Any],
+ *,
+ config: AgentLensConfig,
+ sid: str,
+ turn_id: str,
+ state_path: Path | None = None,
+) -> dict[str, str]:
+ """为一个用户 turn 生成根 carrier。"""
+ from opentelemetry import trace
+
+ carrier: dict[str, str] = {}
+ span = trace.get_tracer(__name__).start_span(f"turn.{sid}.{turn_id}")
+ try:
+ runtime["Zhiyanllm"].set_association_properties(association_properties(config, sid, state_path))
+ runtime["Zhiyanllm"].inject_context(carrier)
+ finally:
+ span.end()
+ ensure_traceparent(carrier)
+ return carrier
+
+
+def generate_subagent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], role: str) -> dict[str, str]:
+ """在当前 turn 下面创建 `invoke_agent` 子 carrier。"""
+ try:
+ with runtime["track_task_server_call"]("invoke_agent", carrier=parent_carrier) as task_span:
+ annotate(runtime, input_data={"agent": role}, output_data={"result": "dispatched"}, tags={"agent": role})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_step_carrier(
+ runtime: dict[str, Any],
+ *,
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str,
+ transcript_path: str,
+) -> dict[str, str]:
+ """创建用于归并同一条 message 工作的 synthetic step span。"""
+ try:
+ with runtime["track_task_server_call"]("react_step", carrier=parent_carrier) as task_span:
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id},
+ output_data={"result": "grouped"},
+ tags={"message_id": message_id, "agent": agent, "transcript_path": transcript_path or ""},
+ )
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def generate_agent_carrier(runtime: dict[str, Any], *, parent_carrier: dict[str, str], agent: str) -> dict[str, str]:
+ """在当前 turn 下创建稳定的 per-agent 聚合 span。"""
+ try:
+ with runtime["track_task_server_call"]("react_agent", carrier=parent_carrier) as task_span:
+ span = getattr(task_span, "_span", None)
+ if span is not None and hasattr(span, "set_attribute"):
+ span.set_attribute("agent.name", agent)
+ annotate(runtime, input_data={"agent": agent}, output_data={"agent": agent}, tags={"agent": agent})
+ child_carrier = carrier_from_task_span(parent_carrier, task_span)
+ if child_carrier:
+ return child_carrier
+ except Exception:
+ return {}
+ return {}
+
+
+def resolve_agent_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+) -> dict[str, str]:
+ """从共享状态里获取或创建持久化的 agent 聚合 carrier。"""
+ normalized_agent = str(agent or "main").strip() or "main"
+ existing = st.get_agent_span_carrier(state_path, sid, normalized_agent)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_agent_carrier(runtime, parent_carrier=parent_carrier, agent=normalized_agent)
+
+ effective_carrier = st.upsert_agent_span_atomic(state_path, sid, normalized_agent, carrier_factory=_factory)
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return dict(parent_carrier)
+ agent_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "agent",
+ "span_name": "react_agent",
+ "agent": normalized_agent,
+ "trace_id": agent_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": agent_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def resolve_step_carrier(
+ *,
+ state_path: Path,
+ sid: str,
+ runtime: dict[str, Any],
+ parent_carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ transcript_path: str,
+) -> dict[str, str] | None:
+ """获取或创建按 message 分组使用的 step carrier。"""
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return None
+ existing = st.get_step_span_carrier(state_path, sid, agent, normalized_message_id)
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+
+ def _factory() -> dict[str, str]:
+ return generate_step_carrier(
+ runtime,
+ parent_carrier=parent_carrier,
+ agent=agent,
+ message_id=normalized_message_id,
+ transcript_path=transcript_path,
+ )
+
+ effective_carrier = st.upsert_step_span_atomic(
+ state_path,
+ sid,
+ agent,
+ normalized_message_id,
+ carrier_factory=_factory,
+ transcript_path=transcript_path,
+ )
+ if not isinstance(effective_carrier, dict) or not effective_carrier.get("traceparent"):
+ return None
+ step_parts = traceparent_parts(effective_carrier)
+ parent_parts = traceparent_parts(parent_carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "step",
+ "span_name": "react_step",
+ "message_id": normalized_message_id,
+ "agent": agent,
+ "trace_id": step_parts.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": step_parts.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ "transcript_path": transcript_path or "",
+ },
+ sanitizer=sanitize_payload,
+ )
+ return dict(effective_carrier)
+
+
+def set_agent_aggregate_on_span(span: Any, aggregate: dict[str, Any] | None) -> None:
+ """把 agent 的累计指标投影成当前 span 的属性。"""
+ if span is None or not hasattr(span, "set_attribute") or not isinstance(aggregate, dict):
+ return
+ tokens = aggregate.get("tokens") or {}
+ if isinstance(tokens, dict):
+ for key in ("input", "output", "cache_read", "cache_creation", "total"):
+ if key in tokens:
+ span.set_attribute(f"agent.cumulative_tokens.{key}", int(tokens.get(key) or 0))
+ for key in ("cost_usd", "tool_duration_ms", "llm_call_count", "tool_call_count", "step_count", "event_count"):
+ if key in aggregate:
+ try:
+ span.set_attribute(f"agent.cumulative.{key}", int(aggregate.get(key) or 0))
+ except (TypeError, ValueError):
+ span.set_attribute(f"agent.cumulative.{key}", str(aggregate.get(key)))
+
+
+def emit_assistant_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ agent: str,
+ message_id: str | None,
+ assistant_text: str,
+ model: str | None = None,
+ transcript_path: str | None = None,
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出一个轻量 assistant span,并按需补上 tool calls。"""
+ if not assistant_text or not assistant_text.strip():
+ return
+ tool_calls: list[dict[str, Any]] = []
+ if message_id and transcript_path:
+ tool_calls = collect_tool_calls_for_message(transcript_path, message_id)
+ output_data: dict[str, Any] = {"role": "assistant", "content": assistant_text[:8000]}
+ if tool_calls:
+ output_data["tool_calls"] = tool_calls
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name="assistant_message") as span:
+ span.set_attribute(runtime["ZhiyanSpanAttributes"].LLM_SPAN_KIND, runtime["ZhiyanllmSpanKindValues"].LLM.value)
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "assistant",
+ "span_name": "assistant_message",
+ "message_id": str(message_id or ""),
+ "agent": agent,
+ "model": str(model or ""),
+ "tool_call_count": len(tool_calls),
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data={"agent": agent, "message_id": message_id or "", "model": model or ""},
+ output_data=output_data,
+ tags={"message_id": str(message_id or ""), "agent": agent},
+ )
+ finally:
+ runtime["otel_detach"](token)
+
+
+def emit_tool_span(
+ runtime: dict[str, Any],
+ *,
+ carrier: dict[str, str],
+ tool_name: str,
+ active_agent: str,
+ skills: list[str],
+ rules: list[str],
+ duration_ms: int | None = None,
+ tool_details: dict[str, Any] | None = None,
+ message_id: str | None = None,
+ step_grouping: str = "fallback",
+ state_path: Path | None = None,
+ sid: str | None = None,
+) -> None:
+ """发出 tool span,并以受控大小挂载 tool payload。"""
+ def _truncate(value: Any, limit: int = 1200) -> Any:
+ text = value if isinstance(value, str) else None
+ if text is None:
+ return value
+ if len(text) <= limit:
+ return text
+ return text[:limit] + "...(truncated)"
+
+ def _maybe_parse_json_text(value: Any) -> Any:
+ if not isinstance(value, str):
+ return value
+ text = value.strip()
+ if not text or text[0] not in "{[":
+ return value
+ try:
+ return json.loads(text)
+ except Exception:
+ return value
+
+ def _parse_bash_result_content(value: Any) -> dict[str, Any] | None:
+ if not isinstance(value, str) or "Command:" not in value:
+ return None
+ normalized_value = value.replace("\\n", "\n")
+ markers = [
+ ("Command:", "command"),
+ ("Stdout:", "stdout"),
+ ("Stderr:", "stderr"),
+ ("Exit Code:", "exit_code"),
+ ("Signal:", "signal"),
+ ]
+ parsed: dict[str, Any] = {}
+ for idx, (marker, key) in enumerate(markers):
+ start = normalized_value.find(marker)
+ if start < 0:
+ continue
+ start += len(marker)
+ end = len(normalized_value)
+ for next_marker, _ in markers[idx + 1:]:
+ pos = normalized_value.find(next_marker, start)
+ if pos >= 0:
+ end = min(end, pos)
+ segment = normalized_value[start:end].strip()
+ if not segment:
+ continue
+ parsed[key] = _truncate(segment, 1200 if key in {"command", "stdout", "stderr"} else 200)
+ return parsed or None
+
+ tool_input: dict[str, Any] = {"tool": tool_name, "agent": active_agent}
+ if skills:
+ tool_input["skill"] = ", ".join(skills)
+ if rules:
+ tool_input["rule"] = ", ".join(rules)
+ if message_id:
+ tool_input["message_id"] = message_id
+ details = dict(tool_details or {})
+ call_id = str(details.get("call_id") or "").strip() or None
+ if call_id:
+ tool_input["call_id"] = call_id
+ arguments_display_text = details.get("arguments_display_text")
+ if arguments_display_text:
+ tool_input["arguments_display_text"] = _truncate(arguments_display_text, 600)
+ arguments = details.get("arguments")
+ if arguments:
+ parsed_arguments = _maybe_parse_json_text(arguments)
+ tool_input["arguments"] = _truncate(parsed_arguments, 1200)
+ if isinstance(parsed_arguments, dict):
+ if parsed_arguments.get("command"):
+ tool_input["command"] = _truncate(parsed_arguments.get("command"), 1200)
+ if parsed_arguments.get("description"):
+ tool_input["description"] = _truncate(parsed_arguments.get("description"), 400)
+
+ tool_output: dict[str, Any] = {"result": "executed"}
+ result_content = details.get("result_content")
+ if result_content is not None:
+ structured_result = _parse_bash_result_content(result_content)
+ if structured_result:
+ tool_output["result"] = structured_result
+ else:
+ tool_output["result_content"] = _truncate(result_content, 1600)
+ output_text = details.get("output_text")
+ if output_text:
+ tool_output["output_text"] = _truncate(output_text, 1600)
+ raw_response = details.get("raw_response")
+ if isinstance(raw_response, dict):
+ tool_output["raw_response"] = {
+ "exitCode": raw_response.get("exitCode"),
+ "signal": raw_response.get("signal"),
+ "interrupted": raw_response.get("interrupted"),
+ "sandboxDenied": raw_response.get("sandboxDenied"),
+ "tool_error_code": raw_response.get("tool_error_code"),
+ }
+
+ ctx = runtime["TracerWrapper"].extract_context(carrier)
+ token = runtime["otel_attach"](ctx)
+ try:
+ with runtime["get_tracer"]() as tracer:
+ with tracer.start_as_current_span(name=f"{tool_name}.TOOL") as span:
+ span_kind_value = runtime["ZhiyanllmSpanKindValues"].TOOL.value
+ span.set_attribute(zhiyan_attr(runtime, "LLM_SPAN_KIND", "gen_ai.span.kind"), span_kind_value)
+ span.set_attribute("gen_ai.span.kind", span_kind_value)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_NAME", "tool.name"), tool_name)
+ if isinstance(tool_details, dict):
+ desc = tool_details.get("description") or tool_details.get("tool_description")
+ if isinstance(desc, str) and desc.strip():
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_DESCRIPTION", "tool.description"), desc.strip())
+ tool_params = tool_input.get("arguments")
+ if tool_params is not None:
+ if not isinstance(tool_params, str):
+ tool_params = json.dumps(tool_params, ensure_ascii=False, default=str)
+ span.set_attribute(zhiyan_attr(runtime, "TOOL_PARAMETERS", "tool.parameters"), tool_params)
+ if duration_ms is not None:
+ span.set_attribute("tool.duration_ms", int(duration_ms))
+ span_ids = span_context_ids(span)
+ parent_parts = traceparent_parts(carrier)
+ debug_write_span(
+ state_path,
+ sid,
+ {
+ "event": "span_emit",
+ "span_kind": "tool",
+ "span_name": f"{tool_name}.TOOL",
+ "tool": tool_name,
+ "message_id": str(message_id or ""),
+ "call_id": call_id or "",
+ "step_grouping": step_grouping,
+ "agent": active_agent,
+ "trace_id": span_ids.get("trace_id", parent_parts.get("trace_id", "")),
+ "span_id": span_ids.get("span_id", ""),
+ "parent_span_id": parent_parts.get("span_id", ""),
+ "parent_traceparent": parent_parts.get("traceparent", ""),
+ },
+ sanitizer=sanitize_payload,
+ )
+ annotate(
+ runtime,
+ input_data=tool_input,
+ output_data=tool_output,
+ tags={"step_grouping": step_grouping, "message_id": str(message_id or "")},
+ )
+ finally:
+ runtime["otel_detach"](token)
diff --git a/.cursor/skills/agent-observability/scripts/core/cls_sink.py b/.cursor/skills/agent-observability/scripts/core/cls_sink.py
new file mode 100644
index 00000000..6525f6ed
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/cls_sink.py
@@ -0,0 +1,470 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import struct
+import subprocess
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .agentlens import bootstrap
+
+
+
+@dataclass(frozen=True)
+class CLSConfig:
+ enabled: bool
+ endpoint: str
+ topic_id: str
+ secret_id: str
+ secret_key: str
+ secret_token: str
+ service_name: str
+ timeout_seconds: int
+ helper_path: Path
+ sdk_entry_path: Path
+
+ @property
+ def ready(self) -> bool:
+ return bool(
+ self.enabled
+ and self.endpoint
+ and self.topic_id
+ and self.secret_id
+ and self.secret_key
+ and self.helper_path.is_file()
+ and self.sdk_entry_path.is_file()
+ )
+
+
+def repo_root() -> Path:
+ return Path(__file__).resolve().parents[5]
+
+
+def helper_path() -> Path:
+ return Path(__file__).with_name("cls_uploader.mjs")
+
+
+def sdk_entry_path() -> Path:
+ return (
+ repo_root()
+ / "cls-codebuddy"
+ / "tencentcloud-cls-sdk-codebuddy"
+ / "node_modules"
+ / "tencentcloud-cls-sdk-js"
+ / "dist"
+ / "index.js"
+ )
+
+
+def debug_log_path() -> Path:
+ return Path(__file__).resolve().parents[2] / "logs" / "cls-push-debug.ndjson"
+
+
+def _value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: str = "",
+ aliases: tuple[str, ...] = (),
+) -> str:
+ keys = (name, *aliases)
+ for key in keys:
+ raw = os.environ.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_local.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ for key in keys:
+ raw = env_file.get(key)
+ if raw is not None and str(raw).strip():
+ return str(raw).strip()
+ return default
+
+
+def _enabled_flag(*, env_local: dict[str, str], env_file: dict[str, str]) -> bool:
+ raw = _value(
+ "CLS_CODINGAGENT_ENABLED",
+ env_local=env_local,
+ env_file=env_file,
+ default="1",
+ )
+ return str(raw).strip().lower() not in {"0", "false", "off", "no"}
+
+
+def _debug_write(payload: dict[str, Any]) -> None:
+ try:
+ path = debug_log_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(payload, ensure_ascii=False) + "\n")
+ except Exception:
+ return
+
+
+# ---- CLS PutLogs 的 protobuf 编码 ----
+# CLS 使用了简化版 protobuf:
+# LogGroup { repeated Log logs = 1; optional string filename = 2; }
+# Log { optional uint32 time = 1; repeated Content contents = 2; }
+# Content { optional string key = 1; optional string value = 2; }
+
+def _encode_varint(value: int) -> bytes:
+ result = b""
+ while value > 0x7F:
+ result += bytes([(value & 0x7F) | 0x80])
+ value >>= 7
+ result += bytes([value & 0x7F])
+ return result
+
+def _encode_field(field_number: int, wire_type: int, data: bytes) -> bytes:
+ tag = (field_number << 3) | wire_type
+ return _encode_varint(tag) + data
+
+def _encode_string_field(field_number: int, value: str) -> bytes:
+ encoded = value.encode("utf-8")
+ return _encode_field(field_number, 2, _encode_varint(len(encoded)) + encoded)
+
+def _encode_uint32_field(field_number: int, value: int) -> bytes:
+ return _encode_field(field_number, 0, _encode_varint(value))
+
+def _encode_content(key: str, value: str) -> bytes:
+ msg = b""
+ if key:
+ msg += _encode_string_field(1, key)
+ if value:
+ msg += _encode_string_field(2, value)
+ return msg
+
+def _encode_log(record: dict[str, Any], service_name: str) -> bytes:
+ ts = record.get("ts")
+ if isinstance(ts, (int, float)):
+ log_time = int(ts) if ts < 1_000_000_000_000 else int(ts / 1000)
+ else:
+ log_time = int(time.time())
+
+ msg = _encode_uint32_field(1, log_time)
+
+ merged = {"service_name": service_name, **record}
+ for key, value in merged.items():
+ if value is None:
+ continue
+ if isinstance(value, (dict, list)):
+ value = json.dumps(value, ensure_ascii=False)
+ else:
+ value = str(value)
+ msg += _encode_field(2, 2, _encode_varint(len(_encode_content(key, value))) + _encode_content(key, value))
+
+ return msg
+
+def _encode_log_group(records: list[dict[str, Any]], service_name: str) -> bytes:
+ msg = b""
+ for record in records:
+ log_bytes = _encode_log(record, service_name)
+ msg += _encode_field(1, 2, _encode_varint(len(log_bytes)) + log_bytes)
+ if service_name:
+ msg += _encode_string_field(2, service_name)
+ return msg
+
+def _encode_log_group_list(records: list[dict[str, Any]], service_name: str) -> bytes:
+ """编码 LogGroupList protobuf:`message LogGroupList { repeated LogGroup logGroupList = 1; }`。"""
+ log_group_bytes = _encode_log_group(records, service_name)
+ return _encode_field(1, 2, _encode_varint(len(log_group_bytes)) + log_group_bytes)
+
+
+# ---- CLS API v3 使用的 TC3-HMAC-SHA256 签名 ----
+
+def _hmac_sha256(key: bytes, data: str) -> bytes:
+ return hmac.new(key, data.encode("utf-8"), hashlib.sha256).digest()
+
+def _sha256_hex(data: str) -> str:
+ return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+def _put_logs_via_api(
+ endpoint: str,
+ topic_id: str,
+ secret_id: str,
+ secret_key: str,
+ log_group_bytes: bytes,
+ region: str = "ap-guangzhou",
+ timeout: int = 20,
+) -> tuple[bool, str]:
+ """通过 CLS API v3 发送 UploadLog,并使用 TC3-HMAC-SHA256 签名。
+
+ `log_group_bytes` 应该是一个 LogGroupList protobuf。
+ """
+ host = endpoint
+ service = "cls"
+ action = "UploadLog"
+ version = "2020-10-16"
+ algorithm = "TC3-HMAC-SHA256"
+ content_type = "application/octet-stream"
+
+ timestamp = int(time.time())
+ date_str = time.strftime("%Y-%m-%d", time.gmtime(timestamp))
+
+ # 请求体就是原始 protobuf 字节串(LogGroupList)
+ payload = log_group_bytes
+ hashed_payload = hashlib.sha256(payload).hexdigest()
+
+ # 规范化请求串
+ canonical_headers = f"content-type:{content_type}\nhost:{host}\nx-tc-action:{action.lower()}\n"
+ signed_headers = "content-type;host;x-tc-action"
+ canonical_request = f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+
+ # 待签名字符串
+ credential_scope = f"{date_str}/{service}/tc3_request"
+ hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
+ string_to_sign = f"{algorithm}\n{timestamp}\n{credential_scope}\n{hashed_canonical_request}"
+
+ # 签名结果
+ secret_date = _hmac_sha256(("TC3" + secret_key).encode("utf-8"), date_str)
+ secret_service = _hmac_sha256(secret_date, service)
+ secret_signing = _hmac_sha256(secret_service, "tc3_request")
+ signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+ authorization = f"{algorithm} Credential={secret_id}/{credential_scope}, SignedHeaders={signed_headers}, Signature={signature}"
+
+ # 构造 HTTP 请求
+ url = f"https://{host}"
+ headers = {
+ "Authorization": authorization,
+ "Content-Type": content_type,
+ "Host": host,
+ "X-TC-Action": action,
+ "X-TC-Timestamp": str(timestamp),
+ "X-TC-Version": version,
+ "X-TC-Region": region,
+ "X-CLS-TopicId": topic_id,
+ "Content-Length": str(len(payload)),
+ }
+
+ req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ body = resp.read().decode("utf-8", errors="replace")
+ if resp.status == 200:
+ return True, body
+ else:
+ return False, f"HTTP {resp.status}: {body}"
+ except urllib.error.HTTPError as e:
+ body = e.read().decode("utf-8", errors="replace")[:500]
+ return False, f"HTTP {e.code}: {body}"
+ except Exception as e:
+ return False, f"{type(e).__name__}: {e}"
+
+
+def _int_value(
+ name: str,
+ *,
+ env_local: dict[str, str],
+ env_file: dict[str, str],
+ default: int,
+ aliases: tuple[str, ...] = (),
+) -> int:
+ raw = _value(name, env_local=env_local, env_file=env_file, default=str(default), aliases=aliases)
+ try:
+ parsed = int(raw)
+ except Exception:
+ return default
+ return parsed if parsed > 0 else default
+
+
+def load_config(cwd: str | None = None) -> CLSConfig:
+ project_root = bootstrap.project_root(cwd)
+ env_file = bootstrap.read_env_file(project_root / ".env")
+ env_local = bootstrap.read_env_file(project_root / ".env.local")
+ return CLSConfig(
+ enabled=_enabled_flag(env_local=env_local, env_file=env_file),
+ endpoint=_value(
+ "CLS_ENDPOINT",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ topic_id=_value(
+ "CLS_TOPIC_ID",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ secret_id=_value(
+ "CLS_SECRET_ID",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID",
+ "TENCENTCLOUD_SECRET_ID_438167613",
+ ),
+ ),
+ secret_key=_value(
+ "CLS_SECRET_KEY",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=(
+ "TC_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY",
+ "TENCENTCLOUD_SECRET_KEY_438167613",
+ ),
+ ),
+ secret_token=_value(
+ "CLS_SECRET_TOKEN",
+ env_local=env_local,
+ env_file=env_file,
+ aliases=("TC_SECRET_TOKEN", "TC_SESSION_TOKEN", "CLS_SESSION_TOKEN"),
+ ),
+ service_name=_value(
+ "CLS_SERVICE_NAME",
+ env_local=env_local,
+ env_file=env_file,
+ ),
+ timeout_seconds=_int_value(
+ "CLS_UPLOAD_TIMEOUT_SECONDS",
+ env_local=env_local,
+ env_file=env_file,
+ default=0,
+ aliases=("CLS_TIMEOUT_SECONDS",),
+ ),
+ helper_path=helper_path(),
+ sdk_entry_path=sdk_entry_path(),
+ )
+
+
+def mirror_record(record: dict[str, Any], *, cwd: str | None = None) -> bool:
+ config = load_config(cwd)
+ if not config.ready:
+ _debug_write(
+ {
+ "stage": "config_not_ready",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "secret_id_present": bool(config.secret_id),
+ "secret_key_present": bool(config.secret_key),
+ "secret_token_present": bool(config.secret_token),
+ "timeout_seconds": config.timeout_seconds,
+ "helper_exists": config.helper_path.is_file(),
+ "sdk_exists": config.sdk_entry_path.is_file(),
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_start",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 先尝试 Python 原生 API v3 上报(兼容内网 endpoint)
+ try:
+ log_group_bytes = _encode_log_group_list([record], config.service_name)
+ success, detail = _put_logs_via_api(
+ endpoint=config.endpoint,
+ topic_id=config.topic_id,
+ secret_id=config.secret_id,
+ secret_key=config.secret_key,
+ log_group_bytes=log_group_bytes,
+ timeout=config.timeout_seconds,
+ )
+ if success:
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "method": "python_api_v3",
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
+ else:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "method": "python_api_v3",
+ "error": detail[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "method": "python_api_v3",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+
+ # 回退方案:使用 node SDK uploader
+ payload = {
+ "endpoint": config.endpoint,
+ "topicId": config.topic_id,
+ "secretId": config.secret_id,
+ "secretKey": config.secret_key,
+ "secretToken": config.secret_token,
+ "serviceName": config.service_name,
+ "records": [record],
+ }
+ try:
+ completed = subprocess.run(
+ ["node", str(config.helper_path), str(config.sdk_entry_path)],
+ input=json.dumps(payload, ensure_ascii=False),
+ text=True,
+ capture_output=True,
+ check=False,
+ timeout=config.timeout_seconds,
+ )
+ if completed.returncode != 0:
+ _debug_write(
+ {
+ "stage": "uploader_failed",
+ "returncode": completed.returncode,
+ "stdout": (completed.stdout or "")[:2000],
+ "stderr": (completed.stderr or "")[:2000],
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+ except Exception as err:
+ _debug_write(
+ {
+ "stage": "uploader_exception",
+ "error": f"{type(err).__name__}: {err}",
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return False
+
+ _debug_write(
+ {
+ "stage": "uploader_ok",
+ "endpoint": config.endpoint,
+ "topic_id": config.topic_id,
+ "timeout_seconds": config.timeout_seconds,
+ "event": record.get("event"),
+ "sid": record.get("sid"),
+ }
+ )
+ return True
diff --git a/.cursor/skills/agent-observability/scripts/core/cls_uploader.mjs b/.cursor/skills/agent-observability/scripts/core/cls_uploader.mjs
new file mode 100644
index 00000000..5c5dccc8
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/cls_uploader.mjs
@@ -0,0 +1,96 @@
+import { createRequire } from 'node:module';
+
+const MAX_FIELD_LENGTH = 32 * 1024;
+
+function truncate(value) {
+ if (value.length <= MAX_FIELD_LENGTH) {
+ return value;
+ }
+ return `${value.slice(0, MAX_FIELD_LENGTH)}...[truncated]`;
+}
+
+function stringifyValue(value) {
+ if (value === null || value === undefined) {
+ return '';
+ }
+ if (typeof value === 'string') {
+ return truncate(value);
+ }
+ if (typeof value === 'number' || typeof value === 'boolean') {
+ return String(value);
+ }
+ try {
+ return truncate(JSON.stringify(value));
+ } catch {
+ return truncate(String(value));
+ }
+}
+
+function timestampSeconds(record) {
+ const raw = Number(record?.ts);
+ if (!Number.isFinite(raw) || raw <= 0) {
+ return Math.floor(Date.now() / 1000);
+ }
+ return raw > 1_000_000_000_000 ? Math.floor(raw / 1000) : Math.floor(raw);
+}
+
+async function readStdin() {
+ const chunks = [];
+ for await (const chunk of process.stdin) {
+ chunks.push(chunk);
+ }
+ return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+ const sdkPath = process.argv[2];
+ if (!sdkPath) {
+ process.exitCode = 2;
+ process.stderr.write('missing sdk path\n');
+ return;
+ }
+
+ const require = createRequire(import.meta.url);
+ const { AsyncClient, LogItem, Content, LogGroup, PutLogsRequest } = require(sdkPath);
+
+ const raw = await readStdin();
+ const payload = JSON.parse(raw || '{}');
+ const records = Array.isArray(payload.records) ? payload.records : [];
+ if (!payload.endpoint || !payload.topicId || !payload.secretId || !payload.secretKey || records.length === 0) {
+ process.exitCode = 0;
+ return;
+ }
+
+ const client = new AsyncClient({
+ endpoint: payload.endpoint,
+ secretId: payload.secretId,
+ secretKey: payload.secretKey,
+ secretToken: payload.secretToken || '',
+ sourceIp: '127.0.0.1',
+ retry_times: 3,
+ });
+
+ const logGroup = new LogGroup();
+ logGroup.setFilename(payload.serviceName || 'agent-observability');
+
+ for (const record of records) {
+ const item = new LogItem();
+ const merged = {
+ service_name: payload.serviceName || 'agent-observability',
+ ...record,
+ };
+ for (const [key, value] of Object.entries(merged)) {
+ item.pushBack(new Content(key, stringifyValue(value)));
+ }
+ item.setTime(timestampSeconds(record));
+ logGroup.addLogs(item);
+ }
+
+ const request = new PutLogsRequest(payload.topicId, logGroup);
+ await client.PutLogs(request);
+}
+
+main().catch((error) => {
+ process.exitCode = 1;
+ process.stderr.write(`${error?.message || String(error)}\n`);
+});
diff --git a/.cursor/skills/agent-observability/scripts/core/collector.py b/.cursor/skills/agent-observability/scripts/core/collector.py
new file mode 100644
index 00000000..cfd681b2
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/collector.py
@@ -0,0 +1,1008 @@
+"""通用采集层。
+
+这一层负责最基础的观测数据采集:
+- 维护 Pre/PostToolUse 的配对关系,计算工具耗时
+- 解析 transcript 增量,提取 usage / model / tool 记录
+- 把 skill/rule 命中情况写入 session state
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, scanner, state as st
+
+# 需要从 transcript 中提取的 token 字段
+TOKEN_KEYS = (
+ "input_tokens", "output_tokens", "cache_read_input_tokens",
+ "cache_creation_input_tokens", "total_tokens",
+)
+
+# transcript 记录里可能携带模型名的字段
+MODEL_KEYS = ("model", "requestModelName", "requestModelId")
+MESSAGE_ID_KEYS = ("messageId", "responseId", "requestId")
+
+
+def transcript_path(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取 transcript 路径字段。"""
+ return str(data.get("transcript_path") or "")
+
+
+def read_stdin_json() -> dict:
+ """从 stdin 读取 JSON;失败时返回空字典。"""
+ import sys
+ try:
+ raw = sys.stdin.read()
+ if raw.strip():
+ d = json.loads(raw)
+ if isinstance(d, dict):
+ return d
+ return {}
+ except Exception as e:
+ return {"_parse_error": str(e)}
+
+
+def record_pre(pending_path: Path, data: dict) -> None:
+ """记录一条 PreToolUse,供后续 PostToolUse 计算耗时。"""
+ pending = st.load_pending(pending_path)
+ sid = data.get("session_id", "?")
+ tool = data.get("tool_name", "?")
+ key = f"{sid}::{tool}::{time.time_ns()}"
+ pending[key] = {
+ "start": time.time(),
+ "tool_name": tool,
+ "session_id": sid,
+ }
+ # 只保留最近 20 条 pending 记录
+ if len(pending) > 20:
+ for k in list(pending.keys())[:-20]:
+ pending.pop(k, None)
+ st.save_pending(pending_path, pending)
+
+
+def record_post(pending_path: Path, data: dict) -> int | None:
+ """把 PostToolUse 与之前的 PreToolUse 配对,并返回耗时毫秒数。"""
+ pending = st.load_pending(pending_path)
+ tool = data.get("tool_name")
+ sid = data.get("session_id", "?")
+ candidates = [(k, v) for k, v in pending.items()
+ if v.get("session_id") == sid and v.get("tool_name") == tool]
+ if not candidates:
+ return None
+ candidates.sort(key=lambda kv: kv[1]["start"])
+ key, item = candidates[-1]
+ duration_ms = int((time.time() - item["start"]) * 1000)
+ pending.pop(key, None)
+ st.save_pending(pending_path, pending)
+ return duration_ms
+
+
+def parse_transcript_tail(
+ path: str,
+ max_lines: int = 50,
+ last_offset: int = 0,
+) -> dict[str, Any]:
+ """解析 transcript 的增量 JSONL 内容,提取 usage、model 与 tool 元数据。
+
+ 返回结构:
+ {
+ "tokens": {...} or None, # 最新累计 usage
+ "prev_tokens": {...} or None, # 倒数第二条累计 usage(兼容字段)
+ "model": str or None,
+ "offset": int, # 当前 EOF
+ "tool_records": [
+ {"offset": int, "timestamp_ms": int | None, "tool": str, "call_id": str | None, "message_id": str | None, "kind": str},
+ ...
+ ],
+ "usage_records": [
+ {"offset": int, "tokens": {...}, "model": str | None, "message_id": str | None},
+ ...
+ ],
+ }
+
+ ``usage_records`` 会保留 ``last_offset`` 之后发现的全部 usage 项,
+ 这样调用方可以回放窗口内每一次模型请求,而不只是最后一个快照。
+ """
+ summary: dict[str, Any] = {
+ "tokens": None,
+ "prev_tokens": None,
+ "model": None,
+ "offset": 0,
+ "tool_records": [],
+ "usage_records": [],
+ }
+ if not path or not os.path.isfile(path):
+ return summary
+
+ try:
+ file_size = os.path.getsize(path)
+ summary["offset"] = file_size
+ if file_size <= last_offset:
+ return summary
+
+ with open(path, "rb") as fp:
+ read_start = max(0, int(last_offset or 0))
+ fp.seek(read_start)
+ tail_bytes = fp.read()
+ except Exception:
+ return summary
+
+ last_model_seen: str | None = None
+ usage_history: list[dict[str, Any]] = []
+ pending_tool_records: list[dict[str, Any]] = []
+ cursor = max(0, int(last_offset or 0))
+
+ for raw_line in tail_bytes.splitlines(keepends=True):
+ cursor += len(raw_line)
+ if not raw_line.lstrip().startswith(b"{"):
+ continue
+ try:
+ obj = json.loads(raw_line.decode("utf-8", errors="ignore"))
+ except Exception:
+ continue
+
+ rec_type = str(obj.get("type") or "").strip().lower() if isinstance(obj, dict) else ""
+ message_id = _find_message_id(obj)
+ m = _find_model(obj)
+ if m:
+ last_model_seen = m
+ line_tool_records = _find_tool_records(obj)
+ if message_id and rec_type not in {"function_call", "function_call_result"}:
+ for pending_record in pending_tool_records:
+ pending_record["next_message_id"] = message_id
+ pending_tool_records = []
+ for tool_record in line_tool_records:
+ tool_record["offset"] = cursor
+ tool_record["timestamp_ms"] = _find_timestamp_ms(obj)
+ tool_record["message_id"] = message_id
+ summary["tool_records"].append(tool_record)
+ pending_tool_records.append(tool_record)
+ usage = _find_usage(obj)
+ if not usage:
+ continue
+
+ usage_history.append({
+ "offset": cursor,
+ "tokens": usage,
+ "model": m or last_model_seen,
+ "message_id": message_id,
+ })
+ if m:
+ summary["model"] = m
+
+ if usage_history:
+ summary["usage_records"] = usage_history
+ summary["tokens"] = usage_history[-1]["tokens"]
+ if len(usage_history) >= 2:
+ summary["prev_tokens"] = usage_history[-2]["tokens"]
+
+ if not summary.get("model") and last_model_seen:
+ summary["model"] = last_model_seen
+ return summary
+
+
+def record_tool_usage(
+ state_path: Path,
+ sid: str,
+ data: dict,
+ skills_meta: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+ collect_skills: bool = False,
+) -> tuple[list[str], list[str]]:
+ """把一次 tool 调用命中的 skill/rule 写入 session state。
+
+ Returns:
+ (used_skills, used_rules): 本次工具调用命中的 skill/rule 名称列表。
+ """
+ tool = data.get("tool_name")
+
+ def _update(state: dict[str, Any]) -> tuple[list[str], list[str]]:
+ sess = st.ensure_session(state, sid)
+ agent = active_agent or sess.get("current_agent") or "main"
+
+ used_skills: set[str] = set()
+ used_rules: set[str] = set()
+
+ # 1) 可选的 skill 收集
+ if collect_skills:
+ # 直接 use_skill 调用
+ direct = scanner.extract_skill_from_tool_call(data)
+ if direct:
+ st.bump_skill(sess, direct, via="use_skill", tool=tool,
+ meta=skills_meta.get(direct), agent=agent)
+ used_skills.add(direct)
+
+ # 路径推断
+ path_skills, _ = scanner.extract_paths_from_tool_call(data)
+ for s in path_skills:
+ st.bump_skill(sess, s, via="path-inferred", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 子模块命中
+ for hit in scanner.extract_submodule_hits(data):
+ skill_name = hit["skill"]
+ # unknown 仅代表“命中子模块但无法确定 skill 名称”,不写入实时 skill 字段
+ if not skill_name or skill_name == "unknown":
+ continue
+ st.bump_skill(sess, skill_name, via="submodule", tool=tool,
+ meta=skills_meta.get(skill_name),
+ submodule=hit["submodule"], agent=agent)
+ used_skills.add(skill_name)
+
+ # Bash skill 脚本
+ for s in scanner.extract_bash_skill_scripts(data):
+ st.bump_skill(sess, s, via="bash-script", tool=tool,
+ meta=skills_meta.get(s), agent=agent)
+ used_skills.add(s)
+
+ # 2) 基于路径推断的 rule(始终开启)
+ _, path_rules = scanner.extract_paths_from_tool_call(data)
+ for r in path_rules:
+ st.bump_rule(sess, r, via="path-inferred", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ # 3) 当前激活的 rule(始终开启)
+ for r in scanner.active_rules_for_call(data, rules_meta, active_agent=agent):
+ st.bump_rule(sess, r, via="active-rule", tool=tool, meta=rules_meta.get(r), agent=agent)
+ used_rules.add(r)
+
+ st.prune_sessions(state)
+ return sorted(used_skills), sorted(used_rules)
+
+ return st.update_state_locked(state_path, _update)
+
+
+
+def cache_inventory(
+ state_path: Path,
+ sid: str,
+ skills_meta: dict,
+ rules_meta: dict,
+) -> None:
+ """把完整的 skill/rule inventory 缓存在 session state 中(在 SessionStart 调用)。"""
+ def _update(state: dict[str, Any]) -> None:
+ sess = st.ensure_session(state, sid)
+ sess["_skills_meta"] = skills_meta
+ sess["_rules_meta"] = rules_meta
+ sess["_inventory_scanned_at"] = time.time()
+
+ # 为所有已知 skill/rule 预先初始化 count=0 的 usage 记录
+ for name, meta in skills_meta.items():
+ rec = sess["skills"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"],
+ "source": meta.get("source"), "version": meta.get("version"),
+ })
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+
+ for name, meta in rules_meta.items():
+ rec = sess["rules"].setdefault(name, {
+ "count": 0, "first_ts": None, "last_ts": None,
+ "tools": [], "via": ["static-scanned"], "source": meta.get("source"),
+ })
+ if "static-scanned" not in rec.get("via", []):
+ rec.setdefault("via", []).append("static-scanned")
+ if not rec.get("source"):
+ rec["source"] = meta.get("source")
+
+ st.prune_sessions(state)
+
+ st.update_state_locked(state_path, _update)
+
+
+def load_cached_inventory(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """从 state 中读取缓存的 skill/rule inventory,避免在热路径里执行 rglob。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return (
+ sess.get("_skills_meta") or {},
+ sess.get("_rules_meta") or {},
+ )
+
+
+def get_session_usage(state_path: Path, sid: str) -> tuple[dict, dict]:
+ """返回某个 session 的 skill/rule usage 字典。"""
+ state = st.load_state(state_path)
+ sess = state.get(sid, {})
+ if not isinstance(sess, dict):
+ return {}, {}
+ return sess.get("skills", {}) or {}, sess.get("rules", {}) or {}
+
+def related_transcript_paths(sid: str, transcript_path: str) -> list[str]:
+ """收集当前 session 的主 transcript 以及所有 subagent transcript。"""
+ paths: list[Path] = []
+ current = Path(transcript_path).expanduser() if transcript_path else None
+ if current and current.is_file():
+ paths.append(current)
+
+ bundle_dir: Path | None = None
+ if current:
+ if current.name == f"{sid}.jsonl":
+ candidate = current.with_suffix("")
+ if candidate.is_dir():
+ bundle_dir = candidate
+ else:
+ for parent in [current.parent, *current.parents]:
+ if parent.name == sid and parent.is_dir():
+ bundle_dir = parent
+ break
+
+ if bundle_dir is None and current:
+ candidate = current.parent / sid
+ if candidate.is_dir():
+ bundle_dir = candidate
+
+ if bundle_dir is not None:
+ main_transcript = bundle_dir.with_suffix(".jsonl")
+ if main_transcript.is_file():
+ paths.append(main_transcript)
+ subagents_dir = bundle_dir / "subagents"
+ if subagents_dir.is_dir():
+ paths.extend(sorted(path for path in subagents_dir.glob("*.jsonl") if path.is_file()))
+
+ out: list[str] = []
+ seen: set[str] = set()
+ for path in paths:
+ resolved = str(path.resolve())
+ if resolved in seen:
+ continue
+ seen.add(resolved)
+ out.append(resolved)
+ return out
+
+
+def _transcript_size_signature(paths: list[str]) -> tuple[tuple[str, int], ...]:
+ """基于路径和文件大小生成 transcript 稳定性签名。"""
+ signature: list[tuple[str, int]] = []
+ for path in paths:
+ try:
+ size = Path(path).stat().st_size
+ except Exception:
+ size = -1
+ signature.append((path, int(size)))
+ return tuple(signature)
+
+
+def settled_related_transcript_paths(
+ sid: str,
+ transcript_path: str,
+ *,
+ max_wait_s: float = 2.0,
+ interval_s: float = 0.4,
+ stable_rounds: int = 2,
+) -> list[str]:
+ """在 replay 前短暂等待 transcript 文件停止增长。"""
+ deadline = time.monotonic() + max(0.0, max_wait_s)
+ previous: tuple[tuple[str, int], ...] | None = None
+ stable_count = 0
+ paths = related_transcript_paths(sid, transcript_path)
+
+ while True:
+ paths = related_transcript_paths(sid, transcript_path)
+ current = _transcript_size_signature(paths)
+ if current == previous:
+ stable_count += 1
+ else:
+ previous = current
+ stable_count = 0
+ if stable_count >= stable_rounds or time.monotonic() >= deadline:
+ return paths
+ sleep_for = min(interval_s, max(0.0, deadline - time.monotonic()))
+ if sleep_for <= 0:
+ return paths
+ time.sleep(sleep_for)
+
+
+def session_id_for_transcript_path(transcript_path: str) -> str | None:
+ """从 transcript 文件内容中反查 session id。"""
+ path = Path(transcript_path)
+ try:
+ with path.open("r", encoding="utf-8") as fp:
+ for _ in range(8):
+ line = fp.readline()
+ if not line:
+ break
+ try:
+ record = json.loads(line)
+ except Exception:
+ continue
+ session_id = record.get("sessionId")
+ if isinstance(session_id, str) and session_id.strip():
+ return session_id.strip()
+ except Exception:
+ return None
+ return None
+
+
+def resolve_transcript_path_alias(sid: str, transcript_path: str) -> str:
+ """把别名 transcript 路径解析成当前 session 下的真实文件路径。"""
+ if not transcript_path:
+ return ""
+ current = Path(transcript_path).expanduser()
+ if current.is_file():
+ return str(current.resolve())
+
+ alias_session_id = current.stem if current.suffix == ".jsonl" else ""
+ if not alias_session_id or alias_session_id == sid:
+ return str(current)
+
+ for candidate in related_transcript_paths(sid, transcript_path):
+ if session_id_for_transcript_path(candidate) == alias_session_id:
+ return candidate
+ return str(current)
+
+def compute_usage_delta(current: dict[str, int], prev: dict[str, int] | None) -> dict[str, int]:
+ """把一条 usage 记录归一化成当前要发出的 event payload。"""
+ _ = prev
+ out = dict(current)
+ out["total"] = int(out.get("input", 0) or 0) + int(out.get("output", 0) or 0)
+ return out
+
+
+def normalize_tokens(tokens: dict[str, Any] | None) -> dict[str, int] | None:
+ """兼容多种 token 字段命名,并统一折叠成一套 schema。"""
+ if not isinstance(tokens, dict):
+ return None
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ input_t = _int(tokens.get("input") if "input" in tokens else tokens.get("input_tokens"))
+ output_t = _int(tokens.get("output") if "output" in tokens else tokens.get("output_tokens"))
+ cache_read = _int(tokens.get("cache_read") if "cache_read" in tokens else tokens.get("cache_read_input_tokens"))
+ cache_creation = _int(tokens.get("cache_creation") if "cache_creation" in tokens else tokens.get("cache_creation_input_tokens"))
+ total = input_t + output_t
+ if input_t <= 0 and output_t <= 0 and total <= 0:
+ return None
+ out = {"input": input_t, "output": output_t, "cache_read": cache_read, "total": total}
+ if cache_creation > 0:
+ out["cache_creation"] = cache_creation
+ return out
+
+
+def collect_transcript_entries(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ *,
+ max_lines: int,
+) -> dict[str, Any]:
+ """读取 transcript 增量,并返回带 source offset 的解析结果。"""
+ state_data = st.load_state(state_path)
+ last_offset = st.get_transcript_offset(state_data, sid, transcript_path)
+ tail = parse_transcript_tail(transcript_path, max_lines=max_lines, last_offset=last_offset)
+ new_offset = int(tail.get("offset", 0) or 0)
+
+ entries: list[dict[str, Any]] = []
+ tool_records: list[dict[str, Any]] = []
+ last_cumulative = st.get_last_cumulative_usage(state_data, sid, transcript_path) or None
+ usage_records = tail.get("usage_records") if isinstance(tail, dict) else None
+ if not isinstance(usage_records, list):
+ usage_records = []
+ raw_tool_records = tail.get("tool_records") if isinstance(tail, dict) else None
+ if not isinstance(raw_tool_records, list):
+ raw_tool_records = []
+
+ for raw_entry in usage_records:
+ if not isinstance(raw_entry, dict):
+ continue
+ current = normalize_tokens(raw_entry.get("tokens"))
+ if not current:
+ continue
+ delta = compute_usage_delta(current, last_cumulative)
+ entries.append({
+ "offset": int(raw_entry.get("offset", 0) or 0),
+ "tokens": delta,
+ "model": str(raw_entry.get("model") or tail.get("model") or "") or None,
+ "message_id": str(raw_entry.get("message_id") or "").strip() or None,
+ })
+ last_cumulative = current
+
+ for raw_tool_record in raw_tool_records:
+ if not isinstance(raw_tool_record, dict):
+ continue
+ tool_name = str(raw_tool_record.get("tool") or "").strip()
+ if not tool_name:
+ continue
+ tool_records.append({
+ "offset": int(raw_tool_record.get("offset", 0) or 0),
+ "timestamp_ms": int(raw_tool_record.get("timestamp_ms", 0) or 0) or None,
+ "tool": tool_name,
+ "call_id": str(raw_tool_record.get("call_id") or "").strip() or None,
+ "kind": str(raw_tool_record.get("kind") or "").strip() or None,
+ "message_id": str(raw_tool_record.get("message_id") or "").strip() or None,
+ "next_message_id": str(raw_tool_record.get("next_message_id") or "").strip() or None,
+ "arguments": raw_tool_record.get("arguments"),
+ "arguments_display_text": raw_tool_record.get("arguments_display_text"),
+ "result_content": raw_tool_record.get("result_content"),
+ "raw_response": raw_tool_record.get("raw_response"),
+ "output_text": raw_tool_record.get("output_text"),
+ })
+
+ return {
+ "entries": entries,
+ "tool_records": tool_records,
+ "new_offset": new_offset,
+ "last_cumulative": last_cumulative,
+ }
+
+
+def find_current_tool_message_id(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ max_lines: int = 80,
+) -> str | None:
+ """找到当前 tool 事件应该归属的 message id。"""
+ if not transcript_path or not tool_name:
+ return None
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ max_lines=max_lines,
+ )
+ tool_records = scan.get("tool_records") or []
+ latest_message_id: str | None = None
+ latest_offset = -1
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ if offset >= latest_offset:
+ latest_offset = offset
+ latest_message_id = message_id
+ return latest_message_id
+
+
+def tool_details_from_record(rec: dict[str, Any]) -> dict[str, Any]:
+ """把原始 tool 记录投影成日志里使用的紧凑 detail 结构。"""
+ details: dict[str, Any] = {}
+ call_id = str(rec.get("call_id") or "").strip() or None
+ if call_id:
+ details["call_id"] = call_id
+ arguments = rec.get("arguments")
+ if arguments is not None:
+ details["arguments"] = arguments
+ arguments_display_text = rec.get("arguments_display_text")
+ if arguments_display_text is not None:
+ details["arguments_display_text"] = arguments_display_text
+ result_content = rec.get("result_content")
+ if result_content is not None:
+ details["result_content"] = result_content
+ raw_response = rec.get("raw_response")
+ if isinstance(raw_response, dict) and raw_response:
+ details["raw_response"] = raw_response
+ output_text = rec.get("output_text")
+ if output_text is not None:
+ details["output_text"] = output_text
+ next_message_id = str(rec.get("next_message_id") or "").strip() or None
+ original_message_id = str(rec.get("message_id") or "").strip() or None
+ if next_message_id and original_message_id:
+ details["original_message_id"] = original_message_id
+ if next_message_id:
+ details["next_message_id"] = next_message_id
+ if original_message_id and next_message_id and original_message_id != next_message_id:
+ details["message_id_reassigned"] = True
+ return details
+
+
+def tool_record_merge_key(rec: dict[str, Any]) -> str:
+ """为一条 tool record 生成去重合并时使用的稳定 key。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"call_id:{call_id}"
+ offset = int(rec.get("offset", 0) or 0)
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ return f"fallback:{tool}:{message_id}:{timestamp_ms}:{offset}"
+
+
+def merge_tool_records(tool_records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """对指向同一次调用的 tool 记录做去重合并。"""
+ merged: dict[str, dict[str, Any]] = {}
+ order: list[str] = []
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ key = tool_record_merge_key(rec)
+ if key not in merged:
+ merged[key] = {
+ "offset": int(rec.get("offset", 0) or 0),
+ "timestamp_ms": int(rec.get("timestamp_ms", 0) or 0) or None,
+ "tool": str(rec.get("tool") or "").strip(),
+ "call_id": str(rec.get("call_id") or "").strip() or None,
+ "kind": str(rec.get("kind") or "").strip() or None,
+ "message_id": str(rec.get("message_id") or "").strip() or None,
+ "next_message_id": str(rec.get("next_message_id") or "").strip() or None,
+ "arguments": rec.get("arguments"),
+ "arguments_display_text": rec.get("arguments_display_text"),
+ "result_content": rec.get("result_content"),
+ "raw_response": rec.get("raw_response"),
+ "output_text": rec.get("output_text"),
+ }
+ order.append(key)
+ continue
+
+ current = merged[key]
+ current["offset"] = max(int(current.get("offset", 0) or 0), int(rec.get("offset", 0) or 0))
+ current_ts = int(current.get("timestamp_ms", 0) or 0)
+ rec_ts = int(rec.get("timestamp_ms", 0) or 0)
+ if current_ts <= 0 and rec_ts > 0:
+ current["timestamp_ms"] = rec_ts
+ for field in ("tool", "call_id", "kind", "message_id", "next_message_id", "arguments", "arguments_display_text", "result_content", "raw_response", "output_text"):
+ if current.get(field) is None and rec.get(field) is not None:
+ current[field] = rec.get(field)
+ if rec.get("arguments") is not None:
+ current["arguments"] = rec.get("arguments")
+ if rec.get("arguments_display_text") is not None:
+ current["arguments_display_text"] = rec.get("arguments_display_text")
+ if rec.get("result_content") is not None:
+ current["result_content"] = rec.get("result_content")
+ if rec.get("raw_response") is not None:
+ current["raw_response"] = rec.get("raw_response")
+ if rec.get("output_text") is not None:
+ current["output_text"] = rec.get("output_text")
+
+ return [merged[key] for key in order]
+
+
+def tool_context_claim_key(rec: dict[str, Any]) -> str:
+ """为 tool context 生成 claim 去重键,避免重复消费。"""
+ call_id = str(rec.get("call_id") or "").strip()
+ if call_id:
+ return f"tool_call|{call_id}"
+ tool = str(rec.get("tool") or "").strip()
+ message_id = str(rec.get("message_id") or "").strip()
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ offset = int(rec.get("offset", 0) or 0)
+ return f"tool_call|{tool}|{message_id}|{timestamp_ms}|{offset}"
+
+
+def find_current_tool_context(
+ state_path: Path,
+ sid: str,
+ transcript_path: str,
+ tool_name: str,
+ *,
+ call_id: str | None = None,
+ event_ts: float | None = None,
+ max_lines: int = 80,
+ claim: bool = False,
+) -> dict[str, Any] | None:
+ """为当前 tool 调用解析最合适的 transcript 上下文块。"""
+ if not tool_name:
+ return None
+ event_ts_ms = int(float(event_ts) * 1000) if event_ts else None
+ normalized_call_id = str(call_id or "").strip() or None
+
+ resolved_path = resolve_transcript_path_alias(sid, transcript_path)
+ candidate_paths: list[str] = []
+ if resolved_path:
+ candidate_paths.append(resolved_path)
+ for path in related_transcript_paths(sid, transcript_path):
+ if path not in candidate_paths:
+ candidate_paths.append(path)
+
+ candidates: list[tuple[tuple[int, int, int], dict[str, Any]]] = []
+ for path in candidate_paths:
+ scan = collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ tool_records = merge_tool_records(scan.get("tool_records") or [])
+ for rec in tool_records:
+ if not isinstance(rec, dict):
+ continue
+ if str(rec.get("tool") or "") != str(tool_name):
+ continue
+ rec_call_id = str(rec.get("call_id") or "").strip() or None
+ if normalized_call_id and rec_call_id != normalized_call_id:
+ continue
+ message_id = (
+ str(rec.get("next_message_id") or "").strip()
+ or str(rec.get("message_id") or "").strip()
+ or None
+ )
+ if not message_id:
+ continue
+ offset = int(rec.get("offset", 0) or 0)
+ timestamp_ms = int(rec.get("timestamp_ms", 0) or 0)
+ if normalized_call_id:
+ score = (0, 0, -offset)
+ elif event_ts_ms and timestamp_ms > 0:
+ delta = timestamp_ms - event_ts_ms
+ score = (abs(delta), 0 if delta >= 0 else 1, -offset)
+ else:
+ score = (10**12, 1, -offset)
+ candidates.append((
+ score,
+ {
+ "message_id": message_id,
+ "transcript_path": path,
+ "agent": agent_identity.agent_for_transcript_path(path, "main"),
+ "pt_id": agent_identity.pt_id_from_transcript_path(path),
+ "tool_details": tool_details_from_record(rec),
+ "_claim_key": tool_context_claim_key(rec),
+ },
+ ))
+
+ candidates.sort(key=lambda item: item[0])
+ saw_duplicate = False
+ for _, candidate in candidates:
+ if not claim:
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ if st.claim_transcript_event(
+ state_path,
+ sid,
+ str(candidate.get("_claim_key") or ""),
+ str(candidate.get("transcript_path") or "") or None,
+ ):
+ out = {
+ "message_id": str(candidate.get("message_id") or ""),
+ "transcript_path": str(candidate.get("transcript_path") or ""),
+ "agent": str(candidate.get("agent") or "main"),
+ "tool_details": dict(candidate.get("tool_details") or {}),
+ }
+ pt_id = candidate.get("pt_id")
+ if pt_id:
+ out["pt_id"] = pt_id
+ return out
+ saw_duplicate = True
+
+ if saw_duplicate:
+ return {"duplicate": True}
+ return None
+
+
+def extract_tool_call_id(data: dict[str, Any]) -> str | None:
+ """从事件 payload 或 tool_input 中提取 tool call id。"""
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId"):
+ value = data.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+
+ tool_input = data.get("tool_input")
+ if isinstance(tool_input, dict):
+ for key in ("call_id", "callId", "tool_call_id", "toolCallId", "id"):
+ value = tool_input.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return None
+
+
+def find_fallback_usage_event(
+ tool_event: dict[str, Any],
+ usage_events: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+ """当找不到直接匹配的 tool usage 时,为 AgentLens 选一条兜底 usage。"""
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ agent = str(tool_event.get("agent") or "main").strip() or "main"
+
+ strong_matches: list[dict[str, Any]] = []
+ weak_matches: list[dict[str, Any]] = []
+ for usage_event in usage_events:
+ if not isinstance(usage_event, dict):
+ continue
+ if (str(usage_event.get("agent") or "main").strip() or "main") != agent:
+ continue
+ if transcript_path and str(usage_event.get("transcript_path") or "").strip() != transcript_path:
+ continue
+ if not str(usage_event.get("message_id") or "").strip():
+ continue
+
+ weak_matches.append(usage_event)
+ event_tool = str(usage_event.get("tool") or "").strip()
+ if tool_name and event_tool in {tool_name, "model_request"}:
+ strong_matches.append(usage_event)
+
+ if strong_matches:
+ return strong_matches[-1]
+ if weak_matches:
+ return weak_matches[-1]
+ return None
+
+
+def build_transcript_event_key(*, kind: str, tool: str, entry: dict[str, Any]) -> str:
+ """为 transcript 重放出的事件生成幂等键。"""
+ _ = (kind, tool)
+ return "|".join(["model_request", str(entry.get("offset", 0) or 0)])
+
+def _find_usage(obj: Any, _depth: int = 0) -> dict | None:
+ """递归查找 JSON 对象里的 token usage。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ if "usage" in obj and isinstance(obj["usage"], dict):
+ u = obj["usage"]
+ picked = {k: u[k] for k in TOKEN_KEYS if k in u}
+ if picked:
+ return picked
+ for v in obj.values():
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_usage(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_model(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找 JSON 对象里的非空模型名。
+
+ 优先使用 `providerData.model` 或顶层 `model`,
+ 其次回退到 `requestModelName` / `requestModelId`。
+ """
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ for k in MODEL_KEYS:
+ v = obj.get(k)
+ if isinstance(v, str) and v.strip():
+ return v.strip()
+ for v in obj.values():
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_model(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_message_id(obj: Any, _depth: int = 0) -> str | None:
+ """递归查找稳定的 message/request 分组标识。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = provider.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ extra = obj.get("extra")
+ if isinstance(extra, dict):
+ for key in MESSAGE_ID_KEYS:
+ value = extra.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in MESSAGE_ID_KEYS:
+ value = obj.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for v in obj.values():
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_message_id(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_timestamp_ms(obj: Any, _depth: int = 0) -> int | None:
+ """递归查找 transcript 中的毫秒级时间戳。"""
+ if _depth > 10:
+ return None
+ if isinstance(obj, dict):
+ value = obj.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ provider = obj.get("providerData")
+ if isinstance(provider, dict):
+ value = provider.get("timestamp")
+ if isinstance(value, (int, float)) and value > 0:
+ return int(value)
+ for v in obj.values():
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ elif isinstance(obj, list):
+ for v in obj:
+ r = _find_timestamp_ms(v, _depth + 1)
+ if r:
+ return r
+ return None
+
+
+def _find_tool_records(obj: Any) -> list[dict[str, Any]]:
+ """从 transcript 记录里提取 tool 调用与 tool 结果片段。"""
+ out: list[dict[str, Any]] = []
+ if not isinstance(obj, dict):
+ return out
+
+ rec_type = str(obj.get("type") or "").strip().lower()
+ provider = obj.get("providerData") if isinstance(obj.get("providerData"), dict) else {}
+ if rec_type in {"function_call", "function_call_result"}:
+ tool_name = str(obj.get("name") or "").strip()
+ if tool_name:
+ record = {
+ "tool": tool_name,
+ "call_id": str(obj.get("callId") or "").strip() or None,
+ "kind": rec_type,
+ }
+ if rec_type == "function_call":
+ arguments = obj.get("arguments")
+ if isinstance(arguments, str) and arguments.strip():
+ record["arguments"] = arguments
+ arguments_display_text = provider.get("argumentsDisplayText")
+ if isinstance(arguments_display_text, str) and arguments_display_text.strip():
+ record["arguments_display_text"] = arguments_display_text.strip()
+ if rec_type == "function_call_result":
+ tool_result = provider.get("toolResult")
+ if isinstance(tool_result, dict):
+ content = tool_result.get("content")
+ if content is not None:
+ record["result_content"] = content
+ raw_response = tool_result.get("rawResponse")
+ if isinstance(raw_response, dict):
+ record["raw_response"] = raw_response
+ output = obj.get("output")
+ if isinstance(output, dict):
+ output_text = output.get("text")
+ if output_text is not None:
+ record["output_text"] = output_text
+ out.append(record)
+
+ content = obj.get("content")
+ if isinstance(content, list):
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ if str(item.get("type") or "").strip().lower() != "tool_use":
+ continue
+ tool_name = str(item.get("name") or "").strip()
+ if not tool_name:
+ continue
+ out.append({
+ "tool": tool_name,
+ "call_id": str(item.get("callId") or "").strip() or None,
+ "kind": "tool_use",
+ })
+
+ return out
diff --git a/.cursor/skills/agent-observability/scripts/core/devflow.py b/.cursor/skills/agent-observability/scripts/core/devflow.py
new file mode 100644
index 00000000..ab7ef794
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/devflow.py
@@ -0,0 +1,234 @@
+"""Devflow 感知层(可选增强,不属于通用采集核心)。
+
+这一层只在项目实际跑着 `.codebuddy/runtime` 描述的 multi-agents-devflow 工作流时才生效:
+- 判断当前 session 是否属于某个 devflow team(`multi-agents-devflow-{task_slug}`)
+- 读取该 team 对应的 `workflow-state.json`,投影成精简 stage 快照
+- 和上一次观测到的快照 diff,只把真正变化的 stage 产出为事件
+
+任何解析失败(team 目录不存在 / workflow-state.json 缺失或损坏 / 字段缺失)都必须
+优雅降级为 None / 空列表,绝不能让不跑 devflow 的普通项目因为这一层报错。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, state as st
+
+
+def task_slug_from_team_dir(team_dir: Path) -> str | None:
+ """从 devflow team 目录名里剥离出 task_slug(固定前缀 `multi-agents-devflow-`)。"""
+ name = team_dir.name
+ prefix = agent_identity.TEAM_PREFIX
+ if not name.startswith(prefix):
+ return None
+ slug = name[len(prefix):].strip()
+ return slug or None
+
+
+def resolve_devflow_context(cwd: str, sid: str, cached_team_dir: str | None = None) -> dict[str, Any] | None:
+ """判断当前 session 是否处于某次 devflow 运行中;不是则返回 None。
+
+ 优先复用 `agent_identity.resolve_team_dir` 做 team 发现(Classic 全部场景,以及
+ Portable 在 `topology: team` 宿主——目前是 CodeBuddy——下也走同一套
+ `multi-agents-devflow-{task_slug}` 命名,可以直接复用,不用区分 edition)。
+
+ `topology: spawn` 的宿主(Codex/Claude/Cursor 的 Portable 适配器)不创建 team
+ 目录,找不到时退化成 `_scan_artifacts_for_active_run` 直接扫 `artifacts/` 目录。
+ 这个兜底本身就是尽力而为的启发式,不保证唯一/精确,见该函数的说明。
+
+ `artifacts_dir` 按 `devflow.defaults.yaml` 的默认值 `{project_root}/artifacts/{task_slug}`
+ 推算——项目若覆写了 `artifacts.root_dir`,这里暂不感知,读取 workflow-state.json
+ 找不到文件会安全返回 None,不会误报。
+ """
+ team_dir = agent_identity.resolve_team_dir(cwd, sid, cached_team_dir)
+ if team_dir is not None:
+ task_slug = task_slug_from_team_dir(team_dir)
+ if task_slug:
+ artifacts_dir = Path(cwd).expanduser() / "artifacts" / task_slug
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ return {
+ "task_slug": task_slug,
+ "team_dir": str(team_dir),
+ "artifacts_dir": str(artifacts_dir),
+ "workflow_state_path": str(workflow_state_path),
+ }
+ return _scan_artifacts_for_active_run(cwd)
+
+
+def _scan_artifacts_for_active_run(cwd: str) -> dict[str, Any] | None:
+ """没有 team 目录时的兜底发现:直接扫 `{cwd}/artifacts/*/workflow-state.json`。
+
+ 用于 `topology: spawn` 的宿主(没有 `.codebuddy/teams/` 这类目录可以反查),以及
+ Classic 没有真正暴露 `team_create` 时的降级场景。这是启发式,不是精确匹配:
+ 多个 task_slug 存在时,优先选"还没跑完"的那个;都跑完或都没跑完时选
+ `workflow-state.json` 文件 mtime 最新的一个。"跑完"的判定要兼容两套 schema——
+ Classic(v1.3)没有顶层 `status` 字段,看 `last_event == "workflow_completed"`;
+ Portable(v2.0)看顶层 `status in {"completed", "failed"}`。项目里如果同时有多个
+ 真正并发、都还没跑完的 devflow 运行,这个兜底可能选错——已知限制,不在这次范围内解决。
+ """
+ artifacts_root = Path(cwd).expanduser() / "artifacts"
+ if not artifacts_root.is_dir():
+ return None
+ candidates: list[tuple[tuple[int, float], str, Path]] = []
+ try:
+ children = list(artifacts_root.iterdir())
+ except Exception:
+ return None
+ for child in children:
+ if not child.is_dir():
+ continue
+ state_path = child / "workflow-state.json"
+ state = read_workflow_state(str(state_path))
+ if not isinstance(state, dict) or not isinstance(state.get("stages"), dict):
+ continue
+ try:
+ mtime = state_path.stat().st_mtime
+ except Exception:
+ mtime = 0.0
+ finished = (
+ str(state.get("last_event") or "") == "workflow_completed"
+ or str(state.get("status") or "") in {"completed", "failed"}
+ )
+ not_finished = 0 if finished else 1
+ candidates.append(((not_finished, mtime), child.name, state_path))
+ if not candidates:
+ return None
+ candidates.sort(key=lambda item: item[0], reverse=True)
+ _, task_slug, state_path = candidates[0]
+ return {
+ "task_slug": task_slug,
+ "team_dir": None,
+ "artifacts_dir": str(state_path.parent),
+ "workflow_state_path": str(state_path),
+ }
+
+
+def read_workflow_state(path: str) -> dict[str, Any] | None:
+ """安全读取 workflow-state.json;文件不存在或解析失败都返回 None。"""
+ try:
+ p = Path(path)
+ if not p.is_file():
+ return None
+ data = json.loads(p.read_text("utf-8"))
+ return data if isinstance(data, dict) else None
+ except Exception:
+ return None
+
+
+def stage_snapshot(workflow_state: dict[str, Any] | None) -> dict[str, Any]:
+ """把 workflow-state.json 投影成精简快照,供比对和事件输出使用。
+
+ 兼容两套 schema:Classic(v1.3,字段名 `executor`,有 `review_result`)和
+ Portable(v2.0,字段名 `executor_role`,没有 `review_result`,但顶层多了
+ `execution_mode`/`host_adapter`/`run_id`/`team_name` 这些 Classic 没有的上下文)。
+ 按 `version` 字段区分,取不到就都尝试取一遍,不强制要求调用方先判断是哪个 edition。
+ """
+ if not isinstance(workflow_state, dict):
+ return {}
+ stages_raw = workflow_state.get("stages")
+ stages: dict[str, Any] = {}
+ if isinstance(stages_raw, dict):
+ for name, info in stages_raw.items():
+ if not isinstance(info, dict):
+ continue
+ stages[name] = {
+ "status": info.get("status"),
+ "executor": info.get("executor") or info.get("executor_role"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ }
+ return {
+ "current_stage": workflow_state.get("current_stage"),
+ "size_class": workflow_state.get("size_class"),
+ "run_mode": workflow_state.get("run_mode"),
+ "schema_version": workflow_state.get("version"),
+ "execution_mode": workflow_state.get("execution_mode"),
+ "host_adapter": workflow_state.get("host_adapter"),
+ "run_id": workflow_state.get("run_id"),
+ "stages": stages,
+ }
+
+
+def diff_stage_changes(prev: dict[str, Any] | None, curr: dict[str, Any]) -> list[dict[str, Any]]:
+ """比较两次 stage 快照,只返回 status/retry_count/review_result 真正变化的阶段。
+
+ 首次观测(`prev` 为 None,即这个 session 第一次检测到 devflow)不产出任何变更——
+ 避免刚接入 observability 时,把一个已经跑了大半的 devflow 运行的全部历史阶段
+ 当成"新事件"一次性炸出来。之后每次变化都会被正常捕获。
+ """
+ if not isinstance(curr, dict) or prev is None:
+ return []
+ curr_stages = curr.get("stages") or {}
+ prev_stages = prev.get("stages") if isinstance(prev, dict) else {}
+ if not isinstance(prev_stages, dict):
+ prev_stages = {}
+ changes: list[dict[str, Any]] = []
+ for name, info in curr_stages.items():
+ if not isinstance(info, dict):
+ continue
+ before = prev_stages.get(name)
+ before = before if isinstance(before, dict) else {}
+ fields = ("status", "retry_count", "review_result")
+ if any(before.get(f) != info.get(f) for f in fields):
+ changes.append({
+ "stage": name,
+ "status": info.get("status"),
+ "executor": info.get("executor"),
+ "retry_count": info.get("retry_count", 0),
+ "review_result": info.get("review_result"),
+ })
+ return changes
+
+
+def resolve_and_diff(state_path: Path, sid: str, cwd: str) -> dict[str, Any] | None:
+ """解析当前 session 归属的 devflow 上下文,返回上下文 + 本次观测到的 stage 变更。
+
+ **不缓存"当前归属哪个 task_slug"这个结论本身**——同一个 sid 在其生命周期内可能
+ 先后归属不同的 devflow 运行。这不是理论场景:当运行时没有暴露真正的
+ `team_create`/`send_message`(因此没有独立的 team 成员 sid),devflow 会退化成
+ 在同一个长生命周期 session 里,先后跑好几次 `/start-devflow`;每次都必须重新判定
+ "现在最合适的 task_slug 是哪个",而不能沿用第一次探测到的那个——沿用旧结论会把
+ 第二次运行的所有事件都错误地归到第一次的 task_slug 下。
+
+ 重新判定的代价很低:`resolve_devflow_context` 对团队目录的探测会用上一次找到的
+ `team_dir` 做快速校验(只在真正失效时才重新扫描 `.codebuddy/teams/`);
+ `artifacts/` 兜底扫描也只是一次浅层 `iterdir()`,不是全量遍历。
+
+ 真正跨调用持久化的只有**按 task_slug 分别保存的 stage 快照历史**——切换到另一个
+ task_slug 不会污染对方的 diff 基线,也不会因为切回旧 task_slug 而把它已经观测过的
+ 历史重新当成"首次观测"。
+
+ 返回 None 表示这次调用没有探测到任何 devflow 上下文;否则返回
+ `{task_slug, artifacts_dir, workflow_state_path, current_stage, size_class, changes}`。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any] | None:
+ dv = st.get_devflow_state(state, sid)
+ cached_team_dir = (dv.get("context") or {}).get("team_dir") if isinstance(dv.get("context"), dict) else None
+ context = resolve_devflow_context(cwd, sid, cached_team_dir)
+ if not isinstance(context, dict):
+ st.set_devflow_state(state, sid, {"context": None})
+ return None
+
+ task_slug = str(context.get("task_slug") or "")
+ workflow_state = read_workflow_state(context.get("workflow_state_path", ""))
+ curr = stage_snapshot(workflow_state)
+ snapshots = dv.get("snapshots")
+ if not isinstance(snapshots, dict):
+ snapshots = {}
+ prev = snapshots.get(task_slug)
+ changes = diff_stage_changes(prev if isinstance(prev, dict) else None, curr)
+ snapshots[task_slug] = curr
+ st.set_devflow_state(state, sid, {"context": context, "snapshots": snapshots})
+
+ result = dict(context)
+ result["current_stage"] = curr.get("current_stage")
+ result["size_class"] = curr.get("size_class")
+ result["schema_version"] = curr.get("schema_version")
+ result["execution_mode"] = curr.get("execution_mode")
+ result["changes"] = changes
+ return result
+
+ return st.update_state_locked(state_path, _update)
diff --git a/.cursor/skills/agent-observability/scripts/core/emitter.py b/.cursor/skills/agent-observability/scripts/core/emitter.py
new file mode 100644
index 00000000..a41dfc05
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/emitter.py
@@ -0,0 +1,578 @@
+"""ndjson 发射层。
+
+只输出当前真正需要的核心字段:
+- common: data_source
+- tool: event, sid, ts, agent, tool, ms, skill, rule, transcript_path
+- usage: event, sid, ts, agent, tool, tokens, model, cost_usd, transcript_path
+- start: event, sid, ts, agent
+- stop: event, sid, ts, agent, tokens, model, cost_usd, cost_session_usd, transcript_path
+- error: event, sid, ts, phase, error
+
+历史 x_* 扩展字段、stop skill/rule 汇总、schema 版本号等都不再生成。
+
+`cost_usd` 的价格表 = 内置 `config/pricing.json` 与用户覆盖文件(默认
+`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`,可用
+`AOBS_PRICING_OVERRIDES_PATH` 改路径)的字段级合并结果,详见 `load_prices()`。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from . import cls_sink
+from . import state as st
+
+DEFAULT_PRICES_PATH = Path(__file__).resolve().parents[2] / "config" / "pricing.json"
+DEFAULT_DATA_SOURCE = "codebuddy-cli"
+
+
+def _default_overrides_path() -> Path | None:
+ """用户定价覆盖文件的默认位置:`<project_root>/.codebuddy/agent-observability/pricing.overrides.json`。
+
+ 刻意放在 `skills/` 树**外**:`scripts/build-classic-hosts.py` 会整棵同步
+ `.codebuddy/skills`,放树内会 (a) 每次改动都产生 `--check` drift,(b) 把用户的
+ 自定义价格复制进 `.claude`/`.cursor` 宿主包;放树外则既不参与同步,也不会被
+ `config/pricing.json` 的后续更新冲掉。
+ """
+ try:
+ project_root = Path(__file__).resolve().parents[5]
+ except IndexError:
+ return None
+ return project_root / ".codebuddy" / "agent-observability" / "pricing.overrides.json"
+
+
+# None 表示"拿不到项目根",此时等同于"没有覆盖文件"(纯内置价格表)。
+DEFAULT_OVERRIDES_PATH: Path | None = _default_overrides_path()
+
+
+def get_log_path(base_dir: Path) -> Path:
+ """返回 metrics 日志路径,并确保目录已存在。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / "metrics.ndjson"
+
+
+def _first_record_ts(log_path: Path, sid: str) -> float | None:
+ """从 metrics.ndjson 中找到某个 session 的最早 ts。
+
+ state 只保留最近几个 session,长流程或历史 session 可能被 prune 后重建,
+ 因此 `started_at` 不能作为唯一权威。日志里的首条 ts 更接近
+ session/workflow 的真实起点。
+ """
+ if not sid or not log_path.exists():
+ return None
+ first_ts: float | None = None
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid:
+ continue
+ try:
+ ts = float(rec.get("ts"))
+ except Exception:
+ continue
+ if first_ts is None or ts < first_ts:
+ first_ts = ts
+ except Exception:
+ return None
+ return first_ts
+
+
+def _inject_session_duration(record: dict[str, Any], log_path: Path) -> None:
+ """从 state 文件读取 session started_at,计算 session_duration_sec 注入 record。
+ 同时扫描 metrics.ndjson 累计 session 级别 token 总量。"""
+ sid = record.get("sid")
+ if not sid or "session_duration_sec" in record:
+ return
+ try:
+ now = float(record.get("ts") or time.time())
+ started_candidates: list[float] = []
+ state_path = log_path.parent / ".state.json"
+ state = st.load_state(state_path)
+ sess = state.get(sid)
+ if isinstance(sess, dict):
+ try:
+ state_started_at = float(sess.get("started_at") or 0)
+ except Exception:
+ state_started_at = 0.0
+ if state_started_at > 0:
+ started_candidates.append(state_started_at)
+ log_started_at = _first_record_ts(log_path, str(sid))
+ if log_started_at is not None and log_started_at > 0:
+ started_candidates.append(log_started_at)
+ if not started_candidates:
+ started_candidates.append(now)
+ started_at = min(started_candidates)
+ record["session_duration_sec"] = round(max(0.0, now - started_at), 3)
+ except Exception:
+ return
+
+ # 累计 session 级别 token(扫描 metrics.ndjson 尾部)
+ try:
+ total_input = 0
+ total_output = 0
+ total_cache = 0
+ if log_path.exists():
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") != "usage":
+ continue
+ tokens = rec.get("tokens")
+ if not isinstance(tokens, dict):
+ continue
+ total_input += int(tokens.get("input") or 0)
+ total_output += int(tokens.get("output") or 0)
+ total_cache += int(tokens.get("cache_read") or 0)
+ record["session_total_tokens"] = total_input + total_output
+ record["session_input_tokens"] = total_input
+ record["session_output_tokens"] = total_output
+ record["session_cache_tokens"] = total_cache
+ except Exception:
+ return
+
+
+def emit(log_path: Path, record: dict[str, Any]) -> None:
+ """向 ndjson 日志追加一条记录。"""
+ record.setdefault("data_source", DEFAULT_DATA_SOURCE)
+ record.setdefault("ts", time.time())
+ _inject_session_duration(record, log_path)
+ with log_path.open("a", encoding="utf-8") as fp:
+ fp.write(json.dumps(record, ensure_ascii=False) + "\n")
+ try:
+ cls_sink.mirror_record(record)
+ except Exception:
+ return
+
+
+def build_tool_event(
+ sid: str,
+ tool: str | None,
+ duration_ms: int | None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+ pt_id: str | None = None,
+) -> dict[str, Any]:
+ """构造 tool 事件记录,只包含调用信息与耗时。
+
+ `task_slug` / `stage` / `pt_id` 只有在检测到 devflow 运行时才会出现(见
+ `core/devflow.py`),非 devflow 项目不受影响。
+ """
+ record = {
+ "event": "tool",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "ms": duration_ms,
+ }
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if turn_id:
+ record["turn_id"] = turn_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ if pt_id:
+ record["pt_id"] = pt_id
+ return record
+
+
+def build_usage_event(
+ sid: str,
+ tool: str | None,
+ tokens: dict[str, Any],
+ active_agent: str | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造 LLM usage 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "usage",
+ "sid": sid,
+ "agent": active_agent or "main",
+ "tool": tool,
+ "tokens": tokens,
+ }
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_start_event(
+ sid: str,
+ agent: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 start 事件记录。
+
+ 初始化阶段没有明确角色时,统一记为 ``main``。
+ """
+ return {
+ "event": "start",
+ "sid": sid,
+ "agent": agent or "main",
+ }
+
+
+def build_prompt_submit_event(
+ sid: str,
+ turn_id: str,
+ agent: str | None = None,
+ prompt_len: int | None = None,
+) -> dict[str, Any]:
+ """构造 `user_prompt_submit` 事件,作为 turn 边界标记。
+
+ 这条记录会落到 metrics.ndjson,方便下游把 turn 和 AgentLens trace 对上。
+ """
+ record: dict[str, Any] = {
+ "event": "user_prompt_submit",
+ "sid": sid,
+ "agent": agent or "main",
+ "turn_id": turn_id,
+ }
+ if prompt_len is not None:
+ record["prompt_len"] = int(prompt_len)
+ return record
+
+
+def build_stop_event(
+ sid: str,
+ tokens: dict | None = None,
+ model: str | None = None,
+ cost_usd: float | None = None,
+ cost_session_usd: float | None = None,
+ active_agent: str | None = None,
+ transcript_path: str | None = None,
+ source_offset: int | None = None,
+ turn_id: str | None = None,
+ message_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 stop 事件记录。"""
+ record: dict[str, Any] = {
+ "event": "stop",
+ "sid": sid,
+ "agent": active_agent or "main",
+ }
+ if tokens:
+ record["tokens"] = tokens
+ if model:
+ record["model"] = model
+ if cost_usd is not None:
+ record["cost_usd"] = cost_usd
+ if cost_session_usd is not None:
+ record["cost_session_usd"] = cost_session_usd
+ if transcript_path:
+ record["transcript_path"] = transcript_path
+ if source_offset is not None:
+ record["source_offset"] = source_offset
+ if turn_id:
+ record["turn_id"] = turn_id
+ if message_id:
+ record["message_id"] = message_id
+ if task_slug:
+ record["task_slug"] = task_slug
+ if stage:
+ record["stage"] = stage
+ return record
+
+
+def build_error_event(
+ phase: str,
+ error: str,
+ sid: str | None = None,
+) -> dict[str, Any]:
+ """构造最小化的 error 事件记录。"""
+ return {
+ "event": "error",
+ "sid": sid or "",
+ "phase": phase,
+ "error": error,
+ }
+
+
+def build_stage_transition_event(
+ sid: str,
+ task_slug: str,
+ stage: str,
+ status: str | None = None,
+ executor: str | None = None,
+ retry_count: int = 0,
+ review_result: str | None = None,
+) -> dict[str, Any]:
+ """构造 devflow stage 变更事件(只在检测到 devflow 运行、且 stage 真的变化时发出)。
+
+ 对应 `workflow-state.json` 里某个 stage 的 `status`/`retry_count`/`review_result`
+ 发生变化——retry_count 上升或 review_result="failed" 是 devflow 里最值得关注的
+ 信号(返工/打回循环),比 hook 自身的 `error` 事件更贴近业务语义。
+ """
+ record: dict[str, Any] = {
+ "event": "stage_transition",
+ "sid": sid,
+ "task_slug": task_slug,
+ "stage": stage,
+ }
+ if status:
+ record["status"] = status
+ if executor:
+ record["executor"] = executor
+ if retry_count:
+ record["retry_count"] = int(retry_count)
+ if review_result:
+ record["review_result"] = review_result
+ return record
+
+
+def resolve_overrides_path() -> Path | None:
+ """返回当前生效的覆盖文件路径:`AOBS_PRICING_OVERRIDES_PATH` 优先,否则默认路径。
+
+ 返回 `None` 表示"不加载任何覆盖"(纯内置价格表)。支持 `~` 展开。
+ """
+ raw = os.environ.get("AOBS_PRICING_OVERRIDES_PATH", "").strip()
+ if raw:
+ return Path(raw).expanduser()
+ return DEFAULT_OVERRIDES_PATH
+
+
+def _coerce_price_table(data: Any) -> dict[str, dict[str, float]]:
+ """把任意 JSON 结果规整成 `{model: {field: float}}`,坏数据按字段/按模型跳过。
+
+ 与内置表加载的差别只有一处:内置表遇到非数字会整体抛错降级,这里逐字段跳过——
+ 用户的补丁文件里写错一个字段不应该把其余正确的覆盖一起丢掉,更不应该让 hook 挂掉。
+ """
+ if not isinstance(data, dict):
+ return {}
+ table: dict[str, dict[str, float]] = {}
+ for raw_key, raw_value in data.items():
+ if not isinstance(raw_value, dict):
+ continue
+ key = str(raw_key).strip().lower()
+ if not key:
+ continue
+ row: dict[str, float] = {}
+ for price_key, price_value in raw_value.items():
+ # bool 是 int 的子类,True 会被 float() 变成 1.0,这里按"不是价格"处理。
+ if price_value is None or isinstance(price_value, bool):
+ continue
+ try:
+ row[str(price_key).strip().lower()] = float(price_value)
+ except (TypeError, ValueError):
+ continue
+ # 全是坏字段的模型不落表:否则它会被 `lookup_price` 命中成 {},
+ # 既算不出成本又不算"未定价",看板上会变成一个查不到原因的空洞。
+ if row:
+ table[key] = row
+ return table
+
+
+def load_price_overrides(path: Path | None = None) -> dict[str, dict[str, float]]:
+ """加载用户定价覆盖文件;任何异常都静默降级为空覆盖(纯内置价格表)。
+
+ 静默是刻意的:这个文件是给人手写的常驻配置,hook 每次都是新进程,
+ 一旦因格式问题抛异常/打印,会让整条 hook 链路变得不可用。
+ """
+ try:
+ target = path if path is not None else resolve_overrides_path()
+ if not target:
+ return {}
+ with Path(target).expanduser().open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ return _coerce_price_table(data)
+
+
+def merge_prices(
+ base: dict[str, dict[str, float]] | None,
+ overrides: dict[str, dict[str, float]] | None,
+) -> dict[str, dict[str, float]]:
+ """字段级合并价格表:覆盖里写出的字段替换内置值,没写的字段沿用内置值。
+
+ 可以新增内置表里不存在的模型;**不支持删除**内置模型或字段(合并只能加不能减)。
+ """
+ merged: dict[str, dict[str, float]] = {}
+ for model, row in (base or {}).items():
+ if isinstance(row, dict):
+ merged[model] = dict(row)
+ for model, patch in (overrides or {}).items():
+ if not isinstance(patch, dict):
+ continue
+ merged.setdefault(model, {}).update(patch)
+ return merged
+
+
+def _load_builtin_prices() -> dict[str, dict[str, float]]:
+ """从 `config/pricing.json` 中一次性加载内置模型价格配置(不含用户覆盖)。"""
+ path = os.environ.get("AOBS_PRICES_PATH", "").strip()
+ prices_path = Path(path).expanduser() if path else DEFAULT_PRICES_PATH
+ try:
+ with prices_path.open("r", encoding="utf-8") as fp:
+ data = json.load(fp)
+ except Exception:
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ return {
+ str(key).lower(): {price_key: float(price_value) for price_key, price_value in value.items()}
+ for key, value in data.items()
+ if isinstance(value, dict)
+ }
+
+
+@lru_cache(maxsize=1)
+def load_prices() -> dict[str, dict[str, float]]:
+ """内置价格表 + 用户覆盖文件的合并结果(字段级)。
+
+ 结果带 `lru_cache`:hook 是短命进程,一次会话里只该读一次盘;长驻进程或单测里
+ 改了覆盖文件/环境变量后,调 `clear_price_cache()` 让下一次调用重新加载。
+ """
+ return merge_prices(_load_builtin_prices(), load_price_overrides())
+
+
+def clear_price_cache() -> None:
+ """丢弃 `load_prices()` 的缓存,让下一次调用重读磁盘与环境变量。"""
+ load_prices.cache_clear()
+
+
+def lookup_price(model: str | None) -> dict[str, float] | None:
+ """为一个具体模型名找到最匹配的价格配置项。"""
+ if not model or not isinstance(model, str):
+ return None
+ normalized = model.lower().strip()
+ if not normalized:
+ return None
+ prices = load_prices()
+ if normalized in prices:
+ return prices[normalized]
+ best_key: str | None = None
+ for key in prices:
+ if key in normalized and (best_key is None or len(key) > len(best_key)):
+ best_key = key
+ if best_key is None:
+ return None
+ return prices[best_key]
+
+
+def is_unpriced(model: str | None) -> bool:
+ """模型是否完全没命中价格表(含模糊匹配)。
+
+ "未定价"的唯一口径就是 `lookup_price(...) is None`(D4):模糊(最长子串)命中的
+ 模型能算出成本,就不该出现在看板的"建议补价"提示里。
+ """
+ return lookup_price(model) is None
+
+
+def estimate_cost(tokens: dict | None, model: str | None) -> dict[str, Any] | None:
+ """根据归一化后的 token 总量估算单条 usage 事件的成本。"""
+ if not isinstance(tokens, dict):
+ return None
+ rates = lookup_price(model)
+ if not rates:
+ return None
+
+ def _int(key: str) -> int:
+ try:
+ return int(tokens.get(key) or 0)
+ except Exception:
+ return 0
+
+ output = _int("output")
+ cache_read = _int("cache_read")
+ cache_write = _int("cache_creation")
+ raw_input = _int("input")
+ fresh_input = raw_input - cache_read - cache_write if raw_input and raw_input >= (cache_read + cache_write) else raw_input
+ cost = (
+ fresh_input * rates.get("input", 0.0)
+ + cache_read * rates.get("cache_read", 0.0)
+ + cache_write * rates.get("cache_write", 0.0)
+ + output * rates.get("output", 0.0)
+ ) / 1_000_000.0
+
+ matched_key = None
+ normalized = (model or "").lower()
+ for key in load_prices():
+ if key in normalized and (matched_key is None or len(key) > len(matched_key)):
+ matched_key = key
+ if matched_key is None and normalized in load_prices():
+ matched_key = normalized
+
+ return {
+ "usd": round(cost, 6),
+ "model_matched": matched_key,
+ "rates": rates,
+ }
+
+
+def cost_of(tokens: dict | None, model: str | None) -> float | None:
+ """只返回美元成本值的便捷封装。"""
+ if not tokens or not model:
+ return None
+ info = estimate_cost(tokens, model)
+ if not info:
+ return None
+ return info.get("usd")
+
+
+def sum_session_cost(log_path: Path, sid: str) -> float | None:
+ """尽力根据已发出的事件反算整个 session 的总成本。"""
+ if not log_path.exists() or not sid:
+ return None
+ total = 0.0
+ seen = False
+ try:
+ with log_path.open("r", encoding="utf-8") as fp:
+ for line in fp:
+ if not line.strip().startswith("{"):
+ continue
+ try:
+ rec = json.loads(line)
+ except Exception:
+ continue
+ if rec.get("sid") != sid or rec.get("event") not in {"usage", "tool"}:
+ continue
+ cost = rec.get("cost_usd")
+ if isinstance(cost, (int, float)):
+ total += float(cost)
+ seen = True
+ except Exception:
+ return None
+ return round(total, 6) if seen else None
diff --git a/.cursor/skills/agent-observability/scripts/core/runtime.py b/.cursor/skills/agent-observability/scripts/core/runtime.py
new file mode 100644
index 00000000..9c647bc0
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/runtime.py
@@ -0,0 +1,598 @@
+from __future__ import annotations
+"""Hook 主编排入口。
+
+这一层负责把外部 hook phase 分发到内部能力:
+- session-start / user-prompt-submit / pre / post / stop
+- 组装统一运行时路径
+- 串联 collector / emitter / agentlens,并承担 transcript 运行时编排
+"""
+
+import os
+import re
+import time
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import agent_identity, agentlens, collector, devflow, emitter, scanner, state as st
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+ """运行时常用路径集合,避免每个分支重复计算。"""
+ base_dir: Path
+ state_path: Path
+ pending_path: Path
+ log_path: Path
+
+
+def base_dir() -> Path:
+ """返回 hook 运行时使用的根目录。"""
+ # 运行时产物统一写到 skill 根目录下的 logs/,保持与旧路径兼容。
+ return Path(__file__).resolve().parents[2]
+
+
+def build_runtime_paths() -> RuntimePaths:
+ """构造本次 hook 运行要用到的路径集合。"""
+ base = base_dir()
+ return RuntimePaths(
+ base_dir=base,
+ state_path=st.get_state_path(base),
+ pending_path=st.get_pending_path(base),
+ log_path=emitter.get_log_path(base),
+ )
+
+
+def session_id_of(data: dict[str, Any]) -> str:
+ """兼容不同字段名,提取 session id。"""
+ return str(data.get("session_id") or data.get("sid") or "")
+
+
+def cwd(data: dict[str, Any]) -> str:
+ """解析当前项目工作目录。"""
+ return str(data.get("cwd") or os.environ.get("CODEBUDDY_PROJECT_DIR") or os.getcwd())
+
+
+def normalize_phase(raw: str | None) -> str:
+ """把多种 phase 写法折叠成统一内部枚举。"""
+ phase = (raw or "").strip().lower()
+ return {
+ "sessionstart": "session-start",
+ "session_start": "session-start",
+ "session-start": "session-start",
+ "pretooluse": "pre",
+ "pre": "pre",
+ "posttooluse": "post",
+ "post": "post",
+ "stop": "stop",
+ "userpromptsubmit": "user-prompt-submit",
+ "user_prompt_submit": "user-prompt-submit",
+ "user-prompt-submit": "user-prompt-submit",
+ "prompt": "user-prompt-submit",
+ }.get(phase, phase)
+
+
+def emit_error(phase: str, sid: str, err: Exception) -> None:
+ """把运行时异常写成 error 事件,而不是直接中断 hook。"""
+ rec = emitter.build_error_event(phase=phase, error=f"{type(err).__name__}: {err}", sid=sid)
+ rec["x_traceback"] = traceback.format_exc(limit=5)[-1200:]
+ emitter.emit(build_runtime_paths().log_path, rec)
+
+
+def derive_turn_id(data: dict[str, Any]) -> str:
+ """优先复用外部已有 id,否则生成一个本地 turn id。"""
+ for key in ("turn_id", "prompt_id", "request_id", "message_id"):
+ raw = data.get(key)
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ if isinstance(raw, (int, float)) and raw:
+ return str(raw)
+ return f"turn-{int(time.time() * 1000)}"
+
+
+def prompt_text_length(data: dict[str, Any]) -> int | None:
+ """统计用户 prompt 的文本长度,用于 turn 边界指标。"""
+ for key in ("prompt", "user_prompt", "message", "content", "text"):
+ val = data.get(key)
+ if isinstance(val, str):
+ return len(val)
+ if isinstance(val, list):
+ total = 0
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ total += len(txt)
+ elif isinstance(item, str):
+ total += len(item)
+ if total:
+ return total
+ return None
+
+
+def extract_prompt_text(data: dict[str, Any]) -> str:
+ """从 hook payload 中提取可读的 prompt 文本。"""
+ for key in ("prompt", "user_prompt", "message", "text"):
+ val = data.get(key)
+ if isinstance(val, str) and val.strip():
+ return val.strip()
+ if isinstance(val, list):
+ parts = []
+ for item in val:
+ if isinstance(item, dict):
+ txt = item.get("text")
+ if isinstance(txt, str):
+ parts.append(txt)
+ elif isinstance(item, str):
+ parts.append(item)
+ if parts:
+ return "\n".join(parts).strip()
+ return ""
+
+
+def derive_business_scenario(prompt_text: str) -> str | None:
+ """从 prompt 文本中派生一个简短业务场景标识。"""
+ if not prompt_text:
+ return None
+
+ m = re.search(r"标题[::]\s*(.+?)(?:\s*描述[::]|\s*$)", prompt_text, re.DOTALL)
+ if m:
+ title = m.group(1).strip()[:60]
+ else:
+ title = prompt_text[:50].strip()
+
+ sanitized = re.sub(r"[^\w\u4e00-\u9fff\-]", "-", title)
+ sanitized = re.sub(r"-{2,}", "-", sanitized).strip("-")
+ return sanitized if sanitized else None
+
+
+def handle_session_start(data: dict[str, Any]) -> None:
+ """处理 SessionStart:预热 inventory,写 start 事件,初始化 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+ emitter.emit(paths.log_path, emitter.build_start_event(sid=current_sid, agent="main"))
+ agentlens.emit_session_start(state_path=paths.state_path, sid=current_sid, cwd=cwd_value, agent="main")
+
+
+def handle_user_prompt_submit(data: dict[str, Any]) -> None:
+ """处理 UserPromptSubmit:建立 turn 边界,并打开 AgentLens turn。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ turn_id = derive_turn_id(data)
+ prompt_len = prompt_text_length(data)
+ prompt_text = extract_prompt_text(data)
+ business_scenario = derive_business_scenario(prompt_text)
+
+ emitter.emit(
+ paths.log_path,
+ emitter.build_prompt_submit_event(sid=current_sid, turn_id=turn_id, agent="main", prompt_len=prompt_len),
+ )
+ agentlens.emit_turn_start(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ turn_id=turn_id,
+ prompt_meta={"prompt_len": prompt_len} if prompt_len is not None else None,
+ business_scenario=business_scenario,
+ )
+
+
+def handle_pre(data: dict[str, Any]) -> None:
+ """处理 PreToolUse:仅记录 pending,等待 post 配对。"""
+ collector.record_pre(build_runtime_paths().pending_path, data)
+
+
+def handle_post(data: dict[str, Any]) -> None:
+ """处理 PostToolUse:计算耗时、归因 agent、发 tool/usage 事件。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ duration_ms = collector.record_post(paths.pending_path, data)
+
+ skills_meta, rules_meta = collector.load_cached_inventory(paths.state_path, current_sid)
+ if not skills_meta and not rules_meta:
+ skills_meta, rules_meta = scanner.scan_skills_and_rules(cwd_value)
+ collector.cache_inventory(paths.state_path, current_sid, skills_meta, rules_meta)
+
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ used_skills, used_rules = collector.record_tool_usage(
+ state_path=paths.state_path,
+ sid=current_sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent=active_agent,
+ collect_skills=True,
+ )
+
+ tool_name = str(data.get("tool_name") or "")
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ event_ts = time.time()
+ tool_call_id = collector.extract_tool_call_id(data)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ )
+ tool_context = collector.find_current_tool_context(
+ state_path=paths.state_path,
+ sid=current_sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=tool_call_id,
+ event_ts=event_ts,
+ claim=True,
+ )
+ duplicate_tool_context = bool(isinstance(tool_context, dict) and tool_context.get("duplicate"))
+ if duplicate_tool_context:
+ tool_context = None
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ transcript_path = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ active_agent = resolved_agent
+
+ tool_pt_id = str(tool_context.get("pt_id") or "").strip() if isinstance(tool_context, dict) else None
+ tool_event = emitter.build_tool_event(
+ sid=current_sid,
+ tool=tool_name,
+ duration_ms=duration_ms,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ pt_id=tool_pt_id,
+ )
+ tool_event["ts"] = event_ts
+ tool_event["skill"] = used_skills
+ tool_event["rule"] = used_rules
+ tool_event["cwd"] = cwd_value
+ if tool_call_id:
+ tool_event["call_id"] = tool_call_id
+ if isinstance(tool_context, dict):
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+
+ usage_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name=tool_name,
+ event_kind="usage",
+ max_lines=80,
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ if duplicate_tool_context:
+ if not usage_events:
+ return
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=None,
+ usage_events=usage_events,
+ )
+ return
+ if str(tool_event.get("message_id") or "").strip():
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ fallback_usage = collector.find_fallback_usage_event(tool_event, usage_events)
+ fallback_usage_mid = str((fallback_usage or {}).get("message_id") or "").strip() or None
+ if fallback_usage_mid:
+ tool_event["message_id"] = fallback_usage_mid
+ emitter.emit(paths.log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=paths.state_path,
+ sid=current_sid,
+ tool_event=tool_event,
+ usage_events=usage_events,
+ )
+ return
+
+ st.append_pending_tool_emit(paths.state_path, current_sid, tool_event)
+
+
+def handle_stop(data: dict[str, Any]) -> None:
+ """处理 Stop:补发 transcript 事件、汇总 session 成本并关闭 AgentLens。"""
+ current_sid = session_id_of(data)
+ if not current_sid:
+ return
+ paths = build_runtime_paths()
+ cwd_value = cwd(data)
+ active_agent, _ = agent_identity.resolve_active_agent_for_event(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ data=data,
+ )
+ transcript_path = collector.transcript_path(data)
+ turn_id = current_turn_id(paths.state_path, current_sid)
+ dv_ctx = resolve_devflow(paths.state_path, current_sid, cwd_value, paths.log_path)
+ task_slug = str(dv_ctx.get("task_slug") or "").strip() if dv_ctx else None
+ stage = str(dv_ctx.get("current_stage") or "").strip() if dv_ctx else None
+ stop_events = emit_transcript_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ transcript_paths=collector.settled_related_transcript_paths(current_sid, transcript_path),
+ current_transcript_path=transcript_path,
+ active_agent=active_agent,
+ tool_name="__stop__",
+ event_kind="stop",
+ max_lines=200,
+ cost_session=emitter.sum_session_cost(paths.log_path, current_sid),
+ turn_id=turn_id,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ flush_pending_tool_events(
+ state_path=paths.state_path,
+ log_path=paths.log_path,
+ sid=current_sid,
+ force_emit_fallback=True,
+ )
+ agentlens.emit_session_stop(
+ state_path=paths.state_path,
+ sid=current_sid,
+ cwd=cwd_value,
+ active_agent=active_agent,
+ transcript_path=transcript_path,
+ stop_events=stop_events,
+ )
+
+
+def resolve_devflow(state_path: Path, sid: str, cwd_value: str, log_path: Path) -> dict[str, Any] | None:
+ """解析 devflow 上下文,并把本次观测到的 stage 变更立即发成 `stage_transition` 事件。
+
+ 任何异常都吞掉、返回 None——devflow 感知是可选增强,绝不能让不跑 devflow 的
+ 项目或 workflow-state.json 格式变化导致 hook 报错。
+ """
+ try:
+ dv_ctx = devflow.resolve_and_diff(state_path, sid, cwd_value)
+ except Exception:
+ return None
+ if not isinstance(dv_ctx, dict):
+ return None
+ task_slug = str(dv_ctx.get("task_slug") or "").strip()
+ if not task_slug:
+ return None
+ for change in dv_ctx.get("changes") or []:
+ if not isinstance(change, dict):
+ continue
+ event = emitter.build_stage_transition_event(
+ sid=sid,
+ task_slug=task_slug,
+ stage=str(change.get("stage") or ""),
+ status=change.get("status"),
+ executor=change.get("executor"),
+ retry_count=int(change.get("retry_count") or 0),
+ review_result=change.get("review_result"),
+ )
+ emitter.emit(log_path, event)
+ return dv_ctx
+
+
+def current_turn_id(state_path: Path, sid: str) -> str | None:
+ """从 state 中读取当前 session 激活中的 turn id。"""
+ try:
+ turn = st.get_current_turn(state_path, sid)
+ except Exception:
+ turn = None
+ if isinstance(turn, dict):
+ raw = turn.get("turn_id")
+ if isinstance(raw, str) and raw.strip():
+ return raw.strip()
+ return None
+
+
+def flush_pending_tool_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ force_emit_fallback: bool = False,
+) -> None:
+ """强制 flush 延迟的 tool 事件,常用于 stop/replay 路径。"""
+ pending = st.get_pending_tool_emits(state_path, sid)
+ if not pending:
+ return
+
+ remaining: list[dict[str, Any]] = []
+ for tool_event in pending:
+ tool_name = str(tool_event.get("tool") or "").strip()
+ transcript_path = str(tool_event.get("transcript_path") or "").strip()
+ call_id = str(tool_event.get("call_id") or "").strip() or None
+ event_ts = tool_event.get("ts")
+ try:
+ event_ts_float = float(event_ts) if event_ts is not None else None
+ except Exception:
+ event_ts_float = None
+
+ tool_context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=transcript_path,
+ tool_name=tool_name,
+ call_id=call_id,
+ event_ts=event_ts_float,
+ claim=True,
+ )
+ if isinstance(tool_context, dict) and tool_context.get("duplicate"):
+ continue
+ if isinstance(tool_context, dict):
+ resolved_transcript_path = str(tool_context.get("transcript_path") or "").strip()
+ if resolved_transcript_path:
+ tool_event["transcript_path"] = resolved_transcript_path
+ resolved_agent = str(tool_context.get("agent") or "").strip()
+ if resolved_agent:
+ tool_event["agent"] = resolved_agent
+ tool_message_id = str(tool_context.get("message_id") or "").strip() or None
+ if tool_message_id:
+ tool_event["message_id"] = tool_message_id
+ tool_details = tool_context.get("tool_details")
+ if isinstance(tool_details, dict) and tool_details:
+ tool_event["tool_details"] = dict(tool_details)
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ if force_emit_fallback:
+ emitter.emit(log_path, tool_event)
+ agentlens.emit_post_step(
+ state_path=state_path,
+ sid=sid,
+ tool_event=tool_event,
+ usage_events=[],
+ )
+ continue
+ remaining.append(tool_event)
+
+ st.replace_pending_tool_emits(state_path, sid, remaining)
+
+
+def emit_transcript_events(
+ *,
+ state_path: Path,
+ log_path: Path,
+ sid: str,
+ transcript_paths: list[str],
+ current_transcript_path: str,
+ active_agent: str,
+ tool_name: str,
+ event_kind: str,
+ max_lines: int,
+ cost_session: float | None = None,
+ turn_id: str | None = None,
+ task_slug: str | None = None,
+ stage: str | None = None,
+) -> list[dict[str, Any]]:
+ """发出基于 transcript 增量重建得到的 usage/stop 事件。"""
+ emitted_events: list[dict[str, Any]] = []
+ current_resolved = str(Path(current_transcript_path).resolve()) if current_transcript_path else ""
+ for path in transcript_paths:
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=path,
+ max_lines=max_lines,
+ )
+ entries = scan.get("entries", []) or []
+ event_tool = tool_name if event_kind == "usage" and path == current_resolved else "model_request"
+ event_agent = active_agent if path == current_resolved else agent_identity.agent_for_transcript_path(path, active_agent)
+
+ for idx, entry in enumerate(entries):
+ event_key = collector.build_transcript_event_key(kind=event_kind, tool=event_tool, entry=entry)
+ if not st.claim_transcript_event(state_path, sid, event_key, path):
+ continue
+ tokens = entry.get("tokens")
+ model = entry.get("model")
+ if event_kind == "stop":
+ event = emitter.build_stop_event(
+ sid=sid,
+ tokens=tokens,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ cost_session_usd=cost_session if idx == len(entries) - 1 else None,
+ active_agent=event_agent,
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ else:
+ event = emitter.build_usage_event(
+ sid=sid,
+ tool=event_tool,
+ tokens=tokens,
+ active_agent=event_agent,
+ model=model,
+ cost_usd=emitter.cost_of(tokens, model),
+ transcript_path=path,
+ source_offset=int(entry.get("offset", 0) or 0),
+ turn_id=turn_id,
+ message_id=str(entry.get("message_id") or "").strip() or None,
+ task_slug=task_slug,
+ stage=stage,
+ )
+ emitter.emit(log_path, event)
+ emitted_events.append(event)
+
+ st.commit_transcript_progress(
+ state_path,
+ sid,
+ path,
+ offset=int(scan.get("new_offset", 0) or 0),
+ last_cumulative_usage=scan.get("last_cumulative"),
+ )
+ return emitted_events
+
+
+def main(argv: list[str]) -> int:
+ """读取 stdin 输入并按 phase 执行对应 hook 处理分支。"""
+ phase = normalize_phase(argv[0] if argv else "")
+ current_sid = ""
+ try:
+ data = collector.read_stdin_json()
+ current_sid = session_id_of(data)
+ if phase == "session-start":
+ handle_session_start(data)
+ elif phase == "user-prompt-submit":
+ handle_user_prompt_submit(data)
+ elif phase == "pre":
+ handle_pre(data)
+ elif phase == "post":
+ handle_post(data)
+ elif phase == "stop":
+ handle_stop(data)
+ else:
+ emitter.emit(
+ build_runtime_paths().log_path,
+ emitter.build_error_event(phase=phase or "unknown", error=f"Unsupported phase: {phase!r}", sid=current_sid),
+ )
+ except Exception as exc:
+ emit_error(phase=phase or "unknown", sid=current_sid, err=exc)
+ return 0
diff --git a/.cursor/skills/agent-observability/scripts/core/scanner.py b/.cursor/skills/agent-observability/scripts/core/scanner.py
new file mode 100644
index 00000000..86b5305e
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/scanner.py
@@ -0,0 +1,496 @@
+"""Skill / Rule 静态扫描层。
+
+这一层只负责扫描项目里的 `.codebuddy/skills` 与 `.codebuddy/rules`:
+- 识别有哪些可用 skill / rule
+- 提取它们的基础元数据与 frontmatter
+- 提供 path-based 命中推断依赖的 inventory 信息
+
+它不依赖具体 workflow 语义,本身是通用层。
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# --- 用于解析 SKILL.md / RULE.mdc frontmatter 的正则 ---
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.S)
+NAME_FIELD_RE = re.compile(r"^name:\s*(.+)$", re.M)
+VERSION_FIELD_RE = re.compile(r"^version:\s*(.+)$", re.M)
+AUTHOR_FIELD_RE = re.compile(r"^author:\s*(.+)$", re.M)
+TAGS_FIELD_RE = re.compile(r"^tags:\s*\[([^\]]+)\]", re.M)
+DESC_FIELD_RE = re.compile(r"^description:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+ALWAYS_APPLY_RE = re.compile(r"^alwaysApply:\s*(true|false)\s*$", re.M | re.I)
+ENABLED_RE = re.compile(r"^enabled:\s*(true|false)\s*$", re.M | re.I)
+GLOBS_RE = re.compile(r"^globs:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+APPLY_AGENTS_RE = re.compile(r"^applyAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+EXCLUDE_AGENTS_RE = re.compile(r"^excludeAgents:\s*(.+?)(?=\n\w+:|\n---|\Z)", re.S | re.M)
+
+# 固定的 inventory 根目录(仅限项目内)
+PROJECT_SKILLS_REL = Path(".codebuddy/skills")
+PROJECT_RULES_REL = Path(".codebuddy/rules")
+
+# 支持识别的 skill 子模块根目录
+SUBMODULE_DIRS = {"references", "scripts", "templates", "examples", "checklists", "roles"}
+
+# 允许严格提取的路径类字段键名(不扫描自由文本)
+PATH_VALUE_KEYS = {
+ "file_path", "filePath", "path", "target_file", "target_directory",
+ "cwd", "rule", "rule_path", "skill_path",
+}
+PATH_LIST_KEYS = {"paths", "files", "rules", "skills"}
+
+# 扫描时要跳过的目录
+SKIP_DIR_PARTS = {"skills-by-node", "node_modules", ".git", "__pycache__", "dist"}
+
+# 可能触发 skill 的工具名
+USE_SKILL_TOOLS = {"use_skill", "UseSkill", "load_skill", "Skill", "skill"}
+
+
+def _is_skipped_path(p: Path) -> bool:
+ """判断路径是否命中扫描时应跳过的目录集合。"""
+ parts = set(p.parts)
+ return bool(parts & SKIP_DIR_PARTS)
+
+
+def _parse_frontmatter(path: Path) -> dict[str, Any]:
+ """解析 `SKILL.md` 或 `RULE.mdc` 中的 frontmatter。"""
+ try:
+ text = path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ def _grab(regex, key, post=None):
+ mm = regex.search(block)
+ if mm:
+ v = mm.group(1).strip().strip('"\'').strip()
+ info[key] = post(v) if post else v
+
+ _grab(NAME_FIELD_RE, "name")
+ _grab(VERSION_FIELD_RE, "version")
+ _grab(AUTHOR_FIELD_RE, "author")
+ _grab(TAGS_FIELD_RE, "tags",
+ lambda v: [t.strip().strip('"\'') for t in v.split(",") if t.strip()])
+ _grab(DESC_FIELD_RE, "description", lambda v: v.strip().replace("\n", " ")[:200])
+ return info
+
+
+def _parse_list_field(block: str, regex: re.Pattern[str]) -> list[str]:
+ """从 frontmatter 文本块中解析一个逗号分隔的列表字段。"""
+ mm = regex.search(block)
+ if not mm:
+ return []
+ raw = mm.group(1).strip().strip('"\'')
+ if raw.startswith("["):
+ raw = raw.strip("[]")
+ return [g.strip().strip('"\'').lower() for g in raw.split(",") if g.strip()]
+
+
+def _parse_rule_frontmatter(rule_path: Path) -> dict[str, Any]:
+ """解析 `RULE.mdc` 中和规则生效相关的 frontmatter 字段。"""
+ try:
+ text = rule_path.read_text("utf-8", errors="ignore")
+ except Exception:
+ return {}
+ m = FRONTMATTER_RE.match(text)
+ if not m:
+ return {}
+ block = m.group(1)
+ info: dict = {}
+
+ mm = ALWAYS_APPLY_RE.search(block)
+ if mm:
+ info["alwaysApply"] = mm.group(1).lower() == "true"
+ mm = ENABLED_RE.search(block)
+ if mm:
+ info["enabled"] = mm.group(1).lower() == "true"
+ globs = _parse_list_field(block, GLOBS_RE)
+ if globs:
+ info["globs"] = globs
+
+ apply_agents = _parse_list_field(block, APPLY_AGENTS_RE)
+ if apply_agents:
+ info["applyAgents"] = apply_agents
+
+ exclude_agents = _parse_list_field(block, EXCLUDE_AGENTS_RE)
+ if exclude_agents:
+ info["excludeAgents"] = exclude_agents
+
+ mm = DESC_FIELD_RE.search(block)
+ if mm:
+ info["description"] = mm.group(1).strip().strip('"\'').replace("\n", " ")[:200]
+ return info
+
+
+def _classify_source(path: Path, cwd: Path | None) -> str:
+ """识别来源类型;当前只支持项目内 `.codebuddy` 路径。"""
+ if not cwd:
+ return "unknown"
+ try:
+ path_str = str(path.resolve())
+ cwd_str = str(cwd.resolve())
+ except Exception:
+ return "unknown"
+ if path_str.startswith(cwd_str + "/.codebuddy/"):
+ return "project"
+ return "unknown"
+
+
+def _collect_submodules(skill_dir: Path) -> dict[str, list]:
+ """收集一个 skill 内部的子模块目录,如 references/scripts/templates。"""
+ sub: dict = {}
+ if not skill_dir.is_dir():
+ return sub
+ for kind in ("references", "scripts", "templates", "examples", "checklists", "roles"):
+ d = skill_dir / kind
+ if d.is_dir():
+ files = [str(f.relative_to(skill_dir))
+ for f in d.rglob("*") if f.is_file()]
+ if files:
+ sub[kind] = sorted(files)[:30]
+ return sub
+
+
+def scan_skills_and_rules(cwd: str) -> tuple[dict[str, Any], dict[str, Any]]:
+ """扫描项目固定根目录:`.codebuddy/skills` 与 `.codebuddy/rules`。"""
+ skills: dict = {}
+ rules: dict = {}
+ cwd_path = Path(cwd) if cwd else None
+ if not cwd_path or not cwd_path.exists():
+ return skills, rules
+
+ skills_root = (cwd_path / PROJECT_SKILLS_REL).resolve()
+ rules_root = (cwd_path / PROJECT_RULES_REL).resolve()
+
+ if skills_root.is_dir() and not _is_skipped_path(skills_root):
+ for p in skills_root.rglob("SKILL.md"):
+ if _is_skipped_path(p):
+ continue
+ skill_dir = p.parent
+ name = skill_dir.name
+ if not name or name in skills:
+ continue
+ meta = _parse_frontmatter(p)
+ skills[name] = {
+ "source": _classify_source(skill_dir, cwd_path),
+ "path": str(skill_dir),
+ "has_skill_md": True,
+ "version": meta.get("version"),
+ "author": meta.get("author"),
+ "description": meta.get("description"),
+ "submodules": _collect_submodules(skill_dir),
+ }
+
+ if rules_root.is_dir() and not _is_skipped_path(rules_root):
+ for p in rules_root.rglob("*.mdc"):
+ if _is_skipped_path(p):
+ continue
+ name = p.parent.name if p.name == "RULE.mdc" else p.stem
+ if not name or name in rules:
+ continue
+ meta = _parse_rule_frontmatter(p)
+ rules[name] = {
+ "source": _classify_source(p.parent, cwd_path),
+ "path": str(p),
+ "alwaysApply": meta.get("alwaysApply", False),
+ "enabled": meta.get("enabled", True),
+ "globs": meta.get("globs") or [],
+ "applyAgents": meta.get("applyAgents") or [],
+ "excludeAgents": meta.get("excludeAgents") or [],
+ "description": meta.get("description"),
+ }
+
+ return skills, rules
+
+
+def lookup_skill_meta(skills_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 skill 元数据。"""
+ meta = (skills_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def lookup_rule_meta(rules_meta: dict[str, Any], name: str) -> dict[str, Any] | None:
+ """从缓存的 inventory 字典里按名称查找 rule 元数据。"""
+ meta = (rules_meta or {}).get(name)
+ return meta if isinstance(meta, dict) else None
+
+
+def _collect_path_strings(obj: Any) -> list[str]:
+ """只收集结构化路径字段,绝不解析自由文本。"""
+ out: list[str] = []
+
+ def _walk(x: Any) -> None:
+ if isinstance(x, dict):
+ for k, v in x.items():
+ if k in PATH_VALUE_KEYS and isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif k in PATH_LIST_KEYS:
+ if isinstance(v, str) and v.strip():
+ out.append(v.strip())
+ elif isinstance(v, list):
+ out.extend([
+ s.strip() for s in v
+ if isinstance(s, str) and s.strip()
+ ])
+ elif isinstance(v, (dict, list)):
+ _walk(v)
+ elif isinstance(x, list):
+ for it in x:
+ if isinstance(it, (dict, list)):
+ _walk(it)
+
+ _walk(obj)
+ return list(dict.fromkeys(out))
+
+
+def _path_parts(path_str: str) -> list[str]:
+ """把路径拆成标准化片段列表,便于后续命中判断。"""
+ p = path_str.replace("\\", "/").strip()
+ return [part for part in p.split("/") if part]
+
+
+def _extract_skill_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 skill 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ name = parts[i + 2]
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _extract_rule_from_path(path_str: str) -> str | None:
+ """从路径中抽取被引用的 rule 名。"""
+ parts = _path_parts(path_str)
+ for i in range(len(parts) - 2):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "rules":
+ name = parts[i + 2]
+ if name.lower().endswith(".mdc"):
+ name = Path(name).stem
+ if name and re.fullmatch(r"[a-zA-Z0-9_\-]+", name):
+ return name
+ return None
+
+
+def _is_rule_allowed_for_agent(name: str, meta: dict[str, Any], active_agent: str | None) -> bool:
+ """按角色判断 rule 是否可用;`global` 永远保持可选。"""
+ if str(name).strip().lower() == "global":
+ return True
+
+ agent = str(active_agent or "").strip().lower()
+ if not agent:
+ return True
+
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+
+ if apply_agents and agent not in apply_agents:
+ return False
+ if exclude_agents and agent in exclude_agents:
+ return False
+ return True
+
+
+def _glob_matches_any_path(globs: list[str], paths_to_check: list[str]) -> bool:
+ """判断配置的 glob 是否命中任一收集到的路径。"""
+ if not globs or not paths_to_check:
+ return False
+ import fnmatch
+
+ for p in paths_to_check:
+ basename = os.path.basename(p)
+ if any(fnmatch.fnmatch(p, g) or fnmatch.fnmatch(basename, g) for g in globs):
+ return True
+ return False
+
+
+def evaluate_rules_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """评估当前工具调用下所有已知 rule,并保留未命中的原因。"""
+ if not rules_meta:
+ return {}
+
+ tool_input = data.get("tool_input") or {}
+ paths_to_check = _collect_path_strings(tool_input)
+ _, path_rules = extract_paths_from_tool_call(data)
+ path_rule_set = set(path_rules)
+
+ evaluations: dict[str, dict[str, Any]] = {}
+ for name, meta in (rules_meta or {}).items():
+ if not isinstance(meta, dict):
+ continue
+
+ globs = [str(g).strip() for g in (meta.get("globs") or []) if str(g).strip()]
+ apply_agents = [str(a).strip().lower() for a in (meta.get("applyAgents") or []) if str(a).strip()]
+ exclude_agents = [str(a).strip().lower() for a in (meta.get("excludeAgents") or []) if str(a).strip()]
+ evaluation: dict[str, Any] = {"matched": False}
+
+ if name in path_rule_set:
+ evaluation["matched"] = True
+ evaluation["via"] = "path_inferred"
+ elif meta.get("enabled") is False:
+ evaluation["reason"] = "disabled"
+ elif not _is_rule_allowed_for_agent(name, meta, active_agent):
+ evaluation["reason"] = "agent_filtered"
+ if apply_agents:
+ evaluation["applyAgents"] = apply_agents
+ if exclude_agents:
+ evaluation["excludeAgents"] = exclude_agents
+ elif meta.get("alwaysApply"):
+ evaluation["matched"] = True
+ evaluation["via"] = "always_apply"
+ elif globs:
+ evaluation["globs"] = globs
+ evaluation["paths_checked"] = len(paths_to_check)
+ if not paths_to_check:
+ evaluation["reason"] = "no_paths"
+ elif _glob_matches_any_path(globs, paths_to_check):
+ evaluation["matched"] = True
+ evaluation["via"] = "glob"
+ else:
+ evaluation["reason"] = "glob_not_matched"
+ evaluation["paths_sample"] = paths_to_check[:3]
+ else:
+ evaluation["reason"] = "no_globs"
+
+ evaluations[name] = evaluation
+
+ return evaluations
+
+
+def unmatched_rule_diagnostics_for_call(
+ data: dict,
+ rules_meta: dict,
+ active_agent: str | None = None,
+) -> dict[str, dict[str, Any]]:
+ """返回当前工具调用下未命中的 rule 的精简诊断信息。"""
+ diagnostics: dict[str, dict[str, Any]] = {}
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched"):
+ continue
+ item: dict[str, Any] = {"reason": evaluation.get("reason") or "unknown"}
+ for key in ("globs", "paths_checked", "paths_sample", "applyAgents", "excludeAgents"):
+ value = evaluation.get(key)
+ if value is not None and value != []:
+ item[key] = value
+ diagnostics[name] = item
+ return diagnostics
+
+
+def filtered_rules_for_agent(rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """列出因 agent 过滤而被排除的 rule(仅看已启用项)。"""
+ filtered: list[str] = []
+ for name, evaluation in evaluate_rules_for_call({}, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("reason") == "agent_filtered":
+ filtered.append(name)
+ return sorted(set(filtered))
+
+
+def active_rules_for_call(data: dict, rules_meta: dict, active_agent: str | None = None) -> list[str]:
+ """判断给定工具调用下哪些 rule 处于生效状态。"""
+ active: list[str] = []
+ for name, evaluation in evaluate_rules_for_call(data, rules_meta, active_agent=active_agent).items():
+ if evaluation.get("matched") and evaluation.get("via") != "path_inferred":
+ active.append(name)
+ return sorted(set(active))
+
+
+def extract_skill_from_tool_call(data: dict) -> str | None:
+ """从类似 use_skill 的工具调用里提取 skill 名称。"""
+ tool = data.get("tool_name", "")
+ if tool not in USE_SKILL_TOOLS:
+ return None
+ tool_input = data.get("tool_input") or {}
+ if isinstance(tool_input, dict):
+ return tool_input.get("command") or tool_input.get("name") or tool_input.get("skill")
+ return None
+
+
+def is_brainstorming_call(data: dict) -> bool:
+ """判断当前工具调用是否正在激活或使用 brainstorming skill。"""
+ direct = extract_skill_from_tool_call(data)
+ if isinstance(direct, str) and direct.strip().lower() == "brainstorming":
+ return True
+
+ path_skills, _ = extract_paths_from_tool_call(data)
+ return any(str(s).strip().lower() == "brainstorming" for s in path_skills)
+
+
+def extract_paths_from_tool_call(data: dict) -> tuple[list[str], list[str]]:
+ """只根据 `.codebuddy` 根目录下的结构化路径推断 skill/rule。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return [], []
+
+ skills: list[str] = []
+ rules: list[str] = []
+ for p in _collect_path_strings(tool_input):
+ s = _extract_skill_from_path(p)
+ if s:
+ skills.append(s)
+ r = _extract_rule_from_path(p)
+ if r:
+ rules.append(r)
+
+ return list(dict.fromkeys(skills)), list(dict.fromkeys(rules))
+
+
+def extract_submodule_hits(data: dict) -> list[dict[str, str]]:
+ """仅从结构化 skill 路径中提取子模块命中结果,不扫描自由文本。"""
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+
+ seen: set[tuple[str, str]] = set()
+ hits: list[dict[str, str]] = []
+ path_values = _collect_path_strings(tool_input)
+
+ for p in path_values:
+ parts = _path_parts(p)
+ for i in range(len(parts) - 3):
+ if parts[i] == ".codebuddy" and parts[i + 1] == "skills":
+ skill_name = parts[i + 2]
+ sub_root = parts[i + 3]
+ if not re.fullmatch(r"[a-zA-Z0-9_\-]+", skill_name):
+ continue
+ if sub_root not in SUBMODULE_DIRS:
+ continue
+ sub_path = "/".join(parts[i + 3:]).rstrip("/")
+ key = (skill_name, sub_path)
+ if key in seen:
+ continue
+ seen.add(key)
+ hits.append({"skill": skill_name, "submodule": sub_path})
+ break
+
+ return hits
+
+
+def extract_bash_skill_scripts(data: dict) -> list[str]:
+ """从命令文本中的显式 `.codebuddy/skills` 路径识别 skill 脚本。"""
+ if data.get("tool_name") not in ("Bash", "bash", "execute_command"):
+ return []
+ tool_input = data.get("tool_input") or {}
+ if not isinstance(tool_input, dict):
+ return []
+ cmd = tool_input.get("command") or ""
+ if not isinstance(cmd, str) or not cmd.strip():
+ return []
+
+ skills: list[str] = []
+ for token in cmd.split():
+ t = token.strip("\"'`;,()[]{}")
+ s = _extract_skill_from_path(t)
+ if s:
+ skills.append(s)
+ return list(dict.fromkeys(skills))
diff --git a/.cursor/skills/agent-observability/scripts/core/state.py b/.cursor/skills/agent-observability/scripts/core/state.py
new file mode 100644
index 00000000..5e7d33e9
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/core/state.py
@@ -0,0 +1,1222 @@
+"""持久化状态层。
+
+这一层负责跨 hook 调用保存与协调状态:
+- session 级 skill/rule 使用统计
+- 当前 agent、派发关系与历史
+- transcript offset、去重 claim、pending emits
+- AgentLens sidecar 状态
+"""
+from __future__ import annotations
+
+import json
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+try:
+ import fcntl
+except Exception: # pragma: no cover - non-posix fallback
+ fcntl = None # type: ignore
+
+
+def get_state_path(base_dir: Path) -> Path:
+ """返回主状态文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".state.json"
+
+
+def get_pending_path(base_dir: Path) -> Path:
+ """返回 Pre/PostToolUse 配对使用的 pending 文件路径。"""
+ log_dir = base_dir / "logs"
+ log_dir.mkdir(parents=True, exist_ok=True)
+ return log_dir / ".pending_calls.json"
+
+
+def load_state(state_path: Path) -> dict[str, Any]:
+ """从磁盘加载状态;任何异常都回退为空字典。"""
+ if state_path.exists():
+ try:
+ return json.loads(state_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_state(state_path: Path, state: dict[str, Any]) -> None:
+ """把状态写回磁盘。"""
+ state_path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+
+
+def get_state_lock_path(state_path: Path) -> Path:
+ """返回状态写锁文件路径。"""
+ return state_path.parent / ".state.lock"
+
+
+def get_transcript_seen_path(state_path: Path) -> Path:
+ """返回 transcript usage 事件 claim 的 sidecar 台账文件。
+
+ 这部分单独存放,不混进 `.state.json`,是为了避免并发 hook 写状态时,
+ 旧 state 覆盖掉已经 claim 过的 transcript offset。
+ """
+ return state_path.parent / ".transcript_events_seen.json"
+
+
+@contextmanager
+def state_lock(state_path: Path):
+ """为状态修改提供跨进程建议锁(独占)。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_EX)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def state_read_lock(state_path: Path):
+ """为状态一致性读取提供跨进程共享读锁。"""
+ lock_path = get_state_lock_path(state_path)
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ with lock_path.open("a+", encoding="utf-8") as fp:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_SH)
+ try:
+ yield
+ finally:
+ if fcntl is not None:
+ fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+
+def update_state_locked(state_path: Path, updater):
+ """在跨进程锁保护下完成 load -> mutate -> save。"""
+ with state_lock(state_path):
+ state = load_state(state_path)
+ result = updater(state)
+ save_state(state_path, state)
+ return result
+
+
+def load_pending(pending_path: Path) -> dict[str, Any]:
+ """加载待配对的 pre/post 数据。"""
+ if pending_path.exists():
+ try:
+ return json.loads(pending_path.read_text("utf-8"))
+ except Exception:
+ return {}
+ return {}
+
+
+def save_pending(pending_path: Path, data: dict[str, Any]) -> None:
+ """保存待配对的 pre/post 数据。"""
+ pending_path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def ensure_session(state: dict, sid: str) -> dict:
+ """确保某个 session 的状态结构存在,并返回该 session 字典。
+
+ Session 结构:
+ {
+ "skills": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "rules": {name: {count, first_ts, last_ts, tools, via, source, by_agent}},
+ "started_at": float,
+ "current_agent": str,
+ "agent_history": [{ts, agent, evidence}],
+ "dispatched": {agent_name: count},
+ "_skills_meta": {...}, # SessionStart 时缓存的 inventory
+ "_rules_meta": {...},
+ }
+ """
+ if sid not in state:
+ state[sid] = {
+ "skills": {},
+ "rules": {},
+ "started_at": time.time(),
+ "current_agent": "main",
+ "agent_history": [],
+ "dispatched": {},
+ }
+ sess = state[sid]
+ # 保证字段类型正确,兼容旧数据
+ if not isinstance(sess.get("skills"), dict):
+ sess["skills"] = {}
+ if not isinstance(sess.get("rules"), dict):
+ sess["rules"] = {}
+ sess.setdefault("current_agent", "main")
+ sess.setdefault("agent_history", [])
+ sess.setdefault("dispatched", {})
+ if not isinstance(sess.get("_pending_tool_emits"), list):
+ sess["_pending_tool_emits"] = []
+ return sess
+
+
+def get_devflow_state(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 缓存的 devflow 上下文与最近一次 stage 快照(见 devflow.py)。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ dv = sess.get("_devflow")
+ return dv if isinstance(dv, dict) else {}
+
+
+def set_devflow_state(state: dict[str, Any], sid: str, updates: dict[str, Any]) -> None:
+ """合并写入某个 session 的 devflow 缓存字段(`checked` / `context` / `last_snapshot`)。"""
+ sess = ensure_session(state, sid)
+ dv = sess.get("_devflow")
+ if not isinstance(dv, dict):
+ dv = {}
+ sess["_devflow"] = dv
+ dv.update(updates)
+
+
+def get_agentlens_session(state: dict[str, Any], sid: str) -> dict[str, Any]:
+ """返回某个 session 的 AgentLens sidecar payload。"""
+ sess = ensure_session(state, sid)
+ payload = sess.setdefault("_agentlens", {})
+ if not isinstance(payload, dict):
+ payload = {}
+ sess["_agentlens"] = payload
+ return payload
+
+
+AGENTLENS_SCHEMA_VERSION = 2
+_TURN_HISTORY_MAX = 5
+
+
+def _migrate_agentlens_v1_to_v2(payload: dict[str, Any], sess: dict[str, Any] | None) -> dict[str, Any]:
+ """把 v1 版 ``_agentlens`` payload 转成以 turn 为中心的 v2 布局。
+
+ v1 布局(pre-turn):
+ {"carrier": {...}, "enabled": bool, "session_id": "...", "app_name": "..."}
+ v2 布局(turn-centric):
+ {
+ "version": 2,
+ "session_id": "...",
+ "enabled": bool,
+ "app_name": "...",
+ "current_turn": {"turn_id": "legacy", "started_at": ..., "carrier": {...}, "subagent_spans": {}, "agent_spans": {}, "step_spans": {}},
+ "turn_history": [],
+ }
+
+ 幂等约束:如果已经带有 ``version``,就原样返回。
+ """
+ if not isinstance(payload, dict):
+ return {"version": AGENTLENS_SCHEMA_VERSION, "enabled": False, "current_turn": None, "turn_history": []}
+ if payload.get("version") == AGENTLENS_SCHEMA_VERSION:
+ payload.setdefault("current_turn", None)
+ payload.setdefault("turn_history", [])
+ current = payload.get("current_turn")
+ if isinstance(current, dict):
+ current.setdefault("subagent_spans", {})
+ current.setdefault("agent_spans", {})
+ current.setdefault("step_spans", {})
+ return payload
+
+ migrated: dict[str, Any] = {
+ "version": AGENTLENS_SCHEMA_VERSION,
+ "session_id": payload.get("session_id"),
+ "enabled": bool(payload.get("enabled", False)),
+ }
+ if "app_name" in payload:
+ migrated["app_name"] = payload.get("app_name")
+ if "last_error" in payload:
+ migrated["last_error"] = payload.get("last_error")
+
+ legacy_carrier = payload.get("carrier")
+ if isinstance(legacy_carrier, dict) and legacy_carrier:
+ started_at = None
+ if isinstance(sess, dict):
+ try:
+ started_at = float(sess.get("started_at") or 0) or None
+ except Exception:
+ started_at = None
+ migrated["current_turn"] = {
+ "turn_id": "legacy",
+ "started_at": started_at or time.time(),
+ "carrier": dict(legacy_carrier),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ else:
+ migrated["current_turn"] = None
+ migrated["turn_history"] = []
+ return migrated
+
+
+def load_agentlens_session(state_path: Path, sid: str) -> dict[str, Any]:
+ """加载某个 session 已持久化的 AgentLens sidecar payload。
+
+ 这里使用共享读锁,避免并发 ``update_agentlens_session`` 写入时读到撕裂数据。
+ 返回值会透明地把 v1 payload 迁移成 v2 副本;真正落盘迁移会在下一次写入时完成。
+ """
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+ payload = sess.get("_agentlens")
+ if not isinstance(payload, dict):
+ return {}
+ # 先给调用方返回迁移后的副本,真正持久化迁移留到后续写入时完成。
+ return _migrate_agentlens_v1_to_v2(dict(payload), sess)
+
+
+def update_agentlens_session(
+ state_path: Path,
+ sid: str,
+ updates: dict[str, Any],
+ *,
+ clear_keys: list[str] | None = None,
+) -> dict[str, Any]:
+ """原子地持久化某个 session 的 AgentLens sidecar 字段。
+
+ 在合并 updates 之前会先做 v1→v2 迁移,这样磁盘上的 payload 会随着写入自然收敛到 v2。
+ """
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ # 如果仍是 v1,就原地迁移。
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+ for key in clear_keys or []:
+ payload.pop(key, None)
+ for key, value in updates.items():
+ if value is None:
+ payload.pop(key, None)
+ else:
+ payload[key] = value
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(payload)
+
+ return update_state_locked(state_path, _update)
+
+
+def begin_turn(
+ state_path: Path,
+ sid: str,
+ turn_id: str,
+ carrier: dict[str, str],
+ *,
+ started_at: float | None = None,
+ max_history: int = _TURN_HISTORY_MAX,
+) -> dict[str, Any]:
+ """在独占锁下打开一个新的 turn。
+
+ 语义:
+ - 如果存在 ``current_turn``,先把它归档进有上限的 ``turn_history``。
+ - 为新 turn 重置 ``subagent_spans`` / ``agent_spans`` / ``step_spans``。
+ - 对相同 ``turn_id`` 保持幂等:重复调用直接返回已有 ``current_turn``,
+ 不重新生成 trace_id。
+
+ 返回最终生成的 ``current_turn`` 字典。
+ """
+ ts = float(started_at if started_at is not None else time.time())
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ sess = ensure_session(state, sid)
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), sess)
+ payload.clear()
+ payload.update(migrated)
+
+ current = payload.get("current_turn")
+ # 幂等:如果同一个 turn_id 还在处理中,就原样返回。
+ if isinstance(current, dict) and str(current.get("turn_id") or "") == str(turn_id):
+ return dict(current)
+
+ # 归档上一个 turn。
+ if isinstance(current, dict) and current.get("turn_id"):
+ history = payload.setdefault("turn_history", [])
+ if not isinstance(history, list):
+ history = []
+ payload["turn_history"] = history
+ archived = {
+ "turn_id": current.get("turn_id"),
+ "started_at": current.get("started_at"),
+ "ended_at": ts,
+ "carrier_traceparent": (current.get("carrier") or {}).get("traceparent"),
+ }
+ history.append(archived)
+ if len(history) > max_history:
+ del history[: len(history) - max_history]
+
+ new_turn = {
+ "turn_id": str(turn_id),
+ "started_at": ts,
+ "carrier": dict(carrier or {}),
+ "subagent_spans": {},
+ "agent_spans": {},
+ "step_spans": {},
+ }
+ payload["current_turn"] = new_turn
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_turn)
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span(
+ state_path: Path,
+ sid: str,
+ role: str,
+ carrier: dict[str, str],
+) -> dict[str, str]:
+ """在当前 turn 下登记 subagent 的 ``invoke_agent`` 子 span carrier。
+
+ 对 `(turn, role)` 维度保持幂等:如果活跃 turn 下已经记录了该角色的 carrier,
+ 就直接返回已有值,不再重复创建。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ # 没有活跃 turn,无法登记 subagent span。
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ subs[role] = {"carrier": dict(carrier or {}), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_subagent_span_atomic(
+ state_path: Path,
+ sid: str,
+ role: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建 subagent 的 ``invoke_agent`` carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_subagent_carrier`` 先产生了不可逆的 zhiyanllm ``invoke_agent`` span,
+ 随后另一个 hook 进程已经写入同一角色,导致本次创建变成孤儿。
+ """
+ now = time.time()
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ subs = current.setdefault("subagent_spans", {})
+ if not isinstance(subs, dict):
+ subs = {}
+ current["subagent_spans"] = subs
+ existing = subs.get(role)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ subs[role] = {"carrier": dict(new_carrier), "opened_at": now}
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_current_turn(state_path: Path, sid: str) -> dict[str, Any] | None:
+ """返回当前活跃的 turn 字典;如果没有打开 turn,就返回 None。"""
+ payload = load_agentlens_session(state_path, sid)
+ current = payload.get("current_turn")
+ return current if isinstance(current, dict) else None
+
+
+def get_subagent_span_carrier(state_path: Path, sid: str, role: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 subagent span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ subs = turn.get("subagent_spans")
+ if not isinstance(subs, dict):
+ return None
+ rec = subs.get(role)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def _empty_agent_aggregate() -> dict[str, Any]:
+ """创建一份空的 agent 聚合指标骨架。"""
+ return {
+ "tokens": {
+ "input": 0,
+ "output": 0,
+ "cache_read": 0,
+ "cache_creation": 0,
+ "total": 0,
+ },
+ "event_count": 0,
+ "cost_usd": 0.0,
+ "tool_duration_ms": 0,
+ "llm_call_count": 0,
+ "tool_call_count": 0,
+ "step_count": 0,
+ }
+
+
+def _normalize_agent(agent: str | None) -> str:
+ """把 agent 名归一化,空值统一落到 ``main``。"""
+ return str(agent or "main").strip() or "main"
+
+
+def _ensure_turn_agent_spans(current: dict[str, Any]) -> dict[str, Any]:
+ """确保当前 turn 下存在 `agent_spans` 容器。"""
+ agent_spans = current.setdefault("agent_spans", {})
+ if not isinstance(agent_spans, dict):
+ agent_spans = {}
+ current["agent_spans"] = agent_spans
+ return agent_spans
+
+
+def _ensure_agent_span_rec(current: dict[str, Any], agent: str) -> dict[str, Any]:
+ """确保指定 agent 在当前 turn 下有一条完整聚合记录。"""
+ agent_spans = _ensure_turn_agent_spans(current)
+ rec = agent_spans.get(agent)
+ if not isinstance(rec, dict):
+ rec = {}
+ agent_spans[agent] = rec
+ carrier = rec.get("carrier")
+ if not isinstance(carrier, dict):
+ rec["carrier"] = {}
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ rec["aggregate"] = _empty_agent_aggregate()
+ return rec
+
+
+def get_agent_span_carrier(state_path: Path, sid: str, agent: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 agent 分组 span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(agent))
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def upsert_agent_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ carrier_factory: Any,
+) -> dict[str, str]:
+ """原子地获取或创建 agent 分组 span carrier。"""
+ now = time.time()
+ normalized_agent = _normalize_agent(agent)
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ existing = rec.get("carrier")
+ if isinstance(existing, dict) and existing.get("traceparent"):
+ return dict(existing)
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ rec["carrier"] = dict(new_carrier)
+ rec.setdefault("opened_at", now)
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def bump_agent_aggregate(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ *,
+ usage_event: dict[str, Any] | None = None,
+ tool_event: dict[str, Any] | None = None,
+ step_created: bool = False,
+) -> dict[str, Any]:
+ """增加活跃 turn 下按 agent 聚合的统计指标。"""
+ normalized_agent = _normalize_agent(agent)
+
+ def _int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except Exception:
+ return 0
+
+ def _float(value: Any) -> float:
+ try:
+ return float(value or 0)
+ except Exception:
+ return 0.0
+
+ def _update(state: dict[str, Any]) -> dict[str, Any]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(
+ dict(payload),
+ state.get(sid) if isinstance(state.get(sid), dict) else None,
+ )
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ rec = _ensure_agent_span_rec(current, normalized_agent)
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ aggregate = _empty_agent_aggregate()
+ rec["aggregate"] = aggregate
+ tokens = aggregate.setdefault("tokens", {})
+ if not isinstance(tokens, dict):
+ tokens = {}
+ aggregate["tokens"] = tokens
+
+ if step_created:
+ aggregate["step_count"] = _int(aggregate.get("step_count")) + 1
+
+ if isinstance(tool_event, dict):
+ aggregate["tool_call_count"] = _int(aggregate.get("tool_call_count")) + 1
+ ms = tool_event.get("ms")
+ if ms is not None:
+ aggregate["tool_duration_ms"] = _int(aggregate.get("tool_duration_ms")) + _int(ms)
+
+ if isinstance(usage_event, dict):
+ raw_tokens = usage_event.get("tokens")
+ if isinstance(raw_tokens, dict):
+ # 聚合 agent 摘要里需要暴露的字段。
+ for key in ("input", "output", "cache_read", "cache_creation"):
+ tokens[key] = _int(tokens.get(key)) + _int(raw_tokens.get(key))
+ # total = input + output,其中 input 已经包含 cache_read。
+ tokens["total"] = _int(tokens.get("input")) + _int(tokens.get("output"))
+ aggregate["llm_call_count"] = _int(aggregate.get("llm_call_count")) + 1
+ aggregate["event_count"] = _int(aggregate.get("event_count")) + 1
+ aggregate["cost_usd"] = round(_float(aggregate.get("cost_usd")) + _float(usage_event.get("cost_usd")), 10)
+
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+ return update_state_locked(state_path, _update)
+
+
+def get_subagent_aggregate(state_path: Path, sid: str, role: str) -> dict[str, Any] | None:
+ """返回活跃 turn 下当前 agent 的聚合摘要。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ agent_spans = turn.get("agent_spans")
+ if not isinstance(agent_spans, dict):
+ return None
+ rec = agent_spans.get(_normalize_agent(role))
+ if not isinstance(rec, dict):
+ return None
+ aggregate = rec.get("aggregate")
+ if not isinstance(aggregate, dict):
+ return None
+ return json.loads(json.dumps(aggregate, ensure_ascii=False))
+
+
+def _step_span_key(agent: str, message_id: str) -> str:
+ """为 step span 生成按 agent 与 message_id 唯一定位的 key。"""
+ return f"{agent}|{message_id}"
+
+
+def upsert_step_span(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ carrier: dict[str, str],
+ *,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在当前 turn 下登记一个 step span carrier,并对 `(turn, agent, message_id)` 保持幂等。"""
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ steps[key] = {
+ "carrier": dict(carrier or {}),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(carrier or {})
+
+ return update_state_locked(state_path, _update)
+
+
+def upsert_step_span_atomic(
+ state_path: Path,
+ sid: str,
+ agent: str,
+ message_id: str,
+ *,
+ carrier_factory: Any,
+ transcript_path: str | None = None,
+) -> dict[str, str]:
+ """在写锁内原子地获取或创建一个 step span carrier。
+
+ `carrier_factory` 是一个无参可调用对象,用来生成 carrier 字典。
+ 只有在 span 还不存在时才会被调用,从而避免这样的 TOCTOU 竞争:
+ ``_generate_step_carrier`` 已经先产生了不可逆的 zhiyanllm span,
+ 但随后另一个 hook 进程已经写入同一 step,导致本次创建失去归属。
+ """
+ now = time.time()
+ normalized_agent = str(agent or "main").strip() or "main"
+ normalized_message_id = str(message_id or "").strip()
+ if not normalized_message_id:
+ return {}
+
+ def _update(state: dict[str, Any]) -> dict[str, str]:
+ payload = get_agentlens_session(state, sid)
+ if payload.get("version") != AGENTLENS_SCHEMA_VERSION:
+ migrated = _migrate_agentlens_v1_to_v2(dict(payload), state.get(sid) if isinstance(state.get(sid), dict) else None)
+ payload.clear()
+ payload.update(migrated)
+ current = payload.get("current_turn")
+ if not isinstance(current, dict):
+ return {}
+ steps = current.setdefault("step_spans", {})
+ if not isinstance(steps, dict):
+ steps = {}
+ current["step_spans"] = steps
+ key = _step_span_key(normalized_agent, normalized_message_id)
+ existing = steps.get(key)
+ if isinstance(existing, dict) and isinstance(existing.get("carrier"), dict) and existing["carrier"]:
+ return dict(existing["carrier"])
+ new_carrier = carrier_factory()
+ if not isinstance(new_carrier, dict) or not new_carrier.get("traceparent"):
+ return {}
+ steps[key] = {
+ "carrier": dict(new_carrier),
+ "opened_at": now,
+ "agent": normalized_agent,
+ "message_id": normalized_message_id,
+ "transcript_path": transcript_path or "",
+ }
+ payload["version"] = AGENTLENS_SCHEMA_VERSION
+ return dict(new_carrier)
+
+ return update_state_locked(state_path, _update)
+
+
+def get_step_span_carrier(state_path: Path, sid: str, agent: str, message_id: str) -> dict[str, str] | None:
+ """返回活跃 turn 下已持久化的 step span carrier;如果没有则返回 None。"""
+ turn = get_current_turn(state_path, sid)
+ if not isinstance(turn, dict):
+ return None
+ steps = turn.get("step_spans")
+ if not isinstance(steps, dict):
+ return None
+ key = _step_span_key(str(agent or "main").strip() or "main", str(message_id or "").strip())
+ rec = steps.get(key)
+ if not isinstance(rec, dict):
+ return None
+ carrier = rec.get("carrier")
+ return dict(carrier) if isinstance(carrier, dict) and carrier else None
+
+
+def get_latest_session_id(state: dict[str, Any]) -> str | None:
+ """返回 state 中最近启动的 session id。"""
+ latest_sid: str | None = None
+ latest_started_at = -1.0
+ for sid, sess in state.items():
+ if sid.startswith("_") or not isinstance(sess, dict):
+ continue
+ started_at = float(sess.get("started_at", 0) or 0)
+ if started_at >= latest_started_at:
+ latest_started_at = started_at
+ latest_sid = sid
+ return latest_sid
+
+
+def get_pending_tool_emits(state_path: Path, sid: str) -> list[dict[str, Any]]:
+ """返回等待与 transcript/message_id 关联的缓冲 tool 事件。"""
+ with state_read_lock(state_path):
+ state = load_state(state_path)
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return []
+ pending = sess.get("_pending_tool_emits")
+ if not isinstance(pending, list):
+ return []
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+
+def append_pending_tool_emit(state_path: Path, sid: str, tool_event: dict[str, Any]) -> list[dict[str, Any]]:
+ """缓存一条 tool 事件,延后再做 message_id 关联。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ pending = sess.setdefault("_pending_tool_emits", [])
+ if not isinstance(pending, list):
+ pending = []
+ sess["_pending_tool_emits"] = pending
+ pending.append(dict(tool_event))
+ return [dict(item) for item in pending if isinstance(item, dict)]
+
+ return update_state_locked(state_path, _update)
+
+
+def replace_pending_tool_emits(state_path: Path, sid: str, tool_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """覆盖某个 session 的缓冲 tool 事件队列。"""
+
+ def _update(state: dict[str, Any]) -> list[dict[str, Any]]:
+ sess = ensure_session(state, sid)
+ normalized = [dict(item) for item in tool_events if isinstance(item, dict)]
+ sess["_pending_tool_emits"] = normalized
+ return [dict(item) for item in normalized]
+
+ return update_state_locked(state_path, _update)
+
+def bump_skill(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ submodule: str | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 skill 使用计数,并按需记录子模块与 agent 维度。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["skills"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "version": None,
+ "submodule_hits": {},
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta:
+ if meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if meta.get("version") and not rec.get("version"):
+ rec["version"] = meta["version"]
+ # 子模块命中统计
+ if submodule:
+ sub_dict = rec.setdefault("submodule_hits", {})
+ if not isinstance(sub_dict, dict):
+ sub_dict = {}
+ rec["submodule_hits"] = sub_dict
+ sh = sub_dict.setdefault(submodule, {
+ "count": 0, "first_ts": now, "last_ts": now, "tools": [],
+ })
+ sh["count"] += 1
+ sh["last_ts"] = now
+ if tool and tool not in sh["tools"]:
+ sh["tools"].append(tool)
+ # 按 agent 维度统计
+ if agent:
+ ag_dict = rec.setdefault("by_agent", {})
+ if not isinstance(ag_dict, dict):
+ ag_dict = {}
+ rec["by_agent"] = ag_dict
+ ar = ag_dict.setdefault(agent, {
+ "count": 0, "first_ts": now, "last_ts": now,
+ "tools": [], "submodules": [],
+ })
+ ar["count"] += 1
+ ar["last_ts"] = now
+ if tool and tool not in ar["tools"]:
+ ar["tools"].append(tool)
+ if submodule and submodule not in ar["submodules"]:
+ ar["submodules"].append(submodule)
+
+
+def bump_rule(
+ sess: dict,
+ name: str,
+ *,
+ via: str,
+ tool: str | None,
+ meta: dict | None = None,
+ agent: str | None = None,
+) -> None:
+ """增加 rule 使用计数。"""
+ if not name:
+ return
+ now = time.time()
+ rec = sess["rules"].setdefault(name, {
+ "count": 0,
+ "first_ts": now,
+ "last_ts": now,
+ "tools": [],
+ "via": [],
+ "source": None,
+ "by_agent": {},
+ })
+ rec["count"] += 1
+ rec["last_ts"] = now
+ if tool and tool not in rec["tools"]:
+ rec["tools"].append(tool)
+ if via not in rec.get("via", []):
+ rec.setdefault("via", []).append(via)
+ if meta and meta.get("source") and not rec.get("source"):
+ rec["source"] = meta["source"]
+ if agent:
+ ag = rec.setdefault("by_agent", {})
+ if not isinstance(ag, dict):
+ ag = {}
+ rec["by_agent"] = ag
+ ar = ag.setdefault(agent, {"count": 0, "last_ts": now})
+ ar["count"] += 1
+ ar["last_ts"] = now
+
+
+def prune_sessions(state: dict, max_sessions: int = 5) -> None:
+ """在 state 中只保留最近的 N 个 session。"""
+ # 先过滤掉非 session 键(以下划线开头)
+ session_keys = [k for k in state if not k.startswith("_")]
+ if len(session_keys) > max_sessions:
+ to_remove = sorted(
+ session_keys,
+ key=lambda s: state[s].get("started_at", 0) if isinstance(state[s], dict) else 0,
+ )[:len(session_keys) - max_sessions]
+ for k in to_remove:
+ del state[k]
+
+
+def _transcript_scope_key(transcript_path: str | None = None) -> str:
+ """把 transcript 路径归一化成内部 scope key。"""
+ path = str(transcript_path or "").strip()
+ return path or "__session__"
+
+
+def _ensure_transcript_scopes(sess: dict) -> dict[str, dict[str, Any]]:
+ """确保 session 下存在 transcript scope 容器,并兼容旧字段迁移。"""
+ scopes = sess.setdefault("_transcripts", {})
+ if not isinstance(scopes, dict):
+ scopes = {}
+ sess["_transcripts"] = scopes
+
+ legacy_scope = scopes.get("__session__")
+ if not isinstance(legacy_scope, dict):
+ legacy_scope = {}
+ scopes["__session__"] = legacy_scope
+
+ if "offset" not in legacy_scope and "_transcript_offset" in sess:
+ legacy_scope["offset"] = int(sess.get("_transcript_offset", 0) or 0)
+
+ legacy_usage = sess.get("_last_cumulative_usage")
+ if "last_cumulative_usage" not in legacy_scope and isinstance(legacy_usage, dict) and legacy_usage:
+ legacy_scope["last_cumulative_usage"] = legacy_usage
+
+ legacy_dedup = sess.get("_last_usage_event")
+ if "last_usage_event" not in legacy_scope and isinstance(legacy_dedup, dict) and legacy_dedup:
+ legacy_scope["last_usage_event"] = legacy_dedup
+
+ return scopes
+
+
+def _get_transcript_scope(
+ sess: dict,
+ transcript_path: str | None = None,
+ *,
+ create: bool = False,
+) -> dict[str, Any] | None:
+ """获取指定 transcript 的 scope;必要时按需创建。"""
+ scopes = _ensure_transcript_scopes(sess)
+ key = _transcript_scope_key(transcript_path)
+ scope = scopes.get(key)
+ if isinstance(scope, dict):
+ return scope
+ if create:
+ scope = {}
+ scopes[key] = scope
+ return scope
+ return None
+
+
+def get_transcript_offset(state: dict, sid: str, transcript_path: str | None = None) -> int:
+ """获取某个 session/transcript 最近一次上报的 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ return int(scope.get("offset", 0) or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ return int(sess.get("_transcript_offset", 0) or 0)
+ return 0
+
+
+def set_transcript_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """在成功上报后持久化 transcript 文件 offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["offset"] = int(offset or 0)
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = int(offset or 0)
+
+
+def get_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, int]:
+ """获取某个 transcript 最近一次上报的累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return {}
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ v = sess.get("_last_cumulative_usage")
+ if isinstance(v, dict):
+ return v
+ return {}
+
+
+def get_last_llm_offset(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> int:
+ """获取最近一次处理到的 LLM source_offset,用于增量构建 I/O。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return 0
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ v = scope.get("last_llm_offset")
+ if isinstance(v, (int, float)):
+ return int(v)
+ return 0
+
+
+def set_last_llm_offset(
+ state: dict,
+ sid: str,
+ offset: int,
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近处理到的 LLM source_offset。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_llm_offset"] = int(offset or 0)
+
+
+def set_last_cumulative_usage(
+ state: dict,
+ sid: str,
+ usage: dict[str, int],
+ transcript_path: str | None = None,
+) -> None:
+ """在处理完一个 turn 后持久化累计 token usage。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_cumulative_usage"] = usage
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = usage
+
+
+def get_last_usage_event(
+ state: dict,
+ sid: str,
+ transcript_path: str | None = None,
+) -> dict[str, Any] | None:
+ """获取某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return None
+
+ scope = _get_transcript_scope(sess, transcript_path)
+ if isinstance(scope, dict):
+ event = scope.get("last_usage_event")
+ if isinstance(event, dict):
+ return event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ event = sess.get("_last_usage_event")
+ if isinstance(event, dict):
+ return event
+ return None
+
+
+def set_last_usage_event(
+ state: dict,
+ sid: str,
+ usage_event: dict[str, Any],
+ transcript_path: str | None = None,
+) -> None:
+ """持久化某个 transcript 最近一次用于去重的 usage 快照。"""
+ sess = state.get(sid)
+ if not isinstance(sess, dict):
+ return
+
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if isinstance(scope, dict):
+ scope["last_usage_event"] = usage_event
+
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_usage_event"] = usage_event
+
+
+def claim_transcript_event(
+ state_path: Path,
+ sid: str,
+ event_key: str,
+ transcript_path: str | None = None,
+ *,
+ max_seen_keys: int = 512,
+) -> bool:
+ """跨进程原子地声明一个 transcript 作用域内的事件键。"""
+ seen_path = get_transcript_seen_path(state_path)
+ scope_key = f"{sid}|{_transcript_scope_key(transcript_path)}"
+
+ with state_lock(state_path):
+ if seen_path.exists():
+ try:
+ ledger = json.loads(seen_path.read_text("utf-8"))
+ except Exception:
+ ledger = {}
+ else:
+ ledger = {}
+ if not isinstance(ledger, dict):
+ ledger = {}
+
+ seen = ledger.setdefault(scope_key, {})
+ if not isinstance(seen, dict):
+ seen = {}
+ ledger[scope_key] = seen
+ if event_key in seen:
+ return False
+ seen[event_key] = time.time()
+ if len(seen) > max_seen_keys:
+ stale_keys = sorted(seen, key=lambda k: float(seen.get(k, 0) or 0))[:-max_seen_keys]
+ for key in stale_keys:
+ seen.pop(key, None)
+ seen_path.write_text(json.dumps(ledger, ensure_ascii=False), encoding="utf-8")
+ return True
+
+
+def commit_transcript_progress(
+ state_path: Path,
+ sid: str,
+ transcript_path: str | None = None,
+ *,
+ offset: int | None = None,
+ last_cumulative_usage: dict[str, int] | None = None,
+) -> None:
+ """在处理完一个窗口后,原子地持久化 transcript 解析进度。"""
+
+ def _update(state: dict[str, Any]) -> None:
+ sess = ensure_session(state, sid)
+ scope = _get_transcript_scope(sess, transcript_path, create=True)
+ if not isinstance(scope, dict):
+ return
+ if offset is not None:
+ current_offset = int(scope.get("offset", 0) or 0)
+ next_offset = int(offset or 0)
+ if next_offset > current_offset:
+ scope["offset"] = next_offset
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_transcript_offset"] = next_offset
+ if isinstance(last_cumulative_usage, dict) and last_cumulative_usage:
+ scope["last_cumulative_usage"] = last_cumulative_usage
+ if _transcript_scope_key(transcript_path) == "__session__":
+ sess["_last_cumulative_usage"] = last_cumulative_usage
+
+ update_state_locked(state_path, _update)
diff --git a/.cursor/skills/agent-observability/scripts/dashboard/index.html b/.cursor/skills/agent-observability/scripts/dashboard/index.html
new file mode 100644
index 00000000..8c391f5c
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/dashboard/index.html
@@ -0,0 +1,1086 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent Observability</title>
+<style>
+:root{
+ --surface-page:#f9f9f7; --surface-card:#fcfcfb; --surface-sunken:#f2f1ec;
+ --text-primary:#0b0b0b; --text-secondary:#52514e; --text-muted:#898781;
+ --grid:#e1e0d9; --axis:#c3c2b7; --border:rgba(11,11,11,0.10);
+ --series-blue:#2a78d6; --series-orange:#eb6834; --series-aqua:#1baf7a; --series-yellow:#eda100;
+ --series-blue-wash:rgba(42,120,214,0.10); --series-orange-wash:rgba(235,104,52,0.10);
+ --seq-100:#cde2fb; --seq-200:#9ec5f4; --seq-350:#5598e7; --seq-450:#2a78d6; --seq-600:#184f95;
+ --status-good:#0ca30c; --status-warning:#b8790a; --status-critical:#d03b3b;
+ --status-good-bg:rgba(12,163,12,0.10); --status-warning-bg:rgba(184,121,10,0.12); --status-critical-bg:rgba(208,59,59,0.10);
+ --accent-ring:rgba(42,120,214,0.35);
+}
+@media (prefers-color-scheme: dark){
+ :root:not([data-theme="light"]){
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+ }
+}
+:root[data-theme="dark"]{
+ --surface-page:#0d0d0d; --surface-card:#1a1a19; --surface-sunken:#161615;
+ --text-primary:#ffffff; --text-secondary:#c3c2b7; --text-muted:#898781;
+ --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+ --series-blue:#3987e5; --series-orange:#d95926; --series-aqua:#199e70; --series-yellow:#c98500;
+ --series-blue-wash:rgba(57,135,229,0.14); --series-orange-wash:rgba(217,89,38,0.14);
+ --seq-100:#184f95; --seq-200:#1c5cab; --seq-350:#256abf; --seq-450:#3987e5; --seq-600:#86b6ef;
+ --status-good:#0ca30c; --status-warning:#fab219; --status-critical:#e66767;
+ --status-good-bg:rgba(12,163,12,0.16); --status-warning-bg:rgba(250,178,25,0.14); --status-critical-bg:rgba(230,103,103,0.14);
+ --accent-ring:rgba(57,135,229,0.4);
+}
+*{box-sizing:border-box;}
+body{background:var(--surface-page); color:var(--text-primary); font-family:"IBM Plex Sans","Segoe UI",system-ui,sans-serif; margin:0;}
+.mono{font-family:"IBM Plex Mono","SFMono-Regular",ui-monospace,monospace;}
+.tab-nums{font-variant-numeric:tabular-nums;}
+h1,h2,h3{text-wrap:balance; margin:0;}
+.app{max-width:1180px; margin:0 auto; padding:28px 24px 64px;}
+
+/* header */
+.app-header{display:flex; flex-wrap:wrap; align-items:flex-end; justify-content:space-between; gap:16px; margin-bottom:6px;}
+.app-title{font-size:22px; font-weight:600; letter-spacing:-0.01em;}
+.app-sub{color:var(--text-secondary); font-size:13.5px; margin-top:4px; max-width:60ch;}
+.sample-badge{display:inline-flex; align-items:center; gap:6px; font-family:"IBM Plex Mono",monospace; font-size:11px; letter-spacing:.04em; text-transform:uppercase; color:var(--status-warning); background:var(--status-warning-bg); border:1px solid var(--border); border-radius:5px; padding:4px 8px; white-space:nowrap;}
+
+/* filter row */
+.filter-row{display:flex; align-items:center; gap:8px; margin:18px 0 22px; padding-bottom:14px; border-bottom:1px solid var(--grid);}
+.filter-label{font-size:12px; color:var(--text-muted); text-transform:uppercase; letter-spacing:.05em; margin-right:4px;}
+.range-btn{font-family:inherit; font-size:13px; color:var(--text-secondary); background:transparent; border:1px solid transparent; border-radius:6px; padding:6px 11px; cursor:pointer;}
+.range-btn:hover{background:var(--surface-sunken);}
+.range-btn[aria-pressed="true"]{background:var(--surface-card); border-color:var(--border); color:var(--text-primary); font-weight:600;}
+.range-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:1px;}
+
+/* KPI strip */
+.kpis{display:grid; grid-template-columns:repeat(5,1fr); gap:1px; background:var(--border); border:1px solid var(--border); border-radius:10px; overflow:hidden; margin-bottom:24px;}
+.kpi{background:var(--surface-card); padding:16px 18px;}
+.kpi-label{font-size:12px; color:var(--text-muted);}
+.kpi-value{font-size:24px; font-weight:600; margin-top:6px; letter-spacing:-0.01em;}
+.kpi-delta{font-size:12px; margin-top:4px;}
+.kpi-delta.up{color:var(--status-critical);}
+.kpi-delta.down{color:var(--status-good);}
+.kpi-delta.flat{color:var(--text-muted);}
+
+/* tabs */
+.tabs{display:flex; gap:4px; border-bottom:1px solid var(--grid); margin-bottom:22px;}
+.tab-btn{font-family:inherit; font-size:13.5px; color:var(--text-secondary); background:transparent; border:none; border-bottom:2px solid transparent; padding:10px 4px; margin-right:22px; cursor:pointer;}
+.tab-btn:hover{color:var(--text-primary);}
+.tab-btn[aria-selected="true"]{color:var(--text-primary); border-bottom-color:var(--series-blue); font-weight:600;}
+.tab-btn:focus-visible{outline:2px solid var(--series-blue); outline-offset:2px;}
+.tab-panel[hidden]{display:none;}
+
+/* cards */
+.card{background:var(--surface-card); border:1px solid var(--border); border-radius:10px; padding:18px 20px;}
+.card + .card{margin-top:16px;}
+.card-head{display:flex; align-items:baseline; justify-content:space-between; margin-bottom:14px; gap:12px; flex-wrap:wrap;}
+.card-title{font-size:14px; font-weight:600;}
+.card-note{font-size:12px; color:var(--text-muted);}
+.grid-2{display:grid; grid-template-columns:1.3fr 1fr; gap:16px;}
+/* .card + .card 的 margin-top 是给"同一列里纵向堆叠的卡片"留间距用的;grid 的两个
+ 格子在 DOM 里也是相邻兄弟,会被同一条规则误伤,导致右边格子的卡片顶部被顶低
+ 16px、和左边对不齐。grid 行内的卡片间距已经由 .grid-2 的 gap 负责,这里清零。 */
+.grid-2 > .card + .card{margin-top:0;}
+/* Token 构成只画两根竖条,不需要宽度;按模型的成本占比要给模型名留横向空间,
+ 反过来分配才对得上两张图各自的实际需要。 */
+.grid-2.grid-2--cost{grid-template-columns:1fr 1.3fr;}
+/* 按模型的成本占比条数不固定(1~5 行),卡片天然高矮不一;Token 构成固定只有一张
+ 图,让它的图表区跟着 grid 拉伸出来的实际卡片高度走,而不是停在自己内容的高度、
+ 底下空出一大截。 */
+.grid-2--cost .card--fill-h{display:flex; flex-direction:column;}
+.grid-2--cost .card--fill-h .chart-wrap{flex:1 1 auto; min-height:160px;}
+.grid-2--cost .card--fill-h .chart-wrap svg.chart{height:100%;}
+@media(max-width:860px){.grid-2{grid-template-columns:1fr;} .grid-2.grid-2--cost{grid-template-columns:1fr;} .kpis{grid-template-columns:repeat(2,1fr);}}
+
+/* legend */
+.legend{display:flex; gap:14px; flex-wrap:wrap; font-size:12px; color:var(--text-secondary);}
+.legend-item{display:flex; align-items:center; gap:6px;}
+.legend-swatch{width:10px; height:10px; border-radius:2px; flex:none;}
+.legend-line{width:14px; height:2px; border-radius:1px; flex:none;}
+
+/* chart chrome */
+.chart-wrap{position:relative;}
+svg.chart{width:100%; height:auto; display:block; overflow:visible;}
+.axis-text{font-size:10.5px; fill:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.gridline{stroke:var(--grid); stroke-width:1;}
+.crosshair{stroke:var(--axis); stroke-width:1; pointer-events:none;}
+.tooltip{position:absolute; pointer-events:none; background:var(--surface-card); border:1px solid var(--border); border-radius:8px; padding:9px 11px; font-size:12px; box-shadow:0 6px 20px rgba(0,0,0,.16); opacity:0; transition:opacity .08s ease; z-index:5; min-width:132px;}
+.tooltip.show{opacity:1;}
+.tooltip-date{color:var(--text-muted); font-size:11px; margin-bottom:5px;}
+.tooltip-row{display:flex; align-items:center; gap:6px; justify-content:space-between; margin-top:3px;}
+.tooltip-key{display:flex; align-items:center; gap:6px; color:var(--text-secondary);}
+.tooltip-swatch{width:10px; height:2px; border-radius:1px;}
+.tooltip-val{font-family:"IBM Plex Mono",monospace; font-weight:600; color:var(--text-primary);}
+.hit-target{fill:transparent; cursor:crosshair;}
+.mark-lift{transition:opacity .08s ease;}
+
+/* stat / hero */
+.hero-row{display:flex; align-items:flex-end; gap:10px;}
+.hero-figure{font-size:30px; font-weight:600; letter-spacing:-0.01em;}
+.hero-unit{font-size:13px; color:var(--text-muted); padding-bottom:5px;}
+
+/* reminders */
+.reminders{display:grid; grid-template-columns:repeat(3,1fr); gap:12px;}
+@media(max-width:860px){.reminders{grid-template-columns:1fr;}}
+.reminder{border-radius:9px; padding:13px 14px; border:1px solid var(--border); display:flex; gap:10px;}
+.reminder.crit{background:var(--status-critical-bg);}
+.reminder.warn{background:var(--status-warning-bg);}
+.reminder.good{background:var(--status-good-bg);}
+.reminder-icon{flex:none; width:20px; height:20px; border-radius:5px; display:flex; align-items:center; justify-content:center; font-size:12px; font-weight:700; color:#fff; margin-top:1px;}
+.reminder.crit .reminder-icon{background:var(--status-critical);}
+.reminder.warn .reminder-icon{background:var(--status-warning); color:#3a2600;}
+.reminder.good .reminder-icon{background:var(--status-good);}
+.reminder-label{font-size:11px; text-transform:uppercase; letter-spacing:.04em; font-weight:700;}
+.reminder.crit .reminder-label{color:var(--status-critical);}
+.reminder.warn .reminder-label{color:var(--status-warning);}
+.reminder.good .reminder-label{color:var(--status-good);}
+.reminder-text{font-size:12.5px; color:var(--text-secondary); margin-top:3px; line-height:1.5;}
+.reminder-text b{color:var(--text-primary); font-weight:600;}
+
+/* tables */
+.table-scroll{overflow-x:auto;}
+table{width:100%; border-collapse:collapse; font-size:12.8px; min-width:640px;}
+th{text-align:left; font-size:11px; text-transform:uppercase; letter-spacing:.04em; color:var(--text-muted); font-weight:600; padding:8px 10px; border-bottom:1px solid var(--grid); white-space:nowrap;}
+td{padding:9px 10px; border-bottom:1px solid var(--grid); color:var(--text-secondary); white-space:nowrap;}
+tr.data-row{cursor:pointer;}
+tr.data-row:hover td{background:var(--surface-sunken);}
+td.strong{color:var(--text-primary); font-weight:600;}
+.chip{display:inline-flex; align-items:center; gap:5px; font-size:11px; font-weight:600; padding:3px 8px; border-radius:99px;}
+.chip.good{color:var(--status-good); background:var(--status-good-bg);}
+.chip.crit{color:var(--status-critical); background:var(--status-critical-bg);}
+.chip-dot{width:6px; height:6px; border-radius:50%; background:currentColor;}
+.expand-row td{background:var(--surface-sunken); padding:0;}
+.timeline{padding:14px 16px 16px;}
+.timeline-turn{margin-bottom:14px;}
+.timeline-turn:last-child{margin-bottom:0;}
+.timeline-turn-head{display:flex; align-items:baseline; justify-content:space-between; gap:10px; margin-bottom:6px;}
+.timeline-turn-label{font-size:11px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace;}
+.timeline-turn-count{font-size:11px; color:var(--text-muted); white-space:nowrap;}
+.timeline-scroll{overflow-x:auto; padding-bottom:3px;}
+.timeline-track{display:flex; gap:2px; align-items:stretch; height:26px; width:max-content; min-width:100%;}
+.timeline-seg{flex:0 0 auto; border-radius:4px; display:flex; align-items:center; justify-content:center; font-size:10.5px; color:#fff; font-family:"IBM Plex Mono",monospace; white-space:nowrap; padding:0 6px; overflow:hidden; text-overflow:ellipsis; box-sizing:border-box;}
+.timeline-seg.ok{background:var(--series-blue);}
+.timeline-seg.err{background:var(--status-critical);}
+.timeline-seg.usage{background:var(--series-aqua);}
+.timeline-seg.merged{background:var(--seq-350);}
+/* 派发给非 main 的 agent(比如 solo-developer、architect)执行的调用,顶部加一条
+ 高亮边框——同一个 turn 里经常混着 main 自己做的调用和转派出去的调用,光看
+ 颜色(ok/err/merged)分不出"这段到底是谁做的"。*/
+.timeline-seg.subagent{border-top:3px solid var(--series-yellow);}
+
+/* skill list */
+.bar-list{display:flex; flex-direction:column; gap:10px;}
+.bar-row{display:grid; grid-template-columns:150px 1fr 64px; gap:10px; align-items:center; font-size:12.5px;}
+.bar-row .name{color:var(--text-primary); overflow:hidden; text-overflow:ellipsis; white-space:nowrap;}
+.bar-track{height:16px; background:var(--surface-sunken); border-radius:4px; position:relative; overflow:hidden;}
+.bar-fill{height:100%; border-radius:4px;}
+.bar-row .val{text-align:right; color:var(--text-secondary);}
+.unused-list{display:flex; flex-direction:column; gap:8px; margin-top:4px;}
+.unused-item{display:flex; align-items:center; justify-content:space-between; gap:10px; font-size:12.5px; padding:8px 10px; background:var(--surface-sunken); border-radius:7px;}
+.unused-name{color:var(--text-primary); font-family:"IBM Plex Mono",monospace; font-size:12px;}
+.reason-chip{font-size:10.5px; color:var(--text-muted); font-family:"IBM Plex Mono",monospace; background:var(--surface-card); border:1px solid var(--border); padding:2px 7px; border-radius:5px;}
+
+/* devflow health */
+.health-row{display:flex; gap:22px; flex-wrap:wrap; align-items:center;}
+.health-stat{display:flex; flex-direction:column; gap:2px;}
+.health-stat .v{font-size:20px; font-weight:600;}
+.health-stat .l{font-size:11px; color:var(--text-muted);}
+.health-bar{flex:1 1 260px; min-width:220px;}
+.health-bar-track{height:10px; border-radius:5px; background:var(--surface-sunken); overflow:hidden; display:flex;}
+.health-bar-seg{height:100%;}
+.health-legend{display:flex; gap:14px; margin-top:8px; font-size:11.5px; color:var(--text-secondary);}
+
+/* devflow runs */
+.run-card{border:1px solid var(--border); border-radius:9px; padding:14px 16px; background:var(--surface-sunken);}
+.run-card + .run-card{margin-top:12px;}
+.run-head{display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:8px; margin-bottom:12px;}
+.run-title{font-family:"IBM Plex Mono",monospace; font-size:12.5px; color:var(--text-primary); font-weight:600;}
+.run-meta{display:flex; align-items:center; gap:8px; font-size:11.5px; color:var(--text-muted);}
+.size-chip{font-size:10.5px; text-transform:uppercase; letter-spacing:.03em; font-weight:700; padding:2px 7px; border-radius:5px; background:var(--surface-card); border:1px solid var(--border); color:var(--text-secondary);}
+.run-status-chip{font-size:11px; font-weight:600; padding:3px 9px; border-radius:99px; display:inline-flex; align-items:center; gap:5px;}
+.stepper{display:flex; align-items:center; overflow-x:auto; padding-bottom:4px;}
+.step{flex:0 0 auto; display:flex; flex-direction:column; align-items:center; width:68px; position:relative;}
+.step-dot{width:26px; height:26px; border-radius:50%; display:flex; align-items:center; justify-content:center; font-family:"IBM Plex Mono",monospace; font-size:9.5px; font-weight:700; color:#fff; border:2px solid var(--surface-sunken); position:relative; z-index:1;}
+.step-dot.pending{background:var(--surface-card); color:var(--text-muted); border-color:var(--axis);}
+.step-dot.in_progress{background:var(--series-blue);}
+.step-dot.completed{background:var(--status-good);}
+.step-dot.failed{background:var(--status-critical);}
+.step-dot.skipped{background:var(--surface-card); color:var(--text-muted); border-style:dashed;}
+.step-label{font-size:10px; color:var(--text-secondary); margin-top:5px; text-align:center; line-height:1.3;}
+.step-connector{position:absolute; top:13px; left:-34px; width:68px; height:2px; background:var(--axis); z-index:0;}
+.step:first-child .step-connector{display:none;}
+.step-retry{position:absolute; top:-8px; right:6px; background:var(--status-critical); color:#fff; font-size:9px; font-weight:700; border-radius:99px; padding:1px 5px; z-index:2;}
+
+/* heatmap */
+.heatmap-wrap{overflow-x:auto;}
+.heatmap-legend{display:flex; align-items:center; gap:5px; font-size:11px; color:var(--text-muted); margin-top:10px;}
+.heatmap-legend .sq{width:10px; height:10px; border-radius:2px;}
+
+footer.note{margin-top:30px; font-size:11.5px; color:var(--text-muted); line-height:1.7; border-top:1px solid var(--grid); padding-top:14px;}
+footer.note code{font-family:"IBM Plex Mono",monospace; background:var(--surface-sunken); padding:1px 5px; border-radius:4px;}
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap">
+</head>
+<body>
+
+<div class="app">
+ <div class="app-header">
+ <div>
+ <div class="app-title">Agent Observability</div>
+ <div class="app-sub">读取本地 <span class="mono">dashboard-data.json</span>(由 <span class="mono">build_dashboard_data.py</span> 从 metrics.ndjson / workflow-state.json 聚合而成)&middot; LoopForge 项目</div>
+ </div>
+ <div class="sample-badge" id="dataStatusBadge">加载中…</div>
+ </div>
+
+ <div class="filter-row">
+ <span class="filter-label">时间范围</span>
+ <button class="range-btn" data-range="7">近 7 天</button>
+ <button class="range-btn" data-range="30">近 30 天</button>
+ <button class="range-btn" data-range="90" aria-pressed="true">近 90 天</button>
+ </div>
+
+ <div class="kpis" id="kpiStrip"></div>
+
+ <div class="tabs" role="tablist">
+ <button class="tab-btn" role="tab" aria-selected="true" data-tab="overview">总览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="sessions">会话浏览</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="skills">Skill · Rule</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="agents">Agent 协作</button>
+ <button class="tab-btn" role="tab" aria-selected="false" data-tab="devflow">Devflow 运行</button>
+ </div>
+
+ <section class="tab-panel" id="panel-overview">
+ <div class="card">
+ <div class="card-head"><span class="card-title">建议关注</span><span class="card-note">按当前范围内的阈值规则实时算出,不是固定文案</span></div>
+ <div class="reminders" id="reminders"></div>
+ </div>
+
+ <div class="card">
+ <div class="card-head">
+ <span class="card-title">每日成本</span>
+ <div class="legend"><div class="legend-item"><span class="legend-line" style="background:var(--series-orange)"></span>cost_usd(按 <span class="mono">config/pricing.json</span> 估算)</div></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="costChart" viewBox="0 0 1080 220"></svg><div class="tooltip" id="costTooltip"></div></div>
+ </div>
+
+ <div class="grid-2 grid-2--cost">
+ <div class="card card--fill-h">
+ <div class="card-head">
+ <span class="card-title">Token 构成</span>
+ <div class="legend" id="tokenLegend"></div>
+ </div>
+ <div class="chart-wrap"><svg class="chart" id="tokenChart" viewBox="0 0 560 270"></svg><div class="tooltip" id="tokenTooltip"></div></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">按模型的成本占比</span><span class="card-note">Top 4 + 其他</span></div>
+ <div class="chart-wrap"><svg class="chart" id="modelChart" viewBox="0 0 460 210"></svg><div class="tooltip" id="modelTooltip"></div></div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">数据表</span><span class="card-note">图表的完整数值备份</span></div>
+ <div class="table-scroll"><table id="dailyTable"><thead><tr><th>日期</th><th>会话数</th><th>成本 (USD)</th><th>input</th><th>output</th><th>cache_read</th><th>工具失败</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-sessions" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近会话</span><span class="card-note">点击一行展开该会话按 turn 的工具调用时间线</span></div>
+ <div class="table-scroll"><table id="sessionTable">
+ <thead><tr><th>Session</th><th>日期</th><th>Agent</th><th>Turns</th><th>工具调用</th><th>Tokens</th><th>成本</th><th>时长</th><th>状态</th></tr></thead>
+ <tbody></tbody>
+ </table></div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-skills" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 触发热力图</span><span class="card-note">按天统计 <span class="mono">scanner.py</span> 命中的 skill 次数</span></div>
+ <div class="heatmap-wrap"><svg class="chart" id="heatmap" viewBox="0 0 900 118"></svg><div class="tooltip" id="heatmapTooltip"></div></div>
+ <div class="heatmap-legend">少<span class="sq" style="background:var(--seq-100)"></span><span class="sq" style="background:var(--seq-200)"></span><span class="sq" style="background:var(--seq-350)"></span><span class="sq" style="background:var(--seq-450)"></span><span class="sq" style="background:var(--seq-600)"></span>多</div>
+ </div>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Skill 使用排行</span><span class="card-note">按范围内触发次数</span></div>
+ <div class="bar-list" id="skillBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">从未命中的 Skill / Rule</span><span class="card-note">来自 <span class="mono">unmatched_rule_diagnostics_for_call</span> 的未命中原因</span></div>
+ <div class="unused-list" id="unusedList"></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-agents" hidden>
+ <div class="grid-2">
+ <div class="card">
+ <div class="card-head"><span class="card-title">Main → 子 Agent 派发次数</span><span class="card-note">来自 <span class="mono">.state.json</span> 的 agent_history</span></div>
+ <div class="bar-list" id="dispatchBars"></div>
+ </div>
+ <div class="card">
+ <div class="card-head"><span class="card-title">工具失败面板</span><span class="card-note">tool_details.raw_response.is_error</span></div>
+ <div class="table-scroll"><table id="failTable"><thead><tr><th>工具</th><th>错误码</th><th>次数</th><th>最近一次</th></tr></thead><tbody></tbody></table></div>
+ </div>
+ </div>
+ </section>
+
+ <section class="tab-panel" id="panel-devflow" hidden>
+ <div class="card">
+ <div class="card-head"><span class="card-title">Auto-Dispatch 健康度</span><span class="card-note">来自 <span class="mono">hooks/logs/auto-dispatch.log</span> 的派发决策统计</span></div>
+ <div class="health-row">
+ <div class="health-stat"><span class="v tab-nums" id="hDispatch">–</span><span class="l">auto_dispatch(零 token 直达)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallback">–</span><span class="l">fallback_to_main(唤醒 main)</span></div>
+ <div class="health-stat"><span class="v tab-nums" id="hFallbackRate">–</span><span class="l">fallback 率</span></div>
+ <div class="health-bar">
+ <div class="health-bar-track" id="hBar"></div>
+ <div class="health-legend">
+ <span><span class="legend-swatch" style="background:var(--status-good);display:inline-block"></span> auto_dispatch</span>
+ <span><span class="legend-swatch" style="background:var(--status-warning);display:inline-block"></span> fallback_to_main</span>
+ <span><span class="legend-swatch" style="background:var(--text-muted);display:inline-block"></span> passthrough(*_failed 等本就该回 main)</span>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div class="card">
+ <div class="card-head"><span class="card-title">最近 Devflow 运行</span><span class="card-note">按 task_slug 分组,串起 main + 最多 7 个 team member 的跨 session 归因</span></div>
+ <div id="devflowRuns"></div>
+ </div>
+ </section>
+
+ <footer class="note">
+ 数据来源:<code>python3 ../build_dashboard_data.py --project-root &lt;devflow 项目根目录&gt;</code> 会读取该项目下
+ <code>.codebuddy/skills/agent-observability/logs/metrics.ndjson</code>、<code>.state.json</code>、
+ <code>artifacts/*/workflow-state.json</code>(Classic/Portable 两种 schema 自动识别)与
+ <code>.codebuddy/hooks/logs/auto-dispatch.log</code>,聚合成同目录下的 <code>dashboard-data.json</code>。
+ 这个页面只读那份快照,不直接碰任何日志/状态文件——重新生成快照后刷新页面即可看到最新数据。
+ 全部处理在本机完成,不发往任何外部服务。
+ </footer>
+</div>
+
+<script>
+(function(){
+ "use strict";
+
+ var css = getComputedStyle(document.documentElement);
+ function tok(name){ return css.getPropertyValue(name).trim(); }
+
+ /* ---------- state populated by loadData() from ./dashboard-data.json (real data, no mock) ---------- */
+ var daily = [], sessions = [], dispatch = [], failures = [];
+ var SKILLS = [], NEVER_USED = [], modelCosts = [], unpricedModels = [];
+ var devflowRuns = [], autoDispatchStats = {auto_dispatch:0, fallback_to_main:0, passthrough:0};
+ var currentRange = 90;
+
+ function sliced(){ return daily.slice(daily.length-currentRange); }
+ function fmtUSD(v){ return "$"+v.toLocaleString(undefined,{minimumFractionDigits:2,maximumFractionDigits:2}); }
+ function fmtCompact(v){
+ if(v>=1e6) return (v/1e6).toFixed(1)+"M";
+ if(v>=1e3) return (v/1e3).toFixed(1)+"K";
+ return String(v);
+ }
+ function fmtDur(sec){
+ var m = Math.floor(sec/60), s = sec%60;
+ if(m>=60){ var h=Math.floor(m/60); m=m%60; return h+"h "+m+"m"; }
+ return m+"m "+s+"s";
+ }
+ function fmtDate(iso){ var p = iso.split("-"); return p[1]+"/"+p[2]; }
+
+ /* ================= KPI strip ================= */
+ function renderKPIs(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalTokens = d.reduce(function(a,x){return a+x.input+x.output;},0);
+ var totalSessions = d.reduce(function(a,x){return a+x.sessionCount;},0);
+ var totalCalls = d.reduce(function(a,x){return a+x.toolCalls;},0);
+ var totalFail = d.reduce(function(a,x){return a+x.failures;},0);
+ var failRate = totalCalls ? (totalFail/totalCalls*100) : 0;
+ var avgDur = sessions.length ? sessions.reduce(function(a,x){return a+x.duration;},0)/sessions.length : 0;
+
+ var items = [
+ {label:"会话数", value:totalSessions.toLocaleString(), delta:null},
+ {label:"累计成本", value:fmtUSD(totalCost), delta:null},
+ {label:"总 Token", value:fmtCompact(totalTokens), delta:null},
+ {label:"平均会话时长", value:fmtDur(Math.round(avgDur)), delta:null},
+ {label:"工具失败率", value:failRate.toFixed(1)+"%", delta:failRate>3?"up":"down"}
+ ];
+ var el = document.getElementById("kpiStrip");
+ el.innerHTML = "";
+ items.forEach(function(it){
+ var deltaHtml = "";
+ if(it.delta){
+ var cls = it.delta==="up" ? "up" : "down";
+ var arrow = it.delta==="up" ? "&#8593;" : "&#8595;";
+ deltaHtml = '<div class="kpi-delta '+cls+'">'+arrow+' vs 前一周期</div>';
+ }
+ var card = document.createElement("div");
+ card.className = "kpi";
+ var vEl = document.createElement("div"); vEl.className="kpi-value tab-nums";
+ var lEl = document.createElement("div"); lEl.className="kpi-label";
+ lEl.textContent = it.label; vEl.textContent = it.value;
+ card.appendChild(lEl); card.appendChild(vEl);
+ if(deltaHtml){ var dWrap=document.createElement("div"); dWrap.innerHTML=deltaHtml; card.appendChild(dWrap.firstChild); }
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= Reminders ================= */
+ /* 模型名来自日志(模型名是外部输入),插入 innerHTML 前必须转义。 */
+ function esc(s){
+ return String(s==null?"":s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;");
+ }
+
+ function renderReminders(){
+ var d = sliced();
+ var totalCost = d.reduce(function(a,x){return a+x.cost;},0);
+ var totalInput = d.reduce(function(a,x){return a+x.input;},0);
+ var totalCache = d.reduce(function(a,x){return a+x.cache;},0);
+ var cacheRate = totalInput ? (totalCache/totalInput*100) : 0;
+ var budget = 40;
+ var el = document.getElementById("reminders");
+ el.innerHTML = "";
+ var items = [];
+ items.push({
+ level: totalCost > budget ? "crit" : (totalCost > budget*0.75 ? "warn" : "good"),
+ label: "成本预算",
+ text: "近 "+currentRange+" 天累计花费 <b>"+fmtUSD(totalCost)+"</b>,预算阈值 "+fmtUSD(budget)+"("+(totalCost>budget?"已超出":(Math.round(totalCost/budget*100)+"% 已用"))+")。"
+ });
+ items.push({
+ level: cacheRate < 30 ? "warn" : "good",
+ label: "Prompt Cache 命中",
+ text: "cache_read 占 input 的 <b>"+cacheRate.toFixed(0)+"%</b>"+(cacheRate<30 ? ",偏低,可能是 system prompt 频繁变化导致缓存失效,白花了 input 成本。" : ",处于正常区间。")
+ });
+ var unusedCount = NEVER_USED.length;
+ items.push({
+ level: unusedCount>0 ? "warn" : "good",
+ label: "Skill 维护",
+ text: unusedCount>0 ? ("有 <b>"+unusedCount+"</b> 个 skill/rule 在范围内从未被命中,建议检查 description 或 globs。") : "所有已扫描的 skill/rule 近期均被命中过。"
+ });
+ /* 第 4 条:模型定价。unpricedModels 由 build_dashboard_data.py 聚合,
+ 只列"完全没命中价格表"的模型(模糊命中的不算,见 emitter.is_unpriced)。 */
+ var unpricedCount = (unpricedModels||[]).length;
+ var unpricedEvents = (unpricedModels||[]).reduce(function(a,x){return a+(x.usageEvents||0);},0);
+ var unpricedNames = (unpricedModels||[]).slice(0,3).map(function(x){return esc(x.name);}).join("、");
+ items.push({
+ level: unpricedCount>0 ? "warn" : "good",
+ label: "模型定价",
+ text: unpricedCount>0
+ ? ("有 <b>"+unpricedCount+"</b> 个模型未命中价格表(<b>"+unpricedEvents+"</b> 条 usage 事件缺少成本):"
+ +unpricedNames+(unpricedCount>3 ? " 等 "+unpricedCount+" 个" : "")
+ +"。可写入 <code>.codebuddy/agent-observability/pricing.overrides.json</code>,"
+ +"或用 <code>AOBS_PRICING_OVERRIDES_PATH</code> 指定覆盖文件补充单价;"
+ +"补充后只影响之后的新事件,不回溯已落盘的历史成本。")
+ : "所有出现的模型都已命中价格表,成本估算完整。"
+ });
+ items.forEach(function(it){
+ var card = document.createElement("div");
+ card.className = "reminder "+it.level;
+ var icon = it.level==="crit" ? "!" : (it.level==="warn" ? "!" : "✓");
+ card.innerHTML =
+ '<div class="reminder-icon">'+icon+'</div>'+
+ '<div><div class="reminder-label">'+(it.level==="crit"?"critical":it.level==="warn"?"warning":"good")+'</div>'+
+ '<div style="font-size:12.5px;font-weight:600;margin-top:2px;">'+it.label+'</div>'+
+ '<div class="reminder-text">'+it.text+'</div></div>';
+ el.appendChild(card);
+ });
+ }
+
+ /* ================= tooltip helper ================= */
+ function positionTooltip(tipEl, wrapEl, x, y){
+ var wrapRect = wrapEl.getBoundingClientRect();
+ var left = x, top = y - 14;
+ var maxLeft = wrapRect.width - 150;
+ if(left > maxLeft) left = maxLeft;
+ if(left < 4) left = 4;
+ tipEl.style.left = left + "px";
+ tipEl.style.top = Math.max(0, top - tipEl.offsetHeight) + "px";
+ }
+
+ var SVGNS = "http://www.w3.org/2000/svg";
+ function el(tag, attrs){
+ var e = document.createElementNS(SVGNS, tag);
+ for(var k in attrs){ e.setAttribute(k, attrs[k]); }
+ return e;
+ }
+
+ /* SVG <text> 没有 CSS text-overflow:ellipsis 那一套,长文本(比如自定义模型名)
+ 会原样溢出、被同一行后面画的柱子盖住。textEl 必须已经挂到 DOM 上(在真实渲染的
+ svg 里)才能拿到准确的 getComputedTextLength()。 */
+ function truncateSvgText(textEl, fullText, maxWidth){
+ textEl.textContent = fullText;
+ if(maxWidth<=0 || textEl.getComputedTextLength()<=maxWidth) return;
+ var lo=0, hi=fullText.length;
+ while(lo<hi){
+ var mid=(lo+hi+1)>>1;
+ textEl.textContent = fullText.slice(0,mid)+"…";
+ if(textEl.getComputedTextLength()<=maxWidth) lo=mid; else hi=mid-1;
+ }
+ textEl.textContent = lo>0 ? fullText.slice(0,lo)+"…" : "…";
+ }
+
+ /* ================= Cost trend (line + area, crosshair tooltip) ================= */
+ function renderCostChart(){
+ var svg = document.getElementById("costChart");
+ svg.innerHTML = "";
+ var W=1080,H=220, padL=44, padR=12, padT=14, padB=26;
+ var d = sliced();
+ if(d.length===0){
+ var empty0 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty0.textContent = "暂无数据 · 等真实会话跑起来后重新生成 dashboard-data.json";
+ svg.appendChild(empty0);
+ return;
+ }
+ var maxCost = Math.max.apply(null, d.map(function(x){return x.cost;})) || 1;
+ var niceMax = Math.ceil(maxCost*1.15/5)*5 || 5;
+ var plotW = W-padL-padR, plotH = H-padT-padB;
+ function xAt(i){ return padL + (d.length<=1?0:(i/(d.length-1))*plotW); }
+ function yAt(v){ return padT + plotH - (v/niceMax)*plotH; }
+
+ // gridlines + y labels
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g;
+ var y = yAt(v);
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"});
+ t.textContent = "$"+v.toFixed(0); svg.appendChild(t);
+ }
+ // x labels (sparse)
+ var step = Math.max(1, Math.round(d.length/7));
+ d.forEach(function(pt,i){
+ if(i%step===0 || i===d.length-1){
+ var t = el("text",{class:"axis-text",x:xAt(i),y:H-6,"text-anchor":"middle"});
+ t.textContent = fmtDate(pt.iso); svg.appendChild(t);
+ }
+ });
+
+ // area path
+ var top = d.map(function(pt,i){ return xAt(i)+","+yAt(pt.cost); }).join(" L ");
+ var areaD = "M "+xAt(0)+","+yAt(0)+" L "+top+" L "+xAt(d.length-1)+","+yAt(0)+" Z";
+ svg.appendChild(el("path",{d:areaD, fill:tok("--series-orange"), opacity:0.10, stroke:"none"}));
+ var lineD = "M "+top;
+ svg.appendChild(el("path",{d:lineD, fill:"none", stroke:tok("--series-orange"), "stroke-width":2, "stroke-linejoin":"round","stroke-linecap":"round"}));
+
+ // emphasized endpoint
+ var lastI = d.length-1;
+ svg.appendChild(el("circle",{cx:xAt(lastI), cy:yAt(d[lastI].cost), r:4.5, fill:tok("--series-orange"), stroke:tok("--surface-card"), "stroke-width":2}));
+ var endLabel = el("text",{class:"axis-text",x:xAt(lastI)-4,y:yAt(d[lastI].cost)-10,"text-anchor":"end", fill:tok("--text-primary")});
+ endLabel.setAttribute("font-weight","600");
+ endLabel.textContent = "$"+d[lastI].cost.toFixed(2);
+ svg.appendChild(endLabel);
+
+ // crosshair + hover
+ var crosshair = el("line",{class:"crosshair",x1:0,x2:0,y1:padT,y2:H-padB, opacity:0});
+ svg.appendChild(crosshair);
+ var hitRect = el("rect",{class:"hit-target",x:padL,y:padT,width:plotW,height:plotH});
+ svg.appendChild(hitRect);
+ var wrap = svg.parentNode, tip = document.getElementById("costTooltip");
+ function onMove(evt){
+ var rect = svg.getBoundingClientRect();
+ var mx = (evt.clientX-rect.left) * (W/rect.width);
+ var idx = Math.round(((mx-padL)/plotW)*(d.length-1));
+ idx = Math.max(0, Math.min(d.length-1, idx));
+ var px = xAt(idx);
+ crosshair.setAttribute("x1",px); crosshair.setAttribute("x2",px); crosshair.setAttribute("opacity",1);
+ var pt = d[idx];
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+tok("--series-orange")+'"></span>成本</span><span class="tooltip-val">'+fmtUSD(pt.cost)+'</span></div><div class="tooltip-row"><span class="tooltip-key">会话数</span><span class="tooltip-val">'+pt.sessionCount+'</span></div>';
+ tip.classList.add("show");
+ var screenX = px/(W/rect.width), screenY = yAt(pt.cost)/(H/rect.height);
+ positionTooltip(tip, wrap, screenX, screenY);
+ }
+ hitRect.addEventListener("pointermove", onMove);
+ hitRect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); crosshair.setAttribute("opacity",0); });
+ }
+
+ /* ================= Token composition (stacked bars) ================= */
+ function renderTokenChart(){
+ var svg = document.getElementById("tokenChart"); svg.innerHTML="";
+ var legend = document.getElementById("tokenLegend");
+ var series = [
+ {key:"input", label:"input", color:tok("--series-blue")},
+ {key:"output", label:"output", color:tok("--series-aqua")},
+ {key:"cache", label:"cache_read", color:tok("--series-yellow")}
+ ];
+ legend.innerHTML = series.map(function(s){ return '<div class="legend-item"><span class="legend-swatch" style="background:'+s.color+'"></span>'+s.label+'</div>'; }).join("");
+
+ // 按模型的成本占比条数不固定(1~5 行),两张图挨着放的时候卡片高矮天然不一样。
+ // .card--fill-h 让这张图的 .chart-wrap 跟着 grid 拉伸出来的实际卡片高度走(CSS),
+ // 这里直接读它撑开后的真实像素尺寸当 viewBox,而不是猜一个写死的高宽比——
+ // renderModelChart() 必须先跑完把内容插进 DOM,这个测量才反映得出最终高度
+ // (见 renderAll() / 时间范围切换 / resize 三处调用顺序)。560x270 只是量不到时
+ // (比如面板还没显示)的兜底默认值。
+ var wrapRect = svg.parentNode.getBoundingClientRect();
+ var W = Math.round(wrapRect.width) || 560;
+ var H = Math.max(160, Math.round(wrapRect.height) || 270);
+ svg.setAttribute("viewBox","0 0 "+W+" "+H);
+ var padL=46,padR=10,padT=10,padB=24;
+ var d = sliced().slice(-30); // cap bars for legibility
+ if(d.length===0){
+ var empty1 = el("text",{class:"axis-text",x:16,y:H/2,fill:tok("--text-muted")});
+ empty1.textContent = "暂无数据";
+ svg.appendChild(empty1);
+ return;
+ }
+ var maxTotal = Math.max.apply(null, d.map(function(x){return x.input+x.output+x.cache;})) || 1;
+ var niceMax = Math.ceil(maxTotal*1.1/10000)*10000 || 10000;
+ var plotW=W-padL-padR, plotH=H-padT-padB;
+ var bw = Math.min(28, plotW/d.length*0.62);
+ var gap = plotW/d.length;
+
+ for(var g=0; g<=4; g++){
+ var v = niceMax/4*g, y = padT+plotH-(v/niceMax)*plotH;
+ svg.appendChild(el("line",{class:"gridline",x1:padL,x2:W-padR,y1:y,y2:y}));
+ var t = el("text",{class:"axis-text",x:padL-8,y:y+3,"text-anchor":"end"}); t.textContent=fmtCompact(v); svg.appendChild(t);
+ }
+ var wrap = svg.parentNode, tip = document.getElementById("tokenTooltip");
+ d.forEach(function(pt,i){
+ var x = padL + i*gap + (gap-bw)/2;
+ var vals = [pt.input, pt.output, pt.cache];
+ var yCursor = padT+plotH;
+ var bar = el("g",{});
+ vals.forEach(function(v,si){
+ var hgt = (v/niceMax)*plotH;
+ if(hgt<=0) return;
+ var yTop = yCursor - hgt;
+ bar.appendChild(el("rect",{x:x,y:yTop+1,width:bw,height:Math.max(0,hgt-2),rx:2,fill:series[si].color}));
+ yCursor = yTop;
+ });
+ var hit = el("rect",{class:"hit-target",x:x-2,y:padT,width:bw+4,height:plotH});
+ svg.appendChild(bar); svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(pt,x){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[0].color+'"></span>input</span><span class="tooltip-val">'+pt.input.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[1].color+'"></span>output</span><span class="tooltip-val">'+pt.output.toLocaleString()+'</span></div>'+
+ '<div class="tooltip-row"><span class="tooltip-key"><span class="tooltip-swatch" style="background:'+series[2].color+'"></span>cache_read</span><span class="tooltip-val">'+pt.cache.toLocaleString()+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(W/rect.width), padT);
+ };}(pt,x));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ var t2 = el("text",{class:"axis-text",x:padL,y:H-6}); t2.textContent = fmtDate(d[0].iso); svg.appendChild(t2);
+ var t3 = el("text",{class:"axis-text",x:W-padR,y:H-6,"text-anchor":"end"}); t3.textContent = fmtDate(d[d.length-1].iso); svg.appendChild(t3);
+ }
+
+ /* ================= Model cost breakdown (horizontal bars) ================= */
+ function renderModelChart(){
+ var svg = document.getElementById("modelChart"); svg.innerHTML="";
+ // modelCosts 是索引器按 usage 事件的真实 model/cost_usd 汇总出来的(全量,不随时间范围筛选——
+ // 按天切分模型成本需要索引器额外输出 daily×model 的交叉表,这版先给全量占比)。
+ var rows = modelCosts.slice().sort(function(a,b){return b.cost-a.cost;});
+ var top = rows.slice(0,4);
+ var restCost = rows.slice(4).reduce(function(a,x){return a+x.cost;},0);
+ if(restCost>0) top.push({name:"其他", cost:restCost, other:true});
+ if(top.length===0){
+ var empty = el("text",{class:"axis-text",x:12,y:30,fill:tok("--text-muted")});
+ empty.textContent = "暂无数据";
+ svg.appendChild(empty);
+ return;
+ }
+
+ var W=460,H=210,padL=12,padR=54,padT=8,padB=8;
+ var rowH = (H-padT-padB)/top.length;
+ var maxV = Math.max.apply(null, top.map(function(x){return x.cost;})) || 1;
+ var colors = [tok("--series-blue"),tok("--series-orange"),tok("--series-aqua"),tok("--series-yellow"),tok("--axis")];
+ var wrap = svg.parentNode, tip = document.getElementById("modelTooltip");
+
+ // 第一遍:把每行的完整模型名挂到 DOM 上量出真实渲染宽度(getComputedTextLength
+ // 要素材已经在 DOM 里才准),取最长的一个决定标签列该留多宽——而不是像之前那样
+ // 写死 84px、名字一长就被柱子盖住。上限按图表总宽的 55% 封顶,避免某一个特别长
+ // 的名字把柱子全挤没了;封顶之后仍放不下的极端情况,靠 truncateSvgText 兜底截断。
+ var geoms = top.map(function(row,i){
+ var y = padT + i*rowH;
+ var barH = Math.min(22, rowH*0.55);
+ var barY = y + (rowH-barH)/2;
+ var label = el("text",{class:"axis-text",x:padL,y:barY+barH/2+3, fill:tok("--text-secondary")});
+ label.setAttribute("font-size","11");
+ label.textContent = row.name;
+ svg.appendChild(label);
+ return {row:row, i:i, y:y, barH:barH, barY:barY, label:label};
+ });
+ var maxLabelW = Math.max.apply(null, geoms.map(function(g){return g.label.getComputedTextLength();}));
+ var labelColW = Math.min(Math.max(maxLabelW+10, 70), W*0.55);
+ var barX = padL+labelColW;
+ var maxW = W-padL-padR-labelColW;
+
+ geoms.forEach(function(g){
+ var row=g.row, i=g.i, y=g.y, barH=g.barH, barY=g.barY, label=g.label;
+ truncateSvgText(label, row.name, labelColW-6);
+ label.appendChild(el("title",{})).textContent = row.name;
+ var w = Math.max(2,(row.cost/maxV)*maxW);
+ var bar = el("rect",{x:barX,y:barY,width:w,height:barH,rx:4,fill:row.other?tok("--axis"):colors[i]});
+ svg.appendChild(bar);
+ var val = el("text",{class:"axis-text",x:barX+w+6,y:barY+barH/2+3, fill:tok("--text-primary")});
+ val.setAttribute("font-weight","600"); val.textContent = fmtUSD(row.cost);
+ svg.appendChild(val);
+ var hit = el("rect",{class:"hit-target",x:0,y:y,width:W,height:rowH});
+ svg.appendChild(hit);
+ hit.addEventListener("pointermove", function(row,y){ return function(evt){
+ var rect = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-row"><span class="tooltip-key">'+row.name+'</span><span class="tooltip-val">'+fmtUSD(row.cost)+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, (W-40)/(W/rect.width), y/(H/rect.height));
+ };}(row,y));
+ hit.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ });
+ }
+
+ /* ================= Daily data table (accessibility fallback) ================= */
+ function renderDailyTable(){
+ var tbody = document.querySelector("#dailyTable tbody");
+ tbody.innerHTML = "";
+ sliced().slice().reverse().forEach(function(pt){
+ var tr = document.createElement("tr");
+ [pt.iso, pt.sessionCount, fmtUSD(pt.cost), pt.input.toLocaleString(), pt.output.toLocaleString(), pt.cache.toLocaleString(), pt.failures]
+ .forEach(function(v,i){
+ var td = document.createElement("td");
+ td.textContent = v; td.classList.add("tab-nums");
+ if(i===0) td.classList.add("strong");
+ tr.appendChild(td);
+ });
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= Sessions tab ================= */
+ function renderSessions(){
+ var tbody = document.querySelector("#sessionTable tbody");
+ tbody.innerHTML = "";
+ if(sessions.length===0){
+ tbody.innerHTML = '<tr><td colspan="9" style="color:var(--text-muted);">暂无会话记录</td></tr>';
+ return;
+ }
+ sessions.forEach(function(s){
+ var tr = document.createElement("tr");
+ tr.className = "data-row";
+ var statusChip = s.status==="error"
+ ? '<span class="chip crit"><span class="chip-dot"></span>有失败</span>'
+ : '<span class="chip good"><span class="chip-dot"></span>正常</span>';
+ tr.innerHTML =
+ '<td class="strong mono">'+s.id+'</td>'+
+ '<td class="tab-nums">'+s.date+'</td>'+
+ '<td>'+s.agent+'</td>'+
+ '<td class="tab-nums">'+s.turns+'</td>'+
+ '<td class="tab-nums">'+s.toolCalls+'</td>'+
+ '<td class="tab-nums">'+s.tokens.toLocaleString()+'</td>'+
+ '<td class="tab-nums">'+fmtUSD(s.cost)+'</td>'+
+ '<td class="tab-nums">'+fmtDur(s.duration)+'</td>'+
+ '<td>'+statusChip+'</td>';
+ tbody.appendChild(tr);
+
+ var expandTr = document.createElement("tr");
+ expandTr.className = "expand-row";
+ expandTr.hidden = true;
+ var td = document.createElement("td");
+ td.colSpan = 9;
+ // 把同一 turn 里连续且工具名相同的调用合并成一段(累加耗时、记次数),
+ // 这样"循环调用同一个工具 N 次"不会被渲染成 N 个几乎看不清的窄条。
+ function mergeTurnEvents(events){
+ var merged = [];
+ events.forEach(function(ev){
+ var last = merged[merged.length-1];
+ var agent = ev.agent || "main";
+ // 只合并连续且 agent 也相同的调用——否则 main 调 Bash、转派给
+ // solo-developer 又调一次 Bash,会被错误地合并成一段"Bash ×2",
+ // 看不出中间其实发生了一次 agent 切换。
+ if(ev.kind==="tool" && last && last.kind==="tool" && last.tool===ev.tool && last.agent===agent){
+ last.ms += ev.ms; last.count += 1; last.err = last.err || ev.err;
+ } else if(ev.kind==="tool"){
+ merged.push({kind:"tool", tool:ev.tool, ms:ev.ms, count:1, err:ev.err, agent:agent});
+ } else {
+ merged.push({kind:"usage", tokens:ev.tokens, agent:agent});
+ }
+ });
+ return merged;
+ }
+ var timelineHtml = s.timeline.map(function(turn){
+ var toolRaw = turn.events.filter(function(e){ return e.kind==="tool"; }).length;
+ var segsData = mergeTurnEvents(turn.events);
+ var toolMerged = segsData.filter(function(e){ return e.kind==="tool"; }).length;
+ // 段宽是真实像素(不是 flex-grow 权重),行外层带 overflow-x:auto——
+ // 调用数再多,也只是这一行变宽可横向滚动,不会撑破卡片或挤压其它内容。
+ var segs = segsData.map(function(seg){
+ var isSubagent = seg.agent && seg.agent !== "main";
+ if(seg.kind==="tool"){
+ var cls = (seg.err ? "err" : (seg.count>1 ? "merged" : "ok")) + (isSubagent ? " subagent" : "");
+ var label = seg.count>1 ? (seg.tool+' ×'+seg.count) : seg.tool;
+ var titleText = seg.tool + (seg.count>1 ? (' × '+seg.count+' 次,合计 '+seg.ms+'ms') : (' · '+seg.ms+'ms')) + ' · agent='+(seg.agent||"main");
+ // 段宽取"按耗时算出的宽度"和"能放下标签文字的最小宽度"两者较大值——
+ // 本地工具调用常常只有几百 ms,纯按 ms*0.05 算出来的宽度几乎总是不到
+ // 文字下限,标签会被整段隐藏,只能靠悬浮 title 才看得到工具名。
+ var labelW = Math.min(140, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(140, seg.ms*0.05));
+ return '<div class="timeline-seg '+cls+'" style="width:'+w+'px" title="'+titleText+'">'+label+'</div>';
+ }
+ var label = seg.tokens+' tok';
+ var labelW = Math.min(130, label.length*6.5+14);
+ var w = Math.max(labelW, Math.min(130, seg.tokens*0.008));
+ var usageCls = "usage"+(isSubagent ? " subagent" : "");
+ return '<div class="timeline-seg '+usageCls+'" style="width:'+w+'px" title="usage · '+seg.tokens+' tok · agent='+(seg.agent||"main")+'">'+label+'</div>';
+ }).join("");
+ var countNote = (toolMerged!==toolRaw)
+ ? ('共 '+toolRaw+' 次工具调用 · 合并连续重复为 '+toolMerged+' 段')
+ : (toolRaw+' 次工具调用');
+ return '<div class="timeline-turn"><div class="timeline-turn-head"><span class="timeline-turn-label">turn '+turn.turn+' &middot; agent='+turn.agent+'</span><span class="timeline-turn-count">'+countNote+'</span></div><div class="timeline-scroll"><div class="timeline-track">'+segs+'</div></div></div>';
+ }).join("");
+ td.innerHTML = '<div class="timeline">'+timelineHtml+'</div>';
+ expandTr.appendChild(td);
+ tbody.appendChild(expandTr);
+
+ tr.addEventListener("click", function(expandTr){ return function(){ expandTr.hidden = !expandTr.hidden; }; }(expandTr));
+ });
+ }
+
+ /* ================= Skills tab ================= */
+ function renderHeatmap(){
+ var svg = document.getElementById("heatmap"); svg.innerHTML="";
+ var d = daily; // full 90d regardless of range filter, like a contribution calendar
+ var cell=11, gap=3, padL=26, padT=14;
+ var weeks = Math.ceil(d.length/7);
+ var maxHit = Math.max.apply(null, d.map(function(x){
+ return Object.keys(x.skillHits).reduce(function(a,k){return a+x.skillHits[k];},0);
+ })) || 1;
+ var ramp = ["--seq-100","--seq-200","--seq-350","--seq-450","--seq-600"];
+ var dow = ["一","三","五"];
+ [1,3,5].forEach(function(row,ix){
+ var t = el("text",{class:"axis-text",x:padL-8,y:padT+row*(cell+gap)+9,"text-anchor":"end"});
+ t.textContent = dow[ix]; svg.appendChild(t);
+ });
+ var wrap = svg.parentNode, tip = document.getElementById("heatmapTooltip");
+ for(var i=0;i<d.length;i++){
+ var pt = d[i];
+ var jsDow = pt.date.getDay(); // 0=Sun
+ var col = Math.floor(i/7), row = jsDow;
+ var total = Object.keys(pt.skillHits).reduce(function(a,k){return a+pt.skillHits[k];},0);
+ var level = total===0 ? -1 : Math.min(4, Math.floor((total/maxHit)*5));
+ var color = level<0 ? tok("--grid") : tok("--"+ramp[level].slice(2));
+ var x = padL + col*(cell+gap), y = padT + row*(cell+gap);
+ var rect = el("rect",{x:x,y:y,width:cell,height:cell,rx:2,fill:color});
+ svg.appendChild(rect);
+ rect.addEventListener("pointermove", function(pt,total,x,y){ return function(evt){
+ var rect2 = svg.getBoundingClientRect();
+ tip.innerHTML = '<div class="tooltip-date">'+pt.iso+'</div><div class="tooltip-row"><span class="tooltip-key">skill 命中</span><span class="tooltip-val">'+total+'</span></div>';
+ tip.classList.add("show");
+ positionTooltip(tip, wrap, x/(900/rect2.width), y/(118/rect2.height));
+ };}(pt,total,x,y));
+ rect.addEventListener("pointerleave", function(){ tip.classList.remove("show"); });
+ }
+ }
+
+ function renderSkillBars(){
+ var el2 = document.getElementById("skillBars");
+ var totals = {};
+ SKILLS.forEach(function(s){ totals[s]=0; });
+ daily.forEach(function(pt){ SKILLS.forEach(function(s){ totals[s]+=pt.skillHits[s]; }); });
+ var rows = SKILLS.map(function(s){ return {name:s, count:totals[s]}; }).sort(function(a,b){return b.count-a.count;});
+ var maxV = rows[0] ? rows[0].count : 1;
+ el2.innerHTML = "";
+ rows.forEach(function(r,i){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">'+r.name+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-blue")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderUnused(){
+ var el2 = document.getElementById("unusedList");
+ el2.innerHTML = "";
+ NEVER_USED.forEach(function(u){
+ var div = document.createElement("div");
+ div.className = "unused-item";
+ div.innerHTML = '<div><div class="unused-name">'+u.name+'</div><div style="font-size:11.5px;color:var(--text-muted);margin-top:2px;">'+u.detail+'</div></div><span class="reason-chip">'+u.reason+'</span>';
+ el2.appendChild(div);
+ });
+ }
+
+ /* ================= Agents tab ================= */
+ function renderDispatch(){
+ var el2 = document.getElementById("dispatchBars");
+ el2.innerHTML = "";
+ if(dispatch.length===0){
+ el2.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无派发记录</div>';
+ return;
+ }
+ var maxV = dispatch[0].count;
+ dispatch.forEach(function(r){
+ var pct = Math.max(3, r.count/maxV*100);
+ var div = document.createElement("div");
+ div.className = "bar-row";
+ div.innerHTML = '<div class="name mono">main → '+r.agent+'</div><div class="bar-track"><div class="bar-fill" style="width:'+pct+'%; background:'+tok("--series-aqua")+'"></div></div><div class="val tab-nums">'+r.count+'</div>';
+ el2.appendChild(div);
+ });
+ }
+
+ function renderFailTable(){
+ var tbody = document.querySelector("#failTable tbody");
+ tbody.innerHTML = "";
+ failures.forEach(function(f){
+ var tr = document.createElement("tr");
+ tr.innerHTML = '<td class="strong">'+f.tool+'</td><td class="mono">'+f.code+'</td><td class="tab-nums">'+f.count+'</td><td class="tab-nums">'+f.last+'</td>';
+ tbody.appendChild(tr);
+ });
+ }
+
+ /* ================= devflow ================= */
+ function renderDevflowHealth(){
+ var d = autoDispatchStats;
+ var total = d.auto_dispatch + d.fallback_to_main + d.passthrough;
+ document.getElementById("hDispatch").textContent = d.auto_dispatch.toLocaleString();
+ document.getElementById("hFallback").textContent = d.fallback_to_main.toLocaleString();
+ var rate = total ? (d.fallback_to_main/total*100) : 0;
+ document.getElementById("hFallbackRate").textContent = rate.toFixed(1)+"%";
+ var bar = document.getElementById("hBar");
+ bar.innerHTML = "";
+ [["auto_dispatch",tok("--status-good")],["fallback_to_main",tok("--status-warning")],["passthrough",tok("--text-muted")]].forEach(function(pair){
+ var seg = document.createElement("div");
+ seg.className = "health-bar-seg";
+ seg.style.width = (total? d[pair[0]]/total*100 : 0)+"%";
+ seg.style.background = pair[1];
+ seg.title = pair[0]+": "+d[pair[0]];
+ bar.appendChild(seg);
+ });
+ }
+
+ function renderDevflowRuns(){
+ var wrap = document.getElementById("devflowRuns");
+ wrap.innerHTML = "";
+ if(devflowRuns.length===0){
+ wrap.innerHTML = '<div style="font-size:12.5px;color:var(--text-muted);">暂无 devflow 运行记录(没有 artifacts/*/workflow-state.json,或者项目还没跑过 /start-devflow)</div>';
+ return;
+ }
+ devflowRuns.forEach(function(run){
+ var card = document.createElement("div");
+ card.className = "run-card";
+ var statusChip = run.overall==="completed"
+ ? '<span class="run-status-chip" style="background:var(--status-good-bg);color:var(--status-good)"><span class="chip-dot"></span>已完成</span>'
+ : run.overall==="running"
+ ? '<span class="run-status-chip" style="background:var(--series-blue-wash);color:var(--series-blue)"><span class="chip-dot"></span>进行中</span>'
+ : '<span class="run-status-chip" style="background:var(--status-critical-bg);color:var(--status-critical)"><span class="chip-dot"></span>已暂停 · 待人工介入</span>';
+ var head = document.createElement("div");
+ head.className = "run-head";
+ head.innerHTML =
+ '<div class="run-title">'+run.slug+'</div>'+
+ '<div class="run-meta"><span class="size-chip">'+run.size+'</span>'+statusChip+
+ '<span class="tab-nums">'+fmtUSD(run.cost)+'</span><span class="tab-nums" title="按真实起止跨度(最早 started_at 到最晚 completed_at)计算;阶段之间有重叠时,会小于各阶段耗时直接相加">'+fmtDur(run.duration)+'</span></div>';
+ card.appendChild(head);
+
+ var stepper = document.createElement("div");
+ stepper.className = "stepper";
+ run.stages.forEach(function(s){
+ var step = document.createElement("div");
+ step.className = "step";
+ var retryBadge = s.retry_count>0 ? '<div class="step-retry">&#8635;'+s.retry_count+'</div>' : "";
+ var titleText = s.name+" · executor="+s.exec+(s.status!=="pending"?(" · "+fmtDur(s.duration)):"")+(s.retry_count>0?(" · retry_count="+s.retry_count):"");
+ step.innerHTML =
+ '<div class="step-connector"></div>'+
+ '<div class="step-dot '+s.status+'" title="'+titleText+'">'+s.label+retryBadge+'</div>'+
+ '<div class="step-label">'+s.name+'</div>';
+ stepper.appendChild(step);
+ });
+ card.appendChild(stepper);
+ wrap.appendChild(card);
+ });
+ }
+
+ /* ================= render all ================= */
+ function renderAll(){
+ renderKPIs();
+ renderReminders();
+ renderCostChart();
+ renderModelChart();
+ renderTokenChart();
+ renderDailyTable();
+ renderSessions();
+ renderHeatmap();
+ renderSkillBars();
+ renderUnused();
+ renderDispatch();
+ renderFailTable();
+ renderDevflowHealth();
+ renderDevflowRuns();
+ }
+
+ /* ================= load real data from ./dashboard-data.json ================= */
+ function setBadge(text, tone){
+ var badge = document.getElementById("dataStatusBadge");
+ badge.textContent = text;
+ badge.style.color = tone==="good" ? tok("--status-good") : tone==="crit" ? tok("--status-critical") : tok("--status-warning");
+ badge.style.background = tone==="good" ? tok("--status-good-bg") : tone==="crit" ? tok("--status-critical-bg") : tok("--status-warning-bg");
+ }
+ function loadData(){
+ fetch("./dashboard-data.json", {cache:"no-store"})
+ .then(function(resp){
+ if(!resp.ok) throw new Error("HTTP "+resp.status);
+ return resp.json();
+ })
+ .then(function(data){
+ daily = (data.daily||[]).map(function(d){ d.date = new Date(d.iso+"T00:00:00"); return d; });
+ sessions = data.sessions||[];
+ dispatch = data.dispatch||[];
+ failures = data.failures||[];
+ SKILLS = (data.skills||[]).map(function(s){return s.name;});
+ NEVER_USED = data.neverUsed||[];
+ modelCosts = data.modelCosts||[];
+ unpricedModels = data.unpricedModels||[];
+ devflowRuns = data.devflowRuns||[];
+ autoDispatchStats = data.autoDispatchStats||{auto_dispatch:0, fallback_to_main:0, passthrough:0};
+
+ var total = (data.source && data.source.event_count) || 0;
+ if(total===0){
+ setBadge("还没有数据 · 见页脚生成说明", "warn");
+ } else {
+ var genAt = data.generated_at ? data.generated_at.replace("T"," ").replace("+00:00"," UTC") : "";
+ setBadge("真实数据 · "+total+" 条事件 · 生成于 "+genAt, "good");
+ }
+ renderAll();
+ })
+ .catch(function(err){
+ setBadge("加载 dashboard-data.json 失败", "crit");
+ var note = document.querySelector("footer.note");
+ if(note){
+ var warn = document.createElement("div");
+ warn.style.cssText = "margin-top:10px;color:"+tok("--status-critical")+";";
+ warn.textContent = "错误详情:" + err.message + "(先运行 build_dashboard_data.py 生成这份快照,再用本地 HTTP server 打开本页——直接双击用 file:// 打开会因为浏览器禁止本地 fetch 而失败)。";
+ note.appendChild(warn);
+ }
+ renderAll();
+ });
+ }
+ loadData();
+
+ /* ================= wiring: range buttons ================= */
+ document.querySelectorAll(".range-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".range-btn").forEach(function(b){ b.setAttribute("aria-pressed","false"); });
+ btn.setAttribute("aria-pressed","true");
+ currentRange = parseInt(btn.dataset.range,10);
+ renderKPIs(); renderReminders(); renderCostChart(); renderModelChart(); renderTokenChart(); renderDailyTable();
+ });
+ });
+
+ /* ================= wiring: tabs ================= */
+ var panels = {overview:"panel-overview", sessions:"panel-sessions", skills:"panel-skills", agents:"panel-agents", devflow:"panel-devflow"};
+ document.querySelectorAll(".tab-btn").forEach(function(btn){
+ btn.addEventListener("click", function(){
+ document.querySelectorAll(".tab-btn").forEach(function(b){ b.setAttribute("aria-selected","false"); });
+ btn.setAttribute("aria-selected","true");
+ Object.keys(panels).forEach(function(k){ document.getElementById(panels[k]).hidden = (k!==btn.dataset.tab); });
+ });
+ });
+
+ window.addEventListener("resize", function(){
+ renderCostChart(); renderModelChart(); renderTokenChart(); renderHeatmap();
+ });
+})();
+</script>
+</body>
+</html>
diff --git a/.cursor/skills/agent-observability/scripts/main.py b/.cursor/skills/agent-observability/scripts/main.py
new file mode 100644
index 00000000..4ca24812
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/main.py
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""agent-observability 的 hook 入口。"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+if __package__ in (None, ""):
+ _SCRIPTS_DIR = Path(__file__).resolve().parent
+ if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+ from core.runtime import main as runtime_main # type: ignore
+else:
+ from .core.runtime import main as runtime_main
+
+
+def main() -> int:
+ return runtime_main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.cursor/skills/agent-observability/scripts/run_hook.sh b/.cursor/skills/agent-observability/scripts/run_hook.sh
new file mode 100644
index 00000000..d476810f
--- /dev/null
+++ b/.cursor/skills/agent-observability/scripts/run_hook.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+PROJECT_DIR="${CODEBUDDY_PROJECT_DIR:-$(cd "$(dirname "$0")"/../../../.. && pwd -P)}"
+PYTHON_BIN="$PROJECT_DIR/.venv/bin/python"
+MAIN_PY="$PROJECT_DIR/.codebuddy/skills/agent-observability/scripts/main.py"
+
+# 只有当 .venv 里可用 zhiyanllm 时才优先使用该解释器;
+# 否则回退到已安装 zhiyanllm 的系统 python3。
+if [ -x "$PYTHON_BIN" ]; then
+ if "$PYTHON_BIN" -c "import zhiyanllm" 2>/dev/null; then
+ exec "$PYTHON_BIN" "$MAIN_PY" "$@"
+ fi
+fi
+
+exec python3 "$MAIN_PY" "$@"
diff --git a/.cursor/skills/agent-observability/templates/settings-hook.json b/.cursor/skills/agent-observability/templates/settings-hook.json
new file mode 100644
index 00000000..a76fc266
--- /dev/null
+++ b/.cursor/skills/agent-observability/templates/settings-hook.json
@@ -0,0 +1,62 @@
+{
+ "_comment": "将本文件合并到 ~/.cursor/settings.json 或 <project>/.cursor/settings.json",
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.cursor/skills/agent-observability/scripts/run_hook.sh session-start",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.cursor/skills/agent-observability/scripts/run_hook.sh user-prompt-submit",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.cursor/skills/agent-observability/scripts/run_hook.sh pre",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.cursor/skills/agent-observability/scripts/run_hook.sh post",
+ "timeout": 30
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"$CODEBUDDY_PROJECT_DIR\"/.cursor/skills/agent-observability/scripts/run_hook.sh stop",
+ "timeout": 30
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.cursor/skills/agent-observability/tests/fixtures/transcript.jsonl b/.cursor/skills/agent-observability/tests/fixtures/transcript.jsonl
new file mode 100644
index 00000000..a5ea47dd
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/fixtures/transcript.jsonl
@@ -0,0 +1,10 @@
+{"type":"system","subtype":"init","session_id":"demo-001","content":"<rules>\n<security_rules>do not exec</security_rules>\n</rules>\n<available_skills>\n<skill><name>pdf</name></skill>\n<skill><name>hermes-devflow</name></skill>\n</available_skills>"}
+{"type":"assistant","providerData":{"messageId":"msg-001"},"content":[{"type":"tool_use","name":"read_file","input":{"filePath":"README.md"}}],"usage":{"input_tokens":1820,"output_tokens":42,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"function_call_result","name":"Read","callId":"call-001","providerData":{"messageId":"msg-001"}}
+{"type":"assistant","providerData":{"messageId":"msg-002"},"content":[{"type":"tool_use","name":"use_skill","input":{"command":"pdf"}}],"usage":{"input_tokens":2100,"output_tokens":58,"cache_read_input_tokens":15300}}
+{"type":"function_call","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-002","providerData":{"messageId":"msg-002"}}
+{"type":"function_call_result","name":"Bash","callId":"call-003","providerData":{"messageId":"msg-002"}}
+{"type":"assistant","providerData":{"messageId":"msg-003"},"content":"完成","usage":{"input_tokens":2240,"output_tokens":120,"cache_read_input_tokens":15300}}
diff --git a/.cursor/skills/agent-observability/tests/test_agent_identity.py b/.cursor/skills/agent-observability/tests/test_agent_identity.py
new file mode 100644
index 00000000..664cc1dd
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_agent_identity.py
@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core.agent_identity import AgentIdentityResolver # type: ignore
+from core import state as st # type: ignore
+
+
+class AgentIdentityResolverTests(unittest.TestCase):
+ def test_extract_identity_from_send_message_json(self):
+ resolver = AgentIdentityResolver()
+ data = {
+ "tool_name": "send_message",
+ "tool_input": {
+ "content": '{"from_role":"developer","next_target":{"role_name":"leader"}}'
+ },
+ }
+ current, dispatched = resolver.extract_identity(data)
+ self.assertEqual(current, "developer")
+ self.assertEqual(dispatched, "leader")
+
+ def test_track_returns_active_and_dispatched(self):
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s2"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "developer")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("current_agent"), "developer")
+ self.assertEqual(sess.get("dispatched", {}).get("developer"), 1)
+
+ def test_track_recognizes_agent_tool_subagent_type(self):
+ """Claude Code 的 Agent 工具用 subagent_type(不是 CodeBuddy 原生 Task 的
+ subagent_name)标识派发目标;这条路径之前没有测试覆盖,_extract_from_task
+ 漏认这个字段会导致 dispatch 统计对所有 Agent 工具派发的场景失明。"""
+ resolver = AgentIdentityResolver()
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s3"
+ state_data = st.load_state(state_path)
+ st.ensure_session(state_data, sid)
+ st.save_state(state_path, state_data)
+
+ data = {
+ "tool_name": "Agent",
+ "tool_input": {"subagent_type": "worker", "description": "spawn a team"},
+ }
+ active, dispatched = resolver.track(state_path=state_path, sid=sid, data=data)
+ self.assertEqual(active, "main")
+ self.assertEqual(dispatched, "worker")
+
+ state2 = st.load_state(state_path)
+ sess = state2.get(sid, {})
+ self.assertEqual(sess.get("dispatched", {}).get("worker"), 1)
+ hist = sess.get("agent_history") or []
+ self.assertTrue(any(
+ h.get("agent") == "worker" and str(h.get("evidence") or "").startswith("dispatch")
+ for h in hist
+ ))
+
+ def test_extract_from_task_prefers_subagent_type_over_subagent_name(self):
+ resolver = AgentIdentityResolver()
+ result = resolver._extract_from_task({"subagent_type": "explorer", "subagent_name": "developer"})
+ self.assertEqual(result, "explorer")
diff --git a/.cursor/skills/agent-observability/tests/test_build_dashboard_data.py b/.cursor/skills/agent-observability/tests/test_build_dashboard_data.py
new file mode 100644
index 00000000..53b031c1
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_build_dashboard_data.py
@@ -0,0 +1,603 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+
+
+class ToolCallFailedTests(unittest.TestCase):
+ """真实 CodeBuddy CLI transcript 里从没出现过 `is_error` 这个键——实测抓到的
+ rawResponse 形如 {"exitCode": 0, "tool_error_code": "0", ...}(成功)或非 0
+ exitCode(失败)。之前只认 is_error,导致这个宿主上失败统计永远是 0。"""
+
+ def test_real_success_shape_from_codebuddy_is_not_a_failure(self):
+ # 实测数据:ls 一个不存在的路径,但命令写成了 `ls ...; echo "EXIT_CODE=$?"`,
+ # 复合命令整体 exitCode 被内层 echo 冲成了 0——工具调用本身没有失败。
+ raw_response = {
+ "exitCode": 0, "signal": None, "interrupted": False,
+ "sandboxDenied": False, "stderrBytesTruncated": 0,
+ "stdoutBytesTruncated": 0, "tool_error_code": "0",
+ }
+ self.assertFalse(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_exit_code_is_a_failure(self):
+ raw_response = {"exitCode": 1, "tool_error_code": "1"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_nonzero_tool_error_code_without_exit_code_is_a_failure(self):
+ raw_response = {"tool_error_code": "127"}
+ self.assertTrue(bdd.tool_call_failed(raw_response))
+
+ def test_legacy_is_error_flag_still_recognized(self):
+ self.assertTrue(bdd.tool_call_failed({"is_error": True}))
+
+ def test_missing_or_non_dict_raw_response_is_not_a_failure(self):
+ self.assertFalse(bdd.tool_call_failed(None))
+ self.assertFalse(bdd.tool_call_failed("not a dict"))
+ self.assertFalse(bdd.tool_call_failed({}))
+
+ def test_build_failures_and_session_status_use_exit_code(self):
+ events = [
+ {
+ "event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash",
+ "tool_details": {"raw_response": {"exitCode": 1, "tool_error_code": "1"}},
+ },
+ ]
+ failures = bdd.build_failures(events)
+ self.assertEqual(len(failures), 1)
+ self.assertEqual(failures[0]["tool"], "Bash")
+ self.assertEqual(failures[0]["code"], "1")
+
+ _, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(sessions[0]["status"], "error")
+
+
+class ResolveInputPathsTests(unittest.TestCase):
+ def setUp(self):
+ self.skill_root = Path("/tmp/fake-skill-root")
+
+ def test_defaults_fall_back_to_skill_root_logs(self):
+ metrics, state = bdd.resolve_input_paths(self.skill_root)
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_none_args_equivalent_to_empty_args(self):
+ m1, s1 = bdd.resolve_input_paths(self.skill_root, None, None)
+ m2, s2 = bdd.resolve_input_paths(self.skill_root, "", "")
+ self.assertEqual((m1, s1), (m2, s2))
+
+ def test_both_args_override(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_metrics_only_override_keeps_default_state(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "/abs/a/metrics.ndjson", None
+ )
+ self.assertEqual(metrics, Path("/abs/a/metrics.ndjson").absolute())
+ self.assertEqual(state, self.skill_root / "logs" / ".state.json")
+
+ def test_state_only_override_keeps_default_metrics(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, None, "/abs/b/.state.json"
+ )
+ self.assertEqual(metrics, self.skill_root / "logs" / "metrics.ndjson")
+ self.assertEqual(state, Path("/abs/b/.state.json").absolute())
+
+ def test_tilde_expansion(self):
+ metrics, state = bdd.resolve_input_paths(
+ self.skill_root, "~/x/metrics.ndjson", "~/y/.state.json"
+ )
+ self.assertEqual(metrics, (Path.home() / "x" / "metrics.ndjson").absolute())
+ self.assertEqual(state, (Path.home() / "y" / ".state.json").absolute())
+
+
+class MainEndToEndTests(unittest.TestCase):
+ def _run_main(self, argv: list[str]) -> None:
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ try:
+ self.assertEqual(bdd.main(), 0)
+ finally:
+ sys.argv = old_argv
+
+ def test_default_paths_unchanged_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ out = Path(td) / "dashboard-data.json"
+ self._run_main(["--project-root", td, "--out", str(out)])
+ self.assertTrue(out.is_file())
+ data = json.loads(out.read_text("utf-8"))
+ expected_metrics = str(bdd.SCRIPTS_DIR.parent / "logs" / "metrics.ndjson")
+ expected_state = str(bdd.SCRIPTS_DIR.parent / "logs" / ".state.json")
+ self.assertEqual(data["source"]["metrics_ndjson"], expected_metrics)
+ self.assertEqual(data["source"]["state_json"], expected_state)
+
+ def test_overridden_paths_read_and_reflected_in_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics_file = root / "metrics.ndjson"
+ state_file = root / ".state.json"
+ metrics_file.write_text(
+ '{"event":"usage","sid":"s1","ts":1,"tokens":{"input":10,"output":20}}\n',
+ encoding="utf-8",
+ )
+ state_file.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ out = root / "dashboard-data.json"
+
+ self._run_main([
+ "--project-root", td,
+ "--out", str(out),
+ "--metrics-path", str(metrics_file),
+ "--state-path", str(state_file),
+ ])
+ self.assertTrue(out.is_file())
+
+ data = json.loads(out.read_text("utf-8"))
+ # resolve_input_paths 对覆盖路径执行 .expanduser().absolute(),断言需对齐(macOS 下不用 .resolve() 以避免 /tmp → /private/tmp 符号链接错位)。
+ self.assertEqual(data["source"]["metrics_ndjson"], str(metrics_file.absolute()))
+ self.assertEqual(data["source"]["state_json"], str(state_file.absolute()))
+ # 覆盖文件确实被读取:metrics 行被解析进了 event_count。
+ self.assertEqual(data["source"]["event_count"], 1)
+
+
+class TopSlowTests(unittest.TestCase):
+ """`--top-slow N` 是纯增量能力:默认不开启,开启后也只往终端打印,绝不改动
+ dashboard-data.json 的结构(看板前端按字段取值,多一个字段或少一个字段都会
+ 直接影响渲染)。这些用例把"降序取前 N""非 tool 事件排除""ms 兜底""只读"
+ 四条边界钉住,避免后续有人顺手把结果写进 JSON 或改了排序方向。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 300, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Bash", "ms": 900, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 120, "agent": "main"},
+ ]
+
+ def _write_metrics(self, root: Path) -> Path:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text(
+ "\n".join(json.dumps(e) for e in self._events()) + "\n",
+ encoding="utf-8",
+ )
+ return metrics
+
+ def _run_main(self, argv: list[str]) -> str:
+ """跑一次 main() 并返回捕获到的 stdout——top-slow 的产出只体现在终端上,
+ 不体现在 JSON 里,所以断言必须落在 stdout。"""
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py"] + argv
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ return buf.getvalue()
+
+ def _printed_tools(self, stdout: str) -> list[str]:
+ tools = []
+ for line in stdout.splitlines():
+ line = line.strip()
+ if not line or not line[0].isdigit():
+ continue
+ tools.append(line.split(". ", 1)[1].split()[0])
+ return tools
+
+ def test_returns_n_slowest_tool_events_descending(self):
+ rows = bdd.build_top_slow(self._events(), 2)
+ self.assertEqual([(r["tool"], r["ms"]) for r in rows], [("Bash", 900), ("Read", 300)])
+
+ def test_limit_greater_than_event_count_returns_all_without_error(self):
+ events = [{"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 10}]
+ rows = bdd.build_top_slow(events, 99)
+ self.assertEqual(len(rows), 1)
+ self.assertEqual(rows[0]["tool"], "Bash")
+
+ def test_non_tool_events_are_excluded(self):
+ rows = bdd.build_top_slow(self._events(), 10)
+ self.assertEqual([r["tool"] for r in rows], ["Bash", "Read", "Grep"])
+ # usage 事件即使带 ms 也不能混进来。
+ self.assertTrue(all(isinstance(r["ms"], (int, float)) for r in rows))
+
+ def test_missing_or_non_numeric_ms_falls_back_to_zero(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": "120"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Grep", "ms": None},
+ {"event": "tool", "sid": "s1", "ts": 4.0, "tool": "Edit", "ms": 1},
+ ]
+ rows = bdd.build_top_slow(events, 4)
+ self.assertEqual(len(rows), 4)
+ # 非数字/缺失的 ms 一律按 0 计,不会把字符串 "120" 排到最前面。
+ self.assertEqual(sum(r["ms"] for r in rows), 1)
+
+ def test_disabled_by_default_prints_nothing_extra(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertNotIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), [])
+
+ def test_enabled_prints_tool_and_ms_descending(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ out = root / "dashboard-data.json"
+ stdout = self._run_main([
+ "--project-root", td, "--out", str(out),
+ "--metrics-path", str(metrics), "--state-path", str(root / ".state.json"),
+ "--top-slow", "2",
+ ])
+ self.assertIn("wrote ", stdout)
+ self.assertIn("top-slow", stdout)
+ self.assertEqual(self._printed_tools(stdout), ["Bash", "Read"])
+ self.assertIn("900ms", stdout)
+ self.assertNotIn("120ms", stdout) # N=2,第三名的 Grep 不该出现
+
+ def test_enabled_does_not_change_dashboard_data_structure(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ metrics = self._write_metrics(root)
+ state = root / ".state.json"
+ state.write_text(json.dumps({"s1": {"skills": {}}}), encoding="utf-8")
+ # 输出到两个不同文件再比对,避免"第二次跑覆盖了第一次"导致对比失真。
+ out_on = root / "on.json"
+ out_off = root / "off.json"
+ self._run_main([
+ "--project-root", td, "--out", str(out_on),
+ "--metrics-path", str(metrics), "--state-path", str(state), "--top-slow", "5",
+ ])
+ self._run_main([
+ "--project-root", td, "--out", str(out_off),
+ "--metrics-path", str(metrics), "--state-path", str(state),
+ ])
+ data_on = json.loads(out_on.read_text("utf-8"))
+ data_off = json.loads(out_off.read_text("utf-8"))
+ data_on.pop("generated_at")
+ data_off.pop("generated_at")
+ self.assertEqual(data_on, data_off)
+ # 兜底断言:结果没有以任何形式渗进 JSON(不只是"结构相同")。
+ self.assertNotIn("topSlow", json.dumps(data_on))
+ self.assertNotIn("top-slow", json.dumps(data_on))
+
+
+class BuildDailyAndSessionsTurnAttributionTests(unittest.TestCase):
+ """真实场景复现过:AgentLens(写 state.current_turn 的那套 tracing)关闭时,
+ tool/usage 事件自己的 turn_id 永远是 None,只有 user_prompt_submit 事件带真实
+ turn_id。修复前所有没有 turn_id 的事件会被塌缩进同一个 "?" 占位桶,看起来
+ 像"整个会话只有 1 个 turn",哪怕实际发了好几轮 prompt。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "tokens": {"input": 10, "output": 5}, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t2", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 6.0, "tool": "Edit", "ms": 80, "agent": "main"},
+ ]
+
+ def test_turns_reflect_prompt_boundaries_not_a_single_bucket(self):
+ daily, sessions = bdd.build_daily_and_sessions(self._events())
+ self.assertEqual(len(sessions), 1)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 2)
+ self.assertEqual(sess["toolCalls"], 3)
+ self.assertEqual(len(sess["timeline"]), 2)
+ turn1_tools = [e["tool"] for e in sess["timeline"][0]["events"] if e["kind"] == "tool"]
+ turn2_tools = [e["tool"] for e in sess["timeline"][1]["events"] if e["kind"] == "tool"]
+ self.assertEqual(turn1_tools, ["Bash"])
+ self.assertEqual(turn2_tools, ["Read", "Edit"])
+
+ def test_events_before_first_prompt_fall_back_to_unknown_bucket(self):
+ events = [
+ {"event": "tool", "sid": "s1", "ts": 1.0, "tool": "Bash", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 2.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Read", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ # 没有归属到任何真实 turn 的事件仍然单独成桶,不会被错误地并入第一个真实 turn。
+ self.assertEqual(len(sess["timeline"]), 2)
+ self.assertEqual(sess["timeline"][0]["turn"], 1)
+
+ def test_prompt_only_turn_with_no_tool_calls_still_appears_in_timeline(self):
+ """真实数据复现过:纯对话轮次(用户发了 prompt,但助手没有调用任何工具,
+ 也没有产生 usage 事件)之前完全不会在 timeline 里建桶——turns 计数是对的
+ (来自 user_prompt_submit 自带的 turn_id),但展开的时间线分组数会比 turns
+ 少,二者对不上。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 100, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 3.0, "turn_id": "t2", "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 4.0, "turn_id": "t3", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "Grep", "ms": 50, "agent": "main"},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["turns"], 3)
+ self.assertEqual(len(sess["timeline"]), 3)
+ self.assertEqual(sess["timeline"][1]["events"], [])
+
+ def test_prompt_only_session_still_counted_in_daily_session_count(self):
+ """真实数据复现过(TC5 当天 5 个 session,"总览"页汇总出的会话数却是 4):
+ daily["_sids"]("会话浏览"总览卡片"会话数"的数据源)之前只在 tool/usage
+ 分支里 add,一个全程只发了 prompt、没有触发任何工具调用也没有 usage 事件
+ 的 session(比如用户发了消息但被拒绝/打断,没有真正执行)会被这天的
+ sessionCount 完全漏掉——尽管 sessions 列表("会话浏览"tab)里它确实在,
+ 导致总览页"会话数"比实际能展开看到的会话数少。"""
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 50, "agent": "main"},
+ {"event": "user_prompt_submit", "sid": "s2", "ts": 3.0, "turn_id": "t1", "agent": "main"},
+ ]
+ daily, sessions = bdd.build_daily_and_sessions(events)
+ self.assertEqual(len(sessions), 2)
+ self.assertEqual(len(daily), 1)
+ self.assertEqual(daily[0]["sessionCount"], 2)
+
+
+class BuildDevflowRunsClassicSoloTests(unittest.TestCase):
+ """真实运行验证过:Classic small 任务会经过 PHASE-0 -> SOLO -> TASK-05
+ (knowledge 由 solo-developer 合并执行),不是只有 PHASE-0/SOLO 两步。"""
+
+ def test_solo_run_includes_task05_and_marks_phase0_completed(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "solo-with-knowledge_20260914_0600"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "solo-with-knowledge_20260914_0600",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ # 注意:真实 schema 里 stages{} 不含 PHASE-0 —— Phase 0 是隐式完成的。
+ "stages": {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-02": {"status": "skipped", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "skipped", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "skipped", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "skipped", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-05", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-05"], "completed")
+ self.assertEqual(stage_by_key["PHASE-0"], "completed")
+ self.assertNotIn("TASK-01", stage_by_key) # SOLO 路径不该混进 medium/large 的阶段
+
+
+class BuildDevflowRunsMediumWithLingeringSoloKeyTests(unittest.TestCase):
+ """用户反馈复现:workflow-state.json 模板固定给每次运行都写一份 SOLO stage
+ (见 assets/workflow-state-template.json 里 SOLO.description 的说明:
+ "仅当 size_class==small 时启用,否则保持 skipped"),medium/large 任务从不会
+ 真正执行它,状态停在 "pending" 或 "skipped"。修复前 `"SOLO" in stages` 只看
+ key 存不存在,不看状态,导致这类 medium 任务被误判成 solo 路径,阶段视图会用
+ CLASSIC_SOLO_ORDER 渲染,把 TASK-01/TASK-02/TASK-03/CODE-REVIEW/TASK-04 全部
+ 从 stepper 里漏掉。"""
+
+ def _run(self, solo_status: str):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ run_dir = project_root / "artifacts" / "medium-with-lingering-solo_20260915_0900"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "medium-with-lingering-solo_20260915_0900",
+ "size_class": "medium",
+ "current_stage": "TASK-03",
+ "last_event": "TASK-02_completed",
+ "stages": {
+ "SOLO": {"status": solo_status, "executor": "solo-developer", "retry_count": 0},
+ "TASK-01": {"status": "completed", "executor": "main", "retry_count": 0},
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ "CODE-REVIEW": {"status": "pending", "executor": "code-reviewer", "retry_count": 0},
+ "TASK-04": {"status": "pending", "executor": "test-engineer", "retry_count": 0},
+ "TASK-05": {"status": "pending", "executor": "knowledge-engineer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+ return bdd.build_devflow_runs(project_root)
+
+ def test_medium_run_with_skipped_solo_key_uses_full_classic_order(self):
+ runs = self._run("skipped")
+ self.assertEqual(len(runs), 1)
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ # 修复前:这里会走 CLASSIC_SOLO_ORDER,TASK-01/02/03/CODE-REVIEW/TASK-04 全部消失。
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("TASK-02", stage_by_key)
+ self.assertIn("TASK-03", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+ self.assertIn("TASK-04", stage_by_key)
+ self.assertEqual(stage_by_key["TASK-02"], "completed")
+ self.assertEqual(stage_by_key["TASK-03"], "in_progress")
+
+ def test_medium_run_with_pending_solo_key_uses_full_classic_order(self):
+ # 模板初始状态是 "pending"(不是所有实现都会显式改成 "skipped"),同样不该被判成 solo。
+ runs = self._run("pending")
+ stage_by_key = {s["key"]: s["status"] for s in runs[0]["stages"]}
+ self.assertIn("TASK-01", stage_by_key)
+ self.assertIn("CODE-REVIEW", stage_by_key)
+
+
+class BuildDevflowRunsDurationTests(unittest.TestCase):
+ """真实数据复现过:TASK-05 的 started_at 可能早于 SOLO 的 completed_at
+ (同一次 solo-developer 执行内部的子步骤,不是真正先后发生的两个阶段)。
+ total_duration 必须按真实起止跨度算,不能对逐阶段 duration 求和——否则会把
+ 重叠部分重复计入,虚高于源数据本身反映的运行时长(这次修复前是 600s,
+ 真实跨度只有 540s)。"""
+
+ def _write_state(self, project_root: Path, stages: dict) -> None:
+ run_dir = project_root / "artifacts" / "overlap-run_20260914_0620"
+ run_dir.mkdir(parents=True)
+ (run_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3",
+ "task_slug": "overlap-run_20260914_0620",
+ "size_class": "small",
+ "current_stage": "SUMMARY",
+ "last_event": "workflow_completed",
+ "stages": stages,
+ }), encoding="utf-8")
+
+ def test_total_duration_uses_true_span_not_sum_of_overlapping_stages(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ "started_at": "2026-09-14T06:20:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ "TASK-05": {
+ "status": "completed", "executor": "solo-developer", "retry_count": 0,
+ # 早于 SOLO 的 completed_at —— 真实数据里观测到的重叠场景。
+ "started_at": "2026-09-14T06:28:00Z", "completed_at": "2026-09-14T06:29:00Z",
+ },
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(len(runs), 1)
+ # 真实跨度是 06:20~06:29 = 540s,不是 540+60=600s。
+ self.assertEqual(runs[0]["duration"], 540)
+ stage_by_key = {s["key"]: s["duration"] for s in runs[0]["stages"]}
+ # 单个阶段自身的 duration 不受影响,仍然如实反映各自的起止跨度。
+ self.assertEqual(stage_by_key["SOLO"], 540)
+ self.assertEqual(stage_by_key["TASK-05"], 60)
+
+ def test_total_duration_is_zero_when_no_stage_has_valid_timestamps(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_root = Path(td)
+ self._write_state(project_root, {
+ "SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ "TASK-05": {"status": "completed", "executor": "solo-developer", "retry_count": 0},
+ })
+ runs = bdd.build_devflow_runs(project_root)
+ self.assertEqual(runs[0]["duration"], 0)
+
+
+class BuildDailyAndSessionsPerEventAgentTests(unittest.TestCase):
+ """真实数据复现过(TC5,size_class=small 但走了真实 team_create/send_message
+ 派发):同一个 sid 下,metrics.ndjson 的 tool/usage 事件本来就各自带着准确的
+ agent 字段(一次真实会话里 66 条 main、64 条 solo-developer),但展开进
+ timeline 的每条 event 字典只有 kind/tool/ms/err,从不写回 agent —— 时间线里
+ 完全看不出某次工具调用到底是 main 自己做的还是派发给 solo-developer 后做的,
+ 等于白白丢弃了上游已经采集到的数据。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Agent", "ms": 50, "agent": "main"},
+ {"event": "tool", "sid": "s1", "ts": 3.0, "tool": "Bash", "ms": 100, "agent": "solo-developer"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "tokens": {"input": 10, "output": 5}, "agent": "solo-developer"},
+ {"event": "tool", "sid": "s1", "ts": 5.0, "tool": "SendMessage", "ms": 30, "agent": "main"},
+ ]
+
+ def test_timeline_events_carry_the_agent_that_actually_ran_them(self):
+ _, sessions = bdd.build_daily_and_sessions(self._events())
+ sess = sessions[0]
+ events = sess["timeline"][0]["events"]
+ by_tool = {e.get("tool"): e for e in events if e["kind"] == "tool"}
+ self.assertEqual(by_tool["Agent"]["agent"], "main")
+ self.assertEqual(by_tool["Bash"]["agent"], "solo-developer")
+ self.assertEqual(by_tool["SendMessage"]["agent"], "main")
+ usage_events = [e for e in events if e["kind"] == "usage"]
+ self.assertEqual(usage_events[0]["agent"], "solo-developer")
+
+ def test_missing_agent_on_raw_event_falls_back_to_main(self):
+ events = [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1"},
+ {"event": "tool", "sid": "s1", "ts": 2.0, "tool": "Read", "ms": 10},
+ ]
+ _, sessions = bdd.build_daily_and_sessions(events)
+ sess = sessions[0]
+ self.assertEqual(sess["timeline"][0]["events"][0]["agent"], "main")
+
+
+class BuildDispatchTests(unittest.TestCase):
+ """真实数据复现过(TC5 的 dashboard-data-top-slow 会话,sid 01a09ef5...):
+ 修复前 build_dispatch() 把 agent_history 里所有 evidence 以 "dispatch" 或
+ "inbox" 开头的条目一律计数,导致两个真实问题——
+ 1) solo-developer 被上报回声(inbox@report:*)重复计入,真实派发只有 2 次,
+ 却显示成 5;
+ 2) team-lead 显示成一个"被 main 派发的子 agent",但 team-lead 在
+ core/agent_identity.py::normalize_role_name 里本来就和 main 归为一类
+ (它是 CodeBuddy 原生 team 基础设施里 lead session 自己的 mailbox 名,
+ 不是真实存在的子 agent),面板标题明明叫"Main → 子 Agent 派发次数",
+ 混进一个其实等价于 main 自己的假子 agent。"""
+
+ def _real_tc5_agent_history(self):
+ # 逐条取自真实会话 01a09ef5-1c6b-7928-870e-a5056ff360e1 的 .state.json。
+ return [
+ {"ts": 1.0, "agent": "solo-developer", "evidence": "dispatch@Agent<-main"},
+ {"ts": 2.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 3.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ {"ts": 4.0, "agent": "solo-developer", "evidence": "inbox@dispatch:solo-developer"},
+ {"ts": 5.0, "agent": "main", "evidence": "dispatch@SendMessage<-solo-developer"},
+ {"ts": 6.0, "agent": "main", "evidence": "inbox@handoff:solo-developer->main"},
+ {"ts": 7.0, "agent": "solo-developer", "evidence": "dispatch@SendMessage<-main"},
+ {"ts": 8.0, "agent": "solo-developer", "evidence": "inbox@report:solo-developer"},
+ ]
+
+ def test_real_tc5_history_excludes_team_lead_and_report_echoes(self):
+ state = {"01a09ef5": {"agent_history": self._real_tc5_agent_history()}}
+ rows = bdd.build_dispatch(state)
+ # team-lead(main 的别名)完全不出现;solo-developer 只数真正代表新派发的
+ # 3 条证据(2 条工具触发的 dispatch@ + 1 条 inbox 独立确认的 dispatch:),
+ # 2 条上报回声(inbox@report:*)不计入。
+ self.assertEqual(rows, [{"agent": "solo-developer", "count": 3}])
+
+ def test_inbox_dispatch_evidence_alone_is_still_counted(self):
+ """inbox 扫描独立确认的 "main 派给了谁"(inbox@dispatch:*)是原生 team
+ 基础设施里唯一能感知到、但没有经过 Agent/Task 工具调用拦截到的派发方式
+ (例如 team-lead 用 mailbox 直接投递任务),必须保留,不能因为过滤
+ report/handoff 回声就连这类真实派发信号也一起丢掉。"""
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "architect", "evidence": "inbox@dispatch:architect"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [{"agent": "architect", "count": 1}])
+
+ def test_report_and_handoff_evidence_alone_are_not_dispatches(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "developer", "evidence": "inbox@report:developer"},
+ {"ts": 2.0, "agent": "test-engineer", "evidence": "inbox@handoff:developer->test-engineer"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+ def test_team_lead_is_excluded_even_without_report_noise(self):
+ state = {"s1": {"agent_history": [
+ {"ts": 1.0, "agent": "team-lead", "evidence": "dispatch@SendMessage<-main"},
+ ]}}
+ rows = bdd.build_dispatch(state)
+ self.assertEqual(rows, [])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.cursor/skills/agent-observability/tests/test_cls_sink.py b/.cursor/skills/agent-observability/tests/test_cls_sink.py
new file mode 100644
index 00000000..2da9d6a1
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_cls_sink.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import cls_sink, emitter # type: ignore
+
+
+class CLSSinkTests(unittest.TestCase):
+ def _write_cls_env(self, root: Path, *extra_lines: str) -> None:
+ lines = [
+ "CLS_TOPIC_ID=test-topic-id",
+ "CLS_ENDPOINT=cls.internal.tencentcloudapi.com",
+ "CLS_SERVICE_NAME=agent-observability",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=20",
+ *extra_lines,
+ ]
+ (root / ".env").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+ def test_load_config_supports_cls_and_tc_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "TC_SECRET_ID=test-secret-id",
+ "TC_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertTrue(config.enabled)
+ self.assertEqual(config.endpoint, "cls.internal.tencentcloudapi.com")
+ self.assertEqual(config.topic_id, "test-topic-id")
+ self.assertEqual(config.secret_id, "test-secret-id")
+ self.assertEqual(config.secret_key, "test-secret-key")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.service_name, "agent-observability")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_load_config_supports_tencentcloud_scoped_credentials(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(
+ os.environ,
+ {
+ "TENCENTCLOUD_SECRET_ID_438167613": "scoped-secret-id",
+ "TENCENTCLOUD_SECRET_KEY_438167613": "scoped-secret-key",
+ },
+ clear=True,
+ ):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "scoped-secret-id")
+ self.assertEqual(config.secret_key, "scoped-secret-key")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertTrue(config.ready)
+
+ def test_mirror_record_invokes_node_uploader(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=0, stdout="", stderr="")) as run, \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-1"}, cwd=td)
+
+ self.assertTrue(ok)
+ run.assert_called_once()
+ payload = json.loads(run.call_args.kwargs["input"])
+ self.assertEqual(payload["records"][0]["event"], "tool")
+ self.assertEqual(payload["topicId"], "test-topic-id")
+ self.assertEqual(payload["secretToken"], "")
+
+ def test_load_config_requires_credentials_from_env(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(root)
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_id, "")
+ self.assertEqual(config.secret_key, "")
+ self.assertEqual(config.secret_token, "")
+ self.assertEqual(config.timeout_seconds, 20)
+ self.assertFalse(config.ready)
+
+ def test_load_config_reads_secret_token_aliases(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "TC_SESSION_TOKEN=test-session-token",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.secret_token, "test-session-token")
+
+ def test_load_config_supports_timeout_override(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ "CLS_UPLOAD_TIMEOUT_SECONDS=45",
+ )
+ with mock.patch.dict(os.environ, {}, clear=True):
+ config = cls_sink.load_config(td)
+
+ self.assertEqual(config.timeout_seconds, 45)
+
+ def test_mirror_record_writes_debug_when_uploader_fails(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(False, "python-failed")), \
+ mock.patch.object(cls_sink.subprocess, "run", return_value=mock.Mock(returncode=1, stdout="", stderr="boom")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-2"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertFalse(ok)
+ self.assertEqual(entries[-1]["stage"], "uploader_failed")
+ self.assertEqual(entries[-1]["stderr"], "boom")
+ self.assertEqual(entries[-1]["timeout_seconds"], 20)
+
+ def test_mirror_record_writes_success_debug_when_uploader_succeeds(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ debug_path = root / "cls-push-debug.ndjson"
+ self._write_cls_env(
+ root,
+ "CLS_SECRET_ID=test-secret-id",
+ "CLS_SECRET_KEY=test-secret-key",
+ )
+ with mock.patch.object(cls_sink, "debug_log_path", return_value=debug_path), \
+ mock.patch.object(cls_sink, "_put_logs_via_api", return_value=(True, "ok")), \
+ mock.patch.dict(os.environ, {}, clear=True):
+ ok = cls_sink.mirror_record({"event": "tool", "sid": "s-3"}, cwd=td)
+
+ entries = [json.loads(line) for line in debug_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertTrue(ok)
+ self.assertEqual(entries[0]["stage"], "uploader_start")
+ self.assertEqual(entries[-1]["stage"], "uploader_ok")
+ self.assertEqual(entries[-1]["method"], "python_api_v3")
+
+ def test_emit_keeps_local_log_when_cls_push_raises(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+ with mock.patch.object(emitter.cls_sink, "mirror_record", side_effect=RuntimeError("boom")):
+ emitter.emit(log_path, {"event": "start", "sid": "s-emit"})
+
+ records = [json.loads(line) for line in log_path.read_text("utf-8").splitlines() if line.strip()]
+
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0]["event"], "start")
+ self.assertEqual(records[0]["sid"], "s-emit")
diff --git a/.cursor/skills/agent-observability/tests/test_collector.py b/.cursor/skills/agent-observability/tests/test_collector.py
new file mode 100644
index 00000000..05547f06
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_collector.py
@@ -0,0 +1,715 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, agentlens, collector, emitter, runtime, state as st # type: ignore
+
+
+class CollectorTests(unittest.TestCase):
+ def test_cost_of_uses_known_model_price_table(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ cost = emitter.cost_of(tokens, "gpt-4o")
+ self.assertIsNotNone(cost)
+ self.assertGreaterEqual(cost, 0.0)
+
+ def test_cost_of_returns_none_for_unknown_model(self):
+ tokens = {"input": 1000, "output": 200, "cache_read": 0, "total": 1200}
+ self.assertIsNone(emitter.cost_of(tokens, "unknown-model"))
+
+ def test_emit_adds_codebuddy_cli_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "codebuddy-cli")
+
+ def test_emit_preserves_explicit_data_source(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-data-source", "data_source": "manual"})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["data_source"], "manual")
+
+ def test_emit_session_duration_uses_first_log_ts_when_state_was_recreated(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ log_path = root / "metrics.ndjson"
+ state_path = root / ".state.json"
+ log_path.write_text(
+ json.dumps({"event": "start", "sid": "s-duration", "ts": 100.0}) + "\n",
+ encoding="utf-8",
+ )
+ state_path.write_text(
+ json.dumps({"s-duration": {"started_at": 190.0}}, ensure_ascii=False),
+ encoding="utf-8",
+ )
+
+ emitter.emit(log_path, {"event": "usage", "sid": "s-duration", "ts": 200.0, "tokens": {"input": 1, "output": 2}})
+
+ records = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
+ self.assertEqual(records[-1]["session_duration_sec"], 100.0)
+
+ def test_emit_session_duration_starts_at_zero_without_prior_log_or_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ log_path = Path(td) / "metrics.ndjson"
+
+ emitter.emit(log_path, {"event": "start", "sid": "s-new", "ts": 100.0})
+
+ record = json.loads(log_path.read_text(encoding="utf-8").strip())
+ self.assertEqual(record["session_duration_sec"], 0.0)
+
+ def test_parse_transcript_tail_extracts_tokens(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ out = collector.parse_transcript_tail(str(transcript), max_lines=20)
+ self.assertIsInstance(out, dict)
+ self.assertIsInstance(out.get("tokens"), dict)
+ self.assertEqual(out["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(out["tokens"].get("output_tokens"), 120)
+ usage_records = out.get("usage_records") or []
+ tool_records = out.get("tool_records") or []
+ self.assertEqual(len(usage_records), 3)
+ self.assertEqual(usage_records[0]["tokens"].get("input_tokens"), 1820)
+ self.assertEqual(usage_records[-1]["tokens"].get("input_tokens"), 2240)
+ self.assertEqual(usage_records[0].get("message_id"), "msg-001")
+ self.assertEqual(usage_records[-1].get("message_id"), "msg-003")
+ self.assertLess(usage_records[0]["offset"], usage_records[-1]["offset"])
+ self.assertEqual(len(tool_records), 8)
+ self.assertEqual(tool_records[0]["tool"], "read_file")
+ self.assertEqual(tool_records[0]["message_id"], "msg-001")
+ self.assertEqual(tool_records[0]["next_message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["tool"], "Bash")
+ self.assertEqual(tool_records[-1]["message_id"], "msg-002")
+ self.assertEqual(tool_records[-1]["next_message_id"], "msg-003")
+
+ def test_realtime_usage_is_request_level_and_dedupes_across_phase(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-transcript"
+
+ scan = collector.collect_transcript_entries(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=str(transcript),
+ max_lines=20,
+ )
+ entries = scan.get("entries") or []
+
+ self.assertEqual(len(entries), 3)
+ self.assertEqual(entries[0]["tokens"]["input"], 1820)
+ self.assertGreater(entries[0]["offset"], 0)
+ self.assertEqual(entries[0]["message_id"], "msg-001")
+ self.assertEqual(entries[1]["tokens"]["input"], 2100)
+ self.assertEqual(entries[1]["tokens"]["total"], 2158)
+ self.assertEqual(len(scan.get("tool_records") or []), 8)
+
+ usage_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Read",
+ entry=entries[0],
+ )
+ stop_key = collector.build_transcript_event_key(
+ kind="stop",
+ tool="__stop__",
+ entry=entries[0],
+ )
+ other_tool_key = collector.build_transcript_event_key(
+ kind="usage",
+ tool="Bash",
+ entry=entries[0],
+ )
+
+ self.assertEqual(usage_key, stop_key)
+ self.assertEqual(usage_key, other_tool_key)
+ self.assertTrue(st.claim_transcript_event(state_path, sid, usage_key, str(transcript)))
+ self.assertFalse(st.claim_transcript_event(state_path, sid, stop_key, str(transcript)))
+
+ def test_find_current_tool_message_id_prefers_transcript_tool_records(self):
+ transcript = ROOT / "tests" / "fixtures" / "transcript.jsonl"
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool-mid"
+
+ read_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Read",
+ )
+ bash_mid = collector.find_current_tool_message_id(
+ state_path,
+ sid,
+ str(transcript),
+ "Bash",
+ )
+
+ self.assertEqual(read_mid, "msg-002")
+ self.assertEqual(bash_mid, "msg-003")
+
+ def test_resolve_subagent_transcript_alias_and_tool_context(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ alias_session_id = "subagent-session-1"
+ subagent = subagents / "agent-a.jsonl"
+ main.write_text("", encoding="utf-8")
+ subagent.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "type": "message",
+ "sessionId": alias_session_id,
+ "providerData": {"agent": "Explore"},
+ }
+ ),
+ json.dumps(
+ {
+ "type": "function_call",
+ "sessionId": alias_session_id,
+ "name": "Grep",
+ "callId": "call-1",
+ "providerData": {
+ "agent": "Explore",
+ "messageId": "msg-sub-001",
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ aliased_path = str(root / f"{alias_session_id}.jsonl")
+ resolved = collector.resolve_transcript_path_alias(sid, aliased_path)
+ self.assertEqual(resolved, str(subagent.resolve()))
+
+ state_path = root / ".state.json"
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid=sid,
+ transcript_path=aliased_path,
+ tool_name="Grep",
+ )
+ self.assertEqual(
+ context,
+ {
+ "message_id": "msg-sub-001",
+ "transcript_path": str(subagent.resolve()),
+ "agent": "explore",
+ "tool_details": {"call_id": "call-1"},
+ },
+ )
+
+ def test_find_current_tool_context_prefers_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ early = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=1.2,
+ )
+ late = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-nearest",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(early["message_id"], "msg-early")
+ self.assertEqual(late["message_id"], "msg-late")
+
+ def test_find_current_tool_context_claims_distinct_call_ids_with_same_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "arguments": "{\"command\":\"echo one\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-2",
+ "arguments": "{\"command\":\"echo two\"}",
+ "providerData": {"messageId": "msg-shared"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result one"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-2",
+ "providerData": {
+ "messageId": "msg-shared",
+ "toolResult": {"content": "result two"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ first = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ second = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+ third = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-claim-shared",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ event_ts=4.9,
+ claim=True,
+ )
+
+ self.assertEqual(first["message_id"], "msg-shared")
+ self.assertEqual(second["message_id"], "msg-shared")
+ self.assertNotEqual(first["tool_details"]["call_id"], second["tool_details"]["call_id"])
+ self.assertIn("arguments", first["tool_details"])
+ self.assertIn("result_content", first["tool_details"])
+ self.assertEqual(third, {"duplicate": True})
+
+ def test_find_fallback_usage_event_prefers_latest_matching_usage(self):
+ tool_event = {
+ "tool": "Bash",
+ "agent": "main",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ usage_events = [
+ {
+ "agent": "main",
+ "tool": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-old",
+ "source_offset": 100,
+ },
+ {
+ "agent": "main",
+ "tool": "Bash",
+ "transcript_path": "/tmp/demo.jsonl",
+ "message_id": "msg-current",
+ "source_offset": 200,
+ },
+ ]
+
+ matched = collector.find_fallback_usage_event(tool_event, usage_events)
+ self.assertIsNotNone(matched)
+ self.assertEqual(matched["message_id"], "msg-current")
+
+ def test_find_current_tool_context_prefers_explicit_call_id_over_nearest_timestamp(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {"messageId": "msg-early"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-early",
+ "providerData": {
+ "messageId": "msg-early",
+ "toolResult": {"content": "early result"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5000,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {"messageId": "msg-late"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 5001,
+ "type": "function_call_result",
+ "name": "Bash",
+ "callId": "call-late",
+ "providerData": {
+ "messageId": "msg-late",
+ "toolResult": {"content": "late result"},
+ },
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-call-id-priority",
+ transcript_path=str(transcript),
+ tool_name="Bash",
+ call_id="call-early",
+ event_ts=4.9,
+ )
+
+ self.assertEqual(context["message_id"], "msg-early")
+ self.assertEqual(context["tool_details"]["call_id"], "call-early")
+ self.assertEqual(context["tool_details"]["result_content"], "early result")
+
+ def test_find_current_tool_context_uses_next_message_id_when_available(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ transcript = root / "session.jsonl"
+ transcript.write_text(
+ "\n".join(
+ [
+ json.dumps(
+ {
+ "timestamp": 1000,
+ "type": "function_call",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-tool"},
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 1001,
+ "type": "function_call_result",
+ "name": "Read",
+ "callId": "call-1",
+ "providerData": {
+ "messageId": "msg-tool",
+ "toolResult": {"content": "<tool_use_error>missing</tool_use_error>"},
+ },
+ }
+ ),
+ json.dumps(
+ {
+ "timestamp": 2000,
+ "type": "assistant",
+ "providerData": {"messageId": "msg-next"},
+ "content": "next step",
+ }
+ ),
+ ]
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ state_path = root / ".state.json"
+
+ context = collector.find_current_tool_context(
+ state_path=state_path,
+ sid="s-next-mid",
+ transcript_path=str(transcript),
+ tool_name="Read",
+ call_id="call-1",
+ )
+
+ self.assertEqual(context["message_id"], "msg-next")
+ self.assertEqual(context["tool_details"]["original_message_id"], "msg-tool")
+ self.assertEqual(context["tool_details"]["next_message_id"], "msg-next")
+ self.assertTrue(context["tool_details"]["message_id_reassigned"])
+
+ def test_flush_pending_tool_events_emits_after_transcript_catches_up(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ state_path = root / ".state.json"
+ log_path = root / "metrics.ndjson"
+ transcript = root / "session.jsonl"
+ transcript.write_text("", encoding="utf-8")
+ sid = "s-pending"
+
+ tool_event = {
+ "event": "tool",
+ "sid": sid,
+ "agent": "main",
+ "tool": "Bash",
+ "ms": 42,
+ "transcript_path": str(transcript),
+ "turn_id": "turn-1",
+ "ts": 1.2,
+ "skill": [],
+ "rule": [],
+ "cwd": str(ROOT),
+ }
+ st.append_pending_tool_emit(state_path, sid, tool_event)
+
+ transcript.write_text(
+ json.dumps(
+ {
+ "timestamp": 1300,
+ "type": "function_call",
+ "name": "Bash",
+ "callId": "call-1",
+ "providerData": {"messageId": "msg-later"},
+ }
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+
+ emitted_calls: list[dict[str, object]] = []
+ original_emit_post_step = agentlens.emit_post_step
+ try:
+ agentlens.emit_post_step = lambda **kwargs: emitted_calls.append(kwargs)
+ runtime.flush_pending_tool_events(
+ state_path=state_path,
+ log_path=log_path,
+ sid=sid,
+ )
+ finally:
+ agentlens.emit_post_step = original_emit_post_step
+
+ self.assertEqual(st.get_pending_tool_emits(state_path, sid), [])
+ lines = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines() if line.strip()]
+ self.assertEqual(len(lines), 1)
+ self.assertEqual(lines[0]["message_id"], "msg-later")
+ self.assertEqual(len(emitted_calls), 1)
+ self.assertEqual(emitted_calls[0]["tool_event"]["message_id"], "msg-later")
+
+ def test_related_transcript_paths_include_subagents(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ sid = "session-123"
+ main = root / f"{sid}.jsonl"
+ bundle = root / sid
+ subagents = bundle / "subagents"
+ subagents.mkdir(parents=True)
+ sub_a = subagents / "agent-a.jsonl"
+ sub_b = subagents / "agent-b.jsonl"
+ for path in (main, sub_a, sub_b):
+ path.write_text("", encoding="utf-8")
+
+ paths = collector.related_transcript_paths(sid, str(main))
+
+ self.assertEqual(
+ paths,
+ [
+ str(main.resolve()),
+ str(sub_a.resolve()),
+ str(sub_b.resolve()),
+ ],
+ )
+
+ def test_subagent_transcript_maps_to_role_name(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-27e41af0.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for knowledge-engineer\\">"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "knowledge-engineer",
+ )
+
+ def test_subagent_transcript_prefers_assignment_role_over_general_provider_agent(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ subagent = root / "subagents" / "agent-165e361f.jsonl"
+ subagent.parent.mkdir(parents=True)
+ subagent.write_text(
+ '{"type":"message","providerData":{"agent":"general-purpose"},"content":[{"text":"<teammate-message teammate_id=\\"team-lead\\" summary=\\"Initial task assignment for developer\\">\\n待命。\\n你在本 devflow 中的角色:developer(开发角色)"}]}\n',
+ encoding="utf-8",
+ )
+
+ self.assertEqual(
+ agent_identity.agent_for_transcript_path(str(subagent), "main"),
+ "developer",
+ )
+
+ def test_inbox_standby_assignment_does_not_switch_current_agent(self):
+ messages = [
+ {
+ "mailbox_name": "architect",
+ "mailbox_role": "architect",
+ "from_role": "main",
+ "summary": "Initial task assignment for architect",
+ "text": "待命,监听 main 唤醒。",
+ "payload": None,
+ "is_shutdown": False,
+ "is_standby": True,
+ }
+ ]
+ current, dispatched, meta = agent_identity.infer_identity_from_messages(messages)
+ self.assertIsNone(current)
+ self.assertIsNone(dispatched)
+ self.assertEqual(meta["messages_seen"], 1)
+
+ def test_record_pre_post_duration(self):
+ with tempfile.TemporaryDirectory() as td:
+ pending = Path(td) / ".pending.json"
+ pre = {"session_id": "s1", "tool_name": "read_file"}
+ post = {"session_id": "s1", "tool_name": "read_file"}
+ collector.record_pre(pending, pre)
+ time.sleep(0.02)
+ ms = collector.record_post(pending, post)
+ self.assertIsInstance(ms, int)
+ self.assertGreaterEqual(ms, 0)
+
+ def test_record_tool_usage_counts_skill_and_rule(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-tool"
+ # 先确保 session 结构
+ s = st.load_state(state_path)
+ st.ensure_session(s, sid)
+ st.save_state(state_path, s)
+
+ data = {
+ "tool_name": "use_skill",
+ "tool_input": {"command": "pdf", "filePath": "README.md"},
+ }
+ skills_meta = {"pdf": {"source": "user", "version": "1.0.0"}}
+ rules_meta = {
+ "security": {"source": "project", "alwaysApply": True, "enabled": True, "globs": []}
+ }
+ collector.record_tool_usage(
+ state_path=state_path,
+ sid=sid,
+ data=data,
+ skills_meta=skills_meta,
+ rules_meta=rules_meta,
+ active_agent="main",
+ collect_skills=True,
+ )
+
+ skills_usage, rules_usage = collector.get_session_usage(state_path, sid)
+ self.assertEqual(skills_usage.get("pdf", {}).get("count"), 1)
+ self.assertEqual(rules_usage.get("security", {}).get("count"), 1)
+
+ def test_step_span_registry_is_idempotent(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ sid = "s-step"
+ carrier = {"traceparent": "00-" + ("1" * 32) + "-" + ("2" * 16) + "-01"}
+ st.begin_turn(state_path, sid, "turn-1", carrier)
+
+ first = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("3" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+ second = st.upsert_step_span(
+ state_path,
+ sid,
+ "main",
+ "msg-001",
+ {"traceparent": "00-" + ("1" * 32) + "-" + ("4" * 16) + "-01"},
+ transcript_path="/tmp/demo.jsonl",
+ )
+
+ self.assertEqual(first, second)
+ self.assertEqual(st.get_step_span_carrier(state_path, sid, "main", "msg-001"), first)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.cursor/skills/agent-observability/tests/test_devflow.py b/.cursor/skills/agent-observability/tests/test_devflow.py
new file mode 100644
index 00000000..9ad0a7fd
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_devflow.py
@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import agent_identity, devflow, state as st # type: ignore
+
+
+def _write_team_config(team_dir: Path, *, lead_session_id: str, member_cwd: str) -> None:
+ team_dir.mkdir(parents=True, exist_ok=True)
+ (team_dir / "config.json").write_text(
+ json.dumps({
+ "leadSessionId": lead_session_id,
+ "createdAt": 1,
+ "members": [{"cwd": member_cwd}],
+ }),
+ encoding="utf-8",
+ )
+
+
+class TaskSlugFromTeamDirTests(unittest.TestCase):
+ def test_strips_fixed_prefix(self):
+ team_dir = Path("/tmp/.codebuddy/teams/multi-agents-devflow-my-task_20260911_1200")
+ self.assertEqual(devflow.task_slug_from_team_dir(team_dir), "my-task_20260911_1200")
+
+ def test_returns_none_for_non_devflow_team_dir(self):
+ team_dir = Path("/tmp/.codebuddy/teams/some-other-team")
+ self.assertIsNone(devflow.task_slug_from_team_dir(team_dir))
+
+
+class StageSnapshotTests(unittest.TestCase):
+ def test_projects_expected_fields_and_ignores_non_dict_stage(self):
+ workflow_state = {
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "run_mode": "auto",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0, "review_result": None},
+ "CODE-REVIEW": {"status": "failed", "executor": "code-reviewer", "retry_count": 1, "review_result": "failed"},
+ "garbage": "not-a-dict",
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["current_stage"], "TASK-03")
+ self.assertEqual(snap["size_class"], "medium")
+ self.assertNotIn("garbage", snap["stages"])
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["retry_count"], 1)
+ self.assertEqual(snap["stages"]["CODE-REVIEW"]["review_result"], "failed")
+
+ def test_handles_missing_or_malformed_input(self):
+ self.assertEqual(devflow.stage_snapshot(None), {})
+ self.assertEqual(devflow.stage_snapshot({"stages": "not-a-dict"}), {
+ "current_stage": None, "size_class": None, "run_mode": None,
+ "schema_version": None, "execution_mode": None, "host_adapter": None, "run_id": None,
+ "stages": {},
+ })
+
+
+class DiffStageChangesTests(unittest.TestCase):
+ def test_first_observation_produces_no_changes(self):
+ curr = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(None, curr), [])
+
+ def test_detects_retry_count_increase_as_a_change(self):
+ prev = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "in_progress", "retry_count": 0}}})
+ curr = devflow.stage_snapshot({"stages": {"CODE-REVIEW": {"status": "failed", "retry_count": 1, "review_result": "failed"}}})
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "CODE-REVIEW")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["review_result"], "failed")
+
+ def test_unchanged_stage_produces_no_entry(self):
+ snap = devflow.stage_snapshot({"stages": {"TASK-02": {"status": "completed", "retry_count": 0}}})
+ self.assertEqual(devflow.diff_stage_changes(snap, snap), [])
+
+
+class PtIdFromTranscriptPathTests(unittest.TestCase):
+ def test_extracts_pt_track_from_subagent_transcript_name(self):
+ path = "/tmp/session-123/subagents/sub-developer-PT-01.jsonl"
+ self.assertEqual(agent_identity.pt_id_from_transcript_path(path), "PT-01")
+
+ def test_returns_none_for_non_subagent_or_non_pt_transcript(self):
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123.jsonl"))
+ self.assertIsNone(agent_identity.pt_id_from_transcript_path("/tmp/session-123/subagents/architect.jsonl"))
+
+
+class ResolveAndDiffTests(unittest.TestCase):
+ def test_returns_none_when_no_devflow_team_found(self):
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ result = devflow.resolve_and_diff(state_path, "sid-1", "/tmp/some-project")
+ self.assertIsNone(result)
+ state = st.load_state(state_path)
+ self.assertIsNone(state["sid-1"]["_devflow"]["context"])
+
+ def test_late_appearing_devflow_run_is_discovered_on_a_later_call(self):
+ """真实 bug 回归测试:同一个长生命周期 sid,会话开始时探测不到 devflow
+ (此时既没有 team 目录也没有 artifacts/),之后才真正跑起 devflow
+ (比如通过 Agent 工具后台 spawn,而不是从一开始就是独立 team 成员 sid)。
+ 早期的"没找到"不能被永久缓存,必须在 artifacts/ 出现之后的下一次调用里发现它。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ project_dir.mkdir()
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-long-lived"
+
+ # 会话早期:还没有任何 devflow 痕迹。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNone(first)
+
+ # 同一个 sid,会话中途才出现 devflow 产物(没有 team 目录,走 artifacts 扫描兜底)。
+ artifacts_dir = project_dir / "artifacts" / "late-appearing-task_20260914_1200"
+ artifacts_dir.mkdir(parents=True)
+ (artifacts_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "current_stage": "SOLO", "size_class": "small",
+ "stages": {"SOLO": {"status": "completed", "executor": "solo-developer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(second)
+ self.assertEqual(second["task_slug"], "late-appearing-task_20260914_1200")
+
+ def test_end_to_end_with_fake_team_and_workflow_state(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ project_dir = root / "project"
+ project_dir.mkdir()
+ config_home = root / "codebuddy-home"
+ teams_root = config_home / "teams"
+ team_dir = teams_root / "multi-agents-devflow-fix-token-bypass_20260911_0900"
+ _write_team_config(team_dir, lead_session_id="sid-42", member_cwd=str(project_dir))
+
+ artifacts_dir = project_dir / "artifacts" / "fix-token-bypass_20260911_0900"
+ artifacts_dir.mkdir(parents=True)
+ workflow_state_path = artifacts_dir / "workflow-state.json"
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "in_progress", "executor": "developer", "retry_count": 0},
+ },
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(config_home)
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-42"
+
+ # 第一次调用:发现 devflow 上下文,但因为是首次观测不产出 changes。
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "fix-token-bypass_20260911_0900")
+ self.assertEqual(first["current_stage"], "TASK-03")
+ self.assertEqual(first["changes"], [])
+
+ # workflow-state.json 更新:TASK-03 打回重试。
+ workflow_state_path.write_text(json.dumps({
+ "current_stage": "TASK-03",
+ "size_class": "medium",
+ "stages": {
+ "TASK-02": {"status": "completed", "executor": "architect", "retry_count": 0},
+ "TASK-03": {"status": "failed", "executor": "developer", "retry_count": 1},
+ },
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["stage"], "TASK-03")
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+
+ # 没有变化时,第三次调用应该不再产出 changes。
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["changes"], [])
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+class PortableSchemaStageSnapshotTests(unittest.TestCase):
+ """Portable(v2.0)用 `executor_role` 而不是 `executor`,且没有 `review_result`。"""
+
+ def test_reads_executor_role_and_top_level_execution_context(self):
+ workflow_state = {
+ "version": "2.0",
+ "current_stage": "IMPLEMENT",
+ "size_class": "medium",
+ "execution_mode": "isolated",
+ "host_adapter": "codebuddy",
+ "run_id": "run-abc",
+ "stages": {
+ "DESIGN": {"status": "completed", "executor_role": "devflow-architect", "retry_count": 0},
+ "IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1},
+ },
+ }
+ snap = devflow.stage_snapshot(workflow_state)
+ self.assertEqual(snap["schema_version"], "2.0")
+ self.assertEqual(snap["execution_mode"], "isolated")
+ self.assertEqual(snap["stages"]["DESIGN"]["executor"], "devflow-architect")
+ self.assertEqual(snap["stages"]["IMPLEMENT"]["retry_count"], 1)
+ self.assertIsNone(snap["stages"]["IMPLEMENT"]["review_result"])
+
+ def test_diff_detects_retry_on_portable_shape_same_as_classic(self):
+ prev = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "in_progress", "executor_role": "devflow-developer", "retry_count": 0}},
+ })
+ curr = devflow.stage_snapshot({
+ "version": "2.0",
+ "stages": {"IMPLEMENT": {"status": "failed", "executor_role": "devflow-developer", "retry_count": 1}},
+ })
+ changes = devflow.diff_stage_changes(prev, curr)
+ self.assertEqual(len(changes), 1)
+ self.assertEqual(changes[0]["stage"], "IMPLEMENT")
+ self.assertEqual(changes[0]["retry_count"], 1)
+ self.assertEqual(changes[0]["executor"], "devflow-developer")
+
+
+class ArtifactsScanFallbackTests(unittest.TestCase):
+ """`topology: spawn` 宿主没有 team 目录,靠扫 artifacts/ 兜底发现 task_slug。"""
+
+ def test_no_artifacts_dir_returns_none(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.assertIsNone(devflow._scan_artifacts_for_active_run(td))
+
+ def test_ignores_non_devflow_json_and_picks_in_progress_run(self):
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ # 不是 devflow 产物的 JSON(没有 stages 字段),不能被误当成一次运行。
+ noise_dir = artifacts / "not-a-devflow-run"
+ noise_dir.mkdir(parents=True)
+ (noise_dir / "workflow-state.json").write_text(json.dumps({"hello": "world"}), encoding="utf-8")
+
+ done_dir = artifacts / "finished-task_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "completed", "stages": {"DESIGN": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "active-task_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "status": "in_progress", "stages": {"IMPLEMENT": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "active-task_20260911_1000")
+ self.assertIsNone(result["team_dir"])
+
+ def test_finished_detection_works_for_classic_schema_without_top_level_status(self):
+ """Classic(v1.3)没有顶层 status 字段,"跑完没跑完"只能看 last_event。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ artifacts = root / "artifacts"
+
+ done_dir = artifacts / "classic-done_20260910_0900"
+ done_dir.mkdir(parents=True)
+ (done_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed",
+ "stages": {"SOLO": {"status": "completed"}},
+ }), encoding="utf-8")
+
+ active_dir = artifacts / "classic-active_20260911_1000"
+ active_dir.mkdir(parents=True)
+ (active_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "TASK-02_completed",
+ "stages": {"TASK-02": {"status": "completed"}, "TASK-03": {"status": "in_progress"}},
+ }), encoding="utf-8")
+
+ result = devflow._scan_artifacts_for_active_run(str(root))
+ self.assertIsNotNone(result)
+ self.assertEqual(result["task_slug"], "classic-active_20260911_1000")
+
+ def test_resolve_and_diff_switches_task_slug_when_a_newer_run_appears(self):
+ """真实 bug 回归测试:同一个长生命周期 sid 先后归属两次不同的 devflow 运行
+ (没有真正 team_create 时的降级场景——第二次 `/start-devflow` 复用了同一个
+ session)。第一次探测缓存下的 task_slug 不能在第二次运行开始后继续沿用;
+ 必须切换到新的那个,而且两个 task_slug 各自的 diff 历史不能互相污染。"""
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-reused-across-two-runs"
+
+ first_dir = project_dir / "artifacts" / "first-task_20260914_0900"
+ first_dir.mkdir(parents=True)
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(first["task_slug"], "first-task_20260914_0900")
+
+ # 同一个 sid,第二次运行出现,且比第一次更新(mtime 更新)。
+ import time
+ time.sleep(0.01)
+ second_dir = project_dir / "artifacts" / "second-task_20260914_1100"
+ second_dir.mkdir(parents=True)
+ (second_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(second["task_slug"], "second-task_20260914_1100")
+ self.assertEqual(second["changes"], []) # 对 second 是首次观测,不产出变更
+
+ # 第一个 task_slug 的历史没有被污染:如果它重新变成"最新"(比如被再次修改),
+ # 应该正确切回,并且不会把 second 的历史错当成 first 的基线。
+ (first_dir / "workflow-state.json").write_text(json.dumps({
+ "version": "1.3", "last_event": "workflow_completed", "current_stage": "SOLO",
+ "stages": {"SOLO": {"status": "completed", "retry_count": 1}},
+ }), encoding="utf-8")
+ time.sleep(0.01)
+ first_dir.joinpath("workflow-state.json").touch()
+
+ third = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(third["task_slug"], "first-task_20260914_0900")
+ # first 上一次被观测到时 retry_count 还是 0,现在变成 1——应该被识别为变化,
+ # 而不是被 second 的快照历史污染成"首次观测"或者对不上的 diff。
+ self.assertEqual(len(third["changes"]), 1)
+ self.assertEqual(third["changes"][0]["retry_count"], 1)
+
+ def test_resolve_and_diff_end_to_end_via_artifacts_scan_no_team(self):
+ with tempfile.TemporaryDirectory() as td:
+ project_dir = Path(td) / "project"
+ artifacts_dir = project_dir / "artifacts" / "portable-task_20260911_1100"
+ artifacts_dir.mkdir(parents=True)
+ state_file = artifacts_dir / "workflow-state.json"
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "in_progress", "executor_role": "devflow-code-reviewer", "retry_count": 0}},
+ }), encoding="utf-8")
+
+ import os
+ old_env = os.environ.get("CODEBUDDY_CONFIG_DIR")
+ os.environ["CODEBUDDY_CONFIG_DIR"] = str(Path(td) / "empty-codebuddy-home")
+ try:
+ state_path = project_dir / ".codebuddy" / "skills" / "agent-observability" / "logs" / ".state.json"
+ sid = "sid-spawn-1"
+
+ first = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertIsNotNone(first)
+ self.assertEqual(first["task_slug"], "portable-task_20260911_1100")
+ self.assertEqual(first["schema_version"], "2.0")
+ self.assertEqual(first["execution_mode"], "isolated")
+ self.assertEqual(first["changes"], [])
+
+ state_file.write_text(json.dumps({
+ "version": "2.0",
+ "status": "in_progress",
+ "current_stage": "REVIEW",
+ "execution_mode": "isolated",
+ "stages": {"REVIEW": {"status": "failed", "executor_role": "devflow-code-reviewer", "retry_count": 1}},
+ }), encoding="utf-8")
+
+ second = devflow.resolve_and_diff(state_path, sid, str(project_dir))
+ self.assertEqual(len(second["changes"]), 1)
+ self.assertEqual(second["changes"][0]["retry_count"], 1)
+ self.assertEqual(second["changes"][0]["status"], "failed")
+ finally:
+ if old_env is None:
+ os.environ.pop("CODEBUDDY_CONFIG_DIR", None)
+ else:
+ os.environ["CODEBUDDY_CONFIG_DIR"] = old_env
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.cursor/skills/agent-observability/tests/test_pricing_overrides.py b/.cursor/skills/agent-observability/tests/test_pricing_overrides.py
new file mode 100644
index 00000000..75615a36
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_pricing_overrides.py
@@ -0,0 +1,394 @@
+"""自定义模型定价覆盖 + 看板未定价模型提示。
+
+覆盖文件是**人手写的常驻配置**,而且加载失败要静默降级——这类"错了也不许
+报错"的代码最容易在半年后被悄悄改坏(比如有人顺手把 try/except 去掉、把合并
+改成整 key 覆盖、或让降级路径开始 print)。这里把字段级合并、四种/五种降级
+路径、缓存语义、未定价口径、看板聚合与"不重算历史成本"逐条钉住。
+
+两个容易踩的隔离坑,本文件统一在 setUp/tearDown 处理:
+1. `load_prices()` 带 `lru_cache`,不 `clear_price_cache()` 用例之间会串味;
+2. `AOBS_PRICING_OVERRIDES_PATH` 是进程级环境变量,不还原会污染同进程里
+ 其它测试模块(尤其是会真的去读默认覆盖文件的 hook 链路)。
+
+真实日志对账(hy4-preview-ioa / hy3-ioa 的计数)不写进单测:日志会持续增长,
+写死数字会变成 flaky 用例。那部分以人工冒烟的方式在 TASK-04 报告里记录。
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+import build_dashboard_data as bdd # type: ignore
+from core import emitter # type: ignore
+
+OVERRIDES_ENV = "AOBS_PRICING_OVERRIDES_PATH"
+
+
+class _OverridesTestCase(unittest.TestCase):
+ """统一处理环境变量与 `load_prices()` 缓存的隔离。"""
+
+ def setUp(self):
+ self._env_backup = os.environ.get(OVERRIDES_ENV)
+ os.environ.pop(OVERRIDES_ENV, None)
+ emitter.clear_price_cache()
+ self._tmp = tempfile.TemporaryDirectory()
+ self.tmp = Path(self._tmp.name)
+
+ def tearDown(self):
+ # 顺序要紧:先还原 env,再清缓存,最后清目录,避免留下一个指向已删除
+ # 目录的环境变量给下一个用例。
+ if self._env_backup is None:
+ os.environ.pop(OVERRIDES_ENV, None)
+ else:
+ os.environ[OVERRIDES_ENV] = self._env_backup
+ emitter.clear_price_cache()
+ self._tmp.cleanup()
+
+ def use_overrides(self, payload, name: str = "overrides.json") -> Path:
+ """把 payload 写成覆盖文件并指向它(JSON 文本原样写入,便于构造非法输入)。"""
+ path = self.tmp / name
+ text = payload if isinstance(payload, str) else json.dumps(payload)
+ path.write_text(text, encoding="utf-8")
+ os.environ[OVERRIDES_ENV] = str(path)
+ emitter.clear_price_cache()
+ return path
+
+ def pure_builtin(self) -> dict:
+ """"纯内置表"的唯一权威来源——不把 pricing.json 的内容抄进断言里,
+ 否则内置表一调整这里就假红;但内置表本身必须是非空的,否则下面的
+ "降级后 == 纯内置表" 断言会退化成空表比空表。"""
+ builtin = emitter._load_builtin_prices()
+ self.assertTrue(builtin, "内置价格表不应为空,否则降级断言失去意义")
+ self.assertIn("gpt-4o", builtin)
+ return builtin
+
+
+class OverridesPathResolutionTests(_OverridesTestCase):
+ """AC4:路径可覆盖。默认位置刻意放在 skills 树**外**——
+ `scripts/build-classic-hosts.py` 会整棵同步 `.codebuddy/skills`,放树内会让
+ 用户每次改价都产生一次 `--check` drift,并被复制进 .claude/.cursor 宿主包。"""
+
+ def test_env_var_wins_over_default(self):
+ path = self.use_overrides({"zz-model": {"output": 1.0}})
+ self.assertEqual(emitter.resolve_overrides_path(), path)
+
+ def test_tilde_is_expanded(self):
+ os.environ[OVERRIDES_ENV] = "~/aobs-overrides-test.json"
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), Path.home() / "aobs-overrides-test.json")
+
+ def test_unset_falls_back_to_default_path(self):
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_blank_env_falls_back_to_default(self):
+ # 空字符串/纯空白都等同于"没设置",不能变成指向 CWD 的相对路径。
+ os.environ[OVERRIDES_ENV] = " "
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.resolve_overrides_path(), emitter.DEFAULT_OVERRIDES_PATH)
+
+ def test_default_path_is_outside_the_skills_tree(self):
+ default = emitter.DEFAULT_OVERRIDES_PATH
+ self.assertIsNotNone(default)
+ self.assertEqual(
+ default,
+ ROOT.parents[2] / ".codebuddy" / "agent-observability" / "pricing.overrides.json",
+ )
+ self.assertNotIn("skills", default.parts[-3:])
+ self.assertFalse(str(default).startswith(str(ROOT)))
+
+
+class MergePricesTests(unittest.TestCase):
+ """AC2:字段级合并。整 key 覆盖被刻意否决过——漏写字段会把该字段按 0 计,
+ 静默把成本算没,风险高于收益。"""
+
+ def test_explicit_field_overrides_builtin_while_others_are_kept(self):
+ merged = emitter.merge_prices(
+ {"gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25}},
+ {"gpt-4o": {"output": 99.0}},
+ )
+ self.assertEqual(merged["gpt-4o"]["output"], 99.0)
+ self.assertEqual(merged["gpt-4o"]["input"], 2.5)
+ self.assertEqual(merged["gpt-4o"]["cache_read"], 1.25)
+
+ def test_new_model_can_be_added(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-new": {"output": 9.0}})
+ self.assertEqual(merged["zz-new"], {"output": 9.0})
+
+ def test_merge_does_not_mutate_its_arguments(self):
+ base = {"gpt-4o": {"input": 2.5, "output": 10.0}}
+ overrides = {"gpt-4o": {"output": 99.0}}
+ merged = emitter.merge_prices(base, overrides)
+ merged["gpt-4o"]["input"] = 0.0
+ # 内置表是模块级共享数据(lru_cache 之外还有调用方持有引用),
+ # 被就地改过的话一次合并会污染整条 hook 链路。
+ self.assertEqual(base["gpt-4o"], {"input": 2.5, "output": 10.0})
+ self.assertEqual(overrides["gpt-4o"], {"output": 99.0})
+
+ def test_empty_or_none_overrides_return_base_copy(self):
+ base = {"gpt-4o": {"output": 10.0}}
+ self.assertEqual(emitter.merge_prices(base, None), base)
+ self.assertEqual(emitter.merge_prices(base, {}), base)
+
+ def test_none_base_returns_overrides_only(self):
+ self.assertEqual(emitter.merge_prices(None, {"zz-new": {"output": 1.0}}), {"zz-new": {"output": 1.0}})
+
+ def test_non_dict_rows_are_ignored(self):
+ merged = emitter.merge_prices({"gpt-4o": {"output": 10.0}}, {"zz-bad": 9.0, "zz-ok": {"output": 2.0}})
+ self.assertNotIn("zz-bad", merged)
+ self.assertEqual(merged["zz-ok"], {"output": 2.0})
+
+
+class LoadPricesOverrideTests(_OverridesTestCase):
+ """AC2 + AC3:加载与降级。"""
+
+ def test_override_applies_field_level_and_adds_model(self):
+ self.use_overrides({"zz-custom": {"input": 1.0, "output": 9.0}, "gpt-4o": {"output": 99.0}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["zz-custom"], {"input": 1.0, "output": 9.0})
+ self.assertEqual(prices["gpt-4o"]["output"], 99.0)
+ self.assertEqual(prices["gpt-4o"]["input"], self.pure_builtin()["gpt-4o"]["input"])
+
+ def test_missing_file_degrades_to_builtin(self):
+ os.environ[OVERRIDES_ENV] = str(self.tmp / "does-not-exist.json")
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_invalid_json_degrades_to_builtin(self):
+ self.use_overrides('{"gpt-4o": {"output": 99.0}')
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_top_level_non_dict_degrades_to_builtin(self):
+ self.use_overrides("[1, 2, 3]")
+ self.assertEqual(emitter.load_prices(), self.pure_builtin())
+
+ def test_non_numeric_field_is_skipped_but_siblings_apply(self):
+ self.use_overrides({"gpt-4o": {"output": "abc", "input": 3.0}})
+ prices = emitter.load_prices()
+ # 写错一个字段不该把同模型其它字段、其它模型的正确覆盖一起丢掉。
+ self.assertEqual(prices["gpt-4o"]["input"], 3.0)
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_model_with_only_bad_fields_is_dropped_and_stays_unpriced(self):
+ """计划外决策(已在 code review 接受):全坏字段的模型不落表。
+ 若落表成 `{}`,它既算不出成本又不算"未定价",看板上会变成一个查不到
+ 原因的空洞;丢弃后至少能在"模型定价"提醒里暴露出来。"""
+ self.use_overrides({"zz-all-bad": {"output": "abc"}})
+ prices = emitter.load_prices()
+ self.assertNotIn("zz-all-bad", prices)
+ self.assertTrue(emitter.is_unpriced("zz-all-bad"))
+
+ def test_bool_is_not_treated_as_a_price(self):
+ # bool 是 int 的子类,float(True) == 1.0 会静默变成"单价 1 美元"。
+ self.use_overrides({"gpt-4o": {"output": True}})
+ prices = emitter.load_prices()
+ self.assertEqual(prices["gpt-4o"]["output"], self.pure_builtin()["gpt-4o"]["output"])
+
+ def test_every_degradation_path_is_silent(self):
+ """静默是刻意的:hook 每次都是新进程,一旦因格式问题 print/抛异常,
+ 整条 hook 链路都会变得不可用。"""
+ for payload in ('{"broken": ', "[1,2,3]", '{"gpt-4o": {"output": "abc"}}', '{"gpt-4o": 1}'):
+ with self.subTest(payload=payload):
+ self.use_overrides(payload)
+ out, err = io.StringIO(), io.StringIO()
+ with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+ prices = emitter.load_prices()
+ self.assertEqual(prices, self.pure_builtin())
+ self.assertEqual(out.getvalue(), "")
+ self.assertEqual(err.getvalue(), "")
+
+ def test_load_prices_is_cached_until_cleared(self):
+ path = self.use_overrides({"zz-cache-model": {"output": 1.0}})
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ path.write_text(json.dumps({"zz-cache-model": {"output": 2.0}}), encoding="utf-8")
+ # 未清缓存:同进程内仍是旧值(hook 是短命进程,这个行为是可接受的)。
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 1.0)
+ emitter.clear_price_cache()
+ self.assertEqual(emitter.load_prices()["zz-cache-model"]["output"], 2.0)
+
+ def test_clear_price_cache_picks_up_env_change(self):
+ self.assertTrue(hasattr(emitter.load_prices, "cache_clear"))
+ self.use_overrides({"zz-a": {"output": 1.0}})
+ self.assertIn("zz-a", emitter.load_prices())
+ self.use_overrides({"zz-b": {"output": 2.0}}, name="second.json")
+ emitter.clear_price_cache()
+ prices = emitter.load_prices()
+ self.assertIn("zz-b", prices)
+ self.assertNotIn("zz-a", prices)
+
+
+class IsUnpricedTests(_OverridesTestCase):
+ """D4:未定价的唯一口径是 `lookup_price(...) is None`。
+ `lookup_price` 会做"最长子串"模糊兜底,所以 `gpt-4o-2024-11-20` 能算出成本,
+ 不该出现在"建议补价"里——口径一旦漂移,用户会去给明明已经命中的模型补价。"""
+
+ def test_unknown_model_is_unpriced(self):
+ self.assertTrue(emitter.is_unpriced("zz-totally-unknown"))
+
+ def test_fuzzy_substring_match_is_not_unpriced(self):
+ self.assertFalse(emitter.is_unpriced("gpt-4o-2024-11-20"))
+
+ def test_missing_or_blank_model_is_unpriced(self):
+ for model in (None, "", " "):
+ with self.subTest(model=model):
+ self.assertTrue(emitter.is_unpriced(model))
+
+ def test_override_makes_a_model_priced(self):
+ self.assertTrue(emitter.is_unpriced("zz-then-priced"))
+ self.use_overrides({"zz-then-priced": {"output": 9.0}})
+ self.assertFalse(emitter.is_unpriced("zz-then-priced"))
+
+
+class BuildUnpricedModelsTests(_OverridesTestCase):
+ """AC5:只看板**统计**,绝不回头重算 cost_usd(D3:覆盖只对新事件生效)。"""
+
+ def _usage(self, model, ts=1.0):
+ return {"event": "usage", "sid": "s1", "ts": ts, "model": model, "tokens": {"input": 1, "output": 1}}
+
+ def test_counts_only_unpriced_usage_events(self):
+ events = [
+ self._usage("zz-unpriced-a", 1.0),
+ self._usage("zz-unpriced-a", 2.0),
+ self._usage("zz-unpriced-b", 3.0),
+ self._usage("gpt-4o-2024-11-20", 4.0), # 模糊命中,不算未定价
+ {"event": "usage", "sid": "s1", "ts": 5.0, "tokens": {"input": 1}}, # model 缺失
+ self._usage(" ", 6.0), # model 空白
+ {"event": "tool", "sid": "s1", "ts": 7.0, "tool": "Bash", "ms": 1}, # 非 usage
+ ]
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [
+ {"name": "zz-unpriced-a", "usageEvents": 2},
+ {"name": "zz-unpriced-b", "usageEvents": 1},
+ ])
+
+ def test_empty_input_returns_empty_list(self):
+ self.assertEqual(bdd.build_unpriced_models([]), [])
+
+ def test_sorted_by_event_count_desc_then_name(self):
+ events = (
+ [self._usage("zz-b", float(i)) for i in range(2)]
+ + [self._usage("zz-a", 9.0)]
+ + [self._usage("zz-c", float(i)) for i in range(2)]
+ )
+ rows = bdd.build_unpriced_models(events)
+ # 计数相同的 zz-b / zz-c 必须按名字定序,否则两次生成的快照无法逐字节比对。
+ self.assertEqual([(r["name"], r["usageEvents"]) for r in rows],
+ [("zz-b", 2), ("zz-c", 2), ("zz-a", 1)])
+
+ def test_pricing_a_model_removes_it_from_the_list(self):
+ events = [self._usage("zz-unpriced-a", 1.0), self._usage("zz-unpriced-b", 2.0)]
+ self.assertEqual(len(bdd.build_unpriced_models(events)), 2)
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ rows = bdd.build_unpriced_models(events)
+ self.assertEqual(rows, [{"name": "zz-unpriced-b", "usageEvents": 1}])
+
+ def test_emitter_import_failure_degrades_to_empty_list(self):
+ """目标机可能没装 emitter 的间接依赖;此时只该退化"未定价"这一项,
+ 看板仍要能出片。"""
+ with mock.patch.object(bdd, "em", None):
+ self.assertEqual(bdd.build_unpriced_models([self._usage("zz-unpriced-a")]), [])
+
+
+class MainSnapshotTests(_OverridesTestCase):
+ """main() 级别:键位、空列表、不重算成本、无覆盖时与改动前一致(AC1)。"""
+
+ def _events(self):
+ return [
+ {"event": "user_prompt_submit", "sid": "s1", "ts": 1.0, "turn_id": "t1", "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 2.0, "model": "gpt-4o-2024-11-20",
+ "tokens": {"input": 100, "output": 10}, "cost_usd": 0.0035, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 3.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ {"event": "usage", "sid": "s1", "ts": 4.0, "model": "zz-unpriced-a",
+ "tokens": {"input": 100, "output": 10}, "agent": "main"},
+ ]
+
+ def _run_main(self, root: Path, out_name: str) -> tuple[dict, str]:
+ metrics = root / "metrics.ndjson"
+ metrics.write_text("\n".join(json.dumps(e) for e in self._events()) + "\n", encoding="utf-8")
+ state = root / ".state.json"
+ state.write_text("{}", encoding="utf-8")
+ out = root / out_name
+ old_argv = sys.argv
+ sys.argv = ["build_dashboard_data.py", "--project-root", str(root),
+ "--out", str(out), "--metrics-path", str(metrics), "--state-path", str(state)]
+ buf = io.StringIO()
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = bdd.main()
+ finally:
+ sys.argv = old_argv
+ self.assertEqual(rc, 0)
+ self.assertIn("wrote ", buf.getvalue())
+ return json.loads(out.read_text("utf-8")), buf.getvalue()
+
+ def test_snapshot_exposes_unpriced_models_right_after_model_costs(self):
+ with tempfile.TemporaryDirectory() as td:
+ data, _ = self._run_main(Path(td), "out.json")
+ keys = list(data.keys())
+ self.assertEqual(keys[keys.index("modelCosts") + 1], "unpricedModels")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual([m["name"] for m in data["modelCosts"]], ["gpt-4o-2024-11-20"])
+
+ def test_no_unpriced_models_yields_empty_list_not_null(self):
+ with tempfile.TemporaryDirectory() as td:
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ data, _ = self._run_main(Path(td), "out.json")
+ self.assertEqual(data["unpricedModels"], [])
+
+ def test_override_never_recomputes_already_written_costs(self):
+ """D3 的回归护栏:给未定价模型补价后,只有 unpricedModels 会变,
+ modelCosts / daily / sessions 必须逐字节不变(历史成本不回溯)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ before, _ = self._run_main(root, "before.json")
+ self.use_overrides({"zz-unpriced-a": {"output": 9.0}})
+ after, _ = self._run_main(root, "after.json")
+ before.pop("generated_at")
+ after.pop("generated_at")
+ self.assertEqual(before["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+ self.assertEqual(after["unpricedModels"], [])
+ before.pop("unpricedModels")
+ after.pop("unpricedModels")
+ self.assertEqual(before, after)
+
+ def test_broken_override_file_keeps_cli_at_exit_zero_and_silent(self):
+ """AC3 的 CLI 层护栏:覆盖文件坏掉时看板仍然出片(exit 0、stderr 为空),
+ 而不是把整条构建链路搞挂。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ self.use_overrides('{"gpt-4o": {"output": 99.0}') # 故意截断的非法 JSON
+ err = io.StringIO()
+ with contextlib.redirect_stderr(err):
+ data, _ = self._run_main(root, "out.json")
+ self.assertEqual(err.getvalue(), "")
+ self.assertEqual(data["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+ def test_no_override_file_matches_nonexistent_override_path(self):
+ """AC1 的核心回归:不传覆盖文件时价格表就是纯内置表,
+ 与"指向一个不存在的路径"的输出完全一致(忽略 generated_at)。"""
+ with tempfile.TemporaryDirectory() as td:
+ root = Path(td)
+ unset, _ = self._run_main(root, "unset.json")
+ os.environ[OVERRIDES_ENV] = str(root / "nope.json")
+ emitter.clear_price_cache()
+ missing, _ = self._run_main(root, "missing.json")
+ unset.pop("generated_at")
+ missing.pop("generated_at")
+ self.assertEqual(unset, missing)
+ self.assertEqual(unset["unpricedModels"], [{"name": "zz-unpriced-a", "usageEvents": 2}])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/.cursor/skills/agent-observability/tests/test_runtime_flow.py b/.cursor/skills/agent-observability/tests/test_runtime_flow.py
new file mode 100644
index 00000000..7bd143ba
--- /dev/null
+++ b/.cursor/skills/agent-observability/tests/test_runtime_flow.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+if str(SCRIPTS) not in sys.path:
+ sys.path.insert(0, str(SCRIPTS))
+
+from core import runtime # type: ignore
+
+
+class RuntimeFlowTests(unittest.TestCase):
+ def test_resolve_active_agent_prefers_inbox_inferred_agent_when_available(self):
+ data = {
+ "tool_name": "Task",
+ "tool_input": {"subagent_name": "developer"},
+ }
+ with tempfile.TemporaryDirectory() as td:
+ state_path = Path(td) / ".state.json"
+ with mock.patch.object(runtime.agent_identity, "merge_agent_identity_from_inbox", return_value=("qa", "developer")) as merge_identity:
+ active, dispatched = runtime.agent_identity.resolve_active_agent_for_event(
+ state_path=state_path,
+ sid="s-inbox",
+ cwd=td,
+ data=data,
+ )
+
+ self.assertEqual(active, "qa")
+ self.assertEqual(dispatched, "developer")
+ merge_identity.assert_called_once()
+
+ def test_handle_post_routes_through_expected_collaborators(self):
+ data = {
+ "session_id": "s-runtime",
+ "cwd": "/tmp/demo",
+ "tool_name": "Read",
+ "transcript_path": "/tmp/demo.jsonl",
+ }
+ with tempfile.TemporaryDirectory() as td:
+ with mock.patch.object(runtime, "build_runtime_paths") as mock_paths, \
+ mock.patch.object(runtime.collector, "record_post", return_value=12), \
+ mock.patch.object(runtime.collector, "load_cached_inventory", return_value=({}, {})), \
+ mock.patch.object(runtime.scanner, "scan_skills_and_rules", return_value=({}, {})), \
+ mock.patch.object(runtime.collector, "cache_inventory"), \
+ mock.patch.object(runtime.collector, "record_tool_usage", return_value=([], [])), \
+ mock.patch.object(runtime.agent_identity, "resolve_active_agent_for_event", return_value=("main", None)), \
+ mock.patch.object(runtime, "current_turn_id", return_value="turn-1"), \
+ mock.patch.object(runtime.collector, "extract_tool_call_id", return_value=None), \
+ mock.patch.object(runtime, "flush_pending_tool_events"), \
+ mock.patch.object(runtime.collector, "find_current_tool_context", return_value=None), \
+ mock.patch.object(runtime.collector, "related_transcript_paths", return_value=["/tmp/demo.jsonl"]), \
+ mock.patch.object(runtime, "emit_transcript_events", return_value=[]), \
+ mock.patch.object(runtime.collector, "find_fallback_usage_event", return_value=None), \
+ mock.patch.object(runtime.st, "append_pending_tool_emit"), \
+ mock.patch.object(runtime.agentlens, "emit_post_step"):
+ mock_paths.return_value = runtime.RuntimePaths(
+ base_dir=Path(td),
+ state_path=Path(td) / ".state.json",
+ pending_path=Path(td) / ".pending.json",
+ log_path=Path(td) / "metrics.ndjson",
+ )
+ runtime.handle_post(data)
+
+ def test_main_dispatches_supported_phase_to_handler(self):
+ with mock.patch.object(runtime, "handle_post") as handle_post, \
+ mock.patch.object(runtime.collector, "read_stdin_json", return_value={"session_id": "s1"}):
+ rc = runtime.main(["post"])
+ self.assertEqual(rc, 0)
+ handle_post.assert_called_once()
diff --git a/.gitignore b/.gitignore
index 363f2326..00c94492 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,14 @@ artifacts/
*.db
*.sqlite
__pycache__/
+
+# agent-observability 运行时产物(本地日志、看板数据快照):不入库,四个 host 副本都要排除
+.codebuddy/skills/agent-observability/logs/*
+.codex/skills/agent-observability/logs/*
+.cursor/skills/agent-observability/logs/*
+.claude/skills/agent-observability/logs/*
+!**/skills/agent-observability/logs/.gitkeep
+**/skills/agent-observability/scripts/dashboard/dashboard-data.json
*.py[cod]
build/
dist/
diff --git a/scripts/build-classic-hosts.py b/scripts/build-classic-hosts.py
index 52613c5d..a8cfcbb5 100644
--- a/scripts/build-classic-hosts.py
+++ b/scripts/build-classic-hosts.py
@@ -206,9 +206,15 @@ def write_host(host: str) -> None:
def check_host(host: str) -> list:
target = ROOT / f".{host}"
wanted = expected(host)
+ # __pycache__/*.pyc 是运行 Python 工具(比如 validate.sh 里的 py_compile)时的
+ # 正常副作用,不是宿主包内容本身;add_tree() 生成期望清单时已经排除了同样的
+ # 东西(见上面 134 行),这里扫描"实际有什么"必须用一样的排除规则,否则任何
+ # 在 .claude/.cursor 下跑过一次 Python 语法检查就会把这些缓存文件误判成
+ # "unmanaged extra"。
actual = {
str(path.relative_to(target)): path.read_bytes()
- for path in target.rglob("*") if path.is_file()
+ for path in target.rglob("*")
+ if path.is_file() and "__pycache__" not in path.parts and path.suffix != ".pyc"
} if target.is_dir() else {}
errors = []
for name in sorted(set(wanted) | set(actual)):