create-webroles

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果它输出消息，请在继续之前将消息显示给用户。

创建 Web 角色

为 Power Pages SPA 站点创建 Web 角色。Web 角色定义不同类型的站点用户所拥有的权限和访问级别。

非 SPA 站点使用相同的角色架构和唯一性约束，但其元数据根目录可以是 <projectRoot>/.powerpages-site，也可以是直接打开的 PAC 导出目录。

站点类型路由

在读取或执行以下工作流之前，先执行现有的 SPA 项目查找：

• 使用现有的文件搜索模式，在当前目录或其直接子目录中查找 powerpages.config.json。

• 如果找到，则继续执行以下现有 SPA 工作流。不要更改其阶段、提示、门控、文件命名、调用方抑制契约或部署行为。

• 仅当现有 SPA 查找未找到 powerpages.config.json 时，运行：

  node "${PLUGIN_ROOT}/scripts/lib/detect-project-context.js"
  

• 如果返回 siteType: "non-spa"，请读取并遵循 ${PLUGIN_ROOT}/skills/create-webroles/references/non-spa-site-workflow.md。不要执行以下任何 SPA 工作流。

• 否则，继续执行阶段 1，并保留其现有的未找到处理方式。

---

核心原则

• 使用 TaskCreate/TaskUpdate：在所有阶段跟踪进度——开始任何工作前，先创建包含所有阶段的待办列表。
• 始终使用 UUID 脚本：切勿手动生成 UUID——始终使用 ${PLUGIN_ROOT}/scripts/generate-uuid.js 为每个 Web 角色生成有效的 UUID v4 值。
• 保留唯一性约束：anonymoususersrole: true 和 authenticatedusersrole: true 各自只能用于一个角色。设置这些标志前，务必检查现有角色。
• 调用方抑制模式为可选：当此技能由另一项技能（例如 /add-ai-webapi）调用，且 $ARGUMENTS 中包含 [CALLED-BY-PARENT-SKILL] 标记时，抑制此技能的部署提示（阶段 1 的缺少部署询问、阶段 6 的部署询问（步骤 3）以及结束提醒），并在创建角色后立即返回。调用方会在整个流程结束时统一进行部署。人工调用绝不会触发此模式。解析方式见下文的阶段 0。

前置条件： 创建 Web 角色前，站点必须至少部署过一次，因为部署会创建用于存储 Web 角色定义的 .powerpages-site 文件夹结构。

初始请求： $ARGUMENTS

阶段 0：检测调用方抑制模式

检查 $ARGUMENTS。如果文本包含标记 [CALLED-BY-PARENT-SKILL]，则设置内部标志 caller-suppress = true，供后续阶段使用。标记后可能会跟随可选令牌 caller=<skill-name>，用于诊断（例如 caller=add-ai-webapi）；请记录此值以用于最终摘要，但不要据此分支处理。

设置该标志后，跳过此技能原本会发出的所有部署提示：

• 阶段 1 缺少部署询问：如果 .powerpages-site 不存在，切勿询问用户是否立即部署。向调用方返回明确的契约违规消息并停止——调用方本应在调用此技能前对此进行门控。
• **阶段 6 部署询问（步骤 3）**以及结束时的“请运行 /deploy-site”提醒：两者都跳过。调用方会在整个流程结束时统一进行一次部署决策。

如果没有该标记，则完全按照当前方式继续（完整的交互流程）。这是防止回归的保障——人工调用的行为不会改变。

---

工作流

1. 阶段 1：验证站点结构 → 检查是否存在 .powerpages-site/web-roles/ 目录
2. 阶段 2：发现现有角色 → 读取当前的 Web 角色 YAML 文件
3. 阶段 3：确定新角色 → 分析站点并询问用户需要哪些角色
4. 阶段 4：创建 Web 角色文件 → 使用 Node 脚本生成 UUID 并创建 YAML 文件
5. 阶段 5：验证 Web 角色 → 确认所有创建的文件均存在、UUID 有效且标志正确
6. 阶段 6：审核并部署 → 提供摘要并继续部署

---

阶段 1：验证站点结构

目标：确认 .powerpages-site/web-roles/ 目录存在，并已准备好存放 Web 角色文件

操作：

1. 定位项目根目录（**/powerpages.config.json），并检查是否存在 .powerpages-site/web-roles/。

🚦 关卡（计划 · create-webroles:1.deploy-first）： 缺少 .powerpages-site — 没有此文件夹，技能无法继续。提示用户先部署，或停止。

触发条件： 阶段 1 未找到 .powerpages-site 目录。 询问原因： 写入不存在路径的 Web 角色 YAML 文件不会被部署流程读取；用户会以为角色已创建，但实际上并没有。 取消后状态： 无 — 未写入任何 YAML 文件。

2. 如果 .powerpages-site 不存在：

   • 在调用方抑制模式（阶段 0 标志）下：停止并显示契约违规消息 — 调用此技能的技能应在调用我们之前，先确认此文件夹存在。
   • 否则：通过 AskUserQuestion 询问用户是否先部署（选项："是，现在部署（推荐）"、"否，我稍后处理"）。如果选择是，则调用 /deploy-site，然后从阶段 2 继续。如果选择否，则停止。

3. 如果 .powerpages-site 存在，但 web-roles/ 不存在： 创建 <PROJECT_ROOT>/.powerpages-site/web-roles/ 目录。

4. 如果两者都存在： 继续阶段 2。

输出：确认 .powerpages-site/web-roles/ 目录存在并已准备就绪

---

阶段 2：发现现有角色

目标：确定站点已定义的所有 Web 角色

操作：

1. 读取 .powerpages-site/web-roles/ 目录中的所有 YAML 文件。每个文件代表一个 Web 角色，格式如下：

   anonymoususersrole: false
   authenticatedusersrole: false
   id: 778fa3d0-a2ef-4d2b-98b8-e6c7d8ce1444
   name: Administrators
   

2. 解析每个文件，并汇总现有 Web 角色列表（名称、ID 和标志）。

3. 向用户展示现有角色：

   "我在您的站点中发现以下现有 Web 角色："

   • Administrators（ID：778fa3d0-...，已认证：false，匿名：false）
   • （等等）

4. 如果尚无角色，请告知用户：

   "您的站点目前尚未定义任何 Web 角色。"

输出：包含所有现有 Web 角色名称、ID 和标志的完整列表

---

阶段 3：确定新角色

目标：根据网站需求和用户输入，决定要创建哪些新的网站角色

操作：

🚦 关卡（plan · create-webroles:3.role-selection）： 对建议的网站角色和自定义网站角色进行多选。此选择将决定阶段 4 中写入的 YAML 文件。

触发条件： 阶段 2 已盘点现有角色；阶段 3 将建议新角色。 询问原因： 错误的角色会在本地创建——虽然可以修复，但会增加 .powerpages-site/web-roles/ 文件夹中的变更。 取消后保留： 无——尚未写入任何 YAML 文件。

1. 根据网站用途和现有角色，建议合适的网站角色。使用 AskUserQuestion 与用户确认。

   Power Pages 网站的常见角色包括：

   • 管理员 — 拥有网站管理的完整权限
   • 已验证用户 — 已登录用户的默认角色（设置 authenticatedusersrole: true）
   • 匿名用户 — 未登录访客的默认角色（设置 anonymoususersrole: true）
   • 内容编辑者 — 可以编辑网站内容的用户
   • 版主 — 可以管理社区内容的用户
   • 根据业务需求创建的自定义角色

2. 询问用户想要创建哪些角色：

   问题	选项
   您想为网站创建哪些网站角色？您可以从建议中选择，也可以描述自定义角色。	(根据网站背景、现有角色和业务领域提供相关建议)

   重要：不要建议已存在的角色。展示选项前，先筛除所有现有角色名称。

3. 允许用户指定自定义角色名称。

输出：已确认要创建的新网站角色列表

---

阶段 4：创建网站角色文件

目标：为每个新网站角色生成格式正确且 UUID 有效的 YAML 文件

操作：

对于用户批准的每个新网站角色，在 .powerpages-site/web-roles/ 中创建一个 YAML 文件。

4.1 生成 UUID

对于每个角色，使用 Node 脚本生成 UUID。切勿自行生成 UUID——务必使用脚本。

node "${PLUGIN_ROOT}/scripts/generate-uuid.js"

4.2 创建 YAML 文件

文件名应为角色名称的 kebab-case 格式，并使用 .yml 扩展名（例如，Administrators → administrators.yml，Content Editors → content-editors.yml）。

按照以下确切格式写入文件（4 个字段，不含额外空格或注释）：

anonymoususersrole: <true if this is the anonymous users role, false otherwise>
authenticatedusersrole: <true if this is the authenticated users role, false otherwise>
id: <UUID from generate-uuid.js>
name: <Role Name>

规则：

• 只能有一个角色设置 anonymoususersrole: true
• 只能有一个角色设置 authenticatedusersrole: true
• 如果现有角色已将其中一个标志设为 true，则不要在新角色中再次设置
• 每个角色都必须具有由脚本生成的唯一 UUID——每个角色运行一次脚本

输出：已创建所有新网站角色 YAML 文件

---

阶段 5：验证网站角色

目标：验证所有已创建的网站角色文件均存在、格式有效且符合约束

操作：

1. 列出 .powerpages-site/web-roles/ 中的所有文件，并读取每个新文件，以确认文件写入正确。

2. 对于每个新网站角色文件，验证：

   • 文件存在于预期路径
   • id 字段包含有效的 UUID v4 格式
   • name 字段与预期的角色名称相符
   • anonymoususersrole 和 authenticatedusersrole 是有效的布尔值

3. 验证所有角色文件（现有角色和新角色）均符合唯一性约束：

   • 设置 anonymoususersrole: true 的角色最多有一个
   • 设置 authenticatedusersrole: true 的角色最多有一个
   • 所有角色的 id 值均无重复

4. 如果任何文件未通过验证，在继续之前修复问题。

输出：所有网站角色文件均已验证——格式正确、UUID 有效且不存在违反约束的情况

---

第 6 阶段：审核与部署

目标：总结已创建的角色，并提供部署选项

操作：

1. 记录技能使用情况：

   参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

   按照参考文档中的技能跟踪说明，记录此技能的使用情况。使用 --skillName "CreateWebroles"。

2. 总结已创建的内容：

   “我已创建以下新的 Web 角色：”

角色名称	ID	匿名用户	已验证用户
内容编辑者	a1b2c3d4-...	false	false
(等等)

🚦 关卡（plan · create-webroles:6.deploy）： 创建后的最终提示——现在部署以使新角色生效，还是稍后再部署。

触发条件： 第 5 阶段验证成功。 询问原因： 自动调用 /deploy-site 会将网站推送到 PAC CLI 当前指向的环境——推送到错误环境后很难撤销。 取消后保留： 无——YAML 文件仍保留在磁盘上；不会触发部署。

3. 在调用方抑制模式下（第 0 阶段标志）：完全跳过部署询问和结束提醒。将已创建角色的摘要返回给调用方并停止。调用方负责做出唯一的编排结束部署决定；在委派任务中嵌套部署提醒，会让用户在每次父技能运行中收到 2–3 次重复提示。

   否则，询问用户是否要部署网站以应用新角色：

   问题	选项
   新的 Web 角色已在本地创建。要在 Power Pages 中应用这些角色，需要部署网站。现在要部署吗？	是，现在部署（推荐），否，我稍后部署

4. 如果选择“是，现在部署”：告知用户调用部署技能：

   “请运行 /deploy-site 来部署网站并应用新的 Web 角色。”

5. 如果选择“否，我稍后部署”：确认并提醒用户：

   “没问题！准备好将新的 Web 角色应用到 Power Pages 环境时，记得使用 /deploy-site 部署网站。”

输出：已展示摘要并提供部署选项

---

重要说明

关键决策点（等待用户）

1. 第 1 阶段后：如果缺少 .powerpages-site，确认是否部署
2. 第 3 阶段后：确认要创建哪些角色
3. 第 6 阶段后：部署或跳过

进度跟踪

开始第 1 阶段之前，使用 TaskCreate 创建包含所有阶段的任务列表：

任务主题	activeForm	描述
验证网站结构	正在验证网站结构	检查 .powerpages-site/web-roles/ 目录，如有需要则创建
发现现有角色	正在发现现有角色	读取当前 Web 角色 YAML 文件，并整理现有角色列表
确定新角色	正在确定新角色	分析网站需求，并询问用户要创建哪些角色
创建 Web 角色文件	正在创建 Web 角色文件	使用 Node 脚本为每个新角色生成带 UUID 的 YAML 文件
验证 Web 角色	正在验证 Web 角色	验证所有文件均存在、UUID 有效且满足唯一性约束
审核并部署	正在审核并部署	总结已创建的角色并提供部署选项

开始每项任务时，通过 TaskUpdate 将其标记为 in_progress，完成后标记为 completed。这样用户可以了解进度，并确保工作流可确定地执行。

---

从第 1 阶段开始：验证网站结构