@max1874/feishu 0.2.21 → 0.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max1874/feishu",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",

package/src/docx.ts

@@ -865,7 +865,11 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_doc_read",
       label: "Feishu Doc Read",
-      description: "Read plain text content and metadata from a Feishu document",
+      description:
+        "Read plain text content and metadata from a Feishu document. " +
+        "Use this for a quick overview of document content. " +
+        "For structured content (tables, block details), use feishu_doc_list_blocks instead. " +
+        "Extract doc_token from URL: /docx/XXX or /docs/XXX.",
       parameters: DocTokenSchema,
       async execute(_toolCallId, params) {
         const { doc_token } = params as { doc_token: string };
@@ -886,7 +890,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_doc_create",
       label: "Feishu Doc Create",
       description:
-        "Create a new empty Feishu document. Automatically grants full_access (manage) permission to the current conversation participant.",
+        "Create a new empty Feishu document. " +
+        "Automatically grants full_access permission to the conversation participant so they can edit. " +
+        "After creating, use feishu_doc_write to populate content. " +
+        "Set permission='tenant_editable' to allow anyone in the organization to edit via link.",
       parameters: CreateDocSchema,
       async execute(_toolCallId, params) {
         const { title, folder_token, permission } = params as {
@@ -911,7 +918,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_doc_write",
       label: "Feishu Doc Write",
       description:
-        "Write markdown content to a Feishu document (replaces all content). Supports headings, lists, code blocks, quotes, links, images, tables, and text styling.",
+        "Write markdown content to a Feishu document. WARNING: This REPLACES ALL existing content. " +
+        "Use for: initial document population, complete rewrites. " +
+        "For partial edits, use feishu_doc_update_block instead. " +
+        "Supports: headings, lists, code blocks, quotes, links, images, tables, bold/italic/strikethrough.",
       parameters: WriteDocSchema,
       async execute(_toolCallId, params) {
         const { doc_token, content } = params as { doc_token: string; content: string };
@@ -932,7 +942,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_doc_append",
       label: "Feishu Doc Append",
       description:
-        "Append markdown content to the end of a Feishu document. Supports same markdown syntax as write.",
+        "Append markdown content to the END of a Feishu document without touching existing content. " +
+        "Use for: adding new sections, logging, incremental content building. " +
+        "Cannot insert in the middle - for that, use feishu_doc_update_block or delete+append. " +
+        "Supports same markdown syntax as feishu_doc_write.",
       parameters: AppendDocSchema,
       async execute(_toolCallId, params) {
         const { doc_token, content } = params as { doc_token: string; content: string };
@@ -952,7 +965,11 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_doc_update_block",
       label: "Feishu Doc Update Block",
-      description: "Update the text content of a specific block in a Feishu document",
+      description:
+        "Update the text content of a specific block without affecting other parts of the document. " +
+        "WORKFLOW: First call feishu_doc_list_blocks to find the block_id, then update it here. " +
+        "Use for: fixing typos, updating a paragraph, modifying specific sections. " +
+        "Only works on text-based blocks (paragraphs, headings, lists). Cannot change block type.",
       parameters: UpdateBlockSchema,
       async execute(_toolCallId, params) {
         const { doc_token, block_id, content } = params as {
@@ -976,7 +993,11 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_doc_delete_block",
       label: "Feishu Doc Delete Block",
-      description: "Delete a specific block from a Feishu document",
+      description:
+        "Delete a specific block from a Feishu document. " +
+        "WORKFLOW: First call feishu_doc_list_blocks to find the block_id, then delete it here. " +
+        "Use for: removing outdated content, clearing sections before rewriting. " +
+        "Combine with feishu_doc_append to replace content in the middle of a document.",
       parameters: DeleteBlockSchema,
       async execute(_toolCallId, params) {
         const { doc_token, block_id } = params as { doc_token: string; block_id: string };
@@ -997,7 +1018,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_doc_list_blocks",
       label: "Feishu Doc List Blocks",
       description:
-        "List all blocks in a Feishu document with full content. Use this to read structured content like tables. Returns block_id for use with update/delete/get_block.",
+        "List all blocks in a Feishu document with their block_id and full content. " +
+        "ESSENTIAL for editing: returns block_id needed by update_block/delete_block/get_block. " +
+        "Better than feishu_doc_read for: seeing document structure, reading tables, finding specific sections. " +
+        "Block types include: text, headings (1-9), bullet/ordered lists, code, quote, table, image, divider.",
       parameters: DocTokenSchema,
       async execute(_toolCallId, params) {
         const { doc_token } = params as { doc_token: string };
@@ -1017,7 +1041,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_doc_get_block",
       label: "Feishu Doc Get Block",
-      description: "Get detailed content of a specific block by ID (from list_blocks)",
+      description:
+        "Get detailed content of a specific block by its block_id. " +
+        "Use when feishu_doc_list_blocks output is truncated or you need fresh data for one block. " +
+        "Returns full block structure including nested content (e.g., table cells).",
       parameters: GetBlockSchema,
       async execute(_toolCallId, params) {
         const { doc_token, block_id } = params as { doc_token: string; block_id: string };
@@ -1037,7 +1064,11 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_folder_list",
       label: "Feishu Folder List",
-      description: "List documents and subfolders in a Feishu folder",
+      description:
+        "List documents and subfolders in a Feishu Drive folder. " +
+        "Extract folder_token from URL: /drive/folder/XXX. " +
+        "Use to browse available documents or find a doc_token to read/edit. " +
+        "Returns: file name, type (docx/sheet/folder/etc), token, URL, last modified time.",
       parameters: FolderTokenSchema,
       async execute(_toolCallId, params) {
         const { folder_token } = params as { folder_token: string };
@@ -1058,7 +1089,9 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_doc_set_permission",
       label: "Feishu Doc Set Permission",
       description:
-        "Set document sharing permission. Use 'tenant_editable' to allow organization members to edit via link.",
+        "Change document sharing permissions after creation. " +
+        "Options: 'tenant_editable' = anyone in organization can edit via link; 'private' = only owner/explicitly granted users. " +
+        "Note: feishu_doc_create already grants full_access to the conversation participant.",
       parameters: SetPermissionSchema,
       async execute(_toolCallId, params) {
         const { doc_token, permission } = params as { doc_token: string; permission: DocPermission };
@@ -1094,7 +1127,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_wiki_read",
       label: "Feishu Wiki Read",
       description:
-        "Read content from a Feishu wiki page. Extract wiki_token from URL /wiki/XXX. Returns wiki metadata and document content if the underlying type is docx.",
+        "Read content from a Feishu Wiki (knowledge base) page. " +
+        "Extract wiki_token from URL: /wiki/XXX. " +
+        "Different from feishu_doc_read - wikis have their own token format and metadata. " +
+        "Returns wiki node info and document content if the underlying type is docx.",
       parameters: WikiTokenSchema,
       async execute(_toolCallId, params) {
         const { wiki_token } = params as { wiki_token: string };
@@ -1114,7 +1150,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
     {
       name: "feishu_wiki_spaces",
       label: "Feishu Wiki Spaces",
-      description: "List available wiki spaces (knowledge bases) the app has access to.",
+      description:
+        "List all Wiki spaces (knowledge bases) the app has access to. " +
+        "Returns space_id needed for feishu_wiki_nodes. " +
+        "Use this first when browsing wikis to find the right knowledge base.",
       parameters: Type.Object({}),
       async execute() {
         try {
@@ -1134,7 +1173,10 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_wiki_nodes",
       label: "Feishu Wiki Nodes",
       description:
-        "List wiki nodes (pages) in a space. Use parent_node_token to list children of a specific node.",
+        "List wiki pages within a Wiki space. " +
+        "WORKFLOW: First call feishu_wiki_spaces to get space_id, then list nodes here. " +
+        "Use parent_node_token to browse nested pages (children of a specific node). " +
+        "Returns node_token for use with feishu_wiki_read.",
       parameters: WikiSpaceIdSchema,
       async execute(_toolCallId, params) {
         const { space_id, parent_node_token } = params as {
@@ -1158,7 +1200,9 @@ export function registerFeishuDocTools(api: OpenClawPluginApi) {
       name: "feishu_app_scopes",
       label: "Feishu App Scopes",
       description:
-        "List current app permissions (scopes). Use to debug permission issues or check available capabilities.",
+        "List the app's current permissions (scopes) granted in Feishu admin console. " +
+        "Use when a tool fails with permission errors to diagnose what's missing. " +
+        "Common required scopes: docx:document (read/edit docs), wiki:wiki (read wikis), drive:drive (folder access).",
       parameters: Type.Object({}),
       async execute() {
         try {