nilaoda · caiqingzhi2020 · Dec 14, 2025 · Dec 15, 2025 · Dec 26, 2025 · Dec 26, 2025
diff --git a/docs/专用于本项目的AI prompt.txt b/docs/专用于本项目的AI prompt.txt
@@ -0,0 +1,324 @@
+## AI 智能体操作指南
+### 操作原则
+#### 1. 保守修改原则
+- **优先扩展**而非修改现有功能
+- **保持接口稳定**，内部实现可优化
+- **向后兼容**是最高优先级
+
+#### 2. 调用链保护原则
+- 任何修改前必须分析完整的调用链
+- 禁止破坏关键路径的方法签名
+- 确保跨模块调用的完整性
+
+#### 3. 测试驱动原则
+- 修改前确认测试覆盖
+- 修改后立即运行测试验证
+- 新增功能必须包含相应测试
+
+### 具体操作步骤
+
+#### 步骤1：修改前的分析（必须执行）
+```bash
+# 1. 搜索目标方法的所有调用位置
+grep -r "目标方法名" /workspace/N_m3u8DL-RE-src/src/ --include="*.cs"
+
+# 2. 分析项目依赖关系
+find /workspace/N_m3u8DL-RE-src/src -name "*.csproj" -exec cat {} \;
+
+# 3. 检查接口实现一致性
+grep -r "interface" /workspace/N_m3u8DL-RE-src/src/ --include="*.cs" | grep -i "目标接口"
+```
+
+#### 步骤2：安全修改策略
+```csharp
+// 策略1：使用可选参数保持兼容
+public async Task<bool> ExistingMethod(string requiredParam, string newParam = null)
+
+// 策略2：使用方法重载
+public async Task<bool> ExistingMethod() => ExistingMethod("default");
+public async Task<bool> ExistingMethod(string param) { /* 实现 */ }
+
+// 策略3：创建新方法而非修改旧方法
+public async Task<bool> NewMethodWithImprovement()
+{
+    // 新功能实现
+}
+```
+
+#### 步骤3：修改后的验证（必须执行）
+```bash
+# 1. 编译验证
+dotnet build /workspace/N_m3u8DL-RE-src/src/N_m3u8DL-RE.sln
+
+# 2. 测试验证
+dotnet test /workspace/N_m3u8DL-RE-src/src/N_m3u8DL-RE.Tests
+
+# 3. 功能验证（模拟用户操作）
+dotnet run --project /workspace/N_m3u8DL-RE-src/src/N_m3u8DL-RE --help
+```
+
+### 常见风险场景及应对
+
+#### 风险场景1：方法重命名
+**风险**：调用链断裂，"找不到方法"错误
+**应对**：
+```csharp
+// 错误做法：直接重命名
+public async Task<bool> NewMethodName() // ❌ 破坏调用链
+
+// 正确做法：保持旧方法，标记为过时
+[Obsolete("请使用NewMethodName方法")]
+public async Task<bool> OldMethodName() => NewMethodName();
+public async Task<bool> NewMethodName() { /* 新实现 */ }
+```
+
+#### 风险场景2：参数变更
+**风险**：调用方参数不匹配
+**应对**：
+```csharp
+// 错误做法：强制要求新参数
+public async Task<bool> Method(string newRequiredParam) // ❌
+
+// 正确做法：保持可选参数
+public async Task<bool> Method(string param = null) // ✅
+{
+    param ??= GetDefaultParam();
+    // 实现逻辑
+}
+```
+
+#### 风险场景3：返回类型变更
+**风险**：调用方类型转换错误
+**应对**：
+```csharp
+// 错误做法：改变返回类型
+public async Task<NewResultType> Method() // ❌
+
+// 正确做法：添加新方法
+public async Task<NewResultType> NewMethod() { /* 新实现 */ }
+// 保持旧方法兼容性
+public async Task<bool> Method() => await NewMethod().IsSuccess;
+```
+#### 风险场景4：报错找不到某文件
+//错误做法:手动新建
+//正确做法:文件可能是被重命名,所以要查询相似文件名的文件是否就是要找的某文件. 若还找不到,则从Git历史查询此文件最后出现在哪一次commit并汇报给用户
+## 项目特定约束和限制
+
+### 技术约束
+1. **.NET 9.0限制**：不能使用更高版本的.NET特性
+2. **C# 13.0限制**：语法特性受版本限制
+3. **依赖版本锁定**：System.CommandLine等依赖版本固定
+
+### 架构约束
+1. **模块依赖方向**：只能从高层模块依赖低层模块
+2. **接口稳定性**：公共接口必须保持向后兼容
+3. **数据流方向**：数据必须按照既定流程传递
+
+### 性能约束
+1. **内存使用**：流媒体处理需要控制内存占用
+2. **网络IO**：下载操作需要合理的并发控制
+3. **文件IO**：大文件处理需要优化IO操作
+
+## 最佳实践总结
+
+### 代码修改最佳实践
+1. **分析先行**：修改前全面分析影响范围
+2. **测试驱动**：先写测试，再实现功能
+3. **小步提交**：每次修改保持小范围，便于回滚
+4. **文档更新**：修改后及时更新相关文档
+
+### 调用链保护最佳实践
+1. **接口契约**：严格遵守接口定义
+2. **方法签名**：保持关键方法签名稳定
+3. **异常处理**：完善的错误处理和恢复机制
+4. **日志记录**：详细的调用链日志记录
+
+### 质量保证最佳实践
+1. **编译检查**：每次修改后必须通过编译
+2. **测试覆盖**：确保测试覆盖关键路径
+3. **集成验证**：验证跨模块功能正常
+4. **性能监控**：监控修改对性能的影响
+
+## 紧急情况处理
+
+### 调用链断裂应急方案
+1. **立即回滚**：恢复到修改前的稳定状态
+2. **日志分析**：分析错误日志定位问题
+3. **测试修复**：编写针对性测试修复问题
+4. **逐步发布**：修复后小范围验证再全面发布
+
+### 编译错误处理
+1. **依赖检查**：确认所有依赖项正确引用
+2. **版本兼容**：检查.NET和目标框架版本
+3. **语法验证**：使用IDE工具验证语法正确性
+4. **构建清理**：清理构建缓存重新编译
+
+---
+
+## 最终提醒
+
+**重要提示**：本提示词基于对 N_m3u8DL-RE 项目的深入分析，所有指导原则都旨在保护项目的稳定性和可维护性。在进行任何代码修改时，请务必遵循本提示词中的规范和要求，确保函数调用链的完整性，避免因修改导致的方法引用失效问题。
+
+**记住**：
+一个稳定的调用链比一个新功能更重要！
+默认输入文件/workspace/input.txt 
+默认输出目录mpegts.js/demo/output  
+记住与Git相关命令需要用户确认才能执行
+生成的临时文件or测试文件名要带前缀deletable
+
+# N_m3u8DL-RE 插件系统开发文档
+
+本文档介绍如何为 N_m3u8DL-RE 开发和使用插件系统。
+
+## 1. 插件系统架构设计
+
+插件系统具有以下特点：
+
+- **非侵入性**: 所有插件代码都放在 `extend` 目录中，不会影响主程序的核心代码
+- **可扩展性**: 通过 [IPlugin](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs#L85-L89) 接口可以轻松添加新的插件功能
+- **配置驱动**: 插件行为可以通过 [PluginConfig.json](file:///workspace/N_m3u8DL-RE-src/extend/PluginConfig.json) 配置文件进行管理
+- **事件驱动**: 通过 `OnFileDownloaded` 事件触发插件逻辑
+
+## 2. 核心组件
+
+### PluginManager.cs (插件管理器)
+- 实现了插件的加载、初始化和事件分发功能
+- 支持从配置文件中读取插件设置
+- 提供了统计下载次数的功能
+
+### UASwitcherPlugin.cs (UA切换插件)
+- 实现了每下载一定数量文件切换一次User-Agent的功能
+- 支持从配置文件中读取自定义User-Agent列表
+
+### ProxySwitcherPlugin.cs (代理切换插件)
+- 实现了每下载一定数量文件切换一次代理的功能
+- 通过Clash API控制代理切换
+
+### BatchDownloadPlugin-and-input-output/BatchDownloadPlugin.cs (批量下载插件)
+- 实现了批量下载多个URL的功能
+- 支持从配置文件读取URL列表
+- 自动生成包含原始URL信息的唯一文件名
+- 支持批量进度跟踪和错误处理
+- **配置架构优化**: 直接读取PluginConfig.json，无需中间配置类
+
+### PluginConfig.json (配置文件)
+- 控制各个插件的启用状态和行为参数
+
+## 3. 插件接口规范
+
+所有插件都需要实现 [IPlugin](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs#L85-L89) 接口:
+
+```csharp
+public interface IPlugin
+{
+    void Initialize(PluginConfig? config);
+    void OnFileDownloaded(string filePath, int downloadCount);
+}
+```
+
+- `Initialize`: 插件初始化方法，在程序启动时调用
+- `OnFileDownloaded`: 文件下载完成回调，在每个文件下载完成后调用
+
+## 4. 集成到主程序
+
+插件系统已集成到主程序中：
+
+### SimpleDownloader.cs 集成
+- 在文件下载完成后添加了插件钩子调用
+- 确保无论下载成功还是跳过已存在的文件都会触发插件事件
+
+### N_m3u8DL-RE.csproj 集成
+- 添加了对extend目录中插件文件的引用
+- 确保插件配置文件会被复制到输出目录
+
+### Program.cs 集成
+- 在程序入口点初始化插件管理器
+
+## 5. 设计优势
+
+- **避免冲突**: 所有修改都在extend目录和必要的集成点，与原作者的开发路径完全分离
+- **易于维护**: 插件系统采用模块化设计，便于单独维护和升级
+- **高度可配置**: 通过配置文件可以灵活控制插件的行为
+- **易于扩展**: 可以通过实现[IPlugin](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs#L85-L89)接口轻松添加新功能
+
+## 6. 使用说明
+
+要使用这个插件系统：
+
+1. 确保extend目录中的插件文件被正确编译
+2. 根据需要修改[PluginConfig.json](file:///workspace/N_m3u8DL-RE-src/extend/PluginConfig.json)中的配置
+3. 程序运行时会自动加载启用的插件
+4. 每当一个文件下载完成时，会自动触发相应的插件逻辑
+
+### 批量下载插件使用
+
+要使用批量下载插件：
+
+1. 在[PluginConfig.json](file:///workspace/N_m3u8DL-RE-src/extend/PluginConfig.json)中启用BatchDownload
+2. 准备URL列表文件（默认路径：`extend/BatchDownloadPlugin-and-input-output/input-batch-urls.txt`）
+3. 使用命令行参数 `--batch` 启用批量模式
+4. 指定输出目录：`--save-dir /path/to/output`
+
+**配置架构优化说明**:
+- **统一配置源**: 所有配置直接从PluginConfig.json读取，无需中间配置类
+- **消除冲突**: 解决了配置冲突问题，确保单一配置来源
+- **灵活配置**: 支持直接在PluginConfig.json中修改所有参数
+
+**命令示例**:
+```bash
+dotnet run -- --batch --save-dir /workspace/mpegts.js/demo/output
+```
+
+**输入文件格式**:
+```
+# 注释行以#开头
+https://example1.com/video1.m3u8
+https://example2.com/video2.m3u8
+```
+
+**输出文件命名**:
+批量下载会自动生成包含原始URL信息的唯一文件名，格式为：
+`{URL基础名}_batch{索引}_of_{总数}_{时间戳}.{扩展名}`
+
+## 7. 开发新插件
+
+要开发一个新的插件，需要：
+
+1. 创建新的插件类，实现[IPlugin](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs#L85-L89)接口
+2. 在[PluginConfig.json](file:///workspace/N_m3u8DL-RE-src/extend/PluginConfig.json)中添加插件配置项
+3. 在[PluginManager.cs](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs)的[LoadPlugins](file:///workspace/N_m3u8DL-RE-src/extend/PluginManager.cs#L16-L44)方法中添加插件加载逻辑
+4. 编译并测试插件功能
+
+## 8. 配置文件说明
+
+[PluginConfig.json](file:///workspace/N_m3u8DL-RE-src/extend/PluginConfig.json) 是插件系统的配置文件，支持以下配置项：
+
+```json
+{
+  "UASwitcher": {
+    "Enabled": true,
+    "UserAgents": [
+      "UA1",
+      "UA2",
+      "UA3"
+    ]
+  },
+  "ProxySwitcher": {
+    "Enabled": true,
+    "ClashApiUrl": "http://127.0.0.1:9090",
+    "SwitchInterval": 3
+  },
+  "BatchDownload": {
+    "Enabled": true,
+    "CreateSubdirectories": false,
+    "MaxConcurrency": 3
+  }
+}
+```
+
+- `Enabled`: 控制插件是否启用
+- `UserAgents`: UA切换插件使用的User-Agent列表
+- `ClashApiUrl`: 代理切换插件使用的Clash API地址
+- `SwitchInterval`: 切换间隔（每下载多少个文件切换一次）
+- `CreateSubdirectories`: 批量下载插件是否为每个URL创建子目录
+- `MaxConcurrency`: 批量下载插件的最大并发数（预留功能）