App 与核心资源
你不需要先学会文件格式，才能使用 Theseus。只要知道每类资源负责什么，就能更准确地向 AI 描述需求，也能在编辑器中判断结果放对了位置。
为什么需要知道
一个看似简单的需求，往往会同时涉及画面、设备和流程。例如“扫码后查询工单，再启动工位”可能包含 Page、Query、Object 和 Graph。知道它们的边界，可以帮助你：
- 告诉 AI 允许修改哪些范围、哪些不能动；
- 在左侧 Resources 中找到 AI 新增或修改的内容；
- 判断问题出在画面、数据、设备能力还是自动化流程；
- 避免把长期流程写进按钮，或把设备协议写进页面。
何时会遇到
创建第一个画面、接入设备、编排多步骤流程、连接 MES，或查看 AI 的修改清单时，你都会看到这些名称。
最小心智模型
App 是一个可以独立编辑、构建、部署和运行的项目。 下面的资源都属于某个 App。
| 资源 | 它负责什么 | 常见例子 |
|---|---|---|
| Page | 面向操作员的运行画面，包含控件、交互动作和页面权限 | 运行看板、参数页、报警页 |
| Component | App 内可复用的可视化模板，常用于列表或 Repeater 的重复项 | 工位卡片、报警条目、IO 状态行 |
| Object | 用业务语言表示设备或能力，对外提供状态和方法 | 轴、扫码枪、工位、RecordStore |
| Graph | 编排多步骤、分支、等待和异常处理，并支持断点调试 | 启动、回零、换型、报工流程 |
| Variable | 保存少量运行数据；可以是 App 共享值、断电保留值或 Graph 局部值 | 当前工单、运行状态、累计产量 |
| Query | 定义如何调用外部系统的可复用合同 | 查 MES 工单、读配方、报生产结果 |
它们通常这样协作：
- Page 向操作员展示 Object 状态和 Variable 值。
- 操作员触发页面动作，调用 Object、Query 或 Graph method。
- Graph 负责多个动作之间的顺序、条件、等待和异常分支。
- Component 接收一项数据，在 Page 中重复呈现统一的视觉结构。
- Query 只定义外部调用方式；返回的数据由 Page、Graph 或 Variable 消费。
需求应该放在哪里
| 你的目标 | 首先考虑 |
|---|---|
| 增加一个操作员画面 | Page |
| 重复显示多台同类设备 | Component + Page |
| 给设备增加“回零”“启动”等能力 | Object |
| 编排“检查 → 动作 → 等待 → 超时处理” | Graph |
| 在画面和流程间共享一个小型状态 | Variable |
| 调用 MES、ERP、WMS 或其他外部服务 | Query |
实际任务可以同时使用多种资源。重点不是强行只选一种，而是让每一部分待在它应该负责的层级。
常见误解
- Page 不是整个应用。 它只是 App 的一个运行画面。
- Component 不是另一个 Page。 它是供页面重复使用的视觉模板，不拥有独立运行入口。
- Object 不是画面控件。 它表达设备或业务能力，Page 和 Graph 都可以使用它。
- Graph 不是所有按钮都必须经过的流程。 单一步骤可以直接使用页面动作；需要顺序、分支、等待或调试时再使用 Graph。
- Variable 不适合保存大表格、图片或完整历史记录。 这类数据应使用 RecordStore、资源文件或外部系统。
- Query 不是一份查询结果。 它是调用外部系统的定义，真实数据仍来自外部系统。