diff --git a/docs/ui_test_usage.md b/docs/ui_test_usage.md
new file mode 100644
index 0000000..e437367
--- /dev/null
+++ b/docs/ui_test_usage.md
@@ -0,0 +1,64 @@
+# UI自动化链路使用说明
+
+## 1. 功能简介
+本系统支持通过 Playwright 驱动浏览器，实现 UI 自动化测试。支持两种模式：
+- 每个 UI 步骤新开浏览器（默认）
+- 多个 UI 步骤复用同一个浏览器（如：第一个步骤登录，后续步骤基于已登录状态继续操作）
+
+## 2. 主要参数说明
+| 参数名              | 类型    | 说明                                   |
+|---------------------|---------|----------------------------------------|
+| browser_type        | string  | 浏览器类型（chromium/firefox/webkit）  |
+| headless            | bool    | 是否无头模式                           |
+| user_data           | map     | 登录等用户信息（如有需要）             |
+| browser_session_id  | string  | 浏览器会话ID（用于复用，系统自动传递） |
+| test_case_id        | string  | 用例ID                                 |
+| url_path            | string  | 页面路径                               |
+
+## 3. 复用浏览器的典型用法
+假设有两个步骤：
+- 步骤1：登录
+- 步骤2：添加新条目
+
+只需在用例配置中将两个步骤都设为 `RunUiTest`，系统会自动在步骤间传递 `browser_session_id`，实现浏览器复用。无需手动干预。
+
+**示例参数（JSON）**：
+```json
+{
+  "test_case_id": "login",
+  "url_path": "/login",
+  "browser_type": "chromium",
+  "headless": true,
+  "user_data": {"user": "test", "pass": "test"}
+}
+```
+
+第二步：
+```json
+{
+  "test_case_id": "add_item",
+  "url_path": "/dashboard",
+  "browser_type": "chromium",
+  "headless": true,
+  "user_data": {}
+}
+```
+
+## 4. 工作流结束后
+系统会自动关闭最后一个 UI 测试用到的浏览器，无需手动清理。
+
+## 5. 结果变量
+- `${step.步骤ID.screenshot_url}`：获取某步骤的截图URL
+- `${step.步骤ID.html_report_url}`：获取某步骤的HTML报告URL
+
+## 6. 常见问题
+- **Q: 如何确保多个步骤复用同一个浏览器？**
+  A: 只要步骤类型为 `RunUiTest`，系统会自动传递 browser_session_id。
+- **Q: 需要手动关闭浏览器吗？**
+  A: 不需要，系统会在工作流结束时自动关闭。
+- **Q: 可以并发多个浏览器会话吗？**
+  A: 支持，每个工作流独立管理自己的 browser_session_id。
+
+## 7. 参考
+- 详细参数传递机制见 `docs/activity_parameter_passing.md`
+- UI 测试用例开发可参考 `workers/python/ui_tests.py` 
\ No newline at end of file