1. 为什么 Agent 需要“验证技能”1.1 一个容易被忽视的环节最近在业务项目里使用 Agent 完成页面改版和接口调整时我发现一个很容易被忽略的环节Agent 能把需求变成代码也能把代码跑起来但“代码是否真的按预期工作”这件事往往缺少标准化的验证手段。传统做法是开发完成后由测试同学或者开发本人手动打开页面、点击按钮、查看接口返回值。但一旦 Agent 开始承担项目交付任务这种“人工回归”就变成了瓶颈。Agent 生成代码的速度越快验证代码的人力成本就越高。如果 Agent 改完代码后不能自行验证它就无法形成一个封闭的“执行—检查—反馈—修复”循环。这正是 pstack 新增“创建与维护验证技能”能力想要解决的问题让 Agent 通过一套可复用、可维护的验证技能像真实用户一样对应用进行访问、操作、断言和结果反馈最终把验证从“人工行为”变成“Agent 的标准化能力”。1.2 什么叫“验证技能”先解释一下“技能”这个概念。在 Agent 开发中技能Skill是一段结构化的指令、脚本和工具集合用来让 Agent 完成某一类特定任务。验证技能则是其中专门负责“校验应用状态”的一类技能。验证技能通常包括以下内容技能描述告诉 Agent 这个技能适合验证什么。输入参数需要外部传入的环境地址、账号、测试数据等。验证步骤Agent 按顺序执行的动作例如访问 URL、点击按钮、提交表单。断言规则判断操作结果是否符合预期的条件。输出格式Agent 最后提交给上层任务的结果通常是结构化 JSON。它和普通测试脚本的区别在于普通测试脚本是人写给人跑的验证技能是给 Agent 调用的。Agent 要先读懂技能描述再决定是否使用使用时要按步骤执行执行后要能解析结果并决定下一步是继续验证还是返回报告。1.3 pstack 新增能力概述pstack 新增的“创建与维护验证技能”能力核心价值有两个方向。第一是“创建”。用户可以在 pstack 中把常见的验证动作沉淀为技能。比如“登录验证技能”“订单流程验证技能”“接口响应验证技能”。创建完成后Agent 在后续任务中可以直接按名称调用不需要每次重复描述验证流程。第二是“维护”。应用页面结构、接口字段、环境地址是经常变化的。如果技能写死很快就失效。pstack 把技能做成可编辑、可版本化管理的能力支持修改脚本、更新描述、切换版本让验证技能能够跟着应用一起演进。下面我会从原理、环境准备、创建实战、运行验证、维护迭代和常见问题几个方面完整拆解这套验证技能的落地过程。2. 验证技能的核心组成与原理2.1 验证技能的组成部分一个可用的验证技能通常由五个部分组成。技能元信息元信息是 Agent 判断“该不该调用这个技能”的依据。它至少包含技能名称、描述、适用场景和输入参数说明。描述越清晰Agent 的匹配准确率越高。执行脚本执行脚本是技能的具体实现它可能是 Python、Shell、JavaScript 脚本也可能是一组 API 调用命令。脚本负责真正访问应用、操作页面、读取数据库或调用接口。指令模板指令模板是给 Agent 看的操作指南它描述“脚本应该怎么跑”“执行前后要注意什么”。有些技能不需要脚本指令模板本身就能引导 Agent 完成人工式验证。断言与退出条件验证技能必须明确什么情况算“通过”什么情况算“失败”。例如登录后是否出现用户昵称、接口返回码是否等于 200、数据库中是否出现新订单。断言条件决定了 Agent 能否正确判断结果。输出协议Agent 验证完以后要能拿到结构化结果。建议统一输出为 JSON包含 status、passed、failed、logs、error 等字段。这样上层 Agent 或流程引擎才能根据结果决定下一步动作。2.2 技能如何被 Agent 调用整个调用流程可以拆成四步。任务拆解。Agent 接到一个业务任务后先拆解任务步骤。如果包含“验证登录是否可用”“确认发布后的页面是否正常”这类子任务就会触发技能匹配。技能匹配。Agent 根据当前上下文和技能描述选择最合适的验证技能。这一步类似函数路由技能描述的质量直接影响匹配率。执行与感知。Agent 调用技能脚本传入必要参数观察脚本输出和日志。结果决策。Agent 读取输出 JSON判断验证是否通过。如果失败Agent 可以选择重新执行、修复代码后重试或直接向用户报告。这个流程决定了验证技能不是“写死的一段测试代码”而是 Agent 工作流中的一个可感知、可反馈的环节。2.3 Skill 与 MCP 的区别在 Agent 开发中经常有人把 Skill 和 MCP 混淆。结合当前 Agent 社区的高频讨论我整理了一个简单的对比表格。对比项Agent Skill技能MCP模型上下文协议本质指令 脚本 工具的封装一种让 Agent 调用外部工具的标准协议粒度面向任务场景例如“登录验证”面向工具能力例如“查询天气”“操作数据库”使用方式Agent 读取技能描述后按流程执行Agent 通过工具调用接口完成单个动作是否包含业务规则通常包含通常不包含典型示例验证订单流程是否正常获取某个订单列表的 API 工具验证技能和 MCP 是互补关系。一个验证技能内部完全可以借助 MCP 协议去调用浏览器自动化工具、数据库客户端或 HTTP 客户端。在 pstack 的实践里我会更建议把“稳定不变的工具访问能力”做成 MCP 服务把“面向业务场景的验证流程”做成技能。3. 环境准备与项目结构3.1 运行环境在开始创建验证技能之前需要先确认本机环境满足基本要求。以我当前的实践环境为例操作系统Windows 10 / macOS / Linux 均可本文示例以 Linux 为主Python 版本3.9 及以上本文示例使用 Python 3.10Node.js 版本如涉及前端调用可使用 Node.js 18pstack CLI建议安装最新稳定版本具体以官方发布为准可选依赖requests、playwright、pytest。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你的 pstack 版本较旧部分界面和命令可能存在差异建议先运行pstack version和pstack --help查看当前版本支持的命令。3.2 示例项目结构为了让验证技能便于管理和维护我建议采用下面的项目结构。verify-skill/ ├── SKILL.md # 技能描述文件Agent 首先读取的内容 ├── config/ │ └── settings.yaml # 环境配置、测试账号等 ├── scripts/ │ ├── verify_login.py # 核心验证脚本 │ └── common.py # 公共工具函数 ├── tests/ │ ├── test_login.py # 本地测试用例 │ └── test_helpers.py └── artifacts/ # 运行日志和报告存放目录其中核心是SKILL.md和scripts/目录。SKILL.md负责告诉 Agent“这个技能是做什么的、怎么调用”scripts/负责具体的验证动作。3.3 创建 pstack 技能入口pstack 一般提供两种创建技能的入口Web 控制台和 CLI。Web 控制台适合交互式创建你可以直接在界面里填写技能名称、描述、脚本内容和输入参数。CLI 更适合将技能纳入 Git 版本管理这也是我推荐的方式。# 进入技能项目目录 cd verify-skill # 在 pstack 中注册/导入技能 # 注意具体命令名称请以当前版本 pstack skill --help 为准 pstack skill import --path . --name login-verification导入后可以通过以下命令查看技能列表确认技能是否注册成功。pstack skill list执行结果中如果出现login-verification说明技能已经进入 Agent 可调用列表。4. 从零创建一个“登录验证技能”4.1 需求拆解我们以一个最常见的 Web 登录功能为例。目标是让 Agent 能自动验证“用户输入账号密码后能否正确登录系统”。拆解任务登录验证包含如下动作访问登录页面确认页面可以打开输入用户名和密码点击登录按钮判断是否跳转到首页并出现用户标识调用登录接口检查返回状态码和业务码汇总结果输出结构化报告。这个验证过程模拟真实用户操作又带有接口层的检查是我们编写验证技能的参考标准。4.2 编写技能描述文件 SKILL.md新建文件SKILL.md。这个文件是 Agent 理解技能的关键。描述要尽量清晰避免歧义。--- name: login-verification description: 用于验证 Web 应用的用户登录流程是否正常包括页面访问、表单提交、登录接口返回码校验。 input: base_url: type: string description: 被测应用的基础地址例如 https://demo.example.com required: true username: type: string description: 登录用户名允许从外部注入。 required: true password: type: string description: 登录密码建议使用环境变量或密钥注入。 required: true output: status: type: string description: 验证状态可选值为 passed / failed / error。 message: type: string description: 结果描述信息。 http_code: type: integer description: 登录接口 HTTP 状态码。 duration_ms: type: integer description: 整个验证流程耗时。 ---这里使用的是常见的 Markdown YAML front matter 格式和很多 Agent 技能规范兼容。pstack 也支持这种格式方便把技能从一个 Agent 平台迁移到另一个平台。4.3 编写验证脚本核心脚本需要做到两点能被 Agent 直接调用并且能把结果结构化输出。我使用 Python 来实现。主要依赖requests。如果你没有安装可以执行pip install requests下面是一个完整的登录接口验证脚本。为了便于理解我做了简化处理。# 文件路径scripts/verify_login.py import argparse import json import sys import time import requests def build_result(status, message, http_codeNone, duration_ms0): return { status: status, message: message, http_code: http_code, duration_ms: duration_ms, } def verify_login(base_url, username, password, timeout10): start time.time() login_url f{base_url}/api/login # 构造登录请求这里以 JSON 请求体为例。 payload { username: username, password: password, } try: response requests.post(login_url, jsonpayload, timeouttimeout) code response.status_code if code ! 200: duration_ms int((time.time() - start) * 1000) return build_result( statusfailed, messagefLogin API returned HTTP {code}, http_codecode, duration_msduration_ms, ) data response.json() # 假设登录成功的接口返回 token并且业务码为 0。 token data.get(data, {}).get(token) biz_code data.get(code) duration_ms int((time.time() - start) * 1000) if token and biz_code 0: return build_result( statuspassed, messageLogin successful, http_codecode, duration_msduration_ms, ) return build_result( statusfailed, messagefUnexpected business response: {json.dumps(data)}, http_codecode, duration_msduration_ms, ) except requests.exceptions.Timeout: duration_ms int((time.time() - start) * 1000) return build_result( statuserror, messagefRequest timeout after {timeout}s, duration_msduration_ms, ) except Exception as exc: duration_ms int((time.time() - start) * 1000) return build_result( statuserror, messagestr(exc), duration_msduration_ms, ) def main(): parser argparse.ArgumentParser(descriptionLogin verification skill script) parser.add_argument(--base-url, requiredTrue, helpTarget application base URL) parser.add_argument(--username, requiredTrue, helpLogin username) parser.add_argument(--password, requiredTrue, helpLogin password) args parser.parse_args() result verify_login(args.base_url, args.username, args.password) # 以 JSON 形式输出结果Agent 通过解析 stdout 获取验证结论。 print(json.dumps(result, ensure_asciiFalse)) sys.exit(0 if result[status] passed else 1) if __name__ __main__: main()脚本的核心逻辑是拼接接口地址提交账号密码判断 HTTP 状态码是否等于 200判断业务响应中是否有 token统一输出 JSON。注意最后一行的sys.exit。当验证通过时返回 0否则返回 1。这样 Agent 不仅能通过 stdout 解析结果还能感知命令的退出码。如果希望进一步模拟真实用户操作可以使用 Playwright 操作浏览器页面。下面是一个 UI 验证片段供参考# 文件路径scripts/ui_login.py核心片段 from playwright.sync_api import sync_playwright def ui_login(base_url, username, password): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page() page.goto(f{base_url}/login, timeout15000) page.fill(#username, username) page.fill(#password, password) page.click(#login-button) page.wait_for_url(**/dashboard, timeout10000) banner page.locator(.user-nickname).inner_text() browser.close() return { status: passed if banner else failed, message: fUI login result: {banner}, }实际项目中接口验证和 UI 验证最好结合使用。接口验证速度快、稳定性高适合快速回归UI 验证更接近真实用户行为适合发布前验收。4.4 声明技能参数与校验规则在上面的SKILL.md中我们已经声明了base_url、username、password三个参数。为了让 Agent 调用时不会传错值可以在描述中增加约束例如input: base_url: type: string description: 被测应用的基础地址必须以 http:// 或 https:// 开头。 required: true example: https://demo.example.com加入example字段能让 Agent 更清楚参数格式。不同平台支持的字段不同建议先查看 pstack 的技能 schema 说明。4.5 把技能注册到 pstack技能目录准备好后使用 pstack CLI 注册。cd verify-skill pstack skill import --path . --name login-verification注册成功后可以在 Agent 配置中为该技能添加执行权限例如允许哪些 Agent、哪些环境下调用。权限控制很重要尤其是技能脚本需要访问数据库或生产环境时必须限制执行范围。5. 运行 Agent 并验证应用5.1 使用 Agent 执行验证技能注册完成后可以在一个 Agent 任务中主动调用它。假设现在要验证测试环境的登录功能Agent 收到的任务可以是请使用 login-verification 技能对测试环境做一次登录验证。 环境地址为 https://demo.example.com测试账号由配置中心提供。 验证完成后输出一份简洁的验证报告。Agent 收到任务后会读取SKILL.md确定调用scripts/verify_login.py并注入参数。在 pstack 的日志中可以看到类似下面的执行记录。[Agent] 已匹配技能login-verification [Agent] 参数解析完成 base_url https://demo.example.com username test_user [Agent] 执行脚本python scripts/verify_login.py --base-url https://demo.example.com --username test_user --password ***** [Agent] 脚本退出码0 [Agent] 输出{status: passed, message: Login successful, http_code: 200, duration_ms: 356}5.2 观察执行日志如果验证失败日志会呈现另一种形态。比如接口返回 401输出如下[Agent] 脚本退出码1 [Agent] 输出{status: failed, message: Login API returned HTTP 401, http_code: 401, duration_ms: 312} [Agent] 尝试重新执行否当前环境未配置自动重试。 [Agent] 向流程引擎返回失败原因。从日志中可以看到Agent 根据输出statusfailed判断验证不通过不再继续后续依赖登录状态的任务。这种“可感知”的能力正是验证技能的核心价值。5.3 结果说明当status为passed时Agent 可以继续后续操作例如发布完成后的自动化回归当status为failed或error时Agent 应该停止或转入人工处理流程。为了保证结果可比建议在技能中定义统一的结果结构。例如{ status: passed, message: Login successful, http_code: 200, duration_ms: 356 }status建议只保留passed、failed、error三种取值。error表示脚本本身执行异常而不是业务未通过。区分这两者能帮助上层流程准确定位问题。6. 技能的维护与迭代6.1 什么时候需要维护技能验证技能不是创建完就能一直用。以下场景出现时必须考虑维护。页面 DOM 结构调整之前定位的按钮选择器失效。接口字段变更返回体中的 token 字段改名。接口地址变更/api/login被调整为/api/auth/login。环境地址变化测试环境域名改变。断言规则不合理验证过严导致频繁误报或过松导致漏报。在这些情况下如果不及时更新技能Agent 的验证结果会逐渐失真最终导致“看起来在验证实际没有真正覆盖”。6.2 维护流程推荐按下面几步维护技能。修改脚本。先在本地更新scripts/verify_login.py确保新逻辑符合当前应用。本地运行。使用测试环境参数执行脚本确认输出正确。更新描述。如果输入参数、输出字段发生变化同步更新SKILL.md。版本号递增。在SKILL.md的 front matter 中维护版本号例如从1.0.0改为1.1.0。重新导入。在 pstack 中重新执行导入命令或通过控制台上传新版本。pstack skill import --path . --name login-verification --version 1.1.0更新完成后可以在技能列表中看到新版本。6.3 灰度与回滚生产环境中的技能更新需要更谨慎。建议先在测试环境跑通新版本再对灰度环境执行一轮真实 Agent 任务。如果发现问题可以通过 pstack 的技能版本切换功能回滚到上一个稳定版本。假设回滚到 1.0.0pstack skill switch --name login-verification --version 1.0.0需要注意技能回滚只影响后续的 Agent 调用已经运行中的任务不会中断。操作前建议先确认没有正在执行的关键任务。7. 常见问题与排查思路在实践过程中我遇到过不少问题。下面整理成表格方便检索。问题现象常见原因解决思路Agent 无法匹配到验证技能技能描述太泛或者参数说明不清晰细化 description标注适用场景和关键字技能调用后长时间没有输出脚本等待响应时间过长网络不通设置请求超时增加执行日志观察脚本是否卡在goto或wait_for验证结果与人工测试不一致断言条件过于简单只判断了 HTTP 200增加业务字段断言如 token、用户昵称、页面元素执行环境缺少依赖包技能运行容器未安装 requests/playwright在技能描述中声明依赖或为技能绑定独立运行环境脚本报权限错误技能执行账号权限过大或过小检查 pstack 执行角色的权限配置遵循最小权限原则Agent 返回 “the agent execution provider did not respond in time”执行服务响应超时常见于脚本阻塞或并发过高检查脚本耗时拆分长任务缩短单次技能执行时间并增加 provider 超时时间最后一个问题值得多说几句。Agent 执行超时表面上看起来是平台配置问题但根因往往出在技能脚本本身。脚本如果里面有重试循环、长时间轮询或者未设置超时的等待逻辑就会拖垮整个 Agent 执行链路。我的经验是验证技能里所有网络请求必须显式设置 timeout并且尽量控制在 10 到 30 秒内完成。8. 最佳实践与工程建议8.1 技能原子化一个技能只做一类验证不要做成“万能验证器”。命名也建议遵循“行为 对象”的规则例如login-verification、order-list-verification、payment-callback-verification。技能越单一Agent 越容易匹配维护成本也越低。8.2 输入输出规范化输入参数可以统一使用 JSON 或 YAML输出统一使用 JSON。不要把“结果”散落在脚本日志里否则 Agent 很难解析。建议所有脚本都实现--output-json这类参数方便控制台调用和 Agent 调用共用一份逻辑。8.3 可观测性技能运行期间要输出关键节点日志例如已经访问的 URL等待了哪个元素接口返回的状态码断言命中的字段。这样即使 Agent 判断错误人工排查时也能快速定位。不要把日志堆在脚本内部不输出否则 Agent 拿到一个空结果无法解释失败原因。8.4 安全边界验证技能经常需要连接测试账号、数据库、内部系统。必须注意以下几点绝不把明文密码写入技能描述或代码仓库优先使用环境变量、密钥管理服务和 pstack 的密钥注入能力生产环境验证要严格授权验证脚本只做只读操作不新增、不修改、不删除业务数据数据库操作使用只读账号并限制 IP 白名单涉及生产环境的技能发布必须走审批流程。8.5 幂等与清理验证脚本要能重复执行并且不会因为上一次运行残留数据而失败。例如登录验证会创建测试用户脚本结束前需要清理该用户或者每次使用随机用户名。否则第二次运行时可能因为用户已存在而误报。8.6 版本管理把整个技能目录纳入 Git 仓库使用标准语义化版本号。每次变更都提交一次 commit并在SKILL.md中同步版本号。这样技能的演进历史会非常清晰。9. 总结与学习路线通过这一篇我们完整拆解了 pstack 新增“创建与维护验证技能”能力背后的核心原理和落地方法。从理解验证技能的组成、搭建项目结构到实际创建登录验证技能、运行 Agent 任务再到维护迭代和排查常见问题整个过程已经形成一条可复用的链路。接下来如果你希望继续深入 Agent 开发建议按以下路线拓展。学习 Agent Skill 与 MCP 的配合使用把通用工具能力沉淀为 MCP 服务把业务验证流程沉淀为技能掌握多 Agent 协作模式比如主 Agent 负责任务编排验证 Agent 作为子 Agent 专门执行验证技能深入 Agent 记忆机制让技能执行结果沉淀为长期记忆避免每次任务重复验证关注 Agent 安全和权限治理特别是在技能中引入生产环境操作时。最后分享一个实现细节不要在技能脚本里硬编码任何环境地址和密钥。所有环境相关参数都通过 pstack 的输入参数注入这样同一份技能才能在测试环境、灰度环境和生产环境之间安全复用。如果你在接入验证技能时遇到其他问题欢迎在评论区留下你的报错信息我会把典型问题补充到文章里。