<p align="center"> <br> <img src="https://raw.githubusercontent.com/notasithlord/peerd/HEAD/docs/store/assets/peerd-wordmark.svg" alt="peerd" width="240" height="48"> <br> <br> </p> [](https://github.com/NotASithLord/peerd/actions/workflows/package-and-release.yml) [](packaging/check-tscheck.ts) [](tests) [](scripts/cdp/run-inbrowser-tests.mjs) [](scripts/firefox/run-runtime-tests.mjs) [](scripts/cdp/run-e2e-verify.mjs) [](docs/security/RED-TEAM-RESULTS.md) [](CONTRIBUTING.md) [](extension/vendor/vendor.lock.json) [](packaging/check-action-pins.ts) [](LICENSE) [](#install) [](SECURITY.md) # 首个原生 Web AI 智能体框架 peerd 是首个直接构建于浏览器原生能力之上的通用智能体运行时：Workers、源（origins）、沙箱、OPFS、WASM/WASI、WebRTC、WebAuthn 和 WebExtensions。它完全运行在 Chrome 和 Firefox 内部，使用你的标签页、已登录会话、Web 应用和本地算力。 **当其他智能体平台试图将浏览器拉入其框架时，peerd 将框架拉入浏览器。** 对于实际推理，你可以选择受支持的托管模型提供商、使用 localhost 的本地模型，或查看对本地 WebGPU 模型的初步支持（我们也在关注 WebNN）。 无需 peerd 账户、托管浏览器或工具服务器连接。当前版本不会向 peerd 发送任何产品遥测数据。 [安装](#install) · [peerd.ai](https://peerd.ai) · [架构](#architecture) · [安全](https://github.com/notasithlord/peerd/blob/main/SECURITY.md) ## 功能特性 - **在你已使用的浏览器中工作。** 智能体可以读取并驱动你的标签页、Web 应用、已登录会话和页面内容。 - **构建可复用的站点客户端。** Web 执行体可以学习一个站点一次，并在后续任务中再次使用该客户端。 - **在浏览器边界内运行代码。** 脚本、密封的 JavaScript Notebook、编译后的 WASI 工具、浏览器 Apps 和 Linux WebVM 为智能体提供本地算力，而无需访问你的主机操作系统。 - **委派给独立的执行体。** 每个页面和计算环境都拥有自己的无密钥执行体，其工具限定于该环境。 - **保留有用的上下文。** 会话、记忆、技能、目标、审查和检查点都保存在扩展中。 - **使用你选择的模型。** 实时提供商清单定义于 [`registry.js`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-provider/registry.js)，包括 BYOK 云适配器和无密钥本地选项。 - **直接连接浏览器。** 预览版构建增加了签名身份、浏览器间发现、dwapps 以及通过 WebRTC 的智能体间通信；商店版则完全裁剪掉这些功能。 ## 为什么选择浏览器 本地智能体可以访问你的整台计算机。远程智能体则存在于他人的计算机中。浏览器是另一种选择：本地能力被置于经过三十多年加固的安全边界之后。 peerd 使用这些边界。页面工作被分配给独立的执行体，仅拥有该标签页或环境所需的工具。凭据、网络规则、确认和审计保留在扩展中。其纵深防御设计假设不安全的内容最终会绕过过滤器。 ## 浏览器支持 peerd 支持 Chromium 和 Firefox。Firefox 在专用 worker 中运行执行体，并使用可见的 Notebook 进行 JavaScript 计算。需要 Chrome 离屏文档宿主的功能会在使用前从 Firefox 控件和模型工具中移除。Firefox 预览版构建在 Firefox 拥有 mesh 宿主之前省略 dweb。 Apps 和 WebVM 运行在 Chrome 上。Apps 没有环境网络访问权限。远程资源、fetch、WebRTC、表单和外部文档导航均被阻止。外部 HTTP 和 HTTPS 链接需要用户确认。 具体的浏览器能力差距、其上游问题以及移除每个防护所需的测试，均记录在 [`docs/BROWSER-COMPATIBILITY.md`](https://github.com/notasithlord/peerd/blob/main/docs/BROWSER-COMPATIBILITY.md) 中。 代码是当前行为的权威来源。从 [`CLAUDE.md`](https://github.com/notasithlord/peerd/blob/main/CLAUDE.md) 开始阅读，然后阅读 `extension/` 下的相关模块。 ## 安全模型 peerd 使用浏览器隔离、狭窄的工具暴露面、service-worker 策略门控和明确的出口控制。主智能体将环境工作委派给无密钥执行体。在 Chrome 和 Firefox 上，非编排器智能体循环运行在独立的专用 worker 堆中。如果浏览器无法证明该边界，执行体请求将不会运行，也不会对其目标执行任何工作。 网络行为取决于操作类型。模型调用、网页读取、运行时资源加载、沙箱流量和预览 dweb 流量使用不同的作用域路径和策略。有关当前边界和已知限制，请参阅 [`SECURITY.md`](https://github.com/notasithlord/peerd/blob/main/SECURITY.md) 和 [`威胁模型`](https://github.com/notasithlord/peerd/blob/main/docs/security/THREAT-MODEL.md)。 ## 安装 ### 从源码安装 Chrome 版 1. 克隆仓库。 2. 打开 `chrome://extensions`。 3. 启用开发者模式。 4. 选择 **加载已解压的扩展程序** 并选择 `extension/` 目录。 源码更改后，从 `chrome://extensions` 重新加载扩展。 ### 从源码安装 Firefox 版 Firefox 需要特定于 Firefox 的包。不要加载已签入的 Chrome 开发清单。请使用版本不低于 `manifests/` 下渠道补丁中声明的最低版本的 Firefox。该下限跟踪浏览器工具使用的文档绑定脚本支持。 ```sh bun run package -- --channel=preview --browser=firefox --no-sign ``` 打开 `about:debugging#/runtime/this-firefox`，选择 **临时载入附加组件**，然后选择 `artifacts/peerd-preview-firefox.xpi`。Firefox 重启后必须重新加载临时附加组件。浏览器和渠道转换由打包脚本定义。 ### 发布包 有关当前工件，请参阅 [GitHub Releases](https://github.com/NotASithLord/peerd/releases)。商店版和预览版构建有所不同。商店版构建省略 dweb。预览版构建包含 dweb，并可能启用额外的自动化功能。打包代码是每个浏览器和渠道的权威依据。 ## 首次运行 1. 从浏览器工具栏打开 peerd。 2. 创建并解锁本地保险库。口令解锁始终可用。通行密钥解锁取决于浏览器和设备对 WebAuthn PRF 的支持。 3. 完成简短的个人资料引导。 4. 打开设置，然后添加提供商密钥或选择受支持的本地提供商。 5. 选择模型并开始聊天。 只有保险库机密和受保护的安全记录受保险库加密边界保护。其他本地扩展状态遵循安全文档中的存储规则。 ## 架构 该扩展有五个主要模块。每个模块通过其 `index.js` 公开其公共 API。 | 模块 | 角色 | |---|---| | [`peerd-provider`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-provider) | 模型适配器和响应格式化 | | [`peerd-egress`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-egress) | 保险库、网络策略、拒绝列表和审计 | | [`peerd-engine`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-engine) | WebVM、Notebook、App 和无头执行 | | [`peerd-runtime`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-runtime) | 智能体循环、执行体、工具、会话、记忆和权限 | | [`peerd-distributed`](https://github.com/notasithlord/peerd/blob/main/extension/peerd-distributed) | 仅预览版的点对点网络和 dwapps | 扩展主体位于 `background/`、`offscreen/`、`sidepanel/`、`engine-tabs/`、`permissions/`、`shared/` 及相关支持目录中。宿主放置和冷 worker 规则记录在 [`docs/EXTENSION-HOSTS.md`](https://github.com/notasithlord/peerd/blob/main/docs/EXTENSION-HOSTS.md) 中。 ## 开发 源码扩展是使用 ES 模块的纯 JavaScript，在加载为已解压扩展时直接运行。没有开发打包器、转译器、监视器或生成的运行时树。发布打包仅在一次性暂存副本上使用 Bun，以从静态 service-worker 和 Chrome 离屏冷图中移除作者模块中的空白和注释。它保留模块边界、绑定名称、惰性导入和每个供应商字节。当可读的诊断工件有用时，向 `bun run package -- ...` 传递 `--no-minify`。 ```sh bun install bun run gen:dev bun test ./tests bun scripts/cdp/run-inbrowser-tests.mjs bun run typecheck bun run lint bun run e2e:verify bun run preflight ``` 有三个测试面： - 纯逻辑的 Bun 测试。 - 扩展和浏览器集成的浏览器内测试。它们在 Chrome 下无头运行，并在 Gecko 下分片运行，针对已安装的 Firefox 商店包。每个通道执行其注册的每个测试；总数略有不同，因为某些测试仅在实时 service worker 响应时注册。 - 用于完整流程的实时 Chrome E2E 和视觉验证。 此外，[`tests/red-team/`](https://github.com/notasithlord/peerd/blob/main/tests/red-team) 中的红队套件驱动威胁模型中的每个对手针对真实防御代码，并记录每个恶意探测是否被阻止。其矩阵位于 [`docs/security/RED-TEAM-RESULTS.md`](https://github.com/notasithlord/peerd/blob/main/docs/security/RED-TEAM-RESULTS.md)。 每个通道发布自己的计数作为上面的徽章。`badges/` 下的徽章 JSON 由运行该通道的 CI 作业生成，然后进行差异比较，因此此页面上的计数始终是实际运行过的证据，而不是某人输入的数字。使用 `bun run gen:badge:functional`、`bun run gen:badge:red-team`、`bun run gen:badge:inbrowser`、`bun run gen:badge:gecko`（需要 Firefox 和 geckodriver）或 `bun run gen:badge:e2e` 重新生成一个，并提交结果。`bun run check:badges` 验证端点格式正确，而无需启动浏览器。 对于 UI 更改，运行 `bun run e2e:verify`，检查 `scripts/cdp/artifacts/result.json`，并检查生成的截图。 生成的文件不得手动编辑。特别是，`extension/manifest.json` 和 `extension/shared/channel-config.js` 来自清单和打包源。CI 会检查它们是否有漂移。 在更改代码之前，请阅读 [`CONTRIBUTING.md`](https://github.com/notasithlord/peerd/blob/main/CONTRIBUTING.md)。 ## 文档 - [`CLAUDE.md`](https://github.com/notasithlord/peerd/blob/main/CLAUDE.md)：项目结构、约定和当前状态 - [`SECURITY.md`](https://github.com/notasithlord/peerd/blob/main/SECURITY.md)：安全策略和报告 - [`docs/security/THREAT-MODEL.md`](https://github.com/notasithlord/peerd/blob/main/docs/security/THREAT-MODEL.md)：信任边界和残余风险 - [`docs/security/LIFECYCLE-CONTRACT.md`](https://github.com/notasithlord/peerd/blob/main/docs/security/LIFECYCLE-CONTRACT.md)：中断行为和恢复限制 - [`docs/security/RED-TEAM-RESULTS.md`](https://github.com/notasithlord/peerd/blob/main/docs/security/RED-TEAM-RESULTS.md)：红队覆盖范围 - [`docs/APP-ACTORS.md`](https://github.com/notasithlord/peerd/blob/main/docs/APP-ACTORS.md)：清单定义的 App 执行体、实时语义适配器和标签页内协同驾驶 UX - [`docs/DWAPP-BUNDLE.md`](https://github.com/notasithlord/peerd/blob/main/docs/DWAPP-BUNDLE.md)：压缩的 dwapp 传输、解码的工作树和二进制资产 - [`docs/store/`](https://github.com/notasithlord/peerd/blob/main/docs/store)：商店打包、权限、隐私和审核员说明 - [`scripts/cdp/states.mjs`](https://github.com/notasithlord/peerd/blob/main/scripts/cdp/states.mjs)：E2E 和视觉状态 ## 依赖和许可证 发布的扩展没有 npm 运行时依赖。`package.json` 声明无依赖，打包从不将 `node_modules` 路径解析到暂存工件中，因此开发工具树无法到达已安装的浏览器。第三方运行时代码改为在 `extension/vendor/` 下供应商化。其源码、版本和许可证位于相邻的 `SOURCE.txt` 文件中，每个供应商字节都通过 SHA-256 固定在 [`extension/vendor/vendor.lock.json`](https://github.com/notasithlord/peerd/blob/main/extension/vendor/vendor.lock.json) 中，`bun run check:vendor` 在 CI 和预检中验证该文件。 另外两个供应链位置带有自己的徽章，均由 `bun run gen:dev` 重新生成并在 CI 中进行漂移检查。每个第三方 GitHub Action 都在完整的提交 SHA 上运行，由 [`check:actions`](https://github.com/notasithlord/peerd/blob/main/packaging/check-action-pins.ts) 门控：主标签是发布者可以移动的可变引用，这意味着持有此检出以及发布工作流中签名密钥的作业中可能包含任意代码。新解析的依赖项在进入锁文件之前还要经过隔离期，由 [`bunfig.toml`](https://github.com/notasithlord/peerd/blob/main/bunfig.toml) 中的 `minimumReleaseAge` 设置，同时在安装时进行恶意软件扫描。 peerd 根据 [Apache License 2.0](https://github.com/notasithlord/peerd/blob/main/LICENSE) 许可。供应商组件保留其自己的许可证。CheerpX 是 Leaning Technologies 提供的专有运行时，不受 peerd 的 Apache 许可证覆盖。
