🔧 故障排除
以下是当前 Python SDK 常见问题及直接修复方式。
1. ImportError: No module named 'wyseos.mate'
原因：
- 当前环境未安装 SDK
- Python 解释器不一致
修复：
pip install wyseos-sdk
python -c "from wyseos.mate import Client; print('ok')"如果你使用虚拟环境，请先激活再执行。
2. ConfigError: Configuration file not found: .../mate.yaml
原因：
load_config()找不到配置文件路径。
修复：
from wyseos.mate import Client, ClientOptions
from wyseos.mate.config import load_config
try:
client = Client(load_config("mate.yaml"))
except Exception:
client = Client(ClientOptions(api_key="YOUR_API_KEY"))3. ConfigError: Invalid YAML in configuration file
原因：
- YAML 格式错误。
修复：
- 使用空格缩进。
- 检查键值对格式。
- 配置结构保持如下：
mate:
api_key: "your-api-key"
# jwt_token: "your-jwt-token"
base_url: "https://api.wyseos.com"
timeout: 304. 配置 ValidationError
常见情况：
- API key 为空：
API key cannot be empty - base_url 非法：
Base URL must start with http:// or https:// - timeout 非法：必须在
1-300范围内
修复：
from wyseos.mate import ClientOptions
opts = ClientOptions(
api_key="YOUR_API_KEY",
base_url="https://api.wyseos.com",
timeout=30,
)5. HTTP 401/403 认证失败
原因：
api_key/jwt_token无效base_url环境错误
修复：
- 在控制台重新生成凭据。
- 确认只使用一种认证方式。
- 确认映射：
- API key ->
x-api-key - JWT ->
Authorization（不带Bearer前缀）
- API key ->
6. TaskRunner 超时或不结束
原因：
- 任务超过
completion_timeout - WebSocket/网络问题
修复：
from wyseos.mate.task_runner import TaskExecutionOptions
options = TaskExecutionOptions(
verbose=True,
completion_timeout=900,
)
result = task_runner.run_task(
task="Complex analysis task",
options=options,
)
print(result.success, result.error)7. run_interactive_session() 看起来没有响应
原因：
- 交互模式在等待服务端输入请求。
修复：
- 保持
verbose=True观察流式输出。 - 在交互循环中按需使用
stop/pause/exit。
8. Product API 的 create_and_wait() 超时
原因：
- 轮询窗口内未完成产品分析。
修复：
report = client.product.create_and_wait(
product="Notion",
poll_interval=20,
max_attempts=60,
on_poll=lambda attempt, status: print(f"[{attempt}] {status}"),
)9. 文件上传失败
原因：
- 文件扩展名不支持
- 文件过大（
> 10MB）
支持扩展名：
.txt,.pdf,.png,.jpg,.jpeg,.md,.csv,.html,.htm,.rss,.xml,.gif,.py,.json
10. 版本检查不一致
版本检查建议优先看包元数据，而不是只看运行时 __version__：
pip show wyseos-sdk需要更多帮助？
- GitHub Issues: mate-sdk-python/issues
- 支持邮箱: [email protected]