企业官网建设流程全解析

DigUp 是一款运行在 Mac 上的本地语义搜索工具，它能读取照片、PDF、录音、视频和代码"内容"，再用 Google DeepMind 的 EmbeddingGemma 2 模型在 Mac 上完成检索。相比只匹配文件名的搜索，DigUp 能让你用"视频里的斑马""谈到睡眠的那一分钟""租约里关于宠物的条款"这类自然语言直接定位到文件里的具体内容。本文带你从源码完整构建 DigUp，覆盖 Xcode 26 工具链、CMake 编译 llama.cpp、Swift 打包签名到最终跑通搜索的全流程。

环境准备：Xcode 26 与 CMake 检查清单

在动手前，先确认三样东西，这是 DigUp 构建的地基：

⚠️一个常见坑：如果你只装了 Command Line Tools 而没有完整 Xcode，构建会失败，因为 CLT 缺少 SwiftUI 和 Swift Testing 宏。先用下面这条命令检查：

xcode-select -p

如果输出指向Command Line Tools，先切回完整 Xcode：

sudo xcode-select -s /Applications/Xcode.app

若系统没有 CMake 但装了uv，scripts/build-llama.sh 会自动在Vendor/cmake-venv里用uv创建虚拟环境并装好cmake+ninja，无需手动安装 CMake。

克隆仓库并准备构建

在终端执行以下命令克隆 DigUp 源码并进入目录：

git clone https://gitcode.com/gh_mirrors/di/DigUp && cd DigUp

DigUp 用 SwiftPM 组织，入口配置在 Package.swift 中，定义了三个产物：DigUpApp（菜单栏应用）、digup（命令行工具）和DigUpKit（无 UI 的核心引擎）。其中 llama.cpp 通过一个名为CLlama的system library接入，它的头文件与静态库路径在 Sources/CLlama/module.modulemap 里被声明，最终链接到Vendor/llama/lib/libllamacpp.a。

用 CMake 编译 llama.cpp 静态库

这是整个构建里唯一"重"的步骤，但脚本全自动，只需一条命令：

scripts/build-llama.sh

它做了四件事（详见 scripts/build-llama.sh）：

1. 锁定版本：浅克隆 llama.cpp 到固定的构建标签b11461，存放到Vendor/llama.cpp（scripts/build-llama.sh）。

2. 打一行补丁：应用 scripts/llama.cpp-no-logits.patch，让嵌入模型不再为每个 token 白白分配 logits 内存。

3. CMake 构建：只编译"库"，不编译工具、服务和示例，并启用 Metal 后端（scripts/build-llama.sh）：

   cmake -S Vendor/llama.cpp -B Vendor/llama-build \ -DGGML_METAL=ON -DGGML_METAL_EMBED_LIBRARY=ON -DLLAMA_BUILD_MTMD=ON \ -DLLAMA_BUILD_TOOLS=OFF -DLLAMA_BUILD_SERVER=OFF

4. 合并产物：把多个.a静态库合并成Vendor/llama/lib/libllamacpp.a，头文件放到Vendor/llama/include。

💡 该脚本幂等：如果产物已存在且标签、补丁的校验戳没变，它会直接跳过，几秒返回。只有升级标签或改补丁时才真正重编。Metal shader 在首次运行时才编译，因此构建阶段不需要 Metal 工具链。

构建 App 与 CLI 可执行文件

llama.cpp 就绪后，用 SwiftPM 编译并测试：

swift build -c release && swift test

这一步会编译出DigUpApp和digup两个二进制，并跑通单元测试。其中测试环节非常关键，下面单独展开。

运行测试：ReferenceVectorTests 验证向量

swift test里最特殊的是 Tests/LlamaRuntimeTests/ReferenceVectorTests.swift：它把固定的参考输入（一张照片、一张截图、一段语音）喂给当前 llama.cpp 构建，再把算出的向量与仓库里存好的基准向量对比。

上面这两张图就是Tests/LlamaRuntimeTests/Reference/里的固定输入，配合speech.wav一起被模型编码，结果与vectors.json比对（Tests/LlamaRuntimeTests/ReferenceVectorTests.swift）。

为什么要跑这个测试？因为 DigUp 的索引里存的是向量，一旦 llama.cpp 版本变化导致向量偏移，旧索引就会"对不上号"。该测试保证每次升级 llama.cpp 前，向量是一致的。如果你将来升级了 llama.cpp 而测试失败，有两个选择：保留旧标签，或升级 LlamaEmbedder.vectorVersion 并用DIGUP_WRITE_REFERENCE=1 swift test --filter ReferenceVectorTests重写基准向量（代价是所有旧索引都要重新编码）。

提示：ReferenceVectorTests以及任何真实搜索都会触发 EmbeddingGemma 2 模型（约 865 MB）的一次性下载，之后便缓存复用。

打包 DigUp.app 与签名

核心都编译好后，运行打包脚本生成可运行的应用包：

./build.sh

build.sh 会：先调用scripts/build-llama.sh确保运行时就绪；再分别构建DigUpApp与digup两个产物；然后把 CLI 放进Contents/Helpers/（避免大小写不敏感磁盘上的重名冲突）、编译图标、嵌入 Sparkle 自动更新框架，最后用hardened runtime签名，输出到build.noindex/DigUp.app。

• 日常开发：直接./build.sh，用 ad-hoc 签名即可运行（每次重建后 macOS 可能重新询问权限）。
• 指定签名身份：SIGN_ID="你的身份" ./build.sh，macOS 会跨重建保留文件夹授权。
• 发布流程：scripts/release.sh 会在此基础上加时间戳、公证（notarize）、装订（staple）并生成 DMG，属于维护者的发布动作，普通构建无需关心。

没有"安装"这一步：源码构建的应用直接从build.noindex/运行即可，配合下面的沙盒脚本最安全。

用 dev-run.sh 沙盒运行（推荐）

scripts/dev-run.sh 是专为开发设计的启动器：它把应用跑在一个隔离沙盒里——临时索引、模型和设置都放在.dev/下，并使用独立的 defaults 套件，绝不动你真实的索引、模型和偏好设置：

scripts/dev-run.sh

还支持若干环境变量：

• ROOTS=a:b:c覆盖要索引的文件夹（ROOTS=留空则以全新安装状态启动）；
• APP=/Applications/DigUp.app可对已安装的副本做同样的沙盒运行；
• 额外参数会原样透传给 App，例如scripts/dev-run.sh -debugQuery "zebra" -debugQuit YES。

应用日志写在<index>/app.log，方便排查。

用 digup CLI 验证索引与搜索

除了 GUI，DigUp 还自带一个功能完整的命令行工具 digup，它既能独立索引/搜索，也是 App 的索引助手。在终端里可以这样验证刚构建的产物：

.build/release/digup status # 查看索引里有什么 .build/release/digup index ~/SomeFolder .build/release/digup search 视频里的斑马 .build/release/digup eval evals/synthetic.json

estimate / index / search / status / eval五个子命令覆盖了"预估耗时 → 建索引 → 搜索 → 查状态 → 跑评测"的完整闭环（--index DIR可指定索引目录，默认在~/Library/Application Support/DigUp/）。

如果想在更真实的文件上试手，scripts/make-testbed.sh 能一键生成一个可随时删除的测试沙盒~/DigUpTestbed（含真实文件克隆、合成媒体和爬虫陷阱用例，需要ffmpeg）。而 evals/ 下的code.json、multilingual.json、synthetic.json正是digup eval用来衡量排序变化的查询集。

常见构建问题排查

小结

整套源码构建可以浓缩为四步：

1. scripts/build-llama.sh—— CMake 编译 llama.cpp 静态库；
2. swift build -c release && swift test—— 编译产物并验证向量一致性；
3. ./build.sh—— 打包签名出build.noindex/DigUp.app；
4. scripts/dev-run.sh/digup—— 在沙盒中安全运行并验证搜索。

完成这四步，你就从源码拥有了一个完全本地化、由 EmbeddingGemma 2 驱动的 DigUp，既能当菜单栏应用用，也能用 CLI 做索引与评测。