@huicai/cli 2026.714.0 → 2026.721.0

package/skills/dev-frontend/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: dev-frontend
+description: 前端开发技术链（Vite 工程化与 Node 版本锁定→TS 严格渐进与 any 治理→React/Vue 状态分层判据→组件设计与状态全集→请求层规范(拦截/取消/竞态/幂等重试)→路由权限双层→Core Web Vitals 性能与分包→兼容降级→Vitest/Playwright→静态资源缓存与发布）。前端开发、首屏优化、工程化治理、还原走查、线上白屏排查时载入。
+version: 1.0.0
+---
+
+# 前端开发技术链
+
+eng-develop 的前端孙链。通则承 eng-develop,视觉与体验规范承 eng-ux,此处写前端工程特有判据。
+
+## 工程化基线
+
+- 构建 Vite 默认;Node 版本入库锁定(.nvmrc+engines+CI 同版,dev-toolchain 三锁);包管理器统一一种且锁文件必提交(pnpm 判据:磁盘复用+幽灵依赖治理);
+- 环境变量分层:.env 本地不入库,.env.example 入库示范;**构建期变量与运行期配置分清**(要"一次构建多环境部署"的,运行期从 /config 接口或注入的全局变量读,别烤死在 bundle 里,eng-release 一次构建同拍);
+- monorepo 判据:多端共享代码(组件库/工具/类型)才上,上了就配任务编排与增量构建。
+
+## TypeScript 严格渐进
+
+新项目 strict 全开;存量先 noImplicitAny 再逐项收紧;
+**any 治理**:边界收窄(unknown 进来,类型守卫收窄),`as any` 评审必问;
+类型的事实源:API 类型从契约生成(openapi-typescript 思路,api-design 契约先行)——**手抄接口类型=注定漂移**;
+组件 props 显式导出类型;工具类型够用就好(类型体操炫技=维护债)。
+
+## 框架与状态分层（判据表,防"全局 store 万物"）
+
+| 状态类型 | 归宿 | 说明 |
+|---|---|---|
+| 组件局部 | useState/ref | 默认起点,别急着上提 |
+| 跨组件共享 | 状态提升/组合/上下文 | 传三层再考虑下一行 |
+| **服务端数据** | 请求缓存层(TanStack Query/SWR 思路) | 缓存/重取/失效内建;**塞进全局 store=手写双份真相** |
+| 真全局(登录态/主题/权限) | store(Pinia/Zustand/Redux) | 剩下的才配进这里,通常很小 |
+
+React/Vue 选型看团队存量与招聘面,不看博客热度(eng-research 评分卡);同产品别双框架并行。
+
+## 组件设计
+
+受控/非受控想清楚再写(混合=表单玄学 bug);展示组件与容器分离(展示组件可进 Storybook 类环境单测);
+props 钻透 >3 层重构(组合/slot/上下文);
+**组件状态全集齐活**:默认/加载/空/错误/超长文本/权限缺失(eng-ux 一等公民),骨架屏优于转圈;
+列表 key 用稳定 id 禁 index(重排=状态窜行)。
+
+## 请求层规范（统一封装,散装 fetch 禁）
+
+拦截器:鉴权注入/401 统一跳转/**token 刷新单飞**(并发 401 只发一次刷新,其余排队)/错误分类(网络层 vs 业务码)统一提示;
+取消:路由切换取消在途请求(AbortController);
+**竞态防护**:搜索联想类"后发先至覆盖新结果"——序号比对或取消旧请求,评审必查;
+重试幂等判据:GET 可重试(退避),POST 必须有幂等键才重试;
+超时显式设置(浏览器默认≈不超时);loading 状态防抖(<300ms 不闪 loading)。
+
+## 路由与权限
+
+路由级懒加载=分包第一刀;
+**权限双层**:路由守卫(粗粒度)+按钮/字段级(细粒度指令或组件);**前端隐藏≠安全,服务端必二次校验**(eng-security 越权双查);
+守卫内避免异步瀑布(权限数据启动时一次拉取入 store);
+刷新保活:深链接直达要能恢复上下文(状态从 URL 参数可重建,**URL 即状态**的页面才可分享)。
+
+## 性能（Core Web Vitals 三指标各个击破）
+
+- **LCP**:首屏关键资源预加载(preload 字体/首图);图片 webp/avif+响应式尺寸;SSR/预渲染判据(SEO 或首屏硬指标才上,复杂度先认);
+- **INP**:长任务拆分(>50ms 任务 yield);高频事件防抖节流;大列表虚拟滚动(>100 行);
+- **CLS**:图片/广告位写死尺寸占位;字体 swap 策略;骨架屏尺寸与真实内容一致;
+- 分包:vendor 稳定层(改动少,缓存命中)/路由层按需;**体积预算入 CI**(单入口 gzip 后预警线自定,新依赖引入先看体积与维护度;**入口应用块与 vendor 稳定层分开设预算**——vendor 是缓存层不是每次发版的首屏增量);**manualChunks 用函数形式**(对象形式把包入口整图钉进 chunk,与按需导入相抵,实战回写 2026-07);
+- 组件库按需导入真实账本(实战回写 2026-07):使用面广的后台(50+ 组件在用)按需化的即时收益在 **CSS 与"未来不为不用的组件买单"**,JS 几乎不降(重组件本来都在用);树摇是否生效用**实现级标记**抽查产物(渲染类名如 el-carousel__,组件名字符串会撞注册表假阳);API 型组件(ElMessage 族)值导入必须走 es 子路径(根入口导入=钉住整库),样式入口手动补、v-loading 单独 app.use(ElLoading)、locale 迁 el-config-provider;
+- 字体中文子集化(全量中文字体 MB 级=首屏杀手)。
+
+## 兼容与降级
+
+browserslist 显式声明(polyfill 与转译按它走,别拍脑袋);
+灰度浏览器矩阵进 eng-quality 兼容用例;
+全局错误边界:window.onerror+unhandledrejection 上报(eng-observability)+**白屏兜底页**(错误边界组件,别让用户对白屏截图)。
+
+## 测试
+
+Vitest 单测(工具函数/hooks/store);组件测试 Testing Library(**测行为不测实现**:查"用户看到什么",不查内部 state);
+Playwright E2E 关键旅程 ≤15 条(eng-quality),选择器 data-testid;
+视觉回归判据:组件库/设计系统才值得上。
+
+## 静态资源发布（线上事故高发区）
+
+内容哈希文件名+长缓存(immutable),**HTML 短缓存/不缓存**(HTML 是版本指针);
+发布顺序:先传静态资源再切 HTML(反了=旧 HTML 引用新 chunk 404);旧版本资源保留一段时间(**在途用户的懒加载 chunk 还要用**,发布即删=ChunkLoadError 雨);
+**静态目录/public 文件名禁与路由重名**(服务器优先静态命中=路由被劫持,SPA 高发坑);
+SPA 服务端 fallback 到 index.html 配好(刷新 404 三件套:fallback/base/路由模式);
+sourcemap 只上传监控平台,不公开(eng-security);CDN 缓存键与灰度承 eng-infra。
+
+**作业包**:`scripts/bundle-budget.py`(dist 产物 gzip 口径体积报告+单文件与总量预算门禁+sourcemap 外泄提醒)。
+
+## 使用纪律
+
+还原走查单过了才提测(eng-ux);console/debugger 门禁拦(dev-toolchain pre-commit);
+每次线上白屏/404/窜数据事故回写本链坑清单;性能预算红线破了当 bug 修不当"下次优化"。

package/skills/dev-frontend/scripts/bundle-budget.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# 前端产物体积预算检查（dev-frontend"体积预算入 CI"的可执行版）。python3 stdlib(zlib),零依赖。
+# 用法:
+#   python3 bundle-budget.py dist/ [--budget-kb 200] [--total-kb 1500] [--top 10]
+#       # budget-kb=单 JS/CSS 文件 gzip 预警线;total-kb=全站 JS gzip 总量预警线
+#   python3 bundle-budget.py --selftest
+# 退出码: 0=预算内 1=超预算(接 CI 即体积门禁) 2=输入错。
+# 口径: gzip 后大小(接近线上传输);brotli 通常再小 10-20%,门禁口径统一即可比。
+import os
+import sys
+import zlib
+
+TEXT_EXT = {".js", ".mjs", ".css", ".html", ".svg", ".json", ".txt", ".map"}
+SKIP_EXT = {".map"}  # sourcemap 不算传输预算(不该公开分发,dev-frontend)
+
+
+def gzip_size(path):
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+        co = zlib.compressobj(6, zlib.DEFLATED, 31)  # 31=gzip 头
+        return len(co.compress(data) + co.flush()), len(data)
+    except OSError:
+        return 0, 0
+
+
+def scan(root):
+    out = []
+    for base, _dirs, files in os.walk(root):
+        for fn in files:
+            p = os.path.join(base, fn)
+            ext = os.path.splitext(fn)[1].lower()
+            gz, raw = gzip_size(p)
+            out.append((os.path.relpath(p, root), ext, raw, gz))
+    return out
+
+
+def report(root, budget_kb, total_kb, top):
+    if not os.path.isdir(root):
+        print(f"[错误] 目录不存在: {root}")
+        return 2
+    rows = scan(root)
+    if not rows:
+        print("[错误] 目录为空")
+        return 2
+    rc = 0
+    js = [(p, r, g) for p, e, r, g in rows if e in (".js", ".mjs") and e not in SKIP_EXT]
+    css = [(p, r, g) for p, e, r, g in rows if e == ".css"]
+    other = [(p, r, g) for p, e, r, g in rows if e not in (".js", ".mjs", ".css")]
+    print(f"== 体积报告 {root} (gzip 口径) ==")
+    for label, group in (("JS", js), ("CSS", css)):
+        tot_g = sum(g for _, _, g in group)
+        print(f"[{label}] {len(group)} 个文件,gzip 合计 {tot_g / 1024:.0f}KB")
+        for p, r, g in sorted(group, key=lambda x: -x[2])[:top]:
+            over = ""
+            if g > budget_kb * 1024:
+                over = f"  <== 超单文件预算 {budget_kb}KB(分包/懒加载/依赖减重)"
+                rc = 1
+            print(f"  {g / 1024:>8.1f}KB gz ({r / 1024:>7.1f}KB raw)  {p}{over}")
+    tot_js = sum(g for _, _, g in js)
+    if tot_js > total_kb * 1024:
+        print(f"[红] JS gzip 总量 {tot_js / 1024:.0f}KB > 预算 {total_kb}KB —— vendor 拆分与路由级分包复查")
+        rc = 1
+    # 分发类文件(安装包/压缩包)不是页面资源,不进大资源提示(实战回写 2026-07:dist/dl 下载区误提示)
+    dist_ext = (".dmg", ".exe", ".msi", ".pkg", ".zip", ".gz", ".7z", ".apk", ".ipa", ".hap")
+    big_assets = [(p, r) for p, r, g in other if r > 300 * 1024 and not p.lower().endswith(dist_ext)]
+    if big_assets:
+        print(f"[提示] >300KB 静态资源 {len(big_assets)} 个(图片压缩 webp/字体子集化):")
+        for p, r in sorted(big_assets, key=lambda x: -x[1])[:5]:
+            print(f"  {r / 1024:>8.0f}KB  {p}")
+    maps = [p for p, e, _, _ in rows if e == ".map"]
+    if maps:
+        print(f"[黄] 产物含 {len(maps)} 个 sourcemap —— 只传监控平台不公开分发(dev-frontend 发布节)")
+    print("判定:", "超预算,阻断" if rc else "预算内")
+    return rc
+
+
+def selftest():
+    import tempfile
+    import random
+    random.seed(7)
+    with tempfile.TemporaryDirectory() as d:
+        os.makedirs(os.path.join(d, "assets"))
+        # 随机内容不可压缩:400KB 十六进制 → gzip 后约 200KB,超 100KB 预算
+        blob = "".join(random.choice("0123456789abcdef") for _ in range(400 * 1024))
+        open(os.path.join(d, "assets", "big.js"), "w").write(blob)
+        open(os.path.join(d, "assets", "ok.css"), "w").write("body{margin:0}")
+        open(os.path.join(d, "app.js.map"), "w").write("{}")
+        assert report(d, 100, 1500, 5) == 1, "big.js 应超预算"
+        assert report(d, 99999, 999999, 5) == 0
+    print("\nselftest ok")
+    return 0
+
+
+if __name__ == "__main__":
+    a = sys.argv[1:]
+    if "--selftest" in a:
+        sys.exit(selftest())
+    if not a:
+        print("用法: bundle-budget.py <dist目录> [--budget-kb 200] [--total-kb 1500] [--top 10] | --selftest")
+        sys.exit(2)
+
+    def opt(name, default):
+        return float(a[a.index(name) + 1]) if name in a else default
+
+    sys.exit(report(a[0], opt("--budget-kb", 200), opt("--total-kb", 1500), int(opt("--top", 10))))

package/skills/dev-go/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: dev-go
+description: Go 技术开发链（模块与项目布局按需生长→错误处理惯例(wrap/Is/As/哨兵)→context 第一参数纪律→goroutine 泄漏三源与防治→channel 模式与关闭纪律→小接口设计→errgroup/singleflight→表驱动测试与 -race→pprof 四件画像→交叉编译与 distroless 发布）。Go 服务/CLI 开发、并发问题排查、内存与 GC 调优时载入。
+version: 1.0.0
+---
+
+# Go 技术开发链
+
+eng-develop 的 Go 孙链。通则承 eng-develop,此处只写 Go 特有判据。
+
+## 模块与项目布局
+
+版本跟官方双版本支持窗;`go mod tidy` 入 CI(依赖漂移即红灯);
+布局**按需生长**:小项目根目录平铺即可,长大再 `cmd/`(多入口)`internal/`(禁外部引用,边界利器)——
+**别一上来照抄大厂 layout**(空目录仪式感=认知税);`pkg/` 只在真有外部使用者时才有意义;
+`go.work` 多模块本地联调用,不提交。
+
+## 错误处理惯例
+
+- 包装带上下文:`fmt.Errorf("read config %s: %w", path, err)`——`%w` 保留链,`errors.Is/As` 判定;
+- 哨兵错误(`var ErrNotFound = errors.New`)用于调用方要分支处理的预期情况;自定义错误类型用于要携带数据的;二者都不需要就直接 wrap 上抛;
+- 错误信息小写、无标点结尾(会被拼进上层消息);
+- **每个 error 三选一只选一次**:处理 / 包装上抛 / 记日志——层层都打日志=同一错误刷五遍(eng-develop 通则落地);
+- `_ = err` 忽略必须注释为何安全(评审红线);panic 只用于程序性错误(init 配置坏),库代码禁 panic 传出。
+
+## context 纪律
+
+第一参数 `ctx context.Context`,不存 struct(存了=生命周期错乱);
+超时逐层收紧(入口 5s,下游调用各自更短);**每个外部调用都带 ctx**(不带=泄漏与堆积之源);
+`context.Value` 只放请求域元数据(traceId/登录态),不放业务参数(隐式传参=不可测试);
+取消要检查:长循环里 `select ctx.Done()` 让路。
+
+## goroutine 泄漏三源与防治
+
+- 三源:无缓冲 channel 发送无人收(接收方提前退出)/`for-select` 漏 `ctx.Done` 分支(永不退出)/HTTP resp.Body 未 Close(连接与 goroutine 挂住);
+- **谁启动谁负责收**:起 goroutine 前先回答"它怎么退出"——答不出就别起;
+- 检测:goroutine 数量常驻监控(斜率>0=泄漏,eng-observability);pprof goroutine 图按创建栈聚类一眼定位;测试用 goleak 兜底;
+- `time.After` 在循环里=定时器堆积,循环内用 `time.NewTimer`+Reset。
+
+## channel 模式速查
+
+无缓冲=同步交接;有缓冲=解耦突发(容量是设计决策不是玄学数);
+**关闭纪律:发送方关,多发送方就别关**(用 ctx 退出或专门的关闭协调者);向已关 channel 发送=panic;
+广播用 `close(ch)`(所有接收者立刻返回零值);
+fan-out/fan-in 用 errgroup 结构化(见下);
+**简单共享状态用 mutex,别硬上 channel**——"通过通信共享内存"是手段不是宗教。
+
+## 并发工具箱
+
+`errgroup.WithContext`:结构化并发默认选择(一错全取消/统一收错/`SetLimit` 限并发——**裸 `go func` 散养是反模式**);
+`singleflight`:缓存击穿防护(同 key 并发只放一个回源,eng-performance 缓存三防);
+`sync.Once` 惰性初始化;`sync.Pool` 高频临时对象复用(GC 压力大再上,先画像);
+数据竞争零容忍:**`-race` CI 必开红灯不合入**(竞争是未定义行为,不是"偶尔数据错")。
+
+## 接口设计
+
+小接口(1–3 方法,io.Reader 是榜样);**接受接口,返回结构体**;
+接口定义在使用方(消费者定义它需要什么),不是实现方预铺;
+别为 mock 而接口化一切(能用真实现就用,eng-quality mock 边界);
+泛型判据:容器/工具函数用,业务逻辑少用(可读性优先)。
+
+## 测试
+
+表驱动+子测试(`t.Run` 命名用例,失败定位准);`t.Parallel` 提速(注意共享状态);
+基准 `b.ReportAllocs()`(分配次数比纳秒稳定);
+golden file 判据(大输出对比,`-update` 刷新);
+集成测试真依赖容器化(eng-quality);httptest 内建好用。
+
+## 性能画像与运行时
+
+pprof 四件:cpu(火焰图)/heap(inuse vs alloc 分清:常驻看 inuse,GC 压力看 alloc)/goroutine/block+mutex(锁竞争);
+**生产常开 pprof HTTP 端点(仅内网可达)**——事故现场随手可采;
+逃逸分析 `-gcflags=-m` 查热点分配;高分配点:string↔[]byte 转换、闭包捕获、interface 装箱;
+容器内存对齐:`GOMEMLIMIT` 设为容器 limit 的 ~90%(默认无上限=OOMKilled 常客);`GOMAXPROCS` 与 CPU limit 对齐(automaxprocs 思路)。
+
+## 构建与发布
+
+交叉编译矩阵:`CGO_ENABLED=0` 纯静态(判据:用了 cgo 依赖则另论);
+`-ldflags "-X main.version=..."` 注入版本(排障先问版本);
+镜像 distroless/alpine 或 scratch(+CA 证书与时区数据按需);
+`govulncheck` 入 CI(只报可达路径的漏洞,信噪比高,eng-security SCA)。
+
+**作业包**:`scripts/go-triage.sh`(pprof 端点收割:goroutine 双采样看增长、创建点聚类找泄漏、heap 概况落盘)。
+
+## 使用纪律
+
+`-race` 与 `go vet` 红灯不合入;goroutine 数与内存常驻监控;
+每次泄漏/竞争事故回写三源清单;性能优化先 pprof 后动手(eng-performance 无画像不优化)。

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

@@ -0,0 +1,54 @@
+#!/bin/sh
+# Go 服务 pprof 一键采集（dev-go"生产常开 pprof 端点"的收割器）。只读 HTTP GET,curl/wget 双兜底。
+# 用法: sh go-triage.sh <host:port> [-o 目录]     # 目标需已暴露 net/http/pprof(仅内网!)
+# 采集: goroutine 概况×2(隔 5 秒看增长=泄漏侦测)/heap 概况/创建点 TOP/阻塞概况;落盘供深入分析。
+HP="$1"; shift
+[ -z "$HP" ] && { echo "用法: go-triage.sh <host:port> [-o 目录]"; exit 2; }
+OUT="/tmp"
+[ "$1" = "-o" ] && OUT="$2"
+have() { command -v "$1" >/dev/null 2>&1; }
+fetch() { # fetch <path> <outfile>
+  if have curl; then curl -s -m 20 "http://$HP$1" -o "$2" 2>/dev/null
+  elif have wget; then wget -q -T 20 -O "$2" "http://$HP$1" 2>/dev/null
+  else echo "[缺工具] 无 curl/wget"; exit 3; fi
+}
+TS=$(date '+%Y%m%d_%H%M%S')
+D="$OUT/go_triage_${TS}"
+mkdir -p "$D" || exit 2
+
+fetch "/debug/pprof/goroutine?debug=1" "$D/goroutine_1.txt"
+[ -s "$D/goroutine_1.txt" ] || { echo "[不可达] http://$HP/debug/pprof/ 拿不到(端点没开?网络?——pprof 端点仅内网暴露,dev-go)"; exit 4; }
+
+G1=$(head -1 "$D/goroutine_1.txt" | grep -oE 'total [0-9]+' | awk '{print $2}')
+echo "==== Go pprof 采集 $HP → $D ===="
+echo "goroutine 总数(第 1 次): ${G1:-?}"
+sleep 5
+fetch "/debug/pprof/goroutine?debug=1" "$D/goroutine_2.txt"
+G2=$(head -1 "$D/goroutine_2.txt" | grep -oE 'total [0-9]+' | awk '{print $2}')
+echo "goroutine 总数(5 秒后): ${G2:-?}"
+if [ -n "$G1" ] && [ -n "$G2" ]; then
+  [ "$G2" -gt $((G1 + 50)) ] 2>/dev/null && echo "[红] 5 秒净增 $((G2 - G1)) —— 泄漏进行时:看下方创建点聚类(泄漏三源,dev-go)"
+  [ "$G2" -gt 5000 ] 2>/dev/null && echo "[黄] goroutine ${G2} 数量偏高 —— 无界并发/堆积嫌疑"
+fi
+echo ""
+echo "---- goroutine 创建点 TOP(按数量聚类) ----"
+grep -E '^[0-9]+ @' "$D/goroutine_2.txt" | sort -rn | head -8 | sed 's/^/  /'
+echo "  (数量大的创建点=嫌疑人;配栈细看: go tool pprof http://$HP/debug/pprof/goroutine)"
+
+fetch "/debug/pprof/heap?debug=1" "$D/heap.txt"
+if [ -s "$D/heap.txt" ]; then
+  echo ""
+  echo "---- heap 概况 ----"
+  grep -E '^# (HeapAlloc|HeapInuse|HeapSys|NumGC|PauseTotalNs)' "$D/heap.txt" | sed 's/^# /  /'
+  echo "  (常驻看 inuse,GC 压力看 alloc —— 深入: go tool pprof -inuse_space/-alloc_space)"
+fi
+
+fetch "/debug/pprof/mutex?debug=1" "$D/mutex.txt"
+fetch "/debug/pprof/block?debug=1" "$D/block.txt"
+echo ""
+echo "(mutex/block 概况已落盘;默认采样率为 0 时为空——需 runtime.SetMutexProfileFraction 开启)"
+echo ""
+echo "==== 完成: $D ===="
+echo "下一步: CPU 30 秒画像 go tool pprof http://$HP/debug/pprof/profile?seconds=30;"
+echo "容器内存对齐查 GOMEMLIMIT(dev-go 运行时节);泄漏对照创建点与 ctx.Done 三源。"
+exit 0

package/skills/dev-harmony/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: dev-harmony
+description: 鸿蒙开发链（立项判据(纯血鸿蒙无 AOSP 兼容=真开发不是打包)→ArkTS 语言约束与 TS 迁移→声明式 ArkUI 状态管理判据→Stage 模型与 HAP/HSP/HAR 包结构→一次开发多端部署的真伪需求→双端并存代码复用边界→性能(冷启动/LazyForEach)→华为生态对接与上架审核）。eng-develop 的鸿蒙孙链:立项评估鸿蒙版、ArkTS 迁移、双端并存架构、上架华为市场时载入。API 版本演进快,细节以当日官方文档为准。
+version: 1.0.0
+---
+
+# 鸿蒙开发链
+
+eng-develop 的鸿蒙孙链(HarmonyOS NEXT/ArkTS 系)。与 dev-mobile(Android/iOS)并列,跨端框架的鸿蒙适配走 dev-cross-platform;
+生态与 API 演进快,**版本细节以当日官方文档为准**,本链管工程判据与坑位。
+
+## 立项判据（先想清楚再动手）
+
+**纯血鸿蒙(NEXT)无 AOSP 兼容层=Android APK 不能跑**——鸿蒙版是一次真开发,不是打包换皮;
+上不上的判据:目标用户的鸿蒙设备占比(数据说话,dev-mobile 版本支持窗同法)/华为渠道与合作诉求/政企客户指定(信创场景 env-xinchuang 常伴随);
+形态三选:原生 ArkTS(体验最优,成本一整条端)/跨端框架适配(Flutter/RN 等对鸿蒙的支持成熟度**逐项评估**,dev-cross-platform 记分卡加一列)/仅元服务或轻量形态(入口级存在,成本低)——
+按"必须原生能力清单"与预算选(dev-cross-platform 桥接成本判据同构)。
+
+## ArkTS 语言要点（TS 老手的再学习清单）
+
+- ArkTS=TS 子集+**静态化约束**:禁 any/unknown 随意用、禁运行时改对象结构(动态加属性)、部分反射与函数式技巧受限——**存量 TS 逻辑迁移要过约束检查**,重度动态代码(动态 schema/元编程)要改写;
+- 声明式 UI(ArkUI):装饰器驱动,组件=struct+build();
+- 状态管理判据(高频翻车区):@State(组件内)/@Prop(父传子单向)/@Link(双向,慎用)/@Observed+@ObjectLink(对象嵌套观察)——**嵌套对象改属性不刷新=没用对观察装饰器**,状态设计先画数据流(dev-frontend 状态分层同构);
+- 并发:Worker/TaskPool 判据(TaskPool 默认,短任务;主线程红线同 dev-mobile:IO 与重计算下线程)。
+
+## 工程结构
+
+- **Stage 模型**:UIAbility 生命周期(与页面路由分层);进程与窗口心智(一多形态下窗口适配);
+- 包结构判据:HAP(entry 主入口/feature 特性包)/HSP(动态共享包,进程内共享)/HAR(静态共享库,编译期复用)——**公共组件与工具沉 HAR,大特性按需 HSP**(包体积与按需加载,dev-mobile 包体积纪律);
+- 一次开发多端部署(一多):自适应布局+响应式断点——**先问产品"哪些端真有用户"**(手机先行,平板/折叠按真实需求,别为演示做全端,dev-cross-platform 端矩阵纪律)。
+
+## 双端并存策略（Android/iOS/鸿蒙三端的现实）
+
+- 代码复用边界:**纯业务逻辑 TS 可共享但要过 ArkTS 约束**(共享层写"约束友好"的 TS:禁动态技巧,提前 lint);UI 层不复用(声明式范式不同);
+- 三端架构对齐:分层与接口对齐(dev-mobile MVVM 同构:UseCase/Repository 共享设计,各端实现),**需求文档一份三端注解**(差异显式标注,eng-requirements);
+- 发布节奏:三端版本对齐策略(功能开关按端控制,eng-release 开关矩阵);服务端兼容窗口覆盖三端(api-design);
+- 团队配置:鸿蒙侧初期与前端/客户端混编(ArkTS 对 TS 背景友好),坑清单共享(knowledge-sop)。
+
+## 性能要点
+
+冷启动:UIAbility 启动链路瘦身(延迟初始化,dev-mobile SDK 懒加载同法);
+长列表 **LazyForEach**+组件复用(cachedCount 调优)——ForEach 全量渲染是卡顿第一来源;
+状态刷新范围控制(状态粒度过粗=大面积重绘;配合 @Observed 精准更新);
+包体积:HAR/HSP 拆分+资源按需;启动与帧率基线进发布对照(dev-mobile 三基线同拍,qa-mobile-automation 采集)。
+
+## 生态对接与上架
+
+华为生态:账号/推送/支付/地图等按需接入(权限与隐私声明同步更新);
+权限模型:用户可随时撤销(运行时检查不可省,dev-mobile 权限降级路径同构);
+**上架审核**:华为市场审核要点与 dev-mobile 合规同构(隐私弹窗时序/权限用途/SDK 清单)——store-compliance-checklist 加鸿蒙列使用;
+元服务判据:轻量入口场景(卡片/免安装)的获客价值评估。
+
+## 测试与排障
+
+真机优先(模拟器覆盖有限);云真机矩阵加鸿蒙档(qa-mobile-automation 设备矩阵);
+DevEco 调试与 profiler(启动/帧率/内存);hilog 日志规范(eng-observability 分级纪律平移);
+自动化:官方测试框架跑关键旅程(≤10 条纪律同 qa-mobile-automation)。
+
+## 使用纪律
+
+立项先出鸿蒙设备占比数据与形态决策(ADR 留档,eng-architecture);共享层 TS 过 ArkTS 约束 lint;
+三端功能差异显式登记;每个适配坑回写坑清单——**鸿蒙是新端不是新皮肤,按一条完整端投入与验收**。
+
+**作业包**:`references/harmony-checklist.md`(立项评估卡/ArkTS 迁移约束速查/包结构与状态管理判据卡/上架自查)。

package/skills/dev-harmony/references/harmony-checklist.md

@@ -0,0 +1,40 @@
+# 鸿蒙立项与开发自查（dev-harmony 落笔件;API 细节以当日官方文档为准）
+
+## 1. 立项评估卡
+
+| 项 | 内容 |
+|---|---|
+| 鸿蒙设备占比 | 目标用户中 __%(数据来源:__)——数据说话,不为演示立项 |
+| 商务/渠道因素 | 华为合作__/政企指定__(信创伴随? env-xinchuang) |
+| 形态决策 | □原生 ArkTS(一条完整端投入) □跨端框架适配(支持度评估:__) □元服务/轻量 |
+| 必须原生能力 | 推送/支付/账号/__(桥接或原生成本:__) |
+| 团队与预算 | 人力 __;ADR 编号:__(eng-architecture 留档) |
+
+## 2. ArkTS 迁移约束速查(存量 TS 逻辑迁移前扫)
+
+- [ ] 无 any/unknown 滥用(类型补全)  - [ ] 无运行时改对象结构(动态加属性/delete 属性)
+- [ ] 无重度反射/元编程(Proxy/动态属性名遍历改写)  - [ ] 无非常规函数式技巧(约束清单过 lint)
+- [ ] 共享层 TS 按"约束友好"风格重构并单独 lint(三端共享的前提)
+- [ ] 动态 schema 场景(表单引擎类)改造方案:__(重灾区,提前设计)
+
+## 3. 工程判据卡
+
+- 包结构:公共组件/工具 → HAR;大特性按需加载 → HSP;入口 → HAP(entry)——体积与复用判据
+- 状态管理速查:组件内 @State/父子单向 @Prop/双向慎用 @Link/**嵌套对象要 @Observed+@ObjectLink**(改属性不刷新=第一坑)
+- 一多(一次开发多端):真实端需求确认(手机先行;平板/折叠有用户数据才做:__)
+- 并发:重计算/IO 走 TaskPool;主线程红线同 dev-mobile
+- 长列表:LazyForEach+cachedCount(ForEach 全量渲染=卡顿第一来源)
+
+## 4. 三端并存检查
+
+- [ ] 分层对齐:UseCase/Repository 设计三端一致,UI 各端实现
+- [ ] 需求文档三端差异显式标注;功能开关按端可控(eng-release)
+- [ ] 服务端兼容窗口覆盖三端版本(api-design)
+- [ ] 坑清单共享机制:__(knowledge-sop)
+
+## 5. 上架与发布自查
+
+- [ ] 隐私弹窗时序(同意后才初始化采集 SDK——store-compliance 同构)
+- [ ] 权限用途声明齐全且用户撤销路径已处理(运行时检查)
+- [ ] 三基线记录:冷启动 __ /包体积 __ /崩溃率 __(qa-mobile-automation 采集)
+- [ ] 云真机矩阵已加鸿蒙档;关键旅程自动化 ≤10 条

package/skills/dev-java/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dev-java
+description: Java 技术开发链（JDK LTS 版本策略→Maven/Gradle 依赖治理 BOM 与冲突仲裁→Spring Boot 工程分层→事务失效八景→线程池参数公式与虚拟线程判据→JVM 内存 GC 调优→JUnit5/Testcontainers→arthas/JFR 排障→常见坑 TOP→镜像分层发布）。Java 后端开发、依赖冲突、线上 JVM 问题、评审基线时载入。
+version: 1.0.0
+---
+
+# Java 技术开发链
+
+eng-develop 的 Java 孙链。通则(命名/日志/DoD)承 eng-develop,此处只写 Java 特有判据。
+
+## JDK 版本策略
+
+- LTS 只认 8/11/17/21;**新项目 17 起步**;21 的虚拟线程见并发节判据;
+- 升级速查:8→11(模块化影响、内部 API 移除、HttpClient)/→17(record、sealed、switch 模式匹配、强封装 add-opens 清单)/→21(虚拟线程、分代 ZGC);
+- 升级纪律:先跑依赖兼容清单(反射与字节码库最易碎:cglib/javassist/agent 类),灰度一个服务蹚坑再铺开(dependency-upgrade 流程)。
+
+## 依赖治理（Maven/Gradle）
+
+- **BOM 统一版本**:Spring Boot BOM/自建平台 BOM 管版本号,业务 pom 不写版本(写了=漂移入口);
+- 冲突仲裁:`dependency:tree` 定位;Maven"就近优先"的坑:间接依赖版本被意外压低,显式管理胜于祈祷;
+- scope 纪律:provided/test 别打进部署包;optional 慎用;**禁 SNAPSHOT 出现在发布制品**(门禁);
+- 依赖收敛检查入 CI(enforcer 类插件:版本冲突/重复类即红灯)。
+
+## 工程结构与 Spring 要点
+
+- 分层纪律:controller 薄(参数校验+编排)/service 持事务边界/repository 只做数据访问;DTO 与 Entity 分离,**Entity 不出 service 层**(序列化惰性加载炸弹+暴露表结构);
+- 配置:@ConfigurationProperties 强类型优先 @Value 散取;配置类集中可检索;
+- **事务失效八景**(评审必查):同类自调用(代理未生效)/方法非 public/异常被 catch 吞掉/抛受检异常未配 rollbackFor/传播设置错(REQUIRES_NEW 嵌套误用)/多数据源事务管理器错配/在非 Spring 管理实例上调用/事务内起新线程(事务不跨线程);
+- Bean 循环依赖=分层坏味道,重构优于 @Lazy 遮羞;@Async 与 @Transactional 同方法=代理边界坑(拆开)。
+
+## 并发
+
+- 线程池手建,**禁 Executors 快捷工厂**(无界队列/无限线程=OOM 双胞胎);参数公式起点:CPU 密集=核数+1;IO 密集=核数×(1+等待时间/计算时间);队列有界+拒绝策略显式选(CallerRuns 背压/Abort 快败),**池指标要上监控**(活跃/队列深度,eng-observability);
+- ThreadLocal 必 finally remove(池化线程复用=脏数据窜请求);InheritableThreadLocal 在池里失效(用装饰器传递);
+- CompletableFuture:自定义线程池传入(默认 ForkJoin 公共池被塞满=全应用卡);异常用 handle/exceptionally 接住(裸 join 吞栈);
+- **虚拟线程判据(21+)**:IO 密集高并发受益大;三查再上:synchronized 长临界区钉住载体线程(改 ReentrantLock)/池化库兼容性/ThreadLocal 大对象泛滥。
+
+## JVM 内存与 GC
+
+- 容器时代三件套:`-Xms=-Xmx`(防抖动)+`MaxRAMPercentage` 与容器 limit 对齐+**`-XX:+HeapDumpOnOutOfMemoryError` 必开**(现场比重启贵重);
+- GC 判据:G1 默认;大堆(>16G)低延迟诉求评估 ZGC;吞吐批处理可 Parallel;**调优先看 GC 日志再动参数**(日志常开无罪);
+- OOM 四类定位:heap(dump 上 MAT 看支配树)/metaspace(类加载泄漏:热部署/动态代理滥用)/direct(NIO/Netty 堆外,-XX:MaxDirectMemorySize)/unable to create thread(线程数爆炸,先 jstack 数线程)。
+
+## 常见坑 TOP（评审自查单）
+
+BigDecimal:禁 double 构造(精度已丢)、比较用 compareTo(equals 连 scale 一起比);
+时间:存储与计算用 Instant/UTC,展示才转时区;`YYYY` 是周年(跨年周必炸),要 `yyyy`;SimpleDateFormat 线程不安全(用 DateTimeFormatter);
+空安全:返回空集合不返回 null;Optional 用在返回值不用在字段/参数;
+equals/hashCode 契约:进 HashMap/Set 的键必须不可变(可变键改字段=元素失踪);
+Arrays.asList 定长、List.of 不可变(add=UnsupportedOperation);
+Stream:惰性求值(无终结操作不执行)、禁副作用(peek 里写库=埋雷)、parallelStream 慎用(公共池+线程安全双坑);
+String 拼接进循环用 StringBuilder;正则预编译(Pattern.compile 提静态)。
+
+## 测试（JUnit5 体系）
+
+JUnit5+AssertJ(断言可读)+Mockito(mock 边界纪律见 eng-quality:只 mock 我不拥有的);
+切片测试提速:@WebMvcTest/@DataJpaTest 只起所需上下文,全量 @SpringBootTest 留给集成层;
+真库集成用 Testcontainers(H2 方言差异会漏 bug);@ParameterizedTest 铺边界(eng-quality 边界三点法)。
+
+## 排障画像（arthas/JFR 五招）
+
+CPU 高:`thread -n 3` 直捞热点栈;慢调用:`trace 类 方法` 逐层耗时;
+参数疑云:`watch` 打入参返回值(不重启不加日志);"改了没生效":`jad` 反编译核对线上字节码;
+内存:`heapdump` + MAT;**JFR 生产常开**(低开销飞行记录,事后回放胜过事前猜测);
+线上三件必留现场:jstack/jmap(或 dump)/GC 日志,先保全再重启(eng-ops 证据保全同拍)。
+
+## 构建与发布
+
+多阶段 Dockerfile;**分层镜像**:依赖层与应用层分离(Spring Boot layered jar),代码改动只重推最上层;
+jlink 裁剪 JRE 判据(体积敏感才做,维护成本先认);JVM 参数进启动脚本入库(不散落在平台配置里)。
+
+**作业包**:`scripts/jvm-triage.sh`(线程栈×2/状态统计/死锁检测/GC 概况/CPU 最高线程定位,打包保全;--histo 显式开(有停顿))。
+
+## 使用纪律
+
+升级依赖必跑全量测试+依赖树 diff(dependency-upgrade);线上问题先保全现场再恢复;
+池类资源(线程池/连接池)一律有界+有监控;每次线上 JVM 事故回写:参数基线与坑清单。

package/skills/dev-java/scripts/jvm-triage.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# JVM 一键排障采集（dev-java 排障画像的可执行版）。默认只读安全命令;jmap -histo 有停顿代价,须显式 --histo。
+# 用法: sh jvm-triage.sh <PID> [-o 目录] [--histo]
+# 采集: 线程栈×2(隔 3 秒,对比看谁一直在跑)/线程状态统计/死锁检测/GC 概况(jstat×5)/
+#       CPU 最高线程与栈定位(Linux)/进程基础信息。JDK 工具缺失(纯 JRE)自动降级并提示 arthas 路线。
+PID="$1"; shift
+[ -z "$PID" ] && { echo "用法: jvm-triage.sh <PID> [-o 目录] [--histo]"; exit 2; }
+OUT=""; HISTO=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -o) OUT="$2"; shift 2;;
+    --histo) HISTO=1; shift;;
+    *) shift;;
+  esac
+done
+kill -0 "$PID" 2>/dev/null || { echo "[错误] 进程 $PID 不存在或无权限"; exit 2; }
+have() { command -v "$1" >/dev/null 2>&1; }
+TS=$(date '+%Y%m%d_%H%M%S')
+D="${OUT:-/tmp}/jvm_triage_${PID}_$TS"
+mkdir -p "$D" || exit 2
+
+echo "==== JVM 排障采集 PID=$PID → $D ===="
+ps -o pid,user,etime,rss,args -p "$PID" 2>/dev/null | tee "$D/process.txt" | head -2
+
+if have jstack; then
+  echo "---- 线程栈×2(隔 3 秒) ----"
+  jstack "$PID" > "$D/jstack_1.txt" 2>&1
+  sleep 3
+  jstack "$PID" > "$D/jstack_2.txt" 2>&1
+  echo "线程状态统计(第 2 份):"
+  grep -oE 'java\.lang\.Thread\.State: [A-Z_]+' "$D/jstack_2.txt" | sort | uniq -c | sort -rn | sed 's/^/  /'
+  BLOCKED=$(grep -c 'State: BLOCKED' "$D/jstack_2.txt")
+  [ "$BLOCKED" -gt 10 ] 2>/dev/null && echo "  [红] BLOCKED $BLOCKED 个 —— 锁竞争:两份栈里找同一把锁(waiting to lock <0x...>)"
+  if grep -q 'Found.*deadlock' "$D/jstack_2.txt"; then
+    echo "  [红] 检测到死锁!"
+    grep -A 20 'Found.*deadlock' "$D/jstack_2.txt" | head -25 | sed 's/^/    /'
+  fi
+  # Linux: CPU 最高线程定位(tid→nid 十六进制匹配栈)
+  if [ -d "/proc/$PID/task" ] && have awk; then
+    echo "CPU 最高线程(tid→栈):"
+    ps -mo tid,pcpu -p "$PID" 2>/dev/null | sort -rk2 | awk 'NR<=4 && $1!="-" && $1+0>0 {print $1, $2}' | while read -r tid cpu; do
+      nid=$(printf 'nid=0x%x' "$tid")
+      name=$(grep "$nid" "$D/jstack_2.txt" | head -1 | cut -c1-90)
+      echo "  tid=$tid cpu=${cpu}% $name"
+    done
+  fi
+else
+  echo "[降级] 无 jstack(纯 JRE?) —— kill -3 $PID 可让栈打进应用 stdout;或上 arthas: thread -n 3(dev-java 五招)"
+  kill -3 "$PID" 2>/dev/null && echo "  已发 SIGQUIT,栈见应用标准输出/日志"
+fi
+
+if have jstat; then
+  echo "---- GC 概况(1s×5,看 O 区与 FGC 增速) ----"
+  jstat -gcutil "$PID" 1000 5 2>/dev/null | tee "$D/jstat.txt" | sed 's/^/  /'
+  FGC1=$(sed -n '2p' "$D/jstat.txt" | awk '{print $(NF-3)}')
+  FGC2=$(tail -1 "$D/jstat.txt" | awk '{print $(NF-3)}')
+  [ -n "$FGC1" ] && [ -n "$FGC2" ] && [ "$FGC2" != "$FGC1" ] 2>/dev/null && \
+    echo "  [红] 5 秒内 Full GC 从 $FGC1 → $FGC2 —— 内存告急:--histo 看对象分布,dump 上 MAT"
+else
+  echo "[降级] 无 jstat —— GC 日志兜底(GC 日志常开无罪,dev-java);arthas: dashboard"
+fi
+
+if [ "$HISTO" = "1" ]; then
+  if have jmap; then
+    echo "---- 对象直方图 TOP30(jmap -histo,有短暂停顿,已确认执行) ----"
+    jmap -histo "$PID" 2>/dev/null | head -35 | tee "$D/histo.txt" | tail -32 | sed 's/^/  /'
+  else
+    echo "[降级] 无 jmap —— arthas: heapdump 或 memory 命令"
+  fi
+else
+  echo "(对象直方图未采集;确认可接受短暂停顿后加 --histo;OOM 现场优先 -XX:+HeapDumpOnOutOfMemoryError 的 dump)"
+fi
+
+# 容器内存对齐提示
+if [ -f /.dockerenv ] || grep -qsE 'kubepods|docker' /proc/1/cgroup 2>/dev/null; then
+  for f in /sys/fs/cgroup/memory.max /sys/fs/cgroup/memory/memory.limit_in_bytes; do
+    [ -r "$f" ] && echo "容器内存上限: $(cat "$f")(与 -Xmx/MaxRAMPercentage 对齐否?dev-java 容器三件套)"
+  done
+fi
+
+( cd "$(dirname "$D")" && tar czf "$(basename "$D").tar.gz" "$(basename "$D")" 2>/dev/null )
+echo "==== 采集完成: ${D}.tar.gz(先保全后分析,eng-ops) ===="
+echo "下一步: 栈对比看热点;BLOCKED 找锁持有者;GC 异常配 --histo 与 heap dump;深入用 arthas 五招。"
+exit 0