AI Code Tutor — V0.5

一个“住在 IDE 里的动画 AI 编程导师”原型。

首发平台是 VS Code Extension，但核心代码从一开始就按“编辑器无关”设计：

• src/core/：编辑器无关的 Tutor Core
• src/adapters/vscode/：VS Code 适配层
• src/ui/：VS Code 里的角色面板
• 未来可以增加 adapters/jetbrains/、adapters/zed/ 等

V0.5 新增

1. 新增“随时打断我”文字提问区，不需要重新选择代码
2. 提问时自动停止当前 TTS，并保留正在讲的步骤和代码高亮
3. AI 答疑会携带当前文件、当前步骤、主讲解总结和步骤附近代码作为上下文
4. 新增快捷提问：讲简单一点、为什么这样写？、举个例子
5. 回答完成后可以继续追问，也可以点击“继续原讲解”回到被打断的步骤
6. 如果打断前正在连续讲解，继续原讲解时会从当前步骤重新朗读并恢复连续播放
7. 新增 Tutor 状态：教学中 / 在听问题 / 思考中 / 正在答疑 / 讲解暂停
8. 问答使用独立的 editor-independent Core 服务，为未来 JetBrains / Zed 复用保留接口边界

V0.4 新增

1. 新增“连续讲解”模式：从当前步骤开始自动朗读
2. 当前步骤语音结束后，自动切到下一段并同步代码高亮
3. 新增讲解状态：等待 / 正在讲 / 暂停 / 准备下一段 / 完成 / 错误
4. 新增暂停与继续控制，暂停时保留当前代码高亮
5. 新增“重讲当前段”，不需要重新请求 AI
6. 新增语音进度条；浏览器提供 boundary 事件时会显示近似朗读进度
7. 连续讲解过程中，角色嘴型、等待动作和完成反馈会跟着语音状态变化
8. 手动切换步骤或点击步骤卡片时会停止连续讲解，避免语音和高亮错位
9. 最后一段结束后进入“讲解完成”状态，再次点击“连续讲解”会从第一段重新开始

V0.3 新增

1. 当前讲解代码使用双层 Decoration：精确 Range 高亮 + 整行引导线
2. 当前代码旁显示 ← AI Tutor 正在讲这里，让“老师正在讲哪儿”更直观
3. Overview Ruler 同步标记当前讲解位置
4. VsCodeEditorAdapter 会记住真正被解释的代码编辑器
   • 即使用户点击右侧 Webview，再按“上一段 / 下一段”也不会丢失目标文件
5. 切换讲解步骤时自动把对应 Range 滚动回视野
6. 角色默认面向左侧代码区，point 动作会明显伸手指向代码
7. 角色面板增加“正在指向第 X–Y 行”提示
8. 当前步骤卡片强化高亮并自动滚动到可见区域

V0.2 新增

1. 新增真实 OpenAiTutorProvider
2. 使用 OpenAI Responses API 分析选中代码
3. 使用 Structured Outputs，让 AI 固定返回：
   • summary
   • steps[]
   • 每一步对应真实文件行号
   • 每一步的角色动作
4. AI 返回行号后转换成 CodeRange，驱动 VS Code 高亮
5. OpenAI API Key 使用 VS Code SecretStorage 保存，不写入源码或 settings.json
6. 新增命令：
   • AI Code Tutor: 设置 OpenAI API Key
   • AI Code Tutor: 清除 OpenAI API Key
7. 新增 Provider 设置，可在 openai 和 local 之间切换
8. 新增模型设置，默认 gpt-5.6
9. AI 请求时显示 VS Code Progress 提示
10. 加入超时、HTTP 错误、拒绝、空响应、格式错误处理

V0.1 已有能力

1. VS Code 插件骨架
2. 读取当前文件、语言、光标、选区
3. 未选中文本时自动使用当前行
4. 获取 TextDocument.isDirty（已保存 / 未保存状态）
5. 监听编辑和保存事件，实时更新角色面板状态
6. 根据讲解步骤高亮指定代码 Range
7. Webview 动画角色原型
8. 上一段 / 下一段讲解
9. 点击讲解步骤重新定位代码
10. 浏览器 TTS 原型（“朗读”按钮）
11. TutorProvider 抽象层

运行

npm install
npm run compile

然后用 VS Code 打开这个项目，按 F5。

VS Code 会启动一个新的 Extension Development Host 窗口。

第一次使用真实 AI

在新窗口中：

1. Ctrl+Shift+P
2. 执行 AI Code Tutor: 设置 OpenAI API Key
3. 输入你的 OpenAI API Key
4. 打开任意代码文件
5. 选中一段代码（不选则使用当前行）
6. Ctrl+Shift+P
7. 执行 AI Code Tutor: 解释选中代码

也可以直接右键选中的代码，点击 AI Code Tutor: 解释选中代码。

API Key 通过 VS Code SecretStorage 保存，不会加入 Git，也不会写到项目代码中。

设置

打开 VS Code Settings，搜索 AI Code Tutor。

Provider

aiCodeTutor.provider = openai | local

• openai：真实 AI 讲解
• local：V0.1 本地演示模式，不调用 API

Model

aiCodeTutor.openAI.model = gpt-5.6

可以以后改成其他支持 Structured Outputs 的 OpenAI 模型。

Timeout

aiCodeTutor.openAI.timeoutSeconds = 45

V0.2 调用链

VS Code
    ↓
VsCodeEditorAdapter
    ↓
EditorContext
    ↓
TutorEngine
    ↓
OpenAiTutorProvider
    ↓
OpenAI Responses API
    ↓
Structured JSON
    ↓
TutorExplanation
    ↓
代码 Range 高亮
+
角色动作
+
文字讲解
+
TTS

AI 返回的结构

AI 返回的是结构化数据，而不是一大段随意文字：

{
  "summary": "这段代码负责给管理员路由统一加权限验证。",
  "steps": [
    {
      "id": "register-middleware",
      "title": "注册管理员中间件",
      "explanation": "app.use 会让后续匹配 /api/admin 的请求先经过 requireAdmin。",
      "startLine": 136,
      "endLine": 139,
      "action": "point"
    }
  ]
}

Provider 再把 AI 返回的真实文件行号转换成编辑器无关的 CodeRange。

即使模型返回了超出当前选区的行号，插件也会把范围限制回当前选区，避免角色指错代码。

跨 IDE 原则

core 不能依赖 vscode。

例如 OpenAiTutorProvider 只认识：

EditorContext
API Key
模型名

它不知道 vscode.TextEditor 是什么。

未来 JetBrains 只需要实现：

JetBrains API
      ↓
JetBrainsEditorAdapter
      ↓
EditorContext
      ↓
同一个 TutorEngine
      ↓
同一个 OpenAiTutorProvider

因此 VS Code 是第一款客户端，而不是产品本身。

下一步（V0.6）

重点从“文字可打断答疑”升级到“语音可打断答疑”：

1. 用户可直接说“等等”“继续”“上一段”等控制讲解
2. 支持麦克风语音提问，并复用 V0.5 的同一套问答上下文
3. AI 回答可以选择自动朗读，回答结束后继续主讲解
4. 增加语音、语速、自动播放等 Tutor 设置
5. 开始把 CSS 占位机器人抽象成可替换动画角色资源
6. 为未来 JetBrains 等 IDE 继续抽离 Tutor UI / Voice 协议