docs +create / +update: skill examples with "...\n..." send literal `\n` to MCP, breaking Markdown rendering

[halleystar]

Environment

• OS: Linux (also reproduced on Debian)
• lark-cli: v1.0.14 and v1.0.15
• Shell: bash 5.x
• Installed via: npm install -g @larksuite/cli

Summary

The official skill references for docs +create and docs +update contain examples like:

lark-cli docs +create --title "项目计划" --markdown "## 目标\n\n- 目标 1\n- 目标 2"

This is misleading. Inside bash double quotes, \n is two literal characters, not a newline. lark-cli forwards the value byte-for-byte to MCP (create-doc / update-doc), so the resulting Feishu document ends up containing the literal text \n\n everywhere instead of paragraph breaks.

Affected skill files (on main and v1.0.15):

• skills/lark-doc/references/lark-doc-create.md — ## 命令 block and ## 示例 section (multiple occurrences)
• skills/lark-doc/references/lark-doc-update.md — ## 命令 block and # 使用示例 section (multiple occurrences)

Agents that follow the skill examples verbatim reliably produce broken documents.

Reproduction (using --dry-run, no document created)

# 1) As written in the skill examples — literal \n
lark-cli docs +create --dry-run --title "t1" --markdown "## A\n\n- x\n- y"

# 2) With real newlines (ANSI-C quoting)
lark-cli docs +create --dry-run --title "t2" --markdown $'## A\n\n- x\n- y'

Payload sent to https://mcp.feishu.cn/mcp for (1):

"markdown": "## A\\n\\n- x\\n- y"

(i.e. the JSON string contains \n as two chars — backslash + n.)

Payload for (2):

"markdown": "## A\n\n- x\n- y"

(i.e. real newline bytes.)

Only (2) renders correctly in Feishu. (1) renders the literal \n as visible text.

Expected

At minimum: the skill documentation should not teach users to write "...\n...". Options:

1. Update examples to use real newlines (multi-line double-quoted strings) or $'...' / @file / stdin (-).
2. Or make --markdown auto-interpret \n / \t etc. as escape sequences (matching common CLI expectations). This is what some users apparently assume based on the current examples.

Option 1 is the safer, documentation-only fix. Option 2 would be a breaking change for anyone relying on literal backslash-n in their markdown.

Impact

• Any AI agent / user copy-pasting the skill examples produces broken docs.
• The problem is not limited to agents: developers reading the README-style examples naturally write the same pattern.
• Related-but-different issue im +messages-send --markdown: table syntax and blank lines are silently dropped #202 / PR feat: markdown support line breaks #338 already addressed blank-line loss on the im +messages-send path; docs +create/+update was not touched.

Suggested documentation fix

Replace the command blocks with real-newline examples, e.g.:

lark-cli docs +create --title "项目计划" --markdown "## 目标

- 目标 1
- 目标 2"

Or explicitly recommend stdin / file:

lark-cli docs +create --title "项目计划" --markdown - <<'MD'
## 目标

- 目标 1
- 目标 2
MD

And add a prominent note:

--markdown is forwarded as-is to the MCP tool. Pass real newlines; literal \n inside "..." will be written as backslash-n into the resulting document.

Happy to submit a PR for the doc changes if that helps.