Feishu

Feishu Wiki Tools

Read, write, optimize, upload local markdown, copy, sync, and export Feishu wiki pages.

Skill Files Location

This skill's supporting files are located relative to this SKILL.md:

• scripts/feishu_tool.py — Self-contained Python script for read/write/info operations (needs only .env)
• references/optimization-guide.md — Format comparison framework and known reference patterns
• references/conservative-edits.md — Guidelines for light-touch editing

Prerequisites

• .env file with credentials (checked in order):
  1. .env in the current directory
  2. ~/.config/feishu_tools/.env

  FEISHU_APP_ID=your_app_id
  FEISHU_APP_SECRET=your_app_secret
  

• Python packages: requests, python-dotenv

Data Locations

• Token cache: ~/.config/feishu_tools/token_cache.json
• Sync state: ~/log/feishu_tools/sync_logs/state/
• Sync logs: ~/log/feishu_tools/sync_logs/ (one log per sync run)

Install dependencies on first run:

pip install requests python-dotenv 2>/dev/null

Arguments

$ARGUMENTS should be: ACTION [ARGS...]

Determine the action from the user's intent:

upload command: /feishu upload [md_path] [parent_url]

• md_path may be relative (resolved from current working directory) or absolute
• parent_url is the Feishu wiki URL under which the new page will be created as a sub-page

Action: read

Read a Feishu wiki page and display its content as markdown.

python <skill-directory>/scripts/feishu_tool.py read SOURCE_URL

Options:

• --no-title — Omit the H1 title from output

The script outputs clean markdown to stdout (logs go to stderr). Display the content to the user. If they ask follow-up questions, answer based on the retrieved text.

Notes

• On first run, it may prompt for OAuth authorization — follow the printed URL
• Token is cached in ~/.config/feishu_tools/token_cache.json for subsequent runs
• Supports docx-type wiki pages only

Action: diff

Read two Feishu wiki pages as markdown and print a unified diff.

python <skill-directory>/scripts/feishu_tool.py diff LEFT_URL RIGHT_URL

Options:

• --no-title — omit the H1 title before diffing
• --context N — control unified diff context size (default: 3)
• --normalize — normalize markdown before diffing to reduce noisy differences

Recommended use:

• Compare a newly created page against a reference page before modifying the tool or skill
• Use --normalize when you want to focus on substantive markdown structure differences rather than trivial separator normalization (e.g. Unicode dashes in table separator rows)

Action: info

Show page metadata.

python <skill-directory>/scripts/feishu_tool.py info SOURCE_URL

Prints: title, node token, obj token, obj type, space ID, has_child.

Action: write

Create a new Feishu wiki page from markdown content.

1. Prepare the markdown content from the conversation or a file.
2. Write the optimized content to a temp file, then upload:

   # Step 1: Write content to a temp file
   UPLOAD_TMP=$(mktemp /tmp/feishu_upload_XXXXXX.md)
   cat > "$UPLOAD_TMP" << 'FEISHU_CONTENT_END'
   ## Section 1
   
   Content here...
   FEISHU_CONTENT_END
   
   # Step 2: Upload from file
   python <skill-directory>/scripts/feishu_tool.py write PARENT_URL \
     --title "Page Title" \
     --input-file "$UPLOAD_TMP"
   
   # Step 3: Clean up
   rm -f "$UPLOAD_TMP"
   

3. The script prints the new page URL to stdout. Share this URL with the user.

Options

• --heading-color — Auto-color heading backgrounds by relative depth: outermost → red/pink, then orange, yellow, green, blue, purple. Explicit {bg=N} on a heading always wins.
• --input-file FILE / -f FILE — Read markdown from FILE instead of stdin. Preferred over heredoc for large documents (avoids shell escaping issues).

Inline formatting

Notes

• New page is created as a child (sub-node) of the parent.
• If --title is omitted, title is extracted from the first H1.
• Always use << 'FEISHU_CONTENT_END' (quoted delimiter) to prevent variable expansion in the temp file write step.
• The --input-file approach avoids heredoc shell escaping issues (e.g. {red:...} markers containing {...} in LaTeX).
• Supported: headings, paragraphs, bold, italic, code, strikethrough, links, bullet/ordered lists, code blocks, blockquotes, dividers, tables (| col | col | pipe format), callout blocks, quote containers (|> prefix), LaTeX equations, images.
• Images: Use ![alt](path) in markdown. Pass --image-dir DIR to resolve relative image paths. Images are uploaded after block creation. If --image-dir is omitted, image lines are treated as text.

Action: upload

Upload a local markdown file to Feishu as a new sub-page, applying the same light-touch optimization rules as the optimize action before publishing.

Format: /feishu upload MD_PATH PARENT_URL

• MD_PATH — path to the local .md file (relative to CWD or absolute)
• PARENT_URL — Feishu wiki URL; the new page is created as its direct child

Core principle: The local file is the authority. Apply formatting improvements from the optimization guide, but do NOT rewrite the author's content, tone, or intent.

Workflow

Follow these 5 tasks in order:

Task 1: Read the Local Markdown File

Resolve the path:

• If MD_PATH starts with /, it is absolute — use as-is
• Otherwise, resolve relative to the current working directory

# Resolve relative path if needed
realpath MD_PATH

Read the file content. This is the document to upload.

Analyze carefully:

• Document title (first H1, or filename if no H1)
• Overall topic and purpose
• Author's writing style and tone
• Existing heading structure and hierarchy
• Content organization and flow
• Use of formatting (bold, lists, code blocks, tables, LaTeX, etc.)
• Metadata blocks (author, venue, date, etc.)
• Technical payload that must survive: numbers, formulas, systems, complexity, deployment facts, experiment settings, citations, caveats, mechanism details

Record your observations — you will need them in Task 4 to preserve the original character.

Task 2: Format Analysis

Read [references/optimization-guide.md](/references/optimization-guide.md) for the detailed comparison framework and known format conventions.

Reference Discipline:

• The optimization guide is a style reference, not a license to restyle the document wholesale
• Preserve the source document's macro-structure unless there is a clear formatting defect
• Do not renumber or deepen the heading hierarchy just to match the reference pattern if the source already has a stable hierarchy
• If an opening block, metadata block, or summary layout already works, prefer light cleanup over redesign
• Prefer blockquote-style callouts that round-trip correctly in exported markdown

Check the document against these specific format conventions:

Hard Constraints:

• Do not assume numbered headings are mandatory when the source already has a coherent hierarchy
• Exception — Chinese ordinal headings are always a defect: ## 一、, ## 二、, ## 三、… use Chinese characters that do NOT trigger the tool's blue-number coloring. Always convert to ## 1 Title, ## 2 Title… format. This is not optional.
• Do not force extra subsection levels simply because the reference is more granular
• All siblings at the same heading level must be consistently numbered or consistently unnumbered. A lone unnumbered heading (e.g., ## Cheatsheet) among numbered siblings must be assigned the next sequential number.
• Treat opening layout, metadata layout, and top-of-document summary layout as high-risk areas where over-editing is likely to regress the page
• Prefer blockquote-style callouts that round-trip correctly in exported markdown

Important: Only note FORMAT differences. Do not evaluate content topics.

Task 3: Content Review (Light Touch)

Read [references/conservative-edits.md](/references/conservative-edits.md) for detailed guidelines.

Fix These:

• Factual errors: Incorrect technical information, wrong version numbers, broken links
• Incomplete descriptions: Sentences that trail off, missing explanations, TODO/placeholder text
• Obvious typos: Spelling errors, grammar mistakes that change meaning
• Broken formatting: Unclosed markdown, inconsistent list indentation

Do NOT Change:

• Author's tone: If they write casually, keep it casual
• Content focus: Respect what the author chose to emphasize
• Technical opinions: If they recommend a tool or approach, keep it
• Original structure: Only adjust structure if it clearly conflicts with format conventions
• Level of detail: If the author was brief on a topic, respect that

Task 4: Generate Optimized Version

CRITICAL: The optimized document should be 80%+ identical to the original. Changes should be subtle improvements, not rewrites.

What to change:

1. Opening callout — Add a [!callout] block at the top if missing

   • Use [!callout icon=ICON bg=2 border=2] — choose an appropriate icon (e.g. gift, bulb, bookmark, pushpin, rocket, star)
   • Put the document's intro description AND paper/code links all inside the callout as child paragraphs
   • Example:

     > [!callout icon=gift bg=2 border=2]
     > 本文档...的简介文字。
     >
     > **Paper**: [Title](url)
     >
     > **Code**: [GitHub](url)
     >
     

   • If the source already has an intro |> quote container or a plain > blockquote that functions as the document summary (e.g., > 一句话总结: ...), move its text into the callout as a child paragraph and remove the original block

2. Heading restructuring — Fix numbering AND hierarchy when needed:

   • Apply continuous sequential numbering at all heading levels: ## 1, ## 2… for top-level; ### 1.1, ### 1.2… for second-level; #### 1.1.1, #### 1.1.2… for third-level. Never leave any heading level unnumbered if its parent level is numbered.
   • Number format: Always use ## 1 Title (number then space then title — no period after the number). The upload tool automatically colors the numeric prefix blue. Format ## 1. Title (period after number) will NOT trigger auto-blue coloring.
   • Heading groups: If multiple sections each restart at "1.", "2."… choose:
     • Elevate the group header: if a heading logically contains sub-items also at the same level, promote it one level up
     • Continuous renumber: if no clear group header, renumber all items sequentially
   • Level conflicts: if a heading that groups sub-sections is at the same level as those sub-sections, promote it one level
   • Renaming allowed: you MAY revise a heading's title when it's too generic — keep the core topic, just improve precision
   • Reordering allowed: you MAY reorder sections when the logical flow clearly improves (note each reorder in the summary)

3. Callouts and quote containers — use freely throughout the document

   • TL;DR blocks → always convert to blue callout: [!callout icon=bulb bg=2 border=2] (NOT a |> quote container)
   • "一句话总结" / "一句话定位" / "核心思想" / "关键结论" → normally convert to green callout: [!callout icon=pushpin bg=3 border=3] (NOT a |> quote container); exception: if they contain $...$, $$...$$, or multiple inline equations, use normal body text or a nearby summary subsection instead
   • Add |> quote containers for other key insights, important observations, counterintuitive findings, and critical design decisions — no upper limit
   • Add > 📌 **标题**: ... blockquotes for critical facts and must-not-miss design decisions
   • A well-formatted long document should have 5–15 callouts/quote containers spread across sections

   Feishu Callout Syntax Rules:

   • Use > [!callout icon=...] form, not a bare [!callout ...] line
   • Keep the callout marker and its body in the same blockquote group
   • If unsure whether a custom callout will round-trip correctly, use a plain > 📌 ... blockquote instead

   Formula Safety Rules:

   • Do not keep formula-bearing summaries inside blockquotes, callouts, or quote containers
   • If a summary sentence contains LaTeX, place it as a normal paragraph or a nearby summary subsection
   • If a sentence mixes prose and several formulas, prefer a normal paragraph
   • If the formula is the main payload, prefer a lead-in sentence plus a standalone display equation block

4. Code block language tags — Add missing language tags to bare code blocks

5. Formatting conventions

   • Bold key technical terms on first mention
   • Use inline code for function names, variables, file paths

6. Inline emphasis — MANDATORY

   You MUST add these — a document with no color markup is incomplete:

   • {red:text} / {red:**text**} — red text color, use liberally throughout the document. Every key conclusion, important value, critical fact, must-not-miss point should be red. A long technical paper needs 10–20 red instances across sections. {red:**...**} for the most critical items.
   • {green:text} / {green:**text**} — green background highlight for key technical concepts, system names, method names on first mention in body text (5–10 per document)

   Other emphasis:

   • {yellow:text}, {orange:text}, {blue:text}, {purple:text} — background highlights for secondary emphasis
   • **bold** — key technical terms, list lead-ins, first-mention important terms
   • *italic* — terms being defined, foreign phrases, titles

   Structural emphasis for scannability:

   • Bold structural signposts: Bold ALL "在...方面" / "在...上" phrases that introduce a topic shift — e.g., "在内存优化方面" → "在内存优化方面", "在通信方面" → "在通信方面". Also bold: "从...角度", "具体来说", "值得注意的是", "核心区别在于"
   • Bold enumeration lead-ins: When a paragraph lists items inline (A does X, B does Y, C does Z), bold each item name: "A does X, B does Y, C does Z"
   • Green-highlight enumerated technique names: When a paragraph enumerates multiple technical techniques with Chinese glosses (e.g., "通过 selective recomputation（选择性重计算）、fine-grained activation offloading（细粒度激活卸载）和 precision-aware optimizer"), apply {green:...} to each technique name on first mention: 通过 {green:selective recomputation}（选择性重计算）、{green:fine-grained activation offloading}（细粒度激活卸载）和 {green:precision-aware optimizer}
   • Red for full conclusions: Red should mark the complete actionable finding, not just a number. Bad: {red:199.5 GB}. Good: {red:将内存需求从 199.5 GB 降至 80 GB 以下}. Each section should have 1–2 red sentences.

   Rules:

   • Preserve ALL existing {red:...}, {green:...}, **bold**, *italic* exactly
   • Never mark entire paragraphs — but DO mark full key sentences/clauses that a reader must not miss
   • Red emphasis is reserved for conclusions and consequences, not routine explanatory clauses
   • Green emphasis is used on genuine first-mention concepts, not repeated on every prominent noun

7. Factual corrections — Fix identified errors from Task 3

8. Description completion — Flesh out incomplete sections

   • Add only information that is clearly implied or factually obvious
   • Do NOT fabricate details or add your own opinions

9. Ordered list numbering — Feishu does NOT auto-renumber ordered list items. If the source markdown uses 1. for every item (a common Markdown habit), all items render as "1." in Feishu. Always use explicit sequential numbers: 1., 2., 3., 4.…

10. Intelligent list conversion — Dense paragraphs that enumerate items should be broken into structured lists:

• When to convert: A paragraph listing 3+ items/features/components with descriptions, separated by 、/；/semicolons, or using "A: desc, B: desc, C: desc" structure
• Format: Bullet list with bold lead-ins: - **ItemName**: description
• When NOT to convert: Items are very short (1–2 words) with no descriptions — keep as inline list. Also keep as paragraph if the enumeration is embedded in narrative flow.

What NOT to change:

• Author's tone and voice (colorful language is intentional)
• Existing emphasis ({red:...}, bold)
• Section scope (don't merge or split sections)
• Technical examples and code snippets (preserve exactly)
• Author's analogies and explanations
• Length (don't pad sections)
• Author's personal insights or recommendations

Produce the complete optimized markdown. Do NOT output a diff — output the full document.

Task 4.5: Content Preservation Audit

Before proceeding to upload, check for:

• Dropped bullets or list items
• Shortened mechanism descriptions
• Removed numbers, formulas, complexity, thresholds
• Removed deployment/experiment/workload facts
• Removed citations or named systems
• Macro-structure drift: added or removed top-level sections, subsection splits, or heading renumbering not justified by a broken source
• Opening-layout drift: title-adjacent summary, author/meta block, and first visual block still feel like the source rather than a template rewrite

If any technical section is materially shorter, re-check it line by line.

Task 4.6: Emphasis Audit

Before proceeding to upload, check for:

• At least 1 red conclusion in each major section
• Green first-mention highlights where new concepts appear
• Bold structural anchors
• Yellow highlights for caveats/tradeoffs where appropriate
• Emphasis density still matches the source tone; remove highlights if the page starts to feel over-marked or noisier than the reference
• Red emphasis is reserved for conclusions and consequences, not routine explanatory clauses
• Green emphasis is used on genuine first-mention concepts, not repeated on every prominent noun

Task 4.7: Rendered-Layout Regression Check

Visually inspect the final markdown and reject it if any of these regressions appear:

• Opening callout or opening summary looks weaker than the source/reference
• Top metadata collapses into stray lines or duplicated blocks
• A clean source paragraph was turned into a noisier list, or a clean list into a denser paragraph
• Headings became more numerous or deeper without a clear readability win
• Emphasis feels materially louder than the source/reference
• Callout syntax is likely to render literally instead of as a Feishu callout

Task 5: Write to Feishu

Determine the page title:

• Use the document's first H1 heading if present
• Otherwise, derive a clean title from the filename (strip path, underscores → spaces, drop .md)

Determine the image directory:

• If the markdown file references images with relative paths (e.g., ![](figures/fig1.png)), set IMAGE_DIR to the directory containing the markdown file
• If images use absolute paths or the document has no images, omit --image-dir

Create a sibling upload file and write the optimized content to it:

UPLOAD_MD="${MD_PATH%.md}_upload.md"
cp "MD_PATH" "$UPLOAD_MD"
# Edit $UPLOAD_MD directly so it contains the final upload body.
# Important: remove the H1 title line from the body (title is passed via --title).

python <skill-directory>/scripts/feishu_tool.py write PARENT_URL \
  --heading-color \
  --image-dir "IMAGE_DIR" \
  --title "TITLE" \
  --input-file "$UPLOAD_MD"

Important notes:

• Always include --heading-color to auto-color headings by depth
• Include --image-dir pointing to the markdown file's parent directory when images are present
• Do NOT include the # Title H1 line in the content body. The title is set via --title. If H1 is in the body, heading depths shift by 1 and all headings get the wrong color.
• Keep the generated *_upload.md file — do not delete it so the upload artifact can be reviewed later
• The --input-file approach avoids shell escaping issues and enables image upload auto-retry

The script prints the URL of the newly created page. Share this URL with the user.

Post-upload verification (optional)

python <skill-directory>/scripts/feishu_tool.py read NEW_PAGE_URL

Summary Report

After completing all tasks, provide the user with:

1. URL of the new page
2. Changes made — brief list of formatting improvements applied
3. Confidence level — how confident you are in the changes

Action: optimize

Light-touch optimization of a Feishu wiki document: fix errors, complete descriptions, and slightly improve formatting — while preserving the original author's tone, style, and intent.

Core principle: The original document is the authority. The reference document only guides formatting structure. Never rewrite or restructure aggressively.

Output: A new wiki sub-page under the reference document containing the optimized version.

Arguments

• SOURCE_URL: The document to optimize (content source)
• DEST_URL: The well-formatted reference document (format guide only; new page created under this)

Workflow

Follow these tasks in order:

1. Read Source — Fetch and understand the source document
2. Read Reference — Fetch and analyze the reference document's format
3. Format Analysis — Compare structures and identify format gaps
4. Content Review — Identify factual errors, incomplete descriptions, minor issues
5. Generate Optimized Version — Apply light-touch improvements 5.5. Content Preservation Audit — Verify no content was dropped or shortened 5.6. Emphasis Audit — Verify color/bold density is appropriate 5.7. Rendered-Layout Regression Check — Verify no visual regressions
6. Write to Feishu — Create new sub-page with optimized content

Task 1: Read Source Document

python <skill-directory>/scripts/feishu_tool.py read SOURCE_URL

Save the full output. This is the document to optimize.

Analyze carefully:

• Overall topic and purpose of the document
• Author's writing style and tone (formal/informal, technical/accessible)
• Existing heading structure and hierarchy
• Content organization and flow
• Level of detail in each section
• Use of formatting (bold, lists, code blocks, etc.)
• Technical payload that must survive: numbers, formulas, systems, complexity, deployment facts, experiment settings, citations, caveats, mechanism details

Record your observations — you will need them in Task 5 to preserve the original character.

Task 2: Read Reference Document

python <skill-directory>/scripts/feishu_tool.py read DEST_URL

Save the full output. This is the format reference only — not a content source.

Analyze the FORMAT only:

• Heading hierarchy pattern (depth, naming conventions)
• Section organization template
• Formatting conventions (when bold is used, list styles, etc.)
• Content density and paragraph structure
• Use of structural elements (dividers, quotes, code blocks)

Task 3: Format Analysis

Read [references/optimization-guide.md](/references/optimization-guide.md) for the detailed comparison framework and known reference format patterns.

Reference Discipline:

• The optimization guide is a style reference, not a license to restyle the document wholesale
• Preserve the source document's macro-structure unless there is a clear formatting defect
• Do not renumber or deepen the heading hierarchy just to match the reference pattern if the source already has a stable hierarchy
• If an opening block, metadata block, or summary layout already works, prefer light cleanup over redesign
• Prefer blockquote-style callouts that round-trip correctly in exported markdown

Check the source document against these specific format conventions:

Hard Constraints:

• Do not assume numbered headings are mandatory when the source already has a coherent hierarchy
• Exception — Chinese ordinal headings are always a defect: ## 一、, ## 二、, ## 三、… use Chinese characters that do NOT trigger the tool's blue-number coloring. Always convert to ## 1 Title, ## 2 Title… format. This is not optional.
• Do not force extra subsection levels simply because the reference is more granular
• All siblings at the same heading level must be consistently numbered or consistently unnumbered. A lone unnumbered heading (e.g., ## Cheatsheet) among numbered siblings must be assigned the next sequential number.
• Treat opening layout, metadata layout, and top-of-document summary layout as high-risk areas where over-editing is likely to regress the page
• Prefer blockquote-style callouts that round-trip correctly in exported markdown

Important: Only note FORMAT differences. Do not compare content topics.

Task 4: Content Review (Light Touch)

Review the source document for issues that should be fixed regardless of format:

Fix These:

• Factual errors: Incorrect technical information, wrong version numbers, broken links
• Incomplete descriptions: Sentences that trail off, missing explanations, TODO/placeholder text
• Obvious typos: Spelling errors, grammar mistakes that change meaning
• Broken formatting: Unclosed markdown, inconsistent list indentation

Do NOT Change:

• Author's tone: If they write casually, keep it casual
• Content focus: If they emphasize certain topics, respect that emphasis
• Technical opinions: If they recommend a tool or approach, keep it
• Original structure: Only adjust structure if it clearly conflicts with the reference format
• Level of detail: If the author was brief on a topic, they may have had a reason

Read [references/conservative-edits.md](/references/conservative-edits.md) for detailed guidelines on what changes are appropriate.

Task 5: Generate Optimized Version

CRITICAL: Read this section carefully before writing.

The 80/20 Rule

The optimized document should be 80%+ identical to the original. Changes should be subtle improvements, not rewrites.

What to change:

1. Opening callout — Add a [!callout] block at the top if missing

   • Use [!callout icon=ICON bg=2 border=2] — choose an appropriate icon freely (e.g. gift, bulb, bookmark, pushpin, rocket, star)
   • Put the document's intro description AND paper/code links all inside the callout as child paragraphs (separated by blank > lines)
   • Example:

     > [!callout icon=gift bg=2 border=2]
     > 本文档...的简介文字。
     >
     > **Paper**: [Title](url)
     >
     > **Code**: [GitHub](url)
     >
     

   • If the source already has an intro |> quote container or a plain > blockquote that functions as the document summary (e.g., > 一句话总结: ...), move its text into the callout as a child paragraph and remove the original block

2. Heading restructuring — Fix numbering AND hierarchy when needed:

   • Apply continuous sequential numbering at all heading levels: ## 1, ## 2… for top-level; ### 1.1, ### 1.2… for second-level; #### 1.1.1, #### 1.1.2… for third-level. Never leave any heading level unnumbered if its parent level is numbered.
   • Number format: Always use ## 1 Title (number then space then title — no period after the number). The upload tool automatically colors the numeric prefix blue. Format ## 1. Title (period after number) will NOT trigger auto-blue coloring.
   • Heading groups: If multiple independent sections each restart at "1.", "2."…, choose a fix:
     • Elevate the group header: if a heading like ## 深度推导：… logically contains sub-items also at ##, promote it to # and demote sub-items to ##
     • Continuous renumber: if no clear group header exists, renumber all items sequentially (1, 2, 3, 4…)
   • Level conflicts: if a heading that groups several sub-sections is at the same ## level as those sub-sections, promote it one level up (## → #, ### → ##, etc.)
   • Renaming allowed: you MAY revise a heading's title when it's too generic or doesn't capture the actual scope — keep the core topic, just improve precision
   • Reordering allowed: you MAY reorder sections when the logical flow clearly improves (e.g., prerequisite concepts before dependent ones) — note each reorder in the summary report

3. Callouts and quote containers — use freely throughout the document

   • TL;DR blocks → always convert to blue callout: [!callout icon=bulb bg=2 border=2] (NOT a |> quote container)
   • "一句话总结" / "一句话定位" / "核心思想" / "关键结论" → normally convert to green callout: [!callout icon=pushpin bg=3 border=3] (NOT a |> quote container); exception: if they contain $...$, $$...$$, or multiple inline equations, use normal body text or a nearby summary subsection instead
   • Add |> quote containers for other key insights, important observations, counterintuitive findings, and critical design decisions — no upper limit
   • Add > 📌 **标题**: ... blockquotes for critical facts and must-not-miss design decisions
   • A well-formatted long document should have 5–15 callouts/quote containers spread across sections

   Feishu Callout Syntax Rules:

   • Use > [!callout icon=...] form, not a bare [!callout ...] line
   • Keep the callout marker and its body in the same blockquote group
   • If unsure whether a custom callout will round-trip correctly, use a plain > 📌 ... blockquote instead

   Formula Safety Rules:

   • Do not keep formula-bearing summaries inside blockquotes, callouts, or quote containers
   • If a summary sentence contains LaTeX, place it as a normal paragraph or a nearby summary subsection
   • If a sentence mixes prose and several formulas, prefer a normal paragraph
   • If the formula is the main payload, prefer a lead-in sentence plus a standalone display equation block

4. Code block language tags — Add missing language tags to bare code blocks

5. Formatting conventions — Apply reference patterns

   • Bold key technical terms on first mention
   • Use inline code for function names, variables, file paths

6. Inline emphasis — MANDATORY

   • Preserve ALL existing {red:...}, {green:...}, **bold**, *italic* from the source exactly
   • {red:text} / {red:**text**} — red text color, use liberally throughout (10–20× for a long technical paper). Mark key conclusions, important values, critical facts in every section.
   • {green:text} / {green:**text**} — green background highlight for key technical concepts/system names on first mention (5–10×)
   • **bold** — key technical terms, lead-in labels in lists
   • *italic* — terms being defined, foreign phrases, titles

   Structural emphasis for scannability:

   • Bold structural signposts: Bold ALL "在...方面" / "在...上" phrases that introduce a topic shift — e.g., "在内存优化方面" → "在内存优化方面", "在通信方面" → "在通信方面". Also bold: "从...角度", "具体来说", "值得注意的是", "核心区别在于"
   • Bold enumeration lead-ins: When a paragraph lists items inline, bold each item name
   • Green-highlight enumerated technique names: When a paragraph enumerates multiple technical techniques with Chinese glosses (e.g., "通过 A（中文A）、B（中文B）和 C"), apply {green:...} to each technique name on first mention
   • Red for full conclusions: Mark the complete finding, not just a number. Each section should have 1–2 red sentences.

   Rules:

   • Never mark entire paragraphs — but DO mark full key sentences/clauses that a reader must not miss
   • Red emphasis is reserved for conclusions and consequences, not routine explanatory clauses
   • Green emphasis is used on genuine first-mention concepts, not repeated on every prominent noun

7. Factual corrections — Fix identified errors from Task 4

8. Description completion — Flesh out incomplete sections

   • Add only information that is clearly implied or factually obvious
   • Do NOT fabricate details or add your own opinions

9. Ordered list numbering — Feishu does NOT auto-renumber ordered list items. If the source markdown uses 1. for every item (a common Markdown habit), all items render as "1." in Feishu. Always use explicit sequential numbers: 1., 2., 3., 4.…

10. Intelligent list conversion — Dense paragraphs that enumerate items should be broken into structured lists:

• When to convert: A paragraph listing 3+ items/features/components with descriptions, separated by 、/；/semicolons
• Format: Bullet list with bold lead-ins: - **ItemName**: description
• When NOT to convert: Items are very short with no descriptions, or the enumeration is embedded in narrative flow

What NOT to change:

• Author's tone and voice — Colorful language (e.g., 灵魂拷问, 降维打击, 一句话总结) is intentional. Keep it.
• Existing emphasis — If the author used {red:...} or bold on something, that was intentional; don't remove or move it
• Section scope — Don't merge or split sections; don't change what each section covers
• Technical examples and code snippets — Preserve exactly
• Author's analogies and explanations — Their way of explaining is part of the value
• Length — Don't pad sections to match reference length
• Author's personal insights or recommendations — These are the core value of the document

Generating the output:

Produce the complete optimized markdown. Do NOT output a diff — output the full document.

Task 5.5: Content Preservation Audit

Before proceeding to upload, check for:

• Dropped bullets or list items
• Shortened mechanism descriptions
• Removed numbers, formulas, complexity, thresholds
• Removed deployment/experiment/workload facts
• Removed citations or named systems
• Macro-structure drift: added or removed top-level sections, subsection splits, or heading renumbering not justified by a broken source
• Opening-layout drift: title-adjacent summary, author/meta block, and first visual block still feel like the source rather than a template rewrite

If any technical section is materially shorter, re-check it line by line.

Task 5.6: Emphasis Audit

Before proceeding to upload, check for:

• At least 1 red conclusion in each major section
• Green first-mention highlights where new concepts appear
• Bold structural anchors
• Yellow highlights for caveats/tradeoffs where appropriate
• Emphasis density still matches the source tone; remove highlights if the page starts to feel over-marked or noisier than the reference
• Red emphasis is reserved for conclusions and consequences, not routine explanatory clauses
• Green emphasis is used on genuine first-mention concepts, not repeated on every prominent noun

Task 5.7: Rendered-Layout Regression Check

Visually inspect the final markdown and reject it if any of these regressions appear:

• Opening callout or opening summary looks weaker than the source/reference
• Top metadata collapses into stray lines or duplicated blocks
• A clean source paragraph was turned into a noisier list, or a clean list into a denser paragraph
• Headings became more numerous or deeper without a clear readability win
• Emphasis feels materially louder than the source/reference
• Callout syntax is likely to render literally instead of as a Feishu callout

Task 6: Write to Feishu

Determine an appropriate title. Use the source document's original title, optionally with a suffix.

Determine the image directory:

• If the source document contains images, the images were fetched from Feishu and may need re-upload. If you saved images locally during read, set IMAGE_DIR to their directory.
• If no images are present, omit --image-dir.

Write the optimized content to a temp file, then upload:

# Step 1: Write optimized content to a temp file using the Write tool
# (write the full optimized markdown — NO H1 line — to this path)
UPLOAD_TMP=$(mktemp /tmp/feishu_upload_XXXXXX.md)

# Step 2: Upload from file (auto-retries failed image uploads)
python <skill-directory>/scripts/feishu_tool.py write DEST_URL \
  --heading-color \
  --image-dir "IMAGE_DIR" \
  --title "TITLE" \
  --input-file "$UPLOAD_TMP"

# Step 3: Clean up temp file
rm -f "$UPLOAD_TMP"

Important notes for writing:

• Always include --heading-color to auto-color headings by depth (required for visual formatting)
• Include --image-dir when the document contains ima

…(truncated)