模块 5协议、Skills 与框架

Python Agent 工程

建立与 TypeScript 的关键映射

  • 类型提示、Protocol、dataclass 与 Pydantic
  • 模块、包、虚拟环境和依赖锁定
  • 异常、Context Manager 和 Iterator/Generator
  • 运行时类型仍需 Schema 校验

理解 asyncio 的执行模型

  • event loop、coroutine、Task 和 async generator
  • TaskGroup/结构化并发与取消传播
  • 阻塞 I/O 或 CPU 工作不能占住事件循环
  • 超时、shield 与资源清理的边界

保持跨语言一致的架构边界

  • 领域状态与业务规则
  • Runner/Use Case
  • Model、Tool、Store 和 Transport Adapter
  • 配置、身份和 Telemetry 注入

Pydantic/JSON Schema 的应用边界

  • 外部请求、模型输出和 Tool 参数解析
  • 严格模式、额外字段和联合类型
  • 序列化版本与兼容性
  • 不要把 ORM/Pydantic 对象无界传入模型 Context

理解生态但不让框架主导架构

  • FastAPI/ASGI 流式响应与生命周期
  • Agent SDK/Graph 框架的状态和 Hook
  • 同步库包装到线程池的代价
  • 包版本、原生依赖和部署镜像

Python 工程质量基线

  • pytest、async test 和 fixture
  • mypy/pyright、lint/format 与依赖审计
  • Fake Model、契约测试和故障注入
  • 时间、随机和环境变量隔离

多语言团队以协议而非对象共享

  • OpenAPI/JSON Schema/Event Schema
  • 错误码、时间、金额和 ID 语义
  • Trace Context 与幂等键
  • 通过同一 Golden Scenario 验证 TypeScript/Python 实现