fix(feishu): drive info finds files past the first page

destire-mio · destire-mio · commit c582bc294715 · 2026-07-12T12:09:13.000+08:00
diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md
@@ -324,6 +324,10 @@ The plugin ships agent tools for Feishu documents, chats, knowledge base, cloud
 
 `tools.base` is an alias for `tools.bitable`; the explicit `bitable` value wins when both are set. Per-account gates live under `accounts.<id>.tools`.
 
+Grant `drive:drive.metadata:readonly` for direct `feishu_drive info` lookups outside the root
+directory, unless the app already has the full `drive:drive` scope. Without either scope, `info`
+keeps the legacy root-directory lookup available through `drive:drive:readonly`.
+
 ### ACP sessions
 
 Feishu/Lark supports ACP for DMs and group thread messages. Feishu/Lark ACP is text-command driven - there are no native slash-command menus, so use `/acp ...` messages directly in the conversation.
diff --git a/extensions/feishu/skills/feishu-drive/SKILL.md b/extensions/feishu/skills/feishu-drive/SKILL.md
@@ -48,7 +48,9 @@ root-list cursors are not forwarded.
 { "action": "info", "file_token": "ABC123", "type": "docx" }
 ```
 
-Searches for the file in the root directory. Note: file must be in root or use `list` to browse folders first.
+Looks up file metadata directly by token and type, regardless of which shared folder contains it.
+Shortcuts are the exception: Feishu's metadata API does not support the `shortcut` type, so shortcut
+info retains the root-directory lookup behavior.
 
 `type`: `doc`, `docx`, `sheet`, `bitable`, `folder`, `file`, `mindnote`, `shortcut`
 
@@ -101,7 +103,8 @@ channels:
 ## Permissions
 
 - `drive:drive` - Full access (create, move, delete)
-- `drive:drive:readonly` - Read only (list, info)
+- `drive:drive:readonly` - Read only (list and root-level info fallback)
+- `drive:drive.metadata:readonly` - Direct `info` lookup outside the root (not needed with `drive:drive`)
 
 ## Known Limitations
 
diff --git a/extensions/feishu/src/drive.test.ts b/extensions/feishu/src/drive.test.ts
@@ -436,6 +436,137 @@ describe("registerFeishuDriveTools", () => {
     });
   });
 
+  it("looks up file info directly by token and type", async () => {
+    const listFiles = vi.fn();
+    const batchQuery = vi.fn().mockResolvedValue({
+      code: 0,
+      data: {
+        metas: [
+          {
+            doc_token: "doc_1",
+            doc_type: "docx",
+            title: "Project Plan",
+            url: "https://example.test/doc_1",
+            create_time: "1710000000",
+            latest_modify_time: "1710001000",
+            owner_id: "ou_owner",
+          },
+        ],
+      },
+    });
+    createFeishuToolClientMock.mockReturnValue({
+      drive: { file: { list: listFiles }, meta: { batchQuery } },
+    });
+    const tool = buildDriveTool();
+
+    const result = await tool.execute("call-info", {
+      action: "info",
+      file_token: "doc_1",
+      type: "docx",
+    });
+
+    expect(batchQuery).toHaveBeenCalledWith({
+      data: {
+        request_docs: [{ doc_token: "doc_1", doc_type: "docx" }],
+        with_url: true,
+      },
+    });
+    expect(listFiles).not.toHaveBeenCalled();
+    expect(result.details).toEqual({
+      token: "doc_1",
+      name: "Project Plan",
+      type: "docx",
+      url: "https://example.test/doc_1",
+      created_time: "1710000000",
+      modified_time: "1710001000",
+      owner_id: "ou_owner",
+    });
+  });
+
+  it("reports a missing file when metadata lookup returns a failed entry", async () => {
+    const batchQuery = vi.fn().mockResolvedValue({
+      code: 0,
+      data: { metas: [], failed_list: [{ code: 970005, token: "missing_doc" }] },
+    });
+    createFeishuToolClientMock.mockReturnValue({
+      drive: { meta: { batchQuery } },
+    });
+    const tool = buildDriveTool();
+
+    const result = await tool.execute("call-info-missing", {
+      action: "info",
+      file_token: "missing_doc",
+      type: "docx",
+    });
+
+    expect(result.details).toMatchObject({ error: "File not found: missing_doc" });
+  });
+
+  it("keeps root-list lookup for shortcut info", async () => {
+    const batchQuery = vi.fn();
+    const listFiles = vi.fn().mockResolvedValue({
+      code: 0,
+      data: {
+        files: [
+          {
+            token: "shortcut_1",
+            name: "Project shortcut",
+            type: "shortcut",
+            url: "https://example.test/shortcut_1",
+          },
+        ],
+      },
+    });
+    createFeishuToolClientMock.mockReturnValue({
+      drive: { file: { list: listFiles }, meta: { batchQuery } },
+    });
+    const tool = buildDriveTool();
+
+    const result = await tool.execute("call-info-shortcut", {
+      action: "info",
+      file_token: "shortcut_1",
+      type: "shortcut",
+    });
+
+    expect(listFiles).toHaveBeenCalledWith({ params: {} });
+    expect(batchQuery).not.toHaveBeenCalled();
+    expect(result.details).toMatchObject({
+      token: "shortcut_1",
+      name: "Project shortcut",
+      type: "shortcut",
+    });
+  });
+
+  it("falls back to root lookup when the metadata scope is missing", async () => {
+    const batchQuery = vi.fn().mockRejectedValue({
+      response: {
+        data: {
+          code: 99991672,
+          msg: "permission denied: drive:drive.metadata:readonly",
+        },
+      },
+    });
+    const listFiles = vi.fn().mockResolvedValue({
+      code: 0,
+      data: {
+        files: [{ token: "doc_1", name: "Project Plan", type: "docx" }],
+      },
+    });
+    createFeishuToolClientMock.mockReturnValue({
+      drive: { file: { list: listFiles }, meta: { batchQuery } },
+    });
+    const tool = buildDriveTool();
+
+    const result = await tool.execute("call-info-missing-scope", {
+      action: "info",
+      file_token: "doc_1",
+      type: "docx",
+    });
+
+    expect(listFiles).toHaveBeenCalledWith({ params: {} });
+    expect(result.details).toMatchObject({ token: "doc_1", name: "Project Plan", type: "docx" });
+  });
+
   it("normalizes folder pagination and suppresses it for root listings", async () => {
     const listFiles = vi.fn().mockResolvedValue({ code: 0, data: { files: [] } });
     createFeishuToolClientMock.mockReturnValue({ drive: { file: { list: listFiles } } });
diff --git a/extensions/feishu/src/drive.ts b/extensions/feishu/src/drive.ts
@@ -367,16 +367,13 @@ async function listFolder(client: Lark.Client, params: Record<string, unknown> =
   };
 }
 
-async function getFileInfo(client: Lark.Client, fileToken: string, folderToken?: string) {
-  // Use list with folder_token to find file info
-  const res = await client.drive.file.list({
-    params: folderToken ? { folder_token: folderToken } : {},
-  });
+async function getRootFileInfo(client: Lark.Client, fileToken: string) {
+  const res = await client.drive.file.list({ params: {} });
   if (res.code !== 0) {
     throw new Error(res.msg);
   }
 
-  const file = res.data?.files?.find((f) => f.token === fileToken);
+  const file = res.data?.files?.find((candidate) => candidate.token === fileToken);
   if (!file) {
     throw new Error(`File not found: ${fileToken}`);
   }
@@ -392,6 +389,58 @@ async function getFileInfo(client: Lark.Client, fileToken: string, folderToken?:
   };
 }
 
+async function getFileInfo(
+  client: Lark.Client,
+  fileToken: string,
+  type: Extract<FeishuDriveParams, { action: "info" }>["type"],
+) {
+  if (type === "shortcut") {
+    // The metadata API does not accept shortcut as a document type. Keep the existing
+    // root-list behavior so the advertised shortcut info contract does not regress.
+    return getRootFileInfo(client, fileToken);
+  }
+
+  let res: Awaited<ReturnType<Lark.Client["drive"]["meta"]["batchQuery"]>>;
+  try {
+    res = await client.drive.meta.batchQuery({
+      data: {
+        request_docs: [{ doc_token: fileToken, doc_type: type }],
+        with_url: true,
+      },
+    });
+  } catch (error) {
+    if (extractDriveApiErrorMeta(error).feishuCode === 99991672) {
+      // Existing read-only apps may not have the newer metadata scope. Preserve their
+      // root-file lookup while allowing scoped apps to resolve files in any shared folder.
+      return getRootFileInfo(client, fileToken);
+    }
+    throw error;
+  }
+  if (res.code === 99991672) {
+    return getRootFileInfo(client, fileToken);
+  }
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const file = res.data?.metas?.find(
+    (meta) => meta.doc_token === fileToken || meta.request_doc_info?.doc_token === fileToken,
+  );
+  if (!file) {
+    throw new Error(`File not found: ${fileToken}`);
+  }
+
+  return {
+    token: file.doc_token,
+    name: file.title,
+    type: file.doc_type,
+    url: file.url,
+    created_time: file.create_time,
+    modified_time: file.latest_modify_time,
+    owner_id: file.owner_id,
+  };
+}
+
 async function createFolder(client: Lark.Client, name: string, folderToken?: string) {
   // Feishu supports using folder_token="0" as the root folder.
   // We *try* to resolve the real root token (explorer API), but fall back to "0"
@@ -791,7 +840,7 @@ export function registerFeishuDriveTools(api: OpenClawPluginApi) {
                   }),
                 );
               case "info":
-                return jsonResult(await getFileInfo(client, p.file_token));
+                return jsonResult(await getFileInfo(client, p.file_token, p.type));
               case "create_folder":
                 return jsonResult(await createFolder(client, p.name, p.folder_token));
               case "move":
