Web Yu-pri CLI Harness 实战指南用 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-harness/WEB_YU_PRI.md这份标准作业流程SOP文档展开讲解如何将日本邮政Japan Post的 Web Yu-pri 网页寄件系统改造为 Agent 友好的命令行工具CLI 通过 Playwright 驱动真实浏览器 UI而非重写日本邮政业务逻辑自动化重复性品目数据录入同时严格规避风险操作。读完本文你将掌握该 harness 的架构设计、安全模型、全部命令用法、物品清单文件格式、已知选择器映射以及测试策略并能够基于仓库源码理解其底层实现原理。一、设计背景为什么用浏览器驱动而非接口对接Web Yu-pri 是日本邮政面向法人用户的在线寄件系统需要登录后使用。从 WEB_YU_PRI.md 的 Purpose 一节可以看到本 harness 的核心思路是不重新实现日本邮政的业务逻辑而是通过 Playwright 驱动真实浏览器 UI 完成操作。这一设计有三层含义登录态复用Web Yu-pri 是登录后才能使用的 Web 应用CLI 采用持久化浏览器 Profilepersistent user profile用户只需在浏览器里手动登录一次后续命令即可复用登录态零凭据设计CLI 从不接收、也不存储账号密码凭据始终留在用户自己的浏览器 Profile 中从源头规避了密码落盘与泄露风险单点职责CLI 只负责替 Agent 在真实页面上做重复性录入不对日本邮政的服务端行为做任何假设。从 browser.py 源码可以确认两个关键端点LOGIN_URL https://mgr.post.japanpost.jp/C30P01Action.do CONTENTS_URL https://mgr.post.japanpost.jp/M060800.do登录/起始 URLC30P01Action.do用于open-login打开登录页人工登录后进入业务系统品目内容表单 URLM060800.do用于contents fill填写报关品目。浏览器引擎方面browser.py 使用 Playwright 的chromium.launch_persistent_context启动持久化上下文并携带--disable-blink-featuresAutomationControlled参数降低自动化特征浏览器通道channel按msedge → chrome → 内置 chromium的顺序依次尝试因此在安装了 Microsoft Edge 或 Chrome 的环境中可以直接复用系统浏览器。二、安全模型只填不提交这是本 harness 最重要的设计约束原文 Safety Model 一节明确说明第一版只自动化重复性数据录入。具体能力边界如下能力说明✅ 可自动化品目描述contents、申报价值合计declared value totals、可选包裹类型package type、危险品标记dangerous-goods flag✅ 可自动化逐行添加品目submitCommand(itemAdd2)❌ 不可自动化最终寄件确认/提交按钮final shipment confirmation/submit button——CLI 不会点击对应的安全流程是操作真实页面之前必须先用--dry-run校验清单并预览填充计划真实填充live fill完成后检查 JSON 输出中的verification字段确认页面是否真的出现了预期内容最后一步提交寄件永远留给人类用户在浏览器中手动完成。源码层面这一承诺被固化在多个位置。首先是 browser.py 中fill_contents返回的safety对象safety: { final_submit_clicked: False, message: Contents were filled only; final shipment confirmation is not clicked., }其次是 build_dry_run 的干跑输出同样带final_submit_clicked: False。与之配套SKILL.md 中的 Safety Rules 也把不得将日本邮政凭据写入命令、文件、日志或提示词先用--dry-run再真实填写不点击最终寄件确认/购买按钮列为 Agent 必须遵守的硬性规则。三、命令总览与全局选项CLI 入口为cli-anything-web-yu-pri由 web_yu_pri_cli.py 基于 Click 实现。原文 Commands 一节列出了 7 个命令命令作用doctor检查 Playwright 可用性与 Profile 路径selectors打印已知的选择器映射用于页面诊断plan items-file校验 JSON/CSV/TSV 物品文件并计算合计open-login在持久化 Profile 中打开 Web Yu-pri 起始 URLstatus打开 URL 并报告当前标题、URL 与选择器存在情况snapshot截图可选附带 HTML 转储contents fill items-file在品目内容表单上逐行填充3.1 全局选项Agent 友好的 JSON 输出所有命令都支持两个全局选项定义于 web_yu_pri_cli.py--json输出机器可读的 JSON便于 Agent 解析--profile-dir指定持久化浏览器 Profile 目录默认~/.cli-anything-web-yu-pri/profile见 browser.py。此外还内置--version。当命令执行失败且启用了--json时fail() 会输出形如{error: ..., type: FileNotFoundError}的结构化错误对象而不是打印人类友好的报错文本这同样是为 Agent 解析设计的。3.2 安装与快速开始安装方式在 README.md 中有完整说明pip install githttps://github.com/HKUDS/CLI-Anything.git#subdirectoryweb-yu-pri/agent-harness如果 Playwright 找不到浏览器可安装 Microsoft Edge 或 Chrome或运行python -m playwright install chromium依赖声明位于 setup.pyclick8.1,9.0与playwright1.45,2.0Python 版本要求3.10控制台入口映射到web_yu_pri_cli:main。一次典型的完整工作流来自 README.md 的 Quick Startcli-anything-web-yu-pri doctor cli-anything-web-yu-pri open-login cli-anything-web-yu-pri plan items.json --json cli-anything-web-yu-pri contents fill items.json --dry-run --json cli-anything-web-yu-pri contents fill items.json --json其中open-login在人工输出模式下会保持浏览器打开并等待回车--wait而在--json模式下默认不等待该逻辑见 web_yu_pri_cli.py。3.3 REPL 交互模式除子命令外还内置了一个repl命令web_yu_pri_cli.py进入web-yu-pri提示符后可直接输入doctor、selectors、plan items.json、contents fill items.json --dry-run等命令适合人工调试。四、物品清单输入模型JSON / CSV / TSV 与字段别名plan与contents fill都接受物品清单文件支持 JSON、CSV、TSV 三种格式文件扩展名决定解析方式见 items.py。每行ItemLine包含五个字段description品目描述、value价值、quantity数量、country原产国两位 ISO 码、hs_codeHS 编码。原文 Input Model 一节给出了完整的字段别名表源码中定义于 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字段解析采用按别名顺序取第一个非空值的策略_pickitems.py因此即使表头混杂了业务方的不同命名习惯也能正确归一化。例如测试用例 test_core.py 中pkg/cost/num/couCd/hsCode这组别名会被正确解析为Award plaque/8000/2/KR/4901.99。4.1 JSON 与 CSV/TSV 示例JSON来自 README.md{ items: [ {description: Award plaque, value: 8000, quantity: 1, country: KR}, {description: Certificate, value: 9000, quantity: 1, country: KR} ] }CSVdescription,value,quantity,country,hs_code Award plaque,8000,1,KR, Certificate,9000,1,KR,TSV 与 CSV 的唯一区别是使用\t作为分隔符。JSON 既可以是{items: [...]}对象结构也可以直接是数组items.pyCSV/TSV 必须包含表头行解析时使用csv.DictReader空行会自动跳过。4.2 数据校验规则从 items.py 可以看到内置的严格校验value必须是整数支持8,000、8000円、JPY8000等带千分位分隔符与货币符号的写法字符会被剥离且 0布尔值会被拒绝quantity必须是整数且 1默认值为 1country必须为两位大写字母 ISO 码如KR、US小写输入会自动转大写KOR这类三位码会被拒绝见测试 test_core.pyhs_code仅允许字母、数字、点与连字符长度 2–20内部空白会被移除description不能为空。4.3 value-mode行价值还是单价默认情况下value被当作单行申报价值line value合计直接求和。当value是单价时应使用--value-mode unit此时行小计 value × quantity。该逻辑由 ItemLine.line_total 实现并由plan与contents fill共用的--value-mode选项可选值为line/unit默认line控制。测试 test_core.py 验证了两种模式line 模式下8000×2 9000×1的合计为 17000第一行按 8000 计unit 模式下4000×2 9000×1的合计同样为 17000第一行按 8000 计。plan输出的关键字段build_contents_planitems.py包括item_count品目行数computed_total按清单计算出的合计declared_total实际申报的合计可由--total-value覆盖total_matches两者是否一致warnings当declared_total ! computed_total时给出明确警告items每行的归一化结果与line_total。五、已知 Web Yu-pri 选择器映射原文 Known Web Yu-pri Selectors 一节给出了品目内容表单M060800.do的全部关键控件。源码中这些选择器定义于 browser.py控件CSS 选择器品目描述#M060800_itemBean_pkg品目价值#M060800_itemBean_cost_value品目数量#M060800_itemBean_num_value原产国#M060800_itemBean_couCdHS 编码#M060800_itemBean_hsCode包裹类型#M060800_shippingBean_pkgType申报价值合计#M060800_shippingBean_pkgTotalPrice_value危险品标记#M060800_ShippingBean_danger添加品目命令submitCommand(itemAdd2)运行cli-anything-web-yu-pri selectors --json即可随时打印这份映射便于 Agent 在页面结构变化时快速诊断。selectors输出中还包括登录 URL、内容表单 URL 与添加品目命令名见 selector_report。配合status命令的has_contents_form字段要求品目描述、价值、数量、合计四个核心选择器同时存在才算内容表单已加载见 inspect_pageAgent 可以在填充前确认自己确实停留在正确的页面上。六、contents fill的底层执行流程contents fill是唯一会写真实页面的命令其完整流程由 fill_contents 实现构建计划调用build_contents_plan计算申报合计产生确定性的填充计划打开表单跳转到M060800.do并通过_require_selector等待品目描述选择器出现超时 15 秒若表单未找到会抛出带页面事实URL、标题、期望选择器的结构化错误便于诊断browser.py可选设置包裹类型与危险品标记--package-type设置下拉/输入值--danger/--no-danger设置危险品勾选逐行填充并添加品目每行先填描述、价值、数量以及可选的原产国、HS 编码然后通过页面全局函数window.submitCommand(itemAdd2)触发添加_run_submit_commandbrowser.py添加后以页面 body 指纹变化 最多 10 秒轮询的方式等待表单刷新完成_wait_after_submit写入申报价值合计将计划中的declared_total填入合计输入框返回验证结果读取页面 body 文本逐一检查各品目描述是否真的出现产出verification对象。填充时对输入框/下拉框的处理也相当健壮_set_valuebrowser.py会先判断标签类型select用select_option普通输入用fill若常规赋值失败则回退到 JS 直接写值并派发input/change事件以适配框架绑定型页面。fill_contents的最终 JSON 输出包含五个部分{ status: filled, plan: {...}, added: [...], page: {url: ..., title: ..., has_contents_form: true, selectors: {...}}, verification: {descriptions_found: [...], descriptions_missing: [], all_found: true}, safety: {final_submit_clicked: false, message: ...} }Agent 应重点检查verification.all_found与safety.final_submit_clicked这两个字段前者确认填充生效、后者确认未触发任何提交动作。七、测试策略无浏览器单测 门控 E2E原文 Test Strategy 一节明确了测试分层仓库中对应两个测试文件单元测试test_core.py——不启动浏览器覆盖字段别名解析test_parse_item_mapping_aliases非法国家码拒绝test_parse_item_rejects_bad_countryJSON 对象/数组载荷与 CSV 别名加载test_load_json_object_payload、test_load_csv_aliasesline/unit 两种价值模式的合计计算test_plan_line_value_mode、test_plan_unit_value_mode申报合计不匹配时的警告test_plan_warns_declared_total_mismatch选择器报告与 dry-run 安全元数据test_selector_report_contains_contents_controls、test_build_dry_run_has_safety_metadata通过 Click 的CliRunner验证 CLI 的--help、plan --json、contents fill --dry-run --json输出以及缺失文件时的结构化 JSON 错误type: FileNotFoundError。E2E 测试test_full_e2e.pytest_dry_run_cli_workflow以子进程方式真实运行 CLI 的 dry-run 完整流程断言输出中的dry_run: true、computed_total: 17000、final_submit_clicked: false及选择器键存在——这是不依赖账号的端到端验证test_live_status_against_contents_page通过环境变量WEB_YU_PRI_LIVE_E2E1门控的可选线上测试需要真实日本邮政账号与已登录的浏览器 Profile实际对M060800.do执行status并断言返回 URL 与标题。八、Agent 落地工作流与注意事项综合原文档与仓库内容建议 Agent 按以下顺序使用本 harness环境检查cli-anything-web-yu-pri doctor确认 Playwright 可用、Profile 路径正确人工登录cli-anything-web-yu-pri open-login让用户在持久化浏览器 Profile 中完成一次登录CLI 不接触凭据页面确认cli-anything-web-yu-pri --json status --url https://mgr.post.japanpost.jp/M060800.do确认内容表单已加载has_contents_form: true规划与干跑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核对输出中的verification与safety字段人工收尾最终寄件确认由用户在浏览器中手动完成CLI 永不越界。需要特别注意的是若清单中的行价值合计与期望申报值不一致可用--total-value覆盖申报合计此时plan会输出警告当源数据是按奖项/类别分行、同时需要保持指定申报总额时应保留分行结构而不是合并行见 SKILL.md 的 Safety Rules。另外选择器与页面 URL 属于对 Web Yu-pri 站点的已知映射若日本邮政改版页面结构应重新通过selectors、status与snapshot诊断后再继续使用。九、仓库结构速览与本 harness 相关的全部资源均位于仓库web-yu-pri/目录下WEB_YU_PRI.md本文依据的 SOP 文档README.md安装与快速开始web_yu_pri_cli.pyCLI 入口与全部命令定义core/browser.pyPlaywright 后端、URL 常量、选择器映射与填充逻辑core/items.py输入归一化、校验与合计计算tests/test_core.py 与 tests/test_full_e2e.py单元与 E2E 测试skills/SKILL.md面向 Agent 的 Skill 定义setup.py打包与依赖声明。整个模块同样可以在 skills/cli-anything-web-yu-pri/SKILL.md 中找到 Skill 形态的副本便于直接接入支持 Skill 的 Agent 环境。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考