必须启用VSCode 1.80+的"workbench.experimental.multimodalAnnotations":true和"comments.allowMedia":true，并安装官方GitHub Pull Requests and Issues扩展，且在已关联远程PR的Git仓库中使用，否则批注无法持久化或显示。
VSCode 的代码标注（Comments）不是“加个注释就完事”的功能，它是一套可绑定上下文、支持富媒体、能进 Git 流程的协作基础设施。但默认关闭，且容易配错路径或权限导致批注不持久、不同步、甚至不显示。
如何启用多模态标注并确保它真正生效
很多人以为装个插件或改个设置就完事，结果发现右键菜单没选项、命令面板搜不到 Toggle Multi-modal Annotation，或者上传图片后刷新就丢失——根本原因是实验性 API 未开启，且依赖特定扩展协同工作。
- 必须使用 VSCode 1.80 及以上版本；低于此版本的
workbench.experimental.multimodalAnnotations配置项无效 - 在
settings.json中同时启用两项配置："workbench.experimental.multimodalAnnotations": true和"comments.allowMedia": true - 安装官方扩展
GitHub Pull Requests and Issues（非第三方“Comment”类插件），否则媒体文件无法持久化存储到 GitHub 关联的 PR 上 - 重启 VSCode 后，只有在已打开的 Git 仓库中、且当前分支有对应远程 PR 时，标注才支持绑定提交；纯本地文件或未初始化 Git 的项目里，只能存为临时会话级批注
为什么截图/语音上传后不显示或报错 File size exceeds limit
VSCode 默认限制单个媒体文件大小为 512KB，但实际上传失败往往不是因为文件太大，而是服务端策略或扩展未激活导致的静默截断。
- 显式设置
"comments.maxFileSizeKB": 5120（即 5MB），但该值仅对GitHub Pull Requests and Issues扩展生效；若用其他 Git 托管平台（如 GitLab），需确认其 API 是否支持 media upload endpoint - 拖拽图片时若出现灰色虚线框但松手无反应，大概率是扩展未启用或当前文件未关联到 PR —— 检查左侧活动栏是否有
GitHub图标，点击进入确认 PR 状态 - 语音录制依赖系统麦克风权限；macOS 上需在「系统设置 > 隐私与安全性 > 麦克风」中允许 VSCode 访问，Windows 则检查「设置 > 隐私 > 麦克风」
add(a, b) 这类函数旁的标注为何无法触发 JSDoc 智能提示
这是两个不同机制：JSDoc 注释块（/** ... */）由语言服务器解析，用于类型推导和补全；而代码标注（Comments）是 UI 层协作层功能，两者不互通。你不能指望在标注里写 @param 就让参数提示弹出来。
- 标注内容不会参与 TypeScript 类型检查或 VSCode 的 IntelliSense；它只渲染在编辑器右侧边栏或行号旁的小图标上
- 若想让函数具备自动补全能力，必须用标准 JSDoc 块注释写在函数声明上方，且确保已启用
javascript.suggest.autoImports和typescript.suggest.autoImports - 标注里嵌入的代码片段（如可运行示例）只是静态文本，不执行、不校验语法；要测试逻辑，仍需复制到调试终端或 REPL 中
真正难的是让标注在多人协作中保持上下文完整——比如某人修改了 add 函数签名，旧标注里的截图和语音还在，但指向的代码行已偏移。VSCode 会尝试按行号做模糊匹配，但一旦缩进、空行或重构发生，标注就可能挂错位置。这不是 bug，是设计使然：它优先保证轻量，而非强一致性。
