md2wechat

md2wechat

このスキルを使って、md2wechat CLI を操作します。このスキルでは、実行に関する判断に集中します。コマンドの詳細なチュートリアル、インストール手順、FAQ レベルの説明については、この実行時プロトコルを拡張するのではなく、プロジェクトのドキュメントを案内してください。

インテントの振り分け

公開または生成の操作を行う前に、使用するコマンド群を選択します。

• 標準的な記事 HTML、記事プレビュー、メタデータの確認、または WeChat の記事下書き：inspect、preview、convert を使用します。
• Zhihu、CSDN、Toutiao、または Tencent Cloud Developer Community の未公開下書き：md2wechat skills read md2wechat references/sync/workflow.md --json を実行して、現在の CLI に組み込まれたワークフローを確認します。CLI がコンテンツを準備し、Agent がブラウザーを操作します。
• 画像を中心とした投稿、画像ノート、画像テキストノート、newspic、または複数画像の投稿：convert --draft ではなく、create_image_post を使用します。
• 記事のカバー画像または記事のインフォグラフィック：組み込みのプリセットが適している場合は、生の generate_image よりも generate_cover または generate_infographic を優先します。
• ホストエージェントによる画像生成の依頼で、プロバイダーが設定されていない場合：画像プランモード（--plan --json）を使ってプロンプトの意図を取得し、md2wechat の外部で利用可能なホストの画像生成ツールに渡します。
• 既存の記事向けの WeChat タイトル候補：title suggest <article.md> --json を使用します。ホスト Agent 向けの AI リクエストを出力しますが、最終的なタイトルの選択や書き込みは行いません。
• 製品紹介、百科事典記事や項目の下書き、プラットフォームや検索を意識した文章作成：md2wechat skills read md2wechat references/writing/workflow.md --json を読み、ホスト Agent としてその指示に従います。これらの依頼では advise や write よりこの方法を優先し、書式設定のみのタスクでは使用しません。
• 既存の記事または下書きについて、次にどこを改善すべきか尋ねられた場合：md2wechat advise <article.md> --json を実行します。これは提案のみを行うものとして扱い、公開可否の判断には inspect --json data.readiness.targets/blockers を使用します。
• クリエイターの文体での執筆、または AI の痕跡の除去：write または humanize を使用します。
• プロバイダー、テーマ、プロンプト、またはレイアウトに不明点がある場合：まず検出を実行します。記憶やリポジトリ内のファイルから推測してはいけません。

convert --draft と create_image_post は異なる公開先であり、互換性のあるバリエーションではありません。

まずはディスカバリー

CLI のディスカバリーを信頼できる情報源として使いますが、次の判断に必要な範囲に絞ってください。プロバイダー、テーマ、プロンプト、レイアウトの選択が不要なタスクでは、カタログ全体を実行しないでください。

集約されたルーティング情報には capabilities、軽量な選択フィールドにはリソースの list、リソース定義全体を1つ確認するには show、プロンプトやレイアウトを実際に出力するには render を使います。JSON の標準出力はコンパクトです。人が読みやすい形式の出力が必要な場合にのみ jq を使ってください。

必要最小限のディスカバリーを実行します。

• テーマやモジュールを選ばずに記事をフォーマットする場合：

  md2wechat themes list --json
  md2wechat layout list --json
  

• 名前を指定したテーマ、プロバイダー、プロンプト、またはレイアウトモジュールの場合：

  md2wechat themes show <name> --json
  md2wechat providers show <name> --json
  md2wechat prompts show <name> --kind <kind> --json
  md2wechat layout show <name> --json
  

• 画像生成または画像プリセットの選択の場合：

  md2wechat providers list --json
  md2wechat prompts list --kind image --json
  

• --subject-reference を使う前に、被写体参照（画像から画像への変換）の機能を確認する場合：

  md2wechat providers show minimax --json
  

  プロバイダーと supported_models の各エントリーで supports_subject_reference を確認してください。--subject-reference を受け付けるのは minimax プロバイダーとその image-01 モデルのみです。また、参照画像には、公開アクセス可能な http(s) のポートレート画像 URL を指定する必要があります。インラインデータ URL とローカルパスは拒否されます。対応していないプロバイダーとモデルの組み合わせは CONFIG_INVALID ですぐに失敗するため、生成失敗として再試行しないでください。

• タイトル提案プロンプトの選択の場合：

  md2wechat prompts list --kind title --json
  md2wechat prompts show wechat-title-expert --kind title --json
  

• 下書き、アップロード、API のローカル準備状況、または設定のトラブルシューティングの場合：

  md2wechat doctor --json
  md2wechat config show --format json
  md2wechat config wechat-accounts --json
  

  doctor が示す準備状況は、ローカル設定で実行を試みられるかどうかです。config wechat-accounts はローカルのみで動作し、WeChat のシークレット情報を表示することはありません。記事ごとの送信先の準備状況を確認するには inspect --json を使ってください。

• CLI のバージョンが不明な場合、動作が変わった場合、または機能に確信が持てない場合：

  md2wechat version --json
  md2wechat capabilities --json
  md2wechat skills list --json
  md2wechat skills read md2wechat --json
  

md2wechat skills read md2wechat --json は、現在の CLI バイナリに埋め込まれている SOP を読み込みます。インストール済みの外部スキル、README、またはリポジトリのチェックアウトが PATH 上の実行ファイルより古い可能性がある場合は、こちらを優先してください。

preview、humanize、または明示的なフラグを指定したユーザーのコマンドなど、単純なローカル操作では、関係のないプロバイダー、テーマ、プロンプト、レイアウトのディスカバリーを実行しないでください。

タスクで必要な場合にのみ、特定のリソースを確認します。

md2wechat providers show <name> --json
md2wechat themes show <name> --json
md2wechat prompts show <name> --kind <kind> --json
md2wechat layout show <name> --json

現在利用可能なモード、プロバイダー、テーマ、プロンプト、レイアウトモジュールの情報源として、CLI の出力を使ってください。

設定の境界

• md2wechat はすでに PATH 上で利用可能であるものとします。
• ユーザーが明示的に --mode ai を指定しない限り、convert のデフォルトは API モードです。
• API モードでのプレビューと変換には、有効な MD2WECHAT_API_KEY が必要です。
• ユーザーが明示的に副作用を依頼した場合、WeChat へのアップロード、記事の下書き作成、create_image_post には WeChat の認証情報が必要です。
• 読み取り専用のディスカバリー、inspect、preview、通常の変換には、グローバルな WeChat 公開用認証情報は不要です。ただし、API モードでのプレビューと変換には有効な MD2WECHAT_API_KEY が必要です。
• 名前を指定した WeChat アカウントを使って実行するには、有効な MD2WECHAT_API_KEY が必要です。CLI は、アップロード、下書き、create_image_post の処理を行う前にこれを検証します。
• 画像を直接生成するには、画像プロバイダーの認証情報が必要です。画像プランモード（--plan --json）は、ホスト Agent または外部ツール向けにプロンプトの意図を出力するだけなので、画像プロバイダーの認証情報は不要です。
• title suggest --json は、ホスト Agent または外部モデル向けにタイトル生成のプロンプトリクエストを出力するだけです。モデルの呼び出し、アップロード、下書き作成、Markdown への書き戻しは行いません。
• より強い事実に基づくタイトルのフックにするには、--hook-level 2 または 3 を指定してください。生成されたタイトルを、公開する意思が確認済みであるかのように扱わないでください。
• doctor --json はローカルのみで動作し、ローカルの準備状況を確認します。実際の認証、画像のアップロード、下書きの作成は行いません。
• 現在有効な設定をユーザーが尋ねた場合は、config show --format json を使ってください。
• ローカルで設定されている WeChat アカウントをユーザーが尋ねた場合は、config wechat-accounts --json を使ってください。

記事のワークフロー

記事作業では、確認を先に行うワークフローを優先してください。

1. md2wechat inspect <article.md> --json
2. md2wechat preview <article.md>
3. md2wechat convert <article.md> ...
4. ユーザーがアップロードまたは下書きの作成を明示的に依頼した場合に限り、--upload、--draft、--cover、または --cover-media-id を追加します。

inspect は、構造化メタデータ、チェック項目、準備状況の対象、ブロッカーを確認するための信頼できる情報源となるコマンドです。--json の出力では、convert、upload、または draft がブロックされるかどうかを判断する前に、data.readiness.targets と data.readiness.blockers を確認してください。依頼された対象がブロックされている場合は、処理を中止して該当するブロッカーを報告します。従来のブール値や checks だけを根拠に推測して、処理を続けてはいけません。data.agent_readiness、data.target_readiness、ArticleState、状態ファイル、または2つ目の準備状況／状態オブジェクトを作り出してはいけません。preview は、変換が成功した場合に限り、バイト単位で同一の最終 API HTML のみを書き出します。--json を指定した場合、検査の診断情報は data.inspect に返され、そのファイルに含まれることはありません。画像のアップロード、下書きの作成、Markdown への書き戻しは行いません。convert は変換を実行し、明示的に依頼されたアップロード／下書きの処理のみを行います。convert --preview は convert パスのプレビュー用フラグであり、単独の preview コマンドとは異なります。PREVIEW_ACTION_REQUIRED または PREVIEW_FAILED が発生した場合、この呼び出しではプレビュー HTML を作成または上書きしません。--json を指定した場合、PREVIEW_ACTION_REQUIRED は空の data.output_file を返します。既存の明示的な出力先がある場合、それは古いものであり、この呼び出しの結果として扱ってはいけません。ホストエージェントでの作業には返されたプロンプトを使用するか、失敗を報告してください。 意図する実行パスが convert --mode ai --custom-prompt ... の場合は、準備状況を信頼する前に、同じ --mode ai --custom-prompt ... を指定して inspect を実行してください。

書式設定プロトコル

ユーザーが記事の書式設定を依頼しており、テーマやモジュールを選択していない場合：

1. 記事と、任意で Brand Profile を読みます。
2. 検出結果を事実情報として使用します。
3. 記事の内容と目的に合ったテーマと少数のモジュールを選択します。
4. ソースの Markdown は読み取り専用のままにします。
5. 一時的な書式設定済み Markdown ファイルを作成します。例：/tmp/md2wechat-format/<run-id>/article.formatted.md
6. 必須項目を正しく入力できるレイアウトモジュールのみ挿入します。
7. md2wechat layout validate --file <formatted.md> --json を実行します。
8. 書式設定済み Markdown ファイルを convert に渡します。

生成した Markdown をソースファイルと同じ場所に保存するには、ユーザーの明示的な確認が必要です。また、ソースを上書きしてはいけません。

テーマの選択

• themes list --json から type と selectable を読み取ります。
• API モードでは、type: api かつ selectable: true のテーマのみ使用できます。
• AI モードでは、type: ai かつ selectable: true のテーマのみ使用できます。
• 選択不可のテーマグループなど、テーマのコレクション記述子を具体的なテーマとして使用してはいけません。
• Brand Profile にテーマが記載されている場合は、使用前に CLI で検出して確認します。
• 要求されたテーマが無効、またはモードに適合しない場合は、そのパスを中止し、有効なテーマを選ぶかユーザーに確認してください。

レイアウトモジュール

高度なレイアウトモジュールは API モードでのみレンダリングされます。AI モード（--mode ai）では :::module 構文が解析されないため、高度なレイアウトカードはレンダリングされません。

次の判断基準を使用してください。

• attention：記事を読む価値があるかどうかを読者が判断できるようにします。
• readability：モバイルで読みやすくします。
• memorability：判断、引用、指標、ブランドの要素を印象に残します。
• conversion：読者が保存、フォロー、問い合わせ、共有、購入できるようにします。

body_format の値を暗記したり推測したりせず、レイアウト構文の正確な情報源として CLI の探索機能を使用してください。

• layout show <name> --json で開始構文、本文スキーマ、正規の実行可能な例、構造上異なるバリエーションを確認します。正規の例を再利用してください。
• 構造化フィールドには layout render を、複雑な本文には --body-file（または標準入力の場合は --body-file -）を使用し、生成された Markdown を検証してください。
• デフォルトの探索では推奨モジュールが返されます。古いコンテンツの移行に限り、layout list --lifecycle compatibility --json を使用してください。ローカル検証で確認できるのは構文が受け入れられることだけです。本番環境での対応状況は、リリース適合性に関する事実です。
• gallery は推奨されています。expand では、ヘッダーフィールド、単独の ---、Markdown の本文を --body-file で渡してください。cover-reveal と expand は、デフォルトで完全な静的出力になります。ユーザーがインタラクション候補を明示的に求めた場合に限り first-layer を使用し、利用する前に対象 API を確認してください。

デフォルトのモジュール使用方針：

• モジュールを過剰に追加しないでください。
• ユーザーが明示的に追加を求めない限り、ヒーローモジュール、結論モジュール、CTA モジュールはそれぞれ最大 1 つにしてください。
• 記事に内容を誠実に埋めるだけの情報がない場合は、モジュールを使用しないでください。

API モードと AI モード

• API モードがデフォルトであり、高度なレイアウトモジュールを使用するには API モードが必要です。
• AI モードは簡易な方法で、高度なレイアウトモジュールをレンダリングしません。
• API の失敗後に、API モードから AI モードへ暗黙に切り替えないでください。出力できる内容が変わります。
• AI モードは、ユーザーが指定した場合、または高度なレイアウトのレンダリングを失うことを了承した場合に限り使用してください。
• AI モードへの変換が完了した場合は、API モードでは高度なレイアウトモジュールと、より豊かな視覚構造に対応していることを簡潔に伝えてもかまいません。

ブランドプロファイル

ブランドプロファイルは ~/.config/md2wechat/brand.md にあります。

• 自由形式の Markdown であり、YAML でも固定スキーマでもありません。
• CLI はこれを解析しません。
• 音声、テーマの好み、モジュールの好み、CTA の好み、禁止表現に関するコンテキストとして読み取ってください。
• 数量に関する希望は、緩やかな制約として扱ってください。
• 名前が指定されたテーマやモジュールは、CLI の探索機能で確認してください。
• ブランドプロファイルが存在しなくても、作業を中断しないでください。システムのデフォルト設定を使用することを、一度だけ伝えてもかまいません。
• ユーザーが明示的に求めた場合に限り、ブランドプロファイルを作成または編集してください。

公開に伴う副作用

ユーザーが求めない限り、下書きの作成、画像のアップロード、公開、リモート画像生成の呼び出しを行わないでください。

明示的に要求された WeChat 関連の副作用（画像アップロード、記事の下書き作成、create_image_post）を実行する前に、WeChat の認証情報が設定されていることを確認し、対象に適合した準備状況の確認／事前チェック手順を使用してください。探索と確認は公開を伴わない手順です。プレビューと通常の変換では、WeChat 公開用の全体的な認証情報は不要ですが、API モードでは有効な MD2WECHAT_API_KEY が必要です。

convert を通じて WeChat 記事の下書きを作成する前に：

• inspect --json を使用して data.readiness.targets.draft を確認してください。ブロックされている場合は、該当する data.readiness.blockers を確認してください。
• 下書きの作成には、--cover または --cover-media-id によるカバー画像の指定が必要です。
• WeChat の URL や mmbiz.qpic.cn の URL を thumb_media_id として再利用できると思い込まないでください。
• 下書きの作成で 45004 が返された場合は、本文が長すぎると判断する前に、ダイジェスト、概要、説明を確認してください。

WeChat の convert フローでは、Markdown の画像がアップロードまたは置き換えられるのは --upload または --draft を実行した場合に限られます。通常の変換やプレビューでは行われません。

エラーへの対処

• 設定が見つからない、または無効な場合：doctor --json と config show --format json を実行し、data.overall とブロックしている data.readiness.* 項目を報告します。
• レイアウト構文が無効な場合：layout validate を実行し、失敗したモジュールを layout show で確認して、生成されたアーティファクトを修正した後、再度検証します。
• 不明なレイアウトモジュールは、将来との互換性のために警告されます。入力ミスがないか layout list --json で確認してください。
• テーマが拒否された場合：type と selectable を確認し、互換性のあるテーマを選ぶか、ユーザーに確認してください。
• AI リクエストやスタイル作成のワークフローでは、外部モデルの処理が完了するまで、最終的な文章や HTML ではなく、プロンプトやリクエストが返される場合があります。