暂时更改一部分Skill

This commit is contained in:
chfei committed 2026-10-27 19:01:56 +08:00
1 parent 84b28f9672
commit 6d4629e4ac
53 files changed
+5293 -10

No files matched your search

+66
View File
@@ -0,0 +1,66 @@
---
name: max-common
description: 在 .NET 项目中接入和使用 MAX.Common,复用其命令、属性通知、集合视图、数值与文件工具、枚举和事件功能。适用于明确使用 MAX.Common 或项目已引用该库的开发任务;WPF 控件和附加行为由 max-common-wpf 处理。
---
# MAX.Common 功能使用
帮助消费项目复用 MAX.Common 的真实能力,避免重复实现已有工具。此 Skill 是使用指南,不包含库二进制,也不要求访问原开发仓库。
## 接入与版本
- 先检查消费项目的 `.csproj`、`Directory.Packages.props`、NuGet 配置和已有 using,保留其依赖管理方式。
- 本参考基于 2026-10-27 的源码快照:包 `MAX.Common` 1.4.17,目标为 `netstandard2.0;netstandard2.1`。这是快照版本,不代表最新版本。优先沿用项目已安装的兼容版本;需要新增时使用可用源中的确定版本。
- 普通项目通过 `PackageReference Include="MAX.Common" Version="1.4.17"` 接入;集中包管理项目将版本放到 `PackageVersion`。源码工程采用 C# 12,不代表所有调用项目都必须使用 C# 12。
- `PolySharp` 是库构建依赖(PrivateAssets=all),不要仅为调用库强制添加它。没有必要为使用本库引入 MAX.Core、Prism 或其他应用框架。
## 按需求选择功能
先阅读 [功能索引](references/features.md) 中与任务对应的部分。需要确定命名空间、构造参数和方法名称时,搜索 [常用 API 声明](references/api.md) 的文件名或类型名;这是选定功能的声明摘录,不是全部 API,也不包含完整实现语义。
引用的包版本与快照不同时,以本地已安装包 XML 文档、反射结果、源码或编译器为准。没有源码时不假设原仓库存在,更不编造未收录的方法。
## 已确认的使用约束
- `MethodCommand<T>` 和 `AsyncMethodCommand<T>` 只接受引用类型或可空值类型,例如 `int?`;`int` 会在构造时抛出异常。传入的实际 CommandParameter 仍必须能转换为 T。
- 命令状态变化后调用 `RaiseCanExecuteChanged()`;库不会自动观察业务属性。同步命令的 `Execute` 不检查 `CanExecute`,程序直接执行时自行判断。
- `AsyncMethodCommand` 使用 `async void Execute`,执行期间拒绝重复执行,通过 finally 恢复状态,但不吞掉业务异常。需要呈现错误时在异步委托中捕获并处理;它不是可 await 的 `ExecuteAsync` API,也不是跨线程互斥锁。
- `BindModelBase` 使用 `SetProperty(ref field, value, ...)`;`BindableBaseEx` 同时提供属性包 `GetValue/SetValue` 和字段方式。两者构造函数都会调用虚方法 `OnInitialized()`,不要在该回调中依赖派生构造函数才完成的初始化。
- `BindModelBase` 先执行 onChanged 再通知属性变化,`BindableBaseEx` 的字段设置先通知再调用 changedCallback。涉及通知顺序时不要将二者视为完全等价。
- `AsyncEvent<TEventArgs>` 通过可空字段 `+=` 首次创建,构造函数私有;`InvokeAsync` 按注册顺序逐个 await,异常会中止后续回调。首次并发订阅存在竞争,不能当作线程安全事件总线。
- `RunLimiter` 限制实例生命周期内的尝试次数,不是时间窗口节流,也不限制同时运行数;动作抛异常也已消耗计数。
- `PathValidator.IsFolderPathValidAndSafe(path, allowRelativePath)` 检查路径格式,不保证存在、可写或位于允许的根目录;路径范围约束需要调用方另外实现。
- `SerializationHelper.TryGetValue` 面向 `SerializationInfo`,失败返回默认值,不是 JSON 序列化工具。`MD5Helper`、Base64 和 URI 编码工具的名称不代表它们提供密码加密。
## 最小用法
```csharp
using MAX.Common.Commands;
using MAX.Common.Models;
public sealed class EditorModel : BindModelBase
{
private string name = string.Empty;
public MethodCommand ClearCommand { get; }
public EditorModel()
{
ClearCommand = new MethodCommand(() => Name = string.Empty,
() => Name.Length > 0);
}
public string Name
{
get => name;
set
{
if (SetProperty(ref name, value))
ClearCommand.RaiseCanExecuteChanged();
}
}
}
```
## 验证与交付
按消费项目实际 TFM 构建。对使用到的行为验证关键边界,例如命令空参数与异常恢复、集合空源与索引、文件路径无效输入。只调用本库时无需构建整个原始解决方案。交付时说明引用版本、变更文件与验证结果;未执行的验证明确标注,可按需继续代码审查。
@@ -0,0 +1,3 @@
interface:
display_name: "MAX.Common"
short_description: "复用 MAX.Common 的命令、绑定模型、集合与通用工具能力"
+381
View File
@@ -0,0 +1,381 @@
# 常用 API 声明参考
来源:MAX.Common,2026-10-27 工作区源码快照。
按下方主题或文件名搜索。仅摘录选定文件的 public / protected 声明;省略方法体、初始化表达式与 XML 注释。这是定位参考,不是可直接编译的 C#,不保证包含嵌套类型的完整可见性上下文。行为说明见 SKILL.md;目标包版本不同时以实际包为准。
目录:命令与绑定模型、集合与数据、文件、数值与校验、事件与运行控制
## 命令与绑定模型
### Commands/MethodCommand.cs
命名空间:`MAX.Common.Commands`
```csharp
public class MethodCommand( Action execute, Func<bool>? canExecute = null ) : ICommand
public event EventHandler? CanExecuteChanged
public bool CanExecute(object parameter)
public void Execute(object parameter)
public void RaiseCanExecuteChanged()
public class MethodCommand<T> : ICommand
public MethodCommand( Action<T> execute, Func<T, bool>? canExecute = null )
public event EventHandler? CanExecuteChanged
public bool CanExecute(object parameter)
public void Execute(object parameter)
public void RaiseCanExecuteChanged()
```
### Commands/AsyncMethodCommand.cs
命名空间:`MAX.Common.Commands`
```csharp
public class AsyncMethodCommand(Func<Task> execute, Func<bool>? canExecute = null) : ICommand
public event EventHandler? CanExecuteChanged
public bool CanExecute(object parameter)
public async void Execute(object parameter)
public void RaiseCanExecuteChanged()
public class AsyncMethodCommand<T> : ICommand
public event EventHandler? CanExecuteChanged
public AsyncMethodCommand(Func<T, Task> execute, Func<T, bool>? canExecute = null)
public bool CanExecute(object parameter)
public async void Execute(object parameter)
public void RaiseCanExecuteChanged()
```
### Models/BindModelBase.cs
命名空间:`MAX.Common.Models`
```csharp
public abstract class BindModelBase : INotifyPropertyChanged
public event PropertyChangedEventHandler? PropertyChanged
public BindModelBase()
public virtual void OnInitialized()
public virtual bool ShouldCheckValueMatching<T>(string? propertyName, T from, T to)
protected virtual bool SetProperty<T>(ref T storage, T value, Action? onChanged = null, [CallerMemberName] string? propertyName = null)
protected virtual bool SetPropertyNoCheck<T>(ref T storage, T value, Action? onChanged = null, [CallerMemberName] string? propertyName = null)
protected virtual void OnPropertyChanging<T>(string? propertyName, T from, T to, CancelEventArgs cancelEventArgs)
protected virtual void OnPropertyChanged(PropertyChangedEventArgs args)
protected void RaisePropertyChanged([CallerMemberName] string? propertyName = null)
```
### Models/BindableBaseEx.cs
命名空间:`MAX.Common.Models`
```csharp
public abstract class BindableBaseEx : INotifyPropertyChanged
public event PropertyChangedEventHandler? PropertyChanged
public BindableBaseEx()
public virtual void OnInitialized()
public static string GetPropertyName<T>(Expression<Func<T>> expression)
protected T? GetProperty<T>(Expression<Func<T>> expression)
protected bool SetProperty<T>(Expression<Func<T>> expression, T value)
protected bool SetProperty<T>(Expression<Func<T>> expression, T value, Action? changedCallback)
protected bool SetProperty<T>(Expression<Func<T>> expression, T value, Action<T?>? changedCallback)
protected bool SetProperty<T>(ref T storage, T value, Expression<Func<T>> expression)
protected bool SetProperty<T>(ref T storage, T value, Expression<Func<T>> expression, Action? changedCallback)
protected void RaisePropertyChanged<T>(Expression<Func<T>> expression)
protected T? GetValue<T>([CallerMemberName] string? propertyName = null)
protected bool SetValue<T>(T value, [CallerMemberName] string? propertyName = null)
protected bool SetValue<T>(T value, Action? changedCallback, [CallerMemberName] string? propertyName = null)
protected bool SetValue<T>(T value, Action<T?>? changedCallback, [CallerMemberName] string? propertyName = null)
protected bool SetValue<T>(ref T storage, T value, [CallerMemberName] string? propertyName = null)
protected bool SetValue<T>(ref T storage, T value, Action? changedCallback, [CallerMemberName] string? propertyName = null)
protected bool SetProperty<T>(ref T storage, T value, string propertyName)
protected virtual bool SetProperty<T>(ref T storage, T value, string propertyName, Action? changedCallback)
protected virtual bool SetPropertyCore<T>(string propertyName, T value, out T? oldValue)
protected virtual void RaisePropertyChanged(string propertyName)
protected void RaisePropertyChanged()
protected void RaisePropertiesChanged(params string[]? propertyNames)
protected virtual void VerifyAccess()
protected virtual bool CompareValues<T>(T storage, T value, string propertyName)
```
### Models/BindObject.cs
命名空间:`MAX.Common.Models`
```csharp
public sealed class BindObject<T> : BindModelBase
public event TypedEventHandler<BindObject<T>, PropertyValueUpdatedEventArgs<T>>? ValueChanged
public T? Value
public BindObject(T? defaultValue = default)
public void Set(T value)
public static implicit operator BindObject<T>(T value)
public static implicit operator T?(BindObject<T> value)
```
## 集合与数据
### Data/Collections/BidirectionalDictionary.cs
命名空间:`MAX.Common.Data.Collections`
```csharp
public class BidirectionalDictionary<TKey, TValue> : IDictionary<TKey, TValue>, IDictionary, IReadOnlyCollection<KeyValuePair<TKey, TValue>>
public TValue this[TKey key]
public int Count
public ICollection<TKey> Keys
public ICollection<TValue> Values
public bool IsReadOnly
public bool IsFixedSize
public bool IsSynchronized
public object SyncRoot
public BidirectionalDictionary()
public BidirectionalDictionary(int capacity)
public void Add(TKey key, TValue value)
public bool Remove(TKey key)
public bool RemoveByValue(TValue value)
public void Clear()
public bool TryGetValue(TKey key, out TValue value)
public bool TryGetKey(TValue value, out TKey key)
public TKey GetKey(TValue value)
public TValue GetValue(TKey key)
public bool ContainsKey(TKey key)
public bool ContainsValue(TValue value)
public void Add(KeyValuePair<TKey, TValue> item)
public bool Contains(KeyValuePair<TKey, TValue> item)
public void CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex)
public bool Remove(KeyValuePair<TKey, TValue> item)
public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
```
### Data/Lists/CyclicReadOnlyList.cs
命名空间:`MAX.Common.Data.Lists`
```csharp
public class CyclicReadOnlyList<T> : IReadOnlyList<T>
public CyclicReadOnlyList(IReadOnlyList<T> source, int startIndex, int loopCount)
public int Count
public T this[int index]
public IEnumerator<T> GetEnumerator()
```
### Data/Lists/SelectorReadonlyList.cs
命名空间:`MAX.Common.Data.Lists`
```csharp
public class SelectorReadonlyList<TSource, TResult>(IReadOnlyList<TSource> source, Func<TSource, TResult> selector) : IReadOnlyList<TResult>
public TResult this[int index]
public int Count
public IEnumerator<TResult> GetEnumerator()
public static class SelectorReadonlyListExtensions
public static IReadOnlyList<TResult> SelectAsReadonlyList<TSource, TResult>(this IReadOnlyList<TSource> source, Func<TSource, TResult> selector)
```
### Data/Lists/ReversedReadonlyList.cs
命名空间:`MAX.Common.Data.Lists`
```csharp
public class ReversedReadonlyList<T>(IReadOnlyList<T> source) : IReadOnlyList<T>
public IReadOnlyList<T> Source
public virtual T this[int index]
public int Count
public IEnumerator<T> GetEnumerator()
```
### Data/PrecisionBuilder.cs
命名空间:`MAX.Common.Data`
```csharp
public class PrecisionBuilder
public int PrecisionLength
public bool UseScientificNotation
public int ScientificNatationTriggerLength
public bool RemoveTrailingZeros
public PrecisionBuilder( int precisionLength, bool useScientificNotation, int scientificNatationTriggerLength, bool removeTrailingZeros )
public PrecisionBuilder( int precisionLength, bool useScientificNotation, int scientificNatationTriggerLength, bool removeTrailingZeros, string scientificNotationString, string autoString )
public string GetResultString(double d)
```
### Models/EnumItem.cs
命名空间:`MAX.Common.Models`
```csharp
public readonly record struct EnumItem( string Name, object Value, string? Description, string? ToolTip )
public static IEnumerable<EnumItem> GetEnumItems<T>() where T : Enum
public static IEnumerable<EnumItem> GetEnumItems(Type type)
public static EnumItem GetEnumItem(Enum @enum)
```
## 文件、数值与校验
### Helpers/FileHelper.Size.cs
命名空间:`MAX.Common.Helpers`
```csharp
public static partial class FileHelper
public static string FileSizeToKB(this long size, string format = "#,##0", string prefix = "", string suffix = " KB")
public static string FileSizeToMB(this long size, string format = "#,##0", string prefix = "", string suffix = " MB")
public static string FileSizeToGB(this long size, string format = "#,##0", string prefix = "", string suffix = " GB")
public static string FileSizeToTB(this long size, string format = "#,##0", string prefix = "", string suffix = " TB")
public static string FileSizeToPB(this long size, string format = "#,##0", string prefix = "", string suffix = " PB")
public static string FileSizeToString(this long size, string format = "#,##0.##", string prefix = "")
```
### Helpers/FileHelper.cs
命名空间:`MAX.Common.Helpers`
```csharp
public static partial class FileHelper
public static string GetUniqueFileName(string fullPath)
public static string FixInvalidFullFilePath(string fullPath, string replacement = " ")
public static bool IsFileNameInvalid(this string name)
public static string FixInvalidFileName(string fileName, string replacement = " ")
public static bool FileNameExists(this string fileName, IEnumerable<string> fileNames)
public static Exception? ShowInExplorer(this string? filePath)
public static Exception? OpenPathInSystemDefault(this string? filePath)
public static async Task<string> CalculateFileMD5Async(string filePath, int bufferSize = 4096)
public static string CalculateFileMD5(string filePath, int bufferSize = 4096)
public static string? CalculateFileMD5(byte[]? bytes)
public static async Task<string?> CalculateFileMD5Async(byte[]? bytes)
public static List<string> ReadAllLines(string filePath, Encoding? encoding = null)
public static FileInfo? SafeGetFileInfo(this string? filePath, Action<Exception>? handleException = null)
public static bool AreFilePathsEqual(this string? path1, string? path2)
public static bool? AreFilePathsEqualSafe(this string? path1, string? path2)
public static string NormalizePath(this string? path)
public static string NormalizePathSafe(this string? path)
```
### Helpers/DirectoryHelper.cs
命名空间:`MAX.Common.Helpers`
```csharp
public static class DirectoryHelper
public static bool IsRootDirectory(string path)
public static bool IsWindowsRootDirectory(string path)
public static bool IsUnixRootDirectory(string path)
public static DirectoryInfo CreateDirectory(string? dir, bool checkFileParent = false)
public static Exception? TryCreateDirectory(string? dir, bool checkFileParent = false)
public static bool HasWriteAccessToFolder(string folderPath)
public static void CopyDirectory( string sourceDir, string destinationDir, bool recursive = true, Predicate<FileInfo>? handleFile = null )
public static string GetUniqueFolderName(string folderPath, bool reuseEmptyDirectory = false)
public static bool IsDirectoryEmpty(this string folderPath)
public static bool IsDirectoryEmptyOrNotExist(this string folderPath)
public static string AppendDirectorySeparatorChar(string path)
public static string GetRelativePath(string relativeTo, string path)
```
### Helpers/NumberHelper.Clamp.cs
命名空间:`MAX.Common.Helpers`
```csharp
public static partial class NumberHelper
public static T ClampGeneric<T>(this T value, T min, T max) where T : IComparable<T>
public static float Clamp(this float input, float min, float max)
public static double Clamp(this double input, double min, double max)
public static decimal Clamp(this decimal input, decimal min, decimal max)
public static int Clamp(this int input, int min, int max)
public static long Clamp(this long input, long min, long max)
public static short Clamp(this short input, short min, short max)
public static sbyte Clamp(this sbyte input, sbyte min, sbyte max)
public static uint Clamp(this uint input, uint min, uint max)
public static ulong Clamp(this ulong input, ulong min, ulong max)
public static ushort Clamp(this ushort input, ushort min, ushort max)
public static byte Clamp(this byte input, byte min, byte max)
```
### Utilities/PathValidator.cs
命名空间:`MAX.Common.Utilities`
```csharp
public static partial class PathValidator
public static bool IsFolderPathValidAndSafe([NotNullWhen(true)] string? path, bool allowRelativePath)
```
### Utilities/FolderNameValidator.cs
命名空间:`MAX.Common.Utilities`
```csharp
public static class FolderNameValidator
public enum ValidationResult
public static IReadOnlyCollection<string> ReservedNamesInWindows
public static bool IsValidFolderName([NotNullWhen(true)] string? folderName)
public static ValidationResult Validate(string? folderName)
public static string GetErrorMessage(ValidationResult result)
```
## 事件与运行控制
### Events/TypedEvent.cs
命名空间:`MAX.Common.Events`
```csharp
public class TypedEvent<TSender, TArgs>
public event TypedEventHandler<TSender, TArgs>? Event
public void Raise(TSender sender, TArgs args)
public class TypedEvent<TArgs>
public event Action<TArgs>? Event
public void Raise(TArgs args)
public class TypedEvent
public event Action? Event
public void Raise()
```
### Events/AsyncEvent.cs
命名空间:`MAX.Common.Events`
```csharp
public class AsyncEvent<TEventArgs> where TEventArgs : EventArgs
public static AsyncEvent<TEventArgs> operator +(AsyncEvent<TEventArgs>? e, Func<object, TEventArgs, Task>? callback)
public static AsyncEvent<TEventArgs>? operator -(AsyncEvent<TEventArgs>? e, Func<object, TEventArgs, Task> callback)
public async Task InvokeAsync(object sender, TEventArgs eventArgs)
```
### Utilities/RunLimiter.cs
命名空间:`MAX.Common.Utilities`
```csharp
public class RunLimiter(Action action, int maxLimit = 1)
public bool Run()
public bool CanRun()
```
### Utilities/DisposeAction.cs
命名空间:`MAX.Common.Utilities`
```csharp
public class DisposeAction(Action action) : IDisposable
public Action Action
public void Dispose()
```
### Utilities/CompensatingTimer.cs
命名空间:`MAX.Common.Utilities`
```csharp
public class CompensatingTimer : IDisposable
public event Action<Exception>? OnTickException
public CompensatingTimer(TimeSpan interval, Action tickCallback)
public void Start()
public void Stop()
public void Dispose()
```
### Helpers/SerializationHelper.cs
命名空间:`MAX.Common.Helpers`
```csharp
public static class SerializationHelper
public static T? TryGetValue<T>(this SerializationInfo info, string name, T? defaultWhenException = default)
```
@@ -0,0 +1,26 @@
# 功能索引
参考版本:MAX.Common 1.4.17。以下命名空间均以 `MAX.Common` 为根。按任务读取对应 API 声明,避免把相似名称当作相同语义。
| 需求 | 命名空间 / 入口 | 选择提示 |
| --- | --- | --- |
| 同步、异步 ICommand | Commands:MethodCommand、AsyncMethodCommand,均有泛型版本 | 不依赖 WPF 控件;泛型参数有可空约束 |
| 属性变化通知 | Models:BindModelBase、BindableBaseEx、BindObject | 依调用方需要选字段模型或属性包,不强行更换现有 MVVM 框架 |
| 枚举描述与展示元数据 | Models.EnumItem、Attributes.EnumDisplayAttribute、TooltipAttribute;Helpers.EnumHelper;Utilities.EnumDisplayManagerBase | 先看元数据读取方式;WPF 显示由 WPF 包处理 |
| 双向映射、列表字典 | Data.Collections:BidirectionalDictionary、ListDictionary | 双向字典提供 TryGetKey / TryGetValue;重复值等规则核对当前实现 |
| 循环、反转、投影与区间读取 | Data.Lists:CyclicReadOnlyList、ReversedReadonlyList、SelectorReadonlyList、RangeDataReadList、ExtendReadonlyList、ObjectReadonlyList | 只读接口不等于独立不可变副本,检查是否持有源集合与索引边界 |
| 二维数据与表格 | Data.Arrays.ReadonlyMatrix、Data.Tables.ListTable;Interfaces.IReadonlyMatrix、IDataTable;Helpers.CollectionHelper 的 Matrix 部分 | 确认行列顺序和维度,避免与 UI DataGrid 混淆 |
| 数值与精度 | Helpers.NumberHelper;Data.PrecisionBuilder;Models.Range、Helpers.RangeHelper | 检查上下限、转换和舍入行为,勿猜测精度单位 |
| 二维向量 | Data:Vector2、Vector2F、Vector2Int、Vector2Mutable;Interfaces.IVector2 | 按数值类型与可变性选择;WPF Point 转换在 WPF 包 |
| 集合操作 | Helpers.CollectionHelper 的 Array / Collection / Enumerable / List 部分、DictionaryHelper;Models.ObservableHashSet | 按具体签名区分原地修改和返回新集合 |
| 文件、目录、大小显示 | Helpers.FileHelper、DirectoryHelper;Comparers.FilePathStringComparer | `long.FileSizeToString()` 自动显示大小;删除、复制等操作先确认覆盖和异常语义 |
| 路径、文件夹名校验 | Utilities.PathValidator、FolderNameValidator | 文件夹名单段校验和完整路径校验分开使用;不提供目录访问授权 |
| 字符串、日期、随机数、GUID | Helpers.StringHelper、DateTimeHelper、RandomHelper、GuidHelper | 沿用现有文化、格式和业务随机性要求 |
| 类型、反射、属性与赋值 | Helpers.TypeHelper、ReflectionHelper、AttributeHelper、StructHelper;Utilities.AssignUtility;Attributes.AssignableAttribute;Interfaces.IAssignable | 先查反射范围及标记规则,不把赋值当作任意对象深克隆 |
| 强类型与异步事件 | Events.TypedEvent、AsyncEvent;Events.Args;根命名空间 TypedEventHandler | 区分同步通知和串行 Task 回调,处理订阅生命周期 |
| 次数限制、清理与定时 | Utilities.RunLimiter、DisposeAction、CompensatingTimer | RunLimiter 是总次数;DisposeAction 可用于 using 作用域清理;定时器按实际 API 管理生命周期 |
| 编码与摘要 | Cryptography.Base64Helper、UriHelper、MD5Helper | 用于已有编码和摘要需求;不将编码当作加密 |
| 进程与运行环境 | Helpers.ProcessHelper、ArchitectureChecker、GCHelper | netstandard 目标不保证具体系统 API 跨平台可用 |
| 版本与颜色数据 | Models.VersionStruct、SimpleColor | WPF Color / Brush 转换需 WPF 包 |
其他支撑类型可在安装包 XML 文档或源码按上述命名空间搜索。这里是能力路由,不承诺未列明的签名与行为。