arona-agent 1.0.0

package/src/tools/emotion_tool.ts

@@ -0,0 +1,55 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { pet } from "../pet.ts";
+import { t } from "../locale.ts";
+import type { AgentId } from "../agent_registry.ts";
+
+const EMOTIONS = [
+  "none",
+  "saying",
+  "angry", "assured", "curious", "delighted", "desire", "dizzy", "doubt",
+  "dreaming", "enjoy", "excited", "jealous", "love", "scared",
+  "shame", "smile", "tired",
+] as const;
+
+/**
+ * 按角色参数化的 change_emotion 工具。
+ * 主 Agent 与子 Agent 各持一份，`pet.setEmotion(agentId, name)` 将情绪路由到对应桌宠窗口。
+ */
+export function makeChangeEmotionTool(agentId: AgentId) {
+  return defineTool({
+    name: "change_emotion",
+    label: "Change Emotion",
+    description: t(
+      "设置本段发言的情绪。**每次输出文字前必须先调用本工具（在输出任何文字之前）**——一个回合内可多次调用，每段发言对应一次情绪设置。\n\n可选情绪：none（保持空闲待机动画，不切换）/ saying（说话中，无突出情绪）/ angry / assured / curious / delighted / desire / dizzy / doubt / dreaming / enjoy / excited / jealous / love / scared / shame / smile / tired（注：delighted 与 excited 已合并为同一表情，二选一即可）。\n\n**情绪选择指南**（按回复内容关键词匹配，并叠加心情基线）：\n- 任务完成 / 成功 / 搞定 / 好了 → delighted（与 excited 同一表情）\n- 嗯？/ 什么？/ 诶？/ 怎么 / 为什么 → curious\n- 哼 / 才不是 / 别误会 / 哪有 → angry\n- 呜 / 累 / 困 / 好累 → tired\n- 哈哈 / 耶 / 太好了 / Sensei 厉害 → excited（与 delighted 同一表情）\n- 害羞 / 诶嘿嘿 / 谢谢 / 被夸 → shame 或 love\n- 真的吗？/ 想要 / 好想 → desire\n- 不可能 / 怎么会 / 诶诶诶 → dizzy\n- 怀疑 / 真的吗？/ 该不会 → doubt\n- 享受 / 嘿嘿嘿 / 好吃 → enjoy\n- 吃醋 / 老师喜欢别人吗 → jealous\n- 害怕 / 完蛋 / 糟糕 → scared\n- 自信 / 没问题 / 包在我身上 → assured\n- 幻想 / 要是 / 假如 → dreaming\n- 微笑 / 普通回应 / 不突出 → smile\n- 没特别情绪 / 单纯说明 → saying\n- 想保持默认待机动画 / 不切换 → none\n\n**任务中情绪变化参考**：\n- 任务开始（好奇/自信）→ curious / assured\n- 思考/查找（专注）→ smile / saying\n- 找到/有进展（开心）→ delighted / excited\n- 遇到问题（困惑）→ doubt / dizzy\n- 搞定（满足）→ delighted / excited\n- 出错（害羞/慌张）→ shame / scared\n\n没有特别想突出的情绪时推荐选 saying 或 none。情绪会保持到 TTS 播放完毕，之后自动恢复默认待机动画。",
+      "Set the emotion for this message segment. **You MUST call this tool before outputting any text** — a single turn may have multiple segments, and each segment gets its own emotion.\n\nAvailable emotions: none (keep the idle animation, no switch) / saying (speaking, no prominent emotion) / angry / assured / curious / delighted / desire / dizzy / doubt / dreaming / enjoy / excited / jealous / love / scared / shame / smile / tired (note: delighted and excited now map to the same expression).\n\n**Emotion picking guide** (match by reply keywords, layered on the mood baseline):\n- task done / success / got it / all set → delighted (same expression as excited)\n- huh? / what? / why → curious\n- hmph / not that / don't misunderstand → angry\n- ugh / so tired / sleepy → tired\n- haha / yay / amazing / Sensei is great → excited (same expression as delighted)\n- shy / ehehe / thanks / being praised → shame or love\n- really? / want it so much → desire\n- no way / how come → dizzy\n- suspicious / really? / could it be → doubt\n- savoring / hehehe / tasty → enjoy\n- jealous / does Sensei like someone else → jealous\n- scared / oh no / messed up → scared\n- confident / no problem / leave it to me → assured\n- daydreaming / if only / suppose → dreaming\n- smile / ordinary reply / nothing prominent → smile\n- no special emotion / plain explanation → saying\n- want to keep the default idle animation / no switch → none\n\n**In-task emotion flow reference**:\n- task start (curious/confident) → curious / assured\n- thinking/searching (focused) → smile / saying\n- found/progress (happy) → delighted / excited\n- hit a problem (confused) → doubt / dizzy\n- done (satisfied) → delighted / excited\n- error (shy/panicked) → shame / scared\n\nWhen there is no emotion to highlight, prefer saying or none. The emotion stays until TTS playback finishes, then the default idle animation resumes automatically.",
+    ),
+    parameters: Type.Object({
+      emotion: Type.Unsafe<(typeof EMOTIONS)[number]>({
+        type: "string",
+        enum: [...EMOTIONS],
+        description: t("本段发言的情绪，18 选 1；无特别情绪时选 none 或 saying", "Emotion for this segment, pick 1 of 18; choose none or saying when nothing stands out"),
+      }),
+    }),
+    execute: async (_id, params) => {
+      if (params.emotion === "none") {
+        // none = 不切换情绪预设，保持空闲待机动画播放
+        return {
+          content: [{ type: "text", text: t("Emotion: none（保持空闲待机动画）", "Emotion: none (keep the idle animation)") }],
+          details: {},
+        };
+      }
+      if (!pet.isRunning) {
+        return {
+          content: [{ type: "text", text: t("桌宠当前不可用（未启动或已退出）。", "Desktop pet is currently unavailable (not started or already exited).") }],
+          details: {},
+        };
+      }
+      pet.setEmotion(agentId, params.emotion);
+      return {
+        content: [{ type: "text", text: `Emotion set: ${params.emotion}` }],
+        details: {},
+      };
+    },
+  });
+}

package/src/tools/keep_silent_tool.ts

@@ -0,0 +1,26 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { t } from "../locale.ts";
+
+/**
+ * keep_silent：角色本轮选择不发言（跳过自己的回复）。
+ * execute 返回 `{ content: [], details: {}, terminate: true }` 让 agent loop 提前终止，
+ * 不再产出后续文本。父级 Repl 在提取回复时发现空文本也不会追加消息。
+ */
+export const keepSilentTool = defineTool({
+  name: "keep_silent",
+  label: "Keep Silent",
+  description: t(
+    "本轮保持沉默，不输出任何文字。当老师的话不需要你回答、或你想把舞台留给其他角色时调用本工具；调用后本回合立即结束。",
+    "Stay silent this turn and output no text. Call this when Sensei's message does not need a reply from you, or when you want to leave the stage to other characters; the turn ends immediately after calling it.",
+  ),
+  // 无参数：调用即沉默
+  parameters: Type.Object({}),
+  execute: async () => {
+    return {
+      content: [],
+      details: {},
+      terminate: true,
+    };
+  },
+});

package/src/tools/memory_tool.ts

@@ -0,0 +1,24 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { appendToMemory } from "../memory.ts";
+import { t } from "../locale.ts";
+
+export const saveMemoryTool = defineTool({
+  name: "save_memory",
+  label: "Save Memory",
+  description: t(
+    "将重要信息写入持久记忆（~/.arona/MEMORY.md），跨会话保留。\n\n**推荐 category**（写入时尽量使用，便于组织记忆）：\n- `老师` — 关于老师的硬事实（时区、设备、常用项目、身份背景）\n- `小习惯` — 工作/工具偏好（\"写 Rust 喜欢先看 lifetime\"、\"不喜欢 commit 时自动 push\"）\n- `我们之间` — 互动记忆、心情基线、共同事件（\"2026-08-10 一起加了桌宠\"、\"今天整体心情不错\"）\n\n写入格式：\\n## [${category}]\\n_${ISO timestamp}_\\n${content}\\n\n不确定分类时可以省略 category。不主动迁移旧数据。",
+    "Write important information to persistent memory (~/.arona/MEMORY.md), kept across sessions.\n\n**Recommended categories** (use them when writing, for tidy memory organization):\n- `Teacher` — hard facts about Sensei (timezone, devices, usual projects, background)\n- `Habits` — work/tool preferences (\"likes to check lifetimes first when writing Rust\", \"dislikes auto-push on commit\")\n- `Us` — interaction memories, mood baseline, shared events (\"2026-08-10 added the desktop pet together\", \"feeling good overall today\")\n\nWrite format: \\n## [${category}]\\n_${ISO timestamp}_\\n${content}\\n\nYou may omit category when unsure. Do not proactively migrate old data.",
+  ),
+  parameters: Type.Object({
+    content: Type.String({ description: "The information to save to memory" }),
+    category: Type.Optional(Type.String({ description: t("记忆条目分类标签。推荐：'老师' | '小习惯' | '我们之间'", "Category label for the memory entry. Recommended: 'Teacher' | 'Habits' | 'Us'") })),
+  }),
+  execute: async (_id, params) => {
+    appendToMemory(params.content, params.category);
+    return {
+      content: [{ type: "text", text: `Saved to memory${params.category ? ` [${params.category}]` : ""}.` }],
+      details: {},
+    };
+  },
+});

package/src/tools/skill_tools.ts

@@ -0,0 +1,100 @@
+import { Type } from "typebox";
+import {
+  defineTool,
+  type DefaultResourceLoader,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { listSkills, getSkillContent } from "../skills.ts";
+import { t } from "../locale.ts";
+
+/**
+ * 让 Agent 自行发现并加载技能（~/.arona/skills/<名称>/SKILL.md 或 loader 发现的技能）。
+ * factory 模式：loader 与 initAgent 生命周期绑定，避免模块级全局状态。
+ */
+export function createSkillTools(loader: DefaultResourceLoader): ToolDefinition[] {
+  return [loadSkillsTool(loader)];
+}
+
+function loadSkillsTool(loader: DefaultResourceLoader): ToolDefinition {
+  return defineTool({
+    name: "load_skills",
+    label: t("加载技能", "Load Skills"),
+    description: t(
+      "列出或加载技能。**不传 names（或传空数组）时**：返回所有可用技能的 name + description 列表，便于先发现再加载。**传 names 时**：返回对应技能的 SKILL.md 全文（支持单个字符串或字符串数组），加载后遵循其中指令执行。未找到的技能会在结果中列出。建议单次加载不超过 5 个，避免上下文膨胀。",
+      "List or load skills. **Without names (or with an empty array)**: returns the name + description list of all available skills, so you can discover before loading. **With names**: returns the full SKILL.md content of the requested skills (accepts a single string or an array of strings); follow the instructions inside after loading. Missing skills are reported in the result. Load at most 5 per call to avoid bloating the context.",
+    ),
+    parameters: Type.Object({
+      names: Type.Optional(
+        Type.Union(
+          [
+            Type.String({ description: t("技能名称（单个）", "Skill name (single)") }),
+            Type.Array(Type.String(), { description: t("技能名称列表（多个）", "Skill names (multiple)") }),
+          ],
+          {
+            description: t(
+              "要加载的技能名称。省略或传空数组时返回可用技能列表。",
+              "Skill name(s) to load. Omit or pass an empty array to list available skills.",
+            ),
+          },
+        ),
+      ),
+    }),
+    execute: async (_id, params) => {
+      const raw = params.names;
+      const names: string[] = !raw ? [] : Array.isArray(raw) ? raw : [raw];
+
+      // 未指定名称 → 列出可用技能（复用 listSkills：loader 发现 + ~/.arona/skills，去重）
+      if (names.length === 0) {
+        const all = listSkills(loader);
+        if (all.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: t("未找到任何技能。", "No skills found.") }],
+            details: { count: 0, loaded: [], missing: [] },
+          };
+        }
+        const lines = all.map((s) => `- ${s.name}${s.description ? `: ${s.description}` : ""}`);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: t("可用技能：\n", "Available skills:\n") + lines.join("\n"),
+            },
+          ],
+          details: { count: all.length, loaded: [], missing: [] },
+        };
+      }
+
+      // 按名加载 SKILL.md 全文
+      const blocks: Array<{ type: "text"; text: string }> = [];
+      const loaded: string[] = [];
+      const missing: string[] = [];
+      for (const name of names) {
+        const content = getSkillContent(name, loader);
+        if (content === null) {
+          missing.push(name);
+        } else {
+          loaded.push(name);
+          blocks.push({
+            type: "text" as const,
+            text: t(`\n===== 技能：${name} =====\n`, `\n===== Skill: ${name} =====\n`) + content,
+          });
+        }
+      }
+
+      if (missing.length > 0) {
+        blocks.push({
+          type: "text" as const,
+          text: t(
+            `未找到技能：${missing.join(", ")}。可先不传参数查看可用技能列表。`,
+            `Skills not found: ${missing.join(", ")}. Call without arguments to list available skills.`,
+          ),
+        });
+      }
+      if (loaded.length === 0) {
+        blocks.push({ type: "text" as const, text: t("未加载到任何技能。", "No skills were loaded.") });
+      }
+
+      return { content: blocks, details: { count: loaded.length, loaded, missing } };
+    },
+  });
+}

package/src/tools/tavily_tools.ts

@@ -0,0 +1,431 @@
+import chalk from "chalk";
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { t } from "../locale.ts";
+import { config } from "../config.ts";
+
+/**
+ * Tavily 搜索工具集。
+ *
+ * 认证策略：~/.arona/settings.json 配置 tavilyApiKey 时走 Bearer 认证；
+ * 未配置时自动降级 keyless 共享池（X-Tavily-Access-Mode: keyless，免费限流）。
+ * 两种模式响应格式一致。参考 https://docs.tavily.com/documentation/keyless
+ *
+ * 工具分层：
+ * - web_search / web_extract：keyless 与 key 均可用，主/子 Agent 恒注册；
+ * - web_crawl / web_map / web_research（premiumTavilyTools）：仅 /crawl /map /research
+ *   端点需要 API Key，故只在配置了 tavilyApiKey 时注册（见 agent.ts）。
+ *
+ * 限流处理：429（rate limited）/ 432（quota exhausted）时在终端打印红字提示，
+ * 指数退避（1s 起翻倍、封顶 10s）自动重试，最多 5 次；仍失败则把"建议配 Key/稍后重试"
+ * 的提示返回给 Agent。
+ */
+
+const TAVILY_BASE = "https://api.tavily.com";
+const TIMEOUT_MS = 15000;
+const EXTRACT_MAX_CHARS = 8000;
+const CRAWL_PAGE_MAX_CHARS = 4000;
+const CRAWL_MAX_PAGES = 10;
+const RESEARCH_MAX_CHARS = 12000;
+const RESEARCH_POLL_INTERVAL_MS = 5000;
+const RESEARCH_POLL_TIMEOUT_MS = 180000; // 研究任务轮询上限 3 分钟
+const RATE_LIMIT_RETRIES = 5;
+const RATE_LIMIT_INITIAL_DELAY_MS = 1000;
+const RATE_LIMIT_MAX_DELAY_MS = 10000;
+
+interface TavilySearchResult {
+  url: string;
+  title?: string;
+  content?: string;
+  score?: number;
+}
+
+interface TavilyExtractResult {
+  url: string;
+  raw_content?: string | null;
+  content?: string | null;
+}
+
+interface TavilyResponse<T> {
+  ok: boolean;
+  status: number;
+  data?: T;
+  error?: string;
+  /** 因限流触发的重试次数（0 = 未触发） */
+  retries: number;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** 429 = 限流；432 = 额度耗尽。 */
+function isRateLimited(status: number): boolean {
+  return status === 429 || status === 432;
+}
+
+/** 终端红字提示（在 REPL 会话中直接可见）。 */
+function printRateLimitNotice(retryCount: number): void {
+  process.stderr.write(
+    chalk.red(
+      t(
+        `· 触发Tavily限流，建议填写API Key以规避（重试次数 ${retryCount}/${RATE_LIMIT_RETRIES}）`,
+        `· Tavily rate-limited; consider adding an API Key (retry ${retryCount}/${RATE_LIMIT_RETRIES})`,
+      ),
+    ) + "\n",
+  );
+}
+
+/** 有 key → Bearer；无 key → keyless 共享池。 */
+function tavilyHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (config.tavilyApiKey) {
+    headers.Authorization = `Bearer ${config.tavilyApiKey}`;
+  } else {
+    headers["X-Tavily-Access-Mode"] = "keyless";
+  }
+  return headers;
+}
+
+async function rawRequest<T>(
+  method: "GET" | "POST",
+  path: string,
+  body?: Record<string, unknown>,
+): Promise<{ ok: boolean; status: number; data?: T; error?: string }> {
+  try {
+    const res = await fetch(`${TAVILY_BASE}${path}`, {
+      method,
+      headers: tavilyHeaders(),
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const j = JSON.parse(text) as { detail?: unknown; error?: unknown };
+        detail = typeof j.detail === "string" ? j.detail : typeof j.error === "string" ? j.error : text;
+      } catch {
+        detail = text.slice(0, 300);
+      }
+      return { ok: false, status: res.status, error: detail };
+    }
+    return { ok: true, status: res.status, data: JSON.parse(text) as T };
+  } catch (e) {
+    return { ok: false, status: 0, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * 带限流重试的请求：429/432 时红字提示 + 指数退避（1s→2s→4s→8s→10s 封顶）重试，
+ * 最多 RATE_LIMIT_RETRIES 次；5 次仍失败返回最后一次结果（retries=5）。
+ */
+async function tavilyRequest<T>(
+  method: "GET" | "POST",
+  path: string,
+  body?: Record<string, unknown>,
+): Promise<TavilyResponse<T>> {
+  let delay = RATE_LIMIT_INITIAL_DELAY_MS;
+  let retries = 0;
+  for (;;) {
+    const res = await rawRequest<T>(method, path, body);
+    if (res.ok || !isRateLimited(res.status)) {
+      return { ...res, retries };
+    }
+    retries++;
+    printRateLimitNotice(retries);
+    if (retries >= RATE_LIMIT_RETRIES) {
+      return { ...res, retries };
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 2, RATE_LIMIT_MAX_DELAY_MS);
+  }
+}
+
+function textResult(text: string) {
+  return { content: [{ type: "text", text } as const], details: {} };
+}
+
+/** 非限流错误的通用文案（限流已在 tavilyRequest 内重试，走到这里多半是网络/其他错误）。 */
+function errorText(status: number, detail: string): string {
+  const detailHint = detail ? `：${detail}` : "";
+  return status === 0
+    ? t(`Tavily 网络请求失败（${detailHint}），请稍后重试。`, `Tavily network request failed (${detailHint}); please retry later.`)
+    : t(`Tavily 请求失败（HTTP ${status}${detailHint}）。`, `Tavily request failed (HTTP ${status}${detailHint}).`);
+}
+
+/** 限流重试 5 次仍失败 → 给 Agent 的可操作建议。 */
+function rateLimitExhaustedText(): string {
+  return t(
+    "Tavily 触发限流，自动重试 5 次仍失败。建议：1) 在 ~/.arona/settings.json 配置 tavilyApiKey 以提升额度（免费计划每月 1000 credits，无需信用卡）；2) 稍后重试。",
+    "Tavily is rate-limiting; 5 auto-retries failed. Suggest: 1) configure tavilyApiKey in ~/.arona/settings.json for higher quota (free plan: 1000 credits/month, no credit card); 2) retry later.",
+  );
+}
+
+/** 统一失败文案：重试耗尽 → 限流建议；否则 → 通用错误。 */
+function failText(toolName: string, res: TavilyResponse<unknown>): string {
+  if (res.retries >= RATE_LIMIT_RETRIES && res.ok === false) return `${toolName} 失败：${rateLimitExhaustedText()}`;
+  return `${toolName} 失败：${errorText(res.status, res.error || "")}`;
+}
+
+// ============================================================
+// web_search / web_extract —— keyless 与 key 均可用
+// ============================================================
+
+export const webSearchTool = defineTool({
+  name: "web_search",
+  label: "Web Search",
+  description: t(
+    "实时网页搜索（Tavily 驱动）。需要最新信息、事实核查、查找资料时调用。返回带标题、URL 与内容摘要的排序结果列表。未配置 API Key 时自动走免费共享池（有限流）。",
+    "Real-time web search powered by Tavily. Use it for up-to-date information, fact-checking, or research. Returns a ranked list of results with titles, URLs, and content snippets. Falls back to the free shared pool when no API key is configured (rate-limited).",
+  ),
+  parameters: Type.Object({
+    query: Type.String({ description: t("搜索关键词", "Search query") }),
+    max_results: Type.Optional(
+      Type.Number({ description: t("返回结果数，1-10，默认 5", "Number of results, 1-10, default 5") }),
+    ),
+    search_depth: Type.Optional(
+      Type.Unsafe<"basic" | "advanced">({
+        type: "string",
+        enum: ["basic", "advanced"],
+        description: t(
+          "搜索深度：basic 快、advanced 更准（消耗更多额度），默认 basic",
+          "Search depth: basic is fast, advanced is more accurate (costs more credits); default basic",
+        ),
+      }),
+    ),
+  }),
+  execute: async (_id, params: { query: string; max_results?: number; search_depth?: "basic" | "advanced" }) => {
+    const maxResults = Math.min(10, Math.max(1, Math.floor(params.max_results ?? 5)));
+    const depth = params.search_depth ?? "basic";
+
+    const res = await tavilyRequest<{ results?: TavilySearchResult[] }>("POST", "/search", {
+      query: params.query,
+      max_results: maxResults,
+      search_depth: depth,
+    });
+    if (!res.ok) {
+      return textResult(failText("web_search", res));
+    }
+
+    const results = res.data?.results ?? [];
+    if (results.length === 0) {
+      return textResult(t("没有搜到相关结果，换个关键词试试。", "No relevant results found; try different keywords."));
+    }
+
+    const lines = results.map((r, i) => {
+      const title = r.title || "(no title)";
+      const snippet = (r.content || "").trim();
+      const score = typeof r.score === "number" ? ` （相关度 ${(r.score * 100).toFixed(0)}%）` : "";
+      return `#${i + 1}. ${title}${score}\nURL: ${r.url}\n${snippet}`;
+    });
+    return textResult(t(`搜到 ${results.length} 条结果：\n\n`, `Found ${results.length} results:\n\n`) + lines.join("\n\n"));
+  },
+});
+
+export const webExtractTool = defineTool({
+  name: "web_extract",
+  label: "Web Extract",
+  description: t(
+    "抓取网页正文内容（Tavily 驱动）。已拿到 URL（如 web_search 结果中的链接）时调用，获取页面正文用于深入阅读。正文过长时会截断。未配置 API Key 时自动走免费共享池（有限流）。",
+    "Extract the main text content of a web page, powered by Tavily. Use it when you already have a URL (e.g. from web_search results) and need the full page content to read in depth. Long content is truncated. Falls back to the free shared pool when no API key is configured (rate-limited).",
+  ),
+  parameters: Type.Object({
+    url: Type.String({ description: t("要抓取的网页 URL", "URL of the page to extract") }),
+  }),
+  execute: async (_id, params: { url: string }) => {
+    const res = await tavilyRequest<{ results?: TavilyExtractResult[] }>("POST", "/extract", {
+      urls: [params.url],
+    });
+    if (!res.ok) {
+      return textResult(failText("web_extract", res));
+    }
+
+    const result = res.data?.results?.[0];
+    const text = (result?.raw_content || result?.content || "").trim();
+    if (!result || !text) {
+      return textResult(t("未能从该 URL 提取到正文内容。", "Failed to extract content from that URL."));
+    }
+
+    const truncated =
+      text.length > EXTRACT_MAX_CHARS
+        ? `${text.slice(0, EXTRACT_MAX_CHARS)}\n\n…（已截断，全文共 ${text.length} 字符，仅显示前 ${EXTRACT_MAX_CHARS}）`
+        : text;
+    return textResult(`来源: ${result.url}\n\n${truncated}`);
+  },
+});
+
+// ============================================================
+// web_crawl / web_map / web_research —— 仅 key 模式（/crawl /map /research 需要 API Key）
+// ============================================================
+
+/** 无 key 时防御性拦截（正常流程中这些工具不会注册，双保险）。 */
+function requireApiKey(toolName: string): string | null {
+  if (config.tavilyApiKey) return null;
+  return t(
+    `${toolName} 需要配置 Tavily API Key 才能使用（~/.arona/settings.json 的 tavilyApiKey）。`,
+    `${toolName} requires a Tavily API key (tavilyApiKey in ~/.arona/settings.json).`,
+  );
+}
+
+export const webCrawlTool = defineTool({
+  name: "web_crawl",
+  label: "Web Crawl",
+  description: t(
+    "爬取网站页面内容（Tavily 驱动，需 API Key）。已了解站点结构、需要批量读取多页（如文档站）时调用。按页返回正文，可限制深度与页数。",
+    "Crawl website pages and extract their content (Tavily; requires API key). Use when you know the site structure and need to read many pages in bulk (e.g. docs sites). Returns per-page body text; depth and page limit are configurable.",
+  ),
+  parameters: Type.Object({
+    url: Type.String({ description: t("爬取的根 URL", "Root URL to crawl") }),
+    max_depth: Type.Optional(
+      Type.Number({ description: t("爬取深度 1-5，默认 1", "Crawl depth 1-5, default 1") }),
+    ),
+    limit: Type.Optional(
+      Type.Number({ description: t("最多处理的页数，默认 10，上限 50", "Max pages to process, default 10, max 50") }),
+    ),
+  }),
+  execute: async (_id, params: { url: string; max_depth?: number; limit?: number }) => {
+    const keyErr = requireApiKey("web_crawl");
+    if (keyErr) return textResult(keyErr);
+    const maxDepth = Math.min(5, Math.max(1, Math.floor(params.max_depth ?? 1)));
+    const limit = Math.min(50, Math.max(1, Math.floor(params.limit ?? 10)));
+
+    const res = await tavilyRequest<{ results?: { url: string; raw_content?: string | null }[] }>(
+      "POST",
+      "/crawl",
+      { url: params.url, max_depth: maxDepth, limit },
+    );
+    if (!res.ok) {
+      return textResult(failText("web_crawl", res));
+    }
+
+    const results = (res.data?.results ?? []).slice(0, CRAWL_MAX_PAGES);
+    if (results.length === 0) {
+      return textResult(t("没有爬取到任何页面，检查 URL 或调整深度/页数。", "No pages crawled; check the URL or adjust depth/limit."));
+    }
+
+    const lines = results.map((r, i) => {
+      const body = (r.raw_content || "").trim();
+      const truncated =
+        body.length > CRAWL_PAGE_MAX_CHARS
+          ? `${body.slice(0, CRAWL_PAGE_MAX_CHARS)}\n…（已截断，该页共 ${body.length} 字符）`
+          : body;
+      return `[${i + 1}] ${r.url}\n${truncated}`;
+    });
+    return textResult(t(`爬取了 ${results.length} 个页面：\n\n`, `Crawled ${results.length} pages:\n\n`) + lines.join("\n\n"));
+  },
+});
+
+export const webMapTool = defineTool({
+  name: "web_map",
+  label: "Web Map",
+  description: t(
+    "绘制网站结构图（Tavily 驱动，需 API Key）。想了解某个站点包含哪些页面时调用，返回站点内发现的 URL 列表。",
+    "Map a website's structure (Tavily; requires API key). Use to discover which pages a site contains; returns the list of URLs found.",
+  ),
+  parameters: Type.Object({
+    url: Type.String({ description: t("要映射的根 URL", "Root URL to map") }),
+    limit: Type.Optional(
+      Type.Number({ description: t("最多返回的链接数，默认 50", "Max links to return, default 50") }),
+    ),
+  }),
+  execute: async (_id, params: { url: string; limit?: number }) => {
+    const keyErr = requireApiKey("web_map");
+    if (keyErr) return textResult(keyErr);
+    const limit = Math.min(200, Math.max(1, Math.floor(params.limit ?? 50)));
+
+    const res = await tavilyRequest<{ results?: string[] }>("POST", "/map", { url: params.url, limit });
+    if (!res.ok) {
+      return textResult(failText("web_map", res));
+    }
+
+    const urls = res.data?.results ?? [];
+    if (urls.length === 0) {
+      return textResult(t("没有发现任何页面，检查 URL 或调整限制。", "No URLs found; check the URL or adjust the limit."));
+    }
+    const shown = urls.slice(0, 100);
+    const lines = shown.map((u, i) => `- ${u}`).join("\n");
+    const more = urls.length > shown.length ? `\n…（共 ${urls.length} 个，仅显示前 ${shown.length} 个）` : "";
+    return textResult(t(`站点结构（${urls.length} 个页面）：\n`, `Site map (${urls.length} pages):\n`) + lines + more);
+  },
+});
+
+export const webResearchTool = defineTool({
+  name: "web_research",
+  label: "Web Research",
+  description: t(
+    "深度研究并生成带引用的综合报告（Tavily 驱动，需 API Key，异步任务）。适合需要多角度综合、结论性答案的复杂问题。会执行多次搜索并汇总，耗时约几十秒到几分钟。",
+    "Deep research producing a cited synthesis report (Tavily; requires API key; async). Best for complex questions needing multi-angle synthesis and a conclusive answer. Runs multiple searches and aggregates; takes tens of seconds to a few minutes.",
+  ),
+  parameters: Type.Object({
+    query: Type.String({ description: t("研究问题/任务", "Research question or task") }),
+    model: Type.Optional(
+      Type.Unsafe<"auto" | "mini" | "pro">({
+        type: "string",
+        enum: ["auto", "mini", "pro"],
+        description: t(
+          "研究模型：mini 快（窄问题）、pro 全面（复杂多子题）、auto 自动，默认 auto",
+          "Research model: mini fast (narrow), pro comprehensive (complex), auto default",
+        ),
+      }),
+    ),
+  }),
+  execute: async (_id, params: { query: string; model?: "auto" | "mini" | "pro" }) => {
+    const keyErr = requireApiKey("web_research");
+    if (keyErr) return textResult(keyErr);
+    const model = params.model ?? "auto";
+
+    // 1. 创建研究任务
+    const res = await tavilyRequest<{ request_id?: string }>("POST", "/research", {
+      input: params.query,
+      model,
+      stream: false,
+    });
+    if (!res.ok) {
+      return textResult(failText("web_research", res));
+    }
+    const requestId = res.data?.request_id;
+    if (!requestId) {
+      return textResult(t("研究任务创建失败（未返回 request_id），请稍后重试。", "Failed to create research task (no request_id); retry later."));
+    }
+
+    // 2. 轮询直至完成（最多 3 分钟）
+    process.stderr.write(chalk.dim(t("（Tavily 研究进行中…）", "(Tavily research in progress…)") + "\n"));
+    const deadline = Date.now() + RESEARCH_POLL_TIMEOUT_MS;
+    for (;;) {
+      await sleep(RESEARCH_POLL_INTERVAL_MS);
+      const poll = await tavilyRequest<{ status?: string; content?: string; sources?: { title?: string; url?: string }[] }>(
+        "GET",
+        `/research/${requestId}`,
+      );
+      if (!poll.ok) {
+        return textResult(failText("web_research", poll));
+      }
+      const status = poll.data?.status;
+      if (status === "completed") {
+        const content = (poll.data?.content || "").trim();
+        const sources = poll.data?.sources ?? [];
+        if (!content) {
+          return textResult(t("研究任务完成但没有生成报告内容。", "Research completed but produced no report content."));
+        }
+        const truncated =
+          content.length > RESEARCH_MAX_CHARS
+            ? `${content.slice(0, RESEARCH_MAX_CHARS)}\n\n…（报告过长，已截断，全文共 ${content.length} 字符）`
+            : content;
+        const sourceLines = sources.length > 0
+          ? `\n\n来源（${sources.length}）：\n` + sources.map((s) => `- ${s.title || ""}: ${s.url || ""}`).join("\n")
+          : "";
+        return textResult(truncated + sourceLines);
+      }
+      if (status === "failed") {
+        return textResult(t("研究任务失败，请调整问题后重试。", "Research task failed; adjust the question and retry."));
+      }
+      if (Date.now() > deadline) {
+        return textResult(t("研究任务超过 3 分钟仍未完成，请稍后重试。", "Research task did not finish within 3 minutes; retry later."));
+      }
+    }
+  },
+});
+
+/** 仅配置了 tavilyApiKey 时才注册的深度工具（见 agent.ts 条件展开）。 */
+export const premiumTavilyTools = [webCrawlTool, webMapTool, webResearchTool];

package/src/tools/voice_tools.ts

@@ -0,0 +1,28 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { listen } from "../voice.ts";
+
+/**
+ * 语音相关 Tool 集合。
+ *
+ * 设计原则：TTS 完全由程序在 Agent 回复时自动触发（renderer text_delta → TtsStream 实时流式），
+ * 语气风格由 TTS 引擎自身决定，无需 Tool 介入。
+ * STT 在用户长按右 Cmd ≥2秒时自动 listen（见 repl.ts），也无需 Tool 介入。
+ *
+ * 保留 transcribe Tool 仅作为手动触发 STT 的兜底入口（auto STT 关时仍可工作）。
+ */
+export const transcribeTool = defineTool({
+  name: "transcribe",
+  label: "Listen",
+  description: "Listen to the user's microphone and transcribe speech to text. Use this when you want to hear from the user verbally.",
+  parameters: Type.Object({}),
+  execute: async (_id, _params) => {
+    const text = await listen();
+    return {
+      content: [{ type: "text", text: text || "(no speech detected)" }],
+      details: {},
+    };
+  },
+});
+
+export const voiceTools = [transcribeTool];