通义灵码需重启VS Code激活，行级补全须在可推断语法上下文触发，/explain等指令仅在专用面板有效，单元测试需指定框架名，跨文件分析依赖语义索引完成。
通义灵码在 VS Code 中不是装上就能“自动变强”的工具——它需要明确触发、合理选中上下文、并避开几个默认配置下的典型失效点。直接按 Tab 补全失败、/explain 没反应、生成代码不贴合项目风格，基本都卡在这几步。
安装后必须重启 VS Code 才能激活插件
很多用户装完就立刻去写代码，结果状态栏没图标、右键无菜单、快捷键无效。这不是 bug，是 VS Code 插件机制要求：安装后必须完整重启编辑器（不只是重载窗口），否则插件进程不会加载。
- Windows/macOS/Linux 均适用；关掉所有 VS Code 窗口，再重新打开
- 确认状态栏右下角出现
Tongyi Lingma图标（通常是个蓝白齿轮或 AI 字样） - 若仍不显示，检查是否被其他插件禁用：按
Ctrl+Shift+P输入Extensions: Show Enabled Extensions，搜索Tongyi Lingma确保状态为“已启用”
行级补全失效的三个常见原因
灰色建议代码不出现、按 Tab 没反应、或者只补全了半行就停住——大概率是触发条件没满足。
- 光标必须位于**可推断语法上下文的位置**：比如函数体内、字符串引号外、
if后面空格处；写在注释里、JSON 值中、或未闭合的括号内都会跳过 - 自动补全默认仅对部分语言生效：Python/Java/TypeScript 默认开，但
.sh、.yml、.md文件需手动开启——按Ctrl+,搜索lingma file exclude，清空或删掉这些后缀 - 网络请求超时会静默失败：状态栏图标变灰、鼠标悬停提示“模型未响应”，此时需检查代理设置或切换到“本地模型”模式（设置中搜
lingma model mode）
/explain、/optimize 等指令必须在通义灵码专用面板中输入
很多人直接在代码文件里敲 /explain，或在终端里输，结果毫无反应。这些指令只在通义灵码左侧弹出的聊天面板中有效。
- 先用鼠标选中目标代码块（支持多行），再点击侧边栏
Tongyi Lingma图标唤出面板 - 面板顶部输入框中输入
/explain或/optimize，**不要加空格或换行**，直接按Enter - 若想让解释更聚焦，可在指令后追加说明，例如：
/explain 解释为什么这里要用 asyncio.gather 而不是 await - 生成结果默认不插入原文件，需手动点面板上方的
Insert按钮；误点Enter提交太快，可用Ctrl+Enter（Windows）换行
生成单元测试时框架名必须拼写准确且紧贴指令
/unittest 默认用 Python 的 unittest 框架，但如果你项目用的是 pytest，只输 /unittest 会生成不兼容的断言风格。
- 正确写法是：
/unittest pytest（中间无换行，无多余空格） - Java 用户要指定
/unittest junit5，否则可能输出 JUnit 4 风格的@Before - 生成的测试代码默认不含
if __name__ == "__main__"或public static void main，需自行补全运行入口 - 如果函数依赖外部服务（如数据库、HTTP 请求），通义灵码不会自动 mock，得靠你后续手动加
patch或@mock.patch
最常被忽略的一点是：通义灵码对“当前文件以外的上下文”感知依赖于 VS Code 的语义索引（Semantic Indexing）。大型单体项目首次打开时，它可能花 1–2 分钟建立跨文件引用关系——这期间 /explain 或跨函数补全大概率不准。别急着换模型或重装，等状态栏图标从“加载中”变成稳定蓝色即可。
