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 decision

• Identity: Markdown files usually belong to the user's cloud space resources, so prefer using --as user. For automation scenarios, or if the app has already created and holds permissions on the target file, you may use --as botdepending on the scenario. Before accessing for the first time as the user identity, 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 issue,user is more commonly a user authorization or user ACL issue; do not switch identities back and forth and retry without making a judgment.

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

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

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

• The user wants to performlocal text replacement / regex replacementon a Markdown file, prefer using lark-cli markdown +patch

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

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

• The user wants to import local Markdown into a new online document (docx), do not use this skill, instead use lark-drive 's lark-cli drive +import --type docx

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

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

• markdown +create Do not guess the target parameter of: for Drive folders use --folder-token, for Wiki nodes use --wiki-token. If the user provides a URL, you can pass the full URL directly; 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 this is not satisfied, the shortcut will directly report an error
• --content Supports:
  • Pass a string directly
  • @file Read content from a local file
  • - Read content from stdin
• markdown +patch 's 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 The final content after replacementcannot be empty; the CLI will reject uploading 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 the escaping of --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 to use first)

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

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.