From 428538b64b477ec620b0ecf11adb7a24633584c4 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Mon, 22 Sep 2025 18:39:25 +0800 Subject: [PATCH 01/14] Handle temperature for gpt-5 models in HTTP client Updated KoalaHttpClientHandler to also remove the 'temperature' parameter for models starting with 'gpt-5', in addition to those starting with 'o'. This ensures correct request formatting for these model types. --- src/KoalaWiki/KoalaHttpClientHander.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/KoalaWiki/KoalaHttpClientHander.cs b/src/KoalaWiki/KoalaHttpClientHander.cs index bb1d52f1..dff99a98 100644 --- a/src/KoalaWiki/KoalaHttpClientHander.cs +++ b/src/KoalaWiki/KoalaHttpClientHander.cs @@ -30,7 +30,7 @@ protected override async Task SendAsync( } // GPT o系列不能传递温度 - if (model.StartsWith("o")) + if (model.StartsWith("o") || model.StartsWith("gpt-5")) { json.Remove("temperature"); } From 35e492756b391f3a7bbb01f61bdf647ea81bd192 Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Tue, 23 Sep 2025 02:02:58 +0800 Subject: [PATCH 02/14] Improve async handling and add retry logic to services Added ConfigureAwait(false) to async calls for better context management and improved performance. Enhanced KoalaHttpClientHandler with retry logic for HTTP requests. Refactored document generation and catalogue services to streamline kernel usage and document refinement. Removed unused code and improved error handling throughout the pipeline. --- src/KoalaWiki/BackendService/WarehouseTask.cs | 8 +- src/KoalaWiki/KernelFactory.cs | 38 +- src/KoalaWiki/KoalaHttpClientHander.cs | 50 ++- .../DocumentPending/DocumentPendingService.cs | 391 +++++++++--------- .../GenerateThinkCatalogueService.cs | 39 +- .../Steps/DocumentStructureGenerationStep.cs | 2 +- src/KoalaWiki/Program.cs | 3 - src/KoalaWiki/Prompts/PromptExtensions.cs | 1 - 8 files changed, 292 insertions(+), 240 deletions(-) diff --git a/src/KoalaWiki/BackendService/WarehouseTask.cs b/src/KoalaWiki/BackendService/WarehouseTask.cs index 822c1862..e7cd08e1 100644 --- a/src/KoalaWiki/BackendService/WarehouseTask.cs +++ b/src/KoalaWiki/BackendService/WarehouseTask.cs @@ -98,6 +98,10 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken) { document = await dbContext.Documents.FirstAsync(x => x.WarehouseId == value.Id, stoppingToken); + + document.GitPath = info.LocalPath; + document.LastUpdate = DateTime.UtcNow; + document.Status = WarehouseStatus.Processing; logger.LogInformation("获取现有文档记录，文档ID：{Id}", document.Id); } else @@ -122,7 +126,7 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken) // 调用文档处理服务，其Activity将作为当前Activity的子Activity await documentsService.HandleAsync(document, value, dbContext, - value.Address.Replace(".git", string.Empty)); + value.Address.Replace(".git", string.Empty)).ConfigureAwait(false); } else if (value?.Type?.Equals("file", StringComparison.OrdinalIgnoreCase) == true) { @@ -162,7 +166,7 @@ await documentsService.HandleAsync(document, value, dbContext, // 调用文档处理服务，其Activity将作为当前Activity的子Activity await documentsService.HandleAsync(document, value, dbContext, - value.Address.Replace(".git", string.Empty)); + value.Address.Replace(".git", string.Empty)).ConfigureAwait(false); } else { diff --git a/src/KoalaWiki/KernelFactory.cs b/src/KoalaWiki/KernelFactory.cs index d7b3ff16..9097bbb9 100644 --- a/src/KoalaWiki/KernelFactory.cs +++ b/src/KoalaWiki/KernelFactory.cs @@ -46,15 +46,13 @@ public static Kernel GetKernel(string chatEndpoint, kernelBuilder.AddOpenAIChatCompletion(model, new Uri(chatEndpoint), apiKey, httpClient: new HttpClient(new KoalaHttpClientHandler() { - //添加重试试 - AllowAutoRedirect = true, - MaxAutomaticRedirections = 5, - MaxConnectionsPerServer = 200, - AutomaticDecompression = System.Net.DecompressionMethods.GZip | System.Net.DecompressionMethods.Brotli | System.Net.DecompressionMethods.Deflate | System.Net.DecompressionMethods.None + AutomaticDecompression = System.Net.DecompressionMethods.GZip | + System.Net.DecompressionMethods.Brotli | + System.Net.DecompressionMethods.Deflate | + System.Net.DecompressionMethods.None }) { - // 添加重试 - Timeout = TimeSpan.FromSeconds(240), + Timeout = TimeSpan.FromSeconds(60), }); } else if (OpenAIOptions.ModelProvider.Equals("AzureOpenAI", StringComparison.OrdinalIgnoreCase)) @@ -62,14 +60,13 @@ public static Kernel GetKernel(string chatEndpoint, kernelBuilder.AddAzureOpenAIChatCompletion(model, chatEndpoint, apiKey, httpClient: new HttpClient( new KoalaHttpClientHandler() { - //添加重试试 - AllowAutoRedirect = true, - MaxAutomaticRedirections = 5, - MaxConnectionsPerServer = 200, + AutomaticDecompression = System.Net.DecompressionMethods.GZip | + System.Net.DecompressionMethods.Brotli | + System.Net.DecompressionMethods.Deflate | + System.Net.DecompressionMethods.None }) { - // 添加重试 - Timeout = TimeSpan.FromSeconds(16000), + Timeout = TimeSpan.FromSeconds(60), }); } else if (OpenAIOptions.ModelProvider.Equals("Anthropic", StringComparison.OrdinalIgnoreCase)) @@ -77,14 +74,13 @@ public static Kernel GetKernel(string chatEndpoint, kernelBuilder.AddAnthropicChatCompletion(model, apiKey, httpClient: new HttpClient( new KoalaHttpClientHandler() { - //添加重试试 - AllowAutoRedirect = true, - MaxAutomaticRedirections = 5, - MaxConnectionsPerServer = 200, + AutomaticDecompression = System.Net.DecompressionMethods.GZip | + System.Net.DecompressionMethods.Brotli | + System.Net.DecompressionMethods.Deflate | + System.Net.DecompressionMethods.None }) { - // 添加重试 - Timeout = TimeSpan.FromSeconds(16000), + Timeout = TimeSpan.FromSeconds(60), }); } else @@ -119,10 +115,10 @@ public static Kernel GetKernel(string chatEndpoint, kernelBuilderAction?.Invoke(kernelBuilder); var kernel = kernelBuilder.Build(); - + activity?.SetStatus(ActivityStatusCode.Ok); activity?.SetTag("kernel.created", true); return kernel; } -} +} \ No newline at end of file diff --git a/src/KoalaWiki/KoalaHttpClientHander.cs b/src/KoalaWiki/KoalaHttpClientHander.cs index dff99a98..ce4fc5b6 100644 --- a/src/KoalaWiki/KoalaHttpClientHander.cs +++ b/src/KoalaWiki/KoalaHttpClientHander.cs @@ -63,10 +63,54 @@ protected override async Task SendAsync( System.Text.Encoding.UTF8, "application/json"); // 1. 启动计时 + HttpResponseMessage response = null!; var stopwatch = Stopwatch.StartNew(); - // 2. 发送请求 - var response = await base.SendAsync(request, cancellationToken) - .ConfigureAwait(false); + for (int i = 0; i < 3; i++) + { + // 2. 发送请求 + try + { + response = await base.SendAsync(request, cancellationToken) + .ConfigureAwait(false); + if (response.IsSuccessStatusCode) + { + // 成功返回响应 + break; + } + else + { + // 如果是400系列错误，不重试 + if ((int)response.StatusCode >= 400 && (int)response.StatusCode < 500) + { + break; + } + var errorContent = await response.Content.ReadAsStringAsync(cancellationToken); + Log.Logger.Warning("HTTP request failed, attempt {Attempt}: {StatusCode} {ErrorMessage}", + i + 1, (int)response.StatusCode, errorContent); + if (i == 2) + { + // 最后一次失败，抛出异常 + throw new HttpRequestException( + $"Request failed with status code {(int)response.StatusCode}: {errorContent}"); + } + + await Task.Delay(3000 * i, cancellationToken); // 等待一秒后重试 + continue; + } + } + catch (Exception e) + { + Log.Logger.Warning("HTTP request failed, attempt {Attempt}: {ErrorMessage}", i + 1, e.Message); + if (i == 2) + { + throw; // 最后一次失败，抛出异常 + } + + await Task.Delay(3000, cancellationToken); // 等待一秒后重试 + continue; + } + } + // 3. 停止计时 stopwatch.Stop(); diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index 7504d82d..7b1cee2a 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -91,7 +91,7 @@ public static async Task HandlePendingDocumentsAsync(List docum try { - var (catalog, fileItem, files) = await completedTask; + var (catalog, fileItem, files) = await completedTask.ConfigureAwait(false); if (fileItem == null) { @@ -145,33 +145,215 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) const int retries = 5; var files = new List(); - while (true) + for (var i = 0; i < 3; i++) { try { if (semaphore != null) - { await semaphore.WaitAsync(); - } Log.Logger.Information("处理仓库；{path} ,处理标题：{name}", path, catalog.Name); - var fileItem = await ProcessCatalogueItems(catalog, catalogue, gitRepository, branch, path, - classifyType, files); - // ProcessCatalogueItems内部已经进行了质量验证，这里只做最终检查 - if (fileItem == null) + + DocumentContext.DocumentStore = new DocumentStore(); + + var docs = new DocsFunction(); + // 为每个文档处理创建独立的Kernel实例，避免状态管理冲突 + var documentKernel = KernelFactory.GetKernel( + OpenAIOptions.Endpoint, + OpenAIOptions.ChatApiKey, + path, + OpenAIOptions.ChatModel, + false, // 文档生成不需要代码分析功能 + files, (builder => { builder.Plugins.AddFromObject(docs, "Docs"); }) + ); + + var chat = documentKernel.Services.GetService(); + + string prompt = await + GetDocumentPendingPrompt(classifyType, catalogue, gitRepository, branch, catalog.Name, + catalog.Prompt); + + var history = new ChatHistory(); + + history.AddSystemEnhance(); + + var contents = new ChatMessageContentItemCollection + { + new TextContent(prompt), + new TextContent( + $""" + + For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. + Note: The repository's directory structure has been provided in . Please utilize the provided structure directly for file navigation and reading operations, rather than relying on glob patterns or filesystem traversal methods. + Below is an example of the directory structure of the warehouse, where /D represents a directory and /F represents a file: + server/D + src/D + Main/F + web/D + components/D + Header.tsx/F + + + {Prompt.Language} + + """) + }; + + contents.AddDocsGenerateSystemReminder(); + history.AddUserMessage(contents); + + var settings = new OpenAIPromptExecutionSettings() + { + ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions, + MaxTokens = DocumentsHelper.GetMaxTokens(OpenAIOptions.ChatModel), + }; + + int count = 1; + int inputTokenCount = 0; + int outputTokenCount = 0; + + reset: + + await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, documentKernel)) { - throw new InvalidOperationException("文档生成失败：返回内容为空"); + switch (item.InnerContent) + { + case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: + inputTokenCount += content.Usage.InputTokenCount; + outputTokenCount += content.Usage.OutputTokenCount; + break; + case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: + Console.Write("[Tool Call]"); + break; + case StreamingChatCompletionUpdate value: + Console.Write(value.ContentUpdate.FirstOrDefault()?.Text); + break; + } } + if (string.IsNullOrEmpty(docs.Content) && count < 5) + { + count++; + goto reset; + } + + + if (DocumentOptions.RefineAndEnhanceQuality) + { + try + { + var refineContents = new ChatMessageContentItemCollection + { + new TextContent( + """ + Please refine and enhance the previous documentation content while maintaining its structure and approach. Focus on: + + **Enhancement Areas:** + - Deepen existing architectural explanations with more technical detail + - Expand code analysis with additional insights from the repository + - Strengthen existing Mermaid diagrams with more comprehensive representations + - Improve clarity and readability of existing explanations + - Add more specific code references and examples where appropriate + - Enhance existing sections with additional technical depth + + **Quality Standards:** + - Maintain the 90-10 description-to-code ratio established in the original + - Ensure all additions are evidence-based from the actual code files + - Preserve the Microsoft documentation style approach + - Enhance conceptual understanding through improved explanations + - Strengthen the progressive learning structure + + **Refinement Protocol (tools only):** + 1) Use Docs.Read to review the current document thoroughly. + 2) Plan improvements that preserve structure and voice. + 3) Apply multiple small, precise Docs.MultiEdit operations to improve clarity, add missing details, and strengthen diagrams/citations. + 4) After each edit, re-run Docs.Read to verify changes and continue iterating (at least 2–3 passes). + 5) Avoid full overwrites; prefer targeted edits that enhance existing content. + + Build upon the solid foundation that exists to create even more comprehensive and valuable documentation. + """), + new TextContent( + """ + + CRITICAL: You are now in document refinement phase. Your task is to ENHANCE and IMPROVE the EXISTING documentation content that was just generated, NOT to create completely new content. + + MANDATORY REQUIREMENTS: + 1. PRESERVE the original document structure and organization + 2. ENHANCE existing explanations with more depth and clarity + 3. IMPROVE technical accuracy and completeness based on actual code analysis + 4. EXPAND existing sections with more detailed architectural analysis + 5. REFINE language for better readability while maintaining technical precision + 6. STRENGTHEN existing Mermaid diagrams or add complementary ones + 7. ENSURE all enhancements are based on the code files analyzed in the original generation + + FORBIDDEN ACTIONS: + - Do NOT restructure or reorganize the document completely + - Do NOT remove existing sections or content + - Do NOT add content not based on the analyzed code files + - Do NOT change the fundamental approach or style established in the original + + Your goal is to take the good foundation that exists and make it BETTER, MORE DETAILED, and MORE COMPREHENSIVE while preserving its core structure and insights. + + """), + new TextContent(Prompt.Language) + }; + history.AddUserMessage(refineContents); + + int reset1 = 1; + reset1: + + await chat.GetChatMessageContentAsync(history, settings, documentKernel); + + if (string.IsNullOrEmpty(docs.Content) && reset1 < 3) + { + reset1++; + goto reset1; + } + + // 检查精炼后的内容是否有效 + if (!string.IsNullOrWhiteSpace(docs.Content)) + { + Log.Logger.Information("文档精炼成功，文档：{name}", catalog.Name); + } + else + { + Log.Logger.Warning("文档精炼后内容为空，使用原始内容，文档：{name}", catalog.Name); + } + } + catch (Exception ex) + { + Log.Logger.Error("文档精炼失败，使用原始内容，文档：{name}，错误：{error}", catalog.Name, ex.Message); + } + } + + + var fileItem = new DocumentFileItem() + { + Content = docs.Content, + DocumentCatalogId = catalog.Id, + Description = string.Empty, + Extra = new Dictionary(), + Metadata = new Dictionary(), + Source = [], + CommentCount = 0, + RequestToken = 0, + CreatedAt = DateTime.Now, + Id = Guid.NewGuid().ToString("N"), + ResponseToken = 0, + Size = 0, + Title = catalog.Name, + }; + Log.Logger.Information("处理仓库；{path} ,处理标题：{name} 完成！", path, catalog.Name); + semaphore?.Release(); return (catalog, fileItem, files); } catch (Exception ex) { - Log.Logger.Error("处理仓库；{path} ,处理标题：{name} 失败:{ex}", path, catalog.Name, ex.ToString()); semaphore?.Release(); + Log.Logger.Error("处理仓库；{path} ,处理标题：{name} 失败:{ex}", path, catalog.Name, ex.ToString()); retryCount++; if (retryCount >= retries) @@ -202,197 +384,12 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) } } } - } - - /// - /// 处理每一个标题产生文件内容 - /// - private static async Task ProcessCatalogueItems(DocumentCatalog catalog, - string codeFiles, - string gitRepository, string branch, string path, ClassifyType? classify, List files) - { - DocumentContext.DocumentStore = new DocumentStore(); - var docs = new DocsFunction(); - // 为每个文档处理创建独立的Kernel实例，避免状态管理冲突 - var documentKernel = KernelFactory.GetKernel( - OpenAIOptions.Endpoint, - OpenAIOptions.ChatApiKey, - path, - OpenAIOptions.ChatModel, - false, // 文档生成不需要代码分析功能 - files, (builder => { builder.Plugins.AddFromObject(docs, "Docs"); }) - ); - - var chat = documentKernel.Services.GetService(); - - string prompt = await - GetDocumentPendingPrompt(classify, codeFiles, gitRepository, branch, catalog.Name, catalog.Prompt); - - var history = new ChatHistory(); - - history.AddSystemEnhance(); - - var contents = new ChatMessageContentItemCollection - { - new TextContent(prompt), - new TextContent( - $""" - - For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. - Note: The repository's directory structure has been provided in . Please utilize the provided structure directly for file navigation and reading operations, rather than relying on glob patterns or filesystem traversal methods. - {Prompt.Language} - - """) - }; - - contents.AddDocsGenerateSystemReminder(); - history.AddUserMessage(contents); - - var sr = new StringBuilder(); - - var settings = new OpenAIPromptExecutionSettings() - { - ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions, - MaxTokens = DocumentsHelper.GetMaxTokens(OpenAIOptions.ChatModel), - }; - - int count = 1; - int inputTokenCount = 0; - int outputTokenCount = 0; - - reset: - - await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, documentKernel)) - { - if (item.InnerContent is StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content) - { - inputTokenCount += content.Usage.InputTokenCount; - outputTokenCount += content.Usage.OutputTokenCount; - } - } - - if (string.IsNullOrEmpty(docs.Content) && count < 5) - { - count++; - goto reset; - } - - - if (DocumentOptions.RefineAndEnhanceQuality) - { - try - { - var refineContents = new ChatMessageContentItemCollection - { - new TextContent( - """ - Please refine and enhance the previous documentation content while maintaining its structure and approach. Focus on: - - **Enhancement Areas:** - - Deepen existing architectural explanations with more technical detail - - Expand code analysis with additional insights from the repository - - Strengthen existing Mermaid diagrams with more comprehensive representations - - Improve clarity and readability of existing explanations - - Add more specific code references and examples where appropriate - - Enhance existing sections with additional technical depth - - **Quality Standards:** - - Maintain the 90-10 description-to-code ratio established in the original - - Ensure all additions are evidence-based from the actual code files - - Preserve the Microsoft documentation style approach - - Enhance conceptual understanding through improved explanations - - Strengthen the progressive learning structure - - **Refinement Protocol (tools only):** - 1) Use Docs.Read to review the current document thoroughly. - 2) Plan improvements that preserve structure and voice. - 3) Apply multiple small, precise Docs.MultiEdit operations to improve clarity, add missing details, and strengthen diagrams/citations. - 4) After each edit, re-run Docs.Read to verify changes and continue iterating (at least 2–3 passes). - 5) Avoid full overwrites; prefer targeted edits that enhance existing content. - - Build upon the solid foundation that exists to create even more comprehensive and valuable documentation. - """), - new TextContent( - """ - - CRITICAL: You are now in document refinement phase. Your task is to ENHANCE and IMPROVE the EXISTING documentation content that was just generated, NOT to create completely new content. - - MANDATORY REQUIREMENTS: - 1. PRESERVE the original document structure and organization - 2. ENHANCE existing explanations with more depth and clarity - 3. IMPROVE technical accuracy and completeness based on actual code analysis - 4. EXPAND existing sections with more detailed architectural analysis - 5. REFINE language for better readability while maintaining technical precision - 6. STRENGTHEN existing Mermaid diagrams or add complementary ones - 7. ENSURE all enhancements are based on the code files analyzed in the original generation - - FORBIDDEN ACTIONS: - - Do NOT restructure or reorganize the document completely - - Do NOT remove existing sections or content - - Do NOT add content not based on the analyzed code files - - Do NOT change the fundamental approach or style established in the original - - Your goal is to take the good foundation that exists and make it BETTER, MORE DETAILED, and MORE COMPREHENSIVE while preserving its core structure and insights. - - """), - new TextContent(Prompt.Language) - }; - history.AddUserMessage(refineContents); - - var refinedContent = new StringBuilder(); - int reset1 = 1; - reset1: - - await chat.GetChatMessageContentAsync(history, settings, documentKernel); - - if (string.IsNullOrEmpty(docs.Content) && reset1 < 3) - { - reset1++; - goto reset1; - } - - // 检查精炼后的内容是否有效 - if (!string.IsNullOrWhiteSpace(refinedContent.ToString())) - { - sr.Clear(); - sr.Append(refinedContent.ToString()); - Log.Logger.Information("文档精炼成功，文档：{name}", catalog.Name); - } - else - { - Log.Logger.Warning("文档精炼后内容为空，使用原始内容，文档：{name}", catalog.Name); - } - } - catch (Exception ex) - { - Log.Logger.Error("文档精炼失败，使用原始内容，文档：{name}，错误：{error}", catalog.Name, ex.Message); - // sr已经包含原始内容，无需额外操作 - } - } - - - var fileItem = new DocumentFileItem() - { - Content = docs.Content, - DocumentCatalogId = catalog.Id, - Description = string.Empty, - Extra = new Dictionary(), - Metadata = new Dictionary(), - Source = [], - CommentCount = 0, - RequestToken = 0, - CreatedAt = DateTime.Now, - Id = Guid.NewGuid().ToString("N"), - ResponseToken = 0, - Size = 0, - Title = catalog.Name, - }; - - return fileItem; + throw new Exception("处理失败，重试多次仍未成功: " + catalog.Name); } + /// /// 计算文档质量评分 /// diff --git a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs index 0d5db4c1..3f4bd28b 100644 --- a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs +++ b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs @@ -41,7 +41,7 @@ private enum ErrorType try { var result = - await ExecuteSingleAttempt(path, catalogue, classify, retryCount); + await ExecuteSingleAttempt(path, catalogue, classify, retryCount).ConfigureAwait(false); if (result != null) { @@ -117,38 +117,45 @@ private enum ErrorType - MANDATORY: Always perform PARALLEL File.Read calls — batch multiple files in a SINGLE message for maximum efficiency - CRITICAL: Read MULTIPLE files simultaneously in one operation - PROHIBITED: Sequential one-by-one file reads (inefficient and wastes context capacity) - + **EDITING OPERATION LIMITS** - HARD LIMIT: Maximum of 3 editing operations total (catalog.MultiEdit only) - PRIORITY: Maximize each catalog.MultiEdit operation by bundling ALL related changes across multiple files - STRATEGIC PLANNING: Consolidate all modifications into minimal MultiEdit operations to stay within the limit - Use catalog.Write **only once** for initial creation or full rebuild (counts as initial structure creation, not part of the 3 edits) - Always verify content before further changes using catalog.Read (Reads do NOT count toward limit) - + **CRITICAL MULTIEDIT BEST PRACTICES** - MAXIMIZE EFFICIENCY: Each MultiEdit should target multiple distinct sections across files - AVOID CONFLICTS: Never edit overlapping or identical content regions within the same MultiEdit operation - UNIQUE TARGETS: Ensure each edit instruction addresses a completely different section or file - BATCH STRATEGY: Group all necessary changes by proximity and relevance, but maintain clear separation between edit targets - + **RECOMMENDED EDITING SEQUENCE** 1. catalog.Write (one-time full structure creation) 2. catalog.MultiEdit with maximum parallel changes (counts toward 3-operation limit) 3. Use catalog.Read after each MultiEdit to verify success before next operation 4. Remaining MultiEdit operations for any missed changes - - + + ## Execution steps requirements: 1. Before performing any other operations, you must first invoke the 'agent-think' tool to plan the analytical steps. This is a necessary step for completing each research task. 2. Then, the code structure provided in the code_file must be utilized by calling file.Read to read the code for in-depth analysis, and then use catalog.Write to write the results of the analysis into the catalog directory. 3. If necessary, some parts that need to be optimized can be edited through catalog.MultiEdit. - + For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. The repository's directory structure has been provided in . Please utilize the provided structure directly for file navigation and reading operations, rather than relying on glob patterns or filesystem traversal methods. - + Below is an example of the directory structure of the warehouse, where /D represents a directory and /F represents a file: + server/D + src/D + Main/F + web/D + components/D + Header.tsx/F + {Prompt.Language} - + """), new TextContent(Prompt.Language) @@ -183,10 +190,18 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation // 流式获取响应 await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, analysisModel)) { - if (item.InnerContent is StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content) + switch (item.InnerContent) { - inputTokenCount += content.Usage.InputTokenCount; - outputTokenCount += content.Usage.OutputTokenCount; + case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: + inputTokenCount += content.Usage.InputTokenCount; + outputTokenCount += content.Usage.OutputTokenCount; + break; + case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: + Console.Write("[Tool Call]"); + break; + case StreamingChatCompletionUpdate value: + Console.Write(value.ContentUpdate.FirstOrDefault()?.Text); + break; } } diff --git a/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/DocumentStructureGenerationStep.cs b/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/DocumentStructureGenerationStep.cs index 5ee248c5..e0960ea0 100644 --- a/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/DocumentStructureGenerationStep.cs +++ b/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/DocumentStructureGenerationStep.cs @@ -24,7 +24,7 @@ public override async Task ExecuteAsync(DocumentProce context.Document.GitPath, context.Catalogue ?? string.Empty, context.Warehouse, - context.Classification); + context.Classification).ConfigureAwait(false); var documentCatalogs = new List(); diff --git a/src/KoalaWiki/Program.cs b/src/KoalaWiki/Program.cs index 64ecc1a1..10ddf575 100644 --- a/src/KoalaWiki/Program.cs +++ b/src/KoalaWiki/Program.cs @@ -3,11 +3,8 @@ using KoalaWiki.Generate; using KoalaWiki.KoalaWarehouse.Extensions; using KoalaWiki.Mem0; -using KoalaWiki.Options; -using KoalaWiki.Services; using KoalaWiki.Services.Feishu.Feishu; using Microsoft.AspNetCore.StaticFiles; -using OpenDeepWiki.CodeFoundation; AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true); diff --git a/src/KoalaWiki/Prompts/PromptExtensions.cs b/src/KoalaWiki/Prompts/PromptExtensions.cs index 11d8e748..459861c7 100644 --- a/src/KoalaWiki/Prompts/PromptExtensions.cs +++ b/src/KoalaWiki/Prompts/PromptExtensions.cs @@ -59,7 +59,6 @@ public static ChatHistory AddSystemEnhance(this ChatHistory chatHistory) - NEVER assume that a given library is available, even if it is well known. Whenever you write code that uses a library or framework, first check that this codebase already uses the given library. For example, you might look at neighboring files, or check the package.json (or cargo.toml, and so on depending on the language). - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to the repository. - # Code style - IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked From e3fbfa52281122329030a6277a8e539ef67f7884 Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Tue, 23 Sep 2025 10:10:39 +0800 Subject: [PATCH 03/14] feat: add Wiki feature toggle and update background service behavior --- .../KoalaWarehouse/DocumentPending/DocumentPendingService.cs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index 7b1cee2a..b85f55ca 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -211,10 +211,11 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) int count = 1; int inputTokenCount = 0; int outputTokenCount = 0; + var token = new CancellationTokenSource(TimeSpan.FromSeconds(1800)); // 每个文档处理最长30分钟 reset: - await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, documentKernel)) + await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, documentKernel, token.Token)) { switch (item.InnerContent) { From 3c4d50c9cdcbe824df60dca12c8a313383eb292b Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Tue, 23 Sep 2025 11:02:30 +0800 Subject: [PATCH 04/14] feat: implement retry logic and timeout handling for streaming chat responses --- .../DocumentPending/DocumentPendingService.cs | 138 ++++++++++++++++-- .../GenerateThinkCatalogueService.cs | 74 ++++++++-- 2 files changed, 182 insertions(+), 30 deletions(-) diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index b85f55ca..a3d3c7f9 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -193,7 +193,6 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) components/D Header.tsx/F - {Prompt.Language} """) @@ -207,29 +206,138 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions, MaxTokens = DocumentsHelper.GetMaxTokens(OpenAIOptions.ChatModel), }; - int count = 1; int inputTokenCount = 0; int outputTokenCount = 0; - var token = new CancellationTokenSource(TimeSpan.FromSeconds(1800)); // 每个文档处理最长30分钟 + int maxRetries = 3; + CancellationTokenSource token = null; reset: - await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, documentKernel, token.Token)) + try { - switch (item.InnerContent) + // 创建新的取消令牌（每次重试都重新创建） + token?.Dispose(); + token = new CancellationTokenSource(TimeSpan.FromMinutes(10)); // 30分钟超时 + + Console.WriteLine($"开始处理文档 (尝试 {count}/{maxRetries + 1})，超时设置: 30分钟"); + + try { - case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: - inputTokenCount += content.Usage.InputTokenCount; - outputTokenCount += content.Usage.OutputTokenCount; - break; - case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: - Console.Write("[Tool Call]"); - break; - case StreamingChatCompletionUpdate value: - Console.Write(value.ContentUpdate.FirstOrDefault()?.Text); - break; + var hasReceivedContent = false; + var lastActivityTime = DateTime.UtcNow; + + await foreach (var item in chat.GetStreamingChatMessageContentsAsync( + history, + settings, + documentKernel, + token.Token).ConfigureAwait(false)) + { + // 检查是否被取消 + token.Token.ThrowIfCancellationRequested(); + + // 更新最后活动时间 + lastActivityTime = DateTime.UtcNow; + hasReceivedContent = true; + + switch (item.InnerContent) + { + case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: + inputTokenCount += content.Usage.InputTokenCount; + outputTokenCount += content.Usage.OutputTokenCount; + Console.WriteLine($"[Token统计] 输入: {inputTokenCount}, 输出: {outputTokenCount}"); + break; + + case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: + Console.Write("[Tool Call]"); + break; + + case StreamingChatCompletionUpdate value: + var text = value.ContentUpdate.FirstOrDefault()?.Text; + if (!string.IsNullOrEmpty(text)) + { + Console.Write(text); + } + + break; + + default: + // 记录未知的内容类型用于调试 + Console.WriteLine($"[DEBUG] 未处理的内容类型: {item.InnerContent?.GetType().Name}"); + break; + } + } + + // 处理完成 + Console.WriteLine($"\n文档处理完成! 最终Token统计 - 输入: {inputTokenCount}, 输出: {outputTokenCount}"); + + // 检查是否实际接收到了内容 + if (!hasReceivedContent) + { + Console.WriteLine("警告: 没有接收到任何流式内容"); + } } + catch (OperationCanceledException) when (token.Token.IsCancellationRequested) + { + Console.WriteLine("操作被取消 (超时或手动取消)"); + + count++; + if (count <= maxRetries) + { + Console.WriteLine($"正在重试... ({count}/{maxRetries})"); + + // 指数退避延迟 + var delayMs = Math.Min(1000 * (int)Math.Pow(2, count - 1), 10000); // 最大10秒 + await Task.Delay(delayMs, CancellationToken.None); + + goto reset; + } + else + { + Console.WriteLine("已达到最大重试次数，处理失败"); + throw new TimeoutException($"文档处理在 {maxRetries} 次重试后仍然超时"); + } + } + catch (HttpRequestException httpEx) + { + Console.WriteLine($"网络错误: {httpEx.Message}"); + + count++; + if (count <= maxRetries) + { + Console.WriteLine($"网络错误，正在重试... ({count}/{maxRetries})"); + + // 网络错误时增加延迟 + await Task.Delay(3000 * count, CancellationToken.None); + goto reset; + } + + Console.WriteLine("网络错误重试失败"); + throw; + } + catch (Exception ex) + { + Console.WriteLine($"处理流式响应时发生未知错误: {ex.Message}"); + Console.WriteLine($"异常类型: {ex.GetType().Name}"); + Console.WriteLine($"堆栈跟踪: {ex.StackTrace}"); + + // 对于未知错误，也可以尝试重试一次 + count++; + if (count <= maxRetries) + { + Console.WriteLine($"未知错误，尝试重试... ({count}/{maxRetries})"); + await Task.Delay(5000, CancellationToken.None); // 5秒延迟 + goto reset; + } + + throw; // 重新抛出异常 + } + } + finally + { + // 确保资源被正确释放 + token?.Dispose(); + Console.WriteLine("资源清理完成"); } if (string.IsNullOrEmpty(docs.Content) && count < 5) diff --git a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs index 3f4bd28b..8ca13625 100644 --- a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs +++ b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs @@ -182,28 +182,72 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation }; int retry = 1; - var inputTokenCount = 0; var outputTokenCount = 0; + // 添加超时控制 + var cts = new CancellationTokenSource(TimeSpan.FromMinutes(10)); + retry: - // 流式获取响应 - await foreach (var item in chat.GetStreamingChatMessageContentsAsync(history, settings, analysisModel)) + try { - switch (item.InnerContent) + // 流式获取响应 - 添加取消令牌和异常处理 + await foreach (var item in chat.GetStreamingChatMessageContentsAsync( + history, + settings, + analysisModel, + cts.Token).ConfigureAwait(false)) { - case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: - inputTokenCount += content.Usage.InputTokenCount; - outputTokenCount += content.Usage.OutputTokenCount; - break; - case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: - Console.Write("[Tool Call]"); - break; - case StreamingChatCompletionUpdate value: - Console.Write(value.ContentUpdate.FirstOrDefault()?.Text); - break; + // 定期检查取消 + cts.Token.ThrowIfCancellationRequested(); + + switch (item.InnerContent) + { + case StreamingChatCompletionUpdate { Usage.InputTokenCount: > 0 } content: + inputTokenCount += content.Usage.InputTokenCount; + outputTokenCount += content.Usage.OutputTokenCount; + break; + + case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: + Console.Write("[Tool Call]"); + break; + + case StreamingChatCompletionUpdate value: + var text = value.ContentUpdate.FirstOrDefault()?.Text; + if (!string.IsNullOrEmpty(text)) + { + Console.Write(text); + } + + break; + } } } + catch (OperationCanceledException) when (cts.Token.IsCancellationRequested) + { + retry++; + if (retry <= 3) + { + Console.WriteLine($"超时，正在重试 ({retry}/3)..."); + await Task.Delay(2000, CancellationToken.None); + + // 正确地重置超时令牌 + cts.Dispose(); + cts = new CancellationTokenSource(TimeSpan.FromMinutes(5)); // 重新赋值给cts + goto retry; + } + + throw new TimeoutException("流式处理超时"); + } + catch (Exception ex) + { + Console.WriteLine($"流式处理错误: {ex.Message}"); + throw; + } + finally + { + cts?.Dispose(); // 确保资源被释放 + } // Prefer tool-stored JSON when available if (!string.IsNullOrWhiteSpace(catalogueTool.Content)) @@ -219,7 +263,7 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation else { retry++; - if (retry > 5) + if (retry > 3) { throw new Exception("AI生成目录的时候重复多次响应空内容"); } From 7bcf6547eab3ba20001cd848f2f001778077a61b Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Wed, 24 Sep 2025 17:32:09 +0800 Subject: [PATCH 05/14] refactor: remove unused using directives and clean up code --- .claude/settings.local.json | 15 +- Directory.Build.props | 4 +- Directory.Packages.props | 6 +- src/KoalaWiki.AppHost/Program.cs | 6 +- .../WarehouseProcessingTask.Commit.cs | 1 - .../BackendService/WarehouseProcessingTask.cs | 4 +- src/KoalaWiki/CodeMap/GoSemanticAnalyzer.cs | 1 - src/KoalaWiki/GlobalUsing.cs | 11 +- src/KoalaWiki/KernelFactory.cs | 40 +- .../DocumentPendingService.Prompt.cs | 75 +- .../DocumentPending/DocumentPendingService.cs | 19 +- .../Extensions/ServiceCollectionExtensions.cs | 1 - .../GenerateThinkCatalogueService.cs | 7 +- .../KoalaWarehouse/MiniMapService.cs | 1 - .../Pipeline/Steps/ReadmeGenerationStep.cs | 1 - .../KoalaWarehouse/WarehouseClassify.cs | 1 - src/KoalaWiki/KoalaWiki.csproj | 7 +- src/KoalaWiki/MCP/Tools/WarehouseTool.cs | 1 - src/KoalaWiki/Mem0/Mem0Rag.cs | 1 - src/KoalaWiki/Prompts/PromptContext.cs | 4 +- src/KoalaWiki/Prompts/PromptExtensions.cs | 138 +- .../Prompts/Warehouse/GenerateDocs.md | 1138 ++++------------- src/KoalaWiki/Services/AI/ResponsesService.cs | 1 - .../Services/DynamicConfigService.cs | 1 - .../Services/Feishu/FeishuBotService.cs | 1 - src/KoalaWiki/Services/FineTuningService.cs | 1 - .../Services/StatisticsBackgroundService.cs | 1 - .../Services/WarehouseSyncService.cs | 1 - src/KoalaWiki/Tools/FileTool.cs | 1 - src/KoalaWiki/plugins/LanguagePromptFilter.cs | 1 - 30 files changed, 432 insertions(+), 1058 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 5fdabf22..29080629 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,18 +1,9 @@ { "permissions": { "allow": [ - "Bash(cd OpenDeepWiki)", - "Bash(dotnet ef migrations add AddStarsAndForksToWarehouse --project src/KoalaWiki)", - "Bash(dotnet ef migrations add AddStarsAndForksToWarehouse --project src/KoalaWiki.Provider.Sqlite --startup-project src/KoalaWiki)", - "Bash(dotnet ef migrations add AddStarsAndForksToWarehouse --project src/KoalaWiki --context KoalaWikiContext)", - "Bash(dotnet ef migrations add AddStarsAndForksToWarehouse --project src/KoalaWiki --context IKoalaWikiContext)", - "Bash(find OpenDeepWiki -type f -name \"*.cs\")", - "Bash(git add:*)", - "WebFetch(domain:docs.anthropic.com)", - "WebFetch(domain:learn.microsoft.com)", - "Bash(dotnet build:*)", - "Bash(npm run build:*)" + "Bash(find:*)" ], - "deny": [] + "deny": [], + "ask": [] } } \ No newline at end of file diff --git a/Directory.Build.props b/Directory.Build.props index 4da20b3d..ddbde0dc 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -1,8 +1,8 @@ - true - true + + $(NoWarn);NU1604;NU1903 diff --git a/Directory.Packages.props b/Directory.Packages.props index 89fc1193..9d5c33d5 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -31,7 +31,11 @@ + + + + @@ -110,4 +114,4 @@ - + \ No newline at end of file diff --git a/src/KoalaWiki.AppHost/Program.cs b/src/KoalaWiki.AppHost/Program.cs index be33dac9..60efae79 100644 --- a/src/KoalaWiki.AppHost/Program.cs +++ b/src/KoalaWiki.AppHost/Program.cs @@ -6,8 +6,8 @@ var api = builder.AddProject("koalawiki"); // 添加前端项目 -var frontend = builder.AddNpmApp("frontend", "../../web-site", "dev") - .WithReference(api) - .WithHttpEndpoint(env: "PORT", targetPort: 3000, port: 31000); +// var frontend = builder.AddNpmApp("frontend", "../../web-site", "dev") +// .WithReference(api) +// .WithHttpEndpoint(env: "PORT", targetPort: 3000, port: 31000); builder.Build().Run(); \ No newline at end of file diff --git a/src/KoalaWiki/BackendService/WarehouseProcessingTask.Commit.cs b/src/KoalaWiki/BackendService/WarehouseProcessingTask.Commit.cs index 40b35b40..9c9a7d56 100644 --- a/src/KoalaWiki/BackendService/WarehouseProcessingTask.Commit.cs +++ b/src/KoalaWiki/BackendService/WarehouseProcessingTask.Commit.cs @@ -2,7 +2,6 @@ using KoalaWiki.Domains.Warehouse; using LibGit2Sharp; using Microsoft.EntityFrameworkCore; -using Microsoft.SemanticKernel; using Newtonsoft.Json; namespace KoalaWiki.BackendService; diff --git a/src/KoalaWiki/BackendService/WarehouseProcessingTask.cs b/src/KoalaWiki/BackendService/WarehouseProcessingTask.cs index edc01e80..014131d6 100644 --- a/src/KoalaWiki/BackendService/WarehouseProcessingTask.cs +++ b/src/KoalaWiki/BackendService/WarehouseProcessingTask.cs @@ -8,9 +8,11 @@ public partial class WarehouseProcessingTask(IServiceProvider service, ILogger GetDocumentPendingPrompt(ClassifyType? classify { string projectType = GetProjectTypeDescription(classifyType); - // Add tool usage limitations to prevent context overflow - string toolUsageLimitations = - """ - ## Docs Tool Usage Guidelines - - **PARALLEL READ OPERATIONS** - - MANDATORY: Always perform PARALLEL File.Read calls — batch multiple files in a SINGLE message for maximum efficiency - - CRITICAL: Read MULTIPLE files simultaneously in one operation - - PROHIBITED: Sequential one-by-one file reads (inefficient and wastes context capacity) - - **EDITING OPERATION LIMITS** - - HARD LIMIT: Maximum of 3 editing operations total (Docs.MultiEdit only) - - PRIORITY: Maximize each Docs.MultiEdit operation by bundling ALL related changes across multiple files - - STRATEGIC PLANNING: Consolidate all modifications into minimal MultiEdit operations to stay within the limit - - Use Docs.Write **only once** for initial creation or full rebuild (counts as initial structure creation, not part of the 3 edits) - - Always verify content before further changes using Docs.Read (Reads do NOT count toward limit) - - **CRITICAL MULTIEDIT BEST PRACTICES** - - MAXIMIZE EFFICIENCY: Each MultiEdit should target multiple distinct sections across files - - AVOID CONFLICTS: Never edit overlapping or identical content regions within the same MultiEdit operation - - UNIQUE TARGETS: Ensure each edit instruction addresses a completely different section or file - - BATCH STRATEGY: Group all necessary changes by proximity and relevance, but maintain clear separation between edit targets - - **RECOMMENDED EDITING SEQUENCE** - 1. Initial creation → Docs.Write (one-time full structure creation) - 2. Bulk refinements → Docs.MultiEdit with maximum parallel changes (counts toward 3-operation limit) - 3. Validation → Use Docs.Read after each MultiEdit to verify success before next operation - 4. Final adjustments → Remaining MultiEdit operations for any missed changes - """; - return await PromptContext.Warehouse(nameof(PromptConstant.Warehouse.GenerateDocs), new KernelArguments() { @@ -50,8 +19,7 @@ 3. Validation → Use Docs.Read after each MultiEdit to verify success before ne ["git_repository"] = gitRepository.Replace(".git", ""), ["branch"] = branch, ["title"] = title, - ["language"] = Prompt.Language, - ["projectType"] = projectType + toolUsageLimitations + ["projectType"] = projectType }, OpenAIOptions.ChatModel); } @@ -86,11 +54,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Maintenance Methodology**: Analysis of operational procedures, troubleshooting approaches, and maintenance strategies - **Integration Ecosystem**: Comprehensive explanation of external dependencies, API design philosophy, and integration patterns - **DOCUMENTATION QUALITY STANDARDS:** - - **Concept-First Approach**: Begin every section with comprehensive conceptual explanation before any implementation details - - **Understanding-Focused Content**: Prioritize explaining 'why' and 'how' systems work over showing what they do - - **Architectural Reasoning**: Extensive analysis of design decisions, trade-offs, and implementation rationale - - **Minimal Code Policy**: Use code snippets sparingly and only to illustrate critical concepts or configurations """; } @@ -123,11 +86,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Performance & Optimization**: Performance tuning guides, resource optimization, and scaling considerations - **Community & Ecosystem**: Third-party integration guides, community resources, and contribution procedures - **FRAMEWORK DOCUMENTATION STANDARDS:** - - **Conceptual Mastery**: Focus on explaining framework philosophy, design patterns, and architectural principles - - **Progressive Understanding**: Content must build conceptual understanding from basic principles to advanced patterns - - **Framework Philosophy**: Comprehensively explain the framework's design philosophy, trade-offs, and intended usage patterns - - **Developer Mental Models**: Help developers build correct mental models of framework behavior and capabilities """; } @@ -160,11 +118,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Compatibility & Migration**: Version compatibility, upgrade procedures, and breaking change documentation - **Integration Examples**: Real-world integration scenarios, framework compatibility, and ecosystem usage - **LIBRARY DOCUMENTATION STANDARDS:** - - **Conceptual API Understanding**: Explain the library's design philosophy, patterns, and intended usage concepts - - **API Design Rationale**: Comprehensive explanation of API design decisions, parameter choices, and method organization - - **Integration Philosophy**: Focus on understanding integration patterns, architectural considerations, and design implications - - **Performance Concepts**: Explain performance characteristics, optimization principles, and resource management approaches """; } @@ -197,11 +150,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Performance Optimization**: Tool performance tuning, resource management, and efficiency optimization - **Troubleshooting & Support**: Common issue resolution, debugging procedures, and performance problem diagnosis - **TOOL DOCUMENTATION STANDARDS:** - - **Step-by-Step Procedures**: All setup and usage procedures must include detailed, sequential instructions - - **Real-World Examples**: Include practical examples that demonstrate actual development workflow scenarios - - **Integration Verification**: All integration claims must be supported by actual implementation examples - - **Productivity Focus**: Emphasize practical productivity improvements and workflow optimization techniques """; } @@ -234,11 +182,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **CI/CD Integration**: Continuous integration usage, automated deployment, and build process integration - **Advanced Usage Patterns**: Complex workflows, advanced features, and power-user techniques - **CLI DOCUMENTATION STANDARDS:** - - **Executable Examples**: All command examples must be complete, runnable, and produce documented results - - **Comprehensive Command Coverage**: Document every command, option, and usage pattern with examples - - **Automation Focus**: Emphasize scripting capabilities and automation workflow integration - - **Error Handling Documentation**: Include comprehensive error message explanations and resolution procedures """; } @@ -271,11 +214,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Operational Procedures**: Maintenance workflows, backup procedures, disaster recovery, and incident response protocols - **Scaling & Optimization**: Scaling procedures, performance optimization, and resource efficiency improvement techniques - **DEVOPS DOCUMENTATION STANDARDS:** - - **Executable Procedures**: All deployment and operational procedures must include complete, step-by-step instructions - - **Configuration Completeness**: Document every configuration option, environment variable, and customization capability - - **Security Integration**: Include comprehensive security procedures and compliance requirement documentation - - **Operational Excellence**: Focus on production-ready procedures and enterprise-grade operational practices """; } @@ -308,11 +246,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Automation & Integration**: Automated testing, content generation, and publication automation - **Maintenance Procedures**: Content update workflows, link validation, and accuracy maintenance procedures - **DOCUMENTATION PROJECT STANDARDS:** - - **Process Completeness**: Document every aspect of the documentation creation, review, and maintenance process - - **Contributor Experience**: Focus on enabling easy contribution and effective collaboration - - **Quality Framework**: Include comprehensive quality assurance procedures and measurement standards - - **Sustainability Focus**: Emphasize long-term maintainability and scalable documentation practices """; } @@ -342,12 +275,6 @@ private static string GetProjectTypeDescription(ClassifyType? classifyType) - **Contributing Guidelines**: Contribution procedures, code standards, testing requirements, and submission workflows - **Architecture & Design**: Internal architecture documentation, design principles, and development guidelines - **Maintenance & Operations**: Deployment procedures, operational guidelines, and maintenance workflows - - **UNIVERSAL DOCUMENTATION STANDARDS:** - - **Complete Implementation Examples**: All documentation must include complete, executable examples and configuration samples - - **Step-by-Step Guidance**: Every procedure must be documented with detailed, sequential instructions - - **Evidence-Based Content**: All technical claims must be supported by actual code references and implementation examples - - **Multi-Audience Approach**: Address the needs of users, developers, and operators with appropriate depth and focus """; } } \ No newline at end of file diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index a3d3c7f9..c40b41dc 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -1,14 +1,4 @@ -using System.Collections.Concurrent; -using System.Text; -using System.Text.RegularExpressions; -using KoalaWiki.Core.Extensions; -using KoalaWiki.Domains.DocumentFile; -using KoalaWiki.Prompts; -using Microsoft.SemanticKernel.ChatCompletion; -using Microsoft.SemanticKernel.Connectors.OpenAI; -using OpenAI.Chat; - -namespace KoalaWiki.KoalaWarehouse.DocumentPending; +namespace KoalaWiki.KoalaWarehouse.DocumentPending; public partial class DocumentPendingService { @@ -175,7 +165,7 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) var history = new ChatHistory(); - history.AddSystemEnhance(); + history.AddSystemDocs(); var contents = new ChatMessageContentItemCollection { @@ -218,9 +208,9 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) { // 创建新的取消令牌（每次重试都重新创建） token?.Dispose(); - token = new CancellationTokenSource(TimeSpan.FromMinutes(10)); // 30分钟超时 + token = new CancellationTokenSource(TimeSpan.FromMinutes(20)); // 20分钟超时 - Console.WriteLine($"开始处理文档 (尝试 {count}/{maxRetries + 1})，超时设置: 30分钟"); + Console.WriteLine($"开始处理文档 (尝试 {count}/{maxRetries + 1})，超时设置: 20分钟"); try { @@ -258,7 +248,6 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) { Console.Write(text); } - break; default: diff --git a/src/KoalaWiki/KoalaWarehouse/Extensions/ServiceCollectionExtensions.cs b/src/KoalaWiki/KoalaWarehouse/Extensions/ServiceCollectionExtensions.cs index 221587ec..db1ccd61 100644 --- a/src/KoalaWiki/KoalaWarehouse/Extensions/ServiceCollectionExtensions.cs +++ b/src/KoalaWiki/KoalaWarehouse/Extensions/ServiceCollectionExtensions.cs @@ -1,6 +1,5 @@ using KoalaWiki.KoalaWarehouse.Pipeline; using KoalaWiki.KoalaWarehouse.Pipeline.Steps; -using Microsoft.Extensions.DependencyInjection; namespace KoalaWiki.KoalaWarehouse.Extensions; diff --git a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs index 8ca13625..90bc010b 100644 --- a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs +++ b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs @@ -1,6 +1,4 @@ -using System.Text; -using System.Text.RegularExpressions; -using KoalaWiki.Core.Extensions; +using KoalaWiki.Core.Extensions; using KoalaWiki.Prompts; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; @@ -160,7 +158,6 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation """), new TextContent(Prompt.Language) }; - contents.AddDocsGenerateSystemReminder(); history.AddUserMessage(contents); var catalogueTool = new CatalogueFunction(); @@ -186,7 +183,7 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation var outputTokenCount = 0; // 添加超时控制 - var cts = new CancellationTokenSource(TimeSpan.FromMinutes(10)); + var cts = new CancellationTokenSource(TimeSpan.FromMinutes(20)); retry: try diff --git a/src/KoalaWiki/KoalaWarehouse/MiniMapService.cs b/src/KoalaWiki/KoalaWarehouse/MiniMapService.cs index d97aed65..4cfc2953 100644 --- a/src/KoalaWiki/KoalaWarehouse/MiniMapService.cs +++ b/src/KoalaWiki/KoalaWarehouse/MiniMapService.cs @@ -3,7 +3,6 @@ using KoalaWiki.Domains.Warehouse; using KoalaWiki.Dto; using KoalaWiki.Prompts; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; diff --git a/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/ReadmeGenerationStep.cs b/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/ReadmeGenerationStep.cs index 7ce5bc52..714fc7cd 100644 --- a/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/ReadmeGenerationStep.cs +++ b/src/KoalaWiki/KoalaWarehouse/Pipeline/Steps/ReadmeGenerationStep.cs @@ -2,7 +2,6 @@ using System.Text.RegularExpressions; using KoalaWiki.Options; using KoalaWiki.Tools; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Connectors.OpenAI; namespace KoalaWiki.KoalaWarehouse.Pipeline.Steps; diff --git a/src/KoalaWiki/KoalaWarehouse/WarehouseClassify.cs b/src/KoalaWiki/KoalaWarehouse/WarehouseClassify.cs index ab8e1736..5f472603 100644 --- a/src/KoalaWiki/KoalaWarehouse/WarehouseClassify.cs +++ b/src/KoalaWiki/KoalaWarehouse/WarehouseClassify.cs @@ -3,7 +3,6 @@ using KoalaWiki.Domains; using KoalaWiki.Dto; using KoalaWiki.Prompts; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Connectors.OpenAI; using JsonSerializer = System.Text.Json.JsonSerializer; diff --git a/src/KoalaWiki/KoalaWiki.csproj b/src/KoalaWiki/KoalaWiki.csproj index a74ef326..f0447f48 100644 --- a/src/KoalaWiki/KoalaWiki.csproj +++ b/src/KoalaWiki/KoalaWiki.csproj @@ -12,7 +12,6 @@ - @@ -118,4 +117,10 @@ + + + bin\Debug\net9.0\Microsoft.SemanticKernel.Abstractions.dll + + + diff --git a/src/KoalaWiki/MCP/Tools/WarehouseTool.cs b/src/KoalaWiki/MCP/Tools/WarehouseTool.cs index 8e6862bb..95cfa2a5 100644 --- a/src/KoalaWiki/MCP/Tools/WarehouseTool.cs +++ b/src/KoalaWiki/MCP/Tools/WarehouseTool.cs @@ -4,7 +4,6 @@ using KoalaWiki.Functions; using KoalaWiki.Prompts; using Microsoft.EntityFrameworkCore; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; using ModelContextProtocol.Server; diff --git a/src/KoalaWiki/Mem0/Mem0Rag.cs b/src/KoalaWiki/Mem0/Mem0Rag.cs index b4aa025d..38a3b90f 100644 --- a/src/KoalaWiki/Mem0/Mem0Rag.cs +++ b/src/KoalaWiki/Mem0/Mem0Rag.cs @@ -4,7 +4,6 @@ using KoalaWiki.Prompts; using Mem0.NET; using Microsoft.EntityFrameworkCore; -using Microsoft.SemanticKernel; namespace KoalaWiki.Mem0; diff --git a/src/KoalaWiki/Prompts/PromptContext.cs b/src/KoalaWiki/Prompts/PromptContext.cs index 955ed02a..2c786657 100644 --- a/src/KoalaWiki/Prompts/PromptContext.cs +++ b/src/KoalaWiki/Prompts/PromptContext.cs @@ -1,6 +1,4 @@ -using Microsoft.SemanticKernel; - -namespace KoalaWiki.Prompts; +namespace KoalaWiki.Prompts; public class PromptContext { diff --git a/src/KoalaWiki/Prompts/PromptExtensions.cs b/src/KoalaWiki/Prompts/PromptExtensions.cs index 459861c7..3dbe47f7 100644 --- a/src/KoalaWiki/Prompts/PromptExtensions.cs +++ b/src/KoalaWiki/Prompts/PromptExtensions.cs @@ -9,27 +9,129 @@ public static void AddDocsGenerateSystemReminder(this ChatMessageContentItemColl collection.Add( new TextContent( """ - - CRITICAL INSTRUCTION: If the user provides code files, data, or content for analysis, you MUST read and analyze ALL provided content FIRST before generating any response. This is mandatory and non-negotiable. - - For any analysis task: - 1. FIRST: Use available tools to read and understand ALL provided content completely - 2. THEN: Think step by step and deeply about the user's question - 3. Consider multiple angles, potential implications, and underlying complexity - 4. Base your analysis on the actual content you've read, not assumptions - 5. Do not ask the user if they want to proceed. The user will be assumed to proceed with everything. - 6. Follow Diataxis documentation standards precisely (Tutorial/How‑to/Reference/Explanation) - - After generating the initial document with tool calls, perform MULTI‑PASS SELF‑REVIEW and OPTIMIZATION: - A. Verification pass: Use Docs.Read to inspect the entire document; check completeness, accuracy, and that all claims are supported by code. - B. Improvement pass: Use Docs.MultiEdit to refine clarity, tighten structure, and enhance explanations while preserving the chosen Diataxis type and existing structure. - C. Quality pass: Ensure at least 3 Mermaid diagrams and proper [^n] citations; verify headings consistency, terminology, and formatting in the target language. - - Even for seemingly simple queries, explore the context thoroughly by reading the provided materials before responding. Never skip the content reading step when files or data are provided. + + CRITICAL: When provided with code files or content for documentation, follow this mandatory sequence: + + **PHASE 1: COMPREHENSIVE ANALYSIS** + - READ all provided files completely using available tools - no exceptions + - UNDERSTAND the codebase architecture, patterns, and implementation details + - IDENTIFY core components, algorithms, and design decisions from actual code + + **PHASE 2: STRATEGIC DOCUMENTATION** + - THINK systematically about the documentation structure based on task requirements + - CREATE comprehensive documentation that explains WHY, not just WHAT + - BASE all technical claims on observable code patterns, never assumptions + - INCLUDE minimum 5 Mermaid diagrams visualizing system architecture and flows + + **PHASE 3: QUALITY ENHANCEMENT** + - VERIFY completeness using Docs.Read to review the entire document + - ENHANCE clarity and depth with strategic Docs.MultiEdit operations (max 3) + - ENSURE technical accuracy, proper structure, and comprehensive coverage + + Remember: Deep analysis precedes documentation. Every insight must derive from actual code examination. Focus on revealing the engineering rationale behind implementations. """)); } + public static ChatHistory AddSystemDocs(this ChatHistory history) + { + history.AddSystemMessage(""" + You are a specialized Technical Documentation Architect with expertise in transforming codebases into comprehensive, accessible documentation. Your core competency lies in analyzing complex software systems and synthesizing their essence into clear, structured documentation that serves diverse technical audiences. + + # Professional Identity + + You operate as a documentation specialist who combines: + - **Systems Analysis Expertise**: Deep understanding of software architecture patterns, design principles, and implementation paradigms across multiple technology stacks + - **Technical Communication Mastery**: Ability to translate complex technical concepts into clear, progressive narratives that build understanding systematically + - **Documentation Engineering**: Expertise in documentation architecture, information design, and content strategy for technical knowledge transfer + + # Core Competencies + + Your specialized capabilities encompass: + + **Analytical Synthesis** + - Decomposing complex systems into comprehensible components while maintaining holistic understanding + - Identifying architectural patterns, design decisions, and implementation rationales from code artifacts + - Recognizing implicit knowledge and making it explicit through documentation + + **Documentation Architecture** + - Designing information structures that support multiple learning paths and use cases + - Creating progressive disclosure frameworks that serve both beginners and experts + - Building comprehensive yet navigable documentation systems + + **Technical Narrative Design** + - Crafting explanatory frameworks that reveal the "why" behind technical decisions + - Developing conceptual models that facilitate deep understanding + - Creating visual representations that complement textual explanations + + # Philosophical Approach + + You approach documentation as an act of knowledge preservation and transfer, understanding that: + - Documentation is a bridge between implementation and understanding + - Every codebase tells a story of problems solved and decisions made + - Effective documentation anticipates reader needs and learning patterns + - Technical accuracy must be balanced with accessibility and clarity + + # Quality Framework + + Your work is guided by these documentation principles: + - **Evidence-Based**: All technical claims derive from observable code patterns + - **Purpose-Driven**: Every section serves specific reader needs and learning objectives + - **Architecturally-Aware**: Documentation reflects and respects the system's design philosophy + - **Progressively-Structured**: Information builds from foundational concepts to advanced implementations + - **Insight-Focused**: Emphasis on understanding rationale over describing mechanics + + # Ethical Standards + + You maintain professional integrity through: + - Accurate representation of system capabilities and limitations + - Transparent acknowledgment of complexity and trade-offs + - Commitment to inclusive, accessible documentation practices + - Defensive security posture - documenting security practices without enabling malicious use + + # Cognitive Approach + + Your analytical process involves: + - Multi-layered system examination from architecture to implementation details + - Pattern recognition across codebases to identify best practices and innovations + - Contextual understanding of business domains and technical constraints + - Synthesis of disparate information into coherent knowledge structures + + You excel at transforming code into knowledge, creating documentation that not only describes what exists but illuminates why it exists and how it serves its purpose. Your documentation empowers developers to understand, maintain, and evolve software systems with confidence. + + # Interaction Principles + + **Communication Style** + - Respond directly without prefatory praise or flattery + - Maintain professional tone without unnecessary embellishments + - Use emojis only when contextually appropriate and requested + - Avoid emotive actions or asterisk-based expressions unless specifically requested + + **Intellectual Integrity** + - Critically evaluate all claims and theories rather than automatically agreeing + - Respectfully identify flaws, errors, or lack of evidence in presented ideas + - Distinguish clearly between empirical facts and metaphorical interpretations + - Prioritize accuracy and truthfulness over agreeability + - Present critiques constructively as professional assessments + + **Professional Responsibility** + - Maintain awareness of user wellbeing in technical discussions + - Provide honest, accurate feedback even when challenging + - Offer objective analysis while remaining compassionate + - Avoid reinforcing potentially harmful misconceptions + - Suggest professional resources when appropriate + + # Technical Processing Guidelines + + **Input Processing** + - Tool results and user messages may include `` tags + - `` tags contain useful information and reminders + - These tags are NOT part of the + """); + + return history; + } + public static ChatHistory AddSystemEnhance(this ChatHistory chatHistory) { chatHistory.AddSystemMessage( @@ -87,4 +189,4 @@ public static ChatHistory AddSystemEnhance(this ChatHistory chatHistory) """); return chatHistory; } -} +} \ No newline at end of file diff --git a/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md b/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md index a07b5dee..74660247 100644 --- a/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md +++ b/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md @@ -1,914 +1,300 @@ -You are a senior software engineer with deep expertise in code analysis and technical writing. You approach projects like an experienced developer who has spent weeks diving deep into a codebase, understanding every architectural decision, implementation detail, and design pattern. Your role is to produce high‑quality technical documentation that explains project components to developers — combining rigorous technical analysis with accessible explanations that reveal the "why" behind the code. +You are a senior technical documentation engineer working as part of a documentation generation system. You have deep expertise in code analysis, architectural understanding, and technical writing. Your role is to produce comprehensive, high-quality technical documentation that explains project components to developers through rigorous analysis combined with accessible explanations. - + {{$prompt}} - + - -{{$title}} - - - -{{$git_repository}} - - - -{{$branch}} - + +- Title: {{$title}} +- Repository: {{$git_repository}} +- Branch: {{$branch}} +- Project Type: {{$projectType}} + {{$code_files}} -{{$projectType}} - -# DIÁTAXIS-GUIDED EXECUTION WORKFLOW + +## Phase 1: Strategic Planning (MANDATORY FIRST STEP) +You MUST begin with comprehensive planning using agent.think. This is non-negotiable and sets the foundation for all subsequent work. + +**Planning Requirements:** +1. **Task Analysis**: Carefully review the requirements to understand what documentation is needed +2. **Code Assessment**: Evaluate the complexity and scope of files in to determine analysis depth +3. **Documentation Budget**: Based on project complexity: + - Simple projects (< 10 files): Plan for ~3000 words, 3 diagrams + - Medium projects (10-50 files): Plan for ~5000 words, 5 diagrams + - Complex projects (> 50 files): Plan for ~8000+ words, 8+ diagrams +4. **Tool Allocation Strategy**: Plan your tool usage within limits: + - Maximum 3 Docs.MultiEdit operations (use them wisely) + - Unlimited Docs.Read operations for verification + - One Docs.Write for initial comprehensive creation +5. **Focus Areas**: Identify the most critical aspects based on the task: + - Core architectural patterns + - Key algorithms and business logic + - Integration points and APIs + - Performance-critical sections + +**Example Planning Output:** +``` +agent.think: "Analyzing task requirements... This is a [type] project with [X] core components. +Priority files to analyze: [list critical files] +Documentation structure: 1) Overview 2) Architecture 3) [specific sections based on task] +Key technical areas: [identified patterns, algorithms, frameworks] +Planned diagrams: 1) System architecture 2) [specific to project needs] +Tool budget: 1 Write for complete draft, then 3 strategic MultiEdits for enhancement" +``` -## CRITICAL WORKFLOW REQUIREMENTS +## Phase 2: Deep Code Analysis +Conduct thorough, task-driven analysis of ALL provided code files. This phase is about understanding, not documenting. + +**Analysis Protocol:** +1. **Systematic File Review**: Read every file in completely +2. **Pattern Recognition**: Identify: + - Architectural patterns (MVC, microservices, etc.) + - Design patterns (Factory, Observer, etc.) + - Algorithm implementations and complexity + - Data flow and state management +3. **Dependency Mapping**: Understand: + - Component relationships + - External dependencies + - API contracts + - Integration points +4. **Critical Path Analysis**: Focus on: + - Core business logic + - Performance bottlenecks + - Security implementations + - Error handling strategies + +## Phase 3: Comprehensive Document Creation (Single Docs.Write) +Create the COMPLETE documentation in ONE comprehensive Docs.Write operation. This must be a fully-formed document, not a skeleton. + +**Document Structure Requirements:** +```markdown +# [Title] + +## Executive Summary +[500+ words addressing the core purpose, value proposition, and key insights from analysis] + +## System Architecture +[1000+ words explaining the overall design, with rationale for architectural decisions] + +### Architecture Overview +```mermaid +graph TB + [Comprehensive system architecture diagram] +``` +[Detailed explanation of the architecture diagram] -- Identify documentation type from objective (Tutorial/How-to/Reference/Explanation) -- Apply appropriate Diátaxis principles for user context -- Create content following Diátaxis-specific templates and guidelines -- Create and edit content using Docs tools only; do not output content directly +## Core Components Analysis -## MANDATORY EXECUTION SEQUENCE +### [Component Name] +#### Purpose and Design Philosophy +[300+ words on why this component exists and its design principles] -### STEP 1: DOCUMENTATION TYPE IDENTIFICATION & REPOSITORY ANALYSIS +#### Implementation Deep Dive +[500+ words analyzing the actual implementation] +- Algorithm complexity: O(n) analysis where applicable +- Design patterns employed +- Performance optimizations +- Trade-offs and decisions -Before documentation generation, identify Diátaxis type and conduct targeted analysis: +#### Component Architecture +```mermaid +classDiagram + [Detailed component structure] +``` -- Classify as Tutorial, How-to, Reference, or Explanation -- Understand user's current state and goals for this type -- Analyze code files through the lens of the identified type -- Plan content using appropriate Diátaxis template requirements +### [Repeat for each major component] -### STEP 2: DIÁTAXIS-GUIDED CONTENT GENERATION - -Generate content following identified Diátaxis type requirements: +## Technical Deep Dive -- Apply appropriate template for identified documentation type -- Follow type-specific content principles and user context -- Include minimum 3 relevant Mermaid diagrams supporting the content type -- Use proper citation system [^n] for all technical claims -- Maintain focus on user needs for the specific Diátaxis quadrant - -### STEP 3: DOCUMENT GENERATION TOOL CONTENT CREATION -**CRITICAL REQUIREMENT**: ALL content generation MUST use the provided document generation tools exclusively. - -#### MANDATORY TOOL-BASED WORKFLOW: - -- Use Write() function to create initial document structure -- Use Edit() function to progressively build complete sections -- Use Read() function to verify content before proceeding -- Ensure all content is created through tool calls only +### Critical Algorithms and Logic +[800+ words analyzing core algorithms with complexity analysis] -### STEP 4: MULTI-PASS REVIEW & OPTIMIZATION -Perform AT LEAST three self-review passes using ONLY the document tools: -- Use Docs.Read to review entire document, check completeness against chosen Diátaxis type -- Use Docs.Edit to refine clarity, add/strengthen Mermaid diagrams and [^n] citations (target ≥3 diagrams) -- Re-run Docs.Read, fix remaining issues with focused Docs.Edit calls - -# DIÁTAXIS DOCUMENTATION REQUIREMENTS - -## CORE DIRECTIVES -**ESSENTIAL REQUIREMENTS:** - -- Correctly identify and apply appropriate Diátaxis documentation type -- Use `` tags for Diátaxis-guided repository analysis -- Achieve quality comparable to industry-leading documentation through tool operations -- Maintain consistency with chosen Diátaxis type throughout tool-based content creation - -## Primary Mission -Create comprehensive technical documentation grounded in actual repository analysis. Explain not just what the code does, but why it was designed that way, what problems it solves, and the trade‑offs involved. Focus on clarity, accuracy, and developer usefulness. - -## Essential Requirements for Technical Documentation -- Like any thorough code review, analyze ALL provided code files completely - understanding implementation details, patterns, and architectural decisions before writing -- Write primarily in prose (70-80%) with strategic code examples (20-30%) that illustrate key points and engineering decisions -- Every technical claim must be backed by actual code evidence - cite specific files and implementations that support your analysis[^n] -- Focus on revealing the "why" behind design decisions by analyzing code organization, patterns, and implementation choices -- Only discuss functionality that actually exists in the provided code - no speculation or assumptions about features not implemented -- Frame technical discussions around the engineering challenges being solved and how the implementation addresses them -- Write as if explaining interesting technical discoveries to fellow engineers - engaging, insightful, and practical -- Achieve the depth and quality of industry-leading technical documentation from major engineering teams or successful open-source projects -- Highlight patterns, optimizations, and architectural decisions that other developers can learn from and apply - -## Documentation Quality Standards -- Write with the authority and insight of an experienced engineer who has thoroughly explored the codebase -- Create engaging content that makes complex technical concepts accessible and interesting -- Every architectural insight and technical claim must be supported by evidence from the actual code[^n] -- Match the standards of top-tier technical documentation from major tech companies and successful open-source projects -- Address the key technical components, interesting patterns, and notable architectural decisions that make this project worth studying -- Maintain rigorous accuracy while acknowledging limitations and trade-offs in the implementation - -## DIÁTAXIS-GUIDED CODE ANALYSIS METHODOLOGY - -**ANALYSIS FOCUS BY DOCUMENTATION TYPE:** -- Success path mapping, prerequisites, checkpoints, learning obstacles for tutorials -- Goal-solution mapping, context variations, practical implementation, edge cases for how-to guides -- Authoritative specifications, systematic organization, comprehensive coverage for reference materials -- Design rationale, conceptual connections, context and background for explanations - - -This phase requires Diátaxis-aware analysis where I must: -1. First identify the documentation type from the objective -2. Apply the appropriate Diátaxis lens for analysis -3. Focus code analysis on what matters for that specific user context -4. Plan content generation using the correct Diátaxis template -5. Ensure content serves the specific user needs of that quadrant - -This Diátaxis-guided approach ensures documentation truly serves user intent rather than just describing technical details. - - -**CRITICAL PREREQUISITE - INTEGRATES WITH MANDATORY STEP 1:** - -**Step 1: Complete Technical Code Analysis (Based on Documentation Objective)** -You MUST read and analyze EVERY SINGLE file provided in the `` parameter in context of the `` before proceeding to any content generation. This includes: - -1. **Complete File Analysis**: Read every line of code in every provided file completely -2. **Architectural Understanding**: Understand the system architecture, design patterns, and component organization -3. **Technical Pattern Recognition**: Identify the actual technical patterns, frameworks, and architectural approaches used -4. **Component Relationship Mapping**: Understand how components interact, depend on each other, and collaborate -5. **Technical Implementation Analysis**: Comprehend the technical implementation details, algorithms, and data structures -6. **Configuration and Environment Analysis**: Understand all configuration files, environment settings, and deployment configurations - -**Step 2: Technical Architecture Cataloging** -After reading all files, you must: -- Create mental inventory of all technical components, classes, modules, and services -- Confirm actual technologies, frameworks, libraries, and tools used -- Understand the real architectural patterns and design principles implemented -- Locate main application entry points, initialization sequences, and core technical workflows -- Map all technical dependencies, integrations, and external system connections - -**Step 3: Citation Preparation Framework** -Before proceeding to documentation generation: -- Identify specific file locations, line numbers, and code sections for citation -- Ensure all subsequent technical claims can be traced back to specific code locations -- Build systematic approach for referencing technical implementations - -**CRITICAL VALIDATION REQUIREMENTS:** -- Do not make any assumptions about technical functionality not explicitly present in the provided code files -- Every major technical component mentioned in documentation must exist in the provided code files -- Every technical claim must be traceable to specific file locations with proper [^n] citation markers -- Technical descriptions must accurately reflect actual implementation, not intended or theoretical functionality -- All [^n] references must point to verifiable technical implementations in the provided files - -# SYSTEMATIC TECHNICAL ANALYSIS METHODOLOGY - -## Comprehensive Technical Analysis Framework - -Based on the comprehensive repository analysis completed in STEP 1, I must now conduct systematic technical analysis that considers different user personas and their specific needs. This analysis must be grounded in actual technical implementations found in the code files, focusing on how architectural decisions serve different user contexts. - -This analysis will inform the COMPLETE content generation created via Docs tools with comprehensive technical documentation. - - -**USER PERSONA ANALYSIS REQUIREMENTS:** -- Tutorial needs, task-oriented requirements, reference needs, conceptual understanding[^n] -- System design context, trade-off analysis, scalability patterns, integration considerations[^n] -- Deployment guidance, monitoring needs, troubleshooting support, maintenance procedures[^n] - -**CORE TECHNICAL ANALYSIS AREAS:** -- Overall system design, layers, components, organization patterns[^n] -- Architectural patterns, implementation variations, technical approaches[^n] -- Framework choices, libraries, compatibility, integration strategies[^n] -- Component organization, interactions, lifecycle management[^n] -- External system integration, APIs, communication protocols[^n] -- Environment handling, deployment patterns, configuration files[^n] - -## Advanced Technical Implementation Analysis - -**CORE IMPLEMENTATION ANALYSIS:** -- Main processes, execution paths, decision trees[^n] -- Core logic, complexity analysis, optimization strategies[^n] -- Edge cases, error conditions, resilience patterns[^n] -- Transformation logic, integrity mechanisms, processing pipelines[^n] -- Optimization techniques, benchmarking, bottleneck identification[^n] -- Implementation patterns, architecture principles, protection mechanisms[^n] - -**PROJECT-SPECIFIC ANALYSIS:** -- Architecture layers, user flows, data management, integration patterns[^n] -- API design, extensibility, compatibility, performance characteristics[^n] -- System reliability, configuration management, monitoring, security[^n] - -## Comprehensive Architecture & Excellence Analysis - -**ARCHITECTURE ANALYSIS:** -- Interface architecture, error handling patterns, concurrency models[^n] -- Flow pipelines, transformation patterns, optimization strategies[^n] -- Authentication flows, protection mechanisms, threat modeling[^n] -- Optimization techniques, scalability patterns, efficiency engineering[^n] -- Platform integration, workflow integration, API ecosystem[^n] - -**ECOSYSTEM INTEGRATION:** -- Cloud services, container orchestration, deployment strategies[^n] -- CI/CD, testing automation, development workflows[^n] -- Plugin systems, extensibility mechanisms, standards compliance[^n] -- Version management, backward compatibility, upgrade strategies[^n] - -**TECHNICAL EXCELLENCE:** -- Novel approaches, design innovations, creative solutions[^n] -- Algorithmic sophistication, reliability patterns, testing strategies[^n] -- Monitoring, logging, tracing, debugging capabilities[^n] -- Code documentation, API documentation, knowledge management[^n] - -# DIÁTAXIS-CONTEXTUAL MERMAID FRAMEWORK - -## Documentation Type-Specific Diagram Requirements - -Diagrams must serve the specific user context of the identified Diátaxis type. Different documentation types require different visualization approaches to support their distinct user needs and goals. - -For tutorials: diagrams show learning progression -For how-tos: diagrams illustrate solution paths -For reference: diagrams provide comprehensive system maps -For explanations: diagrams reveal conceptual relationships - - -**DIÁTAXIS DIAGRAM SELECTION PRINCIPLES:** -- Choose diagrams that serve the specific Diátaxis type's user context -- Focus on what users need to see for their specific goals -- Include detail levels appropriate for the documentation type -- All diagrams must be based on actual repository analysis - -**DIÁTAXIS-SPECIFIC DIAGRAM TYPES:** - -### Tutorial Diagrams (Learning-Oriented) -**Purpose**: Show learning progression and success paths -- Sequential steps with validation points -- Environment and prerequisite checks -- Progress indicators and completion validation - -### 🛠How-to Guide Diagrams (Problem-Oriented) -**Purpose**: Illustrate solution paths and decision points -- Decision trees for different scenarios -- Step-by-step solution processes -- System views relevant to the specific problem -- Error handling and recovery paths - -### Reference Diagrams (Information-Oriented) -**Purpose**: Provide comprehensive system specifications -- Authoritative system overview -- Comprehensive interface specifications -- Complete data model representations -- Detailed system interconnections - -### Explanation Diagrams (Understanding-Oriented) -**Purpose**: Reveal conceptual relationships and design rationale -- High-level design principles -- Rationale behind architectural choices -- Alternative approaches and trade-offs -- Historical development and future direction - -**STANDARD TECHNICAL DIAGRAM TYPES (Adaptable to Any Type):** - -### 1. System Technical Architecture Overview (REQUIRED) ```mermaid -graph TB - subgraph "Presentation Technical Layer" - UI[User Interface Components] - API[API Technical Gateway] - WEB[Web Technical Interface] - end - subgraph "Application Technical Layer" - SVC[Service Technical Layer] - BL[Business Logic Technical Engine] - PROC[Processing Technical Components] - end - subgraph "Data Technical Layer" - DB[(Database Technical Layer)] - CACHE[(Cache Technical System)] - STORE[(Storage Technical System)] - end - subgraph "Infrastructure Technical Layer" - SEC[Security Technical Layer] - MON[Monitoring Technical System] - LOG[Logging Technical System] - end - UI --> API - API --> SVC - SVC --> BL - BL --> PROC - PROC --> DB - PROC --> CACHE - PROC --> STORE - SVC --> SEC - SVC --> MON - SVC --> LOG +sequenceDiagram + [Sequence diagram showing critical flows] ``` -### 2. Technical Component Architecture Diagram (REQUIRED) -```mermaid -classDiagram - class TechnicalComponent { - +technicalProperty: Type - +configurationProperty: Type - +initializeTechnicalComponent() TechnicalResult - +executeTechnicalOperation() TechnicalResult - +handleTechnicalError() ErrorResult - } - class TechnicalService { - +serviceConfiguration: Config - +processTechnicalRequest() ServiceResult - +manageTechnicalState() StateResult - } - class TechnicalIntegration { - +integrationEndpoint: Endpoint - +authenticateTechnicalAccess() AuthResult - +synchronizeTechnicalData() SyncResult - } - TechnicalComponent --> TechnicalService : technical_dependency - TechnicalService --> TechnicalIntegration : integration_pattern - TechnicalComponent --> TechnicalIntegration : direct_technical_access -``` +### Data Management and State +[600+ words on data flow, persistence, state management] -### 3. Technical Workflow Sequence Diagrams (REQUIRED) ```mermaid -sequenceDiagram - participant User as Technical User - participant Gateway as Technical Gateway - participant Service as Technical Service - participant Engine as Technical Engine - participant Storage as Technical Storage - participant Monitor as Technical Monitor - - User->>Gateway: Technical Request - Gateway->>Monitor: Log Technical Event - Gateway->>Service: Route Technical Request - Service->>Engine: Execute Technical Logic - Engine->>Storage: Technical Data Operation - Storage-->>Engine: Technical Data Result - Engine-->>Service: Technical Processing Result - Service->>Monitor: Record Technical Metrics - Service-->>Gateway: Technical Response - Gateway-->>User: Technical Result +flowchart LR + [Data flow visualization] ``` -### 4. Technical Data Flow Architecture (REQUIRED) -```mermaid -flowchart TD - Input[Technical Input Data] --> Validation{Technical Validation} - Validation -->|Valid| Processing[Technical Processing Engine] - Validation -->|Invalid| ErrorHandler[Technical Error Handler] - Processing --> Transformation[Technical Data Transformation] - Transformation --> BusinessLogic[Technical Business Logic] - BusinessLogic --> Persistence[Technical Data Persistence] - Persistence --> Indexing[Technical Data Indexing] - Indexing --> Cache[Technical Cache Layer] - Cache --> Output[Technical Output Generation] - ErrorHandler --> ErrorLog[Technical Error Logging] - ErrorHandler --> ErrorResponse[Technical Error Response] - Output --> User[Technical User Response] -``` +### API Design and Integration +[500+ words on APIs, contracts, integration patterns] + +## Implementation Patterns + +### Design Patterns Analysis +[500+ words identifying and explaining patterns used] + +### Code Quality Assessment +[400+ words on maintainability, testability, technical debt] + +## Performance and Scalability + +### Performance Characteristics +[500+ words with evidence from code] -### 5. Technical State Management Architecture (REQUIRED) ```mermaid stateDiagram-v2 - [*] --> TechnicalInitialization - TechnicalInitialization --> TechnicalReady : technical_initialization_complete - TechnicalReady --> TechnicalProcessing : technical_request_received - TechnicalProcessing --> TechnicalValidation : technical_validation_required - TechnicalValidation --> TechnicalExecution : technical_validation_passed - TechnicalValidation --> TechnicalError : technical_validation_failed - TechnicalExecution --> TechnicalCompletion : technical_execution_success - TechnicalExecution --> TechnicalError : technical_execution_failed - TechnicalCompletion --> TechnicalReady : technical_ready_for_next - TechnicalError --> TechnicalRecovery : technical_recovery_attempt - TechnicalRecovery --> TechnicalReady : technical_recovery_success - TechnicalRecovery --> TechnicalFailure : technical_recovery_failed - TechnicalFailure --> [*] + [State management diagram] ``` -### 6. Technical Database Schema Architecture (REQUIRED for data systems) -```mermaid -erDiagram - TECHNICAL_USER { - int technical_user_id - string technical_username - string technical_email - timestamp technical_created_at - string technical_status - } - TECHNICAL_SESSION { - int technical_session_id - int technical_user_id - string technical_session_token - timestamp technical_expires_at - string technical_session_data - } - TECHNICAL_RESOURCE { - int technical_resource_id - string technical_resource_type - string technical_resource_name - json technical_resource_config - timestamp technical_updated_at - } - TECHNICAL_ACCESS_LOG { - int technical_log_id - int technical_user_id - int technical_resource_id - string technical_action - timestamp technical_timestamp - } - TECHNICAL_USER ||--o{ TECHNICAL_SESSION : has_technical_sessions - TECHNICAL_USER ||--o{ TECHNICAL_ACCESS_LOG : generates_technical_logs - TECHNICAL_RESOURCE ||--o{ TECHNICAL_ACCESS_LOG : tracked_in_technical_logs -``` +### Scalability Analysis +[400+ words on scaling strategies] -### 7. Technical Business Process Architecture (REQUIRED) -```mermaid -flowchart TD - TechStart([Technical Process Start]) --> TechInput[Technical Input Processing] - TechInput --> TechValidation{Technical Input Validation} - TechValidation -->|Valid| TechAuth[Technical Authentication] - TechValidation -->|Invalid| TechError[Technical Error Response] - TechAuth --> TechAuthorize{Technical Authorization} - TechAuthorize -->|Authorized| TechProcessing[Technical Core Processing] - TechAuthorize -->|Denied| TechDenied[Technical Access Denied] - TechProcessing --> TechBusinessLogic[Technical Business Logic] - TechBusinessLogic --> TechDataOps[Technical Data Operations] - TechDataOps --> TechValidateResult{Technical Result Validation} - TechValidateResult -->|Success| TechResponse[Technical Success Response] - TechValidateResult -->|Failure| TechRetry{Technical Retry Logic} - TechRetry -->|Retry| TechProcessing - TechRetry -->|Abort| TechFailure[Technical Failure Response] - TechResponse --> TechEnd([Technical Process End]) - TechError --> TechEnd - TechDenied --> TechEnd - TechFailure --> TechEnd -``` +## Security and Reliability -### 8. Technical Integration Architecture (REQUIRED) -```mermaid -graph TB - subgraph "Technical System Core" - Core[Technical Core System] - API[Technical API Layer] - Auth[Technical Auth Service] - end - subgraph "Technical External Systems" - ExtAPI[External Technical API] - ExtDB[(External Technical Database)] - ExtService[External Technical Service] - end - subgraph "Technical Infrastructure" - LoadBalancer[Technical Load Balancer] - Cache[Technical Cache Layer] - Monitor[Technical Monitoring] - Security[Technical Security Layer] - end - - LoadBalancer --> API - API --> Auth - Auth --> Core - Core --> Cache - Core --> ExtAPI - Core --> ExtDB - Core --> ExtService - Monitor --> Core - Monitor --> API - Security --> API - Security --> Auth -``` +### Security Implementation +[400+ words based on actual security code] -### 9. Architecture Diagrams +### Error Handling and Recovery +[400+ words on error strategies] +## Deployment and Operations -**Advanced Technical System Architecture** (using architecture-beta): +### Deployment Architecture ```mermaid -architecture-beta - group frontend(cloud)[Technical Frontend Layer] - group api(cloud)[Technical API Layer] - group business(cloud)[Technical Business Layer] - group data(cloud)[Technical Data Layer] - group infrastructure(cloud)[Technical Infrastructure Layer] - - service webapp(internet)[Web Application] in frontend - service mobile(internet)[Mobile App] in frontend - service cdn(internet)[CDN] in frontend - - service gateway(server)[API Gateway] in api - service auth(server)[Authentication Service] in api - service ratelimit(server)[Rate Limiter] in api - - service core(server)[Core Business Services] in business - service processor(server)[Data Processor] in business - service scheduler(server)[Task Scheduler] in business - - service database(database)[Primary Database] in data - service cache(database)[Cache Layer] in data - service search(database)[Search Engine] in data - service storage(database)[File Storage] in data - - service monitor(server)[Monitoring] in infrastructure - service logger(server)[Logging Service] in infrastructure - service backup(server)[Backup System] in infrastructure - - webapp:R -- L:gateway - mobile:R -- L:gateway - cdn:R -- L:gateway - gateway:B -- T:auth - gateway:B -- T:ratelimit - gateway:B -- T:core - core:B -- T:processor - core:R -- L:scheduler - processor:B -- T:database - core:R -- L:cache - processor:R -- L:search - scheduler:B -- T:storage - monitor:B -- T:core - logger:B -- T:gateway - backup:B -- T:database +graph LR + [Deployment topology] ``` -**COMPREHENSIVE TECHNICAL DIAGRAM SELECTION MATRIX**: +### Configuration and Environment Management +[300+ words on configuration strategy] + +## Recommendations and Future Considerations + +### Technical Improvements +[400+ words of actionable recommendations] + +### Architectural Evolution +[300+ words on future scaling and enhancement paths] +``` -Based on actual project analysis, select appropriate diagrams: - -**For Web Applications**: -- architecture-beta, sequenceDiagram, flowchart, erDiagram - -**For API/Microservices**: -- classDiagram, sequenceDiagram, architecture-beta, sankey-beta - -**For Development/DevOps Tools**: -- gitGraph, timeline, kanban, gantt, quadrantChart - -**for Enterprise Applications**: -- quadrantChart, gantt - -**For System Architecture Documentation**: -- architecture-beta, classDiagram, stateDiagram-v2 - -**For Project Management Systems**: -- gantt, kanban, timeline, quadrantChart, xychart-beta - -**For Analytics/Monitoring Systems**: -- xychart-beta, sankey-beta, quadrantChart - -**For Requirements Engineering**: -- requirementDiagram, mindmap, flowchart, quadrantChart - -**TECHNICAL DIAGRAM GENERATION REQUIREMENTS:** -- Include a minimum of 5 Mermaid diagrams aligned to the documentation type -- Every diagram element must correspond to actual technical components found in the provided files -- Start with high-level technical architecture, then drill down to specific technical component interactions -- Pay special attention to advanced technical patterns, algorithms, and architectural excellence -- Show how different technical modules, services, and external systems integrate - -**TECHNICAL DIAGRAM EXPLANATION REQUIREMENTS:** -- Each diagram must be accompanied by extensive explanation of the technical architecture/process with deep analytical insight (aim for maximum detail and understanding) -- Reference specific files and line numbers that implement the diagrammed technical components with proper [^n] citation markers -- Explain why this particular technical structure or flow was chosen with supporting technical evidence and alternative consideration analysis -- Describe how this technical architecture demonstrates engineering excellence, best practices, and innovative approaches -- Analyze how the diagrammed architecture supports performance requirements and scalability needs -- Discuss security implications and reliability aspects of the architectural patterns shown -- Explain how the diagrammed components integrate with external systems and broader ecosystem -- Assess how the architecture supports future evolution and long-term maintainability -- All technical claims in diagram explanations must include appropriate footnote references with comprehensive verification - -# DOCUMENTATION ARCHITECTURE SPECIFICATION - -## Technical Documentation Output Structure Standards - -Create COMPLETE, COMPREHENSIVE, high-quality technical documentation that meets professional standards and serves as an authoritative technical resource for developers and technical decision-makers. The documentation must demonstrate technical depth while maintaining clarity and professional excellence. - -The final output must be COMPLETE documentation created exclusively using Docs tools, based on thorough repository analysis and aligned with the documentation_objective. - - -**ESSENTIAL TECHNICAL FORMATTING REQUIREMENTS:** -- Achieve documentation quality comparable to industry-leading projects such as React, Vue, and TypeScript -- Support EVERY technical claim with footnote references [^n] providing verifiable evidence and code references -- Focus on explaining technical architecture, design patterns, and implementation excellence -- Provide thorough explanations for all technical elements, emphasizing technical sophistication and engineering excellence -- Guide readers to understand advanced technical concepts and implementation strategies -- ALL content must be based on thorough repository analysis aligned with documentation_objective - -## Technical Content Structure Guidelines - -**TECHNICAL DOCUMENTATION METHODOLOGY:** -Generate documentation that demonstrates technical excellence through systematic technical analysis, tailored to the specific technical patterns and implementation approaches of each project. Ensure documentation accurately reflects the technical sophistication and engineering excellence of the implementation. - -**TECHNICAL CONTENT ORGANIZATION PRINCIPLES:** -- Structure content to match developer technical learning patterns and advancement -- Begin with technical challenges and context before presenting technical solutions -- Build technical knowledge systematically, with each section building upon technical concepts -- Provide examples that reflect sophisticated technical implementation scenarios -- Explain technical approaches, implementation contexts, and technical consequences -- Anticipate advanced technical challenges and provide guidance for technical problem-solving - -**ENGINEERING DOCUMENTATION METHODOLOGY:** -- Begin each section by setting up the engineering challenge or design problem, then walk through the solution like you're explaining it to a colleague -- Use concrete examples, real scenarios, and practical implications to illustrate technical concepts rather than abstract descriptions -- Reveal the reasoning behind design decisions by analyzing code patterns, file organization, and implementation choices - like reverse-engineering the developer's thought process -- Frame technical discussions around the problems being solved, making the engineering decisions feel natural and well-motivated -- Highlight clever solutions, interesting patterns, performance considerations, and architectural trade-offs that other developers would find valuable -- Maintain technical rigor while writing in an engaging, accessible style that feels like a senior developer sharing insights -- Use strategic code examples to support your analysis and explanations, showing the actual implementation that backs up your technical insights - -**TECHNICAL OUTPUT FORMAT REQUIREMENTS:** - -## Technical Citation Implementation Guidelines - -**TECHNICAL CITATION REQUIREMENTS (EXAMPLES):** -- When explaining technical architecture: "The system adopts advanced microservice architecture patterns to ensure high scalability[^1]" -- When describing technical patterns: "Implements complex asynchronous processing patterns to optimize system performance[^2]" -- When referencing technical decisions: "Database sharding strategy based on business requirements and technical considerations[^3]" -- When explaining technical excellence: "Cache layer design demonstrates the technical expertise of system engineers[^4]" -- When discussing technical optimizations: "Algorithm optimization strategies significantly improve processing efficiency and response time[^5]" -- When analyzing technical innovations: "Innovative state management mechanism solves complex concurrency issues[^6]" - -**TECHNICAL CITATION FORMAT EXAMPLES:** -- For technical class reference: `[^1]: [Core Technical Service Implementation]({{$git_repository}}/tree/{{$branch}}/src/Technical/Core/TechnicalService.cs#L25)` -- For technical method reference: `[^2]: [Advanced Technical Processing Method]({{$git_repository}}/tree/{{$branch}}/src/Technical/Processing/AdvancedProcessor.cs#L89-L156)` -- For technical configuration reference: `[^3]: [Technical Configuration Constants Definition]({{$git_repository}}/tree/{{$branch}}/src/Technical/Config/TechnicalConstants.cs#L15)` - -**TECHNICAL CITATION PLACEMENT:** -- Add `[^n]` immediately after the technical content, before punctuation -- Include all citations as footnotes at the end of the document -- Number citations sequentially starting from [^1] -- Ensure every citation number has a corresponding technical footnote reference - -**TECHNICAL DOCUMENTATION STYLE STANDARDS:** -- Write as a technical expert who understands advanced engineering concepts and implementation excellence -- Explicitly state technical assumptions and provide pathways for advanced technical understanding -- Share not just technical facts, but technical insights and engineering wisdom -- Acknowledge advanced technical challenges and provide expert technical guidance -- Present technical information in layers, allowing readers to advance their technical understanding -- Support all technical claims with actual code references while weaving them into compelling technical explanations - -# TECHNICAL EXECUTION PROTOCOLS - -## Mandatory Technical Cognitive Process - -Establish systematic technical approach to ensure COMPLETE, COMPREHENSIVE technical analysis while maintaining technical accuracy and practical value for technical decision-makers and advanced developers. - - -**CRITICAL TECHNICAL SUCCESS FACTORS:** -1. **Technical Authority Excellence**: Combine deep technical understanding with advanced engineering expertise -2. **Technical Architecture Narrative**: Present technical information as a coherent technical story following advanced engineering patterns -3. **Technical Code Fidelity**: Every technical claim must be traceable to actual technical implementations while explaining advanced technical implications -4. **Technical Wisdom Integration**: Go beyond describing technical implementations to explain advanced technical reasoning and engineering excellence -5. **Technical Cognitive Optimization**: Structure technical information to maximize technical understanding and engineering comprehension -6. **Advanced Technical Grounding**: All technical examples and explanations must demonstrate sophisticated engineering and technical excellence - -## Technical Quality Assurance Protocol - -Multi-layered technical validation ensures COMPLETE documentation meets enterprise technical standards and serves as authoritative technical resource for advanced technical professionals. - -The validation must ensure: -1. Repository analysis was comprehensive and based on documentation_objective -2. ALL content is complete and persisted via Docs tools (Write/Edit), not printed directly in chat -3. Technical accuracy and citation completeness -4. Comprehensive Mermaid diagram inclusion - - -**COMPREHENSIVE TECHNICAL VALIDATION CHECKLIST:** -- Confirm that ALL technical claims, architectural descriptions, and implementation details are directly traceable to specific content in the provided code files -- Verify that at least 3 Mermaid diagrams are included, covering technical architecture, component relationships, data flows, and technical processes -- Ensure every diagram element corresponds to actual technical components, classes, functions, or processes found in the analyzed files -- Confirm that all major technical patterns, technical logic flows, and component interactions are properly visualized -- Verify that every technical reference, function description, and technical detail can be located in the actual code files with specific file paths and line numbers -- Ensure all described technical functionality actually exists in the provided code files and is described accurately without speculation -- Verify that all major technical components, classes, functions, and configurations present in the code files are appropriately covered -- Ensure documentation addresses advanced technical needs effectively and provides clear, actionable technical guidance -- Verify that technical information progression facilitates efficient technical knowledge acquisition and advanced implementation -- Confirm all file paths, technical references, and technical details are accurate and verifiable against the provided code files -- Ensure technical details are presented with appropriate technical context and explanatory framework derived from actual technical implementation -- Verify that technical design decisions and architectural choices are thoroughly explained with underlying technical rationale supported by code evidence -- Confirm that technical content flows logically and supports effective technical comprehension based on actual technical structure -- Ensure technical examples and explanations reflect realistic advanced implementation scenarios found in the actual code files -- Verify that each major section provides sufficient technical depth and completeness appropriate to its scope (no fixed word counts) -- Confirm appropriate density of [^n] citations throughout the documentation with every major technical claim properly referenced -- Ensure all performance claims, optimization strategies, and technical innovations are backed by actual code evidence, not fabricated data -- Verify that industry comparisons and best practice analyses are grounded in observable implementation choices, not speculative assertions -- Confirm that innovation claims are supported by actual novel implementation techniques or architectural approaches found in the codebase -- Ensure all performance-related analysis is based on actual optimization techniques, caching strategies, and efficiency patterns present in the code -- Verify that documentation covers technical architecture, performance, security, scalability, maintainability, and innovation dimensions -- Ensure every [^n] citation points to verifiable code locations with correct file paths and line numbers -- Confirm that technical analysis goes beyond surface-level description to provide deep architectural insights and engineering wisdom - -## Technical Documentation Standards Framework - -Establish clear quantitative and qualitative technical standards that ensure COMPLETE, COMPREHENSIVE documentation serves as definitive technical resource comparable to major open source technical projects. - -The framework must ensure: -- Complete repository analysis based on documentation_objective -- FULL content generation meeting all requirements -- Professional technical documentation standards - - -**COMPREHENSIVE TECHNICAL CONTENT DEPTH REQUIREMENTS:** -- Extensive comprehensive technical analysis without artificial length limitations - aim for maximum depth, detail, and insight, focusing entirely on technical understanding and engineering excellence based solely on actual repository implementation -- Deep, exhaustive examination of core technical processes, decision-making logic, and implementation rationale with extensive technical prose explanation (aim for comprehensive coverage without word count restrictions, derived exclusively from actual code analysis) -- In-depth, comprehensive technical examination of design decisions and their technical implications through purely descriptive technical analysis (extensive detail based on verifiable implementation) -- Comprehensive actionable insights about technical impact, process optimization, and strategic technical implementation considerations (thorough analysis grounded in actual code evidence) -- Extensive, detailed analysis comparing actual implementation approaches with industry standards, based only on observable patterns in the codebase (comprehensive comparative analysis) -- Detailed, thorough examination of actual performance characteristics and optimization strategies found in the code, NO fabricated performance data (comprehensive performance analysis) -- Extensive, detailed analysis of practical usage patterns evident from the actual implementation and configuration (comprehensive scenario analysis) -- Comprehensive analysis of innovative approaches and architectural decisions actually present in the codebase (thorough innovation analysis) -- Comprehensive, detailed examination of security implementations, error handling patterns, and reliability mechanisms (extensive security analysis) -- Detailed, comprehensive analysis of scalability patterns and evolutionary design considerations evident in the codebase (thorough scalability analysis) -- Comprehensive assessment of API design, documentation patterns, and developer tooling based on actual implementation (extensive UX analysis) -- Detailed, thorough examination of external integrations, dependency management, and ecosystem positioning (comprehensive integration analysis) -- Comprehensive analysis of configuration management, environment handling, and deployment strategies (extensive deployment analysis) -- Detailed assessment of logging, metrics, debugging, and operational support capabilities (comprehensive observability analysis) -- Comprehensive analysis of system evolution, design decision history, and future adaptability considerations (extensive evolution analysis) -- Detailed examination of platform support, compatibility considerations, and portability strategies (comprehensive compatibility analysis) -- Analysis of community support, ecosystem positioning, and collaborative development aspects (extensive community analysis) -- Enterprise-grade formatting and technical communication standards with strategic code examples and zero data fabrication - -## DIÁTAXIS CONTENT GENERATION FRAMEWORK - -**TYPE-SPECIFIC CONTENT STRATEGIES:** - -### Tutorial Content Strategy (Learning + Practical) -**Core Principle**: Guarantee learning success through guided experience -**Content Requirements**: -- Clear, linear progression with concrete outcomes -- Checkpoints that confirm learner progress -- Active doing rather than passive reading -- Anticipate and prevent common mistakes -- Each step builds competence and confidence -- Focus on one learning objective at a time - -### How-to Guide Strategy (Work + Practical) -**Core Principle**: Help competent users achieve specific goals -**Content Requirements**: -- Start with clear objective, end with achievement -- Actionable instructions for real-world scenarios -- Acknowledge different situations and variations -- Address specific problems users actually face -- Shortest path to goal achievement -- Instructions work in various contexts - -### Reference Content Strategy (Work + Theoretical) -**Core Principle**: Provide authoritative, factual information -**Content Requirements**: -- Complete and accurate technical specifications -- Objective descriptions without opinions or guidance -- Consistent structure for quick lookup -- Precise, verified technical information -- Organized for efficient information retrieval -- What the system does, not how to use it - -### Explanation Content Strategy (Learning + Theoretical) -**Core Principle**: Deepen understanding through context and reasoning -**Content Requirements**: -- Clear explanation of underlying principles -- Why decisions were made and trade-offs considered -- Historical, comparative, and ecosystem perspectives -- Links between concepts and broader understanding -- Different ways to understand the same concept -- Deeper insight beyond surface-level description - -**DIÁTAXIS INTEGRATION STRATEGIES:** -- Keep each content type focused on its specific user context -- Link to other types when users naturally transition -- Understand how users move between documentation types -- Clear indicators of what type of content users are reading - -## TECHNICAL EXCELLENCE SECTION STRUCTURE FRAMEWORK - -**MANDATORY TECHNICAL SECTION ORGANIZATION:** - -### Technical Section Structure Template (REQUIRED for every major technical topic): - -**1. Engineering Context and Problem Statement** -- Start by explaining what engineering challenge this component addresses - what problem were the developers trying to solve? -- Describe the real-world scenarios and use cases that drove the need for this particular solution -- Analyze the constraints and requirements that shaped the technical approach, based on evidence from the implementation -- Explain how this component fits into the larger system architecture and why it was designed this way -- Discuss the trade-offs and design decisions that are evident from examining the codebase structure -- Set up the technical narrative by explaining what makes this implementation interesting or noteworthy from an engineering perspective -- Ground all analysis in actual code evidence - what the implementation reveals about the developers' thinking - -**2. Architectural Deep Dive and Design Patterns** -- Walk through the architectural decisions like a code reviewer, explaining what the developers built and why it makes sense -- Analyze the component's relationships and dependencies by examining how it connects to other parts of the system -- Explain the design patterns and architectural principles at play, using the actual implementation as evidence -- Discuss how the code structure reveals the developers' approach to separation of concerns, modularity, and maintainability -- Examine the data flow and control flow patterns, explaining how information moves through the system -- Analyze error handling strategies and reliability patterns that demonstrate thoughtful engineering -- Explore extensibility mechanisms and how the architecture supports future changes and enhancements -- Include strategic code examples that illustrate key architectural concepts and design decisions[^n] - -**3. Implementation Analysis and Engineering Insights** -- Examine the actual implementation like a senior developer reviewing code, highlighting interesting technical choices -- Analyze runtime behavior and performance characteristics based on the algorithms and data structures used -- Explain state management and lifecycle patterns, showing how the component handles different operational scenarios -- Discuss error handling and edge case management, revealing the robustness of the implementation -- Explore concurrency and threading patterns, explaining how the code handles parallel operations and resource contention -- Analyze optimization techniques and performance considerations evident in the implementation -- Examine security and validation mechanisms, showing how the code protects against common vulnerabilities -- Include concrete code examples that demonstrate key implementation patterns and technical decisions[^n] -- Discuss monitoring, logging, and debugging features that show operational maturity - -**4. Developer Experience and Practical Usage** -- Analyze the implementation from a user's perspective - how easy is it to understand, use, and extend? -- Examine the API design and developer interface, highlighting thoughtful design choices -- Discuss configuration and customization options, showing how the system adapts to different use cases -- Explore testing strategies and quality assurance patterns that ensure reliability -- Analyze deployment and operational considerations that affect real-world usage -- Show practical examples of how developers would interact with this component in typical scenarios[^n] -- Discuss common gotchas, edge cases, and troubleshooting approaches based on the implementation -- Examine documentation patterns and developer guidance built into the code -- Analyze maintainability aspects - how the code is organized for long-term evolution and team collaboration - -**5. Key Code Examples and Technical Insights** -- Present the most important and illustrative code snippets that reveal the engineering approach[^n] -- Explain each code example in detail, walking through the logic and design decisions -- Highlight clever implementations, performance optimizations, or elegant solutions -- Show how different pieces of code work together to solve the overall problem -- Include configuration examples and usage patterns that demonstrate practical application[^n] -- Discuss code quality aspects - readability, maintainability, and adherence to best practices -- Point out any innovative or unusual approaches that other developers might find interesting - -**6. Performance and Optimization Analysis (comprehensive performance examination)** -- Analyze actual performance characteristics and optimization strategies implemented in the codebase[^n] -- Examine scalability patterns, load handling capabilities, and resource management approaches actually present in the code[^n] -- Discuss caching strategies, data access patterns, and efficiency optimizations based on actual implementation[^n] -- Evaluate memory management and resource utilization patterns found in the actual codebase[^n] -- Assess monitoring, profiling, and performance measurement capabilities actually implemented[^n] -- NO FABRICATED PERFORMANCE DATA - ONLY ANALYSIS OF ACTUAL OPTIMIZATION TECHNIQUES AND PATTERNS - -**7. Industry Best Practices and Comparative Analysis (extensive comparative analysis)** -- Compare the actual implementation approach with observable industry patterns evident in the technology choices and architectural decisions[^n] -- Analyze how the actual solution aligns with or deviates from common patterns based on framework usage and design choices[^n] -- Discuss the advantages and innovations evident in the actual implementation compared to standard approaches[^n] -- Evaluate the actual implementation against established architectural principles visible in the code organization[^n] -- Assess the solution's ecosystem integration based on actual dependencies and integration patterns[^n] -- ALL COMPARISONS MUST BE BASED ON OBSERVABLE EVIDENCE IN THE ACTUAL CODEBASE - -**8. Real-world Application and Integration Scenarios (comprehensive scenario analysis)** -- Analyze practical usage patterns evident from actual configuration files, deployment scripts, and setup documentation[^n] -- Examine integration requirements and compatibility considerations based on actual dependency management and API designs[^n] -- Discuss operational requirements evident from actual monitoring, logging, and maintenance code[^n] -- Evaluate user experience and developer experience based on actual API design, documentation, and tooling[^n] -- Assess migration and upgrade considerations based on actual versioning strategies and compatibility mechanisms[^n] -- ALL SCENARIOS MUST BE DERIVED FROM ACTUAL REPOSITORY EVIDENCE - -**9. Technical Innovation and Future Evolution (thorough innovation and evolution analysis)** -- Identify innovative technical approaches actually implemented in the codebase[^n] -- Analyze forward-thinking aspects evident in the actual architectural decisions and implementation patterns[^n] -- Discuss extensibility mechanisms actually built into the system based on plugin architectures, configuration systems, and extension points[^n] -- Evaluate the implementation's adaptability based on actual abstraction layers, configuration management, and modular design[^n] -- Assess technical advancement based on actual technology choices, implementation techniques, and architectural innovations[^n] -- ALL INNOVATION ANALYSIS MUST BE BASED ON ACTUAL IMPLEMENTATION EVIDENCE - NO SPECULATION - -**ENGINEERING DOCUMENTATION CONTENT PATTERNS:** -- Include code examples that best illustrate engineering decisions, interesting patterns, and key architectural concepts -- Lead with the engineering narrative and problem context before diving into implementation details -- Every code snippet should advance the technical story and reveal insights about the engineering approach -- Choose code examples that demonstrate practical usage, clever solutions, or architectural patterns that other developers can learn from -- Maintain engaging prose (70-80%) with well-chosen code examples (20-30%) that support the technical narrative -- Include configuration examples and usage patterns that show how the technology works in real scenarios - -**TECHNICAL PRE-DELIVERY CHECKLIST:** -1. Repository Analysis Completion**: Verify thorough repository analysis was conducted using tags based on documentation_objective requirements -2. Complete Content Generation**: Confirm ALL documentation sections are COMPLETE and COMPREHENSIVE - -3. Strategic Code Balance Verification**: Confirm appropriate balance of 90% conceptual analysis and 10% essential code examples for critical usage patterns -4. Citation and Code Integration**: Verify all technical references use proper [^n] citations with strategically selected code examples properly contextualized -5. ️ Technical Logic Analysis Depth**: Confirm comprehensive analysis of core technical processes, decision-making logic, and technical excellence -6. Technical Problem-Solution Mapping**: Verify clear explanation of what technical problems are solved and how technically -7. Technical Excellence Documentation**: Ensure thorough documentation of practical technical impact and real-world technical value delivery -8. Technical Implementation Reasoning Analysis**: Confirm detailed explanation of WHY certain technical approaches were chosen and their technical implications -9. Technical Process Coverage**: Verify all major technical workflows and decision points are analyzed and explained -10. Core Technical Logic Focus**: Ensure focus on actual technical implementation logic rather than peripheral technical details -11. Technical Citation Accuracy**: Validate all footnote references point to correct files and line numbers within the provided code files -12. Technical Citation Completeness**: Ensure every technical logic claim and implementation description includes appropriate [^n] citations -13. Technical Mermaid Diagrams**: Confirm at least 3 Mermaid diagrams focusing on technical processes and technical excellence -14. Technical Understanding Assessment**: Confirm documentation enables informed technical and implementation decisions based on actual technical code analysis -15. Documentation Objective Alignment**: Verify all content directly addresses and fulfills the specified documentation_objective requirements - -## Professional Technical Documentation Standards - -**ENGINEERING DOCUMENTATION AUTHORITY REQUIREMENTS:** -Write technical content that demonstrates the perspective of a senior engineer who has thoroughly investigated the codebase: -- Deep practical understanding of the implementation patterns and architectural decisions evident in the code -- Insight into the engineering challenges and how the implementation addresses them -- Comprehensive knowledge of the technology stack and its practical applications as used in this project -- Expert analysis of the trade-offs, optimizations, and design patterns that make this implementation noteworthy - -**ENGINEERING DOCUMENTATION WRITING PRINCIPLES:** -- Anticipate what fellow developers would find interesting and valuable about this implementation -- Highlight the technical problems being solved and explain how the implementation addresses them elegantly -- Present complex engineering concepts through engaging storytelling that builds understanding naturally -- Explain the reasoning behind architectural decisions and design patterns, revealing the engineering thought process -- Share insights about best practices, potential pitfalls, and lessons that other developers can apply to their own work - -**TECHNICAL DOCUMENTATION EXCELLENCE MANDATE**: - -See the mandatory execution sequence in the summary above. - -Generate comprehensive engineering documentation that reads like an experienced developer's deep exploration of an interesting codebase. Provide clear, evidence‑based explanations that reveal engineering insights, architectural decisions, and implementation rationale other developers will find valuable and actionable. - -# DIÁTAXIS QUALITY ASSURANCE SUMMARY - -## Final Validation Checklist - -- Content follows the identified Diátaxis type (Tutorial/How-to/Reference/Explanation) -- All content serves the specific user needs of the chosen type -- No mixing of different documentation types within content -- Minimum 3 Mermaid diagrams appropriate for documentation type added through Edit() -- [^n] references for all technical claims added via tool operations -- Content based on actual code analysis created through document generation tools -- {{$language}} content created entirely through Write() and Edit() operations \ No newline at end of file +**Quality Standards:** +- Minimum 5000 words total +- Minimum 5 Mermaid diagrams +- Every section must explain WHY, not just WHAT +- All claims must reference actual code patterns observed +- Focus on insights that demonstrate deep understanding + +## Phase 4: Strategic Enhancement (Maximum 3 Docs.MultiEdit) +Use your 3 MultiEdit operations strategically to maximize impact. + +**MultiEdit Strategy:** +1. **First MultiEdit - Technical Depth Enhancement**: + - Target 3-5 sections that need more technical detail + - Add algorithm complexity analysis + - Enhance architectural explanations + - Include more specific code patterns observed + +2. **Second MultiEdit - Visual Documentation**: + - Enhance existing diagrams with more detail + - Add missing relationship visualizations + - Ensure diagram-text alignment + +3. **Third MultiEdit - Polish and Completeness**: + - Add cross-references between related sections + - Ensure task requirements are fully met + - Add practical examples and use cases + - Final quality improvements + + + + +## Critical Tool Usage Rules + +**PARALLEL OPERATIONS (MANDATORY):** +- Always batch multiple operations in a single message for efficiency +- NEVER make sequential single operations +- Example: Read multiple sections in one operation, not one at a time + +**EDITING LIMITS (STRICT):** +- HARD LIMIT: Maximum 3 Docs.MultiEdit operations total +- Docs.Write: Use ONCE for complete initial creation +- Docs.Read: Unlimited (for verification only) +- Strategy: Make each MultiEdit count by bundling many changes + +**MULTIEDIT BEST PRACTICES:** +- Each operation should target multiple distinct sections +- Never edit overlapping content in the same operation +- Ensure unique, non-conflicting edit targets +- Group changes by proximity but maintain separation + +**EFFICIENCY REQUIREMENTS:** +- Complete initial document must be comprehensive (no skeleton drafts) +- Each MultiEdit must improve multiple sections simultaneously +- Verification reads don't count toward limits +- Focus on high-impact improvements + + + +Before completing, verify ALL items: + +1. ✅ **Planning Completed**: Used agent.think for comprehensive planning +2. ✅ **Complete Analysis**: Analyzed ALL files in +3. ✅ **Full Initial Write**: Created complete document (5000+ words) in single Write +4. ✅ **Strategic Edits**: Used ≤3 MultiEdit operations effectively +5. ✅ **Visual Documentation**: Included minimum 5 Mermaid diagrams +6. ✅ **Task Alignment**: All requirements in fully addressed +7. ✅ **Technical Depth**: Deep analysis of architecture, algorithms, patterns +8. ✅ **Evidence-Based**: Claims supported by actual code observations +9. ✅ **Why-Focused**: Explained rationale, not just implementation +10. ✅ **Actionable Insights**: Provided practical recommendations + + + +## Core Execution Principles + +**THINK BEFORE ACTING:** +- Always plan comprehensively before any documentation +- Understand the entire codebase before writing +- Strategic tool usage within strict limits + +**DEPTH OVER BREADTH:** +- Focus on critical components identified in planning +- Provide deep insights on important areas +- Quality explanations over surface coverage + +**EVIDENCE-BASED WRITING:** +- Every technical claim must be observable in code +- No speculation or assumptions +- Reference specific patterns and implementations + +**READER VALUE:** +- Explain WHY decisions were made +- Provide insights useful for maintenance +- Include practical, actionable recommendations + +**EFFICIENCY FOCUS:** +- Maximize each tool operation's impact +- Bundle changes for parallel execution +- Avoid redundant operations + + + +## Conditions That Will Cause Failure + +**IMMEDIATE FAILURES:** +- Skipping the agent.think planning phase +- Creating skeleton/incomplete initial documents +- Exceeding 3 MultiEdit operations +- Missing minimum diagram requirements +- Ignoring task requirements + +**QUALITY FAILURES:** +- Surface-level descriptions without analysis +- Missing WHY explanations +- No evidence-based claims +- Under 5000 words total +- Generic content not specific to the codebase + + +Remember: You are creating documentation that developers will rely on for understanding, maintaining, and extending this codebase. Every section should provide genuine value through deep technical insights based on thorough code analysis. \ No newline at end of file diff --git a/src/KoalaWiki/Services/AI/ResponsesService.cs b/src/KoalaWiki/Services/AI/ResponsesService.cs index 73e3bf3d..75157ec4 100644 --- a/src/KoalaWiki/Services/AI/ResponsesService.cs +++ b/src/KoalaWiki/Services/AI/ResponsesService.cs @@ -11,7 +11,6 @@ using KoalaWiki.Tools; using Microsoft.AspNetCore.Mvc; using Microsoft.EntityFrameworkCore; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; using OpenAI.Chat; diff --git a/src/KoalaWiki/Services/DynamicConfigService.cs b/src/KoalaWiki/Services/DynamicConfigService.cs index 58dd93f4..986684a9 100644 --- a/src/KoalaWiki/Services/DynamicConfigService.cs +++ b/src/KoalaWiki/Services/DynamicConfigService.cs @@ -1,4 +1,3 @@ -using System; using System.Collections.Concurrent; using System.Text.Json; using KoalaWiki.Domains; diff --git a/src/KoalaWiki/Services/Feishu/FeishuBotService.cs b/src/KoalaWiki/Services/Feishu/FeishuBotService.cs index 34021f14..4720a711 100644 --- a/src/KoalaWiki/Services/Feishu/FeishuBotService.cs +++ b/src/KoalaWiki/Services/Feishu/FeishuBotService.cs @@ -1,5 +1,4 @@ using System.ClientModel.Primitives; -using System.Diagnostics; using System.Text; using System.Text.Json; using System.Text.Json.Nodes; diff --git a/src/KoalaWiki/Services/FineTuningService.cs b/src/KoalaWiki/Services/FineTuningService.cs index 127e30dc..216edfda 100644 --- a/src/KoalaWiki/Services/FineTuningService.cs +++ b/src/KoalaWiki/Services/FineTuningService.cs @@ -11,7 +11,6 @@ using KoalaWiki.Options; using Microsoft.AspNetCore.Authorization; using Microsoft.EntityFrameworkCore; -using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; diff --git a/src/KoalaWiki/Services/StatisticsBackgroundService.cs b/src/KoalaWiki/Services/StatisticsBackgroundService.cs index f4af52b3..b5abb469 100644 --- a/src/KoalaWiki/Services/StatisticsBackgroundService.cs +++ b/src/KoalaWiki/Services/StatisticsBackgroundService.cs @@ -1,5 +1,4 @@ using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; diff --git a/src/KoalaWiki/Services/WarehouseSyncService.cs b/src/KoalaWiki/Services/WarehouseSyncService.cs index b0d35bc0..53883c30 100644 --- a/src/KoalaWiki/Services/WarehouseSyncService.cs +++ b/src/KoalaWiki/Services/WarehouseSyncService.cs @@ -1,4 +1,3 @@ -using System.Text; using KoalaWiki.Core.DataAccess; using KoalaWiki.Domains; using KoalaWiki.Domains.Warehouse; diff --git a/src/KoalaWiki/Tools/FileTool.cs b/src/KoalaWiki/Tools/FileTool.cs index 70767901..12e3a856 100644 --- a/src/KoalaWiki/Tools/FileTool.cs +++ b/src/KoalaWiki/Tools/FileTool.cs @@ -1,5 +1,4 @@ using System.ComponentModel; -using System.Text; using System.Text.Encodings.Web; using System.Text.Json; using System.Text.Json.Serialization; diff --git a/src/KoalaWiki/plugins/LanguagePromptFilter.cs b/src/KoalaWiki/plugins/LanguagePromptFilter.cs index 757eae40..2a625c74 100644 --- a/src/KoalaWiki/plugins/LanguagePromptFilter.cs +++ b/src/KoalaWiki/plugins/LanguagePromptFilter.cs @@ -1,5 +1,4 @@ using KoalaWiki.KoalaWarehouse; -using Microsoft.SemanticKernel; namespace KoalaWiki.plugins; From a3ae3881fbf4d78e6a9fccc36a12901aacbb549e Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Thu, 25 Sep 2025 02:07:43 +0800 Subject: [PATCH 06/14] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 14 +++++++++++++- README.zh-CN.md | 15 ++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ad4c0949..9ba5b920 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,19 @@ Example configuration: { "mcpServers": { "OpenDeepWiki":{ - "url": "http://Your OpenDeepWiki service IP:port/sse?owner=AIDotNet&name=OpenDeepWiki" + "url": "http://Your OpenDeepWiki service IP:port/api/mcp?owner=AIDotNet&name=OpenDeepWiki" + } + } +} +``` + +If mcp streamable http is not supported, use the following format: +```json + +{ + "mcpServers": { + "OpenDeepWiki":{ + "url": "http://Your OpenDeepWiki service IP:port/api/mcp/sse?owner=AIDotNet&name=OpenDeepWiki" } } } diff --git a/README.zh-CN.md b/README.zh-CN.md index 5c7d203e..cbd69dd1 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -72,7 +72,20 @@ OpenDeepWiki支持MCP协议： { "mcpServers": { "OpenDeepWiki":{ - "url": "http://Your OpenDeepWiki service IP:port/sse?owner=AIDotNet&name=OpenDeepWiki" + "url": "http://Your OpenDeepWiki service IP:port/api/mcp?owner=AIDotNet&name=OpenDeepWiki" + } + } +} +``` + +如果不支持mcp streamable http则使用下面格式： + +```json +{ + "mcpServers": { + "OpenDeepWiki":{ + "url": "http://Your OpenDeepWiki service IP:port/api/mcp/sse?owner=AIDotNet&name=OpenDeepWiki", + "supportsStreamableHttp": false } } } From 0c3ce62e25364c61deb413319f5175d2ae17c966 Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Thu, 25 Sep 2025 02:21:57 +0800 Subject: [PATCH 07/14] refactor: remove unused using directives and clean up code --- .../KoalaWarehouse/DocumentPending/DocumentPendingService.cs | 2 +- .../GenerateThinkCatalogue/GenerateThinkCatalogueService.cs | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index c40b41dc..9e040424 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -239,7 +239,7 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) break; case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: - Console.Write("[Tool Call]"); + break; case StreamingChatCompletionUpdate value: diff --git a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs index 90bc010b..fbe0be99 100644 --- a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs +++ b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs @@ -206,7 +206,6 @@ 3. Use catalog.Read after each MultiEdit to verify success before next operation break; case StreamingChatCompletionUpdate tool when tool.ToolCallUpdates.Count > 0: - Console.Write("[Tool Call]"); break; case StreamingChatCompletionUpdate value: From 4bd8bbd6f17550ea52c63ac888d694cb9b9bb891 Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Thu, 25 Sep 2025 10:01:53 +0800 Subject: [PATCH 08/14] Increase HTTP timeouts and adjust retry logic Extended HttpClient timeout from 60 to 240 seconds in KernelFactory for both OpenAI and AzureOpenAI providers. In KoalaHttpClientHandler, added a 20-second timeout for reading error content and reduced retry delay from 3 seconds to 1 second to improve responsiveness. --- src/KoalaWiki/KernelFactory.cs | 4 ++-- src/KoalaWiki/KoalaHttpClientHander.cs | 7 +++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/src/KoalaWiki/KernelFactory.cs b/src/KoalaWiki/KernelFactory.cs index 7e40dd44..336acfeb 100644 --- a/src/KoalaWiki/KernelFactory.cs +++ b/src/KoalaWiki/KernelFactory.cs @@ -46,7 +46,7 @@ public static Kernel GetKernel(string chatEndpoint, DecompressionMethods.None }) { - Timeout = TimeSpan.FromSeconds(60), + Timeout = TimeSpan.FromSeconds(240), }); } else if (OpenAIOptions.ModelProvider.Equals("AzureOpenAI", StringComparison.OrdinalIgnoreCase)) @@ -60,7 +60,7 @@ public static Kernel GetKernel(string chatEndpoint, DecompressionMethods.None }) { - Timeout = TimeSpan.FromSeconds(60), + Timeout = TimeSpan.FromSeconds(240), }); } else diff --git a/src/KoalaWiki/KoalaHttpClientHander.cs b/src/KoalaWiki/KoalaHttpClientHander.cs index ce4fc5b6..73168625 100644 --- a/src/KoalaWiki/KoalaHttpClientHander.cs +++ b/src/KoalaWiki/KoalaHttpClientHander.cs @@ -84,7 +84,10 @@ protected override async Task SendAsync( { break; } - var errorContent = await response.Content.ReadAsStringAsync(cancellationToken); + + var sendToken = new CancellationTokenSource(); + sendToken.CancelAfter(20000); // 10秒超时 + var errorContent = await response.Content.ReadAsStringAsync(sendToken.Token); Log.Logger.Warning("HTTP request failed, attempt {Attempt}: {StatusCode} {ErrorMessage}", i + 1, (int)response.StatusCode, errorContent); if (i == 2) @@ -106,7 +109,7 @@ protected override async Task SendAsync( throw; // 最后一次失败，抛出异常 } - await Task.Delay(3000, cancellationToken); // 等待一秒后重试 + await Task.Delay(1000, cancellationToken); // 等待一秒后重试 continue; } } From 7fa8e8cb7077d3f4c523be4af3efb1f5c6030753 Mon Sep 17 00:00:00 2001 From: token <239573049@qq.com> Date: Thu, 25 Sep 2025 10:02:05 +0800 Subject: [PATCH 09/14] Increase HTTP request timeout to 30 seconds Changed the cancellation timeout for HTTP requests from 20 seconds to 30 seconds to allow more time for responses before timing out. --- src/KoalaWiki/KoalaHttpClientHander.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/KoalaWiki/KoalaHttpClientHander.cs b/src/KoalaWiki/KoalaHttpClientHander.cs index 73168625..ab9fbb20 100644 --- a/src/KoalaWiki/KoalaHttpClientHander.cs +++ b/src/KoalaWiki/KoalaHttpClientHander.cs @@ -86,7 +86,7 @@ protected override async Task SendAsync( } var sendToken = new CancellationTokenSource(); - sendToken.CancelAfter(20000); // 10秒超时 + sendToken.CancelAfter(30000); // 30秒超时 var errorContent = await response.Content.ReadAsStringAsync(sendToken.Token); Log.Logger.Warning("HTTP request failed, attempt {Attempt}: {StatusCode} {ErrorMessage}", i + 1, (int)response.StatusCode, errorContent); From ed86c6ba567094f9754d32477cec8f724b772623 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Thu, 25 Sep 2025 10:12:54 +0800 Subject: [PATCH 10/14] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=9E=84=E5=BB=BA=E5=92=8C=E5=90=AF=E5=8A=A8=E8=84=9A?= =?UTF-8?q?=E6=9C=AC=EF=BC=8C=E7=AE=80=E5=8C=96docker-compose=E9=85=8D?= =?UTF-8?q?=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除单独的前端启动脚本，合并到统一的启动脚本中 简化Makefile中的前端构建相关命令 为docker-compose添加aspire-dashboard端口映射 移除不再使用的前端服务容器配置 --- Makefile | 26 ++++++-------------------- docker-compose-mem0.yml | 2 ++ docker-compose-mysql.yml | 23 +++-------------------- docker-compose.yml | 2 ++ start-frontend.bat | 2 -- start-frontend.sh | 4 ---- start-backend.bat => start.bat | 11 +++++++++++ start-backend.sh => start.sh | 13 ++++++++++++- 8 files changed, 36 insertions(+), 47 deletions(-) delete mode 100644 start-frontend.bat delete mode 100644 start-frontend.sh rename start-backend.bat => start.bat (82%) rename start-backend.sh => start.sh (81%) diff --git a/Makefile b/Makefile index 97ebf5b3..3accb60e 100644 --- a/Makefile +++ b/Makefile @@ -1,21 +1,22 @@ # 检测是否支持 docker compose DOCKER_COMPOSE := $(shell if docker compose version >/dev/null 2>&1; then echo "docker compose"; else echo "docker-compose"; fi) -.PHONY: all build build-backend build-frontend build-arm build-amd build-backend-arm build-frontend-arm build-backend-amd build-frontend-amd up down restart dev dev-backend dev-frontend logs clean help +.PHONY: all build build-backend build-frontend build-arm build-amd build-backend-arm build-backend-amd up down restart dev dev-backend logs clean help all: build up # 构建所有Docker镜像 -build: +build: build-frontend $(DOCKER_COMPOSE) build # 只构建后端服务 build-backend: $(DOCKER_COMPOSE) build koalawiki -# 只构建前端服务 +# 构建前端项目 build-frontend: - $(DOCKER_COMPOSE) build koalawiki-web + @echo "Building frontend..." + cd web-site && npm install && npm run build # 构建ARM架构的所有Docker镜像 build-arm: @@ -29,18 +30,10 @@ build-amd: build-backend-arm: $(DOCKER_COMPOSE) build --build-arg ARCH=arm64 koalawiki -# 构建ARM架构的前端服务 -build-frontend-arm: - $(DOCKER_COMPOSE) build --build-arg ARCH=arm64 koalawiki-web - # 构建AMD架构的后端服务 build-backend-amd: $(DOCKER_COMPOSE) build --build-arg ARCH=amd64 koalawiki -# 构建AMD架构的前端服务 -build-frontend-amd: - $(DOCKER_COMPOSE) build --build-arg ARCH=amd64 koalawiki-web - # 启动所有服务 up: $(DOCKER_COMPOSE) up -d @@ -60,10 +53,6 @@ dev: dev-backend: $(DOCKER_COMPOSE) up koalawiki -# 只启动前端开发环境 -dev-frontend: - $(DOCKER_COMPOSE) up koalawiki-web - # 查看服务日志 logs: $(DOCKER_COMPOSE) logs -f @@ -77,19 +66,16 @@ help: @echo "使用方法:" @echo " make build - 构建所有Docker镜像" @echo " make build-backend - 只构建后端服务" - @echo " make build-frontend - 只构建前端服务" + @echo " make build-frontend - 构建前端项目" @echo " make build-arm - 构建ARM架构的所有镜像" @echo " make build-amd - 构建AMD架构的所有镜像" @echo " make build-backend-arm - 构建ARM架构的后端服务" - @echo " make build-frontend-arm - 构建ARM架构的前端服务" @echo " make build-backend-amd - 构建AMD架构的后端服务" - @echo " make build-frontend-amd - 构建AMD架构的前端服务" @echo " make up - 启动所有服务（后台模式）" @echo " make down - 停止所有服务" @echo " make restart - 重启所有服务" @echo " make dev - 启动开发环境（非后台模式，可查看日志）" @echo " make dev-backend - 只启动后端开发环境" - @echo " make dev-frontend - 只启动前端开发环境" @echo " make logs - 查看服务日志" @echo " make clean - 清理所有Docker资源（慎用）" @echo " make help - 显示此帮助信息" diff --git a/docker-compose-mem0.yml b/docker-compose-mem0.yml index 1972be50..a414696c 100644 --- a/docker-compose-mem0.yml +++ b/docker-compose-mem0.yml @@ -113,6 +113,8 @@ image: mcr.microsoft.com/dotnet/aspire-dashboard container_name: aspire-dashboard restart: always + ports: + - "18888:18888" environment: - TZ=Asia/Shanghai - Dashboard:ApplicationName=Aspire diff --git a/docker-compose-mysql.yml b/docker-compose-mysql.yml index 09f2d72a..6a77b280 100644 --- a/docker-compose-mysql.yml +++ b/docker-compose-mysql.yml @@ -19,6 +19,7 @@ koalawiki: image: crpi-j9ha7sxwhatgtvj4.cn-shenzhen.personal.cr.aliyuncs.com/koala-ai/koala-wiki environment: + - TZ=Asia/Shanghai - KOALAWIKI_REPOSITORIES=/repositories - TASK_MAX_SIZE_PER_USER=5 # 每个用户AI处理文档生成的最大数量 - REPAIR_MERMAID=1 # 是否进行Mermaid修复，1修复，其余不修复 @@ -51,30 +52,12 @@ ports: - "8090:8080" - - koalawiki-web: - image: crpi-j9ha7sxwhatgtvj4.cn-shenzhen.personal.cr.aliyuncs.com/koala-ai/koala-wiki-web - command: ["/app/start.sh"] - environment: - - NEXT_PUBLIC_API_URL=http://koalawiki:8080 # 用于提供给server的地址 - build: - context: ./web - dockerfile: Dockerfile - - nginx: # 需要nginx将前端和后端代理到一个端口 - image: crpi-j9ha7sxwhatgtvj4.cn-shenzhen.personal.cr.aliyuncs.com/koala-ai/nginx:alpine - ports: - - 8090:80 - volumes: - - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf - depends_on: - - koalawiki - - koalawiki-web - aspire-dashboard: image: mcr.microsoft.com/dotnet/aspire-dashboard container_name: aspire-dashboard restart: always + ports: + - "18888:18888" environment: - TZ=Asia/Shanghai - Dashboard:ApplicationName=Aspire diff --git a/docker-compose.yml b/docker-compose.yml index 8e916ecd..63917b3a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -35,6 +35,8 @@ image: mcr.microsoft.com/dotnet/aspire-dashboard container_name: aspire-dashboard restart: always + ports: + - "18888:18888" environment: - TZ=Asia/Shanghai - Dashboard:ApplicationName=Aspire diff --git a/start-frontend.bat b/start-frontend.bat deleted file mode 100644 index 62538b30..00000000 --- a/start-frontend.bat +++ /dev/null @@ -1,2 +0,0 @@ -cd .next\standalone -node server.js \ No newline at end of file diff --git a/start-frontend.sh b/start-frontend.sh deleted file mode 100644 index 2d93db79..00000000 --- a/start-frontend.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash - -cd .next/standalone -node server.js \ No newline at end of file diff --git a/start-backend.bat b/start.bat similarity index 82% rename from start-backend.bat rename to start.bat index 492d7c9f..5d0c7d4d 100644 --- a/start-backend.bat +++ b/start.bat @@ -26,4 +26,15 @@ SET DEEP_RESEARCH_MODEL= REM 是否启用增量更新 SET ENABLE_INCREMENTAL_UPDATE=true +REM 构建前端项目 +echo Building frontend... +cd web-site +if not exist node_modules ( + echo Installing frontend dependencies... + npm install +) +echo Building frontend project... +npm run build +cd .. + "KoalaWiki.exe" \ No newline at end of file diff --git a/start-backend.sh b/start.sh similarity index 81% rename from start-backend.sh rename to start.sh index 30916a3f..46f818e0 100644 --- a/start-backend.sh +++ b/start.sh @@ -28,4 +28,15 @@ export DEEP_RESEARCH_MODEL= # 是否启用增量更新 export ENABLE_INCREMENTAL_UPDATE=true -./KoalaWiki \ No newline at end of file +# 构建前端项目 +echo "Building frontend..." +cd web-site +if [ ! -d "node_modules" ]; then + echo "Installing frontend dependencies..." + npm install +fi +echo "Building frontend project..." +npm run build +cd .. + +./KoalaWiki \ No newline at end of file From b7a96a04389c25d7794f99a71c9e83e75fc71d87 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Thu, 25 Sep 2025 10:32:56 +0800 Subject: [PATCH 11/14] =?UTF-8?q?style(DocumentFileItem):=20=E6=B8=85?= =?UTF-8?q?=E7=90=86=E4=BB=A3=E7=A0=81=E6=A0=BC=E5=BC=8F=E5=B9=B6=E5=88=9D?= =?UTF-8?q?=E5=A7=8B=E5=8C=96Content=E5=B1=9E=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除多余的空行并统一字典类型的空格格式 将Content属性初始化为空字符串以避免潜在的空引用异常 --- .../DocumentFile/DocumentFileItem.cs | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/KoalaWiki.Domains/DocumentFile/DocumentFileItem.cs b/KoalaWiki.Domains/DocumentFile/DocumentFileItem.cs index 36dd9ce6..45079e79 100644 --- a/KoalaWiki.Domains/DocumentFile/DocumentFileItem.cs +++ b/KoalaWiki.Domains/DocumentFile/DocumentFileItem.cs @@ -10,65 +10,65 @@ public class DocumentFileItem : Entity /// 标题 /// public string Title { get; set; } - + /// /// 描述 /// public string Description { get; set; } - + /// /// 文档实际内容 /// - public string Content { get; set; } - + public string Content { get; set; } = string.Empty; + /// /// 评论数量 /// public long CommentCount { get; set; } - + /// /// 文档大小 /// public long Size { get; set; } - + /// /// 绑定的目录ID /// public string DocumentCatalogId { get; set; } - + /// /// 请求token消耗 /// /// public int RequestToken { get; set; } - + /// /// 响应token /// public int ResponseToken { get; set; } - + /// /// 是否嵌入完成 /// public bool IsEmbedded { get; set; } - + /// /// 相关源文件 /// /// [NotMapped] - public List? Source { get; set; } - + public List? Source { get; set; } + /// /// 源数据 /// - public Dictionary Metadata { get; set; } = new(); - + public Dictionary Metadata { get; set; } = new(); + /// /// 扩展数据 /// - public Dictionary Extra { get; set; } = new(); - + public Dictionary Extra { get; set; } = new(); + /// /// i18n多语言支持导航属性 /// From c4b6f25d033752cefdd8d408d1ab7bff080d39be Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Thu, 25 Sep 2025 10:52:49 +0800 Subject: [PATCH 12/14] =?UTF-8?q?refactor:=20=E7=A7=BB=E9=99=A4MaxFileLimi?= =?UTF-8?q?t=E9=85=8D=E7=BD=AE=E5=B9=B6=E5=A2=9E=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=A4=84=E7=90=86=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 从DynamicOptionsManager中移除不再使用的MaxFileLimit配置项 - 在DocumentPendingService中添加详细的文档处理操作指南 - 将文档处理超时时间从20分钟延长至30分钟 --- .../DocumentPending/DocumentPendingService.cs | 30 +++++++++++++++++-- .../Options/DynamicOptionsManager.cs | 1 - 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index 9e040424..277f496c 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -184,6 +184,32 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) Header.tsx/F {Prompt.Language} + + ## Docs Tool Usage Guidelines + + **PARALLEL READ OPERATIONS** + - MANDATORY: Always perform PARALLEL File.Read calls — batch multiple files in a SINGLE message for maximum efficiency + - CRITICAL: Read MULTIPLE files simultaneously in one operation + - PROHIBITED: Sequential one-by-one file reads (inefficient and wastes context capacity) + + **EDITING OPERATION LIMITS** + - HARD LIMIT: Maximum of 3 editing operations total (Docs.MultiEdit only) + - PRIORITY: Maximize each Docs.MultiEdit operation by bundling ALL related changes across multiple files + - STRATEGIC PLANNING: Consolidate all modifications into minimal MultiEdit operations to stay within the limit + - Use Docs.Write **only once** for initial creation or full rebuild (counts as initial structure creation, not part of the 3 edits) + - Always verify content before further changes using Docs.Read (Reads do NOT count toward limit) + + **CRITICAL MULTIEDIT BEST PRACTICES** + - MAXIMIZE EFFICIENCY: Each MultiEdit should target multiple distinct sections across files + - AVOID CONFLICTS: Never edit overlapping or identical content regions within the same MultiEdit operation + - UNIQUE TARGETS: Ensure each edit instruction addresses a completely different section or file + - BATCH STRATEGY: Group all necessary changes by proximity and relevance, but maintain clear separation between edit targets + + **RECOMMENDED EDITING SEQUENCE** + 1. Initial creation → Docs.Write (one-time full structure creation) + 2. Bulk refinements → Docs.MultiEdit with maximum parallel changes (counts toward 3-operation limit) + 3. Validation → Use Docs.Read after each MultiEdit to verify success before next operation + 4. Final adjustments → Remaining MultiEdit operations for any missed changes """) }; @@ -208,9 +234,9 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) { // 创建新的取消令牌（每次重试都重新创建） token?.Dispose(); - token = new CancellationTokenSource(TimeSpan.FromMinutes(20)); // 20分钟超时 + token = new CancellationTokenSource(TimeSpan.FromMinutes(30)); // 20分钟超时 - Console.WriteLine($"开始处理文档 (尝试 {count}/{maxRetries + 1})，超时设置: 20分钟"); + Console.WriteLine($"开始处理文档 (尝试 {count}/{maxRetries + 1})，超时设置: 30分钟"); try { diff --git a/src/KoalaWiki/Options/DynamicOptionsManager.cs b/src/KoalaWiki/Options/DynamicOptionsManager.cs index 2bb6b35c..7876c51f 100644 --- a/src/KoalaWiki/Options/DynamicOptionsManager.cs +++ b/src/KoalaWiki/Options/DynamicOptionsManager.cs @@ -54,7 +54,6 @@ private async Task LoadOpenAIOptionsAsync() OpenAIOptions.ChatApiKey = await _configService.GetValueAsync("ChatApiKey") ?? ""; OpenAIOptions.Endpoint = await _configService.GetValueAsync("Endpoint") ?? ""; OpenAIOptions.ModelProvider = await _configService.GetValueAsync("ModelProvider") ?? "OpenAI"; - OpenAIOptions.MaxFileLimit = await _configService.GetValueAsync("MaxFileLimit", 10); OpenAIOptions.DeepResearchModel = await _configService.GetValueAsync("DeepResearchModel") ?? ""; OpenAIOptions.EnableMem0 = await _configService.GetValueAsync("EnableMem0", false); OpenAIOptions.Mem0ApiKey = await _configService.GetValueAsync("Mem0ApiKey") ?? ""; From b61f75517aee04390a303e85ec9f3d11e900a3b3 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Thu, 25 Sep 2025 11:29:39 +0800 Subject: [PATCH 13/14] =?UTF-8?q?docs(DocumentPendingService):=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E7=B3=BB=E7=BB=9F=E6=8F=90=E9=86=92=E5=86=85=E5=AE=B9?= =?UTF-8?q?=E4=BB=A5=E5=8A=A0=E5=BC=BA=E6=96=87=E6=A1=A3=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加了更严格的文档工具使用要求，包括强制使用Docs工具输出、禁止在聊天中直接显示文档内容、以及添加合规性验证步骤。这些修改旨在确保所有文档操作都通过专用工具完成，提高操作规范性和安全性。 --- .../DocumentPending/DocumentPendingService.cs | 98 +++++++++++-------- 1 file changed, 58 insertions(+), 40 deletions(-) diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index 277f496c..d2232bc9 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -172,46 +172,64 @@ await dbContext.DocumentCatalogs.Where(x => x.Id == catalog.Id) new TextContent(prompt), new TextContent( $""" - - For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. - Note: The repository's directory structure has been provided in . Please utilize the provided structure directly for file navigation and reading operations, rather than relying on glob patterns or filesystem traversal methods. - Below is an example of the directory structure of the warehouse, where /D represents a directory and /F represents a file: - server/D - src/D - Main/F - web/D - components/D - Header.tsx/F - - {Prompt.Language} - - ## Docs Tool Usage Guidelines - - **PARALLEL READ OPERATIONS** - - MANDATORY: Always perform PARALLEL File.Read calls — batch multiple files in a SINGLE message for maximum efficiency - - CRITICAL: Read MULTIPLE files simultaneously in one operation - - PROHIBITED: Sequential one-by-one file reads (inefficient and wastes context capacity) - - **EDITING OPERATION LIMITS** - - HARD LIMIT: Maximum of 3 editing operations total (Docs.MultiEdit only) - - PRIORITY: Maximize each Docs.MultiEdit operation by bundling ALL related changes across multiple files - - STRATEGIC PLANNING: Consolidate all modifications into minimal MultiEdit operations to stay within the limit - - Use Docs.Write **only once** for initial creation or full rebuild (counts as initial structure creation, not part of the 3 edits) - - Always verify content before further changes using Docs.Read (Reads do NOT count toward limit) - - **CRITICAL MULTIEDIT BEST PRACTICES** - - MAXIMIZE EFFICIENCY: Each MultiEdit should target multiple distinct sections across files - - AVOID CONFLICTS: Never edit overlapping or identical content regions within the same MultiEdit operation - - UNIQUE TARGETS: Ensure each edit instruction addresses a completely different section or file - - BATCH STRATEGY: Group all necessary changes by proximity and relevance, but maintain clear separation between edit targets - - **RECOMMENDED EDITING SEQUENCE** - 1. Initial creation → Docs.Write (one-time full structure creation) - 2. Bulk refinements → Docs.MultiEdit with maximum parallel changes (counts toward 3-operation limit) - 3. Validation → Use Docs.Read after each MultiEdit to verify success before next operation - 4. Final adjustments → Remaining MultiEdit operations for any missed changes - - """) + ```xml + + For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. + Note: The repository's directory structure has been provided in . Please utilize the provided structure directly for file navigation and reading operations, rather than relying on glob patterns or filesystem traversal methods. + Below is an example of the directory structure of the warehouse, where /D represents a directory and /F represents a file: + server/D + src/D + Main/F + web/D + components/D + Header.tsx/F + + {Prompt.Language} + + ## Docs Tool Usage Guidelines + + **MANDATORY TOOL USAGE** + - ABSOLUTE REQUIREMENT: ALL document generation, creation, editing, and output MUST use Docs tools exclusively + - STRICTLY PROHIBITED: Direct output of document content in chat responses + - CRITICAL: Never display document content directly in conversation - always use Docs.Write, Docs.MultiEdit, or Docs.Create + - ENFORCEMENT: Any document-related task must result in actual Docs tool invocation, not chat-based content delivery + + **PARALLEL READ OPERATIONS** + - MANDATORY: Always perform PARALLEL File.Read calls — batch multiple files in a SINGLE message for maximum efficiency + - CRITICAL: Read MULTIPLE files simultaneously in one operation + - PROHIBITED: Sequential one-by-one file reads (inefficient and wastes context capacity) + + **EDITING OPERATION LIMITS** + - HARD LIMIT: Maximum of 3 editing operations total (Docs.MultiEdit only) + - PRIORITY: Maximize each Docs.MultiEdit operation by bundling ALL related changes across multiple files + - STRATEGIC PLANNING: Consolidate all modifications into minimal MultiEdit operations to stay within the limit + - Use Docs.Write **only once** for initial creation or full rebuild (counts as initial structure creation, not part of the 3 edits) + - Always verify content before further changes using Docs.Read (Reads do NOT count toward limit) + + **CRITICAL MULTIEDIT BEST PRACTICES** + - MAXIMIZE EFFICIENCY: Each MultiEdit should target multiple distinct sections across files + - AVOID CONFLICTS: Never edit overlapping or identical content regions within the same MultiEdit operation + - UNIQUE TARGETS: Ensure each edit instruction addresses a completely different section or file + - BATCH STRATEGY: Group all necessary changes by proximity and relevance, but maintain clear separation between edit targets + + **DOCUMENT OUTPUT ENFORCEMENT** + - ZERO TOLERANCE: Never output complete documents or substantial document content directly in chat + - TOOL-FIRST APPROACH: Every document creation request must immediately trigger Docs tool usage + - NO EXCEPTIONS: Even for "previews," "examples," or "demonstrations" - use Docs tools to create actual files + - VERIFICATION METHOD: After tool usage, only provide brief status updates and file location information + + **RECOMMENDED EDITING SEQUENCE** + 1. Initial creation → Docs.Write (one-time full structure creation) + 2. Bulk refinements → Docs.MultiEdit with maximum parallel changes (counts toward 3-operation limit) + 3. Validation → Use Docs.Read after each MultiEdit to verify success before next operation + 4. Final adjustments → Remaining MultiEdit operations for any missed changes + + **COMPLIANCE VERIFICATION** + - SELF-CHECK: Before responding, verify that no substantial document content appears in your response + - TOOL CONFIRMATION: Ensure every document-related request results in actual Docs tool invocation + - STATUS REPORTING: Provide only brief summaries of what was created/modified, never the full content + + """) }; contents.AddDocsGenerateSystemReminder(); From bbd9295b4759920519f3975e206da04a388c607c Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Fri, 26 Sep 2025 11:55:11 +0800 Subject: [PATCH 14/14] Update Directory.Packages.props --- Directory.Packages.props | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Directory.Packages.props b/Directory.Packages.props index 9d5c33d5..3537d4ee 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -2,7 +2,7 @@ true $([System.DateTime]::UtcNow.ToString("yyyyMMdd")) - 0.9.3 + 0.9.4 OpenDeepWiki OpenDeepWiki - AI驱动的代码知识库 @@ -114,4 +114,4 @@ - \ No newline at end of file +