security-review

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

安全审查

引导用户全面审查其 Power Pages 网站的安全性。运行匹配的专项技能，并将所有发现汇总到一份 HTML 报告中。

此技能不会向用户提出技术问题。对话将使用通俗语言。

初始请求： $ARGUMENTS

工作流

此技能分为六个阶段。阶段 2–5 各对应与用户交流的一个环节；阶段 1 和 6 是静默的准备与清理。各环节的说明请参阅 references/flow.md。

阶段	执行内容	面向用户的环节
1 — 前置条件	定位项目，设置工作文件夹	（静默准备）
2 — 范围	了解目标 — 提出一个问题，提供三个答案选项，使用通俗语言	询问目标
3 — 技能	运行匹配的技能，展示进度	扫描进行中
4 — 报告	构建汇总报告 — 汇总 + 各部分的发现	结果摘要 + 发现
5 — 呈现	呈现结果，提供后续修复选项	后续步骤和指导
6 — 清理	删除临时文件	（静默清理）

任务跟踪

分三组创建任务。开始时将每项任务标记为 in_progress，完成时标记为 completed。

第 1 组 — 在前置条件开始时创建：

任务主题	activeForm
检查前置条件	正在检查前置条件

仅创建这一项任务。前置条件完成前，不要创建其他任务。

第 2 组 — 前置条件完成后创建：

任务主题	activeForm
了解目标	正在了解目标

第 3 组 — 了解目标后创建：

任务主题	activeForm
运行技能	正在运行检查
构建报告	正在构建报告
呈现发现	正在呈现发现
清理	正在清理

---

1. 前置条件

1.1 定位项目

使用 Glob 查找 **/powerpages.config.json。如果找不到，请告知用户需要先通过 /create-site 创建网站，然后停止。

对于 monitor 和 release 目标（任何委派给 scan-site 或 manage-firewall 的目标），还需确认 .powerpages-site/website.yml 存在。如果不存在，则说明网站尚未部署 — 请用通俗语言告知用户，运行在线安全审查前需要先部署一次，并建议使用 /deploy-site，然后停止。不要尝试通过名称或 URL 识别网站 — 不同网站可能同名。

对于 code-config 目标，无需检查部署状态：源代码、依赖项、身份验证、Web 角色和表权限都只从本地文件读取。

1.2 准备临时工作文件夹

创建一个全新的工作目录：<SYSTEM_TEMP>/security-review/。此文件夹用于存放各项技能在审查模式下生成的 JSON 数据文件。清理步骤会删除此文件夹。

如果此文件夹是上次中断运行时留下的，请先删除其中的内容（不要删除文件夹本身），再继续。

1.3 确定文档输出路径

最终 HTML 文件始终保存到 <PROJECT_ROOT>/docs/security-review-<YYYY-MM-DD-HHMMSS>.html，使用本次运行开始时的本地时间戳（例如 security-review-2026-05-14-053805.html）。务必包含时间戳 — 不要使用不带时间戳的 security-review.html 文件名。这样可确保每次运行生成的报告都各不相同。

---

2. 了解目标

2.1 询问目标

🚦 关卡（计划 · security-review:2.1.goal）： 确认审查目标——选项将进入三组子技能之一（code-config / release / monitor）。

触发条件： 进入阶段 2.1 时触发，除非 $ARGUMENTS 已经说明目标。 询问原因： 自动选择 release 会运行所有子技能（耗时较长；可能会不必要地访问扫描／防火墙端点）；自动选错目标则会导致审查范围不匹配。 取消时的后续： 无——尚未调用任何子技能。

使用一次 AskUserQuestion 调用询问用户。如果用户的初始请求已经说明目标，则跳过并继续。

问题——要审查什么？

标签	说明
代码与配置	检查源代码、依赖项、身份验证、Web 角色和表权限。仅处理本地文件。
发布准备情况	发布前进行完整审查——检查所有内容。（推荐）
已部署网站	检查线上网站是否存在问题。需要已部署。

目标映射（内部）：

标签	目标 ID	技能
代码与配置	code-config	scan-code、audit-permissions、setup-auth（只读）
发布准备情况	release	scan-code、scan-site、manage-headers、manage-firewall、audit-permissions、setup-auth（只读）
已部署网站	monitor	scan-site

2.2 记录选定的技能集

根据回答构建 selectedSkills 列表。对于 code-config 和 release 目标，始终包含对 setup-auth 的只读检查（它只读取现有 YAML，不会运行该技能本身——见下文 § 3.2）。这是访问与数据安全验证组件。

---

3. 运行匹配的技能

通过 Agent 工具将选定的每项技能作为后台子代理启动。每个子代理都使用参数 --review <SYSTEM_TEMP>/security-review/ 调用自己的技能。每项技能自行处理身份验证、错误报告和进度。

3.1 通过子代理调用技能

技能通过 Agent 工具作为并行子代理运行。

默认方式——在一个并行批次中启动所有符合 Agent 条件的技能。 在一条消息中通过多个 Agent 工具调用生成所有选定的子代理，使其并发启动。每个子代理都使用 run_in_background: true 运行。符合 Agent 条件的技能包括 scan-code、scan-site、manage-headers 和 manage-firewall——它们都支持 --review 模式。scan-site（服务器端扫描，需数分钟）和 scan-code（本地静态分析与依赖项扫描，大型项目可能需要数分钟）耗时最长；其他技能通常几秒内即可完成。

备用方式——分批启动。 如果执行环境因任何原因拒绝并行批次调用，则先启动 scan-code 和 scan-site（耗时较长的技能），然后在后续消息中启动剩余技能。这是工具能力不足时的备用方案，并非首选方式。

内联检查（在子代理运行期间执行）。 audit-permissions 和 setup-auth 不支持 --review，因此绝不能通过 Agent 启动——应按 § 3.2 中所述以内联方式处理。

在进入构建报告步骤之前，等待所有子代理完成。

3.1.1 子代理提示词模式

每个子代理都会收到一条自包含的提示词，其中包括：

1. 要调用的技能，以及带有临时目录路径的 --review 参数
2. 项目根目录路径，以便技能定位网站文件
3. 在范围捕获步骤中记录的所有范围／深度参数

子代理调用示例：

Agent({
  description: "Run scan-site",
  prompt: "Invoke the skill `scan-site` with argument `--review <SYSTEM_TEMP>/security-review/`. The Power Pages project root is <PROJECT_ROOT>. <any additional scope parameters>. Write the **transform script stdout verbatim** to <SYSTEM_TEMP>/security-review/scan-site.json. Do NOT synthesize, augment, or re-classify the findings. If the skill fails, write { \"status\": \"skipped\", \"reason\": \"<plain-language reason>\" } instead.",
  run_in_background: true
})

原文规则： 子代理的输出 JSON 必须仅包含技能转换脚本输出的发现项。编排器不得追加发现项、改写标题、添加严重性等级或以其他方式进行编辑。

3.1.2 预期输出

所有子 Agent 完成后，预计会在 <SYSTEM_TEMP>/security-review/<skill-name>.json 中找到 JSON 文件。每个文件的结构为 { status, findings, details? }，由该技能的转换脚本生成：

<SYSTEM_TEMP>/security-review/
├── scan-code.json           (when invoked)
├── scan-site.json
├── manage-headers.json
├── manage-firewall.json
└── audit-permissions.json   (when invoked)

如果某个技能的子 Agent 失败或被跳过，请写入一个结构为 { "status": "skipped", "reason": "<plain-language reason>" } 的占位文件。报告构建步骤会将其呈现为该部分的单条非严重性发现（不含 severity 字段，以与 § 3.1.3 保持一致）。

3.1.3 严重性策略

只有来自确实会输出严重性的工具的发现，才可以带有 severity 字段：

部分	来源	是否允许严重性？
scan-code	opengrep, trivy	是
scan-site	deep-scan (ZAP)	是
manage-headers	transform-headers.js（清单）	否
manage-firewall	transform-firewall.js（清单）	否
audit-permissions	Web 角色与表权限审计	否
setup-auth	站点设置与身份验证相关源代码审计	否

对于清单部分，请勿在发现中添加 severity，甚至不要添加 info。子 Agent 和协调器必须原样写入转换输出，不得插入带有主观判断严重性的发现。也不得将 tag 字段用作严重性变通方案：该字段仅用于工具提供的简短机械标识符（例如 ZAP 规则 ID、CWE 代码），绝不能包含等同于严重性的字符串（critical、warning、info），因为报告模板会将其显示为标题旁的可见标签。

3.1.4 注释策略（通俗易懂的文本）

manage-firewall 和 manage-headers 的转换脚本仅生成结构化原始数据，不会硬编码通俗易懂的描述。子 Agent 必须生成注释 JSON 文件，并通过 --annotations 将其传递给转换脚本。注释应提供：

• 每条规则 / 每个标头的通俗易懂描述
• 存在真实问题时可选的建议修复方案

请参阅各技能的 SKILL.md § 5.1，了解注释文件的结构。Agent 的任务是根据原始数据编写准确、简洁的描述，而不是臆造严重性或捏造问题。

3.2 不支持 --review 模式的技能

audit-permissions 和 setup-auth 不支持 --review。请在当前流程中处理，而非将其作为后台子 Agent：

• audit-permissions — 通过 Skill 工具调用（而非 Agent）。该技能会同时审计Web 角色和表权限，请在其输出中记录两者。完成后，读取其输出，并按照统一的 { status, findings, details? } 结构写入 <SYSTEM_TEMP>/security-review/audit-permissions.json（将每项审计发现映射到通用发现字段：id、title、location、details、fix）。
• setup-auth — 不要将其作为技能调用。请直接读取 .powerpages-site/site-settings/ 中的 YAML 文件，并检查：
  • 是否配置了身份提供方？（Authentication/OpenIdConnect/*/Authority）
  • 是否已禁用个人资料重定向？（Authentication/Registration/ProfileRedirectEnabled = false）
  • Cookie SameSite 设置是什么？（HTTP/SameSite/Default）

请按相同格式将生成的发现写入 <SYSTEM_TEMP>/security-review/setup-auth.json。

这两个部分的字段策略 — 它们是清单部分，不属于工具输出严重性（参见 § 3.1.3）：

• 请勿在任何发现中包含 severity 字段。
• 请勿包含 tag 字段。tag 字段仅用于工具提供的简短机械标识符（HTTP/X-Frame-Options、ZAP 规则 ID 10055、CWE 代码）。绝不能包含等同于严重性的字符串（critical、warning、info）——报告模板会将 tag 显示为标题旁的可见标签，因此将大模型判断的严重性塞入该字段，会在视觉上重新引入本部分明确禁止的严重性分级。

3.3 状态更新

告诉用户所有检查都在并行运行。每个子 Agent 完成后，发送一条简短的进度消息（例如：“代码检查已完成——发现 2 个重要问题和 4 个较小问题。”）。避免使用技术术语。不要叙述技能的内部步骤。所有子 Agent 完成后，先确认所有检查均已完成，再进入报告生成步骤。

---

4. 生成汇总报告

4.1 汇总

将最多 4 条通俗易懂的后续建议写成 JSON 字符串数组，保存到 <SYSTEM_TEMP>/security-review/next-steps.json。用 2–4 句话通俗地概述整体情况。

node "${PLUGIN_ROOT}/scripts/build-review-data.js" \
  --reportName "Security Review" \
  --inputDir "<SYSTEM_TEMP>/security-review/" \
  --siteName "<SITE_NAME>" \
  --goalLabel "<GOAL_LABEL>" \
  --scopeLabel "<SCOPE_LABEL>" \
  --summary "<SUMMARY_TEXT>" \
  --nextStepsFile "<SYSTEM_TEMP>/security-review/next-steps.json" \
  --output "<SYSTEM_TEMP>/security-review/security-review-data.json"

4.2 渲染主 HTML 报告

node "${PLUGIN_ROOT}/scripts/render-review.js" \
  --output "<DOCS_PATH>" \
  --data "<SYSTEM_TEMP>/security-review/security-review-data.json"

---

5. 呈现报告并跟进

5.1 在浏览器中打开

在用户的默认浏览器中打开 <DOCS_PATH>。

5.2 记录技能使用情况

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

使用 --skillName "SecurityReview"。

5.3 聊天摘要

🚦 关卡（计划 · security-review:5.3.next-action）： 报告后的下一步提示——"带我逐项处理修复 / 重新运行检查 / 暂时到此为止"。此提示决定是否调用修复技能。

触发条件： 第 5.1 阶段已写入 HTML 报告。 询问原因： 避免用户尚未阅读报告就自动调用修复技能（/manage-headers、/manage-firewall、/audit-permissions）；也避免对刚生成的结果自动重新检查，浪费时间。 取消后的结果： 无——docs/security-review-<ts>.html 中的 HTML 报告始终是最终产物。

在聊天中简要概述情况：说明严重 / 警告 / 信息级发现的数量，以及报告的保存位置。然后使用 AskUserQuestion 提供下一步选项：

问题	选项
接下来你想做什么？	带我逐项处理修复；重新运行检查；暂时到此为止

如果用户选择“带我逐项处理修复”，则按章节归类严重发现，并针对每项提供相应的专门技能（/manage-headers、/manage-firewall、/audit-permissions 等）。

如果用户选择“重新运行检查”，则使用相同目标和范围再次调用此技能。

---

6. 清理

删除整个 <SYSTEM_TEMP>/security-review/ 文件夹。最终 HTML 位于 docs/，必须保留。确认已为用户删除临时文件。

如果清理失败（文件被锁定、权限不足），请提醒用户并继续——报告已写入，之后仍可手动删除临时文件夹。

---

约束

• 使用通俗易懂的语言与用户交流——不要一开始就使用技术术语。
• 并行委派子 Agent——每个选定的技能都必须通过 Agent 工具作为并行子 Agent 运行，并在单条消息中启动。子 Agent 工作期间，执行内联的只读 setup-auth 检查。只有在运行环境拒绝并行批次调用时，才使用错峰启动方式（§ 3.1 后备方案）。
• 仅生成一份汇总 HTML 报告——本次运行期间不得生成单个技能的 HTML 报告。技能以 --review 模式运行。
• 保持外观一致——通过 ${PLUGIN_ROOT}/scripts/lib/templates/security-review-report.html 中的共享模板，使用 scripts/render-review.js 进行渲染。不得编写单个技能的 HTML，也不得复制模板；生成的报告在视觉上必须与现有的 audit-permissions 报告一致。
• 必须清理——清理步骤不可省略。清理失败可视为非致命警告，但技能始终会尝试清理。
• 绝不自动执行破坏性子操作——提出更改建议的技能（例如编辑站点设置、删除 WAF 规则）在此编排过程中必须以只读 --review 模式运行。只有用户明确选择“带我逐项处理修复”后，才能应用更改。

参考资料

• references/flow.md——第 2–5 阶段对话环节的缘由和措辞示例