[dependence] ImportError: nanobot.heartbeat missing after v0.2.1 due to upstream refactor

[ttzc]

问题描述

在启用 openclaw 可选依赖时，由于 pyproject.toml 中对 nanobot-ai 的版本约束过于宽松（>=0.1.4.post5），uv sync --extra openclaw 会拉取最新版本（当前为 0.3.0），导致运行时导入 ClawApplication 失败，报错 ModuleNotFoundError: No module named 'nanobot.heartbeat'。

经测试，nanobot-ai==0.2.0 可以正常工作，而 >=0.2.1 全部失败。原因是在 nanobot v0.2.1 中，开发团队将 heartbeat 模块迁移到了 cron 服务（参考其 Release Notes 中 "heartbeat moved onto cron" 的说明），导致原有的 nanobot.heartbeat 导入路径失效。

CI 全绿原因：CI 跑在自托管 runner 上，pip install -r requirements-test.txt 对已满足的 >=0.1.4.post5 不会触发升级，runner 残留旧版 nanobot（含 heartbeat）→ 测试从未暴露该问题。

复现步骤

# 1. 安装 openclaw extra（默认拉取 nanobot-ai 最新版）
uv sync --extra openclaw
# Resolved 278 packages in 1ms / Checked 133 packages in 4ms

# 2. 导入 ClawApplication → 失败
uv run python -c "from trpc_agent_sdk.server.openclaw.claw import ClawApplication; print('claw import OK')"
# ModuleNotFoundError: No module named 'nanobot.heartbeat'

# 3. 锁定 nanobot-ai==0.2.0 → 成功
uv run --isolated --extra openclaw --with "nanobot-ai==0.2.0" python -c "from trpc_agent_sdk.server.openclaw.claw import ClawApplication; print('claw import OK')"
# claw import OK

# 4. 锁定 nanobot-ai==0.2.1 → 失败
uv run --isolated --extra openclaw --with "nanobot-ai==0.2.1" python -c "from trpc_agent_sdk.server.openclaw.claw import ClawApplication; print('claw import OK')"
# ModuleNotFoundError: No module named 'nanobot.heartbeat'

# 5. 锁定 nanobot-ai==0.3.0 → 失败
uv run --isolated --extra openclaw --with "nanobot-ai==0.3.0" python -c "from trpc_agent_sdk.server.openclaw.claw import ClawApplication; print('claw import OK')"
# ModuleNotFoundError: No module named 'nanobot.heartbeat'

预期行为

导入成功，openclaw 功能可用。

实际行为

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from trpc_agent_sdk.server.openclaw.claw import ClawApplication
  File "~\trpc_agent_sdk\server\openclaw\claw.py", line 62, in <module>
    from .agent import create_agent
  File "~\trpc_agent_sdk\server\openclaw\agent\__init__.py", line 8, in <module>
    from ._agent import create_agent
  File "~\trpc_agent_sdk\server\openclaw\agent\_agent.py", line 39, in <module>
    from ..service import CronService
  File "~\trpc_agent_sdk\server\openclaw\service\__init__.py", line 8, in <module>
    from ._heart_service import ClawHeartbeatService
  File "~\trpc_agent_sdk\server\openclaw\service\_heart_service.py", line 23, in <module>
    from nanobot.heartbeat import service as heartbeat_service_package
ModuleNotFoundError: No module named 'nanobot.heartbeat'

环境信息

• OS: Windows 11
• trpc-agent-python: 1.1.19（commit 909998e, "feat: 支持 a2a 1.0 协议"）
• Python: 3.13.14（python -V）
• uv: 0.11.21
• nanobot-ai 版本（自动拉取）: 0.3.0（也测试了 0.2.1，均失败）。自动拉取到该版本，是 pyproject.toml 中宽松约束 >=0.1.4.post5 经 uv sync 自动生成 uv.lock 所致

临时解决方案

手动降级 nanobot-ai 到 ==0.2.0 可临时绕过：

uv sync --extra openclaw --with "nanobot-ai==0.2.0"

或作为下游项目常规做法，直接 uv add 收紧传递依赖版本：

uv add "nanobot-ai<0.2.1"

或修改 pyproject.toml 中 openclaw 的依赖为：

openclaw = [
    "nanobot-ai==0.2.0; python_full_version >= '3.11'",
    ...
]

或作为 trpc-agent-python 的下游使用者，在自己的项目依赖中显式指定 nanobot-ai<0.2.1 以覆盖该传递依赖：

[project]
dependencies = [
    "trpc-agent-python[openclaw]",
    "nanobot-ai<0.2.1",
]

建议修复方案

1. 短期：将 nanobot-ai 版本上限锁定为 <0.2.1，避免自动拉取不兼容版本。注意 pyproject.toml 中 nanobot-ai 约束出现在两处——openclaw extra（>=0.1.4.post5）与 all extra（>=0.1.4.post6），需同步收紧，否则 uv sync --extra all 仍会拉取不兼容版本。
2. 长期：适配 nanobot 新版本的 API，届时放开版本限制。heartbeat 模块在 v0.2.1 已迁移到 cron 服务，适配时可考虑对两代 API 做兼容（旧版 nanobot.heartbeat 与新版 nanobot.cron 共存），例如在导入处按版本探测：

try:
    from nanobot.cron import ...  # nanobot >= 0.2.1
except ImportError:
    from nanobot.heartbeat import ...  # nanobot <= 0.2.0

如果项目方计划适配新版，我可以协助测试。

相关 Issue（本质不同）

#207: pyproject declares requires-python >=3.10 but pinned nanobot-ai needs >=3.11 — install fails on Python 3.10 与本 issue 本质不同：

• pyproject declares requires-python >=3.10 but pinned nanobot-ai needs >=3.11 — install fails on Python 3.10 #207：nanobot-ai 声明 requires-python >=3.11，与 trpc-agent-python 的 >=3.10 冲突，导致 Python 3.10 用户依赖解析/安装阶段即失败；
• 本 issue：nanobot-ai 版本约束无上界，uv sync 拉到 v0.2.1+（移除 nanobot.heartbeat 模块）后，安装成功但运行时 import 崩溃。

两者都源于对 nanobot-ai 上游演进的依赖管理，但失败阶段与修复方向不同：#207 需调整 Python 版本 marker 或 requires-python；本 issue 需收紧版本上界（<0.2.1）或适配新 API。