min-agent 0.2.0 → 0.3.0

package/docs/superpowers/plans/2026-08-16-batch3-config-engineering.md

@@ -0,0 +1,1595 @@
+# 第三批：配置 + 工程 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 多 provider（破坏式 + 自动迁移）、sampling/budget 配置、日志系统、CI、/plan 计划模式、文档完善。
+
+**Architecture:** config.ts 提供迁移与 activeProvider 解析（`migrateLegacyConfig` + `getActiveProvider`），provider.ts 按 active/覆盖名解析模型；agent.ts 的 RunOptions 承载 providerName/planMode，runOnceCore 统一处理采样回退与预算检查；logger.ts 为独立轻量模块（同步追加写）。
+
+**Tech Stack:** TypeScript, AI SDK v6, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-16-batch3-config-engineering-design.md`
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|---|---|
+| `src/config.ts`(改) | providers[] + activeProvider、迁移、getActiveProvider、sampling/budget 字段、setup 重构 |
+| `src/provider.ts`(改) | resolveModel 按 active/覆盖名、getProviderNames |
+| `src/logger.ts`(新) | 日期滚动日志 |
+| `tests/logger.test.ts`(新) | 日志测试 |
+| `src/agent.ts`(改) | RunOptions.providerName/planMode、采样回退、预算检查、日志记录点 |
+| `src/cli.ts`(改) | --provider、models、setup 提示、日志初始化 |
+| `src/tui-chat.ts`(改) | /provider、/budget、/plan、onRunFinish 预算提示 |
+| `src/tui/slash-commands.ts`(改) | 菜单新命令 |
+| `src/serve.ts`(改) | getActiveProvider 适配、body.provider、done 事件 budget_exceeded |
+| `src/context-window.ts`(改) | getActiveProvider 适配 |
+| `src/compaction.ts`(改) | getActiveProvider 适配 |
+| `src/output.ts`(改) | getActiveProvider 适配 |
+| `src/tui/ModelPicker.tsx`(改) | getActiveProvider 适配 |
+| `.github/workflows/ci.yml`(新) | CI |
+| `tests/config.test.ts`(改) | 迁移测试 |
+| `tests/provider.test.ts`(改) | resolveModel 测试 |
+| `tests/serve.test.ts`(改) | provider/budget_exceeded 测试 |
+| `docs/API.md`、`README.md`(改) | 文档同步 |
+
+---
+
+## Task 1: config.ts — 多 provider 结构 + 迁移 + getActiveProvider
+
+**Files:**
+- Modify: `src/config.ts`
+- Test: `tests/config.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/config.test.ts` 末尾追加：
+
+```ts
+import { getActiveProvider, migrateLegacyConfig, loadConfig } from "../src/config.js"
+
+test("migrateLegacyConfig converts the legacy single provider", () => {
+  const legacy = { provider: { baseURL: "https://x", apiKey: "k", defaultModel: "m1" } }
+  const { config, migrated } = migrateLegacyConfig(legacy as any)
+  expect(migrated).toBe(true)
+  expect(config.providers).toEqual([{ name: "default", baseURL: "https://x", apiKey: "k", defaultModel: "m1" }])
+  expect(config.activeProvider).toBe("default")
+  expect((config as any).provider).toBeUndefined()
+})
+
+test("migrateLegacyConfig is a no-op for the new format", () => {
+  const fresh = { providers: [{ name: "a", baseURL: "https://x", apiKey: "k" }], activeProvider: "a" }
+  const { config, migrated } = migrateLegacyConfig(fresh)
+  expect(migrated).toBe(false)
+  expect(config).toBe(fresh)
+})
+
+test("getActiveProvider resolves the active name", () => {
+  const cfg = {
+    providers: [
+      { name: "a", baseURL: "u1", apiKey: "k1" },
+      { name: "b", baseURL: "u2", apiKey: "k2" },
+    ],
+    activeProvider: "b",
+  }
+  expect(getActiveProvider(cfg)?.name).toBe("b")
+})
+
+test("getActiveProvider falls back to the first provider", () => {
+  const cfg = {
+    providers: [{ name: "a", baseURL: "u1", apiKey: "k1" }],
+  }
+  expect(getActiveProvider(cfg)?.name).toBe("a")
+})
+
+test("getActiveProvider returns undefined without providers", () => {
+  expect(getActiveProvider({})).toBeUndefined()
+})
+
+test("loadConfig migrates and persists a legacy config file", () => {
+  const base = makeTemp()
+  const file = path.join(base, "config.json")
+  writeFileSync(file, JSON.stringify({ provider: { baseURL: "https://x", apiKey: "k" } }))
+  const oldDir = process.env.MIN_AGENT_CONFIG_DIR
+  process.env.MIN_AGENT_CONFIG_DIR = base
+  try {
+    const config = loadConfig()
+    expect(config.providers?.[0]?.name).toBe("default")
+    expect(config.activeProvider).toBe("default")
+    const onDisk = JSON.parse(readFileSync(file, "utf-8"))
+    expect(onDisk.providers[0].name).toBe("default")
+    expect(onDisk.provider).toBeUndefined()
+  } finally {
+    if (oldDir) process.env.MIN_AGENT_CONFIG_DIR = oldDir
+    else delete process.env.MIN_AGENT_CONFIG_DIR
+    rmSync(base, { recursive: true, force: true })
+  }
+})
+```
+
+（`readFileSync` 需补 import；`makeTemp` 已存在）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/config.test.ts`
+Expected: 新用例 FAIL（migrateLegacyConfig/getActiveProvider 不存在）
+
+- [ ] **Step 3: 修改 config.ts**
+
+**a)** `ProviderConfig` 接口加 name、`AppConfig` 重构：
+
+```ts
+export interface ProviderConfig {
+  name?: string
+  type?: "openai-compatible" | "openai" | "ollama"
+  baseURL: string
+  apiKey: string
+  defaultModel?: string
+  /** Context window size in tokens (default: 128000) */
+  contextWindow?: number
+}
+
+export interface AppConfig {
+  providers?: ProviderConfig[]
+  activeProvider?: string
+  instructions?: string[]
+  disabledSkills?: string[]
+  /** Permission mode: "allow-all" auto-approves everything, "ask" prompts for dangerous ops (default) */
+  permission?: "allow-all" | "ask"
+  /** Compaction settings */
+  compaction?: {
+    /** Model to use for summarization (defaults to main model). Use a cheap fast model like "gemini-2.0-flash" */
+    model?: string
+    /** Auto-continue after compaction (default: true) */
+    autoContinue?: boolean
+  }
+  /** SearXNG-compatible web search instance (default: public instance) */
+  webSearchURL?: string
+  /** Firecrawl-compatible web fetch instance (default: public instance) */
+  webFetchURL?: string
+  /** Per-model price overrides (USD per 1M tokens), used for cost estimation */
+  pricing?: Record<string, { inputPerMillion: number; outputPerMillion: number }>
+  /** Sampling parameters applied when the request does not override them */
+  sampling?: { temperature?: number; maxTokens?: number; topP?: number }
+  /** Cost budget in USD; the agent stops suggesting work beyond it */
+  budget?: { maxCostUSD?: number }
+}
+```
+
+**b)** 添加迁移与解析函数（`loadConfig` 之后）：
+
+```ts
+export function migrateLegacyConfig(config: AppConfig): { config: AppConfig; migrated: boolean } {
+  const legacy = (config as any).provider as ProviderConfig | undefined
+  if (!legacy) return { config, migrated: false }
+  const { provider, ...rest } = config as any
+  return {
+    config: { ...rest, providers: [{ name: "default", ...provider }], activeProvider: "default" },
+    migrated: true,
+  }
+}
+
+export function getActiveProvider(config: AppConfig): ProviderConfig | undefined {
+  if (!config.providers || config.providers.length === 0) return undefined
+  if (config.activeProvider) {
+    const found = config.providers.find((p) => p.name === config.activeProvider)
+    if (found) return found
+  }
+  return config.providers[0]
+}
+```
+
+**c)** `loadConfig` 集成迁移：
+
+```ts
+export function loadConfig(): AppConfig {
+  const raw = loadConfigFile(path.join(getConfigDir(), CONFIG_FILE_NAME))
+  const { config, migrated } = migrateLegacyConfig(raw)
+  if (migrated) saveConfig(config)
+  return config
+}
+```
+
+**d)** `isConfigured` 改：
+
+```ts
+export function isConfigured(): boolean {
+  const config = loadConfig()
+  const provider = getActiveProvider(config)
+  return !!(provider?.baseURL && provider?.apiKey)
+}
+```
+
+**e)** `runSetup` 重构（本任务先做最小可用版本，交互式多 provider 管理在 Task 3）：
+
+本任务先把 `runSetup` 的结尾保存改为 providers 结构（Task 3 再重构交互流程）：
+
+```ts
+  const providers = config.providers ?? []
+  const existing = getActiveProvider(config)
+  ...
+  // 现有流程收集 typeChoice/baseURL/apiKey/defaultModel 后：
+  const providerEntry: ProviderConfig = { name: existing?.name ?? "default", type: providerType, baseURL, apiKey, defaultModel }
+  if (providers.length === 0) {
+    config.providers = [providerEntry]
+    config.activeProvider = "default"
+  } else {
+    const idx = providers.findIndex((p) => p.name === (existing?.name ?? "default"))
+    if (idx >= 0) providers[idx] = providerEntry
+    else providers.push(providerEntry)
+    config.providers = providers
+  }
+  saveConfig(config)
+```
+
+注意：本任务中 setup 仍提示 `config.provider = {...}` 处需同步修改（消除编译错误）。Task 3 会完整重构 setup 交互。
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/config.test.ts`
+Expected: PASS（原有 + 6 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/config.ts tests/config.test.ts
+git commit -m "feat: 多 provider 配置结构与自动迁移"
+```
+
+---
+
+## Task 2: 全代码库 provider 引用适配 + provider.ts 改造
+
+**Files:**
+- Modify: `src/provider.ts`
+- Modify: `src/context-window.ts`
+- Modify: `src/compaction.ts`
+- Modify: `src/output.ts`
+- Modify: `src/tui/ModelPicker.tsx`
+- Test: `tests/provider.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/provider.test.ts` 末尾追加：
+
+```ts
+import { getProviderNames, resolveModelForProvider, resolveModel } from "../src/provider.js"
+
+test("getProviderNames returns configured names", () => {
+  const config = loadConfig()
+  const names = getProviderNames(config)
+  expect(Array.isArray(names)).toBe(true)
+})
+```
+
+（`loadConfig` 需 import；如 provider.test.ts 已有隔离 setup，跟随现有模式。若无，追加一个 MIN_AGENT_CONFIG_DIR 隔离的测试块，先写 config.json 含两个 provider，断言 getProviderNames 返回两个名字、resolveModel 用 activeProvider 的 baseURL 创建模型、resolveModel("m", "b") 用 provider b）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/provider.test.ts`
+Expected: 新用例 FAIL（编译错误或函数不存在）
+
+- [ ] **Step 3: 修改 provider.ts**
+
+```ts
+import { createOpenAI } from "@ai-sdk/openai"
+import type { LanguageModel } from "ai"
+import { loadConfig, getActiveProvider, type ProviderConfig } from "./config.js"
+
+export function resolveModelForProvider(provider: ProviderConfig, modelId?: string): LanguageModel {
+  if (!provider.baseURL || !provider.apiKey) {
+    throw new Error("Not configured. Run: min-agent setup")
+  }
+
+  const id = modelId ?? provider.defaultModel
+  if (!id) {
+    throw new Error("No model specified. Run: min-agent setup")
+  }
+
+  switch (provider.type ?? "openai-compatible") {
+    case "openai": {
+      const client = createOpenAI({ apiKey: provider.apiKey })
+      return client.chat(id) as unknown as LanguageModel
+    }
+
+    case "ollama": {
+      const client = createOpenAI({
+        baseURL: normalizeOllamaBaseURL(provider.baseURL),
+        apiKey: provider.apiKey || "ollama",
+      })
+      return client.chat(id) as unknown as LanguageModel
+    }
+
+    case "openai-compatible": {
+      const client = createOpenAI({
+        baseURL: provider.baseURL,
+        apiKey: provider.apiKey,
+      })
+      return client.chat(id) as unknown as LanguageModel
+    }
+
+    default:
+      throw new Error(`Unknown provider type: ${provider.type}`)
+  }
+}
+
+export function resolveModel(modelId?: string, providerName?: string): LanguageModel {
+  const config = loadConfig()
+  const provider = providerName
+    ? config.providers?.find((p) => p.name === providerName)
+    : getActiveProvider(config)
+  if (!provider) {
+    throw new Error(providerName ? `Provider "${providerName}" not found` : "Not configured. Run: min-agent setup")
+  }
+  return resolveModelForProvider(provider, modelId)
+}
+
+export function getProviderNames(config: ReturnType<typeof loadConfig>): string[] {
+  return (config.providers ?? []).map((p) => p.name ?? "").filter(Boolean)
+}
+```
+
+（`normalizeOllamaBaseURL` 需 import from config.js：`import { loadConfig, getActiveProvider, normalizeOllamaBaseURL, type ProviderConfig } from "./config.js"`）
+
+- [ ] **Step 4: 适配其余引用点**
+
+**context-window.ts**（detectContextWindow 与 getContextWindow）：
+
+```ts
+import { getConfigDir, loadConfig, getActiveProvider, type AppConfig } from "./config.js"
+
+async function detectContextWindow(config: AppConfig, id: string): Promise<number> {
+  const provider = getActiveProvider(config)
+  const baseURL = provider?.baseURL ?? ""
+  const apiKey = provider?.apiKey ?? ""
+  ...
+}
+
+export async function getContextWindow(modelId?: string): Promise<number> {
+  const config = loadConfig()
+  const provider = getActiveProvider(config)
+  // 1. Explicit user config
+  if (provider?.contextWindow) return provider.contextWindow
+  const id = modelId ?? provider?.defaultModel
+  ...
+}
+```
+
+**compaction.ts**（约 175-177 行）：
+
+```ts
+  const provider = getActiveProvider(cfg)
+  if (provider?.contextWindow) return provider.contextWindow
+  return await getContextWindow(provider?.defaultModel)
+```
+
+（compaction.ts import 加 getActiveProvider）
+
+**output.ts**（约 18 行）：
+
+```ts
+  const model = modelId ?? getActiveProvider(loadConfig())?.defaultModel ?? "unknown"
+```
+
+（output.ts import 加 getActiveProvider；确认 output.ts 现有 import）
+
+**tui/ModelPicker.tsx**（约 36 行）：
+
+```ts
+    const provider = getActiveProvider(cfg)
+    if (provider?.baseURL && provider?.apiKey) {
+```
+
+（ModelPicker.tsx import 加 getActiveProvider）
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `bun test` 全量与 `bun run typecheck`（仓库根）
+Expected: 全部通过，无类型错误
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/provider.ts src/context-window.ts src/compaction.ts src/output.ts src/tui/ModelPicker.tsx tests/provider.test.ts
+git commit -m "feat: 模型解析按 activeProvider 与覆盖名"
+```
+
+---
+
+## Task 3: cli.ts — --provider、models、setup 交互重构
+
+**Files:**
+- Modify: `src/cli.ts`
+- Modify: `src/config.ts`（runSetup）
+
+- [ ] **Step 1: parseFlags 加 --provider**
+
+```ts
+interface ParsedFlags {
+  model?: string
+  provider?: string
+  resume?: string
+  images: string[]
+  port?: number
+  host?: string
+  positionals: string[]
+}
+```
+
+解析循环加：
+
+```ts
+    } else if (a === "--provider" && argv[i + 1]) {
+      provider = take()
+    }
+```
+
+返回对象加 `provider`。`chat` 分支解构加 `provider: providerOverride`，传给 runAgent/runTui。
+
+**runAgent**（src/agent.ts）加 providerName 参数：
+
+```ts
+export async function runAgent(message: string, modelId?: string, imagePaths?: string[], providerName?: string) {
+  ...
+  await runOnce(messages, instructions, modelId, undefined, undefined, tracker, undefined, providerName)
+```
+
+等等——runOnce 签名已定（Task 7 批 2）：`runOnce(messages, instructions, modelId, abortSignal, callbacks, tracker, options)`。providerName 放 options：`options = { providerName }`。runOnceCore 里 `resolveModel(modelId, options?.providerName)`。
+
+**修改 runOnceCore**：
+
+```ts
+  const model = resolveModel(modelId, options?.providerName)
+```
+
+**修改 runOnce/runOnceWithSystem** 的 RunOptions（agent.ts）：
+
+```ts
+export interface RunOptions {
+  temperature?: number
+  maxTokens?: number
+  topP?: number
+  providerName?: string
+  planMode?: boolean
+}
+```
+
+（planMode 字段本任务先加上，Task 8 使用）
+
+**runTui**（src/tui-chat.ts）TuiOptions 加 `providerName?: string`，`runTui` 内 `let currentProvider = opts.providerName`，executeAgent 的 runOnce 调用 options 传 `{ providerName: currentProvider }`（与后续 planMode 合并）：
+
+```ts
+      const runOptions = { providerName: currentProvider }
+      if (mode === "code" && codeSystemPrompt) {
+        await runOnceWithSystem(messages, codeSystemPrompt, currentModel, abortController?.signal, callbacks, tracker, runOptions)
+      } else {
+        await runOnce(messages, instructions, currentModel, abortController?.signal, callbacks, tracker, runOptions)
+      }
+```
+
+**cli.ts chat/code 分支**：
+
+```ts
+      const { model: modelOverride, provider: providerOverride, resume: resumeId, images, positionals } = parseFlags(args.slice(1))
+      ...
+      if (!message) {
+        const { runTui } = await import("./tui-chat.js")
+        await runTui({ modelId: modelOverride, providerName: providerOverride, resumeSessionId: resumeId, mode: "chat", images })
+      } else {
+        await runAgent(message, modelOverride, images.length > 0 ? images : undefined, providerOverride)
+      }
+```
+
+code 分支同样透传 providerName。
+
+- [ ] **Step 2: models 命令适配**
+
+```ts
+    case "models": {
+      const config = loadConfig()
+      const provider = getActiveProvider(config)
+      if (!provider?.baseURL || !provider?.apiKey) {
+        console.error("Not configured. Run: min-agent setup")
+        process.exit(1)
+      }
+      console.log(`Fetching models (${provider.name ?? "default"})...`)
+      const models = await fetchModels(provider.baseURL, provider.apiKey)
+      if (models.length === 0) {
+        console.log("No models found or unable to fetch model list.")
+      } else {
+        console.log(`\nAvailable models (${models.length}):`)
+        for (const m of models) {
+          const marker = m === provider.defaultModel ? " ← default" : ""
+          console.log(`  ${m}${marker}`)
+        }
+      }
+      break
+    }
+```
+
+（cli.ts import 加 getActiveProvider）
+
+- [ ] **Step 3: runSetup 完整重构（src/config.ts）**
+
+将 `runSetup` 整体替换为：
+
+```ts
+export async function runSetup(): Promise<void> {
+  const config = loadConfig()
+  const providers = config.providers ?? []
+  const current = getActiveProvider(config)
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+  console.log("\n🔧 min-agent 配置\n")
+
+  if (providers.length > 0) {
+    console.log("已配置的 Provider:")
+    providers.forEach((p, i) => {
+      const marker = p.name === config.activeProvider ? " ← 当前" : ""
+      console.log(`  ${i + 1}. ${p.name ?? "(未命名)"}  ${p.baseURL}  (${p.defaultModel ?? "未设置模型"})${marker}`)
+    })
+    console.log()
+    console.log("选项:")
+    console.log("  1. 添加新 Provider")
+    console.log("  2. 切换当前 Provider")
+    console.log("  3. 修改当前 Provider")
+    console.log("  4. 完成")
+    const choice = await ask(rl, "选择 (1/2/3/4)", "4")
+
+    if (choice === "1") {
+      const provider = await collectProvider(rl, undefined)
+      provider.name = (await ask(rl, "Provider 名称", `provider-${providers.length + 1}`)).trim() || `provider-${providers.length + 1}`
+      providers.push(provider)
+      config.activeProvider = provider.name
+      config.providers = providers
+      saveConfig(config)
+      console.log(`\n✓ Provider "${provider.name}" 已添加并设为当前`)
+    } else if (choice === "2") {
+      const sel = await ask(rl, "输入序号选择当前 Provider")
+      const idx = parseInt(sel, 10) - 1
+      const target = providers[idx]
+      if (!target?.name) {
+        console.error("无效序号")
+      } else {
+        config.activeProvider = target.name
+        saveConfig(config)
+        console.log(`\n✓ 当前 Provider 已切换为: ${target.name}`)
+      }
+    } else if (choice === "3") {
+      const name = current?.name ?? providers[0]?.name
+      if (!name) { console.error("无可用 Provider"); rl.close(); return }
+      const idx = providers.findIndex((p) => p.name === name)
+      providers[idx] = await collectProvider(rl, providers[idx])
+      config.providers = providers
+      saveConfig(config)
+      console.log(`\n✓ Provider "${name}" 已更新`)
+    } else {
+      console.log("\n配置未变更")
+    }
+    rl.close()
+    return
+  }
+
+  // 首次配置
+  const provider = await collectProvider(rl, undefined)
+  provider.name = "default"
+  config.providers = [provider]
+  config.activeProvider = "default"
+  saveConfig(config)
+  rl.close()
+  console.log(`\n✓ 配置已保存到 ${path.join(getConfigDir(), CONFIG_FILE_NAME)}`)
+}
+
+async function collectProvider(rl: readline.Interface, existing?: ProviderConfig): Promise<ProviderConfig> {
+  console.log("Provider 类型:")
+  console.log("  1. openai-compatible (默认，兼容 OpenAI API 的任意服务)")
+  console.log("  2. openai (OpenAI 官方)")
+  console.log("  3. ollama (本地 Ollama)")
+  console.log()
+
+  const typeChoice = await ask(rl, "选择 Provider (1/2/3)", existing?.type === "ollama" ? "3" : existing?.type === "openai" ? "2" : "1")
+  const providerType = typeChoice === "3" ? "ollama" as const
+    : typeChoice === "2" ? "openai" as const
+    : "openai-compatible" as const
+
+  let baseURL: string
+  let apiKey: string
+
+  if (providerType === "ollama") {
+    baseURL = await ask(rl, "Ollama API URL", existing?.baseURL || "http://localhost:11434/v1")
+    baseURL = normalizeOllamaBaseURL(baseURL)
+    apiKey = "ollama"
+  } else if (providerType === "openai") {
+    baseURL = "https://api.openai.com/v1"
+    apiKey = await ask(rl, "OpenAI API Key", existing?.apiKey)
+  } else {
+    baseURL = await ask(rl, "API Base URL", existing?.baseURL || "https://api.openai.com/v1")
+    apiKey = await ask(rl, "API Key", existing?.apiKey)
+  }
+
+  if (!baseURL || (!apiKey && providerType !== "ollama")) {
+    console.error("URL 和 Key 不能为空")
+    process.exit(1)
+  }
+
+  console.log("\n正在获取模型列表...")
+  const models = await fetchModels(baseURL, apiKey)
+
+  let defaultModel = existing?.defaultModel ?? ""
+  if (models.length > 0) {
+    console.log(`\n可用模型 (${models.length}):`)
+    models.forEach((m, i) => {
+      const marker = m === defaultModel ? " ← 当前默认" : ""
+      console.log(`  ${i + 1}. ${m}${marker}`)
+    })
+    console.log()
+    const choice = await ask(rl, "选择默认模型 (输入序号或模型名)", defaultModel)
+    const idx = parseInt(choice, 10) - 1
+    if (idx >= 0 && idx < models.length) defaultModel = models[idx]!
+    else if (choice) defaultModel = choice
+  } else {
+    console.log("  ⚠ 无法获取模型列表，请手动输入模型名")
+    const hint = providerType === "ollama" ? "llama3" : providerType === "openai" ? "gpt-4o" : ""
+    defaultModel = await ask(rl, "默认模型", defaultModel || hint)
+  }
+
+  return { type: providerType, baseURL, apiKey, defaultModel }
+}
+```
+
+- [ ] **Step 4: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/cli.ts src/config.ts src/agent.ts src/tui-chat.ts
+git commit -m "feat: CLI --provider 与交互式多 provider 配置"
+```
+
+---
+
+## Task 4: TUI /provider + serve 适配
+
+**Files:**
+- Modify: `src/tui-chat.ts`
+- Modify: `src/serve.ts`
+- Test: `tests/serve.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/serve.test.ts` 末尾追加：
+
+```ts
+test("F9: /v1/models 使用 activeProvider", async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/v1/models`)
+  expect(res.status).toBe(200)
+  const body = await res.json()
+  expect(body.default_model).toBe(BAD_MODEL)
+})
+
+test("F9: POST /v1/chat 接受 provider 字段不报错", async () => {
+  const { status } = await postJson("/v1/chat", {
+    message: "hi",
+    stream: false,
+    provider: "default",
+  })
+  expect(status).toBe(200)
+}, 90000)
+```
+
+（beforeAll 的 config.json 已是 providers 结构——**需要更新**：Task 1 迁移后 serve 测试的 beforeAll 写的是旧格式，serve 启动时会迁移。为明确，将 beforeAll 的 config.json 改为新格式：
+
+```ts
+  writeFileSync(
+    path.join(configDir, "config.json"),
+    JSON.stringify({
+      providers: [{ name: "default", baseURL: "http://127.0.0.1:1/v1", apiKey: "test", defaultModel: BAD_MODEL }],
+      activeProvider: "default",
+      pricing: { [BAD_MODEL]: { inputPerMillion: 10, outputPerMillion: 20 } },
+    }),
+  )
+```
+
+）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新用例 FAIL（models 路由 500 或 provider 字段未识别）
+
+- [ ] **Step 3: 修改 tui-chat.ts**
+
+**/provider 命令**（在 /model case 之前添加）：
+
+```ts
+    case "provider": {
+      const cfg = loadConfig()
+      const providers = cfg.providers ?? []
+      if (arg) {
+        const target = providers.find((p) => p.name === arg)
+        if (!target) {
+          sysMsg(tui, `Provider "${arg}" 不存在`)
+          break
+        }
+        cfg.activeProvider = arg
+        saveConfig(cfg)
+        setModel(target.defaultModel ?? "")
+        sysMsg(tui, `✓ 当前 Provider 已切换为: ${arg}`)
+      } else {
+        if (providers.length === 0) {
+          sysMsg(tui, "无已配置 Provider，运行: min-agent setup")
+          break
+        }
+        const lines = providers.map((p) => {
+          const cur = p.name === cfg.activeProvider ? " ← 当前" : ""
+          return `  ${p.name}  ${p.baseURL}${cur}`
+        })
+        sysMsg(tui, `Providers:\n${lines.join("\n")}\n\n切换: /provider <name>`)
+      }
+      break
+    }
+```
+
+**/models 分支适配**（改用 getActiveProvider）：
+
+```ts
+    case "models": {
+      const { fetchModels } = await import("./config.js")
+      const cfg = loadConfig()
+      const provider = getActiveProvider(cfg)
+      if (!provider?.baseURL || !provider?.apiKey) {
+        sysMsg(tui, "未配置 Provider，运行: min-agent setup")
+        break
+      }
+      sysMsg(tui, "正在获取模型列表...")
+      const models = await fetchModels(provider.baseURL, provider.apiKey)
+      if (models.length === 0) {
+        sysMsg(tui, "无法获取模型列表")
+      } else {
+        const lines = models.map((m) => {
+          const marker = m === provider.defaultModel ? " ← 默认" : ""
+          return `  ${m}${marker}`
+        })
+        sysMsg(tui, `可用模型 (${models.length}):\n${lines.join("\n")}`)
+      }
+      break
+    }
+```
+
+**/model 分支适配**（保存到 activeProvider）：
+
+```ts
+    case "model": {
+      if (arg) {
+        const config = await import("./config.js")
+        const cfg = config.loadConfig()
+        const provider = getActiveProvider(cfg)
+        if (provider) {
+          provider.defaultModel = arg
+          config.saveConfig(cfg)
+        }
+        setModel(arg)
+        sysMsg(tui, `✓ 默认模型已设为: ${arg}`)
+      } else {
+        tui.showModelPicker()
+      }
+      break
+    }
+```
+
+**onModelPick 回调适配**（runTui 内约 131 行）：
+
+```ts
+      onModelPick: (model: string) => {
+        tui.hideModelPicker()
+        const cfg = loadConfig()
+        const provider = getActiveProvider(cfg)
+        if (provider) {
+          provider.defaultModel = model
+          saveConfig(cfg)
+        }
+        currentModel = model
+        tui.setModel(model)
+        sysMsg(tui, `✓ 默认模型已设为: ${model}`)
+      },
+```
+
+**runTui 启动处适配**（`config.provider?.defaultModel` 引用，约 50、147 行）：
+
+```ts
+  const config = loadConfig()
+  const activeProvider = getActiveProvider(config)
+  ...
+  let currentModel = modelId ?? activeProvider?.defaultModel
+  ...
+  new TuiRenderer(callbacks, modelId ?? activeProvider?.defaultModel)
+```
+
+（tui-chat.ts import 加 getActiveProvider）
+
+- [ ] **Step 4: 修改 serve.ts**
+
+**a)** import 加 getActiveProvider：
+
+```ts
+import { loadConfig, saveConfig, fetchModels, isConfigured, getActiveProvider } from "./config.js"
+```
+
+**b)** `/v1/models` 路由：
+
+```ts
+      if (req.method === "GET" && pathname === "/v1/models") {
+        const config = loadConfig()
+        const provider = getActiveProvider(config)
+        const base = provider?.baseURL
+        const key = provider?.apiKey
+        if (!base || !key) {
+          sendJson(res, 500, { error: "provider_not_configured" })
+          return
+        }
+        const models = await fetchModels(base, key)
+        sendJson(res, 200, {
+          default_model: provider?.defaultModel ?? null,
+          models,
+        })
+        return
+      }
+```
+
+**c)** `/v1/context` 与 `/v1/cost` 路由（provider 引用）：
+
+```ts
+      if (req.method === "GET" && pathname === "/v1/context") {
+        const config = loadConfig()
+        const provider = getActiveProvider(config)
+        const ctxWindow = await getContextWindow(provider?.defaultModel)
+        sendJson(res, 200, {
+          context_window: ctxWindow,
+          model: provider?.defaultModel ?? null,
+        })
+        return
+      }
+
+      if (req.method === "GET" && pathname === "/v1/cost") {
+        const config = loadConfig()
+        const provider = getActiveProvider(config)
+        const modelId = url.searchParams.get("model") ?? provider?.defaultModel ?? null
+        ...
+      }
+```
+
+**d)** ChatBody 加 provider 字段，handleChatRequest 的 runOptions 加 providerName：
+
+```ts
+interface ChatBody {
+  ...
+  provider?: string
+  ...
+}
+```
+
+```ts
+      const runOptions: { temperature?: number; maxTokens?: number; topP?: number; providerName?: string } = {
+        temperature: ...,
+        maxTokens: ...,
+        topP: ...,
+        providerName: typeof body.provider === "string" ? body.provider : undefined,
+      }
+```
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `bun test tests/serve.test.ts`
+Expected: PASS（原有 + 2 个新用例）
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/tui-chat.ts src/serve.ts tests/serve.test.ts
+git commit -m "feat: TUI /provider 与 serve activeProvider 适配"
+```
+
+---
+
+## Task 5: sampling 配置回退 + 预算上限
+
+**Files:**
+- Modify: `src/agent.ts`
+- Modify: `src/tui-chat.ts`
+- Modify: `src/serve.ts`
+- Test: `tests/serve.test.ts`（budget_exceeded 字段）
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/serve.test.ts` 末尾追加：
+
+```ts
+test("F9: done 事件包含 budget_exceeded 字段", async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/v1/chat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...authHeaders() },
+    body: JSON.stringify({ message: "hi", stream: true }),
+  })
+  const sse = parseSse(await res.text())
+  const done = sse.find((e) => e.type === "done")
+  expect(done).toBeTruthy()
+  expect(typeof (done as any).budget_exceeded).toBe("boolean")
+}, 90000)
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新用例 FAIL（budget_exceeded undefined）
+
+- [ ] **Step 3: 修改 agent.ts**
+
+**a)** `RunOnceCallbacks.onRunFinish` 的 info 加字段：
+
+```ts
+  onRunFinish?: (info: {
+    stepCount: number
+    usage: LanguageModelUsage | undefined
+    hasError: boolean
+    aborted: boolean
+    maxStepsReached: boolean
+    budgetExceeded?: boolean
+  }) => void
+```
+
+**b)** runOnceCore 采样回退（`const model = resolveModel(...)` 之后）：
+
+```ts
+  const sampling = loadConfig().sampling ?? {}
+  const temperature = options?.temperature ?? sampling.temperature
+  const maxTokens = options?.maxTokens ?? sampling.maxTokens
+  const topP = options?.topP ?? sampling.topP
+```
+
+streamText 条件展开改用这些变量：
+
+```ts
+      ...(temperature != null ? { temperature } : {}),
+      ...(maxTokens != null ? { maxTokens } : {}),
+      ...(topP != null ? { topP } : {}),
+```
+
+（agent.ts 需 import loadConfig、getActiveProvider）
+
+**c)** 预算检查（runOnceCore 内，`maxStepsReached` 逻辑附近）：
+
+```ts
+    let budgetExceeded = false
+    const checkBudget = async () => {
+      if (!tracker) return
+      const maxCost = loadConfig().budget?.maxCostUSD
+      if (maxCost == null || maxCost <= 0) return
+      const price = await getModelPrice(modelId ?? getActiveProvider(loadConfig())?.defaultModel ?? "")
+      const cost = estimateCost(
+        { inputTokens: tracker.totalInputTokens, outputTokens: tracker.totalOutputTokens },
+        price,
+      )
+      if (cost != null && cost > maxCost) budgetExceeded = true
+    }
+```
+
+（agent.ts 需 import getModelPrice、estimateCost from "./pricing.js"，getActiveProvider from "./config.js"）
+
+在成功路径与 catch 路径的 onRunFinish 调用前 `await checkBudget()`，并在 info 中传 `budgetExceeded`：
+
+```ts
+    if (cbs.onRunFinish) {
+      await checkBudget()
+      cbs.onRunFinish({ stepCount, usage, hasError, aborted: false, maxStepsReached, budgetExceeded })
+    }
+```
+
+catch 路径两处同样 `await checkBudget()` 并传字段（aborted 路径可不检查——aborted 时已返回，保持简单：aborted 分支传 `budgetExceeded: false`）。
+
+- [ ] **Step 4: 修改 tui-chat.ts**
+
+**onRunFinish** 完成消息追加预算提示（info 解构后）：
+
+```ts
+      onRunFinish: async (info) => {
+        abortController = null
+        tui.setRunning(false)
+        if (info.aborted) return
+        if (info.budgetExceeded) {
+          tui.addMessage({
+            id: `budget-${Date.now()}`,
+            role: "system",
+            content: "⚠ 已达到预算上限，后续回合可能被限制。/budget 查看或调高",
+            timestamp: Date.now(),
+          })
+        }
+        ...
+```
+
+**/budget 命令**（/tokens 附近）：
+
+```ts
+    case "budget": {
+      const cfg = loadConfig()
+      const maxCost = cfg.budget?.maxCostUSD
+      if (arg) {
+        const n = parseFloat(arg)
+        if (isNaN(n) || n <= 0) {
+          sysMsg(tui, "用法: /budget <USD 金额>")
+          break
+        }
+        cfg.budget = { maxCostUSD: n }
+        saveConfig(cfg)
+        sysMsg(tui, `✓ 预算上限已设为: $${n}`)
+        break
+      }
+      const price = await getModelPrice(currentModel ?? "")
+      const cost = formatCost(
+        estimateCost(
+          { inputTokens: tracker.totalInputTokens, outputTokens: tracker.totalOutputTokens },
+          price,
+        ),
+      )
+      sysMsg(tui, maxCost != null
+        ? `预算: 已用约 ${cost} / 上限 $${maxCost}\n设置: /budget <金额>`
+        : `预算: 已用约 ${cost} / 未设置上限\n设置: /budget <金额>`)
+      break
+    }
+```
+
+（getModelPrice/estimateCost/formatCost 已在第一批 import）
+
+- [ ] **Step 5: 修改 serve.ts 的 done 事件**
+
+`createSseCallbacks` 的 onRunFinish（约 190-211 行）done 事件加字段：
+
+```ts
+      sseWrite(res, {
+        type: "done",
+        step_count: info.stepCount,
+        usage: info.usage,
+        has_error: info.hasError,
+        aborted: info.aborted,
+        max_steps_reached: info.maxStepsReached,
+        budget_exceeded: info.budgetExceeded ?? false,
+        session_id: saved,
+        messages,
+        ...(opts.codeMode ? { mode: "code", project: opts.project } : {}),
+      })
+```
+
+- [ ] **Step 6: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add src/agent.ts src/tui-chat.ts src/serve.ts tests/serve.test.ts
+git commit -m "feat: 采样参数配置回退与预算上限"
+```
+
+---
+
+## Task 6: logger.ts 日志系统
+
+**Files:**
+- Create: `src/logger.ts`
+- Modify: `src/agent.ts`
+- Modify: `src/cli.ts`
+- Test: `tests/logger.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+创建 `tests/logger.test.ts`：
+
+```ts
+import { expect, test, beforeEach, afterEach } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync, readdirSync, readFileSync, realpathSync } from "fs"
+import os from "os"
+import path from "path"
+import { initLogger, log, logToolCall, logToolResult } from "../src/logger.js"
+
+let configDir = ""
+let originalConfigDir: string | undefined
+
+beforeEach(() => {
+  configDir = realpathSync(mkdtempSync(path.join(os.tmpdir(), "min-agent-logger-")))
+  originalConfigDir = process.env.MIN_AGENT_CONFIG_DIR
+  process.env.MIN_AGENT_CONFIG_DIR = configDir
+})
+
+afterEach(() => {
+  if (originalConfigDir === undefined) delete process.env.MIN_AGENT_CONFIG_DIR
+  else process.env.MIN_AGENT_CONFIG_DIR = originalConfigDir
+  rmSync(configDir, { recursive: true, force: true })
+})
+
+function todayLog(): string {
+  const now = new Date()
+  const m = String(now.getMonth() + 1).padStart(2, "0")
+  const d = String(now.getDate()).padStart(2, "0")
+  return path.join(configDir, "logs", `min-agent.${now.getFullYear()}-${m}-${d}.log`)
+}
+
+test("log writes to the daily file with timestamp and level", () => {
+  initLogger()
+  log("info", "hello")
+  const content = readFileSync(todayLog(), "utf-8")
+  expect(content).toContain("[info] hello")
+  expect(content).toMatch(/^\[\d{2}:\d{2}:\d{2}\] \[info\] hello/)
+})
+
+test("logToolCall and logToolResult record summarized input", () => {
+  initLogger()
+  logToolCall("bash", { command: "echo hi", timeout: 5 })
+  const content = readFileSync(todayLog(), "utf-8")
+  expect(content).toContain("tool_call bash")
+  expect(content).toContain("echo hi")
+})
+
+test("initLogger cleans up logs older than 7 days", () => {
+  const logsDir = path.join(configDir, "logs")
+  writeFileSync(path.join(logsDir, "min-agent.2020-01-01.log"), "old", { flag: "a" })
+  writeFileSync(path.join(logsDir, "min-agent.2099-01-01.log"), "future", { flag: "a" })
+  initLogger()
+  const files = readdirSync(logsDir)
+  expect(files).not.toContain("min-agent.2020-01-01.log")
+  expect(files).toContain("min-agent.2099-01-01.log")
+})
+```
+
+（注意：initLogger 会创建 logsDir——第三个用例先手动写文件需要目录存在：用 `mkdirSync(logsDir, { recursive: true })` 补 import；或直接依赖 writeFileSync 的父目录——writeFileSync 不创建父目录，需 mkdirSync）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/logger.test.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: 实现 logger.ts**
+
+```ts
+import { existsSync, mkdirSync, readdirSync, unlinkSync, writeFileSync } from "fs"
+import path from "path"
+import { getConfigDir } from "./config.js"
+
+const KEEP_DAYS = 7
+
+function logsDir(): string {
+  return path.join(getConfigDir(), "logs")
+}
+
+function logFilePath(date: Date): string {
+  const y = date.getFullYear()
+  const m = String(date.getMonth() + 1).padStart(2, "0")
+  const d = String(date.getDate()).padStart(2, "0")
+  return path.join(logsDir(), `min-agent.${y}-${m}-${d}.log`)
+}
+
+export function initLogger(): void {
+  try {
+    mkdirSync(logsDir(), { recursive: true })
+    const cutoff = Date.now() - KEEP_DAYS * 24 * 60 * 60 * 1000
+    for (const f of readdirSync(logsDir())) {
+      const m = f.match(/^min-agent\.(\d{4})-(\d{2})-(\d{2})\.log$/)
+      if (!m) continue
+      const ts = new Date(`${m[1]}-${m[2]}-${m[3]}T00:00:00`).getTime()
+      if (ts < cutoff) {
+        try {
+          unlinkSync(path.join(logsDir(), f))
+        } catch {}
+      }
+    }
+  } catch {}
+}
+
+function writeLog(level: string, msg: string): void {
+  try {
+    const now = new Date()
+    const time =
+      `${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}:${String(now.getSeconds()).padStart(2, "0")}`
+    writeFileSync(logFilePath(now), `[${time}] [${level}] ${msg}\n`, { flag: "a" })
+  } catch {}
+}
+
+export function log(level: "info" | "warn" | "error", msg: string): void {
+  writeLog(level, msg)
+}
+
+function summarize(v: unknown, max = 200): string {
+  const s = typeof v === "string" ? v : JSON.stringify(v) ?? String(v)
+  return s.length > max ? s.slice(0, max) + "…" : s
+}
+
+export function logToolCall(name: string, input: unknown): void {
+  writeLog("info", `tool_call ${name} ${summarize(input)}`)
+}
+
+export function logToolResult(name: string, output: unknown): void {
+  writeLog("info", `tool_result ${name} ${summarize(output)}`)
+}
+```
+
+- [ ] **Step 4: agent.ts 记录点**
+
+import：
+
+```ts
+import { initLogger, log, logToolCall, logToolResult } from "./logger.js"
+```
+
+- runOnceCore 开头（`const model = resolveModel(...)` 之后）：
+
+```ts
+  log("info", `run start mode=${mode} messages=${messages.length} model=${model.modelId}`)
+```
+
+- tool-call 事件（case "tool-call" 内）：
+
+```ts
+          logToolCall(event.toolName, event.input)
+```
+
+- tool-result 事件（case "tool-result"/"tool-error" 内）：
+
+```ts
+          logToolResult(event.toolName, displayed)
+```
+
+- error 事件（case "error" 内）：
+
+```ts
+          log("error", `stream error: ${String(event.error)}`)
+```
+
+- catch 路径（`const msg = err instanceof Error ? err.message : String(err)` 附近）：
+
+```ts
+    log("error", msg)
+```
+
+- 成功结束（`if (cbs.onRunFinish) {` 之前）：
+
+```ts
+    log("info", `run end steps=${stepCount}`)
+```
+
+（注意放在 pushTurn 之后、usage 更新附近；只加一次）
+
+- [ ] **Step 5: cli.ts 启动记录**
+
+`main()` 开头（args 检查之后）：
+
+```ts
+  initLogger()
+  log("info", `min-agent started: ${command}`)
+```
+
+（import from "./logger.js"）
+
+- [ ] **Step 6: 运行测试确认通过**
+
+Run: `bun test tests/logger.test.ts` 与 `bun test` 全量、`bun run typecheck`
+Expected: 全部通过
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add src/logger.ts src/agent.ts src/cli.ts tests/logger.test.ts
+git commit -m "feat: 日期滚动运行日志"
+```
+
+---
+
+## Task 7: CI
+
+**Files:**
+- Create: `.github/workflows/ci.yml`（仓库根目录）
+
+- [ ] **Step 1: 创建 CI 文件**
+
+在仓库根 `/Users/kevin/Desktop/project/min-agent/.github/workflows/ci.yml` 创建：
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run typecheck
+      - run: cd packages/min-agent && bun test
+```
+
+- [ ] **Step 2: 验证 YAML 语法**
+
+Run: `bun -e "const y = await Bun.file('.github/workflows/ci.yml').text(); console.log('ok', y.length)"`（仓库根）
+Expected: ok + 长度
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "ci: GitHub Actions 类型检查与测试"
+```
+
+---
+
+## Task 8: /plan 计划模式
+
+**Files:**
+- Modify: `src/agent.ts`（buildTools planMode 过滤）
+- Modify: `src/tui-chat.ts`（/plan 命令）
+
+- [ ] **Step 1: agent.ts buildTools 加 planMode**
+
+```ts
+async function buildTools(
+  mode: "chat" | "code",
+  modelId: string | undefined,
+  abortSignal: AbortSignal | undefined,
+  planMode = false,
+): Promise<Record<string, Tool>> {
+  ...
+  if (planMode) {
+    for (const name of ["bash", "write", "edit", "apply_patch"]) delete allTools[name]
+  }
+  return allTools
+}
+```
+
+runOnceCore 调用处：
+
+```ts
+  const allTools = await buildTools(mode, modelId, abortSignal, options?.planMode)
+```
+
+- [ ] **Step 2: tui-chat.ts /plan**
+
+**状态变量**（undoStack 附近）：
+
+```ts
+  let planMode = false
+```
+
+**executeAgent 的 runOptions**（现有 `const runOptions = { providerName: currentProvider }`）改为：
+
+```ts
+      const runOptions: { providerName?: string; planMode?: boolean } = {
+        providerName: currentProvider,
+        ...(planMode ? { planMode: true } : {}),
+      }
+```
+
+**/plan 命令**（/diff 附近）：
+
+```ts
+    case "plan": {
+      state.togglePlanMode()
+      sysMsg(tui, state.planMode
+        ? "✓ 计划模式已开启：仅只读工具可用，输出计划后再次输入 /plan 确认并执行"
+        : "✓ 已退出计划模式")
+      break
+    }
+```
+
+SlashState 接口加 planMode/togglePlanMode：
+
+```ts
+interface SlashState {
+  ...
+  planMode: boolean
+  togglePlanMode: () => void
+}
+```
+
+调用处传：
+
+```ts
+              planMode,
+              togglePlanMode: () => { planMode = !planMode },
+```
+
+- [ ] **Step 3: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/agent.ts src/tui-chat.ts
+git commit -m "feat: /plan 只读计划模式"
+```
+
+---
+
+## Task 9: 文档同步
+
+**Files:**
+- Modify: `src/cli.ts`（printUsage）
+- Modify: `src/tui/slash-commands.ts`
+- Modify: `src/tui-chat.ts`（/help）
+- Modify: `README.md`
+- Modify: `docs/API.md`
+
+- [ ] **Step 1: printUsage 更新**
+
+- 命令区加：`min-agent chat/code --provider <name>   Use a specific provider`
+- 选项区加：
+
+```
+  --provider <name>    Use a specific configured provider
+```
+
+- setup 说明行更新为 `min-agent setup                   Configure providers (interactive)`
+
+- [ ] **Step 2: slash-commands.ts 菜单**
+
+在 `{ name: "model", ... }` 之后加：
+
+```ts
+  { name: "provider", description: "查看/切换 Provider", argHint: "[name]" },
+```
+
+在 `{ name: "tokens", ... }` 之后加：
+
+```ts
+  { name: "budget", description: "查看/设置预算上限", argHint: "[USD]" },
+  { name: "plan", description: "切换只读计划模式" },
+```
+
+- [ ] **Step 3: /help 同步**（tui-chat.ts 的 help 数组）
+
+```ts
+        "  /model [n]    交互式选择/切换模型",
+        "  /provider [n] 查看/切换 Provider",
+        "  /budget [n]   查看/设置预算上限",
+        "  /plan         切换只读计划模式",
+```
+
+（替换原 `/model [n]` 行并在 `/tokens` 前插入 budget/plan 相关行，保持列表顺序清晰）
+
+- [ ] **Step 4: README.md**
+
+**Configuration 区**的 config.json 示例替换为：
+
+```json
+// ~/.min-agent/config.json
+{
+  "providers": [
+    {
+      "name": "default",
+      "type": "openai-compatible",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKey": "sk-...",
+      "defaultModel": "gpt-5.5",
+      "contextWindow": 128000
+    }
+  ],
+  "activeProvider": "default",
+  "instructions": ["./docs/rules.md"],
+  "disabledSkills": [],
+  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
+  "sampling": { "temperature": 0.7, "maxTokens": 4096 },
+  "budget": { "maxCostUSD": 5 }
+}
+```
+
+说明文字更新：
+
+```markdown
+Multiple providers are supported: add entries to `providers` and set `activeProvider` (or use `min-agent setup`). Old single-provider configs are migrated automatically on first run.
+
+`sampling` sets defaults for temperature/maxTokens/topP (overridable per request). `budget.maxCostUSD` stops cost escalation beyond the limit (check after each turn).
+```
+
+**Commands 区**加：
+
+```markdown
+min-agent chat --provider <name> "msg"   # Use a specific provider
+```
+
+**Interactive Commands 表**加：
+
+```markdown
+| `/provider [name]` | List/switch provider |
+| `/budget [USD]` | Show/set cost budget |
+| `/plan` | Toggle read-only plan mode |
+```
+
+**日志说明**（Environment Variables 区之前或 Configuration 区末尾）：
+
+```markdown
+Logs: `~/.min-agent/logs/min-agent.YYYY-MM-DD.log` (rotated daily, kept 7 days)
+```
+
+- [ ] **Step 5: docs/API.md**
+
+**`POST /v1/chat` 字段表**加：
+
+```markdown
+| `provider` | string | 使用指定 Provider（默认 activeProvider） |
+```
+
+**done 事件字段表**的 done 行补：
+
+```markdown
+| `done` | step_count, usage, has_error, aborted, max_steps_reached, budget_exceeded, messages, session_id | 结束 |
+```
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/cli.ts src/tui/slash-commands.ts src/tui-chat.ts README.md docs/API.md
+git commit -m "docs: 第三批配置与命令文档同步"
+```
+
+---
+
+## Task 10: 全量验证 + 冒烟
+
+- [ ] **Step 1: 类型检查**
+
+Run: `bun run typecheck`（仓库根）
+Expected: 无错误
+
+- [ ] **Step 2: 全量测试**
+
+Run: `bun test`
+Expected: 全部通过
+
+- [ ] **Step 3: 手动冒烟**
+
+Run（packages/min-agent 下）：
+```bash
+bun run src/cli.ts --help
+bun run src/cli.ts chat --provider no-such "hi"        # 应报 Provider not found exit 1
+bun run src/cli.ts models                               # 显示 activeProvider 模型
+bun run src/cli.ts setup                                # 交互流程（可 Ctrl+C 退出）
+```
+
+TUI 冒烟（`bun run src/cli.ts chat`）：
+1. `/provider` 列出 providers
+2. `/plan` 进入计划模式（提示只读）→ `/plan` 退出
+3. `/budget` 显示预算状态 → `/budget 10` 设置
+4. `/help` 包含新命令
+
+- [ ] **Step 4: 提交（如有遗留改动）**
+
+```bash
+git add -A
+git commit -m "chore: 第三批验证收尾"
+```
+
+---
+
+## 自审记录
+
+**Spec 覆盖：**
+- 多 provider（结构/迁移/CLI/TUI/serve）→ Task 1、2、3、4
+- sampling 配置 → Task 5
+- 预算上限 → Task 5
+- 日志系统 → Task 6
+- CI → Task 7
+- /plan → Task 8
+- 文档完善 → Task 9
+
+**类型一致性：** `ProviderConfig`（含 name）在 Task 1 定义，Task 2/3/4 使用；`RunOptions` 的 providerName/planMode 在 Task 3 定义，Task 5/8 使用；`onRunFinish` info 的 budgetExceeded 在 Task 5 定义并被 tui-chat/serve 消费。