sdff-tools

把私有 SDFF DCS 工程资料，转换为可核验、可离线交付的只读查看器。

Python 3.10+ · 解析核心零依赖 · 静态交付 · 本机运行

快速开始 · 核心能力 · 命令行工具 · 数据与安全边界 · 开发与验证

sdff-tools 面向同类 DCS 工程交付目录：在构建期盘点并解析流程图、工程点表、事件、 截图/PFtopo 与审核元数据，最终生成带来源说明、质量状态和校验和的静态查看器。 交付端不需要数据库、Node.js 或网络连接，只需通过本机回环地址打开生成结果。

.pic 在这里不是通用图像格式，而是文件头魔数为 SDFF 的 DCS 组态私有二进制格式。 该格式没有公开规格；本项目的结构结论来自真实工程文件逆向与逐项验证。

Important

仓库不包含任何客户工程数据。README 中的位号、描述和浏览器 fixture 均为结构同形的合成样例。

Note

当前源码候选的内部版本为 0.4.0rc3（PEP 440）；面向用户的展示标签为 v0.4.0-rc.3。普通 commit 不逐次升版本，只有候选晋级正式版时才重新构建为 0.4.0 （展示为 v0.4.0）。当前机器验收候选的源码锚为 0.4.0rc3@afebba9；既有 rc1、 rc2 与 78d7e3c / 0.4.0 查看器产物仅作历史回滚证据，不能作为本轮候选的构建、 MCP 或 ZIP 证明。

已验证的结果

以下数据来自代表性真实工程，用来说明当前实现经过的验证规模，不是对所有项目的性能承诺。

验证项	结果
SDFF 流程图解析	82 / 82 成功
流程图位号 → 工程点表命中率	98.3%
目录级构建	380 页面 · 56,047 位号 · 366 画面对象
事件解析	15,418,409 条 · 156 个日桶 · 6 个月桶
交付校验	schema、引用、守恒、资源和输出白名单 0 错误 / 0 警告

关系图代表构建还生成了 15,114 个 canonical 节点和 22,023 条边；业务视图只投影可读的 工艺、画面导航和对象关系，完整细粒度关系仍保留为离线取证产物。

从交付目录到离线查看器

• 构建期完成重活：Python 负责发现、解析、关联、预聚合和校验。
• 运行期保持简单：浏览器读取静态 HTML、CSS、JavaScript、JSON、SVG 和 PNG。
• 证据优先：缺失、歧义和不支持状态显式呈现，不根据目录顺序或时间戳猜来源。

快速开始

1. 安装

从源码安装完整离线查看器能力：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[offline]"

只想确认一批 .pic 能否解析，可先运行：

sdff info /path/to/流程图目录

2. 构建并检查查看器

sdff inventory /path/to/只读交付目录 -o out/inventory.json
sdff build-viewer /path/to/只读交付目录 -o out/viewer
sdff validate-viewer out/viewer
sdff serve out/viewer

serve 默认只监听 127.0.0.1:8000。如果同类来源存在多个候选，构建会明确失败；请用 --oplog、--alarms、--templates、--process-export 等参数指定来源，而不是依赖自动猜测。

需要工程名称、工段归属或导航目标修正时，先复制并编辑 examples/aliases-project-template.json，再传入 --aliases out/aliases.json。客户配置应继续放在已忽略的 out/，不要提交到仓库。

3. 打包与静态验收

sdff package-viewer out/viewer -o out/sdff-viewer.zip
sdff accept-viewer out/sdff-viewer.zip --json

交付 ZIP 带逐文件校验和与跨平台启动器。解压后，Windows 双击 start-viewer.bat，Linux 运行 ./start-viewer.sh；两者都只在本机启动静态 HTTP 服务。

核心能力

离线查看器

• 以业务、工段、画面对象、位号、关系、事件、质量和交付信息组织静态工程数据。
• 在单图工作区同时查看 SVG、绑定点位、对象、报警、底栏导航与工艺上下游。
• 显式展示来源覆盖、质量 finding、未提供状态和歧义，不把空数据解释成“没有业务关系”。
• 生成不可变 ZIP、manifest、输入指纹、构建报告与双层 SHA-256，支持 side-by-side 回滚。

SDFF 与工程数据解析

• 解析 .pic 的五个数据流：DocInfo、PageInfo、Shape、Tag、Text。
• 抽取 DCS 位号绑定、屏幕坐标、图层、显示格式，并就近匹配静态中文标签。
• 读取 Tags.mdb / Tags.xls，补充中文描述、工程量程、单位码和六级报警限。
• 渲染 SVG，按需输出 PNG，并对渲染结构做检查。
• 构建未裁剪的 relation-graph/v1，导出工艺总览、画面对象关系和 HMI 导航的 .drawio 与 SVG 取证文件。

解析器核心仅使用 Python 标准库 struct 与 zlib；MDB、XLS、PNG、MCP 等能力按需安装。

安装组合

目标	安装命令	额外能力
解析与 SVG 渲染	pip install -e .	零第三方运行依赖
工程点表	pip install -e ".[tagdb]"	读取 Tags.mdb
PNG 输出	pip install -e ".[render]"	SVG 栅格化
单位码反解	pip install -e ".[units]"	读取组态导出的 .xls
完整离线构建	pip install -e ".[offline]"	MDB + XLS + 查看器构建
MCP 辅助验收	pip install -e ".[offline,mcp]"	开发/验收伴随服务

命令行工具

命令	用途
sdff info	概览 .pic 文件或批量解析自检
sdff inventory	只读盘点交付目录与 ZIP 安全元数据
sdff build-viewer	从交付目录、工程 ZIP 或 Project.xml 构建查看器
sdff validate-viewer	校验 schema、引用、守恒、资源和输出白名单
sdff serve	通过本机 HTTP 安全打开已生成查看器
sdff package-viewer	生成启动器、校验和与离线 ZIP
sdff accept-viewer	运行不依赖 MCP 的静态交付验收
sdff render	批量渲染 SVG，并可选输出 PNG / 工段拼图
sdff tags	抽取位号台账，并可关联工程点表
sdff dump	导出指定 SDFF 数据流的属性树 JSON

高级与拆分命令

• sdff units：从组态导出的 XLS 反解 EU 单位码表。
• sdff dataset：单独生成查看器静态数据集。
• sdff process-flow：单独补工艺边与厂区卡片，不必重建整个 dataset。
• sdff app：铺开单页查看器外壳。
• sdff viewer：旧版每页一个自包含 HTML，可用 file:// 打开；完整查看器主路径应使用 build-viewer + serve。
• sdff release-index：记录、列出和校验离线查看器发布索引。

完整参数以 sdff <command> --help 为准。

Python API

from sdff import extract_page, load, referenced_tags

doc = load("喷雾干燥.pic")
page = extract_page(doc, "喷雾干燥.pic")

print(doc.page_info["docWidth"], len(doc.shapes))
print(referenced_tags(doc)[:2])
print(page.bindings[0].tag, page.bindings[0].nearest_label)

读取工程点表：

from sdff.tagdb import load_project

tags = load_project("/path/to/SUPCON_PROJECT")
tag = tags["P1_PT100201B_3"]
print(tag.desc, tag.type_name, tag.limits)

数据与安全边界

• 源目录只读：构建器不会在客户交付目录写缓存或中间文件。
• 客户数据不入 Git：.pic、.mdb、.xls、.xlsx、.csv、.zip、data/ 和 out/ 已被忽略。
• 默认仅本机访问：sdff serve 和包内启动器监听 127.0.0.1；不要无意暴露到局域网。
• 查看器没有运行时后端：不依赖数据库、Neo4j、LLM、Agent 或云服务。
• 事件聚合不是数值趋势：没有真实 timestamp/tag/field/value/quality 时，不展示 PV/SV 曲线。
• 画面对象不是权威设备台账：当前对象关系来自 HMI、位号和工艺证据；缺少稳定设备 ID 时不会包装成物理资产结论。
• 标签匹配是启发式：默认 200 px 距离上限；高置信语义优先使用点表 Tag_Desc。
• 单位码需要外部映射：反解方式见 工程点表说明 §3.4。

access_parser 的 Jet4 文本解码会破坏部分中文描述。本项目已绕过该路径；原因和验证见 工程点表说明 §5。

MCP 辅助验收

sdff-mcp 只服务开发和验收，不进入客户 ZIP。它只能读取 SDFF_MCP_READ_ROOTS 显式授权的 目录，证据只写入 SDFF_MCP_RUN_ROOT/<run-id>/，不提供任意 shell、URL、文件读取或输出位置。 static 验收只需 Python；ui/full 还需要 Node.js 20、前端依赖与 Chromium。

export SDFF_MCP_READ_ROOTS="$PWD/out"
export SDFF_MCP_RUN_ROOT="$PWD/out/mcp-runs"
sdff-mcp

工具目录、报告契约和安全边界见 MCP 辅助验收设计。

文档地图

需要了解	从这里开始
当前状态与下一步	docs/status.md
新开发会话上下文	docs/HANDOFF.md
离线查看器架构与数据契约	docs/design-offline-data-viewer.md
SDFF 格式规格	docs/format-spec.md
逆向依据与验证方法	docs/research-notes.md
渲染设计	docs/design-rendering.md
发版、构建、部署与回滚	docs/release-build-deploy-sop.md
综合评估与产品路线	docs/evaluation-project-comprehensive-2026-08.md

开发与验证

python -m pip install -e ".[dev]"
PYTHONPATH=src pytest

cd frontend
npm ci
npm run test
npm run typecheck
npm run build
PLAYWRIGHT_CHROMIUM_PATH=/path/to/chromium npm run test:e2e

正式源码检查使用统一发版门；它会验证版本一致性、Python/Vitest/TypeScript、隔离前端构建、 包内 webapp 对账和合成浏览器回归：

PYTHON="$PWD/.venv/bin/python" PLAYWRIGHT_CHROMIUM_PATH=/path/to/chromium PATH=/path/to/node20/bin:$PATH bash scripts/release-gate.sh

测试只使用合成 SDFF 与静态 fixture，不依赖客户数据。当前源码候选内部版本为 0.4.0rc3， 展示标签为 v0.4.0-rc.3；版本策略见 docs/versioning-policy.md。 许可证在 pyproject.toml 中声明为 MIT。