zkmkarlsruhe/artwork-autopsy

# 艺术品解剖 [](https://zkm.de) [](https://github.com/zkmkarlsruhe) [](LICENSE) 一个自动化分析服务，它能切入未知、无文档的原生数字艺术品，弄清它是什么、运行它需要什么，以及如何让它重现生机。 ## 概述 `artwork-autopsy` 接收一件原生数字艺术品（zip、磁盘映像或散乱的文件包），并生成 一份具体且可操作的**如何让它重现生机**的提案——它是什么、里面有什么内容、 *入口点*在哪里、它需要哪种遗留 runtime/OS、它连接的网络主机，以及 该使用哪些工具来处理它。它会生成一份报告、一份复苏运行手册以及一组建议。 本项目在**卡尔斯鲁厄艺术与媒体中心（ZKM）**开发，用于原生数字艺术的保护—— 这些作品依赖于过时的操作系统、浏览器插件或多媒体引擎（Flash、 Director/Shockwave、早期的 Java–QuickTime、原生的 Win32/Mac 二进制文件）。它是 遗留 VM 工作台（`research-vm-controller` —— *已在规划路线图中，尚未发布*）前端的 接收/分流大脑，但它**完全独立**：即使没有任何此类基础设施，你也可以运行、测试并使用它。 ## 快速开始 **前置条件：**Docker + Docker Compose。一个**兼容 OpenAI 的 LLM endpoint**是*可选的* —— 如果没有配置，你将获得完整的确定性报告（见下文）；如果配置了，你还会获得 AI 分析师， 因此请将其指向一个真正擅长工具调用的模型（LiteLLM 代理、OpenAI 或任何本地的 `/v1` 服务器）。 ``` # 获取代码 — 递归地 clone SUPERSET，而不仅仅是这个 repo。 # 该 compose stack 从一个 SIBLING submodule # (../wayback-mcp) 构建 side-car (wayback-mcp)，因此 autopsy 需要其 siblings 存在。该 superproject # 会为你放置它们： git clone --recurse-submodules vmctl && cd vmctl/artwork-autopsy # 配置 seams cp .env.example .env # 按原样工作：默认 key `sk-nokey` 仅运行 deterministic-only（无 LLM，无网络调用）。 # 若要同时运行 AI analyst，请在 .env 中设置一个可达的 endpoint 和真实的 key： # AUTOPSY_LLM__BASE_URL=https://your-endpoint/v1 # AUTOPSY_LLM__API_KEY=sk-... # （capability→alias 名称 — analysis/fast、analysis/agent、… — 必须在该 endpoint 上存在。） # 启动 stack — 默认为 db (Postgres) + api + runner。 # （decompiler / RE side-cars 受 profile 限制：请为它们添加 `--profile re --profile sidecars`； # 如果没有它们，每个 deep-reader 将降级为带标记的 note — 这是预期行为。） docker compose up -d --build # 提交一个 born-digital work。本 repo 中提供了一个现成的示例： curl -F file=@examples/sample-netart.zip -F mode=intake http://localhost:8099/jobs # -> {"job_id":"job-…","status":"queued"} （或使用你自己的 zip / disc image / bundle） # 查看它并阅读 report # web UI: http://localhost:8099/ui/jobs/ （渲染后的 report 页面 + 实时进度） # 或 API: GET http://localhost:8099/jobs/ （status + verdict） # GET http://localhost:8099/jobs//artifacts （JSON: kb, runbook, suggestions） # （这些 JSON artifacts 包含与渲染后的 report 页面相同的 findings。） ``` **没有 LLM endpoint？**这是默认情况。使用 `sk-nokey` 时，Docker 作业会运行完整的确定性 核心（解包、格式识别、run-graph、入口点、死掉的 endpoint 标记）并快速生成完整报告 —— AI 分析师阶段会被干净利落地跳过（没有调用，没有超时）。设置真实的 endpoint 和 key 即可启用分析师。 **连 Docker 也没有 —— 本地静态分析流程：** ``` # 需要 Python >=3.13 和 poetry (https://python-poetry.org/docs/#installation) poetry install # add -E drive only for the vmctl-core drive integration poetry run autopsy analyze --no-llm examples/sample-netart.zip ``` 这将在本地运行解包 + 格式/依赖/runtime 检测 + run-graph，并打印出 结构化的事实 —— 与 agent 构建时使用的静态核心完全相同，但不包含 AI 分析师。 LLM endpoint、存储（本地磁盘或 S3/MinIO）以及 side-car 工具都是**可配置接口** （`.env` / `config.toml`）—— 有关所有配置开关及如何运行 反编译器 side-car，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。状态（Postgres 作业存储 + `/state` 产物） 存在于**在 `up`/`down` 之间持久化的命名 Docker 卷中** —— 要全新启动，请运行 `docker compose down -v`。 ## 立场：访问优先，不拘小节 这关乎的是**重新展示，而非毕恭毕敬地保存**。我们使用任何工具，深入剖析 文件，并接受一定程度的损失，前提是这能让作品*运行并能够再次展出*。这是 所有真正让老旧交互式媒体保持活力的人（Internet Archive、Rhizome、demoscene、abandonware） 都在采用的、经过验证的主流做法。我们从那个世界保留了两条规则： 1. **绝不破坏原件。**原始文件包将原封不动地保存；我们所做的一切都是 派生的访问副本。 2. **标记我们的推测。**每一个自动化的发现都是容易出错的提案，都会被标记为推测， 供人类决定是否接受 —— 绝不静默应用。 ## 工作原理（pipeline） **确定性的静态分析流程为 run-graph 提供数据；agent 分析师会对其进行调查，直到作品** **被完全理解。**事实累积在图上；由 LLM 进行判断，它从不进行提取。 1. **接收** —— 文件到达（Web 上传 / API / Postgres 作业存储），按原样存储。 2. **静态核心**（无 LLM） —— 解包（支持分支感知），构建文件树，识别格式 （Siegfried/magika），提取 metadata，解析二进制文件，检测 + 分发 runtime 模块。 快速预览流程进行初步定位。规模上限机制可防止包含数千个文件的包发生爆炸式膨胀 （有上限且被记录，绝不静默截断）。输出：标记为 host/guest/network 的结构化事实包。 3. **Run-graph** —— 这些事实成为一等公民图：类型化的节点（entry/binary/runtime/data/ config/network）+ 边（imports/reads/contains/connects）。有针对性的**深度阅读**（基于 runtime 的 反编译器，通过 pyghidra-mcp 调用 Ghidra 作用于原生二进制节点）将恢复出的源码持久化到 磁盘上。发现的结果依附于节点 —— 每轮不会重复生成。 4. **分析师会话循环** —— 一名 pydantic-ai 调查员（专属的 **AGENT** 层级）以确定性的 线索为种子，利用导航 / 图 / 提取工具对艺术品本身进行测绘。它会一直运行 **直到解决或达成一致性**（默认没有步骤或 token 上限 —— 包含 300 个 endpoint 的作品会审查所有 300 个），仅受协作式取消及其自身一致性判断的限制； 死亡/未完成的会话会重试（≤ 3 次），并以部分报告作为种子重新启动。**network-scope** **门控**可防止它误入不透明的 runtime 内部，而**处于循环中的** 研究员可以在运行期间回答分析师的问题或提供指导 —— 正是这种循环检查引导它 绕过死胡同，走向真正的工作。已失效的后端会获得一份 **wayback prognosis**（捕获/从 存档中提供的提案）。 5. **综合 + 报告** —— 该图投影为 `IntakeReport` 以及三份工件： 结论、文件树、入口点、runtime/依赖情况、复苏运行手册、建议的 base-VM + 工具集。这是一个提案，绝不自动应用。 ## 两个任务，一个引擎 - **艺术品接收** —— 针对未知作品的上述 pipeline。 - **工具群扩充** —— 将相同的引擎指向已知遗留 runtime 工具的目录，以 自动填充它们的 metadata（模型提出建议 → 人类审查）。 ## 结构 - **独立或嵌入式。**作为独立服务运行；rvmc（或其他任何东西）只是一个 API 客户端。提供一个简单的 **Web UI** 供手动使用（在 fleet 模式下可禁用），并基于 同一个核心为 agent 提供 **REST API**。 - **异步** —— 一个带有子进程作业运行器的 **Postgres 作业存储**；每个作业都在 自己的子进程中独立运行，并带有心跳存活检测和实时进度事件。扩展方式 = 增加 runner 副本。 - **可插拔接口** —— LiteLLM endpoint（独立运行 *或* 作为 fleet 网关），对象存储 （S3/MinIO，可降级为本地磁盘），均可通过配置切换。 - **分层模型** —— 用于快速预览/分类定位的快速层级，以及专属的用于分析师调查员的 **agent** 层级，通过别名（`analysis/fast` · `analysis/think`）命名，绝不使用 原始模型 ID。 ## 状态 独立的基础框架、Postgres 作业编排器、确定性静态核心、run-graph、runtime 模块框架（包含 17 个模块）、各个 runtime 的深度阅读器以及 agent 分析师（支持 human-in-the-loop 聊天）均已构建完成。Web / net.art 组合模块以及对分析师进行语料库 A/B 验证的工作仍在进行中。有关已发布 / 进行中 / 待完善的内容，请参阅 [**路线图**](ROADMAP.md)，并查看源自 git 的 [**时间轴**](docs/TIMELINE.md) 以了解具体功能的落地时间（`make timeline` 可从 `git log` 重新生成它）。 ## 贡献一个模块 系统每学会一个 runtime 就会变得更加敏锐。一个 **runtime 模块**就是贡献的单元 —— 在通常情况下，它仅仅是 **数据**：在 [`src/autopsy/runtime/runtime-catalog.yaml`](src/autopsy/runtime/runtime-catalog.yaml) 中添加一个条目，描述如何检测一个 runtime、它暗示了哪个 时代 → base-VM、有序的保护配方、重新运行它的引擎、决定其身份的保真度风险，以及它失效的服务器。你也可以选择添加一个 **深度阅读器** （`src/autopsy/reason/.py`）以及一个 **side-car Dockerfile**，以便真实的反编译器能够从该 runtime 的容器中恢复行为。 模型是 **polyrepo（多仓库）的，模块通过 PR 在仓库内部贡献** —— 添加文件，提交一个 pull request， 分发器就会自动处理。从这里开始： Bug 报告和新模块提案使用结构化的 issue 模板（不再有“它坏了”这种模糊描述） —— 打开一个 issue 即可查看它们。 ## 文档地图 | 文档 | 内容说明 | |---|---| | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 系统一览 —— 一张 Mermaid 图表 + 如何阅读它 | | [`docs/DESIGN.md`](docs/DESIGN.md) | 完整计划：立场、静态↔AI pipeline、三份工件、构建计划 | | [`docs/STRUCTURAL_LOOP.md`](docs/STRUCTURAL_LOOP.md) | 由 run-graph 驱动的定向分析循环 | | [`docs/ENGINEERING.md`](docs/ENGINEERING.md) | 工程宪章（端口与适配器，import-ban） | | [`src/autopsy/runtime/runtime-catalog.yaml`](src/autopsy/runtime/runtime-catalog.yaml) | Runtime 模块数据（新 runtime 的存放处） | | [`docs/CONTRIBUTING-MODULES.md`](docs/CONTRIBUTING-MODULES.md) | 添加 runtime 模块 —— 分步指南、完整示例、模板 | | [`docs/design/`](docs/design/) | Runtime 模块、检测阶梯、工具库、分类器 + 指纹、agent 调查设计 | | [`ROADMAP.md`](ROADMAP.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`docs/TIMELINE.md`](docs/TIMELINE.md) | 方向 · 如何提供帮助 · 构建历史 | ## 许可证 MIT —— 详见 [`LICENSE`](LICENSE)。© 2026 Marc Schütze @ ZKM | 卡尔斯鲁厄艺术与媒体中心。 这是一个 **ZKM 开源项目**，vmctl 家族的一部分，由 Marc Schütze 作为首席研究员领导。

标签：Docker, 安全防御评估, 数字艺术保护, 数字遗产, 版权保护, 自动化分析, 请求拦截, 跨站脚本, 逆向工具