From 0e00fb586f8acfe75c27bd4214fa828902abba41 Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Tue, 19 May 2026 00:21:41 +0800
Subject: [PATCH] docs: add 2026-05-18 work log

---
 docs/work-log-2026-05-18.md | 136 ++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/work-log-2026-05-18.md

diff --git a/docs/work-log-2026-05-18.md b/docs/work-log-2026-05-18.md
new file mode 100644
index 0000000..ff10e23
--- /dev/null
+++ b/docs/work-log-2026-05-18.md
@@ -0,0 +1,136 @@
+# 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` 启动方式。
+
+## 关键技术结论
+
+1. `bricks-mp` 的 shared library 必须保持产品无关。
+   - Sage 登录、默认首页、业务 bootstrap 只能放在 sample/app 层。
+   - 通用库只提供 BricksHttp、renderer、parser、ActionDispatcher 等基础能力。
+
+2. `.ui` / `.dspy` 后端请求必须带 WebBricks 上下文参数。
+   - 参数名必须是 `_webbricks_`，前后都有下划线。
+   - `_webbricks_=1` 表示前端 runtime 已存在，服务端应返回直接 UI/DSpy 结果，不应包 HTML bootstrap。
+   - 同时需要 `_width`、`_height`、`_is_mobile`、`_lang`。
+
+3. Compose Desktop 运行时需要从窗口层同步真实 viewport。
+   - 使用 AWT window size 作为像素尺寸。
+   - density 转换的 `WindowState.size` 只作为 fallback。
+
+4. KMP commonMain 要避免 JVM-only API。
+   - 不能在 commonMain 依赖 `java.net.URLEncoder`、`java.awt`、`javax.*`。
+   - URL encode 使用 Ktor common 的 `encodeURLParameter()`。
+
+5. 构建环境约束明确。
+   - 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 的开发记录已补写在本文件。