Waza：八个 Agent Skills 的工程习惯、源码原理与使用方式

Waza 源码仓库

AI 参与说明（Agent：Codex）：本文依据公开 README、Skill 指令与辅助脚本协助调研、撰写和验证，核验于 2026-10-17，固定版本 3.40.0、提交 2585ee0。使用项目 research、Anatomy、find-docs 与 humanizer-zh；交互图是依据真实函数重建的教学模型，装置外观由本文设计。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop；其他运行参数未取得任务级记录。本文未把 Waza 安装进个人 Agent 配置。

Waza 把八种工程习惯包装成 Coding Agent 可以按需读取的 Skills：动手前推敲问题，出现异常时验证根因，交付前审查真实改动，写作时保留信息并改善表达。它适合已经在用 Claude Code、Codex 或 Cursor，希望让 Agent 的做事顺序与验收依据更明确的人。

它的实现很直接：Markdown 承载需要判断的工作约定，Bash / Python 承担可重复的采证与校验，宿主 Agent 提供模型、工具与权限。项目没有自己的模型推理服务、任务调度服务器或应用数据库。package.json 主要描述 npm / Pi 分发，不能把 npm install 理解成启动一套独立 Agent 系统。包元数据、Skill 与 Script 的分工

我的判断是：先试 /hunt 与 /check 最容易看出它的价值。 两者直接针对“没有证据就修”和“测试绿了就宣布交付”这类常见失误。其余 Skills 按任务补充；有成熟项目指令与同类 Skills 时，应先检查重叠，再决定采用哪套约定。

阅读前的术语参考

八个 Skills，分别从哪里进入

下表描述的是固定提交中各 Skill 的指令职责。部分任务可以调用辅助脚本，涉及方案取舍、根因判断和审查结论的部分仍由 Agent 完成。

不要只凭“检查一下”选 Skill。程序抛异常适合 /hunt；有可审查 diff 适合 /check；Agent 不读指令、MCP 失灵或验证器输出失真适合 /health。skills/RESOLVER.md 集中记录这些歧义，但它是给人和验证脚本读取的路由索引，不是运行时调度程序。Resolver

运行架构：谁在解释指令，谁在执行程序

Waza supplies instructions and evidence helpers. The host agent supplies the model, tools, permissions, and execution loop.

安装后，宿主发现 Skill 的名称和用途。用户显式调用，或宿主依据描述匹配任务，再读取完整 SKILL.md。Skill 引用的模式、参考资料与专项 reviewer 随任务加载；它们不会因为目录存在就全部执行。最终读文件、调用工具、运行测试和作判断的主体仍是宿主 Agent。Skill 元数据、专项审查入口

flowchart TD
  U[用户请求与现有授权] --> H[宿主 Agent 发现并选择 Skill]
  H --> S[读取 SKILL.md 与 Outcome Contract]
  S --> C[读取当前 Project Context]
  C --> J[Agent 判断任务路径]
  J --> R[按需读取 references 与 reviewer 指令]
  J --> T[调用宿主工具与辅助 scripts]
  R --> E[Agent 汇总证据并核对结果约定]
  T --> E
  E --> O[交付计划、诊断、findings 或成稿]
  E --> A{是否已授权后续动作}
  A -->|已授权且前提满足| W[执行对应修复或发布并核验]
  A -->|尚未授权| B[停在请求的交付边界]

这里有三层需要分清：

• Skill 指令决定 Agent 应怎样思考、何时停下、以什么证据报告完成。它依赖模型遵循指令。
• 脚本确定性地收集和变换输入，如读取 manifest、比较版本、检查文档链接；脚本输出本身也有适用范围。
• 宿主权限机制决定某个工具动作是否能执行。Markdown 中的“禁止”不能替代 sandbox、工具权限或服务端鉴权。

因此，安装 Waza 并不会增加缺失的浏览器、GitHub 权限、MCP 连接或语言运行时；也不能保证模型每次都遵循所有规则。项目自己的权限边界仍需由宿主和实际服务执行。

代码组织与核心数据模型

这个项目的数据模型主要是文件约定与结构化证据，并没有业务数据库实体。

元数据生成器、版本证据模型、审计信号

plugins/waza/skills/ 看起来与 skills/ 重复，实际是 Codex plugin 的 generated mirror。上游把 VERSION 与源 Skill 元数据作为来源，生成不同渠道的 manifest 和镜像，再用 build_metadata.py --check 比对已提交字节。维护时应修改源文件并重新生成；直接改镜像会产生漂移。

flowchart TD
  V[VERSION] --> G[build_metadata.py]
  S[skills 的 front matter 与资源] --> G
  R[rules 与共享参考资料] --> G
  G --> C[Claude marketplace]
  G --> X[Codex marketplace、plugin 与 generated mirror]
  G --> P[package.json 与 Pi 分发信息]
  G --> D[共享参考资料副本与安装脚本版本]
  C --> K[check 模式核对生成字节]
  X --> K
  P --> K
  D --> K

沿一次真实请求理解 /check

假设用户说：“检查这个版本是否可以发布，只报告问题。”这是本文构造的输入场景，下面的模式与函数来自固定源码。

1. Agent 读取 skills/check/SKILL.md，先检查工作区，保留用户的 modified、staged 和 untracked 文件。
2. 它从 diff、README、manifest、CI 与发布文档提取 Project Context，确定项目真正要求的验证和产物。
3. 发布就绪问题进入 references/mode-ship.md。Release Gate 2.0 要求核对审查基线、工作区、tag、origin、版本字段、生成文件、包内容、release assets、registry / appcast / CI 等适用证据。
4. Agent 可运行 release_gate.py --root <项目> 采集其中的本地确定性信号。脚本的入口 main() 依次调用 worktree_state()、remote_sync()、tag_baseline()、version_sync()、changelog_mentions()；无 Git 仓库时相应 Git 项标为 N/A。
5. Agent 读取脚本状态，并补查脚本不覆盖的远端与产物事实，形成有依据的判断。本场景只有审查授权，所以交付 findings，不执行发布。

check 公共流程、Ship 模式、main 与各检查函数

这里没有一个“调用 /check，Python 自动调用所有 reviewer 并发布”的程序调用链。上面第 1–3、5 步由 Agent 解释指令组织；第 4 步才是实际的脚本函数调用。

版本字段怎样变成状态

version_sync() 位于 Release Gate 的本地证据环节。输入是仓库里的 VERSION、package.json、Cargo.toml、pyproject.toml 版本，以及从当前 HEAD 可达的稳定 tag；输出是 VERSION FIELD SYNC 证据块和一个统一版本值。后者继续用于 changelog 检查。

它按以下规则处理：

1. repo_file() 与 read_repo_text() 检查仓库输入，拒绝符号链接、越界或超出读取上限的文件；collect_versions() 从支持的文件中取版本字段。
2. 字段的 v / V 前缀被移除，组成一个集合。集合不止一个值表示版本冲突，得到 FAIL；解析失败、不安全输入或受限字符等问题也会得到 FAIL。
3. 字段统一后，parse_semver() 检查精确版本格式，拆出三位 core 与 prerelease。它接受 build metadata，但解析返回值不包含 build metadata。
4. prerelease 在此前没有失败时得到 WARN。与稳定 tag 比较时，版本回退得到 FAIL；core 高于 tag 会提示尚未发布的版本，但这个检查仍可为 PASS。
5. 未找到支持的版本字段，且没有读取错误时为 N/A。没有 tag 不会单独使本项变成 WARN；tag 的缺失由另一个证据块说明。

特别容易看错的是 build metadata：字段集合仍保留 +build.1 这样的后缀，所以 3.40.0+build.1 与 3.40.0+build.2 会冲突；但单一版本与 tag 的解析比较忽略该后缀。两处比较用途不同，不能统一理解成“所有后缀都被忽略”。collect_versions 与 version_sync 源码

亲自改变字段，预测结果

下面解剖的是真实 version_sync() 的版本转换与比较规则。多通道比较仪是视觉比喻；字段、归一化结果和状态来自同一个教学模型。它不访问你的仓库，也不调用模型或发布服务。文件安全检查、Git 状态及整个 Release Gate 的其他项目在图外，仍需分别核验。

本次将控件可达的 6,912 组字段与 Tag 输入逐一交给固定版本的 Python version_sync() 对照，教学模型的状态及统一版本返回值全部一致；另以实际文件 fixture 核对采集入口。此结果覆盖图中可选输入，不扩展为整个 Release Gate 或真实发布流程的验证。

先观察 VERSION=v3.40.0 与 manifest 的 3.40.0 如何在去掉前缀后对齐。再把一个字段改成 3.41.0：冲突发生在字段统一阶段，不能因为其中某个值高于 tag 就通过。最后统一到 3.41.0-rc.1，观察字段一致、格式有效与稳定发布之间的区别。

A successful script run is not a successful release check. release_gate.py 发现 WARN 或 FAIL 时仍返回退出码 0，以区分“成功报告问题”和“脚本本身运行失败”。调用方必须读取各证据块的 status。另外 REMOTE SYNC 即使本地 tracking ref 与 HEAD 相同，仍为 WARN，因为脚本不联网，无法证明远端已经被最新核验。脚本说明与 remote_sync

/hunt 为什么值得单独试

/hunt 的核心没有独立诊断引擎。它把诊断过程写成 Agent 必须满足的证据约定：先提出能解释全部症状的具体假设，再运行一个能够推翻该假设的探针；证据不支持就丢弃假设，不能继续在它上面堆修复。

它要求的 Runtime Evidence Ladder 包括 source trace、deterministic repro、运行日志与状态、相关 build / test，以及适用时真实运行界面的核验。对于页面和生成物，编译通过不能替代打开产物检查。修复一个模式后还要求检查同类位置；连续三次假设失败则输出已排除项和待补证据，停止猜修。诊断、证据阶梯与停止条件

可以给它一条有边界的任务，而不是只说“修一下”：

Use the hunt skill to diagnose this regression.
Expected: changing the selected account reloads its orders.
Observed: the previous account's orders remain until a full refresh.
Reproduce it, identify a falsifiable root-cause hypothesis,
and report the evidence before editing files.

如果目标已经明确包含修复，可以在同一请求中授权“定位根因后实施最小修复，并验证该回归及相关路径”。上游当前规则保留同一未完成任务中仍有效的授权，不要求每次 Skill 内部交接都重复确认；提交、推送和发布仍需要各自的授权范围。hunt Outcome Contract、技能串联规则

安装与第一次使用

以下命令按固定提交的上游说明整理；宿主插件命令随客户端版本变化，执行前应核对当前宿主是否提供对应入口。本次分析在临时源码检出与隔离 HOME 中运行检查，未安装进个人 Agent 目录或修改个人规则。

直接安装 Skills

上游给 Claude Code、Codex、Cursor 的通用命令是：

npx skills add tw93/Waza -a claude-code codex cursor -g -y

这是下载安装命令，要求 Node.js / npm 与网络。-a 选择目标 Agent，-g 为全局安装，-y 跳过交互选择。只使用某个宿主时，可以只保留相应 Agent ID。上游说明技能放入共享 ~/.agents/skills，其他宿主目录按安装器规则接入；安装完成后应检查宿主实际发现了什么，而不是仅凭安装命令成功判断生效。安装说明、安装端到端测试

# 上游的全局更新命令，会处理全局已安装 Skills
npx skills update -g -y

# 移除通过该安装器安装的 Waza Skills
npx skills remove tw93/Waza -g

需要注意 check、read、write 这类名称很通用。已有同名 Skill 时，先核对安装器的替换提示与最终加载来源；希望保留命名空间时可以考虑宿主插件渠道。

使用宿主插件渠道

Claude Code 的交互命令：

/plugin marketplace add tw93/Waza
/plugin install waza@waza

固定版本 README 给 Codex CLI 的命令：

codex plugin marketplace add tw93/Waza
codex plugin add waza@waza

插件方式使用 /waza:check 这样的命名空间。Claude Code 更新命令为 claude plugin update waza；Codex 的上游说明要求先 codex plugin marketplace upgrade waza，再 codex plugin add waza@waza。这条路径与 direct Skills 安装分开管理，选一条满足需求的渠道即可。固定版安装与更新说明、Codex manifest

另有两条渠道：Claude Desktop 上传 release 的 waza.zip 到 Skills；Pi 使用 pi install npm:@tw93/waza，更新为 pi update npm:@tw93/waza。Desktop ZIP 通过生成的 dispatcher 承接八种意图，并不表示它拥有与终端宿主完全相同的工具环境。Desktop dispatcher、Pi 包元数据

怎样确认真的用上了

在 Claude Code 中显式调用已安装的斜杠命令；Codex 按技能名调用，并要求它先读取对应文件。例如：

Use the check skill to review the current diff.
Read the installed SKILL.md first.
Follow this repository's verification commands.
Report actionable findings with file and line evidence.
Do not edit files or publish anything.

观察三项结果：Agent 是否读取正确 Skill；是否使用当前仓库的真实 diff 和验证命令；报告是否含本轮取得的证据。八个 Skills 都约定首行内联 🥷，但这个符号只说明输出形式符合约定，不能证明审查或验证真的发生。

完整任务也可以一次说明：先 /think 形成方案，再在已有实现授权内完成代码，最后 /check 核验。上游把 Skill 边界用于分工，并不把同一请求已经授权的多个阶段强制拆成多次确认。Resolver 串联约定

读取、配置审计与附加规则的实际边界

/read 的平台路由与抓取脚本不同

SKILL.md 告诉 Agent 根据输入选择 GitHub raw / gh、PDF、飞书、微信或通用网页路径；这一步由 Agent 判断。fetch.sh 负责通用抽取的分层尝试，本身没有实现所有平台的统一路由。

# 在源码检出根目录执行，仅请求公开来源
bash skills/read/scripts/fetch.sh https://example.com/

默认先运行 fetch_local.py：请求源站，在本地抽取正文；有 readability-lxml 与 html2text 时使用它们，否则退回标准库抽取。缺少依赖可能影响提取质量，不能把输出的登录页或空壳当正文。

显式加入 --use-proxy 后，本地失败才依次尝试 defuddle.md 与 r.jina.ai。这些服务会收到 URL，Skill 要求公开 URL 也须用户选择使用该回退，禁止把敏感 URL 发给第三方。这个开关不是普通网络代理开关。fetch.sh、read 的隐私边界

还有一个代码层面的细节：fetch_local.py 使用 ProxyHandler({})，不继承环境中的 HTTP 代理。fetch.sh 的第二个位置参数 proxy_url 用于后续 curl 层，不会自动作用于本地抽取器。网络环境需要代理时，应先确认实际经过哪一层。本地请求实现

/health 从轻量证据开始

health 将 Agent config health 与 AI maintainability health 放在同一报告里：前者检查配置、指令、hooks、MCP、Skills 和记忆供应链，后者检查约束能否到达执行位置、风险热点、验证覆盖和失真的文档。

其 collect-data.sh 组织采集，check_agent_context.py、check_maintainability.py、conversation_audit.py 等负责具体信号。默认从 summary 开始，再按用户要求和审计条件决定是否升级 deep。auto summary 从当前项目的候选日志中选择最近至多三个旧会话，deep 扩大旧会话信号扫描范围；instructions 范围跳过历史会话。脚本按最近修改时间排除可能仍活跃的日志，这是启发式判断。采集会接触本地配置与会话信息，即使输出已有脱敏，分享前仍应检查。health Skill、collector

历史会话分析有明确的数据转换：ConversationFile 保存文件与运行时信息，Message 将不同宿主的消息归一化为 role、text、ordinal，Signal 表示识别出的指令纠正、上下文或交付提醒等线索，ScanStats 记录实际覆盖与解析错误。audit() 发现当前项目日志、排除活跃项、按 summary / deep 选择范围，再扫描、去重、脱敏并生成有界报告。它提取的是审计线索，不能把每条提醒直接当作当前 Agent 的已证实缺陷。数据类型、audit 实现

“缺少数据”和“已发现问题”也分开处理：unavailable 不应自动成为 finding；配置文件里写了 MCP，不等于服务器已连接并能调用；脚本采集成功，也不等于实际宿主已执行这些指令。

Optional Rules 与 statusline 单独生效

安装八个 Skills 不会自动启用长期规则。setup-rule.sh 可安装 english、anti-patterns、waza-routing、clarity 等规则；Codex 目标写入 ~/.codex/AGENTS.md 的标记块，其他支持的宿主使用相应规则文件。它们会影响后续会话，卸载 Skills 后也需要另外移除。规则安装器

setup-statusline.sh 是 Claude Code 的附加工具，可能修改 settings，并在缺少 jq 时尝试安装依赖。需要状态栏再单独阅读和执行，不必为了使用 /hunt 一并安装。Codex 的原生状态栏配置是另一条路径，不能将两者的用量语义混用。状态栏安装器

验证能证明什么

仓库的 make test 会校验 Skill 文档、生成元数据、路由漂移、Bash / Python 语法、health 采集与各专项 smoke tests。有 pytest 时还运行 Python unit tests，有 shellcheck 时增加 shell 静态检查。这些条件分支需要看清，不能把跳过项算作已通过。Makefile

本次在固定提交、临时 HOME 与独立 Python 环境中实际执行了以下验证：

环境未安装 shellcheck，该项没有执行；Claude / Codex plugin 更新、Pi 实际运行与 Desktop 上传也未实测。此处将实际执行结果与安装说明分开记录，避免把脚本 smoke 解释成所有宿主都已验收。

另一处需要读源码的是 skills/check/scripts/run-tests.sh。它按 Cargo.toml、tsconfig.json、package.json、Makefile、Python 线索的顺序选择一条默认路径。例如命中 tsconfig.json 就运行 npx tsc --noEmit && npm test，不会继续自动执行仓库所有 lint、build 或其他包管理器命令。/check 自己要求优先采用 Project Context 指定的验证方式，因此这个脚本适合作为回退，不能覆盖项目的实际发布流程。测试回退脚本

行为契约测试可发现某条文档约束被删掉、生成文件不一致或脚本处理输入错误。它们并不等于跨模型的真实任务效果评估；例如检查文档仍含根因要求，不能证明模型在一次复杂回归里真的找到了根因。选用时应拿同一任务、同一环境对比输出，记录错误判断、漏项和实际完成证据。行为契约测试

选用建议

Waza 的长处在于把“认真做事”写得具体：什么输入进入哪种工作方式、什么证据才支持结论、哪些后续动作仍需对应授权。分发侧也用同一来源生成多渠道产物，避免把几份 Skill 副本手工维护成不同版本。项目采用 MIT License。LICENSE

如果经常遇到 Agent 猜修、漏看真实页面、审查脱离项目命令，可以先拿 /hunt 与 /check 各试一个具体任务，以能否交付可复核证据验收。需要持续调研、写作或界面工作时，再加入对应 Skill。

如果期望独立运行的 Agent 平台、完整自动发布流水线或强制权限隔离，需要另行提供实际运行系统。Waza 能帮助 Agent 遵循已有流程，不能替代项目测试、真实运行环境和服务端权限控制。

关联阅读

• Skills Overview：站内 Skills 选型与工作流资料。
• Taste Skill：从设计规则到方向抽样与浏览器检查：另一种将判断、数据与脚本分开的 Skill 设计。
• 上游固定版本完整源码：复核本文的文件、规则与函数。