用途
Modal Function Sync 用于在 modal_functions 仓库中新增或修改 Modal 函数，完成注册，并把生成的客户端本地同步到 win 仓库。它适用于用户提出“实现某个 Modal 函数或流水线”这类需求时，确保函数在 modal_functions 中定义、注册、部署，并正确暴露给 win 调用。
主要能力
- 在 modal_functions 中实现或更新函数，并更新注册表与部署配置，使 Modal 实际发布对应符号。
- 通过本地同步包装脚本生成 win 侧的客户端文件，并保持生成文件不被手工修改。
- 提供漂移检查脚本，在不改动 win 的前提下检测生成客户端是否过期。
- 管理 Modal 运行时密钥：稳定密钥默认走本地规范存储到清单再到 Modal 的同步流程，而非手工更新。
- 支持本地快速验证：可先生成到临时文件，避免污染 win 工作区。
使用方式
- 收集上下文：确认新函数或流水线的意图、输入输出、存储与缓存预期，以及 win 将在何处调用；确认是新增功能还是行为更新。
- 阅读两个仓库中的 AGENTS.md 并遵循嵌套规则。
- 在 modal_functions（事实来源）中实现：在 src/functions/... 下添加或修改代码，更新 src/registry.py 暴露函数，更新 src/deploy.py 使 Modal 发布符号，必要时更新 src/common/ 中的共享辅助代码；修改注册表后运行 python tools/validate_registry.py；保持 Modal 应用名与 src/common/containers.py 一致。
- 处理密钥与配置：若新增或修改 modal.Secret.from_name(...)，判断其是否为应受本地规范存储管理的稳定运行时密钥；默认将其加入 scripts/local/secrets/modal_secrets_manifest.json，并确保本地规范密钥已存在；采用旧有 Modal 专属密钥时，通过 ~/GitHub/scripts/bin/local-secrets set 写入一次，不要打印值或新增规范所有者；密钥形态或环境变量键变化时更新 docs/rules/environment-variables.md。
- 客户端同步：在 modal_functions 中运行 scripts/local/sync_win_modal_client.sh，该脚本会校验注册表、生成 ../win/services/modal/client_generated.py 并用 WIN 的 Ruff 配置格式化；不要手工编辑该生成文件；可用 python tools/generate_modal_client.py --output tmp/client_generated.py 做本地验证；需要只检查时使用 scripts/local/check_win_modal_client_drift.sh；注册表输出变化时，将生成客户端变更纳入 win 工作区。
- win 集成：使用 services/modal/client_generated.py 中的 ModalClientGenerated；必要时在 services/modal/client.py 添加包装或辅助方法；更新 tests/services/modal/test_client.py 及相关调用点。
- 部署与验证：推送到 main，观察 CI 的 lint/tests/deploy；若改动涉及受管 Modal 密钥，确认部署任务中的密钥刷新步骤通过；在 win 中验证关键流程或运行针对性测试。
适用场景
- 需要在 modal_functions 中新增或修改 Modal 函数并同步到 win 时。
- 需要检查 win 侧生成客户端是否与 modal_functions 注册表一致时。
- 需要按规范管理 Modal 运行时密钥与清单时。
限制与注意事项
- 仅文档改动不会触发 Modal 部署（工作流忽略 docs/** 与 *.md）。
- 缺少注册表条目会导致客户端不包含该函数。
- 在代码中添加 modal.Secret.from_name(...) 却未更新清单会重新引入密钥漂移。
- 添加清单条目但没有真实本地后备密钥会导致部署时密钥同步失败。
- 直接编辑生成客户端输出会被本地同步包装脚本覆盖。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。