Explain Changes

一个面向初学者的 VS Code 插件，用更易懂的语言解释代码改动、选中代码和整个项目结构，并提供版本快照、版本对比和报告查看能力。

核心功能

• 改动解释：把当前文件或工作区的代码改动总结成人话
• 代码解释：解释你选中的一段代码，并支持跳转回对应位置
• 项目分析：提供项目快速概览和深度分析
• 版本中心：保存版本快照、查看版本对比、重新生成版本文档、按文件回退
• 报告中心：集中查看历史生成的项目/版本/改动报告

安装方式

方式一：安装 VSIX

1. 在 VS Code 中打开命令面板
2. 运行 Extensions: Install from VSIX...
3. 选择打包好的 explain-changes-0.1.4.vsix
4. 安装完成后，左侧活动栏会出现 Explain Changes 图标

方式二：开发模式运行

npm install
npm run build

然后在 VS Code 中按 F5 启动扩展开发宿主窗口。

首次配置

在 VS Code 设置中搜索 Explain Changes，可配置以下选项：

基础配置

• explainChanges.maxCards
  • 每次生成最多输出多少张摘要卡片
  • 默认值：3

LLM 配置

• explainChanges.llm.engine

  • 可选值：rule / llm / auto
  • rule：只使用本地规则引擎
  • llm：只使用 LLM API
  • auto：优先使用 LLM，失败时回退到规则引擎

• explainChanges.llm.apiFormat

  • 可选值：anthropic-messages / openai-chat-completions
  • 用于选择 API 协议格式

• explainChanges.llm.baseUrl

  • LLM API 基础地址
  • Anthropic 常用：https://api.anthropic.com

• explainChanges.llm.apiKey

  • API 密钥 / 认证令牌

• explainChanges.llm.authHeader

  • 认证请求头名称
  • 默认值：x-api-key
  • 常见值：x-api-key、Authorization

• explainChanges.llm.model

  • 主模型名称
  • 默认值：claude-sonnet-4-6

• explainChanges.llm.modelHaiku

  • Haiku 模型映射（可留空）

• explainChanges.llm.modelSonnet

  • Sonnet 模型映射（可留空）

• explainChanges.llm.modelOpus

  • Opus 模型映射（可留空）

使用入口

1. 侧边栏入口

点击左侧活动栏中的 Explain Changes 图标，打开插件侧边栏。

侧边栏包含以下页面：

• 首页：所有功能入口总览
• 改动：解释当前改动，并查看改动历史
• 代码：解释选中代码，并查看解释历史
• 版本：保存和管理版本快照
• 项目：生成项目快速概览或深度分析
• 报告：查看已经生成的各类报告

2. 命令面板入口

打开命令面板后可直接运行以下命令：

• Generate Plain-Language Summary
  • 解释当前文件改动
• Generate Workspace Summary
  • 解释当前工作区改动
• Explain Selected Code
  • 解释当前选中的代码

典型使用流程

看懂当前改动

1. 修改代码
2. 打开侧边栏的 改动 页
3. 点击“生成改动解释”
4. 查看摘要卡片，并使用“查看对应代码”跳回代码位置

看懂一段代码

1. 在编辑器中选中一段 TypeScript / JavaScript / React / Python 代码
2. 右键菜单或命令面板运行 Explain Selected Code
3. 在 代码 页查看概览解释和逐行解释
4. 点击“跳转”返回对应代码位置

快速接手一个项目

1. 打开 项目 页
2. 选择“快速概览”或“深度分析”
3. 等待生成完成
4. 打开完整报告继续阅读

保存一个阶段版本

1. 打开 版本 页
2. 输入版本标题和说明
3. 点击“保存版本”
4. 插件会保存当前版本快照，并尝试自动生成版本文档
5. 在版本详情中可执行：
   • 打开版本文档
   • 版本对比
   • 重新生成报告
   • 快速概览 / 深度分析
   • 恢复某个变更文件

Git 仓库要求

版本中心依赖 Git。

如果当前项目还不是 Git 仓库，请先在项目目录执行：

git init

否则“保存版本”等功能会提示当前工作区不是 Git 仓库。

支持的语言

当前命令入口主要面向以下语言：

• TypeScript
• JavaScript
• TSX
• JSX
• Python

构建与打包

npm install
npm run lint
npm run build
npx @vscode/vsce package

打包后会生成类似下面的文件：

• explain-changes-0.1.4.vsix

推送到 GitHub 前建议保留的文件

建议提交：

• package.json
• package-lock.json
• tsconfig.json
• esbuild.config.mjs
• .vscodeignore
• .gitignore
• LICENSE
• src/
• media/

建议不要提交：

• node_modules/
• dist/
• *.vsix
• .explain-changes/
• .claude/worktrees/
• **/*.map

许可证

本项目仓库中包含 LICENSE 文件，请以仓库内许可证内容为准。