debuglisted

## 概述 「日志采集服务器 + 代码埋点 + 迭代分析」三步闭环：先收集运行时上下文，再基于真实数据定位修复 ## 分诊：要不要用本 skill（先做这一步） 遵循「不猜测，只验证」。本 skill 是**重型路径**（起服务器 + 埋点 + 让人复现），仅当**同时满足**以下两条才进入执行流程： 1. **AI 自己拿不到运行时上下文**——变量实际值、异步两侧时序、多进程/跨端状态，靠读代码、`grep`、跑测试都无法确定 2. **需要人主动复现**——交互触发、特定环境、偶现 Bug，AI 无法自动重放 否则先走**轻量静态排查**，不要起服务器： - 读相关代码、按调用链推理可能的原因路径 - 索要无法自行获取的信息（环境变量、依赖版本、配置、现有日志） - 能自动化就自动化：跑测试复现、浏览器自动化、查 DevTool 静态分析能定位 → 直接修；确实需要运行时真实数据且必须靠人复现 → 才往下走 Phase 0 ## 执行流程 ### Phase 0: 会话身份（并发前提） 取一个唯一标识 `SESSION`（kebab，体现主题，如 `perm-gate`），所有埋点 `source` 统一加前缀 `SESSION/`——这是多会话隔离（过滤读、范围清空）的根基 ### Phase 1: 启动 / 复用服务器 在**工作区根目录**后台启动（优先 bun，未装则 node），幂等：已有健康实例自动复用，不重复起、不误杀 ```bash # 默认：端口 9210，日志 ./debug.log bun ~/.claude/skills/debug/scripts/debug-server.mjs & # 仅当调试「不同 app / 工作区」时才换端口和日志 DEBUG_PORT=9211 DEBUG_LOG=./logs/debug.log bun ~/.claude/skills/debug/scripts/debug-server.mjs & ``` | 环境变量 | 默认值 | 说明 | |----------|--------|------| | `DEBUG_PORT` | `9210` | 监听端口 | | `DEBUG_LOG` | `./debug.log` | 日志路径（相对启动时 cwd） | `GET /health` 验证已启动后，**登记本会话**（引用计数，防止收尾时被别人提前关停）： ```bash curl -s -X POST http://localhost:9210/register -H 'Content-Type: application/json' -d '{"session":"perm-gate"}' ``` > 被调试 app 的埋点端口通常写死，故多会话调试**同一个 app** 必然共享同一 server 和 `debug.log`，换端口无效——隔离靠 `SESSION/` 前缀。只有调**不同 app/工作区**才用 `DEBUG_PORT`+`DEBUG_LOG` ### Phase 2: 分析并埋点 分析可能的原因路径，在**关键节点**（入口、分支、出口、异步两侧）插入上报，采集变量**实际值**而非"到达了这里" **先一次性建一个埋点 helper**（临时文件，排查完删），之后每处埋点只写一行 `dbg('tag', data)`——`SESSION/` 前缀自动带上（省 token + 保证隔离），`tag` 即定位锚