zhaowei.huangandCursor
158d770c54
将 CycleGUI 开发技能（含 Duplicated id 防碰撞规范）纳入 .cursor/skills，并调整 gitignore 仅放行 skills 目录可提交。 Co-authored-by: Cursor <cursoragent@cursor.com>
6.2 KiB
6.2 KiB
name, description
| name | description |
|---|---|
| cyclegui-app-development | 构建或修改基于 CycleGUI 框架的 .NET 桌面/Web 应用。CycleGUI 提供 ImGui 式立即模式 UI 面板和 3D Workspace 渲染能力。用于用户提到 CycleGUI、RefCycleGUI.dll、Costura.Fody、SimpleLite、PanelBuilder、GUI.PromptPanel、GUI.DeclarePanel、Workspace、Painter、LocalTerminal、LocalTerminal.Start、MinimizeToTray、HideConsoleOnStart、libVRender、WebTerminal、TCPTerminal、3D 场景、立即模式 UI、LoadModel、PutPointCloud，或需要新建/修改 CycleGUI 应用、示例、面板、工具栏、HoverMenu、菜单栏、视口、对象选择、坐标拾取、调试绘制时。 |
CycleGUI 应用开发
本 skill 是 CycleGUI 应用开发的启动卡片。普通任务应能在没有 CycleGUI 源码的情况下完成：先用本文搭出正确结构；需要完整签名、长示例或专题规则时，再按主题加载 reference。只有维护 CycleGUI 框架本体、修复底层 bug、或本地仓库已存在且需要核对变更时，才读取源码。
按需读取
- 项目引用、宿主/插件边界、启动流程：
references/project-setup-and-packaging.md - 面板、工具栏、HoverMenu、控件、菜单栏：
references/panels-controls-menus.md - Workspace 模型、点云、相机、视口、Painter：
references/workspace-scene-and-painter.md - Workspace 对象选择、坐标拾取、async 操作陷阱：
references/workspace-interaction.md - WebTerminal、LocalTerminal、LeastServer：
references/terminals-and-web.md - 完整 API 签名：
references/api-signatures.md - 完整示例：
references/examples.md
引用策略
先判断项目类型：
- 同解决方案示例：例如
LearnCycleGUI，可以ProjectReference到CycleGUI\CycleGUI.csproj。 - 宿主/调度程序：例如
SimpleLite，引用真实CycleGUI.dll，并用Costura.Fody把托管程序集包进宿主 Assembly。 - 插件或二次开发项目：默认引用
RefCycleGUI.dll，不要引用真实CycleGUI.dll。真实 CycleGUI 实现由宿主提供，用于保护 CycleGUI 代码资产并隔离二开项目。
最容易写错的是插件/二开项目：
<Reference Include="CycleGUI">
<HintPath>$(CGUILibDir)RefCycleGUI.dll</HintPath>
<Private>false</Private>
</Reference>
不要指导插件二开项目显式部署或打包真实 CycleGUI.dll。
最小骨架
常用 using：
using CycleGUI;
using CycleGUI.API;
using CycleGUI.Terminals;
using System.Drawing;
using System.Numerics;
启动本地窗口：
Terminal.RegisterRemotePanel(CreateMainPanel);
LocalTerminal.SetTitle("MyApp");
LocalTerminal.Start();
GUI.PromptPanel(CreateMainPanel(GUI.defaultTerminal));
最小面板：
PanelBuilder.CycleGUIHandler CreateMainPanel(Terminal terminal)
{
return pb =>
{
pb.Panel.ShowTitle("Main").InitSize(400, 300);
pb.Label("Ready");
if (pb.Button("Run")) { }
if (pb.Closing()) pb.Panel.Exit();
};
}
需要保留 panel 引用、控制 dock/toolbar/单实例时，用 GUI.DeclarePanel().Define(...)；细节见 references/panels-controls-menus.md。
常见任务路由
- 新建普通桌面/Web 应用：用本文骨架；需要完整 csproj 和 WebTerminal 细节时读
references/project-setup-and-packaging.md、references/terminals-and-web.md。 - 做插件二开：先确认引用
RefCycleGUI.dll；不要把真实CycleGUI.dll带进插件。 - 做表单、表格、toolbar、HoverMenu、菜单栏：读
references/panels-controls-menus.md。 - 加载模型、点云、相机、Painter 调试绘制：读
references/workspace-scene-and-painter.md。 - 做对象选择、坐标拾取、拖拽/放置或 async 交互：读
references/workspace-interaction.md。 - 不确定 API 签名：读
references/api-signatures.md，不要凭 ImGui 习惯猜 CycleGUI 方法。
必须记住
- 普通应用开发不要求用户或下游 agent 读取 CycleGUI 源码。
- CycleGUI 公开颜色字段使用
System.Drawing.Color；不要把 ARGBuint直接塞给颜色字段。 - 所有
namePattern是 glob，不是 regex："UISite-*"正确，"UISite-.*"错。 InitPosRelative的参数是left/top；不要写不存在的offsetX/offsetY。- CycleGUI 没有
BeginChild/ChildWindow/BeginTabBar/BeginTabItem；分区用Table(height:)、CollapsingHeader，标签页用TabButtons（支持forceSelect程序化切 Tab；Table支持scrollToRow程序化滚动到行，变化检测在 API 内部）。 - 不要依赖空壳控件：
Progress、BulletText、Indent/UnIndent、QuestionMark、ToolTip。 - 控件 id 由标签经 ASCII 哈希得到（中文、全角符号等非 ASCII 字符全部折叠成
?）：同一面板内两个「ASCII 折叠后相同」的标签会抛Duplicated id——最典型是同字数的纯中文标签（如筛选条件撞设为类型），或仅中文字符不同、ASCII 部分相同的两个标签（如起点筛选（站点ID或名称）撞终点筛选（站点ID或名称））。修法：标签加###唯一ASCII后缀（显示不变，###会重置哈希），Button用唯一distinct:，或加1./2.等数字前缀；循环内渲染带状态控件须给每项拼唯一 id（如$"启用###en-{item.Id}"）。详见references/panels-controls-menus.md。 - 立即模式：面板默认不会每帧重绘；只在
pb.Panel.Repaint()被调用时重新执行 handler。静态面板（Properties / Actions 等）不要无条件 Repaint；仅实时数据区（Status、MiniPlot、后台线程推送等）才持续 Repaint。延迟回调或跨线程改数据后须显式 Repaint。详见references/panels-controls-menus.md。 - 画布/Workspace 里的业务对象需要点击或选择时，默认用原生
SelectObject+ 可选 Workspace 对象，不要用GetPosition手写命中测试。 SelectObject和GetPosition是互斥交互；进入拾取前结束选择 op，结束后重新启动选择 op。- 修改 CycleGUI C# API、维护框架本体、排查 libVRender/协议问题、或发现 reference 缺失时，才核对源码并同步更新 references。