halcon-skill

HALCON 视觉脚本编写技能

生成、重构、运行和审查 HALCON 视觉程序。保留项目现有格式；新程序默认使用 .hdev，除非用户要求使用 HDevelopEVO/.hscript。只有当选择会实质影响含糊的任务时才提问。

除非用户要求进行其他更改，否则生成或编辑 HALCON 文件（.hdev、.hdvp、.hdpl、.hscript）。

选择工作流

使用某种格式或工具前，只阅读与任务相关的参考文档。

任务	工具和必需参考文档
编写或编辑 HDevelop XML 和过程文档	HDevelop 格式
编写或编辑 HDevelopEVO 文本和导入项	HScript 格式
使用显式输入运行 .hdev 代码（默认：具名本地过程或 test_*），并生成 JSON 结果，可选生成 SVG	scripts/hdev_call.py — Python 运行器
检查 .hdev 中间状态、单步执行、设置断点、检查向量或预览图标值，无需 HDevelop	scripts/hdev_debug.py — 调试器
备用方案：执行现有 .hdev 程序的 main()，或在没有 Python 绑定时运行	hrun — 简要备用说明
执行 .hscript	hscriptengine — HScript 引擎

若需了解算子签名、默认值、有效范围、已安装示例或运行时位置，请阅读 HALCON 环境和文档。请对照已安装的参考文档核实算子详情，不要凭空猜测。

对于叠加层和注释，请阅读可视化：了解精确的调色板、dev_* 用法、支持的 SVG 选项和限制。有关 SVG 设置、调用和输出文件，请阅读 Python 运行器参考文档。

过程职责

• 公共生产 API： 每个供外部应用调用的过程都必须接受一个名为 Image 的图标输入，其中包含实际图像（语义类型为 image，而非区域、XLD、路径或占位符），并返回标量布尔值 JobPass（1 = 通过，0 = 失败）。
• 私有辅助过程： 仅供内部或 test_* 使用的过程只需具备针对任务的参数。通过测试运行器调用辅助过程，不会使其成为公共生产 API。
• 测试： 使用 test_* 测试单个公共或私有过程，提供显式输入和断言；遵循 Python 运行器的测试模式。测试成功与生产环境中的 JobPass 不同：预期的拒绝也可能意味着测试通过。
• 示例： 使用 main() 编排示例，而非作为单元测试接口。将示例参数集中放在顶部。
• 测试和示例入口不受公共生产签名要求约束。避免隐藏的全局状态；测试输入不需要使用全局变量。

文档语言

为每个过程（包括 main() 或 HScript 主节）及每个参数编写文档。生成或更新文档时遵循以下策略：

• 默认始终使用英语。
• 已知用户的本地语言且与英语不同时，添加该语言。
• 检查现有项目文档，并使用其中的其他语言。更新文档时保留这些语言。
• 通常使用一到两种语言；项目中已有的语言可能会增加语言数量。不要强制使用德语，也不要限定翻译副本的数量。
• XML 语言标签或注释块应遵循对应格式的参考文档。任何未标记文本的后备内容必须使用英语；它不算另一种语言。

包括用途、真实的使用示例，以及适用时的参数含义、范围、单位和默认值。确保各语言的译文与相同行为保持一致。

编写约束

• 确保采集/输入、ROI、预处理、检测或测量，以及判定/报告过程清晰易懂。明确说明输出和通过/失败原因。
• 通过过程输入公开可调参数，并提供合理且有文档说明的默认值和有效范围。重复逻辑和开销较大的句柄/模型应复用。
• 进行度量测量时使用经过标定的变换，而不是像素近似值。
• 使用符合习惯的 HALCON 语法和稳定、针对任务的名称。在 HScript 中，导入的 API 使用 public proc，文件本地的辅助过程使用 proc，外部过程使用 from ... import *。
• 生成绝对坐标 ROI 时，应先确定相关图像尺寸，或根据需要显式配置 clip_region，以处理区域裁剪。
• 在生产过程以及示例和测试中，使用 dev_* 算子进行可视化。将生产过程中的可视化叠加放在其所解释的逻辑旁边；可视化不局限于 main() 或 test_*。适当时使用多个窗口，并使用 dev_set_part，不要仅为显示而裁剪图像。只有示例/测试或运行器可以导出带标注的文件；生产过程不得导出此类文件。
• 可视化应为可选且非阻塞；显示不可用时应优雅处理。无头代码中不得使用 stop()、dev_open_dialog 或交互式算子。错误路径应使用 return () 或 throw，并处理合理可预见的运行时故障。
• 仅对输出相互隔离的独立工作使用 par_start/par_join。
• 除非用户提出要求，否则不要添加相机访问或外部通信（网络、工业通信、文件 I/O）。不要因为用户提出调试请求，就推断其已授权操作设备。

测试和产物

检查是否存在 images 文件夹、ok/nok 等类别拆分或训练/测试/验证集，以及 JSON/YAML 标注；酌情使用提供的测试样例。除非另有指定，请将请求生成的测试/运行产物写入 result/，并为每张受测图像关联运行器 JSON 或 CLI 日志。仅传入测试所需的输入。

回归测试应使用常规执行。只有需要中间状态时才进行调试：提出假设，检查相关源代码/变量，并有选择地请求预览。

所有命令使用相同的调试器会话 ID。如果状态仍为 running，应查询 status，而不是启动另一次运行。完成后关闭会话；关闭会话会终止隔离进程，不会执行剩余语句。代码变更后必须新建会话，并执行常规回归测试。绝不要自动重放相机、文件、网络或设备副作用。

原生调试服务器没有密码。请使用可信主机/网络，切勿将其暴露给远程访问；启动前请阅读调试器参考文档。

交付

针对请求提供完整可执行代码，说明关键的图像/标定/极性/光照假设，解释关键算子的选择，并指出可能需要调优的参数。报告执行证据和剩余限制，不得声称未运行的测试已通过。