@max1874/feishu 0.2.21 → 0.2.23

package/package.json

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

package/src/docx.ts

@@ -508,6 +508,20 @@ async function grantFullAccess(client: Lark.Client, docToken: string, memberId:
   return res.data;
 }
 
+/** Transfer document ownership to a user (open_id) */
+async function transferOwner(client: Lark.Client, docToken: string, newOwnerOpenId: string) {
+  const res = await client.drive.permissionMember.transferOwner({
+    path: { token: docToken },
+    params: { type: "docx", need_notification: false, remove_old_owner: false },
+    data: {
+      member_type: "openid",
+      member_id: newOwnerOpenId,
+    },
+  });
+  if (res.code !== 0) throw new Error(res.msg);
+  return res.data;
+}
+
 async function createDoc(
   client: Lark.Client,
   title: string,
@@ -526,16 +540,32 @@ async function createDoc(
     await setDocPermissionTenantEditable(client, docId);
   }
 
-  // Auto-grant full_access to conversation participant (user in DM, chat group in group)
+  // Auto-transfer ownership to the sender, and grant group access if in group chat
+  let ownerTransferredTo: string | undefined;
   let grantedTo: string | undefined;
   const convCtx = getConversationContext();
   if (docId && convCtx) {
-    const memberId = convCtx.chatType === "group" ? convCtx.chatId : convCtx.senderOpenId;
+    // Transfer ownership to the user who triggered this request
     try {
-      await grantFullAccess(client, docId, memberId);
-      grantedTo = memberId;
+      await transferOwner(client, docId, convCtx.senderOpenId);
+      ownerTransferredTo = convCtx.senderOpenId;
     } catch {
-      // Non-fatal: doc is created, permission grant failed
+      // Fallback: grant full_access if transfer fails
+      try {
+        await grantFullAccess(client, docId, convCtx.senderOpenId);
+        grantedTo = convCtx.senderOpenId;
+      } catch {
+        // Non-fatal: doc is created, permission grant failed
+      }
+    }
+
+    // In group chats, also grant full_access to the chat group
+    if (convCtx.chatType === "group") {
+      try {
+        await grantFullAccess(client, docId, convCtx.chatId);
+      } catch {
+        // Non-fatal
+      }
     }
   }
 
@@ -544,6 +574,7 @@ async function createDoc(
     title: doc?.title,
     url: `https://feishu.cn/docx/${docId}`,
     permission: permission ?? "private",
+    ...(ownerTransferredTo && { owner_transferred_to: ownerTransferredTo }),
     ...(grantedTo && { granted_full_access_to: grantedTo }),
   };
 }
@@ -865,7 +896,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 +921,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 +949,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 +973,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 +996,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 +1024,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 +1049,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 +1072,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 +1095,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 +1120,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 +1158,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 +1181,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 +1204,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 +1231,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 {