Napaxi

<p align="center"> <img src="docs/assets/napaxi-logo.png" alt="Napaxi" width="720"> </p> <p align="center"> <strong>用于在您的应用中嵌入智能代理体验的移动原生SDK。</strong> </p> <p align="center"> <a href="LICENSE"><img alt="License: GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg"></a> <img alt="Status: SDK 1.0" src="https://img.shields.io/badge/status-SDK%201.0-blue.svg"> <img alt="Rust" src="https://img.shields.io/badge/Rust-1.92%2B-dea584?logo=rust&amp;logoColor=white"> <img alt="Flutter" src="https://img.shields.io/badge/Flutter-SDK-02569B?logo=flutter&amp;logoColor=white"> <img alt="Dart" src="https://img.shields.io/badge/Dart-3.3%2B-0175C2?logo=dart&amp;logoColor=white"> <img alt="Kotlin" src="https://img.shields.io/badge/Kotlin-Android-7F52FF?logo=kotlin&amp;logoColor=white"> <img alt="Swift" src="https://img.shields.io/badge/Swift-iOS-F05138?logo=swift&amp;logoColor=white"> <img alt="Git LFS" src="https://img.shields.io/badge/Git%20LFS-required-lightgrey.svg"> </p> <p align="center"> <a href="README.zh-CN.md">简体中文</a> · <strong>English</strong> </p> Napaxi 是一个移动原生SDK，用于在您的应用中嵌入智能代理体验。 它为应用团队提供了一个共享的 Rust 智能代理运行时、薄的移动 SDK 适配器和一个演示应用，以展示公共 API 界面。宿主应用保留了 UI、账户、模型配置、权限和产品策略的所有权。Napaxi 拥有可重用的运行时组件：会话、工作区状态、存储、工具、技能、MCP、平台钩子和背景执行，以及适配器合约。 Flutter 是第一个完整的适配器和演示目标。Android 和 iOS SDK 适配器与其并存，所有适配器都共享相同的核心 API 界面。 [文档](docs/README.md) · [Flutter SDK](packages/flutter/README.md) · [架构](docs/architecture.md) · [安全](SECURITY.md) · [贡献](CONTRIBUTING.md) · [CLA](CLA.md) · [发布指南](RELEASING.md) ## 为什么选择 Napaxi - **纯设备端智能代理运行时** Napaxi 在移动应用中原生运行。除了应用批准的模型调用外，运行时不需要 Napaxi 云服务器或远程开发服务器，因此工作区数据、会话状态、文件、工具元数据和智能代理执行都保留在手机上。 - **安全的沙箱环境** 本地工具执行在移动沙箱、策略门控和主机控制的授权后面隔离。应用决定智能代理可以访问哪些外部权限、平台工具、文件、通道和后台功能。 - **可插拔、可扩展的工具** Napaxi 支持 14+ 个移动优先的内置工具、模型即工具工作流、多模型编排、MCP 工具和主机定义的自定义工具。工具界面旨在无需将产品策略移出主机应用即可扩展。 - **可组合的场景** SDK 功能被组织为可重用的运行时和适配器组件，因此团队可以组装不同的智能代理场景，而不是为每个应用、设备或工作流重建单独的堆栈。 - **端到端连接：xApp、xAgent、xChannel** Napaxi 连接应用、智能代理、通道和设备。xApp 实现了一种新的移动智能代理应用模式，具有跨应用交互；xAgent 支持设备上的多智能代理协作和外部智能代理互操作；xChannel 连接更广泛的通道，例如即时通讯工具、蓝牙耳机、车辆系统、无人机和其他设备表面。 ## 您可以使用 Napaxi 构建什么 当您需要一个嵌入应用的智能代理时，Napaxi 会很有用，该智能代理可以： - 通过应用拥有的会话和历史记录进行聊天； - 使用工作区文件、内存、技能、内置工具和 MCP 工具； - 暴露主机批准的平台工具，例如文件、浏览器、设备和后台功能； - 支持一个主机应用中的多个智能代理和组协作； - 根据主机选择的 LLM 提供商和模型配置运行； - 在 Flutter、Android 和 iOS 适配器上保持 SDK 行为的可移植性。 SDK 不会提供产品 UI。主机应用决定体验；Napaxi 提供运行时和移动集成层。 ## 使用示例 这些示例展示了三种不同的集成层：设备端开发工具、沙箱文件实用程序和提供者驱动的设备操作。 ### 纯移动开发 在手机上构建和迭代移动应用。主机应用可以连接 Codex 和 Claude Code 引擎，但执行循环保持在手机端：智能代理在移动工作区中生成或更新 Android 应用代码，通过主机批准的设备端工具构建 APK，并直接安装回设备。除了应用批准的模型调用外，此流程不依赖于云开发服务器。 | 生成移动应用 | 更新、构建和安装 | | --- | --- | | <img src="docs/assets/mobile-dev-generate.gif" alt="Napaxi 从手机生成移动应用" width="260"> | <img src="docs/assets/mobile-dev-update.gif" alt="Napaxi 更新移动应用并安装 APK 到手机" width="260"> | ### 移动文件工具：图像压缩 通过相同的沙箱工具管道公开日常文件实用程序。在此流程中，智能代理接收应用批准的图像，将其压缩到请求的目標大小，将输出写回工作区，并报告结果路径以供预览、共享或附件。 <p align="center"> <img src="docs/assets/mobile-image-compression.png" alt="Napaxi 在手机上压缩图像文件" width="300"> </p> ### 连接设备：智能家居 通过主机批准的提供者应用将智能代理决策路由到执行具体设备操作，例如控制智能家居灯。核心保持会话状态、路由、策略和操作结果契约一致，而提供者拥有实际设备 I/O。 <p align="center"> <img src="docs/assets/mobile-smart-home.gif" alt="Napaxi 从手机控制智能家居灯" width="480"> </p> ## 快速入门 先决条件： - Rust 稳定工具链，以及您计划构建的任何移动目标。 - 用于 `packages/flutter` 和 `examples/flutter` 的 Flutter SDK。 - 用于检入的移动运行时资产的 Git LFS。 - 用于原生移动构建的 Android NDK 和/或 Xcode 命令行工具。 克隆并获取运行时资产： ```sh git clone <repo-url> napaxi cd napaxi git lfs pull ``` 运行核心边界检查： ```sh ./tools/scripts/build.sh check-boundary ``` 运行 Flutter 演示： ```sh cd examples/flutter flutter run ``` 演示应用使用存储库本地的 Flutter SDK： ```yaml dependencies: napaxi_flutter: path: ../../packages/flutter ``` 主机 Flutter 应用导入公共 SDK 入口点： ```dart import 'package:napaxi_flutter/napaxi_flutter.dart'; ``` 有关 SDK API 示例，请参阅 [`packages/flutter/README.md`](packages/flutter/README.md)。 ## 构建原生产物 从存储库根目录构建移动 SDK 产物： ```sh ./tools/scripts/build.sh fast android ./tools/scripts/build.sh fast ios ``` 生成的输出是本地产物，默认不提交： - `packages/flutter/android/jniLibs/*/libnapaxi_api_bridge.so` - `packages/flutter/ios/Frameworks/napaxi_api_bridge.xcframework` - `packages/ios/Frameworks/napaxi_api_bridge.xcframework` 有关 iOS 设备检查、签名、配置和 Swift Package 详细信息，请参阅 [`docs/sdk-integration.md`](docs/sdk-integration.md)。 ## 架构概览 ```text 主机应用 -> SDK 适配器（Flutter / Android / iOS） -> packages/api_bridge -> napaxi_core::api -> Rust 运行时域 ``` 存储库布局： ```text napaxi/ crates/ core/ Rust 运行时内核和适配器面向的核心 API。 features/ 核心消耗的功能域 crates。 packages/ api_bridge/ napaxi_core::api 的 Rust FFI/FRB 桥。 api_contract/ 适配器 API 契约：方法、错误、fixtures。 flutter/ Flutter SDK 包，导出为 napaxi_flutter。 android/ 原生 Android Kotlin SDK 适配器。 ios/ 原生 iOS Swift Package 适配器。 agent_provider/ 代理应用操作的提供者侧 SDK。 examples/ flutter/ 使用 ../../packages/flutter 的 Flutter 集成演示。 provider_app/ 代理应用操作的示例提供者应用。 vendor/ 修补或供应商的第三方依赖。 tools/scripts/ 构建、代码生成、卫生和打包助手。 docs/ 架构、集成和贡献文档。 ``` 依赖方向故意狭窄： ```text crates/features/* -> crates/core -> packages/api_bridge -> SDK 适配器 -> 示例 ``` 适配器必须使用 `napaxi_core::api`。软件包不得直接依赖 `crates/features/*`，演示应用必须调用公共 SDK API。 ## 安全模型 Napaxi 在主机应用中运行，可以公开强大的本地功能。将每个智能代理操作表面视为应用策略，而不仅仅是 SDK 管道。 - 主机应用选择模型提供商、账户、权限和启用的工具。 - 核心策略门控工具描述的准入、工具调用的准入、提供商的准入和模型切换。 - 平台工具和后台执行由适配器拥有，必须通过 SDK API 显式公开。 - 通道/提供者集成应规范传入的消息，并让核心处理路由、会话、历史、策略和出队状态。 - 安全报告应遵循 [`SECURITY.md`](SECURITY.md)，而不是公共问题。 在发布具有原生运行时资产的应用之前，请查看 [`THIRD-PARTY-LICENSES.md`](THIRD-PARTY-LICENSES.md)、 [`packages/flutter/android/jniLibs/THIRD-PARTY.md`](packages/flutter/android/jniLibs/THIRD-PARTY.md)和 [`packages/ios/Vendor/iSHCore/THIRD-PARTY.md`](packages/ios/Vendor/iSHCore/THIRD-PARTY.md) 在重新分发构建产物之前。 ## 验证更改 首先使用最小的有用检查，然后在交付或发布之前运行更广泛的检查。 ```sh # Rust/核心/API 边界 ./tools/scripts/build.sh check-boundary cargo check --manifest-path crates/core/Cargo.toml cargo test --manifest-path crates/core/Cargo.toml -- --quiet # Flutter SDK cd packages/flutter flutter analyze flutter test # Flutter 演示 cd examples/flutter flutter analyze flutter test ``` 发布卫生： ```sh ./tools/scripts/build.sh check-hygiene NAPAXI_RELEASE=1 ./tools/scripts/build.sh check-hygiene ``` 完整的发布流程位于 [`RELEASING.md`](RELEASING.md)。 ## 按目标分类的文档 | 目标 | 从这里开始 | | --- | --- | | 了解项目 | [`docs/overview.md`](docs/overview.md) | | 了解所有权边界 | [`docs/architecture.md`](docs/architecture.md) | | 集成或构建 SDK 产物 | [`docs/sdk-integration.md`](docs/sdk-integration.md) | | 使用 Flutter SDK | [`packages/flutter/README.md`](packages/flutter/README.md) | | 保持适配器同步 | [`docs/sdk-adapter-parity.md`](docs/sdk-adapter-parity.md) | | 添加功能 | [`docs/mobile-capabilities.md`](docs/mobile-capabilities.md) | | 处理提供者应用 | [`docs/agent-provider-protocol.md`](docs/agent-provider-protocol.md) | | 查看代理应用操作 | [`docs/agent-app-actions.md`](docs/agent-app-actions.md) | | 贡献代码 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | | 完成 CLA | [`CLA.md`](CLA.md) | | 报告漏洞 | [`SECURITY.md`](SECURITY.md) | 可以通过以下方式生成 API 参考： ```sh cargo doc --no-deps -p napaxi-core --open cd packages/flutter dart doc ``` ## 开发边界 - 可重用的运行时行为属于 `crates/`，尤其是 `crates/core/`。 - 功能域逻辑属于 `crates/features/`，但不得依赖核心。 - SDK 适配器、平台胶水和绑定桥包属于 `packages/`。 - 仅限演示的 UI、状态、模拟客户端和面板属于 `examples/`。 - 构建、代码生成、卫生和打包助手属于 `tools/scripts/`。 - 持久架构和集成说明属于 `docs/`。 - 生成的桥接文件不得手动编辑。 如果行为应被多个主机应用或适配器共享，请将其放在 Rust 核心或 SDK 包中，并通过公共 API 暴露。 ## 状态 Napaxi SDK `1.0.0` 是第一个公开的 SDK 版本。`crates/core/src/api/` 下的核心 API 是稳定的适配器面向边界，而更深的运行时内部可能继续演变。公共 API 更改在 [`CHANGELOG.md`](CHANGELOG.md) 中跟踪。 ## 联系方式 对于公共项目问题、协作或发布协调，请联系 维护者 [wenyu.mwt@antgroup.com](mailto:wenyu.mwt@antgroup.com)。 请通过 [`SECURITY.md`](SECURITY.md) 报告安全问题，而不是公共问题或电子邮件线程。 ## 贡献 欢迎提出问题和拉取请求。在进行较大更改之前，请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以了解设置、边界规则、验证 期望和许可条款。外部贡献需要适用的贡献者许可协议；请参阅 [`CLA.md`](CLA.md)。 ## 许可证 Napaxi 源代码在 GNU 通用公共许可证 v3.0 或更高版本（`GPL-3.0-or-later`）下获得许可。参见 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。 分发的移动 SDK 还包括具有其自己的许可证的第三方原生运行时组件，包括沙箱相关资产的 GPL/LGPL 义务。请查看 [`THIRD-PARTY-LICENSES.md`](THIRD-PARTY-LICENSES.md)、 [`packages/flutter/android/jniLibs/THIRD-PARTY.md`](packages/flutter/android/jniLibs/THIRD-PARTY.md)和 [`packages/ios/Vendor/iSHCore/THIRD-PARTY.md`](packages/ios/Vendor/iSHCore/THIRD-PARTY.md) 在重新分发构建产物之前。