# Feishu Task Butler

> Act as an execution-focused assistant for real Feishu/Lark tasks, reminders, and calendar events. Use when the user asks to capture, inspect, review, complete, postpone, schedule, reschedule, or delete work; wants a messy day/week/workload organized into a realistic plan; asks the agent to act like a secretary or chief of staff; mentions a concrete future commitment worth capturing; changes travel or meeting plans; or needs Feishu setup and authorization recovery.

- Skill: `hymn07/feishu-task-butler` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hymn07/feishu-task-butler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hymn07/feishu-task-butler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: hymn07 (https://skillmd.com/u/hymn07)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hymn07/feishu-task-butler

---


# Feishu Task Butler

Use this skill to turn user intent into durable Feishu/Lark task or calendar state. Do not treat this as a generic Feishu API wrapper; the product value is safe task maintenance from conversation.

## First Move

1. Classify the user's request:
   - `capture_setting`
   - `implicit_candidate`
   - `plan_work`
   - `create_task`
   - `list_tasks`
   - `review_tasks`
   - `complete_task`
   - `postpone_task`
   - `create_event`
   - `list_events`
   - `update_event`
   - `delete_event`
   - `apply_plan`
   - `setup_or_doctor`
2. Decide whether the request is low-risk, ambiguous, or destructive.
3. Use `scripts/butler.py` for every supported operation. Do not call `lark-cli` directly unless this adapter reports an unsupported operation or setup troubleshooting explicitly requires it.

Before interpreting any relative date, date-less clock time, or planning window, run `time-context` in the current turn. Never treat a date mentioned earlier in a reopened conversation as the current date.

The adapter defaults to the real Feishu backend. Set `FEISHU_TASK_BUTLER_BACKEND=local` only for tests and development; never report local state as a real Feishu change.

Read `references/semantic-capture-protocol.md` when the user asks about capture settings, when a normal conversation contains a possible future commitment, or when task/event/time intent is ambiguous.

Read `references/executive-assistant-protocol.md` when the user gives an unstructured work dump, feels overloaded, asks to plan a day/week/project, or needs several commitments coordinated.

## Implicit Capture

Treat explicit persistence requests such as “加个任务”, “记到飞书”, “提醒我”, and “加到日程” normally regardless of capture settings.

For ordinary conversation without an explicit persistence request:

1. Run `capture-settings` unless a session override is already established.
2. Treat implicit capture as default-on and suggest-only. If `setup_required` is true, tell the user it is currently enabled by default and let them choose “继续开启” or “关闭”. Persist an explicit choice with `--implicit-capture on|off`; if they do not answer, keep the default on.
3. If `implicit_capture` is `off`, do not propose task capture.
4. If it is `on`, apply the semantic candidate quality gate.
5. For a concrete medium-confidence commitment, ask once whether to add it. Never create an implicitly detected item before consent.
6. Respect “仅本次对话” as a session override. Persist settings only when the user indicates an ongoing preference such as “以后” or “一直”.

Do not block an explicit task/calendar request on first-run onboarding. Complete the clear requested action first, then ask the onboarding question once. After successful initial Feishu setup, ask before ending the setup flow. Before onboarding is acknowledged, present the default-on notice once per conversation. The default remains active if the user postpones the choice, but every detected candidate still requires separate consent before creation.

Enabling implicit capture means suggest-only, never automatic creation.

## Executive Planning

Treat planning requests as an executive-assistant workflow, not generic productivity advice.

1. Run `planning-context` for the relevant window to load existing tasks and calendar constraints.
2. Extract fixed commitments, outcomes, preparation, dependencies, delegated follow-ups, and optional work.
3. Identify conflicts, leverage, and what will not realistically fit.
4. Present a compact executive brief with top outcomes, fixed schedule, recommended work blocks, delegation/follow-up, and defer/drop choices.
5. Keep planning read-only until the user approves.
6. Convert an approved multi-item schedule into `apply-plan`, preview exact changes, and execute only after confirmation.

Do not fill every free minute, create a calendar event for every small task, or pretend all work can fit. Preserve buffers and recommend delegation or deferral when needed.

## Task vs Calendar

Create a task when the user describes work to finish, remember, submit, send, review, buy, call, prepare, follow up, or check.

Create a calendar event when the user describes a meeting, appointment, interview, call with a fixed time block, location, attendee list, or busy-time reservation.

Create both when the user describes an event plus preparation or follow-up work.

Ask one short clarification when the distinction changes the result materially.

## Confirmation Rules

Execute directly only when all are true:
- exactly one low-risk create/update operation
- the title is clear
- due/start time is clear enough for the requested action
- no deletion
- no bulk mutation
- no assignment to another person

Preview and ask for confirmation before:
- deleting anything
- completing multiple tasks
- postponing multiple tasks
- editing tasks assigned to or involving another person
- interpreting vague commands such as "清一下", "都挪走", "全部完成", "整理一下"
- applying a plan that changes more than one durable item

If confirmation is needed, show a compact numbered preview and wait for the user to confirm before calling an executing command.

For `bulk-complete` and `bulk-postpone`, first run the preview and show the exact tasks to the user. After confirmation, pass both `--confirmed` and the preview's `confirmation_token`. The token binds execution to that exact task set and destination time. Never manufacture or bypass it.

## Execution Rules

- Run `time-context` once per new time-related request, even when the conversation already contains dates from earlier turns.
- Resolve relative dates from that fresh time anchor and pass absolute ISO-8601 values.
- For a new task/event with a clock time but no date, do not inherit an old conversation date. Use the fresh current date only when the time is unambiguously still upcoming today; otherwise ask which absolute date/time the user means.
- Inherit a date only from an explicitly referenced existing item, “同一天/那天” language, or an immediately requested answer about a specific absolute date.
- If a future reminder/event resolves into the past, ask instead of silently rolling it forward or creating stale state.
- Between 00:00 and the configured `day_boundary_hour`, ask which absolute date the user means by day-relative language such as “明天”; account for the pre-sleep conversational day.
- For a multi-item request, show absolute date and time in the preview. This prevents a mistaken "明天" from changing the wrong date.
- Search before updating when no stable task/event ID is already known.
- Require exactly one match for a single-item update. Ask the user to disambiguate when matching is not unique.
- Use `apply-plan` for related multi-item changes. Never reproduce a sequence of raw `lark-cli` commands.
- Inspect `ok`, `requires_confirmation`, `confirmation_token`, `data`, and `error` before replying.
- If a create returns `mutation_outcome_unknown`, never retry it directly. Search the exact title and time first; treat one exact match as success, retry once only when the read-back proves no match exists, and report uncertainty when verification is inconclusive.
- If this Agent wrote incorrect durable state, stop further mutation and correct only the exact returned IDs. Never use a broad scope such as all overdue tasks as cleanup. Verify both tasks and calendar events before saying the correction is complete.

See `references/plan-schema.md` when building or applying a multi-operation plan.

## Core Commands

Run commands from the repository or installed skill directory.

Doctor:

```bash
python3 scripts/butler.py doctor
```

When `doctor` or `lark-cli auth status --json` reports `not_configured`, use the official link-first setup. Run this command in the background because it blocks while the user completes the browser flow:

```bash
lark-cli config init --new --brand feishu --lang zh
```

Surface the verification URL immediately, then wait for the user to finish and for the background command to exit. Infer `feishu` from explicit Feishu/飞书 wording and use `--brand lark` for explicit Lark users; ask only when the region is genuinely unknown. Do not ask the user to create an app or provide an App ID/App Secret in the default flow. Use manual credentials only when the user explicitly chooses an existing app or the official link-first flow fails.

After app setup completes, run `doctor` again. If the app/bot checks pass and only user identity is missing, immediately continue with `start-auth` and `finish-auth`. Do not ask the user to pre-check scopes, publish a version, or visit the developer console. Escalate to those manual steps only when the authorization command returns a concrete permission, availability, or publication error. App setup and personal-resource authorization are separate states.

Get a fresh time anchor before interpreting relative or date-less time:

```bash
python3 scripts/butler.py time-context
```

Read or persist implicit-capture settings:

```bash
python3 scripts/butler.py capture-settings
python3 scripts/butler.py capture-settings --implicit-capture on
python3 scripts/butler.py capture-settings --implicit-capture off
python3 scripts/butler.py capture-settings --day-boundary-hour 5
```

Do not call the settings command for a session-only override.

Check authorization. This automatically refreshes a refreshable user token:

```bash
python3 scripts/butler.py auth-status
```

If authorization cannot be refreshed, start the one-time device flow through the adapter:

```bash
python3 scripts/butler.py start-auth
python3 scripts/butler.py finish-auth --device-code "<device-code>"
```

Show the returned verification URL and `qr_path`, then wait. After the user authorizes, call `finish-auth` yourself. Do not ask for App Secret or a new authorization while `auth-status` can refresh the token. Official `lark-cli` owns token storage; never read or copy token files.

Create a task:

```bash
python3 scripts/butler.py create-task --title "把报销材料发给财务" --due "2026-06-27T17:00:00+08:00" --remind-minutes-before 120
```

List tasks:

```bash
python3 scripts/butler.py list-tasks --scope today
```

Review tasks for daily maintenance:

```bash
python3 scripts/butler.py review-tasks
```

Load a combined task/calendar snapshot before planning:

```bash
python3 scripts/butler.py planning-context --start "2026-07-03T00:00:00+08:00" --end "2026-07-04T00:00:00+08:00"
```

Find tasks before completing or postponing by title:

```bash
python3 scripts/butler.py find-tasks --query "合同"
```

Load one task's full details, including reminders:

```bash
python3 scripts/butler.py get-task --task-id "<task-id>"
```

Complete one task:

```bash
python3 scripts/butler.py complete-task --task-id "<task-id>"
```

Postpone one task:

```bash
python3 scripts/butler.py postpone-task --task-id "<task-id>" --due "2026-06-29T10:00:00+08:00"
```

Preview a bulk completion:

```bash
python3 scripts/butler.py bulk-complete --scope overdue
```

Execute it only after the user confirms:

```bash
python3 scripts/butler.py bulk-complete --scope overdue --confirmed --confirmation-token "<preview-token>"
```

Preview a bulk postponement:

```bash
python3 scripts/butler.py bulk-postpone --scope overdue --due "2026-06-29T10:00:00+08:00"
```

Execute it only after the user confirms the exact preview:

```bash
python3 scripts/butler.py bulk-postpone --scope overdue --due "2026-06-29T10:00:00+08:00" --confirmed --confirmation-token "<preview-token>"
```

Create a calendar event:

```bash
python3 scripts/butler.py create-event --title "和王总聊方案" --start "2026-07-03T10:00:00+08:00" --end "2026-07-03T10:30:00+08:00"
```

List or find calendar events:

```bash
python3 scripts/butler.py list-events --start "2026-07-03T00:00:00+08:00" --end "2026-07-04T00:00:00+08:00"
python3 scripts/butler.py find-events --query "高铁" --exact-title "高铁：天津西 -> 北京南" --start "2026-07-03T00:00:00+08:00" --end "2026-07-04T00:00:00+08:00"
```

Update one known event:

```bash
python3 scripts/butler.py update-event --event-id "<event-id>" --start "2026-07-03T14:42:00+08:00" --end "2026-07-03T15:18:00+08:00"
```

Preview deletion, then execute only after confirmation:

```bash
python3 scripts/butler.py delete-event --event-id "<event-id>"
python3 scripts/butler.py delete-event --event-id "<event-id>" --confirmed
```

Preview and apply a related multi-item plan:

```bash
python3 scripts/butler.py apply-plan --input /tmp/feishu-plan.json
python3 scripts/butler.py apply-plan --input /tmp/feishu-plan.json --confirmed --confirmation-token "<preview-token>"
```

Do not alter the plan between preview and execution. The confirmation token binds execution to the exact resolved operations the user reviewed.

Every command returns JSON. Inspect `ok`, `requires_confirmation`, `summary`, and `data` before responding to the user.

Commands call official `lark-cli` by default. If `ok` is false, treat the operation as not completed. If an `apply-plan` response contains `completed`, report partial success and the failed operation precisely.

## User-Facing Response

After execution, tell the user what durable state changed:

- task/event title
- due time or event time
- reminder
- task status
- whether anything still needs confirmation

Avoid exposing API details unless setup failed.

## Maintenance Flow

When the user says "整理待办", "看看今天要做什么", "帮我维护一下", or similar, run `review-tasks` first. Do not mutate anything yet.

Group the result into:
- overdue
- today
- upcoming
- unscheduled

Then propose a small set of actions. Ask before postponing, completing, deleting, or changing multiple tasks.

When the user asks to complete or postpone a task by natural title, run `find-tasks` first unless the task id is already known from the current conversation. If multiple matches exist, ask the user which one they mean.

## Setup Troubleshooting

For setup and auth problems, read `references/setup-feishu-app.md` and `references/troubleshooting.md`.

Important: default to the official link-first app setup instead of collecting credentials. App configuration and personal task/calendar authorization are separate states. Do not claim Feishu/Lark is fully connected until `doctor` reports a usable backend.