AI Agent 快捷指令协议：命令、定向发送与对象引用
版本说明：统一快捷指令协议自
v0.0.4.beta起提供。使用时应优先选择界面、审批通知或连接器自动生成的标准文本，不建议手工猜测对象 ID。
用户与 AI Agent 交流时，大多数内容都是自然语言任务，例如“整理这份报告”或“继续分析风险”。但删除会话、压缩上下文、指定目标会话和提交审批意见并不适合交给模型理解后再决定如何执行。
xAgent 使用快捷指令协议，把确定性控制与普通任务分开：
/command 是后端确定性命令。
@{type:id} 表示定向发送或提交给明确目标。
#{type:id} 仅表示对象引用，不改变路由、不隐式执行操作。
@{approval:id} 同意/不同意 是审批控制回复。
#{approval:id} 只是引用审批记录。
为什么需要这套协议
如果只使用自然语言，下面几句话可能产生歧义：
- “删除它”指的是删除当前会话、某个文件，还是只删除一段草稿？
- “让研究会话继续”是把消息发给研究会话，还是让当前 Agent 代为总结？
- “我同意这个审批”对应哪一张审批单？
- 在消息中出现一个文件编号，是否代表允许读取、发送或删除该文件？
xAgent 的设计原则是：自然语言负责表达任务，快捷协议负责表达确定目标和确定操作。
协议先由系统解析，再进行对象归属、权限、状态和操作范围校验。已经被系统识别的命令或审批回复不会再交给模型猜测，也不会作为普通任务重复进入 Agent 上下文。
这样做主要解决四个问题：
- 结果可预期：同一条命令不会因为模型不同而产生不同解释。
- 目标不含糊：消息明确发送到哪个会话、审批意见提交给哪张审批单。
- 权限不旁路：引用对象不等于获得读取、修改或执行权限。
- 入口一致：Web、IM 连接器和其他文本入口可以使用同一套表达方式。
一张表看懂四种用法
| 写法 | 含义 | 是否改变消息目标 | 是否直接执行操作 |
|---|---|---|---|
/command | 对当前会话执行确定性命令 | 否 | 是 |
@{session:id} 内容 | 把内容发送到指定会话 | 是 | 取决于后续内容 |
#{type:id} | 在当前消息中引用一个对象 | 否 | 否 |
@{approval:id} 同意/不同意 | 向指定审批提交明确意见 | 是，路由到审批所属会话 | 是 |
/command：确定性命令
Slash Command 用于执行由系统明确实现的会话操作，不进入 Agent 的任务理解流程。
/compress
没有指定目标时，命令作用于当前会话。也可以在前面添加会话目标：
@{session:13c2b2f5744009c} /compress
这条指令会对指定会话执行上下文压缩，而不是把“/compress”作为一句话发给 Agent。
v0.0.4.beta 中的会话命令
| 命令 | 适用范围 | 作用 | 执行位置 |
|---|---|---|---|
/refresh_messages | 主会话、子会话 | 重新同步当前页面中的会话消息 | Web 页面本地 |
/delete | 仅子会话 | 删除目标子会话 | xAgent 后端 |
/clear-history | 仅主会话 | 推进主会话的历史可见起点 | xAgent 后端 |
/compress | 主会话、子会话 | 手工触发目标会话的上下文压缩 | xAgent 后端 |
命令应独立发送。未知命令、附带多余文本、目标类型不匹配或当前状态不允许执行时，系统会返回明确错误，不会回退成普通 Agent 任务。
@{session:id}：定向发送到会话
在消息开头使用会话目标，可以把后续内容直接发送给指定会话：
@{session:13c2b2f5744009c} 请根据新材料继续检查结论
目标必须位于消息开头。下面的写法只会被视为当前消息中的普通文字，不会自动改变路由：
请让 @{session:13c2b2f5744009c} 继续检查结论
这样可以避免用户引用一段包含 SessionRef 的文字时，消息被意外发送到其他会话。
定向发送不会绕过会话归属校验。目标不存在、已删除、不属于当前用户，或者一条消息包含多个不同目标时，系统会拒绝投递。
@{type:id} 是统一协议格式，但只有真正能够接收消息或控制意见的对象才能作为目标。v0.0.4.beta 公开使用的目标类型是 session 和 approval；文件应使用 #{file:id} 引用，不能作为消息目标。
#{type:id}：只引用对象
对象引用用于告诉当前会话“这段任务涉及哪个对象”，但它不会改变消息发送目标，也不会隐式执行操作。
引用文件
请分析 #{file:2329}，提取风险项并生成摘要
#{file:2329} 只定位文件。真正读取文件时仍需校验当前用户与会话的访问范围，并通过相应文件能力完成。
引用会话
请比较当前结果与 #{session:13c2b2f5744009c} 的结论
这条消息仍发送到当前会话。引用另一个会话不等于向它发送消息，也不保证当前 Agent 已具备读取该会话内容的能力。
引用审批记录
请解释 #{approval:13c5b94bb80003e} 为什么需要审批
这只是在当前任务中引用审批记录，不会提交“同意”或“不同意”。对象是否能被进一步读取或处理，仍取决于当前版本提供的能力和权限。
@{approval:id}：提交审批意见
审批决策必须使用定向目标和明确意见：
@{approval:13c5b94bb80003e} 同意
@{approval:13c5b94bb80003e} 不同意
英文界面或英文审批通知可以使用：
@{approval:13c5b94bb80003e} approve
@{approval:13c5b94bb80003e} reject
系统会根据审批编号找到对应会话，校验审批归属与当前等待状态，再提交首个有效意见。审批已经处理、失效或已有其他入口提交意见时，后续回复不会再次改变结果。
下面的写法不能完成审批：
#{approval:13c5b94bb80003e} 同意
原因是 # 永远只表示引用。把“同意”写在引用后面，也不会把引用提升成审批控制指令。
组合使用
快捷协议可以组合，但处理顺序始终明确：先确定目标，再判断后续内容是命令还是普通消息，最后保留正文中的对象引用。
向指定会话发送包含文件引用的任务
@{session:13c2b2f5744009c} 请检查 #{file:2329} 并更新报告
含义是：
- 把消息发送到指定 Session。
- 在任务正文中引用指定 File。
- 是否读取和修改文件，仍由目标会话的能力、权限和审批策略决定。
对指定会话执行命令
@{session:13c2b2f5744009c} /compress
含义是对目标会话执行确定性压缩，不激活一次普通 Agent 对话。
在 Web 和 IM 中怎么使用
Web 会话
在输入框中输入 /、@{ 或 #{ 时，界面可以提供当前可用对象或命令候选。优先从候选列表插入标准格式，避免手工输入错误 ID。
IM 连接器
微信、Telegram 等连接器收到包含标准快捷指令的文本后，会先解析目标和操作，再决定投递到哪个会话。未指定会话目标的普通消息默认进入当前用户的主会话。
审批通知会附带完整回复格式。直接回复通知中提供的标准文本即可，不要只回复“同意”，否则系统无法确定对应的审批单。
安全与使用边界
@只确定接收目标，不会自动授予 Tool、文件或外部系统权限。#只引用对象，不等于读取、删除、发送、审批或执行。/command只能执行系统已经实现并允许的命令。- 所有目标都必须经过用户归属、存在状态和操作范围校验。
- 一条输入只能有一个明确的不同目标，避免路由冲突。
- 快捷指令不能绕过工作区虚拟文件系统、审批策略或连接器授权。
- 系统无法确认语法、对象或权限时应明确报错，而不是交给模型猜测。
常见错误
| 错误写法 | 问题 | 正确方式 |
|---|---|---|
#{approval:id} 同意 | 引用不提交审批意见 | @{approval:id} 同意 |
请让 @{session:id} 继续 | 目标不在消息开头 | @{session:id} 请继续 |
@{session:id} | 目标后没有消息或命令 | 补充正文或 /command |
/compress 然后继续写报告 | 命令混入普通任务 | 先单独发送 /compress，完成后再发任务 |
@{file:id} 分析 | 文件不是消息接收目标 | 分析 #{file:id} |