用途：为 agent-desktop 的 PlatformAdapter 提供 C-ABI 绑定，供 Python ctypes、Swift、Node ffi-napi、Go cgo、C++、Ruby fiddle 等消费者链接调用，直接访问全部平台适配器操作。
构建：使用工作区 release-ffi profile，命令为 cargo build --profile release-ffi -p agent-desktop-ffi，产物为 target/release-ffi/libagent_desktop_ffi.dylib（Linux 为 .so，Windows 为 .dll），并附带头文件 crates/ffi/include/agent_desktop.h。注意 release profile 为 panic = "abort"，应使用 release-ffi 获得 panic = "unwind"，CI 强制此点。
主要能力：观察-操作循环为规范路径。先调用 ad_init(AD_ABI_VERSION_MAJOR) 校验头文件与库匹配；用 ad_adapter_create_with_session("s1") 创建带会话的适配器；ad_snapshot 返回 {version, ok, command, data} JSON 封装，data.tree 含交互元素的快照限定 ref ID；再通过 ad_execute_by_ref 执行动作，调用 ad_free_string 释放。此外提供 ad_wait（等待元素/窗口/文本/菜单/通知等）、ad_list_displays（截图目标）、ad_list_windows_exact、ad_get_tree_exact（原始 BFS 树，无 @e ref）、底层 ad_execute_action 等。参考文档包括 ownership.md、error-handling.md、threading.md、build-and-link.md。
使用方式：Python ctypes 冒烟示例位于 tests/ffi-python/smoke.py，用法见 tests/ffi-python/README.md。会话 ID 限 1–64 字符 ASCII 字母数字及 - 和 _。结构化 JSONL 追踪需会话清单开启 trace: on。线程上，适配器入口可任意宿主线程调用，桌面变更会获取跨进程交互租约。
限制：ABI 破坏性变更仅在大版本号递增；1.0 之前需锁定链接库版本。ad_last_error_details 可能含屏幕元素名、值与窗口标题，属敏感诊断，避免写入共享日志。句柄需用 ad_free_handle 在同一适配器上释放。日志回调可能来自其他线程且在注销后短暂触发，须保持进程生命周期有效。文本输入在 macOS 上非 ASCII 可能短暂使用剪贴板，敏感文本建议用 AD_ACTION_KIND_SET_VALUE 配合无头策略。其他收费、平台覆盖等未提供。