min-agent 0.4.1 → 0.5.1

package/docs/superpowers/plans/2026-08-23-thinking-wire-profile.md

@@ -0,0 +1,450 @@
+# 思考线协议适配 — 实现计划
+
+> **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:** 用户仍只配置 `off|low|medium|high|max`；发出 chat 请求时按 `(host, model)` 选择 `thinking.type` / `reasoning_effort` 的线协议。MiniMax 启发式先发 `adaptive`；其余若 400 且错误可解析，静默改 profile、同一请求只重试一次，并缓存 7 天。
+
+**Architecture:** 用户意图留在 `ThinkingRequestBody`（ALS）。新建 `thinking-wire.ts`：启发式、学习缓存、`parseThinkingWireHint`、`fetchWithThinkingWire`。`applyThinkingToChatBody` 增加 profile 参数。`modelFetch` 改为 `fetchWithThinkingWire(inner, …).then(foldReasoningInChatResponse)`。Lonae 目录不改。
+
+**Tech Stack:** TypeScript, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-23-thinking-wire-profile-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`、`bun run check`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|------|------|
+| `src/thinking-wire.ts`（新） | profile 类型、默认值、缓存键、启发式、缓存、hint 解析、`fetchWithThinkingWire` |
+| `src/thinking.ts`（改） | `applyThinkingToChatBody(body, spec, profile?)` |
+| `src/provider.ts`（改） | `modelFetch` 走 `fetchWithThinkingWire` |
+| `tests/thinking-wire.test.ts`（新） | 启发式、hint、缓存、fetch 重试 |
+| `tests/thinking.test.ts`（改） | 三种 thinkingType × 开/关、effort omit |
+| `skills/self-config/SKILL.md`（改） | 映射说明 + 缓存文件名 |
+| `skills/self-config/reference.md`（改） | `MIN_AGENT_CONFIG_DIR` 旁注明缓存文件 |
+
+`docs/API.md`、`README.md`、`/help`、Lonae catalog、`/think` UI **不改**。
+
+---
+
+## Task 1: thinking-wire 纯函数与缓存
+
+**Files:**
+- Create: `src/thinking-wire.ts`
+- Test: `tests/thinking-wire.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test, afterEach } from "bun:test"
+import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "fs"
+import os from "os"
+import path from "path"
+import {
+  DEFAULT_THINKING_WIRE,
+  THINKING_WIRE_TTL,
+  clearThinkingWireCache,
+  inferThinkingWire,
+  parseThinkingWireHint,
+  resolveThinkingWireProfile,
+  saveLearnedThinkingWire,
+  thinkingWireCacheKey,
+} from "../src/thinking-wire.js"
+
+function withIsolatedConfig(fn: () => void): void {
+  const home = realpathSync(mkdtempSync(path.join(os.tmpdir(), "min-agent-wire-")))
+  const old = process.env.MIN_AGENT_CONFIG_DIR
+  process.env.MIN_AGENT_CONFIG_DIR = home
+  clearThinkingWireCache()
+  try {
+    fn()
+  } finally {
+    clearThinkingWireCache()
+    if (old) process.env.MIN_AGENT_CONFIG_DIR = old
+    else delete process.env.MIN_AGENT_CONFIG_DIR
+    rmSync(home, { recursive: true, force: true })
+  }
+}
+
+afterEach(() => clearThinkingWireCache())
+
+test("cache key lowercases host and model", () => {
+  expect(thinkingWireCacheKey("Api.Example.COM", "MiniMax-M3")).toBe("api.example.com::minimax-m3")
+  expect(thinkingWireCacheKey("", "m")).toBe("m")
+})
+
+test("inferThinkingWire prefers minimax then openai then default", () => {
+  expect(inferThinkingWire("minimax-m3", "api.console.go", "openai-compatible")).toEqual({
+    thinkingType: "adaptive-disabled",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("gpt-4", "api.minimax.io", undefined)).toEqual({
+    thinkingType: "adaptive-disabled",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("gpt-5", "api.openai.com", "openai")).toEqual({
+    thinkingType: "omit",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("deepseek-v3", "api.deepseek.com", "openai-compatible")).toEqual({
+    thinkingType: "enabled-disabled",
+    effort: "reasoning_effort",
+  })
+})
+
+test("parseThinkingWireHint reads MiniMax allowed list", () => {
+  const raw =
+    'AI_APICallError: Error from provider (Console Go): Upstream request failed: [bad_request_error] invalid params, invalid thinking.type: "enabled" (allowed: adaptive, disabled) (2013)'
+  expect(parseThinkingWireHint(raw)).toEqual({ thinkingType: "adaptive-disabled" })
+  expect(parseThinkingWireHint('invalid thinking.type: "adaptive" (allowed: enabled, disabled)')).toEqual({
+    thinkingType: "enabled-disabled",
+  })
+})
+
+test("parseThinkingWireHint reads unknown parameter", () => {
+  expect(parseThinkingWireHint("Unknown parameter: 'thinking'")).toEqual({ thinkingType: "omit" })
+  expect(parseThinkingWireHint("unknown parameter: reasoning_effort")).toEqual({ effort: "omit" })
+  expect(parseThinkingWireHint("rate limit exceeded")).toBeNull()
+})
+
+test("resolveThinkingWireProfile prefers learned cache over heuristic", () => {
+  withIsolatedConfig(() => {
+    expect(resolveThinkingWireProfile("h.example", "minimax-m3").thinkingType).toBe("adaptive-disabled")
+    saveLearnedThinkingWire("h.example", "minimax-m3", {
+      ...DEFAULT_THINKING_WIRE,
+      thinkingType: "omit",
+      effort: "omit",
+    })
+    const learned = resolveThinkingWireProfile("h.example", "minimax-m3")
+    expect(learned.thinkingType).toBe("omit")
+    expect(learned.effort).toBe("omit")
+    const disk = JSON.parse(readFileSync(path.join(process.env.MIN_AGENT_CONFIG_DIR!, "thinking-wire-cache.json"), "utf-8"))
+    expect(disk["h.example::minimax-m3"].thinkingType).toBe("omit")
+  })
+})
+
+test("expired or wrong version cache is ignored", () => {
+  withIsolatedConfig(() => {
+    const file = path.join(process.env.MIN_AGENT_CONFIG_DIR!, "thinking-wire-cache.json")
+    writeFileSync(
+      file,
+      JSON.stringify({
+        "h::m": { version: 1, thinkingType: "omit", effort: "omit", timestamp: Date.now() - THINKING_WIRE_TTL - 1 },
+        "h::old": { version: 99, thinkingType: "omit", effort: "omit", timestamp: Date.now() },
+      }),
+    )
+    expect(resolveThinkingWireProfile("h", "m", "openai-compatible").thinkingType).toBe("enabled-disabled")
+    expect(resolveThinkingWireProfile("h", "old", "openai-compatible").thinkingType).toBe("enabled-disabled")
+  })
+})
+```
+
+先跑确认失败：
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+```
+
+- [ ] **Step 2: 实现**
+
+`src/thinking-wire.ts`（与 `model-catalog.ts` 同样用 `getConfigDir()` + `atomicWriteFileSync`）：
+
+```ts
+export const THINKING_WIRE_VERSION = 1
+export const THINKING_WIRE_TTL = 7 * 24 * 60 * 60 * 1000
+export const DEFAULT_THINKING_WIRE = {
+  version: THINKING_WIRE_VERSION,
+  thinkingType: "enabled-disabled" as const,
+  effort: "reasoning_effort" as const,
+}
+
+export type ThinkingTypeMode = "enabled-disabled" | "adaptive-disabled" | "omit"
+export type EffortMode = "reasoning_effort" | "omit"
+export interface ThinkingWireProfile {
+  version: number
+  thinkingType: ThinkingTypeMode
+  effort: EffortMode
+  timestamp: number
+}
+export type ThinkingWireHint = Partial<Pick<ThinkingWireProfile, "thinkingType" | "effort">>
+```
+
+- `thinkingWireCacheKey(host, modelId)`：都 `toLowerCase()`；host 空则只要 modelId
+- `inferThinkingWire(modelId, host, providerType?)`：`minimax` 出现在 model 或 host（大小写不敏感）→ adaptive-disabled；`providerType === "openai"` → omit thinking；否则默认
+- `resolveThinkingWireProfile(host, modelId, providerType?)`：有效学习缓存 → 否则启发式填 `timestamp: Date.now()`（启发式**不写盘**）
+- `saveLearnedThinkingWire` 写内存 + `thinking-wire-cache.json`
+- `clearThinkingWireCache()` 清内存（测试用）；磁盘随 `MIN_AGENT_CONFIG_DIR` 隔离
+- `parseThinkingWireHint(text)`：
+  - `/thinking\.type[\s\S]*?allowed:\s*([^)]+)/i`，列表按逗号拆、trim、去引号、小写；含 `adaptive` 且含 `disabled` → `adaptive-disabled`；含 `enabled` 且含 `disabled` → `enabled-disabled`
+  - `/unknown parameter[:\s]+['"`]?thinking['"`]?/i` → omit thinking（不要误匹配 `thinking.type` 那段里的 thinking）
+  - `/unknown parameter[:\s]+['"`]?reasoning_effort['"`]?/i` → omit effort
+  - 都不中 → `null`
+- 未知 `version` 或过期 → 当未命中。损坏 JSON → `{}`
+
+本任务**不要**实现 fetch 包装。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+git add src/thinking-wire.ts tests/thinking-wire.test.ts
+git commit -m "feat: 增加思考线协议 profile 与错误 hint 解析"
+```
+
+---
+
+## Task 2: applyThinkingToChatBody 按 profile 拼 body
+
+**Files:**
+- Modify: `src/thinking.ts`
+- Modify: `tests/thinking.test.ts`
+
+- [ ] **Step 1: 改测试**
+
+把现有「injects reasoning_effort and thinking.type」扩成显式 profile（缺省第三参 = `DEFAULT_THINKING_WIRE` 的 type/effort）：
+
+```ts
+import { DEFAULT_THINKING_WIRE } from "../src/thinking-wire.js"
+
+test("applyThinkingToChatBody follows thinkingType and effort modes", () => {
+  const specOn = { reasoningEffort: "high", thinkingEnabled: true }
+  const specOff = { reasoningEffort: "none", thinkingEnabled: false }
+  expect(applyThinkingToChatBody({ model: "m" }, specOn)).toEqual({
+    model: "m",
+    reasoning_effort: "high",
+    thinking: { type: "enabled" },
+  })
+  expect(
+    applyThinkingToChatBody({ model: "m" }, specOn, { ...DEFAULT_THINKING_WIRE, thinkingType: "adaptive-disabled" }),
+  ).toEqual({
+    model: "m",
+    reasoning_effort: "high",
+    thinking: { type: "adaptive" },
+  })
+  expect(applyThinkingToChatBody({ model: "m" }, specOff, { ...DEFAULT_THINKING_WIRE, thinkingType: "adaptive-disabled" })).toEqual({
+    model: "m",
+    reasoning_effort: "none",
+    thinking: { type: "disabled" },
+  })
+  expect(applyThinkingToChatBody({ thinking: { type: "enabled" }, reasoning_effort: "x" }, specOn, {
+    ...DEFAULT_THINKING_WIRE,
+    thinkingType: "omit",
+    effort: "omit",
+  })).toEqual({})
+})
+```
+
+- [ ] **Step 2: 实现**
+
+```ts
+export function applyThinkingToChatBody(
+  body: Record<string, unknown>,
+  spec: ThinkingRequestBody,
+  profile: Pick<ThinkingWireProfile, "thinkingType" | "effort"> = DEFAULT_THINKING_WIRE,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...body }
+  if (profile.effort === "omit") delete next.reasoning_effort
+  else next.reasoning_effort = spec.reasoningEffort
+  if (profile.thinkingType === "omit") delete next.thinking
+  else {
+    const on = profile.thinkingType === "adaptive-disabled" ? "adaptive" : "enabled"
+    next.thinking = { type: spec.thinkingEnabled ? on : "disabled" }
+  }
+  return next
+}
+```
+
+`ThinkingRequestBody` 不变。`resolveThinkingRequest` / `toWireEffort` 不变。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking.test.ts
+git add src/thinking.ts tests/thinking.test.ts
+git commit -m "feat: 按 wire profile 组装思考请求体"
+```
+
+---
+
+## Task 3: fetch 400 改参并只重试一次
+
+**Files:**
+- Modify: `src/thinking-wire.ts`
+- Modify: `tests/thinking-wire.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `thinking-wire.test.ts` 增加（仍用隔离 `MIN_AGENT_CONFIG_DIR` + `thinkingRequestStore.run`）：
+
+```ts
+import { thinkingRequestStore } from "../src/thinking.js"
+import { fetchWithThinkingWire } from "../src/thinking-wire.js"
+
+test("fetchWithThinkingWire retries once when 400 names adaptive", async () => {
+  withIsolatedConfig(() => {
+    const bodies: string[] = []
+    const inner: FetchLike = async (_input, init) => {
+      bodies.push(String(init?.body ?? ""))
+      if (bodies.length === 1) {
+        return new Response(
+          'invalid thinking.type: "enabled" (allowed: adaptive, disabled)',
+          { status: 400 },
+        )
+      }
+      return new Response("{}", { status: 200 })
+    }
+    return thinkingRequestStore.run({ reasoningEffort: "high", thinkingEnabled: true }, async () => {
+      const res = await fetchWithThinkingWire(inner, "https://gw.example/v1/chat/completions", {
+        method: "POST",
+        body: JSON.stringify({ model: "other-model", messages: [] }),
+      })
+      expect(res.status).toBe(200)
+      expect(bodies).toHaveLength(2)
+      expect(JSON.parse(bodies[0]!).thinking).toEqual({ type: "enabled" })
+      expect(JSON.parse(bodies[1]!).thinking).toEqual({ type: "adaptive" })
+    })
+  })
+})
+
+test("fetchWithThinkingWire does not retry unrelated 400", async () => {
+  withIsolatedConfig(() => {
+    let n = 0
+    const inner: FetchLike = async () => {
+      n++
+      return new Response("insufficient quota", { status: 400 })
+    }
+    return thinkingRequestStore.run({ reasoningEffort: "high", thinkingEnabled: true }, async () => {
+      const res = await fetchWithThinkingWire(inner, "https://gw.example/v1/chat/completions", {
+        method: "POST",
+        body: JSON.stringify({ model: "m" }),
+      })
+      expect(res.status).toBe(400)
+      expect(await res.text()).toBe("insufficient quota")
+      expect(n).toBe(1)
+    })
+  })
+})
+```
+
+`withIsolatedConfig` 若目前是同步的，改成支持 `fn: () => void | Promise<void>` 并 `await`。`FetchLike` 从 `fetch-timeout.js` 导入。
+
+再加一条：hint 相对当前 profile 无变化（已经是 adaptive，400 仍说 allowed adaptive）→ 不重试。可用 minimax 模型名让第一次就发 adaptive，inner 只 400 一次。
+
+- [ ] **Step 2: 实现 `fetchWithThinkingWire`**
+
+签名：
+
+```ts
+export async function fetchWithThinkingWire(
+  inner: FetchLike,
+  input: string | URL | Request,
+  init?: RequestInit,
+  opts?: { providerType?: string },
+): Promise<Response>
+```
+
+逻辑：
+
+1. `spec = thinkingRequestStore.getStore()`；无 spec 或 `init.body` 非字符串 → `return inner(input, init)`
+2. JSON.parse body；非对象 → `return inner(input, init)`
+3. `host` 从 `input` 解析 `URL.hostname`（`Request` 用 `.url`）；失败则 `""`
+4. `modelId` = body.model 字符串，否则 `""`
+5. `providerType` = `opts?.providerType ?? getActiveProvider(getEffectiveConfig())?.type`
+6. `profile = resolveThinkingWireProfile(host, modelId, providerType)`
+7. `firstInit = { ...init, body: JSON.stringify(applyThinkingToChatBody(parsed, spec, profile)) }`
+8. `first = await inner(input, firstInit)`；`first.status !== 400` → `return first`
+9. `text = await first.text()`；`hint = parseThinkingWireHint(text)`
+10. 合并 hint：`next = { ...profile, ...hint, version: 1, timestamp: Date.now() }`；`thinkingType` 与 `effort` 都与当前相同 → `return rebuild400(first, text)`
+11. `saveLearnedThinkingWire(host, modelId, next)`；第二次 `inner(input, { ...init, body: JSON.stringify(applyThinkingToChatBody(parsed, spec, next)) })`，**不再**根据第二次状态重试
+12. `rebuild400`：`new Response(text, { status: 400, statusText: first.statusText, headers: first.headers })`
+
+`getActiveProvider` 在 `thinking-wire.ts` 引用 `config.js` 可以；测试不依赖真实 config（默认走 enabled-disabled）。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+git add src/thinking-wire.ts tests/thinking-wire.test.ts
+git commit -m "feat: 思考字段 400 时改 profile 并只重试一次"
+```
+
+---
+
+## Task 4: 接入 modelFetch
+
+**Files:**
+- Modify: `src/provider.ts`
+
+- [ ] **Step 1: 接线**
+
+删除 `withThinkingBody`。`modelFetch`：
+
+```ts
+return (input, init) => fetchWithThinkingWire(inner, input, init).then(foldReasoningInChatResponse)
+```
+
+从 `thinking-wire.js` 导入 `fetchWithThinkingWire`；`thinking.ts` 不再被 `provider.ts` 直接用来拼 body（ALS 仍由 agent 设置，fetch 内部读）。
+
+现有 `tests/provider.test.ts` 应仍通过（不发真实请求）。
+
+- [ ] **Step 2: 测试并提交**
+
+```bash
+cd packages/min-agent && bun test tests/provider.test.ts tests/thinking-wire.test.ts tests/thinking.test.ts
+git add src/provider.ts
+git commit -m "feat: 模型请求走思考线协议适配"
+```
+
+---
+
+## Task 5: self-config 文档
+
+**Files:**
+- Modify: `skills/self-config/SKILL.md`
+- Modify: `skills/self-config/reference.md`
+
+- [ ] **Step 1: 文案**
+
+`SKILL.md` 思考段落里「The request sends `reasoning_effort` plus `thinking.type`」改为：请求会按当前模型和网关映射思考字段（例如 MiniMax 用 `adaptive`/`disabled`，官方 OpenAI 不发 `thinking` 对象）；学到的映射缓存在 `~/.min-agent/thinking-wire-cache.json`（7 天）。官方 OpenAI 仍把 `max` 映射为 `xhigh`。不要写 400 重试、fetch 包装、profile 类型名。
+
+`reference.md` 环境变量表 `MIN_AGENT_CONFIG_DIR` 一行改为同时提到目录缓存与思考映射缓存，例如：`Replaces ~/.min-agent`（含 `model-catalog-cache.json`、`thinking-wire-cache.json`）。
+
+README / API.md / `/help` 不改。
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add packages/min-agent/skills/self-config/SKILL.md packages/min-agent/skills/self-config/reference.md
+git commit -m "docs: 说明思考请求按模型映射线协议"
+```
+
+（在仓库根目录 add 时用上表路径；在 `packages/min-agent` 内则用 `skills/self-config/…`。）
+
+---
+
+## Task 6: 回归
+
+- [ ] **Step 1: 全量相关测试与检查**
+
+```bash
+cd packages/min-agent && bun test tests/thinking.test.ts tests/thinking-wire.test.ts tests/provider.test.ts
+# 仓库根目录
+bun run typecheck
+bun run check
+```
+
+- [ ] **Step 2: 若有格式问题则 `bun run format` 后再 check，不要 `--no-verify`**
+
+---
+
+## 手工验收
+
+在 `packages/min-agent` 下用 MiniMax-M3（思考非 off）发一句 `hello`：
+
+1. 不应再出现 `invalid thinking.type: "enabled"`
+2. 状态栏仍是「思考 high」这类用户档位，不出现 `adaptive`
+3. 换一个会 400 且错误带 `allowed: adaptive, disabled` 的网关：第一次失败后同一句应自动成功；`~/.min-agent/thinking-wire-cache.json` 出现对应 host+model 条目
+4. `/think off` 发送 `disabled`，对话仍可用