authoring

项目交接 — 内容编写

为内容作者和内容经理生成完整的内容编写指南。此技能会分析项目并生成可执行的文档。

何时使用此技能

• 为新项目的新内容作者提供入门指导
• 培训内容经理
• 将项目交接给客户的内容编写团队
• 创建面向内容作者的文档

---

步骤 0：导航到项目根目录并验证 Edge Delivery Services 项目（有条件执行）

如果已设置 allGuides 标志，请跳过此步骤（编排程序已完成验证并导航）。

重要：如果不跳过，则必须执行 cd 命令。不要使用绝对路径——实际切换目录。

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
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi

重要：

• 必须使用 Bash 工具运行上方的 cd 命令
• 后续所有步骤均从项目根目录执行
• 不要使用绝对路径进行验证——实际导航到该目录
• 指南将创建在 project-root/project-guides/ 中

如果未跳过，且 scripts/aem.js 不存在，请回复：

"此技能专为 AEM Edge Delivery Services 项目设计。当前目录似乎不是 Edge Delivery Services 项目（未找到 scripts/aem.js）。

请导航到 Edge Delivery Services 项目，然后重试。"

如果检查失败，请停止。否则继续——你现在位于项目根目录。

---

沟通指南

• 在任何生成的文档或聊天回复中，绝不要使用 “EDS” 作为 Edge Delivery Services 的缩写
• 始终使用全称 “Edge Delivery Services” 或 “AEM Edge Delivery Services”
• 这适用于所有输出文件（PDF、HTML、Markdown）以及与用户的所有沟通

---

⚠️ 关键路径要求

必须将文件保存到此确切路径：

project-guides/AUTHOR-GUIDE.md

写入任何文件之前：

1. 首先创建目录：mkdir -p project-guides
2. 然后写入：project-guides/AUTHOR-GUIDE.md

原因： 文件必须位于 project-guides/ 中，以便妥善整理并转换为 PDF。

❌ 错误： AUTHOR-GUIDE.md（根目录） ❌ 错误： docs/AUTHOR-GUIDE.md ❌ 错误： /workspace/AUTHOR-GUIDE.md ✅ 正确： project-guides/AUTHOR-GUIDE.md

---

输出格式

必须输出： project-guides/AUTHOR-GUIDE.pdf

严格禁止：

• ❌ 不要读取或分析 fstab.yaml——大多数项目中并不存在此文件，而且它不会显示所有站点
• ❌ 不要创建 .plain.html 文件
• ❌ 不要使用 convert_markdown_to_html 工具——它会将完整指南转换为 HTML，并显示原始 frontmatter，这不是我们想要的
• ❌ 不要告诉用户“手动将 Markdown 转换为 PDF”
• ❌ 不要将 Markdown 保存到根目录或 project-guides/ 以外的任何路径
• ❌ 不要说“稍后”或“会话结束时”生成 PDF——现在就生成

必须遵循的工作流程：

1. 运行 mkdir -p project-guides，确保目录存在
2. 使用 YAML frontmatter（标题、日期）生成 Markdown 内容
3. 保存到 project-guides/AUTHOR-GUIDE.md（确切路径——不得例外）
4. 立即调用 PDF 转换（参见阶段 5.2）
5. 清理所有源文件（仅保留 PDF）
6. 最终输出：project-guides/AUTHOR-GUIDE.pdf

---

执行清单

- [ ] Phase 1: Gather Project Information
- [ ] Phase 2: Analyze Content Structure
- [ ] Phase 3: Document Blocks and Templates
- [ ] Phase 4: Document Configuration Sheets
- [ ] Phase 5: Generate Professional PDF

---

阶段 0：获取组织名称（必须首先执行）

每次运行此技能时——无论用户直接触发（例如“生成内容编写指南”），还是通过交接流程触发，都必须先获取 Config Service 组织名称，然后才能执行任何其他操作。不要跳过此阶段。

0.1 检查已保存的组织

# Check if org name is already saved
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 保存组织名称

获取组织名称后（来自已保存的配置或用户输入），将其保存以供将来使用：

# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains project config)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# Save org name to config file (create or update)
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} 替换为用户提供的实际组织名称。

---

阶段 1：收集项目信息

1.1 通过 Config Service API 获取站点和代码仓库

⚠️ 必须使用的数据源——不允许使用其他来源

必须调用 Config Service API。这是唯一可接受的站点信息来源。

❌ 禁止的做法（会导致结果不正确）：

• 分析 fstab.yaml——在无仓库设置中无法显示所有站点
• 阅读 README.md——内容可能过时或不完整
• 根据代码库结构推断——会遗漏 CDN 配置和其他站点
• 使用 git 远程 URL——组织名称可能与 Config Service 组织不同
• 根据项目文件夹名称进行假设

✅ 必须执行并保存响应：

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# Save response to file - Phase 2 depends on this file
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

📁 必须生成的文件： .claude-plugin/sites-config.json

API 参考： https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

响应是一个包含 sites 数组的 JSON 对象（每个条目都有一个 name 字段）。提取站点名称并构建各站点的 URL：

• 预览： https://main--{site-name}--{org}.aem.page/
• 线上： https://main--{site-name}--{org}.aem.live/

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

然后获取各站点的配置，以了解代码和内容详情。

首先，检查身份验证令牌是否有效：

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.imsToken && t.imsTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.imsToken);
    }
  } catch (e) {}
")

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

如果出现 AUTH_REQUIRED，请先调用身份验证技能再继续：

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

然后获取站点配置：

IMS_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.imsToken || '');
  } catch (e) {}
")
curl -s -H "Authorization: Bearer ${IMS_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

响应示例：

{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    },
    "contentBusId": "..."
  }
}

从响应中提取：

• code.owner / code.repo — GitHub 仓库
• content.source.url — 内容挂载路径（例如，https://content.da.live/org/site/）
• content.source.type — 内容来源类型（markup、onedrive、google）

根据内容来源构建 URL：

• DA URL： https://da.live/#/{org}/{site}/（根据 content.source.url 得出）
• 区块库： https://da.live/#/{org}/{site}/.da/library

⚠️ 不要使用 fstab.yaml——请改用 Config Service API。

1.2 检查多语言支持

# Check for language folders in content structure
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

记录可用的区段样式（例如，深色、突出显示、窄版），用于指南中的“可用区段样式”表格。

---

阶段 3：记录区块和模板

3.1 列出并分析区块

ls blocks/

静默运行区块分析。针对每个区块，确定其用途、变体（例如来自 CSS .blockname.variant）以及作者应在何时使用它。记录项目中的所有区块，让作者了解可用内容。

3.2 记录模板

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

3.3 DA 和 Block Library 路径

从 Config Service 站点配置（内容源）中获取内容路径。Block Library 的 URL 为 https://da.live/#/{content-owner}/{content-path}/.da/library — 路径因项目而异。记录库中显示的区块／模板。

---

阶段 4：记录配置表

4.1 占位符

**位置：**DA 中的 /placeholders（或 /placeholders.xlsx）

ls placeholders.json 2>/dev/null

文档：

字段	说明
位置	在 DA 中查找占位符的位置
语言	存在哪些语言工作表（en、fr 等）
关键字符串	作者可能需要更新的重要占位符

4.2 重定向

**位置：**DA 中的 /redirects（或 /redirects.xlsx）

ls redirects.json 2>/dev/null

文档：

字段	说明
位置	在 DA 中查找重定向的位置
格式	源列 → 目标列
使用场景	URL 变更、页面删除、页面重命名

4.3 批量元数据

**位置：**DA 中的 /metadata（或 /metadata.xlsx）

ls metadata.json 2>/dev/null

文档：

字段	说明
位置	在 DA 中查找批量元数据的位置
模式	使用的 URL 模式（例如 /news/*）
属性	批量设置了哪些元数据属性

4.4 其他配置表

检查是否存在项目专用的配置表：

# Look for other Excel/JSON config files
ls -la *.xlsx *.json 2>/dev/null | grep -v package

---

阶段 5：生成作者指南

5.1 输出文件：project-guides/AUTHOR-GUIDE.md

# [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 source like `content.da.live/org/site/` → use `org/site` for the path after `#/`. This can differ per project; do not use code.owner/code.repo unless the API explicitly maps them.)

### Sites

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

(One row per site from Config Service. **Content Source (DA)** is the content path for that site — use it to build DA and Block Library URLs: `https://da.live/#/{path-from-content-source}/` and `.../.da/library`. Path format varies by project, e.g. `audemars-piguet/arbres-fondationsaudemarspiguet`.)

## 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 into your document.

| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to the Block Library URL (from Config Service content path for this project): `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **What's in it** | All blocks and templates listed in the "Available Blocks" and "Page Templates" sections below appear in the library |
| **How to use** | Click a block or template in the library to insert it at the cursor position in your document |

When creating or editing a page, use the Library sidebar to add blocks instead of typing block names manually.

## 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 Section Metadata block at end of section:

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

**Available Section Styles:**

| Style | Effect |
|-------|--------|
| [List project-specific styles in table format] |

## 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, ensure it 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（必须完成）

此步骤并非可选。现在必须生成 PDF。

1. 将 Markdown 保存到：project-guides/AUTHOR-GUIDE.md

   • 文件必须以 YAML frontmatter 开头：

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

   • 日期格式：始终使用包含日、月、年的完整日期（例如“February 17, 2026”），不能只写月份和年份

2. 保存 Markdown 后立即调用 PDF 转换技能：

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

3. 等待 PDF 生成完成（whitepaper 技能会自动清理源文件）

不要：

• 跳过 PDF 转换步骤
• 告诉用户“稍后会生成 PDF”——现在就生成

5.3 交付给用户

生成 PDF 后，通知用户：

"✓ Author guide complete: project-guides/AUTHOR-GUIDE.pdf"

---

输出

最终输出：project-guides/AUTHOR-GUIDE.pdf

PDF 生成后，所有源文件（.md、.html、.plain.html）都会被删除。仅保留 PDF。

位置：project-guides/ 文件夹

---

成功标准

数据源验证（关键）：

• 已调用 Config Service API（https://admin.hlx.page/config/{ORG}/sites.json）
• 站点列表来自 API 响应，而非 fstab.yaml 或代码库分析
• DA/Block Library URL 根据 Config Service 内容源推导得出，而非根据 code.owner/repo 假定

内容验证：

• 快速参考表包含所有项目 URL
• 所有区块均以表格形式记录
• 所有模板均包含必需的元数据
• 已记录配置表
• 已说明发布工作流
• 已记录常见任务
• 已列出章节／页面元数据选项
• 已包含故障排除内容

输出验证：

• PDF 已成功生成
• 所有源文件均已清理（仅保留 PDF）

---

清晰文档编写提示

1. 使用表格，以便紧凑地呈现参考信息
2. 使用简单的语言，避免技术术语
3. 使用实际项目内容中的示例
4. 记录前先测试操作流程