Gumloop 功能规格 - Revamped Agent Composer

初始上下文

1. 概览

背景

Agent 的执行质量遵循一个简单公式：上下文质量 × 模型能力 = 输出质量。模型能力由 Gumloop 提供，但上下文质量完全取决于用户在输入框中放了什么。

旧版 Composer 只有纯文本输入。用户想引用一个 Skill 时需手动输入「请使用 Customer Support Skill」——Agent 需模糊匹配名称。想引用文件时需先到文件库找到文件，再复制文件名粘贴。这带来三个问题：遗漏（忘了提到关键 Skill/文件）、歧义（拼错名称导致 Agent 找不到）、摩擦（切换页面找文件→复制→粘贴）。

新版 Composer 将输入框从「文本输入」升级为「上下文聚合器」：

┌──────────────────────────────────────────────────────────────────────┐
│                     Composer 演进                                       │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   旧版                            新版                                │
│   ┌──────────────────┐           ┌──────────────────────────────┐   │
│   │  ╔══════════════╗ │           │  @CustomerSupport @SalesData  │   │
│   │  ║ 纯文本输入...  ║ │           │  📄 Q3_report.pdf            │   │
│   │  ╚══════════════╝ │           │  ╔══════════════════════════╗ │   │
│   │                   │           │  ║ 帮我分析这份报告...        ║ │   │
│   │  只有键盘输入       │           │  ╚══════════════════════════╝ │   │
│   └──────────────────┘           │  @提及 · 上传 · 拖拽 · 文件库 │   │
│                                  └──────────────────────────────┘   │
│                                                                      │
│   上下文 = 用户写的字             上下文 = 精确引用 + 用户写的字        │
└──────────────────────────────────────────────────────────────────────┘

这个演进与 v9.9.0 Cmd+K 形成递进：「发现→引用→执行」的完整链路——Cmd+K 找到 → Composer @ 引入 → Agent 获得精确上下文。

目标

1. 消除上下文遗漏：@ 提及将 Skill/Agent/App 引用从模糊文本匹配升级为精确结构化引用
2. 消除文件上传摩擦：三种方式覆盖所有用户习惯——不需要离开对话
3. 提升 Agent 执行质量：更准确的上下文 → 更好的输出
4. 统一用户体验：@ 语法与 Slack、Notion 等主流工具一致——零学习成本

2. 核心机制 [基于 Changelog 推断]

@ 提及系统

用户在输入框中输入 @ 触发提及菜单。可提及三种实体类型：

实体类型	示例	注入上下文的含义
Agent	@Sales Research Agent	引用 Agent 的能力或作为 Subagent 调用
Skill	@Customer Support	Agent 在本次对话中可使用此 Skill 的知识和流程
App (MCP 集成)	@Google Sheets	提示 Agent 可以使用此 App 的工具

提及交互：输入 @ → 弹出菜单（最近使用+收藏优先）→ 继续输入文字实时模糊搜索 → 键盘选择 → 渲染为蓝色 chip。选中的提及被解析为结构化引用（非纯文本）——Agent 收到的是精确的实体 ID 和完整元数据。

文件附件系统

方式	操作	适用场景
本地文件上传	点击附件按钮，从本地文件系统选择	文件在电脑上
从 Gumloop 文件库选择	浏览已有 Gumloop 文件	之前上传过的文件、Agent 产出的文件
拖拽	从文件管理器拖到输入框区域	文件已在 Finder/Explorer 中——最低摩擦

上下文注入机制

@ 提及和文件附件在发送时被解析为结构化上下文——Agent 收到的系统消息中提及被展开为实体的完整元数据，附件被展开为文件引用。这确保 Agent 获得精确的上下文——不是「用户可能想用 Customer Support Skill」，而是「用户指定了 Skill ID xxx，以下是该 Skill 的内容」。

3. 功能需求

模块 A — @ 提及

ID	触发场景	系统行为	优先级
A1	用户在输入框中输入 @	弹出提及菜单，展示最近使用+收藏。按类型分组（Agent/Skill/App）	P0
A2	用户继续输入文字	实时模糊搜索匹配实体（名称+描述）。无匹配时显示「未找到」	P0
A3	用户选择某一实体	渲染为蓝色 chip。focus 回到文本输入	P0
A4	用户点击 chip × 或 backspace	chip 被移除——引用从上下文中删除	P0
A5	发送消息时	chip 解析为结构化引用——注入实体 ID+完整元数据到 Agent 上下文	P0

模块 B — 文件附件

ID	触发场景	系统行为	优先级
B1	用户点击「上传文件」	打开本地文件选择器。支持常见文件类型。上传后显示文件名 chip	P0
B2	用户点击「从 Gumloop 文件选择」	打开文件浏览器弹窗——展示已有 Gumloop 文件。支持搜索筛选	P0
B3	用户拖拽文件到输入框区域	检测 drop 事件。自动上传。大文件显示进度	P0
B4	文件超过大小限制	显示错误提示——最大大小和支持格式	P1

模块 C — 输入框重构

ID	触发场景	系统行为	优先级
C1	输入框获得焦点	如有未发送的草稿，恢复内容（包括提及和附件引用）	P1
C2	用户粘贴包含 @ 的文本	不自动触发提及转换——避免误触	P1

4. 用户场景

5. 竞争分析

竞品	功能/行为	优势	劣势
Slack Composer	@ 提及人和频道、文件拖拽、富文本	成熟的产品化体验——协作工具标杆	@ 只用于人和频道——不是泛化的实体引用。文件只是分享——不注入 AI 上下文
Notion	@ 提及页面/数据库/日期、拖拽文件	@ 可提及任何 Notion 实体——泛化程度最高	文件附件是「嵌入页面」——不是「注入 AI 上下文」
Cursor Composer	@ 提及文件、文件夹、Git 历史、文档	为 AI 编码优化的上下文系统	限于代码开发场景——实体类型是编码特定的
ChatGPT	文件上传按钮 + 纯文本	简单直接	无 @ 提及系统。无文件库选择——只能上传本地文件

关键洞察

1. @ 提及是「从打字到选择」的 UX 范式跃迁：上下文添加从「打字描述」变成「选择引用」——不仅降低输入成本，更重要的是消除歧义。Agent 收到精确实体 ID 而非模糊匹配的自然语言
2. 拖拽不是功能——是预期：文件拖拽在 Slack、Figma、Notion 中已是标配。这是「做了不加分，不做就扣分」的功能——但它是重构 Composer 的重要组成部分
3. @ 提及系统有扩展潜力：当前 @ Agent/Skill/App。未来可 @ 对话历史、@ 数据源、@ 网页 URL——@ 语法成为通用的「上下文引用协议」
4. 与 Cmd+K 的分工：Cmd+K 是「全局搜索任何东西并跳转」，Composer 是「在当前对话中精确引用东西」——互补不冲突，像 macOS Spotlight vs 应用内 @ 提及

6. 遥测

漏斗阶段	事件名称	触发条件	指标/KPI	优先级
采用	composer_mention_triggered	用户输入 @ 触发菜单	@ 提及使用率	P0
采用	composer_mention_selected	用户从菜单选择实体	各实体类型提及分布	P0
采用	composer_file_attached	用户通过任意方式附加文件	带附件的消息占比	P0
采用	composer_drag_drop_used	用户通过拖拽附加文件	拖拽使用率	P1
质量	composer_mention_search_no_result	@ 搜索无匹配	搜索无结果率	P1
影响	conversation_success_with_mentions	含 @ 提及的对话完成情况	@ 提及对对话质量的影响	P0

7. 未来演进方向

阶段	时间线	里程碑	状态
Phase 1 — 核心重构	v10.0.0	@ 提及 Agent/Skill/App + 三种文件附加	已发布
Phase 2 — 扩展引用	v10.x	@ 对话历史、@ 数据源、@ 网页 URL、粘贴图片自动上传	规划中
Phase 3 — 智能建议	v11.x	Agent 根据对话主题自动建议相关 Skill/文件——「你可能需要 Q2 报告和 Sales Data Skill」	探索中
Phase 4 — 编排入口	远期	拖拽 Agent = Subagent 调用。拖拽 Skill 到 Skill = 组合。Composer 成为 Agent 编排的视觉入口	探索中

关键演进判断

1. @ 作为通用引用协议：一旦 @ 语法在 Gumloop 中建立，它成为引用任何平台实体的通用方式。Composer 的未来不是「更好的输入框」而是「Agent 上下文的可视化组装界面」
2. 智能上下文建议可能是最大体验提升：AI 建议（「根据你当前的问题，你可能需要这些 Skill 和文件」）将上下文聚合从「手动选择」推向「AI 辅助」
3. Composer 作为编排入口：拖拽 Agent 到输入框 = Subagent 调用——Composer 从「输入框」变成「Agent 编排 GUI」