gstack 升级或新增 Observable 状态后如何用 /ios-sync 重新同步 iOS 调试桥与访问器【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack在 app 里装好 gstack 的 iOS 调试桥/ios-qa生成的DebugBridgeSwift 包 DebugBridgeGenerated/StateAccessor.swift之后有两个时点会让现有生成产物和上游模板脱节一是把 gstack 升级到带加固修复的新版本二是在 app 里新增了需要快照覆盖的Observable状态。这时用/ios-sync技能重新同步它基于上游 gstack 的模板重生成StateServer.swift、DebugOverlay.swift、Package.swift和带类型的Observable状态访问器并原地更新生成产物。适用环境为 macOS Xcodedevicectl可用、gstack 已通过./setup完成安装且 app 中已存在/ios-qa安装的桥。相关文档见 ios-sync/SKILL.md、docs/howto-ios-testing-with-gstack.md 与 ios-qa/SKILL.md。先判断是否需要重新同步/ios-sync的第一步是版本探测判断这次调用是否可以直接结束读取app/DebugBridgeGenerated/.gstack-version安装时由/ios-qa写入。该文件缺失时按“未知旧版本”处理需要重新生成。读取上游 gstack 根目录下的VERSION文件作为当前版本。两个版本一致、且没有新增Observable类时直接以 already up to date 提前退出不执行重生成。只有版本不一致或新增了Observable类/字段时才进入下面的重生成流程。新增 Observable 状态标记规则决定访问器内容只有带独立标记注释的字段才会出现在访问器和GET /state/snapshot快照里。标记是属性正上方的一行注释// Snapshotable故意不用属性包装器以便与 Observation 的Observable宏共存。未标记的字段不会出现在快照中这默认把 token、PII 和认证状态排除在记录产物之外。文档中的示例文档示例字段名为示意Observable final class AppState { // Snapshotable var username: String var authToken: String // never exported }新增字段要被生成器接受必须同时满足属于文件作用域的Observable类是可写的实例var带显式类型和 internal 或 public setter类型为 JSON 原生标量String、Bool、各整数宽度、Float、Double、CGFloat、数组、String 键的字典或它们的 Optional 组合快照 key 在所有 observable 类之间唯一。生成器对不满足的声明会直接报错停止而不是产出坏 Swift。执行重新同步在 Claude Code 中调用/ios-sync触发语 resync the iOS debug bridge、regenerate iOS accessors 等技能会完成下面四个阶段。也可以直接运行同一确定性命令手动执行 Phase 2 的核心步骤。$APP_SOURCE_DIR替换为 app 的 Swift 源码目录~/.claude/skills/gstack/bin/gstack-ios-qa-regen \ --app-source $APP_SOURCE_DIR \ --bridge-dir $APP_SOURCE_DIR/DebugBridge--app-source是访问器扫描器要检查的目录建议传较窄的 app 源码目录--bridge-dir是 app 在 Debug 构建中链接的本地 Swift 包目录。bin/gstack-ios-qa-regen 的实际行为要求bun在 PATH 上缺失时直接报错退出按显式白名单把支持的桥模板从ios-qa/templates/复制到DebugBridge/包内删除旧版扁平DebugBridgeGenerated/布局下已知过期的生成文件防止残留的第二套 harness 影子化包模块手写 app 源码永远不会被触碰运行访问器生成器写出DebugBridgeGenerated/StateAccessor.swift只有在生成成功后才把当前VERSION写入DebugBridgeGenerated/.gstack-version完成标记——失败或中断的重生成不会呈现为“已是最新”的安装状态。缓存机制保证幂等生成器用复合哈希Swift 版本、generator git rev、lockfile、源码内容、平台 triple作为缓存 key且生成产物本身被排除在哈希之外。全部命中时是一次约 50ms 的空操作源文件字节保持不变只有内容真正变化时才重写。检查生成的 diff重新生成后按 ios-sync/SKILL.md Phase 3 审查查看app/DebugBridge/与app/DebugBridgeGenerated/StateAccessor.swift下的变更。确认命令没有修改 app 的手写 Swift 文件。app 特有的接线Package.swift依赖、main中的#if DEBUG启动代码保留在 app targetDebugBridge包内的规范桥文件是从上游重生成的不应手改手改会在下次重同步时被覆盖。验证结果Phase 4 给出四个验证点全部通过才算同步完成swift build对 app 的包构建成功。xcodebuild -scheme SchemeName构建成功SchemeName换成 app 实际的 scheme。在设备上重启 appMac 端 daemon 连接成功并完成 token 轮换。GET /state/snapshot返回新的访问器 schema hash——新增字段进入快照的直接证据。常见失败与限制ios-sync/SKILL.md 的 Failure modes 表给出四种情况的处理现象处理重生成后 Swift 编译失败用git restore回滚并展示编译错误Codegen 报告标记声明无效改用文件作用域 observable 类 显式 JSON 原生类型的可写实例varinternal/public setter 跨模型唯一的 key否则移除// Snapshotable标记新增 Observable 后 schema hash 不变字段上缺少独立的// Snapshotable标记注释——codegen 正确排除了未标记状态把注释加到要快照的每个字段正上方扫描器看到生成的桥源码传更窄的 app 源码目录regenerator 本身会自动排除DebugBridgeGenerated和StateAccessor.swift两条硬性边界来自 ios-qa/SKILL.md生成器目前只支持文件作用域的Observable类ObservableObject、StateObject等观察模型不会产生访问器依赖接线文档假设 SwiftPM app manifest面对.xcodeproj或.xcworkspace时不要自行发明 package/target 接线未满足条件时应停止桥引导而不改动 app。同步完成后若后续要做 Release 构建再按 docs/howto-ios-testing-with-gstack.md 的流程运行/ios-clean移除DebugBridge依赖与#if DEBUG接线Package.swift中.when(configuration: .debug)条件本身是 Release 构建不会链接桥的结构性兜底。【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考