可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载本指南以 sentry-javascript 仓库中 dotagents 技能包的配置 Schema 参考文档 为核心完整讲解 dotagents 工具链中agents.toml的字段定义、默认值与数据类型并结合作者仓库根目录真实的 agents.toml 与 agents.lock 文件展示如何声明技能依赖、配置信任策略、注册 MCP 服务器与钩子。读完本文你将能独立编写、校验并理解任意项目的agents.toml并掌握锁文件与缓存机制的工作原理。顶层结构与字段速览agents.toml是 dotagents 的唯一配置入口采用 TOML 格式。其顶层结构如下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顶层字段的完整定义见下表FieldTypeRequiredDefaultDescriptionversionintegerYes--Schema version, must be1gitignorebooleanNotrueGenerate.agents/.gitignorefor managed skills.agentsstring[]No[]Agent targets:claude,cursor,codex,vscode,opencode其中version 1是硬性要求schema 演进时会以该字段作为兼容性判据。agents数组决定了后续 symlink、MCP 与 hooks 配置写入哪些 Agent 工具。作者仓库根目录的 agents.toml 即是一个实际样例注意其组合了远程技能与本地技能两种来源version 1 # Check skills into git so collaborators get them without running dotagents install. # Set to true (or remove) to gitignore managed skills instead. gitignore false agents [claude, cursor] [trust] github_orgs [getsentry] github_repos [getsentry/skills, anthropics/skills]可以看到gitignore被显式设为false意味着技能文件直接提交进 Git 仓库任何协作者克隆后无需执行dotagents install即可获得全部技能agents声明了 Claude 与 Cursor 两个目标。Project Section[project]段落用于存放项目展示名可选[project] name my-project # Optional, display name它不影响技能解析或安装逻辑主要供 dotagents 的交互界面与日志输出使用。Symlinks Section[symlinks] targets [.claude, .cursor] # Legacy: explicit symlink targets当顶层agents字段被设置后symlink 目标会根据 Agent 类型自动推导[symlinks]段落仅作为向后兼容的遗留写法存在新项目应优先使用agents字段。仓库中agents [claude, cursor]的实际落盘结果可以在.claude/与.cursor/目录中看到.claude/skills是一个指向../.agents/skills的软链接这正是Agent 目录技能 symlink 指向.agents/skills/这一机制的运行时证据。Skills Section技能条目是agents.toml的核心。每个技能依赖都通过[[skills]]数组声明分普通技能与通配符技能两种形态。普通技能Regular Skills[[skills]] name find-bugs # Required, unique skill identifier source getsentry/skills # Required, skill source ref v1.0.0 # Optional, pin to tag/branch/commit path tools/my-skill # Optional, subdirectory within repoFieldTypeRequiredDescriptionnamestringYesUnique identifier. Pattern:^[a-zA-Z0-9][a-zA-Z0-9._-]*$sourcestringYesowner/repo,owner/reporef,git:url, orpath:relativerefstringNoTag, branch, or commit SHA to pinpathstringNoSubdirectory containing the skill within the source reponame的命名规则要求以字母或数字开头之后只能包含[a-zA-Z0-9._-]。source支持多种格式详见下方来源格式表ref用于将技能钉在某个 tag、分支或 commit 上path用于定位源仓库内技能所在的子目录。在作者仓库中远程技能与本地路径技能混用例如[[skills]] name skill-scanner source getsentry/skills [[skills]] name triage-issue source path:.agents/skills/triage-issue通配符技能Wildcard Skills当希望一次性安装某个源下的全部技能时可将name设为字面量*[[skills]] name * # Wildcard: install all skills from source source getsentry/skills # Required ref v1.0.0 # Optional exclude [deprecated-skill] # Optional, skills to skipFieldTypeRequiredDescriptionnameliteral*YesWildcard markersourcestringYesSame formats as regular skillsrefstringNoTag, branch, or commit SHA to pinexcludestring[]NoSkill names to skip. Default:[]在install与update流程中dotagents 会从源仓库自动发现全部技能除exclude列表中的条目外逐一安装且每个技能在锁文件中都拥有独立的条目可在 agents.lock 中看到[skills.skill-scanner]这样的独立段落。命令行中可用dotagents add source --all快速生成通配符条目。来源格式Source FormatsFormatExampleResolves toGitHub shorthandgetsentry/skillshttps://github.com/getsentry/skills.gitGitHub pinnedgetsentry/skillsv1.0.0Same, checked out atv1.0.0GitHub HTTPShttps://github.com/owner/repoURL used directlyGitHub SSHgitgithub.com:owner/repo.gitSSH cloneGit URLgit:https://git.corp.dev/team/skillsAny non-GitHub git remoteLocalpath:./my-skills/customRelative to project root其中path:本地路径来源始终被信任、不参与信任校验且不会被 gitignore见下文 Gitignore 说明。Trust Section[trust]用于限制允许安装的技能来源。不写[trust]段落时默认允许所有来源向后兼容。支持三种配置形态# Allow all sources explicitly [trust] allow_all true # OR restrict to specific sources: [trust] github_orgs [getsentry] # GitHub org names github_repos [ext-org/repo] # Exact owner/repo pairs git_domains [git.corp.example.com] # Git URL domainsFieldTypeDescriptionallow_allbooleanAllow all sources (overrides other fields)github_orgsstring[]Allowed GitHub organizationsgithub_reposstring[]Allowed exactowner/repopairsgit_domainsstring[]Allowed domains forgit:URLs匹配语义如下GitHub 来源按github_orgs按 owner 匹配或github_repos精确owner/repo对匹配git:URL 来源按git_domains匹配本地path:来源始终允许任一规则命中org OR repo OR domain即视为通过。信任校验发生在add与install的任何网络操作之前属于前置安全检查。作者仓库的 agents.toml 就采用了限定模式github_orgs [getsentry]且github_repos显式列出了getsentry/skills与anthropics/skills后者作为跨组织白名单的典型用例。MCP Section[[mcp]]段落声明 MCPModel Context Protocol服务器dotagents 会将其写入每个 Agent 各自的配置文件中。Stdio 传输本地命令启动[[mcp]] name github # Required, unique server name command npx # Required for stdio args [-y, modelcontextprotocol/server-github] # Optional env [GITHUB_TOKEN] # Optional, env vars to pass throughHTTP 传输远程端点[[mcp]] name remote-api # Required, unique server name url https://mcp.example.com/sse # Required for HTTPFieldTypeRequiredDescriptionnamestringYesUnique server identifiercommandstringStdio onlyCommand to executeargsstring[]NoCommand argumentsenvstring[]NoEnvironment variable names to pass throughurlstringHTTP onlyServer URLheaderstableNoHTTP headers两种传输方式二选一stdio 需要commandHTTP 需要url。env数组只透传变量名值取自运行时环境避免敏感信息写死进配置文件HTTP 模式可通过headers表携带鉴权头例如headers { Authorization Bearer token }。MCP 配置按 Agent 写入对应格式Claude.mcp.jsonJSONCursor.cursor/mcp.jsonJSONCodex.codex/config.tomlTOML与 Codex 其他配置共享VS Code.vscode/mcp.jsonJSONOpenCodeopencode.jsonJSON共享命令行为操作可参考 CLI 参考文档dotagents mcp add github --command npx --args -y --args modelcontextprotocol/server-github --env GITHUB_TOKEN或dotagents mcp add remote-api --url https://mcp.example.com/sse --header Authorization:Bearer token。Hooks Section[[hooks]]声明 Agent 工具事件的钩子命令[[hooks]] event PreToolUse # Required matcher Bash # Optional, tool name filter command my-lint-check # RequiredFieldTypeRequiredDescriptioneventstringYesPreToolUse,PostToolUse,UserPromptSubmit,StopmatcherstringNoTool name to match (omit for all tools)commandstringYesShell command to executematcher缺省时钩子对所有工具生效指定后仅命中对应工具名。钩子配置按 Agent 写入Claude.claude/settings.json合并进已有文件Cursor.cursor/hooks.json独立文件事件映射为 Cursor 等价事件VS Code.claude/settings.json与 Claude 共用同一文件Codex/OpenCode不支持安装/同步时会输出警告Cursor 事件映射关系为PreToolUse→beforeShellExecutionbeforeMCPExecutionPostToolUse→afterFileEditUserPromptSubmit→beforeSubmitPromptStop→stop。作者仓库 .claude/settings.json 中即可看到手工配置的SessionStart钩子示例执行scripts/claude-cloud-setup.sh可作为钩子实际落盘格式的参照。Lockfileagents.lockagents.lock由 dotagents 自动生成禁止手工编辑。它钉住每个技能的确切 commit 与内容哈希保证可复现安装。格式如下version 1 [skills.find-bugs] source getsentry/skills resolved_url https://github.com/getsentry/skills.git resolved_path plugins/sentry-skills/skills/find-bugs resolved_ref v1.0.0 commit c8881564e75eff4faaecc82d1c3f13356851b6e7 integrity sha256-FWmCLdOjxXffiEg7Bx19drylVypeKz8me9OA757jsFieldTypeDescriptionsourcestringOriginal source fromagents.tomlresolved_urlstringResolved git URLresolved_pathstringSubdirectory within reporesolved_refstringRef that was resolved (omitted for default branch)commitstringFull 40-char SHA of resolved commitintegritystringsha256-prefixed base64 content hash本地路径技能path:来源只有source与integrity两个字段没有 commit。这一差异在作者仓库的 agents.lock 中体现得十分直观[skills.add-ai-integration]、[skills.e2e]等本地技能段仅含source与integrity而[skills.dotagents]来源getsentry/dotagents、[skills.skill-creator]来源anthropics/skills、[skills.skill-scanner]来源getsentry/skills则带有resolved_url、resolved_path、commit与integrity的完整记录。环境变量VariablePurposeDOTAGENTS_STATE_DIROverride cache location (default:~/.local/dotagents)DOTAGENTS_HOMEOverride user-scope location (default:~/.agents)DOTAGENTS_STATE_DIR覆盖缓存目录默认~/.local/dotagents未钉 ref 的仓库按 24 小时 TTL 缓存钉住 40 位 commit SHA 的 ref 被不可变缓存、永不重新拉取dotagents install --force可绕过缓存。DOTAGENTS_HOME覆盖用户级作用域目录默认~/.agents配合--user标志管理跨项目共享的技能例如dotagents --user init、dotagents --user add getsentry/skills --all。实战要点与配套文档协同使用agents.toml的完整 Schema 之上还有两层配套文档值得串联使用dotagents SKILL 概览掌握dotagents init / install / add / remove / update / sync / list / mcp的命令级用法与快速上手示例。若dotagents不是直接可用命令可用npx sentry/dotagents等价替代例如npx sentry/dotagents sync。配置指南涵盖最小示例、通配符行为、信任校验时机、钩子事件映射、项目作用域与用户作用域切换、gitignore true/false对技能入库策略的影响以及常见的故障排查技能不安装、symlink 损坏、完整性不匹配。常见排障速查agents.toml语法问题先用dotagents list校验来源不可访问则手动git clone验证 URL受限信任模式下检查[trust]配置symlink 损坏执行dotagents sync修复技能被本地修改导致完整性不匹配时执行dotagents install --force恢复或先sync检测并报告问题。结语agents.toml的 Schema 虽然字段不多却覆盖了技能依赖解析、来源格式、信任边界、MCP 服务器与事件钩子等完整能力并通过agents.lock的 commit 哈希双保险实现可复现安装。本文所述的每一项字段、默认值与解析语义均可在 config-schema.md 原文及仓库根目录的 agents.toml、agents.lock 实际配置中逐一核对。无论是为个人项目初始化技能依赖还是像 sentry-javascript 这样维护一个多 Agent、多技能源的大型仓库理解这套 Schema 都是用好 dotagents 的第一步。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐sentry-javascript 仓库 skill-creator 技能体系的 JSON Schema 完整解读sentry javascript 仓库 skill creator 技能体系的 JSON Schema 完整解读 导读 本文以 .agents/skills/可观测性Sentry JavaScript SDK高级配置选项深入理解init方法参数Sentry JavaScript SDK高级配置选项深入理解init方法参数 Sentry JavaScript SDK的 init 方法是配置错误监控的核可观测性sentry-javascript 中新增 Browser CDN Bundle 的完整实操指南sentry javascript 中新增 Browser CDN Bundle 的完整实操指南 Sentry JavaScript SDK 为浏览器场景提供了可观测性上一篇Django Haystack 常见问题解决方案下一篇Pika 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
