企业官网建设流程全解析

1. 从零理解 Antigravity skill：SKILL.md 与 scripts 到底解决什么问题

Antigravity 里的 skill，本质上是把「一段可复用的操作流程」固化成一个文件夹，让智能体在合适的时机自动加载并执行。它不是一个插件市场里的黑盒，而是一个你能完全掌控的目录：一个SKILL.md定义「什么时候用、怎么用」，一个scripts/目录放「真正干活的代码」，再加可选的references/和assets/存放文档与静态资源。这套结构最直接的价值，是让「查 PostgreSQL 表结构、跑只读 SQL、把结果整理成表格」这类重复动作，从每次手动敲命令变成一句话触发。

我第一次接触这个概念时，最困惑的是它和普通 prompt 模板有什么区别。实测下来，区别在于三点：第一，skill 有明确的触发条件，写在 YAML frontmatter 的description里，智能体会对所有可用 skill 做语义匹配，命中才加载；第二，skill 的正文是持久化到文件的「提示工程」，激活后注入上下文，不依赖你每次重新描述；第三，也是最关键的，skill 可以把执行委托给脚本，让 LLM 去做它不擅长的事——比如精确的数据库连接、参数化查询、结果格式化。LLM 负责理解意图和生成 SQL，脚本负责稳定执行，职责分离。

这套设计对谁有用？如果你经常在本地或测试环境里反复查同一张表、核对数据状态、检查 schema 变更，或者团队里多人需要统一的数据排查流程，那 skill 就很合适。它适合项目特定的脚本，比如某个应用的数据管理、专有框架的样板代码生成；也适合全局工具，比如格式化 JSON、生成 UUID。Antigravity 把 skill 分成两个作用域：项目内放在<workspace-root>/agent/skills/，只在该项目可用；全局放在编辑器配置目录~/.gemini/antigravity/skills/，所有项目都能用。这个划分很实用——数据库连接这种带环境信息的，放项目内；纯工具类的，放全局。

本文要交付的，是一条完整可跟做的路径：从目录结构开始，写一个能触发 PostgreSQL 查询的SKILL.md，用scripts/query_runner.py封装查询与写入逻辑，再在 TaoToken 统一 Key/API 通道下完成调用验证。你会拿到可复制的模板、脚本骨架和本地验证动作。核心检索词就是 Antigravity skill 创建、SKILL.md 模板、scripts 封装 PostgreSQL。下面按步骤拆开讲，每一步都能直接落地。

2. TaoToken 前置准备：统一 Key 与 API 通道怎么配

在写 skill 之前，先把调用通道理顺。Antigravity 的 skill 在执行脚本或调用模型时，需要一个稳定的 API 入口。TaoToken 提供统一的 Key 和 API 通道，把模型调用收敛到一个 Base URL 上，这样 skill 里的脚本不用为每个模型单独维护密钥。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。

前置准备分三步。第一步，拿到 Key。进入控制台创建 API Key，路径是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面生成。生成的 Key 形如sk-开头的一串字符，复制后先存到本地环境变量，不要硬编码进脚本。第二步，确认模型 ID。不同模型有不同 ID，比如 Claude 系列、GPT 系列，具体以文档为准，文档入口 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。第三步，把 Base URL、Key、Model ID 三件套写进配置。

这里要强调一个容易踩的坑：skill 的脚本如果要调用模型，必须显式读取环境变量，而不是依赖编辑器注入。我试过把 Key 写在脚本里，结果提交到仓库时差点泄露。正确做法是用.env或系统环境变量，脚本里用os.environ.get("TAOTOKEN_API_KEY")读取。下面是一个最小配置示例，放在项目根目录的.env里：

TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_MODEL_ID=你的模型ID

如果你用的是 Claude Code 这类工具，配置方式略有不同，需要写进对应的 settings 文件。以 Claude Code 的 settings.json 为例，路径通常在~/.claude/settings.json，内容如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的实际Key", "ANTHROPIC_MODEL": "你的模型ID" } }

注意这里的 Base URL 用的是 TaoToken 的 API 地址，Key 和 Model ID 三件套必须齐全，缺一个都会导致 401 或模型找不到。如果你用的是 Codex，配置写在~/.codex/auth.json，结构类似，把 Base URL、Key、Model ID 对应填进去即可。Cline 或 MCP 场景下，配置通常写在 MCP server 的启动参数里，同样需要这三件套。

配好之后，先做一次最小验证，确认通道可用。用 curl 直接打一次模型对话接口：

curl -X POST "$TAOTOKEN_BASE_URL/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$TAOTOKEN_MODEL_ID"'", "messages": [{"role": "user", "content": "ping"}] }'

如果返回里有choices字段，说明通道通了。这一步很关键，因为 skill 的脚本最终也是走这条通道，前置不通，后面全白搭。验证模型是否正常，也可以直接在模型对话页面测试，入口 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。长期做编码或 Agent 任务的话，可以考虑 Coding Plan，入口 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，把额度集中管理。

3. 可复制配置：SKILL.md 模板与 scripts 目录结构

这一节是核心，直接给可复制的文件。先看目录结构。项目内 skill 放在<workspace-root>/agent/skills/下，我们建一个叫database-inspector的 skill：

agent/skills/database-inspector/ ├── SKILL.md ├── scripts/ │ └── query_runner.py ├── references/ │ └── schema-notes.md └── assets/ └── logo.png

SKILL.md是大脑，scripts/放执行逻辑，references/放文档，assets/放静态资源。逻辑、指令、知识三者分离，这是标准软件工程实践，也让 skill 更容易维护。

先写SKILL.md。它由两部分组成：YAML frontmatter 和 Markdown 正文。frontmatter 是元数据层，也是智能体做语义匹配的唯一依据。name非强制，范围内唯一，小写加连字符，不写则默认目录名；description是强制字段，充当触发短语，必须足够精确，让 LLM 能识别语义相关性。下面这个模板可以直接复制：

--- name: database-inspector description: Use this skill when the user asks to query the database, check table schemas, or inspect user data in the local PostgreSQL instance. 针对本地 PostgreSQL 数据库执行只读 SQL 查询以检索用户或事务数据，用于调试数据状态。 --- # Database Inspector ## Goal To safely query the local database and provide insights on the current data state. ## Instructions - Analyze the user's natural language request to understand the data need. - Formulate a valid SQL query. - CRITICAL: Only SELECT statements are allowed. - Use the script scripts/query_runner.py to execute the SQL. - Command: python scripts/query_runner.py "SELECT * FROM users LIMIT 10" - Present the results in a Markdown table. ## Examples Input: 查一下最近 10 个用户 Output: 调用 query_runner.py 执行 SELECT * FROM users ORDER BY created_at DESC LIMIT 10，返回 Markdown 表格。 ## Constraints - Never output raw user passwords or API keys. - If the query returns > 50 rows, summarize the data instead of listing it all. - 禁止运行 DELETE、UPDATE、DROP 等写操作。

注意description里我同时写了英文和中文触发短语，因为用户可能用任意语言提问，语义匹配覆盖面更广。正文里的Instructions是分步逻辑，Constraints是「禁止」规则，这两块是防止 skill 乱来的关键。

接下来写scripts/query_runner.py。它负责连接 PostgreSQL、执行 SQL、格式化输出。用psycopg2或psycopg都行，这里用psycopg2：

import os import sys import json import psycopg2 from psycopg2.extras import RealDictCursor DB_CONFIG = { "host": os.environ.get("PG_HOST", "localhost"), "port": os.environ.get("PG_PORT", "5432"), "dbname": os.environ.get("PG_DB", "postgres"), "user": os.environ.get("PG_USER", "postgres"), "password": os.environ.get("PG_PASSWORD", ""), } FORBIDDEN = ("delete", "update", "drop", "truncate", "alter", "insert") def is_readonly(sql: str) -> bool: lowered = sql.strip().lower() if not lowered.startswith("select"): return False return not any(word in lowered for word in FORBIDDEN) def run_query(sql: str): if not is_readonly(sql): return {"error": "Only SELECT statements are allowed."} conn = psycopg2.connect(**DB_CONFIG) try: with conn.cursor(cursor_factory=RealDictCursor) as cur: cur.execute(sql) rows = cur.fetchall() return {"rows": [dict(r) for r in rows], "count": len(rows)} finally: conn.close() if __name__ == "__main__": if len(sys.argv) < 2: print(json.dumps({"error": "No SQL provided."})) sys.exit(1) sql = sys.argv[1] result = run_query(sql) print(json.dumps(result, ensure_ascii=False, default=str))

这个脚本做了三件事：校验只读、执行查询、输出 JSON。is_readonly是双保险，即使 SKILL.md 里写了限制，脚本层再拦一次。数据库连接信息全部走环境变量，不硬编码。输出用 JSON，方便智能体解析后转成 Markdown 表格。

如果你需要写入逻辑，比如记录一次查询日志，可以再加一个scripts/log_writer.py，但要注意：写操作必须单独授权，不能和只读查询混在一个脚本里。SKILL.md 里对应加一条Constraints，明确写操作需要用户二次确认。这样职责清晰，也符合最小权限原则。

4. 验证请求与成功结果：本地跑通一次完整调用

配置写完，必须本地验证。验证分两层：先验脚本，再验 skill 触发。

第一层，直接跑脚本。确保 PostgreSQL 在本地或可访问，设置好环境变量：

export PG_HOST=localhost export PG_PORT=5432 export PG_DB=testdb export PG_USER=postgres export PG_PASSWORD=yourpassword python agent/skills/database-inspector/scripts/query_runner.py "SELECT id, name, created_at FROM users ORDER BY created_at DESC LIMIT 5"

成功的话，终端会输出类似：

{"rows": [{"id": 1, "name": "alice", "created_at": "2024-01-01T10:00:00"}], "count": 1}

如果报psycopg2.OperationalError，先检查数据库是否启动、端口是否对、密码是否正确。如果报Only SELECT statements are allowed，说明你的 SQL 被拦截了，这是预期行为，换成 SELECT 即可。

第二层，验 skill 触发。在 Antigravity 里打开项目，确保 skill 目录在<workspace-root>/agent/skills/下。然后发一句自然语言：「查一下最近 10 个用户」。智能体会对所有可用 skill 的description做语义匹配，命中database-inspector后加载 SKILL.md 正文，按 Instructions 生成 SQL，再调用query_runner.py执行。成功时你会看到它返回一个 Markdown 表格，类似：

这一步的关键是观察它有没有真的走脚本。如果它直接编造数据，说明脚本没被调用，检查 SKILL.md 里的Command路径是否写对，以及脚本是否有执行权限。我踩过的坑是路径用了绝对路径，换机器就失效，后来统一改成相对路径scripts/query_runner.py，由 skill 根目录解析。

第三层，验模型通道。如果 skill 里还调用了模型做 SQL 生成或结果总结，确保 TaoToken 的 Base URL、Key、Model ID 三件套生效。可以在脚本里加一段调用模型的逻辑，或者直接在 Antigravity 的对话里观察它是否正常返回。验证模型是否正常，也可以去模型对话页面单独测一次，入口 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

完整跑通后，你会得到一个可复用的数据库操作 skill：一句话触发，自动生成 SQL，脚本执行，结果表格化。整个过程不需要你每次手动敲命令，也不需要重复描述需求。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节对照真实报错，逐个排查。这些错误我在配置过程中基本都遇到过，按顺序说。

401 Unauthorized。最常见，原因是 Key 不对或没传。检查三处：环境变量TAOTOKEN_API_KEY是否设置、脚本里是否读取了它、请求头Authorization: Bearer是否拼写正确。如果是 Claude Code 场景，检查~/.claude/settings.json里的ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL是否齐全。三件套缺一不可：Base URL、Key、Model ID。401 基本就是 Key 或 Base URL 的问题。

local proxy failed。这个报错通常出现在本地网络层，说明请求没到达目标地址。检查 Base URL 是否写成了https://taotoken.net/api，注意不要多加斜杠或路径。如果你在脚本里用了代理配置，确认代理没有拦截。这个错误和 Key 无关，纯粹是地址或网络层的问题。

reading choices 报错。典型表现是Cannot read properties of undefined (reading 'choices')，说明返回体里没有choices字段。原因通常是模型 ID 写错，或者请求体格式不对。检查model字段是否和文档一致，messages是否是数组。如果返回的是错误对象，先打印完整响应体再定位。

OAuth 相关报错。如果你用的是需要 OAuth 的工具链，报错可能提示 token 过期或 scope 不足。这种情况下，重新走一次授权流程，或者改用 API Key 方式。TaoToken 的 API Key 方式不依赖 OAuth，配置更直接，推荐优先用 Key。

脚本执行权限问题。Linux/macOS 下如果脚本没有执行权限，会报Permission denied。解决方法是chmod +x scripts/query_runner.py，或者在 SKILL.md 的 Command 里显式写python scripts/query_runner.py，用解释器调用就不需要执行权限。

SQL 被拦截。如果脚本返回Only SELECT statements are allowed，说明你的 SQL 不是 SELECT 开头，或者包含了delete、update等关键词。这是预期行为，改成只读查询即可。如果确实需要写操作，单独建一个 skill，并在 Constraints 里明确要求用户确认。

skill 不触发。如果发了自然语言但 skill 没被加载，检查description是否足够精确。太笼统的描述会导致语义匹配失败。建议在 description 里同时写英文和中文触发短语，覆盖更多表达方式。另外确认 skill 目录位置正确：项目内是<workspace-root>/agent/skills/，全局是~/.gemini/antigravity/skills/。

排障时如果涉及接入配置，可以参考接入文档，入口 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。需要重新生成 Key 的话，去 API Keys 页面，入口 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

6. 把 skill 用起来：从数据库查询到长期编码工作流

跑通一个 skill 只是开始。真正有价值的是把它扩展成一套工作流。比如你有多个数据库环境，可以建多个 skill，用不同的description区分触发条件：「查本地 PostgreSQL」和「查测试环境 PostgreSQL」分别对应不同 skill，各自读不同的环境变量。这样一句话就能切换环境，不用手动改配置。

再进一步，把 skill 和长期编码任务结合。如果你经常做 Agent 类任务，需要模型持续参与代码生成、数据核对、结果总结，可以考虑 Coding Plan，入口 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，把额度集中管理，避免每次单独配 Key。Coding Plan 适合需要长期、稳定调用模型的场景，和 skill 的自动化触发配合起来，能省掉大量重复操作。

还有一个实用技巧：把references/用起来。比如把数据库的 schema 说明、常用查询模板、字段含义写进references/schema-notes.md，SKILL.md 里用相对路径引用。这样智能体在生成 SQL 时能参考这些知识，减少字段名猜错的情况。逻辑、指令、知识分离，维护起来也清晰——改 schema 只动 references，改流程只动 SKILL.md，改执行只动 scripts。

最后提醒一点：skill 的脚本不要直连生产库。生产环境的写操作风险太高，建议只在测试或本地环境用 skill 做查询和调试。如果确实需要生产数据，走只读账号，并在 Constraints 里明确禁止写操作。安全边界划清楚，skill 才能长期稳定地用下去。

整套流程走下来，你得到的不只是一个数据库查询工具，而是一套可复用的方法论：用 SKILL.md 定义触发与步骤，用 scripts 封装执行逻辑，用 TaoToken 统一调用通道，用 references 沉淀知识。这套结构可以套用到任何重复性工作上——部署脚本、日志分析、样板代码生成，思路都一样。先把一个 skill 跑通，再复制扩展，比一上来就设计复杂体系要靠谱得多。