@echofiles/echo-pdf 0.4.2 → 0.5.0

package/README.md

@@ -1,34 +1,183 @@
 # echo-pdf
 
-`echo-pdf` 是一个部署在 Cloudflare Workers 的 PDF Agent，支持：
+`echo-pdf` 当前阶段定位为本地优先的 PDF context engine for AI agents。
+
+一句话定义：
+
+- 把本地 PDF 处理成可复用的 CLI outputs、library primitives 和 workspace artifacts，供本机 agent/app 继续消费。
+
+当前主线产品形态：
+
+- npm package：`@echofiles/echo-pdf`
+- CLI：`echo-pdf ...`
+- 本地 workspace artifacts：`.echo-pdf-workspace/...`
+- 文档站：仅用于说明安装、CLI、artifacts 和集成契约，不提供在线处理服务
+
+目标用户与主要用法：
+
+- 需要在本机或本地开发环境处理 PDF 的 agent / IDE / app 开发者
+- 需要稳定页级 primitives、document context 和可缓存 artifacts 的下游集成方
+- 需要 clean consumer import + CLI workflow 的本地组件使用方
+
+当前阶段能力：
 
 - 页面提取：把 PDF 指定页渲染为图片
 - OCR：识别页面文本
 - 表格识别：提取表格并输出 LaTeX `tabular`
-- MCP 服务：可直接挂到 Claude Desktop / Cursor / Cline / Windsurf 等客户端
+- 页级文档索引：生成本地可复用的 document / page artifacts
+- 语义结构层：在 page index 之上产出可缓存的 heading / section 结构
+- 页面渲染与 OCR artifacts：把 page render/image 与 OCR 结果缓存到本地 workspace
+
+当前阶段优先：
+
+- 本地 CLI
+- 本地 library/client API
+- 本地 workspace artifacts
+- clean-consumer npm package
+
+当前阶段非重点：
+
+- MCP 扩展或把 MCP 作为主入口
+- Hosted SaaS / multi-tenant 平台能力
+- 把网站做成在线 PDF 服务
+- datasheet / EDA 等领域特化逻辑
+
+进一步的定位说明见：
+
+- [`docs/PRODUCT.md`](./docs/PRODUCT.md)
+- [`docs/PACKAGING.md`](./docs/PACKAGING.md)
+- [`docs/WORKSPACE_CONTRACT.md`](./docs/WORKSPACE_CONTRACT.md)
+- [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md)
+
+## Local-first workflow
+
+最短路径：
+
+```bash
+npm i -g @echofiles/echo-pdf
+echo-pdf document ./sample.pdf
+echo-pdf structure ./sample.pdf
+echo-pdf semantic ./sample.pdf
+echo-pdf page ./sample.pdf --page 1
+echo-pdf render ./sample.pdf --page 1
+echo-pdf ocr ./sample.pdf --page 1 --model gpt-4.1-mini
+```
+
+源码 checkout 的本地开发路径：
+
+```bash
+npm install
+npm run document:dev -- document ./fixtures/smoke.pdf
+npm run document:dev -- structure ./fixtures/smoke.pdf
+npm run document:dev -- semantic ./fixtures/smoke.pdf
+npm run document:dev -- page ./fixtures/smoke.pdf --page 1
+```
+
+说明：
+
+- 发布包 / 已构建 checkout：`echo-pdf document ...` 继续走 `dist/`
+- 源码 checkout 且还没 build：使用 `npm run document:dev -- ...`
+- `document:dev` 只用于本地开发；它会显式优先加载 `src/local/index.ts`，即使仓库里仍然存在旧 `dist/`
+- 发布包和正常 `echo-pdf document ...` 仍然只走 `dist/`
+
+默认会在当前目录写入可检查的 workspace：
+
+```text
+.echo-pdf-workspace/
+  documents/<documentId>/
+    document.json
+    structure.json
+    semantic-structure.json
+    pages/
+      0001.json
+      0002.json
+      ...
+    renders/
+      0001.scale-2.json
+      0001.scale-2.png
+    ocr/
+      0001.scale-2.provider-openai.model-gpt-4o.prompt-<hash>.json
+```
+
+这些 artifacts 会在 PDF 未变化时被复用，便于本地下游产品（例如 echo-datasheet）做增量读取。
+
+正式的 workspace layout、cache/invalidation、detector/strategy metadata、以及下游可依赖边界，见 [`docs/WORKSPACE_CONTRACT.md`](./docs/WORKSPACE_CONTRACT.md)。
+
+## Local library/client API
+
+当前阶段优先提供本地可组合 primitives，让下游产品直接围绕 PDF 建立 document metadata / page-level artifacts，而不是先依赖远端 MCP/SaaS。
+
+### Local-first entrypoints（semver 稳定）
+
+- `@echofiles/echo-pdf`：core API
+- `@echofiles/echo-pdf/core`：与根入口等价的 core API
+- `@echofiles/echo-pdf/local`：本地 document primitives
+- `@echofiles/echo-pdf/worker`：兼容保留的 Worker 路由入口，不是本阶段重点
+
+### Local document primitives
+
+```ts
+import {
+  get_document,
+  get_document_structure,
+  get_semantic_document_structure,
+  get_page_content,
+  get_page_render,
+  get_page_ocr,
+} from "@echofiles/echo-pdf/local"
+
+const doc = await get_document({ pdfPath: "./sample.pdf" })
+const pageIndex = await get_document_structure({ pdfPath: "./sample.pdf" })
+const semantic = await get_semantic_document_structure({ pdfPath: "./sample.pdf" })
+const page1 = await get_page_content({ pdfPath: "./sample.pdf", pageNumber: 1 })
+const render1 = await get_page_render({ pdfPath: "./sample.pdf", pageNumber: 1 })
+const ocr1 = await get_page_ocr({ pdfPath: "./sample.pdf", pageNumber: 1, model: "gpt-4.1-mini" })
+```
+
+这些调用会把 artifacts 写入本地 workspace，并在 PDF 未变化时尽量复用已有页面结果。
+`get_document_structure()` 继续返回最小 page index：`document -> pages[]`。
+`get_semantic_document_structure()` 单独返回 heading / section 语义层，并写入 `semantic-structure.json`。
+`get_page_render()` 会生成可复用的 PNG + metadata。
+`get_page_ocr()` 会把 OCR 结果写入独立 artifact；它需要本地 provider key / model，不依赖 MCP 或远端服务入口。
+
+### Page Index vs Semantic Structure
 
-支持三种使用方式：
+- `get_document_structure()`
+  - 契约：稳定的 `document -> pages[]`
+  - artifact：`structure.json`
+  - 目的：给下游做页级遍历、page artifact 定位、增量读取
+- `get_semantic_document_structure()`
+  - 契约：显式的 heading / section 语义层，优先走本地 provider/model 的 agent 抽取；未配置或失败时退回保守 heuristic
+  - artifact：`semantic-structure.json`
+  - 目的：给下游做章节导航、语义分段；它不替代 page index，也不改变 `pages[]` 输出
 
-- MCP（推荐）
-- CLI
-- HTTP API
+当前 semantic 结构会把 detector 明确写入 artifact：
 
-## Using echo-pdf as a library
+- `agent-structured-v1`：使用本地配置的 provider/model 对 page text 进行结构化抽取
+- `heading-heuristic-v1`：当本地未配置模型，或 agent 抽取失败时使用的保守回退
 
-`@echofiles/echo-pdf` 支持直接作为库导入，面向下游复用 `pdf_extract_pages / pdf_ocr_pages / pdf_tables_to_latex / file_ops` 工具实现。
+两种模式都遵循同一输出契约；检测不到时会返回空结构，而不是伪造 section tree。
+
+## Tool library compatibility
+
+除了 local-first primitives 之外，`@echofiles/echo-pdf` 仍保留现有 `pdf_extract_pages / pdf_ocr_pages / pdf_tables_to_latex / file_ops` 工具实现的复用入口，用于兼容已有集成。
 
 ### Public entrypoints（semver 稳定）
 
-- `@echofiles/echo-pdf`：core API（推荐）
+- `@echofiles/echo-pdf`：core API
 - `@echofiles/echo-pdf/core`：与根入口等价的 core API
-- `@echofiles/echo-pdf/worker`：Worker 路由入口（给 Wrangler/Worker 集成用）
+- `@echofiles/echo-pdf/local`：本地 document primitives
+- `@echofiles/echo-pdf/worker`：Worker 路由入口（兼容保留）
 
 仅以上 `exports` 子路径视为公开 API。`src/*`、`dist/*` 等深路径导入不受兼容性承诺保护，可能在次版本中变动。
 
+完整的 package entrypoint、runtime、semver、以及 clean-consumer import 保证，见 [`docs/PACKAGING.md`](./docs/PACKAGING.md)。
+
 ### Runtime expectations
 
 - Node.js: `>=20`（与 `package.json#engines` 一致）
 - 需要 ESM `import` 能力与标准 `fetch`（Node 20+ 原生支持）
+- `@echofiles/echo-pdf/local` 面向本地 Node/Bun CLI 或 app runtime
 - 建议使用支持 package `exports` 的现代 bundler/runtime（Vite、Webpack 5、Rspack、esbuild、Wrangler 等）
 - TypeScript 消费方建议：`module=NodeNext` + `moduleResolution=NodeNext`
 
@@ -41,7 +190,7 @@ tmpdir="$(mktemp -d)"
 cd "$tmpdir"
 npm init -y
 npm i /path/to/echofiles-echo-pdf-<version>.tgz
-node --input-type=module -e "await import('@echofiles/echo-pdf'); await import('@echofiles/echo-pdf/core'); await import('@echofiles/echo-pdf/worker'); console.log('ok')"
+node --input-type=module -e "await import('@echofiles/echo-pdf'); await import('@echofiles/echo-pdf/core'); await import('@echofiles/echo-pdf/local'); await import('@echofiles/echo-pdf/worker'); console.log('ok')"
 ```
 
 ### Example
@@ -87,7 +236,10 @@ console.log(result)
 - 对公开 API 的破坏性变更只会在 major 版本发布
 - 新增导出、参数扩展（向后兼容）会在 minor/patch 发布
 
-## 1. 服务地址
+## 1. Compatibility surfaces（deferred / not primary）
+
+以下内容是当前仓库中兼容保留的入口，不是本阶段主线产品形态。
+主线仍然是 npm package + CLI + local workspace artifacts；网站只是文档站，不是在线服务。
 
 请先确定你的线上地址（Worker 域名）。文档里用：
 
@@ -159,7 +311,65 @@ echo-pdf config set --key service.storage.maxFileBytes --value 10000000
 echo-pdf config set --key service.maxPagesPerRequest --value 20
 ```
 
-## 3. MCP 使用（推荐）
+## 2.1 六个核心 primitives
+
+本地 CLI 主命令面与 `@echofiles/echo-pdf/local` 的六个 primitives 一一对应：
+
+- `document <file.pdf>` -> `get_document`
+- `structure <file.pdf>` -> `get_document_structure`
+- `semantic <file.pdf>` -> `get_semantic_document_structure`
+- `page <file.pdf> --page <N>` -> `get_page_content`
+- `render <file.pdf> --page <N>` -> `get_page_render`
+- `ocr <file.pdf> --page <N>` -> `get_page_ocr`
+
+兼容边界：
+
+- 旧的 `document get|index|structure|semantic|page|render|ocr ...` 仍作为兼容别名保留
+- README 和 `--help` 现在优先展示这六个主命令，而不是旧的子命令树
+
+建立本地索引并输出 metadata：
+
+```bash
+echo-pdf document ./sample.pdf
+```
+
+读取结构树：
+
+```bash
+echo-pdf structure ./sample.pdf
+```
+
+读取语义结构层：
+
+```bash
+echo-pdf semantic ./sample.pdf
+```
+
+读取指定页面内容：
+
+```bash
+echo-pdf page ./sample.pdf --page 1
+```
+
+生成页面渲染 artifact：
+
+```bash
+echo-pdf render ./sample.pdf --page 1 --scale 2
+```
+
+生成 OCR artifact（需要本地 provider key / model）：
+
+```bash
+echo-pdf ocr ./sample.pdf --page 1 --model gpt-4.1-mini
+```
+
+自定义 artifact workspace：
+
+```bash
+echo-pdf document ./sample.pdf --workspace ./.cache/echo-pdf
+```
+
+## 3. MCP 使用（兼容保留，非本阶段重点）
 
 ### 3.1 检查 MCP 服务可用
 
@@ -201,7 +411,7 @@ echo-pdf mcp call --tool pdf_extract_pages --args '{
 stdio 模式会把本地 `path/filePath` 自动上传为 `fileId` 后再调用远端工具。
 
 ```bash
-echo-pdf mcp stdio
+echo-pdf mcp-stdio
 ```
 
 生成 Claude Desktop/Cursor 等可用的 stdio 配置片段：
@@ -287,12 +497,18 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
   }'
 ```
 
-CLI（支持直接传本地路径）：
+CLI（默认不自动上传本地文件，需显式开启）：
 
 ```bash
-echo-pdf call --tool pdf_extract_pages --args '{"path":"./sample.pdf","pages":[1],"returnMode":"url"}'
+echo-pdf call --tool pdf_extract_pages --auto-upload --args '{"path":"./sample.pdf","pages":[1],"returnMode":"url"}'
 ```
 
+说明：
+
+- `echo-pdf call` 默认禁用本地文件自动上传，避免误上传脚枪。
+- 需要自动上传时，显式传 `--auto-upload`，CLI 会回显上传清单（本地路径 -> fileId）。
+- 如果是本地 agent/IDE 场景，优先使用 `echo-pdf mcp-stdio`，它会按 MCP stdio 约定处理 `path/filePath` 自动上传。
+
 下载产物：
 
 ```bash

package/bin/echo-pdf.js

@@ -4,7 +4,7 @@ import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { downloadFile, postJson, uploadFile, withUploadedLocalFile } from "./lib/http.js"
+import { downloadFile, postJson, prepareArgsWithLocalUploads, uploadFile, withUploadedLocalFile } from "./lib/http.js"
 import { runMcpStdio } from "./lib/mcp-stdio.js"
 
 const CONFIG_DIR = path.join(os.homedir(), ".config", "echo-pdf-cli")
@@ -208,10 +208,25 @@ const runDevServer = (port, host) => {
   })
 }
 
-const runMcpStdioCommand = async () => {
+const printLocalServiceHints = (host, port) => {
+  const resolvedHost = host === "0.0.0.0" ? "127.0.0.1" : host
+  const baseUrl = `http://${resolvedHost}:${port}`
+  const mcpUrl = `${baseUrl}/mcp`
+  process.stdout.write(`\nLocal component endpoints:\n`)
+  process.stdout.write(`  ECHO_PDF_BASE_URL=${baseUrl}\n`)
+  process.stdout.write(`  ECHO_PDF_MCP_URL=${mcpUrl}\n`)
+  process.stdout.write(`\nExport snippet:\n`)
+  process.stdout.write(`  export ECHO_PDF_BASE_URL=${baseUrl}\n`)
+  process.stdout.write(`  export ECHO_PDF_MCP_URL=${mcpUrl}\n\n`)
+}
+
+const runMcpStdioCommand = async (serviceUrlOverride) => {
   const config = loadConfig()
+  const serviceUrl = typeof serviceUrlOverride === "string" && serviceUrlOverride.trim().length > 0
+    ? serviceUrlOverride.trim()
+    : config.serviceUrl
   await runMcpStdio({
-    serviceUrl: config.serviceUrl,
+    serviceUrl,
     headers: buildMcpHeaders(),
     postJson,
     withUploadedLocalFile,
@@ -308,9 +323,134 @@ const writeDevVarsConfigJson = (devVarsPath, configJson) => {
   fs.writeFileSync(devVarsPath, lines.join("\n"))
 }
 
+const LOCAL_DOCUMENT_DIST_ENTRY = new URL("../dist/local/index.js", import.meta.url)
+const LOCAL_DOCUMENT_SOURCE_ENTRY = new URL("../src/local/index.ts", import.meta.url)
+const IS_BUN_RUNTIME = typeof process.versions?.bun === "string"
+const SHOULD_PREFER_SOURCE_DOCUMENT_API = process.env.ECHO_PDF_SOURCE_DEV === "1"
+
+const loadLocalDocumentApi = async () => {
+  if (SHOULD_PREFER_SOURCE_DOCUMENT_API) {
+    if (IS_BUN_RUNTIME && fs.existsSync(fileURLToPath(LOCAL_DOCUMENT_SOURCE_ENTRY))) {
+      return import(LOCAL_DOCUMENT_SOURCE_ENTRY.href)
+    }
+    throw new Error(
+      "Source-checkout document dev mode requires Bun and src/local/index.ts. " +
+      "Use `npm run document:dev -- <command> ...` from a source checkout."
+    )
+  }
+  try {
+    return await import(LOCAL_DOCUMENT_DIST_ENTRY.href)
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : ""
+    if (code === "ERR_MODULE_NOT_FOUND") {
+      throw new Error(
+        "Local document commands require built artifacts in a source checkout. " +
+        "Run `npm run build` first, use `npm run document:dev -- <command> ...` in a source checkout, or install the published package."
+      )
+    }
+    throw error
+  }
+}
+
+const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render", "ocr"]
+const LEGACY_DOCUMENT_SUBCOMMANDS = ["index", "get", "structure", "semantic", "page", "render", "ocr"]
+
+const isLegacyDocumentSubcommand = (value) => typeof value === "string" && LEGACY_DOCUMENT_SUBCOMMANDS.includes(value)
+
+const readDocumentPrimitiveArgs = (command, subcommand, rest) => {
+  if (command === "document" && isLegacyDocumentSubcommand(subcommand)) {
+    const primitive = subcommand === "index" || subcommand === "get" ? "document" : subcommand
+    return {
+      primitive,
+      pdfPath: rest[0],
+    }
+  }
+  return {
+    primitive: command,
+    pdfPath: command === "document" ? subcommand : rest[0],
+  }
+}
+
+const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
+  const local = await loadLocalDocumentApi()
+  const { primitive, pdfPath } = readDocumentPrimitiveArgs(command, subcommand, rest)
+  const workspaceDir = typeof flags.workspace === "string" ? flags.workspace : undefined
+  const forceRefresh = flags["force-refresh"] === true
+  const renderScale = typeof flags.scale === "string" ? Number(flags.scale) : undefined
+
+  if (typeof pdfPath !== "string" || pdfPath.length === 0 || pdfPath.startsWith("--")) {
+    throw new Error(`${primitive} requires a pdf path argument`)
+  }
+
+  if (primitive === "document") {
+    const data = await local.get_document({ pdfPath, workspaceDir, forceRefresh })
+    print(data)
+    return
+  }
+
+  if (primitive === "structure") {
+    const data = await local.get_document_structure({ pdfPath, workspaceDir, forceRefresh })
+    print(data)
+    return
+  }
+
+  if (primitive === "semantic") {
+    const data = await local.get_semantic_document_structure({
+      pdfPath,
+      workspaceDir,
+      forceRefresh,
+      provider: typeof flags.provider === "string" ? flags.provider : undefined,
+      model: typeof flags.model === "string" ? flags.model : undefined,
+    })
+    print(data)
+    return
+  }
+
+  const pageNumber = typeof flags.page === "string" ? Number(flags.page) : NaN
+  if (!Number.isInteger(pageNumber) || pageNumber < 1) {
+    throw new Error(`${primitive} requires --page <positive integer>`)
+  }
+
+  if (primitive === "page") {
+    const data = await local.get_page_content({ pdfPath, workspaceDir, forceRefresh, pageNumber })
+    print(data)
+    return
+  }
+
+  if (primitive === "render") {
+    const data = await local.get_page_render({ pdfPath, workspaceDir, forceRefresh, pageNumber, renderScale })
+    print(data)
+    return
+  }
+
+  if (primitive === "ocr") {
+    const data = await local.get_page_ocr({
+      pdfPath,
+      workspaceDir,
+      forceRefresh,
+      pageNumber,
+      renderScale,
+      provider: typeof flags.provider === "string" ? flags.provider : undefined,
+      model: typeof flags.model === "string" ? flags.model : undefined,
+      prompt: typeof flags.prompt === "string" ? flags.prompt : undefined,
+    })
+    print(data)
+    return
+  }
+
+  throw new Error(`Unsupported local primitive command: ${primitive}`)
+}
+
 const usage = () => {
   process.stdout.write(`echo-pdf CLI\n\n`)
   process.stdout.write(`Commands:\n`)
+  process.stdout.write(`  document <file.pdf> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  structure <file.pdf> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  semantic <file.pdf> [--provider alias] [--model model] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  page <file.pdf> --page <N> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  render <file.pdf> --page <N> [--scale N] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  ocr <file.pdf> --page <N> [--scale N] [--provider alias] [--model model] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`\nCompatibility / existing service commands:\n`)
   process.stdout.write(`  init [--service-url URL]\n`)
   process.stdout.write(`  dev [--port 8788] [--host 127.0.0.1]\n`)
   process.stdout.write(`  provider set --provider <${PROVIDER_SET_NAMES.join("|")}> --api-key <KEY> [--profile name]\n`)
@@ -322,12 +462,19 @@ const usage = () => {
   process.stdout.write(`  model get [--provider alias] [--profile name]\n`)
   process.stdout.write(`  model list [--profile name]\n`)
   process.stdout.write(`  tools\n`)
-  process.stdout.write(`  call --tool <name> --args '<json>' [--provider alias] [--model model] [--profile name]\n`)
+  process.stdout.write(`  call --tool <name> --args '<json>' [--provider alias] [--model model] [--profile name] [--auto-upload]\n`)
+  process.stdout.write(`  document get <file.pdf> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  document structure <file.pdf> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  document semantic <file.pdf> [--provider alias] [--model model] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  document page <file.pdf> --page <N> [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  document render <file.pdf> --page <N> [--scale N] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  document ocr <file.pdf> --page <N> [--scale N] [--provider alias] [--model model] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  file upload <local.pdf>\n`)
   process.stdout.write(`  file get --file-id <id> --out <path>\n`)
   process.stdout.write(`  mcp initialize\n`)
   process.stdout.write(`  mcp tools\n`)
   process.stdout.write(`  mcp call --tool <name> --args '<json>'\n`)
+  process.stdout.write(`  mcp-stdio [--service-url URL]\n`)
   process.stdout.write(`  mcp stdio\n`)
   process.stdout.write(`  setup add <claude-desktop|claude-code|cursor|cline|windsurf|gemini|json>\n`)
 }
@@ -338,7 +485,7 @@ const setupSnippet = (tool, serviceUrl, mode = "http") => {
       mcpServers: {
         "echo-pdf": {
           command: "echo-pdf",
-          args: ["mcp", "stdio"],
+          args: ["mcp-stdio"],
           env: {
             ECHO_PDF_SERVICE_URL: serviceUrl,
           },
@@ -416,7 +563,7 @@ const main = async () => {
   const [command, ...raw] = argv
   let subcommand = ""
   let rest = raw
-  if (["provider", "mcp", "setup", "model", "config"].includes(command)) {
+  if (["provider", "mcp", "setup", "model", "config", "document"].includes(command)) {
     subcommand = raw[0] || ""
     rest = raw.slice(1)
   }
@@ -436,10 +583,16 @@ const main = async () => {
     const port = typeof flags.port === "string" ? Number(flags.port) : 8788
     const host = typeof flags.host === "string" ? flags.host : "127.0.0.1"
     if (!Number.isFinite(port) || port <= 0) throw new Error("dev --port must be positive number")
+    printLocalServiceHints(host, Math.floor(port))
     runDevServer(Math.floor(port), host)
     return
   }
 
+  if (command === "mcp-stdio") {
+    await runMcpStdioCommand(typeof flags["service-url"] === "string" ? flags["service-url"] : undefined)
+    return
+  }
+
   if (command === "provider" && subcommand === "set") {
     const providerAlias = resolveProviderAliasInput(flags.provider)
     const apiKey = flags["api-key"]
@@ -566,6 +719,11 @@ const main = async () => {
     return
   }
 
+  if (LOCAL_PRIMITIVE_COMMANDS.includes(command) || (command === "document" && isLegacyDocumentSubcommand(subcommand))) {
+    await runLocalPrimitiveCommand(command, subcommand, rest, flags)
+    return
+  }
+
   if (command === "call") {
     const config = loadConfig()
     const profileName = getProfileName(config, flags.profile)
@@ -573,7 +731,17 @@ const main = async () => {
     const tool = flags.tool
     if (typeof tool !== "string") throw new Error("call requires --tool")
     const args = typeof flags.args === "string" ? JSON.parse(flags.args) : {}
-    const preparedArgs = await withUploadedLocalFile(config.serviceUrl, tool, args)
+    const autoUpload = flags["auto-upload"] === true
+    const prepared = await prepareArgsWithLocalUploads(config.serviceUrl, tool, args, {
+      autoUpload,
+    })
+    if (prepared.uploads.length > 0) {
+      process.stderr.write(`[echo-pdf] auto-uploaded local files:\n`)
+      for (const item of prepared.uploads) {
+        process.stderr.write(`  - ${item.localPath} -> ${item.fileId} (${item.tool})\n`)
+      }
+    }
+    const preparedArgs = prepared.args
     const provider = resolveProviderAlias(profile, flags.provider)
     const model = typeof flags.model === "string" ? flags.model : resolveDefaultModel(profile, provider)
     const providerApiKeys = buildProviderApiKeys(config, profileName)
@@ -638,7 +806,7 @@ const main = async () => {
   }
 
   if (command === "mcp" && subcommand === "stdio") {
-    await runMcpStdioCommand()
+    await runMcpStdioCommand(typeof flags["service-url"] === "string" ? flags["service-url"] : undefined)
     return
   }
 

package/bin/lib/http.js

@@ -53,20 +53,45 @@ export const downloadFile = async (serviceUrl, fileId, outputPath) => {
   return absOut
 }
 
-export const withUploadedLocalFile = async (serviceUrl, tool, args) => {
+const parseAutoUploadFlag = (value) => {
+  if (value === true) return true
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase()
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on"
+  }
+  return false
+}
+
+export const prepareArgsWithLocalUploads = async (serviceUrl, tool, args, options = {}) => {
   const nextArgs = { ...(args || {}) }
+  const uploads = []
+  const autoUploadEnabled = options.autoUpload !== false
   if (tool.startsWith("pdf_")) {
     const localPath = typeof nextArgs.path === "string"
       ? nextArgs.path
       : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
     if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
+      if (!autoUploadEnabled) {
+        throw new Error(
+          "Local file auto-upload is disabled for `echo-pdf call`. " +
+          "Use --auto-upload, or upload first (`echo-pdf file upload`) and pass fileId, or use `echo-pdf mcp-stdio`."
+        )
+      }
       const upload = await uploadFile(serviceUrl, localPath)
       const fileId = upload?.file?.id
       if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
       nextArgs.fileId = fileId
       delete nextArgs.path
       delete nextArgs.filePath
+      uploads.push({ tool, localPath, fileId })
     }
   }
+  return { args: nextArgs, uploads }
+}
+
+export const withUploadedLocalFile = async (serviceUrl, tool, args, options = {}) => {
+  const { args: nextArgs } = await prepareArgsWithLocalUploads(serviceUrl, tool, args, {
+    autoUpload: parseAutoUploadFlag(options.autoUpload ?? true),
+  })
   return nextArgs
 }

package/dist/auth.js

@@ -1,7 +1,19 @@
 export const checkHeaderAuth = (request, env, options) => {
-    if (!options.authHeader || !options.authEnv)
+    const authHeader = typeof options.authHeader === "string" ? options.authHeader.trim() : "";
+    const authEnv = typeof options.authEnv === "string" ? options.authEnv.trim() : "";
+    const hasHeader = authHeader.length > 0;
+    const hasEnv = authEnv.length > 0;
+    if (!hasHeader && !hasEnv)
         return { ok: true };
-    const required = env[options.authEnv];
+    if (!hasHeader || !hasEnv) {
+        return {
+            ok: false,
+            status: 500,
+            code: options.misconfiguredCode,
+            message: `${options.contextName} auth must configure both authHeader and authEnv`,
+        };
+    }
+    const required = env[authEnv];
     if (typeof required !== "string" || required.length === 0) {
         if (options.allowMissingSecret === true)
             return { ok: true };
@@ -9,10 +21,10 @@ export const checkHeaderAuth = (request, env, options) => {
             ok: false,
             status: 500,
             code: options.misconfiguredCode,
-            message: `${options.contextName} auth is configured but env "${options.authEnv}" is missing`,
+            message: `${options.contextName} auth is configured but env "${authEnv}" is missing`,
         };
     }
-    if (request.headers.get(options.authHeader) !== required) {
+    if (request.headers.get(authHeader) !== required) {
         return {
             ok: false,
             status: 401,