安裝

安裝 npm package

在 Web App 專案加入 SDK：

npm install @kaoruisaac/pedelec

在 browser-side code 匯入：

import { Pedelec, defineTool } from "@kaoruisaac/pedelec";

Package 使用 ESM 並附帶 TypeScript declaration。它不會一起安裝 Chrome Extension、Desktop App、provider CLI 或 Ollama model。

Optional：使用 integration Agent Skill

如果你要請 Coding Agent 將 Pedelec 接到新的或既有的 browser application，可以選擇以下其中一種開發者 integration path：

Option A — Skills CLI

npx skills add kaoruisaac/pedelec

Option B — Release bundle

從 GitHub Releases 下載 pedelec-integration-guideline.zip，解壓縮後告訴 Coding Agent 先讀取 START_HERE.md。這是開發者 integration path，不是 runtime prerequisite，也不是 Pedelec Desktop App 或 Chrome Extension 的安裝程式。

pedelec-integration 會協助 Agent 檢查專案、設計 product tools、實作 browser-side SDK 與 session lifecycle，並補上產品需要的 connection、approval、Provider / effort 與 task feedback UI。兩種方式都不會替終端使用者安裝 Pedelec Desktop App 或 Chrome Extension；以下的使用者端安裝仍是 runtime prerequisites。

安裝使用者端元件

執行 Web App 的使用者需要一組相容的 Pedelec 元件：

安裝目標作業系統的 Pedelec Desktop App。
啟動 App，讓 Core Runtime 可用。
確認 App 已註冊 Chrome Native Messaging host。
在同一個 Chrome profile 安裝並啟用 Pedelec Chrome Extension。
安裝並登入至少一個 provider，或完成 Ollama 設定。

請使用 Web App 所支援版本的官方 Pedelec release channel。SDK、Extension 與 Desktop Runtime 版本保持接近，可以減少 protocol mismatch。

在 browser code 建立 client

import { Pedelec } from "@kaoruisaac/pedelec";

export function createPedelecClient() {
  if (typeof window === "undefined") {
    throw new Error("Pedelec 只能在 browser 中初始化。 ");
  }

  return new Pedelec();
}

同一個 page lifecycle 通常共用一個 client。Client 擁有一條 Extension port，並可管理多個 sessions。

驗證 Extension

const pedelec = createPedelecClient();
const approval = await pedelec.getApprovalStatus();

if (!approval.installed) {
  throw new Error("Pedelec Extension 目前無法使用。 ");
}

console.log("Current origin:", approval.origin);
console.log("Already approved:", approval.approved);

getApprovalStatus() 會將 Extension unavailable 與 disconnected 轉成 { installed: false, approved: false, origin, appConnected: false }，而不是在這兩種情況直接 throw；其他錯誤仍可能 throw。

驗證 Desktop Runtime 與 providers

請以非敏感的 getApprovalStatus().appConnected 做 Desktop connectivity test。listProviders() 需要 origin approval，適合用於 provider 選擇：

const providers = await pedelec.listProviders();

for (const provider of providers) {
  console.table({
    code: provider.code,
    available: provider.available,
    error: provider.error,
  });
}

if (!providers.some((provider) => provider.available)) {
  throw new Error("目前沒有可用的 Pedelec provider。 ");
}

可以依失敗層級判讀：

EXTENSION_UNAVAILABLE：browser page 無法連到 Extension。
NATIVE_HOST_UNAVAILABLE：Extension 存在，但無法連到已註冊 native host。
CORE_RUNTIME_UNAVAILABLE 或 IPC_UNAVAILABLE：host 無法連到 Core，可能已嘗試 background launch；若仍失敗請手動開啟 Desktop 或修復安裝。
available: false：Core 正常，但該 provider 尚未準備好。

Provider 設定注意事項

CLI providers

Desktop App 必須能在自己的 environment 找到 executable。在已開啟 terminal 能執行的 command，不代表 graphical desktop app 繼承的環境也看得到。修改 PATH 後請重新啟動 Desktop App。

Authentication 由各 provider 決定。建立 session 前，先完成 provider 一般的 login 或 credential setup。

Ollama

Pedelec 的 Ollama provider 使用內附的 pedelec-agent，不是把 ollama CLI 當 provider process。仍需要：

在 default http://127.0.0.1:11434 啟動 Ollama-compatible server，或設定其他 local、remote 或 Ollama Cloud endpoint；
非預設位址時在 Desktop App 設定 base URL；
在 Desktop Settings 設定 Ollama API key。現行 agent 要求非空值：本機 server 填 ollama，authenticated remote/Cloud endpoint 填該服務提供的有效 key；
安裝選擇的 model；
在選中的 Ollama effort profile 設定 model；
optional 設定 Tavily API key，讓 Ollama model 可使用 Tavily web search。目前 agent 固定使用 basic search depth，每次最多回傳五筆結果；未設定 Tavily key 時不會提供 web search。

下一步完成快速開始，建立真實 session、接收 assistant output 並正確結束 session。