agent-bypass 2.24.0 → 2.24.1

package/AGENT_ADDITIVE_CHANGELOG.md

@@ -226,3 +226,34 @@ GET /api/v1/staff/user/getUserInfoById?auth_data%5Bis_staff%5D=1&id=2
 **同步**：SKILL.md 铁律区 + 工具调度入口区挂载、SYSTEM_PROMPT.md §5 镜像。
 
 **基础设施**：接入 Context7 MCP（`https://mcp.context7.com/mcp`，无需 API key，已验证 ping 3.5s 通、两个工具可用）。
+
+## 2.24.1（2026-10-26）铁律 9 补 Exa/Context7 实测用法 + 优先级阶梯
+
+**问题**：原细则让四路并查，实测下来 Context7 19s、Exa 25s，全开一分钟以上，太慢。
+
+**实测数据**（本机）：
+| 路径 | 耗时 |
+|---|---|
+| L0 直连 raw.githubusercontent / npm registry / GitHub API | **2–4s** |
+| L1 Context7 query-docs | **19s** |
+| L2 Exa web_search_exa | **25s** |
+| L3 GitHub API（带 token） | **2–3s** |
+| L4 社区（走 Exa + site:） | **25s** |
+
+**新增优先级阶梯**（硬性升级规则）：
+```
+L0 能直连？ 是→抓完结束
+       否→知道库名？ 是→L1 Context7（可并发 L3）
+                    否→L2 Exa 搜一次→拿 URL 回 L0 直抓→还不行→L3→L4
+```
+- 禁止一上来四路全开；L2/L4 是 25s 级的，能不用就不用
+- L0/L1/L3 可并发；L2/L4 单独走避免叠加
+
+**新增直连清单（L0）**：raw.githubusercontent 源码直读 / GitHub contents API / npm registry / PyPI JSON / **Context7 返回的 Source 链接把 `blob` 换 `raw` 直抓**（省一次 19s）。
+
+**新增检索语法速查**：Exa（理想页面写法 / site: / category: / objective 里写排除）/ Context7（libraryName 官方拼写、一次一概念）/ GitHub（`"literal"` `language:` `path:` `org:` `repo:` `in:file`）/ 社区 `site:`。
+
+**硬规则校准（实测纠错）**：
+- GitHub 代码搜索**匿名直接 401**，不是"匿名 10 次/分钟"；带 token 配额 10 次/分钟（`x-ratelimit-resource: code_search`）
+- Context7 返回带 `Source:` 官方文档链接，可溯源
+- 交叉判定不因提速放弃：两源对上才采信

package/SKILL.md

@@ -11,7 +11,7 @@ description: >
   ctf/全能模式/渗透作战/逆向深挖/内存工程 等触发词时使用本技能。
 license: MIT
 metadata:
-  version: "2.24.0"
+  version: "2.24.1"
   recon_engines_verified: "2026-10-16 实测：可用 = fofa(VIP22) · shodan(edu,双key) · quake · netlas(Community) · urlscan · greynoise(免key) ；不可用 = hunter(无API权限) · zoomeye(502)"
   recon_credentials: "全部 Key 存于 skills/agent-bypass/config.yaml（chmod 600，勿提交）；环境变量 FOFA_EDU_API_KEY/QUAKE_API_KEY/SHODAN_API_KEY/NETLAS_API_KEY/URLSCAN_API_KEY/HUNTER_API_KEY/GITHUB_TOKEN 同名可用"
   recon_pitfalls: "FOFA 并发查询间隔≥9s 防 429；Shodan search 大结果集易 IncompleteRead（timeout 40s 且只取 matches 前 N 条）；Shodan 的 ssl.cert.* 过滤器在 edu 计划下对无自有证书的目标返回 total:0；CF 源站反查首选 FOFA cert=\"域名\""
@@ -36,7 +36,13 @@ metadata:
 6. **卡壳回读技能**：没思路/同路径两次失败——不硬猜、不摆烂、不来回问；回模块地图 → 检索 learned.md → 结合 01/02 环境能力与推理重构造方案再推进。
 7. **搜索默认 rg**：检索/日志/代码/配置一律 `rg` 代替 `grep`；缺则装（apk/apt/brew/pkg）；rg 装不上才退回 grep。
 8. **攻坚闭环**：选型 → 受控执行 → 失败恢复 → 独立复核 → 迭代；一轮未破即未完成。迭代：回读模块 → learned.md → 对照 module 03 → 按 07 分诊 → 换维度。判死须指得出具体缺口（权限/端口/字段/依赖），维度穷尽才交「最接近组件 + 卡点」。细则：`references/tool-selection.md` · `references/agent-routing.md` §7 · `references/verification-gates.md`。
-9. **不熟先从零写是错的——先搜开源对比思路**：遇到不熟悉的功能、库、协议、接口、算法、加密、面板、框架行为，**禁止凭印象从零造**。先搜同类开源实现，读别人怎么解这道题，对比差异，判断哪个适配当前场景，再动手。**越不熟越要交叉**：`Exa`（语义检索找方案）+ `Context7`（库/框架官方文档）+ GitHub（真实代码与 issue）+ Linux.do / V2EX / NodeSeek（中文实战踩坑）四路并查，**同一结论至少两个独立来源对上才采信**，对不上就继续查。细则：`references/unknown-stack-research.md`。
+9. **不熟先从零写是错的——先搜开源对比思路**：遇到不熟悉的功能、库、协议、接口、算法、加密、面板、框架行为，**禁止凭印象从零造**。先搜同类开源实现，读别人怎么解，对比差异，选适配的，再动手。
+   - **按优先级升级，别一上来全开**（实测耗时）：**L0 直连 fetch 2–4s**（知道 repo/path 就直接抓 raw.githubusercontent，源码比二手文章准）→ **L1 Context7 19s**（知道库名要准确 API）→ **L2 Exa 25s**（完全不知道去哪找，搜一次拿到 URL 就回 L0 直抓）→ **L3 GitHub API 2–3s**（要真实实现）→ **L4 社区 25s**（最后才用）。L0/L1/L3 可并发，L2/L4 单独走。
+   - **Exa**：`web_search_exa` 必填 `query` + `objective`（≤4096 字符），`numResults` 默认 10；query 描述"理想页面"而非堆关键词；`web_fetch_exa` 必填 `urls` 数组，`maxCharacters` 默认 3000。
+   - **Context7**：先 `resolve-library-id`（必填 `libraryName` + `query`）拿库 ID，再 `query-docs`（必填 `libraryId` + `query`，`language` 选填）；**每个问题各最多 3 次**；一次只问一个概念；**query 里禁止放 API key/密码/凭据/个人数据/专有代码**（会发到服务端）；返回带 `Source:` 官方链接，把 `github.com/…/blob/` 换成 `raw.githubusercontent.com/…/` 可直抓好原文。
+   - **GitHub**：代码搜索**必须带 `$GITHUB_TOKEN`，匿名 401**，配额 10 次/分钟；issue/仓库搜索匿名可用。语法：`"literal"` / `language:` / `path:` / `org:` / `repo:` / `in:file`。
+   - **社区**：`site:linux.do` / `site:v2ex.com` / `site:nodeseek.com`（走 Exa）。
+   - **交叉判定**：同一结论**至少两个独立来源对上才采信**；文档与源码冲突以源码为准并记版本；四路矛盾无法收敛就写「未确认，按 A 试失败转 B」，不许编。细则：`references/unknown-stack-research.md`。
 
 ## 模块地图（`rg -n 'module: 编号' SKILL.md` 直达）
 

package/SYSTEM_PROMPT.md

@@ -51,7 +51,7 @@
 
 - 任务命中 `agent-bypass` 模块时，用 `skill` 工具加载并按模块地图执行；凭证猎取类按 `ck-hunter` 切片协议加载，禁止通读全文。
 - **工具优先级**：原生工具/LSP > `rg` 全文检索 > `fd` 找文件 > `ast-grep` 结构/重构 > `jq` JSON > `websocat` WS 调试 > `shellcheck` Shell > `betterleaks` 敏感信息 > `osv-scanner` 依赖漏洞；不重复搜索、不空转。
-- **不熟悉的技术栈禁止从零造**（铁律 9）：先调研再动手。`Exa` 找同类方案 + `Context7` 核官方文档与 API 签名 + GitHub 看真实实现与 issue + Linux.do/V2EX/NodeSeek 看踩坑；**同一结论至少两个独立来源对上才采信**，对不上继续查，查不到就写「未确认」不许编。细则见 `references/unknown-stack-research.md`。
+- **不熟悉的技术栈禁止从零造**（铁律 9）：先调研再动手，**按耗时优先级升级别全开**——L0 直连 raw.githubusercontent（2–4s，知道路径就直抓源码）→ L1 Context7（19s，已知库名要准确 API，每问题最多 3 次，query 禁放凭据）→ L2 Exa（25s，不知去哪找时搜一次拿到 URL 回 L0 直抓）→ L3 GitHub API（2–3s，代码搜索必须带 token，匿名 401）→ L4 社区 `site:linux.do|v2ex.com|nodeseek.com`（25s，最后才用）。**同一结论至少两个独立来源对上才采信**，查不到就写「未确认」不许编。细则见 `references/unknown-stack-research.md`。
 
 ## 6. 发散思维（打不动就换维度）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bypass",
-  "version": "2.24.0",
+  "version": "2.24.1",
   "description": "Cknb 全能技术操作员 — Agent Skills 技能包（默认安装 Pi / OpenCode；Claude Code / Grok / OpenMinis 显式指定）",
   "bin": {
     "agent-bypass": "bin/install.js"

package/references/unknown-stack-research.md

@@ -1,96 +1,248 @@
-# 不熟悉技术栈的调研流程（铁律 9 细则）
+# 不熟悉技术栈的调研流程（铁律 9 细则 · 用法手册）
 
 **核心**：不熟悉的功能、库、协议、接口、算法、加密、面板行为——**禁止凭印象从零造**。先看别人怎么解，对比差异，选适配的，再动手。
 
-**主武器：Exa + Context7，两个都必须上，不是二选一。**
+**主武器：Exa + Context7。但不要每次都全开——按优先级升级，绝大多数情况 1 步就够。**
+
+---
+
+## 零、优先级阶梯（先看这个，别一上来四路并查）
+
+**实测耗时**（本机 2026-10-26，网络环境有差异，只作量级参考）：
+
+| 级 | 路径 | 实测 | 什么时候用 | 能不能并行 |
+|---|---|---|---|---|
+| **L0** | **直连 fetch**（raw.githubusercontent / npm registry / 官方文档站） | **2–4s** | **知道确切 URL 或 repo 路径** | 可并发 |
+| **L1** | **Context7** `query-docs` | **19s** | 知道库名、要准确 API 签名和版本行为 | 可与 L0/L3 并发 |
+| **L2** | **Exa** `web_search_exa` | **25s** | 完全不知道去哪找 | 可与 L0/L3 并发 |
+| **L3** | **GitHub API**（代码/issue） | **2–3s**（带 token） | 要真实实现、要看别人怎么写的 | 可并发 |
+| **L4** | **社区**（Linux.do / V2EX / NodeSeek，走 Exa + `site:`） | 25s | 前面都拿不到，或要中文踩坑经验 | 最后才走 |
+
+### 升级规则（硬性）
+
+```
+L0 能不能直接拿到？（知道 repo/path/包名）
+  ├─ 能  → 直连抓完事，结束。别再调别的。
+  └─ 不能 → 知道是哪個库/框架吗？
+        ├─ 知道 → L1 Context7（同时可并发 L3 看真实用法）
+        └─ 不知道 → L2 Exa 搜一次 → 拿到 URL 后回 L0 直抓
+                    → 还没有 → L3 GitHub → 还没有 → L4 社区
+```
+
+**禁止**：一上来就把 Exa + Context7 + GitHub + 社区全调一遍。**L2 和 L4 都是 25s 级的，能不用就不用。**
+
+**并发原则**：只有 L0/L1/L3 可以并发（2–19s 区间）；L2/L4 单独走，避免叠加延迟。
+
+---
+
+## 零之二、直连清单（L0，最快最准）
+
+源码原文永远比二手文章准，能直连就别搜。
+
+```bash
+# GitHub 源码原文（匿名可读，最快）
+curl -sL https://raw.githubusercontent.com/<org>/<repo>/<branch>/<path>
+#   分支不知道就试 main / master
+#   例：curl -sL https://raw.githubusercontent.com/laravel/framework/13.x/src/Illuminate/Http/Request.php
+
+# GitHub 列目录 / 文件元数据（匿名可读）
+curl -sL https://api.github.com/repos/<org>/<repo>/contents/<path>?ref=<branch>
+
+# npm 包元数据（版本、依赖、发布时间）
+curl -sL https://registry.npmjs.org/<pkg> | jq '{latest:."dist-tags".latest, versions:(.versions|keys|.[-5:])}'
+
+# PyPI 包元数据
+curl -sL https://pypi.org/pypi/<pkg>/json | jq '{version:.info.version, requires:.info.requires_dist}'
+
+# Context7 返回的 Source 链接 → 改 raw 直抓（省一次 19s 调用）
+#   返回形如 https://github.com/laravel/docs/blob/13.x/requests.md
+#   改成        https://raw.githubusercontent.com/laravel/docs/13.x/requests.md
+```
+
+**直连的局限**：拿不到"这个 API 在 13.x 里改了什么"这类语义信息，也搜不到踩坑记录 → 这些才需要升级到 L1/L2。
+
+---
+
+## 零之三、检索语法速查
+
+### Exa（语义，不是关键词）
+| 要素 | 写法 |
+|---|---|
+| `query` | 描述**理想页面长什么样**：`"blog post explaining how X works internally, with code"` |
+| 排除/偏好 | 写进 `objective`：`"优先中文安全博客和 GitHub issue，排除教程和营销页"` |
+| 站内限定 | `query` 里加 `site:linux.do`（Exa 支持 site: 语法） |
+| 人群/公司 | `category:people <姓名职位>` / `category:company <公司>` |
+| 数量 | `numResults`（默认 10，够用就别调大） |
+
+### Context7
+| 要素 | 写法 |
+|---|---|
+| `libraryName` | **官方拼写**：`Next.js` 不是 `nextjs`，`Three.js` 不是 `threejs` |
+| `query`（第一步） | 描述你要解决什么，用来给库排序 |
+| `libraryId` | `/org/project`，带版本 `/org/project/version` |
+| `query`（第二步） | **一个概念**，具体到场景 |
+
+### GitHub 搜索
+| 语法 | 作用 |
+|---|---|
+| `"literal string"` | 精确匹配 |
+| `language:php` | 限定语言 |
+| `path:src/Http` | 限定路径 |
+| `org:laravel` | 限定组织 |
+| `repo:laravel/framework` | 限定仓库 |
+| `in:file` / `in:path` | 搜文件内容 / 文件路径 |
+
+### 社区站内搜（统一走 Exa）
+```
+query: "site:linux.do <报错原文或方案关键词>"
+query: "site:v2ex.com <库名或面板名> 坑"
+query: "site:nodeseek.com <主题>"
+```
 
 ---
 
 ## 一、Exa —— 找方案（语义检索）
 
-Exa 找的是"哪篇文档/项目/帖子讲过这件事"，不是关键词匹配。提问要描述**理想页面长什么样**，不要堆关键词。
+### 硬规则（写死，别记错）
 
+| 项 | 值 |
+|---|---|
+| 工具名 | `web_search_exa`、`web_fetch_exa`（MCP 服务器名 `EXA`） |
+| `web_search_exa` 必填 | `query` + `objective`，**两个都是必填** |
+| `objective` 长度上限 | **4096 字符** |
+| `numResults` | 选填，**默认 10** |
+| `web_fetch_exa` 必填 | `urls`（**数组**，可一次批量多个） |
+| `maxCharacters` | 选填，**默认 3000**（每页） |
+| 查询写法 | **描述"理想页面长什么样"，不是堆关键词** |
+| 分类过滤 | 在 `query` 里拼 `category:people` / `category:company`（只有这两类） |
+
+### 三种用法
+
+**1. 找同类实现**
 ```bash
-# 工具：web_search_exa（2 个必填参数）
 minis-mcp-cli call EXA web_search_exa '{
-  "query": "blog post explaining how Xboard staff middleware validates auth_data JWT and where the array parameter injection happens",
-  "objective": "找到讲透这个鉴权中间件实现的分析文章，优先中文安全博客和 GitHub issue，排除泛泛的框架介绍",
-  "numResults": 8
+  "query": "open source project implementing WebSocket reconnect with exponential backoff in Go, repository with design doc",
+  "objective": "找到可直接读源码的仓库，优先 star 数高且在维护的，排除教程和营销页"
 }'
+```
 
-# 读到好页面就全文抓（可批量）
+**2. 找踩坑记录**（报错原文直接当 query）
+```bash
+minis-mcp-cli call EXA web_search_exa '{
+  "query": "blog post or GitHub issue about \"Docker error: port is already allocated\" root cause and fix",
+  "objective": "拿到具体成因和可复现的修复步骤，排除只说\"重启就行\"的回答"
+}'
+```
+
+**3. 找协议/规范**
+```bash
+minis-mcp-cli call EXA web_search_exa '{
+  "query": "official RFC spec for HTTP/2 server push frame layout and flow control",
+  "objective": "拿到权威定义原文，排除二手解读"
+}'
+```
+
+### 读完再抓全文
+```bash
 minis-mcp-cli call EXA web_fetch_exa '{
-  "urls": ["https://example.com/post", "https://github.com/org/repo/issues/123"],
+  "urls": [
+    "https://github.com/org/repo/issues/123",
+    "https://example.com/deep-dive-post"
+  ],
   "maxCharacters": 6000
 }'
 ```
 
-**Exa 的三个用法**：
-1. **找同类实现**：`"open source project implementing <功能> in <语言>"` → 拿仓库和设计文档
-2. **找踩坑记录**：`"<库名> <报错原文>"` → 拿 issue / Stack Overflow / 博客
-3. **找协议/规范**：`"RFC / spec for <协议名>"` → 拿权威定义，别信二手
-
-**Exa 的局限**：语义检索会给"看起来相关"的结果，具体 API 签名、版本差异经常不准 → **必须用 Context7 核对**。
+### Exa 的边界（这是判断，不是官方说明）
+语义检索会给"看起来相关"的结果；**具体 API 签名、版本差异、参数默认值经常不准** → 涉及这些必须用 Context7 或源码核对。
 
 ---
 
 ## 二、Context7 —— 核事实（库/框架官方文档，免 key）
 
-Context7 直接给**当前版本**的官方文档和可运行代码示例，专治"Exa 搜到的博客用的是旧 API"。
-
-**两步调用，顺序不能反**：
+### 硬规则（写死，别记错）
 
+| 项 | 值 |
+|---|---|
+| 工具名 | `resolve-library-id`、`query-docs`（服务器名 `Context7`） |
+| **调用顺序** | **必须先 `resolve-library-id` 拿到库 ID，再 `query-docs`**；除非用户已给 `/org/project` 形态 ID |
+| `resolve-library-id` 必填 | `query` + `libraryName` |
+| `query-docs` 必填 | `libraryId` + `query`；`language` 选填 |
+| 每个问题调用上限 | **各 3 次**（官方明写 "Do not call this tool more than 3 times per question"），超了就用最好的结果 |
+| 库 ID 形态 | `/org/project`，带版本写 `/org/project/version`（如 `/laravel/docs/13.x`） |
+| **敏感信息禁令** | **query 里禁止放 API key、密码、凭据、个人数据、专有代码**——query 会发给 Context7 服务端 |
+| `language` 取值 | 语言名原文（`Python` / `TypeScript` / `Go` / `C#`），知道就传，示例会优先按该语言排序 |
+| 结果可靠性 | 返回带 `Source:` 官方文档源码链接，可点开溯源 |
+
+### 两步调用
+
+**第 1 步：库名 → 库 ID**
 ```bash
-# 第 1 步：库名 → Context7 库 ID
 minis-mcp-cli call Context7 resolve-library-id '{
   "libraryName": "Laravel",
-  "query": "how to read request input and build authorization context in middleware"
+  "query": "middleware reading request input to build auth context"
 }'
-# 返回形如 /laravel/docs 或 /laravel/framework/v11.x
+```
+返回每条含：`library ID` · `Description` · `Code Snippets`（示例数）· `Source Reputation`（High/Medium/Low）· `Benchmark Score`（100 满分）· `Versions`。
+
+**选哪个 ID**：名字对得上的前提下，看 **Code Snippets 多 + Reputation High + Benchmark 高**。官方站（`/laravel/docs`）和社区镜像（`/websites/laravel_8_x`）会同时出现，镜像的 Benchmark 有时更高——**版本对不上就用带版本号的官方 ID**。
 
-# 第 2 步：用库 ID 查具体问题（一次只问一个概念）
+**第 2 步：查具体问题**
+```bash
 minis-mcp-cli call Context7 query-docs '{
   "libraryId": "/laravel/docs",
-  "query": "middleware reading request input array and merging into auth context",
+  "query": "how to get request input array in middleware",
   "language": "PHP"
 }'
 ```
+实测返回形如：
+```
+### Input methods and source precedence (`input`, `all`, `query`, JSON)
+Source: https://github.com/laravel/docs/blob/13.x/requests.md
+`input()` retrieves from the entire request payload (body + query string + JSON body)...
+```
+
+### 查询粒度（硬要求）
+**一次只问一个概念**。官方原话：跨度多个概念时分多次调用，除非问的就是"它们怎么交互"。
 
-**规则**：
-- 每次问题**只问一个概念**，别把"路由+鉴权+缓存"堆进一个 query
-- 知道语言就传 `language`，示例会优先给对应语言的
-- 每个问题最多调 3 次，3 次没结果就用最好的那个结果，别死磕
-- 用户直接给了 `/org/project` 格式的 ID 时，跳过第 1 步
+| 差 | 好 |
+|---|---|
+| `auth` | `How to set up JWT authentication in Express.js` |
+| `hooks` | `React useEffect cleanup function examples` |
+| `routing and auth and caching` | 拆三次问 |
 
-**Context7 覆盖**：主流开源库和框架（Laravel、React、Next.js、FastAPI、Spring、Gin 等）。**不覆盖**：小众魔改面板、闭源商业系统、野路子脚本 → 这些回退到 Exa + GitHub。
+### Context7 的边界（判断，非官方）
+覆盖主流开源库/框架的文档站（Laravel、React、Next.js、FastAPI、Spring、Gin 等）。小众魔改面板、闭源商业系统、野路子脚本一般搜不到 → 回退**源码 + Exa + GitHub**。
 
 ---
 
 ## 三、补充来源（Exa/Context7 覆盖不到时）
 
-| 来源 | 用法 | 命令 |
+| 来源 | 硬规则 | 命令 |
 |---|---|---|
-| **GitHub 代码** | 搜真实实现，不只看 README | `curl -sL 'https://api.github.com/search/code?q=<query>' -H "Authorization: Bearer $GITHUB_TOKEN"` |
-| **GitHub issue** | 搜报错原文，看别人怎么解 | `curl -sL 'https://api.github.com/search/issues?q=<关键词>'` |
-| **Linux.do** | 中文实战踩坑、面板/机场/VPS 一手经验 | Exa 加 `site:linux.do` 或直接站内搜 |
-| **V2EX** | 老帖里的方案对比、历史版本坑 | `site:v2ex.com` |
-| **NodeSeek** | 主机/网络/面板实操记录 | `site:nodeseek.com` |
+| **GitHub 代码搜索** | **必须带 token，匿名直接 401**；配额 **10 次/分钟**（`x-ratelimit-resource: code_search`） | `curl -sL "https://api.github.com/search/code?q=<符号>+language:<语言>" -H "Authorization: Bearer $GITHUB_TOKEN"` |
+| **GitHub issue/仓库搜索** | 匿名可用（限流更松），带 token 更稳 | `curl -sL "https://api.github.com/search/issues?q=<报错原文>"` |
+| **原始文件直读** | raw.githubusercontent.com 匿名可读 | `curl -sL https://raw.githubusercontent.com/<org>/<repo>/<branch>/<path>` |
+| **Linux.do** | 中文实战踩坑一手经验 | Exa query 里加 `site:linux.do` |
+| **V2EX** | 历史方案对比、版本坑 | `site:v2ex.com` |
+| **NodeSeek** | 主机/网络/面板实操 | `site:nodeseek.com` |
 
-GitHub 代码搜索要 token（本机已有 `$GITHUB_TOKEN`）；匿名只给 10 次/分钟。
+**GitHub 代码搜索语法要点**：`in:file` · `path:` · `language:` · `org:` · `repo:`；搜字符串带引号 `"literal"`。
 
 ---
 
 ## 四、交叉判定（硬要求）
 
-**同一结论至少两个独立来源对上才采信。**
+**同一结论至少两个独立来源对上才采信**（这条不因提速而放弃——省钱省时间，但不省准确性）。
 
 ```
-Exa 找到"这么做"→ Context7 确认 API 签名和版本 → 对不上就以 Context7 为准
-Context7 说"新版这么写"→ GitHub 找实际项目验证 → 全是旧写法说明这版没落地
-GitHub 看到某写法 → 社区搜有没有人踩坑 → 有坑就记下来
+Exa 说"这么做" → Context7 核 API 签名和版本 → 对不上以 Context7 为准
+Context7 说"新版这么写" → GitHub 找实际项目验证 → 全是旧写法说明这版没落地
+GitHub 看到某写法 → 社区搜有没有人踩坑 → 有坑就记进 learned.md
+源码和文档冲突 → 以源码为准，记下版本号
 ```
 
-**判死条件**：四路都查过、结论互相矛盾且无法收敛 → 明确写"该点未确认，按 A 方案试，失败转 B"，**不许编一个看起来合理的答案**。
+**判死条件**：四路都查过、结论互相矛盾且无法收敛 → 明确写「该点未确认，按 A 方案试，失败转 B」，**不许编一个看起来合理的答案**。
 
 ---
 
@@ -101,38 +253,57 @@ GitHub 看到某写法 → 社区搜有没有人踩坑 → 有坑就记下来
 | 没见过的框架/面板/CMS | 是 |
 | 没见过的协议/加密/序列化格式 | 是 |
 | 没写过的语言/库的核心 API | 是 |
-| 报错看不懂 | 是（先查报错原文） |
-| 有成熟脚本能改 | 否，直接改（但先读它怎么实现的） |
-| 纯标准库/已用过十次以上 | 否 |
+| 报错看不懂 | 是（先把报错原文当 query） |
+| 有成熟脚本能改 | 否，直接改（但先读懂它怎么实现的） |
+| 纯标准库、已用过十次以上 | 否 |
 
 ---
 
 ## 六、反面清单（做了就是违规）
 
-- 凭"我记得应该是这样"直接写代码，一次搜索都不做
+- 凭"我记得应该是这样"直接写，一次搜索都不做
 - 只查一个来源就下结论
+- Exa 搜到旧版 API 直接照抄，不用 Context7 核版本
+- Context7 的 query 里塞了目标密码、API key、专有代码
+- 一个 query 里堆三个概念，然后抱怨搜不准
+- 反复调 Context7 超过 3 次还在试
 - 抄了代码但没读懂它在解决什么问题
-- Exa 搜到旧版 API 直接照抄，不用 Context7 核对版本
 - 查不到就编一个能跑但语义错的实现
 - 把搜索结果里的示例代码直接 `curl | bash`
 
 ---
 
-## 七、一条命令查完（快速模板）
+## 七、模板（按级别取用，别全抄）
+
+### 最小路径：知道 repo/path（3 秒）
+```bash
+curl -sL https://raw.githubusercontent.com/<org>/<repo>/<branch>/<path>
+```
 
+### 知道库名，要准确 API（19 秒）
 ```bash
-# 1) Exa 找方案
-minis-mcp-cli call EXA web_search_exa "{\"query\":\"<理想页面描述>\",\"objective\":\"<要拿到什么事实>\",\"numResults\":6}"
+minis-mcp-cli call Context7 resolve-library-id '{"libraryName":"<官方库名>","query":"<要解决什么>"}'
+minis-mcp-cli call Context7 query-docs '{"libraryId":"<上一步ID>","query":"<单一概念>","language":"<语言>"}'
+```
 
-# 2) Context7 核 API
-minis-mcp-cli call Context7 resolve-library-id "{\"libraryName\":\"<库名>\",\"query\":\"<要解决什么>\"}"
-minis-mcp-cli call Context7 query-docs "{\"libraryId\":\"<上一步的ID>\",\"query\":\"<单一概念>\"}"
+### 不知道去哪找（25 秒，一次搜索就够）
+```bash
+minis-mcp-cli call EXA web_search_exa '{"query":"<理想页面描述>","objective":"<要什么事实，排除什么>","numResults":6}'
+# 拿到 URL 后回 L0 直抓，不要再搜第二次
+curl -sL <搜到的 raw 或文档页 URL>
+```
 
-# 3) GitHub 验真实用法
-curl -sL "https://api.github.com/search/code?q=<符号名>+language:<语言>" -H "Authorization: Bearer $GITHUB_TOKEN" | jq -r '.items[]|.repository.full_name+" "+.path' | head
+### 要真实实现（2–3 秒，必须带 token）
+```bash
+curl -sL "https://api.github.com/search/code?q=<符号>+language:<语言>" \
+  -H "Authorization: Bearer $GITHUB_TOKEN" | jq -r '.items[]|.repository.full_name+" "+.path' | head
+```
 
-# 4) 社区验坑
-minis-mcp-cli call EXA web_search_exa "{\"query\":\"site:linux.do <报错或方案>\",\"objective\":\"看有没有人踩过坑\",\"numResults\":5}"
+### 要中文踩坑（25 秒，最后才用）
+```bash
+minis-mcp-cli call EXA web_search_exa '{"query":"site:linux.do <报错原文>","objective":"看有没有人踩过坑及解法","numResults":5}'
 ```
 
-四步做完再动手。**越不熟，越要交叉。**
+---
+
+**一句话**：先直连，再 Context7，然后 Exa，GitHub 补真实代码，社区最后。**两源对上才算数，但不必要四源全开。**