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集成