lark-markdown

markdown（v1）

重大事項 — 開始前に、まず Read ツールを使って ../lark-shared/SKILL.md を読み込んでください。認証と権限の処理について記載されています。

クイック判断

• ID：Markdown ファイルは通常、ユーザーのクラウドストレージのリソースにあたるため、まず --as user を使用します。自動化のシナリオ、またはアプリが対象ファイルを作成済みで、その権限を持っている場合は、状況に応じて --as bot を使用できます。初めて user としてアクセスする前に、lark-cli auth login を実行してください。

• markdown +create / +overwrite が失敗した場合は、まず ID と権限の問題かどうかを確認してください。bot ではアプリのスコープや対象フォルダーの ACL、user ではユーザーの認可やユーザー ACL が原因であることが多くあります。判断せずに ID を切り替えて再試行しないでください。

• ユーザーがネイティブの .md ファイルをアップロードまたは作成したい場合は、lark-cli markdown +create を使用します。

• ユーザーがネイティブの .md ファイルの過去のバージョン間の差分、またはリモートの Markdown とローカルの下書きを比較したい場合は、lark-cli markdown +diff を使用します。

• ユーザーが Drive 内の .md ファイルの内容を読み取りたい場合は、lark-cli markdown +fetch を使用します。

• ユーザーが Markdown ファイルのテキストの一部置換／正規表現置換をしたい場合は、まず lark-cli markdown +patch を使用します。

• ユーザーが Drive 内の .md ファイルの内容を上書き更新したい場合は、lark-cli markdown +overwrite を使用します。

• ユーザーが Markdown ファイルの過去のバージョン番号を取得してから、比較／ダウンロード／ロールバックしたい場合は、まず lark-drive の lark-cli drive +version-history を使用します。

• ユーザーがローカルの Markdown をオンラインの新しいドキュメント（docx）としてインポートしたい場合は、このスキルを使わず、lark-drive の lark-cli drive +import --type docx を使用します。

• ユーザーが Markdown ファイルの名前変更／移動／削除／検索／権限／コメントなど、クラウドストレージ（クラウドドライブ／クラウドストレージ）上の操作をしたい場合は、このスキルではなく、lark-drive に切り替えてください。

• markdown +create / +overwrite で missing scope、permission denied、not found、quota_exceeded、version limit が発生した場合は、原則として再試行を停止し、エラーのヒントに従ってください。rate_limit、server_error、一時的なネットワークエラーの場合に限り、回数を限定してバックオフ再試行してください。

• markdown +create の対象パラメーターを推測しないでください。Drive フォルダーには --folder-token、Wiki ノードには --wiki-token を使用します。ユーザーから URL が渡された場合は、URL 全体をそのまま指定できます。CLI がトークンに正規化します。doc／sheet／wiki の URL を --folder-token に指定して試さないでください。

主な制約

• このスキルが扱うのは、Drive 内に通常のファイルとして保存された Markdownであり、docx ドキュメントではありません。
• --name とローカルの --file のファイル名には、明示的に .md 拡張子を付ける必要があります。付いていない場合、ショートカットはエラーを返します。
• --content は次の形式に対応しています。
  • 文字列を直接指定する
  • @file を指定してローカルファイルから内容を読み込む
  • - を指定して stdin から内容を読み込む
• markdown +patch の内部動作は、Markdown 全体をダウンロードし、ローカルで置換してから、ファイル全体を上書きアップロードすることです。
• markdown +patch はサーバー側で原子的に実行されるパッチではありません。CLI 側で構成された部分更新機能です。
• markdown +patch が現在サポートしているのは、--pattern と --content の1 組のみです。
• markdown +patch による置換後の内容は空にできません。Drive は 0 バイトの Markdown をサポートしておらず、空ファイルは通常、誤操作であるため、CLI はアップロードを拒否します。
• --file に指定できるのは、ローカルの .md ファイルパスのみです。

正規表現で置換する場合は、--pattern のエスケープに特に注意してください。

# BAD: 未转义正则特殊字符，可能匹配到错误位置
lark-cli markdown +patch --file-token boxcnxxxx --regex --pattern "version (1.0)" --content "version (2.0)"

# GOOD: 显式转义括号和点号
lark-cli markdown +patch --file-token boxcnxxxx --regex --pattern "version \\(1\\.0\\)" --content "version (2.0)"

ショートカット（優先して使用することを推奨）

ショートカットは、よく使う操作を高水準でラップしたものです（lark-cli markdown +<verb> [flags]）。ショートカットがある操作では、優先して使用してください。

ショートカット	説明
+create	Drive に Markdown ファイルを作成する
+diff	2 つのリモート Markdown バージョンを比較する、またはリモートの Markdown とローカルファイルを比較する
+fetch	Drive から Markdown ファイルを取得する
+patch	取得・ローカル置換・上書きの手順で、Drive 内の Markdown ファイルにパッチを適用する
+overwrite	Drive 内の既存の Markdown ファイルを上書きする

参考資料

• lark-shared — 認証とグローバルパラメーター
• lark-drive — Drive ファイル管理、docx のインポート、移動／削除／検索など