@sparkelf/dsh-artifact-app 0.0.0-stage → 0.1.0
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 +56 -2
- package/cordis.patch.yml +3 -0
- package/lib/client.js +824 -0
- package/lib/client.js.map +1 -0
- package/lib/index.d.ts +638 -0
- package/lib/index.js +2154 -0
- package/package.json +82 -3
- package/skills/artifact-app-authoring/SKILL.md +157 -0
package/package.json
CHANGED
|
@@ -1,6 +1,85 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sparkelf/dsh-artifact-app",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "DataOps cockpit artifacts in the DSH right sidebar: templates, render host, SSE open bridge and model tools.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./lib/index.js",
|
|
7
|
+
"types": "./lib/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./lib/index.d.ts",
|
|
11
|
+
"default": "./lib/index.js"
|
|
12
|
+
},
|
|
13
|
+
"./client": {
|
|
14
|
+
"default": "./lib/client.js"
|
|
15
|
+
},
|
|
16
|
+
"./package.json": "./package.json"
|
|
17
|
+
},
|
|
18
|
+
"dsh": {
|
|
19
|
+
"bundle": {
|
|
20
|
+
"patch": "./cordis.patch.yml"
|
|
21
|
+
},
|
|
22
|
+
"client": {
|
|
23
|
+
"platform": "web",
|
|
24
|
+
"inject": [
|
|
25
|
+
"@deepseek-ai/dsh-client-locale",
|
|
26
|
+
"@deepseek-ai/dsh-client-ui-slots",
|
|
27
|
+
"@deepseek-ai/dsh-client-ui-primitives"
|
|
28
|
+
]
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
"files": [
|
|
32
|
+
"lib/index.js",
|
|
33
|
+
"lib/index.d.ts",
|
|
34
|
+
"lib/client.js",
|
|
35
|
+
"lib/client.js.map",
|
|
36
|
+
"cordis.patch.yml",
|
|
37
|
+
"skills/artifact-app-authoring/SKILL.md",
|
|
38
|
+
"README.md"
|
|
39
|
+
],
|
|
40
|
+
"scripts": {
|
|
41
|
+
"build": "tsdown",
|
|
42
|
+
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
43
|
+
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": "^22.19.0 || >=24.0.0"
|
|
46
|
+
},
|
|
47
|
+
"license": "MIT",
|
|
48
|
+
"repository": {
|
|
49
|
+
"type": "git",
|
|
50
|
+
"url": "git+https://github.com/SparkElf/dsh-plugins-plus.git",
|
|
51
|
+
"directory": "packages/artifact-app"
|
|
52
|
+
},
|
|
53
|
+
"publishConfig": {
|
|
54
|
+
"access": "public"
|
|
55
|
+
},
|
|
56
|
+
"peerDependencies": {
|
|
57
|
+
"@deepseek-ai/cordis": "^4.0.4",
|
|
58
|
+
"@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.2",
|
|
59
|
+
"@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.2",
|
|
60
|
+
"@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.2",
|
|
61
|
+
"@deepseek-ai/dsh-credentials": ">=0.1.7-rc.2",
|
|
62
|
+
"@deepseek-ai/dsh-host-webserver": ">=0.1.7-rc.2",
|
|
63
|
+
"@deepseek-ai/dsh-skill": ">=0.1.7-rc.2",
|
|
64
|
+
"@deepseek-ai/dsh-tools": ">=0.1.7-rc.2",
|
|
65
|
+
"@deepseek-ai/dsh-user-approval": ">=0.1.7-rc.2",
|
|
66
|
+
"react": ">=18.2.0 <20"
|
|
67
|
+
},
|
|
68
|
+
"devDependencies": {
|
|
69
|
+
"@deepseek-ai/cordis": "4.0.4",
|
|
70
|
+
"@deepseek-ai/dsh-client-locale": "0.1.7-rc.2",
|
|
71
|
+
"@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
|
|
72
|
+
"@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
|
|
73
|
+
"@deepseek-ai/dsh-credentials": "0.1.7-rc.2",
|
|
74
|
+
"@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
|
|
75
|
+
"@deepseek-ai/dsh-skill": "0.1.7-rc.2",
|
|
76
|
+
"@deepseek-ai/dsh-tools": "0.1.7-rc.2",
|
|
77
|
+
"@deepseek-ai/dsh-user-approval": "0.1.7-rc.2",
|
|
78
|
+
"@types/node": "^22.0.0",
|
|
79
|
+
"@types/react": "~18.3.1",
|
|
80
|
+
"@types/react-dom": "^18.3.0",
|
|
81
|
+
"react": "^18.2.0",
|
|
82
|
+
"react-dom": "^18.2.0",
|
|
83
|
+
"tsdown": "^0.22.2"
|
|
84
|
+
}
|
|
6
85
|
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: artifact-app-authoring
|
|
3
|
+
description: 根据数据资源制作驾驶舱 / 大屏 / 看板,或修改已有驾驶舱时使用。包含模板选择、data-slot 填写、artifactApp 运行时约束、HTML 文件预览和发布前用户确认;没有用户明确同意不得发布。
|
|
4
|
+
metadata:
|
|
5
|
+
permissions:
|
|
6
|
+
- artifact-app:create
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 驾驶舱(Artifact App)制作
|
|
10
|
+
|
|
11
|
+
用户要把一个数据资源做成驾驶舱、大屏或看板时用本技能。你只写「内容区」:模板负责布局、视觉和运行时,插件 host 负责注入 ECharts、SDK、CSP 和 token。
|
|
12
|
+
|
|
13
|
+
## 一、什么时候用
|
|
14
|
+
|
|
15
|
+
- 根据资源做驾驶舱 / 大屏 / 看板 / 经营盘
|
|
16
|
+
- 把这个资源做成可视化
|
|
17
|
+
- 更新这个驾驶舱 / 加一个图表 / 改一个指标
|
|
18
|
+
- 用某个模板做一个驾驶舱
|
|
19
|
+
|
|
20
|
+
不适用:纯问数取数(用 `dataops-query`);只是要一张静态图(用图表工具)。
|
|
21
|
+
|
|
22
|
+
## 二、硬规则
|
|
23
|
+
|
|
24
|
+
1. **先选模板,不要从零写 HTML。** 先 `artifact_template_list`,按业务场景选一个;再 `artifact_template_get` 拿骨架和 `data-slot` 契约。
|
|
25
|
+
2. **只填 `data-slot`。** 不改 `window.artifactApp` 运行时,不删 required markers,不改模板的布局与 CSS 变量。
|
|
26
|
+
3. **HTML 写到固定目录**:`/workspace/artifact-apps/<slug>.html`,文件头必须有
|
|
27
|
+
`<meta name="artifact-app" content="cockpit">`,
|
|
28
|
+
建议同时写 `<meta name="artifact-app-template" content="<templateId>@<version>">`。
|
|
29
|
+
4. **取数统一走运行时**:
|
|
30
|
+
- 表:`artifactApp.query({ sources, sql, maxRows })`,`sources` 必须是 `[{ resourceRef, alias }]`(不是字符串数组);
|
|
31
|
+
- 已登记 API:`artifactApp.callApi({ operationRef, args })`;
|
|
32
|
+
- 自定义请求:`artifactApp.fetch('/api/...')`。
|
|
33
|
+
HTML 里不写 token,不手写 `Authorization`。
|
|
34
|
+
5. **轮询统一用 `artifactApp.every(intervalMs, fn)`**,不要自己写 `setInterval` / `setTimeout`。
|
|
35
|
+
6. **图表用 `artifactApp.chart(el, option)`**;使用全局 `echarts`,不要引 CDN。
|
|
36
|
+
7. **状态用 `artifactApp.ui.loading/empty/error/noPermission`**;403 用 `artifactApp.requestAccess(resourceRef)`。
|
|
37
|
+
8. **格式化用 `artifactApp.format.number/percent/currency/date`**;配置从 `artifactApp.config` 读;启动时调 `artifactApp.ready()`。
|
|
38
|
+
9. **发布必须用户明确确认。** 先让用户看到预览,问「确认发布吗?」;只有用户明确说「发布 / 确认」后才调用 `cockpit_publish`。
|
|
39
|
+
|
|
40
|
+
## 三、禁止
|
|
41
|
+
|
|
42
|
+
- 直接 `fetch('/api/...')`、手写 `Authorization`、读取或打印 token。
|
|
43
|
+
- 用 `setInterval` / `setTimeout` 做轮询。
|
|
44
|
+
- 访问 `window.parent`、`localStorage`、`sessionStorage`、`document.cookie`、`indexedDB`。
|
|
45
|
+
- 外链 `script` / `img` / `font` / CDN / `@import url(http...)`。
|
|
46
|
+
- 把 token、内网 IP、数据库名写进 HTML。
|
|
47
|
+
- 删除或改写 `window.artifactApp`、`data-slot` 标记、模板的 required markers。
|
|
48
|
+
- 写 `/workspace/artifact-apps/` 之外的文件。
|
|
49
|
+
- 调 auth、用户 / 角色 / 部门管理、工作区生命周期接口。
|
|
50
|
+
- 未经用户确认调 `cockpit_publish` / `cockpit_delete` / `cockpit_grant`。
|
|
51
|
+
|
|
52
|
+
## 四、流程
|
|
53
|
+
|
|
54
|
+
1. **确认资源与口径**:复用 `dataops-query` 的选表策略;`describe_resource` 看字段,`execute_sql` 聚合确认口径;不要拉明细全量。
|
|
55
|
+
2. **选模板**:`artifact_template_list` → 按场景选一个 → `artifact_template_get`。
|
|
56
|
+
3. **写 HTML**:在模板上填 `data-slot` 内容(KPI、图表容器、表格、榜单)、查询调用与 ECharts option。
|
|
57
|
+
4. **写文件**:写到 `/workspace/artifact-apps/<slug>.html`,带 `artifact-app` 标记。
|
|
58
|
+
5. **预览**:从文件树打开这个 HTML。插件文件查看器会自动建/复用草稿并渲染真实数据;不要另调预览工具(没有 `cockpit_preview`)。
|
|
59
|
+
6. **改**:用户提修改就直接改同一个 HTML 文件,重新打开/刷新预览。
|
|
60
|
+
7. **改刷新频率 / 保持连接**:用户说「每分钟刷一次」→ `cockpit_update` 改 `refresh_interval_seconds`;说「打开后保持连接」→ `keep_connection=true`。默认保持连接是 false,不要主动打开。
|
|
61
|
+
8. **发布**:用户确认后 `cockpit_publish({ html_path, name?, description?, catalog?, template_id?, template_version?, artifact_id? })`。不带 `artifact_id` 是新建发布;带 `artifact_id` 是发新版本。
|
|
62
|
+
9. **分享**:用户明确指定主体后才 `cockpit_grant`;删除必须先让用户确认,`cockpit_delete` 会再走一次插件审批。
|
|
63
|
+
|
|
64
|
+
## 五、HTML 合同
|
|
65
|
+
|
|
66
|
+
- 基于 `artifact_template_get` 返回的骨架写;只填 slot,不改运行时。
|
|
67
|
+
- 首屏 skeleton;每块数据独立处理 loading / 空 / 无权限 / 失败,不要因为一个接口失败整页白屏。
|
|
68
|
+
- 无权限的图表用骨架模板的「暂无权限 + 申请权限」,按钮调 `artifactApp.requestAccess(resourceRef)`;不在共享前做预检。
|
|
69
|
+
- 401 由运行时处理:自动向父页面要新 token 重试一次;仍 401 显示「登录已过期」,可用 `artifactApp.on('token:expired', fn)` 感知。
|
|
70
|
+
- 适配窄栏:`width:100%`、`height:100%`、CSS Grid、`clamp()` 字号。
|
|
71
|
+
- 中文标签;金额/百分比带单位和千分位。
|
|
72
|
+
- 不在 HTML 源码里出现 token、内网 IP、数据库名。
|
|
73
|
+
|
|
74
|
+
## 六、取数示例
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
artifactApp.ready();
|
|
78
|
+
|
|
79
|
+
artifactApp.every(artifactApp.config.refreshIntervalSeconds * 1000, async () => {
|
|
80
|
+
artifactApp.ui.loading(document.getElementById('trend'), '加载中…');
|
|
81
|
+
try {
|
|
82
|
+
const payload = await artifactApp.query({
|
|
83
|
+
sources: [{ resourceRef: 'urn:dataops:resource:123', alias: 'sales' }],
|
|
84
|
+
sql: 'SELECT month, SUM(amount) AS amount FROM sales GROUP BY month ORDER BY month',
|
|
85
|
+
maxRows: 500
|
|
86
|
+
});
|
|
87
|
+
artifactApp.chart(document.getElementById('trend'), {
|
|
88
|
+
xAxis: { type: 'category', data: payload.rows.map(row => row[0]) },
|
|
89
|
+
yAxis: { type: 'value' },
|
|
90
|
+
series: [{ type: 'line', data: payload.rows.map(row => row[1]) }]
|
|
91
|
+
});
|
|
92
|
+
} catch (error) {
|
|
93
|
+
artifactApp.ui.error(document.getElementById('trend'), '取数失败:' + error.message);
|
|
94
|
+
}
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## 七、模板清单怎么选
|
|
99
|
+
|
|
100
|
+
- 警务:警情态势 / 案件侦办 / 治安巡防 / 重点人员场所管控。
|
|
101
|
+
- 商业:经营大屏 / 通行运营 / 投资与项目 / 销售经营。
|
|
102
|
+
- 没有现成业务主题:`blank`。
|
|
103
|
+
|
|
104
|
+
按「用户打开这个驾驶舱想问的问题」选,不按图表类型选。
|
|
105
|
+
|
|
106
|
+
## 八、模板包:目录化 + 素材托管
|
|
107
|
+
|
|
108
|
+
从 v0.1.x 起,驾驶舱模板可以直接以**目录包**形式发布,素材不再必须内联进 HTML。
|
|
109
|
+
|
|
110
|
+
### 目录结构
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
<template-id>/
|
|
114
|
+
├── template.json # { id, name, description?, catalog?, slots[], question?, theme? }
|
|
115
|
+
├── template.html # 内联 CSS;素材用 asset://<逻辑名> 引用
|
|
116
|
+
└── assets/ # 可选
|
|
117
|
+
├── logo.png
|
|
118
|
+
└── nanning.geojson
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
- **逻辑名 = 文件名去掉后缀**:`assets/logo.png` → `asset://logo`;
|
|
122
|
+
- 支持的类型:`.png .jpg .jpeg .webp .svg .json .geojson .woff2 .css .js .html`;
|
|
123
|
+
- 单文件 ≤ 32 MB,整包解压后 ≤ 100 MB,文件数 ≤ 200;
|
|
124
|
+
- **不要**在包里放 `node_modules`、隐藏文件或可执行文件。
|
|
125
|
+
|
|
126
|
+
### 为什么优先用素材而不是 base64
|
|
127
|
+
|
|
128
|
+
| 方式 | 体积 | 缓存 | 适用 |
|
|
129
|
+
| --- | --- | --- | --- |
|
|
130
|
+
| base64 内联 | 每份驾驶舱都背全部图片 | 无 | 单文件分发(离线发出去) |
|
|
131
|
+
| `asset://` + assets/ | HTML 只有几十 KB | `immutable` 长缓存、多应用共享 | 平台内正常浏览 |
|
|
132
|
+
|
|
133
|
+
**默认用 `asset://`**;只有明确要「导出一个能离线打开的 HTML」时才依赖导出时的内联。
|
|
134
|
+
|
|
135
|
+
### 发布流程
|
|
136
|
+
|
|
137
|
+
1. 在 workspace 里建好 `<template-id>/` 目录(template.json + template.html + assets/);
|
|
138
|
+
2. 调工具 `artifact_template_publish({ directory: '<template-id>' })`;
|
|
139
|
+
3. 服务端会:解 zip → 校验(路径穿越/体积/后缀/SVG 脚本)→ 素材按内容寻址落盘 → 建模板版本;
|
|
140
|
+
4. 之后用 `artifact_app_create` / `artifact_app_publish` 引用该 `template_id` 建应用。
|
|
141
|
+
|
|
142
|
+
### 素材解析顺序(渲染时)
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
应用版本 own → 模板 assets/(按 templateId) → shared
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- 应用想换一张图,把同名素材挂到应用版本即可覆盖,其他继续沿用模板的;
|
|
149
|
+
- 模板升级不会自动改变已建应用(应用版本冻结模板版本号),要同步得显式调
|
|
150
|
+
`artifact_app_upgrade_template`。
|
|
151
|
+
|
|
152
|
+
### 导出
|
|
153
|
+
|
|
154
|
+
| 模式 | 产物 | 用途 |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `inline` | 单 HTML(素材 + runtime + ECharts 全内联) | 邮件/网盘/离线 |
|
|
157
|
+
| `external` | zip(index.html + assets/) | 部署到静态服务器 |
|