新功能 (2026-06-18) — CLI 與整合

八項 headless 能力,補齊腳本化、整合與 CI 使用情境:一個真正的命令列介面、把錄製轉成程式碼,以及一級的 HTTP / SQL / Email / PDF / 等待步驟。每項功能都提供 headless Python API、AC_* 執行器指令、MCP 工具,以及視覺化 Script Builder 項目,並有 headless 測試覆蓋——網路、SMTP、PDF 後端皆以注入方式測試,完全不會碰到外部系統。

命令列介面 

套件現在會安裝 je_auto_control console script,可在 shell 或 CI 中執行與檢查動作檔:

je_auto_control run script.json --var user=alice --dry-run
je_auto_control validate script.json      # 別名:lint
je_auto_control list-commands --filter mouse --json
je_auto_control fmt script.json --check
je_auto_control record out.json --duration 5
je_auto_control codegen script.json --target pytest -o test_flow.py
je_auto_control version

run 直接執行(--dry-run 只驗證並列出步驟而不實際操作), validate / lint 檢查結構並拒絕未知指令,``fmt`` 標準化 JSON, record 錄製輸入,``codegen`` 產生程式碼(見下),``list-commands`` 列出執行器即時的指令目錄。

程式碼產生 

把錄製或動作檔轉成可提交、可執行的程式碼:

from je_auto_control import generate_code, generate_code_file

code = generate_code(actions, target="pytest", style="calls")
generate_code_file("flow.json", "test_flow.py", target="pytest")

target 可為 pytest / python / robot。預設的 calls 風格會把每個 AC_* 指令對應到 facade 呼叫(ac.click_mouse(...)), 流程控制與私有 adapter 則退回 ac.execute_action([...]);``actions`` 風格則直接嵌入動作清單並透過執行器重播。

執行器指令:AC_generate_code。CLI:je_auto_control codegen。

HTTP / API 

不需額外相依的 HTTP(S) 客戶端,適合 UI + API 混合流程:

from je_auto_control import http_request

resp = http_request(
    "https://api.example/items", method="POST",
    json_body={"name": "Sam"},
    headers={"X-Trace": "1"},
    auth={"type": "bearer", "token": "..."},
    timeout=30.0)
assert resp["status"] == 201

回傳 {status, ok, headers, text, json, url};非 2xx 回應會被回傳而非丟出例外,因此可直接對狀態碼斷言。僅允許 http / https。 AC_http_to_var 現在共用同一個客戶端,因此也能送 body、headers 與認證。

執行器指令:AC_http_request。

SQL 

唯讀、參數化的 SQLite 查詢:

from je_auto_control import query_sqlite

rows = query_sqlite("app.db", "SELECT id, name FROM users")
count = query_sqlite("app.db",
                     "SELECT COUNT(*) FROM users WHERE active = ?",
                     params=[1], fetch="scalar")

查詢僅限單句唯讀的 SELECT / WITH,以唯讀連線執行,且值一律以參數綁定(絕不字串拼接)。

執行器指令:``AC_sql_to_var``(列 / 單列 / 純量存入變數)與 ``AC_assert_db``(對純量查詢以 eq / ne / lt / gt / contains / … 斷言)。

Email(SMTP)

透過標準庫寄信——例如流程的報告:

from je_auto_control import send_email

send_email(
    {"sender": "bot@x.com", "to": ["qa@x.com"],
     "subject": "Run passed", "body": "All green",
     "attachments": ["report.html"]},
    {"host": "smtp.x.com", "port": 587,
     "username": "bot@x.com", "password": "..."})

預設啟用 TLS(STARTTLS,或設定 use_ssl 時用隱式 SSL),使用已驗證憑證的預設 context;支援多收件人、CC、HTML 內文與檔案附件。

執行器指令:AC_send_email。

PDF 

從 PDF 文件抽取文字並斷言其內容(可選的 pypdf 後端—— pip install je_auto_control[pdf]):

from je_auto_control import extract_pdf_text, assert_pdf_text

text = extract_pdf_text("invoice.pdf", pages=1)
assert_pdf_text("invoice.pdf", "Total: $50.00")

執行器指令:AC_pdf_to_var``(文字存入變數)與 ``AC_assert_pdf_text (文字存在 / 不存在,可指定頁碼)。

智慧等待 

兩個用來取代不可靠 sleep 的等待:

from je_auto_control import (
    wait_until_file, wait_until_port, wait_until_process)

wait_until_file("~/Downloads/report.pdf", stable_for_s=1.0)
wait_until_port("127.0.0.1", 8080, timeout_s=30.0)
wait_until_process("myserver", present=True, timeout_s=30.0)

wait_until_file 會在檔案存在、達到 min_size 位元組、且大小持續 stable_for_s 秒不變(下載寫完)後回傳。wait_until_port 會在 host:port 可接受 TCP 連線後回傳——是啟動伺服器的最佳搭檔。兩者都回傳 WaitOutcome 並有硬性 timeout_s 上限。

wait_until_process 會在名稱含目標字串的行程出現(或 present=False 時結束)後回傳——是 launch_process / kill_process 的搭檔(需 psutil)。

執行器指令:AC_wait_for_file、AC_wait_for_port、AC_wait_for_process。

安全性 

HTTP 與 SMTP 強制 http / https 或使用已驗證憑證的 TLS,並設定明確逾時;SQL 為唯讀且參數綁定;所有使用者提供的檔案路徑在 I/O 前都會以 realpath 解析。