@huicai/cli 2026.712.80880 → 2026.721.0

package/skills/dev-mobile/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dev-mobile
+description: 移动端开发链（双端 MVVM 单向数据流→Kotlin 协程/Swift 并发要点→生命周期与进程被杀恢复→单一数据源离线架构→启动/卡顿/内存性能预算→包体积审计→权限与隐私合规(个保法/工信部)→双端灰度发布与热修判据→崩溃率红线与符号表管理）。Android/iOS 开发、上架合规整改、崩溃治理、启动优化时载入。
+version: 1.0.0
+---
+
+# 移动端开发链
+
+eng-develop 的移动端原生孙链(Android/Kotlin+iOS/Swift);跨端框架与小程序见 dev-cross-platform;鸿蒙端(ArkTS/三端并存策略)载 **dev-harmony**。
+
+## 架构基线
+
+MVVM+单向数据流:Android(ViewModel+StateFlow/Compose)/iOS(SwiftUI+Observable 或 UIKit+MVVM);
+状态=不可变数据类,事件上行、状态下行(双向绑定的隐式修改=状态失控之源);
+模块化判据:按特性分模块(编译提速+权责边界),公共层(网络/存储/设计组件)下沉;
+**业务逻辑下沉到与 UI 框架无关的层**(UseCase/Repository)——可单测、可跨端迁移。
+
+## 语言要点
+
+- Kotlin:协程结构化并发(作用域跟生命周期:viewModelScope/lifecycleScope,**裸 GlobalScope 评审拦**);空安全禁 `!!`(用 ?.、requireNotNull 带消息);data class+copy 做不可变状态;Flow 冷流与 StateFlow 热流分清;
+- Swift:值类型优先(struct 默认,引用语义才 class);**闭包捕获 `[weak self]` 纪律**(逃逸闭包+长生命周期持有=环引用);async/await 迁移(回调金字塔逐层改);Sendable/actor 并发检查渐进开;
+- 双端共同:主线程红线——IO/网络/大 JSON 解析一律下线程(ANR 与卡顿第一来源)。
+
+## 生命周期与状态保存
+
+**进程随时被杀心智**:后台返回=可能全新进程,关键状态可恢复(SavedStateHandle/StateRestoration),恢复路径要真测(开发者选项"不保留活动"/模拟内存终止);
+配置变更(旋转/分屏/深色)与 ViewModel 边界;
+后台任务双端差异表:Android WorkManager(约束调度)/iOS BGTaskScheduler(机会性,**别承诺后台准点执行**——产品设计要按"尽力而为"来)。
+
+## 网络与离线（单一数据源）
+
+本地库(Room/CoreData/SQLDelight)=事实源,网络层是同步器——UI 只订阅本地,弱网天然可用;
+弱网设计:超时重试指数退避+抖动;请求合并与增量同步(全量拉取=流量与电量刺客);
+**序列化兼容**:字段增删容错(未知字段忽略/缺字段默认值),服务端灰度期新旧版本并存(api-design 只加不改不删同拍);
+错误分层提示:网络断(可重试)/服务端错(联系客服+traceId)/业务拒绝(按文案)。
+
+## 性能预算（每版本对照基线）
+
+- **启动**:冷启动预算定数字(如 2s);主线程初始化清单化管理,三方 SDK 懒加载/延迟到首帧后——**SDK 串行初始化是冷启动最大杀手**;启动阶段埋点分段计时(哪段涨了立刻可见);
+- **卡顿**:帧监控常驻;列表:复用+图片按控件尺寸解码(原图直塞=内存与滚动双杀)+分页;主线程 IO 检测(StrictMode/主线程 checker);
+- **内存**:图片缓存设上限;泄漏常客(Android:静态持 Context/Handler 延迟消息;iOS:闭包环引用/NotificationCenter 未移除)用 LeakCanary/Instruments 每版本扫;低内存回调要响应(清缓存)。
+
+## 包体积
+
+审计常态化:每版本体积 diff 入发布报告(eng-release);
+手段:资源(webp/矢量/按密度分发 App Bundle)/SO 按架构分包/**三方 SDK 引入前称重**(体积+权限+隐私采集三查,eng-security 供应链同拍);
+动态下发判据与合规边界:资源可动态,**代码动态下发看平台规则**(iOS 红线,见发布节)。
+
+## 权限与隐私合规（国内上架生死线）
+
+- 最小权限:用不到不申请;**用到的那一刻再弹**(首启轰炸=拒绝率与通报双高);拒绝后的降级路径要设计(无定位也能手选城市);
+- **合规红线序**:首启隐私政策弹窗(明示收集清单)→用户同意→**才允许初始化任何采集 SDK**(未同意先采集=工信部通报高频第一名);
+- 三方 SDK 合规清单:各 SDK 收集什么/隐私政策是否披露/版本是否在合规名单——SDK 升级也要复查;
+- 自启动与关联启动收敛;个人信息处理登记(个保法):收集字段-用途-保存期限表;
+- 双端隐私标注(Apple 隐私标签/App 权限说明)与实际行为一致(不一致=拒审)。
+
+## 发布与灰度
+
+- 双端通道:iOS TestFlight→分阶段发布(7 日曲线,可暂停);Android 国内多市场矩阵(各市场包管理+上架政策差异,渠道包统一构建产出);
+- 强更/软更策略分级:安全漏洞与协议不兼容才强更(强更是核武器);版本支持窗口用数据定(最低系统版本看留存占比,砍版本前出影响数);
+- **热修复判据**:iOS 禁热更代码(红线,违者下架风险);Android 补丁方案先过目标市场合规,只修崩溃级问题不带业务;
+- 回滚现实:客户端发出去收不回——**灰度分阶段+服务端开关兜底**(高危功能后端可关)是唯一的"回滚"。
+
+## 崩溃与监控
+
+崩溃率红线进发布准出(参考 <0.1%,eng-quality 准出);**新增崩溃>存量崩溃**(新版本引入的优先);
+符号表纪律:每次构建归档 dSYM/mapping(丢了=天书堆栈,发布流水线自动上传);
+ANR/卡顿/启动耗时上报(eng-observability 端侧延伸);开屏必崩=P1 走 eng-ops(暂停放量+服务端开关止血)。
+
+## 测试
+
+单测:ViewModel/UseCase 纯逻辑层(架构分层的红利);
+UI 测试:关键旅程(登录/核心任务/支付)双端各 ≤10 条;
+真机矩阵:云真机覆盖 TOP 机型+最低支持版本;发布前 monkey/稳定性长跑;自动化工程细则载 **qa-mobile-automation**;
+弱网与离线场景进用例(飞行模式切换/弱网工具)。
+
+**作业包**:`references/store-compliance-checklist.md`(隐私合规红线序(同意后才初始化 SDK)/三方 SDK 登记表/发布自查与 48h 观察项)。
+
+## 使用纪律
+
+主线程红线评审必查;上架前合规自查单全过(隐私弹窗时序/权限清单/SDK 名单);
+每版本三基线对照:启动耗时/包体积/崩溃率——**劣化当 bug 修**(eng-performance 回归防线同拍)。

package/skills/dev-mobile/references/store-compliance-checklist.md

@@ -0,0 +1,33 @@
+# 移动端上架合规与发布自查单（dev-mobile 落笔件;政策会变,存疑处以当日官方文档为准）
+
+## 1. 隐私合规红线序(工信部通报高频,逐项勾)
+
+- [ ] **首启:隐私政策弹窗→用户同意→才初始化任何采集 SDK**(未同意先采集=通报第一名;冷启动代码走查确认初始化时序)
+- [ ] 隐私政策链接可达,收集清单与实际一致(字段-用途-保存期限表:__)
+- [ ] 权限最小化:逐项有业务理由;**用到那一刻再弹**;拒绝后降级路径可用(无定位可手选城市)
+- [ ] 三方 SDK 合规清单(逐个登记):
+
+| SDK | 版本 | 收集什么 | 隐私政策已披露 | 合规名单内 | 初始化时机(同意后?) |
+|---|---|---|---|---|---|
+
+- [ ] 自启动/关联启动收敛;后台无超范围采集
+- [ ] 双端隐私标注(Apple 隐私标签/权限用途声明)与实际行为一致(不一致=拒审)
+
+## 2. 发布前技术自查
+
+- [ ] 三基线对照:启动耗时 __(基线 __)/包体积 __(基线 __)/崩溃率 __(红线 <0.1%)
+- [ ] 符号表归档:dSYM/mapping 已上传(流水线自动;丢了=天书堆栈)
+- [ ] 覆盖安装路径测过(老版本→新版本,数据迁移;覆盖崩=差评重灾)
+- [ ] 强更/软更策略确认;服务端兼容窗口(老版本还能用 __ 天)
+- [ ] 热修复合规:iOS 无代码热更;Android 补丁过目标市场规则
+
+## 3. 双端通道检查
+
+- iOS:□TestFlight 灰度 □分阶段发布(7 日曲线可暂停) □审核敏感项自查(虚拟支付/未披露权限)
+- Android:□渠道包矩阵一致(统一构建产出) □各市场上架政策差异过一遍 □灰度比例 __
+
+## 4. 上线后 48h 观察项
+
+- [ ] 崩溃聚类(新增>存量优先;开屏必崩=P1 停放量+服务端开关止血)
+- [ ] ANR/卡顿/启动耗时无劣化;核心旅程转化无异常
+- [ ] 用户评价与客服通道盯守(隐性问题从这冒头)

package/skills/dev-node/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dev-node
+description: Node.js 服务端开发链（LTS 版本与包管理统一→NestJS/Fastify/Express 判据与 BFF 定位→事件循环阻塞定位→流与背压→内存泄漏四常客与容器内存对齐→优雅退出与健康检查→错误边界(操作性 vs 编程性)→pino 结构化日志→依赖安全与原型污染→PM2 vs 容器部署判据）。Node 后端/BFF 开发、接口卡顿、内存泄漏、OOMKilled 排查时载入。
+version: 1.0.0
+---
+
+# Node.js 服务端开发链
+
+eng-develop 的 Node 服务端孙链。前端工程见 dev-frontend;此处写服务端运行时特有判据。
+
+## 基线
+
+LTS 偶数版(奇数版不上生产);版本入库锁定(.nvmrc+engines+volta 任一,CI 同版);
+包管理器一种到底,CI 用 `npm ci`/frozen-lockfile(锁文件漂移=构建不可重现);
+TS 服务:开发 tsx/ts-node 直跑,**生产跑构建产物**(启动快+源码不上线);ESM/CJS 选定一种,混用互操作坑先认。
+
+## 框架与定位判据
+
+NestJS(团队大/要 DI 与模块化强约束/长期演进)/Fastify(性能敏感/轻量自组)/Express(生态惯性,注意中间件生态陈旧度);
+**BFF 定位纪律**:聚合、裁剪、适配端差异——**业务事务不写在 BFF**(写了=第二个后端,两处业务逻辑漂移);
+网关类需求(限流/鉴权/路由)交网关层,别在应用里手搓一半。
+
+## 事件循环:单线程心智
+
+- **一处阻塞=全部请求阻塞**。CPU 密集三出路:worker_threads(计算类)/子进程(隔离危险操作)/挪去别的服务(量大成规模);
+- 隐形阻塞杀手:大 JSON.parse/stringify(几 MB 级就有感)、同步 fs/crypto 系列(带 Sync 后缀的都别在请求路径)、复杂正则灾难性回溯(ReDoS,eng-security);
+- 定位:event loop delay/lag 指标常驻监控(eng-observability)+`--inspect` CPU profile 火焰图+长任务日志;
+- 并发控制:**无界并发是自我 DoS**(`Promise.all` 一万个请求打下游),并发池限流(p-limit 思路)+下游超时。
+
+## 流与背压
+
+大文件/大结果集必须流式(整读进内存=OOM 预定);
+`pipeline()` 替手动 pipe(错误传播与资源清理内建,手 pipe 漏 error 监听=进程崩);
+**背压尊重**:write 返回 false 就停,等 drain 再写(不等=内存缓冲区无限涨);
+HTTP 响应流式下发(CSV 导出/大列表)判据:>10MB 或生成慢的都该流。
+
+## 内存:泄漏四常客与容器对齐
+
+- 四常客:无上限缓存(Map 当缓存不设逐出→lru 化)/闭包长引用(回调持大对象)/事件监听未卸(EventEmitter 泄漏警告别 setMaxListeners 掩耳)/定时器未清(setInterval 无 clear);
+- 定位:heapsnapshot 两次快照对比(泄漏对象增量一目了然);生产用 `--heapsnapshot-signal` 或诊断通道;
+- **容器内存对齐**:`--max-old-space-size` 与容器 limit 匹配(留 25% 给堆外),默认堆上限≠容器限额——不对齐=莫名 OOMKilled(K8s 事件里才看得到,应用日志无迹);
+- Buffer 属堆外,大量 Buffer 场景堆不大也能超容器限额。
+
+## 进程生命周期与部署
+
+- **优雅退出序**:收 SIGTERM → 停接新请求(server.close)→ 在途请求完成 → 关连接池/MQ 消费 → 退出;超时兜底强杀(30s);K8s preStop+terminationGracePeriod 配合;
+- 健康检查两级:liveness 简单自检(别查依赖,eng-infra 探针判据)/readiness 查依赖;
+- 部署判据:**容器/K8s 下单进程副本交编排,别再 PM2 cluster**(两层管理打架);裸机多核才用 PM2 cluster;
+- 崩溃哲学:uncaughtException/unhandledRejection **必须挂**——记日志+优雅退出,不硬扛(状态已不可信);进程管理器/编排负责拉起。
+
+## 错误边界
+
+操作性错误(下游超时/校验失败)= 预期内,分类处理+重试退避;编程性错误(undefined 调用)= bug,快崩快修;
+async 错误统一到框架错误中间件(Express 的 async 包装/Fastify 内建);
+错误响应统一结构+traceId(eng-observability);**吞错(catch 后空过)评审红线**(eng-develop 通则)。
+
+## 日志
+
+pino 结构化 JSON(console.log 上生产=不可检索+性能差);
+requestId/traceId 用 AsyncLocalStorage 贯穿(手传参数版本必漏);
+日志分级与敏感信息纪律承 eng-observability。
+
+## 依赖与安全
+
+audit 门禁分级(eng-security SCA SLA);锁文件必提交;
+**安装脚本风险**:第三方包 postinstall 可执行任意代码,私服白名单+`--ignore-scripts` 判据(开了要处理需编译依赖);
+原型污染:合并/克隆工具对外部输入慎用(`__proto__` 键),入口统一 schema 校验(zod/ajv)——**校验过的数据才进业务**;
+eval/new Function 禁;child_process 拼接命令禁(参数数组化,eng-security 命令注入)。
+
+## 测试
+
+node:test 或 vitest;接口级 supertest(起内存 server 全链路);
+时间与随机注入;外部服务 mock 在 HTTP 层(nock 思路)而非函数层(更接近真实);
+DB 集成测试真库容器(eng-quality 同则)。
+
+**作业包**:`scripts/node-triage.sh`(cgroup 内存对齐(OOMKilled 头号根因)/句柄/CLOSE_WAIT 归属/关键环境一键初判)。
+
+## 使用纪律
+
+请求路径禁同步 IO 与无界并发(评审必查);压测定容量再上线(eng-performance);
+每次 OOM/卡死事故回写:泄漏模式或阻塞源入本链清单;
+BFF 的接口契约与前端同源(api-design 生成类型,dev-frontend 同拍)。

package/skills/dev-node/scripts/node-triage.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+# Node 进程一键排障（dev-node 内存对齐/句柄/连接泄漏的采集与初判）。只读,POSIX sh,降级友好。
+# 用法: sh node-triage.sh <PID>
+# 覆盖: 容器内存对齐(--max-old-space-size vs cgroup,OOMKilled 头号根因)/RSS 与句柄水位/
+#       CLOSE_WAIT 归属/线程数/关键环境变量。堆内 profile 走 --inspect/heapsnapshot(链内画像节)。
+PID="$1"
+[ -z "$PID" ] && { echo "用法: node-triage.sh <PID>"; exit 2; }
+kill -0 "$PID" 2>/dev/null || { echo "[错误] 进程 $PID 不存在或无权限"; exit 2; }
+have() { command -v "$1" >/dev/null 2>&1; }
+Y=""
+yel() { Y="$Y
+  [!] $1"; }
+
+echo "==== Node 排障 PID=$PID ===="
+ps -o pid,user,etime,rss,args -p "$PID" 2>/dev/null | head -2
+RSS_KB=$(ps -o rss= -p "$PID" 2>/dev/null | tr -d ' ')
+[ -n "$RSS_KB" ] && echo "RSS: $((RSS_KB / 1024))MB"
+
+echo ""
+echo "---- 内存对齐(OOMKilled 第一嫌疑) ----"
+ARGS=$(ps -o args= -p "$PID" 2>/dev/null)
+MOS=$(echo "$ARGS" | grep -oE 'max-old-space-size=[0-9]+' | head -1 | cut -d= -f2)
+[ -z "$MOS" ] && [ -r "/proc/$PID/environ" ] && \
+  MOS=$(tr '\0' '\n' < "/proc/$PID/environ" 2>/dev/null | grep -oE 'max-old-space-size=[0-9]+' | head -1 | cut -d= -f2)
+echo "--max-old-space-size: ${MOS:-未设置(默认堆上限≠容器限额)}"
+CG=""
+for f in /sys/fs/cgroup/memory.max /sys/fs/cgroup/memory/memory.limit_in_bytes; do
+  [ -r "$f" ] && CG=$(cat "$f") && break
+done
+if [ -n "$CG" ] && [ "$CG" != "max" ]; then
+  CGMB=$((CG / 1048576))
+  echo "cgroup 内存上限: ${CGMB}MB"
+  if [ -z "$MOS" ]; then
+    yel "容器有限额但未设 max-old-space-size —— 建议设为 limit 的 75%(≈$((CGMB * 3 / 4))MB,留堆外与 Buffer)"
+  elif [ "$MOS" -gt $((CGMB * 9 / 10)) ] 2>/dev/null; then
+    yel "max-old-space-size(${MOS}MB) 逼近 cgroup(${CGMB}MB) —— 堆外+Buffer 无余量,OOMKilled 风险"
+  fi
+  [ -n "$RSS_KB" ] && [ $((RSS_KB / 1024)) -gt $((CGMB * 85 / 100)) ] && yel "RSS 已达 cgroup 的 85%+ —— 快照对比找泄漏四常客"
+else
+  echo "cgroup: 未检出限额(裸机/非容器)"
+fi
+
+echo ""
+echo "---- 句柄与连接 ----"
+if [ -d "/proc/$PID/fd" ]; then
+  FD=$(ls "/proc/$PID/fd" 2>/dev/null | wc -l | tr -d ' ')
+  LIM=$(grep -i 'Max open files' "/proc/$PID/limits" 2>/dev/null | awk '{print $4}')
+  echo "打开句柄: $FD / 上限 ${LIM:-?}"
+  [ -n "$LIM" ] && [ "$LIM" != "unlimited" ] && [ "$FD" -gt $((LIM * 7 / 10)) ] 2>/dev/null && yel "句柄 >70% 上限 —— 泄漏四常客+流未关排查"
+elif have lsof; then
+  FD=$(lsof -p "$PID" 2>/dev/null | wc -l | tr -d ' ')
+  echo "打开句柄(lsof 估计): $FD"
+fi
+if have ss; then
+  CW=$(ss -tanp 2>/dev/null | grep "pid=$PID" | grep -c CLOSE-WAIT)
+  EST=$(ss -tanp 2>/dev/null | grep "pid=$PID" | grep -c ESTAB)
+  echo "本进程连接: ESTAB=$EST CLOSE_WAIT=$CW"
+  [ "$CW" -gt 50 ] 2>/dev/null && yel "CLOSE_WAIT=$CW —— 响应体/连接未消费关闭(HTTP client body 必须消费或销毁)"
+fi
+if [ -r "/proc/$PID/status" ]; then
+  TH=$(grep '^Threads' "/proc/$PID/status" | awk '{print $2}')
+  echo "线程数: $TH (libuv 线程池默认 4,UV_THREADPOOL_SIZE 可调;线程暴涨查 worker_threads 泄漏)"
+fi
+
+echo ""
+echo "---- 关键环境 ----"
+if [ -r "/proc/$PID/environ" ]; then
+  tr '\0' '\n' < "/proc/$PID/environ" 2>/dev/null | grep -E '^(NODE_ENV|NODE_OPTIONS|UV_THREADPOOL_SIZE)=' | sed 's/^/  /'
+  tr '\0' '\n' < "/proc/$PID/environ" 2>/dev/null | grep -q '^NODE_ENV=production' || yel "NODE_ENV 非 production —— 部分框架走开发路径(性能与缓存差一截)"
+else
+  echo "  (/proc 不可读,环境变量跳过 —— macOS/权限)"
+fi
+
+echo ""
+echo "==== 初判 ===="
+if [ -n "$Y" ]; then echo "待处理:$Y"; else echo "未见系统侧明显异常 —— 事件循环阻塞/堆内泄漏走 --inspect profile 与 heapsnapshot(dev-node 画像节)"; fi
+echo "深入三招: event loop delay 指标 / CPU profile 火焰图 / 两次 heapsnapshot 对比。"
+exit 0

package/skills/dev-php/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: dev-php
+description: PHP 技术开发链（PHP 8 现代化(严格类型/枚举/readonly)→5.x→8 迁移路径与 rector→Composer 治理→Laravel/ThinkPHP/Symfony 判据→Eloquent N+1→FPM 调参公式与慢日志→OPcache/JIT 判据→安全 TOP(注入/反序列化/上传/弱比较)→PHPUnit→Swoole 常驻心智切换→部署重载）。PHP 开发、老系统维护升级、FPM 性能、安全整改时载入。
+version: 1.0.0
+---
+
+# PHP 技术开发链
+
+eng-develop 的 PHP 孙链。通则承 eng-develop,此处只写 PHP 特有判据。国内存量 PHP 系统多为 5.x/7.x 老项目,迁移与安全是本链两大重心。
+
+## 版本与现代化
+
+- 新代码 8.1+ 起步(枚举/readonly/纤程/never);**新文件 `declare(strict_types=1)` 纪律**(弱类型自动转换是 PHP bug 温床之首);
+- 类型全覆盖渐进:参数/返回/属性类型逐步补(phpstan/psalm 静态分析分级推进,level 逐档提);
+- **5.x→8 迁移路径**:先上静态分析摸家底 → rector 自动化改写过渡到 7.4 → 高危变更表人工过(引用传参语义/花括号字符串下标移除/魔术引号与 mysql_ 系残留/create_function/each)→ 8.x(命名参数与内部函数签名收紧)——分模块灰度,全量回归护航(refactor-safely 特征测试先行);
+- ext 兼容清单先查(老扩展无 8 版=改造或替换,迁移排期大头常在这)。
+
+## Composer 治理
+
+锁文件必提交;`config.platform.php` 锁定目标运行时版本(本地 8.3 装出生产 8.1 跑不了的包=经典);
+autoload PSR-4,禁 require 手串文件;
+**`composer update` 只许带包名**(裸 update=全量开盲盒,升级走 dependency-upgrade);
+私服/国内镜像统一(dev-toolchain);abandoned 包季度巡检(PHP 生态弃坑率高)。
+
+## 框架判据
+
+Laravel(生态最全/招聘面广;魔法多,**门面与魔术方法让 IDE 与静态分析打折**,ide-helper 类工具补);
+ThinkPHP(国内存量大/中文文档;版本代差大,3.x 与 6+ 是两个世界,老版本安全补丁要盯);
+Symfony 组件化(自建/改造老项目的正路:不换框架,先引组件替手写轮子);
+**存量框架不折腾**(换框架=重写,按 eng-research 退出成本评估),新服务再选型。
+
+## 工程结构与 ORM
+
+Controller 薄;输入验证收口(FormRequest/验证器,**$_GET/$_POST 裸用评审拦**);服务层持事务边界;
+**Eloquent N+1 专项**:列表页 `with()` 预加载;debugbar/查询日志盯单请求查询数(>20 条即嫌疑);`chunk/cursor` 处理大结果集(all() 整取=内存峰值);
+生成 SQL 抽查 EXPLAIN(eng-database ORM 不免检)。
+
+## PHP-FPM 调参
+
+- pm 模式:`dynamic` 默认/`static` 高负载稳定(省进程管理开销);
+- **max_children 公式**:可用内存 ÷ 单进程峰值内存(实测 RSS,别拍脑袋)——设大了 OOM,设小了 502/排队;
+- 必开三件:`request_slowlog_timeout`+slowlog(慢请求自动打栈,定位神器)/`pm.max_requests`(防泄漏兜底重启)/`pm.status_path`(池状态监控入 eng-observability);
+- 超时链对齐:nginx `fastcgi_read_timeout` ≥ PHP `max_execution_time`,不对齐=504 与半执行。
+
+## OPcache / JIT
+
+**OPcache 生产必开**(字节码缓存,数倍差距);容量与命中率监控(满了=静默性能悬崖);
+`validate_timestamps=0` 生产关校验(发布时显式重载,见部署节);
+preload 判据(框架核心类常驻,8.x 收益可测再开);
+JIT:CPU 密集计算才有感,常规 Web IO 型收益小——**别为 JIT 折腾,先修 N+1**。
+
+## 安全 TOP（PHP 重灾区专项,总则承 eng-security）
+
+SQL 注入:PDO 预处理参数化(拼接=红线);ORM 的 `whereRaw`/原生片段照查;
+**反序列化:`unserialize()` 外部输入=RCE 级危险**(POP 链),一律 JSON 替代;`phar://` 触发面(文件函数收到用户可控路径要过滤协议);
+文件上传:三验(白名单扩展名+MIME+内容魔数)+存储出 webroot+随机名+禁执行权限;
+文件包含:用户输入进 include/require=红线(模板白名单映射);
+**弱比较**:`==` 的魔法(`"0e123"=="0e456"` 为真/`0=="a"` 历史差异)——比较用 `===`;密码一律 `password_hash/password_verify`,token 比较 `hash_equals`(防时序);
+XSS:模板引擎自动转义确认开启({!! !!} 与 raw 输出评审必查);
+配置红线:`display_errors=Off` 生产铁律(错误回显=信息泄露),错误进日志(eng-observability)。
+
+## 测试
+
+PHPUnit;数据库测试事务回滚 trait(RefreshDatabase 类机制,注意速度选内存库要认差异——eng-quality 真库判据);
+HTTP 功能测试(框架内建 `$this->post()` 断言链);
+**老代码先补特征测试再动**(锁住现状行为,refactor-safely)——没有测试的重构叫赌博。
+
+## 常驻内存判据（Swoole/RoadRunner/FrankenPHP）
+
+上的判据:长连接(IM/推送)/高并发低延迟/队列消费常驻——常规 CRUD 上 FPM 足够;
+**心智切换认账**:FPM 的"请求即世界"失效——全局/静态变量跨请求污染(单例带用户态=窜数据事故)、连接要池化、内存泄漏会累积(监控+定期优雅重启)、`die/exit` 不可用;
+框架要选常驻兼容版本;能力不足时别硬上(排障工具与人才储备都比 FPM 少)。
+
+## 部署
+
+FPM+nginx 基线;容器化:fpm+nginx 双容器(职责清)或 supervisord 单容器(简单)判据;
+**发布重载序**:新代码就位 → `opcache_reset`/优雅 reload FPM(USR2)→ 验证——validate_timestamps=0 时忘重载=新代码不生效"灵异事件";
+定时任务收敛(crontab 入库管理或调度中心,散落各机=幽灵任务)。
+
+**作业包**:`scripts/fpm-calc.py`(max_children 内存公式+目标 QPS 吞吐核对+必开三件与超时链提醒)。
+
+## 使用纪律
+
+strict_types 新文件全覆盖;静态分析 level 只升不降;
+`==`/裸超全局/unserialize 评审三查;每次安全整改回写本链 TOP 清单;
+慢日志月度 TOP 治理(与 sql-tuning 联动)。

package/skills/dev-php/scripts/fpm-calc.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# PHP-FPM 调参计算器（dev-php max_children 公式的可执行版）。python3 stdlib,零依赖。
+# 用法:
+#   python3 fpm-calc.py --mem-total-mb 8192 --proc-mem-mb 64 [--reserve-mb 1024] [--avg-req-ms 80 --target-qps 300]
+#   python3 fpm-calc.py --selftest
+# proc-mem-mb 用实测 RSS(别拍脑袋): ps -o rss= -C php-fpm | awk '{s+=$1;n++} END{print s/n/1024}'
+import argparse
+import sys
+
+
+def calc(a):
+    avail = a.mem_total_mb - a.reserve_mb
+    if avail <= 0 or a.proc_mem_mb <= 0:
+        print("[错误] 可用内存或单进程内存不合法")
+        return 2
+    mc = int(avail / a.proc_mem_mb)
+    print(f"max_children = (总内存{a.mem_total_mb}MB - 预留{a.reserve_mb}MB[OS/DB/缓存]) ÷ 单进程峰值{a.proc_mem_mb}MB = {mc}")
+    print(f"  配套建议: pm=dynamic 时 start={max(mc // 4, 2)} min_spare={max(mc // 8, 2)} max_spare={max(mc // 2, 4)};高负载稳定场景 pm=static")
+    if a.avg_req_ms and a.target_qps:
+        need = a.target_qps * a.avg_req_ms / 1000
+        print(f"吞吐核对: 目标 {a.target_qps} QPS × 平均 {a.avg_req_ms}ms = 需并发 worker ≈ {need:.0f}")
+        if need > mc:
+            print(f"  [红] 需要 {need:.0f} > 内存上限 {mc} —— 内存不够撑目标 QPS:降单进程内存(查泄漏/大数组)、加机器、或上缓存降 QPS 到库")
+        else:
+            print(f"  内存上限 {mc} 足够(余量 {(mc - need) * 100 / mc:.0f}%);瓶颈更可能在下游(N+1/慢 SQL,先修那个)")
+    print("必开三件核对: request_slowlog_timeout+slowlog / pm.max_requests(防泄漏兜底) / pm.status_path(监控);")
+    print("超时链对齐: nginx fastcgi_read_timeout ≥ PHP max_execution_time(不对齐=504 与半执行,dev-php)。")
+    return 0
+
+
+def selftest():
+    ns = argparse.Namespace
+    assert calc(ns(mem_total_mb=8192, proc_mem_mb=64, reserve_mb=1024, avg_req_ms=80, target_qps=300)) == 0
+    assert calc(ns(mem_total_mb=2048, proc_mem_mb=128, reserve_mb=512, avg_req_ms=200, target_qps=500)) == 0  # 触发红灯路径
+    print("\nselftest ok")
+    return 0
+
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv:
+        sys.exit(selftest())
+    p = argparse.ArgumentParser(description="PHP-FPM max_children 计算")
+    p.add_argument("--mem-total-mb", type=float, required=True)
+    p.add_argument("--proc-mem-mb", type=float, required=True)
+    p.add_argument("--reserve-mb", type=float, default=1024)
+    p.add_argument("--avg-req-ms", type=float)
+    p.add_argument("--target-qps", type=float)
+    sys.exit(calc(p.parse_args()))

package/skills/dev-python/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: dev-python
+description: Python 技术开发链（3.10+ 与 uv/venv 环境隔离→pyproject 单一事实源与依赖锁定→类型注解渐进 mypy→pytest fixture/参数化/mock 边界→asyncio 判据与阻塞排查→pandas 内存与向量化→cProfile/py-spy 画像→打包发布判据→常见坑 TOP→脚本工程化四件套）。Python 开发、环境依赖混乱、数据处理性能、脚本上生产时载入。
+version: 1.0.0
+---
+
+# Python 技术开发链
+
+eng-develop 的 Python 孙链。通则承 eng-develop,此处只写 Python 特有判据。
+
+## 版本与环境
+
+- 3.10+ 起步(结构化模式匹配/精确报错行);3.12+ 性能红利可观;
+- **每项目独立环境**:uv 优先(解析快、锁一致、代 pip/venv/pipx 多角色),venv+pip 兜底;**系统 Python 永不装包**(apt/brew 的 Python 是系统件,不是你的游乐场);
+- 版本声明入库:`requires-python` + `.python-version`(工具链锁,dev-toolchain 三锁之一);
+- 依赖两层分离:直接依赖(pyproject 声明,range 宽松)与锁定文件(uv.lock/requirements.txt 精确,**必提交**);更新集中走 dependency-upgrade。
+
+## 工程结构
+
+- **src 布局**(src/pkg/ 而非根目录平铺):防"测试import到了本地目录而非安装包"的经典假绿;
+- pyproject.toml 单一事实源:依赖/构建/工具配置(ruff/mypy/pytest)归一,告别 setup.py+cfg+ini 三分天下;
+- 入口纪律:库暴露 `__init__` 公共面;应用用 `if __name__ == "__main__":` + console_scripts;
+- **脚本工程化四件套**(脚本上生产的底线):argparse 参数(禁硬编码路径)/logging 替 print(可调级别)/明确退出码(0 成功非 0 失败,调度系统靠它判断)/异常兜底(裸栈滚屏≠错误处理)。
+
+## 类型注解渐进
+
+新代码必注(函数签名起步);核心模块回补;mypy 分模块渐进 strict(一步到位=劝退);
+高频工具:`Optional` 显式(隐式 None 是 bug 温床)/`TypedDict`(接口字典结构化)/`Protocol`(鸭子类型正名,免继承耦合)/dataclass 或 pydantic(边界校验判据:外部输入用 pydantic 校验,内部传递 dataclass 够用)。
+
+## 常见坑 TOP（评审自查单）
+
+可变默认参数 `def f(x=[])`(共享一个列表,用 None 哨兵);
+闭包晚绑定(循环里 lambda 全捕获最后值,默认参数固化 `lambda i=i:`);
+`is` vs `==`(is 只用于 None/单例;小整数缓存的 is 巧合别依赖);
+浮点:钱用 Decimal(字符串构造),0.1+0.2!=0.3;
+**GIL 认知**:线程只救 IO 密集;CPU 密集用多进程或 numpy/polars(C 层释放 GIL);3.13+ free-threaded 仍属评估期;
+循环 import:分层修架构或函数内延迟导入(后者是止痛不是治病);
+编码:`open()` 显式 `encoding="utf-8"`(Windows 默认 GBK 惨案高发);
+时区:naive datetime 禁上生产,`datetime.now(timezone.utc)` 起步;
+异常:禁裸 `except:`(连 KeyboardInterrupt 都吞),`except Exception` 且记日志带栈(`logger.exception`);
+路径:pathlib 替字符串拼接;`os.path.join` 遇绝对路径会"吞前缀"。
+
+## pytest 体系
+
+- fixture 金字塔:conftest.py 分层放(就近原则),作用域明确(function 默认,session 级共享资源);
+- `@pytest.mark.parametrize` 铺边界(eng-quality 三点法);
+- **mock 打补丁位置=使用处不是定义处**(`patch("app.service.requests")` 而非 `patch("requests")`——高频翻车点);mock 边界纪律承 eng-quality;
+- 慢测标记分离(`-m "not slow"` 日常,全量进 CI);随机与时间注入固定(freezegun/固定 seed)——**结果可复算**;
+- 覆盖率下限进 CI(下限告警,不冲高分)。
+
+## asyncio 判据
+
+- 上 async 的判据:高并发 IO(爬虫/网关/长连接);CPU 密集与低并发脚本别凑热闹;
+- **同步库混进事件循环=全场卡死**(requests 混在 async 里),用 aiohttp/httpx(async 客户端);存量同步调用 `run_in_executor` 包;
+- 超时纪律:每个 await 外部调用有 timeout(`asyncio.timeout` 上下文);
+- 并发结构化:`TaskGroup`(3.11+)统一收错,替代裸 `create_task` 散养(散养任务的异常无人认领);
+- 阻塞排查:debug 模式 `PYTHONASYNCIODEBUG=1` 报慢回调;事件循环卡顿监控。
+
+## pandas 内存与性能
+
+读取即瘦身:`usecols` 只要所需列、`dtype` 显式(默认 object 吃内存)、低基数列转 `category`;
+大文件 `chunksize` 分块或直接上 polars/duckdb(**数据>内存 1/3 就该换引擎**,duckdb 直查 parquet/csv 常常免加载);
+向量化替 `iterrows`(百倍差距);链式赋值警告的正解是 `.loc[]` 单步定位;
+中间结果落盘 parquet(重跑从断点起,eng-data-platform 中间表纪律同拍)。
+
+## 画像与排障
+
+cProfile 找热点函数(配 snakeviz 可视化);**py-spy 生产可用**(无侵入采样:`py-spy top` 实时/`py-spy dump` 卡死现场栈——进程假死第一招);
+行级瓶颈 line_profiler;内存 tracemalloc(增量快照对比找泄漏)。
+
+## 打包与发布
+
+库:wheel 构建发私服;应用:**容器优先**(环境锁死);单文件 PyInstaller 判据(无 Python 环境的分发场景)+坑先认(杀软误报/启动解压慢/隐藏导入手工补);
+入口脚本用 console_scripts 而非"python 某路径"(路径耦合)。
+
+**作业包**:`scripts/venv-doctor.sh`(解释器身份/venv 状态/镜像源/锁文件纪律/同名遮蔽等坑位一键体检)。
+
+## 使用纪律
+
+无锁定文件不部署;脚本三无(无日志/无参数/无退出码)不上生产;
+数据处理固定 seed+版本锁定保证可复算;每次环境事故回写:锁文件纪律或镜像基线(dev-toolchain)。

package/skills/dev-python/scripts/venv-doctor.sh

@@ -0,0 +1,75 @@
+#!/bin/sh
+# Python 环境医生（dev-python"环境依赖混乱"的一键诊断）。只读,零依赖,POSIX sh。
+# 用法: sh venv-doctor.sh [项目目录]      # 缺省当前目录
+# 诊断: 解释器身份/venv 状态/镜像源配置/锁文件纪律/版本声明一致性/依赖冲突/常见坑位。
+DIR="${1:-.}"
+cd "$DIR" 2>/dev/null || { echo "[错误] 目录不存在: $DIR"; exit 2; }
+have() { command -v "$1" >/dev/null 2>&1; }
+Y=""
+yel() { Y="$Y
+  [!] $1"; }
+
+echo "==== Python 环境体检 ($(pwd)) ===="
+
+echo "---- 解释器身份 ----"
+for py in python3 python; do
+  if have "$py"; then
+    echo "$py → $(command -v $py) ($($py -V 2>&1))"
+  fi
+done
+have python3 || have python || { echo "[红] 无 python —— 离线环境从离线仓装(env-offline)"; exit 3; }
+PY=$(have python3 && echo python3 || echo python)
+
+echo ""
+echo "---- venv 状态 ----"
+INV=$($PY -c "import sys; print('venv' if sys.prefix != getattr(sys,'base_prefix',sys.prefix) else 'system')" 2>/dev/null)
+if [ "$INV" = "venv" ]; then
+  echo "当前解释器在虚拟环境: $($PY -c 'import sys; print(sys.prefix)')"
+else
+  echo "当前解释器 = 系统 Python"
+  [ -n "$VIRTUAL_ENV" ] && yel "VIRTUAL_ENV=$VIRTUAL_ENV 已设但解释器不是它 —— PATH 顺序问题(激活没生效/shell 缓存 hash -r)"
+  [ -d .venv ] && yel "项目有 .venv/ 但未激活 —— 你可能正把包装进系统 Python(系统 Python 永不装包纪律)"
+fi
+echo "site-packages: $($PY -c 'import site; print(site.getsitepackages()[0] if site.getsitepackages() else site.getusersitepackages())' 2>/dev/null)"
+
+echo ""
+echo "---- 版本声明一致性(dev-toolchain 三锁) ----"
+DECL=""
+[ -f .python-version ] && DECL=$(cat .python-version | head -1) && echo ".python-version: $DECL"
+[ -f pyproject.toml ] && grep -E 'requires-python' pyproject.toml | head -1 | sed 's/^/pyproject: /'
+RUN=$($PY -c 'import sys; print("%d.%d"%sys.version_info[:2])')
+echo "运行版本: $RUN"
+[ -n "$DECL" ] && case "$DECL" in "$RUN"*) : ;; *) yel "运行版本 $RUN 与 .python-version($DECL) 不一致";; esac
+
+echo ""
+echo "---- 依赖与锁文件 ----"
+LOCK=""
+for f in uv.lock poetry.lock requirements.txt requirements.lock Pipfile.lock; do
+  [ -f "$f" ] && LOCK="$LOCK $f"
+done
+if [ -n "$LOCK" ]; then echo "锁文件:$LOCK"; else yel "无锁文件 —— 无锁定文件不部署(dev-python 纪律)"; fi
+[ -f requirements.txt ] && grep -cE '==' requirements.txt >/dev/null 2>&1 && {
+  UNPINNED=$(grep -vcE '^(#|$|.*==|.*@|-r )' requirements.txt)
+  [ "$UNPINNED" -gt 0 ] 2>/dev/null && yel "requirements.txt 有 $UNPINNED 行未钉版本(应用要精确锁定)"
+}
+if have uv; then echo "uv: $(uv --version 2>/dev/null)"; fi
+echo "pip 源配置:"
+$PY -m pip config list 2>/dev/null | grep -E 'index-url|trusted' | sed 's/^/  /' || echo "  (默认官方源;内网配私服/镜像,dev-toolchain)"
+
+echo ""
+echo "---- 依赖健康(pip check) ----"
+CHK=$($PY -m pip check 2>&1 | head -5)
+if echo "$CHK" | grep -qiE 'no broken|^$'; then echo "  无冲突"; else echo "$CHK" | sed 's/^/  /'; yel "存在依赖冲突(pip check 有输出)"; fi
+
+echo ""
+echo "---- 常见坑位扫描 ----"
+[ -f setup.py ] && [ -f pyproject.toml ] && echo "  setup.py 与 pyproject 并存(逐步归一到 pyproject 单一事实源)"
+ls *.py 2>/dev/null | grep -qE '^(json|csv|logging|token|types|email)\.py$' && yel "项目根有与标准库同名的 .py(json.py 等)—— 遮蔽标准库的经典事故"
+[ -d src ] || { ls *.py >/dev/null 2>&1 && [ -f pyproject.toml ] && echo "  非 src 布局(可用;新库建议 src/ 防'测到本地目录'假绿)"; }
+[ -n "$PYTHONPATH" ] && yel "PYTHONPATH=$PYTHONPATH 已设 —— 隐式导入路径,排查导入错乱先看它"
+
+echo ""
+echo "==== 结论 ===="
+if [ -n "$Y" ]; then echo "待处理:$Y"; else echo "环境基本健康。"; fi
+echo "处置对照: dev-python 版本与环境节;新机配置走 dev-toolchain。"
+exit 0