@dsh-fly/dsh-plugin-fly-mode 0.0.0-stage → 0.1.3

package/tools/dsh-plugin-fly-blackbox/assets/client-blackbox/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: client-blackbox
+description: 当用户报告某个客户端（小程序 / App / 桌面端）行为不对、接口不明、显示与提交不一致、提示语指向一个用户无法完成的动作时加载：建立中间人可观测性、判层（显示 / 提交 / 存储）、用假值与缺失区分真相、并按五阶段带 Gate 流程收口。
+---
+
+# 客户端黑盒排查
+
+你手上只有客户端，没有源码、没有服务端日志、没有能对话的工程师。这套框架就是为这种局面写的：
+**先建模，再动手；每一步都有 Gate，没过不要往下走。**
+
+配套资产（`Base directory for this skill:` 给出的目录下）：
+
+| 文件 | 用途 |
+| --- | --- |
+| `reference/playbook.md` | 五阶段全文：动作、判据、Gate、失败了回哪一步 |
+| `reference/checklist.md` | 全流程可勾选清单（含 Phase 1 自检三连） |
+| `reference/case-ttw.md` | 脱敏案例：三处独立缺陷、三次转折、工单结构 |
+| `reference/rules.schema.md` | `rules.json` 的 schema 与"显式 off"纪律 |
+| `code/mitm_addon_template.py` | 声明式 + 热加载的 mitmproxy addon（读 `FLY_ALLOW_INTERCEPT`） |
+| `code/rules.example.json` | 规则示例（watch / patch_response / patch_request） |
+
+---
+
+## 0. 什么时候用 / 什么时候停手
+
+**用**（命中任意两条就该上这套流程）：
+
+- 界面**显示有值 / 显示已完成**，但提交或下一步校验始终失败；
+- 提示语指向一个**用户物理上无法完成的动作**（"请先补充 X"，而 X 页面没有编辑入口）；
+- 退出重登 / 重装 / 换设备 / 清缓存 / 换网络**全部无效**（症状一模一样）；
+- 提示语与操作结果**互相矛盾**；
+- 客服复现不了，或只会说"你重新填一下"。
+
+**停手**（本仓的硬边界，任何一条命中就停下来问人）：
+
+1. **wxapkg 不做**。加密容器（`V1MMWX`）的离线解开不在本仓能力内 —— 不承诺、不试、不解释成"应该能行"。
+2. **不做半个代理**。TLS 拦截**没有纯仓内替代**：只转发 `CONNECT` 的代理看得到域名、看不到 body，
+   而这类缺陷恰恰在 body 里（页面路由/渲染逻辑塞在 JSON 里，还有相当一部分响应体是图片、字体、gzip）。
+   要么用 mitmproxy，要么以后做原生代理 —— 不拿"看得到域名"冒充"看得到内容"。
+3. **不自动装依赖**。缺 mitmproxy 时把安装命令**交给用户**（两行，点名解释器），不自己 pip install。
+4. **不自动提权**。`sudo` / `osascript … administrator privileges` 一律只输出成文本给人复制；
+   工具侧执行前就拒绝（提权调用弹不出框、也没有超时，真会话会无超时挂住）。
+5. **不碰计费、资格、身份类规则**。只绕"展示 / 自检"这类坏掉的前端逻辑。
+6. **不写 `~/.dsh/skills`**，不把真实抓包与真实 ID 带进仓库。
+
+---
+
+## 1. 心智模型：三源一闸（S1 / S2 / S3 / G）
+
+任何"填写类 / 状态类"故障，本质都是下面四个位置的值或逻辑不一致。**先写下来，再动手。**
+
+| 代号 | 名称 | 含义 | 出错时的典型症状 |
+| --- | --- | --- | --- |
+| **S1** | 渲染源 | 屏幕上显示的东西 | 显示"男"，其实是 `range[0]` 兜底渲染 |
+| **S2** | 提交源 | 前端真正装进请求体的值 | 校验拦住不发包；或发出去的是空值/默认值 |
+| **S3** | 存储源 | 服务端真正生效的值 | 接口返回 `code:0`，字段纹丝不动 |
+| **G** | 闸门 | 谁在判定"不通过" | 前端本地 `return`，还是服务端拒绝 |
+
+**核心动作是对账（reconciliation）**：把 S1 / S2 / S3 分别取到手一一比对，同时确定 G 在哪一层。
+**80% 的时间浪费，都源于把 S1 当成了 S3。**
+
+---
+
+## 2. 六条判据 T1–T6（每条：怎么测 / 什么算证伪）
+
+| # | 判据 | 怎么测 | 什么算证伪 |
+| --- | --- | --- | --- |
+| **T1** | 用户看到的文字不是数据 | 界面显示 → 独立读接口取真值 | 显示值与读接口一致 ⇒ 这条陷阱不成立 |
+| **T2** | 提示文案出现的位置决定责任层 | 把提示语原文丢进**全部响应体**搜 | 搜到 ⇒ 服务端判定；搜不到 ⇒ 纯前端文案 |
+| **T3** | "没发出"和"发出被拒"是两种病 | 数该域名下的非 GET 请求条数 | 有保存请求 ⇒ 前端放行了，问题在服务端侧 |
+| **T4** | 接口返回的可能是"回显请求对象" | 换一个**独立读接口**复核同一条记录 | 读接口与返回体一致 ⇒ 落库成功 |
+| **T5** | 假值陷阱：`0` 是最贵的空值 | 用字符串 `"0"` 注入（JS 里它是真值） | 注入 `"0"` 仍被拦 ⇒ 不是 `!v` 校验的问题 |
+| **T6** | 门禁分两类，一类可骗一类必须停手 | 读响应体：`confirm`/`Y`/`N`/`state` 在谁手里 | 服务端直接返回硬错误 ⇒ 服务端门禁，停手 |
+
+**T5 的通用钥匙**：注入**字符串** `"0"`。JS 里只有 `""` 是假值，`"0"` 是真值 —— 它能同时过
+`!v` 判假与 `==null` 判空，而服务端（Jackson / Gson / JSON 解析器）通常把它正常转成数字 `0`。
+
+---
+
+## 3. 五阶段（每阶段：做什么、Gate 是什么、失败回哪）
+
+| 阶段 | 目标 | Gate | Gate 不过时回哪 |
+| --- | --- | --- | --- |
+| **Phase 0 症状分流** | 把症状翻译成假设 | 能用 S1/S2/S3/G 说清楚，且"为什么重登无效"有自洽解释 | 回用户的原始描述，补事实 |
+| **Phase 1 建立可观测性** | 能看见每一帧流量 | **自检三连**全绿（HTTP 200 / HTTPS 200 / 目标客户端出现 `[NEW HOST]`） | 管道问题：换客户端 / 换端口 / 查 pinning |
+| **Phase 2 协议测绘** | 把黑盒变成接口清单 | 能画出"操作 → 请求 → 谁判定"的流程图，并知道提示语出自哪层 | 回 Phase 1（没抓全） |
+| **Phase 3 三源对账** | 定位到具体那一行 | 能写出"哪个接口、哪个字段、哪一层丢的" | 找不到写接口 → 存活性探测；前端不发包 → 诱出法 |
+| **Phase 4 修复决策** | 用最小侵入达成用户目标 | 用户目标达成且**没有脏数据**（或已规划回滚） | 服务端门禁 ⇒ 停手转人工 |
+| **Phase 5 收口交接** | 可还原、可复现、可追责 | 环境已还原 + 存档 + 工单可执行 | 回放过程补证据 |
+
+**Phase 1 的自检三连**（Gate 1 的硬指标，顺序不能跳）：
+
+```bash
+# ① HTTP 能过
+curl -s -o /dev/null -w '%{http_code}\n' -x http://127.0.0.1:8080 http://example.com/
+# ② HTTPS 中间人能过（这一步才是真正的验证）
+curl -s -o /dev/null -w '%{http_code}\n' -x http://127.0.0.1:8080 \
+     --cacert .fly-blackbox/mitmproxy/mitmproxy-ca-cert.pem https://example.com/
+# ③ 目标客户端确实走了代理：看日志里有没有 [NEW HOST]
+tail -f .fly-blackbox/capture/all.log
+```
+
+> **在证明管道通畅之前，不要对"没抓到东西"做任何解释。** 抓不到东西的第一嫌疑永远是管道，
+> 不是"目标有 pinning"。
+
+---
+
+## 4. 反模式（都是踩过的）
+
+| # | 反模式 | 后果 | 正确做法 |
+| --- | --- | --- | --- |
+| 1 | 把 UI 显示当数据（T1） | 半天耗在"明明有值"上 | 回到数据源验证 |
+| 2 | 不区分"没发出"与"被拒绝"（T3） | 在错误的分支上使劲 | 抓包，一秒区分 |
+| 3 | 相信接口回显（T4） | 误判成功 | 独立读接口复核 |
+| 4 | 用 `!v` 判断枚举（T5） | `0` 值永久不可达（很多线上 bug 的真身） | 显式判 `== null` / `=== ''` |
+| 5 | 盲试 `save` / `insert` 类接口 | 数据被写坏 | 先 GET 探测方法，评估覆盖风险 |
+| 6 | 一次改多个变量 | 无法归因 | 单一变量 + 明确观察点 |
+| 7 | 没证明管道通就解释"没抓到" | 误判为 pinning 而放弃 | 自检三连 |
+| 8 | 还原顺序颠倒（先杀进程再关代理） | 瞬断网 | 先关系统代理，再杀代理进程 |
+| 9 | 忘了写还原脚本 | 留下长期代理 | 第一分钟就写 |
+| 10 | 反复注销 / 重注册 / 找回 | 纯浪费时间（数据在服务端表里） | 先建模，再操作 |
+| 11 | 拿前端文案当证据 | 定位错层 | 全文搜响应体（T2） |
+| 12 | 把"客服复现不了"当成自己没说清 | 自责并放弃 | 用**字段级 diff** 逼他们进同一条路径 |
+| 13 | 只抓不改 / 只改不验 | 拿不到结论 | 每次变更后用独立读接口复核 |
+| 14 | 绕过计费 / 资格类校验 | 越界 | 只绕"展示 / 自检"，业务规则一律不碰 |
+
+---
+
+## 5. 合规红线（不可谈判）
+
+1. **只操作你自己的账号与数据。** 不做横向探测、不碰他人 ID。
+2. **不做破坏性写入。** 涉及账号资料的写入前逐条过 Phase 4 的风险清单（打码字段、整行覆盖、`save` 类接口）。
+3. **不绕过计费、资格、身份类规则。** 属"业务规则"的门禁一律停手。
+4. **发现漏洞 → 负责任披露**，不利用、不传播、不变现。
+5. **抓包存档包含凭据**（token / 手机号 / 身份证）。归档前脱敏；发人之前打码。
+
+---
+
+## 6. 工具与资产（本包提供）
+
+| 工具 | 干什么 | 授权 |
+| --- | --- | --- |
+| `bx_proxy` | 起 / 停 / 看本地拦截代理（`status` 回显状态文件、confdir、dump、`mitmdump --version`） | `start`/`stop`/`restart` 需 `FLY_ALLOW_INTERCEPT=1` |
+| `bx_doctor` | 五段判决：HTTP / **HTTPS 的签发者是否就是 confdir 里的 mitm CA** / 目标客户端是否出现 / 冲突代理 / 系统代理 `Enabled` | 需 `FLY_ALLOW_INTERCEPT=1` |
+| `bx_sysproxy` | 看 / 开关 macOS 系统代理（判决默认路由服务名，附一条还原命令） | `on`/`off` 需 `FLY_ALLOW_INTERCEPT=1` |
+| `bx_ca` | CA 信任状态 + **要人跑的命令文本** + `security verify-cert` 事后证据 | 不受门控（永不提权） |
+| `bx_flows` | 离线读 dump：`hosts` / `list` / `show` / `grep`（版本闸 + 拒绝截断） | 不受门控（只读） |
+| `bx_diff` | 改前/改后字段级 diff，显式区分**缺失** / **假值** / **类型变化** | 不受门控（只读） |
+
+规则文件固定 `<workspace>/.fly-blackbox/rules.json`，由**你自己用文件工具写**，`bx_proxy start` 只读并校验；
+schema 与"显式 off、无静默默认值"的纪律见 `reference/rules.schema.md`。
+
+---
+
+## 7. 人机分工
+
+| 事 | 谁做 |
+| --- | --- |
+| 起代理、判管道、读 dump、比对前后 | 工具（`bx_*`） |
+| 系统代理 / 信任 CA（要密码） | **人**（工具只给命令与事后证据） |
+| ⌘Q 再重开目标客户端（`WeChatAppEx` 只在启动时读系统代理） | **人** |
+| 屏幕上发生了什么（"现在显示女了"） | **人** —— 屏幕本身就是 oracle，这一条不可替代 |
+| 写入类动作的取舍（要不要动这条记录） | **人**（风险清单逐条过） |

package/tools/dsh-plugin-fly-blackbox/assets/client-blackbox/code/mitm_addon_template.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+mitm_addon_template.py —— 客户端黑盒排查用的 mitmproxy 插件（声明式 + 热加载）
+
+设计原则（都是实战踩坑换来的）
+  1. **声明式**：行为全写在 rules.json 里，不写死在代码里 —— 换个目标只改 json
+  2. **热加载**：改完 rules.json 立即生效，**不重启代理**
+     （排查中最浪费时间的就是"改一行配置 → 重启 → 等客户端重连"）
+  3. **永远先 watch，再 patch**；patch 一次只动一个字段
+  4. **每一处篡改都在日志里吼一声**，让你不可能忘记自己改过什么
+  5. **缺规则 / 规则非法 = 拒绝启动**，绝不回退到"默认注入"
+     （反面教材：一次性脚本把规则文件写空，addon 静默继续改包，结论跟着一起坏掉）
+  6. **改动路径要显式授权**：只有 `FLY_ALLOW_INTERCEPT=1` 时才允许注入；
+     否则退化成只读记录 —— 只读路径永远可用
+
+用法（由 `bx_proxy start` 拼出来，这里是它的形状）
+    mitmdump -s mitm_addon_template.py -w <workspace>/.fly-blackbox/flows.mitm \
+             --set confdir=<workspace>/.fly-blackbox/mitmproxy \
+             -p 8080
+    # 规则路径与授权开关走**环境变量**（不是 `--set`）：
+    #   MITM_RULES=<workspace>/.fly-blackbox/rules.json
+    #   MITM_CAPTURE=<workspace>/.fly-blackbox/capture
+    #   FLY_ALLOW_INTERCEPT=1        （只有 =1 才允许注入；否则只读记录）
+    #
+    # 为什么不用 `--set fly_rules=…`：实测 mitmdump 12.2.3 里 `--set` 的值要到 addon 的
+    # `load()` **之后**才写进 `ctx.options`（`load()` 里读到的是空串、`running()` 里才是
+    # 给定值），而本 addon 的纪律是"规则文件缺失/非法 = 在 `load()` 里拒绝启动"。用
+    # `--set` 传规则路径会静默退回默认的 `rules.json`、当场抛 RuleError、mitmdump 退出 1
+    # —— 代理根本起不来，而症状看起来像"规则文件没写"。
+
+规则示例见同目录 rules.example.json，schema 见 reference/rules.schema.md。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+
+from mitmproxy import ctx, http
+
+# ---------------------------------------------------------------- 基础配置
+
+# 规则路径走**环境变量**：这是唯一在 addon 的 import / load() 期就生效的通道
+# （`--set` 要等 load() 之后才写进 ctx.options —— 见文件头"为什么不用 --set"）。
+RULES_PATH = Path(
+    os.environ.get("MITM_RULES")
+    or getattr(ctx.options, "fly_rules", "")
+    or "rules.json"
+)
+CAPTURE_DIR = Path(os.environ.get("MITM_CAPTURE", "./capture"))
+
+# 值是"空"的判定 —— 注意 0 与 "0" 都算空（这正是大量线上 bug 的来源，见 playbook T5）。
+# patch 时按需选择 mode。
+EMPTY_VALUES = (None, "", 0, "0", [], {})
+
+_rules_cache: dict | None = None
+_rules_mtime: float = -1.0
+_seen_hosts: set[str] = set()
+
+
+def _intercept_allowed() -> bool:
+    """改动路径的授权开关。未设/不等于 1 → 只记录、不注入。"""
+    return os.environ.get("FLY_ALLOW_INTERCEPT") == "1"
+
+
+# ---------------------------------------------------------------- 规则加载
+
+
+class RuleError(RuntimeError):
+    """规则文件缺失或非法 —— 一律拒绝启动，绝不静默回退。"""
+
+
+def _load_rules() -> dict:
+    """
+    读规则。**缺文件、空文件、非法 JSON、缺关键键都抛错**。
+
+    这里刻意不提供"默认规则"：默认规则意味着"用户以为关掉了，其实还在注入"，
+    而那种静默正是本框架最贵的一个坑。
+    """
+    path = RULES_PATH
+    if not path.is_file():
+        raise RuleError(f"规则文件不存在：{path} —— 拒绝启动（不提供默认注入）")
+    raw = path.read_text(encoding="utf-8")
+    if raw.strip() == "":
+        raise RuleError(
+            f"规则文件是空的：{path} —— 空文件曾被静默当成'默认注入'，"
+            '所以这里一律当非法。要关掉注入请显式写 {"enabled": false}'
+        )
+    try:
+        loaded = json.loads(raw)
+    except Exception as exc:  # noqa: BLE001 - 原话要透给用户
+        raise RuleError(f"规则文件不是合法 JSON：{path} —— {exc}") from exc
+    if not isinstance(loaded, dict):
+        raise RuleError(f"规则文件顶层必须是对象：{path}")
+
+    watch = loaded.get("watch") or {}
+    if not isinstance(watch, dict):
+        raise RuleError(f"watch 必须是对象：{path}")
+    for key in ("patch_request", "patch_response"):
+        if key in loaded and not isinstance(loaded[key], list):
+            raise RuleError(f"{key} 必须是数组：{path}")
+    return {
+        "enabled": bool(loaded.get("enabled", True)),
+        "hosts": list(loaded.get("hosts") or []),
+        "watch": {
+            "paths": list(watch.get("paths") or []),
+            "log_bodies": bool(watch.get("log_bodies", True)),
+            "log_all_requests": bool(watch.get("log_all_requests", True)),
+            "noise_hosts": list(watch.get("noise_hosts") or []),
+        },
+        "patch_request": list(loaded.get("patch_request") or []),
+        "patch_response": list(loaded.get("patch_response") or []),
+    }
+
+
+def rules() -> dict:
+    """热加载：mtime 变了就重读。所以改完 json 不用重启代理。"""
+    global _rules_cache, _rules_mtime
+    try:
+        mtime = RULES_PATH.stat().st_mtime
+    except OSError:
+        # 文件在运行中被删了：缓存还在就继续用缓存（进程内的规则不会凭空变），
+        # 没有缓存说明启动时就没读到 —— 那时已经抛错退出了。
+        if _rules_cache is None:
+            raise RuleError(f"规则文件不见了：{RULES_PATH}") from None
+        return _rules_cache
+    if _rules_cache is None or mtime != _rules_mtime:
+        loaded = _load_rules()  # 非法就在下一次请求时抛出来
+        _rules_cache = loaded
+        _rules_mtime = mtime
+        ctx.log.warn(
+            f"[RULES] 已加载 {RULES_PATH}（改动自动生效）：enabled={loaded['enabled']} "
+            f"patch_request {len(loaded['patch_request'])} 条 / patch_response {len(loaded['patch_response'])} 条"
+        )
+    return _rules_cache
+
+
+# ---------------------------------------------------------------- 工具函数
+
+
+def _log_file(name: str, line: str) -> None:
+    CAPTURE_DIR.mkdir(parents=True, exist_ok=True)
+    with (CAPTURE_DIR / name).open("a", encoding="utf-8") as fh:
+        fh.write(line + "\n")
+
+
+def _host_ok(host: str, r: dict) -> bool:
+    hosts = r.get("hosts") or []
+    return (not hosts) or any(h in host for h in hosts)
+
+
+def _match(patterns, path: str) -> bool:
+    return any(re.search(p, path, re.I) for p in (patterns or []))
+
+
+def _json_of(text: str):
+    try:
+        return json.loads(text)
+    except Exception:
+        return None
+
+
+def _apply(node, updates: dict, mode: str, create_missing: bool) -> list[str]:
+    """递归地把 updates 应用到 JSON 树里所有"含有这些 key"的 dict。
+
+    mode:
+      set_if_empty  仅当原值为空（None/""/0/"0"/[]/{}）时写入
+      force         无条件覆盖
+      only_missing  仅当 key 不存在时新增（配合 create_missing）
+    """
+    hits: list[str] = []
+
+    if isinstance(node, dict):
+        for key, value in updates.items():
+            if key in node:
+                old = node[key]
+                if mode == "force" or (mode == "set_if_empty" and old in EMPTY_VALUES):
+                    node[key] = value
+                    hits.append(f"{key}: {old!r} -> {value!r}")
+            elif create_missing and mode == "only_missing":
+                node[key] = value
+                hits.append(f"{key}: <缺失> -> {value!r}")
+        for value_node in node.values():
+            hits.extend(_apply(value_node, updates, mode, create_missing))
+    elif isinstance(node, list):
+        for item in node:
+            hits.extend(_apply(item, updates, mode, create_missing))
+
+    return hits
+
+
+def _patch_message(message, rule: dict, kind: str) -> None:
+    """kind: 'REQ' | 'RESP'。只处理 JSON。"""
+    if not _intercept_allowed():
+        ctx.log.warn(
+            f"[PATCH-{kind}] 规则命中 {rule.get('path')}，但 FLY_ALLOW_INTERCEPT != 1 —— "
+            "只读模式，拒绝改动。要注入请先显式授权。"
+        )
+        return
+    ctype = (message.headers.get("content-type", "") or "").lower()
+    text = message.get_text(strict=False) or ""
+    data = _json_of(text)
+    if data is None:
+        if "json" in ctype:
+            ctx.log.warn(f"[PATCH-{kind}] {rule.get('path')} 命中但 body 不是合法 JSON，跳过")
+        return
+
+    mode = rule.get("mode", "set_if_empty")
+    hits = _apply(data, rule.get("set", {}), mode, bool(rule.get("create_missing")))
+    if hits:
+        message.set_text(json.dumps(data, ensure_ascii=False))
+        ctx.log.warn(f"[PATCH-{kind}] {rule.get('path')} :: " + "; ".join(hits))
+
+
+# ---------------------------------------------------------------- hooks
+
+
+def request(flow: http.HTTPFlow) -> None:
+    r = rules()
+    host = flow.request.pretty_host
+    if not _host_ok(host, r):
+        return
+
+    watch = r["watch"]
+    if watch.get("log_all_requests", True):
+        line = f"{time.strftime('%H:%M:%S')} REQ  {flow.request.method} {flow.request.pretty_url}"
+        _log_file("all.log", line)
+        if host and host not in _seen_hosts:
+            _seen_hosts.add(host)
+            ctx.log.warn(f"[NEW HOST] {host}")
+            _log_file("all.log", f"*** NEW HOST: {host}")
+        if not any(n in host for n in (watch.get("noise_hosts") or [])):
+            ctx.log.info(line)
+
+    if watch.get("log_bodies") and _match(watch.get("paths"), flow.request.path):
+        body = flow.request.get_text(strict=False) or ""
+        _log_file(
+            "watch.log",
+            f"\n===== REQ {time.strftime('%H:%M:%S')} =====\n"
+            f"{flow.request.method} {flow.request.pretty_url}\n"
+            f"--- headers ---\n"
+            + "\n".join(f"{k}: {v}" for k, v in flow.request.headers.items())
+            + f"\n--- body ---\n{body[:4000]}",
+        )
+
+    if not r["enabled"]:
+        return
+    for rule in r.get("patch_request", []):
+        if not _match([rule.get("path", "")], flow.request.path):
+            continue
+        methods = [m.upper() for m in rule.get("methods", ["POST", "PUT", "PATCH"])]
+        if flow.request.method.upper() not in methods:
+            continue
+        _patch_message(flow.request, rule, "REQ")
+
+
+def response(flow: http.HTTPFlow) -> None:
+    r = rules()
+    host = flow.request.pretty_host
+    if not _host_ok(host, r):
+        return
+
+    watch = r["watch"]
+    if watch.get("log_all_requests", True):
+        _log_file(
+            "all.log",
+            f"{time.strftime('%H:%M:%S')} RESP {flow.response.status_code} "
+            f"{flow.request.method} {flow.request.pretty_url}",
+        )
+
+    # 先记录原始响应（存档优先于篡改 —— 证据不能被自己改没了）
+    if watch.get("log_bodies") and _match(watch.get("paths"), flow.request.path):
+        _log_file(
+            "watch.log",
+            f"\n----- RESP {time.strftime('%H:%M:%S')} {flow.response.status_code} "
+            f"{flow.request.path} -----\n"
+            f"{(flow.response.get_text(strict=False) or '')[:4000]}",
+        )
+
+    if not r["enabled"]:
+        return
+    for rule in r.get("patch_response", []):
+        if not _match([rule.get("path", "")], flow.request.path):
+            continue
+        _patch_message(flow.response, rule, "RESP")
+
+
+def load(_loader) -> None:
+    """启动即校验规则：缺文件 / 空文件 / 非法 → 直接抛，进程不进入服务状态。"""
+    loaded = rules()
+    ctx.log.info(
+        f"fly-blackbox addon 就绪：规则 {RULES_PATH} · enabled={loaded['enabled']} · "
+        f"注入授权 FLY_ALLOW_INTERCEPT={'1（开）' if _intercept_allowed() else '未设（只读）'}"
+    )
+
+
+def done() -> None:
+    ctx.log.info(f"抓包存档目录：{CAPTURE_DIR}（all.log / watch.log）")

package/tools/dsh-plugin-fly-blackbox/assets/client-blackbox/code/rules.example.json

@@ -0,0 +1,52 @@
+{
+  "_说明": [
+    "声明式排查规则。改完保存即生效，不需要重启 mitmdump（addon 按 mtime 热加载）。",
+    "纪律：永远先只开 watch 跑一遍，看清真实流量，再加 patch。",
+    "patch 一次只动一个字段，并在心里明确『观察点』是什么（界面显示？发包？响应码？）。",
+    "关掉注入必须显式写 enabled: false —— 空文件是非法配置，bx_proxy start 会拒绝启动。"
+  ],
+
+  "enabled": true,
+
+  "hosts": ["api.example.com"],
+
+  "watch": {
+    "paths": ["user|member|profile|account|enroll|apply|check"],
+    "log_bodies": true,
+    "log_all_requests": true,
+    "noise_hosts": ["weixin.qq.com", "qpic.cn", "gtimg.cn"]
+  },
+
+  "patch_response": [
+    {
+      "_场景": "服务端把『拦不拦』的决定权交给了客户端（state/confirm/Y/N）→ 客户端门禁，可解除",
+      "path": "member/checkMemberMe",
+      "mode": "force",
+      "set": { "state": true, "confirm": false }
+    },
+    {
+      "_场景": "诱出法：把空字段注入成非空，骗过前端必填校验，逼它把请求发出去",
+      "_技巧": "枚举字段优先试字符串 \"0\" —— JS 里它是真值，能同时过 !v 判假和 ==null 判空",
+      "path": "member/getMemberById",
+      "mode": "set_if_empty",
+      "set": { "gender": "0" }
+    },
+    {
+      "_场景": "给缺失字段补值（key 不存在时才新增）",
+      "path": "some/path",
+      "mode": "only_missing",
+      "create_missing": true,
+      "set": { "extraFlag": true }
+    }
+  ],
+
+  "patch_request": [
+    {
+      "_场景": "请求已经发出去了但字段是空的，直接在传输层补上",
+      "path": "member/updateMember",
+      "methods": ["POST"],
+      "mode": "set_if_empty",
+      "set": { "gender": "0" }
+    }
+  ]
+}