lark-doc

权威经验

在多轮对话的情况下，用户要求重新修改文档时，必须重新阅读文档，因为用户可能自己手动编辑过文件，此时文件的内容可能与上下文内容不一致，直接使用之前读取的内容会造成用户手动编辑的内容丢失。

用户要求将前轮对话转换为飞书文档时，须保留可视化组件的原始格式与交互，echarts 块及 HTML 组件（含原图叠加和内嵌 SVG）均可通过 html5-block 承接，可编辑的 SVG 和 mermaid 都使用画板承接并优先保留其原格式。

skill 边界

明确本 skill 的适用边界，并非所有写作任务都适用于此 skill，对于不应使用本文能力的情况请选择更加合适的 skill

• 典型应该使用本 skill 的情况：

  • 明确要求交付的是飞书/豆包在线文档
  • 明确给定的是飞书/豆包在线文档要求基于此编辑
  • 读取在线云文档

• 典型不应该使用本 skill 的情况：

  • 应路由到 word Skill：
    • 给定 PDF 文件要求转换为 Word 文件
    • 用户明确要求交付 Word 文件
    • 用户提供一份 Word 文件作为模板要求基于此进行 Word 写作
    • 用户提供一份 Word 文件要求基于此进行修改编辑
  • 应路由到 lark-drive:
    • 要求把一个飞书/豆包在线文档导出为 Word 文件
    • 添加、分页查看、回复评论或增删 reaction
    • 给定一个 Word 文件要求上传为在线文档
    • 找文档、导入导出、云空间文件上传 / 下载 / 权限管理
    • 复制文档、创建副本或另存为副本时，按其指引使用 drive +copy

• 对于一个写作类任务，但用户没有明确告知交付载体时，应该遵循如下判断

  体裁	典型场景	默认交付载体
  学术教研与基础教育教学	学习计划、备考路径、复习讲义、试卷与讲评、教案、公开课、教学设计、课程材料、论文写作与指导	Word
  党政公文和其他正式文书写作	党政机关、事业单位、基层党组织面向体系内或公共部门的正式文书；企业、社会组织等境内法人向党政部门、事业单位提交的正式文书及党建材料；个人向政府、基层村居或党组织提交的思想汇报、申请等材料	Word
  事业单位/国有企业/人民团体组织内的职场文书	事业单位、人民团体、国有企业的总结、计划、汇报、方案、会议材料、制度、发言稿等非党建公文材料正式文书	Word
  专业法律文书与商务协议	围绕具体案件、法律问题或权利义务关系的法律意见、律师函、催告、起诉、答辩、上诉、代理、辩护、仲裁及程序申请；采购、服务、合作、买卖、租赁、承揽、补充协议、履约约定	Word
  专业领域文书	工程技术方案与医疗文书、财务与审计报告，以及其他需要适用于现行专业规则的文书	Word
  媒体与传播	微信公众号推文、小红书图文笔记、邮件、短视频口播稿、短视频分镜脚本、平台标题、封面文案和标题库	在线文档
  创意写作	网文、小说、故事、同人、剧本、互动叙事、故事大纲	在线文档
  品牌营销	营销策划、品牌认知、产品上市、内容种草、活动战役、增长转化、客户经营、渠道动销与整合营销	在线文档
  生活应用与攻略	旅行计划、旅行路书、城市或景点攻略、健身计划、减脂计划、生活指南	在线文档
  分析报告与决策支持	基于表格、数据、调研材料、多个附件或可核验来源形成详细分析、研究、比较、诊断或建议	在线文档
  市场化企业职场文书	民营、外资及一般商业组织的项目提案、工作总结、正式汇报、项目提案、岗位说明、培训材料、会议纪要（非政务党建类）	在线文档
  无法判断	没有明确载体要求，且无法匹配以上体裁	Word

⚠️ 交付载体为在线文档的才应该使用本 skill，本 skill 可以与其他 skill 一起共同解决用户的问题。比如使用别的 skill/工具获取用户提供的非在线文档信息，再使用本 skill 的能力输出在线文档；或者使用本 skill 的能力先读取在线文档，然后交由别的 skill/工具完成后续的非在线文档产物交付。

在线文档场景与 Shortcut 路由

• CRITICAL：先判断场景，再读取该场景的参考文件；不要在任务开始时一次性读取全部参考文件。每个文件只在首次进入对应阶段时读取一次。
• 用户附件必须逐一盘点，完整提取结果可以落盘保存，只把当前任务需要的证据载入上下文。
• 本地文件引用统一遵循文件访问权限：CWD 内优先使用 @./相对路径，其他目录使用 @绝对路径。XML 内的相对资源路径先查 CWD；仅文件不存在时再查源 XML 文件所在目录，同名文件以 CWD 为准。内联内容、stdin、在线文档没有源文件目录，不执行回退。
• Windows 兼容性：SystemPrompt 出现 Computer OS: Windows 或为 windows os 时遵循以下指令
  • Bash 工具实际按 PowerShell 语法执行：每次 Bash 调用只执行一条外部命令；禁止使用 && / || 串联命令，多步操作拆成多次 Bash 调用。禁止使用 PowerShell Get-Content 读取待传给 lark-cli 的本地文件，也不得通过变量或管道中转文件内容；
  • 参数支持文件输入时，必须直接使用上述 @file 形式（@ 前必须加双引号），避免文本解码或重编码导致内容损坏。常见问题：在 PowerShell 5.X 上，双引号会被直接移除，导致内容解码失败。
  • 文件读写走工具本身或 Python**：不要用 > / Out-File / Get-Content ... | cli --xxx -，PowerShell 5 默认非 UTF-8、加 BOM、走 stdin 时非 ASCII 字节会被重编码。读写文件形式时使用统一编码，比如 utf-8
• 身份：文档操作推荐显式指定 --as user。
• 最终给用户的回复不要过长：最重要的产物是你最终生成的文档产物，而不是给用户的最终回复。最终回复 不能超过300字，也不能超过 8 行，只需要简单介绍一下产物即可

文档意图澄清

当用户基于一个文档提出 prompt，结合当前请求和已有对话仍无法判断是希望编辑文档，还是仅需要回答问题时（如“帮我翻译第 xx 段”），先调用 interaction.ask 询问，并按下述选择或超时规则处理；未明确选择编辑时不修改文档。用户意图已明确时直接执行，不重复询问。

interaction.ask 调用方式：按工具当前提供的参数定义调用，必须以选项形式询问用户，提供“编辑文档”和“仅回答问题”两个可点击选项。询问文案中保留“1）编辑文档；2）仅回答问题”作为数字回复兜底，并告知“选择超时默认仅回答，不修改文档”；弹框外不重复列出选项。不要用普通文本代替可用的交互工具；仅当 interaction.ask 不可用时，使用相同问题和数字选项以普通文本询问，按同样的选择或超时规则处理。

按钮与文字等价：用户通过按钮、数字或明确文字选择“编辑文档”（1）时进入编辑流程；选择“仅回答问题”（2）时只在对话中回答，不修改文档。收到明确选择后不再二次确认；回复含糊或互相矛盾时才继续澄清。

选择超时：工具或当前交互通道明确返回选择超时时，默认仅在对话中回答，不修改文档，不将超时视为编辑授权。

文档内容

• 读取 / 摘要 — +fetch：先读参考再获取文档。
• 创建 — +create 工作流：从零创作时完整执行 Authoring 流程，简单任务不是跳过的理由；仅创建空文档或原样导入用户提供的完整内容时，按其中的 Shortcut 直接创建。
• 编辑 / block 直达链接 — +update：语义改写、润色、重组、补写或排版均按 update 参考完成。

辅助能力

• 草稿初始化、解析与统计 — +script：支持解析文档 URL / token 与本地 XML，统计字数并返回字符诊断；不支持 Markdown 输入。
• 历史版本 — +history-list / +history-revert / +history-revert-status：查询、回滚文档历史版本或检查回滚任务状态。

资源、画板与思维笔记

• 插入本地素材 — +media-insert：在文末插入本地图片或文件。
• 预览素材 — +media-preview：预览文档或评论中的图片、附件或素材。
• 下载素材 — +media-download：下载文档中的图片、附件、素材或画板缩略图。
• Docx 封面 — +resource-download / +resource-update / +resource-delete：下载、更新或删除 Docx 封面。
• 画板 — 画板工作流：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 whiteboard +update 写入。
• 思维笔记 — mindnotes：已有思维笔记走 思维笔记链路；新建思维笔记走 lark-doc-whiteboard。