min-agent 0.5.0 → 0.5.1

package/docs/superpowers/plans/2026-08-23-cli-setup.md

@@ -0,0 +1,501 @@
+# CLI setup 向导改版 — 实现计划
+
+> **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 setup` 成为全局服务商向导与循环管理器；flag 齐了可非交互；TTY 下未配置的交互会话直进同一套首次向导。密钥不回显；Ink 全向导不在 CI 跑。
+
+**Architecture:** 纯函数在 `provider-form.ts`（名称、掩码、增删改切）。`fetchModelsLive` 返回实时结果且不把缓存当成功；`fetchModels` 仍给 TUI/`models` 做按 baseURL 分桶的缓存回退。`flow.ts` 注入 `isTty` / `fetchLive` / `wizard`。一次性 Ink 应用在 `ui.tsx`，不抽 `ModelPicker`。根命令 `--model` 不复用；写入默认模型用 `--default-model`。`--yes` 读根 option，setup 里只表示跳过确认。
+
+**Tech Stack:** TypeScript, React 18 + Ink 5, commander 14, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-23-cli-setup-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`、`bun run check`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|------|------|
+| `src/cli/setup/provider-form.ts`（新） | `suggestName`、`validateProviderName`、`maskApiKey`、`filterChoices`、`applyAdd`/`applySwitch`/`applyUpdate`/`applyRemove` |
+| `src/cli/setup/detect.ts`（新） | 800ms 探测 `localhost:11434/api/tags` |
+| `src/cli/setup/flow.ts`（新） | 非交互编排 + TTY 分流；可注入 deps |
+| `src/cli/setup/ui.tsx`（新） | Ink 首次向导 + 管理器 |
+| `src/cli/commands/setup.ts`（改） | flag、调用 flow |
+| `src/cli/commands/index.ts`（改） | 注册 setup options |
+| `src/cli/commands/shared.ts`（改） | TTY 未配置直进向导 |
+| `src/config.ts`（改） | `fetchModelsLive`、缓存分桶；删除 `runSetup`/`ask`/`collectProvider` |
+| `src/cli/program.ts`（改） | help 文案 |
+| `README.md`、`skills/self-config/SKILL.md`、`reference.md`（改） | 用户/agent 文档 |
+| `tests/setup-form.test.ts`（新） | 纯函数 |
+| `tests/setup-detect.test.ts`（新） | 探测 |
+| `tests/models-cache.test.ts`（新） | 分桶缓存 + live |
+| `tests/setup-cli.test.ts`（新） | 非交互 CLI |
+| `tests/setup-flow.test.ts`（新） | 分流、不启动 Ink |
+
+`docs/API.md`、`exec`/`serve`/`models` 未配置硬错误、TUI `/help`、权限/沙箱/思考/记忆命令 **不改**。
+
+非交互 CLI 的 flag 校验文案跟现有命令一致（英文 `Invalid --context-window value`）。向导里的窗口/名称错误用 spec 中文。
+
+---
+
+## Task 1: provider-form 纯函数
+
+**Files:**
+- Create: `src/cli/setup/provider-form.ts`
+- Test: `tests/setup-form.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import type { AppConfig } from "../src/config.js"
+import {
+  applyAddProvider,
+  applyRemoveProvider,
+  applySwitchProvider,
+  applyUpdateProvider,
+  filterChoices,
+  maskApiKey,
+  suggestName,
+  validateProviderName,
+} from "../src/cli/setup/provider-form.js"
+
+test("suggestName uses type defaults and host slug", () => {
+  expect(suggestName("openai", "https://api.openai.com/v1", [])).toBe("openai")
+  expect(suggestName("ollama", "http://localhost:11434/v1", [])).toBe("ollama")
+  expect(suggestName("openai-compatible", "https://www.OpenRouter.ai/api/v1", [])).toBe("openrouter-ai")
+  expect(suggestName("openai-compatible", "not-a-url", [])).toBe("provider")
+})
+
+test("suggestName suffixes on conflict", () => {
+  expect(suggestName("openai", "", ["openai"])).toBe("openai-2")
+  expect(suggestName("openai", "", ["openai", "openai-2"])).toBe("openai-3")
+})
+
+test("validateProviderName rejects empty slash and colon", () => {
+  expect(validateProviderName("")).toBeTruthy()
+  expect(validateProviderName("  ")).toBeTruthy()
+  expect(validateProviderName("a/b")).toBeTruthy()
+  expect(validateProviderName("a:b")).toBeTruthy()
+  expect(validateProviderName("groq")).toBeNull()
+})
+
+test("maskApiKey never returns the full key", () => {
+  expect(maskApiKey("")).toBe("****")
+  expect(maskApiKey("abc")).toBe("****")
+  expect(maskApiKey("sk-abcdefghijklmnop")).toBe("…mnop")
+  expect(maskApiKey("sk-abcdefghijklmnop")).not.toContain("sk-abcdef")
+})
+
+test("filterChoices is case-insensitive", () => {
+  expect(filterChoices("gpt", ["GPT-4o", "claude", "gpt-4o-mini"])).toEqual(["GPT-4o", "gpt-4o-mini"])
+})
+
+const base: AppConfig = {
+  providers: [{ name: "a", type: "openai", baseURL: "https://api.openai.com/v1", apiKey: "k1", defaultModel: "m1" }],
+  activeProvider: "a",
+  futureKey: 1,
+} as AppConfig & { futureKey: number }
+
+test("applyAddProvider appends and activates", () => {
+  const next = applyAddProvider(base, {
+    name: "b",
+    type: "ollama",
+    baseURL: "http://localhost:11434/v1",
+    apiKey: "ollama",
+    defaultModel: "llama3",
+  }, { overwrite: false })
+  expect("error" in next).toBe(false)
+  if ("error" in next) return
+  expect(next.activeProvider).toBe("b")
+  expect(next.providers).toHaveLength(2)
+  expect((next as { futureKey?: number }).futureKey).toBe(1)
+})
+
+test("applyAddProvider rejects duplicate without overwrite", () => {
+  const next = applyAddProvider(base, {
+    name: "a",
+    type: "openai",
+    baseURL: "https://api.openai.com/v1",
+    apiKey: "k2",
+    defaultModel: "m2",
+  }, { overwrite: false })
+  expect("error" in next).toBe(true)
+})
+
+test("applyAddProvider overwrite replaces same name", () => {
+  const next = applyAddProvider(base, {
+    name: "a",
+    type: "openai",
+    baseURL: "https://api.openai.com/v1",
+    apiKey: "k2",
+    defaultModel: "m2",
+  }, { overwrite: true })
+  expect("error" in next).toBe(false)
+  if ("error" in next) return
+  expect(next.providers?.[0]?.apiKey).toBe("k2")
+  expect(next.activeProvider).toBe("a")
+})
+
+test("applySwitchProvider and missing name", () => {
+  expect("error" in applySwitchProvider(base, "nope")).toBe(true)
+  const next = applySwitchProvider(
+    { ...base, providers: [...(base.providers ?? []), { name: "b", baseURL: "u", apiKey: "k" }] },
+    "b",
+  )
+  expect("error" in next).toBe(false)
+  if ("error" in next) return
+  expect(next.activeProvider).toBe("b")
+})
+
+test("applyUpdateProvider renames and syncs activeProvider", () => {
+  const next = applyUpdateProvider(base, "a", {
+    name: "renamed",
+    type: "openai",
+    baseURL: "https://api.openai.com/v1",
+    apiKey: "k1",
+    defaultModel: "m1",
+  })
+  expect("error" in next).toBe(false)
+  if ("error" in next) return
+  expect(next.providers?.[0]?.name).toBe("renamed")
+  expect(next.activeProvider).toBe("renamed")
+})
+
+test("applyRemoveProvider drops active then last", () => {
+  const two: AppConfig = {
+    providers: [
+      { name: "a", baseURL: "u1", apiKey: "k1" },
+      { name: "b", baseURL: "u2", apiKey: "k2" },
+    ],
+    activeProvider: "a",
+  }
+  const afterA = applyRemoveProvider(two, "a")
+  expect("error" in afterA).toBe(false)
+  if ("error" in afterA) return
+  expect(afterA.activeProvider).toBe("b")
+  const empty = applyRemoveProvider(afterA, "b")
+  expect("error" in empty).toBe(false)
+  if ("error" in empty) return
+  expect(empty.providers ?? []).toEqual([])
+  expect(empty.activeProvider).toBeUndefined()
+})
+```
+
+`apply*` 返回 `AppConfig` 或 `{ error: string }`（中文错误，与 spec 一致：找不到、同名、非法名）。`error` 字符串给 CLI 包一层 `CliError`，本文件不 import commander。
+
+- [ ] **Step 2: 实现并跑测试**
+
+```bash
+cd packages/min-agent && bun test tests/setup-form.test.ts
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add packages/min-agent/src/cli/setup/provider-form.ts packages/min-agent/tests/setup-form.test.ts
+git commit -m "feat: 抽出 setup 的服务商表单纯函数"
+```
+
+---
+
+## Task 2: 模型列表 live 结果与按 URL 分桶缓存
+
+**Files:**
+- Modify: `src/config.ts`
+- Test: `tests/models-cache.test.ts`
+
+把 `loadModelsCache`/`saveModelsCache` 改为 `Record<string, string[]>`，key = `baseURL.replace(/\/$/, "")`。旧文件若是 `string[]` 或坏 JSON → 当作空。
+
+新增并导出：
+
+```ts
+export interface FetchModelsLiveResult {
+  models: string[]
+  ok: boolean
+  status?: number
+}
+
+export async function fetchModelsLive(baseURL: string, apiKey: string): Promise<FetchModelsLiveResult>
+```
+
+- 实时请求现有 `/models`（及无 `/v1` 时的 `/v1/models` 回退）
+- `ok: true` 且 `models.length > 0` 时写入该 URL 的缓存桶
+- HTTP 非 2xx：`ok: false`，带 `status`，`models: []`，**不读缓存**
+- 网络抛错：`ok: false`，无 status，`models: []`，不读缓存
+
+`fetchModels(baseURL, apiKey)` 保持给 TUI/`models`：先 live，空则回退**该 URL** 的缓存（不是全局一份列表）。
+
+- [ ] **Step 1: 写失败测试**（`globalThis.fetch` 替换，隔离 `MIN_AGENT_CONFIG_DIR`）
+
+覆盖：
+
+1. live 200 写入分桶；换另一个 baseURL 读不到上一份
+2. 旧 `models-cache.json` 为 `["a"]` 时 `fetchModels` 在 live 空时不把 `a` 当成该 URL 的缓存
+3. `fetchModelsLive` 在 401 时 `ok: false`、`status: 401`、`models: []`；随后 `fetchModels` 仍可因缓存回退（若之前成功写过）——401 这次不得把缓存写进 live 结果
+4. live 成功后 `fetchModels` 网络失败则回退该 URL 缓存
+
+- [ ] **Step 2: 实现并跑测试**
+
+```bash
+cd packages/min-agent && bun test tests/models-cache.test.ts tests/config.test.ts
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add packages/min-agent/src/config.ts packages/min-agent/tests/models-cache.test.ts
+git commit -m "feat: 模型列表按服务商缓存，并提供实时拉取"
+```
+
+---
+
+## Task 3: 探测本机 Ollama
+
+**Files:**
+- Create: `src/cli/setup/detect.ts`
+- Test: `tests/setup-detect.test.ts`
+
+```ts
+export interface OllamaDetectResult {
+  found: boolean
+  baseURL?: string // 已 normalizeOllamaBaseURL
+}
+
+export async function detectLocalOllama(opts?: {
+  fetchImpl?: typeof fetch
+  timeoutMs?: number
+}): Promise<OllamaDetectResult>
+```
+
+默认 `GET http://localhost:11434/api/tags`，`AbortSignal.timeout(800)`。2xx 视为 found，`baseURL` 为 `http://localhost:11434/v1`。超时/网络/非 2xx → `{ found: false }`，不抛。
+
+- [ ] **Step 1: 写失败测试**（注入 `fetchImpl`）
+
+- [ ] **Step 2: 实现并跑**
+
+```bash
+cd packages/min-agent && bun test tests/setup-detect.test.ts
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add packages/min-agent/src/cli/setup/detect.ts packages/min-agent/tests/setup-detect.test.ts
+git commit -m "feat: setup 可探测本机 Ollama"
+```
+
+---
+
+## Task 4: 非交互 flow + CLI flag
+
+**Files:**
+- Create: `src/cli/setup/flow.ts`
+- Create: `src/cli/setup/flags.ts`（类型 + 互斥/缺项校验，可选，避免 flow 过大）
+- Modify: `src/cli/commands/setup.ts`
+- Modify: `src/cli/commands/index.ts`
+- Test: `tests/setup-cli.test.ts`、`tests/setup-flow.test.ts`
+
+`SetupFlags`：
+
+```ts
+export interface SetupFlags {
+  type?: "openai-compatible" | "openai" | "ollama"
+  url?: string
+  apiKey?: string
+  name?: string
+  defaultModel?: string
+  contextWindow?: number
+  switch?: string
+  remove?: string
+  yes?: boolean
+}
+```
+
+`isNonInteractive(flags)`：`--type` / `--switch` / `--remove` 任一出现。
+
+互斥：`type` 与 `switch`/`remove` 同时出现 → `CliError("一次只能执行一种操作。")`。
+
+`runSetup(flags, deps)`：
+
+- 非交互：不调用 `deps.runWizard`
+- `--remove`：找不到 → 中文 CliError；非 TTY 且无 `yes` → `删除需要确认。` hint `加上 --yes`；否则 `applyRemoveProvider` + `saveConfig`，打印已保存路径
+- `--switch`：`applySwitchProvider` + 保存
+- `--type`：补默认 URL/Key（ollama：`normalizeOllamaBaseURL(url ?? localhost)`，key `ollama`；openai：官方 URL）；缺 URL/Key 按 spec 中文 CliError；无 `--default-model` 则 `fetchLive`，ollama 失败用 `llama3`，openai / compatible 空模型 → 码 1「默认模型不能为空。」；`fetchLive` 抛错且非 ollama 回退 → 码 2；名称 `flags.name ?? suggestName(...)`；同名无 `yes` → 码 1 + hint `加上 --yes 以覆盖`；有 yes 则 overwrite；`--context-window` 写入 draft
+- 无非交互 flag：若 `!deps.isTty` → `无法在非交互环境完成配置。` + hint 列出 flag；若 TTY → `deps.runWizard({ mode: hasProvider ? "hub" : "first-run" })`
+
+本任务 `runWizard` 可先做成：**仍调用现有 `runSetup()` from config.ts**，保证交互不被破坏。下一任务再换 Ink。
+
+`setup.ts` 从 `rootOpts().yes` 取 `--yes`，`isTty: Boolean(process.stdin.isTTY && process.stdout.isTTY)`。
+
+index.ts：setup 子命令声明 `--type/--url/--api-key/--name/--default-model/--context-window/--switch/--remove`。`--context-window` 用 `parsePositiveIntArg("--context-window")`。`--type` 非法值 → `CliError` 列出三个合法值。
+
+description：`Configure providers (interactively, or with flags)`。
+
+- [ ] **Step 1: 写 `setup-flow.test.ts`**
+
+注入内存 config + mock `fetchLive` / `runWizard`：
+
+- 非 TTY 无 flag → 抛错且 `runWizard` 未被调用
+- `--type ollama` 写入 llama3（fetch 空）
+- `--type openai` 无 key → 码 1
+- 同名无 yes 失败；有 yes 覆盖
+- `--switch` / `--remove --yes`
+- `--type` + `--remove` 互斥
+- stdout 不含完整 key（`save` 后打印掩码或只打印路径）
+
+- [ ] **Step 2: 写 `setup-cli.test.ts`**
+
+仿 `cli-invoke.test.ts` 的 `runCli` + `MIN_AGENT_CONFIG_DIR`，`stdin: "ignore"`：
+
+- `setup --type ollama` 退出 0，config 可 `isConfigured` 语义（有 baseURL+apiKey+model）
+- `setup --type openai --api-key SECRETKEY1234 --default-model gpt-4o`；stderr/stdout 不含 `SECRETKEY1234`
+- 缺 key 退出 1
+- 同名第二次无 `--yes` 退出 1；带 `--yes` 覆盖
+- `--switch` / `--remove --yes`
+- `--type ollama --remove x` 退出 1
+- 无 flag 的 `setup` 退出 1 且不写 `providers`
+- 空 argv 仍 `Not configured`（可放在本文件或依赖现有 `cli-invoke.test.ts`）
+
+- [ ] **Step 3: 实现，跑测试**
+
+```bash
+cd packages/min-agent && bun test tests/setup-flow.test.ts tests/setup-cli.test.ts tests/cli-invoke.test.ts
+```
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add packages/min-agent/src/cli/setup/flow.ts packages/min-agent/src/cli/setup/flags.ts packages/min-agent/src/cli/commands/setup.ts packages/min-agent/src/cli/commands/index.ts packages/min-agent/tests/setup-flow.test.ts packages/min-agent/tests/setup-cli.test.ts
+git commit -m "feat: setup 支持非交互 flag 管理服务商"
+```
+
+---
+
+## Task 5: Ink 首次向导与管理器
+
+**Files:**
+- Create: `src/cli/setup/ui.tsx`
+- Modify: `src/cli/setup/flow.ts`（`runWizard` 默认实现改为 `renderSetupWizard`）
+- Modify: `src/config.ts`（本任务结束时删除 `runSetup`/`ask`/`collectProvider` 及 `readline` import）
+
+`renderSetupWizard(opts: { mode: "session-gate" | "first-run" | "hub" }): Promise<"saved" | "aborted">`
+
+用 `ink.render()`，结束 `unmount`。主题可复用 `src/tui/theme.ts` 的颜色 token，不要 import TUI overlay 组件。
+
+屏幕按 spec §4–§5：S0–S5、H0 及子动作。Key 输入掩码；修改时空提交保留原 Key。拉模型用 `fetchModelsLive`，空 → S3b。Esc/Ctrl+C → aborted，除管理器里**已经 saveConfig 过的步骤**外不写盘。
+
+管理器「测试连接」展示 `可访问，N 个模型` 或 `无法连接到该服务商。` + status + 提示；剥掉 body 里的 `Bearer` / `sk-`。
+
+S1 进入前 `detectLocalOllama()`；found 则标注「已检测到」并默认选 Ollama。
+
+不在 CI 跑 Ink。`filterChoices` 已在 Task 1。
+
+- [ ] **Step 1: 实现 ui + 把 flow 的 TTY 分支接到它；删掉 config.ts 旧向导**
+
+确认无残留 `runSetup` 引用（`rg runSetup packages/min-agent/src`）。
+
+- [ ] **Step 2: 跑已有测试 + typecheck**
+
+```bash
+cd packages/min-agent && bun test tests/setup-form.test.ts tests/setup-flow.test.ts tests/setup-cli.test.ts tests/models-cache.test.ts
+npx tsc --noEmit
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add packages/min-agent/src/cli/setup packages/min-agent/src/config.ts packages/min-agent/src/cli/commands/setup.ts
+git commit -m "feat: setup 用 Ink 向导配置服务商"
+```
+
+---
+
+## Task 6: 未配置会话直进向导
+
+**Files:**
+- Modify: `src/cli/commands/shared.ts`
+
+`startTuiSession`：`!isConfigured()` 时若 `process.stdin.isTTY && process.stdout.isTTY`，调用 `runSetup({} as flags, deps)` 且 wizard mode 为 `session-gate`（S0）。成功且 `isConfigured()` 后继续 `runTui`，**原样传递** `model/provider/resume/images/positionals`。向导 aborted 或仍未配置 → `CliError("Not configured.", { hint: "Run: min-agent setup" })` 码 1。
+
+非 TTY 保持现有硬错误。`exec`/`serve`/`models` 不调用 `startTuiSession` 的此分支（它们自己检查 `isConfigured`）。
+
+- [ ] **Step 1: `setup-flow.test.ts` 增测**
+
+导出 `shouldOfferSetupWizard(isConfigured, isTty)` 或测 `startTuiSession` 的纯前置：非 TTY 不 offer。不要在 CI 真 render Ink。
+
+现有 `cli-invoke.test.ts` 空 argv 仍匹配 `/Not configured/`。
+
+- [ ] **Step 2: 实现并跑**
+
+```bash
+cd packages/min-agent && bun test tests/cli-invoke.test.ts tests/setup-flow.test.ts
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add packages/min-agent/src/cli/commands/shared.ts packages/min-agent/tests/setup-flow.test.ts
+git commit -m "feat: 未配置的交互会话在终端里直接进入 setup"
+```
+
+---
+
+## Task 7: README、help、self-config
+
+**Files:**
+- Modify: `README.md`（中英 Configuration / 配置：保留引导句；各加三例）
+
+```bash
+min-agent setup --type ollama
+min-agent setup --type openai-compatible --url https://api.example.com/v1 --api-key "$KEY" --name groq --default-model llama-3.1-70b
+min-agent setup --switch ollama
+```
+
+不写模块路径、Ink、缓存文件名。
+
+- Modify: `src/cli/program.ts` after-help：`min-agent setup` 一行改为带常用 flag；Examples 加一条非交互
+- Modify: `skills/self-config/SKILL.md` Providers：CLI `min-agent setup` 及 `--type/--url/--api-key/--name/--default-model/--switch/--remove`；`--yes` 在 setup 中跳过覆盖/删除确认，不写 permission
+- Modify: `skills/self-config/reference.md`：字段示例不变；补一句交互与非交互添加都走 setup，密钥只写全局
+
+`docs/API.md`、`/help` 不改。
+
+- [ ] **Step 1: 改文案**
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add packages/min-agent/README.md packages/min-agent/src/cli/program.ts packages/min-agent/skills/self-config/SKILL.md packages/min-agent/skills/self-config/reference.md
+git commit -m "docs: 说明 setup 的引导与非交互用法"
+```
+
+---
+
+## Task 8: 回归
+
+- [ ] **Step 1:**
+
+```bash
+cd packages/min-agent && bun test tests/setup-form.test.ts tests/setup-detect.test.ts tests/models-cache.test.ts tests/setup-flow.test.ts tests/setup-cli.test.ts tests/cli-invoke.test.ts tests/config.test.ts
+# 仓库根目录
+bun run typecheck
+bun run check
+```
+
+- [ ] **Step 2: 若格式问题则 `bun run format` 后再 check，不要 `--no-verify`**
+
+---
+
+## 手工验收
+
+在 `packages/min-agent` 下（隔离配置目录更佳：`MIN_AGENT_CONFIG_DIR=/tmp/min-agent-setup-demo`）：
+
+1. `bun run src/cli.ts setup --type ollama`（无 TTY 也行）写入后 `cat $MIN_AGENT_CONFIG_DIR/config.json` 有 ollama provider
+2. TTY：`bun run src/cli.ts setup` 出现可方向键选择的类型列表；Ollama 若本机在跑应标注已检测到
+3. 添加兼容接口，模型列表可输入过滤；Key 不在屏幕明文回显
+4. 再次 setup 进入管理器：切换、修改（回车保留 Key）、测连、删除确认、Esc 退出码 0
+5. 清空 config 后 TTY 跑 `bun run src/cli.ts` → S0「开始配置」；配完进入 TUI。管道：`bun run src/cli.ts </dev/null` 仍 `Not configured`
+6. `bun run src/cli.ts exec ping` 未配置仍硬错误，不进向导
+7. `bun run src/cli.ts setup --type openai --api-key sk-testdemokey9999 --default-model gpt-4o` 的终端输出不含完整 key