@thinkingai/ae-cli 6.1.8 → 6.1.10

package/README.zh.md

@@ -1,224 +1,292 @@
-
 [中文版](./README.zh.md) | [English](./README.md)
 
 # ae-cli
 
-ThinkingAI AgenticEngine (AE) 平台的 CLI 工具。专为 AI Agent 和人类用户设计。
+`ae-cli` 是 ThinkingAI AgenticEngine（AE）平台的命令行客户端，为 AI Agent 和人工操作提供稳定、结构化的接口，覆盖分析、实验、元数据、埋点、运营、DataOps、知识库、Agent 资源及系统管理。
+
+CLI 的核心设计包括：
+
+- JSON 优先的输出，便于 Agent 读取和执行后续操作。
+- 按 Host 隔离的认证与多环境配置。
+- 常用工作流使用精选命令，长尾操作通过 Capability Gateway 动态发现。
+- 明确的参数校验、dry-run 和高风险确认契约。
+- CLI 与 Skills 按当前 AE 环境要求的精确版本同步。
+
+## 环境要求
+
+- Node.js 20 或更高版本。
+- 安装 CLI 时能够访问 npm 仓库。
+- 首次安装 Skills，或本地 Skills 来源不可用时，能够访问 GitHub。
 
 ## 安装
 
-**第一步：安装 ae-cli**
+安装公开版 CLI 和 Agent Skills：
 
 ```bash
 npm install -g @thinkingai/ae-cli
+npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+```
+
+Skills 会帮助 Claude Code、Codex、Cursor 等编码 Agent 理解、发现并调用 `ae-cli`。
+
+登录 AE 环境：
+
+```bash
+ae-cli auth login --host https://your-ae-host.example.com
+ae-cli auth status
 ```
 
-**第二步：安装 AI Agent Skills**
+## 环境版本同步
+
+每个 AE 环境都会返回其要求的精确 `aeCliVersion`。使用统一更新命令安装对应版本的 CLI 和 Skills：
 
 ```bash
-npx skills add ThinkingAIAgenticEngine/ae-cli -g -y
+ae-cli update
+ae-cli update --dry-run
 ```
 
-这将安装 4 个技能包到您的 AI 编程助手（Claude Code、Trae、Cursor 等）中，使助手能够理解并调用 ae-cli 命令。
+`ae-cli update` 安装当前 Host 要求的精确版本，不依赖 npm `latest`。更新时优先从已安装的 npm 包同步 Skills，本地来源失败后才回退到对应的 GitHub tag。
+
+从 `6.0.37` 和 `6.1.9` 维护线开始，普通业务命令可以自动升级或降级到环境要求的版本。同步成功后，旧进程会返回 `AE_CLI_VERSION_SYNCED`；重新执行原命令，即可使用新的 CLI 和 Skills。安装失败会给出提示，但不会用安装输出污染业务命令的 JSON 结果。
 
-更新方式：
+常用控制方式：
 
 ```bash
-npm cache clean --force && npm install -g @thinkingai/ae-cli
-npx skills add ThinkingAIAgenticEngine/ae-cli -g -y
+# 更新到另一个已配置 Host 要求的版本
+ae-cli update --host https://another-host.example.com
+
+# 安装指定版本
+ae-cli update --target 6.1.9
+
+# 单次命令跳过兼容性检查
+ae-cli --no-update-check capability list --domain analysis
 ```
 
 ## 快速开始
 
 ```bash
-ae-cli auth login --host xxxxx
+# 查看和切换环境
+ae-cli config list
+ae-cli config current
+ae-cli config use https://your-ae-host.example.com
+
+# 发现当前 Host 暴露的能力
+ae-cli capability list --domain analysis
+ae-cli capability search "dashboard list" --domain analysis
+ae-cli capability inspect analysis.dashboard.list
+
+# 校验、预览和执行
+ae-cli capability validate analysis.dashboard.list --input '{"project_id":1}'
+ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
+ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
+
+# 筛选结构化输出
+ae-cli capability list --domain analysis --jq '.data.capabilities[] | .id'
+```
+
+## 命令范围
+
+运行 `ae-cli --help` 或 `ae-cli <command> --help` 获取权威命令清单。
+
+| 命令或业务域 | 用途 |
+|---|---|
+| `analysis` | 报告、看板、即席分析、下钻、详情、告警和分析模型 |
+| `experiment` | Atlas 实验、报表、流量层、分桶、Feature、指标和操作日志 |
+| `analysis-meta` | 事件/属性元数据、指标、虚拟元数据、埋点治理和项目配置 |
+| `analysis-governance` | 资产搜索、血缘、影响分析和治理操作 |
+| `metadata` | 基于 Capability Gateway 的数据表和属性操作 |
+| `tracking` | 埋点方案生命周期、SDK 示例、检查、采集诊断、代码生成和内置 Wiki |
+| `engage-flow`、`engage-task`、`engage-setting`、`engage-scene`、`engage-activity`、`engage-workbench` | 运营流程、任务、设置、策略、活动和工作台 |
+| `community` | 社区帖子、评论、话题、情感、直播和报告工作流 |
+| `dataops_repo`、`dataops_datatable`、`dataops_flow`、`dataops_ide`、`dataops_integration`、`dataops_operations` | 数仓、数据表、任务流、IDE、数据集成和运维工作流 |
+| `kb` | 知识库生命周期、LLM 查询及确定性的 index/grep/read 检索 |
+| `agent` | Agent、自动化、模型、MCP、Skills、附件、凭证和沙盒工具 |
+| `system` | root/admin 的成员、沙盒、共享工具、模型、用量、配额和 IM 渠道管理 |
+| `team` | Agent Team 生命周期，以及 TeamRun 执行、对话、结果和产物 |
+| `capability` | 能力发现、Schema 查看、参数校验、dry-run 和通用执行 |
+| `auth`、`config` | 按 Host 隔离的认证和多环境配置 |
+| `api` | 用于诊断或过渡场景的原始认证 HTTP 请求 |
+| `sync` | 在本地工作区与 Agent 应用之间推送或拉取 Skills 和 MCP |
+| `model` | 在 Agent 沙盒中切换当前工作区模型 |
+| `update` | 将 CLI 和 Skills 同步到当前 Host 要求的版本 |
+
+`analysis_meta` 仍用于兼容旧的精选元数据命令。新接入优先使用带连字符的 Capability Gateway 业务域。
+
+## Capability Gateway
+
+不需要独立精选命令的能力，应优先通过 Capability Gateway 调用：
+
+```bash
+ae-cli capability list --domain analysis --project-id 1
+ae-cli capability search "report list" --domain analysis
+ae-cli capability inspect analysis.report.list
+ae-cli capability validate analysis.report.list --input input.json
+ae-cli capability dry-run analysis.report.list --input input.json
+ae-cli capability run analysis.report.list --input input.json
 ```
 
-## 使用方法
+`--input` 支持内联 JSON、JSON 文件路径、`@<path>`，或通过 `-` 从 stdin 读取。
+
+复杂嵌套参数尚在调整时使用 `validate`；需要确认最终风险等级、输出模式、取消能力或删除门禁时使用 `dry-run`。默认不要对同一份最终入参连续执行 `validate` 和 `dry-run`，因为 `dry-run` 已包含参数校验。
+
+Gateway 命令遵循 [Capability 命令收录规则](docs/capability-command-admission.md)。常见工作流可以提供精选命令，长尾能力则保持动态发现。
+
+## 认证与多环境
+
+凭证按 Host 独立存储，切换环境不会复用其他 Host 的 token。
 
 ```bash
-# AE 元数据域（元数据和治理）
-ae-cli analysis_meta +list_events --project_id 1
+ae-cli auth login --host https://host-a.example.com
+ae-cli auth status --host https://host-a.example.com
+ae-cli auth logout --host https://host-a.example.com
+
+ae-cli config list
+ae-cli config current
+ae-cli config set-host https://host-b.example.com --label staging
+ae-cli config use staging
+```
+
+登录使用跨平台设备码流程。当前环境无法打开浏览器时，可使用 `--no-browser`。
 
-# 表格输出
-ae-cli analysis_meta +list_events --project_id 1 --format table
+## 输出与安全
 
-# 原始 API 调用
-ae-cli api GET /v1/ta/event/catalog/listEvent --params '{"projectId": 1}'
+命令返回稳定的输出信封：
 
-# 知识库（新建 → 上传 → 编译 → 查询）
+```json
+{
+  "ok": true,
+  "data": {},
+  "_notice": {}
+}
+```
+
+- 默认使用 `--format json`，推荐 Agent 使用。
+- 支持的人工列表命令可使用 `--format table`。
+- `--jq <expr>` 使用 jq 1.8 筛选业务结果，再输出统一信封。
+- `--validate` 仅规范化 Capability Gateway 参数，不执行业务逻辑。
+- `--dry-run` 预览操作，不执行业务逻辑。
+- `--yes` 跳过明确标记为高风险写操作的交互确认。
+- `_notice` 可以携带 Host 兼容性或更新提示，不改变成功的业务数据。
+
+JSON 参数通常支持内联 JSON、`@file`、文件路径或通过 `-` 从 stdin 读取，具体以命令帮助为准。
+
+## 知识库
+
+管理服务端知识库生命周期：
+
+```bash
 ae-cli kb +new --scope company --name engineering-handbook --description "Team docs"
 ae-cli kb +add --name engineering-handbook --files '["./docs/guide.md","https://example.com/page"]'
 ae-cli kb +schema --name engineering-handbook
 ae-cli kb +compile --name engineering-handbook
-ae-cli kb +query -q "如何配置 sandbox 容器？" \
-  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
-  --top-k 10
+ae-cli kb +status --name engineering-handbook
+ae-cli kb +query -q "如何配置沙盒？" --top-k 10
+```
+
+外部 Agent 可以使用不依赖服务端 LLM 的确定性检索：
 
-# 面向外部 agent 的检索原语（读 index → grep 定位 → read 翻页）
+```bash
+ae-cli kb +list
 ae-cli kb +index --sources '[{"scope":"company","name":"engineering-handbook"}]'
-ae-cli kb +grep -q "sandbox 配置" \
-  --sources '[{"scope":"company","name":"engineering-handbook"}]'
-ae-cli kb +read --source '{"scope":"company","name":"engineering-handbook"}' \
-  --path "wiki/sandbox.md"
+ae-cli kb +grep -q "沙盒配置" --sources '[{"scope":"company","name":"engineering-handbook"}]'
+ae-cli kb +read --source '{"scope":"company","name":"engineering-handbook"}' --path "wiki/sandbox.md"
 ```
 
-## 身份验证
+## Agent 与系统管理
 
-每个 AE 主机 URL 维护独立的身份验证 token。
+`agent` 域管理当前用户可见的 Agent 资源：
 
 ```bash
-# 设备码登录（跨平台）
-ae-cli auth login
-
-# 检查状态
-ae-cli auth status
-
-# 登出
-ae-cli auth logout
-```
-
-## 命令
-
-### 域
-
-| 域 | 命令数 | 描述 |
-|---|---|---|
-| `analysis` | 30+ | 分析工作流：告警、报表、仪表板、即时分析/下钻、实体/事件详情、分析模型 |
-| `analysis_meta` | 20+ | 元数据治理：事件/属性、指标、虚拟元数据、项目配置、埋点方案、标记时间、实体目录 |
-| `engage` | 40+ | Hermes Engage MCP：渠道、任务、配置、流程、策略 |
-| `dataops_repo` | 1 | DataOps 仓库辅助：空间发现 |
-| `dataops_datatable` | 5 | 数据表：表/视图创建、发布、详情、数据字典 |
-| `dataops_flow` | 15 | 任务流：流程创建、任务节点、调度、执行、监控、发布预览 |
-| `dataops_operations` | 4 | 运维：工作流实例搜索、实例详情、任务日志、停止执行 |
-| `dataops_ide` | 9 | IDE 查询：元数据浏览、SQL 执行、查询管理 |
-| `dataops_integration` | 19 | 数据集成：数据源管理、同步方案、数据同步 |
-| `community` | 10+ | 社区分析：帖子搜索、情感分析、话题趋势、直播数据 |
-| `analysis_common` | 2 | 跨模块通用约束：资源链接补全、项目 ID 门控 |
-| `agent` | 15 | Agent 平台资源管理：模型、MCP 服务、Skill、附件库的增删查和启停 |
-| `team` | 14 | AI Agent Team：团队管理（列表/创建/更新/删除/AI生成/模板/项目）和 TeamRun 执行（启动/监听/对话/回复/取消/结果/产物） |
-| `kb` | 11 | 知识库生命周期：查询 / 新建 / 添加源（md/目录/url）/ schema / 编译 / 删除源 / 删除；检索原语：list / index / grep / read |
-| `auth` / `config` | 2 | 身份验证和主机配置 |
-
-### kb（知识库）
-
-知识库生命周期（`+new` → `+add` → `+schema` → `+compile` → `+status` → `+query`）：
-
-- **新建** (`+new`)：`--scope personal|company`，`--name`，可选 `--description`、`--tags`、`--project-id`、`--project-name`
-- **上传源** (`+add`)：`--name`，`--files` JSON 数组（`.md` 文件、目录非递归扫描、或 http(s) URL 自动转 Markdown）
-- **生成 schema** (`+schema`)：`--name`，可选 `--force`、`--model`
-- **编译** (`+compile`)：`--name`，`--mode incremental|full`（默认 incremental）
-- **查询状态** (`+status`)：`--name`
-- **查询** (`+query`)：`--query` / `-q`，可选 `--sources` JSON 引用（省略则搜索全部可访问知识库）、`--top-k`（1-50，默认 10）、`--locale`
-- **删除源** (`+rm-source`)：`--name`，`--display-name`
-- **删除知识库** (`+remove`)：`--name`
-
-面向外部 agent 的检索原语（`+list` → `+index` → `+grep` → `+read`）；均为确定性文件检索端点、服务端零 LLM 调用，让 agent（Claude Code / Codex / Cursor）像翻代码库一样探索知识库：
-
-- **列表** (`+list`)：可选 `--build-status`（默认 `compiled`）、`--locale`。返回可访问知识库的元信息（含 `buildStatus`），不含 `index.md` 导航地图。
-- **索引** (`+index`)：可选 `--sources` JSON 引用（省略则列出全部可访问知识库），可选 `--locale`。返回每个知识库的元信息及其 `index.md` 导航地图。
-- **检索** (`+grep`)：`--query` / `-q`，可选 `--sources`、`--top-k`（1-50，默认 10）、`--locale`。返回命中行的路径、行号、面包屑与上下文片段。
-- **读取** (`+read`)：`--source` JSON 引用（精确指向一个知识库），`--path`（相对知识库根目录的页面路径），可选 `--offset` / `--limit`（行窗口）、`--locale`。返回页面全文或行窗口。
-
-### 全局选项
-
-| 选项 | 描述 | 默认值 |
-|---|---|---|
-| `--host <url>` | 覆盖当前 AE 主机 URL | 从配置读取 |
-| `--format <json\|table>` | 输出格式 | json |
-| `--jq <expr>` | jq 1.8 表达式（jq-wasm），作用于命令业务结果，再包进输出信封 | - |
-| `--validate` | 改对参数：仅能力网关 `/validate`（精选网关命令）。勿与 `--dry-run` 同用 | false |
-| `--dry-run` | 确认可以跑：能力网关 `/dry-run`（或其它传输的请求预览）。勿与 `--validate` 同用 | false |
-| `--yes` | 跳过高风险写操作确认 | false |
-| `--no-update-check` | 跳过 ae-cli 新版本检查 | false |
-
-## Skills
-
-`skills/` 目录包含 4 个 AI Agent 技能包：
-
-| Skill | 描述 |
-|---|---|
-| `ae-analysis` | 统一分析技能：analysis + audience + metadata + 通用约束（项目门控/资源链接） |
-| `ae-engage` | Hermes Engage MCP：渠道、任务、配置、流程、策略 |
-| `ae-dataops` | 数仓管理、任务流、IDE 查询、数据集成、运维管理 |
-| `ae-community` | 社区分析：帖子、评论、话题、直播 |
+ae-cli agent +list-agents
+ae-cli agent +list-models
+ae-cli agent +list-mcps
+ae-cli agent +list-skills
+ae-cli agent +list-automations
+ae-cli agent +list-attachments
+```
 
-安装方式：
+`system` 域调用管理接口 `/api/admin/**`，要求当前用户拥有 `root` 或 `agent_admin` 角色：
 
 ```bash
-npx skills add ThinkingAIAgenticEngine/ae-cli -g -y
+ae-cli system +list-members --status enabled
+ae-cli system +list-sandboxes
+ae-cli system +get-usage-summary --days 30
+ae-cli system +list-quota-rules
+ae-cli system +list-channels
 ```
 
-## Skill 详情
-
-### ae-analysis
+最终权限始终由服务端校验。遇到权限错误时不要重试或绕过。
 
-统一的 AE 分析能力：
-- **分析**：告警、报表、仪表板、即时分析/下钻、实体/事件详情、分析模型
-- **受众**：分群和标签生命周期管理，以及定义模型工具
-- **元数据**：事件/属性、指标、虚拟元数据、项目配置、埋点方案、标记时间
-- **通用约束**：强制的项目 ID 门控和写入后资源链接补全
+## Agent Skills
 
-### engage
+npm 包内包含与公开仓库一致的 `skills/` 目录：
 
-Hermes Engage MCP 能力：
-- **渠道**：渠道管理、配置渠道、审批、白名单
-- **任务**：任务列表、详情、数据/指标概览、实验报告
-- **配置**：配置项、策略、对比、触发/分析报告
-- **流程**：流程创建、节点配置、报告、验证
+| Skill | 范围 |
+|---|---|
+| `ae-capability` | Capability 发现和通用调用 |
+| `ae-analysis`、`ae-analysis-global` | 分析、受众、元数据、治理及多集群工作流 |
+| `ae-experiment` | Atlas 实验、Feature、指标、流量层和报表工作流 |
+| `ae-metadata` | 基于 Capability Gateway 的元数据数据表操作 |
+| `ae-engage` | 运营操作和工作流指南 |
+| `ae-dataops` | 数仓、任务流、IDE、数据集成和运维 |
+| `ae-community` | 社区分析和报告 |
+| `ae-kb` | 知识库生命周期和检索 |
+| `ae-agent`、`ae-system`、`ae-team` | Agent 资源、系统管理和 TeamRun 工作流 |
+| `ae-generate-tracking-plan`、`ae-generate-tracking-code` | 埋点方案和埋点代码生成 |
+| `ae-data-integration-helper` | SDK 和 LogBus2 集成指南 |
+
+重新安装全部公开 Skills：
 
-### ae-dataops
+```bash
+npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+```
 
-数仓管理：
-- **仓库辅助**：空间发现
-- **数据表**：表创建、视图、批量操作、数据字典
-- **任务流**：流程创建、任务节点、调度、执行、监控
-- **IDE 查询**：元数据浏览、SQL 执行、查询管理
-- **数据集成**：数据源管理、同步方案、数据同步
+## 开发
 
-### ae-community
+```bash
+git clone https://github.com/ThinkingAIAgenticEngine/ae-cli.git
+cd ae-cli
+npm install
+npm run build
+node dist/index.js --help
+```
 
-社区社媒分析：
-- **帖子**：搜索、详情、语料标签
-- **评论**：情感分析、标签分析、摘要
-- **话题**：热门话题、趋势、每日摘要
-- **直播**：直播间、场次、分析、指标
-- **渠道信息**：渠道概览指标
+开发时直接从源码运行：
 
-## 架构
+```bash
+npm run dev -- --help
+```
 
-ae-cli 基于：
-- **TypeScript**（约 8000 行代码）
-- **Commander.js** 作为 CLI 框架
-- **WebSocket** 用于 MCP 服务器集成
-- **Node.js** 运行时（v20+）
+核心目录：
 
-项目结构：
-```
+```text
 src/
-├── core/          # 核心模块：auth, config, client, mcp
-├── framework/     # 框架：types, register, runner, output
-├── api/           # 原始 API 访问
-└── commands/      # 领域特定命令
-    ├── auth.ts
-    ├── config.ts
-    ├── te-analysis/
-    ├── te-meta/
-    ├── te-engage/
-    ├── te-dataops/
-    ├── te-community/
-    ├── te-common/
-    └── te-kb/
-```
-
-## 验证脚本
+├── core/          # 认证、配置、客户端、兼容性和版本同步
+├── framework/     # 命令注册、生命周期、输出和错误
+├── api/           # 原始认证 API 访问
+└── commands/      # 业务域和 CLI 工具
+skills/            # 随 npm 包发布的 Agent Skills
+self-check/        # 发布和文档一致性检查
+test/, tests/      # 命令、契约和回归测试
+```
+
+常用验证命令：
 
 ```bash
-npm run verify:analysis-tools
-npm run verify:analysis-meta-tools
-npm run verify:analysis-common-tools
+npm run build
+npm run qa-changed
+npm run self-check
+npm run check:release
+npm run verify:experiment-tools
+npm run verify:update-check
+npm run verify:version-sync
 ```
 
+## 更新日志
+
+- [English changelog](./CHANGELOG.md)
+- [中文更新日志](./CHANGELOG.zh-CN.md)
+
 ## 许可证
 
 MIT

package/dist/{auth-B2BRSYMS.js → auth-56Z45UVR.js}

@@ -5,7 +5,7 @@ import {
   printError,
   printOutput,
   runHostCompatCheck
-} from "./chunk-JTKMDN4A.js";
+} from "./chunk-KTYR3U6D.js";
 import {
   clearCliToken,
   mintCliToken

package/dist/{capability-6KPXYNO7.js → capability-2H6PAOA3.js}

@@ -16,7 +16,7 @@ import {
 import {
   printError,
   printOutput
-} from "./chunk-JTKMDN4A.js";
+} from "./chunk-KTYR3U6D.js";
 import "./chunk-E7UXXHO3.js";
 import {
   SecureStoreAuthError,

package/dist/{capability-ROKYESAP.js → capability-YPOQX6PL.js}

@@ -16,7 +16,7 @@ import {
 import {
   printError,
   printOutput
-} from "./chunk-JTKMDN4A.js";
+} from "./chunk-KTYR3U6D.js";
 import "./chunk-E7UXXHO3.js";
 import {
   SecureStoreAuthError,