md-business

md-business

⬇ 下载桌面应用（Windows / macOS）——提供安装程序，无需构建。也可以添加 Chrome 扩展，在浏览器中阅读和打印 Markdown 业务文档；或添加 VS Code 扩展，在编写代码的地方验证和预览文档。

English | 日本語

以 Markdown 为事实来源，由 AI 原生驱动的业务文档。

md-business 是一个开源框架，用于将业务文档作为 Markdown 文件进行管理，并提供结构化的 frontmatter、架构、验证、Git 历史记录和便于人类阅读的查看器。

它不只是 Markdown 查看器、PDF 生成器或模板集合。

md-business 将 Markdown 视为发票、测试规范、设计文档、API 文档、数据库设计文档、估算单、会议记录及其他运营文档的权威事实来源。AI Agent 可以直接创建、编辑、验证、比较差异并渲染这些文档；人类则可以通过 PDF、Google Workspace、Chrome、VS Code、PWA、桌面应用或 GitHub 等熟悉的界面查看和使用它们。

为什么要开发它

大多数业务文档仍然存放在主要为人类设计的工具中：

• 文字处理软件
• 电子表格
• PDF
• 云盘
• 办公套件
• SaaS 后台工具
• 内部网页表单

这些工具适合人类输入和审核，但并不适合作为 AI 可操作的事实来源。

AI Agent 可以阅读并总结这些文档，但往往无法安全、持续地将它们作为结构化业务资产来操作。在可靠编辑、验证、比较差异、版本控制、自动化，以及在多个 Agent 或系统之间交接方面，它们都面临困难。

md-business 的出发点不同：

业务文档应以 AI Agent 能够直接操作的格式存储。

Markdown 提供人类可读的正文。 YAML frontmatter 提供机器可读的元数据。 JSON Schema 提供验证能力。 Git 提供历史记录、审核、分支和回滚。 渲染器和查看器提供面向人类的输出。

核心理念

Markdown source of truth
        ↓
Schema validation
        ↓
AI agent editing
        ↓
Git diff / review / approval
        ↓
PDF / Sheets / Docs / browser / desktop / SaaS integration

重要的层是 Markdown 源文件。

查看器和集成只是人类及现有工作流的访问入口。它们的作用是让非技术用户无需了解 Markdown、Git 或 AI Agent，也能审核、批准、打印、分享或提交文档。

md-business 是什么

md-business 是：

• 一个由架构驱动的业务文档系统
• 一个以 Markdown 为先的事实来源层
• 一种专为 AI Agent 设计的文档格式
• 一种适合 Git 的不透明办公文件替代方案
• 一个连接 AI 工作流与面向人类的业务文档的桥梁
• 本地优先、由 Agent 驱动的业务运营基础

md-business 不是什么

md-business 不是：

• Notion 克隆版
• Google Docs 克隆版
• 电子表格替代品
• 简单的 Markdown 查看器
• 仅用于生成 PDF 的工具
• 封闭的 SaaS 工作流工具

现有办公套件和 SaaS 工具仍可用于审阅、交付或受监管的后端。md-business 专注于 AI Agent 实际可以操作的事实来源层。

为什么选择 Markdown

Markdown 是适用于 AI 原生业务运营的实用基础格式，因为：

• AI Agent 可以可靠地编辑它
• 人们无需特殊软件即可阅读
• Git 可以跟踪每项更改
• 可以使用拉取请求进行审阅和审批
• Frontmatter 可以存储结构化业务数据
• JSON Schema 可以验证文档是否正确
• 渲染器可以生成 PDF、HTML、Sheets、Docs 或其他输出
• 本地仓库可以由桌面工具或自主 Agent 操作

人的职责

md-business 不会免除人的责任。

它让人们不再处理重复的文档操作，而是专注于审阅、审批、异常处理和业务决策。

AI Agent 操作源文件。 人们审批结果。 查看器提供界面。

示例用例

测试规格

AI Agent 以 Markdown 格式生成和更新测试用例。 Schema 会验证必填字段。 Git 会跟踪更改。 Google Sheets 或浏览器查看器可让非工程人员执行测试并审阅结果。

设计文档

AI Agent 以受版本控制的 Markdown 格式维护基础设计文档、API 规格、数据库设计文档和实现说明。 Mermaid 图表、结构化 Frontmatter 和 Schema 验证让文档易于审阅和自动化处理。

发票和报价单

AI Agent 会在 Markdown 中更新日期、明细项、税务字段、客户信息和付款条款。 Schema 会验证必填字段。 PDF 渲染器会生成面向人的文档。 外部会计工具可以作为集成目标，而不是主要编辑界面。

分发渠道

md-business 提供多个面向用户的查看器和自动化渠道：

渠道	用途	状态
Tauri Desktop App	本地优先的仓库操作和文档工作流自动化	可用
Chrome Extension	在浏览器中打开和预览 Markdown 业务文档	可用
Google Workspace Add-on	在熟悉的办公工作流中审阅和展示文档	审核中
VS Code Extension	面向开发者和 Agent 的编辑	可用
PWA	跨平台的用户查看器	计划中
GitHub Action	CI 验证和自动渲染	计划中
LINE LIFF	面向日本业务工作流的移动优先访问	计划中

这些渠道不是核心产品。 它们是围绕 Markdown 事实来源构建的适配器。

当前模板

模板	Schema	位置
发票 / 报价单 / 收据	invoice/v1	templates/invoice/ — 6 个变体
测试规格	test-spec/v1	templates/test-spec/
设计文档	spec/v1	templates/spec/
API 规格	api-spec/v1	templates/api-spec/
调查报告	investigation/v1	templates/investigation/

使用模板

每个随附模板都使用虚构数据，不包含真实的公司名称、注册编号、银行账户或发票编号。将文件复制到你自己的工作区，并直接编辑其中的值。

发票模板（templates/invoice/）：

• standard.md — 英文基础模板，单个项目，税率为 10%
• standard-ja.md — 日文基础模板，混合使用 10% / 8% 的税率，包含银行账户和适格请求书发行事业者注册编号（T + 13 位虚构数字）
• tax-exempt-ja.md — 免税事业者（免税个体经营者）版本，不含注册编号，并附有 2023–2029 年经过措置的脚注
• inbound-eligible.md — 多项目发票，同时使用标准税率和优惠税率
• quote-ja.md — 报价单（種別: 見積書），包含有效日期，而非付款截止日期
• receipt-ja.md — 收据（種別: 領収書），包含但书栏和可选的收入印花栏

你可以在 Chrome 扩展查看器中打开这些模板，或通过 @md-business/renderer-pdf 渲染，无需编写任何代码即可生成可直接打印的 PDF。

数据库设计文档（关系型数据库对应 db-spec/v1，文档型数据库对应 nosql-db-spec/v1）包含架构，并可在所有应用中打开，但目前还没有空白模板——examples/ 中有可供复制的已填写示例。未来可能会添加会议记录、合同、运营检查清单和其他业务文档模板。

示例

模板提供空白表单。已填写的示例见 examples/。

其中包含一个虚构项目——内部设备借用工具——的端到端文档：设计文档、API 规范、数据库设计、测试表、发票，以及附带证据文件的调查报告。文档之间相互引用，因此你可以了解它们在真实项目中的关联方式。

公司名称、注册编号、银行账户和员工代码均为虚构。可以照着格式填写，但不要照抄其中的值。详见 examples/README.md。

截图

截图将添加到 docs/screenshots/ 下。关于截图规格（1280 × 800 px / PNG）和计划截图列表，请参阅 docs/screenshots/README.md：

• Chrome 扩展查看器展示合规发票
• Chrome 扩展 A4 PDF 预览
• Google Workspace Add-on 测试规格表视图
• Google Workspace Add-on「GitHub 推送」侧边栏操作

目前，请查看 Chrome 网上应用店已发布的查看器页面，其中包含相关截图：https://chromewebstore.google.com/detail/lmdplkkfmgapnhombimeohjliinifgjh。

派生与自定义

md-business 采用 MIT 许可证，并明确支持派生，用于内部部署、咨询项目和按供应商部署。有关推荐的派生策略、上游同步工作流、各软件包的自定义位置以及分发渠道说明，请参阅 docs/fork-guide/。

长期愿景

md-business 旨在让 AI Agent 能够处理业务文档。

md-business 不会将 AI 叠加在不透明的 SaaS 界面、PDF、电子表格和办公文件之上，而是将结构化 Markdown 置于工作流的核心。

这将带来一种不同的组织方式：

• 文档纳入版本控制
• 变更可供审查
• AI Agent 可直接处理源文件
• 人员通过熟悉的视图进行审批
• 本地代码库可成为运营工作区
• 可自动化后台和上游工程流程，而无需将事实源锁定在特定 SaaS 中

目标并非取代所有业务工具。

目标是让规范业务文档层开放、可移植、可审查、可自动化，并以 AI 为核心。

文档

架构	规范	软件包
发票 / 报价单 / 收据（日本インボイス制度）	invoice/v1	docs/spec/invoice-v1.md → packages/schema-invoice/
设计文档	spec/v1	docs/spec/spec-v1.md → packages/schema-spec/
测试规范	test-spec/v1	docs/spec/test-spec-v1.md → packages/schema-test-spec/
测试表（制表符分隔）	test-spec-tsv/v1	docs/spec/test-spec-tsv-v1.md → packages/schema-test-spec-tsv/
API 规范	api-spec/v1	packages/schema-api-spec/
数据库设计（关系型）	db-spec/v1	packages/schema-db-spec/
数据库设计（NoSQL）	nosql-db-spec/v1	packages/schema-nosql-db-spec/
调查报告	investigation/v1	packages/schema-investigation/

如果存在规范文档，其中会包含 JSON Schema 链接、顶层字段表、YAML frontmatter 示例和验证示例。

桌面应用

桌面应用（Tauri 2 + SvelteKit）可在专用查看器中打开上述所有业务文档类型，在实时分栏视图中编辑 Markdown，并导出 A4 PDF。

• 查找：在文件列表筛选器中输入内容，搜索文件夹中 Markdown 文件和测试表的标题及正文；也可以将列表切换为缩略图网格。

• 阅读：缩放预览（50–300%，Ctrl/Cmd + + / - / 0 或 Ctrl + 滚轮）；打印和 PDF 始终以 100% 输出。

• 绘图：zumen 块会生成架构图，chart 块会根据相邻的 TSV 文件绘制柱状图 / 折线图 / 饼图，data 块会将 TSV 文件引用为表格。VS Code 扩展也会绘制相同的块；Chrome 扩展仅绘制 zumen，因为它无法读取相邻文件。

• 保持最新：应用会在启动时检查是否有更新版本，并在你同意后安装。Windows（x64 / ARM64）和 macOS 版本均已发布。

• 下载（Windows / macOS）：https://meta-taro.github.io/md-business/download/

• 用户指南（英文）：https://meta-taro.github.io/md-business/manual/

• 操作手册（日文）：https://meta-taro.github.io/md-business/manual/ja/

内置 MCP 服务

桌面应用是让 AI Agent 操作真相源层的入口。启动时，它会运行一个本地 MCP 服务，让 AI 客户端读取、验证、搜索、创建和更新你当前打开的文件夹中的业务文档。

• 在 MCP 选项卡中连接：Add settings to the open folder 会为读取该文件的客户端写入 .mcp.json，而 Copy client settings 会将可直接使用的 mcpServers 条目复制到剪贴板。
• 连接详情会在重启后保留，因此粘贴一次的设置会持续生效。
• about_md_business 会针对每项任务，按顺序说明“我可以在这里做什么”以及要调用哪些工具。文档工具包括 list_schemas、get_schema、read_document、validate_document、create_document、update_document 和 search_documents；测试表格则使用 read_tsv、append_tsv_row 和 update_tsv_row。每次调用都会根据声明的架构进行验证，并显示在应用中。
• 测试表格使用制表符分隔格式，而非 Markdown，因此 Agent 会逐行填写：未触及的行不会出现在差异中。search_documents 会将这些表格与 Markdown 文档一并列出，因此 Agent 无需获知表格路径，就能找到它。
• 如果文件夹是 git 仓库，git_status、git_diff 和 git_commit 可让 Agent 检查所做的更改并记录下来，让一天的编辑最终成为清晰易读的历史记录，而不是一堆未跟踪的文件。
• 外部 JSON / XML（交换格式的发票、银行对账单、会计导出文件）为只读：read_data 会将其作为树结构读取，data_to_table 会将重复部分引用为表格。read_har 用于读取网络捕获文件。
• 日志绝不会被完整读取：search_lines 和 read_lines 用于查找命中内容并读取其附近的行，filter_records 和 aggregate 用于处理 JSONL / TSV 记录，build_timeline 则按时间顺序合并多个文件。所有结果都会屏蔽令牌、Cookie 和电子邮件地址。save_evidence 会将摘录保存为文件，供调查报告引用；check_tsv 无需逐行读取测试表格即可对其进行检查。
• 对于声明为网站的文件夹（md-business.yml），declare_web_mode、web_mode_status、list_site_files、read_site_file 和 write_site_file 可让 Agent 编辑网站自身的文件，同时应用会实时显示结果。
• open_in_app 会将 Agent 刚写入的文档显示在你面前；list_open_documents / close_document 则可让它查看并整理选项卡。
• export_pdf 会请求应用打开文档并调出打印对话框，让 Agent 将排版完成的 A4 页面交给你保存——保存位置仍由你决定。
• capture_window 会拍摄应用自身的窗口，让 Agent 看到实际呈现效果，而不是根据文件猜测。画面中只有这个窗口——桌面上的其他内容都不会入镜——而且照片仍归你所有，除非你同意，否则不会公开。
• 访问范围仅限应用中当前打开的文件夹；服务只绑定到回环地址，不带匹配令牌的请求都会被拒绝。
• Agent 写入文件时，文件列表和预览会自动同步更新——无需重新加载或手动刷新。

git push 刻意未作为工具开放，服务也绝不会接收机密信息或 API 密钥。协议详情请参阅 packages/mcp-server/。

发布历史

四款应用——桌面应用、Chrome 扩展、VS Code 扩展和 Workspace Add-on——均采用独立版本管理。CHANGELOG.md 列出了每款应用的当前版本，并链接到各自的历史记录。

约定

• 数据单元格约定 — 空单元格是未填写数据的唯一规范表示。不要用 — / – / ― / N/A / TBD 填充表格单元格。
• 快照表格 — 说明获取的数据存放在哪里，以及包含哪些列。每一行都会记录数据的来源时间和地点；重新获取的数据会追加，绝不覆盖。

快速入门

使用

无需构建步骤、Node.js 或包管理器。

1. 下载桌面应用（Windows x64 / ARM64 .msi / .exe、macOS .dmg）并安装。或者，如果你只需要在浏览器中阅读和打印文档，可以添加 Chrome 扩展程序。
2. 打开一个文件夹。带有 schema: frontmatter 键的任何 .md 文件都会在对应文档类型的查看器中打开；.tsv 测试表会在网格编辑器中打开。
3. 从模板开始——从 templates/ 复制一个模板，或者使用文件列表中的 ＋ 按钮，根据列预设创建测试表。
4. 从预览中打印为 A4 PDF。

用户指南（日本語）介绍了其余内容。

若要让 AI Agent 编辑这些文档，请将 MCP 客户端连接到桌面应用运行的服务。在右侧面板中打开 MCP 标签页：将设置添加到打开的文件夹会在该文件夹中写入 .mcp.json——读取该文件的客户端（包括 Claude Code）会自动加载设置；或者，复制客户端设置会将相同的条目复制到剪贴板，以便用于在其他位置配置的客户端。无论哪种方式，配置看起来都如下所示，端口和令牌已自动填入：

{
  "mcpServers": {
    "md-business": {
      "type": "http",
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

<PORT> 和 <TOKEN> 显示在该面板中，并会在重启后保留，因此粘贴一次的设置可以持续使用。令牌是访问凭据：在 Git 仓库中，应用写入 .mcp.json 时会将其添加到 .gitignore。服务绑定到 loopback，不接受缺少匹配令牌的请求，且访问范围不会超出当前打开的文件夹。

若要独立运行服务，而不使用桌面应用，请参阅 packages/mcp-server/。

开发

需要 Node.js 24+ 和 pnpm（通过 corepack 安装）。不支持 npm 和 yarn。构建桌面应用还需要 Tauri 2 前置条件（Rust 工具链和平台 WebView）。

corepack enable
pnpm install
pnpm dev

检查——提交更改前必须全部通过：

pnpm lint       # svelte-check (desktop) / tsc --noEmit (everything else)
pnpm typecheck  # same checkers, run as their own task
pnpm test:run   # Vitest, with coverage where it is configured
pnpm build      # every package and app

详情请参阅 CONTRIBUTING.md。

贡献

欢迎提交问题和 PR。若要添加新架构或分发渠道，请参阅 CONTRIBUTING.md。

许可证

MIT——欢迎自由分叉和定制。也鼓励创建不向上游合并的衍生仓库（例如 schema-invoice-custom）。