handover-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操作及故障排查的完整管理员指南。

Step 0: Navigate to Project Root (CONDITIONAL)

步骤0：导航至项目根目录（可选）

Skip if

allGuides

is set in

.claude-plugin/project-config.json

(orchestrator already validated).

bash

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

does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.

All subsequent steps operate from project root. Guides are created at

project-guides/

如果

.claude-plugin/project-config.json

中已设置

allGuides

（编排器已验证），则跳过此步骤。

bash

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/

目录中。

Execution Checklist

执行清单

markdown

- [ ] 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

markdown

- [ ] 阶段0：获取组织名称并完成认证
- [ ] 阶段1：从Config Service API获取项目上下文
- [ ] 阶段2：生成管理员指南内容
- [ ] 阶段3：针对项目定制内容
- [ ] 阶段4：转换为PDF格式

Phase 0: Get Organization Name and Authenticate

阶段0：获取组织名称并完成认证

0.1 Check for Saved Organization

0.1 检查已保存的组织信息

bash

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) {}
"

bash

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 Prompt for Organization Name (If Not Saved)

0.2 提示用户输入组织名称（未保存时）

If no org name is found, ask the user:

"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."

Ask as a plain text question — not

AskUserQuestion

with options. Organization name is mandatory; do not offer a skip option.

如果未找到组织名称，请询问用户：

"请提供您的Config Service组织名称。这是您Edge Delivery Services URL中的
{org}
部分（例如：
https://main--site--{org}.aem.page
）。组织名称可能与您的GitHub组织名称不同。"

以纯文本问题形式询问，不要使用带选项的

AskUserQuestion

。组织名称为必填项，不提供跳过选项。

0.3 Save Organization Name

0.3 保存组织名称

bash

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

Replace

{ORG_NAME}

with the actual organization name.

bash

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 Check Auth Token

0.4 检查认证令牌

bash

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

If no valid token exists, invoke the auth skill:

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

bash

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 Verify Authentication

0.5 验证认证状态

bash

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"

If not 200, re-run the auth skill before proceeding.

bash

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，请重新运行认证技能后再继续。

Phase 1: Gather Project Context

阶段1：收集项目上下文

1.1 Fetch Sites via Config Service API

1.1 通过Config Service API获取站点信息

The Config Service API is the only reliable source for site information. Do not use

fstab.yaml

, README, or git remote URLs.

bash

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(', '));
"

If validation fails, verify the org name is correct, re-authenticate, and retry.

Config Service API是获取站点信息的唯一可靠来源。请勿使用

fstab.yaml

、README或Git远程URL。

bash

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 Fetch Per-Site Config

1.2 获取每个站点的配置

For each site, fetch its config:

bash

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

Extract:

```
code.owner
```
/
```
code.repo
```
— GitHub repository
```
content.source.url
```
— Content mountpath
```
content.source.type
```
— Content source type (markup, onedrive, google)

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

Build context:

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

针对每个站点，获取其配置：

bash

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）

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

构建上下文信息：

组织: {org}
站点: {site1}, {site2}, ...
配置类型: {无仓库 | 标准}
代码仓库: {owner}/{repo}
预览地址: https://main--{site}--{org}.aem.page/
正式环境地址: https://main--{site}--{org}.aem.live/
登录地址: https://admin.hlx.page/login/{org}/{site}
配置地址: https://admin.hlx.page/config/{org}/

Phase 2: Generate Admin Guide

阶段2：生成管理员指南

Output file:

project-guides/ADMIN-GUIDE.md

(run

mkdir -p project-guides

first).

markdown

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

输出文件：

project-guides/ADMIN-GUIDE.md

（先执行

mkdir -p project-guides

创建目录）。

markdown

---
title: "[项目名称] - 管理员指南"
date: "[完整日期 — 例如：2026年2月17日]"
---

[Project Name] - Admin Guide

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

Complete administration guide for managing this Edge Delivery Services project.

管理此Edge Delivery Services项目的完整管理指南。

Quick Reference

快速参考

URLs

URL地址

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/

用途	URL
登录	https://admin.hlx.page/login/{org}/{site}
Config Service	https://admin.hlx.page/config/{org}/
预览环境	https://main--{site}--{org}.aem.page/
正式环境	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/

站点	内容源	预览地址	正式地址
{site1}	[来自站点配置]	https://main--{site1}--{org}.aem.page/	https://main--{site1}--{org}.aem.live/

Authentication

认证管理

Login

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

添加用户

Role	Command
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

内容操作

Operation	Endpoint
Preview page	`POST /preview/{org}/{site}/main/{path}`
Bulk preview	`POST /preview/{org}/{site}/main/*`
Publish page	`POST /live/{org}/{site}/main/{path}`
Bulk publish	`POST /live/{org}/{site}/main/*`
Unpublish	`DELETE /live/{org}/{site}/main/{path}`
Purge cache	`POST /cache/{org}/{site}/main/{path}`
Purge all	`POST /cache/{org}/{site}/main/*`

操作	端点
预览页面	`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/*`

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

常见任务

Task	Steps
Add new admin	POST to `/config/{org}/sites/{site}/access/admin.json`
Republish site	POST `/preview/{org}/{site}/main/` then `/live/{org}/{site}/main/`
Clear all cache	POST to `/cache/{org}/{site}/main/*`
Deploy code changes	POST to `/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请求

Troubleshooting

故障排查

Issue	Solution
401 Unauthorized	Token expired — login again
403 Forbidden	Insufficient permissions — check role
404 Not Found	Check org/site/path spelling
429 Rate Limited	Wait and retry
Cache not clearing	Try with `forceUpdate: true`
Code not syncing	Manual sync: POST to `/code/{owner}/{repo}/main`

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

Resources

资源链接

Resource	URL
Admin API Docs	https://www.aem.live/docs/admin.html
Config Service	https://www.aem.live/docs/config-service-setup

---

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

---

Phase 3: Customize for Project

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

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

将所有占位符替换为从Config Service API获取的实际值：

```
{org}
```
→ 实际组织名称
```
{site}
```
→ 实际站点名称（多个站点时需对应替换）
```
{owner}
```
/
```
{repo}
```
→ 站点配置中的代码所有者和仓库名称

如果是多站点（无仓库）配置，添加一个章节列出所有站点的预览地址、正式地址和内容源。

检查并记录项目特定配置：

自定义请求头：
```
/config/{org}/sites/{site}/headers.json
```
CDN配置
任何项目特定的管理员流程

Phase 4: Convert to Professional PDF

阶段4：转换为专业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]"
---

Immediately invoke PDF conversion:

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

The whitepaper skill auto-cleans source files. Final output:

project-guides/ADMIN-GUIDE.pdf

Inform the user: "Admin guide complete: project-guides/ADMIN-GUIDE.pdf"

将完成的Markdown文件保存到

project-guides/ADMIN-GUIDE.md

。文件必须以YAML前置元数据开头：

yaml

---
title: "[项目名称] - 管理员指南"
date: "[完整日期 — 例如：2026年2月17日]"
---

立即调用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"

Success Criteria

成功标准

Category	Check
Data Source	Config Service API called ( `https://admin.hlx.page/config/{ORG}/sites.json` )
Data Source	Site list from API response, not fstab.yaml or codebase analysis
Data Source	Code repo info from site config API, not git remote
Content	All org/site values filled from Config Service API
Content	Login URL correct
Content	All API endpoints have correct org/site
Content	Multi-site documented (if applicable)
Content	Common tasks listed with correct paths
Output	PDF generated at `project-guides/ADMIN-GUIDE.pdf`
Output	All source files cleaned up (only PDF remains)

Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.

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

注意事项： 请勿使用缩写"EDS"，在所有输出和文档中请始终使用"Edge Delivery Services"或"AEM Edge Delivery Services"。