内容
# Maket
**将您的 AI 助手转变为视觉设计师。** 描述您想要的 - 海报、传单、产品标签、社交帖子 - AI 助手将其组成一个 HTML/CSS 文档，具有精确的排版、品牌图表、您的图像库和用于可重复变体的键入数据集合。实时预览实时更新。完成后导出为 PDF 或作为草稿发送到 Gmail。
[](LICENSE)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/ng-galien/maket/actions/workflows/ci.yml)
[](https://github.com/ng-galien/maket/actions/workflows/ci.yml)
[](#contributing)
<p align="center">
<img src="docs/demo.gif" alt="Maket demo walkthrough" width="800" />
</p>
<p align="center">
<em>60 秒 · 图表 → 库 → 数据 → AI 组成 → 各种文档 → 导出。</em>
</p>
---
## 为什么选择 Maket
您的 AI 助手擅长写作。但设计是关于空间、层次和节奏的 - 而这发生在布局中，而不是散文中。Maket 为 AI 助手提供了一个**真正的画布**（以毫米为单位的 HTML/CSS 页面）、一个**实时预览**，反映每一个更改、一个**资产 + 品牌库**，以确保输出的一致性，以及**键入数据集合**，将一个页面模板变成一个验证的变体系列。您留在对话中；AI 助手处理工艺。
## 功能
- **实时预览** - 更改立即在浏览器中显示。单击任何元素进行注释，并将反馈发送回聊天。
- **HTML/CSS 画布** - 页面是真正的 HTML，大小以毫米为单位。没有专有格式锁定。
- **品牌图表** - 定义设计令牌（颜色、字体、间距、阴影）一次；Maket 在组成过程中强制执行它们。
- **图像库** - 放入图像，标记它们，AI 为简介选择正确的图像。
- **数据驱动的集合** - 定义键入字段与 JSON 模式，粘贴或编辑有序行，将页面绑定到诸如 `{{ product_name }}` 的占位符，预览一行或整个系列，并为每行渲染一个输出页面。
- **PDF 导出** - 通过无头 Chromium 进行打印就绪输出。
- **Gmail 草稿** - 组成电子邮件文档，并将其作为草稿发送到 Gmail；您审查并发送给自己。
- **纸张和屏幕格式** - A2-A8，以及用于数字模型的 DESKTOP/TABLET/MOBILE 宽高比。
- **代理技能包含** - 三种技能（`maket`、`maket-charte`、`maket-review`），教 AI 助手如何设计、品牌和审查文档。
## 它的样子
```
您 - 为周日晚上爵士音乐会制作一张 A5 传单，氛围温暖
AI - maket_doc new doc="爵士音乐会传单" format=A5 orientation=portrait
maket_charte view name="Smoky Club"
maket_html set doc="爵士音乐会传单" page=1 context_token=...
→ 实时预览打开。温暖的琥珀色在深海军蓝上，衬线字体的标题，细无衬线字体用于场地详情。
您 - （点击预览中的日期）“把它变大”
AI - maket_workspace list_messages → 看到您的备注
maket_html patch doc="爵士音乐会传单" ops=[...]
→ 日期缩放，层次重新平衡。
您 - 完美，导出
AI - maket_pdf doc="爵士音乐会传单"
→ ~/.maket/exports/jazz-flyer.pdf
```
## 数据驱动的文档
集合将一个页面变成一个可重用的模板，用于产品标签、活动徽章、个性化传单、证书、目录页面或任何其他重复的文档。每个集合都有一个 **JSON 模式** 和一组有序的行。将它绑定到一个页面，将键入的值放在 HTML 中使用 `{{ field_name }}`，Maket 为每行渲染一个变体。
集合工作区和 `maket_collection` 工具都支持模式更改、行插入/更新/删除、粘贴导向的表格编辑和验证反馈。Maket 在渲染之前验证模式、每行和每个占位符。在预览中，您可以保持原始模板可见、检查选定的行或显示完整的生成系列；打印和 PDF 输出将绑定的页面扩展到所有行。
```text
您 - 创建一个包含名称和价格的产品标签系列
AI - maket_doc new doc="产品标签" format=A6 orientation=portrait
maket_collection action=create name=products
schema='{"type":"object","properties":{"product_name":{"type":"string"},"price":{"type":"string"}},"required":["product_name","price"]}'
maket_collection action=add_row name=products
data='{"product_name":"Earl Grey","price":"12 €"}'
maket_collection action=add_row name=products
data='{"product_name":"Sencha","price":"14 €"}'
maket_collection action=bind doc="产品标签" page=1 name=products
maket_html set doc="产品标签" page=1
html='<article data-id="label"><h1 data-id="name">{{ product_name }}</h1><p data-id="price">{{ price }}</p></article>'
→ 预览可以显示模板、任一产品或两个生成的标签。
您 - 导出整个系列
AI - maket_pdf doc="产品标签"
→ 每个集合行一个 PDF 页面。
```
## 安装
### 选项 A - npm（推荐）
```bash
# 将 Maket 集成到您的 AI 客户端（一次性 - 删除 --apply 进行试运行）
npx -y @ng-galien/maket install claude --apply
npx -y @ng-galien/maket install codex --apply
npx -y @ng-galien/maket install gemini --apply
# 启动本地服务器并打开预览
npx -y @ng-galien/maket start
npx -y @ng-galien/maket open
```
CLI 在 `~/.claude.json`（或运行 `claude mcp add` 如果已安装 Claude Code CLI）中注册了一个 `mcpServers.maket` 条目，在 `~/.codex/config.toml` 中添加了一个 `[mcp_servers.maket]` 部分，或在 `~/.gemini/settings.json` 中添加了一个 `mcpServers.maket` 条目。没有参数时，二进制文件作为_stdio MCP 桥运行 - 这是 Claude Desktop、Codex、Gemini 和其他 MCP 客户端自动调用的表单。
守护进程控制：`maket status`、`maket logs [--bridge]`、`maket stop`、`maket restart`。诊断：`maket doctor`、`maket config`。升级：`maket update [--check]`。撤销安装：`maket uninstall <claude|codex|gemini> --apply`。在 `install claude` 上使用 `--scope=project` 以写入 `<cwd>/.mcp.json` 而不是用户范围文件。全局标志 `--data-dir`、`--port`、`--host` 覆盖任何命令上的匹配 `MAKET_*` 环境变量。
### 选项 B - 克隆并修改
```bash
git clone https://github.com/ng-galien/maket.git
cd maket
npm install
npm run dev
```
在 `:24843` 上启动服务器，在 `:5173` 上启动 Vite HMR。包含的 `.mcp.json` 将项目中打开的 MCP 客户端指向 `http://localhost:24843/mcp`。
### 代码质量和架构规则
Maket 使用 `code-moniker` 进行结构规则和代码异味审查。版本控制的规则源是 `.code-moniker.toml`；运行 `npm run smell:rules` 检查默认规则，运行 `npm run smell:review` 审查存储库。质量门户通过 `npm run quality` 运行此审查。
不要在 `AGENTS.md` 中添加可强制执行的架构或边界规则，也不要在 `code-moniker` 之外添加临时检查脚本。`AGENTS.md` 是存储库中特工的工作指南；它不是项目的规则引擎。如果边界规则尚无法用 `code-moniker` 表示，请将其记录为 `code-moniker` 演变，而不是创建另一个本地规则系统。
例外是本地和明确的。如果故意不应用规则，请保持规则启用并在被检查的文件中添加有针对性的抑制注释，例如 `// code-moniker: ignore[smell-long-callable]`，并在附近解释设计原因。
### 选项 C - 将其打包为桌面扩展（.mcpb）
```bash
npm install -g @anthropic-ai/mcpb
npm run build:client
node scripts/pack-mcpb.ts
# → dist/maket.mcpb
```
将 `dist/maket.mcpb` 拖入桌面 MCP 主机（例如 Claude Desktop → 设置 → 扩展）。
**要求：** Node.js ≥22 和兼容 MCP 的客户端（Claude Code、Claude Desktop、Codex、Gemini 或类似）。
### CLI 参考
```text
maket [command] [--data-dir <path>] [--port <n>] [--host <h>]
bridge 以 stdio ↔ HTTP MCP 代理运行（MCP 客户端的默认形式）
start 在后台启动 Maket HTTP 服务器
stop 停止由 'maket start' 启动的服务器
restart 停止（如果正在运行）然后启动
status 显示服务器是否可达
open 在浏览器中打开 Maket UI
logs [--bridge] 跟踪服务器（或桥）日志
config 打印已解析的运行时配置
doctor 一次性诊断（节点、端口、数据目录、Chromium、Gmail、npm）
update [<version>] 升级 CLI（或固定到 <version>）；--check 进行无操作比较
install <client> 将 Maket 集成到 MCP 客户端（claude | codex | gemini）
uninstall <client> 从 MCP 客户端删除 Maket（claude | codex | gemini）
安装/卸载标志：--apply，--scope=user|project
gmail <sub> 管理 Gmail OAuth 状态 （status | reset [--force]）
help, version
```
## 工具
Maket 暴露了 13 个复合 MCP 工具。每个工具调度多个操作：
| 工具 | 功能 |
|------|--------------|
| `maket_doc` | 文档生命周期 — 新建、列表、删除、复制、重命名、元数据、导入/导出 |
| `maket_learn` | 代理人入职 — 工作流程、HTML 组成、图表、集合、审查、安装 |
| `maket_workspace` | 会话操作 — 焦点、状态、锁定、列出消息、确认消息 |
| `maket_page` | 页面结构 — 添加、删除、重命名、重新排序、列表 |
| `maket_canvas` | 画布设置 — 格式、方向、背景、每边打印边距 |
| `maket_html` | 页面内容 — `set`（完全替换）、`patch`（通过 `data-id` 进行外科手术操作）、`get`、`check`（布局溢出/重叠/边距间隙） |
| `maket_charte` | 品牌图表 — 列表、查看、设置、删除 |
| `maket_collection` | 类型化数据集合 — 列表、查看、创建、验证/更改模式、添加/更新/删除行、绑定/解绑页面 |
| `maket_image` | 资产库 — 列表、查看、元数据、导入、删除 |
| `maket_preview` | 打开实时预览 URL 或将页面快照为 PNG |
| `maket_mermaid` | 将 Mermaid 图形渲染为 SVG 并注入 |
| `maket_pdf` | 通过无头 Chromium 将文档导出为 PDF |
| `maket_gmail` | Gmail — 连接、搜索、读取、草稿 |
**布局和打印边距指南： [docs/layout.md](docs/layout.md)** - 预览中的青色安全区意味着什么，每种用例的边距预设，以及当某些内容看起来不对劲时要向助手提出的提示。
## 插件和技能
MCP 服务器公开了 `maket_learn`，这是代理人入职的真实来源。技能保持薄：它们将 Claude、Codex 或 Gemini 导向实时工具指导，而不是复制产品知识。人类入职是分开的，从 Maket UI 中的帮助按钮打开。
`plugin/claude/` 目录提供了三个代理技能：
- **`maket`** — 入门技能。从 `maket_learn` 开始，然后使用 MCP 工具进行设计工作。
- **`maket-charte`** — 品牌身份专家。从简介、行业或参考 URL 构建连贯的设计令牌系统。
- **`maket-review`** — 质量保证代理。审计图表合规性、图像路径、布局溢出；通过 `maket_html patch` 修复问题。
Claude、Codex 和 Gemini 兼容性文件位于 `plugin/` 下。
## 配置
默认情况下，Maket 将数据存储在 `~/.maket/` 中：
- `documents.db` — SQLite（文档、图表、集合、资产元数据）
- `assets/`、`documents/`、`exports/` — 用户文件
用环境变量覆盖：
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `MAKET_PORT` | `24842`（或开发模式下的 `3333`） | HTTP 服务器端口 |
| `MAKET_DATA_DIR` | `~/.maket/` | 用户数据目录 |
| `MAKET_DB` | `$MAKET_DATA_DIR/documents.db` | SQLite 路径 |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | — | Gmail OAuth 凭证（可选） |
### Gmail 集成（可选，高级用户）
Maket 可以将撰写的文档转换为 Gmail 草稿（带有 PDF 附件）。它**仅创建草稿** - 绝不发送。您在 Gmail 中审查草稿并亲自点击发送。
设置大约需要 10 分钟：您在 Google Cloud Console 中注册自己的 OAuth 台式机客户端，启用 Gmail API，将自己添加为测试用户，并将 JSON 粘贴到 Maket 的设置表单中。凭证存储在 `~/.maket/` 下，具有仅限所有者权限 - 仓库中没有内容，任何服务器上都没有内容。
**完整演练 + 故障排除： [docs/gmail-setup.md](docs/gmail-setup.md).**
快速 CLI 助手（设置完成后）：
```bash
maket gmail status # 检查凭证是否就位
maket gmail reset --force # 擦除并重新开始
```
### 引导下游工作区
如果您将 Maket 作为长期运行的服务器运行，并希望其他项目连接到它：
```bash
make bootstrap DIR=/path/to/my-project PORT=3335
```
在目标目录中创建 `.mcp.json`、`.claude/skills/` 和一个最小的 `package.json`。绝不会覆盖现有文件。
## 架构
<details>
<summary>各个部分如何组合</summary>
```
┌──────────┐ MCP Streamable HTTP ┌────────────────────────┐
│ AI 代理 │ ──────────────────────► │ Express @ :3333 │
│ （任意 │ │ ├─ /mcp (MCP 服务器) │
│ MCP │ │ ├─ /assets, /export │
│ 客户端) │ │ └─ WS /ws (预览) │
└──────────┘ └────────┬───────────────┘
│
┌────────┴────────┐
│ SQLite │
│ ~/.maket/*.db │
└─────────────────┘
│
▼ WS 广播
┌─────────────────┐
│ React 预览 │
│ （Vite，:5173） │
└─────────────────┘
```
- **MCP 通过 Streamable HTTP** - 无状态，每个请求一个服务器。
- **Awilix DI** - 每个服务、工具包和 HTTP 路由都在 `packages/server/src/bootstrap.ts` 中注册。
- **存储 → 总线 → WebSocket** - 每个突变都会发出一个类型化事件；预览会协调。
- **`packages/shared`** - 仅限 wire-contract 类型（WS 消息，HTTP 信封）。域类型保留在每侧。
参见 [`CLAUDE.md`](CLAUDE.md) 以获取完整的架构指南。
</details>
## 开发
```bash
npm run dev # 服务器 + Vite HMR（最常见）
npm run quality # lint + 类型检查 + 测试（提交前必须通过）
npm run test # vitest
```
预提交：`lefthook` 运行 `biome`、`tsc -b` 和 `vitest` - 所有三个都必须通过。
更多脚本：`dev:watch`（重建客户端到 `public/`）、`dev:server`、`dev:client`、`build:client`、`lint:fix`、`test:coverage`。参见 [`package.json`](package.json) 以获取完整列表。
## 贡献
欢迎贡献。要开始：
1. 复刻仓库并创建功能分支。
2. 运行 `npm install && npm run dev` 以设置环境。
3. 进行更改；保持它们有范围（一个错误修复不需要周围的清理）。
4. 运行 `npm run quality` - 它必须通过。
5. 打开一个带有清晰的更改描述和动机的 PR。
发现了错误，有想法，或在构建前要讨论某些内容？打开一个 [问题](https://github.com/ng-galien/maket/issues) 或开始一个 [讨论](https://github.com/ng-galien/maket/discussions)。
## 更新日志
在 [CHANGELOG.md](CHANGELOG.md) 中查看每个版本的用户可见更改。使用 `npm run changelog:draft` 撰写下一个 `[Unreleased]` 部分（将上次标记后的提交与常规提交类型分组）。
## 许可
[MIT](LICENSE) — © Alexandre Boyer
连接信息
猜你喜欢
暂无推荐服务器