docs: 补全 README(pybricks widget函数/load_pybricks注册/已知缺陷UiConform崩溃)

README.md

@@ -1,3 +1,39 @@
-# pybricks
+# bricks-for-python（pybricks）
 
-bricks服务器端模块
+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` 无上述问题，可正常使用（现网主要用这两个）。