文档操作

规范的文档转换、编辑、检查和 .odb 操作 documents.js 暴露—一个Zod输入/输出模式和一个与传输无关的模式 run() 每个操作的函数 document-mcp， document-rest, document-cli 是否可以在不重新定义其形状或行为的情况下公开相同的操作。

在这个包裹出现之前， document-mcp 直接在自己的工具中定义每个MCP工具的Zod模式和分派逻辑 src/tools/*.ts, document-cli 再次以手写方式描述相同的底层操作 commander 标志——“做什么”的两个独立定义 convert_document 以“可以默默地漂流，没有第三个表面可以建立的共同真相来源”为例。 document-operations 那是真相的来源吗，所有行动的来源 document-mcp它自己的工具集在行为上没有改变，从任何一个传输自己的结果塑造中解耦，并且 document-rest 第一个新消费者是直接针对它而不是针对第二个副本构建的吗？

graph TD
    schema("document-schema.js")
    documents("documents.js")
    outline("document-outline.js")
    compute("document-compute.js")
    operations("document-operations")
    mcp("document-mcp")
    rest("document-rest")

    schema --> documents
    schema --> outline
    schema --> compute
    documents --> operations
    outline --> operations
    compute --> operations
    operations --> mcp
    operations --> rest

    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
    click documents "https://github.com/ExaDev/documents.js" "documents.js"
    click outline "https://github.com/ExaDev/documents.js/tree/main/packages/document-outline.js" "document-outline.js"
    click compute "https://github.com/ExaDev/documents.js/tree/main/packages/document-compute.js" "document-compute.js"
    click operations "https://github.com/ExaDev/documents.js/tree/main/packages/document-operations" "document-operations"
    click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
    click rest "https://github.com/ExaDev/documents.js/tree/main/packages/document-rest" "document-rest"

    style operations fill:#f9a825,stroke:#333,stroke-width:3px

这个 DocumentOperation 合同

此包导出的每个操作都具有相同的形状(src/operation.ts）：

interface DocumentOperation<In, Out> {
  readonly name: string;
  readonly title: string;
  readonly description: string;
  readonly inputSchema: z.ZodType<In>;
  readonly outputSchema?: z.ZodType<Out>;
  run(input: In, context?: { readonly signal?: AbortSignal }): Promise<Out>;
}

inputSchema/outputSchema 是验证和描述文本的唯一真实来源； run() 是与传输无关的实现。失败总是抛出错误（普通错误，或以下错误之一） documents.js自己的打字错误，例如： OdbReportNotSpecifiedError， OdmUnresolvedSectionError) - - - run() 永远不要塑造特定于传输的结果。每个传输自己决定如何呈现抛出的错误： document-mcp 将其封装为 isError 工具结果(带有可选的 mapError （这两个操作的错误携带了值得在结构上显示的数据），REST路由会将其映射到4xx JSON体，CLI命令会将其打印到带有非零退出码的stderr。

defineOperation()/defineOperationWithoutOutputSchema() 从一个普通的对象中构建一个，进行推断 In/Out 从Zod模式中删除，这样调用站点就不会重复 z.infer<typeof Schema> 本身。使用 WithoutOutputSchema 少数操作的变体，其原始MCP工具注册声明no outputSchema 一点也不(metadata_read每个格式的返回形状不同；这个 .odb-读取操作返回 documents.js—在那里添加一个猜测的模式可能会有引入以前不存在的输出验证的风险，并且可能会拒绝猜测没有预料到的真实值。

DOCUMENT_OPERATIONS （src/registry.ts)是一个数组中的每个操作——“与MCP相同的注册表”——一个希望枚举每个操作而不是按名称导入操作的调用者可以达到：MCP服务器将每个条目注册为工具，REST服务器将为每个条目添加一条路由，CLI将根据条目验证其自己的解析标志 inputSchema 发送之前 run()。

操作

下面的每个操作都是在行为不变的情况下从 document-mcp的自己的 src/tools/*.ts -请参阅该包的README以获得每个包的完整描述；该表是索引。

开始

pnpm install
pnpm build         # turbo -> tsdown -> dist/ (ESM + CJS + .d.ts)
pnpm typecheck     # turbo -> tsc --noEmit, plus attw --pack
pnpm lint          # turbo -> eslint . --fix --cache --max-warnings 0
pnpm test          # turbo -> vitest run
pnpm test:workers  # turbo -> vitest under the real Cloudflare Workers runtime (workerd) via @cloudflare/vitest-pool-workers, exercising every operation's bytesBase64 input path

陷阱

• 不支持Worker同构，不像它所依赖的基础包。 resolveDocumentInput的 path 分支(src/io/document-input.ts)通过从磁盘读取文件 node:fs/promises, odm_to_pdf章节目录解析(src/operations/odm.ts)使用 node:fs的同步API——同样的原因 document-mcp 和 document-cli 的同构包列表中排除的 monorepo root README。 pnpm test:workers 仍然证明了每一个操作 bytesBase64 输入路径在workerd下正确运行 path/chaptersDir 涉及),匹配 document-mcp自己的工人测试范围。
• document-mcp他自己的测试没有被移到这里 他们继续测试完整的MCP注册(createServer() +一个真正的客户机/服务器JSON-RPC往返)，它仍然执行这个包自己的 run() 下面的函数——移动它们意味着重新验证现有的3000行代码，通过测试行为，没有功能上的好处。这个包自己的测试是对每个测试进行独立的、更直接的单元级检查 run() 独立运行。
• odb_render_report的 OdbReportNotSpecifiedError 和 odm_to_pdf的 OdmUnresolvedSectionError 不在这里被抓。 两者都是由底层抛出的 documents.js 功能和繁殖- mcp特异性富集（修复提示）， structuredContent.availableReports/.hrefs)住在 document-mcp的自己的 mapError 钩子(src/tools/odb-render-report.ts， src/tools/odm.ts)，因为这种塑造是表示，而不是操作逻辑。

贡献

发布、CI和提交消息约定都是工作空间范围的，而不是包本地的——请参阅 monorepo root README 对于释放机制和 CONTRIBUTING.md 对于共享的git钩子和历史约定。工作内 packages/document-operations/。

许可证

麻省理工学院