@huicai/cli 2026.714.0 → 2026.721.0

package/skills/data-chain/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: data-chain
+description: 数据技能链总控（口径治理→加工分析→指标看板→汇报自动化全链→技能路由与端到端工作流）。当数据诉求跨环节（"从原始表到月度经营看板""新指标从定义到上线"）或不确定用哪个技能时先载入。
+version: 1.0.0
+---
+
+# 数据技能链总控
+
+## 场景路由表
+
+| 数据环节 | 高频场景 | 技能 |
+|---|---|---|
+| 口径与治理 | 指标字典/质量规则/主数据/分级脱敏 | **data-governance** |
+| 大表加工 | 清洗/关联/勾稽/对账 | **data-report-pro**（普通表 xlsx-analysis） |
+| 分析建模 | 统计/分群/归因/预测口径 | data-analysis + marketing-analytics(RFM) + ecommerce-ops(LMDI) |
+| 因果实验 | AB 设计/样本量/SRM/显著性 | **ab-testing** |
+| 指标体系 | 北极星/驱动树/护栏 | **metrics-system** |
+| 可视化呈现 | 图表规范/交互报告/看板架构 | data-analysis + metrics-system(信息架构) |
+| 汇报交付 | 分析报告/汇报页/数据附录 | docx-author + slides-html + xlsx-analysis |
+| 自动化 | 日报周报例程/异常预警 | **office-automation** |
+
+## 端到端工作流
+
+### ① 月度经营数据链（每月跑）
+取数与口径核对（data-governance 字典为准,**口径争议先裁决再出数**）→ data-report-pro
+加工（字典→清洗→关联校验→勾稽,中间表落盘）→ 指标计算（metrics-system 驱动树逐节点,
+异常节点下钻归因）→ 可视化（data-analysis 规范:一图一事+中文字体）→ 报告
+（结论卡先行,每数可溯源）→ 汇报页（slides-html KPI 版式）→ 归档（`数据/YYYY-MM/`
+含代码与中间表——**下月复算得出同样的数**）。
+
+### ② 新指标上线链（按需）
+需求澄清（要回答什么问题→metrics-system 反推指标）→ 定义评审（口径伪 SQL 级+Owner+
+与既有指标查重——同名冲突走 data-governance 裁决流程）→ 试算验证（历史数据回填,
+与相邻指标勾稽:新指标与老指标矛盾必有一错）→ 字典登记+看板上线（信息架构定位:
+进哪屏答哪问）→ 观察期（两周内异常波动复核口径）→ 转常态监控（质量规则挂上,
+断更/跳变自动告警）。
+
+### ③ 数据异常追查链（告警触发）
+异常确认（是数据错还是业务真变了——**先查数据链路再惊动业务**:上游到位?口径变更公告?
+质量规则触发记录?）→ 数据侧排查（data-report-pro 守恒校验逐段定位）→
+业务侧归因（维度下钻+事件对照）→ 结论分发（数据缺陷→源头系统整改单;业务异常→
+经营预警报告）→ 复盘（该异常应有的质量规则补上——**每次事故换一条规则,规则库就是免疫系统**）。
+
+## 自动化例程配方
+
+- 核心指标日报：驱动树 TOP 节点日更,环比超阈值标红并附初步下钻;
+- 数据质量周报：规则通过率+新增异常清单按源头系统分组;
+- 月度经营数据链整链例程化（D+3 自动出初稿,人工归因后发布）;
+- 字典巡检：季度扫描无 Owner/超评审期指标清单。
+
+## 使用纪律
+
+无字典口径的数字不出报告（先补登记）;敏感数据出域前过脱敏清单（data-governance）;
+一切结论可复算（代码+中间表+版本归档）。

package/skills/data-governance/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: data-governance
+description: 数据治理（指标口径管理、数据质量规则、主数据治理、数据分级分类、数据字典体系）。当用户说"口径打架/指标对不上/数据质量/主数据/数据标准/数据资产盘点"时使用。
+version: 1.0.0
+---
+
+# 数据治理（口径有主，质量有规则，敏感有分级）
+
+## 指标口径治理（治"同名不同数"）
+
+- **指标三件套**：业务定义（人话一句）+ 计算口径（表/字段/过滤/聚合的伪 SQL 级精确）+
+  **唯一 Owner**（口径变更只有 Owner 能批）;
+- 指标字典表：指标名/别名/定义/口径/维度约束/更新频率/Owner/下游引用/生效版本——
+  data-report-pro 的任务级字典升级为组织级资产;
+- 同名冲突处理流程：冲突登记 → Owner 裁决（合并/改名/共存但强制带口径后缀,
+  如"GMV_下单口径/GMV_支付口径"）→ 下游通知与切换期;
+- **口径变更=数据事故高发区**：变更三要素（生效日期/新旧对照/历史数据是否重刷）公告后才可上线。
+
+## 数据质量（规则化，不靠人肉)
+
+六维规则表（每条规则:维度/对象/规则描述/检测逻辑/阈值/责任人/处置动作）：
+完整性（关键字段空值率<X%）/ 唯一性（主键重复=0）/ 一致性（跨表勾稽:明细汇总=汇总表,
+data-report-pro 承接）/ 及时性（T+1 到位时点）/ 准确性（与权威源抽样比对）/
+有效性（枚举值域/格式校验）;
+质量报告节奏：规则跑批 → 异常清单派单 → 周报（规则通过率趋势+TOP 问题源头系统）——
+**质量问题按源头系统归因**,在下游修数是止痛不是治病。
+
+## 主数据治理（客户/物料/供应商/组织）
+
+- 识别主数据域（跨 ≥2 系统使用+相对稳定）;
+- 合并去重规则：匹配键分级（统一社会信用代码=强匹配;名称+地址=弱匹配需人工）,
+  **黄金记录**生成规则（字段级取信优先级:工商数据>CRM>手工）;
+- 变更管理：主数据变更走申请-审核-分发,禁止下游各自维护副本;
+- 落地检查：新系统接入必须消费主数据服务而非自建客商表（架构评审检查项）。
+
+## 数据分级分类与使用
+
+四级参考（公开/内部/敏感/机密）×分类（个人信息/经营/财务/技术）——每级给
+处理要求（存储加密/传输/导出审批/脱敏规则/保留期限）;
+个人信息处理清单（目的/最小必要/委托处理——具体合规义务建议咨询专业律师,
+转 risk-compliance 数据合规专项）;
+**分析场景的脱敏纪律**：给模型/给外部的数据先过脱敏清单（姓名/证件/手机/精确地址）。
+
+## 数据资产盘点
+
+存量盘点表（系统/库表/负责人/更新状态/下游引用/最后访问）→ 僵尸表清理
+（无访问+无下游 → 归档流程）;报表盘点同理（无人看的报表停更是最大的降本）。
+
+## 验收自查
+
+- [ ] 每个指标有唯一 Owner 与精确口径
+- [ ] 质量规则可执行有阈值,问题按源头归因
+- [ ] 主数据匹配键分级,黄金记录规则明确
+- [ ] 敏感数据处理要求落到动作

package/skills/data-report-pro/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: data-report-pro
+description: 大型复杂数据报表处理（十万~百万行、多表关联、跨表勾稽、对账差异定位、数据字典）。当用户给出大数据量表格/多份关联报表要求"对账/合并/勾稽/找差异/建数据字典"时使用。
+version: 1.0.0
+---
+
+# 大型复杂报表（经 run_python；十万行以上按本法作业，普通表格用 xlsx-analysis 即可）
+
+## 三条铁律
+
+1. **数据字典先行**：不清楚每列的业务含义、主键、口径（含税否/币种/期间）就开始算 = 必错。
+   先产出 `数据字典.md`（列名/含义/类型/空值率/取值示例/口径存疑点），存疑点问用户。
+2. **总量守恒校验**：任何过滤/关联/去重后，立即核对行数与关键金额的变化并 print——
+   「合并后金额少了 3.7 万」必须当场发现，而不是在结论里。
+3. **结论可复算**：所有中间表落盘（parquet/csv），报告里的每个数字都能指回生成它的代码段。
+
+## 大数据量读取（内存与速度）
+
+```python
+# CSV 十万行以上：先采样定 dtype，再全量（内存省 50–80%）
+sample = pd.read_csv(f, nrows=5000)
+dtypes = {c: 'float32' for c in sample.select_dtypes('float').columns}
+dtypes |= {c: 'category' for c in sample.select_dtypes('object').columns if sample[c].nunique() < 1000}
+df = pd.read_csv(f, dtype=dtypes, parse_dates=[...])   # 千万级再用 chunksize 分块聚合
+# Excel 大文件：openpyxl read_only 引擎逐行流式；多 Sheet 大表逐 Sheet 处理，勿一次读全
+```
+`read_skill_file` 读本技能 `scripts/bigdata.py`：dtype 压缩 / 分块聚合 / 安全合并 / 对账差异定位四个可复用函数。
+
+## 多表关联（合并即风险）
+
+- merge 一律带 `validate=`（'1:1'/'1:m'）与 `indicator=True`，print 双侧未匹配行数与样例；
+- 关联键先做**清洗对表**：strip/大小写/全半角/前导零——「看起来一样连不上」九成栽在这里；
+- 禁止对含重复键的表做 1:1 合并硬算。
+
+## 跨表勾稽与对账（对账差异定位五步法）
+
+1. 总额层：双方总金额/总行数差多少（方向与量级）；
+2. 维度层：按 日期→机构→科目 逐维 groupby diff，锁定差异集中在哪些桶；
+3. 明细层：对差异桶做**双向反连接**（A有B无 / B有A无 / 双有但金额不等 三张清单）；
+4. 归因：每张清单抽样看原因（时间切割/口径/重复/漏记），归因要有证据行；
+5. 报告：`对账报告.xlsx`——汇总页(差异瀑布) + 三张明细清单 + 归因说明，xlsx-analysis 样式落盘。
+
+## 复杂指标与报表生成
+
+- 期间对比（同比/环比/YTD）统一用日期维表驱动，不手拼字符串；
+- 报告数字与图表**同源**：先算出结果表，再由结果表出图（禁止图和文各算一遍）；
+- 大报告 = 「Excel 结果簿（多 Sheet 带格式）+ Word 分析报告（docx-author）+ 关键图（data-analysis 字体规范）」三件套。
+
+## 长任务作业法
+
+十万行 × 多表的活按阶段推进并 todo_write 跟踪：字典 → 清洗 → 关联校验 → 勾稽 → 归因 → 成稿;
+每阶段中间产物落盘,阶段结论 print——被打断后从最近阶段续作,不重跑全程。
+
+## 验收自查
+
+- [ ] 数据字典产出且口径存疑点已确认
+- [ ] 每次过滤/合并后的行数与金额变化都有 print 记录
+- [ ] 对账差异做到明细级三清单，归因有证据行
+- [ ] 报告中的每个数字可指回代码与中间表
+
+## 附件
+
+- `scripts/bigdata.py` — read_csv_lean（dtype 压缩）/ chunk_agg（分块聚合）/ safe_merge（校验合并）/ recon_diff（双向对账三清单）；可直接执行自测
+
+> 本技能属 **Excel 与数据分析链**——19 项数据能力路由与端到端工作流见 `excel-analysis-chain`。

package/skills/data-report-pro/scripts/bigdata.py

@@ -0,0 +1,79 @@
+# 大型报表四件套（经 run_python 执行）：dtype 压缩读取 / 分块聚合 / 校验合并 / 双向对账。
+# 直接执行本文件 = 自测：构造 5 万行数据演练全部函数并断言。
+import pandas as pd
+import numpy as np
+
+
+def read_csv_lean(path, sample_rows=5000, **kw):
+    """先采样推 dtype 再全量读：float→float32、低基数字符→category，内存省 50–80%。"""
+    sample = pd.read_csv(path, nrows=sample_rows, **kw)
+    dtypes = {c: 'float32' for c in sample.select_dtypes('float').columns}
+    for c in sample.select_dtypes('object').columns:
+        if sample[c].nunique(dropna=True) < max(1000, sample_rows // 10):
+            dtypes[c] = 'category'
+    df = pd.read_csv(path, dtype=dtypes, **kw)
+    print(f'[read_csv_lean] {path} -> {df.shape}, 内存 {df.memory_usage(deep=True).sum()/1048576:.1f}MB')
+    return df
+
+
+def chunk_agg(path, by, agg, chunksize=200_000, **kw):
+    """千万级 CSV 分块 groupby 聚合（sum/count 类可分配聚合）。agg 如 {'金额':'sum'}。"""
+    parts = []
+    for chunk in pd.read_csv(path, chunksize=chunksize, **kw):
+        parts.append(chunk.groupby(by, observed=True).agg(agg))
+    out = pd.concat(parts).groupby(level=list(range(len(by) if isinstance(by, list) else 1))).sum()
+    print(f'[chunk_agg] 分块 {len(parts)} 次 -> {out.shape}')
+    return out.reset_index()
+
+
+def safe_merge(a, b, on, how='left', validate='1:m', amount_col=None):
+    """带体检的 merge：打印双侧未匹配数与金额守恒检查，匹配异常直接抛错。"""
+    m = a.merge(b, on=on, how=how, validate=validate, indicator=True)
+    stat = m['_merge'].value_counts().to_dict()
+    print(f'[safe_merge] on={on} how={how} 匹配统计={stat}')
+    if amount_col and amount_col in a.columns:
+        d = float(a[amount_col].sum()) - float(m[m['_merge'] != 'right_only'][amount_col].sum())
+        print(f'[safe_merge] {amount_col} 守恒差={d:.2f}')
+        if abs(d) > 1e-6:
+            raise AssertionError(f'合并后 {amount_col} 不守恒（差 {d:.2f}）：先查重复键/过滤条件')
+    return m.drop(columns=['_merge'])
+
+
+def recon_diff(a, b, key, amount, tol=0.005):
+    """双向对账 → 三清单：A有B无 / B有A无 / 双有额不等；并打印差异总览。"""
+    ka = a.groupby(key, as_index=False, observed=True)[amount].sum()
+    kb = b.groupby(key, as_index=False, observed=True)[amount].sum()
+    m = ka.merge(kb, on=key, how='outer', suffixes=('_A', '_B'), indicator=True)
+    only_a = m[m['_merge'] == 'left_only'].drop(columns='_merge')
+    only_b = m[m['_merge'] == 'right_only'].drop(columns='_merge')
+    both = m[m['_merge'] == 'both'].drop(columns='_merge')
+    diff = both[(both[amount + '_A'] - both[amount + '_B']).abs() > tol]
+    total = float(ka[amount].sum() - kb[amount].sum())
+    print(f'[recon] 总差={total:.2f} | A有B无 {len(only_a)} 条 | B有A无 {len(only_b)} 条 | 金额不等 {len(diff)} 条')
+    return {'only_a': only_a, 'only_b': only_b, 'diff': diff, 'total_gap': total}
+
+
+if __name__ == '__main__':
+    import tempfile, os
+    rng = np.random.default_rng(7)
+    n = 50_000
+    df = pd.DataFrame({
+        '机构': rng.choice(['华东', '华南', '华北'], n),
+        '单号': np.arange(n),
+        '金额': rng.uniform(10, 1000, n).round(2),
+    })
+    p = os.path.join(tempfile.mkdtemp(), 'big.csv')
+    df.to_csv(p, index=False, encoding='utf-8')
+    lean = read_csv_lean(p)
+    assert len(lean) == n and str(lean['机构'].dtype) == 'category'
+    agg = chunk_agg(p, '机构', {'金额': 'sum'}, chunksize=12_000)
+    assert abs(agg['金额'].sum() - df['金额'].sum()) < 1  # float32 容差
+    dim = pd.DataFrame({'机构': ['华东', '华南', '华北'], '大区经理': ['张三', '李四', '王五']})
+    m = safe_merge(lean, dim, on='机构', validate='m:1', amount_col='金额')
+    assert '大区经理' in m.columns
+    b = df.copy()
+    b = b[b['单号'] != 5]                      # 制造 A有B无
+    b.loc[b['单号'] == 7, '金额'] += 100       # 制造金额不等
+    r = recon_diff(df, b, key='单号', amount='金额')
+    assert len(r['only_a']) == 1 and len(r['diff']) == 1
+    print('OK bigdata.py')

package/skills/data-streaming/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: data-streaming
+description: 实时计算链（真流式门槛判据→事件时间/处理时间与水位线心智→窗口类型判据→状态管理(checkpoint/TTL/大状态治理)→exactly-once 真实成本与端到端条件→反压定位处置→数据倾斜加盐→维表关联三判据→作业升级 savepoint 与状态演进→流批对账→经典事故清单）。eng-data-platform 的实时计算孙链(Flink 系心智):建实时指标/风控流、作业反压、状态膨胀、checkpoint 连环失败、实时与离线对不上时载入。
+version: 1.0.0
+---
+
+# 实时计算链
+
+eng-data-platform 的实时计算孙链(Flink 系引擎心智)。入场门槛承 eng-data-platform 批流判据:
+**业务动作依赖秒级结果才上真流式**(风控拦截/实时营销触达);"老板想早点看"用微批,别为仪表盘养 Flink 集群。
+
+## 时间与水位线（流计算第一心智）
+
+- **事件时间 vs 处理时间**:算业务(每 5 分钟订单额)一律事件时间(数据自带时间戳),处理时间只配监控类粗算——**乱序与迟到是常态**(网络/重试/离线补传),这是流计算一切复杂度的来源;
+- 水位线=系统对"迟到容忍"的显式声明:watermark=最大事件时间−容忍阈值,窗口等到水位线越过才闭算;
+- 阈值权衡:容忍大=延迟大但少丢,容忍小=快但迟到数据多——**迟到数据的去处必须显式设计**(侧输出收集→补记或对账,静默丢弃=实时与离线永远对不上);
+- **水位线停滞排查**:某分区无数据→整体水位不推进→窗口全不触发(下游"没数据"的经典根因)——空闲分区标记/多源对齐检查(infra-mq 分区衔接)。
+
+## 窗口类型判据
+
+滚动(固定周期指标,默认)/滑动(每分钟看最近一小时,注意重叠倍数=状态与计算放大)/会话(用户行为段,gap 定义要业务评审)/
+全局+触发器(自定义节奏);
+窗口结果的下游语义:窗口重算(迟到触发再次输出)时下游要能覆盖更新(**下游表按窗口键 upsert,不是 append**——append 会重复,eng-data-platform 幂等纪律的流版)。
+
+## 状态管理（流作业的"数据库"）
+
+- checkpoint=容错地基:周期快照,失败从最近 checkpoint 恢复(至少一次重放窗口内的重复要认,见语义节);间隔权衡(密=开销大,疏=恢复重放长);
+- **状态 TTL 必设**:按 key 的状态(去重集/累计值)无 TTL=无限膨胀(用户 ID 级状态天然无界)——TTL 依据业务窗口(去重 24h 就设 24h);
+- 大状态治理:状态后端选盘式(RocksDB 系)+增量 checkpoint;状态规模监控(**checkpoint 大小与耗时趋势是作业健康第一指标**);超大状态(TB 级)先质疑设计(能否预聚合/缩 key 空间/冷状态外置);
+- 恢复演练:从 checkpoint/savepoint 真恢复一次计时(eng-reliability 预案纪律,恢复不了的状态=没有状态)。
+
+## 一致性语义（宣传与现实）
+
+at-least-once+**下游幂等**=默认正道(简单皮实,arch-distributed 幂等四模式);
+引擎内 exactly-once 的成本:checkpoint 对齐(反压时对齐雪上加霜,非对齐 checkpoint 判据)——
+**端到端 exactly-once 三前提**:源可重放(Kafka 位移)+引擎 checkpoint+**汇支持事务/幂等**(两阶段提交 sink 或 upsert 汇)——三者缺一就是至少一次,别只看引擎宣传(infra-mq 同款提醒);
+判据:计费/风控级才追端到端精确,一般指标 at-least-once+幂等汇足够。
+
+## 反压定位与处置
+
+定位动线:背压监控找**第一个红的算子**(它的下游慢,不是它慢)→看该下游算子:外部 IO 慢(维表查询/sink 写入)?计算重?倾斜(见下)?
+处置序:异步 IO+批量(维表与 sink 优化,首选)→加并行度(**上限=分区数**,infra-mq)→攒批参数→拆算子链隔离瓶颈;
+**反压连锁**:反压→checkpoint 变慢超时→失败重启→重放加剧反压——死亡螺旋,**checkpoint 连环失败时先治反压不是调超时**;
+源头限流兜底(消费限速)保作业活着慢慢追(infra-mq 堆积治理呼应)。
+
+## 数据倾斜
+
+症状:个别并行度 100% 其余围观(反压面板一根红);
+定位:key 分布统计(热 key:超头部用户/默认值键——**空值/默认值聚集是隐形热 key**,先过滤或单独通道);
+治理:两阶段聚合(key 加盐打散局部聚合→去盐全局聚合,db-redis 热 key 同思想)/热键单独处理/预聚合上移。
+
+## 维表关联判据
+
+| 方式 | 适用 | 代价 |
+|---|---|---|
+| 广播 | 小表(配置/字典,百万级内)且低频变 | 全量进每并行度内存;变更全量重发 |
+| 异步查询+缓存 | 大维表(用户/商品) | 缓存命中率决定吞吐;**缓存 TTL=接受的陈旧窗口**(说清楚) |
+| temporal join | 维表变更也是流(CDC)且要"当时值" | 状态存历史版本,TTL 治理;语义最正,复杂度最高 |
+
+**维表关联的一致性要声明**:关联到的是"此刻值"还是"事件发生时值"——报表口径纠纷高发点(data-governance 口径裁决)。
+
+## 作业升级与状态演进
+
+**savepoint 流程**:停前打 savepoint→新版本从 savepoint 启动——状态兼容是前提:算子加 uid(不加=拓扑变了状态对不上)/状态 schema 演进规则(加字段可以,改类型=迁移);
+不兼容变更(改分组键/改窗口)=状态作废,**从历史重算的通道要有**(Kafka 保留期覆盖重算窗口,infra-mq 保留策略联动);
+升级也是发布(eng-release):灰度双跑判据(新旧作业并行写不同表,对账后切,大改动必须)。
+
+## 流批对账（实时的信用工程）
+
+**Lambda 认账**(eng-data-platform):实时表与离线表同口径字段 T+1 对账例程(eng-automation),差异率阈值告警;
+差异三来源心智:迟到数据(水位线丢弃侧输出核对)/口径漂移(实时 SQL 与离线 SQL 双头维护→尽量同引擎批流一体或代码生成同源)/汇端重复(幂等缺陷);
+**实时指标口径差异对业务声明**("实时数为参考,结算以 T+1 为准"写进看板,metrics-system 口径纪律)。
+
+## 经典事故清单（根因→防线）
+
+状态无 TTL 膨胀 OOM(TTL 必设+规模监控);checkpoint 连环超时死亡螺旋(先治反压);
+水位线停滞下游断流(空闲分区);热 key 单点打满(加盐);
+维表缓存陈旧引发口径投诉(TTL 声明);升级丢状态(uid+savepoint 流程);
+迟到数据静默丢(侧输出+对账);重启风暴打挂下游(sink 限流+退避)。
+
+**作业包**:`references/job-checklist.md`(作业上线四件套(迟到去向必答)/反压处置卡/savepoint 升级流程/流批对账登记)。
+
+## 使用纪律
+
+新作业上线四件套:水位线与迟到策略/状态 TTL/checkpoint 监控/流批对账例程;
+作业升级必走 savepoint 流程;窗口口径与离线对齐评审(data-governance);
+每次流事故回写清单——**实时链路的信用=对账差异率,不是"看起来在动"**。

package/skills/data-streaming/references/job-checklist.md

@@ -0,0 +1,36 @@
+# 流作业上线与升级检查单（data-streaming 落笔件）
+
+## 1. 上线四件套
+
+| 项 | 内容 |
+|---|---|
+| 作业/口径依据 | __(与离线口径对齐评审过,data-governance) |
+| 时间语义 | □事件时间(默认)+水位线容忍 __ 分钟 □处理时间(仅监控类) |
+| **迟到数据去向** | □侧输出→补记/对账 □容忍丢弃(业务签认:__)——静默丢=永远对不上 |
+| 窗口 | □滚动 __ □滑动 __/__ □会话 gap __;下游 upsert 按窗口键(重算会重复输出,append 必错) |
+| 状态 TTL | 每 key 状态 TTL=__(依据业务窗口;**无 TTL=无限膨胀**) |
+| checkpoint | 间隔 __;大小与耗时基线 __(健康第一指标,进监控) |
+| 一致性 | □at-least-once+汇端幂等(默认) □端到端 exactly-once(三前提核过:源可重放/checkpoint/汇支持事务) |
+| lag 告警 | 阈值 __(infra-mq 联动);反压面板已挂 |
+
+## 2. 反压处置卡(checkpoint 连环失败时先治反压不是调超时)
+
+1. 定位第一个红算子(它的**下游**慢)
+2. 下游优化:维表异步 IO+缓存(TTL=陈旧窗口 __ 已声明)/sink 攒批
+3. 并行度调整(≤分区数 __);倾斜检查:热 key __(空值/默认值聚集?)→加盐两阶段
+4. 源头限流保命,慢慢追
+
+## 3. 作业升级流程(升级=发布,eng-release)
+
+- [ ] 算子已加 uid(不加=拓扑变了状态对不上)
+- [ ] 停前 savepoint:__;状态 schema 兼容确认(加字段可,改类型=迁移)
+- [ ] 不兼容变更→从历史重算通道核过(Kafka 保留期 __ 覆盖重算窗口?)
+- [ ] 大改动:新旧双跑写不同表→对账 __ 天→切换
+- [ ] 恢复演练:从 savepoint 真恢复计时 __ 分钟
+
+## 4. 流批对账登记(实时链路的信用)
+
+| 指标/表 | 对账口径(与离线 T+1) | 差异率阈值 | 当前差异 | 差异归因(迟到/口径漂移/汇端重复) |
+|---|---|---|---|---|
+
+> 看板声明:"实时数为参考,结算以 T+1 为准";维表关联的"当时值 vs 此刻值"已声明:__

package/skills/data-wrangling/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: data-wrangling
+description: 数据清洗与多表关联匹配（清洗规范化、去重、模糊匹配、VLOOKUP 式关联、多表合并、宽长转换）。当用户说"清洗数据/两张表拼一起/对不上/VLOOKUP/模糊匹配/去重/表格规范化"时使用。Excel 分析链之整理环。
+version: 1.0.0
+---
+
+# 数据清洗与关联匹配（Excel 分析链 · 整理环；全景见 excel-analysis-chain）
+
+"数据分析 80% 时间在清洗"是行业共识——本技能把这 80% 做成可复算流程,取代手工
+VLOOKUP + 反复筛选替换。
+
+## 清洗规范化（`read_skill_file` 读 `scripts/join_tools.py`）
+
+- `clean_columns()`：列名规范（去空格/统一命名）、类型修复（日期 to_datetime、
+  千分位金额转数值、文本前导零保护）、缺失标记（**区分"真缺失"与"0"与"未填"**——
+  用 0 填缺失是经典错误）;
+- 值域规范：全半角/大小写/别名映射（"北京市/北京/BJ"→标准值,映射表参数化）、
+  单位统一、异常值标记（不删除,标记交人工——**清洗不是偷偷改数**）;
+- 去重：`dedup()` 按业务主键去重,保留规则显式（最新/最全/首条），**报告去掉了多少行**。
+
+## 多表关联（Excel VLOOKUP/INDEX-MATCH 的正确替代）
+
+- `safe_join()`：带体检的关联（data-report-pro 同源:validate 关系+双侧未匹配清单+
+  金额守恒）——**关联前先清洗对表键**（strip/大小写/全半角/前导零,"看着一样连不上"
+  九成栽这里）;
+- **模糊匹配**：`fuzzy_match()` 名称匹配（编辑距离/token 相似度,阈值参数化）——
+  公司名/地址/商品名对表的利器,输出匹配对+相似度+**待人工确认区间**
+  （高分自动、中分人工、低分放弃,别全自动一刀切）;
+- 多表合并：多个来源纵向拼接（列对齐校验,来源标记列）/横向多键关联;
+  一对多关系明示（避免笛卡尔积炸行）。
+
+## 结构转换
+
+宽转长（melt:多列指标→一列,画图与透视友好）/长转宽（pivot）;
+拆分与合并列（地址拆省市区/多值单元格炸开）;分组填充（ffill 仅对确认的合并单元格列）。
+
+## 数据质量报告（清洗的交付物）
+
+清洗前后对比：行数变化/各列空值率/去重量/异常标记数/关联匹配率——
+**清洗要留痕**（每步做了什么、影响多少行），下游才敢信这份数据;
+可复用为清洗管道（同源数据每次自动清洗,office-automation 例程）。
+
+## 验收自查
+
+- [ ] 缺失/0/未填三者已区分;异常标记不删除
+- [ ] 关联前清洗了键;匹配率与未匹配清单已报
+- [ ] 模糊匹配分档（自动/人工/放弃）
+- [ ] 清洗全程留痕（前后对比报告）
+
+## 附件
+
+- `scripts/join_tools.py` — clean_columns/dedup/safe_join(体检)/fuzzy_match(分档)/宽长转换;可直接执行自测

package/skills/data-wrangling/scripts/join_tools.py

@@ -0,0 +1,99 @@
+# 清洗与关联件（经 run_python 执行）：列名/类型清洗 / 去重 / 带体检关联 / 模糊匹配（纯 difflib，无外部依赖）。
+# 直接执行本文件 = 自测。
+import difflib
+import re
+import numpy as np
+import pandas as pd
+
+_PUNCT = str.maketrans({'（': '(', '）': ')', '，': ',', '　': ' '})
+
+
+def normalize_key(s):
+    """关联键归一：去空白、全半角、大小写、括号地区注、常见公司后缀——用于连接前对齐。"""
+    t = str(s).translate(_PUNCT).strip().lower()
+    t = re.sub(r'\s+', '', t)
+    t = re.sub(r'\([^)]*\)', '', t)  # 去括号内容（地区注："阿里巴巴(中国)"→"阿里巴巴"）
+    t = re.sub(r'(股份有限公司|有限责任公司|有限公司|集团|公司|co\.?,?ltd\.?|inc\.?)$', '', t)
+    return t
+
+
+def clean_columns(df, numeric=None, dates=None, keep_leading_zero=None):
+    """列名 strip；numeric 列去千分位转数值；dates 转日期；keep_leading_zero 保文本。返回清洗后 df + 报告。"""
+    d = df.copy()
+    d.columns = [str(c).strip() for c in d.columns]
+    report = {}
+    for c in (numeric or []):
+        raw = d[c]
+        d[c] = pd.to_numeric(d[c].astype(str).str.replace(',', '').str.strip(), errors='coerce')
+        report[c] = f'转数值，新增缺失 {int(d[c].isna().sum() - raw.isna().sum())}'
+    for c in (dates or []):
+        d[c] = pd.to_datetime(d[c], errors='coerce')
+        report[c] = f'转日期，无法解析 {int(d[c].isna().sum())}'
+    for c in (keep_leading_zero or []):
+        d[c] = d[c].astype(str)
+    nulls = {c: f'{d[c].isna().mean():.1%}' for c in d.columns if d[c].isna().any()}
+    print(f'[清洗] {len(d)} 行 · 类型处理 {report} · 空值率 {nulls}')
+    return d, {'rows': len(d), 'ops': report, 'null_rate': nulls}
+
+
+def dedup(df, keys, keep='last', sort_by=None):
+    """按业务主键去重，保留规则显式（last/first）。报告去掉多少行。"""
+    d = df.sort_values(sort_by) if sort_by else df
+    before = len(d)
+    out = d.drop_duplicates(subset=keys, keep=keep)
+    print(f'[去重] 按 {keys} keep={keep}：{before} → {len(out)}（去掉 {before - len(out)} 行）')
+    return out.reset_index(drop=True)
+
+
+def safe_join(left, right, on=None, left_on=None, right_on=None, how='left', validate='m:1', amount_col=None):
+    """带体检关联：打印匹配统计与未匹配样例；amount_col 给出则做守恒检查。"""
+    m = left.merge(right, on=on, left_on=left_on, right_on=right_on, how=how,
+                   validate=validate, indicator=True)
+    stat = m['_merge'].value_counts().to_dict()
+    print(f'[关联] how={how} validate={validate} → {stat}')
+    miss = m[m['_merge'] == 'left_only']
+    if len(miss):
+        key = left_on or on
+        print(f'  未匹配 {len(miss)} 行，样例键：{miss[key].head(3).tolist() if key else "—"}')
+    if amount_col and amount_col in left.columns:
+        gap = float(left[amount_col].sum() - m[m['_merge'] != 'right_only'][amount_col].sum())
+        assert abs(gap) < 1e-6, f'关联后 {amount_col} 不守恒（差 {gap}）：查重复键'
+    return m.drop(columns='_merge')
+
+
+def fuzzy_match(left_names, right_names, hi=0.90, lo=0.70):
+    """模糊匹配（difflib 相似度）：分自动(≥hi)/人工(lo–hi)/放弃(<lo)三档。返回匹配表。"""
+    right_norm = {normalize_key(r): r for r in right_names}
+    keys = list(right_norm)
+    rows = []
+    for l in left_names:
+        lk = normalize_key(l)
+        best = difflib.get_close_matches(lk, keys, n=1, cutoff=lo)
+        if best:
+            score = difflib.SequenceMatcher(None, lk, best[0]).ratio()
+            band = '自动' if score >= hi else '人工确认'
+            rows.append({'左': l, '匹配右': right_norm[best[0]], '相似度': round(score, 3), '处置': band})
+        else:
+            rows.append({'左': l, '匹配右': None, '相似度': 0.0, '处置': '放弃'})
+    out = pd.DataFrame(rows, columns=['左', '匹配右', '相似度', '处置'])  # 空输入也保有列，避免 KeyError '处置'
+    print(f'[模糊匹配] 自动 {(out["处置"] == "自动").sum()} · 人工 {(out["处置"] == "人工确认").sum()} · 放弃 {(out["处置"] == "放弃").sum()}')
+    print(out.to_markdown(index=False))
+    return out
+
+
+if __name__ == '__main__':
+    raw = pd.DataFrame({'客户 ': ['A', 'A', 'B'], '金额': ['1,200', '1,200', '800'],
+                        '编号': ['007', '007', '013'], '日期': ['2026/1/1', '2026/1/1', '2026-02-03']})
+    clean, rep = clean_columns(raw, numeric=['金额'], dates=['日期'], keep_leading_zero=['编号'])
+    assert clean['金额'].iloc[0] == 1200.0 and clean['编号'].iloc[0] == '007'
+    dd = dedup(clean, keys=['客户', '编号'])
+    assert len(dd) == 2
+    dim = pd.DataFrame({'客户': ['A', 'B'], '大区': ['东', '南']})
+    j = safe_join(dd, dim, on='客户', validate='m:1', amount_col='金额')
+    assert '大区' in j.columns
+    fm = fuzzy_match(['阿里巴巴有限公司', '腾讯科技', '未知企业X'],
+                     ['阿里巴巴（中国）有限公司', '腾讯科技股份有限公司'])
+    assert (fm['处置'] == '放弃').sum() == 1  # 未知企业X 无匹配
+    assert fm[fm['左'] == '腾讯科技']['匹配右'].iloc[0] is not None  # 去后缀后应匹配上
+    assert list(fuzzy_match([], ['x']).columns) == ['左', '匹配右', '相似度', '处置']  # 空输入不崩、保有列
+    print('OK join_tools.py')

package/skills/db-es/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: db-es
+description: 搜索引擎链 Elasticsearch（非事实源定位与重建方案→显式 mapping 与动态映射陷阱→text/keyword 双字段与 ik 中文分词→分片规划(单分片 10-50G/不可改)→时间滚动索引 ILM 与别名零停机→filter 缓存与深分页 search_after→聚合内存风险→CDC 同步与对账→集群(堆≤32G/熔断/脑裂)→经典事故清单）。eng-database 的搜索孙链:建搜索/日志检索、中文分词调优、深分页打挂、聚合 OOM、mapping 改不动时载入。
+version: 1.0.0
+---
+
+# 搜索引擎链（Elasticsearch 系）
+
+eng-database 的搜索孙链(ES/OpenSearch 通用心智)。定位铁律承 eng-database:
+**搜索引擎不是事实源**——数据可从源库重建,重建方案(全量导入管道+耗时预估)与索引同日交付,没有重建方案的 ES=悬空资产。
+
+## mapping 设计（建错=重建,先想后建）
+
+- **显式 mapping 纪律**:动态映射的三连坑——首条数据定字段类型(第一条 "123" 进来=long,后面 "abc" 全拒)/字段无界增长(把用户输入当字段名=mapping 爆炸,集群元数据拖垮)/日期猜测误判——生产索引 `dynamic: strict` 或 false;
+- text vs keyword 双字段:text 分词(全文检索)/keyword 原样(精确匹配/排序/聚合)——**默认双字段,聚合排序必须用 .keyword**(对 text 聚合=fielddata 内存炸弹,禁开);
+- 中文分词 ik:ik_max_word(索引用,细粒度)+ik_smart(搜索用,粗粒度)搭配;**自定义词典热更机制建好**(业务词/品牌名不进词典=切碎搜不到,词典更新是运营常态);同义词过滤器判据(搜索期同义优于索引期,改词免重建);
+- 字段瘦身:不检索的字段 `index: false`,不聚合排序的关 doc_values,大字段(正文)判据 store 或源库回查——**mapping 上的每个默认开关都是存储与内存**。
+
+## 分片规划（建时定终身）
+
+- **主分片数创建后不可改**(只能 reindex 重建)——按目标容量规划:单分片 10–50GB 经验带,过大恢复慢/过小元数据开销;
+- 分片总数控制:每 GB 堆支撑 20 分片量级参考,小索引合并(月度小索引合成年度)——**千级小分片拖垮 master 是日志集群头号病**;
+- 副本:1 副本默认(可用+读扩展);写高峰可临时 0 副本导入再补;
+- 路由判据:按租户 routing 收敛查询到单分片(arch-multitenant 场景),热点租户要评估。
+
+## 时间滚动与 ILM（日志/时序场景标配）
+
+按时间滚动索引(daily/按大小 rollover)+ILM 生命周期:热(SSD 写查)→温(只查)→冷(冻结/低配)→删——存储成本一个量级差(eng-infra 生命周期同则);
+**别名三用**:写别名指当前索引/读别名跨多索引/重建切换——**一切访问走别名,零停机 reindex 全靠它**(直连索引名=重建即改代码);
+重建流程:新索引(新 mapping)→reindex 拷贝(限速)→双写或追增量→别名原子切换→观察→删旧。
+
+## 查询与聚合
+
+- bool 四子句心智:must/should 算分,**filter/must_not 不算分且可缓存**——精确过滤(状态/租户/时间)一律放 filter(性能差距数倍);
+- **深分页红线**:from+size 页深过万=协调节点聚合爆(每分片都取 from+size 条)——翻页用 search_after(游标),导出用 PIT/scroll;产品设计上限制页深(没人真翻第 500 页,eng-ux);
+- 聚合内存风险:高基数字段 terms 聚合(百万级唯一值)=堆压力,cardinality 用近似(precision 权衡)/composite 聚合分页拉全量;
+- 慢查询治理:slowlog 阈值开+profile API 定位;通配符前缀查询(`*x`)与正则=全字典扫描,评审拦(qa 用例同拦);
+- 相关性调优单列:字段权重 boost/function_score 业务因子(销量/时间衰减)——**调相关性要有评测集**(标注查询-期望结果对,ai-eval 方法论同构)。
+
+## 写入与同步管道
+
+批量 bulk(千条/兆级一批起调)+背压重试(429 退避);refresh_interval 默认 1s=近实时,导入期调大(30s/-1)换吞吐;
+**CDC 同步是主流形态**(binlog→MQ→ES,db-mysql/infra-mq 衔接):最终一致要认(秒级窗口),乱序防护(版本号/时间戳外部版本);
+**对账例程必配**(eng-automation):源库与 ES 条数勾稽(按天分区比对)+抽样字段比对——同步链路静默断=搜索缺数,用户以为"没有"其实"没同步";
+删除同步别漏(软删要同步删/过滤,源删 ES 不删=僵尸结果)。
+
+## 集群运维
+
+- 节点角色分离(规模化后):master 专职(稳定第一)/data 分层(热温冷)/coordinating 挡聚合;
+- **JVM 堆 ≤32GB**(压缩指针红线,常配 31G),堆=机器内存一半(另一半给 lucene 文件缓存——**文件缓存才是查询性能的真主力**);
+- 熔断器与队列:parent circuit breaker 触发=先查聚合与大结果集;写拒绝看线程池队列;
+- 脑裂防护:master 候选奇数台+quorum(7.x+ 自动),跨机房部署要明确多数派放哪;
+- 恢复与均衡限速(大分片恢复打满带宽影响服务)。
+
+## 经典事故清单（根因→防线）
+
+mapping 爆炸(dynamic strict);text 聚合 fielddata OOM(用 .keyword);深分页打挂协调节点(search_after+页深上限);
+高基数聚合熔断(近似/composite);同步链路静默断(对账例程+lag 告警);
+小分片千级拖垮 master(rollover 策略+定期合并);磁盘水位触发只读锁(85/90/95 三水位监控,锁了要手动解);
+误删索引(别名操作规范+快照策略,eng-ops 3-2-1 的 ES 落地=snapshot 仓库)。
+
+**作业包**:`scripts/es-health.sh`(集群状态/磁盘三水位/未分配分片原因/小索引计数/线程池拒绝,只读初判)。
+
+## 使用纪律
+
+新索引上线四件套:显式 mapping 评审/分片规划依据/重建方案/对账例程;
+一切访问走别名;分词词典有 Owner 有更新流程;相关性调整走评测对照;
+每次 ES 事故回写清单——**ES 的坑一半在"建的时候没想",另一半在"同步断了没人知"**。