scientify 1.5.0 → 1.6.1

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;AAmBlD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAkFtD"}

package/dist/index.js

@@ -3,6 +3,7 @@ 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 { createAutoUpdaterService } from "./src/services/auto-updater.js";
 import { createSkillInjectionHook } from "./src/hooks/inject-skill.js";
 // Default: check every hour
@@ -12,6 +13,7 @@ export default function register(api) {
     api.registerTool(createArxivSearchTool());
     api.registerTool(createArxivDownloadTool());
     api.registerTool(createGithubSearchTool());
+    api.registerTool(createPaperBrowserTool());
     // 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":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,4BAA4B;AAC5B,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAsB;IACrD,iBAAiB;IACjB,GAAG,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC1C,GAAG,CAAC,YAAY,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC5C,GAAG,CAAC,YAAY,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAE3C,iDAAiD;IACjD,MAAM,YAAY,GAAG,GAAG,CAAC,YAAoD,CAAC;IAC9E,MAAM,iBAAiB,GAAG,YAAY,EAAE,UAAU,KAAK,KAAK,CAAC,CAAC,qBAAqB;IAEnF,IAAI,iBAAiB,EAAE,CAAC;QACtB,GAAG,CAAC,eAAe,CACjB,wBAAwB,CAAC;YACvB,WAAW,EAAE,WAAW;YACxB,eAAe,EAAE,wBAAwB;YACzC,MAAM,EAAE;gBACN,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;gBACnC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;gBACnC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;aACxC;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,gEAAgE;QAC7E,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,0CAA0C;QACvD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,YAAY;KACtB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,KAAK;QAClB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,oDAAoD;QACjE,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,IAAI,EAAE,yCAAyC;QAC5D,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,qDAAqD;IACrD,4EAA4E;IAC5E,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,GAAG,CAAC,EAAE,CAAC,kBAAkB,EAAE,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAE/E,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.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":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,MAAM,CAAC;IAChD,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;QACrB,WAAW,EAAE,uDAAuD;KACrE,CAAC;IACF,UAAU,EAAE,IAAI,CAAC,QAAQ,CACvB,IAAI,CAAC,MAAM,CAAC;QACV,WAAW,EAAE,+CAA+C;QAC5D,OAAO,EAAE,CAAC;KACX,CAAC,CACH;IACD,SAAS,EAAE,IAAI,CAAC,QAAQ,CACtB,IAAI,CAAC,MAAM,CAAC;QACV,WAAW,EAAE,wCAAwC,qBAAqB,UAAU,iBAAiB,IAAI;QACzG,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,iBAAiB;KAC3B,CAAC,CACH;CACF,CAAC,CAAC;AAEH,SAAS,eAAe,CAAC,MAA+B,EAAE,GAAW,EAAE,IAA6B;IAClG,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,eAAe,CAAC,MAA+B,EAAE,GAAW,EAAE,IAA4B;IACjG,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,mMAAmM;QACrM,UAAU,EAAE,sBAAsB;QAClC,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,OAAgB,EAAE,EAAE;YACvD,MAAM,MAAM,GAAG,OAAkC,CAAC;YAClD,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAE,CAAC;YAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,qBAAqB,EAChF,iBAAiB,CAClB,CAAC;YAEF,uBAAuB;YACvB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,wBAAwB,QAAQ,EAAE,CAAC,CAAC;YAC1E,CAAC;YAED,uCAAuC;YACvC,IAAI,KAAK,CAAC;YACV,IAAI,CAAC;gBACH,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,uBAAuB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACnH,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACpB,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,uBAAuB,QAAQ,EAAE,CAAC,CAAC;YACrE,CAAC;YAED,oBAAoB;YACpB,IAAI,OAAe,CAAC;YACpB,IAAI,CAAC;gBACH,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,wBAAwB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACpH,CAAC;YAED,mBAAmB;YACnB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;YAEhC,sBAAsB;YACtB,IAAI,SAAS,GAAG,UAAU,EAAE,CAAC;gBAC3B,OAAO,MAAM,CAAC,GAAG,CACf,eAAe,EACf,cAAc,SAAS,wBAAwB,UAAU,EAAE,CAC5D,CAAC;YACJ,CAAC;YAED,mBAAmB;YACnB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,QAAQ,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;YAC/D,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;YAE1D,2EAA2E;YAC3E,MAAM,aAAa,GAAG,aAAa;iBAChC,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;gBACjB,MAAM,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC;gBAChC,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3D,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAC;YAEd,mBAAmB;YACnB,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;YACrC,MAAM,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC;YAE9B,IAAI,cAAc,GAAG,EAAE,CAAC;YACxB,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;gBACvB,cAAc,GAAG,6CAA6C,QAAQ,kBAAkB,OAAO,GAAG,CAAC,qCAAqC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,qBAAqB,CAAC;YACjM,CAAC;iBAAM,IAAI,OAAO,EAAE,CAAC;gBACnB,cAAc,GAAG,4DAA4D,QAAQ,kBAAkB,OAAO,GAAG,CAAC,KAAK,CAAC;YAC1H,CAAC;iBAAM,IAAI,OAAO,EAAE,CAAC;gBACnB,cAAc,GAAG,qDAAqD,QAAQ,kBAAkB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,wBAAwB,CAAC;YAC5J,CAAC;iBAAM,CAAC;gBACN,cAAc,GAAG,mBAAmB,CAAC;YACvC,CAAC;YAED,OAAO,MAAM,CAAC,EAAE,CAAC;gBACf,SAAS,EAAE,QAAQ;gBACnB,WAAW,EAAE,UAAU;gBACvB,QAAQ,EAAE;oBACR,UAAU,EAAE,SAAS;oBACrB,QAAQ,EAAE,OAAO;oBACjB,SAAS,EAAE,aAAa,CAAC,MAAM;iBAChC;gBACD,OAAO,EAAE,aAAa,GAAG,cAAc;gBACvC,QAAQ,EAAE,OAAO;gBACjB,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scientify",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "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",

package/skills/literature-survey/SKILL.md

@@ -21,11 +21,15 @@ metadata:
 ├── survey/
 │   ├── search_terms.json      # 检索词列表
 │   └── report.md              # 最终报告
-└── papers/
-    ├── _downloads/            # 原始下载
-    ├── _meta/                 # 每篇论文的元数据
-    │   └── {arxiv_id}.json
-    └── {direction}/           # 整理后的分类
+├── papers/
+│   ├── _downloads/            # 原始下载
+│   ├── _meta/                 # 每篇论文的元数据
+│   │   └── {arxiv_id}.json
+│   └── {direction}/           # 整理后的分类
+├── repos/                     # 参考代码仓库（Phase 3）
+│   ├── {repo_name_1}/
+│   └── {repo_name_2}/
+└── prepare_res.md             # 仓库选择报告（Phase 3）
 ```
 
 ---
@@ -95,11 +99,84 @@ arxiv_download({
 
 ---
 
-### Phase 3: 分类整理
+### Phase 3: GitHub 代码搜索与参考仓库选择
 
-所有检索词处理完毕后：
+**目标**：为下游 skill（research-survey、research-plan、research-implement）提供可参考的开源实现。
 
-#### 3.1 读取所有元数据
+#### 3.1 选择高分论文
+
+读取 `papers/_meta/` 下得分 ≥4 的论文，选出 **Top 5** 最相关论文。
+
+#### 3.2 搜索参考仓库
+
+对每篇选中论文，用以下关键词组合搜索 GitHub 仓库：
+- 论文标题 + "code" / "implementation"
+- 核心方法名 + 作者名
+- 论文中提到的数据集名 + 任务名
+
+使用 `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
+
+对搜索到的仓库，评估：
+- Star 数（建议 >100）
+- 代码质量（有 README、有 requirements.txt、代码结构清晰）
+- 与论文的匹配度（README 中引用了论文 / 实现了论文中的方法）
+
+选择 **3-5 个**最相关的仓库，clone 到 `repos/`：
+
+```bash
+mkdir -p "$PROJECT_DIR/repos"
+cd "$PROJECT_DIR/repos"
+git clone --depth 1 <repo_url>
+```
+
+#### 3.4 写入选择报告
+
+创建 `$PROJECT_DIR/prepare_res.md`：
+
+```markdown
+# 参考仓库选择
+
+| 仓库 | 对应论文 | Stars | 选择理由 |
+|------|----------|-------|----------|
+| repos/{repo_name} | {paper_title} (arxiv:{id}) | {N} | {理由} |
+
+## 各仓库关键文件
+
+### {repo_name}
+- **模型实现**: `model/` 或 `models/`
+- **训练脚本**: `train.py` 或 `main.py`
+- **数据加载**: `data/` 或 `dataset.py`
+- **核心文件**: `{关键文件路径}` — {描述}
+```
+
+**如果搜不到相关仓库**，在 `prepare_res.md` 中注明"无可用参考仓库"，后续 skill 将不依赖代码映射。
+
+---
+
+### Phase 4: 分类整理
+
+所有检索词和代码搜索完毕后：
+
+#### 4.1 读取所有元数据
 
 ```bash
 ls $PROJECT_DIR/papers/_meta/
@@ -107,11 +184,11 @@ ls $PROJECT_DIR/papers/_meta/
 
 读取所有 `.json` 文件，汇总论文列表。
 
-#### 3.2 聚类分析
+#### 4.2 聚类分析
 
 根据论文的标题、摘要、来源检索词，识别 3-6 个研究方向。
 
-#### 3.3 创建文件夹并移动
+#### 4.3 创建文件夹并移动
 
 ```bash
 mkdir -p "$PROJECT_DIR/papers/data-driven"
@@ -120,12 +197,13 @@ mv "$PROJECT_DIR/papers/_downloads/2401.12345" "$PROJECT_DIR/papers/data-driven/
 
 ---
 
-### Phase 4: 生成报告
+### Phase 5: 生成报告
 
 创建 `survey/report.md`：
 - 调研概要（检索词数、论文数、方向数）
 - 各研究方向概述
 - Top 10 论文
+- **参考仓库摘要**（引用 prepare_res.md）
 - 建议阅读顺序
 
 ---

package/skills/research-experiment/SKILL.md

@@ -31,7 +31,8 @@ metadata:
 
 | File | Content |
 |------|---------|
-| `$W/experiment_res.md` | 完整实验报告 |
+| `$W/experiment_res.md` | 完整实验报告（含 full training + 消融 + 补充实验） |
+| `$W/experiment_analysis/analysis_{N}.md` | 每轮实验分析报告（迭代过程中产生） |
 
 ---
 
@@ -69,9 +70,55 @@ python run.py  # full epochs
 python run.py --epochs 2 --ablation no_attention
 ```
 
-### Step 4: 写入实验报告
+### Step 4: 实验分析→补充实验迭代（2 轮）
 
-写入 `$W/experiment_res.md`：
+**⚠️ 这是 Novix Exp Analyzer 机制 — 对已有结果进行分析，提出补充实验，执行后再分析。**
+
+循环 **2 次**：
+
+#### 4.1 分析当前结果
+
+读取当前所有实验结果（full training + 消融），写入分析报告 `$W/experiment_analysis/analysis_{N}.md`：
+
+```markdown
+# Experiment Analysis Round {N}
+
+## 当前结果摘要
+- Full training: {metrics}
+- 消融实验: {key findings}
+
+## 发现的问题或机会
+1. {observation} → 建议: {experiment}
+2. ...
+
+## 补充实验计划
+| 实验名称 | 目的 | 修改内容 | 预期结果 |
+|----------|------|----------|----------|
+| {exp_name} | {why} | {what to change} | {expected} |
+```
+
+补充实验类型参考（**Novix Exp Analyzer** 的典型输出）：
+- **敏感性分析**：关键超参数（lr、hidden_dim、dropout）的影响
+- **可视化**：attention map、embedding 可视化、训练曲线对比图
+- **对比实验**：与 baseline 方法的性能对比
+- **鲁棒性测试**：不同数据规模/噪声水平下的表现
+
+#### 4.2 执行补充实验
+
+根据分析报告中的计划，修改代码并执行补充实验。**只改实验相关参数/配置，不改核心算法逻辑。**
+
+```bash
+cd $W/project && source .venv/bin/activate
+python run.py --experiment {exp_name}
+```
+
+记录结果后，回到 4.1 进行下一轮分析（共 2 轮）。
+
+---
+
+### Step 5: 写入最终实验报告
+
+汇总所有实验结果（full training + 消融 + 2 轮补充实验），写入 `$W/experiment_res.md`：
 
 ```markdown
 # Experiment Report
@@ -97,8 +144,25 @@ python run.py --epochs 2 --ablation no_attention
 | No {component} | 去掉 {X} | {value} | {-/+}% |
 | ... | ... | ... | ... |
 
+## Supplementary Experiments
+
+### Sensitivity Analysis
+| 超参数 | 值 | val_metric | 备注 |
+|--------|-----|-----------|------|
+| ... | ... | ... | ... |
+
+### Comparison with Baselines
+| 方法 | val_metric | 备注 |
+|------|-----------|------|
+| Ours | {value} | — |
+| {Baseline} | {value} | ... |
+
+### Visualizations
+- 训练曲线: `$W/project/figures/training_curve.png`
+- {其他可视化}: `$W/project/figures/{name}.png`
+
 ## Conclusions
-- {key findings}
+- {key findings from all experiments}
 
 ## Limitations
 - {limitations and future work}
@@ -112,3 +176,5 @@ python run.py --epochs 2 --ablation no_attention
 2. 所有数值必须来自真实执行输出
 3. 消融实验至少做 2 个
 4. 如果 full training 失败（OOM 等），调整 batch_size 后重试，不要跳过
+5. **补充实验迭代必须做 2 轮（Novix Exp Analyzer 机制）** — 第 1 轮针对初始结果，第 2 轮针对补充实验结果
+6. 补充实验不改核心算法，只改实验配置/参数/可视化代码

package/skills/research-plan/SKILL.md

@@ -23,7 +23,8 @@ metadata:
 | `$W/task.json` | /research-pipeline or user |
 | `$W/survey_res.md` | /research-survey |
 | `$W/notes/paper_*.md` | /research-survey |
-| `$W/repos/` (optional) | git clone |
+| `$W/repos/` | /literature-survey Phase 3 |
+| `$W/prepare_res.md` | /literature-survey Phase 3 |
 
 **If `survey_res.md` is missing, STOP:** "需要先运行 /research-survey 完成深度分析"
 
@@ -41,10 +42,22 @@ metadata:
 
 读取以下文件，理解研究目标和技术方案：
 - `$W/task.json` — 研究目标
-- `$W/survey_res.md` — 技术路线建议和核心公式
-- 浏览 `$W/repos/` 的目录结构（如有）
+- `$W/survey_res.md` — 技术路线建议、核心公式、**公式→代码映射表**、参考代码架构摘要
+- `$W/prepare_res.md` — 参考仓库列表及关键文件说明
 
-### Step 2: 制定四部分计划
+### Step 2: 参考代码深度分析
+
+**⚠️ 强制性步骤（Novix Plan Agent 机制）** — 读参考仓库的实现细节，确保 plan 有具体可行的依据。
+
+对 `prepare_res.md` 中的重点仓库：
+1. 读取目录结构和 README
+2. 读取核心模型代码，理解架构实现方式
+3. 读取训练脚本，理解超参数选择和训练技巧
+4. 读取数据加载代码，理解预处理流程
+
+为每个组件记录：**参考文件路径 + 关键实现细节**。这些信息将直接填入 plan 的"参考代码"列。
+
+### Step 3: 制定四部分计划
 
 写入 `$W/plan_res.md`：
 
@@ -100,11 +113,12 @@ metadata:
   2. {ablation 2}
 ```
 
-### Step 3: 自检
+### Step 4: 自检
 
 验证计划的完整性：
 - [ ] 每个模型组件都有对应公式
-- [ ] 数据集有具体获取方式
+- [ ] **每个组件的"参考代码"列已填写**（当 repos/ 存在时）
+- [ ] 数据集有具体获取方式（URL 或下载命令）
 - [ ] Loss 函数有数学定义
 - [ ] 评估指标有明确定义
 - [ ] 训练参数合理（不要 lr=0.1 for Adam）

package/skills/research-review/SKILL.md

@@ -48,7 +48,27 @@ metadata:
 - `$W/project/` — 实际代码
 - `$W/ml_res.md` — 执行结果
 
-### Step 2: 逐项检查
+### Step 2: 提取原子性概念清单
+
+**⚠️ 这是 Novix Judge Agent 的核心机制 — 逐一核对每个原子性学术概念。**
+
+从 `$W/survey_res.md` 的"关键公式汇总"和"核心方法对比"中，提取所有需要在代码中实现的**原子性学术概念**（每个公式、每个核心组件都是一个概念）。
+
+为每个概念记录：
+- 概念名称（如 "Multi-Head Attention", "Contrastive Loss", "Batch Normalization"）
+- 对应公式（LaTeX 格式）
+- 预期代码位置（根据 plan_res.md 推断）
+
+示例清单：
+```
+原子性概念清单（从 survey_res.md 提取）：
+1. Multi-Head Attention — $Attention(Q,K,V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$ — 预期在 model/attention.py
+2. Layer Normalization — $LN(x) = \gamma \frac{x - \mu}{\sigma} + \beta$ — 预期在 model/layers.py
+3. Residual Connection — $y = F(x) + x$ — 预期贯穿所有模型组件
+...
+```
+
+### Step 3: 逐项检查
 
 #### A. 数据集真实性审查
 
@@ -62,7 +82,7 @@ metadata:
 
 | 检查项 | 方法 |
 |--------|------|
-| 模型架构匹配公式 | 逐层对比 survey_res.md 中的核心公式 vs `model/` 实现，检查维度变换、激活函数、注意力机制等关键细节 |
+| **原子性概念逐一核对** | **对照 Step 2 的概念清单，逐个检查**：该概念是否在代码中有对应实现？公式翻译是否正确？维度/参数是否一致？每个概念标注 ✓ 或 ✗ 并记录代码位置 |
 | Loss 函数正确 | 对比 plan Training Plan vs `training/loss.py`，验证数学公式是否正确翻译为代码 |
 | 评估指标正确 | 对比 plan Testing Plan vs `testing/`，确认指标计算逻辑无误 |
 | 关键算法未被简化 | 检查 plan 中的核心创新点是否被完整实现，而非用简化/占位逻辑替代 |
@@ -76,7 +96,7 @@ metadata:
 | Loss 合理 | 非 NaN/Inf，有下降趋势（epoch 1 loss > epoch 2 loss） |
 | 数据管道匹配 plan | 对比 plan Dataset Plan vs `data/` 实现，batch size、预处理步骤一致 |
 
-### Step 3: 写入审查报告
+### Step 4: 写入审查报告
 
 写入 `$W/iterations/judge_v1.md`：
 
@@ -92,8 +112,16 @@ metadata:
 - [x/✗] Data loading code produces correct shape/dtype/count
 - [x/✗] No undeclared mock data
 
-### 算法实现
-- [x/✗] Model architecture matches survey formulas
+### 算法实现 - 原子性概念核对
+
+**逐一核对 Step 2 提取的每个学术概念：**
+
+| 概念 | 公式 | 代码位置 | 结果 | 备注 |
+|------|------|----------|------|------|
+| {概念名} | $...$ | `model/xxx.py:L42` | ✓/✗ | {正确实现/公式错误/缺失/简化为占位符} |
+| ... | ... | ... | ... | ... |
+
+### 算法实现 - 整体检查
 - [x/✗] Loss function correctly implements the math
 - [x/✗] Key algorithm components fully implemented (no simplified placeholders)
 - [x/✗] Evaluation metrics correct
@@ -108,21 +136,27 @@ metadata:
 2. ...
 ```
 
-### Step 4: 迭代（如果 NEEDS_REVISION）
+### Step 5: 迭代（如果 NEEDS_REVISION）
+
+**⚠️ 防偏移机制：每轮迭代都重新读取原始设计文档，确保修改方向正确。**
 
 循环最多 3 次：
 
 1. 读取 `judge_v{N}.md` 的修改建议
-2. 修改 `$W/project/` 中的代码
-3. 重新执行：
+2. **防偏移检查：重新读取** `$W/survey_res.md` 和 `$W/plan_res.md`
+   - 对照原始学术设计目标
+   - 确保修改不是为了"绕过审查"而偏离学术严谨性
+   - 确认修改符合 survey 中的公式定义和 plan 中的设计意图
+3. 修改 `$W/project/` 中的代码
+4. 重新执行：
    ```bash
    cd $W/project && source .venv/bin/activate && python run.py --epochs 2
    ```
-4. 读取执行输出，验证修复
-5. 写入 `judge_v{N+1}.md`
-6. 如果 PASS → 停止；否则继续
+5. 读取执行输出，验证修复
+6. **重新执行 Step 2-4**（提取概念清单 → 逐项检查 → 写报告），写入 `judge_v{N+1}.md`
+7. 如果 PASS → 停止；否则继续
 
-### Step 5: 最终判定
+### Step 6: 最终判定
 
 3 轮后仍 NEEDS_REVISION → 在最后一份 judge 中列出剩余问题，标记 `verdict: BLOCKED`，等待用户介入。
 
@@ -137,3 +171,5 @@ metadata:
 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，确保不偏离原始设计目标

package/skills/research-survey/SKILL.md

@@ -24,9 +24,12 @@ Read and verify these files exist before starting:
 |------|--------|
 | `$W/papers/_meta/*.json` | /literature-survey |
 | `$W/papers/_downloads/` or `$W/papers/{direction}/` | /literature-survey |
-| `$W/repos/` (optional) | git clone in /literature-survey or manually |
+| `$W/repos/` | /literature-survey Phase 3 |
+| `$W/prepare_res.md` | /literature-survey Phase 3 |
 
-**If any prerequisite is missing, STOP and report:** "需要先运行 /literature-survey 完成论文下载"
+**If papers are missing, STOP:** "需要先运行 /literature-survey 完成论文下载"
+
+**Note:** 如果 `prepare_res.md` 中注明"无可用参考仓库"，代码映射步骤可跳过，但需在 survey_res.md 中标注。
 
 ## Output
 
@@ -58,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 提取核心内容
@@ -67,11 +79,14 @@ ls $W/papers/_meta/
 - **数学公式**：至少 1 个关键公式（保留 LaTeX 格式）
 - **创新点**：与同领域其他方法的区别
 
-#### 2.3 映射到代码（如果 repos/ 存在）
+#### 2.3 映射到参考代码
 
-如果 `$W/repos/` 中有相关仓库：
-- 找到公式对应的代码实现
-- 记录文件路径和行号
+**⚠️ 强制性步骤（当 repos/ 存在时）** — 代码映射是下游 plan 和 implement 的关键输入。
+
+读取 `$W/prepare_res.md` 中的仓库列表，对每个公式/核心概念：
+1. 在对应仓库中搜索实现代码（用 grep 关键类名/函数名）
+2. 记录**文件路径、行号、代码片段**
+3. 如果多个仓库有不同实现，记录差异
 
 #### 2.4 写入笔记
 
@@ -127,7 +142,19 @@ $$
 
 ## 关键公式汇总
 
-{列出所有提取的核心公式}
+**每个公式附带代码映射，供下游 plan 和 implement 参考。**
+
+| 公式名称 | LaTeX | 参考代码 |
+|----------|-------|----------|
+| {name} | $...$ | `repos/{repo}/path.py:L42` |
+| ... | ... | ... |
+
+## 参考代码架构摘要
+
+基于 repos/ 中的参考实现，推荐的代码结构：
+- 数据加载: 参考 `repos/{repo}/data/`
+- 模型实现: 参考 `repos/{repo}/model/`
+- 训练循环: 参考 `repos/{repo}/train.py`
 ```
 
 ---