feat: implement cross-platform image extraction logic and project configuration management

Author: bruc3van

bin/converter.py

@@ -850,7 +850,7 @@ def _is_decorative_image(data, width=None, height=None, is_decorative_flag=False
 
 def _setup_image_output_dir(markdown_output_path):
     """
-    在 Markdown 输出文件旁创建 images/ 子目录。
+    在 Markdown 输出文件旁创建配置的图片子目录。
 
     Args:
         markdown_output_path: Markdown 输出文件的绝对路径
@@ -866,17 +866,17 @@ def _setup_image_output_dir(markdown_output_path):
 
 def _save_extracted_image(data, image_save_dir, image_rel_dir, base_name, image_counter):
     """
-    保存图片到 images/ 目录。
+    保存图片到配置的图片目录。
 
     Args:
         data: 图片二进制数据
-        image_save_dir: images/ 目录绝对路径
-        image_rel_dir: images/ 相对路径（用于 Markdown 引用）
+        image_save_dir: 图片目录绝对路径
+        image_rel_dir: 图片目录相对路径（用于 Markdown 引用）
         base_name: 文档基础名称（不含扩展名）
         image_counter: 图片序号
 
     Returns:
-        相对路径字符串，如 'images/report_img_001.png'，失败返回 None
+        相对路径字符串，如 'assets/report_img_001.png'，失败返回 None
     """
     fmt = _detect_image_format(data)
     if fmt is None:
@@ -2546,29 +2546,30 @@ def main():
             pass
 
     if len(sys.argv) < 2:
-        print("Usage: converter.py <file_path> [extract_images] [output_path]")
+        print("Usage: converter.py <file_path> [extract_images] [output_path] [image_output_folder]")
         sys.exit(1)
 
     file_path = sys.argv[1]
     extract_images = True
     if len(sys.argv) > 2 and sys.argv[2].lower() in ('false', 'no', '0'):
         extract_images = False
     output_path = sys.argv[3] if len(sys.argv) > 3 else None
+    image_output_folder = sys.argv[4] if len(sys.argv) > 4 else 'images'
 
     # 确定图片输出目录
     image_save_dir = None
     image_rel_dir = None
     file_ext = os.path.splitext(file_path)[1].lower()
     if extract_images and file_ext in ('.docx', '.xlsx', '.pptx'):
         if output_path:
-            # 图片放在 output_path 同级的 images/ 目录
+            # 图片放在 output_path 同级的配置目录下
             out_dir = os.path.dirname(os.path.abspath(output_path))
-            image_save_dir = os.path.join(out_dir, 'images')
-            image_rel_dir = 'images'
+            image_save_dir = os.path.join(out_dir, image_output_folder)
+            image_rel_dir = image_output_folder
         else:
-            # fallback：放在输入文件目录的 images/ 下
-            image_save_dir = os.path.join(os.path.dirname(os.path.abspath(file_path)), 'images')
-            image_rel_dir = 'images'
+            # fallback：放在输入文件目录的配置目录下
+            image_save_dir = os.path.join(os.path.dirname(os.path.abspath(file_path)), image_output_folder)
+            image_rel_dir = image_output_folder
 
     # 调用对应转换函数
     try:

bin/darwin/image_extractor.py

@@ -19,7 +19,7 @@ def __init__(self, document_path: str, output_dir: str = None, markdown_dir: str
         self.document_name = self.document_path.stem
         self.document_ext = self.document_path.suffix.lower()
 
-        # Set output directory - use DocuGenius/images/{document_name}/ structure
+        # Set output directory under the configured DocuGenius image folder
         if output_dir:
             self.output_dir = Path(output_dir) / self.document_name
         else:
@@ -134,7 +134,7 @@ def _extract_from_docx(self) -> Dict:
                     image_info = {
                         'filename': img_filename,
                         'path': str(img_path),
-                        'relative_path': f"images/{self.document_name}/{img_filename}",
+                        'relative_path': self._calculate_relative_path(img_path),
                         'format': img_ext.upper(),
                         'size_bytes': len(image_data),
                         'source': 'docx_relationship'
@@ -208,7 +208,7 @@ def _extract_from_pptx(self) -> Dict:
                         image_info = {
                             'filename': img_filename,
                             'path': str(img_path),
-                            'relative_path': f"images/{self.document_name}/{img_filename}",
+                            'relative_path': self._calculate_relative_path(img_path),
                             'slide': slide_num + 1,
                             'format': img_ext.upper(),
                             'size_bytes': len(image_data),
@@ -340,7 +340,7 @@ def _calculate_relative_path(self, image_path: Path) -> str:
             return relative_path
         except Exception as e:
             # Fallback to simple relative path
-            return f"images/{self.document_name}/{image_path.name}"
+            return f"{self.output_dir.name}/{self.document_name}/{image_path.name}"
 
     def _calculate_file_hash(self, file_path: Path) -> str:
         """Calculate MD5 hash of a file for duplicate detection"""

bin/win32/image_extractor.py

@@ -29,7 +29,7 @@ def __init__(self, document_path: str, output_dir: str = None, markdown_dir: str
         self.document_name = self.document_path.stem
         self.document_ext = self.document_path.suffix.lower()
 
-        # Set output directory - use DocuGenius/images/{document_name}/ structure
+        # Set output directory under the configured DocuGenius image folder
         if output_dir:
             self.output_dir = Path(output_dir) / self.document_name
         else:
@@ -351,7 +351,7 @@ def _calculate_relative_path(self, image_path: Path) -> str:
             return relative_path
         except Exception as e:
             # Fallback to simple relative path
-            return f"images/{self.document_name}/{image_path.name}"
+            return f"{self.output_dir.name}/{self.document_name}/{image_path.name}"
 
     def _calculate_file_hash(self, file_path: Path) -> str:
         """Calculate MD5 hash of a file for duplicate detection"""

package.nls.json

@@ -7,16 +7,16 @@
   "config.overwriteExisting.description": "Overwrite existing .md files if source file is newer",
   "config.extractImages.description": "[BETA] Extract images from Word, Excel, and PowerPoint documents to a separate assets folder (PDF image extraction is not supported)",
 
-  "config.imageOutputFolder.description": "Folder name for extracted images (relative to document location or markdown subdirectory) (only effective when image extraction is enabled)",
-  "config.imageMinSize.description": "Minimum image size threshold used when extracting document images",
+  "config.imageOutputFolder.description": "Folder name for extracted images, used for saved assets and Markdown links (relative to the document location or markdown subdirectory; only effective when image extraction is enabled)",
+  "config.imageMinSize.description": "Minimum extracted image size in pixels used to skip tiny decorative images",
   "config.enableDocumentSplitting.description": "Automatically split large documents into multiple Markdown files for better performance and readability",
   "config.documentSplittingThreshold.description": "Character count threshold for document splitting (documents exceeding this limit will be split into multiple files)",
 
   "config.organizeInSubdirectory.description": "Organize converted Markdown files in a subdirectory to separate them from source files",
   "config.markdownSubdirectoryName.description": "Name of the subdirectory where converted Markdown files will be stored",
   "config.showSuccessNotifications.description": "Show popup notifications when files are successfully converted",
-  "config.createProjectConfig.description": "Create .docugenius.json project configuration file by default (if disabled, uses global settings only)",
-  "config.copyTextFiles.description": "Copy plain text files (.txt, .md, .csv, etc.) to the knowledge base folder for unified indexing",
+  "config.createProjectConfig.description": "When you explicitly enable DocuGenius for a workspace, persist project state in .docugenius.json (if disabled, project state stays in VS Code workspace storage and global settings are used)",
+  "config.copyTextFiles.description": "Copy plain text files (.txt, .md, .csv, etc.) into the DocuGenius output location without modifying the originals",
   "config.batchConversionBehavior.description": "How to handle multiple files detected at once",
   "config.batchConversionBehavior.askForEach": "Ask for confirmation for each file individually",
   "config.batchConversionBehavior.askOnce": "Ask once for all files in the batch",
@@ -101,7 +101,7 @@
   "converter.error.lastError": "Last error: {0}",
   "converter.log.copySuccess": "Copied: {0} -> {1}",
   "converter.log.deletedOutput": "Deleted: {0} (source file {1} was deleted)",
-  "converter.log.deletedImages": "Deleted images: images/{0}/",
+  "converter.log.deletedImages": "Deleted images: {0}",
   "converter.log.deletedLegacyAssets": "Deleted legacy assets: {0}_assets/",
   "converter.log.cleanupFailed": "Failed to clean up deleted file {0}: {1}",
   "converter.status.cleanup": "Cleaned up {0}",

package.nls.zh-cn.json

@@ -7,16 +7,16 @@
   "config.overwriteExisting.description": "如果源文件较新，则覆盖现有的 .md 文件",
   "config.extractImages.description": "[BETA] 将 Word、Excel、PowerPoint 文档中的图片提取到单独的资源文件夹（暂不支持 PDF 图片提取）",
 
-  "config.imageOutputFolder.description": "提取图片的文件夹名称（相对于文档位置或 markdown 子目录）（仅在启用图片提取时生效）",
-  "config.imageMinSize.description": "提取文档图片时使用的最小图片尺寸阈值",
+  "config.imageOutputFolder.description": "提取图片的文件夹名称，用于保存资源文件和生成 Markdown 图片链接（相对于文档位置或 markdown 子目录；仅在启用图片提取时生效）",
+  "config.imageMinSize.description": "提取图片时使用的最小图片尺寸（像素），用于跳过过小的装饰性图片",
   "config.enableDocumentSplitting.description": "自动将大型文档切分为多个 Markdown 文件，以提高性能和可读性",
   "config.documentSplittingThreshold.description": "文档切分的字符数阈值（超过此限制的文档将被切分为多个文件）",
 
   "config.organizeInSubdirectory.description": "将转换的文件组织在子目录中，以便与源文件分离",
   "config.markdownSubdirectoryName.description": "存储转换的文件的子目录名称",
   "config.showSuccessNotifications.description": "文件成功转换时显示弹出通知",
-  "config.createProjectConfig.description": "默认创建 .docugenius.json 项目配置文件（如果禁用，则仅使用全局设置）",
-  "config.copyTextFiles.description": "将纯文本文件（.txt、.md、.csv 等）复制到知识库文件夹以进行统一索引",
+  "config.createProjectConfig.description": "当你显式为工作区启用 DocuGenius 时，将项目状态写入 .docugenius.json（如果禁用，则项目状态保存在 VS Code 工作区存储中，并使用全局设置）",
+  "config.copyTextFiles.description": "将纯文本文件（.txt、.md、.csv 等）复制到 DocuGenius 输出目录中，不会修改原文件",
   "config.batchConversionBehavior.description": "如何处理同时检测到的多个文件",
   "config.batchConversionBehavior.askForEach": "为每个文件单独请求确认",
   "config.batchConversionBehavior.askOnce": "为批次中的所有文件请求一次确认",
@@ -101,7 +101,7 @@
   "converter.error.lastError": "最后错误: {0}",
   "converter.log.copySuccess": "已复制: {0} -> {1}",
   "converter.log.deletedOutput": "已删除: {0}（源文件 {1} 已被删除）",
-  "converter.log.deletedImages": "已删除图片目录: images/{0}/",
+  "converter.log.deletedImages": "已删除图片目录: {0}",
   "converter.log.deletedLegacyAssets": "已删除旧版资源目录: {0}_assets/",
   "converter.log.cleanupFailed": "清理已删除文件 {0} 失败: {1}",
   "converter.status.cleanup": "已清理 {0}",

package.nls.zh.json

@@ -7,16 +7,16 @@
   "config.overwriteExisting.description": "如果源文件较新，则覆盖现有的 .md 文件",
   "config.extractImages.description": "[BETA] 将 Word、Excel、PowerPoint 文档中的图片提取到单独的资源文件夹（暂不支持 PDF 图片提取）",
 
-  "config.imageOutputFolder.description": "提取图片的文件夹名称（相对于文档位置或 markdown 子目录）（仅在启用图片提取时生效）",
-  "config.imageMinSize.description": "提取文档图片时使用的最小图片尺寸阈值",
+  "config.imageOutputFolder.description": "提取图片的文件夹名称，用于保存资源文件和生成 Markdown 图片链接（相对于文档位置或 markdown 子目录；仅在启用图片提取时生效）",
+  "config.imageMinSize.description": "提取图片时使用的最小图片尺寸（像素），用于跳过过小的装饰性图片",
   "config.enableDocumentSplitting.description": "自动将大型文档切分为多个 Markdown 文件，以提高性能和可读性",
   "config.documentSplittingThreshold.description": "文档切分的字符数阈值（超过此限制的文档将被切分为多个文件）",
 
   "config.organizeInSubdirectory.description": "将转换的文件组织在子目录中，以便与源文件分离",
   "config.markdownSubdirectoryName.description": "存储转换的文件的子目录名称",
   "config.showSuccessNotifications.description": "文件成功转换时显示弹出通知",
-  "config.createProjectConfig.description": "默认创建 .docugenius.json 项目配置文件（如果禁用，则仅使用全局设置）",
-  "config.copyTextFiles.description": "将纯文本文件（.txt、.md、.csv 等）复制到知识库文件夹以进行统一索引",
+  "config.createProjectConfig.description": "当你显式为工作区启用 DocuGenius 时，将项目状态写入 .docugenius.json（如果禁用，则项目状态保存在 VS Code 工作区存储中，并使用全局设置）",
+  "config.copyTextFiles.description": "将纯文本文件（.txt、.md、.csv 等）复制到 DocuGenius 输出目录中，不会修改原文件",
   "config.batchConversionBehavior.description": "如何处理同时检测到的多个文件",
   "config.batchConversionBehavior.askForEach": "为每个文件单独请求确认",
   "config.batchConversionBehavior.askOnce": "为批次中的所有文件请求一次确认",
@@ -101,7 +101,7 @@
   "converter.error.lastError": "最后错误: {0}",
   "converter.log.copySuccess": "已复制: {0} -> {1}",
   "converter.log.deletedOutput": "已删除: {0}（源文件 {1} 已被删除）",
-  "converter.log.deletedImages": "已删除图片目录: images/{0}/",
+  "converter.log.deletedImages": "已删除图片目录: {0}",
   "converter.log.deletedLegacyAssets": "已删除旧版资源目录: {0}_assets/",
   "converter.log.cleanupFailed": "清理已删除文件 {0} 失败: {1}",
   "converter.status.cleanup": "已清理 {0}",