README: surface examples, OCR backends, observability, uv.lock

Three README languages updated to reflect what landed this session:

- examples/: each README now has a short pointer to the 17-script
  directory at the top of Quick Start, before the API-snippet sections.
- OCR backends: the OCR feature bullet and the OCR Quick Start section
  mention the three pluggable backends (Tesseract / EasyOCR /
  PaddleOCR), the AUTOCONTROL_OCR_BACKEND env var, and link to the
  per-language backend docs.
- Observability: new Quick Start section + a feature bullet covering
  the Prometheus /metrics exporter and the OpenTelemetry-compatible
  tracer that AutoControl ships with stdlib-only.
- uv.lock: Development > Setting Up shows how to use the committed
  lockfile (uv sync / uv lock --upgrade).

No changes to docs/source/ — the new OCR-backends and observability
pages were already wired into both language indexes earlier in the
session.

Author: JE-Chen

README.md

@@ -37,6 +37,7 @@
   - [Event Triggers](#event-triggers)
   - [Run History](#run-history)
   - [Report Generation](#report-generation)
+  - [Observability (Prometheus / OpenTelemetry)](#observability-prometheus--opentelemetry)
   - [Remote Automation (Socket / REST)](#remote-automation-socket--rest)
   - [Plugin Loader](#plugin-loader)
   - [Shell Command Execution](#shell-command-execution)
@@ -60,7 +61,7 @@
 - **Image Recognition** — locate UI elements on screen using OpenCV template matching with configurable threshold
 - **Accessibility Element Finder** — query the OS accessibility tree (Windows UIA / macOS AX) to locate buttons, menus, and controls by name/role
 - **AI Element Locator (VLM)** — describe a UI element in plain language and let a vision-language model (Anthropic / OpenAI) find its screen coordinates
-- **OCR** — extract text from screen regions using Tesseract; wait for, click, or locate rendered text; regex search and full-region dump
+- **OCR** — extract text from screen regions through three pluggable backends (Tesseract for ASCII, EasyOCR for CJK without an external binary, PaddleOCR for highest-quality Chinese / Japanese / Korean). Single unified API + canonical language codes; backend chosen by `backend=` kwarg, `AUTOCONTROL_OCR_BACKEND` env var, or auto-detection. Wait for, click, or locate rendered text; regex search and full-region dump
 - **LLM Action Planner** — translate a plain-language description into a validated `AC_*` action list using Claude
 - **Runtime Variables & Control Flow** — `${var}` substitution at execution time, plus `AC_set_var` / `AC_inc_var` / `AC_if_var` / `AC_for_each` / `AC_loop` / `AC_retry` for data-driven scripts
 - **Remote Desktop** — stream this machine's screen and accept remote input over a token-authenticated TCP protocol, *or* connect to another machine and view + control it (host + viewer GUIs included). Optional TLS (HTTPS-grade encryption), WebSocket transport (ws:// + wss:// for browser / firewall-friendly clients), persistent 9-digit Host ID, host→viewer audio streaming, bidirectional clipboard sync (text + image), and chunked file transfer (drag-drop + progress bar; arbitrary destination path; no size cap). Plus folder sync (additive mirror — local deletions never propagate) and a self-hosted coturn TURN config bundle generator (turnserver.conf + systemd unit + docker-compose + README). **AnyDesk-style popout**: when the viewer authenticates, the live remote desktop opens in its own resizable top-level window so the control panel stays uncluttered. The Remote Desktop tabs are wrapped in `QScrollArea` so the panel stays usable on small windows and stretches edge-to-edge on 4K displays. Driveable headlessly via `je_auto_control` and over MCP through the new `ac_remote_*` tools
@@ -94,6 +95,7 @@
 - **OpenAPI 3.1 + Swagger UI** — `GET /openapi.json` (auth-gated, generated from the live route table) + `GET /docs` (browser Swagger UI with bearer token bar). Drift test in CI catches new routes added without metadata.
 - **Configuration Bundle** — single-file JSON export/import of user config (admin hosts, address book, trusted viewers, known hosts, host service, IDs). Atomic write with `<name>.bak.<timestamp>` backups; CLI `python -m je_auto_control.utils.config_bundle export|import`; `POST /config/{export,import}`; GUI buttons on the REST API tab.
 - **USB Passthrough (experimental, opt-in)** — wire-level protocol over a WebRTC `usb` DataChannel (10 opcodes, CREDIT-based flow control, 16 KiB payload cap). Host-side `UsbPassthroughSession` end-to-end on the Linux libusb backend; Windows `WinUSB` backend with full ctypes wiring (hardware-unverified); macOS `IOKit` skeleton. Viewer-side blocking client (`UsbPassthroughClient` → `ClientHandle.control_transfer / bulk_transfer / interrupt_transfer`). Persistent ACL (`~/.je_auto_control/usb_acl.json`, default deny, mode 0600) with host-side prompt QDialog and tamper-evident audit-log integration. Default off — opt-in via `enable_usb_passthrough(True)` or `JE_AUTOCONTROL_USB_PASSTHROUGH=1`. Phase 2e external security review checklist included; default-on requires sign-off.
+- **Observability (Prometheus + OpenTelemetry)** — stdlib-only `Counter` / `Gauge` / `Histogram` registry with a tiny built-in HTTP exporter on `/metrics`, plus an OpenTelemetry-compatible tracer that upgrades to real OTel spans when the SDK is installed. The executor and agent loop emit `autocontrol_action_calls_total{action,outcome}`, `autocontrol_action_duration_seconds`, and `autocontrol_agent_steps_total{tool,outcome}` automatically — drop the URL into a Prometheus scrape config and you have a Grafana dashboard with zero per-script wiring.
 
 ---
 
@@ -334,6 +336,14 @@ third-party components and their licenses.
 
 ## Quick Start
 
+Looking for copy-pasteable end-to-end scripts instead of API snippets?
+The [`examples/`](examples/) directory has 17 self-contained programs
+covering screenshot + click, OCR, the headless scheduler, remote
+desktop, the agent loop, observability, recording / replay, runtime
+variables, window management, hotkeys, image triggers, HTML reports,
+the MCP stdio bridge, the REST API, the secrets vault, and plugin
+loading.
+
 ### Mouse Control
 
 ```python
@@ -463,12 +473,26 @@ ac.click_text("Submit")
 ac.wait_for_text("Loading complete", timeout=15.0)
 ```
 
+Backend selection — set ``AUTOCONTROL_OCR_BACKEND=tesseract|easyocr|paddleocr``
+or pass ``backend=`` per call; otherwise auto-detection picks the first
+one that imports:
+
+```python
+ac.find_text_matches("登入", lang="chi_tra", backend="easyocr")
+ac.click_text("Sign in", backend="tesseract")
+```
+
 If Tesseract is not on `PATH`, point at it explicitly:
 
 ```python
 ac.set_tesseract_cmd(r"C:\Program Files\Tesseract-OCR\tesseract.exe")
 ```
 
+Backend install paths and the canonical lang-code table are in
+[docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst](docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst)
+(or the [繁體中文](docs/source/Zh/doc/ocr_backends/ocr_backends_doc.rst)
+version).
+
 Dump every recognised text record in a region (or full screen), or
 search by regex when the text varies:
 
@@ -1086,6 +1110,36 @@ xml_string = je_auto_control.generate_xml()
 
 Reports include: function name, parameters, timestamp, and exception info (if any) for each recorded action. HTML reports display successful actions in cyan and failed actions in red.
 
+### Observability (Prometheus / OpenTelemetry)
+
+Stdlib-only metric primitives plus an OpenTelemetry-compatible tracer
+fallback. The executor and agent loop emit call counts and latency
+histograms automatically — no per-script wiring required.
+
+```python
+import je_auto_control as ac
+
+# Expose /metrics on http://127.0.0.1:9090 for Prometheus to scrape.
+exporter = ac.default_metrics_exporter()
+exporter.start()
+
+# Add your own metric — same shapes as prometheus_client.
+counter = ac.default_metric_registry().register(ac.MetricCounter(
+    "myapp_widgets_built_total", "widgets built",
+    label_names=("kind",),
+))
+counter.inc(labels={"kind": "blue"})
+
+# Wrap a callable in a span — no-op until opentelemetry-api is installed.
+@ac.traced("my_pipeline.process_one")
+def process_one(item): ...
+```
+
+Built-in metrics are listed in
+[docs/source/Eng/doc/observability/observability_doc.rst](docs/source/Eng/doc/observability/observability_doc.rst)
+(or the [繁體中文](docs/source/Zh/doc/observability/observability_doc.rst)
+version).
+
 ### Remote Automation (Socket / REST)
 
 Two servers are available — a raw TCP socket and a stdlib HTTP/REST
@@ -1348,6 +1402,13 @@ cd AutoControl
 pip install -r dev_requirements.txt
 ```
 
+Reproducible installs use the committed `uv.lock`:
+
+```bash
+uv sync               # install pinned versions across the whole dep tree
+uv lock --upgrade     # refresh after editing pyproject.toml
+```
+
 ### Running Tests
 
 ```bash

README/README_zh-CN.md

@@ -36,6 +36,7 @@
   - [事件触发器](#事件触发器)
   - [执行历史](#执行历史)
   - [报告生成](#报告生成)
+  - [可观测性（Prometheus / OpenTelemetry）](#可观测性prometheus--opentelemetry)
   - [远程自动化（Socket / REST）](#远程自动化socket--rest)
   - [插件加载器](#插件加载器)
   - [Shell 命令执行](#shell-命令执行)
@@ -59,7 +60,7 @@
 - **图像识别** — 使用 OpenCV 模板匹配在屏幕上定位 UI 元素，支持可配置的检测阈值
 - **Accessibility 元件搜索** — 通过操作系统无障碍树（Windows UIA / macOS AX）按名称/角色定位按钮、菜单、控件
 - **AI 元件定位（VLM）** — 用自然语言描述 UI 元素，由视觉语言模型（Anthropic / OpenAI）返回屏幕坐标
-- **OCR** — 使用 Tesseract 从屏幕提取文字，可搜索、点击或等待文字出现；支持 regex 搜索与整块区域 dump
+- **OCR** — 三个可插拔后端（Tesseract 用于 ASCII、EasyOCR 无外部可执行文件且支持 CJK、PaddleOCR 中／日／韩质量最高），统一 API 与标准语言代码；后端由 `backend=` 参数、`AUTOCONTROL_OCR_BACKEND` 环境变量或自动探测决定。可搜索、点击或等待文字出现；支持 regex 搜索与整块区域 dump
 - **LLM 动作规划器** — 用 Claude 把自然语言描述翻译成验证过的 `AC_*` 动作清单
 - **运行期变量与流程控制** — 执行时 `${var}` 替换，加上 `AC_set_var` / `AC_inc_var` / `AC_if_var` / `AC_for_each` / `AC_loop` / `AC_retry` 让脚本数据驱动
 - **远程桌面** — 用 token 认证的 TCP 协议串流本机画面并接收输入，**或** 连接到他机观看与控制（host + viewer GUI 内置）。可选 TLS（HTTPS 级加密）、WebSocket 传输（``ws://`` + ``wss://``，穿墙／浏览器友好）、持久化 9 位数 Host ID、host→viewer 音频串流、双向剪贴板同步（文字 + 图片）、分块文件传输（拖放 + 进度条；任意目的路径；无大小上限）。另含文件夹同步（增量镜像 — 本地删除不会传出去）与自建 coturn TURN 配置包生成器（turnserver.conf + systemd unit + docker-compose + README）。**AnyDesk 风格弹出窗口**：viewer 认证成功后远程桌面会开在独立的可调整大小顶层窗口，控制面板保持简洁；Remote Desktop 子分页外层包了 `QScrollArea`，小窗口下可滚动、4K 屏幕下会铺满。同时支持 headless API 与 MCP 工具 (`ac_remote_*`) 直接驱动
@@ -331,6 +332,12 @@ sudo apt-get install cmake libssl-dev
 
 ## 快速开始
 
+想要可以直接复制粘贴的完整脚本而不只是 API 片段？
+[`examples/`](../examples/) 目录收录 17 个独立示例：截屏+点击、OCR、
+调度器、远程桌面、agent loop、可观测性、录制/回放、运行期变量、
+窗口管理、热键、图像触发器、HTML 报告、MCP stdio bridge、REST API、
+secret vault，以及插件加载。
+
 ### 鼠标控制
 
 ```python
@@ -457,12 +464,24 @@ ac.click_text("Submit")
 ac.wait_for_text("加载完成", timeout=15.0)
 ```
 
+选择后端 — 设置 ``AUTOCONTROL_OCR_BACKEND=tesseract|easyocr|paddleocr``
+或在调用时传入 ``backend=``；都不设置时会自动挑第一个 import 成功的：
+
+```python
+ac.find_text_matches("登录", lang="chi_sim", backend="easyocr")
+ac.click_text("Sign in", backend="tesseract")
+```
+
 若 Tesseract 不在 `PATH` 中，可手动指定路径：
 
 ```python
 ac.set_tesseract_cmd(r"C:\Program Files\Tesseract-OCR\tesseract.exe")
 ```
 
+各后端安装路径与标准语言代码表见
+[docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst](../docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst)
+或[繁体中文版本](../docs/source/Zh/doc/ocr_backends/ocr_backends_doc.rst)。
+
 把区域（或整屏）内所有识别到的文字 dump 出来，或用 regex 搜索变动内容：
 
 ```python
@@ -999,6 +1018,35 @@ xml_string = je_auto_control.generate_xml()
 
 报告内容包含：每个记录动作的函数名称、参数、时间戳及异常信息（如有）。HTML 报告中成功的动作以青色显示，失败的动作以红色显示。
 
+### 可观测性（Prometheus / OpenTelemetry）
+
+纯标准库的 metric 原语加上 OpenTelemetry 兼容 tracer，
+executor 与 agent loop 会自动发送调用次数与延迟分布 metric，
+不用手动 instrument。
+
+```python
+import je_auto_control as ac
+
+# 在 http://127.0.0.1:9090 开放 /metrics，给 Prometheus scrape。
+exporter = ac.default_metrics_exporter()
+exporter.start()
+
+# 自定义 metric — 形状与 prometheus_client 相同。
+counter = ac.default_metric_registry().register(ac.MetricCounter(
+    "myapp_widgets_built_total", "widgets built",
+    label_names=("kind",),
+))
+counter.inc(labels={"kind": "blue"})
+
+# 把 callable 包进 span — 未安装 opentelemetry-api 时为 no-op。
+@ac.traced("my_pipeline.process_one")
+def process_one(item): ...
+```
+
+内建 metric 清单见
+[docs/source/Eng/doc/observability/observability_doc.rst](../docs/source/Eng/doc/observability/observability_doc.rst)
+或[繁体中文版](../docs/source/Zh/doc/observability/observability_doc.rst)。
+
 ### 远程自动化（Socket / REST）
 
 提供两种服务器：原始 TCP socket 与纯 stdlib HTTP/REST。默认均绑定
@@ -1237,6 +1285,13 @@ cd AutoControl
 pip install -r dev_requirements.txt
 ```
 
+可复现的安装走已 commit 的 `uv.lock`：
+
+```bash
+uv sync               # 依锁文件同步整条依赖链
+uv lock --upgrade     # 编辑 pyproject.toml 后重新锁
+```
+
 ### 运行测试
 
 ```bash

README/README_zh-TW.md

@@ -36,6 +36,7 @@
   - [事件觸發器](#事件觸發器)
   - [執行歷史](#執行歷史)
   - [報告產生](#報告產生)
+  - [可觀測性（Prometheus / OpenTelemetry）](#可觀測性prometheus--opentelemetry)
   - [遠端自動化（Socket / REST）](#遠端自動化socket--rest)
   - [外掛載入器](#外掛載入器)
   - [Shell 命令執行](#shell-命令執行)
@@ -59,7 +60,7 @@
 - **圖像辨識** — 使用 OpenCV 模板匹配在螢幕上定位 UI 元素，支援可設定的偵測閾值
 - **Accessibility 元件搜尋** — 透過作業系統無障礙樹（Windows UIA / macOS AX）依名稱/角色定位按鈕、選單、控制項
 - **AI 元件定位（VLM）** — 用自然語言描述 UI 元素，交由視覺語言模型（Anthropic / OpenAI）取得螢幕座標
-- **OCR** — 使用 Tesseract 從螢幕擷取文字，可搜尋、點擊或等待文字出現；支援 regex 搜尋與整塊區域 dump
+- **OCR** — 三個可插拔後端（Tesseract 用於 ASCII、EasyOCR 不需外部執行檔且支援 CJK、PaddleOCR 中／日／韓品質最佳），統一 API 與標準語言代碼；後端由 `backend=` 參數、`AUTOCONTROL_OCR_BACKEND` 環境變數或自動偵測決定。可搜尋、點擊或等待文字出現；支援 regex 搜尋與整塊區域 dump
 - **LLM 動作規劃器** — 用 Claude 把自然語言描述翻譯成驗證過的 `AC_*` 動作清單
 - **執行期變數與流程控制** — 執行時 `${var}` 取代，加上 `AC_set_var` / `AC_inc_var` / `AC_if_var` / `AC_for_each` / `AC_loop` / `AC_retry` 讓腳本資料驅動
 - **遠端桌面** — 用 token 認證的 TCP 協定串流本機畫面並接收輸入，**或** 連線到他機觀看與控制（host + viewer GUI 皆內建）。可選 TLS（HTTPS 級加密）、WebSocket 傳輸（``ws://`` + ``wss://``，穿牆／瀏覽器友善）、持久化 9 位數 Host ID、host→viewer 音訊串流、雙向剪貼簿同步（文字 + 圖片）、分塊檔案傳輸（拖放 + 進度條；任意目的路徑；無大小上限）。另含資料夾同步（增量鏡像 — 本地刪除不會傳出去）與自架 coturn TURN 設定包產生器（turnserver.conf + systemd unit + docker-compose + README）。**AnyDesk 風格彈出視窗**：viewer 認證成功後遠端桌面會開在獨立的可調整大小頂層視窗，控制面板維持簡潔；Remote Desktop 子分頁外層包了 `QScrollArea`，小視窗下可捲動、4K 螢幕下會延展到整寬。同時可由 headless API 與 MCP 工具（`ac_remote_*`）直接驅動
@@ -331,6 +332,12 @@ sudo apt-get install cmake libssl-dev
 
 ## 快速開始
 
+想要可以直接複製貼上的完整腳本而不只是 API 片段？
+[`examples/`](../examples/) 資料夾收錄 17 支獨立範例：截圖+點擊、OCR、
+排程器、遠端桌面、agent loop、可觀測性、錄製/回放、執行期變數、
+視窗管理、熱鍵、影像觸發、HTML 報告、MCP stdio bridge、REST API、
+secret vault，以及外掛載入。
+
 ### 滑鼠控制
 
 ```python
@@ -457,12 +464,24 @@ ac.click_text("Submit")
 ac.wait_for_text("載入完成", timeout=15.0)
 ```
 
+選擇後端 — 設定 ``AUTOCONTROL_OCR_BACKEND=tesseract|easyocr|paddleocr``
+或在呼叫時傳入 ``backend=``；都不設定時會自動挑第一個 import 成功的：
+
+```python
+ac.find_text_matches("登入", lang="chi_tra", backend="easyocr")
+ac.click_text("Sign in", backend="tesseract")
+```
+
 若 Tesseract 不在 `PATH` 中，可手動指定路徑：
 
 ```python
 ac.set_tesseract_cmd(r"C:\Program Files\Tesseract-OCR\tesseract.exe")
 ```
 
+各後端安裝路徑與標準語言代碼表見
+[docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst](../docs/source/Eng/doc/ocr_backends/ocr_backends_doc.rst)
+或[繁體中文版本](../docs/source/Zh/doc/ocr_backends/ocr_backends_doc.rst)。
+
 把區域（或整螢幕）內所有辨識到的文字 dump 出來，或用 regex 搜尋變動內容：
 
 ```python
@@ -999,6 +1018,35 @@ xml_string = je_auto_control.generate_xml()
 
 報告內容包含：每個紀錄動作的函式名稱、參數、時間戳記及例外資訊（如有）。HTML 報告中成功的動作以青色顯示，失敗的動作以紅色顯示。
 
+### 可觀測性（Prometheus / OpenTelemetry）
+
+純標準函式庫的 metric 元件加上 OpenTelemetry 相容 tracer，
+executor 與 agent loop 都會自動發送呼叫次數與延遲分布 metric，
+不用手動 instrument。
+
+```python
+import je_auto_control as ac
+
+# 在 http://127.0.0.1:9090 開放 /metrics，給 Prometheus scrape。
+exporter = ac.default_metrics_exporter()
+exporter.start()
+
+# 自訂 metric — 形狀與 prometheus_client 相同。
+counter = ac.default_metric_registry().register(ac.MetricCounter(
+    "myapp_widgets_built_total", "widgets built",
+    label_names=("kind",),
+))
+counter.inc(labels={"kind": "blue"})
+
+# 把 callable 包進 span — 未安裝 opentelemetry-api 時為 no-op。
+@ac.traced("my_pipeline.process_one")
+def process_one(item): ...
+```
+
+內建 metric 清單見
+[docs/source/Eng/doc/observability/observability_doc.rst](../docs/source/Eng/doc/observability/observability_doc.rst)
+或[繁體中文版本](../docs/source/Zh/doc/observability/observability_doc.rst)。
+
 ### 遠端自動化（Socket / REST）
 
 提供兩種伺服器：原始 TCP socket 與純 stdlib HTTP/REST。預設均綁定
@@ -1237,6 +1285,13 @@ cd AutoControl
 pip install -r dev_requirements.txt
 ```
 
+可重現的安裝走已 commit 的 `uv.lock`：
+
+```bash
+uv sync               # 依鎖檔同步整條相依鏈
+uv lock --upgrade     # 編輯 pyproject.toml 後重新鎖
+```
+
 ### 執行測試
 
 ```bash