--- title: Local App summary: 由 Agent 托管的交互界面，其请求与事件流转机制，以及共享会话访问的边界。 order: 120 --- # Local App Local App 是由特定 Agent 托管的静态 HTML 与 JavaScript 交互界面。它可以呈现针对特定业务的视图、收集用户输入，或为专属工作流提供可视化操作控件。App 的静态文件存放在该 Agent 的 `apps/` 目录下，用户通过统一的逻辑路由在浏览器中访问。 App 也可以是静态站点或未预压缩、单线程的 Unity Web 构建。根目录下没有 `manifest.json` 时，只需提供 `index.html`：运行时在内存中推导元数据，不修改构建产物。显式清单仍控制元数据和自定义入口；损坏的清单会报错，不会触发入口猜测。 例如，文档维护 Agent 可以托管一个排队审查界面，并在界面中放置一个触发死链检查的按钮。该 App 负责展示队列并发送请求，Agent 则执行经过授权的操作并返回最终结果。 ## 与其他界面的关系 Web GUI 是用于管理整个 Holon 运行时的通用客户端；而 Local App 则是服务于特定场景、归属于某个 Agent 的轻量级界面。后者的静态文件与 Web GUI 自身的前端实现彼此独立。 Skill 说明如何执行某套工作流程，工具（Tool）负责调用系统能力。Local App 可以为这一流程提供可视化的人机交互入口，但它既不能替代 Skill，也不能替代工具。在界面上增加一个“执行检查”的按钮，并不会凭空创造出新的运行时能力。 ## 请求与事件流 浏览器端 SDK 提供应用的运行上下文、请求方法以及事件流监听机制。上下文标识该 App 自身、所属 Agent 以及会话状态；请求方法用于向 Agent 提交结构化输入；事件流则反映该 App 相关的运行时活动。 在上述排队审查界面的例子中，请求成功返回仅代表运行时已受理该操作，并不代表死链检查已经通过，甚至不代表 Agent 已经处理完毕。前端界面必须明确区分已受理（accepted）、排队中（pending）与已完成（completed）状态，并在结果就绪时展示真实数据。 当前的事件流主要推送请求入队与任务开始处理等事件，不会持续推送最终业务成果或 Agent 的全部底层行为。App 必须通过与其流程相适应的结果通道获取最终结论，不能把“开始处理”当成“处理完成”。由于重放缓冲有限，网络断开重连后，应当直接查询工作状态，而不是假设收不到事件就代表什么都没发生。详见[交付结果与产物位置](./results-and-artifacts.md)。 ## 身份、会话与权限边界 App 的访问路由标识所属 Agent 和应用标识，而不会向外暴露 Agent Home 的物理绝对路径。这些路由属于逻辑地址，并非独立的访问凭证。 托管的 App 共享宿主运行时的同源上下文与已认证的浏览器会话。SDK 直接沿用该会话，不具备任何越权能力。请求会完整保留 App 来源标识；无论是按钮文本还是所属 Agent 的身份，都不能把前端提交的文本自动提升为操作者指令。 宿主环境要求文件路径不越出应用根目录、不含隐藏路径，并提供可配置的单文件大小上限（默认 64 MiB）。平台不再按扩展名限制访问，默认也不附加 App 内容安全策略（CSP）。操作者可配置完整的 App CSP；浏览器 CORS 与应用自身的 CSP 仍然生效。这些设置不改变 Web GUI 或 Explorer 的沙箱策略，也不能为每个 App 提供独立来源或隔离互不信任的应用。在能够访问控制平面的浏览器会话中托管 App 之前，务必审查其前端源码。 daemon 运行时，`holon config set` 和 `holon config unset` 通过现有配置 API 持久化这些设置并调度 reload。成功 reload 后，后续 App 请求使用新设置；在途流保留已取得的策略。直接编辑配置文件不会自动触发 reload；离线设置在 daemon 启动或重启后生效。 跨 Agent 的操作依然受制于运行时的严格权限检查。SDK 不包含独立的权限控制机制，也无法绕过运行时的安全约束。 ## 适用场景 当一个轻量、持久的专属界面能让 Agent 的工作成果更直观或更易调用时，使用 Local App 是理想的选择。如果是日常的通用 Agent 管理，Web GUI 或 CLI 已经足够胜任。如果是无人值守的自动化集成，应优先接入 HTTP 控制平面，而无需让浏览器页面常驻。 ## 下一步 - [创建并托管 Local App](../guides/host-local-apps.md) - [Local App 清单与 SDK 参考](../reference/local-apps.md) - [使用 Web GUI](../guides/use-web-gui.md) - [HTTP 自动化](../guides/automate-over-http.md) - [执行与访问边界](./security-and-execution-boundaries.md)