mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/activitysmithhq--activitysmith-cli.md

15 KiB
Raw Permalink Blame History

iOS推送与动态岛CLI工具

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

ActivitySmith CLI

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

安装

npm install -g activitysmith-cli

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

从本仓库安装公开技能：

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

技能在本仓库中的路径：

skills/activitysmith

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

鉴权

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

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

推送通知

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

发送推送通知

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

带媒体的富文本推送通知

带图片的富文本推送通知 

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

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

带音频的富文本推送通知

支持以下格式：

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

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

可交互推送通知

可交互推送通知示例

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

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"
      }
    }
  ]'

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

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

实时活动（Live Activities）

指标类实时活动截图

实时活动共有三种类型：

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

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

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

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

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

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

指标（Metrics）

指标流示例 

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）

分段进度流示例 

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

进度（Progress）

进度流示例 

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

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

结束流

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

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，例如服务器健康状况、队列压力或数据库负载。

启动

指标启动示例 

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

更新

指标更新示例 

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": "%" }
    ]
  }'

结束

指标结束示例 

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 是动态的，可在工作流变化时随时增减。

启动

分段进度启动示例 

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

更新

分段进度更新示例 

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

结束

分段进度结束示例 

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

进度类型（Progress）

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

启动

进度启动示例 

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

更新

进度更新示例 

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

结束

进度结束示例 

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

实时活动操作按钮

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

带操作按钮的指标实时活动

打开 URL 操作

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 操作

带操作按钮的实时活动 

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）

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

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 获取机器可读的输出格式。

activitysmith push --title "Hello" --json