Skip to content

Commit 231c1c2

Browse files
JusterZhuclaude
JusterZhu
and
claude
committed
feat: add multi-agent adapters - Cursor / Copilot / Cline / Codex CLI
13 new adapter files enabling GeneralUpdate skills across 4 additional AI agents: - .cursor/rules/ (5 .mdc files) — Cursor IDE, YAML frontmatter + globs + alwaysApply - .github/copilot-instructions.md — GitHub Copilot (repository-wide, all-in-one) - .github/instructions/backend-api.instructions.md — Copilot path-specific API contract - .clinerules/ (5 .md files) — Cline, YAML frontmatter + globs + tags - RULES.md — Codex CLI / universal agent (single comprehensive reference) Total: 49 files across 5 agent formats Co-Authored-By: Claude <noreply@anthropic.com>
1 parent e7ca6eb commit 231c1c2

13 files changed

Lines changed: 445 additions & 0 deletions

‎.clinerules/01-generalupdate-init.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
description: "GeneralUpdate auto-update integration for .NET — Bootstrap, manifest, dual-project scaffold"
3+
globs: ["**/*.cs", "**/*.csproj", "**/*.json"]
4+
tags: ["dotnet", "update", "generalupdate"]
5+
---
6+
7+
# GeneralUpdate 快速集成
8+
9+
## NuGet: GeneralUpdate.Core(必需), Differential(可选), Bowl(可选)
10+
11+
## 最小集成
12+
SetSource(url, key) -> SetOption(AppType.Client) -> LaunchAsync()
13+
14+
## 4 大场景: None/UpgradeOnly/MainOnly/Both
15+
16+
## manifest.json 字段
17+
MainAppName, UpdateAppName, ProductId, InstallPath, UpdatePath, ClientVersion, UpgradeClientVersion
18+
19+
## 关键: UpgradeApp须随首个版本发布, 双进程AppSecretKey一致, 版本4段式

‎.clinerules/02-generalupdate-ui.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
description: "GeneralUpdate update UI — framework detection, RealDownloadService bridge, 11-state state machine"
3+
globs: ["**/*.xaml", "**/*.axaml", "**/*.cs"]
4+
tags: ["dotnet", "wpf", "avalonia", "winforms", "maui"]
5+
---
6+
7+
# 更新界面
8+
9+
## 框架: SemiUrsa/LayUI/WPFDevelopers/AntdUI/MAUI
10+
11+
## 11状态: Idle->Checking->Found->Downloading->Paused->Error->Applying->Success->Failed->Rollback->Latest
12+
13+
## 桥接: RealDownloadService(GeneralUpdate.Core -> IDownloadService)

‎.clinerules/03-generalupdate-strategy.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: "GeneralUpdate strategies — decision tree, 6 strategies, mixed combinations"
3+
globs: ["**/*.cs"]
4+
tags: ["dotnet", "generalupdate"]
5+
---
6+
7+
# Update Strategies
8+
9+
## Decision Tree
10+
11+
- **Has a backend (SignalR, gRPC, WebSocket, etc.)?** -> SignalR / Silent / Differential / Standard
12+
- **No backend?** -> OSS (Object Storage Service)
13+
14+
## The 6 Strategies
15+
16+
| Strategy | When to Use |
17+
|----------|-------------|
18+
| **Standard** | Direct download from an HTTP/S source with basic UI progress. Simplest setup. |
19+
| **OSS** | Files hosted on S3 / MinIO / Azure Blob / OSS-compatible storage. No backend required. |
20+
| **Silent** | Unattended background update. No UI shown to the user. Reboots / restarts on next launch. |
21+
| **Differential** | Binary diff (bsdiff) patches instead of full-file downloads. Save bandwidth — good for large binaries. |
22+
| **CVP** (Cross Version Patch) | Skip intermediate versions when jumping N versions. Client applies a cumulative patch. |
23+
| **Push** | Server-initiated update via SignalR / WebSocket push notification. Client then fetches the package. |
24+
25+
## Mixed Combinations
26+
27+
| Combination | Typical Scenario |
28+
|-------------|------------------|
29+
| **OSS + Silent** | Game launcher / kiosk — pulls from CDN, no UI interaction. |
30+
| **Standard + Differential** | Client downloads full files on first update, patches thereafter. |
31+
| **CVP + Differential** | Cross-version jump applied as a single binary patch — best of both strategies. |
32+
| **Standard + Push** | Backend pushes a "new version available" toast; user clicks to download via HTTP. |
33+
34+
## Platform Considerations
35+
36+
| Platform | Notes |
37+
|----------|-------|
38+
| **Windows** | Uses **Bowl** crash daemon (restarts the app bus on unhandled exception). Full file-system access. |
39+
| **Linux / macOS** | Uses **UnixPermissionHooks** to handle `chmod +x` / setuid and OS-level permission elevation. |
40+
41+
> For the full Bootstrap pipeline and middleware architecture, see `01-generalupdate-init.md`.

‎.clinerules/04-generalupdate-advanced.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: "GeneralUpdate advanced — 10+ extension points, 4 IPC, Bowl, AOT"
3+
globs: ["**/*.cs"]
4+
tags: ["dotnet", "generalupdate", "advanced"]
5+
---
6+
7+
# 高级定制
8+
9+
## 扩展点: Hooks/Strategy/UpdateReporter/DownloadSource/DownloadOrchestrator/DownloadPolicy/DownloadExecutor/DownloadPipeline/SslValidationPolicy/HttpAuthProvider
10+
11+
## IPC: EncryptedFile(默认)/NamedPipe/SharedMemory/AutoFallback
12+
13+
## Bowl: procdump->监控->dump->故障报告->AutoRestore
14+
15+
## AOT: v5.0+支持, SignalR用JSON+JsonSerializerContext

‎.clinerules/05-generalupdate-troubleshoot.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
description: "GeneralUpdate troubleshooting — 50+ issues C/H/M/L, diagnostic workflow"
3+
globs: ["**/*.cs", "**/*.csproj", "**/*.json"]
4+
tags: ["dotnet", "generalupdate"]
5+
---
6+
7+
# 故障排查
8+
9+
## 诊断: 版本一致? manifest正确? UpgradeApp存在? 策略可访问? 日志异常?
10+
11+
## C级: 升级没启动/Method not found/路径超长/IPC暴露/跨租户泄露
12+
## H级: 静默不生效/无限循环/OSS无更新/文件占用
13+
14+
## 命令: curl测试API, cat manifest验证, ls检查UpgradeApp
15+
16+
---
17+
18+
## 诊断流程 (5步)
19+
20+
1. **版本号** — `manifest.json` 的 `ClientVersion` / `UpgradeClientVersion` 是否与服务端返回的版本一致? 4段式版本(string)严格匹配。
21+
2. **manifest 字段** — `MainAppName`、`UpdateAppName`、`ProductId`、`InstallPath`、`UpdatePath` 是否填写正确且与服务端一致?
22+
3. **UpgradeApp 存在** — 主应用目录下是否存在 `Upgrade` 子目录及 `Upgrade.exe` (或对应平台可执行文件)? 随首个版本一同发布的。
23+
4. **策略可访问** — `SetSource(url, key)` 配置的 API/OSS 端点能否正常响应? OSS 策略需要 `SetOSSInfo` 配置正确。
24+
5. **日志异常** — 检查 `logs/` 目录下 GeneralUpdate 日志, 搜索 `Exception` / `Error` / `Failed` 关键字。
25+
26+
## C级 (Critical) — 阻塞升级
27+
28+
| 问题 | 原因 | 排查/解决 |
29+
|------|------|-----------|
30+
| **升级没启动** | `LaunchAsync()` 未调用 / 调用顺序错误 / 主进程未检测到新版本 | 确认 `Bootstrap.LaunchAsync()` 在 `Main()` 中调用, 且 `SetOption(AppType.Client)` 正确 |
31+
| **Method not found** | 引用的 GeneralUpdate 版本与服务端不匹配 / 混用不同大版本 | 统一 NuGet 版本, 清理 bin/obj 后重新生成 |
32+
| **路径超长 (>260)** | Windows 路径限制, `InstallPath` / `UpdatePath` 过深 | 缩短安装路径; 或启用 `SetOption` 中的长路径支持 (`LongPathSupport = true`) |
33+
| **IPC 暴露** | EncryptedFile IPC 写入明文 / NamedPipe 未鉴权 | 启用加密传输; NamedPipe 设置 `AccessControl` 限制连接用户; 不使用 `AutoFallback` 回退到明文 |
34+
| **跨租户泄露** | 多租户部署共用 `ProductId` / `AppSecretKey` | 每个租户分配独立 `ProductId` 和 `AppSecretKey`; 服务端鉴权时校验租户标识 |
35+
36+
## H级 (High) — 严重但不阻塞启动
37+
38+
| 问题 | 原因 | 排查/解决 |
39+
|------|------|-----------|
40+
| **静默更新不生效** | `UpdateMode.Silent` 配置缺失 / 权限不足无法后台启动 | 确认 `SetOption(UpdateMode.Silent)` 且应用有后台运行权限; 检查 `LaunchCommand` 参数是否正确传递 |
41+
| **无限循环更新** | `ClientVersion` 与服务端最新版本不一致导致不断检测到"新版本" | 验证更新后是否更新了本地 `manifest.json` 的版本号; 确认服务端已标记该版本为"已发布"状态 |
42+
| **OSS 无更新** | Bucket 配置错误 / 文件命名不匹配 / 签名过期 | `curl` 测试 OSS URL 是否直接可下载; 确认 `SetOSSInfo` 的 endpoint/bucket/region 正确 |
43+
| **文件占用** | 更新时目标文件正在被使用 (主进程/杀软/搜索索引) | 关闭主进程后更新; 使用 `Bowl` 守护进程管理进程生命周期; 排除杀软扫描目录 |
44+
45+
## M级 (Medium) — 功能降级
46+
47+
| 问题 | 原因 | 排查/解决 |
48+
|------|------|-----------|
49+
| **进度不动** | `IDownloadService` 未正确绑定 / UI 线程阻塞 | 确认桥接实现; 使用 `async/await` 避免阻塞 UI 线程 |
50+
| **差分更新失败** | BSDIFF 补丁应用时数据不完整 / 旧版本基准文件不匹配 | 校验原始文件哈希; 确认差分策略仅在同源版本间使用 |
51+
| **升级后配置丢失** | `UpdatePath` 未包含配置文件 / 更新后未合并 `appsettings.json` | 在更新流程中添加配置文件合并步骤; 或使用外部配置中心 |
52+
| **信号量泄露** | IPC 信号量未正确释放, 重启后端口/资源被占用 | 重启系统; 检查 `Bowl` 是否正确清理资源; 监控信号量计数 |
53+
| **ZIP 遍历写入** | 恶意更新的 ZIP 包包含 `../` 路径覆盖系统文件 | 使用 `ZipSecurity` 校验项, 拒绝包含 `../` 或绝对路径的条目 |
54+
| **AOT 编译失败** | 动态加载 / 反射代码未适配 NativeAOT | 添加 `[DynamicDependency]` 特性; 避免 `Assembly.Load` 等动态加载 |
55+
| **SignalR 重连慢** | WebSocket 长连接断开后 `RetryDelay` 配置过长 | 调整 `SignalRRetryPolicy` 的 `RetryDelay` 和 `MaxRetryCount` |
56+
| **SSL 证书错误** | 自签名证书未受信 / 服务器 SNI 不匹配 | 配置 `SslValidationPolicy`; 或添加自定义证书验证委托 |
57+
58+
## L级 (Low) — 非关键
59+
60+
| 问题 | 原因 | 排查/解决 |
61+
|------|------|-----------|
62+
| **UI 闪烁** | 主/升级进程窗口切换 | 使用 `Silent` 模式; 或延长窗口淡入淡出过渡时间 |
63+
| **日志过多** | `LogLevel.Debug` 未关闭 | 生产环境使用 `LogLevel.Warning` 或 `LogLevel.Error` |
64+
| **分发包过大** | 包含完整文件而非差异包 | 启用 `Differential` 策略; 清理冗余依赖 (移除 `Microsoft.*` 运行时) |
65+
| **首次更新慢** | OSS 冷启动 / CDN 首次回源 | 预热 CDN; 或发布版本前预上传到上传节点 |
66+
| **多语言显示异常** | CultureInfo 在更新线程中未继承 | 在更新线程入口处设置 `CultureInfo.CurrentUICulture` |
67+
68+
## 诊断命令速查
69+
70+
```bash
71+
# 测试 API 是否可访问
72+
curl -v "http://your-server/api/update/check?appName=MyApp&clientVersion=1.0.0.1"
73+
74+
# 验证 manifest.json 内容
75+
cat /path/to/app/manifest.json | jq .
76+
77+
# 检查 UpgradeApp 是否存在
78+
ls -la /path/to/app/Upgrade/Upgrade.exe
79+
80+
# 查看 OSS 文件列表
81+
curl -v "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/?prefix=updates/"
82+
83+
# 检查端口占用 (IPC 调试)
84+
netstat -ano | findstr :54321
85+
86+
# 检查信号量残留 (Windows)
87+
powershell "Get-CimInstance Win32_Semaphore | Select-Object Name, Count"
88+
```
89+
90+
## 日志文件位置
91+
92+
| 平台 | 默认路径 |
93+
|------|----------|
94+
| Windows | `%LOCALAPPDATA%\GeneralUpdate\logs\{ProductId}\` |
95+
| Linux | `~/.local/share/GeneralUpdate/logs/{ProductId}/` |
96+
| macOS | `~/Library/Logs/GeneralUpdate/{ProductId}/` |
97+
98+
## 安全注意事项
99+
100+
- IPC 传输 — 不使用明文 `AutoFallback`, 始终启用加密
101+
- ZIP 包校验 — 启用 `ZipSecurity` 拒绝路径穿越条目
102+
- 签名验证 — 程序集签名: 在 `SetSource` 中提供公钥, 拒绝未签名更新
103+
- AppSecretKey 管理 — 硬编码在客户端是最后手段; 优先从启动参数或环境变量注入

‎.cursor/rules/generalupdate-advanced.mdc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
description: "GeneralUpdate advanced customization — 10+ extension points, 4 IPC providers, Bowl crash daemon, AOT"
3+
globs: ["**/*.cs", "**/*.csproj"]
4+
alwaysApply: false
5+
---
6+
7+
# GeneralUpdate 高级定制
8+
9+
## 10+ 扩展点
10+
Hooks, Strategy, UpdateReporter, DownloadSource, DownloadOrchestrator, DownloadPolicy, DownloadExecutor, DownloadPipeline, SslValidationPolicy, HttpAuthProvider
11+
12+
## 4 种 IPC
13+
EncryptedFile(默认), NamedPipe, SharedMemory, AutoFallback
14+
15+
## Bowl 崩溃守护
16+
Phase1: procdump准备 -> Phase2: 监控 -> Phase3: 检查dump -> Phase4: MiniDump+故障报告+系统诊断+AutoRestore+OnCrash
17+
18+
## AOT/Trim
19+
v5.0+ 支持。SignalR用JSON协议+JsonSerializerContext

‎.cursor/rules/generalupdate-init.mdc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: "GeneralUpdate auto-update integration — Bootstrap config, NuGet packages, manifest setup, dual-project scaffold for .NET applications"
3+
globs: ["**/*.cs", "**/*.csproj", "**/*.json"]
4+
alwaysApply: false
5+
---
6+
7+
# GeneralUpdate 快速集成
8+
9+
## NuGet
10+
- `GeneralUpdate.Core` — 必需。Bootstrap/策略/下载/IPC/事件
11+
- `GeneralUpdate.Differential` — 可选。差分更新
12+
- `GeneralUpdate.Bowl` — 可选。崩溃守护
13+
14+
## 最小集成
15+
SetSource(url, key) -> SetOption(AppType.Client) -> LaunchAsync()
16+
17+
## 4 大更新场景
18+
- None, UpgradeOnly, MainOnly, Both
19+
20+
## manifest.json
21+
MainAppName, UpdateAppName, ProductId, InstallPath, UpdatePath, ClientVersion, UpgradeClientVersion
22+
23+
## 关键警告
24+
- UpgradeApp.exe 必须随首个版本发布（不能自己下载自己）
25+
- Client 和 Upgrade 必须相同 AppSecretKey
26+
- 版本号必须是 4 段式
27+
- manifest ClientVersion 不能为空
28+
29+
## 3 种配置方式
30+
- Minimal: SetSource + manifest.json
31+
- Standard: SetConfig(UpdateRequest) + Option + events
32+
- appsettings: LoadFromConfiguration(config)
33+
34+
## 5 种 HTTP 认证
35+
HMAC(默认), Basic, Bearer, APIKey, 自定义(IHttpAuthProvider)

‎.cursor/rules/generalupdate-strategy.mdc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: "GeneralUpdate update strategies — decision tree, 6 strategies, mixed combinations, platform differences"
3+
globs: ["**/*.cs", "**/*.csproj"]
4+
alwaysApply: false
5+
---
6+
7+
# GeneralUpdate 更新策略
8+
9+
## 决策树
10+
有后端 -> 需要推送? -> SignalR -> 常驻后台? -> 静默 -> 大应用? -> 差分 -> 标准
11+
无后端 -> OSS
12+
13+
## 6 种策略
14+
1. 标准客户端-服务端: 有后端, 中复杂
15+
2. OSS 对象存储: 无后端, 低成本
16+
3. 静默更新: 后台轮询, 退出时更新
17+
4. 差分更新: 增量补丁, 省带宽
18+
5. 跨版本 CVP: 跳中间版本
19+
6. SignalR 推送: 服务端主动
20+
21+
## 混合策略
22+
- OSS+静默: 无服务器+常驻后台
23+
- 标准+差分: 大应用+有服务器
24+
- CVP+链式兜底: 跳过版本+可回退
25+
26+
## 平台差异
27+
Windows: Hash->解压->Patch+Bowl+Drivelution
28+
Linux/macOS: Hash->解压->Patch(无Bowl,需UnixPermissionHooks)

‎.cursor/rules/generalupdate-troubleshoot.mdc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: "GeneralUpdate troubleshooting — 50+ known issues classified by severity C/H/M/L, traced to GitHub/Gitee issues"
3+
globs: ["**/*.cs", "**/*.csproj", "**/*.json"]
4+
alwaysApply: false
5+
---
6+
7+
# GeneralUpdate 故障排查
8+
9+
## 诊断流程
10+
1. NuGet版本一致?
11+
2. manifest正确?
12+
3. UpgradeApp存在?
13+
4. 策略可访问?
14+
5. 日志有异常?
15+
16+
## C级(致命)
17+
C1: 升级没启动 -> UpgradeApp未随主程序发布
18+
C2: Method not found -> NuGet版本不一致
19+
C3: 路径超长 -> 备份嵌套(#501)
20+
C4: IPC暴露 -> AES硬编码
21+
C5: 跨租户泄露 -> 服务端11处漏洞
22+
23+
## H级(高)
24+
H1: 静默不生效 -> ProcessExit不触发(#484)
25+
H2: 无限循环 -> 未WriteBack(#475)
26+
H3: OSS无更新 -> 不区分场景(#485)
27+
28+
## 诊断命令
29+
curl -X POST https://server/Upgrade/Verification -H "Content-Type: application/json" -d '{...}'
30+
cat generalupdate.manifest.json | python3 -m json.tool

‎.cursor/rules/generalupdate-ui.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "GeneralUpdate update UI generation — auto-detect UI framework, generate update windows with real GeneralUpdate.Core progress bindings"
3+
globs: ["**/*.xaml", "**/*.axaml", "**/*.cs", "**/*.csproj"]
4+
alwaysApply: false
5+
---
6+
7+
# GeneralUpdate 更新界面生成
8+
9+
## 框架检测
10+
Semi.Avalonia -> SemiUrsa 模板
11+
LayUI.Wpf -> LayUI 模板
12+
WPFDevelopers -> WPFDevelopers 模板
13+
AntdUI -> AntdUI 模板
14+
Microsoft.Maui -> MAUI 模板
15+
16+
## UI 状态机 (11 种状态)
17+
Idle->Checking->FoundUpdate->Downloading->Paused->DownloadError->Applying->UpgradeProgress->Success->Failed->RollingBack->AlreadyLatest
18+
19+
## 核心桥接: RealDownloadService
20+
将 GeneralUpdate.Core 事件映射到 IDownloadService 接口, 替换 MockDownloadService
21+
22+
## 事件到状态映射
23+
UpdateInfo -> FoundUpdate/AlreadyLatest
24+
MultiDownloadStatistics -> Downloading
25+
MultiDownloadError -> DownloadError
26+
MultiAllDownloadCompleted -> UpgradeProgress -> Success
27+
Exception -> Failed

0 commit comments

Comments
 (0)