shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

TencentDB DatabaseClaw Skill

tencentdb-databaseclaw-skill

person作者: u_f4712daahubenterprise
download下载资源包

TencentDB-DatabaseClaw

Send messages to a DatabaseClaw instance via the CreateChatCompletion SSE API and receive streaming Agent responses.

When to Use

  • An AI agent needs to invoke DatabaseClaw for SQL execution, inspection, or data analysis
  • Building an AI workflow that integrates DatabaseClaw as a tool (LangChain / CrewAI / custom)
  • Verifying a DatabaseClaw instance is healthy by sending a test message
  • Cross-product function-calling where DBClaw acts as a backend tool

Not for: instance lifecycle management (isolate/restart/offline) — user must operate in the DatabaseClaw Console.

API Scope: This skill ONLY uses CreateChatCompletion (SSE chat) and CreateClawSession (create session for console visibility). No other APIs are supported.

Critical Facts (Must-Know Before Starting)

| Fact | Value | |------|-------| | SSE streaming host | tdai.ai.tencentcloudapi.com | | Non-streaming host (list/describe) | tdai.tencentcloudapi.com | | Service name (for TC3 signing) | tdai | | API version | 2025-07-17 | | Action (chat) | CreateChatCompletion | | Action (session) | CreateClawSession (non-streaming host) | | Required body fields | InstanceId, InputContent | | Optional body fields | ChatId (pass SessionKey here to link with console session list) | | Forbidden body fields | AppId, Uin, OwnerUin, IdempotencyKey (identity derived from AK/SK) | | Instance requirement | Status must be running | | SSE end marker | data: [DONE] | | Response wrapper | Frames may be wrapped in {"Response": {...}} — unwrap before parsing | | Heartbeat interval | 20 seconds (ignore these frames) | | Recommended timeout | 120s (covers 99% cases); complex multi-region scans may take 60-90s | | Timeout guidance | Simple Q&A: 2-5s; single query: 5-15s; multi-region scan: 30-90s |

Domain split is the #1 pitfall: CreateChatCompletion MUST hit tdai.ai.tencentcloudapi.com. Using tdai.tencentcloudapi.com returns InternalError.

Workflow

Step 0: Ensure Instance is Running

Before using this skill, the target DatabaseClaw instance must be in running status. If the instance is not running (API returns an error like "实例状态异常"), guide the user to:

  1. Open the DatabaseClaw Console
  2. Locate the target instance and ensure it is in "运行中" status
  3. If the instance is stopped/isolated, click "重启" or "解除隔离" in the console

Important: This skill only uses the CreateChatCompletion API (and optionally CreateClawSession). Instance lifecycle operations (restart/isolate/offline) are NOT supported via this skill — the user must operate them in the console.

Step 1: Session Creation (Default Behavior)

By default, chat.py automatically calls CreateClawSession (on tdai.tencentcloudapi.com) to get a SessionKey before sending the message. This makes the conversation visible in the console's session list page (会话列表).

# Default: session is created automatically
python3 scripts/chat.py --instance-id $INSTANCE_ID --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --message "hello"

To skip session creation (conversation won't appear in console list):

python3 scripts/chat.py --instance-id $INSTANCE_ID --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --no-session --message "hello"

Step 2: Send Message (Programmatic)

Use scripts/chat.py — two output modes:

  • Default (clean): Only final Agent response on stdout. Ideal for piping into other tools or Agent integrations.
  • --verbose / -v: Shows tool calls, reasoning, and connection info on stderr. Ideal for debugging and development.
# Clean mode (default) — only final answer on stdout
python3 scripts/chat.py \
  --instance-id $INSTANCE_ID \
  --secret-id $SECRET_ID \
  --secret-key $SECRET_KEY \
  --message "查询近7天慢查询 TOP 10"

Omit --message for interactive multi-turn mode.

Verbose mode (show tool calls and intermediate steps on stderr):

python3 scripts/chat.py -v \
  --instance-id $INSTANCE_ID \
  --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --message "查询ap-shanghai的MySQL实例"

For internal dev gateway (no signing needed):

python3 scripts/chat.py \
  --internal \
  --instance-id $INSTANCE_ID \
  --message "SELECT 1"

Step 3: Parse SSE Stream

The response is a standard SSE stream (data: {json}\n\n). Key event types:

| Event Object | Meaning | Action | |-------------|---------|--------| | (first frame, has ChatId) | Connection established | Store ChatId for multi-turn | | claw.tool_call | Agent calling a tool | Display progress (optional) | | claw.tool_result | Tool execution complete | Display result (optional) | | claw.partial / chat.chunk | Text chunk | Append to output buffer | | claw.final / FinishReason=stop | Stream complete | Close connection | | heartbeat | Keep-alive (every 20s) | Ignore | | "Error" key in Response | API error | Log and abort | | data: [DONE] | Hard stream end | Close connection |

Concatenate all Delta.Content values to form the complete Agent response.

Step 4: Integrate into Agent Framework

For Python integration with proper TC3 signing, see references/python-integration.md. The reference includes:

  • Verified tc3_sign() function
  • HTTP headers format
  • SSE stream parsing example
  • Error diagnosis table

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | InternalError | Wrong host (used tdai.tencentcloudapi.com) | Switch to tdai.ai.tencentcloudapi.com | | UnknownParameter | Body contains AppId/Uin/OwnerUin | Remove them; identity is from AK/SK | | MissingParameter (InputContent) | Missing required field | Add InputContent to body | | AuthFailure.SignatureExpire | Timestamp drift | Use int(time.time()), never datetime.utcnow() | | InvalidAuthorization | Wrong credential_scope | Must be YYYY-MM-DD/tdai/tc3_request | | Instance error in SSE | Instance not running | Go to DatabaseClaw Console and ensure instance is in "运行中" status | | Connection timeout | Instance stuck | Restart instance via console, retry |

TC3 Signing Checklist

When implementing TC3 signing manually (not using scripts/chat.py):

  1. Timestamp: int(time.time()) — never datetime.utcnow() (macOS timezone drift)
  2. SignedHeaders must include: content-type;host;x-tc-timestamp (alphabetical)
  3. credential_scope: {date}/tdai/tc3_request (service name = tdai)
  4. Host in canonical_headers: tdai.ai.tencentcloudapi.com (the SSE host)
  5. HTTP headers must include: X-TC-Action, X-TC-Version, X-TC-Region, X-TC-Timestamp, Authorization
  6. Accept header: text/event-stream

Full signing implementation: references/python-integration.md

Files

| Path | Purpose | |------|--------| | scripts/chat.py | Standalone CLI client — single message or interactive mode, zero external deps beyond stdlib | | references/python-integration.md | Complete TC3 signing code, HTTP headers, SSE parsing, error diagnosis |