min-agent 0.4.0 → 0.5.0

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

@@ -0,0 +1,140 @@
+# 思考线协议适配 — 设计文档
+
+**日期:** 2026-08-23
+**状态:** 已批准（启发式 + 400 改参重试并缓存）
+
+## 问题
+
+用户配置是统一的 `off | low | medium | high | max`，但上游 chat 请求的思考字段因模型和网关而异。min-agent 目前一律发送：
+
+```json
+{ "reasoning_effort": "<档位>", "thinking": { "type": "enabled" | "disabled" } }
+```
+
+MiniMax-M3（经 Console Go 等网关）只接受 `thinking.type` 为 `adaptive` 或 `disabled`，收到 `enabled` 会 400。官方 OpenAI 则可能根本不认 `thinking` 对象。
+
+模型目录（`models.lonae.com`）只提供上下文窗口和 effort 列表，**不提供** `thinking.type` 的合法取值。MiniMax-M3 的 `reasoningOptions` 甚至是空数组，目录查找成功也无法避免这次 400。
+
+## 目标
+
+1. 用户侧配置、`/think`、CLI `--think`、HTTP `/v1/thinking` 仍只用五档英文强度，不暴露 `adaptive` / `enabled` / `xhigh`
+2. 发出请求前按 `(providerHost, modelId)` 选择线协议：启发式先发对
+3. 若仍 400 且错误可解析为思考字段约束，静默改 profile、**同一请求只重试一次**，并把学到的 profile 写入本地缓存
+4. 目录继续只负责窗口和档位列表；线协议与目录解耦
+
+## 不做
+
+- 不扩展 Lonae catalog schema
+- 不把 `adaptive` 放进 `/think` 选择器或配置值
+- 不为 MiniMax-M3 把选择器收成「开/关」（非 `off` 一律当开思考；档位无深度时仍发对应 `reasoning_effort`，由上游忽略）
+- 不重试非思考类 400，不二次以上重试
+- 不把 wire profile 写入 `config.json`
+- 不改变 compaction、reasoning 流式折叠、TUI 思考块展示
+
+## 设计决策
+
+| 决策 | 结论 |
+|------|------|
+| 用户配置 | 仍是 `off\|low\|medium\|high\|max`；`thinkingEnabled = thinking !== "off"` |
+| 线协议层 | 独立 wire profile，不塞进 Lonae 缓存条目 |
+| 解析顺序 | 学习缓存 → 启发式 → 默认 `enabled-disabled` + `reasoning_effort` |
+| 注入点 | 现有 `modelFetch` / `withThinkingBody`，可读写 URL 与 JSON body |
+| 400 | 仅当 body 可解析为思考字段约束时改 profile 并重试一次；对用户静默 |
+| 缓存文件 | `~/.min-agent/thinking-wire-cache.json`（`MIN_AGENT_CONFIG_DIR` 下同路径），TTL 7 天 |
+| OpenAI 官方 | `provider.type === "openai"` → 不发 `thinking` 对象 |
+| MiniMax | `modelId` 或 hostname 含 `minimax`（大小写不敏感）→ `adaptive-disabled` |
+
+---
+
+## 1. Wire profile
+
+```ts
+type ThinkingTypeMode = "enabled-disabled" | "adaptive-disabled" | "omit"
+type EffortMode = "reasoning_effort" | "omit"
+
+interface ThinkingWireProfile {
+  version: 1
+  thinkingType: ThinkingTypeMode
+  effort: EffortMode
+  timestamp: number
+}
+```
+
+`applyThinkingToChatBody(body, spec, profile)`：
+
+- `effort === "reasoning_effort"`：写 `reasoning_effort`（现有 `toWireEffort` 结果）；`omit` 则删除该键
+- `thinkingType === "omit"`：删除 `thinking`
+- 否则写 `thinking.type`：开思考时 `enabled` 或 `adaptive`，关思考时 `disabled`
+
+`ThinkingRequestBody` 仍表示用户意图（`reasoningEffort` + `thinkingEnabled`），不把 profile 放进 ALS。fetch 时用请求 URL 的 host 和 body 里的 `model` 解析 profile。
+
+缓存键：`${hostname.toLowerCase()}::${modelId.toLowerCase()}`。hostname 从请求 URL 取；取不到则只用 `modelId`。
+
+---
+
+## 2. 启发式
+
+在学习缓存未命中时：
+
+1. `modelId` 或 hostname 包含 `minimax` → `{ thinkingType: "adaptive-disabled", effort: "reasoning_effort" }`
+2. 当前 provider `type === "openai"` → `{ thinkingType: "omit", effort: "reasoning_effort" }`
+3. 否则 → `{ thinkingType: "enabled-disabled", effort: "reasoning_effort" }`
+
+启发式结果不写磁盘。只有 400 学到的 profile 才持久化，以便覆盖错误启发式。
+
+`toWireEffort` 规则不变：`off` → `none`；`max` 仍按目录/`openai` 映射 `xhigh`。
+
+---
+
+## 3. 400 探测
+
+仅处理 chat completions 的 JSON body 请求。流程：
+
+1. 按当前 profile 注入后 `fetch`
+2. 若 `response.ok` 或状态不是 400：原样返回（仍走现有 `foldReasoningInChatResponse`）
+3. 读 400 body（`text()`）。用纯函数 `parseThinkingWireHint(text)` 得到对 profile 的补丁
+4. 补丁相对当前 profile **有变化** 才更新内存+磁盘，用新 profile 重写 body，**重试一次**
+5. 第二次无论成败都不再为思考字段重试；失败则把第二次响应交给 SDK（若第二次未发出，把第一次 400 用已读文本重建 `Response`）
+
+`parseThinkingWireHint` 识别：
+
+| 错误文本形态 | 补丁 |
+|--------------|------|
+| `thinking.type` 且 `allowed` 列表含 `adaptive` 与 `disabled` | `thinkingType: "adaptive-disabled"` |
+| `thinking.type` 且 `allowed` 含 `enabled` 与 `disabled` | `thinkingType: "enabled-disabled"` |
+| `Unknown parameter` / `unknown parameter` 指向 `thinking` | `thinkingType: "omit"` |
+| 同上指向 `reasoning_effort` | `effort: "omit"` |
+
+列表解析忽略大小写与空白。无法识别或补丁无变化 → 不重试。
+
+并发：两个请求可能同时 400 再各写一次缓存，可接受，不引入锁。内存 Map + 磁盘与 `model-catalog` 相同模式。TTL 7 天；过期条目当未命中，可再次学习。`version !== 1` 的条目忽略。
+
+---
+
+## 4. 错误与界面
+
+重试对用户不可见：没有「改参」「adaptive」提示。两次都失败时沿用现有 `AI_APICallError` 展示。
+
+`/think`、状态栏「思考 high」、HTTP `GET/POST /v1/thinking` 的字段与文案不变。
+
+---
+
+## 5. 文档与测试
+
+同步：
+
+- `skills/self-config/SKILL.md`：请求按模型/网关映射 `thinking` / `reasoning_effort`，并提及学习缓存文件；不写探测实现细节
+- `skills/self-config/reference.md`：环境变量表旁可注明缓存文件名（若该文件已列目录缓存）
+- `docs/API.md`：用户可见 thinking 枚举不变；不必描述 wire 字段
+- `README.md`：不增加线协议说明
+- `/help`：不改
+
+测试（纯函数 + fetch 包装）：
+
+- `applyThinkingToChatBody` 三种 `thinkingType` × 开/关、`effort` omit
+- 启发式：minimax 模型名、minimax host、openai type、默认
+- `parseThinkingWireHint`：本次 MiniMax 原文、unknown parameter、无法识别
+- fetch：400 可解析 → 第二次请求 body 已改且只发两次；不可解析 → 只发一次
+- 缓存读写、过期、version 不匹配
+
+实现落点：`src/thinking.ts` 扩展拼 body 与 hint 解析；新建 `src/thinking-wire.ts`（profile 解析、启发式、缓存）以免 `thinking.ts` 再膨胀；`src/provider.ts` 的 `modelFetch` 接 400 重试。测试放 `tests/thinking.test.ts` 与 `tests/thinking-wire.test.ts`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "min-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",

package/skills/self-config/SKILL.md

@@ -2,7 +2,7 @@
 name: self-config
 description: >
   Configures min-agent itself: providers, MCP servers, skills, rules, memory,
-  permission, sandbox, plugins, and files under ~/.min-agent/ and .min-agent/.
+  permission, sandbox, thinking intensity, plugins, and files under ~/.min-agent/ and .min-agent/.
   Use when the user asks to install, enable, disable, or change min-agent settings.
 always-load: true
 version: 1.0.0
@@ -28,7 +28,7 @@ Config files are **strict JSON** (no comments). Read the file before editing. Pr
 | Goal | File | Notes |
 |------|------|--------|
 | Providers, keys, search backends, pricing, extra instruction paths, global skill disables | `~/.min-agent/config.json` | Keys only here |
-| Project skill toggles; overlay `activeProvider` / `defaultModel` / `sampling` / `budget` / `permission` / `sandbox` / `compaction` / `agent` | `.min-agent/config.json` | Overlay is field-by-field; `sampling`/`budget`/`sandbox`/`compaction`/`agent` merge keys |
+| Project skill toggles; overlay `activeProvider` / `defaultModel` / `sampling` / `budget` / `permission` / `thinking` / `memory` / `sandbox` / `compaction` / `agent` | `.min-agent/config.json` | Overlay is field-by-field; `sampling`/`budget`/`sandbox`/`compaction`/`agent` merge keys |
 | MCP servers | `~/.min-agent/mcp.json` or `.min-agent/mcp.json` | Merge by server **name**; project replaces the same name |
 | Memories | `memory.json` in the same dirs | Prefer `memory_save` / `memory_search` tools over editing the file |
 | Global rules | `~/.min-agent/rules.md` | Always loaded |
@@ -76,11 +76,12 @@ Instructions...
 
 `description` may be a YAML `|` / `>` block. Optional: `version`, `allowed-tools`, `always-load`, `metadata.requires.bins`. Do not disable `self-config` unless the user explicitly asks.
 
-## Rules, memory, permission, sandbox
+## Rules, memory, permission, sandbox, thinking
 
 - Rules: edit the files in the table above. `/reload` reloads rules only, not MCP.
-- Memory: use memory tools. Default save scope is project when `.min-agent/` exists. Shape: `{ "content": string, "tags": string[], "created": ISO string }` array.
+- Memory: **off** by default. Config `memory` is `on` | `off` (`true`/`enable` → on, `false`/`disable` → off). Project overlays global; writing `memory` globally also removes a project `memory` overlay. When off, memories are not injected and `memory_save` / `memory_search` / `memory_delete` are not registered (takes effect next turn after you change the file). CLI `min-agent memory on|off` / `--memory` follow the same write-vs-this-run rule as permission. `/memory on|off` writes **global** by default (and clears a project overlay); `/memory --project` writes only the project file. `/memory` lists the switch plus stored entries; `/memory <text>` still writes `memory.json` even when off. Default save scope is project when `.min-agent/` exists. Shape: `{ "content": string, "tags": string[], "created": ISO string }` array. When on, memories are injected each turn as background reference, not as work to resume. Do not store secrets or API keys. HTTP: `GET/POST /v1/memory/mode`, chat body `memory`, and `GET /v1/memory` include `memory` / `source` / `label`.
 - Permission: `ask` (default) | `accept-edits` | `allow-all` in config `permission`. CLI `min-agent permission …` / `--permission` without a message writes config and exits; with a message it is this session only. `--yes` is this session only and does not write config.
+- Thinking intensity: `off` | `low` | `medium` | `high` | `max` in config `thinking`. Omit the field to use **medium**, then clamp to levels the current model actually exposes (from the model catalog). `/think` opens an interactive picker of those English levels and writes **global** config; that also clears a project `thinking` overlay so a leftover project `off` cannot hide the new value after restart. `/think --project` writes only the project file. Typed `/think off|low|medium|high|max` still works when the model supports that value. `min-agent think …` / `--think` follow the same write-vs-this-run rule as permission. `xhigh` / `extra-high` / `none` are accepted as aliases (`xhigh` → `max`, `none` → `off`). Each request maps that intensity onto the current model and gateway (MiniMax uses `adaptive`/`disabled`; official OpenAI omits `thinking` and maps `max` to `xhigh`). Learned mappings are cached in `~/.min-agent/thinking-wire-cache.json` for 7 days. Per-model context window and supported effort values are loaded from the model catalog (`https://models.lonae.com`, override with `MIN_AGENT_MODELS_API_URL`) and cached in `~/.min-agent/model-catalog-cache.json` for 7 days after a successful lookup. When the provider host is unknown, effort levels are the majority across offerings that actually list efforts (toggle-only rows do not vote), so a single gateway cannot invent `medium`.
 - Sandbox default is **off**. `mode`: `off` | `workspace` | `strict`. Optional `network`, `extraWriteRoots`, `extraReadRoots`. Isolation is independent of permission. `--sandbox` / `--network` without a message write config and exit.
 
 ## Providers

package/skills/self-config/reference.md

@@ -24,6 +24,8 @@ Read this when you need exact keys. Files are strict JSON.
   "instructions": ["./docs/rules.md"],
   "disabledSkills": [],
   "permission": "ask",
+  "thinking": "max",
+  "memory": "on",
   "sandbox": {
     "mode": "off",
     "network": "allow",
@@ -54,6 +56,8 @@ Read this when you need exact keys. Files are strict JSON.
 }
 ```
 
+- `thinking`: `off` | `low` | `medium` | `high` | `max`; omit to use medium. A project `thinking` value overlays global; writing thinking globally removes the project overlay so the chosen level is what later sessions use. `/think --project` writes only the project file.
+- `memory`: `on` | `off`; omit to keep **off**. When off, stored `memory.json` entries are not injected and memory tools are unavailable. A project `memory` value overlays global; writing memory globally removes the project overlay. `/memory --project` writes only the project file.
 - `contextWindow`: tokens; omit to query the API, then 512k fallback.
 - `agent.autoContinue` omitted → uses `compaction.autoContinue` (default true).
 - `agent.maxSteps` omitted → no tool-step ceiling.
@@ -71,9 +75,9 @@ Read this when you need exact keys. Files are strict JSON.
 
 Allowed keys (no `providers`, no API keys, no search secrets):
 
-`disabledSkills`, `enabledSkills`, `activeProvider`, `defaultModel`, `sampling`, `budget`, `permission`, `sandbox`, `compaction`, `agent`.
+`disabledSkills`, `enabledSkills`, `activeProvider`, `defaultModel`, `sampling`, `budget`, `permission`, `thinking`, `memory`, `sandbox`, `compaction`, `agent`.
 
-Present keys overlay the global file. Nested objects `sampling` / `budget` / `sandbox` / `compaction` / `agent` merge per field. `defaultModel` overrides the active provider's model without copying keys.
+Present keys overlay the global file. Nested objects `sampling` / `budget` / `sandbox` / `compaction` / `agent` merge per field. `defaultModel` overrides the active provider's model without copying keys. Writing `thinking` or `memory` to global config also removes the matching project overlay.
 
 ## `mcp.json`
 
@@ -127,16 +131,17 @@ Default: confirm before run. `readOnly: true` or `dangerous: false` skips confir
 
 ## Memory `memory.json`
 
-Array of `{ "content": string, "tags": string[], "created": string }`. Prefer memory tools.
+Array of `{ "content": string, "tags": string[], "created": string }`. Prefer memory tools when `memory` is `on`. Injected as background reference each turn only when enabled, not as pending work. Do not store secrets or API keys. The enable switch lives in config (`memory`), not in this file.
 
 ## Environment overrides
 
 | Variable | Role |
 |----------|------|
-| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` |
+| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` (includes `model-catalog-cache.json`, `thinking-wire-cache.json`) |
 | `MIN_AGENT_SKILLS_DIRS` | Replaces user skill roots (path-delimiter separated) |
 | `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` / `true` skips packaged skills |
 | `MIN_AGENT_SANDBOX` / `MIN_AGENT_SANDBOX_NETWORK` | Isolation |
+| `MIN_AGENT_MODELS_API_URL` | Model catalog base (default `https://models.lonae.com`) |
 | `MIN_AGENT_SERPER_API_KEY` | Overrides `serperApiKey` |
 | `MIN_AGENT_SEARXNG_URL` | Overrides `webSearchURL` (SearXNG instead of Serper) |
 | `MIN_AGENT_SEARXNG_FALLBACK_ENGINES` | Default `google,bing`; empty string disables retry |
@@ -146,4 +151,4 @@ Array of `{ "content": string, "tags": string[], "created": string }`. Prefer me
 
 ## HTTP (only if the user is running `min-agent serve`)
 
-Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.
+Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Thinking: `GET/POST /v1/thinking`. Memory switch: `GET/POST /v1/memory/mode`. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.