@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/wenyao_skill_contract.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""从填报映射真源生成技能里的「列契约」参考文档（避免手写漂移）。
+
+用法：
+  python3 scripts/wenyao_skill_contract.py            # 写到 skills/ml-invoice/references/template-fill-contract.md
+  python3 scripts/wenyao_skill_contract.py --stdout   # 打到标准输出
+  python3 scripts/wenyao_skill_contract.py --check     # 只校验磁盘文件与真源一致（CI/单测用），不一致 exit 1
+
+真源：scripts/wenyao-template-map.json
+目标：skills/ml-invoice/references/template-fill-contract.md
+"""
+import json
+import pathlib
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+MAP_PATH = ROOT / 'scripts' / 'wenyao-template-map.json'
+sys.path.insert(0, str(ROOT / 'scripts'))
+import ml_store_ids  # noqa: E402  （店铺→卖家ID 的唯一真源）
+OUT_PATH = ROOT / 'skills' / 'ml-invoice' / 'references' / 'template-fill-contract.md'
+
+SRC_CN = {
+    'field': '飞书字段',
+    'calc': '计算',
+    'const': '常量',
+    'llm': 'LLM 翻译',
+    'image': '图片',
+    'storemap': '店铺映射',
+}
+
+
+def detail_of(c: dict) -> str:
+    src = c['source']
+    if src == 'field':
+        return f"飞书 `{c['field']}`"
+    if src == 'calc':
+        return f"`{c['expr']}`"
+    if src == 'llm':
+        return f"LLM：{c.get('note') or c.get('prompt', '')}"
+    if src == 'storemap':
+        return '店铺 → 卖家ID'
+    if src == 'image':
+        return f"飞书 `{c.get('field', '产品图')}`（浮动图片，锚 `{c.get('anchor', 'AA8')}`）"
+    value = c.get('value', '')
+    shown = '（空）' if value == '' else f'`{value}`'
+    extra = f"（{c['note']}）" if c.get('note') else ''
+    if c.get('perRow'):
+        extra += '｜**随行变化**（影子对比器按 `perRow` 放行，判据在填报器）'
+    return f"{shown}{extra}"
+
+
+def material_section() -> list:
+    """材质英文三级解析 + 与 HS 的分界（2026-10-12 事故固化）。
+
+    ⛔ 这里**不写填报器的脚本路径**（路径写在 `SKILL.md`，避免引擎面文件复述业务词）：
+    真源只有一份判据（填报器的 `resolve_material_en()`），本节只描述**怎么传、怎么回写**。
+    """
+    return [
+        '', '## 材质英文（`S` 列）三级解析 —— 与 HS 的分界', '',
+        '合同：`S` = `{材质}，{材质英文}`。**材质英文走三级解析**（唯一实现 = 填报器的 '
+        '`resolve_material_en()`；脚本路径与入口见 `SKILL.md`「材质英文（`S` 列）三级解析」）：', '',
+        '| 级 | 来源 | 命中后 | 写回字典？ |', '|---|---|---|---|',
+        '| ① | per-SKU 字典 `<数据目录>/lip-sku-dict.json`（键 = `SKU`，**优先 `confirmed:true`** '
+        '的「材质英文」） | 直接用 | ⛔ 不写（答案已固化） |',
+        '| ② | 本映射的 `materialEn` 通用小词典 | 直接用 | ⛔ 不写 |',
+        '| ③ | 会话传入 `--material-en "<英文>"`（或行内 `材质英文`；**政策A：LLM 译出的可直接用**） '
+        '| 用它填 `S` 列 | ✅ 写回 |', '',
+        '写回形状（③ 定音时；落到 `<数据目录>/lip-sku-dict.json`）：', '',
+        '```json',
+        '{"<SKU>": {"材质英文": "<英文>", "confirmed": false,',
+        '           "来源": "LLM 译 <YYYY-MM-DD>（政策A：材质英文可直接用，HS 不动）", "备注": ""}}',
+        '```', '',
+        '- 写回**合并进已有条目**（⛔ 不丢 `品名英文`/`海关编码`）；**原子写**（`tmp` + `os.replace`）；'
+        '同 `SKU` 同值 ⇒ **幂等跳过**（不重写、不动 mtime）；',
+        '- **⛔ 不覆盖 `confirmed:true`**；字典里已有 `confirmed:true` 条目但缺材质英文 ⇒ 只留痕、'
+        '**不写回**（不把已确认条目降级成 `confirmed:false`）；',
+        '- **同名不同值 ⇒ 冲突交人**：保留字典值、**不写回**、阻断重跑（与 `flow_case` 的'
+        '「不覆盖 + 记冲突」同一口径）；',
+        '- 审计：`<数据目录>/material-en/audit.jsonl`；阶段台账：编排器 P0 行打印的 `log=<路径>`'
+        '（`run-<货件号>-<时间>.jsonl`，目录名见 `SKILL.md`）。', '',
+        '**三级都没命中 ⇒ 阻断**（填报器不落盘、闸门 exit ≠ 0），文案指路：', '',
+        '```',
+        '材质「<中文材质>」未能在 SKU 字典 / 小词典命中 ⇒ 请翻译成英文后用 --material-en 重跑',
+        '（政策A：材质英文允许 LLM 译；HS 编码仍必须人工维护）',
+        '```', '',
+        '### ⛔ HS 编码（`Z` 列）不在这条链上', '',
+        'HS 编码由**运营/人工维护**：系统**不预填、不写候选、不自动确认**（红线，勿动）。'
+        '「不预填」那条**只管 HS** —— 把它套到材质英文上，就是 2026-10-12 两条票被误阻的成因。', '',
+        '另有一份**按中文品名**建的翻译缓存 `<数据目录>/lip-product-dict.json`（品名英文/材质英文/'
+        'HS 候选），与本节这份**按 SKU** 的字典是两回事：本填报链只读 `lip-sku-dict.json`'
+        '（HS 候选**不预填**进模板，见上一条红线）。',
+    ]
+
+
+
+def render(m: dict) -> str:
+    L = ['# 填报列契约（由 `scripts/wenyao-template-map.json` 生成，勿手改）', '']
+    L += ['模板真源：**门户下载版**《跨境电商-下单模板.xlsx》（`getTemplateUrl`）。',
+          '运营版《上海文鳐发票模版.xlsx》仅作「每列怎么填」的说明，**列序不可照抄**（门户版多 `*是否投保`）。', '']
+    L.append(f"- sheet: `{m['sheet']}`｜表头行: **{m['headerRow']}**｜数据行: **{m['dataRow']}**｜清底: `{m['clearRowsBelow']}`")
+    L.append(f"- 模板来源标记: `{m['templateSource']}`")
+    L += ['', '## 顶部块（第 2 行）', '', '| 字段 | 单元格 | 取值 | 说明 |', '|---|---|---|---|']
+    for k, v in m['topBlock'].items():
+        val = v.get('value', '')
+        shown = '`__TODAY__`（当前日期）' if val == '__TODAY__' else ('（空）' if val == '' else f'`{val}`')
+        L.append(f"| {k} | `{v['cell']}` | {shown} | {v.get('note', '')} |")
+    L += ['', f"## 明细列（第 8 行，A..{m['columns'][-1]['col']}）", '',
+          '| 列 | 表头 | 来源 | 取值/表达式 |', '|---|---|---|---|']
+    for c in m['columns']:
+        L.append(f"| `{c['col']}` | {c['header']} | {SRC_CN.get(c['source'], c['source'])} | {detail_of(c)} |")
+    L += ['', '## 店铺 → 卖家ID 映射', '',
+          '真源：`scripts/ml-store-ids.json`（键=国家-店号；**主账号/子账号共用同一 ML ID**）。', '',
+          '| 店铺 | 卖家ID |', '|---|---|']
+    for k, v in ml_store_ids.load().items():
+        L.append(f"| {k} | `{v}` |")
+    if ml_store_ids.UNKNOWN_HINT:
+        L += ['', '未配置（解析将**响亮失败**、不会顶替）：' + '、'.join(ml_store_ids.UNKNOWN_HINT)]
+    if m.get('materialEn'):
+        L += ['', '## 材质中英对照', '', '| 中文 | 英文 |', '|---|---|']
+        for k, v in m['materialEn'].items():
+            L.append(f"| {k} | {v} |")
+    L += material_section()
+    if m.get('knownDivergence'):
+        L += ['', '## 已知与运营版的差异', '']
+        for d in m['knownDivergence']:
+            L.append(f'- {d}')
+    L += ['', '## 硬约束', '',
+          '- **只写第 2、8 行**；第 5-6 行是门户自带示例（门户要求不删）⇒ 不动；表头/声明/校验/冻结窗格一律不动。',
+          '- **写值前先清空 `A2..H2`**（门户版预填 `CNYTN/USLGB/东莞集货仓/墨西哥` 不得沿用）。',
+          '- **港前仓 = `华南仓`**（覆盖模板自带的 `东莞集货仓`），G2 单元格校验**保留不动**。',
+          '- 方数用**精确值**，不做 Excel 式四舍五入。',
+          '- 产品图为**浮动图片**，需 Pillow。', '']
+    return '\n'.join(L)
+
+
+def main() -> int:
+    m = json.loads(MAP_PATH.read_text())
+    text = render(m)
+    if '--stdout' in sys.argv:
+        sys.stdout.write(text)
+        return 0
+    if '--check' in sys.argv:
+        cur = OUT_PATH.read_text() if OUT_PATH.exists() else ''
+        if cur != text:
+            print(f'❌ {OUT_PATH.relative_to(ROOT)} 与真源不一致，请跑 python3 scripts/wenyao_skill_contract.py')
+            return 1
+        print(f'✅ 技能列契约与真源一致（{len(text.splitlines())} 行）')
+        return 0
+    OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    OUT_PATH.write_text(text)
+    print(f'已写入 {OUT_PATH.relative_to(ROOT)}（{len(text.splitlines())} 行）')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/engine/scripts/wenyao_template_fetch.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""wenyao_template_fetch.py — 取文鳐门户的「导入模版」(跨境电商-下单模板.xlsx) 并解析结构（2026-09-10）
+
+为什么不用普通下载：本门户的模板下载是 **JS fetch → blob → 合成点击**，而本浏览器是 `open -na`
+启动（非 Playwright 启动）⇒ Playwright 收不到 download 事件；即便用 CDP 设下载目录也不稳。
+**最稳做法**：在页面里钩住 `URL.createObjectURL`，点完之后把 blob 以 base64 取回 Python 落盘
+（完全绕开下载管线）。再兜底：CDP 网络捕获 + 目录轮询。
+
+安全边界：只取**模板**；不选文件、不点「导入」、不点导出/取消订单；完事关闭弹窗。
+
+用法：python3 scripts/wenyao_template_fetch.py [--out-dir DIR]
+"""
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from playwright.sync_api import sync_playwright
+
+HOME = Path.home()
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  —— 勿在此复制判据
+DATA = Path(resolve_data_dir()['dir'])
+DEFAULT_OUT = DATA / "wenyao-downloads"
+CDP = os.environ.get("WENYAO_CDP", "http://127.0.0.1:9333")
+
+BLOB_HOOK = """() => {
+  if (window.__blobHook) return 'already';
+  const orig = URL.createObjectURL;
+  URL.createObjectURL = function (b) { try { window.__lastBlob = b; } catch (e) {} return orig.call(URL, b); };
+  window.__blobHook = true;
+  return 'hooked';
+}"""
+
+READ_BLOB = """async () => {
+  const b = window.__lastBlob;
+  if (!b) return null;
+  const buf = await b.arrayBuffer();
+  const bytes = new Uint8Array(buf);
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return { b64: btoa(s), size: bytes.length, type: b.type || '' };
+}"""
+
+
+def summarize_xlsx(path):
+    try:
+        import openpyxl
+    except Exception as e:
+        return {"err": f"openpyxl 不可用: {e}"}
+    try:
+        wb = openpyxl.load_workbook(path, data_only=True, read_only=True)
+        out = {"sheets": wb.sheetnames, "detail": {}}
+        for ws in wb.worksheets:
+            rows = []
+            for i, r in enumerate(ws.iter_rows(values_only=True)):
+                if i > 3:
+                    break
+                rows.append([str(c)[:22] if c is not None else "" for c in r][:16])
+            out["detail"][ws.title] = {"dims": f"{ws.max_row}x{ws.max_column}", "head": rows}
+        return out
+    except Exception as e:
+        return {"err": str(e)[:200]}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out-dir", default=str(DEFAULT_OUT))
+    a = ap.parse_args()
+    out_dir = Path(a.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    os.chmod(out_dir, 0o700)
+    res = {}
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(CDP, timeout=8000)
+        pages = [pg for c in browser.contexts for pg in c.pages]
+        page = next((pg for pg in pages if "ffl-tech" in (pg.url or "")), pages[0])
+        try:
+            page.keyboard.press("Escape"); page.wait_for_timeout(500)
+        except Exception:
+            pass
+        # 网络捕获（兜底：若模板是服务端直链而非 blob）
+        net = []
+        try:
+            sess = page.context.new_cdp_session(page)
+            sess.send("Browser.setDownloadBehavior", {"behavior": "allow", "downloadPath": str(out_dir)})
+            sess.send("Network.enable")
+            sess.on("Network.responseReceived", lambda e: net.append({
+                "url": (e.get("response") or {}).get("url", "")[:200],
+                "mime": (e.get("response") or {}).get("mimeType", ""),
+                "cd": [h for h in (((e.get("response") or {}).get("headers") or {}).items()
+                                   if isinstance(((e.get("response") or {}).get("headers")), dict) else [])
+                       if h[0].lower() == "content-disposition"][:1]
+            }) if any(k in ((e.get("response") or {}).get("url", "")).lower() for k in ("template", "xlsx", "excel", "download", "moban", "模板")) else None)
+        except Exception as e:
+            res["cdp_err"] = str(e)[:120]
+        # 打开弹窗
+        opened = False
+        for sel in ["button:has-text('导入订单')", "text=导入订单"]:
+            try:
+                el = page.query_selector(sel)
+                if el and el.is_visible():
+                    el.click(); opened = True; break
+            except Exception:
+                continue
+        page.wait_for_timeout(2500)
+        res["dialog_opened"] = opened
+        res["hook"] = page.evaluate(BLOB_HOOK)
+        # 点真正的 xlsx 链接
+        clicked = None
+        for sel in ["button:has-text('跨境电商-下单模板.xlsx')", "text=跨境电商-下单模板.xlsx", "text=下载导入模版"]:
+            try:
+                el = page.query_selector(sel)
+                if el and el.is_visible():
+                    el.click(); clicked = sel; break
+            except Exception:
+                continue
+        res["clicked"] = clicked
+        # 取 blob
+        got = None
+        for _ in range(20):
+            page.wait_for_timeout(1000)
+            got = page.evaluate(READ_BLOB)
+            if got and got.get("b64"):
+                break
+        saved = None
+        if got and got.get("b64"):
+            name = "跨境电商-下单模板.xlsx"
+            dest = out_dir / name
+            dest.write_bytes(base64.b64decode(got["b64"]))
+            os.chmod(dest, 0o600)
+            saved = dest
+            res["via"] = "blob-hook"
+            res["blob_type"] = got.get("type")
+        else:
+            # 兜底：目录轮询
+            for _ in range(15):
+                page.wait_for_timeout(1000)
+                files = [f for f in out_dir.iterdir() if f.is_file() and not f.name.endswith(".crdownload")]
+                if files:
+                    saved = max(files, key=lambda f: f.stat().st_mtime)
+                    res["via"] = "dir-poll"
+                    break
+        if saved:
+            res["saved"] = {"path": str(saved), "bytes": saved.stat().st_size, "name": saved.name}
+            if saved.suffix.lower() in (".xlsx", ".xls", ".xlsm"):
+                res["structure"] = summarize_xlsx(saved)
+        if net:
+            res["network_hits"] = net[:5]
+        # 关闭弹窗（只关不提交）
+        closed = False
+        for sel in ["button:has-text('取消')", ".next-dialog-close", "text=取消"]:
+            try:
+                el = page.query_selector(sel)
+                if el and el.is_visible():
+                    el.click(); closed = True; break
+            except Exception:
+                continue
+        if not closed:
+            try: page.keyboard.press("Escape")
+            except Exception: pass
+        res["dialog_closed"] = closed
+        try:
+            page.screenshot(path=str(DATA / "wenyao-probe" / "64-template-fetch.png"), full_page=True)
+        except Exception:
+            pass
+        print(json.dumps(res, ensure_ascii=False, indent=1))
+    return 0 if (res.get("saved")) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())