构建与链接

每个平台的适配器只能在它自己的操作系统上构建。这不是限制，而是必然：适配器 import 的 是这个操作系统的可访问性 API，换一台机器就找不到那些符号。

构建

需要 Rust 1.89 或更新版本，外加平台工具链：macOS 13+ 上的 Xcode 命令行工具、 Windows 上的 MSVC 构建工具，或 Linux 上的 C 链接器。

core 永远不 import 平台 crate，平台 crate 之间也互不 import。把 cargo 的范围限制在 宿主平台对应的包上，在 macOS 上：

HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
cargo build --release "${HOST_PKGS[@]}"
cargo test "${HOST_PKGS[@]}"
cargo clippy "${HOST_PKGS[@]}" --all-targets -- -D warnings

在 Windows 上把列表里的 agent-desktop-macos 换成 agent-desktop-windows； 在 Linux 上换成 agent-desktop-linux。

agent-desktop-ffi 产出对应平台的动态库和头文件。

链接

一个二进制在编译期就选定它要驱动哪个操作系统，所以链接时只能带一个平台适配器。 把可执行文件和平台辅助程序放在同一个目录——CLI 走的是同样的规则， 见安装与权限。

ABI 版本

ad_init 接收 AD_ABI_VERSION_MAJOR，只有与库匹配时才返回 AD_RESULT_OK。 把头文件里的常量和链接的库一起校验，而不是假设它们来自同一次发布：

#include "agent_desktop.h"

if (ad_init(AD_ABI_VERSION_MAJOR) != AD_RESULT_OK) {
    /* 头文件和库不是同一次发布，停下来而不是继续调用。 */
}

所有关卡

CONTRIBUTING.md 列出了从源码构建需要通过的全部关卡。从源码构建 CLI 本身的步骤在 仓库的 docs/install.md#from-source。

• C 库总览：入口点、内存所有权和线程规则。
• 常见问题：构建失败时的排查顺序。