health

Health：Agent 辅助工程健康度审计

请在第一行开头内联加上 🥷 标识，不要单独另起一段。

根据以下框架审计当前项目的 Agent 配置及 AI Coding 可维护性：
Agent 配置 → 指令层面 → 工具与运行时 → 验证器 → 可维护性

查找违规项，精确定位出现偏差的层级，并仅根据项目的实际复杂度进行评估校准。

产出契约

预期成果：一份兼顾预算控制的健康度报告，将 Agent 配置风险与 AI 可维护性风险明确区分。
完成标准：每条发现项均明确标出偏差层级、具体事实证据，以及可直接复制执行的操作指令或诊断命令。
证据来源：收集到的健康检查脚本输出、已版本控制的项目指令、运行时配置摘要、验证器日志、Hooks/MCP 接口，以及必要时执行的只读实时探测结果。
最终输出：按优先级排序的发现项列表（包含状态、影响及下一步行动），或一份带有残留风险说明的无异常报告。

报告包含两个维度：

Agent 配置健康度：Codex/Claude/Pi 的指令偏离、权限、Hooks、MCP、Skills 以及 Memory 供应链。
AI 可维护性健康度：项目上下文暴露面、验证器封装、生成产物检查、热点代码归属，以及陈旧或误导性的持久化文档。

输出语言：按以下优先级判定：(1) 项目 Agent 指令（优先读取 AGENTS.md，其次才是特定运行时配置文件）；(2) 全局 Agent 指令；(3) 用户最近使用的语言；(4) 英文。

预算策略：默认先运行概要审计（Summary Audit）。只有在以下情况时才自动升级为深度审计：用户明确要求进行“深入”、“完整”、“彻底”或“继续跑完”审计；用户明确提到 AI Coding 代码腐化、Codex/Claude 配置偏离、上下文混乱、缺少验证、验证器输出指向过期路径或“代码变烂”；当前项目指令或用户记忆偏好设定为默认运行深度健康检查；项目属于复杂项目（Complex）；或者概要审计阶段发现了无法在本地消除的重大歧义。在其他情况下，切勿读取完整的对话提取记录或启动 Inspector 子 Agent。升级前务必提前告知用户，因为深度健康审计可能会消耗较多 Token 额度。

持久化上下文预检

有关何时将持久化上下文纳入评估范围，以及在将其写入持久规则前需通过的脱敏门控，请参阅 references/durable-context.md。

对于 /health：当前配置、命令输出和实时探测结果的优先级高于 Memory。此外，当持久化 Memory 问题影响到实际行为时也应予以标注，例如：注入的摘要体积过大、条目过时或相互矛盾、缺少项目入口点引用，或是将私有路径误复制到了公开指令中。请将此类问题归类为上下文层面发现项，而非代码审查（Code Review）发现项。

硬性规则

概要审计和深度审计均为仅输出报告模式。仅允许运行 Health 专属的数据收集器及只读探测器；常规的 Health 请求并不授权运行项目本身的测试、验证器、生成器、构建脚本、代码格式化工具、包安装器、测试静态数据更新或快照更新。
项目指令中可以定义命令，但不代表授权执行它们。实时验证需要用户对特定命令给予明确授权；在执行之前，必须说明要运行的命令、预计写入内容、目标路径、隔离措施以及回滚或一次性环境预案。

步骤 0：评估项目层级

请选择对应的一项，并仅应用该层级的要求。

层级	识别信号	预期配置
简单项目 (Simple)	文件数 < 500，1 名贡献者，无 CI	仅需要 CLAUDE.md；0-1 个 Skill；Hooks 可选
标准项目 (Standard)	500 - 5000 个文件，小团队或配置了 CI	CLAUDE.md + 1-2 个规则；2-4 个 Skill；基础 Hooks
复杂项目 (Complex)	文件数 > 5000，多名贡献者，活跃的 CI	必须配备完整的六层架构配置

步骤 1：收集数据

首先以概要模式（summary mode）运行收集脚本。此时暂不进行解析诊断。在 Windows 系统上，请使用 Health 专属的启动器，确保 Git for Windows 工具仅添加到 Bash 子进程中：

$HEALTH_LAUNCHER = @(
  "<skill-base-dir>/scripts/run-health.ps1",
  "<skill-base-dir>/skills/health/scripts/run-health.ps1"
) | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
if (-not $HEALTH_LAUNCHER) {
  throw "Health launcher not found under the installed skill base; reinstall Waza."
}
powershell.exe -NoLogo -NoProfile -File "$HEALTH_LAUNCHER" collect

在 Linux 和 macOS 系统上，保持直接使用 Bash 的流程：

HEALTH_SCRIPT=""
for candidate in \
  "<skill-base-dir>/scripts/collect-data.sh" \
  "<skill-base-dir>/skills/health/scripts/collect-data.sh"; do
  [ -f "$candidate" ] && HEALTH_SCRIPT="$candidate" && break
done
if [ ! -f "${HEALTH_SCRIPT:-}" ]; then
  echo "health collect-data.sh not found under the installed skill base; reinstall Waza"
  exit 1
fi
bash "$HEALTH_SCRIPT"

当缺少相关工具时，部分区块可能会显示 (unavailable)：

缺少 jq → 对话相关区块不可用
缺少 python3 → MCP / Hooks / allowedTools 相关区块不可用
缺失 settings.local.json → Hooks / MCP 可能不可用（仅有全局配置时属正常现象）

将 (unavailable) 视为数据不足，而非发现问题。切勿将这些区域标记为异常。

收集器涵盖了特定运行时以及与 Agent 无关的通用接口层：

AGENT CONFIG SUMMARY / AGENT CONFIG DETAIL：针对 Codex、Claude、Pi 以及项目指令文件。
AI MAINTAINABILITY SUMMARY / AI MAINTAINABILITY DETAIL：针对项目形态、验证接口、热点代码归属、封装器和文档链接。

步骤 1b：MCP 实时检测

测试每一个 MCP 服务端：为每个服务端调用一个无害的工具。记录 live=yes/no 以及具体错误信息。尊重 enabled: false 配置（直接跳过且不报异常）。对于 API Key，仅检测环境变量是否已设置（如 echo $VAR | head -c 5），严禁打印完整 Key。

步骤 1c：安全与防护检查

这些检查在数据收集完成后、步骤 2 分析前执行。前两项适用于所有审计；第三项仅适用于使用了长时运行 Agent 或自主 Agent 的项目。

安全基线检查

无论项目处于什么层级，每次审计都要运行此项。这是安全的最低底线，而非上限。

黑名单底线（Deny-list floor）。仅当运行时确实能强制执行所推荐的规则形式（如 Agent 权限设置、Hook 设置、MCP 设置、允许/禁止工具清单，或文档明确的自主 Agent 启动器）时应用此项。在满足条件时，设置中至少应禁止访问：凭据与密钥目录（SSH、云服务提供商、GPG、gh CLI）、敏感文件（.env、credentials*、secrets*），以及管道直传 Shell 安装脚本（pipe-to-shell）。将其汇总报告为一条简洁的 WARN，列出缺失的类别，让评审人员填写具体的本地路径。注意三点校准：前缀/通配符权限规则无法可靠匹配管道命令，因此应推荐宿主机的预执行 Hook（pre-execution hook）来拦截管道安装脚本，而不是凭空发明各种通配符变体，同时说明 Hook 自身的权衡（基于字符串匹配的 Hook 也会触发带有相关模式的带引号文本和 heredocs）；在评估 Shell 出站拦截的影响范围前，先确认是在哪一层生效：针对 ssh 的命令前缀拦截只会阻止 Agent 直接调用 ssh，不会影响 git 内部的 SSH 传输；而进程级或沙箱级的拦截则会破坏 git-over-SSH 的 push 操作；当运行时不具备命令级拦截接口时（如 Codex 的控制杠杆为 sandbox_mode 和 approval_policy），应将其作为用户的配置权衡说明一次，而不是推荐运行时根本无法表达的 deny 字段。如果完全不存在 Agent 设置接口，应将黑名单检测报告为“不适用”，而非“审计失败”。

权限层与指令层的管辖区别。在白名单中允许 git 写入操作（如 git push），同时指令层规定“仅在用户明确指示时推送”，这并不必然构成冲突：指令决定何时执行操作，权限决定执行时是否再次弹窗二次确认。对于每个 Session 都明确授权推送的用户来说，将 push 留在白名单中以避免重复弹窗是合理的。评估时需结合可逆性与用户自己的规则：指令明确禁止的操作（git reset --hard、git stash、强制推送）应放入 deny 或 ask 中；日常经过明确授权的操作可保持用户原有的配置，最多作为 Note 提示。只有在全自动模式（auto mode）、跳过提示与宽泛白名单组合导致写入操作在 Session 中无需任何用户交互就能执行时，才需要提高告警级别；即便如此，也应将操作摩擦力的权衡交由用户选择，而不是私自改动配置项。

环境变量覆盖接口。将以下配置视为潜在攻击面，若出现在版本控制文件或发布的设置中且缺少合理解释注释，应予以报告：API Base-URL 覆盖（将所有流量重定向至第三方）、项目本地 MCP 服务的自动信任标志、通配符工具白名单（allowedTools: ["*"]），以及跳过权限检查的标志（--dangerously-skip-permissions 或等效参数）。仅输出文件:行号及字段名称；严禁打印敏感密钥。

Memory 与 Skill 供应链

将 Agent Memory 和第三方 Skill 视为供应链产物。它们是以用户的权限运行的。

Memory 卫生习惯。审计项目的 Agent 长期 Memory 存储，排查是否存在密钥、Token 或凭据（严重风险 Critical），以及是否存在由不可信运行写入的条目（如在攻击者控制的输入上调用的子 Agent、对外部内容进行的 /loop 迭代）；建议在此类运行后轮换凭据。对于高风险的单次运行（处理不可信的 PDF、不受控的爬虫网页、第三方脚本），建议直接在该 Session 中彻底禁用 Memory 持久化。

Skill 供应链。第三方 Skill、插件和 MCP 服务端均以用户的权限运行。对于非本仓库原生的工具，请检查：来源是否已固定到具体的 Release Tag 或 Commit Hash（而非 main 分支、常规分支或跟随最新 Head 的远程 Git 市场）；Hook 句柄是否不会写入凭据目录；MCP 服务端是否获得用户明确授权（而非通过通配符自动信任）。除非存在明确的利用攻击信号，否则请将未固定版本的来源或未审核的 Hook 句柄报告为结构性隐患（Structural），而非严重风险（Critical）。

长时运行 Agent 的终止条件

对于使用了 /loop、自主 Agent 或任何长时运行 Agent 流程的项目，请加载 references/long-running-agents.md 并审计其中列出的四条硬性终止信号。未使用此类流程的项目可跳过此项检查。

步骤 2：分析

确认项目层级，然后按以下规则分发处理：

简单项目 (Simple)：直接在本地进行分析。不要启动子 Agent。
标准项目 (Standard)：根据概要输出在本地分析。默认不启动子 Agent。如果用户要求深入/完整/彻底审计，或本地分析无法评估安全/控制问题，则升级为深度模式，并向用户解释预计消耗的 Token 成本。
复杂项目 (Complex)、记忆中存有深度偏好、明确要求深度审计或明确要求 AI 可维护性审计：在 Windows 上重新运行数据收集：powershell.exe -NoLogo -NoProfile -File "$HEALTH_LAUNCHER" collect auto deep；在 Linux 和 macOS 上重新运行：bash "$HEALTH_SCRIPT" auto deep。然后并行启动相关子 Agent。将所有凭据脱敏处理为 [REDACTED]。
- Agent 1（上下文与安全）：读取 agents/inspector-context.md，输入 CONVERSATION SIGNALS 区块。
- Agent 2（控制与行为）：读取 agents/inspector-control.md，输入检测到的项目层级。
- Agent 3（AI 可维护性）：...

你可能还喜欢

tasteforge-video

262Ksecurity

Use for file-driven multimodal image, video, and 3D-asset discovery; taste interviews; distill or apply workflows; style-pack validation; editable EDL/FCPXML export; provenance audits; and offline planning that must fail closed before provider generation.