编辑器工作区
一个编辑器窗口始终绑定一个精确的 *.the 项目。页面、流程、Git、AI 和运行操作都属于这个 App；需要同时编辑多个 App 时，分别打开多个编辑器窗口。
先认识六个区域
Windows 和 Linux 的应用中心、编辑器和系统设置共用独立的顶部菜单栏，提供文件、编辑、视图、运行、窗口和帮助入口；窗口按钮位于右上角，页面工具栏位于菜单栏下方。按 F10 聚焦菜单，用左右方向键选择，再按 Enter 打开。macOS 继续使用屏幕顶部的系统菜单栏。
各平台的窗口左上角都有侧栏显示/隐藏按钮；macOS 将它放在红绿灯右侧。应用中心展开侧栏时，旁边的后退/前进按钮按访问记录切换会话，没有可切换的记录时禁用。收起侧栏后，这两个按钮替换为同一行的 新建会话 按钮，仍在当前项目中新建对话；重新展开会恢复前进/后退按钮。
| 区域 | 用来做什么 |
|---|---|
| 顶栏 | 核对 App 与运行目标；执行 Build、Start、Debug、Continue、Stop；打开 AI 和 Properties |
| Resources | 按业务资源查找 Page、Component、Object、QG、C# Provider、Vision、Safety、Asset 和手册 |
| Files | 查看实际工程目录；创建、移动、重命名、上传或删除文件 |
| 版本 | 保存项目版本、同步团队、维护标准版和客户版；高级模式提供完整 Git 操作 |
| WorkArea | 打开多个编辑标签并分栏；Page 使用 Design/Preview/Source，QG 使用 Flow/Source |
| Properties / Problems / Console | 编辑选中项；查看构建问题；检查当前运行目标返回的日志和故障 |
系统设置位于 Activity Bar 底部。当前 App 的首页、模块、功能包、变量、Query、i18n 和 App user 等配置从这里进入。
启用 Pulsar 模块后，Resources 的 Objects 列表会显示只读的 pulsar 对象。选中可查看接口；轴与 IO 配置仍在“设置 → 轴/IO”中维护，该对象不能手动改名或删除。
从任务选择入口
| 想完成的任务 | 从哪里开始 |
|---|---|
| 新建 Page 或 Component | Resources 中右键对应分组 |
| 新建 QG 或 C# Provider | Resources 中右键 Scripts |
| 新建或配置 Object | Resources 中的 Objects |
| 编写设备手册 | Resources 中的 手册；文件固定存放在 manual/ |
| 查实际路径或普通配置文件 | Files |
| 调整 Page 结构与外观 | Page 的 Design 和 Properties |
| 测试 Page 交互 | Page 的 Design |
| 查看或修改 QG 流程 | QG 的 Flow 或 Source |
| 处理完整构建问题 | Build 后打开 Problems |
| 查看运行输出 | Start/Debug 后打开 Console |
| 让 AI 协助当前 App | 顶栏 AI 按钮或 Cmd/Ctrl+I |
Source 是 Page、Component 和 QG 的最终源码。Design 和 Flow 都会更新同一份源码，不会创建另一份需要手工同步的项目格式。
设备手册固定放在 App 根目录的 manual/ 文件夹中，支持子目录。新建 App 会创建该文件夹；已有 App 即使尚无手册，也会显示独立的手册分组。右键分组新建文件，填写例如 start.md，然后双击打开。Markdown 文档默认使用可视化编辑，支持格式工具栏、列表、表格和代码块；输入 / 可插入内容块。顶部可切换编辑 / 源码，点击目录定位章节。修改后使用保存命令；切换视图不会保存文件。正文、列表标记、格式工具栏和代码块随界面主题切换。
粘贴、拖入或上传图片时，图片会保存到当前文档旁的 images/ 子目录，并插入相对路径。已有图片和其他手册文档也可以通过相对路径引用。编辑模式使用 Ctrl/Cmd+点击打开链接。App Hub 左右两处手册入口打开同一套文件标签页，默认显示排版后的只读正文，可通过预览 / 源码切换视图；预览中直接点击即可打开链接。图片、PDF 等附件可放在手册目录内。手册的已保存内容会随 Build 和交付一起打包，修改手册后需重新 Build 才会更新已交付内容。
打开、选择和修改
- 在 Resources 双击资源，将它打开到 WorkArea。
- 在画布、Flow 或 Resources 中选择目标。
- 在 Properties 修改当前目标支持的字段。
- 保存后，重新选择目标并确认显示值正确。
- 需要运行验证时，先核对顶栏运行目标，再选择 Build、Start 或 Debug。
Page 的 Design 网格、选中框和参考线只属于编辑器，不会进入运行页。Component 内部需要修改时，双击该 App Component 实例打开对应 .qpc；不要把复用组件的内部实现复制回每个 Page。
保存与磁盘变更
Cmd+S（macOS）或Ctrl+S（Windows/Linux）保存当前标签。- Build 只使用磁盘上已保存的文件。存在未保存、冲突或已删除的打开文档时，编辑器会先提醒；继续仍只构建磁盘版本。
- AI、Git 或外部编辑器修改一个没有本地草稿的文件时，打开标签会刷新。
- 如果同一文件同时有本地草稿和外部变更，编辑器会保留草稿并提示冲突。先比较内容，再决定保存或从磁盘重新加载。
- 关闭含未保存修改或冲突的标签、关闭编辑器或返回应用中心时，会要求确认。
- 保存只更新工程源码，不会替换正在运行的 App。
Design、Build 和运行
| 动作 | 适合验证什么 | 需要记住 |
|---|---|---|
| Design | 布局、属性和本地交互；按住 Alt 操作控件 | 不执行 Object / Query，不输出跳过调用日志 |
| Build Debug | 完整诊断和 QG 源码断点 | 使用已保存工程文件并交付到当前目标 |
| Build Release | 交付前的优化版本 | 仍需 Start 和现场验收 |
| Start | 正常运行已部署版本 | 缺少适用 Build 时会先询问是否 Build and continue |
| Debug | 断点、日志、状态和故障路径 | 仍会执行真实设备动作 |
运行中修改源码不会热替换当前实例。让新逻辑生效时使用 Stop → 保存 → Build → Start/Debug。
Problems 与 Console
- 编辑器内红线：当前打开文档的实时语法、类型和补全问题。
- Problems：最近一次 Build 对全部已保存工程文件生成的问题快照。保存工程文件后，旧快照会清除，直到下一次 Build。
- Console：当前运行目标在 Start/Debug 期间发送的日志和故障摘要。
Problems 和 Console 都可作为 AI 的只读分析上下文。点击分析不会自动修改 App；仍要审阅 AI 的原因判断和建议范围。
常用快捷键
| 操作 | macOS | Windows / Linux |
|---|---|---|
| 保存 | Cmd+S | Ctrl+S |
| 关闭当前标签 | Cmd+W | Ctrl+W 或 Ctrl+F4 |
| 下一个 / 上一个标签 | Ctrl+Tab / Ctrl+Shift+Tab | 相同 |
| 第 1–8 个标签 | Cmd+1–8 | Ctrl+1–8 |
| 最后一个标签 | Cmd+9 | Ctrl+9 |
| 打开或关闭 AI | Cmd+I | Ctrl+I |
一次修改的最小验收
- 标签不再显示未保存或冲突状态。
- Resources、Source 和 Properties 中的资源与关键字段一致。
- 当前文档没有阻止继续的实时错误。
- Build 后 Problems 没有阻止运行的错误。
- 顶栏绑定的是计划使用的运行目标。
- Start 或 Debug 中的结果符合正常、异常和恢复预期。
- 涉及真实设备时，现场反馈和独立安全措施都已确认。