Screph 用户手册

1. 选择并编辑元素

Screph 提供灵活的工具，用于精确选择和编辑接口元素。

工作模式

• 选择 (S): 选择现有的元素或特征以检查其属性或执行其他操作。
• 创建 + 形状: 首先选择意图 - 图像元素、容器区域、像素/区域特征、图案、网格或目标点 - 然后选择允许的形状：矩形、椭圆形、多边形或套索。可用的意图取决于程序模式。
• 移动 (M): 移动所选对象而不改变其形状。
• 调整大小 (R): 调整现有矩形、椭圆、多边形或套索的大小、顶点或轮廓。
• 层次结构 (H): 仅在两个元素之间创建父 → 子关系。关联、流和逻辑关系通过关系图或 创建关系 操作单独创建。

形状创建和导航

• 统一意图/形状选择: C、E、P 和L 选择矩形、椭圆形、多边形和套索作为当前意图。 Shift+A 直接选择矩形选择区域。特征快捷方式为 X 像素、A 区域、T 图案、 Y 目标、G 区域网格、Shift+P 多边形和Shift+L 套索；模式配置文件可能会隐藏不允许的类型。
• 手势: 通过拖动创建矩形和椭圆形，通过按住按钮绘制套索，通过放置顶点创建多边形；通过双击或单击其起点来完成多边形。未完成的形状不会创建规范的对象。
• 平移/缩放: 中间按钮或 Space 加上左键拖动甚至可以在活动工具上平移视口。滚轮缩放； Ctrl+滚轮。 Ctrl+=、Ctrl+- 和 Ctrl+0 也可用。

互动

• 选择: 在选择模式下点击元素。
• 画布区域设置: Ctrl+单击可在 InfoPanel 可以包装的集合中添加或删除元素/特征选择区域。
• 树形多选: Ctrl 选择单独的行，Shift 选择范围。
• 上下文菜单: 右键单击元素-tree 行将其选中，隐藏/显示其子树，删除元素，删除关系，打开Module 子菜单，将其转换为选择区域，或展开/折叠子树。
• 树可见性: 元素名称右侧的眼睛图标会暂时隐藏或显示元素、其子项及其画布关系。隐藏的元素不会从项目中删除，无法单击，无法成为新区域的父区域，也无法接收新的关系。
• 子树模块: Module 菜单为下选择的树枝创建一个紧凑的 module.json <project>_artifacts/modules/ 加上旁边生成的帮助程序类。主项目仍然是事实来源，而该模块用作小型代理或代码生成上下文。树行中的小 M 徽章表明该分支有一个模块并指示其状态。相同的菜单可以复制代理就绪上下文或刷新过时的模块。在创建过程中，您可以保留对共享资源的引用或构建独立的模块文件夹。代理任务在模块旁边创建，Send to Codex 通过现有的 Codex VS Code 桥写入请求。打开选定的 IDE/代码工具和 Codex 发送使用项目根目录，以便代理可以看到依赖项并编辑其他项目区域。
• 删除: 选择元素或特征并按 Delete。 Screph 请求确认；对象锁（包括使用元素删除的相关对象上的锁）会阻止操作。

移动、顶点和几何提交

移动/调整大小会更改现有规范记录，而不是创建副本。对象锁或相应的画布层锁会阻止该手势。对于R模式下的多边形/路径元素，可以拖动顶点； Tab/Shift+Tab 更改活动顶点，箭头键将其移动 1 px，Shift+箭头 5 px 和 Ctrl+箭头 10 px。 Enter 在光标下最近的边上插入顶点。双击顶点将其删除，或双击边插入新顶点。

特征生命周期

特征是一个规范项目对象，而不仅仅是一个画布矩形。根据活动的 Selector 配置文件，项目可以存储 pixel（点和采样颜色）、region（几何和摘要）、 pattern、region_grid 和 static_diff。这些记录属于一个项目历史记录，并存储在 image_features 中。 Y 工具不会创建单独的类型；它将目标点分配给选定的几何图形特征并存储其相对于几何图形的偏移量。

• 重复: 上下文菜单创建新的 ID/显示 ID 和副本名称，保留几何/摘要/设置，但清除 crop、mask、 preview 及其资产元数据。它是一个新对象，而不是对源资源的另一个引用。
• 制作图案: 从源特征的几何形状创建一个单独的图案，对当前图像的摘要进行采样，将目标置于中心并以相似度 0.8 开始， exact=false 并调整 1.0 的大小。需要真正的源图像。
• 网格和派生区域: 从区域创建网格默认创建一个新的region_grid，网格大小为 3×3；行和列可以在检查器中从 1 更改为 64。 衍生区域子菜单提供增长、插入、左/右/上/下；数量以像素为单位输入（默认情况下，增长/插入为 16，相邻区域为 32），结果被限制在源图像边界内。
• 静态差异: 在打开上下文菜单之前选择另一个特征时会出现该项目。特征都需要几何形状和可用的源图像；结果存储基础/比较 ID、组合 bbox、更改的像素和差异百分比。默认阈值为 16。

特征检查器公开名称、规范描述、创作模式、所有者、来源、几何/颜色/目标、图案设置、网格设置、关系、问题、只读 JSON 投影和单独的匹配。可以手动将所有者分配给选定的元素或分离；自动选择区域成员资格是一个单独的机制。更改目标、几何图形、源或网格会将现有位图资源标记为过时（当它们存在时）。活动配置文件特征和对象锁可以拒绝任何此类突变。

选择区域：成员身份和边界

A 选择区域是仅几何形状的容器：它可以使用矩形、椭圆形、多边形或套索几何形状并存储元素/特征成员资格，但没有像素、裁剪或图像序列。重要的是，当前的成员资格检查使用区域的边界矩形，而不是精确填充的椭圆/多边形/路径。默认情况下，会自动收集其完整边界框包含在该矩形内的对象。通过嵌套区域，对象将被路由到最近的、最小的匹配区域。

• 创建: 使用Container 区域意图进行绘制，使用在普通无图像元素上制作区域，或者收集元素/特征与 Ctrl+单击并按 在 InfoPanel 中创建区域 。 周围的区域用 8 px 填充包裹选定的元素、其后代和特征。
• 管理会员资格: 刷新会员资格重新运行自动收集； Attach... 选择一个包含的对象，Attach all 处理每个候选结果，并且Detach... 从当前区域删除一个对象。
• 会员锁: 将一个元素或特征冻结在其当前成员资格状态并防止自动重新分配。手动分离启用此锁；手动附加清除它。这是一个规范的对象属性，与持久对象锁和仅会话层锁不同。
• 移动和转换: 使用默认设置，移动区域会移动其子区域元素和特征。 到普通去除容器语义。图像有效负载阻止另一个方向的转换；现有的帧绑定首先通过捕获控制器释放，释放失败会取消操作。

元素属性

• 名称: 唯一名称（自动或用户定义）。
• 类型: 所选程序模式的活动标注目录中的类型。
• 坐标和尺寸: 位置（X、Y）和大小。
• 层次结构: 有关与其他元素的关系的信息。
• 注释: 元素的文字描述。

2. 图像检查和测量

像素检查工具可在 InfoPanel 的 Image 选项卡上使用，而直方图、线条轮廓和证据比较则在 Capture/Images 底座上图像分析选项卡。它们在活动的画布演示文稿上运行，而不更改其源像素。

A/B/C/D 演示文稿

菜单栏工具栏中的布局控件最多可创建一个画布的四个窗格：A； A/B 并排或堆叠；左边是 A，右边是 B/C；或 2×2 A/B/C/D 网格。这些不是项目副本：规范的元素、特征、关系、选择和项目历史记录由每个窗格共享。所选的视觉材料及其本地显示设置可能会有所不同。

• 选择和激活: 使用窗格的设置按钮将其重命名并选择源、工作 CV 结果或诊断演示文稿、其显示模式和裁剪源。激活会将画布工具路由到该窗格；过时的、未映射的或只读的演示文稿无法进行编辑。此类激活请求被拒绝；如果当前活动窗格变得不兼容，所有权将返回到 A。
• 链接导航: 链接窗格同步比例、视口中心和画布空间光标。窗格 A 始终属于链接组； B/C/D 可以取消链接以实现独立的缩放/平移。从兼容的只读窗格导航仍然可以移动链接组，而无需授予其编辑标注的权限。
• 关闭并重置: A 无法关闭； B/C/D 已显式关闭，关闭窗格不会删除其选定的演示文稿。选择较小的布局永远不会隐式删除现有窗格。全局 Reset 更强大：它将 Source 分配给 A，激活它，关闭 B/C/D 并返回到单窗格布局。

像素、放大器和导航

• 像素探针: 立即显示光标下方的坐标、RGB、HEX、HSV 和源，然后在 0.5 秒后记录稳定值。可以复制单个稳定场或全套稳定场。
• 采样内容: 探头和线路轮廓读取活动演示文稿的确切 material 层。如果该材料不可用或未映射到画布，Screph 会报告诊断，而不是默默地替换原始图像。
• 放大镜: Context 31×31、Detail 15×15 和 值 9×9 模式，具有独立的网格、十字准线和框架切换。
• 查看: 适合、100% 缩放、像素网格和可调整大小的导航器/小地图。导航器可以切换、调整大小并用于使视口居中。

画布层

图层面板控制六个固定组：源图像、CV 叠加、元素和关系、特征、助手预览和测量。每个组都有可见性、不透明度、编辑锁定和上移/下移控件。

音调 & 配置文件

• 直方图: 组合 RGB、单个通道或灰度/LUT 加级别仅用于显示。这是一种非破坏性的显示转换，而不是对材质或项目图像的更改。
• 线路配置文件: 在活动演示文稿上画一条线以获得沿线的距离、坐标、R/G/B 和亮度。可以选择或删除多个测量，可以进行本地撤消/重做，并且可以将当前配置文件复制为 TSV 或明确导出为 CSV。

比较 & 证据

只读面板将演示文稿 A 与选定的 B 进行配对，提供“适合所有”和 400 毫秒闪烁比较，然后显示摘要、诊断和来源。报告绑定到源/上下文修订，因此不匹配标记证据过时。注册、稳定和工业部件使用专门的检查员；组件报告还提供接受/拒绝过滤、指标表和所选组件的只读覆盖。

3. 注释（文本/语音）

注释是规范的人类可读的对象描述，而不是单独的提示文件。文本和语音输入更新相同的目标字段并参与项目历史记录。

可以描述什么

• Element / feature / feature match: InfoPanel 卡中的 description_ human 字段。语音面板将其转录内容写入同一字段；当前的 UI 不会创建单独的并行“语音记录”。
• Relation edge: 边缘检查器或 关系描述 对话框中的描述。其嵌入式语音小部件将识别的文本附加到草稿中；规范边缘仅在 OK 之后发生变化。
• Image Series entry: 每个条目 annotation 字段。对话框中的文本或语音提交至 OK； Cancel 使条目保持不变。整个 CV-run 注释是单独编辑的，目前仅为文本。

语音标注

所选识别器（本地 Vosk 或显式配置的 Yandex、Google 或 OpenAI 路径）由共享语音小部件使用。不可用的提供程序不会自动替换。

1. 选择元素、特征或特征匹配记录。 Screph 在创建这些对象后自动请求注释；仅当不存在描述时，特征目标更改才会执行此操作。图像系列条目、CV 保存、边缘和 CV 运行注释不会自动启动语音小部件。
2. 要手动启动，请按 语音注释 。小部件将打开并显示当前描述，并进行几次简短尝试以自动开始录制。
3. 对着麦克风清晰说话；录制按钮可切换录制和停止。
4. 审核，如有必要，编辑识别的文本，然后按 Done 或Ctrl+Enter。

Escape 或关闭按钮关闭小部件而不发出结果。在主动录制/识别期间失去焦点、移动到另一个选择操作或开始另一个语音会话可能会结束当前会话；使用关闭按钮或 Escape 进行显式取消。在常规设置→操作模式、复制和隐藏和复制、清除和隐藏仅写入剪贴板，不写入更新对象。

注释和语义命令

语义默认启用，语音注释使用 fast_skip_non_commands，0.72 或以上的高置信度规则可能立即应用。 ✓/× 按钮仅针对实际放置在审核队列中的意图激活。 require_confirmation_for_llm 确认已标记的意图 requires_review；它本身并不通过审核强制每个 LLM 结果。为了保证仅听写行为，请清除处理语音注释或选择不要运行注释语义。

4. 保存和加载项目

当前项目是包含规范 <name>.json、源图像和相关内容的目录产物。当前加载/保存流程不再使用 .sgaip 格式。

正在保存

• 文件 → 保存项目: 覆盖现有文件或创建新文件。热键：Ctrl+S。
• 文件 → 保存设置... (Ctrl+Shift+S): 选择项目环境、编码工具、保存后行为、保存位置和特征投影配置文件。该对话框可以在不写入项目的情况下应用配置文件，或者应用它并立即保存。

不要将此对话框与旧版 元素选择 → 文件 & 格式 主设置窗口中的选项卡混淆：其可见时间戳、PNG/JPG 和 JPEG 质量字段将保留，但当前项目编写器不使用他们。

项目环境

可用的保存结果取决于程序模式。 GUI Automation 可以定位 Screph Automate 或 PyAutoGUI。 General、Industrial Vision 和自主无人车提供相应的内置Screph CV（OpenCV / NumPy) 环境和“无工具 - 仅 Screph 项目”选项。 IDE 或代码工具单独选择，不切换程序模式。

• 当前项目覆盖现有的当前路径；当当前路径不存在时，Screph 会询问名称并在默认项目根下创建一个目录。
• Subproject 始终要求输入名称并在当前项目目录中创建一个目录；如果没有当前项目，它将使用默认根目录。代码工具工作区仍然是父项目根目录。
• 始终询问 显示名称，并且仅当当前项目存在时，才会显示子项目选择。

对话框的“将被创建”列表是目标摘要，而不是完整的包清单：它省略了自动 for_ai_agent、_artifacts目录和条件时间轴/帧绑定伴随文件。

请参阅 项目环境和 Saving 以获取完整的可用性表。

保存的内容

• 源图像和 Capture/时间线参考；
• 元素、特征、几何、注释，键入关系和标注组；
• 树模块注册表项、CV 结果引用和选定的保存配置文件；
• 保存/加载诊断和产物完整性报告。

保存成功后，Screph 会在项目旁边自动创建 <name>.for_ai_agent.json。它是 Screph Code/IDE 的派生投影，而不是在 Selector 中重新打开的文件。时间轴和帧绑定捕获使用它们自己的伴随文件（如果存在）；有关完整包，请参阅 数据和导出指南。

加载和恢复

File → 加载项目 (Ctrl+O) 打开项目 Manager，不是普通的文件选择器。它递归地考虑所选根下最多 2,000 个合格的 JSON 文件，跳过已知服务文件和产物目录，并将条目分隔到 Projects， 自动保存和问题。

• 所选项目公开历史记录、图形/树小地图、计数、标签、注释和诊断。
• 经理可以打开、复制或重命名项目，将当前状态保存到选定条目，以新名称恢复自动保存并将地图导出为 GraphML/HTML/JSON。
• 选择文件... 允许您显式选择 JSON 文件。管理器仅在架构检查后且包含至少一个元素、edge、特征或特征匹配记录时才打开规范项目或自动保存。代理导出不会成为可编辑项目：当其规范引用存在时，Open 解析为该规范文件；树模块和任意 JSON 保持不可打开。
• 在打开之前，Manager 诊断会覆盖 JSON 角色、读取/架构失败、缺少路径和空域；这不是全新的完整产物完整性扫描。实际加载后，InfoPanel 会显示当前域加载报告以及已保存的保存报告。
• 启动时，Selector 单独尝试恢复 autosave_session.json。此启动流程接受元素或边缘，或单独加载的基础图像，因此仅屏幕截图的自动保存可能会在启动时恢复，即使 Manager 将无对象域视为不可打开。 Capture 时间线具有单独的恢复机制。
• 关闭期间 Selector 或 Capture 自动保存失败需要明确的用户决定。 Selector 仅针对脏项目写入其关闭自动保存； Capture 可以单独保留录制帧。

复制和重命名仅适用于常规规范项目，而恢复适用于自动保存。它们对整个目录进行操作，并对齐主 JSON、时间线和帧绑定伴随文件，但不会重建代理导出或迁移 Manager 本地标签和注释。切换前再次保存。

从历史记录中删除和清除缺失仅更改最近路径列表；项目经理不会删除项目文件。标签和注释通过绝对路径单独存储，不属于可移植包的一部分。创建新项目时，Screph 会提示保存当前项目、不保存继续或取消；现有的时间表可以明确地纳入新项目中。

5. 使用图像序列

元素的 图像系列 是其保存的视觉状态和附加的 CV 输出的集合。它不是 Capture 时间轴本身：时间轴提供源帧，而系列条目属于规范元素并在保存时将所需图像/产物移动到项目包中。

在 InfoPanel 中选择了元素系列

• 初始视图: 对于普通的新元素，Screph 尝试从选定的裁剪源创建条目 0：活动的画布演示材料或明确选择的演示材料规范来源。不可用的来源不会被默默地替换。
• 将当前视图添加到系列: 不进行纯屏幕截图。它通过对选定的元素进行强制应用/保存来运行当前的 CV 方法，并分配下一个数字注释。因此，它需要 CV 面板，并且可能会为一次运行创建多个输出图块。
• 运行卡: 共享 cv_run_id 的输出被分组在一起。双击打开文件；输出的上下文菜单可以打开它，将蒙版/灰度/剪切设为主要，或删除该输出。删除最终输出也会删除系列条目。
• 描述和审核: 卡片菜单通过文本或语音编辑其注释，编辑整个 CV 运行注释，打开带有条目上下文的助手，或删除条目。数字和自动生成的标签带有 ! 标记，直到手动审核为止。

框架系列和 Capture 时间线

图像帧的上下文菜单提供 捕获当前帧、 帧中的记录系列/Stop 系列录制和在时间轴上显示捕获的帧。录制过程中，移动到新帧会自动存储帧裁剪；对于一个图像帧，不会捕获两次相同的帧索引。该帧必须解锁，图像内具有有效的几何形状，并且不能同时记录另一帧。

更改活动框架的几何形状会根据其设置停止或重新启动记录。删除时间线范围会重新映射幸存的帧绑定，而删除系列条目首先会清除其帧绑定绑定。索引位于项目旁边，名称为 <name>.frame-bound-image-series-index.json；条目和图像本身通过规范项目及其产物保存。

源时间线导航和编辑

• 时间轴支持第一个/上一个/下一个/最后一个导航、播放、速度和循环。
• 要删除内容，请选择一个范围，然后选择 从时间轴中删除选择 或按 Ctrl+Del。上下文菜单还可以删除剪辑或清除时间线；原始媒体文件未更改。

Capture 选项卡在 专用指南 中有详细描述。

6. 标注关系图

关系图可视化规范元素/特征之间的键入链接。边描述了语义关系及其属性；它不会自动成为点击、转换或执行步骤。

图表选项卡显示的内容

• 节点: 元素、选择区域、特征和树模块根。状态反映了选择/可见性、模块新鲜度和特征问题。
• 层次结构: 父链接 → 子链接源自规范父状态，并且与任意关系保持不同。
• Ownership: 切换系统所有者 → 特征边缘；这是 owner_element_id 的视觉投影，而不是另一个可编辑用户关系。
• Relations: 显示或隐藏用户边缘。单击节点会选择其元素/特征，单击边缘会打开其属性，节点可见性控件会隐藏特征或整个元素子树。

创建和编辑关系

1. 打开元素或特征上下文菜单，选择 创建关系...，然后选择另一个端点。
2. 选择 Association、Flow 或 Logical 关系； Hierarchy 也可用于元素 → 元素对。 反向在创建之前交换源和目标。
3. 选择画布上或图表中的边。检查器显示 ID/源/目标/类型、可编辑描述、只读 JSON 属性，并可以将源或目标重新指向现有元素/特征。
4. 边缘上下文菜单还可以更改类型、通过语音输入编辑描述、打开该关系的助手或将其删除。

Screph 拒绝自端点/缺失端点、重复定向对、特征层次结构和层次结构循环。分配新的父级会将子级与其先前的父级分离。特征关系还取决于活动模式的 FEATURE_RELATE 功能。

特征匹配记录不是边

特征属性的 Matches 组从另一个特征或元素创建匹配项并存储种类、得分 0…1、来源、 bbox/目标和描述。这些记录分别保存在规范的 feature_matches 下；关系图当前不将它们渲染为用户边缘。

记录的操作顺序属于 Action Trace，而可执行逻辑属于自动化脚本/运行时。 CV Method Graph 是第三个独立的计算图。

7. 数据准备和仿真

在 GUI Automation 模式下，Screph 准备结构化自动化上下文：图像、选择、注释、关系图形、屏幕状态和可导出的project.json。此数据可用于动作仿真、内置 Screph Code 以及外部 IDE 或代理工作流。

在其他模式下，保存目标为规范项目以及该模式内置的 CV 环境；那里不提供 GUI 自动化消费者。

当前 GUI Automation 输出

• Screph Automate: project.json、main.py 和运行时指南；显式的 Open Result 按钮可打开自动化管理器。
• PyAutoGUI: project.json、main.py 和专用指南。执行需要可用的 script.runtime。
• 规范保存后，Screph 验证坐标合约，然后准备目标文件。错误会阻止安全的自动化切换，但不会删除已写入的规范/代理文件。

保存后打开代码工具是尽力而为的下游操作：禁用或不可用的后端，或者启动/发送失败，不会回滚已保存的项目。如果可用，上下文为 for_ai_agent，否则规范 JSON；兼容的后端也可能会收到生成请求。

内置 Screph Code 的详细 GUI 流程记录在下面的第 8-15 节中：启动、保存时自动启动、传输上下文、Builder、编辑预览，以及恢复。

8. IDE 集成

Screph 通过两种模式与 IDE 和代码工具集成。第一种模式是内置Screph Code，可以手动打开，也可以在保存项目时自动启动。第二种模式是将项目 JSON 以及相关的产物导出到外部 IDE 和智能体管道。

集成方法

• 导出数据: 保存为导入其他工具的格式。
• 复制代码: 剪贴板 → IDE。
• 文件系统: 另存为文件。

如果您使用内置 Screph Code，请继续阅读下面的第 8-15 节：它们描述了 Screph Code 窗口、 Project 和 Builder 选项卡、快捷方式、差异预览、 撤消、检查点和设置。

9. Screph Code GUI：General 上下文和先决条件

内置 Screph Code 的详细指南如下。这些部分扩展了上面的简短概述并描述了当前实现的 GUI 流程：后端选择、从 Screph 启动、上下文传输、Builder、编辑预览、验证和恢复。

重要提示：本指南仅适用于内置 Screph Code 编辑器。在代码集成设置中，选择代码编辑器：Screph Code [内置]。如果选择另一个后端（Trae、PearAI 等），项目面板按钮将打开不同的工具。

• Screph Code 可与已保存的 Screph 项目、其 project.json、工作区文件夹以及该项目的指南文件配合使用选择保存策略。
• Screph Code 内部有一个带有代码编辑器的专用窗口、一个 Artifacts 选项卡、一个Project 面板和 Builder 面板。
• 生成和编辑使用与主应用程序中为 Screph Code 配置的相同 LLM 设置。
• 该窗口通过单独的 Pro Agent 进程运行，并需要可用的 codegen.runtime 和分配给该进程的 LLM 配置文件codegen 角色。明确报告缺少依赖项。

运行时和连接设置包含在 依赖关系和更新 和 LLM 连接 中。

10。如何打开 Screph Code 以及自动启动的工作原理

手动启动

1. 打开代码集成设置并选择 代码编辑器：Screph Code [内置]。
2. 如果需要，请配置基本 Screph Code 集成选项： 项目文件夹、 输出文件夹和提示模板。
3. 在项目面板上，从下拉列表中选择编辑器并使用 Screph Code 按钮。

项目保存时自动启动

Autostart: Screph Code 复选框存储保存后切换标志。启用后，Screph 尝试启动选定的代码工具并在目标准备成功后发送项目上下文。后端不可用或启动/发送失败不会回滚已保存的项目。

在当前实现中，主保存流程首先创建规范/代理包，然后验证并准备目标，然后才执行尽力而为的代码工具切换。它使用代理导出作为上下文（如果可用），否则为规范的 JSON。

此规则适用于主保存流程。即使附近存在 for_ai_agent 伴随文件，Project Manager保存和某些旧保存入口点也会直接传递规范项目路径。 打开编辑器按钮仅启动所选工具；如果没有保存后切换，它本身不会发送项目上下文。

11。 Screph 发送到 Screph Code

从 Screph 启动不仅仅是打开项目文件夹。保存时，Screph 为 Screph Code 创建专用上下文有效负载；窗口使用它来填充字段并可选择立即启动构建流程。

• project_json: 保存的项目 JSON 的路径。
• output_dir: 生成文件的项目工作区目录。
• guide_path: 所选保存策略的指南文件（如果找到）。
• 切换标志: include_project_json = true，include_guides = true，auto_generate = true。
• 初始消息: 生成项目代码。

auto_generate 是历史字段名称：当前消费者将初始消息放置在 Builder 中，并以编程方式调用常规字段发送操作。当前窗口没有单独的 Ctrl+B 命令或隔离的仅生成管道。

12. Screph Code 窗口图及 Builder 的作用

• 左列包含 JSON/Output 路径、手动打开/保存/另存为操作、运行/停止/重新启动当前文件，运行时 log/诊断/导出控件和工作区资源管理器。
• 该中心包含 Monaco 和 Code、Plan、 更改、任务、执行和材质选项卡。计划/任务表面代理事件，执行报告子进程运行，材料存储响应和支持结果。
• 右侧的 Builder 列显示 LLM 状态/模型、脚本、请求输入、拖放附件、语音输入和 Send 按钮。 输入发送请求； Shift/Ctrl+Enter 留给文本小部件的标准编辑行为。
• 请求字段上下文菜单可以插入当前文件/选择引用或附加当前/所选项目文件。活动文档、未保存的缓冲区、选择和附件作为结构化上下文发送；大部分的预算可能会被削减并在上下文芯片中报告。

13。 Builder 请求、工作区写入和文件执行

发送 Builder 任务

1. 保存项目或手动打开 Screph Code。
2. 检查 JSON 和 Output 路径、选定的模型和工作空间。保存后切换会从上下文有效负载中填充它们。
3. 输入具体任务，可选择附加文件或当前文件/选择参考，然后选择 Send 或按 Enter。
4. 遵循计划/任务和记录。 Stop 要求当前 OpenHands 会话停止，但它不会自动回滚已发生的工作区写入。
5. 响应后，刷新并检查资源管理器中受影响的文件，并使用 Git 或其他外部 diff 工具。代理的最终文本并不能证明哪些文件已更改。

Builder 响应意味着什么

当前的 Builder 始终使用 mode=agent 创建请求。它可能仅以文本应答，但它也可以调用具有写入功能的工作区工具。因此，Send 不是只读聊天操作。写入工具会限制所选工作空间的路径，但不会对每个操作进行单独确认。

手动编辑和执行

Monaco 缓冲区仅通过“保存”/“另存为”保留。运行是一个单独的显式操作：它在可用的预检后在子进程中执行选定的脚本，而停止/重新启动则控制运行。这不是 Automation Runtime，它不会在 Builder 响应后自动执行代码。

14。设置、选项卡和历史记录

• 当前的 Builder 设置对话框包含 LLM/模型分配、默认项目/输出路径和 Python/PyAutoGUI 的依赖项操作。旧的提示模板、验证/样式和收集/聊天/代理控件不是当前界面的一部分。
• 计划和任务项目 OpenHands 事件；它们不是批准队列。更改仅显示由匹配的生产者显式添加的记录；它不会自动拦截每个工作区写入。
• Undo/Checkpoints 取决于内存中EditHistory。当前的主 Builder 发送路径不会在那里注册直接 screph_file 编辑，因此这些控件不会取代 Git、备份或磁盘级文件检查。
• 材质存储大型 Builder 响应并在本地工作空间状态下支持产物。在代码中打开材质会将文本加载到编辑器缓冲区中；仍然需要保存/另存为来保存它。

15。错误、警告和恢复

• 典型的预运行问题包括：缺少项目 JSON、无输出文件夹、空的 Builder 输入或不可用LLM。
• 如果上下文预算削减历史或检索，Builder 将显示具有丢弃/截断状态的上下文/提示碎片。这意味着上下文不完整；这不是模型错误。
• OpenHands 文本响应不能保证已创建所需的文件。手动检查工作区和预期目标。
• 停止将请求移至已取消状态，但不会回滚已完成的工具调用。仅当该工具会话仍保留其内存中撤消堆栈时，通过 Git/备份或通过 screph_file undo_edit 恢复不需要的写入。
• 运行预检和子进程执行有自己的诊断/log/export。脚本失败不会回滚代码文件，也不意味着主 Screph 进程崩溃。

16。实用 Screph Code 技巧

• 在发送请求之前创建 Git 提交/分支或工作区备份，尤其是在保存后自动启动时。
• 明确说明范围：目标文件、允许的相邻文件、所需的验证以及不需要执行时的不运行约束。
• 使用附件或当前文件/选择参考来获取精确的上下文；不要假设代理会在大型工作区中选择正确的文件。
• 在 Builder 之后，检查git diff、新的/删除的文件以及预期的目标内容，然后使用 Run 或 Automation Runtime 单独执行脚本。
• 在切换之前保存规范项目，以便主保存流程可以传递最新的 for_ai_agent 投影和 CV 配方参考。