{
  "name": "lark-native-block-migration",
  "description": "Inventory, plan, execute, resume, and verify high-fidelity cross-tenant Lark/Feishu document migrations using native blocks.",
  "path": "lark-native-block-migration",
  "category": "feishu",
  "tags": [
    "lark",
    "feishu",
    "migration",
    "docx",
    "native-blocks"
  ],
  "author": "alanzeng",
  "version": "1.0.0",
  "source": "custom",
  "files": [
    "SKILL.md",
    "agents/openai.yaml",
    "references/artifacts.md",
    "references/fidelity.md",
    "scripts/init_run.py",
    "scripts/verify_artifacts.py"
  ],
  "install": "npx -y skills add https://skill.alanzeng.com --skill lark-native-block-migration --yes",
  "raw_url": "https://skill.alanzeng.com/skills/lark-native-block-migration/SKILL.md",
  "github_url": "https://github.com/alanzeng423/skill-hub/tree/main/skills/lark-native-block-migration",
  "body": "# Lark/Feishu Native Block Migration\n\nMigrate semantic document structures with Lark CLI and native APIs. Do not use DOCX export/import as the primary path for Docx content.\n\n## Required companion skills\n\nRead `lark-shared`, `lark-doc`, `lark-wiki`, and `lark-drive` before acting. Read `lark-sheets` or `lark-base` when those resources occur. Use `lark-openapi-explorer` only when the CLI lacks a required native operation.\n\n## Inputs\n\nResolve or ask for:\n\n- source and target Lark CLI profiles;\n- source roots: Wiki/Doc URLs, node tokens, or My Library selections;\n- target Wiki parent or My Library root;\n- inclusion/exclusion rules;\n- required treatment for unsupported blocks;\n- a fresh run directory outside the skill folder.\n\nNever write tenant domains, tokens, user IDs, or credentials into this skill. Store run-specific values only in the run directory.\n\n## Safety contract\n\nSplit every new migration into two phases.\n\n1. Perform read-only discovery and present the exact migration list, object counts, unsupported features, storage estimate where available, and fidelity plan.\n2. Wait for explicit user approval before creating, importing, moving, overwriting, or deleting target objects.\n\nTreat the source as read-only. Never delete the source. Never clean up target artifacts unless the user separately approves the exact deletion list. Take a target-parent snapshot before writes. Prefer a new empty target subtree so rollback means deleting only mapped target nodes.\n\n## Workflow\n\n### 1. Preflight identities and permissions\n\n- Run auth status for both profiles as user and record domain, user identity, scopes, and token health.\n- Confirm the source and target profiles are not accidentally reversed.\n- Resolve source roots and target parent metadata.\n- Check target write permission and quota before migration.\n\n### 2. Build a complete inventory\n\n- Recursively enumerate every selected source node with pagination.\n- Record `node_token`, `obj_token`, `obj_type`, title, parent, depth, path, child flag, URL, icon, and creation/update metadata when exposed.\n- Fetch every Docx in full detail. Count structural tags and extract media, attachments, whiteboards, Sheet/Base blocks, document references, tasks, synced blocks, and unsupported plugin blocks.\n- Deduplicate resources by source token without deduplicating directory nodes.\n- Apply exclusions to a separate filtered inventory; preserve the original inventory.\n- Stop if pagination, permissions, or fetch failures make the inventory incomplete.\n\nInitialize a run directory with `scripts/init_run.py`. Use the artifact schemas in [artifacts.md](references/artifacts.md).\n\n### 3. Produce the plan\n\nPresent:\n\n- the full source tree and total count by object type;\n- excluded paths and reason;\n- native-preservation strategy for each block class;\n- explicit semantic degradations;\n- expected temporary local storage and target storage impact;\n- execution order, validation gates, and rollback boundary.\n\nUse [fidelity.md](references/fidelity.md) for the preservation matrix. Do not claim “完全一致” when a block must be rasterized, flattened, or converted to a link/card.\n\n### 4. Create target skeletons top-down\n\n- Sort filtered inventory by depth and path.\n- Create Docx/Wiki nodes under the mapped target parent.\n- Export/import object types that have no native cross-tenant copy, then move them into the target Wiki hierarchy.\n- Append one mapping record immediately after each successful creation. Never defer the mapping write.\n- Make creation idempotent: skip only a source node with a confirmed live mapped target.\n- Preserve icons through the native icon field/API after node creation; verify them separately from titles.\n\n### 5. Transform Docx content\n\n- Fetch native XML/block content from the source.\n- Rewrite in-scope internal document references with the node/object mapping.\n- Replace cross-tenant resource tokens with deterministic placeholders before writing content.\n- Preserve supported native structure: headings, paragraphs, rich text, lists, quotes, callouts, code, equations, tables, checkboxes, columns/grids, bookmarks, and dividers.\n- Keep out-of-scope links as source hyperlinks and report them.\n- Record every transformation and degradation per document.\n\n### 6. Migrate resources\n\n- Images and attachments: download from the source profile and upload/insert into the mapped target Docx. Retain original filename and presentation mode when supported.\n- Embedded Sheets: export/import the workbook, validate sheet order/titles, map source to target workbook/sheet IDs, then insert a native Sheet block. Expect the Docx insertion step to create another private workbook token; verify the final block does not reference the source tenant.\n- Embedded Bases: export/import the Base and use a supported native embedded block or document reference card. Report any loss of view/dashboard/workflow behavior.\n- Whiteboards: prefer native structural export/import if supported. Otherwise insert a labeled visual snapshot and report that editability was lost.\n- Tasks, synced blocks, plugin/readonly blocks: preserve native semantics only when cross-tenant APIs support them; otherwise apply the user-approved degradation.\n\nAfter insertion, remove placeholders and scan all target Docx content for leftovers.\n\n### 7. Resume and repair safely\n\n- Keep append-only NDJSON journals for skeleton, content, resource, icon, and verification stages.\n- Determine completion from the latest record for a stable source/target key.\n- Retry failed stages only; never recreate successful target nodes.\n- When a target object disappeared or was manually moved, inspect it before deciding whether to repair the map or recreate it.\n\n### 8. Verify by reading the target back\n\n- Recursively inventory the target subtree.\n- Compare node count, object type, title, icon, parent relationship, and exact child sets.\n- Fetch each target Docx and compare structural block counts and resource counts against the source.\n- Assert that attachments are uploaded, media placeholders are absent, and no in-scope source tokens remain.\n- Validate imported Sheet/Base metadata and mapped IDs.\n- Produce machine-readable JSON plus a concise Markdown report listing pass/fail per document and every approved degradation.\n- Do not declare completion while any required node is missing or any unexpected degradation is unresolved.\n\nRun `scripts/verify_artifacts.py RUN_DIR` for local artifact consistency before the final report. This complements, but does not replace, live target read-back.\n\n## Completion report\n\nReport source/target roots, mapped counts by type, verified documents, media/resource counts, icons verified, exclusions, failures, degradations, storage-heavy attachments, and rollback scope. Link the destination root and any failed document directly.",
  "frontmatter": {
    "name": "lark-native-block-migration",
    "description": "Inventory, plan, execute, resume, and verify high-fidelity cross-tenant migration of Lark/Feishu Docx trees, My Library directories, and Wiki hierarchies using native document blocks. Use when moving Lark or Feishu cloud documents between domains/profiles while preserving titles, parent-child structure, text formatting, images, attachments, icons, embedded Sheets/Bases, and internal links; also use for migration dry-runs, repair, or post-migration fidelity audits."
  }
}