scientify 1.6.0 → 1.6.2

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAkBlD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAiFtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAqBlD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAoFtD"}

package/dist/index.js

@@ -3,6 +3,9 @@ import { handleResearchStatus, handlePapers, handleIdeas, handleProjects, handle
 import { createArxivSearchTool } from "./src/tools/arxiv-search.js";
 import { createArxivDownloadTool } from "./src/tools/arxiv-download.js";
 import { createGithubSearchTool } from "./src/tools/github-search-tool.js";
+import { createPaperBrowserTool } from "./src/tools/paper-browser.js";
+import { createOpenAlexSearchTool } from "./src/tools/openalex-search.js";
+import { createUnpaywallDownloadTool } from "./src/tools/unpaywall-download.js";
 import { createAutoUpdaterService } from "./src/services/auto-updater.js";
 import { createSkillInjectionHook } from "./src/hooks/inject-skill.js";
 // Default: check every hour
@@ -12,6 +15,9 @@ export default function register(api) {
     api.registerTool(createArxivSearchTool());
     api.registerTool(createArxivDownloadTool());
     api.registerTool(createGithubSearchTool());
+    api.registerTool(createPaperBrowserTool());
+    api.registerTool(createOpenAlexSearchTool());
+    api.registerTool(createUnpaywallDownloadTool());
     // Register auto-updater service (silent updates)
     const pluginConfig = api.pluginConfig;
     const autoUpdateEnabled = pluginConfig?.autoUpdate !== false; // enabled by default

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/openalex-search.d.ts

@@ -0,0 +1,26 @@
+export declare const OpenAlexSearchToolSchema: import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    filter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare function createOpenAlexSearchTool(): {
+    label: string;
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TString;
+        max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        filter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (_toolCallId: string, rawArgs: unknown) => Promise<{
+        type: "tool_result";
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: boolean;
+    }>;
+};
+//# sourceMappingURL=openalex-search.d.ts.map

package/dist/src/tools/openalex-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openalex-search.d.ts","sourceRoot":"","sources":["../../../src/tools/openalex-search.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,wBAAwB;;;;;EAqBnC,CAAC;AA4DH,wBAAgB,wBAAwB;;;;;;;;;;2BAOP,MAAM,WAAW,OAAO;;;;;;;;EA0ExD"}

package/dist/src/tools/openalex-search.js

@@ -0,0 +1,123 @@
+import { Type } from "@sinclair/typebox";
+import { Result } from "./result.js";
+const OPENALEX_API = "https://api.openalex.org/works";
+const DEFAULT_MAX_RESULTS = 20;
+const MAX_RESULTS_LIMIT = 100;
+export const OpenAlexSearchToolSchema = Type.Object({
+    query: Type.String({
+        description: "Search query for academic works (papers, articles). Can search by title, abstract, author, or keywords.",
+    }),
+    max_results: Type.Optional(Type.Number({
+        description: "Maximum number of results (1-100). Default: 20.",
+        minimum: 1,
+        maximum: MAX_RESULTS_LIMIT,
+    })),
+    filter: Type.Optional(Type.String({
+        description: 'Optional filter string (e.g., "publication_year:2020-2024", "type:journal-article", "is_oa:true"). See OpenAlex docs for filter syntax.',
+    })),
+    sort: Type.Optional(Type.String({
+        description: 'Sort by: "cited_by_count" (most cited), "publication_date" (newest first), or "relevance_score" (default).',
+    })),
+});
+function readStringParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null) {
+        if (opts?.required) {
+            throw new Error(`Missing required parameter: ${key}`);
+        }
+        return undefined;
+    }
+    return String(value);
+}
+function readNumberParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null)
+        return undefined;
+    const num = Number(value);
+    if (isNaN(num))
+        return undefined;
+    return opts?.integer ? Math.floor(num) : num;
+}
+function reconstructAbstract(invertedIndex) {
+    if (!invertedIndex)
+        return "";
+    const words = [];
+    for (const [word, positions] of Object.entries(invertedIndex)) {
+        for (const pos of positions) {
+            words.push([word, pos]);
+        }
+    }
+    words.sort((a, b) => a[1] - b[1]);
+    return words.map(([word]) => word).join(" ").substring(0, 500); // Limit to 500 chars
+}
+export function createOpenAlexSearchTool() {
+    return {
+        label: "OpenAlex Search",
+        name: "openalex_search",
+        description: "Search for academic papers across all disciplines using OpenAlex API. Returns paper metadata including DOI, authors, citations, and open access status. More comprehensive than arXiv (covers all fields, not just STEM).",
+        parameters: OpenAlexSearchToolSchema,
+        execute: async (_toolCallId, rawArgs) => {
+            const params = rawArgs;
+            const query = readStringParam(params, "query", { required: true });
+            const maxResults = Math.min(readNumberParam(params, "max_results", { integer: true }) ?? DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT);
+            const filterStr = readStringParam(params, "filter");
+            const sortStr = readStringParam(params, "sort") ?? "relevance_score";
+            // Build URL parameters
+            const urlParams = new URLSearchParams({
+                search: query,
+                per_page: String(maxResults),
+                mailto: "research@openclaw.ai", // Polite pool for higher rate limits
+            });
+            if (filterStr) {
+                urlParams.set("filter", filterStr);
+            }
+            // Map sort parameter
+            const sortMapping = {
+                cited_by_count: "cited_by_count:desc",
+                publication_date: "publication_date:desc",
+                relevance_score: "relevance_score:desc",
+            };
+            urlParams.set("sort", sortMapping[sortStr] || sortMapping.relevance_score);
+            const url = `${OPENALEX_API}?${urlParams.toString()}`;
+            let response;
+            try {
+                response = await fetch(url, {
+                    headers: {
+                        "User-Agent": "scientify-research-agent/1.0 (mailto:research@openclaw.ai)",
+                    },
+                });
+            }
+            catch (error) {
+                return Result.err("network_error", `Failed to reach OpenAlex API: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (response.status === 429) {
+                return Result.err("rate_limited", "OpenAlex API rate limit exceeded. Please wait a moment and retry.");
+            }
+            if (!response.ok) {
+                return Result.err("api_error", `OpenAlex API returned ${response.status}: ${response.statusText}`);
+            }
+            const data = (await response.json());
+            const works = (data.results ?? []).map((work) => ({
+                id: work.id.replace("https://openalex.org/", ""), // Clean ID
+                title: work.title || "Untitled",
+                doi: work.doi?.replace("https://doi.org/", "") || null,
+                year: work.publication_year,
+                date: work.publication_date,
+                type: work.type,
+                authors: work.authorships.slice(0, 5).map((a) => a.author.display_name), // First 5 authors
+                venue: work.primary_location?.source?.display_name || "Unknown",
+                cited_by: work.cited_by_count,
+                is_open_access: work.open_access.is_oa,
+                oa_url: work.open_access.oa_url,
+                abstract_preview: reconstructAbstract(work.abstract_inverted_index),
+            }));
+            return Result.ok({
+                query,
+                total_count: data.meta?.count ?? 0,
+                returned: works.length,
+                works,
+            });
+        },
+    };
+}
+//# sourceMappingURL=openalex-search.js.map

package/dist/src/tools/openalex-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openalex-search.js","sourceRoot":"","sources":["../../../src/tools/openalex-search.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/paper-browser.d.ts

@@ -0,0 +1,24 @@
+export declare const PaperBrowserToolSchema: import("@sinclair/typebox").TObject<{
+    file_path: import("@sinclair/typebox").TString;
+    start_line: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    num_lines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare function createPaperBrowserTool(): {
+    label: string;
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        file_path: import("@sinclair/typebox").TString;
+        start_line: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        num_lines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>;
+    execute: (_toolCallId: string, rawArgs: unknown) => Promise<{
+        type: "tool_result";
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: boolean;
+    }>;
+};
+//# sourceMappingURL=paper-browser.d.ts.map

package/dist/src/tools/paper-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper-browser.d.ts","sourceRoot":"","sources":["../../../src/tools/paper-browser.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB;;;;EAiBjC,CAAC;AAqBH,wBAAgB,sBAAsB;;;;;;;;;2BAOL,MAAM,WAAW,OAAO;;;;;;;;EAuFxD"}

package/dist/src/tools/paper-browser.js

@@ -0,0 +1,121 @@
+import { Type } from "@sinclair/typebox";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { Result } from "./result.js";
+const DEFAULT_VIEWPORT_SIZE = 100;
+const MAX_VIEWPORT_SIZE = 500;
+export const PaperBrowserToolSchema = Type.Object({
+    file_path: Type.String({
+        description: "Path to the paper file (.tex, .md, or any text file).",
+    }),
+    start_line: Type.Optional(Type.Number({
+        description: "Starting line number (1-indexed). Default: 1.",
+        minimum: 1,
+    })),
+    num_lines: Type.Optional(Type.Number({
+        description: `Number of lines to display (default: ${DEFAULT_VIEWPORT_SIZE}, max: ${MAX_VIEWPORT_SIZE}).`,
+        minimum: 1,
+        maximum: MAX_VIEWPORT_SIZE,
+    })),
+});
+function readStringParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null) {
+        if (opts?.required) {
+            throw new Error(`Missing required parameter: ${key}`);
+        }
+        return undefined;
+    }
+    return String(value);
+}
+function readNumberParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null)
+        return undefined;
+    const num = Number(value);
+    if (isNaN(num))
+        return undefined;
+    return opts?.integer ? Math.floor(num) : num;
+}
+export function createPaperBrowserTool() {
+    return {
+        label: "Paper Browser",
+        name: "paper_browser",
+        description: "Read large paper files (.tex, .md) in paginated chunks. Use this to avoid loading entire multi-thousand-line files into context at once. Returns a viewport of lines with navigation information.",
+        parameters: PaperBrowserToolSchema,
+        execute: async (_toolCallId, rawArgs) => {
+            const params = rawArgs;
+            const filePath = readStringParam(params, "file_path", { required: true });
+            const startLine = Math.max(1, readNumberParam(params, "start_line", { integer: true }) ?? 1);
+            const numLines = Math.min(readNumberParam(params, "num_lines", { integer: true }) ?? DEFAULT_VIEWPORT_SIZE, MAX_VIEWPORT_SIZE);
+            // Validate file exists
+            if (!existsSync(filePath)) {
+                return Result.err("file_not_found", `File does not exist: ${filePath}`);
+            }
+            // Check if it's a file (not directory)
+            let stats;
+            try {
+                stats = statSync(filePath);
+            }
+            catch (error) {
+                return Result.err("file_error", `Cannot access file: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!stats.isFile()) {
+                return Result.err("not_a_file", `Path is not a file: ${filePath}`);
+            }
+            // Read file content
+            let content;
+            try {
+                content = readFileSync(filePath, "utf-8");
+            }
+            catch (error) {
+                return Result.err("read_error", `Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Split into lines
+            const lines = content.split("\n");
+            const totalLines = lines.length;
+            // Validate start line
+            if (startLine > totalLines) {
+                return Result.err("invalid_range", `Start line ${startLine} exceeds total lines ${totalLines}`);
+            }
+            // Extract viewport
+            const endLine = Math.min(startLine + numLines - 1, totalLines);
+            const viewportLines = lines.slice(startLine - 1, endLine);
+            // Add line numbers (matching cat -n format for consistency with Read tool)
+            const numberedLines = viewportLines
+                .map((line, idx) => {
+                const lineNum = startLine + idx;
+                return `${lineNum.toString().padStart(6, " ")}\t${line}`;
+            })
+                .join("\n");
+            // Navigation hints
+            const hasMore = endLine < totalLines;
+            const hasPrev = startLine > 1;
+            let navigationHint = "";
+            if (hasMore && hasPrev) {
+                navigationHint = `\n\nNavigate: paper_browser({ file_path: "${filePath}", start_line: ${endLine + 1} }) for next page, or start_line: ${Math.max(1, startLine - numLines)} for previous page.`;
+            }
+            else if (hasMore) {
+                navigationHint = `\n\nMore content below. Use: paper_browser({ file_path: "${filePath}", start_line: ${endLine + 1} })`;
+            }
+            else if (hasPrev) {
+                navigationHint = `\n\nEnd of file. Use: paper_browser({ file_path: "${filePath}", start_line: ${Math.max(1, startLine - numLines)} }) for previous page.`;
+            }
+            else {
+                navigationHint = "\n\n[End of file]";
+            }
+            return Result.ok({
+                file_path: filePath,
+                total_lines: totalLines,
+                viewport: {
+                    start_line: startLine,
+                    end_line: endLine,
+                    num_lines: viewportLines.length,
+                },
+                content: numberedLines + navigationHint,
+                has_more: hasMore,
+                has_prev: hasPrev,
+            });
+        },
+    };
+}
+//# sourceMappingURL=paper-browser.js.map

package/dist/src/tools/paper-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper-browser.js","sourceRoot":"","sources":["../../../src/tools/paper-browser.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/unpaywall-download.d.ts

@@ -0,0 +1,22 @@
+export declare const UnpaywallDownloadToolSchema: import("@sinclair/typebox").TObject<{
+    dois: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    output_dir: import("@sinclair/typebox").TString;
+}>;
+export declare function createUnpaywallDownloadTool(): {
+    label: string;
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        dois: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        output_dir: import("@sinclair/typebox").TString;
+    }>;
+    execute: (_toolCallId: string, rawArgs: unknown) => Promise<{
+        type: "tool_result";
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: boolean;
+    }>;
+};
+//# sourceMappingURL=unpaywall-download.d.ts.map

package/dist/src/tools/unpaywall-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpaywall-download.d.ts","sourceRoot":"","sources":["../../../src/tools/unpaywall-download.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,2BAA2B;;;EAStC,CAAC;AAqDH,wBAAgB,2BAA2B;;;;;;;;2BAOV,MAAM,WAAW,OAAO;;;;;;;;EAgIxD"}

package/dist/src/tools/unpaywall-download.js

@@ -0,0 +1,169 @@
+import { Type } from "@sinclair/typebox";
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Result } from "./result.js";
+const UNPAYWALL_API = "https://api.unpaywall.org/v2";
+const USER_EMAIL = "research@openclaw.ai"; // Required by Unpaywall
+export const UnpaywallDownloadToolSchema = Type.Object({
+    dois: Type.Array(Type.String(), {
+        description: "List of DOIs to download (e.g., ['10.1038/s41586-021-03819-2']). Maximum 20 DOIs per request.",
+        minItems: 1,
+        maxItems: 20,
+    }),
+    output_dir: Type.String({
+        description: "Absolute path to output directory where PDFs will be saved.",
+    }),
+});
+function readStringParam(params, key, opts) {
+    const value = params[key];
+    if (value === undefined || value === null) {
+        if (opts?.required) {
+            throw new Error(`Missing required parameter: ${key}`);
+        }
+        return undefined;
+    }
+    return String(value);
+}
+async function downloadPDF(url, outputPath) {
+    try {
+        const response = await fetch(url, {
+            headers: {
+                "User-Agent": "scientify-research-agent/1.0 (mailto:research@openclaw.ai)",
+            },
+            redirect: "follow",
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const contentType = response.headers.get("content-type") || "";
+        if (!contentType.includes("pdf") && !contentType.includes("octet-stream")) {
+            // Not a PDF, might be HTML landing page
+            return false;
+        }
+        const buffer = await response.arrayBuffer();
+        writeFileSync(outputPath, Buffer.from(buffer));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createUnpaywallDownloadTool() {
+    return {
+        label: "Unpaywall Download",
+        name: "unpaywall_download",
+        description: "Download open access PDFs using Unpaywall API. Provide DOIs and output directory. Non-OA papers will be skipped with error captured (no failure). Returns list of successfully downloaded papers.",
+        parameters: UnpaywallDownloadToolSchema,
+        execute: async (_toolCallId, rawArgs) => {
+            const params = rawArgs;
+            const doisRaw = params.dois;
+            if (!Array.isArray(doisRaw) || doisRaw.length === 0) {
+                return Result.err("invalid_input", "dois must be a non-empty array");
+            }
+            const dois = doisRaw.map((d) => String(d).trim()).filter((d) => d.length > 0);
+            const outputDir = readStringParam(params, "output_dir", { required: true });
+            const resolvedOutputDir = resolve(outputDir);
+            // Create output directory if it doesn't exist
+            try {
+                if (!existsSync(resolvedOutputDir)) {
+                    mkdirSync(resolvedOutputDir, { recursive: true });
+                }
+            }
+            catch (error) {
+                return Result.err("filesystem_error", `Failed to create output directory: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const results = [];
+            let successCount = 0;
+            let notOACount = 0;
+            let failedCount = 0;
+            // Process each DOI
+            for (const doi of dois) {
+                try {
+                    // Query Unpaywall API
+                    const apiUrl = `${UNPAYWALL_API}/${encodeURIComponent(doi)}?email=${USER_EMAIL}`;
+                    const response = await fetch(apiUrl, {
+                        headers: {
+                            "User-Agent": "scientify-research-agent/1.0 (mailto:research@openclaw.ai)",
+                        },
+                    });
+                    if (!response.ok) {
+                        results.push({
+                            doi,
+                            status: "api_error",
+                            message: `API error: ${response.status} ${response.statusText}`,
+                        });
+                        failedCount++;
+                        continue;
+                    }
+                    const data = (await response.json());
+                    // Check if OA available
+                    if (!data.is_oa || !data.best_oa_location) {
+                        results.push({
+                            doi,
+                            status: "not_oa",
+                            message: "Paper is not open access",
+                            title: data.title,
+                        });
+                        notOACount++;
+                        continue;
+                    }
+                    // Get PDF URL
+                    const pdfUrl = data.best_oa_location.url_for_pdf || data.best_oa_location.url;
+                    if (!pdfUrl) {
+                        results.push({
+                            doi,
+                            status: "no_pdf_url",
+                            message: "No PDF URL available",
+                            title: data.title,
+                        });
+                        failedCount++;
+                        continue;
+                    }
+                    // Download PDF
+                    const sanitizedDoi = doi.replace(/[\/\\:]/g, "_");
+                    const filename = `${sanitizedDoi}.pdf`;
+                    const outputPath = join(resolvedOutputDir, filename);
+                    const downloaded = await downloadPDF(pdfUrl, outputPath);
+                    if (downloaded) {
+                        results.push({
+                            doi,
+                            status: "success",
+                            message: "Downloaded successfully",
+                            file_path: outputPath,
+                            title: data.title,
+                        });
+                        successCount++;
+                    }
+                    else {
+                        results.push({
+                            doi,
+                            status: "download_failed",
+                            message: "Failed to download PDF (might be HTML landing page or access denied)",
+                            title: data.title,
+                        });
+                        failedCount++;
+                    }
+                }
+                catch (error) {
+                    results.push({
+                        doi,
+                        status: "api_error",
+                        message: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                    failedCount++;
+                }
+                // Rate limiting: sleep 100ms between requests
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            return Result.ok({
+                total: dois.length,
+                success: successCount,
+                not_oa: notOACount,
+                failed: failedCount,
+                output_dir: resolvedOutputDir,
+                results,
+            });
+        },
+    };
+}
+//# sourceMappingURL=unpaywall-download.js.map

package/dist/src/tools/unpaywall-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpaywall-download.js","sourceRoot":"","sources":["../../../src/tools/unpaywall-download.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scientify",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Scientify - AI-powered research workflow automation for OpenClaw. Includes idea generation, literature review, research pipeline skills, and arxiv tool.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,16 +29,6 @@
   "bugs": {
     "url": "https://github.com/tsingyuai/scientify/issues"
   },
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "dev": "tsc --watch",
-    "dev:link": "npm run build && rm -rf ~/.openclaw/extensions/scientify && ln -sfn \"$(pwd)\" ~/.openclaw/extensions/scientify",
-    "dev:unlink": "rm -f ~/.openclaw/extensions/scientify",
-    "dev:reload": "nodemon --watch src --watch skills --ext ts,md,json --exec \"npm run build && pkill -USR1 -f 'openclaw.mjs gateway' || true\" --delay 500ms",
-    "prepublishOnly": "npm run clean && npm run build",
-    "release": "npm version patch && git push && git push --tags"
-  },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
@@ -61,5 +51,14 @@
     "extensions": [
       "./dist/index.js"
     ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "dev:link": "npm run build && rm -rf ~/.openclaw/extensions/scientify && ln -sfn \"$(pwd)\" ~/.openclaw/extensions/scientify",
+    "dev:unlink": "rm -f ~/.openclaw/extensions/scientify",
+    "dev:reload": "nodemon --watch src --watch skills --ext ts,md,json --exec \"npm run build && pkill -USR1 -f 'openclaw.mjs gateway' || true\" --delay 500ms",
+    "release": "npm version patch && git push && git push --tags"
   }
-}
+}

package/skills/literature-survey/SKILL.md

@@ -114,12 +114,25 @@ arxiv_download({
 - 核心方法名 + 作者名
 - 论文中提到的数据集名 + 任务名
 
-使用 `web_search` 或 `exec` 调用 GitHub API：
-```bash
-# 示例：
-web_search({ query: "{paper_title} implementation github" })
+使用 `github_search` 工具：
+```javascript
+// 示例：
+github_search({
+  query: "{paper_title} implementation",
+  max_results: 10,
+  sort: "stars",
+  language: "python"  // 可选：根据论文领域选择语言
+})
+
+// 如果有具体方法名：
+github_search({
+  query: "{method_name} {author_last_name}",
+  max_results: 5
+})
 ```
 
+**提示**：如果需要 GitHub API 高频率限制，设置环境变量 `GITHUB_TOKEN`。
+
 #### 3.3 筛选与 clone
 
 对搜索到的仓库，评估：

package/skills/research-review/SKILL.md

@@ -96,6 +96,31 @@ metadata:
 | Loss 合理 | 非 NaN/Inf，有下降趋势（epoch 1 loss > epoch 2 loss） |
 | 数据管道匹配 plan | 对比 plan Dataset Plan vs `data/` 实现，batch size、预处理步骤一致 |
 
+#### D. 性能初步评估
+
+**⚠️ 关键新增 — 防止"代码正确但效果很差"的算法被放行。**
+
+从 `ml_res.md` 提取 2 epoch 验证结果，评估算法有效性：
+
+| 检查项 | 判定标准 | 诊断 |
+|--------|----------|------|
+| **Loss 下降幅度** | 计算 `reduction = (epoch1_loss - epoch2_loss) / epoch1_loss * 100%` | <5% → 可能学习率过小、架构有问题或数据未正确处理 |
+| **Loss 稳定性** | 检查 epoch 1 和 epoch 2 的 loss 波动 | 震荡 >20% → 可能学习率过大或 batch size 不当 |
+| **Metrics 合理性** | 对比任务的随机 baseline（分类: 1/num_classes，回归: 数据方差） | 接近随机（±10%）→ 模型未真正学习，可能特征无效或架构过简单 |
+| **与 plan 预期对比** | 如果 plan_res.md 中有性能预期，对比实际结果 | 低于预期 30% → 需要反思算法设计或超参数设置 |
+
+**性能异常的常见原因**：
+
+| 症状 | 可能原因 | 验证方法 |
+|------|----------|----------|
+| Loss 几乎不变（<2%） | 学习率过小 | 检查 plan_res.md 中 lr 值，对比 survey_res.md 中 baseline lr |
+| Loss 震荡剧烈（>30%） | 学习率过大 | 同上 |
+| Loss 下降但 metric 不变 | 模型过简单或特征无效 | 检查模型参数量；检查数据预处理是否正确（归一化、标准化） |
+| Accuracy 接近随机 | 数据标签错误或未正确加载 | 重新验证数据加载代码，打印样本检查 |
+| Loss=NaN/Inf | 梯度爆炸、数值不稳定 | 检查是否有 Batch/Layer Normalization；检查 lr 是否过大 |
+
+**如果发现性能异常，标记 `verdict: NEEDS_ALGORITHM_REVIEW`（不同于 NEEDS_REVISION）。**
+
 ### Step 4: 写入审查报告
 
 写入 `$W/iterations/judge_v1.md`：
@@ -103,7 +128,7 @@ metadata:
 ```markdown
 # Review v1
 
-## Verdict: PASS / NEEDS_REVISION
+## Verdict: PASS / NEEDS_REVISION / NEEDS_ALGORITHM_REVIEW
 
 ## Checklist
 
@@ -131,12 +156,45 @@ metadata:
 - [x/✗] Training loop proper (loss decreasing)
 - [x/✗] Results are from real execution (not fabricated)
 
+### 性能初步评估（新增）
+
+**2-Epoch Validation Results** (from `ml_res.md`):
+- Epoch 1 loss: {value}
+- Epoch 2 loss: {value}
+- Loss reduction: {percent}% (expected: >10% for initial epochs)
+- Metric (e.g., accuracy): {value} (random baseline: {baseline_value})
+
+**Performance Assessment**:
+- [x/✗] Loss decreasing adequately (reduction >5%)
+- [x/✗] Metrics above random baseline (+10% or more)
+- [x/✗] No severe oscillation (<20% variance)
+- [x/✗] Meets plan expectations (if performance target specified in plan_res.md)
+
+**Diagnosis** (if performance issues):
+- **Symptom**: {what's wrong - e.g., "Loss reduction only 0.9%, far below 10% expected"}
+- **Likely cause**: {diagnosis - e.g., "Learning rate too small (lr=1e-5, survey baseline=1e-3)"}
+- **Evidence**: {supporting evidence - e.g., "survey_res.md Table 2 shows all baselines use lr=1e-3"}
+
 ## Issues (if NEEDS_REVISION)
 1. **{issue}**: {description} → **Fix**: {specific fix instruction}
 2. ...
+
+## Algorithm Review Suggestions (if NEEDS_ALGORITHM_REVIEW)
+
+**按优先级排序的改进建议**（只调整超参数/训练配置，不改核心算法）：
+
+1. **{建议名称}**（最可能有效）
+   - **What to change**: {具体修改内容}
+   - **Where**: {文件路径和代码位置}
+   - **Expected improvement**: {预期效果}
+
+2. **{次要建议}**
+   - ...
+
+**Note**: 如果尝试所有建议后仍无改善，可能需要重新考虑算法选择或数据质量。
 ```
 
-### Step 5: 迭代（如果 NEEDS_REVISION）
+### Step 5a: 代码修复迭代（如果 NEEDS_REVISION）
 
 **⚠️ 防偏移机制：每轮迭代都重新读取原始设计文档，确保修改方向正确。**
 
@@ -147,29 +205,145 @@ metadata:
    - 对照原始学术设计目标
    - 确保修改不是为了"绕过审查"而偏离学术严谨性
    - 确认修改符合 survey 中的公式定义和 plan 中的设计意图
-3. 修改 `$W/project/` 中的代码
+3. 修改 `$W/project/` 中的代码（修复 bug、补全缺失实现）
 4. 重新执行：
    ```bash
    cd $W/project && source .venv/bin/activate && python run.py --epochs 2
    ```
 5. 读取执行输出，验证修复
 6. **重新执行 Step 2-4**（提取概念清单 → 逐项检查 → 写报告），写入 `judge_v{N+1}.md`
-7. 如果 PASS → 停止；否则继续
+7. 如果 PASS 或 NEEDS_ALGORITHM_REVIEW → 停止；否则继续
+
+### Step 5b: 算法反思与调优（如果 NEEDS_ALGORITHM_REVIEW）
+
+**⚠️ 关键新增 — 代码正确但性能不佳时的改进循环。**
+
+**前提**：代码实现正确（所有原子性概念 ✓），但 2 epoch 验证显示性能异常。
+
+循环最多 **2 次**：
+
+#### 5b.1 性能诊断
+
+重新读取以下材料进行诊断：
+- `$W/ml_res.md` — 2 epoch 验证的具体数值
+- `$W/survey_res.md` — baseline 方法的超参数设置（特别是学习率、batch size）
+- `$W/plan_res.md` — 当前实现的超参数配置
+- `$W/project/run.py` 和 `$W/project/training/` — 训练配置代码
+
+**诊断检查清单**：
+
+| 症状 | 诊断步骤 | 常见原因 |
+|------|----------|----------|
+| Loss 下降 <5% | 对比 plan lr vs survey baseline lr | lr 过小（如 plan=1e-5 但 survey=1e-3） |
+| Loss 震荡 >20% | 同上 + 检查 batch size | lr 过大或 batch size 过小 |
+| Accuracy 接近随机 | 检查数据预处理代码、检查 loss 是否下降 | 数据归一化缺失、特征错误、模型过简单 |
+| Loss=NaN/Inf | 检查是否有 normalization、检查 lr | 梯度爆炸、数值不稳定 |
+
+#### 5b.2 生成改进建议
+
+基于诊断结果，生成**按优先级排序**的改进建议。
+
+**改进范围限制**：
+- ✅ 允许：调整超参数（lr、batch size、epochs、optimizer、scheduler）
+- ✅ 允许：修改训练配置（添加 warmup、gradient clipping、weight decay）
+- ✅ 允许：修复数据预处理问题（添加归一化、标准化）
+- ❌ 禁止：修改核心算法逻辑（模型架构、loss 函数数学公式）
+
+**建议格式**（写入 `judge_v{N}.md` 的 "Algorithm Review Suggestions" 部分）：
+
+```markdown
+1. **调整学习率**（优先级：高，预期改善：显著）
+   - **当前值**: lr=1e-5 (from plan_res.md)
+   - **建议值**: lr=1e-3 (from survey_res.md Table 2, all baselines use 1e-3)
+   - **修改位置**: `$W/project/run.py:L15` — `optimizer = Adam(lr=1e-3)`
+   - **理由**: Loss 下降仅 0.9%，远低于正常 10%+，高度怀疑 lr 过小
+
+2. **添加数据归一化**（优先级：中，预期改善：中等）
+   - **检查**: `$W/project/data/dataset.py` 是否有归一化
+   - **建议**: 添加 `transforms.Normalize(mean=[0.5], std=[0.5])`
+   - **理由**: 如果输入数据范围 [0,255]，模型收敛会很慢
+```
+
+#### 5b.3 执行改进并验证
+
+1. 根据建议**逐项尝试**（从优先级高的开始）
+2. 每次修改后：
+   ```bash
+   cd $W/project && source .venv/bin/activate && python run.py --epochs 2
+   ```
+3. 读取新的执行输出，对比改进前后：
+   - Loss reduction 是否提升？（如 0.9% → 12%）
+   - Metrics 是否改善？（如 accuracy 12% → 34%）
+4. 记录每次尝试的结果到 `judge_v{N+1}.md` 的 "Algorithm Review Iterations" 部分：
+
+```markdown
+## Algorithm Review Iterations
+
+### Iteration 1
+- **Change**: Increased lr from 1e-5 to 1e-3
+- **Result**:
+  - Loss reduction: 0.9% → 12.3% ✓ (improvement: +11.4%)
+  - Accuracy: 12% → 34% ✓ (improvement: +22%)
+- **Conclusion**: Learning rate was the bottleneck. Issue resolved.
+- **New verdict**: PASS ✓
+
+### Iteration 2 (if needed)
+- ...
+```
+
+#### 5b.4 判定
+
+- **改善显著**（loss reduction 提升 >5%）→ `verdict: PASS`，停止
+- **改善微小**（<2%）→ 继续下一个建议或下一轮
+- **2 轮后仍无改善** → `verdict: BLOCKED`，标注原因（如"所有超参数调整均无效，可能需要重新选择算法或检查数据质量"）
+
+---
+
+**Step 5a vs 5b 的区别**：
+
+| | Step 5a (NEEDS_REVISION) | Step 5b (NEEDS_ALGORITHM_REVIEW) |
+|---|---|---|
+| 触发条件 | 代码有 bug、实现错误 | 代码正确但性能不佳 |
+| 修改范围 | 核心算法代码 | 超参数和训练配置 |
+| 迭代次数 | 3 次 | 2 次 |
+| 目标 | 正确性 | 有效性 |
 
 ### Step 6: 最终判定
 
-3 轮后仍 NEEDS_REVISION → 在最后一份 judge 中列出剩余问题，标记 `verdict: BLOCKED`，等待用户介入。
+**终止条件**：
+
+| 场景 | 判定 | 说明 |
+|------|------|------|
+| 所有 checklist ✓ + 性能合理 | `PASS` | 交付给 research-experiment |
+| Step 5a 3 轮后仍有 bug | `BLOCKED - Code Issues` | 列出剩余问题，等待用户介入 |
+| Step 5b 2 轮后性能仍异常 | `BLOCKED - Performance Issues` | 标注尝试过的改进和结果，建议用户重新考虑算法选择或数据质量 |
 
 ---
 
 ## Rules
 
+### 审查标准
+
 1. 审查必须逐项对照 plan，不能只看"代码能跑"
 2. 每个 issue 必须给出具体的修复指令（不是"请改进"）
 3. 验证修复后必须重新执行代码并检查输出
-4. PASS 的前提：所有 checklist 项通过 + [RESULT] 数值合理
+4. **PASS 的前提**：所有 checklist 项通过 + 性能初步评估合理（不仅仅是"有下降"）
 5. **数据集必须验证真实性** —— 实际执行数据加载代码，确认有真实数据（哪怕是小规模）；纯随机 tensor 不算
 6. **执行时间必须与算力匹配** —— 2 epoch 训练时间过短（数据量 >1000 却 <2s）说明数据未加载或训练是空循环
 7. **算法实现必须完整** —— plan 中标注的核心创新点必须逐一检查，不能被简化为 `nn.Linear` 占位
 8. **原子性概念逐一核对（Novix Judge 机制）** —— Step 2 提取的每个概念都必须在 judge 报告的表格中有对应行，标注 ✓ 或 ✗
-9. **防偏移（每轮迭代必须重新对齐）** —— Step 5 每轮修改前必须重新读取 survey_res.md 和 plan_res.md，确保不偏离原始设计目标
+9. **防偏移（每轮迭代必须重新对齐）** —— Step 5a/5b 每轮修改前必须重新读取 survey_res.md 和 plan_res.md，确保不偏离原始设计目标
+
+### 性能评估（新增）
+
+10. **性能初步评估是强制项** —— Step 3D 必须执行，不能跳过
+11. **Loss 下降幅度有最低要求** —— 2 epoch 验证的 loss reduction <5% 必须标记为性能异常
+12. **Metrics 必须超过随机 baseline** —— 分类任务 accuracy 接近 1/num_classes（±10%）视为"模型未学习"
+13. **性能异常触发算法反思** —— 代码正确但性能不佳时，必须进入 Step 5b 尝试调优，不能直接 PASS
+
+### 算法反思（新增）
+
+14. **Step 5b 只调超参数，不改算法** —— 禁止修改核心算法逻辑、模型架构、loss 函数公式
+15. **改进建议必须有依据** —— 每个建议必须引用 survey_res.md 或 plan_res.md 中的具体内容
+16. **改进效果必须量化** —— 每次尝试后必须记录改善幅度（如 "loss reduction +11.4%"），不能只说"有改善"
+17. **2 轮算法反思后仍无改善视为 BLOCKED** —— 标注原因并建议用户介入（如"可能需要更换算法或检查数据质量"）

package/skills/research-survey/SKILL.md

@@ -61,6 +61,15 @@ ls $W/papers/_meta/
 - **Model Architecture** section
 - 数学公式定义
 
+**对于大型论文**（>2000 行），使用 `paper_browser` 分页阅读：
+```javascript
+// 先读前 100 行找到 section 位置
+paper_browser({ file_path: "$W/papers/{arxiv_id}/{file}.tex", start_line: 1, num_lines: 100 })
+
+// 找到 Method section 后，跳转到该位置
+paper_browser({ file_path: "$W/papers/{arxiv_id}/{file}.tex", start_line: 450, num_lines: 150 })
+```
+
 如果没有 .tex（只有 PDF），基于 abstract 分析。
 
 #### 2.2 提取核心内容