产品报价助手（Product Quote）

目的

把公司全部产品信息与价格表沉淀为一份结构化「产品主数据」文件，作为工具的长期记忆；并封装三类可复用动作：资料查询发送、按需导出价格表、竞品报价替换。让用户在对话中一句话即可调取资料或生成报价单。

何时使用

• 用户要"查/发某个产品的资料、卖点、参数"。
• 用户要"导出一份价格表，列要包含数量、价格、运营价扣率等信息"。
• 用户上传了一份竞品/友商的报价表，要求"换成我们自己的产品，按 X 折生成新报价"。
• 用户要做家装米家全屋智能报价或酒店客房智能报价（需要按报价方法论配置方案）。
• 用户要"查某个产品的 3C 证书 / 质检报告（型式试验报告）"，或要认证资质文件发给客户/伙伴。
• 用户要维护、更新公司产品库。

工作原理

工具的数据核心是一份 产品主数据 Excel（字段规范见 references/data_schema.md）。所有动作都从该文件读取，因此"长期记忆"= 这份文件；"学习"= 用户把产品填进去。核心逻辑由 scripts/build_quote.py 确定性执行，避免每次重写代码。

资产与脚本

• assets/产品主数据模板.csv —— 空白主数据模板（含示例行，删除即可；UTF-8 BOM，Excel 可直接打开）。
• assets/竞品报价导入模板.csv —— 竞品报价导入模板。
• 说明：技能市场禁止上传二进制文件，故模板以 CSV 文本提供；需要 xlsx 版模板时运行 scripts/make_templates.py 现场生成。引擎同时支持 xlsx 与 csv 主数据。
• scripts/build_quote.py —— 引擎，支持五种模式：
• export 导出价格表
• replace 竞品替换报价
• lookup 命令行查询（核对用）
• pack 把产品主数据打包成便携数据包（.zip，可复制给同事）
• import 导入数据包，一键在本地复原产品主数据（.xlsx）
• scripts/extract_ppt.py —— 从 PPT/PDF 抽取文字与表格为中间 CSV（乱数据录入用）。
• scripts/merge_master.py —— 把归一化后的产品 CSV 合并进主数据（新增/更新，自动算扣率）。
• scripts/make_templates.py —— 重新生成上述两份模板。

运行环境依赖

• 引擎脚本依赖 openpyxl；处理 PPT/PDF 还依赖 python-pptx、pdfplumber。
• 运行前若缺失，先安装：pip install openpyxl python-pptx pdfplumber。
• references/data_schema.md —— 字段定义、折扣规则、维护方法。

数据录入 / 学习（解析图片、PPT、PDF、表格等乱数据）

用户常把产品资料以图片、PPT、PDF、Word、Excel 等形式发来，且格式杂乱。本技能负责把它们解析、归一化后写入产品主数据（即"学习"）。流程：

1. 接收原始材料：图片直接由智能体用多模态读取；PPT/PDF 用 scripts/extract_ppt.py 抽文字与表格到中间 CSV；xlsx/csv/docx 直接读取。
2. 归一化：智能体把抽取出的内容整理成一份归一化 CSV，列尽量对齐主数据表头：
   产品编号,产品名称,类别,规格型号,单位,标准零售价,运营价,成本,产品资料/卖点,备注。
   - 价格里的"¥、元、逗号"在 merge_master.py 中会自动清洗。
   - 没有"产品编号"的，由智能体按"类别+名称"规则补一个稳定编码（如 空调-KFR72）。
   - 运营价扣率(%) 不填，脚本自动算。
3. 合并入库：运行 scripts/merge_master.py --master <主数据.xlsx> --input <归一化.csv>。
   同一"产品编号"已存在则更新，否则追加。输出新增/更新条数。
4. 核对：合并后抽查首行金额与扣率；有歧义的产品向用户确认，不要臆造价格。

中间文件建议放在 <workspace>/product-data/提取/ 下，避免污染主数据。

性能规范（重要：决定每次出结果的速度）

工具脚本本身很快（万行主数据查询/导出约 3 秒）。慢的根源几乎总是用法问题，遵守以下规则：

1. 禁止用 Read 工具直接读整个主数据文件。主数据有上万行，整读进对话上下文会让回合从秒级变成分钟级。查询一律走 lookup 命令。
2. 查询/发送资料必须用 lookup（一次命令完成筛选+紧凑输出）：
   bash python scripts/build_quote.py lookup --master <主数据.xlsx> --keyword <关键词> [--category <类别>] [--limit 30]
   - 默认只显示前 30 条、6 个核心列；不够就加 --limit 或用 --fields 指定列，不要去全量读取。
   - 关键词要具体（型号/编号优先），避免"开关"这种命中上千条的词。
3. 一次调用拿全结果：export/replace 都是一条命令完成，不要拆成多轮对话。
4. pack 只在需要分享数据库时执行（打包万条数据+数千张图约需 30-60 秒），日常查询不要 pack。
5. 需要"发送产品资料（含图片）"时：先 lookup --keyword X --fields "产品编号,产品名称,产品资料/卖点,图片" 拿到图片路径，再按路径读取对应的那几张图，不要读整个图片目录。

使用流程

0. 首次初始化产品库

若用户还没有主数据文件：可直接把 assets/产品主数据模板.csv 另存为 <workspace>/product-data/产品主数据.xlsx（或 .csv，引擎两者都支持），删除示例行后填入真实产品与价格；也可运行 scripts/make_templates.py 生成带格式的 xlsx 模板。后续所有动作以该文件为 --master。

1. 查询 / 发送产品资料

• 用 lookup 模式在命令行核对，或直接读取主数据文件、按关键词/类别筛选后在对话中回复产品名称、规格、卖点。
• 产品状态检查：主数据含「产品状态」列（在销 / 在销(BTO) / 在销(定做) / 停产停销）。发送资料或报价时，若命中"停产停销"，必须提示该产品已退市、勿再报价；"在销(BTO)/在销(定做)"需提示交期与公司确认。
• 发送资料含图片：主数据新增「图片」列，存产品预览图的相对路径（相对主数据目录，多张以 ; 分隔，图在 <主数据目录>/图片/ 下）。回复产品资料时，除文字卖点外，一并列出该产品「图片」列指向的图片文件路径，供用户/同事直接打开查看。无图片的产品只回文字。
• 如需"发送资料"，将筛选结果整理成文字或导出为 Excel 交付。

2. 导出价格表（按用户指定列）

运行：

python scripts/build_quote.py export \
  --master <主数据.xlsx> --output <输出.xlsx> \
  --columns "产品编号,产品名称,规格型号,单位,运营价,运营价扣率(%)" \
  --category 空调        # 可选：按类别筛选
  # --keyword 关键词     # 可选：按关键词筛选

列名必须是主数据里存在的表头；默认导出全部列。把生成的 Excel 交付给用户。

3. 竞品替换报价

1. 让用户按 assets/竞品报价导入模板.csv（或运行 make_templates.py 生成的 xlsx 版）填好竞品表，关键是"对应我方产品编号"列填我方主数据里的产品编号。
2. 运行：

python scripts/build_quote.py replace \
  --master <主数据.xlsx> --input <竞品报价.xlsx> \
  --output <新报价单.xlsx> --discount 0.8 --base operation

• --discount 0.8 = 8 折；--base operation 以运营价为基价（默认），standard 以标准价为基价。
  3. 检查输出里的"匹配状态"列：若有"未匹配"，提示用户核对产品编号。把新报价单交付。

4. 分享 / 复制数据库给同事（数据包）

技能（脚本+模板）与产品数据库是分离的：同事从技能市场装到的只是脚本，本地没有任何产品数据。要把你维护好的产品库复制给同事，用"数据包"机制：

1. 打包（你端）——把主数据压成一个便携 .zip（内含 产品主数据.csv + manifest.json 版本清单 + 导入说明.md + 图片/ 预览图目录）：
   bash python scripts/build_quote.py pack \ --master <主数据.xlsx> --output <产品数据包_日期.zip>
   主数据为 CSV 纯文本；图片只打包「图片」列实际引用的压缩预览图（默认 900px，控制包体），可经网盘/企业微信发送；数据包含二进制图片是允许的（数据包不传 SkillHub，仅技能包禁二进制）。
2. 发送：把该 .zip 原样发给已安装本技能的同事。
3. 导入（同事端）——一条命令在本地复原 产品主数据.xlsx 并解出 图片/：
   bash python scripts/build_quote.py import --pack <产品数据包_日期.zip> --dest ./product-data
   默认导入到当前目录 product-data/（产品主数据.xlsx 可直接用 Excel/WPS 打开编辑，图片/ 预览图与「图片」列路径一一对应），并附 manifest.json 记录版本/条数/图片数/字段。
4. 同事随后即可 lookup / export / replace，且"发送资料"能带出产品图片；其后续增补的数据也可再次 pack 回传，实现数据库（含图片）的复制与同步。

> 注意：数据包含公司完整产品与价格，属敏感商业数据，分享范围由你自行把控。

报价方法论（生成任何报价前必读）

完整原则清单见 references/quote-principles.md（由用户逐条教学沉淀，持续迭代）。生成任何报价前，必须先遵守以下原则，再用上面的引擎出表：

• P1 基价与折扣口径：目录价/运营价/扣率以产品主数据为唯一事实源；默认报价单价 = 目录价 × 5折（P17），用户可逐单指定其他折扣覆盖；未指定且无 P17 口径前只列目录价与运营价，不擅自生成成交价。
• P2 方案型 BOM：全屋智能按空间/功能整理 BOM，先列方案清单再逐项落到主数据编码。
• P3 报价边界：明确"含/不含"（不含施工安装、线缆、底盒等），单列说明。
• P4 特殊产品：BTO/定做/停产停销/缺价产品必须显式标注（"待定"或提示交期），不得静默计入合计。
• P5 输出物规范：PDF（发客户，横版、含产品图）+ 可编辑 XLSX（嵌入图片）双版本交付。
• P6 校验自检：出表后核验页数/图片嵌入数/合计金额；价格缺失或歧义必须提示，不臆造。
• P7 中枢网关：小米中枢网关（ZSWG01CM，运营¥330=目录¥1100 的 30%）。
• P8 小爱音箱：Xiaomi 智能音箱 Pro（运营¥280=目录¥930 的 30.11%）每单必含；<80㎡且设备<15 个由音箱兼任网关（免配 P7），大户型两者都配。
• P9 同系列配套：面板指定某系列（如 HM1），则配套插座/网络/USB/地脚灯/连体框均用同系列；同品类内部优先统一型号。
• P10 米家全屋智能强制组成：面板必须米家、网关必须有、小爱必须有、浴霸/晾衣架/门锁/传感器必须米家智能产品。
• P11 照明与供电：筒射灯默认可普通（接米家开关即控，无调光调色，需调光调色用户指定智能款）；灯带需变压器（每米 10W、变压器标称功率八折选型：标称 ≥ 米数×10÷0.8）；智能灯带同理；灯带电源用 P8 系列低压开关电源（97403374~78，已录主数据，运营价=目录价50%），灯带 10米/卷。
• P12 关键设备多型号对比选型：门锁/浴霸/晾衣架须列出该品类全部适用型号（在销+米家智能），按价格与参数/功能差异做对比总结供客户选择，单列"选型对比"区。
• P13 报价单呈现风格：单一明细表（图片|名称|代码|备注|规格|数量|单价|单项合计）+ 末尾合计行；默认只给最终单价、不堆砌多价列；规格列写全参数；外采品标注"外采"。
• P14 酒店报价专用：酒店只用 B1 系列涂鸦蓝牙方案（禁用 zigbee），所有面板必须 B1 系列；网关两方案——默认小智管家（98314031 小智智能音箱 PRO 酒店版，可兼蓝牙网关），备选小度大金刚（98314001）+蓝牙网关（98313038，目录¥150/运营¥45=30%）；筒射灯/灯带默认普通（呼应 P11）；以单间客房为单元按房间数汇总；呈现风格沿用 P13。
• P15 电动窗帘：米家项目每窗标配电动窗帘——布帘+纱帘各一条轨道各一台电机（每窗 2 电机+2 轨道）；电机 98307133 隐藏式蓝牙mesh（263.33/79=30%）；轨道 98306005 按米计价（每米运营¥35=目录¥116.67 的 30%）；窗帘布/纱外采不计入。
• P16 报价图片选用规范：产品图必须"对、清、准"——直接产品图优先；无图从海报裁特写（严禁整张海报）；严禁跨品类放错图（浴霸≠开关面板/电源图）；无图留"—"并告知用户；同外观系列可共用图。出表前逐项核对图片与产品对应关系。
• P17 报价基准价口径：默认报价单价 = 目录价 × 5折（目录价 × 0.5），适用所有产品；目录价缺失按运营价兜底再 ×0.5；灯带按卷价折算每米（目录¥88/10米≈¥8.8/米 → 报¥4.4/米）后再按口径打折；选型对比区"报价"列同步展示同口径价。用户可逐单指定其他折扣覆盖默认值。

3C 证书 / 质检报告查询（v1.7.0 新增）

给定产品型号，定位其 3C 证书与型式试验报告（质检报告），交付给客户/伙伴作资质证明。完整方法论（证书分类、编号规则、两步法、实战案例、钉钉直连实测命令与空间 ID）见 references/cert-query.md，查询前必读。

铁律（违反必漏检）

1. 禁止扫描 PDF 正文搜型号——证书/报告是图片型扫描件，无文本层，正文搜索必然漏检。
2. 正确入口是《认证产品一览表》索引：按型号搜（范围"工作簿/查找全部"）→ 逐条核对确切型号并读出内部编号（如 0201234）→ 用编号取文件：0201234.pdf=3C证书、0201234-X.pdf=型式试验报告、0201234-Bx.pdf=变更。
3. 证书分类：0201 插座 / 0202 开关 / 0206 安装盒外框 / 0907 USB / 1001 灯具。
4. 索引里"3C证书"行的型号列常为空，只有报告行带型号文本——证书只能靠编号定位。

数据源与多成员设计

• 首选：直连钉钉实时一览表（已绑定钉钉连接器时，用 dws CLI：dws drive list-spaces --space-type orgSpace --format json 列空间 → dws drive +list --space-id <sid> --folder-id <fid> --format json 列文件夹 → dws drive +download 下载；空间/节点 ID 见 references/cert-query.md 第五节）。钉钉上的文件以最新版为准。
• 回退：本地缓存（认证检测索引.csv + 证书/报告文件夹），结果须标注"基于历史快照"。
• 钉钉授权是账号级的：每个成员连接自己的钉钉跑同一套查询逻辑；未连钉钉的成员用数据包本地库并向用户说明是快照数据。

注意事项

• 主数据文件是唯一事实源，价格调整只改它，不要改动技能逻辑。
• 所有金额解析失败会按 0 处理，生成后务必抽查首行金额。
• 折扣系数传入小数（0.8 而非 80），避免误用。
• 运营价扣率由脚本自动计算，模板中的公式仅为展示，以脚本输出为准。