@ai-setting/roy-agent-core 1.7.51 → 1.7.53

package/dist/env/task/types.d.ts

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Task Component Types
+ */
+import { z } from "zod";
+/**
+ * Task status enum
+ */
+export declare const TaskStatusEnum: z.ZodEnum<["todo", "active", "completed", "paused", "cancelled", "archived"]>;
+export type TaskStatus = z.infer<typeof TaskStatusEnum>;
+/**
+ * Task priority enum
+ */
+export declare const TaskPriorityEnum: z.ZodEnum<["low", "medium", "high"]>;
+export type TaskPriority = z.infer<typeof TaskPriorityEnum>;
+/**
+ * Task type enum
+ * - normal: 常规任务，需要跟踪完成
+ * - cycle: 周期任务（如写周报），无需 complete，定期执行
+ * - longterm: 长期任务/愿景目标，无法一次性完成，持续跟进
+ */
+export declare const TaskTypeEnum: z.ZodEnum<["normal", "cycle", "longterm"]>;
+export type TaskType = z.infer<typeof TaskTypeEnum>;
+/**
+ * Action type for task operations
+ */
+export declare const ActionTypeEnum: z.ZodEnum<["create", "progress", "milestone", "problem", "solution", "decision", "review", "completed", "workflow_extracted"]>;
+export type ActionType = z.infer<typeof ActionTypeEnum>;
+/**
+ * Task entity
+ */
+export interface Task {
+    id: number;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    type: TaskType;
+    progress: number;
+    current_status: string;
+    goals_and_expected_deliverables: string;
+    parent_task_id?: number;
+    createdAt: string;
+    updatedAt: string;
+    due_date?: string;
+    tags?: string[];
+    /** Project root path for task positioning */
+    project_path: string;
+    /** JSON string with time-space positioning info (worktree, branch, etc.) */
+    context: string;
+}
+/**
+ * TaskOperation entity — 双维度操作记录（Task #2211 重构后版本）
+ *
+ * 每条 operation 描述任务生命周期中**某一时刻达到的里程碑/状态**
+ * 与**达成该状态所采用的过程概要**——两个维度严格分工：
+ *
+ * 1. **状态/里程碑维度**（"达成的状态/结果"）：
+ *    - `milestoneType`: 里程碑类型（ActionTypeEnum: create/progress/milestone/problem/...）
+ *    - `milestoneTitle`: 里程碑标题（一行）
+ *    - `milestoneDescription`: 达成状态/结果描述
+ *
+ * 2. **过程维度**（"如何达到"）：
+ *    - `processDescription`: 过程概要（采取的策略 + 工具步骤概要，100-150 字符）
+ *
+ * ⚠️ **不要把 action 当状态**，也不要让 process 与 milestone_description 重复。
+ *
+ * ---
+ * **向后兼容**（兼容窗口期，Task #2211 引入）：
+ * - DB 列已重命名为 milestone_* (migration 004)；action_* 列已不存在。
+ * - `actionType/actionTitle/actionDescription` 仍作为本接口的 @deprecated alias 保留，
+ *   通过 getter/setter 自动代理到 milestone_* 字段，保证现有调用方代码不改也能工作。
+ * - 旧调用方应尽快迁移到 milestone_* 主字段。
+ */
+export interface TaskOperation {
+    id: number;
+    taskId: number;
+    sessionId: string;
+    /** 里程碑类型（create / progress / milestone / problem / solution / decision / review / completed / workflow_extracted） */
+    milestoneType: ActionType;
+    /** 里程碑标题（一行） */
+    milestoneTitle: string;
+    /** 状态/结果描述（保留原义，可长可短；过程概要应放在 processDescription） */
+    milestoneDescription: string;
+    /**
+     * 过程概要：采取了什么策略 + 工具步骤达成的概要描述。
+     *
+     * 设计哲学：操作记录只承担节点阶段 milestone 摘要。
+     * 字符范围硬约束 100-150，应用层 schema 校验。
+     * 完整过程通过 sessionId 回查 session。
+     */
+    processDescription: string;
+    timestamp: string;
+    mdPath?: string;
+    /**
+     * @deprecated 旧命名，已重命名为 milestoneType。仍可读写（自动代理），
+     * 旧调用方应尽快迁移到 milestoneType。
+     */
+    actionType?: ActionType;
+    /** @deprecated 已重命名为 milestoneTitle。 */
+    actionTitle?: string;
+    /** @deprecated 已重命名为 milestoneDescription。 */
+    actionDescription?: string;
+}
+/**
+ * TaskTag entity
+ *
+ * Tag 池中的单个 Tag
+ */
+export interface TaskTag {
+    id: number;
+    name: string;
+    createdAt: string;
+    taskCount: number;
+}
+export declare const TaskConfigSchema: z.ZodDefault<z.ZodObject<{
+    storage: z.ZodDefault<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["memory", "sqlite"]>>;
+        dbPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "memory" | "sqlite";
+        dbPath?: string | undefined;
+    }, {
+        type?: "memory" | "sqlite" | undefined;
+        dbPath?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    storage: {
+        type: "memory" | "sqlite";
+        dbPath?: string | undefined;
+    };
+}, {
+    storage?: {
+        type?: "memory" | "sqlite" | undefined;
+        dbPath?: string | undefined;
+    } | undefined;
+}>>;
+export type TaskConfig = z.infer<typeof TaskConfigSchema>;
+export interface CreateTaskOptions {
+    title: string;
+    description?: string;
+    priority?: TaskPriority;
+    type?: TaskType;
+    /**
+     * 父任务 ID（可选）。
+     * - 不传 / undefined / null：创建根任务（root task，无父任务）
+     * - 传 number：作为指定父任务的子任务
+     */
+    parent_task_id?: number | null;
+    goals_and_expected_deliverables?: string;
+    due_date?: string;
+    tags?: string[];
+    sessionId: string;
+    /** Project root path for task positioning. Use 'unknown' if unknown. */
+    project_path: string;
+    /**
+     * JSON string with time-space positioning info.
+     * - For coding tasks: include worktree_path, branch, type
+     * - For other tasks: use '{}' or '{"type":"unknown"}'
+     * Must be a valid JSON string.
+     */
+    context: string;
+}
+export interface UpdateTaskOptions {
+    title?: string;
+    description?: string;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    type?: TaskType;
+    progress?: number;
+    current_status?: string;
+    goals_and_expected_deliverables?: string;
+    due_date?: string;
+    tags?: string[];
+    /** 项目路径，标识任务所属的项目 */
+    project_path?: string;
+    /** 任务上下文信息，用于存储额外上下文 */
+    context?: string;
+    /** 父任务 ID，null = 设为根任务（无父任务） */
+    parent_task_id?: number | null;
+}
+export interface ListTasksOptions {
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    type?: TaskType;
+    parent_task_id?: number;
+    limit?: number;
+    offset?: number;
+    /**
+     * 检索层级深度：
+     * - undefined / null：不做层级过滤（默认行为，向后兼容）
+     * - 0：只查询根任务（`parent_task_id IS NULL`）
+     * - 1：根 + 一层子任务
+     * - 2：根 + 二层子任务，依此类推
+     * - -1 或负数：不限制层级（全部）
+     *
+     * 注意：与 `parent_task_id` 一起使用时，`parent_task_id` 优先
+     * （即深度过滤从指定父节点开始计算）。
+     */
+    depth?: number;
+    /**
+     * 是否包含已归档任务。默认 false（向后兼容）。
+     * 当前 task 系统尚未实现归档字段，保留接口位以便 Phase 5 接入。
+     */
+    include_archived?: boolean;
+}
+export interface CreateOperationOptions {
+    taskId: number;
+    sessionId: string;
+    /** 里程碑类型（主命名，替代旧 actionType） */
+    milestoneType: ActionType;
+    /** 里程碑标题（主命名，替代旧 actionTitle） */
+    milestoneTitle: string;
+    /** 里程碑描述/状态/结果（主命名，替代旧 actionDescription） */
+    milestoneDescription?: string;
+    /**
+     * 过程概要（采取的策略 + 工具步骤），可选；如提供，应用层会校验 100-150 字符。
+     * 字符范围外会由 tool schema 拒绝（不在 DB 层强约束）。
+     */
+    processDescription?: string;
+    mdPath?: string;
+    /**
+     * @deprecated 兼容旧调用方。如提供，自动映射到 milestoneType。
+     * 建议尽快迁移到 milestoneType。
+     */
+    actionType?: ActionType;
+    /** @deprecated 已重命名为 milestoneTitle。 */
+    actionTitle?: string;
+    /** @deprecated 已重命名为 milestoneDescription。 */
+    actionDescription?: string;
+}
+export interface ListOperationsOptions {
+    taskId: number;
+    /** 过滤里程碑类型（主命名） */
+    milestoneType?: ActionType;
+    /** @deprecated 已重命名为 milestoneType。仍可读写，自动代理。 */
+    actionType?: ActionType;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Operation update payload — 兼容 milestone_* 与 action_* 两种字段。
+ *
+ * 双维度：
+ * - milestone_* 字段描述状态/结果
+ * - processDescription 描述过程
+ */
+export interface UpdateOperationOptions {
+    milestoneTitle?: string;
+    milestoneDescription?: string;
+    processDescription?: string;
+    /** @deprecated 已重命名为 milestoneTitle。 */
+    actionTitle?: string;
+    /** @deprecated 已重命名为 milestoneDescription。 */
+    actionDescription?: string;
+}
+/**
+ * 任务列表结果（带分页总数）
+ *
+ * 用于 listTasks / searchTasksByKeywords 等分页接口。
+ * - tasks: 当前页的任务列表
+ * - total: 满足筛选条件的总任务数（分页前）
+ */
+export interface TaskListResult {
+    tasks: Task[];
+    total: number;
+}
+/**
+ * 搜索选项（searchTasksByKeywords 专用）
+ */
+export interface SearchTasksOptions {
+    limit?: number;
+    offset?: number;
+    excludeTaskId?: number;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    type?: TaskType;
+    /**
+     * 检索层级深度（与 ListTasksOptions.depth 语义一致）：
+     * - undefined：不过滤
+     * - 0：只根任务
+     * - 1：根 + 一层子任务
+     * - 2：根 + 二层子任务，依此类推
+     * - -1 或负数：不限制
+     */
+    depth?: number;
+    /**
+     * 是否包含已归档任务。默认 false。
+     */
+    include_archived?: boolean;
+}

package/dist/env/tool/built-in/bash-effect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bash Spawner - Effect 架构实现
+ *
+ * 借鉴 opencode 的 Effect/Scope 架构，实现正确的 stdin 生命周期管理。
+ *
+ * 进程树清理（2026-07 新增）：
+ * - POSIX spawn 使用 `detached: true`，让子 shell 拥有独立的进程组（PGID == shell PID），
+ *   这样 `process.kill(-shell_pid, SIGKILL)` 才能杀进程组（含孙进程）而不误伤父进程组。
+ * - Windows 走 taskkill /F /T 杀进程树，不依赖 detached。
+ * - 若当前在 delegate_task 的 ProcessRegistry 作用域内，bash 启动的 child.pid 会
+ *   自动注册到 registry；child exit 时自动反注册。当外层 task 超时/stop 时
+ *   registry.killAll() 会杀掉所有仍注册的进程（彻底解决"孙进程泄漏"问题）。
+ */
+import { Effect, Context, Layer } from "effect";
+import { spawn as _childProcessSpawn } from "child_process";
+export declare function _setSpawnForTests(s: typeof _childProcessSpawn | undefined): void;
+export interface BashSpawnerOptions {
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+}
+export interface BashSpawnerResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    success: boolean;
+    timedOut: boolean;
+}
+export declare const BashSpawner: Context.Tag<{
+    run(command: string, options?: BashSpawnerOptions): Effect.Effect<BashSpawnerResult>;
+}, {
+    run(command: string, options?: BashSpawnerOptions): Effect.Effect<BashSpawnerResult>;
+}>;
+export declare const BashSpawnerLayer: Layer.Layer<{
+    run(command: string, options?: BashSpawnerOptions): Effect.Effect<BashSpawnerResult>;
+}, never, never>;

package/dist/env/tool/built-in/bash.d.ts

@@ -0,0 +1,16 @@
+import type { Tool } from "../types";
+/**
+ * Bash 工具
+ *
+ * 使用 Effect 架构实现，支持正确的 stdin 生命周期管理。
+ *
+ * 关键特性：
+ * 1. 使用 Effect/Scope 管理进程生命周期
+ * 2. stdin 保持打开直到 Effect 完成
+ * 3. 支持 OpenTelemetry W3C TraceContext 跨进程追踪
+ *
+ * 跨平台兼容：
+ * - Windows: 使用 cmd.exe
+ * - Linux/macOS: 使用 bash
+ */
+export declare const bashTool: Tool;

package/dist/env/tool/built-in/echo.d.ts

@@ -0,0 +1,7 @@
+import type { Tool } from "../types";
+/**
+ * Echo tool - simple echo command
+ *
+ * This is a convenience tool for logging messages in workflows.
+ */
+export declare const echoTool: Tool;

package/dist/env/tool/built-in/edit-file.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "../types";
+/**
+ * 编辑文件工具
+ * 通过 oldString/newString 替换来编辑文件
+ */
+export declare const editFileTool: Tool;

package/dist/env/tool/built-in/glob.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "../types";
+/**
+ * Glob 工具
+ * 文件模式匹配搜索
+ */
+export declare const globTool: Tool;

package/dist/env/tool/built-in/grep.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "../types";
+/**
+ * Grep 工具
+ * 在文件中搜索内容
+ */
+export declare const grepTool: Tool;

package/dist/env/tool/built-in/index.d.ts

@@ -0,0 +1,39 @@
+import type { Tool } from "../types";
+import { bashTool } from "./bash";
+import { echoTool } from "./echo";
+import { globTool } from "./glob";
+import { readFileTool } from "./read-file";
+import { writeFileTool } from "./write-file";
+import { editFileTool } from "./edit-file";
+import { grepTool } from "./grep";
+import { understandImageTool } from "./understand-image";
+import { createQueryBackgroundProcessTool } from "./query-background-process-tool";
+export { bashTool };
+export { echoTool };
+export { globTool };
+export { readFileTool };
+export { writeFileTool };
+export { editFileTool };
+export { grepTool };
+export { understandImageTool };
+import { queryBackgroundProcessTool } from "./query-background-process-tool";
+export { queryBackgroundProcessTool, createQueryBackgroundProcessTool };
+export { setUnderstandImageLLMProvider, getUnderstandImageLLMProvider, resetUnderstandImageLLMProvider, type UnderstandImageLLMProvider, } from "./understand-image";
+/**
+ * 获取所有内置工具
+ *
+ * Note:
+ * - run-workflow tool is not included here because it requires
+ *   a WorkflowService instance which needs to be initialized at runtime.
+ *   Use initRunWorkflowTool(workflowService) to initialize it.
+ * - query_background_process is registered but visible ONLY to the
+ *   "default" agent (via metadata.allowedAgentTypes=["default"]).
+ *   Other agents (roy / strict-task-agent / explore / etc.) won't see it.
+ *   实际使用时 TaskComponent.start() 会用 createQueryBackgroundProcessTool(manager)
+ *   重新注册一个 manager-bound 实例，覆盖此 no-manager 默认版本。
+ */
+export declare function getAllBuiltInTools(): Tool[];
+/**
+ * 获取指定内置工具
+ */
+export declare function getBuiltInTool(name: string): Tool | undefined;

package/dist/env/tool/built-in/query-background-process-tool.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview query_background_process — Default Agent 后台进程查询工具
+ *
+ * 目的：
+ * - 让 default 接待员 agent 可以查询由 `delegate_task` 启动的后台子进程当前状态
+ * - 解决"通知丢失"或"怀疑卡住"时无法判断后台任务真实状态的问题
+ *
+ * 可见性：
+ * - `metadata.allowedAgentTypes: ["default"]` — 只对 default agent 可见
+ * - 其他 agent（roy / strict-task-agent / explore 等）看不到这个工具
+ * - 不需要这个工具的原因是：subagent 自己不会被委托任务，所以也不会去查后台进程
+ *
+ * 注入方式（2026-07 重构）：
+ * - 使用 `createQueryBackgroundProcessTool(manager)` 工厂函数闭包注入
+ * - 每个 Environment/TaskComponent 持有一个独立的 BackgroundTaskManager 引用
+ * - TaskComponent.start() 创建 manager-bound tool 并注册到 ToolComponent
+ * - 多个 Environment 拥有独立的 manager，不会互相覆盖（修复多 Environment 互相 reset 问题）
+ *
+ * Session ownership（2026-07 新增）：
+ * - 工具会校验 ctx.session_id 与 task.parentSessionId 一致
+ * - 不匹配 → 返回 status='not_found'（不暴露存在性）
+ * - 防止 session A 拿 bgProcessId 偷看 session B 的后台任务
+ *
+ * 输入：
+ * - bgProcessId: string  — delegate_task 返回的 background process ID
+ *
+ * 输出（JSON 字符串）：
+ * {
+ *   alive: boolean,
+ *   status: 'running' | 'pending' | 'completed' | 'failed' | 'stopped' | 'timeout' | 'not_found',
+ *   createdAt: number,        // 启动时间戳
+ *   lastUpdatedAt: number,    // 最后状态更新时间戳
+ *   description?: string,     // 任务描述
+ *   result?: any,             // 已完成时返回
+ *   error?: string,           // 失败时返回
+ * }
+ *
+ * 失败行为：
+ * - manager 未注入 → success=false, error="not initialized"
+ * - 参数校验失败 → throw (zod)
+ * - 任务不存在 → success=true, status='not_found'（正常查询结果，不是错误）
+ */
+import type { Tool } from "../types";
+import type { BackgroundTaskManager, BackgroundTask } from "../../task/delegate/delegate-tool";
+/**
+ * 输出 schema（结构化返回，序列化为 JSON 字符串）
+ */
+export interface QueryBackgroundProcessOutput {
+    /** 是否仍在运行（pending/running 视为 alive=true） */
+    alive: boolean;
+    /** 当前状态 */
+    status: BackgroundTask["status"] | "not_found";
+    /** 启动时间戳（毫秒） */
+    createdAt: number;
+    /** 最后状态更新时间戳（毫秒；not_found 时为查询时刻） */
+    lastUpdatedAt: number;
+    /** 任务描述（not_found 时为 undefined） */
+    description?: string;
+    /** 已完成 / 失败 / 停止时的结果 */
+    result?: string;
+    /** 失败时的错误信息 */
+    error?: string;
+}
+/**
+ * 将 BackgroundTask 转成工具输出。
+ *
+ * - alive: status === 'pending' || 'running' → true；其余 → false
+ * - lastUpdatedAt: task.lastUpdatedAt，兼容旧任务时 fallback 到 completedAt/startedAt/createdAt
+ * - description: 总是透传（agent 需要知道是哪个任务）
+ *
+ * 提取为纯函数便于单元测试。
+ */
+export declare function backgroundTaskToOutput(task: BackgroundTask): QueryBackgroundProcessOutput;
+/**
+ * not_found 状态的输出
+ */
+export declare function notFoundOutput(bgProcessId: string): QueryBackgroundProcessOutput;
+/**
+ * query_background_process 工具的"无 manager"实例。
+ *
+ * 历史：这个 named export 原本是 module-global 单例，所有 agent 共享一个 manager 引用。
+ * 重构后（2026-07）：
+ * - 实际注入的 manager 通过 `createQueryBackgroundProcessTool(manager)` 工厂绑定
+ * - 此 named export 仍存在以保持向后兼容（getAllBuiltInTools / 旧测试代码会引用），
+ *   但它绑定的是 null manager → 执行时会返回 "not initialized" 错误
+ * - TaskComponent.start() 会用 `createQueryBackgroundProcessTool(manager)` 重新注册
+ *   真正的实例到 ToolComponent，覆盖此 no-manager 版本
+ *
+ * 用法示例（推荐）：
+ * ```ts
+ * const tool = createQueryBackgroundProcessTool(manager);
+ * toolComponent.register(tool);
+ * ```
+ */
+export declare const queryBackgroundProcessTool: Tool;
+/**
+ * 工厂函数 — 创建 manager-bound 工具实例（2026-07 重构新增）
+ *
+ * 为什么需要工厂：
+ * - 旧模式（setter 全局变量）导致多 Environment/TaskComponent 实例互相覆盖 manager
+ * - 工厂函数将 manager 闭包到工具内部，每个 TaskComponent 创建独立的 tool 实例
+ * - TaskComponent.start() 负责调用此工厂并把生成的 tool 注册到 ToolComponent
+ *
+ * 行为契约：
+ * - manager 有效（getTask 函数存在）→ 正常查询
+ * - manager 为 null/undefined → 返回 success=false, error="not initialized"
+ * - 任务存在但 ctx.session_id 与 task.parentSessionId 不匹配 → 返回 not_found
+ *   （防止跨 session 数据泄露；不暴露存在性）
+ *
+ * @param manager BackgroundTaskManager 实例；传入 null/undefined 表示未注入
+ * @returns 新的 Tool 实例
+ */
+export declare function createQueryBackgroundProcessTool(manager?: BackgroundTaskManager | null): Tool;

package/dist/env/tool/built-in/read-file.d.ts

@@ -0,0 +1,5 @@
+import type { Tool } from "../types";
+/**
+ * 读取文件工具
+ */
+export declare const readFileTool: Tool;

package/dist/env/tool/built-in/understand-image.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview understand_image — 多模态图片理解工具
+ *
+ * 对齐 MCP `understand_image` 工具的入参格式（image_source + prompt），
+ * 但内部走 LLMComponent.invoke() 多模态调用路径。
+ *
+ * 设计取舍：
+ * - 不直接 import LLMComponent（避免循环依赖 + 让单元测试注入 mock 即可）。
+ *   改用模块级 setter（类似 `setToolConfigComponent`），由 AgentComponent 在
+ *   LLMComponent 就绪后注入。
+ * - 不注入 provider 时直接返回错误（fail-loud，避免静默空响应）。
+ * - 图片解析复用 `parseImageInput` (P0)，支持 URL / data:base64 / 本地路径 / @ 前缀。
+ * - 返回多模态 LLM 调用的文本结果。
+ *
+ * 实施位置：core 包内置工具，由 `loadBuiltInTools()` 自动注册到 default 和所有
+ * 声明过 tools 的 agent。
+ */
+import type { Tool } from "../types";
+import type { LLMMessage } from "../../llm/types";
+/**
+ * LLM 调用 provider 函数签名。
+ *
+ * AgentComponent 注入时会包装 LLMComponent.invoke() 调用：
+ *   - 接收 messages[]（已组装为多模态 text + image content）
+ *   - 返回 LLM 的文本响应
+ *   - 不抛错由调用方处理
+ *
+ * 测试中以 mock 替代。
+ */
+export type UnderstandImageLLMProvider = (messages: LLMMessage[]) => Promise<string>;
+/**
+ * 设置 understand_image 工具使用的 LLM provider
+ *
+ * 通常由 AgentComponent 在 LLMComponent 就绪时调用。
+ */
+export declare function setUnderstandImageLLMProvider(provider: UnderstandImageLLMProvider | null): void;
+/**
+ * 读取当前 provider（仅用于测试 / 诊断）。
+ */
+export declare function getUnderstandImageLLMProvider(): UnderstandImageLLMProvider | null;
+/**
+ * 重置 provider（仅用于测试 cleanup）。
+ */
+export declare function resetUnderstandImageLLMProvider(): Promise<void>;
+/**
+ * understand_image 工具
+ *
+ * 使用一个多模态 LLM 来分析图片内容。可用于：
+ * - 看图描述（"What is in this image?"）
+ * - OCR / 图文混排解析
+ * - 视觉问答（VQA）
+ *
+ * 支持的 image_source：
+ * - http(s) URL — 直接传给 LLM
+ * - data:base64 URL — 直接传给 LLM
+ * - 本地文件路径 — readFile 后以 buffer 形式传给 LLM
+ * - `@`-prefixed 路径 — 同上，前缀被剥除
+ */
+export declare const understandImageTool: Tool;

package/dist/env/tool/built-in/write-file.d.ts

@@ -0,0 +1,5 @@
+import type { Tool } from "../types";
+/**
+ * 写入文件工具
+ */
+export declare const writeFileTool: Tool;

package/dist/env/tool/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./types";
+export { ToolComponent } from "./tool-component";
+export type { ToolComponentConfig } from "./tool-component";
+export { setToolConfigComponent, getMaxOutputSize } from "./tool-component";
+export { ToolRegistry } from "./registry";
+export { ToolValidator } from "./validator";
+export { getAllBuiltInTools, getBuiltInTool } from "./built-in";
+export { bashTool } from "./built-in/bash";
+export { echoTool } from "./built-in/echo";
+export { globTool } from "./built-in/glob";
+export { readFileTool } from "./built-in/read-file";
+export { writeFileTool } from "./built-in/write-file";
+export { editFileTool } from "./built-in/edit-file";
+export { grepTool } from "./built-in/grep";
+export { understandImageTool } from "./built-in/understand-image";
+export { setUnderstandImageLLMProvider, getUnderstandImageLLMProvider, resetUnderstandImageLLMProvider, type UnderstandImageLLMProvider, } from "./built-in/understand-image";

package/dist/env/tool/registry.d.ts

@@ -0,0 +1,61 @@
+import type { Tool, ToolRegistration, ToolListFilter } from "./types";
+/**
+ * 工具注册中心
+ * 管理所有已注册的工具
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * 注册工具
+     */
+    register(tool: Tool, registration: ToolRegistration): void;
+    /**
+     * 注销工具
+     */
+    unregister(name: string): boolean;
+    /**
+     * 获取工具
+     */
+    getTool(name: string): ToolRegistration | undefined;
+    /**
+     * 获取所有工具注册信息
+     */
+    getAllTools(): ToolRegistration[];
+    /**
+     * 列出工具（带过滤）
+     */
+    listTools(filter?: ToolListFilter): Tool[];
+    /**
+     * 检查工具是否存在
+     */
+    has(name: string): boolean;
+    /**
+     * 获取工具数量
+     */
+    getCount(): number;
+    /**
+     * 启用工具
+     */
+    enable(name: string): boolean;
+    /**
+     * 禁用工具
+     */
+    disable(name: string): boolean;
+    /**
+     * 清除所有工具
+     */
+    clear(): void;
+    /**
+     * 导出工具注册表快照
+     */
+    snapshot(): ToolRegistration[];
+    /**
+     * 从快照恢复
+     */
+    restore(snapshot: ToolRegistration[]): void;
+    /**
+     * 简单的 glob 模式匹配
+     * 支持 * 匹配任意字符
+     */
+    private matchGlob;
+}