From 6df504f21023fc5b4ef91bd74c816e66816ec467 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:59:06 +0800 Subject: [PATCH 01/31] =?UTF-8?q?refactor(tools):=20=E9=87=8D=E6=9E=84?= =?UTF-8?q?=E5=B7=A5=E5=85=B7=E7=B1=BB=E5=91=BD=E5=90=8D=E5=92=8C=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=EF=BC=8C=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=E7=94=9F?= =?UTF-8?q?=E6=88=90=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将Function后缀的工具类统一重命名为Tool后缀，包括FileFunction改为FileTool，AgentFunction改为AgentTool等 新增RagTool、CodeAnalyzeTool、GithubTool和GiteeTool工具类 优化文档生成的质量验证逻辑，移除不必要的环境变量检查 调整文档精炼流程，增加多次迭代和自检步骤 更新提示模板，强化Diataxis文档标准和多轮自检要求 --- .vscode/settings.json | 3 +- docker-compose.yml | 2 + src/KoalaWiki/KernelFactory.cs | 6 +- .../DocumentPending/DocumentPendingService.cs | 31 +- .../GenerateThinkCatalogueService.cs | 117 +-- src/KoalaWiki/MCP/MCPExtensions.cs | 14 +- src/KoalaWiki/Prompts/PromptExtensions.cs | 10 +- .../Prompts/Warehouse/AnalyzeCatalogue.md | 56 +- .../Prompts/Warehouse/GenerateDocs.md | 842 +++++++----------- .../Prompts/Warehouse/GenerateMindMap.md | 36 +- src/KoalaWiki/Prompts/Warehouse/Overview.md | 671 -------------- src/KoalaWiki/Properties/launchSettings.json | 2 +- src/KoalaWiki/Services/AI/ResponsesService.cs | 6 +- src/KoalaWiki/Services/WarehouseService.cs | 4 +- .../Tools/{AgentFunction.cs => AgentTool.cs} | 4 +- ...eAnalyzeFunction.cs => CodeAnalyzeTool.cs} | 2 +- .../Tools/{FileFunction.cs => FileTool.cs} | 173 +++- .../Tools/{GiteeFunction.cs => GiteeTool.cs} | 4 +- .../{GithubFunction.cs => GithubTool.cs} | 6 +- .../Tools/{RagFunction.cs => RagTool.cs} | 4 +- 20 files changed, 565 insertions(+), 1428 deletions(-) delete mode 100644 src/KoalaWiki/Prompts/Warehouse/Overview.md rename src/KoalaWiki/Tools/{AgentFunction.cs => AgentTool.cs} (99%) rename src/KoalaWiki/Tools/{CodeAnalyzeFunction.cs => CodeAnalyzeTool.cs} (98%) rename src/KoalaWiki/Tools/{FileFunction.cs => FileTool.cs} (74%) rename src/KoalaWiki/Tools/{GiteeFunction.cs => GiteeTool.cs} (99%) rename src/KoalaWiki/Tools/{GithubFunction.cs => GithubTool.cs} (97%) rename src/KoalaWiki/Tools/{RagFunction.cs => RagTool.cs} (87%) diff --git a/.vscode/settings.json b/.vscode/settings.json index 02be5782..865e17a5 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,4 @@ { - "chatgpt.openOnStartup": true + "chatgpt.openOnStartup": true, + "markdown.validate.enabled": true } \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index e6281758..76a967f8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -52,6 +52,8 @@ image: mcr.microsoft.com/dotnet/aspire-dashboard container_name: aspire-dashboard restart: always + ports: + - 18889:18889 environment: - TZ=Asia/Shanghai - Dashboard:ApplicationName=Aspire \ No newline at end of file diff --git a/src/KoalaWiki/KernelFactory.cs b/src/KoalaWiki/KernelFactory.cs index 4d022aed..6203448d 100644 --- a/src/KoalaWiki/KernelFactory.cs +++ b/src/KoalaWiki/KernelFactory.cs @@ -100,14 +100,14 @@ public static Kernel GetKernel(string chatEndpoint, } // 添加文件函数 - var fileFunction = new FileFunction(gitPath, files); + var fileFunction = new FileTool(gitPath, files); kernelBuilder.Plugins.AddFromObject(fileFunction); - kernelBuilder.Plugins.AddFromType(); + kernelBuilder.Plugins.AddFromType(); activity?.SetTag("plugins.file_function", "loaded"); if (DocumentOptions.EnableCodeDependencyAnalysis) { - var codeAnalyzeFunction = new CodeAnalyzeFunction(gitPath); + var codeAnalyzeFunction = new CodeAnalyzeTool(gitPath); kernelBuilder.Plugins.AddFromObject(codeAnalyzeFunction); activity?.SetTag("plugins.code_analyze_function", "loaded"); } diff --git a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs index a009ff11..a7bee12f 100644 --- a/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs +++ b/src/KoalaWiki/KoalaWarehouse/DocumentPending/DocumentPendingService.cs @@ -11,10 +11,8 @@ namespace KoalaWiki.KoalaWarehouse.DocumentPending; public partial class DocumentPendingService { - private static int TaskMaxSizePerUser = 5; + private static int TaskMaxSizePerUser = 3; private static int MinContentLength = 1000; - private static int MinMermaidDiagrams = 3; - private static int MinCitations = 5; private static double MinQualityScore = 60.0; private static double MinChineseRatio = 0.3; @@ -33,19 +31,7 @@ static DocumentPendingService() { MinContentLength = lengthInt; } - - var minMermaid = Environment.GetEnvironmentVariable("DOC_MIN_MERMAID_DIAGRAMS").GetTrimmedValueOrEmpty(); - if (!string.IsNullOrEmpty(minMermaid) && int.TryParse(minMermaid, out var mermaidInt)) - { - MinMermaidDiagrams = mermaidInt; - } - - var minCite = Environment.GetEnvironmentVariable("DOC_MIN_CITATIONS").GetTrimmedValueOrEmpty(); - if (!string.IsNullOrEmpty(minCite) && int.TryParse(minCite, out var citeInt)) - { - MinCitations = citeInt; - } - + var minScore = Environment.GetEnvironmentVariable("DOC_MIN_QUALITY_SCORE").GetTrimmedValueOrEmpty(); if (!string.IsNullOrEmpty(minScore) && double.TryParse(minScore, out var scoreDouble)) { @@ -290,14 +276,14 @@ private static async Task ProcessCatalogueItems(DocumentCatalo // 保存原始内容，防止精炼失败时丢失 var originalContent = sr.ToString(); - if (string.IsNullOrEmpty(docs.Content) && count < 3) + if (string.IsNullOrEmpty(docs.Content) && count < 5) { count++; goto reset; } // 先进行基础质量验证，避免对质量过差的内容进行精炼 - var (isInitialValid, initialMessage, initialMetrics) = ValidateDocumentQuality(originalContent, catalog.Name); + var (isInitialValid, initialMessage, initialMetrics) = ValidateDocumentQuality(docs.Content, catalog.Name); if (!isInitialValid) { @@ -343,6 +329,13 @@ private static async Task ProcessCatalogueItems(DocumentCatalo - 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.Edit 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( @@ -531,4 +524,4 @@ public static void RepairMermaid(DocumentFileItem fileItem) Log.Error(ex, "修复mermaid语法失败"); } } -} \ No newline at end of file +} diff --git a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs index d648a687..dc4dea3a 100644 --- a/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs +++ b/src/KoalaWiki/KoalaWarehouse/GenerateThinkCatalogue/GenerateThinkCatalogueService.cs @@ -5,6 +5,7 @@ using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; using Newtonsoft.Json; +using JsonSerializer = System.Text.Json.JsonSerializer; namespace KoalaWiki.KoalaWarehouse.GenerateThinkCatalogue; @@ -144,7 +145,7 @@ Perfect. Analyze all code files thoroughly and generate the complete documentati var catalogueTool = new CatalogueFunction(); var analysisModel = KernelFactory.GetKernel(OpenAIOptions.Endpoint, - OpenAIOptions.ChatApiKey, path, OpenAIOptions.AnalysisModel, false, null, + OpenAIOptions.ChatApiKey, path, OpenAIOptions.AnalysisModel, true, null, builder => { builder.Plugins.AddFromObject(catalogueTool, "Catalogue"); }); var chat = analysisModel.Services.GetService(); @@ -173,16 +174,16 @@ Perfect. Analyze all code files thoroughly and generate the complete documentati { // 质量增强逻辑 if (!DocumentOptions.RefineAndEnhanceQuality || attemptNumber >= 4) // 前几次尝试才进行质量增强 - return ExtractAndParseJson(catalogueTool.Content, warehouse.Name, attemptNumber); + return ExtractAndParseJson(catalogueTool.Content); await RefineResponse(history, chat, settings, analysisModel, catalogueTool, attemptNumber); - - return ExtractAndParseJson(catalogueTool.Content, warehouse.Name, attemptNumber); + + return ExtractAndParseJson(catalogueTool.Content); } else { retry++; - if (retry > 3) + if (retry > 5) { throw new Exception("AI生成目录的时候重复多次响应空内容"); } @@ -198,15 +199,15 @@ private static async Task RefineResponse(ChatHistory history, IChatCompletionSer { // 根据尝试次数调整细化策略 var refinementPrompt = """ - Refine the stored documentation_structure JSON iteratively using tools only: - - Use Catalogue.Read to inspect the current JSON. - - Apply several Catalogue.Edit operations to: - • add Level 2/3 subsections for core components, features, data models, integrations - • normalize kebab-case titles and maintain 'getting-started' then 'deep-dive' ordering - • enrich each section's 'prompt' with actionable guidance (scope, code areas, outputs) - - Prefer localized edits; only use Catalogue.Write for a complete rewrite if necessary. - - Never print JSON in chat; use tools exclusively. - """; + Refine the stored documentation_structure JSON iteratively using tools only: + - Use Catalogue.Read to inspect the current JSON. + - Apply several Catalogue.Edit operations to: + • add Level 2/3 subsections for core components, features, data models, integrations + • normalize kebab-case titles and maintain 'getting-started' then 'deep-dive' ordering + • enrich each section's 'prompt' with actionable guidance (scope, code areas, outputs) + - Prefer localized edits; only use Catalogue.Write for a complete rewrite if necessary. + - Never print JSON in chat; use tools exclusively. + """; history.AddUserMessage(refinementPrompt); @@ -219,95 +220,13 @@ private static async Task RefineResponse(ChatHistory history, IChatCompletionSer } } - private static DocumentResultCatalogue? ExtractAndParseJson( - string responseText, string warehouseName, int attemptNumber) + private static DocumentResultCatalogue? ExtractAndParseJson(string responseText) { - var extractedJson = ExtractJsonWithMultipleStrategies(responseText, attemptNumber); - - if (string.IsNullOrWhiteSpace(extractedJson)) - { - Log.Logger.Warning("无法从响应中提取有效JSON内容，原始响应长度：{length}", responseText.Length); - return null; - } - - Log.Logger.Debug("提取的JSON内容长度：{length}，尝试次数：{attempt}", extractedJson.Length, attemptNumber + 1); + var extractedJson = JsonSerializer.Deserialize(responseText); - // 多种JSON解析策略 - return ParseJsonWithFallback(extractedJson, warehouseName, attemptNumber); + return extractedJson; } - private static string ExtractJsonWithMultipleStrategies(string responseText, int attemptNumber) - { - var strategies = new List> - { - // 策略1: documentation_structure 标签 - text => - { - var regex = new Regex(@"\s*(.*?)\s*", - RegexOptions.Singleline | RegexOptions.IgnoreCase); - var match = regex.Match(text); - return match.Success ? match.Groups[1].Value.Trim() : string.Empty; - }, - - // 策略2: ```json 代码块 - text => - { - var regex = new Regex(@"```json\s*(.*?)\s*```", - RegexOptions.Singleline | RegexOptions.IgnoreCase); - var match = regex.Match(text); - return match.Success ? match.Groups[1].Value.Trim() : string.Empty; - }, - - // 策略3: 简单的 ``` 代码块 - text => - { - var regex = new Regex(@"```\s*(.*?)\s*```", - RegexOptions.Singleline); - var match = regex.Match(text); - var content = match.Success ? match.Groups[1].Value.Trim() : string.Empty; - return content.StartsWith("{") && content.EndsWith("}") ? content : string.Empty; - }, - - // 策略4: 寻找最大的JSON对象 - text => - { - var regex = new Regex(@"\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}", - RegexOptions.Singleline); - var matches = regex.Matches(text); - return matches.Count > 0 - ? matches.Cast().OrderByDescending(m => m.Length).First().Value - : string.Empty; - }, - - // 策略5: 清理并返回原文本（如果看起来像JSON） - text => - { - var cleaned = text.Trim().TrimStart("json").Trim(); - return cleaned.StartsWith("{") && cleaned.EndsWith("}") ? cleaned : string.Empty; - } - }; - - // 根据尝试次数决定使用哪些策略 - var strategiesToUse = attemptNumber < 3 ? strategies.Take(3) : strategies; - - foreach (var strategy in strategiesToUse) - { - try - { - var result = strategy(responseText); - if (!string.IsNullOrWhiteSpace(result)) - { - return result; - } - } - catch (Exception ex) - { - Log.Logger.Debug("JSON提取策略失败：{error}", ex.Message); - } - } - - return string.Empty; - } private static DocumentResultCatalogue? ParseJsonWithFallback( string jsonContent, string warehouseName, int attemptNumber) diff --git a/src/KoalaWiki/MCP/MCPExtensions.cs b/src/KoalaWiki/MCP/MCPExtensions.cs index 061c611e..cfa92a56 100644 --- a/src/KoalaWiki/MCP/MCPExtensions.cs +++ b/src/KoalaWiki/MCP/MCPExtensions.cs @@ -95,7 +95,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) tools.Add(new Tool() { - Name = $"{mcpName}-" + nameof(FileFunction.ReadFileFromLineAsync), + Name = $"{mcpName}-" + nameof(FileTool.ReadFileFromLineAsync), Description = "Returns the file content from the specified starting line to the ending line (inclusive). If the total output length exceeds 10,000 characters, only the first 10,000 characters are returned, the content order is consistent with the original file, and the original line breaks are retained.", InputSchema = JsonSerializer.Deserialize( @@ -127,7 +127,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) tools.Add(new Tool() { - Name = $"{mcpName}-" + nameof(FileFunction.GetTree), + Name = $"{mcpName}-" + nameof(FileTool.GetTree), Description = "Returns the file tree of the repository, including directories and files.", InputSchema = JsonSerializer.Deserialize(""" { @@ -159,7 +159,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) var functionName = context.Params.Name; - if (functionName.Equals(mcpName + "-" + nameof(FileFunction.ReadFileFromLineAsync), + if (functionName.Equals(mcpName + "-" + nameof(FileTool.ReadFileFromLineAsync), StringComparison.CurrentCulture)) { var items = context.Params?.Arguments?["items"]; @@ -189,7 +189,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) .Where(x => x.WarehouseId == warehouse.Id) .FirstOrDefaultAsync(token); - var fileFunction = new FileFunction(document.GitPath, null); + var fileFunction = new FileTool(document.GitPath, null); var sw = Stopwatch.StartNew(); @@ -215,7 +215,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) }; } // 在这里需要根据不同方法名称调用不同实现 - if (functionName.Equals(mcpName + "-" + nameof(FileFunction.GetTree), + if (functionName.Equals(mcpName + "-" + nameof(FileTool.GetTree), StringComparison.CurrentCulture)) { var dbContext = context.Services!.GetService(); @@ -228,7 +228,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) .Where(x => x.WarehouseId == warehouse.Id) .FirstOrDefaultAsync(token); - var fileFunction = new FileFunction(document.GitPath, null); + var fileFunction = new FileTool(document.GitPath, null); var sw = Stopwatch.StartNew(); @@ -278,7 +278,7 @@ public static IServiceCollection AddKoalaMcp(this IServiceCollection service) var sw = Stopwatch.StartNew(); - var rag = new RagFunction(warehouse.Id); + var rag = new RagTool(warehouse.Id); var response = await rag.SearchAsync(question, limit, minRelevance); diff --git a/src/KoalaWiki/Prompts/PromptExtensions.cs b/src/KoalaWiki/Prompts/PromptExtensions.cs index bcdc99e8..e9b10cbf 100644 --- a/src/KoalaWiki/Prompts/PromptExtensions.cs +++ b/src/KoalaWiki/Prompts/PromptExtensions.cs @@ -38,7 +38,13 @@ public static void AddDocsGenerateSystemReminder(this ChatMessageContentItemColl 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 Google Diataxis standard + 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.Edit 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. + D. Final pass: Re‑read with Docs.Read and fix any remaining issues with additional Docs.Edit calls. Prefer several small, precise edits over one large overwrite. 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. @@ -110,4 +116,4 @@ public static ChatHistory AddSystemEnhance(this ChatHistory chatHistory) """); return chatHistory; } -} \ No newline at end of file +} diff --git a/src/KoalaWiki/Prompts/Warehouse/AnalyzeCatalogue.md b/src/KoalaWiki/Prompts/Warehouse/AnalyzeCatalogue.md index ed4a655c..ca29b048 100644 --- a/src/KoalaWiki/Prompts/Warehouse/AnalyzeCatalogue.md +++ b/src/KoalaWiki/Prompts/Warehouse/AnalyzeCatalogue.md @@ -66,18 +66,18 @@ Target Language: ## Content Generation Strategy ### Getting Started Guide Content: -- **Project Overview**: Core purpose, technology stack, target users, key benefits -- **Environment Setup**: Prerequisites, installation, configuration, verification steps -- **Core Concepts**: Essential terminology, architectural principles, key abstractions -- **Basic Usage**: First examples, common workflows, fundamental operations -- **Quick Reference**: Essential commands, configurations, troubleshooting guide +- Core purpose, technology stack, target users, key benefits +- Prerequisites, installation, configuration, verification steps +- Essential terminology, architectural principles, key abstractions +- First examples, common workflows, fundamental operations +- Essential commands, configurations, troubleshooting guide ### Deep Dive Analysis Content: -- **Architecture Analysis**: System design, component relationships, data flow patterns -- **Core Components**: Detailed analysis of system modules, services, and data layers -- **Feature Implementation**: In-depth examination of key features and business logic -- **Technical Details**: Algorithms, design patterns, performance optimization -- **Integration & APIs**: External interfaces, plugin systems, extension mechanisms +- System design, component relationships, data flow patterns +- Detailed analysis of system modules, services, and data layers +- In-depth examination of key features and business logic +- Algorithms, design patterns, performance optimization +- External interfaces, plugin systems, extension mechanisms ## Output Format @@ -125,9 +125,9 @@ Generate a hierarchical JSON structure organized into two main modules based on - `children`: Optional array for complex topics requiring detailed breakdown **Nesting Levels (examples):** -- **Level 1**: Main sections (overview, setup, analysis, etc.) -- **Level 2**: Sub-topics within main sections (components, features, etc.) -- **Level 3**: Detailed aspects for complex features (algorithms, patterns, etc.) +- Main sections (overview, setup, analysis, etc.) +- Sub-topics within main sections (components, features, etc.) +- Detailed aspects for complex features (algorithms, patterns, etc.) **Sub-section Creation Rules:** - System modules with multiple responsibilities @@ -146,29 +146,17 @@ Generate a hierarchical JSON structure organized into two main modules based on ## Content Depth Requirements ### Getting Started Guide Requirements: -- **Project Overview**: Technology stack analysis, architectural overview, core value analysis -- **Environment Setup**: Step-by-step installation, dependency management, configuration validation -- **Core Concepts**: Technical terminology, system abstractions, component relationships -- **Basic Usage**: Practical examples, workflow demonstrations, operational procedures +- Technology stack analysis, architectural overview, core value analysis +- Step-by-step installation, dependency management, configuration validation +- Technical terminology, system abstractions, component relationships +- Practical examples, workflow demonstrations, operational procedures ### Deep Dive Analysis Requirements: -- **Architecture Analysis**: Design pattern identification, component interaction mapping, scalability analysis -- **Core Components**: - - System module responsibilities and interfaces - - Service layer architecture and dependencies - - Data model relationships and schemas - - API design patterns and endpoints -- **Feature Implementation**: - - Core functionality breakdown with feature decomposition into sub-components - - Business logic and workflow analysis with step-by-step process mapping - - Feature architecture patterns and structural organization - - Use case implementation analysis and user scenario handling - - Feature interaction matrix and dependency mapping - - Performance characteristics and scalability analysis per feature - - Error handling mechanisms and edge case management - - Testing strategies and validation approaches for each functional module -- **Technical Implementation**: Algorithm complexity, design pattern usage, security implementations -- **Integration & APIs**: External system interfaces, plugin architectures, extension mechanisms +- Design pattern identification, component interaction mapping, scalability analysis +- System module responsibilities and interfaces, service layer architecture and dependencies, data model relationships and schemas, API design patterns and endpoints +- Core functionality breakdown with feature decomposition into sub-components, business logic and workflow analysis with step-by-step process mapping, feature architecture patterns and structural organization, use case implementation analysis and user scenario handling, feature interaction matrix and dependency mapping, performance characteristics and scalability analysis per feature, error handling mechanisms and edge case management, testing strategies and validation approaches for each functional module +- Algorithm complexity, design pattern usage, security implementations +- External system interfaces, plugin architectures, extension mechanisms ## Execution Instructions diff --git a/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md b/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md index 2caf627a..a07b5dee 100644 --- a/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md +++ b/src/KoalaWiki/Prompts/Warehouse/GenerateDocs.md @@ -1,6 +1,5 @@ -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 write engaging, blog-style technical content that explains project components as if you're sharing insights with fellow developers - combining rigorous technical analysis with accessible explanations that reveal the "why" behind the code. +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. - {{$prompt}} @@ -20,154 +19,95 @@ You are a senior software engineer with deep expertise in code analysis and tech {{$code_files}} - {{$projectType}} -# DIÁTAXIS-GUIDED EXECUTION SUMMARY -**CRITICAL WORKFLOW REQUIREMENTS:** -1. **ANALYZE**: Identify documentation type from objective (Tutorial/How-to/Reference/Explanation) -2. **CONTEXTUALIZE**: Apply appropriate Diátaxis principles for user context -3. **GENERATE**: Create content following Diátaxis-specific templates and guidelines -4. **OUTPUT**: Wrap final content in `` tags with {{$language}} documentation +# DIÁTAXIS-GUIDED EXECUTION WORKFLOW ---- +## CRITICAL WORKFLOW REQUIREMENTS -# DIÁTAXIS-BASED EXECUTION WORKFLOW +- 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 -## MANDATORY EXECUTION SEQUENCE - FOLLOW EXACTLY +## MANDATORY EXECUTION SEQUENCE ### STEP 1: DOCUMENTATION TYPE IDENTIFICATION & REPOSITORY ANALYSIS - -You MUST begin by identifying the documentation type from the objective and conducting Diátaxis-aware analysis: - -1. **Diátaxis Type Classification**: Determine if this is Tutorial, How-to, Reference, or Explanation documentation -2. **User Context Analysis**: Understand the target user's situation and needs for this documentation type -3. **Repository Deep Dive**: Analyze code files with Diátaxis type-specific focus -4. **Content Strategy Planning**: Plan documentation approach using appropriate Diátaxis principles -5. **Template Selection**: Choose the correct Diátaxis template for content generation - -This analysis is MANDATORY and determines the entire documentation approach. - - -**DIÁTAXIS-CRITICAL PREREQUISITE:** Before documentation generation, identify Diátaxis type and conduct targeted analysis: -1. **Documentation Type Identification**: Classify as Tutorial, How-to, Reference, or Explanation -2. **User Context Assessment**: Understand user's current state and goals for this type -3. **Diátaxis-Focused Code Analysis**: Analyze code files through the lens of the identified type -4. **Template Application Planning**: Plan content using appropriate Diátaxis template requirements +- 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 ### STEP 2: DIÁTAXIS-GUIDED CONTENT GENERATION + Generate content following identified Diátaxis type requirements: + - 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 -- Ensure content meets minimum length requirements (1000+ characters) with substantial analysis - -### STEP 3: DOCUMENT GENERATION TOOL CONTENT CREATION (MANDATORY) -**CRITICAL REQUIREMENT**: ALL content generation MUST use the provided document generation tools exclusively. NEVER output content directly. - -**MANDATORY TOOL-BASED WORKFLOW:** -1. **Initialize with Write Tool**: Use the Write() function to create the initial document structure -2. **Iterative Content Building**: Use the Edit() function to progressively build complete sections -3. **Content Verification**: Use the Read() function to verify content before proceeding -4. **Final Assembly**: Ensure all content is created through tool calls only - -**CONTENT CREATION PROTOCOL:** -- Start with Write() containing document outline and first section -- Use multiple Edit() calls to add each major section systematically -- Each Edit() call should add substantial content (500-1000 words minimum) -- Include all Mermaid diagrams within tool operations -- Add all citation references through Edit() operations -- NEVER output final content directly - all content must exist within the document generation system - -**FINAL TOOL-BASED CONTENT REQUIREMENTS:** -- Complete, detailed documentation content created through Write() and Edit() operations -- Comprehensive technical analysis added via tool operations -- All required Mermaid diagrams included through Edit() operations -- Proper citation references added via tool operations -- Professional formatting in {{$language}} maintained through document generation tools + +### 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 + +### 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:** -1. **DOCUMENT GENERATION TOOL USAGE**: Exclusively use available document generation tools for ALL content creation - NEVER output content directly -2. **TYPE IDENTIFICATION**: Correctly identify and apply appropriate Diátaxis documentation type -3. **USER-CENTERED ANALYSIS**: Use `` tags for Diátaxis-guided repository analysis -4. **SYSTEMATIC CITATIONS**: Include [^n] citations for all technical claims and references via Edit() operations -5. **CONTEXTUAL DIAGRAMS**: Minimum 3 Mermaid diagrams supporting the specific documentation type (ideally 6-8) added through Edit() operations -6. **PROFESSIONAL STANDARDS**: Achieve quality comparable to industry-leading documentation through tool operations -7. **TOOL-BASED CONTENT CREATION**: Final content must exist entirely within the document generation system - no direct output allowed -8. **TYPE CONSISTENCY**: Maintain consistency with chosen Diátaxis type throughout tool-based content creation - -# CORE DIRECTIVES +- 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 -Write compelling technical blog content that reads like a seasoned developer's deep-dive analysis of a project. Your writing should feel like sitting down with a senior engineer who has thoroughly explored the codebase and can explain not just what the code does, but why it was designed that way, what problems it solves, and what makes it interesting from an engineering perspective. Focus on storytelling through code - revealing the thought processes, architectural decisions, and clever solutions that make this project worth understanding. - -## Essential Requirements for Engineering Blog Content -- **Deep Code Investigation**: Like any thorough code review, you must analyze ALL provided code files completely - understanding the implementation details, patterns, and architectural decisions before writing -- **Balanced Technical Storytelling**: Write primarily in prose (70-80%) with strategic code examples (20-30%) that illustrate key points and engineering decisions -- **Evidence-Based Engineering Insights**: Every technical claim must be backed by actual code evidence - cite specific files and implementations that support your analysis[^n] -- **Architectural Detective Work**: Focus on revealing the "why" behind design decisions by analyzing code organization, patterns, and implementation choices -- **Real Implementation Focus**: Only discuss functionality that actually exists in the provided code - no speculation or assumptions about features not implemented -- **Engineering Problem-Solution Narrative**: Frame technical discussions around the engineering challenges being solved and how the implementation addresses them -- **Developer-to-Developer Communication**: Write as if explaining interesting technical discoveries to fellow engineers - engaging, insightful, and practical -- **Industry-Quality Analysis**: Achieve the depth and quality of technical blog posts from companies like Netflix, Spotify, or major open-source projects -- **Practical Engineering Insights**: Highlight patterns, optimizations, and architectural decisions that other developers can learn from and apply - -## Engineering Blog Quality Standards -- **Senior Developer Perspective**: Write with the authority and insight of an experienced engineer who has thoroughly explored the codebase -- **Compelling Technical Narrative**: Create engaging content that makes complex technical concepts accessible and interesting -- **Implementation-Grounded Analysis**: Every architectural insight and technical claim must be supported by evidence from the actual code[^n] -- **Industry-Leading Quality**: Match the standards of top-tier engineering blogs from major tech companies and successful open-source projects -- **Comprehensive Engineering Coverage**: Address the key technical components, interesting patterns, and notable architectural decisions that make this project worth studying -- **Technical Accuracy and Honesty**: Maintain rigorous accuracy while acknowledging limitations and trade-offs in the implementation +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 -**DOCUMENTATION TYPE CLASSIFICATION & ANALYSIS:** - -### Diátaxis Type Identification -Before code analysis, classify documentation type and apply appropriate lens: - -#### Tutorial Documentation (Learning-Oriented) -**User Context**: Beginners learning through guided practice -**Analysis Focus**: -- **Success Path Mapping**: Identify step-by-step learning progression that guarantees success -- **Prerequisite Identification**: Find minimal setup and knowledge requirements -- **Checkpoint Discovery**: Locate validation points and progress indicators -- **Learning Obstacles**: Identify potential confusion points and provide clear guidance - -#### How-to Guide Documentation (Problem-Oriented) -**User Context**: Competent users solving specific problems -**Analysis Focus**: -- **Goal-Solution Mapping**: Identify specific problems and their solution paths -- **Context Variations**: Understand different scenarios where solutions apply -- **Practical Implementation**: Focus on actionable steps and real-world usage -- **Edge Cases**: Identify common complications and resolution strategies - -#### Reference Documentation (Information-Oriented) -**User Context**: Users looking up specific information -**Analysis Focus**: -- **Authoritative Specifications**: Catalog complete, accurate system behaviors -- **Systematic Organization**: Structure information for quick lookup and navigation -- **Comprehensive Coverage**: Ensure all parameters, options, and behaviors are documented -- **Factual Accuracy**: Focus on what the system does, not how to use it - -#### Explanation Documentation (Understanding-Oriented) -**User Context**: Users seeking conceptual understanding -**Analysis Focus**: -- **Design Rationale**: Extract reasoning behind architectural decisions -- **Conceptual Connections**: Understand how components relate to broader concepts -- **Context and Background**: Provide historical and comparative perspective -- **Mental Model Building**: Help users understand the why behind the system +**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 @@ -193,185 +133,82 @@ You MUST read and analyze EVERY SINGLE file provided in the `` param **Step 2: Technical Architecture Cataloging** After reading all files, you must: -1. **Component Inventory**: Create mental inventory of all technical components, classes, modules, and services -2. **Technology Stack Verification**: Confirm actual technologies, frameworks, libraries, and tools used -3. **Architecture Pattern Mapping**: Understand the real architectural patterns and design principles implemented -4. **Technical Entry Points**: Locate main application entry points, initialization sequences, and core technical workflows -5. **Dependency Analysis**: Map all technical dependencies, integrations, and external system connections +- 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: -1. **Reference Point Establishment**: Identify specific file locations, line numbers, and code sections for citation -2. **Technical Evidence Base**: Ensure all subsequent technical claims can be traced back to specific code locations -3. **Citation Framework Preparation**: Build systematic approach for referencing technical implementations +- 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:** -- **Zero Assumptions**: Do not make any assumptions about technical functionality not explicitly present in the provided code files -- **Complete Technical Coverage**: Every major technical component mentioned in documentation must exist in the provided code files -- **Accurate Technical Attribution**: Every technical claim must be traceable to specific file locations with proper [^n] citation markers -- **Implementation Fidelity**: Technical descriptions must accurately reflect actual implementation, not intended or theoretical functionality -- **Citation Traceability**: All [^n] references must point to verifiable technical implementations in the provided files +- 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 -## Phase 1: User-Centric Technical Architecture Discovery +## Comprehensive Technical Analysis Framework -Based on the comprehensive repository analysis completed in STEP 1, I must now conduct user-centric technical architecture discovery 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 (developers, architects, operators, end-users). +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 stage aims to generate detailed and comprehensive document content. Through appropriate Dialectasis content types and using the toolset provided by Docs, the documents will be created to meet the needs of different users. +This analysis will inform the COMPLETE content generation created via Docs tools with comprehensive technical documentation. **USER PERSONA ANALYSIS REQUIREMENTS:** - -### Developer-Focused Analysis -- **Tutorial Needs**: What step-by-step learning paths do developers need?[^n] -- **Task-Oriented Requirements**: What specific problems are developers trying to solve?[^n] -- **Reference Needs**: What quick-lookup information do developers require?[^n] -- **Conceptual Understanding**: What architectural principles must developers understand?[^n] - -### Architect-Focused Analysis -- **System Design Context**: How does this fit into larger system architectures?[^n] -- **Trade-off Analysis**: What design decisions were made and why?[^n] -- **Scalability Patterns**: How does the architecture support growth?[^n] -- **Integration Considerations**: How does this connect with other systems?[^n] - -### Operator-Focused Analysis -- **Deployment Guidance**: What are the operational requirements?[^n] -- **Monitoring Needs**: What observability is built in?[^n] -- **Troubleshooting Support**: How are issues diagnosed and resolved?[^n] -- **Maintenance Procedures**: What ongoing care is required?[^n] - -**ESSENTIAL TECHNICAL DISCOVERY REQUIREMENTS:** -1. **System Architecture Analysis**: Conduct comprehensive analysis of the overall system architecture, identifying layers, components, and technical organization patterns based on actual file structure, dependency graphs, and module organization[^n] - -2. **Design Pattern Investigation**: Systematically identify and analyze design patterns, architectural patterns, and technical approaches actually used throughout the system, with detailed examination of implementation variations and adaptations[^n] - -3. **Technology Stack Analysis**: Exhaustive analysis of technology choices, frameworks, libraries, and their technical implications, including version analysis, compatibility considerations, and integration strategies[^n] - -4. **Component Architecture Evaluation**: Detailed examination of how technical components are organized, interact, and collaborate to deliver system functionality, including lifecycle management and dependency injection patterns[^n] - -5. **Integration Architecture Analysis**: Comprehensive examination of how the system integrates with external systems and services, including API design, communication protocols, and data transformation patterns[^n] - -6. **Configuration and Environment Management**: Analysis of configuration management strategies, environment handling, and actual configuration files[^n] - -## Phase 2: Core Technical Implementation Analysis - -Using the comprehensive repository analysis from STEP 1, I need to conduct deep technical analysis of the core implementation patterns, algorithms, data structures, and technical decision-making that drives the system. This analysis must reveal the technical sophistication and engineering excellence behind the implementation and directly support the documentation_objective. - -This analysis will inform the COMPLETE content generation that must be wrapped in tags with comprehensive technical documentation. - - -**MANDATORY TECHNICAL IMPLEMENTATION ANALYSIS:** - -### Core Technical Architecture Investigation -- **Primary Technical Workflows**: Comprehensive analysis of the main technical processes and workflows, understanding the technical implementation patterns, execution paths, and decision trees[^n] -- **Algorithm and Data Structure Analysis**: Detailed examination of core algorithms, data structures, and technical processing logic, including complexity analysis and optimization strategies[^n] -- **Technical Pattern Implementation**: In-depth analysis of how technical patterns and architectural principles are implemented, including variations and customizations specific to the project[^n] -- **System Behavior Analysis**: Extensive understanding of how the system behaves under different technical conditions and scenarios, including edge cases and error conditions[^n] -- **Data Flow and Transformation Analysis**: Detailed mapping of data flow through the system, transformation logic, and data integrity mechanisms[^n] -- **Concurrency and Parallelism Analysis**: Examination of concurrent processing patterns, thread management, and synchronization mechanisms actually implemented[^n] -- **Resource Management Analysis**: Analysis of memory management, connection pooling, and resource lifecycle management strategies[^n] - -### Technical Implementation Deep Dive -- **Core Technical Logic**: Comprehensive analysis of the fundamental technical logic and processing mechanisms, including business rule implementation and validation strategies[^n] -- **Data Flow Technical Architecture**: Detailed examination of how data flows through the system from a technical architecture perspective, including transformation pipelines and data validation[^n] -- **Error Handling Technical Patterns**: In-depth understanding of technical error handling, resilience patterns, failure management, and recovery mechanisms[^n] -- **Performance Technical Implementation**: Extensive analysis of technical performance optimizations and their implementation strategies, including benchmarking approaches and bottleneck identification[^n] -- **State Management Technical Patterns**: Analysis of state management strategies, persistence mechanisms, and consistency guarantees[^n] -- **API Design and Interface Architecture**: Examination of API design patterns, interface contracts, and integration capabilities[^n] -- **Testing and Quality Assurance Architecture**: Analysis of testing strategies, quality gates, and validation mechanisms built into the implementation[^n] -- **Documentation and Developer Experience**: Assessment of code documentation, API documentation, and developer tooling based on actual implementation[^n] - -### Technical Design Decision Analysis -- **Architecture Technical Rationale**: Comprehensive understanding of the technical reasoning behind architectural decisions, including trade-off analysis and alternative considerations[^n] -- **Technology Choice Technical Analysis**: Detailed analysis of technical stack decisions and their implications for system performance, maintainability, and long-term evolution[^n] -- **Scalability Technical Design**: Extensive examination of how technical architecture supports system scalability, performance, and capacity planning[^n] -- **Security Technical Implementation**: In-depth analysis of technical security measures, their implementation patterns, and security architecture principles[^n] -- **Maintainability and Evolution Strategy**: Analysis of how the technical design supports long-term maintainability, refactoring, and system evolution[^n] -- **Deployment and Operations Architecture**: Examination of deployment strategies, operational requirements, and infrastructure considerations[^n] -- **Integration and Interoperability Design**: Analysis of how the system is designed for integration with external systems and ecosystem compatibility[^n] -- **Cost and Resource Optimization**: Assessment of resource utilization optimization and cost-effective design decisions evident in the implementation[^n] - -**TECHNICAL ANALYSIS FRAMEWORKS:** - -### For Application Projects -- **Application Architecture Analysis**: Systematically analyze application structure, technical layers, and component organization[^n] -- **Technical User Flow Analysis**: Trace technical implementation of user interactions and system responses[^n] -- **Data Management Technical Patterns**: Examine technical data management, storage, and processing patterns[^n] -- **Technical Integration Analysis**: Analyze how the application integrates with external systems and services[^n] -- **Performance Technical Architecture**: Evaluate technical performance characteristics and optimization strategies[^n] - -### For Library/Framework Projects -- **API Design Technical Analysis**: Comprehensive analysis of public interfaces, design patterns, and technical usability[^n] -- **Technical Integration Patterns**: Evaluate technical compatibility and integration approaches with external systems[^n] -- **Extensibility Technical Architecture**: Analyze technical extension mechanisms and customization capabilities[^n] -- **Performance Technical Characteristics**: Understand technical performance implications and optimization strategies[^n] - -### For Infrastructure/DevOps Projects -- **Infrastructure Technical Architecture**: Evaluate technical infrastructure design patterns and system reliability[^n] -- **Configuration Technical Management**: Analyze technical configuration management, environment handling, and deployment patterns[^n] -- **Monitoring Technical Implementation**: Document technical monitoring, logging, and observability implementations[^n] -- **Security Technical Architecture**: Assess technical security implementations and protection mechanisms[^n] - -## Phase 3: Advanced Technical Architecture Analysis - -Conduct comprehensive technical analysis of advanced architectural patterns, system design principles, and technical excellence demonstrated in the implementation. This phase focuses on the sophisticated technical aspects that make the system robust, scalable, and maintainable, directly supporting the documentation_objective requirements. - -This advanced analysis will contribute to the COMPLETE, COMPREHENSIVE documentation that must be generated and wrapped in tags. - - -**ADVANCED TECHNICAL ANALYSIS REQUIREMENTS:** -- **Technical Interface Architecture**: Complete analysis of all technical interfaces, contracts, and interaction patterns[^n] -- **Technical Error Handling Patterns**: Document sophisticated error handling, recovery strategies, and resilience patterns[^n] -- **Concurrency Technical Models**: Analyze advanced concurrency patterns, threading approaches, and parallel processing implementations[^n] -- **Technical Data Flow Architecture**: Map sophisticated data transformation pipelines, processing patterns, and optimization strategies[^n] -- **Security Technical Architecture**: Document advanced security implementations, authentication flows, and protection mechanisms[^n] - -### Advanced Technical Implementation Analysis -- **Technical Performance Optimization**: Deep analysis of performance optimization techniques and their technical implementation[^n] -- **Technical Scalability Architecture**: Examine advanced scalability patterns and their technical implementation strategies[^n] -- **Technical Reliability Patterns**: Analyze reliability, fault tolerance, and system resilience technical implementations[^n] -- **Technical Integration Excellence**: Understand sophisticated integration patterns and technical interoperability solutions[^n] - -### Technical Innovation Analysis -- **Technical Design Innovation**: Identify innovative technical approaches and their implementation advantages[^n] -- **Technical Efficiency Optimization**: Analyze technical efficiency improvements and optimization strategies[^n] -- **Technical Maintainability Patterns**: Examine technical patterns that enhance code maintainability and system evolution[^n] -- **Technical Excellence Demonstration**: Understand how the implementation demonstrates technical excellence and engineering best practices[^n] - -## Phase 4: Technical Ecosystem Integration Assessment - -Evaluate how the technical implementation positions itself within broader technology ecosystems, analyzing technical integrations, dependencies, and ecosystem connections based on actual implementations found in the code files. This assessment must align with the documentation_objective and support comprehensive documentation generation. - -This ecosystem analysis will be integrated into the COMPLETE documentation content that must be wrapped in tags. - - -**TECHNICAL ECOSYSTEM INTEGRATION ANALYSIS:** -- **Technical Platform Integration**: Comprehensive assessment of how the system technically integrates with major platforms and ecosystems, including cloud services, container orchestration, and platform-specific optimizations[^n] -- **Technical Workflow Integration**: Detailed analysis of how the system fits into technical development and operational workflows, including CI/CD integration, testing automation, and deployment pipelines[^n] -- **Technical Deployment Architecture**: Extensive examination of technical deployment strategies, infrastructure requirements, containerization approaches, and environment management[^n] -- **Technical Community Integration**: In-depth assessment of technical ecosystem positioning, community integration approaches, plugin systems, and extensibility mechanisms[^n] -- **Technical Evolution Strategy**: Comprehensive analysis of technical upgrade strategies, version management, backward compatibility, and evolution planning[^n] -- **Dependency Management Excellence**: Analysis of dependency selection criteria, version management strategies, and security considerations in third-party integrations[^n] -- **Cross-Platform Compatibility**: Examination of multi-platform support, portability considerations, and platform-specific adaptations[^n] -- **API Ecosystem Integration**: Assessment of API design for ecosystem integration, standards compliance, and interoperability patterns[^n] - -## Phase 5: Advanced Technical Excellence Analysis - -Conduct deep analysis of advanced technical aspects that demonstrate engineering excellence, innovation, and sophisticated problem-solving approaches evident in the actual implementation. This analysis must directly support the documentation_objective and contribute to generating COMPLETE, COMPREHENSIVE documentation. - -This excellence analysis will be incorporated into the final wrapped documentation content. - - -**ADVANCED TECHNICAL EXCELLENCE REQUIREMENTS:** -- **Algorithmic Sophistication Analysis**: Detailed examination of complex algorithms, data structures, and computational efficiency optimizations actually implemented[^n] -- **Architectural Innovation Assessment**: Analysis of novel architectural patterns, design innovations, and creative technical solutions evident in the codebase[^n] -- **Performance Engineering Excellence**: Comprehensive evaluation of performance optimization techniques, profiling integration, and efficiency engineering practices[^n] -- **Security Engineering Depth**: In-depth analysis of security architecture, threat modeling, and defensive programming practices implemented[^n] -- **Reliability Engineering Patterns**: Examination of fault tolerance, disaster recovery, and system resilience mechanisms built into the implementation[^n] -- **Observability and Monitoring Excellence**: Assessment of comprehensive monitoring, logging, tracing, and debugging capabilities integrated into the system[^n] -- **Testing and Quality Engineering**: Analysis of testing strategies, quality gates, automated validation, and quality assurance engineering[^n] -- **Documentation Engineering**: Evaluation of code documentation, API documentation, and knowledge management approaches[^n] +- 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 @@ -386,39 +223,39 @@ For explanations: diagrams reveal conceptual relationships **DIÁTAXIS DIAGRAM SELECTION PRINCIPLES:** -- **Type-Appropriate Visualization**: Choose diagrams that serve the specific Diátaxis type's user context -- **User-Centered Design**: Focus on what users need to see for their specific goals -- **Context-Relevant Detail**: Include detail levels appropriate for the documentation type -- **Supporting Evidence**: All diagrams must be based on actual repository analysis +- 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 -- **Progress Flow Diagrams**: Sequential steps with validation points -- **Setup Verification Diagrams**: Environment and prerequisite checks -- **Success Checkpoint Maps**: Progress indicators and completion validation +- 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 -- **Problem-Solution Flowcharts**: Decision trees for different scenarios -- **Implementation Sequence Diagrams**: Step-by-step solution processes -- **Context-Aware Architecture**: System views relevant to the specific problem -- **Troubleshooting Flowcharts**: Error handling and recovery paths +- 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 -- **Complete System Architecture**: Authoritative system overview -- **API Reference Diagrams**: Comprehensive interface specifications -- **Database Schema Diagrams**: Complete data model representations -- **Component Relationship Maps**: Detailed system interconnections +- Authoritative system overview +- Comprehensive interface specifications +- Complete data model representations +- Detailed system interconnections ### Explanation Diagrams (Understanding-Oriented) **Purpose**: Reveal conceptual relationships and design rationale -- **Conceptual Architecture**: High-level design principles -- **Design Decision Trees**: Rationale behind architectural choices -- **Comparison Diagrams**: Alternative approaches and trade-offs -- **Evolution Timeline**: Historical development and future direction +- 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):** @@ -689,13 +526,13 @@ Based on actual project analysis, select appropriate diagrams: - architecture-beta, sequenceDiagram, flowchart, erDiagram **For API/Microservices**: -- classDiagram, sequenceDiagram, architecture-beta, requirementDiagram, sankey-beta +- classDiagram, sequenceDiagram, architecture-beta, sankey-beta **For Development/DevOps Tools**: - gitGraph, timeline, kanban, gantt, quadrantChart **for Enterprise Applications**: -- quadrantChart, gantt, requirementDiagram +- quadrantChart, gantt **For System Architecture Documentation**: - architecture-beta, classDiagram, stateDiagram-v2 @@ -706,29 +543,26 @@ Based on actual project analysis, select appropriate diagrams: **For Analytics/Monitoring Systems**: - xychart-beta, sankey-beta, quadrantChart -**For User Experience Analysis**: -- quadrantChart, timeline - **For Requirements Engineering**: - requirementDiagram, mindmap, flowchart, quadrantChart **TECHNICAL DIAGRAM GENERATION REQUIREMENTS:** -- **Minimum 6-8 Technical Diagrams**: Every documentation must include at least 6-8 comprehensive Mermaid diagrams showcasing technical excellence -- **Code-Based Technical Evidence**: Every diagram element must correspond to actual technical components found in the provided files -- **Progressive Technical Detail**: Start with high-level technical architecture, then drill down to specific technical component interactions -- **Technical Sophistication Focus**: Pay special attention to advanced technical patterns, algorithms, and architectural excellence -- **Technical Integration Mapping**: Show how different technical modules, services, and external systems integrate +- 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:** -- **Comprehensive Technical Context**: Each diagram must be accompanied by extensive explanation of the technical architecture/process with deep analytical insight (aim for maximum detail and understanding) -- **Technical Code References**: Reference specific files and line numbers that implement the diagrammed technical components with proper [^n] citation markers -- **Technical Design Rationale**: Explain why this particular technical structure or flow was chosen with supporting technical evidence and alternative consideration analysis -- **Technical Excellence Analysis**: Describe how this technical architecture demonstrates engineering excellence, best practices, and innovative approaches -- **Performance and Scalability Context**: Analyze how the diagrammed architecture supports performance requirements and scalability needs -- **Security and Reliability Considerations**: Discuss security implications and reliability aspects of the architectural patterns shown -- **Integration and Ecosystem Context**: Explain how the diagrammed components integrate with external systems and broader ecosystem -- **Evolution and Maintainability Analysis**: Assess how the architecture supports future evolution and long-term maintainability -- **Citation Integration**: All technical claims in diagram explanations must include appropriate footnote references with comprehensive verification +- 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 @@ -736,19 +570,16 @@ Based on actual project analysis, select appropriate diagrams: 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 a COMPLETE documentation wrapped in tags, based on thorough repository analysis and aligned with the documentation_objective. +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:** -- **MANDATORY Blog Wrapper**: ALL FINAL CONTENT MUST be contained within `` tags - this is NON-NEGOTIABLE for proper structure and organization -- **COMPLETE Content Requirement**: The `` tags must contain COMPLETE, COMPREHENSIVE, DETAILED documentation content - no partial or incomplete content allowed -- **Professional Technical Standards**: Achieve documentation quality comparable to industry-leading projects such as React, Vue, and TypeScript -- **Comprehensive Citation Integration**: Support EVERY technical claim with footnote references [^n] providing verifiable evidence and code references -- **Technical Architecture Priority**: Focus on explaining technical architecture, design patterns, and implementation excellence -- **Comprehensive Technical Analysis**: Provide thorough explanations for all technical elements, emphasizing technical sophistication and engineering excellence -- **Technical Excellence Development**: Guide readers to understand advanced technical concepts and implementation strategies -- **Section Technical Depth**: Ensure each major section contains substantial technical content (1000-1500 words minimum) with comprehensive technical analysis -- **Repository Analysis Integration**: ALL content must be based on thorough repository analysis aligned with documentation_objective +- 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 @@ -756,30 +587,23 @@ The final output must be a COMPLETE documentation wrapped in tags, 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:** -- **Technical Learning Progression**: Structure content to match developer technical learning patterns and advancement -- **Technical Problem-Solution Integration**: Begin with technical challenges and context before presenting technical solutions -- **Progressive Technical Understanding**: Build technical knowledge systematically, with each section building upon technical concepts -- **Technical Implementation Integration**: Provide examples that reflect sophisticated technical implementation scenarios -- **Comprehensive Technical Decision Guidance**: Explain technical approaches, implementation contexts, and technical consequences -- **Technical Challenge Identification**: Anticipate advanced technical challenges and provide guidance for technical problem-solving - -**ENGINEERING BLOG CONTENT METHODOLOGY:** -- **Developer Storytelling Approach**: 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 -- **"Show, Don't Just Tell" Philosophy**: Use concrete examples, real scenarios, and practical implications to illustrate technical concepts rather than abstract descriptions -- **Architectural Detective Work**: Reveal the reasoning behind design decisions by analyzing code patterns, file organization, and implementation choices - like reverse-engineering the developer's thought process -- **Problem-Solution Narrative**: Frame technical discussions around the problems being solved, making the engineering decisions feel natural and well-motivated -- **Engineering Insight Focus**: Highlight clever solutions, interesting patterns, performance considerations, and architectural trade-offs that other developers would find valuable -- **Conversational Technical Depth**: Maintain technical rigor while writing in an engaging, accessible style that feels like a senior developer sharing insights -- **Code as Evidence**: Use strategic code examples to support your analysis and explanations, showing the actual implementation that backs up your technical insights +- 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:** -- **MANDATORY TOOL USAGE**: ALL content creation must use document generation tools exclusively -- **NO DIRECT OUTPUT ALLOWED**: Never output documentation content directly in response -- **TOOL-BASED CONTENT STRUCTURE**: Create content through Write() and Edit() operations -- **TOOL-BASED MERMAID INTEGRATION**: Include minimum 6-8 comprehensive Mermaid diagrams through Edit() operations -- **TOOL-BASED TECHNICAL VISUALIZATION**: Every significant technical process must be visualized through tool operations -- **TOOL-BASED CODE REFERENCES**: Ensure every diagram element represents actual implementations through tool operations -- **TOOL-BASED CITATION SYSTEM**: Integrate footnote citations [^n] with proper file references through Edit() operations ## Technical Citation Implementation Guidelines @@ -798,30 +622,23 @@ Generate documentation that demonstrates technical excellence through systematic **TECHNICAL CITATION PLACEMENT:** - Add `[^n]` immediately after the technical content, before punctuation -- Include all citations as footnotes at the end of the document within `` tags +- 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:** -- **Technical Authority**: Write as a technical expert who understands advanced engineering concepts and implementation excellence -- **Technical Assumption Transparency**: Explicitly state technical assumptions and provide pathways for advanced technical understanding -- **Technical Wisdom Integration**: Share not just technical facts, but technical insights and engineering wisdom -- **Technical Challenge Empathy**: Acknowledge advanced technical challenges and provide expert technical guidance -- **Progressive Technical Disclosure**: Present technical information in layers, allowing readers to advance their technical understanding -- **Evidence-Based Technical Narrative**: Support all technical claims with actual code references while weaving them into compelling technical explanations +- 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. - -This cognitive process must follow the mandatory execution sequence: -1. STEP 1: Repository analysis with tags -2. STEP 2: Complete content generation -3. STEP 3: Blog format output with tags - -All analysis must be based on documentation_objective and result in COMPLETE documentation content. **CRITICAL TECHNICAL SUCCESS FACTORS:** @@ -838,66 +655,65 @@ Multi-layered technical validation ensures COMPLETE documentation meets enterpri The validation must ensure: 1. Repository analysis was comprehensive and based on documentation_objective -2. ALL content is complete and wrapped in tags +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:** -- Technical Code Fidelity Verification**: Confirm that ALL technical claims, architectural descriptions, and implementation details are directly traceable to specific content in the provided code files -- Technical Mermaid Diagram Completeness**: Verify that minimum 6-8 comprehensive Mermaid diagrams are included, covering technical architecture, component relationships, data flows, and technical processes -- ️ Technical Diagram-Code Alignment**: Ensure every diagram element corresponds to actual technical components, classes, functions, or processes found in the analyzed files -- Technical Visual Representation Coverage**: Confirm that all major technical patterns, technical logic flows, and component interactions are properly visualized -- Technical Source Attribution Validation**: 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 -- ️ Technical Implementation Accuracy Check**: Ensure all described technical functionality actually exists in the provided code files and is described accurately without speculation -- Technical Complete Coverage Assessment**: Verify that all major technical components, classes, functions, and configurations present in the code files are appropriately covered -- Technical Professional Standards Validation**: Ensure documentation addresses advanced technical needs effectively and provides clear, actionable technical guidance -- Technical Learning Path Assessment**: Verify that technical information progression facilitates efficient technical knowledge acquisition and advanced implementation -- Technical Accuracy Verification**: Confirm all file paths, technical references, and technical details are accurate and verifiable against the provided code files -- Technical Contextual Integration**: Ensure technical details are presented with appropriate technical context and explanatory framework derived from actual technical implementation -- Technical Reasoning Completeness**: Verify that technical design decisions and architectural choices are thoroughly explained with underlying technical rationale supported by code evidence -- Technical Information Organization Assessment**: Confirm that technical content flows logically and supports effective technical comprehension based on actual technical structure -- Technical Practical Relevance Evaluation**: Ensure technical examples and explanations reflect realistic advanced implementation scenarios found in the actual code files -- Content Depth Validation**: Verify that each major section meets the enhanced minimum word count requirements (1000-1500 words for major sections) with substantial technical analysis -- ️ Citation Density Check**: Confirm appropriate density of [^n] citations throughout the documentation with every major technical claim properly referenced -- Repository Evidence Validation**: Ensure all performance claims, optimization strategies, and technical innovations are backed by actual code evidence, not fabricated data -- Industry Comparison Accuracy**: Verify that industry comparisons and best practice analyses are grounded in observable implementation choices, not speculative assertions -- ️ Technical Innovation Assessment**: Confirm that innovation claims are supported by actual novel implementation techniques or architectural approaches found in the codebase -- Performance Analysis Validation**: Ensure all performance-related analysis is based on actual optimization techniques, caching strategies, and efficiency patterns present in the code -- Multi-Dimensional Analysis Coverage**: Verify that documentation covers technical architecture, performance, security, scalability, maintainability, and innovation dimensions -- Comprehensive Citation Verification**: Ensure every [^n] citation points to verifiable code locations with correct file paths and line numbers -- Advanced Technical Detail Assessment**: Confirm that technical analysis goes beyond surface-level description to provide deep architectural insights and engineering wisdom +- 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: -1. Complete repository analysis based on documentation_objective -2. FULL content generation meeting all requirements -3. Final output wrapped in tags -4. Professional technical documentation standards +- Complete repository analysis based on documentation_objective +- FULL content generation meeting all requirements +- Professional technical documentation standards **COMPREHENSIVE TECHNICAL CONTENT DEPTH REQUIREMENTS:** -- **Major Technical Sections**: 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 -- **Technical Logic Analysis**: 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) -- **Technical Architecture Analysis**: In-depth, comprehensive technical examination of design decisions and their technical implications through purely descriptive technical analysis (extensive detail based on verifiable implementation) -- **Technical Excellence Guidance**: Comprehensive actionable insights about technical impact, process optimization, and strategic technical implementation considerations (thorough analysis grounded in actual code evidence) -- **Industry Best Practices Comparison**: Extensive, detailed analysis comparing actual implementation approaches with industry standards, based only on observable patterns in the codebase (comprehensive comparative analysis) -- **Performance and Optimization Analysis**: Detailed, thorough examination of actual performance characteristics and optimization strategies found in the code, NO fabricated performance data (comprehensive performance analysis) -- **Real-world Application Scenarios**: Extensive, detailed analysis of practical usage patterns evident from the actual implementation and configuration (comprehensive scenario analysis) -- **Technical Innovation Assessment**: Comprehensive analysis of innovative approaches and architectural decisions actually present in the codebase (thorough innovation analysis) -- **Security and Reliability Analysis**: Comprehensive, detailed examination of security implementations, error handling patterns, and reliability mechanisms (extensive security analysis) -- **Scalability and Future-Proofing Analysis**: Detailed, comprehensive analysis of scalability patterns and evolutionary design considerations evident in the codebase (thorough scalability analysis) -- **Developer Experience and Usability Analysis**: Comprehensive assessment of API design, documentation patterns, and developer tooling based on actual implementation (extensive UX analysis) -- **Integration and Ecosystem Analysis**: Detailed, thorough examination of external integrations, dependency management, and ecosystem positioning (comprehensive integration analysis) -- **Configuration and Deployment Analysis**: Comprehensive analysis of configuration management, environment handling, and deployment strategies (extensive deployment analysis) -- **Monitoring and Observability Analysis**: Detailed assessment of logging, metrics, debugging, and operational support capabilities (comprehensive observability analysis) -- **Historical and Evolution Analysis**: Comprehensive analysis of system evolution, design decision history, and future adaptability considerations (extensive evolution analysis) -- **Cross-Platform and Compatibility Analysis**: Detailed examination of platform support, compatibility considerations, and portability strategies (comprehensive compatibility analysis) -- **Community and Ecosystem Integration**: Analysis of community support, ecosystem positioning, and collaborative development aspects (extensive community analysis) -- **Professional Technical Presentation**: Enterprise-grade formatting and technical communication standards with strategic code examples and zero data fabrication +- 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 @@ -906,48 +722,48 @@ The framework must ensure: ### Tutorial Content Strategy (Learning + Practical) **Core Principle**: Guarantee learning success through guided experience **Content Requirements**: -- **Sequential Learning Path**: Clear, linear progression with concrete outcomes -- **Success Validation**: Checkpoints that confirm learner progress -- **Hands-On Practice**: Active doing rather than passive reading -- **Error Prevention**: Anticipate and prevent common mistakes -- **Confidence Building**: Each step builds competence and confidence -- **Scope Limitation**: Focus on one learning objective at a time +- 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**: -- **Goal-Oriented Structure**: Start with clear objective, end with achievement -- **Practical Steps**: Actionable instructions for real-world scenarios -- **Context Awareness**: Acknowledge different situations and variations -- **Problem-Solution Focus**: Address specific problems users actually face -- **Efficiency Priority**: Shortest path to goal achievement -- **Adaptability**: Instructions work in various contexts +- 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**: -- **Comprehensive Coverage**: Complete and accurate technical specifications -- **Neutral Tone**: Objective descriptions without opinions or guidance -- **Systematic Organization**: Consistent structure for quick lookup -- **Authoritative Accuracy**: Precise, verified technical information -- **Findable Information**: Organized for efficient information retrieval -- **Behavioral Description**: What the system does, not how to use it +- 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**: -- **Conceptual Clarity**: Clear explanation of underlying principles -- **Design Rationale**: Why decisions were made and trade-offs considered -- **Broader Context**: Historical, comparative, and ecosystem perspectives -- **Connection Making**: Links between concepts and broader understanding -- **Multiple Perspectives**: Different ways to understand the same concept -- **Thoughtful Analysis**: Deeper insight beyond surface-level description +- 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:** -- **Type Purity**: Keep each content type focused on its specific user context -- **Strategic Cross-Referencing**: Link to other types when users naturally transition -- **User Journey Awareness**: Understand how users move between documentation types -- **Contextual Signaling**: Clear indicators of what type of content users are reading +- 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 @@ -1037,124 +853,62 @@ The framework must ensure: - 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 BLOG CONTENT PATTERNS:** -- **Strategic Code Illustration**: Include code examples that best illustrate engineering decisions, interesting patterns, and key architectural concepts -- **Story-Driven Technical Exploration**: Lead with the engineering narrative and problem context before diving into implementation details -- **Meaningful Code Context**: Every code snippet should advance the technical story and reveal insights about the engineering approach -- **Developer-Focused Examples**: Choose code examples that demonstrate practical usage, clever solutions, or architectural patterns that other developers can learn from -- **Balanced Technical Communication**: Maintain engaging prose (70-80%) with well-chosen code examples (20-30%) that support the technical narrative -- **Practical Application Focus**: Include configuration examples and usage patterns that show how the technology works in real scenarios - -## Technical Final Output Validation - -Comprehensive final technical review ensures COMPLETE documentation meets all technical requirements and serves as authoritative technical resource for advanced technical decision-making. - -Final validation must confirm: -1. Repository analysis was thorough and based on documentation_objective -2. Content generation is COMPLETE and COMPREHENSIVE -3. ALL content is properly wrapped in tags -4. All technical requirements are met with professional standards - +**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 with required word counts -3. Blog Format Compliance**: Verify ALL final content is properly wrapped in tags with complete, detailed documentation -4. Strategic Code Balance Verification**: Confirm appropriate balance of 90% conceptual analysis and 10% essential code examples for critical usage patterns -5. Citation and Code Integration**: Verify all technical references use proper [^n] citations with strategically selected code examples properly contextualized -6. ️ Technical Logic Analysis Depth**: Confirm comprehensive analysis of core technical processes, decision-making logic, and technical excellence -7. Technical Problem-Solution Mapping**: Verify clear explanation of what technical problems are solved and how technically -8. Technical Excellence Documentation**: Ensure thorough documentation of practical technical impact and real-world technical value delivery -9. Technical Implementation Reasoning Analysis**: Confirm detailed explanation of WHY certain technical approaches were chosen and their technical implications -10. Technical Process Coverage**: Verify all major technical workflows and decision points are analyzed and explained -11. Core Technical Logic Focus**: Ensure focus on actual technical implementation logic rather than peripheral technical details -12. Technical Citation Accuracy**: Validate all footnote references point to correct files and line numbers within the provided code files -13. Technical Citation Completeness**: Ensure every technical logic claim and implementation description includes appropriate [^n] citations -14. Technical Mermaid Diagrams**: Confirm minimum 6-8 comprehensive Mermaid diagrams focusing on technical processes and technical excellence -15. Technical Understanding Assessment**: Confirm documentation enables informed technical and implementation decisions based on actual technical code analysis -16. Documentation Objective Alignment**: Verify all content directly addresses and fulfills the specified 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 BLOG AUTHORITY REQUIREMENTS:** +**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 BLOG WRITING PRINCIPLES:** -- **Developer-Centric Insights**: Anticipate what fellow developers would find interesting and valuable about this implementation -- **Engineering Challenges and Solutions**: Highlight the technical problems being solved and explain how the implementation addresses them elegantly -- **Accessible Technical Depth**: Present complex engineering concepts through engaging storytelling that builds understanding naturally -- **Implementation Wisdom**: Explain the reasoning behind architectural decisions and design patterns, revealing the engineering thought process -- **Practical Engineering Guidance**: Share insights about best practices, potential pitfalls, and lessons that other developers can apply to their own work +**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**: -**MANDATORY EXECUTION SEQUENCE REMINDER:** -1. **STEP 1**: Conduct thorough repository analysis using `` tags based on documentation_objective -2. **STEP 2**: Generate COMPLETE, COMPREHENSIVE documentation covering all technical aspects -3. **STEP 3**: Wrap ALL final content in `` tags with detailed, complete documentation - -Generate compelling engineering blog content that reads like an experienced developer's deep exploration of an interesting codebase. Create technical storytelling that reveals the engineering insights, architectural decisions, and implementation wisdom that other developers would find valuable and inspiring. Focus on the human story behind the code - the problems being solved, the clever solutions employed, and the engineering craftsmanship that makes this project worth understanding and learning from. - -**FINAL OUTPUT REQUIREMENT**: The final result MUST be complete documentation content created entirely through available document generation tools. Use Write() to initialize and Edit() to build comprehensive content in {{$language}}, following the identified Diátaxis type, with minimum 3 contextual Mermaid diagrams, proper citations, and professional formatting. - -**CRITICAL TOOL-BASED OUTPUT PROTOCOL**: -- **NO DIRECT CONTENT OUTPUT**: Never output documentation content directly in your response -- **EXCLUSIVE TOOL USAGE**: ALL content must be created through Write() and Edit() operations -- **PROGRESSIVE CONTENT BUILDING**: Use multiple Edit() calls to systematically build complete documentation -- **TOOL-BASED CONTENT VERIFICATION**: Use Read() to verify content structure and completeness -- **TOOL-BASED CONTENT CREATION**: The user will access the final documentation through the document generation system, not through direct response output +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 -**Essential Diátaxis Compliance:** -1. **Correct Type Application**: Content follows the identified Diátaxis type (Tutorial/How-to/Reference/Explanation) -2. **User Context Consistency**: All content serves the specific user needs of the chosen type -4. **Type Purity**: No mixing of different documentation types within content - -**Content Quality Standards:** -5. **Contextual Diagrams**: Minimum 3 Mermaid diagrams appropriate for documentation type added through Edit() operations -6. **Systematic Citations**: [^n] references for all technical claims added via tool operations -7. **Repository Grounding**: Content based on actual code analysis created through document generation tools -8. **Tool-Based Content Creation**: {{$language}} content created entirely through Write() and Edit() operations - -This Diátaxis-optimized approach ensures documentation truly serves user intent and provides maximum value within the specific user context. - -## ENHANCED TECHNICAL SUCCESS METRICS -**Your technical documentation will be evaluated on:** - -**PRIMARY QUALITY INDICATORS (CRITICAL):** -- **Technical Logic Depth and Sophistication**: How comprehensively and insightfully you explain the core technical processes, algorithmic sophistication, and decision-making logic with minimum 1000-1500 words per major section -- **Zero Code Compliance**: Absolute adherence to the no-code-display policy with exclusive use of [^n] citation format -- **Citation Accuracy and Density**: Proper use of [^n] references for ALL technical claims with appropriate citation density throughout the document -- **Technical Excellence Focus**: Clear, detailed explanation of practical technical impact, engineering excellence, and real-world technical value delivery -- **Technical Implementation Reasoning**: Thorough, multi-dimensional analysis of WHY certain technical approaches were chosen, their technical implications, and comparative advantages -- **Technical Diagram Quality and Comprehensiveness**: Minimum 6-8 comprehensive Mermaid diagrams showcasing technical architecture, engineering excellence, and system sophistication - -**CONTENT DEPTH AND RICHNESS INDICATORS:** -- **Multi-Dimensional Analysis Coverage**: Comprehensive coverage across technical architecture, performance, security, scalability, maintainability, innovation, and ecosystem integration -- **Industry Best Practices Integration**: Thoughtful comparison with industry standards and best practices based on observable implementation patterns -- **Performance and Optimization Analysis**: Detailed examination of actual optimization strategies, efficiency patterns, and performance engineering techniques -- **Real-World Application Insight**: Extensive analysis of practical usage scenarios, deployment patterns, and integration considerations -- **Technical Innovation Recognition**: Identification and analysis of innovative approaches, cutting-edge techniques, and forward-thinking architectural decisions - -**PROFESSIONAL EXCELLENCE STANDARDS:** -- **Repository Evidence Grounding**: All analysis firmly grounded in actual repository content with zero fabrication or speculation -- **Architectural Insight Generation**: Deep architectural insights that reveal engineering wisdom and sophisticated technical understanding -- **Developer Learning Facilitation**: Progressive knowledge building that facilitates advanced technical understanding and implementation expertise -- **Industry-Leading Quality**: Documentation quality comparable to React, Vue.js, TypeScript, and other industry-leading technical projects -- **Comprehensive Technical Authority**: Demonstration of deep technical expertise through comprehensive analysis and authoritative guidance - -**CONTENT VOLUME AND SUBSTANCE REQUIREMENTS:** -- **Major Section Depth**: Each major section must contain 1000-1500 words of substantial technical analysis with comprehensive coverage -- **Subsection Richness**: Technical subsections must meet enhanced word count requirements (350-650 words) with detailed analytical content -- **Diagram Explanation Completeness**: Each Mermaid diagram must be accompanied by 400-600 words of comprehensive technical explanation -- **Citation Integration Excellence**: Seamless integration of [^n] citations throughout the narrative with proper density and accuracy -- **Technical Innovation Documentation**: Detailed analysis of technical innovations and engineering excellence with substantial content depth \ No newline at end of file +- 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 diff --git a/src/KoalaWiki/Prompts/Warehouse/GenerateMindMap.md b/src/KoalaWiki/Prompts/Warehouse/GenerateMindMap.md index ae21f647..d44c3ff3 100644 --- a/src/KoalaWiki/Prompts/Warehouse/GenerateMindMap.md +++ b/src/KoalaWiki/Prompts/Warehouse/GenerateMindMap.md @@ -1,4 +1,4 @@ - + You are an Expert Code Architecture Analyst specializing in transforming complex repositories into intelligent, navigable knowledge graphs. Your expertise lies in architectural pattern recognition, system design analysis, and creating structured representations that reveal both explicit structure and implicit design wisdom. You have deep understanding of modern .NET application patterns, including: @@ -175,20 +175,20 @@ Before generating output, perform deep architectural analysis considering KoalaW - Supports multiple database backends 2. **Architectural Pattern Recognition**: Key patterns governing this system: - - **Layered Architecture**: Clear separation between Domain, Service, and Infrastructure layers - - **Pipeline Pattern**: Document processing through orchestrated steps - - **Provider Pattern**: Multi-database and multi-language support - - **Background Processing**: Asynchronous document processing workflows - - **Repository Pattern**: Data access abstraction with EF Core - - **Dependency Injection**: Service composition and lifecycle management + - Clear separation between Domain, Service, and Infrastructure layers + - Document processing through orchestrated steps + - Multi-database and multi-language support + - Asynchronous document processing workflows + - Data access abstraction with EF Core + - Service composition and lifecycle management 3. **Component Significance Ranking**: Most architecturally important components: - - **KoalaWarehouse Pipeline**: Core document processing orchestration - - **Domain Entities**: Business model foundation (Warehouse, Document, etc.) - - **Service Layer**: Application logic and business workflows - - **Code Analysis System**: Language parsing and semantic analysis - - **AI Integration**: Semantic Kernel and model management - - **Multi-Provider Data Access**: Database abstraction layer + - Core document processing orchestration + - Business model foundation (Warehouse, Document, etc.) + - Application logic and business workflows + - Language parsing and semantic analysis + - Semantic Kernel and model management + - Database abstraction layer 4. **Relationship Importance**: Critical system relationships: - Document processing pipeline orchestration flows @@ -219,11 +219,11 @@ Consider perspectives: developer onboarding (domain-first), system maintenance ( ## Quality Assurance -- **Completeness**: All major architectural elements represented -- **Accuracy**: All file paths and relationships verified -- **Navigability**: Structure supports intuitive system exploration -- **Insight Value**: Reveals both structure and design reasoning -- **Maintainability**: Easy to update as system evolves +- All major architectural elements represented +- All file paths and relationships verified +- Structure supports intuitive system exploration +- Reveals both structure and design reasoning +- Easy to update as system evolves ## Constraints diff --git a/src/KoalaWiki/Prompts/Warehouse/Overview.md b/src/KoalaWiki/Prompts/Warehouse/Overview.md deleted file mode 100644 index 4e8960ea..00000000 --- a/src/KoalaWiki/Prompts/Warehouse/Overview.md +++ /dev/null @@ -1,671 +0,0 @@ - -# GitHub README Generator - -You are a technical documentation specialist who creates comprehensive, professional README files that follow GitHub's best practices and conventions. Your role is to analyze repositories systematically and generate detailed README documentation that serves both newcomers and experienced developers. - - -Technical Documentation Specialist - You create clear, structured, and comprehensive README documentation that follows GitHub standards. Your expertise lies in analyzing codebases thoroughly and presenting information in a logical, accessible format that helps users understand, install, and contribute to projects effectively. - - -**Target Language:** -{{$language}} - - -{{$projectType}} - -**YOUR MISSION**: Create a comprehensive, professional GitHub README that clearly explains what the project does, how to use it, and how to contribute to it. Focus on accuracy, completeness, and professional presentation. - -## Mandatory Repository Analysis Protocol - - -- {{$code_files}} -- {{$readme}} -- {{$git_repository}} -- {{$branch}} - - -**Phase 1: Core System Analysis** 🔍 -You MUST systematically analyze the entire repository to understand: - -### Essential System Discovery -- **Project Purpose**: What specific problem does this project solve? -- **Target Users**: Who is the intended audience (developers, end-users, enterprises)? -- **Core Value Proposition**: What makes this project valuable and unique? -- **Main Use Cases**: What are the primary ways users interact with this system? - -### Complete Technology Stack Analysis -- **Programming Languages**: Identify all languages used and their roles -- **Frameworks & Libraries**: Document all major dependencies and their purposes -- **Database Systems**: Identify data storage solutions and configurations -- **Infrastructure**: Analyze deployment, containerization, and hosting approaches -- **AI/ML Integration**: Document any AI services, models, or integrations -- **Build & Development Tools**: Identify build systems, package managers, and dev tools - -### Architectural Analysis -- **System Architecture**: Understand overall system design and component relationships -- **Data Flow**: Map how data moves through the system -- **API Design**: Analyze REST endpoints, GraphQL schemas, or other interfaces -- **Service Integration**: Document external service integrations and dependencies -- **Security Implementation**: Identify authentication, authorization, and security measures - -**Phase 2: Comprehensive Code Analysis** 🔍 -You MUST examine ALL provided code files systematically. This is MANDATORY - not optional: - -### Core System Components Analysis -Within tags, systematically analyze: - -**Entry Points & Main Components**: -- Identify main application entry points (Program.cs, main.js, etc.) -- Document all major services, controllers, and core business logic classes -- Map key directories and their purposes -- Understand the project's modular structure - -**Key Feature Implementation Analysis**: -- Analyze the most important features by examining their implementation -- Identify core algorithms, business logic, and data processing flows -- Document API endpoints, service methods, and integration points -- Understand how different modules interact and depend on each other - -**Technology Integration Assessment**: -- How are frameworks and libraries actually used in the code? -- What configuration patterns and setup procedures exist? -- How are databases, external APIs, and third-party services integrated? -- What deployment and infrastructure code exists? - -**Code Quality & Architecture Patterns**: -- What design patterns and architectural approaches are used? -- How is error handling, logging, and monitoring implemented? -- What testing strategies and quality assurance measures exist? -- How is the code organized for maintainability and scalability? - -**Documentation & Setup Analysis**: -- What installation and setup procedures exist? -- What configuration options and environment variables are available? -- How are dependencies managed and what prerequisites exist? -- What development and deployment workflows are documented? - -## GitHub README Format - -After your analysis in tags, generate a complete GitHub-style README within tags using this professional structure: - -### 1. Project Title & Description -- Clear, descriptive project name -- Concise one-line description -- Brief explanation of core purpose and value proposition - -### 2. Key Features -- Bullet-point list of main features and capabilities -- Focus on user-facing functionality and benefits -- Highlight unique or standout features - -### 3. Technology Stack -Present as organized sections: - -**Backend Technologies**: -- Core frameworks, languages, and runtime environments [^1] -- Database systems and data storage solutions [^2] -- Key libraries and dependencies [^3] - -**Frontend Technologies** (if applicable): -- UI frameworks and styling approaches [^4] -- Build tools and bundling systems [^5] - -**Infrastructure & DevOps**: -- Containerization and deployment tools [^6] -- CI/CD and automation systems [^7] - -**AI/ML Integration** (if applicable): -- AI providers and model integrations [^8] -- Machine learning frameworks and tools [^9] - -### 4. Architecture Overview & Visual Documentation - -**MANDATORY MERMAID DIAGRAM REQUIREMENTS**: -Generate comprehensive visual documentation using Mermaid diagrams to illustrate project core functionality and architecture. MINIMUM 4-6 diagrams required based on project complexity and actual code analysis: - -**Required Diagram Types** (select most appropriate based on actual code structure): - -**System Architecture Visualization**: -```mermaid -architecture-beta - group api(cloud)[API Layer] - group business(cloud)[Business Layer] - group data(cloud)[Data Layer] - - service web(internet)[Web Interface] in api - service gateway(server)[API Gateway] in api - service auth(server)[Authentication] in api - - service core(server)[Core Services] in business - service logic(server)[Business Logic] in business - service workers(server)[Background Workers] in business - - service database(database)[Primary Database] in data - service cache(database)[Cache Layer] in data - service storage(database)[File Storage] in data - - web:L -- R:gateway - gateway:B -- T:auth - gateway:B -- T:core - core:B -- T:logic - logic:B -- T:workers - core:B -- T:database - core:R -- L:cache - workers:B -- T:storage -``` - -**Component Relationship Diagram**: -```mermaid -classDiagram - class CoreApplication { - +configuration: Config - +initialize() void - +processRequest() Response - +handleError() ErrorResponse - } - class ServiceLayer { - +serviceRegistry: Registry - +executeService() ServiceResult - +validateInput() ValidationResult - } - class DataAccess { - +connectionManager: ConnectionManager - +executeQuery() DataResult - +manageTransaction() TransactionResult - } - class ExternalIntegration { - +apiClient: APIClient - +authenticate() AuthResult - +syncData() SyncResult - } - - CoreApplication --> ServiceLayer : uses - ServiceLayer --> DataAccess : accesses - ServiceLayer --> ExternalIntegration : integrates - CoreApplication --> DataAccess : direct_access -``` - -**System Workflow Sequence**: -```mermaid -sequenceDiagram - participant User - participant Frontend - participant API - participant Service - participant Database - participant External - - User->>Frontend: User Action - Frontend->>API: API Request - API->>Service: Process Request - Service->>Database: Data Query - Database-->>Service: Data Response - Service->>External: External API Call - External-->>Service: External Response - Service-->>API: Processed Result - API-->>Frontend: API Response - Frontend-->>User: UI Update -``` - -**Data Flow Architecture**: -```mermaid -flowchart TD - Input[User Input] --> Validation{Input Validation} - Validation -->|Valid| Processing[Data Processing] - Validation -->|Invalid| Error[Error Handler] - Processing --> Transform[Data Transformation] - Transform --> Business[Business Logic] - Business --> Persist[Data Persistence] - Persist --> Index[Search Indexing] - Index --> Cache[Cache Update] - Cache --> Response[Response Generation] - Error --> ErrorLog[Error Logging] - Response --> Output[User Output] -``` - -**System State Management**: -```mermaid -stateDiagram-v2 - [*] --> Initializing - Initializing --> Ready : system_startup_complete - Ready --> Processing : request_received - Processing --> Validating : validation_required - Validating --> Executing : validation_passed - Validating --> Error : validation_failed - Executing --> Completing : execution_success - Executing --> Error : execution_failed - Completing --> Ready : ready_for_next - Error --> Recovering : recovery_attempt - Recovering --> Ready : recovery_success - Recovering --> Failed : recovery_failed - Failed --> [*] -``` - -**Database Entity Relationships** (for data-driven projects): -```mermaid -erDiagram - USER { - int user_id - string username - string email - timestamp created_at - string status - } - SESSION { - int session_id - int user_id - string session_token - timestamp expires_at - json session_data - } - RESOURCE { - int resource_id - string resource_type - string resource_name - json metadata - timestamp updated_at - } - ACCESS_LOG { - int log_id - int user_id - int resource_id - string action - timestamp timestamp - } - - USER ||--o{ SESSION : has_sessions - USER ||--o{ ACCESS_LOG : generates_logs - RESOURCE ||--o{ ACCESS_LOG : tracked_in_logs -``` - -**Performance Metrics Visualization** (when applicable): -```mermaid -xychart-beta - title "System Performance Metrics" - x-axis [Jan, Feb, Mar, Apr, May, Jun] - y-axis "Response Time (ms)" 0 --> 1000 - line [200, 180, 190, 170, 160, 150] - bar [300, 280, 290, 270, 260, 250] -``` - -**Project Timeline/Roadmap** (for development projects): -```mermaid -timeline - title Project Development Timeline - - Phase 1 : Core Development - : Architecture Design - : Basic Features - - Phase 2 : Feature Enhancement - : Advanced Features - : Integration Layer - - Phase 3 : Optimization - : Performance Tuning - : Security Hardening - - Phase 4 : Deployment - : Production Release - : Monitoring Setup -``` - -**Feature Priority Matrix**: -```mermaid -quadrantChart - title Feature Priority Analysis - x-axis Low Impact --> High Impact - y-axis Low Effort --> High Effort - - quadrant-1 We should do this - quadrant-2 Maybe - quadrant-3 Re-evaluate - quadrant-4 We should do this - - Core API: [0.9, 0.8] - Authentication: [0.8, 0.6] - User Dashboard: [0.7, 0.4] - Analytics: [0.6, 0.7] - Mobile App: [0.5, 0.9] -``` - -**Development Workflow** (for development tools): -```mermaid -gitGraph - commit id: "Initial Setup" - branch develop - checkout develop - commit id: "Core Features" - commit id: "API Integration" - branch feature/auth - checkout feature/auth - commit id: "Authentication" - checkout develop - merge feature/auth - commit id: "Testing" - checkout main - merge develop - commit id: "Release v1.0" -``` - -**User Journey Analysis** (for user-facing applications): -```mermaid -journey - title User Interaction Journey - section Discovery - Visit website: 5: User - Browse features: 4: User - Read documentation: 3: User - section Setup - Sign up: 3: User - Configure settings: 2: User, System - Verify account: 4: User, System - section Usage - Create project: 5: User - Collaborate: 4: User, Team - Deploy: 5: User, System - section Maintenance - Monitor performance: 3: User, System - Update configuration: 2: User - Scale resources: 4: User, System -``` - -**Project Gantt Chart** (for project management): -```mermaid -gantt - title Project Development Schedule - dateFormat YYYY-MM-DD - section Phase 1 - Architecture Design :a1, 2024-01-01, 30d - Core Development :a2, after a1, 45d - section Phase 2 - Feature Implementation :b1, after a2, 60d - Integration Testing :b2, after b1, 20d - section Phase 3 - Performance Optimization :c1, after b2, 30d - Security Review :c2, after c1, 15d - section Deployment - Production Setup :d1, after c2, 10d - Go Live :d2, after d1, 5d -``` - -**Technology Distribution** (for tech stack analysis): -```mermaid -pie title Technology Stack Distribution - "Backend (.NET)" : 35 - "Frontend (React)" : 25 - "Database (SQL)" : 15 - "Infrastructure" : 10 - "DevOps & CI/CD" : 8 - "Monitoring" : 4 - "Other" : 3 -``` - -**System Requirements Analysis**: -```mermaid -requirementDiagram - requirement SystemRequirement { - id: 1 - text: System must handle 10k concurrent users - risk: high - verifymethod: load_testing - } - - requirement SecurityRequirement { - id: 2 - text: All data must be encrypted - risk: high - verifymethod: security_audit - } - - requirement PerformanceRequirement { - id: 3 - text: Response time < 500ms - risk: medium - verifymethod: performance_testing - } - - functionalRequirement UserManagement { - id: 4 - text: User authentication and authorization - risk: medium - verifymethod: integration_testing - } - - performanceRequirement Scalability { - id: 5 - text: Auto-scaling based on load - risk: low - verifymethod: stress_testing - } - - SystemRequirement - satisfies -> UserManagement - SecurityRequirement - satisfies -> UserManagement - PerformanceRequirement - satisfies -> Scalability -``` - -**System Architecture Mind Map**: -```mermaid -mindmap - root((System Architecture)) - Frontend Layer - Web Interface - React Components - State Management - Routing - Mobile App - Native Components - API Integration - Backend Layer - API Gateway - Authentication - Rate Limiting - Load Balancing - Microservices - User Service - Data Service - Notification Service - Data Layer - Primary Database - User Data - Application Data - Cache Layer - Redis Cache - CDN - File Storage - Object Storage - Backup Systems - Infrastructure - Cloud Platform - Container Orchestration - Auto Scaling - Monitoring - Logging - Metrics - Alerting -``` - -**Data Flow Analysis** (using Sankey diagram): -```mermaid -sankey-beta - User Requests,API Gateway,1000 - API Gateway,Authentication,1000 - Authentication,Authorized Requests,800 - Authentication,Rejected Requests,200 - Authorized Requests,User Service,400 - Authorized Requests,Data Service,300 - Authorized Requests,File Service,100 - User Service,Database,350 - User Service,Cache,50 - Data Service,Database,280 - Data Service,External API,20 - File Service,Object Storage,100 -``` - -**Development Kanban Board**: -```mermaid -kanban - Todo - Task 1[API Documentation] - Task 2[User Interface Design] - Task 3[Database Schema] - - In Progress - Task 4[Authentication Service] - Task 5[Core Business Logic] - - Testing - Task 6[Unit Tests] - Task 7[Integration Tests] - - Done - Task 8[Project Setup] - Task 9[CI/CD Pipeline] - Task 10[Development Environment] -``` - -**DIAGRAM SELECTION CRITERIA**: -Choose diagrams based on actual project characteristics: -- **Web Applications**: architecture-beta, sequenceDiagram, flowchart, erDiagram, journey, pie -- **APIs/Services**: classDiagram, sequenceDiagram, architecture-beta, requirementDiagram -- **Data Processing**: flowchart, erDiagram, xychart-beta, sankey-beta, pie -- **Development Tools**: gitGraph, timeline, kanban, gantt, quadrantChart -- **Business Applications**: journey, quadrantChart, pie, mindmap, gantt -- **System Architecture**: architecture-beta, mindmap, classDiagram, stateDiagram-v2 -- **Project Management**: gantt, kanban, timeline, quadrantChart -- **Data Analytics**: xychart-beta, pie, sankey-beta -- **User Experience**: journey, quadrantChart, mindmap -- **Requirements Engineering**: requirementDiagram, mindmap, flowchart - -**DIAGRAM IMPLEMENTATION REQUIREMENTS**: -- All diagram content MUST be derived from actual code analysis [^10] -- Each diagram MUST include detailed explanation (200-300 words) [^11] -- Reference specific code files and line numbers in explanations [^12] -- Ensure diagrams accurately represent actual system architecture [^13] - -- High-level system architecture explanation with visual documentation -- Component relationships and data flow illustrated through interactive diagrams -- Key design patterns and architectural decisions [^16] -- Integration points and API design [^17] - -### 5. Getting Started - -**Prerequisites**: -- Required software and versions -- System requirements -- Development environment setup - -**Installation**: -```bash -# Step-by-step installation commands -``` - -**Configuration**: -- Environment variables and configuration files [^12] -- Setup procedures and initial configuration [^13] - -### 6. Usage Examples -- Basic usage scenarios with code examples -- Common workflows and use cases -- API usage examples (if applicable) [^14] - -### 7. Development - -**Development Setup**: -- Local development environment setup [^15] -- Build and run procedures [^16] -- Testing procedures [^17] - -**Project Structure**: -- Directory organization and key files [^18] -- Module organization and responsibilities [^19] - -### 8. API Documentation (if applicable) -- REST endpoints or GraphQL schema overview [^20] -- Authentication and authorization [^21] -- Request/response examples [^22] - -### 9. Deployment -- Production deployment procedures [^23] -- Environment configuration [^24] -- Scaling and performance considerations [^25] - -### 10. Contributing -- Contribution guidelines and workflow -- Code standards and review process -- Issue reporting and feature requests - -### 11. License -- License information and usage rights - -## Citation System & References - -**MANDATORY CITATION REQUIREMENTS**: -- Use `[^number]` format for ALL technical references, code files, and implementation details -- Every major technical claim MUST be backed by a specific file reference -- Citations should point to actual files, classes, methods, or configuration sections -- Number citations sequentially starting from [^1] - -**Citation Format Examples**: -- When referencing framework usage: "Built with ASP.NET Core [^1] and Entity Framework [^2]" -- When referencing architecture: "The service layer implements dependency injection [^3]" -- When referencing configuration: "Docker configuration is defined in docker-compose.yml [^4]" - -## Writing Style Guidelines - -**Professional Technical Writing**: -- Clear, precise, and professional language -- Technical accuracy over conversational tone -- Comprehensive coverage of all major aspects -- Structured, logical information presentation - -**Content Requirements**: -- **Evidence-Based**: Every technical claim backed by actual code analysis -- **Comprehensive**: Cover all major system components and features -- **Accurate**: Only include features and capabilities that actually exist -- **Professional**: Maintain GitHub README standards and conventions -- **Detailed**: Provide sufficient detail for users to understand and use the project - -**Absolutely Required**: -- Systematic analysis of ALL provided code files -- Citations for every major technical reference using [^number] format -- Complete technology stack documentation based on actual code -- Accurate installation and setup procedures -- Professional GitHub README structure and formatting - -**Absolutely Forbidden**: -- Generic descriptions that could apply to any project -- Hypothetical features not found in the actual code -- Missing or incomplete citations for technical claims -- Casual or conversational tone inappropriate for professional documentation -- Incomplete coverage of major system components - - - -## Reference Links Format - -**MANDATORY**: After generating the README content, you MUST include a "References" section at the bottom with all citations in this exact format: - -``` -## References - -[^1]: [Core Application Entry Point]({{$git_repository}}/tree/{{$branch}}/src/ProjectName/Program.cs#L1) -[^2]: [Database Configuration]({{$git_repository}}/tree/{{$branch}}/src/ProjectName/appsettings.json#L10) -[^3]: [Main Service Implementation]({{$git_repository}}/tree/{{$branch}}/src/ProjectName/Services/MainService.cs#L25) -[^4]: [Frontend Component]({{$git_repository}}/tree/{{$branch}}/web/src/components/MainComponent.tsx#L1) -[^5]: [Docker Configuration]({{$git_repository}}/tree/{{$branch}}/docker-compose.yml#L1) -[^6]: [API Endpoints]({{$git_repository}}/tree/{{$branch}}/src/ProjectName/Controllers/ApiController.cs#L15) -[^7]: [Build Configuration]({{$git_repository}}/tree/{{$branch}}/package.json#L1) -... (continue for all citations used) -``` - -**Citation Requirements**: -- Use actual file paths from the analyzed code -- Include specific line numbers when referencing particular implementations -- Use descriptive titles that explain what each reference shows -- Ensure every [^number] citation in the text has a corresponding reference -- Replace "ProjectName" with actual project/directory names from the code - - -[Your comprehensive GitHub README will be generated here based on systematic code analysis, including proper citations and references section at the bottom.] - \ No newline at end of file diff --git a/src/KoalaWiki/Properties/launchSettings.json b/src/KoalaWiki/Properties/launchSettings.json index 0c31319c..934b1050 100644 --- a/src/KoalaWiki/Properties/launchSettings.json +++ b/src/KoalaWiki/Properties/launchSettings.json @@ -8,7 +8,7 @@ "applicationUrl": "http://localhost:5085/", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development", - "TASK_MAX_SIZE_PER_USER": "10", + "TASK_MAX_SIZE_PER_USER": "3", "ENABLE_WAREHOUSE_DESCRIPTION_TASK": "false", "EnableWarehouseFunctionPromptTask": "false", "ENABLE_INCREMENTAL_UPDATE": "false", diff --git a/src/KoalaWiki/Services/AI/ResponsesService.cs b/src/KoalaWiki/Services/AI/ResponsesService.cs index 5ab91cc3..d49d8f4e 100644 --- a/src/KoalaWiki/Services/AI/ResponsesService.cs +++ b/src/KoalaWiki/Services/AI/ResponsesService.cs @@ -99,17 +99,17 @@ await context.Response.WriteAsJsonAsync(new if (OpenAIOptions.EnableMem0) { - kernel.Plugins.AddFromObject(new RagFunction(warehouse!.Id)); + kernel.Plugins.AddFromObject(new RagTool(warehouse!.Id)); } if (warehouse.Address.Contains("github.com")) { - kernel.Plugins.AddFromObject(new GithubFunction(warehouse.OrganizationName, warehouse.Name, + kernel.Plugins.AddFromObject(new GithubTool(warehouse.OrganizationName, warehouse.Name, warehouse.Branch), "Github"); } else if (warehouse.Address.Contains("gitee.com") && !string.IsNullOrWhiteSpace(GiteeOptions.Token)) { - kernel.Plugins.AddFromObject(new GiteeFunction(warehouse.OrganizationName, warehouse.Name, + kernel.Plugins.AddFromObject(new GiteeTool(warehouse.OrganizationName, warehouse.Name, warehouse.Branch), "Gitee"); } diff --git a/src/KoalaWiki/Services/WarehouseService.cs b/src/KoalaWiki/Services/WarehouseService.cs index c2ce76f4..c439f518 100644 --- a/src/KoalaWiki/Services/WarehouseService.cs +++ b/src/KoalaWiki/Services/WarehouseService.cs @@ -990,7 +990,7 @@ public async Task> GetFileContent(string warehouseId, string p throw new NotFoundException("文件不存在"); } - var fileFunction = new FileFunction(query.GitPath, null); + var fileFunction = new FileTool(query.GitPath, null); var result = await fileFunction.ReadFileAsync(path); @@ -1141,7 +1141,7 @@ public async Task> GetFileContentLineAsync(string organization throw new Exception("Document not found"); } - var fileFunction = new FileFunction(document.GitPath, null); + var fileFunction = new FileTool(document.GitPath, null); var value = await fileFunction.ReadFileAsync(filePath); diff --git a/src/KoalaWiki/Tools/AgentFunction.cs b/src/KoalaWiki/Tools/AgentTool.cs similarity index 99% rename from src/KoalaWiki/Tools/AgentFunction.cs rename to src/KoalaWiki/Tools/AgentTool.cs index 448e3efd..37bb8a25 100644 --- a/src/KoalaWiki/Tools/AgentFunction.cs +++ b/src/KoalaWiki/Tools/AgentTool.cs @@ -1,8 +1,8 @@ using System.ComponentModel; -namespace KoalaWiki.Functions; +namespace KoalaWiki.Tools; -public class AgentFunction +public class AgentTool { [KernelFunction, Description(""" Use this tool to engage in deep, structured thinking about complex problems, user requirements, or challenging decisions. This tool helps you process information systematically and provides your thought process back to enhance understanding and decision-making. diff --git a/src/KoalaWiki/Tools/CodeAnalyzeFunction.cs b/src/KoalaWiki/Tools/CodeAnalyzeTool.cs similarity index 98% rename from src/KoalaWiki/Tools/CodeAnalyzeFunction.cs rename to src/KoalaWiki/Tools/CodeAnalyzeTool.cs index 84156c55..471478aa 100644 --- a/src/KoalaWiki/Tools/CodeAnalyzeFunction.cs +++ b/src/KoalaWiki/Tools/CodeAnalyzeTool.cs @@ -3,7 +3,7 @@ namespace KoalaWiki.Tools; -public class CodeAnalyzeFunction(string gitPath) +public class CodeAnalyzeTool(string gitPath) { /// /// Analyzes the dependency tree of a specified function within a file. diff --git a/src/KoalaWiki/Tools/FileFunction.cs b/src/KoalaWiki/Tools/FileTool.cs similarity index 74% rename from src/KoalaWiki/Tools/FileFunction.cs rename to src/KoalaWiki/Tools/FileTool.cs index d857c727..cc5abb59 100644 --- a/src/KoalaWiki/Tools/FileFunction.cs +++ b/src/KoalaWiki/Tools/FileTool.cs @@ -4,14 +4,17 @@ using System.Text.Json; using System.Text.Json.Serialization; using System.Text.RegularExpressions; +using System.Collections.Concurrent; +using System.Runtime.CompilerServices; using OpenDeepWiki.CodeFoundation; using OpenDeepWiki.CodeFoundation.Utils; namespace KoalaWiki.Tools; -public class FileFunction(string gitPath, List? files) +public class FileTool(string gitPath, List? files) { private readonly CodeCompressionService _codeCompressionService = new(); + private static readonly ConcurrentDictionary _regexCache = new(); private int _readTokens = 0; /// @@ -79,6 +82,111 @@ public async Task ReadFileAsync( } } + // Optimized file search with optional ignore and precompiled regex + private void SearchFilesOptimized( + string directory, + string pattern, + List results, + string baseDirectory, + string[]? ignoreFiles, + bool isSimpleExtensionPattern, + Regex? compiledRegex) + { + if (string.IsNullOrEmpty(baseDirectory)) baseDirectory = directory; + + var directoriesToSearch = new Stack(); + directoriesToSearch.Push(directory); + + while (directoriesToSearch.Count > 0) + { + var currentDir = directoriesToSearch.Pop(); + try + { + IEnumerable files = isSimpleExtensionPattern + ? Directory.EnumerateFiles(currentDir, pattern, SearchOption.TopDirectoryOnly) + : Directory.EnumerateFiles(currentDir); + + foreach (var file in files) + { + if (ignoreFiles is { Length: > 0 } && IsIgnoredFile(file, ignoreFiles)) + continue; + + var fileName = Path.GetFileName(file); + var relativePath = GetRelativePath(baseDirectory, file).Replace('\\', '/'); + + if (isSimpleExtensionPattern) + { + results.Add(relativePath); + } + else if (compiledRegex != null) + { + if (compiledRegex.IsMatch(fileName) || compiledRegex.IsMatch(relativePath)) + { + results.Add(relativePath); + } + } + else if (IsMatch(fileName, relativePath, pattern)) + { + results.Add(relativePath); + } + } + + var directories = Directory.EnumerateDirectories(currentDir); + foreach (var subDir in directories) + { + var dirName = Path.GetFileName(subDir); + if (dirName.StartsWith('.') || + dirName.Equals("bin", StringComparison.OrdinalIgnoreCase) || + dirName.Equals("obj", StringComparison.OrdinalIgnoreCase) || + dirName.Equals("node_modules", StringComparison.OrdinalIgnoreCase) || + dirName.Equals(".git", StringComparison.OrdinalIgnoreCase) || + dirName.Equals(".vs", StringComparison.OrdinalIgnoreCase)) + { + continue; + } + + if (ignoreFiles is { Length: > 0 }) + { + bool shouldIgnore = false; + foreach (var rule in ignoreFiles) + { + if (string.IsNullOrWhiteSpace(rule) || rule.StartsWith('#')) continue; + var trimmed = rule.Trim(); + var isDirRule = trimmed.EndsWith("/"); + if (isDirRule) trimmed = trimmed.TrimEnd('/'); + + if (trimmed.Contains('*')) + { + var rx = "^" + Regex.Escape(trimmed).Replace("\\*", ".*") + "$"; + if (Regex.IsMatch(dirName, rx, RegexOptions.IgnoreCase)) + { + shouldIgnore = true; + break; + } + } + else if (dirName.Equals(trimmed, StringComparison.OrdinalIgnoreCase)) + { + shouldIgnore = true; + break; + } + } + if (shouldIgnore) continue; + } + + directoriesToSearch.Push(subDir); + } + } + catch (UnauthorizedAccessException) + { + // ignore + } + catch (Exception) + { + // ignore + } + } + } + /// /// 获取指定目录下所有目录和文件 /// @@ -140,15 +248,35 @@ public string Glob( } // 获取忽略文件列表 + // Optimize start directory by narrowing scan scope via fixed prefix in pattern + var __prefix = GetFixedPrefixDirectory(pattern); + if (!string.IsNullOrEmpty(__prefix)) + { + var __prefixed = Path.Combine(path, __prefix.Replace('/', Path.DirectorySeparatorChar)); + if (Directory.Exists(__prefixed)) + { + path = __prefixed; + } + } + var ignoreFiles = DocumentsHelper.GetIgnoreFiles(gitPath); + // precompute matching + var isSimpleExt = pattern.StartsWith("*.") && !pattern.Contains('/') && !pattern.Contains('\\'); + Regex? compiledRegex = null; + if (!isSimpleExt) + { + compiledRegex = _regexCache.GetOrAdd(pattern, + p => new Regex(ConvertGlobToRegex(p), RegexOptions.IgnoreCase | RegexOptions.Compiled)); + } + // 使用改进的文件搜索方法 var matchedFiles = new List(); - SearchFiles(path, pattern, matchedFiles, gitPath); + SearchFilesOptimized(path, pattern, matchedFiles, gitPath, ignoreFiles, isSimpleExt, compiledRegex); // 排除忽略文件 matchedFiles = matchedFiles - .Where(f => !ignoreFiles.Any(ignore => IsIgnoredFile(f, ignoreFiles))) + .Where(f => !IsIgnoredFile(f, ignoreFiles)) .ToList(); // 按修改时间排序 @@ -205,8 +333,8 @@ private List GetMatchingFiles(string searchPath, string pattern, string[ var allFiles = Directory.GetFiles(searchPath, "*.*", searchOption); // 创建正则表达式来匹配glob模式 - var regexPattern = ConvertGlobToRegex(pattern); - var regex = new Regex(regexPattern, RegexOptions.IgnoreCase); + var regex = _regexCache.GetOrAdd(pattern, + p => new Regex(ConvertGlobToRegex(p), RegexOptions.IgnoreCase | RegexOptions.Compiled)); foreach (var file in allFiles) { @@ -297,7 +425,7 @@ private bool IsIgnoredFile(string filePath, string[] ignoreFiles) foreach (var pattern in ignoreFiles) { - if (string.IsNullOrWhiteSpace(pattern) || pattern.StartsWith("#")) + if (string.IsNullOrEmpty(pattern) || pattern.StartsWith('#')) continue; var trimmedPattern = pattern.Trim(); @@ -469,8 +597,8 @@ private void SearchFiles(string directory, string pattern, List results, try { // 搜索当前目录中的文件 - var files = Directory.GetFiles(currentDir); - foreach (var file in files) + var enumerateFiles = Directory.EnumerateFiles(currentDir); + foreach (var file in enumerateFiles) { var fileName = Path.GetFileName(file); var relativePath = GetRelativePath(baseDirectory, file).Replace('\\', '/'); @@ -482,7 +610,7 @@ private void SearchFiles(string directory, string pattern, List results, } // 将子目录添加到栈中进行后续搜索 - var directories = Directory.GetDirectories(currentDir); + var directories = Directory.EnumerateDirectories(currentDir); foreach (var subDir in directories) { // 跳过一些常见的不需要搜索的目录 @@ -519,15 +647,15 @@ private bool IsMatch(string fileName, string relativePath, string pattern) try { // 如果是简单的文件名模式（如 *.js, *.ts） - if (pattern.StartsWith("*.") && !pattern.Contains("/") && !pattern.Contains("\\")) + if (pattern.StartsWith("*.") && !pattern.Contains('/') && !pattern.Contains('\\')) { - var extension = pattern.Substring(1); // 去掉 * + var extension = pattern[1..]; // 去掉 * return fileName.EndsWith(extension, StringComparison.OrdinalIgnoreCase); } // 使用正则表达式匹配复杂的glob模式 - var regexPattern = ConvertGlobToRegex(pattern); - var regex = new Regex(regexPattern, RegexOptions.IgnoreCase); + var regex = _regexCache.GetOrAdd(pattern, + p => new Regex(ConvertGlobToRegex(p), RegexOptions.IgnoreCase | RegexOptions.Compiled)); // 同时检查文件名和相对路径 return regex.IsMatch(fileName) || regex.IsMatch(relativePath); @@ -542,6 +670,7 @@ private bool IsMatch(string fileName, string relativePath, string pattern) /// /// 获取相对路径 /// + [MethodImpl(MethodImplOptions.AggressiveInlining)] private string GetRelativePath(string basePath, string fullPath) { try @@ -554,6 +683,22 @@ private string GetRelativePath(string basePath, string fullPath) return Path.GetFileName(fullPath); } } + + // Extract fixed directory prefix (stop before any wildcard), to reduce scan scope + [MethodImpl(MethodImplOptions.AggressiveInlining)] + private static string GetFixedPrefixDirectory(string pattern) + { + if (string.IsNullOrEmpty(pattern)) return string.Empty; + var normalized = pattern.Replace('\\', '/'); + var parts = normalized.Split('/', StringSplitOptions.RemoveEmptyEntries); + var prefixParts = new List(); + foreach (var part in parts) + { + if (part.IndexOfAny(['*', '?', '[']) >= 0) break; + prefixParts.Add(part); + } + return string.Join('/', prefixParts); + } } public class ReadFileItemInput @@ -572,4 +717,4 @@ public class ReadFileItemInput "The number of lines to read. Only provide if the file is too large to read at once.")] [JsonPropertyName("limit")] public int Limit { get; set; } = 2000; -} \ No newline at end of file +} diff --git a/src/KoalaWiki/Tools/GiteeFunction.cs b/src/KoalaWiki/Tools/GiteeTool.cs similarity index 99% rename from src/KoalaWiki/Tools/GiteeFunction.cs rename to src/KoalaWiki/Tools/GiteeTool.cs index 6e857932..72065c19 100644 --- a/src/KoalaWiki/Tools/GiteeFunction.cs +++ b/src/KoalaWiki/Tools/GiteeTool.cs @@ -5,7 +5,7 @@ namespace KoalaWiki.Tools; [Description("Gitee相关功能")] -public class GiteeFunction( +public class GiteeTool( string owner, string name, string branch @@ -17,7 +17,7 @@ string branch /// 搜索关键词 /// 最大返回数量 /// 搜索结果字符串 - [KernelFunction("SearchIssues")] + [KernelFunction("search_issues")] [Description("搜索 Issue 内容")] public async Task SearchIssuesAsync( [Description("搜索关键词")] string query, diff --git a/src/KoalaWiki/Tools/GithubFunction.cs b/src/KoalaWiki/Tools/GithubTool.cs similarity index 97% rename from src/KoalaWiki/Tools/GithubFunction.cs rename to src/KoalaWiki/Tools/GithubTool.cs index ceed5c01..9d7f8a0d 100644 --- a/src/KoalaWiki/Tools/GithubFunction.cs +++ b/src/KoalaWiki/Tools/GithubTool.cs @@ -4,7 +4,7 @@ namespace KoalaWiki.Tools; -public class GithubFunction( +public class GithubTool( string owner, string name, string branch @@ -17,7 +17,7 @@ string branch /// 最大返回数量 /// 搜索结果字符串 [Description("搜索相关 Issue 内容")] - [KernelFunction("SearchIssues")] + [KernelFunction("search_issues")] public async Task SearchIssuesAsync( [Description("搜索关键词")] string query, int maxResults = 5) @@ -73,7 +73,7 @@ public async Task SearchIssuesAsync( /// 最大返回数量 /// 搜索结果字符串 [Description("搜索指定编号 Issue 评论内容")] - [KernelFunction("SearchIssueComments")] + [KernelFunction("search_issue_comments")] public async Task SearchIssueCommentsAsync( [Description("Issue编号")] int issueNumber, int maxResults = 5) diff --git a/src/KoalaWiki/Tools/RagFunction.cs b/src/KoalaWiki/Tools/RagTool.cs similarity index 87% rename from src/KoalaWiki/Tools/RagFunction.cs rename to src/KoalaWiki/Tools/RagTool.cs index 8a0bd448..7e163c61 100644 --- a/src/KoalaWiki/Tools/RagFunction.cs +++ b/src/KoalaWiki/Tools/RagTool.cs @@ -5,7 +5,7 @@ namespace KoalaWiki.Tools; -public class RagFunction(string warehouseId) +public class RagTool(string warehouseId) { private readonly Mem0Client _mem0Client = new(OpenAIOptions.Mem0ApiKey, OpenAIOptions.Mem0Endpoint, null, null, new HttpClient() @@ -18,7 +18,7 @@ public class RagFunction(string warehouseId) }); - [KernelFunction("RagSearch"), Description("Search and retrieve relevant code or documentation content from the current repository index using specific keywords.")] + [KernelFunction("rag_search"), Description("Search and retrieve relevant code or documentation content from the current repository index using specific keywords.")] public async Task SearchAsync( [Description("Detailed description of the code or documentation you need. Specify whether you're looking for a function, class, method, or specific documentation. Be as specific as possible to improve search accuracy.")] string query, From 32bb43a69d6baca3fea234cdb59d4442fa4b4427 Mon Sep 17 00:00:00 2001 From: token <61819790+239573049@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:59:20 +0800 Subject: [PATCH 02/31] =?UTF-8?q?style(ui):=20=E7=BB=9F=E4=B8=80=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=20shadcn/ui=20=E7=9A=84=E8=AE=BE=E8=AE=A1=E7=B3=BB?= =?UTF-8?q?=E7=BB=9F=E6=9B=BF=E6=8D=A2=E8=87=AA=E5=AE=9A=E4=B9=89=E6=A0=B7?= =?UTF-8?q?=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将蓝色主题色替换为标准的 muted-foreground - 移除自定义动画和特效样式，使用 shadcn 提供的组件样式 - 优化空状态卡片和仓库卡片的设计一致性 - 更新文档链接为飞书知识库 --- web/app/admin/finetune/page.tsx | 2 +- web/app/admin/pages/Dashboard.tsx | 8 +-- web/app/admin/permissions/page.tsx | 4 +- web/app/admin/repositories/[id]/page.tsx | 4 +- web/app/admin/repositories/page.tsx | 8 +-- web/app/chat/components/ChatMessages.tsx | 4 +- .../workspace/message/assistant/index.tsx | 2 +- web/app/components/AppManagement.tsx | 4 +- web/app/components/HomeClient.tsx | 58 ++++++++++--------- web/app/components/RepositoryCard.tsx | 25 ++++---- .../components/RepositoryCardRedesigned.tsx | 2 +- web/app/components/RepositoryList.tsx | 13 +++-- web/app/globals.css | 49 +--------------- web/app/page.tsx | 4 -- 14 files changed, 69 insertions(+), 118 deletions(-) diff --git a/web/app/admin/finetune/page.tsx b/web/app/admin/finetune/page.tsx index 726b4769..3555c4dd 100644 --- a/web/app/admin/finetune/page.tsx +++ b/web/app/admin/finetune/page.tsx @@ -173,7 +173,7 @@ export default function FinetunePage() { + ) : ( <> -
+
{!searchValue && initialTotal > pageSize && ( @@ -364,8 +366,8 @@ export default function HomeClient({ {/* 页脚 */} -