debug-instrumentation

name	debug-instrumentation
version	1.0.0
description	调试埋点闭环。用户明确要求新增用于调试的日志、log、console.log、print 或埋点，或分析已加入的调试日志输出时使用；统一可搜索 token，并按埋点、采集、假设归因、询问清理推进。
disable-model-invocation	true

Debug Instrumentation（埋点调试）

用假设驱动的闭环把一次排查变成可搜索、可验证、可清理的证据链：先在最可疑路径放置少量埋点，再采集证据、归因，并由用户决定何时清理。

Token 与批次

每条调试日志都以一个纯文本 token 开头：

[DBG_<语义短标签>_<4位随机字符>]

• 语义短标签 使用 3–15 个字符的 kebab-case：[a-z]+(?:-[a-z]+)*。
• 4位随机字符 使用 [a-z0-9]{4}。生成埋点代码时手动选定即可，不在业务代码中加入随机数逻辑。
• 完整 token 的格式为 ^\[DBG_(?=[a-z-]{3,15}_)[a-z]+(?:-[a-z]+)*_[a-z0-9]{4}\]$。
• 同一轮、同一目的的埋点复用同一个完整 token；验证新假设或独立模块时创建新批次。
• 创建新 token 前，若可检索目标工作区，先用固定字符串搜索 [DBG_，了解是否存在历史调试批次；再按候选标签搜索 [DBG_<label>_。不要把方括号当作正则，也不要扫描 .git 或依赖目录。
• 搜到历史批次时，列出完整 token、位置和可判断的用途。写入前让用户在 清理后新增、沿用现有、仅新增 中选择；默认建议为 沿用现有。只可沿用用户明确选定且与当前排查语义相符的完整 token，不能因存在任意 [DBG_] 就自动复用无关批次。
• 清理后新增 先完整走本 Skill 的清理双确认，删除完成后才生成新 token；仅新增 保留旧批次并使用不同 suffix；没有历史命中时才可直接生成新 token。

开始写入前，输出本轮批次清单：token、用途、位置和待验证的假设。若历史批次命中，把处理选择和本轮清单合并为一次确认；涉及多个标签时，同样一次性列出全部标签并等待用户确认。无历史命中的单标签则在具备修改授权后直接执行。初次埋点只覆盖最可疑路径，保持日志量可读。

闭环

1. 埋点

先阅读相关代码、调用链和现有日志，提出当前最可能的原因，再选取能区分该假设的输入、分支、异步边界或返回值。日志的第一个输出内容必须是 token，原有项目的日志级别、参数风格和脱敏规范保持不变。

JavaScript：

console.log('[DBG_auth-flow_x7k2] refresh requested', { userId, hasRefreshToken });

Python：

logger.info('[DBG_auth-flow_x7k2] refresh requested user_id=%s', user_id)

完成后报告每个 token、修改位置和用户应如何触发复现。无法访问实际运行环境时，只提供可执行的采集步骤，不把预期当作真实输出。

2. 采集

按用户提供的形式处理日志：

• 直接分析粘贴的文本。
• 读取用户给出的 .log、.txt 或其他日志文件路径。
• 日志量较大时主动过滤目标批次：已知完整 token 用完整 token；只知道标签时用 [DBG_<label> 前缀。

优先使用固定字符串搜索，避免方括号被解释为正则：

rg -F '[DBG_auth-flow_x7k2]' path/to/logs
grep -F '[DBG_auth-flow' path/to/logs

记录日志来源、可见时间/顺序和缺失区段。没有文件访问权限、运行工具或复现条件时，明确说明需要用户提供的日志或授权。

3. 归因

把“日志事实”“推断”“结论”分开陈述，并用 token 和关键顺序支撑结论。证据充分时，说明原因、受影响路径和建议修复方向。

证据不足时，保持假设驱动：提出最多两个可证伪假设；逐项说明需要补在哪个函数或边界、记录什么字段、为什么能区分假设；为追加埋点生成新 token。等待用户决定是否追加，不扩大为全面撒网。

4. 清理

每轮分析结束后主动询问：

这批 [DBG_xxx_xxxx] 是否可以清理，还是需要保留继续排查？

用户选择清理后，按完整 token 定位命中并区分：源码中本轮插入的埋点、采集到的日志、说明文档或历史内容。此步骤支持跨会话：用户提供完整 token 即可，不依赖当前对话记忆。仅为该 token 对应的源码埋点生成删除 diff，展示待删除内容后再次等待最终确认。确认后删除、复查语法或项目检查，并重新搜索完整 token，确认源码中不再残留；用户日志和文档默认保持不动。

交付格式

每次响应按当前阶段报告：

• 批次：token、目的、修改位置或日志来源。
• 证据：关键日志顺序与可确认事实。
• 归因：结论，或下一批可证伪假设。
• 清理：保留中、等待清理授权、等待 diff 确认，或已验证清理完成。

不要把临时 token 伪装成长期业务日志规范；它的价值是短期、可检索和可撤销。