@jungtz/chat-kit 0.1.0

package/docs/API.md

@@ -0,0 +1,153 @@
+# API 速查（@jungtz/chat-kit）
+
+> 對象：使用端工程師與 AI agent。此檔隨 npm 包出貨（`node_modules/@jungtz/chat-kit/docs/API.md`）。
+> 流程、責任邊界與範例見 `docs/FLOW.md`（repo 內）；型別的完整宣告見 `dist/**/*.d.ts`（包內）。
+> 兩個進入點：`.`（引擎／提示詞／閘門）與 `./models`（設定 → model，亦可從 `.` 匯入）。
+> 套件沒有任何 import 副作用：不讀 env、不讀檔、不建全域 singleton。
+
+## 1. 引擎
+
+```ts
+createChatEngine(options: { domains: Record<string, DomainAdapter> }): ChatEngine
+
+interface ChatEngine {
+  runTurn(input: TurnInput): AsyncGenerator<ChatEvent, void, undefined>;  // 串流
+  completeTurn(input: TurnInput): Promise<TurnResult>;                    // 一次回完整結果
+}
+```
+
+### TurnInput
+
+| 欄位 | 型別 | 說明 |
+| :-- | :-- | :-- |
+| `domain` | `string` | 已註冊的 Domain id |
+| `channel` | `string` | 通道；決定 `channelParts` 與 `GuardContext.channel` |
+| `messages` | `readonly ChatMessage[]` | 最後一則必須是 `user`；system 訊息接在 Domain 片段之後（`extraSystem`，原樣帶入、不檢查佔位符） |
+| `model` | `LanguageModel`（AI SDK） | `models/` 產出的 model，或任何自建 model |
+| `tenantId?` | `string` | 原樣傳給 Domain |
+| `entity?` | `Readonly<Record<string, unknown>>` | 對話標的，原樣傳給 Domain |
+| `modelOptions?` | `{ temperature?, maxOutputTokens?, providerOptions?, timeout? }` | `timeout` 為 `number` 或 `{ totalMs?, stepMs?, chunkMs? }`（`chunkMs` 是串流閒置上限） |
+| `signal?` | `AbortSignal` | 使用者離開時中止上游 |
+
+### ChatEvent
+
+| 型別 | 欄位 |
+| :-- | :-- |
+| `context` | `injectedKeys: string[]` |
+| `thinking` / `content` | `text`（content 只含新增部分） |
+| `tool-call` / `tool-result` | `toolName`、`input`／`output` |
+| `guard` | `name`、`action: 'neutralized'\|'transformed'\|'rewrite'\|'observed'`、`detail?` |
+| `usage` | `usage: TurnUsage` |
+| `done` | `text`（套用全部閘門後）、`rewritten`、`finishReason` |
+| `error` | `error: unknown` |
+
+- **出錯不送 `done`**：用「有沒有收到 `done`」判斷成功，不可用「串流結束了」。
+- `TurnUsage`：`inputTokens`／`outputTokens`／`reasoningTokens`／`totalTokens`，缺席為 `undefined`（用量紀錄記 `null`，不記 `0`）。
+- `TurnResult`（`completeTurn`）：`text`、`thinking`、`rewritten`、`finishReason`、`usage`（可為 `null`）、`toolCalls[]`、`guards[]`、`injectedKeys[]`。
+- `messages` 不合法或未註冊 domain：**在第一個事件前拋錯**（呼叫端 try/catch）；其餘失敗走 `error` 事件。
+
+## 2. DomainAdapter
+
+```ts
+interface DomainAdapter {
+  id: string;
+  prompt: PromptSpec | ((turn: TurnContext) => PromptSpec | Promise<PromptSpec>);
+  buildContext?(turn: TurnContext): Promise<ContextBlock[]> | ContextBlock[];
+  tools?(turn: TurnContext): ToolSet | Promise<ToolSet>;   // AI SDK tool()，含 execute
+  maxToolSteps?: number;                                    // 預設 3
+  prepareStep?: PrepareStepFunction<ToolSet>;               // 每步呼叫前的鉤子（如強制重查）
+  outputGuards?: readonly OutputGuard[];                    // 接在內建閘門之後
+}
+```
+
+`TurnContext`：`{ domain, channel, tenantId?, entity?, messages（已過輸入閘門）, userMessage（已中和標記）, signal? }`——刻意**不含 model**，Domain 不該依模型改變資料。
+
+## 3. 提示詞
+
+```ts
+interface PromptSpec {
+  parts: readonly string[];                                  // 依序拼接的 system 片段
+  channelParts?: Readonly<Record<Channel, readonly string[]>>; // 接在 parts 之後
+  placeholders?: Readonly<Record<string, string>>;           // {{NAME}} 展開，殘留即拋錯
+  composeUserMessage?(args: { blocks: string; message: string }): string;
+}
+
+interface ContextBlock {
+  key: string;            // 同一輪內不可重複
+  order: number;          // 小的在前；同 order 依 key 字典序，可重現
+  trust: 'authoritative' | 'reference' | 'realtime';
+  placement: 'system' | 'user';
+  title: string;
+  content: string;        // 空字串＝本輪無資料，整塊略過
+  format?: 'marked' | 'raw';   // 預設 marked（[REFERENCE: 標題] … [END REFERENCE]）
+}
+```
+
+- 佔位符**只掃模板本身**：值裡剛好出現 `{{x}}` 不展開、不算殘留。
+- 一般使用端不必呼叫；測試／除錯可用：`assemblePrompt`、`expandPlaceholders`、`orderBlocks`、`renderBlock`、`openMarker`／`closeMarker`／`markerPattern`／`TRUST_LABELS`。
+
+## 4. 閘門
+
+```ts
+interface OutputGuard {
+  name: string;
+  transform?(buffer: string, ctx: GuardContext): string;                    // 串流中，純函式
+  check?(finalText: string, ctx: GuardContext): GuardVerdict | Promise<GuardVerdict>; // 結束後
+}
+
+interface GuardVerdict { action: 'pass' | 'rewrite'; text?: string; reason?: string }
+interface GuardContext { modelId: string; channel: string }
+```
+
+- `rewrite` 帶 `text`：改寫只反映在 `done.text`（已送出的串流收不回來）。
+- **觀察模式**：`pass` 帶 `reason` ＝ 放行但回報 `guard` 事件（`action: 'observed'`），供規則上線前量測命中率。
+- 內建：`stripMarkersGuard`（清內部標記，引擎一律套用）；`selfIntroGuard(modelNames: string[])`（模型自我介紹過濾，含備援模型名也要列）。
+- 低階工具：`neutralizeMarkers(text)`（輸入中和，引擎已內建）、`applyTransforms(buffer, guards, ctx)`。
+
+## 5. models/（設定 → model）
+
+```ts
+createModelFromConfig(providers: ProviderMap, rawConfig: RawModelConfig | ModelConfig,
+  options?: ModelFromConfigOptions): { model: LanguageModelV3; targets: ModelTarget[] }
+
+resolveModelChain(providers, rawConfig, options?): ModelTarget[]   // 只解析不建 model
+resolveModelTarget(providers, providerKey, options?): ModelTarget  // 單一 provider
+createRoutedModel(target: ModelTarget, options?: RoutedModelOptions): LanguageModelV3
+createFallbackModel(models: readonly LanguageModelV3[], options?: FallbackModelOptions): LanguageModelV3
+reasoningOptions(effort: ReasoningEffort | null): SharedV3ProviderOptions
+createKeyRing(options?: KeyRingOptions): KeyRing
+listModels(baseURL, apiKeys, options?): Promise<ListedModel[]>
+```
+
+| 類型 | 要點 |
+| :-- | :-- |
+| `ProviderDef` | `{ baseURL?, apiKey? \| apiKeys?, defaultModel?, sdk?, reasoningEffort? }`；金鑰支援 `${ENV}` 展開 |
+| `ModelTarget` | 整包 `{ providerKey, baseURL, apiKeys[], model, protocol, reasoningEffort? }`，不拆開傳 |
+| `Protocol` | `'openai-compatible'`（`/chat/completions`）／`'openai'`（`/responses`）／`'anthropic'`（`/messages`） |
+| `ReasoningEffort` | `'none' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` |
+| `ModelFromConfigOptions` | `defaultProviderKey?`、`defaultReasoningEffort?`、`requireApiKey?`、`env?`、`logger?`、`routed?`、`fallback?` |
+| `FallbackEvent` | `{ from, to, error, index }`——`onFallback` 用來記「實際回應者」，用量才不會記錯 provider |
+| `KeyRing` | `pick`／`markExhausted`／`status()`／`reset()`；429 冷卻遵守 `Retry-After` |
+
+設定形狀（`rawConfig`）：`{ model: 'provider' 或 'provider/model', reasoningEffort?, backup? }`；主設定無效直接拋錯，備援無效只警告並略過。備援只沿用推理強度、不沿用模型名（改用備援自己的 `defaultModel`）。
+
+## 6. 常見陷阱
+
+| 陷阱 | 正確做法 |
+| :-- | :-- |
+| `ai` 裝到 7.x | 釘 `ai@^6`、`@ai-sdk/provider@^3`（`ai@7` 介面變動未支援） |
+| 自己呼叫 `streamText` 沒設 `maxRetries` | 一律 `maxRetries: 0`——輪替與備援已在 models 層，SDK 重試會再疊一層 |
+| 用「串流結束了」判斷成功 | 用「有沒有收到 `done`」 |
+| usage 缺席填 `0` | 記 `null`——`0` 是「真的消耗 0」，會污染統計 |
+| 手組 `providerOptions` 且命名空間含點 | 一律用 `reasoningOptions()`——含點的鍵會讓推理強度被 AI SDK 靜默丟掉 |
+| `messages` 最後一則不是 user／空內容 | 第一個事件前拋錯，呼叫端要 try/catch |
+| 依賴 `file:` 或 `npm link` | 釘死版本（npm 版本號或 git tag） |
+
+## 7. 對應檔案（深入時）
+
+| 主題 | 檔案 |
+| :-- | :-- |
+| 五步管線與事件 | `dist/engine/types.d.ts`（原始碼 `src/engine/engine.ts`） |
+| 組裝與信任標記 | `src/prompt/assemble.ts`、`src/prompt/markers.ts` |
+| 換手與金鑰輪替 | `src/models/fallback-model.ts`、`stream-peek.ts`、`key-ring.ts` |
+| provider 特例 | `src/models/quirks.ts` |

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@jungtz/chat-kit",
+  "version": "0.1.0",
+  "description": "通用 Chat 引擎：AI SDK 模型層、金鑰輪替、主備援、提示詞組裝與閘門",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.ts",
+      "import": "./dist/models/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/API.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --outDir .build && rollup -c",
+    "build:prod": "cross-env NODE_ENV=production npm run build",
+    "prepare": "npm run build:prod",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run build:prod && npm test"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/openai-compatible": "^2.0.0",
+    "@ai-sdk/provider": "^3.0.0",
+    "ai": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.127",
+    "@ai-sdk/openai": "^3.0.124",
+    "@ai-sdk/openai-compatible": "^2.0.81",
+    "@ai-sdk/provider": "^3.0.18",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@types/node": "^22.20.5",
+    "ai": "^6.0.300",
+    "cross-env": "^10.1.0",
+    "rollup": "^4.63.6",
+    "tsx": "^4.23.15",
+    "typescript": "5.9",
+    "zod": "^4.6.5"
+  }
+}