drive (v1)

drive (v1) Skill for Happycapy Skills Platform

The drive (v1) skill (lark-drive) is an integration for the Happycapy Skills platform that enables robust management of files and folders within Lark (Feishu) Drive, Lark Suite’s cloud storage and document collaboration solution. This skill exposes a comprehensive set of file operations through a command-line interface (CLI), making it essential for developers, automation engineers, and teams looking to orchestrate document workflows, manage permissions, and interact programmatically with Lark Drive's cloud infrastructure.

What Is This

The drive (v1) skill is a CLI-driven tool that provides direct access to Lark Drive’s file and folder management capabilities. It allows users and automations to:

• Upload and download files
• Create, copy, move, and delete files or folders
• Retrieve file metadata and details
• Manage document comments and permissions
• Subscribe to document comment update events

This functionality is accessed via the lark-cli drive command suite, enabling seamless integration into scripts, CI/CD pipelines, and custom applications.

Why Use It

Modern organizations rely on cloud document platforms for collaboration, storage, and workflow automation. The drive (v1) skill empowers teams to:

• Automate document organization, archiving, and sharing tasks
• Integrate Lark Drive with third-party systems or internal tools
• Manage document permissions, comments, and metadata at scale
• Enable programmatic file operations, reducing manual errors and effort

The skill abstracts the intricacies of the Lark Open Platform API, providing a streamlined CLI interface that can be embedded within broader automation or used interactively by technical staff.

How to Use It

Prerequisites

• Authentication and Permissions: Before using drive (v1), you must set up authentication and permissions as documented in the shared lark-shared/SKILL.md. This typically involves configuring API credentials and ensuring the appropriate scopes for file operations.
• Installation: Ensure lark-cli is installed and available in your environment.

Basic Operations

All functionality is accessed via lark-cli drive. For help, execute:

lark-cli drive --help

Example:

Uploading a File

lark-cli drive upload --parent-folder-token=fldcnxxxx --file-path=./report.pdf

Example:

Downloading a File

lark-cli drive download --file-token=doxcnxxxxxxxxx --output=./downloaded_report.pdf

Example:

Creating a Folder

lark-cli drive folder create --parent-folder-token=fldcnxxxx --name="2024 Projects"

Example:

Managing Comments

lark-cli drive comment list --file-token=doxcnxxxxxxxxx
lark-cli drive comment add --file-token=doxcnxxxxxxxxx --content="Please review section 2."

Example:

Managing Permissions

lark-cli drive permission list --file-token=doxcnxxxxxxxxx
lark-cli drive permission update --file-token=doxcnxxxxxxxxx --user-id=ou_xxx --role=reader

Handling Document URLs and Tokens

Lark Drive supports various document types, each with specific URL formats and token handling requirements. Understanding these is essential for correct operation.

Special Handling for Wiki Links

Wiki (knowledge base) links do not directly map to a file token. You must first resolve the actual document type and obtain the real token.

Workflow:

1. Use the wiki.spaces.get_node API to query the node for the wiki token.
2. Determine the underlying document type (doc, sheet, etc.) and retrieve the corresponding obj_token.
3. Use the resolved token for further operations.

## Example (pseudo-code, replace with actual CLI/API call)
lark-cli wiki spaces get_node --wiki-token=wikcnxxxxxxxxx
## Parse response to extract obj_token and type

When to Use It

The drive (v1) skill is ideal for:

• Automating file uploads, downloads, and organization in Lark Drive
• Integrating Lark Drive with other platforms (such as reporting tools or workflow engines)
• Managing document comments and permissions programmatically
• Building bots or tools that need to monitor and respond to document events (such as comment updates)
• Handling large-scale migration or synchronization of files and folders

Important Notes

• Authentication Is Mandatory: Always ensure correct authentication and permission setup before using this skill. Refer to the shared lark-shared/SKILL.md for detailed steps.
• Token Handling: Not all document URLs yield usable tokens directly. Pay special attention to wiki links, which require an additional resolution step.
• Error Handling: All CLI operations should be checked for errors, especially when automating workflows.
• Event Subscriptions: You can subscribe to user comment changes and other file events to build reactive integrations.
• CLI Binaries: The lark-cli binary is required for all operations. Ensure it is up-to-date and correctly configured in your environment.

The drive (v1) skill is a powerful enabler for any team or application needing advanced, automated interactions with Lark Drive. By adhering to correct token handling and authentication practices, you can safely and efficiently leverage Lark’s cloud document ecosystem.