ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

CLI-Anything Web Yu-pri:用命令行驱动日本邮政国际邮件内容申报表单的实战指南

CLI-Anything Web Yu-pri:用命令行驱动日本邮政国际邮件内容申报表单的实战指南 CLI-Anything Web Yu-pri用命令行驱动日本邮政国际邮件内容申报表单的实战指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文介绍 CLI-Anything 生态中专门面向日本邮政 Web Yu-pri 的 Agent 化 CLI 工具cli-anything-web-yu-pri。Web Yu-pri 是日本邮政的登录制网页应用本工具不重写其业务逻辑而是通过 Playwright 驱动真实浏览器完成登录、页面巡检、截图、dry-run 规划与内容申报表单Contents Form填写。读完本文你将掌握该 CLI 的安装方式、安全使用模型、JSON/CSV/TSV 申报数据的输入规范、全部常用命令以及如何基于已知选择器完成可审计的表单自动化填充。一、工具定位Agent 化的 Web Yu-pri 工作流Web Yu-pri网址https://mgr.post.japanpost.jp/C30P01Action.do是登录后才能使用的网络申报应用重复录入内容品名、申报价值、数量、原产国、HS 编码等明细行非常耗时。该 harness 的核心思路在 web-yu-pri/agent-harness/WEB_YU_PRI.md 中有明确表述该 harness 将日本邮政 Web Yu-pri 的浏览器工作流转成 Agent 友好的 CLI。由于是登录制 Web 应用CLI 通过 Playwright 驱动真实浏览器 UI而非重新实现日本邮政的业务逻辑。由此形成三个关键设计前提真实浏览器驱动底层使用 Playwright Chromium 的持久化用户配置目录persistent profile登录态保存在本地。不碰凭据CLI 从不接收、不存储日本邮政账号密码登录由用户手动在浏览器 profile 中完成。不点最终确认自动化只覆盖重复的数据录入明细行、申报总值、可选包装类型、危险品标志绝不点击最终出货确认/提交按钮。从源码结构看模块划分为三个核心文件浏览器后端Playwright 封装与选择器映射、输入模型JSON/CSV/TSV 解析与申报计划计算、CLI 入口基于 Click 的命令分发。二、安装与环境准备2.1 安装 CLI从仓库子目录安装对应 setup.py 中定义的包名cli-anything-web-yu-pripip install githttps://github.com/HKUDS/CLI-Anything.git#subdirectoryweb-yu-pri/agent-harness根据 setup.py 的声明运行依赖为click8.1,9.0与playwright1.45,2.0要求 Python 3.10安装后自动注册cli-anything-web-yu-pri控制台命令。2.2 浏览器内核准备若本机没有可用的 Chromium/Edge/Chrome执行python -m playwright install chromium从 browser.py 的启动逻辑可以看到browser_session()会依次尝试msedge、chrome、内置 Chromium 三种通道任一可启动即复用该通道并以--disable-blink-featuresAutomationControlled参数启动尽量降低被页面识别为自动化的概率。2.3 验证运行环境cli-anything-web-yu-pri --json doctordoctor返回 JSON包含持久化 profile 目录、登录页与申报页 URL以及playwright_available布尔值其实现见 browser.py。profile 默认位于~/.cli-anything-web-yu-pri/profile可用全局参数--profile-dir覆盖。三、安全使用模型务必先读Skill 文档中的 Safety Rules 是整个工具的行为红线逐条对应到源码实现安全规则源码佐证不得在命令、文件、日志、提示词中放入日本邮政凭据CLI 入口 docstring 明确 never store account passwordsopen-login只负责打开登录页使用open-login让用户手动登录持久化 profile见 web_yu_pri_cli.py真实填写前先跑contents fill ... --dry-run --json--dry-run直接调用build_dry_run()不启动浏览器见 browser.py不点击最终出货确认或购买按钮fill_contents()返回值中带safety: {final_submit_clicked: False}见 browser.py源数据中奖项/品类分行时保持明细行分离同时保留申报总额由plan与--total-value机制支撑见下文第五节特别强调contents fill的行为边界在命令 help 中写得很清楚——仅填写内容与申报总额不会点击最终出货确认/提交按钮web_yu_pri_cli.py。因此真实出货仍由人工在浏览器中完成最终确认。四、常用命令速查# 1. 环境体检 cli-anything-web-yu-pri --json doctor # 2. 在持久化 profile 中手动打开登录页 cli-anything-web-yu-pri open-login # 3. 巡检申报页报告标题、URL、关键选择器是否出现 cli-anything-web-yu-pri --json status --url https://mgr.post.japanpost.jp/M060800.do # 4. 校验申报文件并打印填充计划含总额计算 cli-anything-web-yu-pri --json plan items.json # 5. 真实填写前的 dry-run不启动浏览器 cli-anything-web-yu-pri --json contents fill items.json --dry-run # 6. 真实填写并用 --total-value 覆盖申报总额 cli-anything-web-yu-pri --json contents fill items.json --total-value 17000全部子命令一览与 README.md 一致命令作用doctor检查本地运行时与 profile 路径selectors打印已知的 Web Yu-pri 选择器映射plan items-file校验 JSON/CSV/TSV 申报文件并计算总额open-login在持久化 profile 中打开登录/起始 URLstatus打开 URL 并报告标题、当前 URL、选择器存在性snapshot -o page.png截图可选附带 HTML dumpcontents fill items-file填写申报明细行与申报总值repl启动一个交互式 REPL可逐条输入上述子命令4.1 全局参数--json输出机器可读 JSONAgent 安全输出模式错误时同样输出{error: ..., type: ...}结构--profile-dir指定持久化浏览器 profile 目录--version打印版本当前为 0.1.0见init.py。五、申报数据文件Items File规范5.1 JSON 示例{ items: [ {description: Award plaque, value: 8000, quantity: 1, country: KR}, {description: Certificate, value: 9000, quantity: 1, country: KR} ] }JSON 顶层可以是对象必须含items数组也可以是裸数组。从 items.py 可以看到对象载荷缺items键或载荷不是数组时都会直接报错。5.2 CSV/TSV 列名别名CSV 必须包含表头行_load_delimited中fieldnames为空会抛错。列名支持以下别名对应 items.py 的键元组descriptiondescription、desc、content、contents、item、name、pkgvaluevalue、declared_value、cost、price、amount、yen、jpyquantityquantity、qty、num、countcountrycountry、country_code、country_of_origin、origin、couCd、cou_cdHS codehs_code、hs、hscode、hsCode例如以下 CSV 与上方 JSON 等价pkg,cost,num,couCd,hsCode Award plaque,8000,1,KR, Certificate,9000,1,KR,CSV 用逗号分隔TSV 用制表符分隔按文件扩展名.csv/.tsv自动判定。5.3 值解析的容错规则从 items.py 的实现可以归纳出输入校验行为value必须是非负整数支持字符串中的逗号、空格以及JPY、jpy、¥、円等标记会被自动剥离例如8,000解析为 8000quantity必须为 1 的整数缺省视为 1country必须是两位 ISO 字母代码自动转大写如KR、USKOR这类三位码会直接校验失败测试test_parse_item_rejects_bad_country覆盖了该场景hs_code允许字母、数字、点、连字符长度 2~20空格会被剔除description不能为空。5.4--value-mode行总值与单价模式默认value按该行申报总值line处理当数据中的 value 是单价时使用--value-mode unit此时该行总额 value × quantity。两种模式的计算实现见 items.py配套的单测test_plan_line_value_mode/test_plan_unit_value_mode分别验证了两种模式下总额为 17000 的等价结果。5.5 申报总额与告警plan会计算computed_total所有行总额之和并在命令行提供--total-value覆盖申报总值declared_total。若两者不一致输出中会带warnings数组并置total_matches: false见 items.py。这正是 Skill 中保持明细行分离、同时保留申报总额的实现机制例如奖项与证书两行分别申报但用--total-value 17000将合计写为申报总值。六、选择器诊断与页面巡检6.1 打印已知选择器cli-anything-web-yu-pri --json selectors输出包含登录页 URL、申报页 URL、全部已知选择器映射与新增明细命令itemAdd2定义于 browser.py。6.2 申报页已知控件M060800.do含义选择器品名Item description#M060800_itemBean_pkg申报价值Item value#M060800_itemBean_cost_value数量Item quantity#M060800_itemBean_num_value原产国Country of origin#M060800_itemBean_couCdHS 编码#M060800_itemBean_hsCode包装类型Package type#M060800_shippingBean_pkgType申报总值Total declared value#M060800_shippingBean_pkgTotalPrice_value危险品标志Dangerous-goods flag#M060800_ShippingBean_danger新增明细命令submitCommand(itemAdd2)6.3 状态巡检与截图cli-anything-web-yu-pri --json status --url https://mgr.post.japanpost.jp/M060800.do cli-anything-web-yu-pri snapshot --url https://mgr.post.japanpost.jp/M060800.do -o page.png --html-output page.htmlstatus报告页面标题、当前 URL、每个已知选择器的存在性并给出has_contents_form汇总布尔值需品名、价值、数量、总值四个核心选择器同时存在见 browser.py。对 Agent 而言可用它判断当前是否处于可填写的申报表单页。snapshot输出全页截图PNG--html-output可选保存页面 HTML 快照便于离线诊断选择器是否因页面改版而失效。七、真实表单填充contents fill的完整参数与流程7.1 完整参数表cli-anything-web-yu-pri contents fill items-file \ [--url URL] [--country-default ISO] [--total-value YEN] \ [--value-mode line|unit] [--package-type VALUE] \ [--danger|--no-danger] [--dry-run] [--headless] \ [--browser-channel msedge|chrome] [--delay-ms N]参数默认值说明--urlhttps://mgr.post.japanpost.jp/M060800.do申报表单页地址--country-default无未写国家代码的行使用的默认 ISO 国家码--total-value无按行合计覆盖申报总值日元整数--value-modelineline行总值 /unit单价×数量--package-type无可选的包装类型 select 值--danger / --no-danger无设置危险品标志存在该控件时--dry-run关只校验并打印计划不启动浏览器--headless关无头模式运行--browser-channel无指定 Playwright 通道如msedge、chrome--delay-ms500每新增一条明细后的等待毫秒数7.2 执行流程源码视角fill_contents()browser.py的调用链为用同一份build_contents_plan计算计划打开申报页并wait_for_selector(#M060800_itemBean_pkg)15 秒内找不到表单则抛错并附带页面标题/URL 诊断信息若指定了--package-type/--danger先设置包装类型与危险品标志select 用select_optioncheckbox/radio 用set_checked其余控件走fill异常时退化为原生 DOM 赋值 input/change事件派发逐条填充品名、价值、数量、原产国、HS 编码然后通过window.submitCommand(itemAdd2)提交新增明细提交后通过 body 指纹比对轮询等待页面刷新_wait_after_submit结合delay_ms与最多 10 秒等待确保上一条写入完成再写下一条全部明细行写完后将申报总值写入#M060800_shippingBean_pkgTotalPrice_value最后从页面 body 文本中回查每个品名是否出现输出verification.descriptions_found/descriptions_missing/all_found作为填写后的校验证据。7.3 返回结构真实填写后--json输出包含status: filled、plan申报计划、added已新增的每条明细、page页面巡检信息与verification品名回查以及始终为final_submit_clicked: false的safety对象——这是 Agent 判断仅完成录入、未提交出货的关键审计字段。八、测试策略与验证方式8.1 单元与 CLI 冒烟测试test_core.py 覆盖了列名别名解析pkg/cost/num/couCd/hsCode、国家码与金额格式校验、JSON 对象/数组两种载荷、CSV 别名装载、两种 value-mode 的总额计算、申报总额不匹配告警、选择器报告、dry-run 安全元数据以及 CLI 层--json输出与缺文件时的{type: FileNotFoundError}错误结构。8.2 E2E 测试test_full_e2e.py 包含两条用例dry-run 工作流默认执行模拟 Agent 在触碰真实站点前先校验申报文件验证--json contents fill ... --dry-run输出的 JSON 结构、合计 17000、选择器映射与安全元数据live 巡检默认跳过以WEB_YU_PRI_LIVE_E2E1环境变量门控因为实时执行需要真实日本邮政账号与已登录的浏览器 profile仅运行status巡检申报页不做表单变更。按 TEST.md 的记录python -m pytest cli_anything/web_yu_pri/tests -v结果为 16 passed、1 skippedlive 用例。九、Agent 使用范式小结对 LLM/Agent 而言最稳妥的 Web Yu-pri 操作顺序是doctor确认环境与 profile 就绪open-login让人类用户手动登录必要时先snapshot观察登录页状态构造申报 JSON/CSV先plan校验文件并核对computed_total与预期contents fill ... --dry-run --json做浏览器外的最终核对执行真实contents fill ... --json解析verification与safety字段确认已录入但未提交最终出货确认保留给人类用户在浏览器中完成。这一流程把易错的重复录入交给机器、把需负责任的最终确认留给人与 Skill 文档的安全规则完全一致。若页面结构变更导致选择器失效可借助selectors、status与snapshot --html-output快速诊断并更新选择器映射。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表