從這裡開始 · 前置條件
安裝 Heddle 並設定模型
執行 SDK 範例前，請先準備 Node.js 20+ TypeScript/ESM host，以及至少一組模型憑證。
客製化深度
Level 1 — 可運作的對話
託管深度
A — Node.js 行程
文件狀態
支援的 SDK 邊界
前置假設
- Node.js 20 或更新版本
- TypeScript/ESM 應用程式或評估專案
- 在 server-side 或本機行程執行；Heddle 主套件不是 browser package
- Provider routing 與 credential preflight
- 對話預設值與本機持久化狀態
- 憑證供應與 secret storage
- 模型選擇、成本政策與 provider account
安裝執行環境套件
npm install @roackb2/heddleCurated package 包含 quickstart runner、conversation engine、工具、MCP host extensions、核准、session、artifact 與產品端可使用的 result types。
如果之後要讓瀏覽器使用遠端託管的 Heddle Agent，請在 client application 改裝 browser-safe package：
npm install @roackb2/heddle-remote不要把 @roackb2/heddle bundle 進瀏覽器客戶端；它是 Node 執行環境。
設定一個 Provider
OpenAI Platform API key
export OPENAI_API_KEY="your_key"Platform API-key authentication 是嵌入式產品較穩定的 OpenAI 路徑。Heddle CLI 也提供實驗性、由使用者主動選擇的 OpenAI account sign-in，但應用程式不應把 consumer account session 當作正式環境的 credential design。
Anthropic API key
export ANTHROPIC_API_KEY="your_key"Heddle 不使用 Anthropic consumer-subscription OAuth。選擇 Claude model 時，請提供 API key。
本機 Ollama model
啟動 Ollama、列出本機已安裝模型，並使用 ollama/ prefix 選擇：
ollama list
export HEDDLE_MODEL="ollama/llama3.2:latest"本機模型可以連線，不代表 tool calling 一定可靠。請用產品的實際工具與流程驗證指定模型。
選擇模型
Quickstart 會依序解析 HEDDLE_MODEL、HEDDLE_EXAMPLE_MODEL、OPENAI_MODEL、ANTHROPIC_MODEL 的第一個已設定值，最後才使用 Heddle 內建的 OpenAI default。
產品明確組裝 engine 時，直接傳入 model：
import { createConversationEngine } from '@roackb2/heddle'
const engine = createConversationEngine({
workspaceRoot: process.cwd(),
stateRoot: process.cwd() + "/.heddle",
model: process.env.HEDDLE_MODEL ?? "gpt-5.4",
preferApiKey: true,
})preferApiKey 可確保嵌入式產品即使在同一台機器上發現實驗性的 CLI account session，仍優先使用 Platform API key。若宿主自行解析憑證，也可以直接傳入 apiKey。
不要把冗長且會變動的 model list 複製進應用程式。Provider prefix 與最新設定方式請參考模型與憑證。
檢查點
當產品端能 import @roackb2/heddle、解析一個支援的 model，並在不把 credential 暴露給 browser code 的情況下取得憑證，就可以繼續。
接著閱讀建立第一個 Agent；如果產品已經有 server 或 UI，請先選擇整合層級。