segment-automation

通过 Rube MCP 自动化 Segment

通过 Rube MCP 使用 Composio 的 Segment 工具包，自动化 Segment 客户数据平台的操作。

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过工具包 segment 使用 RUBE_MANAGE_CONNECTIONS 建立有效的 Segment 连接
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，验证 Rube MCP 可用
2. 使用工具包 segment 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请使用返回的授权链接完成 Segment 身份验证
4. 运行任何工作流前，确认连接状态为 ACTIVE

来源、身份与隐私范围

确认具体的来源、工作区、环境和下游目标。测试事件可能触发客户消息并污染生产指标；请使用经批准的测试来源和合成 ID。发送用户特征或上下文需要适当的同意和数据共享授权，不能仅凭已配置目标就认定已获授权。对于不确定的重试，请预览身份合并和来源更新，并核对稳定的消息 ID。检查实际架构和目标语义，了解删除、空值用户特征及别名行为；请求被接受不代表已送达。

核心工作流

1. 跟踪事件

使用场景：用户想要向 Segment 发送事件数据，以便传递到下游目标

工具调用顺序：

1. SEGMENT_TRACK - 发送单个跟踪事件［必需］

关键参数：

• userId：用户标识符（未提供 anonymousId 时必需）
• anonymousId：匿名标识符（未提供 userId 时必需）
• event：事件名称（例如，'Order Completed'、'Button Clicked'）
• properties：包含特定事件属性的对象
• timestamp：ISO 8601 时间戳（可选；默认为服务器时间）
• context：包含上下文元数据的对象（IP、用户代理等）

注意事项：

• 必须至少提供 userId 或 anonymousId 其中之一
• 必须提供 event 名称，并遵循一致的命名规范
• 属性为自由格式对象；请确保各事件的架构一致
• 时间戳必须采用 ISO 8601 格式（例如，'2024-01-15T10:30:00Z'）
• 事件采用异步处理；API 响应成功表示请求已接受，而非已送达

2. 识别用户

使用场景：用户想要将用户特征关联到 Segment 中的用户资料

工具调用顺序：

1. SEGMENT_IDENTIFY - 设置用户特征和身份［必需］

关键参数：

• userId：用户标识符（未提供 anonymousId 时必需）
• anonymousId：匿名标识符
• traits：包含用户属性的对象（电子邮件、姓名、套餐等）
• timestamp：ISO 8601 时间戳
• context：上下文元数据

注意事项：

• 必须至少提供 userId 或 anonymousId 其中之一
• 用户特征会与现有特征合并，而非替换
• 如需移除某项特征，请将其设为 null
• 对新用户，应先调用 Identify，再调用 Track
• 除非目标已配置为允许处理个人身份信息，否则请避免在用户特征中发送个人身份信息

3. 批量操作

适用场景：用户希望在单个请求中发送多个事件、identify 或其他调用

工具调用顺序：

1. SEGMENT_BATCH - 在单个请求中发送多个 Segment 调用［必需］

关键参数：

• batch：消息对象数组，每个对象包含：
  • type：消息类型（'track'、'identify'、'group'、'page'、'alias'）
  • userId / anonymousId：用户标识符
  • 根据类型而定的其他字段（event、properties、traits 等）

注意事项：

• 批次中的每条消息都必须包含有效的 type 字段
• 批次大小上限适用；请查看 schema 以了解当前上限
• 批次中的所有消息会独立处理；一条消息失败不会影响其他消息
• 每条消息都必须单独满足其类型的要求（例如，track 需要事件名称）
• 批量操作是发送多个调用的最高效方式；优先使用批量操作，而非逐条调用

4. 对用户进行分组

适用场景：用户希望将某个用户与公司、团队或组织关联起来

工具调用顺序：

1. SEGMENT_GROUP - 将用户与群组关联［必需］

关键参数：

• userId：用户标识符（若没有 anonymousId，则必填）
• anonymousId：匿名标识符
• groupId：群组／组织标识符（必填）
• traits：包含群组属性的对象（name、industry、size、plan）
• timestamp：ISO 8601 时间戳

注意事项：

• 必须提供 groupId；它用于标识公司或组织
• 群组 traits 会与该群组现有的 traits 合并
• 一个用户可以属于多个群组
• 群组 traits 会更新群组资料，而非用户资料

5. 跟踪页面浏览量

适用场景：用户希望在 Segment 中记录页面浏览事件

工具调用顺序：

1. SEGMENT_PAGE - 发送页面浏览事件［必需］

关键参数：

• userId：用户标识符（若没有 anonymousId，则必填）
• anonymousId：匿名标识符
• name：页面名称（例如，'Home'、'Pricing'、'Dashboard'）
• category：页面类别（例如，'Docs'、'Marketing'）
• properties：包含页面特定属性的对象（url、title、referrer）

注意事项：

• 必须至少提供 userId 或 anonymousId 其中之一
• name 和 category 是可选参数，但建议提供，以便进行正确的分析
• 标准属性包括 url、title、referrer、path、search
• 页面调用通常会自动执行；手动调用适用于服务端页面跟踪

6. 设置用户别名并管理来源

适用场景：用户希望合并匿名用户与已识别用户，或管理来源配置

工具调用顺序：

1. SEGMENT_ALIAS - 关联两个用户身份［可选］
2. SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE - 查看来源 schema 设置［可选］
3. SEGMENT_UPDATE_SOURCE - 更新来源配置［可选］

关键参数：

• 对于 ALIAS：
  • userId：新的用户标识符（已识别的 ID）
  • previousId：旧的用户标识符（匿名 ID）
• 对于来源操作：
  • sourceId：来源标识符

注意事项：

• ALIAS 是单向操作；无法撤销
• previousId 是匿名／旧 ID，userId 是新的／已识别的 ID
• 并非所有目标端都支持别名调用；请查看目标端文档
• 仅在实际目标端的身份模型有此要求时才使用 alias；不要假设每次注册都需要不可撤销的合并。
• 更新来源可能会影响数据收集；请仔细检查变更

常见模式

用户生命周期

标准的 Segment 用户生命周期：

1. Anonymous user visits -> PAGE call with anonymousId
2. User interacts -> TRACK call with anonymousId
3. User signs up -> IDENTIFY with stable userId; alias only if the configured destination identity flow requires it
4. User takes action -> TRACK call with userId
5. User joins org -> GROUP call linking userId to groupId

批量优化

对于批量数据摄取：

1. Collect events in memory (array of message objects)
2. Each message includes type, userId/anonymousId, and type-specific fields
3. Call SEGMENT_BATCH with the collected messages
4. Check response for any individual message errors

命名约定

Segment 建议统一事件命名：

• 事件：使用“对象 动作”格式（例如，'Order Completed'、'Article Viewed'）
• 属性：使用 snake_case（例如，'order_total'、'product_name'）
• Traits：使用 snake_case（例如，'first_name'、'plan_type'）

已知注意事项

身份解析：

• 每次调用都必须包含 userId 或 anonymousId
• 每个用户身份合并只使用一次 ALIAS
• 先识别用户再跟踪事件，确保正确关联用户

数据质量：

• 所有来源的事件名称应保持一致
• 属性应遵循定义好的架构，以确保下游兼容性
• 除非已为目标配置相关处理，否则避免发送敏感 PII

速率限制：

• 批量操作请使用 BATCH，以遵守速率限制
• 单独调用会按来源进行速率限制
• 批量调用效率更高，也更不容易受到限流

响应解析：

• 成功响应表示请求已被接受，并不代表已发送至目标
• 响应数据可能嵌套在 data 键下
• 检查批量响应中的错误字段，了解单条消息是否失败

时间戳：

• 必须采用带时区的 ISO 8601 格式（例如：'2024-01-15T10:30:00Z'）
• 省略时间戳时将使用服务器接收时间
• 导入历史数据时应包含明确的时间戳

快速参考

任务	工具标识	关键参数
跟踪事件	SEGMENT_TRACK	userId, event, properties
识别用户	SEGMENT_IDENTIFY	userId, traits
批量调用	SEGMENT_BATCH	batch (array of messages)
用户分组	SEGMENT_GROUP	userId, groupId, traits
页面浏览	SEGMENT_PAGE	userId, name, properties
合并身份	SEGMENT_ALIAS	userId, previousId
来源架构	SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE	sourceId
更新来源	SEGMENT_UPDATE_SOURCE	sourceId
数据仓库	SEGMENT_LIST_CONNECTED_WAREHOUSES_FROM_SOURCE	sourceId

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。