md2docx

md2docx - Markdown 转 Word 转换器

将 Markdown 文本转换为格式专业的 Word（DOCX）文档。

快速开始

根据你的环境选择合适的模式：

# URL mode: Returns download URL (for cloud/remote environments)
python scripts/convert.py input.md --url

# File mode: Saves file directly (for local environments)
python scripts/convert.py input.md --file

选择合适的模式

场景	模式	命令
工具在云端运行，用户需要下载	--url	python scripts/convert.py input.md --url
工具在本地运行，用户希望保存文件	--file	python scripts/convert.py input.md --file
远程执行（MCP、API、云端 Agent）	--url	返回供用户下载的 URL
本地执行（用户的机器）	--file	直接将文件保存到磁盘

判断规则：

• 使用 --url：工具运行环境与用户所在环境不同（云端、远程服务、MCP 服务）时
• 使用 --file：工具运行在用户希望保存输出文件的同一台机器上时

工作原理

1. 准备 Markdown：确保内容采用标准 Markdown 格式
2. 运行脚本：以合适的模式执行 scripts/convert.py
3. 获取结果：
   • URL 模式：接收下载 URL
   • 文件模式：文件保存到指定位置

API 详情

端点：

• URL 模式：https://api.deepshare.app/convert-text-to-url → 返回 {"url": "..."}
• 文件模式：https://api.deepshare.app/convert-text → 直接返回 DOCX 文件

身份验证：添加请求头 X-API-Key: {api_key}

API 密钥配置

你可以通过以下三种方式配置 API 密钥：

1. 环境变量（优先级最高）

   export DEEP_SHARE_API_KEY="your_api_key_here"
   

2. 工具变量（优先级中等） 编辑此工具文件 YAML 前置元数据中的 api_key 字段：

   ---
   name: md2docx
   api_key: "your_api_key_here"
   ---
   

3. 试用密钥（后备方案）：f4e8fe6f-e39e-486f-b7e7-e037d2ec216f

优先级顺序：

1. 环境变量 DEEP_SHARE_API_KEY（如果已设置）
2. 工具的 api_key 变量（如果不为空）
3. 试用密钥（配额有限）

⚠️ 试用模式：配额有限。如需稳定地用于生产环境，请访问 https://ds.rick216.cn/purchase 购买。

请求格式

{
  "content": "markdown text here",
  "filename": "output",
  "template_name": "templates",
  "language": "zh",
  "hard_line_breaks": false,
  "remove_hr": false
}

参数

参数	默认值	说明
content	必填	要转换的 Markdown 文本
filename	"output"	输出文件名（不含 .docx）
template_name	"templates"	模板：templates、论文、article、thesis 等
language	"zh"	模板语言：zh 或 en
hard_line_breaks	false	保留单个换行符
remove_hr	false	移除水平分隔线

常用模板

中文（language: "zh"）：

• templates - 通用模板
• 论文 - 学术论文
• 论文-首行不缩进 - 首行不缩进的论文
• 论文-标题加粗 - 标题加粗的论文

英文（language: "en"）：

• templates - 通用模板
• article - 文章／报告样式
• thesis - 学术论文

转换脚本用法

命令行选项

python scripts/convert.py <input.md> [options]

Options:
  --url              Return download URL (default if no mode specified)
  --file             Save file directly to disk
  --template, -t     Template name (default: templates)
  --language, -l     Language: zh or en (default: zh)
  --output, -o       Output directory for file mode
  --api-key, -k      API key (optional)

示例

# URL mode (cloud/remote environments)
python scripts/convert.py document.md --url
python scripts/convert.py paper.md --url --template 论文 --language zh

# File mode (local environments)
python scripts/convert.py document.md --file
python scripts/convert.py paper.md --file --output ./docs --template thesis --language en

# With custom API key
python scripts/convert.py doc.md --url --api-key your_key

转换前验证

确保 Markdown 内容符合以下要求：

• 标题使用 # 语法
• 列表使用 - 或 1. 语法
• 代码块使用三个反引号
• 数学公式使用 $...$（行内）或 $$...$$（块级）
• 图片使用可公开访问的 URL

响应处理

URL 模式响应

成功（200 OK）：

{
  "url": "https://flies.deepshare.app/mcp/hash/document_xxx.docx"
}

文件模式响应

成功：文件已保存到磁盘，路径已输出到 stdout

错误响应（两种模式均适用）

• 401 Unauthorized - API 密钥无效
• 403 Forbidden - 配额已用尽 → 请访问 https://ds.rick216.cn/purchase 购买
• 413 Payload Too Large - 内容超过 10MB
• 500 Internal Server Error - 服务不可用，请重试

与用户沟通

成功时

告知用户：

1. 转换已成功完成
2. URL 模式：提供下载 URL
3. 文件模式：提供文档的保存路径
4. 检查使用了哪个 API 密钥：
   • 如果使用环境变量或 Skill 变量：无需提醒
   • 如果使用试用密钥：提醒：“⚠️ 你正在使用试用模式（额度有限）。如需稳定地用于生产环境，请在此处获取 API 密钥：https://ds.rick216.cn/purchase”

额度超限时

告知用户：

1. 转换失败：额度已超限
2. 前往 https://ds.rick216.cn/purchase 购买更多额度
3. 或使用其他 API 密钥

发生其他错误时

告知用户：

1. 出了什么问题（根据错误消息）
2. 如何解决
3. 提供重试选项

提示

• API 密钥配置：
  • 选项 1（推荐）：设置环境变量 DEEP_SHARE_API_KEY

    export DEEP_SHARE_API_KEY="your_api_key_here"
    

  • 选项 2：编辑此 Skill 的 YAML frontmatter 中的 api_key
  • 选项 3：使用试用密钥（额度有限）
• 文件大小：Markdown 文件请控制在 10MB 以下
• 图片：使用 https:// URL，而不是本地路径
• 数学公式：使用 LaTeX 语法：$E=mc^2$ 或 $$\int_0^\infty$$
• 换行：地址、诗歌等内容请设置 hard_line_breaks: true
• 模板：根据文档类型（论文、文章等）选择模板

工作流示例

工作流 1：云环境（URL 模式）

用户请求：“将此内容转换为 Word”（Skill 在云端运行）

1. 将 Markdown 内容保存到临时文件（例如 temp.md）

2. 使用 URL 模式运行转换脚本：

   python scripts/convert.py temp.md --url
   

3. 脚本将：

   • 按优先级选择 API 密钥（环境变量 → Skill → 试用密钥）
   • 调用转换 API
   • 返回下载 URL

4. 向用户提供下载 URL

5. 清理临时文件

工作流 2：本地环境（文件模式）

用户请求：“将我的 notes.md 转换为 Word”（Skill 在本地运行）

1. 使用文件模式运行转换脚本：

   python scripts/convert.py notes.md --file --output ./output
   

2. 脚本将：

   • 按优先级选择 API 密钥（环境变量 → Skill → 试用密钥）
   • 调用转换 API
   • 直接保存 DOCX 文件

3. 告知用户文件的保存位置

4. 无需清理，输出文件即为结果