Back to Details

admin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Handover - Admin Guide

项目交接 - 管理员指南

Generate comprehensive documentation for administrators taking over an AEM Edge Delivery Services project. Produces a complete admin guide with Config Service setup, permissions, Admin API operations, and troubleshooting.
为接管AEM Edge Delivery Services项目的管理员生成全面的文档。生成包含Config Service设置、权限、Admin API操作和故障排查的完整管理员指南。

When to Use This Skill

使用本Skill的场景

  • Project handover to client administrators
  • Documenting admin procedures for a project
  • Creating operations runbook
  • "Generate admin guide"
  • "Admin documentation"
  • "Admin handover"
  • 向客户管理员进行项目交接
  • 记录项目的管理员流程
  • 创建操作手册
  • 「生成管理员指南」
  • 「管理员文档」
  • 「管理员交接」

Step 0: Navigate to Project Root and Verify Edge Delivery Services Project (CONDITIONAL)

步骤0：导航至项目根目录并验证Edge Delivery Services项目（可选）

Skip this step if 
allGuides
flag is set (orchestrator already validated and navigated).
CRITICAL: If NOT skipped, you MUST execute the 
cd
command. Do NOT use absolute paths — actually change directory.
bash
ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"allGuides"[[:space:]]*:[[:space:]]*true')
if [ -z "$ALL_GUIDES" ]; then
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi
IMPORTANT:
  • You MUST run the 
    cd
    command above using the Bash tool
  • All subsequent steps operate from project root
  • Do NOT use absolute paths to verify — actually navigate
  • Guides will be created at 
    project-root/project-guides/
If NOT skipped AND 
scripts/aem.js
does NOT exist, respond:
"This skill is designed for AEM Edge Delivery Services projects. The current directory does not appear to be an Edge Delivery Services project (
scripts/aem.js
not found).
Please navigate to an Edge Delivery Services project and try again."
STOP if check fails. Otherwise proceed — you are now at project root.
如果已设置
allGuides
标志，则跳过此步骤（编排器已验证并导航到位）。
重要提示：如果未跳过此步骤，必须执行
cd
命令。请勿使用绝对路径——实际切换目录。
bash
ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"allGuides"[[:space:]]*:[[:space:]]*true')
if [ -z "$ALL_GUIDES" ]; then
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi
注意事项：
  • 必须使用Bash工具运行上述
    cd
    命令
  • 后续所有步骤均从项目根目录执行
  • 请勿使用绝对路径进行验证——实际导航至对应目录
  • 指南将创建在
    project-root/project-guides/
    路径下
如果未跳过此步骤且
scripts/aem.js
不存在，请回复：
"本Skill专为AEM Edge Delivery Services项目设计。当前目录似乎并非Edge Delivery Services项目（未找到
scripts/aem.js
）。
请导航至Edge Delivery Services项目后重试。"
如果检查失败，请停止操作。否则继续——你已处于项目根目录。

Execution Checklist

执行检查清单

markdown
- [ ] Phase 1: Gather Project Context
- [ ] Phase 2: Generate Admin Guide Content
- [ ] Phase 3: Customize for Project
- [ ] Phase 4: Generate Professional PDF
markdown
- [ ] 阶段1：收集项目上下文
- [ ] 阶段2：生成管理员指南内容
- [ ] 阶段3：针对项目定制内容
- [ ] 阶段4：生成专业PDF

Communication Guidelines

沟通准则

  • NEVER use "EDS" as an acronym for Edge Delivery Services in any generated documentation or chat responses
  • Always use the full name "Edge Delivery Services" or "AEM Edge Delivery Services"
  • This applies to all output files (PDF, HTML, markdown) and all communication with the user
  • **禁止使用"EDS"**作为Edge Delivery Services的缩写，在任何生成的文档或聊天回复中均不得使用
  • 始终使用完整名称"Edge Delivery Services"或"AEM Edge Delivery Services"
  • 此规则适用于所有输出文件（PDF、HTML、Markdown）以及与用户的所有沟通

⚠️ CRITICAL PATH REQUIREMENT

⚠️ 关键路径要求

YOU MUST SAVE THE FILE TO THIS EXACT PATH:
project-guides/ADMIN-GUIDE.md
BEFORE WRITING ANY FILE:
  1. First, create the directory: 
    mkdir -p project-guides
  2. Then write to: 
    project-guides/ADMIN-GUIDE.md
WHY THIS MATTERS: Files must be in 
project-guides/
for proper organization and PDF conversion.
❌ WRONG: 
ADMIN-GUIDE.md
(root) ❌ WRONG: 
docs/ADMIN-GUIDE.md
❌ WRONG: 
/workspace/ADMIN-GUIDE.md
✅ CORRECT: 
project-guides/ADMIN-GUIDE.md
必须将文件保存至以下精确路径：
project-guides/ADMIN-GUIDE.md
在写入任何文件之前：
  1. 首先创建目录：
    mkdir -p project-guides
  2. 然后写入至：
    project-guides/ADMIN-GUIDE.md
为何如此重要： 文件必须存放在
project-guides/
路径下，以确保组织规范并支持PDF转换。
❌ 错误路径： 
ADMIN-GUIDE.md
（根目录） ❌ 错误路径： 
docs/ADMIN-GUIDE.md
❌ 错误路径： 
/workspace/ADMIN-GUIDE.md
✅ 正确路径： 
project-guides/ADMIN-GUIDE.md

Output Format

输出格式

MANDATORY OUTPUT: 
project-guides/ADMIN-GUIDE.pdf
STRICTLY FORBIDDEN:
  • ❌ Do NOT read or analyze 
    fstab.yaml
    — it does NOT exist in most projects and does NOT show all sites
  • ❌ Do NOT create 
    .plain.html
    files
  • ❌ Do NOT use 
    convert_markdown_to_html
    tool — this converts the FULL guide to HTML with raw frontmatter visible, which is NOT what we want
  • ❌ Do NOT tell user to "convert markdown to PDF manually"
  • ❌ Do NOT save markdown to root directory or any path other than 
    project-guides/
  • ❌ Do NOT say "PDF will be generated later" or "at session end" — generate it NOW
The HTML output must be a SHORT summary page (created with Write tool) containing:
  • Title and brief description
  • "What's Inside" bullet list
  • PDF download link NOT the full guide content converted to HTML.
REQUIRED WORKFLOW:
  1. Run 
    mkdir -p project-guides
    to ensure directory exists
  2. Generate markdown content with YAML frontmatter (title, date)
  3. Save to 
    project-guides/ADMIN-GUIDE.md
    (EXACT PATH - no exceptions)
  4. IMMEDIATELY invoke PDF conversion (see Phase 4.1)
  5. Clean up all source files (only PDF remains)
  6. Final output: 
    project-guides/ADMIN-GUIDE.pdf
强制输出： 
project-guides/ADMIN-GUIDE.pdf
严格禁止：
  • ❌ 请勿读取或分析
    fstab.yaml
    ——大多数项目中不存在该文件，且无法显示所有站点信息
  • ❌ 请勿创建
    .plain.html
    文件
  • ❌ 请勿使用
    convert_markdown_to_html
    工具——该工具会将完整指南转换为HTML并显示原始前置内容，不符合需求
  • ❌ 请勿告知用户"手动将Markdown转换为PDF"
  • ❌ 请勿将Markdown保存至根目录或
    project-guides/
    以外的任何路径
  • ❌ 请勿说"PDF将稍后生成"或"会话结束时生成"——立即生成
HTML输出必须为简短摘要页面（使用Write工具创建），包含：
  • 标题和简要描述
  • "内容概览"项目符号列表
  • PDF下载链接 而非完整指南内容转换后的HTML。
要求的工作流程：
  1. 运行
    mkdir -p project-guides
    确保目录存在
  2. 生成带有YAML前置内容（标题、日期）的Markdown内容
  3. 保存至
    project-guides/ADMIN-GUIDE.md
    （精确路径——无例外）
  4. 立即调用PDF转换功能（参见阶段4.1）
  5. 清理所有源文件（仅保留PDF）
  6. 最终输出：
    project-guides/ADMIN-GUIDE.pdf

Phase 0: Get Organization Name (Required First)

阶段0：获取组织名称（必须首先执行）

Whenever this skill runs — whether the user triggered it directly (e.g. "generate admin guide") or via the handover flow — you must have the Config Service organization name before doing anything else. Do not skip this phase.
无论本Skill是由用户直接触发（例如"生成管理员指南"）还是通过交接流程触发，在执行任何操作之前必须先获取Config Service组织名称。请勿跳过此阶段。

0.1 Check for Saved Organization

0.1 检查已保存的组织信息

bash
undefined
bash
undefined

Check if org name is already saved

Check if org name is already saved

cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"org"[[:space:]]:[[:space:]]"[^"]*"' | head -1
undefined
cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"org"[[:space:]]:[[:space:]]"[^"]*"' | head -1
undefined

0.2 Prompt for Organization Name (If Not Saved)

0.2 提示用户提供组织名称（如果未保存）

If no org name is saved, you MUST pause and ask the user directly:
"What is your Config Service organization name? This is the 
{org}
part of your Edge Delivery Services URLs (e.g., 
https://main--site--{org}.aem.page
). The org name may differ from your GitHub organization."
IMPORTANT RULES:
  • DO NOT use 
    AskUserQuestion
    with predefined options     — ask as a plain text question
  • Organization name is MANDATORY — do not offer a "skip" option
  • Wait for user to type the org name before proceeding
  • If user doesn't provide a valid org name, ask again
如果未保存组织名称，必须暂停并直接询问用户：
"你的Config Service组织名称是什么？这是Edge Delivery Services URL中的
{org}
部分（例如
https://main--site--{org}.aem.page
）。组织名称可能与GitHub组织不同。"
重要规则：
  • 请勿使用带有预定义选项的
    AskUserQuestion
    ——以纯文本形式提问
  • 组织名称为必填项——请勿提供"跳过"选项
  • 等待用户输入组织名称后再继续
  • 如果用户未提供有效的组织名称，请再次询问

0.3 Save Organization Name

0.3 保存组织名称

Once you have the org name (either from saved config or user input), save it for future use:
bash
undefined
获取组织名称后（无论是从已保存的配置还是用户输入），将其保存以备将来使用：
bash
undefined

Create config directory if needed

Create config directory if needed

mkdir -p .claude-plugin
mkdir -p .claude-plugin

Ensure .claude-plugin is in .gitignore (contains auth tokens)

Ensure .claude-plugin is in .gitignore (contains auth tokens)

grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

Save org name to config file (create or update)

Save org name to config file (create or update)

if [ -f .claude-plugin/project-config.json ]; then cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]:[[:space:]]"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json else echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json fi

Replace `{ORG_NAME}` with the actual organization name provided by the user.

---
if [ -f .claude-plugin/project-config.json ]; then cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]:[[:space:]]"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json else echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json fi

将`{ORG_NAME}`替换为用户提供的实际组织名称。

---

Phase 0.5: Authenticate with Config Service (Browser Login)

阶段0.5：通过Config Service进行身份验证（浏览器登录）

After getting the organization name, authenticate using Playwright browser automation.
获取组织名称后，使用Playwright浏览器自动化工具进行身份验证。

0.5.1 Check for Existing Auth Token

0.5.1 检查现有身份验证令牌

bash
undefined
bash
undefined

Check if auth token is already saved

Check if auth token is already saved

AUTH_TOKEN=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"authToken"[[:space:]]:[[:space:]]"[^"]"' | sed 's/"authToken"[[:space:]]:[[:space:]]*"//' | sed 's/"$//')
if [ -n "$AUTH_TOKEN" ]; then echo "Auth token found" else echo "No auth token - need to authenticate" fi
undefined
AUTH_TOKEN=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"authToken"[[:space:]]:[[:space:]]"[^"]"' | sed 's/"authToken"[[:space:]]:[[:space:]]*"//' | sed 's/"$//')
if [ -n "$AUTH_TOKEN" ]; then echo "Auth token found" else echo "No auth token - need to authenticate" fi
undefined

0.5.2 Open Browser for Login (If No Token)

0.5.2 打开浏览器进行登录（如果无令牌）

If no auth token exists, use Playwright CLI:
  1. Install Playwright (if needed):
bash
npx playwright --version 2>/dev/null || npm install -g playwright
npx playwright install chromium 2>/dev/null || true
  1. Get the first site name (unauthenticated endpoint):
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
SITE=$(curl -s "https://admin.hlx.page/config/${ORG}/sites.json" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
  1. Display clear instructions and open browser:
bash
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║                                                                ║"
echo "║   BROWSER WINDOW OPENING FOR ADOBE ID LOGIN                    ║"
echo "║                                                                ║"
echo "║   1. Sign in with your Adobe ID credentials                   ║"
echo "║   2. After successful login, CLOSE THE BROWSER WINDOW         ║"
echo "║                                                                ║"
echo "║   >>> CLOSE THE BROWSER TO CONTINUE <<<                       ║"
echo "║                                                                ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""

mkdir -p .claude-plugin
npx playwright open --save-storage=.claude-plugin/auth-storage.json "https://admin.hlx.page/login/${ORG}/${SITE}/main"
如果不存在身份验证令牌，请使用Playwright CLI：
  1. 安装Playwright（如有需要）：
bash
npx playwright --version 2>/dev/null || npm install -g playwright
npx playwright install chromium 2>/dev/null || true
  1. 获取第一个站点名称（未验证端点）：
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
SITE=$(curl -s "https://admin.hlx.page/config/${ORG}/sites.json" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
  1. 显示清晰说明并打开浏览器：
bash
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║                                                                ║"
echo "║   正在打开浏览器窗口进行Adobe ID登录                          ║"
echo "║                                                                ║"
echo "║   1. 使用你的Adobe ID凭据登录                                ║"
echo "║   2. 登录成功后，关闭浏览器窗口                              ║"
echo "║                                                                ║"
echo "║   >>> 关闭浏览器以继续 <<<                                    ║"
echo "║                                                                ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""

mkdir -p .claude-plugin
npx playwright open --save-storage=.claude-plugin/auth-storage.json "https://admin.hlx.page/login/${ORG}/${SITE}/main"

0.5.3 Extract and Save Auth Token

0.5.3 提取并保存身份验证令牌

After browser is closed, extract token from storage file:
bash
echo "Browser closed. Extracting auth token..."

AUTH_TOKEN=$(node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.claude-plugin/auth-storage.json', 'utf8'));
const cookie = data.cookies.find(c => c.name === 'auth_token');
console.log(cookie ? cookie.value : '');
")

ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
echo "{\"org\": \"${ORG}\", \"authToken\": \"${AUTH_TOKEN}\"}" > .claude-plugin/project-config.json

rm -f .claude-plugin/auth-storage.json
echo "Auth token saved."
关闭浏览器后，从存储文件中提取令牌：
bash
echo "浏览器已关闭。正在提取身份验证令牌..."

AUTH_TOKEN=$(node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.claude-plugin/auth-storage.json', 'utf8'));
const cookie = data.cookies.find(c => c.name === 'auth_token');
console.log(cookie ? cookie.value : '');
")

ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
echo '{"org": "${ORG}", "authToken": "${AUTH_TOKEN}"}' > .claude-plugin/project-config.json

rm -f .claude-plugin/auth-storage.json
echo "身份验证令牌已保存。"

0.5.4 Verify Authentication

0.5.4 验证身份验证

Test the token works:
bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
测试令牌是否有效：
bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')

Test with authenticated endpoint

Test with authenticated endpoint

curl -s -w "%{http_code}" -o /dev/null -H "x-auth-token: ${AUTH_TOKEN}"
"https://admin.hlx.page/config/${ORG}/sites.json"

If returns 200, authentication is successful. If 401, re-authenticate.

---
curl -s -w "%{http_code}" -o /dev/null -H "x-auth-token: ${AUTH_TOKEN}"
"https://admin.hlx.page/config/${ORG}/sites.json"

如果返回200，则身份验证成功。如果返回401，请重新进行身份验证。

---

Phase 1: Gather Project Context

阶段1：收集项目上下文

1.1 Fetch Sites and Code Repo via Config Service API

1.1 通过Config Service API获取站点和代码仓库信息

⚠️ MANDATORY DATA SOURCE — NO ALTERNATIVES ALLOWED
You MUST call the Config Service API. This is the ONLY acceptable source for site information.
❌ PROHIBITED APPROACHES (will produce incorrect results):
  • Analyzing 
    fstab.yaml
    — does NOT show all sites in repoless setups
  • Reading 
    README.md
    — may be outdated or incomplete
  • Inferring from codebase structure — misses CDN configs and additional sites
  • Using git remote URLs — org name may differ from Config Service org
  • Making assumptions based on project folder names
✅ REQUIRED: Execute and save response:
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
⚠️ 必须使用此数据源——不允许使用其他替代方案
必须调用Config Service API。这是获取站点信息的唯一可接受来源。
❌ 禁止使用的方法（会产生错误结果）：
  • 分析
    fstab.yaml
    ——无法显示无仓库设置中的所有站点
  • 读取
    README.md
    ——可能已过时或不完整
  • 从代码库结构推断——会遗漏CDN配置和其他站点
  • 使用git远程URL——组织名称可能与Config Service组织不同
  • 根据项目文件夹名称做出假设
✅ 必须执行并保存响应：
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')

Save response to file - Step 1.2 depends on this file

Save response to file - Step 1.2 depends on this file

curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

**📁 REQUIRED ARTIFACT:** `.claude-plugin/sites-config.json`

**API Reference:** https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

The response is a JSON object with a `sites` array (each entry has a `name` field). Extract site names and construct per-site URLs:
- **Preview:** `https://main--{site-name}--{org}.aem.page/`
- **Live:** `https://main--{site-name}--{org}.aem.live/`

Multiple sites = **repoless** setup. Single site = **standard** setup.

**Then fetch individual site config for code and content details:**

```bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
curl -s -H "x-auth-token: ${AUTH_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Example response:
json
{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    }
  }
}
Extract from response:
  • code.owner
    / 
    code.repo
    — GitHub repository
  • content.source.url
    — Content mountpath (e.g., 
    https://content.da.live/org/site/
    )
  • content.source.type
    — Content source type (markup, onedrive, google)
⚠️ Do NOT use 
fstab.yaml
 — use Config Service API instead.
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

**📁 必须生成的文件：** `.claude-plugin/sites-config.json`

**API参考：** https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

响应为包含`sites`数组的JSON对象（每个条目包含`name`字段）。提取站点名称并构建每个站点的URL：
- **预览环境：** `https://main--{site-name}--{org}.aem.page/`
- **生产环境：** `https://main--{site-name}--{org}.aem.live/`

多个站点 = **无仓库**设置。单个站点 = **标准**设置。

**然后获取单个站点的配置以获取代码和内容详情：**

```bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
curl -s -H "x-auth-token: ${AUTH_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
示例响应：
json
{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    }
  }
}
从响应中提取：
  • code.owner
    / 
    code.repo
    — GitHub仓库
  • content.source.url
    — 内容挂载路径（例如
    https://content.da.live/org/site/
    ）
  • content.source.type
    — 内容源类型（markup, onedrive, google）
⚠️ 请勿使用
fstab.yaml
——请改用Config Service API。

1.2 Build Context

1.2 构建上下文

Read from artifact created in 1.1:
bash
cat .claude-plugin/sites-config.json
Parse the JSON to extract site names, then fetch each site's config for code repo:
bash
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Use these API responses to build context: site names, code repo (owner/repo), preview/live URLs. If site config includes a content source (e.g. content.da.live path), record it for the Sites table.
Admin Context:
├── Organization: {org from saved config}
├── Site(s): {site1}, {site2}, ... (from Config Service API response)
├── Setup Type: {repoless | standard} (from Config Service API)
├── Code Repo: {code.owner}/{code.repo} (from Config Service — GitHub or Cloud Manager)
├── Preview: https://main--{site}--{org}.aem.page/
├── Live: https://main--{site}--{org}.aem.live/
├── Login URL: https://admin.hlx.page/login/{org}/{site}
└── Config Service: https://admin.hlx.page/config/{org}/
从1.1中生成的文件读取内容：
bash
cat .claude-plugin/sites-config.json
解析JSON以提取站点名称，然后获取每个站点的配置以获取代码仓库信息：
bash
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
使用这些API响应构建上下文：站点名称、代码仓库（owner/repo）、预览/生产URL。如果站点配置包含内容源（例如content.da.live路径），请将其记录到站点表格中。
管理员上下文：
├── 组织：{从已保存配置获取的org}
├── 站点：{site1}, {site2}, ...（来自Config Service API响应）
├── 设置类型：{无仓库 | 标准}（来自Config Service API）
├── 代码仓库：{code.owner}/{code.repo}（来自Config Service — GitHub或Cloud Manager）
├── 预览环境：https://main--{site}--{org}.aem.page/
├── 生产环境：https://main--{site}--{org}.aem.live/
├── 登录URL：https://admin.hlx.page/login/{org}/{site}
└── Config Service：https://admin.hlx.page/config/{org}/

Phase 2: Generate Admin Guide

阶段2：生成管理员指南

Output File: 
project-guides/ADMIN-GUIDE.md

输出文件：
project-guides/ADMIN-GUIDE.md

Generate the admin handover document with the following structure:
markdown
undefined
生成管理员交接文档，结构如下：
markdown
undefined

[Project Name] - Admin Guide

[项目名称] - 管理员指南

Complete administration guide for managing this Edge Delivery Services project.
本Edge Delivery Services项目的完整管理指南。

Quick Reference

快速参考

URLs

URL

PurposeURL
Loginhttps://admin.hlx.page/login/{org}/{site}
Config Servicehttps://admin.hlx.page/config/{org}/
Previewhttps://main--{site}--{org}.aem.page/
Livehttps://main--{site}--{org}.aem.live/
用途URL
登录https://admin.hlx.page/login/{org}/{site}
Config Servicehttps://admin.hlx.page/config/{org}/
预览环境https://main--{site}--{org}.aem.page/
生产环境https://main--{site}--{org}.aem.live/

Sites (if multi-site/repoless)

站点（如果是多站点/无仓库设置）

SiteContent Source (DA)PreviewLive
{site1}[from site config if present]https://main--{site1}--{org}.aem.page/https://main--{site1}--{org}.aem.live/
{site2}[from site config if present]https://main--{site2}--{org}.aem.page/https://main--{site2}--{org}.aem.live/
站点内容源(DA)预览环境生产环境
{site1}[如果存在则来自站点配置]https://main--{site1}--{org}.aem.page/https://main--{site1}--{org}.aem.live/
{site2}[如果存在则来自站点配置]https://main--{site2}--{org}.aem.page/https://main--{site2}--{org}.aem.live/

Authentication

身份验证

Login

登录

  1. Open: https://admin.hlx.page/login/{org}/{site}
  2. Sign in with your Adobe ID
  3. Copy auth token for API operations
  1. 打开：https://admin.hlx.page/login/{org}/{site}
  2. 使用Adobe ID登录
  3. 复制身份验证令牌用于API操作

Logout

登出

bash
curl -X POST \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/logout/{org}/{site}/main"
bash
curl -X POST \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/logout/{org}/{site}/main"

User Management

用户管理

View Current Access

查看当前访问权限

bash
curl -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access.json"
bash
curl -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access.json"

Add User

添加用户

RoleCommand
Admin
POST /config/{org}/sites/{site}/access/admin.json
with 
{"users": ["email"]}
Author
POST /config/{org}/sites/{site}/access/author.json
with 
{"users": ["email"]}
角色命令
管理员
POST /config/{org}/sites/{site}/access/admin.json
，请求体为
{"users": ["email"]}
作者
POST /config/{org}/sites/{site}/access/author.json
，请求体为
{"users": ["email"]}

Remove User

删除用户

bash
curl -X DELETE \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"
bash
curl -X DELETE \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"

Content Operations

内容操作

Preview

预览

OperationEndpoint
Single page
POST /preview/{org}/{site}/main/{path}
Bulk preview
POST /preview/{org}/{site}/main/*
操作端点
单页面
POST /preview/{org}/{site}/main/{path}
批量预览
POST /preview/{org}/{site}/main/*

Publish

发布

OperationEndpoint
Single page
POST /live/{org}/{site}/main/{path}
Bulk publish
POST /live/{org}/{site}/main/*
Unpublish
DELETE /live/{org}/{site}/main/{path}
操作端点
单页面
POST /live/{org}/{site}/main/{path}
批量发布
POST /live/{org}/{site}/main/*
取消发布
DELETE /live/{org}/{site}/main/{path}

Cache

缓存

OperationEndpoint
Purge path
POST /cache/{org}/{site}/main/{path}
Purge all
POST /cache/{org}/{site}/main/*
操作端点
清除路径缓存
POST /cache/{org}/{site}/main/{path}
清除全部缓存
POST /cache/{org}/{site}/main/*

Code Operations

代码操作

Sync Code

同步代码

bash
curl -X POST \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/code/{owner}/{repo}/main"
bash
curl -X POST \
  -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/code/{owner}/{repo}/main"

Common Tasks

常见任务

TaskSteps
Add new adminPOST to 
/config/{org}/sites/{site}/access/admin.json
Republish sitePOST to 
/preview/{org}/{site}/main/*
then 
/live/{org}/{site}/main/*
Clear all cachePOST to 
/cache/{org}/{site}/main/*
Deploy code changesPOST to 
/code/{owner}/{repo}/main
任务步骤
添加新管理员向
/config/{org}/sites/{site}/access/admin.json
发送POST请求
重新发布站点先向
/preview/{org}/{site}/main/*
发送POST请求，再向
/live/{org}/{site}/main/*
发送POST请求
清除全部缓存向
/cache/{org}/{site}/main/*
发送POST请求
部署代码变更向
/code/{owner}/{repo}/main
发送POST请求

Troubleshooting

故障排查

IssueSolution
401 UnauthorizedToken expired - login again
403 ForbiddenInsufficient permissions - check role
404 Not FoundCheck org/site/path spelling
429 Rate LimitedWait and retry
Cache not clearingTry with 
forceUpdate: true
Code not syncingManual sync: POST to 
/code/{owner}/{repo}/main
问题解决方案
401 Unauthorized令牌过期——重新登录
403 Forbidden权限不足——检查角色
404 Not Found检查组织/站点/路径拼写
429 Rate Limited等待后重试
缓存未清除尝试添加
forceUpdate: true
参数
代码未同步手动同步：向
/code/{owner}/{repo}/main
发送POST请求

Resources

资源

ResourceURL
Admin API Docshttps://www.aem.live/docs/admin.html
Config Servicehttps://www.aem.live/docs/config-service-setup
undefined
资源URL
Admin API文档https://www.aem.live/docs/admin.html
Config Servicehttps://www.aem.live/docs/config-service-setup
undefined

Phase 3: Customize for Project

阶段3：针对项目定制内容

3.1 Fill in Project-Specific Values

3.1 填充项目特定值

Replace all placeholders:
  • {org}
    → actual organization from Config Service API
  • {site}
    → actual site name(s)
  • {owner}
    → code owner from Config Service (GitHub org or Cloud Manager program)
  • {repo}
    → code repo from Config Service
替换所有占位符：
  • {org}
    → 从Config Service API获取的实际组织名称
  • {site}
    → 实际站点名称
  • {owner}
    → 从Config Service获取的代码所有者（GitHub组织或Cloud Manager项目）
  • {repo}
    → 从Config Service获取的代码仓库

3.2 Add Multi-Site Details (if repoless)

3.2 添加多站点详情（如果是无仓库设置）

If project has multiple sites, add a section listing all sites with their:
  • Site name
  • Preview URL
  • Live URL
  • Content source
如果项目包含多个站点，添加一个部分列出所有站点的：
  • 站点名称
  • 预览环境URL
  • 生产环境URL
  • 内容源

3.3 Document Project-Specific Configurations

3.3 记录项目特定配置

Check for and document:
  • Custom headers (
    /config/{org}/sites/{site}/headers.json
    )
  • CDN configuration
  • Any project-specific admin procedures
检查并记录：
  • 自定义头信息（
    /config/{org}/sites/{site}/headers.json
    ）
  • CDN配置
  • 任何项目特定的管理员流程

Phase 4: Convert to Professional PDF

阶段4：转换为专业PDF

4.1 Generate PDF (MANDATORY)

4.1 生成PDF（必须执行）

THIS STEP IS NOT OPTIONAL. YOU MUST GENERATE THE PDF NOW.
  1. Save markdown to: 
    project-guides/ADMIN-GUIDE.md
    • File MUST start with YAML frontmatter:
      yaml
      ---
title: "[Project Name] - Admin Guide"
date: "[Full Date - e.g., February 17, 2026]"
---
    • Date format: Always use full date with day, month, and year (e.g., "February 17, 2026"), NOT just month and year
  2. IMMEDIATELY after saving the markdown, invoke the PDF conversion skill:
    Skill({ skill: "project-management:whitepaper", args: "project-guides/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })
  3. Wait for PDF generation to complete (whitepaper skill auto-cleans source files)
DO NOT:
  • Skip the PDF conversion step
  • Tell user "PDF will be generated later" — generate it NOW
此步骤为必填项。必须立即生成PDF。
  1. 将Markdown保存至：
    project-guides/ADMIN-GUIDE.md
    • 文件必须以YAML前置内容开头：
      yaml
      ---
title: "[项目名称] - 管理员指南"
date: "[完整日期 - 例如：2026年2月17日]"
---
    • 日期格式： 始终使用包含日、月、年的完整日期（例如"2026年2月17日"），请勿仅使用月和年
  2. 保存Markdown后立即调用PDF转换Skill：
    Skill({ skill: "project-management:whitepaper", args: "project-guides/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })
  3. 等待PDF生成完成（whitepaper Skill会自动清理源文件）
请勿：
  • 跳过PDF转换步骤
  • 告知用户"PDF将稍后生成"——立即生成

4.2 Deliver to User

4.2 交付给用户

After PDF is generated, inform the user:
"✓ Admin guide complete: project-guides/ADMIN-GUIDE.pdf"
PDF生成完成后，告知用户：
"✓ 管理员指南已完成：project-guides/ADMIN-GUIDE.pdf"

Output

输出

FINAL OUTPUT: 
project-guides/ADMIN-GUIDE.pdf
All source files (.md, .html, .plain.html) are deleted after PDF generation. Only the PDF remains.
Location: 
project-guides/
folder
最终输出： 
project-guides/ADMIN-GUIDE.pdf
PDF生成后，所有源文件（.md、.html、.plain.html）将被删除。仅保留PDF。
位置： 
project-guides/
文件夹

Success Criteria

成功标准

Data Source Validation (CRITICAL):
  • Config Service API was called (
    https://admin.hlx.page/config/{ORG}/sites.json
    )
  • Site list came from API response, NOT from fstab.yaml or codebase analysis
  • Code repo info came from site config API, NOT from git remote
Content Validation:
  • All org/site values filled from Config Service API
  • Login URL correct
  • All API endpoints have correct org/site
  • Multi-site documented (if applicable)
  • Common tasks listed with correct paths
Output Validation:
  • PDF generated successfully
  • All source files cleaned up (only PDF remains)
数据源验证（关键）：
  • 已调用Config Service API（
    https://admin.hlx.page/config/{ORG}/sites.json
    ）
  • 站点列表来自API响应，而非fstab.yaml或代码库分析
  • 代码仓库信息来自站点配置API，而非git远程仓库
内容验证：
  • 所有组织/站点值均从Config Service API填充
  • 登录URL正确
  • 所有API端点具有正确的组织/站点信息
  • 已记录多站点信息（如适用）
  • 常见任务列出了正确的路径
输出验证：
  • PDF生成成功
  • 所有源文件已清理（仅保留PDF）

Tips

提示

  1. Always use Config Service API - org/site/code repo may differ from what's in the local git remote
  2. Test login URL - Verify the login URL works before documenting
  3. List all sites - For repoless setups, document every site
  4. Include examples - Show actual paths from the project
  1. 始终使用Config Service API——组织/站点/代码仓库可能与本地git远程仓库中的信息不同
  2. 测试登录URL——记录前验证登录URL是否可用
  3. 列出所有站点——对于无仓库设置，记录每个站点
  4. 包含示例——显示项目中的实际路径