LX CLI接入指南

灵犀埋点采集与上报 CLI，支持用户自定义 PV/MV/MC 事件上报；在执行 skill start 后，上报的埋点会自动串联为同一次会话链路；并支持从 SKILL.md 自动解析 skill 元信息。

安装

使用美团内部 npm registry 安装（需内网环境）：

# npm
npm install -g @datafe/lx-cli --registry=http://r.npm.sankuai.com

安装后可直接使用如下指令获取使用方法：

lx docs

接入

1) SKILL 执行开始前，skill start（必须执行）

注：不执行 skill start 会导致后续埋点无法串联为同一次会话链路。

lx skill start --skill-path <skill_dir>/SKILL.md --custom custom1=<your_custom>

2) 业务方按需上报 pv/mv/mc 等埋点

注：如需使用 pv/mv/mc 自定义埋点，appnm/category/cid/bid 需先在 Ocean 注册；业务参数可通过 --val-lab 与 --custom 传入，具体层级需以 Ocean 中注册规则为准。skill start/end 仅支持 --custom，不支持 --val-lab。

# PV 埋点：示例补充业务参数
# 请替换为你在 Ocean 注册的参数
lx pv --skill-path <skill_dir>/SKILL.md --cid <your_cid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom>

# MV 埋点：示例补充业务参数
# 请替换为你在 Ocean 注册的参数
lx mv --skill-path <skill_dir>/SKILL.md --cid <your_cid> --bid <your_bid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom>

# MC 埋点：示例补充业务参数
# 请替换为你在 Ocean 注册的参数
lx mc --skill-path <skill_dir>/SKILL.md --cid <your_cid> --bid <your_bid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom>

3) SKILL 执行结束执行 skill end（建议执行）

注：执行 skill end 可补齐执行结果统计信息，不执行会丢失部分统计数据。

lx skill end --skill-path <skill_dir>/SKILL.md --custom lx_is_success=<true|false> --custom lx_total_step=<本skill总步骤数> --custom lx_executed_step=<已成功执行步骤数> --custom lx_failed_step_name="<失败步骤名，成功时为空>" --custom lx_summary="<300字内执行总结，总结的步骤数要与lx_total_step相同>" --custom custom1=<your_custom>

指令总览

| 指令 | 说明 | 示例 | |------|------|------| | skill start [options] | skill 开始执行时必须执行，用于初始化灵犀链路 | lx skill start --skill-path <skill_dir>/SKILL.md --custom custom1=<your_custom> | | skill end [options] | skill 执行结束时执行 | lx skill end --skill-path <skill_dir>/SKILL.md --custom lx_is_success=<true|false> --custom lx_total_step=<本skill总步骤数> --custom lx_executed_step=<已成功执行步骤数> --custom lx_failed_step_name="<失败步骤名，成功时为空>" --custom lx_summary="<300字内执行总结，总结的步骤数要与lx_total_step相同>" --custom custom1=<your_custom> | | pv [options] | 发送 PV 曝光上报 | lx pv --skill-path <skill_dir>/SKILL.md --cid <your_cid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom> | | mv [options] | 发送 MV 模块曝光上报 | lx mv --skill-path <skill_dir>/SKILL.md --cid <your_cid> --bid <your_bid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom> | | mc [options] | 发送 MC 模块点击上报 | lx mc --skill-path <skill_dir>/SKILL.md --cid <your_cid> --bid <your_bid> --appnm <your_appnm> --category <your_category> --val-lab val_lab1=<your_val_lab> --custom custom1=<your_custom> | | docs | 输出主指令与全部子指令帮助信息 | lx docs | | help [command] | 查看指定指令帮助 | lx help skill |

通用参数说明

多数子指令会复用以下参数：

| 参数 | 必填 | 说明 | |------|------|------| | --skill-path <skillPath> | 条件必填 | skill 文档路径（SKILL.md 所在目录）；与 --skill-id 二选一；传入后自动解析 skill_id、skill_name、skill_version | | --skill-id <skillId> | 条件必填 | skill 唯一标识；与 --skill-path 二选一；同时传入时，优先取 --skill-id | | --skill-name <skillName> | 否 | skill 名称；优先于 --skill-path 解析值；未传入 --skill-path 时建议传入 | | --skill-version <skillVersion> | 否 | skill 版本；优先于 --skill-path 解析值；未传入 --skill-path 时建议传入 | | --val-lab <key=value> | 否（可重复） | 可选；val_lab 字段（仅 pv/mv/mc 支持）；支持重复传入，相同 key 后者覆盖前者 | | --custom <key=value> | 否（可重复） | 可选；val_lab.custom 字段，支持重复传入，相同 key 后者覆盖前者 |

参数层级约定：

• skill start/end：业务参数仅支持 --custom（不支持 --val-lab）。
• pv/mv/mc：业务参数支持 --val-lab 与 --custom。
• 具体写入 val_lab 还是 val_lab.custom，以 Ocean 规则为准。
• --val-lab 与 --custom 均支持重复传入，相同 key 后者覆盖前者。

指令详情

skill start / skill end

skill start 与 skill end 共享同一组选项（业务参数仅支持 --custom）

| 选项 | 必填 | 说明 | |------|------|------| | --skill-path <skillPath> | 条件必填 | skill 文档路径（SKILL.md文档所在目录路径；与 --skill-id 任选其一；传入后自动解析 skill_id、skill_name、skill_version） | | --custom <key=value> | 否（可重复） | 可选；val_lab.custom 字段（skill start/end 的业务参数仅支持该项）；支持重复传入，相同 key 后者覆盖前者 | | --skill-id <skillId> | 条件必填 | skill_id（与 --skill-path 任选其一；同时传入时，优先取 --skill-id） | | --skill-name <skillName> | 否 | skill 名称（可选；优先于 --skill-path 解析值，未传入--skill-path 时建议传入） | | --skill-version <skillVersion> | 否 | skill 版本（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | -h, --help | 否 | 查看命令帮助 |

pv

发送 PV 曝光上报。

| 选项 | 必填 | 说明 | |------|------|------| | --skill-path <skillPath> | 条件必填 | skill 文档路径（SKILL.md文档所在目录路径；与 --skill-id 任选其一；传入后自动解析 skill_id、skill_name、skill_version） | | --val-lab <key=value> | 否（可重复） | 可选；val_lab 字段（仅 pv/mv/mc 支持）；支持重复传入，相同 key 后者覆盖前者 | | --custom <key=value> | 否（可重复） | 可选；val_lab.custom 字段，与 val_lab 同为业务参数，具体传入层级以ocean中的规则为准；支持重复传入，相同 key 后者覆盖前者 | | --skill-id <skillId> | 条件必填 | skill_id（与 --skill-path 任选其一；同时传入时，优先取 --skill-id） | | --skill-name <skillName> | 否 | skill 名称（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --skill-version <skillVersion> | 否 | skill 版本（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --cid <cid> | 是 | Ocean 注册页面标识（必传） | | --appnm <appnm> | 是 | Ocean 注册应用名称（必传） | | --category <category> | 是 | Ocean 注册上报通道（必传） | | -h, --help | 否 | 查看指令帮助 |

mv

发送 MV 模块曝光上报。

| 选项 | 必填 | 说明 | |------|------|------| | --skill-path <skillPath> | 条件必填 | skill 文档路径（SKILL.md文档所在目录路径；与 --skill-id 任选其一；传入后自动解析 skill_id、skill_name、skill_version） | | --val-lab <key=value> | 否（可重复） | 可选；val_lab 字段（仅 pv/mv/mc 支持）；支持重复传入，相同 key 后者覆盖前者 | | --custom <key=value> | 否（可重复） | 可选；val_lab.custom 字段，与 val_lab 同为业务参数，具体传入层级以ocean中的规则为准；支持重复传入，相同 key 后者覆盖前者 | | --skill-id <skillId> | 条件必填 | skill_id（与 --skill-path 任选其一；同时传入时，优先取 --skill-id） | | --skill-name <skillName> | 否 | skill 名称（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --skill-version <skillVersion> | 否 | skill 版本（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --cid <cid> | 是 | Ocean 注册页面标识（必传） | | --appnm <appnm> | 是 | Ocean 注册应用名称（必传） | | --category <category> | 是 | Ocean 注册上报通道（必传） | | --bid <bid> | 是 | Ocean 注册模块标识（必传） | | -h, --help | 否 | 查看指令帮助 |

mc

发送 MC 模块点击上报。

| 选项 | 必填 | 说明 | |------|------|------| | --skill-path <skillPath> | 条件必填 | skill 文档路径（SKILL.md文档所在目录路径；与 --skill-id 任选其一；传入后自动解析 skill_id、skill_name、skill_version） | | --val-lab <key=value> | 否（可重复） | 可选；val_lab 字段（仅 pv/mv/mc 支持）；支持重复传入，相同 key 后者覆盖前者 | | --custom <key=value> | 否（可重复） | 可选；val_lab.custom 字段，与 val_lab 同为业务参数，具体传入层级以ocean中的规则为准；支持重复传入，相同 key 后者覆盖前者 | | --skill-id <skillId> | 条件必填 | skill_id（与 --skill-path 任选其一；同时传入时，优先取 --skill-id） | | --skill-name <skillName> | 否 | skill 名称（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --skill-version <skillVersion> | 否 | skill 版本（可选；优先于 --skill-path 解析值，未传入 --skill-path 时建议传入） | | --cid <cid> | 是 | Ocean 注册页面标识（必传） | | --appnm <appnm> | 是 | Ocean 注册应用名称（必传） | | --category <category> | 是 | Ocean 注册上报通道（必传） | | --bid <bid> | 是 | Ocean 注册模块标识（必传） | | -h, --help | 否 | 查看指令帮助 |

docs

docs 会输出完整帮助信息（即本文档内容）。

| 选项 | 必填 | 说明 | |------|------|------| | -h, --help | 否 | 查看指令帮助 |

全局选项

| 选项 | 说明 | |------|------| | -V, --version | 输出版本号 | | --no-auto-upgrade | 禁用自动升级（默认不禁用） | | -h, --help | 查看帮助 |

自动升级机制

lx-cli 默认启用自动升级检查：

1. 执行除 --version、--help 外的指令时触发检查。
2. 版本信息缓存 30 分钟，避免频繁请求 registry。
3. 发现新版本后自动执行全局升级（npm install -g @datafe/lx-cli）。
4. 升级成功后自动使用新版本重试原指令。
5. 升级失败不阻塞当前指令，仍使用本地版本继续执行。

临时禁用自动升级示例：

lx --no-auto-upgrade docs