Bindery (Evdboom)

装订

Markdown图书创作工具包： VS代码扩展+黑曜石插件 用于排版格式和多格式导出，与 MCP服务器 用于全文搜索和AI助手集成。

起源

这个项目最初是一个个人写作工具，诞生于对大多数人工智能辅助写作最终形成的复制粘贴循环的沮丧。

它始于Word和ChatGPT：编写一章，将其复制到浏览器中，获取反馈，然后粘贴回去。版本控制是一个问题，要让ChatGPT项目与最新的.docx文件保持同步需要做很多工作。转向VS Code和Markdown文件似乎是自然而然的下一步：纯文本、版本控制以及插入MCP服务器的能力，这样像Codex这样的代理就可以直接阅读这本书。

但在实践中，我仍然回到了复制粘贴以获取反馈，只真正使用了排版格式的工具。大多数VS Code扩展都是为编码而构建的：在短迭代中，代码是真实的，而不是在web工具中运行时间较长的基于聊天的会话。正是这种挫败感推动了VS Code扩展的诞生。至少，格式化和导出应该没有任何仪式。

Claude Cowork带来了更大的转变，它将长时间运行的代理的会话内存与直接文件访问相结合。这使得MCP服务器真正有用：代理可以在会话中导航章节、搜索上下文并跟踪故事，而无需手动传递所有内容。扩展和MCP服务器现在支持两种工作流程：VS Code代理（Copilot、Codex、Claude for VS Code）和独立的Claude Desktop/Cowork。以及一个黑曜石插件，其功能与VS Code扩展相同，适用于不使用更注重开发的VS Code的用户。

组件

vscode文本/ --VS代码扩展

这 装订 扩展提供：

• 排版格式 --卷曲引号、em破折号、省略号、智能撇号（保存或按需）
• 章节合并与导出 --Markdown、DOCX、EPUB、通过Pandoc+LibreOffice输出PDF，自动检测工具路径
• 方言与翻译管理 --方言输出的可扩展替换规则（例如美国→英国），以及跨语言词汇表 .bindery/translations.json
• 多语言支持 --可配置每种语言的章节标签和文件夹结构，带有方言派生词
• 工作区配置 — .bindery/settings.json 用于项目级设置
• MCP集成 --为GitHub Copilot Chat注册了25个Bindery工具并撰写 .vscode/mcp.json 克劳德/Codex

从安装 VS Code 应用商店 或者：

cd vscode-ext
npm install
npm run compile
npx @vscode/vsce package

看 vscode文本/README.md 获取完整文档。

mcp ts/ --MCP服务器（Node.js/TypeScript）

A. 模型上下文协议 将您的图书项目暴露给AI助手的服务器。纯Node.js。

• BM25全文搜索 --通过以下方式在所有章节和笔记中快速搜索词汇 迷你搜索
• 可选语义搜索 --set BINDERY_OLLAMA_URL 用于语义重新排序，或为预先计算的嵌入搜索启用完整的语义索引
• 版本跟踪 — get_review_text 返回一个结构化的git diff 加 任何被包裹的区域 ... 标记（因此仍可以审查正在进行的已提交工作）。 git_snapshot 将进度保存为git提交。Git在工作区设置过程中会自动初始化（如果可用）
• 翻译和方言管理 --《汉语词典》中的词汇条目和方言替换规则 .bindery/translations.json，可由代理查询和更新
• 会话内存 --坚持不懈 .bindery/memories/ 用于跨会话决策的文件，具有追加、列表和压缩操作
• 章节状态跟踪 --每章进度跟踪器(draft, in-progress, done, needs-review)
• 多书支持 --通过配置一本或多本书 --book Name=path CLI参数或 BINDERY_BOOKS 环境变量；每个工具调用都按名称指定要使用的书（代理永远看不到原始路径）
• 容器/安装感知 --沙盒环境中的代理（例如Cowork）可以调用 identify_book 即使装载路径与配置的路径不同，也可以使用其工作目录来发现其图书名称

看 mcpb/README.md 查看完整的27个工具参考和使用示例。

黑曜石插件/ --黑曜石插件

这 装订 Obsidian插件为Obsidian保管库用户提供了与VS Code扩展相同的功能集：

• 排版格式 --卷曲引号、em破折号、省略号、智能撇号（保存或按需）
• 章节合并与导出 --Markdown、DOCX、EPUB、通过Pandoc+LibreOffice输出PDF
• 方言与翻译管理 --可扩展替换规则和术语表
• 多语言支持 --可配置的每语言章节标签
• 工作区配置 — .bindery/settings.json 用于vault级别设置
• AI指令生成 --生成CLAUDE.md、副驾驶指令.md、.cursor/rules、AGENTS.md
• 审查标记 --标记区域以获取代理反馈
• MCP代码段生成器 --复制JSON以进行Claude Desktop集成

构建和安装：

cd obsidian-plugin
npm install
npm run compile
npm run bundle
# out/main.js is ready for manual Obsidian installation

然后在黑曜石：设置→ 社区插件（如果不受限制）→ 从文件夹安装或从手动安装 out/main.js.

mcpb/ --Claude桌面扩展

将MCP服务器打包为 .mcpb 用于在Claude Desktop或Cowork中一键安装的文件。

下载最新版本 从 发布 --不需要构建步骤。

快速开始

VS代码（复制品/克劳德/法典）

1. 安装 粘合剂延伸 来自市场
2. 在VS Code中打开您的图书文件夹
3. 跑 Bindery: Initialize Workspace 创造 .bindery/settings.json （如果不存在，也初始化git repo）
4. 跑 Bindery: Register MCP Server 创造 .vscode/mcp.json （主要用于Claude/Codex发现；GitHub Copilot Chat不需要，因为扩展会自动注册工具）
5. 工具现在可以在GitHub Copilot Chat、Claude for VS Code和Codex中使用

克劳德桌面/协作

1. 下载 bindery-mcp-*.mcpb 从 最新版本
2. 打开克劳德桌面→ 设置→ 扩展→ 从文件安装
3. 填写 书籍 以分号分隔的字段 Name=path 对：

ScaryBook=C:\Users\My\Projects\ScaryBook;MyNovel=D:\Writing\MyNovel

1. 可选择设置 Ollama网址 如果你想进行语义重新排序
2. 如果需要，可以选择启用语义索引并选择默认搜索模式 full_semantic 当嵌入索引过时时，使用重建警告进行搜索。

- 注： 运行本地Ollama实例时，完全嵌入可能是一项繁重的操作，具体取决于您的硬件。

1. 工具现在可用——代理调用 list_books 查找书籍名称

架构概述

以下流程显示了Bindery的写作环境如何与代理、MCP和高级技能连接。

flowchart TD
  U([User])

    subgraph IWE[Writing Environment]
      VS[VS Code + Bindery Extension]
      OB[Obsidian + Bindery Plugin]
      AG[In-editor Agent]
    end

    subgraph AT[Bindery Agent Tools]
      MCP[Bindery MCP Server]
      SK[Bindery Skills]
    end

    CL["Claude Desktop (Cowork)"]    
    WB[Book Workspace Files]

    U --> IWE
    U --> CL

    IWE --> WB

    VS --> AG
    OB --> AG

    AG --> AT
    CL --> AT

    MCP --> WB

仅格式化和导出（无MCP）

VS Code扩展和Obsidian插件都是独立工作的——排版格式化和导出不需要服务器设置。

项目结构

├── bindery-core/        Shared templates & types (TS)
│   ├── src/
│   │   └── templates/   AI instruction templates (claude, copilot, cursor, agents, skills)
│   └── package.json
├── bindery-merge/       Shared merge logic (TS)
│   ├── src/
│   │   ├── merge.ts     Chapter discovery, merge, export via Pandoc/LibreOffice
│   │   └── tool-locate.ts   Cross-platform tool path resolution
│   └── package.json
├── vscode-ext/          VS Code extension (TS)
│   ├── src/
│   ├── package.json
│   └── README.md
├── obsidian-plugin/     Obsidian plugin (TS)
│   ├── src/
│   ├── package.json
│   └── README.md
├── mcp-ts/              MCP server (Node.js / TS)
│   ├── src/
│   └── package.json
├── mcpb/                Claude Desktop extension
│   ├── manifest.json
│   └── server/          (CI-populated)
└── LICENSE

共享逻辑 bindery-core 和 bindery-merge 确保两者 vscode-ext 和 obsidian-plugin 实现相同的功能。

先决条件

• 一个写作环境:

- VS Code 1.85+ - 黑曜石桌面 启用了社区插件

• Git （推荐）——版本跟踪所需， get_review_text，以及 git_snapshot。在工作区设置过程中自动初始化。

- 通过包管理器或从安装 https://git-scm.com

• 潘多克。 （可选）——DOCX/EPUB/PDF导出所需。

- 通过包管理器或从安装 https://pandoc.org/installing.html

• 办公套件 （可选）--仅用于PDF导出。

- 通过包管理器或从安装 https://www.libreoffice.org

• 奥拉玛 （可选）——语义重排序和搜索所需。

- 通过包管理器或从安装 https://ollama.com/

Pandoc/LibreOffice自动检测

在所有平台上，扩展程序按以下顺序解析刀具路径：

1. 明确的 bindery.pandocPath / bindery.libreOfficePath 用户设置（如果已设置且文件存在）
2. 命令打开 PATH (where.exe 在Windows上， which 其他地方）
3. 众所周知的安装位置：

- 视窗: %LOCALAPPDATA%\Pandoc\pandoc.exe, %ProgramFiles%\Pandoc\pandoc.exe, %ProgramFiles%\LibreOffice\program\soffice.exe - macOS: /opt/homebrew/bin/pandoc, /usr/local/bin/pandoc, /Applications/LibreOffice.app/Contents/MacOS/soffice - Linux: /usr/bin/pandoc, /usr/bin/libreoffice

你通常不需要配置任何东西——正常安装Pandoc/LibreOffice，导出就可以了 bindery_health MCP工具查看检测到的内容。

已知限制

• Git 必须打开 PATH （或在标准安装位置） get_review_text 和 git_snapshot.如果找不到git，这些工具将失败，并显示明显的错误；所有其他工具仍然有效。
• 潘多克。 DOCX、EPUB和PDF导出需要。仅Markdown导出没有外部依赖关系。
• 办公套件 仅适用于PDF导出。Bindery通过Pandoc生成DOCX，然后使用LibreOffice无头转换来生成PDF。
• 语义搜索 需要可选 奥拉玛 例子没有它，词汇BM25搜索仍然可以离线工作。配置为 BINDERY_OLLAMA_URL；可通过以下方式进行可选调整 BINDERY_OLLAMA_TIMEOUT_MS （默认值为15000）以及 BINDERY_OLLAMA_RETRIES （默认值1）。
• 具有语义索引的大型书籍 在首次构建时嵌入可能需要几分钟。当章节内容不变时，重建是增量的。
• 章节编号：这些工具按文件名对章节进行排序，但接受不连续的数字。 get_overview 现在标记空白（例如第1、3章没有2）作为警告。
• 搜索索引格式：当磁盘上的格式更改时，会自动碰撞。较旧的索引会被自动忽略，并在下次使用时重新生成，无需手动操作。

隐私

Bindery保留在您的工作区内，只有当MCP服务器填写了可选的Ollama URL时，文本才会被发送到Ollama进行嵌入/语义搜索。完整的隐私政策可以在以下网址查看 https://evdboom.nl/projects/bindery/privacy

许可证

麻省理工学院——见 许可证.

贡献——模板真实来源

主机奇偶校验提醒

vscode-ext/ 和 obsidian-plugin/ 是 两个相等的实现 同一个Bindery创作工具包。两者都支持：

• 排版格式 （花引号、破折号、省略号）
• 章节合并与导出 （MD、DOCX、EPUB、通过Pandoc+LibreOffice提供的PDF）
• 方言与翻译管理 --可扩展替换规则和术语表
• 多语言支持 --可配置的章节标签和文件夹结构
• 工作区初始化 — .bindery/settings.json 和 .bindery/translations.json
• AI指令生成 --CLAUDE.md、副驾驶指令.md、游标/规则、代理.md
• 审查标记 --将文本换行 `` 用于代理反馈
• MCP配置代码段 --用于Claude桌面/协作集成的JSON
• 工作空间管理 --添加语言、方言和翻译条目

两个插件通过以下方式共享所有核心逻辑 @bindery/merge （章节发现、合并执行、工具路径解析），以最大限度地减少重复并确保一致的行为。中的共享模板 @bindery/core/src/templates/ 为VS Code和Obsidian工作流提供数据。

除非更改是针对特定主机的，否则对一个更改的功能添加应反映在同一PR或明确链接的后续PR中的另一个中。

AI指令文件模板保存在 只有一个地方:

bindery-core/src/templates/*.ts   ← SINGLE SOURCE OF TRUTH (one file per template)

mcp-ts/src/templates.ts 是保持现有进口稳定的薄再出口垫片。消费者应继续从当地的包装入口点进口， 但模板编辑属于以下匹配文件 bindery-core/src/templates/.

本地同步

更改文件后 bindery-core/src/templates/，重建并测试工作区：

npm run build --workspace=bindery-core
npm test --workspace=bindery-core
npm test --workspace=mcp-ts
npm test --workspace=vscode-ext
npm test --workspace=obsidian-plugin

运行测试

# Shared packages
cd bindery-core && npm test
cd bindery-merge && npm test

# MCP server
cd mcp-ts && npm test

# VS Code extension
cd vscode-ext && npm test

# Obsidian plugin
cd obsidian-plugin && npm test

CI做什么

CI工作流程(.github/workflows/ci.yml)在每个推送和拉取请求上运行：

1. 构建和测试 bindery-core, mcp-ts, vscode-ext，以及 obsidian-plugin （Ubuntu、Windows、macOS）。
2. 运行 刀具奇偶校验保护 (scripts/check-tool-parity.mjs)在覆盖工作。
3. 强制执行 覆盖阈值 （语句80%，分支65%，函数90%，行80%）跨包。