feishu-bitable-task-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feishu Bitable Task Manager

Feishu Bitable 任务管理器

Use this skill to read/write tasks in a Feishu Bitable “task status table” while staying compatible with its schema conventions.

使用该Skill在飞书多维表格的「任务状态表」中读写任务，同时兼容其结构规范。

Path Convention

路径规范

Canonical install and execution directory:

~/.agents/skills/feishu-bitable-task-manager/

. Run commands from this directory:

bash

cd ~/.agents/skills/feishu-bitable-task-manager

One-off (safe in scripts/loops from any working directory):

bash

(cd ~/.agents/skills/feishu-bitable-task-manager && npx tsx scripts/bitable_task.ts --help)

标准安装与执行目录：

~/.agents/skills/feishu-bitable-task-manager/

。请从该目录运行命令：

bash

cd ~/.agents/skills/feishu-bitable-task-manager

一次性执行（可在任意工作目录的脚本/循环中安全运行）：

bash

(cd ~/.agents/skills/feishu-bitable-task-manager && npx tsx scripts/bitable_task.ts --help)

Quick start

快速开始

Run:

bash

npx tsx scripts/bitable_task.ts <subcommand> [flags]

运行：

bash

npx tsx scripts/bitable_task.ts <subcommand> [flags]

Required env

必需环境变量

```
FEISHU_APP_ID
```
,
```
FEISHU_APP_SECRET
```
```
TASK_BITABLE_URL
```
Optional:
```
FEISHU_BASE_URL
```
Optional:
```
TASK_FIELD_*
```
(override task table column names)

```
FEISHU_APP_ID
```
、
```
FEISHU_APP_SECRET
```
```
TASK_BITABLE_URL
```
可选：
```
FEISHU_BASE_URL
```
可选：
```
TASK_FIELD_*
```
（覆盖任务表列名）

Key defaults (compat rules)

核心默认规则（兼容性规则）

Treat date presets as literal strings:
```
Today
```
,
```
Yesterday
```
,
```
Any
```
(
```
Any
```
means no date constraint).

Prefer fetching by

--task-id

--biz-task-id

when possible (it overrides

--app/--scene/--status/--date

Ignore view filtering by default; use view filtering only when explicitly enabled (see
```
references/task-fetch.md
```
).

Keep only decoded rows with

TaskID != 0

and at least one of

Params/ItemID/BookID/URL/UserID/UserName

Allow comma-separated priority lists for
```
--status
```
/
```
--scene
```
.
```
fetch
```
supports
```
--limit
```
; earlier scene/status values are filled first when
```
--limit
```
is set.
```
claim
```
is single-task only; do not use
```
--limit
```
.
```
--candidate-limit
```
only controls candidate attempts (see
```
references/task-claim.md
```
).
```
fetch
```
and
```
claim
```
both split comma-separated
```
--scene
```
values and query each scene in order (do not treat the full CSV as one literal scene).
When ingesting JSON/JSONL, pass through keys that match column names; map
```
CDNURL
```
/
```
cdn_url
```
into
```
Extra
```
when present.

将日期预设视为字面字符串：
```
Today
```
、
```
Yesterday
```
、
```
Any
```
（
```
Any
```
表示无日期限制）。
尽可能优先通过
```
--task-id
```
/
```
--biz-task-id
```
获取任务（它会覆盖
```
--app/--scene/--status/--date
```
参数）。
默认忽略视图过滤；仅在显式启用时使用视图过滤（详见
```
references/task-fetch.md
```
）。

仅保留

TaskID != 0

且至少包含

Params/ItemID/BookID/URL/UserID/UserName

中一项的解码行。

允许
```
--status
```
/
```
--scene
```
使用逗号分隔的优先级列表。
```
fetch
```
命令支持
```
--limit
```
参数；设置
```
--limit
```
时，会优先填充较早的场景/状态值对应的任务。
```
claim
```
命令仅支持单个任务；请勿使用
```
--limit
```
参数。
```
--candidate-limit
```
仅控制候选任务的尝试次数（详见
```
references/task-claim.md
```
）。
```
fetch
```
和
```
claim
```
命令都会拆分逗号分隔的
```
--scene
```
值，并按顺序查询每个场景（不会将完整的CSV视为单个字面场景）。
导入JSON/JSONL时，会直接传递与列名匹配的键；若存在
```
CDNURL
```
/
```
cdn_url
```
，则将其映射到
```
Extra
```
字段。

Commands

命令

Fetch

获取任务（Fetch）

bash

npx tsx scripts/bitable_task.ts fetch --app com.smile.gifmaker --scene 综合页搜索 --status pending --date Today --limit 10
npx tsx scripts/bitable_task.ts fetch --task-id "1326,1327" --raw
npx tsx scripts/bitable_task.ts fetch --biz-task-id ext-20240101-001 --raw

bash

npx tsx scripts/bitable_task.ts fetch --app com.smile.gifmaker --scene 综合页搜索 --status pending --date Today --limit 10
npx tsx scripts/bitable_task.ts fetch --task-id "1326,1327" --raw
npx tsx scripts/bitable_task.ts fetch --biz-task-id ext-20240101-001 --raw

Claim (multi-worker safe)

认领任务（Claim，支持多 Worker 安全操作）

bash

npx tsx scripts/bitable_task.ts claim \
  --app com.tencent.mm \
  --scene 个人页搜索,综合页搜索 \
  --device-serial <serial> \
  --status pending,failed \
  --date Today \
  --candidate-limit 5

Claim behavior details are in

references/task-claim.md

bash

npx tsx scripts/bitable_task.ts claim \
  --app com.tencent.mm \
  --scene 个人页搜索,综合页搜索 \
  --device-serial <serial> \
  --status pending,failed \
  --date Today \
  --candidate-limit 5

认领行为的详细说明请见

references/task-claim.md

。

Update

更新任务（Update）

bash

npx tsx scripts/bitable_task.ts update --task-id 180413 --status running --device-serial <serial> --dispatched-at now
npx tsx scripts/bitable_task.ts update --input updates.jsonl

bash

npx tsx scripts/bitable_task.ts update --task-id 180413 --status running --device-serial <serial> --dispatched-at now
npx tsx scripts/bitable_task.ts update --input updates.jsonl

Create

创建任务（Create）

bash

npx tsx scripts/bitable_task.ts create \
  --input tasks.jsonl \
  --app com.smile.gifmaker \
  --scene 单个链接采集 \
  --status pending \
  --date YYYY-MM-DD \
  --skip-existing BizTaskID

bash

npx tsx scripts/bitable_task.ts create \
  --input tasks.jsonl \
  --app com.smile.gifmaker \
  --scene 单个链接采集 \
  --status pending \
  --date YYYY-MM-DD \
  --skip-existing BizTaskID

Drama Fetch (read-only)

剧集数据获取（Drama Fetch，只读）

Fetch rows from source drama Bitable by optional BookID filter. Use

--format meta

when callers need normalized drama metadata fields:

bash

npx tsx scripts/drama_fetch.ts --bitable-url "<DRAMA_BITABLE_URL>" --book-id "id1,id2" --format meta

通过可选的BookID过滤器从源剧集多维表格获取数据行。当调用方需要标准化的剧集元数据字段时，使用

--format meta

参数：

bash

npx tsx scripts/drama_fetch.ts --bitable-url "<DRAMA_BITABLE_URL>" --book-id "id1,id2" --format meta

Derive tasks from a source Bitable (原始多维表格)

从源多维表格生成任务

sync

accepts either

--input

--bitable-url

(optionally with

--book-id

) and handles task creation:

bash

npx tsx scripts/drama_sync_task.ts \
  --bitable-url "https://.../base/SOURCE_APP?table=SOURCE_TABLE" \
  --task-url "https://.../base/TASK_APP?table=TASK_TABLE" \
  --app com.smile.gifmaker \
  --extra "test" \
  --params-list \
  --limit 10 \
  --skip-existing \
  --date 2026-02-10

--date YYYY-MM-DD

sets the task date for created records and for

--skip-existing

dedup filtering. Defaults to today when omitted.

Params mode flags (mutually exclusive):

```
--params-list
```
— one task per source row;
```
Params
```
is a JSON array of all search terms, e.g.
```
["好一个乖乖女","段休冥 鹿鸣于"]
```
.
```
--params-split
```
— one task per search term; uses the same dedup logic as
```
--params-list
```
but creates separate tasks, each with a plain string
```
Params
```
.
```
--params-actor
```
— one task per source row;
```
Params
```
uses only
```
主角名
```
.

sync

命令接受

--input

或

--bitable-url

参数（可搭配

--book-id

），并处理任务创建：

bash

npx tsx scripts/drama_sync_task.ts \
  --bitable-url "https://.../base/SOURCE_APP?table=SOURCE_TABLE" \
  --task-url "https://.../base/TASK_APP?table=TASK_TABLE" \
  --app com.smile.gifmaker \
  --extra "test" \
  --params-list \
  --limit 10 \
  --skip-existing \
  --date 2026-02-10

--date YYYY-MM-DD

参数会为创建的记录设置任务日期，并用于

--skip-existing

的去重过滤。若省略该参数，默认使用今日日期。

参数模式标志（互斥）：

```
--params-list
```
— 每个源数据行对应一个任务；
```
Params
```
字段为包含所有搜索词的JSON数组，例如
```
["好一个乖乖女","段休冥 鹿鸣于"]
```
。
```
--params-split
```
— 每个搜索词对应一个任务；使用与
```
--params-list
```
相同的去重逻辑，但会创建独立的任务，每个任务的
```
Params
```
为纯字符串。
```
--params-actor
```
— 每个源数据行对应一个任务；
```
Params
```
字段仅使用「主角名」。

Resources

参考资源

Read
```
references/task-fetch.md
```
for filters, pagination, validation, and field mapping.
Read
```
references/task-claim.md
```
for cross-machine safe task claiming.
Read
```
references/task-update.md
```
for status updates, timing fields, and batch update rules.
Read
```
references/task-create.md
```
for create payload rules and batch create behavior.
Read
```
references/feishu-integration.md
```
for Feishu API endpoints and request/response payloads.

Use

scripts/bitable_task.ts

scripts/drama_fetch.ts

scripts/drama_sync_task.ts

as the source of truth for flags and behavior.

阅读
```
references/task-fetch.md
```
了解过滤器、分页、验证和字段映射规则。
阅读
```
references/task-claim.md
```
了解跨机器安全认领任务的规则。
阅读
```
references/task-update.md
```
了解状态更新、时间字段和批量更新规则。
阅读
```
references/task-create.md
```
了解创建负载规则和批量创建行为。
阅读
```
references/feishu-integration.md
```
了解飞书API端点和请求/响应负载。

请将

scripts/bitable_task.ts

scripts/drama_fetch.ts

scripts/drama_sync_task.ts

作为参数和行为的权威参考。