# track

> 登记或更新要跟进的东西：机会（值得行动的帖子、人、社区或合作方）、实验（带截止时间和可选停止规则的渠道尝试）和短链接（用于点击归因）。

URL: https://mcp-docs.opennomos.com/zh/docs/tools/growth/track

> 登记或更新要跟进的东西：机会（值得行动的帖子、人、社区或合作方）、实验（带截止时间和可选停止规则的渠道尝试）和短链接（用于点击归因）。登记机会只需要 URL 或标题。重复的 URL 会更新已有的机会。阶段可以按任意顺序设置，也从不推断。每次调用最多 20 项；其中一项失败不影响其他项。实验不会自动结束：你做出决定（stop、scale、extend、keep）时再记录。

> 以上是服务端发布的英文描述的译文；英文原文见[英文页](https://mcp-docs.opennomos.com/docs/tools/growth/track.md)。工具名、参数名和取值保持原样。

| 字段 | 值 |
| --- | --- |
| 工具包 | Core (`core`) |
| 每次调用的预估成本 | $0 |
| 工具包每月上限 | 无 |
| 项目 | 按顺序确定：显式的 `project` → 请求头 → 凭据默认项目 → 工作区默认项目 |

## 参数

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `project` | 否 | `string` | 项目 slug 或 id。省略则用凭据或工作区的默认项目。 |
| `items` | 是 | `object[]` | 要登记或更新的 1–20 项，例如 [\{"type":"opportunity","opportunity":\{"url":"https://reddit.com/r/SaaS/comments/abc"\}\}]。 |
| `items[].type` | 是 | `"opportunity"` \| `"experiment"` \| `"link"` | 这一项是什么；它的字段放在同名的对象里。 |
| `items[].id` | 否 | `string` | 已有机会或实验的 id，用来更新它而不是新建。 |
| `items[].opportunity` | 否 | `object` | 用于 type=opportunity。字段：title、url、kind、summary、tags[]、priority（-1\|0\|1）、stage、experiment_id、next_followup（\{in_days\}\|\{at\}\|ISO\|null）、source。给 title 或 url 之一就够。已被登记的 URL 会更新那个机会。 |
| `items[].experiment` | 否 | `object` | 用于 type=experiment。创建：name、channel、metric、days\|deadline，可选 hypothesis、target、stop_rule\{metric,op,value\}、stop_rule_text。带 id 时是更新：name、hypothesis、target、stop_rule_text、decision（stop\|scale\|extend\|keep）、extend_days、note。metric:tracked、contacted、replied、willing_to_talk、converted、actions、clicks 或 outcome:<type>。 |
| `items[].link` | 否 | `object` | 用于 type=link。字段：target_url（https）、channel、label、opportunity_id、experiment_id、mode（redirect\|utm_only）。返回带 UTM 参数的短 URL。 |

## 示例调用

```json
{
  "project": "acme-crm",
  "items": [
    {
      "type": "opportunity",
      "opportunity": {
        "url": "https://www.reddit.com/r/SaaS/comments/1abc23/looking_for_a_lightweight_crm",
        "tags": [
          "crm"
        ],
        "next_followup": {
          "in_days": 2
        }
      }
    },
    {
      "type": "experiment",
      "experiment": {
        "name": "Reddit helpful replies",
        "channel": "reddit",
        "metric": "willing_to_talk",
        "days": 14,
        "target": 3,
        "stop_rule": {
          "metric": "willing_to_talk",
          "op": "<",
          "value": 2
        }
      }
    },
    {
      "type": "link",
      "link": {
        "target_url": "https://acme.com/pricing",
        "channel": "reddit",
        "experiment_id": "exp_7Hn2LpWc0"
      }
    }
  ]
}
```

REST:`POST https://service.opennomos.com/v1/tools/track`，以上 JSON 作为请求体。MCP:`tools/call`,`name: "track"`，以上 JSON 作为 `arguments`。

## 示例结果

示例里的值是示意性的；结构来自服务端代码。

```json
{
  "project": {
    "id": "prj_k3Vd9aQx2",
    "slug": "acme-crm"
  },
  "results": [
    {
      "index": 0,
      "type": "opportunity",
      "status": "created",
      "id": "opp_Qm4x9TnB1",
      "stage": "discovered",
      "next_followup_at": "2026-10-18T09:00:00.000Z"
    },
    {
      "index": 1,
      "type": "experiment",
      "status": "created",
      "id": "exp_7Hn2LpWc0",
      "deadline_at": "2026-10-30T09:00:00.000Z"
    },
    {
      "index": 2,
      "type": "link",
      "status": "created",
      "mode": "redirect",
      "id": "lnk_Tz81vM2",
      "code": "aB3dE9xQ",
      "short_url": "https://service.opennomos.com/l/aB3dE9xQ",
      "final_url": "https://acme.com/pricing?utm_source=reddit&utm_medium=opennomos&utm_campaign=exp_7Hn2LpWc0&utm_content=aB3dE9xQ"
    }
  ],
  "summary": {
    "created": 3,
    "updated": 0,
    "duplicate": 0,
    "error": 0
  }
}
```

## 说明

- 一次调用接受 1–20 项。各项相互独立：某一项失败时，它会得到 `status: "error"` 和一个 `code`，不影响其他项。
- **机会**：给标题或 URL 之一就够。已经登记过的 URL（规范化 Reddit、X、小红书的帖子 URL，并去掉 `utm_*`、`fbclid`、`gclid` 之后）会更新已有的机会，返回 `duplicate` 或 `updated`。阶段可以按任意顺序设置，也从不推断。
- **实验**：创建时给 `name`、`channel`、`metric`，以及 `days` 或 `deadline` 中的一个。更新时传实验的 `id`:`name`、`hypothesis`、`target`、`stop_rule_text`、`note`，以及 `decision`（`stop`、`scale`、`extend` 或 `keep`;`extend` 还需要 `extend_days`）。实验不会自动结束。见[实验](https://mcp-docs.opennomos.com/zh/docs/growth-loop/experiments.md)。
- **短链接**：返回短 URL（`redirect` 模式）或只带 UTM 的 URL（`utm_only` 模式）。链接只能创建，不能更新。见[归因](https://mcp-docs.opennomos.com/zh/docs/growth-loop/attribution.md)。
- 写入按工作区限流（每分钟 60 次，按服务实例计）。

## 错误

被拒绝的调用（输入有误、id 未知、触发限流）返回 `message` 和 `code`；走 MCP 时结果带 `isError: true`。见[错误](https://mcp-docs.opennomos.com/zh/docs/reference/errors.md)。