From e009db3cf7565396e5947cc98b855ca4a818a40a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9C=B1=E6=BD=AE?= <zhuchaowe@users.noreply.github.com>
Date: Mon, 15 Jun 2026 14:29:24 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=8A=95=E9=99=8D=E5=B0=BA?=
 =?UTF-8?q?=E5=AF=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../account-reconciliation/SKILL.md           | 142 ++++++++++++++++++
 skills/linggan/agnes-image/SKILL.md           |   6 +-
 .../agnes-image/scripts/generate_image.py     |  27 ++++
 3 files changed, 173 insertions(+), 2 deletions(-)
 create mode 100644 skills/developing/account-reconciliation/SKILL.md

diff --git a/skills/developing/account-reconciliation/SKILL.md b/skills/developing/account-reconciliation/SKILL.md
new file mode 100644
index 0000000..925b4f5
--- /dev/null
+++ b/skills/developing/account-reconciliation/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: account-reconciliation
+description: 收银稽核对账。核对企迈（QianMai）系统账单与外卖平台（京东到家 / 美团外卖 / 饿了么·淘宝闪购）账单是否一致。当用户提供「美团饿了么收银稽核口径」类 Excel、需要做收银稽核 / 平台对账 / 账单核对 / 结算金额比对时使用。讲清数据结构、读取陷阱与逐单对账口径，按实际表灵活适配。
+category: Data & Retrieval
+---
+
+# 收银稽核对账 (Account Reconciliation)
+
+核对**企迈系统账单**与**外卖平台账单**逐单是否一致，定位差异。覆盖京东到家、美团外卖、饿了么（淘宝闪购）三个平台。
+
+## When to use
+
+- 用户提供「美团饿了么收银稽核口径」一类的对账 Excel，要求做收银稽核 / 平台对账 / 账单核对。
+- 需要逐单比对「企迈系统结算金额」与「平台结算金额」是否一致、定位差异订单。
+- 需要核对平台佣金、配送费、优惠等科目口径。
+
+> ⚠️ 实际 Excel **不保证标准**（表头会错位、字段名会变、订单号带特殊前缀）。
+> **不要硬编码列号**，要按下文方法按「值/语义」定位列。本文字段名是当前样本口径，
+> 遇到新表先做「数据探查」确认，再套用对账逻辑。
+
+## Excel 结构
+
+通常 7 个 sheet：
+
+| sheet | 角色 | 形态 |
+|---|---|---|
+| `对账映射关系` | 口径说明 | 三组（企迈↔京东 / 企迈↔饿了么 / 企迈↔美团）字段映射 + 汇总公式 |
+| `企迈-京东` / `企迈-美团` / `企迈-饿了么` | **企迈系统侧** | **流水拆分表**：一个订单 = 多行，每行一个「结账方式名称」+ 金额 |
+| `平台-京东` / `平台-美团` / `平台-饿了么` | **平台侧** | **宽表**：一个订单 = 一行，几十~上百列 |
+
+- 企迈侧需按 `三方订单号` 聚合，对「结账方式名称」透视，金额取 `营业额（元）`。
+- 平台侧一单一行，主键 `订单号`（饿了么为 `订单编号`）。
+
+> `对账映射关系` sheet 里的汇总公式用了 `C2/C3/H2/M2/M6` 这类**单元格引用**，存在
+> off-by-one 偏移、部分越界，**不可直接套用**。一律**以实际数据验证为准**。
+
+## 数据读取的 5 个坑（务必处理）
+
+1. **订单号带前导反引号**：企迈侧订单号/三方订单号以 `` ` `` 前缀存为文本（如
+   `` `3365287004676962 ``），平台侧多为纯数字。关联前两边都要 `lstrip('`').strip()`，
+   统一转字符串再比较（平台侧 int 大数 `str()` 后无精度问题）。
+
+2. **企迈-京东表头与数据错位 ~2 列**：该 sheet 表头标签与列内容**对不上**（表头第 0 列
+   写「门店名称」实际放门店编码；表头第 15 列写「优惠拉动营业额」实际放结账方式名称）。
+   **不能信任 `企迈-京东` 的表头标签**。美团/饿了么表头一般正常。
+
+3. **「结账方式名称」列要按值定位，避开干扰列**：企迈侧同时存在 `结账方式拆分` 和
+   `结账方式名称` 两列，**两列都可能含「XX支付」**。正确的「结账方式名称」列应**同时包含**
+   结算行的值（如 `美团外卖支付`）**和**佣金行的值（`平台佣金`）。定位方法：
+   ```
+   遍历每一列，取该列所有去重值集合；
+   选「同时包含 pay_name 且包含 '平台佣金'」的那一列；
+   找不到再退化为「只包含 pay_name」的列。
+   ```
+   这样京东（表头错位）和美团/饿了么（表头正常）都能正确命中。
+
+4. **平台字段名有全角/半角括号、尾部空格差异**：如饿了么的
+   `平台服务费（含技术服务费和配送服务费） `（全角括号 + 尾部空格）。匹配平台列时用
+   「**包含**」而非「精确相等」，必要时去空格再比。
+
+5. **平台侧佣金/服务费是负数（扣项）**：平台账单里佣金、平台服务费多为负值（从结算款里扣）。
+   与企迈「平台佣金」（正值）比对时**两边取绝对值**。
+
+## 关联键
+
+```
+企迈.三方订单号  ==  平台.订单号        # 京东、美团
+企迈.三方订单号  ==  平台.订单编号      # 饿了么
+```
+清洗后取交集；不在交集的订单单独列出（「仅企迈有」「仅平台有」常见于售后单、跨日结算、未同步）。
+
+## 对账口径（已用样本逐单验证，差异 = 0.00）
+
+判定阈值：`|企迈金额 − 平台金额| < 0.01` 视为一致。
+
+### 1) 结算金额（核心，必对）
+
+企迈侧取「结账方式名称 = XX支付」那一行的 `营业额`，对平台结算字段：
+
+| 平台 | 企迈侧（结账方式名称） | = | 平台侧字段 |
+|---|---|---|---|
+| 京东 | `京东支付` | = | `应结金额` |
+| 美团 | `美团外卖支付` | = | `商家应收款` |
+| 饿了么 | `淘宝闪购支付` | = | `结算金额` |
+
+### 2) 佣金（企迈「平台佣金」= 平台收取的全部服务费合计，取绝对值）
+
+企迈侧「平台佣金」是平台收取的**全部服务费**（佣金 + 配送等打包），所以平台侧要用
+「**含佣金和配送的平台服务费**」整体比对，而非只看佣金分项：
+
+| 平台 | 企迈侧 | = \|Σ平台字段\| |
+|---|---|---|
+| 京东 | `平台佣金` | `总佣金(货款佣金+运费佣金+餐盒费佣金)(可开票)` |
+| 美团 | `平台佣金` | `平台服务费(含佣金和配送服务费)` |
+| 饿了么 | `平台佣金` | `平台服务费（含技术服务费和配送服务费）` + `增值服务费（店铺推广）` |
+
+> 很多订单没有「平台佣金」行（企迈侧缺该行）且平台佣金为 0，此时两边都是 0，一致。
+
+### 3) 配送费 / 优惠（口径较模糊，建议「展示并人工核对」而非硬判定）
+
+企迈侧配送/优惠类结账方式名称（如 `满减配送费`、`折扣商品`、`使用红包`、`满减`、
+`取件服务费`、`商家承担配送费`、`京东秒送货款优惠`、`优惠劵`、`淘宝闪购商家优惠`、
+`店铺满减` 等）与平台侧多个补贴/配送字段是**多对多**关系，映射表组合公式不可靠。
+**建议把企迈这些行的明细 + 平台对应字段并列展示**，标出差额供人工判断，不强行下
+「一致/不一致」结论。
+
+## 对账步骤
+
+1. **探查**（每个新 Excel 必做）：打印各 sheet 行列数；打印企迈侧前几行**带列索引**的
+   原始值，确认「三方订单号 / 营业额 / 结账方式名称」真实列位置（注意京东错位）；
+   打印平台侧表头，确认结算/佣金字段真实列名（注意全角/空格）。
+
+2. **建企迈索引**：按 `三方订单号` 分组（清洗反引号），对「结账方式名称」透视
+   `营业额` 求和，得到每单 `{结账方式名称: 金额}`。
+
+3. **建平台索引**：按 `订单号/订单编号` 分组（清洗反引号），取结算字段、佣金字段
+   （佣金可能多个字段求和）。
+
+4. **逐单比对**：对交集订单，比「结算」「佣金」（取绝对值），算差额，<0.01 判一致；
+   配送/优惠并列展示明细。
+
+5. **输出**：
+   - 报告（markdown）：每平台订单数对比、仅单边存在的订单、逐单核对表
+     （企迈结算 / 平台结算 / 差 / 一致；企迈佣金 / 平台佣金 / 差 / 一致）、
+     企迈侧结账方式名称分布。
+   - 明细（CSV，用 `utf-8-sig` 便于 Excel 打开）：逐单各科目金额 + 企迈拆分串。
+
+## 运行环境
+
+- 本仓库用 poetry，读 Excel 用 `openpyxl`：`load_workbook(path, data_only=True)` 取计算值。
+- 临时脚本放 `/tmp`，运行 `poetry run python /tmp/xxx.py`。
+- 注意：用 heredoc 写脚本在本环境可能不落盘，**用文件写入工具创建脚本**更可靠。
+
+## 排查
+
+- **关联数为 0**：订单号没对上 —— 检查反引号清洗、int/str 类型、是否取错 key 列
+  （平台侧有「订单序号」「结算id」等多个像 key 的列，认准「订单号/订单编号」）。
+- **某字段全为 NA**：平台 sheet 实际列名与配置不符，用「包含」匹配并核对全角/空格。
+- **结算对得上但佣金对不上**：先确认企迈「平台佣金」列是否被「结账方式拆分」干扰列
+  顶替（见读取坑第 3 点）；再确认平台侧佣金是否需多字段求和、是否取绝对值。
+- **新平台 / 列名变化**：先做「探查」确认结算、佣金字段真实列名，再按对账口径表配置；
+  佣金若多字段组合，用「Σ后取绝对值」与企迈「平台佣金」比。
diff --git a/skills/linggan/agnes-image/SKILL.md b/skills/linggan/agnes-image/SKILL.md
index e0b18ef..76365fa 100644
--- a/skills/linggan/agnes-image/SKILL.md
+++ b/skills/linggan/agnes-image/SKILL.md
@@ -28,12 +28,14 @@ export AGNES_API_KEY="sk-xxxxxxxx"
 python {baseDir}/scripts/generate_image.py --prompt "一只圆润萌系的小火龙，大眼睛，贴纸风格"
 ```
 
-指定尺寸：
+指定尺寸（宽高**必须是 16 的倍数**，如 `1024x768`、`1152x768`）：
 
 ```bash
 python {baseDir}/scripts/generate_image.py --prompt "壮丽的山川日出" --size "1024x768"
 ```
 
+> ⚠️ 生成图片的宽和高都必须是 16 的倍数。脚本会自动把传入的尺寸四舍五入到最近的 16 倍数，并在 stderr 提示调整结果。
+
 ### 图生图（保持一致性）
 
 提供参考图 URL 或 `data:image` Base64，让新图沿用参考图的角色/构图：
@@ -70,7 +72,7 @@ python {baseDir}/scripts/generate_image.py \
 
 - `--prompt`: (必选) 图像生成的文本描述，支持中英文。
 - `--model`: (可选) 模型 ID，默认 `agnes-image-2.1-flash`。
-- `--size`: (可选) 图像尺寸，如 `1024x1024`、`1024x768`，默认 `1024x1024`。
+- `--size`: (可选) 图像尺寸，如 `1024x1024`、`1024x768`，默认 `1024x1024`。**宽高必须是 16 的倍数**，否则脚本会自动规整到最近的 16 倍数。
 - `--image`: (可选) 参考图 URL 或 `data:image/...;base64,...`，用于图生图，可多次指定。
 - `--api-key`: (可选) Agnes API Key，未提供时读取 `AGNES_API_KEY` 环境变量。
 - `--save`: (可选) 下载并保存到指定本地路径。
diff --git a/skills/linggan/agnes-image/scripts/generate_image.py b/skills/linggan/agnes-image/scripts/generate_image.py
index 036387c..27700be 100644
--- a/skills/linggan/agnes-image/scripts/generate_image.py
+++ b/skills/linggan/agnes-image/scripts/generate_image.py
@@ -70,6 +70,22 @@ def fetch_bytes(url):
         return r.read()
 
 
+def normalize_size(size):
+    """Round width/height to the nearest multiple of 16 (minimum 16).
+
+    Returns the normalized "WxH" string. Raises ValueError on bad input.
+    """
+    parts = size.lower().replace(" ", "").split("x")
+    if len(parts) != 2:
+        raise ValueError(f"invalid size '{size}', expected format like 1024x768")
+    w, h = int(parts[0]), int(parts[1])
+    if w <= 0 or h <= 0:
+        raise ValueError(f"invalid size '{size}', width/height must be positive")
+    w = max(16, round(w / 16) * 16)
+    h = max(16, round(h / 16) * 16)
+    return f"{w}x{h}"
+
+
 def make_transparent(png_bytes, thresh=60, white_min=225):
     """把纯白背景变透明（保留内部白色）。
     从图像四边多个种子点做 flood fill，只清除与边缘连通的白色区域。
@@ -114,6 +130,17 @@ def main():
         print("ERROR: 缺少 API Key，请用 --api-key 或设置 AGNES_API_KEY 环境变量。")
         sys.exit(1)
 
+    # Image dimensions must be multiples of 16; round to the nearest valid size.
+    try:
+        normalized_size = normalize_size(args.size)
+    except ValueError as e:
+        print(f"ERROR: {e}")
+        sys.exit(1)
+    if normalized_size != args.size:
+        print(f"NOTE: size '{args.size}' adjusted to '{normalized_size}' (must be a multiple of 16).",
+              file=sys.stderr)
+    args.size = normalized_size
+
     # 需要保存且要透明时，直接请求 URL 再下载处理（Pillow 处理本地字节）
     want_b64 = False
     try: