catalog/repos/activitysmithhq--activitysmith-cli.md

# iOS推送与动态岛CLI工具

`推送通知` `实时活动` `CLI` `Node.js` `iOS` `API封装`

# ActivitySmith CLI

ActivitySmith API 的 CLI 封装工具，基于官方 Node SDK 构建。

## 安装

```bash
npm install -g activitysmith-cli
```

## 安装技能（适用于 Codex/Claude 等支持 Skills 的智能体）

从本仓库安装公开技能：

```bash
npx skills add ActivitySmithHQ/activitysmith-cli --skill activitysmith
```

技能在本仓库中的路径：

```text
skills/activitysmith
```

该技能与智能体平台无关，使用 `ACTIVITYSMITH_API_KEY` 进行鉴权，命令与下文所示 CLI 命令相同。

## 鉴权

设置环境变量 `ACTIVITYSMITH_API_KEY`，或通过 `--api-key` 参数传入。

对于技能脚本，也可以将 `skills/activitysmith/.env.example` 复制为 `skills/activitysmith/.env`。

## 推送通知

运行 `activitysmith --help` 查看所有可用命令。

### 发送推送通知

```bash
activitysmith push \
  --title "构建失败 🚨" \
  --message "CI 流水线在 main 分支失败"
```

### 带媒体的富文本推送通知

<p align="center">
  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-image.png" alt="带图片的富文本推送通知" width="680" />
</p>

```bash
activitysmith push \
  --title "首页已就绪" \
  --message "您的智能体已完成重新设计。" \
  --media "https://cdn.example.com/output/homepage-v2.png" \
  --redirection "https://github.com/acme/web/pull/482"
```

在推送通知中发送图片、视频或音频，长按可直接在通知中预览媒体内容，点击后跳转至关联链接。

<p align="center">
  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png" alt="带音频的富文本推送通知" width="680" />
</p>

支持以下格式：

- 图片直链：`.jpg`、`.png`、`.gif` 等
- 音频文件直链：`.mp3`、`.m4a` 等
- 视频文件直链：`.mp4`、`.mov` 等
- 响应头包含正确媒体 `Content-Type` 的 URL（即使路径无扩展名）

`--media` 可与 `--redirection` 组合使用，但不能与 `--actions` 或 `--actions-file` 同时使用。

### 可交互推送通知

<p align="center">
  <img src="https://cdn.activitysmith.com/features/actionable-push-notifications-2.png" alt="可交互推送通知示例" width="680" />
</p>

可交互推送通知支持点击时打开 URL，或在长按通知时触发指定操作。Webhook 由 ActivitySmith 后端执行。

```bash
activitysmith push \
  --title "构建失败 🚨" \
  --message "CI 流水线在 main 分支失败" \
  --redirection "https://github.com/org/repo/actions/runs/123456789" \
  --actions '[
    {
      "title": "打开失败记录",
      "type": "open_url",
      "url": "https://github.com/org/repo/actions/runs/123456789"
    },
    {
      "title": "创建事故",
      "type": "webhook",
      "url": "https://hooks.example.com/incidents/create",
      "method": "POST",
      "body": {
        "service": "payments-api",
        "severity": "high",
        "source": "activitysmith-cli"
      }
    }
  ]'
```

也可以从文件加载操作配置：

```bash
activitysmith push \
  --title "构建失败 🚨" \
  --message "CI 流水线在 main 分支失败" \
  --actions-file "./actions.json"
```

## 实时活动（Live Activities）

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png" alt="指标类实时活动截图" width="680" />
</p>

实时活动共有三种类型：

- `metrics`（指标）：适合展示实时运营统计数据，如服务器 CPU 和内存、队列深度或副本延迟
- `segmented_progress`（分段进度）：适合基于步骤的工作流，如部署、备份和 ETL 流水线
- `progress`（进度）：适合连续任务，如上传、重建索引等以百分比追踪的长时任务

通过 API 使用实时活动时，有两种方案可选。第一种是**无状态模式**，最为简单——一次 API 调用即可启动或更新活动，另一次调用结束活动，无需在您这边追踪状态。该模式适合追求低复杂度的场景，非常适合定时任务等自动化工作流。

第二种是**经典模式**，提供对生命周期的精确控制，分别有独立的启动、更新和结束调用，让您完全掌控活动状态。

以下各节将逐一介绍这两种实现方式，您可以根据使用场景选择最合适的方案。

### 简单模式：让 ActivitySmith 自动管理实时活动

使用稳定的 `stream_key` 标识您正在追踪的系统或工作流，例如服务器、部署、构建流水线、定时任务或充电会话。这对于定时任务等计划任务特别有用，因为您无需在两次运行之间存储 `activity_id`。

#### 指标（Metrics）

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png" alt="指标流示例" width="680" />
</p>

```bash
activitysmith activity stream prod-web-1 \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 9, "unit": "%" },
      { "label": "MEM", "value": 45, "unit": "%" }
    ]
  }'
```

#### 分段进度（Segmented Progress）

<p align="center">
  <img src="https://cdn.activitysmith.com/features/update-live-activity.png" alt="分段进度流示例" width="680" />
</p>

```bash
activitysmith activity stream nightly-backup \
  --content-state '{
    "title": "夜间备份",
    "subtitle": "上传归档",
    "type": "segmented_progress",
    "numberOfSteps": 3,
    "currentStep": 2
  }'
```

#### 进度（Progress）

<p align="center">
  <img src="https://cdn.activitysmith.com/features/progress-live-activity.png" alt="进度流示例" width="680" />
</p>

```bash
activitysmith activity stream search-reindex \
  --content-state '{
    "title": "搜索重建索引",
    "subtitle": "catalog-v2",
    "type": "progress",
    "percentage": 42
  }'
```

每当状态发生变化时，使用相同的 `stream_key` 再次运行 `activitysmith activity stream <stream-key> ...`。

#### 结束流

当被追踪的进程结束，且您不再希望设备上显示实时活动时使用此命令。`content_state` 在此处为可选项；如果您希望以最终状态结束流，可以包含它。

```bash
activitysmith activity end-stream prod-web-1 \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 7, "unit": "%" },
      { "label": "MEM", "value": 38, "unit": "%" }
    ]
  }'
```

如果之后使用相同的 `stream_key` 再次发送 `activity stream` 请求，ActivitySmith 将为该流重新启动一个新的实时活动。

流响应中包含 `operation` 字段：

- `started`：ActivitySmith 为此 `stream_key` 启动了新的实时活动
- `updated`：ActivitySmith 更新了当前实时活动
- `rotated`：ActivitySmith 结束了上一个实时活动并启动了新的
- `noop`：传入状态与当前状态一致，未发送更新
- `paused`：流已暂停，未启动或更新实时活动
- `ended`：流结束后由 `activity end-stream` 返回

### 高级模式：完整生命周期控制

当您需要自行管理实时活动的生命周期时使用以下命令：

1. 运行 `activitysmith activity start ...`
2. 保存返回的 `activity_id`
3. 随着进度变化运行 `activitysmith activity update ...`
4. 工作完成后运行 `activitysmith activity end ...`

以下示例可使用 `--content-state <json>` 传入内容状态，也可以按照「内容状态选项」文档中所述使用标志位构建相同的载荷。

### 指标类型（Metrics）

当您希望持续展示一组实时统计数据时使用 `metrics`，例如服务器健康状况、队列压力或数据库负载。

#### 启动

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png" alt="指标启动示例" width="680" />
</p>

```bash
activitysmith activity start \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 9, "unit": "%" },
      { "label": "MEM", "value": 45, "unit": "%" }
    ]
  }'
```

#### 更新

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-update.png" alt="指标更新示例" width="680" />
</p>

```bash
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 76, "unit": "%" },
      { "label": "MEM", "value": 52, "unit": "%" }
    ]
  }'
```

#### 结束

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-end.png" alt="指标结束示例" width="680" />
</p>

```bash
activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 7, "unit": "%" },
      { "label": "MEM", "value": 38, "unit": "%" }
    ],
    "autoDismissMinutes": 2
  }'
```

### 分段进度类型（Segmented Progress）

当任务或工作流会经历明确的步骤或阶段时使用 `segmented_progress`，适合部署、备份、ETL 流水线和检查清单等场景。`numberOfSteps` 是动态的，可在工作流变化时随时增减。

#### 启动

<p align="center">
  <img src="https://cdn.activitysmith.com/features/start-live-activity.png" alt="分段进度启动示例" width="680" />
</p>

```bash
activitysmith activity start \
  --content-state '{
    "title": "夜间数据库备份",
    "subtitle": "创建快照",
    "numberOfSteps": 3,
    "currentStep": 1,
    "type": "segmented_progress",
    "color": "yellow"
  }'
```

#### 更新

<p align="center">
  <img src="https://cdn.activitysmith.com/features/update-live-activity.png" alt="分段进度更新示例" width="680" />
</p>

```bash
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "夜间数据库备份",
    "subtitle": "上传归档",
    "numberOfSteps": 3,
    "currentStep": 2
  }'
```

#### 结束

<p align="center">
  <img src="https://cdn.activitysmith.com/features/end-live-activity.png" alt="分段进度结束示例" width="680" />
</p>

```bash
activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "夜间数据库备份",
    "subtitle": "验证恢复",
    "numberOfSteps": 3,
    "currentStep": 3,
    "autoDismissMinutes": 2
  }'
```

### 进度类型（Progress）

当状态天然是连续变化时使用 `progress`，适合充电、下载、同步任务、上传、计时器，以及任何以百分比或数值范围作为最直观信号的流程。

#### 启动

<p align="center">
  <img src="https://cdn.activitysmith.com/features/progress-live-activity-start.png" alt="进度启动示例" width="680" />
</p>

```bash
activitysmith activity start \
  --content-state '{
    "title": "电动车充电",
    "subtitle": "已增加 30 英里续航",
    "type": "progress",
    "percentage": 15
  }'
```

#### 更新

<p align="center">
  <img src="https://cdn.activitysmith.com/features/progress-live-activity-update.png" alt="进度更新示例" width="680" />
</p>

```bash
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "电动车充电",
    "subtitle": "已增加 120 英里续航",
    "percentage": 60
  }'
```

#### 结束

<p align="center">
  <img src="https://cdn.activitysmith.com/features/progress-live-activity-end.png" alt="进度结束示例" width="680" />
</p>

```bash
activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "电动车充电",
    "subtitle": "已增加 200 英里续航",
    "percentage": 100,
    "autoDismissMinutes": 2
  }'
```

### 实时活动操作按钮

与可交互推送通知类似，实时活动也可以添加一个按钮，用于在浏览器中打开指定 URL 或触发 Webhook。Webhook 由 ActivitySmith 后端执行。

<p align="center">
  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png" alt="带操作按钮的指标实时活动" width="680" />
</p>

#### 打开 URL 操作

```bash
activitysmith activity start \
  --content-state '{
    "title": "服务器健康",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      { "label": "CPU", "value": 76, "unit": "%" },
      { "label": "MEM", "value": 52, "unit": "%" }
    ]
  }' \
  --action '{
    "title": "打开监控面板",
    "type": "open_url",
    "url": "https://ops.example.com/servers/prod-web-1"
  }'
```

#### Webhook 操作

<p align="center">
  <img src="https://cdn.activitysmith.com/features/live-activity-with-action.png?v=20260319-1" alt="带操作按钮的实时活动" width="680" />
</p>

```bash
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{
    "title": "重建商品搜索索引",
    "subtitle": "分片 7/12",
    "numberOfSteps": 12,
    "currentStep": 7
  }' \
  --action '{
    "title": "暂停重建",
    "type": "webhook",
    "url": "https://ops.example.com/hooks/search/reindex/pause",
    "method": "POST",
    "body": {
      "job_id": "reindex-2026-03-19",
      "requested_by": "activitysmith-cli"
    }
  }'
```

## 频道（Channels）

频道用于定向推送给特定团队成员或设备，可用于推送通知和实时活动。

```bash
activitysmith push \
  --title "构建失败 🚨" \
  --message "CI 流水线在 main 分支失败" \
  --channels "devs,ops"
```

## 别名

CLI 安装了两个可执行文件名：

- `activitysmith`（推荐）
- `activitysmith-cli`（别名）

## 内容状态选项

对于 `activity stream|start|update|end|end-stream`，可通过 JSON 传入内容状态：

- `--content-state <json>`
- `--content-state-file <path>`

对于 `metrics` 类型，还可以直接传入指标数组：

- `--metrics <json-array>`
- `--metrics-file <path>`

或使用标志位构建载荷的其余部分：

- `--title <标题>`
- `--subtitle <副标题>`
- `--type <类型>`
- `--number-of-steps <数字>`
- `--current-step <数字>`
- `--percentage <数字>`
- `--value <数字>`
- `--upper-limit <数字>`
- `--color <颜色>`
- `--step-color <颜色>`
- `--auto-dismiss-minutes <数字>`

实时活动操作选项：

- `--action <json>`
- `--action-file <path>`

定向推送选项：

- `--channels <逗号分隔的频道标识>` （用于 `push`、`activity stream` 和 `activity start`）

必填字段说明：

- `activity stream`：`--title`、`--type`，以及 `--metrics`、`--number-of-steps` 与 `--current-step`、`--percentage`，或 `--value` 与 `--upper-limit`
- `activity start`：`--title`、`--type`，以及 `--metrics`、`--number-of-steps` 与 `--current-step`、`--percentage`，或 `--value` 与 `--upper-limit`
- `activity update`：`--title`，以及 `--metrics`、`--current-step`、`--percentage`，或 `--value` 与 `--upper-limit`
- `activity end`：`--title`，以及 `--metrics`、`--current-step`、`--percentage`，或 `--value` 与 `--upper-limit`
- `activity end-stream`：不要求传入内容状态，但如果提供，规则与 `activity end` 相同

## 输出

使用 `--json` 获取机器可读的输出格式。

```bash
activitysmith push --title "Hello" --json
```