ops

Edge Delivery Services 管理操作

使用自然语言命令，对 AEM Edge Delivery Services 项目执行管理操作。

快速参考

类别	示例
内容	预览 /path、发布 /path、取消发布 /path、查看状态 /path
缓存	清除缓存 /path、强制清除缓存
代码	同步代码、部署代码
索引	重新索引 /path、从索引中移除
站点地图	生成站点地图
快照	创建快照 X、发布快照 X、批准快照 X
日志	显示日志、显示最近一小时的日志
用户	将 user@email 添加为作者/发布者/开发者、移除管理员 user@email、我是谁
作业	列出作业、查看作业状态 X、停止作业 X
站点	列出站点、切换到 site-X、使用分支 feature-X
配置	显示组织配置、显示站点配置、更新 robots.txt
密钥	列出密钥、创建密钥、删除密钥
API 密钥	列出 API 密钥、创建 API 密钥、撤销 API 密钥
令牌	列出令牌、创建令牌、撤销令牌
配置文件	显示配置文件配置、创建配置文件、删除配置文件
索引配置	显示索引配置、更新索引配置（query.yaml）
站点地图配置	显示站点地图配置、更新站点地图配置（sitemap.yaml）
版本控制	列出版本、恢复版本、回滚配置
页面	列出页面、列出所有页面、显示已编入索引的页面
DA（文档创作）	da list、da source /path、da copy、da move、da delete、da config、da update config、da versions、da create version、da upload media、da auth

---

沟通指南

• **绝不要使用“EDS”**作为 Edge Delivery Services 的缩写
• 始终使用全称“Edge Delivery Services”或“AEM Edge Delivery Services”
• 操作失败时，显示清晰且可执行的错误消息
• 执行破坏性操作前进行确认——参见 resources/security.md

---

欢迎消息

如果用户调用此技能时未指定具体命令（例如，只输入 /ops 或“帮我处理运维操作”），显示：

Edge Delivery Services Operations

Quick commands to try:
  list pages       - Show all indexed pages
  who am i         - Check your user profile
  list sites       - Show available sites
  show site config - View site configuration
  preview /path    - Preview a content path
  show logs        - View recent activity

For the full command list: type help, /ops help, or what can you do?

---

跨平台说明

Shell 命令使用兼容 POSIX 的语法（适用于 macOS/Linux）。在 Windows 上，可直接使用 Git Bash 或 WSL。Agent 应根据用户的环境调整语法。

---

意图路由器

步骤 0：获取组织和站点（必须首先执行）

检查 ~/.aem/ops-config.json 中是否已存储组织和站点：

eval $(node -e "
  const fs = require('fs');
  try {
    const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
    console.log('ORG=' + JSON.stringify(c.org || ''));
    console.log('SITE=' + JSON.stringify(c.site || ''));
  } catch(e) {
    console.log('ORG='); console.log('SITE=');
  }
")
echo "org=${ORG:-NOT SET} site=${SITE:-NOT SET}"

如果 ORG 和 SITE 均已设置，请向用户确认：

“上次使用的是：org={ORG}、site={SITE}。要继续使用这些值吗？如果不想继续，请提供其他站点 URL（例如，https://main--mysite--myorg.aem.page/）。”

• 如果用户确认 → 继续
• 如果用户提供 URL → 从中解析组织和站点，并保存新值

如果 ORG 或 SITE 为空，请询问：

“请输入要执行运维操作的站点预览/线上 URL（例如，https://main--mysite--myorg.aem.page/）。”

从 URL 中解析组织和站点：

URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
  HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
  ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
  SITE=$(echo "$HOST_PART" | awk -F'--' '{print $(NF-1)}')
  echo "Parsed from URL: org=$ORG site=$SITE"
fi

如果用户提供的不是有效的 .aem.page 或 .aem.live URL，请再次询问。

保存组织和站点：

mkdir -p "${HOME}/.aem"
node -e "
  const fs = require('fs');
  const p = process.env.HOME + '/.aem/ops-config.json';
  let c = {};
  try { c = JSON.parse(fs.readFileSync(p, 'utf8')); } catch(e) {}
  c.org = '${ORG}';
  c.site = '${SITE}';
  fs.writeFileSync(p, JSON.stringify(c, null, 2));
"

组织和站点只能使用 ~/.aem/ops-config.json 中的值或用户直接输入的值。绝不要根据 git remote、fstab.yaml 或文件夹/仓库名称推断。

在确认组织和站点之前，不要继续。

步骤 1：身份验证（必须执行）

在进行任何 API 调用之前，检查是否存在身份验证令牌：

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

如果 AUTH_TOKEN 为空，请先调用身份验证技能，再继续：

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

所有 admin.hlx.page API 调用都使用 -H "x-auth-token: ${AUTH_TOKEN}" 标头。

对于敏感端点和破坏性操作，请先阅读 resources/security.md 和 resources/sensitive.md。

步骤 2：加载完整配置并验证角色

eval $(node -e "
  const fs = require('fs');
  try {
    const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
    console.log('ORG=' + JSON.stringify(c.org || ''));
    console.log('SITE=' + JSON.stringify(c.site || ''));
    console.log('REF=' + JSON.stringify(c.ref || 'main'));
  } catch(e) {
    console.log('ORG='); console.log('SITE='); console.log('REF=main');
  }
")
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) {}
")
echo "Config: org=$ORG site=$SITE ref=$REF auth=${AUTH_TOKEN:+set}"

获取用户资料以验证身份验证状态并记录用户身份：

PROFILE_RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/profile")
HTTP_CODE=$(echo "$PROFILE_RESPONSE" | tail -n1)
PROFILE=$(echo "$PROFILE_RESPONSE" | sed '$d')

if [ "$HTTP_CODE" = "401" ]; then
  echo "Auth token expired. Need to re-authenticate..."
  echo "REAUTH_REQUIRED"
  exit 1
elif [ "$HTTP_CODE" != "200" ]; then
  echo "Failed to fetch profile (HTTP $HTTP_CODE). Check network/API status."
  exit 1
fi

eval $(echo "$PROFILE" | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try {
    const p = JSON.parse(d).profile || {};
    console.log('USER_EMAIL=' + JSON.stringify(p.email || ''));
    console.log('USER_NAME=' + JSON.stringify(p.name || ''));
  } catch(e) { console.log('USER_EMAIL=\"\"'); console.log('USER_NAME=\"\"'); }
")

echo "Authenticated as: $USER_EMAIL ($USER_NAME)"

如果返回 REAUTH_REQUIRED，请调用身份验证技能并重试。

要确定用户在站点上的角色，请检查站点访问配置：

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

如果操作返回 403，请告知用户所需的角色：

权限	所需角色
预览	basic_author、author、publish 或 admin
发布到线上	basic_publish、publish 或 admin
取消发布	publish 或 admin
代码同步	develop 或 admin
配置读取	config、config_admin 或 admin
配置写入	config_admin 或 admin
快照管理	author、publish 或 admin

将 email 保存到 ~/.aem/ops-config.json，以供今后使用。

如果缺少站点或其他值，请读取 resources/config.md。

步骤 3：根据意图路由

用户意图	资源模块
预览、发布、取消发布、状态、删除预览	resources/content.md
缓存、清除缓存、清空缓存、使缓存失效	resources/cache.md
同步代码、部署代码、更新代码	resources/code.md
重建索引、索引、从索引中移除、搜索	resources/index.md
站点地图、生成站点地图	resources/sitemap.md
快照、暂存发布、捆绑包	resources/snapshots.md
日志、审计、活动	resources/logs.md
用户、访问、权限、我是谁、添加用户、移除用户	resources/users.md
作业、批量操作、停止作业	resources/jobs.md
站点、分支、切换、列出站点	resources/sites.md
组织配置、站点配置、robots.txt	resources/config-api.md
密钥、创建密钥、删除密钥	resources/secrets.md
API 密钥、apikey、创建密钥、撤销密钥	resources/apikeys.md
令牌、访问令牌	resources/tokens.md
个人资料配置、个人资料设置	resources/profiles.md
索引配置、helix-index、搜索配置	resources/index-config.md
站点地图配置、helix-sitemap、站点地图规则	resources/sitemap-config.md
版本、历史记录、回滚、恢复	resources/versioning.md
页面、列出页面、已编入索引的页面、所有页面	resources/pages.md
da、da 列表、da 来源、da 复制、da 移动、da 删除、da 配置、da 版本	resources/da.md
破坏性操作、需要确认	resources/security.md
敏感端点（电子邮件、凭据、API 密钥）	resources/sensitive.md

步骤 4：读取资源并执行

1. 从 resources/ 读取相应的资源文件
2. 按照该资源中的说明操作
3. 对于配置更新：始终先 GET 当前配置，并在修改前向用户展示
4. 对于代码同步：同步前始终检查 repoless 状态（参见 code.md）
5. 对于破坏性操作：读取 resources/security.md 并遵循确认协议——不得例外（说明操作、解释影响、询问“是/否”，仅在用户回答“是”后执行）
6. 执行 API 调用
7. 按照下方的完成标准处理响应

完成标准

HTTP 响应	含义	必须执行的操作
200/201	成功	显示结果及完整 URL（https://{ref}--{site}--{org}.aem.page{path}）
202	异步作业已启动	报告作业名称；提示用户使用 check job status {jobName} 跟踪进度
204	成功（无响应正文）	确认：“已为 {path} 完成 {action}”
4xx/5xx	错误	原样显示 API 错误，然后根据 resources/errors.md 建议修复方法

报告成功前：

• 对于内容操作：在适用时同时提供预览 URL 和线上 URL
• 对于批量操作：在作业完成前，切勿说“已发布”或“已预览”——应说“作业已启动”
• 对于破坏性操作：确认已移除的内容以及仍然存在的内容

URL 解析辅助

如果用户提供的是 AEM URL，而不是单独的 org/site/path 值：

# Pattern: https://{ref}--{site}--{org}.aem.page{path}
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
  DOMAIN=$(echo "$URL" | cut -d'/' -f3)
  HOST_PART=$(echo "$DOMAIN" | cut -d'.' -f1)
  REF=$(echo "$HOST_PART" | awk -F'--' '{print $1}')
  ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
  SITE=$(echo "$HOST_PART" | awk -F'--' '{
    r=""; for(i=2;i<NF;i++) r=(r==""?"":r"--")$i; print r
  }')
  URL_PATH=$(echo "$URL" | sed 's|https://[^/]*||')
  URL_PATH=${URL_PATH:-/}
  echo "Parsed from URL: org=$ORG site=$SITE ref=$REF path=$URL_PATH"
fi

示例：uat--hmns-uat-kw--alshaya-axp.aem.page → ref=uat、site=hmns-uat-kw、org=alshaya-axp。

---

前提条件

1. 已接入 Admin Service — 项目必须具有 admin.hlx.page 访问权限
2. 用户拥有账号 — 身份验证所必需（支持联合登录）
3. 用户拥有站点角色 — 角色在站点配置中定义（access.admin.role）。共有八种角色：admin、author、publish、develop、basic_author、basic_publish、config、config_admin。如果用户没有角色，API 将返回 403。
4. 网络访问权限 — 能够访问 admin.hlx.page

---

帮助响应

当用户想要查看命令列表时（触发条件：help、what can you do?、/ops help、list commands）：

Content Operations:
  preview /path          - Update preview
  publish /path          - Publish to live
  unpublish /path        - Remove from live
  status /path           - Check preview/live status

Cache Operations:
  clear cache /path      - Purge CDN cache
  force clear cache      - Force purge

Code Operations:
  sync code              - Deploy latest code

Index Operations:
  reindex /path          - Re-index for search

Sitemap:
  generate sitemap       - Create sitemap.xml

Snapshots:
  create snapshot {name} - Create staged release
  publish snapshot {name}- Publish all in snapshot

Logs:
  show logs              - View recent logs
  show logs last hour    - Filtered by time

Users:
  add user@email as role - Grant access
  remove role user@email - Revoke access
  who am i               - Current user

Jobs:
  list jobs              - Show bulk operations
  stop job {name}        - Cancel job

Sites:
  list sites             - Show all sites
  switch to site-x       - Change active site
  use branch feat-x      - Set branch

Config:
  show org config        - View org settings
  show site config       - View site settings
  update robots.txt      - Modify crawler rules

Secrets:
  list secrets           - Show secrets
  create secret {name}   - Add new secret
  delete secret {name}   - Remove secret

API Keys:
  list API keys          - Show API keys
  create API key {name}  - Generate new key
  revoke API key {id}    - Delete key

Profiles:
  show profile config    - View profile settings
  create profile {id}    - Create profile config
  delete profile {id}    - Remove profile config

Index Config:
  show index config      - View query.yaml
  update index config    - Modify indexing rules

Sitemap Config:
  show sitemap config    - View sitemap.yaml
  update sitemap config  - Modify sitemap rules

Versioning:
  list versions          - Show config history
  restore version {id}   - Rollback to version

Pages:
  list pages             - Show all indexed pages
  list pages /blog       - Filter by path prefix

Document Authoring (DA):
  da auth                - Authenticate with DA
  da list                - List DA organizations
  da list /path          - List files in DA path
  da source /path        - Get file content from DA
  da copy /src to /dest  - Copy file/folder in DA
  da move /src to /dest  - Move/rename in DA
  da delete /path        - Delete from DA
  da upload /path        - Upload content to DA
  da upload media /path  - Upload image/media to DA
  da config              - View DA site config
  da update config       - Update DA site config
  da versions /path      - List file versions
  da create version      - Create labeled version snapshot
  da restore version X   - Restore a previous version
  da preview /path       - Preview DA content
  da publish /path       - Publish DA content