可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载agents.toml是 dotagents 技能依赖管理器的核心配置文件它声明了一个项目中所有 Agent 技能Skill的来源、可信任的下载范围、MCP 服务器与工具事件钩子。本指南以 sentry-javascript 仓库中实际落地的 agents.toml、agents.lock 与 dotagents 技能自带的三份参考文档configuration.md、config-schema.md、cli-reference.md为主线读完你将掌握agents.toml每一个字段的含义与默认值、六种技能来源格式、通配符技能、信任白名单、MCP/Hooks 的分发机制以及dotagents init / add / install / sync / list等命令与配置的联动关系能够在自己的项目中直接复刻一套可运行的 Agent 技能管理方案。agents.toml 定位dotagents 的声明式配置中心dotagents 是一个面向多 Agent 工具的技能依赖管理器它读取agents.toml中的声明解析、下载并安装技能到统一的.agents/skills/目录再通过符号链接或原生发现机制让 Claude Code、Cursor、Codex、VS Code、OpenCode 等工具都能发现这些技能。agents.toml就是这一切的包清单——它声明了装哪些技能、从哪里装、信任谁、附带哪些 MCP 服务器和钩子。在本仓库中这一套机制被真实使用项目根目录同时存在 agents.toml 与自动生成的 agents.lock而.agents/skills/下则落地了包括dotagents、release、triage-issue、fix-issue、upgrade-dep在内的二十余个技能。其中 dotagents 技能自身的 SKILL.md 明确指出若dotagents未作为直接命令可用可通过npx sentry/dotagents运行所有命令与参数行为一致。配置文件的顶层结构由 config-schema.md 给出完整骨架version 1 # Required, must be 1 gitignore true # Optional, default true agents [claude, cursor] # Optional, agent targets [project] # Optional [trust] # Optional [[skills]] # Optional, array of skill entries [[mcp]] # Optional, array of MCP servers [[hooks]] # Optional, array of hook declarations顶层字段的精确约束如下字段类型必填默认值说明versioninteger是--Schema 版本必须为1gitignoreboolean否true是否为受管技能生成.agents/.gitignoreagentsstring[]否[]Agent 目标claude、cursor、codex、vscode、opencode最小配置从一个可运行的示例开始一份最精简但完整可用的agents.toml只需要三行version 1 agents [claude] [[skills]] name find-bugs source getsentry/skillsversion 1是当前唯一的 schema 版本必须声明agents [claude]控制后续为哪些 Agent 工具生成符号链接与配置[[skills]]数组中每个条目声明一个技能name与source均必填。在 sentry-javascript 仓库的真实 agents.toml 中最小配置被扩展成了完整的生产级清单version 1、gitignore false、agents [claude, cursor]并在[trust]中限定github_orgs [getsentry]、github_repos [getsentry/skills, anthropics/skills]随后以[[skills]]数组声明了 20 个技能条目如dotagents、release、triage-issue、skill-scanner、skill-creator等既包含远程源getsentry/dotagents、getsentry/skills、anthropics/skills也包含本仓库内的本地路径技能path:.agents/skills/...。这份文件本身就是对下文各配置块的完整示范。Skills声明技能依赖的核心区块常规技能字段每个技能条目需要name与source可选地通过ref锁定版本或通过path指定源仓库内的子目录[[skills]] name find-bugs source getsentry/skills ref v1.0.0 path plugins/sentry-skills/skills/find-bugs各字段的精确语义来自 config-schema.md字段类型必填说明namestring是唯一标识符模式为^[a-zA-Z0-9][a-zA-Z0-9._-]*$sourcestring是owner/repo、owner/reporef、git:url或path:relativerefstring否要锁定的 tag、分支或 commit SHApathstring否源仓库内包含该技能的子目录六种 Source 格式source是 dotagents 的灵魂字段支持六种写法对应不同的解析结果格式示例解析结果GitHub shorthand简写getsentry/skillshttps://github.com/getsentry/skills.gitGitHub pinned锁定版本getsentry/skillsv1.0.0同上检出到v1.0.0GitHub HTTPShttps://github.com/owner/repoURL 直接使用GitHub SSHgitgithub.com:owner/repo.gitSSH 克隆Git URLgit:https://git.corp.dev/team/skills任意非 GitHub 的 git remoteLocal本地路径path:./my-skills/custom相对于项目根目录其中path:本地路径技能在 sentry-javascript 仓库中被大量使用例如agents.toml中的source path:.agents/skills/release、source path:.agents/skills/triage-issue等。本地技能直接指向仓库内已存在的技能目录无需任何网络下载。技能命名规则name必须以字母或数字开头且只能包含[a-zA-Z0-9._-]字符不得包含空格、斜杠等其它字符。通配符技能Wildcard Skills当一个来源包含多个技能时可以用一条name *条目把整个来源的全部技能一次性纳入管理并可选地用exclude排除掉不需要的[[skills]] name * source getsentry/skills exclude [deprecated-skill]在install和update时dotagents 会扫描该来源发现的所有技能并逐个安装exclude中列出的除外每个技能在 lockfile 中拥有独立的条目。命令行中可用dotagents add source --all快速创建一条通配符条目。从 cli-reference.md 可以看到通配符条目的完整字段name字面量*必填、source必填格式与常规技能相同、ref可选与exclude可选默认[]。另外需要留意--all与--name/位置参数互斥不能同时使用。Trust限制可信任的下载来源Trust 段用于限定哪些技能来源被允许。若完全不写[trust]段则默认放行所有来源向后兼容显式声明时有两种模式# 显式放行所有来源 [trust] allow_all true# 限定到具体的 GitHub 组织与仓库 [trust] github_orgs [getsentry] github_repos [external-org/specific-repo] git_domains [git.corp.example.com]匹配规则如下GitHub 来源按 owner 匹配github_orgs或按精确的owner/repo匹配github_reposGit URL 来源git:前缀按域名匹配git_domains本地path:来源永远被允许一个来源只要命中任意一条规则org 或 repo 或 domain即通过校验。allow_all的优先级最高置为true时会覆盖其它所有字段。信任校验发生在add与install的任何网络操作之前——也就是说来源不被信任时根本不会发起克隆请求。sentry-javascript 仓库的 agents.toml 给出了一个白名单 混合来源的实例github_orgs [getsentry]放行整个 getsentry 组织github_repos [getsentry/skills, anthropics/skills]精确放行两个具体仓库同时path:本地技能不受限制。MCP Servers声明模型上下文协议服务器[[mcp]]数组用于声明 MCPModel Context Protocol服务器声明后会被写入每个目标 Agent 的配置文件支持 stdio 与 HTTP 两种传输方式# Stdio 传输 [[mcp]] name github command npx args [-y, modelcontextprotocol/server-github] env [GITHUB_TOKEN] # HTTP 传输 [[mcp]] name remote-api url https://mcp.example.com/sse headers { Authorization Bearer token }字段约束来自 config-schema.md字段类型必填说明namestring是唯一的服务器标识commandstring仅 stdio要执行的命令argsstring[]否命令参数envstring[]否需要透传的环境变量名urlstring仅 HTTP服务器 URLheaderstable否HTTP 请求头command与url二选一且互斥。MCP 配置按 Agent 写入各自的原生格式Agent写入位置格式Claude.mcp.jsonJSONCursor.cursor/mcp.jsonJSONCodex.codex/config.tomlTOML与 Codex 其它配置共享VS Code.vscode/mcp.jsonJSONOpenCodeopencode.jsonJSON共享日常操作中也可以不手写agents.toml而是用dotagents mcp add命令声明stdio 示例为dotagents mcp add github --command npx --args -y --args modelcontextprotocol/server-github --env GITHUB_TOKENHTTP 示例为dotagents mcp add remote-api --url https://mcp.example.com/sse --header Authorization:Bearer token--args、--header、--env均可重复传入--command与--url互斥配合dotagents mcp remove name与dotagents mcp list [--json]完成增删查。Hooks为 Agent 工具事件挂接命令[[hooks]]数组用于声明工具事件钩子——当 Agent 发生指定工具事件时执行一条 shell 命令[[hooks]] event PreToolUse matcher Bash command my-lint-check字段说明字段类型必填说明eventstring是事件类型见下matcherstring否要匹配的工具名省略则匹配所有工具commandstring是要执行的 shell 命令支持的事件PreToolUse、PostToolUse、UserPromptSubmit、Stop。Hook 配置同样按 Agent 分发且各工具的支持程度不同Claude写入.claude/settings.json合并进既有文件Cursor写入.cursor/hooks.json独立文件事件映射为 Cursor 等价事件VS Code与 Claude 共用.claude/settings.jsonCodex / OpenCode不支持 hooks安装 / sync 时会发出警告。Cursor 的事件映射关系如下dotagents 事件Cursor 等价事件PreToolUsebeforeShellExecutionbeforeMCPExecutionPostToolUseafterFileEditUserPromptSubmitbeforeSubmitPromptStopstopAgents控制配置与符号链接的目标agents数组决定 dotagents 为哪些 Agent 工具生成符号链接和配置文件agents [claude, cursor, codex, vscode, opencode]每个被列入的 Agent 会获得一个指向.agents/skills/的agent-dir/skills/符号链接Claude、Cursor或直接从.agents/skills/原生发现技能Codex、VS Code、OpenCodeAgent 配置文件中的 MCP 服务器配置支持的钩子配置。从 config-schema.md 还可以看到agents为空数组[]时不会为任何 Agent 生成目标此外存在一个向后兼容的[symlinks]段[symlinks] targets [.claude, .cursor]当设置了agents时符号链接目标会自动推导[symlinks]仅用于旧版兼容。在 sentry-javascript 仓库中agents [claude, cursor]意味着同时维护 Claude Code 与 Cursor 两套技能发现路径。Scopes项目级与用户级两种作用域项目作用域默认默认情况下 dotagents 作用于当前项目要求项目根目录存在agents.toml。技能被安装到.agents/skills/符号链接指向项目内的.claude/skills/、.cursor/skills/等。用户作用域--user使用--user时dotagents 转而操作~/.agents/用于管理跨项目共享的技能可通过环境变量DOTAGENTS_HOME覆盖该目录dotagents --user init dotagents --user add getsentry/skills --all用户作用域的符号链接指向~/.claude/skills/与~/.cursor/skills/。还有一个实用的自动回退规则当当前目录既不存在agents.toml又不在任何 git 仓库内时dotagents 会自动回退到用户作用域。Gitignore决定技能是否入库gitignore字段控制受管技能是否被 git 忽略gitignore trueschema 默认值dotagents 生成.agents/.gitignore列出所有受管远程来源技能。就地技能path:.agents/skills/...永远不会被 gitignore因为它们必须被 git 跟踪才能发挥作用gitignore false不生成.gitignore技能直接随仓库提交。任何克隆仓库的人无需运行install就能直接获得全部技能。sentry-javascript 仓库正是选择了后者根目录 agents.toml 第 24 行的注释明确写道 Check skills into git so collaborators get them without running dotagents install并把gitignore false落到实处。经核实仓库的.agents/目录中确实不存在自动生成的.gitignore文件全部技能以就地path:源形式入库跟踪克隆即可用。Caching缓存机制与 TTLdotagents 对技能来源做了两级缓存缓存位置~/.local/dotagents/可通过环境变量DOTAGENTS_STATE_DIR覆盖未锁定版本unpinned的仓库缓存有效期为 24 小时24-hour TTL过期后重新拉取锁定到 40 位 SHA 的引用缓存不可变immutable永远不会重新拉取——因为提交哈希是内容寻址的一旦锁定就不需要更新需要绕过缓存时使用dotagents install --force。环境变量总览变量用途DOTAGENTS_STATE_DIR覆盖缓存位置默认~/.local/dotagentsDOTAGENTS_HOME覆盖用户作用域位置默认~/.agents这两个变量在 configuration.md 与 config-schema.md 中均有记载是隔离多项目缓存或重定向用户级技能目录的常用手段。配套命令配置如何被消费agents.toml中的声明最终由 dotagents 命令消费。核心命令一览详见 cli-reference.md 与 SKILL.md命令作用dotagents init初始化agents.toml与.agents/目录dotagents install按agents.toml安装全部技能dotagents add specifier添加技能依赖并安装dotagents remove name移除技能dotagents update [name]更新技能到最新版本dotagents sync调和状态收养孤儿、修复符号链接、校验完整性dotagents list列出已安装技能及其状态dotagents mcp添加、移除或列出 MCP 服务器声明install的完整工作流与agents.toml各区块一一对应加载配置与 lockfile → 展开通配符条目 → 逐个校验来源的信任策略 → 解析技能优先使用 lockfile 锁定的提交→ 复制技能到.agents/skills/name/→ 写入带完整性哈希的 lockfile → 按gitignore生成.agents/.gitignore→ 创建 / 校验 Agent 符号链接 → 写入 MCP 与 hook 配置。其中--frozen在 lockfile 缺失或不同步时直接失败且不修改 lockfileCI 友好--force则忽略锁定提交、全部重新解析到最新引用。sync是配置与磁盘状态之间的对账命令执行收养孤儿技能已安装但未在配置中声明→ 重新生成.agents/.gitignore→ 检查缺失技能 → 校验完整性哈希 → 修复 Agent 符号链接 → 校验 / 修复 MCP 配置 → 校验 / 修复 hook 配置并把被本地修改的技能、缺失的 MCP/hook 配置作为警告报告把缺失技能作为错误报告。list的状态指示器对排障尤其有用✓ok已安装完整性匹配~modified安装后被本地修改✗missing在配置中但未安装?unlocked已安装但未进入 lockfile。Lockfile配置的精确快照agents.toml是意图声明agents.lock 则是不可手改的精确快照文件头标注 Auto-generated by dotagents. Do not edit.。以本仓库 lockfile 中的dotagents技能条目为例[skills.dotagents] source getsentry/dotagents resolved_url https://github.com/getsentry/dotagents.git resolved_path skills/dotagents commit a71b92d3cca4d0ed7bd763b611771ff9c81d50c8 integrity sha256-/KBw6Ea4epWV0EiNUF32dEQKd7vcBhns31rSI6D4R1o字段含义source为agents.toml中的原始来源resolved_url为解析后的 git URLresolved_path为仓库内子目录resolved_ref为解析出的引用默认分支时省略commit为解析提交的完整 40 位 SHAintegrity为sha256-前缀的 base64 内容哈希。本地路径技能如path:.agents/skills/release在 lockfile 中只含source与integrity没有 commit。integrity哈希正是sync检测技能被本地修改以及install --force恢复原状的数据依据。Troubleshooting常见问题排查技能无法安装用dotagents list检查agents.toml语法是否可被正常解析手动git clone该 URL确认来源本身可访问若处于受限模式配置了[trust]检查来源是否命中信任规则。符号链接损坏运行dotagents sync修复。完整性不匹配integrity mismatch说明技能在安装后被本地修改过——运行dotagents install --force从缓存 / 远端恢复原始内容或运行dotagents sync检测并上报问题详情。从仓库实例学到的落地模式回看 sentry-javascript 的完整实践可以提炼出三条可直接复用的配置模式混合来源声明远程源getsentry/dotagents、getsentry/skills、anthropics/skills与本地path:源共存于同一[[skills]]数组核心维护类技能入库跟踪、社区技能按需远程拉取信任白名单 就地技能豁免[trust]只放行 getsentry 组织与两个精确仓库path:本地技能不受信任规则约束实现了外部来源严控、内部技能免审gitignore false 的协作策略技能全部随仓库提交协作成员克隆即用无需运行install配合 lockfile 保证一致性。如果你要在自己的项目里初始化一套同样的配置从dotagents init开始交互模式会依次引导选择 Agent、决定是否 gitignore、选择信任策略随后用dotagents add getsentry/skills find-bugs添加具体技能、用dotagents add getsentry/skills --all添加通配符条目、用dotagents install --frozen在 CI 中锁定版本安装。完整的字段级参考可继续查阅 config-schema.md命令级参考见 cli-reference.md。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐sentry-javascript 中的 dotagents agents.toml 配置 Schema 完全指南sentry javascript 中的 dotagents agents.toml 配置 Schema 完全指南 本指南以 sentry javascript可观测性dotagents 技能依赖管理实战用 agents.toml 统一管理多 Agent 工具的 Skillsdotagents 技能依赖管理实战用 agents.toml 统一管理多 Agent 工具的 Skills 导读 本指南围绕 sentry javascri可观测性sentry-javascript 单体仓库统一升级 sentry/conventions 依赖的完整操作指南bump-conventions 技能全解sentry javascript 单体仓库统一升级 sentry/conventions 依赖的完整操作指南bump conventions 技能全解可观测性上一篇transdim性能优化指南提升模型训练速度的5个实用技巧下一篇如何快速掌握VideoProcessor6大核心功能让视频处理变得简单高效创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考