扩展安全、维护与排障

扩展把多个能力装在一个包里，定位故障时先区分包未加载、某个 MCP 未启动、命令冲突和设置缺失。

扩展不在列表

检查 gemini-extension.json 是否在根、JSON 是否有效、name 与目录是否一致。当前命令参考列出 /extensions restart，命令定义可用 /commands reload；扩展专页仍要求重启会话，若当前版本不支持重载或修改未生效则重启 CLI。link 成功不代表运行中的会话自动重新扫描全部配置。

MCP 工具不可用

核对 manifest 的 command、args 和 cwd，并独立启动服务确认依赖齐全。F12 打开交互调试控制台查看错误；扩展已显示不等于其中的 MCP 已连接。

本地 settings.json 可能覆盖同名服务或过滤工具，按MCP 配置检查最终集合。

命令被其他来源覆盖

用户与项目命令优先于扩展。用 /help 查来源，再尝试带扩展点前缀的名称，例如 /extension.command。这与目录命名形成的冒号分组不同。

凭据与设置

必需变量应通过 manifest settings 声明，敏感项使用 sensitive true。安装使用 skip-settings 后需要补配置；不要为解决空变量把 key 写回共享 manifest。

输入与边界

官方建议限制工具权限并验证路径。示例中的 path.resolve 字符串前缀检查只是基础演示，不足以证明处理了符号链接、目录本身和平台差异。实际服务应按任务定义允许范围，并针对越界输入验证。

维护版本与产物

工具改名或参数不兼容应反映破坏性版本变化，新增能力与修复也要清楚标识。发布前测试实际归档而不只是开发目录，检查入口、依赖与资源齐全；版本号、Release tag 和界面显示应一致。