qlogicagent 2.13.4 → 2.13.5

package/dist/skills/tools/worktree-tool.js

@@ -0,0 +1,147 @@
+// ============================================================
+// Worktree Tool — git worktree isolation for parallel development.
+// Reference: claude-code-haha/src/tools/EnterWorktreeTool/EnterWorktreeTool.ts
+//            claude-code-haha/src/tools/ExitWorktreeTool/ExitWorktreeTool.ts
+// Category: system (git)
+// Dependency: #13 AgentTool
+// ============================================================
+export const WORKTREE_TOOL_NAME = "worktree";
+export const WORKTREE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["enter", "exit", "list"],
+            description: "enter: Create and switch to an isolated git worktree branch.\n" +
+                "exit: Leave worktree (keep or remove it).\n" +
+                "list: Show all active worktrees.",
+        },
+        name: {
+            type: "string",
+            description: "Worktree/branch name (for enter). Must be kebab-case, max 64 characters. " +
+                "If omitted, auto-generated from task context.",
+        },
+        exitAction: {
+            type: "string",
+            enum: ["keep", "remove"],
+            description: "For exit: 'keep' retains the worktree for later use; 'remove' deletes it.",
+        },
+        discardChanges: {
+            type: "boolean",
+            description: "Required true to confirm discarding uncommitted changes when exitAction='remove'. " +
+                "Safety mechanism to prevent data loss.",
+        },
+    },
+    required: ["action"],
+};
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]?$/;
+export function createWorktreeTool(deps) {
+    return {
+        name: WORKTREE_TOOL_NAME,
+        label: "Git Worktree",
+        description: "Create isolated git worktree branches for parallel development. " +
+            "Each worktree has its own working directory independent of the main branch. " +
+            "Use for: parallel features, safe experimentation, sub-agent isolation. " +
+            "Exit to keep or remove the worktree when done.",
+        parameters: WORKTREE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            switch (params.action) {
+                case "enter": {
+                    if (deps.isInWorktree()) {
+                        return {
+                            content: [{ type: "text", text: "Error: already in a worktree. Exit first before entering another." }],
+                            details: { type: "worktree", error: "already_in_worktree" },
+                        };
+                    }
+                    if (params.name && !NAME_PATTERN.test(params.name)) {
+                        return {
+                            content: [{ type: "text", text: "Error: name must be kebab-case (a-z, 0-9, hyphens), 2-64 characters." }],
+                            details: { type: "worktree", error: "invalid_name" },
+                        };
+                    }
+                    const result = await deps.enterWorktree(params.name);
+                    if (!result.success) {
+                        return {
+                            content: [{ type: "text", text: `Error: ${result.error || "failed to create worktree"}` }],
+                            details: { type: "worktree", error: result.error },
+                        };
+                    }
+                    const wt = result.worktree;
+                    const lines = [
+                        `Entered worktree: ${wt.name}`,
+                        `  Branch: ${wt.branch}`,
+                        `  Path: ${wt.path}`,
+                        "",
+                        "Working in isolated branch. Changes here do not affect the main branch.",
+                        "Use action='exit' when done (keep or remove).",
+                    ];
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                        details: { type: "worktree", action: "enter", name: wt.name, branch: wt.branch, path: wt.path },
+                    };
+                }
+                case "exit": {
+                    if (!deps.isInWorktree()) {
+                        return {
+                            content: [{ type: "text", text: "Error: not in a worktree." }],
+                            details: { type: "worktree", error: "not_in_worktree" },
+                        };
+                    }
+                    const exitAction = params.exitAction || "keep";
+                    // Safety: require explicit discard confirmation for remove with changes
+                    if (exitAction === "remove") {
+                        const current = deps.currentWorktree?.();
+                        if (current && (current.hasChanges || current.unpushedCommits > 0) && !params.discardChanges) {
+                            const warnings = [];
+                            if (current.hasChanges)
+                                warnings.push("uncommitted changes");
+                            if (current.unpushedCommits > 0)
+                                warnings.push(`${current.unpushedCommits} unpushed commit(s)`);
+                            return {
+                                content: [{ type: "text", text: `Error: worktree has ${warnings.join(" and ")}. Set discardChanges=true to confirm removal, or use exitAction='keep'.` }],
+                                details: { type: "worktree", error: "has_changes", hasChanges: current.hasChanges, unpushedCommits: current.unpushedCommits },
+                            };
+                        }
+                    }
+                    const result = await deps.exitWorktree(exitAction, params.discardChanges);
+                    if (!result.success) {
+                        return {
+                            content: [{ type: "text", text: `Error: ${result.error || "failed to exit worktree"}` }],
+                            details: { type: "worktree", error: result.error },
+                        };
+                    }
+                    const action = exitAction === "keep" ? "Worktree kept for later use." : "Worktree removed.";
+                    return {
+                        content: [{ type: "text", text: `Exited worktree. ${action}\nRestored to: ${result.previousCwd || "main workspace"}` }],
+                        details: { type: "worktree", action: "exit", exitAction, previousCwd: result.previousCwd },
+                    };
+                }
+                case "list": {
+                    const result = await deps.listWorktrees();
+                    if (!result.worktrees || result.worktrees.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No worktrees (only the main working tree)." }],
+                            details: { type: "worktree", action: "list", count: 0 },
+                        };
+                    }
+                    const lines = [`Worktrees (${result.worktrees.length}):`, ""];
+                    for (const wt of result.worktrees) {
+                        const current = wt.isCurrent ? " ← current" : "";
+                        const status = wt.hasChanges ? " (has changes)" : "";
+                        lines.push(`  ${wt.name} [${wt.branch}]${current}${status}`);
+                        lines.push(`    path: ${wt.path}`);
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                        details: { type: "worktree", action: "list", count: result.worktrees.length },
+                    };
+                }
+                default:
+                    return {
+                        content: [{ type: "text", text: `Error: unknown action "${params.action}".` }],
+                        details: { type: "worktree", error: "unknown_action" },
+                    };
+            }
+        },
+    };
+}

package/dist/skills/tools/write-tool.d.ts

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WRITE_TOOL_NAME: "write";
+export interface WriteToolParams {
+    path: string;
+    content: string;
+}
+export declare const WRITE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Absolute path to the file to write.";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Content to write to the file.";
+        };
+    };
+    readonly required: readonly ["path", "content"];
+};
+/** Deps injected by the host runtime for file writing. */
+export interface WriteToolDeps {
+    /** Write content to a file. Create parent dirs as needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Resolve a relative path to absolute. */
+    resolvePath(input: string): string;
+    /**
+     * Check if file has been read before writing (first-read-then-write protection).
+     * Returns null if write is allowed, or a warning message.
+     * If not provided, no protection is applied.
+     */
+    checkReadBeforeWrite?(path: string): string | null;
+    /**
+     * Validate write access for the given path.
+     * Returns null if allowed, or an error message if blocked.
+     */
+    validatePath?(path: string): string | null;
+    /**
+     * Check for concurrent modification before overwriting an existing file.
+     * Returns null if safe to write, or a warning if modified since last read.
+     * If not provided, no concurrent modification check is performed.
+     */
+    checkConcurrentModification?(path: string): string | null;
+}
+export declare function createWriteTool(deps: WriteToolDeps): PortableTool<WriteToolParams>;

package/dist/skills/tools/write-tool.js

@@ -0,0 +1,83 @@
+// ============================================================
+// File Write Tool — create/overwrite files.
+// Reference: claude-code-haha/src/tools/FileWriteTool/FileWriteTool.ts
+// Category: coding
+// ============================================================
+export const WRITE_TOOL_NAME = "write";
+export const WRITE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Absolute path to the file to write.",
+        },
+        content: {
+            type: "string",
+            description: "Content to write to the file.",
+        },
+    },
+    required: ["path", "content"],
+};
+const MAX_WRITE_SIZE = 500_000; // 500KB safety limit
+export function createWriteTool(deps) {
+    return {
+        name: WRITE_TOOL_NAME,
+        label: "Write File",
+        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. " +
+            "Automatically creates parent directories. " +
+            "Prefer edit/patch for modifying existing files (safer than full overwrite). " +
+            "ALWAYS use this tool to create new files — never use shell commands (echo, cat, heredoc) for file creation. " +
+            "Preferred over shell redirection for creating/modifying files.",
+        parameters: WRITE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const resolved = deps.resolvePath(params.path);
+            // Validate path access
+            if (deps.validatePath) {
+                const blocked = deps.validatePath(resolved);
+                if (blocked) {
+                    return {
+                        content: [{ type: "text", text: `Access denied: ${blocked}` }],
+                        details: { type: "write", path: resolved, error: "access_denied" },
+                    };
+                }
+            }
+            // Large file protection
+            if (params.content.length > MAX_WRITE_SIZE) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Content too large (${params.content.length} chars, max ${MAX_WRITE_SIZE}). ` +
+                                "Split into multiple writes or use a different approach.",
+                        }],
+                    details: { type: "write", path: resolved, error: "content_too_large" },
+                };
+            }
+            // First-read-then-write protection
+            if (deps.checkReadBeforeWrite) {
+                const warning = deps.checkReadBeforeWrite(resolved);
+                if (warning) {
+                    return {
+                        content: [{ type: "text", text: warning }],
+                        details: { type: "write", path: resolved, error: "not_read_first" },
+                    };
+                }
+            }
+            // Concurrent modification detection
+            if (deps.checkConcurrentModification) {
+                const conflict = deps.checkConcurrentModification(resolved);
+                if (conflict) {
+                    return {
+                        content: [{ type: "text", text: `Concurrent modification detected: ${conflict}. Re-read the file first.` }],
+                        details: { type: "write", path: resolved, error: "concurrent_modification" },
+                    };
+                }
+            }
+            await deps.writeFile(resolved, params.content);
+            const lineCount = params.content.split("\n").length;
+            return {
+                content: [{ type: "text", text: `Wrote ${lineCount} lines to ${resolved}` }],
+                details: { type: "write", path: resolved, lineCount },
+            };
+        },
+    };
+}

package/dist/skills/tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool registry and compatibility facade.
+ *
+ * The registry is the single source of truth for locally executable tools.
+ * New runtime code should depend on a ToolCatalog/ToolRegistry instance; the
+ * module-level functions below remain as a compatibility facade for older
+ * bootstrap paths while those call sites are migrated.
+ */
+import type { PortableTool } from "./portable-tool.js";
+import type { ToolDefinition } from "../protocol/wire/index.js";
+import { AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, filterToolsForAgent } from "./tool-access.js";
+export { AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, filterToolsForAgent };
+export declare class ToolRegistry {
+    private readonly toolPool;
+    private readonly activatedTools;
+    setTools(tools: PortableTool[]): void;
+    addTool(tool: PortableTool<any>): void;
+    addTools(tools: PortableTool<any>[]): void;
+    removeTool(name: string): boolean;
+    findTool(name: string): PortableTool | undefined;
+    hasTool(name: string): boolean;
+    getToolNames(): string[];
+    getToolCount(): number;
+    executeTool(name: string, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<import("./portable-tool.js").PortableToolResult>;
+    getTools(): PortableTool[];
+    activateTool(name: string): boolean;
+    isToolActivated(name: string): boolean;
+    clearActivatedTools(): void;
+    getToolManifest(includeDeferred?: boolean): ToolDefinition[];
+}
+export declare function getDefaultToolRegistry(): ToolRegistry;
+export declare function setToolPool(tools: PortableTool[]): void;
+export declare function addTool(tool: PortableTool<any>): void;
+export declare function addTools(tools: PortableTool<any>[]): void;
+export declare function removeTool(name: string): boolean;
+export declare function findTool(name: string): PortableTool | undefined;
+export declare function hasTool(name: string): boolean;
+export declare function getToolNames(): string[];
+export declare function getToolCount(): number;
+export declare function executeTool(name: string, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<import("./portable-tool.js").PortableToolResult>;
+export declare function getTools(): PortableTool[];
+export declare function activateTool(name: string): boolean;
+export declare function isToolActivated(name: string): boolean;
+export declare function clearActivatedTools(): void;
+export declare function getToolManifest(includeDeferred?: boolean): ToolDefinition[];

package/dist/skills/tools.js

@@ -0,0 +1,165 @@
+/**
+ * Tool registry and compatibility facade.
+ *
+ * The registry is the single source of truth for locally executable tools.
+ * New runtime code should depend on a ToolCatalog/ToolRegistry instance; the
+ * module-level functions below remain as a compatibility facade for older
+ * bootstrap paths while those call sites are migrated.
+ */
+import { AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, filterToolsForAgent } from "./tool-access.js";
+import { resolveToolRisk } from "../runtime/ports/tool-risk.js";
+// Re-export for consumers
+export { AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, filterToolsForAgent };
+export class ToolRegistry {
+    toolPool = new Map();
+    activatedTools = new Set();
+    setTools(tools) {
+        this.toolPool.clear();
+        this.activatedTools.clear();
+        for (const tool of tools) {
+            this.toolPool.set(tool.name, tool);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addTool(tool) {
+        this.toolPool.set(tool.name, tool);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addTools(tools) {
+        for (const tool of tools)
+            this.addTool(tool);
+    }
+    removeTool(name) {
+        this.activatedTools.delete(name);
+        return this.toolPool.delete(name);
+    }
+    findTool(name) {
+        return this.toolPool.get(name);
+    }
+    hasTool(name) {
+        return this.toolPool.has(name);
+    }
+    getToolNames() {
+        return Array.from(this.toolPool.keys());
+    }
+    getToolCount() {
+        return this.toolPool.size;
+    }
+    async executeTool(name, toolCallId, args, signal) {
+        const tool = this.toolPool.get(name);
+        if (!tool)
+            throw new Error(`Tool not found: ${name}`);
+        return tool.execute(toolCallId, args, signal);
+    }
+    getTools() {
+        return Array.from(this.toolPool.values()).filter(t => t.isEnabled?.() !== false);
+    }
+    activateTool(name) {
+        const tool = this.toolPool.get(name);
+        if (!tool)
+            return false;
+        if (tool.isEnabled?.() === false)
+            return false;
+        this.activatedTools.add(name);
+        return true;
+    }
+    isToolActivated(name) {
+        return this.activatedTools.has(name);
+    }
+    clearActivatedTools() {
+        this.activatedTools.clear();
+    }
+    getToolManifest(includeDeferred = false) {
+        const manifest = [];
+        for (const tool of this.toolPool.values()) {
+            if (tool.isEnabled?.() === false)
+                continue;
+            if (!includeDeferred && tool.shouldDefer && !this.activatedTools.has(tool.name))
+                continue;
+            // Shared core resolver (explicit fields: riskLevel > isDangerous > isReadOnly > isEgress > write)
+            let risk = resolveToolRisk(tool);
+            // Preserve category-based escalation from "write" (site-specific extra logic)
+            if (risk === "write") {
+                if (tool.category === "media" || tool.category === "web" || tool.category === "mcp")
+                    risk = "external_egress";
+                else if (tool.category === "system" || tool.name === "exec" || tool.name === "computer")
+                    risk = "system";
+            }
+            manifest.push({
+                type: "function",
+                function: {
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                },
+                meta: {
+                    category: tool.category ?? "other",
+                    displayName: tool.displayName ?? {
+                        key: `capability.tool.${tool.name}.name`,
+                        fallback: tool.label,
+                    },
+                    displayDescription: tool.displayDescription ?? {
+                        key: `capability.tool.${tool.name}.description`,
+                        fallback: "",
+                    },
+                    parallelSafe: tool.isConcurrencySafe ?? false,
+                    riskLevel: risk,
+                    isReadOnly: risk === "read",
+                    isDangerous: risk === "system",
+                    isDelete: tool.isDelete ?? false,
+                    isEgress: tool.isEgress ?? (risk === "external_egress"),
+                    egressCarriesData: tool.egressCarriesData ?? false,
+                },
+            });
+        }
+        return manifest;
+    }
+}
+const defaultToolRegistry = new ToolRegistry();
+export function getDefaultToolRegistry() {
+    return defaultToolRegistry;
+}
+export function setToolPool(tools) {
+    defaultToolRegistry.setTools(tools);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function addTool(tool) {
+    defaultToolRegistry.addTool(tool);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function addTools(tools) {
+    defaultToolRegistry.addTools(tools);
+}
+export function removeTool(name) {
+    return defaultToolRegistry.removeTool(name);
+}
+export function findTool(name) {
+    return defaultToolRegistry.findTool(name);
+}
+export function hasTool(name) {
+    return defaultToolRegistry.hasTool(name);
+}
+export function getToolNames() {
+    return defaultToolRegistry.getToolNames();
+}
+export function getToolCount() {
+    return defaultToolRegistry.getToolCount();
+}
+export function executeTool(name, toolCallId, args, signal) {
+    return defaultToolRegistry.executeTool(name, toolCallId, args, signal);
+}
+export function getTools() {
+    return defaultToolRegistry.getTools();
+}
+export function activateTool(name) {
+    return defaultToolRegistry.activateTool(name);
+}
+export function isToolActivated(name) {
+    return defaultToolRegistry.isToolActivated(name);
+}
+export function clearActivatedTools() {
+    defaultToolRegistry.clearActivatedTools();
+}
+export function getToolManifest(includeDeferred = false) {
+    return defaultToolRegistry.getToolManifest(includeDeferred);
+}

package/dist/skills/web-search/brave-source.d.ts

@@ -0,0 +1,2 @@
+import type { SourceProvider } from "../../runtime/ports/source-provider.js";
+export declare function createBraveSource(): SourceProvider;

package/dist/skills/web-search/brave-source.js

@@ -0,0 +1,36 @@
+const BRAVE_ID = "brave";
+async function resolveKey() {
+    const { getModelRegistry } = await import("../../runtime/infra/model-registry.js");
+    return getModelRegistry().getTunable("braveApiKey") ?? process.env.BRAVE_API_KEY?.trim();
+}
+export function createBraveSource() {
+    return {
+        id: BRAVE_ID,
+        kind: "serp",
+        capabilities: { semantic: false, freshness: true, domainFilter: false },
+        search: async (query, opts, signal) => {
+            const key = await resolveKey();
+            if (!key)
+                return []; // 可选源:未配置 key → 静默跳过(非错误)
+            const url = new URL("https://api.search.brave.com/res/v1/web/search");
+            url.searchParams.set("q", query);
+            url.searchParams.set("count", String(opts.maxResults ?? 10));
+            if (opts.lang)
+                url.searchParams.set("search_lang", opts.lang);
+            const res = await fetch(url.toString(), {
+                signal,
+                headers: { Accept: "application/json", "X-Subscription-Token": key },
+            });
+            if (!res.ok)
+                throw new Error(`[brave-source] HTTP ${res.status}`);
+            const data = (await res.json());
+            return (data.web?.results ?? []).slice(0, opts.maxResults ?? 10).map((r) => ({
+                title: r.title ?? "",
+                url: r.url ?? "",
+                snippet: r.description ?? "",
+                publishedAt: r.age,
+                source: BRAVE_ID,
+            }));
+        },
+    };
+}

package/dist/skills/web-search/crawl4ai-extractor.d.ts

@@ -0,0 +1,15 @@
+export interface ExtractedContent {
+    content: string;
+    title?: string;
+}
+export interface Crawl4aiExtractor {
+    /** 提取 URL 正文为 markdown;失败/未配置/超时返回 null(让上层回退本地提取)。 */
+    extract(url: string, opts?: {
+        maxChars?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<ExtractedContent | null>;
+    /** 是否已配置 base url(诊断用)。 */
+    isConfigured(): boolean;
+}
+export declare function createCrawl4aiExtractor(): Crawl4aiExtractor;

package/dist/skills/web-search/crawl4ai-extractor.js

@@ -0,0 +1,92 @@
+// L2 正文提取 — Crawl4AI 自托管(Docker,见 deploy/crawl4ai/)。
+// 用浏览器渲染 + 内容过滤产出高信噪比 markdown,替代 tool-bootstrap 的简版 stripHtmlTags。
+// 设计:未配 CRAWL4AI_BASE_URL 或服务不可用/超时 → 返回 null,由上层 fail-loud 回退本地提取(local-first)。
+// 部署蓝图见 docs/agent-search-engine-design.md §13.1(L2 检索层,本地 Docker 同款迁 ECS)。
+import { getModelRegistry } from "../../runtime/infra/model-registry.js";
+/** 读 settings tunable crawl4aiBaseUrl,回退 env CRAWL4AI_BASE_URL;均无则 null(跳过 Crawl4AI)。 */
+function resolveBaseUrl() {
+    const fromTunable = getModelRegistry().getTunable("crawl4aiBaseUrl");
+    const base = (fromTunable ?? process.env.CRAWL4AI_BASE_URL ?? "").trim();
+    return base ? base.replace(/\/+$/, "") : null;
+}
+export function createCrawl4aiExtractor() {
+    return {
+        isConfigured: () => resolveBaseUrl() !== null,
+        async extract(url, opts) {
+            const base = resolveBaseUrl();
+            if (!base)
+                return null; // 未配置 → 跳过,回退本地
+            const timeoutMs = opts?.timeoutMs ?? 20_000;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            // 透传上层 signal(取消时一并中止)
+            const onAbort = () => controller.abort();
+            opts?.signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                const res = await fetch(`${base}/crawl`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        urls: [url],
+                        crawler_config: {
+                            type: "CrawlerRunConfig",
+                            params: {
+                                cache_mode: "bypass",
+                                // PruningContentFilter 按文本/链接密度剪 boilerplate(导航/页脚/侧栏),
+                                // 产出 fit_markdown(实测 runoob 31955→10401 字,顶部导航全去)。
+                                // 未触发过滤的页面 fit_markdown 为空串,pickMarkdown 回退 raw_markdown。
+                                markdown_generator: {
+                                    type: "DefaultMarkdownGenerator",
+                                    params: {
+                                        content_filter: {
+                                            type: "PruningContentFilter",
+                                            params: { threshold: 0.48, threshold_type: "dynamic" },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    }),
+                    signal: controller.signal,
+                });
+                if (!res.ok)
+                    return null;
+                const json = (await res.json());
+                const first = json.results?.[0];
+                if (!first || first.success === false)
+                    return null;
+                const text = pickMarkdown(first.markdown);
+                if (!text)
+                    return null;
+                const sliced = opts?.maxChars && text.length > opts.maxChars ? text.slice(0, opts.maxChars) : text;
+                const title = typeof first.metadata?.title === "string" ? first.metadata.title : undefined;
+                return { content: sliced, title };
+            }
+            catch {
+                return null; // 网络/超时/解析失败 → 回退本地
+            }
+            finally {
+                clearTimeout(timer);
+                opts?.signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}
+/**
+ * fit_markdown(内容过滤去 boilerplate)优先,回退 raw_markdown / 带引用版 / 字符串形态。
+ * 注意:Crawl4AI 未配 content filter 时 fit_markdown 是空串 ""(非 null),
+ * 故必须显式找"第一个非空"变体,不能用 ?? (?? 对空串不回退)。
+ */
+function pickMarkdown(md) {
+    if (typeof md === "string")
+        return md.trim();
+    if (md && typeof md === "object") {
+        const o = md;
+        for (const key of ["fit_markdown", "raw_markdown", "markdown_with_citations"]) {
+            const v = o[key];
+            if (typeof v === "string" && v.trim().length > 0)
+                return v.trim();
+        }
+    }
+    return "";
+}

package/dist/skills/web-search/embedding-rerank.d.ts

@@ -0,0 +1,13 @@
+import type { RawHit } from "../../runtime/ports/source-provider.js";
+import type { EmbeddingProvider } from "../memory/local-embedding.js";
+export interface Reranker {
+    /** 按 query 语义相关性重排 hits;失败/无模型时返回原序(fail-loud,不破坏召回)。 */
+    rerank(query: string, hits: RawHit[]): Promise<RawHit[]>;
+}
+export interface EmbeddingRerankerDeps {
+    /** embedding provider 工厂(调用方注入,可异步懒解析)。dimensions=0 视为无模型 → 原序。 */
+    getProvider: () => EmbeddingProvider | Promise<EmbeddingProvider>;
+    /** 每条 hit 文本(title+snippet)最大字符,控 token。默认 512。 */
+    maxTextChars?: number;
+}
+export declare function createEmbeddingReranker(deps: EmbeddingRerankerDeps): Reranker;