plexus

# 普勒克斯 > **人工智能代理的本地能力网关**。普勒克斯是一个用户安装的、开源的网关，它暴露了一个人工智能原生的、自我描述的端点，因此任何人工智能代理都可以**发现 → 理解 → 被授权 → 调用**您机器上的软件能力 - 在一个您可以查看、范围限定和撤销的信任模型下。 [](LICENSE) [](docs/protocol/PLEXUS-PROTOCOL.md) [](https://bun.sh) [](#macOS-first-with-a-real-cross-platform-seam)  <p align="center">_{五个代理，一个墙 - 读取流程，写入待处理，执行按调用，脱机子集弹回，撤销是外科手术。 <a href="https://plexus.vibecoding.icu/">在网站上观看实时演示 →</a>}</p> --- ## ▶︎ 5分钟试用 - 交给您的人工智能 在仓库中打开 **Claude Code** （或其他任何编码代理），然后说： **“读取 `docs/getting-started.md` 并为我设置普勒克斯。”** 它安装、启动普勒克斯、配置所有内容（询问您要公开的文件夹）、连接自己作为一个代理，并演示一个读取和一个写入 - 同时**您在普勒克斯UI中批准每个授权**。您将看到一个代理访问您的Mac的能力，而无需shell，锁定到您公开的内容，每个强大的操作都得到您的批准。 **→ [`docs/getting-started.md`](docs/getting-started.md)** - 完整的运行手册（也是一个很好的复制粘贴指南，如果您想手动操作）。 ### 从哪里开始 | 您想... | 去 | | --- | --- | | 看看普勒克斯是什么以及为什么 | 您已经在正确的页面上 - 继续阅读 | | **运行它** （将仓库交给您的代理） | **[`docs/getting-started.md`](docs/getting-started.md)** | | **理解模型 + 构建** （安装，连接代理，编写源代码） | **[`docs/README.md`](docs/README.md)** - 开发者阅读路径 | 本页面是产品登陆页面。它不会重复开始步骤 - 请遵循 `docs/README.md` 获取这些信息。 --- ## 为什么是普勒克斯 MCP回答 *"我有哪些功能？"* 普勒克斯回答 *"你应该如何使用我？"* - 它将功能包装在**使用知识**、一个**可读的信任模型**和一个**审计跟踪**中，然后通过一个稳定的人工智能原生协议将它们提供给代理。 重点不是另一个工具注册表。这是**您已经使用的本地macOS软件**的界面。普勒克斯将您的Obsidian保险库、Apple Calendar、Reminders、Notes、Mail、Contacts和Photos、浏览器、Shortcuts和Claude Code编排成代理可以发现和调用的能力 - 而无需您提供一个空白密钥，也无需代理自行授予一个修改操作。 **透明度是产品。** 默认拒绝、按能力范围限定、可撤销、审计 - 这个信任故事 **就是价值**，而不是对它的税收。 --- ## 快速开始（macOS） 普勒克斯运行在 [Bun](https://bun.sh) （≥ 1.3.0）上。如果您没有安装Bun，请运行： ```sh # 1. 安装依赖（工作区 monorepo） bun install # 2. 启动网关 - 仅限回环（127.0.0.1:7077）。打印URL，然后保持运行（Ctrl-C停止）。 bun run start # 可选地，在启动时打开一个Obsidian保险库（持久化为托管源）： bun run start --vault ~/Documents/MyVault # 打印ADMIN连接密钥（管理凭证 - 您用它访问/admin；**绝不**交给代理）。从 ~/.plexus/ 读取，无需服务器： bun run start --print-key # 证明整个发现 → 授权 → 调用循环端到端（自包含，无需设置）： bun run demo ``` 首次运行是自动的：网关创建 `~/.plexus/` （连接密钥，签名密钥，审计日志）在首次启动时 - 无需配置。在 `http://127.0.0.1:7077/admin` 打开管理UI，以添加源，批准授权，并读取审计跟踪。它与网关同源提供服务，因此页面的HTML/资产加载无需密钥 - 但每个 `/admin/api/*` 调用仍需要连接密钥。 **桌面应用程序（Electron，macOS）：** 一个**开发者运行**的托盘壳作为一个 sidecar 监督运行时，并托管相同的管理UI，具有原生批准通知。签名/ notarized 分发和自动更新 **延期** （当前构建是 unsigned）。从桌面软件包运行它： ```sh bun run --cwd packages/desktop start ``` **→ 完整指南： [`docs/README.md`](docs/README.md)** - 开发者阅读路径：安装，启动，添加源，连接代理（生成一次性代码 + 授予起始能力集），并批准具有信任窗口选择器的授权。 --- ## 概念（60秒模型） **两个凭证，绝不混淆。** 这是整个信任故事： - **连接密钥** （`plx_live_…`）- **管理员/管理**凭证和信任边界。所有者作为管理员持有它；旋转它会一次性撤销所有内容。 **代理绝不会看到或使用它。** - **每个代理的PAT** （`plx_agent_…`）- 每个代理的**自己的持久凭证**。它被**一次性**从一次性注册码兑换，存储在本地（0600），并且可以按代理撤销。PAT身份验证的握手绑定了**实际的**代理ID - 代理不能**自我声明**其他人的身份。 **流程是管理员 → 代理，而不是代理帮助自己：** 1. **管理员连接代理。** 在控制台的 **连接代理** 向导（或 `POST /admin/api/agents/connect`）中，您命名代理，授予它一个**起始能力集**，并且普勒克斯生成一个**一次性注册码** （`plx_enroll_…`，15分钟，仅限一次使用）。您交给代理 **一条命令** - 绝不是连接密钥。 2. **代理安装一次。** 它运行安装命令（`curl -fsSL <gateway>/integration/<agentId>/install.sh | …`），兑换代码 → 存储其 **PAT** （0600）→ 下降一个编译的插件，在其PATH上公开一个代理特定的启动器 **`plexus-<agentId>`**。 3. **代理通过其启动器发现 + 调用。** `plexus-<agentId> list` 显示它**当前**可以调用的内容（已授予）与**需要批准**的内容；`plexus-<agentId> <capabilityId>` 调用。**该启动器是代理的完整且唯一的接口** - 它绝不手工编写HTTP，也绝不猜测身份验证。 您**公开**的内容被建模为 **连接器 → 源 → 能力**：一个托管源（例如，Obsidian保险库）注册能力（例如，`obsidian.vault.read`）实时**无需重启** - 它们立即出现在管理界面中，代理在所有者将它们添加到该代理的**授权子集**后发现它们。您**信任**的内容是一个统一的模型： 按能力范围的**授权**，**信任窗口**（`once` / `1h` / `1d` / `7d` / `直到撤销`），**3类来源**（第一方 / 托管 / 扩展），**敏感性**评级，以及 **`GET /grants`** 账本，其中每个授权都可见且可撤销。 **持久性由敏感性决定，而不是来源。** 一个 `read` 能力在连接时**持久**（无缝重用，1d/7d） 。具有副作用的能力（**写入/执行**，例如 `claudecode.run`）默认情况下**每次使用都需要批准** - 代理无法自行提升权限。只有**所有者**可以提升权限，按代理和能力：**持久**在连接时选择（默认为**关闭**，双重确认 - 唯一路径为 `execute`），或对于 `write`，批准其待处理请求，具有真正的信任窗口或直接授予；一旦提升，它将使用真正的信任窗口 / 直到撤销。 **代理接口是编译的，而不是附加的。** 每个代理的启动器在 **Claude Code** 插件中提供，该插件是 **投影到始终存在的自我描述层**（`.well-known` + `requestShapes` + 如何使用）。该层适用于**任何**代理，无需插件；插件是缓存/快捷方式，使相同能力感觉更原生于每个代理 - 绝不是替换，并且绝不是在其中嵌入持久密钥。 **→ 深入了解： [`docs/concepts.md`](docs/concepts.md)** · **安全模型： [`docs/design/security-model.md`](docs/design/security-model.md)** · **协议合同： [`docs/protocol/PLEXUS-PROTOCOL.md`](docs/protocol/PLEXUS-PROTOCOL.md)** --- ## 公开的内容 **第一方来源** （macOS优先；**代码 + 密封测试验证** - 实时E2E针对真正的macOS TCC应用程序**未在此版本运行**，请参见 [KNOWN-LIMITATIONS](docs/KNOWN-LIMITATIONS.md))： - **Obsidian** - 只读路径限定文件系统读取（`obsidian.vault.read`），或通过Obsidian Local REST API插件进行读写（`obsidian-rest.vault.{list,read,write}`）。 - **Apple Calendar** - 只读（`grants:["read"]` 通过构造）。 - **Apple Reminders** - 读取 **和** 写入。 - **Apple Notes** - 读取 + **仅创建**写入（`apple-notes.notes.create`；无更新/删除）。 - **Apple Mail** - 严格**只读**（邮箱，有限搜索，读取一条消息；无草稿/发送）。 - **Apple Contacts** - 只读搜索 + 全卡读取。 - **Apple Photos** - 读取姿势：相册，仅元数据搜索，和一个隔离的导出（`~/.plexus/exports/photos/`）。 - **Shortcuts** - 列表（读取）+ 运行（**执行** → 待处理；默认为记录模式，实际启动为所有者选择）。 - **浏览器** - 只读Safari/Chrome标签页，书签，历史记录（每个浏览器逐渐降级）。 - **工作区** （`workspace`）- 一个授权的工作目录作为路径限定的文件系统：读取（`workspace.{list,read}`）**和**写入（`workspace.write` → 待处理）。 - **Claude Code** （`claudecode`）- macOS `sandbox-exec` 隔离下的无头Claude Code （`claudecode.run`，**执行** → 待处理）。 - **Codex** （`codex`）- 无头 `codex exec` 在相同的沙盒隔离下，是 `claudecode.run` 的镜像（`codex.run`，**执行** → 待处理）。 每个源报告其自己的**健康状态**（代理面向的字段 + 通过 `GET /admin/api/health` 的管理仪表板），因此代理 - 和您 - 可以在调用失败前看到后台应用程序是否不可达。 **用户扩展** - 编写一个清单，**预览安全界面**（cli二进制文件，rest主机，跨源附件，按能力动词），然后实时安装： ```sh plexus extension preview ./my-source.json # 验证 + 显示安全界面（无提交） plexus extension add ./my-source.json # 实时安装（您是人类批准者） plexus extension list plexus extension remove my-source ``` 或从 `/admin` UI执行所有操作。**作者指南**用于编码代理，在 `GET /admin/api/extensions/authoring-guide` 处提供。 **→ 教程：** [连接代理](docs/tutorials/connect-an-agent.md) · [创建扩展](docs/tutorials/create-an-extension.md) · [第一方来源](docs/tutorials/first-party-sources.md) --- ## 截图 **概览** - 仪表板：公开的内容，需要您的内容，近期活动。  **我公开的内容** - 连接器 → 源 → 能力界面，具有用于添加源的动态配置表单。  **创建扩展** - 编写一个清单，并在安装前预览其安全界面。  --- ## 安全姿势 - **默认回环。** 网关默认绑定到 `127.0.0.1`。绑定到选择的NIC或 `0.0.0.0` 是**需要选择**的（`~/.plexus/network.json`），并且当您这样做时，**每个 `/admin/api/*` 路由都是连接密钥保护的** - 连接密钥成为LAN的信任边界。 - **主机/源保护** 每个端点上的身份验证（DNS重绑定防御）；请求没有匹配的 `Host` 被拒绝（`host_forbidden`，403）。 - **默认拒绝，范围限定调用。** 授权按能力和动词范围限定；令牌寿命有限。变异（`write`/`execute`）授权待处理人类 - 代理**不能**自行授权。 - **更改时重新授权。** 重新配置源的端点/密钥会清除其授权，因此之前的授权不能**无声**地延续到新目标。 - 密钥存储在 `~/.plexus/secrets/` 下，并通过**名称**引用 - 绝不写入配置文件中，绝不回显。 **→ 完整说明： [`docs/security.md`](docs/security.md)** --- ## macOS优先，具有真正的跨平台缝隙 普勒克斯是一个 **Bun + TypeScript + Hono** 工作区 monorepo： ``` packages/ protocol/ 关键部分 - 编译器强制执行的线协议（冻结在 0.1.3） runtime/ 无头回环网关（发现，授权，调用，审计，来源） cli/ `plexus` CLI（发现 / 清单 / 技能 / 调用 / 源 / 扩展 / 捆绑） web-admin/ 同源React管理UI desktop/ Electron shell（macOS）- 监督器 + 托盘 + 原生通知 ``` OS表面生活在单个 `PlatformServices` 缝隙下：macOS是已发货的**完全实现**的目标，而 **Linux 已实现并端到端验证** - 无头可移植网关在真正的Linux内核中运行在Docker中（Ubuntu + Bun；参见 [`docs/deploy-linux.md`](docs/deploy-linux.md）），自动门控第一方源到可移植 `{workspace, sysinfo}` 集。**Windows** 在**相同缝隙**下实现，但尚未在真正的Windows主机上验证 - 因此跨平台是一个填入，不是重写。 **协议冻结在 `PLEXUS_PROTOCOL_VERSION = 0.1.3`** 并且**仅限增加** - 新增可选字段，从不更改线路协议。 --- ## 版本控制 - 两个数字，两个时钟 普勒克斯带有 **两个独立的版本号**，并且区别很重要： | | 是什么 | 如何移动 | 谁依赖它 | |---|---|---|---| | **软件版本** （`PLEXUS_VERSION`，例如 `0.7.0`）| **产品**发布 - 网关，桌面应用，源，UI | **快速** - 每个功能/修复都会增加 | 线上代理；这是信息性显示（在管理界面中显示为 `running · v0.7.0`） | | **协议版本** （`PLEXUS_PROTOCOL_VERSION`，`0.1.3`）| **代理端线路协议** - 发现/握手/授权/调用的形状 | **很少** - 冻结，**仅限增加**（新增可选字段会增加补丁） | **代理**将其集成到这里，而不是软件版本 | 它们 **按设计解耦**：产品可以从 `0.6 → 0.7 → 1.0 …` 而协议保持 `0.1.x`，因为 **线路在快速移动的应用下是稳定的**。集成了协议 `0.1.0` 的代理在每个软件版本都有效 - 它只需要关注 *协议* 版本的变化（即使如此，也是一个代理集成到这里，而不是应用程序版本。 > 标签/发布跟踪软件版本（`v0.7.0`）。协议版本存在于代码（`@plexus/protocol`）和 `.well-known/plexus` 中，并按其自己的计划进行更新。 --- ## 构建，测试，类型检查 ```sh bash run-tests.sh # 规范的门控：bunx tsc --noEmit（严格）+ bun test bunx tsc --noEmit # 仅类型检查 bun test # 仅测试 ``` 参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解 monorepo 布局，协议的附加规则，以及如何编写源模块或扩展。 --- ## 文档 | 文档 | 涵盖内容 | | --- | --- | | **[开发者阅读路径](docs/README.md)** | **从这里开始理解 + 构建** - 文档的脊柱，按顺序排列。 | | [快速入门（macOS）](docs/getting-started.md) | 安装 → 启动 → 连接代理（生成代码 + 授权能力集），端到端。 | | [概念](docs/concepts.md) | 自我描述协议，信任模型，来源和扩展。 | | [安全](docs/security.md) | 回环边界，连接密钥，主机/源保护，重构。 | | [连接代理](docs/tutorials/connect-an-agent.md) | 从编码代理驱动普勒克斯。 | | [创建扩展](docs/tutorials/create-an-extension.md) | 编写 + 预览 + 安装清单。 | | [第一方来源](docs/tutorials/first-party-sources.md) | Obsidian，Apple Calendar/Reminders/Notes/Mail/Contacts/Photos，Shortcuts，浏览器，Claude Code。 | | [协议合同](docs/protocol/PLEXUS-PROTOCOL.md) | 冻结线路规范 + ADR。 | | [已知限制](docs/KNOWN-LIMITATIONS.md) | 诚实的 0.1 前状态：MCP 导入，`io.input` 范围，桌面/跨平台未完全 E2E 验证。 | --- ## 贡献与行为准则 欢迎贡献 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。本项目遵循 [贡献者契约](CODE_OF_CONDUCT.md)。 ## 许可 [MIT](LICENSE) © 2026 Plexus contributors.