# 上下文模式：所有大输出的默认值 ## 强制规则所有命令默认为上下文模式。仅将 Bash 用于保证小输出的操作。 Bash白名单（可以安全直接运行）： * **文件突变** : `mkdir`, `mv`, `cp`, `rm`, `touch`, `chmod` * **Git 写入** : `git add`, `git commit`, `git push`, `git checkout`, `gitbranch`, `git merge` * **导航**：`cd`、`pwd`、`which` * **进程控制** : `kill`, `pkill` * **包管理** : `npm install`, `npmpublish`, `pip install` * **简单输出** : `echo`, `printf` **其他所有内容 →`ctx_execute` 或 `ctx_execute_file`。** 任何读取、查询、获取、列表、日志、测试、构建、比较、检查或调用外部服务的命令。这包括所有 CLI（gh、aws、kubectl、docker、terraform、wrangler、fly、heroku、gcloud 等）——有数千个，我们无法全部列出。 **当不确定时，使用上下文模式。** 每 KB 不必要的上下文都会降低整个会话的质量和速度。 ## 决策树想要运行命令/读取文件/调用 API？ │ ├── 命令在 Bash 白名单上（文件突变、git 写入、导航、echo）？ │ └── 使用 Bash │ ├── 输出可能很大或者您不确定？ │ └── 使用上下文模式 ctx_execute 或 ctx_execute_file │ ├── 获取网页文档或 HTML 页面？ │ └── 使用ctx_fetch_and_index → ctx_search │ ├── 使用Playwright（导航、快照、控制台、网络）？ │ └── 始终使用文件名参数保存到文件，然后： │ browser_snapshot(文件名) → ctx_index(路径) 或 ctx_execute_file(路径) │ browser_console_messages(文件名) → ctx_execute_file(路径) │ browser_network_requests(文件名) → ctx_execute_file(路径) │ ⚠ browser_navigate 自动返回快照——忽略它， │ 使用 browser_snapshot(filename) 进行任何检查。 │ ⚠ Playwright MCP 使用单个浏览器实例 — 不是并行安全的。 │ 对于并行浏览器操作，请通过执行来使用代理浏览器。 │ ├── 使用代理浏览器（并行安全浏览器自动化）？ │ └── 通过execute (shell)运行——每个调用都有自己的子进程： │execute("代理浏览器打开 example.com && 代理浏览器快照 -i -c") │ ✓ 支持隔离浏览器实例的会话 │ ✓ 并行子代理执行安全 │ ✓ 具有基于引用的交互的轻量级可访问性树 │ ├── 处理另一个 MCP 工具（Context7、GitHub API 等）的输出？ │ ├── 输出已经在先前工具调用的上下文中？ │ │ └── 直接使用。不要使用 ctx_index(content: ...) 重新索引。 │ ├── 需要多次搜索输出？ │ │ └── 通过ctx_execute保存到文件，然后ctx_index(path) → ctx_search │ └── 一击解救？ │ └── 通过ctx_execute保存到文件，然后ctx_execute_file(path) │ └── 读取文件进行分析/总结（而不是编辑）？ └── 使用ctx_execute_file（文件加载到FILE_CONTENT，而不是上下文） ## 何时使用每种工具情况|工具|示例 ---|---|--- 命中 API 端点 | `ctx_execute` | `fetch('http://localhost:3000/api/orders')` 运行返回数据的 CLI | `ctx_execute` | `gh pr list`、`aws s3 ls`、`kubectl get pods` 运行测试 | `ctx_execute` | `npm test`、`pytest`、`go test ./...` Git 操作 | `ctx_execute` | `git log --oneline -50`, `git diff HEAD~5` Docker/K8s 检查 | `ctx_execute` | `docker stats --no-stream`、`kubectl 描述 pod` 读取日志文件 | `ctx_execute_file` |解析 access.log、error.log、构建输出读取数据文件 | `ctx_execute_file` |分析 CSV、JSON、YAML、XML 阅读源码分析| `ctx_execute_file` |计算函数、查找模式、提取指标获取网络文档 | `ctx_fetch_and_index` |索引 React/Next.js/Zod 文档，然后搜索剧作家快照| `browser_snapshot(文件名)` → `ctx_index(路径)` → `ctx_search` |保存到文件、索引服务器端、查询剧作家快照（单镜头）| `browser_snapshot(文件名)` → `ctx_execute_file(路径)` |保存到文件，在沙箱中提取剧作家控制台/网络| `browser_*(文件名)` → `ctx_execute_file(路径)` |保存到文件，在沙箱中分析 MCP 输出（已在上下文中）|直接使用|不要重新索引——它已经加载了 MCP输出（需要多查询） | `ctx_execute` 保存 → `ctx_index(path)` → `ctx_search` |先保存到文件，索引服务器端 ## 自动触发器无需询问即可对其中任何一个使用上下文模式： * **API 调试** ：“命中此端点”、“调用 API”、“检查响应”、“查找响应中的错误” * **日志分析** ：“检查日志”、“有什么错误”、“读取access.log”、“调试500s” * **测试运行** ：“运行测试”，“检查测试是否通过”，“测试套件输出” * **Git 历史记录** ：“显示最近的提交”、“git 日志”、“更改内容”、“分支之间的差异” * **数据检查** ：“查看 CSV”、“解析 JSON”、“分析配置” * **基础设施**：“列出容器”、“检查 Pod”、“S3 存储桶”、“显示正在运行的服务” * **依赖审计** ：“检查依赖关系”、“过时的包”、“安全审计” * **构建输出**：“构建项目”，“检查警告”，“编译错误” * **代码指标** ：“计数行数”、“查找 TODO”、“函数计数”、“分析代码库” * **Web 文档查找** ：“查找文档”、“检查 API 参考”、“查找示例” ## 语言选择情况|语言 |为什么 ---|---|--- HTTP/API 调用、JSON | `javascript` |本机获取、JSON.parse、异步/等待数据分析、CSV、统计 | `蟒蛇` | csv、统计、集合、重新带管道的 Shell 命令 | `壳` | grep、awk、jq、本机工具文件模式匹配 | `壳` |查找、厕所、排序、uniq ## 搜索查询策略 * BM25 使用**OR 语义** — 匹配更多术语的结果自动排名更高 * 每个查询使用 2-4 个特定技术术语 * **当多个文档被索引时，始终使用`source`参数**以避免跨源污染 * 部分匹配有效： `source: "Node"` 匹配 `"Node.js v22 CHANGELOG"` * **始终使用“查询”数组** — 在一次调用中批量处理所有搜索问题： * `ctx_search（查询：[“转换管道”，“精炼 superRefine”，“强制编解码器”]，来源：“Zod”）` * 切勿进行多个单独的 ctx_search() 调用 — 将所有查询放入一个数组中 ## 外部文档 * **始终对外部文档使用 `ctx_fetch_and_index`** — 切勿将 `cat` 或 `ctx_execute` 与您不拥有的包的本地路径一起使用 * 对于 GitHub 托管的项目，请使用原始 URL：`https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md` * 建立索引后，在搜索中使用“source”参数将结果范围限定到该特定文档 ## 关键规则 1. **始终console.log/打印您的发现。** stdout 是进入上下文的所有内容。没有输出 = 浪费调用。 2. **编写分析代码，而不仅仅是数据转储。** 不要 `console.log(JSON.stringify(data))` — 首先分析，打印结果。 3. **输出要具体。** 使用 ID、行号、精确值打印 bug 详细信息，而不仅仅是计数。 4. **对于需要编辑的文件**：使用普通的读取工具。上下文模式用于分析，而不是编辑。 5. **仅适用于 Bash 白名单命令** ：使用 Bash 进行文件突变、git 写入、导航、流程控制、包安装和回显。其他一切都通过上下文模式。 6. **永远不要使用`ctx_index(content: large_data)`。**使用`ctx_index(path: ...)`在服务器端读取文件。 “content”参数通过上下文作为工具参数发送数据 - 仅将其用于小型内联文本。 7. **始终在 Playwright 工具上使用“文件名”参数**（“browser_snapshot”、“browser_console_messages”、“browser_network_requests”）。如果没有它，完整的输出就会进入上下文。 8. **不要重新索引上下文中已有的数据。** 如果 MCP 工具在先前的响应中返回数据，则该数据已加载 - 直接使用它或先保存到文件。 ## 沙盒数据工作流程 <沙盒数据工作流程> <关键规则> 使用支持保存到文件的工具时：始终使用“文件名”参数。切勿将大型原始数据集直接返回到上下文。 LargeDataTool(文件名：“路径”) → mcp__context-mode__ctx_index(路径：“路径”) → ctx_search() 无论源工具（Playwright、GitHub API、AWS CLI 等）如何，这都是上下文保存的通用模式。 ## 示例 ### 调试 API 端点 const resp = wait fetch('http://localhost:3000/api/orders'); const { 订单 } = 等待 resp.json(); 常量错误= []； const negQty = orders.filter(o => o.quantity < 0); if (negQty.length) bugs.push(`负数量: ${negQty.map(o => o.id).join(', ')}`); const nullFields = orders.filter(o => !o.product || !o.customer); if (nullFields.length) bugs.push(`空字段：${nullFields.map(o => o.id).join(', ')}`); console.log(`${orders.length} 订单，${bugs.length} 发现错误:`); bugs.forEach(b => console.log(`- ${b}`)); ### 分析测试输出 npm 测试 2>&1 回显“退出=$？” ### 检查 GitHub PR gh pr list --json 编号、标题、状态、reviewDecision --jq '.[] | "\(.number) [\(.state)] \(.title) — \(.reviewDecision // "无审核")"' ### 读取并分析大文件 # FILE_CONTENT 由 ctx_execute_file 预加载导入 json 数据 = json.loads(FILE_CONTENT) print(f"记录: {len(data)}") # ...分析并打印结果 ## 浏览器和剧作家集成 **当任务涉及剧作家快照、屏幕截图或页面检查时，始终通过文件 → 沙箱进行路由。** Playwright `browser_snapshot` 返回 10K–135K 的可访问性树数据标记。在没有“文件名”的情况下调用它会将所有内容转储到上下文中。将输出传递给“ctx_index(content: ...)”将其作为参数第二次发送到上下文中。两者都是错误的。 **关键见解**：“browser_snapshot”有一个“filename”参数，该参数保存到文件而不是返回到上下文。 `ctx_index` 有一个 `path` 参数，用于读取服务器端的文件。 `ctx_execute_file` 处理沙箱中的文件。 **这些都不是触摸上下文。** ### 工作流程A：快照→文件→索引→搜索（多个查询）步骤1：browser_snapshot（文件名：“/tmp/playwright-snapshot.md”） → 保存到文件，返回约 50B 确认（不是 135K 代币）步骤2：ctx_index（路径：“/tmp/playwright-snapshot.md”，来源：“Playwright快照”） → 读取文件服务器端，索引到 FTS5，返回 ~80B 确认步骤3：ctx_search（查询：[“登录表单电子邮件密码”]，来源：“Playwright”） → 仅返回匹配的块 (~300B) **总上下文：~430B** 而不是 270K 令牌。真正节省 99%。 ### 工作流程B：快照→文件→执行文件（一次性提取）步骤1：browser_snapshot（文件名：“/tmp/playwright-snapshot.md”） → 保存到文件，返回 ~50B 确认步骤2：ctx_execute_file(路径：“/tmp/playwright-snapshot.md”，语言：“javascript”，代码：“ const links = [...FILE_CONTENT.matchAll(/- link \"([^\"]+)\"/g)].map(m => m[1]); const 按钮 = [...FILE_CONTENT.matchAll(/- 按钮 \"([^\"]+)\"/g)].map(m => m[1]); const 输入 = [...FILE_CONTENT.matchAll(/- 文本框|- 复选框|- radio/g)]; console.log('链接：'，links.length，'| 按钮：'，buttons.length，'| 输入：'，inputs.length); console.log('导航：', links.slice(0, 10).join(', ')); ”） → 在沙箱中处理，返回~200B 摘要 **总上下文：~250B** 而不是 135K 令牌。 ### 工作流程 C：控制台和网络（如果较大，则保存到文件） browser_console_messages（级别：“错误”，文件名：“/tmp/console.md”） → ctx_execute_file(路径: "/tmp/console.md", ...) 或 ctx_index(路径: "/tmp/console.md", ...) browser_network_requests（includeStatic：false，文件名：“/tmp/network.md”） → ctx_execute_file(路径: "/tmp/network.md", ...) 或 ctx_index(路径: "/tmp/network.md", ...) ### 关键：为什么 `filename` \+ `path` 是必需的方法|上下文成本|正确的？ ---|---|--- `browser_snapshot()` → 原始上下文 | **135K 代币** |否 `browser_snapshot()` → `ctx_index(内容：原始)` | **270K 代币**（双倍！） |否 `browser_snapshot(文件名)` → `ctx_index(路径)` → `ctx_search` | **~430B** |是的 `browser_snapshot(文件名)` → `ctx_execute_file(路径)` | **~250B** |是的 ### 关键规则 > **在调用 `browser_snapshot`、`browser_console_messages` 或 `browser_network_requests` 时始终使用 `filename` 参数。** 然后通过 `ctx_index(path: ...)` 或 `ctx_execute_file(path: ...)` 进行处理 — 切勿通过 `ctx_index(content: ...)` 进行处理。 > > 数据流向：**编剧→文件→服务器端读取→上下文**。从不：**剧作家→上下文→ctx_index（内容）→再次上下文**。 ## 子代理的使用子代理通过 PreToolUse 挂钩自动接收上下文模式工具路由。您不需要手动将工具名称添加到子代理提示中 - 挂钩会注入它们。只需编写自然的任务描述即可。 ## 反模式 * 通过 Bash 使用 `curl http://api/endpoint` → 50KB 洪水上下文。将 `ctx_execute` 与 fetch 结合使用。 * 通过 Bash 使用 `cat large-file.json` → 上下文中的整个文件。请改用“ctx_execute_file”。 * 通过 Bash 使用 `gh pr list` → 在上下文中使用原始 JSON。请使用带有“--jq”过滤器的“ctx_execute”。 * 通过 `| 管道传输 Bash 输出头-20`→你失去了剩下的。使用“ctx_execute”分析所有数据并打印摘要。 * 通过 Bash 运行 `npm test` → 上下文中的完整测试输出。使用 ctx_execute 来捕获和总结。 * 调用“browser_snapshot()”而不使用“filename”参数 → 135K 令牌淹没上下文。 **始终**使用`browser_snapshot（文件名：“/tmp/snap.md”）`。 * 调用“browser_console_messages()”或“browser_network_requests()”而不使用“filename” → 整个输出会淹没上下文。 **始终**使用“文件名”参数。 * 将任何大数据传递给 `ctx_index(content: ...)` → 数据作为参数进入上下文。 **始终**使用 `ctx_index(path: ...)` 读取服务器端。 `content` 参数只能用于您自己编写的小型内联文本。 * 调用 MCP 工具（Context7 `query-docs`、GitHub API 等），然后将响应传递给 `ctx_index(content: response)` → **双倍**上下文使用。响应已经在上下文中 - 直接使用它或先保存到文件。 * 忽略 `browser_navigate` 自动快照 → 导航响应包括完整页面快照。不要依赖它进行检查 - 单独调用“browser_snapshot(filename)”。 ## 参考文件 * [JavaScript/TypeScript 模式]() * [Python 模式]() * [Shell 模式]() * [反模式和常见错误]()

上下文模式

包含技能