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 user cloud space resources; prefer using --as user. For automation scenarios, or if the app has already created and holds permissions for the target file, you may use --as botas appropriate. Before accessing as user for the first time, run lark-cli auth login

• markdown +create / +overwrite fails, first determine whether it is an identity or 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 judgment.

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

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

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

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

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

• If the 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

• If the user wants to import a local Markdown as an online new-version document (docx), do not use this skill; instead use lark-drive of lark-cli drive +import --type docx

• If the user wants to performrename / move / delete / search / permission / commentand 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 retry with limited backoff for rate_limit、server_error or temporary network errors.

• markdown +create Do not guess the target parameters of --folder-token: use --wiki-tokenfor Drive folders and --folder-token for trial and error.

Core boundaries

• This skill handles Markdown stored as an ordinary file in Drive, not docx documents
• --name Both --file and the local .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 The internal semantics ofare: first fully download the Markdown, then replace locally, then overwrite and upload the entire file
• markdown +patch It is not a server-side atomic patch; it is a local update capability orchestrated on the CLI side
• markdown +patch Currently only supportsa single group --pattern / --content
• markdown +patch The 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 mistaken operation
• --file Only accepts local .md File path

When performing 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 with 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.