ctbjrj/.agents/skills/sd-enhanced-components/SKILL.md

name, description

name

description

sd-enhanced-components

SharpDevelop 5.x WinForms 设计器**全部工具箱**（5 分类 81 条目）的属性手册与 Designer.cs 代码生成规则：增强组件（Smart.CustomComponents 13 个：停靠面板/停靠窗口、圆角按钮、图片按钮、侧边菜单、功能区 RibbonStrip、增强数据表格、多选下拉框、可调高文本框/下拉框、OK/NG 状态灯、变量绑定控件、日志组件）+ 标准控件（Button/TextBox/ListView/TreeView/TabControl/菜单工具栏/对话框等 45 个）+ 数据/组件/打印（BindingSource、Timer、SerialPort、PrintDocument 等 23 个）。每个控件含全部属性（类型/默认值/序列化规则）、事件与运行时 API。当用户要在 WinForms 项目里使用、询问属性、手写或生成任何 *.Designer.cs 代码、生成停靠窗口类、排查"?"载入错误或"valid theme"运行错误时，必须使用本技能。提到"增强组件""Smart.CustomComponents""停靠窗口""功能区""RibbonStrip""工具箱""某个控件有哪些属性""生成设计器代码"即触发。新建解决方案时用 copy-to-solution.cmd 把本技能复制到项目里。

SharpDevelop 增强组件（Smart.CustomComponents）手册

库源码：F:\Visual Studio\1\33\SharpDevelop-master\src\Libraries\CustomComponents\（本技能内容即从该源码与编译产物反射逐项提取，属性名/类型/默认值以源码为准）。 工具箱类别名：增强组件（SharpDevelopControlLibrary.sdcl 注册，13 个控件）。

使用本技能的典型任务

1. 在用户项目里手工使用/推荐这些控件的属性（"这个控件有哪些属性"）
2. 生成或校对 *.Designer.cs（SharpDevelop CodeDom 序列化风格）
3. 从停靠窗口集合配置生成窗口类三件套（等价于"生成停靠窗口代码"命令）
4. 排错：设计器载入 ?、运行时 "DockPanel.Theme must be set to a valid theme"

工具箱全量清单（5 分类 81 条目，权威来源 data\options\SharpDevelopControlLibrary.sdcl）

分类	条目数	属性手册
增强组件（Smart.CustomComponents）	13	references/components.md
Windows Forms（标准控件+菜单+对话框）	45	references/winforms-controls.md
Data（绑定/表格/数据集）	7	references/winforms-components.md
Components（后台/IO/系统组件）	11	references/winforms-components.md
Printing（打印全家桶）	5	references/winforms-components.md

（Timer/ErrorProvider/HelpProvider/ImageList 在 Windows Forms 与 Components 两个分类重复出现，规则一致；Data 分类里的 DataNavigator 在 .NET 4.8 不存在，是死条目，用 BindingNavigator。）

读哪个文件：增强组件 → references/components.md；标准控件/菜单/对话框 → references/winforms-controls.md；组件/数据/打印 → references/winforms-components.md；写任何 Designer.cs 代码前再读 references/codegen.md（骨架模板、Content 集合、菜单嵌套、ListView/TreeView、RibbonStrip 三层集合、非可视组件、停靠窗口三文件流程）。

复制到新解决方案（三种方式，已自动化）

本技能的分发链（源→编译产物→新方案）：

用户级正本 C:\Users\099978\.agents\skills\sd-enhanced-components\   ←源（改这里）
  ① 编译 Smart.CustomComponents 时同步到 SharpDevelop 仓库根副本 + bin\sd-enhanced-components\
    （bin = 设计器编译输出/测试运行目录）
  ② SharpDevelop 新建解决方案时自动复制到 <新方案>\.agents\skills\sd-enhanced-components\

1. 全自动：本定制版 SharpDevelop 在"文件→新建→解决方案"落盘后自动复制（ProjectTemplate.CreateAndOpenSolution 里调 SkillFolderSync，日志在 bin\SkillSync.Log.txt）。源找不到时自动回退：先 bin，再应用根目录。
2. 手动脚本：copy-to-solution.cmd <解决方案目录>（同样复制到 <目录>\.agents\skills\sd-enhanced-components\）。
3. 全局生效：用户级技能目录本就全局生效——复制是留档与给其他 AI 工具。

改手册后同步三处：用户级正本 → 重编 Smart.CustomComponents（自动进仓库根副本 + bin）→ 新方案由 SharpDevelop 自动带。

零、项目组织铁律（用户强制，最高优先级）

1. UI 只写主窗口：新建解决方案自带的主窗口 MainForm（MainForm.cs / MainForm.Designer.cs）是唯一 UI 承载体，所有控件/布局/Designer.cs 生成一律写进 MainForm；Program.cs 保持 Application.Run(new MainForm())。
2. 绝不另开窗口写 UI：不要为了放界面新建 TestForm/Form2 之类第二个窗体；多窗口只在用户明确要求时才做。
3. AI 生成 Designer.cs 前必须先写引用（否则死锁）：手写/生成 Designer.cs 用了增强控件而项目尚无程序集引用时，设计器加载第一步（类型解析）就失败（一片 CS0246），而"自动补引用"恰恰跑在设计器加载流程内部——类型解析不过它就没机会执行，形成死循环：引用缺失 → 设计器加载失败 → 自动补引用不触发 → 引用依然缺失。所以写 Designer.cs 的同一次改动里必须先把 9 个引用写进 csproj（完整清单见第一章）。HintPath 默认指向 SharpDevelop 安装目录 C:\Program Files (x86)\SharpDevelop\5.2\bin——装完即存在、机器间一致；装在非默认位置时先用第一章"定位实际安装目录"找到真实 bin 再写；开发机要立刻用仓库最新控件时可临时换仓库 bin F:\Visual Studio\1\33\SharpDevelop-master\bin（仅本机存在，交付/通用模板别用）。前提：安装目录必须是最新构建（jk55 案例：08-27 旧安装包缺 RibbonStrip/Logger，13 控件只认 11——须重打 MSI 重装或用仓库 bin 最新 DLL 覆盖安装目录）。"切设计标签自动补引用"只在工具箱拖放场景有效（那时设计器本来就能加载）。<Private>True</Private> 编译时会把 DLL 复制进项目 bin\Debug，之后运行/分发不再依赖 HintPath 原位置。案例：jk55 项目（2026-09-01）。
4. 历史测试项目里 AI 写的 TestForm（如 ww123）是测试产物，不是范本；交付写法以本节为准。
5. 属性白名单 + 报错后完全重启（s23 案例 2026-09-01）：Designer.cs 每个属性必须能在 components.md 该控件条目下查到——跨控件抄属性会抛 CodeDomSerializerException（"没有名为 X 的属性"）并中止整个设计器加载（已知易错：VariableEditTextBox 无 PlaceholderText、VariableDisplayLabel 无 BorderStyle）。改完报错的 Designer.cs 后必须完全退出 SharpDevelop.exe 重开（关标签页没用）——设计器 CodeDom 反序列化的 AppDomain 在进程内缓存旧异常，不重启会一直回放。
6. 新窗口开发前必须全面规划，确保 SD 设计器可打开可编辑（用户强制 2026-10-01）：每个新窗口的开发需求，动手写代码前必须先产出规划，规划内容详细到能直接指导后续设计与开发。规划至少包含四块：
   • 控件规划：窗口内所有控件的类型选择（增强组件/标准控件，对照本手册属性白名单）、命名、布局设计（Location/Size/Dock/Anchor/分组）、属性配置（只写非默认值）；
   • 交互逻辑：各控件之间的联动关系、事件挂接、状态流转；
   • 依赖清单：所需引用的资源文件（图标/图片/resx）、组件库与依赖程序集（Designer.cs 用到增强控件时，同一次改动先写 csproj 引用，见第 3 条）；
   • 数据接口：窗口与其他系统模块（主窗口/数据库/停靠布局/外部进程）的数据交互方式与调用入口。 窗口一律采用双文件结构：窗口名.Designer.cs（纯布局与属性，SD 设计器能正确打开并继续编辑微调）+ 窗口名.cs（交互逻辑与业务代码），Designer.cs 里绝不写业务代码；窗口文件记得同步注册进 csproj（Compile Include + Designer.cs 加 <DependentUpon>）。
7. 版本号铁律（用户强制 2026-10-01）：每次发版必须递增版本号。每次打安装包/发 Gitea Release 前，必须先跑 tools\递增版本号.ps1（默认修订号 +1，如 1.0.3→1.0.4；大改动可传参指定如 1.1.0）。规则：
   • 唯一事实源 = 成套报价软件\Properties\AssemblyInfo.cs 的 AssemblyVersion（固定三段式 主.次.修订.0，禁用 1.0.* 自动号——每次编译都变，无法对应发布的安装包）；
   • 「关于软件」窗口运行时自动读程序集版本显示（不在 Designer 写死）；
   • release\成套报价软件\setup.iss 的 AppVersion 与 OutputBaseFilename=成套报价软件_Setup_版本 由脚本同步；
   • Gitea Release 的 tag 与版本号一致（如 v1.0.4）；
   • 发版链固定为：递增版本号 → 编译 → make_package → ISCC → 更新包 → git 提交推送 → Release。跳过递增 = 两个不同功能的安装包同版本号，用户分不清、回滚排障全乱。
8. git 推送流程与故障排查（2026-10-01 实战沉淀，用户强制写入）。日常流程：改动 → git add -A → git commit -m "中文消息" → git push（remote 已内嵌用户令牌自动认证，无需弹窗）。Release 附件（安装包/更新包）走 Gitea 附件存储只在发版时上传一次，git push 只推源码文本，两者互不相干——不要混淆"推送源码"与"重传安装包"。常见失败与处置：
   • Failed to authenticate user / 认证失败：令牌失效或被撤销。让用户去 Gitea 网页 头像→设置→应用 生成新令牌（勾 repository 读写），然后 git remote set-url origin http://0999we:<新令牌>@192.168.9.43:3000/0999we/ctbjrj.git。同令牌也用于 Gitea REST API（Authorization: token <令牌> 头，建 Release/传附件用）。
   • ! [rejected] (fetch first)：远程有本地没有的提交（通常是用户自己在 Gitea 网页上传过文件）。处置：git fetch → git log HEAD..origin/master --oneline 看远程新增 → git pull --rebase 整合 → git push。绝不 force push（会抹掉用户网页上传的东西）。
   • GCM 弹窗/OAuth 凭据残留：本项目不靠 GCM（remote 内嵌令牌）。若 cmdkey 里出现 git:http://refresh_token.192.168.9.43:3000 之类失效条目，cmdkey /list | findstr 192.168 找到后 cmdkey /delete <条目名> 清掉。
   • 另一个程序正在使用此文件：git add/checkout 撞上运行中的 node/AI 引擎/主程序占用。先 Get-CimInstance Win32_Process 查占用进程（看 CommandLine 路径），Stop-Process 结束开发目录侧的进程再操作（安装目录 C:\成套报价软件 下的不动）。
   • .gitignore 否定规则陷阱：父目录被排除时深层 ! 否定无效（!release/成套报价软件/setup.iss 配 release/* 不生效）。必须逐层放行：!release/ → release/* → !release/成套报价软件 → release/成套报价软件/* → !release/成套报价软件/setup.iss。改完用 git status --short 验证目标文件真的 staged（A 状态）。
   • 中文路径显示八进制转义（\346\210\220...）：git 默认 quotepath，排查时加 -c core.quotepath=false，如 git -c core.quotepath=false ls-tree -r --name-only HEAD。
   • LF→CRLF warning：无害，忽略。
   • push 后验证：git ls-remote origin 的 HEAD 与本地 git log -1 哈希一致才算成功。

一、项目前提（缺一不可）

用这些控件的用户项目必须是：

<TargetFrameworkVersion>v4.8</TargetFrameworkVersion>
<PlatformTarget>x86</PlatformTarget>   <!-- SharpDevelop 调试器仅 32 位；SQLite 为 x86 混合模式 -->
<Prefer32Bit>true</Prefer32Bit>
<ApplicationManifest>app.manifest</ApplicationManifest>  <!-- dpiAware，否则运行时缩放 2/3 -->

引用清单（老式 csproj 引用不传递，9 个全要，HintPath 默认指向 SharpDevelop 安装目录 C:\Program Files (x86)\SharpDevelop\5.2\bin（稳定、装完即有）；开发机临时用仓库 bin 见零章第 3 条）：

程序集	备注
Smart.CustomComponents, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ba044a4aa43e0dc4	主库，强命名
WeifenLuo.WinFormsUI.Docking	DockSurface 基类 DockPanel
WeifenLuo.WinFormsUI.Docking.ThemeVS2015	VS2015 主题（含关闭按钮补丁）
System.Data.SQLite	x86 混合模式 1.0.119（增强表格用，无需 Interop.dll）
log4net	Logger 日志组件后端（漏了 Logger 报类型解析失败）
System.Resources.Extensions / System.Memory / System.Runtime.CompilerServices.Unsafe / System.Numerics.Vectors	二级依赖链（主题资源加载必需，漏了运行时报 valid theme）

HintPath 模板：C:\Program Files (x86)\SharpDevelop\5.2\bin\<dll 名>，并加 <Private>True</Private>（可复制 csproj 片段见 codegen.md §0.1）。 工具箱拖放会自动补齐引用（此时设计器能加载，自动补才跑得起来）；AI 手写 Designer.cs 必须按零章第 3 条先写引用。

定位实际安装目录（装在非默认位置时，AI 按顺序执行）

注册表卸载键的 InstallLocation 是空的（WiX 安装包不写该值），别指望它。按可靠性依次试：

# ① IDE 正在运行：进程路径（exe 所在目录即 bin，最直接）
Get-Process SharpDevelop -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Path

# ② 开始菜单快捷方式解析（已实测可用）
$s = New-Object -ComObject WScript.Shell
Get-ChildItem "$env:ProgramData\Microsoft\Windows\Start Menu\Programs", "$env:AppData\Microsoft\Windows\Start Menu\Programs" -Recurse -Filter '*SharpDevelop*.lnk' -ErrorAction SilentlyContinue | ForEach-Object { $s.CreateShortcut($_.FullName).TargetPath }

# ③ 已有项目的 HintPath（能跑通的项目里记的就是真实安装位置）
Get-ChildItem "$env:USERPROFILE\Documents\SharpDevelop Projects" -Recurse -Filter *.csproj -ErrorAction SilentlyContinue | Select-String 'Smart\.CustomComponents\.dll.*HintPath'

# ④ 常见默认位置探测
Test-Path 'C:\Program Files (x86)\SharpDevelop\5.2\bin\SharpDevelop.exe'
Test-Path 'C:\Program Files\SharpDevelop\5.2\bin\SharpDevelop.exe'

找到的 SharpDevelop.exe 所在目录就是 HintPath 前缀（安装布局固定为 ...\SharpDevelop\<版本>\bin\）。仍找不到时问用户装在哪，不要瞎猜路径写进 csproj。

二、控件速查（详见 references/components.md；标准控件见 winforms-controls.md）

控件	类型全名（命名空间 Smart.CustomComponents）	核心属性	生成代码注意
停靠面板 DockSurface	DockSurface : DockPanel	DockTheme、DockWindows 集合、LayoutFileName	Content 集合 + 三文件生成（见 codegen.md）
圆角按钮 RoundedButton	RoundedButton : Control	Style(8 种配色)、Radius、三态色、Border	枚举序列化用英文名
图片按钮 ImageButton	ImageButton : Control	属性名就是中文：图片路径/图片缩放/图文布局…	生成代码直接写中文标识符
侧边菜单 SideMenuPanel	SideMenuPanel : UserControl	MenuItems、Pages、菜单宽度/行高/配色 10 项	两个 Content 集合，页面走 sideMenuPageN 字段
功能区 RibbonStrip	RibbonStrip : UserControl	Tabs→Groups→Buttons 三层集合、AccentColor 等 4 色、ActiveTabIndex	图标走 RibbonButton.FromFile("路径")；点击统一 ButtonClick(e.Tab/e.Group/e.Button)
增强数据表格 EnhancedDataGridView	EnhancedDataGridView : DataGridView	EnableExcelStyleSelection、Sqlite 三件套、EnableCellPaste	列走标准 DataGridView Columns 序列化
多选下拉框 MultiSelectComboBox	MultiSelectComboBox : Control	Items、MultiSelect、Searchable、AllowCustomInput、Token 配色	Items 是 Content 字符串集合
可调高下拉框 ResizableComboBox	ResizableComboBox : Control	Items、SelectedIndex、Flat、箭头/边框配色	SelectedText 不序列化
可调高文本框 ResizableTextBox	ResizableTextBox : Control	PlaceholderText、Flat、三态边框色、密码字符	高度自由（这是它的存在意义）
OK/NG 状态灯 OKNGStatusControl	OKNGStatusControl : Control	IsOK、BindVariable	绝不写 Text（自绘覆盖）
变量显示标签 VariableDisplayLabel	VariableDisplayLabel : Control	BindVariable、DisplayValue、TextAlign	只读，事件 ValueChanged
变量编辑框 VariableEditTextBox	VariableEditTextBox : TextBox	BindVariable（Value=Text）	即 TextBox，仅多绑定属性
日志记录器 Logger（非可视）	Logger : Component	日志文件名/日志级别/按天滚动/最多保留份数	log4net 后端；代码调 写信息/写警告/写错误/写异常；详见 components.md 第 12 节

标准控件最常用的"总是写/绝不写"清单（完整规则在 winforms-controls.md）：Label 的 AutoSize = true、CheckBox 与 TabPage 的 UseVisualStyleBackColor = true 总是写；DateTimePicker 的 Value、Timer 的 Enabled、各对话框的运行时结果绝不写。

三、代码生成五条铁律

1. 只序列化非默认值。属性表里给了每个属性的默认值——与默认相同就不写进 Designer.cs（SharpDevelop 序列化器行为，手写也要遵守，否则设计器重载后会"多出"赋值行）。
2. 枚举一律用英文标识符（属性网格显示的中文来自 TypeConverter，ChineseEnumConverter.ConvertTo 只管显示；EnumCodeDomSerializer 序列化走原始名）。例：this.roundedButton1.Style = Smart.CustomComponents.RoundedButtonStyle.Success; 唯一例外是 ImageButton——它的属性/枚举本身就是中文标识符（图文布局.图左文右）。
3. Content 集合（MenuItems/Pages/Items/DockWindows）逐条目生成：new 条目 → 赋非默认属性 → 父.集合.Add(条目临时变量)。标了 Hidden/Browsable(false) 的属性（PersistString、ContentXml、ColumnsXml、SourceFile、Selected* 等）绝不写。
4. 事件在属性赋值之后、Controls.Add 之前挂：this.roundedButton1.Click += new System.EventHandler(this.roundedButton1_Click);
5. 颜色属性带 ShouldSerialize 默认值（见属性表"序列化条件"列），与出厂色相同则省略。

四、排错速查

症状	根因	处置
设计器抛 CodeDomSerializerException："XX 没有名为 YY 的属性"，窗体全不显示（s23 案例）	Designer.cs 写了该控件没有的属性（跨控件抄属性）；反序列化遇未知属性即中止整个加载	对照 components.md 该控件的白名单删掉错行；删完完全退出重启 IDE（设计器 AppDomain 缓存旧异常，不重启继续报）
构建报 MSB3644"找不到 v4.8 参考程序集"+ 一串 MSB3247 版本冲突；设计器偶发无输出（s23 案例）	系统只装了 4.8.1 Developer Pack，Reference Assemblies\...\.NETFramework\v4.8 目录为空，MSBuild 只能从 GAC 捞到 v2.0/v4.0 混解析	装 .NET 4.8 Developer Pack 离线包（NDP48-DevPack-ENU.exe 约 140MB，静默装）；装完 v4.8 目录 133 个参考 DLL，MSB3644/MSB3247 一起消失
AI 生成项目后设计区空白/一片 CS0246（jk55 案例）	Designer.cs 用了增强控件但 csproj 无程序集引用；设计器加载第一步类型解析就失败，"自动补引用"跑在加载流程内部永远不触发——死锁：引用缺失→加载失败→自动补不触发→引用仍缺失	同一次改动里手动把 9 个引用写进 csproj（清单见第一章），HintPath 指向安装目录；写完再开设计视图即正常。自动补引用只在工具箱拖放场景可用
自动补引用兜底后仍剩个别 CS0246（RibbonStrip/Logger 认不出）	安装目录 C:\Program Files (x86)\SharpDevelop\5.2\bin 的 DLL 是旧构建（08-27 包缺这两个类型，13 控件只认 11）	重打 MSI 重装（或把仓库 bin 最新 DLL 覆盖安装目录），让稳定路径带全 13 控件；开发机可临时把 HintPath 指仓库 bin 过渡
设计器载入 "Could not find type '?'"	项目引用解析不到（裸引用无 HintPath）	08-25 13:53 及以后的 MSI 已在引用解析层中心兜底（自动回退到安装 bin）；旧包则补 HintPath
运行时 "DockPanel.Theme must be set to a valid theme"	缺二级依赖链（Resources.Extensions 等 4 个）	13:53+ 的库带 AssemblyResolve 运行时兜底；或按第一节补全 8 个引用。诊断看 bin\Debug\DockWindows.Log.txt
运行时菜单重复/集合翻倍	设计期默认内容放进了构造函数	默认集合内容只能在 Designer.Initialize 且 !host.Loading 时注入（SideMenuPanel 已修，新控件照此办理）
自定义集合编辑器改了不保存	原地改集合没发 IComponentChangeService 通知	编辑器写回前后发 OnComponentChanging/Changed
CellStyle Builder/列编辑器等框架对话框全英文	.NET Framework 中文语言包未装（GAC 无 System.Design.resources zh-Hans）	装 .NET 4.8 简体中文语言包（fwlink 2053984，/q /norestart），一次修复所有控件的框架编辑器外壳（标题/按钮）
对话框外壳已中文但内部属性行仍英文	内部 PropertyGrid 的属性行走翻译层词典；DataGridViewCellStyle 不是 Component，单独注册	DesignerTranslation.Install() 已为 DataGridViewCellStyle 补挂类型级提供器；缺行名就往词典加一条（如 SortMode→排序模式）
改 CoreProperties.UILanguage 为 zh-CN 后整个 IDE 变英文	SD 自家资源只有中性 zh 命名，具体文化不被识别回落 en	保持 UILanguage=zh；用 ResourceService 里 IsNeutralCulture→CreateSpecificCulture 升格线程文化的代码补丁（勿动配置）
属性面板改列标题高度模式后不生效/被顶回	Designer.cs 残留显式模式行 + 引用指向旧版库 DLL	删掉 Designer.cs 中该行；确认项目 HintPath 指向当前编译产物；EDG.Ctor.Log.txt 有"谁改的模式+调用栈"

诊断优先级（用户要求）：读日志文件（DockWindows.Log.txt / EDG.Ctor.Log.txt / DesignerTranslation.log），截图识别是最后手段。