Files
AgentLab/backend/app/memory/parsing.py
T
ThearchyHelios 7b04162540 Excel/CSV 变成能查的表、PPT 读得进来、跑挂了能接着跑、文档和工具有了地址
四件事,其中 Excel 那条不是"多支持一种格式",是补一个和地基冲突的缺口。

**Excel / CSV → 可以用 SQL 查的表。**

这个项目有条不可回退的决策:叙述层无算术权限,所有算术下沉到 SQL 或口径卡,
叙述只能引用(engine/issuance.py)。表格传进知识库只能被切块检索,数字就成了
模型从片段里"读"出来的——复核层拦得住凭空多出的数字,拦不住"从一堆片段里
读错了一格"。所以表格必须变成表。

不新增数据源类型:kind='sqlite' 早就支持,build_url 拿 database 当文件路径。
落成 .db 文件再建一条 DataSource 指过去,下游一行都不用改——SQL 守卫、结构
探查、db_query__<name> 工具、查询快照进工件库、Copilot 的数据源清单,全都白拿。
建表走 sqlite3 直连而不是 run_query:guard 的 _ALWAYS_DENIED 里有 create,
那是对的(模型不该能建表),而导入是我们自己发起的可信操作。

四个语义是这块的全部分量:

- **类型要推,不能全存 TEXT。** SQLite 是动态类型,但列亲和性决定排序和比较:
  整数列落成 TEXT 的话 '10' < '9',SUM() 在混入空串时静默出错,而没有任何
  地方会报。逐列扫描推断 INTEGER/REAL/TEXT,空单元格存 NULL 不存 "",
  日期存 ISO(字典序恰好等于时间序)。测试里那条 ORDER BY 要是 9<10 而不是
  '10'<'9',守的就是整块的意义。
- **表头取第 1 行,但不猜。** 不做"自动找表头"的启发式:猜错的表现是列名变成
  一行数据,没有任何征兆,直到某天有人发现汇总一直少一行。改成 header_row
  可填,并把推断出的列名和类型当场回显——错了一眼看见。
- **同名重传原地替换,id 和 name 都不变。** 名字会成为工具名(db_query__sales)
  而工具名写进了保存过的图,另起一个 sales_2 等于悄悄让那些图失效。
- **中文原样保留。** 一开始把 sheet 名清洗成了 ASCII,结果「明细」「汇总」都变成
  sheet、sheet_2,模型和用户都认不出哪张是哪张——而 SQLite 的标识符本来就允许
  非 ASCII,那道清洗纯属自找麻烦。现在只替换会断句的空白和标点。

实测:两 sheet 的中文 xlsx → 两张表,金额列 INTEGER,跨表 JOIN + SUM 跑通,
Copilot 的工具清单里带着表名。CSV 按 utf-8-sig / utf-8 / gb18030 依次试——
GBK 的 CSV 是 Excel 另存为的默认行为,按 UTF-8 读会得到乱码列名,而乱码不报错。

知识库那边顺手改了指路:传 .xlsx/.csv 进去不再说"不是 UTF-8 文本",
而是告诉你该传到数据源那边、以及为什么。

**PPT。** 文本框和表格分开取(表格的 has_text_frame 是 False),幻灯片之间
留空行当段落边界。.ppt/.doc/.xls 这些老二进制格式认出来再拒,说清楚"另存为
新格式"——以前它们会掉进"不是 UTF-8 文本"那个兜底,对着一个 .ppt 说这话,
用户根本不知道该怎么办。

**问数据页的「接着跑」。** 挂了那一轮不该只剩一行红字:断点一直在 checkpoint
里躺着。按钮挂在 approvalsFor 那个每轮插槽里(本来就托着「看执行过程」和
「跑一下」)。不带图——问数据页改不了图,这里就是"用原来的配置重试失败的
那一步",配置本身错了要到画布上改。实测:续的是同一次运行(8→13 条事件),
只跑了 lp 往后,轨迹里有 run.resumed。

**文档 / 工具的地址。** /knowledge/kb/:docId 是新页面——文档原来连详情视图都
没有,而切块这层做了不少事(按行边界留重叠、跨块续表头),结果一处都看不见。
现在逐段列出来带字数和 token 数,还标出"这份文档里混着两个模型建的向量"
(换模型只重建了一部分时真会发生,而那会让这部分内容悄悄退回关键词检索)。
新增 GET /kb/documents/{id}。工具那边 tab key 从 tools 改成 library,
否则地址是 /tools/tools/<id>。

验证:后端 265 passed(新增 test_tabular.py 16 条);tsc 干净;三个 check 全过,
check-ui 补了文档/工具两节;四块都在真浏览器/真后端上端到端跑过。
开发库里造的演示数据源、会话和运行已清干净。
2026-09-20 16:19:07 +08:00

188 lines
7.6 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""把上传的文件变成文本。
在此之前 upload 只接受 UTF-8:PDF 传上去直接 415,而 mime 字段记了却从不
参与任何判断。知识库里最常见的恰恰是 PDF 和 Word。
PDF/DOCX 的解析库走可选依赖(pyproject 的 [docs]),和 [db]、[microvm] 一样
——它们加起来几十兆,而只用纯文本的人不该为此付出安装时间。没装时给的报错
要能照着做,不是一句 ImportError。
HTML 用已经在依赖里的 beautifulsoup4,不额外引入东西。
"""
from __future__ import annotations
import io
import re
#: 认得出的扩展名 → 处理方式。mime 不可靠(浏览器给 .md 报 application/octet-stream)
_PDF = {".pdf"}
_DOCX = {".docx"}
_PPTX = {".pptx"}
_HTML = {".html", ".htm"}
#: 表格数据。它们有更好的去处——数据源那条路会把它变成可以真查的表,
#: 而传进知识库只能当文本检索:数字是模型"读"出来的不是"算"出来的,
#: 而这个项目的地基恰恰是"所有算术下沉到 SQL 或口径卡"(见 engine/issuance.py)
_TABULAR = {".xlsx", ".xls", ".csv", ".tsv"}
#: 老的二进制 Office 格式。解析它们要装 libreoffice 之类的外部转换器,代价和
#: 收益不成比例——但认出来并说清楚"另存为新格式",比让用户对着 ImportError
#: 或者"不是 UTF-8 文本"发愣强得多
_LEGACY_OFFICE = {".ppt": "PowerPoint", ".doc": "Word", ".xls": "Excel"}
class UnsupportedDocument(ValueError):
"""认不出或解析不了。message 直接给用户看。"""
def _ext(filename: str) -> str:
idx = filename.rfind(".")
return filename[idx:].lower() if idx >= 0 else ""
def _from_pdf(raw: bytes) -> str:
try:
from pypdf import PdfReader
except ImportError as e:
raise UnsupportedDocument(
"要读 PDF 得先装解析库:pip install 'agentlab-backend[docs]'"
) from e
try:
reader = PdfReader(io.BytesIO(raw))
except Exception as e: # noqa: BLE001
raise UnsupportedDocument(f"这个 PDF 读不开:{type(e).__name__}: {e}") from e
# 按页拼,页与页之间留空行——切块是按段落切的,页边界正好是天然的段落边界
pages = []
for i, page in enumerate(reader.pages):
try:
pages.append(page.extract_text() or "")
except Exception: # noqa: BLE001 - 单页坏了不该毁掉整份文档
pages.append(f"(第 {i + 1} 页解析失败)")
# PDF 抽出来的每行都拖着排版留下的填充空格,不清掉会混进切块和词频统计
cleaned = []
for page in pages:
lines = [ln.rstrip() for ln in page.splitlines()]
body = "\n".join(ln for ln in lines if ln.strip())
if body:
cleaned.append(body)
text = "\n\n".join(cleaned)
if not text.strip():
raise UnsupportedDocument(
"这个 PDF 里没有可提取的文字——多半是扫描件。"
"扫描件要先过 OCR,这里不做图像识别。"
)
return text
def _from_docx(raw: bytes) -> str:
try:
import docx
except ImportError as e:
raise UnsupportedDocument(
"要读 Word 得先装解析库:pip install 'agentlab-backend[docs]'"
) from e
try:
doc = docx.Document(io.BytesIO(raw))
except Exception as e: # noqa: BLE001
raise UnsupportedDocument(f"这个 Word 文档读不开:{type(e).__name__}: {e}") from e
parts = [p.text.strip() for p in doc.paragraphs if p.text.strip()]
# 表格也要:合同、口径说明这类文档的关键信息常常整个在表里,
# 只取段落等于把它们全丢了
for table in doc.tables:
for row in table.rows:
cells = [c.text.strip() for c in row.cells if c.text.strip()]
if cells:
parts.append(" | ".join(cells))
text = "\n\n".join(parts)
if not text.strip():
raise UnsupportedDocument("这个 Word 文档里没有文字内容")
return text
def _from_pptx(raw: bytes) -> str:
try:
from pptx import Presentation
except ImportError as e:
raise UnsupportedDocument(
"要读 PowerPoint 得先装解析库:pip install 'agentlab-backend[docs]'"
) from e
try:
deck = Presentation(io.BytesIO(raw))
except Exception as e: # noqa: BLE001
raise UnsupportedDocument(f"这个 PowerPoint 读不开:{type(e).__name__}: {e}") from e
slides: list[str] = []
for page in deck.slides:
parts: list[str] = []
for shape in page.shapes:
# 表格和文本框要分开取:一张幻灯片的关键信息常常整个在表里,
# 而 has_text_frame 对表格是 False
if getattr(shape, "has_table", False):
for row in shape.table.rows:
cells = [c.text.strip() for c in row.cells if c.text.strip()]
if cells:
parts.append(" | ".join(cells))
elif getattr(shape, "has_text_frame", False):
text = shape.text_frame.text.strip()
if text:
parts.append(text)
if parts:
slides.append("\n".join(parts))
# 幻灯片之间留空行。和 PDF 按页拼是同一个道理:页/片的边界本来就是
# 天然的段落边界,而切块是按段落切的
text = "\n\n".join(slides)
if not text.strip():
raise UnsupportedDocument(
"这个 PowerPoint 里没有可提取的文字——多半整页都是图片。"
"图里的字要先过 OCR,这里不做图像识别。"
)
return text
def _from_html(raw: bytes) -> str:
from bs4 import BeautifulSoup
soup = BeautifulSoup(raw.decode("utf-8", errors="replace"), "html.parser")
for tag in soup(["script", "style", "nav", "footer"]):
tag.decompose()
text = soup.get_text("\n")
# 连续空行压成一个:HTML 转出来到处是空行,会把切块的段落判断搅乱
return re.sub(r"\n{3,}", "\n\n", text).strip()
def extract(raw: bytes, filename: str, mime: str = "") -> str:
"""文件字节 → 文本。认不出就按 UTF-8 文本试。"""
ext = _ext(filename)
if ext in _PDF or mime == "application/pdf":
return _from_pdf(raw)
if ext in _DOCX or "wordprocessingml" in mime:
return _from_docx(raw)
if ext in _PPTX or "presentationml" in mime:
return _from_pptx(raw)
if ext in _HTML or mime == "text/html":
return _from_html(raw)
if ext in _TABULAR:
raise UnsupportedDocument(
f"{filename} 是表格数据,请传到「设置 → 数据源」那里——"
"它会变成一张可以用 SQL 查的表,数字是算出来的、能追溯到哪条查询。"
"传进知识库只能当文本检索,模型只是把数字读出来,容易读错也查不出来源。"
)
if ext in _LEGACY_OFFICE:
# 认出来再拒,而不是让它掉进下面那个"不是 UTF-8"的兜底——
# 后者对着一个 .ppt 说"不是文本",用户根本不知道该怎么办
raise UnsupportedDocument(
f"读不了 {filename}:{_LEGACY_OFFICE[ext]} 的老二进制格式({ext})需要"
f"外部转换器才能解析。请在 Office 里另存为 {ext}x 再传。"
)
try:
return raw.decode("utf-8")
except UnicodeDecodeError as e:
raise UnsupportedDocument(
f"读不了 {filename or '这个文件'}:它不是 UTF-8 文本,"
f"也不是认得出的 PDF / Word / PowerPoint / HTML。"
) from e