evolcore 0.0.27 → 0.0.29-test.0

package/dist/utils/cross-platform.js

@@ -6,6 +6,7 @@ import { promisify } from 'util';
 import fs from 'fs';
 import { getProcessStartTime, parseCimDate } from './process-introspect.js';
 import { decodeWindowsOutput } from './windows-output.js';
+import { resolveTrustedWindowsCmdPath } from './windows-shell-trust.js';
 const execFileAsync = promisify(execFile);
 const CLI_PROBE_FAILURE_BACKOFF_MS = 5_000;
 const CLI_PROBE_PACKAGES = {
@@ -17,9 +18,70 @@ const cliPathCache = new Map();
 const cliInstallationCache = new Map();
 const cliProbeCache = new Map();
 export const isWindows = process.platform === 'win32';
+// Keep this in sync with the Windows command-line metacharacters. The whole
+// `/c` expression is passed as one verbatim argument so paths with spaces and
+// shim-forwarded values such as `%`, `!`, `&`, and quotes stay data.
+const WINDOWS_CMD_META_RE = /([()[\]%!^"`<>&|;, *?])/g;
+function escapeWindowsCmdCommand(value) {
+    return value.replace(WINDOWS_CMD_META_RE, '^$1');
+}
+function escapeWindowsCmdArgument(value) {
+    let escaped = String(value);
+    escaped = escaped.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    escaped = escaped.replace(/(?=(\\+?)?)\1$/g, '$1$1');
+    escaped = `"${escaped}"`;
+    return escaped.replace(WINDOWS_CMD_META_RE, '^$1');
+}
+/** Build one argv-based CLI launch without consulting the parent terminal. */
+export function buildCliLaunchCommand(executable, args, options = {}) {
+    const windows = options.isWindows ?? isWindows;
+    const extension = windows ? path.win32.extname(executable).toLowerCase() : '';
+    const shim = extension === '.cmd' || extension === '.bat';
+    if (!shim) {
+        return {
+            command: executable,
+            args,
+            resolvedPath: executable,
+            launcherKind: 'native-exe',
+            launcherPath: executable,
+        };
+    }
+    const resolveWindowsCmd = options.resolveWindowsCmd ?? resolveTrustedWindowsCmdPath;
+    const launcherPath = resolveWindowsCmd(options.comSpec);
+    if (!launcherPath) {
+        throw Object.assign(new Error('未找到受信任的系统 cmd.exe，已拒绝启动 Windows CLI shim'), {
+            code: 'EACCES',
+            path: executable,
+        });
+    }
+    const shellCommand = [
+        escapeWindowsCmdCommand(executable),
+        ...args.map(escapeWindowsCmdArgument),
+    ].join(' ');
+    return {
+        command: launcherPath,
+        args: ['/d', '/s', '/v:off', '/c', `"${shellCommand}"`],
+        resolvedPath: executable,
+        launcherKind: extension === '.cmd' ? 'cmd-shim' : 'bat-shim',
+        launcherPath,
+        windowsVerbatimArguments: true,
+    };
+}
 /** Resolve a CLI executable without spawning where/which. */
 export function resolveProbePath(command) {
-    const pathKey = `${command}\0${process.cwd()}\0${process.env.PATH ?? ''}\0${process.env.PATHEXT ?? ''}`;
+    const extensions = isWindows
+        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(ext => /\.(com|exe|bat|cmd)$/i.test(ext))
+        : [''];
+    return resolveProbePathWithExtensions(command, extensions, 'executable');
+}
+/** Diagnose an incomplete npm installation without ever executing its PS1 shim. */
+export function resolvePowerShellShimPath(command) {
+    if (!isWindows)
+        return null;
+    return resolveProbePathWithExtensions(command, ['.ps1'], 'powershell-shim');
+}
+function resolveProbePathWithExtensions(command, extensions, cacheKind) {
+    const pathKey = `${cacheKind}\0${command}\0${process.cwd()}\0${process.env.PATH ?? ''}\0${extensions.join(';')}`;
     const cachedPath = cliPathCache.get(pathKey);
     if (cachedPath && fs.existsSync(cachedPath))
         return cachedPath;
@@ -27,9 +89,6 @@ export function resolveProbePath(command) {
     const directories = (process.env.PATH ?? '').split(path.delimiter);
     if (isWindows)
         directories.unshift(process.cwd());
-    const extensions = isWindows
-        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(ext => /\.(com|exe|bat|cmd)$/i.test(ext))
-        : [''];
     for (const directory of directories) {
         for (const extension of extensions) {
             const candidate = path.resolve(directory.replace(/^"|"$/g, ''), command + extension);
@@ -98,20 +157,25 @@ export function invalidateCliProbes() {
 function cliProbeTimeouts(command, options) {
     return options.timeouts?.length ? options.timeouts : command === 'codex' ? [3_000, 15_000] : [3_000];
 }
-function prepareCliProbe(command, args) {
-    const executable = resolveProbePath(command);
+function prepareCliProbe(command, args, options = {}) {
+    const executable = options.executable ?? resolveProbePath(command);
     if (!executable)
         throw Object.assign(new Error(`${command} CLI not found`), { code: 'ENOENT' });
-    const identity = `${probeInstallationIdentity(command, executable)}|${process.env.ComSpec ?? ''}`;
+    const launchCommand = buildCliLaunchCommand(executable, args);
+    const launch = launchCommand;
+    const identity = `${probeInstallationIdentity(command, executable)}|${cliFileIdentity(launch.launcherPath)}`;
     const key = JSON.stringify([command, args]);
     let entry = cliProbeCache.get(key);
     if (!entry || entry.identity !== identity || (entry.retryAt !== undefined && Date.now() >= entry.retryAt)) {
         entry = { identity };
         cliProbeCache.set(key, entry);
     }
-    const shim = isWindows && /\.(cmd|bat)$/i.test(executable);
-    return { entry, command: shim ? process.env.ComSpec ?? 'cmd.exe' : executable,
-        args: shim ? ['/d', '/s', '/c', executable, ...args] : args };
+    return {
+        entry,
+        command: launchCommand.command,
+        args: launchCommand.args,
+        launch,
+    };
 }
 function failCliProbe(entry, error) {
     entry.error = error;
@@ -119,7 +183,7 @@ function failCliProbe(entry, error) {
     throw error;
 }
 export function probeCliSync(command, args, options = {}) {
-    const request = prepareCliProbe(command, args);
+    const request = prepareCliProbe(command, args, options);
     if (request.entry.output !== undefined)
         return request.entry.output;
     if (request.entry.error !== undefined)
@@ -127,10 +191,14 @@ export function probeCliSync(command, args, options = {}) {
     for (const [index, timeout] of cliProbeTimeouts(command, options).entries()) {
         const startedAt = Date.now();
         try {
-            return request.entry.output = execFileSync(request.command, request.args, { encoding: 'utf8', timeout, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+            return request.entry.output = execFileSync(request.command, request.args, {
+                encoding: 'utf8', timeout, windowsHide: true,
+                windowsVerbatimArguments: request.launch.windowsVerbatimArguments,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
         }
         catch (error) {
-            options.onFailure?.(args, startedAt, error, timeout);
+            options.onFailure?.(args, startedAt, error, timeout, request.launch);
             if (error.code !== 'ETIMEDOUT' || index === cliProbeTimeouts(command, options).length - 1)
                 return failCliProbe(request.entry, error);
         }
@@ -138,7 +206,7 @@ export function probeCliSync(command, args, options = {}) {
     throw new Error('CLI probe exhausted');
 }
 export async function probeCli(command, args, options = {}) {
-    const request = prepareCliProbe(command, args);
+    const request = prepareCliProbe(command, args, options);
     if (request.entry.output !== undefined)
         return request.entry.output;
     if (request.entry.error !== undefined)
@@ -151,7 +219,10 @@ export async function probeCli(command, args, options = {}) {
             const startedAt = Date.now();
             try {
                 const output = await new Promise((resolve, reject) => {
-                    const child = execFile(request.command, request.args, { encoding: 'utf8', timeout, windowsHide: true }, (error, stdout, stderr) => {
+                    const child = execFile(request.command, request.args, {
+                        encoding: 'utf8', timeout, windowsHide: true,
+                        windowsVerbatimArguments: request.launch.windowsVerbatimArguments,
+                    }, (error, stdout, stderr) => {
                         if (error) {
                             if (error.killed && error.signal === 'SIGTERM' && error.code == null)
                                 error.code = 'ETIMEDOUT';
@@ -166,7 +237,7 @@ export async function probeCli(command, args, options = {}) {
                 return request.entry.output = output;
             }
             catch (error) {
-                options.onFailure?.(args, startedAt, error, timeout);
+                options.onFailure?.(args, startedAt, error, timeout, request.launch);
                 if (error.code !== 'ETIMEDOUT' || index === timeouts.length - 1)
                     return failCliProbe(request.entry, error);
             }

package/dist/utils/error-dict.json

@@ -109,19 +109,22 @@
       "id": "api-error-502",
       "match": "api error: 502",
       "action": "retry",
-      "type": "api_error"
+      "type": "api_error",
+      "message": "❌ API 网关异常，请稍后重试"
     },
     {
       "id": "api-error-503",
       "match": "api error: 503",
       "action": "retry",
-      "type": "api_error"
+      "type": "api_error",
+      "message": "❌ API 服务暂时不可用，请稍后重试"
     },
     {
       "id": "api-error-504",
       "match": "api error: 504",
       "action": "retry",
-      "type": "api_error"
+      "type": "api_error",
+      "message": "❌ API 请求超时，请稍后重试"
     },
     {
       "id": "not-valid-json",

package/dist/utils/error-utils.js

@@ -25,6 +25,7 @@ export function isExecutionFailure(error) {
     return error instanceof ExecutionTimeoutError || error instanceof OrphanedTargetSessionError;
 }
 export const CLAUDE_STARTUP_ARGUMENTS_TOO_LONG = 'claude_startup_arguments_too_long';
+export const CLAUDE_CODE_STARTUP_FAILED = 'claude_code_startup_failed';
 /** A completed provider response exhausted its output budget, rather than a transport failure. */
 export function isOutputTokenLimitError(error) {
     const record = error && typeof error === 'object' ? error : undefined;
@@ -58,6 +59,22 @@ export function createClaudeStartupArgumentsTooLongError(error) {
         wrapped.cause = error;
     return wrapped;
 }
+export function isClaudeCodeStartupProcessError(error) {
+    const record = error && typeof error === 'object' ? error : undefined;
+    const code = String(record?.code ?? '').toLowerCase();
+    const message = String(record?.message ?? error ?? '').toLowerCase();
+    return code === 'eftype'
+        || message.includes('spawn eftype')
+        || message.includes('not a valid application for this os platform');
+}
+export function createClaudeCodeStartupError(error) {
+    const wrapped = new Error(`${CLAUDE_CODE_STARTUP_FAILED}: Claude Code SDK 本地运行时启动失败，任务未执行`);
+    wrapped.name = 'ClaudeCodeStartupError';
+    wrapped.code = CLAUDE_CODE_STARTUP_FAILED;
+    if (error !== undefined)
+        wrapped.cause = error;
+    return wrapped;
+}
 export var ErrorType;
 (function (ErrorType) {
     ErrorType["SDK_TIMEOUT"] = "sdk_timeout";
@@ -71,6 +88,7 @@ export var ErrorType;
     ErrorType["SESSION_UNAVAILABLE"] = "session_unavailable";
     ErrorType["SANDBOX_INITIALIZATION_FAILED"] = "sandbox_initialization_failed";
     ErrorType["CLAUDE_STARTUP_ARGUMENTS_TOO_LONG"] = "claude_startup_arguments_too_long";
+    ErrorType["CLAUDE_CODE_STARTUP_FAILED"] = "claude_code_startup_failed";
     ErrorType["UNKNOWN"] = "unknown";
 })(ErrorType || (ErrorType = {}));
 /**
@@ -329,6 +347,9 @@ export function classifyError(error) {
     if (isClaudeStartupArgumentsTooLong(error)) {
         return ErrorType.CLAUDE_STARTUP_ARGUMENTS_TOO_LONG;
     }
+    if (error?.code === CLAUDE_CODE_STARTUP_FAILED) {
+        return ErrorType.CLAUDE_CODE_STARTUP_FAILED;
+    }
     // 字典优先 — 命中则直接返回
     const rule = matchErrorRule(msg);
     if (rule) {
@@ -410,6 +431,10 @@ export function getErrorMessage(error, terminalReason, includeEmoji = true) {
         const prefix = includeEmoji ? '⚠️ ' : '';
         return `${prefix}当前 Claude 启动参数过长，任务未执行`;
     }
+    if (error?.code === CLAUDE_CODE_STARTUP_FAILED) {
+        const prefix = includeEmoji ? '❌ ' : '';
+        return `${prefix}Claude Code SDK 本地运行时启动失败（${CLAUDE_CODE_STARTUP_FAILED}），当前任务未执行。请重新安装并对齐 Claude Code SDK 与 Windows 原生组件版本，然后重启 EvolCore 后重试`;
+    }
     // terminalReason 提供更精确的错误提示（SDK 0.2.100+）
     if (terminalReason) {
         const prefix = includeEmoji ? '❌ ' : '';
@@ -433,6 +458,8 @@ export function getErrorMessage(error, terminalReason, includeEmoji = true) {
                 return `${warnPrefix}执行沙箱启动失败（sandbox_initialization_failed），当前操作未执行；请检查文件系统挂载规则及 user namespace/seccomp 配置`;
             case 'claude_startup_arguments_too_long':
                 return `${warnPrefix}当前 Claude 启动参数过长，任务未执行`;
+            case 'claude_code_startup_failed':
+                return `${prefix}Claude Code SDK 本地运行时启动失败（${CLAUDE_CODE_STARTUP_FAILED}），当前任务未执行。请重新安装并对齐 Claude Code SDK 与 Windows 原生组件版本，然后重启 EvolCore 后重试`;
             case 'aborted_streaming':
             case 'aborted_tools':
                 return `${prefix}任务已中断`;

package/dist/utils/logger.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import { resolvePaths } from '../paths.js';
 import { LogWriter } from './log-writer.js';
-import { classifyToolErrorCode, normalizeToolErrorCode } from '../core/permission/tool-error-code.js';
+import { normalizeToolErrorClassification } from '../core/permission/tool-error-code.js';
 import { normalizePermissionMode } from '../core/permission/mode.js';
 import { buildToolLifecycleEventKey, normalizeToolCorrelation } from '../core/audit/event-key.js';
 let currentLevel = process.env.LOG_LEVEL || 'INFO';
@@ -114,21 +114,40 @@ export function normalizeStructuredLog(data) {
         ?? (isToolResult && isError === true ? 'error' : undefined)
         ?? (isToolResult && isError === false ? 'allow' : undefined)
         ?? (isToolUse ? 'pending' : undefined);
-    const executed = data.executed ?? nested?.executed
+    const explicitExecuted = data.executed ?? nested?.executed;
+    const explicitExecutionState = data.executionState ?? data.execution_state
+        ?? nested?.executionState ?? nested?.execution_state;
+    const executed = explicitExecuted
         ?? (isToolResult ? true : isToolUse ? false : undefined);
-    const executionState = data.executionState ?? data.execution_state
-        ?? nested?.executionState ?? nested?.execution_state
+    const executionState = explicitExecutionState
         ?? (isToolResult ? (isError === true ? 'failed' : 'completed') : isToolUse ? 'requested' : undefined);
+    const exitCode = data.exitCode ?? data.exit_code ?? nested?.exitCode ?? nested?.exit_code;
     const explicitErrorCode = data.errorCode
         ?? data.error_code
         ?? nested?.errorCode
         ?? nested?.error_code;
-    const errorCode = isToolResult && isError === true
-        ? classifyToolErrorCode({ errorCode: explicitErrorCode, decisionSource })
-        : explicitErrorCode;
-    const classificationMissing = isToolResult && isError === true
-        && !normalizeToolErrorCode(explicitErrorCode)
-        && decisionSource !== 'policy' && decisionSource !== 'approval';
+    const explicitErrorDetailCode = data.errorDetailCode
+        ?? data.detailCode
+        ?? data.detail_code
+        ?? nested?.errorDetailCode
+        ?? nested?.detailCode
+        ?? nested?.detail_code;
+    const classification = isToolResult && isError === true
+        ? normalizeToolErrorClassification({
+            errorCode: explicitErrorCode,
+            errorDetailCode: explicitErrorDetailCode,
+            decisionSource,
+            executed: explicitExecuted,
+            executionState: explicitExecutionState,
+            exitCode,
+            policyCode: data.policyCode ?? nested?.policyCode,
+        })
+        : undefined;
+    const errorCode = classification?.errorCode ?? explicitErrorCode;
+    const errorDetailCode = classification?.errorDetailCode
+        ?? (typeof explicitErrorDetailCode === 'string' ? explicitErrorDetailCode : undefined);
+    const classificationMissing = classification?.classificationMissing || data.classificationMissing === true || nested?.classificationMissing === true;
+    const classificationConflict = classification?.classificationConflict || data.classificationConflict === true || nested?.classificationConflict === true;
     const lifecycleEventKey = lifecycleRecord
         ? (eventKey ?? buildToolLifecycleEventKey({
             sessionId,
@@ -155,7 +174,10 @@ export function normalizeStructuredLog(data) {
         ...(executed !== undefined ? { executed } : {}),
         ...(executionState ? { executionState } : {}),
         ...(errorCode ? { errorCode } : {}),
+        ...(errorDetailCode ? { errorDetailCode } : {}),
+        ...(exitCode !== undefined ? { exitCode } : {}),
         ...(classificationMissing ? { classificationMissing: true } : {}),
+        ...(classificationConflict ? { classificationConflict: true } : {}),
         ...(missingContextFields.length > 0 ? { contextMissing: missingContextFields } : {}),
     };
 }

package/dist/utils/media-cache.js

@@ -11,6 +11,9 @@ import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
 import { logger } from './logger.js';
+import { agentRelationDir } from '../paths.js';
+import { parsePeerKey } from '../core/relation/peer-identity.js';
+import { isSameOrDescendant } from '../core/permission/protected-paths.js';
 // ── 常量 ──────────────────────────────────────────────────────────────────────
 const DEFAULT_MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
 const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
@@ -18,6 +21,14 @@ const ALLOWED_IMAGE_MIMES = new Set([
     'image/png', 'image/jpeg', 'image/gif', 'image/webp',
 ]);
 const UPLOADS_SUBDIR = '.evolcore/uploads';
+const RELATION_ATTACHMENT_ID_RE = /^[a-f0-9]{32}$/;
+const RELATION_ATTACHMENT_MAX_BYTES = DEFAULT_MAX_FILE_SIZE;
+const RELATION_ATTACHMENT_EXTENSIONS = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+};
 // ── SSRF 防护 ─────────────────────────────────────────────────────────────────
 /** 已知安全的 CDN 域名白名单 */
 const ALLOWED_CDN_HOSTS = new Set([
@@ -101,6 +112,79 @@ export async function validateImage(buffer, opts) {
     }
     return { mime: type.mime };
 }
+function relationAttachmentsDir(selfAid, peerKey) {
+    parsePeerKey(peerKey);
+    return path.join(agentRelationDir(selfAid, peerKey), 'attachments');
+}
+/** Save one inbound image as a stable, peer-scoped attachment owned by the daemon. */
+export function saveRelationAttachment(buffer, selfAid, peerKey, mimeType) {
+    const extension = RELATION_ATTACHMENT_EXTENSIONS[mimeType];
+    if (!extension)
+        throw new Error(`Unsupported relation attachment MIME type: ${mimeType}`);
+    if (buffer.length < 1 || buffer.length > RELATION_ATTACHMENT_MAX_BYTES) {
+        throw new Error(`Relation attachment must be between 1 byte and ${RELATION_ATTACHMENT_MAX_BYTES} bytes`);
+    }
+    const directory = relationAttachmentsDir(selfAid, peerKey);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        fs.chmodSync(directory, 0o700);
+    const attachmentId = crypto.randomBytes(16).toString('hex');
+    const filename = `${attachmentId}${extension}`;
+    const filePath = path.join(directory, filename);
+    const metadataPath = path.join(directory, `${attachmentId}.json`);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    const metadata = {
+        version: 1, attachmentId, selfAid, peerKey, filename, mimeType,
+        sha256, size: buffer.length, createdAt: Date.now(),
+    };
+    fs.writeFileSync(filePath, buffer, { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(metadataPath, JSON.stringify(metadata), { flag: 'wx', mode: 0o600 });
+    return { ...metadata, filePath };
+}
+/** Resolve an attachment only inside the authenticated Agent/peer relation. */
+export function readRelationAttachment(selfAid, peerKey, attachmentSource) {
+    const attachmentId = RELATION_ATTACHMENT_ID_RE.test(attachmentSource)
+        ? attachmentSource
+        : path.basename(attachmentSource, path.extname(attachmentSource));
+    if (!RELATION_ATTACHMENT_ID_RE.test(attachmentId))
+        throw new Error('Invalid attachment ID');
+    const directory = relationAttachmentsDir(selfAid, peerKey);
+    const metadataPath = path.join(directory, `${attachmentId}.json`);
+    const metadataStat = fs.lstatSync(metadataPath);
+    if (!metadataStat.isFile() || metadataStat.isSymbolicLink())
+        throw new Error('Attachment metadata must be a regular file');
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    if (metadata.version !== 1 || metadata.attachmentId !== attachmentId
+        || metadata.selfAid !== selfAid || metadata.peerKey !== peerKey
+        || RELATION_ATTACHMENT_EXTENSIONS[metadata.mimeType] === undefined
+        || metadata.filename !== `${attachmentId}${RELATION_ATTACHMENT_EXTENSIONS[metadata.mimeType]}`) {
+        throw new Error('Attachment ownership metadata mismatch');
+    }
+    const filePath = path.join(directory, metadata.filename);
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== metadata.size
+        || stat.size < 1 || stat.size > RELATION_ATTACHMENT_MAX_BYTES) {
+        throw new Error('Attachment file is missing or invalid');
+    }
+    const realDirectory = fs.realpathSync(directory);
+    const realPath = fs.realpathSync(filePath);
+    if (!isSameOrDescendant(realPath, realDirectory))
+        throw new Error('Attachment path escaped its relation directory');
+    if (path.isAbsolute(attachmentSource) && fs.realpathSync(attachmentSource) !== realPath) {
+        throw new Error('Attachment path does not match the current relation');
+    }
+    const buffer = fs.readFileSync(filePath);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    if (sha256 !== metadata.sha256)
+        throw new Error('Attachment content hash mismatch');
+    return {
+        attachment: {
+            attachmentId, selfAid, peerKey, filePath: realPath,
+            mimeType: metadata.mimeType, sha256, size: buffer.length,
+        },
+        buffer,
+    };
+}
 /**
  * 把已下载的附件 Buffer 转成入站图片条目（供 baseagent 视觉通道）。
  *

package/dist/utils/msg-diag.js

@@ -0,0 +1,97 @@
+/**
+ * msg-diag: 消息生命周期诊断打点
+ * 各处理环节调用 diagLog()，写入专用 msg-diag.jsonl。
+ * ec watch diag 读取该文件，固定行实时展示各环节最新处理的消息。
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+function getLogPath() {
+    const home = process.env.EVOLCORE_HOME ?? path.join(os.homedir(), '.evolcore');
+    return path.join(home, 'logs', 'msg-diag.jsonl');
+}
+let _logPath = null;
+let _fd = null;
+const MAX_SIZE = 500 * 1024; // 500 KB
+const TRIM_SIZE = 250 * 1024; // 超限后保留最后 250 KB
+function trimIfNeeded(p) {
+    try {
+        const stat = fs.statSync(p);
+        if (stat.size <= MAX_SIZE)
+            return;
+        // 读最后 TRIM_SIZE 字节，从第一个完整行开始保留
+        const fd = fs.openSync(p, 'r');
+        const buf = Buffer.alloc(TRIM_SIZE);
+        fs.readSync(fd, buf, 0, TRIM_SIZE, stat.size - TRIM_SIZE);
+        fs.closeSync(fd);
+        const str = buf.toString('utf-8');
+        const firstNl = str.indexOf('\n');
+        const kept = firstNl >= 0 ? str.slice(firstNl + 1) : str;
+        fs.writeFileSync(p, kept, 'utf-8');
+    }
+    catch {
+        // 修剪失败不阻塞主流程
+    }
+}
+function getFd() {
+    try {
+        if (!_logPath)
+            _logPath = getLogPath();
+        const dir = path.dirname(_logPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        // 每次写前检查大小，超限则修剪并重新打开
+        if (_fd !== null) {
+            try {
+                const stat = fs.statSync(_logPath);
+                if (stat.size > MAX_SIZE) {
+                    fs.closeSync(_fd);
+                    _fd = null;
+                    trimIfNeeded(_logPath);
+                }
+            }
+            catch {
+                fs.closeSync(_fd);
+                _fd = null;
+            }
+        }
+        if (_fd === null) {
+            _fd = fs.openSync(_logPath, 'a');
+        }
+        return _fd;
+    }
+    catch {
+        return null;
+    }
+}
+function shortId(id) {
+    if (!id)
+        return '';
+    return id.split('.')[0];
+}
+function cut(text, n) {
+    if (!text)
+        return '';
+    const s = text.replace(/\r?\n/g, ' ').trim();
+    return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+export function diagLog(stage, data) {
+    try {
+        const entry = {
+            stage,
+            ts: new Date().toISOString(),
+            aid: shortId(data.aid ?? ''),
+            from: shortId(data.from ?? ''),
+            to: shortId(data.to ?? ''),
+            msgId: data.msgId ?? '',
+            taskId: data.taskId,
+            preview: cut(data.text ?? '', 50),
+        };
+        const fd = getFd();
+        if (fd !== null)
+            fs.writeSync(fd, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // 诊断打点失败不影响主流程
+    }
+}