oh-pi 0.1.52 → 0.1.54

package/dist/bin/oh-pi.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * @module oh-pi CLI 入口脚本
+ * 处理 Windows 终端 UTF-8 编码，然后启动主流程。
+ */
 import { execSync } from "node:child_process";
 // Windows terminals default to non-UTF-8 codepage (e.g. GBK/CP936),
 // causing garbled emoji and Unicode output. Force UTF-8 before any output.

package/dist/tui/agents-select.d.ts

@@ -1 +1,9 @@
+/**
+ * Presents an interactive prompt for the user to select an agent template
+ * (e.g. general developer, fullstack, security, data/AI, colony operator).
+ *
+ * Exits the process if the user cancels the selection.
+ *
+ * @returns The selected agent template identifier string.
+ */
 export declare function selectAgents(): Promise<string>;

package/dist/tui/agents-select.js

@@ -1,5 +1,13 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
+/**
+ * Presents an interactive prompt for the user to select an agent template
+ * (e.g. general developer, fullstack, security, data/AI, colony operator).
+ *
+ * Exits the process if the user cancels the selection.
+ *
+ * @returns The selected agent template identifier string.
+ */
 export async function selectAgents() {
     const agent = await p.select({
         message: t("agent.select"),

package/dist/tui/confirm-apply.d.ts

@@ -1,3 +1,8 @@
 import type { OhPConfig } from "../types.js";
 import type { EnvInfo } from "../utils/detect.js";
+/**
+ * 展示配置摘要，处理已有配置的备份/覆盖，安装 pi（如需），并应用最终配置。
+ * @param config - 用户选择的配置对象
+ * @param env - 当前环境信息
+ */
 export declare function confirmApply(config: OhPConfig, env: EnvInfo): Promise<void>;

package/dist/tui/confirm-apply.js

@@ -2,9 +2,20 @@ import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { t } from "../i18n.js";
 import { applyConfig, installPi, backupConfig } from "../utils/install.js";
+/**
+ * 统计已有配置中指定目录下的文件数量。
+ * @param env - 环境信息
+ * @param dir - 目录名称前缀
+ * @returns 匹配的文件数
+ */
 function countExisting(env, dir) {
     return env.existingFiles.filter(f => f.startsWith(dir + "/")).length;
 }
+/**
+ * 展示配置摘要，处理已有配置的备份/覆盖，安装 pi（如需），并应用最终配置。
+ * @param config - 用户选择的配置对象
+ * @param env - 当前环境信息
+ */
 export async function confirmApply(config, env) {
     // ═══ Summary ═══
     const summary = [

package/dist/tui/extension-select.d.ts

@@ -1 +1,6 @@
+/**
+ * Prompts the user to select enabled extensions from the available list via a multi-select TUI prompt.
+ * Exits the process if the user cancels the selection.
+ * @returns A promise that resolves to an array of selected extension names.
+ */
 export declare function selectExtensions(): Promise<string[]>;

package/dist/tui/extension-select.js

@@ -1,6 +1,11 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
 import { EXTENSIONS } from "../types.js";
+/**
+ * Prompts the user to select enabled extensions from the available list via a multi-select TUI prompt.
+ * Exits the process if the user cancels the selection.
+ * @returns A promise that resolves to an array of selected extension names.
+ */
 export async function selectExtensions() {
     const exts = await p.multiselect({
         message: t("ext.select"),

package/dist/tui/keybinding-select.d.ts

@@ -1 +1,8 @@
+/**
+ * Prompts the user to select a keybinding scheme (default, Vim, or Emacs).
+ *
+ * Displays an interactive select prompt and exits the process if the user cancels.
+ *
+ * @returns The name of the selected keybinding scheme.
+ */
 export declare function selectKeybindings(): Promise<string>;

package/dist/tui/keybinding-select.js

@@ -1,5 +1,12 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
+/**
+ * Prompts the user to select a keybinding scheme (default, Vim, or Emacs).
+ *
+ * Displays an interactive select prompt and exits the process if the user cancels.
+ *
+ * @returns The name of the selected keybinding scheme.
+ */
 export async function selectKeybindings() {
     const kb = await p.select({
         message: t("kb.select"),

package/dist/tui/mode-select.d.ts

@@ -1,3 +1,8 @@
 import type { EnvInfo } from "../utils/detect.js";
 export type Mode = "quick" | "custom" | "preset";
+/**
+ * Prompt the user to select a configuration mode: quick, preset, or custom.
+ * @param {EnvInfo} env - Detected environment information
+ * @returns {Promise<Mode>} The mode selected by the user
+ */
 export declare function selectMode(env: EnvInfo): Promise<Mode>;

package/dist/tui/mode-select.js

@@ -1,5 +1,10 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
+/**
+ * Prompt the user to select a configuration mode: quick, preset, or custom.
+ * @param {EnvInfo} env - Detected environment information
+ * @returns {Promise<Mode>} The mode selected by the user
+ */
 export async function selectMode(env) {
     const mode = await p.select({
         message: t("mode.select"),

package/dist/tui/preset-select.d.ts

@@ -1,5 +1,10 @@
 import type { OhPConfig } from "../types.js";
 interface Preset extends Omit<OhPConfig, "providers"> {
 }
+/**
+ * Prompts the user to select a configuration preset via an interactive TUI menu.
+ * Exits the process if the user cancels the selection.
+ * @returns The {@link Preset} configuration object for the chosen preset.
+ */
 export declare function selectPreset(): Promise<Preset>;
 export {};

package/dist/tui/preset-select.js

@@ -1,5 +1,9 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
+/**
+ * Registry of built-in configuration presets (Full Power / Clean / Colony).
+ * Each entry maps a preset key to its i18n label/hint keys and a full {@link Preset} config object.
+ */
 const PRESETS = {
     full: {
         labelKey: "preset.full", hintKey: "preset.fullHint",
@@ -27,6 +31,11 @@ const PRESETS = {
         },
     },
 };
+/**
+ * Prompts the user to select a configuration preset via an interactive TUI menu.
+ * Exits the process if the user cancels the selection.
+ * @returns The {@link Preset} configuration object for the chosen preset.
+ */
 export async function selectPreset() {
     const key = await p.select({
         message: t("preset.select"),

package/dist/tui/provider-setup.d.ts

@@ -1,3 +1,8 @@
 import { type ProviderConfig } from "../types.js";
 import type { EnvInfo } from "../utils/detect.js";
+/**
+ * Interactively configure API providers, detecting existing keys, allowing multi-select, and supporting custom endpoints.
+ * @param env - Current environment info with detected providers
+ * @returns Configured provider list
+ */
 export declare function setupProviders(env?: EnvInfo): Promise<ProviderConfig[]>;

package/dist/tui/provider-setup.js

@@ -12,7 +12,13 @@ const PROVIDER_API_URLS = {
     xai: "https://api.x.ai",
     mistral: "https://api.mistral.ai",
 };
-/** Fetch models dynamically — tries multiple API styles, returns metadata + detected API type */
+/**
+ * 动态获取模型列表，依次尝试 Anthropic、Google、OpenAI 兼容 API 风格。
+ * @param provider - 提供商名称
+ * @param baseUrl - API 基础地址
+ * @param apiKey - API 密钥或环境变量名
+ * @returns 发现的模型列表及检测到的 API 类型
+ */
 async function fetchModels(provider, baseUrl, apiKey) {
     const base = baseUrl.replace(/\/+$/, "");
     const resolvedKey = process.env[apiKey] ?? apiKey;
@@ -91,6 +97,11 @@ async function fetchModels(provider, baseUrl, apiKey) {
     catch { /* fall through */ }
     return { models: [] };
 }
+/**
+ * Interactively configure API providers, detecting existing keys, allowing multi-select, and supporting custom endpoints.
+ * @param env - Current environment info with detected providers
+ * @returns Configured provider list
+ */
 export async function setupProviders(env) {
     const entries = Object.entries(PROVIDERS);
     // Detect existing providers — offer skip or add new
@@ -175,6 +186,10 @@ export async function setupProviders(env) {
     }
     return configs;
 }
+/**
+ * Interactively configure a custom provider (Ollama, vLLM, or other OpenAI-compatible endpoints).
+ * @returns Custom provider config, or null if cancelled
+ */
 async function setupCustomProvider() {
     const name = await p.text({
         message: t("provider.name"),
@@ -207,6 +222,15 @@ async function setupCustomProvider() {
     p.log.success(t("provider.customConfigured", { name, url: baseUrl }));
     return { name, apiKey, defaultModel, baseUrl, api, discoveredModels };
 }
+/**
+ * Select a default model by dynamically fetching available models, falling back to a static list or manual input.
+ * @param provider - Provider name
+ * @param label - Provider display label
+ * @param staticModels - Static model list fallback
+ * @param baseUrl - API base URL
+ * @param apiKey - API key
+ * @returns Selected model and discovered model metadata
+ */
 async function selectModelWithMeta(provider, label, staticModels, baseUrl, apiKey) {
     let modelIds = staticModels;
     let discoveredModels;
@@ -246,6 +270,11 @@ async function selectModelWithMeta(provider, label, staticModels, baseUrl, apiKe
     }
     return { defaultModel: model, discoveredModels, api };
 }
+/**
+ * Prompt the user to enter an API key.
+ * @param label - Provider display label
+ * @returns The entered API key
+ */
 async function promptKey(label) {
     const key = await p.password({
         message: t("provider.apiKey", { label }),

package/dist/tui/theme-select.d.ts

@@ -1 +1,6 @@
+/**
+ * Prompts the user to select a theme from the available themes list.
+ * Exits the process if the user cancels the selection.
+ * @returns The name of the selected theme.
+ */
 export declare function selectTheme(): Promise<string>;

package/dist/tui/theme-select.js

@@ -1,6 +1,11 @@
 import * as p from "@clack/prompts";
 import { t } from "../i18n.js";
 import { THEMES } from "../types.js";
+/**
+ * Prompts the user to select a theme from the available themes list.
+ * Exits the process if the user cancels the selection.
+ * @returns The name of the selected theme.
+ */
 export async function selectTheme() {
     const theme = await p.select({
         message: t("theme.select"),

package/dist/tui/welcome.d.ts

@@ -1,2 +1,6 @@
 import type { EnvInfo } from "../utils/detect.js";
+/**
+ * 展示欢迎界面，显示 pi 安装状态、环境信息及已有配置概况。
+ * @param {EnvInfo} env - 当前检测到的环境信息
+ */
 export declare function welcome(env: EnvInfo): void;

package/dist/tui/welcome.js

@@ -1,6 +1,10 @@
 import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { t } from "../i18n.js";
+/**
+ * 展示欢迎界面，显示 pi 安装状态、环境信息及已有配置概况。
+ * @param {EnvInfo} env - 当前检测到的环境信息
+ */
 export function welcome(env) {
     console.clear();
     p.intro(chalk.cyan.bold(" oh-pi ") + chalk.dim(t("welcome.title")));
@@ -19,6 +23,11 @@ export function welcome(env) {
             categorize(env.existingFiles), t("welcome.existingConfig"));
     }
 }
+/**
+ * 按顶层目录分类统计文件数量，返回格式化字符串。
+ * @param {string[]} files - 文件相对路径列表
+ * @returns {string} 分类统计字符串，如 "extensions (3)  prompts (5)"
+ */
 function categorize(files) {
     const cats = {};
     for (const f of files) {

package/dist/utils/resources.d.ts

@@ -1,3 +1,4 @@
+/** 资源路径映射对象 */
 export declare const resources: {
     agent: (name: string) => string;
     extension: (name: string) => string;

package/dist/utils/resources.js

@@ -5,6 +5,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const RESOURCES = join(PKG_ROOT, "pi-package");
+/** 资源路径映射对象 */
 export const resources = {
     agent: (name) => join(RESOURCES, "agents", `${name}.md`),
     extension: (name) => join(RESOURCES, "extensions", name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-pi",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "One-click setup for pi-coding-agent. Like oh-my-zsh for pi.",
   "type": "module",
   "bin": {

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

@@ -67,7 +67,7 @@ export function adapt(config: ConcurrencyConfig, pendingTasks: number): Concurre
   // 不超过待处理任务数
   const taskCap = Math.min(pendingTasks, config.max);
 
-  if (samples.length < 3) {
+  if (samples.length < 2) {
     // 冷启动：直接给一半 max，快速利用并发
     next.current = Math.min(Math.ceil(config.max / 2), taskCap);
     return next;
@@ -111,5 +111,10 @@ export function adapt(config: ConcurrencyConfig, pendingTasks: number): Concurre
   }
   // 否则保持不变
 
+  // 429 recovery: restore to optimal when CPU is underutilized (e.g. after backoff)
+  if (latest.cpuLoad < 0.5 && next.current < config.optimal) {
+    next.current = config.optimal;
+  }
+
   return next;
 }

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

@@ -558,6 +558,75 @@ export default function antColonyExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ═══ Helper: build status summary ═══
+
+  function buildStatusText(): string {
+    if (!activeColony) return "No colony is currently running.";
+    const c = activeColony;
+    const state = c.state;
+    const elapsed = state ? formatDuration(Date.now() - state.createdAt) : "0s";
+    const m = state?.metrics;
+    const tasks = state?.tasks || [];
+    const ants = state?.ants || [];
+    const streams = Array.from(c.antStreams.values());
+
+    const lines: string[] = [
+      `## 🐜 Colony Status`,
+      `**Goal:** ${c.goal}`,
+      `**Phase:** ${c.phase}`,
+      `**Duration:** ${elapsed}`,
+    ];
+
+    if (m) {
+      lines.push(`**Tasks:** ${m.tasksDone}/${m.tasksTotal} done, ${m.tasksFailed} failed`);
+      lines.push(`**Ants spawned:** ${m.antsSpawned} | **Active:** ${streams.length}`);
+      lines.push(`**Cost:** ${formatCost(m.totalCost)} | **Tokens:** ${formatTokens(m.totalTokens)}`);
+    }
+
+    if (tasks.length > 0) {
+      lines.push("", "### Tasks");
+      for (const t of tasks) {
+        const icon = t.status === "done" ? "✓" : t.status === "failed" ? "✗" : t.status === "active" ? "●" : "○";
+        const dur = t.finishedAt && t.startedAt ? ` (${formatDuration(t.finishedAt - t.startedAt)})` : "";
+        lines.push(`- ${icon} [${t.caste}] ${t.title}${dur}`);
+      }
+    }
+
+    if (streams.length > 0) {
+      lines.push("", "### Active Ants");
+      for (const s of streams) {
+        lines.push(`- ${casteIcon(s.caste)} ${s.antId.slice(0, 14)} | ${s.tokens}tok | ${s.lastLine.slice(0, 60)}`);
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  // ═══ Tool: bg_colony_status ═══
+  pi.registerTool({
+    name: "bg_colony_status",
+    label: "Colony Status",
+    description: "Check the status of a running background ant colony. Use this instead of bg_status to monitor colony progress.",
+    parameters: Type.Object({}),
+    async execute() {
+      return {
+        content: [{ type: "text" as const, text: buildStatusText() }],
+      };
+    },
+  });
+
+  // ═══ Command: /colony-status ═══
+  pi.registerCommand("colony-status", {
+    description: "Show current colony progress",
+    async handler(_args, ctx) {
+      if (!activeColony) {
+        ctx.ui.notify("No colony is currently running.", "info");
+        return;
+      }
+      ctx.ui.notify(buildStatusText(), "info");
+    },
+  });
+
   // ═══ Command: /colony-stop ═══
   pi.registerCommand("colony-stop", {
     description: "Stop the running background colony",

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

@@ -226,8 +226,8 @@ export class Nest {
   // ═══ Internal ═══
 
   private withStateLock<T>(fn: () => T): T {
-    const MAX_WAIT = 5000;
-    const SPIN_MS = 15;
+    const MAX_WAIT = 3000;
+    const SPIN_MS = 1;
     const start = Date.now();
     while (true) {
       try {

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

@@ -72,7 +72,7 @@ function makeInitialScoutTask(goal: string): Task {
 
 function childTaskFromParsed(
   parentId: string,
-  parsed: { title: string; description: string; files: string[]; caste: AntCaste; priority: TaskPriority },
+  parsed: { title: string; description: string; files: string[]; caste: AntCaste; priority: TaskPriority; context?: string },
 ): Task {
   return {
     id: makeTaskId(),
@@ -83,6 +83,7 @@ function childTaskFromParsed(
     status: "pending",
     priority: parsed.priority,
     files: parsed.files,
+    context: parsed.context || undefined,
     claimedBy: null,
     result: null,
     error: null,
@@ -378,7 +379,6 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
       nest.updateState({ status: "failed", finishedAt: Date.now() });
       const finalState = nest.getState();
       callbacks.onComplete(finalState);
-      cleanup();
       return finalState;
     }
 
@@ -399,9 +399,18 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
       await runAntWave({ ...waveBase, caste: "worker" });
     }
 
+    // ═══ Auto-check: run tsc before soldier review ═══
+    let tscPassed = true;
+    try {
+      const { execSync } = await import("node:child_process");
+      execSync("npx tsc --noEmit", { cwd: opts.cwd, timeout: 30000, stdio: "pipe" });
+    } catch {
+      tscPassed = false;
+    }
+
     // ═══ Phase 3: 审查 ═══
     const completedWorkerTasks = nest.getAllTasks().filter(t => t.caste === "worker" && t.status === "done");
-    if (completedWorkerTasks.length > 0) {
+    if (completedWorkerTasks.length > 0 && (!tscPassed || completedWorkerTasks.length > 3)) {
       nest.updateState({ status: "reviewing" });
       callbacks.onPhase("reviewing", "Dispatching soldier ants to review changes...");
       const reviewTask = makeReviewTask(completedWorkerTasks);
@@ -424,14 +433,14 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
     nest.updateState({ status: "done", finishedAt: Date.now(), metrics: finalMetrics });
     const finalState = nest.getState();
     callbacks.onComplete(finalState);
-    cleanup();
     return finalState;
 
   } catch (e) {
     nest.updateState({ status: "failed", finishedAt: Date.now() });
     const failState = nest.getState();
     callbacks.onComplete(failState);
-    cleanup();
     return failState;
+  } finally {
+    cleanup();
   }
 }

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

@@ -57,6 +57,7 @@ export interface ParsedSubTask {
   files: string[];
   caste: AntCaste;
   priority: 1 | 2 | 3 | 4 | 5;
+  context?: string;
 }
 
 const CASTE_PROMPTS: Record<AntCaste, string> = {
@@ -67,6 +68,7 @@ Behavior:
 - Identify files, functions, dependencies related to the goal
 - IMPORTANT: After EACH tool call, summarize what you found so far. Do NOT wait until the end.
 - Report findings as structured intelligence for Worker Ants
+- For each recommended task, include the KEY code snippets (with file:line) the worker will need — this saves workers from re-reading files
 
 Output format (MUST follow exactly):
 ## Discoveries
@@ -79,6 +81,7 @@ For each task the colony should do next:
 - files: <comma-separated file paths>
 - caste: worker
 - priority: <1-5, 1=highest>
+- context: <relevant code snippets that the worker will need, with file:line references>
 
 ## Warnings
 Any risks, blockers, or conflicts detected.`,
@@ -142,6 +145,12 @@ function buildPrompt(task: Task, pheromoneContext: string, castePrompt: string,
   if (task.files.length > 0) {
     prompt += `**Files scope:** ${task.files.join(", ")}\n`;
   }
+  if (task.context) {
+    prompt += `\n## Pre-loaded Context (from scout)\n${task.context}\n`;
+  }
+  if (/[\u4e00-\u9fff]/.test(task.description)) {
+    prompt += '\nIMPORTANT: Follow the language requirements specified in the task description. If the task says to write in Chinese, write in Chinese.\n';
+  }
   return prompt;
 }
 
@@ -149,13 +158,18 @@ function buildPrompt(task: Task, pheromoneContext: string, castePrompt: string,
 function parseSubTasks(output: string): ParsedSubTask[] {
   const tasks: ParsedSubTask[] = [];
   const regex = /### TASK:\s*(.+)\n(?:- description:\s*(.+)\n)?(?:- files:\s*(.+)\n)?(?:- caste:\s*(\w+)\n)?(?:- priority:\s*(\d))?/g;
+  const taskBlocks = output.split(/(?=### TASK:)/);
   for (const m of output.matchAll(regex)) {
+    const block = taskBlocks.find(b => b.includes(`### TASK: ${m[1]?.trim()}`)) || "";
+    const ctxMatch = block.match(/- context:\s*([\s\S]*?)(?=### TASK:|## |\n\n|$)/);
+    const context = ctxMatch?.[1]?.trim() || undefined;
     tasks.push({
       title: m[1]?.trim() || "Untitled",
       description: m[2]?.trim() || m[1]?.trim() || "",
       files: (m[3]?.trim() || "").split(",").map(f => f.trim()).filter(Boolean),
       caste: (m[4]?.trim() as AntCaste) || "worker",
       priority: (parseInt(m[5] || "3") as 1 | 2 | 3 | 4 | 5) || 3,
+      context,
     });
   }
   return tasks;

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

@@ -35,6 +35,7 @@ export interface Task {
   status: TaskStatus;
   priority: TaskPriority;
   files: string[];           // 锁定的文件
+  context?: string;          // Scout 预加载的代码片段
   claimedBy: string | null;  // ant id
   result: string | null;
   error: string | null;