水杉·教学助手
在 VS Code 内一站式完成水杉在线平台的作业查看与提交、课件与视频学习，无需频繁切换浏览器。内置 AI 编程智能体，可直接在编辑器内读写源文件、执行命令、诊断错误，形成"发现问题 → 修复 → 验证"的闭环。
功能
- 🔐 登录：侧边栏输入水杉账号密码登录，Token 加密存储于 VS Code Secrets，自动续期。
- 👤 用户信息：侧边栏顶部账号卡片，显示头像、姓名、手机号；提供「个人主页」入口与「退出登录」按钮。
- 📚 资源中心：课程 → 周进度 → 资源 三级树；顶部「待办作业」跨课程聚合、按截止时间排序、带倒计时配色。
- 📝 作业工作区：点击作业自动创建工作夹（含说明与老师附件），记录「作业 ↔ 文件夹」绑定，新窗口打开即可写代码。
- ☁️ 智能提交：绑定文件夹内单文件直接交、多文件可选，提交前二次确认；提交情况面板显示是否已交、批改状态、得分与教师评语。
- 📄 课件打开：
- PDF 直接在 VS Code 内翻页阅读（可选中/复制文字）；
- 图片 / 文本 / 代码 / Notebook 用编辑器原生打开；
- PPT / Word / 压缩包等下载后交由系统默认程序打开。
- 🎬 视频播放：阿里云 VOD 视频在 VS Code 内直接播放（含字幕控件），B 站等外链自动在浏览器打开；若当前编辑器内核不支持视频解码则自动降级到浏览器，不留黑屏。
- 🧰 其他 / 实训 / 通知：其他与实训资源按类型打开，通知以文本查看。
- 👤 个人主页：点击账号卡片的「📋 个人主页」按钮，在编辑器 Tab 中查看完整个人信息。
- 📊 行为遥测：内置学生编程行为采集系统，支持代码运行结果(RUN_RESULT)事件和场景检测(homework/drill/practice/freeform)，用于教学分析和个性化指导。
🤖 AI 编程智能体
侧边栏「水杉 AI」聊天面板背后挂着一套可调用 IDE 工具的智能体，不只是回文字——它能直接操作你的代码。
📖 详细使用指南、FAQ、技术实现：见 docs/ai-agent.md
可用工具
| 工具 |
作用 |
read_file(path) |
读取工作区内的文件内容 |
write_file(path, content) |
直接修改/创建源文件（弹 Diff 预览，确认后才写磁盘） |
edit_file(path, edits[]) |
局部编辑文件的某几段（省 token，Diff 更聚焦） |
list_dir(path?, maxDepth?) |
列出目录结构（自动忽略 node_modules 等噪音目录） |
run_command(command) |
在终端执行命令（如 git status、npm test），输出回传给 AI |
get_diagnostics(path) |
获取当前文件的编译错误 / 警告列表 |
触发方式
| 方式 |
操作 |
| 聊天提问 |
侧边栏发消息，AI 自动判断是否需要调工具 |
| 右键菜单 |
在代码编辑器内右键 → 水杉 AI: 一键修当前文件的 bug |
| 命令面板 |
Ctrl+Shift+P → 搜索 水杉 AI: ... |
右键菜单命令
- 水杉 AI: 聊天 — 打开聊天面板
- 水杉 AI: 解释这段代码 — 选中代码后调用
- 水杉 AI: 调试这段代码 — 选中代码后调用
- 水杉 AI: 优化这段代码 — 选中代码后调用
- 水杉 AI: 一键修当前文件的 bug — 自动读取 IDE 诊断 + 代码 → AI 调用
get_diagnostics → read_file → write_file 完成修复闭环
- 水杉 AI: 运行选中的代码 — 选中代码片段，AI 自动选合适的运行命令（python/node/javac/go 等），输出回传到聊天面板由 AI 解释
- 水杉 AI: 运行当前文件 — 不选中时跑整个文件，根据扩展名自动匹配运行命令
安全约束
- 逐次确认：每一次工具调用都会弹卡片让你点 ✅ / ❌，AI 不会私自改文件
- IDE 原生 Diff 预览：
write_file 执行前会打开 VSCode 内置的 vscode.diff 编辑器（左右对比、语法高亮、行号同步、可折叠），看清楚再点"应用"。你甚至可以在 Diff 编辑器右侧手动微调 AI 的提案，点确认后插件会用你编辑后的版本写回文件
- 内存 / 硬盘三方同步：插件在 AI 读/写前会自动保存未保存修改，保证"你在编辑器看到的 = AI 读到的 = AI 写入的"，不会出现 AI 基于旧版本瞎改的尴尬
- 路径沙箱：所有文件操作必须在当前工作区 / 当前文件所在目录内，路径穿越会被拦截
- 命令黑名单：
run_command 拒绝 rm -rf /、format c:、shutdown 等危险命令，30 秒超时防卡死
- 循环上限：单次对话最多 8 轮工具循环，防止 token 爆炸
典型使用场景
| 场景 |
操作 |
预期 |
| 一键修 BUG |
打开一个有语法错的 .py → 右键"一键修当前文件的 bug" |
AI 跑 get_diagnostics 看错误 → read_file 看代码 → write_file 修复 → 弹 Diff 让你确认 |
| 改完跑测试 |
聊天框："帮我修这个测试用例，改完跑一下 pytest" |
AI 改代码 → 跑 pytest 看结果 → 还有失败就继续改，直到全绿 |
| 跑选中代码 |
选中一段 Python 片段 → 右键"运行选中的代码" |
AI 写到临时文件 → python tmp_xxx.py → 输出回聊天面板由 AI 解释 |
| 查环境信息 |
聊天框："看看我这个 Node 环境怎么样" |
AI 跑 node --version && npm list → 总结版本号 |
| Diff 里微调 |
AI 要改文件 → 弹 vscode.diff → 你在右侧改几行 → 点 ✅ |
插件用你编辑后的版本写回文件，而不是 AI 最初的提案 |
工具历史侧边栏
侧边栏水杉面板的 工具历史 视图（🕘 图标）展示你最近 100 条工具调用记录，按 今天 / 昨天 / 更早 分组。点击某条记录弹出 WebView 显示完整 input/output（带复制按钮），方便回溯"刚才 AI 看了哪些文件、跑了什么命令"。每次工具调用会自动上报到后端（脱敏 + 截断），为教师端报表提供数据。
快速开始
- 在扩展面板搜索「水杉」并安装（或从
.vsix 安装）。
- 点击活动栏的水杉图标，打开侧边栏并登录。
- 展开课程 → 周 → 资源：
- 作业：点击创建工作区、编写后用内联「提交」按钮上交；
- 课件 / 视频 / 其他：直接点击查看或播放。
- 体验 AI 智能体：
- 打开任意代码文件 → 在聊天框发"读一下 package.json 的版本号" → 看工具卡片弹出来 → 点 ✅；
- 写一个故意有 bug 的文件 → 右键"一键修当前文件的 bug" → 观察 AI 自动走
get_diagnostics → read_file → write_file 闭环，Diff 在 IDE 编辑器区打开；
- 选中一段代码 → 右键"运行选中的代码" → AI 自动选运行命令，输出回传到聊天面板由 AI 解释；
- 没选中时 → 右键"运行当前文件" → 适合跑整个脚本（
.py / .js / .ts / .sh 等）。
配置
在 VS Code 设置中搜索「水杉」：
| 配置项 |
默认值 |
说明 |
shuishan.baseUrl |
https://www.shuishan.net.cn/api |
平台 API 基础地址 |
shuishan.oauthClientId |
system |
OAuth2 客户端 ID |
shuishan.oauthClientSecret |
（空） |
OAuth2 客户端密钥（一般无需填写） |
shuishan.aiBaseUrl |
（生产） |
磐恰 AI 后端地址（JWT Token Exchange 路径） |
shuishan.aiAgentId |
（空） |
教学 Agent ID，可覆盖默认对话人设 |
shuishan.ai.autoApproveReadonly |
false |
yolo 模式：自动批准只读工具（read_file / list_dir / get_diagnostics），写文件 / 跑命令仍要确认 |
shuishan.telemetryEnabled |
true |
启用行为事件上报（含工具调用历史） |
开发
npm install
npm run compile # 编译
npm run watch # 监听编译
# 按 F5 在 Extension Host 中调试
第三方组件
- PDF.js（Apache-2.0，Mozilla）——用于 PDF 课件渲染，许可见
media/pdfjs/LICENSE。
- Aliplayer（阿里巴巴）——用于视频播放，运行时从阿里云 CDN 加载，未随插件分发。
版权
© 华东师范大学数据科学与工程学院 水杉团队。保留所有权利。详见随附的 LICENSE 文件。
联系方式：fanyang@stu.ecnu.edu.cn
| |
