Feishu Bitable Query

Query Feishu Bitable (多维表格) with server-side filter, sort, field selection, and multiple output formats. Activate when querying bitable records with conditio...

Security Scan

Tool is a coherent Feishu Bitable query script, but it reads a local agent config (~/.openclaw/openclaw.json) for Feishu credentials while the skill metadata does not declare that access — this mismatch warrants caution.

Purpose & Capability

The code and SKILL.md implement a Feishu Bitable query tool (server-side filters, pagination, output formats) which matches the skill name and description. However, the script automatically reads credentials from ~/.openclaw/openclaw.json (channels.feishu.appId/appSecret). The registry metadata did not declare a required config path or credentials, so the declared requirements are incomplete.

Instruction Scope

SKILL.md and the included script stay within the stated purpose: they call Feishu APIs (open.feishu.cn), perform server-side list/search, local time-filtering, formatting, and pagination. The instructions do not request unrelated system files or external endpoints beyond Feishu, and they explicitly document the auth method (the local config file).

Install Mechanism

No install step is provided (instruction-only with an included script). Nothing is downloaded or installed at runtime by the skill metadata — lowest-risk install model. The included Python script will run when invoked but there is no automatic installer or remote download.

Credentials

Metadata declares no required env vars or config paths, yet the script reads ~/.openclaw/openclaw.json to extract Feishu appId/appSecret. That file may contain other agent/channel credentials. Requesting secret access (appSecret) is proportionate to the tool's action only if the file access is explicitly declared and the user expects it; because the registry omitted this, users may unknowingly expose secrets. No unrelated external credentials or surprising environment variables are used in the code itself.

Persistence & Privilege

The skill is not always-enabled and does not request elevated or persistent platform privileges. It does not modify other skills' configurations or system-wide settings. Autonomous invocation is allowed by default (normal) but not combined with other worrisome privileges.

What to consider before installing

This skill appears to do what it claims, but pay attention: the Python script reads your agent config at ~/.openclaw/openclaw.json to obtain Feishu appId/appSecret even though the skill metadata does not list that config path. Before installing or running it, inspect that file to confirm it only contains credentials you are willing to expose to this script. Consider: (1) open ~/.openclaw/openclaw.json and verify channels.feishu contains only the expected appId/appSecret and no unrelated secrets; (2) check file permissions so only your user can read it; (3) if you prefer explicit control, run the script with explicit credentials or modify it to accept credentials via environment variables or a dedicated config path; (4) only run the script in a trusted environment (network egress goes to open.feishu.cn); (5) if the skill comes from an unknown/untrusted source, prefer to review the full script content or run it in an isolated container. The main risk here is the undeclared access to a local config file containing secrets — that mismatch is why I classify this as suspicious.

Use scripts/feishu_bitable_query.py to query Bitable tables with server-side filtering. This avoids pulling all records into context and handles pagination automatically.

When to Use This Script vs the Built-in Tool

• Use this script when: filter conditions are needed, data volume is large (>100 records), need specific output format (TSV/JSONL), or need to pipe results to other scripts
• Use the built-in tool (feishu_bitable_list_records) when: simple reads, small tables, or no filter needed

Quick Reference

SCRIPT="scripts/feishu_bitable_query.py"

# Count records matching a filter
python3 $SCRIPT --app-token APP --table-id TBL --filter 'EXPR' --count

# Query with filter, compact output
python3 $SCRIPT --app-token APP --table-id TBL \
  --filter 'EXPR' \
  --compact-fields '["字段1","字段2"]' \
  --all-pages 2>/dev/null

# Query with view (uses view's built-in filter/sort)
python3 $SCRIPT --app-token APP --table-id TBL --view-id VIEW --all-pages

# TSV output for readability
python3 $SCRIPT --app-token APP --table-id TBL \
  --compact-fields '["描述","状态"]' --format tsv --all-pages 2>/dev/null

# JSONL for piping to other tools
python3 $SCRIPT --app-token APP --table-id TBL --format jsonl --all-pages 2>/dev/null

Key Options

Option	Description
--filter	飞书 filter 表达式 (server-side)
--sort	Sort expression
--fields	API 层面只返回指定字段 (JSON array)
--view-id	使用视图的筛选排序
--compact-fields	输出时只显示指定字段，自动格式化 (JSON array)
--format	json (default), jsonl, tsv
--all-pages	自动翻页拉取全部
--count	只输出匹配总数
--include-id	输出中包含 record_id
--time-filter	本地时间过滤 (可多次), 格式见下方
--page-size	每页条数 1-500, default 500

Filter 两种模式

模式 1: 公式语法 --filter（GET List API）

CurrentValue.[字段名]="值"
AND(CurrentValue.[字段名]="值", CurrentValue.[字段2]="值2")
CurrentValue.[Owner].contains("张三")

优点：Link 字段返回完整 text。缺点：日期字段不支持范围比较。

模式 2: JSON 结构体 --filter-json（POST Search API）

--filter-json '{
  "conjunction": "and",
  "conditions": [
    {"field_name": "进度 Owner", "operator": "contains", "value": ["ou_xxx"]},
    {"field_name": "结束时间", "operator": "isGreater", "value": ["ExactDate", "1770000000000"]}
  ]
}'

支持的 operator: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty, isGreater, isLess, isGreaterEqual, isLessEqual

日期字段 value 格式: ["ExactDate", "毫秒时间戳"], ["Today"], ["TheLastMonth"], ["TheNextWeek"] 等

优点：支持日期范围过滤（服务端）。缺点：DuplexLink 字段不返回 text（只返回 record_id）。

选择建议

• 需要 Link 字段文本（如「所属任务」名称）→ 用 --filter + --time-filter（本地时间过滤）
• 大量数据只需日期过滤（不关心 Link 文本）→ 用 --filter-json（服务端过滤更高效）
• 两者结合：先用 --filter-json 做粗筛，再用 --time-filter 做精细过滤

Time Filter (本地时间过滤)

飞书 API 不支持对时间戳字段做范围比较，--time-filter 在本地过滤（拉取后过滤）。

格式：字段名:规则，可多次使用。

# 前后 N 天
--time-filter '结束时间:14d'

# 未来 N 天
--time-filter '结束时间:14d+'

# 过去 N 天
--time-filter '更新:30d-'

# 晚于/早于指定日期
--time-filter '结束时间:>2026-02-16'
--time-filter '结束时间:<2026-03-16'

# 日期范围
--time-filter '结束时间:2026-02-16~2026-03-16'

# 组合多个时间过滤
--time-filter '结束时间:14d' --time-filter '更新:30d-'

Field Auto-Formatting

--compact-fields 自动处理常见字段类型：

• User 字段: [{name: "张三"}] → "张三"
• 时间戳字段 (更新/创建时间/开始时间/结束时间): 1770574521000 → "2026-02-09"
• MultiSelect: ["opt1", "opt2"] → "opt1, opt2"
• Link 字段: [{text: "xxx"}] → "xxx"

Piping Pattern

# Query → filter locally → format
python3 $SCRIPT --app-token APP --table-id TBL \
  --filter 'CurrentValue.[Owner].contains("张三")' \
  --compact-fields '["描述","状态","更新"]' \
  --format jsonl --all-pages 2>/dev/null \
  | python3 -c "
import json,sys
for line in sys.stdin:
    r = json.loads(line)
    if r.get('状态') == '执行中':
        print(f'  - {r[\"描述\"]} ({r[\"更新\"]})')
"

Auth

Script reads credentials from ~/.openclaw/openclaw.json → channels.feishu.appId/appSecret automatically. No manual token needed.

Stderr vs Stdout

• stderr: pagination progress (Page 1: 500 records...)
• stdout: query results only

Always use 2>/dev/null when piping to suppress progress output.