@huicai/cli 2026.714.0 → 2026.721.0

package/skills/db-es/scripts/es-health.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+# Elasticsearch 健康检查（db-es 集群运维与事故清单的采集与初判）。只读 GET,curl/wget 双兜底。
+# 用法: sh es-health.sh [http://主机:9200] [-u 用户:密码]
+#   认证也可走环境变量 ES_AUTH=用户:密码(不进 ps);自签证书加 ES_INSECURE=1。
+ES="${1:-http://127.0.0.1:9200}"
+case "$ES" in -*) ES="http://127.0.0.1:9200";; esac
+AUTH="${ES_AUTH:-}"
+[ "$1" = "-u" ] && AUTH="$2"
+[ "$2" = "-u" ] && AUTH="$3"
+have() { command -v "$1" >/dev/null 2>&1; }
+get() {
+  if have curl; then
+    curl -s -m 15 ${AUTH:+-u "$AUTH"} ${ES_INSECURE:+-k} "$ES$1" 2>/dev/null
+  elif have wget; then
+    wget -q -T 15 -O - ${AUTH:+--user="${AUTH%%:*}" --password="${AUTH#*:}"} "$ES$1" 2>/dev/null
+  else
+    echo "__NO_TOOL__"
+  fi
+}
+H=$(get "/_cluster/health")
+[ "$H" = "__NO_TOOL__" ] && { echo "[缺工具] 无 curl/wget"; exit 3; }
+[ -z "$H" ] && { echo "[不可达] $ES (网络/认证 ES_AUTH/HTTPS 三查)"; exit 4; }
+jval() { echo "$H" | tr ',{}' '\n\n\n' | grep "\"$1\"" | head -1 | cut -d: -f2 | tr -d '" '; }
+FLAGS=""
+flag() { FLAGS="$FLAGS
+  [$1] $2"; }
+
+STATUS=$(jval status)
+echo "==== ES 健康检查 $ES ($(date '+%F %T')) ===="
+echo "集群: $(jval cluster_name)  状态: $STATUS  节点: $(jval number_of_nodes)  数据节点: $(jval number_of_data_nodes)"
+echo "分片: 活跃 $(jval active_shards)  重定位 $(jval relocating_shards)  初始化 $(jval initializing_shards)  未分配 $(jval unassigned_shards)"
+case "$STATUS" in
+  red) flag 红 "集群 RED:有主分片未分配 —— 数据不可用,先看下方 unassigned 原因";;
+  yellow) flag 黄 "集群 YELLOW:副本未分配(单节点集群的常态;多节点则查磁盘水位/分配规则)";;
+esac
+PT=$(jval number_of_pending_tasks)
+[ -n "$PT" ] && [ "$PT" -gt 50 ] 2>/dev/null && flag 黄 "pending_tasks=$PT —— master 忙不过来(小分片过多?db-es 分片规划)"
+
+echo ""
+echo "---- 磁盘与分配(85/90/95 三水位,锁了要手动解) ----"
+get "/_cat/allocation?v&h=node,disk.percent,disk.used,disk.total,shards" | head -8 | sed 's/^/  /'
+get "/_cat/allocation?h=disk.percent" | while read -r p; do
+  case "$p" in [0-9]*) [ "$p" -ge 85 ] 2>/dev/null && echo "  [红] 有节点磁盘 ${p}% ≥85% 水位 —— 索引将被限写/只读锁";; esac
+done
+
+echo ""
+echo "---- 未分配分片原因(RED/YELLOW 时看这里) ----"
+UN=$(jval unassigned_shards)
+if [ -n "$UN" ] && [ "$UN" != "0" ]; then
+  get "/_cat/shards?h=index,shard,prirep,state,unassigned.reason" | grep -v STARTED | head -10 | sed 's/^/  /'
+  echo "  (详因: GET /_cluster/allocation/explain —— 磁盘水位/分配过滤/节点丢失最常见)"
+else
+  echo "  无未分配分片"
+fi
+
+echo ""
+echo "---- 索引 TOP(大小与分片数,单分片 10-50G 经验带) ----"
+get "/_cat/indices?v&h=index,health,pri,rep,docs.count,store.size&s=store.size:desc" | head -12 | sed 's/^/  /'
+SMALL=$(get "/_cat/indices?h=index,store.size&bytes=mb" | awk '$2+0<50' | wc -l | tr -d ' ')
+[ -n "$SMALL" ] && [ "$SMALL" -gt 100 ] 2>/dev/null && flag 黄 "小索引(<50MB)有 $SMALL 个 —— 千级小分片拖垮 master 是日志集群头号病(rollover/合并)"
+
+echo ""
+echo "---- 线程池拒绝(write/search 拒绝=过载信号) ----"
+get "/_cat/thread_pool/write,search?v&h=node_name,name,active,queue,rejected" | head -10 | sed 's/^/  /'
+REJ=$(get "/_cat/thread_pool/write,search?h=rejected" | awk '$1+0>0' | head -1)
+[ -n "$REJ" ] && echo "  [黄] 有拒绝计数 —— 写侧攒批与 refresh_interval,查侧查深分页与大聚合(db-es)"
+
+echo ""
+echo "==== 结论 ===="
+if [ -n "$FLAGS" ]; then echo "异常项:$FLAGS"; else echo "未见明显异常(mapping 爆炸与同步断链要靠对账例程,快照抓不到)"; fi
+echo "处置对照: db-es 经典事故清单;JVM 堆与熔断详情: GET /_nodes/stats/jvm,breaker。"
+exit 0

package/skills/db-migration/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: db-migration
+description: 数据迁移链（模式判据(停机窗口/在线双写/CDC 追增量)→六步法(摸底/schema 映射/全量搬运限速/增量追平/三层校验/切换)→双写期纪律→脏数据处置台账→回退反向同步与放弃回退点→异构迁移坑清单(Oracle→MySQL/PG/信创库:空串 NULL/日期精度/序列/存储过程)→大规模搬运红线监控）。eng-database 与 eng-legacy 的迁移孙链:换库、分表迁移、机房搬迁、信创替库、"迁完数据对不上"时载入。
+version: 1.0.0
+---
+
+# 数据迁移链
+
+eng-database 与 eng-legacy 共同的迁移孙链。迁移的铁律一句话:**不校验的迁移=祈祷**;
+第二句:**搬运时长=数据量÷实测带宽,不是拍脑袋**(eng-complex-env 载荷缩放纪律的迁移版)。
+
+## 模式判据（按停机容忍选,别炫技）
+
+| 模式 | 适用 | 代价 |
+|---|---|---|
+| **停机窗口迁移** | 窗口够(量小或业务可停) | 最简单最可靠——**窗口够就选它,在线迁移是被逼的不是先进的** |
+| 在线双写迁移 | 不可停+应用可改造 | 应用侵入(双写代码)+双写期一致性维护 |
+| CDC 追增量 | 不可停+应用不可改 | 依赖 binlog/WAL 工具链;DDL 与特殊类型的 CDC 兼容要验 |
+
+混合常态:全量(快照)+CDC 追平+短暂只读窗口切换——把"停机 8 小时"压成"只读 5 分钟"。
+
+## 六步法
+
+1. **摸底**:量与增速(算搬运时长)/表清单与依赖(外键/触发器/视图/存储过程)/脏数据普查(违反目标库约束的数据先找出来:超长/非法日期/孤儿外键)/访问方普查(谁在连,eng-legacy 隐性依赖清单);
+2. **schema 映射**:类型映射表(逐类型确认精度与边界)/字符集(GBK→utf8mb4 的长度膨胀与乱码抽查)/约束与默认值差异/索引重建计划(**先裸表搬数后建索引**,快数倍)——异构场景深坑见下节;
+3. **全量搬运**:分批(按主键区间,断点可续,eng-complex-env 长任务纪律)/限速错峰(**从库拉取,别打主库**;目标库关闭部分约束与 binlog 加速判据)/进度外显(剩余时间可估);
+4. **增量追平**:水位推进(CDC 位点或时间戳),追平判据=延迟稳定在秒级;
+5. **三层校验**:行数对(按表按分区)→抽样字段对(随机+边界样本:最大最小/特殊字符/NULL)→**全量校验和**(按块 checksum,资金表必做)——差异定位到块再钻行;校验工具与迁移工具**分开实现**(同一套逻辑自己对自己=白对);**作业包**:`scripts/checksum-mysql.sql`+`checksum-postgres.sql`(三层校验与分块模板,含异构对齐与钻行)、`scripts/compare-reports.py`(两端 CSV 对比器,缺失/多出/行数/校验和四类差异,退出码可进切换门禁);
+6. **切换**:只读窗口(停写→追平最后增量→校验尾块)→切流(连接串/DNS/开关)→观察(业务勾稽指标,eng-legacy 观察清单)→回退预案在手(见回退节)。
+
+## 双写期纪律（在线迁移专用）
+
+写序:**主库(老)成功即返回成功**,副库(新)失败进补偿队列异步修(不许双库都同步等=可用性乘法);
+禁双主:双写期间读与"真相"只认老库,新库只追不服务(切换才反转);
+补偿队列监控(积压=新库有问题,清零才许切换);
+双写代码带开关(eng-release 发布开关),切换后限期拆(eng-legacy 防腐层拆除日期同则)。
+
+## 脏数据处置
+
+迁移是清洗时机不是搬垃圾时机:脏数据台账(问题/量/处置:修/弃/带病迁移)——
+**带病迁移要显式声明**(目标库放宽约束接住,记债后修),静默丢弃=对不上账的元凶;
+处置决策要业务签字(数据是业务的,不是 DBA 的,data-governance 裁决同源)。
+
+## 回退设计
+
+切换后回退窗口:**反向同步**(新库→老库 CDC,保持老库可回切)维持 N 天;
+**放弃回退点显式声明**:反向同步停止之日=只能向前——昭告并确认(过点之后的"回退"=一次新的迁移);
+回退演练:切换预演时连回退一起演(eng-complex-env 等价验证+eng-reliability 预案纪律)。
+
+## 异构迁移坑清单（Oracle→MySQL/PG/信创库高发）
+
+**空字符串 vs NULL**(Oracle '' = NULL,MySQL/PG 不是——判空逻辑与唯一约束行为全量排查,env-xinchuang 同坑);
+日期:精度(秒 vs 微秒)/零值日期(MySQL '0000-00-00' 别家不认)/时区语义;
+序列与自增:序列迁移要**续号**(新库起始值=老库当前值+安全余量,忘了=主键冲突);
+数值精度(NUMBER 不限精度→DECIMAL 定精度,超精度数据先查);
+大小写与排序规则(查询结果顺序变化惊扰业务,ORDER BY 显式化);
+存储过程与触发器:方言重写或下沉应用层(eng-legacy 判据——**迁移是去存储过程的最好时机**);
+分页与函数语法(应用侧 SQL 改造走方言层收口,env-xinchuang 架构策略);
+隐式类型转换行为差异(db-mysql 失效清单的跨库版:老库能跑的 SQL 新库可能全表扫,**迁移后 TOP SQL 全量 EXPLAIN 一遍**)。
+
+## 大规模专项（TB 级/十亿行级）
+
+影响生产红线监控:源库负载(从库延迟/IO)超阈值自动降速暂停(**迁移打挂生产=本末倒置**);
+分治:按业务域分波次迁移(一次全迁的爆炸半径不可控),波次间隔离(已迁表回源查询的兼容期方案);
+归档先行:冷数据先归档再迁移(搬运量减半的最便宜手段,eng-database 三板斧);
+时长预演:等价环境按同带宽同批次跑 1% 外推全量时长(误差>2 倍=方案重估)。
+
+## 使用纪律
+
+无三层校验不切换;回退窗口与放弃回退点写进方案评审;脏数据处置有业务签字;
+迁移窗口按实测外推排期(eng-planning);切换走 eng-release 变更流程+eng-ops 值守;
+每次迁移事故回写坑清单——**迁移做得好的标志:切换日无聊得像演练,因为它就是第 N 次演练**。

package/skills/db-migration/scripts/checksum-mysql.sql

@@ -0,0 +1,46 @@
+-- 迁移校验模板(MySQL 侧) —— db-migration 三层校验的可执行版。只读。
+-- 用法: 替换 <占位符> 后在源库与目标库各跑一遍,结果导出 CSV 再用 compare-reports.py 对比:
+--   mysql -h主机 -u用户 -p -N -B 库名 < checksum-mysql.sql > source.csv
+-- 注意: 源目标必须同一时点(停写窗口内,或对同一水位的快照/从库执行),否则差异无意义。
+
+-- ============ 第一层: 全库各表行数(粗筛,先跑这个) ============
+-- information_schema 的 table_rows 是估算值——只用于发现数量级差异;精确对比用第二层。
+SELECT CONCAT('rowcount_approx,', table_name, ',', IFNULL(table_rows,0), ',-')
+FROM information_schema.tables
+WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'
+ORDER BY table_name;
+
+-- ============ 第二层: 单表精确行数(逐张核心表跑) ============
+-- 每张要精确核对的表复制一行,别怕笨,笨的可靠:
+-- SELECT CONCAT('rowcount,<表名>,', COUNT(*), ',-') FROM <表名>;
+
+-- ============ 第三层: 分块校验和(资金表/核心表必做) ============
+-- 原理: 按主键分块,块内对"拼接列"求 CRC32 之和——两端逐块比对,差异定位到块再钻行。
+-- 占位说明:
+--   <表名>       目标表
+--   <主键>       整型主键列(字符串主键改用 CRC32(主键) 分块: FLOOR(CRC32(<主键>)/40000000))
+--   <块大小>     每块行数量级,10 万行左右(块太大定位慢,太小结果集大)
+--   <列清单>     参与校验的列,逗号分隔。注意:
+--                * 两端都有且语义相同的列(迁移改名列要在一侧起别名对齐);
+--                * 时间列统一格式化: DATE_FORMAT(t,'%Y-%m-%d %H:%i:%s')(精度差异会假阳,見链内异构坑);
+--                * 浮点列先 ROUND(x,2)(浮点直比=假阳之源);金额 DECIMAL 用 CAST(x AS CHAR);
+--                * NULL 由 CONCAT_WS 统一跳过——但"空串 vs NULL"语义差异(Oracle 系迁移)要先在
+--                  schema 映射阶段处理,这里检不出"两端都错得一致"的问题。
+SELECT CONCAT(
+  'checksum,<表名>#blk', FLOOR(`<主键>` / <块大小>), ',',
+  COUNT(*), ',',
+  IFNULL(SUM(CRC32(CONCAT_WS('#', <列清单>))), 0)
+)
+FROM `<表名>`
+GROUP BY FLOOR(`<主键>` / <块大小>)
+ORDER BY FLOOR(`<主键>` / <块大小>);
+
+-- ============ 附: 差异块钻行 ============
+-- 某块两端不一致时,对该块逐行输出行级指纹,diff 定位到行:
+-- SELECT <主键>, CRC32(CONCAT_WS('#', <列清单>)) FROM `<表名>`
+-- WHERE `<主键>` >= <块号>*<块大小> AND `<主键>` < (<块号>+1)*<块大小> ORDER BY `<主键>`;
+
+-- ============ 附: 大表跑法 ============
+-- 1) 在从库/快照上跑,别打主库(db-migration 大规模红线);
+-- 2) 逐表跑而不是一把梭(可断点续跑,eng-complex-env 长任务纪律);
+-- 3) 记录执行时的水位(如 max(更新时间)/binlog 位点),两端水位一致结果才可比。

package/skills/db-migration/scripts/checksum-postgres.sql

@@ -0,0 +1,39 @@
+-- 迁移校验模板(PostgreSQL 侧) —— db-migration 三层校验的可执行版。只读。
+-- 用法: 替换 <占位符> 后执行,结果导出 CSV 与另一端对比(compare-reports.py):
+--   psql -h主机 -U用户 -d库名 -At -F, -f checksum-postgres.sql > target.csv
+-- 与 MySQL 侧配对使用时,校验算法要两端一致(本模板与 checksum-mysql.sql 的 CRC32 对齐:
+-- PG 无内置 CRC32,用 md5 前 8 位十六进制转 bigint 求和——异构对比时 MySQL 侧需改用同款 md5 算法,
+-- 见文末"异构对齐"节;PG 同构迁移(PG→PG)直接两端跑本模板即可)。
+
+-- ============ 第一层: 全库各表行数(估算粗筛) ============
+SELECT 'rowcount_approx,' || relname || ',' || COALESCE(n_live_tup, 0) || ',-'
+FROM pg_stat_user_tables
+ORDER BY relname;
+
+-- ============ 第二层: 单表精确行数 ============
+-- SELECT 'rowcount,<表名>,' || COUNT(*) || ',-' FROM <表名>;
+
+-- ============ 第三层: 分块校验和 ============
+-- 占位: <表名> <主键>(整型;串主键用 ('x'||substr(md5(<主键>),1,8))::bit(32)::bigint 分块)
+--       <块大小>(10 万级) <列清单>(concat_ws 的参数,逐列 ::text;时间列 to_char 统一格式;
+--       浮点 round(x::numeric,2);NULL 由 concat_ws 跳过——空串语义差异先在映射层处理)
+SELECT 'checksum,<表名>#blk' || (<主键> / <块大小>) || ','
+       || COUNT(*) || ','
+       || COALESCE(SUM(('x' || substr(md5(concat_ws('#', <列清单>)), 1, 8))::bit(32)::bigint), 0)
+FROM <表名>
+GROUP BY <主键> / <块大小>
+ORDER BY <主键> / <块大小>;
+
+-- ============ 附: 差异块钻行 ============
+-- SELECT <主键>, md5(concat_ws('#', <列清单>)) FROM <表名>
+-- WHERE <主键> >= <块号>*<块大小> AND <主键> < (<块号>+1)*<块大小> ORDER BY <主键>;
+
+-- ============ 异构对齐(MySQL↔PG 对比时) ============
+-- 两端算法必须完全一致才可比。MySQL 侧改用与本模板同款 md5:
+--   SUM(CONV(SUBSTRING(MD5(CONCAT_WS('#', <列清单>)), 1, 8), 16, 10))
+-- 并逐列对齐 ::text 的格式化行为(布尔/日期/数值的字符串形态两库不同——
+-- 先抽 10 行两端打印 concat_ws 结果肉眼比对,格式对齐后再全量跑,省得白跑两小时)。
+
+-- ============ 附: 执行水位记录 ============
+-- SELECT 'watermark,pg_lsn,' || pg_current_wal_lsn() || ',-';   -- 源端记录位点
+-- 两端水位一致(停写窗口/同一快照)结果才可比(db-migration 六步法第 5 步)。

package/skills/db-migration/scripts/compare-reports.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# 迁移校验对比器（db-migration 三层校验的最后一步）。零依赖,python3 stdlib。
+# 输入: 两份 CSV(源/目标),行格式 = 类型,键,行数,校验和   (checksum-*.sql 的输出)
+#   如: rowcount,orders,1234567,-
+#       checksum,orders#blk12,100000,3812345678
+# 用法: python3 compare-reports.py source.csv target.csv [--max-show 20]
+#       python3 compare-reports.py --selftest
+# 退出码: 0=完全一致  1=有差异  2=参数/文件错误  —— 可直接接入切换前门禁(eng-release)。
+import sys
+import csv
+
+
+def load(path):
+    rows = {}
+    try:
+        with open(path, newline="", encoding="utf-8", errors="replace") as f:
+            for ln in csv.reader(f):
+                if not ln or len(ln) < 3 or ln[0].startswith("#"):
+                    continue
+                key = (ln[0].strip(), ln[1].strip())          # (类型, 表/块)
+                cnt = ln[2].strip()
+                chk = ln[3].strip() if len(ln) > 3 else "-"
+                if key in rows:
+                    print(f"[警告] {path} 重复键 {key},后者覆盖前者(检查 SQL 是否重复跑)")
+                rows[key] = (cnt, chk)
+    except OSError as e:
+        print(f"[错误] 读不了 {path}: {e}")
+        sys.exit(2)
+    return rows
+
+
+def compare(src, dst, max_show=20):
+    miss, extra, cnt_diff, chk_diff = [], [], [], []
+    for k, (c, h) in src.items():
+        if k not in dst:
+            miss.append(k)
+        else:
+            c2, h2 = dst[k]
+            if c != c2:
+                cnt_diff.append((k, c, c2))
+            elif h != "-" and h2 != "-" and h != h2:
+                chk_diff.append((k, h, h2))
+    extra = [k for k in dst if k not in src]
+
+    def show(title, items, fmt):
+        print(f"  {title}: {len(items)}")
+        for it in items[:max_show]:
+            print("    " + fmt(it))
+        if len(items) > max_show:
+            print(f"    ...(其余 {len(items) - max_show} 条略,--max-show 调大)")
+
+    total_bad = len(miss) + len(extra) + len(cnt_diff) + len(chk_diff)
+    print(f"== 对比结果: 源 {len(src)} 项 / 目标 {len(dst)} 项 ==")
+    if total_bad == 0:
+        approx = sum(1 for (t, _) in src if t == "rowcount_approx")
+        print("  全部一致 ✔")
+        if approx == len(src):
+            print("  [提醒] 仅对比了估算行数(rowcount_approx)——粗筛通过≠校验通过,")
+            print("         核心表补跑第二层精确行数与第三层分块校验(见 checksum-*.sql)。")
+        return 0
+    show("目标缺失(源有目标无 → 掉数据/没跑全)", miss, lambda k: f"{k[0]} {k[1]}")
+    show("目标多出(源无目标有 → 脏写/范围没对齐)", extra, lambda k: f"{k[0]} {k[1]}")
+    show("行数不一致", cnt_diff, lambda x: f"{x[0][1]}: 源={x[1]} 目标={x[2]} (差 {abs(int(x[1]) - int(x[2])) if x[1].isdigit() and x[2].isdigit() else '?'})")
+    show("校验和不一致(行数同但内容异 → 钻行模板定位)", chk_diff, lambda x: f"{x[0][1]}: 源={x[1]} 目标={x[2]}")
+    print("  处置索引: 缺失/多出→核对迁移范围与水位;行数差→增量没追平或过滤条件不一致;")
+    print("            校验和差→用 checksum-*.sql 末尾'差异块钻行'模板定位到行,按脏数据台账处置。")
+    return 1
+
+
+def selftest():
+    import tempfile, os
+    a = "rowcount,orders,100,-\nchecksum,orders#blk0,50,111\nchecksum,orders#blk1,50,222\nrowcount,users,10,-\n"
+    b = "rowcount,orders,100,-\nchecksum,orders#blk0,50,111\nchecksum,orders#blk1,50,999\nrowcount,extra_t,1,-\n"
+    with tempfile.TemporaryDirectory() as d:
+        fa, fb = os.path.join(d, "a.csv"), os.path.join(d, "b.csv")
+        open(fa, "w").write(a)
+        open(fb, "w").write(b)
+        rc = compare(load(fa), load(fb))
+        assert rc == 1, "应检出差异"
+        rc2 = compare(load(fa), load(fa))
+        assert rc2 == 0, "自比应一致"
+    print("selftest ok: 差异检出与一致判定均正常")
+    return 0
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:]]
+    if "--selftest" in args:
+        sys.exit(selftest())
+    max_show = 20
+    if "--max-show" in args:
+        i = args.index("--max-show")
+        max_show = int(args[i + 1])
+        del args[i:i + 2]
+    if len(args) != 2:
+        print(__doc__ or "用法: compare-reports.py source.csv target.csv [--max-show N] | --selftest")
+        sys.exit(2)
+    sys.exit(compare(load(args[0]), load(args[1]), max_show))

package/skills/db-mysql/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: db-mysql
+description: MySQL 深度链（8.0 基线→InnoDB 锁三型与间隙锁死锁高发场景→MVCC 长事务 undo 膨胀→聚簇索引心智与索引失效清单→buffer pool 调参→主从复制(ROW/GTID/延迟根因/并行回放)→online DDL 三算法判据与 gh-ost→双 1 参数与性能折衷→诊断动线→经典事故清单）。eng-database 的 MySQL 孙链:死锁排查、主从延迟、大表 DDL、参数调优、"这条 SQL 为什么不走索引"时载入。
+version: 1.0.0
+---
+
+# MySQL 深度链
+
+eng-database 的 MySQL 孙链。通用 schema/索引/事务纪律承 eng-database,此处只写 MySQL/InnoDB 特有判据。
+版本基线:8.0 起步(窗口函数/CTE/immediate 加列/不可见索引/降序索引),5.7 存量按迁移路径走(dependency-upgrade)。
+
+## InnoDB 锁三型（死锁排查的地基）
+
+- 记录锁(锁索引记录)/间隙锁(锁记录间空隙,RR 隔离级特有)/临键锁(记录+前隙,RR 默认)——**锁的是索引不是行**:无索引可用时锁全表扫过的所有记录(大范围 UPDATE 无索引=锁灾);
+- 间隙锁死锁高发场景背下来:并发"先查后插"(SELECT 不存在→INSERT,两事务各持同一间隙锁互等插入意向锁)——解法:唯一约束+直接 INSERT ON DUPLICATE/改乐观(捕获冲突重试);
+- RR vs RC 判据:RC 无间隙锁(死锁少、并发高)+必须 ROW binlog;RR 防幻读;**高并发写入系统评估 RC 是正经选项**(大厂常态),换级别要全量回归;
+- 加锁分析动线:`performance_schema.data_locks`(8.0)看谁持什么锁→`SHOW ENGINE INNODB STATUS` 的 LATEST DETECTED DEADLOCK 判读(两事务各持什么等什么)→按固定顺序改造(eng-database 死锁三防)。
+
+## MVCC 与长事务
+
+undo 链提供一致性读;**长事务三害具体化**:undo 不能清(histroy list length 涨,查询越来越慢)/阻塞 purge/大量锁持有——
+`information_schema.innodb_trx` 按时长巡检,>5s 告警(eng-database 同则),**框架默认开事务+慢外调=最常见根因**(事务边界收窄到真正需要的写段);
+history list length 进监控(eng-observability),持续高位=有长事务或 purge 跟不上。
+
+## 索引深度（聚簇索引心智）
+
+- **主键即数据**:表按主键组织,二级索引叶子存主键→主键越大所有二级索引越肥;主键必须递增趋势(eng-database UUIDv4 打碎 B+ 树的 MySQL 版解释);
+- 回表与覆盖:二级索引命中后拿主键回聚簇取整行;高频查询用覆盖索引免回表(EXPLAIN Extra: Using index);
+- ICP 索引条件下推:联合索引中范围后的列也能在引擎层过滤(5.6+自动,理解它才能读懂"为什么这样也不慢");
+- **索引失效清单**(评审与排障速查):列上函数/运算(`DATE(create_time)=` 改范围查询)、**隐式类型转换**(字符串列用数字查=全表扫,反向则可用)、隐式字符集转换(join 两表字符集不同)、前导通配 `LIKE '%x'`、OR 混合无索引列、联合索引跳过最左;
+- 直方图判据(8.0):不建索引又要优化器懂分布的低选择性列。
+
+## buffer pool 与核心参数
+
+buffer pool ≈ 物理内存 60–70%(专用机);命中率监控(Innodb_buffer_pool_read_requests vs reads);
+**双 1 与性能折衷**:`innodb_flush_log_at_trx_commit=1`+`sync_binlog=1`=不丢数据基线(金融必须);非关键库可评估 2/N 换吞吐,**丢数窗口要书面认账**(eng-ops 风险接受人);
+redo log 大小:写密集调大(checkpoint 压力),8.0.30+ 动态调;
+连接数:max_connections 配池上限对齐(eng-database 连接池公式),**别用加大连接数治慢查询**(治标致堵)。
+
+## 主从复制
+
+- binlog 格式 **ROW 默认**(STATEMENT 的非确定函数不一致坑);GTID 必开(故障切换与级联简单化);
+- 延迟根因四查:大事务(一把 UPDATE 百万行→分批)/单线程回放跟不上(并行复制按事务依赖,8.0 WRITESET 并行开起来)/从库配置弱或跑重查询/DDL 阻塞回放;
+- 延迟监控用心跳表(Seconds_Behind_Master 会说谎:大事务期间显示 0 然后跳变);
+- 半同步判据:关键库开(至少一从确认,丢数窗口收窄),超时退化行为要知道(退化成异步要告警);
+- 读写分离的读己之写(eng-database)在 MySQL 落地:会话粘性/关键读走主/GTID wait 判据。
+
+## online DDL 三算法与工具判据
+
+| 算法 | 操作示例 | 代价 |
+|---|---|---|
+| INSTANT | 8.0 加列(末尾)/改默认值 | 秒回,首选;有次数上限与限制条件,先查文档确认路径 |
+| INPLACE | 加索引/多数改动 | 不锁读写但耗 IO/CPU,大表仍要错峰;注意 metadata lock 等待(前面有长事务=后面全排队,**DDL 前先杀长事务**) |
+| COPY | 改类型/改字符集 | 锁写+双倍空间,大表禁直发 |
+
+大表(亿级)判据:gh-ost/pt-osc 外部工具(可限速/可暂停/可回退),配合 eng-database expand-contract 与变更窗口(eng-release);
+**每条 DDL 上线前**:EXPLAIN 语义确认+测试库同量级演练计时+磁盘余量检查(COPY/INPLACE 都吃临时空间)。
+
+## 诊断动线（从现象到根因）
+
+卡顿即刻三查:`SHOW PROCESSLIST`(谁在跑/State 堆积形态:Waiting for table metadata lock=DDL 阻塞链;Sending data=大扫描)→
+`SHOW ENGINE INNODB STATUS`(死锁/长事务/IO 状态)→ `performance_schema` 三表(data_locks/events_statements_summary 按耗时排/table_io_waits 热表);
+慢日志常开(long_query_time 1s 起,含未走索引记录判据)→ 周报治理(sql-tuning 承接执行计划优化);
+容量:表碎片(data_free 大=该 OPTIMIZE 错峰)/自增水位巡检(int 耗尽事故真实存在,eng-automation 例程)。
+**作业包**:`scripts/mysql-health.sql`(11 节只读巡检:长事务/锁等待/metadata lock/连接与命中率/history list/TOP 慢/自增水位/碎片/大表——`mysql < 文件` 即跑,例程化周跑留档比趋势)。
+
+## 经典事故清单（根因→防线）
+
+大事务撑爆(binlog 单文件暴涨/从库延迟雪崩→分批改+事务大小监控);间隙锁死锁风暴(见锁节改造);
+隐式转换全表扫拖垮(评审清单+慢日志抓);metadata lock 连环塞(DDL 前清长事务+低峰窗口);
+主键用随机字符串写入雪崩(页分裂,换趋势递增);字符集混用 join 失效(统一 utf8mb4);
+误删数据(生产禁裸 DML+延迟从库/binlog 闪回预案,eng-ops 四眼)。
+
+## 使用纪律
+
+RR/RC、双 1、并行复制等全局参数=架构决策(改动走 ADR+全量回归,eng-architecture);
+死锁日志每例必分析(不积攒);DDL 演练计时后再上生产;
+每次 MySQL 事故回写本链清单——**MySQL 的坑九成有名有姓,先查清单再开创新坑**。

package/skills/db-mysql/scripts/mysql-health.sql

@@ -0,0 +1,80 @@
+-- MySQL 健康巡检(db-mysql 诊断动线的可执行版)。全部只读 SELECT;8.0 为基线(5.7 差异见行内注)。
+-- 用法: mysql -h主机 -u用户 -p < mysql-health.sql | less   (或逐段复制执行)
+-- 例程化: 接 eng-automation 例程周跑,输出留档比对趋势。
+
+SELECT '==== 1. 长事务(>5s 告警,db-mysql 事务纪律) ====' AS section;
+SELECT trx_id, trx_state, TIMESTAMPDIFF(SECOND, trx_started, NOW()) AS run_seconds,
+       trx_rows_locked, trx_rows_modified, LEFT(IFNULL(trx_query,'(空:事务开着没在跑=框架默认开事务嫌疑)'),80) AS query_head
+FROM information_schema.innodb_trx
+WHERE TIMESTAMPDIFF(SECOND, trx_started, NOW()) > 5
+ORDER BY run_seconds DESC LIMIT 10;
+
+SELECT '==== 2. 当前锁等待(谁堵谁;5.7 用 sys.innodb_lock_waits) ====' AS section;
+SELECT r.trx_mysql_thread_id AS waiting_thread, LEFT(IFNULL(r.trx_query,''),60) AS waiting_query,
+       b.trx_mysql_thread_id AS blocking_thread, LEFT(IFNULL(b.trx_query,'(空:持锁不干活,查该会话)'),60) AS blocking_query,
+       TIMESTAMPDIFF(SECOND, r.trx_wait_started, NOW()) AS wait_seconds
+FROM performance_schema.data_lock_waits w
+JOIN information_schema.innodb_trx r ON r.trx_id = w.REQUESTING_ENGINE_TRANSACTION_ID
+JOIN information_schema.innodb_trx b ON b.trx_id = w.BLOCKING_ENGINE_TRANSACTION_ID
+LIMIT 10;
+
+SELECT '==== 3. metadata lock 等待(DDL 被长事务卡的形态) ====' AS section;
+SELECT id, user, db, time AS wait_seconds, state, LEFT(IFNULL(info,''),80) AS query_head
+FROM information_schema.processlist
+WHERE state LIKE '%metadata lock%' ORDER BY time DESC LIMIT 10;
+
+SELECT '==== 4. 连接水位(池公式对照,别用加连接治慢查) ====' AS section;
+SELECT v.variable_value AS max_connections,
+       (SELECT variable_value FROM performance_schema.global_status WHERE variable_name='Threads_connected') AS threads_connected,
+       (SELECT variable_value FROM performance_schema.global_status WHERE variable_name='Threads_running') AS threads_running,
+       (SELECT variable_value FROM performance_schema.global_status WHERE variable_name='Max_used_connections') AS max_used
+FROM performance_schema.global_variables v WHERE v.variable_name='max_connections';
+
+SELECT '==== 5. buffer pool 命中率(<99% 看内存与冷扫描) ====' AS section;
+SELECT ROUND(100 - 100 * rd.variable_value / GREATEST(rq.variable_value,1), 3) AS hit_pct,
+       rq.variable_value AS read_requests, rd.variable_value AS disk_reads
+FROM (SELECT variable_value FROM performance_schema.global_status WHERE variable_name='Innodb_buffer_pool_reads') rd,
+     (SELECT variable_value FROM performance_schema.global_status WHERE variable_name='Innodb_buffer_pool_read_requests') rq;
+
+SELECT '==== 6. history list length(高位=长事务/purge 滞后) ====' AS section;
+SELECT count AS history_list_length,
+       CASE WHEN count > 100000 THEN '<== 高位:先查第 1 节长事务' ELSE 'ok' END AS hint
+FROM information_schema.innodb_metrics WHERE name='trx_rseg_history_len';
+
+SELECT '==== 7. TOP 慢摘要(按总耗时;需 performance_schema 开启) ====' AS section;
+SELECT LEFT(digest_text, 90) AS query_pattern, count_star AS calls,
+       ROUND(sum_timer_wait/1e12, 1) AS total_s, ROUND(avg_timer_wait/1e9, 1) AS avg_ms,
+       sum_rows_examined AS rows_examined,
+       CASE WHEN sum_no_index_used > 0 THEN CONCAT('无索引 ', sum_no_index_used, ' 次') ELSE '' END AS no_index
+FROM performance_schema.events_statements_summary_by_digest
+WHERE schema_name IS NOT NULL AND schema_name NOT IN ('performance_schema','information_schema','mysql','sys')
+ORDER BY sum_timer_wait DESC LIMIT 10;
+
+SELECT '==== 8. 自增水位(>70% 提前扩类型;int 上限 21 亿) ====' AS section;
+SELECT t.table_schema, t.table_name, c.column_name, c.column_type, t.auto_increment,
+       ROUND(100 * t.auto_increment / (CASE
+         WHEN c.column_type LIKE 'tinyint%unsigned' THEN 255 WHEN c.column_type LIKE 'tinyint%' THEN 127
+         WHEN c.column_type LIKE 'smallint%unsigned' THEN 65535 WHEN c.column_type LIKE 'smallint%' THEN 32767
+         WHEN c.column_type LIKE 'int%unsigned' THEN 4294967295 WHEN c.column_type LIKE 'int%' THEN 2147483647
+         WHEN c.column_type LIKE 'bigint%unsigned' THEN 18446744073709551615 ELSE 9223372036854775807 END), 2) AS used_pct
+FROM information_schema.tables t
+JOIN information_schema.columns c ON c.table_schema=t.table_schema AND c.table_name=t.table_name AND c.extra LIKE '%auto_increment%'
+WHERE t.auto_increment IS NOT NULL AND t.table_schema NOT IN ('mysql','sys','information_schema','performance_schema')
+HAVING used_pct > 30 ORDER BY used_pct DESC LIMIT 15;
+
+SELECT '==== 9. 碎片 TOP(data_free 大→错峰 OPTIMIZE/重建) ====' AS section;
+SELECT table_schema, table_name, ROUND(data_length/1048576) AS data_mb,
+       ROUND(data_free/1048576) AS free_mb, ROUND(100*data_free/GREATEST(data_length+index_length,1),1) AS frag_pct
+FROM information_schema.tables
+WHERE table_schema NOT IN ('mysql','sys','information_schema','performance_schema') AND data_free > 100*1048576
+ORDER BY data_free DESC LIMIT 10;
+
+SELECT '==== 10. 大表 TOP(容量规划与归档候选,eng-database 三板斧) ====' AS section;
+SELECT table_schema, table_name, ROUND((data_length+index_length)/1073741824, 2) AS total_gb,
+       table_rows AS rows_approx, ROUND(index_length/GREATEST(data_length,1), 2) AS index_ratio
+FROM information_schema.tables
+WHERE table_schema NOT IN ('mysql','sys','information_schema','performance_schema')
+ORDER BY data_length+index_length DESC LIMIT 10;
+
+SELECT '==== 11. 复制状态提醒 ====' AS section;
+SELECT '从库上另跑: SHOW REPLICA STATUS\G (5.7: SHOW SLAVE STATUS\G);延迟看心跳表不信 Seconds_Behind_Master(大事务期间说谎,见 db-mysql 复制节)' AS note;

package/skills/db-postgres/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: db-postgres
+description: PostgreSQL 深度链（MVCC 死元组与 autovacuum 调优→XID 回卷停机风险→索引类型判据表(GIN/GiST/BRIN/部分/表达式)→EXPLAIN ANALYZE 读法与统计偏差→分区表判据→进程模型与 pgbouncer 池模式→流复制与复制槽堆积→JSONB 判据→必装扩展(pg_stat_statements/pgvector)→经典事故清单）。eng-database 的 PostgreSQL 孙链:表膨胀、vacuum 排障、复杂查询调优、PG 选型评估、pgvector 向量库时载入。
+version: 1.0.0
+---
+
+# PostgreSQL 深度链
+
+eng-database 的 PostgreSQL 孙链。通用纪律承 eng-database,此处只写 PG 特有判据。
+PG 的运维主旋律一句话:**伺候好 vacuum,盯住复制槽,连接要过池**。
+
+## MVCC 与 vacuum（PG 第一运维主题）
+
+- 机制心智:UPDATE=插新版本+旧版本成死元组(不像 InnoDB 用 undo)——**死元组留在表里,靠 vacuum 回收**;高更新表必然膨胀,治理是常态不是异常;
+- autovacuum 调优:默认参数对大表太保守(20% 变更才触发=亿级表攒两千万死元组)——大表按表调 `autovacuum_vacuum_scale_factor`(0.01 级)+成本限制放宽(vacuum 跑不动=白配);
+- **长事务阻塞 vacuum**:vacuum 只能清"所有活跃事务都看不见"的死元组——一个挂着的长事务让全库膨胀(idle in transaction 连接超时必配 `idle_in_transaction_session_timeout`);
+- 膨胀监控:pgstattuple/估算查询进巡检(eng-automation 例程),膨胀率>30% 治理(pg_repack 在线重建,VACUUM FULL 锁表禁生产直发);
+- **XID 回卷=停机事故**:32 位事务 ID 耗尽前必须冻结——监控 `age(datfrozenxid)`(>15 亿报警),autovacuum 被长事务/孤儿复制槽卡住时回卷风险陡增,这是 PG 最著名的"不管就宕机"。
+
+## 索引类型判据表（PG 的核心红利）
+
+| 类型 | 用于 | 要点 |
+|---|---|---|
+| btree | 默认(等值/范围/排序) | 同 eng-database 通则 |
+| GIN | jsonb 查询/数组包含/全文检索 | 写放大明显,写密集表慎;fastupdate 权衡 |
+| GiST | 几何/范围类型/邻近 | PostGIS 地基;排他约束(时间段不重叠)是隐藏神器 |
+| BRIN | 大表天然有序列(时序 append-only) | 索引极小;乱序表无效 |
+| 部分索引 | 只查子集(WHERE status='active') | 索引瘦身利器,条件要与查询完全匹配 |
+| 表达式索引 | 函数查询(lower(email)) | MySQL 失效清单里的场景 PG 能救,但统计信息另算 |
+
+复合技巧:covering index(INCLUDE 列免回表)/并发建索引 `CREATE INDEX CONCURRENTLY`(**生产建索引必须带,失败留 INVALID 索引要清理**)。
+
+## 查询计划与统计
+
+EXPLAIN ANALYZE 读法动线:**先比"估计行数 vs 实际行数"**(偏差 10 倍+=统计过期或相关性问题→ANALYZE/扩展统计 CREATE STATISTICS 多列相关)→
+看节点类型(Seq Scan 大表=缺索引或统计骗了/Nested Loop 内层大表=灾难,常因行数低估)→ 看 buffers(shared read 高=冷数据 IO);
+work_mem 判据:排序/哈希溢盘(Sort Method: external merge)则按查询级 SET 调,**全局调大=并发×work_mem 内存爆**;
+JIT 对短查询反噬(计划时间>执行时间时关);并行查询判据(大扫描聚合受益,OLTP 无感)。
+
+## 分区表
+
+判据:单表过亿或按时间滚动清理需求(**删旧数据=DETACH/DROP 分区秒级**,DELETE 亿行=灾难)——这是上分区的第一理由;
+声明式分区(RANGE 按时间默认);分区裁剪确认(EXPLAIN 看只扫目标分区,条件必须带分区键);
+陷阱:default 分区接了脏数据后加新分区会冲突扫描/唯一约束必须含分区键/分区数适度(千级起看规划器开销)。
+
+## 进程模型与连接池
+
+**每连接一进程=连接贵**(内存与调度成本远高于 MySQL 线程)——直连数百上千=性能悬崖;
+pgbouncer 事务池模式为默认(连接复用率最高),**代价背下来**:session 级特性失效(SET/预备语句/advisory lock 跨事务)——框架的 prepared statement 要配兼容模式或关;
+池链路:应用池(小)→pgbouncer→PG(max_connections 百级即可);
+`idle_in_transaction`/`statement_timeout` 双超时全局兜底(eng-database 三层超时的 PG 落地)。
+
+## 复制与高可用
+
+流复制(物理)默认:同步/异步判据同 MySQL 半同步逻辑(丢数窗口书面认账);
+**复制槽堆积=磁盘杀手**:槽保住 WAL 不清理,消费者(从库/CDC)断了不删槽→WAL 撑爆磁盘全库停写——孤儿槽监控是必配例程(eng-automation),`max_slot_wal_keep_size` 上保险;
+逻辑复制判据:跨版本升级(大版本升级正路:逻辑复制双跑切换)/异构同步(CDC 到 ES/数仓,db-es 与 eng-data-platform 衔接)/部分表订阅;DDL 不复制要人工同步(坑);
+故障切换:自动切换组件+脑裂防护,切换后旧主回收(pg_rewind)。
+
+## JSONB 判据
+
+灵活字段收纳(表单/配置/外部报文)合适;**查询频繁的字段提升为列**(jsonb 里查=GIN 索引+估行不准双税);
+jsonb_path_ops 索引更小(只支持 @>);更新整字段重写(高频局部更新的大 jsonb=膨胀加速器);
+"schema 无关"是幻觉:应用层仍要 schema 治理(eng-database 反预留字段同理)。
+
+## 必装扩展与生态
+
+`pg_stat_statements` 必装(慢查询聚合视图,sql-tuning 的数据源);`pgvector`(向量检索,ai-rag 的 PG 方案:中小规模知识库免引新库,HNSW 参数与召回率实测);
+PostGIS(地理)/`pg_trgm`(模糊搜索 LIKE '%x%' 能用上索引)——**扩展是 PG 选型的最大红利,选型评估时列进能力清单**(eng-research)。
+
+## 经典事故清单（根因→防线）
+
+膨胀失控查询变慢(autovacuum 参数+长事务治理);XID 回卷紧急冻结停服(age 监控);
+复制槽堆积磁盘满(孤儿槽巡检);连接耗尽(过池+双超时);
+CONCURRENTLY 建索引失败残留 INVALID(建后检查);大版本升级扩展不兼容(升级演练清单);
+死锁形态与 MySQL 不同(PG 无间隙锁,但外键触发的隐式锁与显式 LOCK 顺序仍会死锁,日志 log_lock_waits 开)。
+
+## 作业包
+
+`scripts/pg-health.sql`(十节只读巡检:XID 回卷/复制槽滞留/长事务与 idle-in-tx/死元组膨胀/relfrozenxid 老化/连接分布/INVALID 与零使用索引/大表/pg_stat_statements TOP/复制延迟——`psql -f 文件` 即跑;XID 与复制槽两节接告警)。
+
+## 使用纪律
+
+高更新核心表逐表核 autovacuum 参数;复制槽与 XID age 进监控;生产建索引必 CONCURRENTLY;
+连接一律过池并认账池模式限制;每次 PG 事故回写本链清单——
+**PG 强在能力密度,难在"默认参数只适合玩具库":上生产先过一遍参数与巡检清单。**