min-agent 0.5.0 → 0.6.0

package/docs/superpowers/specs/2026-08-23-input-paste-attachments-design.md

@@ -1,174 +0,0 @@
-# 输入框粘贴图片与文本片段设计
-
-日期: 2026-08-23
-状态: 已批准（方案 1：输入框内原子标记）
-
-## 问题
-
-交互会话的输入框不能把剪贴板图片挂到当前草稿：贴图只能 `/paste`（立刻发送）或 `/attach <路径>`。多行文本粘贴会整段铺进输入框，末尾换行还可能被当成 Enter 误发送。
-
-## 目标
-
-1. 剪贴板图片用 Ctrl+V 插到光标处，显示为 `[图片 #N]`，写完说明再 Enter 发送
-2. 一次粘贴只要超过一行，收成 `[粘贴 #N · X 行]`，发送时带上全文
-3. 单行粘贴仍直接插入
-4. 标记在输入框里是原子块：左右移、退格、Delete、点击都不拆开
-5. 只有附件、没打字也可以发送
-
-## 不做
-
-- 不改 HTTP `/v1/paste`，不新增配置项，不改 `skills/self-config`
-- 不把 Cmd+V 从终端抢过来（macOS 贴图用 Ctrl+V）
-- 不把附件正文写入 `input-history.json`
-- 不做拖拽文件进终端、不做输入框内 Shift 选区
-- `/paste [t]` 仍是立刻发送剪贴板图片，不改成挂草稿
-
-## 设计决策
-
-| 决策 | 结论 |
-|------|------|
-| 呈现 | 草稿字符串里每个附件一个私有区码点；屏幕上画成标记 |
-| 文本门槛 | 规范化后仍含换行 → 片段；否则当普通字插入 |
-| 贴图快捷键 | Ctrl+V 读系统剪贴板；无图时静默 |
-| `/paste` | 保持立刻发送 |
-| 斜杠命令 | `display` 去空白后以 `/` 开头则走现有命令处理，附件不进入对话 |
-| 历史 | 只存展开后的短标记字面量，不存图片/长文；翻历史不会恢复附件 |
-
----
-
-## 1. 数据模型
-
-`InputBar` 继续用 `{ value, caretIndex }`。`caretIndex` 仍是 `Array.from(value)` 的码点下标。
-
-每个附件占用 **一个** Unicode 私有区码点，从 `U+E000` 起按插入顺序分配，本条草稿内不复用。旁路表：
-
-```ts
-type DraftAttachment =
-  | { kind: "image"; id: number; data: Buffer; mimeType: string }
-  | { kind: "snippet"; id: number; text: string; lineCount: number }
-```
-
-`id` 按类型分开从 1 递增：`[图片 #1]` 与 `[粘贴 #1 · 3 行]` 可以同时存在。
-
-屏幕标记（用户可见，无实现细节）：
-
-- 图片：`[图片 #${id}]`
-- 片段：`[粘贴 #${id} · ${lineCount} 行]`
-
-未在旁路表中的私有区字符按宽 1 的 `�` 绘制，不当附件。
-
-每次编辑后扫描 `value`：旁路表里码点已不在 `value` 中的条目删除（退格、Ctrl+U/K/W、Ctrl+C 清空都走这条）。Ctrl+C 清空或提交成功后：`value` 清空，旁路表清空，两个计数器回到 1。
-
-折行与点击：该码点是一个 cluster，显示宽度为 `min(displayWidth(标记), 输入区宽度)`。过宽时单独占一行，绘制时末尾用 `…` 截断；点击该行任一单元格都落在这一个码点上。硬件光标列用展开后的显示宽度计算，与现有 IME 锚点一致。
-
----
-
-## 2. 文本粘贴
-
-挂载输入框时打开 bracketed paste（`CSI ? 2004 h`），卸载时关闭（`CSI ? 2004 l`），与现有鼠标协议一起写 stdout。
-
-在 InputBar 已有的 raw stdin 监听里拼包：`ESC[200~` 起、`ESC[201~` 止。包收齐前 `useInput` 丢掉这段输入（含 Ink 剥掉 ESC 后的 `[200~` / `[201~` 碎片），避免插两遍，也避免粘贴里的换行走现有「末尾 `\r`/`\n` 当 Enter」逻辑。
-
-粘贴正文处理（纯函数，可单测）：
-
-1. `\r\n` 与 `\r` 全部变成 `\n`
-2. 去掉**末尾一个** `\n`（编辑器复制常带）
-3. 若仍含 `\n`：分配片段码点，插入光标处，`lineCount = text.split("\n").length`
-4. 否则：当普通文本插入（与打字相同）
-
-片段正文上限 **1_000_000** 个 UTF-16 码元。超过则不插入，系统提示 `粘贴内容过大，未附加`。
-
-单行过长仍插入，不收成片段。
-
----
-
-## 3. 图片粘贴
-
-`useInput` 在现有 `Ctrl+B` 之后、吞掉其它 Ctrl 组合之前处理 `key.ctrl && input === "v"`：调用已有 `getClipboardImage()`。
-
-- 有图且 `data.length <=` 现有 `MAX_IMAGE_BYTES`（5MB）：插入图片码点，MIME 用剪贴板返回值
-- 有图但超过 5MB：提示 `图片超过 5MB，未附加`，不插入
-- 无图：静默返回（不提示），避免想贴字时误按 Ctrl+V 刷警告
-
-Mac 上 Cmd+V 仍由终端注入文字。README 与 `/help` 写明贴图用 Ctrl+V。
-
----
-
-## 4. 编辑
-
-因为每个标记是一个码点，现有 `moveCaretHorizontal` / `backspaceAt` / `deleteAt` 已整块移动或删除。`Ctrl+W` / `Ctrl+K` / `Ctrl+U` 按现有「删一段字符串」处理，事后扫描丢掉孤儿附件。
-
-点击：先按展开后的显示列命中 cluster，再映射回 `value` 码点下标；点在标记上时 caret 落在该码点前（与现在点在某字前一致），再按右键一次跳过整块。
-
-Enter：`display` 去空白后非空，**或**旁路表非空，即可发送。发送后清空草稿与表。
-
----
-
-## 5. 提交与展示
-
-`onSubmit` 改为接收一次提交的结构化结果：
-
-```ts
-type SubmittedPrompt = {
-  display: string
-  content: string | Array<{ type: "text"; text: string } | { type: "image"; image: Buffer; mimeType: string }>
-}
-```
-
-`display`：把 `value` 里的附件码点换成标记文案，用于对话区用户气泡和输入历史。
-
-`content` 按 `value` 从左到右展开：
-
-- 连续普通字合成一个 `text` part
-- 片段换成一个 `text` part，正文前后各单独一行分隔：`--- 粘贴 #${id} ---`
-- 图片一个 `image` part（`Buffer` + `mimeType`）
-
-若没有任何图片 part，`content` 收成单个字符串（与现在 `messages.push({ content: text })` 兼容）。有图片则为数组。
-
-`tui-chat`：`addMessage` 用 `display`；`messages.push({ role: "user", content })` 用 `content`。`lastUserMessage` 存 `display`。
-
-`display` 去空白后以 `/` 开头：原样交给现有 `handleSlashCommand`，旁路表丢弃、不写入 `messages`（避免 `/help` 误带一张图）。否则按上面的 `content` 入列。
-
-超限提示不进输入框正文：`InputBar` 增加 `onNotice(text: string)`，`tui-chat` 接到现有系统消息通道（与 `/paste` 失败提示同一处）。
-
-输入历史：`pushInput` 写入 `display`（短标记，无二进制、无片段全文）。从历史上召回的标记是普通字符，旁路表为空。
-
----
-
-## 6. 文件与同步
-
-| 文件 | 改动 |
-|------|------|
-| `src/tui/paste-draft.ts`（新） | 规范化粘贴、单行/多行判定、码点分配、展开 `display`/`content`、孤儿回收；无 React |
-| `src/tui/bracketed-paste.ts`（新） | 从 stdin 块里扫描 bracketed paste 包 |
-| `src/tui/caret-pos.ts` / `text-width.ts` | cluster 宽度可注入「此码点显示宽」；`visualRows` / 点击换算认识附件宽 |
-| `src/tui/InputBar.tsx` | 打开/关闭 bracketed paste、粘贴包、Ctrl+V、旁路表、`onNotice`、按新规则提交 |
-| `src/tui/index.tsx` / `App.tsx` | `onSubmit` 改为 `SubmittedPrompt`；透传 `onNotice` |
-| `src/tui-chat.ts` | 按 `display`/`content` 入列；斜杠判定见上；`onNotice` 走系统消息 |
-| `src/tui/slash-handler.ts` | `/help` 快捷键增加 Ctrl+V 贴图、多行粘贴收成片段 |
-| `README.md` | 中英快捷键各补一句 |
-| `docs/API.md` | 不改（TUI 便利，协议不变） |
-
-`/paste`、`/attach`、CLI `-i` 行为不变。
-
----
-
-## 7. 测试
-
-纯函数（`tests/paste-draft.test.ts`、`tests/bracketed-paste.test.ts`，必要时扩 `tests/caret-pos.test.ts`）：
-
-- 单行；`a\nb`；`a\nb\n` 去掉末尾换行后仍是两行片段；仅 `hello\n` → 单行插入
-- 片段展开顺序：字 + 图 + 片段不错位；无图时 `content` 为字符串
-- 删除码点后旁路表回收；清空后计数从 1 再起
-- 超 1_000_000 码元拒绝；标记过宽时点击仍落在该码点
-- bracketed paste 扫描：跨 chunk、内含 `\n`/`\r`、无结束符时保持缓冲
-
-`InputBar` 不测 Ink 渲染。stdin 夹具覆盖：粘贴多行不提交；粘贴中的 `useInput` 碎片不插入。
-
-## 错误文案
-
-| 情况 | 文案 |
-|------|------|
-| 图片 > 5MB | `图片超过 5MB，未附加` |
-| 片段 > 1_000_000 码元 | `粘贴内容过大，未附加` |
-| Ctrl+V 无图 | （无文案） |

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

@@ -1,140 +0,0 @@
-# 思考线协议适配 — 设计文档
-
-**日期:** 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`。