{
  "schemaVersion": "1.0",
  "item": {
    "slug": "feishu-docs",
    "name": "飞书文档API技能",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/StevenLikeWatermelon/feishu-docs",
    "canonicalUrl": "https://clawhub.ai/StevenLikeWatermelon/feishu-docs",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/feishu-docs",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=feishu-docs",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SETUP.md",
      "SKILL.md",
      "bin/cli.js",
      "example-usage.md",
      "examples/create-project-doc.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/feishu-docs"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/feishu-docs",
    "agentPageUrl": "https://openagent3.xyz/skills/feishu-docs/agent",
    "manifestUrl": "https://openagent3.xyz/skills/feishu-docs/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/feishu-docs/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "飞书文档(Docx)技能",
        "body": "操作飞书新版文档(Docx)的openClaw技能，基于飞书开放平台 API 实现文档全生命周期管理。"
      },
      {
        "title": "功能特性",
        "body": "功能说明文档 CRUD创建、获取、更新（全量替换）、删除文档内容追加向已有文档末尾追加 Markdown/HTML 内容内容转换通过飞书服务端 API 将 Markdown/HTML 转换为文档块块操作获取文档块列表（自动分页）、插入子块、删除块权限管理添加协作者、查看权限成员列表文件管理按文件夹列出文件、按关键词搜索文档"
      },
      {
        "title": "环境变量",
        "body": "export FEISHU_APP_ID=cli_xxxxxx          # 飞书应用 App ID\nexport FEISHU_APP_SECRET=your_app_secret  # 飞书应用 App Secret\n\n也可通过 .env 文件配置（项目使用 dotenv 自动加载）。"
      },
      {
        "title": "快速开始",
        "body": "# 安装依赖\nnpm install\n\n# 查看帮助\nnode bin/cli.js --help\n\n# 创建文档（含 Markdown 内容）\nnode bin/cli.js create -f fldxxxxxx -t \"项目计划\" -c \"# 概述\\n\\n内容...\"\n\n# 获取文档\nnode bin/cli.js get -d dcnxxxxxx --format markdown --include-content\n\n# 全量替换文档内容\nnode bin/cli.js update -d dcnxxxxxx --content-file new-content.md\n\n# 追加内容\nnode bin/cli.js update -d dcnxxxxxx --append -c \"## 补充\\n\\n新增内容\"\n\n# 删除文档\nnode bin/cli.js delete -d dcnxxxxxx"
      },
      {
        "title": "CLI 命令",
        "body": "命令说明必要参数create创建文档（有内容时自动使用转换流程）-f文件夹token, -t标题create-with-content创建文档并通过转换API插入内容-f文件夹token, -t标题get获取文档信息-d文档IDupdate替换或追加文档内容-d文档ID, -c内容或--content-filedelete删除文档-d文档IDsearch搜索文档-q关键词list列出文件夹中的文件-f文件夹tokenshare分享文档给用户-d文档ID, -u用户IDpermissions查看文档权限成员-d文档IDconvert将Markdown/HTML转换为文档块（预览）-t内容类型\n\n所有命令均支持 --app-id 和 --app-secret 参数覆盖环境变量。"
      },
      {
        "title": "文档管理",
        "body": "方法说明createDocument(folderToken, title)创建空文档createDocumentWithContent(folderToken, title, content, contentType)创建文档并插入内容getDocument(documentId)获取文档信息getDocumentRawContent(documentId)获取文档纯文本内容deleteDocument(documentId)删除文档（通过 Drive API）"
      },
      {
        "title": "文档块操作",
        "body": "方法说明getDocumentBlocks(documentId, pageSize, pageToken)获取文档块列表（单页）getAllDocumentBlocks(documentId)获取所有块（自动分页）updateDocumentBlock(documentId, blockId, updateRequest)更新指定块createDocumentBlocks(documentId, blockId, children, index)在指定块下插入子块deleteDocumentBlock(documentId, blockId)删除指定块batchDeleteBlocks(documentId, blockIds)批量删除块"
      },
      {
        "title": "内容操作",
        "body": "方法说明appendToDocument(documentId, content, contentType)向文档末尾追加内容replaceDocumentContent(documentId, content, contentType)全量替换文档内容convertContent(contentType, content, userIdType)将 Markdown/HTML 转换为文档块"
      },
      {
        "title": "文件与搜索",
        "body": "方法说明listFolderFiles(folderToken, type)列出文件夹下的文件searchDocuments(query, folderToken)按关键词搜索文档"
      },
      {
        "title": "权限管理",
        "body": "方法说明addPermissionMember(token, memberId, memberType, perm)添加权限成员getPermissionMembers(token)获取权限成员列表"
      },
      {
        "title": "格式转换（本地）",
        "body": "方法说明markdownToBlocks(markdown)Markdown → 飞书块结构（本地转换）blocksToMarkdown(blocks)飞书块结构 → Markdown（支持数字/字符串 block_type）"
      },
      {
        "title": "飞书 API 端点",
        "body": "代码实际调用的飞书开放平台端点：\n\nPOST   /docx/v1/documents                                    # 创建文档\nGET    /docx/v1/documents/{document_id}                      # 获取文档信息\nGET    /docx/v1/documents/{document_id}/raw_content          # 获取文档纯文本\nGET    /docx/v1/documents/{document_id}/blocks               # 获取文档块列表\nPATCH  /docx/v1/documents/{document_id}/blocks/{block_id}    # 更新块\nDELETE /docx/v1/documents/{document_id}/blocks/{block_id}    # 删除块\nPOST   /docx/v1/documents/{document_id}/blocks/{block_id}/children  # 插入子块\nPOST   /docx/v1/documents/blocks/convert                     # Markdown/HTML→块\nDELETE /drive/v1/files/{file_token}?type=docx                # 删除文档\nGET    /drive/v1/files?folder_token=xxx                      # 列出文件夹文件\nPOST   /drive/v1/permissions/{token}/members?type=docx       # 添加权限成员\nGET    /drive/v1/permissions/{token}/members?type=docx       # 获取权限成员\nPOST   /auth/v3/tenant_access_token/internal/                # 获取 tenant_access_token"
      },
      {
        "title": "可靠性机制",
        "body": "Token 缓存与并发控制：access_token 缓存复用，多个并发请求不会重复刷新\n自动重试：401 未授权自动刷新 token 重试；429 限流和 5xx 错误指数退避重试（最多 2 次）\nToken 过期码识别：检测飞书错误码 99991663/99991661 自动刷新 token\n安全错误处理：安全访问 error.response.data，避免非 JSON 响应导致崩溃"
      },
      {
        "title": "注意事项",
        "body": "应用权限：飞书应用需具备 docs:doc、drive:drive、drive:file 等相关权限\n内容插入：create 命令含 content 时自动走 convertContent → createDocumentBlocks 流程，确保文档结构正确\n批量插入限制：每批最多插入 50 个块（飞书 API 限制）\n表格处理：转换含表格的内容时自动去除 merge_info 字段；block_type 为 31/32 的表格块暂被过滤\n内容大小：单次转换内容不超过 10MB"
      },
      {
        "title": "项目结构",
        "body": "├── src/api.js        # FeishuDocsAPI 类（所有 API 方法 + 格式转换）\n├── bin/cli.js        # Commander 命令行工具\n├── package.json      # 依赖：axios, commander, dotenv\n├── test-convert.js   # 转换接口测试\n├── SKILL.md          # 本文件\n└── README.md         # 项目说明"
      }
    ],
    "body": "飞书文档(Docx)技能\n\n操作飞书新版文档(Docx)的openClaw技能，基于飞书开放平台 API 实现文档全生命周期管理。\n\n功能特性\n功能\t说明\n文档 CRUD\t创建、获取、更新（全量替换）、删除文档\n内容追加\t向已有文档末尾追加 Markdown/HTML 内容\n内容转换\t通过飞书服务端 API 将 Markdown/HTML 转换为文档块\n块操作\t获取文档块列表（自动分页）、插入子块、删除块\n权限管理\t添加协作者、查看权限成员列表\n文件管理\t按文件夹列出文件、按关键词搜索文档\n环境变量\nexport FEISHU_APP_ID=cli_xxxxxx          # 飞书应用 App ID\nexport FEISHU_APP_SECRET=your_app_secret  # 飞书应用 App Secret\n\n\n也可通过 .env 文件配置（项目使用 dotenv 自动加载）。\n\n快速开始\n# 安装依赖\nnpm install\n\n# 查看帮助\nnode bin/cli.js --help\n\n# 创建文档（含 Markdown 内容）\nnode bin/cli.js create -f fldxxxxxx -t \"项目计划\" -c \"# 概述\\n\\n内容...\"\n\n# 获取文档\nnode bin/cli.js get -d dcnxxxxxx --format markdown --include-content\n\n# 全量替换文档内容\nnode bin/cli.js update -d dcnxxxxxx --content-file new-content.md\n\n# 追加内容\nnode bin/cli.js update -d dcnxxxxxx --append -c \"## 补充\\n\\n新增内容\"\n\n# 删除文档\nnode bin/cli.js delete -d dcnxxxxxx\n\nCLI 命令\n命令\t说明\t必要参数\ncreate\t创建文档（有内容时自动使用转换流程）\t-f文件夹token, -t标题\ncreate-with-content\t创建文档并通过转换API插入内容\t-f文件夹token, -t标题\nget\t获取文档信息\t-d文档ID\nupdate\t替换或追加文档内容\t-d文档ID, -c内容或--content-file\ndelete\t删除文档\t-d文档ID\nsearch\t搜索文档\t-q关键词\nlist\t列出文件夹中的文件\t-f文件夹token\nshare\t分享文档给用户\t-d文档ID, -u用户ID\npermissions\t查看文档权限成员\t-d文档ID\nconvert\t将Markdown/HTML转换为文档块（预览）\t-t内容类型\n\n所有命令均支持 --app-id 和 --app-secret 参数覆盖环境变量。\n\nAPI 方法\n文档管理\n方法\t说明\ncreateDocument(folderToken, title)\t创建空文档\ncreateDocumentWithContent(folderToken, title, content, contentType)\t创建文档并插入内容\ngetDocument(documentId)\t获取文档信息\ngetDocumentRawContent(documentId)\t获取文档纯文本内容\ndeleteDocument(documentId)\t删除文档（通过 Drive API）\n文档块操作\n方法\t说明\ngetDocumentBlocks(documentId, pageSize, pageToken)\t获取文档块列表（单页）\ngetAllDocumentBlocks(documentId)\t获取所有块（自动分页）\nupdateDocumentBlock(documentId, blockId, updateRequest)\t更新指定块\ncreateDocumentBlocks(documentId, blockId, children, index)\t在指定块下插入子块\ndeleteDocumentBlock(documentId, blockId)\t删除指定块\nbatchDeleteBlocks(documentId, blockIds)\t批量删除块\n内容操作\n方法\t说明\nappendToDocument(documentId, content, contentType)\t向文档末尾追加内容\nreplaceDocumentContent(documentId, content, contentType)\t全量替换文档内容\nconvertContent(contentType, content, userIdType)\t将 Markdown/HTML 转换为文档块\n文件与搜索\n方法\t说明\nlistFolderFiles(folderToken, type)\t列出文件夹下的文件\nsearchDocuments(query, folderToken)\t按关键词搜索文档\n权限管理\n方法\t说明\naddPermissionMember(token, memberId, memberType, perm)\t添加权限成员\ngetPermissionMembers(token)\t获取权限成员列表\n格式转换（本地）\n方法\t说明\nmarkdownToBlocks(markdown)\tMarkdown → 飞书块结构（本地转换）\nblocksToMarkdown(blocks)\t飞书块结构 → Markdown（支持数字/字符串 block_type）\n飞书 API 端点\n\n代码实际调用的飞书开放平台端点：\n\nPOST   /docx/v1/documents                                    # 创建文档\nGET    /docx/v1/documents/{document_id}                      # 获取文档信息\nGET    /docx/v1/documents/{document_id}/raw_content          # 获取文档纯文本\nGET    /docx/v1/documents/{document_id}/blocks               # 获取文档块列表\nPATCH  /docx/v1/documents/{document_id}/blocks/{block_id}    # 更新块\nDELETE /docx/v1/documents/{document_id}/blocks/{block_id}    # 删除块\nPOST   /docx/v1/documents/{document_id}/blocks/{block_id}/children  # 插入子块\nPOST   /docx/v1/documents/blocks/convert                     # Markdown/HTML→块\nDELETE /drive/v1/files/{file_token}?type=docx                # 删除文档\nGET    /drive/v1/files?folder_token=xxx                      # 列出文件夹文件\nPOST   /drive/v1/permissions/{token}/members?type=docx       # 添加权限成员\nGET    /drive/v1/permissions/{token}/members?type=docx       # 获取权限成员\nPOST   /auth/v3/tenant_access_token/internal/                # 获取 tenant_access_token\n\n可靠性机制\nToken 缓存与并发控制：access_token 缓存复用，多个并发请求不会重复刷新\n自动重试：401 未授权自动刷新 token 重试；429 限流和 5xx 错误指数退避重试（最多 2 次）\nToken 过期码识别：检测飞书错误码 99991663/99991661 自动刷新 token\n安全错误处理：安全访问 error.response.data，避免非 JSON 响应导致崩溃\n注意事项\n应用权限：飞书应用需具备 docs:doc、drive:drive、drive:file 等相关权限\n内容插入：create 命令含 content 时自动走 convertContent → createDocumentBlocks 流程，确保文档结构正确\n批量插入限制：每批最多插入 50 个块（飞书 API 限制）\n表格处理：转换含表格的内容时自动去除 merge_info 字段；block_type 为 31/32 的表格块暂被过滤\n内容大小：单次转换内容不超过 10MB\n项目结构\n├── src/api.js        # FeishuDocsAPI 类（所有 API 方法 + 格式转换）\n├── bin/cli.js        # Commander 命令行工具\n├── package.json      # 依赖：axios, commander, dotenv\n├── test-convert.js   # 转换接口测试\n├── SKILL.md          # 本文件\n└── README.md         # 项目说明"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/StevenLikeWatermelon/feishu-docs",
    "publisherUrl": "https://clawhub.ai/StevenLikeWatermelon/feishu-docs",
    "owner": "StevenLikeWatermelon",
    "version": "1.1.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/feishu-docs",
    "downloadUrl": "https://openagent3.xyz/downloads/feishu-docs",
    "agentUrl": "https://openagent3.xyz/skills/feishu-docs/agent",
    "manifestUrl": "https://openagent3.xyz/skills/feishu-docs/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/feishu-docs/agent.md"
  }
}