应用结构

python
import asyncio
import fastsim

async def main() -> None:
    async with fastsim.app("run.yaml") as simulation:
        await simulation.start()
        snapshot = await simulation.state()
        targets = await simulation.control.targets()
        print(snapshot, targets)

asyncio.run(main())

上下文负责最终 close，但业务代码仍应显式处理 start、Operation 结果、取消和超时。不要从 Application 中提取后端原生对象并在外部线程操作。

按能力选择客户端

  • scene：catalog、state、pose/drag/attach 等受控场景操作。
  • frames：frame catalog、lookup 与 transform。
  • geometry：规划几何能力、catalog、transform 与资源读取。
  • kinematics：按当前可用 solver 执行查询。
  • control：目标发现、joint/track Chunk、Operation 状态和取消。
  • visualization：发布调试几何、metric 与 event。
  • checkpoint、camera 与 output：按 Run/插件能力出现。

调用前应通过能力与目标发现确认当前部署可用内容。缺少可选能力是明确错误或不可用状态，不应靠捕获任意异常后继续。

并发与超时

API 是异步的，但后端世界仍由单一权威边界串行化。超时限制调用者等待时间，不自动等价于取消物理操作；长操作应保留 Operation 并根据状态决定 cancel 或继续等待。

同步调用

简单脚本可使用 FastSimRun 的同步上下文与生命周期方法。不要在已有 asyncio loop 中嵌套同步门面；服务与 UI 应保持异步 Application。

所有当前签名由源码生成在Python SDK中。