Skip to content

DEBUG.md

Latest commit

 

History

History
212 lines (190 loc) · 19.3 KB

DEBUG.md

File metadata and controls

212 lines (190 loc) · 19.3 KB

DEBUG 日志

[2026-02-01]

  1. [FEAT] 创建 AI 代码解释器 VS Code 插件 MVP (21:22)

    • 用户提问 (User Query)：用户希望开发一个 VS Code 插件，功能是选中代码后手动触发 AI 解释，并将结果显示在侧边栏。
    • 问题分析 (Analysis)：需求明确，技术栈 TypeScript + Node.js 是 VS Code 插件标准选择，无技术障碍。核心是实现命令注册、获取选中文本、调用 AI API、Webview 渲染。
    • 解决过程 (process)：
      • 原计划使用 yo code 脚手架，但检测到环境响应较慢
      • 决定直接手动创建项目结构，更快速可控
    • 解决方案 (Solution):
      • 创建 package.json：定义命令、右键菜单、配置项
      • 创建 tsconfig.json、.vscode/launch.json、.vscode/tasks.json：编译和调试配置
      • 创建 src/extension.ts：插件入口
      • 创建 src/commands/explainCode.ts：核心命令逻辑
      • 创建 src/views/ExplainPanel.ts：Webview 侧边栏面板
      • 创建 src/services/aiService.ts：OpenAI 兼容 API 调用封装
      • 创建 src/utils/config.ts：配置读取工具
    • 用户反馈 (Result)：待验证 (Pending)

  2. [FEAT] 添加 Mock 模式 + Gemini 配置 (21:33)

    • 用户提问 (User Query)：MVP 不需要配置 API 就能测试，API 配置改为 Gemini。
    • 问题分析 (Analysis)：原实现在无 API Key 时直接报错，不利于 UI 功能测试。需添加模拟模式并更新默认配置为 Gemini。
    • 解决过程 (process)：无意外问题
    • 解决方案 (Solution):
      • 修改 src/services/aiService.ts：添加 getMockExplanation() 方法，无 API Key 时返回模拟解释
      • 修改 package.json：默认模型改为 gemini-2.0-flash，API URL 改为 Gemini OpenAI 兼容接口
      • 修改 src/utils/config.ts：同步更新默认值
    • 用户反馈 (Result)：待验证 (Pending)

  3. [FIX] 修复扩展无法激活问题 (22:03)

    • 用户提问 (User Query)：扩展一直不能激活，按 F5 启动后无响应。
    • 问题分析 (Analysis)：activationEvents 为空数组，虽然 VS Code 1.74+ 支持隐式激活，但可能存在边界情况导致激活失败。另 tasks.json 仅有 watch 任务，可能影响首次编译。
    • 解决过程 (process)：检查编译输出目录 out/，确认所有 JS 文件存在且完整。
    • 解决方案 (Solution):
      • 修改 package.json：添加 "onCommand:ai-code-explainer.explainCode" 到 activationEvents
      • 修改 .vscode/tasks.json：添加独立的 compile 任务
      • 重新执行 npm run compile 确保编译成功
    • 用户反馈 (Result)：待验证 (Pending) - 启动方法:
      1. 在 VS Code 中打开此项目文件夹
      2. 按 F5 启动扩展开发主机
      3. 在新窗口中打开任意代码文件，选中代码，右键→"AI: Explain Selected Code"

[2026-02-02]

  1. [FIX] 修复 Gemini API 调用 404 错误 (00:50)

    • 用户提问 (User Query)：API 报错 "models/gemini-3.0-pro is not found"。
    • 问题分析 (Analysis)：用户配置的模型名 gemini-3.0-Pro 不存在，Gemini 目前可用模型为 gemini-2.0-flash、gemini-1.5-pro 等。
    • 解决过程 (process)：无意外问题。
    • 解决方案 (Solution): 修改 settings.json，将模型改为 "gemini-2.0-flash"。
    • 用户反馈 (Result)：已解决 - 插件正常工作，AI 解释功能可用

  2. [REFACTOR] 更新默认模型配置 (09:05)

    • 用户提问 (User Query)：用户询问是否可以将模型更换为 gemini-3.0-flash。
    • 问题分析 (Analysis)：虽然 gemini-3.0-flash 可能尚未正式发布或需特定权限，但在代码配置层面，用户希望将其设为默认值。代码透传模型参数，修改默认配置即可。
    • 解决过程 (process)：直接修改配置文件中的默认值。
    • 解决方案 (Solution):
      • 修改 package.json：aiCodeExplainer.model 默认值更新为 gemini-3.0-flash
      • 修改 src/utils/config.ts：getConfig 回退默认值更新为 gemini-3.0-flash
    • 用户反馈 (Result)：待验证 (Pending)

  3. [REFACTOR] 项目结构重构 + 设置页面 + 双模式问答 (12:45)

    • 用户提问 (User Query)：调整文件结构便于扩展，添加设置页面配置系统提示词，实现两种问答模式（快速模式/问答模式）。
    • 问题分析 (Analysis)：
      • 当前结构 services/aiService 和 views/ExplainPanel 不利于后续功能扩展。
      • 需要 ConversationManager 管理多轮对话记忆。
      • 需要独立的设置页面 (SettingsPanel) 供用户配置。
    • 解决过程 (process)：按三阶段执行：1) 文件结构重构 2) 设置页面 3) 对话模式。编译通过。
    • 解决方案 (Solution):
      • 新建 src/core/：types.ts (类型定义)、AIService.ts (重构)、ConversationManager.ts (对话记忆)、index.ts (导出)
      • 新建 src/panels/：ChatPanel.ts (原 ExplainPanel 重构，支持模式切换和追问)、SettingsPanel.ts (设置页面)
      • 新建 src/commands/openSettings.ts：打开设置命令
      • 更新 extension.ts：注册 openSettings 命令
      • 更新 package.json：新增 systemPrompt、defaultMode 配置项
      • 删除：旧的 src/services/ 和 src/views/ 目录
    • 用户反馈 (Result)：已解决

  4. [FIX] 修复模型 404 错误 (gemini-3.0-flash 不存在) (15:51)

    • 用户提问 (User Query)：调试时报错 models/gemini-3.0-flash is not found。
    • 问题分析 (Analysis)：
      • gemini-3.0-flash 是尚未发布/不存在的模型名，API 不认识。
      • 代码中的默认值已改为 gemini-2.0-flash，但 Antigravity 用户设置缓存了旧配置。
      • VS Code 配置优先级：用户设置 > 扩展默认值。因此即使代码改了默认值，用户设置仍会覆盖它。
    • 解决过程 (process)：
      • 使用 grep_search 搜索 aiCodeExplainer 配置项在所有相关目录的分布。
      • 发现 c:/Users/Lucas/AppData/Roaming/Antigravity/User/settings.json 中缓存了旧模型名。
    • 解决方案 (Solution):
      • 修改 Antigravity 用户设置文件，将 aiCodeExplainer.model 从 gemini-3.0-flash 改为 gemini-2.0-flash。
      • 同时更新了代码中的所有默认值（package.json、config.ts、SettingsPanel.ts）。
    • 用户反馈 (Result)：已解决 - 功能正常工作

  5. [FEAT] UI优化：代码折叠 + Markdown渲染 (17:30)

    • 用户提问 (User Query)：代码过多时希望折叠起来，AI 回答使用 Markdown 格式渲染并支持代码高亮。

    • 问题分析 (Analysis)：当前 ChatPanel.ts 使用 textContent 显示纯文本，无法渲染 Markdown。用户代码直接展示，量大时占满屏幕。

    • 解决过程 (process)：无意外问题，一次性实现。

    • 解决方案 (Solution):

      • 引入 CDN：marked.min.js + highlight.min.js + 主题 CSS
      • 新增 <details>/<summary> 可折叠代码块（>10行默认折叠）
      • 新增 .markdown-body 样式：标题、列表、代码块、引用、表格等
      • 修改 streamUpdate/end 事件：实时渲染 Markdown + 代码高亮
      • 主要修改：src/panels/ChatPanel.ts

    • 用户反馈 (Result)-实现的效果蛮差的

      fork the current chat 7. [REFACTOR] UI 深度优化：代码块工具栏 + 智能滚动 + 停止生成 (21:55)

      • 用户提问 (User Query)：Markdown 渲染效果差，缺乏交互功能（如复制代码、停止生成）。
      • 问题分析 (Analysis)：
        • 原实现仅有基础渲染，代码块无法一键复制。
        • 缺乏请求取消机制，长回复无法手动终止。
        • 自动滚动逻辑简单，用户手动向上查看时会被强制拉回底部。
      • 解决过程 (process)：
        • 在 AIService 中引入 AbortController 支持。
        • 在 ChatPanel Webview 中重写了渲染器，注入自定义按钮。
        • 增加了基于用户行为的智能滚动判断。
      • 解决方案 (Solution):
        • 修改 src/core/AIService.ts：chat 方法新增 AbortSignal 参数。
        • 修改 src/panels/ChatPanel.ts：
          • 实现 Stop 命令处理和请求中止逻辑。
          • Webview HTML 升级：增加代码块“复制”按钮、生成中的“停止”按钮、智能滚动逻辑。
          • 视觉升级：优化了 Markdown 字体、边距、引用块和代码块的 VS Code 风格适配。
      • 用户反馈 (Result)：待验证 (Pending)

[2026-02-03]

  1. [FIX] 修复快速模式体验问题 (00:57)

    • 用户提问 (User Query)：快速模式实现效果差，每次提问应该独立，不管理记忆。
    • 问题分析 (Analysis)：后端 ConversationManager.ts 已正确实现每次重置消息历史，但前端 UI 未同步清空聊天界面。用户看到旧对话残留，但 AI 不记得之前内容，造成体验割裂。
    • 解决过程 (process)：定位到 ChatPanel.ts 中模式切换和新对话开始时未清空界面的问题。
    • 解决方案 (Solution): 修改 src/panels/ChatPanel.ts：
      • 切换到快速模式时自动发送 cleared 消息清空聊天界面
      • 更新状态文本提示区分两种模式：「快速模式：每次独立提问」vs「问答模式：支持多轮对话」
    • 用户反馈 (Result)：待验证 (Pending)

  2. [FIX] 放宽右键菜单显示条件 (00:24)

    • 用户提问 (User Query)：刷新后右键菜单仍未出现。
    • 问题分析 (Analysis)：editor/context 菜单带 editorHasSelection 条件，若未先选中文本或焦点不在编辑器，菜单不会显示。核心矛盾是菜单显示条件过严，而非命令未注册。
    • 解决过程 (process)：检查 package.json 的 menus.editor/context 条件后，改为更宽松的 editorTextFocus。
    • 解决方案 (Solution): 修改 package.json：将 menus.editor/context 的 when 从 editorHasSelection 改为 editorTextFocus，保证在编辑器聚焦时即可看到命令。
    • 用户反馈 (Result)：待验证 (Pending)

  3. [FIX] 确认菜单不显示的真实原因是扩展版本未正确安装 (00:33)

    • 用户提问 (User Query)：要求记录原因：未正确安装 0.0.8 版本。
    • 问题分析 (Analysis)：右键菜单仍不出现的核心原因并非代码配置，而是扩展未实际安装到目标环境，导致菜单贡献未生效。核心矛盾是部署版本未落地。
    • 解决过程 (process)：用户明确反馈“AI Code Explainer 没有正确安装”，据此定位原因。
    • 解决方案 (Solution): 记录到 DEBUG.md：问题根因是未正确安装 0.0.8 版本，需按 VSIX 或开发主机方式重新安装。
    • 用户反馈 (Result)：正常使用

[2026-02-06]

  1. [DOCS] 新建分支迭代更新文档并建立实现状态跟踪 (20:13)

    • 用户提问 (User Query)：用户要求新建 improve1.2 分支，备注“codex 疯狂麦克斯改造版first”，并单独创建更新文档记录更新内容与实现情况。
    • 问题分析 (Analysis)：核心需求是将后续改造工作与现有分支隔离，并建立可持续追踪的文档锚点。仅有口头约定不利于后续验收，需要在仓库中落地一个明确文件来持续维护状态。简要概括：分支隔离 + 文档化追踪是本次任务主线。
    • 解决过程 (process)：先执行 git switch -c improve1.2 创建并切换分支；随后基于分支目标创建 UPDATE.md，加入分支信息、备注、更新清单、关键文件与实现状态定义，确保后续改造可持续追加。
    • 解决方案 (Solution):
      • 创建并切换分支：improve1.2
      • 新建 UPDATE.md：写入分支标识与备注，并以表格记录关键改造项（涉及 src/utils/config.ts、package.json、src/core/ConversationManager.ts、src/panels/ChatPanel.ts、src/core/AIService.ts、src/panels/SettingsPanel.ts）及当前实现状态。
    • 用户反馈 (Result)：待验证 (Pending)

  2. [REFACTOR] 解释器 first 改造：提示词升级 + 会话裁剪 + 配置热刷新 + 渲染安全加固 (20:21)

    • 用户提问 (User Query)：用户要求开始 improve1.2 的“codex 疯狂麦克斯改造版first”，重点包含解释器工作流优化与系统提示词升级。
    • 问题分析 (Analysis)：原实现存在四个核心问题：默认提示词约束弱导致输出不稳定；chat 模式历史无限增长导致上下文膨胀；设置保存后已打开面板不自动生效；Markdown 直接 innerHTML 渲染存在脚本注入风险。此外，追问文本在前端发送后先清空，导致展示不一致。简要概括：需要同时提升“稳定性、可控性、安全性、交互一致性”。
    • 解决过程 (process)：先新增统一默认提示词常量 DEFAULT_SYSTEM_PROMPT，再重构 ConversationManager 增加历史裁剪；随后为 AIService 增加 refreshConfig() 并在 extension.ts 监听配置变更触发 ChatPanel.refreshConfig()；最后在 ChatPanel.ts 增加 CSP、禁用 renderer.html、新增 sanitizeHtml()，并修复追问展示时序。中途 npm run compile 受 PowerShell 执行策略限制失败，改用 npm.cmd run compile 后编译通过。
    • 解决方案 (Solution):
      • 新增 src/core/defaultPrompt.ts：定义统一默认提示词 DEFAULT_SYSTEM_PROMPT。
      • 修改 src/utils/config.ts：getConfig() 的 systemPrompt 默认值改为引用 DEFAULT_SYSTEM_PROMPT。
      • 修改 package.json：更新 aiCodeExplainer.systemPrompt 的默认文本为结构化解释协议。
      • 修改 src/core/ConversationManager.ts：构造函数使用统一默认提示词；新增 trimHistory()，在 addUserMessage() 与 addAssistantMessage() 执行最近 8 轮裁剪。
      • 修改 src/core/AIService.ts：新增 refreshConfig()；构造时调用刷新；请求 URL 增加尾斜杠规范化。
      • 修改 src/extension.ts：新增 onDidChangeConfiguration 监听，命中 aiCodeExplainer 时触发 ChatPanel.currentPanel?.refreshConfig()。
      • 修改 src/panels/ChatPanel.ts：新增 refreshConfig()；修复 handleFollowUp() 透传展示文本；Webview 增加 CSP；marked 增加 renderer.html 屏蔽原始 HTML；新增 sanitizeHtml()；修复追问输入先清空导致 UI 显示“追问中...”的问题。
      • 修改 src/panels/SettingsPanel.ts：更新 systemPrompt 输入框 placeholder，使其与新提示词风格一致。
    • 用户反馈 (Result)：待验证 (Pending)

  3. [FIX] 完成 VSIX 打包与安装闭环，修复 Windows 下 vsce 打包 EPERM (20:57)

    • 用户提问 (User Query)：用户指出“没有打包成 vsix 文件并安装”，要求自动验证插件运行是否达到预期。
    • 问题分析 (Analysis)：在当前 Windows 环境中，vsce 触发 npm 相关流程会出现 spawn EPERM。根因不是代码编译失败，而是 vsce 在依赖检测/脚本调用阶段触发了受限执行链路。简要概括：需要绕开 vsce 的 npm 触发路径，改为可执行的本机打包流程。
    • 解决过程 (process)：先验证 npx.cmd @vscode/vsce 可用；尝试常规打包失败后，逐步收敛方案：移除 package.json 的 vscode:prepublish 钩子，先手动执行 npm.cmd run compile，再用 npx.cmd @vscode/vsce package --no-dependencies 成功产出 VSIX；最后使用 code.cmd --install-extension ... --force 完成安装并用 code.cmd --list-extensions 校验扩展已注册。
    • 解决方案 (Solution):
      • 修改 package.json：移除 scripts.vscode:prepublish，避免 vsce 打包时触发受限 npm 链路。
      • 生成文件：ai-code-explainer-0.0.9-improve1.2.vsix。
      • 安装验证：执行 code.cmd --install-extension "D:\\AboutWork\\AI\\code\\0201-codeExplain\\ai-code-explainer-0.0.9-improve1.2.vsix" --force 返回成功；code.cmd --list-extensions 检测到 your-publisher-name.ai-code-explainer。
    • 用户反馈 (Result)：待验证 (Pending)

  4. [FEAT] 将设置框集成到聊天对话面板 (22:53)

    • 用户提问 (User Query)：用户要求“将设置框集成到对话框中”，希望在聊天面板内直接修改系统提示词等配置。
    • 问题分析 (Analysis)：原实现的设置入口独立在 SettingsPanel.ts，导致“解释-调参-再解释”流程被拆断。核心问题是配置路径与对话路径分离，增加了操作成本。简要概括：需要把设置入口内聚到 ChatPanel，形成单面板闭环。
    • 解决过程 (process)：先在 ChatPanel 后端消息分发中新增 getSettings/saveSettings，复用 updateConfig 持久化并调用 refreshConfig 即时生效；再在 Webview 顶部增加“设置”按钮与弹层表单（模式、系统提示词、模型、API Key、Base URL）；最后通过 settings/settingsSaved/settingsSaveError 消息完成前后端同步，并重新编译确认通过。
    • 解决方案 (Solution):
      • 修改 src/panels/ChatPanel.ts：
        • 新增后端方法 saveSettings()，接入 updateConfig() 并同步 ConversationManager 模式与系统提示词。
        • 新增消息命令：getSettings、saveSettings。
        • Webview UI 新增 settings-modal 弹层与“设置”按钮，支持在面板内编辑并保存配置。
        • 前端新增 openSettingsModal()、savePanelSettings()、updateModeUi()，保存后自动关闭弹层并更新模式状态文案。
      • 验证：执行 npm.cmd run compile 编译通过。
    • 用户反馈 (Result)：待验证 (Pending)

  5. [FIX] 右键菜单可见性兜底：新增编辑器标题栏入口并三端重装 (00:26)

    • 用户提问 (User Query)：用户反馈“没有安装成功，右键没有选择项”。
    • 问题分析 (Analysis)：排查后确认扩展已安装到 VS Code、Cursor、Antigravity 三个客户端，且扩展清单中存在 editor/context 菜单贡献。核心问题更像是入口可见性不稳定或使用场景差异（例如不在文本编辑器上下文）。简要概括：安装本身成功，但需要增加更稳定的可见入口。
    • 解决过程 (process)：先探测本机多客户端命令路径，分别安装并验证扩展 ID；再读取三个客户端的扩展目录 package.json，确认命令与菜单贡献均存在；随后修改 package.json 增加 editor/title 入口并保留右键入口，重新打包 VSIX，三端强制安装。
    • 解决方案 (Solution):
      • 修改 package.json：
        • menus.editor/context.when 调整为 editorTextFocus || editorHasSelection
        • 新增 menus.editor/title 挂载 ai-code-explainer.explainCode
      • 重新打包：ai-code-explainer-0.0.9-improve1.2.vsix
      • 三端安装与校验：
        • code.cmd --install-extension ... --force
        • cursor.cmd --install-extension ... --force
        • antigravity.cmd --install-extension ... --force
        • 三端 --list-extensions 均检测到 your-publisher-name.ai-code-explainer
    • 用户反馈 (Result)：待验证 (Pending)