handover-author

项目交接——内容创作

为内容作者和内容管理员生成完整的内容创作指南。分析项目并生成可执行的文档。

---

步骤 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 from Config Service API
- [ ] Phase 2: Analyze content structure
- [ ] Phase 3: Document blocks and templates
- [ ] Phase 4: Document configuration sheets
- [ ] 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 通过 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 — GitHub 仓库
• content.source.url — 内容挂载路径（例如，https://content.da.live/org/site/）
• content.source.type — 内容源类型（markup、onedrive、google）

根据内容源构建 DA 和区块库 URL：

• DA URL：https://da.live/#/{org}/{site}/
• 区块库：https://da.live/#/{org}/{site}/.da/library

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

1.2 检查多语言支持

ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"

记录项目是否为多语言项目，以及支持哪些语言。

---

阶段 2：分析内容结构

读取阶段 1 中的站点配置：

cat .claude-plugin/sites-config.json

2.1 分析导航和页脚

ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"

记录：导航和页脚的位置（DA 路径或本地文件）、菜单结构、移动端行为。

2.2 确定页面模板

ls -la templates/ 2>/dev/null && ls templates/

对于每个模板，记录：名称、用途、应用方法（元数据设置）。

2.3 区段样式

grep -E "\.section\." styles/styles.css 2>/dev/null | head -15

记录可用的区段样式（例如，dark、highlight、narrow），用于指南中的“可用区段样式”表格。

---

阶段 3：记录区块和模板

3.1 列出并分析区块

ls blocks/

静默运行区块分析。确定每个区块的用途、变体（来自 CSS .blockname.variant），以及作者应在何时使用该区块。记录所有区块，让作者了解可用选项。

3.2 记录模板

对于阶段 2.2 中找到的每个模板，记录：名称、用途、必填元数据字段，以及应用方法（在 Metadata 区块中设置 template: name）。

3.3 DA 和区块库路径

从 Config Service 站点配置中获取内容路径。区块库 URL 为 https://da.live/#/{content-owner}/{content-path}/.da/library — 该路径因项目而异。

---

阶段 4：记录配置表

4.1 占位符

ls placeholders.json 2>/dev/null

记录：DA 中的位置、语言表格、作者可能需要更新的关键字符串。

4.2 重定向

ls redirects.json 2>/dev/null

记录：DA 中的位置、格式（来源 → 目标列）、使用时机。

4.3 批量元数据

ls metadata.json 2>/dev/null

记录：DA 中的位置、URL 模式、通过批量操作设置的元数据属性。

4.4 其他配置表

ls -la *.xlsx *.json 2>/dev/null | grep -v package

---

阶段 5：生成内容创作指南

5.1 输出文件

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

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

# [Project Name] - Author Guide

## Quick Reference

| Resource | URL |
|----------|-----|
| Document Authoring | https://da.live/#/{content-owner}/{content-path}/ |
| Preview (per site) | https://main--{site}--{org}.aem.page/ |
| Live (per site) | https://main--{site}--{org}.aem.live/ |
| Block Library | https://da.live/#/{content-owner}/{content-path}/.da/library |
| Bulk Operations | https://da.live/apps/bulk |

(**Content path** comes from the Config Service site config — e.g., `content.da.live/org/site/` → use `org/site` for the path after `#/`. This varies by project.)

### Sites

| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

## Getting Started

### Access Requirements
- [ ] DA access (request from admin)
- [ ] Preview/publish permissions

### Your First Page
1. Go to DA: [link]
2. Navigate to the correct folder
3. Create new document
4. Use blocks from Library sidebar
5. Add Metadata block at bottom
6. Preview → Publish

## Content Organization

### Site Structure
[Describe the folder structure in DA]

### Languages
[List supported languages if multi-lingual]

## Block Library

The Block Library is the sidebar in Document Authoring where you browse and insert blocks and templates.

| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to: `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **How to use** | Click a block or template in the library to insert it at the cursor position |

## Available Blocks

| Block | Purpose | Variants | Usage |
|-------|---------|----------|-------|
| [name] | [what it's for] | [variant1, variant2] | [when to use] |

[Generate table rows for all blocks]

## Page Templates

| Template | Purpose | Required Metadata | How to Apply |
|----------|---------|-------------------|--------------|
| [name] | [what type of pages] | [key fields] | `template: [name]` in Metadata |

[Generate table rows for all templates]

## Configuration Sheets

| Sheet | Location | Purpose | When to Update |
|-------|----------|---------|----------------|
| Placeholders | `/placeholders` | Reusable text strings, translations | Changing labels, button text |
| Redirects | `/redirects` | Forward old URLs to new URLs | After deleting/moving pages |
| Bulk Metadata | `/metadata` | Apply metadata to multiple pages | Setting defaults by folder |

## Publishing Workflow

| Environment | Domain | Purpose |
|-------------|--------|---------|
| Preview | `.aem.page` | Test changes before going live |
| Live | `.aem.live` | Production site |

**Workflow:** Edit in DA → Preview → Publish → Live immediately

**Bulk:** https://da.live/apps/bulk

## Common Tasks

| Task | Steps |
|------|-------|
| **Create a Page** | Navigate to folder → New → Document → Add content → Add Metadata → Preview → Publish |
| **Edit a Page** | Open in DA → Make changes → Preview → Publish |
| **Delete a Page** | Add redirect first → Delete document → Publish redirects |
| **Update Navigation** | Edit `/nav` document → Preview → Publish |
| **Update Footer** | Edit `/footer` document → Preview → Publish |

## Sections and Section Metadata

Sections group content together. Create sections with horizontal rules (`---`).

Add styles with a Section Metadata block at the end of the section:

| Section Metadata | |
|------------------|-|
| style | [style-name] |

**Available Section Styles:**

| Style | Effect |
|-------|--------|
| [List project-specific styles] | |

## Page Metadata

| Property | Required | Purpose | Example |
|----------|----------|---------|---------|
| `title` | Yes | Page title for SEO | "About Us" |
| `description` | Yes | SEO description | "Learn about..." |
| `image` | No | Social sharing image | /images/og.jpg |
| `template` | No | Apply page template | project-article |
| [Add project-specific fields] | | | |

## Images and Media

| Method | How |
|--------|-----|
| Drag & drop | Drag images directly into DA editor |
| AEM Assets | Use Assets sidebar in DA |

Best practices: descriptive filenames, always add alt text, images auto-optimized.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Page not updating after publish | Wait 1-2 min for cache, hard refresh (Cmd+Shift+R) |
| Block not displaying correctly | Check structure matches expected format, verify variant spelling |
| Images not showing | Verify image uploaded to DA, check path is correct |
| Wrong template styling | Check `template` value in Metadata matches template name exactly |

## Resources

| Resource | URL |
|----------|-----|
| DA Documentation | https://docs.da.live/ |
| Authoring Guide | https://www.aem.live/docs/authoring |
| Placeholders Docs | https://www.aem.live/docs/placeholders |
| Redirects Docs | https://www.aem.live/docs/redirects |

## Support Contacts

[Add project-specific contacts]

5.2 转换为专业 PDF

将完成的 Markdown 保存到 project-guides/AUTHOR-GUIDE.md，并添加 YAML 前置元数据（标题、完整日期格式的日期，例如“February 17, 2026”）。然后立即调用 PDF 转换：

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

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

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

---

成功标准

类别	检查项
数据源	已调用 Config Service API（https://admin.hlx.page/config/{ORG}/sites.json）
数据源	站点列表来自 API 响应，而非 fstab.yaml 或代码库分析
数据源	DA/Block Library URL 根据 Config Service 内容源推导，而非根据 code.owner/repo 臆测
内容	包含列出所有项目 URL 的快速参考表
内容	以表格形式记录所有区块
内容	记录所有模板及其必需元数据
内容	记录配置表
内容	说明发布工作流
内容	记录常见任务
内容	列出节/页面元数据选项
内容	包含故障排除内容
输出	在 project-guides/AUTHOR-GUIDE.pdf 生成 PDF
输出	清理所有源文件（仅保留 PDF）

---

**沟通要求：**任何输出和文档中都不得使用“EDS”作为缩写；始终写作“Edge Delivery Services”或“AEM Edge Delivery Services”。