fast-context-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,12 @@
+# Notice
+
+本项目是 `fast-context-mcp` 的 Skill + CLI 形态适配。
+
+- 母项目本地路径：`/Users/awei84/开源项目/fast-context-mcp`
+- 母项目 package 版本：`1.4.2`
+- 本次搬运来源 commit：`e7af092c53ed92a77b47c4a88dd51ea471a0e081`
+- 母项目 license：MIT
+
+本包不使用 MCP server wrapper。运行时入口是 `src/cli.mjs`，它直接调用 `src/core.mjs` 暴露的 `searchWithContent()` 和 `extractKeyInfo()`。
+
+当前仓库保留 vendored core 形态。后续若两个仓库继续并行演进，建议把协议和搜索核心抽成共享 npm 包，避免 `core.mjs`、`executor.mjs`、`directory-scorer.mjs` 长期漂移。

package/README.md

@@ -0,0 +1,172 @@
+# fast-context-skill
+
+Fast Context 的 Skill + CLI 形态：面向 Claude / agent 工作流的 AI 驱动语义代码搜索工具。
+
+本项目复用 [`fast-context-mcp`](https://github.com/awei84/fast-context-mcp) 的 Node.js 核心代码，只新增一层 CLI 和 `SKILL.md`。它不是 Python 重写版，也不会引入本地语义搜索兜底。
+
+## 什么时候用
+
+- 需要给 Claude Desktop、Claude Code、Cursor 或其他 MCP 客户端接入 MCP server 时，用 `fast-context-mcp`。
+- 需要一个 Skill 友好的 CLI，让 agent 通过 `npx` 调用时，用 `fast-context-skill`。
+
+两种形态复用同一套 Windsurf SWE-grep 协议和内置本地工具。
+
+## 环境要求
+
+- Node.js >= 18
+- Windsurf 账号 / 本机 Windsurf 登录状态，或手动设置 `WINDSURF_API_KEY`
+
+不需要系统安装 `rg` 或 `tree`。`ripgrep` 通过 `@vscode/ripgrep` 内置，目录树输出使用 `tree-node-cli`。
+
+## 使用方式
+
+运行语义代码搜索：
+
+```bash
+npx -y fast-context-skill search \
+  --query "where is authentication handled" \
+  --project /absolute/path/to/project
+```
+
+也兼容同类 Skill 的顶层参数形式：
+
+```bash
+npx -y fast-context-skill \
+  --query "where is authentication handled" \
+  --project /absolute/path/to/project
+```
+
+本仓库本地开发时：
+
+```bash
+node src/cli.mjs search \
+  --query "where is authentication handled" \
+  --project /absolute/path/to/project
+```
+
+从本机 Windsurf 安装中提取 API Key：
+
+```bash
+npx -y fast-context-skill extract-key
+```
+
+## CLI
+
+### `search`
+
+```bash
+fast-context-skill search --query <text> --project <absolute-path> [options]
+```
+
+参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--query`, `-q` | 必填 | 自然语言搜索问题 |
+| `--project`, `-p` | 必填 | 项目根目录；相对路径会先转成绝对路径再校验 |
+| `--tree-depth` | `3` | repo map 深度，`0-6`；大仓库建议调低 |
+| `--max-turns` | `FC_MAX_TURNS` 或 `3` | 搜索轮数，`1-5` |
+| `--max-results` | `10` | 最大返回文件数，`1-30` |
+| `--max-commands` | `FC_MAX_COMMANDS` 或 `8` | 每轮最大本地命令数 |
+| `--timeout-ms` | `FC_TIMEOUT_MS` 或 `30000` | 请求超时时间，单位毫秒 |
+| `--exclude` | 无 | 排除路径或 glob；可重复，也支持逗号分隔；逗号会被当作分隔符 |
+| `--include-code-snippets` | `FC_INCLUDE_SNIPPETS` 或 `false` | 输出中附带代码片段 |
+| `--json` | `false` | 用 JSON 包装输出 |
+| `--progress` | `false` | 将进度日志输出到 stderr |
+| `--check-key` | `false` | 验证 Windsurf API Key 自动发现，只输出脱敏值 |
+| `--print-key` | `false` | 输出完整 Windsurf API Key，仅限本机排查使用 |
+| `--key-env` | `false` | 输出 `export WINDSURF_API_KEY=...` 命令 |
+| `--db-path` | 无 | 指定 Windsurf `state.vscdb` 路径，仅用于 key 命令 |
+
+输出包含相关文件路径、行号范围、供后续 `rg` 使用的 grep keywords，以及描述实际搜索配置的 `[config]` 行。
+
+### `extract-key`
+
+```bash
+fast-context-skill extract-key
+```
+
+读取本机 Windsurf SQLite 数据库，并打印可直接使用的 `WINDSURF_API_KEY` export 命令。
+
+也可以使用快捷 key 命令：
+
+```bash
+npx -y fast-context-skill --check-key
+npx -y fast-context-skill --print-key
+eval "$(npx -y fast-context-skill --key-env)"
+```
+
+`--print-key` 和 `--key-env` 会输出完整密钥，只应在用户本机排查时使用，不要写入日志、issue 或仓库文件。
+
+## Skill
+
+`SKILL.md` 会指导 agent 调用：
+
+```bash
+npx -y fast-context-skill search --query "..." --project /absolute/path/to/project
+```
+
+预期工作流：
+
+1. 用 Fast Context 找候选文件和 grep keywords。
+2. 用 `rg` 或直接读取文件核验候选结果。
+3. 基于具体 `path:line` 证据回答。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `WINDSURF_API_KEY` | auto-discover | Windsurf API key |
+| `FC_MAX_TURNS` | `3` | 每次查询的搜索轮数 |
+| `FC_MAX_COMMANDS` | `8` | 每轮最大并行本地命令数 |
+| `FC_TIMEOUT_MS` | `30000` | Connect 请求超时毫秒数 |
+| `FC_RESULT_MAX_LINES` | `50` | 单条命令输出最大行数 |
+| `FC_LINE_MAX_CHARS` | `250` | 单行输出最大字符数 |
+| `FC_INCLUDE_SNIPPETS` | `false` | 默认是否输出代码片段 |
+| `FC_REPO_MAP_MODE` | `bootstrap_hotspot` | repo map 策略：`bootstrap_hotspot` 或 `classic` |
+| `FC_BOOTSTRAP_ENABLED` | `true` | 是否启用 bootstrap hotspot 发现 |
+| `FC_BOOTSTRAP_TREE_DEPTH` | `1` | bootstrap 阶段目录树深度 |
+| `FC_BOOTSTRAP_MAX_TURNS` | `2` | bootstrap 阶段搜索轮数 |
+| `FC_BOOTSTRAP_MAX_COMMANDS` | `6` | bootstrap 阶段最大命令数 |
+| `FC_HOTSPOT_TOP_K` | `4` | 追加的热点目录数量 |
+| `FC_HOTSPOT_TREE_DEPTH` | `2` | 热点子树深度 |
+| `FC_HOTSPOT_MAX_BYTES` | `122880` | repo map 字节预算 |
+| `WS_MODEL` | `MODEL_SWE_1_6_FAST` | Windsurf model |
+| `WS_APP_VER` | `1.48.2` | Windsurf app version 元数据 |
+| `WS_LS_VER` | `1.9544.35` | Windsurf language server version 元数据 |
+
+## 项目结构
+
+```text
+fast-context-skill/
+├── src/
+│   ├── cli.mjs              # CLI 入口
+│   ├── config.mjs           # 运行时环境变量配置
+│   ├── core.mjs             # 从 fast-context-mcp 复用的协议/搜索核心
+│   ├── executor.mjs         # 本地 rg/readfile/tree/ls/glob 执行器
+│   ├── extract-key.mjs      # Windsurf API Key 提取
+│   ├── protobuf.mjs         # Connect-RPC/Protobuf 辅助函数
+│   ├── directory-scorer.mjs # repo map 热点目录评分
+│   └── project-path.mjs     # 项目路径校验
+├── SKILL.md
+├── NOTICE.md
+├── references/
+│   └── script-contract.md
+├── package.json
+└── README.md
+```
+
+## 开发
+
+```bash
+npm install
+npm test
+node src/cli.mjs --help
+```
+
+## 不做什么
+
+- 不做本地 `semble` 兜底。
+- 不走 Python 依赖路线。
+- 不替代 MCP 包；本项目只提供独立的 CLI + Skill 形态。
+- 不把多模型 fallback 作为首版目标；当前保留 `WS_MODEL` 单模型配置和现有请求重试。

package/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: fast-context-skill
+description: AI-driven semantic code search via Windsurf's Devstral SWE-grep protocol. Use to find where logic lives, how a flow works, which files matter for a bug or feature, or to orient in an unfamiliar repo before editing. 用于定位代码、理解业务链路与调用关系。已知精确标识符时先用 rg。
+when_to_use: |
+  Trigger on requests like "where is X implemented/handled", "how does this flow work", "which files relate to <feature/bug>", "理解一下这块逻辑", "这个功能在哪实现". Use when the exact symbol name is not yet known and you need a short list of candidate files before reading or editing. Skip it when the filename/symbol is already known (use rg) or for structural refactors (use ast-grep).
+argument-hint: "[query]"
+user-invocable: true
+allowed-tools: Bash
+---
+
+# Fast Context
+
+## 何时使用
+
+当需要探索代码库上下文、定位功能实现、理解跨模块调用链，或先用自然语言缩小候选文件时使用本技能。
+
+已知明确函数名、类名、变量名、路由、报错文本时，先用 `rg` 精确搜索；如果结果不足以理解上下文，再使用 Fast Context。
+
+## 工作流
+
+1. 使用 CLI 运行语义搜索。**优先用英文写 query**：底层模型的代码语料以英文为主，英文 query 与代码同语种，语义召回更准。中文也能用，但建议把关键名词换成英文（"用户登录鉴权" → "user login authentication"）。
+
+```bash
+npx -y fast-context-skill search --query "where is auth handled" --project /absolute/path/to/project
+```
+
+兼容形式：
+
+```bash
+npx -y fast-context-skill --query "where is auth handled" --project /absolute/path/to/project
+```
+
+2. 阅读输出中的文件路径、行号范围、`grep keywords` 和 `[config]`（见下方「输出示例」）。
+
+3. 必须用 `rg` 或文件读取核验 Fast Context 返回的候选结果，再基于具体 `path:line` 给结论。
+
+## 输出示例
+
+```text
+Found 3 relevant files.
+
+--- [1/3] /project/src/auth/handler.mjs (L10-60, L120-180) ---
+--- [2/3] /project/src/middleware/jwt.mjs (L1-40) ---
+--- [3/3] /project/src/models/user.mjs (L20-80) ---
+
+grep keywords: authenticate, jwt.*verify, session.*token
+
+[config] project_path=/project, tree_depth=3, tree_size=12.5KB, max_turns=3, max_results=10, timeout_ms=30000
+```
+
+把文件 + 行号当作起点，用 `grep keywords` 做二次精确搜索，再读文件核验。失败时输出会带 `Error:` 和 `[hint]`，按提示调小 `--tree-depth`/`--max-turns` 或缩小 `--project`。
+
+## 推荐参数
+
+query 尽量用英文短句描述要找的功能或代码路径。默认轻量模式：
+
+```bash
+npx -y fast-context-skill search \
+  --query "where is the user login session validated" \
+  --project /absolute/path/to/project \
+  --max-results 10 \
+  --max-turns 3 \
+  --tree-depth 3 \
+  --exclude node_modules,dist,build,coverage
+```
+
+大仓库或超时：
+
+```bash
+npx -y fast-context-skill search \
+  --query "where is the user login session validated" \
+  --project /absolute/path/to/project \
+  --max-results 8 \
+  --max-turns 2 \
+  --tree-depth 1 \
+  --exclude node_modules,dist,build,coverage,vendor
+```
+
+需要一次性获取代码片段：
+
+```bash
+npx -y fast-context-skill search \
+  --query "where is the user login session validated" \
+  --project /absolute/path/to/project \
+  --include-code-snippets
+```
+
+## API Key
+
+CLI 会优先读取 `WINDSURF_API_KEY`。未设置时，会尝试从本机 Windsurf 数据库自动读取。
+
+也可以手动提取：
+
+```bash
+npx -y fast-context-skill extract-key
+```
+
+常用 key 排查命令：
+
+```bash
+npx -y fast-context-skill --check-key
+npx -y fast-context-skill --print-key
+eval "$(npx -y fast-context-skill --key-env)"
+```
+
+`--print-key` 和 `--key-env` 会输出完整密钥，只能在用户本机排查时使用，不要写入日志或仓库文件。
+
+## 参考
+
+需要精确了解 CLI 参数契约和失败处理时，读取 `references/script-contract.md`。
+
+## 约束
+
+- 不要把 Fast Context 的结果直接当最终事实。
+- 最终回答必须回指到经过核验的具体文件位置。
+- 不要引入本地语义搜索 fallback；失败时返回真实错误，并按 `[hint]` 调小参数或缩小 `--project`。

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "fast-context-skill",
+  "version": "0.1.0",
+  "description": "Skill + CLI form of fast-context, powered by Windsurf SWE-grep protocol",
+  "type": "module",
+  "main": "src/cli.mjs",
+  "bin": {
+    "fast-context-skill": "src/cli.mjs",
+    "fast-cxt-skill": "src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "references/",
+    "SKILL.md",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@vscode/ripgrep": "^1.15.9",
+    "scule": "^1.3.0",
+    "sql.js": "^1.14.0",
+    "tree-node-cli": "^1.6.0",
+    "zod": "^3.23.0"
+  },
+  "license": "MIT"
+}

package/references/script-contract.md

@@ -0,0 +1,70 @@
+# Fast Context CLI Contract
+
+## 命令
+
+推荐使用子命令形态：
+
+```bash
+npx -y fast-context-skill search \
+  --project "/absolute/path/to/project" \
+  --query "Where is <feature> implemented?"
+```
+
+为了兼容同类 Skill，也支持顶层参数形态：
+
+```bash
+npx -y fast-context-skill \
+  --project "/absolute/path/to/project" \
+  --query "Where is <feature> implemented?"
+```
+
+CLI 会调用 `searchWithContent()`，通过 Windsurf Devstral 做远程语义搜索，并在本地执行受限的 `rg`、文件读取和目录树命令。
+
+## 常用参数
+
+- `--query`, `-q`：自然语言搜索问题。
+- `--project`, `--project-path`, `-p`：项目根目录。CLI 会解析为绝对路径并校验目录存在。
+- `--max-results`：最大返回文件数。聚焦查找用 3-5，功能链路用 10-20，宽泛探索用 20-30。
+- `--max-turns`：搜索轮数。快速定位用 1，默认 3，复杂跨模块链路可用 4-5。
+- `--max-commands`：每轮允许远程搜索循环请求的本地命令数。
+- `--tree-depth`：初始 repo map 深度。大仓库用 1-2，小仓库可用 4-6。
+- `--timeout-ms`：Devstral 请求超时。
+- `--exclude`：排除目录或文件模式，可重复，也可用逗号分隔。逗号会被当作分隔符，因此路径或 glob 本身不要包含逗号。
+- `--include-code-snippets`：在候选文件下附带代码片段。
+- `--progress`：将搜索进度输出到 stderr。
+- `--json`：将 CLI 结果包装成 JSON。注意当前搜索结果本体仍是文本。
+
+## Key 命令
+
+- `extract-key`：输出脱敏 key、长度、来源路径和 export 命令。
+- `--check-key`：只验证本机 Windsurf key 自动发现，输出脱敏 key。
+- `--print-key`：输出完整 key，仅限本机排查使用。
+- `--key-env`：输出 `export WINDSURF_API_KEY='...'`。
+- `--db-path`：为 key 命令指定 Windsurf `state.vscdb` 路径。
+
+## 响应预期
+
+- 返回的文件和行号范围是候选上下文，不是最终事实。
+- `grep keywords` 用于后续本地 `rg` 精确核验。
+- `[config]` 行说明实际使用的 `tree_depth`、`max_turns`、`max_results`、超时和排除项。
+
+## 完整性检查
+
+在修改代码或给出项目特定结论前，至少确认相关的：
+
+- 入口点和公开 API。
+- 核心函数、类、hook、组件、命令或 handler。
+- 类型、接口、schema、validator 和配置。
+- 数据访问、副作用、外部调用和持久化边界。
+- 调用方、消费者、路由，以及从用户可见行为到实现的链路。
+- 现有测试、fixture、helper 和集成覆盖。
+
+缺少关键上下文时，继续用更聚焦的问题查询 Fast Context，或回到本地 `rg` 和文件读取。
+
+## 失败处理
+
+- 依赖缺失：在包目录运行 `npm install`。
+- 结果太浅：提高 `--max-turns` 或 `--max-results`，或换成更具体的问题。
+- 仓库太大：降低 `--tree-depth`，增加 `--exclude`，或把 `--project` 缩小到子目录。
+- 认证失败：先运行 `--check-key`，确认 Windsurf 已登录，或设置 `WINDSURF_API_KEY`。
+- 不要引入本地语义搜索 fallback；失败时暴露真实错误和调参建议。