Files
GC-XH/.workbuddy/memory/2026-11-19.md
T

14 KiB
Raw Blame History

2026-11-19 工作日志

GC 项目 Flutter 1.1.1 编译环境配置

项目结构关键发现

  • 仓库有两个远程:origin(Avalonia 版,分支 main)和 origin2(Flutter 版,分支 origin2/main,tag 1.1.1)。
  • 用户口中的"C#+Flutter 项目"指 origin2/main:GC-UI/ 是前后端分离实现——Flutter 前端(GC-UI/frontend/)+ .NET 8 后端(GC-UI/backend/GC.UI.Server/)。模型窗口仍由后端用 Avalonia 承载(契约不可变)。
  • 当前 main 分支是纯 Avalonia 版,无 Flutter 代码。最初误判"没有 Flutter",实际在另一远程分支。

分支操作

  • 原 main 有未提交改动(8 个文件,version.json 从 1.0.7 手改成 1.1.1),已 stash 到 stash@{0}(message: backup-before-flutter-switch-20261119)。
  • 已新建本地分支 flutter-1.1.1 跟踪 origin2/main,HEAD 在 tag 1.1.1(commit 3c74eff)。

Flutter 环境(已完成)

  • 工程锁定 Flutter 3.24.5(Dart 3.5.4),依据是 GC-UI/frontend/.metadata 的 revision dec2ee5c1f98f8e84a7d5380c05eb8a3d0a81668,与官方 release hash 一致。
  • SDK 安装在 /Users/lixi/development/flutter,zip 校验 sha256 ca9624a6de7a1a8962f2f0a3e2a57b16434ca34f1137b8d9dc68c5ca1f187133。
  • 国内镜像(快 100 倍,8MB/s):FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn、PUB_HOSTED_URL=https://pub.flutter-io.cn。
  • 已把 PATH 和两个镜像变量写入 ~/.zshrc。
  • flutter pub get 成功,flutter analyze 零问题(代码本身健康)。
  • 注意:Flutter 构建命令需在无沙箱模式下运行(需写 SDK 缓存目录 .pub-preload-cache)。

编译阻塞(待用户处理)

  • 目标 macOS 版,但本机只有 Command Line Tools,无完整 Xcode(xcodebuild 不存在)。
  • flutter build macos --release 实测报错 exit 72:xcrun: error: unable to find utility "xcodebuild"。
  • App Store 无 Apple ID 登录态(MobileMeAccounts / 钥匙串均无凭据),命令行无法无人值守安装 Xcode。
  • 用户选择:自己手动在 App Store 登录并安装 Xcode,装完后再继续 flutter build macos。
  • 备选方案(用户未选):本机可用 buildsh/cross/build-ui-win-cross.sh 走 mingw-w64 + wine 交叉编译 Windows 版(需 brew install mingw-w64 cmake ninja + brew install --cask wine-stable),Rosetta 2 已安装。

编译完成(Xcode 27.2 装好后)

用户手动装好 Xcode 27.2(/Applications/Xcode.app,xcode-select 已指向)。编译过程连破 3 个新 Xcode 兼容问题:

  1. 部署目标过低:macos/Runner.xcodeproj/project.pbxproj 三处 MACOSX_DEPLOYMENT_TARGET = 10.14 → 改为 12.0(Xcode 27 最低支持 12.0)。这是对工程文件的持久化改动。
  2. lipo -verify_arch 参数解析变更:Flutter 3.24.5 的 packages/flutter_tools/lib/src/build_system/targets/macos.dart 一次性传多个架构给 -verify_arch,Xcode 27 的 lipo 报 "requires exactly one input file"。改为逐个架构分别验证。改后需删 bin/cache/flutter_tools.stamp 强制重建 snapshot 才生效。
  3. 假符号链接:解压 Flutter SDK 时沙箱把 .framework 里的符号链接写成文本文件路径(内容是 Versions/Current/...),导致 SwiftPM 报 Unable to resolve module 'FlutterMacOS'。按「先 Versions/Current→A,再顶层 4 个链接」顺序修复,共 19 个(SDK artifacts 15 + build 目录 4)。修复脚本思路见 /tmp/fix2.sh(临时)。

产物:GC-UI/frontend/build/macos/Build/Products/Release/GC-UI.app(38MB,版本 1.1.1,universal x86_64+arm64,adhoc 签名,bundle id com.morris.gc.gcUi)。 交付 zip:dist/GC-UI-1.1.1-mac-universal.zip(16MB,sha256 55f40c146e86cfed3adc1f02a72ab89944dd81ba8e9c8ba6cf929f7061573db5)。 注意:这是 Flutter 前端外壳,需 .NET 后端(GC.UI.Server / GC-BOOT 进程内托管)配合才能完整工作。完整发布包 GC.app 需走 build.sh build,但该流程强制走 Windows 交叉编译(wine/mingw,本机装不了,Homebrew 被沙箱拦截),故未跑完整发布。

"打开即连好"完整发布包(用户反馈单独 GC-UI.app 报"无法连接后端")

根因:Flutter 前端不含后端,靠 GC_UI_PORT 环境变量 / .GC/ui-backend.json 发现后端。正统入口是 GC-BOOT(产物 GC):FlutterShell.TryRun 在进程内起后端 → 选端口 → 拉起 GC-UI.app/Contents/MacOS/GC-UI 并传入 GC_UI_PORT → 前端自动连上。单独双击 GC-UI.app 必然连不上。

手动只构建 macOS 完整包(绕开装不了的 wine/mingw):

  1. dotnet publish GC-BOOT/GC-BOOT.csproj -c Release -r osx-arm64 --self-contained -p:... -o dist/mac-arm64(GC-BOOT.csproj 已把后端作库引用,FrameworkReference Microsoft.AspNetCore.App,一个 exe 够用)
  2. 同样 publish GC-SAVEDOG(裁剪)
  3. 复制 GC-UI.app 到 dist/mac-arm64
  4. 组装 GC.app:Info.plist(版本 1.1.1)+ Contents/MacOS 放 GC/GC.UI.Server.runtimeconfig.json/GC-UI.app,SAVEDOG 收进 .GC/bin,iconutil 从 icon-1024.png 生成 AppIcon.icns
  5. ditto -c -k --sequesterRsrc --keepParent 打包

验证通过:open GC.app 后用 curl 查 http://127.0.0.1:17890/api/health 返回 {"ok":true,"version":"1.1.1","platform":"osx-arm64"};frontend 进程 GC-UI 在跑;models/settings/about API 全部正常。测试完已 pkill 并清掉 .GC 运行数据。

最终交付:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 3bb4101fee9588b1a3b73dcf2e65bc081b83220e5fbbe18a433ee2af8ccfb5e3),解压得 GC.app,双击即自动连好后端。旧的 dist/GC-UI-1.1.1-mac-universal.zip 只是纯前端,已被取代。

注意:dotnet publish 的 -o dist/mac-arm64 不会清旧文件;rm -rf dist/mac-arm64 会触发批量删除保护(156 文件)。发布包数据目录落在 dist/mac-arm64/.GC(AppPaths 回退逻辑),启动器日志里 SAVEDOG 显示"未找到"是因为它找的是同级而非 .GC/bin,不影响主流程。

真正根因:App Sandbox 缺 network.client(用户第二次反馈仍连不上)

上面的"验证通过"是假阳性:只 curl 了后端(后端在沙箱外,当然正常),从没让前端真发请求。前端报"无法连接后端(baseUrl)"是 api_client.dart:428 的 ApiException。

真因:GC-UI/frontend/macos/Runner/Release.entitlements 只开了 com.apple.security.app-sandbox=true,没有 com.apple.security.network.client。沙箱内进程向 127.0.0.1:17890 发起出站 HTTP 会被内核拒绝(EPERM),所以发布版前端连不上;DebugProfile.entitlements 有 network.server 所以开发时正常,掩盖了问题。用 codesign -d --entitlements :- GC-UI.app 可确认签名里只有 app-sandbox。

修复:给 Release.entitlements 加 network.client + network.server → 重新 flutter build macos --release(新签名自动嵌入)→ 替换 GC.app 内 GC-UI.app → 重打包。

这次验证到位:open GC.app 后 lsof -nP -a -p <前端PID> -iTCP 显示 GC-UI ... TCP 127.0.0.1:60082->127.0.0.1:17890 (ESTABLISHED)——前端真连上了。这才是"打开即连好"的硬证据。

最终交付覆盖更新:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 2b0f4c25ce4e52edf18a45ceb2fe2f91612757db5589f346ffd984665cab5172),包内前端签名已含 network.client/server。

教训:验证桌面端"连后端"必须看前端进程的网络连接(lsof),不能只 curl 后端。无 GUI 会话时 screencapture/AppleScript 不可用。

恢复用户改动

回到 main 后执行 git stash pop 恢复 stash@{0} 的 8 个文件改动。 当前 checkout 分支:flutter-1.1.1(跟踪 origin2/main,tag 1.1.1)。

提交 PR 到 xhmcl(Gitea 28.1.0,git.xhmcl.com/Morris/GC)

分支 fix/macos-release-sandbox-network(commit 3efdf74),只含本次修复两文件:Release.entitlements、project.pbxproj。 严格排除了干扰项:model/contour-map/*(他人地貌改动)、pubspec.lock(配国内镜像 pub get 的副作用,不能提交)、未跟踪的 mp4/js/html 等。 PR #28:Morris/GC#28 (base main,state open,mergeable=true,+7/−3,2 files)。

凭据/接口要点(踩坑记录):

  • 该实例 git 协议与 API 认证分离。gdt_... 是 git 凭据(当密码用可 push),但调 API 全部 401(Authorization: token/Bearer、X-Token、PRIVATE-TOKEN、query 都试过)。
  • 建 PR 必须用账号登录密码做 basic auth:curl -u 'Morris:<密码>' -X POST .../api/v1/repos/Morris/GC/pulls -d @body.json,返回 201。
  • push 时若报 "unable to get credential storage lock: File exists",用 git -c credential.helper= push + GIT_ASKPASS 脚本绕过;其实首次已推成功,是误报。
  • 临时凭据文件(netrc/askpass/pr.json)用完即删,不落盘留存。
  • 注意:本机无图形会话时 screencapture/AppleScript 不可用;验证"前端连后端"必须用 lsof -nP -a -p <PID> -iTCP 看 ESTABLISHED。

模型无法启动 + 后端崩溃(PR #29)

根因:macOS 的 AppKit 要求 NSApplication 在主线程。Flutter 模式下 FlutterShell 用 ui.WaitForExit() 占住主线程,而 AvaloniaHost 在 new Thread(...) 副线程里跑 StartWithClassicDesktopLifetime。点「启动模型」时模型窗口在副线程触碰 AppKit → 进程级崩溃,后端随之消失(表现为"无法启动模型"+"后端容易崩溃")。纯 Avalonia 版不受影响,只在 Flutter 打包模式暴露。

修复(4 文件,+114/−51):

  • AvaloniaHost:新增 RunOnCurrentThread()/Shutdown(),EnsureStartedAsync() 改为只等 _ready,不再自建线程。
  • BackendServer.Start(args, port, out AvaloniaHost) 重载(out 参数不能在 lambda 里用,内部用局部 host)。
  • FlutterShell:前端拉起后在主线程跑 Avalonia 事件循环,ui.Exited 时后台 Shutdown();Avalonia 不可用时退化 WaitForExit()。
  • Program.cs:app.StartAsync() 后主线程跑 Avalonia,失败则 WaitForShutdown()(需 using Microsoft.Extensions.Hosting)。

验证:/api/health → uiAvailable:true;前端 ESTABLISHED →17890;POST launch → HTTP 200 {"ok":true,"message":"已启动模型 contour-map"};启动后后端存活。

交付:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 4b3978eab5cb8fba4e97a3a623cb532080b9e0e24dd6f3e28e69440966c510bb)。 PR #29:Morris/GC#29

坑:dist/mac-arm64/GC.app 在清理 .GC 时被误删过;可从 /tmp/gc-fresh-test/GC.app 取 GC-SAVEDOG 与结构,配合 /tmp/gc-new/GC(publish 产物)+ build 目录新前端重建。组装脚本见上面的"打开即连好完整发布包"步骤。

contour-map 模型重写(对照加密 HTML 课件移植)

背景:用户提供的 ~/Downloads/等高线及地形部位演示.html(79MB)是授权壳 + AES-256-GCM + gzip 的课件,内含 Three.js 版五大地貌演示。已在本地用 node 复现解密(key = 两数组异或,AAD QLAB|contour-landform-reading|...),还原出 83MB 内部课件;其内容为「10 张内嵌 PNG + 切割视频 + 标注层」,并非可交互 3D。按用户要求改为在 model/contour-map 用 C#/Avalonia 重写。

改动文件(均在 model/contour-map/src/):

  • TerrainField.cs:新增 LandformKind(Peak/Ridge/Valley/Saddle/Cliff)与五个高度场生成器。要点是地形要宽阔(穹状山体、宽脊、V 形谷、双峰垭口、台地陡崖),半径过小会变成“尖锥/薄墙”。
  • ContourView.cs:重写为可交互 3D(拖动旋转、滚轮缩放),四步实验(切割/成线/投影/判坡),俯视/立体切换,自动取景 UpdateCamera(按包围盒八点投影铺满画布),法线光照,裙边侧壁,分层设色在 3D 用 ColorForHeightSmooth 平滑过渡、俯视仍用硬分档。
  • ContourPage.cs:地貌标签移到画布上方(WrapPanel,窄屏自动换行);右侧栏 344px,<980px 自动隐藏;四步流程/观察面板/判读要点;底部播放、重置、视图切换、上色、实时读数;空格与 1–5 快捷键;全屏。
  • DefaultTexts.cs:90 个键,中英各一套。
  • ContourMapRuntime.cs:LoadTexts 改为「内置默认 + i18n/*.json 覆盖」,之前完全忽略语言包。
  • 清单 contour-map.json 版本 1.1 → 1.2;help.json 同步新交互。

修掉的真实 Bug:

  1. ExtractContour 的 Chain() 只向尾部延伸,一条等高线被切成大量短链 → 3D 里显示成虚线等高线。改为端点索引 + 双向延伸后,每层只剩 1 条 300+ 点的完整曲线。
  2. SlopeAt 固定除以 450,导致山体坡度全饱和为 1(整片红),“疏密判坡”失效。改为按 span*2.6 自适应归一化。
  3. 切割步骤原本只是叠一张半透明板,山尖仍在。改为把高度场压到切面 min(h, lv),得到真实截面,并用 ExtractContour(lv) 精确求交线。
  4. 切割时山峰标注悬在切面上方 → 高于切面的山峰不再标注。

性能:62×62 面片 + 画刷颜色缓存,1440×900 离屏单帧约 35ms(≈28fps),可接受。

验证:dotnet build 0 警告 0 错误;dotnet run --project model/_engine/PreviewGen 全模型离屏渲染通过并生成封面;自建 /tmp/ccheck 全尺寸渲染器逐状态出图核对(默认/俯视/五地貌/四步/中间帧)。

交付:PR #30 Morris/GC#30(feat/contour-map-rewrite → main,12 文件 +1903/-600,基于最新 main 单提交)。提交 PR 时注意:本地 flutter-1.1.1 落后 origin2/main 4 个提交,需先 stash 改动、从 origin2/main 建分支再 pop,否则 PR 会带上 48 个无关提交;gitcode(origin) 的 main 更旧且仍是 NeoRF.* 命名空间,不宜作为 PR 目标。推送用 GIT_ASKPASS 临时脚本传凭据,用完即删,不写 remote URL。