Feishu Block Surgery

Use this skill when the user gives a Feishu Docx URL/token and wants targeted edits to an existing document. Prefer preserving the current structure and changing only the requested blocks.

Do not use it for Sheets/Base/Slides work, brand-new documents with no existing structure, or summarize-only requests.

Workflow

1. Confirm the doc URL/token, target sections, and whether the user wants preview-first behavior.
2. Check auth:

lark-cli auth status --verify

3. Fetch the current structure before editing:

lark-cli docs +fetch --api-version v2 --doc "$DOC" --scope outline --detail with-ids

4. Narrow to the smallest useful scope:

lark-cli docs +fetch --api-version v2 --doc "$DOC" --scope section --start-block-id <block_id> --detail full
lark-cli docs +fetch --api-version v2 --doc "$DOC" --scope keyword --keyword "<text>" --detail with-ids

5. Pick the lightest edit form:

   • Use block_replace for targeted table/section edits.
   • Use block_insert_after, block_move_after, and block_delete for local layout adjustment.
   • Use full overwrite --doc-format xml only when the user explicitly wants a structural rewrite or the doc is too rough to patch safely.

6. Apply edits incrementally:

lark-cli docs +update --api-version v2 --doc "$DOC" --command block_replace --block-id <block_id> --content @content.xml

For overwrite flows, fetch the current revision_id and pass it explicitly:

lark-cli docs +update --api-version v2 --doc "$DOC" --command overwrite --doc-format xml --content @file.xml --revision-id <revision_id>

7. For attachments, upload from the artifact directory and then move the resulting file block into place:

cd /path/to/artifacts
lark-cli docs +media-insert --api-version v2 --doc "$DOC" --file ./artifact.zip --type file

8. Re-fetch the touched section/table and verify remote state.

User Preferences Captured

• Keep the original table/section skeleton unless the user asks for a redesign.
• Prefer concrete, project-specific Chinese wording over generic abstractions.
• When the user says "先不用改源文件", stage or show the draft before remote writes.
• If private platform/bot access fails but user-level lark-cli works, use user auth instead of forcing the private bot path.
• Attachment placement matters: files should end up in the requested table/section, not merely appended somewhere in the document.

Pitfalls

• Unknown docs +update flags: use documented lark-cli v2 flags only.
• docs +media-insert rejects absolute paths: cd to the artifact directory and pass a relative path.
• Uploading attachments before planning placement often leaves them outside the target table; upload, note block IDs, then move.
• Full overwrite can damage structure; use it only when the user wants a full rewrite.

Output

Report the exact changed sections, attachment placement, and verification method. Include the new revision ID when an overwrite or revision-sensitive update was used.