# 從 v0.2.1 升級到 v0.2.2

**純新增**。既有 callsite 全部照舊——不用改 import、不用改 config 欄位、不用重接 CSS 變數。以下三段都是可選的採用點，是否用完全看你想不想吃到 v0.2.2 的新東西。

從更早版本升級的話，先看 [v0.2.1 migrating](../../v0.2.1/dddk/migrating.md)——以下假設你已經是 v0.2.1。

## 可選：改用 `dddk.prompts` 集中管理 LLM prompt

如果你現在是用 `webAgent.systemPrompt`、`InlineAgentConfig.systemPrompt`、`VoiceConfig.cleanupPrompt`、`DwellConfig.systemPrompt` 這些欄位覆蓋 SDK 預設，可以繼續用——它們仍然贏過 registry（跟以前一樣）。但如果你想「同一支 prompt 有 EN + JA + zh-TW 三個版本」，config 欄位只接受一個字串，registry 才有能力。

Before（單 locale、每子系統一支）：

```ts
new DotDotDuck({
  webAgent: { systemPrompt: MY_JAPANESE_NARRATOR },
  llm: ...,
});
```

After（依 locale 覆蓋、單一 API）：

```ts
const dddk = new DotDotDuck({ llm: ... });

dddk.prompts.override('webagent-narrator.system', 'ja', () => MY_JAPANESE_NARRATOR);
dddk.prompts.override('webagent-narrator.system', 'zh-TW', () => MY_TRADITIONAL_CHINESE_NARRATOR);
// 英文吃 SDK 預設。
```

執行期切 locale 也 OK——registry 是 process 級的、在組 message 時才讀，所以下一回合的 agent turn 會自動用當前 locale 的 prompt，不用重掛。

完整介紹：[prompts.md](./prompts.md)。

## 可選：把 `new DotDotDuck({...})` 換成 `autoInstall(...)`

如果你已經每個 config 欄位都明確寫好了，別花時間改——只是搬程式碼。`autoInstall()` 目標是：

- **新的 app** 想先跑起來看看再決定要設什麼。
- **Landing page / 行銷站** 只要 palette + Dwell + 吉祥物、不用 LLM。
- **`<script src>` embed** 掛在靜態站，完整 config 是殺雞用牛刀。

Before：

```ts
const dddk = new DotDotDuck({
  llm: myProvider,
  locale: navigator.language.startsWith('zh') ? 'zh-TW' : 'en',
  // ... 又 20 個欄位手寫 ...
});
```

After（跳過 boilerplate、只覆蓋你在乎的）：

```ts
const dddk = autoInstall({
  llm: myProvider,
  paletteCommands: myCommands,
});
// Locale、鴨子精靈、其他 20 個欄位都吃合理預設。
```

想保留舊行為（沒接 `llm` 就靜默 no-op，等同 raw `new DotDotDuck({})`），設 `demoLLM: false`：

```ts
const dddk = autoInstall({ demoLLM: false });
```

完整介紹：[auto-install.md](./auto-install.md)。

## 可選：把鴨子精靈檔從你自家 static 移掉

v0.2.2 之前，SDK 假設 host 自己在 `--dddk-*-url` 指向的路徑 host 吉祥物 PNG（加上 Dwell overlay 硬編的 `/duck/swim-cycle.png`）。v0.2.2 **七張** sprite 全部 build-time bundle 進 `dist/duck/`，`tokens.css` 也綁好預設——包含新的 WebAgent `cursor.png`（鴨子騎紙飛機）取代原本 SVG 的箭頭鴨頭。

Before：

```css
/* 你的 app.css */
:root {
  --dddk-avatar-url: url('/duck/neutral.png');
  --dddk-swim-url: url('/duck/swim-side.png');
  --dddk-hero-url: url('/duck/hero-greet.png');
  --dddk-chill-url: url('/duck/chill-shades.png');
}
```

```
static/duck/
  neutral.png
  swim-side.png
  hero-greet.png
  chill-shades.png
```

After（SDK 出貨、你自家的可以刪）：

```css
/* 你的 app.css——只要不換 sprite 這裡就不用寫 */
```

**子目錄注意**——如果你的 app 掛在 `/tools/` 這類子目錄，保留 `:root` override 指向 root-absolute 路徑。原因寫在 [v0.2.2 release notes](./release-notes.zh-TW.md) 的「子目錄注意」段。

## 移除／棄用

無。v0.2.1 有的欄位、函式、CSS 變數，v0.2.2 全部照舊。

## 新增 API 總表

| API | 位置 |
|---|---|
| `dddk.prompts` | 每個 `DotDotDuck` instance 上 |
| `PromptRegistry`、`PROMPT_IDS`、`promptRegistry` | `@perhapxin/dddk` 根 export |
| `autoInstall(opts?)`、`AutoInstallOptions` | `@perhapxin/dddk` 根 export |
| `dddk.mobile.showHeroGreeting(text, opts?)` | `dddk.mobile` 上（v0.2.1 實驗性，v0.2.2 轉正） |
| 8 條吉祥物動畫時間 token | CSS 變數——在 `:root` 宣告即覆蓋 |
| 6 條鴨子精靈 URL | CSS 變數——SDK 內建預設；宣告即覆蓋 |