# `autoInstall()`——一行安裝

零設定的啟動點。回傳完全構造好的 `DotDotDuck`，內建合理預設，讓你先看到 SDK 跑起來、再決定要設什麼。

## 最少寫

```ts
import { autoInstall } from '@perhapxin/dddk';
import '@perhapxin/dddk/styles.css';

const dddk = autoInstall();
```

就這樣。你會拿到：

- 綁在 `Ctrl+K` / `⌘K` 的 command palette。
- 掛在螢幕正下方的字幕條。
- 桌面滑鼠環境的 Dwell 長按偵測。
- 右下角行動裝置 FAB。
- 六張預設鴨子精靈從 SDK 內建的 `dist/duck/` 載入。
- Locale 自動偵測：`zh` / `zh-*` → `'zh-TW'`，其他 → `'en'`。
- SDK 內建 prompt 預設註冊在 `dddk.prompts` 上。
- Demo LLM——收到任何 completion 都回覆「接你自己的 LLM 才會啟用真的 AI」，這樣 agent / InlineAgent / voice-cleanup 不會靜默 no-op，使用者看得到為什麼沒事發生。

## 傳 overrides

`DotDotDuckConfig` 的每個欄位都照收，另加一個工廠專用旗標（`demoLLM`）。

```ts
const dddk = autoInstall({
  llm: myOpenAIProvider,          // 真的 LLM 換掉 demo stub
  siteName: 'Acme',
  agentName: 'Rex',
  paletteCommands: myCommands,
  brand: { voice: 'friendly' },
  webAgent: {
    contextProvider: () => ({ tenant: currentTenant() }),
  },
});
```

`autoInstall(overrides)` 跟 `new DotDotDuck({ ...factoryDefaults, ...overrides })` 等價，工廠函式只是幫你挑好預設。你沒 override 的欄位都留 demo 預設。

## 關掉 demo LLM

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

```ts
const dddk = autoInstall({ demoLLM: false });
// Palette + Dwell + FAB 照掛；agent 系列功能靜默 no-op，
// 直到 runtime 才接 llm 進來。
```

適用場景：你的 LLM provider 是非同步載的（例如卡在認證後），想先讓 SDK 就緒、LLM 之後補。

## 完整選項 type

```ts
interface AutoInstallOptions extends Partial<DotDotDuckConfig> {
  /**
   * 為 true 且沒有 `llm` 時，接一個 demo LLM，任何 completion 都回
   * 制式的「請接 LLM」提示。預設 true。設 false 保留舊的「沒 llm
   * 就靜默 no-op」行為（等同 raw `new DotDotDuck({})`），適合
   * runtime 才會接 LLM 的場景。
   */
  demoLLM?: boolean;
}
```

回傳：`DotDotDuck`。跟 `new DotDotDuck(...)` 拿到的一樣。所有方法（`startAgent`、`runSkill`、`submitSurface` 等）都在。

## 何時不用 `autoInstall`

- **你已經每個 config 欄位都明確寫好了。** 換成 `autoInstall({...})` 只是搬程式碼、沒好處。
- **你需要 SSR 安全的初始化。** `autoInstall` 建構時會讀 `navigator.language`，server 端跑不了。丟進 `onMount`（Svelte）／`useEffect`（React）／`mounted`（Vue）。
- **你想把 demo LLM 當常態產品用。** Demo LLM 是刻意「不能用在正式產品」的——它的回覆會告訴使用者去接真的 LLM。如果你的產品確實不需要 LLM，設 `demoLLM: false` 跳過提示。

## 常見整合模式

### Vanilla HTML + `<script>`

```html
<script type="module">
  import { autoInstall } from 'https://esm.sh/@perhapxin/dddk@0.2.2';
  import 'https://esm.sh/@perhapxin/dddk@0.2.2/styles.css';

  const dddk = autoInstall();
  window.dddk = dddk; // 方便 DevTools 打
</script>
```

### SvelteKit

```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  import { autoInstall } from '@perhapxin/dddk';
  import '@perhapxin/dddk/styles.css';

  onMount(() => {
    const dddk = autoInstall({
      llm: myProvider,
      paletteCommands: buildCommands(),
    });
    return () => dddk.destroy?.();
  });
</script>
```

### React / Next.js

```tsx
'use client';
import { useEffect } from 'react';
import { autoInstall } from '@perhapxin/dddk';
import '@perhapxin/dddk/styles.css';

export function DddkBoot() {
  useEffect(() => {
    const dddk = autoInstall({ llm: getLLM() });
    return () => dddk.destroy?.();
  }, []);
  return null;
}
```

## 相關

- [overview.md](./overview.zh-TW.md)——SDK 一眼看完。
- [quickstart-frameworks.md](./quickstart-frameworks.zh-TW.md)——各框架的安裝。
- [prompts.md](./prompts.zh-TW.md)——自訂 demo LLM（或真 LLM）要用的 prompt。
- [migrating.md](./migrating.zh-TW.md)——從 `new DotDotDuck({...})` 換成 `autoInstall(...)`。