acikpoz

acikpoz

将土耳其公共工程单价从 PDF 转换为可供计算的数据。

在土耳其，每项公共工程都按政府目录定价：ÇŞB （Çevre, Şehircilik ve İklim Değişikliği Bakanlığı）的 birim fiyat 手册——其中包含数千条单价 （一个 poz：代码、描述、单位和价格），估算人员、承包商和审计人员都会查阅。这些手册以长篇 PDF 的形式发布。acikpoz 会将页面还原为结构化记录，并确保过程可重复，从而让成本估算或投标准备能够通过计算完成，而不必手动抄录。

它依靠严谨的几何分析，而非语言模型：先将页面上的文字按视觉行分组，再根据页面页眉确定价格列的位置，而不是猜测固定位置。正是这一做法让它值得信赖——有些章节（例如 Sıhhi Tesisat）每行会印有两个数字，分别是真正的 Birim Fiyat 和单独的 Montaj Bedeli，简单的解析器可能会悄悄读错。acikpoz 会读取页眉，因此能读对列。

与 ihalent（用于结构化投标结果）搭配使用时，acikpoz 涵盖了土耳其公共工程经济的另一半：作为结果衡量基准的价格。

它始终遵守的唯一规则

价格只能是目录实际印在价格列中的数字。它不会强行转换、不会借用相邻条目的数字，也不会猜测。由此带来两个有意为之的结果：

• 组标题 poz——例如 EVİYELER: 这样的类别标题，其子条目才包含实际价格——本身没有价格。acikpoz 会将其 fiyat 留为 None，并标记 is_group_header。它不会凭空编造一个零。
• 目录中没有印出价格的 poz 属于缺失项，会被展示并计数，而不会被隐藏。每项结果都会报告其覆盖情况：已定价、作为标题的 poz，以及确实缺少价格的 poz 分别有多少。

成本工具的价值有一半在于拒绝编造来源中没有印出的数字。这与 andon 和 ihalent 所遵循的诚实原则相同。

安装

pip install acikpoz          # add [mcp] for the MCP server: pip install "acikpoz[mcp]"

快速开始

指定你已有的一份官方目录 PDF（acikpoz 附带解析器，不附带数据）：

acikpoz parse bf2026.pdf --pages 8-20
acikpoz parse bf2026.pdf --json > pozes.jsonl     # one poz per line, for pipelines
acikpoz parse bf2026.pdf --csv pozes.csv          # Excel-ready (utf-8-sig, Turkish text)
acikpoz parse bf2026.pdf --group 25               # only Sıhhi Tesisat pozes
acikpoz parse bf2026.pdf --priced-only            # drop headers and gaps

表格视图——这是针对已发布的 2026 年目录实际运行的结果，不是示意图：

图中有两点正是关键所在：

• 三行的价格列显示 -。目录未列出这些项目的价格，因此 acikpoz 也不会显示价格——它们会被计为缺项，而不是用相邻项目的价格填补。
• 接着，validate 会标记解析中无法确定的内容：这一页有五个单位（+2000、azami、Yapı、-30°C、2,5）其实是落入单位列的描述文本片段。有些版式的提取结果并不完美，工具会如实报告这一点，而不是交给你一张看似整洁、单位却有误的表格。

复现此结果——只需指定页面，无需其他操作：

acikpoz parse    bf2026.pdf --pages 400
acikpoz validate bf2026.pdf --pages 400

目录是由该部委提供的原始文件，在此发布。图片由 scripts/make_demo_svg.py 重新生成，该脚本会下载 PDF，并运行与 CLI 相同的代码。

等级（优秀／良好／一般／较差）是一目了然的置信度信号，类似 camelot 提供的准确度：低于 good 时，请先检查页面，再信任输出。--json 会在每次解析的结果中包含 price_parse_rate 和 grade。

也可以使用 Python：

from acikpoz import parse_catalog

result = parse_catalog("bf2026.pdf", pages=range(8, 20))
for p in result.pozes:
    if p.is_priced:
        print(p.poz_no, p.birim, p.fiyat)
print(result.to_dict()["counts"])   # priced / group_headers / price_gaps

工作原理

1. 行。 根据垂直位置将词语归入视觉行（容差为几个点），然后按从左到右的顺序排序。
2. 根据表头确定价格列。 右侧（x > 400）的 Fiyat 表头词会确定价格列的 x 坐标。左侧描述中偶然出现的“fiyat”不会被误认为价格列。
3. 单元格。 对于每个 poz 行，最左侧单元格是 poz 代码；离价格列 x 坐标最近的数字形状标记是价格；单位位于其左侧；其余部分为描述。缩进的续行会扩展当前描述（也可能包含换行后延续的价格）。
4. 分组表头。 描述以 : 结尾且没有价格的 poz 是类别标题——会被标记，而不会被视为缺项。

对比两个目录年份

目录会定期重新发布；估算人员和审计人员一直手动追踪的问题是今年的费率相较去年有何变化？ acikpoz diff 可以回答这个问题——它按 poz 代码合并两个年份，并对每项变化进行分类：

acikpoz diff bf2025.pdf bf2026.pdf --pages 8-400
acikpoz diff bf2025.pdf bf2026.pdf --tolerance 1   # hide sub-1-TL rounding noise
acikpoz diff bf2025.pdf bf2026.pdf --json

它会报告价格变动（含 Δ 和 %Δ）、新增和移除的 poz、单位变更，以及新增或失去已列价格的 poz——还会报告该年度的平均价格变化百分比。据研究所知，没有其他开源工具能对 ÇŞB 目录进行逐年差异比较。

验证解析结果

在解析后的目录用于成本估算之前，先确认数据干净会很有帮助。acikpoz validate 会对 poz 运行确定性的质量规则——不使用 ML，不修复数据，只负责指出问题：

acikpoz validate bf2026.pdf --pages 8-400
acikpoz validate bf2026.pdf --json

它会标记重复的 poz 代码、格式错误的代码、非正价格（错误），以及缺少单位或单位不在已知集合中的有价 poz（警告）。出现任何错误时，它都会以非零状态码退出，因此可以用于拦截工作流（acikpoz validate … && build-estimate）。这也体现了 acikpoz 对自身局限的坦诚：在某些章节（如 Sıhhi Tesisat）中，单位只在分组表头处列出，行项目继承该单位，因此逐行单位检测效果较弱；validate 会如实指出这一点，而不会将其隐藏。价格、poz 代码和描述仍然可靠。

将 acikpoz 用于 AI Agent

MCP 服务（pip install 'acikpoz[mcp]'，然后运行 acikpoz-mcp）会提供三种工具： parse_catalog（将 PDF 转为结构化的 poz，附带如实的覆盖情况）、diff（对比两个目录年份 → 对变更进行分类）和 validate（将 PDF 转为质量检查结果）。Agent 获得的是结构化 数据，而不是需要自行解析的文字。将它与 ihalent 搭配使用，Agent 就能同时分析招标 结果以及用于衡量该结果的单价。

// e.g. Claude Desktop / Claude Code mcp config
{ "mcpServers": { "acikpoz": { "command": "acikpoz-mcp" } } }

如实说明适用范围

• 它读取标准目录版式。 基于表头的列检测能很好地处理常见的单价列和双单价列页面；不常见的版式可能会留下更多缺漏——它会如实报告，而不是掩盖问题。如果某个部分解析得不好，那就是值得提供样例来修复的 Bug。
• 它是解析器，不是价格数据库。 它不会捆绑或再分发目录。你提供官方 PDF；acikpoz 会将你的副本转换为数据。
• 价格为原始名义价格，即 PDF 上印出的价格。 不包含通胀调整——调用方了解年份后自行决定是否进行分析调整。

数据，以及 PDF 为何不在这里

ÇŞB 目录是官方公共文件，但本仓库不会再分发这些文件：仓库只提供解析器，不包含其他内容，并通过 .gitignore 排除 *.pdf。请让 acikpoz 读取你从官方来源获取的目录。这与 ihalent 的原则相同——拥有工具，而非数据。

本项目的构建方式

我是一名从事建筑行业的工业工程师，会阅读这些目录。我设计了解析方法——基于几何而非机器学习，如实保留缺漏而非编造数字——并审查每一行代码；我大量使用 AI Agent 来提高实现速度，提交说明也如实记录了这一点。测试就是约定：它们编码了真实页面生成的精确词语几何信息，包括双列 Sıhhi Tesisat 陷阱和组表头规则，因此测试通过就意味着解析器能够处理真实内容。

相关项目

• ihalent — 拼出土耳其公共采购全貌的另一半。acikpoz 读取说明工程应当花费多少的单价目录；ihalent 读取招标结果公告，说明工程最终以什么价格、按什么折扣中标。遵循同样的原则：每个数字都能追溯到来源，不编造任何内容。

Eren Gülmez 的更多工具。

许可证

MIT — 详见 LICENSE。