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、クラウドエージェント）	--url	ユーザー向けのダウンロード URL を返します
ローカル実行（ユーザーのマシン）	--file	.docx をディスクに直接保存します

判断基準：

• --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 キーは 3 つの方法で設定できます。

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. 構文を使用している
• コードブロックに 3 つのバッククォートを使用している
• 数式に $...$（インライン）または $$...$$（ブロック）を使用している
• 画像に一般公開されている URL を使用している

レスポンスの処理

URL モードのレスポンス

成功（200 OK）：

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

ファイルモードのレスポンス

成功：ファイルがディスクに保存され、パスが標準出力に表示されます

エラーレスポンス（両モード共通）

• 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 に変換して」（スキルはクラウドで実行）

1. Markdown の内容を一時ファイル（例：temp.md）に保存します

2. URL モードで変換スクリプトを実行します：

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

3. スクリプトは次の処理を行います：

   • 優先順位に従って API キーを選択します（環境変数 → スキル → トライアル）
   • 変換 API を呼び出します
   • ダウンロード URL を返します

4. ダウンロード URL をユーザーに提示します

5. 一時ファイルを削除します

ワークフロー 2：ローカル環境（ファイルモード）

ユーザーの依頼：「notes.md を Word に変換して」（スキルはローカルで実行）

1. ファイルモードで変換スクリプトを実行します：

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

2. スクリプトは次の処理を行います：

   • 優先順位に従って API キーを選択します（環境変数 → スキル → トライアル）
   • 変換 API を呼び出します
   • DOCX ファイルを直接保存します

3. ファイルの保存先をユーザーに伝えます

4. クリーンアップは不要です。ファイルが出力です