manage-headers

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出了消息，请先将其展示给用户再继续。

管理标头

检查并配置 Power Pages 站点的 HTTP 安全标头。标头以 HTTP/* 站点设置的形式配置，存储在 .powerpages-site/site-settings/ YAML 文件中。

初始请求： $ARGUMENTS

注意事项

• 站点设置是 YAML 文件。 每个标头对应 .powerpages-site/site-settings/ 中的一个单独 .yml 文件。文件名会将 / 替换为 -（例如，HTTP/X-Frame-Options → http-x-frame-options.sitesetting.yml）。
• 不存在 = 无标头。 如果某项站点设置不存在，运行时会完全省略该标头（新站点上的 CSP 除外——请参阅 headers-reference.md）。
• HSTS 和 Cache-Control 由平台管理。 不要尝试设置 HTTP/Strict-Transport-Security——运行时无法识别它，该设置不会生效。
• Maker 模式会绕过标头。 来自 Power Pages Studio 的请求会跳过所有 HTTP/* 标头的发送。请在无痕标签页中验证标头，不要使用 Studio 预览。
• CSP 会原样传递。 运行时会逐字发送该值，不会自动合并运行时来源。CSP 必须包含 Power Pages 运行时主机，否则站点会出问题。
• CSP nonce。 当 script-src 包含 'nonce' 时，运行时会在每个请求中将其替换为 'nonce-<random>'，并自动为内联事件处理程序生成哈希。通过 document.createElement 动态创建的脚本不会获得 nonce。
• SameSite=None 需要 HTTPS。 运行时会在 HTTPS 上自动为每个 Cookie 设置 Secure。
• CORS * 会自动特殊处理。 运行时会在每个请求中将 * 替换为发出请求的特定 Origin——浏览器看到的是单一来源标头，而非通配符。

工作流

1. 先决条件 — 定位项目，确认 site-settings 目录存在
2. 检查当前标头 — 读取站点设置 YAML 文件，找出已配置和缺失的标头
3. 评估并规划 — 找出缺漏并提出建议
4. 应用更改 — 编辑现有设置或创建新设置
5. 总结 — 展示结果、记录使用情况并提供后续建议

任务跟踪

创建四组任务。开始时将任务标记为 in_progress，完成后标记为 completed。

组	创建时机	任务
1	开始时	检查先决条件
2	先决条件通过后	检查当前标头 · 评估并规划（审查模式下跳过“评估并规划”）
3	用户批准更改后	应用更改（审查模式下跳过，或未接受任何更改时跳过）
4	应用或评估后	总结（始终执行）

---

1. 先决条件

1.1 定位项目并检测审查模式

使用 Glob 查找 **/powerpages.config.json。如果 $ARGUMENTS 包含 --review <out-dir>，记下输出目录——跳过步骤 3–4，步骤 5 仅写入 JSON。

1.2 验证 site-settings 目录

检查 .powerpages-site/site-settings/ 是否存在。如果不存在，说明该站点尚未部署——告知用户并建议使用 /deploy-site。然后停止。

---

2. 检查当前标头

使用 Glob 查找 .powerpages-site/site-settings/ 中所有 *.yml 文件。使用 Read 读取每个文件并提取 name 和 value 字段。找出所有以 HTTP/ 为前缀的设置——这些就是已配置的标头。

与 references/headers-reference.md 中的已识别标头目录进行比较。对于目录中的每个标头：

• 已配置 — 记录其当前值。
• 缺失 — 记录为缺失，并注明 headers-reference.md 中推荐的值。

针对 CSP：如果存在 HTTP/Content-Security-Policy，使用 Glob + Read 扫描项目源文件，查找外部 URL，并检查策略是否涵盖这些 URL。通过 pac auth who 确认站点的云环境，以确定正确的 Power Pages 运行时主机（参见 headers-reference.md §“CSP 必须允许的 Power Pages 运行时来源”）。

---

3. 评估并制定计划

在审查模式下跳过。

必须只使用通俗语言。开头不要使用 CSP、CORS、HSTS 或 MIME 嗅探等术语——应以日常用语解释：

标头概念	通俗名称
Content-Security-Policy	“浏览器允许加载哪些脚本和资源”
X-Frame-Options / frame-ancestors	“其他网站能否将你的网站嵌入框架中”
X-Content-Type-Options	“阻止浏览器猜测文件类型”
CORS headers	“哪些其他网站可以调用你的网站数据”
SameSite cookies	“浏览器何时发送你的登录 Cookie”

默认做法

阅读 references/headers-reference.md，了解推荐值和指导。优先展示最重要的缺漏——相对于推荐值缺失或配置错误的标头。

🚦 关卡（计划 · manage-headers:3.per-finding）： 逐项处理——针对每个标头缺漏，询问用户接受、自定义或跳过。此流程会在循环中针对每项缺漏触发；跳过的项目会保留标头当前值，接受或自定义的项目会在第 4 阶段触发 Edit / create-script 调用。

触发条件： 第 3 阶段入口已根据 references/headers-reference.md 汇总标头缺漏。 提问原因： 自动接受可能应用会破坏站点的 CSP/CORS 值（阻止合法脚本、拒绝第三方小组件）；自动跳过则会导致站点缺少重要标头。 取消后果： 无——只有对已接受项目，第 4 阶段才会调用 Edit / create-script。

针对每项发现，使用 AskUserQuestion 展示：

• 说明更改为何重要的通俗解释
• 推荐值
• 选项：接受推荐值、自定义或跳过

不要一次性展示所有标头——先展示重要的缺漏。对于已设置为推荐值的标头，在摘要中提及即可，无需用户采取操作。

CSP 组合

当用户需要 CSP（缺失或不完整）时，使用以下内容组合一项策略：

1. headers-reference.md 中的起始模板
2. 正确的云环境专用运行时主机
3. 从项目源文件中发现的外部 URL——扫描所有源文件、模板、脚本等
4. 内联脚本的 'nonce' 关键字

展示组合或修正后的 CSP 供用户审核。建议先以仅报告模式（HTTP/Content-Security-Policy-Report-Only）开始，再启用强制执行。

---

4. 应用更改

在审查模式下跳过。

对于现有设置：直接对 YAML 文件使用 Edit——修改 value 字段。

对于新增设置：使用共享创建脚本：

node "${PLUGIN_ROOT}/scripts/create-site-setting.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --name "<setting-name>" \
  --value "<value>" \
  --description "<description>"

详情请参阅 references/commands.md。

应用所有更改后，询问是否部署：“准备好部署这些更改了吗？它们会在下次部署后生效。”如果用户同意，则调用 /deploy-site。

---

5. 总结

5.1 审查模式

首先，读取配置的 HTTP/* 站点设置（来自步骤 2——你已经获取了这些设置）。然后编写 <REVIEW_DIR>/header-annotations.json，用通俗易懂的语言描述每个标头；如果配置值确实存在问题（缺少关键指令、值较弱），则提供建议的修正方案。转换脚本不再硬编码标头描述——这些描述由你提供。

{
  "headers": {
    "HTTP/<HeaderName>": { "description": "What this header does, in plain language.", "fix": "Optional fix if the configured value has a genuine issue." }
  }
}

使用 references/headers-reference.md 获取权威说明和验证规则。仅当值存在实际问题时才提供 fix——不要对每个标头都发表意见。

然后运行转换：

node "${PLUGIN_ROOT}/skills/manage-headers/scripts/transform-headers.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --annotations "<REVIEW_DIR>/header-annotations.json"

将标准输出写入 <REVIEW_DIR>/manage-headers.json，然后停止。转换会输出 { status, findings, details }；编排技能会负责展示结果。

5.2 呈现摘要

在审查模式下跳过。

用通俗易懂的语言总结：更改了什么、还存在哪些缺口，以及哪些配置已经妥当。

5.3 记录技能使用情况

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

使用 --skillName "ManageHeaders"。

5.4 提供后续建议

如果根据发现的问题存在自然的后续操作，请提出建议。如果没有有意义的后续操作，则结束技能。

---

约束

• 使用通俗语言——绝不能对用户使用技术行话。用日常用语解释标头名称。
• 以 headers-reference.md 为准——推荐值和已识别的标头目录均以该文件为准。评估前先阅读。
• 结合上下文进行交互——每条建议都必须反映站点的实际配置和用法：
  • 提出任何值建议前，先阅读站点的源文件、集成和身份验证设置。
  • 未验证某个值不会破坏站点功能之前，绝不要推荐该值（参见 headers-reference.md 中的“需验证的上下文”列）。
  • 提出更改建议时，承认现有值可能是有意设置的。
  • 对于 CSP，参考项目源文件中实际出现的外部 URL。
  • 对于 CORS，确认站点实际使用的跨域使用方，再设定范围。
  • 对于 Cross-Origin-Opener-Policy，确认站点是否使用基于弹出窗口的身份验证。
  • 对于 Cross-Origin-Resource-Policy，确认站点是否托管 Azure AD B2C 自定义登录页面、是否被跨域嵌入，或是否有集成会加载其资源。不确定时，保持未设置或使用 cross-origin。
• 预览仅用于审查更改——仅对会修改设置值的选项添加 preview。不要添加到信息类选项中。
• 建议绝不能破坏站点——推荐某个值前，考虑它是否会阻止站点实际使用的资源。对于 CSP，始终确认已包含运行时来源和项目外部 URL。对于 CORS，确认站点实际的跨域需求。不确定时，优先建议先使用仅报告模式。
• 绝不要建议放宽现有策略——如果用户已有严格的 CSP、CORS 范围或限制性标头值，不要建议降低限制。有效的严格策略优于宽泛策略。绝不要在 CSP 指令中推荐 https: 通配符——应列出具体主机。
• 更改后部署——标头更改只有在部署后才会生效。应用更改后，始终提供 /deploy-site 选项。

参考资料

• references/headers-reference.md——已识别的标头目录、推荐值、CSP 组合规则和运行时来源。在交互模式下，于步骤 2（检查）和步骤 3（评估）之前阅读。
• references/commands.md——共享的 create-site-setting.js 用法。在创建新设置的步骤 4（应用）时阅读。