diff --git a/website/docs/agent-skills/_category_.json b/website/docs/agent-skills/_category_.json new file mode 100644 index 0000000..6e1b103 --- /dev/null +++ b/website/docs/agent-skills/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Agent Skills", + "position": 4, + "link": { + "type": "generated-index", + "description": "Claude Code Agent Skills 使用教程 — 帮助 .NET 开发者在 5 分钟内将 GeneralUpdate 自动更新系统集成到任意 .NET 应用中。覆盖 50+ 真实 Issue 发现的已知问题，提供即用型代码生成 + 深度故障排查。" + } +} diff --git a/website/docs/agent-skills/generalupdate-advanced.md b/website/docs/agent-skills/generalupdate-advanced.md new file mode 100644 index 0000000..7c106d3 --- /dev/null +++ b/website/docs/agent-skills/generalupdate-advanced.md @@ -0,0 +1,258 @@ +--- +sidebar_position: 5 +sidebar_label: 🔧 高级定制 +title: 🔧 generalupdate-advanced — 高级定制参考 +--- + +# 🔧 GeneralUpdate 高级定制参考 + +涵盖扩展点架构、Pipeline 管道、差分引擎、Bowl 崩溃守护、事件系统、文件系统工具等。 + +> ⚠️ **API 版本说明**：本指南基于 **NuGet v10.4.6 稳定版**。 +> +> 以下功能在稳定版中**不存在**（但在开发分支 v10.5.0-beta.2 中已有）： +> - `IUpdateHooks` 生命周期钩子 +> - `IProcessInfoProvider` IPC 替换接口 +> - `SilentPollOrchestrator` 静默轮询器 +> - `Option` 可编程配置系统（v10.4.6 仅使用 `Configinfo` 属性） +> - `ISslValidationPolicy` SSL 策略接口 +> +> 各功能的可用性在文中已标注。 + +--- + +## 1. Pipeline 管道系统（v10.4.6 可用） + +GeneralUpdate 使用 Pipeline 管道模式处理更新包的校验、解压、补丁应用。 + +### PipelineBuilder API + +```csharp +using GeneralUpdate.Common.Internal.Pipeline; +using GeneralUpdate.Common.Internal.Strategy; + +// 创建管道上下文 +var context = new PipelineContext(); +context.Add("ZipFilePath", @"C:\temp\update.zip"); +context.Add("Hash", "sha256-hex-value"); +context.Add("Format", 0); // 0=Zip +context.Add("Encoding", System.Text.Encoding.UTF8); +context.Add("SourcePath", @"C:\Program Files\MyApp"); +context.Add("PatchEnabled", true); + +// 构建并执行管道 +await new PipelineBuilder(context) + .UseMiddleware() // 哈希校验 + .UseMiddleware() // 解压 + .UseMiddleware() // 差分补丁（需安装 Differential 包） + .Build(); +``` + +| 中间件 | 类名 | 命名空间 | 功能 | +|--------|------|---------|------| +| 哈希校验 | `HashMiddleware` | `GeneralUpdate.Core.Pipeline` | SHA256 完整性校验 | +| 解压 | `CompressMiddleware` | `GeneralUpdate.Core.Pipeline` | 解压 ZIP 包 | +| 差分补丁 | `PatchMiddleware` | `GeneralUpdate.Core.Pipeline` | 应用 BSDIFF/HDiffPatch 补丁 | +| 驱动更新 | `DrivelutionMiddleware` | `GeneralUpdate.Core.Pipeline` | Windows 驱动安装 | + +--- + +## 2. 策略系统（v10.4.6 可用） + +GeneralUpdate 内置三种平台策略，通过 `AbstractStrategy` 模板方法模式实现： + +| 策略 | 类名 | 平台 | +|------|------|------| +| Windows | `WindowsStrategy` | Windows | +| Linux | `LinuxStrategy` | Linux | +| OSS | `OSSStrategy` | 跨平台（对象存储） | + +> ⚠️ 稳定版**不支持**通过 `bootstrap.Strategy()` 注入自定义策略。 +> 自定义策略需要继承 `AbstractStrategy` 并直接调用。 + +--- + +## 3. Bowl 崩溃守护（v10.4.6 存在但功能有限） + +Bowl 是一个崩溃监控组件，通过 `MonitorParameter` 配置。 + +> ⚠️ **注意**：v10.4.6 的 Bowl 仅提供基础类型定义，`Bowl` 类没有公开的 `LaunchAsync` 方法。 +> 完整功能在开发分支（v10.5.0-beta.2）中。 + +### MonitorParameter 配置 + +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; + +var param = new MonitorParameter +{ + ProcessNameOrId = "MyApp.exe", + DumpFileName = "v1.0.0.0_fail.dmp", + FailFileName = "v1.0.0.0_fail.json", + TargetPath = @"C:\Program Files\MyApp", + FailDirectory = @"C:\Program Files\MyApp\fail", + BackupDirectory = @"C:\Program Files\MyApp\backup", + WorkModel = "Upgrade", +}; + +// Bowl 实例（v10.4.6 无公开 LaunchAsync，此为占位） +var bowl = new Bowl(); +``` + +完整 Bowl 崩溃守护功能请关注 GeneralUpdate 后续版本。 + +### Bowl 引用规则 + +Bowl 引用规则：只用 `GeneralUpdate.Bowl`（传递依赖 Core，两者不能同时引用）。 + +--- + +## 4. EventManager 事件系统（v10.4.6 可用） + +EventManager 是一个全局单例，提供事件的发布和订阅： + +```csharp +using GeneralUpdate.Common.Internal.Event; + +// 添加监听 +EventManager.Instance.AddListener((object? sender, UpdateInfoEventArgs e) => +{ + // 处理版本发现事件 +}); + +// 手动分发事件 +EventManager.Instance.Dispatch(this, new ExceptionEventArgs(ex, "自定义错误")); + +// 清空所有监听 +EventManager.Instance.Clear(); + +// 释放 +EventManager.Instance.Dispose(); +``` + +> ⚠️ EventManager 是全局单例，`Dispose()` 后 `Instance` 仍然可访问（代码审计发现）。 + +--- + +## 5. 文件系统工具（v10.4.6 可用） + +### BlackList（黑名单） + +`Configinfo` 支持通过以下属性排除文件： + +```csharp +var config = new Configinfo +{ + // ... + BlackFiles = new List { "*.log", "*.tmp" }, + BlackFormats = new List { ".pdb", ".vshost.exe" }, + SkipDirectorys = new List { "logs", "cache", "temp" }, +}; +``` + +### FileTree（文件树对比） + +```csharp +using GeneralUpdate.Common.FileBasic; + +var tree = new FileTree(); +var snapshot = tree.CreateSnapshot(@"C:\Program Files\MyApp"); +// 或从 StorageManager 获取比较结果 +``` + +--- + +## 6. 差分引擎（v10.4.6 可用，需安装 Differential 包） + +安装 `GeneralUpdate.Differential` 包后可用： + +```csharp +// DifferentialCore 提供核心差分能力 +using GeneralUpdate.Differential; + +// 清理模式（服务端）：对比新旧版本生成补丁 +await DifferentialCore.CleanAsync(srcDir, tgtDir, patchDir); + +// 脏模式（客户端）：应用补丁 +await DifferentialCore.DirtyAsync(installDir, patchDir); +``` + +自定义匹配器（v10.4.6 可用）： + +```csharp +using GeneralUpdate.Differential.Matchers; + +// 自定义清理匹配器 +var cleanMatcher = new DefaultCleanMatcher(); // 或实现 ICleanMatcher +var dirtyMatcher = new DefaultDirtyMatcher(); // 或实现 IDirtyMatcher +``` + +--- + +## 7. AOT / NativeAOT 兼容性 + +GeneralUpdate.Core v10.4.6 支持 .NET Native AOT： + +```xml + + true + true + +``` + +JSON 序列化上下文（减少 AOT 大小）： + +```csharp +using GeneralUpdate.Common.Internal.JsonContext; + +// 使用内置的 JsonSerializerContext +// VersionRespJsonContext, PacketJsonContext, ProcessInfoJsonContext 等 +``` + +--- + +## 8. Drivelution（Windows 驱动更新） + +`GeneralUpdate.Drivelution` 包提供 Windows 驱动管理： + +```csharp +using GeneralUpdate.Drivelution; + +// 扫描驱动目录 +var allDrivers = GeneralDrivelution.ScanDirectory(driverDir); + +// 验证驱动 +var isValid = GeneralDrivelution.ValidateDriver(driverPath); + +// 安装驱动（DIFx → SetupAPI → PnPUtil 级联） +var result = GeneralDrivelution.InstallDriver(driverPath); +``` + +--- + +## 内容索引 + +| 主题 | 可用性 | 参考 | +|------|--------|------| +| Pipeline 管道 | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Pipeline` | +| 策略系统 | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Strategy` | +| FileTree | ✅ v10.4.6 | `GeneralUpdate.Common.FileBasic` | +| BlackList | ✅ v10.4.6 | `Configinfo.BlackFiles` 等属性 | +| 差分引擎 | ✅ 需 `GeneralUpdate.Differential` | `DifferentialCore` | +| AOT | ✅ v10.4.6 | `JsonSerializerContext` 子类 | +| EventManager | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Event` | +| Bowl 崩溃守护 | ⚠️ 基础类型 | `GeneralUpdate.Bowl.Bowl` | +| IUpdateHooks | ❌ v10.4.6 不支持 | 开发分支 v10.5.0-beta.2 中 | +| 自定义 Strategy 注入 | ❌ v10.4.6 不支持 | 开发分支 v10.5.0-beta.2 中 | +| IPC 替换接口 | ❌ v10.4.6 不支持 | 开发分支 v10.5.0-beta.2 中 | +| SilentPollOrchestrator | ❌ v10.4.6 不支持 | 开发分支 v10.5.0-beta.2 中 | +| Option 系统 | ❌ v10.4.6 不支持 | 仅 Configinfo 属性 | + +--- + +## 相关技能 + +- [🚀 generalupdate-init — Bootstrap 配置](./generalupdate-init.md) +- [⚙️ generalupdate-strategy — 更新策略选择](./generalupdate-strategy.md) +- [🩺 generalupdate-troubleshoot — 问题诊断](./generalupdate-troubleshoot.md) diff --git a/website/docs/agent-skills/generalupdate-init.md b/website/docs/agent-skills/generalupdate-init.md new file mode 100644 index 0000000..3071ddd --- /dev/null +++ b/website/docs/agent-skills/generalupdate-init.md @@ -0,0 +1,269 @@ +--- +sidebar_position: 2 +sidebar_label: 🚀 集成指南 +title: 🚀 generalupdate-init — 快速集成指南 +--- + +# 🚀 GeneralUpdate 集成完全指南 + +帮助开发者在任意 .NET 应用中集成 GeneralUpdate 自动更新。从零开始，覆盖所有配置方式、部署场景和生产环境考量。 + +> ⚠️ **针对 NuGet v10.4.6 稳定版**。开发分支（v10.5.0-beta.2）有不同 API。 + +--- + +## 工作流程 + +``` +1. 探测项目状态 + ├── 检查 .csproj → 目标框架、UI 类型 + └── 检查现有配置 → 已安装 NuGet？已有 manifest？ + +2. 选择集成模式 + ├── [Minimal] （new Configinfo + SetConfig + LaunchAsync）— 推荐新用户 + ├── [Standard]（Configinfo + 事件监听）— 需要精细控制 + └── [Scaffold]（完整双项目结构）— 从零开始的团队项目 + +3. 生成输出 + ├── NuGet 安装命令 + ├── Bootstrap 配置代码 + ├── manifest.json 模板 + └── 部署检查清单 + +4. 后续引导 + ├── 需要 UI → generalupdate-ui + ├── 选择策略 → generalupdate-strategy + └── 遇到问题 → generalupdate-troubleshoot +``` + +--- + +## 核心概念：4 大更新场景 + +GeneralUpdate 根据服务端返回的包类型决定更新策略： + +| 场景 | 行为 | +|------|------| +| **None** | 无需更新，直接启动主程序 | +| **UpgradeOnly** | 只更新升级程序自身：Client 原地解压 Upgrade 包 | +| **MainOnly** | 只更新主程序：Client → IPC → 启动 Upgrade 进程 | +| **Both** | 两者都更新 | + +### 双进程架构 + +``` +App.exe (Client) 负责: + ├── 版本验证（HTTP 请求服务端） + ├── 下载所有更新包 + ├── IPC 写入（加密文件传递参数给 Upgrade） + └── 启动 Upgrade.exe 然后自己退出 + +Upgrade.exe (Upgrade 进程) 负责: + ├── 读取 IPC 文件 + ├── 应用更新（解压/补丁/替换文件） + └── 启动主程序然后自己退出 +``` + +--- + +## Configinfo 配置详解 + +### Configinfo 完整属性 + +```csharp +var config = new Configinfo +{ + // === 必需 === + UpdateUrl = "https://your-server.com/Upgrade/Verification", + AppSecretKey = "your-secret-key", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = ".", + + // === 可选 === + ReportUrl = "https://your-server.com/Upgrade/Report", + UpdateLogUrl = "https://your-server.com/Upgrade/Log", + UpgradeClientVersion = "1.0.0.0", + + // === 安全认证 === + Scheme = "Bearer", // HTTP 认证方案 + Token = "your-token", // HTTP 认证令牌 + + // === 黑名单（备份/复制时排除）=== + BlackFiles = new List { "*.log", "*.tmp" }, + BlackFormats = new List { ".pdb" }, + SkipDirectorys = new List { "logs", "cache" }, +}; +``` + +### 应用角色（AppType） + +`AppType` 是一个 class，包含两个静态字段： + +| 字段 | 值 | 说明 | +|------|-----|------| +| `AppType.ClientApp` | 1 | 标准客户端（主程序） | +| `AppType.UpgradeApp` | 2 | 标准升级程序 | + +> ⚠️ v10.4.6 不支持 OssClient（值 3-4），这些在开发分支中。 + +### 事件监听器完整清单 + +```csharp +// 全部 6 个事件 +.AddListenerUpdateInfo((_, e) => { + /* 版本验证结果（e.Info?.Body 含 VersionInfo 列表） */ +}) +.AddListenerMultiDownloadStatistics((_, e) => { + /* 批量下载进度（e.ProgressPercentage, e.Speed, e.Remaining） */ +}) +.AddListenerMultiDownloadCompleted((_, e) => { + /* 每版本下载完成（e.Version, e.IsComplated） */ +}) +.AddListenerMultiDownloadError((_, e) => { + /* 下载错误（e.Exception, e.Version） */ +}) +.AddListenerMultiAllDownloadCompleted((_, e) => { + /* 全部下载完成（e.IsAllDownloadCompleted, e.FailedVersions） */ +}) +.AddListenerException((_, e) => { + /* 异常（e.Message, e.Exception） */ +}) +``` + +--- + +## 集成方式的完整代码 + +### 方式 A：Minimal — 使用 Configinfo + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Shared.Object; + +var config = new Configinfo +{ + UpdateUrl = "https://your-server.com/api", + AppSecretKey = "your-32-char-secret-key-here!", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = "." +}; + +await new GeneralUpdateBootstrap() + .SetConfig(config) + .LaunchAsync(); +``` + +### 方式 B：Standard — Configinfo + 事件 + 监听 + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Common.Download; + +var config = new Configinfo +{ + UpdateUrl = "https://your-server.com/Upgrade/Verification", + AppSecretKey = "your-secret-key", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = AppDomain.CurrentDomain.BaseDirectory, + ReportUrl = "https://your-server.com/Upgrade/Report", +}; + +await new GeneralUpdateBootstrap() + .SetConfig(config) + .AddListenerUpdateInfo((_, e) => + { + Console.WriteLine($"发现 {e.Info?.Body?.Count ?? 0} 个版本"); + }) + .AddListenerMultiDownloadStatistics((_, e) => + { + Console.WriteLine($"进度: {e.ProgressPercentage}% | {e.Speed}"); + }) + .AddListenerMultiDownloadCompleted((_, e) => + { + Console.WriteLine($"版本 {e.Version} 下载完成"); + }) + .AddListenerMultiAllDownloadCompleted((_, e) => + { + Console.WriteLine($"全部完成 (IsAllDownloadCompleted={e.IsAllDownloadCompleted})"); + }) + .AddListenerMultiDownloadError((_, e) => + { + Console.WriteLine($"下载失败: 版本 {e.Version} — {e.Exception?.Message}"); + }) + .AddListenerException((_, e) => + { + Console.WriteLine($"异常: {e.Message}"); + }) + .LaunchAsync(); +``` + +### Upgrade 进程配置 + +```csharp +using GeneralUpdate.Core; + +// Upgrade 模式从 IPC 文件读取配置，无需 SetConfig +await new GeneralUpdateBootstrap() + .AddListenerException((_, e) => + Console.WriteLine($"错误: {e.Message}")) + .LaunchAsync(); +``` + +--- + +## 生产环境部署检查清单 + +### 发布目录结构 + +``` +publish/ +├── MyApp.exe ← MainAppName（主程序） +├── generalupdate.manifest.json +└── update/ + └── UpgradeApp.exe ← 升级程序，必须随首个版本发布 +``` + +### 双进程验证 + +| 检查项 | 说明 | +|--------|------| +| UpgradeApp.exe 存在于发布目录 | 首个版本就必须有 | +| Client 和 Upgrade 使用相同 AppSecretKey | IPC 加密通信依赖此 Key | +| Client 和 Upgrade 使用相同 NuGet 版本号 | 版本不一致导致 "Method not found" | +| Upgrade 进程不需要网络 | 所有数据由 Client 预下载 | + +--- + +## ⚠️ 已知问题 + +### NuGet 类型冲突 + +`GeneralUpdate.Core` 和 `GeneralUpdate.Bowl` **不能同时引用**（CS0433 类型冲突）。 + +请根据需求选择： +- 使用 Core：`dotnet add package GeneralUpdate.Core` +- 使用 Bowl：**只引用** `GeneralUpdate.Bowl`（它传递依赖 Core 所有功能） +- 差分类型已内嵌在 Core，**无需额外** `GeneralUpdate.Differential` 包 + +### 稳定版功能限制 + +v10.4.6 无 `IUpdateHooks`、无可编程 `Option`、无静默轮询器。这些功能在开发分支（v10.5.0-beta.2）中可用。 + +--- + +## 相关技能 + +- [🎨 generalupdate-ui — UI 框架自动检测 + 更新窗口代码生成](./generalupdate-ui.md) +- [⚙️ generalupdate-strategy — 6 种更新策略选择与配置](./generalupdate-strategy.md) +- [🔧 generalupdate-advanced — 高级定制](./generalupdate-advanced.md) +- [🩺 generalupdate-troubleshoot — 已知问题诊断](./generalupdate-troubleshoot.md) diff --git a/website/docs/agent-skills/generalupdate-strategy.md b/website/docs/agent-skills/generalupdate-strategy.md new file mode 100644 index 0000000..dc1fd83 --- /dev/null +++ b/website/docs/agent-skills/generalupdate-strategy.md @@ -0,0 +1,106 @@ +--- +sidebar_position: 4 +sidebar_label: ⚙️ 策略指南 +title: ⚙️ generalupdate-strategy — 更新策略指南 +--- + +# ⚙️ GeneralUpdate 更新策略完全指南 + +> ⚠️ **针对 NuGet v10.4.6 稳定版**。该版本使用 `Configinfo` 配置，无可编程 `Option` 系统。 + +--- + +## 策略决策树 + +``` +你的应用有后端服务吗？ +├── 有 +│ ├── 需要服务端主动推送更新？ → SignalR 推送 +│ └── 否 → 标准客户端-服务端 +│ +└── 没有（只有对象存储 S3/MinIO/OSS） + └── OSS 标准 +``` + +--- + +## 6 种策略详细对比 + +| 策略 | 服务端 | 说明 | +|------|:------:|------| +| **① 标准客户端-服务端** | ✅ GeneralSpacestation | 有后端的中大型应用（推荐入门） | +| **② OSS 对象存储** | ❌ 仅 S3/MinIO | 无后端，最低成本 | +| **③ 静默更新** | ✅ 同①或② | 后台无声升级 | +| **④ 差分更新** | ✅ 需差分构建 | 增量补丁节省带宽 | +| **⑤ 跨版本 CVP** | ✅ 需 CVP 构建 | 跳过中间版本直跳 | +| **⑥ SignalR 推送** | ✅ 需 SignalR Hub | 服务端主动推送 | + +--- + +## 集成代码 + +所有策略使用相同的 `Configinfo` 配置模式： + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Shared.Object; + +var config = new Configinfo +{ + UpdateUrl = "https://your-server.com/api", + AppSecretKey = "your-secret-key", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = ".", +}; + +await new GeneralUpdateBootstrap() + .SetConfig(config) + .AddListener*(...) + .LaunchAsync(); +``` + +具体示例参见 `examples/` 目录下的策略文件。 + +--- + +## 混合组合策略 + +| 组合 | 典型场景 | +|------|----------| +| **OSS + Silent** | 游戏启动器 / kiosk — 从 CDN 拉取，无需用户交互 | +| **Standard + Differential** | 首次全量下载，后续差分补丁 | +| **CVP + Differential** | 跨版本跳跃 + 单一差分补丁 | +| **Standard + Push** | 后端推送通知，用户点击下载 | + +--- + +## 平台特定差异 + +| 平台 | 特性 | +|------|------| +| **Windows** | 完整功能。使用 **Bowl** 崩溃守护（在未处理异常时重启应用总线）。完全文件系统访问。 | +| **Linux / macOS** | ⚠️ v10.4.6 无 `UnixPermissionHooks`，需手动 `chmod +x`。目标框架建议 .NET 8+。 | + +--- + +## 已知问题 + +| # | 问题 | 规避方案 | +|---|------|---------| +| 1 | OSS 模式不区分 Main/Upgrade 更新 | 接受此行为 | +| 2 | UpgradeApp.exe 必须放在 update/ 子目录 | 按规范部署 | +| 3 | NuGet 版本冲突导致 "Method not found" | Client 和 Upgrade 使用相同版本号 | +| 4 | 无限升级循环 | 确保 manifest.json 版本号正确 | +| 5 | SignalR HubConnection Dispose 后重连崩溃 | Dispose 时将连接置 null | + +--- + +## 相关技能 + +- [🚀 generalupdate-init — 如果还未配置 Bootstrap](./generalupdate-init.md) +- [🎨 generalupdate-ui — 如果需要更新界面](./generalupdate-ui.md) +- [🩺 generalupdate-troubleshoot — 如果遇到问题](./generalupdate-troubleshoot.md) +- [🔧 generalupdate-advanced — 高级定制](./generalupdate-advanced.md) diff --git a/website/docs/agent-skills/generalupdate-troubleshoot.md b/website/docs/agent-skills/generalupdate-troubleshoot.md new file mode 100644 index 0000000..fd8c7a0 --- /dev/null +++ b/website/docs/agent-skills/generalupdate-troubleshoot.md @@ -0,0 +1,123 @@ +--- +sidebar_position: 6 +sidebar_label: 🩺 故障排查 +title: 🩺 generalupdate-troubleshoot — 故障排查 +--- + +# 🩺 GeneralUpdate 故障排查 + +综合性诊断系统 — 覆盖 50+ 已知问题，均可追溯到 GitHub/Gitee Issue 或代码审计发现。 + +## 工作流程 + +``` +1. 症状收集 + ├── 用户描述的症状是什么？ + ├── 错误信息/堆栈是什么？ + ├── GeneralUpdate 版本号？ + ├── 平台（Windows/Linux/macOS）？ + └── 更新策略（标准/OSS/静默）？ + +2. 症状匹配 → 查找 reference.md + ├── 找到匹配的 Q/C/H/M/L → 给出根因 + 修复 + 代码 + └── 未找到匹配 → 执行通用诊断流程（6步骤） + +3. 提供修复 + ├── 具体的代码修改、配置调整、版本升级建议 + └── 预防措施（如何避免再发生） + +4. 验证 + └── 确认修复后问题解决 +``` + +## 症状分级 + +reference.md 中的问题按严重度分级： + +| 级别 | 颜色 | 含义 | 数量 | +|:----:|:----:|------|:----:| +| C | 🔴 **致命** | 阻断性故障、数据损坏、安全漏洞 | 8 | +| H | 🟠 **高** | 场景阻断、功能失效、需要升级 | 11 | +| M | 🟡 **中** | 功能异常、需要配置调整 | 20 | +| L | 🔵 **低** | 代码气味、边缘情况、已知行为 | 12 | + +--- + +## C 级（Critical）— 阻塞升级 + +| 问题 | 原因 | 排查/解决 | +|------|------|-----------| +| **升级没启动** | `LaunchAsync()` 未调用 / UpgradeApp.exe 未部署 | 确认 `Bootstrap.LaunchAsync()` 在 `Main()` 中调用 | +| **Method not found** | Client 和 Upgrade NuGet 版本不一致 | 统一 NuGet 版本, 清理 bin/obj 后重新生成 | +| **路径超长 (>260)** | Windows 路径限制 | 缩短安装路径 | +| **IPC 暴露** | IPC 加密密钥硬编码 | 使用强 AppSecretKey; 更新到 v10.4.6+ | +| **跨租户泄露** | 服务端多租户隔离缺失 | 每个租户独立 ProductId + AppSecretKey | +| **ZIP 遍历写入** | 恶意 ZIP 含 `../` 路径 | v10.4.6+ 已修复 | +| **BSDIFF 整数溢出** | 大文件差分补丁计算溢出 | 使用 HDiffPatch 算法 | +| **静默不生效** | 进程退出时未触发 | 确保正确调用 Close() 或 Dispose() | + +## H 级（High）— 严重但不阻塞启动 + +| 问题 | 原因 | 排查/解决 | +|------|------|-----------| +| **无限循环更新** | manifest.json 版本号未回写 | 更新到 v10.4.6+（已修复 WriteBack） | +| **OSS 无更新** | Bucket 配置错误 / versions.json 格式不对 | curl 测试 OSS URL 是否可下载 | +| **文件占用** | 目标文件被占用 | 关闭主进程后更新; 排除杀软扫描目录 | +| **SignalR 推送无响应** | 连接断开或认证失败 | 检查 SignalR Hub 状态和 Token 配置 | +| **Bowl 不守护** | 进程名配置错误 | 确认 ProcessNameOrId 与实际进程名一致 | +| **差分更新失败** | 基准文件不匹配 | 校验原始文件哈希匹配 | +| **下载进度不动** | IDownloadService 未正确绑定 | 确认桥接实现是否正确 | +| **跨版本跳跃失败** | 中间版本包缺失 | 确保服务端保留了所有版本的补丁 | + +## M 级（Medium）— 功能降级 + +| 问题 | 原因 | 排查/解决 | +|------|------|-----------| +| **AOT 编译失败** | 反射代码未适配 NativeAOT | 添加 `[DynamicDependency]` 属性 | +| **SignalR 重连慢** | RetryDelay 配置过长 | 调整重连参数 | +| **日志不输出** | 日志路径权限不足 | 检查 %TEMP%/GeneralUpdate/logs/ 权限 | +| **多租户配置错误** | ProductId 冲突 | 确保每个租户唯一 ProductId | +| **黑名单不生效** | 格式配置错误 | 确认文件名和扩展名格式正确 | + +## L 级（Low）— 非关键 + +| 问题 | 原因 | 排查/解决 | +|------|------|-----------| +| **分发包过大** | 未使用差分 | 差分已内嵌在 Core，启用 `PatchEnabled` 即可 | +| **首次更新慢** | CDN 冷启动 | 预热 CDN | +| **更新后配置丢失** | 黑名单未包含配置目录 | 确认 `SkipDirectorys` 包含配置文件夹 | + +--- + +## 通用诊断流程（6 步） + +当问题无法直接匹配到已知症状时，执行以下 6 步排查： + +1. **版本一致性检查** — Client 和 Upgrade 的 NuGet 版本是否一致？ +2. **manifest.json 验证** — 文件是否存在？字段值是否正确？ +3. **UpgradeApp 存在性** — UpgradeApp.exe 是否在预期目录？ +4. **网络可访问性** — UpdateUrl 能否用 curl 访问？ +5. **日志分析** — 查看 `%TEMP%/GeneralUpdate/logs/` 下的日志文件 +6. **最小重现** — 从 Minimal 集成开始，逐步增加复杂度 + +## 日志文件位置 + +| 平台 | 默认路径 | +|------|----------| +| Windows | `%TEMP%/GeneralUpdate/logs/` | +| Linux | `/tmp/GeneralUpdate/logs/` | + +## 安全注意事项 + +- AppSecretKey 管理 — 硬编码在客户端是最后手段; 优先从启动参数或环境变量注入 +- 定期轮换 IPC 加密密钥 +- 生产环境禁用调试日志 + +--- + +## 相关技能 + +- [🚀 generalupdate-init — Bootstrap 配置](./generalupdate-init.md) +- [🎨 generalupdate-ui — 更新界面诊断](./generalupdate-ui.md) +- [⚙️ generalupdate-strategy — 策略相关故障](./generalupdate-strategy.md) +- [🔧 generalupdate-advanced — 高级功能故障](./generalupdate-advanced.md) diff --git a/website/docs/agent-skills/generalupdate-ui.md b/website/docs/agent-skills/generalupdate-ui.md new file mode 100644 index 0000000..bf5479b --- /dev/null +++ b/website/docs/agent-skills/generalupdate-ui.md @@ -0,0 +1,135 @@ +--- +sidebar_position: 3 +sidebar_label: 🎨 界面生成 +title: 🎨 generalupdate-ui — 更新界面生成 +--- + +# 🎨 GeneralUpdate 更新界面生成 — 全状态覆盖 + +自动检测开发者的 UI 框架类型，生成带真实 GeneralUpdate.Core 事件绑定的完整更新窗口代码。 + +> ⚠️ 针对 NuGet v10.4.6 稳定版。`RealDownloadService.cs` 为抽象桥接模板，需手动适配。 + +--- + +## UI 状态机（所有模板覆盖以下状态） + +``` + ┌─────────────┐ + │ Idle │ ← 初始状态 + └──────┬──────┘ + │ 自动/手动触发 + ▼ + ┌─────────────┐ + ┌─────│ Checking │ ← "正在检查更新..." + │ └──────┬──────┘ + │ │ + │ ┌──────┴──────┐ + │ ▼ ▼ + │ ┌────────┐ ┌──────────┐ + │ │ Latest │ │ Found! │ ← 显示版本号/大小 + │ └────────┘ └────┬─────┘ + │ │ 用户点击"开始更新" + │ ▼ + │ ┌──────────────┐ + │ ┌─────│ Downloading │ ← 进度条/速度/剩余时间 + │ │ └──────┬───────┘ + │ │ │ + │ │ ┌──────┴──────┐ + │ │ ▼ ▼ + │ │ ┌────────┐ ┌──────────┐ + │ │ │ Paused │ │ Error │ ← 显示错误 + "重试" + │ │ └───┬────┘ └────┬─────┘ + │ │ │ 继续 │ 重试 + │ │ ▼ ▼ + │ │ ┌──────────────┐ + │ │ │ Downloading │ + │ │ └──────────────┘ + │ │ + │ │ ┌──────────────┐ + │ └────→│ Applying │ ← "正在安装更新..." + │ └──────┬───────┘ + │ │ + │ ┌──────┴──────┐ + │ ▼ ▼ + │ ┌─────────┐ ┌──────────┐ + │ │ Success │ │ Failed │ + │ └────┬────┘ └──────────┘ + │ │ + │ ▼ + │ ┌──────────┐ + │ │ Restart │ ← 重启应用 + │ └──────────┘ + │ + └── 回到 Idle +``` + +--- + +## 工作流程 + +``` +1. 框架探测 + ├── 扫描 .csproj → PackageReference 识别 UI 库 + ├── 如果无法识别 → 询问用户 + └── 如果无 UI 框架 → 控制台进度条 + +2. 状态代码生成 + ├── IDownloadService 桥接接口 + ├── RealDownloadService 桥接代码（手动适配 GeneralUpdate.Core 事件） + ├── ViewModel（MVVM）或 Code-Behind + └── 窗口/页面 XAML + +3. 集成指导 + ├── 如何引入 GeneralUpdateBootstrap + └── Bootstrap 配置（与 generalupdate-init 配合） +``` + +--- + +## 核心桥接：RealDownloadService + +所有 UI 模板共享这个桥接类，将 GeneralUpdate.Core 的事件映射到 `IDownloadService` 接口。 + +### 桥接逻辑（v10.4.6 稳定版） + +```csharp +// GeneralUpdate.Core 事件 → DownloadStatus 状态机映射： + +GeneralUpdateBootstrap.AddListenerMultiDownloadStatistics + → Downloading（更新 ProgressPercentage/Speed/Remaining） + +GeneralUpdateBootstrap.AddListenerMultiDownloadCompleted + → 文件处理中（解压/校验） + +GeneralUpdateBootstrap.AddListenerMultiAllDownloadCompleted + → Applying → Success + +GeneralUpdateBootstrap.AddListenerMultiDownloadError + → DownloadError（自动重试 N 次后） + +GeneralUpdateBootstrap.AddListenerException + → Failed（非致命异常不改变状态） +``` + +--- + +## UI 框架模板清单 + +| 模板文件 | 适用框架 | 包含特性 | +|---------|---------|---------| +| `SemiUrsaClientView.axaml` + `.cs` | Avalonia + SemiUrsa | 全状态机、暗黑切换、动画 | +| `SemiUrsaUpgradeView.axaml` + `.cs` | Avalonia + SemiUrsa (Upgrade) | 等待中 UI | +| `LayUIStyle.xaml` + `.cs` | WPF + LayUI.Wpf | 玻璃效果、进度条 | +| `WPFDevelopersStyle.xaml` + `.cs` | WPF + WPFDevelopers | 圆形进度、呼吸灯动画 | +| `AntdUIStyle.cs` | WinForms + AntdUI | 暗黑主题、波浪进度按钮 | +| `MauiUpdatePage.xaml` + `.cs` | MAUI | 深色模式、AppThemeBinding | +| `DownloadViewModels.cs` | 所有框架共用 | MVVM ViewModel | +| `RealDownloadService.cs` | 所有框架共用 | **核心桥接** | + +--- + +## 相关技能 + +- [🚀 generalupdate-init — 如果还未配置 Bootstrap](./generalupdate-init.md) +- [🩺 generalupdate-troubleshoot — 如果 UI 显示异常](./generalupdate-troubleshoot.md) diff --git a/website/docs/agent-skills/overview.md b/website/docs/agent-skills/overview.md new file mode 100644 index 0000000..a699282 --- /dev/null +++ b/website/docs/agent-skills/overview.md @@ -0,0 +1,202 @@ +--- +sidebar_position: 1 +sidebar_label: 📋 总览 +title: 🚀 Agent Skills 总览 +--- + +# 🚀 GeneralUpdate Agent Skills 套件 + +**Claude Code 技能套件** — 帮助 .NET 开发者在 5 分钟内将 [GeneralUpdate](https://github.com/GeneralLibrary/GeneralUpdate) 自动更新系统集成到任意 .NET 应用中。 + +覆盖 50+ 真实 Issue 发现的已知问题，提供即用型代码生成 + 深度故障排查。 + +> **Current Version: 0.0.1-bate.1** — targets NuGet `GeneralUpdate.Core ≥ 10.4.6` stable release +> 兼容性：`v10.4.6`（NuGet 最新稳定版） +> 所有 32 个模板文件已通过 `dotnet build` 编译验证（0 errors）。 + +--- + +## 安装 Skills + +### 获取 Skill 文件 + +所有 Skill 文件位于 `GeneralUpdate-Samples` 仓库的 `tmpgeneralupdate-skill-codegen` 目录下： + +``` +samples-repo/ +└── src/Hub/Samples/ + └── tmpgeneralupdate-skill-codegen/ + ├── SKILL.md ← 套件入口（必装） + └── .claude/skills/ + ├── generalupdate-init/ ← 🚀 集成指南 + ├── generalupdate-ui/ ← 🎨 界面生成 + ├── generalupdate-strategy/ ← ⚙️ 策略指南 + ├── generalupdate-advanced/ ← 🔧 高级定制 + └── generalupdate-troubleshoot/ ← 🩺 故障排查 +``` + +### 安装到 Claude Code + +**方式一（推荐）**：将整个技能套件克隆到你项目的 `.claude` 目录： + +```bash +# 在你的项目根目录下执行 +mkdir -p .claude/skills +cp -r /src/Hub/Samples/tmpgeneralupdate-skill-codegen/.claude/skills/* .claude/skills/ +cp /src/Hub/Samples/tmpgeneralupdate-skill-codegen/SKILL.md .claude/ +``` + +**方式二**：如果已有 `.claude` 目录，只复制 skills 子目录： + +```bash +# 在你的项目根目录下执行 +cp -r /src/Hub/Samples/tmpgeneralupdate-skill-codegen/.claude/skills .claude/ +``` + +### 验证安装 + +启动 Claude Code，输入 `/generalupdate-init`，如果看到集成指南输出，说明安装成功。你也可以直接描述需求让 Skills 自动激活，例如： + +> *"给我的 WPF 应用添加自动更新"* + +--- + +## 先决条件 + +1. **Claude Code**: 需要安装并配置 [Claude Code CLI](https://claude.com/claude-code) +2. **.NET SDK**: 目标项目需基于 .NET 8+（推荐 .NET 10） +3. **GeneralUpdate 服务端**: 对于标准策略，需要部署 [GeneralSpacestation](https://github.com/JusterZhu/GeneralSpacestation) 或兼容的后端服务 +4. **双进程架构**: 需要理解 Client + Upgrade 双进程的核心理念 + +--- + +## Skills 总览 + +| Skill | 命令 | 描述 | 覆盖范围 | +|-------|------|------|----------| +| 🚀 **generalupdate-init** | `/generalupdate-init` | 双项目脚手架 + Bootstrap 配置（4 种方式） | 4 大场景 + 4 种配置方式 + 完整 API | +| 🎨 **generalupdate-ui** | `/generalupdate-ui` | 自动识别 UI 框架，生成全状态更新窗口（11 种状态） | 6 UI 框架 + 全状态机 + 桥接代码 | +| ⚙️ **generalupdate-strategy** | `/generalupdate-strategy` | 6 种策略决策树 + 混合组合 + 平台差异 | 6 策略 + 4 组合 + 平台对照 | +| 🔧 **generalupdate-advanced** | `/generalupdate-advanced` | 10+ 扩展点 + 4 种 IPC + Bowl + AOT | 10+ 扩展点 + 完整架构图 | +| 🩺 **generalupdate-troubleshoot** | `/generalupdate-troubleshoot` | 50+ 已知问题诊断 + 6 步通用排查 | 8 致命 + 11 高 + 20 中 + 12 低 | + +--- + +## 快速开始 + +在 Claude Code 中，只需描述你的需求，对应的 Skill 会自动激活： + +``` +"给我的 WPF 应用添加自动更新" +→ 自动激活 generalupdate-init + generalupdate-ui + +"更新成功了但启动报错" +→ 自动激活 generalupdate-troubleshoot + +"配置 OSS 静默更新" +→ 自动激活 generalupdate-strategy + +"添加 Bowl 崩溃守护 + 自定义 Hooks" +→ 自动激活 generalupdate-advanced +``` + +--- + +## 数据来源 + +所有技能的内容基于以下真实数据： + +- **GitHub Issues**: #308–#517（重构、Bug、功能、测试） +- **Gitee Issues**: 30 个真实用户反馈（中文社区痛点） +- **全面代码审计**: 17 CRITICAL/HIGH + 14 MEDIUM + 10 INFO 发现 +- **Samples 源码**: CompleteUpdateSample、SilentUpdateSample、OssSample、DifferentialSample、PushSample、BowlSample、ExtensionSample、CompressSample、ImDiskQuickInstallSample +- **UI Samples**: SemiUrsa、LayUI、AntdUI、WPFDevelopers、MauiUpdate、AndroidUpdate + +--- + +## Skill 文件结构 + +``` +.claude/skills/ +├── generalupdate-init/ (7 files) +│ ├── SKILL.md ← 4 大场景 + 4 种配置 + API 详解 +│ ├── reference.md ← NuGet/API/协议/框架兼容性 +│ └── templates/ +│ ├── MinimalIntegration.cs +│ ├── FullIntegration.cs +│ ├── generalupdate.manifest.json +│ └── project-scaffold/ +│ +├── generalupdate-ui/ (10 files) +│ ├── SKILL.md ← 11 状态 UI 状态机 + 框架检测逻辑 +│ └── templates/ +│ ├── RealDownloadService.cs +│ ├── DownloadViewModels.cs +│ ├── SemiUrsaClientView.axaml / SemiUrsaUpgradeView.axaml +│ ├── LayUIStyle.xaml / WPFDevelopersStyle.xaml +│ ├── AntdUIStyle.cs +│ └── MauiUpdatePage.xaml/.cs +│ +├── generalupdate-strategy/ (7 files) +│ ├── SKILL.md ← 决策树 + 6 策略详解 + 混合 + 平台对照 +│ └── examples/ +│ ├── ClientServerStrategy.cs / OssStrategy.cs +│ ├── SilentStrategy.cs / DifferentialStrategy.cs +│ └── CrossVersionStrategy.cs / PushStrategy.cs +│ +├── generalupdate-advanced/ (6 files) +│ ├── SKILL.md ← 10+ 扩展点 + 4 IPC + Bowl + 事件系统 +│ ├── reference.md +│ └── templates/ +│ ├── CustomHooks.cs / CustomStrategy.cs +│ ├── BowlIntegration.cs / NamedPipeIPC.cs +│ +└── generalupdate-troubleshoot/ (2 files) + ├── SKILL.md ← 诊断工作流 + └── reference.md ← 50+ 症状清单（C/H/M/L 四级） +``` + +--- + +## API 兼容性说明 + +> ⚠️ **NuGet 引用规则**: +> - Core only: `dotnet add package GeneralUpdate.Core` +> - With Bowl: reference **only** `GeneralUpdate.Bowl`（传递依赖 Core，两者不能共存） +> - Differential 已嵌入 Core，**无需**额外引用 `GeneralUpdate.Differential` + +> ⚠️ **API Surface**: v10.4.6 稳定版 API 与开发分支（v10.5.0-beta.2）有根本性差异。当前稳定版不支持： +> - ❌ 无可编程 `Option` 配置系统（仅 `Configinfo` 属性） +> - ❌ 无 `IUpdateHooks` 生命周期钩子 +> - ❌ 无 `IStrategy` 可替换策略接口 +> - ❌ 无 `SilentPollOrchestrator` +> - ❌ 无 `ProcessContract` / IPC 替换接口 + +--- + +## 反馈与建议 + +使用过程中遇到任何问题或有改进建议，欢迎提交 Issue： + +- **GitHub Issues**: [GeneralUpdate-Samples/issues](https://github.com/GeneralLibrary/GeneralUpdate-Samples/issues) — 报告 Bug、提出功能需求 +- **GeneralUpdate Issues**: [GeneralUpdate/issues](https://github.com/GeneralLibrary/GeneralUpdate/issues) — 核心库 Bug 和功能请求 + +提交时请附上以下信息以便快速排查： +- GeneralUpdate 版本号（如 v10.4.6） +- 平台（Windows / Linux / macOS） +- 更新策略（标准 / OSS / 静默 / 差分 / 推送） +- 完整错误日志（可从 `%TEMP%/GeneralUpdate/logs/` 获取） + +--- + +## 版本历史 + +### 0.0.1-bate.1 — 2026-06-16 + +Initial beta release. All templates rewritten for NuGet v10.4.6 stable API. + +## 相关项目 + +- [GeneralUpdate](https://github.com/GeneralLibrary/GeneralUpdate) — .NET 自动更新核心库 +- [GeneralSpacestation](https://github.com/JusterZhu/GeneralSpacestation) — 更新服务端 +- [GeneralUpdate-Samples](https://github.com/GeneralLibrary/GeneralUpdate-Samples) — 示例项目合集 diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8b5fb0c..db0635c 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -80,6 +80,12 @@ const config = { position: 'left', label: 'Doc', }, + { + type: 'docSidebar', + sidebarId: 'agentSkillsSidebar', + position: 'left', + label: 'Agent Skills', + }, { type: 'dropdown', label: '定价', diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/_category_.json b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/_category_.json new file mode 100644 index 0000000..c3faeb9 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Agent Skills", + "position": 4, + "link": { + "type": "generated-index", + "description": "Claude Code Agent Skills tutorial — help .NET developers integrate GeneralUpdate auto-update into any .NET application in 5 minutes. Covers 50+ real-world issues discovered through GitHub/Gitee, provides production-ready code generation + deep troubleshooting." + } +} diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-advanced.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-advanced.md new file mode 100644 index 0000000..fd00fd9 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-advanced.md @@ -0,0 +1,135 @@ +--- +sidebar_position: 5 +sidebar_label: 🔧 Advanced +title: 🔧 generalupdate-advanced — Advanced Customization +--- + +# 🔧 GeneralUpdate Advanced Customization Reference + +Covers extension point architecture, Pipeline, differential engine, Bowl crash daemon, event system, and filesystem tools. + +> ⚠️ **API Version Note**: This guide is based on **NuGet v10.4.6 stable**. +> +> The following features do **NOT exist** in the stable release (but are available in dev branch v10.5.0-beta.2): +> - `IUpdateHooks` lifecycle hooks +> - `IProcessInfoProvider` IPC replacement interface +> - `SilentPollOrchestrator` silent poller +> - `Option` programmable config system (v10.4.6 uses `Configinfo` properties only) +> - `ISslValidationPolicy` SSL policy interface +> +> Feature availability is noted in each section. + +--- + +## 1. Pipeline System (v10.4.6 available) + +GeneralUpdate uses the Pipeline pattern for update package verification, extraction, and patch application. + +### PipelineBuilder API + +```csharp +using GeneralUpdate.Common.Internal.Pipeline; +using GeneralUpdate.Common.Internal.Strategy; + +var context = new PipelineContext(); +context.Add("ZipFilePath", @"C:\temp\update.zip"); +context.Add("Hash", "sha256-hex-value"); +context.Add("Format", 0); // 0=Zip +context.Add("Encoding", System.Text.Encoding.UTF8); +context.Add("SourcePath", @"C:\Program Files\MyApp"); +context.Add("PatchEnabled", true); + +await new PipelineBuilder(context) + .UseMiddleware() // Hash verification + .UseMiddleware() // Extraction + .UseMiddleware() // Differential patch + .Build(); +``` + +--- + +## 2. Strategy System (v10.4.6 available) + +| Strategy | Class | Platform | +|----------|-------|----------| +| Windows | `WindowsStrategy` | Windows | +| Linux | `LinuxStrategy` | Linux | +| OSS | `OSSStrategy` | Cross-platform | + +> ⚠️ Stable release does **not support** custom strategy injection via `bootstrap.Strategy()`. + +--- + +## 3. Bowl Crash Daemon (v10.4.6 limited) + +> ⚠️ v10.4.6 Bowl only provides basic type definitions. `Bowl` class has no public `LaunchAsync` method. Full functionality is in dev branch. + +### MonitorParameter Configuration + +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; + +var param = new MonitorParameter +{ + ProcessNameOrId = "MyApp.exe", + DumpFileName = "v1.0.0.0_fail.dmp", + FailFileName = "v1.0.0.0_fail.json", + TargetPath = @"C:\Program Files\MyApp", + FailDirectory = @"C:\Program Files\MyApp\fail", + BackupDirectory = @"C:\Program Files\MyApp\backup", + WorkModel = "Upgrade", +}; + +var bowl = new Bowl(); +``` + +--- + +## 4. EventManager (v10.4.6 available) + +```csharp +using GeneralUpdate.Common.Internal.Event; + +// Add listener +EventManager.Instance.AddListener((object? sender, UpdateInfoEventArgs e) => { }); + +// Dispatch event manually +EventManager.Instance.Dispatch(this, new ExceptionEventArgs(ex, "Custom error")); + +// Clear all listeners +EventManager.Instance.Clear(); + +// Dispose +EventManager.Instance.Dispose(); +``` + +> ⚠️ EventManager is a global singleton. After `Dispose()`, `Instance` is still accessible (found by code audit). + +--- + +## Feature Availability Index + +| Feature | Availability | Reference | +|---------|-------------|-----------| +| Pipeline | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Pipeline` | +| Strategy System | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Strategy` | +| FileTree | ✅ v10.4.6 | `GeneralUpdate.Common.FileBasic` | +| BlackList | ✅ v10.4.6 | `Configinfo.BlackFiles` etc. | +| Differential Engine | ✅ needs `GeneralUpdate.Differential` | `DifferentialCore` | +| AOT | ✅ v10.4.6 | `JsonSerializerContext` subclasses | +| EventManager | ✅ v10.4.6 | `GeneralUpdate.Common.Internal.Event` | +| Bowl Crash Daemon | ⚠️ Basic types only | `GeneralUpdate.Bowl.Bowl` | +| IUpdateHooks | ❌ v10.4.6 unsupported | Dev branch v10.5.0-beta.2 | +| Custom Strategy Injection | ❌ v10.4.6 unsupported | Dev branch v10.5.0-beta.2 | +| IPC Replacement Interface | ❌ v10.4.6 unsupported | Dev branch v10.5.0-beta.2 | +| SilentPollOrchestrator | ❌ v10.4.6 unsupported | Dev branch v10.5.0-beta.2 | +| Option System | ❌ v10.4.6 unsupported | Configinfo properties only | + +--- + +## Related Skills + +- [🚀 generalupdate-init — Bootstrap configuration](./generalupdate-init.md) +- [⚙️ generalupdate-strategy — Strategy selection](./generalupdate-strategy.md) +- [🩺 generalupdate-troubleshoot — Issue diagnosis](./generalupdate-troubleshoot.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-init.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-init.md new file mode 100644 index 0000000..535b57d --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-init.md @@ -0,0 +1,204 @@ +--- +sidebar_position: 2 +sidebar_label: 🚀 Integration +title: 🚀 generalupdate-init — Quick Integration Guide +--- + +# 🚀 GeneralUpdate Integration Complete Guide + +Helps developers integrate GeneralUpdate auto-update into any .NET application from scratch, covering all configuration methods, deployment scenarios, and production considerations. + +> ⚠️ **Targeting NuGet v10.4.6 stable**. Dev branch (v10.5.0-beta.2) has different APIs. + +--- + +## Workflow + +``` +1. Project Detection + ├── Check .csproj → target framework, UI type + └── Check existing configuration → NuGet installed? Existing manifest? + +2. Select Integration Mode + ├── [Minimal] (new Configinfo + SetConfig + LaunchAsync) — recommended for new users + ├── [Standard] (Configinfo + event listeners) — fine control + └── [Scaffold] (full dual-project structure) — team projects from scratch + +3. Generate Output + ├── NuGet installation commands + ├── Bootstrap configuration code + ├── manifest.json template + └── Deployment checklist + +4. Next Steps + ├── Need UI → generalupdate-ui + ├── Choose strategy → generalupdate-strategy + └── Having issues → generalupdate-troubleshoot +``` + +--- + +## Core Concept: 4 Update Scenes + +| Scene | Behavior | +|-------|----------| +| **None** | No update needed, launch main app directly | +| **UpgradeOnly** | Only update the upgrade app itself | +| **MainOnly** | Only update the main app | +| **Both** | Update both | + +### Dual-Process Architecture + +``` +App.exe (Client) is responsible for: + ├── Version verification (HTTP request to server) + ├── Downloading all update packages + ├── IPC write (encrypted file to pass parameters to Upgrade) + └── Launching Upgrade.exe then exiting + +Upgrade.exe (Upgrade process) is responsible for: + ├── Reading the IPC file + ├── Applying the update (extract/patch/replace files) + └── Launching the main app then exiting +``` + +--- + +## Configinfo Reference + +### Complete Configinfo Properties + +```csharp +var config = new Configinfo +{ + // === Required === + UpdateUrl = "https://your-server.com/Upgrade/Verification", + AppSecretKey = "your-secret-key", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = ".", + + // === Optional === + ReportUrl = "https://your-server.com/Upgrade/Report", + UpdateLogUrl = "https://your-server.com/Upgrade/Log", + UpgradeClientVersion = "1.0.0.0", + + // === Authentication === + Scheme = "Bearer", + Token = "your-token", + + // === Blacklist (excluded from backup/copy) === + BlackFiles = new List { "*.log", "*.tmp" }, + BlackFormats = new List { ".pdb" }, + SkipDirectorys = new List { "logs", "cache" }, +}; +``` + +### Event Listener Checklist + +```csharp +// All 6 events +.AddListenerUpdateInfo((_, e) => { + /* Version verification results */ +}) +.AddListenerMultiDownloadStatistics((_, e) => { + /* Batch download progress */ +}) +.AddListenerMultiDownloadCompleted((_, e) => { + /* Per-version download complete */ +}) +.AddListenerMultiDownloadError((_, e) => { + /* Download error */ +}) +.AddListenerMultiAllDownloadCompleted((_, e) => { + /* All downloads complete */ +}) +.AddListenerException((_, e) => { + /* Exception handler */ +}) +``` + +--- + +## Integration Code + +### Minimal Integration + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Shared.Object; + +var config = new Configinfo +{ + UpdateUrl = "https://your-server.com/api", + AppSecretKey = "your-32-char-secret-key-here!", + AppName = "MyApp.exe", + MainAppName = "MyApp.exe", + ClientVersion = "1.0.0.0", + ProductId = "my-product-001", + InstallPath = "." +}; + +await new GeneralUpdateBootstrap() + .SetConfig(config) + .LaunchAsync(); +``` + +### Upgrade Process Configuration + +```csharp +using GeneralUpdate.Core; + +// Upgrade mode reads config from IPC file, no SetConfig needed +await new GeneralUpdateBootstrap() + .AddListenerException((_, e) => + Console.WriteLine($"Error: {e.Message}")) + .LaunchAsync(); +``` + +--- + +## Production Deployment Checklist + +### Directory Structure + +``` +publish/ +├── MyApp.exe ← MainAppName (main program) +├── generalupdate.manifest.json +└── update/ + └── UpgradeApp.exe ← Upgrade program, must ship with first release +``` + +### Dual-Process Verification + +| Check | Description | +|-------|-------------| +| UpgradeApp.exe exists in publish directory | Must be present from first release | +| Client and Upgrade use same AppSecretKey | Required for IPC encrypted communication | +| Client and Upgrade use same NuGet version | Mismatch causes "Method not found" | +| Upgrade process doesn't need network | All data pre-downloaded by Client | + +--- + +## ⚠️ Known Issues + +### NuGet Type Conflicts + +`GeneralUpdate.Core` and `GeneralUpdate.Bowl` **cannot be referenced together** (CS0433 type conflicts). + +Choose based on requirements: +- Using Core: `dotnet add package GeneralUpdate.Core` +- Using Bowl: **only reference** `GeneralUpdate.Bowl` (transitively includes all Core functionality) +- Differential types are embedded in Core, **no need** for separate `GeneralUpdate.Differential` package + +--- + +## Related Skills + +- [🎨 generalupdate-ui — UI framework auto-detection + update window code generation](./generalupdate-ui.md) +- [⚙️ generalupdate-strategy — 6 update strategy selection and configuration](./generalupdate-strategy.md) +- [🔧 generalupdate-advanced — Advanced customization](./generalupdate-advanced.md) +- [🩺 generalupdate-troubleshoot — Known issue diagnosis](./generalupdate-troubleshoot.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-strategy.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-strategy.md new file mode 100644 index 0000000..39ad620 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-strategy.md @@ -0,0 +1,77 @@ +--- +sidebar_position: 4 +sidebar_label: ⚙️ Strategy +title: ⚙️ generalupdate-strategy — Update Strategy Guide +--- + +# ⚙️ GeneralUpdate Strategy Complete Guide + +> ⚠️ **Targeting NuGet v10.4.6 stable**. This version uses `Configinfo` configuration, with no programmatic `Option` system. + +--- + +## Strategy Decision Tree + +``` +Does your app have a backend service? +├── Yes +│ ├── Need server-push updates? → SignalR Push +│ └── No → Standard Client-Server +│ +└── No (only object storage S3/MinIO/OSS) + └── OSS Standard +``` + +--- + +## 6 Strategy Comparison + +| Strategy | Server | Description | +|----------|:------:|-------------| +| **① Standard Client-Server** | ✅ GeneralSpacestation | Medium/large apps with backend (recommended starting point) | +| **② OSS Object Storage** | ❌ S3/MinIO only | No backend, lowest cost | +| **③ Silent Update** | ✅ Same as ① or ② | Background silent upgrade | +| **④ Differential Update** | ✅ Needs differential builds | Incremental patches to save bandwidth | +| **⑤ Cross Version (CVP)** | ✅ Needs CVP builds | Skip intermediate versions | +| **⑥ SignalR Push** | ✅ Needs SignalR Hub | Server-initiated updates | + +--- + +## Mixed Strategy Combinations + +| Combination | Typical Scenario | +|-------------|------------------| +| **OSS + Silent** | Game launcher / kiosk — pulls from CDN, no user interaction | +| **Standard + Differential** | Full download on first update, patches thereafter | +| **CVP + Differential** | Cross-version jump as a single binary patch | +| **Standard + Push** | Backend pushes notification, user clicks to download | + +--- + +## Platform Differences + +| Platform | Notes | +|----------|-------| +| **Windows** | Full functionality. **Bowl** crash daemon (restarts app bus on unhandled exception). Full filesystem access. | +| **Linux / macOS** | ⚠️ v10.4.6 has no `UnixPermissionHooks`, need manual `chmod +x`. Target .NET 8+. | + +--- + +## Known Issues + +| # | Issue | Workaround | +|---|-------|------------| +| 1 | OSS mode doesn't distinguish Main/Upgrade updates | Accept this behavior | +| 2 | UpgradeApp.exe must be in `update/` subdirectory | Deploy as specified | +| 3 | NuGet version mismatch causes "Method not found" | Use same version for Client and Upgrade | +| 4 | Infinite update loop | Ensure manifest.json version is correct | +| 5 | SignalR HubConnection crashes after Dispose | Set connection to null when disposing | + +--- + +## Related Skills + +- [🚀 generalupdate-init — Bootstrap configuration](./generalupdate-init.md) +- [🎨 generalupdate-ui — Update UI generation](./generalupdate-ui.md) +- [🩺 generalupdate-troubleshoot — Issue diagnosis](./generalupdate-troubleshoot.md) +- [🔧 generalupdate-advanced — Advanced customization](./generalupdate-advanced.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-troubleshoot.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-troubleshoot.md new file mode 100644 index 0000000..728c846 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-troubleshoot.md @@ -0,0 +1,117 @@ +--- +sidebar_position: 6 +sidebar_label: 🩺 Troubleshoot +title: 🩺 generalupdate-troubleshoot — Troubleshooting +--- + +# 🩺 GeneralUpdate Troubleshooting + +Comprehensive diagnostic system covering 50+ known issues, all traceable to GitHub/Gitee Issues or code audit findings. + +## Workflow + +``` +1. Symptom Collection + ├── What is the user's symptom? + ├── Error message/stack trace? + ├── GeneralUpdate version? + ├── Platform (Windows/Linux/macOS)? + └── Update strategy (Standard/OSS/Silent)? + +2. Symptom Matching → Lookup known issues + ├── Match found → Provide root cause + fix + code + └── No match → Execute 6-step universal diagnostic + +3. Provide Fix + ├── Specific code changes, config adjustments, version upgrade suggestions + └── Preventive measures + +4. Verify + └── Confirm the fix resolves the issue +``` + +## Symptom Severity Levels + +| Level | Color | Meaning | Count | +|:-----:|:-----:|---------|:-----:| +| C | 🔴 **Critical** | Blocking failure, data corruption, security vulnerability | 8 | +| H | 🟠 **High** | Scenario blocking, feature failure, upgrade needed | 11 | +| M | 🟡 **Medium** | Functionality degraded, configuration adjustment needed | 20 | +| L | 🔵 **Low** | Code smell, edge cases, known behavior | 12 | + +--- + +## C Level (Critical) — Blocks Updates + +| Issue | Cause | Solution | +|-------|-------|----------| +| **Update not starting** | `LaunchAsync()` not called / UpgradeApp.exe not deployed | Ensure `Bootstrap.LaunchAsync()` is called in `Main()` | +| **Method not found** | Client and Upgrade NuGet versions differ | Unify NuGet versions, clean bin/obj and rebuild | +| **Path too long (>260)** | Windows path limit | Shorten install path | +| **IPC exposure** | IPC encryption key hardcoded | Use strong AppSecretKey; upgrade to v10.4.6+ | +| **Cross-tenant leakage** | Missing server multi-tenant isolation | Independent ProductId + AppSecretKey per tenant | +| **ZIP traversal write** | Malicious ZIP with `../` paths | v10.4.6+ already fixed | +| **BSDIFF integer overflow** | Large file diff calculation overflow | Use HDiffPatch algorithm | +| **Silent mode not working** | Process exit not triggered | Ensure Close() or Dispose() is called correctly | + +## H Level (High) — Severe but Non-Blocking + +| Issue | Cause | Solution | +|-------|-------|----------| +| **Infinite update loop** | manifest.json version not updated | Upgrade to v10.4.6+ (WriteBack fixed) | +| **OSS no update found** | Bucket config wrong / incorrect versions.json | curl test OSS URL | +| **File in use** | Target file locked | Close main process before update | +| **SignalR push not responding** | Connection dropped or auth failure | Check SignalR Hub status and Token config | +| **Bowl not monitoring** | Process name misconfigured | Verify ProcessNameOrId matches actual process | + +## M Level (Medium) — Functionality Degraded + +| Issue | Cause | Solution | +|-------|-------|----------| +| **AOT build failure** | Reflection not adapted for NativeAOT | Add `[DynamicDependency]` attributes | +| **SignalR reconnection slow** | RetryDelay too long | Adjust retry parameters | +| **Logs not outputting** | Log path permission issue | Check %TEMP%/GeneralUpdate/logs/ permissions | +| **Multi-tenant config wrong** | ProductId collision | Ensure unique ProductId per tenant | + +## L Level (Low) — Non-Critical + +| Issue | Cause | Solution | +|-------|-------|----------| +| **Package too large** | Differential not enabled | Differential is embedded in Core, enable `PatchEnabled` | +| **First update slow** | CDN cold start | Warm up CDN | +| **Config lost after update** | Blacklist doesn't include config dir | Ensure `SkipDirectorys` includes config folder | + +--- + +## 6-Step Universal Diagnostic + +When the issue can't be directly matched, follow these 6 steps: + +1. **Version consistency check** — Are Client and Upgrade NuGet versions the same? +2. **manifest.json verification** — Does the file exist? Are fields correct? +3. **UpgradeApp existence** — Is UpgradeApp.exe in the expected directory? +4. **Network accessibility** — Can you curl the UpdateUrl? +5. **Log analysis** — Check logs in `%TEMP%/GeneralUpdate/logs/` +6. **Minimal reproduction** — Start with Minimal integration, gradually add complexity + +## Log File Locations + +| Platform | Default Path | +|----------|-------------| +| Windows | `%TEMP%/GeneralUpdate/logs/` | +| Linux | `/tmp/GeneralUpdate/logs/` | + +## Security Notes + +- AppSecretKey management — hardcoding in the client is a last resort; prefer startup arguments or environment variables +- Rotate IPC encryption keys regularly +- Disable debug logging in production + +--- + +## Related Skills + +- [🚀 generalupdate-init — Bootstrap configuration](./generalupdate-init.md) +- [🎨 generalupdate-ui — Update UI diagnostics](./generalupdate-ui.md) +- [⚙️ generalupdate-strategy — Strategy-related issues](./generalupdate-strategy.md) +- [🔧 generalupdate-advanced — Advanced feature issues](./generalupdate-advanced.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-ui.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-ui.md new file mode 100644 index 0000000..cca2056 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/generalupdate-ui.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 3 +sidebar_label: 🎨 UI Generation +title: 🎨 generalupdate-ui — Update UI Generation +--- + +# 🎨 GeneralUpdate Update UI Generation — Full State Coverage + +Auto-detects the developer's UI framework and generates a complete update window with real GeneralUpdate.Core event bindings. + +> ⚠️ Targeting NuGet v10.4.6 stable. `RealDownloadService.cs` is an abstract bridge template requiring manual adaptation. + +--- + +## UI State Machine (Covered by All Templates) + +``` + ┌─────────────┐ + │ Idle │ ← Initial state + └──────┬──────┘ + │ Auto/manual trigger + ▼ + ┌─────────────┐ + ┌─────│ Checking │ ← "Checking for updates..." + │ └──────┬──────┘ + │ │ + │ ┌──────┴──────┐ + │ ▼ ▼ + │ ┌────────┐ ┌──────────┐ + │ │ Latest │ │ Found! │ ← Show version/size + │ └────────┘ └────┬─────┘ + │ │ User clicks "Update" + │ ▼ + │ ┌──────────────┐ + │ ┌─────│ Downloading │ ← Progress bar/speed/time + │ │ └──────┬───────┘ + │ │ │ + │ │ ┌──────┴──────┐ + │ │ ▼ ▼ + │ │ ┌────────┐ ┌──────────┐ + │ │ │ Paused │ │ Error │ ← Show error + "Retry" + │ │ └───┬────┘ └────┬─────┘ + │ │ │ Resume │ Retry + │ │ ▼ ▼ + │ │ ┌──────────────┐ + │ │ │ Downloading │ + │ │ └──────────────┘ + │ │ + │ │ ┌──────────────┐ + │ └────→│ Applying │ ← "Installing update..." + │ └──────┬───────┘ + │ │ + │ ┌──────┴──────┐ + │ ▼ ▼ + │ ┌─────────┐ ┌──────────┐ + │ │ Success │ │ Failed │ + │ └────┬────┘ └──────────┘ + │ │ + │ ▼ + │ ┌──────────┐ + │ │ Restart │ ← Restart app + │ └──────────┘ + │ + └── Back to Idle +``` + +--- + +## Core Bridge: RealDownloadService + +All UI templates share this bridge class, mapping GeneralUpdate.Core events to the `IDownloadService` interface. + +### Bridge Logic (v10.4.6 stable) + +```csharp +// GeneralUpdate.Core Event → DownloadStatus State Machine Mapping: + +GeneralUpdateBootstrap.AddListenerMultiDownloadStatistics + → Downloading (update ProgressPercentage/Speed/Remaining) + +GeneralUpdateBootstrap.AddListenerMultiDownloadCompleted + → Processing files (extraction/verification) + +GeneralUpdateBootstrap.AddListenerMultiAllDownloadCompleted + → Applying → Success + +GeneralUpdateBootstrap.AddListenerMultiDownloadError + → DownloadError (after N automatic retries) + +GeneralUpdateBootstrap.AddListenerException + → Failed (non-fatal exceptions don't change state) +``` + +--- + +## UI Framework Template List + +| Template File | Framework | Features | +|---------------|-----------|----------| +| `SemiUrsaClientView.axaml` + `.cs` | Avalonia + SemiUrsa | Full state machine, dark toggle, animations | +| `SemiUrsaUpgradeView.axaml` + `.cs` | Avalonia + SemiUrsa (Upgrade) | Waiting UI | +| `LayUIStyle.xaml` + `.cs` | WPF + LayUI.Wpf | Glass effect, progress bar | +| `WPFDevelopersStyle.xaml` + `.cs` | WPF + WPFDevelopers | Circular progress, breathing light animation | +| `AntdUIStyle.cs` | WinForms + AntdUI | Dark theme, wave progress button | +| `MauiUpdatePage.xaml` + `.cs` | MAUI | Dark mode, AppThemeBinding | +| `DownloadViewModels.cs` | All frameworks shared | MVVM ViewModel | +| `RealDownloadService.cs` | All frameworks shared | **Core bridge** | + +--- + +## Related Skills + +- [🚀 generalupdate-init — Bootstrap configuration](./generalupdate-init.md) +- [🩺 generalupdate-troubleshoot — UI display issues](./generalupdate-troubleshoot.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/overview.md b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/overview.md new file mode 100644 index 0000000..d910810 --- /dev/null +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/agent-skills/overview.md @@ -0,0 +1,202 @@ +--- +sidebar_position: 1 +sidebar_label: 📋 Overview +title: 🚀 Agent Skills Overview +--- + +# 🚀 GeneralUpdate Agent Skills Suite + +**Claude Code Skill Suite** — Helps .NET developers integrate the [GeneralUpdate](https://github.com/GeneralLibrary/GeneralUpdate) auto-update system into any .NET application in 5 minutes. + +Covers 50+ real-world issues discovered through GitHub/Gitee, providing production-ready code generation + deep troubleshooting. + +> **Current Version: 0.0.1-bate.1** — targets NuGet `GeneralUpdate.Core ≥ 10.4.6` stable release +> Compatibility: `v10.4.6` (latest NuGet stable release) +> All 32 template files have passed `dotnet build` verification (0 errors). + +--- + +## Installing Skills + +### Get the Skill Files + +All Skill files are located in the `GeneralUpdate-Samples` repository under the `tmpgeneralupdate-skill-codegen` directory: + +``` +samples-repo/ +└── src/Hub/Samples/ + └── tmpgeneralupdate-skill-codegen/ + ├── SKILL.md ← Suite entry point (required) + └── .claude/skills/ + ├── generalupdate-init/ ← 🚀 Integration Guide + ├── generalupdate-ui/ ← 🎨 UI Generation + ├── generalupdate-strategy/ ← ⚙️ Strategy Guide + ├── generalupdate-advanced/ ← 🔧 Advanced Customization + └── generalupdate-troubleshoot/ ← 🩺 Troubleshooting +``` + +### Install into Claude Code + +**Option 1 (Recommended)**: Clone the entire skill suite into your project's `.claude` directory: + +```bash +# Run in your project root +mkdir -p .claude/skills +cp -r /src/Hub/Samples/tmpgeneralupdate-skill-codegen/.claude/skills/* .claude/skills/ +cp /src/Hub/Samples/tmpgeneralupdate-skill-codegen/SKILL.md .claude/ +``` + +**Option 2**: If you already have a `.claude` directory, just copy the skills subdirectory: + +```bash +# Run in your project root +cp -r /src/Hub/Samples/tmpgeneralupdate-skill-codegen/.claude/skills .claude/ +``` + +### Verify Installation + +Start Claude Code and type `/generalupdate-init`. If you see the integration guide output, installation was successful. You can also let Skills auto-activate by describing your needs, for example: + +> *"Add auto-update to my WPF application"* + +--- + +## Prerequisites + +1. **Claude Code**: Install and configure [Claude Code CLI](https://claude.com/claude-code) +2. **.NET SDK**: Target project must be .NET 8+ (.NET 10 recommended) +3. **GeneralUpdate Server**: For standard strategies, deploy [GeneralSpacestation](https://github.com/JusterZhu/GeneralSpacestation) or a compatible backend service +4. **Dual-Process Architecture**: Understand the Client + Upgrade dual-process concept + +--- + +## Skills Overview + +| Skill | Command | Description | Coverage | +|-------|---------|-------------|----------| +| 🚀 **generalupdate-init** | `/generalupdate-init` | Dual-project scaffold + Bootstrap config (4 methods) | 4 update scenes + 4 config modes + full API | +| 🎨 **generalupdate-ui** | `/generalupdate-ui` | Auto-detect UI framework, generate full-state update window (11 states) | 6 UI frameworks + full state machine + bridge code | +| ⚙️ **generalupdate-strategy** | `/generalupdate-strategy` | 6 strategy decision tree + mixed combinations + platform differences | 6 strategies + 4 combinations + platform reference | +| 🔧 **generalupdate-advanced** | `/generalupdate-advanced` | 10+ extension points + 4 IPC + Bowl + AOT | 10+ extension points + architecture guide | +| 🩺 **generalupdate-troubleshoot** | `/generalupdate-troubleshoot` | 50+ known issue diagnosis + 6-step universal troubleshooting | 8 Critical + 11 High + 20 Medium + 12 Low | + +--- + +## Quick Start + +In Claude Code, just describe your needs and the corresponding Skill will auto-activate: + +``` +"Add auto-update to my WPF application" +→ Auto-activates generalupdate-init + generalupdate-ui + +"Update succeeded but app crashes on startup" +→ Auto-activates generalupdate-troubleshoot + +"Configure OSS silent update" +→ Auto-activates generalupdate-strategy + +"Add Bowl crash daemon + custom Hooks" +→ Auto-activates generalupdate-advanced +``` + +--- + +## Data Sources + +All skill content is based on real-world data: + +- **GitHub Issues**: #308–#517 (refactoring, bugs, features, tests) +- **Gitee Issues**: 30 real user feedback (Chinese community pain points) +- **Full Code Audit**: 17 CRITICAL/HIGH + 14 MEDIUM + 10 INFO findings +- **Samples Source Code**: CompleteUpdateSample, SilentUpdateSample, OssSample, DifferentialSample, PushSample, BowlSample, ExtensionSample, CompressSample, ImDiskQuickInstallSample +- **UI Samples**: SemiUrsa, LayUI, AntdUI, WPFDevelopers, MauiUpdate, AndroidUpdate + +--- + +## Skill File Structure + +``` +.claude/skills/ +├── generalupdate-init/ (7 files) +│ ├── SKILL.md +│ ├── reference.md +│ └── templates/ +│ ├── MinimalIntegration.cs +│ ├── FullIntegration.cs +│ ├── generalupdate.manifest.json +│ └── project-scaffold/ +│ +├── generalupdate-ui/ (10 files) +│ ├── SKILL.md +│ └── templates/ +│ ├── RealDownloadService.cs +│ ├── DownloadViewModels.cs +│ ├── SemiUrsaClientView.axaml / SemiUrsaUpgradeView.axaml +│ ├── LayUIStyle.xaml / WPFDevelopersStyle.xaml +│ ├── AntdUIStyle.cs +│ └── MauiUpdatePage.xaml/.cs +│ +├── generalupdate-strategy/ (7 files) +│ ├── SKILL.md +│ └── examples/ +│ ├── ClientServerStrategy.cs / OssStrategy.cs +│ ├── SilentStrategy.cs / DifferentialStrategy.cs +│ └── CrossVersionStrategy.cs / PushStrategy.cs +│ +├── generalupdate-advanced/ (6 files) +│ ├── SKILL.md +│ ├── reference.md +│ └── templates/ +│ ├── CustomHooks.cs / CustomStrategy.cs +│ ├── BowlIntegration.cs / NamedPipeIPC.cs +│ +└── generalupdate-troubleshoot/ (2 files) + ├── SKILL.md + └── reference.md ← 50+ symptom checklist (C/H/M/L levels) +``` + +--- + +## API Compatibility Notes + +> ⚠️ **NuGet Reference Rules**: +> - Core only: `dotnet add package GeneralUpdate.Core` +> - With Bowl: reference **only** `GeneralUpdate.Bowl` (transitively includes Core — they cannot coexist) +> - Differential is embedded in Core, **no need** for a separate `GeneralUpdate.Differential` reference + +> ⚠️ **API Surface**: v10.4.6 stable API differs fundamentally from the dev branch (v10.5.0-beta.2). The stable release does NOT support: +> - ❌ Programmatic `Option` config system (only `Configinfo` properties) +> - ❌ `IUpdateHooks` lifecycle hooks +> - ❌ `IStrategy` replaceable strategy interface +> - ❌ `SilentPollOrchestrator` +> - ❌ `ProcessContract` / IPC replacement interfaces + +--- + +## Feedback & Suggestions + +If you encounter any issues or have suggestions for improvement, please submit an Issue: + +- **GitHub Issues**: [GeneralUpdate-Samples/issues](https://github.com/GeneralLibrary/GeneralUpdate-Samples/issues) — Report bugs, request features +- **GeneralUpdate Issues**: [GeneralUpdate/issues](https://github.com/GeneralLibrary/GeneralUpdate/issues) — Core library bugs and feature requests + +For faster resolution, please include: +- GeneralUpdate version (e.g. v10.4.6) +- Platform (Windows / Linux / macOS) +- Update strategy (Standard / OSS / Silent / Differential / Push) +- Full error log (available from `%TEMP%/GeneralUpdate/logs/`) + +--- + +## Version History + +### 0.0.1-bate.1 — 2026-06-16 + +Initial beta release. All templates rewritten for NuGet v10.4.6 stable API. + +## Related Projects + +- [GeneralUpdate](https://github.com/GeneralLibrary/GeneralUpdate) — .NET auto-update core library +- [GeneralSpacestation](https://github.com/JusterZhu/GeneralSpacestation) — Update server +- [GeneralUpdate-Samples](https://github.com/GeneralLibrary/GeneralUpdate-Samples) — Sample projects diff --git a/website/sidebars.js b/website/sidebars.js index 0631ae4..5f81aca 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -54,6 +54,16 @@ const sidebars = { ], }, ], + + // ── Agent Skills Sidebar (独立侧边栏) ──────────────────────────── + agentSkillsSidebar: [ + 'agent-skills/overview', + 'agent-skills/generalupdate-init', + 'agent-skills/generalupdate-ui', + 'agent-skills/generalupdate-strategy', + 'agent-skills/generalupdate-advanced', + 'agent-skills/generalupdate-troubleshoot', + ], }; export default sidebars;