跳转至

ListEntities

浏览用户的 Macro 工作区，查看其有权访问的近期项目。返回 Macro 文档、代理会话、项目、电子邮件、聊天频道、通话记录和外部实体。使用此工具可概览用户最近在处理什么，或按类型查找项目。对于活动摘要类问题（例如“今天发生了什么”、“最近怎么样”、“帮我更新进度”或“今天的站会发生了什么”），请从此处开始；当用户给出明确范围时，应用精确的时间、类型、频道或邮箱过滤器。对于 Macro 任务请求（例如“列出我的任务”、“分配给我的任务”或“我昨天完成的任务”），除非用户明确要求使用 Linear，否则应优先使用此工具而非 Linear 等外部任务跟踪器。Macro 任务是文档项，其 df 子类型为 {"l":{"dst":"task"}}，includeTypes 为 ["document"]。通过 propf 使用 entity_type TASK 过滤任务状态和分配人：Status 属性 00000001-0000-0000-0000-000000000002，Completed 选项 00000001-0000-0000-0002-000000000004，Assignees 属性 00000001-0000-0000-0000-000000000001。当前用户的分配人实体 ID 是其 Macro 用户 ID，通常为 macro|\。对于“昨天完成”，请结合状态 Completed、分配给本人以及一个 df updatedAt 的昨天时间窗口，使用 ua gte/lt ISO 时间戳。返回的文档、项目、电子邮件和通话记录包含用户可见的标签，以 {label, scope} 对的形式呈现。要按标签过滤（例如“我标记为 bug-report 的项目”），请在 tags 参数中传入标签名称——ListTags 可显示存在哪些标签。要按名称或内容查找特定项目，请改用搜索工具。

参数

参数 类型 必需 描述
includeTypes ("calendar_event" | "document" | "agent_session" | "project" | "email" | "channel" | "channel_thread" | "call" | "foreign_entity")[] 否 将返回的项目过滤为特定的项目类型。如果未提供，则返回所有类型。示例：["document", "email"] 只返回文档和电子邮件。Macro 任务作为文档项返回，因此对于任务请求，请使用 includeTypes=["document"] 并带有 df 子类型 task。此项会被折叠到 AST 中，并作为游标级过滤的一部分应用。
favoritesOnly boolean 否 仅返回用户已收藏（加星标）的项目。用于“我的收藏”或“我给哪些项目加过星标”之类的请求。照常与 includeTypes 和其他过滤器组合使用。使用 SetFavorite 收藏或取消收藏项目。
sortBy "recently_viewed" | "recently_updated" | "recently_created" 否 ListEntities AI 工具的排序顺序。
df any 否 完整的 soup AST 文档过滤器（df）。使用与 /items/soup/ast 相同的结构，例如 {"l":{"id":"..."}}。对于 Macro 任务，使用 {"l":{"dst":"task"}}；对于技能，使用 {"l":{"dst":"skill"}}。对于“昨天完成”，将任务子类型与 updatedAt 边界进行 AND 组合，例如 {"&":[{"l":{"dst":"task"}},{"&":[{"l":{"ua":{"gte":"\"}}},{"l":{"ua":{"lt":"\"}}}]}]}，使用 ISO 时间戳。
pf any 否 完整的 soup AST 项目过滤器（pf）。
asf any 否 代理会话过滤器（asf）：对于会话使用 {"l":{"id":"\"}}，对于所有者使用 {"l":{"o":"macro|email@example.com"}}。
emailPreset "signal" 否 高级电子邮件过滤器预设。对于信号邮件使用 "signal"。信号邮件和重要邮件是同义词：如果用户要求重要邮件，请使用 emailPreset="signal"。这会展开为电子邮件 AST {"&":[{"l":{"Importance":true}},{"l":{"Shared":"exclude"}}]}，并且如果省略 includeTypes，则默认返回电子邮件。
ef any 否 高级完整 soup AST 电子邮件过滤器（ef）。对于常见请求，优先使用 emailPreset="signal"。信号邮件和重要邮件是同义词；它们使用 {"&":[{"l":{"Importance":true}},{"l":{"Shared":"exclude"}}]}。支持按线程时间戳过滤：{"l":{"ca":{"gte":"\"}}} 匹配 created_at，{"l":{"ua":{"gte":"\","lt":"\"}}} 匹配 updated_at，使用带 gt/lt/gte/lte 比较器的 ISO 时间戳。对于“过去 7 天的邮件”，将 ua（或 ca）的 gte 边界设为当前时间之前的 7 天，例如 {"l":{"ua":{"gte":"\<7-days-ago-ISO>"}}}。
chanf any 否 完整的 soup AST 频道过滤器（chanf）。
cthf any 否 完整的 soup AST 频道线程过滤器（cthf）。
callf any 否 完整的 soup AST 通话过滤器（callf）。
fef any 否 完整的 soup AST 外部实体过滤器（fef）。
propf any 否 完整的 soup AST 属性过滤器（propf）。用于 Macro 任务的状态、分配人、优先级和其他实体属性。对于任务状态 Completed：{"l":{"pd":"00000001-0000-0000-0000-000000000002","et":"TASK","v":{"so":"00000001-0000-0000-0002-000000000004"}}}。对于分配给当前用户的任务：{"l":{"pd":"00000001-0000-0000-0000-000000000001","et":"TASK","v":{"er":"macro|user@example.com"}}}。使用 & 组合两者：{"&":[statusCompleted, assignedToMe]}。对于未限定范围的任务请求，优先使用此工具而非 Linear 工具。
emailView string 否 为电子邮件结果填充预览的邮箱视图。有效值：inbox（默认）、sent、drafts、starred、all、important、other 或 user:\
inbox string 否 将电子邮件结果限制为单个已连接的收件箱，以该收件箱的电子邮件地址给出。省略此参数可覆盖用户可访问的所有收件箱（其自己的收件箱以及委托给他们的任何收件箱）。仅当用户将请求限定到特定邮箱（例如“我的工作收件箱”、“共享收件箱”）时才设置此参数；请先调用 ListInboxes 获取确切地址。仅影响电子邮件结果。
tags TagFilter[] 否 将结果过滤为带有给定标签的项目——默认匹配其中任意一个，使用 tagsMatch="all" 时则匹配全部。每个条目通过其标签名称指定一个标签，与用户自己的标签进行不区分大小写的匹配；仅当用户区分个人标签和团队标签时才设置 scope（"personal" 或 "team"）。未知标签会失败并返回可用标签列表——如果不确定存在哪些标签，请先调用 ListTags。只有可标记项目（文档、任务、项目、电子邮件、通话记录）才能匹配标签过滤器。对于标签过滤，优先使用此参数，而不是手动构建 propf 过滤器。
tagsMatch "any" | "all" 否 过滤项目时，多个标签筛选条件的组合方式。
limit integer 否 返回的最大项目数。默认值为 50；最大值为 500。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 macro3/macro