@windsland52/maa-log-tools 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Windsland52
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -24,9 +24,24 @@ The concrete adapter is provided by `@windsland52/maa-log-adapter`.
   - `DEFAULT_CORE_PARSE_OPTIONS`
 - `@windsland52/maa-log-tools/node-input`
   - Node file/zip/folder extraction helpers
+  - `LogBundleFocus`
 - `@windsland52/maa-log-tools/cli`
   - CLI entry module
 
+## Focused Loading
+
+`analyzeZipBuffer`, `analyzeZipFile`, `analyzeDirectory`, `extractZipContentFromNodeBuffer`, `extractZipContentFromNodeFile`, and `loadNodeLogDirectory` all accept an optional `focus` selector:
+
+```ts
+{
+  keywords?: string[]
+  started_after?: string
+  started_before?: string
+}
+```
+
+When `focus` is provided, the helpers scan candidate primary and history log files and only merge files whose content matches the keywords and/or timestamp boundaries. If `focus` is omitted, the previous default loading behavior is preserved.
+
 ## CLI
 
 ```bash

package/dist/index.d.ts

@@ -1,19 +1,23 @@
 import type { KernelOutput } from '@windsland52/maa-log-kernel';
 import type { AnalyzeLogContentInput, ParseFileOptions } from '@windsland52/maa-log-runtime';
+import { type LogBundleFocus } from './nodeInput';
 type ParseOptions = ParseFileOptions;
 export interface AnalyzeZipBufferInput {
     zipData: Uint8Array;
     sourceRef?: string;
+    focus?: LogBundleFocus;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }
 export interface AnalyzeZipFileInput {
     zipFilePath: string;
+    focus?: LogBundleFocus;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }
 export interface AnalyzeDirectoryInput {
     directoryPath: string;
+    focus?: LogBundleFocus;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }

package/dist/index.js

@@ -8,7 +8,9 @@ export const analyzeLogContent = async (input) => {
     });
 };
 export const analyzeZipBuffer = async (input) => {
-    const extracted = extractZipContentFromNodeBuffer(input.zipData, input.sourceRef);
+    const extracted = extractZipContentFromNodeBuffer(input.zipData, input.sourceRef, {
+        focus: input.focus,
+    });
     if (!extracted)
         return null;
     return analyzeLogContent({
@@ -21,7 +23,9 @@ export const analyzeZipBuffer = async (input) => {
     });
 };
 export const analyzeZipFile = async (input) => {
-    const extracted = await extractZipContentFromNodeFile(input.zipFilePath);
+    const extracted = await extractZipContentFromNodeFile(input.zipFilePath, {
+        focus: input.focus,
+    });
     if (!extracted)
         return null;
     return analyzeLogContent({
@@ -34,7 +38,9 @@ export const analyzeZipFile = async (input) => {
     });
 };
 export const analyzeDirectory = async (input) => {
-    const extracted = await loadNodeLogDirectory(input.directoryPath);
+    const extracted = await loadNodeLogDirectory(input.directoryPath, {
+        focus: input.focus,
+    });
     if (!extracted)
         return null;
     return analyzeLogContent({

package/dist/nodeExecutionTimeline.js

@@ -3,7 +3,7 @@ import { sortNodesByGlobalExecutionOrder } from './taskExecutionOrder.js';
 const isNodeActionFailed = (node) => {
     if (node.action_details && node.action_details.success === false)
         return true;
-    return (node.node_flow || []).some((item) => item.type === 'action' && item.status === 'failed');
+    return (node.node_flow || []).some((item) => (item.type === 'action' || item.type === 'action_node') && item.status === 'failed');
 };
 export const buildNodeExecutionTimeline = (nodes, options = {}) => {
     const originalIndexByNode = new Map();

package/dist/nodeInput.d.ts

@@ -11,7 +11,18 @@ export interface NodeExtractedLogContent {
     waitFreezesImages: Map<string, string>;
     textFiles: KernelTextFile[];
 }
+export interface LogBundleFocus {
+    keywords?: string[];
+    started_after?: string;
+    started_before?: string;
+}
+export interface ExtractZipContentOptions {
+    focus?: LogBundleFocus;
+}
+export interface LoadNodeLogDirectoryOptions {
+    focus?: LogBundleFocus;
+}
 export declare const readNodeTextFileContent: (filePath: string) => Promise<string>;
-export declare const extractZipContentFromNodeBuffer: (zipData: Uint8Array, sourceRef?: string) => NodeExtractedLogContent | null;
-export declare const extractZipContentFromNodeFile: (zipFilePath: string) => Promise<NodeExtractedLogContent | null>;
-export declare const loadNodeLogDirectory: (inputDirectoryPath: string) => Promise<NodeExtractedLogContent | null>;
+export declare const extractZipContentFromNodeBuffer: (zipData: Uint8Array, sourceRef?: string, options?: ExtractZipContentOptions) => NodeExtractedLogContent | null;
+export declare const extractZipContentFromNodeFile: (zipFilePath: string, options?: ExtractZipContentOptions) => Promise<NodeExtractedLogContent | null>;
+export declare const loadNodeLogDirectory: (inputDirectoryPath: string, options?: LoadNodeLogDirectoryOptions) => Promise<NodeExtractedLogContent | null>;

package/dist/nodeInput.js

@@ -4,16 +4,24 @@ import { unzipSync } from 'fflate';
 const MAIN_LOG_NAMES = ['maa.log', 'maafw.log'];
 const BAK_LOG_NAMES = ['maa.bak.log', 'maafw.bak.log'];
 const SEARCH_TEXT_EXTENSIONS = ['.log', '.txt', '.jsonl'];
-const PRIMARY_LOG_NAME_SET = new Set([
-    ...MAIN_LOG_NAMES,
-    ...BAK_LOG_NAMES,
-].map((name) => name.toLowerCase()));
+const MAIN_LOG_NAME_SET = new Set(MAIN_LOG_NAMES.map((name) => name.toLowerCase()));
+const HISTORY_LOG_NAME_PATTERNS = [
+    /^maa\.bak(?:\..+)?\.log$/i,
+    /^maafw\.bak(?:\..+)?\.log$/i,
+];
 const toPosixPath = (value) => value.replace(/\\/g, '/');
 const normalizeLowerPath = (value) => toPosixPath(value).toLowerCase();
 const isSearchTextFile = (normalizedPath) => {
     const lower = normalizedPath.toLowerCase();
     return SEARCH_TEXT_EXTENSIONS.some((ext) => lower.endsWith(ext));
 };
+const isHistoryLogName = (fileName) => {
+    return HISTORY_LOG_NAME_PATTERNS.some((pattern) => pattern.test(fileName));
+};
+const isCoreLogName = (fileName) => {
+    const lower = fileName.toLowerCase();
+    return MAIN_LOG_NAME_SET.has(lower) || isHistoryLogName(lower);
+};
 const decodeNodeBytes = (bytes) => {
     const encodings = ['utf-8', 'gbk', 'gb18030', 'gb2312'];
     for (const encoding of encodings) {
@@ -84,13 +92,11 @@ const isNeededZipEntry = (entryPath) => {
     const name = lower.slice(lower.lastIndexOf('/') + 1);
     if (isSearchTextFile(lower))
         return true;
-    if (MAIN_LOG_NAMES.includes(name))
+    if (isCoreLogName(name))
         return true;
-    if (BAK_LOG_NAMES.includes(name))
+    if ((lower.includes('/on_error/') || lower.startsWith('on_error/')) && lower.endsWith('.png'))
         return true;
-    if (lower.includes('/on_error/') && lower.endsWith('.png'))
-        return true;
-    if (lower.includes('/vision/') && lower.endsWith('.jpg'))
+    if ((lower.includes('/vision/') || lower.startsWith('vision/')) && lower.endsWith('.jpg'))
         return true;
     return false;
 };
@@ -100,11 +106,132 @@ const toZipReference = (sourceRef, entryPath) => {
 const toFileReference = (absolutePath) => {
     return `file:${toPosixPath(absolutePath)}`;
 };
+const isRelativeImagePath = (relativePath, directory, extension) => {
+    const normalized = relativePath.toLowerCase();
+    return normalized === `${directory}${extension}`
+        || normalized.startsWith(`${directory}/`)
+        || normalized.includes(`/${directory}/`);
+};
+const normalizeTimestampBoundary = (value) => {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.includes('.') ? trimmed : `${trimmed}.000`;
+};
+const extractTimestamps = (content) => {
+    const matches = content.match(/\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\]/g) ?? [];
+    return matches
+        .map((item) => item.slice(1, -1))
+        .map((item) => normalizeTimestampBoundary(item) ?? item);
+};
+const contentMatchesFocus = (content, focus) => {
+    const keywords = (focus.keywords ?? []).filter((keyword) => keyword.trim().length > 0);
+    if (keywords.length > 0 && !keywords.some((keyword) => content.includes(keyword))) {
+        return false;
+    }
+    const startedAfter = normalizeTimestampBoundary(focus.started_after);
+    const startedBefore = normalizeTimestampBoundary(focus.started_before);
+    if (!startedAfter && !startedBefore) {
+        return true;
+    }
+    return extractTimestamps(content).some((timestamp) => {
+        if (startedAfter && timestamp < startedAfter) {
+            return false;
+        }
+        if (startedBefore && timestamp > startedBefore) {
+            return false;
+        }
+        return true;
+    });
+};
+const joinMergedContent = (chunks) => {
+    return chunks.reduce((result, chunk) => {
+        if (chunk.length === 0)
+            return result;
+        if (result.length === 0)
+            return chunk;
+        return result.endsWith('\n') ? `${result}${chunk}` : `${result}\n${chunk}`;
+    }, '');
+};
+const rankLogPath = (filePath) => {
+    const baseName = path.basename(filePath).toLowerCase();
+    if (baseName === 'maafw.bak.log' || baseName.startsWith('maafw.bak.')) {
+        return 0;
+    }
+    if (baseName === 'maa.bak.log' || baseName.startsWith('maa.bak.')) {
+        return 1;
+    }
+    if (baseName === 'maafw.log') {
+        return 2;
+    }
+    if (baseName === 'maa.log') {
+        return 3;
+    }
+    return 10;
+};
+const sortLogPaths = (paths) => {
+    return [...paths].sort((left, right) => {
+        const rankDiff = rankLogPath(left) - rankLogPath(right);
+        if (rankDiff !== 0)
+            return rankDiff;
+        return left.localeCompare(right);
+    });
+};
+const collectFocusedFileContents = async (logPaths, focus) => {
+    const chunks = [];
+    for (const logPath of sortLogPaths(logPaths)) {
+        const content = await readNodeTextFileContent(logPath);
+        if (!contentMatchesFocus(content, focus))
+            continue;
+        chunks.push(content);
+    }
+    return joinMergedContent(chunks);
+};
+const collectFocusedZipContents = (entries, paths, basePath, focus) => {
+    const normalizedBasePath = normalizeLowerPath(basePath);
+    const candidatePaths = sortLogPaths(paths.filter((entryPath) => {
+        const normalizedPath = toPosixPath(entryPath);
+        const lastSlash = normalizedPath.lastIndexOf('/');
+        const parentPath = lastSlash === -1 ? '' : normalizedPath.slice(0, lastSlash);
+        if (normalizeLowerPath(parentPath) !== normalizedBasePath) {
+            return false;
+        }
+        const fileName = normalizedPath.slice(lastSlash + 1);
+        return isCoreLogName(fileName);
+    }));
+    const chunks = [];
+    for (const entryPath of candidatePaths) {
+        const bytes = entries[entryPath];
+        if (!bytes)
+            continue;
+        const content = decodeNodeBytes(bytes);
+        if (!contentMatchesFocus(content, focus))
+            continue;
+        chunks.push(content);
+    }
+    return joinMergedContent(chunks);
+};
+const buildDefaultZipContent = (entries, paths, basePath) => {
+    const bakLogName = BAK_LOG_NAMES.find((name) => findZipEntry(entries, paths, joinPath(basePath, name)));
+    const mainLogName = MAIN_LOG_NAMES.find((name) => findZipEntry(entries, paths, joinPath(basePath, name)));
+    const bakData = bakLogName ? findZipEntry(entries, paths, joinPath(basePath, bakLogName)) : null;
+    const mainData = mainLogName ? findZipEntry(entries, paths, joinPath(basePath, mainLogName)) : null;
+    const chunks = [];
+    if (bakData) {
+        chunks.push(decodeNodeBytes(bakData));
+    }
+    if (mainData) {
+        chunks.push(decodeNodeBytes(mainData));
+    }
+    return joinMergedContent(chunks);
+};
 export const readNodeTextFileContent = async (filePath) => {
     const bytes = await readFile(filePath);
     return decodeNodeBytes(new Uint8Array(bytes));
 };
-export const extractZipContentFromNodeBuffer = (zipData, sourceRef = 'memory.zip') => {
+export const extractZipContentFromNodeBuffer = (zipData, sourceRef = 'memory.zip', options = {}) => {
     const files = unzipSync(zipData, {
         filter: (entry) => isNeededZipEntry(entry.name),
     });
@@ -112,19 +239,9 @@ export const extractZipContentFromNodeBuffer = (zipData, sourceRef = 'memory.zip
     const basePath = findBaseDirectory(paths);
     if (basePath == null)
         return null;
-    const bakLogName = BAK_LOG_NAMES.find((name) => findZipEntry(files, paths, joinPath(basePath, name)));
-    const mainLogName = MAIN_LOG_NAMES.find((name) => findZipEntry(files, paths, joinPath(basePath, name)));
-    const bakData = bakLogName ? findZipEntry(files, paths, joinPath(basePath, bakLogName)) : null;
-    const mainData = mainLogName ? findZipEntry(files, paths, joinPath(basePath, mainLogName)) : null;
-    let content = '';
-    if (bakData) {
-        content += decodeNodeBytes(bakData);
-    }
-    if (mainData) {
-        if (content && !content.endsWith('\n'))
-            content += '\n';
-        content += decodeNodeBytes(mainData);
-    }
+    const content = options.focus
+        ? collectFocusedZipContents(files, paths, basePath, options.focus)
+        : buildDefaultZipContent(files, paths, basePath);
     if (!content)
         return null;
     const errorImages = new Map();
@@ -153,24 +270,26 @@ export const extractZipContentFromNodeBuffer = (zipData, sourceRef = 'memory.zip
                 waitFreezesImages.set(waitKey, toZipReference(sourceRef, normalizedPath));
             }
         }
-        if (isSearchTextFile(normalizedPath)) {
-            const fileData = files[currentPath];
-            if (!fileData)
-                continue;
-            textFiles.push({
-                path: normalizedPath,
-                name: fileName,
-                content: decodeNodeBytes(fileData),
-                reference: toZipReference(sourceRef, normalizedPath),
-            });
-        }
+        if (!isSearchTextFile(normalizedPath))
+            continue;
+        if (isCoreLogName(fileName))
+            continue;
+        const fileData = files[currentPath];
+        if (!fileData)
+            continue;
+        textFiles.push({
+            path: normalizedPath,
+            name: fileName,
+            content: decodeNodeBytes(fileData),
+            reference: toZipReference(sourceRef, normalizedPath),
+        });
     }
     textFiles.sort((a, b) => a.path.localeCompare(b.path));
     return { content, errorImages, visionImages, waitFreezesImages, textFiles };
 };
-export const extractZipContentFromNodeFile = async (zipFilePath) => {
+export const extractZipContentFromNodeFile = async (zipFilePath, options = {}) => {
     const bytes = await readFile(zipFilePath);
-    return extractZipContentFromNodeBuffer(new Uint8Array(bytes), zipFilePath);
+    return extractZipContentFromNodeBuffer(new Uint8Array(bytes), zipFilePath, options);
 };
 const pathExists = async (targetPath) => {
     try {
@@ -244,22 +363,26 @@ const pickPrimaryLogPath = async (debugPath, allFiles, candidates) => {
     }
     return null;
 };
-export const loadNodeLogDirectory = async (inputDirectoryPath) => {
-    const debugPath = await resolveDebugDirectory(inputDirectoryPath);
-    if (!debugPath)
-        return null;
-    const allFiles = await collectFilesRecursively(debugPath);
+const buildDefaultDirectoryContent = async (debugPath, allFiles) => {
     const bakLogPath = await pickPrimaryLogPath(debugPath, allFiles, BAK_LOG_NAMES);
     const mainLogPath = await pickPrimaryLogPath(debugPath, allFiles, MAIN_LOG_NAMES);
-    let content = '';
+    const chunks = [];
     if (bakLogPath) {
-        content += await readNodeTextFileContent(bakLogPath);
+        chunks.push(await readNodeTextFileContent(bakLogPath));
     }
     if (mainLogPath) {
-        if (content && !content.endsWith('\n'))
-            content += '\n';
-        content += await readNodeTextFileContent(mainLogPath);
+        chunks.push(await readNodeTextFileContent(mainLogPath));
     }
+    return joinMergedContent(chunks);
+};
+export const loadNodeLogDirectory = async (inputDirectoryPath, options = {}) => {
+    const debugPath = await resolveDebugDirectory(inputDirectoryPath);
+    if (!debugPath)
+        return null;
+    const allFiles = await collectFilesRecursively(debugPath);
+    const content = options.focus
+        ? await collectFocusedFileContents(allFiles.filter((filePath) => isCoreLogName(path.basename(filePath))), options.focus)
+        : await buildDefaultDirectoryContent(debugPath, allFiles);
     if (!content)
         return null;
     const errorImages = new Map();
@@ -270,14 +393,13 @@ export const loadNodeLogDirectory = async (inputDirectoryPath) => {
         const relativePath = toPosixPath(path.relative(debugPath, absolutePath));
         const lowerRelativePath = relativePath.toLowerCase();
         const fileName = path.basename(absolutePath);
-        const lowerFileName = fileName.toLowerCase();
-        if (lowerRelativePath.includes('/on_error/') && lowerRelativePath.endsWith('.png')) {
+        if (isRelativeImagePath(lowerRelativePath, 'on_error', '.png')) {
             const key = parseErrorImageKey(fileName);
             if (key) {
                 errorImages.set(key, toFileReference(absolutePath));
             }
         }
-        if (lowerRelativePath.includes('/vision/') && lowerRelativePath.endsWith('.jpg')) {
+        if (isRelativeImagePath(lowerRelativePath, 'vision', '.jpg')) {
             const visionKey = parseVisionImageKey(fileName);
             if (visionKey) {
                 visionImages.set(visionKey, toFileReference(absolutePath));
@@ -289,7 +411,7 @@ export const loadNodeLogDirectory = async (inputDirectoryPath) => {
         }
         if (!isSearchTextFile(relativePath))
             continue;
-        if (PRIMARY_LOG_NAME_SET.has(lowerFileName))
+        if (isCoreLogName(fileName))
             continue;
         textFiles.push({
             path: relativePath,

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@windsland52/maa-log-tools",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "type": "module",
   "private": false,
-  "scripts": {
-    "typecheck": "tsc -p ./tsconfig.json",
-    "build": "pnpm run clean && tsc -p ./tsconfig.build.json && node ../../scripts/fix-esm-imports.mjs ./dist",
-    "clean": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\""
-  },
   "bin": {
     "mla-log-tools": "./dist/cli.js"
   },
@@ -46,11 +41,11 @@
     }
   },
   "dependencies": {
-    "@windsland52/maa-log-adapter": "workspace:*",
-    "@windsland52/maa-log-kernel": "workspace:*",
-    "@windsland52/maa-log-parser": "workspace:*",
-    "@windsland52/maa-log-runtime": "workspace:*",
-    "fflate": "^0.8.2"
+    "fflate": "^0.8.2",
+    "@windsland52/maa-log-adapter": "1.0.0",
+    "@windsland52/maa-log-kernel": "1.0.0",
+    "@windsland52/maa-log-runtime": "1.0.0",
+    "@windsland52/maa-log-parser": "1.0.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -61,5 +56,15 @@
   "files": [
     "dist",
     "README.md"
-  ]
-}
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaaXYZ/MaaLogAnalyzer",
+    "directory": "packages/maa-log-tools"
+  },
+  "scripts": {
+    "typecheck": "tsc -p ./tsconfig.json",
+    "build": "pnpm run clean && tsc -p ./tsconfig.build.json && node ../../scripts/fix-esm-imports.mjs ./dist",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\""
+  }
+}