@easyv/screen-cli 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,102 +1,284 @@
1
1
  # @easyv/screen-cli
2
2
 
3
- 用命令驱动 EasyV 大屏,给 AI Agent(Cursor、Claude、Codex)调用。能做三件事:
3
+ `easyv-screen` 是 EasyV 可视化大屏的命令行工具。用它搭建大屏、修改配置和交互、给组件接数据、查看组件的数据来源和交互配置,也可以从零开发组件并上传到平台。
4
4
 
5
- - 从零搭建一个大屏,没有合适的组件就从零开发并上传
6
- - 修改已有大屏:改配置、配交互、接数据源、调图层
7
- - 排查大屏:一个组件为什么不显示、点击为什么没反应
5
+ 命令默认输出 JSON,人可以直接用,Cursor、Claude、Codex 等 AI Agent 也可以调用。
6
+
7
+ ## 能做什么
8
+
9
+ - **搭建大屏**:查分组、创建大屏、放入组件、校验布局、截图、发布
10
+ - **修改大屏**:改配置、调位置和图层、配置点击联动、升级组件版本
11
+ - **接数据**:查已有数据源、新建数据库或 API 连接、看表结构和预览数据、把组件绑到数据源或静态数据
12
+ - **排查问题**:查看一个组件的数据来源,以及它触发了谁、谁触发了它
13
+ - **开发组件**:现成组件表达不了需求时,在本地生成骨架、打包签名并上传
8
14
 
9
15
  ## 安装
10
16
 
17
+ 需要 Node.js 18 或更高版本。
18
+
11
19
  ```bash
12
- npm install
13
- npm run build
14
- npm link
20
+ npm install -g @easyv/screen-cli
15
21
  ```
16
22
 
17
- 安装技能到各 AI 工具的技能目录:
23
+ 要用 AI 来操作大屏时,把附带的技能装进各工具的技能目录:
18
24
 
19
25
  ```bash
20
26
  easyv-screen skills install
21
27
  ```
22
28
 
23
- ## 配置与登录
29
+ 技能会写到 `~/.agents/skills`,并链接到 `~/.cursor/skills`、`~/.claude/skills` 和 `~/.codex/skills`。
30
+
31
+ ## 配置工作台
32
+
33
+ 命令访问的工作台地址保存在本机。只用一个工作台时,设置一次地址即可:
34
+
35
+ ```bash
36
+ easyv-screen config set --base-url https://你的工作台
37
+ ```
38
+
39
+ `--base-url` 是工作台的域名地址。再次执行会改这个地址。地址变了之后,原来的登录会清掉,需要重新登录。
40
+
41
+ ```bash
42
+ easyv-screen config list
43
+ easyv-screen config remove
44
+ ```
45
+
46
+ 只有一个工作台时,`list` 返回 `baseUrl`、`currentKey` 和 `keys`。`remove` 会删掉这个地址和全部登录。
24
47
 
25
- 一个 baseURL 是一个环境。每个环境下可以有多把 API Key,环境之间的 Key 互相隔离。切到某个环境后,只能使用和切换这个环境下的 Key。
48
+ 要同时使用多个工作台时,每个工作台是一个环境,登录状态互相隔离。切到某个环境后,只能使用和切换这个环境下的登录。
26
49
 
27
50
  ```bash
28
51
  easyv-screen config add --name dev \
29
- --base-url http://127.0.0.1:9800/api/easyv/open/v1 \
30
- --web http://workspace.easyv.test --use
52
+ --base-url https://另一个工作台 \
53
+ --use
54
+ ```
31
55
 
32
- easyv-screen config add --name test \
33
- --base-url http://workspace.saas-test.k8s.dtstack.cn/api/easyv/open/v1 \
34
- --web http://workspace.saas-test.k8s.dtstack.cn
56
+ - `--use` 表示添加后立刻切换到这个环境。当时还没有工作台时,第一个环境即使不带 `--use` 也会成为当前环境
35
57
 
58
+ ```bash
36
59
  easyv-screen config list
37
60
  easyv-screen config use dev
61
+ easyv-screen config remove dev
62
+ ```
63
+
64
+ 有多个环境时,`list` 会多出 `current` 和 `environments`。`current` 是当前环境名,对应项的 `current` 为 true。`remove` 要带上环境名称,会删掉该环境及其全部登录。多个工作台用 `add`、`use`、`remove` 管理。
65
+
66
+ ## 登录
67
+
68
+ 在浏览器确认后即可使用,过期后会自动刷新。一次登录绑定一个空间和一个团队。要操作同一个工作台里的另一个团队,用别的名称再登录一次,然后切换。
69
+
70
+ ```bash
71
+ easyv-screen auth login
72
+ easyv-screen auth login --name other
73
+ ```
74
+
75
+ 默认名称是 `default`。
38
76
 
39
- easyv-screen auth add --name personal --token <appId.secret>
40
- easyv-screen auth add --name ci --token <appId.secret>
77
+ 查看和切换:
78
+
79
+ ```bash
80
+ easyv-screen auth status
41
81
  easyv-screen auth list
42
- easyv-screen auth use personal
43
- easyv-screen auth login # 浏览器确认后,保存到当前环境
44
- easyv-screen auth status # 当前环境、Key,以及绑定的空间和团队
82
+ easyv-screen auth use other
83
+ easyv-screen auth logout
45
84
  ```
46
85
 
47
- Key 在 macOS 上存进钥匙串,配置文件里只留名称。
86
+ `status` 会显示工作台地址、当前登录,以及绑定的空间和团队。有多个工作台时还会带上当前环境名。`logout` 移除当前正在使用的登录。
87
+
88
+ 在 macOS 上,登录状态存在系统钥匙串里,配置文件只保留名称。配置目录是 `~/.easyv-screen`。
48
89
 
49
- ## 常用命令
90
+ ## 搭一块大屏
50
91
 
51
92
  ```bash
52
- easyv-screen screen groups --json
53
- easyv-screen screen create --name "销售看板" --group 1 --json
93
+ easyv-screen screen groups
94
+ easyv-screen screen create --name "销售看板" --group 1
54
95
  easyv-screen screen document get <id> -o doc.json
55
- easyv-screen screen document put <id> -f doc.json --if-match <revision>
96
+ ```
97
+
98
+ `document get` 拿到当前文档和 `revision`。之后的写入带上这个版本号,避免盖掉别人刚保存的内容。
99
+
100
+ 组件目录和配置字段从平台实时读取:
101
+
102
+ ```bash
103
+ easyv-screen component list --keyword 折线
104
+ easyv-screen component schema basicLineV2
105
+ easyv-screen component fields basicLineV2 --keyword "图例 宽度"
106
+ ```
107
+
108
+ - `list` 列出可用组件,含中文名、分类、来源(`platform` 或 `space`)和版本。`--source` 可按来源过滤
109
+ - `schema` 给出数据字段、事件、动作、默认尺寸和全部配置字段
110
+ - `fields` 按意图查少量配置字段。返回的 `path` 用于新增或修改组件;多个词用空格分隔,需要同时命中。不传关键词时只看分组
111
+
112
+ 新增组件时,服务端以组件包的默认配置为底,只叠加传入的字段。
113
+
114
+ 局部修改写成操作文件,一次提交:
115
+
116
+ ```json
117
+ {
118
+ "operations": [
119
+ {
120
+ "op": "addComponent",
121
+ "key": "c-kpi-1",
122
+ "module": "basicLineV2",
123
+ "version": "1.0.0",
124
+ "name": "销售趋势",
125
+ "layout": { "left": 40, "top": 80, "width": 640, "height": 360 },
126
+ "configPatches": [{ "path": "chart.legend.show", "value": true }]
127
+ }
128
+ ]
129
+ }
130
+ ```
131
+
132
+ ```bash
56
133
  easyv-screen screen apply <id> -f ops.json --if-match <revision>
57
134
  easyv-screen screen validate <id>
58
135
  easyv-screen screen snapshot <id> -o preview.png
136
+ easyv-screen screen publish <id>
137
+ ```
59
138
 
60
- easyv-screen component list --keyword 折线
61
- easyv-screen component fields basicLineV2 --keyword "图例"
139
+ `apply` 里任何一条操作不通过,整批都不会写入。返回的新 `revision` 用于下一次写入。版本冲突时退出码是 `4`,重新 `document get`,把改动合并进最新文档后再提交。
140
+
141
+ 整份替换文档用 `document put`,同样带上 `--if-match`:
142
+
143
+ ```bash
144
+ easyv-screen screen document put <id> -f doc.json --if-match <revision>
145
+ ```
146
+
147
+ `apply` 支持的操作:
148
+
149
+ | 操作 | 作用 |
150
+ | --- | --- |
151
+ | `addComponent` | 新增组件。`key`、`module`、`version`、`name`、`layout`;可选 `configPatches`、`data`、`parentKey`、`index` |
152
+ | `removeComponent` | 删除组件 |
153
+ | `setComponentConfig` | 按路径改配置,`configPatches` 为 `[{ path, value }]` |
154
+ | `setComponentLayout` | 改位置和尺寸:`left`、`top`、`width`、`height` |
155
+ | `element.update` | 改名称,或替换整棵配置树 |
156
+ | `addComponentEvent` / `updateComponentEvent` / `deleteComponentEvent` | 新增、替换、删除交互事件 |
157
+ | `setComponentStaticData` | 设置静态数据 |
158
+ | `element.bindData` / `element.unbindData` | 绑定数据源,或改回静态数据 |
159
+ | `setLayerVisible` | 显示或隐藏 |
160
+ | `moveLayer` | 调整图层顺序或父级 |
161
+ | `groupLayers` / `ungroupLayer` | 成组或解散。分组 key 以 `g-` 开头 |
162
+ | `upgradeComponentVersion` | 升级组件版本 |
163
+ | `screen.updateMeta` | 修改大屏名称 |
164
+
165
+ 交互事件的 `trigger` 是触发方式(如 `click`、`mouseEnter`),`actions` 里的 `component` 用 `$component(<数字 id>)` 指向目标。数字 id 是组件 key 里 `c-` 后面的数字。
166
+
167
+ 其他常用命令:
168
+
169
+ ```bash
170
+ easyv-screen screen list --group 1 --keyword 销售
171
+ easyv-screen screen get <id>
172
+ easyv-screen screen unpublish <id>
173
+ ```
174
+
175
+ `validate` 也可以先检查一份还没保存的文档:`easyv-screen screen validate <id> -f doc.json`。未通过时退出码为 `1`。
176
+
177
+ ## 给组件接数据
178
+
179
+ 密码从环境变量或标准输入读取,避免留在 shell 历史里。
180
+
181
+ ```bash
182
+ easyv-screen data source list
183
+ easyv-screen data source create --name 业务库 --type mysql \
184
+ --addr 10.0.0.8 --username app --database biz \
185
+ --password-env DB_PASSWORD
186
+
187
+ easyv-screen data source test <dataId>
188
+ easyv-screen data source tables <dataId>
189
+ easyv-screen data source columns <dataId> --table orders
190
+ easyv-screen data source preview <dataId> --sql "select * from orders limit 20"
191
+ ```
192
+
193
+ `--type` 例如 `mysql`、`postgresql`、`api`。API、MQTT、WebSocket 用 `--base-url` 指定地址。更新时省略密码会保留原密码:
194
+
195
+ ```bash
196
+ easyv-screen data source update <dataId> --name 业务库-只读
197
+ easyv-screen data source get <dataId>
198
+ easyv-screen data source delete <dataId>
199
+ ```
200
+
201
+ `get` 返回的密码已掩码。密码也可以用 `--password-stdin` 从标准输入读入。
202
+
203
+ ## 排查
204
+
205
+ 查看一个组件的数据来源和交互配置。命令只返回配置,不判断原因。`<screenId>` 是大屏 id,也可以是一份本地文档 JSON 的路径。
206
+
207
+ `<key>` 是组件在文档里的 key,以 `c-` 开头。平台上已有的组件是 `c-` 加组件数字 id,例如组件 `88` 写成 `c-88`。通过命令新建并指定了 key 的组件,用当时写入的那个 key,例如 `c-kpi-1`,横线后面不一定是数字 id。
208
+
209
+ ```bash
210
+ easyv-screen debug <screenId> <key>
211
+ easyv-screen debug <screenId> <key> --trigger click
212
+ easyv-screen debug <screenId> <key> --event <eventId>
213
+ ```
214
+
215
+ - `data` 是数据绑定和静态数据。`dataBinding` 不为空时,用里面的 `data_id` 再查 `data source get`
216
+ - `outgoing` 是这个组件配置的事件,`incoming` 是其它组件指向它的事件
217
+ - `refs` 把事件里的 `$component(...)` 等引用解析成文档 key 和名称
218
+ - `--trigger` 和 `--event` 用来缩小事件范围,可以一起用
219
+
220
+ 显隐、位置和完整配置用 `screen document get`。组件能触发的事件和能接收的动作用 `component schema`。
221
+
222
+ ## 从零开发组件
223
+
224
+ 在当前目录生成工程 `./easyv-components`。组件 module 自动加上 `ai_` 前缀,例如 `kpi-card` 会变成 `ai_kpi_card`。
225
+
226
+ ```bash
62
227
  easyv-screen component init
63
228
  easyv-screen component create kpi-card --title "指标卡"
64
229
  easyv-screen component publish ai_kpi_card
230
+ ```
65
231
 
66
- easyv-screen data source list --json
67
- easyv-screen data source create --name 业务库 --type mysql --addr 10.0.0.8 \
68
- --username app --database biz --password-env DB_PASSWORD
232
+ `create` 之后编辑这三个文件,再执行 `publish`:
69
233
 
70
- easyv-screen debug why-hidden <id> <key> --json
71
- easyv-screen debug why-no-response <id> <key> --json
234
+ - `easyv-components/src/components/ai_kpi_card/config/main.json`:配置项、触发事件、接收的动作
235
+ - `config/main.data.json`:默认静态数据和字段说明
236
+ - `index.jsx`:用 `props` 里的 `configuration` 和 `data` 渲染,触发事件调用 `emit`
237
+
238
+ 打包签名依赖全局命令 `easyv`(npm 包 `@easyv/cli`)。第一次发布前安装并写入开放平台的 Access ID 和 Secret Key:
239
+
240
+ ```bash
241
+ npm install -g @easyv/cli
242
+ easyv config set accessid <Access ID>
243
+ easyv config set secretkey <Secret Key>
72
244
  ```
73
245
 
74
- 命令输出默认是 JSON。退出码:`0` 成功、`1` 业务错误、`2` 参数错误、`3` 认证失败、`4` 版本冲突。
246
+ 密钥在工作台右上角进入「开放平台 → 组件开发」(`/development/componentDev`),点「获取 Accesskey」复制。`publish` 发现平台已有同名组件且版本不低于本地时,会把补丁号加一,再打包上传。只打包、不上传时用 `easyv-screen component build <目录名>`。
75
247
 
76
- ## 组件信息
248
+ 上传结果里 `status` 为 `published` 后,就可以在大屏里用返回的 `module` 和 `version` 引用它。
77
249
 
78
- 不随包维护组件文档,全部从平台实时读取:
250
+ ## 给 AI 用的技能
79
251
 
80
- - `component list`:组件目录,含中文名、分类和缩略图
81
- - `component schema <module>`:从组件包静态解析出的数据字段、事件、动作、默认尺寸和全部配置字段
82
- - `component fields <module> --keyword "图例 宽度"`:按意图查少量配置字段,拿到的 `path` 用于 `addComponent` / `setComponentConfig`
252
+ `easyv-screen skills install` 会安装下面这些技能。Agent 接到对应任务时按技能里的步骤调用命令。
83
253
 
84
- 新增组件时服务端会以组件包的默认配置为底,只叠加传入的字段。
254
+ | 技能 | 什么时候用 |
255
+ | --- | --- |
256
+ | `easyv-screen-shared` | 每次操作前:确认工作台、登录,写入时带上 revision |
257
+ | `easyv-screen-build` | 从零搭建一块大屏 |
258
+ | `easyv-screen-edit` | 改配置、配交互、调图层 |
259
+ | `easyv-screen-data` | 给组件接数据源或填静态数据 |
260
+ | `easyv-screen-debug` | 排查时读取组件的数据来源和交互关系 |
261
+ | `easyv-component-dev` | 从零开发组件并上传 |
262
+
263
+ ## 输出和退出码
85
264
 
86
- ## 技能
265
+ 命令默认输出 JSON。带上 `--json` 时格式不变。
87
266
 
88
- | 技能 | 用途 |
267
+ | 退出码 | 含义 |
89
268
  | --- | --- |
90
- | `easyv-screen-shared` | 登录、输出、乐观锁等共用规则 |
91
- | `easyv-screen-build` | 从零搭建大屏 |
92
- | `easyv-screen-edit` | 修改大屏、配置交互 |
93
- | `easyv-screen-data` | 给组件接数据源 |
94
- | `easyv-screen-debug` | 排查显隐和交互问题 |
95
- | `easyv-component-dev` | 从零开发并上传组件 |
96
-
97
- ## 依赖的后端
98
-
99
- 接口契约以后端仓库 `dtstack-account` 的 `openapi/spec/openapi.v1.yaml` 为准,对应 `/api/easyv/open/v1`。
100
- `npm run sync-spec` 把它同步到本仓库的 `spec/`(不入库,打包时自动同步);后端仓库不在同级目录时用 `EASYV_BACKEND_DIR` 指定。
101
- 组件打包签名使用 `@easyv/cli` 提供的 `easyv` 命令,Access ID 和 Secret Key 的配置见 `easyv-component-dev` 技能。
102
- 截图需要 `playwright` 和 Chromium。
269
+ | 0 | 成功 |
270
+ | 1 | 业务错误,例如校验未通过 |
271
+ | 2 | 参数错误 |
272
+ | 3 | 未登录或凭证失效 |
273
+ | 4 | 版本冲突,文档已被其他人改过 |
274
+
275
+ ## 截图
276
+
277
+ `screen snapshot` 打开当前工作台的预览页并保存图片,用来核对位置和显隐。本机需要安装 Playwright 和 Chromium:
278
+
279
+ ```bash
280
+ npm install -g playwright
281
+ npx playwright install chromium
282
+ ```
283
+
284
+ 默认输出 `snapshot.png`,用 `-o` 指定别的路径。预览页是布局示意图,用来核对摆放,不是最终渲染效果。
package/dist/client.js CHANGED
@@ -73,9 +73,9 @@ class Client {
73
73
  }
74
74
  const headers = {};
75
75
  if (!options.anonymous) {
76
- const token = (0, config_1.isSession)(this.credential) ? this.credential.accessToken : this.credential;
76
+ const token = (0, config_1.isSession)(this.credential) ? this.credential.accessToken : undefined;
77
77
  if (token == null)
78
- throw new ApiError('UNAUTHORIZED', '当前环境还没有选择 API Key。运行 easyv-screen auth list 查看,或 easyv-screen auth add --name <名称> --token <appId.secret>', 401);
78
+ throw new ApiError('UNAUTHORIZED', '还没有登录。运行 easyv-screen auth login', 401);
79
79
  headers['authorization'] = `Bearer ${token}`;
80
80
  }
81
81
  if (options.ifMatch != null)
@@ -149,11 +149,11 @@ function encodeMultipart(file) {
149
149
  }
150
150
  function createClient(overrides = {}) {
151
151
  const target = (0, config_1.activeTarget)();
152
- const endpoint = overrides.endpoint ?? target?.baseUrl;
153
- if (endpoint == null || endpoint.length === 0) {
154
- throw new ApiError('BAD_REQUEST', '没有选择环境。运行 easyv-screen config add --name <名称> --base-url <地址>', 0);
152
+ const origin = overrides.endpoint ?? target?.baseUrl;
153
+ if (origin == null || origin.length === 0) {
154
+ throw new ApiError('BAD_REQUEST', (0, config_1.missingWorkspaceMessage)(), 0);
155
155
  }
156
- return new Client(endpoint, target?.credential);
156
+ return new Client((0, config_1.apiEndpoint)(origin), target?.credential);
157
157
  }
158
158
  /** 打印错误并按约定退出码退出 */
159
159
  function exitOnError(error) {