企业官网建设流程全解析

• 可观测性

本指南以 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

顶层字段的完整定义见下表：

其中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 repo

name的命名规则要求以字母或数字开头，之后只能包含[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 skip

在install与update流程中，dotagents 会从源仓库自动发现全部技能，除exclude列表中的条目外逐一安装，且每个技能在锁文件中都拥有独立的条目（可在 agents.lock 中看到[skills.skill-scanner]这样的独立段落）。命令行中可用dotagents add <source> --all快速生成通配符条目。

来源格式（Source Formats）

其中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 domains

匹配语义如下：

• 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]]段落声明 MCP（Model 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 through

HTTP 传输（远程端点）

[[mcp]] name = "remote-api" # Required, unique server name url = "https://mcp.example.com/sse" # Required for HTTP

两种传输方式二选一：stdio 需要command，HTTP 需要url。env数组只透传变量名（值取自运行时环境，避免敏感信息写死进配置文件）；HTTP 模式可通过headers表携带鉴权头，例如headers = { Authorization = "Bearer token" }。

MCP 配置按 Agent 写入对应格式：

• Claude：.mcp.json（JSON）
• Cursor：.cursor/mcp.json（JSON）
• Codex：.codex/config.toml（TOML，与 Codex 其他配置共享）
• VS Code：.vscode/mcp.json（JSON）
• OpenCode：opencode.json（JSON，共享）

命令行为操作可参考 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" # Required

matcher缺省时钩子对所有工具生效；指定后仅命中对应工具名。钩子配置按 Agent 写入：

• Claude：.claude/settings.json（合并进已有文件）
• Cursor：.cursor/hooks.json（独立文件，事件映射为 Cursor 等价事件）
• VS Code：.claude/settings.json（与 Claude 共用同一文件）
• Codex/OpenCode：不支持，安装/同步时会输出警告

Cursor 事件映射关系为：PreToolUse→beforeShellExecution+beforeMCPExecution；PostToolUse→afterFileEdit；UserPromptSubmit→beforeSubmitPrompt；Stop→stop。作者仓库 .claude/settings.json 中即可看到手工配置的SessionStart钩子示例（执行scripts/claude-cloud-setup.sh），可作为钩子实际落盘格式的参照。

Lockfile（agents.lock）

agents.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-FWmCLdOj+x+XffiEg7Bx19drylVypeKz8me9OA757js="

本地路径技能（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的完整记录。

环境变量

• 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 之上还有两层配套文档值得串联使用：

1. dotagents SKILL 概览：掌握dotagents init / install / add / remove / update / sync / list / mcp的命令级用法与快速上手示例。若dotagents不是直接可用命令，可用npx @sentry/dotagents等价替代，例如npx @sentry/dotagents sync。
2. 配置指南：涵盖最小示例、通配符行为、信任校验时机、钩子事件映射、项目作用域与用户作用域切换、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 的第一步。

• 可观测性