bruce-doc-converter 0.1.0__tar.gz

bruce_doc_converter-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+prune bruce_doc_converter/md_to_docx/node_modules
+prune bruce_doc_converter/md_to_docx/.cache
+
+global-exclude __pycache__ *.py[cod] .DS_Store

bruce_doc_converter-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: bruce-doc-converter
+Version: 0.1.0
+Summary: Agent-facing document converter CLI for Office/PDF/Markdown workflows
+Author: Bruce
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: python-docx
+Requires-Dist: openpyxl
+Requires-Dist: python-pptx
+Requires-Dist: pdfplumber
+
+# Bruce Doc Converter
+
+> 为 Claude Code / OpenClaw 添加双向文档转换能力
+
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-Skill-purple.svg)](https://github.com/anthropics/claude-code)
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Bruce Doc Converter** 是一个面向 Agent 的文档转换 CLI，为 **Claude Code / OpenClaw** 添加**双向文档转换**能力：
+
+- **Office/PDF → Markdown**：将 Word、Excel、PowerPoint、PDF 转换为 AI 友好的 Markdown 格式
+- **Markdown → Word**：将 Markdown 导出为排版精美的 Word 文档，自动渲染 Mermaid 图表
+
+## 安装
+
+```bash
+pipx install bruce-doc-converter
+```
+
+如果 `pipx` 不可用：
+
+```bash
+python3 -m pip install bruce-doc-converter
+# macOS Homebrew Python 需要加 --break-system-packages 或使用 venv：
+# python3 -m venv .venv && .venv/bin/pip install bruce-doc-converter
+```
+
+## Agent CLI 用法
+
+```bash
+bdc convert /path/to/document.docx
+bdc convert /path/to/notes.md
+bdc batch /path/to/documents
+```
+
+CLI 默认向 stdout 输出 JSON，stderr 仅用于进度和依赖安装日志。
+
+查看帮助：
+
+```bash
+bdc --help-json
+```
+
+### 输出示例（单文件成功）
+
+```json
+{
+  "schema_version": "1.0",
+  "success": true,
+  "input_path": "/absolute/input.docx",
+  "input_format": "docx",
+  "output_format": "markdown",
+  "output_path": "/absolute/Markdown/input.md",
+  "markdown_content": "# 内容...",
+  "extracted_images": [],
+  "warnings": []
+}
+```
+
+### 输出示例（失败）
+
+```json
+{
+  "schema_version": "1.0",
+  "success": false,
+  "input_path": "/absolute/input.doc",
+  "input_format": "doc",
+  "error_code": "UNSUPPORTED_FORMAT",
+  "error": "不支持的文件格式: .doc。支持的格式: .docx, .xlsx, .pptx, .pdf, .md",
+  "suggestion": "请先转换为 .docx/.xlsx/.pptx 后再重试。"
+}
+```
+
+### 输出示例（批量转换）
+
+批量转换的 `success` 表示是否所有文件都转换成功；部分失败时 `success` 为 `false`，但 `succeeded`、`failed` 和 `results` 会保留每个文件的明细。
+
+```json
+{
+  "schema_version": "1.0",
+  "success": true,
+  "total": 1,
+  "succeeded": 1,
+  "failed": 0,
+  "results": [
+    {
+      "input_path": "/absolute/input.docx",
+      "result": {
+        "schema_version": "1.0",
+        "success": true,
+        "input_path": "/absolute/input.docx",
+        "input_format": "docx",
+        "output_format": "markdown",
+        "output_path": "/absolute/Markdown/input.md",
+        "markdown_content": "# 内容...",
+        "extracted_images": [],
+        "warnings": []
+      }
+    }
+  ]
+}
+```
+
+## 功能特性
+
+- **标题识别**：自动识别 Word 标题层级（Heading 1-6）及中文标题样式
+- **格式保留**：保留粗体、斜体等文本格式
+- **表格转换**：智能转换表格为 Markdown 格式
+- **列表支持**：有序列表、无序列表及多级嵌套
+- **Mermaid 图表**：支持通过 `mmdc` 渲染 Mermaid 代码块，嵌入 Word 为 PNG 图片
+- **图片提取**：Office/PDF 转 Markdown 时可提取内嵌图片
+
+## 支持的格式
+
+| 格式               | 输入 | 输出 | 质量       |
+| ------------------ | ---- | ---- | ---------- |
+| Word (.docx)       | ✅   | ✅   | 优秀       |
+| Excel (.xlsx)      | ✅   | ❌   | 优秀       |
+| PowerPoint (.pptx) | ✅   | ❌   | 良好       |
+| PDF (.pdf)         | ✅   | ❌   | 取决于类型 |
+| Markdown (.md)     | ✅   | ✅   | 优秀       |
+
+> **注意**：不支持旧版格式（.doc, .xls, .ppt），请先转换为新格式。
+
+## 环境要求
+
+- **Python 3.8+**（必需）
+- **Node.js 14+**（可选，仅 Markdown → Word 需要）
+
+## 常见问题
+
+### 文件过大怎么办？
+
+当前限制为 100MB，建议分割文件或压缩内容。
+
+### Markdown 转 Word 失败？
+
+需要安装 Node.js。如果 Node.js 已安装但仍报错，检查依赖：
+
+```bash
+npm --prefix bruce_doc_converter/md_to_docx install
+```
+
+### PDF 提取不到内容？
+
+扫描型 PDF 需先执行 OCR，或解除 PDF 保护后重试。
+
+## 最佳实践
+
+1. **使用新版 Office 格式**（.docx, .xlsx, .pptx）
+2. **PDF 优先使用文本型**，扫描型建议先 OCR
+3. **文件大小建议 < 50MB**
+
+## 项目结构
+
+```
+bruce-doc-converter/
+├── SKILL.md                      # Agent Skill 定义
+├── pyproject.toml                # Python 包元数据
+├── requirements.txt              # 本地开发依赖
+├── bruce_doc_converter/
+│   ├── __init__.py
+│   ├── cli.py                    # bdc CLI 入口
+│   ├── converter.py              # 转换核心逻辑
+│   └── md_to_docx/              # Markdown → Word 的 Node.js 模块
+├── references/
+│   └── supported-formats.md
+└── tests/
+    ├── test_cli.py
+    ├── test_convert_document.py
+    └── md_to_docx.test.js
+```
+
+## 许可证
+
+MIT License

bruce_doc_converter-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Bruce Doc Converter
+
+> 为 Claude Code / OpenClaw 添加双向文档转换能力
+
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-Skill-purple.svg)](https://github.com/anthropics/claude-code)
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Bruce Doc Converter** 是一个面向 Agent 的文档转换 CLI，为 **Claude Code / OpenClaw** 添加**双向文档转换**能力：
+
+- **Office/PDF → Markdown**：将 Word、Excel、PowerPoint、PDF 转换为 AI 友好的 Markdown 格式
+- **Markdown → Word**：将 Markdown 导出为排版精美的 Word 文档，自动渲染 Mermaid 图表
+
+## 安装
+
+```bash
+pipx install bruce-doc-converter
+```
+
+如果 `pipx` 不可用：
+
+```bash
+python3 -m pip install bruce-doc-converter
+# macOS Homebrew Python 需要加 --break-system-packages 或使用 venv：
+# python3 -m venv .venv && .venv/bin/pip install bruce-doc-converter
+```
+
+## Agent CLI 用法
+
+```bash
+bdc convert /path/to/document.docx
+bdc convert /path/to/notes.md
+bdc batch /path/to/documents
+```
+
+CLI 默认向 stdout 输出 JSON，stderr 仅用于进度和依赖安装日志。
+
+查看帮助：
+
+```bash
+bdc --help-json
+```
+
+### 输出示例（单文件成功）
+
+```json
+{
+  "schema_version": "1.0",
+  "success": true,
+  "input_path": "/absolute/input.docx",
+  "input_format": "docx",
+  "output_format": "markdown",
+  "output_path": "/absolute/Markdown/input.md",
+  "markdown_content": "# 内容...",
+  "extracted_images": [],
+  "warnings": []
+}
+```
+
+### 输出示例（失败）
+
+```json
+{
+  "schema_version": "1.0",
+  "success": false,
+  "input_path": "/absolute/input.doc",
+  "input_format": "doc",
+  "error_code": "UNSUPPORTED_FORMAT",
+  "error": "不支持的文件格式: .doc。支持的格式: .docx, .xlsx, .pptx, .pdf, .md",
+  "suggestion": "请先转换为 .docx/.xlsx/.pptx 后再重试。"
+}
+```
+
+### 输出示例（批量转换）
+
+批量转换的 `success` 表示是否所有文件都转换成功；部分失败时 `success` 为 `false`，但 `succeeded`、`failed` 和 `results` 会保留每个文件的明细。
+
+```json
+{
+  "schema_version": "1.0",
+  "success": true,
+  "total": 1,
+  "succeeded": 1,
+  "failed": 0,
+  "results": [
+    {
+      "input_path": "/absolute/input.docx",
+      "result": {
+        "schema_version": "1.0",
+        "success": true,
+        "input_path": "/absolute/input.docx",
+        "input_format": "docx",
+        "output_format": "markdown",
+        "output_path": "/absolute/Markdown/input.md",
+        "markdown_content": "# 内容...",
+        "extracted_images": [],
+        "warnings": []
+      }
+    }
+  ]
+}
+```
+
+## 功能特性
+
+- **标题识别**：自动识别 Word 标题层级（Heading 1-6）及中文标题样式
+- **格式保留**：保留粗体、斜体等文本格式
+- **表格转换**：智能转换表格为 Markdown 格式
+- **列表支持**：有序列表、无序列表及多级嵌套
+- **Mermaid 图表**：支持通过 `mmdc` 渲染 Mermaid 代码块，嵌入 Word 为 PNG 图片
+- **图片提取**：Office/PDF 转 Markdown 时可提取内嵌图片
+
+## 支持的格式
+
+| 格式               | 输入 | 输出 | 质量       |
+| ------------------ | ---- | ---- | ---------- |
+| Word (.docx)       | ✅   | ✅   | 优秀       |
+| Excel (.xlsx)      | ✅   | ❌   | 优秀       |
+| PowerPoint (.pptx) | ✅   | ❌   | 良好       |
+| PDF (.pdf)         | ✅   | ❌   | 取决于类型 |
+| Markdown (.md)     | ✅   | ✅   | 优秀       |
+
+> **注意**：不支持旧版格式（.doc, .xls, .ppt），请先转换为新格式。
+
+## 环境要求
+
+- **Python 3.8+**（必需）
+- **Node.js 14+**（可选，仅 Markdown → Word 需要）
+
+## 常见问题
+
+### 文件过大怎么办？
+
+当前限制为 100MB，建议分割文件或压缩内容。
+
+### Markdown 转 Word 失败？
+
+需要安装 Node.js。如果 Node.js 已安装但仍报错，检查依赖：
+
+```bash
+npm --prefix bruce_doc_converter/md_to_docx install
+```
+
+### PDF 提取不到内容？
+
+扫描型 PDF 需先执行 OCR，或解除 PDF 保护后重试。
+
+## 最佳实践
+
+1. **使用新版 Office 格式**（.docx, .xlsx, .pptx）
+2. **PDF 优先使用文本型**，扫描型建议先 OCR
+3. **文件大小建议 < 50MB**
+
+## 项目结构
+
+```
+bruce-doc-converter/
+├── SKILL.md                      # Agent Skill 定义
+├── pyproject.toml                # Python 包元数据
+├── requirements.txt              # 本地开发依赖
+├── bruce_doc_converter/
+│   ├── __init__.py
+│   ├── cli.py                    # bdc CLI 入口
+│   ├── converter.py              # 转换核心逻辑
+│   └── md_to_docx/              # Markdown → Word 的 Node.js 模块
+├── references/
+│   └── supported-formats.md
+└── tests/
+    ├── test_cli.py
+    ├── test_convert_document.py
+    └── md_to_docx.test.js
+```
+
+## 许可证
+
+MIT License

bruce_doc_converter-0.1.0/bruce_doc_converter/__init__.py

@@ -0,0 +1,3 @@
+"""Agent-facing document converter CLI."""
+
+__version__ = "0.1.0"

bruce_doc_converter-0.1.0/bruce_doc_converter/cli.py

@@ -0,0 +1,206 @@
+import argparse
+import json
+import os
+import sys
+
+from bruce_doc_converter.converter import SUPPORTED_EXTENSIONS, batch_convert, convert_document
+
+SCHEMA_VERSION = "1.0"
+
+SUGGESTIONS = {
+    "UNSUPPORTED_FORMAT": "请先转换为 .docx/.xlsx/.pptx 后再重试。",
+    "NODE_NOT_FOUND": "请安装 Node.js 后重试 Markdown 到 Word 转换。",
+    "EMPTY_PDF_CONTENT": "请先对扫描件执行 OCR，或解除 PDF 保护后重试。",
+}
+
+
+def _emit(payload, exit_code):
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return exit_code
+
+
+def _usage_error(message):
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "success": False,
+        "error_code": "USAGE_ERROR",
+        "error": message,
+    }
+
+
+class _JsonArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that emits JSON on error instead of human-readable text."""
+
+    def error(self, message):
+        _emit(_usage_error(message), 1)
+        sys.exit(1)
+
+
+def _format_of(path):
+    ext = os.path.splitext(str(path))[1].lower()
+    if not ext:
+        return "unknown"
+    return ext[1:] if ext.startswith(".") else ext
+
+
+def _output_format(input_format):
+    return "docx" if input_format == "md" else "markdown"
+
+
+def _classify_error(error):
+    text = error or ""
+    if "文件不存在" in text or "目录不存在" in text or "文件未找到" in text:
+        return "FILE_NOT_FOUND"
+    if "输入路径不是文件" in text:
+        return "NOT_A_FILE"
+    if "输入路径不是目录" in text or "输出路径不是目录" in text:
+        return "NOT_A_DIRECTORY"
+    if "文件过大" in text:
+        return "FILE_TOO_LARGE"
+    if "不支持的文件格式" in text or "不支持的文件类型" in text:
+        return "UNSUPPORTED_FORMAT"
+    if "未找到 Node.js" in text:
+        return "NODE_NOT_FOUND"
+    if "Node.js 依赖安装失败" in text or "依赖安装失败" in text:
+        return "DEPENDENCY_INSTALL_FAILED"
+    if "Node.js 脚本输出解析失败" in text or "调用 Node.js 脚本失败" in text:
+        return "NODE_CONVERSION_FAILED"
+    if "转换超时" in text:
+        return "CONVERSION_TIMEOUT"
+    if "PDF 未提取到任何文本或表格" in text:
+        return "EMPTY_PDF_CONTENT"
+    if "权限不足" in text:
+        return "PERMISSION_DENIED"
+    if "内存不足" in text:
+        return "OUT_OF_MEMORY"
+    if "系统错误" in text:
+        return "OS_ERROR"
+    return "CONVERSION_ERROR"
+
+
+def _normalize_single_result(input_path, result):
+    normalized_input = os.path.realpath(os.path.expanduser(str(input_path)))
+    input_format = _format_of(normalized_input)
+
+    if result.get("success"):
+        raw_output = result.get("output_path")
+        output_path = os.path.realpath(raw_output) if raw_output else None
+        payload = {
+            "schema_version": SCHEMA_VERSION,
+            "success": True,
+            "input_path": normalized_input,
+            "input_format": input_format,
+            "output_format": _output_format(input_format),
+            "output_path": output_path,
+            "warnings": [],
+        }
+        if input_format == "md":
+            payload["message"] = result.get("message", "")
+        else:
+            payload["markdown_content"] = result.get("markdown_content", "")
+            payload["extracted_images"] = result.get("extracted_images", [])
+        if result.get("warning"):
+            payload["warnings"].append(result["warning"])
+        return payload
+
+    error = result.get("error", "转换失败")
+    error_code = result.get("error_code") or _classify_error(error)
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "success": False,
+        "input_path": normalized_input,
+        "input_format": input_format,
+        "error_code": error_code,
+        "error": error,
+    }
+    if error_code in SUGGESTIONS:
+        payload["suggestion"] = SUGGESTIONS[error_code]
+    return payload
+
+
+def _help_payload():
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "success": True,
+        "commands": {
+            "convert": "Convert one .docx/.xlsx/.pptx/.pdf file to Markdown, or one .md file to DOCX.",
+            "batch": "Convert supported files in a directory.",
+        },
+        "supported_extensions": SUPPORTED_EXTENSIONS,
+    }
+
+
+def _build_parser():
+    # add_help=False: -h would print human text, breaking the JSON-only stdout contract.
+    # Use --help-json for machine-readable help instead.
+    parser = _JsonArgumentParser(prog="bdc", add_help=False)
+    parser.add_argument("--help-json", action="store_true")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Subparsers inherit _JsonArgumentParser because type(parser) is _JsonArgumentParser
+    convert_parser = subparsers.add_parser("convert", add_help=False)
+    convert_parser.add_argument("file")
+    convert_parser.add_argument("--output-dir")
+    convert_parser.add_argument("--extract-images", choices=["true", "false"], default="true")
+
+    batch_parser = subparsers.add_parser("batch", add_help=False)
+    batch_parser.add_argument("directory")
+    batch_parser.add_argument("--output-dir")
+    batch_parser.add_argument("--recursive", choices=["true", "false"], default="true")
+    batch_parser.add_argument("--extract-images", choices=["true", "false"], default="true")
+    return parser
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        return _emit(_usage_error("缺少命令。可用命令: convert, batch"), 1)
+
+    parser = _build_parser()
+    namespace = parser.parse_args(args)
+
+    if namespace.help_json:
+        return _emit(_help_payload(), 0)
+
+    if namespace.command == "convert":
+        output_dir = os.path.realpath(os.path.expanduser(namespace.output_dir)) if namespace.output_dir else None
+        result = convert_document(
+            namespace.file,
+            extract_images=namespace.extract_images == "true",
+            output_dir=output_dir,
+        )
+        payload = _normalize_single_result(namespace.file, result)
+        return _emit(payload, 0 if payload["success"] else 1)
+
+    if namespace.command == "batch":
+        output_dir = os.path.realpath(os.path.expanduser(namespace.output_dir)) if namespace.output_dir else None
+        raw_results = batch_convert(
+            namespace.directory,
+            recursive=namespace.recursive == "true",
+            extract_images=namespace.extract_images == "true",
+            output_dir=output_dir,
+        )
+        results = []
+        for item in raw_results:
+            result_payload = _normalize_single_result(item["file"], item["result"])
+            results.append({
+                "input_path": result_payload["input_path"],
+                "result": result_payload,
+            })
+        succeeded = sum(1 for item in results if item["result"]["success"])
+        total = len(results)
+        payload = {
+            "schema_version": SCHEMA_VERSION,
+            "success": succeeded == total,
+            "total": total,
+            "succeeded": succeeded,
+            "failed": total - succeeded,
+            "results": results,
+        }
+        return _emit(payload, 0 if payload["success"] else 1)
+
+    return _emit(_usage_error("缺少命令。可用命令: convert, batch"), 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())