TROUBLESHOOTING / NEXT STEPS
按症状排查扩展问题
从客户端提示、校验错误或 HTTP 状态码开始，先确认是哪一层拒绝了请求，再采取对应修复。
常见症状
| 你看到的现象 | 常见原因 | 建议动作 |
|---|---|---|
| 本地校验报告清单错误 | 根目录文件不叫 manifest.json，字段缺失，或 runtime 与 apiVersion / 贡献内容不匹配。 | 在示例目录运行校验脚本，按错误字段修正清单；再用目标运行时的 schema 和 API 参考核对。 |
| 预览页找不到扩展或提示目录无效 | 选择的不是包含普通根 manifest.json 文件的目录，或者清单无法解析。 | 回到 My Extensions 的 Preview source directory，选择解压后的项目根目录，并重新运行本地校验。 |
| quote view 没有报价 | 宿主没有为当前回调准备报价快照，或当前启用未获准 tradingRead。 | 检查该扩展的权限授权和宿主市场数据状态，然后刷新报价视图。guest 读取的是宿主预载快照，不会自行请求行情。 |
| 交互式 Wasm 包无法启动 | 目标宿主未声明 API v2 所需的原生 ABI feature bits 3 和 4，或清单目标与 guest 导入不匹配。 | 检查 SDK reference 的 API v2 合同，并在支持这些特性的目标客户端验证；按实际已支持宿主版本设置包的 minHostVersion。 |
| 校验通过，但客户端不接受安装 | 结构校验只说明包形状符合工具规则；正式安装还会检查签名、发布者信任、审核、兼容性、授权权限和适用权益。 | 查看 Marketplace 发布状态和客户端错误详情，逐项确认已审核版本、可信发布者密钥、宿主版本和权限授权。 |
| 解析兼容版本接口返回 HTTP 404 | 给定 host_version 和 channel 下没有已批准且兼容的发布版本。 | 检查 host_version、channel（默认 stable）、审核状态和发布版本的 minHostVersion；测试 beta 时确认目标客户端选择了 beta channel。 |
| 发布接口返回 marketplace_publishing_disabled | 当前 Cloud 部署的 Marketplace 发布开关关闭。 | 停止重复提交。该部署需要管理员启用发布功能后才能继续。 |
| 登录接口返回未授权 | Bearer access token 已过期、缺失，或不属于当前登录账户。 | 通过正常 TradingAI Cloud 登录重新建立会话，再用当前 access token 重试；不要从客户端本地存储中读取 token。 |
| 请求返回 HTTP 429 | 该账户或路由在当前时间窗内请求过多。 | 降低请求频率、停止并行重试，等待一段时间后再发送单次请求。 |
预览与正式安装检查的区别
源目录预览用于快速查看安全清单和静态视图。它不运行 Wasm 或本地 HTML/JavaScript，不取实时报价，不登记发布者，不验签，也不安装扩展。若预览成功而安装失败，请继续检查签名、发布审核、客户端信任和兼容性。
继续定位
- 构建与 Cloud 请求指南：核对命令、origin 和登录边界。
- 发布工作流：核对发布者验证、提交和审核状态。
- 兼容性说明：区分清单 API、Wasm ABI 和宿主版本。
- Cloud REST API 参考：查看路由鉴权与状态说明。
反馈文档问题
如果文档步骤与实际客户端不一致，可通过通用支持邮箱 support@tradingai.io 反馈。请附客户端版本、扩展版本、使用的文档链接、复现步骤和已去除凭据的错误信息。