feat(markdown): add docxToMarkdown File/InputStream/byte[]/path shortcuts

Agent/RAG consumers can now extract markdown from a docx in one call
without manually loading a WordprocessingMLPackage first. All overloads
delegate to the existing pkg-based implementation; null inputs return ''.
EasyMarkdownTest: +3 cases (file / stream+bytes+path / null inputs).
Verified (JDK 17): xhtml markdown 6/6 green.

Author: loong10k

easydoc-xhtml/src/main/java/io/github/easy4j/doc/xhtml/markdown/EasyMarkdown.java

@@ -1,6 +1,9 @@
 package io.github.easy4j.doc.xhtml.markdown;
 
+import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.InputStream;
 import java.util.Map;
 
 import org.docx4j.Docx4J;
@@ -32,6 +35,40 @@ public static WordprocessingMLPackage markdownToDocx(String markdown,
 		return template.process(html, vars);
 	}
 
+	/** docx 文件 → Markdown。null 输入返回空串。 */
+	public static String docxToMarkdown(File file) throws Exception {
+		if (file == null) {
+			return "";
+		}
+		return docxToMarkdown(WordprocessingMLPackage.load(file));
+	}
+
+	/** docx 输入流 → Markdown（流由本方法负责关闭）。null 输入返回空串。 */
+	public static String docxToMarkdown(InputStream in) throws Exception {
+		if (in == null) {
+			return "";
+		}
+		try (InputStream closeable = in) {
+			return docxToMarkdown(WordprocessingMLPackage.load(closeable));
+		}
+	}
+
+	/** docx 字节数组 → Markdown。null 输入返回空串。 */
+	public static String docxToMarkdown(byte[] bytes) throws Exception {
+		if (bytes == null) {
+			return "";
+		}
+		return docxToMarkdown(WordprocessingMLPackage.load(new ByteArrayInputStream(bytes)));
+	}
+
+	/** docx 文件路径 → Markdown。null/空白路径返回空串。 */
+	public static String docxToMarkdown(String path) throws Exception {
+		if (path == null || path.trim().isEmpty()) {
+			return "";
+		}
+		return docxToMarkdown(new File(path));
+	}
+
 	/** docx → Markdown（经 docx4j HTML 导出 + 简化 HTML→MD 映射）。null 输入返回空串。 */
 	public static String docxToMarkdown(WordprocessingMLPackage pkg) throws Exception {
 		if (pkg == null) {

easydoc-xhtml/src/test/java/io/github/easy4j/doc/xhtml/markdown/EasyMarkdownTest.java

@@ -3,8 +3,15 @@
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
 import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
 
 class EasyMarkdownTest {
 
@@ -31,4 +38,39 @@ void docxToMarkdownConvertsHeadingAndBold() throws Exception {
 		assertTrue(md.contains("标题"), "heading text must appear in markdown output");
 		assertTrue(md.contains("加粗"), "text must appear in markdown output");
 	}
+
+	@Test
+	void docxToMarkdownFromFile(@TempDir Path tempDir) throws Exception {
+		WordprocessingMLPackage pkg = EasyMarkdown.markdownToDocx("# 标题\n\n**加粗** 内容");
+		File file = tempDir.resolve("doc.docx").toFile();
+		pkg.save(file);
+		String md = EasyMarkdown.docxToMarkdown(file);
+		assertTrue(md.contains("标题"), "heading text must appear in markdown output");
+		assertTrue(md.contains("加粗"), "text must appear in markdown output");
+	}
+
+	@Test
+	void docxToMarkdownFromInputStreamBytesAndPath(@TempDir Path tempDir) throws Exception {
+		WordprocessingMLPackage pkg = EasyMarkdown.markdownToDocx("# 标题");
+		File file = tempDir.resolve("doc2.docx").toFile();
+		pkg.save(file);
+		try (InputStream in = new FileInputStream(file)) {
+			assertTrue(EasyMarkdown.docxToMarkdown(in).contains("标题"),
+					"input stream input must produce markdown");
+		}
+		byte[] bytes = Files.readAllBytes(file.toPath());
+		assertTrue(EasyMarkdown.docxToMarkdown(bytes).contains("标题"),
+				"byte[] input must produce markdown");
+		assertTrue(EasyMarkdown.docxToMarkdown(file.getAbsolutePath()).contains("标题"),
+				"path input must produce markdown");
+	}
+
+	@Test
+	void docxToMarkdownNullInputsReturnEmpty() throws Exception {
+		assertTrue(EasyMarkdown.docxToMarkdown((File) null).isEmpty());
+		assertTrue(EasyMarkdown.docxToMarkdown((InputStream) null).isEmpty());
+		assertTrue(EasyMarkdown.docxToMarkdown((byte[]) null).isEmpty());
+		assertTrue(EasyMarkdown.docxToMarkdown((String) null).isEmpty());
+		assertTrue(EasyMarkdown.docxToMarkdown("   ").isEmpty());
+	}
 }