Claude Skill for kingbase 人大金仓：把数据库连接配置改到 TaoToken

1. 为什么要在 KingbaseES 场景里给 Claude 配一个 Skill

KingbaseES（人大金仓）在国内政企、金融、能源项目里出现频率很高，它兼容 PostgreSQL 协议，但很多团队在写 Claude Skill 时，数据库连接和模型调用是两套割裂的配置：数据库走本地环境变量，模型走另一套 Key，结果调试时经常出现「SQL 能跑通但模型不响应」或者「模型响应了但连不上库」的割裂状态。我试过把这两条链路收敛到同一个通道，具体做法是让 Skill 里的模型调用统一走 TaoToken 的 API 通道，数据库连接参数则通过环境变量注入，这样一份配置就能同时覆盖「连库」和「调模型」两件事。

这篇文章面向的是已经在用 Claude Skills 做数据库辅助操作、但还没把模型调用通道统一起来的开发者。核心检索词是 Claude Skill for kingbase 配置，也就是怎么在人大金仓这个具体数据库场景下，把 Skill 的目录结构、连接参数模板、模型调用地址一次性配好，并且能跑一次完整的「提问 → 生成 SQL → 执行 → 校验结果」动作来确认配置生效。

KingbaseES 本身是 PostgreSQL 兼容的，所以大部分 PG 的 Python 驱动（比如 psycopg2）可以直接用，端口默认常见的是 54321 而不是 PG 的 5432，这一点在写连接模板时容易踩坑。Skill 的价值在于：当你对 Claude 说「帮我查一下 kingbase 里 test 库的订单表结构」时，它能自动触发对应的脚本，而不是让你每次手动拼连接串。

把模型调用收敛到 TaoToken 的好处是，Skill 里所有需要调用大模型的地方（比如生成 SQL、解释执行计划、做 SQL 校验）都指向同一个 Base URL 和 Key，不用在多个供应商之间来回切换配置。下面我会先给出 Skill 的目录结构，再给连接参数模板，然后是可直接复制的配置片段，最后演示一次完整调用和结果校验。

2. TaoToken 前置准备：Key、Base URL 与 Skill 目录结构

在写 Skill 之前，先把 TaoToken 这边的准备工作做完。你需要一个可用的 API Key，以及确认 Base URL 是https://taotoken.net/api。这两个东西是后面所有配置片段的基础，缺一个 Skill 里的模型调用就会报 401。

2.1 获取 API Key 与确认 Base URL

进入控制台创建 API Key，路径是 console 页面。创建完成后你会拿到一串以sk-开头的 Key，这个 Key 只显示一次，建议直接写进环境变量而不是硬编码在脚本里。Base URL 固定用https://taotoken.net/api，注意这个地址后面不加任何 UTM 参数，保持干净。

如果你还没创建过 Key，可以先到 API Keys 页面生成一个。模型对话页面可以用来快速验证 Key 是否可用，不用写代码就能发一条测试消息。

2.2 Skill 目录结构

一个标准的 kingbase Skill 目录长这样，你可以直接照着建：

skills/ └── kingbase/ ├── SKILL.md ├── scripts/ │ ├── connect.py │ ├── query.py │ ├── execute.py │ ├── schema.py │ └── validate.py └── references/ ├── syntax.md ├── validation_rules.md └── best_practices.md

SKILL.md是入口文件，里面写清楚 name、description 和触发条件。scripts/放实际干活的 Python 脚本，references/放语法参考和校验规则。Claude 在识别到「kingbase / 人大金仓 / KingbaseES」并且意图和数据库操作相关时，会去读SKILL.md然后调用对应脚本。

2.3 SKILL.md 的最小写法

SKILL.md不需要写得很复杂，关键是让 Claude 知道什么时候触发、触发后调用哪个脚本。一个可用的最小版本：

--- name: kingbase description: 面向 KingbaseES（人大金仓）的数据库操作 Skill，支持连接、查询、DML/DDL 执行、结构探查与 SQL 校验。 --- # KingbaseES Skill 当用户提到 kingbase、人大金仓、KingbaseES 且意图涉及数据库操作时触发。 ## 可用脚本 - scripts/connect.py：测试连接 - scripts/query.py：执行 SELECT - scripts/execute.py：执行 DML/DDL - scripts/schema.py：探查库表结构 - scripts/validate.py：SQL 校验 ## 模型调用 所有需要模型推理的步骤统一走 TaoToken 通道，Base URL 为 https://taotoken.net/api。

这里把模型调用通道写进 SKILL.md 的描述里，是为了让 Claude 在处理 SQL 生成、校验这类需要推理的任务时，知道该往哪个地址发请求。实际发请求的逻辑放在脚本里，下面会给配置片段。

3. 可复制配置：连接参数模板与模型调用片段

这一节是全文最核心的部分，所有片段都可以直接复制。配置分两块：数据库连接参数（走环境变量）和模型调用参数（走 TaoToken）。两块都配好，Skill 才能完整跑起来。

3.1 数据库连接环境变量模板

KingbaseES 的连接参数通过环境变量注入，这样脚本里不用写死密码。把下面这段放进你的 shell 配置文件（比如~/.bashrc或~/.zshrc），或者直接在运行 Skill 的会话里 export：

export KINGBASE_HOST=localhost export KINGBASE_PORT=54321 export KINGBASE_DATABASE=test export KINGBASE_USER=system export KINGBASE_PASSWORD=your_password export KINGBASE_SCHEMA=public export KINGBASE_CONNECT_TIMEOUT=10

注意KINGBASE_PORT默认是 54321，不是 PostgreSQL 的 5432。如果你连的是远程库，把localhost换成实际地址。KINGBASE_SCHEMA默认public，如果你们的库用了自定义 schema，这里要改。

3.2 模型调用配置片段（JSON 格式）

Skill 里调用模型的部分，统一走 TaoToken。下面是一个 JSON 格式的配置片段，可以放在 Skill 的配置目录里，比如skills/kingbase/config.json：

{ "model_provider": { "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "model_id": "claude-sonnet-4-20250514", "timeout": 60 }, "kingbase": { "host_env": "KINGBASE_HOST", "port_env": "KINGBASE_PORT", "database_env": "KINGBASE_DATABASE", "user_env": "KINGBASE_USER", "password_env": "KINGBASE_PASSWORD", "schema_env": "KINGBASE_SCHEMA", "connect_timeout_env": "KINGBASE_CONNECT_TIMEOUT" } }

这里api_key_env指向TAOTOKEN_API_KEY，也就是说你的 Key 存在这个环境变量里，脚本运行时去读。model_id填你要用的模型 ID，具体可用的模型列表可以在模型对话页面确认。

3.3 把 Key 写进环境变量

export TAOTOKEN_API_KEY=sk-你的实际Key

如果你用的是 Claude Code 这类工具，配置方式会略有不同，通常在settings.json里指定 Base URL 和 Key。但核心三件套是一样的：Base URL、Key、Model ID。这三样在 TaoToken 的接入文档里都有说明，配置时对照着填就行。

3.4 连接脚本示例

scripts/connect.py负责测试数据库连接，读环境变量，用 psycopg2 建连接：

import os import psycopg2 def get_connection(): return psycopg2.connect( host=os.environ["KINGBASE_HOST"], port=os.environ["KINGBASE_PORT"], dbname=os.environ["KINGBASE_DATABASE"], user=os.environ["KINGBASE_USER"], password=os.environ["KINGBASE_PASSWORD"], connect_timeout=int(os.environ.get("KINGBASE_CONNECT_TIMEOUT", 10)), ) if __name__ == "__main__": conn = get_connection() print("连接成功，KingbaseES 版本：", conn.server_version) conn.close()

跑这个脚本之前，确保psycopg2已经装好，pip install psycopg2-binary即可。如果连接成功，会打印出 KingbaseES 的版本号。

3.5 模型调用脚本示例

scripts/validate.py里调用模型做 SQL 校验，走 TaoToken 通道：

import os import requests def call_model(prompt: str) -> str: base_url = "https://taotoken.net/api" api_key = os.environ["TAOTOKEN_API_KEY"] resp = requests.post( f"{base_url}/v1/messages", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "model": "claude-sonnet-4-20250514", "max_tokens": 1024, "messages": [{"role": "user", "content": prompt}], }, timeout=60, ) resp.raise_for_status() return resp.json()["content"][0]["text"]

这段代码把 Base URL 和 Key 都从环境变量和常量里取，没有硬编码敏感信息。resp.raise_for_status()会在 401 或 4xx 时直接抛异常，方便定位问题。

4. 验证请求：从本地调用到结果校验的完整动作

配置写完之后，必须跑一次完整动作来确认生效。这一节演示从「提问」到「生成 SQL」到「执行」到「校验结果」的全过程，每一步都有可复现的命令和预期输出。

4.1 第一步：确认数据库连接可用

先跑连接脚本：

python skills/kingbase/scripts/connect.py

预期输出类似：

连接成功，KingbaseES 版本： 120003

如果这一步就报错，先别往下走，去看第 5 节的排查部分。连接不通的话，后面模型调用再正常也没用。

4.2 第二步：确认模型调用通道可用

单独测一下模型调用，不掺数据库逻辑：

python -c " import os, requests r = requests.post( 'https://taotoken.net/api/v1/messages', headers={'Authorization': f'Bearer {os.environ[\"TAOTOKEN_API_KEY\"]}', 'Content-Type': 'application/json'}, json={'model': 'claude-sonnet-4-20250514', 'max_tokens': 64, 'messages': [{'role': 'user', 'content': '回复 OK 两个字母'}]}, timeout=30, ) print(r.status_code) print(r.json()['content'][0]['text']) "

预期输出：

200 OK

如果返回 401，说明 Key 不对或者没读到环境变量。如果返回 404，检查 Base URL 是不是写成了带路径的地址。

4.3 第三步：让 Skill 生成一条查询 SQL

现在把两步合起来。假设你对 Claude 说：「帮我查一下 kingbase 里 test 库 public schema 下有哪些表」。Skill 会先调模型生成 SQL，再执行。模型调用部分走 TaoToken，生成的 SQL 类似：

SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name;

这一步的关键是模型调用和数据库连接用的是同一份配置来源，不会出现「模型以为连的是 A 库，实际连的是 B 库」这种错位。

4.4 第四步：执行并校验结果

把生成的 SQL 交给query.py执行：

python skills/kingbase/scripts/query.py --sql "SELECT table_name FROM information_schema.tables WHERE table_schema='public' ORDER BY table_name;"

预期输出是一张表名列表。如果表为空，说明 schema 里确实没表，或者 schema 名字不对。到这里，一次完整的「提问 → 生成 → 执行 → 校验」就完成了。如果每一步都符合预期，说明你的 Skill 配置已经生效。

4.5 第五步：用校验脚本做一次 SQL 安全校验

最后跑一下validate.py，让模型对一条待执行 SQL 做安全校验：

python skills/kingbase/scripts/validate.py --sql "DROP TABLE orders;"

预期模型会返回类似「该语句为 DDL 删除操作，建议确认表名并备份后再执行」的提示。这一步验证的是模型调用通道在 Skill 内部工作正常，且能对危险操作给出拦截建议。

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

配置过程中最容易撞上的几类报错，这里逐个对照。每个报错都给出触发场景和修复动作，你可以按报错信息直接定位。

5.1 401 Unauthorized

触发场景：模型调用返回 401。原因通常是 Key 没读到、Key 写错、或者 Key 已经失效。检查TAOTOKEN_API_KEY环境变量是否存在：

echo $TAOTOKEN_API_KEY

如果输出为空，说明没 export 成功。如果输出有值但还是 401，去 API Keys 页面确认这个 Key 是否还在有效期内。注意 Key 只在创建时显示一次，如果丢了只能重新创建。

5.2 local proxy failed

触发场景：请求发不出去，报连接失败。这个报错通常和本地网络环境有关，不是 TaoToken 侧的问题。检查你的请求地址是不是写成了https://taotoken.net/api，有没有多写或少写路径。另外确认本机没有设置会拦截请求的环境变量，比如HTTP_PROXY之类。如果你在容器里跑，确认容器能访问外网。

5.3 reading choices 相关报错

触发场景：解析模型响应时失败，报类似reading 'choices'的错误。这通常是因为你按 OpenAI 的响应格式去解析，但实际返回的是 Anthropic 格式。TaoToken 的/v1/messages接口返回的是content数组，不是choices。把解析代码从resp.json()["choices"][0]["message"]["content"]改成resp.json()["content"][0]["text"]即可。

5.4 OAuth 相关报错

触发场景：如果你用的是 Claude Code 这类工具，可能会遇到 OAuth 登录相关的报错。这类工具通常支持两种认证方式：OAuth 登录和 API Key。如果你要走 TaoToken 通道，应该在配置里指定 Base URL 和 API Key，而不是走 OAuth 流程。检查settings.json里是否同时配了 OAuth 和 API Key，两者冲突时优先用 API Key 配置。

5.5 连接超时

触发场景：connect.py卡住然后报超时。检查KINGBASE_HOST和KINGBASE_PORT是否正确，KingbaseES 默认端口是 54321。如果连的是远程库，确认防火墙放行了对应端口。KINGBASE_CONNECT_TIMEOUT默认 10 秒，网络慢的话可以调大。

5.6 三件套检查清单

如果你用的是 CC Switch、Cline MCP 或 Codex 这类工具，配置时确保三件套齐全：

三件套缺任何一个，调用都会失败。Base URL 写错会 404，Key 写错会 401，Model ID 写错会报模型不存在。

6. 把配置固化下来：长期使用与 CTA

配置跑通之后，建议把环境变量写进 shell 配置文件，这样每次开新会话都自动生效。如果你用的是 Claude Code 做长期编码，可以考虑 Coding Plan，它适合需要持续调用模型做代码生成和 SQL 辅助的场景。如果只是偶尔验证模型是否可用，模型对话页面更轻量，不用写代码就能测。

对于需要频繁接入不同项目的团队，把 Skill 目录做成模板仓库是个好习惯。每次新项目只需要改环境变量里的 host、port、database，模型调用部分完全不用动，因为 Base URL 和 Key 是统一的。这样切换项目时不会出现「这个项目用 A 通道、那个项目用 B 通道」的混乱。

接入文档里有更详细的参数说明和示例，配置过程中遇到不确定的字段可以去对照。API Keys 页面用来管理你的 Key，建议定期轮换。如果你还没决定用哪种方式长期使用，可以先从模型对话页面快速验证，确认通道可用后再决定是否上 Coding Plan。

最后提醒一点：Skill 里的数据库连接参数和模型调用参数要分开管理，前者走环境变量，后者走配置文件加环境变量。不要把数据库密码和 API Key 混在同一个文件里，也不要把它们提交到版本库。跑通一次完整动作之后，把配置片段保存下来，下次新项目直接复用，能省掉大量重复调试的时间。