From 54bf9bc901fb524fdca9df0fbfd419859924ca2c Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Mon, 7 Sep 2026 11:42:17 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=20README(pybricks=20?=
 =?UTF-8?q?widget=E5=87=BD=E6=95=B0/load=5Fpybricks=E6=B3=A8=E5=86=8C/?=
 =?UTF-8?q?=E5=B7=B2=E7=9F=A5=E7=BC=BA=E9=99=B7UiConform=E5=B4=A9=E6=BA=83?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index db7bb9f..e716a16 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,39 @@
-# pybricks
+# bricks-for-python（pybricks）
 
-bricks服务器端模块
\ No newline at end of file
+Bricks 前端的服务器端 Python 打包模块：把常用弹窗/消息 widget 的 JSON 构造
+封装成 Python 函数，注册进 ahserver 的 ServerEnv，供各模块 dspy/handler 直接返回 UI。
+
+## 提供的函数（bricks_for_python/init.py）
+
+| 函数 | widgettype | 用途 |
+|------|-----------|------|
+| `UiWindow(title, icon, content, cheight=10, cwidth=15)` | PopupWindow | 弹出内容窗口（movable、auto_open） |
+| `UiConform(title, message, binds=[])` | Conform | 确认对话框 |
+| `UiError(title, message, timeout=5)` | Error | 右上角错误提示 |
+| `UiMessage(title, message, timeout=5)` | Message | 右上角普通消息 |
+| `load_pybricks()` | — | 把上述四个函数注册到 ServerEnv 全局 |
+
+## 宿主集成
+
+宿主应用 `app/<name>.py` 的 `init()` 里：
+
+```python
+from bricks_for_python.init import load_pybricks
+load_pybricks()   # 注册 UiWindow/UiError/UiMessage/UiConform
+```
+
+之后任意 dspy/handler 可直接 `return UiMessage(title='成功', message='...')`。
+与 `bricks`（前端 JS 框架）配套：本模块只产 JSON 声明，渲染由前端 bricks 完成。
+
+## 安装
+
+```bash
+pip install .   # build.sh 基础包清单成员，产线/Sage 宿主都装
+```
+
+## 已知问题（改代码前注意，init.py 全文仅 import ServerEnv）
+
+- `UiConform` 当前调用即崩：`binds:json.dump(...)` 把变量 binds（默认 []，不可哈希）当 dict 键 → TypeError；且 `json`、`entire_url` 均未导入。修复需补 import 并改为 `"binds": json.dumps(...)`。
+- `UiWindow`/`UiConform` 里的 `entire_url(...)` 未导入：UiWindow 仅在 icon 传空时触发 NameError（传了 icon 则可用）。
+- `UiWindow` 的 `if kw: dic.update(kw)` 位于 `return` 之后，是死代码，kw 实际不生效。
+- `UiError`/`UiMessage` 无上述问题，可正常使用（现网主要用这两个）。