dr-robert-li/cowork-wordpress-expert

构建设置技能

生成 SETUP.md — 用户的导入后配置和内容替换指南 — 并使用 NL 特定的元数据更新 build.json。此技能在 build-content 之后、zip 打包之前运行。

输入变量（由 build-theme 和 build-content 设置）：

变量	来源	描述
BUILD_DIR	build-scaffold	构建工作目录的绝对路径
NL_PROMPT	COMMAND.md 第1节	原始自然语言站点描述
THEME_SLUG	build-theme	已安装的主题别名
THEME_NAME	build-theme	人类可读的主题名称
THEME_VERSION	build-theme	已安装的主题版本字符串
THEME_INSTALLED	build-theme	布尔值 — 主题是否成功安装
INSTALLED_PLUGINS	build-content	成功安装的插件数组，格式为 slug:name:version
FAILED_PLUGINS	build-content	安装或激活失败的插件别名数组
PAGES_CREATED	build-content	创建的页面数量（整数）
POSTS_CREATED	build-content	创建的文章数量（整数）
MENU_ASSIGNED	build-content	布尔值 — 导航菜单是否已分配给主题位置
MENU_LOCATION	build-content	使用的主题位置名称（如果未分配，则为空字符串）

---

第1节：SETUP.md 生成

使用所有可用的上下文（已安装的插件、主题、页面数量和 NL 提示）编写 $BUILD_DIR/SETUP.md，以生成一个按优先级排序的设置指南，用户可以在将站点导入 Local WP 后立即遵循。

echo "[构建] 正在生成 SETUP.md..."

# ── 构建“已安装内容”部分 ────────────────────────────────────────

SETUP_FILE="$BUILD_DIR/SETUP.md"

# 开始编写 SETUP.md
cat > "$SETUP_FILE" << 'SETUP_HEADER'
# 设置指南

本指南将引导您在将新 WordPress 站点导入 Local WP 后进行配置。项目按优先级排序 — 请先完成关键步骤，然后按自己的节奏处理重要和可选步骤。

---

## 已安装内容

SETUP_HEADER

# 主题条目
echo "- **主题：** ${THEME_NAME}（v${THEME_VERSION}）" >> "$SETUP_FILE"
echo "" >> "$SETUP_FILE"

# 插件列表
if [ ${#INSTALLED_PLUGINS[@]} -gt 0 ]; then
  echo "- **插件：**" >> "$SETUP_FILE"
  for plugin_entry in "${INSTALLED_PLUGINS[@]}"; do
    # 格式：slug:name:version
    PLUGIN_SLUG=$(echo "$plugin_entry" | cut -d: -f1)
    PLUGIN_NAME=$(echo "$plugin_entry" | cut -d: -f2)
    PLUGIN_VER=$(echo "$plugin_entry" | cut -d: -f3)
    # Claude 根据插件别名和名称生成每个插件的一行用途
    PLUGIN_PURPOSE="<${PLUGIN_NAME} 功能的一行描述 — 由 Claude 根据插件知识生成>"
    echo "  - **${PLUGIN_NAME}**（v${PLUGIN_VER}）— ${PLUGIN_PURPOSE}" >> "$SETUP_FILE"
  done
  echo "" >> "$SETUP_FILE"
fi

# 失败的插件（如果有）
if [ ${#FAILED_PLUGINS[@]} -gt 0 ]; then
  echo "- **安装失败的插件：**" >> "$SETUP_FILE"
  for slug in "${FAILED_PLUGINS[@]}"; do
    echo "  - ${slug} — 构建期间尝试安装但失败" >> "$SETUP_FILE"
  done
  echo "" >> "$SETUP_FILE"
fi

接下来，编写按优先级排序的操作列表。这是一个 AI 判断任务 — Claude 会根据其对每个插件的设置工作流程的了解，利用 NL 提示上下文来确定对于此特定站点而言最重要的事项，从而生成每个插件的实际分步说明。

# ── 构建“下一步做什么”部分 ────────────────────────────────────────

cat >> "$SETUP_FILE" << 'SETUP_NEXT'
---

## 下一步做什么（按优先级排序）

SETUP_NEXT

# ── 关键项目 ────────────────────────────────────────────────────────────
echo "### 关键" >> "$SETUP_FILE"
echo "" >> "$SETUP_FILE"

STEP_NUM=1

# 对于每个需要配置的已安装插件，Claude 会生成
# 包含完整 WordPress 管理导航路径的分步说明。
# 例如 WPForms Lite：
#
#   echo "${STEP_NUM}. **配置 WPForms — 创建您的联系表单**" >> "$SETUP_FILE"
#   cat >> "$SETUP_FILE" << 'EOF'
#      转到：**WPForms > 添加新表单**
#      步骤：
#      1. 点击“选择模板”并选择 **简单联系表单**
#      2. 点击“使用模板” — 表单构建器打开
#      3. （可选）通过从左侧面板拖拽来添加或删除字段
#      4. 点击右上角的 **保存**
#      5. 转到 **页面 > 联系我们 > 编辑**
#      6. 添加新块，搜索“WPForms”，然后选择 WPForms 块
#      7. 从下拉列表中选择您刚刚创建的表单
#      8. 点击 **更新** 以保存页面
#   EOF
#   STEP_NUM=$((STEP_NUM + 1))

# Claude 为 INSTALLED_PLUGINS 中每个需要进行用户配置的插件生成等效块。
# 无需设置即可工作的插件（例如，静默激活的缓存插件）可以在重要部分中记录，
# 如果无需任何操作，则可以省略。

# ── 联系页面占位符替换（始终是关键） ────────────────────
echo "${STEP_NUM}. **替换联系页面的占位符信息**" >> "$SETUP_FILE"
cat >> "$SETUP_FILE" << 'CONTACT_STEP'
   转到：**页面 > 联系我们 > 编辑**
   用您的真实信息替换以下占位符内容：
   - 页面标题中的虚构业务名称
   - 虚构的街道地址（例如，“123 Example Street, Sample City”）
   - 虚构的电话号码
   - 虚构的电子邮件地址
   - 任何虚构的营业时间或位置详情

CONTACT_STEP
STEP_NUM=$((STEP_NUM + 1))

# ── 重要项目 ───────────────────────────────────────────
echo "" >> "$SETUP_FILE"
echo "### 重要" >> "$SETUP_FILE"
echo "" >> "$SETUP_FILE"

# 关于页面内容替换
echo "${STEP_NUM}. **更新关于页面内容**" >> "$SETUP_FILE"
cat >> "$SETUP_FILE" << 'ABOUT_STEP'
   转到：**页面 > 关于我们 > 编辑**
   替换以下占位符内容：
   - 虚构的业务/个人名称和传记
   - 任何虚构的团队成员描述
   - 占位头像或个人资料图片（通过媒体块上传您自己的）
   - 任何虚构的资质、历史或起源故事

ABOUT_STEP
STEP_NUM=$((STEP_NUM + 1))

# 主页内容替换
echo "${STEP_NUM}. **更新主页的英雄横幅和介绍内容**" >> "$SETUP_FILE"
cat >> "$SETUP_FILE" << 'HOME_STEP'
   转到：**页面 > 首页 > 编辑**
   替换以下占位符内容：
   - 英雄横幅标题和标语（使其具体针对您的业务或优惠）
   - 英雄横幅背景或特色图片（通过封面/图像块上传）
   - 描述您业务内容的介绍段落
   - 任何行动号召按钮标签和链接

HOME_STEP
STEP_NUM=$((STEP_NUM + 1))

# 基于站点类型的附加页面 — Claude 为 PAGES_CREATED 中主页、关于和联系我们之外的每个页面生成针对页面的指南。示例：
#
# 作品集页面：
#   echo "${STEP_NUM}. **将您的实际作品添加到作品集页面**" >> "$SETUP_FILE"
#   ...
#   STEP_NUM=$((STEP_NUM + 1))
#
# 服务页面：
#   echo "${STEP_NUM}. **使用您的实际服务更新服务页面**" >> "$SETUP_FILE"
#   ...
#   STEP_NUM=$((STEP_NUM + 1))
#
# Claude 使用 NL_PROMPT 上下文来确定存在哪些附加页面以及它们包含哪些占位符内容，
# 然后编写有针对性的指南。

# 属于重要（非关键）的任何其他插件配置
# Claude 在此处为需要设置但如果不配置不会破坏站点的插件添加步骤（例如，SEO 插件配置、图库设置）

# ── 可选项目 ────────────────────────────────────────────
echo "" >> "$SETUP_FILE"
echo "### 可选" >> "$SETUP_FILE"
echo "" >> "$SETUP_FILE"

# 示例文章替换
echo "${STEP_NUM}. **添加您自己的博客文章以替换示例内容**" >> "$SETUP_FILE"
cat >> "$SETUP_FILE" << 'POSTS_STEP'
   示例文章演示了您的主题如何渲染博客内容。它们使用与您站点主题相关的、
   逼真但虚构的主题。
   转到：**文章 > 所有文章** 以编辑现有示例或添加新文章。
   发布您自己的内容后，可以删除示例文章。

POSTS_STEP
STEP_NUM=$((STEP_NUM + 1))

# 占位图片替换
echo "${STEP_NUM}. **用您自己的照片替换占位图片**" >> "$SETUP_FILE"
cat >> "$SETUP_FILE" << 'IMAGES_STEP'
   构建过程中生成了纯色占位图片以显示布局意图。
   用您自己的图片替换它们：
   转到：**媒体 > 添加新媒体** 以上传您的照片
   然后编辑每个页面/文章，并将占位图片块替换为您上传的内容。

IMAGES_STEP
STEP_NUM=$((STEP_NUM + 1))

# 如果未自动分配菜单（FSE 块主题边缘情况）
if [ "$MENU_ASSIGNED" = "false" ] || [ "$MENU_ASSIGNED" = "" ]; then
  echo "${STEP_NUM}. **在站点编辑器中分配导航菜单**" >> "$SETUP_FILE"
  cat >> "$SETUP_FILE" << 'MENU_STEP'
   您的导航菜单在构建期间创建，但无法自动分配给主题位置（这是块主题的预期行为）。
   转到：**外观 > 编辑器 > 导航**
   选择“主菜单”并将其放置在页眉导航区域。

MENU_STEP
  STEP_NUM=$((STEP_NUM + 1))
fi

# 完成 SETUP.md
echo "---" >> "$SETUP_FILE"
echo "" >> "$SETUP_FILE"
echo "*由 WordPress Expert 插件生成 — CoWork 构建系统*" >> "$SETUP_FILE"

SETUP_ITEM_COUNT=$((STEP_NUM - 1))
echo "[构建] SETUP.md 已生成（${SETUP_ITEM_COUNT} 个设置项）"

给 Claude 的实施说明：

• 插件说明是一项 AI 判断任务。 对于 INSTALLED_PLUGINS 中的每个插件，Claude 会根据其对该插件设置工作流程的了解，生成详细、分步的说明。说明必须包含完整的 WP 管理导航路径（例如，“转到 WPForms > 添加新表单 > 选择联系表单模板 > 保存 > 复制短代码 > 编辑联系页面 > 添加短代码块”）。
• 上下文决定优先级。 Claude 会阅读 NL_PROMPT 以确定哪些设置项属于关键 vs 重要。对于摄影作品集站点，替换作品集图片属于关键。对于餐厅，配置预订插件属于关键。
• 逐页覆盖。 build-content 创建的每个页面都会获得一个专属条目，其中包含关于它包含哪些占位符内容的具体指南。
• 无通用说明。 所有指南都针对特定插件和站点类型 — 而非通用的“配置您的插件”建议。

---

第2节：build.json NL 元数据更新

读取现有的 build.json（由 build-scaffold 第6节创建）并添加 NL 特定字段。使用与 build-mcp 第4节相同的 Python3 JSON 解析模式。

echo "[构建] 正在使用 NL 元数据更新 build.json..."

BUILD_JSON="$BUILD_DIR/build.json"

# 构建用于 JSON 序列化的数组
INSTALLED_JSON=""
for plugin_entry in "${INSTALLED_PLUGINS[@]}"; do
  PLUGIN_SLUG=$(echo "$plugin_entry" | cut -d: -f1)
  PLUGIN_NAME=$(echo "$plugin_entry" | cut -d: -f2)
  PLUGIN_VER=$(echo "$plugin_entry" | cut -d: -f3)
  if [ -n "$INSTALLED_JSON" ]; then
    INSTALLED_JSON="${INSTALLED_JSON},"
  fi
  INSTALLED_JSON="${INSTALLED_JSON}{\"slug\":\"${PLUGIN_SLUG}\",\"name\":\"${PLUGIN_NAME}\",\"version\":\"${PLUGIN_VER}\",\"installed\":true}"
done

FAILED_JSON=""
for slug in "${FAILED_PLUGINS[@]}"; do
  if [ -n "$FAILED_JSON" ]; then
    FAILED_JSON="${FAILED_JSON},"
  fi
  FAILED_JSON="${FAILED_JSON}\"${slug}\""
done

# 将 Python 脚本写入临时文件（与 build-content 图片生成器相同的模式）
NL_META_SCRIPT="/tmp/update_build_json_$$.py"

cat > "$NL_META_SCRIPT" << PYEOF
import json, sys

build_file = sys.argv[1]
nl_prompt = sys.argv[2]
theme_slug = sys.argv[3]
theme_name = sys.argv[4]
theme_version = sys.argv[5]
theme_installed = sys.argv[6] == 'true'
pages_created = int(sys.argv[7])
posts_created = int(sys.argv[8])
menu_assigned = sys.argv[9] == 'true'
installed_json = sys.argv[10]
failed_json = sys.argv[11]

with open(build_file) as f:
    data = json.load(f)

data['mode'] = 'nl'
data['nl_prompt'] = nl_prompt
data['theme'] = {
    'slug': theme_slug,
    'name': theme_name,
    'version': theme_version,
    'installed': theme_installed
}
data['plugins'] = json.loads('[' + installed_json + ']') if installed_json else []
data['content'] = {
    'pages_created': pages_created,
    'posts_created': posts_created,
    'menu_assigned': menu_assigned
}
if failed_json:
    data['failed_plugins'] = json.loads('[' + failed_json + ']')

with open(build_file, 'w') as f:
    json.dump(data, f, indent=2)

print('[构建] build.json 已使用 NL 元数据更新')
PYEOF

python3 "$NL_META_SCRIPT" \
  "$BUILD_JSON" \
  "$NL_PROMPT" \
  "$THEME_SLUG" \
  "$THEME_NAME" \
  "$THEME_VERSION" \
  "${THEME_INSTALLED:-true}" \
  "$PAGES_CREATED" \
  "$POSTS_CREATED" \
  "${MENU_ASSIGNED:-false}" \
  "$INSTALLED_JSON" \
  "$FAILED_JSON"

# 清理临时脚本
rm -f "$NL_META_SCRIPT"

更新 NL 元数据后的 build.json：

{
  "build_id": "nl-photography-portfolio-20260220-143022",
  "mode": "nl",
  "nl_prompt": "a portfolio site for a freelance photographer",
  "wp_version": "6.7",
  "php_version": "8.2",
  "site_url": "http://localhost",
  "site_title": "a portfolio site for a freelance photographer",
  "created_at": "2026-02-20T14:30:22Z",
  "theme": {
    "slug": "blocksy",
    "name": "Blocksy",
    "version": "2.0.50",
    "installed": true
  },
  "plugins": [
    { "slug": "envira-gallery-lite", "name": "Envira Gallery Lite", "version": "1.9.0", "installed": true },
    { "slug": "wpforms-lite", "name": "WPForms Lite", "version": "1.9.0", "installed": true }
  ],
  "content": {
    "pages_created": 4,
    "posts_created": 3,
    "menu_assigned": false
  },
  "failed_plugins": [],
  "mcp_adapter": {
    "included": true,
    "activated": true,
    "version": "0.4.1"
  }
}

---

第3节：构建摘要扩展

附加

…

[因翻译而截断]