> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 适用场景与产品边界

当你的应用需要把 Agent 作为可观察、可继续、可恢复的后台工作来运行时，Hexagon 提供 Session、Run 和云执行资源的共同管理层。

## 常见场景

| 场景 | 输入与结果 | 需要关注 |
| - | - | - |
| 应用内项目修改 | 上传代码和需求，得到修改后的文件、测试结果与预览 | 文件权限、工具能力、产物限制、预览生命周期 |
| 多轮项目自动化 | 第一轮生成结果，后续在同一工作区继续调整 | 同 Session 单活动 Run、对话保持、空闲恢复差异 |
| 连接外部业务系统 | Agent 读取需求，在授权和审批后写入报告 | 凭据范围、批准前零写入、未知结果对账 |
| 多种执行组合 | 应用使用共同的 SDK，选择不同云环境与 Harness | 能力预检、协议兼容性、精确组合的真实验证 |

## 如何决定是否引入控制平面

如果你只需要在自己的终端运行一次 Harness，可以直接使用该 Harness。如果你希望自己实现全部调度、状态持久化、凭据和资源清理，可以直接使用 Sandbox API。

Hexagon 适用于需要把这些生命周期能力作为应用基础设施的场景。引入它同时意味着你需要运行控制平面和数据库，管理自己的 Provider / 模型账户，并监控未完成的云操作。

## 三条具体应用旅程

### 在你的产品里添加项目功能

用户上传一个小型 Web 项目，要求添加状态筛选。输入是项目文件、明确修改要求和固定验收测试；有用的输出是修改后的源码、实际测试执行结果和获准访问的预览，最后得到可下载产物。模型声称“已完成”不构成验收标准。

这条旅程需要云文件访问与执行、兼容的 Harness／模型组合、持久观察、产物导出，以及界面需要时的私有预览。后端负责把用户映射到 Session 并保留 Run ID。限制包括每 Session 只有一个活动 Run、上传／导出有大小边界、预览依赖运行中的服务和访问授权。公开部署结果时，应将合适的产物交给你的部署系统。参考[项目教程](https://docs.hexagon.autos/zh-CN/start/project-task.md)与[私有预览指南](https://docs.hexagon.autos/zh-CN/build/private-preview.md)。

### 用户离开后继续项目工作

首次请求修改项目，后续请求继续调整同一份工作。输入包括既有 Session ID、新指令及该 Session 已建立的上下文；输出是第二个可独立追踪的 Run 和新产物快照，原 Run 仍可查询。

这需要应用持久保存标识、支持事件重放，并为选定 Harness／Sandbox 验证连续工作策略。浏览器断开时工作可以继续，但授权等待仍占用活动 Run 槽位；Runtime 已中断不能视为健康的继续起点；保留文件不保证保留进程内存。Hexagon 不是独立的跨 Session 记忆产品，领域知识如何保存和检索仍由应用决定。阅读[后端接入](https://docs.hexagon.autos/zh-CN/build/backend-integration.md)、[多轮工作](https://docs.hexagon.autos/zh-CN/build/multi-turn.md)和[持久化边界](https://docs.hexagon.autos/zh-CN/concepts/persistence.md)。

### 执行涉及外部账户的后台任务

任务从外部服务读取需求，修改项目文件，再写回报告。输入是任务、选定 Tool 绑定、可用的账户授权与操作策略；输出除了项目交付物，还包括可独立核对的外部报告标识或结果。

这需要真实模型到 Tool 的完整执行链、可用账户授权，以及策略要求时的审批。应用展示准确的待定操作，并继续观察同一 Run。报告写入响应丢失时，即使报告已经存在，结果也可能仍为 unknown；决定是否再次写入前，先核对原调用。这不是分布式事务，也不承诺跨服务全局 exactly-once。开始阅读 [Tools](https://docs.hexagon.autos/zh-CN/build/tools.md)、[审批](https://docs.hexagon.autos/zh-CN/build/approvals.md)和[恢复](https://docs.hexagon.autos/zh-CN/build/recovery.md)。

## 先比较需要承担的责任

下表比较职责归属，不是性能排名，也不描述每个第三方产品的全部能力。

| 决策 | 直接使用 Harness | 直接使用 Sandbox API | 接入 Hexagon |
| - | - | - | - |
| Agent 执行 | 在选定环境调用 Harness | 通过环境 API 安装并调用 Harness | 选择兼容 Harness，由 Runtime 监督执行 |
| 应用任务身份 | 使用原生标识并增加业务映射 | 自行定义任务记录并映射云资源 | 将业务请求映射到持久 Session／Run ID |
| 观察与恢复 | 适配原生输出和生命周期行为 | 围绕云操作建立持久化、进程观察和对账 | 消费持久事件，按已有恢复契约处理 |
| 凭据与 Tool 决策 | 配置 Harness／环境并落实所需边界 | 建立应用要求的凭据与策略路径 | 配置受保护连接和 broker Tool 策略；后端仍负责业务授权 |
| 长期运行 | 维护所选执行环境 | 维护云编排与故障处理 | 运行控制平面／数据库，管理密钥／备份及 Provider／模型账户 |

只在终端执行的工作流可能不需要 Hexagon 增加的持久应用边界。如果现有平台已经承担同类任务编排，需要明确评估接入和迁移成本。如果需求包含定时调度、忙碌 Session 的排队、公开应用托管或领域记忆层，应指出由哪个外围组件提供，不能仅从 Session 和 Run 的存在推断这些服务已经具备。

## 接入前明确这些边界

* **模型协议**：Messages、Chat Completions、Responses 按 Harness 和端点分别支持，不承诺自动转换或 fallback。
* **预览**：用于访问 Session 内运行的 Web 服务，具有授权和过期限制；不提供通用的生产应用发布承诺。
* **状态**：Run 结果、工作区、Harness 对话和进程内存具有不同持久化边界。
* **恢复**：客户端断线可以重新观察原任务；外部写入响应丢失需要对账，不能无条件重试。
* **身份**：你的应用仍需验证业务用户是否有权读取或操作对应任务。控制平面的租户校验不能替代应用业务授权。
* **兼容性**：支持一个 Provider 不代表它支持每个 OCI 镜像、模型协议或网络策略。

先选取满足要求的已验证组合，再扩展到其他组合。参阅[模型协议](https://docs.hexagon.autos/zh-CN/integrations/model-protocols.md)、[Sandbox 能力](https://docs.hexagon.autos/zh-CN/integrations/sandboxes.md)与[验证矩阵](https://docs.hexagon.autos/zh-CN/integrations/verified-combinations.md)。

下一步：[安装与启动](https://docs.hexagon.autos/zh-CN/start/install.md)。

下一步可以[运行首个 Session](https://docs.hexagon.autos/zh-CN/start/first-session.md)、[选择组合](https://docs.hexagon.autos/zh-CN/integrations/choose.md)，或评估[自托管要求](https://docs.hexagon.autos/zh-CN/operate/self-host.md)。产品边界依据[架构](https://github.com/NexusFox88/docs/blob/main/resources/docs/architecture.md)与[验收旅程](https://github.com/NexusFox88/docs/blob/main/resources/testing/acceptance.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.