Feishu, Notion or Plain Docs: Which Reads Best to an Assistant

Feed the same project tracker to an assistant three times — once as a Feishu Bitable, once as a Notion database, once as a folder of Markdown files — and you get three different failure modes. The format is not the deciding factor. Field consistency, the shape of the permission model, and what the API actually returns in a single call are what determine whether your automation works on Monday and still works in March.

This is a comparison of the three as data sources for a script, not as places for humans to type.

What an assistant actually needs from a doc system

Structure that looks tidy to a person and structure that parses well are different things. A page with a bold heading and a colored callout reads as organized to you; to a parser it is a flat list of rich-text runs. What a program needs is narrower:

• Stable identifiers. A record ID that survives a rename, so your last write does not orphan.
• Typed fields. A field is a date, a select with a fixed vocabulary, or a person — not a string you have to regex.
• An addressable schema. An endpoint that tells you what fields exist before you write.
• Delegable permissions. A machine identity that can be granted access without borrowing a human’s login.
• Honest pagination. A cursor that tells you whether there is more data.

The rest is chunking strategy, which is closer to what people call context engineering than to document management.

Feishu and DingTalk: typed tables behind an app identity

Feishu (Lark) splits the problem in two. Documents live in the Docx API as a block tree; structured data lives in Bitable, which behaves like a database with typed fields. For an assistant, Bitable is the interesting half. The records endpoint returns rows as JSON, and the fields endpoint returns the schema, so you can validate before writing rather than discovering a renamed column at 3am.

# Feishu (Lark) Open Platform: read Bitable records as the app
# Host is open.feishu.cn for Feishu, open.larksuite.com for Lark international.
APP_ID=cli_xxxxxxxxxxxx
APP_SECRET=xxxxxxxxxxxxxxxx

TOKEN=$(curl -s -X POST \
  https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json' \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" \
  | python -c 'import sys,json; print(json.load(sys.stdin)["tenant_access_token"])')

curl -s "https://open.feishu.cn/open-apis/bitable/v1/apps/$APP_TOKEN/tables/$TABLE_ID/records?page_size=500" \
  -H "Authorization: Bearer $TOKEN"

The friction is not the API, it is the identity model. You get a tenant_access_token from app credentials, which means the app sees only what the app has been granted. If a document was shared with a person and never added as a collaborator for the app, the call fails with a permission error even though the URL opens fine in your browser. Scopes like bitable:app and docx:document have to be enabled on the app, and user_access_token behaves differently from tenant tokens — a distinction that costs people an afternoon the first time. Data residency also matters: Feishu and DingTalk tenants live in specific regions, and you should confirm which one your compliance story allows before wiring anything up.

Where Feishu wins: non-engineers can own a Bitable and the schema stays typed anyway. Where it loses: prose documents still parse as a block tree with numeric block types, which you have to flatten yourself.

Notion: a block tree plus a database layer

Notion’s API has the same two halves — pages and blocks on one side, databases with typed properties on the other. Database rows are the reliable surface. Page bodies are a nested tree of block objects, and inline formatting arrives as rich-text arrays with annotations, so anything you extract needs flattening before it is useful to a model.

import os, requests

H = {"Authorization": f"Bearer {os.environ['NOTION_TOKEN']}",
     "Notion-Version": "2022-06-28",
     "Content-Type": "application/json"}

rows, cursor = [], None
while True:
    body = {"page_size": 100, **({"start_cursor": cursor} if cursor else {})}
    r = requests.post(f"https://api.notion.com/v1/databases/{DB_ID}/query",
                      headers=H, json=body, timeout=30)
    r.raise_for_status()
    data = r.json()
    rows.extend(data["results"])
    if not data.get("has_more"):
        break
    cursor = data["next_cursor"]

Two things bite people here. First, an integration only sees pages and databases that were explicitly shared with it; an unshared page returns a not-found error, not a permission-denied error, which sends you looking for a typo in the ID. Second, the API is rate-limited and paginated, so any sync job needs backoff and a cursor you persist between runs — restart from scratch and you will hit the limit rather than finish. Property names are also case- and whitespace-sensitive in a way that a select column tolerates and a formula column does not.

Where Notion wins: a well-kept database is as parseable as anything Bitable offers, and the Notion-Version header makes API changes explicit rather than silent. Where it loses: mixed teams tend to keep the important prose in pages, and pages are the weakest surface in all three systems.

Plain Markdown: boring, and that is the point

A folder of Markdown files has no API, no per-document permissions, and no schema — until you add frontmatter and enforce it yourself. In exchange you get deterministic parsing, real diffs, and zero vendor coupling. If the repo is already your source of truth, this is often the highest-reliability option for an assistant, because nothing can rearrange the document underneath you between two runs.

---
doc_type: project
project_id: acme-billing
owner: dana@example.com
status: active          # active | paused | done
reviewed_at: 2026-02-14
---

That comment is doing real work: it is the vocabulary a validator checks against. Without it, status: Active, status: in progress and status: WIP all appear within a month and your assistant silently misclassifies work. The costs are real too — no query engine (you grep, index, or build embeddings), duplicates appear as billing-v2-final.md, and a 4,000-line document chunks badly unless you split on headings.

The comparison, on the axes that matter

Ranked purely on how reliably an assistant extracts structured facts, the order is the same inside all three systems: typed table first, typed database second, Markdown with validated frontmatter third, and prose documents last. The platform matters less than whether the data sits in rows.

Which is why the recommendation is by team profile, not by product:

Switching platforms to improve parse reliability is almost never worth it. Freezing field names in the platform you already pay for is.

What to do next

1. Freeze the field names on one collection this week. Pick the tracker your assistant reads most, write the canonical field list and allowed values into a file in the repo, and treat that file as the contract.
2. Give the assistant its own machine identity. A Feishu app with a tenant token, or a dedicated Notion integration. Then deliberately request a document you never shared with it and confirm the error you get matches your expectations.
3. Check pagination handling before you trust a sync. Run your script twice against the same collection and assert the row counts match. Cursor bugs show up as quiet duplicates, not crashes.
4. Snapshot to Markdown weekly. A flat export per collection is your escape hatch if an API version changes or a permission is revoked mid-quarter.
5. If you are starting from zero on Feishu or DingTalk, borrow a schema instead of designing one. The Feishu Template Marketplace is a $19 one-time pack of twenty-plus ready-made templates covering project tracking, OKRs, meeting notes and documentation. The templates themselves are not the point; the pre-agreed field names are.

If the sync keeps failing after that, the problem is usually the machine identity and not the format — the same triage logic in Triage Habits for Automation That Fails While You Sleep applies here.

Get Feishu Template Marketplace

Feishu Template Marketplace — $19, one-time payment, instant download. See the full breakdown on the review page.

Related reading

• The Ultimate Guide to AI Automation 2026
• How I Built a 10-Product Digital Business
• Building an AI Content Factory