admin

项目交接 — 管理员指南

为接手 AEM Edge Delivery Services 项目的管理员生成完整文档。提供完整的管理员指南，涵盖 Config Service 设置、权限、Admin API 操作和故障排查。

何时使用此技能

• 将项目移交给客户管理员
• 记录项目的管理流程
• 创建运维手册
• “生成管理员指南”
• “管理员文档”
• “管理员交接”

---

步骤 0：导航至项目根目录并验证 Edge Delivery Services 项目（有条件执行）

如果设置了 allGuides 标记，则跳过此步骤（协调程序已完成验证和导航）。

重要：如果未跳过此步骤，则必须执行 cd 命令。不要使用绝对路径——请实际切换目录。

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
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 不存在，请回复：

“此技能适用于 AEM Edge Delivery Services 项目。当前目录似乎不是 Edge Delivery Services 项目（未找到 scripts/aem.js）。

请导航至 Edge Delivery Services 项目，然后重试。”

如果检查失败，请停止。否则继续——你现在位于项目根目录。

---

执行检查清单

- [ ] Phase 1: Gather Project Context
- [ ] Phase 2: Generate Admin Guide Content
- [ ] Phase 3: Customize for Project
- [ ] Phase 4: Generate Professional PDF

---

沟通指南

• 在任何生成的文档或聊天回复中，绝不要将 Edge Delivery Services 简写为“EDS”
• 始终使用全称“Edge Delivery Services”或“AEM Edge Delivery Services”
• 这适用于所有输出文件（PDF、HTML、Markdown）以及与用户的所有沟通

---

⚠️ 关键路径要求

必须将文件保存到以下确切路径：

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

---

输出格式

必须输出： project-guides/ADMIN-GUIDE.pdf

严格禁止：

• ❌ 不要读取或分析 fstab.yaml——大多数项目中都不存在此文件，而且它不会显示所有站点
• ❌ 不要创建 .plain.html 文件
• ❌ 不要使用 convert_markdown_to_html 工具——它会将完整指南转换为 HTML，并显示原始 frontmatter，这不是我们想要的结果
• ❌ 不要告诉用户“手动将 Markdown 转换为 PDF”
• ❌ 不要将 Markdown 保存到根目录或 project-guides/ 以外的任何路径
• ❌ 不要说“稍后”或“会在会话结束时”生成 PDF——现在就生成

HTML 输出必须是简短的摘要页面（使用 Write 工具创建），包含：

• 标题和简短说明
• “内容一览”项目符号列表
• PDF 下载链接 而不是转换为 HTML 的完整指南内容。

必须遵循的工作流程：

1. 运行 mkdir -p project-guides，确保目录存在
2. 生成包含 YAML frontmatter（标题、日期）的 Markdown 内容
3. 保存到 project-guides/ADMIN-GUIDE.md（确切路径，不得例外）
4. 立即调用 PDF 转换（见阶段 4.1）
5. 清理所有源文件（仅保留 PDF）
6. 最终输出：project-guides/ADMIN-GUIDE.pdf

---

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

每次运行此技能时——无论是用户直接触发（例如“生成管理员指南”），还是通过交接流程触发——都必须先获取 Config Service 组织名称，然后才能进行其他操作。不要跳过此阶段。

0.1 检查已保存的组织名称

# Check if org name is already saved
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"

0.2 提示词：组织名称（未保存时）

如果未保存组织名称，你必须暂停并直接询问用户：

“你的 Config Service 组织名称是什么？它是 Edge Delivery Services URL 中的 {org} 部分（例如：https://main--site--{org}.aem.page）。组织名称可能与 GitHub 组织不同。”

重要规则：

• 不要使用带预定义选项的 AskUserQuestion——请以纯文本形式提问
• 组织名称为必填项——不要提供“跳过”选项
• 等待用户输入组织名称后再继续
• 如果用户提供的组织名称无效，请再次询问

0.3 保存组织名称

获取组织名称后（从已保存的配置或用户输入中获取），请保存，以便日后使用：

# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains project config)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# 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

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

---

阶段 0.5：使用 Adobe IMS 进行身份验证

获取组织名称后，进行身份验证以获取 IMS 令牌。

0.5.1 检查现有身份验证令牌

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.imsToken && t.imsTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.imsToken);
    }
  } catch (e) {}
")
IMS_EXPIRY=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(String(t.imsTokenExpiry || 0));
  } catch (e) { process.stdout.write('0'); }
")
NOW=$(date +%s)

if [ -n "$IMS_TOKEN" ] && [ "$IMS_EXPIRY" -gt "$((NOW + 60))" ]; then
  echo "Token valid (expires in $((IMS_EXPIRY - NOW)) seconds)"
else
  echo "Token missing or expired. Need to authenticate."
fi

0.5.2 进行身份验证（如果没有有效令牌）

如果不存在有效令牌，请调用身份验证技能：

Skill({ skill: "project-management:auth" })

此操作将：

1. 打开浏览器以登录 Adobe ID
2. 自动获取 IMS OAuth 令牌
3. 将令牌保存到 ~/.aem/ims-token.json（用户级别，在各项目之间共享）
4. 完成后自动关闭浏览器

0.5.3 验证身份验证

身份验证技能完成后，验证令牌是否有效：

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.imsToken || '');
  } catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# Test with authenticated endpoint
curl -s -w "%{http_code}" -o /dev/null -H "Authorization: Bearer ${IMS_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json"

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

---

阶段 1：收集项目上下文

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

⚠️ 必须使用的数据源——不允许使用其他数据源

你必须调用 Config Service API。这是获取站点信息的唯一可接受数据源。

❌ 禁止采用的方法（会导致结果不正确）：

• 分析 fstab.yaml——在无仓库设置中不会显示所有站点
• 读取 README.md——内容可能已过时或不完整
• 根据代码库结构推断——会遗漏 CDN 配置和其他站点
• 使用 git 远程 URL——组织名称可能与 Config Service 组织不同
• 根据项目文件夹名称做出假设

✅ 必须执行并保存响应：

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# 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

📁 必须生成的文件： .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/

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

然后获取各站点的配置，以了解代码和内容详情：

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.imsToken || '');
  } catch (e) {}
")
curl -s -H "Authorization: Bearer ${IMS_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.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 构建上下文

从 1.1 中创建的文件读取：

cat .claude-plugin/sites-config.json

解析 JSON 以提取站点名称，然后获取每个站点的配置以查找代码仓库：

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

使用这些 API 响应构建上下文：站点名称、代码仓库（owner/repo）、预览和线上 URL。如果站点配置包含内容源（例如 content.da.live 路径），请将其记录在 Sites 表格中。

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}/

---

阶段 2：生成管理员指南

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

按照以下结构生成管理员交接文档：

# [Project Name] - Admin Guide

Complete administration guide for managing this Edge Delivery Services project.

## Quick Reference

### URLs

| Purpose | URL |
|---------|-----|
| **Login** | https://admin.hlx.page/login/{org}/{site} |
| **Config Service** | https://admin.hlx.page/config/{org}/ |
| **Preview** | https://main--{site}--{org}.aem.page/ |
| **Live** | https://main--{site}--{org}.aem.live/ |

### Sites (if multi-site/repoless)

| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {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/ |

## 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

### Logout

```bash
curl -X POST \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/logout/{org}/{site}/main"

用户管理

查看当前访问权限

curl -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access.json"

添加用户

角色	命令
管理员	POST /config/{org}/sites/{site}/access/admin.json with {"users": ["email"]}
作者	POST /config/{org}/sites/{site}/access/author.json with {"users": ["email"]}

移除用户

curl -X DELETE \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"

内容操作

预览

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

发布

操作	端点
单页	POST /live/{org}/{site}/main/{path}
批量发布	POST /live/{org}/{site}/main/*
取消发布	DELETE /live/{org}/{site}/main/{path}

缓存

操作	端点
清除路径缓存	POST /cache/{org}/{site}/main/{path}
清除所有缓存	POST /cache/{org}/{site}/main/*

代码操作

同步代码

curl -X POST \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/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 请求

故障排除

问题	解决方案
401 未授权	令牌已过期——请重新登录
403 禁止访问	权限不足——请检查角色
404 未找到	请检查 org/site/path 的拼写
429 请求过多	等待后重试
缓存未清除	尝试使用 forceUpdate: true
代码未同步	手动同步：向 /code/{owner}/{repo}/main 发送 POST 请求

---

资源

资源	URL
管理 API 文档	https://www.aem.live/docs/admin.html
配置服务	https://www.aem.live/docs/config-service-setup

## Phase 3: Customize for Project

### 3.1 Fill in Project-Specific Values

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

### 3.2 Add Multi-Site Details (if repoless)

If project has multiple sites, add a section listing all sites with their:
- Site name
- Preview URL
- Live URL
- Content source

### 3.3 Document Project-Specific Configurations

Check for and document:
- Custom headers (`/config/{org}/sites/{site}/headers.json`)
- CDN configuration
- Any project-specific admin procedures

---

## Phase 4: Convert to Professional PDF

### 4.1 Generate PDF (MANDATORY)

**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

### 4.2 Deliver to User

After PDF is generated, inform the user:

"✓ 管理指南已完成：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

---

## 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)

---

## 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