@huicai/cli 2026.714.0 → 2026.721.0

package/skills/ops-linux/scripts/quick-triage.sh

@@ -0,0 +1,138 @@
+#!/bin/sh
+# Linux 一键体检脚本（ops-linux 四棵决策树的采集与初判,只读零依赖,工具缺失自动降级）。
+# 用法: sh quick-triage.sh [-o 目录]     # -o 时全量原始输出落盘该目录并打 tar.gz(事件现场保全)
+# 输出: 屏幕=红黄灯初判+关键数据;落盘=完整命令输出(eng-ops 证据保全先于操作)。
+# 安全: 全部只读命令(eng-automation 只读诊断级);不含 strace/tcpdump 等有代价工具(按需人工上,见链内红线)。
+
+OUT=""
+[ "$1" = "-o" ] && OUT="$2"
+TS=$(date '+%Y%m%d_%H%M%S')
+if [ -n "$OUT" ]; then D="$OUT/triage_$TS"; mkdir -p "$D" || { echo "无法创建 $D"; exit 2; }; fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+grab() { # grab <文件名> <命令...> : 落盘完整输出,返回输出内容供解析
+  f="$1"; shift
+  o=$("$@" 2>&1)
+  [ -n "$OUT" ] && echo "$o" > "$D/$f"
+  echo "$o"
+}
+FLAG_R=""; FLAG_Y=""
+red() { FLAG_R="$FLAG_R
+  [红] $1"; }
+yel() { FLAG_Y="$FLAG_Y
+  [黄] $1"; }
+
+echo "==================== 一键体检 $TS ===================="
+echo "主机: $(hostname 2>/dev/null) | 内核: $(uname -r 2>/dev/null)"
+
+# ---- 全局: load 与核数 ----
+# 实战回写 2026-07:macOS 是 "load averages: a b c"(无逗号)、无 nproc——解析与核数双兜底
+CORES=$( (nproc 2>/dev/null) || (sysctl -n hw.ncpu 2>/dev/null) || grep -c ^processor /proc/cpuinfo 2>/dev/null || echo 1)
+UP=$(grab uptime.txt uptime)
+echo "$UP"
+L1=$(echo "$UP" | sed 's/.*load average[s]*: *//' | awk '{print $1}' | tr -d ',')
+L1I=${L1%%.*}
+[ -n "$L1I" ] && [ "$L1I" -ge "$CORES" ] 2>/dev/null && yel "load($L1)≥核数($CORES) —— 若 CPU 使用率不高,查 D 状态进程(决策树:CPU)"
+
+# ---- CPU ----
+echo ""
+echo "---- CPU ----"
+if have vmstat; then
+  VM=$(grab vmstat.txt vmstat 1 3)
+  echo "$VM" | tail -4
+  CS=$(echo "$VM" | tail -1 | awk '{print $12}')
+  WA=$(echo "$VM" | tail -1 | awk '{print $16}')
+  SY=$(echo "$VM" | tail -1 | awk '{print $14}')
+  case "$CS" in [0-9]*) [ "$CS" -gt 100000 ] && yel "上下文切换 cs=$CS —— 线程过多或锁颠簸(strace -c/各语言链画像)";; esac
+  case "$WA" in [0-9]*) [ "$WA" -gt 20 ] && red "IO 等待 wa=$WA% —— 转 IO 决策树,加 CPU 无用";; esac
+  case "$SY" in [0-9]*) [ "$SY" -gt 30 ] && yel "内核态 sy=$SY% —— 系统调用风暴嫌疑";; esac
+else echo "(无 vmstat,跳过)"; fi
+echo "TOP CPU 进程:"
+grab ps_cpu.txt ps aux | sort -rk3 | head -6 | awk '{printf "  %-10s %5s%%CPU %5s%%MEM %s\n",$1,$3,$4,$11}'
+DCNT=$(ps -eo stat 2>/dev/null | grep -c '^D')
+[ "$DCNT" -gt 0 ] 2>/dev/null && { red "D 状态(不可中断)进程 $DCNT 个 —— 等 IO/NFS/内核锁,load 假高元凶"; ps -eo pid,stat,wchan:20,comm 2>/dev/null | awk '$2~/^D/' | head -5 | sed 's/^/    /'; }
+
+# ---- 内存 ----
+echo ""
+echo "---- 内存 ----"
+if [ -r /proc/meminfo ]; then
+  grab meminfo.txt cat /proc/meminfo >/dev/null
+  AV=$(awk '/MemAvailable/{print int($2/1024)}' /proc/meminfo)
+  TO=$(awk '/MemTotal/{print int($2/1024)}' /proc/meminfo)
+  echo "总 ${TO}M / 可用 ${AV}M (看 available)"
+  [ -n "$AV" ] && [ -n "$TO" ] && [ "$TO" -gt 0 ] && [ $(( AV * 100 / TO )) -lt 10 ] && red "可用内存 <10% —— 查 TOP RSS 与泄漏(语言链堆分析)"
+fi
+echo "TOP 内存进程:"
+ps aux 2>/dev/null | sort -rk4 | head -4 | awk '{printf "  %-10s %5s%%MEM rss=%sK %s\n",$1,$4,$6,$11}'
+OOM=$(dmesg -T 2>/dev/null | grep -iE 'out of memory|oom-kill' | tail -3)
+if [ -n "$OOM" ]; then red "dmesg 有 OOM 记录(被杀的未必是元凶):"; echo "$OOM" | sed 's/^/    /'; [ -n "$OUT" ] && dmesg -T 2>/dev/null | tail -200 > "$D/dmesg_tail.txt"; fi
+# cgroup(容器)校正
+if [ -f /.dockerenv ] || grep -qsE 'kubepods|docker' /proc/1/cgroup 2>/dev/null; then
+  for f in /sys/fs/cgroup/memory.current /sys/fs/cgroup/memory.max; do [ -r "$f" ] && echo "  cgroup $(basename "$f"): $(cat "$f")"; done
+  echo "  (容器内 free/top 显示宿主内存,以 cgroup 为准 —— 决策树:内存假象)"
+fi
+
+# ---- 磁盘与 IO ----
+echo ""
+echo "---- 磁盘/IO ----"
+grab df.txt df -h >/dev/null
+# 只读/镜像卷恒 100% 是常态噪声(Linux 的 /dev/loop|squashfs=snap 卷;macOS 的封存系统卷)——
+# 实战回写 2026-07:排除后再判红,别把 snap 卷当磁盘满(ops-linux 磁盘满四查注记)
+DF_NOISE='/dev/loop|squashfs|iso9660|cdrom|/System/Volumes|devfs|map '
+df -h 2>/dev/null | grep -vE "$DF_NOISE" | awk 'NR>1 && $5+0>85 {print "  "$0"  <== >85%"}' | while read -r l; do echo "$l"; done
+DFULL=$(df -h 2>/dev/null | grep -vE "$DF_NOISE" | awk '$5+0>92 && $1 ~ /^\//' | head -1)
+[ -n "$DFULL" ] && red "磁盘 >92%: $(echo "$DFULL" | awk '{print $6" "$5}') —— 磁盘满四查(du/df 差=已删未释放 lsof +L1;inode;日志;挂载遮蔽)"
+INO=$(df -i / 2>/dev/null | awk 'NR==2{print $5+0}')
+[ -n "$INO" ] && [ "$INO" -gt 85 ] 2>/dev/null && red "根分区 inode ${INO}% —— 海量小文件"
+if have lsof; then
+  DEL=$(lsof +L1 2>/dev/null | awk 'NR>1{s+=$7} END{print int(s/1048576)}')
+  [ -n "$DEL" ] && [ "$DEL" -gt 500 ] 2>/dev/null && yel "已删除未释放文件占 ${DEL}M —— 找持有进程重启/truncate"
+fi
+if have iostat; then
+  IO=$(grab iostat.txt iostat -x 1 2)
+  echo "$IO" | awk '/Device|^[a-z]/ && !/loop/' | tail -6 | sed 's/^/  /'
+  echo "$IO" | tail -6 | awk '$1!~/loop|Device/ && $NF+0>90 {print "  <== "$1" util>90%"}'
+else echo "  (无 iostat,IO 细节跳过)"; fi
+
+# ---- 网络 ----
+echo ""
+echo "---- 网络 ----"
+if have ss; then
+  grab ss_summary.txt ss -s >/dev/null
+  EST=$(ss -tan state established 2>/dev/null | wc -l)
+  TW=$(ss -tan state time-wait 2>/dev/null | wc -l)
+  CW=$(ss -tan state close-wait 2>/dev/null | wc -l)
+  echo "连接: ESTAB≈$((EST-1)) TIME_WAIT≈$((TW-1)) CLOSE_WAIT≈$((CW-1))"
+  [ "$CW" -gt 500 ] 2>/dev/null && red "CLOSE_WAIT $((CW-1)) —— 代码没关连接(查连接池/HTTP body 未关,dev-* 链)"
+  [ "$TW" -gt 20000 ] 2>/dev/null && yel "TIME_WAIT $((TW-1)) —— 主动关闭方常态,过高考虑连接复用/长连接化"
+  [ -n "$OUT" ] && ss -tlnp > "$D/listen.txt" 2>&1
+elif have netstat; then netstat -an 2>/dev/null | awk '/tcp/{s[$NF]++} END{for(k in s) printf "  %s=%d",k,s[k]; print ""}'
+else echo "  (无 ss/netstat)"; fi
+RETR=$(netstat -s 2>/dev/null | grep -iE 'retransmit' | head -2)
+[ -n "$RETR" ] && echo "$RETR" | sed 's/^/  重传: /'
+if [ -r /proc/sys/net/netfilter/nf_conntrack_count ] && [ -r /proc/sys/net/netfilter/nf_conntrack_max ]; then
+  CC=$(cat /proc/sys/net/netfilter/nf_conntrack_count); CM=$(cat /proc/sys/net/netfilter/nf_conntrack_max)
+  [ "$CM" -gt 0 ] && [ $(( CC * 100 / CM )) -gt 80 ] && red "conntrack ${CC}/${CM} >80% —— 表满会静默丢连接"
+fi
+
+# ---- 句柄与时钟 ----
+echo ""
+echo "---- 句柄/时钟 ----"
+[ -r /proc/sys/fs/file-nr ] && { FN=$(cat /proc/sys/fs/file-nr); echo "系统句柄(file-nr): $FN"; }
+echo "本进程 ulimit -n: $(ulimit -n 2>/dev/null)"
+if have chronyc; then OFF=$(chronyc tracking 2>/dev/null | awk -F': *' '/System time/{print $2}'); echo "时钟偏移: ${OFF:-未知}"
+elif have timedatectl; then echo "对时: $(timedatectl 2>/dev/null | grep -i synchronized | tr -d ' ')"
+else yel "无法确认对时状态 —— 证书/分布式凭证问题先想到时钟"; fi
+
+# ---- 汇总 ----
+echo ""
+echo "==================== 初判汇总 ===================="
+[ -n "$FLAG_R" ] && { echo "红灯:$FLAG_R"; }
+[ -n "$FLAG_Y" ] && { echo "黄灯:$FLAG_Y"; }
+[ -z "$FLAG_R$FLAG_Y" ] && echo "未见系统层明显异常 —— 问题可能在应用层(语言链画像)或依赖侧(RED 先于 USE)"
+echo "下一步: 对照红黄灯进 ops-linux 对应决策树;应用层转 dev-* 语言链画像。"
+if [ -n "$OUT" ]; then
+  ( cd "$OUT" && tar czf "triage_$TS.tar.gz" "triage_$TS" 2>/dev/null )
+  echo "现场包: $OUT/triage_$TS.tar.gz (eng-ops 证据保全,先归档再操作)"
+fi
+exit 0

package/skills/optimization-solver/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: optimization-solver
+description: 运筹优化与决策求解（线性规划、指派/运输、目标规划、What-if 情景与规划求解、约束优化）。当用户说"最优方案/怎么分配/排产优化/成本最低/利润最大/规划求解/资源怎么配"时使用。Excel 分析链之决策环。
+version: 1.0.0
+---
+
+# 运筹优化与决策求解（Excel 分析链 · 决策环；全景见 excel-analysis-chain）
+
+对标 Excel"规划求解(Solver)"但无变量数限制,可复算、可版本化。**建模比求解难**——
+本技能重点在把业务问题翻译成"目标+决策变量+约束"三件套。
+
+## 建模三件套（求解前必须写清）
+
+1. **决策变量**：我们能控制什么（生产多少/怎么分配/选不选）——连续还是整数（0-1 选址、
+   整数排产）;
+2. **目标函数**：最大化什么/最小化什么（利润/成本/工期）——**单目标先行**,多目标转目标规划;
+3. **约束**：资源上限（产能/预算/工时）、需求下限、平衡关系、逻辑约束——
+   **约束漏一条,最优解就是错的**（"最优但不可行"是建模事故）。
+
+## 求解（`read_skill_file` 读 `scripts/solver.py`，需 scipy：packages=['scipy']）
+
+- `linprog_solve()`：线性规划（生产组合/配料/投资分配）——目标系数+约束矩阵,
+  输出最优解+目标值+**影子价格**（约束松紧:哪个资源是瓶颈,多一单位值多少钱——
+  这是运筹给管理层最有价值的洞察）;
+- `assignment()`：指派问题（人-任务/机-单最优匹配,匈牙利算法）;
+- `transport()`：运输问题（多产地多销地最小运费,supply-chain 衔接）;
+- **整数约束**（0-1 选址/整数产量）用分支定界（scipy milp 或提示装 pulp）——
+  连续解取整≠整数最优,别偷懒。
+
+## What-if 与敏感性（决策的稳健性）
+
+- 情景对比：关键参数（需求/价格/产能）几档下的最优解如何变——**最优解对哪个假设敏感**;
+- 影子价格解读：瓶颈资源加产能的边际收益 → 扩产决策依据;
+- 参数区间：目标系数在多大范围内最优解不变（解的稳定性）;
+- **诚实边界**：模型是现实的简化,给出"未建模因素"清单（质量/关系/风险偏好），
+  最优解是决策输入不是决策本身。
+
+## 典型问题映射
+
+生产计划（利润最大化 s.t. 产能物料）→ 与 production-planning 产能负荷衔接;
+投资组合（收益最大 s.t. 预算风险）;排班（覆盖需求 min 人力）;配料/下料（成本最小 s.t. 规格）;
+选址（总成本最小,0-1 变量）。
+
+## 验收自查
+
+- [ ] 三件套写清,约束无遗漏（解可行）
+- [ ] 整数问题用整数求解,未连续取整
+- [ ] 给了影子价格/瓶颈解读
+- [ ] 做了关键参数敏感性;标注未建模因素
+
+## 附件
+
+- `scripts/solver.py` — linprog_solve(影子价格)/assignment/transport（scipy）;缺 scipy 时给安装提示。可执行自测（有 scipy 才跑求解）

package/skills/optimization-solver/scripts/solver.py

@@ -0,0 +1,107 @@
+# 运筹求解件（经 run_python 执行，需 scipy：run_python 传 packages=['scipy']）：
+# 线性规划（含影子价格）/ 指派 / 运输。缺 scipy 时给清晰安装提示，不崩。
+# 直接执行本文件 = 自测（有 scipy 才执行求解断言）。
+import numpy as np
+
+try:
+    from scipy.optimize import linprog, linear_sum_assignment
+    HAS_SCIPY = True
+except ImportError:
+    HAS_SCIPY = False
+
+
+def _need_scipy():
+    if not HAS_SCIPY:
+        raise ImportError('运筹求解需要 scipy：run_python 调用时传 packages=["scipy"]')
+
+
+def linprog_solve(c, A_ub=None, b_ub=None, A_eq=None, b_eq=None, bounds=None, maximize=True, names=None):
+    """线性规划。默认最大化（内部转最小化）。返回最优解/目标值/影子价格（约束对偶值）。"""
+    _need_scipy()
+    cc = [-x for x in c] if maximize else list(c)
+    res = linprog(cc, A_ub=A_ub, b_ub=b_ub, A_eq=A_eq, b_eq=b_eq, bounds=bounds, method='highs')
+    if not res.success:
+        print(f'[LP] 无可行解/求解失败：{res.message}——检查约束是否矛盾')
+        return {'success': False, 'message': res.message}
+    obj = -res.fun if maximize else res.fun
+    names = names or [f'x{i+1}' for i in range(len(c))]
+    sol = dict(zip(names, np.round(res.x, 4)))
+    # 影子价格 = 上界约束的对偶值（marginals，highs 提供）
+    shadow = None
+    try:
+        shadow = np.round(res.ineqlin.marginals, 4).tolist() if A_ub is not None else None
+    except Exception:
+        pass
+    print(f'[LP] {"最大" if maximize else "最小"}化目标值 = {obj:.4f}')
+    print(f'  最优解：{sol}')
+    if shadow:
+        binding = [i for i, m in enumerate(shadow) if abs(m) > 1e-9]
+        print(f'  影子价格（≠0=瓶颈约束）：{shadow}；瓶颈约束索引 {binding}')
+    return {'success': True, 'objective': round(obj, 4), 'solution': sol, 'shadow_prices': shadow}
+
+
+def assignment(cost_matrix, maximize=False):
+    """指派问题（匈牙利算法）：行=人/机，列=任务。返回匹配对与总成本。"""
+    _need_scipy()
+    cost = np.asarray(cost_matrix, float)
+    r, c = linear_sum_assignment(cost, maximize=maximize)
+    total = cost[r, c].sum()
+    pairs = list(zip(r.tolist(), c.tolist()))
+    print(f'[指派] {"最大" if maximize else "最小"}化总额 = {total:.2f} · 匹配 行→列 {pairs}')
+    return {'pairs': pairs, 'total': round(float(total), 2)}
+
+
+def transport(supply, demand, cost):
+    """运输问题（转为 LP）：最小化总运费。供需不平衡时自动加零成本虚拟产地/销地配平（标准做法，
+    虚拟产地的调运=未满足需求、虚拟销地的调运=过剩供应）——生产中不平衡才是常态。"""
+    _need_scipy()
+    supply = [float(x) for x in supply]
+    demand = [float(x) for x in demand]
+    cost = [[float(x) for x in row] for row in cost]
+    ts, td = sum(supply), sum(demand)
+    note = ''
+    if ts + 1e-9 < td:          # 供不应求：加虚拟产地（一行零成本），其调运即未满足需求
+        cost = cost + [[0.0] * len(demand)]
+        supply = supply + [td - ts]
+        note = f'（供<需，加虚拟产地补 {td - ts:.2f}=未满足需求）'
+    elif td + 1e-9 < ts:        # 供过于求：加虚拟销地（一列零成本），其调运即过剩供应
+        cost = [row + [0.0] for row in cost]
+        demand = demand + [ts - td]
+        note = f'（供>需，加虚拟销地吸 {ts - td:.2f}=过剩供应）'
+    supply, demand = np.asarray(supply, float), np.asarray(demand, float)
+    cost = np.asarray(cost, float)
+    m, n = cost.shape
+    c = cost.flatten()
+    # 供应约束（≤）与需求约束（≥转≤）
+    A_ub, b_ub = [], []
+    for i in range(m):
+        row = np.zeros(m * n)
+        row[i * n:(i + 1) * n] = 1
+        A_ub.append(row)
+        b_ub.append(supply[i])
+    for j in range(n):
+        row = np.zeros(m * n)
+        row[j::n] = -1
+        A_ub.append(row)
+        b_ub.append(-demand[j])
+    res = linprog(c, A_ub=A_ub, b_ub=b_ub, bounds=[(0, None)] * (m * n), method='highs')
+    plan = np.round(res.x.reshape(m, n), 2)
+    print(f'[运输] 最小总运费 = {res.fun:.2f}{note}\n  调运方案：\n{plan}')
+    return {'total_cost': round(float(res.fun), 2), 'plan': plan}
+
+
+if __name__ == '__main__':
+    if not HAS_SCIPY:
+        print('SKIP solver.py 自测：未装 scipy（生产环境 run_python 传 packages=["scipy"]）')
+    else:
+        # 生产组合：max 3A+5B s.t. A≤4, 2B≤12, 3A+2B≤18
+        r = linprog_solve(c=[3, 5], A_ub=[[1, 0], [0, 2], [3, 2]], b_ub=[4, 12, 18],
+                          bounds=[(0, None), (0, None)], names=['A', 'B'])
+        assert r['success'] and abs(r['objective'] - 36.0) < 1e-3  # 经典解 A=2,B=6 → 36
+        asg = assignment([[9, 2, 7], [6, 4, 3], [5, 8, 1]])
+        assert asg['total'] <= 9  # 最优匹配
+        tr = transport([20, 30], [10, 25, 15], [[8, 6, 10], [9, 12, 13]])
+        assert tr['total_cost'] > 0 and tr['plan'].sum() == 50
+        tr2 = transport([50, 30], [10, 25, 15], [[8, 6, 10], [9, 12, 13]])  # 供>需 80>50：自动配平不崩
+        assert tr2['plan'].sum() == 80  # 含虚拟销地吸收的 30 过剩供应
+        print('OK solver.py')

package/skills/pdf-toolkit/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pdf-toolkit
+description: PDF 处理：拆分/合并/抽页/旋转/水印/加密解密/页信息。当用户说"PDF 拆分/合并/加水印/提取某几页/去密码"时使用。
+version: 1.0.0
+---
+
+# PDF 处理（经 run_python 执行，pypdf 已随托管运行时就绪）
+
+## 先分清两类任务
+
+- **读内容**（总结/翻译/问答）：优先 `read_document`（平台解析，支持数百页分段通读，扫描件也能 OCR）；pypdf 的 `extract_text()` 对扫描件返回空。
+- **操作文件**（拆/合/水印/加密）：用本技能，`read_skill_file` 读 `scripts/pdf_ops.py` 连同任务代码执行。
+
+## 代码模式
+
+```python
+from pdf_ops import info, split, merge, rotate, watermark_text, decrypt
+
+info('合同.pdf')                                  # 页数/元数据/是否加密（动手前先看）
+split('合同.pdf', '1-3,7', '合同_节选.pdf')        # 抽页（页码从 1 起，支持区间与散页）
+merge(['a.pdf', 'b.pdf'], '合并.pdf')
+rotate('扫描.pdf', 90, '转正.pdf')                 # 顺时针
+watermark_text('报告.pdf', '内部资料 勿外传', '报告_水印.pdf')   # 需 reportlab：run_python 传 packages=['reportlab']
+decrypt('加密.pdf', '密码', '解密.pdf')            # 仅限用户提供了合法密码的自有文件
+```
+
+## 注意
+
+- **水印**依赖 reportlab（生成水印层再逐页叠加）：调用 run_python 时带 `packages=['reportlab']` 按需补装；中文水印 helper 已注册 CID 字体（STSong-Light），无需字体文件。
+- 加密 PDF：任何操作前先 `decrypt`；用户没给密码就直说，**不尝试破解**。
+- 页码口径：对用户一律 1 起；pypdf 内部 0 起（helper 已转换）。
+- 大 PDF（几百 MB）逐页流式处理没问题，但别 extract_text 全量打印——输出有 30K 截断。
+
+## 验收自查
+
+- [ ] 动手前 `info()` 的输出在结果里（页数对得上用户预期）
+- [ ] 每个产物都重开 `info()` 校验页数并 print
+- [ ] 水印/旋转抽查了首页效果描述（页数、方向）
+- [ ] 没有对加密文件做未授权尝试
+
+## 附件
+
+- `scripts/pdf_ops.py` — info/split/merge/rotate/watermark_text/decrypt 六件套（页码 1 起、产物自动 info 校验）；可直接执行自测（自建空白页 PDF 演练）

package/skills/pdf-toolkit/scripts/pdf_ops.py

@@ -0,0 +1,137 @@
+# PDF 操作六件套（经 run_python 执行）。页码对外一律 1 起；每个产物写完自动 info 校验。
+# 水印需 reportlab（run_python 传 packages=['reportlab'] 按需装），其余仅 pypdf。
+# 直接执行本文件 = 自测：自建空白页 PDF 演练 拆/合/转（水印在装了 reportlab 时才验）。
+from pypdf import PdfReader, PdfWriter
+
+
+def info(path, quiet=False):
+    """页数/元数据/加密状态。动手前先看，产物写完再看。"""
+    r = PdfReader(path)
+    enc = r.is_encrypted
+    meta = {} if enc else {k.strip('/'): str(v) for k, v in (r.metadata or {}).items()}
+    n = 0 if enc else len(r.pages)
+    if not quiet:
+        print(f'[info] {path} · {"已加密" if enc else f"{n} 页"}'
+              + (f' · {meta}' if meta else ''))
+    return {'pages': n, 'encrypted': enc, 'meta': meta}
+
+
+def _parse_ranges(spec, total):
+    """'1-3,7,10-12' → 0 起页索引列表（越界报错）。"""
+    out = []
+    for part in str(spec).replace('，', ',').split(','):
+        part = part.strip()
+        if not part:
+            continue
+        if '-' in part:
+            a, b = part.split('-', 1)
+            lo, hi = int(a), int(b)
+        else:
+            lo = hi = int(part)
+        if not (1 <= lo <= hi <= total):
+            raise ValueError(f'页码越界：{part}（共 {total} 页，页码从 1 起）')
+        out.extend(range(lo - 1, hi))
+    return out
+
+
+def split(path, ranges, out):
+    """抽页：split('a.pdf', '1-3,7', 'out.pdf')。"""
+    r = PdfReader(path)
+    w = PdfWriter()
+    for i in _parse_ranges(ranges, len(r.pages)):
+        w.add_page(r.pages[i])
+    with open(out, 'wb') as f:
+        w.write(f)
+    info(out)
+    return out
+
+
+def merge(paths, out):
+    w = PdfWriter()
+    for p in paths:
+        w.append(p)
+    with open(out, 'wb') as f:
+        w.write(f)
+    info(out)
+    return out
+
+
+def rotate(path, degrees, out, pages=None):
+    """顺时针旋转（pages 缺省=全部，或 '2-5' 式页码串）。"""
+    r = PdfReader(path)
+    idx = set(_parse_ranges(pages, len(r.pages))) if pages else set(range(len(r.pages)))
+    w = PdfWriter()
+    for i, page in enumerate(r.pages):
+        w.add_page(page.rotate(degrees) if i in idx else page)
+    with open(out, 'wb') as f:
+        w.write(f)
+    info(out)
+    return out
+
+
+def watermark_text(path, text, out, opacity=0.15, size=36, angle=30):
+    """全页文字水印。依赖 reportlab（packages=['reportlab']）；中文用内置 CID 字体，无需字体文件。"""
+    import io
+    try:
+        from reportlab.lib.pagesizes import A4
+        from reportlab.pdfbase import pdfmetrics
+        from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+        from reportlab.pdfgen import canvas
+    except ImportError:
+        raise ImportError('水印需要 reportlab：run_python 调用时传 packages=["reportlab"]')
+    pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light'))
+    r = PdfReader(path)
+    w = PdfWriter()
+    for page in r.pages:
+        pw, ph = float(page.mediabox.width), float(page.mediabox.height)
+        buf = io.BytesIO()
+        cv = canvas.Canvas(buf, pagesize=(pw, ph))
+        cv.setFont('STSong-Light', size)
+        cv.setFillGray(0.5, opacity)
+        cv.saveState()
+        cv.translate(pw / 2, ph / 2)
+        cv.rotate(angle)
+        cv.drawCentredString(0, 0, text)
+        cv.restoreState()
+        cv.save()
+        buf.seek(0)
+        page.merge_page(PdfReader(buf).pages[0])
+        w.add_page(page)
+    with open(out, 'wb') as f:
+        w.write(f)
+    info(out)
+    return out
+
+
+def decrypt(path, password, out):
+    """解密（仅限用户提供合法密码的自有文件；不做破解）。"""
+    r = PdfReader(path)
+    if r.is_encrypted and not r.decrypt(password):
+        raise ValueError('密码不正确')
+    w = PdfWriter()
+    for page in r.pages:
+        w.add_page(page)
+    with open(out, 'wb') as f:
+        w.write(f)
+    info(out)
+    return out
+
+
+if __name__ == '__main__':
+    w = PdfWriter()
+    for _ in range(5):
+        w.add_blank_page(width=595, height=842)  # A4 空白页 ×5
+    with open('pdf_ops_src.pdf', 'wb') as f:
+        w.write(f)
+    info('pdf_ops_src.pdf')
+    split('pdf_ops_src.pdf', '1-2,5', 'pdf_ops_split.pdf')
+    merge(['pdf_ops_split.pdf', 'pdf_ops_src.pdf'], 'pdf_ops_merge.pdf')
+    rotate('pdf_ops_split.pdf', 90, 'pdf_ops_rot.pdf')
+    assert info('pdf_ops_split.pdf', quiet=True)['pages'] == 3
+    assert info('pdf_ops_merge.pdf', quiet=True)['pages'] == 8
+    try:
+        watermark_text('pdf_ops_split.pdf', '内部资料', 'pdf_ops_wm.pdf')
+        print('watermark: OK')
+    except ImportError as e:
+        print('watermark: 跳过（' + str(e).split('：')[0] + '）')
+    print('OK')

package/skills/pivot-crosstab/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pivot-crosstab
+description: 维度透视与交叉分析（数据透视表、交叉表、占比与贡献、趋势环比同比、多维钻取）。当用户说"做个透视/交叉分析/占比/环比同比/按维度拆/分组汇总"时使用。Excel 分析链之透视环。
+version: 1.0.0
+---
+
+# 维度透视与交叉分析（Excel 分析链 · 透视环；全景见 excel-analysis-chain）
+
+pandas 的 pivot 比 Excel 透视表强在**可复算、可组合、无行数上限**。会 Excel 透视表的用户
+把"拖字段"翻译成参数即可。
+
+## 核心操作（`read_skill_file` 读 `scripts/pivot_tools.py`）
+
+- `pivot()`：多维透视——index/columns/values/aggfunc（sum/mean/count/median…），
+  margins 出总计行列;对齐 Excel"行/列/值/筛选"四区心智;
+- `crosstab_pct()`：交叉表 + 三种占比（占总体/占行/占列——**"占比"要问清占谁的**,
+  这是交叉分析最常见的口径错）;卡方独立性检验挂钩（转 statistical-testing 判断维度相关性）;
+- `share_contribution()`：占比与**贡献度**（谁贡献了增长的大头,联动帕累托）;
+- `trend()`：环比（较上期）/同比（较去年同期）/YTD 累计——**日期维表驱动**,不手拼字符串;
+  移动平均平滑;增长率的分母陷阱（基期为 0/负）如实标注。
+
+## 分析纪律
+
+- 先摸结构（data-report-pro 口径:dtypes/空值/量级）再透视;
+- 多维钻取按"总-分-明细"层层下探,每层带结论("华东增长主要来自新客,占增量 68%")而非只出表;
+- **聚合掩盖结构**：均值看分布（配 median 与分位）、总量看构成（配占比）——
+  单一聚合数会骗人;
+- 大数据量（百万行）透视用 observed=True + category 类型(data-report-pro 的 dtype 压缩)。
+
+## 产出
+
+透视结果簿（xlsx-analysis 样式回写:冻结/条件格式/数据条）+ 关键图（data-analysis:
+堆叠柱看构成/折线看趋势/热力图看交叉密度）+ 结论段。可做成月度自动透视例程（office-automation）。
+
+## 验收自查
+
+- [ ] 占比口径明确（占总/行/列）
+- [ ] 趋势用日期维驱动,基期异常已标注
+- [ ] 聚合配了分布/构成佐证
+- [ ] 钻取每层有结论
+
+## 附件
+
+- `scripts/pivot_tools.py` — pivot/crosstab_pct/share_contribution/trend（环比同比 YTD）;可直接执行自测

package/skills/pivot-crosstab/scripts/pivot_tools.py

@@ -0,0 +1,90 @@
+# 透视与交叉分析件（经 run_python 执行）：多维透视 / 交叉表三占比 / 占比贡献 / 环比同比 YTD。
+# 直接执行本文件 = 自测。
+import numpy as np
+import pandas as pd
+
+
+def pivot(df, index, values, columns=None, aggfunc='sum', margins=True):
+    """多维透视（对齐 Excel 行/列/值）。index/columns 可为列表（多层）。"""
+    pt = pd.pivot_table(df, index=index, columns=columns, values=values,
+                        aggfunc=aggfunc, margins=margins, margins_name='合计', observed=True)
+    print(f'[透视] index={index} columns={columns} values={values} agg={aggfunc}')
+    print(pt.round(2).to_markdown())
+    return pt
+
+
+def crosstab_pct(df, row, col, how='all'):
+    """交叉表 + 占比。how: 'all'占总体 / 'row'占行 / 'col'占列。"""
+    ct = pd.crosstab(df[row], df[col], margins=True, margins_name='合计')
+    if how == 'row':
+        pct = pd.crosstab(df[row], df[col], normalize='index')
+    elif how == 'col':
+        pct = pd.crosstab(df[row], df[col], normalize='columns')
+    else:
+        pct = pd.crosstab(df[row], df[col], normalize='all')
+    label = {'all': '占总体', 'row': '占行', 'col': '占列'}[how]
+    print(f'[交叉] {row} × {col} · {label}')
+    print((pct * 100).round(1).to_markdown())
+    return ct, pct
+
+
+def share_contribution(df, dim, value, base_df=None):
+    """占比与贡献度。给 base_df（上期同结构）则算增量贡献（谁贡献了增长）。"""
+    cur = df.groupby(dim, observed=True)[value].sum()
+    out = pd.DataFrame({'当期': cur})
+    out['占比%'] = (cur / cur.sum() * 100).round(1)
+    if base_df is not None:
+        base = base_df.groupby(dim, observed=True)[value].sum().reindex(cur.index).fillna(0)
+        delta_total = cur.sum() - base.sum()
+        out['上期'] = base
+        out['增量'] = (cur - base).round(2)
+        out['增量贡献%'] = (out['增量'] / delta_total * 100).round(1) if delta_total else np.nan
+    out = out.sort_values('当期', ascending=False)
+    print(f'[占比贡献] {dim} on {value}' + ('（含增量贡献）' if base_df is not None else ''))
+    print(out.to_markdown())
+    return out
+
+
+def trend(df, date_col, value, freq='M', agg='sum'):
+    """时间趋势：环比(MoM)/同比(YoY,freq=M 时按 12 期)/YTD 累计 + 3 期移动平均。"""
+    d = df.copy()
+    # 稳健解析：脏日期列（越界年份/混入"汇总"等）用 coerce 归 NaT，再剔除，避免 OutOfBounds/ParseError 打断趋势
+    d[date_col] = pd.to_datetime(d[date_col], errors='coerce')
+    if not pd.api.types.is_datetime64_any_dtype(d[date_col]):
+        print(f'[趋势] {value}：{date_col} 不是可解析的日期列'); return pd.DataFrame()
+    d = d[d[date_col].dt.year.between(1900, 2200)]
+    if d.empty:
+        print(f'[趋势] {value}：无可解析的有效日期'); return pd.DataFrame()
+    freq_norm = {'M': 'ME', 'Q': 'QE', 'Y': 'YE'}.get(freq, freq)  # pandas 3.0：M→ME
+    s = d.set_index(date_col)[value].resample(freq_norm).agg(agg)
+    out = pd.DataFrame({'值': s})
+    out['环比%'] = (s.pct_change() * 100).round(1)
+    yoy_lag = {'M': 12, 'ME': 12, 'Q': 4, 'QE': 4, 'W': 52, 'D': 365}.get(freq, 12)
+    out['同比%'] = (s.pct_change(yoy_lag) * 100).round(1)
+    out['YTD'] = s.groupby(s.index.year).cumsum()
+    out['MA3'] = s.rolling(3).mean().round(2)
+    print(f'[趋势] {value} · {freq} · 环比/同比/YTD')
+    print(out.round(2).tail(15).to_markdown())
+    return out
+
+
+if __name__ == '__main__':
+    rng = np.random.default_rng(4)
+    n = 2000
+    df = pd.DataFrame({
+        '地区': rng.choice(['华东', '华南', '华北'], n),
+        '渠道': rng.choice(['线上', '线下'], n),
+        '日期': pd.Timestamp('2025-01-01') + pd.to_timedelta(rng.integers(0, 540, n), unit='D'),
+        '销售额': rng.uniform(100, 1000, n).round(2),
+    })
+    pt = pivot(df, index='地区', columns='渠道', values='销售额', aggfunc='sum')
+    assert '合计' in pt.index
+    ct, pct = crosstab_pct(df, '地区', '渠道', how='row')
+    assert abs(pct.sum(axis=1).iloc[0] - 1.0) < 1e-9  # 占行:每行和为 1
+    cur = df[df['日期'] >= '2025-07-01']
+    base = df[df['日期'] < '2025-07-01']
+    sc = share_contribution(cur, '地区', '销售额', base_df=base)
+    assert '增量贡献%' in sc.columns
+    tr = trend(df, '日期', '销售额', freq='M')
+    assert '环比%' in tr.columns and '同比%' in tr.columns and tr['YTD'].notna().any()
+    print('OK pivot_tools.py')