fast-context

Fast Context

概述

将 Fast Context 用作代码库相关工作的第一步：定位实现路径、追踪流程、查找测试，并在编写代码或提供项目特定建议前收集所需的完整定义。

此技能会直接从已安装的技能目录运行 scripts/fast-context-search.mjs。该脚本使用来自上游 v1.3.0-beta.2 源码的 Fast Context 核心逻辑，以及 Windsurf Devstral，但不要求安装或启用 Fast Context MCP 服务。它不能替代精确的本地检查；请使用返回的文件路径和 grep 关键词，通过 rg、sed 和文件读取进行有针对性的检查。

适用场景

• 在进行代码更改、架构建议、错误修复、测试计划或解释之前，尤其是这些工作依赖项目特定行为时。
• 不清楚相关文件的位置，或功能涉及多个模块时。
• 需要完整定义、签名、调用点、配置、路由、架构或测试时。

纯对话任务、对已知小文件的微小修改，或查阅第三方库文档时，请跳过此技能。需要最新外部 API 文档时，请使用 Context7 等文档检索技能。

工作流

1. 编写一个自然语言查询，说明用户目标，并询问所需的确切上下文。优先使用“在哪里”“是什么”和“如何”等问句。
2. 确定已安装的技能目录，并运行 node <skill-directory>/scripts/fast-context-search.mjs，将 --project 设为项目根目录的绝对路径，将 --query 设为自然语言搜索查询。
3. 阅读返回的文件范围，并使用建议的 grep 关键词，通过本地工具检查精确的定义。
4. 检查完整性：确保已识别所有相关的类、函数、变量、类型、配置、路由、调用点和测试，并获取其完整签名。
5. 如果缺少任何内容，请针对缺失的概念、符号或流程再次递归查询 Fast Context。
6. 如果检索后仍有歧义，请在更改行为前向用户提出引导性问题。

默认命令

node /path/to/installed/fast-context/scripts/fast-context-search.mjs \
  --project "/absolute/path/to/project" \
  --query "Where is <feature or behavior> implemented, and what full definitions, signatures, call sites, config, and tests are relevant to <user goal>?" \
  --max-results 10 \
  --max-turns 3 \
  --tree-depth 0 \
  --exclude ".git,node_modules,dist,build,coverage"

聚焦查找符号时，将 max_results 设为 3-5；追踪功能时设为 10-20；广泛探索时设为 20-30。快速查找时，将 max_turns 设为 1；追踪复杂的跨模块流程时设为 4-5。

查询模式

• 定位实现：<功能> 在哪里实现？请包括入口点、核心函数/类、数据类型、配置和测试。
• 追踪流程：<用户操作或 API 调用> 如何从入口点经过代码库，直到持久化/输出？请包括完整定义和调用点。
• 准备更改：为了实现 <要求>，需要更改哪些代码？请查找当前行为、扩展点、验证逻辑、测试和相关风险。
• 查找测试：有哪些测试覆盖 <行为>，应在哪里添加新测试？请包括测试夹具和辅助函数。

参数调优与回退

• 如果结果过于浅显，请增加 max_turns 或 max_results，或改为查询范围更窄的符号或流程。
• 如果仓库映射过大，请减小 tree_depth、添加 exclude_paths，或使用 repo_map_mode: "bootstrap_hotspot"。
• 如果身份验证失败，请使用 --check-key 运行同一脚本，以验证本地 Windsurf 密钥查找情况；然后在登录 Windsurf 或设置 WINDSURF_API_KEY 后重试。
• 如果用户明确需要密钥，请使用 --print-key 在本地打印，或使用 --key-env 打印适用于当前 shell 的 export WINDSURF_API_KEY=... 命令。请将输出视为机密。
• 如果缺少 Node 依赖，请在已安装的 Fast Context 技能目录中运行 npm install。
• 如果脚本不可用或仍然失败，请简要说明，并继续使用本地 rg --files、rg 和有针对性的文件读取。

参考

仅在需要时，阅读 references/script-contract.md，了解脚本参数的精确约定、响应格式和调优说明。