min-agent 0.2.0 → 0.3.0

package/docs/superpowers/specs/2026-08-16-batch1-tui-improvements-design.md

@@ -0,0 +1,183 @@
+# 第一批：Bug 修复 + TUI 交互体验 — 设计文档
+
+**日期:** 2026-08-16
+**状态:** 已批准
+**范围:** 30 项改进清单中的第一批（8 项）：TUI 交互体验与缺陷修复
+
+---
+
+## 背景
+
+min-agent 功能审查发现 30 项缺失/欠缺，按"价值/风险"划分为三批实施。本 spec 覆盖第一批：最高价值、低风险的 TUI 交互体验项目。
+
+## 目标与非目标
+
+**目标:**
+- 修复 `chat -i` 图片静默丢弃缺陷
+- 补齐 TUI 缺失的核心交互：输入历史、undo、redo、diff、会话管理
+- 增加成本估算显示
+- README 与 `/help` 同步
+
+**非目标:**
+- 多 provider、采样参数、预算上限、日志、CI、/plan（第二、三批）
+- 输入历史持久化（会话内内存即可）
+- 成本预算执行（第三批）
+
+## 设计决策（已与用户确认）
+
+| 决策 | 结论 |
+|------|------|
+| 范围 | 全部 30 项，分三批推进，本批为第一批 |
+| 成本数据源 | models.dev 自动拉取 + config 手动覆盖 |
+| 计划模式 | 内置 /plan（第三批） |
+
+## 模块设计
+
+### 1. 图片附加修复 + `/attach`
+
+**现状缺陷:** `cli.ts:225-227` — `min-agent chat -i img.png`（无消息）时 images 被静默丢弃，`TuiOptions` 无 images 字段。
+
+**修改:**
+
+- `src/tui-chat.ts` `TuiOptions` 增加 `images?: string[]`
+- `src/cli.ts` chat 分支：`runTui({ modelId, resumeSessionId, mode, images })`
+- `runTui` 启动时：若 `images` 非空且 resume 会话无未处理图片，用 `buildUserContent()` 构建首条用户消息注入，TUI 显示 `[📎 图片]` 占位（对齐 `/paste` 交互）
+- 新斜杠命令 `/attach <path>`（alias: `/image`）：读取本地图片（复用 5MB 上限逻辑），push 到 messages 并触发 agent 运行；读取失败警告并跳过，不崩溃
+- 图片注入逻辑提取为可复用函数（`src/tui-chat.ts` 内部），`/paste` 与 `/attach` 共用
+
+### 2. README 与 `/help` 同步
+
+- `README.md` 交互命令表补充 `/models`、`/mcp`、`/skills`
+- 本批新增命令（`/undo`、`/redo`、`/diff`、`/sessions`、`/rename`、`/attach`）同步进 README 表与 `/help` 输出及 `slash-commands.ts` 菜单
+
+### 3. 输入历史（新模块 `src/tui/input-history.ts`）
+
+纯函数，无 React/Ink 依赖：
+
+```ts
+interface HistoryState {
+  entries: string[]      // 已提交输入，最新在后
+  index: number          // 当前浏览位置，-1 表示草稿态
+  draft: string          // 进入历史模式前的草稿
+}
+createHistory(): HistoryState
+pushInput(state, text): HistoryState          // 提交输入
+browseHistory(state, direction): { text, state }  // direction: 1 更早 | -1 更新
+exitHistory(state): { text, state }           // 恢复草稿
+hasHistory(state): boolean
+```
+
+**行为:**
+- ↑（upArrow）进入历史模式：草稿暂存，从最近输入开始；再次 ↑ 更早，↓ 回退
+- 浏览历史期间用户编辑文本 → 退出历史模式（回到草稿）
+- Esc → 退出历史模式恢复草稿
+- 空历史时 ↑ 无效果（保持现有行为）
+- 重复输入去重（连续相同输入只记录一次）
+
+**InputBar.tsx 集成:** upArrow/downArrow 处理路径改为调用 input-history；当前编辑文本替换为历史条目
+
+### 4. `/undo`（新模块 `src/tui/undo-stack.ts`）
+
+纯函数：
+
+```ts
+interface TurnRecord { start: number; end: number }
+createUndoStack(): TurnRecord[]
+pushTurn(stack, start, end): TurnRecord[]
+popTurn(stack): TurnRecord | undefined
+```
+
+**tui-chat.ts 集成:**
+- `executeAgent` 前记录 `turnStart = messages.length`；结束后 `pushTurn(stack, turnStart, messages.length)`（try/finally 中完成，失败回合也入栈以便撤销）
+- `/undo`：pop 栈顶，`messages.splice(start, end - start)`，TUI 消息列表同步截断（`tui.update` 重新渲染剩余消息），系统提示 "✓ 已撤销 1 轮"
+- 栈空 → "没有可撤销的内容"
+- `/clear` 清空 undo 栈；`/redo` 的回合正常入栈（可撤销 redo）
+
+### 5. 成本估算（新模块 `src/pricing.ts`）
+
+对齐 `context-window.ts` 模式（内存缓存 + 磁盘缓存 + in-flight 共享 + 7 天 TTL）：
+
+```ts
+estimateCost(usage: { inputTokens: number; outputTokens: number }, modelId: string): Promise<number | null>
+getModelPrice(modelId: string): Promise<{ inputPerMillion: number; outputPerMillion: number } | null>
+```
+
+**数据源:** models.dev `api.json`（`context-window.ts` 已在用），读取 `model.pricing.input` / `model.pricing.output`（USD / 1M tokens）
+
+**覆盖配置:** `config.json` 新增：
+
+```json
+"pricing": {
+  "gpt-4o": { "inputPerMillion": 2.5, "outputPerMillion": 10 }
+}
+```
+
+**集成点:**
+- `src/tui-chat.ts` `/tokens` 输出追加 `| 约 $0.012`
+- `onRunFinish` 完成消息追加成本（`Done in N step(s) | Tokens: ... | ~$0.012`）
+- 无价格数据 → 显示 `--`，不阻塞
+- 缓存文件 `~/.min-agent/pricing-cache.json`
+
+### 6. `/diff`（新模块 `src/tui/diff-view.ts`）
+
+```ts
+getWorkingTreeDiff(): Promise<{ ok: true; diff: string } | { ok: false; reason: "not_git" | "no_changes" | "error"; message: string }>
+```
+
+- 执行 `git diff --stat` + `git diff`（cwd 为 git 仓库时），输出合并展示
+- 非 git 仓库 → `{ ok: false, reason: "not_git" }`，TUI 提示 "非 git 仓库，无法显示 diff"
+- 无未提交变更 → `"no_changes"`，提示 "工作区无未提交变更"
+- 输出超长截断（复用 `truncateToolOutput` 思路，限制 8000 字符）
+- TUI `/diff` 命令将 diff 作为系统消息展示
+
+### 7. `/redo`（中断重试）
+
+- `lastUserMessage: string | null` 变量，每次用户文本消息提交时更新（`/paste`、`/attach` 不更新）
+- `/redo`：`lastUserMessage` 存在 → push 相同消息到 messages + TUI + `executeAgent()`；不存在 → "没有可重发的消息"
+- Esc 取消后的重试流程：用户输入 `/redo`
+
+### 8. `/sessions` + `/rename <title>`
+
+- `src/sessions.ts` 新增：
+
+```ts
+renameSession(id: string, title: string): boolean
+```
+
+- `/sessions`：`listSessions()` 输出（id、标题、消息数、日期），当前会话标 `←`；当前会话 id 未知（未保存过）时用 `(未保存)`
+- `/rename <title>`：若 `sessionId` 为空（会话未保存过），先 `sessionId = saveSession(messages)` 落盘；再调用 `renameSession(sessionId, title)`，失败提示"会话不存在"
+- 退出时 `saveSession(messages, sessionId)` 沿用已改标题（内部读取现有 meta.created）
+
+## 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| 图片文件不存在/超 5MB | 警告并跳过该图片，继续运行 |
+| 价格拉取失败 | 缓存空结果，成本显示 `--` |
+| undo 栈空 | "没有可撤销的内容" |
+| redo 无消息 | "没有可重发的消息" |
+| diff 非 git / 无变更 | 明确提示 |
+| rename 不存在的会话 | 返回 false，TUI 提示 |
+
+## 测试
+
+新增测试文件：
+
+| 文件 | 覆盖 |
+|------|------|
+| `tests/input-history.test.ts` | 入栈/导航/去重/草稿恢复/边界 |
+| `tests/undo-stack.test.ts` | 入栈/出栈/空栈/顺序 |
+| `tests/pricing.test.ts` | 价格解析、缓存命中、覆盖配置优先、失败回退（mock fetch） |
+| `tests/diff-view.test.ts` | git diff 提取（mock execSync）、非 git、无变更 |
+
+验证命令（`packages/min-agent` 下）：
+- `npx tsc --noEmit`
+- `bun test`
+- `bun run src/cli.ts` 手动冒烟
+
+## 文档同步（AGENTS.md 强制）
+
+- `README.md`：交互命令表补 `/models` `/mcp` `/skills` `/undo` `/redo` `/diff` `/sessions` `/rename` `/attach`
+- TUI `/help` 输出同步
+- `src/tui/slash-commands.ts` 菜单同步
+- `docs/API.md`：本批无 API 变更（会话重命名 API 属第二批，届时同步）

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

@@ -0,0 +1,220 @@
+# 第二批：CLI + 工具 + HTTP API — 设计文档
+
+**日期:** 2026-08-16
+**状态:** 已批准
+**范围:** 30 项改进清单中的第二批（17 项）：CLI 增强、工具增强、HTTP API 补齐
+
+---
+
+## 背景
+
+min-agent 功能审查发现的 30 项缺失按"价值/风险"分三批实施。本 spec 覆盖第二批：CLI 命令补全、工具能力增强、HTTP API 完整性。第一批（TUI 交互）已完成并合并到 master。
+
+## 设计决策（已与用户确认）
+
+| 决策 | 结论 |
+|------|------|
+| update 命令 | 检查 npm registry 版本后自动执行 `npm install -g min-agent@latest` |
+| apply_patch | 完整 unified diff（解析 + 应用 + 冲突报告） |
+| 会话导出格式 | 完整 session JSON（meta + messages，与 sessions/ 目录同格式） |
+
+## 模块设计
+
+### 1. CLI 增强
+
+#### 1.1 `min-agent history delete <id>` / `rename <id> <title>`
+
+- `src/cli.ts` history 分支扩展：
+  - `history delete <id>` → `deleteSession(id)`，成功提示 ✓，失败报"会话不存在"（exit 1）
+  - `history rename <id> <title>` → `renameSession(id, title)`，同样处理
+- 复用第一批已实现的 `src/sessions.ts` 函数，无新模块
+
+#### 1.2 `min-agent mcp add --env KEY=VALUE`
+
+- `parseMcpAddArgs` 增加 `--env` 解析（可重复，`KEY=VALUE` 格式，非法格式报错）
+- 构建 `entry.environment = { KEY: "VALUE", ... }`（仅当有 env 时设置）
+- `mcp info` 已支持显示 environment 键列表，无需改
+
+#### 1.3 `min-agent update` 自动升级
+
+- 新逻辑（放 `src/cli.ts` 或独立 `src/updater.ts`；因含 fetch + execSync 逻辑，独立模块 `src/updater.ts` 更清晰）：
+
+```ts
+export async function runUpdate(): Promise<void>
+```
+
+- 流程：
+  1. 读取本地版本（现有 `--version` 的读 package.json 逻辑）
+  2. fetch `https://registry.npmjs.org/min-agent/latest`（10s 超时），取 `version`
+  3. 本地已最新 → 提示并返回
+  4. 有新版 → 打印版本信息，执行 `npm install -g min-agent@latest`（`execSync(..., { stdio: "inherit" })`），成功提示重启
+  5. 网络失败 → 提示无法检查
+- 注意事项：npm 不可用时报错提示改用 `npm install -g min-agent@latest` 手动执行
+
+#### 1.4 `min-agent history export <id> [-o file]`
+
+- `history export <id>`：`loadSession(id)`，无会话报错 exit 1
+- 输出完整 SessionData JSON（`JSON.stringify(data, null, 2)`）；`-o <file>` 写文件并提示路径，否则 stdout
+- 复用 `loadSession`，无新模块
+
+### 2. 工具增强
+
+#### 2.1 bash 支持 `cwd` 参数
+
+- `src/tools/bash.ts`：
+  - `BashInput` 加可选 `cwd?: string`
+  - `executeBash(command, timeout, cwd?)` 签名扩展，spawn 用 `cwd: cwd ? path.resolve(process.cwd(), cwd) : process.cwd()`
+  - 工具描述补充"cwd：在指定目录执行（相对当前目录或绝对路径）"
+- `src/tools/explore.ts` 的 `readOnlyBashTool` 同步支持（executeBash 已扩展，只需 schema 加 cwd）
+- 不引入确认流程变化（cwd 本身无危险）
+
+#### 2.2 `apply_patch` 工具（新模块 `src/tools/apply_patch.ts`）
+
+Unified diff 解析与应用：
+
+```ts
+interface ApplyPatchInput {
+  diff: string
+}
+```
+
+**解析器**（纯函数，可测试）：
+- 扫描 `--- <path>` / `+++ <path>` 文件头（忽略 `a/`、`b/` 前缀；`/dev/null` 表示创建新文件）
+- 扫描 `@@ -start,count +start,count @@` hunks（行号可省略 count）
+- hunk 内行：`' '` 上下文、`-` 删除、`+` 新增、`\` 续行标记（No newline at end of file 忽略处理）
+- 多文件、多 hunk 支持
+
+**应用器**：
+- 目标文件不存在且 diff 标记为新增（`/dev/null` 或 b/ 文件无 a/）→ 创建
+- 目标文件不存在且无新增标记 → 报错"文件不存在"
+- 逐 hunk 应用：按上下文匹配定位（允许行偏移——匹配时计算目标位置；简化策略：从 hunk 期望位置附近 ±3 行内查找匹配起点，找不到则冲突）
+- 冲突 → 返回错误信息（哪个文件、哪个 hunk 行号范围），不部分写入
+- 应用顺序：每个文件独立应用，全部成功才写（原子性：先全量解析验证，再写文件）
+- 写文件前 confirm（危险操作，遵循项目规则）
+- 输出：每个文件的变更统计（`-N/+M` 行数）
+
+#### 2.3 write 支持 `append`
+
+- `src/tools/write.ts`：`WriteInput` 加可选 `append?: boolean`
+- `append: true` 时：`writeFile(resolved, content, { flag: "a" })`，跳过"覆盖现有文件"确认（追加不需要）
+- 描述更新：追加模式说明
+
+#### 2.4 web_search 参数扩展
+
+- `src/tools/web_search.ts`：`WebSearchInput` 加 `language?: string`、`time_range?: string`
+- 透传 SearXNG：`language`（ISO 639-1，如 `zh`、`en`）、`time_range`（`day`/`week`/`month`/`year`，校验白名单）
+- language 白名单校验（简化：非空字符串直接透传，SearXNG 自己处理无效值）；time_range 白名单校验
+
+#### 2.5 chat 模式工具扩展
+
+- `src/tools/index.ts` `createChatTools()`：加 `todo: todoTool`
+- `src/agent.ts` `buildTools()`：explore 工厂改为两种模式都加：
+
+```ts
+  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)
+  }
+```
+
+改为：
+
+```ts
+  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)
+  }
+```
+
+- task 保留 code 模式；explore 两种模式都有；todo 两种模式都有
+
+### 3. HTTP API 补齐
+
+#### 3.1 `GET /v1/sessions/:id`
+
+- `loadSession(id)` → 404（不存在）/ 200（`{ session: { meta, messages } }`）
+
+#### 3.2 `POST /v1/sessions/:id/rename`
+
+- body `{ title: string }`（必填非空，否则 400）
+- `renameSession(id, title)` → false 时 404
+- 成功 200 `{ ok: true, session_id, title }`
+
+#### 3.3 `POST /v1/skills/:name/enable|disable`
+
+- enable：从 `config.disabledSkills` 移除 name
+- disable：加入（去重）
+- 保存 config，200 `{ ok: true, name, enabled: bool }`
+
+#### 3.4 `POST /v1/mcp/:name/enable|disable`
+
+- 更新 `config.mcpServers[name].enabled`（不存在 404）
+- 200 `{ ok: true, name, enabled: bool }`
+
+#### 3.5 `/v1/paste` 支持 code 模式
+
+- body 加 `code?: boolean`
+- code 时：`scanProject()` + `buildCodeSystemPrompt()`，用 `runOnceWithSystem`，响应带 `mode: "code"` 与 `project` 字段（与 /v1/code 一致）
+- stream 与 JSON 两种模式都支持
+
+#### 3.6 `GET /v1/cost`
+
+- 参数：`model`（可选，默认配置默认模型）、`input`、`output`（token 数，可选）
+- 响应：`{ model, price: ModelPrice | null, cost_usd: number | null }`
+- `getModelPrice(model)` + `estimateCost`
+- 复用第一批的 pricing.ts
+
+#### 3.7 `POST /v1/chat/undo`
+
+- body `{ session_id }`（必填，404 检查）
+- 语义：截断 messages 到最后一条 user 消息之后（保留该 user 消息，删除其后所有 assistant/tool 消息）——与 TUI /undo 的"保留 user 消息"语义一致
+- 实现：从后往前找 `role === "user"` 的索引 `i`，`messages = messages.slice(0, i + 1)`；无 user 消息 → 400
+- 保存并返回 `{ ok: true, message_count, messages }`
+
+#### 3.8 采样参数透传
+
+- `ChatBody` 加 `temperature?: number`、`maxTokens?: number`、`topP?: number`
+- `src/agent.ts` `runOnce`/`runOnceWithSystem`/`runOnceCore` 加可选 `options?: { temperature?: number; maxTokens?: number; topP?: number }`
+- `streamText({ ..., temperature, maxTokens, topP })` 条件展开（undefined 不传，保持默认）
+- serve.ts 两个聊天 handler（/v1/chat、/v1/code、/v1/paste）透传
+- 注意：AI SDK 的 streamText 参数是 `temperature?: number`、`maxTokens?: number`（Vercel AI SDK v6 是 `maxTokens`）、`topP?: number`
+
+### 4. 文档同步
+
+- `docs/API.md`：新端点表格 + 各端点说明、采样参数字段、cost 端点
+- `README.md`：Commands 区补 `history delete/rename/export`、`mcp add --env`、`update`
+- `src/cli.ts` printUsage 同步
+
+## 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| update 网络失败 | 提示无法检查新版本，不崩溃 |
+| update npm 失败 | 报错并提示手动 `npm install -g min-agent@latest` |
+| apply_patch 冲突 | 明确报告文件与 hunk 位置，拒绝写入 |
+| apply_patch 目标文件不存在 | 报错（除非 diff 标记新增） |
+| history delete/rename/export 目标不存在 | 报错 exit 1 |
+| mcp add --env 非法格式 | 报错并提示 `--env KEY=VALUE` |
+| 采样参数非法值 | 透传给模型 API（不校验），由 provider 拒绝 |
+
+## 测试
+
+| 文件 | 覆盖 |
+|------|------|
+| `tests/apply-patch.test.ts`(新) | 解析（文件头/hunk/行）、应用（修改/新增/删除）、新文件创建、上下文偏移匹配、冲突报告、原子性（冲突不部分写入） |
+| `tests/web-search.test.ts`(改) | language/time_range 参数透传（mock fetch） |
+| `tests/serve.test.ts`(改) | 新端点：sessions/:id、rename、skills enable/disable、mcp enable/disable、cost、chat/undo、paste code、采样参数透传 |
+| bash cwd | 直接执行验证（`executeBash("pwd", undefined, tmpdir)` 输出为 tmpdir） |
+| CLI 新命令 | 冒烟验证 |
+
+验证命令（`packages/min-agent` 下）：`bun test`、`bun run typecheck`（仓库根）、手动冒烟。
+
+## 文档同步清单
+
+- `docs/API.md`：新端点 + 采样参数 + cost
+- `README.md`：history 子命令、mcp --env、update、export
+- `src/cli.ts` printUsage

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

@@ -0,0 +1,196 @@
+# 第三批：配置 + 工程 — 设计文档
+
+**日期:** 2026-08-16
+**状态:** 已批准
+**范围:** 30 项改进清单中的第三批（7 项）：多 provider、采样参数、预算上限、日志系统、CI、/plan 计划模式、文档完善
+
+---
+
+## 背景
+
+min-agent 功能审查发现的 30 项缺失按三批实施。前两批（TUI 交互、CLI/工具/API）已完成并合并到 master。本批为配置体系与工程基础设施。
+
+## 设计决策（已与用户确认）
+
+| 决策 | 结论 |
+|------|------|
+| 多 provider 切换 | 破坏式改造：`providers[]` + `activeProvider`，自动迁移旧配置；CLI `--provider <name>` + TUI `/provider <name>` |
+| 预算超限行为 | 回合结束检查 + 提示（不硬中断流式输出） |
+| 日志粒度 | 运行日志 + 日期滚动（保留 7 天） |
+
+## 模块设计
+
+### 1. 多 Provider（破坏式改造 + 自动迁移）
+
+#### 1.1 配置结构（src/config.ts）
+
+```ts
+export interface ProviderConfig {
+  name?: string
+  type?: "openai-compatible" | "openai" | "ollama"
+  baseURL: string
+  apiKey: string
+  defaultModel?: string
+  contextWindow?: number
+}
+
+export interface AppConfig {
+  providers?: ProviderConfig[]
+  activeProvider?: string
+  instructions?: string[]
+  disabledSkills?: string[]
+  permission?: "allow-all" | "ask"
+  compaction?: { model?: string; autoContinue?: boolean }
+  webSearchURL?: string
+  webFetchURL?: string
+  sampling?: { temperature?: number; maxTokens?: number; topP?: number }
+  budget?: { maxCostUSD?: number }
+  pricing?: Record<string, { inputPerMillion: number; outputPerMillion: number }>
+}
+```
+
+**移除** `provider?: ProviderConfig`（旧字段）。
+
+#### 1.2 自动迁移
+
+- `migrateLegacyConfig(config: AppConfig): { config: AppConfig; migrated: boolean }`
+  - 检测 `config.provider`（旧单对象）存在 → 转为 `providers: [{ name: "default", ...旧字段 }]` + `activeProvider: "default"`，删除 `provider` 字段，`migrated = true`
+- `loadConfig()` 调用迁移并在 migrated 时 `saveConfig` 写回磁盘（一次性迁移；cachedConfig 缓存迁移后对象）
+- 导出 `getActiveProvider(config?: AppConfig): ProviderConfig | undefined`（activeProvider 名称匹配；未设 activeProvider 且 providers 长度 1 → 返回该 provider；无匹配 → undefined）
+
+#### 1.3 provider 解析（src/provider.ts）
+
+- `resolveModelForProvider(provider: ProviderConfig, modelId?)` 签名不变（参数类型改为新接口）
+- `resolveModel(modelId?, providerName?)`：取 `getActiveProvider`，providerName 覆盖时按名字查找（找不到报错 `Provider "x" not found`）
+- `getProviderNames(config): string[]`（供 CLI/TUI 展示）
+
+#### 1.4 CLI（src/cli.ts）
+
+- `parseFlags` 加 `--provider <name>`（`-p`？不，`-p` 已是 port。用 `--provider` 长参数）
+- `chat`/`code` 分支：`resolveModel(modelId, providerOverride)` 生效——通过 runTui/runAgent 传 providerName，最终进 resolveModel
+  - runTui TuiOptions 加 `providerName?: string`；runAgent 加参数
+- `models` 命令：显示 activeProvider（或 --provider 指定）的模型列表
+- `setup` 重构：列出现有 providers（名称 + URL + 默认模型 + 当前标记），选项：切换默认 / 添加新 provider / 修改当前；新 provider 信息收集复用现有流程（type/URL/key/model）
+- `mcp`/`skills`/`history` 等不涉及 provider，不变
+
+#### 1.5 TUI（src/tui-chat.ts）
+
+- `/provider`：无参列出 providers（当前标记 ←），有参切换 activeProvider（saveConfig + sysMsg）
+- `/model`：显示当前 provider 的模型列表（fetchModels 用 activeProvider 的 baseURL/apiKey）
+- 状态栏/启动信息展示当前 provider 名（可选，保持精简）
+
+#### 1.6 serve（src/serve.ts）
+
+- 所有 `config.provider?.xxx` 引用改为 `getActiveProvider(config)?.xxx`
+- `/v1/models`、`/v1/context` 等同理
+- `body.provider` 可选：指定 provider 名（覆盖 activeProvider）
+
+### 2. 采样参数 config（src/config.ts + src/agent.ts）
+
+- `AppConfig.sampling?: { temperature?: number; maxTokens?: number; topP?: number }`
+- `runOnceCore`：options 为空（或字段 undefined）时回退 `loadConfig().sampling` 对应字段
+- 优先级：API 请求显式 options > config.sampling > 模型默认
+- 实现：在 runOnceCore 开头合并 `const effective = { temperature: options?.temperature ?? sampling?.temperature, ... }`（仅当字段非 undefined 时传 streamText）
+
+### 3. 预算上限（src/agent.ts + tui-chat.ts + serve.ts）
+
+- `AppConfig.budget?: { maxCostUSD?: number }`
+- 成本累计：tracker 已有 totalInputTokens/totalOutputTokens；新增 `tracker.usage` 或直接在 runOnce 结束后估算
+- `runOnceCore` 结束（onRunFinish 前）：`const maxCost = loadConfig().budget?.maxCostUSD`；若 `estimateCost({ totalInput, totalOutput }, price) > maxCost` → 置 `budgetExceeded = true`，onRunFinish 的 info 加 `budgetExceeded?: boolean` 字段
+- TUI onRunFinish：budgetExceeded 时完成消息追加"⚠ 已达到预算上限（约 $X / $Y），/budget 查看或调高"
+- `/budget` 命令：无参显示 `已用约 $X / 上限 $Y（未设置则提示）`；`/budget <n>` 设置上限
+- serve：done 事件加 `budget_exceeded` 字段
+- 注意：estimateCost 需要 getModelPrice（异步）——runOnceCore 结束时 await
+
+### 4. 日志系统（新模块 src/logger.ts）
+
+```ts
+export function initLogger(): void          // 创建 ~/.min-agent/logs/ 目录 + 清理 7 天前日志
+export function log(level: "info" | "warn" | "error", msg: string): void  // 追加到当天日志文件
+export function logToolCall(name: string, input: unknown): void
+export function logToolResult(name: string, output: unknown): void
+```
+
+- 文件：`~/.min-agent/logs/min-agent.YYYY-MM-DD.log`（日期滚动，用 `getConfigDir()`）
+- 追加写（`writeFileSync(..., { flag: "a" })`），日志行格式：`[HH:mm:ss] [level] msg`（JSON 参数摘要截断 200 字符）
+- 清理：initLogger 时删除 7 天前的日志文件
+- 记录点：
+  - agent.ts `runOnceCore` 开头：`log("info", `run start mode=${mode} model=${model.modelId} messages=${messages.length}`)`
+  - tool-call 事件：`logToolCall`
+  - tool-result 事件：`logToolResult`
+  - 错误：`log("error", ...)`（onStreamError / catch 路径）
+  - runOnceCore 结束：`log("info", `run end steps=${stepCount} tokens=...`)`
+  - cli.ts 启动：`log("info", "min-agent started")`
+- 不记录消息内容（隐私），只记录数量与工具参数摘要
+
+### 5. CI（新文件 .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
+```
+
+（仓库根为 bun workspaces monorepo；typecheck 脚本在根 package.json）
+
+### 6. /plan 计划模式（src/agent.ts + tui-chat.ts）
+
+- `RunOptions` 加 `planMode?: boolean`
+- `runOnceCore` 的 `buildTools` 结果在 planMode 时过滤：
+  - 移除：`bash`、`write`、`edit`、`apply_patch`（写/执行类）
+  - 保留：`read`、`glob`、`grep`、`web_search`、`web_fetch`、`todo`、`question`、`explore`（内部只读 bash）、`skill`、mcp 工具、memory 工具、plugin 工具（保留——插件只读性未知，但删除会让插件用户困惑；保留并说明）
+- TUI `/plan`：切换 planMode 状态（`let planMode = false`）：
+  - 进入：sysMsg 提示"计划模式：仅只读工具可用，输出计划后再次输入 /plan 确认并执行"
+  - 退出：sysMsg 提示"已退出计划模式"
+- executeAgent 调 runOnce 时传 `{ ...(planMode ? { planMode: true } : {}) }`（与 options 合并）
+- `/redo` 等不受影响
+
+### 7. 文档完善
+
+- `README.md`：Configuration 区更新（providers[] 结构 + 迁移说明 + sampling/budget 字段）、Commands 区加 `--provider`、交互命令加 `/provider` `/budget` `/plan`、日志位置说明
+- `docs/API.md`：`/v1/chat` 请求加 `provider` 字段；done 事件加 `budget_exceeded`
+- `src/cli.ts` printUsage：`--provider`、setup 新流程说明
+- `/help` 与 `slash-commands.ts` 菜单同步（/provider、/budget、/plan）
+
+## 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| --provider 指定不存在 | 报错 `Provider "x" not found` exit 1 |
+| 无 providers 且无旧配置 | isConfigured false，"Run: min-agent setup" |
+| 预算超限 | 回合结束提示，不中断；/budget 调高后继续 |
+| 日志写入失败 | 静默忽略（log 内 try/catch），不阻塞主流程 |
+| 迁移写回失败 | 内存中继续使用迁移后配置，忽略写回错误 |
+
+## 测试
+
+| 文件 | 覆盖 |
+|------|------|
+| `tests/config.test.ts`(改) | 旧格式自动迁移（provider → providers[]）、activeProvider 解析、getActiveProvider |
+| `tests/provider.test.ts`(改) | resolveModel 按 activeProvider / providerName 覆盖 / 不存在报错 |
+| `tests/logger.test.ts`(新) | 日志写入格式、日期滚动文件名、7 天清理（mock 时间或直接创建旧文件） |
+| `tests/serve.test.ts`(改) | body.provider 覆盖、done 事件 budget_exceeded |
+| 预算逻辑 | runOnceCore 结束检查（纯函数提取 `shouldStopForBudget(totalTokens, price, maxCostUSD)` 可测） |
+| 采样回退 | config.sampling 生效（无 API options 时）—— 函数级验证 |
+
+验证命令（`packages/min-agent` 下）：`bun test`、`bun run typecheck`（仓库根）、手动冒烟。
+
+## 文档同步清单
+
+- `README.md`：Configuration 区、Commands、交互命令、日志
+- `docs/API.md`：provider 字段、budget_exceeded
+- `src/cli.ts` printUsage、TUI `/help`、`src/tui/slash-commands.ts` 菜单

package/docs/superpowers/specs/2026-08-16-input-caret-design.md

@@ -0,0 +1,63 @@
+# 输入框光标编辑设计
+
+日期:2026-08-16
+状态:已批准(用户确认设计)
+
+## 问题
+
+min-agent TUI 输入框的光标固定在文本末尾:
+- 左右键被显式忽略(InputBar.tsx:172),无法移动光标
+- 点击输入框无任何反应(未启用终端鼠标协议)
+- 用户无法在文本中间插入/删除内容
+
+## 目标
+
+1. 左右键移动光标(跨折行边界可达全文)
+2. 点击输入框定位光标
+3. 所有编辑操作(输入/退格/删除)在光标处进行
+
+## 设计
+
+### 1. 光标状态
+
+InputBar 新增 `caretIndex` state,基于 code point 数组索引(`Array.from(value)`),兼容 CJK/emoji。
+
+- 左右键:`caretIndex ± 1`;行首左移 → 上一行尾,行尾右移 → 下一行头
+- 输入字符:插入到 `caretIndex`
+- 退格:删 `caretIndex - 1`;Delete:删 `caretIndex`
+- Enter/提交、斜杠菜单逻辑不变
+- menuOpen 时:上下键选菜单,左右键不移动光标(保持现状)
+
+### 2. 点击定位(SGR 鼠标协议)
+
+- 启用:`\x1b[?1000h\x1b[?1006h`(按下事件 + SGR 格式);卸载/卸载组件时:`\x1b[?1000l\x1b[?1006l`
+- 鼠标序列在 InputBar 已有的 raw stdin 监听中解析(与 Kitty Shift+Enter 共用通道);useInput 中过滤残留片段(类似 `isKittySequenceFragment`)
+- 输入框绝对位置:输入框渲染在 App footer,其起始行 = `terminalRows - 输入框视觉行数 + 1`;点击行落在输入框内容区内才处理
+- 坐标换算:点击列 → 行内字符索引,逐字符按 `displayWidth` 累加,找到最接近点击列的边界(全角字符取最近边界)
+
+### 3. 光标渲染与硬件光标
+
+- `█` 块移动到 `caretIndex` 处(渲染该行时插入);空值时在 gutter 后显示 `█`
+- caret.ts 的 rowsAbove 计算:光标不再恒在最后一行,`rowsAbove = 输入框总行数 - 光标行号 + border/hint/menu 行数`;caret.ts 本身无需修改(接受任意 rowsAbove/column)
+
+### 4. 文件改动
+
+| 文件 | 改动 |
+|---|---|
+| `src/tui/InputBar.tsx` | caretIndex state、左右键/插入/退格逻辑、`█` 渲染位置、鼠标启用与解析 |
+| `src/tui/mouse.ts`(新) | 鼠标协议启用/禁用序列、`parseSgrMouse()` 纯函数 |
+| `src/tui/caret-pos.ts`(新) | 视觉行 → 字符索引换算、光标跨行移动等纯函数 |
+
+### 5. 测试
+
+- `parseSgrMouse` 序列解析(按下事件、坐标提取、非鼠标序列返回 null)
+- 点击坐标 → caretIndex 换算(含 CJK 宽度、折行、空行)
+- 左右键跨行移动边界(行首/行尾)
+- 插入/退格/删除在光标处
+
+## 不做(YAGNI)
+
+- 鼠标选中文本、拖拽选择
+- 点击斜杠菜单项选择
+- 上下键行间移动(左右键跨行已覆盖)
+- Home/End、Ctrl+A/E 等快捷键