agent-robot-avatar 0.2.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/CHANGELOG.md +60 -0
- package/LICENSE +21 -0
- package/README.md +286 -0
- package/agent-robot-avatar.js +16 -0
- package/assets/support/alipay.png +0 -0
- package/assets/support/wechat-pay.png +0 -0
- package/docs/README.de.md +152 -0
- package/docs/README.es.md +217 -0
- package/docs/README.fr.md +215 -0
- package/docs/README.ja.md +217 -0
- package/docs/README.ko.md +217 -0
- package/docs/README.pt.md +217 -0
- package/docs/README.zh-CN.md +286 -0
- package/docs/README.zh-TW.md +219 -0
- package/index.d.ts +78 -0
- package/package.json +76 -0
- package/src/agent-robot-avatar-actions.js +394 -0
- package/src/agent-robot-avatar-antenna-flash.js +127 -0
- package/src/agent-robot-avatar-antenna.js +173 -0
- package/src/agent-robot-avatar-core.js +1056 -0
- package/src/agent-robot-avatar-extension-host.js +73 -0
- package/src/agent-robot-avatar-failure.js +127 -0
- package/src/agent-robot-avatar-head-roundness.js +136 -0
- package/src/agent-robot-avatar-inspect.js +231 -0
- package/src/agent-robot-avatar-version.js +3 -0
- package/src/agent-robot-avatar-waiting.js +121 -0
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
# Agent Robot Avatar
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="../assets/readme/agent-robot-avatar-header.jpg" alt="Agent Robot Avatar">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
[English](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/README.md) | [简体中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-CN.md) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md) | [日本語](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ja.md) | [한국어](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ko.md) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Português](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.pt.md) | [Deutsch](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.de.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.md)
|
|
8
|
+
|
|
9
|
+
 [](../LICENSE) [](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [](https://ko-fi.com/P0E625WIOI)
|
|
10
|
+
|
|
11
|
+
      
|
|
12
|
+
|
|
13
|
+
一个轻量、富有表现力的机器人头像 Web Component，可用于 AI Agent，也可用于其他需要交互反馈的应用。
|
|
14
|
+
|
|
15
|
+
Agent Robot Avatar 基于 SVG 与原生 JavaScript 构建，不依赖第三方动画框架。它作为原生自定义元素工作，并提供一组尽量精简的 API，用于控制表情、交互状态、鼠标跟随、等待反馈和头部造型。
|
|
16
|
+
|
|
17
|
+
**当前公开版本：v0.2.0**
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
<img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 交互动画演示" width="560">
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
## 主要特点
|
|
24
|
+
|
|
25
|
+
- 纯 SVG + 原生 JavaScript
|
|
26
|
+
- 原生 Web Component
|
|
27
|
+
- 无第三方动画框架依赖
|
|
28
|
+
- 自动眨眼与轻微随机视线活动
|
|
29
|
+
- 鼠标 / 指针跟随与带惯性的头部运动
|
|
30
|
+
- 局部果冻式拖拽形变与弹性回弹
|
|
31
|
+
- 可由程序主动触发的 Agent 状态与表情
|
|
32
|
+
- 明确区分等待、失败、警告、审视、内容阻止与系统错误
|
|
33
|
+
- 可调整头部圆角
|
|
34
|
+
- 悬浮式天线，并支持可选状态闪动
|
|
35
|
+
- Demo 界面与可复用组件本体分离
|
|
36
|
+
|
|
37
|
+
## 快速开始
|
|
38
|
+
|
|
39
|
+
直接使用仓库源码时，请保持根目录的 `agent-robot-avatar.js` 与 `src/` 目录一起使用，然后加载公开入口：
|
|
40
|
+
|
|
41
|
+
```html
|
|
42
|
+
<script type="module" src="./agent-robot-avatar.js"></script>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
在页面中加入：
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<agent-robot-avatar id="avatar"></agent-robot-avatar>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
组件加载后会自动进入默认待机状态，不需要额外初始化。
|
|
52
|
+
|
|
53
|
+
最小可运行示例位于 [`examples/basic.html`](../examples/basic.html)。
|
|
54
|
+
|
|
55
|
+
使用打包工具的项目可以通过 npm 安装和引入：
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm install agent-robot-avatar
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
import 'agent-robot-avatar';
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
npm 包内置 TypeScript 类型声明，覆盖动作名称、事件和公开方法，无需另外安装类型包。
|
|
66
|
+
|
|
67
|
+
## 基本 API
|
|
68
|
+
|
|
69
|
+
统一通过 `play()` 触发表情或状态：
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
const avatar = document.querySelector('#avatar');
|
|
73
|
+
|
|
74
|
+
avatar.play('success');
|
|
75
|
+
avatar.play('failure');
|
|
76
|
+
avatar.play('warning');
|
|
77
|
+
avatar.play('inspect');
|
|
78
|
+
avatar.play('angry');
|
|
79
|
+
avatar.play('error');
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
恢复默认待机：
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
avatar.reset();
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## 状态与表情
|
|
89
|
+
|
|
90
|
+
| 状态 | API 名称 | 典型用途 |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| 默认待机 | `idle` | 正常待机状态 |
|
|
93
|
+
| 发呆 | `bored` | 长时间无任务或空闲 |
|
|
94
|
+
| 等待 | `waiting` | 请求已经发出，正在等待结果返回 |
|
|
95
|
+
| 输入中 | `input` | 用户正在输入 |
|
|
96
|
+
| 发送 | `send` | 内容已发送 / 点头反馈 |
|
|
97
|
+
| 成功 | `success` | 任务成功完成 |
|
|
98
|
+
| 失败 | `failure` | 任务执行完成，但结果失败 |
|
|
99
|
+
| 警告确认 | `warning` | 高风险、覆盖、删除等操作需要再次确认 |
|
|
100
|
+
| 审视 | `inspect` | 检查、核对或验证结果 |
|
|
101
|
+
| 内容阻止 | `angry` | 请求被阻止、不允许执行或无法继续 |
|
|
102
|
+
| 系统错误 | `error` | 网络、服务或系统本身发生错误 |
|
|
103
|
+
| 惊讶 | `surprise` | 出现意外事件或结果 |
|
|
104
|
+
| 睡眠 | `sleep` | 进入睡眠状态 |
|
|
105
|
+
| 唤醒 | `wake` | 从睡眠状态恢复 |
|
|
106
|
+
|
|
107
|
+
这些状态有意区分“任务结果”和“系统状态”。例如，`failure` 表示任务本身执行失败，而 `error` 专门表示连接、服务或系统故障；`waiting` 表示正在等待一个已经发出的请求，而 `bored` 表示当前没有活跃任务。
|
|
108
|
+
|
|
109
|
+
另外提供部分语义别名：
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
avatar.play('failed'); // 等同 failure
|
|
113
|
+
avatar.play('fail'); // 等同 failure
|
|
114
|
+
avatar.play('verify'); // 等同 inspect
|
|
115
|
+
avatar.play('review'); // 等同 inspect
|
|
116
|
+
avatar.play('blocked'); // 等同 angry
|
|
117
|
+
avatar.play('policy-blocked'); // 等同 angry
|
|
118
|
+
avatar.play('system-error'); // 等同 error
|
|
119
|
+
avatar.play('connection-error'); // 等同 error
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## 持续等待
|
|
123
|
+
|
|
124
|
+
在实际 Agent 流程中，请求发出后、结果返回前可以使用持续等待状态：
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
avatar.startWaiting();
|
|
128
|
+
|
|
129
|
+
// 收到回复或结果后停止。
|
|
130
|
+
avatar.stopWaiting();
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
调用其他动作时，也会自动中断当前等待状态。
|
|
134
|
+
|
|
135
|
+
## 鼠标跟随
|
|
136
|
+
|
|
137
|
+
鼠标 / 指针跟随默认开启，也可以通过程序控制：
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
avatar.setPointerFollow(false);
|
|
141
|
+
avatar.setPointerFollow(true);
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## 天线闪动
|
|
145
|
+
|
|
146
|
+
天线状态闪动默认关闭，可以为每个头像单独开启：
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
avatar.setAntennaFlash(true);
|
|
150
|
+
avatar.setAntennaFlash(false);
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## 头部圆角
|
|
154
|
+
|
|
155
|
+
头部可以在偏方与偏圆之间调整，同时继续使用相同的眼睛裁切和拖拽形变系统：
|
|
156
|
+
|
|
157
|
+
```js
|
|
158
|
+
avatar.setHeadRoundness(0); // 更方
|
|
159
|
+
avatar.setHeadRoundness(50); // 默认
|
|
160
|
+
avatar.setHeadRoundness(100); // 更圆
|
|
161
|
+
|
|
162
|
+
console.log(avatar.getHeadRoundness());
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
输入值会限制在 `0–100` 范围内。交互 Demo 默认使用三档预设，也可以解锁为连续调节。
|
|
166
|
+
|
|
167
|
+
圆角发生变化时会触发 `head-roundness-change` 事件：
|
|
168
|
+
|
|
169
|
+
```js
|
|
170
|
+
avatar.addEventListener('head-roundness-change', (event) => {
|
|
171
|
+
console.log(event.detail.value);
|
|
172
|
+
});
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## 状态事件
|
|
176
|
+
|
|
177
|
+
视觉状态发生变化时，组件会触发 `face-state` 事件：
|
|
178
|
+
|
|
179
|
+
```js
|
|
180
|
+
avatar.addEventListener('face-state', (event) => {
|
|
181
|
+
console.log(event.detail.state);
|
|
182
|
+
});
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
宿主应用可以据此同步界面状态、日志、Agent 工作流或无障碍反馈。
|
|
186
|
+
|
|
187
|
+
## 基础属性
|
|
188
|
+
|
|
189
|
+
```html
|
|
190
|
+
<agent-robot-avatar
|
|
191
|
+
size="160"
|
|
192
|
+
color="#08090b"
|
|
193
|
+
auto-sleep="30000">
|
|
194
|
+
</agent-robot-avatar>
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| 属性 | 说明 |
|
|
198
|
+
| --- | --- |
|
|
199
|
+
| `size` | 组件尺寸，单位为像素 |
|
|
200
|
+
| `color` | 头像主色 |
|
|
201
|
+
| `auto-sleep` | 无操作后自动进入睡眠的时间，单位为毫秒；`0` 表示关闭自动睡眠 |
|
|
202
|
+
|
|
203
|
+
以上属性均为可选。
|
|
204
|
+
|
|
205
|
+
## 默认行为
|
|
206
|
+
|
|
207
|
+
即使不主动调用任何 API，头像本身也具有轻微的生命感：
|
|
208
|
+
|
|
209
|
+
- 随机眨眼
|
|
210
|
+
- 轻微随机视线移动
|
|
211
|
+
- 鼠标靠近时自然跟随
|
|
212
|
+
- 头部带惯性的轻微运动
|
|
213
|
+
- 自然恢复默认待机
|
|
214
|
+
- 可选自动睡眠
|
|
215
|
+
|
|
216
|
+
## 拖拽交互
|
|
217
|
+
|
|
218
|
+
头像支持直接鼠标或指针拖拽。拖动时，外轮廓会围绕受力位置产生局部形变，而不是作为刚性整体移动。
|
|
219
|
+
|
|
220
|
+
- 大幅向外拉动：回弹完成后触发 `angry`
|
|
221
|
+
- 大幅向中心挤压：回弹完成后触发 `success`
|
|
222
|
+
- 小幅拖动：只产生形变，不触发表情
|
|
223
|
+
|
|
224
|
+
松开后头像会通过弹性回弹恢复原状。
|
|
225
|
+
|
|
226
|
+
## 交互 Demo
|
|
227
|
+
|
|
228
|
+
`demo/index.html` 是完整交互 Demo，包含：
|
|
229
|
+
|
|
230
|
+
- 全部公开表情状态
|
|
231
|
+
- 鼠标跟随
|
|
232
|
+
- 果冻式拖拽形变
|
|
233
|
+
- 等待状态生命周期
|
|
234
|
+
- 头部圆角三档预设与连续调节
|
|
235
|
+
- 颜色与行为控制
|
|
236
|
+
- 模拟 Agent 对话状态
|
|
237
|
+
|
|
238
|
+
完整交互 Demo 与所有 Demo 专用 JavaScript 已集中放入 `demo/`，不会进入可复用组件的 npm 运行时包。
|
|
239
|
+
|
|
240
|
+
## 项目结构
|
|
241
|
+
|
|
242
|
+
```text
|
|
243
|
+
agent-robot-avatar.js 正式组件入口
|
|
244
|
+
src/ 可复用组件运行时与表情模块
|
|
245
|
+
demo/ 完整交互 Demo 与 Demo 专用辅助脚本
|
|
246
|
+
examples/ 最小集成示例
|
|
247
|
+
assets/support/ 支持项目 / 支付二维码素材
|
|
248
|
+
docs/ 多语言文档
|
|
249
|
+
README.md 英文主文档
|
|
250
|
+
CHANGELOG.md 正式版本记录
|
|
251
|
+
CONTRIBUTING.md 贡献指南
|
|
252
|
+
package.json 包与分发元数据
|
|
253
|
+
LICENSE MIT License
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## 分发
|
|
257
|
+
|
|
258
|
+
软件包已以 `agent-robot-avatar` 名称发布到 npm，包含公开入口、TypeScript 类型声明、运行时模块、文档和支持项目素材。
|
|
259
|
+
|
|
260
|
+
npm 包只包含公开入口、TypeScript 类型声明、`src/` 运行时、文档和支持项目素材，不会把 Demo 专用文件一起发布。
|
|
261
|
+
|
|
262
|
+
## 兼容性
|
|
263
|
+
|
|
264
|
+
Agent Robot Avatar 面向支持 ES Modules、Custom Elements、SVG、Pointer Events 和 Web Animations API 的现代浏览器。
|
|
265
|
+
|
|
266
|
+
## 参与贡献
|
|
267
|
+
|
|
268
|
+
欢迎提交 Issue 和 Pull Request。提交修改前请先阅读 [`CONTRIBUTING.md`](../CONTRIBUTING.md)。
|
|
269
|
+
|
|
270
|
+
## 项目状态
|
|
271
|
+
|
|
272
|
+
v0.1.0 是首个公开版本线。当前刻意保持较小的公开 API，以便在未来 `1.0.0` 稳定性承诺之前继续谨慎演进。
|
|
273
|
+
|
|
274
|
+
Agent Robot Avatar 为独立开发的开源项目，不隶属于、代表或获得任何 AI 平台或品牌的官方背书。
|
|
275
|
+
|
|
276
|
+
## License
|
|
277
|
+
|
|
278
|
+
MIT License。详见 [`LICENSE`](../LICENSE)。
|
|
279
|
+
|
|
280
|
+
## 请我喝杯咖啡
|
|
281
|
+
|
|
282
|
+
如果这个项目对你有帮助，也可以请我喝杯咖啡。任选你方便的方式即可：
|
|
283
|
+
|
|
284
|
+
| Ko-fi | 支付宝 | 微信支付 |
|
|
285
|
+
| --- | --- | --- |
|
|
286
|
+
| <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> | <img src="../assets/support/alipay.png" alt="支付宝收款码" width="160"> | <img src="../assets/support/wechat-pay.png" alt="微信支付收款码" width="160"> |
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Agent Robot Avatar
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="../assets/readme/agent-robot-avatar-header.jpg" alt="Agent Robot Avatar">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
[English](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/README.md) | [简体中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-CN.md) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md) | [日本語](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ja.md) | [한국어](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ko.md) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Português](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.pt.md) | [Deutsch](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.de.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.md)
|
|
8
|
+
|
|
9
|
+
 [](../LICENSE) [](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [](https://ko-fi.com/P0E625WIOI)
|
|
10
|
+
|
|
11
|
+
      
|
|
12
|
+
|
|
13
|
+
一個輕量、富有表現力的機器人頭像 Web Component，可用於 AI Agent，也可用於其他需要互動回饋的應用。
|
|
14
|
+
|
|
15
|
+
Agent Robot Avatar 以 SVG 與原生 JavaScript 建構，不依賴第三方動畫框架。它作為原生自訂元素運作，並提供精簡 API 來控制表情、互動狀態、指標跟隨、等待回饋與頭部造型。
|
|
16
|
+
|
|
17
|
+
**目前公開版本：v0.2.0**
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
<img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 互動動畫展示" width="560">
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
## 主要特色
|
|
24
|
+
|
|
25
|
+
- 純 SVG + 原生 JavaScript
|
|
26
|
+
- 原生 Web Component
|
|
27
|
+
- 無第三方動畫框架依賴
|
|
28
|
+
- 自動眨眼與細微隨機視線活動
|
|
29
|
+
- 滑鼠 / 指標跟隨與帶慣性的頭部運動
|
|
30
|
+
- 局部果凍式拖曳形變與彈性回彈
|
|
31
|
+
- 可由程式觸發的 Agent 狀態與表情
|
|
32
|
+
- 明確區分等待、失敗、警告、審視、內容阻止與系統錯誤
|
|
33
|
+
- 可調整頭部圓角
|
|
34
|
+
- 懸浮式天線，可選擇啟用狀態閃動
|
|
35
|
+
- Demo 與可重複使用的元件本體分離
|
|
36
|
+
|
|
37
|
+
## 快速開始
|
|
38
|
+
|
|
39
|
+
直接使用倉庫原始碼時，請讓根目錄的 `agent-robot-avatar.js` 與 `src/` 一起使用，並載入公開入口：
|
|
40
|
+
|
|
41
|
+
```html
|
|
42
|
+
<script type="module" src="./agent-robot-avatar.js"></script>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
加入自訂元素：
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<agent-robot-avatar id="avatar"></agent-robot-avatar>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
元件載入後會自動進入預設待機狀態，不需要額外初始化。最小可執行範例位於 [`examples/basic.html`](../examples/basic.html)。
|
|
52
|
+
|
|
53
|
+
## 基本 API
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
const avatar = document.querySelector('#avatar');
|
|
57
|
+
|
|
58
|
+
avatar.play('success');
|
|
59
|
+
avatar.play('failure');
|
|
60
|
+
avatar.play('warning');
|
|
61
|
+
avatar.play('inspect');
|
|
62
|
+
avatar.play('angry');
|
|
63
|
+
avatar.play('error');
|
|
64
|
+
|
|
65
|
+
avatar.reset();
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## 狀態與表情
|
|
69
|
+
|
|
70
|
+
| 狀態 | API 名稱 | 典型用途 |
|
|
71
|
+
| --- | --- | --- |
|
|
72
|
+
| 預設待機 | `idle` | 正常待機 |
|
|
73
|
+
| 發呆 | `bored` | 長時間沒有任務或閒置 |
|
|
74
|
+
| 等待 | `waiting` | 請求已送出，等待結果 |
|
|
75
|
+
| 輸入中 | `input` | 使用者正在輸入 |
|
|
76
|
+
| 傳送 | `send` | 內容已送出 / 點頭回饋 |
|
|
77
|
+
| 成功 | `success` | 任務成功完成 |
|
|
78
|
+
| 失敗 | `failure` | 任務完成，但結果失敗 |
|
|
79
|
+
| 警告確認 | `warning` | 高風險或破壞性操作需要確認 |
|
|
80
|
+
| 審視 | `inspect` | 檢查、核對或驗證結果 |
|
|
81
|
+
| 內容阻止 | `angry` | 請求被阻止、不允許或無法繼續 |
|
|
82
|
+
| 系統錯誤 | `error` | 連線、服務或系統錯誤 |
|
|
83
|
+
| 驚訝 | `surprise` | 意外事件或結果 |
|
|
84
|
+
| 睡眠 | `sleep` | 進入睡眠 |
|
|
85
|
+
| 喚醒 | `wake` | 從睡眠恢復 |
|
|
86
|
+
|
|
87
|
+
`failure` 代表任務本身執行失敗；`error` 專門表示連線、服務或系統故障。`waiting` 是仍在等待已送出請求，而 `bored` 代表目前沒有活躍任務。
|
|
88
|
+
|
|
89
|
+
語意別名：
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
avatar.play('failed');
|
|
93
|
+
avatar.play('fail');
|
|
94
|
+
avatar.play('verify');
|
|
95
|
+
avatar.play('review');
|
|
96
|
+
avatar.play('blocked');
|
|
97
|
+
avatar.play('policy-blocked');
|
|
98
|
+
avatar.play('system-error');
|
|
99
|
+
avatar.play('connection-error');
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## 持續等待
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
avatar.startWaiting();
|
|
106
|
+
// 收到回覆或結果後停止。
|
|
107
|
+
avatar.stopWaiting();
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
呼叫其他動作也會中斷目前等待狀態。
|
|
111
|
+
|
|
112
|
+
## 滑鼠跟隨
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
avatar.setPointerFollow(false);
|
|
116
|
+
avatar.setPointerFollow(true);
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## 頭部圓角
|
|
120
|
+
|
|
121
|
+
```js
|
|
122
|
+
avatar.setHeadRoundness(0); // 更方
|
|
123
|
+
avatar.setHeadRoundness(50); // 預設
|
|
124
|
+
avatar.setHeadRoundness(100); // 更圓
|
|
125
|
+
|
|
126
|
+
console.log(avatar.getHeadRoundness());
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
值會限制在 `0–100`。變更時會觸發 `head-roundness-change`：
|
|
130
|
+
|
|
131
|
+
```js
|
|
132
|
+
avatar.addEventListener('head-roundness-change', (event) => {
|
|
133
|
+
console.log(event.detail.value);
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## 狀態事件
|
|
138
|
+
|
|
139
|
+
視覺狀態變更時會觸發 `face-state`：
|
|
140
|
+
|
|
141
|
+
```js
|
|
142
|
+
avatar.addEventListener('face-state', (event) => {
|
|
143
|
+
console.log(event.detail.state);
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## 基礎屬性
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<agent-robot-avatar
|
|
151
|
+
size="160"
|
|
152
|
+
color="#08090b"
|
|
153
|
+
auto-sleep="30000">
|
|
154
|
+
</agent-robot-avatar>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
| 屬性 | 說明 |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `size` | 元件尺寸（像素） |
|
|
160
|
+
| `color` | 頭像主色 |
|
|
161
|
+
| `auto-sleep` | 閒置多久後自動睡眠（毫秒）；`0` 關閉自動睡眠 |
|
|
162
|
+
|
|
163
|
+
## 預設行為
|
|
164
|
+
|
|
165
|
+
即使不呼叫 API，頭像也會隨機眨眼、輕微移動視線、在指標靠近時自然跟隨、產生帶慣性的頭部運動，並可選擇自動睡眠。
|
|
166
|
+
|
|
167
|
+
## 拖曳互動
|
|
168
|
+
|
|
169
|
+
拖曳時，頭部會在受力位置附近局部變形，而不是整體剛性移動。
|
|
170
|
+
|
|
171
|
+
- 強力向外拉：回彈後觸發 `angry`
|
|
172
|
+
- 強力向中心推：回彈後觸發 `success`
|
|
173
|
+
- 小幅拖曳：只變形，不觸發表情
|
|
174
|
+
|
|
175
|
+
## 互動 Demo
|
|
176
|
+
|
|
177
|
+
`demo/index.html` 包含全部公開表情、指標跟隨、果凍拖曳、等待生命週期、頭部圓角調整、顏色 / 行為控制，以及模擬 Agent 對話。Demo 專用 JavaScript 全部集中在 `demo/`，不會進入可重複使用的 npm runtime。
|
|
178
|
+
|
|
179
|
+
## 專案結構
|
|
180
|
+
|
|
181
|
+
```text
|
|
182
|
+
agent-robot-avatar.js 正式元件入口
|
|
183
|
+
src/ 可重複使用的元件 runtime 與表情模組
|
|
184
|
+
demo/ 完整互動 Demo 與 Demo 專用程式
|
|
185
|
+
examples/ 最小整合範例
|
|
186
|
+
assets/support/ 支持專案 / 付款 QR 圖片
|
|
187
|
+
docs/ 多語言文件
|
|
188
|
+
README.md 英文主文件
|
|
189
|
+
CHANGELOG.md 正式版本記錄
|
|
190
|
+
CONTRIBUTING.md 貢獻指南
|
|
191
|
+
package.json 套件與發佈資訊
|
|
192
|
+
LICENSE MIT License
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## 發佈與相容性
|
|
196
|
+
|
|
197
|
+
套件已以 `agent-robot-avatar` 名稱發佈至 npm，並內建動作、事件與公開方法的 TypeScript 型別宣告。元件面向支援 ES Modules、Custom Elements、SVG、Pointer Events 與 Web Animations API 的現代瀏覽器。
|
|
198
|
+
|
|
199
|
+
## 參與貢獻
|
|
200
|
+
|
|
201
|
+
歡迎 Issue 與 Pull Request。提交前請閱讀 [`CONTRIBUTING.md`](../CONTRIBUTING.md)。
|
|
202
|
+
|
|
203
|
+
## 專案狀態
|
|
204
|
+
|
|
205
|
+
v0.1.0 是第一個公開版本線。公開 API 目前刻意保持精簡，讓專案能在未來 `1.0.0` 穩定性承諾前持續謹慎演進。
|
|
206
|
+
|
|
207
|
+
Agent Robot Avatar 是獨立開發的開源專案，不隸屬、代表或獲得任何 AI 平台或品牌的官方背書。
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
MIT License。詳見 [`LICENSE`](../LICENSE)。
|
|
212
|
+
|
|
213
|
+
## 請我喝杯咖啡
|
|
214
|
+
|
|
215
|
+
如果這個專案對你有幫助，也可以請我喝杯咖啡。選擇你方便的方式即可：
|
|
216
|
+
|
|
217
|
+
| Ko-fi | 支付寶 | 微信支付 |
|
|
218
|
+
| --- | --- | --- |
|
|
219
|
+
| <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> | <img src="../assets/support/alipay.png" alt="支付寶收款碼" width="160"> | <img src="../assets/support/wechat-pay.png" alt="微信支付收款碼" width="160"> |
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
export type AgentRobotAvatarAction =
|
|
2
|
+
| 'idle'
|
|
3
|
+
| 'bored'
|
|
4
|
+
| 'waiting'
|
|
5
|
+
| 'wait'
|
|
6
|
+
| 'input'
|
|
7
|
+
| 'send'
|
|
8
|
+
| 'success'
|
|
9
|
+
| 'failure'
|
|
10
|
+
| 'failed'
|
|
11
|
+
| 'fail'
|
|
12
|
+
| 'warning'
|
|
13
|
+
| 'inspect'
|
|
14
|
+
| 'verify'
|
|
15
|
+
| 'review'
|
|
16
|
+
| 'angry'
|
|
17
|
+
| 'blocked'
|
|
18
|
+
| 'policy-blocked'
|
|
19
|
+
| 'error'
|
|
20
|
+
| 'system-error'
|
|
21
|
+
| 'connection-error'
|
|
22
|
+
| 'surprise'
|
|
23
|
+
| 'sleep'
|
|
24
|
+
| 'wake';
|
|
25
|
+
|
|
26
|
+
export type AgentRobotAvatarState =
|
|
27
|
+
| 'idle'
|
|
28
|
+
| 'happy'
|
|
29
|
+
| 'sad'
|
|
30
|
+
| 'angry'
|
|
31
|
+
| 'sleepy'
|
|
32
|
+
| 'input'
|
|
33
|
+
| 'sleep'
|
|
34
|
+
| 'surprise'
|
|
35
|
+
| 'waiting'
|
|
36
|
+
| 'warning'
|
|
37
|
+
| 'error'
|
|
38
|
+
| 'inspect'
|
|
39
|
+
| 'failure';
|
|
40
|
+
|
|
41
|
+
export interface AgentRobotAvatarEventMap extends HTMLElementEventMap {
|
|
42
|
+
'face-state': CustomEvent<{ state: AgentRobotAvatarState }>;
|
|
43
|
+
'head-roundness-change': CustomEvent<{ value: number; version: string }>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export declare class AgentRobotAvatar extends HTMLElement {
|
|
47
|
+
play(action: AgentRobotAvatarAction): this | Promise<void>;
|
|
48
|
+
reset(): this;
|
|
49
|
+
startWaiting(): Promise<this>;
|
|
50
|
+
stopWaiting(): this;
|
|
51
|
+
setPointerFollow(enabled?: boolean): this;
|
|
52
|
+
setAntennaFlash(enabled?: boolean): this;
|
|
53
|
+
setHeadRoundness(value?: number): this;
|
|
54
|
+
getHeadRoundness(): number;
|
|
55
|
+
noteActivity(wake?: boolean): void;
|
|
56
|
+
|
|
57
|
+
addEventListener<K extends keyof AgentRobotAvatarEventMap>(
|
|
58
|
+
type: K,
|
|
59
|
+
listener: (this: AgentRobotAvatar, event: AgentRobotAvatarEventMap[K]) => unknown,
|
|
60
|
+
options?: boolean | AddEventListenerOptions,
|
|
61
|
+
): void;
|
|
62
|
+
|
|
63
|
+
removeEventListener<K extends keyof AgentRobotAvatarEventMap>(
|
|
64
|
+
type: K,
|
|
65
|
+
listener: (this: AgentRobotAvatar, event: AgentRobotAvatarEventMap[K]) => unknown,
|
|
66
|
+
options?: boolean | EventListenerOptions,
|
|
67
|
+
): void;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export declare const VERSION: string;
|
|
71
|
+
|
|
72
|
+
export default AgentRobotAvatar;
|
|
73
|
+
|
|
74
|
+
declare global {
|
|
75
|
+
interface HTMLElementTagNameMap {
|
|
76
|
+
'agent-robot-avatar': AgentRobotAvatar;
|
|
77
|
+
}
|
|
78
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "agent-robot-avatar",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "A lightweight expressive robot avatar Web Component for AI agents and interactive applications.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./agent-robot-avatar.js",
|
|
7
|
+
"module": "./agent-robot-avatar.js",
|
|
8
|
+
"types": "./index.d.ts",
|
|
9
|
+
"browser": "./agent-robot-avatar.js",
|
|
10
|
+
"unpkg": "./agent-robot-avatar.js",
|
|
11
|
+
"jsdelivr": "./agent-robot-avatar.js",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./index.d.ts",
|
|
15
|
+
"import": "./agent-robot-avatar.js",
|
|
16
|
+
"default": "./agent-robot-avatar.js"
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"sideEffects": true,
|
|
20
|
+
"scripts": {
|
|
21
|
+
"dev": "node scripts/serve.mjs",
|
|
22
|
+
"check": "node scripts/check-source.mjs",
|
|
23
|
+
"test": "npm run check && npm run test:types && npm run test:release && npm run test:package && npm run test:browser",
|
|
24
|
+
"release:check": "npm test && npm publish --dry-run --ignore-scripts --tag latest",
|
|
25
|
+
"prepublishOnly": "npm test && node scripts/check-publish-tag.mjs",
|
|
26
|
+
"test:types": "tsc -p tsconfig.types.json",
|
|
27
|
+
"test:release": "node --test tests/release.test.mjs",
|
|
28
|
+
"test:package": "node --test tests/package.test.mjs",
|
|
29
|
+
"test:browser": "playwright test"
|
|
30
|
+
},
|
|
31
|
+
"files": [
|
|
32
|
+
"agent-robot-avatar.js",
|
|
33
|
+
"index.d.ts",
|
|
34
|
+
"src/",
|
|
35
|
+
"assets/support/",
|
|
36
|
+
"docs/",
|
|
37
|
+
"README.md",
|
|
38
|
+
"CHANGELOG.md",
|
|
39
|
+
"LICENSE"
|
|
40
|
+
],
|
|
41
|
+
"keywords": [
|
|
42
|
+
"ai",
|
|
43
|
+
"agent",
|
|
44
|
+
"robot",
|
|
45
|
+
"avatar",
|
|
46
|
+
"web-component",
|
|
47
|
+
"svg",
|
|
48
|
+
"svg-animation",
|
|
49
|
+
"animation",
|
|
50
|
+
"interactive",
|
|
51
|
+
"vanilla-javascript",
|
|
52
|
+
"ui"
|
|
53
|
+
],
|
|
54
|
+
"author": "CX ArtLab",
|
|
55
|
+
"license": "MIT",
|
|
56
|
+
"repository": {
|
|
57
|
+
"type": "git",
|
|
58
|
+
"url": "git+https://github.com/CX-ARTLab/agent-robot-avatar.git"
|
|
59
|
+
},
|
|
60
|
+
"homepage": "https://github.com/CX-ARTLab/agent-robot-avatar#readme",
|
|
61
|
+
"bugs": {
|
|
62
|
+
"url": "https://github.com/CX-ARTLab/agent-robot-avatar/issues"
|
|
63
|
+
},
|
|
64
|
+
"funding": {
|
|
65
|
+
"type": "individual",
|
|
66
|
+
"url": "https://ko-fi.com/P0E625WIOI"
|
|
67
|
+
},
|
|
68
|
+
"publishConfig": {
|
|
69
|
+
"access": "public",
|
|
70
|
+
"registry": "https://registry.npmjs.org/"
|
|
71
|
+
},
|
|
72
|
+
"devDependencies": {
|
|
73
|
+
"@playwright/test": "1.62.1",
|
|
74
|
+
"typescript": "7.0.2"
|
|
75
|
+
}
|
|
76
|
+
}
|