handover-admin

项目交接——管理员指南

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

---

步骤 0：导航到项目根目录（有条件）

如果 .claude-plugin/project-config.json 中设置了 allGuides，则跳过（编排器已完成验证）。

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
  cd "$(git rev-parse --show-toplevel)"
  ls scripts/aem.js
fi

如果 scripts/aem.js 不存在，请告知用户此技能需要 AEM Edge Delivery Services 项目，然后停止。

后续所有步骤均在项目根目录下执行。指南会创建在 project-guides/ 中。

---

执行检查清单

- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Fetch project context from Config Service API
- [ ] Phase 2: Generate admin guide content
- [ ] Phase 3: Customize for project
- [ ] Phase 4: Convert to PDF

---

阶段 0：获取组织名称并进行身份验证

0.1 检查是否已保存组织名称

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 保存组织名称

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

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.4 检查身份验证令牌

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.authToken);
    }
  } catch (e) {}
")
echo "auth=${AUTH_TOKEN:+set}"

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

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

0.5 验证身份验证状态

AUTH_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.authToken || '');
  } catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
STATUS=$(curl -s -w "%{http_code}" -o /dev/null \
  -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json")
echo "Auth check: HTTP $STATUS"

如果状态码不是 200，请重新运行身份验证技能，然后再继续。

---

阶段 1：收集项目上下文

1.1 通过 Config Service API 获取站点

Config Service API 是获取站点信息的唯一可靠来源。不要使用 fstab.yaml、README 或 git 远程仓库 URL。

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
AUTH_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.authToken || '');
  } catch (e) {}
")

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

node -e "
  const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
  const j = JSON.parse(d);
  if (!j.sites || !j.sites.length) {
    console.error('No sites returned — verify org name and re-authenticate if needed');
    process.exit(1);
  }
  console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"

如果验证失败，请确认组织名称是否正确，重新进行身份验证，然后重试。

1.2 获取各站点配置

为每个站点获取其配置：

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

提取：

• code.owner / code.repo——GitHub 仓库
• content.source.url——内容挂载路径
• content.source.type——内容来源类型（markup、onedrive、google）

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

构建上下文：

Organization: {org}
Site(s): {site1}, {site2}, ...
Setup: {repoless | standard}
Code Repo: {owner}/{repo}
Preview: https://main--{site}--{org}.aem.page/
Live: https://main--{site}--{org}.aem.live/
Login: https://admin.hlx.page/login/{org}/{site}
Config: https://admin.hlx.page/config/{org}/

---

阶段 2：生成管理员指南

输出文件：project-guides/ADMIN-GUIDE.md（请先运行 mkdir -p project-guides）。

---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

# [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 | Preview | Live |
|------|----------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

## Authentication

### Login

1. Open: https://admin.hlx.page/login/{org}/{site}
2. Sign in with your credentials

### Logout

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

用户管理

查看当前访问权限

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

添加用户

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

移除用户

curl -X DELETE -H "x-auth-token: $AUTH_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 "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/code/{owner}/{repo}/main"

常见任务

任务	步骤
添加新管理员	向 /config/{org}/sites/{site}/access/admin.json 发送 POST 请求
重新发布站点	先调用 POST /preview/{org}/{site}/main/*，再调用 /live/{org}/{site}/main/*
清除所有缓存	向 /cache/{org}/{site}/main/* 发送 POST 请求
部署代码更改	向 /code/{owner}/{repo}/main 发送 POST 请求

故障排查

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

资源

资源	URL
管理员 API 文档	https://www.aem.live/docs/admin.html
Config Service	https://www.aem.live/docs/config-service-setup

---

## Phase 3: Customize for Project

Replace all placeholders with values from the Config Service API:
- `{org}` → actual organization name
- `{site}` → actual site name(s)
- `{owner}` / `{repo}` → code owner and repo from site config

If multi-site (repoless), add a section listing all sites with their preview URL, live URL, and content source.

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

---

## Phase 4: Convert to Professional PDF

Save the completed markdown to `project-guides/ADMIN-GUIDE.md`. The file must start with YAML frontmatter:

```yaml
---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

立即调用 PDF 转换：

Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })

白皮书技能会自动清理源文件。最终输出：project-guides/ADMIN-GUIDE.pdf。

告知用户：“管理员指南已完成：project-guides/ADMIN-GUIDE.pdf”

---

成功标准

类别	检查项
数据源	已调用 Config Service API（https://admin.hlx.page/config/{ORG}/sites.json）
数据源	网站列表来自 API 响应，而非 fstab.yaml 或代码库分析
数据源	代码仓库信息来自网站配置 API，而非 git remote
内容	所有组织／网站值均从 Config Service API 填写
内容	登录 URL 正确
内容	所有 API 端点中的组织／网站信息正确
内容	已记录多站点信息（如适用）
内容	列出了常见任务及正确路径
输出	已在 project-guides/ADMIN-GUIDE.pdf 生成 PDF
输出	已清理所有源文件（仅保留 PDF）

---

**沟通要求：**绝不使用“EDS”这一缩写；所有输出和文档中始终写作“Edge Delivery Services”或“AEM Edge Delivery Services”。