docs: 为全部代码补充中文注释并加入 AGENTS 注释规范

2026-08-13 22:09:55 +08:00
parent 77e9ac6b7e
commit ac41a9a6da
29 changed files with 472 additions and 2 deletions
@@ -36,3 +36,10 @@ uv run uvicorn app.main:app --reload --port 8001
 - Python 环境统一使用 uv 管理，不直接使用 pip 修改依赖。
 - 测试必须达到 100% 行覆盖率，且只能通过调用真实代码路径覆盖。
 - 行覆盖率不包含外部端口占用/权限问题；真实网络启动由 uvicorn 冒烟测试单独覆盖。
+
+## 代码注释规范
+
+- 本仓库所有源码（Python、TOML 等支持注释的文件）必须配有详细中文注释，说明模块职责、类与函数的作用以及关键逻辑，确保后续维护人员可以快速理解代码工作原理。
+- 新增或修改代码时，必须同步补充或更新对应注释；不得删除已有注释。
+- 测试代码同样必须配有中文注释，说明每条测试验证的行为。
+- JSON 数据文件不支持注释，字段语义以 `wov-sdk` 的 `NodeManifest` 模型注释为准；修改 JSON 字段时须同步更新文档。