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

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`），不能只接受纯数字。
 
 ## 初始化入口