用 Macro SDK 构建工作空间集成:TypeScript 实体句柄、鉴权与 API 参考导航
用 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;
}
这段代码包含三个值得展开的设计点:
new Macro({})不传任何选项时,SDK 会回落到环境变量MACRO_API_KEY;macro.documents.search()返回的是 AsyncGenerator,而不是数组,页面在迭代时按需拉取;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-mentionmention,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 声明与注释生成,包含方法使用的请求/响应类型。
常用共享页面:
- 实体句柄基类 —
field、mappedField、mutate及toJSON行为; - 搜索选项 — 与
searchOn/pageSize对应; - rich messages and mentions —
msg、wrapXml、toBody。
维护文档时,在 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,不需要请求处理函数、凭据或数据库。
实践中的排错清单
结合源码,以下问题最容易在一开始遇到:
400 ambiguous credentials:说明请求同时带了两个凭据头。检查是否既设了MACRO_API_KEY又在auth里传了别的凭据。bot token passed as a user credential/user API key passed as a bot token:前缀与凭据类型不匹配,改用对应的auth.type。requestedAs() requires bot auth:用户令牌永远代表自己,代用户在 SDK 层就被禁止(见 client.ts)。no Macro credential:既没有环境变量也没有显式传入凭据,构造函数会延迟到首次请求才报这条错。Pagination cursor did not advance:服务端未推进游标,通常是过滤条件与游标不匹配导致,检查是否复用了别的列表的游标。- 读不到刚写的数据:句柄字段可能仍是变动前拉取的缓存;写方法会清缓存,但跨进程或跨会话的改动需要重新取句柄。
- 权限问题:SDK 的每个请求都经过 Macro 的授权检查,句柄本身不携带权限;同一条
byId在不同凭据下可能得到完全不同的可见性。
小结
SDK 参考文档的三层信息——快速开始、实体命名空间目录、生成的类型参考——对应着一条清晰的使用路径:先用 MACRO_API_KEY 构造 Macro 客户端,按命名空间找到实体,用 byId 或 search 拿到懒加载句柄,再用异步访问器读字段、用方法写变更、用 AsyncGenerator 分页。理解了 MacroOpts 的回落顺序、鉴权头选择规则和 MacroEntity 的缓存语义,就能在脚本、服务端应用和 Agent 工具之间复用同一套 API,而无需关心底层 14 个后端服务的差异。