min-agent 0.2.1 → 0.4.0

package/docs/superpowers/plans/2026-08-16-batch2-cli-tools-api.md

@@ -0,0 +1,2105 @@
+# 第二批：CLI + 工具 + HTTP API 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:** 补齐 CLI 命令（history 子命令、mcp env、update、export）、工具能力（bash cwd、apply_patch、write append、web_search 参数、chat 模式工具）、HTTP API（8 个新端点/参数）。
+
+**Architecture:** 工具增强以纯函数 + 可注入依赖为主（apply_patch 解析器纯函数、updater 版本比较纯函数）；API 端点沿用 serve.ts 现有路由模式；agent.ts 的 runOnce 加可选 options 参数透传采样参数。
+
+**Tech Stack:** TypeScript, AI SDK v6, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-16-batch2-cli-tools-api-design.md`
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|---|---|
+| `src/tools/apply_patch.ts`(新) | unified diff 解析与应用工具 |
+| `tests/apply-patch.test.ts`(新) | apply_patch 测试 |
+| `src/updater.ts`(新) | 版本检查与自动升级 |
+| `src/tools/bash.ts`(改) | BashInput.cwd + executeBash cwd |
+| `src/tools/explore.ts`(改) | readOnlyBashTool 加 cwd |
+| `tests/bash.test.ts`(改) | cwd 测试 |
+| `src/tools/write.ts`(改) | append 参数 |
+| `tests/file-tools.test.ts`(改) | append 测试 |
+| `src/tools/web_search.ts`(改) | language/time_range |
+| `tests/web-search.test.ts`(改) | 参数透传测试 |
+| `src/tools/index.ts`(改) | chat 模式加 todo + apply_patch 注册 |
+| `src/agent.ts`(改) | buildTools explore 两种模式 + runOnce options |
+| `src/cli.ts`(改) | history 子命令、mcp --env、update、usage |
+| `src/serve.ts`(改) | 新端点 + 采样参数 + paste code |
+| `tests/serve.test.ts`(改) | 新端点测试 |
+| `docs/API.md`(改) | 新端点文档 |
+| `README.md`(改) | CLI 命令同步 |
+
+---
+
+## Task 1: bash 支持 cwd 参数
+
+**Files:**
+- Modify: `src/tools/bash.ts`
+- Modify: `src/tools/explore.ts`
+- Test: `tests/bash.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/bash.test.ts` 末尾追加（并补 import）：
+
+```ts
+import { mkdtempSync, rmSync, realpathSync } from "fs"
+import { tmpdir } from "os"
+import path from "path"
+
+test("bash runs in the specified cwd", async () => {
+  const dir = realpathSync(mkdtempSync(path.join(tmpdir(), "min-agent-bash-")))
+  try {
+    const out = await executeBash("pwd", undefined, dir)
+    expect(out).toBe(dir)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/bash.test.ts`
+Expected: 新用例 FAIL（`pwd` 输出当前工作目录而非 dir）
+
+- [ ] **Step 3: 修改 bash.ts**
+
+`type BashInput` 加字段，`executeBash` 加参数，spawn 用 cwd。文件顶部补 `import path from "path"`。
+
+```ts
+type BashInput = { command: string; timeout?: number; cwd?: string }
+```
+
+工具 schema 与描述：
+
+```ts
+  description:
+    "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory (or `cwd` if specified). You SHOULD set a timeout based on how long you expect the command to take. If no timeout is set, the command runs until it finishes or the user manually interrupts (Ctrl+C).",
+  inputSchema: jsonSchema<BashInput>({
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The shell command to execute" },
+      timeout: { type: "number", description: "Timeout in milliseconds. Set based on expected duration (e.g. 5000 for quick commands, 60000 for builds). Omit only for commands with unpredictable duration." },
+      cwd: { type: "string", description: "Working directory for the command (relative to the current directory or absolute)" },
+    },
+    required: ["command"],
+  }),
+  execute: async ({ command, timeout, cwd }) => {
+    if (!isAutoApprove() && isDangerousCommand(command)) {
+      const approved = await confirm(`Execute dangerous command: ${command}`)
+      if (!approved) return "Command rejected by user."
+    }
+    return executeBash(command, timeout, cwd)
+  },
+```
+
+`executeBash` 签名与 spawn：
+
+```ts
+export async function executeBash(command: string, timeout?: number, cwd?: string): Promise<string> {
+  ensureSigintHandler()
+  ...
+    const proc = spawn(actualCommand, [], {
+      shell: true,
+      cwd: cwd ? path.resolve(process.cwd(), cwd) : process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+      env: { ...process.env, ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}) },
+    })
+```
+
+- [ ] **Step 4: 修改 explore.ts 的 readOnlyBashTool**
+
+`execute` 内透传 cwd：
+
+```ts
+  inputSchema: jsonSchema<{ command: string; timeout?: number; cwd?: string }>({
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The read-only shell command to execute" },
+      timeout: { type: "number", description: "Timeout in milliseconds" },
+      cwd: { type: "string", description: "Working directory (relative or absolute)" },
+    },
+    required: ["command"],
+  }),
+  execute: async ({ command, timeout, cwd }) => {
+    if (!isReadOnlyCommand(command)) {
+      return `Error: "${command.slice(0, 80)}" is not a read-only command. Allowed: ${[...READ_ONLY_BINS].join(", ")} (read-only git subcommands only).`
+    }
+    return executeBash(command, timeout, cwd)
+  },
+```
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `bun test tests/bash.test.ts`
+Expected: PASS（6 个原有用例 + 1 个新用例）
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/tools/bash.ts src/tools/explore.ts tests/bash.test.ts
+git commit -m "feat: bash 工具支持工作目录参数"
+```
+
+---
+
+## Task 2: write 支持 append
+
+**Files:**
+- Modify: `src/tools/write.ts`
+- Test: `tests/file-tools.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/file-tools.test.ts` 末尾追加：
+
+```ts
+test("write appends when append is set", async () => {
+  const dir = tmpDir()
+  try {
+    const file = path.join(dir, "a.txt")
+    await exec(writeTool)({ filePath: file, content: "one\n" }, {})
+    const out = await exec(writeTool)({ filePath: file, content: "two\n", append: true }, {})
+    expect(out).toContain("(appended)")
+    expect(readFileSync(file, "utf-8")).toBe("one\ntwo\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("write append creates the file when it does not exist", async () => {
+  const dir = tmpDir()
+  try {
+    const file = path.join(dir, "new.txt")
+    const out = await exec(writeTool)({ filePath: file, content: "hello", append: true }, {})
+    expect(out).toContain("(appended)")
+    expect(readFileSync(file, "utf-8")).toBe("hello")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+```
+
+（`readFileSync` 已在 import 中）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/file-tools.test.ts`
+Expected: 新用例 FAIL（append 未实现，输出不含 "(appended)"，且内容被覆盖）
+
+- [ ] **Step 3: 修改 write.ts**
+
+```ts
+type WriteInput = { filePath: string; content: string; append?: boolean }
+```
+
+描述：
+
+```ts
+  description:
+    "Write content to a file. Creates the file if it doesn't exist, overwrites if it does (unless `append` is true). Creates parent directories as needed.",
+```
+
+schema properties 追加：
+
+```ts
+      append: { type: "boolean", description: "If true, append to the file instead of overwriting" },
+```
+
+execute：
+
+```ts
+  execute: async ({ filePath, content, append }) => {
+    if (Buffer.byteLength(content, "utf-8") > MAX_WRITE_BYTES) {
+      return `Error: content exceeds ${MAX_WRITE_BYTES} bytes. Write in smaller chunks or check the content size.`
+    }
+    const resolved = path.resolve(process.cwd(), filePath)
+
+    // Confirm overwriting existing files
+    if (!append && !isAutoApprove() && existsSync(resolved)) {
+      const approved = await confirm(`Overwrite existing file: ${filePath}`)
+      if (!approved) return "Write rejected by user."
+    }
+
+    try {
+      await mkdir(path.dirname(resolved), { recursive: true })
+      await writeFile(resolved, content, append ? { flag: "a", encoding: "utf-8" } : "utf-8")
+      return `Written ${Buffer.byteLength(content, "utf-8")} bytes to ${filePath}${append ? " (appended)" : ""}`
+    } catch (err: any) {
+      return `Error writing file: ${err.message}`
+    }
+  },
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/file-tools.test.ts`
+Expected: PASS（原有用例 + 2 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tools/write.ts tests/file-tools.test.ts
+git commit -m "feat: write 工具支持追加模式"
+```
+
+---
+
+## Task 3: apply_patch 工具（unified diff 应用）
+
+**Files:**
+- Create: `src/tools/apply_patch.ts`
+- Modify: `src/tools/index.ts`（注册到 chat 与 code 工具集）
+- Test: `tests/apply-patch.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+创建 `tests/apply-patch.test.ts`：
+
+```ts
+import { expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, realpathSync, existsSync } from "fs"
+import os from "os"
+import path from "path"
+import { setAutoApprove } from "../src/confirm.js"
+import { parseUnifiedDiff, applyPatch } from "../src/tools/apply_patch.js"
+
+setAutoApprove(true)
+
+function makeTemp(): string {
+  return realpathSync(mkdtempSync(path.join(os.tmpdir(), "min-agent-patch-")))
+}
+
+const MODIFY_DIFF = `--- a/foo.txt
++++ b/foo.txt
+@@ -1,3 +1,3 @@
+ line1
+-line2
++line2-edited
+ line3
+`
+
+test("parseUnifiedDiff parses headers and hunks", () => {
+  const files = parseUnifiedDiff(MODIFY_DIFF)
+  expect(files.length).toBe(1)
+  expect(files[0]!.path).toBe("foo.txt")
+  expect(files[0]!.isNew).toBe(false)
+  expect(files[0]!.hunks.length).toBe(1)
+  const lines = files[0]!.hunks[0]!.lines
+  expect(lines.map((l) => l.type)).toEqual(["context", "delete", "add", "context"])
+})
+
+test("applyPatch modifies an existing file", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "foo.txt"), "line1\nline2\nline3\n")
+    const result = applyPatch(parseUnifiedDiff(MODIFY_DIFF), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "foo.txt"), "utf-8")).toBe("line1\nline2-edited\nline3\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch creates a new file from /dev/null", () => {
+  const dir = makeTemp()
+  try {
+    const diff = `--- /dev/null
++++ b/new.txt
+@@ -0,0 +1,2 @@
++hello
++world
+`
+    const result = applyPatch(parseUnifiedDiff(diff), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "new.txt"), "utf-8")).toBe("hello\nworld\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch deletes lines", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "foo.txt"), "keep\nremove-me\nkeep2\n")
+    const diff = `--- a/foo.txt
++++ b/foo.txt
+@@ -1,3 +1,2 @@
+ keep
+-remove-me
+ keep2
+`
+    const result = applyPatch(parseUnifiedDiff(diff), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "foo.txt"), "utf-8")).toBe("keep\nkeep2\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch matches hunks with small offsets", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "foo.txt"), "a\nb\nc\nline1\nline2\nline3\nd\n")
+    const result = applyPatch(parseUnifiedDiff(MODIFY_DIFF), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "foo.txt"), "utf-8")).toBe("a\nb\nc\nline1\nline2-edited\nline3\nd\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch rejects conflicts without partial writes", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "foo.txt"), "totally\ndifferent\ncontent\n")
+    const result = applyPatch(parseUnifiedDiff(MODIFY_DIFF), dir)
+    expect(result.ok).toBe(false)
+    expect(readFileSync(path.join(dir, "foo.txt"), "utf-8")).toBe("totally\ndifferent\ncontent\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch handles multiple files in one diff", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "a.txt"), "x1\nx2\n")
+    writeFileSync(path.join(dir, "b.txt"), "y1\n")
+    const diff = `--- a/a.txt
++++ b/a.txt
+@@ -1,2 +1,2 @@
+ x1
+-x2
++x2b
+--- a/b.txt
++++ b/b.txt
+@@ -1 +1 @@
+-y1
++y1b
+`
+    const result = applyPatch(parseUnifiedDiff(diff), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "a.txt"), "utf-8")).toBe("x1\nx2b\n")
+    expect(readFileSync(path.join(dir, "b.txt"), "utf-8")).toBe("y1b\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch handles multiple hunks in one file", () => {
+  const dir = makeTemp()
+  try {
+    writeFileSync(path.join(dir, "foo.txt"), "one\ntwo\nthree\nfour\n")
+    const diff = `--- a/foo.txt
++++ b/foo.txt
+@@ -1,2 +1,2 @@
+-one
++one-edited
+ two
+@@ -3,2 +3,2 @@
+ three
+-four
++four-edited
+`
+    const result = applyPatch(parseUnifiedDiff(diff), dir)
+    expect(result.ok).toBe(true)
+    expect(readFileSync(path.join(dir, "foo.txt"), "utf-8")).toBe("one-edited\ntwo\nthree\nfour-edited\n")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test("applyPatch fails when the target file does not exist", () => {
+  const dir = makeTemp()
+  try {
+    const result = applyPatch(parseUnifiedDiff(MODIFY_DIFF), dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain("不存在")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/apply-patch.test.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: 实现 apply_patch.ts**
+
+```ts
+import { tool, jsonSchema } from "ai"
+import { readFile, writeFile } from "fs/promises"
+import { existsSync } from "fs"
+import path from "path"
+import { confirm, isAutoApprove } from "../confirm.js"
+
+export interface HunkLine {
+  type: "context" | "delete" | "add"
+  text: string
+}
+
+export interface Hunk {
+  oldStart: number
+  oldCount: number
+  newStart: number
+  newCount: number
+  lines: HunkLine[]
+}
+
+export interface PatchFile {
+  path: string
+  isNew: boolean
+  hunks: Hunk[]
+}
+
+export type PatchResult =
+  | { ok: true; files: { path: string; isNew: boolean; del: number; add: number }[] }
+  | { ok: false; error: string }
+
+const OFFSET_TOLERANCE = 3
+
+export function parseUnifiedDiff(diff: string): PatchFile[] {
+  const files: PatchFile[] = []
+  let current: PatchFile | null = null
+  let currentHunk: Hunk | null = null
+  let pendingHeader: string | null = null
+
+  const lines = diff.replace(/\r\n/g, "\n").split("\n")
+
+  for (const raw of lines) {
+    if (raw.startsWith("--- ")) {
+      pendingHeader = raw.slice(4)
+      continue
+    }
+    if (pendingHeader !== null && raw.startsWith("+++ ")) {
+      const target = raw.slice(4)
+      if (current) files.push(current)
+      current = {
+        path: stripPrefix(target),
+        isNew: pendingHeader === "/dev/null",
+        hunks: [],
+      }
+      currentHunk = null
+      pendingHeader = null
+      continue
+    }
+    if (raw.startsWith("@@ ")) {
+      const m = raw.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/)
+      if (m && current) {
+        currentHunk = {
+          oldStart: parseInt(m[1]!, 10),
+          oldCount: m[2] ? parseInt(m[2], 10) : 1,
+          newStart: parseInt(m[3]!, 10),
+          newCount: m[4] ? parseInt(m[4], 10) : 1,
+          lines: [],
+        }
+        current.hunks.push(currentHunk)
+      }
+      continue
+    }
+    if (currentHunk && current) {
+      if (raw.startsWith("+") && !raw.startsWith("+++")) {
+        currentHunk.lines.push({ type: "add", text: raw.slice(1) })
+      } else if (raw.startsWith("-") && !raw.startsWith("---")) {
+        currentHunk.lines.push({ type: "delete", text: raw.slice(1) })
+      } else if (raw.startsWith(" ")) {
+        currentHunk.lines.push({ type: "context", text: raw.slice(1) })
+      }
+      // "\" 行忽略
+    }
+  }
+  if (current) files.push(current)
+  return files
+}
+
+function stripPrefix(p: string): string {
+  const trimmed = p.trim()
+  if (trimmed === "/dev/null") return trimmed
+  if (trimmed.startsWith("a/")) return trimmed.slice(2)
+  if (trimmed.startsWith("b/")) return trimmed.slice(2)
+  return trimmed
+}
+
+function findMatch(lines: string[], start: number, block: string[]): number {
+  if (block.length === 0) return Math.max(0, Math.min(start, lines.length))
+  for (
+    let pos = Math.max(0, start - OFFSET_TOLERANCE);
+    pos <= Math.min(lines.length - block.length, start + OFFSET_TOLERANCE);
+    pos++
+  ) {
+    let ok = true
+    for (let i = 0; i < block.length; i++) {
+      if (lines[pos + i] !== block[i]) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return pos
+  }
+  return -1
+}
+
+function applyHunk(lines: string[], hunk: Hunk): { lines: string[] } | { error: string } {
+  const block = hunk.lines.filter((l) => l.type !== "add").map((l) => l.text)
+  const pos = findMatch(lines, hunk.oldStart - 1, block)
+  if (pos === -1) {
+    return { error: `第 ${hunk.oldStart} 行附近的 hunk 未找到匹配（需要匹配 ${block.length} 行）` }
+  }
+  const result = [...lines]
+  result.splice(pos, block.length)
+  const adds = hunk.lines.filter((l) => l.type === "add").map((l) => l.text)
+  result.splice(pos, 0, ...adds)
+  return { lines: result }
+}
+
+export function applyPatch(files: PatchFile[], cwd: string = process.cwd()): PatchResult {
+  const applied: { file: PatchFile; content: string }[] = []
+  for (const file of files) {
+    const target = path.resolve(cwd, file.path)
+    if (file.isNew && !existsSync(target)) {
+      const lines: string[] = []
+      for (const hunk of file.hunks) {
+        const r = applyHunk(lines, hunk)
+        if ("error" in r) return { ok: false, error: `${file.path}: ${r.error}` }
+        lines.length = 0
+        lines.push(...r.lines)
+      }
+      applied.push({ file, content: lines.join("\n") })
+      continue
+    }
+    if (!existsSync(target)) {
+      return { ok: false, error: `${file.path}: 文件不存在` }
+    }
+    let content: string
+    try {
+      content = readFileSync2(target)
+    } catch (err: any) {
+      return { ok: false, error: `${file.path}: 读取失败 ${err.message}` }
+    }
+    const lines = content.split("\n")
+    for (const hunk of file.hunks) {
+      const r = applyHunk(lines, hunk)
+      if ("error" in r) return { ok: false, error: `${file.path}: ${r.error}` }
+      lines.length = 0
+      lines.push(...r.lines)
+    }
+    applied.push({ file, content: lines.join("\n") })
+  }
+
+  const changed = applied.map((a) => ({
+    path: a.file.path,
+    isNew: a.file.isNew,
+    del: a.file.hunks.reduce((s, h) => s + h.lines.filter((l) => l.type === "delete").length, 0),
+    add: a.file.hunks.reduce((s, h) => s + h.lines.filter((l) => l.type === "add").length, 0),
+  }))
+  return { ok: true, files: changed }
+}
+
+function readFileSync2(p: string): string {
+  return readFileSyncSync(p)
+}
+```
+
+注意：上面 `readFileSync2`/`readFileSyncSync` 是为了避免与 fs/promises 冲突的占位——**实际实现**应为：
+
+```ts
+import { readFileSync } from "fs"
+
+function readFileSync2(p: string): string {
+  return readFileSync(p, "utf-8")
+}
+```
+
+（`applyPatch` 是同步函数，用 fs.readFileSync；async 写入由工具 execute 层处理。**最终实现请保持 applyPatch 纯同步**，读取用 `readFileSync`（fs），写入在工具 execute 里做。为清晰起见，把写盘逻辑也放进 applyPatch：文件全部应用成功后在内存计算 content，然后由 execute 写盘前 confirm。）
+
+最终 `apply_patch.ts` 的完整结构（以此为准，替换上面占位思路）：
+
+```ts
+import { tool, jsonSchema } from "ai"
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs"
+import path from "path"
+import { confirm, isAutoApprove } from "../confirm.js"
+
+export interface HunkLine {
+  type: "context" | "delete" | "add"
+  text: string
+}
+
+export interface Hunk {
+  oldStart: number
+  oldCount: number
+  newStart: number
+  newCount: number
+  lines: HunkLine[]
+}
+
+export interface PatchFile {
+  path: string
+  isNew: boolean
+  hunks: Hunk[]
+}
+
+export type PatchResult =
+  | { ok: true; files: { path: string; isNew: boolean; del: number; add: number }[] }
+  | { ok: false; error: string }
+
+const OFFSET_TOLERANCE = 3
+
+export function parseUnifiedDiff(diff: string): PatchFile[] {
+  const files: PatchFile[] = []
+  let current: PatchFile | null = null
+  let currentHunk: Hunk | null = null
+  let pendingHeader: string | null = null
+
+  const lines = diff.replace(/\r\n/g, "\n").split("\n")
+
+  for (const raw of lines) {
+    if (raw.startsWith("--- ")) {
+      pendingHeader = raw.slice(4)
+      continue
+    }
+    if (pendingHeader !== null && raw.startsWith("+++ ")) {
+      const target = raw.slice(4)
+      if (current) files.push(current)
+      current = { path: stripPrefix(target), isNew: pendingHeader === "/dev/null", hunks: [] }
+      currentHunk = null
+      pendingHeader = null
+      continue
+    }
+    if (raw.startsWith("@@ ")) {
+      const m = raw.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/)
+      if (m && current) {
+        currentHunk = {
+          oldStart: parseInt(m[1]!, 10),
+          oldCount: m[2] ? parseInt(m[2], 10) : 1,
+          newStart: parseInt(m[3]!, 10),
+          newCount: m[4] ? parseInt(m[4], 10) : 1,
+          lines: [],
+        }
+        current.hunks.push(currentHunk)
+      }
+      continue
+    }
+    if (currentHunk && current) {
+      if (raw.startsWith("+") && !raw.startsWith("+++")) {
+        currentHunk.lines.push({ type: "add", text: raw.slice(1) })
+      } else if (raw.startsWith("-") && !raw.startsWith("---")) {
+        currentHunk.lines.push({ type: "delete", text: raw.slice(1) })
+      } else if (raw.startsWith(" ")) {
+        currentHunk.lines.push({ type: "context", text: raw.slice(1) })
+      }
+    }
+  }
+  if (current) files.push(current)
+  return files
+}
+
+function stripPrefix(p: string): string {
+  const trimmed = p.trim()
+  if (trimmed === "/dev/null") return trimmed
+  if (trimmed.startsWith("a/")) return trimmed.slice(2)
+  if (trimmed.startsWith("b/")) return trimmed.slice(2)
+  return trimmed
+}
+
+function findMatch(lines: string[], start: number, block: string[]): number {
+  if (block.length === 0) return Math.max(0, Math.min(start, lines.length))
+  for (
+    let pos = Math.max(0, start - OFFSET_TOLERANCE);
+    pos <= Math.min(lines.length - block.length, start + OFFSET_TOLERANCE);
+    pos++
+  ) {
+    let ok = true
+    for (let i = 0; i < block.length; i++) {
+      if (lines[pos + i] !== block[i]) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return pos
+  }
+  return -1
+}
+
+function applyHunk(lines: string[], hunk: Hunk): { lines: string[] } | { error: string } {
+  const block = hunk.lines.filter((l) => l.type !== "add").map((l) => l.text)
+  const pos = findMatch(lines, hunk.oldStart - 1, block)
+  if (pos === -1) {
+    return { error: `第 ${hunk.oldStart} 行附近的 hunk 未找到匹配（需要匹配 ${block.length} 行）` }
+  }
+  const result = [...lines]
+  result.splice(pos, block.length)
+  const adds = hunk.lines.filter((l) => l.type === "add").map((l) => l.text)
+  result.splice(pos, 0, ...adds)
+  return { lines: result }
+}
+
+/** 在内存中应用全部文件；成功后返回各文件新内容。 */
+export function buildPatchedFiles(
+  files: PatchFile[],
+  cwd: string = process.cwd(),
+): { ok: true; contents: { file: PatchFile; content: string }[] } | { ok: false; error: string } {
+  const contents: { file: PatchFile; content: string }[] = []
+  for (const file of files) {
+    const target = path.resolve(cwd, file.path)
+    const exists = existsSync(target)
+    if (file.isNew && !exists) {
+      const lines: string[] = []
+      for (const hunk of file.hunks) {
+        const r = applyHunk(lines, hunk)
+        if ("error" in r) return { ok: false, error: `${file.path}: ${r.error}` }
+        lines.length = 0
+        lines.push(...r.lines)
+      }
+      contents.push({ file, content: lines.join("\n") })
+      continue
+    }
+    if (!exists) return { ok: false, error: `${file.path}: 文件不存在` }
+    let content: string
+    try {
+      content = readFileSync(target, "utf-8")
+    } catch (err: any) {
+      return { ok: false, error: `${file.path}: 读取失败 ${err.message}` }
+    }
+    const lines = content.split("\n")
+    for (const hunk of file.hunks) {
+      const r = applyHunk(lines, hunk)
+      if ("error" in r) return { ok: false, error: `${file.path}: ${r.error}` }
+      lines.length = 0
+      lines.push(...r.lines)
+    }
+    contents.push({ file, content: lines.join("\n") })
+  }
+  return { ok: true, contents }
+}
+
+export const applyPatchTool = tool<{ diff: string }, string>({
+  description:
+    "Apply a unified diff to the working tree. Use this for precise multi-file edits or when you have a generated diff. " +
+    "Supports standard unified diff format (---/+++ headers, @@ hunks, context/delete/add lines). " +
+    "New files are created when the diff targets /dev/null. Conflicts are reported without partial writes.",
+  inputSchema: jsonSchema<{ diff: string }>({
+    type: "object",
+    properties: {
+      diff: { type: "string", description: "The unified diff text to apply" },
+    },
+    required: ["diff"],
+  }),
+  execute: async ({ diff }) => {
+    const parsed = parseUnifiedDiff(diff)
+    if (parsed.length === 0) return "Error: 无法解析 diff（缺少 ---/+++ 文件头）"
+    const built = buildPatchedFiles(parsed)
+    if (!built.ok) return `Error: ${built.error}`
+    const summary = built.contents
+      .map((c) => {
+        const del = c.file.hunks.reduce((s, h) => s + h.lines.filter((l) => l.type === "delete").length, 0)
+        const add = c.file.hunks.reduce((s, h) => s + h.lines.filter((l) => l.type === "add").length, 0)
+        return `  ${c.file.path} ${c.file.isNew ? "(new)" : ""} -${del}/+${add}`
+      })
+      .join("\n")
+    if (!isAutoApprove()) {
+      const approved = await confirm(`Apply patch to ${built.contents.length} file(s)?\n${summary}`)
+      if (!approved) return "Patch rejected by user."
+    }
+    for (const c of built.contents) {
+      const target = path.resolve(process.cwd(), c.file.path)
+      mkdirSync(path.dirname(target), { recursive: true })
+      writeFileSync(target, c.content, "utf-8")
+    }
+    return `Applied patch:\n${summary}`
+  },
+})
+```
+
+注意：
+- `buildPatchedFiles` 是纯同步函数（供测试直接调用，不写盘）
+- `applyPatch` 测试 import 的 `parseUnifiedDiff, applyPatch` —— **测试改为 import `parseUnifiedDiff, buildPatchedFiles`**，断言改为检查 `buildPatchedFiles` 返回的 contents（写盘由工具 execute 负责，测试用 `setAutoApprove(true)` 后可走 execute 验证写盘）。测试文件中的 `applyPatch(...)` 调用全部替换为：
+
+```ts
+const built = buildPatchedFiles(parseUnifiedDiff(diff), dir)
+expect(built.ok).toBe(true)
+if (built.ok) expect(built.contents[0]!.content).toBe("line1\nline2-edited\nline3\n")
+```
+
+冲突/不存在用例断言 `built.ok === false` 与 `built.error`。**请按此调整 Step 1 的测试代码**（Step 1 中 `applyPatch` 调用点统一改 `buildPatchedFiles`，断言相应调整）。
+
+- [ ] **Step 4: 注册到 tools/index.ts**
+
+`createChatTools` 与 `createCodeTools` 的 tools 对象都加一行：
+
+```ts
+import { applyPatchTool } from "./apply_patch.js"
+```
+
+```ts
+    apply_patch: applyPatchTool,
+```
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `bun test tests/apply-patch.test.ts`
+Expected: PASS（9 个用例）
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/tools/apply_patch.ts src/tools/index.ts tests/apply-patch.test.ts
+git commit -m "feat: apply_patch 工具支持 unified diff 应用"
+```
+
+---
+
+## Task 4: web_search 参数扩展
+
+**Files:**
+- Modify: `src/tools/web_search.ts`
+- Test: `tests/web-search.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/web-search.test.ts` 末尾追加：
+
+```ts
+test("web_search forwards language and time_range params", async () => {
+  let captured = ""
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = (async (url: any) => {
+    captured = String(url)
+    return new Response(JSON.stringify({ results: [] }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  }) as typeof fetch
+  try {
+    await exec({ query: "q", language: "zh", time_range: "week" }, {})
+    expect(captured).toContain("language=zh")
+    expect(captured).toContain("time_range=week")
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test("web_search ignores an invalid time_range", async () => {
+  let captured = ""
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = (async (url: any) => {
+    captured = String(url)
+    return new Response(JSON.stringify({ results: [] }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  }) as typeof fetch
+  try {
+    await exec({ query: "q", time_range: "decade" }, {})
+    expect(captured).not.toContain("time_range")
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/web-search.test.ts`
+Expected: 新用例 FAIL（URL 不含 language/time_range）
+
+- [ ] **Step 3: 修改 web_search.ts**
+
+```ts
+type WebSearchInput = { query: string; categories?: string; language?: string; time_range?: string }
+
+const VALID_TIME_RANGES = new Set(["day", "week", "month", "year"])
+```
+
+schema properties 追加：
+
+```ts
+      language: { type: "string", description: "Search language code (e.g. zh, en). Passed to the backend when valid" },
+      time_range: { type: "string", description: "Time range filter: day, week, month, year" },
+```
+
+execute：
+
+```ts
+  execute: async ({ query, categories, language, time_range }) => {
+    const cat = categories && VALID_CATEGORIES.has(categories) ? categories : "general"
+    try {
+      const params = new URLSearchParams({
+        q: query,
+        format: "json",
+        categories: cat,
+      })
+      if (language && language.trim()) params.set("language", language.trim())
+      if (time_range && VALID_TIME_RANGES.has(time_range)) params.set("time_range", time_range)
+      const response = await fetch(`${searxngBase()}/search?${params}`, {
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/web-search.test.ts`
+Expected: PASS（2 个原有用例 + 2 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tools/web_search.ts tests/web-search.test.ts
+git commit -m "feat: web_search 支持语言与时间范围参数"
+```
+
+---
+
+## Task 5: chat 模式工具扩展
+
+**Files:**
+- Modify: `src/tools/index.ts`
+- Modify: `src/agent.ts`（buildTools）
+
+- [ ] **Step 1: 修改 tools/index.ts**
+
+`createChatTools` 加 todo（文件顶部已 import todoTool）：
+
+```ts
+export function createChatTools(): Record<string, Tool> {
+  const tools: Record<string, Tool> = {
+    bash: bashTool,
+    read: readTool,
+    write: writeTool,
+    edit: editTool,
+    glob: globTool,
+    grep: grepTool,
+    web_search: webSearchTool,
+    web_fetch: webFetchTool,
+    todo: todoTool,
+    question: questionTool,
+  }
+  return tools
+}
+```
+
+- [ ] **Step 2: 修改 agent.ts buildTools**
+
+现有（约 202-223 行）：
+
+```ts
+async function buildTools(
+  mode: "chat" | "code",
+  modelId: string | undefined,
+  abortSignal: AbortSignal | undefined,
+): Promise<Record<string, Tool>> {
+  const builtinTools = mode === "code" ? createCodeTools() : createChatTools()
+  if (mode === "code") builtinTools["todo"] = createTodoTool()
+  const mcpTools = getMcpTools()
+  const memoryTools = getMemoryTools()
+  const pluginTools = await loadPluginTools()
+  const skills = getSkills()
+  const allTools: Record<string, Tool> = { ...builtinTools, ...memoryTools, ...pluginTools }
+  for (const [id, t] of Object.entries(mcpTools)) allTools[id] = t
+  if (skills.length > 0) allTools["skill"] = getSkillsTool()
+  if (mode === "code") {
+    const { createTaskTool } = await import("./tools/task.js")
+    const { createExploreTool } = await import("./tools/explore.js")
+    allTools["task"] = createTaskTool(modelId, abortSignal)
+    allTools["explore"] = createExploreTool(modelId, abortSignal)
+  }
+  return allTools
+}
+```
+
+改为：
+
+```ts
+async function buildTools(
+  mode: "chat" | "code",
+  modelId: string | undefined,
+  abortSignal: AbortSignal | undefined,
+): Promise<Record<string, Tool>> {
+  const builtinTools = mode === "code" ? createCodeTools() : createChatTools()
+  builtinTools["todo"] = createTodoTool()
+  const mcpTools = getMcpTools()
+  const memoryTools = getMemoryTools()
+  const pluginTools = await loadPluginTools()
+  const skills = getSkills()
+  const allTools: Record<string, Tool> = { ...builtinTools, ...memoryTools, ...pluginTools }
+  for (const [id, t] of Object.entries(mcpTools)) allTools[id] = t
+  if (skills.length > 0) allTools["skill"] = getSkillsTool()
+  const { createExploreTool } = await import("./tools/explore.js")
+  allTools["explore"] = createExploreTool(modelId, abortSignal)
+  if (mode === "code") {
+    const { createTaskTool } = await import("./tools/task.js")
+    allTools["task"] = createTaskTool(modelId, abortSignal)
+  }
+  return allTools
+}
+```
+
+（todo 两种模式都覆盖为 per-run 实例；explore 两种模式都有；task 仅 code）
+
+- [ ] **Step 3: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/tools/index.ts src/agent.ts
+git commit -m "feat: chat 模式提供 todo 与 explore 工具"
+```
+
+---
+
+## Task 6: CLI 增强（history 子命令、mcp --env、update）
+
+**Files:**
+- Create: `src/updater.ts`
+- Modify: `src/cli.ts`
+
+- [ ] **Step 1: 实现 updater.ts**
+
+```ts
+import { readFileSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { execSync } from "child_process"
+
+export function localVersion(): string {
+  const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json")
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"))
+  return pkg.version ?? "0.0.0"
+}
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] ?? 0
+    const vb = pb[i] ?? 0
+    if (va !== vb) return va - vb
+  }
+  return 0
+}
+
+export async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const response = await fetch("https://registry.npmjs.org/min-agent/latest", {
+      signal: AbortSignal.timeout(10000),
+      headers: { Accept: "application/json" },
+    })
+    if (!response.ok) return null
+    const data = (await response.json()) as { version?: string }
+    return data.version ?? null
+  } catch {
+    return null
+  }
+}
+
+export async function runUpdate(): Promise<void> {
+  const current = localVersion()
+  console.log(`当前版本: ${current}`)
+  const latest = await fetchLatestVersion()
+  if (!latest) {
+    console.error("无法检查新版本（网络不可用）。")
+    return
+  }
+  if (compareVersions(current, latest) >= 0) {
+    console.log(`已是最新版本 (${latest})`)
+    return
+  }
+  console.log(`发现新版本: ${latest}`)
+  console.log("正在升级 min-agent...")
+  try {
+    execSync("npm install -g min-agent@latest", { stdio: "inherit" })
+    console.log(`✓ 已升级到 ${latest}，请重启终端后生效`)
+  } catch {
+    console.error("自动升级失败。请手动执行: npm install -g min-agent@latest")
+  }
+}
+```
+
+- [ ] **Step 2: 修改 cli.ts**
+
+**a) printUsage 更新**（Commands 区）：
+
+```
+  min-agent history                 List saved sessions
+  min-agent history delete <id>     Delete a saved session
+  min-agent history rename <id> <t> Rename a saved session
+  min-agent history export <id> [-o <file>]  Export a session as JSON
+  min-agent update                  Check for updates and upgrade
+```
+
+并把 `min-agent mcp add <name> <cmd>` 行后补充：
+
+```
+                                    (--env KEY=VALUE 可重复)
+```
+
+**b) parseMcpAddArgs 加 --env**：
+
+```ts
+function parseMcpAddArgs(argv: string[]): {
+  skipCheck: boolean
+  url?: string
+  token?: string
+  sse: boolean
+  environment: Record<string, string>
+  cmd: string[]
+} {
+  let skipCheck = false
+  let url: string | undefined
+  let token: string | undefined
+  let sse = false
+  const environment: Record<string, string> = {}
+  const cmd: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--skip-check") {
+      skipCheck = true
+      continue
+    }
+    if (a === "--sse") {
+      sse = true
+      continue
+    }
+    if (a === "--url" && argv[i + 1]) {
+      url = argv[++i]
+      continue
+    }
+    if (a === "--token" && argv[i + 1]) {
+      token = argv[++i]
+      continue
+    }
+    if (a === "--env" && argv[i + 1]) {
+      const kv = argv[++i]
+      const eq = kv.indexOf("=")
+      if (eq <= 0) {
+        console.error(`Invalid --env format: ${kv} (use KEY=VALUE)`)
+        process.exit(1)
+      }
+      environment[kv.slice(0, eq)] = kv.slice(eq + 1)
+      continue
+    }
+    cmd.push(a)
+  }
+  return { skipCheck, url, token, sse, environment, cmd }
+}
+```
+
+**c) mcp add case 应用 environment**：
+
+```ts
+          const { skipCheck, url, token, sse, environment, cmd } = parseMcpAddArgs(args.slice(3))
+
+          let entry: McpServerConfig
+          if (url?.trim()) {
+            entry = {
+              url: url.trim(),
+              enabled: true,
+              remoteTransport: sse ? "sse" : "auto",
+            }
+            if (token?.trim()) entry.token = token.trim()
+          } else if (cmd.length > 0) {
+            entry = { command: cmd, enabled: true }
+          } else {
+            console.error("Usage: min-agent mcp add <name> [--skip-check] <command...>")
+            console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse] [--token <bearer>] [--skip-check]")
+            process.exit(1)
+          }
+          if (Object.keys(environment).length > 0) entry.environment = environment
+```
+
+**d) history 分支扩展**（在现有 list 逻辑前加子命令分发）：
+
+```ts
+    case "history": {
+      const subcommand = args[1]
+      if (subcommand === "delete") {
+        const id = args[2]
+        if (!id) { console.error("Usage: min-agent history delete <id>"); process.exit(1) }
+        const { deleteSession } = await import("./sessions.js")
+        if (deleteSession(id)) {
+          console.log(`✓ 会话 ${id} 已删除`)
+        } else {
+          console.error(`会话 ${id} 不存在`)
+          process.exit(1)
+        }
+        break
+      }
+      if (subcommand === "rename") {
+        const id = args[2]
+        const title = args.slice(3).join(" ")
+        if (!id || !title) { console.error("Usage: min-agent history rename <id> <title>"); process.exit(1) }
+        const { renameSession } = await import("./sessions.js")
+        if (renameSession(id, title)) {
+          console.log(`✓ 会话 ${id} 已重命名为: ${title}`)
+        } else {
+          console.error(`会话 ${id} 不存在`)
+          process.exit(1)
+        }
+        break
+      }
+      if (subcommand === "export") {
+        const id = args[2]
+        if (!id) { console.error("Usage: min-agent history export <id> [-o <file>]"); process.exit(1) }
+        const { loadSession } = await import("./sessions.js")
+        const session = loadSession(id)
+        if (!session) {
+          console.error(`会话 ${id} 不存在`)
+          process.exit(1)
+        }
+        const json = JSON.stringify(session, null, 2)
+        const outIdx = args.indexOf("-o")
+        const outFile = outIdx !== -1 ? args[outIdx + 1] : undefined
+        if (outFile) {
+          writeFileSync(outFile, json, "utf-8")
+          console.log(`✓ 会话 ${id} 已导出到 ${outFile}`)
+        } else {
+          console.log(json)
+        }
+        break
+      }
+      const { listSessions } = await import("./sessions.js")
+      const sessions = listSessions()
+      if (sessions.length === 0) {
+        console.log("No saved sessions.")
+        console.log("Sessions are auto-saved when you exit interactive chat.")
+      } else {
+        console.log(`Sessions (${sessions.length}):`)
+        for (const s of sessions.slice(0, 20)) {
+          const date = s.updated.split("T")[0]
+          console.log(`  ${s.id}  ${date}  ${s.title} (${s.messageCount} msgs)`)
+        }
+        console.log("\nResume with: min-agent chat --resume <id>")
+      }
+      break
+    }
+```
+
+（`writeFileSync` 已在 cli.ts import）
+
+**e) update case**（在 `case "init"` 之前添加）：
+
+```ts
+    case "update": {
+      const { runUpdate } = await import("./updater.js")
+      await runUpdate()
+      break
+    }
+```
+
+- [ ] **Step 3: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过
+
+- [ ] **Step 4: 冒烟**
+
+Run: `bun run src/cli.ts history delete`（应提示 Usage）与 `bun run src/cli.ts --help`
+Expected: 正常输出
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/updater.ts src/cli.ts
+git commit -m "feat: CLI history 子命令、mcp --env 与 update 升级"
+```
+
+---
+
+## Task 7: agent.ts 采样参数 options
+
+**Files:**
+- Modify: `src/agent.ts`
+
+- [ ] **Step 1: 实现**
+
+在 `RunOnceCallbacks` 接口之后添加：
+
+```ts
+export interface RunOptions {
+  temperature?: number
+  maxTokens?: number
+  topP?: number
+}
+```
+
+`runOnceCore` 签名加 `options` 参数（mode 之后）：
+
+```ts
+async function runOnceCore(
+  messages: ModelMessage[],
+  systemPrompt: string,
+  modelId: string | undefined,
+  abortSignal: AbortSignal | undefined,
+  callbacks: RunOnceCallbacks | undefined,
+  tracker: TokenTracker | undefined,
+  mode: "chat" | "code",
+  options?: RunOptions,
+): Promise<void> {
+```
+
+`streamText` 调用加条件展开（`maxRetries` 之后、`abortSignal` 之后）：
+
+```ts
+    const result = streamText({
+      model,
+      system: systemPrompt,
+      messages,
+      tools: allTools,
+      stopWhen: stepCountIs(MAX_STEPS),
+      maxRetries: 3,
+      abortSignal,
+      ...(options?.temperature != null ? { temperature: options.temperature } : {}),
+      ...(options?.maxTokens != null ? { maxTokens: options.maxTokens } : {}),
+      ...(options?.topP != null ? { topP: options.topP } : {}),
+      onStepFinish({ stepNumber }) {
+        stepCount = stepNumber
+        if (stepNumber >= MAX_STEPS) maxStepsReached = true
+      },
+      onError() {},
+    })
+```
+
+`runOnce` 与 `runOnceWithSystem` 加 options 参数并透传：
+
+```ts
+export async function runOnce(
+  messages: ModelMessage[],
+  instructions: string[],
+  modelId?: string,
+  abortSignal?: AbortSignal,
+  callbacks?: RunOnceCallbacks,
+  tracker?: TokenTracker,
+  options?: RunOptions,
+) {
+  await runOnceCore(messages, buildSystemPrompt(instructions), modelId, abortSignal, callbacks, tracker, "chat", options)
+}
+
+/** runOnce variant that accepts a pre-built system prompt (for code mode) */
+export async function runOnceWithSystem(
+  messages: ModelMessage[],
+  systemPrompt: string,
+  modelId?: string,
+  abortSignal?: AbortSignal,
+  callbacks?: RunOnceCallbacks,
+  tracker?: TokenTracker,
+  options?: RunOptions,
+) {
+  await runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, "code", options)
+}
+```
+
+- [ ] **Step 2: 验证**
+
+Run: `bun run typecheck`（仓库根）和 `bun test`
+Expected: 无错误，全部通过（现有调用点不传 options，行为不变）
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add src/agent.ts
+git commit -m "feat: agent 支持采样参数透传"
+```
+
+---
+
+## Task 8: serve 端点 — sessions/:id、rename、chat/undo
+
+**Files:**
+- Modify: `src/serve.ts`
+- Test: `tests/serve.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/serve.test.ts` 追加（import 加 `saveSession`，从 `../src/sessions.js`）：
+
+```ts
+import { saveSession } from "../src/sessions.js"
+
+test("F6: GET /v1/sessions/:id 返回会话详情", async () => {
+  const id = saveSession([{ role: "user", content: "hello" }])
+  const res = await fetch(`http://127.0.0.1:${port}/v1/sessions/${id}`)
+  expect(res.status).toBe(200)
+  const body = await res.json()
+  expect(body.session.meta.id).toBe(id)
+  expect(body.session.messages).toHaveLength(1)
+})
+
+test("F6: GET /v1/sessions/:id 不存在的会话返回 404", async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/v1/sessions/no-such-id`)
+  expect(res.status).toBe(404)
+})
+
+test("F6: POST /v1/sessions/:id/rename 重命名会话", async () => {
+  const id = saveSession([{ role: "user", content: "hi" }])
+  const { status, text } = await postJson(`/v1/sessions/${id}/rename`, { title: "renamed" })
+  expect(status).toBe(200)
+  expect(JSON.parse(text).title).toBe("renamed")
+  const session = JSON.parse(await (await fetch(`http://127.0.0.1:${port}/v1/sessions/${id}`)).text())
+  expect(session.session.meta.title).toBe("renamed")
+})
+
+test("F6: POST /v1/sessions/:id/rename 缺 title 返回 400", async () => {
+  const id = saveSession([{ role: "user", content: "hi" }])
+  const { status } = await postJson(`/v1/sessions/${id}/rename`, {})
+  expect(status).toBe(400)
+})
+
+test("F6: POST /v1/chat/undo 截断到最后一条 user 消息", async () => {
+  const id = saveSession([
+    { role: "user", content: "q1" },
+    { role: "assistant", content: "a1" },
+    { role: "user", content: "q2" },
+    { role: "assistant", content: "a2" },
+  ])
+  const { status, text } = await postJson("/v1/chat/undo", { session_id: id })
+  expect(status).toBe(200)
+  const body = JSON.parse(text)
+  expect(body.message_count).toBe(3)
+  expect(body.messages[2]!.role).toBe("user")
+  expect(body.messages[2]!.content).toBe("q2")
+})
+
+test("F6: POST /v1/chat/undo 缺 session_id 返回 400", async () => {
+  const { status } = await postJson("/v1/chat/undo", {})
+  expect(status).toBe(400)
+})
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新用例 FAIL（404 或 400）
+
+- [ ] **Step 3: 实现 serve.ts**
+
+**a)** import 加 `renameSession`：
+
+```ts
+import { loadSession, saveSession, listSessions, deleteSession, renameSession } from "./sessions.js"
+```
+
+**b)** 在 `DELETE /v1/sessions/` 路由之后添加：
+
+```ts
+      if (req.method === "GET" && pathname.startsWith("/v1/sessions/")) {
+        const id = pathname.slice("/v1/sessions/".length)
+        if (!id) { sendJson(res, 400, { error: "missing_session_id" }); return }
+        const session = loadSession(id)
+        if (!session) { sendJson(res, 404, { error: "session_not_found", session_id: id }); return }
+        sendJson(res, 200, { session })
+        return
+      }
+
+      if (req.method === "POST" && pathname.startsWith("/v1/sessions/") && pathname.endsWith("/rename")) {
+        const id = pathname.slice("/v1/sessions/".length, -"/rename".length)
+        const parsed = await readJsonBody<{ title?: string }>(req)
+        if (!parsed.ok) { sendJsonError(res, parsed); return }
+        const title = parsed.value.title?.trim()
+        if (!title) { sendJson(res, 400, { error: "missing_title" }); return }
+        if (!renameSession(id, title)) { sendJson(res, 404, { error: "session_not_found", session_id: id }); return }
+        sendJson(res, 200, { ok: true, session_id: id, title })
+        return
+      }
+```
+
+**c)** 在 `POST /v1/chat/compact` 路由附近添加 chat/undo：
+
+```ts
+      if (req.method === "POST" && pathname === "/v1/chat/undo") {
+        const parsed = await readJsonBody<{ session_id?: string }>(req)
+        if (!parsed.ok) { sendJsonError(res, parsed); return }
+        const body = parsed.value
+        if (!body.session_id) { sendJson(res, 400, { error: "missing_session_id" }); return }
+        const session = loadSession(body.session_id)
+        if (!session) { sendJson(res, 404, { error: "session_not_found" }); return }
+        let userIdx = -1
+        for (let i = session.messages.length - 1; i >= 0; i--) {
+          if (session.messages[i]!.role === "user") {
+            userIdx = i
+            break
+          }
+        }
+        if (userIdx === -1) { sendJson(res, 400, { error: "no_user_message" }); return }
+        session.messages = session.messages.slice(0, userIdx + 1)
+        saveSession(session.messages, body.session_id)
+        sendJson(res, 200, { ok: true, message_count: session.messages.length, messages: session.messages })
+        return
+      }
+```
+
+注意：chat/undo 路由必须放在 `/v1/chat` 的 POST 精确匹配之前或之后均可（路径不同）；放在 `/v1/chat/compact` 之后即可。
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/serve.test.ts`
+Expected: PASS（原有 + 6 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/serve.ts tests/serve.test.ts
+git commit -m "feat: API sessions 详情/重命名与会话撤销端点"
+```
+
+---
+
+## Task 9: serve 端点 — skills/mcp toggle、paste code
+
+**Files:**
+- Modify: `src/serve.ts`
+- Test: `tests/serve.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/serve.test.ts` 末尾追加：
+
+```ts
+test("F7: POST /v1/skills/:name/disable 与 enable", async () => {
+  const { status } = await postJson("/v1/skills/my-skill/disable", {})
+  expect(status).toBe(200)
+  const config = JSON.parse(require("fs").readFileSync(path.join(configDir, "config.json"), "utf-8"))
+  expect(config.disabledSkills).toContain("my-skill")
+  await postJson("/v1/skills/my-skill/enable", {})
+  const config2 = JSON.parse(require("fs").readFileSync(path.join(configDir, "config.json"), "utf-8"))
+  expect(config2.disabledSkills ?? []).not.toContain("my-skill")
+})
+
+test("F7: POST /v1/mcp/:name/disable 与 enable", async () => {
+  const { loadMcpConfig, saveMcpConfig } = await import("../src/mcp.js")
+  const cfg = loadMcpConfig()
+  cfg.mcpServers["test-server"] = { command: ["echo", "hi"], enabled: true }
+  saveMcpConfig(cfg)
+  const { status } = await postJson("/v1/mcp/test-server/disable", {})
+  expect(status).toBe(200)
+  expect(loadMcpConfig().mcpServers["test-server"]!.enabled).toBe(false)
+  await postJson("/v1/mcp/test-server/enable", {})
+  expect(loadMcpConfig().mcpServers["test-server"]!.enabled).toBe(true)
+})
+
+test("F7: POST /v1/mcp/:name/disable 不存在的服务器返回 404", async () => {
+  const { status } = await postJson("/v1/mcp/no-such-server/disable", {})
+  expect(status).toBe(404)
+})
+
+test("F7: POST /v1/paste 支持 code 模式", async () => {
+  const { status, text } = await postJson("/v1/paste", {
+    image_base64: PNG_B64,
+    message: "分析",
+    code: true,
+    stream: false,
+  })
+  expect(status).toBe(200)
+  const body = JSON.parse(text)
+  expect(body.mode).toBe("code")
+  expect(body.project).toBeTruthy()
+})
+```
+
+注意：测试中避免 `require`，改用顶部已 import 的 `readFileSync`（`tests/serve.test.ts` 顶部已 import `readFileSync` from "fs"）。skills 测试改用：
+
+```ts
+test("F7: POST /v1/skills/:name/disable 与 enable", async () => {
+  const { status } = await postJson("/v1/skills/my-skill/disable", {})
+  expect(status).toBe(200)
+  const config = JSON.parse(readFileSync(path.join(configDir, "config.json"), "utf-8"))
+  expect(config.disabledSkills).toContain("my-skill")
+  await postJson("/v1/skills/my-skill/enable", {})
+  const config2 = JSON.parse(readFileSync(path.join(configDir, "config.json"), "utf-8"))
+  expect(config2.disabledSkills ?? []).not.toContain("my-skill")
+})
+```
+
+（注意：config.json 的读取与 saveConfig 的缓存——serve 进程的 loadConfig 有 mtime 缓存，测试进程直接读文件断言即可）
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新用例 FAIL（404）
+
+- [ ] **Step 3: 实现 serve.ts**
+
+**a)** 在 skills 路由（`GET /v1/skills`）之后添加：
+
+```ts
+      const skillToggle = pathname.match(/^\/v1\/skills\/([^/]+)\/(enable|disable)$/)
+      if (req.method === "POST" && skillToggle) {
+        const name = decodeURIComponent(skillToggle[1]!)
+        const enabled = skillToggle[2] === "enable"
+        const config = loadConfig()
+        const disabled = new Set(config.disabledSkills ?? [])
+        if (enabled) disabled.delete(name)
+        else disabled.add(name)
+        config.disabledSkills = [...disabled]
+        saveConfig(config)
+        sendJson(res, 200, { ok: true, name, enabled })
+        return
+      }
+```
+
+（需要 `saveConfig` import：`import { loadConfig, saveConfig, fetchModels, isConfigured } from "./config.js"`）
+
+**b)** 在 MCP DELETE 路由之后添加：
+
+```ts
+      const mcpToggle = pathname.match(/^\/v1\/mcp\/([^/]+)\/(enable|disable)$/)
+      if (req.method === "POST" && mcpToggle) {
+        const name = decodeURIComponent(mcpToggle[1]!)
+        const enabled = mcpToggle[2] === "enable"
+        const { loadMcpConfig, saveMcpConfig } = await import("./mcp.js")
+        const config = loadMcpConfig()
+        if (!config.mcpServers[name]) { sendJson(res, 404, { error: "mcp_not_found", name }); return }
+        config.mcpServers[name]!.enabled = enabled
+        saveMcpConfig(config)
+        sendJson(res, 200, { ok: true, name, enabled })
+        return
+      }
+```
+
+**c)** /v1/paste 支持 code 模式：
+
+paste 的 body 类型与提取处（约 575 行）改为：
+
+```ts
+        const parsed = await readJsonBody<{ image_base64?: string; mime_type?: string; message?: string; session_id?: string; model?: string; stream?: boolean; code?: boolean; temperature?: number; maxTokens?: number; topP?: number }>(req)
+```
+
+提取处添加：
+
+```ts
+        const codeMode = body.code === true
+```
+
+流式分支：
+
+```ts
+        if (stream) {
+          res.writeHead(200, sseHeaders(c))
+          res.flushHeaders?.()
+          const callbacks = createSseCallbacks(res, messages, { sessionId })
+          try {
+            if (codeMode) {
+              const project = scanProject()
+              const system = buildCodeSystemPrompt(project, instructions)
+              await runOnceWithSystem(messages, system, modelId, abort.signal, callbacks)
+            } else {
+              await runOnce(messages, instructions, modelId, abort.signal, callbacks)
+            }
+          } catch (err: any) {
+            if (!res.writableEnded) {
+              sseWrite(res, { type: "fatal", message: err?.message ?? String(err) })
+              res.end()
+            }
+          }
+        } else {
+          const { callbacks, toolCalls, toolResults, finishInfo } = createJsonCallbacks()
+          if (codeMode) {
+            const project = scanProject()
+            const system = buildCodeSystemPrompt(project, instructions)
+            await runOnceWithSystem(messages, system, modelId, abort.signal, callbacks)
+            sendJson(res, 200, {
+              messages,
+              assistant: [...messages].reverse().find((m) => m.role === "assistant") ?? null,
+              tool_calls: toolCalls,
+              tool_results: toolResults,
+              session_id: sessionId ? saveSessionSafe(messages, sessionId) : undefined,
+              step_count: finishInfo()?.stepCount ?? 0,
+              usage: finishInfo()?.usage ?? null,
+              has_error: finishInfo()?.hasError ?? false,
+              aborted: finishInfo()?.aborted ?? false,
+              max_steps_reached: finishInfo()?.maxStepsReached ?? false,
+              mode: "code",
+              project,
+            })
+          } else {
+            await runOnce(messages, instructions, modelId, abort.signal, callbacks)
+            const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant")
+            let saved: string | undefined
+            if (sessionId) { try { saved = saveSession(messages, sessionId) } catch {} }
+            const fi = finishInfo()
+            sendJson(res, 200, {
+              messages,
+              assistant: lastAssistant ?? null,
+              tool_calls: toolCalls,
+              tool_results: toolResults,
+              session_id: saved,
+              step_count: fi?.stepCount ?? 0,
+              usage: fi?.usage ?? null,
+              has_error: fi?.hasError ?? false,
+              aborted: fi?.aborted ?? false,
+              max_steps_reached: fi?.maxStepsReached ?? false,
+            })
+          }
+        }
+```
+
+注意：上述代码中 `saveSessionSafe` 是占位——**实际实现**保持与现有一致的保存逻辑（`if (sessionId) { try { saved = saveSession(messages, sessionId) } catch {} }`），并让 `assistant` 变量在分支前提取。为避免分支重复，重写整个 paste 非流式部分为：
+
+```ts
+        } else {
+          const { callbacks, toolCalls, toolResults, finishInfo } = createJsonCallbacks()
+          let project: ProjectInfo | undefined
+          if (codeMode) {
+            project = scanProject()
+            const system = buildCodeSystemPrompt(project, instructions)
+            await runOnceWithSystem(messages, system, modelId, abort.signal, callbacks)
+          } else {
+            await runOnce(messages, instructions, modelId, abort.signal, callbacks)
+          }
+          const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant")
+          let saved: string | undefined
+          if (sessionId) { try { saved = saveSession(messages, sessionId) } catch {} }
+          const fi = finishInfo()
+          sendJson(res, 200, {
+            messages,
+            assistant: lastAssistant ?? null,
+            tool_calls: toolCalls,
+            tool_results: toolResults,
+            session_id: saved,
+            step_count: fi?.stepCount ?? 0,
+            usage: fi?.usage ?? null,
+            has_error: fi?.hasError ?? false,
+            aborted: fi?.aborted ?? false,
+            max_steps_reached: fi?.maxStepsReached ?? false,
+            ...(codeMode ? { mode: "code", project } : {}),
+          })
+        }
+```
+
+流式分支同样用 project 变量（code 时）并保持 createSseCallbacks 的 opts 不带 project（paste 不做 session save 变更）。**以这个最终版本为准**。
+
+（`ProjectInfo` 类型已在 serve.ts import 中：`import { scanProject, buildCodeSystemPrompt, type ProjectInfo } from "./code-mode.js"`）
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/serve.test.ts`
+Expected: PASS（原有 + 4 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/serve.ts tests/serve.test.ts
+git commit -m "feat: API skills/mcp 启停端点与 paste code 模式"
+```
+
+---
+
+## Task 10: serve 端点 — GET /v1/cost + 采样参数透传
+
+**Files:**
+- Modify: `src/serve.ts`
+- Modify: `src/agent.ts`（Task 7 已完成，此任务只需 serve 透传）
+- Test: `tests/serve.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/serve.test.ts` 末尾追加：
+
+```ts
+test("F8: GET /v1/cost 返回价格与成本", async () => {
+  const res = await fetch(`http://127.0.0.1:${port}/v1/cost?model=${BAD_MODEL}&input=1000000&output=500000`)
+  expect(res.status).toBe(200)
+  const body = await res.json()
+  expect(body.model).toBe(BAD_MODEL)
+  expect(body.cost_usd).toBe(20)
+})
+
+test("F8: /v1/chat 接受采样参数不报错", async () => {
+  const { status } = await postJson("/v1/chat", {
+    message: "say hi",
+    stream: false,
+    temperature: 0.5,
+    maxTokens: 100,
+    topP: 0.9,
+  })
+  expect(status).toBe(200)
+})
+```
+
+注意：cost 测试需要 config.json 提供 pricing 覆盖（避免网络）。在 `beforeAll` 的 config.json 写入中加入：
+
+```ts
+  writeFileSync(
+    path.join(configDir, "config.json"),
+    JSON.stringify({
+      provider: { baseURL: "http://127.0.0.1:1/v1", apiKey: "test", defaultModel: BAD_MODEL },
+      pricing: { [BAD_MODEL]: { inputPerMillion: 10, outputPerMillion: 20 } },
+    }),
+  )
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新用例 FAIL（404 或 cost_usd 为 null）
+
+- [ ] **Step 3: 实现 serve.ts**
+
+**a)** import 加 pricing：
+
+```ts
+import { getModelPrice, estimateCost } from "./pricing.js"
+```
+
+**b)** 在 `/v1/context` 路由之后添加 cost：
+
+```ts
+      if (req.method === "GET" && pathname === "/v1/cost") {
+        const config = loadConfig()
+        const modelId = url.searchParams.get("model") ?? config.provider?.defaultModel ?? null
+        const input = parseInt(url.searchParams.get("input") ?? "0", 10)
+        const output = parseInt(url.searchParams.get("output") ?? "0", 10)
+        const price = modelId ? await getModelPrice(modelId) : null
+        const cost = price ? estimateCost({ inputTokens: input, outputTokens: output }, price) : null
+        sendJson(res, 200, { model: modelId, price, cost_usd: cost })
+        return
+      }
+```
+
+**c)** ChatBody 加采样参数（约 233 行）：
+
+```ts
+interface ChatBody {
+  message?: string
+  messages?: ModelMessage[]
+  model?: string
+  stream?: boolean
+  session_id?: string
+  images?: string[]
+  temperature?: number
+  maxTokens?: number
+  topP?: number
+}
+```
+
+**d)** handleChatRequest 中提取 runOptions（在 `abort` 定义之后）：
+
+```ts
+      const runOptions: { temperature?: number; maxTokens?: number; topP?: number } = {
+        temperature: typeof body.temperature === "number" ? body.temperature : undefined,
+        maxTokens: typeof body.maxTokens === "number" ? body.maxTokens : undefined,
+        topP: typeof body.topP === "number" ? body.topP : undefined,
+      }
+```
+
+`run` 函数改为：
+
+```ts
+      const run = (callbacks: RunOnceCallbacks | undefined) =>
+        codeMode
+          ? runOnceWithSystem(messages, codeSystemPrompt!, modelId, abort.signal, callbacks, undefined, runOptions)
+          : runOnce(messages, instructions, modelId, abort.signal, callbacks, undefined, runOptions)
+```
+
+**e)** paste 也透传采样参数：paste 分支的 runOnce 调用加 `undefined, runOptions`（paste 的 body 类型已在 Task 9 扩展）。在 paste 分支提取处添加：
+
+```ts
+        const runOptions: { temperature?: number; maxTokens?: number; topP?: number } = {
+          temperature: typeof body.temperature === "number" ? body.temperature : undefined,
+          maxTokens: typeof body.maxTokens === "number" ? body.maxTokens : undefined,
+          topP: typeof body.topP === "number" ? body.topP : undefined,
+        }
+```
+
+流式与 JSON 分支的 runOnce/runOnceWithSystem 调用加 `undefined, runOptions`。
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `bun test tests/serve.test.ts`
+Expected: PASS（原有 + 2 个新用例）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/serve.ts tests/serve.test.ts
+git commit -m "feat: API 成本端点与采样参数透传"
+```
+
+---
+
+## Task 11: 文档同步（API.md、README、usage）
+
+**Files:**
+- Modify: `docs/API.md`
+- Modify: `README.md`
+
+- [ ] **Step 1: 更新 API.md**
+
+**a)** 端点一览表追加：
+
+```markdown
+| GET | `/v1/sessions/:id` | 会话详情 |
+| POST | `/v1/sessions/:id/rename` | 重命名会话 |
+| POST | `/v1/chat/undo` | 撤销最后一轮 |
+| POST | `/v1/skills/:name/enable` | 启用技能 |
+| POST | `/v1/skills/:name/disable` | 禁用技能 |
+| POST | `/v1/mcp/:name/enable` | 启用 MCP 服务器 |
+| POST | `/v1/mcp/:name/disable` | 禁用 MCP 服务器 |
+| GET | `/v1/cost` | 模型价格与成本估算 |
+```
+
+**b)** `POST /v1/chat` 请求字段表追加：
+
+```markdown
+| `temperature` | number | 采样温度（透传模型 API） |
+| `maxTokens` | number | 最大输出 token 数 |
+| `topP` | number | 核采样参数 |
+```
+
+**c)** `POST /v1/paste` 请求字段表追加：
+
+```markdown
+| `code` | boolean | 使用 code 模式（项目感知） |
+| `temperature` | number | 采样温度 |
+| `maxTokens` | number | 最大输出 token 数 |
+| `topP` | number | 核采样参数 |
+```
+
+code 模式的响应说明追加："`code: true` 时响应额外包含 `mode: "code"` 与 `project` 字段。"
+
+**d)** 新增端点说明章节（sessions/rename/undo/skills toggle/mcp toggle/cost），参考现有章节格式：
+
+```markdown
+## `GET /v1/sessions/:id`
+
+```json
+{ "session": { "meta": { "id": "abc", "title": "...", ... }, "messages": [...] } }
+```
+
+## `POST /v1/sessions/:id/rename`
+
+```json
+// 请求
+{ "title": "new title" }
+// 响应
+{ "ok": true, "session_id": "abc", "title": "new title" }
+```
+
+## `POST /v1/chat/undo`
+
+```json
+// 请求
+{ "session_id": "abc123" }
+// 响应
+{ "ok": true, "message_count": 3, "messages": [...] }
+```
+
+截断到最后一条 user 消息（保留该消息，删除其后的 assistant/tool 消息）。
+
+## `POST /v1/skills/:name/enable` / `/disable`
+
+```json
+{ "ok": true, "name": "my-skill", "enabled": false }
+```
+
+## `POST /v1/mcp/:name/enable` / `/disable`
+
+```json
+{ "ok": true, "name": "fs", "enabled": true }
+```
+
+## `GET /v1/cost`
+
+| 参数 | 说明 |
+|------|------|
+| `model` | 模型 ID（默认配置默认模型） |
+| `input` | 输入 token 数 |
+| `output` | 输出 token 数 |
+
+```json
+{ "model": "gpt-4o", "price": { "inputPerMillion": 2.5, "outputPerMillion": 10 }, "cost_usd": 7.5 }
+```
+```
+
+- [ ] **Step 2: 更新 README.md**
+
+Commands 区（约 27-40 行）更新：
+
+```markdown
+min-agent history                 # List saved sessions
+min-agent history delete <id>     # Delete a session
+min-agent history rename <id> <t> # Rename a session
+min-agent history export <id> [-o file]  # Export a session as JSON
+min-agent update                  # Check for updates and upgrade
+```
+
+MCP 区补充 --env 示例：
+
+```markdown
+min-agent mcp add <name> <cmd...> --env KEY=VALUE # Local stdio with env vars
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add docs/API.md README.md
+git commit -m "docs: 第二批 API 与 CLI 文档同步"
+```
+
+---
+
+## Task 12: 全量验证 + 冒烟
+
+- [ ] **Step 1: 类型检查**
+
+Run: `bun run typecheck`（仓库根）
+Expected: 无错误
+
+- [ ] **Step 2: 全量测试**
+
+Run: `bun test`
+Expected: 全部通过
+
+- [ ] **Step 3: 手动冒烟**
+
+Run:
+```bash
+bun run src/cli.ts --help
+bun run src/cli.ts history export no-such-id
+bun run src/cli.ts history delete no-such-id
+bun run src/cli.ts mcp add test echo hi --env FOO=bar --skip-check
+bun run src/cli.ts mcp info test
+bun run src/cli.ts mcp remove test
+```
+
+预期：help 含新命令；export/delete 报"会话不存在" exit 1；mcp add 显示 `(0 tools detected)` 且 info 显示 Env: FOO；remove 成功。
+
+- [ ] **Step 4: 提交（如有遗留改动）**
+
+```bash
+git add -A
+git commit -m "chore: 第二批验证收尾"
+```
+
+---
+
+## 自审记录
+
+**Spec 覆盖：**
+- history delete/rename/export → Task 6
+- mcp add --env → Task 6
+- update 自动升级 → Task 6（updater.ts）
+- bash cwd → Task 1
+- apply_patch → Task 3
+- write append → Task 2
+- web_search 参数 → Task 4
+- chat 模式工具 → Task 5
+- GET /v1/sessions/:id、rename → Task 8
+- skills/mcp enable-disable → Task 9
+- paste code → Task 9
+- GET /v1/cost → Task 10
+- POST /v1/chat/undo → Task 8
+- 采样参数透传 → Task 7（agent）+ Task 10（serve）
+- 文档同步 → Task 11
+
+**类型一致性：** `RunOptions` 在 Task 7 定义并被 Task 10 使用；`buildPatchedFiles`/`parseUnifiedDiff` 在 Task 3 定义并被测试使用；`PatchResult` 判别联合类型一致。