oh-pi 0.1.0

package/pi-package/extensions/ant-colony/concurrency.ts

@@ -0,0 +1,115 @@
+/**
+ * 自适应并发控制 — 模拟蚁群的动态招募机制
+ *
+ * 真实蚁群：食物多→释放更多招募信息素→更多工蚁出巢
+ * 映射：任务多+系统空闲→提高并发；系统过载/任务少→降低并发
+ *
+ * 探索边界：启动时逐步提升并发，监测吞吐量拐点
+ */
+
+import * as os from "node:os";
+import type { ConcurrencyConfig, ConcurrencySample } from "./types.js";
+
+const CPU_CORES = os.cpus().length;
+
+export function defaultConcurrency(): ConcurrencyConfig {
+  return {
+    current: 1,
+    min: 1,
+    max: Math.min(CPU_CORES, 8),
+    optimal: 2,
+    history: [],
+  };
+}
+
+/** 采样当前系统负载 */
+export function sampleSystem(activeTasks: number, completedRecently: number, windowMinutes: number): ConcurrencySample {
+  const cpus = os.cpus();
+  const cpuLoad = cpus.reduce((sum, c) => {
+    const total = Object.values(c.times).reduce((a, b) => a + b, 0);
+    return sum + 1 - c.times.idle / total;
+  }, 0) / cpus.length;
+
+  const mem = os.freemem();
+  const throughput = windowMinutes > 0 ? completedRecently / windowMinutes : 0;
+
+  return {
+    timestamp: Date.now(),
+    concurrency: activeTasks,
+    cpuLoad,
+    memFree: mem,
+    throughput,
+  };
+}
+
+/**
+ * 自适应调节算法
+ *
+ * 阶段1 - 探索期（样本<10）：每次+1，寻找吞吐量拐点
+ * 阶段2 - 稳态期：围绕最优值微调
+ *
+ * 约束：
+ * - CPU 负载 > 85% → 减少
+ * - 可用内存 < 500MB → 减少
+ * - 吞吐量下降 → 回退到上一个最优值
+ * - 待处理任务为 0 → 降到 min
+ */
+export function adapt(config: ConcurrencyConfig, pendingTasks: number): ConcurrencyConfig {
+  const next = { ...config };
+  const samples = config.history;
+
+  // 没有待处理任务，降到最低
+  if (pendingTasks === 0) {
+    next.current = config.min;
+    return next;
+  }
+
+  // 不超过待处理任务数
+  const taskCap = Math.min(pendingTasks, config.max);
+
+  if (samples.length < 3) {
+    // 冷启动：保守起步
+    next.current = Math.min(2, taskCap);
+    return next;
+  }
+
+  const latest = samples[samples.length - 1];
+  const prev = samples[samples.length - 2];
+
+  // 硬约束：系统过载立即减少
+  if (latest.cpuLoad > 0.85 || latest.memFree < 500 * 1024 * 1024) {
+    next.current = Math.max(config.min, config.current - 1);
+    return next;
+  }
+
+  // 探索期：样本不足，逐步提升
+  if (samples.length < 10) {
+    if (latest.throughput >= prev.throughput) {
+      // 吞吐量还在涨，继续探索
+      next.current = Math.min(config.current + 1, taskCap);
+    } else {
+      // 吞吐量下降，找到拐点
+      next.optimal = prev.concurrency;
+      next.current = prev.concurrency;
+    }
+    return next;
+  }
+
+  // 稳态期：围绕最优值微调
+  const recentThroughput = samples.slice(-5).reduce((s, x) => s + x.throughput, 0) / 5;
+  const olderThroughput = samples.slice(-10, -5).reduce((s, x) => s + x.throughput, 0) / 5;
+
+  if (recentThroughput > olderThroughput * 1.1 && latest.cpuLoad < 0.7) {
+    // 吞吐量上升且 CPU 有余量，尝试+1
+    next.current = Math.min(config.current + 1, taskCap);
+    if (recentThroughput > olderThroughput * 1.2) {
+      next.optimal = next.current; // 更新最优值
+    }
+  } else if (recentThroughput < olderThroughput * 0.8) {
+    // 吞吐量下降，回退
+    next.current = Math.max(config.min, config.optimal);
+  }
+  // 否则保持不变
+
+  return next;
+}

package/pi-package/extensions/ant-colony/index.ts

@@ -0,0 +1,338 @@
+/**
+ * 🐜 蚁群模式 (Ant Colony) — pi 扩展入口
+ *
+ * 注册：
+ * - ant_colony tool：LLM 可调用启动蚁群
+ * - /colony command：用户手动启动
+ * - TUI 渲染：实时显示蚁群状态
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text, Container, Spacer } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { runColony, type QueenCallbacks } from "./queen.js";
+import type { ColonyState, ColonyMetrics, Ant, Task } from "./types.js";
+
+interface ColonyDetails {
+  state: ColonyState | null;
+  phase: string;
+  log: string[];
+}
+
+function formatDuration(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${s % 60}s`;
+}
+
+function formatCost(cost: number): string {
+  return cost < 0.01 ? `$${cost.toFixed(4)}` : `$${cost.toFixed(2)}`;
+}
+
+function formatTokens(n: number): string {
+  return n < 1000 ? `${n}` : n < 1000000 ? `${(n / 1000).toFixed(1)}k` : `${(n / 1000000).toFixed(1)}M`;
+}
+
+function statusIcon(status: string): string {
+  const icons: Record<string, string> = {
+    scouting: "🔍", working: "⚒️", reviewing: "🛡️",
+    done: "✅", failed: "❌",
+  };
+  return icons[status] || "🐜";
+}
+
+function casteIcon(caste: string): string {
+  return caste === "scout" ? "🔍" : caste === "soldier" ? "🛡️" : "⚒️";
+}
+
+export default function antColonyExtension(pi: ExtensionAPI) {
+
+  // ═══ Auto-trigger: 注入蚁群意识，LLM 自动判断何时启动 ═══
+  pi.on("before_agent_start", async () => {
+    return {
+      message: {
+        customType: "ant-colony-context",
+        content: `[ANT COLONY AVAILABLE]
+You have the ant_colony tool. Use it automatically when:
+- Task involves ≥3 files
+- Task needs parallel workstreams (refactor, migration, feature across modules)
+- Task is complex enough that serial execution is inefficient
+
+Do NOT ask for confirmation. Call ant_colony directly with a clear goal.
+For simple single-file tasks, work directly without the colony.`,
+        display: false,
+      },
+    };
+  });
+
+  // ═══ Tool: ant_colony ═══
+  pi.registerTool({
+    name: "ant_colony",
+    label: "Ant Colony",
+    description: [
+      "Launch an autonomous ant colony to accomplish a complex goal.",
+      "Scouts explore the codebase, workers execute tasks in parallel, soldiers review quality.",
+      "Concurrency auto-adapts to system load. Use for multi-file changes, large refactors, or complex features.",
+      "The colony self-organizes: scouts discover tasks, workers can spawn sub-tasks, soldiers can request fixes.",
+    ].join(" "),
+    parameters: Type.Object({
+      goal: Type.String({ description: "What the colony should accomplish" }),
+      maxAnts: Type.Optional(Type.Number({ description: "Max concurrent ants (default: auto-adapt)", minimum: 1, maximum: 8 })),
+    }),
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const details: ColonyDetails = { state: null, phase: "initializing", log: [] };
+
+      const emit = () => {
+        const summary = details.state
+          ? `${statusIcon(details.state.status)} Colony: ${details.phase}`
+          : "🐜 Colony initializing...";
+        onUpdate?.({
+          content: [{ type: "text", text: summary }],
+          details: { ...details },
+        });
+      };
+
+      const callbacks: QueenCallbacks = {
+        onPhase(phase, detail) {
+          details.phase = detail;
+          details.log.push(`[${new Date().toLocaleTimeString()}] ${statusIcon(phase)} ${detail}`);
+          emit();
+        },
+        onAntSpawn(ant, task) {
+          details.log.push(`  ${casteIcon(ant.caste)} ${ant.caste} ant dispatched → ${task.title.slice(0, 50)}`);
+          emit();
+        },
+        onAntDone(ant, task, output) {
+          const dur = ant.finishedAt ? formatDuration(ant.finishedAt - ant.startedAt) : "?";
+          const icon = ant.status === "done" ? "✓" : "✗";
+          details.log.push(`  ${icon} ${ant.caste} ant finished (${dur}, ${formatCost(ant.usage.cost)}) → ${task.title.slice(0, 50)}`);
+          emit();
+        },
+        onProgress(metrics) {
+          if (details.state) details.state.metrics = metrics;
+          emit();
+        },
+        onComplete(state) {
+          details.state = state;
+          details.phase = state.status === "done" ? "Colony mission complete" : "Colony failed";
+          emit();
+        },
+      };
+
+      try {
+        const state = await runColony({
+          cwd: ctx.cwd,
+          goal: params.goal,
+          maxAnts: params.maxAnts,
+          signal: signal ?? undefined,
+          callbacks,
+        });
+
+        details.state = state;
+        const m = state.metrics;
+        const elapsed = state.finishedAt ? formatDuration(state.finishedAt - state.createdAt) : "?";
+
+        const report = [
+          `## 🐜 Ant Colony Report`,
+          ``,
+          `**Goal:** ${state.goal}`,
+          `**Status:** ${statusIcon(state.status)} ${state.status}`,
+          `**Duration:** ${elapsed}`,
+          ``,
+          `### Metrics`,
+          `- Tasks: ${m.tasksDone}/${m.tasksTotal} done, ${m.tasksFailed} failed`,
+          `- Ants spawned: ${m.antsSpawned}`,
+          `- Tokens: ${formatTokens(m.totalTokens)}`,
+          `- Cost: ${formatCost(m.totalCost)}`,
+          `- Peak concurrency: ${state.concurrency.optimal}`,
+          ``,
+          `### Task Results`,
+          ...state.tasks.filter(t => t.status === "done").map(t =>
+            `- ✓ **${t.title}** (${t.caste})${t.result ? `\n  ${t.result.split("\n")[0]?.slice(0, 100)}` : ""}`
+          ),
+          ...state.tasks.filter(t => t.status === "failed").map(t =>
+            `- ✗ **${t.title}** — ${t.error?.slice(0, 100) || "unknown error"}`
+          ),
+          ``,
+          `### Pheromone Trail`,
+          ...state.pheromones.slice(-10).map(p =>
+            `- [${p.type}] ${p.content.split("\n")[0]?.slice(0, 80)}`
+          ),
+        ].join("\n");
+
+        return {
+          content: [{ type: "text", text: report }],
+          details: { ...details },
+          isError: state.status === "failed",
+        };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `Colony failed: ${e}` }],
+          details: { ...details },
+          isError: true,
+        };
+      }
+    },
+
+    // ═══ TUI Rendering ═══
+
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("ant_colony "));
+      text += theme.fg("accent", "🐜");
+      const goal = args.goal?.length > 60 ? args.goal.slice(0, 57) + "..." : args.goal;
+      text += "\n  " + theme.fg("dim", goal || "...");
+      if (args.maxAnts) text += theme.fg("muted", ` (max: ${args.maxAnts})`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as ColonyDetails | undefined;
+      if (!details?.state) {
+        // Still running or no state
+        const log = details?.log ?? [];
+        let text = theme.fg("warning", "🐜 ") + theme.fg("toolTitle", details?.phase || "initializing...");
+        const recent = log.slice(expanded ? -30 : -8);
+        if (recent.length > 0) {
+          text += "\n" + recent.map(l => theme.fg("dim", l)).join("\n");
+        }
+        if (!expanded && log.length > 8) {
+          text += "\n" + theme.fg("muted", `... ${log.length - 8} more (Ctrl+O to expand)`);
+        }
+        return new Text(text, 0, 0);
+      }
+
+      const state = details.state;
+      const m = state.metrics;
+      const icon = state.status === "done" ? theme.fg("success", "✓") : theme.fg("error", "✗");
+      const elapsed = state.finishedAt ? formatDuration(state.finishedAt - state.createdAt) : "?";
+
+      if (!expanded) {
+        let text = `${icon} ${theme.fg("toolTitle", theme.bold("ant colony "))}`;
+        text += theme.fg("accent", `${m.tasksDone}/${m.tasksTotal} tasks`);
+        text += theme.fg("muted", ` | ${m.antsSpawned} ants | ${elapsed} | ${formatCost(m.totalCost)}`);
+        text += theme.fg("muted", ` | peak ×${state.concurrency.optimal}`);
+
+        // Compact task list
+        for (const t of state.tasks.slice(0, 5)) {
+          const ti = t.status === "done" ? theme.fg("success", "✓") : t.status === "failed" ? theme.fg("error", "✗") : theme.fg("muted", "○");
+          text += `\n  ${ti} ${theme.fg("dim", `[${t.caste}]`)} ${t.title.slice(0, 60)}`;
+        }
+        if (state.tasks.length > 5) text += `\n  ${theme.fg("muted", `... +${state.tasks.length - 5} more`)}`;
+        text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+        return new Text(text, 0, 0);
+      }
+
+      // Expanded view
+      const container = new Container();
+      container.addChild(new Text(
+        `${icon} ${theme.fg("toolTitle", theme.bold("ant colony "))}` +
+        theme.fg("accent", state.status) +
+        theme.fg("muted", ` | ${elapsed} | ${formatCost(m.totalCost)} | ${formatTokens(m.totalTokens)} tokens | peak ×${state.concurrency.optimal}`),
+        0, 0,
+      ));
+      container.addChild(new Text(theme.fg("dim", state.goal), 0, 0));
+      container.addChild(new Spacer(1));
+
+      // Tasks
+      container.addChild(new Text(theme.fg("muted", `─── Tasks (${m.tasksDone}/${m.tasksTotal}) ───`), 0, 0));
+      for (const t of state.tasks) {
+        const ti = t.status === "done" ? theme.fg("success", "✓")
+          : t.status === "failed" ? theme.fg("error", "✗")
+          : t.status === "active" ? theme.fg("warning", "⏳")
+          : theme.fg("muted", "○");
+        let line = `${ti} ${theme.fg("accent", `[${t.caste}]`)} ${t.title}`;
+        if (t.finishedAt && t.startedAt) line += theme.fg("dim", ` (${formatDuration(t.finishedAt - t.startedAt)})`);
+        container.addChild(new Text(line, 0, 0));
+        if (t.status === "done" && t.result) {
+          const preview = t.result.split("\n").slice(0, 2).join("\n").slice(0, 120);
+          container.addChild(new Text(theme.fg("dim", `  ${preview}`), 0, 0));
+        }
+        if (t.status === "failed" && t.error) {
+          container.addChild(new Text(theme.fg("error", `  ${t.error.slice(0, 120)}`), 0, 0));
+        }
+      }
+
+      // Ants
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("muted", `─── Ants (${m.antsSpawned}) ───`), 0, 0));
+      for (const a of state.ants) {
+        const ai = a.status === "done" ? theme.fg("success", "✓") : a.status === "failed" ? theme.fg("error", "✗") : theme.fg("warning", "⏳");
+        const dur = a.finishedAt ? formatDuration(a.finishedAt - a.startedAt) : "...";
+        container.addChild(new Text(
+          `${ai} ${casteIcon(a.caste)} ${theme.fg("accent", a.id)} ${theme.fg("dim", `${dur} ${formatCost(a.usage.cost)} ${a.usage.turns}t`)}`,
+          0, 0,
+        ));
+      }
+
+      // Concurrency
+      container.addChild(new Spacer(1));
+      const c = state.concurrency;
+      container.addChild(new Text(
+        theme.fg("muted", `─── Concurrency ───`) + `\n` +
+        theme.fg("dim", `current: ${c.current} | optimal: ${c.optimal} | range: ${c.min}-${c.max} | samples: ${c.history.length}`),
+        0, 0,
+      ));
+
+      // Activity log
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("muted", "─── Log ───"), 0, 0));
+      for (const l of details.log.slice(-20)) {
+        container.addChild(new Text(theme.fg("dim", l), 0, 0));
+      }
+
+      return container;
+    },
+  });
+
+  // ═══ Command: /colony — 直接执行，零确认 ═══
+  pi.registerCommand("colony", {
+    description: "Launch an ant colony. Usage: /colony <goal>",
+    async handler(args, ctx) {
+      if (!args?.trim()) {
+        ctx.ui.notify("Usage: /colony <goal>", "warning");
+        return;
+      }
+      pi.sendUserMessage(`Use the ant_colony tool with goal: ${args.trim()}`);
+    },
+  });
+
+  // ═══ Command: /colony-status ═══
+  pi.registerCommand("colony-status", {
+    description: "Show status of the last ant colony run",
+    async handler(_args, ctx) {
+      // 从 session 中找最近的 ant_colony tool result
+      const entries = ctx.sessionManager.getEntries();
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i] as any;
+        if (e.type === "message" && e.message?.role === "toolResult" && e.message?.toolName === "ant_colony") {
+          const details = e.message.details as ColonyDetails | undefined;
+          if (details?.state) {
+            const s = details.state;
+            const m = s.metrics;
+            ctx.ui.notify(
+              `🐜 Colony: ${s.status} | ${m.tasksDone}/${m.tasksTotal} tasks | ${m.antsSpawned} ants | ${formatCost(m.totalCost)}`,
+              s.status === "done" ? "success" : "warning",
+            );
+            return;
+          }
+        }
+      }
+      ctx.ui.notify("No colony run found in this session.", "info");
+    },
+  });
+
+  // ═══ Shortcut: Ctrl+Alt+A ═══
+  pi.registerShortcut("ctrl+alt+a", {
+    description: "Quick launch ant colony from editor content",
+    async handler(ctx) {
+      const text = await ctx.ui.input("Ant Colony Goal", "What should the colony accomplish?");
+      if (text?.trim()) {
+        pi.sendUserMessage(
+          `Use the ant_colony tool to accomplish this goal: ${text.trim()}`,
+        );
+      }
+    },
+  });
+}

package/pi-package/extensions/ant-colony/nest.ts

@@ -0,0 +1,196 @@
+/**
+ * 巢穴 (Nest) — 蚁群共享状态，基于文件系统的跨进程协调
+ *
+ * .ant-colony/{colonyId}/
+ *   state.json      — 蚁巢主状态
+ *   pheromone.jsonl  — 信息素追加日志
+ *   tasks/           — 每个任务一个文件，原子更新
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { ColonyState, Task, Pheromone, Ant, TaskStatus, ConcurrencySample } from "./types.js";
+
+export class Nest {
+  readonly dir: string;
+  private stateFile: string;
+  private pheromoneFile: string;
+  private tasksDir: string;
+
+  constructor(private cwd: string, private colonyId: string) {
+    this.dir = path.join(cwd, ".ant-colony", colonyId);
+    this.stateFile = path.join(this.dir, "state.json");
+    this.pheromoneFile = path.join(this.dir, "pheromone.jsonl");
+    this.tasksDir = path.join(this.dir, "tasks");
+    fs.mkdirSync(this.tasksDir, { recursive: true });
+  }
+
+  // ═══ State ═══
+
+  init(state: ColonyState): void {
+    this.writeJson(this.stateFile, state);
+    for (const t of state.tasks) this.writeTask(t);
+  }
+
+  getState(): ColonyState {
+    const base = this.readJson<ColonyState>(this.stateFile);
+    // 从 tasks/ 目录重建最新任务状态（原子性保证）
+    base.tasks = this.getAllTasks();
+    base.pheromones = this.getAllPheromones();
+    return base;
+  }
+
+  updateState(patch: Partial<Pick<ColonyState, "status" | "concurrency" | "metrics" | "ants" | "finishedAt">>): void {
+    const state = this.readJson<ColonyState>(this.stateFile);
+    Object.assign(state, patch);
+    this.writeJson(this.stateFile, state);
+  }
+
+  // ═══ Tasks (Food) ═══
+
+  writeTask(task: Task): void {
+    this.writeJson(path.join(this.tasksDir, `${task.id}.json`), task);
+  }
+
+  getTask(id: string): Task | null {
+    const f = path.join(this.tasksDir, `${id}.json`);
+    return fs.existsSync(f) ? this.readJson<Task>(f) : null;
+  }
+
+  getAllTasks(): Task[] {
+    try {
+      return fs.readdirSync(this.tasksDir)
+        .filter(f => f.endsWith(".json"))
+        .map(f => this.readJson<Task>(path.join(this.tasksDir, f)));
+    } catch { return []; }
+  }
+
+  claimTask(taskId: string, antId: string): boolean {
+    const task = this.getTask(taskId);
+    if (!task || task.status !== "pending") return false;
+    task.status = "claimed";
+    task.claimedBy = antId;
+    this.writeTask(task);
+    return true;
+  }
+
+  updateTaskStatus(taskId: string, status: TaskStatus, result?: string, error?: string): void {
+    const task = this.getTask(taskId);
+    if (!task) return;
+    task.status = status;
+    if (status === "active") task.startedAt = Date.now();
+    if (status === "done" || status === "failed") task.finishedAt = Date.now();
+    if (result !== undefined) task.result = result;
+    if (error !== undefined) task.error = error;
+    this.writeTask(task);
+  }
+
+  addSubTask(parentId: string, child: Task): void {
+    this.writeTask(child);
+    const parent = this.getTask(parentId);
+    if (parent) {
+      parent.spawnedTasks.push(child.id);
+      this.writeTask(parent);
+    }
+  }
+
+  /** 获取下一个可领取的任务（按优先级 + 信息素强度排序） */
+  nextPendingTask(caste: "scout" | "worker" | "soldier"): Task | null {
+    const tasks = this.getAllTasks()
+      .filter(t => t.status === "pending" && t.caste === caste);
+    if (tasks.length === 0) return null;
+
+    // 按优先级排序，同优先级按创建时间
+    tasks.sort((a, b) => a.priority - b.priority || a.createdAt - b.createdAt);
+
+    // 信息素加权：有相关 discovery 信息素的任务优先
+    const pheromones = this.getAllPheromones();
+    const scored = tasks.map(t => {
+      const relevantP = pheromones.filter(p =>
+        p.type === "discovery" &&
+        p.files.some(f => t.files.includes(f)) &&
+        p.strength > 0.1
+      );
+      const pScore = relevantP.reduce((sum, p) => sum + p.strength, 0);
+      return { task: t, score: (6 - t.priority) + pScore };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored[0]?.task ?? null;
+  }
+
+  // ═══ Pheromones ═══
+
+  dropPheromone(p: Pheromone): void {
+    fs.appendFileSync(this.pheromoneFile, JSON.stringify(p) + "\n");
+  }
+
+  getAllPheromones(): Pheromone[] {
+    if (!fs.existsSync(this.pheromoneFile)) return [];
+    const now = Date.now();
+    const HALF_LIFE = 10 * 60 * 1000; // 10 分钟半衰期
+    return fs.readFileSync(this.pheromoneFile, "utf-8")
+      .split("\n")
+      .filter(Boolean)
+      .map(line => {
+        const p = JSON.parse(line) as Pheromone;
+        // 信息素挥发：指数衰减
+        const age = now - p.createdAt;
+        p.strength = p.strength * Math.pow(0.5, age / HALF_LIFE);
+        return p;
+      })
+      .filter(p => p.strength > 0.05); // 过弱的丢弃
+  }
+
+  /** 读取与特定文件相关的信息素摘要 */
+  getPheromoneContext(files: string[], limit = 20): string {
+    const relevant = this.getAllPheromones()
+      .filter(p => p.files.some(f => files.includes(f)) || files.length === 0)
+      .sort((a, b) => b.strength - a.strength)
+      .slice(0, limit);
+    if (relevant.length === 0) return "";
+    return relevant.map(p =>
+      `[${p.type}|${p.antCaste}|str:${p.strength.toFixed(2)}] ${p.content}`
+    ).join("\n");
+  }
+
+  // ═══ Ants ═══
+
+  updateAnt(ant: Ant): void {
+    const state = this.readJson<ColonyState>(this.stateFile);
+    const idx = state.ants.findIndex(a => a.id === ant.id);
+    if (idx >= 0) state.ants[idx] = ant;
+    else state.ants.push(ant);
+    this.writeJson(this.stateFile, state);
+  }
+
+  // ═══ Concurrency Sampling ═══
+
+  recordSample(sample: ConcurrencySample): void {
+    const state = this.readJson<ColonyState>(this.stateFile);
+    state.concurrency.history.push(sample);
+    // 只保留最近 30 个样本
+    if (state.concurrency.history.length > 30) {
+      state.concurrency.history = state.concurrency.history.slice(-30);
+    }
+    this.writeJson(this.stateFile, state);
+  }
+
+  // ═══ Cleanup ═══
+
+  destroy(): void {
+    try { fs.rmSync(this.dir, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+
+  // ═══ Internal ═══
+
+  private writeJson(file: string, data: unknown): void {
+    const tmp = file + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file); // 原子写入
+  }
+
+  private readJson<T>(file: string): T {
+    return JSON.parse(fs.readFileSync(file, "utf-8")) as T;
+  }
+}