用于AI驱动式开发的Amazon Devices Builder Tools故障排除
此页面可帮助您解决在设置和使用“用于AI驱动式开发的Amazon Devices Builder Tools”时遇到的常见问题，包括连接错误（MCP error -32000: Connection closed（MCP错误-32000：连接已关闭））、缺少上下文文档以及未能触发技能。每个问题都包括问题描述、可能的原因和分步解决方案。
有关设置说明，请参阅设置用于AI驱动式开发的Amazon Devices Builder Tools。
在您进行故障排除之前
确认Amazon Devices Builder Tools正在运行并已连接到您的AI代理。在您的代理聊天中，输入：
列出Amazon Devices Builder Tools提供的工具
您应该看到包含工具的响应，其中包括analyze_perfetto_traces、get_app_hot_functions、list_documents、read_asset、read_document、search_documentation和symbolicate_acr。
您也可以运行check-status命令来验证您的设置：
npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status
完全配置后，您将看到和以下类似的输出：
代理 │ 上下文文档 │ MCP配置
───────────────────────┼──────────────────────────┼──────────────────────────
Kiro │ ✅ v5.1 │ ✅ 已配置
📊 摘要：
检查的代理总数： 1
✅ 完全配置： 1
如果出现工具列表且check-status显示您的代理已完全配置，则表示MCP服务器正在运行。如果不是这样，请继续查看下一部分中的问题。
常见问题
对于大多数问题，首先从您的项目目录运行check-status。它会验证所有支持的代理的上下文文档（存在、版本、损坏）和MCP配置。
AI代理不会使用Amazon Devices Builder Tools来回答与Vega相关的问题
原因： MCP服务器的安装或配置出现问题，或者AI代理在配置后需要重新启动。
解决方案：
-
验证MCP服务器的安装情况：
npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help如果程序包正确安装，您将看到一条帮助消息，其中列出了可用命令（
init-context、check-status）。如果未安装程序包，则会看到“command not found”（未找到命令）或模块解析错误。运行set-up command来安装它。
- 确认您的AI代理设置文件中的
mcpServers下存在amazon-devices-buildertools-mcp条目。 - 配置更改后，重新启动您的AI代理。
-
通过询问亚马逊设备特定的问题来验证修复效果。
示例： “How do I build a Vega app?”（如何构建Vega应用？）
如果代理以特定于亚马逊设备的步骤进行响应，则问题得到解决。
错误消息显示，文档未包含在amazon-devices-buildertools-mcp版本中
原因： 文档名称存在拼写错误、文档不存在或您的MCP服务器版本已过时。
解决方案：
-
列出可用文档：
为我显示Amazon Devices Builder Tools中的所有文档 - 将您使用的文档名称与步骤1中返回的列表进行比较。验证名称是否存在以及拼写是否完全匹配。
-
重新运行
init-context来刷新上下文文档。在npx命令中使用@latest总是会获取最新版本：npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context - 使用正确的名称重试文档请求。如果加载文档，则问题得到解决。
AI代理提供通用响应，而不是特定于亚马逊设备的指导
原因： 上下文初始化未完成、上下文文件丢失或AI代理无法识别上下文文件。
解决方案：
-
从您的项目目录运行
check-status（请参阅故障排除之前）。如果输出内容中显示问题，请遵循其提供的建议。 -
如果
check-status显示上下文文档缺失或已过期，请重新运行init-context（参见开始使用）。 -
关闭您当前的聊天对话并开始新的聊天对话。
-
询问特定于亚马逊设备的问题，以确认代理能够提供相关指导。
示例： “Can you list all documents related to feature development on vega?”（可以列出所有与Vega上功能开发相关的文档吗？）
如果代理以特定于亚马逊设备的指导进行响应，则问题得到解决。
代理技能不能自动触发
原因： 您的AI代理需要上下文初始化才能检测技能。如果没有正确设置，代理将无法识别技能元数据。
解决方案：
-
从您的项目目录运行
check-status以验证您的整体设置，包括技能安装（请参阅故障排除之前）。 -
如果
check-status报告问题，则重新运行init-context以确保技能已安装（请参阅开始使用）。 -
验证代理的全局技能目录中是否存在SKILL.md文件。常见技能目录位置：
AI代理 技能目录路径 Kiro ~/.kiro/skills/Cursor 项目根目录中的 ~/.cursor/skills/或.cursor/skills/Claude Code ~/.claude/skills/ -
重启您的AI代理会话。
技能根据提示匹配触发。使用与技能相关的特定关键字。
示例： “Set up Vega SDK for the
amazon-devices-vega-setup-sdkskill”（为amazon-devices-vega-setup-sdk技能设置Vega SDK）。 -
如果技能仍然未触发，则先列出可用技能：
列出所有可用的Amazon Devices Builder Tools技能然后，引用特定技能：
使用amazon-devices-vega-build-and-run技能来帮我部署应用如果技能触发并提供指导性步骤，则问题得到解决。
自动加载不必要的代理技能
原因： init-context命令会全局安装所有可用的代理技能。您可能需要移除与工作流无关的特定技能。
解决方案：
-
找到您的AI代理的技能目录（参见技能目录位置）。
-
删除要移除的技能的SKILL.md文件。
例如，要移除
amazon-devices-vega-media-player技能，请运行以下命令：rm ~/.kiro/skills/amazon-devices-vega-media-player/SKILL.md -
重启您的AI代理会话。移除的技能不再触发。
init-context会重新安装所有技能。要在重新运行安装程序后仍然移除某个技能，请在每次init-context运行后删除其SKILL.md文件。amazon-devices-buildertools-mcp无法加载
添加配置后，IDE无法初始化MCP并显示：
MCP error -32000: Connection closed
原因： 程序包安装失败或Node版本不匹配。
解决方案：
-
验证程序包在IDE之外运行：
npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help如果您看到帮助消息，说明程序包已正确安装 - 跳至步骤3。
-
如果命令失败，则全局安装该程序包：
npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest -
确认程序包出现在您当前的Node版本下：
npm list -g每个Node版本都会保留自身的全局安装内容。例如，
nvm use 20 && npm list -g显示的列表与nvm use 22 && npm list -g不同。 -
关闭您当前的聊天对话并开始新的聊天对话。
-
要求您的代理列出可用工具。
示例： “What tools does Amazon Devices Builder Tools provide?”（Amazon Devices Builder Tools提供哪些工具？）
如果代理使用工具列表进行响应，则问题得到解决。
amazon-devices-buildertools-mcp不能用于asdf
原因：asdf创建了shell脚本包装器而不是直接节点二进制文件。MCP服务器需要真实的节点二进制文件，因此基于npx的标准配置在CLI上运行，但在IDE中失败，出现MCP error -32000: Connection closed（MCP错误-32000：连接已关闭）。
解决方案：
-
安装MCP：
npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest -
获取节点二进制文件的路径：
% asdf which node您会看到与以下类似的输出：
~/ASDF_DATA/installs/nodejs/22.20.0/bin/node -
获取amazon-devices-buildertools-mcp二进制文件的路径：
% asdf which amazon-devices-buildertools-mcp您会看到与以下类似的输出：
<>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp注意： 步骤2和3的输出因您的ASDF_DATA_DIR设置而异。 -
使用步骤2和3中的路径更新AI代理的MCP设置文件。将占位符路径替换为您的实际输出：
"amazon-devices-buildertools-mcp-npx": { "type": "stdio", "command": "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/node", // 从上面复制的路径 "args": [ "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp" // 从上面复制的路径 ] },注意： 使用密钥名称amazon-devices-buildertools-mcp-npx而不是amazon-devices-buildertools-mcp，以避免与无效的基于npx的配置发生冲突。由于这个备用密钥，即使MCP工作正常，check-status也会报告“Not configured”（未配置）。 -
关闭您当前的聊天对话并开始新的聊天对话。
-
在新聊天中，要求您的代理列出可用工具，由此确认工具负载。
示例： “What tools does Amazon Devices Builder Tools provide?”（Amazon Devices Builder Tools提供哪些工具？）
npm程序包页面没有日语版本
原因： Amazon Devices Builder Tools的npm程序包页面仅提供英文版本。npm注册表不支持日语区域设置。
解决方案：
改用主设置页面上的设置说明。此页面提供日语版本，包含您需要的所有安装和配置步骤。无论区域设置如何，npm命令（npx、npm install）的工作原理都是一样的。
Gemini CLI无法从项目目录加载指导文档
原因： Gemini CLI存在一个已知问题，它无法提取安装在项目目录中的GEMINI.md指导文档。有关详细信息，请参阅google-gemini/gemini-cli。
解决方案：
将文件复制到您的主目录以进行自动加载：
cp GEMINI.md ~/.gemini/GEMINI.md
或者，在Gemini CLI会话中键入read GEMINI.md来手动加载它。
GitHub Copilot无法加载指导文档
原因： 在某些配置中，GitHub Copilot可能无法自动加载AGENTS.md指导文档。这是一个已知问题。有关详细信息，请参阅community/discussions（仅提供英文版）。
解决方案：
在Copilot聊天会话中键入read AGENTS.md以手动加载上下文。
应用迁移工作流未产生预期结果
原因： 应用迁移工作流（应用移植）处于Beta测试阶段，仅支持以下迁移路径：
- Fire OS WebView应用 → Vega网页应用
- Fire OS React Native应用 → VegaScript应用
- 通用电视应用 → Vega应用（可自动检测应用类型）
这些路径之外的迁移，或涉及自定义原生模块、多活动架构或高度自定义的Fire OS API的复杂迁移，可能不会产生预期结果。
解决方案：
- 确认您的应用与上面列出的受支持迁移路径之一相匹配。
- 对于复杂的迁移，可能需要手动迁移步骤以及自动化工作流。
- 确认支持所用路径后，重新运行迁移提示。
如果工作流仍然产生意外输出，请在您的AI代理聊天中使用“I want to provide feedback”（我想提供反馈）提示来提供反馈。
相关主题
Last updated: 2026年5月20日
