min-agent 0.2.1 → 0.4.0

package/docs/superpowers/plans/2026-08-20-unified-tui-default.md

@@ -0,0 +1,631 @@
+# 根命令默认 TUI + 合并 chat/code — 实现计划
+
+> **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:** `min-agent` 无子命令进入交互 TUI（可带首条 prompt）；`min-agent exec` 非交互跑完退出；运行时与 HTTP 取消 chat/code 双模式，统一为原 code 能力。
+
+**Architecture:** 分发逻辑抽到 `src/cli-invoke.ts`（`cli.ts` 会在 import 时跑 `main`，测试不能碰它）。agent 去掉 `mode`，工具只留 `createTools()`。TUI 始终 coding prompt；HTTP `/v1/chat` 与 `/v1/code` 走同一 handler。
+
+**Tech Stack:** TypeScript, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-20-unified-tui-default-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|---|---|
+| `src/cli-invoke.ts`(新) | `parseFlags`、`resolveCliInvocation`、`resolveExecPrompt`、保留子命令表 |
+| `tests/cli-invoke.test.ts`(新) | 分发与 exec prompt 纯函数测试 |
+| `src/cli.ts`(改) | 用 invocation 分发；空参数进 TUI；`exec`；Usage |
+| `src/tools/index.ts`(改) | `createChatTools`/`createCodeTools` → `createTools()` |
+| `src/tools/task.ts`(改) | 改调 `createTools()` |
+| `src/agent.ts`(改) | 去 mode；`runOnce` 用 coding prompt；返回 `{ hasError }` |
+| `src/tui-chat.ts`(改) | 去 `mode`，加 `initialPrompt` |
+| `src/tui/agent-runner.ts`(改) | 去 mode 分支，始终 `runOnceWithSystem` |
+| `src/tui/slash-handler.ts`(改) | `/sessions` 恢复示例改为根命令 `--resume` |
+| `src/serve.ts`(改) | chat/code/paste 统一项目感知，去掉 `mode` 字段 |
+| `tests/serve.test.ts`(改) | 断言 `project`、无 `mode` |
+| `README.md`(改) | Quick Start / Commands |
+| `docs/API.md`(改) | chat/code/paste 文档 |
+
+---
+
+## Task 1: cli-invoke.ts — 分发纯函数
+
+**Files:**
+- Create: `src/cli-invoke.ts`
+- Test: `tests/cli-invoke.test.ts`
+- Modify: `src/cli.ts`（本 task 只把 `parseFlags`/`ParsedFlags` 迁走并改 import，**不改 main 行为**）
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import { parseFlags, resolveCliInvocation, resolveExecPrompt } from "../src/cli-invoke.js"
+
+test("empty argv is tui with no prompt", () => {
+  const inv = resolveCliInvocation([])
+  expect(inv).toEqual({ kind: "tui", flags: { images: [], positionals: [] } })
+})
+
+test("first token --help is help", () => {
+  expect(resolveCliInvocation(["--help"])).toEqual({ kind: "help" })
+  expect(resolveCliInvocation(["-h"])).toEqual({ kind: "help" })
+})
+
+test("first token --version is version", () => {
+  expect(resolveCliInvocation(["--version"])).toEqual({ kind: "version" })
+  expect(resolveCliInvocation(["-v"])).toEqual({ kind: "version" })
+})
+
+test("reserved command strips the command name from positionals", () => {
+  const inv = resolveCliInvocation(["setup"])
+  expect(inv.kind).toBe("command")
+  if (inv.kind !== "command") return
+  expect(inv.command).toBe("setup")
+  expect(inv.flags.positionals).toEqual([])
+})
+
+test("exec with message is command", () => {
+  const inv = resolveCliInvocation(["exec", "hello", "world"])
+  expect(inv).toMatchObject({ kind: "command", command: "exec" })
+  if (inv.kind !== "command") return
+  expect(inv.flags.positionals).toEqual(["hello", "world"])
+})
+
+test("chat and code are reserved aliases", () => {
+  expect(resolveCliInvocation(["chat"]).kind).toBe("command")
+  expect(resolveCliInvocation(["code", "fix", "it"])).toMatchObject({
+    kind: "command",
+    command: "code",
+    flags: { positionals: ["fix", "it"], images: [] },
+  })
+})
+
+test("bare prompt is tui", () => {
+  expect(resolveCliInvocation(["修", "lint"])).toMatchObject({
+    kind: "tui",
+    flags: { positionals: ["修", "lint"], images: [] },
+  })
+})
+
+test("flags before a reserved command still dispatch the command", () => {
+  const inv = resolveCliInvocation(["--model", "gpt-4o", "exec", "hi"])
+  expect(inv.kind).toBe("command")
+  if (inv.kind !== "command") return
+  expect(inv.command).toBe("exec")
+  expect(inv.flags.model).toBe("gpt-4o")
+  expect(inv.flags.positionals).toEqual(["hi"])
+})
+
+test("flags without a command are tui", () => {
+  const inv = resolveCliInvocation(["-m", "gpt-4o", "--resume", "abc"])
+  expect(inv.kind).toBe("tui")
+  if (inv.kind !== "tui") return
+  expect(inv.flags.model).toBe("gpt-4o")
+  expect(inv.flags.resume).toBe("abc")
+  expect(inv.flags.positionals).toEqual([])
+})
+
+test("flag then prompt is tui", () => {
+  const inv = resolveCliInvocation(["-i", "a.png", "look"])
+  expect(inv.kind).toBe("tui")
+  if (inv.kind !== "tui") return
+  expect(inv.flags.images).toEqual(["a.png"])
+  expect(inv.flags.positionals).toEqual(["look"])
+})
+
+test("typo of a subcommand is treated as a prompt", () => {
+  const inv = resolveCliInvocation(["setpu"])
+  expect(inv.kind).toBe("tui")
+  if (inv.kind !== "tui") return
+  expect(inv.flags.positionals).toEqual(["setpu"])
+})
+
+test("resolveExecPrompt uses joined positionals on a tty", () => {
+  expect(resolveExecPrompt(["hello", "world"], "", true)).toEqual({ ok: true, prompt: "hello world" })
+})
+
+test("resolveExecPrompt reads stdin when prompt is dash", () => {
+  expect(resolveExecPrompt(["-"], "from stdin", false)).toEqual({ ok: true, prompt: "from stdin" })
+})
+
+test("resolveExecPrompt reads stdin when no args and not a tty", () => {
+  expect(resolveExecPrompt([], "piped", false)).toEqual({ ok: true, prompt: "piped" })
+})
+
+test("resolveExecPrompt errors when no args on a tty", () => {
+  expect(resolveExecPrompt([], "", true).ok).toBe(false)
+})
+
+test("resolveExecPrompt appends piped stdin to a prompt", () => {
+  expect(resolveExecPrompt(["do this"], "file contents", false)).toEqual({
+    ok: true,
+    prompt: "do this\n\nfile contents",
+  })
+})
+
+test("resolveExecPrompt dash with empty stdin is an error", () => {
+  expect(resolveExecPrompt(["-"], "", true).ok).toBe(false)
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/cli-invoke.test.ts`
+Expected: FAIL（模块不存在）
+
+- [ ] **Step 3: 实现 `src/cli-invoke.ts`**
+
+把 `cli.ts` 里的 `ParsedFlags` 与 `parseFlags` **原样搬过来并 export**（行为必须与现在一致，含 `--yes` 调用 `setAutoApprove`）。再加：
+
+```ts
+export const RESERVED_COMMANDS = [
+  "setup", "models", "serve", "mcp", "history", "memory",
+  "skills", "update", "init", "rules", "exec", "chat", "code",
+] as const
+
+export type ReservedCommand = (typeof RESERVED_COMMANDS)[number]
+
+export type CliInvocation =
+  | { kind: "help" }
+  | { kind: "version" }
+  | { kind: "tui"; flags: ParsedFlags }
+  | { kind: "command"; command: ReservedCommand; flags: ParsedFlags }
+
+export function resolveCliInvocation(argv: string[]): CliInvocation {
+  if (argv[0] === "--help" || argv[0] === "-h") return { kind: "help" }
+  if (argv[0] === "--version" || argv[0] === "-v") return { kind: "version" }
+  const flags = parseFlags(argv)
+  const command = flags.positionals[0]
+  if (command && (RESERVED_COMMANDS as readonly string[]).includes(command)) {
+    return {
+      kind: "command",
+      command: command as ReservedCommand,
+      flags: { ...flags, positionals: flags.positionals.slice(1) },
+    }
+  }
+  return { kind: "tui", flags }
+}
+
+export function resolveExecPrompt(
+  positionals: string[],
+  stdinText: string,
+  stdinIsTty: boolean,
+): { ok: true; prompt: string } | { ok: false; error: string } {
+  const joined = positionals.join(" ")
+  const piped = stdinText.length > 0
+  if (joined === "-") {
+    const prompt = stdinText
+    if (!prompt.trim()) return { ok: false, error: "Usage: min-agent exec <message>" }
+    return { ok: true, prompt }
+  }
+  if (!joined) {
+    if (stdinIsTty || !piped) return { ok: false, error: "Usage: min-agent exec <message>" }
+    return { ok: true, prompt: stdinText }
+  }
+  if (piped && !stdinIsTty) return { ok: true, prompt: `${joined}\n\n${stdinText}` }
+  return { ok: true, prompt: joined }
+}
+```
+
+`cli.ts`：删除本地 `ParsedFlags`/`parseFlags`，改为 `import { parseFlags, type ParsedFlags } from "./cli-invoke.js"`。`main` 仍按 `args[0]` switch，行为不变。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `bun test tests/cli-invoke.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/cli-invoke.ts tests/cli-invoke.test.ts src/cli.ts
+git commit -m "feat: 抽出 CLI 分发纯函数"
+```
+
+---
+
+## Task 2: 工具集合并
+
+**Files:**
+- Modify: `src/tools/index.ts`
+- Modify: `src/tools/task.ts`
+
+- [ ] **Step 1: 无单独测试文件**（现有测试不直接 import 这两套工厂）。实现后 `npx tsc --noEmit`。
+
+- [ ] **Step 2: 实现**
+
+`src/tools/index.ts`：删除 `createChatTools`。把 `createCodeTools` 改名为 `createTools`（函数体保持原 code 工具集，含 `EXA_API_KEY` 时的 `codesearch`）。
+
+`src/tools/task.ts`：`createCodeTools` → `createTools`。
+
+`src/agent.ts` 本 task 先改 import 与 `buildTools` 里工厂调用为 `createTools()`，**暂时仍留 `mode` 参数**（下一 task 删），避免一次 diff 过大。若 typecheck 因 `createChatTools` 引用失败，本 task 就把 `buildTools` 改成只调 `createTools()`，`mode === "code"` 的 `task` 工具改为**始终**挂上 `createTaskTool`。
+
+推荐本 task 一次做完 `buildTools` 去 mode 中与工具相关的部分：
+
+- `builtinTools = createTools()`
+- 始终 `allTools["task"] = createTaskTool(...)`
+- 删掉 `if (mode === "code")` 包 task 的分支
+- `mode` 参数先留着给 `runOnceCore` 日志，下一 task 再删
+
+- [ ] **Step 3: 类型检查**
+
+Run: `npx tsc --noEmit`
+Expected: PASS
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/tools/index.ts src/tools/task.ts src/agent.ts
+git commit -m "feat: 合并 chat/code 工具集为 createTools"
+```
+
+---
+
+## Task 3: agent 去掉 mode，runOnce 走 coding prompt
+
+**Files:**
+- Modify: `src/agent.ts`
+
+- [ ] **Step 1: 改 `runOnceCore`**
+
+- 去掉参数 `mode: "chat" | "code"`
+- 日志改为 `run start messages=${...} model=${...}`
+- `buildTools` 去掉 `mode` 参数（签名同步）
+- 所有 `return` 改为 `return { hasError }`（成功路径 `hasError` 为当时的值；abort 路径按现有 `hasError`/`aborted` 逻辑，**返回值只暴露 hasError**：abort 不算 hasError，与 `onRunFinish` 一致）
+- `runOnce` / `runOnceWithSystem` 的返回类型改为 `Promise<{ hasError: boolean }>`
+
+`runOnce` 改为：
+
+```ts
+export async function runOnce(...) {
+  const { loadInstructions } = await import("./instructions.js") // 若 instructions 已传入则不必
+  const project = scanProject()
+  const systemPrompt = buildCodeSystemPrompt(project, instructions)
+  return runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options)
+}
+```
+
+`instructions` 已是参数，直接 `buildCodeSystemPrompt(scanProject(), instructions)`。顶部 import `scanProject, buildCodeSystemPrompt` from `./code-mode.js`。
+
+删除旧的 `buildSystemPrompt(instructions)` 调用路径。若 `buildSystemPrompt` 仅被 `runOnce` 使用，保留函数本身（可能仍被别处用）；grep 后无引用则删除。
+
+`runAgent`：
+
+```ts
+const { hasError } = await runOnce(messages, instructions, modelId, undefined, undefined, tracker, { providerName })
+return hasError
+```
+
+返回类型 `Promise<boolean>`（true = 失败）。不要给 `runOnce` 传 callbacks（否则会关掉 TTY 输出）。
+
+- [ ] **Step 2: 类型检查 + agent 测试**
+
+Run: `npx tsc --noEmit` 且 `bun test tests/agent-loop.test.ts`
+Expected: PASS（测试继续用 `runOnceWithSystem`）
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add src/agent.ts
+git commit -m "feat: agent 统一 coding prompt 并返回 hasError"
+```
+
+---
+
+## Task 4: TUI 去掉 mode，支持首条 prompt
+
+**Files:**
+- Modify: `src/tui-chat.ts`
+- Modify: `src/tui/agent-runner.ts`
+- Modify: `src/tui/slash-handler.ts`
+- Modify: `src/cli.ts`（仅让现有 `chat`/`code` 分支能编译：暂时仍传 `mode` 的话本 task 必须改掉调用处）
+
+- [ ] **Step 1: `AgentRunnerDeps`**
+
+删除 `mode`。`codeSystemPrompt` 改为必填 `string`。`run()` 只调用 `runOnceWithSystem`。
+
+- [ ] **Step 2: `TuiOptions`**
+
+```ts
+export interface TuiOptions {
+  modelId?: string
+  providerName?: string
+  resumeSessionId?: string
+  images?: string[]
+  initialPrompt?: string
+}
+```
+
+`runTui`：始终 `scanProject()` + `buildCodeSystemPrompt`。`createAgentRunner({ ..., codeSystemPrompt })` 不再传 `mode`。
+
+启动后、`tui.start()` 之后、现有 images 注入处，合并为首条 user 消息：
+
+```ts
+const prompt = opts.initialPrompt?.trim() ?? ""
+const notify = ... // 保持现有三种提示
+if (images?.length) {
+  const parts = [{ type: "text", text: prompt }, ...loadImageParts(images, notify)]
+  if (parts.length > 1 || prompt) {
+    messages.push({ role: "user", content: prompt ? parts : parts })
+    tui.addMessage({ id: `user-${Date.now()}`, role: "user", content: prompt ? prompt : `[📎 图片] ${images.join(", ")}`, timestamp: Date.now() })
+    await runner.run()
+  }
+} else if (prompt) {
+  tui.addMessage({ id: `user-${Date.now()}`, role: "user", content: prompt, timestamp: Date.now() })
+  messages.push({ role: "user", content: prompt })
+  await runner.run()
+}
+```
+
+细节（必须遵守 spec）：
+
+- **仅 prompt**：文本 user 消息 + `run()`
+- **仅图片**：现有逻辑（空文本 + 图片 parts，length>1 才 run）
+- **prompt + 图片**：同一条 user，`text` 为 prompt，加上图片 parts
+- **resume + prompt**：在已 load 的 messages 后追加，再 run
+- 皆无：不 run
+
+TUI 展示：有 prompt 时 user 气泡用 prompt 文本；仅图片时保持 `[📎 图片] ...`。两者都有时气泡用 prompt（图片仍在消息 content 里）。
+
+- [ ] **Step 3: slash-handler**
+
+`/sessions` 里 `min-agent chat --resume <id>` 改为 `min-agent --resume <id>`。
+
+- [ ] **Step 4: cli.ts 过渡**
+
+`chat`：无 message 时 `runTui({ ..., initialPrompt: undefined })`；**有 message 时暂时仍 `runAgent`**（下一 task 改为 TUI）。`code`：`runTui({ ... })` 去掉 `mode: "code"`。此步只要 typecheck 过。
+
+- [ ] **Step 5: 类型检查**
+
+Run: `npx tsc --noEmit`
+Expected: PASS
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/tui-chat.ts src/tui/agent-runner.ts src/tui/slash-handler.ts src/cli.ts
+git commit -m "feat: TUI 统一 coding 会话并支持首条 prompt"
+```
+
+---
+
+## Task 5: CLI 默认 TUI + exec
+
+**Files:**
+- Modify: `src/cli.ts`
+
+- [ ] **Step 1: 改 `main` 入口**
+
+删除「`args.length === 0` 打印 Usage」。保留第一个 token 为 `-h`/`--help`、`-v`/`--version` 的分支，**或**直接：
+
+```ts
+const invocation = resolveCliInvocation(args)
+switch (invocation.kind) {
+  case "help":
+    printUsage()
+    process.exit(0)
+  case "version":
+    // 现有读 package.json 逻辑
+    process.exit(0)
+  case "tui":
+    await startTuiSession(invocation.flags)
+    break
+  case "command":
+    // 原 switch，但 command 来自 invocation.command
+    // flags 用 invocation.flags，不要再 parseFlags(args.slice(1))
+}
+```
+
+抽出 `startTuiSession(flags: ParsedFlags)`：
+
+```ts
+async function startTuiSession(flags: ParsedFlags) {
+  if (!isConfigured()) {
+    console.error("Not configured. Run: min-agent setup")
+    process.exit(1)
+  }
+  const { runTui } = await import("./tui-chat.js")
+  const prompt = flags.positionals.join(" ").trim()
+  await runTui({
+    modelId: flags.model,
+    providerName: flags.provider,
+    resumeSessionId: flags.resume,
+    images: flags.images,
+    initialPrompt: prompt || undefined,
+  })
+}
+```
+
+`chat` / `code` 两个 case 都只调用 `startTuiSession(invocation.flags)`（有无位置参数都进 TUI，**不再** `runAgent`）。
+
+`exec` case：
+
+```ts
+case "exec": {
+  if (!isConfigured()) {
+    console.error("Not configured. Run: min-agent setup")
+    process.exit(1)
+  }
+  const flags = invocation.flags
+  const stdinIsTty = Boolean(process.stdin.isTTY)
+  let stdinText = ""
+  const joined = flags.positionals.join(" ")
+  const shouldReadStdin = joined === "-" || !stdinIsTty
+  if (shouldReadStdin) {
+    try {
+      stdinText = await Bun.readableStreamToText(Bun.stdin.stream())
+    } catch {
+      console.error("Failed to read stdin")
+      process.exit(1)
+    }
+  }
+  const resolved = resolveExecPrompt(flags.positionals, stdinText, stdinIsTty)
+  if (!resolved.ok) {
+    console.error(resolved.error)
+    process.exit(1)
+  }
+  const failed = await runAgent(
+    resolved.prompt,
+    flags.model,
+    flags.images.length > 0 ? flags.images : undefined,
+    flags.provider,
+  )
+  if (failed) process.exit(1)
+  break
+}
+```
+
+注意：无位置参数且是 TTY 时 **不要**读 stdin（会挂起等 EOF）。`shouldReadStdin = joined === "-" || !stdinIsTty` 已覆盖：TTY 且无参数 → 不读，`resolveExecPrompt` 报 Usage。
+
+原 `default: Unknown command` 删除（非保留词已在 `kind: "tui"`）。
+
+各子命令里原来的 `parseFlags(args.slice(1))` 改为使用 `invocation.flags`（positionals 已去掉命令名）。`mcp`/`history` 等仍看 `args[1]` 也可以，但 flag 覆盖必须来自 `invocation.flags`。为减少行为漂移：子命令内部若仍用 `args.slice(1)` 的局部 parse，**允许保留**（与现在一致），只要 `chat`/`code`/`exec`/根 TUI 走 `invocation`。`models`/`serve` 继续 `parseFlags(args.slice(1))` 即可。
+
+- [ ] **Step 2: 改 `printUsage`**
+
+Usage 开头改为（风格与现有英文 Usage 一致，不出现 chat/code 两种模式）：
+
+```
+Usage:
+  min-agent                         Start interactive session
+  min-agent <message>               Start interactive session and send message
+  min-agent exec <message>          Run one message non-interactively
+  min-agent --resume <id>           Resume a previous session
+  min-agent chat | code             Same as interactive session (compat)
+  ...其余子命令保持...
+Examples:
+  min-agent setup
+  min-agent
+  min-agent "hello"
+  min-agent exec "hello"
+  min-agent --resume <id>
+```
+
+- [ ] **Step 3: 类型检查**
+
+Run: `npx tsc --noEmit`
+Expected: PASS
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/cli.ts
+git commit -m "feat: 默认进入交互会话并新增 exec"
+```
+
+---
+
+## Task 6: HTTP API 统一
+
+**Files:**
+- Modify: `src/serve.ts`
+- Modify: `tests/serve.test.ts`
+- Modify: `docs/API.md`
+
+- [ ] **Step 1: 改测试**
+
+`F7: POST /v1/paste 支持 code 模式` 改为例如「paste 响应带 project、不带 mode」：
+
+```ts
+test("F7: POST /v1/paste 带 project 且无 mode", async () => {
+  const { status, text } = await postJson("/v1/paste", {
+    image_base64: PNG_B64,
+    message: "分析",
+    stream: false,
+  })
+  expect(status).toBe(200)
+  const body = JSON.parse(text)
+  expect(body.mode).toBeUndefined()
+  expect(body.project).toBeTruthy()
+}, 90000)
+```
+
+再加（或改现有 chat 用例）断言 `POST /v1/chat` 非流式带 `project`、无 `mode`；`POST /v1/code` 与 chat 结构一致。
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/serve.test.ts`
+Expected: 新断言 FAIL（chat 无 project / paste 仍可能因 `code: true` 才有 project）
+
+- [ ] **Step 3: 改 `serve.ts`**
+
+- `handleChatRequest` 去掉 `codeMode` 参数。始终 `project = scanProject()`，`runOnceWithSystem(messages, buildCodeSystemPrompt(project, instructions), ...)`
+- SSE/JSON 响应：去掉 `mode: "code"`，始终带 `project`
+- `createSseCallbacks` 去掉 `codeMode`，始终附 `project`
+- 路由：`handleChatRequest(req, res)`，`/v1/chat` 与 `/v1/code` 同一调用
+- paste：去掉 `body.code` 分支，始终扫描项目 + `runOnceWithSystem`；响应带 `project`、不带 `mode`；忽略多余字段 `code`
+
+- [ ] **Step 4: 改 `docs/API.md`**
+
+- 端点表：`/v1/code` 写成「与 `/v1/chat` 相同（兼容路径）」
+- `POST /v1/chat` 非流式示例加上 `"project": { ... }`
+- `done` 事件说明加上 `project`
+- 删除「Code 模式对话」独立语义；`/v1/code` 一节改为别名
+- paste：删除 `code` 字段；写明始终返回 `project`；多传 `code` 忽略
+- 示例里 `# Code 模式` 改为 `# 兼容路径 /v1/code`
+
+顶部并发说明仍可提 `/v1/chat`、`/v1/code`、`/v1/paste`。
+
+- [ ] **Step 5: 测试通过**
+
+Run: `bun test tests/serve.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/serve.ts tests/serve.test.ts docs/API.md
+git commit -m "feat: HTTP 对话接口统一为项目感知"
+```
+
+---
+
+## Task 7: README 与残留文案
+
+**Files:**
+- Modify: `README.md`
+- 全文搜 `packages/min-agent` 里用户可见的「chat 模式 / code 模式 / coding mode」（不含历史 spec/plan）
+
+- [ ] **Step 1: README Quick Start / Commands**
+
+```bash
+min-agent setup              # Configure provider
+min-agent                    # Interactive session
+min-agent "hello"            # Interactive session, send immediately
+min-agent exec "hello"       # One-shot, then exit
+```
+
+Commands 列表把 `chat`/`code` 收成兼容一行，补上 `exec`、根命令 `--resume` / `-m` / `-i` / `--provider`。
+
+- [ ] **Step 2: grep 残留**
+
+`rg -n "mode: \"chat\"|createChatTools|createCodeTools|codeMode|coding mode|Code 模式" packages/min-agent/src packages/min-agent/README.md packages/min-agent/docs/API.md`
+
+只允许旧 spec/plan 文档里出现。源码与用户文档必须清掉。
+
+- [ ] **Step 3: 全量验证**
+
+Run: `npx tsc --noEmit` 且 `bun test`（在 `packages/min-agent`）且仓库根 `bun run typecheck`
+Expected: PASS
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add README.md
+git commit -m "docs: 默认交互会话与 exec 的使用说明"
+```
+
+---
+
+## 实现注意事项
+
+- **不要** import `cli.ts` 做测试（模块加载会执行 `main`）。
+- `exec` 在 TTY 且无参数时不得读 stdin，否则会卡住。
+- `runAgent` 不能靠传入 `callbacks` 来取 `hasError`，那会关掉终端打印。
+- `/plan` 与双模式无关，不要动其语义。
+- 用户可见文案不要写「原 code 模式」「TUI」等内部叫法；Usage/README 用 interactive session / 交互会话。