{"id":50519773,"url":"https://github.com/wellingfeng/lark-beautifier","last_synced_at":"2026-06-03T03:06:47.353Z","repository":{"id":359819355,"uuid":"1247215300","full_name":"wellingfeng/lark-beautifier","owner":"wellingfeng","description":"Codex skill and CLI for beautifying Feishu/Lark documents","archived":false,"fork":false,"pushed_at":"2026-05-23T16:19:49.000Z","size":3703,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T17:14:17.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wellingfeng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T03:14:39.000Z","updated_at":"2026-05-23T16:19:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wellingfeng/lark-beautifier","commit_stats":null,"previous_names":["wellingfeng/lark-beautifier"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/wellingfeng/lark-beautifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellingfeng%2Flark-beautifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellingfeng%2Flark-beautifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellingfeng%2Flark-beautifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellingfeng%2Flark-beautifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wellingfeng","download_url":"https://codeload.github.com/wellingfeng/lark-beautifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellingfeng%2Flark-beautifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33845819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T03:06:42.098Z","updated_at":"2026-06-03T03:06:47.346Z","avatar_url":"https://github.com/wellingfeng.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lark Beautifier\n\n[中文说明](README.zh-CN.md)\n\nLark Beautifier is a Node.js / TypeScript CLI and installable agent skill for turning plain Markdown into Feishu/Lark-ready documents. It keeps the source meaning intact while adding safer structure, stronger visual rhythm, Lark-flavored Markdown components, and optional Feishu write-back helpers.\n\nThe current v3 direction is visual-first: the formatter still handles typography, callouts, grids, and smart tables, but the skill can also orchestrate cover blocks, section dividers, timelines, action items, Feishu whiteboards, flowcharts, diagrams, generated images, infographics, and Xiaohongshu-style demo cards when the user asks for a richer document.\n\n## Before / After Examples\n\nThese examples use professional rendering-engine technical articles with text, tables, code snippets, rendered Mermaid flowcharts, and launch checklists. The article content was written against Epic's World Partition documentation, Android game performance guidance, the Vulkan Guide, and Arm mobile GPU best practices, then passed through `lark-beautifier` and the aligned screenshot comparison skill.\n\n### UE5 World Partition Technical Details\n\n![UE5 World Partition raw vs lark-beautifier comparison](doc/assets/readme/mobile-world-partition-comparison.png)\n\n### Mobile Rendering Pipeline Optimization\n\n![Mobile rendering pipeline raw vs lark-beautifier comparison](doc/assets/readme/mobile-render-pipeline-comparison.png)\n\n### Mobile Vulkan Rendering\n\n![Mobile Vulkan raw vs lark-beautifier comparison](doc/assets/readme/mobile-vulkan-comparison.png)\n\n## Features\n\n- Cleans Chinese typography without touching fenced code, inline code, links, image URLs, raw HTML, or existing Lark XML blocks.\n- Converts high-confidence cues into Feishu-style callouts and comparison grids.\n- Renders complex Markdown tables as smarter Lark-friendly tables with semantic column widths.\n- Separates risk mode from visual style: `safe | structured | bold` controls safety, while `theme` and `visualDensity` control presentation.\n- Adds reusable components such as `cover-banner`, `section-divider`, `timeline`, `before-after`, `quote-block`, `kpi-card-row`, and `action-items`.\n- Produces visual suggestions or drafts for whiteboards, Mermaid diagrams, image prompts, charts, and social cards.\n- Includes a dry-run-first Feishu write-back helper for real docs through Feishu OpenAPI and `@larksuiteoapi/lark-mcp` OAuth.\n\n## Install\n\n```bash\nnpm install\nnpm run build\n```\n\nRun from source:\n\n```bash\nnpm run dev -- examples/raw.md -o examples/beautified.md --mode structured\n```\n\nRun after build:\n\n```bash\nnode dist/cli.js input.md --output output.md --mode structured\n```\n\n## Recommended User Workflow\n\n1. Write or export the source document as Markdown. Keep code blocks, Mermaid diagrams, tables, timelines, and image references in the source when they matter.\n2. Run `lark-beautifier` locally and write the result to `tmp/` or another review location.\n3. Review the diff or output Markdown. Use `safe` for executive, legal, finance, and compliance-sensitive docs; use `structured` for normal team docs; use `bold` only for user-approved visual drafts.\n4. Create a new Feishu document from the beautified Markdown, or run the write-back helper in dry-run mode against an existing document.\n5. Apply to a live Feishu document only after the plan is reviewed. Use `--append` when you need to preserve existing content.\n\n```bash\n# 1. Generate a local beautified draft.\nnode dist/cli.js input.md \\\n  --output tmp/input-beautified.md \\\n  --mode structured \\\n  --theme auto \\\n  --components auto \\\n  --visual-density balanced\n\n# 2. Inspect changes before writing anywhere.\nnode dist/cli.js input.md --mode structured --diff\n\n# 3. Create a new Feishu document from the result.\nlark-cli docs +create --as bot \\\n  --title \"Beautified Document\" \\\n  --markdown \"@tmp/input-beautified.md\"\n```\n\nIf your Markdown references local images, Feishu cannot download those relative paths during `docs +create`. Insert local media after document creation:\n\n```bash\nlark-cli docs +media-insert --as bot \\\n  --doc \"https://www.feishu.cn/docx/...\" \\\n  --file doc/assets/readme/mobile-vulkan-comparison.png \\\n  --caption \"Mobile Vulkan comparison\"\n```\n\n## CLI Usage\n\n```bash\nnode dist/cli.js input.md \\\n  --output output.md \\\n  --mode structured \\\n  --theme technical-blue \\\n  --visual-density balanced \\\n  --components auto \\\n  --callouts auto \\\n  --grids auto \\\n  --tables smart \\\n  --whiteboards suggest \\\n  --enhancements suggest\n```\n\nRisk modes:\n\n| Mode | Purpose |\n| --- | --- |\n| `safe` | Conservative formatting for high-stakes documents. |\n| `structured` | Default mode for PRDs, meeting notes, technical plans, reports, retros, and project docs. |\n| `bold` | Stronger visual rhythm for user-approved rich documents; draft diagrams/prompts require explicit `--enhancements draft`. |\n\nVisual themes:\n\n| Theme | Best For |\n| --- | --- |\n| `technical-blue` | Engineering docs, architecture notes, API docs, release notes. |\n| `warm-product` | PRDs, product plans, user stories, launch docs. |\n| `clean-minimal` | Executive briefs, external docs, compliance-sensitive writing. |\n| `vivid-marketing` | Marketing drafts, social posts, event pages, demo scripts. |\n\nComponent controls:\n\n```bash\n# Let the analyzer choose high-confidence components.\nnode dist/cli.js input.md -o output.md --components auto --theme auto\n\n# Opt into specific components only.\nnode dist/cli.js input.md -o output.md --components cover-banner,section-divider,action-items\n\n# Inspect document signals as JSON.\nnode dist/cli.js input.md --analyze --check 2\u003e analysis.json\n```\n\nUseful validation flags:\n\n- `--check` exits non-zero if the file would change.\n- `--diff` prints a unified diff.\n- `--conservative` downgrades risky transformations.\n- `--to-lark-cli` prints a legacy `lark-cli docs +create` command for the generated output file.\n\n## Install As A Skill\n\nThe canonical skill package lives at:\n\n```text\nskills/lark-beautifier\n```\n\nInstall it for Codex:\n\n```bash\ngit clone https://github.com/wellingfeng/lark-beautifier.git\ncp -R lark-beautifier/skills/lark-beautifier ~/.codex/skills/\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/wellingfeng/lark-beautifier.git\nCopy-Item -Recurse lark-beautifier\\skills\\lark-beautifier $env:USERPROFILE\\.codex\\skills\\\n```\n\nThen ask Codex to use `$lark-beautifier`.\n\n## Agent Tutorial\n\nWhen using the skill from Codex or Claude Code, give the agent the source, the target risk level, and whether it may create visual artifacts or write back to Feishu.\n\nSafe local polish:\n\n```text\nUse $lark-beautifier to beautify docs/rendering-note.md for Feishu.\nUse structured mode, write the output to tmp/rendering-note-beautified.md,\nand do not update any live Feishu document yet.\n```\n\nVisual technical article:\n\n```text\nUse $lark-beautifier to turn this UE5 technical article into a rich Feishu\ndocument. Keep the technical meaning intact. Use cover/KPI cards, native\ntables, Mermaid flowcharts, a timeline, code blocks, and image placeholders.\nCreate a dry-run write-back plan only.\n```\n\nLive write-back with review:\n\n```text\nUse $lark-beautifier on this Feishu doc URL. First produce a dry-run plan\nunder tmp/. Show me the likely changes, table count, callout count, and\nwhether the default strategy would replace or append. Do not apply until I\nconfirm.\n```\n\nThe Claude Code mirror is kept in lockstep at:\n\n```text\n.claude/skills/lark-beautifier\n```\n\nProject-local Claude Code install:\n\n```bash\nmkdir -p .claude/skills\ncp -R lark-beautifier/.claude/skills/lark-beautifier .claude/skills/\n```\n\n## Feishu Write-Back\n\nThe write-back helper is dry-run-first. It can produce a plan from a local Markdown file without modifying the target document:\n\n```bash\nnode skills/lark-beautifier/scripts/lark-doc-writeback.mjs \\\n  --doc \"https://example.feishu.cn/docx/...\" \\\n  --input examples/beautified.md \\\n  --mode structured \\\n  --plan-output tmp/writeback-plan.json\n```\n\nAfter reviewing the plan, apply it explicitly:\n\n```bash\nLARK_MCP_APP_ID=\u003capp_id\u003e node skills/lark-beautifier/scripts/lark-doc-writeback.mjs \\\n  --doc \"https://example.feishu.cn/docx/...\" \\\n  --input examples/beautified.md \\\n  --mode structured \\\n  --apply\n```\n\nFor `--mode bold`, live write-back also requires `--confirm-bold`.\n\nFor first-time OAuth login, prefer the Lark MCP authorization-code flow:\n\n```bash\nnpx -y @larksuiteoapi/lark-mcp login -a \u003capp_id\u003e -s \u003capp_secret\u003e -p 8765 --host 127.0.0.1\n```\n\nDo not commit app secrets, access tokens, refresh tokens, or local OAuth storage.\n\n## Reproducing The README Comparisons\n\nThe README screenshots were generated with this pipeline:\n\n1. Draft raw rendering-engine Markdown articles under `tmp/readme-demo/`.\n2. Create raw Feishu documents with `lark-cli docs +create --as bot --markdown @tmp/readme-demo/\u003carticle\u003e-raw.md`.\n3. Beautify the Markdown with `lark-beautifier`.\n4. Create beautified Feishu documents with `lark-cli docs +create --as bot --markdown @tmp/readme-demo/\u003carticle\u003e-beautified.md`.\n5. Generate paragraph-aligned long comparison images with `$aligned-screenshot-compare`.\n\nCommands:\n\n```bash\nnode tools/generate-readme-demo.mjs\n\nnode skills/lark-beautifier/scripts/beautify.mjs \\\n  tmp/readme-demo/ue5-world-partition-raw.md \\\n  --output tmp/readme-demo/ue5-world-partition-beautified.md \\\n  --mode structured \\\n  --theme technical-blue \\\n  --components auto \\\n  --visual-density balanced \\\n  --whiteboards off \\\n  --enhancements off\n\nlark-cli docs +create --as bot \\\n  --title \"UE5 World Partition Technical Details (Raw)\" \\\n  --markdown \"@tmp/readme-demo/ue5-world-partition-raw.md\"\n\nlark-cli docs +create --as bot \\\n  --title \"UE5 World Partition Technical Details (Beautified)\" \\\n  --markdown \"@tmp/readme-demo/ue5-world-partition-beautified.md\"\n\nnode skills/aligned-screenshot-compare/scripts/align-compare.mjs \\\n  --left tmp/readme-demo/ue5-world-partition-raw.md \\\n  --right tmp/readme-demo/ue5-world-partition-beautified.md \\\n  --left-title \"Raw Feishu document\" \\\n  --right-title \"lark-beautifier output\" \\\n  --out-html tmp/readme-demo/ue5-world-partition-compare.html \\\n  --out-png doc/assets/readme/mobile-world-partition-comparison.png \\\n  --presentation\n```\n\nRepeat the same commands for `mobile-render-pipeline` and `mobile-vulkan`. Source references:\n\n- Epic Games: [World Partition in Unreal Engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-in-unreal-engine), [World Partition HLOD](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition---hierarchical-level-of-detail-in-unreal-engine), and [World Partition Data Layers](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition---data-layers-in-unreal-engine).\n- Android Developers: [Optimize your game](https://developer.android.com/games/optimize), [Android Frame Pacing](https://developer.android.com/games/sdk/frame-pacing), and [Android GPU Inspector](https://developer.android.com/agi).\n- Khronos Group: [Vulkan Guide](https://docs.vulkan.org/guide/latest/).\n- Arm: [Mali GPU Best Practices](https://developer.arm.com/documentation/101897/latest).\n\n## Development\n\n```bash\nnpm test\nnpm run check\nnpm run build\nnpm run lint:md\nnpm run check:skills\nnode skills/lark-beautifier/scripts/self-check.mjs\nnpm run package:skill\n```\n\nThe canonical skill source is `skills/lark-beautifier`. After changing it, run:\n\n```bash\nnpm run sync:skills\nnpm run check:skills\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwellingfeng%2Flark-beautifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwellingfeng%2Flark-beautifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwellingfeng%2Flark-beautifier/lists"}