agent-robot-avatar 0.2.1 → 0.3.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.
Files changed (20) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +178 -30
  3. package/agent-robot-avatar.js +10 -1
  4. package/docs/README.de.md +8 -6
  5. package/docs/README.es.md +6 -8
  6. package/docs/README.fr.md +8 -8
  7. package/docs/README.ja.md +6 -8
  8. package/docs/README.ko.md +6 -8
  9. package/docs/README.pt.md +6 -8
  10. package/docs/README.zh-CN.md +194 -96
  11. package/docs/README.zh-TW.md +6 -8
  12. package/index.d.ts +30 -0
  13. package/package.json +1 -1
  14. package/src/agent-robot-avatar-antenna.js +24 -45
  15. package/src/agent-robot-avatar-core.js +39 -23
  16. package/src/agent-robot-avatar-geometry.js +40 -0
  17. package/src/agent-robot-avatar-head-roundness.js +2 -35
  18. package/src/agent-robot-avatar-inspect.js +37 -29
  19. package/src/agent-robot-avatar-runtime.js +875 -0
  20. package/src/agent-robot-avatar-version.js +1 -1
package/docs/README.ko.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
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
8
 
9
- ![버전](https://img.shields.io/badge/version-v0.2.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
9
+ ![버전](https://img.shields.io/badge/version-v0.3.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
10
10
 
11
11
  ![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
12
12
 
@@ -20,7 +20,7 @@ Agent Robot Avatar는 AG-UI 스타일 Agent 인터페이스의 시각적 피드
20
20
 
21
21
  Agent Robot Avatar는 SVG와 Vanilla JavaScript로만 구성되어 있으며 타사 애니메이션 프레임워크에 의존하지 않습니다. 네이티브 Custom Element로 동작하고 표정, 상호작용 상태, 포인터 추적, 대기 피드백, 머리 형태를 제어하는 간결한 API를 제공합니다.
22
22
 
23
- **현재 공개 버전: v0.2.1**
23
+ **현재 공개 버전: v0.3.1**
24
24
 
25
25
  <p align="center">
26
26
  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 인터랙티브 애니메이션 데모" width="560">
@@ -180,6 +180,8 @@ avatar.addEventListener('face-state', (event) => {
180
180
  - 강하게 중심으로 밀기: 복귀 후 `success`
181
181
  - 작은 드래그: 변형만 적용
182
182
 
183
+ 이 드래그 표정은 프로그램 제어 액션이 아바타를 사용하지 않는 idle 상태에서만 적용됩니다. `waiting`, `input`, `inspect` 등이 실행 중일 때는 변형은 유지되지만 드래그 표정은 억제되며 나중에 재생되지 않습니다. `pointercancel`은 형태만 복구하고 성공/화남 표정을 발생시키지 않습니다.
184
+
183
185
  ## 인터랙티브 Demo
184
186
 
185
187
  `demo/index.html`에는 모든 공개 상태, 포인터 추적, 젤리 드래그, waiting 라이프사이클, 머리 둥글기 조절, 색상 / 동작 설정, Agent 대화 시뮬레이션이 포함됩니다. Demo 전용 JavaScript는 `demo/`에 분리되어 재사용 가능한 npm runtime에는 포함되지 않습니다.
@@ -210,7 +212,7 @@ Issue와 Pull Request를 환영합니다. 제출 전 [`CONTRIBUTING.md`](../CONT
210
212
 
211
213
  ## 프로젝트 상태
212
214
 
213
- v0.2.1은 현재 공개 버전입니다. v0.1.0은 첫 공개 버전으로 계속 제공됩니다. 향후 `1.0.0` 안정성 약속 이전에 신중하게 발전시킬 수 있도록 공개 API를 의도적으로 작게 유지하고 있습니다.
215
+ v0.3.1은 현재 공개 버전입니다. v0.1.0은 첫 공개 버전으로 계속 제공됩니다. 향후 `1.0.0` 안정성 약속 이전에 신중하게 발전시킬 수 있도록 공개 API를 의도적으로 작게 유지하고 있습니다.
214
216
 
215
217
  Agent Robot Avatar는 독립적으로 개발된 오픈 소스 프로젝트이며 특정 AI 플랫폼이나 브랜드와 제휴하거나 공식 승인을 받은 프로젝트가 아닙니다.
216
218
 
@@ -220,8 +222,4 @@ MIT License. 자세한 내용은 [`LICENSE`](../LICENSE)를 참조하세요.
220
222
 
221
223
  ## 커피 한 잔으로 후원하기
222
224
 
223
- 프로젝트가 도움이 되었다면 편한 방법으로 후원할 수 있습니다.
224
-
225
- | Ko-fi | Alipay | WeChat Pay |
226
- | --- | --- | --- |
227
- | <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="Alipay QR code" width="160"> | <img src="../assets/support/wechat-pay.png" alt="WeChat Pay QR code" width="160"> |
225
+ <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>
package/docs/README.pt.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
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
8
 
9
- ![Versão](https://img.shields.io/badge/version-v0.2.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
9
+ ![Versão](https://img.shields.io/badge/version-v0.3.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
10
10
 
11
11
  ![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
12
12
 
@@ -20,7 +20,7 @@ Agent Robot Avatar também pode funcionar como uma camada de feedback visual par
20
20
 
21
21
  Agent Robot Avatar é construído com SVG e JavaScript puro, sem dependência de frameworks de animação de terceiros. Funciona como um Custom Element nativo e oferece uma API compacta para expressões, estados de interação, seguimento do ponteiro, feedback de espera e formato da cabeça.
22
22
 
23
- **Versão pública atual: v0.2.1**
23
+ **Versão pública atual: v0.3.1**
24
24
 
25
25
  <p align="center">
26
26
  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Demonstração animada interativa do Agent Robot Avatar" width="560">
@@ -180,6 +180,8 @@ Ao arrastar, a cabeça se deforma localmente ao redor do ponto de interação, e
180
180
  - Empurrão forte para o centro: ativa `success` após retornar
181
181
  - Arraste pequeno: apenas deformação
182
182
 
183
+ Essas expressões de arraste só se aplicam em idle quando nenhuma ação programática controla o avatar. Durante `waiting`, `input`, `inspect` e outras ações ativas, a deformação é preservada, mas a expressão de arraste é suprimida e não é reproduzida depois. `pointercancel` restaura apenas a forma, sem acionar success ou angry.
184
+
183
185
  ## Demo interativo
184
186
 
185
187
  `demo/index.html` inclui todos os estados públicos, seguimento do ponteiro, arraste tipo gelatina, ciclo de waiting, ajuste do arredondamento, controles de cor e comportamento e simulação de conversa com Agent. O JavaScript exclusivo do Demo fica isolado em `demo/` e não faz parte do runtime reutilizável do npm.
@@ -210,7 +212,7 @@ Issues e Pull Requests são bem-vindos. Leia [`CONTRIBUTING.md`](../CONTRIBUTING
210
212
 
211
213
  ## Status do projeto
212
214
 
213
- v0.2.1 é a versão pública atual. v0.1.0 continua disponível como a primeira versão pública. A API pública é mantida deliberadamente pequena para evoluir com cuidado antes de um futuro compromisso de estabilidade `1.0.0`.
215
+ v0.3.1 é a versão pública atual. v0.1.0 continua disponível como a primeira versão pública. A API pública é mantida deliberadamente pequena para evoluir com cuidado antes de um futuro compromisso de estabilidade `1.0.0`.
214
216
 
215
217
  Agent Robot Avatar é um projeto independente de código aberto e não é afiliado, endossado nem representa nenhuma plataforma ou marca de IA.
216
218
 
@@ -220,8 +222,4 @@ MIT License. Consulte [`LICENSE`](../LICENSE).
220
222
 
221
223
  ## Pague-me um café
222
224
 
223
- Se este projeto for útil, você pode apoiá-lo pelo método mais conveniente:
224
-
225
- | Ko-fi | Alipay | WeChat Pay |
226
- | --- | --- | --- |
227
- | <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="QR code do Alipay" width="160"> | <img src="../assets/support/wechat-pay.png" alt="QR code do WeChat Pay" width="160"> |
225
+ <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>
package/docs/README.zh-CN.md CHANGED
@@ -6,21 +6,17 @@
6
6
 
7
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
8
 
9
- ![Version](https://img.shields.io/badge/version-v0.2.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
9
+ ![Version](https://img.shields.io/badge/version-v0.3.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
10
10
 
11
11
  ![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
12
12
 
13
13
  一个轻量、富有表现力的机器人头像 Web Component，可用于 AI Agent，也可用于其他需要交互反馈的应用。
14
14
 
15
- 适用于 AI 助手和 Agent 交互界面，包括与 ChatGPT、Claude、Codex、Cursor、Grok Bot、Gemini CLI 和 OpenCode 类似的产品与使用场景。
15
+ 适用于 AI 助手和 Agent 交互界面，也可用于桌面宠物、数字吉祥物、聊天机器人头像以及其他互动角色体验。
16
16
 
17
- 它也可用于桌面宠物、虚拟宠物、桌面伙伴、数字吉祥物、聊天机器人头像以及其他互动角色体验。
17
+ Agent Robot Avatar 基于 SVG 与原生 JavaScript 构建，不依赖第三方动画框架，作为原生自定义元素工作，并提供尽量精简的公开 API。
18
18
 
19
- Agent Robot Avatar 也可作为 AG-UI 类 Agent 界面的视觉反馈层。
20
-
21
- Agent Robot Avatar 基于 SVG 与原生 JavaScript 构建，不依赖第三方动画框架。它作为原生自定义元素工作，并提供一组尽量精简的 API，用于控制表情、交互状态、鼠标跟随、等待反馈和头部造型。
22
-
23
- **当前公开版本：v0.2.1**
19
+ **当前公开版本：v0.3.1**
24
20
 
25
21
  <p align="center">
26
22
  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 交互动画演示" width="560">
@@ -34,35 +30,29 @@ Agent Robot Avatar 基于 SVG 与原生 JavaScript 构建，不依赖第三方
34
30
 
35
31
  - 纯 SVG + 原生 JavaScript
36
32
  - 原生 Web Component
37
- - 无第三方动画框架依赖
38
- - 自动眨眼与轻微随机视线活动
39
- - 鼠标 / 指针跟随与带惯性的头部运动
33
+ - 零运行时第三方依赖
34
+ - 自动眨眼、视线与头部跟随
40
35
  - 局部果冻式拖拽形变与弹性回弹
41
- - 可由程序主动触发的 Agent 状态与表情
42
- - 明确区分等待、失败、警告、审视、内容阻止与系统错误
36
+ - 程序控制的 Agent 状态与表情
37
+ - 独立的 `action-state` 语义动作生命周期事件
38
+ - `wake-on` 睡眠唤醒策略
39
+ - `motion` 减少动态效果支持
40
+ - 不可见时暂停持续绘制
43
41
  - 可调整头部圆角
44
- - 悬浮式天线，并支持可选状态闪动
45
- - Demo 界面与可复用组件本体分离
42
+ - 悬浮式天线与可选状态闪动
46
43
 
47
44
  ## 快速开始
48
45
 
49
- 直接使用仓库源码时，请保持根目录的 `agent-robot-avatar.js` 与 `src/` 目录一起使用，然后加载公开入口：
46
+ 直接使用仓库源码时，请保持根目录的 `agent-robot-avatar.js` 与 `src/` 目录一起使用：
50
47
 
51
48
  ```html
52
49
  <script type="module" src="./agent-robot-avatar.js"></script>
53
- ```
54
-
55
- 在页面中加入：
56
-
57
- ```html
58
50
  <agent-robot-avatar id="avatar"></agent-robot-avatar>
59
51
  ```
60
52
 
61
- 组件加载后会自动进入默认待机状态，不需要额外初始化。
62
-
63
- 最小可运行示例位于 [`examples/basic.html`](../examples/basic.html)。
53
+ 最小示例位于 [`examples/basic.html`](../examples/basic.html)，无障碍语义状态示例位于 [`examples/accessibility.html`](../examples/accessibility.html)。
64
54
 
65
- 使用打包工具的项目可以通过 npm 安装和引入：
55
+ 通过 npm：
66
56
 
67
57
  ```bash
68
58
  npm install agent-robot-avatar
@@ -72,12 +62,10 @@ npm install agent-robot-avatar
72
62
  import 'agent-robot-avatar';
73
63
  ```
74
64
 
75
- npm 包内置 TypeScript 类型声明，覆盖动作名称、事件和公开方法，无需另外安装类型包。
65
+ npm 包内置 TypeScript 类型声明。
76
66
 
77
67
  ## 基本 API
78
68
 
79
- 统一通过 `play()` 触发表情或状态：
80
-
81
69
  ```js
82
70
  const avatar = document.querySelector('#avatar');
83
71
 
@@ -95,7 +83,9 @@ avatar.play('error');
95
83
  avatar.reset();
96
84
  ```
97
85
 
98
- `reset()` 会取消待完成的动画并恢复待机。移除元素也会取消计时器、动画、等待和拖拽反馈，清理过程不会触发 `face-state` 事件。重新挂载后从待机开始，并保留外观和行为设置。被取消的动画 Promise 会正常完成。
86
+ `reset()` 会统一取消当前程序动作、待完成计时、头部动画、拖拽/回弹和尚未触发的拖拽表情，然后回到 `idle`。被取消的动画 Promise 仍按原约定正常结束，不会因为取消而产生未处理拒绝。移除组件时会执行同类内部清理，但不会额外发送用于清理的 `face-state` 或 `action-state` 通知；同时会释放该实例的媒体偏好监听和观察器，清理过程不会反向重启渲染。重新挂载后从 `idle` 开始、保留配置，并只初始化一次连接期运行资源。
87
+
88
+ 真正开始的新动作会替换旧动作；旧动作不能在之后恢复并覆盖新动作。未知动作会在破坏性清理前抛错。已经醒着时调用 `wake`、已经处于持续输入时再次调用 `input` 等无操作调用不会破坏当前动作，也不会产生虚假的语义生命周期事件。
99
89
 
100
90
  ## 状态与表情
101
91
 
@@ -107,64 +97,183 @@ avatar.reset();
107
97
  | 输入中 | `input` | 用户正在输入 |
108
98
  | 发送 | `send` | 内容已发送 / 点头反馈 |
109
99
  | 成功 | `success` | 任务成功完成 |
110
- | 失败 | `failure` | 任务执行完成，但结果失败 |
111
- | 警告确认 | `warning` | 高风险、覆盖、删除等操作需要再次确认 |
100
+ | 失败 | `failure` | 任务完成但结果失败 |
101
+ | 警告确认 | `warning` | 高风险操作需要再次确认 |
112
102
  | 审视 | `inspect` | 检查、核对或验证结果 |
113
103
  | 内容阻止 | `blocked` | 请求被阻止、不允许执行或无法继续 |
114
104
  | 系统错误 | `error` | 网络、服务或系统本身发生错误 |
115
105
  | 惊讶 | `surprise` | 出现意外事件或结果 |
116
- | 睡眠 | `sleep` | 进入睡眠状态 |
117
- | 唤醒 | `wake` | 从睡眠状态恢复 |
106
+ | 睡眠 | `sleep` | 组件进入睡眠姿态 |
107
+ | 唤醒 | `wake` | 从睡眠姿态恢复 |
118
108
 
119
- 这些状态有意区分“任务结果”和“系统状态”。例如，`failure` 表示任务本身执行失败，而 `error` 专门表示连接、服务或系统故障；`waiting` 表示正在等待一个已经发出的请求，而 `bored` 表示当前没有活跃任务。
109
+ `sleep` 只描述头像组件自身的状态，不表示真实 Agent 已离线。
120
110
 
121
- 另外提供部分语义别名：
111
+ 语义别名：
122
112
 
123
113
  ```js
124
- avatar.play('failed'); // 等同 failure
125
- avatar.play('fail'); // 等同 failure
126
- avatar.play('verify'); // 等同 inspect
127
- avatar.play('review'); // 等同 inspect
128
- avatar.play('angry'); // 与 blocked 使用相同表情
129
- avatar.play('policy-blocked'); // 等同 blocked
130
- avatar.play('system-error'); // 等同 error
131
- avatar.play('connection-error'); // 等同 error
114
+ avatar.play('failed'); // failure
115
+ avatar.play('fail'); // failure
116
+ avatar.play('verify'); // inspect
117
+ avatar.play('review'); // inspect
118
+ avatar.play('angry'); // 与 blocked 使用相同视觉表情
119
+ avatar.play('policy-blocked'); // blocked
120
+ avatar.play('system-error'); // error
121
+ avatar.play('connection-error'); // error
132
122
  ```
133
123
 
134
124
  ## 持续等待
135
125
 
136
- 在实际 Agent 流程中，请求发出后、结果返回前可以使用持续等待状态：
137
-
138
126
  ```js
139
127
  avatar.startWaiting();
140
128
 
141
- // 收到回复或结果后停止。
129
+ // 请求在没有被其他动作替换的情况下结束时：
142
130
  avatar.stopWaiting();
143
131
  ```
144
132
 
145
- 调用其他动作时，也会自动中断当前等待状态。
133
+ `startWaiting()` 会一直保持到 `stopWaiting()`、`reset()` 或新的程序动作将其替换。当前确实处于 waiting 时，`stopWaiting()` 对 waiting 的语义生命周期是正常 `end`。为保持既有行为，如果在其他活跃程序动作期间调用 `stopWaiting()`，头像仍会回到 `idle`，但该动作现在会且只会记录一次 `cancel`；没有活跃动作时不会制造虚假的终止事件。
134
+
135
+ 等待、输入或其他尚未结束的程序动作期间仍可以拖拽产生形变，但拖拽表情不会覆盖程序动作；被抑制的拖拽表情会直接丢弃，不会在动作结束后补播。
136
+
137
+ 典型请求生命周期：
138
+
139
+ ```js
140
+ avatar.startWaiting();
141
+ try {
142
+ const result = await runAgentRequest();
143
+ await avatar.play(result.ok ? 'success' : 'failure');
144
+ } catch (error) {
145
+ await avatar.play('error');
146
+ }
147
+ ```
148
+
149
+ `error` 动画播放完并回到 `idle`，只表示头像动画结束，不表示真实连接或业务错误已经解决。真实请求状态始终由宿主应用决定。
150
+
151
+ ## `action-state` 语义动作事件
152
+
153
+ 现有 `face-state` 保留兼容，它描述视觉状态，可能出现 `happy`、`sad` 等视觉词，不建议直接拿它判断真实任务结果。
154
+
155
+ 新增 `action-state`：
156
+
157
+ ```js
158
+ avatar.addEventListener('action-state', (event) => {
159
+ const { action, phase, source } = event.detail;
160
+ console.log(action, phase, source);
161
+ });
162
+ ```
163
+
164
+ 约定：
165
+
166
+ - `action`：规范化后的动作名；`failed` / `fail` → `failure`，`verify` / `review` → `inspect`。
167
+ - `phase`：`start`，之后且仅之后一个 `end` 或 `cancel`。
168
+ - `source`：`api`、`interaction`、`automatic`。
169
+ - 持续 waiting / input 不会因为单次视觉循环完成而产生 `end`。
170
+ - `stopWaiting()` 在 waiting 活跃时正常记录 `end`；若它把其他活跃程序动作重置为 idle，则该动作记录 `cancel`。
171
+ - 无操作调用不产生虚假事件。
172
+ - 普通拖拽反馈使用 `action: "reaction"`、`source: "interaction"`，不会被误认为 API 发出的任务成功/失败。
173
+ - 事件会冒泡，并设置为 `composed`，可跨越组件的 Shadow DOM 边界监听。
174
+ - 卸载只清理内部工作，不额外制造宿主播报事件。
175
+
176
+ ## 无障碍接入
146
177
 
147
- ## 鼠标跟随
178
+ 建议宿主根据 `action-state` 将程序动作映射为本地化文字，并使用普通的 `role="status"`：
148
179
 
149
- 鼠标 / 指针跟随默认开启，也可以通过程序控制：
180
+ ```html
181
+ <div id="agent-status" role="status" aria-live="polite"></div>
182
+ ```
183
+
184
+ ```js
185
+ const status = document.querySelector('#agent-status');
186
+ const messages = {
187
+ waiting: '正在处理…',
188
+ failure: '任务失败。',
189
+ error: '连接异常。',
190
+ };
191
+
192
+ avatar.addEventListener('action-state', ({ detail }) => {
193
+ if (detail.source === 'interaction') return;
194
+ if (detail.phase === 'start' && messages[detail.action]) {
195
+ status.textContent = messages[detail.action];
196
+ }
197
+ });
198
+ ```
199
+
200
+ 不要播报眨眼、视线变化或普通拖拽反应；也不要默认把所有错误都做成打断式警报。如果宿主本身已经播报同一状态，可以把头像视为装饰，避免重复通知。
201
+
202
+ 完整示例见 [`examples/accessibility.html`](../examples/accessibility.html)，其中覆盖等待、成功、失败、连接错误、宿主取消、新请求替换旧请求，以及旧请求迟到结果不能覆盖新状态；无障碍文字由宿主请求状态驱动，不重复播报底层表情变化。
203
+
204
+ ## 睡眠唤醒策略
205
+
206
+ 新增属性：
207
+
208
+ ```html
209
+ <agent-robot-avatar wake-on="manual"></agent-robot-avatar>
210
+ ```
211
+
212
+ | 值 | 行为 |
213
+ | --- | --- |
214
+ | `activity` | 默认值；保留原行为，页面指针/键盘活动可以自动唤醒头像。 |
215
+ | `interaction` | 只有直接与这个头像交互时自动唤醒；页面其他区域活动不唤醒。 |
216
+ | `manual` | 页面活动和头像交互都不会自动唤醒，由宿主显式控制。 |
217
+
218
+ 显式调用仍保持显式语义：`avatar.play('wake')` 在所有模式下都可唤醒；`avatar.noteActivity()` 默认记录活动并唤醒，即使宿主是在真实 `keydown`、`pointerdown` 或 `click` 事件处理函数中调用它也一样。`noteActivity(false)` 只记录活动、不唤醒。页面环境活动与头像直接交互的自动唤醒会走独立来源并继续遵守 `wake-on`；自动唤醒的 `action-state` source 为 `automatic`，宿主显式唤醒仍为 `api`。其他程序动作可以按照动作语义离开睡眠；`reset()` 始终回到 `idle`。不同实例可以使用不同策略。
219
+
220
+ ## 减少动态效果
221
+
222
+ 新增：
223
+
224
+ ```html
225
+ <agent-robot-avatar motion="auto"></agent-robot-avatar>
226
+ ```
227
+
228
+ | 值 | 行为 |
229
+ | --- | --- |
230
+ | `auto` | 默认；遵循系统 `prefers-reduced-motion`，并响应运行期间的偏好变化。 |
231
+ | `reduce` | 保留可辨认的静态状态，减少持续、弹性和闪烁类动画。 |
232
+ | `full` | 始终使用普通动画，不受系统减少动态效果偏好影响。 |
233
+
234
+ reduce 模式会简化等待转圈、待机游走/眨眼、惯性跟随、弹性回弹、天线弹簧和闪烁等装饰动态，但 waiting / input 等语义生命周期仍持续存在，直到宿主结束或替换。自动睡眠使用独立、可取消的计时调度，不依赖持续绘制，因此 reduce 已暂停绘制时仍能按 `auto-sleep` 进入睡眠；用户活动和运行时修改超时会重新调度，waiting/input 不会被自动睡眠覆盖。影响画面的静态状态会先提交最终 SVG 再暂停，包括最终闭眼的 sleep 姿态。切换 motion 不会恢复已经被取消的旧动作，也不会改变 `action-state` 的语义。
235
+
236
+ ## 鼠标 / 指针跟随
150
237
 
151
238
  ```js
152
239
  avatar.setPointerFollow(false);
153
240
  avatar.setPointerFollow(true);
154
241
  ```
155
242
 
156
- ## 天线闪动
243
+ 高频指针更新会合并为每个动画帧最多处理最新位置一次，普通模式下的视线跟随保持不变。
244
+
245
+ ## 移动端拖拽
157
246
 
158
- 天线状态闪动默认关闭，可以为每个头像单独开启：
247
+ 头像交互区域使用 `touch-action: pinch-zoom`：单指移动交给头像拖拽逻辑，同时保留双指缩放能力；从头像外部开始的页面滚动仍按页面正常手势处理。
248
+
249
+ `pointercancel`、指针捕获丢失、reset、动作替换或卸载都会恢复形状，并且不会把手势取消误判成 `success` / `angry`。
250
+
251
+ ## 天线闪动
159
252
 
160
253
  ```js
161
254
  avatar.setAntennaFlash(true);
162
255
  avatar.setAntennaFlash(false);
163
256
  ```
164
257
 
165
- ## 头部圆角
258
+ 状态闪动默认关闭；reduce 模式会停止不必要的持续闪烁。
259
+
260
+ ## 审视表情配置
166
261
 
167
- 头部可以在偏方与偏圆之间调整，同时继续使用相同的眼睛裁切和拖拽形变系统：
262
+ 可以在加载组件前配置：
263
+
264
+ ```html
265
+ <script>
266
+ window.AgentRobotAvatarInspectConfig = {
267
+ aperture: 24,
268
+ scanOffset: 12,
269
+ };
270
+ </script>
271
+ <script type="module" src="./agent-robot-avatar.js"></script>
272
+ ```
273
+
274
+ 加载前已经提供的有效值会被保留，只对缺失或无效项补默认值。配置通过 `Number(...)` 转换并要求有限值；`aperture` 限制在 `6–40`，`scanOffset` 限制在 `0–24`，时间参数限制在对应的 `0/40–2400 ms` 范围。加载后仍可修改同一个 `window.AgentRobotAvatarInspectConfig` 对象，每次开始 inspect 时会再次规范化。默认配置的视觉效果保持不变。
275
+
276
+ ## 头部圆角
168
277
 
169
278
  ```js
170
279
  avatar.setHeadRoundness(0); // 更方
@@ -174,9 +283,9 @@ avatar.setHeadRoundness(100); // 更圆
174
283
  console.log(avatar.getHeadRoundness());
175
284
  ```
176
285
 
177
- 输入值会限制在 `0–100` 范围内。交互 Demo 默认使用三档预设，也可以解锁为连续调节。
286
+ 输入值限制在 `0–100`。天线模块和圆角模块现在复用同一套头部扁平化几何计算，避免默认形状出现实现偏差。
178
287
 
179
- 圆角发生变化时会触发 `head-roundness-change` 事件：
288
+ `head-roundness-change`：
180
289
 
181
290
  ```js
182
291
  avatar.addEventListener('head-roundness-change', (event) => {
@@ -184,9 +293,7 @@ avatar.addEventListener('head-roundness-change', (event) => {
184
293
  });
185
294
  ```
186
295
 
187
- ## 状态事件
188
-
189
- 视觉状态发生变化时，组件会触发 `face-state` 事件：
296
+ ## `face-state` 视觉事件
190
297
 
191
298
  ```js
192
299
  avatar.addEventListener('face-state', (event) => {
@@ -194,60 +301,51 @@ avatar.addEventListener('face-state', (event) => {
194
301
  });
195
302
  ```
196
303
 
197
- 宿主应用可以据此同步界面状态、日志、Agent 工作流或无障碍反馈。
304
+ 该事件继续用于视觉同步和旧接入；涉及真实 Agent 生命周期和无障碍播报时优先使用 `action-state`。
198
305
 
199
306
  ## 基础属性
200
307
 
201
308
  ```html
202
309
  <agent-robot-avatar
203
- size="160"
310
+ size="160px"
204
311
  color="#08090b"
205
- auto-sleep="30000">
312
+ auto-sleep="30000"
313
+ wake-on="activity"
314
+ motion="auto">
206
315
  </agent-robot-avatar>
207
316
  ```
208
317
 
209
318
  | 属性 | 说明 |
210
319
  | --- | --- |
211
- | `size` | 组件尺寸，单位为像素 |
212
- | `color` | 头像主色 |
213
- | `auto-sleep` | 无操作后自动进入睡眠的时间，单位为毫秒；`0` 表示关闭自动睡眠 |
320
+ | `size` | 正像素尺寸；支持 `140` 和 `140px`。不支持的单位、非法字符串、0、负数和非有限值统一回退到 `112px`。 |
321
+ | `color` | 头像主色。 |
322
+ | `auto-sleep` | 无操作后自动睡眠的毫秒数；`0` 关闭。 |
323
+ | `wake-on` | `activity`（默认）、`interaction`、`manual`。 |
324
+ | `motion` | `auto`（默认）、`reduce`、`full`。 |
214
325
 
215
- 以上属性均为可选。
326
+ 动态修改尺寸后，拖拽坐标和指针跟随会使用当前实际布局尺寸。
216
327
 
217
328
  ## 默认行为
218
329
 
219
- 即使不主动调用任何 API，头像本身也具有轻微的生命感：
220
-
221
- - 随机眨眼
222
- - 轻微随机视线移动
223
- - 鼠标靠近时自然跟随
224
- - 头部带惯性的轻微运动
225
- - 自然恢复默认待机
226
- - 可选自动睡眠
330
+ 普通模式下继续保留随机眨眼、轻微视线活动、指针跟随、头部惯性和自然回待机等既有风格。开启 reduce 后会简化这些装饰动作。
227
331
 
228
332
  ## 拖拽交互
229
333
 
230
- 头像支持直接鼠标或指针拖拽。拖动时，外轮廓会围绕受力位置产生局部形变，而不是作为刚性整体移动。
231
-
232
- - 大幅向外拉动：回弹完成后触发 `angry`
233
- - 大幅向中心挤压：回弹完成后触发 `success`
234
- - 小幅拖动：只产生形变，不触发表情
334
+ - 空闲状态大幅向外拉：恢复后触发 `angry` 视觉反馈
335
+ - 空闲状态大幅向中心挤压：恢复后触发 `success` 视觉反馈
336
+ - 小幅拖动：只产生形变
337
+ - 程序动作活跃时：可以形变，但拖拽表情不覆盖程序动作
338
+ - reset / 新动作 / pointercancel / 丢失捕获 / 卸载：统一取消旧拖拽后续反应
235
339
 
236
- 松开后头像会通过弹性回弹恢复原状。
340
+ ## 不可见暂停与性能
237
341
 
238
- ## 交互 Demo
342
+ 组件在自身或父容器没有可见布局区域、或离开视口后暂停持续帧绘制；重新可见时按当前有效状态恢复，不补播已经失效的动作。有限动作的计时和 Promise 不依赖持续绘制，因此不会因为不可见而无限挂起。
239
343
 
240
- `demo/index.html` 是完整交互 Demo，包含：
344
+ 指针移动按动画帧合并，只处理每帧最新位置。现有页面隐藏和稳定 sleep 暂停机制继续保留；实例卸载时会清理观察器与媒体查询监听。
241
345
 
242
- - 全部公开表情状态
243
- - 鼠标跟随
244
- - 果冻式拖拽形变
245
- - 等待状态生命周期
246
- - 头部圆角三档预设与连续调节
247
- - 颜色与行为控制
248
- - 模拟 Agent 对话状态
346
+ ## 交互 Demo
249
347
 
250
- 完整交互 Demo 与所有 Demo 专用 JavaScript 已集中放入 `demo/`，不会进入可复用组件的 npm 运行时包。
348
+ `demo/index.html` 是完整交互 Demo，包含全部公开表情、指针跟随、拖拽形变、等待生命周期、圆角、颜色与模拟 Agent 对话状态。Demo 专用 JavaScript 与 npm 运行时保持分离。
251
349
 
252
350
  ## 项目结构
253
351
 
@@ -255,7 +353,7 @@ avatar.addEventListener('face-state', (event) => {
255
353
  agent-robot-avatar.js 正式组件入口
256
354
  src/ 可复用组件运行时与表情模块
257
355
  demo/ 完整交互 Demo 与 Demo 专用辅助脚本
258
- examples/ 最小集成示例
356
+ examples/ 最小集成与无障碍示例
259
357
  assets/support/ 支持项目 / 支付二维码素材
260
358
  docs/ 多语言文档
261
359
  README.md 英文主文档
@@ -267,13 +365,13 @@ LICENSE MIT License
267
365
 
268
366
  ## 分发
269
367
 
270
- 软件包已以 `agent-robot-avatar` 名称发布到 npm，包含公开入口、TypeScript 类型声明、运行时模块、文档和支持项目素材。
368
+ 软件包以 `agent-robot-avatar` 名称发布到 npm。npm 包包含公开入口、TypeScript 类型声明、`src/` 运行时、文档和支持项目素材；Demo 专用文件和测试文件不会进入运行时包。
271
369
 
272
- npm 包只包含公开入口、TypeScript 类型声明、`src/` 运行时、文档和支持项目素材，不会把 Demo 专用文件一起发布。
370
+ ## 兼容性与验证
273
371
 
274
- ## 兼容性
372
+ 面向支持 ES Modules、Custom Elements、SVG、Pointer Events、Web Animations API、`IntersectionObserver`、`ResizeObserver` 和 `matchMedia` 的现代浏览器。
275
373
 
276
- Agent Robot Avatar 面向支持 ES Modules、Custom Elements、SVG、Pointer Events 和 Web Animations API 的现代浏览器。
374
+ 自动浏览器测试覆盖 Chromium、Firefox 和 WebKit；移动端拖拽取消另外使用 Chromium 可信触摸模拟验证。真实手机是否验证以对应 PR / 发布说明为准。
277
375
 
278
376
  ## 参与贡献
279
377
 
@@ -281,7 +379,7 @@ Agent Robot Avatar 面向支持 ES Modules、Custom Elements、SVG、Pointer Eve
281
379
 
282
380
  ## 项目状态
283
381
 
284
- v0.2.1 是当前公开版本。v0.1.0 作为首个公开版本继续保留。当前刻意保持较小的公开 API，以便在未来 `1.0.0` 稳定性承诺之前继续谨慎演进。
382
+ v0.3.1 是当前公开版本。当前刻意保持较小的公开 API，以便在未来 `1.0.0` 稳定性承诺之前继续谨慎演进。
285
383
 
286
384
  Agent Robot Avatar 为独立开发的开源项目，不隶属于、代表或获得任何 AI 平台或品牌的官方背书。
287
385
 
@@ -291,7 +389,7 @@ MIT License。详见 [`LICENSE`](../LICENSE)。
291
389
 
292
390
  ## 请我喝杯咖啡
293
391
 
294
- 如果这个项目对你有帮助，也可以请我喝杯咖啡。任选你方便的方式即可：
392
+ 如果这个项目对你有帮助，也可以请我喝杯咖啡：
295
393
 
296
394
  | Ko-fi | 支付宝 | 微信支付 |
297
395
  | --- | --- | --- |
package/docs/README.zh-TW.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
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
8
 
9
- ![Version](https://img.shields.io/badge/version-v0.2.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
9
+ ![Version](https://img.shields.io/badge/version-v0.3.1-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
10
10
 
11
11
  ![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
12
12
 
@@ -20,7 +20,7 @@ Agent Robot Avatar 也可作為 AG-UI 類 Agent 介面的視覺回饋層。
20
20
 
21
21
  Agent Robot Avatar 以 SVG 與原生 JavaScript 建構，不依賴第三方動畫框架。它作為原生自訂元素運作，並提供精簡 API 來控制表情、互動狀態、指標跟隨、等待回饋與頭部造型。
22
22
 
23
- **目前公開版本：v0.2.1**
23
+ **目前公開版本：v0.3.1**
24
24
 
25
25
  <p align="center">
26
26
  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 互動動畫展示" width="560">
@@ -182,6 +182,8 @@ avatar.addEventListener('face-state', (event) => {
182
182
  - 強力向中心推：回彈後觸發 `success`
183
183
  - 小幅拖曳：只變形，不觸發表情
184
184
 
185
+ 上述拖曳表情只會在沒有程式控制動作佔用頭像的 idle 狀態生效。`waiting`、`input`、`inspect` 等動作執行期間仍保留拖曳形變，但拖曳表情會被抑制且不會延後補播；`pointercancel` 只恢復形狀，不會觸發成功或生氣表情。
186
+
185
187
  ## 互動 Demo
186
188
 
187
189
  `demo/index.html` 包含全部公開表情、指標跟隨、果凍拖曳、等待生命週期、頭部圓角調整、顏色 / 行為控制，以及模擬 Agent 對話。Demo 專用 JavaScript 全部集中在 `demo/`，不會進入可重複使用的 npm runtime。
@@ -212,7 +214,7 @@ LICENSE MIT License
212
214
 
213
215
  ## 專案狀態
214
216
 
215
- v0.2.1 是目前的公開版本。v0.1.0 作為第一個公開版本繼續保留。公開 API 目前刻意保持精簡，讓專案能在未來 `1.0.0` 穩定性承諾前持續謹慎演進。
217
+ v0.3.1 是目前的公開版本。v0.1.0 作為第一個公開版本繼續保留。公開 API 目前刻意保持精簡，讓專案能在未來 `1.0.0` 穩定性承諾前持續謹慎演進。
216
218
 
217
219
  Agent Robot Avatar 是獨立開發的開源專案，不隸屬、代表或獲得任何 AI 平台或品牌的官方背書。
218
220
 
@@ -222,8 +224,4 @@ MIT License。詳見 [`LICENSE`](../LICENSE)。
222
224
 
223
225
  ## 請我喝杯咖啡
224
226
 
225
- 如果這個專案對你有幫助，也可以請我喝杯咖啡。選擇你方便的方式即可：
226
-
227
- | Ko-fi | 支付寶 | 微信支付 |
228
- | --- | --- | --- |
229
- | <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="WeChat Pay QR code" width="160"> |
227
+ <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>