wov-sdk/AGENTS.md

WOV SDK

本仓库是 WOV 平台的节点协议和 SDK，不包含业务逻辑。

职责

• 定义 NodeManifest：节点的能力、命令、资源、生命周期配置。
• 定义节点调用协议：GET /health、POST /invoke。
• 提供标准节点 HTTP 服务端，让每个节点仓库可以独立运行。
• 提供工作流 DAG 数据结构，供 wov-api 使用。

不变量

• SDK 保持零第三方运行时依赖，方便任意节点仓库独立安装。
• 节点之间只通过产物 URI 交换数据，不直接互相调用。
• 节点 Manifest 一旦发布，字段语义不得随意改变；新增能力必须向后兼容。

环境

• Python 环境统一使用 uv 管理，不直接使用 pip 修改依赖。
• 测试必须达到 100% 行覆盖率，且只能通过调用真实代码路径覆盖。

代码注释规范

• 本仓库所有源码（Python、TOML 等支持注释的文件）必须配有详细中文注释，说明模块职责、协议模型字段语义、类与函数的作用以及关键逻辑，确保后续维护人员可以快速理解代码工作原理。
• 新增或修改代码时，必须同步补充或更新对应注释；不得删除已有注释。
• 测试代码同样必须配有中文注释，说明每条测试验证的行为。
• JSON 数据文件不支持注释，字段语义以本仓库 models.py 中的模型注释为准；修改 JSON 字段时须同步更新文档。