lark-markdown

markdown (v1)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling

Quick decisions

• Identity: Markdown files usually belong to the user's cloud space resources, so prefer to use --as user. For automation scenarios, or if the app has already created and holds permissions on the target file, use as appropriate for the scenario --as bot. For the first time as user identity, before accessing execute lark-cli auth login

• markdown +create / +overwrite fails, first determine whether it is an identity and permission issue:bot is more commonly an app scope or target directory ACL,user is more commonly user authorization or user ACL; do not switch identities back and forth and retry without making a judgment.

• User wants toupload or create a native .md file, use lark-cli markdown +create

• User wants tocompare historical version differences of a native .md file, or compare remote Markdown with a local draft, use lark-cli markdown +diff

• User wants toread the content of a certain .md file in Drive, use lark-cli markdown +fetch

• User wants to perform on a Markdown filelocal text replacement / regex replacement, prefer to use lark-cli markdown +patch

• User wants tooverwrite and update the content of a certain .md file in Drive, use lark-cli markdown +overwrite

• User wants to first get the historical version number of a Markdown file, then compare/download/roll back, first use lark-drive of lark-cli drive +version-history

• User wants to import a local Markdown into an online new document (docx), do not use this skill, instead use lark-drive of lark-cli drive +import --type docx

• User wants to perform on a Markdown filerename / move / delete / search / permissions / commentsand other cloud space (cloud drive/cloud storage) operations, do not stay in this skill, switch to lark-drive

• markdown +create / +overwrite hits missing scope、permission denied、not found、quota_exceeded、version limit , by default stop retrying and handle according to the error hint; only rate_limit、server_error or temporary network errors should do limited backoff retries.

• markdown +create target parameters should not be guessed: Drive folders use --folder-token, Wiki nodes use --wiki-token. If the user gives a URL, you can directly pass the full URL; the CLI will normalize it into a token. Do not put doc/sheet/wiki URLs into --folder-token for trial and error.

Core boundaries

• This skill handles Markdown stored as ordinary files in Drive, not docx documents
• --name and local --file filenames must both explicitly carry the .md suffix; if not satisfied, the shortcut will directly report an error
• --content supports:
  • directly pass a string
  • @file read content from a local file
  • - read content from stdin
• markdown +patch internal semantics are:first fully download the Markdown, then replace locally, then overwrite and upload the entire file
• markdown +patch is not a server-side atomic patch; it is a local update capability orchestrated on the CLI side
• markdown +patch Currently onlysingle group --pattern / --content
• markdown +patch Final content after replacementcannot be empty; the CLI will refuse to upload an empty file because Drive does not support zero-byte Markdown, and an empty file is usually a mistake
• --file Only accepts local .md file paths

When doing regex replacement, pay special attention to escaping --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)"

Shortcuts (recommended for priority use)

Shortcut is a high-level wrapper for common operations (lark-cli markdown +<verb> [flags]). For operations that have a Shortcut, prefer using it.

Shortcut	Description
+create	Create a Markdown file in Drive
+diff	Compare two remote Markdown versions, or compare remote Markdown against a local file
+fetch	Fetch a Markdown file from Drive
+patch	Patch a Markdown file in Drive via fetch-local-replace-overwrite
+overwrite	Overwrite an existing Markdown file in Drive

Reference

• lark-shared — authentication and global parameters
• lark-drive — Drive file management, import docx, move/delete/search, etc.