mcpField
H
handover

handover

github.com/adobe文档处理3161.5k 次安装今天更新
代码仓库

关于 handover

handover 是用于生成 Edge Delivery Services 项目交接文档的编排技能，可按需生成作者、开发者和管理员指南，并输出 PDF。

主要功能

  1. 01生成作者、开发者和管理员指南
  2. 02选择单份指南或生成全部三份
  3. 03并行执行全部指南的生成任务
  4. 04在 project-guides 目录输出 PDF

适用场景

  1. 01为团队交接准备项目文档
  2. 02为作者、开发者和管理员编写对应指南

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/adobe/skills --skill handover

安装后在 Claude Code 中输入/handover确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.releaserc.json
CHANGELOG.md
package.json

详细介绍

项目交接文档

为 Edge Delivery Services 项目生成全面的交接文档。统筹为不同受众创建指南。

可用的文档类型

指南受众技能
创作指南内容作者和内容经理handover-author
开发者指南开发人员和技术团队handover-developer
管理员指南站点管理员和运维人员handover-admin

执行流程

步骤 0：导航到项目根目录（必须）
cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js

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

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

步骤 0.5：清理过期配置
rm -f .claude-plugin/project-config.json
步骤 1：询问用户需要哪种文档类型

使用 AskUserQuestion，并且只能包含以下 4 个选项：

AskUserQuestion({
  "questions": [{
    "question": "Which type of handover documentation would you like me to generate?",
    "header": "Guide Type",
    "options": [
      {"label": "All (Recommended)", "description": "Generate all three guides: Authoring, Developer, and Admin"},
      {"label": "Authoring Guide", "description": "For content authors and managers - blocks, templates, publishing"},
      {"label": "Developer Guide", "description": "For developers - codebase, implementations, design tokens"},
      {"label": "Admin Guide", "description": "For site administrators - permissions, API operations, cache"}
    ],
    "multiSelect": false
  }]
})
步骤 1.5：获取组织名称

用户选择指南类型后，在调用任何子技能之前，确保已获取组织名称。

1.5.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) {}
"
1.5.2 从 Git 获取站点名称
SITE=$(basename -s .git $(git remote get-url origin 2>/dev/null) 2>/dev/null)
echo "site=${SITE:-NOT SET}"
1.5.3 提示用户提供组织名称（如果尚未保存）

如果没有已保存的组织名称，请询问用户：

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

你可以提供组织名称，也可以提供预览 URL 或正式环境 URL。”

使用纯文本提问，不要使用带选项的 AskUserQuestion。组织名称为必填项。

如果用户提供了 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}')
  echo "Parsed from URL: org=$ORG"
fi
1.5.4 保存组织名称
mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# Include allGuides flag only when "All (Recommended)" was selected
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
# OR for "All (Recommended)":
echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json

将 {ORG_NAME} 替换为实际的组织名称。仅当用户选择“All (Recommended)”时才包含 "allGuides": true——这会通知子技能跳过步骤 0 的验证。

步骤 1.6：进行身份验证

检查是否存在有效的身份验证令牌：

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

if [ -n "$AUTH_TOKEN" ]; then
  echo "Token valid"
else
  echo "Token missing or expired."
fi

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

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

在此处完成身份验证后，所有并行运行的子技能都可以使用已保存的令牌，无需分别提示用户登录。

步骤 1.7：验证组织名称

完成身份验证后，验证组织名称：

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');
  process.stdout.write(JSON.parse(d).org || '');
")
curl -s -w "\nHTTP: %{http_code}" -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json"

如果 HTTP 状态码为 200：组织名称有效，继续执行步骤 2。

如果状态码不是 200：告知用户组织名称似乎不正确，并请用户提供正确名称。更新 .claude-plugin/project-config.json，然后重试，直到 HTTP 状态码为 200。

步骤 2：调用相应技能
选择操作
全部并行调用全部三个技能（参见步骤 3）
创作指南Skill({ skill: "aem-project-management:handover-author" })
开发者指南Skill({ skill: "aem-project-management:handover-developer" })
管理员指南Skill({ skill: "aem-project-management:handover-admin" })

如果用户只选择一种指南，请直接在主对话中调用技能（不要通过 Agent），以便将权限提示发送给用户。

步骤 3：“全部”选择——并行执行

开始前立即向用户反馈：

"Starting parallel generation of all 3 handover guides:
  Authoring Guide - analyzing blocks, templates, configurations...
  Developer Guide - analyzing code, patterns, architecture...
  Admin Guide - analyzing deployment, security, operations..."

在单条消息中同时启动全部三个 Agent（前台模式）。不要使用 run_in_background: true。告诉每个 Agent 阅读子技能的 SKILL.md 并直接遵循其中的说明——不要让 Agent 调用 Skill 工具。

Agent({
  description: "Generate authoring guide",
  prompt: "You are generating an authoring guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-author/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

Agent({
  description: "Generate developer guide",
  prompt: "You are generating a developer guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-developer/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

Agent({
  description: "Generate admin guide",
  prompt: "You are generating an admin guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-admin/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

将 {PROJECT_ROOT} 替换为实际的项目根目录路径（git rev-parse --show-toplevel 的输出）。

使用以下命令确定 {PLUGIN_ROOT}：

PLUGIN_ROOT=$([ -d ".claude/plugins/aem-project-management" ] && echo ".claude/plugins/aem-project-management" || echo "$CLAUDE_PLUGIN_ROOT")

全部三个任务完成后，报告最终摘要：

"Handover documentation complete:

project-guides/
├── AUTHOR-GUIDE.pdf
├── DEVELOPER-GUIDE.pdf
└── ADMIN-GUIDE.pdf

All PDFs generated. Source files cleaned up."

输出文件

选择输出文件
全部project-guides/AUTHOR-GUIDE.pdf、project-guides/DEVELOPER-GUIDE.pdf、project-guides/ADMIN-GUIDE.pdf
编写指南project-guides/AUTHOR-GUIDE.pdf
开发者指南project-guides/DEVELOPER-GUIDE.pdf
管理员指南project-guides/ADMIN-GUIDE.pdf

每个子技能都会在完成指南后立即生成 PDF。PDF 生成后，所有源文件（.md、.html、.plain.html）都会被清理。

相关技能

  • aem-project-management:handover-author — 作者/内容经理指南
  • aem-project-management:handover-developer — 开发者技术指南
  • aem-project-management:handover-admin — 管理员运维指南
  • aem-project-management:whitepaper — PDF 生成（由每个子技能调用）

评论

支持 Markdown