lark-doc-reviser

Read unresolved comments in a Feishu (Lark) document and apply targeted edits block-by-block based on those comments. Use when the user shares a Feishu doc U...

Security Scan

The skill's code and SKILL.md are consistent with a Feishu/Lark doc comment editor, but the package metadata fails to declare the required lark-cli binary and the workflow writes persistent files — review and validate lark-cli usage and local file writes before installing.

Purpose & Capability

The skill's name, description, SKILL.md, and bundled scripts all target Feishu (Lark) document comment reading and patching. However, the registry metadata lists no required binaries while the SKILL.md and every script depend on the external 'lark-cli' tool and an authenticated session. This metadata omission is an inconsistency that should be corrected/confirmed.

Instruction Scope

Runtime instructions and scripts limit actions to: (1) calling lark-cli to fetch blocks and unresolved comments, (2) producing and writing a workspace JSON state file, (3) calling lark-cli to PATCH blocks, and (4) calling lark-cli to mark comments resolved. The instructions do not read unrelated system files or send data to third-party endpoints beyond lark-cli API calls. They explicitly advise manual handling for structural operations that require other APIs.

Install Mechanism

There is no install spec (instruction-only style) which minimizes install-time risk. The package does include three Python scripts that will be written to disk when the skill is installed or bundled — this is expected but worth noting. The SKILL.md requires lark-cli but no automated install or link to a trusted release is provided.

Credentials

The skill requests no environment variables or credentials in metadata and the scripts rely on the user's existing lark-cli authentication (no secrets are requested by the skill). This is proportionate for a tool that calls the user's Lark account via lark-cli. There are no unexpected credential requests or unrelated env access.

Persistence & Privilege

The skill does write state files to a workspace directory (SKILL.md instructs 'Always save to workspace'), but it does not request always:true, does not claim permanent global presence, and does not modify other skills or system-wide agent settings. Persisted files may contain document state and should be managed by the user.

What to consider before installing

This skill appears to do what it says (read unresolved Feishu/Lark comments and update blocks via lark-cli), but before installing or running it, do the following: (1) Confirm you have lark-cli installed and authenticated locally — the SKILL.md and scripts require it even though the skill metadata doesn't declare it. (2) Inspect the scripts (they are included) and run them in an isolated environment or with non-sensitive test docs first. (3) Be aware the tool writes workspace/<token>_state.json files that persist document state; store or delete these files if they contain sensitive content. (4) Understand that running the patch and resolve scripts will modify and mark comments resolved in your live documents — verify patches before applying. (5) If you need higher assurance, ask the publisher to update metadata to declare the lark-cli dependency and provide guidance about required lark-cli permissions or scopes.

Workflow

Step 1 — Fetch doc state

python3 scripts/fetch_doc.py <doc_url_or_token> --out workspace/<token>_state.json

This saves full doc state to workspace/<token>_state.json and prints a summary to stdout:

• commented_blocks: blocks that have unresolved comments, each with elements, full_text, and comments[]{comment_id, anchor_text, instruction}
• all_blocks: full block list (no elements, for structural reference)

Always save to workspace. The editing process may span multiple sessions.

Step 2 — Present comments to user

Show each entry in commented_blocks as:

[block_type] full_text
  → 【anchor_text】 instruction

Ask the user to confirm which comments to address, or proceed if the intent is clear.

Step 3 — Apply text edits

For each comment requiring a text change, construct a patches list and run:

python3 scripts/patch_blocks.py <doc_token> patches.json

patches.json format — elements completely replace the block's existing content:

[
  {
    "block_id": "doxcnXXXX",
    "elements": [
      {"text": "普通文字"},
      {"text": "加粗", "bold": true},
      {"text": "代码", "code": true},
      {"text": "斜体", "italic": true}
    ]
  }
]

Supported element fields: text (required), bold, italic, code, strikethrough, underline.

Note: update_text_elements clears comment_ids from the elements. This is expected — always resolve addressed comments in Step 4.

Step 4 — Resolve addressed comments

python3 scripts/resolve_comments.py <doc_token> <comment_id> [comment_id ...]
# or via stdin:
echo '["id1","id2"]' | python3 scripts/resolve_comments.py <doc_token> -

Step 5 — Re-fetch and update state

Re-run Step 1 to refresh workspace/<token>_state.json after edits.

Limitations

These operations are not handled by this skill's scripts and require additional API calls:

• Insert blank line / empty block: needs Create Block API
• Delete a block (e.g., remove a divider): needs Delete Block API
• Structural reordering: needs Move Block API

For such operations, use lark-cli api directly or ask the user if they want to handle them manually.

Warning

Never use lark-cli docs +update --mode replace_range --selection-by-title to rename a heading. It selects the entire section (heading + all content until next heading) and deletes it all. Use --selection-with-ellipsis "heading text" instead.