minimal-agent 0.10.0 → 0.12.0

package/src/config/numericLimits.ts

@@ -0,0 +1,80 @@
+/**
+ * 配置里每一个「数字输入」的边界与取值语义——**唯一真值**。
+ *
+ * 为什么要有这个文件（真实事故）：同一个数字此前在**三层各写一份**互不相同的边界——
+ * 前端 input 的 `min/max/step`、写入时 `applyConfigPatch` 的 clamp、读回时
+ * `parseAdvisor/parseSubagents` 的 `boundedNumber`。三份一旦不一致，用户在设置页输入
+ * 一个「前端允许、后端不允许」的值，回车/失焦后会**静默变回原值**：前端没报错（它认为
+ * 合法），后端也没报错（它认为自己只是在纠偏），中间没有任何提示。顾问「输入预算」被
+ * 死钉在 128000 就是这么来的——用户的顾问模型是 90 万上下文窗口，却怎么改都跳回 12.8 万。
+ *
+ * 因此：**边界只准在这里声明**，minimal-agent 的读/写两层与 minimal-desktop 的设置页
+ * 全部 import 这里。前端 clamp 后再提交，后端再 clamp 一次兜底——两次 clamp 结果必然
+ * 相同，用户看到的值就是存下来的值。
+ *
+ * 单位约定：这里的边界一律用**存储单位**（毫秒 / 比例 / 绝对个数）。UI 若按秒/分钟/
+ * 百分比展示，自己换算（见 minimal-desktop `NumberInput`），不在这里再开一份显示单位的
+ * 边界，否则又回到多份真值。
+ */
+
+/** 一个数字字段的取值边界。`step` 只影响 UI 的上下箭头步进，不参与合法性判断。 */
+export interface NumericLimit {
+  min: number;
+  max: number;
+  step: number;
+  /** 'integer' = 只能是整数总量（token / 毫秒 / 轮数 / 个数）；'ratio' = 比例，保留 4 位小数（= 百分比 2 位）。 */
+  kind: 'integer' | 'ratio';
+}
+
+export const CONFIG_LIMITS = {
+  /** 顾问单次咨询喂进去的输入 token 上限。上界给到 200 万是为了容纳百万级上下文模型；
+   *  真正生效值还会再被「所选顾问模型的 contextWindow」二次收窄（见 advisor.ts）。 */
+  advisorInputTokenBudget: { min: 1_000, max: 2_000_000, step: 1_000, kind: 'integer' },
+  /** 顾问单次咨询的最长等待（毫秒）。重思考模型 + 大上下文可以跑很久，上界给到 10 分钟。 */
+  advisorTimeoutMs: { min: 5_000, max: 600_000, step: 5_000, kind: 'integer' },
+
+  /** 单个回合内最多派生几个子任务。 */
+  subagentMaxCallsPerTurn: { min: 1, max: 50, step: 1, kind: 'integer' },
+  /** 子任务并发上限。 */
+  subagentMaxConcurrent: { min: 1, max: 20, step: 1, kind: 'integer' },
+  /** 单个子任务的总时长兜底（毫秒），上界 2 小时。 */
+  subagentTimeoutMs: { min: 60_000, max: 7_200_000, step: 60_000, kind: 'integer' },
+  /** explore（只读调研）子任务的轮数上限。 */
+  subagentExploreMaxTurns: { min: 5, max: 500, step: 5, kind: 'integer' },
+  /** general（读写执行）子任务的轮数上限。 */
+  subagentGeneralMaxTurns: { min: 10, max: 1_000, step: 10, kind: 'integer' },
+
+  /** 电脑操作每帧画面的像素预算。 */
+  computerUseMaxImagePixels: { min: 100_000, max: 10_000_000, step: 100_000, kind: 'integer' },
+
+  /** 自动压缩触发阈值，占 contextWindow 的比例（0,1]。UI 按百分比展示，保留 2 位小数。 */
+  compactRatio: { min: 0.01, max: 1, step: 0.01, kind: 'ratio' },
+
+  /** 模型条目的上下文窗口。 */
+  modelContextWindow: { min: 1_000, max: 20_000_000, step: 1_000, kind: 'integer' },
+  /** 模型条目的单次输出上限（可留空 = 用公式推荐值，故 UI 允许空串，这里只约束填了值的情况）。 */
+  modelMaxTokens: { min: 256, max: 1_000_000, step: 256, kind: 'integer' },
+} as const satisfies Record<string, NumericLimit>;
+
+export type ConfigLimitKey = keyof typeof CONFIG_LIMITS;
+
+/** 比例类字段保留的小数位（4 位比例 = 2 位百分比）。 */
+const RATIO_DECIMALS = 4;
+
+/**
+ * 把任意输入规整成该字段合法的存储值：非法/空 → fallback；整数类四舍五入；
+ * 比例类保留 4 位小数（否则 `0.85` 会被步进累加成 `0.8500000000000001` 存进 config.json）。
+ * 最后按 min/max 收口。
+ */
+export function normalizeLimited(value: unknown, limit: NumericLimit, fallback: number): number {
+  const raw = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  const rounded = limit.kind === 'integer'
+    ? Math.round(raw)
+    : Number(raw.toFixed(RATIO_DECIMALS));
+  return Math.min(limit.max, Math.max(limit.min, rounded));
+}
+
+/** 判断一个值是否已经落在合法范围内（UI 用来决定要不要提示「已自动调整」）。 */
+export function withinLimit(value: number, limit: NumericLimit): boolean {
+  return Number.isFinite(value) && value >= limit.min && value <= limit.max;
+}

package/src/config.ts

@@ -0,0 +1,109 @@
+/**
+ * ============================================================
+ *  config.ts —— 全局配置加载（从 .env 读取）
+ * ------------------------------------------------------------
+ *  只从环境变量读取，集中管理所有配置。
+ *
+ *  必需的环境变量：
+ *    MINIMAL_AGENT_BASE_URL   - API 完整端点地址，如 https://api.minimax.chat/v1/chat/completions
+ *    MINIMAL_AGENT_API_KEY    - API key
+ *    MINIMAL_AGENT_MODEL      - 模型名，如 MiniMax-M2.7
+ *
+ *  可选的环境变量：
+ *    MINIMAL_AGENT_PROVIDER   - 友好名称，默认 "env"
+ *    MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口，默认 128000
+ *    MINIMAL_AGENT_MAX_TOKENS - 单次输出 token 上限，默认 16384（弱 provider 默认偏小会截断长输出）
+ * ============================================================
+ */
+
+import { configService } from './config/configService.js';
+import type { Provider } from './types.js';
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+
+/**
+ * 单次输出 token 上限的默认值。
+ *
+ * 16384：实测火山豆包接受、足够一次性写完整篇 PLAN.md（实测 ~6.5k token），又远低于
+ * 豆包 131072 的宽容上限。不发 max_tokens 的话豆包默认仅 4096，长输出会被硬截断。
+ * 个别 provider 若拒绝该值，client 会自动去掉 max_tokens 重发降级。
+ */
+const DEFAULT_MAX_TOKENS = 16_384;
+
+/** 解析正整数环境变量（NaN/≤0 → undefined，由调用方决定默认值）。 */
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = parseInt(raw, 10);
+  return !Number.isNaN(n) && n > 0 ? n : undefined;
+}
+
+/**
+ * 解析压缩阈值比例（0~1 小数）。
+ * 非法值（NaN、0、负数、>1）返回 undefined，由调用方决定是否用默认值 0.85。
+ */
+function parseCompactRatio(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = parseFloat(raw);
+  if (Number.isNaN(n) || n <= 0 || n > 1) return undefined;
+  return n;
+}
+
+/**
+ * 加载 Provider 配置（从环境变量）。
+ * 缺少必需变量时抛出明确错误。
+ */
+export async function loadProvider(): Promise<Provider> {
+  const baseURL = process.env.MINIMAL_AGENT_BASE_URL;
+  const apiKey = process.env.MINIMAL_AGENT_API_KEY;
+  const model = process.env.MINIMAL_AGENT_MODEL;
+
+  if (!baseURL || !apiKey || !model) {
+    const missing = [];
+    if (!baseURL) missing.push('MINIMAL_AGENT_BASE_URL');
+    if (!apiKey) missing.push('MINIMAL_AGENT_API_KEY');
+    if (!model) missing.push('MINIMAL_AGENT_MODEL');
+
+    throw new Error(
+      `缺少必需的环境变量：${missing.join(', ')}\n\n` +
+        `请在 .env 中配置：\n` +
+        `  MINIMAL_AGENT_BASE_URL=https://api.example.com/v1\n` +
+        `  MINIMAL_AGENT_API_KEY=your-api-key\n` +
+        `  MINIMAL_AGENT_MODEL=your-model\n\n` +
+        `参考 .env.example`,
+    );
+  }
+
+  const contextWindowRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
+  let contextWindow = DEFAULT_CONTEXT_WINDOW;
+  if (contextWindowRaw) {
+    const n = parseInt(contextWindowRaw, 10);
+    if (!Number.isNaN(n) && n > 0) {
+      contextWindow = n;
+    }
+  }
+
+  const compactRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
+
+  const maxTokens =
+    parsePositiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS) ?? DEFAULT_MAX_TOKENS;
+
+  return {
+    name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
+    baseURL,
+    apiKey,
+    model,
+    contextWindow,
+    maxTokens,
+    ...(compactRatio !== undefined ? { compactRatio } : {}),
+  };
+}
+
+/** Shared CLI/Desktop configuration: JSON first, environment only as bootstrap or env mode. */
+export async function loadProviderLayered(): Promise<Provider | null> {
+  return configService.provider();
+}
+
+/** @deprecated Compatibility hook. Trusted tools now read ConfigService directly. */
+export async function applyToolKeysToEnv(): Promise<void> {
+  await configService.reload();
+}

package/src/context/agentHome.ts

@@ -0,0 +1,11 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** 测试和嵌入宿主可覆盖 home 根，生产默认使用系统主目录。 */
+export function agentHomeBase(): string {
+  return process.env.MINIMAL_AGENT_HOME || homedir();
+}
+
+export function agentStateDir(): string {
+  return join(agentHomeBase(), '.minimal-agent');
+}

package/src/context/archive.ts

@@ -0,0 +1,144 @@
+/**
+ * ============================================================
+ *  src/context/archive.ts —— /new 自动归档历史对话
+ * ------------------------------------------------------------
+ *  做的事：
+ *    `/new` 清空上下文前，先把当前对话历史落盘到 archive 目录，
+ *    供后续 `/list-archive`、`/restore <id>` 查看 / 找回。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/archive/<cwd-hash>/<ISO-timestamp>.json
+ *    - cwd-hash：当前工作目录 sha1 前 12 位（避免不同项目 archive 串台）
+ *    - timestamp：new Date().toISOString().replace(/:/g, '-')（Windows 不允许冒号）
+ *
+ *  存储格式：
+ *    { updatedAt: number; messages: Message[] }
+ *
+ *  抉择：
+ *    - 仅含 system 消息（空对话）跳过写入，返回空字符串
+ *    - 失败由调用方 try/catch 吞掉，本模块不做 stderr（保持纯函数语义）
+ *    - 损坏文件在 listArchives 中静默 skip
+ *    - 通过 MINIMAL_AGENT_HOME 环境变量让测试切到临时目录，避免污染真实 ~/.minimal-agent
+ * ============================================================
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { contentToPlainText } from '../multimodal.js';
+import type { Message } from '../types.js';
+
+/** 一条归档摘要，列表展示用 */
+export interface ArchiveEntry {
+  /** archive id（ISO timestamp 字符串，冒号已替换为 - 以兼容 Windows） */
+  id: string;
+  /** 文件 mtime（unix millis），用于排序 */
+  updatedAt: number;
+  /** messages 数量（含 system） */
+  msgCount: number;
+  /** 首条 user message 前 80 字符（换行 / 多空白合并为单空格） */
+  firstUserPreview: string;
+}
+
+/** 解析 archive 根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome(): string {
+  return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+
+function archiveDir(cwd: string): string {
+  const hash = createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+  return join(agentHome(), '.minimal-agent', 'archive', hash);
+}
+
+/**
+ * 归档当前 messages 到 archive 目录。
+ *
+ * @returns archive id（成功）或空字符串（无内容跳过）
+ *
+ * 行为：
+ *  - messages 为空 / 仅含 system role → 跳过，返回 ''
+ *  - 写入失败抛错（调用方负责吞）
+ */
+export async function archiveCurrent(messages: Message[]): Promise<string> {
+  const nonSystem = messages.filter((m) => m.role !== 'system');
+  if (nonSystem.length === 0) return '';
+
+  const dir = archiveDir(getWorkingDir());
+  await mkdir(dir, { recursive: true });
+
+  const id = new Date().toISOString().replace(/:/g, '-');
+  const path = join(dir, `${id}.json`);
+  // 写入完整 messages（含 system）—— restoreArchive 期待原样还原以做 roundtrip
+  // 跳过判定单独用 nonSystem（空对话不归档）—— 这是有意分层的：
+  //   skip 判定 = "有没有用户/助手消息可归档"
+  //   write 内容 = "保留完整上下文供 /restore 还原"
+  await writeFile(
+    path,
+    JSON.stringify({ updatedAt: Date.now(), messages }),
+    'utf8',
+  );
+  return id;
+}
+
+/**
+ * 列出当前 cwd 下所有归档，最新优先（按文件 mtime 倒序）。
+ *
+ * 损坏 / 无法解析的文件会被静默跳过——不影响其它条目展示。
+ * 目录不存在视作空列表。
+ */
+export async function listArchives(): Promise<ArchiveEntry[]> {
+  const dir = archiveDir(getWorkingDir());
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const entries: ArchiveEntry[] = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const id = name.slice(0, -'.json'.length);
+    const fpath = join(dir, name);
+    try {
+      const st = await stat(fpath);
+      const raw = await readFile(fpath, 'utf8');
+      const data = JSON.parse(raw) as { messages: Message[] };
+      if (!Array.isArray(data.messages)) continue;
+      const firstUser = data.messages.find((m) => m.role === 'user');
+      const preview =
+        firstUser
+          ? contentToPlainText(firstUser.content).replace(/\s+/g, ' ').slice(0, 80)
+          : '';
+      entries.push({
+        id,
+        updatedAt: st.mtimeMs,
+        msgCount: data.messages.length,
+        firstUserPreview: preview,
+      });
+    } catch {
+      // 损坏文件静默 skip
+    }
+  }
+  return entries.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/**
+ * 按 id 恢复归档。
+ *
+ * @returns messages 数组（成功）；找不到 / 损坏 / messages 非数组 → null
+ */
+export async function restoreArchive(id: string): Promise<Message[] | null> {
+  const dir = archiveDir(getWorkingDir());
+  const path = join(dir, `${id}.json`);
+  try {
+    const raw = await readFile(path, 'utf8');
+    const data = JSON.parse(raw) as { messages: Message[] };
+    return Array.isArray(data.messages) ? data.messages : null;
+  } catch {
+    return null;
+  }
+}

package/src/context/budgetPlan.js

@@ -0,0 +1,54 @@
+import { getCompactThreshold } from './compact.js';
+import { countMessagesTokens, countTextTokens, estimateToolsTokens } from './tokenCounter.js';
+import { budgetClassForToolName } from '../tools/capabilities.js';
+export function buildContextBudgetPlan(input) {
+    const inputLimit = getCompactThreshold(input.provider);
+    const historyTokens = countMessagesTokens(input.history);
+    const toolTokens = estimateToolsTokens(input.tools);
+    const transientTokens = countTextTokens(input.transientContext ?? '');
+    const multimodalTokens = input.multimodalTokens ?? 0;
+    const totalInputTokens = historyTokens + toolTokens + transientTokens + multimodalTokens;
+    return {
+        contextWindow: input.provider.contextWindow,
+        inputLimit,
+        reservedOutput: Math.max(0, input.provider.contextWindow - inputLimit),
+        historyTokens,
+        toolTokens,
+        transientTokens,
+        multimodalTokens,
+        totalInputTokens,
+        overBudget: totalInputTokens > inputLimit,
+    };
+}
+const AUXILIARY_REMOVAL_ORDER = ['Advisor', 'Agent'];
+/**
+ * Last-resort schema reduction. Normal requests keep the full catalog; this is
+ * used only after history compaction still cannot fit the provider window.
+ */
+export function fitToolsForEmergency(input) {
+    let tools = [...input.tools];
+    let plan = buildContextBudgetPlan({ ...input, tools });
+    if (!plan.overBudget)
+        return { tools, removedNames: [], plan };
+    const required = input.requiredNames ?? new Set();
+    const auxiliaryRank = new Map(AUXILIARY_REMOVAL_ORDER.map((name, index) => [name, index]));
+    const candidates = tools
+        .filter((tool) => !required.has(tool.name) && budgetClassForToolName(tool.name) === 'auxiliary')
+        .sort((a, b) => {
+        const rankA = auxiliaryRank.get(a.name);
+        const rankB = auxiliaryRank.get(b.name);
+        if (rankA !== undefined || rankB !== undefined) {
+            return (rankA ?? Number.MAX_SAFE_INTEGER) - (rankB ?? Number.MAX_SAFE_INTEGER);
+        }
+        return estimateToolsTokens([b]) - estimateToolsTokens([a]);
+    });
+    const removedNames = [];
+    for (const candidate of candidates) {
+        if (!plan.overBudget || tools.length <= 1)
+            break;
+        tools = tools.filter((tool) => tool.name !== candidate.name);
+        removedNames.push(candidate.name);
+        plan = buildContextBudgetPlan({ ...input, tools });
+    }
+    return { tools, removedNames, plan };
+}

package/src/context/budgetPlan.ts

@@ -0,0 +1,88 @@
+import type { Message, Provider, Tool } from '../types.js';
+import { getCompactThreshold } from './compact.js';
+import { countMessagesTokens, countTextTokens, estimateToolsTokens } from './tokenCounter.js';
+import { budgetClassForToolName } from '../tools/capabilities.js';
+
+export interface ContextBudgetPlan {
+  contextWindow: number;
+  inputLimit: number;
+  reservedOutput: number;
+  historyTokens: number;
+  toolTokens: number;
+  transientTokens: number;
+  multimodalTokens: number;
+  totalInputTokens: number;
+  overBudget: boolean;
+}
+
+export function buildContextBudgetPlan(input: {
+  provider: Provider;
+  history: readonly Message[];
+  tools: readonly Tool[];
+  transientContext?: string;
+  multimodalTokens?: number;
+}): ContextBudgetPlan {
+  const inputLimit = getCompactThreshold(input.provider);
+  const historyTokens = countMessagesTokens(input.history as Message[]);
+  const toolTokens = estimateToolsTokens(input.tools as Tool[]);
+  const transientTokens = countTextTokens(input.transientContext ?? '');
+  const multimodalTokens = input.multimodalTokens ?? 0;
+  const totalInputTokens = historyTokens + toolTokens + transientTokens + multimodalTokens;
+  return {
+    contextWindow: input.provider.contextWindow,
+    inputLimit,
+    reservedOutput: Math.max(0, input.provider.contextWindow - inputLimit),
+    historyTokens,
+    toolTokens,
+    transientTokens,
+    multimodalTokens,
+    totalInputTokens,
+    overBudget: totalInputTokens > inputLimit,
+  };
+}
+
+export interface EmergencyToolFit {
+  tools: Tool[];
+  removedNames: string[];
+  plan: ContextBudgetPlan;
+}
+
+const AUXILIARY_REMOVAL_ORDER = ['Advisor', 'Agent'];
+
+/**
+ * Last-resort schema reduction. Normal requests keep the full catalog; this is
+ * used only after history compaction still cannot fit the provider window.
+ */
+export function fitToolsForEmergency(input: {
+  provider: Provider;
+  history: readonly Message[];
+  tools: readonly Tool[];
+  transientContext?: string;
+  multimodalTokens?: number;
+  requiredNames?: ReadonlySet<string>;
+}): EmergencyToolFit {
+  let tools = [...input.tools];
+  let plan = buildContextBudgetPlan({ ...input, tools });
+  if (!plan.overBudget) return { tools, removedNames: [], plan };
+
+  const required = input.requiredNames ?? new Set<string>();
+  const auxiliaryRank = new Map(AUXILIARY_REMOVAL_ORDER.map((name, index) => [name, index]));
+  const candidates = tools
+    .filter((tool) => !required.has(tool.name) && budgetClassForToolName(tool.name) === 'auxiliary')
+    .sort((a, b) => {
+      const rankA = auxiliaryRank.get(a.name);
+      const rankB = auxiliaryRank.get(b.name);
+      if (rankA !== undefined || rankB !== undefined) {
+        return (rankA ?? Number.MAX_SAFE_INTEGER) - (rankB ?? Number.MAX_SAFE_INTEGER);
+      }
+      return estimateToolsTokens([b]) - estimateToolsTokens([a]);
+    });
+  const removedNames: string[] = [];
+  for (const candidate of candidates) {
+    if (!plan.overBudget || tools.length <= 1) break;
+    tools = tools.filter((tool) => tool.name !== candidate.name);
+    removedNames.push(candidate.name);
+    plan = buildContextBudgetPlan({ ...input, tools });
+  }
+  return { tools, removedNames, plan };
+}