AgentHost

# AgentHost AgentHost 是一个本地的 MCP 运行时，为 Codex 和其他代理提供了一个受管制的实体，运行在 Linux 工作站上。它为文件、shell、桌面、辅助功能、浏览器、本地视觉、语音和视觉辅助等提供了有限的能力，同时将策略、授权、确认、回执、检查点、编辑和审计日志等保持在本地。 AgentHost 是通用的，与提供商无关。Gmail、WhatsApp、Slack、Blender 等应用程序名称仅为示例，而非内置产品目标。 ## 状态和支持 当前的公共边界是一个 Linux x86_64 源代码检查或经过验证的 Linux 存档/CLI 发布。 - Node.js 20+ 和 Python 3 是主机运行的必要条件。 - X11 是经过验证的可见叠加层路径；Wayland 报告了诚实的限制。 - Firefox 和 Chromium 浏览器桥扩展目前是解包的/手动开发工件，直到发布签名/存储版本。 - MCP 服务器基于标准输入输出；浏览器和控制室监听器仅限于本地环回且除非显式启用。 - 根 npm 包仍然是私有的；不保证 npm 发布。 状态更改操作仍然是策略、授权、干预运行、精确目标和确认门控的。工作流重放和调度器记录仅为元数据。视觉表面永远不会控制目标应用程序。 ## 最快启动：发布存档 对于下载的、校验和验证的 Linux 存档： ```bash sha256sum -c agenthost-v0.1.0-linux-x64.tar.gz.sha256 tar -xzf agenthost-v0.1.0-linux-x64.tar.gz cd agenthost-v0.1.0-linux-x64 ./bin/agenthost.mjs doctor ./bin/agenthost.mjs setup ./bin/agenthost.mjs integrations codex add --apply ./bin/agenthost.mjs start ``` 存档包装器可以直接运行。本地发布安装可以在 `~/.local/bin` 下创建 `agenthost` 命令： ```bash npm run release:install -- release/agenthost-v0.1.0-linux-x64.tar.gz agenthost doctor agenthost setup agenthost integrations codex add --apply agenthost start ``` AgentHost 只写入其自己的用户目录。这些命令不使用 `sudo`、安装系统包、创建系统服务或静默安装浏览器扩展。有关更新、回滚和诊断，请参见 [发布操作](docs/08_RELEASE_AND_OPERATIONS.md)。 ## 源代码检查 对于贡献者和本地开发，请使用此路径： ```bash git clone https://github.com/abdelazizfacoiti/AgentHost.git cd AgentHost npm install npm run build npm run smoke:mcp ``` 在单独的终端中启动 MCP 服务器。隔离的主页将开发状态与正常的 AgentHost 安装分开： ```bash export AGENTHOST_HOME="$PWD/.agenthost" export AGENTHOST_CONFIG="$PWD/.agenthost/config.json" npm run start:mcp ``` 使用以下命令运行完整的本地验证套件： ```bash npm test npm run lint npm run benchmark:routing ``` ## MCP 客户端配置 发布安装后，MCP 客户端可以使用以下配置启动 AgentHost： ```json { "mcpServers": { "agenthost": { "command": "agenthost", "args": ["start"] } } } ``` 对于源代码检查，请使用内置的 MCP 入口点，并在客户端环境中设置隔离的主页和配置： ```json { "mcpServers": { "agenthost": { "command": "node", "args": ["/absolute/path/to/AgentHost/packages/mcp-server/dist/index.js"], "env": { "AGENTHOST_HOME": "/absolute/path/to/AgentHost/.agenthost", "AGENTHOST_CONFIG": "/absolute/path/to/AgentHost/.agenthost/config.json" } } } } ``` 服务器在标准输出上保持正常的诊断信息，以便 MCP 标准输入输出保持有效。 ## 浏览器桥：快速连接 浏览器桥为 AgentHost 提供了结构化的选项卡和 DOM 信息，无需 cookie、密码、浏览器存储、任意 JavaScript 或直接选择器执行。它默认禁用，仅绑定到 `127.0.0.1`。 ### 已安装的发布版本 选择一个浏览器并运行显式的设置流程： ```bash agenthost browser setup --browser firefox --apply # 或： agenthost browser setup --browser chromium --apply ``` 命令准备解包的扩展，启用本地桥，等待注册，验证重新连接，并打印确切的扩展目录。在等待过程中： 1. Firefox：打开 `about:debugging#/runtime/this-firefox`，选择 **加载临时附加组件…**，然后选择打印的 `manifest.json`。 2. Chromium：打开 `chrome://extensions`，启用 **开发者模式**，然后选择 **加载解包**，进入打印的浏览器目录。 3. 打开 AgentHost 扩展弹出窗口，并确认环回端口（默认为 `43117`）。 4. 选择 **与 AgentHost 配对**。 5. 在 AgentHost 终端提示中批准确切的扩展身份。 6. 等待重新连接验证，然后运行 `agenthost browser status`。 ### 源代码检查 准备隔离的源代码设置，然后在同一环境中启动 MCP： ```bash export AGENTHOST_HOME="$PWD/.agenthost" export AGENTHOST_CONFIG="$PWD/.agenthost/config.json" export AGENTHOST_BROWSER_EXTENSION_DIR="$PWD/.agenthost/browser-extension" npm run browser:setup ``` `npm run browser:setup` 准备解包的工件并打印其确切路径。它不启动注册。选择一个浏览器，然后在终端 1 中运行配对命令： ```bash npm run build npm run browser:pair -- --browser firefox --apply --approve # 或：npm run browser:pair -- --browser chromium --apply --approve ``` 让该命令运行。它启动有限的本地注册会话并打印要加载的确切清单/目录。在 Firefox 中使用 `about:debugging#/runtime/this-firefox` → **加载临时附加组件…**；在 Chromium 中使用 `chrome://extensions` → **开发者模式** → **加载解包**。打开扩展弹出窗口并单击 **与 AgentHost 配对**。在命令报告浏览器桥就绪后，在终端 2 中启动正常的 MCP： ```bash npm run start:mcp ``` 不要将 `npm run start:mcp` 用作配对命令：它提供 MCP 服务但不创建注册会话。使用 `browser.setup_status`、`browser.diagnose_bridge` 和 `browser.verify_pairing` 进行恢复和实时状态。新设置使用基于浏览器的注册；一次性令牌仅作为旧版修复路径，不适用于全新设置。配对凭证不会被记录，第二个浏览器会话将被拒绝。 ### 第一次安全浏览器检查 使用公共或用户控制的本地测试页面 - 不是通信、财务、凭证、MFA、CAPTCHA 或管理页面 - 然后按顺序调用这些固定的 MCP 工具： ```text browser.detect browser.setup_status browser.verify_pairing browser.list_tabs browser.get_active_tab browser.current_url browser.get_page_context browser.find_element ``` 在测试来源的扩展弹出窗口中显式授予站点访问权限。元素操作需要短期的不透明 `elementId` 引用，并且仍然受策略、授权、干运行、确认和验证的约束。如果扩展不可用，AgentHost 将报告干净的故障，并可能建议辅助功能、本地 OCR/视觉、指针回退或引导模式；它永远不会静默切换。 参见 [浏览器设置验证](docs/06_BROWSER_SETUP_VALIDATION.md) 和 [浏览器扩展发布](docs/07_BROWSER_EXTENSION_RELEASE.md)，了解重置、重新连接、签名和故障排除详细信息。 ## 视觉飞行员演示 演示使用权威的编辑运行时活动，永不点击、输入、导航、移动真实指针或控制目标应用程序： ```bash npm run demo:visual-copilot -- --diagnose npm run demo:visual-copilot -- --headless npm run demo:visual-copilot -- --require-gui ``` 在 X11 上首先使用 `--diagnose`。 `--require-gui` 在握手、透明度、映射、准备就绪、纪元、实时注册和可见性确认全部成功之前关闭。参见 [DEMO.md](DEMO.md) 进行手动检查。 ## 安全边界 AgentHost 设计为显式和可检查的： - 没有公共网络监听器、隐藏的持久性或自主后台工作； - 没有凭证/秘密提取、CAPTCHA/MFA/登录/支付绕过或 sudo； - 没有静默发送、提交、上传、删除、存档、支付、购买或发布； - 没有任意生成的 JavaScript/Python 执行； - 没有浏览器 cookie/存储/调试器访问； - 没有调度器执行或工作流重放工作线程； - 日志、回执、指标、叠加层或控制室投影中没有原始私有页面文本、OCR、截图、令牌或秘密。 支持的外部或破坏性影响仍然是精确目标、授权、确认、验证和回执管控的。 不支持、保护、模糊或无法验证的影响会返回精确的诊断信息或引导模式。 ## 文档和贡献 - [规范文档索引](docs/INDEX.md) - [产品规格](docs/01_PRODUCT_SPEC.md) - [系统架构](docs/02_SYSTEM_ARCHITECTURE.md) - [MCP 工具和适配器](docs/03_MCP_TOOLS_AND_ADAPTERS.md) - [安全、权限和日志](docs/04_SECURITY_PERMISSIONS_AND_LOGGING.md) - [发布操作](docs/08_RELEASE_AND_OPERATIONS.md) - [隐私和支持](docs/11_PRIVACY_AND_SUPPORT.md) - [贡献](CONTRIBUTING.md) - [安全报告](SECURITY.md) - [支持](SUPPORT.md) - [行为准则](CODE_OF_CONDUCT.md) 示例中的提供商名称仅为示例。新功能必须保持应用无关、模式验证、策略门控、编辑和可审计。 ## 许可证 AgentHost 在 Apache-2.0 下获得许可。参见 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)。GTK3、Tesseract、eSpeak NG 和 Bubblewrap 等主机程序仍然单独获得许可，不由 AgentHost 捆绑。