用 Macro SDK 构建工作空间集成:TypeScript 实体句柄、鉴权与 API 参考导航

原创2026-10-30 23:56:092,257 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

用 Macro SDK 构建工作空间集成:TypeScript 实体句柄、鉴权与 API 参考导航

Macro 是一个把邮件、聊天、文档、任务、Agent 与 CRM 通过 @ 提及和共享 AI 记忆串联起来的工作空间,而 @macro-inc/sdk 是访问这套工作空间的官方 JavaScript/TypeScript 客户端。本文以 SDK 参考文档主页为骨架,逐条展开它的快速开始、实体命名空间目录与句柄模型,并结合仓库源码说明鉴权头选择、分页保护、富消息构造与事件订阅的真实实现,帮助你把 macro.documents、macro.email、macro.databases 等入口真正跑通。

SDK 是什么:三层结构

从仓库结构看,packages/sdk 由两层组成,而参考文档本身位于第三个包中:

目录 角色 说明
packages/sdk/generated/ 生成层 由 Macro 的 OpenAPI 规范经 HeyAPI 生成的 TypeScript 类型与客户端
packages/sdk/src/ 手写层 提供“ORM 风”的人体工学 API,即本文讨论的实体与命名空间
packages/sdk-docs/reference/ 文档层 用 TypeDoc 从 src/ 的声明与注释生成的 Markdown 与 HTML 参考

packages/sdk/package.json 中 main/module/types 均指向 dist/src/macro.js 与 dist/src/macro.d.ts,exports 同时开放 ./generated/* 子路径,因此你既可以用高层实体 API,也可以直接使用生成的服务客户端。

参考文档在仓库中是被检入(checked in)的产物:编辑 SDK 源码注释或声明后重新生成并提交,这样每次 SDK 变更都会带来可评审的文档差异。

安装与快速开始

安装 SDK:

npm install @macro-inc/sdk

在 Macro 的 Settings → API Keys 创建 API key(形如 mak_...),并把它放进运行环境:

export MACRO_API_KEY=mak_xxxxxxxxxxxxxxxx

最小可运行示例——搜索文档、读取名称与正文,命中第一份就停止:

import { Macro } from '@macro-inc/sdk';

const macro = new Macro({});

// 查找文档并读取文本,命中第一个即停止
for await (const document of macro.documents.search('weekly update')) {
  console.log(await document.name());
  console.log(await document.content());
  break;
}

这段代码包含三个值得展开的设计点:

  1. new Macro({}) 不传任何选项时,SDK 会回落到环境变量 MACRO_API_KEY;
  2. macro.documents.search() 返回的是 AsyncGenerator,而不是数组,页面在迭代时按需拉取;
  3. document.name() 与 document.content() 是 异步访问器,调用即产生请求,break 之后不会再拉取后续页。

若需要显式凭据、Bot 身份或自定义服务地址,可查阅客户端选项 MacroOpts 与全部入口 Macro。

客户端选项:MacroOpts 全字段说明

MacroOpts 定义在 config.ts,下表结合源码注释给出每个字段的行为与默认值来源:

字段 类型 作用与回落顺序
auth MacroAuth 显式鉴权配置,优先级高于 token
token string | (() => string | Promise<string>) auth: { type: 'user', token } 的简写,接受 mak_ API key 或 Bearer JWT
env 'dev' | 'prod' | 'local' 环境,回落顺序为 opts.env → MACRO_ENV → 'prod'
hosts Partial<Record<ServiceName, string>> 覆盖单个服务域名,例如只把某个服务指向 localhost
webAppUrl string Web 应用基址,用于拼接实体链接;也读取 MACRO_WEB_URL
webhookSecret string 校验持久化 webhook 投递签名;也可用 MACRO_WEBHOOK_SECRET
requestedAs string Bot 代用户身份,作为 x-macro-bot-for-macro-user-id 发送;应通过 macro.requestedAs(user) 设置
wsVerify string 透传给底层客户端的校验参数
onRequest (event: RequestActivity) => void 请求活动观测回调,不包含参数、URL 与响应数据

ServiceName 覆盖 14 个后端服务(agent-harness、storage、auth、email、calendar、cognition、notification、properties、search、scheduled-action、static-files、connection、contacts、unfurl)。注意 search 与 properties 实际由 storage 主机提供,因此在 HOSTS 映射中二者指向与 storage 相同的地址。

local 环境的默认端口同样定义在该文件里,便于本地联调:

// packages/sdk/src/config.ts 中 local 环境的节选
'agent-harness': 'http://localhost:8101',
storage: 'http://localhost:8086',
email: 'http://localhost:8087',
calendar: 'http://localhost:8088/calendar',
notification: 'http://localhost:8089',

calendar 的 /calendar 前缀是刻意保留的,目的是让本地路径与网关路径保持一致。若 MACRO_ENV 取值非法,resolveEnv 会抛出 invalid MACRO_ENV "..." — expected local, dev, or prod。

鉴权:三种凭据与“只发一个头”规则

每次请求只携带一种 Macro 凭据,共三类:

凭据 签发位置 前缀 代表身份
API key Settings → API Keys mak_ 创建它的用户
Bot token Settings → Bots mbot_ 该 Bot,可选代表某个用户
Bearer token 已登录会话 无(JWT) 登录用户

API key 的三种写法

// 1) 最简:从 MACRO_API_KEY 读取
const macro = new Macro({});
const me = await macro.users.me();

// 2) 代码内传入:token 同时接受 API key 与 bearer token
const macro2 = new Macro({ token: process.env.MACRO_API_KEY });

// 3) 显式声明凭据类型(不做前缀校验,兼容 mak_ 前缀之前的旧 key)
const macro3 = new Macro({
  auth: { type: 'user', apiKey: process.env.MACRO_API_KEY },
});

API key 永远以创建者身份行事,requestedAs 仅对 Bot 生效。

Bot token 与作用域

const asBot = new Macro({ auth: { type: 'bot', token: process.env.MACRO_BOT_TOKEN } });
const asWolf = asBot.requestedAs('macro|wolf@macro.com');

Bot 请求带访问作用域:设置了 requestedAs 时默认 scope: 'user'(使用被代表用户的权限),否则默认 team(使用拥有该 Bot 的团队权限,仅适用于团队 Bot)。可用 auth: { type: 'bot', token, scope } 显式覆盖。

Bearer token 与刷新

const macro = new Macro({ auth: { type: 'user', token: () => session.accessToken() } });

函数形式每次请求都会求值,因此天然支持令牌刷新。

请求头到底是哪一个

后端拒绝同时携带两个凭据的请求(返回 400 ambiguous credentials),SDK 的 requestAuthHeaders(见 client.ts)保证只设置一组头:

你传入的 实际发送的头
apiKey: '…' x-macro-user-api-key: …
token: 'mak_…' 或 MACRO_API_KEY=mak_… x-macro-user-api-key: mak_…
token: '<jwt>' 或 MACRO_API_KEY=<jwt> Authorization: Bearer <jwt>
token: 'mbot_…' 抛错,需改用 auth: { type: 'bot', token } 或 MACRO_BOT_TOKEN
type: 'bot' x-macro-bot-token 加 x-macro-bot-scope

这些分支由 ts-pattern 的 match 穷尽匹配实现,错误信息也写得很具体:把 bot token 当用户凭据会提示 bot token passed as a user credential,反向混用则提示 user API key passed as a bot token。另外,若 MACRO_API_KEY 与 MACRO_BOT_TOKEN 同时存在,构造函数会直接抛错,要求你通过 auth 明确选择其一。

实体句柄:先拿句柄,再读字段

macro.documents.byId(id) 只创建一个句柄,不会发起请求。字段在首次读取时懒加载:

const document = macro.documents.byId(documentId);
const [name, content] = await Promise.all([
  document.name(),
  document.content(),
]);

这套行为由基类 MacroEntity 实现(见 entity.ts):

  • 构造函数接收 (client, id, seed?),把详情记录包进 Lazy,若调用方已带上种子记录则无需首次请求;
  • field(key) 生成一个异步访问器,并把 null 归一化为 undefined;
  • mappedField(key, map) 把 id 字段映射成另一个句柄,例如 document.owner() 返回可直接检查的 User;
  • mutate(fn) 执行写操作后会 detail.clear(),使后续读取重新拉取,避免读到过期缓存。

FavoritableEntity 在此基础上增加 favorite() / unfavorite() / permission();PropertiedEntity 再增加 properties() / setProperty() / updatePropertyOptions() / deleteProperty()。注意二者使用的实体类型标识并不相同——收藏接口用 document,属性服务用 DOCUMENT,源码中分别由 entityType 与 propertyEntityType 承载。

toJSON() 只在详情已加载时附带 detail,因此日志里打印句柄通常只出现 { id },不会意外暴露整条记录。

命名空间目录:找到你要的那块能力

SDK 把相关操作按命名空间挂在 macro 上,Macro 构造函数逐个实例化它们(见 macro.ts)。以下四张表完整对应参考文档的入口清单,链接均指向生成的 Markdown 参考页。

内容与工作

入口 代表什么
macro.documents 工作空间中的文档与文件,含正文、评论、分享与历史
macro.tasks 需要跟踪与完成的工作,含负责人、截止时间与状态
macro.projects 组织文档与其他工作空间条目的集合
macro.workspace 跨工作空间活动的视图,可按实体类型、时间、属性或收件箱状态过滤
macro.databases 表格化的结构化信息,含类型化句柄、SQL 查询、带版本保护的原子写入与视图
macro.forms 收集回答进数据库的问题表单,且不向填写者开放其他行
macro.properties 自定义字段及其选项,用于描述与过滤实体
macro.foreignEntities 指向外部系统条目、并被链入 Macro 的引用

沟通

入口 代表什么
macro.email 已连接的邮箱、会话、消息、草稿、附件与标签
macro.channels 共享会话,含消息、回复、线程与帖子
macro.chats AI 聊天会话及其消息
macro.calendar 已连接的日历与事件,含时间、参与者与邀请
macro.calls 通话录制及其关联转录
macro.notifications 当前用户的活动通知,含已读/已处理状态与投递偏好

人员与组织

入口 代表什么
macro.users Macro 中的人及其资料,包括已认证用户
macro.teams 团队及其成员关系
macro.crm 公司与联系人记录,含备注与关系
macro.favorites 当前用户收藏的实体
macro.pins 固定在用户首页指定位置的条目

AI 与集成

入口 代表什么
macro.agentSessions Agent 会话,含配置、消息、排队动作与执行状态
macro.bots Bot 身份及其配置
macro.ai 针对你提供内容的 AI 操作:结构化生成与 Jev 的是/否分类
macro.events 通过流或 webhook 接收器订阅的实时实体事件
macro.webhooks 把事件投递到你应用 URL 的持久化订阅

自动化与资源管理

Routines、可配置 Agent 及其宿主都使用类型化句柄:macro.routines、macro.agents 与 macro.harnesses。Routine 的触发器可以引用实体,执行结果返回转录句柄;Agent 会话与工具审批保留频道/会话作用域。

任务型工作项用 macro.initiatives,日程与邀请用 macro.meetings,凭据管理用 macro.apiKeys。API key 创建时密钥单独返回,句柄只序列化元数据。

搜索与分页:AsyncGenerator 的语义细节

列表与搜索方法在可翻页时返回自动翻页的迭代器,for await 消费、break 提前停止:

for await (const doc of macro.documents.recent()) {
  console.log(await doc.name());
}

for await (const hit of macro.documents.search('quarterly revenue')) {
  console.log(hit.webUrl());
}

// 需要一次性收集全部结果时
const allDocs = await Array.fromAsync(macro.documents.recent());

搜索选项 SearchOpts(见 search.ts 与 SearchOpts 参考)只有两个字段:

字段 类型 默认值 作用
searchOn 'name' | 'content' | 'name_content' 'name_content' 限定匹配字段
pageSize number 50 每次请求的页大小

底层调用 client.search.unifiedSearch,固定 match_type: 'partial',并在客户端按命中项的 type 过滤出目标实体,再映射成对应句柄。这也是为什么 macro.documents.search() 只产出 Document,即便统一搜索还返回了别的类型。

分页器在 pagination.ts,有一个值得了解的防御逻辑:若服务端返回的 nextCursor 与本次请求使用的游标序列化结果相同,迭代器会抛出 Pagination cursor did not advance,而不是无限循环。写自定义分页循环时可以借鉴这条检查。

不同命名空间的游标形态不同:documents.recent() 用 offset 做游标(数字转字符串),工作空间列表用不透明字符串游标,评论时间线用结构化的 MessageCursor 对象。

文档实体上的完整读写链路

macro.documents 的方法在 namespace.ts 与 document.ts 中实现,覆盖创建、读取、变更与删除:

const doc = await macro.documents.create({
  name: 'Weekly update',
  markdown: '# Week 32\n\n- shipped the thing',
});

await doc.rename('Weekly update (final)');
await doc.setTeamShare(true);
await doc.delete();        // 软删除,可用 doc.restore() 恢复

值得注意的源码细节:

  • content() 先取文本内容接口,返回 null 时退回导出接口拿 presigned URL 再 fetch,失败抛 MacroApiError('failed to download document content');
  • delete({ permanent: true }) 走永久删除接口,默认软删除;
  • copy({ name, versionId }) 可基于指定版本复制;
  • comments() 先分页拉取根消息,再以 8 路并发(THREAD_FETCH_CONCURRENCY)展开线程;
  • webUrl() 由 client.webAppUrl 拼接 /app/md/{id},因此自定义 webAppUrl 或 MACRO_WEB_URL 会直接改变链接;
  • byTeamSlug('ENG-42') 解析团队任务引用,并在响应结构不符时抛 Invalid team task document response。

二进制文档走上传通道:documents.createUpload({ name, sha, fileType, mimeType, ... }) 预留文档并返回 uploadUrl、contentType 与 content,先把字节传到 uploadUrl,再调用 prepareSave() / save() / simpleSave() 提交。

富文本消息与 @ 提及

msg 标签模板用于构造频道消息或文档评论的富文本,每个 mention 同时写入内容标签与 mentions[] 数组,二者不会漂移:

import { msg, here } from '@macro-inc/sdk';

const channel = macro.channels.byId('chan_1');
const user = macro.users.byId('user_1');
await channel.send(msg`Hey ${user}, take a look at ${doc}. cc ${here}`);

实现位于 mentions.ts:

  • Mentionable 只需实现 toMention(),返回 { tag, mention };
  • wrapXml(tag, data) 把 JSON 中的 <、>、& 转义为 \u003c、\u003e、\u0026,防止像 </m-document-mention> 这样的名字提前闭合标签;
  • here 是内置的 m-group-mention mention,entity_type 为 group、entity_id 为 here;
  • msg 对重复 mention 去重,普通字符串原样插入,因此 Markdown 语法不会被转义。

文档的 toMention() 会带上 documentId、documentName 与 blockName(取 fileType,默认 md)。

事件订阅:SSE 优先,webhook 可选

macro.events 始终可用,默认传输是实时 SSE 流,不需要公网 URL、持久化 webhook 或签名密钥:

const macro = new Macro({ token: process.env.MACRO_API_KEY });
const me = await macro.users.me();

macro.events.on('message.posted', async ({ metadata, target }) => {
  if (metadata.sender === me.id) return; // 不回复自己
  if (target.type === 'channel') await target.message.reply('hi!');
  else await target.comment.reply('hi!');
});

const stop = await macro.events.listen();
// 之后:stop();

listen() 打开 GET /webhook/events/stream,使用与持久化 webhook 相同的 WebhookFilters 模型;若未传 filters,它会从已通过 .on() 注册的事件名推导。scope 默认 'user',团队工作空间可传 'team'。投递是尽力而为的:断线后不会重放。

MacroEvents 会把事件水合(hydrate)成 ORM 句柄,与 webhook 投递载荷一致。事件分四族:document.*、channel.*、message.*、agent_session.*。消息事件(posted、patched、deleted、mentioned、attachment_created、attachment_removed)同时覆盖频道消息与文档评论,metadata.parent 指明父级,水合后的 target 携带 Channel + Message(回复还带 Thread)或 Document + Comment。

若需要 HTTPS POST,注册 webhook 并提供 webhookSecret(或 MACRO_WEBHOOK_SECRET),SDK 负责验签与分发:

const macro = new Macro({
  token: process.env.MACRO_API_KEY,
  webhookSecret: process.env.MACRO_WEBHOOK_SECRET,
});

// Hono
app.post('/webhook', (c) => macro.events.webhook()(c.req.raw));

一个常见错误来自 listen() 的过滤器校验:若既没有传 filters、也没有预先注册处理器,它会抛出 listen() needs filters — pass filters or register handlers with .on() first(见 receiver.ts)。

从目录进入参考:生成式 API 文档怎么读

参考文档主页的最后一段说明了阅读方式:点击任一实体链接即可看到方法、示例与关联类型。这些页面由 TypeDoc 从 SDK 声明与注释生成,包含方法使用的请求/响应类型。

常用共享页面:

维护文档时,在 packages/sdk-docs 目录执行:

bun run generate         # 生成 Markdown 与 HTML 参考
bun run check:generated  # 渲染到 dist/docs/ 并逐字节对比 reference/
bun run type-check
bun run test             # 先做文档一致性检查,再测公开契约
bun run docs:dev         # 本地预览

check:generated 只比较、不改写:出现新增、变更或删除页面即失败,从而让 CI 拦住过期的参考文档。bun run build 只产出被忽略的构建资产,发布时用 bun run docs:deploy,Worker 以静态资源方式提供 HTML,不需要请求处理函数、凭据或数据库。

实践中的排错清单

结合源码,以下问题最容易在一开始遇到:

  1. 400 ambiguous credentials:说明请求同时带了两个凭据头。检查是否既设了 MACRO_API_KEY 又在 auth 里传了别的凭据。
  2. bot token passed as a user credential / user API key passed as a bot token:前缀与凭据类型不匹配,改用对应的 auth.type。
  3. requestedAs() requires bot auth:用户令牌永远代表自己,代用户在 SDK 层就被禁止(见 client.ts)。
  4. no Macro credential:既没有环境变量也没有显式传入凭据,构造函数会延迟到首次请求才报这条错。
  5. Pagination cursor did not advance:服务端未推进游标,通常是过滤条件与游标不匹配导致,检查是否复用了别的列表的游标。
  6. 读不到刚写的数据:句柄字段可能仍是变动前拉取的缓存;写方法会清缓存,但跨进程或跨会话的改动需要重新取句柄。
  7. 权限问题:SDK 的每个请求都经过 Macro 的授权检查,句柄本身不携带权限;同一条 byId 在不同凭据下可能得到完全不同的可见性。

小结

SDK 参考文档的三层信息——快速开始、实体命名空间目录、生成的类型参考——对应着一条清晰的使用路径:先用 MACRO_API_KEY 构造 Macro 客户端,按命名空间找到实体,用 byId 或 search 拿到懒加载句柄,再用异步访问器读字段、用方法写变更、用 AsyncGenerator 分页。理解了 MacroOpts 的回落顺序、鉴权头选择规则和 MacroEntity 的缓存语义,就能在脚本、服务端应用和 Agent 工具之间复用同一套 API,而无需关心底层 14 个后端服务的差异。

登录后查看全文
macro