@cueai/omni-reader-mcp 1.1.1 → 1.1.3

package/README.md

@@ -33,17 +33,33 @@ Bridge 运行时只使用以下产品配置：
 始终使用已审核的精确版本，不使用隐式 `latest`：
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.1 setup
+npx -y @cueai/omni-reader-mcp@1.1.3 setup
 ```
 
 交互 setup 支持 Hermes、Cursor、Claude Desktop 和通用 stdio 配置。非交互安装使用同一参数解析和写入逻辑：
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.1 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.1.1 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.1.1 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.3 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.3 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.3 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
+Agent/脚本在 pty 下运行（stdin 仍是 TTY）时，用 `--headless`（别名 `--non-interactive`）显式声明非交互，无需 `--yes` 且绝不读 stdin：
+
+```sh
+npx -y @cueai/omni-reader-mcp@1.1.3 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+```
+
+## 缓存与 journal 隔离
+
+本地解析缓存与操作 journal 默认位于用户级缓存目录（macOS `~/Library/Caches/cue/omni-reader-mcp`、Windows `%LOCALAPPDATA%\Cue\omni-reader-mcp\Cache`、Linux `~/.cache/cue/omni-reader-mcp`）。若 Agent 的文件监视器（如 WorkBuddy）锁定该目录下的文件导致写入失败，设置 `OMNI_CACHE_DIR` 将缓存与 journal 一起隔离到不被监视的目录：
+
+```sh
+export OMNI_CACHE_DIR=/var/cache/omni-reader
+```
+
+显式 `OMNI_CACHE_DIR` 不会被项目重叠检查改写到临时目录；仍禁止与项目目录互相包含。
+
 setup 会：
 
 1. 展示 user-scope 配置目标和变更；
@@ -73,7 +89,14 @@ Agent 将用户提供的来源字符串直接传给 `parse(source)`：
 - `read_result`
 - `discard_result`
 
-每个工具都返回 `structuredContent` 和严格 `outputSchema`。
+每个工具都返回 `structuredContent` 和严格 `outputSchema`，同时为只读取传统 MCP `content[].text` 的客户端提供等价回退：
+
+- `parse` 完成且结果可 inline 时，text 直接返回完整 Markdown；
+- processing、artifact、cleanup、cancel、expired 和 failure 状态，text 返回与 `structuredContent` 字段等价的紧凑 JSON；
+- `read_result` 的 text JSON 包含本次 `result.text` 和可选 `next_cursor`，客户端必须追完所有 cursor 后再拼接正文；
+- `discard_result` 的 text JSON 明确返回 `discarded`，不得仅凭调用成功宣称结果已删除。
+
+这使不展示 `structuredContent` 的客户端也能取得 operation/result 句柄和完整正文，同时不改变支持结构化结果的客户端契约。
 
 ## 前台、后台和进度
 
@@ -112,23 +135,23 @@ Agent 不应自动拆分、转码或上传公共站点；应请用户提供符
 ## 命令
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.1 doctor
-npx -y @cueai/omni-reader-mcp@1.1.1 doctor --json
-npx -y @cueai/omni-reader-mcp@1.1.1 clean
-npx -y @cueai/omni-reader-mcp@1.1.1 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.3 doctor
+npx -y @cueai/omni-reader-mcp@1.1.3 doctor --json
+npx -y @cueai/omni-reader-mcp@1.1.3 clean
+npx -y @cueai/omni-reader-mcp@1.1.3 uninstall --yes --json
 ```
 
 不带命令运行固定版本会启动 stdio MCP server：
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.1
+npx -y @cueai/omni-reader-mcp@1.1.3
 ```
 
 `doctor --json` 返回 package/npm/client adapter、Key present/absent、allowed-root 安全状态、endpoint compatibility、artifact、cache mode、onboarding 和 reload 状态；不会输出 Key、私有来源路径或内容。
 
 ## 卸载与回滚
 
-`uninstall --yes --json` 只删除当前受信的 1.1.1 Bridge entry；存在匹配的可信备份时恢复原 URL-only `omni-reader` entry。卸载不会删除用户源文件，也不会静默删除未过期的本地结果。
+`uninstall --yes --json` 只删除当前受信的 1.1.3 Bridge entry；存在匹配的可信备份时恢复原 URL-only `omni-reader` entry。卸载不会删除用户源文件，也不会静默删除未过期的本地结果。
 
 需要回滚 1.1.1 时：
 

package/dist/artifact-store.d.ts

@@ -44,6 +44,7 @@ export interface ArtifactReadResult {
 interface ArtifactFinalizeInput extends ReleasedMetadata {
     readonly resultId: string;
 }
+export declare function syncDirectory(directory: string, platform?: NodeJS.Platform): Promise<void>;
 export declare function defaultArtifactRoot(options?: DefaultArtifactRootOptions): string;
 export declare function selectArtifactRoot(options: SelectArtifactRootOptions): Promise<SelectedArtifactRoot>;
 export declare class ArtifactStore {

package/dist/artifact-store.js

@@ -53,14 +53,21 @@ async function removeIfPresent(filePath) {
         throw error;
     }
 }
-async function syncDirectory(directory) {
+export async function syncDirectory(directory, platform = process.platform) {
+    // Windows cannot fsync a directory handle: opening a directory with
+    // O_RDONLY raises EPERM. File fsync still provides primary durability.
+    if (platform === "win32")
+        return;
     let handle;
     try {
         handle = await open(directory, "r");
         await handle.sync();
     }
     catch (error) {
-        if (!errno(error, "EINVAL") && !errno(error, "ENOTSUP") && !errno(error, "EISDIR")) {
+        if (!errno(error, "EINVAL") &&
+            !errno(error, "ENOTSUP") &&
+            !errno(error, "EISDIR") &&
+            !errno(error, "EPERM")) {
             throw error;
         }
     }
@@ -232,6 +239,14 @@ export function defaultArtifactRoot(options = {}) {
     const platform = options.platform ?? process.platform;
     const homeDirectory = options.homeDirectory ?? os.homedir();
     const env = options.env ?? process.env;
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const configured = env.OMNI_CACHE_DIR;
+    if (configured !== undefined && configured.length > 0) {
+        // Explicit isolation: Agents' file watchers lock files under the default
+        // cache (WorkBuddy dogfood). An explicit root skips the overlap fallback;
+        // ArtifactStore.open still rejects a project-inside-cache layout.
+        return paths.resolve(configured);
+    }
     if (platform === "darwin") {
         return path.posix.join(homeDirectory, "Library", "Caches", "cue", "omni-reader-mcp");
     }
@@ -287,12 +302,14 @@ function selectionPathsOverlap(left, right, platform) {
 export async function selectArtifactRoot(options) {
     const platform = options.platform ?? process.platform;
     const rootDirectory = defaultArtifactRoot(options);
+    const env = options.env ?? process.env;
+    const explicitRoot = env.OMNI_CACHE_DIR !== undefined && env.OMNI_CACHE_DIR.length > 0;
     const [rootIdentity, projectIdentity, homeIdentity] = await Promise.all([
         selectionPathIdentity(rootDirectory, platform),
         selectionPathIdentity(options.projectDirectory, platform),
         selectionPathIdentity(options.homeDirectory ?? os.homedir(), platform),
     ]);
-    if (!selectionPathsOverlap(rootIdentity, projectIdentity, platform)) {
+    if (explicitRoot || !selectionPathsOverlap(rootIdentity, projectIdentity, platform)) {
         return { mode: "default", rootDirectory };
     }
     const paths = platform === "win32" ? path.win32 : path.posix;

package/dist/cli/arguments.d.ts

@@ -4,6 +4,7 @@ export interface SetupArguments {
     readonly allowedRoots: readonly string[];
     readonly addRoots: readonly string[];
     readonly yes: boolean;
+    readonly headless: boolean;
     readonly json: boolean;
 }
 export type ParsedCommand = {

package/dist/cli/arguments.js

@@ -32,12 +32,13 @@ function parseSetupArguments(values, platform) {
     let allowedRoot;
     let addRoot;
     let yes = false;
+    let headless = false;
     let json = false;
     const seen = new Set();
     const paths = pathsFor(platform);
     for (let index = 0; index < values.length; index += 1) {
         const flag = values[index];
-        if (!["--client", "--allowed-root", "--add-root", "--yes", "--json"].includes(flag)) {
+        if (!["--client", "--allowed-root", "--add-root", "--yes", "--headless", "--non-interactive", "--json"].includes(flag)) {
             throw new CliUsageError(`Unknown setup flag: ${flag}`);
         }
         if (seen.has(flag))
@@ -47,6 +48,10 @@ function parseSetupArguments(values, platform) {
             yes = true;
             continue;
         }
+        if (flag === "--headless" || flag === "--non-interactive") {
+            headless = true;
+            continue;
+        }
         if (flag === "--json") {
             json = true;
             continue;
@@ -83,6 +88,7 @@ function parseSetupArguments(values, platform) {
         allowedRoots: allowedRoot === undefined ? [] : [allowedRoot],
         addRoots: addRoot === undefined ? [] : [addRoot],
         yes,
+        headless,
         json,
     };
 }

package/dist/cli/setup.js

@@ -39,14 +39,20 @@ async function interactiveArguments(options) {
 }
 async function selectedTargetAndRoots(options) {
     const requested = options.arguments;
+    // --headless (alias: --non-interactive) declares a non-interactive run
+    // explicitly, so setup works even when the caller is attached to a TTY
+    // (WorkBuddy runs under a pty). Without the flag, non-TTY is inferred.
+    const headless = requested.headless || !options.stdinIsTTY;
     if (requested.client === undefined) {
-        if (!options.stdinIsTTY) {
-            throw new CliUsageError("Non-interactive setup requires: setup --client hermes --allowed-root <absolute-path> --yes --json");
+        if (headless) {
+            throw new CliUsageError("Headless setup requires: setup --client hermes --allowed-root <absolute-path> --headless --json");
         }
         const selected = await interactiveArguments(options);
         return { ...selected, interactive: true };
     }
-    if (!options.stdinIsTTY && !requested.yes) {
+    // Only an explicit --headless bypasses the consent gate; a non-TTY
+    // without --yes still hard-errors so scripts cannot silently write.
+    if (!requested.headless && !options.stdinIsTTY && !requested.yes) {
         throw new CliUsageError("Non-interactive setup requires --yes.");
     }
     const existing = await configuredAllowedRoots(requested.client, options);
@@ -55,7 +61,7 @@ async function selectedTargetAndRoots(options) {
         : requested.addRoots.length > 0
             ? [...new Set([...existing, ...requested.addRoots])]
             : existing;
-    return { target: requested.client, roots, interactive: !requested.yes };
+    return { target: requested.client, roots, interactive: headless ? false : !requested.yes };
 }
 function writePreview(options, prepared) {
     options.write(`Target: ${prepared.displayPath}\n`);

package/dist/constants.d.ts

@@ -6,7 +6,7 @@ export declare const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export declare const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export declare const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export declare const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.1.1";
+export declare const BRIDGE_RELEASE_VERSION = "1.1.3";
 export declare const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export declare const FOREGROUND_BUDGET_MS = 15000;
 export declare const STATUS_LONG_POLL_MAX_MS = 20000;

package/dist/constants.js

@@ -6,7 +6,7 @@ export const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.1.1";
+export const BRIDGE_RELEASE_VERSION = "1.1.3";
 export const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export const FOREGROUND_BUDGET_MS = 15_000;
 export const STATUS_LONG_POLL_MAX_MS = 20_000;

package/dist/operation-journal.d.ts

@@ -61,6 +61,14 @@ export interface OperationJournalOptions {
     readonly rootDirectory?: string;
     readonly now?: () => Date;
 }
+/**
+ * Rename with a Windows fallback. Node's rename() rejects replacing an
+ * existing destination on Windows with EPERM instead of overwriting
+ * atomically; WorkBuddy dogfood hit this on every journal update because
+ * the record file already exists. The record lock makes the journal
+ * single-writer, so remove-then-rename cannot race a concurrent writer.
+ */
+export declare function renameWithFallback(sourcePath: string, destinationPath: string, platform?: NodeJS.Platform): Promise<void>;
 export declare class OperationJournal {
     #private;
     constructor(options?: OperationJournalOptions);

package/dist/operation-journal.js

@@ -56,6 +56,12 @@ function bridgeError(code, message, retryable) {
     });
 }
 function defaultRootDirectory() {
+    const configured = process.env.OMNI_CACHE_DIR;
+    if (configured !== undefined && configured.length > 0) {
+        return process.platform === "win32"
+            ? path.win32.resolve(configured)
+            : path.posix.resolve(configured);
+    }
     if (process.platform === "darwin") {
         return path.join(homedir(), "Library", "Caches", "cue", "omni-reader-mcp");
     }
@@ -199,6 +205,25 @@ async function closeQuietly(handle) {
 function sleep(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
+/**
+ * Rename with a Windows fallback. Node's rename() rejects replacing an
+ * existing destination on Windows with EPERM instead of overwriting
+ * atomically; WorkBuddy dogfood hit this on every journal update because
+ * the record file already exists. The record lock makes the journal
+ * single-writer, so remove-then-rename cannot race a concurrent writer.
+ */
+export async function renameWithFallback(sourcePath, destinationPath, platform = process.platform) {
+    try {
+        await rename(sourcePath, destinationPath);
+    }
+    catch (error) {
+        if (platform !== "win32" || error.code !== "EPERM") {
+            throw error;
+        }
+        await unlink(destinationPath);
+        await rename(sourcePath, destinationPath);
+    }
+}
 function assertStableTransition(current, updated) {
     for (const [before, after] of [
         [current.operationId, updated.operationId],
@@ -553,7 +578,7 @@ export class OperationJournal {
             await handle.sync();
             await handle.close();
             handle = undefined;
-            await rename(temporaryPath, recordPath);
+            await renameWithFallback(temporaryPath, recordPath);
             if (process.platform !== "win32")
                 await chmod(recordPath, 0o600);
             await this.#syncDirectory();

package/dist/operation-manager.js

@@ -541,11 +541,37 @@ function remoteContext(value) {
     }
     return context;
 }
+function _userFacingMessage(code, result) {
+    const error = result.error;
+    if (!error.file_uploaded && !error.parser_started) {
+        if (code === "antibot_blocked" || code === "empty_content") {
+            return "目标网站返回了验证码或空白页面，解析器无法提取内容。可尝试用本地 Bridge 下载页面后上传。";
+        }
+        if (code === "SERVICE_TEMPORARILY_UNAVAILABLE") {
+            return "解析服务暂时不可用，请稍后重试。";
+        }
+        if (code === "ssrf_blocked") {
+            return "该链接指向内部/私有地址，已被安全策略拦截。";
+        }
+        return `文件上传失败（${code}）。请检查网络连接，或尝试用本地 Bridge 下载后上传。`;
+    }
+    if (!error.parser_started) {
+        return `文件已上传但解析未能启动（${code}）。可能是文件格式不支持或文件损坏。`;
+    }
+    return `解析失败（${code}）。可尝试更换链接或文件格式。`;
+}
 function remoteFailure(result) {
     const error = result.error;
+    // Map internal error codes to user-facing messages so the caller (and the
+    // user) can understand what happened without reading protocol internals.
+    const code = error.code || "UNKNOWN_ERROR";
+    let message = error.message || "";
+    if (!message || message === code) {
+        message = _userFacingMessage(code, result);
+    }
     return new OmniBridgeError({
-        code: error.code,
-        message: error.message,
+        code,
+        message,
         ...(error.failure_scope === undefined ? {} : { failureScope: error.failure_scope }),
         sourceKind: "url",
         ...(error.user_action === undefined ? {} : { userAction: error.user_action }),

package/dist/result-contract.js

@@ -210,26 +210,24 @@ export const discardResultToolOutputSchema = z
     error: stableErrorSchema.optional(),
 })
     .strict();
-function summarizeForTextFallback(value) {
-    if (value.status === "failed") {
-        const error = value.error;
-        return `Omni failed: ${typeof error?.code === "string" ? error.code : "UNKNOWN"}.`;
+function textFallback(value) {
+    if (value.status === "completed") {
+        const result = value.result;
+        if (result !== null
+            && typeof result === "object"
+            && !Array.isArray(result)
+            && result.kind === "inline"
+            && typeof result.text === "string") {
+            return result.text;
+        }
     }
-    if (value.status === "processing")
-        return "Omni processing.";
-    if (value.status === "cleanup_pending")
-        return "Omni cleanup pending.";
-    if (value.status === "canceled")
-        return "Omni canceled.";
-    if (value.status === "expired")
-        return "Omni result expired.";
-    return "Omni completed.";
+    return JSON.stringify(value);
 }
 export function structuredResult(schema, value) {
     const structuredContent = schema.parse(value);
     return {
         ...(structuredContent.status === "failed" ? { isError: true } : {}),
         structuredContent,
-        content: [{ type: "text", text: summarizeForTextFallback(structuredContent) }],
+        content: [{ type: "text", text: textFallback(structuredContent) }],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueai/omni-reader-mcp",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",