ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
|
||
# mail +triage
|
||
|
||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
|
||
查看收件箱邮件摘要（date / from / subject / message_id），用于快速浏览和决定读哪封邮件。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
# 默认：收件箱邮件（默认 20 条，默认table 格式）
|
||
lark-cli mail +triage
|
||
|
||
# 查看收件箱未读
|
||
lark-cli mail +triage --filter '{"folder":"inbox","is_unread":true}'
|
||
|
||
# 全文搜索
|
||
lark-cli mail +triage --query "合同审批"
|
||
|
||
# 按发件人 / 主题搜索
|
||
lark-cli mail +triage --filter '{"from":["boss@example.com"],"subject":"季度报告"}'
|
||
|
||
# 按时间范围搜索（如"上周的邮件"）
|
||
lark-cli mail +triage --query "项目评审" --filter '{"time_range":{"start_time":"2026-03-16T00:00:00+08:00","end_time":"2026-03-22T23:59:59+08:00"}}'
|
||
|
||
# 指定文件夹
|
||
lark-cli mail +triage --filter '{"folder":"sent"}'
|
||
|
||
# 系统标签（可通过 folder 或 label 传入，搜索时自动转为 folder）
|
||
lark-cli mail +triage --filter '{"folder":"flagged"}'
|
||
lark-cli mail +triage --filter '{"label":"important"}'
|
||
lark-cli mail +triage --filter '{"label":"重要邮件"}'
|
||
|
||
# json/data 格式可配合 jq 处理
|
||
lark-cli mail +triage --format json | jq '.messages[].subject'
|
||
|
||
# 分页：先取 10 条，再用 page_token 翻页
|
||
lark-cli mail +triage --max 10 --format json
|
||
# 输出中包含 page_token，传入下一次请求
|
||
lark-cli mail +triage --page-token 'list:FfccvoqPd...' --max 10 --format json
|
||
|
||
# --page-size 是 --max 的别名
|
||
lark-cli mail +triage --page-size 10
|
||
```
|
||
|
||
## 参数
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `--filter <json>` | — | 筛选条件（见下方字段说明） |
|
||
| `--query <text>` | — | 全文搜索关键词 |
|
||
| `--format <mode>` | `table` | `table` / `json` / `data`（`json` 和 `data` 均输出含分页信息的对象） |
|
||
| `--max <n>` | `20` | 最大返回条数（1-400），内部自动分页拉取 |
|
||
| `--page-size <n>` | — | `--max` 的别名，两者含义相同；同时指定时 `--page-size` 优先 |
|
||
| `--page-token <token>` | — | 上一次响应返回的分页令牌，传入后从该位置继续拉取。令牌带 `search:` 或 `list:` 前缀，标识来源路径，不可混用 |
|
||
| `--labels` | — | table 格式时额外显示 labels 列 |
|
||
| `--mailbox <id>` | `me` | 邮箱地址 |
|
||
|
||
### `--filter` 支持的字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `folder` | string | 文件夹名称筛选。系统文件夹固定值：`inbox`/`sent`/`draft`/`trash`/`spam`/`archive`/`priority`/`flagged`/`other`/`scheduled`，也支持自定义文件夹名称。子文件夹需用 `parent_name/child_name` 格式，可通过 folder list 接口查看 |
|
||
| `folder_id` | string | 文件夹 ID，优先级高于 `folder`。系统值：`INBOX`/`SENT`/`DRAFT`/`TRASH`/`SPAM`/`ARCHIVED`，自定义文件夹为数字 ID |
|
||
| `label` | string | 自定义标签名称筛选。子标签需用 `parent_name/child_name` 格式，可通过 label list 接口查看 |
|
||
| `label_id` | string | 标签 ID，优先级高于 `label`。自定义标签为数字 ID |
|
||
| `is_unread` | boolean | 是否未读 |
|
||
| `from` | string[] | 发件人 |
|
||
| `to` | string[] | 收件人 |
|
||
| `subject` | string | 主题关键词 |
|
||
| `has_attachment` | boolean | 是否有附件 |
|
||
| `time_range` | object | 时间范围 `{"start_time":"2026-01-01T00:00:00+08:00","end_time":"..."}` |
|
||
|
||
> **系统标签说明**：`IMPORTANT`/`FLAGGED`/`OTHER` 可通过 `folder` 或 `label` 传入（也支持中文别名 `重要邮件`/`已加旗标`/`其他邮件`、搜索名 `priority`/`flagged`/`other`）。搜索时自动转为 folder 字段，列表时自动转为 label_id。label list 接口不返回这三个系统标签。
|
||
>
|
||
> **⚠️ 注意**：查询未读请用 `"is_unread":true`。
|
||
可运行 `mail +triage --print-filter-schema` 查看完整字段说明。
|
||
|
||
## 输出
|
||
|
||
### `--format json` / `--format data`
|
||
|
||
两者输出格式相同，均为含分页信息的对象：
|
||
|
||
```json
|
||
{
|
||
"messages": [
|
||
{
|
||
"message_id": "SEU2...",
|
||
"mailbox_id": "me",
|
||
"date": "Fri, 21 Mar 2026 11:40:00 +0800",
|
||
"from": "Alice <alice@example.com>",
|
||
"subject": "Weekly update",
|
||
"labels": "INBOX,UNREAD"
|
||
}
|
||
],
|
||
"mailbox_id": "me",
|
||
"count": 20,
|
||
"has_more": true,
|
||
"page_token": "list:FfccvoqPd_loLhtcRx8cx..."
|
||
}
|
||
```
|
||
|
||
- `mailbox_id`：当前邮箱标识，用于传递给 `mail +message --mailbox` 以保持公共邮箱上下文
|
||
- `has_more`：是否还有下一页
|
||
- `page_token`：传入 `--page-token` 可获取下一页；为空字符串表示已到末尾
|
||
- token 前缀 `search:` / `list:` 标识来源 API 路径，不可混用
|
||
|
||
### `table` 格式
|
||
|
||
`page_token` 信息输出在 stderr，自动携带 `--query`/`--filter`/`--mailbox` 参数方便续页：
|
||
```text
|
||
15 message(s)
|
||
next page: mail +triage --query '合同审批' --page-token 'search:abc123...'
|
||
tip: read full content: single message use mail +message --message-id <id>; multiple messages use mail +messages --message-ids <id1>,<id2>,<id3>
|
||
```
|
||
|
||
公共邮箱场景下，`--mailbox` 会自动出现在续页和 tip 中：
|
||
```text
|
||
next page: mail +triage --mailbox 'shared@example.com' --query '合同审批' --page-token 'search:abc123...'
|
||
tip: read full content: single message use mail +message --mailbox 'shared@example.com' --message-id <id>; multiple messages use mail +messages --mailbox 'shared@example.com' --message-ids <id1>,<id2>,<id3>
|
||
```
|
||
|
||
### 搜索分页注意事项
|
||
|
||
搜索路径（使用 `--query` 或 `from`/`to`/`subject` 等 filter）的分页结果在**同一翻页链内**保持一致（无重复、无丢失）。但不同 `--max` 值发起的独立搜索可能返回不同排序，这是搜索 API 的固有行为。列表路径（仅 `folder`/`label` 筛选）无此限制。
|
||
|
||
## 参考
|
||
|
||
- [lark-mail](../SKILL.md) — 邮箱域总览
|
||
- [lark-mail-watch](lark-mail-watch.md) — 实时监听新邮件
|