cli-anything-web-yu-pri用 CLI 與 Playwright 驅(qū)動日本郵政 Web Yu-pri 報關(guān)內(nèi)容表單的 Agent 實戰(zhàn)指南【免費下載鏈接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/項目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingWeb Yu-priWeb ゆうプリ是日本郵政面向登錄用戶的 Web 標(biāo)簽錄入應(yīng)用其「內(nèi)容品目contents行錄入」高度重復(fù)。cli-anything-web-yu-pri 以https://mgr.post.japanpost.jp/C30P01Action.do為入口通過 Playwright 驅(qū)動真實瀏覽器 UI把「登錄、巡檢、截圖、dry-run 規(guī)劃、內(nèi)容表單填寫」全部封裝為結(jié)構(gòu)化 CLI 命令讓 LLM Agent 能夠安全、可驗證地完成申報內(nèi)容的自動化錄入。讀完本文你將掌握該技能的安裝方式、命令語義、Items 文件規(guī)范、選擇器診斷方法以及源碼層面的填報流程與安全邊界。一、設(shè)計背景為什么用 CLI 驅(qū)動真實瀏覽器而不是重寫業(yè)務(wù)邏輯Web Yu-pri 是一個需要登錄的 Web 應(yīng)用業(yè)務(wù)邏輯校驗、計費、運單號生成完全在服務(wù)端閉環(huán)。cli-anything-web-yu-pri 沒有嘗試在本地重新實現(xiàn)日本郵政的報關(guān)邏輯而是把「瀏覽器里的人肉操作」轉(zhuǎn)化為「可被 Agent 調(diào)用的 CLI 原語」。這一設(shè)計在倉庫的 SOP 文檔 WEB_YU_PRI.md 中被明確概括為This harness turns Japan Posts Web Yu-pri browser workflow into an agent-friendly CLI. Web Yu-pri is a logged-in web application, so the CLI drives the real browser UI through Playwright instead of reimplementing Japan Post business logic.關(guān)鍵技術(shù)事實見 core/browser.py官方起始 URL登錄頁https://mgr.post.japanpost.jp/C30P01Action.do已知內(nèi)容表單 URLhttps://mgr.post.japanpost.jp/M060800.do瀏覽器引擎Playwright Chromium配合持久化用戶 Profilepersistent profile用戶在 Profile 中手動登錄一次之后 CLI 復(fù)用會話憑據(jù)策略CLI 從不接收、也從不存儲賬號密碼這套「真實瀏覽器 持久化 Profile 結(jié)構(gòu)化命令」的組合正是本技能能夠既自動化、又保持賬號安全的關(guān)鍵。二、安裝與環(huán)境準(zhǔn)備技能本身是一份 Agent Skill 元數(shù)據(jù)其對應(yīng) Python 包為cli-anything-web-yu-pri版本 0.1.0見 setup.pyPython 要求3.10核心依賴為click8.1,9.0與playwright1.45,2.0。pip install githttps://github.com/HKUDS/CLI-Anything.git#subdirectoryweb-yu-pri/agent-harness如果本機沒有可用的瀏覽器執(zhí)行python -m playwright install chromium也可以安裝 Microsoft Edge 或 Chrome 后通過--browser-channel msedge或--browser-channel chrome指定通道。從 browser_session 的實現(xiàn) 可以看到啟動回退順序顯式指定的 channel →msedge→chrome→ Playwright 內(nèi)置 chromium每個通道都會附加--disable-blink-featuresAutomationControlled參數(shù)以減少自動化痕跡全部失敗時才報錯并匯總各通道錯誤。安裝后建議先跑一次體檢命令確認(rèn) Playwright 與 Profile 路徑狀態(tài)cli-anything-web-yu-pri doctordoctor會返回profile_dir、login_url、contents_url與playwright_available等信息實現(xiàn)見 browser.py。默認(rèn) Profile 目錄為~/.cli-anything-web-yu-pri/profile可用全局參數(shù)--profile-dir覆蓋。三、安全規(guī)則Agent 自動化的紅線技能文檔SKILL.md規(guī)定了四條必須遵守的安全規(guī)則這些規(guī)則不只是使用建議在源碼層同樣有對應(yīng)落實不要把日本郵政憑據(jù)寫入命令、文件、日志或 Prompt。CLI 的憑據(jù)模型決定了它根本不接受密碼參數(shù)登錄只發(fā)生在瀏覽器 Profile 內(nèi)的人工操作中。使用open-login讓用戶先在持久化 Profile 中手動登錄之后所有命令復(fù)用該登錄會話。真實填寫之前必須先執(zhí)行contents fill ... --dry-run --json做離線驗證。CLI 不點擊最終的出貨確認(rèn)/購買按鈕。contents fill在填完內(nèi)容品目與申報總價后即停止JSON 輸出的safety對象中final_submit_clicked恒為false見 fill_contents 的返回值。當(dāng)源數(shù)據(jù)存在獨立的獎項/類別行時保持逐行獨立同時保留用戶請求的申報總價對應(yīng)--total-value覆蓋機制見第五節(jié)。這套安全模型在 WEB_YU_PRI.md 中被總結(jié)為第一版只自動化「重復(fù)性數(shù)據(jù)錄入」填寫內(nèi)容包括品目行、申報總價、可選包裝類型與危險品標(biāo)志但絕不觸碰最終提交按鈕。四、命令總覽與--json機器可讀輸出全局參數(shù)--json讓所有命令輸出結(jié)構(gòu)化的 JSON專為 Agent 消費設(shè)計默認(rèn)人類可讀輸出則由emit/fail統(tǒng)一格式化見 web_yu_pri_cli.py。錯誤時--json模式輸出{error: ..., type: 異常類型名}并退出碼 1。技能文檔給出的常用命令組合cli-anything-web-yu-pri --json doctor cli-anything-web-yu-pri open-login cli-anything-web-yu-pri --json status --url https://mgr.post.japanpost.jp/M060800.do cli-anything-web-yu-pri --json plan items.json cli-anything-web-yu-pri --json contents fill items.json --dry-run cli-anything-web-yu-pri --json contents fill items.json --total-value 17000完整子命令清單對應(yīng) README.md 與 CLI 實現(xiàn)命令作用doctor檢查本地運行時與 Profile 路徑selectors打印已知的 Web Yu-pri 選擇器映射表plan items-file校驗 JSON/CSV/TSV 品目文件并計算總額open-login在持久化 Profile 中打開登錄/起始 URLstatus打開 URL 并報告標(biāo)題、當(dāng)前 URL 與選擇器存在性snapshot -o page.png截取頁面截圖可附帶 HTML 快照contents fill items-file填寫內(nèi)容品目行與申報總價repl啟動一個交互式小 REPL 便于逐條執(zhí)行上述命令各命令的關(guān)鍵選項見 web_yu_pri_cli.pyopen-login--url默認(rèn)登錄 URL、--headless、--browser-channel、--wait/--no-wait保持瀏覽器開啟直到按回車默認(rèn)人類輸出時開啟、--json時關(guān)閉status--url、--headless、--browser-channelsnapshot--url、-o/--output必填 PNG 路徑、--html-output可選 HTML dump、--headless、--browser-channelcontents fill--url默認(rèn)內(nèi)容表單 URL、--country-default、--total-value、--value-mode、--package-type、--danger/--no-danger、--dry-run、--headless、--browser-channel、--delay-ms默認(rèn) 500每條品目添加后的等待毫秒數(shù)open-login默認(rèn)人類輸出下會進入交互會話打開頁面后提示「Log in or inspect the page, then press Enter here to close the browser」用戶在真實瀏覽器窗口完成登錄回車后關(guān)閉會話--json模式下則直接打開即返回不阻塞等待。五、Items 文件JSON/CSV/TSV 輸入規(guī)范與字段別名技能把「一次申報的內(nèi)容品目」建模為一個獨立的輸入文件。JSON 格式{ items: [ {description: Award plaque, value: 8000, quantity: 1, country: KR}, {description: Certificate, value: 9000, quantity: 1, country: KR} ] }頂層items為數(shù)組每個元素是一個品目對象也允許直接傳品目數(shù)組_load_json同時支持 dict 與 list 兩種載荷見 items.py。CSV/TSV 則要求含表頭的首行并按后綴自動選擇分隔符CSV 用逗號、TSV 用制表符。CSV 表頭支持豐富的別名技能文檔中的別名清單與 items.py 完全一致語義可用別名description品目描述description、desc、content、contents、item、name、pkgvalue金額value、declared_value、cost、price、amount、yen、jpyquantity數(shù)量quantity、qty、num、countcountry原產(chǎn)國country、country_code、country_of_origin、origin、couCd、cou_cdHS code海關(guān)編碼hs_code、hs、hscode、hsCodedescription,value,quantity,country,hs_code Award plaque,8000,1,KR, Certificate,9000,1,KR,value的語義與--value-mode默認(rèn)value視為該行的行總價line value即line_total value當(dāng)value是單價、需要乘以quantity時加--value-mode unit此時line_total value * quantity見 ItemLine.line_total。輸入規(guī)范化細(xì)節(jié)有單測佐證見 test_core.py金額解析支持千分位逗號與日元符號8,000、JPY 8000等會被清洗為整數(shù)8000布爾值會被拒絕負(fù)數(shù)與低于下限的值報錯_coerce_int國家代碼強制兩位大寫 ISO 碼如kr會規(guī)范化為KRKOR這類三位碼直接拋ValueErrorHS code允許字母、數(shù)字、點與連字符去除內(nèi)部空白長度 2–20 字符品目描述不可為空每行quantity缺省為 1country缺省時可從--country-default注入六、填報規(guī)劃plan與總額計算plan命令不打開瀏覽器僅校驗文件并輸出確定性的填報計劃是 Agent「先驗證、后執(zhí)行」的關(guān)鍵一步。規(guī)劃由 build_contents_plan 生成核心字段字段含義item_count品目行數(shù)computed_total由各行l(wèi)ine_total求和得到的計算總額declared_total申報總價默認(rèn)等于計算總額可用--total-value覆蓋total_matchesdeclared_total是否與computed_total一致value_mode本次使用的金額模式line/unitwarnings警告列表例如聲明總額與計算總額不一致時給出明確提示items每行的規(guī)范化結(jié)果與line_total「保留獨立行、同時維持請求的申報總額」正是通過--total-value實現(xiàn)的例如兩份獨立內(nèi)容合計 17000 日元就可以用--total-value 17000讓聲明總價與請求一致若與逐行求和不同plan會輸出declared total 17000 does not match computed item total ...的警告且total_matches為false對應(yīng)測試 test_plan_warns_declared_total_mismatch。line與unit兩種模式的差異也有測試背書line模式下 8000×2 行加 9000×1 行的合計為 17000且首行l(wèi)ine_total為 8000unit模式下 4000×2 與 9000×1 同樣得到 17000見 test_plan_line_value_mode。七、選擇器診斷把「頁面狀態(tài)」變成可檢查的事實Web 頁面隨時可能改版技能為此內(nèi)置了選擇器自檢能力cli-anything-web-yu-pri --json selectors cli-anything-web-yu-pri snapshot --url https://mgr.post.japanpost.jp/M060800.do -o page.png --html-output page.htmlselectors輸出login_url、contents_url、selectors映射表與add_item_command實現(xiàn)見 selector_report。snapshot則截取整頁 PNG并可選保存page.content()的 HTML dump便于 Agent 離線檢查真實 DOM見 capture_snapshot。已知內(nèi)容表單控件技能文檔與 SELECTORS 常量 一致控件語義CSS 選擇器品目描述#M060800_itemBean_pkg品目金額#M060800_itemBean_cost_value品目數(shù)量#M060800_itemBean_num_value原產(chǎn)國#M060800_itemBean_couCdHS code#M060800_itemBean_hsCode包裝類型#M060800_shippingBean_pkgType申報總價#M060800_shippingBean_pkgTotalPrice_value危險品標(biāo)志#M060800_ShippingBean_danger添加品目命令submitCommand(itemAdd2)status命令返回的 inspect_page 結(jié)果包含url、title與逐選擇器的selectors存在性布爾映射并聚合出has_contents_form字段——它要求item_description、item_value、item_quantity、total_value四個關(guān)鍵選擇器同時存在才為真。Agent 可據(jù)此在真實填寫前判斷當(dāng)前頁面是否為可操作的內(nèi)容表單。八、contents fill 的源碼級填報流程與驗證機制contents fill是技能的核心命令。其真實流程在 fill_contents 中可完整追蹤調(diào)用build_contents_plan計算總額并校驗輸入打開內(nèi)容表單 URL并用wait_for_selector15 秒超時確認(rèn)#M060800_itemBean_pkg存在失敗時報出頁面事實URL、標(biāo)題、期望選擇器而非空泛報錯若指定了--package-type寫入#M060800_shippingBean_pkgType若指定了--danger設(shè)置#M060800_ShippingBean_danger復(fù)選框/單選框逐行_fill_item依次填 description、value、quantity再按需填 country 與 hs_code通過頁面 JS 調(diào)用window.submitCommand(itemAdd2)添加該行見 _run_submit_command_wait_after_submit等待domcontentloaded并用_body_fingerprint頁面 URL 正文長度 前 200 個表單控件的 id/name:value 指紋輪詢確認(rèn)頁面確實發(fā)生了變化避免「點了沒生效」的競態(tài)全部行添加完畢后把declared_total寫入#M060800_shippingBean_pkgTotalPrice_value讀取頁面正文做回讀驗證_verify_descriptions檢查每一條品目描述是否出現(xiàn)在頁面文本中輸出descriptions_found、descriptions_missing與all_found。_set_value見 browser.py對select使用select_option、對普通輸入使用fill若二者都失敗則降級為原生賦值并派發(fā)input/change事件。這個三級策略讓表單操作對多種頁面控件都具備彈性。最終 JSON 輸出結(jié)構(gòu)為status: filled、plan完整填報計劃、added逐行實際提交的記錄、page頁面巡檢結(jié)果、verification描述回讀驗證、safetyfinal_submit_clicked: false與說明文案。Agent 應(yīng)依據(jù)verification.all_found判斷填報是否成功。--dry-run則完全不啟動瀏覽器browser_launched: false只輸出plan、selectors、add_item_command與安全元數(shù)據(jù)見 build_dry_run這正是技能安全規(guī)則要求的「觸網(wǎng)前必做」的一步。九、測試策略離線可測與真實環(huán)境隔離倉庫把「不依賴真實日本郵政賬號」的測試與「真實環(huán)境」測試嚴(yán)格分層詳見 TEST.mdtest_core.py覆蓋別名解析、非法國家碼拒絕、JSON 對象/數(shù)組載荷加載、CSV 別名、line/unit總額計算、總額不匹配警告、選擇器報告、dry-run 安全元數(shù)據(jù)以及 CLI 層的--help、plan --json、contents fill --dry-run --json、缺失文件的 JSON 錯誤輸出等 15 項瀏覽器相關(guān)邏輯通過 mock 隔離全程不啟動瀏覽器。test_full_e2e.pytest_dry_run_cli_workflow以子進程方式端到端驗證「寫 items.json → dry-run → 檢查 JSON 結(jié)構(gòu)、總額 17000、safety 與選擇器映射」test_live_status_against_contents_page則被WEB_YU_PRI_LIVE_E2E1環(huán)境變量門控——真實登錄與表單變更默認(rèn)不進入 CI。按文檔記錄的測試結(jié)果python -m pytest cli_anything/web_yu_pri/tests -v共收集 17 項16 通過、1 跳過跳過的正是 live 測試。這種設(shè)計讓核心邏輯可以在任何環(huán)境回歸而真實站點操作始終由人工把關(guān)。十、Agent 推薦工作流從檢查到安全填報綜合以上能力一個完整的 Agent 工作流如下# 1. 環(huán)境體檢 cli-anything-web-yu-pri --json doctor # 2. 人工登錄持久化 Profile憑據(jù)不進 CLI cli-anything-web-yu-pri open-login # 3. 巡檢內(nèi)容表單是否可用 cli-anything-web-yu-pri --json status --url https://mgr.post.japanpost.jp/M060800.do # 4. 離線規(guī)劃校驗 items 文件并核對總額 cli-anything-web-yu-pri --json plan items.json # 5. 干跑確認(rèn)選擇器、計劃與安全元數(shù)據(jù)不啟動瀏覽器 cli-anything-web-yu-pri --json contents fill items.json --dry-run # 6. 真實填寫只到內(nèi)容行 申報總價不點最終提交 cli-anything-web-yu-pri --json contents fill items.json --total-value 17000最后一步返回的verification與safety字段是 Agent 判斷「已填寫但未提交」的權(quán)威證據(jù)verification.all_found說明品目行全部上屏safety.final_submit_clicked: false說明最終出貨確認(rèn)仍留給人工完成。更多實現(xiàn)細(xì)節(jié)可繼續(xù)閱讀 WEB_YU_PRI.md、core/browser.py 與 core/items.py?！久赓M下載鏈接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/項目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考