Macro AI Chat 与 Agent 会话机制详解:上下文、连接器、代码模式与配额
Macro AI Chat 与 Agent 会话机制详解:上下文、连接器、代码模式与配额
本文以 Macro 仓库中的 AI Chat 行为规范为骨架,系统拆解 Agent 会话从入口、提示词构造、上下文剥离、连接器授权,到代码模式执行、队列调度与 AI 配额结算的完整链路。读完后,你既能理解这些行为背后的源码位置,也能据此在本地开发环境复现文档中给出的每一项验证步骤。
一、会话从哪里来:入口与路由
Macro 的 AI 能力并不只有一种形态。仓库文档把"会话住在哪里"单列一节,原因在于不同入口创建的是不同实体,路由、共享语义和存储位置都不一样。
1.1 三种会话 URL
| 会话类型 | URL 形态 | 说明 |
|---|---|---|
| Chat 会话(Agent) | /app/agents/<id> |
新式 chat agent 会话 |
| Code 会话 | /app/coders/<id> |
编码类 Agent 会话 |
| 旧版聊天 | /app/agent-chats/<id> |
历史遗留 chat,仍可打开 |
| 独立 legacy chat | /app/chat/<uuid> |
旧聊天单页 |
| 文档内聊天 | /app/md/<doc>/chat/<chat> |
分屏形态的 doc-scoped chat |
打开会话时,URL 会依据会话类型自动更新;刷新或前进/后退都能恢复其模式与内容。新建会话会用真实 id 替换临时 URL,且不会重新挂载 composer,也不会多出一条历史记录——这是前端路由把临时会话"接管"的设计,避免用户刚打完的第一条提示词因 remount 被清空。
1.2 Ask AI 入口矩阵
文档用一整节描述 "Ask AI entry points",因为它们的落点细节不同:
- 桌面搜索(含
Tab)中的 Ask AI / 命令菜单 Ask AI:都会开启一个 agent session。搜索框里已有非空查询时,该查询会在会话就绪后作为第一条 prompt 发送;空查询则打开空 composer。桌面搜索会把当前 split 替换为 Agents 工作区,而命令菜单动作会新开一个 split。 - Ask Macro / Chat with Agent:作用于文档、任务、PDF、DOCX、代码文件、图片、canvas、表格、邮件、频道、通话与项目。它们打开的是"裸会话"(不带 Agents 工作区的对话侧栏),实体 mention 以未发送草稿的形式留在 composer 中。表格会保留当前 sheet 与选中区域;频道消息会保留被引用的那条消息。
- 这些动作不会创建 legacy cognition chat,与
enable-chat-v3-agents开关无关。
文档内聊天的路径也很明确:打开文档 → side panel Actions → Ask Macro,文档会以 link chip 形式预置为上下文,仍需补一个问题再 Send。
1.3 Home、Agents 与快捷键
Home 的 composer 跟随 enable-chat-v3-agents:关闭时保留 legacy chat,开启时挂载与 Agents 页相同的 new-conversation composer。发送后停留在 Home,新会话在 Home 的详情面板打开(/home/agent/<id>),首条 prompt 显示为已发送,会话创建后其行加入 Home 列表顶部。
从编辑器外部按键 c 再 a,或 Create → Agent,会打开 /app/component/agents 并把焦点放进新会话输入框;此时并不会创建会话,只有真正发送 prompt 才落库。若 Agents 已停在 roster 上,该快捷键把它带回 composer;若 composer 已有草稿,草稿保持不变。C Shift+A 走标准分屏导航,申请一个新 split。
1.4 会话列表的加载与占位
Agents 会话列表首屏会在短暂延迟后显示 row skeleton;拉取下一页时追加三个占位行,已有会话仍可交互。占位行是装饰性的、不可聚焦,必须等出现带名字的会话按钮再选择。prefers-reduced-motion 下 shimmer 动画关闭。
列表还承载了较多状态语义:
- Chat 行用聊天图标,Code 行用
</>(若已关联 PR,则用 PR 状态图标)。 - 正在启动或轮次仍在进行的会话,用与 transcript 相同的三点工作波纹替代首图标,行可访问名追加
Starting或Working,且无需刷新即可跟随每轮状态切换。 - 关联 PR 的会话在标题下方显示
#<number>,图标颜色随 open / merged / closed 变化;点击打开同步后的 GitHub PR 实体,若尚未同步则在新标签页打开 GitHub。 - 右键(或移动端长按)弹出与 Home 相同的实体菜单:Rename、Favorite、Copy link、Share、Archive、Delete 等;归档会话归入列表底部的 Archived。
- 设定为 Hide runs 的 routine 运行默认隐藏,需点击搜索控件旁的时钟按钮(Show hidden routine runs)才显示;每次进入 Agents 视图,列表都从"不显示隐藏运行"开始。
二、提示词的真实构造:<m-agent-context> 与来源行
这是本文最容易"看不懂文档、但一看源码就通"的部分。
2.1 私有前缀如何被剥离
文档指出:prompt 气泡只显示用户文本,私有 <m-agent-context> 前缀仍留在发给 agent 的 payload 中,但在 Markdown 渲染前被剥离;乐观回显与重载后的存储 prompt 都是如此。排队中的预览与编辑器同样隐藏它,而编辑排队中的 prompt 会在保存时保留其私有前缀。
源码对应两处:
- 构造侧:agent-context.ts 定义了
TriggerContext联合类型,注释明确写出它"精确镜像 Rust 的TriggerContext(crates/trigger_context/src/lib.rs)在协议上的形状:snake_case 字段、可选字段缺省而非 null"。 - 解析侧:prompt-origin.ts 用常量
OPEN = '<m-agent-context>'、CLOSE = '</m-agent-context>'定位块,先检查markdown.startsWith(OPEN),再取indexOf(CLOSE),随后JSON.parse取data.text。解析失败通过neverthrow的Result吞掉(unwrapOr(undefined)),不会因为一段畸形前缀而导致消息渲染崩溃。
TriggerContext 的成员直接对应文档中"prompt 从别处投递而来"的各种场景:mentioned、follow_up、conversation、task_assigned、requested、dispatched、routine。每种都带不同的补充结构,例如 TaskAssignedContext 包含任务快照与分配者,RoutineContext 包含 trigger 列表与本次 firing。
2.2 气泡下的安静一行
文档规定:prompt 下方有一行 data-testid="prompt-footer" 的浅色文本,显示发布时间;若 prompt 来自别处(mention、讨论区的 follow-up、被分配的任务、handoff、routine 运行),还会显示来源,例如 via @mention in #eng · 2:02 PM。点击来源可跳转到对应位置:频道消息、评论线程、任务、邮件、通话、routine,或交接工作的那个会话。agent 实际收到的上下文保持隐藏。
这行由 PromptFooter.tsx 实现:
origin被拆成lead、place、tail三段,place用text-ink-muted提亮,与lead/tail的text-ink-extra-muted形成层次。postedAt缺失时不渲染时间,origin存在时用·分隔来源和时间。- 有
onOpen时渲染为<button>,否则退化为不可点的<span>;点按支持Shift走"新 split"路径(openInNewSplitForMention)。 - 文档所说的"仍在发送中的 prompt 不显示该行,直到日志确认",在类型层面就是
postedAt为undefined(注释:absent until the log confirms the prompt)。
跳转目标由 open-prompt-origin.ts 的 useOpenPromptOrigin 分发,OriginDestination 覆盖 channel_message、document、project、crm_company、crm_contact、call、task、routine、email_thread、agent_session、external。文档评论还会先读 getItemPreview 判断文件类型,再决定跳到哪个 block,读不到则 toast 失败——这与文档中"点击来源打开那个位置"的描述一一对应。
2.3 mention chip 的序列化标签
Agent 会话里 @ 插入的 mention chip,在模型侧以标签形式序列化:文档/频道/聊天/任务/邮件/日历事件/技能用 <m-document-mention>,日期或时间用 <m-date-mention>,会话用 <m-agent-session-mention>,人用 <m-user-mention>,主题色用 <m-theme-mention>。
两个行为值得注意:
- 在 composer 中点击仍在编辑态的 chip,会在新 split 打开被提及条目,草稿与光标位置不变,且不会发送。
- Agent 回复中输出同类标签会被渲染成可点击 chip;带
"expanded":true的会话 chip 会渲染成跟随该会话最新轮次的 Magic Chip 卡片。
文档另外规定:如果回复在某个 Macro mention chip 中途被停止,未闭合的尾部标记在停止后与重载后都保持隐藏;已完成的 chip、Markdown 代码块里的字面标签示例、以及未完成 chip 之前的正文仍然可见。这解释了为什么"看起来被截断"的回复不会在页面上留下半截 XML。
三、从会话里连接应用:DiscoverConnectors 与授权回流
3.1 发现与判断
当现有工具无法处理请求时,会话可用 DiscoverConnectors 按应用名搜索 Pipedream,并检查应用的真实工具列表。文档特别强调:应用名本身不能证明所请求的动作被支持。这一点在提示词里也有硬性约束——crates/prompt/src/agent_session.rs 明确要求"绝不要仅因为名字匹配就声称某应用支持某动作"。
展开发现行可以看到返回结果;对合适的未连接应用,助手会给出 Connect
3.2 三种授权路径
| 场景 | 行为 |
|---|---|
| Web 上普通未连接应用 | 在 transcript 之上打开托管授权流程 |
| 覆盖式应用(自带 MCP server,见 Settings → Integrations) | 在新标签页打开该 server 的 OAuth consent,授权后会话继续,之后通过该 server 而非 Pipedream 访问 |
| 原生应用 | 在系统浏览器打开 consent,授权后自行回到 Macro,Return to Macro 是兜底链接 |
等待对话框中的 Done 会去 Pipedream 检查该流程创建的账号;被取消或过期的回调不能恢复 agent。后端校验并登记连接后,会话会在同一对话中发出一条可见的续接消息。
3.3 续接前置的 session/resume
这是实现上最关键的一步:在续接消息到达 agent 之前,harness 需要把实时会话重新递给它一份允许的 connector server 列表(一次 session/resume),下一轮才能用上新应用。原生 Macro runtime 与沙箱编码会话支持这一点;不能 resume 的 runtime 会在下次 attach 时拾取该应用。未发送的草稿会保留。关闭授权或登记失败不发送任何消息。若授权期间对话已变更或关闭,就不会有自动续接,但连接的应用对下一次请求仍可用。
验证要求写得很具体:用一个未连接应用,先看工具、点 Connect、取消一次、再完成授权,确认恰好出现一条续接消息且助手能发现该应用的工具;另需确认被禁用的连接不会显示为已连接。常规 AI chat 不暴露发现与自动续接;已选定应用的 agent 保持其配置的 MCP 范围,授权不会把范围外的应用塞进去。
四、首响应延迟:从按键到首个可见文字
文档对这一节给了一套可测量的里程碑,前端实现即 prompt-telemetry.ts。
4.1 里程碑链路
PromptStage 依次为:created(新建会话的创建返回)→ loaded → configured(模型与 effort 确认)→ accepted(control POST 返回)→ confirmed(日志回传该 prompt 行)→ first_output → first_text → text_mounted → first_text_rendered → first_text_paint。
文档明确:只有最后一个里程碑才算"可见响应成功";裸 Markdown 前缀和代码工具栏标签不算数。若滚动边界处只有代码工具栏可见,要等代码本体进入视口才算达成。隐藏标签页上报 hidden;十秒内原始文本没有可见渲染器则上报 not_rendered,并记录渲染器是否挂载过、是否持续附着。
submit_surface 使用有界分类(home、agents、mobile_composer、search、document、drive、agent_session、other),避免相邻 split 把提交来源标错;fallback 能识别 Drive 文档,歧义时上报 other。所有里程碑都不记录消息内容。
4.2 DevTools 里直接读
同一批阶段会立即出现在 performance.getEntriesByType('measure') 中,名称为 agent.prompt.*,detail 里带 session ID,agent.prompt 条目包含最终 outcome。源码中 performance.measure(\agent.prompt.${stage}`)与performance.measure('agent.prompt')正是这两类条目;outcome 的取值包括text、no_text、no_output、failed、released、hidden、not_rendered、stalled,其中 stalled 对应 5 分钟仍未出字(STALL_THRESHOLD_MS),渲染超时为 10 秒(RENDER_TIMEOUT_MS`)。
4.3 开场白机制
Macro 的 in-process agent 会用快模型(gpt-5.4-mini)先给一句开场,通常在回车后半秒内出现:
- 寒暄("hi there"、"thanks")就直接以这句作为全部回复,与被选模型(已并行启动)一起取消。
- 真实任务("what is on my calendar tomorrow?")得到一句短开场("Let me check your calendar."),空行之后接所选模型的答案,不会出现第二句确认。
- 开场只回应用户说的话,绝不使用 prompt 里的隐藏上下文。
- 已发送的 prompt 从首帧起就完全不透明,其
Contextchip 已在位,因此服务端确认时不会发生位移。
注意:带自有 API key 的 agent 会跳过这句开场,因为开场跑在 Macro 的模型上。
4.4 transcript 启动与 fold worker
验证要求同时覆盖 dev server 与 production build:首屏应加载编译后的 fold.worker-*.js 及其 WASM 资产;仅导入 client 不应构造 worker。若出现 data:video/mp2t 的 worker URL,说明原始 TypeScript 被打包成了资产——这是典型的构建配置错误。空白的 worker 启动错误本身不足以证明标签页已过期。
另有一条易被忽略的交互约定:焦点进入 agent composer 只应本地预热 transcript 渲染器,聚焦本身不得发送 prompt。记录导航与聚焦时间要和控制台输入、回车到首个答案的时间分开统计。
五、项目、条目操作与工具行渲染
5.1 项目(Initiatives)
Project 工具支持列出、读取、创建、更新、删除、共享项目,以及读取项目活动。后端工具名使用 Initiative,但操作的是 Tasks 中的原生 Projects 视图。Agent 通过 SetEntityProperty 作用于任务的 Project 属性来设置或清除归属。
项目行包括 Find projects、Read project、Create project assigned、moved、not a task、not found、skipped no permission;移除结果为 unassigned 或 not assigned,属于其他项目的任务保持不变。两个动作都需要对项目与每个任务有编辑权限;移除在遇到权限或服务失败时中止,同批中靠前的任务可能已被移除。
删除项目后结果不给出指向已删除项目的链接;删除失败显示 Not deleted。
5.2 工具行的生命周期
内存 agent 的工具行在模型点名调用的瞬间就以 pending 出现。参数预览最多每 250 ms 更新一次,并在 16 KiB 处停止;进入执行后预览被完整输入替换。若在模型写参数期间取消,该行以 failed 关闭且不执行。已完成的行都有可展开的结果开关,包括空结果与逐任务失败;Result data 揭示完整返回。成功变更会刷新项目视图。
5.3 条目操作与身份语义
助手能执行与应用菜单相同的条目动作:
- 消息与评论:编辑、删除、对频道消息加反应;编辑或删除文档评论;打开 DM。
- 条目级:移入回收站、复制、重命名、改共享、收藏、静音或稍后提醒。
- 其他:创建 CRM 公司与联系人、重命名或删除通话、创建技能、运行或删除 routine。
关键规则是身份:编辑与删除以消息/评论作者身份执行——助手改自己的消息就是自己,改用户的消息就是用户;而反应永远是用户的。文档建议用一次性条目验证,因为这些操作会改动真实数据。
5.4 UploadFile 与 GenerateImage 的边界
UploadFile 接受文件名与标准带 padding 的 base64 内容,解码后最大 25 MiB。源码中阈值有明确定义:upload.rs 的 MAX_INLINE_UPLOAD_BYTES: usize = 25 * 1024 * 1024,超限错误文本为 "file exceeds the 25 MiB inline upload limit"。可选 project ID 会把文件放进调用者可编辑的文件夹。工具不能访问 agent 的本地路径,也不能下载 URL;生成型文本与原生 Macro 表格应改用 CreateDocument。工具行显示文件名,成功后显示 Uploaded,展开可打开创建的文档并看到上传字节数。成功只代表字节已入存储,预览、DOCX 转换、Markdown 初始化与索引可能异步完成。
GenerateImage 接受文本 prompt,用 Google 的 Nano Banana 模型渲染并存入 static file service(实现见 generate_image.rs 与 gemini.rs)。可选 aspectRatio 取 square、landscape、portrait、widescreen、tall;源码注释给出比例:1:1、4:3、3:4、16:9、9:16。响应包含 staticFileId、永久 url、像素 width/height 与可直接发送的 markdown;它不创建文档,也不接受文件名或目标项目。
参考图最多三张,形如:
[
{"type": "staticFile", "id": "<UUID>"},
{"type": "document", "id": "<UUID>"}
]
上传照片用附件 URL 中 /file/<id> 的 UUID;文档用其 document ID;上一次生成的结果用其 staticFileId。必须在 prompt 里按数组顺序称"image 1 / 2 / 3"——仅靠文字描述不会把照片传给图像模型。每次结果都保存为新的静态文件。
渲染侧也有约束:结果直接作为图片出现在分组工具调用之外,从 SFS URL 加载,无文件名头、不导航到文档,保持宽高比并适配可用宽度。生成中显示状态;加载失败显示 "Preview unavailable"。频道消息中必须原样复制返回的 markdown 到独立一行:其 <m-image> 标记保留尺寸并把图片限制在 400 × 400 像素内,因此加载不会改变频道行高;换成普通 Markdown 图片 URL 会丢失尺寸。缺少 Google Generative AI key 的主机会让工具失败——build_context.rs 在 GOOGLE_GENERATIVE_AI_API_KEY 缺失时打 warn 并禁用该工具。
六、Composer:Auto / Chat / Code 与模型选择
6.1 模式开关与 Auto 判定
起始页 composer 的内嵌条上是 Auto / Chat / Code:桌面在输入框下方,手机在上方。Chat 与 Code 会限制可提供的 agent;选择只在 composer 挂载期间有效,每个 composer 都以 Auto 打开。
Auto 处于 enable-composer-auto-mode PostHog flag 之后(仅 Macro 员工),agent harness 也会检查该 flag;没有它时开关是 Chat / Code,Auto 读作 Chat。Auto(星形图标,即侧栏的 Agents 图标)会隐藏 agent、model、effort、speed 控件。发送时输入会短暂被阻断("Choosing Chat or Code…"),期间 POST /agent-mode-choice 请 Cloudflare 的 Clef Flash 判断该 prompt 是否需要编码 agent(服务端实现见 mode_choice.rs)。
判定结果的落地规则:Code 会用用户最近使用的编码 agent(否则第一个可启动的)加其默认模型,仓库选项为 Choose automatically;Chat 用与 Chat 模式相同的模型。若没有可启动的编码 agent,prompt 直接走 Chat 且不再询问;任何失败或 3 秒超时同样回落到 Chat。会话最终以 Chat 或 Code 打开,如同从该模式启动。
切换模式会保留草稿与附件,并清除上一模式的 model / effort 覆盖;不会过滤对话侧栏。
6.2 模型目录
所有模型控件——生产 chat、agent composer、运行中的会话、Settings 中的默认模型字段——都是同一个 ModelCatalogPicker:桌面是可搜索 popover,触屏是可搜索的 Choose a model 底部弹层,均以 Suggested 打头,完整供应商目录收在 More models 之后。选中即应用并关闭菜单;锁定模型仍列出,但置灰加锁,点击进入升级流程。
新建会话时模型目录的分组顺序为:Suggested(按可用性列出 Opus 5.5、Sonnet 5.5、GPT-5.6、GPT-6 Astra、Gemini)→ More models(按供应商分组的完整目录,含 Suggested 项与 effort/speed 变体)→ 你的 agents(Built-in、Your agents、Needs connection)。搜索匹配名称、ID 与供应商名;打开时自动聚焦 Search models 并即时可输入。
选中的模型会成为"下一次发送"的覆盖,不会更新已保存的 agent;持久默认值要在 agent 编辑器里配置。发送或切换到其他 agent 会清除该覆盖。最常使用的受支持且可用的 agent 会被初始选中,否则选 Macro。
6.3 Effort 与 Speed
模型选择器旁的"速度表"式 effort 按钮打开 effort 级别列表,当前值带勾选;桌面为按钮下方居中的 popover,移动端为独立底部弹层。模型少于两个 effort 选项时隐藏。Free 与 Pro 用户的新会话从最低档开始,除非显式改选;已有会话保持当前设置。
⚡ 按钮为 GPT-6 Astra 与 GPT-6.1 Sol 启用 Ultrafast(6 倍 token 计费),tooltip 在发送前显示模式、状态与倍率。Claude 系列(含 Opus 5.5)在 Anthropic 批准该账号的 fast mode 之前保持标准速度;其他模型维持标准。偏好保存在 localStorage,由 legacy chat 与原生 Macro agent composer 共享;外部编码 agent 使用自己的速度控制。用量记录按每次调用供应商实际交付的速度计费,OpenAI 超过 272,000 token 的 prompt 该次调用按长上下文费率计算,标准与加速费率各有独立计价键。
新建会话会在发送首条消息前确认所选模型与 effort;若启动即报告设置被拒或超时,首条 prompt 尚未发送。相关 harness 契约与测试覆盖见 agent-effort.md。
七、排队、打断与"停止"的真实语义
7.1 服务端队列
发送从不被正在运行的轮次阻塞:轮次进行中发出的 prompt 在服务端排队,当前轮次结束后自动派发,每轮一条。队列上限 50 条,超出时发送被拒绝并报错而不是入队。等待中的 prompt 在被接受、编辑或移除时写穿到 session store,harness 重启后会恢复——不能因为管理副本 drain 就消失。
7.2 三个不同按钮
| 控件 | 语义 |
|---|---|
| Send next | 显式中断当前轮次,发送最旧的排队消息 |
| Flush queued messages | 空 composer 时的同一动作(带环的发送箭头),按顺序排空队列 |
| Steer(单行) | 中断当前轮次并把该行移到队首,让它下一个跑 |
Stop 只取消当前轮次;队列继续排空,下一条排队 prompt 会开启新轮次。要彻底静默一个会话,需先清空队列再停止。
只读会话两者都不提供。Send next 与 Steer 在上一条正在启动时仍可用。连续多次 Steer 的请求按按下顺序逐条发出,每条的发出都在前一条离开服务端队列之后,因此三次快速点击会按序发出三条、各一次;被拒绝的 steer 会把该行以 Not sent 放回,仍留在队列中可再次 steer。输入框里的文字优先,回车照常排队新 prompt。
队列行的展示细节:位于 transcript 与输入框之间,最新的在上、将要发送的在最下;列表高度取视口 40% 与 24rem 的较小值,超出后自行滚动并从底部开始,以便"下一条待发"可见。每行先是单行预览,点击(或 Enter/Space)展开编辑器,展开高度取视口 32% 与 16rem 的较小值;再次点击或 Esc 收起并保留编辑内容与编辑器状态。编辑是防抖自动保存加 blur 保存,没有保存按钮,且仅在派发前可改。
7.3 键盘路径
输入框最开头按 ↑ 会把焦点移入最下方(下一条待发)的队列行,继续 ↑ 走向更新的条目,↓ 返回并在越过底部行后回到输入框。
7.4 权限提示
所有对会话有 Edit 权限的人都可以批准或拒绝其 ACP 权限请求,即使不是创建者。待处理请求在 composer 上方显示一张 Approval needed 卡片,命令或受影响文件与动作分开呈现,transcript 不重复该请求。Allow once、Always allow、Deny 立即生效,Always allow 的 tooltip 显示规则文本,More options 收纳其他记住的选择。只有具备 Edit 或 Owner 会话权限的已认证用户可作答,bot、harness 与内部服务凭据不能代答;Viewer 与 Commenter 只能看到等待提示。
Runtime 侧还有两层开关:Settings → Agents → Runtimes → New runtime 的 Allow bypassing permission requests(默认关闭)与 macrod Quickstart / Config 的 Full Access(默认关闭),选择在下次配对时生效。Settings → Agents → Runtime 的 Always prompt / Always bypass 只对本地 macrod harness 出现;内置 Macro、in-memory、Cursor、Codex runtime 始终 bypass,没有该选择器。后端强制执行这些策略。
八、移动端与响应式行为
8.1 手机上的 Agents
开启 enable-chat-v3-agents 后,手机上的 Agents 打开新会话列表,包含 GitHub PR 状态与链接。点行进入全屏会话,头部返回键回上一屏,直链则回 Agents。纵屏与横屏触控布局都没有会话侧栏。Changes 打开全宽统一 diff 加 Back to conversation,返回时保留未发送草稿。
移动端会话列表省略桌面的 Agents 与 Connections 控件,需用 Agents composer 或全局新建菜单开始对话。返回列表再打开 composer 会保留草稿、附件、agent、模型、仓库与分支。
8.2 浮动 composer
浮动移动 composer 只出现在 Agents;Home 与其他视图保留各自的 New 动作或自己的回复/评论 composer。它是一个不透明圆角输入,与 New 按钮同表面(深色模式含玻璃处理);Send 是无背景的纯上箭头(禁用时亦然);占位符是 "Message Macro AI"。折叠时高度与 New 一致,Send 可见而模型/供应商控件隐藏,直到输入被聚焦。
点输入框后横向展开占满整行,隐藏 New,给草稿一个位于控件之上的全宽文本区。手机上 Auto/Chat/Code 以图标形式留在输入上方的内嵌条中,Code 模式下仓库控件出现在其旁。点击外部收起并恢复 New;编辑器和模型选择器保持挂载,因此收起不丢草稿。关闭模型或 effort 选择器后焦点回到消息输入框。
宽度断点方面:桌面控件高 32px,触控模拟下 36px,模型选择器与闪电按钮需共享高度与垂直居中;仓库与分支选择器在搜索框聚焦期间保持 composer 展开,锚点不位移。分屏宽度低于 720px 时的关闭按钮、Back to conversations 等行为也在文档中逐条列出。
九、分享、权限与读取其他会话
9.1 分享面板
独立 chat(/app/chat/<uuid>)在桌面头部有 Share 与 Copy Share Link;实体列表菜单与实体共享快捷键上也有同一 Share。它打开与文档相同的 Share 对话框(移动端为抽屉):
- People / channels:选收件人与访问级别,可附一条消息发送。
- Link sharing:None / Public / Team link 加访问级别。
- Team access(仅 owner,且 owner 属于某个 team):None / View / Comment / Edit 下拉,直接把 chat 分享给 owner 的整个团队;设回 None 即撤销。该控制独立于 team link。只有实际 owner 能改,继承 owner 权限的人会收到 "Failed to change team access" toast。
会话侧的规则更细:View 与 Comment 允许阅读,Edit 还允许控制会话;只读会话的 composer、模型选择器与排队控件均禁用。其他参与者可以为已有权限的人复制链接,但不能授予权限或修改共享设置;仅复制链接从不改变权限。未保存的新会话草稿不提供分享。
分享一条会话引用到消息中默认授予 View 并保留既有授权,用访问选择器才能给 Comment 或 Edit。
9.2 Session 头部与侧栏
会话头部包含侧栏重开控件、关联 PR 状态 chip、收藏、Share 与 Side panel。侧栏开关(或 ])打开 Details、Plan、Changes、Activity、References:宽布局在 transcript 旁、窄布局覆盖其上,且不会另开 split。Details 列出 Status、Agent、Model 与日期;Runtime 行只对编码 runtime 出现,in-memory chat agent 没有该行。References 与文档同款:每行对应一条 @ 提及或分享该会话的频道消息、一条提及它的评论(文档、项目、CRM 记录、通话)、或一篇提及它的文档;点击在 split 中打开,评论行会打开其父级并定位到该评论。
9.3 读取他人的 agent 会话
ReadAgentSession 由会话 mention 或搜索结果提供 ID,要求调用者具备正常会话访问权,返回最近 20 条折叠消息(prompt、回复、工具活动、失败),单条消息上限 4000 字符,响应与消息的截断标记用于标示省略;终端失败单独返回,以免长回复掩盖它。
ListEntities(includeTypes: ["agent_session"]) | NameSearch | ContentSearch → 找到会话
ListAgents → 找到可用 agent
CreateAgentSession → 用选定 agent 开新会话
ManageAgentSession → 重命名/归档/删除/prompt/stop
权限边界很清晰:重命名、归档、删除需要所有权;prompt 与 stop 需要编辑权限。prompt 接受只报告"已发送或已排队",不报告完成;结果不确定时必须先读会话再重试。ReadAgentSessionSharing 查看链接、团队与频道授权,UpdateAgentSessionSharing 由 owner 修改,ShareWithChannel 可分享到频道。这些工具不能代替用户批准权限请求。
十、代码模式:DescribeCodeTools、ReadCodeDocs 与 ExecuteCode
10.1 工具面
当 harness 配置了本地 Deno runtime,会话的 macro_internal server 会暴露 DescribeCodeTools、ReadCodeDocs 与 ExecuteCode。in-process agent 在首次模型调用就能看到这三个 schema,无需 SearchTools 或 LoadTools。
对 Macro 的 in-process agent,后端每轮评估会话所有者的 ai-code-mode flag。启用者得到更小的直接工具集:SDK 支持的搜索、读取、列举与数据操作走 SDK;文档编辑保留直接的 EditDocument,DisplayResults 仍用于渲染结果;工作区 feed 与混合实体名搜索保留 ListEntities 与 NameSearch;ContentSearch 支持会话历史。legacy chat 与 workspace SDK 命名空间被排除在 agent 文档之外。经 SDK 路由的方法不再出现在直接 schema、SearchTools 与 LoadTools 中,但仍可通过 DescribeCodeTools 发现。用户审阅类工具、AskUser、连接器发现、已连接应用的按需加载、subagent 与显式 provider 代码执行保留各自直接生命周期;第三方 MCP 工具照常可用。
flag 缺失/关闭、评估失败、PostHog 未配置、或缺少 code-mode MCP 工具时,保留标准工具集。摘要/压缩调用不加载 flag、不广告工具。flag 变更在下一轮生效,不改变进行中轮次的工具。该 flag 控制呈现而非授权:SDK 请求仍受正常用户权限约束,签发运行凭据需要执行批准。
10.2 程序契约
要求 agent 写一个导出 async function main({macro, session, execution}) 的 JavaScript 模块。这些是真实的公开 SDK 句柄,例如 macro.documents.search(...) 是异步迭代器,await document.content() 取回文档内容。返回 {data} 形式的纯 JSON;可选的 reviews 数组保存审阅引用,省略时默认 []。支持循环、提前 break 与有界并行 Promise。
必须保留用户的源过滤条件、源 ID、错误与覆盖上限;停止分页迭代器不能证明已穷尽。
10.3 发现与文档
DescribeCodeTools 接受实体名(如 documents、email、ai、agentSessions)与指南主题(examples、search、ai、templates)。名称返回对应实体索引;它也接受 task:同一套 Jev 选择在该文本上运行,在 32 KiB 预算内返回所有相关实体索引,并列出因体积被省略的实体。
ReadCodeDocs 接受最多 10 个 symbol,在 32 KiB 预算内返回各自 TypeDoc 参考(签名、参数、选项字段、返回类型);参考中其他符号以反引号标注。Agent 应在写程序前把要用的 symbol 一起读掉。没有运行时的 sdk.help 或 sdk.ToolName 代理;实际 SDK 暴露 macro.ai.structuredCompletion 与 macro.ai.decide,Handlebars 从 handlebars 导入;AI 文档编辑仍用直接的 EditDocument。
每轮 code-mode 都会收到紧凑实体目录。Jev 可在生成前加载相关实体索引,截止一秒,超时回落到仅目录。
10.4 运行时与安全边界
harness 为每次执行启动全新 Deno 进程;依赖在构建期打包,运行中不做 TypeScript 编译或包下载。进程在必要的账户批准后拿到短时普通用户 token;SDK 方法用常规 API 授权向配置的 Macro 服务主机发 HTTP 请求。该 token 同时签署会话的 agent 身份:SDK 消息显示该 agent 为发送者,from pill 显示所选代理用户;普通用户 token 没有 agent 归属,客户端头与消息体无法自行选择。
没有 runner service、WebSocket 桥或逐 API 调用审批回调。每 harness 进程可跑 8 个执行、排队 16 个;公共 MCP 运行有自己的预算。网络主机、进程生命周期、输出与内存都有界;文件系统写入、任意导入与子进程被拒绝。token 在签发后到期,进程退出不会提前吊销。
10.5 审阅栈与幂等
代码创建保存型审阅时会立即发出一条独立的已完成 PresentReview ACP 调用,其卡片可在程序结束前出现并在此后继续可编辑。呈现的语义是"已呈现给用户",不等于已批准或已发送。随后 agent 会问 "Should I kick it off?",账户所有者答 yes 时才用 DecideReview 提交,卡片读作 "Started by the agent at your request"。
执行日志保留源码、状态与最终 JSON/错误;已完成的 API 写入不会因失败或取消而回滚。若复用的 execution ID 指向不同源码,卡片会报告工具结果不可用,且不展示另一份程序的结果。未完成的保存记录在读与重试时明确标注为未经确认的结果。
本地开发 build 可在 Console 过滤 [Code mode],每次执行在完整调用输入到达后打印源码与 session/execution ID;生产 build 不打印。绝不要记录或返回执行的 token。
10.6 公共 MCP 上的代码模式
公共 workspace MCP(mcp-server[-dev].macro.com)在 initialize、tools/list 与 tools/call 上为 OAuth 用户评估同一 ai-code-mode flag,按用户缓存一分钟。启用者看到 ExecuteCode、DescribeCodeTools、ReadCodeDocs 取代被 SDK 覆盖的原生工具,server instructions 要求先 DescribeCodeTools(带 task)再 ReadCodeDocs,然后写程序。程序导出 async function main({macro}) 并严格返回 {data}(空的 reviews: [] 会被丢弃)。这里没有 session、执行日志、审阅栈与 execution_id,receipt 只带状态、观察到的 SDK 活动、结果与错误。运行以用户身份执行,无 agent 归属与 owner 批准卡,MCP 客户端在每次工具调用前询问;SDK 写入(含发邮件)立即生效。每个副本 4 个运行 / 8 个排队。
本地验证可用:
tooling/scripts/claude-local-mcp.sh --instance <name> --email <email>
它为一个既有用户铸造本地 token 并只传递 Macro MCP。本地 Doppler 没有 PostHog key,需在服务启动前往该实例的 local.generated.env 加 POSTHOG_API_KEY 与 POSTHOG_HOST,指向 macro-<name>_services 网络上的替身 /flags/ 服务,然后对比启用与未启用用户的 tools/list。
十一、AI 用量配额与计费
11.1 两个独立策略
准入使用后端的 ENABLE_AI_USAGE_ENFORCEMENT 策略,由宿主配置后生效,默认关闭且与环境无关;结算(额度消耗与自动充值)由另一个同样默认关闭、与环境无关的 ENABLE_AI_USAGE_BILLING 策略把关。
准入开启后,cognition chat 与 structured completion 在额度耗尽时返回 402,在校验不可用时返回 503 且带 ai_billing_unavailable;两者都不会启动 AI 工作。chat 准入还先于 chat/message 创建。既有的模型与 chat 权限失败优先于配额错误。503 应当稍后重试,而不是当作批准,也不要反复重发 prompt。
自动会话命名独立准入:命名被拒或校验不可用时,成功的 chat 继续使用既有/默认标题。
11.2 定价模型
crates/ai_billing/src/lib.rs 的模块文档把定价写成公式:
free cap = AI_USAGE_FREE_INCLUDED_ALLOWANCE_CENTS (每用户每月、按供应商成本计)
premium = AI_USAGE_INCLUDED_ALLOWANCE_CENTS (每席位每周期、按供应商成本计)
max = AI_USAGE_MAX_INCLUDED_ALLOWANCE_CENTS (每席位每周期、按供应商成本计)
extra = cost x (100 + AI_USAGE_OVERAGE_MARKUP_PERCENT) / 100
文档强调:所有数字都不在代码里,全部是 Doppler 必填值,宿主启动时由 config.rs 加载进一个 AiPricing。用量与额度是 cost cents,额度包、扣款、上限与套餐是 customer cents,两者只在 AiPricing 的换算处相遇。超额付费先由预付额度覆盖(一次性 Stripe Checkout),再按 opt-in 的超额设置分块计费,价格均为成本加小幅 markup。免费计划是硬上限。
计费责任方(payer)是拥有额度、超额设置与 Stripe customer 的账户:个人订阅者,或团队成员通过团队订阅获得付费访问时的团队 owner。每个团队席位只用自己的计划额度,额度不在成员间转移;owner 的预付额度与超额上限由团队共享。
11.3 402 / 503 的界面与队列行为
已付费额度用尽且没有额度包或用量计费覆盖时,发送消息返回 HTTP 402,应用打开 AI usage limit 对话框(标题为 You've used this month's included AI,或消费上限/扣款失败变体),显示 Monthly limit、Add additional credits to keep going. 与 Open usage settings。额度包在 Settings → Usage 购买,订阅变更在 Settings → Billing。
免费计划用尽时返回 402 且 code 为 ai_free_allowance_exhausted,标题为 You've used this month's free AI,文案 Subscribe to a paid plan to keep going.,并提供 View plans(打开 Billing);该升级路径在用量摘要加载中或失败时仍可用。免费用户不能买额度包,也不能开启 Auto-Reload——开启 Auto-Reload 正是付费用户打开用量计费的方式。上限按 UTC 日历月重置。
会话创建与消费控制同样对准入失败返回 402/503。等待中的 prompt 在执行前会再检查一次:耗尽时把被拒工作从队列移除,并把已宣告的回复解析为失败,同时发布 agent_session.command_rejected,带 action ID 与安全的失败细节。计费不可用则保留等待中的工作,等下一次驱动队列的事件,而不是持续重试。已运行的轮次不被追溯取消;Stop/cancel 与非消费类控件仍可用。直接 ACP 请求收到的是带稳定 code 与 retryable 的协议错误,而非 HTTP 状态。
直接 AI 工具/MCP 或 AI 编辑的拒绝属于失败的工具结果,即使外层传输成功;拒绝后不应发生任何 worker/provider 编辑。普通手工编辑、确定性工具/导入,以及豁免的 Memory、AiProjection、CallSummary、Dictation、ChatRename 不受配额阻断。托管会话按持久化的 owner 计配额,而非协作的发送者;外部出资的 runtime 跳过会话配额,但 Macro 出资的工具与辅助调用仍独立检查。
11.4 Agent API keys
在 Anthropic 或 OpenAI 模型上以 In Macro 运行的 agent 可以拥有自己的 API key,在 agent 编辑器模型下方设置(共享的 ApiKeyInput,已保存的 key 只显示为 sk-ant-••••)。有编辑权的人可设置或 Remove;保存的 key 不会再显示,移除也不会在供应商侧吊销。key 在 agent 之后保存(PUT /auth/agents/{id}/api-key)。
其行为规则相当精确:
- 有可用 key 的 agent 的每一轮都跑在该 key 上:不计入也不扣减个人的 Macro 用量,而是记在 key 上(
ai_usage.agent_api_key_id)。这些轮次跳过跑在 Macro 模型上的快开场白;调用模型的工具与上下文摘要仍用 Macro 的 key 并计数。 - 只有该 agent 自己的会话消耗其 key:个人 agent 是 owner 的会话,团队 agent 是当前成员的会话;他人的会话按他人 Macro 用量计。
- 会话的模型列表是该 key 供应商的模型,与个人计划无关,也无法选另一供应商的模型。
- key 属于 Premium 与 Max 计划(及企业团队),按 agent 的 owner 校验;Free 上该字段禁用并附说明;降级前保存的 key 会保留(且可移除),但 agent 改按 Macro 用量运行。
- 当 agent 不再适配该 key(换到其他供应商模型或其他 harness),key 停止计数,编辑器会说明保存的 key 未被使用,并在 Where it runs 下提供 Remove key。
11.5 配额验证矩阵
文档要求用隔离的本地后端与本地计费 fixture,而不是真实托管账号,完整矩阵见 ai-quota-enforcement.md。核心五步:
- 所有宿主上 flag 缺失/false 时,发一条 legacy chat 与一条托管会话 prompt,确认常规行为与新的未计数用量行。
- enforcement 为 true 且付费 fixture 已耗尽时,选 Macro 出资的模型,从 Home、legacy chat、doc-scoped chat 发送,确认 402 与稳定拒绝码、没有新的孤儿 session/chat/message/stream、没有 provider 工作、重试与取消控件可用。再在计费不可用时重复,预期 503
ai_billing_unavailable而非成功或自动重发。 - 在允许时启动托管轮次并排队一条 follow-up,然后在派发前耗尽 owner,检查队列移除、失败回复(若存在)与匹配的
agent_session.command_rejectedaction ID;不要期待被拒工作有完成的 runtime 轮次。故障期间确认等待工作保留且无重试循环,Stop 仍有效。 - 对可编辑文档与独立 AI 工具使用耗尽 fixture,确认失败结果与文档内容未变、用量上限对话框打开(Free 显示订阅 CTA,付费显示 Usage settings CTA)、手工编辑与 dictation 仍可用;可选重命名被拒的成功 chat 保留原/默认标题。
- 一致地设回 false 并重启/重部署所有本地进程,显式重试被拒工作并确认恢复、新的未计数行与未变的已计数历史。不要删除历史来模拟回滚,也不要声称回滚等于配额重置。
纯前端检查可走 Settings → Usage → Developer tools 直接打开 Free 或付费上限对话框再重置预览——这是显示覆盖,不是配额变更。要在不产生托管 AI 花费的前提下测试真实拒绝处理,可在 Chrome DevTools 中只拦截被测 AI 请求并返回匹配的 402 body,之后恢复响应;后端准入与结算仍需上述隔离 fixture。
十二、失败、重连与 transcript 导航
12.1 失败行与重连
失败的 agent 轮次在 Home 与 Agents 中显示小红点,重载列表后仍在;打开行可读到既有 transcript 错误。开始新一轮会清除失败点,未读状态独立。
harness server 崩溃且租约过期后,会话无需新消息就会停止显示 Working 并转为断开;transcript 保留,恢复不会重放 prompt 或重试工具调用。打开中的 chat 会在刷新持久历史的同时保留读取期间到达的实时事件,因此已恢复的会话保持活跃;瞬时历史读取失败会自动重试而实时消息继续,关闭 chat 会取消待处理的重试。
用 ACP load 重连时,最后已提交的对话在历史重建期间保持可见;成功 load 一次性替换transcript(含 prompt、thought、工具结果),不会追加另一份副本。重放行可在既有 message/tool ID 上改变内容类型,实时 transcript 必须显示新内容而不报错、不重载。失败的 load 保留上一份对话,迟到的重放通知在初始化/重连标记之间保持隐藏。
12.2 滚动与搜索跳转
会话复用频道的 TanStack ThreadList。打开会话落在最新消息,包括历史晚于空视图到达的情形。只挂载可见行与 overscan 缓冲——要搜索较早轮次的 DOM 文本,必须先滚到那里。
搜索链接带上 agent_message_turn=<zero-based turn>&agent_message_author=user|agent,会等待历史加载后滚动并高亮匹配的折叠消息,而不是停在最新;再点其他命中(包括已在打开的会话内)会重复跳转;手动导航或 Scroll to bottom 清除高亮,后续输出不会重复搜索跳转。
跟随规则:在距末尾 50px 内时,新消息与流式增长会跟随;向上滚动即脱离跟随。远在末尾之上时向下滚会出现 Scroll to bottom,点击回到最新并恢复跟随;触控设备上由 composer 上方的圆形 Jump to latest 替代,只要离开末尾就显示。右缘自定义滚动条也可拖拽定位。
十三、可直接照做的验证清单
文档本身是一份测试规范,其验证步骤可以整理成下面这份可执行清单:
- 并发观看者:在两个已登录浏览器上下文打开同一共享会话,确认各自显示对方的头像(最多三个 + 计数),关闭一个后另一个的头像消失。
- 上下文剥离:用带上下文的 prompt 在确认前与重载后各检查一次,气泡只显示用户文本;排队预览与编辑器同样隐藏,编辑后保存仍保留私有前缀。
- 来源跳转:对来自 mention、讨论 follow-up、被分配任务、handoff、routine 的 prompt,核对
prompt-footer文案并点击来源,确认落到正确位置(Shift 点击开新 split)。 - 连接器:用未连接应用检查工具列表 → Connect → 取消一次 → 完成授权,确认恰好一条续接消息且 agent 能发现其工具;再确认禁用连接不显示为已连接。
- 首响应延迟:分别用默认模型与显式 model/effort 发prompt,观测首个可见输出与首段答案文字;核对
performance.getEntriesByType('measure')中agent.prompt.*的里程碑与 outcome。 - 会话启动:对 production build 检查首屏加载
fold.worker-*.js与 WASM,确认不出现data:video/mp2t的 worker URL。 - 工具行:用长文档创建请求,写作中途取消一次,确认该行以 failed 关闭且未执行;再完成一次调用并重连,确认最终输入与结果重放。
- 上传与出图:
UploadFile校验成功字节数、超限与权限失败的表现;GenerateImage延迟图片下载,对比加载前后行高(桌面与窄宽),并重开会话复验。 - 排队与打断:在轮次进行中排队多条,分别验证 Send next、逐行 Steer、空 composer 的 Flush,以及 Stop 仅停当前轮次;确认只读会话不提供这些控件。
- 代码模式:为测试 owner 启用后端
ai-code-mode并配置 Deno runner,对比启用与未启用 owner 的工具面;要求一次文档查找(不提工具名),检查源码与结果、重载后持久化;创建一个不发信的邮件草稿栈,确认卡片在故意延迟的程序返回前到达、chat 仍可用、编辑跨导航与重载保留;停止一次执行并确认保存状态不声称未完成的工作已成功。 - 配额:按第五节矩阵在隔离后端逐步执行,flag 关闭时也要检查取消行为;前端只做 Developer tools 的显示覆盖验证。
需要集中查看 composer 的 / 菜单行为时,可对照下面两张截图确认 Connections 与 Skills 分组在桌面与手机上的呈现差异(原件位于 slash-connections-desktop.png 与 slash-connections-phone.png)。
结语
这份 AI Chat 规范的价值在于:它把"看起来像 UI 细节"的行为都锚定到了可验证的机制上——<m-agent-context> 在渲染前被剥离而 payload 保留、续接消息之前必须先有一次 session/resume、队列上限 50 条且 Stop 只停当前轮、UploadFile 的 25 MiB 来自 MAX_INLINE_UPLOAD_BYTES、GenerateImage 的五个比例来自枚举而非默认值、配额数字全部来自 Doppler 而非代码。按上面的清单逐项跑通,就能在不修改仓库的前提下,把这套会话系统从入口到结算完整验证一遍。
延伸阅读:Agent effort 能力契约、AI 配额强制与覆盖矩阵、Forms 与 AI 工具的交互、Herdr 原生会话与审批。

