開始使用 / 安裝
安裝
Heddle 以全域 Node.js CLI 形式發布。支援 macOS、Linux 與 Windows，並需要 Node.js 20+。
安裝前準備
- 使用 Node.js 20 或更新版本。
- 可以用 npm 全域安裝，或用 npx 隨需執行。
- 至少設定一種 provider：OpenAI account sign-in、OpenAI API key，或 Anthropic API key。
- 請在你希望 Heddle 檢查、修改與驗證的 repo 裡執行。
全域安裝
Terminal
npm install -g @roackb2/heddle安裝全域 heddle command，讓你可以從任何目錄執行。
不全域安裝也可以執行
Terminal
npx @roackb2/heddleProvider 驗證
OpenAI — Account Sign-in（實驗性）
Terminal
heddle auth login openai使用你的 ChatGPT / Codex account。這不是 OpenAI 官方支援方式；使用時需遵守 OpenAI 條款。可用 heddle auth status 檢查，或用 heddle auth logout openai 移除 credential。
OpenAI — API Key
Terminal
export OPENAI_API_KEY="your_key_here"如果 OAuth credential 與 API key 同時存在，可用 heddle --prefer-api-key 優先使用 API key。
Anthropic — API Key
Terminal
export ANTHROPIC_API_KEY="your_key_here"選擇 auth 路徑
路徑適合情境備註
OpenAI account sign-in用 ChatGPT/Codex credential 快速完成本機設定實驗性；不是 OpenAI 官方支援。
OpenAI API key穩定使用 OpenAI Platformhosted web search 與 drift embedding 需要 API key。
Anthropic API key使用 Claude modelHeddle 不支援 Anthropic consumer subscription OAuth。
驗證安裝
Terminal
heddle --version
heddle auth status
heddle ask "Reply with OK"第一次 agent run 會在 .heddle/ 下建立 workspace-local state，包含 saved session、trace、memory catalog、upload、heartbeat task 與 run record。
快速開始
Terminal
# 1. 進入任何 repo
cd /path/to/your/project
# 2. 啟動互動式 chat
heddle
# 3. 試一個 prompt
# "Summarize this repo and show the main entrypoints."
# 4. 啟動 browser control plane（選用）
heddle daemon選用：Semantic Drift Telemetry
在同一個環境安裝 cyberloop，即可在 chat session 中啟用 drift-level observability：
Terminal
npm install -g cyberloop