SE - Comp Analysis

核心目标

用户给定文件路径 → 读取文档 → 提取产品手册参数 → 按产品类型分组生成竞品对比表 → 多轮自检 → 输出 .md 文件

产品类型由源文档内容决定，不预设"充电版/换电版"等固定分类。同一任务中同类型产品生成一张对比表，不同类型产品分别生成各自对比表。

---

完整工作流

Step 1 — 文件探测与格式判断

读取目标文件，判断是单文件还是文件夹。文件夹则遍历所有支持格式的文件，逐个读取。

文件格式 → 工具映射：

| 格式 | 推荐工具 | 兜底工具 | |---|---|---| | .pdf ≤10MB | xparse（xparse-parse skill） | pypdf / pdfplumber | | .pdf >10MB | pypdf 分段提取 | pdfplumber 按页提取 | | .docx | python-docx | — | | .xlsx | openpyxl 或 pandas | — | | .pptx | python-pptx | — |

xparse 限制： 免费 API 仅支持 PDF ≤10MB；付费 API ≤500MB。超出则用 pypdf 兜底。

文件大小检测：

Get-Item "文件路径" | Select-Object Length  # 字节

---

Step 2 — 内容读取

PDF（pypdf 全量提取）：

import pypdf, sys
sys.stdout.reconfigure(encoding='utf-8')
r = pypdf.PdfReader(r"文件路径")
for i, p in enumerate(r.pages):
    t = p.extract_text()
    if t and t.strip():
        print(f"=== Page {i+1} ===")
        print(t)

PDF（xparse 精确提取）：

xparse-cli.exe parse "文件路径"  # 输出包含表格结构

DOCX（python-docx）：

from docx import Document
doc = Document(r"文件路径")
for t in doc.tables:
    for row in t.rows:
        print([c.text.strip() for c in row.cells])

XLSX（openpyxl）：

import openpyxl
wb = openpyxl.load_workbook(r"文件路径")
for sheet in wb.sheetnames:
    ws = wb[sheet]
    for row in ws.iter_rows(values_only=True):
        print(row)

PPTX（python-pptx）：

from pptx import Presentation
prs = Presentation(r"文件路径")
for slide in prs.slides:
    for shape in slide.shapes:
        if hasattr(shape, "text"):
            print(shape.text)

大 PDF 分段策略（>10MB）：

# 只提取含参数表的页面（通常在靠后页面）
r = pypdf.PdfReader(r"文件路径")
total = len(r.pages)
for i in range(max(0, total-4), total):  # 最后5页
    t = r.pages[i].extract_text()
    if t.strip():
        print(f"=== Page {i+1} ===")
        print(t)

---

Step 3 — 参数提取与分类

从读取结果中提取每个产品的参数。参数分类由文档内容决定，不强制限定的分类集合。

通用标准分类（优先使用，覆盖大多数产品手册）：

| 分类 | 典型参数项 | |---|---| | 产品基础参数 | 型号、产品类型、重量、尺寸（长×宽×高）、适用范围/适配机型 | | 性能与效率 | 核心性能指标、速度、容量、功率、效率值 | | 供电与电气 | 供电方式、输入/输出电压、功耗（待机/运行/峰值） | | 防护与环境 | 防护等级、工作温度范围、存储温度、噪音等级 | | 通信与接口 | 通信方式、接口类型、数据传输协议 | | 软件与功能 | 配套软件、功能特性、二次开发接口 | | 可靠性与寿命 | 工作寿命、MTBF、检修周期、认证标准 | | 物理规格 | 安装方式、外壳材质、重量、尺寸、线缆长度 |

实际分类以源文档中出现的参数类别为准。文档中有专属分类（如"机场操控"、"换电时长"）时，保留该分类并填入对应参数。

---

Step 4 — 按产品类型分组生成对比表

遍历所有已读取的产品，按类型分组：

1. 识别产品类型： 从文档标题或参数中识别该产品属于哪个类型（如"充电版"、"换电版"、"室内型"、"室外型"等）
2. 同类型产品 → 同张表： 同一类型下所有产品合并到一张对比表
3. 异类型产品 → 分别建表： 不同类型产品各自生成独立对比表
4. 输出文件命名： {产品类型}竞品参数对比.md，如 充电版竞品参数对比.md、室外型竞品参数对比.md

输出路径： 优先使用用户指定路径；未指定则保存到用户桌面或当前工作目录。

表格结构（自适应，含以下区块，按实际参数多少选择性生成）：

一、产品基础参数
二、性能与效率
三、供电与电气
四、防护与环境
五、通信与接口
六、软件与功能
七、可靠性与寿命
八、主要亮点总结（原文出处）
九、参数差异速查

写入规范：

• 所有数据必须严格出自源文档，不推算、不假设
• 源文档未提供的参数行留空（—），不填入推算值
• 单位必须与源文档完全一致，不换算
• 同一参数项在所有产品中均无数据时，整行删除

---

Step 5 — 多轮自检（强制执行）

第一轮 — 数值完整性检查：

• 每个参数行中各产品数据是否与源文档一致
• 单位是否统一（mm ≠ m，min ≠ s，W ≠ kW）

第二轮 — 逻辑一致性检查：

• 参数数值在合理范围内（如温度最小值 < 最大值）
• 同型号产品的尺寸/重量等参数在不同来源中是否一致

第三轮 — 源文档逐条核对：

• 调出原始提取文本，逐行对照
• 重点检查：尺寸、重量、功率、性能指标等数值型参数
• 发现错误立即修正

---

质量红线

1. 禁止推算数据 — 源文档无数据则留空（—），绝不填写"典型值"或"行业平均"
2. 禁止跨产品混用参数 — A 产品的参数不许写到 B 产品行
3. 禁止在亮点总结中混入其他产品参数 — 每条亮点严格出自对应产品文档
4. 单位必须逐行核对 — mm ≠ m，min ≠ s，W ≠ kW
5. 文件写入必须使用 qclaw-text-file 技能的脚本 — 不可用内置 write 工具直接写目标文件

---

辅助脚本

• scripts/pdf_extract.py — pypdf 批量提取，支持指定页范围（负数表示倒数第N页）
• scripts/docx_extract.py — python-docx 提取，支持表格结构输出
• scripts/xlsx_extract.py — openpyxl 提取，支持多 sheet

详见各脚本文件。