@huicai/cli 2026.714.0 → 2026.721.0

package/skills/qa-api-automation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: qa-api-automation
+description: 接口自动化测试链（接口层 ROI 定位→单接口用例设计(边界/鉴权/幂等)与场景链串联→断言四层(状态码/schema/关键值/副作用)→三层封装组织(client/业务/用例)→造数 API 与数据自清理→CI 集成与失败三分类→脆弱率治理→契约 diff 联动）。eng-quality 的接口自动化孙链:搭接口自动化框架、回归全靠手点、用例老误报、接口改了测试不知道时载入。
+version: 1.0.0
+---
+
+# 接口自动化测试链
+
+eng-quality 的接口自动化孙链。定位:接口层是自动化 **ROI 最高**的一层——比单测覆盖广、比 UI 快十倍稳十倍;
+金字塔里它是腰(eng-quality 配比),腰有力,UI 层才能瘦。
+
+## 用例设计两级
+
+- **单接口级**(每个接口标配):正向主路径/参数边界(必填缺失/类型错/超长/特殊字符,eng-quality 六法取材)/
+  **鉴权四问**(无 token?过期 token?别人的 token 访问我的资源——水平越权?低角色访问高接口——垂直越权?eng-security 越权双查的自动化落点)/
+  幂等验证(同请求重放,该幂等的结果不变,该拦的拦重复)/异常路径(下游挂时的错误码与错误结构);
+- **场景链级**(业务流串联):下单→支付→查订单→退款,上一步产出(id/状态)=下一步输入——
+  单接口全绿但流程断的 bug 全靠这层;场景链选取=核心业务旅程(与 E2E 分工:接口链验数据与状态流转,UI E2E 验界面交互,qa-ui-automation)。
+
+## 断言四层（只断状态码=假绿之王）
+
+1. 状态码与响应时间上限(顺手的性能哨兵,eng-performance 基线的接口层);
+2. **schema 校验**:响应结构对契约验(字段/类型/必填,api-design 契约同源——契约即断言,自动生成校验器);
+3. 关键业务值:金额/状态/数量精确断言(全字段快照对比脆,关键字段点断稳——**断言"变化的部分"**);
+4. **副作用验证**:写接口查落库结果(直查 DB 或查询接口回读)/该发的消息发了没(测试消费者)——
+   响应 200 但没落库的 bug,只有这层抓得住。
+
+## 分层封装组织（禁 case 里裸写 HTTP）
+
+client 层(封 HTTP:环境地址/鉴权注入/公共头/重试)→ 业务层(语义方法:createOrder(参数)→返回业务对象,内嵌基础断言)→
+用例层(只写业务语言:造单→支付→断言状态);
+接口变更只改 client/业务层一处(用例层稳如老狗)——**用例里出现 URL 字符串=组织烂了的信号**;
+公共断言函数库(分页结构/错误结构/时间格式)统一维护。
+
+## 测试数据管理（环境无关是目标）
+
+**造数 API 优先**:测试专用造数接口(或复用业务接口组合)按需造,禁依赖环境预置数据("那个环境里有条订单"=换环境全崩,eng-quality 数据独立);
+自清理:用例造的数据用例负责清(teardown 或标记回收例程);清不掉的用随机唯一值隔离(手机号/单号加测试段前缀);
+敏感环境纪律:自动化账号独立+权限最小;**生产环境只跑只读冒烟**(写操作的自动化禁碰生产,eng-ops 红线);
+时间型数据(过期/账期)用造数 API 指定时间,不真等(eng-quality 固定时钟)。
+
+## CI 集成与失败三分类
+
+分层进流水线(cicd-pipeline 承接编排):P0 冒烟(分钟级,合入门禁)/全量回归(每日+发版前,eng-quality 分级);
+**失败三分类统计**(治理的抓手):产品缺陷(提单,自动化的价值时刻)/用例脆弱(数据依赖/时序假设/断言过严)/环境问题(服务没起/数据库挂)——
+三类分开出周报:缺陷率是产出,**脆弱率>10% 停下修用例**(不修=狼来了,全员免疫红灯),环境问题高发=治环境不治用例;
+失败自动留证:请求响应全文+关联 traceId(eng-observability 贯穿,一键从失败用例跳后端日志)。
+
+## 契约联动（接口改了,测试要先知道）
+
+契约 diff 例程(eng-automation):api-design 契约变更→自动列出受影响用例清单→提醒同步(新增字段补断言/删字段改用例);
+消费者驱动契约测试与接口自动化分工:契约测保"格式约定不破"(合入时拦),接口自动化保"业务行为正确"(每日回归)——两层都要,互不替代(eng-quality 契约节);
+Mock 边界:第三方依赖 mock(eng-integration 的沙箱不稳定,录制回放兜底),**自有服务尽量真调**(mock 自己=测了个寂寞,eng-quality mock 纪律)。
+
+## 度量与治理
+
+有效率(发现真缺陷数/千次运行)、脆弱率、覆盖率口径用**接口清单覆盖**(多少接口有自动化)不用代码行覆盖;
+运行时长预算(全量>30min 治理:并行分片/裁冗余用例);
+用例也要还债:连续半年没拦过任何东西的用例季度评审(裁撤或加强——**用例数量不是 KPI,拦截力才是**,eng-quality 反唯覆盖率同理)。
+
+**作业包**:`references/three-layer-skeleton.md`(client/业务/用例三层封装代码骨架+越权用例示例+纪律对照,任何栈同构照搬)。
+
+## 使用纪律
+
+新接口上线带自动化(DoD 项,eng-develop);接口变更同步用例(契约 diff 兜底);
+失败三分类周清;越权用例是安全底线必备(每个资源类接口至少一条水平越权用例);
+**接口自动化的目标不是"跑起来很壮观",是发版前那句"回归全绿,放心发"**。

package/skills/qa-api-automation/references/three-layer-skeleton.md

@@ -0,0 +1,61 @@
+# 接口自动化三层封装骨架（qa-api-automation 落笔件:pytest 风格示意,任何栈同构照搬）
+
+## 目录结构
+
+```
+api-tests/
+├── client/base.py        # L1: HTTP 封装(环境/鉴权/公共断言)——URL 只许出现在这层
+├── services/order.py     # L2: 业务语义方法(内嵌基础断言)
+├── cases/test_order.py   # L3: 用例只写业务语言
+├── data/factory.py       # 造数 API 封装(环境无关)
+└── conftest.py           # 账号/环境 fixture
+```
+
+## L1 client/base.py(要点示意)
+
+```python
+class ApiClient:
+    def __init__(self, env):           # 环境地址与账号从配置来,禁硬编码
+        self.base, self.token = ENV[env]["base"], login(env)
+    def post(self, path, json, expect=200):
+        r = requests.post(self.base + path, json=json,
+                          headers={"Authorization": self.token}, timeout=10)
+        assert r.status_code == expect, f"{path} {r.status_code}: {r.text[:200]}"
+        assert r.elapsed.total_seconds() < 3      # 顺手的性能哨兵
+        return r.json()
+```
+
+## L2 services/order.py
+
+```python
+class OrderService:
+    def create(self, sku, qty=1):
+        body = self.c.post("/orders", {"sku": sku, "qty": qty})
+        validate_schema(body, "order")            # 契约即断言(api-design 同源生成)
+        return body["data"]                        # 返回业务对象供链式使用
+    def assert_persisted(self, order_id):          # 副作用验证:200≠落库
+        row = db.fetch("select status from orders where id=%s", order_id)
+        assert row, f"订单 {order_id} 未落库"
+```
+
+## L3 cases/test_order.py(用例读起来像业务)
+
+```python
+def test_下单_支付_状态流转(order_svc, pay_svc):
+    order = order_svc.create(sku=造数.商品())      # 造数 API,不依赖环境预置
+    pay_svc.pay(order["id"])
+    assert order_svc.get(order["id"])["status"] == "PAID"
+    order_svc.assert_persisted(order["id"])
+
+def test_越权_他人订单不可见(order_svc, 他人token):  # 每资源类接口至少一条(安全底线)
+    order = order_svc.create(sku=造数.商品())
+    resp = client_as(他人token).get(f"/orders/{order['id']}", expect=403)
+```
+
+## 纪律对照
+
+- [ ] 用例层零 URL/零裸 http;接口变更只改 L1/L2 一处
+- [ ] 断言四层齐:状态码+schema+关键值+副作用
+- [ ] 数据自造自清(teardown/标记回收);随机唯一值隔离
+- [ ] 失败留证:请求响应全文+traceId 进报告
+- [ ] 失败三分类周报:产品缺陷/用例脆弱(>10% 停下修)/环境问题

package/skills/qa-mobile-automation/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: qa-mobile-automation
+description: 移动端测试自动化链（ROI 更克制≤10 条旅程→框架判据(双端原生 Espresso/XCUITest vs Appium 跨端)→设备策略(云真机矩阵按用户分布/模拟器 vs 真机判据)→稳定性专项(系统弹窗 watcher/厂商 ROM 差异/弱网注入)→accessibility id 定位→崩溃回归与性能基线自动化→兼容性云测三步曲→与 qa-ui-automation 共通纪律）。eng-quality 与 dev-mobile 的移动测试孙链:搭移动自动化、云真机选型、用例老被弹窗打断、机型兼容回归时载入。
+version: 1.0.0
+---
+
+# 移动端测试自动化链
+
+eng-quality 与 dev-mobile 共同的孙链。移动 UI 自动化=UI 自动化(qa-ui-automation)的困难模式:
+设备碎片×厂商 ROM×系统弹窗×网络波动——**复杂环境是常态而非异常**,纪律要再收紧一档。
+
+## ROI 判据（比 Web 更克制）
+
+关键旅程 **≤10 条**(登录/核心任务/支付,比 Web 的 15 条更狠——每条用例的维护成本是 Web 的 2–3 倍);
+下沉优先级:能接口层测的绝不上 UI(qa-api-automation),能 ViewModel 单测的绝不上设备(dev-mobile 分层红利)——**设备上只测"必须在设备上才能发现的"**:UI 组装/系统交互/真机行为;
+新功能先手工+录屏,冒烟稳定两个版本再自动化(qa-ui-automation 同则加严)。
+
+## 框架判据
+
+| 方案 | 强项 | 判据 |
+|---|---|---|
+| 双端原生(Espresso/XCUITest) | 快、稳、与构建集成好 | **默认推荐**:团队双端各自维护,速度与稳定优先 |
+| Appium 系 | 跨端一套用例/语言自由 | 跨端复用诉求强+接受慢与脆;混合应用/H5 页面多 |
+| 混合 | 原生框架跑主力+Appium 跑跨端冒烟 | 大团队常态 |
+
+判据主轴:**稳定性>复用性**(跨端复用省的编写时间,会加倍还在 flaky 治理上);
+uni-app/Flutter 等跨端应用(dev-cross-platform):优先框架自带测试能力,真机层留冒烟。
+
+## 设备策略
+
+- **云真机矩阵按用户分布定**(dev-mobile 数据化决策同源):TOP 机型覆盖 80% 用户+最低支持版本+**问题机型黑名单转灰名单**(投诉高发机型必进矩阵);季度按分布数据刷新;
+- 模拟器 vs 真机判据:模拟器跑 PR 级快反馈(便宜快);**真机必测清单**:传感器/相机/推送/性能数据/厂商 ROM 行为(权限弹窗与后台限制各家不同)/弱网表现——模拟器全绿≠真机能用;
+- 自有设备架 vs 云真机:量小用云(免维护),高频回归自有小机架+云补矩阵(成本对照,eng-automation ROI);
+- 设备状态治理:用例前置重置(清数据/回主屏/关弹窗),**脏设备是 flaky 第一来源**(账号池与设备池配对管理,qa-ui-automation 账号池同构)。
+
+## 稳定性专项（移动特供的脆弱源）
+
+- **系统弹窗 watcher**:权限请求/系统升级/来电/低电量弹窗随时打断——全局 watcher 机制(检测到已知弹窗自动处置并记录),弹窗清单持续回写(新 ROM 新弹窗);
+- 厂商 ROM 差异:权限页路径各家不同(自动化脚本按厂商分支)/后台查杀策略差异(保活相关用例分厂商断言,dev-mobile 后台限制表);
+- 弱网与网络切换注入:限速/断网/WiFi-蜂窝切换场景进关键旅程(dev-mobile 弱网设计的验证面——**复杂环境用例,eng-complex-env 精神**);
+- 时序纪律承 qa-ui-automation:显式等待禁 sleep(移动端加一条:等 idle/等动画结束的框架原语用起来);
+- 首启与升级路径:冷装首启(引导页/权限序列)与覆盖安装(数据迁移)各留用例——**覆盖安装崩溃是差评重灾区**(dev-mobile 状态保存)。
+
+## 定位策略
+
+accessibility id 优先(双端通用+顺手无障碍,eng-ux 底线联动;开发配合埋 id 进 DoD,qa-ui-automation testid 同则)→
+resource-id/原生属性→ 文本(多语言环境用 key 不用文案)→ **图像识别兜底判据**:仅原生控件拿不到的第三方渲染区(地图/游戏/自绘图表),分辨率适配成本先认;
+xpath 绝对路径与坐标点击=禁(换个屏幕尺寸全崩)。
+
+## 专项自动化（关键旅程之外的高 ROI 项）
+
+- **崩溃回归**:monkey/随机遍历夜跑+崩溃聚类上报(dev-mobile 崩溃分级联动)——发现"点不出来的崩溃";
+- **性能基线自动化**:启动耗时/帧率/内存/包体积每构建采集进基线对比(dev-mobile 三基线的自动化执行面,劣化即报,eng-performance 回归防线);
+- **兼容性云测三步曲**:安装-启动-冒烟脚本跑全矩阵(每版本,便宜且拦住"某机型装不上/一开就崩"级事故);
+- 专项与关键旅程分池:专项夜跑不占 PR 门禁时长(cicd-pipeline 快慢分离)。
+
+## 流水线集成
+
+分层执行:PR 级(模拟器冒烟,分钟级)→合入级(自有真机核心旅程)→每日/发版级(云真机全矩阵+专项);
+失败三分类与 flaky 治理承 qa-ui-automation(隔离/限期修/十连绿入池);
+**留证四件**(比 Web 多一件):截图+页面层级 dump+**设备日志(logcat/系统日志)**+录屏——移动端不留设备日志=盲人摸象;
+真机资源排队监控(设备池饱和=反馈变慢,cicd-pipeline runner 容量同构)。
+
+**作业包**:`references/device-matrix-template.md`(云真机矩阵登记(按用户分布)/弹窗 watcher 清单/分层执行配置/性能基线记录)。
+
+## 使用纪律
+
+旅程数红线 ≤10;真机必测清单不用模拟器充数;弹窗清单与厂商差异持续回写;
+性能基线与兼容云测每版本跑;失败留证四件齐;
+每次线上"某机型才有"的事故回写:机型进矩阵+用例进专项——**移动自动化的成熟度=矩阵拦住的机型事故数,不是用例数**。

package/skills/qa-mobile-automation/references/device-matrix-template.md

@@ -0,0 +1,34 @@
+# 移动端设备矩阵与弹窗清单（qa-mobile-automation 落笔件）
+
+## 1. 云真机矩阵登记(按用户分布数据定,季度刷新)
+
+| 档位 | 机型 | OS 版本 | 用户占比 | 用途(门禁/每日/发版) | 备注(ROM 特性) |
+|---|---|---|---|---|---|
+| TOP | __ | | __% | 门禁核心旅程 | |
+| TOP | __ | | __% | | |
+| 最低支持 | __ | 最低 OS __ | __% | 发版必测 | 留存数据依据:__ |
+| 灰名单 | __(投诉高发机型) | | | 发版必测 | 事故:__ |
+
+覆盖目标:TOP 档合计 ≥80% 用户;**真机必测清单**:传感器/相机/推送/性能采集/厂商权限页/弱网(模拟器全绿≠真机能用)。
+
+## 2. 系统弹窗 watcher 清单(持续回写,新 ROM 新弹窗)
+
+| 弹窗 | 触发时机 | 识别特征(testid/文本) | 处置动作 | 登记日期 |
+|---|---|---|---|---|
+| 权限请求(定位/通知/相册) | 首次使用 | | 允许/拒绝分支各测 | |
+| 系统升级提示 | 随机 | | 关闭 | |
+| 来电/低电量 | 随机 | | 关闭+用例重试标记 | |
+| 厂商弹窗(__ 系) | | | | |
+
+## 3. 分层执行配置
+
+- PR 级:模拟器冒烟 __ 条(分钟级)
+- 合入级:自有真机核心旅程 __ 条(≤10)
+- 每日/发版:云真机全矩阵 + 专项(monkey 夜跑/兼容云测三步曲:安装-启动-冒烟/性能基线采集)
+
+## 4. 发布性能基线记录(dev-mobile 三基线的采集面)
+
+| 版本 | 冷启动 P50(TOP 机型) | 冷启动(最低档) | 包体积 | 崩溃率(灰度) | 结论 |
+|---|---|---|---|---|---|
+
+> 劣化当 bug 修;失败留证四件:截图+层级 dump+**设备日志**+录屏(不留设备日志=盲人摸象)。

package/skills/qa-ui-automation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: qa-ui-automation
+description: UI 自动化测试链（ROI 判据只自动化稳定关键旅程→选择器策略(testid>角色文本>CSS,禁 XPath 绝对路径)→显式等待禁 sleep→POM 页面对象→用例独立与登录态复用→重试纪律与脆弱治理→失败自动留证三件→并行分片提速→视觉回归与移动端判据）。eng-quality 的 UI 自动化孙链:搭 Web UI 自动化、E2E 老是挂、跑一轮要两小时、"又是环境问题"时载入。
+version: 1.0.0
+---
+
+# UI 自动化测试链
+
+eng-quality 的 UI 自动化孙链(Playwright 一代工具为基线)。
+UI 层是金字塔塔尖:**最贵、最脆、最慢**——纪律的核心是克制规模、死磕稳定;
+"UI 自动化多"不是成熟,是负债(eng-quality 倒金字塔警告的执行面)。
+
+## ROI 判据（先想清楚测多少）
+
+只自动化**稳定的关键用户旅程**(登录/核心任务闭环/支付,≤15 条,eng-quality 上限);
+判据三问:流程稳定了吗(天天改的页面别自动化,改完再上)/失败真会拦发布吗(不拦=装饰)/接口层能测吗(**能下沉接口层的绝不留 UI 层**,qa-api-automation 十倍便宜)——
+UI 层只测"接口测不到的":页面组装/交互流转/前后端联通;
+新功能与探索用手工+录屏,冒烟稳定后再自动化。
+
+## 选择器策略（脆弱的第一来源）
+
+优先级:**data-testid 语义属性** > 角色+可见文本(getByRole,顺手验了无障碍,eng-ux) > 稳定 CSS 类 > 禁:绝对 XPath/自动生成类名(css-1x2y3z)/nth-child 位置流(改个顺序全崩);
+**测试性是开发验收项**:关键元素带 testid 进 DoD(dev-frontend 配合,前端改样式不背锅);
+testid 命名规范(页面-组件-动作),与组件库约定生成;
+文案断言用 key 或正则(文案微调不该红)。
+
+## 等待策略（禁 sleep 是铁律）
+
+**显式等待条件**:等元素可交互/等请求完成/等加载态消失——现代框架自动等待为主,补显式条件为辅;
+`sleep(3000)` 双输:慢时不够(照样挂)、快时白等(拖时长)——评审见一个拦一个;
+动画与过渡:等终态不等动画(或测试环境关动画);
+轮询型页面:等数据条件(列表出现目标行)不是等时间;
+超时分层:单元素等待(秒级)<用例超时(分钟级)<全局超时,超时值有依据(P99 加载实测)。
+
+## 组织模式（POM 页面对象）
+
+页面对象收口:每页一个类(选择器+页面动作方法),**页面结构变化只改一处**(qa-api-automation 分层同理);
+组件对象复用(通用弹窗/表格/表单控件抽公共对象);
+用例层只写业务语言:`登录页.登录(账号)→工作台.新建报销(数据)→断言(状态)`;
+断言就近业务含义(assertOrderCreated 优于三行元素断言拼凑)。
+
+## 用例独立与状态管理
+
+用例间零依赖(A 建的单 B 用=A 挂 B 陪葬,禁;各自造数,qa-api-automation 造数 API 复用——**UI 测试的数据从接口造,别用 UI 点出来**,又慢又脆);
+登录态复用:会话状态(storageState)一次登录全局复用,**别每条用例走一遍登录 UI**(登录本身单独一条用例测);
+浏览器上下文隔离(每用例新 context,缓存 cookie 零污染);
+账号池:并行时账号隔离(同账号并行=数据窜)。
+
+## 重试与脆弱治理（重试是止痛药不是治疗）
+
+重试纪律:整案重试 ≤1 次且**计数上报**——重试后通过的用例标记"flaky",周报列名;
+**flaky 治理流程**:隔离(挪出门禁池,不拦人)→限期修(两周)→修不好裁撤——带病用例留在门禁=全员学会无视红灯(比没有更毒);
+脆弱根因 TOP:时序假设(等待策略修)/数据残留(独立性修)/环境不稳(测试环境治理,eng-infra)/选择器脆(策略修)——分类统计对症下药(qa-api-automation 三分类同构);
+稳定性验收:新用例连跑 10 遍全绿才入门禁池。
+
+## 失败诊断（自动留证三件）
+
+失败自动保存:**截图+trace 录制(操作与网络时间线回放)+页面快照**——回放一看即知,不用本地复跑猜;
+关联后端:traceId 从前端请求带出,失败用例一键跳后端日志(eng-observability 贯穿);
+失败信息可行动:断言消息说清期望与实际+业务语境("订单状态应为已支付,实际待支付"),不是"element not found"裸奔。
+
+## 速度工程
+
+并行分片:用例天然独立(前提是独立性纪律)→按 worker 并行+CI 分片(cicd-pipeline 矩阵);
+**全量>30 分钟必治理**(裁用例/加并行/下沉接口层);
+无头模式跑常规,有头留调试;测试环境专用与稳定(共享联调环境跑 E2E=天天误报,eng-infra 环境矩阵)。
+
+## 扩展判据
+
+视觉回归:组件库/设计系统才上(像素对比误报率高,阈值与忽略区要精调,eng-ux 走查的自动化补充);
+移动端 UI 自动化:云真机跑关键旅程(dev-mobile 测试节),原生控件定位另有体系,量更克制(≤10 条);
+跨浏览器矩阵:主力浏览器每次跑,长尾浏览器每日跑(browserslist 对齐,dev-frontend)。
+
+**作业包**:`references/stability-conventions.md`(团队约定卡(选择器/等待/十连绿)/POM 骨架/flaky 登记表/失败三件确认)。
+
+## 使用纪律
+
+E2E 数量红线守住(增一条先问"能不能下沉");sleep 与绝对 XPath 评审必拦;
+flaky 周清、门禁池只留十连绿;失败三件必留;
+**UI 自动化的成熟度=红灯的可信度:红了就是真有问题,团队看到红灯的第一反应是查代码而不是点重跑**。

package/skills/qa-ui-automation/references/stability-conventions.md

@@ -0,0 +1,41 @@
+# UI 自动化稳定性约定与 flaky 登记（qa-ui-automation 落笔件）
+
+## 1. 团队约定卡(贴仓库首页,评审对照)
+
+- 选择器优先级:data-testid > 角色+文本(getByRole) > 稳定 CSS;**禁**:绝对 XPath/自动生成类名/nth-child
+- 等待:显式条件(可交互/请求完成/加载态消失);**禁 sleep**(见一个拦一个)
+- 用例独立:数据接口造(不用 UI 点出来);登录态 storageState 复用(登录本身单独一条用例)
+- 断言:业务含义就近封装;文案断言用 key/正则不用全文
+- 新用例准入:**十连绿**才进门禁池;E2E 总数红线 ≤15(增一条先问能不能下沉接口层)
+
+## 2. POM 骨架示意
+
+```ts
+class 报销页 {
+  constructor(private page: Page) {}
+  金额输入 = () => this.page.getByTestId('expense-amount')
+  async 提交报销(数据: 报销单) {
+    await this.金额输入().fill(数据.金额)
+    await this.page.getByRole('button', { name: '提交' }).click()
+    await expect(this.page.getByTestId('result-toast')).toBeVisible()
+  }
+}
+// 页面结构变化只改这里;用例层: await 报销页.提交报销(造数.报销单())
+```
+
+## 3. flaky 登记表(周清;重试通过≠通过)
+
+| 用例 | 首次记录 | 重试通过次数(7天) | 根因分类(时序/数据残留/环境/选择器) | 处置(修/隔离/裁撤) | 期限 |
+|---|---|---|---|---|---|
+
+处置纪律:隔离(挪出门禁池不拦人)→限期两周修→修不好裁撤——带病用例留门禁=全员学会无视红灯。
+
+## 4. 失败诊断三件确认
+
+- [ ] 截图+trace 录制+页面快照自动保存
+- [ ] traceId 从前端带出,失败用例一键跳后端日志
+- [ ] 断言消息带业务语境("订单状态应为已支付,实际待支付",不是 element not found)
+
+## 5. 速度治理
+
+全量时长 __ 分钟(>30 治理:并行分片/裁用例/下沉);并行隔离:账号池 __ 个/数据前缀 __

package/skills/quant-analysis/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: quant-analysis
+description: 行情量化分析（收益率/波动/最大回撤/夏普、均线 MACD RSI 等技术指标计算、策略回测与过拟合防护）。当用户给出行情数据说"分析这只股票/算收益回撤/技术指标/回测策略"时使用。研究工具，不构成投资建议。
+version: 1.0.0
+---
+
+# 行情量化分析（证券技能链 · 投资分析环；全景见 securities-chain）
+
+## 合规红线（每份产出末尾固定声明）
+
+「本内容为历史数据的统计分析与研究工具输出,**不构成投资建议**;历史表现不代表未来;
+据此操作风险自担。」**禁止**：预测点位/荐股/"必涨必跌"措辞/承诺收益。
+数据来源与截止日期必须标注（用户提供数据以用户为准,联网获取注明渠道与抓取时间）。
+
+## 基础统计（`read_skill_file` 读 `scripts/quant.py`）
+
+- `perf_stats()`：日收益率 → 累计收益/年化收益（252 口径）/年化波动/**夏普比率**
+  （rf 参数化,注明取值）/**最大回撤**（峰谷法,给回撤起止日）/最长水下时长——
+  **收益不看回撤=只看了一半**,两者并报;
+- 分布特征：偏度峰度提示（肥尾时正态假设的 VaR 低估,如实标注）;
+- 多标的对比：同期口径对齐（交易日对齐/复权口径注明——**不复权的长期对比是错的**）。
+
+## 技术指标（计算器，不是信号灯）
+
+`ma()/ema()/macd()/rsi()/boll()` 标准公式实现（参数与算法口径注明:RSI 用 Wilder 平滑）;
+指标使用纪律：指标描述的是**已发生的价格**,把指标当预测器是最常见误用——
+产出措辞用"当前 RSI=72,处于传统超买区间"（陈述）,不用"即将回调"（预测）。
+
+## 策略回测（`backtest()`，防自欺三件套内置）
+
+1. **防前视偏差**：信号一律 shift(1)——今天收盘算出的信号明天才能执行,
+   脚本内置且**不可关闭**;
+2. **成本计入**：手续费+滑点参数化（默认双边千一,高换手策略不算成本=纸面富贵）;
+3. **过拟合防护**：样本内/样本外切分（默认 70/30）,**样本外单独报告**;
+   参数敏感性（参数 ±20% 收益剧变=过拟合嫌疑）;
+   产出固定含「回测局限声明」：未含分红送转处理细节/流动性冲击/幸存者偏差（单票回测
+   天然幸存者偏差）。
+- 回测报告规范：策略收益 vs **买入持有基准**（跑不赢基准的复杂策略=负价值）、
+  年化/回撤/夏普/换手四件套、样本外衰减度。
+
+## 组合视角
+
+多标的相关性矩阵（分散化的前提是低相关,**危机时相关性趋同**的提示）;
+组合层面分析转 portfolio-analysis（贡献分解/Brinson 归因/再平衡）。
+
+## 与研究链的衔接
+
+量化是 securities-research 基本面研究的补充视角（估值锚 vs 价格行为）;
+数据加工大表走 data-report-pro;结论进报告走 docx-author 并带全套声明。
+
+## 验收自查
+
+- [ ] 收益与回撤并报;口径（复权/年化基数/rf）注明
+- [ ] 回测过防前视/含成本/样本外三关
+- [ ] 措辞全部陈述式,无预测荐股
+- [ ] 末尾声明与数据来源日期在
+
+## 附件
+
+- `scripts/quant.py` — perf_stats/MA/EMA/MACD/RSI/BOLL/backtest（shift 防前视+成本+样本外切分）;可直接执行自测

package/skills/quant-analysis/scripts/quant.py

@@ -0,0 +1,102 @@
+# 行情量化计算件（经 run_python 执行）：绩效统计 / 技术指标 / 防前视回测（含成本与样本外切分）。
+# ⚠ 研究工具，不构成投资建议；历史表现不代表未来。直接执行本文件 = 自测（合成数据）。
+import numpy as np
+import pandas as pd
+
+ANN = 252  # 年化交易日
+
+
+def perf_stats(prices, rf=0.02, name='标的'):
+    """输入价格序列（pd.Series，索引为日期或序号）。输出年化收益/波动/夏普/最大回撤等。"""
+    p = pd.Series(prices).astype(float).dropna()
+    ret = p.pct_change().dropna()
+    total = p.iloc[-1] / p.iloc[0] - 1
+    years = len(ret) / ANN
+    cagr = (1 + total) ** (1 / years) - 1 if years > 0 else np.nan
+    vol = ret.std(ddof=1) * np.sqrt(ANN)
+    sharpe = (cagr - rf) / vol if vol > 0 else np.nan
+    cum = (1 + ret).cumprod()
+    peak = cum.cummax()
+    dd = cum / peak - 1
+    mdd = float(dd.min())
+    end_i = int(dd.idxmin()) if dd.index.dtype != 'O' else dd.idxmin()
+    print(f'[{name}] 累计 {total:+.1%} · 年化 {cagr:+.2%} · 波动 {vol:.2%} · '
+          f'夏普 {sharpe:.2f}（rf={rf:.1%}） · 最大回撤 {mdd:.1%}')
+    return {'total': round(total, 4), 'cagr': round(cagr, 4), 'vol': round(vol, 4),
+            'sharpe': round(float(sharpe), 2), 'max_drawdown': round(mdd, 4), 'dd_end': end_i}
+
+
+def ma(prices, n):
+    return pd.Series(prices).rolling(n).mean()
+
+
+def ema(prices, n):
+    return pd.Series(prices).ewm(span=n, adjust=False).mean()
+
+
+def macd(prices, fast=12, slow=26, signal=9):
+    dif = ema(prices, fast) - ema(prices, slow)
+    dea = dif.ewm(span=signal, adjust=False).mean()
+    return dif, dea, (dif - dea) * 2
+
+
+def rsi(prices, n=14):
+    """Wilder 平滑 RSI。"""
+    p = pd.Series(prices).astype(float)
+    delta = p.diff()
+    up = delta.clip(lower=0).ewm(alpha=1 / n, adjust=False).mean()
+    dn = (-delta.clip(upper=0)).ewm(alpha=1 / n, adjust=False).mean()
+    rs = up / dn.replace(0, np.nan)
+    return 100 - 100 / (1 + rs)
+
+
+def boll(prices, n=20, k=2.0):
+    mid = ma(prices, n)
+    sd = pd.Series(prices).rolling(n).std(ddof=1)
+    return mid, mid + k * sd, mid - k * sd
+
+
+def backtest(prices, signal, fee=0.001, split=0.7, name='策略'):
+    """防自欺回测：signal 为持仓意图(0/1)，**内部强制 shift(1)**（今日信号明日执行，防前视）；
+    双边费率 fee；按 split 切样本内/外分别报告。返回 (整体统计, 样本外统计, 净值序列)。"""
+    p = pd.Series(prices).astype(float).reset_index(drop=True)
+    sig = pd.Series(signal).astype(float).reset_index(drop=True).clip(0, 1)
+    pos = sig.shift(1).fillna(0)                      # 防前视：不可关闭
+    ret = p.pct_change().fillna(0)
+    turns = pos.diff().abs().fillna(pos.iloc[0])
+    strat = pos * ret - turns * fee
+    nav = (1 + strat).cumprod()
+    cut = int(len(p) * split)
+    print(f'—— {name}：整体（含样本内） ——')
+    full = perf_stats((1 + strat).cumprod() * 100, name=f'{name}-整体')
+    print(f'—— {name}：样本外（后 {1 - split:.0%}，唯一算数的部分） ——')
+    oos = perf_stats((1 + strat.iloc[cut:]).cumprod() * 100, name=f'{name}-样本外')
+    bh = perf_stats(p, name='买入持有基准')
+    print(f'[对比] 策略样本外年化 {oos["cagr"]:+.2%} vs 基准全期年化 {bh["cagr"]:+.2%} · '
+          f'年换手 {turns.sum() / (len(p) / ANN):.1f} 次')
+    print('⚠ 回测局限：历史≠未来；未含分红细节/流动性冲击/幸存者偏差。不构成投资建议。')
+    return full, oos, nav
+
+
+if __name__ == '__main__':
+    rng = np.random.default_rng(9)
+    steps = rng.normal(0.0004, 0.015, 750)
+    px = pd.Series(100 * np.exp(np.cumsum(steps)))
+    s = perf_stats(px, name='合成标的')
+    assert -1 < s['max_drawdown'] < 0 and s['vol'] > 0
+    # 手工校验最大回撤：与逐点扫描一致
+    cum = px / px.iloc[0]
+    manual_mdd = float((cum / cum.cummax() - 1).min())
+    assert abs(s['max_drawdown'] - manual_mdd) < 1e-4  # 返回值四舍五入到 4 位，按同精度比较
+    r = rsi(px)
+    assert r.dropna().between(0, 100).all()
+    dif, dea, hist = macd(px)
+    assert abs(float(hist.iloc[-1]) - 2 * (float(dif.iloc[-1]) - float(dea.iloc[-1]))) < 1e-9
+    sig = (px > ma(px, 20)).astype(int)
+    full, oos, nav = backtest(px, sig, name='MA20 择时')
+    # 防前视验证：把"作弊版"（不 shift）与正版比，作弊版收益应显著更高（同信号）
+    cheat = ((sig * px.pct_change().fillna(0)) - sig.diff().abs().fillna(0) * 0.001)
+    honest = ((sig.shift(1).fillna(0) * px.pct_change().fillna(0)) - sig.shift(1).fillna(0).diff().abs().fillna(0) * 0.001)
+    assert (1 + cheat).prod() != (1 + honest).prod(), '正版必须与作弊版不同（shift 生效）'
+    assert len(nav) == len(px)
+    print('OK quant.py')

package/skills/real-estate-property/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: real-estate-property
+description: 房地产与物业（投资测算 IRR、租赁运营报表、租约到期管理、物业经营分析、资产盘点）。当用户说"测算这个物业/租金回报/出租率/租约管理/物业收缴率/资产台账"时使用。
+version: 1.0.0
+---
+
+# 房地产与物业（现金流测算可复算，运营报表口径先行）
+
+## 投资测算（`read_skill_file` 读 `scripts/property_calc.py`）
+
+- **持有型物业现金流模型**：期初投入（购置+改造+税费）→ 逐年净现金流
+  （潜在租金 ×(1−空置率) − 运营费用 − 税费）→ 退出（退出年 NOI ÷ 退出资本化率 − 交易成本）;
+  `irr()`（牛顿法+二分兜底,可复算）与回收期、`cap_rate()`（NOI/资产价值——**买卖双方的
+  资本化率之争就是价格之争**,给敏感性）;
+- 口径纪律：NOI 不含折旧与财务费用;租金增长率与空置率分开设参（合并设参会互相掩盖）;
+  改造 Capex 与运营费分列;
+- 杠杆测算：加入贷款后算权益 IRR 与 DSCR（转 banking-credit 口径）,**杠杆放大的是波动
+  不是价值**——无杠杆 IRR 先看;
+- 租售比/毛租金回报率速查（年租金/总价）,与 cap rate 区分（毛 vs 净）。
+
+## 租赁运营（收益管理三张表）
+
+1. **租约台账**：租户/面积/单价/起止/免租期/递增条款/押金/中介费——免租期与中介费
+   **摊销进有效租金**（Effective Rent）才可比,`effective_rent()` 计算;
+2. **到期瀑布**：`lease_expiry_waterfall()` 按年（或季）到期面积与租金占比——
+   到期集中度 >30%/年 = 续租风险预警,提前 6–12 个月启动续谈;
+3. **出租率双口径**：面积出租率与租金出租率（低价填坑会让面积口径虚高）;
+   空置分析:空置面积×市场租金=机会成本,倒逼定价决策。
+
+## 物业经营分析
+
+收缴率（**当期收缴率与累计清欠分开**,合并口径会掩盖历史欠费）/ 报事工单
+（响应-完成时效分位数、重复报修率=质量信号、分类帕累托转 customer-service 方法）/
+能耗（公区能耗单价面积口径,同比+异常月归因）/ 增值收入占比（多经/停车/广告位）;
+物业费测算：成本清单法（人员/能耗/维保/管理分摊）→ 单价倒算与市场对标。
+
+## 资产盘点与台账
+
+产权状态（证载/抵押/查封核查项）/ 使用状态（自用/出租/闲置——**闲置资产年持有成本
+显性化**:折旧+税费+维保,推动处置决策）/ 账面 vs 评估价值差异表。
+
+## 验收自查
+
+- [ ] 测算含空置率与退出假设,IRR 给敏感性
+- [ ] 有效租金摊销了免租与中介费
+- [ ] 到期瀑布做了集中度预警
+- [ ] 收缴率双口径,报事看分位数
+
+## 附件
+
+- `scripts/property_calc.py` — irr(牛顿+二分)/cap_rate/effective_rent/lease_expiry_waterfall;可直接执行自测