byted-viking-aisearch-feishu

Viking AISearch Feishu Skill

You are an assistant focused on searching and reading content for Feishu "Cloud Docs / Spreadsheets / Bitables / Wiki". You must be strictly read-only and must not implement any write operations.

🎯 Core Features

Search: Aggregate search across cloud docs (doc/docx), spreadsheets (sheet), bitables (bitable), and wiki spaces and nodes (wiki)
Read: Read the raw text of doc/docx; read preview range data of sheet; read bitable table structure and record samples; read wiki nodes (automatically redirect to the associated object content) and the list of child nodes of a wiki space

🚦 Scenario Routing

User intent example	Matched scenario	Primary method	Output
"Search Feishu for materials about 'Q4'"	Aggregate search	`search_items()` / `search_docs()`	Return item list (title/type/token/url/source…)
"Read the content of this docx / sheet / base"	Content reading	`fetch_raw_content()`	Return `content`(plain text/TSV/JSON summary)
"List the wiki spaces I have permission to access"	Wiki spaces	`list_wiki_spaces()` / `search_wiki_spaces()`	Return space list
"List the child nodes of a certain wiki space"	Space child nodes	`list_wiki_space_nodes()`	Return node list

📚 Main Interface Usage

1) Initialization

from scripts.feishu_search import FeishuDocSearch

# 方式一：使用环境变量（推荐）
# export LARK_USER_ACCESS_TOKEN="u-xxxxxxxxxxxxxxxxxxxxxxxx"
tool = FeishuDocSearch()

# 方式二：显式传入 access_token
tool = FeishuDocSearch(access_token="u-xxx")

2) Aggregate search - `search_items()`

Function: Search cloud docs/spreadsheets/bitables by keyword, and optionally aggregate wiki nodes and wiki spaces

Parameters：

Parameter name	Type	Required	Default value	Description
`search_key`	`str`	Yes	-	Search keyword
`count`	`int`	No	`10`	Number of results to return (after pagination)
`offset`	`int`	No	`0`	Offset (after pagination)
`types`	`List[str]`	No	`["doc","docx","sheet","bitable","wiki","wiki_space"]`	Set of search types
`owner_ids`	`List[str]`	No	`None`	Owner Open ID filter (only for suite docs search)
`chat_ids`	`List[str]`	No	`None`	Group chat ID filter (only for suite docs search)
`space_id`	`str`	No	`None`	Only search nodes within this wiki space (wiki node search)

Return semantics：

As long as at least one search path returns usable results,search_items() can still return success=true
If a certain path fails or degrades, the result will be explicitly exposed in data.warnings instead of being silently swallowed
Common warning keys include:suite_error、suite_fallback_error、wiki_nodes_error、wiki_spaces_error、wiki_spaces_warning

Typical partial success return：

{
  "success": true,
  "message": "搜索成功",
  "data": {
    "total": 3,
    "has_more": false,
    "items": [],
    "warnings": {
      "suite_error": {
        "message": "文档套件搜索失败",
        "error": {}
      }
    }
  }
}

3) Compatibility interface - `search_docs()`

search_docs() is a historical compatibility interface, implemented internally based on search_items() , and by default includes doc/docx/sheet/bitable/wiki。

Usage example：

# 基础搜索
result = tool.search_docs(search_key="项目计划")

# 指定类型搜索
result = tool.search_docs(
    search_key="季度报告",
    docs_types=["doc", "docx", "sheet", "bitable", "wiki"]
)

# 分页搜索
result = tool.search_docs(
    search_key="技术方案",
    count=20,
    offset=0
)

Return example：

{
  "success": true,
  "message": "搜索成功",
  "data": {
    "total": 12,
    "has_more": false,
    "warnings": {
      "wiki_error": {
        "message": "权限不足，请为应用开通 wiki 搜索相关权限",
        "error": {
          "type": "permission_denied",
          "detail": "HTTP 403: ..."
        }
      }
    },
    "items": [
      {
        "docs_token": "your_docs_token_xxx",
        "docs_type": "docx",
        "owner_id": "ou_xxx",
        "title": "项目计划.docx",
        "url": "https://xxx.feishu.com/docx/xxx",
        "source": "suite_docs"
      },
      {
        "docs_token": "your_docs_token_xxx",
        "docs_type": "wiki",
        "title": "用户操作手册",
        "url": "https://xxx.feishu.com/wiki/xxx",
        "space_id": "your_space_id_xxx",
        "obj_type": "docx",
        "obj_token": "your_obj_token_xxx",
        "source": "wiki_nodes"
      }
    ]
  }
}

3.5) Search wiki nodes - `search_wiki_nodes()`

Function: Search wiki documents by wiki node title/content

Parameters：

Parameter Name	Type	Required	Default Value	Description
`keyword`	`str`	Yes	-	Search keyword
`count`	`int`	No	`None`	Number of results to return
`offset`	`int`	No	`None`	Offset
`space_id`	`str`	No	`None`	Specify the wiki knowledge space

Usage Example：

result = tool.search_wiki_nodes(
    keyword="用户操作手册",
    space_id="your_space_id_xxx"
)

Response Example：

{
  "success": true,
  "message": "搜索成功",
  "data": {
    "total": 1,
    "has_more": false,
    "items": [
      {
        "docs_token": "your_docs_token_xxx",
        "docs_type": "wiki",
        "title": "用户操作手册",
        "url": "https://xxx.feishu.com/wiki/xxx",
        "space_id": "your_space_id_xxx",
        "obj_type": "docx",
        "obj_token": "your_obj_token_xxx",
        "source": "wiki_nodes"
      }
    ]
  }
}

4) Content Reading - `fetch_raw_content()`

Supported docs_type：

doc / docx: Read the original content (raw_content)
sheet: Read the preview range data of the spreadsheet (defaults to the first worksheet A1:Z100, can pass range_a1/max_rows/max_cols）
bitable: Read the list of data tables in the bitable, and read a sample of records from one data table (can pass table_id/page_size/page_token）
wiki: Read a knowledge base node; if the node's associated object is doc/docx/sheet/bitable, the associated object's content will be automatically read
wiki_space: Read the list of child nodes in the knowledge base space (supports pagination)

Additional Notes：

search_wiki_spaces() When the pagination limit is reached, data.has_more=truewill be returned, and in data.warnings.pagination_truncated it is noted that the results may be incomplete
fetch_sheet_content() When the metainfo endpoint fails but the query endpoint succeeds, success=trueis still returned, and in data.warnings.metainfo_error the degradation information is retained
fetch_bitable_content() When "the table list is retrieved successfully but the record sample fails to be read", success=true and message=部分成功：已获取数据表列表，但记录样本读取失败are returned, and at the same time in data.warnings.records_error the failure details are exposed

Usage Example：

# 读取 docx
result = tool.fetch_raw_content(
    docs_type="docx",
    docs_token="your_docs_token_xxx"
)

# 读取 sheet（可指定范围）
sheet_result = tool.fetch_raw_content(
    docs_type="sheet",
    docs_token="your_sheet_token_xxx",
    range_a1="Sheet1!A1:D50"
)

# 读取 bitable（可指定表与分页）
base_result = tool.fetch_raw_content(
    docs_type="bitable",
    docs_token="your_app_token_xxx",
    table_id="tbl_xxx",
    page_size=50
)

Response Example (docx)：

{
  "success": true,
  "message": "获取成功",
  "data": {
    "content": "Q4项目计划\n一、项目背景..."
  }
}

🔑 Authentication

Use Authorization: Bearer <LARK_USER_ACCESS_TOKEN>(user access token)
The access token is injected into the environment variable viking_feishu_oauth_provider via LARK_USER_ACCESS_TOKEN, enabling dynamic retrieval

📝 Suggested Usage Flow

Typical flow: search and read content

# 1. 搜索
search_result = tool.search_docs(search_key="项目计划")
if not search_result.get("success"):
    print(search_result.get("message"))
    raise SystemExit

items = search_result.get("data", {}).get("items", [])
if not items:
    print("未找到相关文档")
    raise SystemExit

# 2. 获取第一个文档的 token 和类型
first_item = items[0]
docs_token = first_item["docs_token"]
docs_type = first_item["docs_type"]

# 3. 读取内容
content_result = tool.fetch_raw_content(docs_type=docs_type, docs_token=docs_token)
print(content_result)

📋 Document Type Enumeration

docs_type	Description
`doc`	Legacy Feishu document
`docx`	New Feishu document
`sheet`	Spreadsheet
`bitable`	Bitable
`wiki`	Feishu wiki node (can automatically read the associated object's content)
`wiki_space`	Knowledge base space (can read the list of child nodes)

Get wiki node information - `get_wiki_node()`

Function: Get detailed information about a wiki node, including the title, associated object type, etc.

Usage Example：

result = tool.get_wiki_node(node_token="your_node_token_xxx")

Response Example：

{
  "success": true,
  "message": "获取成功",
  "data": {
    "node_token": "your_node_token_xxx",
    "title": "文档标题",
    "obj_type": "docx",
    "obj_token": "your_obj_token_xxx",
    "node_type": "origin",
    "space_id": "your_space_id_xxx",
    "creator": "ou_xxx",
    "owner": "ou_xxx"
  }
}

🚨 Error Handling

Error Type	Identification Method	Returned Message
Authentication failed	`401`/`Unauthorized`	"Authentication failed. Please check whether access_token is valid or has expired"
Insufficient permissions	`403`/`Forbidden`	"Insufficient permissions. Please enable search-related permissions for the application"
Request timeout	Contains `timeout`	"Request timed out. Please try again later"
Search parameter error	`search_key` is empty	"search_key cannot be empty"
Unsupported document type	Unknown `docs_type`	"Unsupported docs_type. Only doc/docx/sheet/bitable/wiki/wiki_space are supported"

About this skill

🎯 Core Features

🚦 Scenario Routing

📚 Main Interface Usage

1) Initialization

2) Aggregate search - search_items()

3) Compatibility interface - search_docs()

3.5) Search wiki nodes - search_wiki_nodes()

4) Content Reading - fetch_raw_content()

🔑 Authentication

📝 Suggested Usage Flow

📋 Document Type Enumeration

Get wiki node information - get_wiki_node()

🚨 Error Handling

2) Aggregate search - `search_items()`

3) Compatibility interface - `search_docs()`

3.5) Search wiki nodes - `search_wiki_nodes()`

4) Content Reading - `fetch_raw_content()`

Get wiki node information - `get_wiki_node()`