Apostrophe Cms Generator

🚀 Apostrophe代码生成器

Apostrophe代码生成器是一款由AI驱动的工具，借助Claude AI和MCP（模型上下文协议）架构，为Apostrophe CMS模块生成代码。它能有效提升开发效率，让开发者更轻松地创建各类模块。

🚀 快速开始

# 1. 确保已安装先决条件
node --version    # 版本必须 >= 18
claude --version  # 必须安装Claude Code CLI

# 2. 安装
./install.sh      # Linux/macOS
# 或者手动安装：
npm install && cd mcp-server && npm install

# 3. 运行
npm start

# 4. 打开浏览器
# http://localhost:3031

就这么简单！ 选择一个项目，选择模块类型，进行配置，然后生成代码。

✨ 主要特性

• 片段生成器：创建存储在数据库中的内容类型。
• 页面生成器：生成具有内容区域和片段关系的页面类型。
• 小部件生成器：创建具有关系模式的可重用UI组件。
• 捆绑包生成器：一次性生成完整的功能集（片段 + 页面 + 小部件）。
• 设计令牌提取：自动提取并使用项目的设计令牌生成SCSS。
• BEM方法：可选的遵循BEM命名约定的SCSS生成（实验性）。
• 自动注册：自动将生成的模块注册到项目的modules.js中。
• SCSS集成：自动创建并导入SCSS文件。
• 生成历史记录：浏览和重用以前生成的模块。

⚠️ 重要提示

CSS/SCSS生成是实验性的。结果可能因项目复杂性和设计令牌可用性而异。在部署到生产环境之前，请始终审查生成的样式。

📦 安装指南

快速安装（推荐）

# 克隆或下载仓库
cd /path/to/apostrophe-code-generator

# 运行安装脚本
./install.sh

安装脚本将执行以下操作：

1. 检查Node.js和npm。
2. 安装主应用程序依赖项。
3. 安装MCP服务器依赖项。
4. 可选地配置Claude Code集成。

手动安装

如果你更喜欢手动安装：

# 导航到项目目录
cd /path/to/apostrophe-code-generator

# 安装主依赖项
npm install

# 安装MCP服务器依赖项
cd mcp-server
npm install
cd ..

💻 使用示例

启动应用程序

# 从项目根目录
npm start

# 或者在开发模式下使用自动重新加载
npm run dev

服务器将在 http://localhost:3031 上启动。

使用Web界面

1. 打开浏览器 并导航到 http://localhost:3031。
2. 选择一个项目：从下拉列表中选择一个Apostrophe项目。项目会从父目录中自动发现。
3. 选择模块类型：选择你要生成的内容：
   • 片段：存储在数据库中的内容类型。
   • 页面：具有内容区域的页面类型。
   • 小部件：可重用的UI组件。
   • 捆绑包：完整的功能集（片段 + 页面 + 小部件）。
4. 配置选项：填写模块详细信息：
   • 模块名称
   • 描述
   • 字段和关系
   • 样式选项（BEM、设计令牌）
5. 生成：点击“生成代码”，让AI创建你的模块。
6. 保存到项目：审查生成的代码并直接保存到你的项目中。

生成历史记录

所有生成的模块都会保存到历史记录中。你可以：

• 查看以前生成的模块
• 使用修改后的设置重新生成
• 将代码复制到剪贴板
• 从历史记录中删除

🔧 技术细节

高级：直接Claude Code MCP集成

本节为可选内容。localhost:3031 上的Web UI是使用此工具的主要方式。此MCP集成仅适用于希望直接从Claude Code CLI调用生成器而不使用Web界面的高级用户。

为什么使用此功能？

如果你已经在Apostrophe项目的Claude Code会话中工作，你可以直接要求Claude Code使用生成器工具来生成模块，而无需切换到浏览器。

示例：在Claude Code中，你可以说：

"使用apostrophe-generator为my-project创建一个名为news-feed的小部件"

配置

1. 找到你的Claude Code设置文件：
   • Linux/macOS：~/.claude/settings.json
   • Windows：%USERPROFILE%\.claude\settings.json
2. 添加MCP服务器配置：

{
  "mcpServers": {
    "apostrophe-generator": {
      "command": "node",
      "args": ["/absolute/path/to/apostrophe-code-generator/mcp-server/index.js"],
      "env": {},
      "description": "Apostrophe CMS代码生成工具"
    }
  }
}

将 /absolute/path/to/ 替换为你实际的安装路径。 3. 重启Claude Code 以加载新的MCP服务器。

可用的MCP工具

配置完成后，Claude Code中可使用以下工具：

工具	描述
list_apostrophe_projects	列出所有发现的Apostrophe项目
generate_piece	生成一个片段模块
generate_page	生成一个页面模块
generate_widget	生成一个小部件模块
generate_bundle	生成一个完整的捆绑包
save_generated_code	将生成的代码保存到项目中

生成模块结构

片段模块

片段是存储在数据库中的内容类型（如文章、产品、团队成员）。 生成的文件：

modules/pieces/{piece-name}/
└── index.js              # 带有字段的模式定义

无模板 - 片段仅为数据；它们通过片段页面或小部件显示。 index.js结构：

export default {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Piece Name',
    pluralLabel: 'Piece Names',
    seoFields: false,
    openGraph: false
  },
  fields: {
    add: {
      // 自定义字段在此定义
      description: { type: 'string', label: 'Description' },
      featuredImage: {
        type: 'area',
        label: 'Featured Image',
        options: {
          widgets: { '@apostrophecms/image': {} }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: ['title', 'description', 'featuredImage']
      }
    }
  }
};

页面模块

页面是可通过URL路由的内容，可以显示片段（片段页面）或独立内容。 生成的文件：

modules/pages/{page-name}/
├── index.js              # 模式定义
└── views/
    ├── index.html        # 列表视图（用于片段页面）
    └── show.html         # 详细视图（用于片段页面）

对于独立页面，仅生成 page.html 而不是index/show。 index.js结构：

export default {
  extend: '@apostrophecms/piece-page-type',  // 或 '@apostrophecms/page-type'
  options: {
    label: 'Page Name',
    pieceModuleName: 'piece-name'  // 仅适用于片段页面
  },
  fields: {
    add: {
      // 页面特定的字段
    },
    group: {
      // 字段组
    }
  }
};

小部件模块

小部件是可重用的UI组件，可以放置在内容区域中。 生成的文件：

modules/widgets/{widget-name}-widget/
├── index.js              # 模式定义
└── views/
    └── widget.html       # 小部件模板

注意：小部件文件夹名称始终以 -widget 后缀结尾。 index.js结构：

export default {
  extend: '@apostrophecms/widget-type',
  fields: {
    add: {
      heading: { type: 'string', label: 'Heading' },
      content: {
        type: 'area',
        label: 'Content',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: ['heading', 'content']
      }
    }
  }
};

widget.html模板：

<div class="widget-name-widget" data-widget-name-widget>
  <h2>{{ data.widget.heading }}</h2>
  {% area data.widget, 'content' %}
</div>

捆绑包模块

捆绑包一次性生成一个完整的功能集：片段 + 片段页面 + 小部件。 生成的文件：

modules/
├── pieces/{name}/
│   └── index.js
├── pages/{name}-page/
│   ├── index.js
│   └── views/
│       ├── index.html
│       └── show.html
└── widgets/{name}-widget/
    ├── index.js
    └── views/
        └── widget.html

捆绑包关系：

• 小部件自动包含一个 _pieces 关系字段以引用片段。
• 页面被配置为片段类型的片段页面。

SCSS生成（可选）

当启用 BEM样式 时，会生成额外的SCSS文件。

生成的SCSS文件

modules/asset/ui/src/scss/
├── components/
│   └── _{widget-name}.scss    # 用于小部件
└── pages/
    └── _{page-name}.scss      # 用于页面

SCSS特性

• BEM方法：块-元素-修饰符命名约定。
• 设计令牌集成：使用项目现有的设计令牌（颜色、间距、排版）。
• 自动导入：SCSS文件会自动导入到主样式表中。

示例生成的SCSS：

// _news-widget.scss
.news-widget {
  padding: $spacing-lg;
  background-color: $color-background;

  &__heading {
    font-size: $font-size-xl;
    color: $color-text-primary;
    margin-bottom: $spacing-md;
  }

  &__content {
    line-height: $line-height-relaxed;
  }

  &__item {
    border-bottom: 1px solid $color-border;
    padding: $spacing-md 0;

    &:last-child {
      border-bottom: none;
    }
  }
}

设计令牌提取

生成器会自动扫描项目中的设计令牌，位置如下：

• modules/asset/ui/src/scss/_settings.scss
• modules/asset/ui/src/scss/_variables.scss
• 任何匹配 *variables* 或 *tokens* 模式的文件

提取的令牌类型：

• 颜色 ($color-*)
• 间距 ($spacing-*)
• 排版 ($font-*, $line-height-*)
• 断点 ($breakpoint-*)

自动注册

生成的模块会自动注册到项目的 modules.js 文件中。

添加的内容

// modules.js
module.exports = {
  // ... 现有模块 ...

  // 由代码生成器自动添加：
  'news': {},                    // 片段
  'news-page': {},               // 页面
  'news-widget': {},             // 小部件
};

SCSS导入

如果生成了SCSS，会在主SCSS文件中添加导入语句：

// 在 _components.scss 或 main.scss 中
@import 'components/_news-widget';

历史记录存储

所有生成的模块都会保存到 history/ 文件夹中，以便参考和重用。

历史记录文件夹结构

history/
└── 2025-11-18_14-30-45_news-widget/
    ├── metadata.json
    └── modules/
        └── widgets/
            └── news-widget/
                ├── index.js
                └── views/
                    └── widget.html

元数据格式

{
  "moduleName": "news-widget",
  "moduleType": "widget",
  "projectName": "my-apostrophe-project",
  "fileCount": 2,
  "fullDesign": false,
  "description": "A widget to display latest news items",
  "timestamp": "2025-11-18T14:30:45.123Z"
}

历史记录特性

• 查看：浏览以前生成的模块。
• 重新生成：使用以前的设置作为起点。
• 复制：直接将代码复制到剪贴板。
• 删除：从历史记录中删除条目（不影响保存的项目文件）。

API端点

Express服务器暴露以下端点：

端点	方法	描述
/api/projects	GET	列出发现的Apostrophe项目
/api/generate	POST	生成一个模块
/api/save	POST	将生成的文件保存到项目中
/api/delete	POST	从项目中删除保存的文件
/api/history	GET	列出生成历史记录
/api/history/:id	GET	获取特定的历史记录条目
/api/history/:id	DELETE	删除历史记录条目

生成请求格式

{
  "projectId": "my-project",
  "type": "widget",
  "name": "news",
  "label": "News Widget",
  "description": "Display latest news with images and summaries",
  "includeBemStyles": true,
  "fullDesign": false
}

生成响应格式

{
  "success": true,
  "files": [
    {
      "path": "modules/widgets/news-widget/index.js",
      "content": "export default { ... }"
    },
    {
      "path": "modules/widgets/news-widget/views/widget.html",
      "content": "<div class=\"news-widget\">...</div>"
    }
  ],
  "registrationNote": "Module registered in modules.js",
  "historyId": "2025-11-18_14-30-45_news-widget"
}

字段类型参考

模块模式可用的字段类型：

类型	描述	示例
string	单行文本	{ type: 'string', label: 'Title' }
area	富内容区域	{ type: 'area', options: { widgets: {...} } }
boolean	复选框（true/false）	{ type: 'boolean', label: 'Featured' }
select	下拉菜单	{ type: 'select', choices: [...] }
checkboxes	多选	{ type: 'checkboxes', choices: [...] }
relationship	链接到其他片段	{ type: 'relationship', withType: 'article' }
array	重复字段组	{ type: 'array', fields: { add: {...} } }
date	日期选择器	{ type: 'date', label: 'Publish Date' }
time	时间选择器	{ type: 'time', label: 'Event Time' }
url	URL输入	{ type: 'url', label: 'Website' }
email	电子邮件输入	{ type: 'email', label: 'Contact Email' }
integer	整数	{ type: 'integer', label: 'Quantity' }
float	小数	{ type: 'float', label: 'Price' }
slug	URL安全字符串	{ type: 'slug', following: 'title' }
color	颜色选择器	{ type: 'color', label: 'Background Color' }
range	滑块输入	{ type: 'range', min: 0, max: 100 }
attachment	文件上传	{ type: 'attachment', label: 'Document' }

保留字段名称

切勿使用这些名称 - 它们是Apostrophe保留的：

• type, _id, slug, published, archived
• trash, visibility, createdAt, updatedAt
• metaType, aposMode, aposLocale

替代方案：

• 代替 type → 使用 category, kind, itemType
• 代替 status → 使用 currentStatus, statusLabel

项目结构

apostrophe-code-generator/
├── server/                     # Express服务器
│   ├── index.js               # 主服务器入口点
│   ├── mcp-client.js          # 用于AI生成的MCP客户端
│   └── apostrophe-docs/       # Apostrophe文档和模式
├── mcp-server/                 # 用于Claude Code的MCP服务器
│   ├── index.js               # MCP服务器入口点
│   ├── generator.js           # 代码生成逻辑
│   ├── design-token-parser.js # 设计令牌提取
│   ├── package.json           # MCP服务器依赖项
│   └── mcp-config.json        # 示例MCP配置
├── public/                     # Web UI
│   ├── index.html             # 主向导界面
│   ├── css/                   # 样式表
│   └── js/                    # 客户端JavaScript
├── docs/                       # 文档
├── history/                    # 生成的模块历史记录
├── install.sh                  # 安装脚本
├── package.json               # 主要依赖项
└── README.md                  # 此文件

配置

服务器端口

默认端口是 3031。要更改它，请设置 PORT 环境变量：

PORT=8080 npm start

项目发现

默认情况下，该工具会在父目录中查找Apostrophe项目。此行为是自动的，无需配置。

故障排除

常见问题

"Cannot find module '@modelcontextprotocol/sdk'"

MCP服务器依赖项未安装。运行：

cd mcp-server
npm install

"No projects found"

确保你的Apostrophe项目在父目录中，并且包含一个带有 shortName 属性的 app.js 文件：

// app.js
module.exports = require('apostrophe')({
  shortName: 'my-project',
  // ...
});

"Claude API timeout" 或生成失败

1. 确保安装了Claude Code：claude --version
2. 确保配置了Claude Code：claude configure
3. 检查你的Anthropic API密钥是否有效
4. 尝试更简单的模块描述
5. 检查你的互联网连接

"MCP server failed"

1. 检查Claude设置中的MCP服务器路径是否正确
2. 确保所有依赖项都已安装
3. 检查Node.js版本（需要 >= 18）

端口已在使用中

另一个应用程序正在使用端口3031。你可以：

• 停止其他应用程序
• 使用不同的端口：PORT=3032 npm start

获取帮助

如果你遇到问题：

1. 检查浏览器控制台以查看错误信息
2. 检查终端以查看服务器端错误
3. 确保满足所有先决条件
4. 验证项目结构是否符合预期格式

架构

组件

1. Express服务器 (server/index.js)
   • 提供Web UI
   • 处理API请求
   • 管理项目发现
   • 与MCP服务器通信
2. MCP服务器 (mcp-server/index.js)
   • 提供由AI驱动的代码生成
   • 与Claude AI集成
   • 为Claude Code集成暴露工具
3. Web UI (public/)
   • 向导式界面
   • 实时生成进度
   • 历史记录管理

数据流

用户输入 → Express服务器 → MCP服务器 → Claude AI
                                    ↓
用户 ← Web UI ← Express服务器 ← 生成的代码

开发

在开发模式下运行

npm run dev

这将启动服务器，并在文件更改时自动重新加载。

构建Tailwind CSS

如果你修改了样式：

./tailwindcss-linux-x64 -i public/css/input.css -o public/css/styles.css --watch

贡献

欢迎贡献代码！请确保：

1. 代码遵循现有模式
2. 记录新功能
3. 通过测试（如果适用）

Windows安装

install.sh 脚本适用于Linux/macOS。Windows用户应手动安装：

使用命令提示符

cd path\to\apostrophe-code-generator

:: 安装主依赖项
npm install

:: 安装MCP服务器依赖项
cd mcp-server
npm install
cd ..

:: 启动服务器
npm start

使用PowerShell

cd path\to\apostrophe-code-generator

# 安装主依赖项
npm install

# 安装MCP服务器依赖项
cd mcp-server
npm install
cd ..

# 启动服务器
npm start

Windows先决条件

1. Node.js：从 https://nodejs.org/ 下载（v18+）
2. Claude Code：npm install -g @anthropic-ai/claude-code
3. 配置Claude：claude configure

兼容性

Apostrophe CMS版本

Apostrophe版本	支持情况
4.x (A4)	✅ 是
3.x (A3)	✅ 是
2.x (A2)	❌ 否
此工具为 Apostrophe 3.x和4.x 生成代码。模块结构、字段类型和模板语法与A3和A4都兼容。

Node.js版本

Node.js版本	支持情况
22.x	✅ 是
20.x	✅ 是
18.x	✅ 是
16.x及以下	❌ 否

操作系统

操作系统	支持情况
Linux	✅ 是
macOS	✅ 是
Windows 10/11	✅ 是
WSL/WSL2	✅ 是

已知限制

SCSS生成（实验性）

• 当项目有明确定义的设计令牌时，SCSS生成效果最佳。
• 如果项目中不存在令牌，生成的SCSS可能包含未定义的变量。
• 在编译之前，请始终审查生成的SCSS。
• 复杂的布局可能需要手动调整。

AI生成

• 结果取决于描述的质量。
• 非常复杂的模块可能需要多次生成或手动编辑。
• 生成时间会有所不同（通常根据复杂性为10 - 60秒）。
• 偶尔的JSON解析错误可能需要重试。

项目发现

• 仅发现 父目录 中的项目。
• 项目必须有带有 shortName 属性的 app.js 文件。
• 符号链接的项目可能无法被发现。

捆绑包生成

• 捆绑包一次生成3个模块 - 这可能需要更长时间。
• 所有3个模块共享相同的基本名称。
• 无法自定义捆绑包内各个模块的名称。

FAQ

一般问题

问：我需要Anthropic API密钥吗？ 答：是的。Claude Code需要从 https://console.anthropic.com/ 获取的API密钥。

问：使用这个工具需要多少钱？ 答：工具本身是免费的。你通过Anthropic账户支付Claude API的使用费用。每次生成通常使用1,000 - 5,000个令牌。

问：我可以离线使用这个工具吗？ 答：不可以。该工具需要互联网连接才能与Claude AI通信。

项目问题

问：为什么我的项目没有出现在下拉列表中？ 答：请确保你的项目：

• 位于此工具的父目录中。
• 有一个 app.js 文件。
• 在app.js中包含 shortName: 'your-project'。

问：我可以更改项目发现的位置吗？ 答：目前不可以。项目必须位于父目录中。未来版本可能会支持配置。

生成问题

问：生成的代码有错误。我该怎么办？ 答：尝试：

1. 简化你的描述。
2. 再次生成（AI响应可能会有所不同）。
3. 手动编辑生成的代码。
4. 检查是否使用了保留字段名称。

问：我可以在保存之前编辑生成的代码吗？ 答：目前在UI中不可以。你可以先生成、保存，然后在IDE中进行编辑。

问：我如何重新生成一个模块？ 答：使用历史记录功能查看以前的生成记录，并使用修改后的设置重新生成。

样式问题

问：SCSS中有未定义的变量。为什么？ 答：生成器使用项目的设计令牌。如果某个令牌不存在，变量将未定义。请用实际值替换或在项目中添加这些令牌。

问：我可以禁用SCSS生成吗？ 答：可以。在配置模块时，取消选中“Include BEM Styles”。

卸载

要删除代码生成器：

# 只需删除文件夹
rm -rf /path/to/apostrophe-code-generator

# 可选：如果不再需要，删除全局Claude Code
npm uninstall -g @anthropic-ai/claude-code

卸载此工具不会影响你Apostrophe项目中已生成的模块。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

致谢

创建者：Andrei Mateas 所属团队：GLOOBUS A-Team

本项目基于Claude AI和MCP（模型上下文协议）构建。

变更日志

v1.0.0

• 初始版本发布
• 片段、页面、小部件和捆绑包生成器
• 设计令牌提取
• BEM SCSS生成（实验性）
• 生成历史记录
• Claude Code MCP集成