docs: settle host import leading-star and lookup label contract

CHANGELOG.md

@@ -9,10 +9,15 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.126
+
+- 沉淀 `replaces: import` 宿主契约：表头必填红星在前（`*显示名`），技能须同时兼容前/后缀 `*`；lookup 单元格可为 `{value} · {label}`
+- 新增可复用模块 `scripts/service/table_file_import.py` 与单测；更新 ACTIONS / SCHEMA / CHECKLIST A4-14 / replaces-import 示例
+
 ## 1.0.125
 
 - 固化免费 PyArmor Trial 发布约定：行数门槛是预防线；实际失败时按日志定位模块并按职责拆分，保留兼容门面，以 Gitea Trial 加密结果验收
-- 记录 field_locator 拆分后同一免费 Trial 链路成功的复盘案例；不使用未经验证的统一字节数阈值
+- 记录 field_locator 拆分后同一免费 Trial 链路成功的复盘案例；不使用未经验证的统一字节数规则
 
 ## 1.0.124
 

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.125
+version: 1.0.126
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:

assets/examples/README.md

@@ -14,4 +14,4 @@
 - `bind-visible-when-row.action.example.json`：行菜单显隐 `bind.visibleWhen` 形状参考（按当前行状态显示/隐藏行按钮；见 `references/ACTIONS.md`「行菜单显隐」）。
 - `selection-label-column.action.example.json`：选择摘要 `bind.labelColumn` 形状参考（见 `references/ACTIONS.md`「选择摘要」）。
 - `selection-mode-optional.action.example.json`：`bind.selectionMode: "optional"` 智能勾选/按数量合并形状参考（含 `cron`：配置页按无勾选分支，只见数量字段）；用户可见文案为口语中文（见 `references/ACTIONS.md`「勾选驱动模式」「用户可见文案」）。
-- `replaces-create.action.example.json` / `replaces-update.action.example.json` / `replaces-delete.action.example.json` / `replaces-import.action.example.json`：数据管理默认按钮接管（`replaces`）形状参考；**import 时 UI 仍用宿主「导入数据」面板**，确认后调技能写库（见 `references/ACTIONS.md`「`replaces`」）。
+- `replaces-create.action.example.json` / `replaces-update.action.example.json` / `replaces-delete.action.example.json` / `replaces-import.action.example.json`：数据管理默认按钮接管（`replaces`）形状参考；**import 时 UI 仍用宿主「导入数据」面板**，确认后调技能写库（见 `references/ACTIONS.md`「`replaces`」）。实现 import 解析时复用 `scripts/service/table_file_import.py`（兼容宿主前缀 `*` 表头与 `{value} · {label}` lookup 单元格）。

assets/examples/replaces-import.action.example.json

@@ -1,7 +1,7 @@
 {
   "id": "item-import",
   "label": "导入记录",
-  "description": "由宿主「导入数据」面板调用：解析 Excel/CSV 并写入业务表（含领域校验与派生字段）。",
+  "description": "由宿主「导入数据」面板调用：解析 Excel/CSV 并写入业务表（含领域校验与派生字段）。表头可带前/后缀*；lookup 列可为「编号 · 名称」。",
   "replaces": "import",
   "placements": [],
   "executionProfile": "sync",
@@ -19,7 +19,7 @@
       "filePath": {
         "type": "string",
         "title": "导入文件",
-        "description": "由宿主导入面板传入的 Excel/CSV 路径。",
+        "description": "由宿主导入面板传入的 Excel/CSV 路径。表头：显示名（可带前/后缀*）；关联列可填编号或「编号 · 名称」。",
         "format": "file"
       },
       "onError": {

development/CHECKLIST.md

@@ -116,6 +116,7 @@ checklist_version: 1.0
 - [ ] A4-11 **P1** 若行操作应按业务状态显隐（如仅待确认可「采用」、仅已采用可「加入待写」）：用 **`bind.visibleWhen`**（对当前行列值求值；存库原始值如 `approved`）；勿指望 Policy L3；CLI 侧仍须校验状态（见 `references/ACTIONS.md`「行菜单显隐」）
 - [ ] A4-12 **P1** 若要在表单里翻页勾选一批业务行（文章、平台等）：用 Lookup **`presentation: "paged_table"`**（仍是 `display_type: lookup`，勿新造类型）；`skill_cli` 的 stdout 为一行 `{"items","total"}`，0 条也成功退出；该列表命令不要在入口加载整包 platform-kit 或 Playwright（见 `references/ACTIONS.md`「分页勾选小表」）
 - [ ] A4-13 **P1** 若 Action 有固定小枚举（状态/船司/优先级等）需中文展示：用 `enum` + **`enumNames`**，或绑列复用列 `options_json` 数组；宿主优先序为绑列 options → enumNames → 纯 enum；**禁止**为中文展示造假 Lookup（见 `references/ACTIONS.md`「静态枚举 label」）
+- [ ] A4-14 **P0** 若声明 `replaces: import`：表头清洗须兼容宿主**前缀**必填星（`*显示名`）与旧后缀（`显示名*`）；lookup 列须能解析 `{value} · {label}`；推荐复用 `scripts/service/table_file_import.py`；**禁止**只 `removesuffix("*")` 导致「字段不能为空」（见 `references/ACTIONS.md`「导入表头与 lookup 单元格」）
 ---
 
 ## 5. 账号与浏览器会话（网页 RPA 适用；其他形态标 N/A 或改测等价项）

references/ACTIONS.md

@@ -291,6 +291,20 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 可抄文件见 [`assets/examples/`](../assets/examples/)：`replaces-*.action.example.json`。
 
+### 导入表头与 lookup 单元格（宿主契约，`replaces: import` 必读）
+
+宿主「下载导入模板」与导入预览已统一：
+
+| 现象 | 宿主实际写出 | 技能解析须兼容 |
+|------|--------------|----------------|
+| 必填红星 | 写在**显示名前**：`*长尾词`、`* 名称`（表单标签同此） | **前缀 / 后缀** `*` / `＊` 都要剥掉后再对 `display_name`；**禁止**只 `removesuffix("*")` |
+| lookup / 关联列 | 单元格常为 `{value} · {label}`，如 `157 · 波兰小包专线` | 取前导整数写库；勿要求用户只填纯数字 |
+| 示例行 | 单元格以 `【示例】` 开头 | 整行跳过，勿当业务数据 |
+
+写库链路：宿主面板只把 **`filePath` + `onError`** 交给技能；**字段映射下拉结果不传入 CLI**。技能必须自己读文件、洗表头、映射列。预览「看起来有字」不等于技能已认到必填列——只剥后缀 `*` 时，前缀模板会导致「xxx不能为空」。
+
+**推荐实现：** 直接复用模板内 [`scripts/service/table_file_import.py`](../scripts/service/table_file_import.py)（`normalize_header` / `optional_int` / `load_table_rows`）。Action 文案里写「表头：名称（可带前/后缀*）」即可，**不要**再写死「表头：名称*」误导后人。
+
 ### 示例：create
 
 ```json
@@ -437,7 +451,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - 点默认「新增/编辑/删除」时走该 Action 的 `interaction`（create/update 常用 `form`；delete 常用 `confirm`）。
 - 点默认「导入」时**固定**打开宿主导入面板；确认后若有 `replaces:import` 则调用该 Action（`interaction` 不决定是否再弹技能表单）。
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
-- `import` 约定：`filePath`（或 `file`）+ 可选 `onError`（`skip`/`abort` 或上例中文枚举）；技能自行解析文件与表头。
+- `import` 约定：`filePath`（或 `file`）+ 可选 `onError`（`skip`/`abort` 或上例中文枚举）；技能自行解析文件与表头（须兼容宿主前缀 `*` 与 lookup `编号 · 名称`，见上文「导入表头与 lookup 单元格」）。
 - 整表 `_jiangchang_tables.readonly=1` 时仍隐藏宿主默认新增/编辑/导入与直写删除；**若声明了 `replaces: delete`，宿主仍显示「删除」并走技能 CLI**（不直写 SQLite）。
 - **列元数据复用**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与列上 **options**（静态枚举 `options_json` **数组**，或已解析的 lookup）：
   - 优先让属性名 = 物理列名（如 `carrier_code` / `platform_key`）；

references/SCHEMA.md

@@ -38,6 +38,8 @@
 - 可在技能安装/更新成功后静默调用 `python scripts/main.py init-db` 做幂等 ensure（内部即 `init_db()`）；失败不影响安装结果
 - 若技能启用了单元格呈现（见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)），读取旁路呈现数据并为格子 / 行 / 列 / 区域映射语义样式（`tone`）；不猜测业务规则；整行色只涂表格行，不铺到详情字段
 - **导入模板下拉（宿主能力）**：下载「Excel 模板」时，宿主按本表可导入列的元数据自动加 Excel 数据有效性下拉——凡列已有可选集合（`options_json` 静态枚举、schema 已解析的 lookup 选项、未写 options 的 `boolean` 默认「是/否」等）即加下拉；无选项的列仍为自由文本。下拉展示 **label**；导入写库时宿主（或 `replaces: import` 技能）再 **label → value**。CSV 模板**不能**带下拉，可选值仍写在导入弹窗「可导入字段说明」与 Excel「填写说明」页。技能**无需**自备带下拉的模板文件；把字段选项声明在 `_jiangchang_columns` 即可让所有技能受益。宿主不按技能名写死「只支持某几种业务字段」。
+- **导入模板表头必填标记（宿主能力）**：Excel/CSV 表头对必填列统一加**前缀**红星（`*显示名` / `* 显示名`），与新增表单标签一致；**不是**后缀 `显示名*`。走 `replaces: import` 的技能必须按 [`ACTIONS.md`](ACTIONS.md)「导入表头与 lookup 单元格」剥前/后缀 `*` 后再对 `display_name`；推荐复用 [`scripts/service/table_file_import.py`](../scripts/service/table_file_import.py)。
+- **导入模板 lookup 单元格**：用户从下拉选中的值常以 `{value} · {label}` 写入表格（与列表展示一致）。`replaces: import` 技能解析关联列时须能从该展示串取出编号（`optional_int`），不能只接受纯数字。
 
 ## 初始化入口
 

scripts/service/table_file_import.py

@@ -0,0 +1,216 @@
+"""解析数据管理导入用的 Excel / CSV（中文表头、【示例】行跳过）。
+
+实现 ``replaces: import`` 时请复用本模块，勿只认「后缀 *」表头。
+
+宿主契约（须兼容）：
+
+- 必填红星写在显示名前：``*长尾词`` / ``* 名称``（旧技能文档可能写 ``名称*``）
+- lookup 单元格可能是 ``157 · 波兰小包专线``（``{value} · {label}``），不只是纯数字
+- 以 ``【示例】`` 开头的单元格所在行应跳过
+"""
+
+from __future__ import annotations
+
+import csv
+import re
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+EXAMPLE_MARKER = "【示例】"
+DATA_SHEET_NAMES = ("数据", "Sheet1", "sheet1")
+
+
+def normalize_on_error(raw: Optional[str]) -> str:
+    text = str(raw or "").strip().lower()
+    if text in {
+        "abort",
+        "stop",
+        "立即停止，不再导入后续行",
+        "立即停止",
+        "停止",
+    }:
+        return "abort"
+    # Chinese default / skip variants
+    return "skip"
+
+
+def normalize_header(header: str) -> str:
+    """归一化导入表头。
+
+    宿主模板把必填红星写在名称前（``*长尾词`` / ``* 长尾词``）；
+    旧技能文档常用后缀（``长尾词*``）。两侧都要认。
+    """
+    text = str(header or "").strip().replace("\ufeff", "")
+    for _ in range(4):
+        prev = text
+        text = text.strip()
+        for star in ("*", "＊"):
+            text = text.removeprefix(star).removesuffix(star).strip()
+        for marker in ("（必填）", "(required)"):
+            text = text.removeprefix(marker).removesuffix(marker).strip()
+        if text == prev:
+            break
+    return text
+
+
+def _is_example_row(cells: Iterable[Any]) -> bool:
+    for cell in cells:
+        text = str(cell or "").strip()
+        if text.startswith(EXAMPLE_MARKER):
+            return True
+    return False
+
+
+def _cell_str(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value).strip()
+
+
+def map_headers(
+    headers: list[str],
+    aliases: dict[str, tuple[str, ...]],
+) -> dict[str, int]:
+    """aliases: field_name -> accepted Chinese/English header names."""
+    normalized = [normalize_header(h) for h in headers]
+    mapping: dict[str, int] = {}
+    for field, names in aliases.items():
+        accepted = {normalize_header(n) for n in names}
+        accepted.add(normalize_header(field))
+        for index, header in enumerate(normalized):
+            if header in accepted:
+                mapping[field] = index
+                break
+    return mapping
+
+
+def rows_as_dicts(
+    headers: list[str],
+    data_rows: list[list[Any]],
+    *,
+    aliases: dict[str, tuple[str, ...]],
+) -> list[dict[str, str]]:
+    mapping = map_headers(headers, aliases)
+    if not mapping:
+        raise ValueError("未识别到有效表头，请使用技能模板或中文列名")
+    out: list[dict[str, str]] = []
+    for row_index, raw in enumerate(data_rows, start=2):
+        if _is_example_row(raw):
+            continue
+        if not any(_cell_str(c) for c in raw):
+            continue
+        item: dict[str, str] = {"_row": str(row_index)}
+        for field, col in mapping.items():
+            item[field] = _cell_str(raw[col] if col < len(raw) else "")
+        out.append(item)
+    return out
+
+
+def read_csv_matrix(path: Path) -> tuple[list[str], list[list[str]]]:
+    raw = path.read_bytes()
+    text = raw.decode("utf-8-sig")
+    try:
+        dialect = csv.Sniffer().sniff(text[:4096], delimiters=",\t;")
+    except csv.Error:
+        dialect = csv.excel
+    reader = csv.reader(text.splitlines(), dialect)
+    rows = [list(r) for r in reader]
+    if not rows:
+        raise ValueError("CSV 为空")
+    return [str(c) for c in rows[0]], rows[1:]
+
+
+def read_xlsx_matrix(path: Path) -> tuple[list[str], list[list[Any]]]:
+    try:
+        from openpyxl import load_workbook
+    except ImportError as exc:
+        raise ValueError("读取 Excel 需要 openpyxl，请安装依赖或另存为 CSV 后再导入") from exc
+
+    wb = load_workbook(path, read_only=True, data_only=True)
+    try:
+        sheet = None
+        for name in DATA_SHEET_NAMES:
+            if name in wb.sheetnames:
+                sheet = wb[name]
+                break
+        if sheet is None:
+            # Prefer first non-guide sheet
+            for name in wb.sheetnames:
+                if name not in ("填写说明",):
+                    sheet = wb[name]
+                    break
+        if sheet is None:
+            raise ValueError("Excel 中没有可用工作表")
+        matrix: list[list[Any]] = []
+        for row in sheet.iter_rows(values_only=True):
+            matrix.append(list(row))
+        if not matrix:
+            raise ValueError("Excel 数据表为空")
+        headers = [_cell_str(c) for c in matrix[0]]
+        return headers, matrix[1:]
+    finally:
+        wb.close()
+
+
+def load_table_rows(
+    file_path: str,
+    *,
+    aliases: dict[str, tuple[str, ...]],
+) -> list[dict[str, str]]:
+    path = Path(file_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"文件不存在：{path}")
+    suffix = path.suffix.lower()
+    if suffix in {".xlsx", ".xlsm"}:
+        headers, data = read_xlsx_matrix(path)
+    elif suffix in {".csv", ".txt"}:
+        headers, data = read_csv_matrix(path)
+    else:
+        raise ValueError("仅支持 .xlsx / .csv 文件")
+    return rows_as_dicts(headers, data, aliases=aliases)
+
+
+_STATUS_ALIASES = {
+    "active": "active",
+    "启用": "active",
+    "archived": "archived",
+    "停用": "archived",
+    "pending_review": "pending_review",
+    "待确认": "pending_review",
+    "approved": "approved",
+    "已采用": "approved",
+    "skipped": "skipped",
+    "已跳过": "skipped",
+    "pending": "pending",
+    "待生成": "pending",
+    "generated": "generated",
+    "已生成": "generated",
+    "failed": "failed",
+    "失败": "failed",
+}
+
+
+def map_status(raw: str, *, allowed: set[str], default: str) -> str:
+    text = str(raw or "").strip()
+    if not text:
+        return default
+    key = _STATUS_ALIASES.get(text) or _STATUS_ALIASES.get(text.lower()) or text
+    return key if key in allowed else default
+
+
+def optional_int(raw: str) -> Optional[int]:
+    """解析编号；兼容宿主 lookup 展示值 ``157 · 波兰小包专线``。"""
+    text = str(raw or "").strip()
+    if not text or text.lower() in {"null", "none", "undefined"}:
+        return None
+    if re.fullmatch(r"-?\d+", text):
+        value = int(text)
+        return None if value <= 0 else value
+    # Host lookup labels: "157 · 名称" / "157·名称" / "157 - 名称"
+    matched = re.match(r"^(-?\d+)\s*[·•\-—|｜]\s*\S", text)
+    if matched:
+        value = int(matched.group(1))
+        return None if value <= 0 else value
+    raise ValueError(f"编号必须是整数：{text}")

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.125"
+SKILL_VERSION = "1.0.126"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

tests/test_development_policy_guard.py

@@ -241,6 +241,8 @@ LOGGING_006_EXEMPT_BASENAMES = frozenset(
         "task_run_support.py",
         "entitlement_service.py",
         "sibling_bridge.py",
+        # Pure Excel/CSV header helpers for replaces:import; no domain side effects.
+        "table_file_import.py",
     }
 )
 

tests/test_docs_standards.py

@@ -382,6 +382,10 @@ class TestDocsStandards(unittest.TestCase):
             "drop_deprecated_user_table",
             "孤儿物理表",
             "_jiangchang_grid_presentation",
+            "导入模板表头必填标记",
+            "*显示名",
+            "table_file_import.py",
+            "导入模板 lookup 单元格",
         ):
             self.assertIn(marker, text, msg=f"SCHEMA.md missing {marker!r}")
 
@@ -432,8 +436,21 @@ class TestDocsStandards(unittest.TestCase):
             "visibleWhen",
             "grid_help",
             "列筛选",
+            "导入表头与 lookup 单元格",
+            "table_file_import.py",
+            "*长尾词",
+            "{value} · {label}",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("A4-14", checklist)
+        self.assertIn("table_file_import.py", checklist)
+        self.assertTrue(
+            os.path.isfile(
+                os.path.join(get_skill_root(), "scripts/service/table_file_import.py")
+            ),
+            msg="scripts/service/table_file_import.py missing",
+        )
         self.assertTrue(
             os.path.isfile(
                 os.path.join(get_skill_root(), "assets/examples/lookup-skill-cli.action.example.json")

tests/test_table_file_import.py

@@ -0,0 +1,67 @@
+"""宿主导入模板表头 / lookup 展示值契约（replaces:import）。"""
+
+from __future__ import annotations
+
+import csv
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class TableFileImportTests(unittest.TestCase):
+    def test_normalize_header_host_leading_and_legacy_trailing_star(self) -> None:
+        from service.table_file_import import map_headers, normalize_header
+
+        self.assertEqual(normalize_header("*长尾词"), "长尾词")
+        self.assertEqual(normalize_header("* 长尾词"), "长尾词")
+        self.assertEqual(normalize_header("长尾词*"), "长尾词")
+        self.assertEqual(normalize_header("＊关键词＊"), "关键词")
+        self.assertEqual(normalize_header("*关键词（必填）"), "关键词")
+        self.assertEqual(normalize_header("名称"), "名称")
+
+        aliases = {
+            "phrase": ("长尾词", "phrase", "问题"),
+            "keyword_id": ("所属关键词", "keyword_id", "关键词编号"),
+        }
+        mapping = map_headers(["*长尾词", "所属关键词"], aliases)
+        self.assertEqual(mapping.get("phrase"), 0)
+        self.assertEqual(mapping.get("keyword_id"), 1)
+
+        mapping_legacy = map_headers(["长尾词*", "所属关键词"], aliases)
+        self.assertEqual(mapping_legacy.get("phrase"), 0)
+
+    def test_optional_int_accepts_lookup_display_label(self) -> None:
+        from service.table_file_import import optional_int
+
+        self.assertEqual(optional_int("157"), 157)
+        self.assertEqual(optional_int("157 · 波兰小包专线"), 157)
+        self.assertEqual(optional_int("157·波兰小包专线"), 157)
+        self.assertEqual(optional_int("2 · 通用私信-留资"), 2)
+        self.assertIsNone(optional_int(""))
+        with self.assertRaises(ValueError):
+            optional_int("波兰小包专线")
+
+    def test_load_table_rows_skips_example_and_maps_leading_star(self) -> None:
+        from service.table_file_import import load_table_rows
+
+        aliases = {
+            "phrase": ("长尾词",),
+            "keyword_id": ("所属关键词",),
+        }
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "rows.csv"
+            with path.open("w", encoding="utf-8-sig", newline="") as fh:
+                writer = csv.writer(fh)
+                writer.writerow(["*长尾词", "所属关键词"])
+                writer.writerow(["【示例】示例长尾词", "152 · 示例"])
+                writer.writerow(["波兰小包专线怎么选", "157 · 波兰小包专线"])
+
+            rows = load_table_rows(str(path), aliases=aliases)
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(rows[0]["phrase"], "波兰小包专线怎么选")
+            self.assertEqual(rows[0]["keyword_id"], "157 · 波兰小包专线")
+            self.assertEqual(rows[0]["_row"], "3")
+
+
+if __name__ == "__main__":
+    unittest.main()