vscode-copilot-chat 调试日志全解析：用 JSONL 会话日志定位 Agent 异常行为

人工智能AI 应用AI Agent代码智能体交互助手工具调用MCP Clients【免费下载链接】vscode-copilot-chatCopilot Chat extension for VS Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-copilot-chat点击查看免费下载导读本指南以 assets/prompts/skills/troubleshoot/SKILL.md 为骨架系统讲解 GitHub Copilot ChatVS Code内置 debug-logs 会话日志的目录结构、事件类型、查询工具链与排查工作流并结合本仓库的源码实现如 chatDebugFileLoggerService.ts深入揭示这些日志文件是如何被写出的。读完本文你将掌握一套以日志证据为准、不靠猜测的 Agent 行为调查方法从请求耗时、工具调用成败、子代理启用原因到指令/技能/代理加载失败等问题的定位与修复路径。一、这个 Skill 解决什么问题troubleshootSkill 的核心使命是通过直接分析 JSONL 调试日志调查并解释 Chat Agent 的意外行为。它适用的典型问题包括为什么这次请求花了这么长时间为什么某个工具或子代理被调用了为什么指令 / Skill / 代理文件没有被加载为什么某个工具调用被阻止或失败为什么模型没有遵循预期该 Skill 的黄金法则是结论必须建立在日志证据之上绝不猜测Base conclusions on evidence from logs. Do not guess。从仓库源码看这条法则与日志系统的设计完全一致——调试日志由 ChatDebugFileLoggerService 负责写入它同时订阅三类数据源OTel span 完成事件onDidCompleteSpan、span 实时事件onDidEmitSpanEvent用于实时捕获用户消息以及核心调试事件vscode.chat.onDidReceiveChatDebugEvent用于 discovery 类事件从而保证 main.jsonl 中每条记录都是运行时真实发生的事件而非事后推断。二、数据源debug-logs 会话日志目录结构调查的入口是变量{{VSCODE_TARGET_SESSION_LOG}}指向的会话日志目录。Copilot Chat 会按会话把日志写入debug-logs/sessionId/目录典型布局如下debug-logs/sessionId/ main.jsonl — 始终从这里开始主对话日志 models.json —可选会话开始时可用模型的快照 system_prompt_0.json —可选发送给模型的完整系统提示词未截断 system_prompt_1.json —可选会话中途切换模型时写入 tools_0.json —可选发送给模型的工具定义 tools_1.json —可选会话中途切换模型时写入 runSubagent-agentName-uuid.jsonl —可选子代理的工具调用与 LLM 请求 searchSubagent-uuid.jsonl —可选搜索子代理的工作记录 title-uuid.jsonl —可选仅 UI标题生成 categorization-uuid.jsonl —可选仅 UI提示词分类 summarize-uuid.jsonl —可选仅 UI会话摘要2.1 各文件的作用与读取优先级main.jsonl永远是第一读取对象它包含完整对话流并带有child_session_ref条目按文件名链接到每个子文件。子文件只在对应操作实际发生时才会出现。title / categorization / summarize 属于 UI 层面的内务记录与故障排查关系不大。调查模型可用性或选择问题时读models.json它包含会话开始时全部可用模型含能力、计费、限额信息的列表。调查模型被告知了什么系统提示词、指令时读main.jsonl中system_prompt_ref条目引用的system_prompt_*.json文件其内容为{ content: ... }形式的完整未截断系统提示词。调查模型当时有哪些工具可用时同样方式读取tools_*.json。若会话中途切换过模型会存在多个编号文件——每条llm_request条目的systemPromptFile属性会标明该请求激活的是哪个文件。2.2 源码侧的文件写入机制上述布局并非文档虚构而是由 ChatDebugFileLoggerService._ensureSession 直接实现父会话写入自己的目录debug-logs/sessionId/main.jsonl子会话如 title、categorization写入父目录下的label-childSessionId.jsonl同时向父会话的main.jsonl写入一条child_session_ref交叉引用条目attrs.childLogFile指向子文件名每个 JSONL 文件以session_start条目作为版本头attrs中记录copilotVersion与vscodeVersion由 IEnvService 提供便于判断日志出自哪个构建模型快照由setModelSnapshot()缓存并在每个父会话开始时异步写入models.json_writeModelSnapshot系统提示词与工具定义文件通过_onSpanCompleted/_onToolsAvailableEvent在模型或模式变化时按序号递增写入system_prompt_0.json、tools_0.json……而llm_request条目会挂上systemPromptFile/toolsFile引用与 Skill 文档的描述一一对应。三、JSONL 条目通用字段main.jsonl的每一行都是一个独立的 JSON 对象通用字段如下字段含义ts纪元毫秒时间戳epoch msdur持续时长毫秒sid会话 IDtype事件类型name描述性名称spanId事件 / 跨度 IDparentSpanId父跨度 ID用于构建层级树statusok或errorattrs类型相关的附加细节接口层定义位于 IDebugLogEntrytype枚举完整包含session_start、tool_call、llm_request、user_message、agent_response、subagent、discovery、error、generic、child_session_ref、hook、turn_start、turn_end——与下文事件参考一一对应。四、事件类型参考与实例4.1 discovery —— 定制文件加载指令、技能、代理、钩子{ts:1773200251309,dur:0,sid:62f52dec,type:discovery,name:Load Instructions,spanId:2cb1f2f4,status:ok,attrs:{details:Resolved 0 instructions in 0.0ms | folders: [/c:/Users/user/.copilot/instructions, /workspace/.github/instructions],category:discovery,source:core}} {ts:1773200251415,dur:0,sid:62f52dec,type:discovery,name:Load Agents,spanId:38a897d8,status:ok,attrs:{details:Resolved 3 agents in 0.0ms | loaded: [Plan, Ask, Explore] | folders: [/workspace/.github/agents],category:discovery,source:core}} {ts:1773200251431,dur:0,sid:62f52dec,type:discovery,name:Load Skills,spanId:472eb225,status:ok,attrs:{details:Resolved 6 skills in 0.0ms | loaded: [agent-customization, troubleshoot, ...],category:discovery,source:core}}关键 attrsdetails人类可读摘要含文件夹路径、已加载项、跳过原因排查为什么某文件没加载的直接线索category恒为discoverysourcecore。4.2 tool_call —— 工具调用成功或失败{ts:1773200222647,dur:4,sid:62f52dec,type:tool_call,name:manage_todo_list,spanId:000000000000000b,parentSpanId:0000000000000003,status:ok,attrs:{args:{\operation\:\read\},result:No todo list found.}} {ts:1773200234047,dur:8937,sid:62f52dec,type:tool_call,name:run_in_terminal,spanId:000000000000000d,parentSpanId:0000000000000003,status:error,attrs:{args:{\command\:\echo rama\},result:ERROR: conpty.node missing,error:A native exception occurred during launch}}关键 attrsargs工具入参的 JSON 字符串、result工具输出或错误文本、error当status:error时出现。源码中tool_call由EXECUTE_TOOL类型的 OTel span 转换而来_spanToEntrydur即工具执行耗时。4.3 llm_request —— 模型往返{ts:1773200231010,dur:3001,sid:62f52dec,type:llm_request,name:chat:gpt-4o,spanId:000000000000000c,parentSpanId:0000000000000003,status:ok,attrs:{model:gpt-4o,inputTokens:15025,outputTokens:126,ttft:1987,maxTokens:32000,systemPromptFile:system_prompt_0.json,userRequest:echo hello,inputMessages:[{...}]}}关键 attrsmodel实际使用的模型inputTokens/outputTokens输入 / 输出 token 数ttft首 token 延迟毫秒排查请求慢的核心指标maxTokens、temperature、topP模型采样参数systemPromptFile/toolsFile引用会话目录中的对应文件userRequest完整未截断的用户消息内容inputMessages完整消息数组的 JSON截断在 64KBerror失败时出现。对应源码可见 ChatDebugFileLoggerService 中CHATspan 的转换逻辑name统一格式化为chat:model。4.4 agent_response —— 模型输出文本 工具调用{ts:1773200234011,dur:0,sid:62f52dec,type:agent_response,name:agent_response,spanId:agent-msg-000000000000000c,parentSpanId:0000000000000003,status:ok,attrs:{response:[{\role\:\assistant\,...}],reasoning:The user wants me to run a command.}}关键 attrsresponse消息部件数组的 JSON 编码可能被截断、reasoning可选——思考模式激活时模型的链式推理文本可能被截断。源码侧由 CHAT span 的输出消息与copilot_chat.reasoning_content属性生成chatDebugFileLoggerService.ts。4.5 user_message —— 用户输入{ts:1773200251345,dur:0,sid:62f52dec,type:user_message,name:user_message,spanId:000000000000000f,status:ok,attrs:{content:using subagent count .md}}关键 attrscontent用户消息文本。源码通过onDidEmitSpanEvent实时捕获_onSpanEvent避免与 span 完成事件重复。4.6 subagent —— 子代理调用{ts:1773200254954,dur:7921,sid:62f52dec,type:subagent,name:Explore,spanId:0000000000000014,parentSpanId:0000000000000013,status:ok,attrs:{agentName:Explore}}关键 attrsagentName、description可选、error失败时。源码在INVOKE_AGENTspan 且存在父 span 时生成chatDebugFileLoggerService.ts顶层 agent span 仅作容器、不产出条目。4.7 generic —— 杂项事件{ts:1773200260000,dur:0,sid:62f52dec,type:generic,name:some-event,spanId:abc123,status:ok,attrs:{details:Additional context,category:some-category}}特殊 generic 条目system_prompt_ref引用会话目录中的system_prompt_*.jsonattrs.file为文件名、attrs.model为对应模型tools_ref引用tools_*.json字段同上。4.8 session_start —— 会话元数据会话开始时出现一次{ts:1773200251300,dur:0,sid:62f52dec,type:session_start,name:session_start,spanId:session-start-62f52dec,status:ok,attrs:{copilotVersion:0.43.2026033104,vscodeVersion:1.99.0}}关键 attrscopilotVersion、vscodeVersion用于识别产生日志的构建版本。4.9 turn_start / turn_end —— 工具调用循环的迭代边界{ts:1773200251400,dur:0,sid:62f52dec,type:turn_start,name:turn_start:0,spanId:turn-start-X-0,status:ok,attrs:{turnId:0}} {ts:1773200255000,dur:0,sid:62f52dec,type:turn_end,name:turn_end:0,spanId:turn-end-X-0,status:ok,attrs:{turnId:0}}关键 attrsturnId单次用户请求内工具调用循环的迭代序号。可用于判断事件属于第几轮迭代并统计循环总次数。源码中通过 span 事件turn_start/turn_end生成_onTurnBoundaryEvent。4.10 事件层级spanId / parentSpanId 组成的树事件通过spanId/parentSpanId构成树形结构典型链路为user_messagespanId:X—— 用户发起一轮llm_requestparentSpanId:X—— 该轮的模型调用agent_responseparentSpanId:X—— 模型返回内容tool_callparentSpanId:X—— 响应中触发的工具执行又一次llm_requestparentSpanId:X—— 拿到工具结果后的下一轮模型调用子代理调用会形成嵌套层级runSubagent的tool_callspanId:Y成为子subagentspan 的父节点该 span 又成为其自身llm_request/tool_call的父节点。五、工具链策略为什么必须用终端而不是 grep_search调试日志文件位于工作区之外用户存储目录因此工作区范围内的搜索工具如grep_search无法访问它们必须改用终端。这一点同样有源码依据ToolName.FindTextInFiles grep_search 本质上是工作区文本搜索而调试日志由 IChatDebugFileLoggerService 写入扩展存储目录debug-logs不属于工作区文件。5.1 macOS / Linux / WSL / Git Bash使用run_in_terminal配合grep或jq# 查找错误 grep status:error logPath # 查找 discovery 事件 grep type:discovery logPath # 查找慢事件duration 5s jq -c select(.dur 5000) logPath # 查找工具调用 grep type:tool_call logPath # 搜索特定文本 grep search_term logPath # 获取最后 N 行 tail -n 50 logPath # 按类型统计事件数 jq -r .type logPath | sort | uniq -c | sort -rn # 提取特定字段 jq -c {type, name, status, dur} logPath # 按类型过滤并显示详情 jq -c select(.type discovery) logPath # 查找用户消息 jq -c select(.type user_message) | .attrs.content logPath5.2 WindowsPowerShell使用run_in_terminal配合 PowerShell 命令# 查找错误 Select-String status:error logPath # 查找 discovery 事件 Select-String type:discovery logPath # 查找工具调用 Select-String type:tool_call logPath # 搜索特定文本 Select-String search_term logPath # 获取最后 N 行 Get-Content logPath -Tail 50 # 用 Node.js 解析过滤始终可用筛选 dur 5000 的事件 node -e require(fs).readFileSync(logPath,utf8).split(\n).filter(Boolean).map(JSON.parse).filter(e e.dur 5000).forEach(e console.log(JSON.stringify(e))) # 按类型统计事件数 node -e const linesrequire(fs).readFileSync(logPath,utf8).split(\n).filter(Boolean).map(JSON.parse);const c{};lines.forEach(ec[e.type](c[e.type]||0)1);Object.entries(c).sort((a,b)b[1]-a[1]).forEach(([t,n])console.log(n,t))5.3 通用规则日志文件可能非常大长会话可达数十 MB。不确定时先查文件大小ls -lh logPathWindows 用(Get-Item logPath).Length。文件很大时避免一次性载入内存的命令如node -e的readFileSync优先使用grep、jq、Select-String、tail、head等流式工具。read_file只用于已知行号后的小范围读取几行即可绝不整文件读取。用run_in_terminal的ls -lhWindows 用dir定位候选.jsonl文件并检查大小。Windows 上若没有grep/jq退而求其次用Select-String或node -e单行命令仅限较小文件。六、排查工作流Investigation Workflow定位日志文件聚焦会话日志目录先读每个目录的main.jsonl。若给出多个会话目录全部调查——用户可能想对比或寻找跨会话的共性模式。只有当问题跨会话或给定会话不含相关事件时才去搜索 debug-logs 目录中其他会话文件。快速分诊用run_in_terminal错误搜索status:error延迟过滤高dur值 5000发现类问题搜索type:discovery工具行为搜索type:tool_call模型行为搜索type:llm_request只读相关切片抽取可疑事件附近的确切行必要时用spanId/parentSpanId关联上下文。确定根因从证据中挑选最可能的原因多因素并存时按影响程度排序。给出修复建议尽可能提供可执行的具体下一步。七、网络问题调查collectDiagnostics 命令若怀疑网络连通性或认证问题如重复请求超时、401/403 错误、日志中的模型端点失败通过run_vscode_command工具执行 VS Code 命令github.copilot.debug.collectDiagnostics。该命令会返回完整诊断报告字符串可直接从工具输出读取报告内容包括认证与令牌状态网络可达性检查代理与证书配置扩展与环境详情命令同时会在编辑器中打开报告供用户查看可用返回的字符串诊断网络问题。源码佐证该命令在 loggingActions.ts 中注册含.internal变体命令常量定义于 constants.ts同时 vscodeCmdTool.tsx 将该命令列入可执行的 VS Code 命令工具与 Skill 文档描述的run_vscode_command用法一致工具名定义见 toolNames.ts。八、定制化文档参考与兜底方案8.1 定制化文档参考当调查涉及某类定制文件指令、提示词文件、代理等而需要核对预期格式或行为时可查阅 VS Code 官方文档对应页面Custom instructions、Prompt files、Custom agents、Language models、MCP servers、Hooks、Agent plugins用于验证文件格式期望、确认支持的字段、帮助用户修复定制文件。8.2 兜底方案Copilot Issues Wiki当调查无法得出明确根因、也没有具体修复建议时加载 Copilot Issues wiki 页面在返回的 wiki 内容中搜索与用户问题相关的章节在回复中总结适用的排查步骤若 wiki 包含相关指引将其作为用户可尝试的具体建议若 wiki 也无相关信息明确告知用户诊断日志未显示该行为的明确原因已知问题 wiki 也未覆盖此场景建议向 vscode 仓库提交 issue。九、回复准则如何向用户汇报回复应覆盖三部分内容但不需要为每部分单独设标题发生了什么及为什么根因或最可能的解释、来自日志的关键证据转述而非原始转储、如何修复或下一步尝试。9.1 格式要求使用标题、项目符号与加粗让回复可扫描段落保持简短优先列表而非大段文字引用日志证据时转述或总结不粘贴原始日志行若某细节很重要如错误消息只引用该消息本身对比多个值或事件时使用表格如名称不匹配、跨步骤延迟分解。9.2 抽象层级不要叙述调查过程不要说我正在调查会话调试日志……我在日志中找到了关键线索……我正在检查技能文件元数据……直接进入结论。不要使用内部术语如 discovery summary、frontmatter name、the loader、event hierarchy、span tree——用用户能行动起来的平实语言描述发生了什么。不要向用户描述内部日志文件结构、事件类型或 JSONL 格式——这些是实现细节用户无需知道。抽象地称呼日志文件如 the debug log 或 the session log而非main.jsonl、runSubagent-Explore-abc123.jsonl等字面文件名。聚焦发生了什么、为什么而不是你是怎么发现的。9.3 示例对比不好的示范叙述调查、使用内部术语、粘贴原始日志我正在调查会话调试日志以确认测试技能是否被发现。在技能发现摘要中加载器报告skipped: testing2 (name-mismatch)。SKILL.md 中的 frontmatter 名称与文件夹标识不匹配。好的示范简洁、用户友好、可操作testing 技能被发现但未加载原因是文件夹与技能文件之间存在名称不匹配值文件夹名testingSKILL.md 中的 nametesting2两者必须一致才能加载。如何修复二选一——将 SKILL.md 中的name: testing2改为name: testing或将文件夹从testing/重命名为testing2/然后开启新的聊天会话使其生效。十、重要规则速查没有证据就不要假设因果关系用run_in_terminal搜索日志文件——绝不用grep_search它无法访问工作区外文件macOS/Linux 用grep/jqWindows 用Select-String/node -e绝不用read_file整读日志文件——它们可能非常大。先搜索再用read_file读小范围保持日志访问的针对性与高效怀疑网络问题时先用run_vscode_command执行github.copilot.debug.collectDiagnostics并利用返回的诊断字符串再下结论无明确原因时先查阅 Copilot Issues wiki 再放弃wiki 也无相关信息时明确说出来。十一、扩展阅读仓库内的相关实现assets/prompts/skills/troubleshoot/SKILL.md本文的源文档可在仓库中查看其 frontmatter 与完整内容。src/extension/chat/vscode-node/chatDebugFileLoggerService.tsdebug 日志写入的完整实现涵盖 session 路由、文件命名、截断MAX_ATTR_VALUE_LENGTH 5000、TRUNCATION_RETAIN_RATIO 0.6、自动刷新默认FLUSH_INTERVAL_MS 4000与旧日志清理默认保留 50 个会话。src/platform/chat/common/chatDebugFileLoggerService.tsIDebugLogEntry规范定义与IChatDebugFileLoggerService服务接口。src/platform/configuration/common/configurationService.ts相关配置项chat.chatDebug.fileLogging.enabled默认 false、chat.chatDebug.fileLogging.flushIntervalMs默认 4000、chat.agentDebugLog.fileLogging.maxRetainedSessionLogs默认 50、chat.agentDebugLog.fileLogging.maxSessionLogSizeMB默认 100——注意文件日志功能默认关闭需要通过实验或配置开启。src/extension/tools/common/toolNames.tsgrep_search、run_in_terminal、run_vscode_command等工具名定义印证 Skill 文档中的工具使用约定。src/extension/log/vscode-node/loggingActions.tsgithub.copilot.debug.collectDiagnostics命令注册处。该仓库还包含src/extension/trajectory/下的轨迹日志体系ATIF 格式与本文的 debug-logs 属于互补的两种排查视角感兴趣的读者可继续阅读 src/extension/trajectory/ARCHITECTURE.md。结语无论问题是请求太慢工具被莫名调用还是技能/代理没有加载troubleshootSkill 提供的方法论都一致——用终端工具在 debug-logs 里找到证据沿spanId层级还原因果链最后用用户听得懂的语言给出可执行的修复方案。结合本仓库的源码你不仅能会读日志更能理解每一行日志背后的写入机制从而做出更精准的判断。赞分享人工智能AI 应用AI Agent代码智能体交互助手工具调用MCP Clients【免费下载链接】vscode-copilot-chatCopilot Chat extension for VS Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-copilot-chat点击查看免费下载相关推荐kkFileView CAD图纸浏览器批注速成指南在预览页上直接画标红kkFileView CAD图纸浏览器批注速成指南在预览页上直接画标红 施工例会刚结束总工把一份 .dwg 发过来让你确认两处改线而你的笔记本上只装了浏览后端从Serverless到AgentCubeSandbox背后的架构演进思考从Serverless到AgentCubeSandbox背后的架构演进思考 CubeSandbox 是一款面向 AI Agent 的高性能安全沙箱服务基于Agent 沙箱虚拟化云原生人工智能后端容器运行时VS Code Copilot Chat 变更日志解读从统一 Chat 视图到 MCP、Agent 会话与安全信任体系VS Code Copilot Chat 变更日志解读从统一 Chat 视图到 MCP、Agent 会话与安全信任体系 本文以 extensions/copi开发工具代码编辑器上一篇让旧款Mac重获新生OpenCore Legacy Patcher完整指南下一篇IntelliJ Platform 插件开发指南用 Configurable 为 IDEA Settings 对话框添加自定义设置项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考