@aigne/doc-smith 0.8.12-beta.3 → 0.8.12-beta.4

package/docs/release-notes.zh.md

@@ -0,0 +1,255 @@
+# 发行说明
+
+本文档总结了该工具每个版本的新功能、改进和错误修复。所有变更均按时间倒序排列。
+
+## 版本 0.8.12-beta.3 (2025-10-09)
+
+### 错误修复
+
+- 解决了发布到云端时错误地要求管理员权限的问题。
+
+## 版本 0.8.12-beta.2 (2025-10-09)
+
+### 错误修复
+
+- 修正了更新文档时文件路径的错误。
+- 修复了可能导致文档生成和更新失败的问题。
+
+## 版本 0.8.12-beta.1 (2025-10-08)
+
+### 新功能
+
+- 引入了历史记录跟踪功能，允许您查看文档的过往变更。
+- 在文档更新过程中，翻译现在是一个可选步骤，提供了更大的灵活性。
+
+### 改进
+
+- 优化了文档生成和更新流程，以提高可靠性。
+
+## 版本 0.8.12-beta (2025-10-07)
+
+### 错误修复
+
+- 内部文件读取工具现在可以正确支持相对路径。
+
+## 版本 0.8.11 (2025-10-05)
+
+此版本包含常规维护和稳定性改进。
+
+## 版本 0.8.11-beta.7 (2025-10-03)
+
+### 新功能
+
+- 增强了文档生成器和更新器，以获得更好的性能。
+- 通过使用共享上下文，提高了文档结构分析和内容优化的速度。
+
+### 错误修复
+
+- 更新了内部文档并优化了自定义组件的提示，以提高准确性。
+
+## 版本 0.8.11-beta.5 (2025-10-01)
+
+### 新功能
+
+- 新增了对发布时的用户角色要求和自定义规则配置的支持。
+- 将 D2 图表生成功能分离为一个独立的工具，以实现更专注的功能。
+
+## 版本 0.8.11-beta.4 (2025-09-30)
+
+### 新功能
+
+- 为使用选择输入的 Agent 添加了“仅检查”选项。
+
+### 错误修复
+
+- 改进了文档选择实用程序中的错误处理。
+- 调整了翻译提示；现在代码块内的注释可以被正确翻译。
+
+## 版本 0.8.11-beta.3 (2025-09-29)
+
+### 错误修复
+
+- 为评估 Agent 添加了命令行入口。
+
+## 版本 0.8.11-beta.2 (2025-09-27)
+
+### 错误修复
+
+- 解决了依赖冲突，以确保更平稳的运行。
+
+## 版本 0.8.11-beta.1 (2025-09-27)
+
+### 新功能
+
+- 引入了文档评估功能，以生成质量报告。
+- 通过改进的工具增强了文档和结构的更新流程。
+- 改进了发布过程中的供应商处理和调试能力。
+
+### 错误修复
+
+- 修复了组件描述被当作属性而非文本处理的问题，从而改进了自定义组件的渲染。
+
+## 版本 0.8.10 (2025-09-20)
+
+此版本包含常规维护和稳定性改进。
+
+## 版本 0.8.10-beta.3 (2025-09-19)
+
+### 错误修复
+
+- 添加了与企业部署相关的链接。
+- 优化了文档审查提示的文案。
+
+## 版本 0.8.10-beta.2 (2025-09-18)
+
+### 错误修复
+
+- 改进了文档结构审查的提示和显示。
+- 更新了字段元素的使用规则，以确保正确渲染。
+
+## 版本 0.8.10-beta.1 (2025-09-18)
+
+### 新功能
+
+- 新增了在生成前审查文档结构的工作流。
+
+### 错误修复
+
+- 提高了用户界面中英文文本的一致性和清晰度。
+- 更新了 DocSmith 徽标。
+
+## 版本 0.8.9 (2025-09-15)
+
+### 错误修复
+
+- 更新了 D2 图表的主题颜色，以获得更好的视觉一致性。
+
+## 版本 0.8.8 (2025-09-13)
+
+### 错误修复
+
+- 优化了问询反馈的文案，使其更清晰、更有帮助。
+
+## 版本 0.8.7 (2025-09-12)
+
+### 新功能
+
+- 新增了使用 `<x-field>` 自定义组件定义 API 参数的支持。
+
+## 版本 0.8.6 (2025-09-11)
+
+### 新功能
+
+- 成功发布后，现在默认显示 URL。
+
+### 错误修复
+
+- 确保在部署过程中正确保存日志，以防止数据丢失。
+
+## 版本 0.8.5 (2025-09-10)
+
+### 新功能
+
+- 新增了对将文档发布到企业空间的支持。
+
+## 版本 0.8.4 (2025-09-09)
+
+### 错误修复
+
+- Markdown 代码块现在被解析为自定义的 `<x-code>` 元素，并支持标题和图标等增强属性。
+- 将 D2 图表的背景设置为透明，以便更好地与不同主题集成。
+
+## 版本 0.8.3 (2025-09-05)
+
+### 错误修复
+
+- 为本地图片添加了自动尺寸检测功能，以确保其正确显示。
+
+## 版本 0.8.1 (2025-09-03)
+
+### 新功能
+
+- 通过更全面的示例调整了 D2 图表生成，以提高输出质量。
+
+## 版本 0.8.0 (2025-09-03)
+
+### 新功能
+
+- 更新了自定义组件的指南，增加了新的格式限制。
+
+## 版本 0.7.1 (2025-08-31)
+
+### 错误修复
+
+- 修复了使用 Tab 键进行路径选择时无法正常工作的错误。
+
+## 版本 0.7.0 (2025-08-30)
+
+### 新功能
+
+- 新增了用于生成和管理文档的交互式聊天模式。
+- 在文档生成和发布工作流中引入了对 D2 图表的支持。
+- 启用了对自定义组件和更强大的配置处理的支持。
+
+## 版本 0.6.0 (2025-08-27)
+
+### 新功能
+
+- 实现了在发布文档前对媒体进行处理的完整支持。
+
+## 版本 0.5.0 (2025-08-26)
+
+### 新功能
+
+- 用户反馈现在可以作为持久化偏好保存，供未来会话使用。
+
+### 错误修复
+
+- 优化了初始设置过程中提问的文本。
+
+## 版本 0.4.4 (2025-08-22)
+
+### 错误修复
+
+- 新增了在发布过程中分配看板 ID 的支持。
+
+## 版本 0.4.1 (2025-08-21)
+
+### 错误修复
+
+- 新增了对更新看板信息的支持。
+
+## 版本 0.4.0 (2025-08-20)
+
+### 新功能
+
+- 引入了用于翻译文档的新命令 `translate`。
+
+## 版本 0.3.0 (2025-08-19)
+
+### 新功能
+
+- 优化了在文档生成期间收集上下文的工作流。
+
+### 错误修复
+
+- 优化了为运行自托管 Discuss Kit 实例的用户提供的帮助文本。
+
+## 版本 0.2.11 (2025-08-15)
+
+### 错误修复
+
+- 更换了默认语言模型以提高生成质量。
+
+## 版本 0.2.5 (2025-08-08)
+
+### 错误修复
+
+- 优化了命令行界面流程，以提供更流畅的用户体验。
+
+## 版本 0.2.0 (2025-08-05)
+
+### 新功能
+
+- 现在，当运行命令时，如果配置缺失，工具将自动初始化配置。
+- 新增了 `update` 命令，用于在源文件发生更改时刷新文档。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.12-beta.3",
+  "version": "0.8.12-beta.4",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,7 @@
     "@aigne/gemini": "^0.14.0",
     "@aigne/openai": "^0.16.0",
     "@aigne/publish-docs": "^0.11.0",
-    "@blocklet/payment-broker-client": "^1.21.5",
+    "@blocklet/payment-broker-client": "^1.21.10",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11",
@@ -28,6 +28,8 @@
     "dompurify": "^3.2.6",
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
+    "gpt-tokenizer": "^3.2.0",
+    "isbinaryfile": "^5.0.6",
     "jsdom": "^26.1.0",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",

package/prompts/common/document/content-rules-core.md

@@ -12,6 +12,7 @@ Content Generation Rules:
 {% endif %}
 - Output complete information including all content planned for the {{nodeName}}
 - Ensure each {{nodeName}} detail includes a markdown level-1 heading displaying the current {{nodeName}} title: {{title}}
+- Maintain a strict, sequential heading hierarchy; no skipping (e.g., no jump from level-1 to level-3).
 - Format markdown output with proper line breaks and spacing for easy reading
 - For list data with many items, prioritize using markdown table for cleaner, more readable presentation
 - Do not mention 'DataSources' in output, your content is for user consumption, and users are unaware of DataSources

package/prompts/common/document-structure/document-structure-rules.md

@@ -10,15 +10,14 @@ DataSources usage rules:
 Structural planning rules:
 
 1. {{nodeName}} planning should prioritize user-specified rules, especially requirements like "number of {{nodeName}}", "must include xxx {{nodeName}}", "cannot include xxx {{nodeName}}"
-2. Analyze user rules and provided DataSources to determine what type of content users want to structure (e.g., websites, documentation, books, etc.) and design appropriate structures for different content types
-3. {{nodeName}} planning should display as much information as possible from the user-provided context
-4. Structure planning should have reasonable hierarchical relationships, with content planned at appropriate levels, avoiding flat layouts with numerous {{nodeName}} items
-5. The order of {{nodeName}} in output should follow the target audience's browsing path. It doesn't need to follow the exact order in DataSources—progress from simple to advanced, from understanding to exploration, with reasonable pathways
-6. Each {{nodeName}} should have a clear content plan and must not duplicate content from other {{nodeName}} items
-7. Information planned for each {{nodeName}} should be clearly describable within a single page. If there's too much information to display or the concepts are too broad, consider splitting into sub-{{nodeName}} items
-8. If previous documentation structure and user feedback are provided, make only necessary modifications based on user feedback without major changes
-9. If previous documentation structure is provided but no feedback is given, **directly return the previous documentation structure**
-10. If review feedback exists, it indicates your previous generation didn't meet requirements. Optimize your output based on the review feedback
+2. {{nodeName}} planning should display as much information as possible from the user-provided context
+3. Structure planning should have reasonable hierarchical relationships, with content planned at appropriate levels, avoiding flat layouts with numerous {{nodeName}} items
+4. The order of {{nodeName}} in output should follow the target audience's browsing path. It doesn't need to follow the exact order in DataSources—progress from simple to advanced, from understanding to exploration, with reasonable pathways
+5. Each {{nodeName}} should have a clear content plan and must not duplicate content from other {{nodeName}} items
+6. Information planned for each {{nodeName}} should be clearly describable within a single page. If there's too much information to display or the concepts are too broad, consider splitting into sub-{{nodeName}} items
+7. If previous documentation structure and user feedback are provided, make only necessary modifications based on user feedback without major changes
+8. If previous documentation structure is provided but no feedback is given, **directly return the previous documentation structure**
+9. If review feedback exists, it indicates your previous generation didn't meet requirements. Optimize your output based on the review feedback
 
 {{nodeName}} planning rules:
 

package/prompts/common/document-structure/output-constraints.md

@@ -4,6 +4,6 @@
   - If datasources contain source code, **include as much related and adjacent source code as possible** to ensure quality of subsequent detail generation.
   - First identify the most relevant source code files, then analyze the source code referenced within them. Referenced file paths, referenced files, and files in referenced paths all need to be included in sourceIds
   - For referenced files, analyze another layer of source code files referenced within them and add to sourceIds to ensure complete context for detail generation
-2. Ensure sourceIds are never empty. Do not plan {{nodeName}} items without related data sources
+2. **Ensure sourceIds are never empty**. Do not plan {{nodeName}} items without related data sources
 
 </output_constraints>

package/prompts/structure/document-rules.md

@@ -4,12 +4,18 @@ Documentation structure rules:
 - Plan the structure based on the provided source code, ensuring each planned node has enough information to be displayed.
 - Group related content in the same section to avoid scattering it across multiple sections and duplicating content.
 - Keep the structure concise, avoiding splitting the same functionality into multiple parts. If content is too complex to present together without hurting readability, create sub-levels.
-- **First level: ≤ 7 items; hierarchy: ≤ 3 levels.** Use consistent semantics within each level (verb tense and noun number).
 - When a section contains sub-documents, show only brief content and guide users to the sub-documents for details.
 - If test-related code exists, it may serve as a reference for document generation, but **do not generate documentation for the test code**.
+{% if not isSubStructure %}
+- **hierarchy: ≤ 3 levels.** Use consistent semantics within each level (verb tense and noun number).
 - Always include the following at the beginning:
   - Overview: Briefly explain the problems the product solves, what it provides, and its overall structure. Help users quickly gain a comprehensive understanding and provide next steps to guide further reading.
 
-- Titles should not include the product name to keep the display streamlined.
 - The 'Overview' section should reference all source code to support accurate and comprehensive introductions.
+{%else%}
+- **hierarchy: ≤ 2 levels.** Use consistent semantics within each level (verb tense and noun number).
+- The current process is generate sub-structures for a large module, showing detailed content planned in the parent document, no need to include 'Overview' section
+{% endif %}
+
+- Titles should not include the product name to keep the display streamlined.
 - Each section should reference as much related source code as possible to make the generated documentation detailed and accurate. When unsure, prioritize adding references.

package/prompts/structure/generate/system-prompt.md

@@ -33,9 +33,34 @@ Always follow one principle: You must ensure the final structural plan meets use
 {% include "../../common/document-structure/conflict-resolution-guidance.md" %}
 
 
-{% ifAsync docsType == 'general' %}
-  {% include "../structure-example.md" %}
+<sub_structure>
+{% if isLargeContext %}
+Analyze the provided file list and DataSources to complete the document structure planning:
+  - If the DataSources contain sufficient context and already include content from all files in the file list, you can directly generate a detailed document structure.
+  - First plan the document structure based on DataSources and <file_list>, ensuring all user-provided information will be presented in the document
+  - Ensure initial planning has sufficient content separation to avoid oversized data sources when generating sub-documents
+  - For sections with extensive content, use the `generateSubStructure` tool to generate detailed sub-structures
+  - Trigger all Tool calls at once whenever possible
+  - When triggering Tool calls, only output Tool call related information
+  - Carefully check the data returned by the `generateSubStructure` tool, integrate all data, merge the complete document structure, and finally verify that it meets the requirements in <output_constraints>
+
+Using `generateSubStructure`:
+- When the provided file list is large and DataSources don't contain all file contents, resulting in an oversized context, split the generation into sub-document structures to make the context more focused and complete
+- Generate sub-documents to more effectively and fully utilize the data source files provided in <file_list>
+- Requires `parentDocument` and `subSourcePaths` as context parameters
+- `subSourcePaths` supports individual files and Glob Patterns, generation process:
+  - Analyze relevant files from the file list, include as many related files as possible to ensure complete context
+  - Selected files must come from <file_list>, ensure file paths are correct
+  - Consolidation Rules:
+    1. If all files from a single directory (e.g., src/) have been selected, consolidate them into a pattern like src/\*.
+    2. If multiple files with a common naming convention are selected (e.g., README.md, README-dockerfile.md, README-turbo.md), consolidate them into a pattern like README\*.md.
+    3. Ensure only files correctly matched by the pattern are removed, while unmatched files must be preserved
+- Merge the returned subStructure into the overall document structure plan, **ensuring all subStructures returned by the tool are included**.
+
+{% else %}
+The current context is sufficient, proceed directly with document structure planning based on DataSources.
 {% endif %}
+</sub_structure>
 
 
 {% include "../../common/document-structure/output-constraints.md" %}

package/prompts/structure/generate/user-prompt.md

@@ -4,6 +4,10 @@
 {% include "../../common/document-structure/user-preferences.md" %}
 
 
+<file_list>
+{{allFilesPaths}}
+</file_list>
+
 <datasources>
 {{ datasources }}
 </datasources>
@@ -43,3 +47,17 @@ If a previous structural plan (last_document_structure) is provided, follow thes
 {{ structureReviewFeedback }}
 </document_structure_review_feedback>
 {% endif %}
+
+{% if isSubStructure %}
+<parent_document>
+The current process is planning sub-structures for the following section:
+
+{{parentDocument}}
+
+Sub-structures must meet the following requirements:
+- Sub-structures are planned based on DataSources and the parent document's description
+- The parent document provides an overview of the planned content, while sub-structures directly plan the specific content to be displayed
+- Further break down and comprehensively display the content planned in the parent document
+- All sub-structures must have their parentId value set to {{parentDocument.path}}
+</parent_document>
+{% endif %}

package/prompts/structure/update/system-prompt.md

@@ -107,5 +107,17 @@ Analyze the user feedback to determine the intended operation:
 </operation_output_constraints>
 </operation_execution_rules>
 
+<file_tool_usage>
+1. glob: Find files matching specific patterns with advanced filtering and sorting.
+
+2. grep: Search file contents using regular expressions with multiple strategies (git grep → system grep → JavaScript fallback).
+
+3. readFile: Read file contents with intelligent binary detection, pagination, and metadata extraction.
+
+When to use Tools:
+- During document structure update, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
+- When sourceIds or file content from <file_list> is needed but not provided in DataSources, use readFile to read the file content
+</file_tool_usage>
+
 
 {% include "../../common/document-structure/output-constraints.md" %}

package/prompts/structure/update/user-prompt.md

@@ -2,6 +2,9 @@
 
 {% include "../../common/document-structure/user-preferences.md" %}
 
+<file_list>
+{{allFilesPaths}}
+</file_list>
 
 <datasources>
 {{ datasources }}

package/tests/agents/clear/choose-contents.test.mjs

@@ -85,7 +85,7 @@ describe("choose-contents", () => {
   test("should prompt user when no targets provided", async () => {
     mockOptions.prompts.checkbox.mockResolvedValue(["generatedDocs"]);
 
-    await chooseContents({}, mockOptions);
+    await chooseContents({ docsDir: "/test/docs", workDir: "/test" }, mockOptions);
 
     expect(mockOptions.prompts.checkbox).toHaveBeenCalledWith({
       message: "Select items to clear:",
@@ -103,7 +103,7 @@ describe("choose-contents", () => {
   test("should handle empty selection from prompts", async () => {
     mockOptions.prompts.checkbox.mockResolvedValue([]);
 
-    const result = await chooseContents({}, mockOptions);
+    const result = await chooseContents({ docsDir: "/test/docs", workDir: "/test" }, mockOptions);
 
     expect(result.message).toBe("No items selected to clear.");
     expect(mockContext.invoke).not.toHaveBeenCalled();
@@ -112,16 +112,20 @@ describe("choose-contents", () => {
   test("should return available options when no prompts available", async () => {
     const optionsWithoutPrompts = { context: mockContext };
 
-    const result = await chooseContents({}, optionsWithoutPrompts);
+    const result = await chooseContents(
+      { docsDir: "/test/docs", workDir: "/test" },
+      optionsWithoutPrompts,
+    );
 
     expect(result.message).toBe(
-      "Available options to clear: generatedDocs, documentStructure, documentConfig, authTokens",
+      "Available options to clear: generatedDocs, documentStructure, documentConfig, authTokens, deploymentConfig",
     );
     expect(result.availableTargets).toEqual([
       "generatedDocs",
       "documentStructure",
       "documentConfig",
       "authTokens",
+      "deploymentConfig",
     ]);
   });