feat: support whiteboard file inputs in docs XML by SunPeiYang996 · Pull Request #1784 · larksuite/cli

SunPeiYang996 · 2026-07-07T11:44:36Z

Summary

Adds local file expansion for docs XML whiteboard blocks so agents can reference SVG, Mermaid, and PlantUML files with @ paths before sending content to Docs AI.

Changes

Expand file references from path="@..." or body @file into inline whiteboard content.
Aggregate missing whiteboard file errors after scanning all blocks.
Document the new file-input shortcuts in lark-doc XML and whiteboard guidance.

Test Plan

gofmt -l shortcuts/doc/html5_block_resources.go shortcuts/doc/html5_block_resources_test.go
go test ./shortcuts/doc -run "TestDocsCreateV2(WhiteboardFileInputs|WhiteboardFileInputReportsAllMissingPaths|HTML5BlockReferenceMapFromPath|HTML5BlockPathReadFailure)"
go test ./shortcuts/doc
lark-cli E2E via ccm-e2e-check exec-cli (bot/user 7/7 Pass; report gate passed)
skill-creator quick_validate.py skills/lark-doc (blocked by existing skills/lark-doc/SKILL.md frontmatter version; PR intentionally leaves SKILL.md unchanged)

E2E Result

Bot identity E2E: 4/4 Pass on BOE via isolated ccm dev env.
User identity E2E: 3/3 Pass on BOE via isolated ccm dev env.
Missing-file aggregation validation: Pass.
Report gate: passed.
Workflow status: REQ_ID=lark-cli-whiteboard-at-files-pr1784 recorded as passed.
Local Markdown report: /Users/bytedance/.ccm-harness/worktrees/lark-cli-whiteboard-at-files/larksuite_cli/.lark-cli-e2e-test/reports/pr-1784-whiteboard-at-files/report.md
Local HTML report: /Users/bytedance/.ccm-harness/worktrees/lark-cli-whiteboard-at-files/larksuite_cli/.lark-cli-e2e-test/reports/pr-1784-whiteboard-at-files/report.html
Structured result: /Users/bytedance/.ccm-harness/worktrees/lark-cli-whiteboard-at-files/larksuite_cli/.lark-cli-e2e-test/reports/pr-1784-whiteboard-at-files/result.json

Related Issues

None

Summary by CodeRabbit

New Features
- Added support for loading whiteboard content from local files and inlining it into document writes.
- Expanded whiteboard handling for SVG, Mermaid, and PlantUML content, including inline file references.
Bug Fixes
- Improved validation for whiteboard inputs and path formats.
- Better error reporting when multiple file-backed whiteboards are missing or invalid, including across markdown code fences.
Documentation
- Updated whiteboard usage examples to show local file-based input options.

coderabbitai · 2026-07-07T11:46:17Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cd19d3cf-38c7-45b5-bfac-485d7fae16ba

📥 Commits

Reviewing files that changed from the base of the PR and between ab807a3 and b132798.

📒 Files selected for processing (2)

shortcuts/doc/html5_block_resources.go
shortcuts/doc/html5_block_resources_test.go

🚧 Files skipped from review as they are similar to previous changes (1)

shortcuts/doc/html5_block_resources.go

📝 Walkthrough

Walkthrough

Adds a whiteboard file-input inlining feature to Docs V2 write content preparation: <whiteboard> elements referencing local SVG/mermaid/plantUML files via path or inline @file bodies are validated and rewritten with inlined file contents before HTML5-block rewriting. Includes supporting tag parsing/rendering helpers, tests, and documentation updates.

Changes

Whiteboard inlining feature

Layer / File(s)	Summary
Whiteboard constants, regex, and tag struct `shortcuts/doc/html5_block_resources.go`	Adds `<whiteboard>` tag/attribute constants, a regex to match self-closing and paired whiteboard elements, and a `whiteboardStartTag` struct.
Docs V2 write pipeline integration `shortcuts/doc/html5_block_resources.go`	Calls `prepareWhiteboardWriteContent` before `prepareHTML5BlockWriteContent` in `prepareDocsV2WriteInput`.
Core whiteboard rewriting logic `shortcuts/doc/html5_block_resources.go`	Adds `prepareWhiteboardWriteContent`, `rewriteWhiteboardFileRefs`/`rewriteWhiteboardFileRef`, tag/body parsing helpers, `readWhiteboardPath` with path/extension validation, and aggregated validation error handling for markdown fence-aware rewriting.
Start tag parsing, attribute, and render helpers `shortcuts/doc/html5_block_resources.go`	Adds `parseWhiteboardStartTag`, `attr`, `removeAttrs`, `setAttr`, `render`, and `escapeXMLText` for serializing and escaping rewritten `<whiteboard>` tags.
Tests and documentation updates `shortcuts/doc/html5_block_resources_test.go`, `skills/lark-doc/references/lark-doc-whiteboard.md`, `skills/lark-doc/references/lark-doc-xml.md`	Adds tests for successful file inlining and aggregated missing-path failures, plus documentation describing `path`/`@file` whiteboard inputs and inline expansion behavior.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant prepareDocsV2WriteInput
  participant prepareWhiteboardWriteContent
  participant cmdutil

  Caller->>prepareDocsV2WriteInput: submit doc content
  prepareDocsV2WriteInput->>prepareWhiteboardWriteContent: rewrite whiteboard tags
  prepareWhiteboardWriteContent->>prepareWhiteboardWriteContent: parse tag, validate path/body/type
  prepareWhiteboardWriteContent->>cmdutil: ReadInputFile(path)
  cmdutil-->>prepareWhiteboardWriteContent: file contents
  prepareWhiteboardWriteContent-->>prepareDocsV2WriteInput: inlined content
  prepareDocsV2WriteInput-->>Caller: rewritten content

Suggested reviewers: syh-cpdsss

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly summarizes the main change: support for whiteboard file inputs in docs XML.
Description check	✅ Passed	The description follows the template and includes summary, changes, test plan, and related issues.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch sun/whiteboard-at-file-inputs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-07-07T11:49:55Z

Codecov Report

❌ Patch coverage is 72.64957% with 64 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.39%. Comparing base (f0b6f35) to head (b132798).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/doc/html5_block_resources.go	72.64%	44 Missing and 20 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1784      +/-   ##
==========================================
- Coverage   74.46%   74.39%   -0.08%     
==========================================
  Files         855      857       +2     
  Lines       88568    89185     +617     
==========================================
+ Hits        65954    66350     +396     
- Misses      17543    17712     +169     
- Partials     5071     5123      +52

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/doc/html5_block_resources_test.go`:
- Around line 465-492: The test
TestDocsCreateV2WhiteboardFileInputReportsAllMissingPaths only asserts
substrings from err.Error(), but it should verify the typed problem metadata
instead. Update it to use errs.ProblemOf on the aggregated whiteboard-path error
returned by runDocsCreateShortcut, and assert the correct category, subtype, and
param values for each missing whiteboard path while also checking the underlying
cause is preserved. Confirm the exact metadata used by the production whiteboard
error path so the assertions match the real aggregated error shape.

In `@shortcuts/doc/html5_block_resources.go`:
- Around line 262-276: The segment handling in applyOutsideCodeFences currently
stops processing later markdown segments after the first rewrite error, so only
the first missing-whiteboard group is reported. Update the logic around the
rewrite callback to keep scanning every outside-code-fence segment, collect any
rewriteErr values instead of returning early, and aggregate or combine them
after applyOutsideCodeFences finishes in html5_block_resources.go.

In `@skills/lark-doc/references/lark-doc-whiteboard.md`:
- Around line 61-62: The whiteboard docs currently mention only the SVG
file-based path form in the <whiteboard> examples, but they should also document
the new body form for local SVG files. Update the examples around the existing
whiteboard SVG/PlantUML guidance to include the <whiteboard
type="svg">`@diagram.svg`</whiteboard> usage alongside the existing <whiteboard
type="svg" path="`@diagram.svg`"></whiteboard> and related PlantUML examples, so
the entry point is fully covered.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8dadf75d-a56c-4cde-8511-2aba419af67c

📥 Commits

Reviewing files that changed from the base of the PR and between 6f95c5e and d8cb216.

📒 Files selected for processing (4)

shortcuts/doc/html5_block_resources.go
shortcuts/doc/html5_block_resources_test.go
skills/lark-doc/references/lark-doc-whiteboard.md
skills/lark-doc/references/lark-doc-xml.md

github-actions · 2026-07-07T11:50:44Z

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@b1327981cc5eec4c2f3ee296f1ffa8eace78e0c7

🧩 Skill update

npx skills add larksuite/cli#sun/whiteboard-at-file-inputs -y -g

feat: support whiteboard file inputs in docs XML

d8cb216

github-actions Bot added domain/ccm PR touches the ccm domain size/L Large or sensitive change across domains or core paths labels Jul 7, 2026

coderabbitai Bot reviewed Jul 7, 2026

View reviewed changes

Comment thread shortcuts/doc/html5_block_resources_test.go

Comment thread shortcuts/doc/html5_block_resources.go Outdated

Comment thread skills/lark-doc/references/lark-doc-whiteboard.md Outdated

SunPeiYang996 added 3 commits July 7, 2026 20:32

docs: prefer path syntax for whiteboard file inputs

ab807a3

docs: keep lark-doc skill metadata unchanged

a365b58

fix: aggregate whiteboard path errors across markdown

b132798

fangshuyu-768 approved these changes Jul 8, 2026

View reviewed changes

SunPeiYang996 merged commit 9a6ba41 into main Jul 8, 2026
40 checks passed

SunPeiYang996 deleted the sun/whiteboard-at-file-inputs branch July 8, 2026 03:18

This was referenced Jul 8, 2026

chore: release v1.0.67 #1808

Merged

chore: release v1.0.68 #1809

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: support whiteboard file inputs in docs XML#1784

feat: support whiteboard file inputs in docs XML#1784
SunPeiYang996 merged 4 commits into
mainfrom
sun/whiteboard-at-file-inputs

SunPeiYang996 commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

codecov Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

SunPeiYang996 commented Jul 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test Plan

E2E Result

Related Issues

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

codecov Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 PR Preview Install Guide

🧰 CLI update

🧩 Skill update

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SunPeiYang996 commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

codecov Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading