CLI 使用手册
阅读导航
所属目录：能力中心。检索关键词：CLI、ae-cli、命令行、Coding Agent、Skill、安装、登录、授权、Capability Gateway。
- 在 Codex、Claude Code 等 Coding Agent 里接入：Coding Agent。
- 快速了解 CLI 能做什么：CLI 快速入门。
- 用工具协议连接外部服务：MCP。
- 沉淀可复用的任务方法：Skill。
- 设置周期执行的任务：自动化。
Agentic Engine CLI（命令名 ae-cli）是 Agentic Engine 的命令行客户端，为 AI Agent 和人工操作提供稳定、结构化的接口。安装并授权后，Codex、Claude Code、WorkBuddy 等本地 AI Agent 可以在你的账号权限内直接查数据、搭看板、管埋点、跟进运营和数据开发任务，你只需要用自然语言说清想做什么。
工作方式
你用自然语言提问 → 本地 AI Agent（Claude Code、Codex、WorkBuddy 等）→ ae-cli → 你的 Agentic Engine 项目 → 可核对的结果
安装 CLI 时会一并装上配套的 Agent Skills。Skills 告诉 AI Agent 有哪些命令、什么场景用哪条命令、写操作前要做哪些确认，所以你不需要记命令。
- 权限边界：CLI 完全沿用你的账号和项目权限，不会多拿一份数据；最终权限由服务端校验。
- 凭证：按 Agentic Engine 地址分开加密保存在本机，切换环境不会复用其他环境的凭证。
- 写操作：建看板、建人群、推送这类会改变现状的操作，先让 AI 给出方案，你确认后再执行。
CLI 与 MCP 的分工：要让 Agent 使用 Agentic Engine 的内置业务能力（分析、运营、埋点、数据开发、知识库等），优先使用 CLI；MCP 用来让 Agent 连接外部工具和业务服务，见 MCP。
开始前准备
- Agentic Engine 已升级到 6.x 版本。
- 账号有目标项目的访问权限。
- 已拿到 Agentic Engine 地址：即你平时打开 Agentic Engine 网页的地址，由管理员提供。
- 本机安装了 Node.js 20 或更高版本，能访问 npm 仓库；首次安装 Skills 时还需要能访问 GitHub。
- 本机网络能访问 Agentic Engine 地址。
安装与登录
方式一：让 AI Agent 帮你安装（推荐）
把下面这段话发给能操作终端的 AI Agent（例如 Codex、Claude Code、WorkBuddy），并把其中的地址换成你的 Agentic Engine 地址：
请阅读 https://raw.githubusercontent.com/ThinkingAIAgenticEngine/ae-cli/main/cli-installation-guide.md 并按说明帮我安装或升级 Agentic Engine CLI（ae-cli）。我的 Agentic Engine 地址是 https://your-ae-host.example.com。只安装 ae-cli 和配套 Skills，不要修改当前项目；遇到登录授权或需要管理员权限时请暂停并提示我。
AI Agent 会依次完成这些步骤：
- 检查 Node.js 和 npm 版本；版本不够时，用 nvm、fnm 或 Volta 这类版本管理工具在用户目录下安装，不会使用
sudo npm install -g。 - 安装 ae-cli 和配套 Skills。
- 发起登录并把授权链接发给你；你在浏览器里完成授权后，它继续完成登录。
- 运行
ae-cli update，安装当前环境要求的 CLI 和 Skills 版本。 - 汇报 Node.js 版本、CLI 版本、Agentic Engine 地址、登录状态和 Skills 同步结果。
安装完成后，关闭并重新打开 AI Agent，或新开一个任务，让它加载新装的 Skills。
方式二：手动安装
先确认 Node.js 版本不低于 20：
node --version
版本过低时，安装 Skills 可能报 EBADENGINE 或 styleText 相关错误，请先升级或切换 Node.js。然后安装 CLI 和配套 Skills，并确认版本：
npm install -g @thinkingai/ae-cli
npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
ae-cli --version
如果本机已有其他工具占用了 ae-cli 这个命令名，先确认再替换。
登录授权
ae-cli auth login --host https://your-ae-host.example.com
ae-cli auth status --host https://your-ae-host.example.com
登录使用设备码流程：浏览器会打开授权页面，核对页面上的验证码与终端显示的一致后，点击「确认授权」。回到终端查看登录状态，authenticated 为 true 即登录成功。
- 当前环境打不开浏览器时，在登录命令后加
--no-browser。 - 由 AI Agent 代为登录时，可以分两步：先加
--no-wait运行登录命令，拿到授权链接；你完成授权后，再用返回的设备码加--device-code运行一次。设备码过期就重新执行第一步。 - 也可以在 Agentic Engine 的「外部访问管理」里复制 CLI Token，再用
ae-cli auth set-token --host <地址>导入。输入时不回显，命令输出里也不会包含 Token。
同步到环境要求的版本
每个 Agentic Engine 环境都要求一个确定的 CLI 版本。安装或升级后运行：
ae-cli update --host https://your-ae-host.example.com
ae-cli --version
ae-cli update 按当前环境的要求安装对应版本的 CLI 和 Skills，不依赖 npm 的最新版，所以升级时不要直接用 npm 装到 latest。想先看会装哪个版本，加 --dry-run。
从 6.0.37 和 6.1.9 维护线开始，普通命令发现版本不一致时会自动同步；同步成功后返回 AE_CLI_VERSION_SYNCED，重新执行原命令即可。
安装精选场景 Skill
ThinkingAI 把多年服务经验沉淀成了场景 Skill，覆盖 LTV 分析、异常诊断等高频场景。可以直接让 AI 安装：
帮我安装 https://github.com/ThinkingAIAgenticEngine/scenario-skills
也可以在终端里按业务分类交互安装：
npx skills@latest add ThinkingAIAgenticEngine/scenario-skills
验证是否就绪
向 AI 提一个明确、低风险的问题：
请查询我当前可访问的项目列表，只返回项目名称和项目 ID。现在只查看，不要修改任何内容。
AI 能识别 Agentic Engine 的能力、提示你完成授权或返回项目列表，说明链路已经打通。如果它把问题当成普通聊天，先检查 CLI 与 Skills 是否已安装，以及当前 AI Agent 是否重新加载了 Skills。
5 分钟跑通第一次查询
不需要学命令。把这句话发给 AI：
帮我查最近 7 天每日活跃用户，按天列趋势。先告诉我用了哪个事件、时间范围和去重规则。
看到结果后，只核对三件事：
- 事件选对了吗？
- 时间范围对吗？
- 统计的是人数还是次数？
常用场景
下面的提示词都可以直接复制：把括号里的占位内容换成你项目里的真实对象，再发给 AI。标「只读」的只查询、不修改；标「确认后执行」的，AI 会先给方案，你确认后才会创建或修改。
查核心指标（只读）
适合先对某段时间的核心玩法有个整体概览，再决定往哪里深挖。
帮我看一下最近 7 天，（核心行为）的整体表现：每天有多少人触发、总共多少次，按天列出趋势。
确认：哪个项目；AI 选了哪个事件，选错了直接纠正，它会重跑。下一句可以问：「按渠道拆一下昨天的触发人数。」
结果不对时：把大问题拆小，先问「最近 7 天每天多少人登录」，确认事件可用后再加指标。
用漏斗定位流失（只读）
帮我看一下最近 7 天，从（起点事件）到（终点事件）的转化漏斗：
（步骤1）→（步骤2）→（步骤3）→（步骤4），
按 1 天转化窗口统计每步人数和转化率，告诉我哪个环节流失最大。
确认：漏斗每一步对应的事件（AI 会列出来等你确认）；转化窗口（常规 1 天，活动类可以放宽到 3 天）。某一步人数为 0 时，先怀疑事件选错或时间范围内没有数据。
常用分析模型速查（只读）
| 分析类型 | 回答什么问题 | 可复制的提示词 |
|---|---|---|
| 事件分析 | 某个行为发生多少次、趋势如何 | 查最近 7 天（事件）每天的触发人数和次数，按天列趋势。 |
| 漏斗分析 | 哪一步流失最多 | 用（步骤A→步骤B→步骤C）建漏斗，1 天窗口，找出流失最大的环节。 |
| 留存分析 | 用户是否持续回来 | 统计最近 7 天（注册）用户的次日留存率，回访事件用（登录）。 |
| 分布分析 | 用户或数值集中在哪里 | 统计最近 7 天（充值金额）的用户分布，按区间展示。 |
保存为看板（确认后执行）
把刚才的（漏斗分析）和（事件分析）搭建成一个看板。
先列出看板名称、包含哪些报表、每个报表的口径，我确认后再创建。
创建成功后，AI 会返回看板链接，打开就是 Agentic Engine 里的真实看板。账号需要有创建报表和看板的权限。
多轮追问找原因（只读）
真实的分析通常要多轮追问：每轮只换一个维度，上一轮的「待验证」就是下一轮的提问。以「收入增长停滞」为例：
- 看大盘：「查最近 14 天每天的付费人数和登录人数，按天列趋势，告诉我付费率大概什么水平。」
- 按渠道拆：「按来源渠道拆最近 7 天的付费人数和付费金额，列出每个渠道的人均付费。」
- 按新老拆：「用『是否首次付费』把最近 7 天的付费拆开，看首购和复购各占多少人数、多少金额。」
- 按金额分层：「把最近 7 天的付费用户按累计付费金额分层（0–30、30–98、98–328、328–648、648 以上），看每层人数占比，再列出付费金额最高的礼包。」
分析做完后，让 AI 把事实、判断和建议动作分开写成报告：
把刚才的分析整理成报告，结构固定为：
结论摘要、数据口径、关键事实、原因判断、待验证项、建议动作。
事实和判断必须分开写，推测的内容标为待验证，不要写成结论。
盘点与治理数据资产
数据资产的语义质量决定 AI 取数的上限：事件命名混乱、属性没有注释、口径不统一时，AI 只能猜。建议先盘点，再分析。
| 场景 | 可复制的提示词 | 读写 |
|---|---|---|
| 资产盘点 | 请盘点我当前项目的埋点资产：统计事件和属性的总数；找出缺少显示名或注释的事件和属性；找出命名不规范的事件；找出最近 90 天没有数据上报的事件。先输出检查范围、判定规则和分类清单，不要修改任何资产。 | 只读 |
| 语义补全 | 基于刚才的盘点结果，为缺少显示名或注释的事件和属性生成补全建议，输出原字段名、建议显示名、建议注释和修改原因。只给建议表，我审核后再执行。 | 确认后执行 |
| 数据质量自检 | 请检查最近 7 天的数据质量：核心事件的上报量有没有突然掉零或暴涨；关键属性的空值率和异常枚举值；已断连或长期无数据的资产。输出现象、可能原因和需要人工确认的证据，不要修改任何资产。 | 只读 |
「无数据」不等于「没用」：周期性活动的事件平时不上报是正常的，清理前先和业务确认。
设计埋点方案、生成埋点代码
把业务流程讲清楚，AI 才能给出能落地的方案。不要只说一句「帮我设计埋点」，而是给出完整的用户路径和最关心的指标：
帮我给任务模块生成埋点方案。
业务目标：了解玩家在任务环节的完成情况和流失分布，找出卡点任务，以及奖励对留存的影响。
玩家行为路径：点开任务列表 → 接受任务 → 做任务 → 完成 → 领奖励 → 离开。
判定口径：完成 = 达成任务目标，不等于领了奖励。
需要的维度：任务类型、完成耗时、奖励类型、完成后的下一步动作；玩家等级、账号类型。
AI 会输出可评审的方案初稿，包括事件名、显示名、触发时机、属性、属性类型、示例值和验收方式，并优先复用项目里已有的公共属性。方案评审通过后，可以继续生成代码：
基于埋点方案帮我生成（Android / iOS / Web / 服务端）的埋点代码。
首次生成建议输出为代码片段文件，人工检查后再合并；涉及具体 API 参数时，以对应平台的 SDK 文档为准。
从分析到运营闭环
需要开通运营模块。推送渠道要先在 Agentic Engine 中配置并启用，人群条件引用的事件和属性必须已经存在。
| 步骤 | 可复制的提示词 | 读写 |
|---|---|---|
| 运营建议 | 基于刚才的分析结论，帮我生成运营建议，按「目标人群、触发条件、建议动作、预期观察指标、风险与排除条件」输出。先给方案，不要创建任何人群或触达任务。 | 只读 |
| 流程画布 | 把（目标人群）的关怀做成一条流程画布。先列出草案：人群定义、触发条件、等待条件、触达渠道、频控规则、退出条件，我确认后再创建。 | 确认后执行 |
| 效果分析 | 帮我看一下（画布名称）最近 7 天的执行效果：进入人数、触达人数、转化人数、各节点的退出原因，每个指标说明口径。 | 只读 |
| 效果看板 | 把这条画布的执行效果搭建成看板，包含目标指标、过程指标、分层维度和时间筛选。先给配置草案，我确认后再创建。 | 确认后执行 |
跨系统联动与定时任务
跨系统联动需要先在 AI Agent 里装好对应外部工具的 CLI 或 MCP（例如飞书用 lark-cli），否则下面的提示词会直接失败。发消息、建文档这类对外操作，一律先看草稿再确认。
| 场景 | 可复制的提示词 |
|---|---|
| 多源数据整合 | 把 Agentic Engine 里的付费数据和（飞书表格）里的活动数据，整合成一份按天对齐的报表。先列出两边的数据粒度、日期字段、指标口径和缺失值处理规则，我确认后再合并，不要修改外部文件。 |
| 日报发到工作群 | 查一下今天的活跃数据，整理成日报发到我们的工作群。日报包含核心指标、环比变化、异常项和原始分析链接。先生成草稿给我看，我确认后再发。 |
| 周报生成在线文档 | 把本周数据整理成周报，生成飞书文档，结构为指标总览、按日走势、变化解读、运营动作回顾、下周待办。先生成草稿，我确认后再创建。 |
| 定时监控 | 帮我建一个自动化任务：版本发布后每 30 分钟查一次（项目）的核心指标（指标1、指标2），整理成监控卡发到（飞书群）；某项指标较前 7 日均值下跌超过 10% 时在消息里标红提醒。先列出执行计划、查询口径和推送样式，我确认后再开启。 |
定时任务先手动跑一次，确认格式和口径无误后再开启；监控类频率从 30 分钟起步，日报一天一次就够。在 Agentic Engine 里设置周期任务，见 自动化。
创建与复用分析资产（确认后执行）
| 资产 | 适用问题 | 创建前要确认 |
|---|---|---|
| 虚拟属性 | 用多个原始字段组合出分析维度 | 公式、空值处理、影响范围 |
| 用户标签 | 固化稳定的用户分类规则 | 计算周期、数据来源、更新频率 |
| 用户分群 | 圈选可分析或可运营的人群 | 进入条件、排除条件、有效期 |
| 报表与看板 | 固定高频指标的查看方式 | 指标口径、筛选条件、访问权限 |
| 跨项目复用 | 把通用的分析结构迁移到其他项目 | 事件映射、属性映射、口径差异 |
请为（目标）设计一个（虚拟属性 / 标签 / 分群 / 看板）草案。
先列出依赖的事件与属性、计算或筛选逻辑、更新方式、权限和迁移风险。
不要直接创建，等我确认。
项目多时，批量操作最省时间，例如「按版本监控看板的结构，给项目 A、B、C 各建一份，建好后列出差异项」。
数据开发平台
需要开通数据开发平台。
| 场景 | 可复制的提示词 |
|---|---|
| 库表与任务流查询 | 列出当前环境可访问的库、表与任务流，按最近更新时间和状态汇总。 |
| 取数与调试 | 基于（业务问题）生成查询思路和 SQL 草案，先说明数据表、关联条件、时间范围和校验方式，不执行写操作。 |
| 任务流搭建 | 为（业务域）设计一条任务流：列出节点编排、调度周期和发布计划，不要直接创建。 |
| 宽表加工 | 把（事件表）加工成（宽表），先给字段清单、聚合粒度、分区策略和增量更新逻辑，我确认后再建表建流。 |
| 运行排障 | 汇总近（N）天失败的实例，按任务流和失败原因分类，并给出修复建议。 |
更多场景
- 本地数据接入：「把这份（本地文件路径）的数据接入 Agentic Engine。先识别文件结构，列出字段映射和类型，我确认后再执行导入。」
- 社区洞察（需要开通全域洞察）：「整理最近一周社区里关于（新版本）的讨论，总结热门话题、正负面反馈和需要优先关注的风险。」
- 知识库：「在（知识库名称）里查找关于（主题）的页面，读取原文后回答（问题），并附上来源页面。」
- 平台管理（需要管理员权限）：「列出系统里已配置的渠道和最近 30 天的用量汇总。只读，不要修改。」
CLI 的能力无法一一列举。直接把需求告诉 AI，它会判断能否执行、还缺哪些配置。
核对结果
拿到任何数字，先问四个问题：用了哪个事件？什么指标口径？什么时间范围？什么筛选条件？ 口径不对就当场纠正，让 AI 重跑。取数和看板对不上时，让 AI 把查询条件逐条列出来，和看板里报表的配置逐条比对。
| 层级 | 含义 | 示例 |
|---|---|---|
| 事实 | 数据能直接复现 | 「最近 7 天付费转化率 30.46%。」 |
| 判断 | 对事实的解释 | 「流失集中在商城到发起充值的环节，可能与定价曝光有关。」 |
| 待验证 | 当前数据不足以确认 | 「需要结合商城曝光埋点验证。」 |
AI 停下来问你「这个词指哪一个」不是出错：一个词同时命中多个指标或事件时，它会把口径的选择权留给你。同一个歧义反复出现，就把默认口径沉淀进 Skill 或 知识库。
命令速查
日常使用不需要记命令，AI Agent 会通过 Skills 找到合适的命令。排查问题或写脚本时，可以这样查看帮助，层级命令可以继续追加 --help：
ae-cli --help
ae-cli analysis --help
ae-cli project member --help
| 类别 | 根命令 | 用途 |
|---|---|---|
| 分析与项目 | analysis、analysis-meta、analysis-governance、project、metadata、personal-semantic-preference、project-semantic | 报告、看板、即席分析、告警、标签和分群；事件与属性目录、指标和埋点治理；数据资产搜索与血缘；项目、成员、角色与权限；数据表与维度表绑定；个人语义偏好；导出项目资产包 |
| 数据与埋点 | tracking、data-integration | 埋点方案、SDK 示例、采集诊断和代码生成；本地 CSV、JSON、Excel 数据的检查、转换和上传 |
| 社区洞察 | community | 社区帖子、评论、话题、情感、直播和报告 |
| 运营触达 | engage-flow、engage-task、engage-setting、engage-scene、engage-activity、engage-workbench、engage-query | 运营流程、任务与触达内容、渠道与受众设置、场景与策略、活动与专题、工作台与待办、运营查询与异步导出 |
| 数据开发平台 | dataops_repo、dataops_datatable、dataops_flow、dataops_ide、dataops_integration、dataops_operations | 数仓与数据源、表和视图、开发流程与调度、IDE 查询、数据集成、运维与告警 |
| Agent 平台 | kb、agent、context、memory、team、system | 知识库与问答；Agent、自动化、模型、MCP、Skills 与附件；当前页面上下文；用户记忆；Agent Team；成员、沙箱、用量、配额和渠道等系统管理 |
| 通用工具 | capability、auth、config、sync、model、update | 能力发现与通用调用；登录与账号；环境管理；同步 Skills 和 MCP；切换沙箱模型；同步到环境要求的版本 |
Capability Gateway
没有专门命令的长尾能力，通过 Capability Gateway 动态发现和调用：
ae-cli capability list --domain analysis
ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
--input 支持内联 JSON、JSON 文件路径或在文件路径前加 @，也可以用 - 从标准输入读取。dry-run 已经包含参数校验，并会显示风险等级，确认无误后再 run。
输出格式
命令默认输出统一的 JSON 结构（ok、data、_notice），便于 AI Agent 读取：
--format table：支持的列表命令以表格显示，便于人工查看。--jq <表达式>：先筛选业务结果，再输出。--dry-run：只预览，不执行。--yes：跳过高风险写操作的交互确认，只在确认过影响范围后使用。
多环境与多账号
凭证按 Agentic Engine 地址分开保存。同时使用测试和正式环境时，用 config 管理：
ae-cli config list
ae-cli config add https://host-b.example.com --label staging --use
ae-cli config use staging
ae-cli config current
同一环境需要多个账号时，登录命令加 --add，再用 ae-cli auth list 查看、ae-cli auth use --account <账号> 切换；ae-cli auth logout 退出当前账号。在终端直接运行 ae-cli config 或 ae-cli auth，会打开交互式选择器。
安全与权限
- CLI 不会获得超出账号范围的权限；公司隔离、资源归属和最终权限都由服务端校验。
- 写操作先 dry-run，或先让 AI 给出方案、影响范围和回退方式，确认后再执行；删除等高风险操作还会要求再次确认。
- 不要在对话里粘贴密码、Token 或其他凭证；CLI 的输出也不会包含 Token。
system下的管理命令要求账号拥有 root 或 agent_admin 角色。遇到权限错误不要重试或绕过，请联系管理员确认。- 安装时只装 Node.js、
@thinkingai/ae-cli和官方 Skills；不要关闭 TLS 校验，也不要使用不可信的镜像源。
常见问题
安装与授权问题自查
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
| 无法安装或下载超时 | 网络、npm 源或代理限制 | 检查网络与代理，使用团队认可的依赖源，保留完整错误信息 |
| 授权后仍未登录 | 浏览器授权未完成或设备码已过期 | 重新运行登录命令完成授权，再查看登录状态 |
| 找不到目标项目 | 账号没有权限，或连错了环境 | 核对 Agentic Engine 地址、账号和项目 ID |
| AI 不认识 Agentic Engine 的能力 | Skills 没有安装，或当前 AI Agent 没有重新加载 | 重新安装 Skills，然后重启 AI Agent |
| 提示命令不存在或版本不一致 | CLI 或 Skills 与环境要求的版本不同 | 运行 ae-cli update --host <地址>，再重启 AI Agent |
| 私有化环境连不上 | 地址、端口、证书或内网配置不一致 | 向部署方核对连接参数，再检查代理与证书 |
AI 的结论可以直接当作事实吗？
不能。先看它用的指标口径、时间范围和筛选条件。数据结果是事实，原因解释是判断，需要进一步验证；重要的经营判断仍应由负责人复核。
为什么同一个问题有时回答不一样？
问题可能缺少时间范围、口径或维度，项目里的语义信息也可能不完整。口径固定的高频任务写成 Skill，探索性的问题让 AI 多追问。
为什么别人能用的能力，我这里找不到？
依次检查 CLI 版本、AI 已加载的 Skills 版本、当前环境是否部署了该能力、账号是否有权限。可以先运行 ae-cli capability list 看当前环境开放了哪些能力。
遇到问题时应该提供什么？
告诉客户成功经理：Agentic Engine 地址、ae-cli --version 的输出、目标项目、复现步骤和完整的错误信息。不要发送密码、Token 或其他凭证。
相关链接
- ae-cli 源码与 Skills：github.com/ThinkingAIAgenticEngine/ae-cli
- 安装与升级说明（给 AI Agent 读）：cli-installation-guide.md
- 精选场景 Skills：github.com/ThinkingAIAgenticEngine/scenario-skills