Macro 的片段（snippets）怎么用：分号唤起、团队共享，以及官方文档没写的那部分
每天要重复敲的那几段文字，其实每个人心里都有数：周会纪要的固定格式、给客户的标准回复、代码评审前要过一遍的检查清单、提 PR 时那套描述模板。以前的处理方式无非两种，一种是翻到上次写过的地方复制粘贴，另一种是把它们攒在某个备忘录里，用的时候切窗口。两种都要离开当前正在写的东西。
Macro 把这件事做成了 snippets（片段）。官方文档给它的一句话定义很直白：可复用的 markdown 片段，在任何 markdown 区域打一个分号就能选中插入。听起来是个小功能，但它牵扯到几个值得先弄清的点——片段和普通文档是什么关系、分号在什么位置才会触发、个人建的片段怎么变成全团队共用的模板、以及哪些你以为会有的能力，官方文档其实一个字都没写。
这篇按官方文档把这些逐条捋清楚。凡是文档没写的，下面都会明说是没写，不做推测。
片段本质上就是一份完整的 markdown 文档
这是理解 snippets 的关键一句。官方文档写得很明确：一个片段是一份完整的 markdown 文档，所以文档编辑器支持的东西它全都支持——标题、列表、清单（checklist）、表格、代码块，其余同理。
这句话的分量在于，它把片段从”一段纯文本”抬到了”一份结构化模板”。文档编辑器那边的能力清单本身就不算窄：段落、一到三级标题、无序/有序/清单列表（带可勾选的复选框）、引用块、代码块（Prism 语法高亮，覆盖 15 种以上语言）、表格、分割线、图片、视频、链接，以及用 KaTeX 渲染的行内和块级公式。这些在片段里同样成立。
所以像”新人入职清单”这种东西，插进来就是一串真的可勾选的复选框，而不是几行画出来的方框字符；像”故障复盘模板”这种，插进来直接带表格和代码块的骨架。片段做的事更接近”往当前位置注入一段带结构的内容”，而不是简单的文本展开。
另一条同样重要：片段可以随时修改，之后每次插入都会用更新后的内容。这意味着模板改版只要改一处，后续所有插入自动跟上。但要注意文档的措辞是”每次未来的插入”（every future insertion）——至于已经插进各处文档里的旧内容会不会跟着变，官方文档没有说明。从这句话的字面意思看，比较稳妥的预期是：插入即是一次内容拷贝，已落地的那份不会回溯更新。真要确认，得自己在工作区里试。
新建：c + s，名字就是唯一的检索键
创建路径官方给了两条，都从创建启动器（create launcher）走：
- 按
c打开创建启动器，再按s； - 或者在启动器里点 Snippet 卡片。
这套按键和 Macro 其它对象的创建方式是一致的，c 后面跟一个字母决定建什么：c + d 建文档、c + t 建任务、c + e 建邮件、c + m 建消息、c + g 建频道、c + a 建 AI 对话、c + n 建画布、c + f 建文件夹、c + o 建代码文件、c + s 建片段。这类按键流的完整清单可以参考 Macro 的键盘快捷键体系。
真正需要提前想清楚的是命名。官方文档在这里专门叮嘱了一句：给片段起一个清晰的名字，因为这就是你之后在分号菜单里搜索它时要打的东西。分号菜单的筛选方式是”继续往下打字按名称过滤”——注意是按名称，文档没有提到会检索片段的正文内容。
这条约束的实际后果是：命名策略要按”你插入时脑子里会冒出的词”来定，而不是按分类学来定。如果一堆片段都叫”模板-周报""模板-复盘""模板-回复”，打分号后再打”模板”两个字，菜单里还是一长串。反过来，用”周报""复盘""退款回复”这种直接的词开头，两三个字符就能筛到唯一一条。
分号在哪儿能用、按键怎么走
插入的触发条件有个容易踩的细节。官方文档写的是：在行首或者一个空格之后打 ;，才会打开片段菜单。换句话说，在一句话中间紧贴着前一个字符打分号，按文档描述的条件是不满足触发前提的。这也解释了为什么这个设计不会误伤正常写作——大多数时候你打分号是当标点用的，而标点通常紧跟在字符后面。
菜单打开后的操作是一套很短的键位：
| 操作 | 按键 |
|---|---|
| 打开创建启动器 | c |
| 新建片段 | c 然后 s |
| 唤起片段菜单 | ;（行首或空格之后） |
| 按名称过滤 | 继续往下打字 |
| 上下移动 | ↑ / ↓ |
| 插入选中的片段 | enter |
| 关掉菜单、把分号留成普通文本 | esc 或 space |
最后那条值得单独记一下：esc 或空格会关掉菜单并把已经打出来的 ; 保留成普通文本。也就是说误触了不用退格，继续打就行。
能插入的位置，官方文档列了五类 markdown 界面：
| 可插入的位置 | 说明 |
|---|---|
| 文档 | 文档编辑器本身也支持用 ; 唤起片段菜单，与斜杠菜单并列 |
| 任务 | 任务正文同样是 markdown 面 |
| 频道消息 | 发消息时可直接插模板 |
| 画布文本框 | Canvas 里的文字块 |
| agent 指令 | 给 agent 写指令的地方 |
最后一类容易被忽略但挺实用。Macro 的 agent 是工作区内的角色，能搜索和阅读你能看到的东西、起草邮件和文档、建任务、往频道里发消息，并且能按计划定时跑；它们继承你的权限，产出都归到你名下。这一块的能力边界见 Macro 的 Agent 能做什么、边界在哪。既然 agent 指令也是 markdown 面，那些反复用的提示词骨架——比如”先只起草不要发送""输出按这几栏列表格”——就可以存成片段，写指令时一个分号调出来，省掉每次凭记忆重打的偏差。
顺带说清楚一个容易混的点：在文档编辑器里，/ 是斜杠菜单，用来插入编辑器自带的块（普通文本、标题、引用、代码块、各类列表、内联任务、图片、视频、链接、公式、5×3 表格、分割线）；; 是片段菜单，插入的是你自己攒的那份 markdown。两套菜单各管各的。文档编辑器的完整能力见 Macro 文档的实时协作与 markdown 原生机制。
个人的还是团队的：一个开关的事
按官方文档，片段刚建出来时是个人的（personal）。要共享，打开这个片段，在侧栏 Sharing 区把 Share with team 打开。之后这条片段会出现在每个队友的分号菜单里，而且队友可以编辑它——文档给的用途说明是：让全团队共用的模板保持单一事实来源。
这里有两点值得留意。
第一，“队友可以编辑”是双向的。单一事实来源的好处是模板改版一次到位，代价是任何一个队友都能改动共享片段。片段文档里没有提到共享片段有没有编辑者/评论者/只读这类分级，也没有提版本历史或回滚——注意，文档那边是明确有这两样的（文档用的是 owner、editor、commenter、viewer 四级权限，并且有按用户和时间分组的历史版本，还能把任意历史版本 fork 成新文档），但片段文档一个字都没提这些是否同样适用。所以在没有实测确认之前，不要按”改坏了能翻历史”来规划共享片段的使用方式。
第二，片段的共享路径和 Macro 主流的共享方式不是同一套。Macro 的权限模型官方称为”基于频道的共享”——把东西 @ 提到某个频道里，它就共享给了这个频道的全部成员；有人加入频道就获得访问权，被移出就失去。而片段用的是自身侧栏的一个”共享给团队”开关，粒度是个人 / 全团队二选一，文档没有提能否只共享给某几个人或某个频道。关于整体权限模型的细节，见 Macro 的权限模型：谁能看到什么。
什么内容值得做成片段
官方文档给的判断标准只有一句，但很好用：任何你输入超过两次的东西。文档列举的例子包括每周更新的格式、入职清单、支持回复、PR 描述，以及样板法律条款。
按这个标准往下推，可以自己排一张优先级表——下面这段只是普通 markdown，不是 Macro 的特殊语法，片段里写什么完全由你决定：
## 周会纪要
**日期**：
**参会**：
### 上周进展
- [ ]
### 本周计划
- [ ]
### 阻塞项
| 事项 | 负责人 | 需要谁 |
|---|---|---|
| | | |
这种带复选框和表格的骨架，正是”片段是一份完整 markdown 文档”这条设定带来的直接好处：插进来就是可勾选、可填的结构，不用再手搓格式。
判断一条内容该不该做成片段，除了”是否输入超过两次”，还可以再加一层：这段内容的格式是否稳定、内容是否需要因人因事大改。格式稳定、只改填空的（会议纪要、复盘、PR 描述）最划算；每次都要重写大半的，做成片段反而多一道删改。
什么时候不适用，以及文档没说的部分
先说清楚适用边界。片段是”插入固定内容”，官方文档里没有出现任何关于变量、占位符、动态字段的描述——没有提到能自动填当天日期、能插入光标跳转位、能带参数替换。如果你的需求是”模板里有三处每次都不一样、希望插入后自动停在第一处待填”，按现有文档描述，Macro 的片段做不到这一层，你只能插进来手动改。这跟很多文本展开工具的能力模型是不同的，不要按那套预期来规划。
其次是批量管理。官方文档没有提到片段的导入导出、文件夹归类，也没有提到给片段打标签。Macro 的 MCP 服务对外暴露的工具一共 16 个（bash 代码执行、内容搜索、建文档、取实体属性、取会话、列实体、名称搜索、读内容、读元数据、读会话、发邮件、设实体属性、文本编辑器代码执行、更新会话标签、网页抓取、网页搜索），里面没有任何一个是片段相关的。也就是说，想用脚本把现有的一百条模板批量灌进去，官方文档目前没有给出这条路径。
再次是触发方式本身。分号是唯一的唤起符号，文档没有提到能不能改成别的字符，也没有提到能否给单个片段设置缩写码直接展开。习惯了”打 ;zb 直接出周报”这种缩写展开的人，需要调整一下预期：这里的流程固定是分号 → 打名字过滤 → 回车。
最后是几处纯粹的空白，列出来是为了避免误判：已插入内容是否随片段更新而变化，文档未说明；共享片段是否有权限分级和版本历史，片段文档未提；片段数量是否有上限、是否计入某种配额，文档未说明。这些都需要在自己的工作区里验证，或者等官方补充说明，不要照着其它产品的习惯去假设。
把这些边界摆清楚之后，片段的定位其实很明确：它解决的是”结构固定、反复输入”这一类摩擦，靠的是一个分号加两三个字符的检索成本，加上”改一处、后续全部生效”的共享模板机制。它不打算做参数化模板引擎，也没有配套的批量管理能力。按这个定位去用，收益是稳的；越过这条线去期待，就会失望。
延伸阅读
- 从头读起：Macro 是什么：邮件、任务、文档、CRM 共用一个双向数据库的开源工作区
- 本专题共 40 篇，完整分组目录见专题页
- Macro 的 GitHub 集成到底做了什么：分支、PR 合并与任务状态自动同步的边界在哪
- Macro 的应用体系与扩展点：MCP、GitHub 与自托管到底能接什么
本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、
MCP 工具参考与自托管说明整理，核对日 2026-08-17。
我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感；
官方标注为计划中的能力文中已如实标明，不代表当前可用。
价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。