handover-developer

项目交接 - 开发

为开发人员生成完整的技术指南。分析代码库并编写可执行的文档，帮助开发人员了解、维护和扩展项目。

---

步骤 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: Gather project information
- [ ] Phase 2: Analyze project architecture
- [ ] Phase 3: Document design system
- [ ] Phase 4: Document blocks, models, and templates
- [ ] Phase 5: Generate 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) {}
")

if [ -z "$AUTH_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

如果为 AUTH_REQUIRED，请调用身份验证技能：

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

---

阶段 1：收集项目信息

1.1 获取项目 URL 和代码库

git remote -v | head -1
git branch -a | head -10

提取：代码库所有者、代码库名称、主分支名称。

1.2 检查配置方式

ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"

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

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

获取每个站点的配置：

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

提取：code.owner、code.repo、content.source.url、content.source.type。

多个站点 = 无代码库配置。单个站点 = 标准配置。请记录此信息——它会影响 aem up 本地开发说明。

1.4 检查 Node.js 要求

cat .nvmrc 2>/dev/null || cat package.json | grep -A2 '"engines"'

---

阶段 2：分析项目架构

读取站点配置：

cat .claude-plugin/sites-config.json

2.1 梳理项目结构

ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "No templates folder"

2.2 区分样板文件与自定义文件

仅记录实际经过自定义的文件。

git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5

Git 历史	操作
只有“Initial commit”	跳过 — 默认样板文件，从未修改过
只有 aem-aemy[bot] 提交	跳过 — 自动生成
团队成员进行了多次提交	记录 — 已自定义

2.3 分析 scripts/aem.js（核心库）

grep -E "^export" scripts/aem.js

记录项目从 aem.js 导入的函数（例如 sampleRUM、loadHeader、loadFooter、decorateBlock、loadBlock、loadCSS）。

2.4 分析 scripts/scripts.js

grep -E "^import|^export|^function|^async function|buildAutoBlocks|loadTemplate|getLanguage|getSiteRoot|decorateMain|loadEager|loadLazy|loadDelayed" scripts/scripts.js

记录：

模式	记录内容
import 语句	从 aem.js 和 utils.js 导入的内容
loadEager / loadLazy	在 E-L-D 阶段添加的任何自定义逻辑
buildAutoBlocks	自动构建区块的逻辑
loadTemplate / 模板处理	模板系统
getLanguage / 语言检测	多语言配置
getSiteRoot / 站点检测	多站点配置
外部脚本加载	加载阶段 — 如果在 eager 阶段，需标记为性能风险

2.5 分析 scripts/delayed.js

grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js

记录分析集成、营销工具和性能监控。确认此文件中没有渲染关键代码。

2.6 检查实用函数

grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "No utils.js"
ls scripts/*.js
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null

记录共享实用函数，以及导入这些函数的区块和脚本。

2.7 检查外部依赖

grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/null

---

阶段 3：记录设计系统

3.1 提取 CSS 自定义属性

grep -E "^\s*--" styles/styles.css

按以下类别整理：字体排版、颜色、间距、布局。

3.2 记录字体设置

grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null

记录：字体文件及格式、字体系列名称、字重、备用字体。

3.3 记录断点

grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u

标准断点：移动端 < 600px，平板端 600-899px，桌面端 900px+，大屏端 1200px+。记录任何偏差。

3.4 记录区块样式

grep -A 5 "\.section\." styles/styles.css
grep -A 5 "\.section\[" styles/styles.css

---

阶段 4：记录区块、模型和模板

过滤样板内容

静默运行——不要向用户显示输出。

• 包含：提交次数至少为 2 次，且至少有一次提交发生在“Initial commit”之后的项目
• 排除：只有“Initial commit”或只有 aem-aemy[bot] 提交的项目

4.1 识别并分析自定义区块

head -30 blocks/{blockname}/{blockname}.js
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js

针对每个自定义区块记录：

字段	记录内容
名称	区块文件夹名称
用途	区块的功能
DOM 输入	CMS 预期的 HTML 结构
DOM 输出	装饰后转换得到的结构
变体	用于修改行为的 CSS 类
依赖项	外部库、其他区块、工具函数

4.2 记录 Universal Editor 模型（如有自定义）

对 models/*.json 应用样板内容过滤。如果标准样板模型（_page.json、_section.json、_button.json、_image.json、_text.json、_title.json）未更改，则排除。若所有模型都是样板内容，则跳过本节。

4.3 记录自定义模板

对 templates/*/ 应用样板内容过滤。针对每个自定义模板，记录其用途、应用方式（元数据中的 template: name）以及它所做的更改。

---

阶段 5：生成开发者指南

5.1 输出文件

保存到 project-guides/DEVELOPER-GUIDE.md（先运行 mkdir -p project-guides）。

阅读 resources/developer-guide-template.md，了解完整文档结构。使用阶段 1–4 收集的数据填充所有章节——将每个 [placeholder] 替换为实际项目值。

5.2 转换为专业 PDF

将完成的 Markdown 文件连同 YAML frontmatter 保存到 project-guides/DEVELOPER-GUIDE.md（frontmatter 中包含 title、date，日期使用完整格式，例如“February 17, 2026”）。然后立即调用 PDF 转换：

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

whitepaper skill 会自动清理源文件。最终输出：project-guides/DEVELOPER-GUIDE.pdf。

告知用户：“开发者指南已完成：project-guides/DEVELOPER-GUIDE.pdf”

---

成功标准

类别	检查项
数据源	已调用 Config Service API（https://admin.hlx.page/config/{ORG}/sites.json）
数据源	网站列表来自 API 响应，而不是 fstab.yaml 或代码库分析
数据源	Repoless/standard 的判定来自 Config Service，而不是根据代码推断
内容	快速参考包含所有项目 URL
内容	架构概述准确反映项目
内容	设计系统已完整记录（令牌、字体、断点）
内容	已记录项目专属区块
内容	已记录自定义 scripts.js 函数
内容	已记录 delayed.js 集成
内容	已记录模板（如适用）
内容	已验证本地开发环境设置
内容	常见任务包含清晰的操作说明
内容	故障排查章节涵盖常见问题
输出	已在 project-guides/DEVELOPER-GUIDE.pdf 生成 PDF
输出	所有源文件均已清理（仅保留 PDF）

---

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