Troubleshooting

常见安装、运行、事件、持久化、resume、snapshot 和工具问题的排查路径。

这篇文档按「症状 → 原因 → 处理」组织。排查时先确认你正在运行哪个示例或业务入口，再看对应分类。

排查总图

Mermaid

Rendering diagram...

安装失败

症状	常见原因	处理
`uv add` 无法拉取私有 GitLab	本机 SSH 没有权限或端口不可达	先运行 `git ls-remote ssh://git@gitlab.biubbmk.cn:2233/ai/we0-agent-sdk.git`。
`ModuleNotFoundError: we0agent`	没有在业务项目安装依赖，或虚拟环境不对	用 `uv pip list` 或 `uv run python -c "import we0agent"` 验证当前环境。
`Python >=3.12` 相关错误	当前解释器版本低	用 `uv python install 3.12` 或切换项目 Python。

模型或 API key 报错

症状	常见原因	处理
provider 返回认证错误	`OPENAI_API_KEY` / 其他 key 未设置或设置到错误 shell	在运行命令前 `export OPENAI_API_KEY="..."`，再用同一个 shell 执行 `uv run ...`。
`Unsupported provider family`	`ProviderCard.family` 不在支持列表	当前支持 `openai`、`anthropic`、`google_genai`、`deepseek`。
访问 `context_window` 或 `max_output_tokens` 抛 `ValueError`	`ModelCard` 未声明能力，底层 profile 也缺失	在 `ModelCard` 显式填写 `context` 和 `max_tokens`。

stream 没有输出

先确认事件处理器是否只处理了某一种事件。stream() 返回的是统一 We0Event，文本只是其中一种。

async for event in agent.stream(...):
    print(event["type"])

常见原因：

模型没有产出文本，而是先产出 tool-input-* 或 tool-call。
事件处理代码用了属性访问 event.type，但事件是 TypedDict，必须用 event["type"]。
stream() 配置了结构化输出。structured_output.output_schema 非空时只能用 invoke()。
abort 事件被复用且已经 set，导致运行一开始就被中断。

prompt / resume 参数错误

报错	原因	处理
`messages is required in prompt mode.`	`mode="prompt"` 但没有传 `messages`	prompt 模式必须追加新用户消息。
`messages is not allowed in resume mode.`	`mode="resume"` 还传了 `messages`	resume 模式只恢复旧会话，不追加消息。
resume 没有额外事件	会话本身已经是干净完成态	只有未完成 assistant 或工具状态才需要恢复。

持久化问题

症状	常见原因	处理
SQLite 表不存在	忘记调用 `await persistence.initialize_schema()`	首次使用 SQL 持久化前先建表。
resume 找不到历史	prompt 和 resume 使用了不同 `session_id` 或不同 persistence 实例	确保同一个 `session_id` 和同一个数据库文件。
文件路径混乱	示例工作区没有清理，或业务代码使用相对路径	仓库示例会清理自己的工作区；业务侧建议传绝对路径。

工具执行失败

工具失败通常有三类：

类型	表现	处理
参数校验失败	Pydantic 报字段缺失或类型不对	改 `parameters` schema 的描述，让模型更容易生成合法输入。
工具内部异常	`tool-error` 事件	在工具 handler 里捕获业务错误，返回更可读的 message。
副作用冲突	文件被并发写、命令互相影响	对有副作用工具设置 `ToolExecutionPolicy(is_concurrency_safe=False, has_side_effects=True)`。

生产环境不要直接暴露 demo 里的 bash 工具，除非外层有严格沙箱和权限控制。

snapshot / revert 问题

症状	常见原因	处理
没有 patch	没有注入 `ports.session_revert`，或工具没有改变 worktree	检查 `SessionRevertService(...)` 和工具写入目录。
snapshot 仓库污染业务仓库	自定义 `SnapshotState` 指向业务 `.git`	使用 `file_system.snapshot_state(worktree=...)` 生成内部 gitdir。
revert 失败提示 busy	会话正在运行	先 abort 或等待 session idle，再执行 revert。

文档图表不显示

当前 docs-site 支持 mermaid、plantuml / puml / uml、dot / graphviz、vega / vega-lite。

症状	常见原因	处理
代码块没有变成图	fence 名称不在支持列表	检查是否写成了 `text` 或拼错语言名。
PlantUML 不显示	无法访问 PlantUML 公共 SVG endpoint	内网部署时改成自建 PlantUML/Kroki。
Vega 图不显示	无法访问 jsDelivr CDN 或 JSON 不合法	确保 spec 是合法 JSON，并考虑本地托管 Vega runtime。

图表代码块使用标准 fence 名称即可被渲染。

最小复现模板

遇到不确定问题时，先缩到这个形态：

import asyncio

async for event in agent.stream(
    abort=asyncio.Event(),
    session_id="debug-session",
    messages=[user_message("只回复 ok")],
    max_steps=1,
):
    print(event)

如果这个能跑，问题通常在工具、持久化、snapshot 或业务事件处理层；如果这个也不能跑，优先查模型、API key、安装和 We0Agent 构造参数。

Troubleshooting

On this page