feat(parse): add Feishu/Lark cloud document parser

[ryzn0518]

Summary

• Add FeishuParser that imports Feishu cloud documents (docx, wiki, sheets, bitable) into the knowledge base via URL
• Uses lark-oapi SDK for all API calls with attribute-driven block detection
• Follows the existing convert-then-parse pattern: Feishu → Markdown → MarkdownParser → VikingFS

Motivation

Feishu (飞书) is widely used for documentation in Chinese tech companies. This parser enables teams to directly import Feishu cloud documents into OpenViking's knowledge base by simply providing a URL, supporting automatic L0/L1 generation and semantic search.

What's Supported

Document Type	URL Pattern	API Used
Documents	*.feishu.cn/docx/{id}	Blocks API (attribute-driven)
Wiki pages	*.feishu.cn/wiki/{token}	Wiki API → auto-resolve → delegate
Spreadsheets	*.feishu.cn/sheets/{token}	Sheets v2/v3 API
Bitable	*.feishu.cn/base/{token}	Bitable API
Embedded sheets in docx	(auto-detected)	Sheets v2 API

Design Highlights

• Attribute-driven block detection: Instead of hard-coding 50+ block type integer constants, inspects which SDK attribute is populated per block. Unknown/future block types with text elements are auto-extracted.
• Data-driven dispatch: Document type routing (_DOC_TYPE_HANDLERS), special block handling (_SPECIAL_BLOCK_HANDLERS), and text formatting (_TEXT_FORMAT) are all table-driven.
• Lazy imports: lark-oapi is imported inside methods to avoid breaking when the optional dependency is not installed.
• Reuses existing bot-feishu dependency group — no new dependency groups needed.

Usage

# Configure credentials (env vars or ov.conf)
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

# Import documents
ov add-resource "https://example.feishu.cn/docx/doxcnABC123"
ov add-resource "https://example.feishu.cn/wiki/wikiXYZ"
ov add-resource "https://example.feishu.cn/sheets/shtcn456"
ov add-resource "https://example.feishu.cn/base/bascn789"

# Incremental update
ov add-resource "https://example.feishu.cn/docx/xxx" -to viking://resources/my_doc

Test Plan

• URL parsing for all document types (docx, wiki, sheets, base, larksuite.com)
• Attribute-driven block → markdown conversion (headings, lists, code, tables, images, etc.)
• Text style formatting (bold, italic, inline code, links, strikethrough)
• Embedded sheet extraction and empty column trimming
• Bitable field formatting (list, dict, None, string)
• End-to-end: Feishu URL → parse → VikingFS → L0/L1 → vectorization → semantic search

[CLAassistant]

All committers have signed the CLA.

[github-actions]

Failed to generate code suggestions for PR

[qin-ctx]

Good feature addition overall. The convert-then-parse pattern and data-driven dispatch design are solid choices.

One blocking issue: synchronous lark-oapi SDK calls inside async parse() will block the event loop — needs asyncio.to_thread() wrapping, consistent with how other parsers in this project handle blocking I/O (e.g., code/code.py).

See inline comments for details.

[qin-ctx]

[Bug] (blocking) Synchronous API calls block the async event loop.

_resolve_wiki_node(), _parse_docx(), _parse_sheets(), and _parse_bitable() all make synchronous HTTP calls via the lark-oapi SDK, but they are called directly from async def parse() without asyncio.to_thread() wrapping.

For large documents with pagination, these calls can block the event loop for several seconds. This project already uses asyncio.to_thread() for blocking I/O in other parsers (e.g., code/code.py:379). The same pattern should be applied here:

markdown, doc_title = await asyncio.to_thread(getattr(self, handler_name), token)

Similarly for _resolve_wiki_node on line 172.

[qin-ctx]

[Design] (non-blocking) doc_id = block.parent_id assumes the embedded sheet is a direct child of the page block.

If the embedded sheet is nested inside a container block (e.g., quote_container or table), parent_id would point to that container rather than the document. The API call to /open-apis/docx/v1/documents/{doc_id}/blocks/{block_id} would then fail or return unexpected data.

Consider passing document_id explicitly from _parse_docx() (where it's known) instead of inferring it from parent_id:

def _embedded_sheet_to_markdown(self, block, block_map=None, *, document_id=None, **_):
    doc_id = document_id or block.parent_id

[qin-ctx]

[Design] (non-blocking) Using dir(block) for block type detection is fragile.

dir() returns all attributes including methods, properties, and class-level attributes. The skip set only covers currently known non-content names. If a future lark-oapi SDK version adds a non-underscore helper method or property that returns a truthy value (e.g., to_json, validate, serialize), it would be falsely detected as a content attribute.

Consider using block_type (the integer already available on every block) as the primary dispatch mechanism, with attribute inspection as a fallback for unknown types:

# Primary: known block_type dispatch
# Fallback: attribute inspection for unknown types

This preserves the auto-compat benefit for unknown types while being robust for known ones.

[qin-ctx]

[Design] (non-blocking) Creates a new FeishuParser instance (and thus a new lark-oapi client with separate auth token lifecycle) on every URL call.

The ParserRegistry already registers a FeishuParser instance. Consider either:

• Retrieving the parser from the registry, or
• Caching the lark-oapi client at class level (as _get_client() already does per-instance)

The current approach works but creates unnecessary overhead for repeated imports.

[qin-ctx]

[Suggestion] (non-blocking) download_images and request_timeout (next line) are declared but never read by FeishuParser.

Images currently generate feishu://image/{token} placeholder links without actual downloading, and request_timeout is not passed to the lark-oapi client builder.

If these are planned for future work, consider adding a comment noting that. Otherwise, removing them avoids misleading users into thinking they have an effect.

[qin-ctx]

[Suggestion] (non-blocking) Prefix matching is slightly too broad.

path.startswith(f"/{t}") would match unintended paths like /docx-editor or /base-pricing (hypothetical non-document Feishu pages). Using segment-level matching would be more precise:

has_doc_path = any(
    path == f"/{t}" or path.startswith(f"/{t}/")
    for t in ("docx", "wiki", "sheets", "base")
)

[qin-ctx]

[Suggestion] (non-blocking) Ordered list counter doesn't reset between separate ordered lists under the same parent.

The counter is keyed by parent_id and monotonically incremented. If a document has two independent ordered lists under the same parent block, the second list continues numbering from where the first ended (e.g., 1-3 then 4-6 instead of 1-3 then 1-3).

A possible fix is to reset the counter when a non-ordered block is encountered for a given parent, or to use (parent_id, list_index) as the key.

[qin-ctx]

[Suggestion] (non-blocking) Good unit test coverage for utility functions, but no tests for the core parse methods (_parse_docx, _parse_sheets, _parse_bitable).

These methods contain pagination logic, error handling, and API response processing that would benefit from tests with mocked lark-oapi responses. For example:

@patch('lark_oapi.Client')
def test_parse_docx_with_pagination(mock_client):
    # Mock multi-page block list response
    ...

This would catch regressions in the API interaction layer without requiring live credentials.