@easyv/screen-cli 0.1.0 → 0.1.1
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 +236 -54
- package/dist/client.js +6 -6
- package/dist/commands/auth.js +83 -84
- package/dist/commands/debug.js +14 -34
- package/dist/commands/screen.js +3 -3
- package/dist/config.js +163 -57
- package/dist/debug-query.js +224 -0
- package/package.json +1 -1
- package/skills/easyv-screen-debug/SKILL.md +35 -21
- package/skills/easyv-screen-shared/SKILL.md +9 -8
package/README.md
CHANGED
|
@@ -1,102 +1,284 @@
|
|
|
1
1
|
# @easyv/screen-cli
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
+
要同时使用多个工作台时,每个工作台是一个环境,登录状态互相隔离。切到某个环境后,只能使用和切换这个环境下的登录。
|
|
26
49
|
|
|
27
50
|
```bash
|
|
28
51
|
easyv-screen config add --name dev \
|
|
29
|
-
--base-url
|
|
30
|
-
--
|
|
52
|
+
--base-url https://另一个工作台 \
|
|
53
|
+
--use
|
|
54
|
+
```
|
|
31
55
|
|
|
32
|
-
|
|
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
|
-
|
|
40
|
-
|
|
77
|
+
查看和切换:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
easyv-screen auth status
|
|
41
81
|
easyv-screen auth list
|
|
42
|
-
easyv-screen auth use
|
|
43
|
-
easyv-screen auth
|
|
44
|
-
easyv-screen auth status # 当前环境、Key,以及绑定的空间和团队
|
|
82
|
+
easyv-screen auth use other
|
|
83
|
+
easyv-screen auth logout
|
|
45
84
|
```
|
|
46
85
|
|
|
47
|
-
|
|
86
|
+
`status` 会显示工作台地址、当前登录,以及绑定的空间和团队。有多个工作台时还会带上当前环境名。`logout` 移除当前正在使用的登录。
|
|
87
|
+
|
|
88
|
+
在 macOS 上,登录状态存在系统钥匙串里,配置文件只保留名称。配置目录是 `~/.easyv-screen`。
|
|
48
89
|
|
|
49
|
-
##
|
|
90
|
+
## 搭一块大屏
|
|
50
91
|
|
|
51
92
|
```bash
|
|
52
|
-
easyv-screen screen groups
|
|
53
|
-
easyv-screen screen create --name "销售看板" --group 1
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
|
|
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
|
-
|
|
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
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
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
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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 :
|
|
76
|
+
const token = (0, config_1.isSession)(this.credential) ? this.credential.accessToken : undefined;
|
|
77
77
|
if (token == null)
|
|
78
|
-
throw new ApiError('UNAUTHORIZED', '
|
|
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
|
|
153
|
-
if (
|
|
154
|
-
throw new ApiError('BAD_REQUEST',
|
|
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(
|
|
156
|
+
return new Client((0, config_1.apiEndpoint)(origin), target?.credential);
|
|
157
157
|
}
|
|
158
158
|
/** 打印错误并按约定退出码退出 */
|
|
159
159
|
function exitOnError(error) {
|