模块 5协议、Skills 与框架

TypeScript Agent 工程

从边界组织代码而非按 SDK 示例堆文件

  • domain：任务、状态与业务不变量
  • application：Run 用例与编排
  • adapters：Model、Tool、Store、Transport
  • infrastructure：配置、Telemetry 与部署
  • UI/协议类型通过显式契约共享

静态类型不能替代运行时校验

  • Schema 作为外部输入事实
  • 从 Schema 推导 TypeScript 类型减少漂移
  • 判别联合表示事件和状态机
  • unknown 优于 any，边界处解析后再进入领域层

异步流需要取消、背压和清理

  • AsyncIterable/ReadableStream 的事件消费
  • AbortSignal 贯穿模型、Tool 和客户端
  • 并发 Tool 的上限与 Promise.allSettled 语义
  • finally 中关闭连接、刷新 Trace 和释放资源

依赖注入保持业务逻辑可测试

  • Runner 依赖接口而非全局单例
  • RunContext 只携带显式业务依赖和身份
  • 配置和秘密在 Composition Root 解析
  • 避免把请求对象传遍所有 Tool

用稳定错误类型跨层传递恢复语义

  • Validation、Policy、Retryable、Conflict、Cancelled 和 Unknown Outcome
  • cause 保留诊断链但不直接暴露用户
  • Result/Event 协议与异常边界一致
  • Unhandled rejection 和浮动 Promise 作为测试失败

测试分层覆盖概率与确定性边界

  • 状态机、Schema、策略和 Context Builder
  • Model/Tool/Store Adapter
  • 录制模型事件或 Fake Model 驱动完整 Run
  • 超时、取消、重复、乱序和部分失败

Node 运行时的生产细节

  • 连接复用、并发池和内存上限
  • 进程信号与优雅关闭
  • Edge/Serverless 的生命周期和 Trace Flush
  • Source Map、结构化日志和版本元数据