@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/integration_contract.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""货代集成契约（迭代 2 第一步，2026-09-20）。
+
+## 问题
+"发票"是**能力**（闸门/守卫/状态机/缺口规则，与货代无关），而"某货代怎么开票"是**集成**。
+此前两者揉在一起：货代细节散落在 4 处 —— 注册表 1 条、角色 preset、提示词、
+**每个货代一份 runner 脚本**（401 行 vs 1046 行，互不共享）。⇒ 接第 3 个货代要改 9 处。
+
+## 本模块定义什么
+`scripts/integrations/<name>/adapter.py` 必须提供：
+
+**元数据（声明式，供注册表/提示词/工作台读取）**
+    NAME            集成名（注册表 `integration:` 引用它）
+    CARRIER         货代在业务表里的**精确写法**（= `routing.match` 的值）
+    CAPABILITIES    {'invoice': bool, 'labels': bool, 'portal_confirm': bool}
+    MANUAL_GATES    [{'what','who','why'}]  必须人工的点（登录滑块/门户确认…）
+    ERROR_CLASSES   [(正则, 失败类)]  门户错误文案 → retryable/needs_human/needs_agent
+    RUNNERS         {'主入口': '脚本名'}  声明的脚本必须真实存在
+    WRITEBACK_FLOW  回写用的流程 id（复用同一份守卫）
+    TEMPLATE        模板/映射文件（可空）
+
+**可调用（行为面，必须是纯函数、离线可测）**
+    match(row) -> bool                       行是否属于本货代
+    preflight(row, cfg) -> {'ours': [], 'ops': []}   缺口分型（我方 / 运营）
+    plan(row, cfg) -> [{'phase','script','argv','writes'}]  可执行计划（引擎/角色据此派发）
+    classify_error(text) -> kind             门户文案 → 失败类（与 flow_failure 同一套 kind）
+
+## 边界（刻意）
+适配器**不重写既有 runner**：它只回答"这一票该怎么跑"（计划 + 分型 + 错误词表），
+真正执行仍是既有脚本 ⇒ 行为不变、可逐票对照。
+
+用法：
+    python3 scripts/integration_contract.py --list
+    python3 scripts/integration_contract.py --describe wenyao
+    python3 scripts/integration_contract.py --validate [--json]
+    python3 scripts/integration_contract.py --plan wenyao --record <record_id> [--carrier 上海文鳐]
+退出码：0 通过；1 有问题；2 参数/加载错误。
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import pathlib
+import re
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+INTEGRATIONS_DIR = HERE / "integrations"
+
+META_STR = ("NAME", "CARRIER", "WRITEBACK_FLOW")
+STATUS_DOC = "ready | scaffold（脚手架骨架，门禁会拦）"
+META_OBJ = ("CAPABILITIES", "MANUAL_GATES", "ERROR_CLASSES", "RUNNERS")
+CALLABLES = ("match", "preflight", "plan", "classify_error")
+KINDS = ("retryable", "needs_human", "needs_agent")
+CAP_KEYS = ("invoice", "labels", "portal_confirm")
+
+
+def discover() -> list:
+    """列出 `scripts/integrations/*/adapter.py`。"""
+    if not INTEGRATIONS_DIR.exists():
+        return []
+    return sorted(p.parent.name for p in INTEGRATIONS_DIR.glob("*/adapter.py"))
+
+
+def load(name: str):
+    """按目录名加载适配器模块（不走包导入，避免 __init__ 依赖）。"""
+    path = INTEGRATIONS_DIR / name / "adapter.py"
+    if not path.exists():
+        raise FileNotFoundError(f"集成的适配器不存在：{path}")
+    spec = importlib.util.spec_from_file_location(f"integration_{name}", path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def validate(name: str) -> list:
+    """契约校验 → 问题清单（空 = 通过）。纯静态检查 + 脚本存在性，不联网、不写表。"""
+    problems: list = []
+    try:
+        m = load(name)
+    except Exception as exc:  # noqa: BLE001
+        return [f"加载失败：{exc}"]
+
+    # 完成度（2026-09-20）：脚手架生成的骨架必须显式标 `STATUS = "scaffold"`，
+    # 门禁据此拦住"看起来装好了、其实没实现"的集成（比让它静默通过安全得多）。
+    status = str(getattr(m, "STATUS", "ready") or "ready")
+    if status != "ready":
+        problems.append(f"STATUS={status}（尚未实现：补门户细节/runner 后改为 ready）")
+
+    for k in META_STR:
+        if not str(getattr(m, k, "") or "").strip():
+            problems.append(f"缺元数据 {k}")
+    for k in META_OBJ:
+        if not hasattr(m, k):
+            problems.append(f"缺元数据 {k}")
+
+    caps = getattr(m, "CAPABILITIES", {}) or {}
+    if not isinstance(caps, dict) or not caps:
+        problems.append("CAPABILITIES 必须是非空 dict")
+    else:
+        unknown = [k for k in caps if k not in CAP_KEYS]
+        if unknown:
+            problems.append(f"CAPABILITIES 含未知键：{unknown}（可用 {list(CAP_KEYS)}）")
+        if not caps.get("invoice"):
+            problems.append("未声明 invoice 能力（发票集成的必备项）")
+
+    gates = getattr(m, "MANUAL_GATES", None)
+    if not isinstance(gates, list):
+        problems.append("MANUAL_GATES 必须是列表（可为空，但必须显式声明）")
+    else:
+        for g in gates:
+            if not isinstance(g, dict) or not all(g.get(k) for k in ("what", "who")):
+                problems.append(f"MANUAL_GATES 条目缺 what/who：{g!r}")
+
+    classes = getattr(m, "ERROR_CLASSES", None)
+    if not isinstance(classes, list) or not classes:
+        problems.append("ERROR_CLASSES 不能为空（门户错误文案必须能被分类）")
+    else:
+        for c in classes:
+            if not (isinstance(c, (list, tuple)) and len(c) == 2 and c[1] in KINDS):
+                problems.append(f"ERROR_CLASSES 条目须为 (正则, {list(KINDS)} 之一)：{c!r}")
+                continue
+            try:
+                re.compile(str(c[0]))
+            except re.error as exc:
+                problems.append(f"ERROR_CLASSES 正则不合法 {c[0]!r}：{exc}")
+
+    runners = getattr(m, "RUNNERS", {}) or {}
+    if not isinstance(runners, dict) or not runners:
+        problems.append("RUNNERS 必须是非空 dict（{'主入口': '脚本名'}）")
+    else:
+        for label, script in runners.items():
+            if not (HERE / str(script)).exists():
+                problems.append(f"RUNNERS['{label}'] 指向的脚本不存在：{script}")
+
+    tmpl = getattr(m, "TEMPLATE", "")
+    if tmpl and not (HERE / str(tmpl)).exists():
+        problems.append(f"TEMPLATE 指向的文件不存在：{tmpl}")
+
+    for fn in CALLABLES:
+        f = getattr(m, fn, None)
+        if not callable(f):
+            problems.append(f"缺可调用 {fn}()")
+    return problems
+
+
+def describe(name: str) -> dict:
+    """给人/角色看的集成说明（工作台、提示词、SOP 都读它，避免各写一份）。"""
+    m = load(name)
+    return {
+        "name": getattr(m, "NAME", name),
+        "carrier": getattr(m, "CARRIER", ""),
+        "capabilities": getattr(m, "CAPABILITIES", {}),
+        "manual_gates": getattr(m, "MANUAL_GATES", []),
+        "error_classes": [[str(p), k] for p, k in (getattr(m, "ERROR_CLASSES", []) or [])],
+        "runners": getattr(m, "RUNNERS", {}),
+        "template": getattr(m, "TEMPLATE", ""),
+        "writeback_flow": getattr(m, "WRITEBACK_FLOW", ""),
+        "problems": validate(name),
+    }
+
+
+def plan(name: str, row: dict) -> list:
+    m = load(name)
+    return m.plan(row, {})
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="货代集成契约（校验/描述/出计划）")
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--describe")
+    ap.add_argument("--validate", action="store_true")
+    ap.add_argument("--plan")
+    ap.add_argument("--record", help="--plan 用：record_id")
+    ap.add_argument("--carrier", help="--plan 用：货代公司（缺省用适配器声明的）")
+    ap.add_argument("--shipment", help="--plan 用：货件号（可选）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    if a.list:
+        names = discover()
+        print(json.dumps(names, ensure_ascii=False) if a.json else "  " + "、".join(names))
+        return 0
+    if a.describe:
+        try:
+            d = describe(a.describe)
+        except Exception as exc:  # noqa: BLE001
+            print(f"❌ {exc}", file=sys.stderr)
+            return 2
+        print(json.dumps(d, ensure_ascii=False, indent=2))
+        return 1 if d["problems"] else 0
+    if a.validate:
+        out, bad = {}, 0
+        for n in discover():
+            p = validate(n)
+            out[n] = p
+            bad += 1 if p else 0
+        if a.json:
+            print(json.dumps(out, ensure_ascii=False, indent=2))
+        else:
+            for n, p in out.items():
+                print(f"  {'✅' if not p else '❌'} {n}" + ("" if not p else "：" + "；".join(p)))
+        return 1 if bad else 0
+    if a.plan:
+        row = {"_id": a.record or "", "货件号": a.shipment or "", "货代公司": a.carrier or ""}
+        try:
+            steps = plan(a.plan, row)
+        except Exception as exc:  # noqa: BLE001
+            print(f"❌ {exc}", file=sys.stderr)
+            return 2
+        print(json.dumps({"integration": a.plan, "steps": steps}, ensure_ascii=False, indent=2))
+        return 0
+    ap.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/integrations/wenyao/adapter.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""上海文鳐 发票集成适配器（迭代 2）。
+
+货代专属事实的**唯一出处**：此前散在注册表 routing、业务线提示词、执行脚本、模板映射真源
+与技能目录五处；**脚本清单不在本注释里复述** —— 契约按下方 `RUNNERS` / `TEMPLATE` 收集
+（包内容集也由它派生；注释里再抄一份就是第二份清单，只会漂移）。
+本文件只回答"这一票该怎么跑 + 怎么分型 + 错误怎么归类"，**不重写 runner**（执行仍是既有脚本）。
+
+门户：`my.ffl-tech.com`（**对方生产系统**，每次访问先经用户确认；登录需人工过一次滑块验证）。
+契约见 `scripts/integration_contract.py`。
+"""
+from __future__ import annotations
+
+NAME = "wenyao"
+STATUS = "ready"        # ready=可用；scaffold=脚手架生成的骨架（门禁会拦）
+CARRIER = "上海文鳐"                 # = 注册表 routing.match 的精确写法
+CAPABILITIES = {"invoice": True, "labels": True, "portal_confirm": True}
+
+MANUAL_GATES = [
+    {"what": "文鳐门户首次/失效登录需人工过一次滑块验证", "who": "用户（终端）",
+     "why": "门户是对方生产系统，自动化过验证有风险；过一次后复用持久 profile",
+     "how": "python3 scripts/wenyao-login-human.py（人工完成滑块后回车继续）"},
+    {"what": "每次门户访问前经用户确认", "who": "用户",
+     "why": "登录/导入/导出都在对方生产系统留真实痕迹（skills/ml-invoice 记的红线）",
+     "how": "会话里问一句；获批后本票按 plan() 执行"},
+    {"what": "HS 编码（海关编码）由运营人工维护；**材质英文不在此列**", "who": "运营",
+     "why": "红线**只管 HS**：系统不预填/不写候选/不自动确认。材质英文走三级解析"
+            "（① per-SKU 字典 → ② 通用小词典 → ③ --material-en，政策A 允许 LLM 译）；"
+            "三级都没命中时**填报阶段自己会阻断并指路**，不要当敏感字段停下",
+     "how": "HS 由运营在 lip 表填好后重勾「发票就绪」；材质英文缺 ⇒ 译成英文后加 --material-en 重跑"},
+]
+
+# 门户错误文案 → 失败类（与 flow_failure 同一套 kind；顺序即优先级）
+ERROR_CLASSES = [
+    (r"滑块|验证码|captcha|验证未通过", "needs_agent"),
+    (r"登录失效|未登录|needLogin|登录墙", "needs_human"),
+    (r"重复|已存在|参考单号", "needs_agent"),
+    (r"等待选择器超时|选择器超时|locator.*(timeout|超时)", "needs_agent"),
+    (r"net::ERR|ECONNRESET|ETIMEDOUT|503|502|429", "retryable"),
+]
+
+RUNNERS = {
+    "全链路（P1–P14 分阶段）": "wenyao_run.py",
+    # ⚠️ 下面两个此前**没声明** ⇒ 不进能力包（`scripts/` 全量同步的机器上不显形，
+    #    纯包装机则 P3/放行闸门直接缺件）：声明后包内容集随之带上它们。
+    "模板填报器（S 列材质英文三级解析的唯一实现）": "wenyao_fill_template.py",
+    "影子放行闸门（与黄金样本逐格比对）": "wenyao_shadow_diff.py",
+    "回写器（共用守卫）": "wenyao-invoice-writeback.mjs",
+    "字段契约生成器": "wenyao_skill_contract.py",
+}
+TEMPLATE = "wenyao-template-map.json"
+WRITEBACK_FLOW = "wenyao-invoice"
+
+
+def match(row: dict) -> bool:
+    return str((row or {}).get("货代公司") or "").strip() == CARRIER
+
+
+def preflight(row: dict, cfg: dict | None = None) -> dict:
+    """缺口分型（运营必须填 / 我方要补）。判据来自注册表 required 的 role=input/state。"""
+    row = row or {}
+    ops, ours = [], []
+    for name in ("产品图", "HS编码", "是否带电", "是否带磁", "产品名称", "SKU", "数量", "箱数",
+                 "重量", "长", "宽", "高"):
+        if not str(row.get(name) or "").strip():
+            ops.append(name)
+    if not str(row.get("货件号") or "").strip():
+        ours.append("货件号（应由 FULL 流程回填）")
+    return {"ours": ours, "ops": ops}
+
+
+def plan(row: dict, cfg: dict | None = None) -> list:
+    """可执行计划（引擎/角色据此派发；**不改写既有 runner**）。
+
+    文鳐是全链路脚本：一次调用按 P1–P14 顺序跑完，`--from` 可断点续跑。
+    """
+    row = row or {}
+    rec = str(row.get("_id") or row.get("record_id") or "")
+    ship = str(row.get("货件号") or "")
+    if not (rec or ship):
+        raise ValueError("plan() 需要 record_id 或货件号（缺一不可）")
+    ident = ["--record-id", rec] if rec else ["--shipment", ship]
+    return [
+        {"phase": "P1-路由", "script": "wenyao_run.py", "argv": [*ident, "--shadow"],
+         "writes": False, "why": "只读取证：核对货代/状态/字段齐备；材质英文三级解析"
+                                  "（SKU 字典→小词典→--material-en）未命中时本步即阻断并指路"},
+        {"phase": "P2-P14-全链路", "script": "wenyao_run.py",
+         "argv": [*ident, "--yes"], "writes": True,
+         "why": "模板填报 → 回写「发票文件」+置填写中 → 门户导入/勾选/导出 → 回写「大货标签」"},
+    ]
+
+
+def classify_error(text: str) -> str:
+    import re
+    for pat, kind in ERROR_CLASSES:
+        if re.search(pat, str(text or ""), re.I):
+            return kind
+    return "needs_agent"

package/engine/scripts/integrations/xzh/adapter.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""鑫中航-美墨 发票集成适配器（迭代 2）。
+
+门户：`http://106.13.216.234:10001`（老 IP 型系统，对方生产系统）。
+执行入口：`invoice_lip_runner.py`（两段式：生成 → 门户上传/下载标签），
+门户段实现在 `invoice_stageb.py`；模板与 defaults 来自 `invoice-mapping.json`。
+契约见 `scripts/integration_contract.py`。
+"""
+from __future__ import annotations
+
+NAME = "xzh"
+STATUS = "ready"        # ready=可用；scaffold=脚手架生成的骨架（门禁会拦）
+CARRIER = "鑫中航-美墨"               # = 注册表 routing.match 的精确写法
+CAPABILITIES = {"invoice": True, "labels": True, "portal_confirm": True}
+
+MANUAL_GATES = [
+    {"what": "门户账号（invoice-mapping.json 的 xinzhonghang.user）由运营维护", "who": "运营",
+     "why": "对方生产系统账号，凭据不进仓库/不进对话", "how": "在 ~/.dsh/argent/invoice-mapping.json 维护"},
+    {"what": "HS 编码/材质由运营人工维护", "who": "运营",
+     "why": "报关敏感字段，系统不预填", "how": "运营在 lip 表填好后重勾「发票就绪」"},
+]
+
+ERROR_CLASSES = [
+    (r"参考单号.*重复|已存在该单", "needs_agent"),        # 幂等命中：视为已存在，继续下载标签
+    (r"登录|Login|账号|密码", "needs_human"),
+    (r"标签未就绪|标签.*生成中", "retryable"),
+    (r"等待选择器超时|选择器超时|locator.*(timeout|超时)", "needs_agent"),
+    (r"net::ERR|ECONNRESET|ETIMEDOUT|503|502|429", "retryable"),
+]
+
+RUNNERS = {
+    "全链路（生成→上传→标签→回写）": "invoice_lip_runner.py",
+    "门户段（登录/上传/下载标签）": "invoice_stageb.py",
+    "回写器（共用守卫）": "wenyao-invoice-writeback.mjs",
+}
+TEMPLATE = ""                         # 模板路径在部署配置 invoice-mapping.json 里（每客户一份）
+WRITEBACK_FLOW = "xzh-invoice"
+
+
+def match(row: dict) -> bool:
+    return str((row or {}).get("货代公司") or "").strip() == CARRIER
+
+
+def preflight(row: dict, cfg: dict | None = None) -> dict:
+    row = row or {}
+    ops, ours = [], []
+    for name in ("HS编码", "材质", "产品名称", "SKU", "数量", "箱数"):
+        if not str(row.get(name) or "").strip():
+            ops.append(name)
+    if not str(row.get("货件号") or "").strip():
+        ours.append("货件号（应由 FULL 流程回填）")
+    return {"ours": ours, "ops": ops}
+
+
+def plan(row: dict, cfg: dict | None = None) -> list:
+    row = row or {}
+    rec = str(row.get("_id") or row.get("record_id") or "")
+    if not rec:
+        raise ValueError("plan() 需要 record_id（鑫中航入口按记录 id）")
+    return [
+        {"phase": "生成发票", "script": "invoice_lip_runner.py",
+         "argv": ["--record-id", rec, "--generate-only"], "writes": False,
+         "why": "先只生成 xlsx 并核对（不写表、不上传门户）"},
+        {"phase": "上传+标签+回写", "script": "invoice_lip_runner.py",
+         "argv": ["--record-id", rec], "writes": True,
+         "why": "门户上传（幂等：已有则视为已存在）→ 下载大货标签 → 回写「发票文件/大货标签」+置已完成"},
+    ]
+
+
+def classify_error(text: str) -> str:
+    import re
+    for pat, kind in ERROR_CLASSES:
+        if re.search(pat, str(text or ""), re.I):
+            return kind
+    return "needs_agent"

package/engine/scripts/invoice-mapping.example.json

@@ -0,0 +1,40 @@
+{
+  "templates": {
+    "鑫中航": "/Users/chester/Documents/鑫中航发票模板.xlsx",
+    "上海文鳐": "",
+    "商达": "",
+    "允墨": ""
+  },
+  "defaults": {
+    "服务类型": "美转墨S1",
+    "报关方式": "买单报关",
+    "带电": "否",
+    "带磁": "否",
+    "申报币种": "USD",
+    "国内收货仓库": "深圳仓",
+    "收件人地址库": "MXRC03",
+    "用途": "家用",
+    "申报价值USD": "10",
+    "brand": "无",
+    "model": "无"
+  },
+  "hsCache": "/Users/chester/.dsh/argent/hs-cache.json",
+  "output": {
+    "invoice": "/Users/chester/.dsh/argent/invoice-output",
+    "labels": "/Users/chester/.dsh/argent/invoice-labels",
+    "logs": "/Users/chester/.dsh/argent/invoice-logs"
+  },
+  "xinzhonghang": {
+    "url": "http://106.13.216.234:10001/Login/VueLoginView",
+    "user": "100610"
+  },
+  "fullSource": {
+    "base": "TJrmbxuIyauNqrsJL9FclLfbnhc",
+    "table": "tbl4vDxpCa71YLpe"
+  },
+  "skuSource": {
+    "base": "TJrmbxuIyauNqrsJL9FclLfbnhc",
+    "table": "tblM4SMAB028VCbb"
+  },
+  "_storeIdNote": "店铺→卖家ID 不在此文件：唯一真源 = scripts/ml-store-ids.json（由 scripts/ml_store_ids.py 解析）。2026-09-19 前的副本键是 '1店-子账号' 这种短名，lip 的完整店名匹配不上 ⇒ 曾导致发票 PO 静默退化成紫鸟 store_id。"
+}

package/engine/scripts/invoice-table.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+# ============================================================
+# invoice-table.sh — 发票流程建表脚本（幂等，单表方案 v2，2026-08-20）
+# 在正式 Base（FULL 货件管理）中创建：
+#   「FULL任务」— 运营唯一填写表
+#       SKU=双向关联选择器（选项来自 SKU 主数据字典）
+#       品名/品名英文/海关编码/材质/重量/尺寸/产品图 = lookup 自动带出
+#       数量/箱数/店铺名称/货代/国内收货仓库/就绪 = 运营填写
+#   「SKU 主数据」— 商品字典（人工维护）
+# 用法: invoice-table.sh [--base-token <token>]
+# 默认 Base: ~/.dsh/argent/fulfillment.env 的 FEISHU_BASE_TOKEN
+# 说明: v3 API 不支持 link/auto_number 建表，建 FULL任务 走 v1 API 裸调。
+# ============================================================
+set -euo pipefail
+
+BASE_TOKEN="${BASE_TOKEN:-}"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base-token) BASE_TOKEN="${2:-}"; shift 2 ;;
+    *) echo "未知参数: $1"; exit 1 ;;
+  esac
+done
+
+if [ -z "$BASE_TOKEN" ]; then
+  ENV_FILE="$HOME/.dsh/argent/fulfillment.env"
+  [ -f "$ENV_FILE" ] && set -a && source "$ENV_FILE" && set +a
+  BASE_TOKEN="${FEISHU_BASE_TOKEN:-}"
+fi
+[ -z "$BASE_TOKEN" ] && { echo "未提供 Base Token（--base-token 或 fulfillment.env）"; exit 1; }
+
+python3 - "$BASE_TOKEN" << 'PYEOF'
+import json, subprocess, sys
+
+BASE = sys.argv[1]
+
+def cli(*args, timeout=60):
+    p = subprocess.run(["lark-cli", *args, "--as", "bot", "--format", "json"],
+                       capture_output=True, text=True, timeout=timeout)
+    try:
+        return json.loads(p.stdout)
+    except Exception:
+        return {"ok": False, "error": {"message": p.stderr[:200]}}
+
+def table_id(name):
+    d = cli("base", "+table-list", "--base-token", BASE)
+    for t in d.get("data", {}).get("tables", []):
+        if t.get("name") == name:
+            return t.get("id")
+    return None
+
+def field_names(tid):
+    d = cli("base", "+field-list", "--base-token", BASE, "--table-id", tid)
+    return [f.get("name") for f in d.get("data", {}).get("fields", [])]
+
+def field_ids(tid):
+    d = cli("base", "+field-list", "--base-token", BASE, "--table-id", tid)
+    return {f.get("name"): f.get("id") for f in d.get("data", {}).get("fields", [])}
+
+def ensure_view(tid, vname):
+    d = cli("base", "+view-list", "--base-token", BASE, "--table-id", tid)
+    for v in d.get("data", {}).get("views", []):
+        if v.get("name") == vname:
+            return v.get("id")
+    cli("base", "+view-create", "--base-token", BASE, "--table-id", tid,
+        "--json", json.dumps({"name": vname, "type": "grid"}))
+    d = cli("base", "+view-list", "--base-token", BASE, "--table-id", tid)
+    for v in d.get("data", {}).get("views", []):
+        if v.get("name") == vname:
+            return v.get("id")
+    return None
+
+def hide_fields(tid, vid, hidden):
+    """v1 视图接口：隐藏字段（字段编组 API 不存在，用视图隐藏实现运营/系统分视图）。"""
+    if not vid:
+        return
+    cli("api", "PATCH",
+        f"/open-apis/bitable/v1/apps/{BASE}/tables/{tid}/views/{vid}",
+        "--data", json.dumps({"property": {"hidden_fields": hidden}}))
+
+SKU_MASTER = "SKU 主数据"
+FULL = "FULL任务"
+
+# ── 1. SKU 主数据 ──
+print("── 检查/创建「SKU 主数据」表 ──")
+sku_tid = table_id(SKU_MASTER)
+if sku_tid:
+    print(f"✓ SKU 主数据 已存在: {sku_tid}")
+else:
+    d = cli("base", "+table-create", "--base-token", BASE, "--name", SKU_MASTER,
+            "--fields", json.dumps([
+                {"type": "text", "name": "SKU"},
+                {"type": "text", "name": "品名"},
+                {"type": "text", "name": "品名英文"},
+                {"type": "number", "name": "重量(kg/箱)"},
+                {"type": "number", "name": "长(cm)"},
+                {"type": "number", "name": "宽(cm)"},
+                {"type": "number", "name": "高(cm)"},
+                {"type": "text", "name": "材质中文"},
+                {"type": "text", "name": "材质英文"},
+                {"type": "text", "name": "海关编码"},
+                {"type": "attachment", "name": "产品图"},
+                {"type": "text", "name": "备注"},
+            ], ensure_ascii=False))
+    print("→ SKU 主数据 创建:", "ok" if d.get("ok") else d.get("error", {}).get("message", "?"))
+    sku_tid = table_id(SKU_MASTER)
+    if not sku_tid:
+        sys.exit(1)
+
+# ── 2. FULL任务（v2：link SKU + lookup 自动带出）──
+print("── 检查/创建「FULL任务」表 ──")
+full_tid = table_id(FULL)
+if full_tid:
+    flds = field_names(full_tid)
+    if "SKU名称" in flds:
+        print(f"✓ FULL任务 已存在且为 v2 结构: {full_tid}")
+    else:
+        print(f"⚠ FULL任务 存在但非 v2 结构（字段: {flds[:5]}...），请手工确认后删除重建")
+        sys.exit(1)
+else:
+    base_fields = [
+    {"field_name": "序号", "type": 1005, "property": {"auto_serial": {"type": "auto_increment_number"}}},
+    {"field_name": "SKU", "type": 21, "property": {"table_id": sku_tid, "multiple": False, "back_field_name": "FULL任务关联"}},
+    {"field_name": "数量", "type": 2},
+    {"field_name": "箱数", "type": 2},
+    {"field_name": "店铺名称", "type": 3, "property": {"options": [{"name": "3店-主账号"}, {"name": "2店-子账号"}, {"name": "1店-子账号"}]}},
+    {"field_name": "货代", "type": 3, "property": {"options": [{"name": "鑫中航"}, {"name": "上海文鳐"}, {"name": "商达"}, {"name": "允墨"}]}},
+    {"field_name": "国内收货仓库", "type": 3, "property": {"options": [{"name": "深圳仓"}, {"name": "义乌仓"}, {"name": "广州仓"}]}},
+    {"field_name": "就绪", "type": 7},
+    {"field_name": "状态", "type": 3, "property": {"options": [{"name": "Pending"}, {"name": "运行中"}, {"name": "已完成"}, {"name": "失败"}]}},
+    {"field_name": "发票状态", "type": 3, "property": {"options": [{"name": "待生成"}, {"name": "填写中"}, {"name": "已上传"}, {"name": "标签已下载"}, {"name": "已完成"}, {"name": "失败"}, {"name": "不开发票"}]}},
+    {"field_name": "当前步骤", "type": 1},
+    {"field_name": "货件号", "type": 1},
+    {"field_name": "发票错误信息", "type": 1},
+    {"field_name": "发票文件", "type": 17},
+    {"field_name": "大货标签", "type": 17},
+    {"field_name": "产品标签", "type": 17},
+    {"field_name": "箱唛", "type": 17},
+    {"field_name": "创建时间", "type": 1001},
+]
+    d = cli("api", "POST", f"/open-apis/bitable/v1/apps/{BASE}/tables",
+            "--data", json.dumps({"table": {"name": FULL, "fields": base_fields}}, ensure_ascii=False))
+    if not d.get("ok"):
+        print("✗ FULL任务 建表失败:", d.get("error", {}).get("message", "?"))
+        sys.exit(1)
+    full_tid = d["data"]["table_id"]
+    print(f"→ FULL任务 已创建: {full_tid}（基础字段 {len(base_fields)} 个）")
+
+    # lookup 字段（11 个，自动带出字典数据）
+    lookups = ["SKU名称", "品名", "品名英文", "海关编码", "材质中文", "材质英文",
+               "重量(kg/箱)", "长(cm)", "宽(cm)", "高(cm)", "产品图"]
+    src_field = {  # 源表（SKU 主数据）字段名
+        "SKU名称": "SKU", "品名": "品名", "品名英文": "品名英文", "海关编码": "海关编码",
+        "材质中文": "材质中文", "材质英文": "材质英文", "重量(kg/箱)": "重量(kg/箱)",
+        "长(cm)": "长(cm)", "宽(cm)": "宽(cm)", "高(cm)": "高(cm)", "产品图": "产品图",
+    }
+    where = {"logic": "and", "conditions": [["SKU", "==", {"type": "field_ref", "field": "SKU"}]]}
+    json_fields = [
+        {"name": name, "type": "lookup", "from": sku_tid, "select": src_field[name], "where": where}
+        for name in lookups
+    ]
+    d = cli("base", "+field-create", "--i-have-read-guide", "--base-token", BASE,
+            "--table-id", full_tid, "--json", json.dumps(json_fields, ensure_ascii=False))
+    print("→ lookup 字段:", "ok" if d.get("ok") else d.get("error", {}).get("message", "?"))
+
+# ── 3. 视图配置（字段编组 API 不存在，用视图隐藏实现运营/系统分视图）──
+print("── 配置视图（运营填写 / AI自动）──")
+fids = field_ids(full_tid)
+OP_FIELDS = ["SKU", "数量", "箱数", "店铺名称", "货代", "国内收货仓库", "就绪", "序号"]
+ALL_NAMES = set(field_names(full_tid))
+op_view = ensure_view(full_tid, "运营填写")
+if op_view:
+    hide_fields(full_tid, op_view, [fids[n] for n in ALL_NAMES - set(OP_FIELDS)])
+    print("✓ 运营填写 视图（仅运营字段）")
+ai_view = ensure_view(full_tid, "AI自动")
+if ai_view:
+    hide_fields(full_tid, ai_view, [fids[n] for n in OP_FIELDS if n in fids])
+    print("✓ AI自动 视图（仅系统字段）")
+sku_fids = field_ids(sku_tid)
+op_view = ensure_view(sku_tid, "运营填写")
+if op_view:
+    # 运营只维护中文/物理属性；品名英文/材质英文由 AI 翻译，FULL任务关联自动
+    hide_fields(sku_tid, op_view, [sku_fids[n] for n in ("FULL任务关联", "品名英文", "材质英文") if n in sku_fids])
+    print("✓ SKU主数据 运营填写 视图（维护字段，英文翻译字段已隐藏）")
+ai_view = ensure_view(sku_tid, "AI自动")
+if ai_view:
+    # 主字段（SKU）无法隐藏；AI自动 视图 = SKU + 英文翻译字段 + 自动反向关联
+    ai_show = {"SKU", "品名英文", "材质英文", "FULL任务关联"}
+    hide_fields(sku_tid, ai_view, [sku_fids[n] for n in set(sku_fids) - ai_show])
+    print("✓ SKU主数据 AI自动 视图（英文翻译 + 自动字段）")
+PYEOF
+
+echo ""
+echo "完成。表清单："
+lark-cli base +table-list --base-token "$BASE_TOKEN" --as bot --format json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); [print(' -', t['name'], t['id']) for t in d.get('data',{}).get('tables',[])]"