Draughtsman

Draughtsman

原生面向 Agent、可自托管的绘图工具。 Draughtsman 图表是一个类型化图，而非图片：节点和边都带有类型、端口和属性，并存储在由你运行的数据库中。图有一种无损文本格式（DSL），供人和 AI Agent 阅读、比较差异和编写；内置 MCP 服务让 Agent 可以直接创建、修改、评审和渲染图表。画布编辑器、导出内容和渲染结果都来自同一模型。它运行在你自己的服务上，除非你启用明确说明会向外发送数据的可选功能，否则数据不会离开你的网络。

• 类型化图模型：四种文档类型（流程图、架构图、自由形式图和时序图），Agent 可通过 get_schema 查询类型词汇表。
• 无损文本 DSL：打印图表、编辑文本，再解析回来，内容不会丢失。差异以句子形式呈现，因此图表适合纳入 git。
• MCP 服务：通过 HTTP（/mcp）或 stdio（draughtsman mcp --stdio）提供八种工具。
• 可自托管：单个可执行文件（或单个容器），默认使用 SQLite，也可选择 Postgres。无需在我们这里创建账户，也不会向我们发送数据。

快速开始

你需要一台能够运行 Docker 的机器，或一个发行版压缩包。大约需要五分钟。

Docker

无需注册、无需在我们这里创建账户，也无需申请。目前还没有将镜像发布到仓库，因此需要从本仓库构建。 最快的方法是使用 docker-compose.yml：

git clone https://github.com/overpassapps/draughtsman.git && cd draughtsman
docker compose up -d --build
docker compose logs draughtsman | grep "setup code"

也可以手动操作，并在主机上创建一个文件夹来存放数据：

docker build -t draughtsman:local .

mkdir -p draughtsman-data && sudo chown -R 10001:10001 draughtsman-data && sudo chmod 700 draughtsman-data   # Linux; Docker Desktop needs no chown
docker run -d --name draughtsman --restart unless-stopped \
  -p 127.0.0.1:5180:5180 \
  -v "$(pwd)/draughtsman-data:/data" \
  draughtsman:local

curl -s http://127.0.0.1:5180/api/health      # {"status":"ok"}
docker logs draughtsman 2>&1 | grep "setup code"

打开 http://localhost:5180，输入日志中的一次性设置码，然后创建第一个管理员。端口仅绑定到 loopback；如需供其他人访问，请在前面配置反向代理（docs/deployment.md）。完整 Docker 指南：docs/install-docker.md。

要发布多平台镜像（linux/amd64 和 linux/arm64，可在任何机器上从一个 Dockerfile 构建，包括 Apple silicon），请使用 docker-container 构建器；默认构建器无法推送多平台镜像。构建阶段会在你的机器上原生运行，只有最终运行阶段因平台而异：

docker buildx create --name multi --driver docker-container --use    # once
docker buildx build --platform linux/amd64,linux/arm64 -t docker.io/wroolie/draughtsman:<ver> --push .

发行版压缩包

macOS（Apple silicon 和 Intel）、Linux（x64、arm64）和 Windows（x64、arm64）的压缩包解压后即为一个文件夹，无需安装其他内容：无需 .NET，也无需 Node。目前尚未发布任何版本，因此没有可供链接的下载内容；scripts/publish.sh <platform> 可从源代码构建压缩包，docs/install.md 介绍了解压、作为服务运行和校验和。

tar -xzf draughtsman-0.1.0-linux-x64.tar.gz && cd draughtsman-0.1.0-linux-x64
./draughtsman                      # http://localhost:5180

从源代码构建

需要 .NET SDK 10.0.x（在 global.json 中固定）和 Node 22.12 或更高版本：

dotnet run --project src/Draughtsman.Server        # http://localhost:5180

如果 web/dist 存在，Web 应用会从中提供（cd web && npm ci && npm run build）。CONTRIBUTING.md 介绍了完整的开发流程。

通过 MCP 连接 AI Agent

登录后，打开顶栏中的 Tokens，创建一个令牌（密钥 dst_… 只会显示一次），然后：

# a running server, over HTTP (Claude Code shown; any MCP client that speaks streamable HTTP works)
claude mcp add --transport http draughtsman http://127.0.0.1:5180/mcp --header "Authorization: Bearer dst_…"

# the same machine and data folder, over stdio: no token, no port
claude mcp add draughtsman -e DRAUGHTSMAN_DATA=/path/to/data -- /path/to/draughtsman mcp --stdio

这些工具包括 list_documents、read_document、create_document、patch_document、render_document、diff_documents、critique_document 和 get_schema。令牌可以设为只读。SKILL.md 是一份现成的 Agent 技能说明，介绍了 DSL 和这些工具；HTTP 接口规范见 docs/api.md。

已构建的功能

• 编辑器：提供画布，支持平移、缩放、框选、吸附、撤销和重做；连接线可绕开形状布线（直角、直线、曲线）；支持端口、容器和分组、样式面板、文本窗格（在画布旁编辑 DSL 或 Mermaid）、触控笔和触控操作，以及将 Agent 的编辑实时合并到打开的图表中。
• 图表类型和形状：流程图（ISO 5807 符号、BPMN、泳道）、架构图（通用技术图标、组织结构图、UML 类和接口）、时序图（按消息顺序编辑，支持片段和注释）、自由图、UML 状态图形状、带有列间连接线的数据库表，以及基本形状。
• 导入：Mermaid（流程图和时序图，以及 erDiagram）、SQL DDL（T-SQL、PostgreSQL、MySQL、SQLite）、draw.io 和 Visio .vsdx（也可通过 Lucidchart 的 Visio 导出文件导入）。
• 导出：在浏览器中导出 PNG 和 SVG；通过浏览器的打印对话框导出 PDF（或通过可选的 Chromium 组件在服务器端导出）；还可导出 DSL、JSON、Mermaid、SQL，以及打包为单个独立 HTML 文件的漫游演示。
• 漫游演示：沿图表路径移动的摄像机视角；演示保存在文档中，可全屏播放并显示字幕。
• 团队功能：本地账户（Administrator 和 Editor）、API 令牌、回收站、可命名的版本（支持比较和还原）、评审面板、缩略图、用于设置品牌、主题、AI 和电子邮件的管理页面，以及通过命令行备份和还原。
• 可选 AI：使用自带模型（Ollama、任何兼容 OpenAI 的端点、Anthropic、Azure OpenAI），支持从文本生成和图表转文档。默认关闭，需由管理员配置；使用本地 Ollama 时，数据不会离开你的网络。
• 运维：支持 SQLite 或 Postgres，提供 Docker 镜像、适用于 systemd、launchd 和 Windows 的服务安装程序、draughtsman doctor 和 config check、升级安全检查（SQLite 迁移失败时自动回滚），以及隔离网络安装方式（docs/air-gapped.md、docs/data-flow.md）。

完整长版说明（含配置）见 docs/status.md。

尚未实现

我们希望你能先在这里了解这些情况：

• 单点登录（OIDC、SAML）和 default 以外的工作区。登录仅支持本地方式。
• Viewer 角色或按文档设置权限。所有已登录用户都能读取所有图表，Editor 可以修改任何图表。
• 实时多人协同编辑。打开的编辑器会轮询并合并较新版本；若保存的版本已过时，系统会拒绝保存，而不会覆盖现有内容。
• 已发布的容器镜像和发行版压缩包。目前需要从源代码自行构建，压缩包也尚未进行代码签名或公证。
• SQL Server 存储（目前支持 SQLite 和 Postgres）。
• 无需在服务器上额外安装组件的 PDF 渲染器：服务器端生成 PDF 需要可选的 Chromium 组件，而且 render_document 无法返回 PNG。
• BPMN 形状的按类型主题颜色，以及服务器端对边类型的样式设置（服务器渲染会将 BPMN 消息流画成普通箭头）。
• 漫游演示的视频或 GIF 导出；BPMN 补偿、循环和多实例标记，以及编舞图。
• 自动清理无引用的已上传图片，以及清理安全事件日志。
• Windows 是一个发行目标，并拥有独立的 CI 阶段，但与 Linux 和 macOS 相比，Windows 压缩包和 service install 的验证还不够充分。

已知限制的完整列表见 CHANGELOG.md。

文档

完整文档：https://draughtsman.overpass.co.uk/docs/。本仓库的 docs/ 中也包含相同页面，以及构建规范、架构决策、文档架构和 DSL 语法。

许可

Draughtsman 是自由软件，仅依据 GNU Affero 通用公共许可证 v3.0 发布（LICENSE）。版权所有 © Overpass Limited。你可以使用、修改和分支它；如果你将修改后的版本作为网络服务运行，就必须向使用该服务的人提供其源代码。

如果 AGPL 不适合你，Overpass 也提供 Draughtsman 的商业许可（COMMERCIAL-LICENSE.md）。该许可允许你的组织修改 Draughtsman，并将其连接到自有系统供内部使用，同时对这些修改保密，无需履行 AGPL 要求的向网络用户提供源代码的义务。最多 50 人的团队一次性支付 £1,500，人数不限则一次性支付 £3,000。两种许可均包含 12 个月的更新和电子邮件支持；续订更新服务的费用为标价的 25%／年。该许可涵盖在组织内部运行 Draughtsman；如需将其嵌入面向他人的产品或服务，请咨询单独协议。如需购买或咨询，请发送邮件至 [email protected]。

购买商业许可。 商业许可通过电子邮件购买：发送邮件至 [email protected]，注明组织名称和所需许可等级，我们会回复订单供你确认，并发送发票。许可文本见 COMMERCIAL-LICENSE.md；你购买时生效的版本即为你接受的版本。

第三方组件仍适用各自的许可：请参阅 THIRD-PARTY-NOTICES.txt。

贡献

欢迎提交错误报告、想法和拉取请求。请先阅读 CONTRIBUTING.md。外部贡献者需要签署贡献者许可协议，以便 Overpass Limited 能继续提供商业许可。所有参与者都应遵守行为准则。如有疑问，请使用 GitHub Discussions，而不要提交 issue。

支持项目

Draughtsman 由 Overpass 构建和维护。如果它为你节省了时间，可以通过 https://github.com/sponsors/overpassapps 赞助这项工作。

安全

请将漏洞私下报告至 [email protected]，不要在公开 issue 中报告。有关范围、时间安排和安全模型，请参阅 SECURITY.md。

---

由 Overpass 制作。