用途：在 ARK 技术栈各层（SDK、API、Dashboard）之间重新生成与调试类型，主要用于修复 ark-dashboard 的 TypeScript 类型错误，以及在 CRD 变更后同步更新类型。
类型生成流水线：CRD YAML（ark/config/crd/）经 make ark-sdk-build 自动生成 ark-sdk Python 类型与 overlay 工具；再到 ark-api 的 Pydantic 模型（暴露新字段时需手动更新）；经 make ark-api-build 生成 openapi.json；最后到 ark-dashboard 的 TypeScript 类型，通过 npm run generate:api 生成 types.ts。
主要能力与用法：ark-sdk 类型由 Kubernetes CRD YAML 自动生成，make ark-sdk-build 依次执行 crd_to_openapi.py 转换 CRD 为 OpenAPI schema、openapi-generator-cli 生成 Python 类型、覆盖 overlay 文件并构建 wheel 包。自定义 SDK 功能以 overlay 形式加在 lib/ark-sdk/gen_sdk/overlay/python/ark_sdk/ 下，再运行 make ark-sdk-build。ark-api 模型位于 services/ark-api/ark-api/src/ark_api/models/，手工维护，make ark-api-build 从 FastAPI 路由与 Pydantic 模型生成 openapi.json。
Dashboard 类型生成：进入 services/ark-dashboard/ark-dashboard，复制 ../../ark-api/openapi.json 到 ../out/，运行 npm run generate:api，再用 npm run build 验证类型可编译。
限制与注意事项：Pydantic 模型类名必须全局唯一，同名类会导致 FastAPI 生成类似 ark_api__models__agents__Header-Input 的非确定性 schema 名，引发 CI 失败。解决方式是加域前缀，如 Agent*、MCPServer*、Query*、Model*。generate_openapi.py 会在 schema 名含 models 时报错作为安全网。遇到类型错误时，应重新生成 types.ts、用 grep 查找正确 schema 名并更新 service 文件；不要用 models 名绕过，要从根源修复。