use-spark

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using spark

使用spark

spark

is a CLI for the Spark email client. Use it to query the user's mailbox, calendar, contacts, meetings, and team data.

spark

是Spark邮件客户端的一款CLI工具。可用于查询用户的邮箱、日历、联系人、会议及团队数据。

Running spark

运行spark

bash

spark <command> [options]

Environment:

spark

is a thin client that talks to the user's running Spark macOS Desktop app. Do not try to execute it inside a sandbox, container, CI runner, or any environment isolated from the user's desktop session - it will fail to connect.

bash

spark <command> [options]

环境说明：

spark

是一款轻量客户端，需与用户正在运行的Spark macOS桌面应用通信。请勿在沙箱、容器、CI运行器或任何与用户桌面会话隔离的环境中尝试执行它——否则将无法连接。

Commands

命令列表

Command	Description
`accounts`	List accounts, calendars, teams, shared inboxes
`folders`	List folders/labels with message counts
`emails`	List emails with filters and pagination
`search`	Hybrid keyword + semantic search with full bodies
`thread`	Read full thread - headers, bodies, attachments
`events`	List calendar events for a time range
`availability`	Find free time slots, optionally with attendees
`contacts`	Search contacts by name or email
`team`	Show team info, members, shared inboxes, assignments
`meetings`	List meeting transcripts
`meeting`	Read a single meeting transcript

命令	描述
`accounts`	列出账户、日历、团队和共享收件箱
`folders`	列出文件夹/标签及对应邮件数量
`emails`	通过筛选器和分页功能列出邮件
`search`	混合关键词+语义搜索，返回完整邮件内容
`thread`	读取完整对话线程——包含邮件头、正文和附件信息
`events`	列出指定时间范围内的日历事件
`availability`	查找空闲时段，可指定参会人员
`contacts`	通过姓名或邮箱搜索联系人
`team`	查看团队信息、成员、共享收件箱及任务分配情况
`meetings`	列出会议纪要
`meeting`	读取单条会议纪要

accounts

List all configured accounts with their calendars, teams, and shared inboxes.

bash

spark accounts

Run this first to discover what accounts, calendars, and teams are available.

列出所有已配置的账户及其关联的日历、团队和共享收件箱。

bash

spark accounts

建议先运行此命令，了解可用的账户、日历和团队信息。

folders

List folders with message counts. Output includes folder identifiers in parentheses - use these as arguments to

emails

and

search

. Mailboxes backed by a Google account show

(Gmail labels)

on the Email Account or Shared Inbox header. Teams show the team name as a usable identifier for

emails

bash

spark folders                        # all accounts
spark folders user@example.com       # single account

列出文件夹及对应邮件数量。输出内容中括号内的是文件夹标识符——可将其作为

emails

和

search

命令的参数。由Google账户支持的邮箱会在邮件账户或共享收件箱标题后显示

(Gmail labels)

。团队名称可作为

emails

命令的有效标识符。

bash

spark folders                        # 所有账户
spark folders user@example.com       # 单个账户

emails

List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail-style filters.

bash

spark emails                                                   # Unified Inbox
spark emails user@example.com:Archive                          # specific folder
spark emails "My Team"                                         # all shared threads in a team
spark emails --filter "from:alice@co.com is:unread"             # filtered
spark emails --filter "newer_than:7d has:attachment"            # recent with attachments
spark emails --page 2 --page-size 20                           # pagination
spark emails --order ascending                                 # oldest first
spark emails --new-senders                                     # show only new sender emails

GateKeeper filtering: When viewing the Inbox with GateKeeper in explicit mode, new sender emails are automatically filtered out and a "New Senders" count is shown at the top. Use

--new-senders

to view those emails.

Folder identifier formats (run

folders

to see available ones):

Format	Example	Meaning
Bare name	`Inbox` , `Archive`	Unified folder (cross-account)
`email`	`user@example.com`	Account inbox shorthand
`email:Folder`	`user@example.com:Archive`	Specific account folder
`"Team Name"`	`"My Team"`	All shared threads in a team (quote if spaces)
`shared@email:Folder`	`shared@co.com:Inbox`	Shared inbox folder

Filter operators (combinable, Gmail-style):

Operator	Example
`from:<addr>`	`from:alice@co.com`
`to:<addr>`	`to:bob@co.com`
`cc:<addr>`	`cc:team@co.com`
`subject:<text>`	`subject:"quarterly report"`
`before:yyyy/MM/dd`	`before:2026/03/01`
`after:yyyy/MM/dd`	`after:2026/01/01`
`newer_than:Xd`	`newer_than:7d` (also `w` , `m` , `y` )
`older_than:Xd`	`older_than:30d`
`has:attachment`	also `document` , `spreadsheet` , `presentation` , `reminder`
`is:unread`	also `read` , `starred` , `pinned` , `unreplied`
`is:shared`	emails shared to any team (alias for `is:shared_email` )
`is:shared_inbox_open`	open items in shared inbox
`is:shared_inbox_done`	completed/closed items in shared inbox
`category:personal`	also `priority` , `notification` , `newsletter` , `invitation` , `invitation_response`
`assigned_to:me`	emails assigned to current user
`assigned_to:<email>`	emails assigned to specific teammate
`assigned_to:unassigned`	shared inbox items with no assignee
`assigned_to:other`	emails assigned to someone else (not me)
`assigned_by:me`	emails delegated by current user
`filename:<name>`	`filename:report.pdf`

列出包含元数据（ID、发件人、日期、主题、标记）的邮件。支持分页和Gmail风格的筛选器。

bash

spark emails                                                   # 统一收件箱
spark emails user@example.com:Archive                          # 指定文件夹
spark emails "My Team"                                         # 团队所有共享对话
spark emails --filter "from:alice@co.com is:unread"             # 筛选邮件
spark emails --filter "newer_than:7d has:attachment"            # 近期带附件的邮件
spark emails --page 2 --page-size 20                           # 分页
spark emails --order ascending                                 # 按时间升序（ oldest first）
spark emails --new-senders                                     # 仅显示新发件人的邮件

GateKeeper筛选： 当在显式模式下使用GateKeeper查看收件箱时，新发件人的邮件会被自动过滤，顶部会显示“新发件人”数量。使用

--new-senders

参数可查看这些邮件。

文件夹标识符格式（运行

folders

命令查看可用标识符）：

格式	示例	含义
纯名称	`Inbox` , `Archive`	跨账户统一文件夹
`邮箱地址`	`user@example.com`	账户收件箱简写
`邮箱地址:文件夹名`	`user@example.com:Archive`	指定账户的文件夹
`"团队名称"`	`"My Team"`	团队所有共享对话（名称含空格时需加引号）
`共享邮箱:文件夹名`	`shared@co.com:Inbox`	共享收件箱文件夹

筛选运算符（可组合使用，Gmail风格）：

运算符	示例
`from:<addr>`	`from:alice@co.com`
`to:<addr>`	`to:bob@co.com`
`cc:<addr>`	`cc:team@co.com`
`subject:<text>`	`subject:"quarterly report"`
`before:yyyy/MM/dd`	`before:2026/03/01`
`after:yyyy/MM/dd`	`after:2026/01/01`
`newer_than:Xd`	`newer_than:7d` （也支持 `w` 周、 `m` 月、 `y` 年）
`older_than:Xd`	`older_than:30d`
`has:attachment`	还支持 `document` 文档、 `spreadsheet` 表格、 `presentation` 演示文稿、 `reminder` 提醒
`is:unread`	还支持 `read` 已读、 `starred` 星标、 `pinned` 置顶、 `unreplied` 未回复
`is:shared`	共享至任意团队的邮件（ `is:shared_email` 的别名）
`is:shared_inbox_open`	共享收件箱中的未处理项
`is:shared_inbox_done`	共享收件箱中的已完成/已关闭项
`category:personal`	还支持 `priority` 优先级、 `notification` 通知、 `newsletter` 通讯、 `invitation` 邀请、 `invitation_response` 邀请回复
`assigned_to:me`	分配给当前用户的邮件
`assigned_to:<email>`	分配给特定团队成员的邮件
`assigned_to:unassigned`	共享收件箱中未分配的项
`assigned_to:other`	分配给其他用户（非当前用户）的邮件
`assigned_by:me`	当前用户委派的邮件
`filename:<name>`	`filename:report.pdf`

search

Hybrid keyword + semantic search returning up to 20 emails with full bodies, sorted by relevance.

bash

spark search "quarterly report"
spark search "API integration" --filter "from:alice@co.com"
spark search "budget" --in user@example.com:Archive
spark search "vacation" --in user@example.com              # all folders in account

Parameter	Required	Description
`<about>`	Yes	Search topic (positional)
`--filter`	No	Gmail-style filter (same operators as `emails` )
`--in`	No	Scope: account, team, folder, or shared inbox. All folders if omitted.

Use
search
when the user asks about a topic. It returns email bodies so you can answer questions about content. Use

emails

when listing/browsing by folder or filters without needing bodies.

混合关键词+语义搜索，最多返回20封按相关性排序的完整邮件。

bash

spark search "quarterly report"
spark search "API integration" --filter "from:alice@co.com"
spark search "budget" --in user@example.com:Archive
spark search "vacation" --in user@example.com              # 账户下所有文件夹

参数	是否必填	描述
`<about>`	是	搜索主题（位置参数）
`--filter`	否	Gmail风格筛选器（与 `emails` 命令的运算符相同）
`--in`	否	搜索范围：账户、团队、文件夹或共享收件箱。省略则搜索所有文件夹。

当用户询问特定主题时使用
search
命令，它会返回邮件正文，便于你回答内容相关问题。当仅需按文件夹或筛选器列出/浏览邮件而不需要正文时，使用

emails

命令。

thread

Print every message in a thread - headers, full plain-text bodies, and attachment info. After the thread summary line, lists custom (non-system) folder labels once for the whole thread, using qualified names like

account@domain.com:MyLabel

(same style as

folders

bash

spark thread 1114                          # by message ID from emails/search output
spark thread --download-attachments 1114   # also fetch attachments via IMAP

Use

emails

search

to find message IDs (the ID column), then

thread

to read the full conversation.

打印对话线程中的每一条消息——包含邮件头、完整纯文本正文和附件信息。在对话摘要行之后，会列出整个线程的自定义（非系统）文件夹标签，格式为

account@domain.com:MyLabel

（与

folders

命令的格式一致）。

bash

spark thread 1114                          # 通过emails/search输出中的消息ID查询
spark thread --download-attachments 1114   # 同时通过IMAP获取附件

先使用

emails

或

search

命令查找消息ID（ID列），再使用

thread

命令读取完整对话。

events

List calendar events for a time range.

bash

spark events                                          # today's remaining events
spark events --tomorrow
spark events --week
spark events --week --in user@example.com             # specific account
spark events --week --in user@example.com:Work        # specific calendar
spark events --start 2026-03-16 --end 2026-03-20      # custom range

Date formats:

yyyy-MM-dd

dd/MM/yyyy

, or

yyyy-MM-ddTHH:mm

Run

accounts

to see available calendar accounts and calendar names.

列出指定时间范围内的日历事件。

bash

spark events                                          # 今日剩余事件
spark events --tomorrow
spark events --week
spark events --week --in user@example.com             # 指定账户
spark events --week --in user@example.com:Work        # 指定日历
spark events --start 2026-03-16 --end 2026-03-20      # 自定义时间范围

日期格式：

yyyy-MM-dd

、

dd/MM/yyyy

或

yyyy-MM-ddTHH:mm

。

运行

accounts

命令查看可用的日历账户和日历名称。

availability

Find free time slots. Without

--attendees

, shows the user's own availability. With

--attendees

, computes mutual free windows.

bash

spark availability                                                        # today
spark availability --tomorrow
spark availability --week --attendees alice@co.com
spark availability --start 2026-03-16 --end 2026-03-20 --attendees a@co.com,b@co.com

Free slots are within working hours (08:00-20:00), skip weekends, and ignore events marked "free".

查找空闲时段。不带

--attendees

参数时，显示当前用户的空闲时间；带

--attendees

参数时，计算所有参会人员的共同空闲窗口。

bash

spark availability                                                        # 今日
spark availability --tomorrow
spark availability --week --attendees alice@co.com
spark availability --start 2026-03-16 --end 2026-03-20 --attendees a@co.com,b@co.com

空闲时段限定在工作时间（08:00-20:00），跳过周末，且忽略标记为“空闲”的事件。

contacts

Search contacts by name or email. Strict match first, then fuzzy fallback.

bash

spark contacts "john"
spark contacts "example.com"

通过姓名或邮箱搜索联系人。优先精确匹配，再进行模糊匹配。

bash

spark contacts "john"
spark contacts "example.com"

team

Show team info - metadata, shared inboxes with members, full member list, assigned emails, assignment summary.

bash

spark team                     # list available teams
spark team "Readdle"           # specific team

查看团队信息——元数据、含成员的共享收件箱、完整成员列表、已分配邮件及任务分配摘要。

bash

spark team                     # 列出可用团队
spark team "Readdle"           # 指定团队

meetings

List meeting transcripts with optional filters and pagination.

bash

spark meetings
spark meetings --filter "newer_than:30d"
spark meetings --filter "subject:standup" --page-size 10

Filter operators:

subject:<text>

before:yyyy/MM/dd

after:yyyy/MM/dd

newer_than:Xd

older_than:Xd

列出会议纪要，支持筛选器和分页。

bash

spark meetings
spark meetings --filter "newer_than:30d"
spark meetings --filter "subject:standup" --page-size 10

筛选运算符：

subject:<text>

、

before:yyyy/MM/dd

、

after:yyyy/MM/dd

、

newer_than:Xd

、

older_than:Xd

。

meeting

Read a single meeting transcript's summary. Optionally include the full transcript and/or notes.

bash

spark meeting 42                            # summary only
spark meeting --transcript 42               # include transcript
spark meeting --notes 42                    # include notes
spark meeting --transcript --notes 42       # everything

Use

meetings

to find meeting IDs.

读取单条会议纪要的摘要。可选择包含完整纪要和/或会议笔记。

bash

spark meeting 42                            # 仅摘要
spark meeting --transcript 42               # 包含会议纪要
spark meeting --notes 42                    # 包含会议笔记
spark meeting --transcript --notes 42       # 全部内容

使用

meetings

命令查找会议ID。

Smart Categories

智能分类

Spark automatically classifies incoming email into six categories. Use the

category:

filter operator with

emails

and

search

to view mail by category.

Category	Filter	Typical Content
Priority	`category:priority`	Auto-prioritized or manually marked as priority
People	`category:personal`	Direct person-to-person email
Notifications	`category:notification`	Service notifications, alerts, receipts
Newsletters	`category:newsletter`	Subscriptions, digests, marketing
Invites	`category:invitation`	Calendar invitations
Invite Responses	`category:invitation_response`	RSVPs, accepts, declines

Browse by category:

bash

spark emails Inbox --filter "category:priority is:unread"       # unread priority mail
spark emails Inbox --filter "category:personal is:unread"       # unread people mail
spark emails Inbox --filter "category:invitation"               # pending invites
spark emails Inbox --filter "category:notification is:unread"   # unread notifications
spark emails Inbox --filter "category:newsletter newer_than:7d" # recent newsletters

Category-first review pattern: Process inbox in priority order - priority first, then people, then invites, then notifications, then newsletters. This ensures the most important messages get attention first.

Spark会自动将收到的邮件分为6个类别。在

emails

和

search

命令中使用

category:

筛选运算符，可按类别查看邮件。

类别	筛选器	典型内容
优先级	`category:priority`	自动标记或手动设置为优先级的邮件
个人邮件	`category:personal`	直接的个人往来邮件
通知邮件	`category:notification`	服务通知、提醒、收据
通讯邮件	`category:newsletter`	订阅内容、合集、营销邮件
邀请邮件	`category:invitation`	日历邀请
邀请回复	`category:invitation_response`	回复邀请、接受/拒绝通知

按类别浏览：

bash

spark emails Inbox --filter "category:priority is:unread"       # 未读优先级邮件
spark emails Inbox --filter "category:personal is:unread"       # 未读个人邮件
spark emails Inbox --filter "category:invitation"               # 待处理邀请
spark emails Inbox --filter "category:notification is:unread"   # 未读通知邮件
spark emails Inbox --filter "category:newsletter newer_than:7d" # 近期通讯邮件

优先按类别处理模式： 按优先级顺序处理收件箱——先处理优先级邮件，再处理个人邮件，接着是邀请邮件、通知邮件，最后是通讯邮件。这样能确保最重要的消息优先得到关注。

Typical Workflows

典型工作流

Answer a question about emails:

```
spark search "topic"
```
- find relevant emails with bodies
Read the output and answer the user's question

Find and read a specific email:

spark emails --filter "from:sender subject:keyword"

- locate the email

```
spark thread <ID>
```
- read the full conversation

Check someone's schedule for a meeting:

spark availability --tomorrow --attendees alice@co.com,bob@co.com

Suggest a time from the free slots

Get team workload overview:

```
spark team "Team Name"
```
- see members and assigned emails

Look up a contact:

```
spark contacts "name or domain"
```
- find their email address

Review assigned shared inbox items:

spark emails shared@co.com:Inbox --filter "assigned_to:unassigned"

- unassigned items

spark emails --filter "assigned_to:bob@co.com"

- items assigned to a teammate

spark emails --filter "is:shared_inbox_open"

- all open shared inbox items

spark emails --filter "is:shared_inbox_done"

- completed items

Read meeting notes:

spark meetings --filter "newer_than:30d"

- find recent meetings

```
spark meeting <ID> --transcript --notes
```
- read summary, transcript, and notes

回答邮件相关问题：

```
spark search "topic"
```
- 查找包含正文的相关邮件
读取输出内容并回答用户的问题

查找并读取特定邮件：

spark emails --filter "from:sender subject:keyword"

- 定位目标邮件

```
spark thread <ID>
```
- 读取完整对话

查看参会人员的会议日程：

spark availability --tomorrow --attendees alice@co.com,bob@co.com

从空闲时段中建议合适的会议时间

获取团队工作量概览：

```
spark team "Team Name"
```
- 查看成员及已分配邮件情况

查询联系人：

```
spark contacts "name or domain"
```
- 查找联系人邮箱地址

查看共享收件箱的任务分配：

spark emails shared@co.com:Inbox --filter "assigned_to:unassigned"

- 未分配的项

spark emails --filter "assigned_to:bob@co.com"

- 分配给指定团队成员的项

spark emails --filter "is:shared_inbox_open"

- 共享收件箱中所有未处理项

spark emails --filter "is:shared_inbox_done"

- 已完成的项

查看会议笔记：

spark meetings --filter "newer_than:30d"

- 查找近期会议

```
spark meeting <ID> --transcript --notes
```
- 读取摘要、会议纪要和笔记

Keeping this skill up to date

保持技能更新

The CLI and this skill share a single version (

metadata.version

in the front-matter above). New features in newer Spark Desktop releases ship with an updated embedded skill. Backward compatibility is guaranteed within a major version, so the commands and flags documented here keep working - but newly added features won't appear in this file until it is reinstalled.

Check for an update when - and only when - you hit one of these signals:

The user asks about a Spark feature, command, or flag that isn't documented here.
A
```
spark
```
command fails with an "unknown command" or "unknown option" error you didn't expect.
The user explicitly says they upgraded Spark or that the skill is out of date.

In those cases:

bash

spark --version

If the printed version is greater than

metadata.version

above, reinstall and re-read this file before answering:

bash

spark skill --install <parent-of-use-spark>

<parent-of-use-spark>

is the directory containing the

use-spark/

folder this

SKILL.md

lives in.

Do not check on every session or before every command - this skill is the source of truth unless one of the signals above tells you otherwise.

CLI工具与本技能共享同一版本（见前文的

metadata.version

）。Spark桌面应用新版本中的新功能会随更新后的内嵌技能一同发布。主版本内保证向后兼容，因此本文档中记录的命令和参数会持续可用——但新增功能需重新安装后才会显示在此文档中。

仅当出现以下情况时，检查是否需要更新：

用户询问的Spark功能、命令或参数未在本文档中记录。
```
spark
```
命令执行失败，出现“未知命令”或“未知选项”的意外错误。
用户明确表示已升级Spark或本技能已过时。

出现上述情况时：

bash

spark --version

如果打印的版本高于前文的

metadata.version

，请重新安装并阅读本文档后再回答问题：

bash

spark skill --install <parent-of-use-spark>

<parent-of-use-spark>

是包含本

SKILL.md

所在的

use-spark/

文件夹的上级目录。

请勿在每次会话或每个命令前检查更新——除非出现上述信号，否则本技能即为最新参考。

Tips

提示

Always quote multi-word arguments:
```
spark search "project update"
```

Combine filter operators in a single

--filter

string:

--filter "from:alice@co.com is:unread newer_than:7d"

Use
```
folders
```
to discover exact folder identifiers before passing them to
```
emails
```
or
```
search --in
```
Use
```
accounts
```
to discover calendar names before passing them to
```
events --in
```
The
```
search
```
command is best for topic-based queries;
```
emails
```
is best for browsing/filtering by metadata
```
thread
```
returns the full conversation - use it when you need the complete email text, not just metadata
This release is read-only. If the user asks you to send, archive, snooze, assign, or comment - explain that those actions aren't available yet and they'll need to use Spark Desktop directly.

多词参数需加引号：
```
spark search "project update"
```

在单个

--filter

字符串中组合多个筛选运算符：

--filter "from:alice@co.com is:unread newer_than:7d"

在将文件夹标识符传入
```
emails
```
或
```
search --in
```
命令前，先使用
```
folders
```
命令确认准确的标识符
在将日历名称传入
```
events --in
```
命令前，先使用
```
accounts
```
命令确认可用的日历名称
```
search
```
命令最适合基于主题的查询；
```
emails
```
命令最适合按元数据浏览/筛选
```
thread
```
命令返回完整对话——当你需要完整邮件文本而非仅元数据时使用
当前版本为只读模式。如果用户要求发送、归档、暂缓、分配邮件或添加评论，请说明这些操作目前不可用，需直接使用Spark桌面应用完成。