lark-slides

slides (v1)

Quick Reference

CRITICAL, Before starting, you MUST use the Read tool to read ../lark-shared/SKILL.md. Authentication, permissions, and global parameters are all governed by lark-shared.

CRITICAL, Before generating any XML, you MUST use the Read tool to read xml-schema-quick-ref.md. Guessing XML structure from memory is prohibited.

CRITICAL, When creating a new presentation or performing a major page rewrite, you MUST first generate .lark-slides/plan/<deck-or-task-id>/slide_plan.json before generating XML. Create the corresponding directory first. See planning-layer.md for planning layer rules and intermediate artifact lifecycles. Small edits like replacing a single title or inserting a block are exempt.

CRITICAL, When creating a new presentation or performing a major page rewrite, you MUST read visual-planning.md before generating XML to ensure layout_type, visual_focus, and text_density actually change the page geometry, main visual, and text volume.

CRITICAL, When creating a new presentation or performing a major page rewrite, planning asset_need MUST follow asset-planning.md: perform metadata planning only, must include fallback_if_missing, and must not require real searching, downloading, or uploading of assets.

CRITICAL, After creation or major rewrite, you MUST perform explicit validation according to validation-checklist.md: read back full XML, verify page count and key elements, check for blank/broken pages, obvious overflows, and layout risks. For XML syntax and text overlap static checks, prioritize using scripts/xml_text_overlap_lint.py.

CRITICAL, During pre-creation self-checks or troubleshooting, you MUST check XML escaping, structure, shell truncation, image tokens, 3350001, and layout risks according to troubleshooting.md.

CRITICAL, If the user mentions "template", "apply template", "reference a certain theme/style/layout", or if the user requirement clearly falls into an existing scenario template (e.g., work report, product introduction, business plan, training, promotion report, etc.), you MUST first perform template search using scripts/template_tool.py search. By default, provide 2-3 best-matching template candidates for the user to choose from. After locking a template, use summarize to obtain theme and layout summaries. Only use extract to crop target page-type XML when a layout skeleton is needed. Do not read the full template XML directly.

[!NOTE] scripts/template_tool.py requires Python 3. references/template-index.json is a script cache/lightweight routing index, not a document for the agent to read by default. assets/templates/*.xml are machine resources and should only be accessed via script summary or extraction; do not read them in full.

CRITICAL, When using templates to generate or rewrite pages, you MUST summarize the target page type first; only extract when a specific layout skeleton is needed.

Editing existing slide pages: Prioritize using +replace-slide (block-level replacement/insertion, do not change page order). See lark-slides-edit-workflows.md for action selection and the full read-modify-write process.

Identity Selection

Feishu slides are typically the user's own content resources. By default, you should prioritize explicitly using --as user to perform slides-related operations, and always specify the identity explicitly.

• --as user (Recommended): Create, read, and manage presentations as the currently logged-in user. Complete user authorization before execution:

lark-cli auth login --domain slides

• --as bot: Use only when the user explicitly requests operation as an application, or when the bot needs to hold/create resources. When using bot identity, additionally confirm whether the bot actually has access permissions to the target presentation.

Execution Rules:

1. Creating, reading, adding/deleting slides, and continuing to edit an existing PPT based on a user-provided link should all default to --as user.
2. If permission is denied, first check if the bot identity was used by mistake; do not default to the bot.
3. Only switch to --as bot when the user explicitly requests "operate as application/bot identity" or when the current workflow involves the bot creating resources followed by collaboration authorization.

Pre-execution Checklist

Important: references/slides_xml_schema_definition.xml is the only correct source for this skill's XML protocol; other md files are only summaries of it and the CLI schema.

High-frequency read:

• xml-schema-quick-ref.md
• planning-layer.md (New / Major rewrite)
• visual-planning.md (New / Major rewrite)
• asset-planning.md (New / Major rewrite)
• validation-checklist.md (After creation / Major rewrite)

Read on demand:

• Creation: lark-slides-create.md
• Editing: lark-slides-edit-workflows.md, lark-slides-replace-slide.md
• Screenshot: lark-slides-screenshot.md
• Images: lark-slides-media-upload.md
• Flowcharts / Sequence diagrams / Architecture diagrams / Decorative patterns: lark-slides-whiteboard.md
• Icons: iconpark.md, scripts/iconpark_tool.py
• Templates: template-catalog.md, scripts/template_tool.py
• Troubleshooting: troubleshooting.md
• Full protocol: slides_xml_schema_definition.xml

Workflow

This is a presentation, not a document. Each slide is an independent visual frame; information density should be low, and layout should include whitespace.

Design Ideas

Do not generate slides without a sense of design. A plain white background + title + bullets can only serve as a minimalist temporary draft, not a formal delivery.

Before writing XML, determine the deck-level visual strategy in slide_plan.json:

• Thematic Color Palette: Colors must serve the theme, industry, and audience; do not default to blue business style. If the same set of colors works for another completely different theme, the color scheme is not specific enough.
• Primary/Secondary Ratio: Choose 1 primary color to carry about 60-70% of visual weight, 1-2 auxiliary colors for structure and partitioning, and 1 accent color used only for key numbers, conclusions, or action points. Do not give all colors the same weight.
• Background Consistency: Determine the background strategy for the entire deck first; keep the same brightness tone and base color system by default. Only section breaks, transitions, or emphasis pages should intentionally change the background, and changes must be made to look like part of the same design through the same primary color, texture, sidebar, or motif. Regardless of light or dark, ensure sufficient contrast for body text, icons, and lines.
• Unified Motif: Choose a reusable visual motif to run through the entire document, such as a thick sidebar, circular icon base, semi-bleed image area, numbered nodes, card top-left color blocks, or large numbers. Do not change the decorative language on every page.

Each page must have at least one visual element: image, icon, chart, table, process, comparison structure, large number, schematic, or abstract visual composed of shapes. Text boxes themselves do not count as main visuals.

Prioritize these page forms:

• Two-column structure: Text on left/image on right or vice versa, visual area occupies 35-45% width.
• Icon row: Icon on a color block or circular base, with a short title and one sentence of explanation on the right.
• 2x2 / 2x3 grid: Suitable for capabilities, modules, risks, action items; keep content in each cell at the same level.
• Semi-bleed visual: Image or abstract shape occupies the left/right half-screen, with text overlaid or aligned to the edge.
• Large number card: Use 60-72pt numbers for key metrics, accompanied by 10-14pt labels below.
• Comparison columns: Use side-by-side layout for before/after, plan A/B, problem/solution, with titles and baselines strictly aligned.
• Timeline/Flowchart: Use nodes and arrows to express steps; the flow direction must be visible at a glance.

Font and spacing suggestions:

• Titles 36-44pt, key conclusions can be larger; body text 14-18pt; notes 10-12pt.
• Body text defaults to left-aligned; use center-aligned only for covers, endings, or large number scenarios.
• Page margins at least 40px; keep 24-40px spacing between content blocks, and maintain consistency within the same deck.
• Card padding must leave real space; do not let text touch the edges. Consider text box padding when aligning shapes and text.

Common errors to avoid:

• Do not reuse the same title + three bullets layout for all pages.
• Do not use low-contrast text or icons, such as light gray text on a light background.
• Do not let decorative lines cross through text, or let footers, sources, or numbering crowd the main content.
• Do not represent missing assets as blank image boxes; must generate XML-native visuals according to fallback_if_missing.
• Do not leave template placeholder text, example company names, example dates, or original template content unrelated to the user's theme.

Creation Method Selection

[!WARNING] The risk of --slides '[...]' lies mainly in shell parameter passing, not just page count. Even for 1 page, if the XML is complex enough, two-step creation is recommended.

[!IMPORTANT] slides +create --slides creates page by page at the underlying level; it is not an atomic operation. If it fails midway, record the xml_presentation_id, read back to confirm current status, then continue to fix or append.

Template and Script Priority Workflow

See template-catalog.md for template details. Main workflow: search first, summarize after locking, extract only when a skeleton is needed; do not read full template XML directly or copy placeholder text.

python3 skills/lark-slides/scripts/template_tool.py search --query "<User requirement original text>" --limit 3
python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <Cover|Table of Contents|Section|Content|Ending>
python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <Page type> --out /tmp/template-slice.xml

Step 1: Requirement clarification & Knowledge reading
  - Clarify theme, audience, page count, style; handle template requirements according to "Template and Script Priority Workflow"
  - Read xml-schema-quick-ref.md; also read planning-layer.md, visual-planning.md, asset-planning.md for new/major rewrites

Step 2: Generate outline → User confirmation → Write slide_plan.json
  - Generate structured outline for user confirmation; if using a template, indicate which template it is based on
  - New/major rewrites must first create directory and write to `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
  - Execute plan fields, path naming, template boundaries, and `asset_need` structure according to planning-layer.md / asset-planning.md

Step 3: Generate XML according to slide_plan.json → Create
  - Consume plan page by page: key_message for main conclusion, layout_type for geometry, visual_focus for main visual, text_density for text volume
  - When real assets are missing, must use `fallback_if_missing` to generate XML-native fallback visuals; do not leave blank
  - Determine creation method according to "Creation Method Selection"; handle images, complex XML, escaping, and 3350001 troubleshooting according to lark-slides-create.md, media-upload.md, troubleshooting.md

Step 4: Review & Delivery
  - After creation, must use xml_presentations.get to read full XML and perform explicit validation according to validation-checklist.md, including XML text overlap check
  - Handle failures or partial successes according to troubleshooting.md; use `+replace-slide` for local issues
  - If no issues → Delivery: Inform user of presentation ID and access method

jq Command Template (for editing existing PPT)

+create --slides is recommended for new PPTs. The following jq template is suitable for appending pages to an existing presentation, avoiding manual escaping of double quotes:

# Append to the end
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
  <data>
    Place elements like shape, line, table, chart, whiteboard here
  </data>
</slide>' '{slide:{content:$content}}')"

# Insert before a specific page: before_slide_id must be in the --data body, at the same level as slide
# ⚠️ Do not put before_slide_id into --params, CLI will silently send it as an unknown query parameter, the server will ignore it, and the new page will go to the end
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
    '{slide:{content:$content}, before_slide_id:$before}')"

Gradients must use rgba() format with percentage stops, e.g., linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%). Using rgb() or omitting stops will cause the server to fallback to white.

Outline Template

Use the following format when generating an outline for user confirmation:

[PPT Title], [Positioning description], for [Target audience]

Template: [No template used / <category>/<template>.xml (Reason for recommendation)]

Page structure (N pages):
1. Cover page: [Title text]
2. [Page theme]: [Point 1], [Point 2], [Point 3]
3. [Page theme]: [Point description]
...
N. Ending page: [Ending text]

Style: [Color scheme], [Layout style]

Core Concepts

URL Format and Tokens

+replace-slide and +media-upload shortcuts automatically parse the above two URL types; when calling native APIs directly, you still need to parse wiki links manually.

Wiki Link Special Handling (Critical!)

Knowledge base links (/wiki/TOKEN) cannot be used directly as xml_presentation_id. Before calling native APIs directly, query the wiki node first, confirm node.obj_type == "slides", then use node.obj_token as the real presentation ID.

lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'

Shortcuts +replace-slide and +media-upload automatically parse /wiki/ URLs; you only need to perform this step manually when calling xml_presentations.* / xml_presentation.slide.*.

Resource Relationship

Wiki Space
└── Wiki Node (Knowledge base node, obj_type: slides)
    └── obj_token → xml_presentation_id

Slides (Presentation)
├── xml_presentation_id (Unique presentation identifier)
├── revision_id (Version number)
└── Slide (Slide page)
    └── slide_id (Unique page identifier)

Shortcuts and APIs

Shortcuts are high-level wrappers for common operations (lark-cli slides +<verb> [flags]). Use shortcuts when available.

Use native APIs when no shortcut covers the operation. High-frequency resources: xml_presentations.get to read full text; xml_presentation.slide.create/delete/get/replace to manage single pages.

lark-cli schema slides.<resource>.<method>   # Must check parameter structure before calling API
lark-cli slides <resource> <method> [flags] # Call API

Important: When using native APIs, you must run schema first to view the --data / --params parameter structure; do not guess field formats.

Core Rules

1. Plan before writing XML: When creating a new presentation or performing a major page rewrite, you must write to .lark-slides/plan/<deck-or-task-id>/slide_plan.json first; templates, styles, and outlines can only serve as planning input and cannot bypass the planning layer.
2. Creation process: Simple short XML (1-3 pages, simple structure, few special characters) can be created in one step using slides +create --slides '[...]'; for complex content, images/long Chinese text/nested quotes/many special characters, or more than 10 pages, default to creating a blank PPT with slides +create first, then add page by page using xml_presentation.slide.create.
3. <slide> direct children are only <style>, <data>, <note>: Text and graphics must be placed inside <data>.
4. Text expressed via <content>: Must use <content><p>...</p></content>; text cannot be written directly inside a shape.
5. Save key IDs: Subsequent operations require xml_presentation_id, slide_id, and revision_id.
6. Delete with caution: Deletion is irreversible, and at least one slide must remain.
7. Prioritize block-level replacement for editing existing pages: Use +replace-slide (block_replace / block_insert) to modify a single shape/img; do not rebuild the entire page. Only use slide.delete + slide.create when the entire page structure needs to be replaced.
8. <img src> can only use file_token uploaded to Feishu Drive; http(s) external links are prohibited: The Feishu slides renderer does not proxy external images; external src usually does not display or shows a broken image in PPT. The process must be: "Save image locally → Upload using slides +media-upload or @./path placeholder in +create --slides → Use file_token in <img src>". If the user provides a web image link, curl/download it to CWD first before the upload process; do not put external URLs directly into src. Images max 20 MB (slides upload API does not support chunked upload).

Note: If md content is inconsistent with slides_xml_schema_definition.xml or the output of lark-cli schema slides.<resource>.<method>, the latter two take precedence.