Quick Start Examples
Scenario 1: Diagnose Instance Performance Issues (Recommended)
CODEBLOCK0
Scenario 2: Execute Instance Inspection
CODEBLOCK1
Scenario 3: SQL Optimization
CODEBLOCK2
Security
Credential Management
This skill supports two authentication modes:
- - Mode 1 - Password login (企业版（免费试用）): Requires
DBDOCTOR_URL, DBDOCTOR_USER, DBDOCTOR_PASSWORD. - Mode 2 - Email verification code login (免费版（永久免费）, Windows/Mac): Requires
DBDOCTOR_URL, DBDOCTOR_EMAIL. When a verification code is needed, the user will be prompted interactively.
If DBDOCTOR_EMAIL is configured, email mode takes precedence.
Credentials are managed by the platform and injected as environment variables at runtime. This skill does not write credentials to disk. The .token_cache file (API session token only) is the only file persisted locally and is listed in .gitignore.
Privileged Operations
Two tools perform write operations that require operator care:
- - execute\sql: Executes arbitrary SQL on the target database. Review all SQL statements before execution. The tool does not enforce read-only restrictions.
- manage\instance: Registers new database instances to the platform. Verify all connection parameters (IP, port, credentials) before execution.
All other tools are read-only queries against the DBdoctor API.
Authentication Mechanism
The program supports two login methods:
- 1. Password mode: Reads username/password from environment variables, AES-encrypts the password, and calls
/nephele/login to obtain a Token. - Email mode: Sends a verification code to the configured email via
/drapi/user/verificationCode, prompts the user to enter the code, AES-encrypts it, and calls /nephele/login with authType=authCode.
Token is cached in .token_cache. When the token expires, the system automatically re-authenticates (password mode is silent; email mode prompts for a new verification code). No manual auth management is required.
Configuration
Set the following environment variables based on your login mode:
| Variable | Description | Required |
|---|
| DBDOCTOR\URL | DBdoctor API base URL (e.g. http://host:port) | Always |
| DBDOCTOR\USER |
Login username (also used as UserId) | Password mode only |
| DBDOCTOR\_PASSWORD | Login password (sensitive) | Password mode only |
| DBDOCTOR\_EMAIL | Login email for verification code | Email mode only |
Note: If DBDOCTOR_EMAIL is set, email verification code mode is used. Otherwise, username/password mode is used.
Mode 1: Password login (企业版（免费试用）)
CODEBLOCK3
Mode 2: Email verification code login (免费版（永久免费）)
CODEBLOCK4
Manual configuration
Edit ~/.clawdbot/clawdbot.json:
CODEBLOCK5
System environment variables
CODEBLOCK6
Install Dependencies
CODEBLOCK7
Dependencies: requests, pycryptodome, python-dotenv
Instance Information Retrieval Guidelines
Important: When tenant and project information is needed, it must be dynamically retrieved through tools, and is prohibited from being extracted directly from user input.
Strictly prohibited from fabricating tenant and project information
Method 1: Retrieve via getcurrentuser (Recommended)
CODEBLOCK8
Method 2: Retrieve via get_instance (Recommended)
CODEBLOCK9
API Usage Constraints
Strictly prohibited from calling interfaces not defined in this document
- - Only use tools and interfaces listed in the API Reference
- Prohibited from fabricating or inferring interface paths
- Prohibited from calling interfaces of other systems or services
Tool Combination Patterns
Pattern 1: Performance Diagnosis Workflow (Most Common)
CODEBLOCK10
Pattern 2: Instance Inspection Workflow
CODEBLOCK11
Pattern 3: SQL Optimization Workflow
CODEBLOCK12
Pattern 4: New Instance Registration Workflow
CODEBLOCK13
Information Collection Matrix
| Task Type | Required Information | Collection Strategy | Notes |
|---|
| Query Instance | None | Call tool directly | Get instance list and tenant/project |
| Instance Inspection |
Instance ID |
Check -> Ask -> Call | tenant/project via get_instance |
|
Performance Diagnosis |
Instance ID + Time Range |
Check -> Ask -> Call | tenant/project via get_instance |
|
View Data |
Instance ID |
Check -> Ask -> Call | tenant/project via get_instance |
For detailed processing strategies, decision trees and rules: reference/agent_guidelines.md
Tool API Reference
For complete API documentation with parameters, examples, and related pages, see: reference/api_reference.md
Quick Reference: Parameter Requirements Summary
| Tool | Required Parameters |
|---|
| get\instance | None (returns all instances) |
| get\current\_user |
None (get current user tenant-project info) |
| get\
instance\abnormal | --instance-id |
| get\
database\by\_instance | --instance-id |
| manage\_instance | --ip, --port, --engine, --db-user, --db-password, --db-version, --tenant, --project |
| get\
slow\sql | --instance-id, --start-time, --end-time |
| get\
table\ddl | --instance-id, --database, --schema, --table |
| execute\_sql | --instance-id, --database, --schema, --sql, --engine, --tenant, --project |
| sql\_audit | --instance-id, --database, --schema, --sql |
| get\
sql\audit\_rules | --engine (optional), --priority (optional) |
| do\
inspect\instance | --instance-id, --tenant (optional), --project (optional) |
| get\
recent\inspect\_report | --instance-id, --start-time, --end-time, --tenant, --project |
| get\
inspect\item | None |
| get\
current\process | --instance-id |
| alert\_message | --status (optional), --priority (optional), --instance-ip (optional) |
| performance\_diagnosis | --instance-id, --start-time, --end-time (comprehensive, recommended) |
| get\
basic\monitor\_info | --instance-id, --start-time, --end-time |
| get\
host\resource\_info | --instance-id, --start-time, --end-time |
| get\
db\parameter\_info | --instance-id |
| get\
aas\info | --instance-id, --start-time, --end-time |
| get\
related\sql\_info | --instance-id, --start-time, --end-time |
| get\
instance\info | --instance-id |
| get\
slow\sql\
by\time | --instance-id, --start-time, --end-time |
| ai\
sql\rewrite | --instance-id, --database, --schema, --sql |
| get\
sql\rewrite\_result | --task-id |
Notes
- 1. Timestamps: Time range parameters use Unix timestamps (seconds), not milliseconds
- Schema: For MySQL, schema name equals database name
- Engine Types: mysql, oracle, postgresql, dm (Dameng), sqlserver, oracle-rac
- SQL Parameter: When --sql contains spaces or special characters, wrap in quotes
- tenant/project: Must be obtained via
get_instance — never fabricate or extract from user input - Time Range Default: Alert queries default to last 2 hours if not specified
- Performance Diagnosis: Recommended time ranges: last 1h, 6h, or 24h
Reference Document Index
- -
reference/api_reference.md - Complete Tool API Reference (parameters, examples, related pages) - INLINECODE19 - Performance Diagnosis Knowledge Base
- INLINECODE20 - Best Practices Guide
- INLINECODE21 - SQL Audit Rules and Inspection Rules
- INLINECODE22 - Common Issues and Solutions
- INLINECODE23 - Agent Processing Strategies and Decision Guidelines
快速入门示例
场景一：诊断实例性能问题（推荐）
bash
1. 获取租户和项目
python scripts/get
currentuser.py --extract
2. 获取实例列表
python scripts/get_instance.py --tenant [租户] --project [项目]
3. 执行全面的性能诊断（最近1小时）
python scripts/performance_diagnosis.py --instance-id [实例ID] --start-time [开始时间戳] --end-time [结束时间戳]
场景二：执行实例巡检
bash
1. 获取实例的租户和项目
python scripts/get_instance.py
2. 执行巡检
python scripts/do
inspectinstance.py --instance-id [实例ID] --tenant [租户] --project [项目]
3. 获取巡检报告
python scripts/get
recentinspect_report.py --instance-id [实例ID] --start-time [开始时间] --end-time [结束时间] --tenant [租户] --project [项目]
场景三：SQL优化
bash
1. 获取慢SQL列表
python scripts/get
slowsql.py --instance-id [实例ID] --start-time [开始时间] --end-time [结束时间]
2. 审核慢SQL
python scripts/sql_audit.py --instance-id [实例ID] --database [数据库] --schema [模式] --sql [SQL语句]
3. 使用AI重写SQL（可选）
python scripts/ai
sqlrewrite.py --instance-id [实例ID] --database [数据库] --schema [模式] --sql [SQL语句]
安全
凭证管理
本技能支持两种认证模式：
- - 模式1 - 密码登录（企业版（免费试用））：需要 DBDOCTORURL、DBDOCTORUSER、DBDOCTORPASSWORD。
- 模式2 - 邮箱验证码登录（免费版（永久免费），Windows/Mac）：需要 DBDOCTORURL、DBDOCTOR_EMAIL。当需要验证码时，将交互式提示用户输入。
如果配置了 DBDOCTOR_EMAIL，则优先使用邮箱模式。
凭证由平台管理，并在运行时作为环境变量注入。本技能不会将凭证写入磁盘。 .token_cache 文件（仅包含API会话令牌）是唯一持久化到本地的文件，并已在 .gitignore 中列出。
特权操作
有两个工具执行需要操作者谨慎处理的写操作：
- - executesql：在目标数据库上执行任意SQL。执行前请检查所有SQL语句。该工具不强制执行只读限制。
- manageinstance：向平台注册新的数据库实例。执行前请验证所有连接参数（IP、端口、凭证）。
所有其他工具都是针对DBdoctor API的只读查询。
认证机制
程序支持两种登录方式：
- 1. 密码模式：从环境变量读取用户名/密码，对密码进行AES加密，并调用 /nephele/login 获取Token。
- 邮箱模式：通过 /drapi/user/verificationCode 向配置的邮箱发送验证码，提示用户输入验证码，进行AES加密，并通过 authType=authCode 调用 /nephele/login。
Token 缓存在 .token_cache 中。当Token过期时，系统会自动重新认证（密码模式静默处理；邮箱模式会提示输入新的验证码）。无需手动管理认证。
配置
根据您的登录模式设置以下环境变量：
| 变量 | 描述 | 是否必需 |
|---|
| DBDOCTORURL | DBdoctor API基础URL（例如 http://host:port） | 始终需要 |
| DBDOCTORUSER |
登录用户名（也用作UserId） | 仅密码模式 |
| DBDOCTOR_PASSWORD | 登录密码（敏感信息） | 仅密码模式 |
| DBDOCTOR_EMAIL | 用于验证码的登录邮箱 | 仅邮箱模式 |
注意：如果设置了 DBDOCTOR_EMAIL，则使用邮箱验证码模式。否则，使用用户名/密码模式。
模式1：密码登录（企业版（免费试用））
bash
CLI配置（推荐）
clawdbot skills config dbdoctor-tools DBDOCTOR_URL http://[主机]:[端口]
clawdbot skills config dbdoctor-tools DBDOCTOR_USER [用户名]
clawdbot skills config dbdoctor-tools DBDOCTOR_PASSWORD [密码]
模式2：邮箱验证码登录（免费版（永久免费））
bash
CLI配置（推荐）
clawdbot skills config dbdoctor-tools DBDOCTOR_URL http://[主机]:[端口]
clawdbot skills config dbdoctor-tools DBDOCTOR_EMAIL [邮箱]
手动配置
编辑 ~/.clawdbot/clawdbot.json：
json5
{
skills: {
entries: {
dbdoctor-tools: {
env: {
// 模式1：密码登录
DBDOCTOR_URL: http://[主机]:[端口],
DBDOCTOR_USER: [用户名],
DBDOCTOR_PASSWORD: [密码]
// 模式2：邮箱登录（使用此项替代USER/PASSWORD）
// DBDOCTOR_URL: http://[主机]:[端口],
// DBDOCTOR_EMAIL: [邮箱]
}
}
}
}
}
系统环境变量
bash
Linux / Mac - 密码模式
export DBDOCTOR_URL=http://[主机]:[端口]
export DBDOCTOR_USER=[用户名]
export DBDOCTOR_PASSWORD=[密码]
Linux / Mac - 邮箱模式
export DBDOCTOR_URL=http://[主机]:[端口]
export DBDOCTOR_EMAIL=[邮箱]
Windows PowerShell - 密码模式
$env:DBDOCTOR_URL=http://[主机]:[端口]
$env:DBDOCTOR_USER=[用户名]
$env:DBDOCTOR_PASSWORD=[密码]
Windows PowerShell - 邮箱模式
$env:DBDOCTOR_URL=http://[主机]:[端口]
$env:DBDOCTOR_EMAIL=[邮箱]
安装依赖
bash
pip install -r requirements.txt
依赖项：requests, pycryptodome, python-dotenv
实例信息获取指南
重要：当需要租户和项目信息时，必须通过工具动态获取，禁止直接从用户输入中提取。
严禁伪造租户和项目信息
方法1：通过 getcurrentuser 获取（推荐）
- 1. 调用 getcurrentuser --extract 获取所有租户和项目
- 选择目标租户和项目
- 调用 get_instance --tenant xxx --project yyy
- 选择目标实例并执行其他操作
方法2：通过 get_instance 获取（推荐）
- 1. 调用 get_instance 查询所有实例（无需参数）
- 从返回数据中找到目标实例
- 从实例数据中提取租户和项目
API使用约束
严禁调用本文档未定义的接口
- - 仅使用API参考中列出的工具和接口
- 禁止伪造或推断接口路径
- 禁止调用其他系统或服务的接口
工具组合模式
模式1：性能诊断工作流（最常见）
getcurrentuser --extract
|
get_instance --tenant xxx --project yyy
|
performance_diagnosis --instance-id xxx --start-time t1 --end-time t2
|
[根据诊断结果]
- 大量慢SQL -> sqlaudit / aisql_rewrite
- 资源瓶颈 -> gethostresourceinfo / getbasicmonitorinfo
- 高活跃会话 -> getaasinfo / getcurrentprocess
模式2：实例巡检工作流
getinstance -> doinspectinstance -> getrecentinspectreport
模式3：SQL优化工作流
getslowsql / getrelatedsqlinfo -> sqlaudit -> aisqlrewrite (如果需要)
模式4：新实例注册工作流
getcurrentuser --extract -> manageinstance -> getinstance (确认)
信息收集矩阵
| 任务类型 | 所需信息 | 收集策略 | 备注 |
|---|
| 查询实例 | 无 | 直接调用工具 | 获取实例列表及租户/项目 |
| 实例巡检 |
实例ID |
检查 -> 询问 -> 调用 | 通过 get_instance 获取租户/项目 |
|
性能诊断 |
实例ID + 时间范围 |
检查 -> 询问 -> 调用 | 通过 get_instance 获取租户/项目 |
|
查看数据 |
实例ID |
检查
