用途
win-aip-contract-sync 是一个本地优先（local-first）的 WIN 到 AIP 契约同步工作流。它适用于以下情况：
- WIN 后端作业端点或公共 DTO 需要提供给 ../aipodcasting 使用。
- AIP 前端代码需要从 WIN 生成作业路径、作业类型或 DTO 类型。
- 涉及契约同步、生成的 AIP 类型，或 lib/aip/contracts/** 出现漂移。
主要能力
该技能围绕契约源与生成输出的分离来组织工作：
- WIN 拥有契约源；aipodcasting/lib/aip/contracts/** 是生成输出。
- 在本地运行同步，不等待 CI 或云端跨仓库同步。
- 禁止手工编辑 aipodcasting/lib/aip/contracts/** 下的生成文件。
- 生成的作业端点 ID 为路径 slug：去掉斜杠，并将 / 和 - 替换为 _。例如 /operations/episodes/retry-ingest 变为 operations_episodes_retry_ingest。最终键需在 aipodcasting/lib/aip/contracts/job-endpoints.ts 中验证。
- 数据库模型保持内部，仅暴露公共 DTO。
- 仅当前端字段或 UX 位置无法安全推断时才询问。
- 除非用户明确要求或仓库本地自动化处理，否则不提交或推送。
使用方式
检查仓库状态
git -C /Users/dobby/GitHub/win status -sb git -C /Users/dobby/GitHub/aipodcasting status -sb
需绕过无关的本地更改，不要还原它们。
后端更改（win）
- 对于作业端点，保持 @register_endpoint 元数据以及请求/结果 schema 可契约化。
- 对于同步 UI 数据，定义或更新公共 Pydantic 响应 DTO，并设置 response_model=...。
- 将前端消费的 DTO 添加到 scripts/contracts/export_public_dto_contracts.py 中的 PUBLIC_DTOS。
- 显式将数据库/内部模型映射到 DTO。
从 win 运行生成同步
cd /Users/dobby/GitHub/win scripts/local/sync_aip_contracts.sh
该包装脚本会导出作业契约、清除过期的生成 DTO 输出、写入当前 DTO，并使用 AIP 的 Biome 配置进行格式化。
前端工作（aipodcasting）
- 从 lib/aip/contracts/** 导入生成的类型。
- 使用生成的端点 ID/路径，通过通用 AIP 作业代理提交作业。
- 对于同步读取或写入，向 WIN 添加轻量 Next.js API 代理；不要添加 MongoDB 访问。
- 将功能本地过滤器、表单状态和仅 UI 类型保留在生成契约之外。
验证
- 确认 ../aipodcasting/lib/aip/contracts/** 下存在预期的生成文件。
- 当需要非变更性的过期契约检查时，运行 scripts/local/check_aip_contracts_drift.sh。
- 对更改的 WIN 契约导出器或处理器运行聚焦的后端测试。
- 当前端 TypeScript 或契约消费者更改时，在 ../aipodcasting 中运行 pnpm type-check。
- 报告两个仓库的 git status -sb。
适用场景
- 新增或修改 WIN 作业端点、公共响应 DTO、生成的前端契约或 AIP 前端集成。
- 需要确保 WIN 与 aipodcasting 之间的契约保持一致，避免生成类型漂移。
- 在本地开发环境中快速同步契约，而不依赖 CI 或云端跨仓库同步。
限制
- 该技能为本地优先工作流，不等待 CI 或云端跨仓库同步。
- 生成文件不可手工编辑，必须通过同步脚本生成。
- 数据库模型保持内部，仅暴露公共 DTO。
- 除非用户明确要求或仓库本地自动化处理，否则不提交或推送。
- 仅当前端字段或 UX 位置无法安全推断时才询问。
参考资料
- win/AGENTS.md
- win/docs/references/api-endpoint-implementation.md
- win/docs/references/scripts-and-tools-reference.md
- win/scripts/local/sync_aip_contracts.sh
- aipodcasting/AGENTS.md
- aipodcasting/docs/references/aip-backend-integration.md
- aipodcasting/docs/references/aip-integration-patterns.md