尧图网站建设 
Skyvern 仓库的 AI Agent 协作开发指南从 AGENTS.md 解读项目结构与代码质量体系【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 是一个使用 LLM 与计算机视觉自动化浏览器工作流的开源项目。本文以仓库根目录的 AGENTS.md 为主线系统解读 AI Agent以及人类开发者在 Skyvern 代码库中协作时的项目导航方法、编码规范、PR 提交流程与质量检查体系并结合仓库内的实际源码、配置文件与测试目录给出可验证的实现依据。读完本文你将掌握如何在 Skyvern 仓库中快速定位模块、遵循统一的代码风格提交变更并通过 pre-commit 与类型检查工具链保证贡献质量。一、项目结构Agent 导航 Skyvern 代码库的起点AGENTS.md 将仓库组织为若干顶层目录这与仓库实际布局一一对应。核心 Python 包位于 skyvern/ 目录包含以下子模块目录职责仓库佐证skyvern/cli/命令行接口组件含run_commands.py、workflow.py、quickstart.py等命令实现skyvern/client/客户端实现与集成含生成的 Python 客户端 SDKraw_client.py、client.pyskyvern/forge/核心自动化逻辑与工作流含agent.py、agent_functions.py、FastAPI 应用与 SDK 层skyvern/library/共享工具与对外 SDK 封装含公开的Skyvern类与页面/浏览器/locator 包装器skyvern/schemas/数据模型与校验模式基于 pydantic 的请求/响应模型skyvern/services/业务逻辑与服务层任务、工作流、浏览器会话等业务编排skyvern/utils/通用工具函数日志脱敏、action 序列化等公共工具skyvern/webeye/Web 交互与浏览器自动化Playwright 驱动的 DOM 抓取与动作执行除主包外仓库还包含skyvern-frontend/React 前端应用负责任务管理与监控、integrations/第三方服务集成如 Make、n8n、MCP、alembic/数据库迁移脚本、scripts/工具与部署脚本、tests/单元测试、SDK 测试与冒烟测试。从源码结构看Skyvern 的运行时依赖被拆分为local与server两组可选依赖见 pyproject.tomlserver是local的超集额外包含 uvicorn、psycopgPostgreSQL 驱动等后端组件。因此Agent 在定位某个功能时应先判断其属于 CLI、浏览器引擎webeye、核心自动化forge还是业务服务services层再深入对应目录。二、编码规范Python 标准与代码风格约定AGENTS.md 对 Python 代码提出了明确要求这些约定与仓库的工具链配置相互印证Python 版本与类型注解要求使用 Python 3.11 特性并编写类型注解。pyproject.toml 中requires-python 3.11,3.15与之完全一致仓库还通过 pre-commit 钩子强制校验 Python 版本在 3.11–3.13 范围内见 .pre-commit-config.yaml 中的check-python-version。行宽 100 字符与命名风格遵循 PEP 8行宽 100 字符变量与函数使用snake_case类使用PascalCase。绝对导入所有模块使用绝对导入避免相对导入造成的可读性与重构问题。Google 风格 docstring所有公开函数与类需要编写文档字符串便于生成 API 文档与让 LLM 理解模块意图。仓库代码是这些约定的直接体现例如 skyvern/errors/errors.py 中的UserDefinedError使用 pydanticBaseModel、StrEnum与field_validator注释详细说明了错误码与推理文本的截断策略——这正是类型注解 详尽文档的典型样例。异步编程约定Skyvern 是一个高并发浏览器自动化平台AGENTS.md 明确要求优先使用async/await而非回调使用asyncio处理并发异步代码必须处理异常使用上下文管理器context manager进行资源清理。从仓库看核心运行时代码如 skyvern/forge/agent.py、webeye 浏览器模块均采用 async 风格编写且 pyproject.toml 的依赖中包含aiohttp、asyncssh、aiofiles、aiosqlite、aioboto3等一整套异步生态库印证了全栈异步的实现路线。三、错误处理与日志安全异常体系与敏感信息脱敏AGENTS.md 对错误处理的要求是使用具体异常类、携带有意义的错误消息、按严重级别记录日志、绝不在错误消息中暴露敏感信息。仓库在这三方面都有落地实现异常体系skyvern/errors/errors.py 定义了ErrorTypeUSER_DEFINED_ERROR/SYSTEM_DEFINED_ERROR与UserDefinedError模型其中confidence_float通过 pydantic 约束在 0–1 之间reasoning字段则由验证器按ERROR_CODE_REASONING_MAX_LENGTH截断——保证 LLM 生成的错误说明不会因过长而丢失错误码。日志脱敏AGENTS.md 强调不在错误消息中暴露敏感信息仓库在 skyvern/forge/log_redaction.py 中实现了完整的字段级脱敏机制SENSITIVE_HEADERS与SENSITIVE_FIELDS定义了全量敏感名称集合authorization、cookie、x-api-key、password、secret、token、api_key、credential、totp、otp、verification_code 等采用精确匹配而非子串匹配避免误伤credential_id、author、page_token这类仅包含敏感子串但并非密钥的字段对字符串内嵌的 Bearer 凭证如?tokenBearer%20jwt、Authorization: Bearer token进行正则替换为redacted对签名制品 URL/v1/artifacts/.../content?带 query剥离能力参数递归遍历 dict/list/BaseModel 结构深度上限 20 层并对循环引用输出circular防止指数级展开。这套脱敏逻辑被请求日志中间件与 structlog 处理器共用是绝不暴露敏感信息这条规范在源码层的直接证据。相关测试见 tests/unit/forge/sdk/artifact/test_secret_artifact_redaction.py。四、Pull Request 流程分支命名、PR 指南与提交信息格式AGENTS.md 规定了完整的提交流程Agent 与开发者都应遵守1. 分支命名新功能feature/descriptive-name缺陷修复fix/issue-description维护任务chore/task-description2. PR 指南使用Fixes #123或Closes #123关联 issue提交清晰的变更描述同步更新相关文档确保所有测试通过合并前至少获得一个评审批准。3. 提交信息格式[Component] Action: Brief description More detailed explanation if needed. - Bullet points for additional context - Reference issues with #123该格式将变更收敛到具体组件如[Agent]、[Webeye]、[CLI]便于维护者与 Agent 快速定位变更影响面。五、代码质量检查pre-commit 钩子链与静态分析AGENTS.md 要求提交代码前运行pre-commit run --all-files仓库的 .pre-commit-config.yaml 是这一要求的完整落地钩子链覆盖了 Python 与前端两侧钩子作用pre-commit-hooks官方集合大文件检查15MB 上限、BOM/大小写冲突/合并冲突/符号链接检查、debug-statements、私钥检测check-python-version强制 Python 版本在 3.11–3.13ruffruff-formatPython lint 与格式化自动--fix排除生成的skyvern/client/isortimport 排序同样排除skyvern/client/pygrep-hooks禁止 blanket noqa、mock 方法误用、log.warn、缺失类型注解pyupgrade自动升级到新语法mypy严格类型检查--disallow-untyped-defs等排除tests/、alembic/与生成的 clientautoflake移除未使用 import递归、保留__init__importprettierJavaScript 格式化frontend-precommit在skyvern-frontend/内运行npm run precommitlint-stagedvitest前端单测npm ci后执行npm run testalembic-check手动阶段执行先alembic upgrade head再alembic check确保模型与迁移同步见 run_alembic_check.shshellcheck/yamlfmtShell 脚本检查与 YAML 格式化排除含 Go 模板的 Helm charts其中alembic-check对数据库层尤为重要Skyvern 的 schema 演进全部由 alembic/ 目录下的迁移脚本管理若模型与迁移不同步例如 OSS 同步 PR 漏掉了云端的迁移该钩子会直接报错并提示生成alembic revision --autogenerate。除 pre-commit 外开发阶段还可以独立运行ruff check/ruff formatlint 与格式化、mypy skyvern类型检查、pytest tests/运行测试套件见 CLAUDE.md。六、性能考虑查询、结构与缓存的取舍AGENTS.md 提醒 Agent 关注性能优化数据库查询、选用合适的数据结构、在收益明确处引入缓存、监控内存使用。这些原则在仓库中有多处体现数据库索引迁移alembic/ 目录下存在大量为查询性能而生的索引迁移如任务、步骤、制品表的组合索引与部分索引说明先分析查询、再补索引是项目常规操作缓存依赖pyproject.toml 引入cachetools与asyncache为 LLM 响应、脚本生成等场景提供进程内/异步缓存能力脱敏遍历的复杂度控制log_redaction.py 对日志对象遍历同时做了深度上限与循环引用去重保证每次日志脱敏的时间复杂度与节点数线性相关——这是选用合适数据结构、控制资源消耗的微观范例。七、安全最佳实践从规范到实现AGENTS.md 列出的安全要求包括绝不提交密钥或凭证、校验所有输入、使用环境变量承载配置、遵循最小权限原则、保持依赖更新。仓库的实现证据包括环境变量配置仓库根目录提供 .env.example将数据库连接、LLM Key、存储凭证等全部收敛为环境变量密钥文件均被 .gitignore 排除输入校验基于 pydantic 的 schema 层skyvern/schemas/在 API 边界完成参数类型与取值范围校验如confidence_float的 0–1 约束密钥检测pre-commit 中的detect-private-key钩子会在提交前拦截私钥文件从源头杜绝密钥入库日志脱敏如第三节所述敏感字段与 Bearer 凭证在进入日志前即被统一替换避免通过日志侧信道泄露凭证。八、获取帮助与开发命令速查AGENTS.md 建议先检索已有 issue 再开新问题、引用相关文档、为 bug 提供复现步骤、明确描述问题与预期行为。配合 CLAUDE.md 中记录的常用命令可以快速进入开发状态uv sync # 安装 Python 依赖 skyvern run all # 同时启动后端与 UI skyvern run server / skyvern run ui # 分别启动后端 / UI skyvern status / skyvern stop all # 查看状态 / 停止服务 skyvern quickstart # 首次初始化含数据库迁移 pytest tests/ # 运行测试 alembic upgrade head # 应用数据库迁移 pre-commit run --all-files # 提交前全量质量检查总结AGENTS.md 是 AI Agent 与人类开发者进入 Skyvern 代码库的协作契约它定义了从目录导航、编码风格、异步与错误处理到 PR 流程、质量门禁、性能与安全的全套规则。这些规则并非停留在文档层面——仓库的 pyproject.toml、.pre-commit-config.yaml、skyvern/errors/errors.py 与 skyvern/forge/log_redaction.py 等文件提供了可验证的实现支撑。对于希望为 Skyvern 贡献代码的 Agent 或开发者而言遵循本文梳理的规范与工具链即可在保持代码库一致性的前提下高效地完成功能开发、缺陷修复与维护任务。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Skyvern 仓库的 AI Agent 协作开发指南：从 AGENTS.md 解读项目结构与代码质量体系
Skyvern 仓库的 AI Agent 协作开发指南从 AGENTS.md 解读项目结构与代码质量体系【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 是一个使用 LLM 与计算机视觉自动化浏览器工作流的开源项目。本文以仓库根目录的 AGENTS.md 为主线系统解读 AI Agent以及人类开发者在 Skyvern 代码库中协作时的项目导航方法、编码规范、PR 提交流程与质量检查体系并结合仓库内的实际源码、配置文件与测试目录给出可验证的实现依据。读完本文你将掌握如何在 Skyvern 仓库中快速定位模块、遵循统一的代码风格提交变更并通过 pre-commit 与类型检查工具链保证贡献质量。一、项目结构Agent 导航 Skyvern 代码库的起点AGENTS.md 将仓库组织为若干顶层目录这与仓库实际布局一一对应。核心 Python 包位于 skyvern/ 目录包含以下子模块目录职责仓库佐证skyvern/cli/命令行接口组件含run_commands.py、workflow.py、quickstart.py等命令实现skyvern/client/客户端实现与集成含生成的 Python 客户端 SDKraw_client.py、client.pyskyvern/forge/核心自动化逻辑与工作流含agent.py、agent_functions.py、FastAPI 应用与 SDK 层skyvern/library/共享工具与对外 SDK 封装含公开的Skyvern类与页面/浏览器/locator 包装器skyvern/schemas/数据模型与校验模式基于 pydantic 的请求/响应模型skyvern/services/业务逻辑与服务层任务、工作流、浏览器会话等业务编排skyvern/utils/通用工具函数日志脱敏、action 序列化等公共工具skyvern/webeye/Web 交互与浏览器自动化Playwright 驱动的 DOM 抓取与动作执行除主包外仓库还包含skyvern-frontend/React 前端应用负责任务管理与监控、integrations/第三方服务集成如 Make、n8n、MCP、alembic/数据库迁移脚本、scripts/工具与部署脚本、tests/单元测试、SDK 测试与冒烟测试。从源码结构看Skyvern 的运行时依赖被拆分为local与server两组可选依赖见 pyproject.tomlserver是local的超集额外包含 uvicorn、psycopgPostgreSQL 驱动等后端组件。因此Agent 在定位某个功能时应先判断其属于 CLI、浏览器引擎webeye、核心自动化forge还是业务服务services层再深入对应目录。二、编码规范Python 标准与代码风格约定AGENTS.md 对 Python 代码提出了明确要求这些约定与仓库的工具链配置相互印证Python 版本与类型注解要求使用 Python 3.11 特性并编写类型注解。pyproject.toml 中requires-python 3.11,3.15与之完全一致仓库还通过 pre-commit 钩子强制校验 Python 版本在 3.11–3.13 范围内见 .pre-commit-config.yaml 中的check-python-version。行宽 100 字符与命名风格遵循 PEP 8行宽 100 字符变量与函数使用snake_case类使用PascalCase。绝对导入所有模块使用绝对导入避免相对导入造成的可读性与重构问题。Google 风格 docstring所有公开函数与类需要编写文档字符串便于生成 API 文档与让 LLM 理解模块意图。仓库代码是这些约定的直接体现例如 skyvern/errors/errors.py 中的UserDefinedError使用 pydanticBaseModel、StrEnum与field_validator注释详细说明了错误码与推理文本的截断策略——这正是类型注解 详尽文档的典型样例。异步编程约定Skyvern 是一个高并发浏览器自动化平台AGENTS.md 明确要求优先使用async/await而非回调使用asyncio处理并发异步代码必须处理异常使用上下文管理器context manager进行资源清理。从仓库看核心运行时代码如 skyvern/forge/agent.py、webeye 浏览器模块均采用 async 风格编写且 pyproject.toml 的依赖中包含aiohttp、asyncssh、aiofiles、aiosqlite、aioboto3等一整套异步生态库印证了全栈异步的实现路线。三、错误处理与日志安全异常体系与敏感信息脱敏AGENTS.md 对错误处理的要求是使用具体异常类、携带有意义的错误消息、按严重级别记录日志、绝不在错误消息中暴露敏感信息。仓库在这三方面都有落地实现异常体系skyvern/errors/errors.py 定义了ErrorTypeUSER_DEFINED_ERROR/SYSTEM_DEFINED_ERROR与UserDefinedError模型其中confidence_float通过 pydantic 约束在 0–1 之间reasoning字段则由验证器按ERROR_CODE_REASONING_MAX_LENGTH截断——保证 LLM 生成的错误说明不会因过长而丢失错误码。日志脱敏AGENTS.md 强调不在错误消息中暴露敏感信息仓库在 skyvern/forge/log_redaction.py 中实现了完整的字段级脱敏机制SENSITIVE_HEADERS与SENSITIVE_FIELDS定义了全量敏感名称集合authorization、cookie、x-api-key、password、secret、token、api_key、credential、totp、otp、verification_code 等采用精确匹配而非子串匹配避免误伤credential_id、author、page_token这类仅包含敏感子串但并非密钥的字段对字符串内嵌的 Bearer 凭证如?tokenBearer%20jwt、Authorization: Bearer token进行正则替换为redacted对签名制品 URL/v1/artifacts/.../content?带 query剥离能力参数递归遍历 dict/list/BaseModel 结构深度上限 20 层并对循环引用输出circular防止指数级展开。这套脱敏逻辑被请求日志中间件与 structlog 处理器共用是绝不暴露敏感信息这条规范在源码层的直接证据。相关测试见 tests/unit/forge/sdk/artifact/test_secret_artifact_redaction.py。四、Pull Request 流程分支命名、PR 指南与提交信息格式AGENTS.md 规定了完整的提交流程Agent 与开发者都应遵守1. 分支命名新功能feature/descriptive-name缺陷修复fix/issue-description维护任务chore/task-description2. PR 指南使用Fixes #123或Closes #123关联 issue提交清晰的变更描述同步更新相关文档确保所有测试通过合并前至少获得一个评审批准。3. 提交信息格式[Component] Action: Brief description More detailed explanation if needed. - Bullet points for additional context - Reference issues with #123该格式将变更收敛到具体组件如[Agent]、[Webeye]、[CLI]便于维护者与 Agent 快速定位变更影响面。五、代码质量检查pre-commit 钩子链与静态分析AGENTS.md 要求提交代码前运行pre-commit run --all-files仓库的 .pre-commit-config.yaml 是这一要求的完整落地钩子链覆盖了 Python 与前端两侧钩子作用pre-commit-hooks官方集合大文件检查15MB 上限、BOM/大小写冲突/合并冲突/符号链接检查、debug-statements、私钥检测check-python-version强制 Python 版本在 3.11–3.13ruffruff-formatPython lint 与格式化自动--fix排除生成的skyvern/client/isortimport 排序同样排除skyvern/client/pygrep-hooks禁止 blanket noqa、mock 方法误用、log.warn、缺失类型注解pyupgrade自动升级到新语法mypy严格类型检查--disallow-untyped-defs等排除tests/、alembic/与生成的 clientautoflake移除未使用 import递归、保留__init__importprettierJavaScript 格式化frontend-precommit在skyvern-frontend/内运行npm run precommitlint-stagedvitest前端单测npm ci后执行npm run testalembic-check手动阶段执行先alembic upgrade head再alembic check确保模型与迁移同步见 run_alembic_check.shshellcheck/yamlfmtShell 脚本检查与 YAML 格式化排除含 Go 模板的 Helm charts其中alembic-check对数据库层尤为重要Skyvern 的 schema 演进全部由 alembic/ 目录下的迁移脚本管理若模型与迁移不同步例如 OSS 同步 PR 漏掉了云端的迁移该钩子会直接报错并提示生成alembic revision --autogenerate。除 pre-commit 外开发阶段还可以独立运行ruff check/ruff formatlint 与格式化、mypy skyvern类型检查、pytest tests/运行测试套件见 CLAUDE.md。六、性能考虑查询、结构与缓存的取舍AGENTS.md 提醒 Agent 关注性能优化数据库查询、选用合适的数据结构、在收益明确处引入缓存、监控内存使用。这些原则在仓库中有多处体现数据库索引迁移alembic/ 目录下存在大量为查询性能而生的索引迁移如任务、步骤、制品表的组合索引与部分索引说明先分析查询、再补索引是项目常规操作缓存依赖pyproject.toml 引入cachetools与asyncache为 LLM 响应、脚本生成等场景提供进程内/异步缓存能力脱敏遍历的复杂度控制log_redaction.py 对日志对象遍历同时做了深度上限与循环引用去重保证每次日志脱敏的时间复杂度与节点数线性相关——这是选用合适数据结构、控制资源消耗的微观范例。七、安全最佳实践从规范到实现AGENTS.md 列出的安全要求包括绝不提交密钥或凭证、校验所有输入、使用环境变量承载配置、遵循最小权限原则、保持依赖更新。仓库的实现证据包括环境变量配置仓库根目录提供 .env.example将数据库连接、LLM Key、存储凭证等全部收敛为环境变量密钥文件均被 .gitignore 排除输入校验基于 pydantic 的 schema 层skyvern/schemas/在 API 边界完成参数类型与取值范围校验如confidence_float的 0–1 约束密钥检测pre-commit 中的detect-private-key钩子会在提交前拦截私钥文件从源头杜绝密钥入库日志脱敏如第三节所述敏感字段与 Bearer 凭证在进入日志前即被统一替换避免通过日志侧信道泄露凭证。八、获取帮助与开发命令速查AGENTS.md 建议先检索已有 issue 再开新问题、引用相关文档、为 bug 提供复现步骤、明确描述问题与预期行为。配合 CLAUDE.md 中记录的常用命令可以快速进入开发状态uv sync # 安装 Python 依赖 skyvern run all # 同时启动后端与 UI skyvern run server / skyvern run ui # 分别启动后端 / UI skyvern status / skyvern stop all # 查看状态 / 停止服务 skyvern quickstart # 首次初始化含数据库迁移 pytest tests/ # 运行测试 alembic upgrade head # 应用数据库迁移 pre-commit run --all-files # 提交前全量质量检查总结AGENTS.md 是 AI Agent 与人类开发者进入 Skyvern 代码库的协作契约它定义了从目录导航、编码风格、异步与错误处理到 PR 流程、质量门禁、性能与安全的全套规则。这些规则并非停留在文档层面——仓库的 pyproject.toml、.pre-commit-config.yaml、skyvern/errors/errors.py 与 skyvern/forge/log_redaction.py 等文件提供了可验证的实现支撑。对于希望为 Skyvern 贡献代码的 Agent 或开发者而言遵循本文梳理的规范与工具链即可在保持代码库一致性的前提下高效地完成功能开发、缺陷修复与维护任务。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考