sql-linker — SQL 链接器

重要：所有脚本/路径相对于此技能目录。运行方式：cd {skill_dir} && python scripts/... 或使用 cwd 参数。

SQL-Linker — 双层架构：数据操作层 + 业务层 / Data Ops + Business Layer 概述 / Overview （中文）SQL-Linker 提供跨数据库的 CRUD 操作能力，支持 MySQL、PostgreSQL、SQLite 三种主流数据库。内置审计日志模块，每次操作自动记录操作人身份、IP、SQL 语句、操作时间，确保数据可溯源、安全可控。业务层（db_bridge）负责字段白名单过滤和时间戳自动注入，数据操作层（sql_linker）负责连接管理、CRUD 执行和审计记录，两层严格分离，互不干扰。 （English）SQL-Linker provides cross-database CRUD operations, supporting MySQL, PostgreSQL, and SQLite, with a built-in audit trail module that automatically records operator identity, IP, SQL statements, and timestamps for full traceability and compliance. The business layer (db_bridge) handles field whitelist filtering and automatic timestamp injection, while the data operation layer (sql_linker) manages database connections, CRUD execution, and audit logging. The two layers are strictly separated and independent.

核心架构 / Core Architecture （中文）系统由两层组成，业务层和数据操作层职责分明： （English）The system consists of two layers with clearly defined responsibilities: workspace/ └── .sql_linker/ ← 配置文件根目录 ├── config_home/ │ ├── config.yaml ← 数据库连接配置 │ ├── audit_config.json ← 审计配置 │ └── extra_tables.json ← 特权表配置（JSON） └── table_home/ └── table_dictionary.json ← 主词典（JSON，所有受控表） skills/sql-linker/scripts/ ├── controller_layer/ ← 数据操作层 │ ├── sql_linker.py ← 连接管理 + CRUD 执行 + 审计上下文注入 │ └── sql_audit.py ← 审计模块（sql_linker.py 内部使用） └── service_layer/ ← 业务层 └── db_bridge.py ← 四层访问控制 + 时间戳注入 + 字段白名单

（中文）业务层（service_layer）：读取 table_dictionary.json，过滤字段，注入时间戳，校验访问权限，调用数据操作层，不直接操作数据库。 （English）Business Layer (service_layer): Reads table_dictionary.json, filters fields, injects timestamps, verifies access rights, and calls the data operation layer. Does not directly access the database.

（中文）数据操作层（controller_layer）：管理数据库连接，执行 CRUD 操作，写入审计日志，处理参数化查询，不处理业务逻辑。 （English）Data Operation Layer (controller_layer): Manages database connections, executes CRUD operations, writes audit logs, handles parameterized queries. Does not process business logic.

四层访问模型 / Four-Layer Access Model （中文）系统通过四层访问模型实现精确的表访问控制： （English）The system implements precise table access control through a four-layer access model: SYSTEM (系统表 sql_audit_log) Hard-coded: db_bridge.py SYSTEM_TABLES SELECT/INSERT: ALLOW UPDATE/DELETE: DENY (SystemTableWriteDenied) Field whitelist: N/A Timestamp injection: N/A Audit: Native cursor bypasses db_bridge Audit log cannot be tampered by business layer NORMAL (主词典表格) File: table_dictionary.json Field whitelist: YES (only fields in table.json) Timestamp injection: YES (created_at/updated_at auto-generated) Audit: Full Ready to use without extra config PRIVILEGED (特权表格) File: extra_tables.json + config.yaml extra_tables_enabled Field whitelist: NO (unknown schema, direct DB exposure) Timestamp injection: NO Audit: Full Requires extra_tables.json declaration + config enable BLOCKED (禁用) Not in dictionary nor extra_tables All operations denied, denial logged Cannot access unless added to extra_tables.json

（中文）访问判定流程：提取 SQL 中的表名 → 检查 SYSTEM → 检查主词典（NORMAL）→ 检查 extra_tables（PRIVILEGED）→ 其余 BLOCKED。 （English）Access Decision Flow: Extract table name from SQL → Check SYSTEM → Check main dictionary (NORMAL) → Check extra_tables (PRIVILEGED) → Rest BLOCKED.

引导初始化 / Bootstrap （中文）首次使用或缺少配置文件时，系统自动生成默认模板（幂等操作，不会覆盖已有文件）： （English）On first use or when config files are missing, the system automatically generates default templates (idempotent, will not overwrite existing files): from db_bridge import DBBridge db = DBBridge(user_label="openclaw-control-ui", session_id="agent:hr:main") created = db.bootstrap() print(f'Created: {created}') # ['...\\config.yaml', '...\\audit_config.json', ...]

（中文）自动生成的文件列表： （English）Auto-generated files: 文件路径 默认内容 .sql_linker/config_home/config.yaml 连接模板（host/port/user 占位，password_env 引用 .env） .sql_linker/config_home/audit_config.json 审计默认开启，log_select=false .sql_linker/config_home/extra_tables.json 特权表，默认关闭，max_extra_tables=10 .sql_linker/table_home/table_dictionary.json 带示例表的空模板 .sql_linker/.env 凭据占位符提示

配置文件说明 / Config Files table_home/table_dictionary.json — 主词典 / Main Dictionary （中文）所有受控业务表必须在主词典中声明，字段白名单仅对 NORMAL 层生效： （English）All controlled business tables must be declared in the main dictionary. Field whitelist only applies to NORMAL layer: { "version": 1, "tables": [ { "table_name": "supplier_table", "comment": "供应商信息表", "fields": [ { "name": "id", "type": "BIGINT", "pk": true, "auto": true }, { "name": "supplier_code", "type": "VARCHAR(32)", "pk": false, "auto": false }, { "name": "supplier_name", "type": "VARCHAR(128)", "pk": false, "auto": false }, { "name": "short_name", "type": "VARCHAR(32)", "pk": false, "auto": false } ] } ] }