template-understander 模板理解器
一次配置（入口）。用户给一张「表格模板图」或一份「Excel 表头」→ 智能体读表格、理解成用户要的「字段框」→ 产出「模板定义 JSON」→ 用户确认后存盘，供主 SKILL「表格台账生成」反复使用。
> 与主 SKILL 关系：本 SKILL 只做"理解表格→定字段"，不识别单据、不做台账。识别/导出交给主 SKILL table-ledger-assistant。
一、触发时机
第一次用 / 换一张表格 / 改模板时调用。日常记明细走主 SKILL，不要重复跑本 SKILL。
二、工作流程（用户确认门：理解不对，绝不往下）
① 询问用户：客户表格（表头图 / Excel / 老表），先上传表格
② 智能体读【客户的表格】→ 提炼字段框 → 用户确认 → 得到 columns（字段框 100% 来自这张客户表，不查模板库）
③ 展示字段框 → 【确认门】用户逐列核对，不对就改
④ 按需配导出样式 export_style（字体/底色/行高/列宽/横幅）
⑤ set_library_dir(客户项目目录) → 存「样式模板」（仅格式，不含业务字段）
⑥ 提示用户：字段框已就位，可去主 SKILL 记账
铁律（P0-4 4d）：任何客户业务结构/字段不得写回通用 模板库/；客户样式存客户自己的项目目录，也不反回来当字段来源。没有用户点头，绝不存档。
三、理解规则（读客户表 → 字段）
智能体看客户表格时，把用户"想填的每一列"提取成字段，不猜具体业务、不套行业模板。规约如下：
- 字段对象（
columns[]每项）：
json
{"key": "英文标识", "name": "中文列标题", "type": "text", "required": true}
2. type 取以下之一（决定校验/提取方式）：
| type | 含义 | 例子 |
|---|---|---|
date |
日期 | 送货日期、开单日期 |
amount |
金额 | 单价、合计 |
int |
整数 | 数量、序号 |
enum |
固定枚举（需 options 数组） |
品牌、销售员 |
text |
自由文本（默认） | 备注、型号、地址 |
3. enum 列必须带 options（该列常见取值），没有就填 text。 |
||
| 4. required：表格里每行必填的列设 true（金额/型号/日期等），可有可无设 false。 |
> 字段来源红线：columns 的每家必填来自本次客户表格的表头。下面示例仅用于演示结构/格式，其中的业务字段（品牌/型号/单价…）不是任何真实客户的字段来源，更不得写回通用模板库（P0-4）。
顶层结构（格式/演示示例）
{
"template_name": "示例样式模板",
"sheet_header": "配送台账{日期}",
"columns": [
{"key": "bdate", "name": "送货日期", "type": "date", "required": true},
{"key": "brand", "name": "品牌", "type": "enum", "options": ["美的","格力","海尔"], "required": true},
{"key": "model", "name": "型号", "type": "text", "required": true},
{"key": "price", "name": "单价", "type": "amount", "required": true},
{"key": "remark", "name": "备注", "type": "text", "required": false}
],
"export_style": {
"font_name": "微软雅黑",
"font_size": 10,
"banner_fill": "BDD7EE",
"header_fill": "2E75B6",
"row_height": 26,
"col_widths": {"C": 10, "D": 14, "F": 20}
}
}
-
sheet_header可含{日期}占位符，导出时自动替换成当天日期（没有就省略）。 -
export_style规定<b>导出格式</b>（P0-3 样式自定义）：font_name/font_size/banner_fill/header_fill/row_height/col_widths；不设则主 SKILL 回退内置软件版审美。
四、存档（确认后）— 存"客户样式模板"，不碰通用模板库
用户点头后：
from scripts.template_store import set_library_dir, save_template
set_library_dir("<客户项目目录>") # 客户样式存客户的目录，绝不写回通用 模板库/（4d）
save_template(tpl, bump=True) # 校验+版本+last_used 一次带上
-
存放位置：客户样式模板统一放客户自己的项目目录（
set_library_dir指向它），天然隔离多客户、不串数据、不污染通用模板库（P0-4 4d）。 -
通用
table-ledger-assistant/模板库/只放不涉业务的样式样张（现只有送货台账模板.json），任何客户结构不得写入。 -
改某客户样式 → 存回该客户目录，version+1（
save_template(..., bump=True)）；不要手工 Edit 丢版本（P2-3）。 -
下次同客户表格：主 SKILL 直接复用该客户目录里的字段框 + 样式，门1（确认）一次过。
五、校验（配置文件合法性）
存盘/复用前用 scripts/template_schema.py 校验，非法输出按 §9.1 自动重试一次：
from scripts.template_schema import validate_template, pprint_errors
errs = validate_template(tpl)
# errs 为空=通过；否则把 pprint_errors(errs) 展示给用户，让智能体修正后再审
常见错误：columns 为空数组、type 超纲、enum 缺 options、key 重复、缺 template_name。
六、文件清单
| 文件 | 功能 |
|---|---|
SKILL.md |
入口/理解规则/确认门（本文件） |
scripts/template_schema.py |
模板定义 JSON 校验（§9.1 重试机制） |
scripts/template_store.py |
模板落盘 + 版本/日期管理（§4.2） |
七、踩坑提醒（写进工作流）
- 字段永远来自客户的表：先读客户表头提炼字段框，不套模板、不查模板库（P0-4 4a）。
- 不理解就确认：字段框再特殊，也按"用户要填的列"理解，不套行业模板。
- enum 别乱给：只有列里有明确固定取值才给 options，否则 text，避免后续识别被卡。
- 必填优先：金额/型号/日期这类核心列 required 设 true，保证台账不出空关键格。
- 不污染通用模板库：客户结构存客户目录，
模板库/一行不写（P0-4 4d）。 - 确认门是硬性的，展示字段框后必须等用户"OK/改"，不能自己往下走。
FAQ
Q0：这个技能怎么安装？和主技能什么关系？
A：CLI 安装：python skills_store_cli.py install template-understander-ysmb；也可网页下载 zip 解压到 ~/.workbuddy/skills/。它是主技能「表格台账生成」的配套配置工具——先用它给客户表格定字段框（一次性），日常记账直接走主技能。
Q1：本 SKILL 和主 SKILL 什么关系？
A：本 SKILL 只做「读客户表头→定字段框 + 配样式」的一次性配置；识别单据、生成台账走主 SKILL table-ledger-assistant。
Q2：字段框存哪里？会不会串客户？
A：客户样式模板存客户自己的项目目录（set_library_dir 指向），天然隔离；通用 模板库/ 只放不涉业务的样式样张，任何客户结构不得写入（P0-4 4d）。
Q3：配置完主 SKILL 不认？
A：确认存档路径与主 SKILL 的 set_library_dir 一致；存盘前先用 scripts/template_schema.py 校验（errs 为空才通过）。
Q4：enum 列怎么填 options？
A：只有列里有明确固定取值才给 options，否则 type 用 text，避免后续识别被卡。
> © 2026 养生曼巴。本技能个人/小微企业日常使用免费；企业/商业用途（商用集成、再分发、打包进商业产品、批量代运营等）需授权，授权与定制入口见同作者主技能 table-ledger-assistant 或邮件 799621125@qq.com。
