2026-05-18 工作日志：bricks-mp / Sage 桌面客户端

背景

当天围绕 bricks-mp 仓库完成 Kotlin Multiplatform + Compose Desktop 运行时搭建，并针对 Sage / WebBricks 服务端 .ui、.dspy 加载链路进行了多轮调试。目标是让桌面端能够像浏览器端 bricks 一样加载 Sage 服务端 UI，并可打包为 macOS 应用。

仓库：git@git.opencomputing.cn:yumoqing/bricks-mp.git 主分支：main

时间线

上午：项目初始化与 Compose Desktop 打包链路

b9c5856 初始化 bricks-mp 项目结构。
- 建立 shared 模块。
- 添加 Bricks 基础模型、解析器、渲染器、HTTP 客户端和 ActionDispatcher 雏形。
- 初步支持 Text、布局、输入等基础 widget。
82c2b89 增加 macOS Sage 桌面客户端能力。
- 增加登录、UI 加载、Compose 渲染和 DMG 打包配置。
- 扩展 BricksRenderer，覆盖更多 bricks widget 到 Compose 的映射。
- 增加 Sage 客户端登录/session 相关逻辑。
bf7827a 添加 Gradle Wrapper 8.5，确保构建工具版本固定。
45abb01 为 desktop-only 构建暂时关闭 Android/iOS targets。
- 当前环境没有 Android SDK / Xcode，直接启用多端 target 会导致构建失败。
03c8a8a 修正 KMP JVM target 命名。
- 从 jvm("desktop") 改为 jvm()。
- source set 从 desktopMain 调整为 jvmMain。
ceaadf3 修正 DMG packageVersion。
- Compose DMG 打包不接受 0.x.y，改为 1.0.0。
7b88174 调整工程结构。
- 将 Main.kt 移入 shared/src/jvmMain。
- 移除容易出错的 desktopApp 独立模块。
- 在 root build 配置中补足 repositories。
b80d607 / 605b520 修复编译错误。
- 处理 Modifier.weight() scope 问题。
- 修复 asStateFlow、cookie API、CoroutineScope import、JsonPrimitive 表单值、Material3 experimental API 等问题。

上午：Sage 登录和 HTTP 表单链路调试

e4f35ec 尝试使用 Ktor FormDataContent 处理表单 POST。
b342ae8 发现 FormDataContent 在 commonMain 不可用后，改为 URL-encoded string body。
26ebfe1 进一步调整 form encoding 和 postForm 参数。
a0a4b56 增加 User-Agent / Referer、先 GET index 获取 session cookie，并处理非 JSON 登录响应。
9d3593f 修正 Sage 登录端点。
- 使用 /rbac/user/up_login.dspy。
- 登录字段使用 username 和 password/passwd 链路排查后按 Sage 端实际接口调整。

晚上：将 Sage 逻辑从库中剥离，补独立示例应用

4993e55 重构产品边界。
- shared 保持产品无关，只保留通用 bricks runtime、HTTP、ActionDispatcher。
- 将 Sage 专有 bootstrap/login 逻辑从库包移出，放到应用示例层。
- 增加 WebBricksRequestContext，集中生成 .ui/.dspy 请求所需上下文参数：
  - _webbricks_=1
  - _width
  - _height
  - _is_mobile
  - _lang
- 增加 README，说明产品专有客户端应放在应用工程中，不进入 com.bricks.mp 通用库包。
d9b5455 新增独立 Sage sample app。
- 路径：test/sageclient/
- 通过 Gradle composite build 引用根项目 :shared，不污染根 settings.gradle.kts。
- 增加 build.sh，支持从任意目录运行，并优先使用 repo Gradle wrapper。
- 增加 test/sageclient/README.md。
1f577fd 加强 JDK 检查。
- Kotlin 2.1.0 不支持 Java 25/26 版本字符串。
- build.sh 要求 JDK 17 或 JDK 21；macOS 可自动选择 /usr/libexec/java_home 中的 21/17。
388272b 修复 commonMain redirect 解析。
- 避免使用 Ktor commonMain 中不可用/不稳定的 URLBuilder.encodedPath 等 API。
- 改为平台无关字符串解析，适配绝对、根相对、相对 Location。
87ebf5a 支持 sageclient 启动 URL。
- 支持命令行第一个参数直接传入 https://ai.atvoe.com/center.ui 这类 URL。
- 对绝对 URL：提取 origin 作为 baseUrl，路径和 query 作为初始 urlwidget 加载目标。
- 文档中补充 Gradle run 和 macOS .app 启动方式。

关键技术结论

bricks-mp 的 shared library 必须保持产品无关。
- Sage 登录、默认首页、业务 bootstrap 只能放在 sample/app 层。
- 通用库只提供 BricksHttp、renderer、parser、ActionDispatcher 等基础能力。
.ui / .dspy 后端请求必须带 WebBricks 上下文参数。
- 参数名必须是 _webbricks_，前后都有下划线。
- _webbricks_=1 表示前端 runtime 已存在，服务端应返回直接 UI/DSpy 结果，不应包 HTML bootstrap。
- 同时需要 _width、_height、_is_mobile、_lang。
Compose Desktop 运行时需要从窗口层同步真实 viewport。
- 使用 AWT window size 作为像素尺寸。
- density 转换的 WindowState.size 只作为 fallback。
KMP commonMain 要避免 JVM-only API。
- 不能在 commonMain 依赖 java.net.URLEncoder、java.awt、javax.*。
- URL encode 使用 Ktor common 的 encodeURLParameter()。
构建环境约束明确。
- JDK 17/21 可用。
- Java 25/26 会触发 Kotlin/Gradle 版本解析问题。
- 当前 Linux 执行环境未安装 java，无法在本机完整跑 Gradle build；已通过脚本语法和静态检查兜底。

验证记录

当天完成的验证包括：

Git 提交链完整推送到 origin/main。
test/sageclient/build.sh 增加 JDK 版本检查。
commonMain 中排查并移除不适合 commonMain 的 URLBuilder/encodedPath 依赖。
sample app 使用 composite build，不纳入根项目默认构建。
文档覆盖：
- root README 中说明 WebBricks 参数和 HTTP error/redirect 处理。
- test/sageclient/README.md 中说明构建、运行、启动 URL 和可选系统属性。

后续 2026-05-19 追加修复

19 日零点后根据服务端日志继续修复启动 URL 请求链路：

39727f8 fix: preserve webbricks params for startup ui requests
- 将 .ui/.dspy 请求参数显式合成到最终 URL 后再调用 Ktor client。
- 避免启动 URL 链路中 _webbricks_ 未出现在真实请求 URL，导致 Sage 按普通页面返回 HTML/header/footer 模板。
- README 补充说明：startup URL 仍必须通过 BricksHttp 请求并携带 _webbricks_=1。

当前状态

main 已推送到远端。
最新提交：39727f8 fix: preserve webbricks params for startup ui requests。
2026-05-18 的开发记录已补写在本文件。

6.4 KiB Raw Blame History Unescape Escape