pi-grok-search 2.0.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/README.md

@@ -0,0 +1,151 @@
+# pi-grok-search
+
+[English](./README_EN.md) | 简体中文
+
+通过 [Grok API](https://docs.x.ai/) + [Tavily](https://tavily.com/) + [Firecrawl](https://firecrawl.dev/) 为 [pi](https://github.com/earendil-works/pi-mono) 提供完整的网络访问能力。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> 参考: [GrokSearch MCP](https://github.com/GuDaStudio/GrokSearch)
+
+## 双引擎架构
+
+```
+pi ──Extension──► pi-grok-search
+                    ├─ grok_search     ───► Grok API（AI 深度搜索）
+                    ├─ grok_sources    ───► 信源缓存（按 session_id）
+                    ├─ web_fetch       ───► Tavily Extract → Firecrawl Scrape（自动降级）
+                    ├─ web_map         ───► Tavily Map（站点映射）
+                    └─ search_planning ──► 6 阶段结构化搜索规划
+```
+
+## 功能特性
+
+- **🔍 AI 深度搜索** — Grok 驱动，自动时间注入，支持平台聚焦
+- **📄 网页抓取** — Tavily Extract → Firecrawl Scrape 自动降级
+- **🗺️ 站点映射** — Tavily Map 遍历网站结构
+- **📋 搜索规划** — 6 阶段结构化规划
+- **💾 信源缓存** — session_id 索引，按需获取
+- **🔄 智能重试** — Retry-After 头解析 + 指数退避
+- **⚙️ 交互式配置** — CLI 菜单配置 Grok/Tavily/Firecrawl API
+- **🔍 连接诊断** — 一键测试所有 API 连通性
+
+## 安装
+
+### 方式一：pi install（推荐）
+
+```bash
+# 从 GitHub 安装
+pi install git:github.com/justhiL/pi-grok-search
+
+# 或指定版本
+pi install git:github.com/justhiL/pi-grok-search@v2.0.0
+```
+
+### 方式二：手动安装
+
+```bash
+# 全局
+git clone https://github.com/justhiL/pi-grok-search.git ~/.pi/agent/extensions/pi-grok-search/
+
+# 项目本地
+git clone https://github.com/justhiL/pi-grok-search.git .pi/extensions/pi-grok-search/
+```
+
+### 方式三：测试运行
+
+```bash
+pi -e git:github.com/justhiL/pi-grok-search
+```
+
+## 配置
+
+安装后在 pi 中运行 `/grok-config` 进入交互式配置菜单，或直接设置环境变量：
+
+### 环境变量
+
+```bash
+# Grok（必填）
+export GROK_API_URL="https://api.x.ai/v1"
+export GROK_API_KEY="xai-your-key"
+export GROK_MODEL="grok-4-fast"        # 可选
+
+# Tavily（可选，提供 web_fetch / web_map）
+export TAVILY_API_KEY="tvly-your-key"
+
+# Firecrawl（可选，Tavily 失败时托底）
+export FIRECRAWL_API_KEY="fc-your-key"
+```
+
+### 交互式配置
+
+在 pi 中输入：
+
+```
+/grok-config
+```
+
+支持：查看配置、设置 Grok/Tavily/Firecrawl API、切换模型、测试连接。
+
+### 配置文件
+
+持久化到 `~/.config/pi-grok-search/config.json`：
+
+```json
+{
+  "apiUrl": "https://api.x.ai/v1",
+  "apiKey": "xai-your-key",
+  "model": "grok-4-fast",
+  "tavilyApiKey": "tvly-your-key",
+  "firecrawlApiKey": "fc-your-key"
+}
+```
+
+## 使用
+
+### 命令
+
+| 命令                     | 说明                       |
+| ------------------------ | -------------------------- |
+| `/grok-search <query>`   | 搜索网络信息               |
+| `/grok-config`           | 交互式配置管理             |
+| `/grok-model [model-id]` | 切换 Grok 模型             |
+| `/pi-ext-docs [topic]`   | 搜索 pi Extension 开发文档 |
+
+### 工具（LLM 自动调用）
+
+| 工具              | 说明                                        |
+| ----------------- | ------------------------------------------- |
+| `grok_search`     | AI 深度搜索，返回结果 + session_id          |
+| `grok_sources`    | 通过 session_id 获取信源列表                |
+| `web_fetch`       | 抓取网页内容（Tavily → Firecrawl 自动降级） |
+| `web_map`         | 遍历网站结构，生成站点地图                  |
+| `grok_config`     | 查看/修改/测试配置                          |
+| `search_planning` | 6 阶段结构化搜索规划                        |
+
+安装后 LLM 会自动识别这些工具，根据用户问题自主决定调用。
+
+## 信源质量准则
+
+本扩展内置了严格的搜索行为规范（通过 `promptGuidelines` 注入系统提示）：
+
+- 搜索用英文，输出用中文
+- 即使有内部知识也必须搜索验证
+- 关键事实需 ≥2 个独立来源支持
+- 冲突来源需呈现双方证据
+- 不确定时先说明局限性
+
+## 相关链接
+
+- [linux do](https://linux.do)
+- [本项目 GitHub](https://github.com/justhiL/pi-grok-search)
+- [pi 官方文档](https://github.com/earendil-works/pi-mono)
+- [pi Extension 文档](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)
+- [Grok API](https://docs.x.ai/)
+- [Tavily API](https://docs.tavily.com/)
+- [Firecrawl API](https://docs.firecrawl.dev/)
+- [GrokSearch MCP 参考](https://github.com/GuDaStudio/GrokSearch)
+
+## License
+
+[MIT](LICENSE)

package/README_EN.md

@@ -0,0 +1,150 @@
+# pi-grok-search
+
+English | [简体中文](./README.md)
+
+Complete web access for [pi](https://github.com/earendil-works/pi-mono) powered by [Grok API](https://docs.x.ai/) + [Tavily](https://tavily.com/) + [Firecrawl](https://firecrawl.dev/).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Inspired by [GrokSearch MCP](https://github.com/GuDaStudio/GrokSearch)
+
+## Architecture
+
+```
+pi ──Extension──► pi-grok-search
+                    ├─ grok_search     ───► Grok API (AI Deep Search)
+                    ├─ grok_sources    ───► Source Cache (by session_id)
+                    ├─ web_fetch       ───► Tavily Extract → Firecrawl Scrape (auto-fallback)
+                    ├─ web_map         ───► Tavily Map (Site Mapping)
+                    └─ search_planning ──► 6-Phase Structured Search Planning
+```
+
+## Features
+
+- **🔍 AI Deep Search** — Grok-powered, auto time injection, platform focus
+- **📄 Web Fetch** — Tavily Extract → Firecrawl Scrape auto-fallback
+- **🗺️ Site Mapping** — Tavily Map traverses website structure
+- **📋 Search Planning** — 6-phase structured planning
+- **💾 Source Cache** — session_id indexed, on-demand retrieval
+- **🔄 Smart Retry** — Retry-After header parsing + exponential backoff
+- **⚙️ Interactive Config** — CLI menu for Grok/Tavily/Firecrawl API
+- **🔍 Connection Diagnostics** — One-click test all API connectivity
+
+## Installation
+
+### Option 1: pi install (Recommended)
+
+```bash
+# Install from GitHub
+pi install git:github.com/justhiL/pi-grok-search
+
+# Or with specific version
+pi install git:github.com/justhiL/pi-grok-search@v2.0.0
+```
+
+### Option 2: Manual Install
+
+```bash
+# Global
+git clone https://github.com/justhiL/pi-grok-search.git ~/.pi/agent/extensions/pi-grok-search/
+
+# Project-local
+git clone https://github.com/justhiL/pi-grok-search.git .pi/extensions/pi-grok-search/
+```
+
+### Option 3: Test Run
+
+```bash
+pi -e git:github.com/justhiL/pi-grok-search
+```
+
+## Configuration
+
+After installation, run `/grok-config` in pi for interactive configuration, or set environment variables directly:
+
+### Environment Variables
+
+```bash
+# Grok (required)
+export GROK_API_URL="https://api.x.ai/v1"
+export GROK_API_KEY="xai-your-key"
+export GROK_MODEL="grok-4-fast"        # optional
+
+# Tavily (optional, provides web_fetch / web_map)
+export TAVILY_API_KEY="tvly-your-key"
+
+# Firecrawl (optional, fallback when Tavily fails)
+export FIRECRAWL_API_KEY="fc-your-key"
+```
+
+### Interactive Config
+
+In pi, type:
+
+```
+/grok-config
+```
+
+Supports: view config, set Grok/Tavily/Firecrawl API, switch model, test connections.
+
+### Config File
+
+Persisted to `~/.config/pi-grok-search/config.json`:
+
+```json
+{
+  "apiUrl": "https://api.x.ai/v1",
+  "apiKey": "xai-your-key",
+  "model": "grok-4-fast",
+  "tavilyApiKey": "tvly-your-key",
+  "firecrawlApiKey": "fc-your-key"
+}
+```
+
+## Usage
+
+### Commands
+
+| Command                  | Description               |
+| ------------------------ | ------------------------- |
+| `/grok-search <query>`   | Search the web            |
+| `/grok-config`           | Interactive configuration |
+| `/grok-model [model-id]` | Switch Grok model         |
+| `/pi-ext-docs [topic]`   | Search pi Extension docs  |
+
+### Tools (Auto-invoked by LLM)
+
+| Tool              | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `grok_search`     | AI deep search, returns results + session_id         |
+| `grok_sources`    | Retrieve source list by session_id                   |
+| `web_fetch`       | Fetch web content (Tavily → Firecrawl auto-fallback) |
+| `web_map`         | Traverse website structure, generate site map        |
+| `grok_config`     | View / modify / test configuration                   |
+| `search_planning` | 6-phase structured search planning                   |
+
+After installation, LLM automatically recognizes these tools and decides when to call them.
+
+## Search Quality Guidelines
+
+Built-in behavioral guidelines (injected into system prompt via `promptGuidelines`):
+
+- Search queries in English, user output in Chinese
+- Must verify with search even if internal knowledge exists
+- Key claims require ≥2 independent sources
+- Conflicting sources: present evidence from both sides
+- State limitations when uncertain
+
+## Links
+
+- [GitHub](https://github.com/justhiL/pi-grok-search)
+- [pi Official Docs](https://github.com/earendil-works/pi-mono)
+- [pi Extension Docs](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)
+- [Grok API](https://docs.x.ai/)
+- [Tavily API](https://docs.tavily.com/)
+- [Firecrawl API](https://docs.firecrawl.dev/)
+- [GrokSearch MCP Reference](https://github.com/GuDaStudio/GrokSearch)
+
+## License
+
+[MIT](LICENSE)