摘要文档与云盘是企业知识管理的基础设施。本文深入lark-cli的shortcuts/doc/和shortcuts/drive/包从文档的创建/读取/更新到云盘文件的上传/下载/导出完整解析这两个模块的Shortcuts实现。包含文档操作流程图、云盘文件生命周期图、以及Python文档处理客户端的实战代码。一、引言知识管理的API化1.1 场景驱动# 基于模板创建周报lark-cli doc create--title周报-第3周--markdown# 本周进展\n- ...# 搜索包含架构设计的文档lark-cli doc search--query架构设计# 下载云盘文件lark-cli drive download --file-tokenboxxxxxxxxx# 导出文档为PDFlark-cli drive export --file-tokendoxxxxxxxxx--formatpdf二、Doc Shortcuts体系2.1 文档操作Doc Shortcuts创建create 创建文档--title 标题--markdown Markdown内容读取fetch 获取文档内容search 搜索文档更新update 更新文档块媒体media-upload 上传图片media-download 下载媒体2.2 Markdown转飞书文档飞书文档不是纯文本而是块Block结构。Shortcuts负责将用户输入的Markdown转换为Block列表defmarkdown_to_blocks(md:str)-list:Markdown转飞书文档块blocks[]forlineinmd.split(\n):ifline.startswith(# ):blocks.append({block_type:1,heading1:{elements:[{text_run:{content:line[2:]}}]}})elifline.startswith(## ):blocks.append({block_type:2,heading2:{elements:[{text_run:{content:line[3:]}}]}})elifline.startswith(- ):blocks.append({block_type:13,bullet:{elements:[{text_run:{content:line[2:]}}]}})elifline.strip():blocks.append({block_type:2,text:{elements:[{text_run:{content:line}}]}})returnblocks三、Drive Shortcuts体系3.1 云盘文件操作// shortcuts/drive/drive_download.govarDownloadShortcutcommon.Shortcut{Service:drive,Command:download,AuthTypes:[]string{user,bot},Flags:[]common.Flag{{Name:file-token,Type:string,Required:true,Desc:文件Token},{Name:output,Type:string,Required:true,Desc:保存路径},},Execute:func(ctx context.Context,rctx*common.RuntimeContext)error{fileToken:rctx.Str(file-token)outputPath:rctx.Str(output)// 使用DoAPI获取原始响应二进制req:larkcore.ApiReq{HttpMethod:GET,ApiPath:fmt.Sprintf(/open-apis/drive/v1/files/%s/download,fileToken),}resp,err:rctx.DoAPI(req,larkcore.WithFileDownload())iferr!nil{returnerr}// 写入文件os.WriteFile(outputPath,resp.RawBody,0644)rctx.Out(map[string]string{downloaded:outputPath},nil)returnnil},}四、Python实战文档批处理工具#!/usr/bin/env python3# -*- coding: utf-8 -*- doc_processor.py 飞书文档批处理工具 importjsonfrompathlibimportPathimportrequestsclassDocProcessor:文档处理器def__init__(self,access_token:str):self.tokenaccess_token self.basehttps://open.feishu.cndefcreate_doc(self,title:str,content_md:str)-str:基于Markdown创建文档urlf{self.base}/open-apis/docx/v1/documentsresprequests.post(url,json{title:title},headers{Authorization:fBearer{self.token}})doc_idresp.json()[data][document][document_id]# 批量插入内容块简化版blocksself._md_to_blocks(content_md)batch_urlf{self.base}/open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children/batch_createrequests.post(batch_url,json{children:blocks},headers{Authorization:fBearer{self.token}})returndoc_iddef_md_to_blocks(self,md:str)-list:Markdown转Block简化版blocks[]forlineinmd.split(\n):lineline.strip()ifnotline:continueifline.startswith(# ):blocks.append({block_type:1,heading1:{elements:[{text_run:{content:line[2:]}}]}})elifline.startswith(## ):blocks.append({block_type:2,heading2:{elements:[{text_run:{content:line[3:]}}]}})else:blocks.append({block_type:2,text:{elements:[{text_run:{content:line}}]}})returnblocksdefdownload_file(self,file_token:str,output_path:str)-None:下载云盘文件urlf{self.base}/open-apis/drive/v1/files/{file_token}/downloadresprequests.get(url,headers{Authorization:fBearer{self.token}})Path(output_path).write_bytes(resp.content)if__name____main__:processorDocProcessor(u-xxxxxxxx)doc_idprocessor.create_doc(测试文档,# 标题\n正文内容)print(f创建文档:{doc_id})五、FAQ与最佳实践Q1Doc和Drive的Token有什么区别Doc使用document_iddoc_xxx/dox_xxxDrive文件使用file_tokenbox_xxx。下载文档内容通过Docx API下载云盘文件通过Drive API。Q2如何导出文档为PDF飞书提供异步导出接口先创建导出任务轮询任务状态最后下载导出文件。lark-cli的exportShortcut封装了这一复杂流程。六、总结Doc与Drive的设计要点Doc是块结构不是纯文本而是heading/paragraph/bullet/image等块的组合Drive处理二进制上传/下载需要multipart/form-data和流式处理导出是异步的PDF/Word导出需要创建任务→轮询→下载的三步流程参考资料lark-cli 源码-shortcuts/doc/: Doc Shortcutslark-cli 源码-shortcuts/drive/: Drive Shortcuts飞书Docx API: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/docx-v1飞书Drive API: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1本文基于 lark-cli Doc/Drive模块源码分析。