droid-patch 0.4.1 → 0.6.0

package/README.md

@@ -26,6 +26,9 @@ npx droid-patch --skip-login droid-nologin
 # Patch with --websearch to enable local search proxy
 npx droid-patch --websearch droid-search
 
+# Patch with --websearch --standalone for fully local mode (mock non-LLM APIs)
+npx droid-patch --websearch --standalone droid-local
+
 # Patch with --reasoning-effort to enable reasoning for custom models
 npx droid-patch --reasoning-effort droid-reasoning
 
@@ -54,23 +57,25 @@ npx droid-patch --skip-login -o /path/to/dir my-droid
 
 ### Available Options
 
-| Option | Description |
-|--------|-------------|
-| `--is-custom` | Patch `isCustom:!0` to `isCustom:!1` (enables context compression for custom models) |
-| `--skip-login` | Bypass login by injecting a fake `FACTORY_API_KEY` into the binary |
-| `--api-base <url>` | Replace Factory API URL with a custom server (max 22 chars) |
-| `--websearch` | Inject local WebSearch proxy with multiple search providers |
-| `--reasoning-effort` | Enable reasoning effort UI selector for custom models (set to high) |
-| `--dry-run` | Verify patches without actually modifying the binary |
-| `-p, --path <path>` | Path to the droid binary (default: `~/.droid/bin/droid`) |
-| `-o, --output <dir>` | Output directory for patched binary (creates file without alias) |
-| `--no-backup` | Skip creating backup of original binary |
-| `-v, --verbose` | Enable verbose output |
+| Option                | Description                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `--is-custom`         | Patch `isCustom:!0` to `isCustom:!1` (enables context compression for custom models) |
+| `--skip-login`        | Bypass login by injecting a fake `FACTORY_API_KEY` into the binary                   |
+| `--api-base <url>`    | Replace Factory API URL with a custom server (max 22 chars)                          |
+| `--websearch`         | Inject local WebSearch proxy with multiple search providers                          |
+| `--standalone`        | Standalone mode: mock non-LLM Factory APIs (use with `--websearch`)                  |
+| `--reasoning-effort`  | Enable reasoning effort UI selector for custom models (set to high)                  |
+| `--disable-telemetry` | Disable telemetry and Sentry error reporting                                         |
+| `--dry-run`           | Verify patches without actually modifying the binary                                 |
+| `-p, --path <path>`   | Path to the droid binary (default: `~/.droid/bin/droid`)                             |
+| `-o, --output <dir>`  | Output directory for patched binary (creates file without alias)                     |
+| `--no-backup`         | Skip creating backup of original binary                                              |
+| `-v, --verbose`       | Enable verbose output                                                                |
 
 ### Manage Aliases and Files
 
 ```bash
-# List all aliases
+# List all aliases (shows versions, flags, creation time)
 npx droid-patch list
 
 # Remove an alias
@@ -80,8 +85,13 @@ npx droid-patch remove <alias-name>
 npx droid-patch remove ./my-droid
 npx droid-patch remove /path/to/patched-binary
 
-# Check proxy status
-npx droid-patch proxy-status
+# Remove aliases by filter
+npx droid-patch remove --patch-version=0.4.0     # by droid-patch version
+npx droid-patch remove --droid-version=1.0.40    # by droid version
+npx droid-patch remove --flag=websearch          # by feature flag
+
+# Clear all droid-patch data (aliases, binaries, metadata)
+npx droid-patch clear
 ```
 
 ### Update Aliases
@@ -147,6 +157,7 @@ Replaces all `process.env.FACTORY_API_KEY` references in the binary with a hardc
 **Purpose**: Bypass the login/authentication requirement without needing to set the `FACTORY_API_KEY` environment variable.
 
 **How it works**:
+
 - The original code checks `process.env.FACTORY_API_KEY` to authenticate
 - After patching, the code directly uses the fake key string, bypassing the env check
 - This is a binary-level patch, so it works across all terminal sessions without any environment setup
@@ -160,6 +171,7 @@ Replaces the Factory API base URL (`https://api.factory.ai`) with a custom URL.
 **Limitation**: URL must be 22 characters or less (same length as original URL).
 
 **Examples**:
+
 ```bash
 # Valid URLs (<=22 chars)
 npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
@@ -176,16 +188,21 @@ Enables WebSearch functionality through a local proxy server that intercepts `/a
 **Purpose**: Enable WebSearch functionality without Factory.ai authentication.
 
 **Features**:
+
 - **Multiple search providers** with automatic fallback
-- **Auto-start**: Proxy starts automatically when you run the alias
-- **Auto-shutdown**: Proxy shuts down after 5 minutes of inactivity (configurable)
-- **Process detection**: Stays alive as long as droid is running
+- **Per-instance proxy**: Each droid instance runs its own proxy on an auto-assigned port
+- **Auto-cleanup**: Proxy automatically stops when droid exits
+- **Forward target**: Use `--api-base` with `--websearch` to forward non-search requests to a custom backend
 
 **Usage**:
+
 ```bash
-# Create alias with websearch
+# Create alias with websearch (uses official Factory API)
 npx droid-patch --websearch droid-search
 
+# Create alias with websearch + custom backend
+npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom
+
 # Just run it - everything is automatic!
 droid-search
 ```
@@ -193,6 +210,7 @@ droid-search
 ### `--reasoning-effort`
 
 Enables reasoning effort control for custom models by patching the binary to:
+
 1. Set `supportedReasoningEfforts` from `["none"]` to `["high"]`
 2. Set `defaultReasoningEffort` from `"none"` to `"high"`
 3. Enable the reasoning effort UI selector (normally hidden for custom models)
@@ -201,12 +219,14 @@ Enables reasoning effort control for custom models by patching the binary to:
 **Purpose**: Allow custom models to use reasoning effort features that are normally only available for official models.
 
 **How it works**:
+
 - The droid UI shows a reasoning effort selector when `supportedReasoningEfforts.length > 1`
 - Custom models are hardcoded with `["none"]`, hiding the selector
 - This patch changes the value to `["high"]` and modifies the UI condition to show the selector
 - The reasoning effort setting will be sent to your custom model's API
 
 **Usage**:
+
 ```bash
 # Enable reasoning effort for custom models
 npx droid-patch --reasoning-effort droid-reasoning
@@ -238,6 +258,52 @@ Available values:
 
 **Note**: The `xhigh` value bypasses validation and is sent directly to your API. Make sure your custom model/proxy supports this parameter.
 
+### `--standalone`
+
+Enables standalone mode when used with `--websearch`. In this mode, non-LLM Factory APIs are mocked locally instead of being forwarded to Factory servers.
+
+**Purpose**: Reduce unnecessary network requests and enable fully local operation (except for LLM API calls).
+
+**How it works**:
+
+- **Whitelist approach**: Only `/api/llm/a/*` (Anthropic) and `/api/llm/o/*` (OpenAI) are forwarded to upstream
+- All other Factory APIs are mocked:
+  - `/api/sessions/create` → Returns unique local session ID
+  - `/api/cli/whoami` → Returns 401 (triggers local token fallback)
+  - `/api/tools/get-url-contents` → Returns 404 (triggers local URL fetch)
+  - Other APIs → Returns empty `{}` response
+
+**Usage**:
+
+```bash
+# Standalone mode with websearch
+npx droid-patch --websearch --standalone droid-local
+
+# Combine with other patches for fully local setup
+npx droid-patch --is-custom --skip-login --websearch --standalone droid-full-local
+```
+
+### `--disable-telemetry`
+
+Disables telemetry data uploads and Sentry error reporting.
+
+**Purpose**: Prevent droid from sending usage data and error reports to Factory servers.
+
+**How it works**:
+
+- Breaks Sentry environment variable checks (`ENABLE_SENTRY`, `VITE_VERCEL_ENV`)
+- Makes `flushToWeb()` always return early, preventing any telemetry fetch requests
+
+**Usage**:
+
+```bash
+# Disable telemetry only
+npx droid-patch --disable-telemetry droid-private
+
+# Combine with other patches
+npx droid-patch --is-custom --skip-login --disable-telemetry droid-private
+```
+
 ---
 
 ## WebSearch Configuration Guide
@@ -248,14 +314,14 @@ The `--websearch` feature supports multiple search providers. Configure them usi
 
 The proxy tries providers in this order and uses the first one that succeeds:
 
-| Priority | Provider | Quality | Free Tier | Setup Difficulty |
-|----------|----------|---------|-----------|------------------|
-| 1 | Smithery Exa | Excellent | Free (via Smithery) | Easy |
-| 2 | Google PSE | Very Good | 10,000/day | Medium |
-| 3 | Serper | Very Good | 2,500 free credits | Easy |
-| 4 | Brave Search | Good | 2,000/month | Easy |
-| 5 | SearXNG | Good | Unlimited (self-host) | Hard |
-| 6 | DuckDuckGo | Basic | Unlimited | None |
+| Priority | Provider     | Quality   | Free Tier             | Setup Difficulty |
+| -------- | ------------ | --------- | --------------------- | ---------------- |
+| 1        | Smithery Exa | Excellent | Free (via Smithery)   | Easy             |
+| 2        | Google PSE   | Very Good | 10,000/day            | Medium           |
+| 3        | Serper       | Very Good | 2,500 free credits    | Easy             |
+| 4        | Brave Search | Good      | 2,000/month           | Easy             |
+| 5        | SearXNG      | Good      | Unlimited (self-host) | Hard             |
+| 6        | DuckDuckGo   | Basic     | Unlimited             | None             |
 
 ---
 
@@ -417,6 +483,7 @@ Find public instances at [searx.space](https://searx.space/)
 #### Option B: Self-Host with Docker
 
 1. **Run SearXNG with Docker**
+
    ```bash
    docker run -d \
      --name searxng \
@@ -504,31 +571,7 @@ export BRAVE_API_KEY="your_brave_key"
 
 ---
 
-## Proxy Management
-
-### Auto-Shutdown
-
-The proxy automatically shuts down after 5 minutes of inactivity to save resources.
-
-```bash
-# Customize timeout (in seconds)
-export DROID_PROXY_IDLE_TIMEOUT=600   # 10 minutes
-export DROID_PROXY_IDLE_TIMEOUT=0     # Disable auto-shutdown
-```
-
-### Check Proxy Status
-
-```bash
-npx droid-patch proxy-status
-```
-
-Output shows:
-- Proxy running status
-- Process ID
-- Droid process detection
-- Idle timeout settings
-
-### Debug Mode
+## Debug Mode
 
 Enable detailed logging to troubleshoot search issues:
 
@@ -547,15 +590,33 @@ npx droid-patch --websearch droid-search
 droid-search  # Just works!
 
 # Full-featured droid
-npx droid-patch --is-custom --skip-login --websearch droid-full
+npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full
+
+# Standalone mode: websearch + mock non-LLM APIs
+npx droid-patch --websearch --standalone droid-local
+
+# Privacy mode: disable telemetry
+npx droid-patch --disable-telemetry droid-private
+
+# Full local setup: all features combined
+npx droid-patch --is-custom --skip-login --websearch --standalone --disable-telemetry droid-full-local
+
+# Websearch with custom backend
+npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom
 
 # Create a standalone patched binary in current directory
 npx droid-patch --skip-login -o . my-droid
 ./my-droid --version
 
+# List all aliases with version info
+npx droid-patch list
+
 # Clean up
-npx droid-patch remove droid-search   # remove alias and all related files
-npx droid-patch remove ./my-droid     # remove file
+npx droid-patch remove droid-search              # remove single alias
+npx droid-patch remove --flag=websearch          # remove all websearch aliases
+npx droid-patch remove --flag=standalone         # remove all standalone aliases
+npx droid-patch remove --patch-version=0.4.0     # remove by droid-patch version
+npx droid-patch clear                            # remove everything
 ```
 
 ## License

package/README.zh-CN.md

@@ -26,6 +26,9 @@ npx droid-patch --skip-login droid-nologin
 # 使用 --websearch 启用本地搜索代理
 npx droid-patch --websearch droid-search
 
+# 使用 --websearch --standalone 启用完全本地模式（mock 非 LLM API）
+npx droid-patch --websearch --standalone droid-local
+
 # 使用 --reasoning-effort 为自定义模型启用推理功能
 npx droid-patch --reasoning-effort droid-reasoning
 
@@ -54,23 +57,25 @@ npx droid-patch --skip-login -o /path/to/dir my-droid
 
 ### 可用选项
 
-| 选项 | 说明 |
-|------|------|
-| `--is-custom` | 将 `isCustom:!0` 修改为 `isCustom:!1`（为自定义模型启用上下文压缩） |
-| `--skip-login` | 通过注入假的 `FACTORY_API_KEY` 跳过登录验证 |
-| `--api-base <url>` | 将 Factory API URL 替换为自定义服务器（最多 22 个字符） |
-| `--websearch` | 注入本地 WebSearch 代理，支持多个搜索提供商 |
-| `--reasoning-effort` | 为自定义模型启用推理强度 UI 选择器（设置为 high） |
-| `--dry-run` | 验证修补但不实际修改二进制文件 |
-| `-p, --path <path>` | droid 二进制文件路径（默认：`~/.droid/bin/droid`） |
-| `-o, --output <dir>` | 修补后二进制文件的输出目录（直接创建文件，不创建别名） |
-| `--no-backup` | 跳过创建原始二进制文件的备份 |
-| `-v, --verbose` | 启用详细输出 |
+| 选项                  | 说明                                                                |
+| --------------------- | ------------------------------------------------------------------- |
+| `--is-custom`         | 将 `isCustom:!0` 修改为 `isCustom:!1`（为自定义模型启用上下文压缩） |
+| `--skip-login`        | 通过注入假的 `FACTORY_API_KEY` 跳过登录验证                         |
+| `--api-base <url>`    | 将 Factory API URL 替换为自定义服务器（最多 22 个字符）             |
+| `--websearch`         | 注入本地 WebSearch 代理，支持多个搜索提供商                         |
+| `--standalone`        | 独立模式：mock 非 LLM 的 Factory API（与 `--websearch` 配合使用）   |
+| `--reasoning-effort`  | 为自定义模型启用推理强度 UI 选择器（设置为 high）                   |
+| `--disable-telemetry` | 禁用遥测数据上传和 Sentry 错误报告                                  |
+| `--dry-run`           | 验证修补但不实际修改二进制文件                                      |
+| `-p, --path <path>`   | droid 二进制文件路径（默认：`~/.droid/bin/droid`）                  |
+| `-o, --output <dir>`  | 修补后二进制文件的输出目录（直接创建文件，不创建别名）              |
+| `--no-backup`         | 跳过创建原始二进制文件的备份                                        |
+| `-v, --verbose`       | 启用详细输出                                                        |
 
 ### 管理别名和文件
 
 ```bash
-# 列出所有别名
+# 列出所有别名（显示版本、flags、创建时间）
 npx droid-patch list
 
 # 删除别名
@@ -80,8 +85,13 @@ npx droid-patch remove <alias-name>
 npx droid-patch remove ./my-droid
 npx droid-patch remove /path/to/patched-binary
 
-# 检查代理状态
-npx droid-patch proxy-status
+# 按条件删除别名
+npx droid-patch remove --patch-version=0.4.0     # 按 droid-patch 版本
+npx droid-patch remove --droid-version=1.0.40    # 按 droid 版本
+npx droid-patch remove --flag=websearch          # 按功能 flag
+
+# 清除所有 droid-patch 数据（别名、二进制文件、元数据）
+npx droid-patch clear
 ```
 
 ### 更新别名
@@ -147,6 +157,7 @@ export PATH="$HOME/.droid-patch/aliases:$PATH"
 **用途**：无需设置 `FACTORY_API_KEY` 环境变量即可跳过登录/认证要求。
 
 **工作原理**：
+
 - 原始代码通过检查 `process.env.FACTORY_API_KEY` 进行认证
 - 修补后，代码直接使用假密钥字符串，绕过环境变量检查
 - 这是二进制级别的修补，因此在所有终端会话中都有效，无需任何环境设置
@@ -160,6 +171,7 @@ export PATH="$HOME/.droid-patch/aliases:$PATH"
 **限制**：URL 必须不超过 22 个字符（与原始 URL 长度相同）。
 
 **示例**：
+
 ```bash
 # 有效的 URL（<=22 个字符）
 npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
@@ -176,16 +188,21 @@ npx droid-patch --api-base "http://my-long-domain.com:3000" droid  # 错误！
 **用途**：无需 Factory.ai 认证即可使用 WebSearch 功能。
 
 **特性**：
+
 - **多搜索提供商**：支持自动降级
-- **自动启动**：运行别名时代理自动启动
-- **自动关闭**：空闲 5 分钟后代理自动关闭（可配置）
-- **进程检测**：只要 droid 在运行，代理就保持活跃
+- **每实例独立代理**：每个 droid 实例运行自己的代理，自动分配端口
+- **自动清理**：droid 退出时代理自动停止
+- **转发目标**：使用 `--api-base` 配合 `--websearch` 可将非搜索请求转发到自定义后端
 
 **使用方法**：
+
 ```bash
-# 创建带 websearch 的别名
+# 创建带 websearch 的别名（使用官方 Factory API）
 npx droid-patch --websearch droid-search
 
+# 创建带 websearch + 自定义后端的别名
+npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom
+
 # 直接运行 - 一切都是自动的！
 droid-search
 ```
@@ -193,6 +210,7 @@ droid-search
 ### `--reasoning-effort`
 
 通过修补二进制文件为自定义模型启用推理强度控制：
+
 1. 将 `supportedReasoningEfforts` 从 `["none"]` 改为 `["high"]`
 2. 将 `defaultReasoningEffort` 从 `"none"` 改为 `"high"`
 3. 启用推理强度 UI 选择器（通常对自定义模型隐藏）
@@ -201,12 +219,14 @@ droid-search
 **用途**：允许自定义模型使用通常仅对官方模型可用的推理强度功能。
 
 **工作原理**：
+
 - 当 `supportedReasoningEfforts.length > 1` 时，droid UI 会显示推理强度选择器
 - 自定义模型硬编码为 `["none"]`，隐藏了选择器
 - 此补丁将值改为 `["high"]` 并修改 UI 条件以显示选择器
 - 推理强度设置将发送到您的自定义模型 API
 
 **使用方法**：
+
 ```bash
 # 为自定义模型启用推理强度
 npx droid-patch --reasoning-effort droid-reasoning
@@ -238,6 +258,52 @@ npx droid-patch --is-custom --reasoning-effort droid-full
 
 **注意**：`xhigh` 值会绕过验证直接发送到 API。请确保您的自定义模型/代理支持此参数。
 
+### `--standalone`
+
+与 `--websearch` 配合使用时启用独立模式。在此模式下，非 LLM 的 Factory API 会在本地 mock，而不是转发到 Factory 服务器。
+
+**用途**：减少不必要的网络请求，实现完全本地化运行（LLM API 调用除外）。
+
+**工作原理**：
+
+- **白名单方式**：只有 `/api/llm/a/*`（Anthropic）和 `/api/llm/o/*`（OpenAI）会转发到上游
+- 其他所有 Factory API 都会被 mock：
+  - `/api/sessions/create` → 返回唯一的本地 session ID
+  - `/api/cli/whoami` → 返回 401（触发本地 token 回退）
+  - `/api/tools/get-url-contents` → 返回 404（触发本地 URL 获取）
+  - 其他 API → 返回空 `{}` 响应
+
+**使用方法**：
+
+```bash
+# 独立模式 + websearch
+npx droid-patch --websearch --standalone droid-local
+
+# 与其他补丁组合实现完全本地化
+npx droid-patch --is-custom --skip-login --websearch --standalone droid-full-local
+```
+
+### `--disable-telemetry`
+
+禁用遥测数据上传和 Sentry 错误报告。
+
+**用途**：阻止 droid 向 Factory 服务器发送使用数据和错误报告。
+
+**工作原理**：
+
+- 破坏 Sentry 环境变量检查（`ENABLE_SENTRY`、`VITE_VERCEL_ENV`）
+- 使 `flushToWeb()` 始终提前返回，阻止任何遥测 fetch 请求
+
+**使用方法**：
+
+```bash
+# 仅禁用遥测
+npx droid-patch --disable-telemetry droid-private
+
+# 与其他补丁组合
+npx droid-patch --is-custom --skip-login --disable-telemetry droid-private
+```
+
 ---
 
 ## WebSearch 配置指南
@@ -248,14 +314,14 @@ npx droid-patch --is-custom --reasoning-effort droid-full
 
 代理按以下顺序尝试提供商，使用第一个成功的：
 
-| 优先级 | 提供商 | 质量 | 免费额度 | 设置难度 |
-|--------|--------|------|----------|----------|
-| 1 | Smithery Exa | 优秀 | 免费（通过 Smithery） | 简单 |
-| 2 | Google PSE | 很好 | 10,000 次/天 | 中等 |
-| 3 | Serper | 很好 | 2,500 免费额度 | 简单 |
-| 4 | Brave Search | 好 | 2,000 次/月 | 简单 |
-| 5 | SearXNG | 好 | 无限（自托管） | 较难 |
-| 6 | DuckDuckGo | 基本 | 无限 | 无需配置 |
+| 优先级 | 提供商       | 质量 | 免费额度              | 设置难度 |
+| ------ | ------------ | ---- | --------------------- | -------- |
+| 1      | Smithery Exa | 优秀 | 免费（通过 Smithery） | 简单     |
+| 2      | Google PSE   | 很好 | 10,000 次/天          | 中等     |
+| 3      | Serper       | 很好 | 2,500 免费额度        | 简单     |
+| 4      | Brave Search | 好   | 2,000 次/月           | 简单     |
+| 5      | SearXNG      | 好   | 无限（自托管）        | 较难     |
+| 6      | DuckDuckGo   | 基本 | 无限                  | 无需配置 |
 
 ---
 
@@ -417,6 +483,7 @@ export SEARXNG_URL="https://searx.be"
 #### 选项 B：使用 Docker 自托管
 
 1. **使用 Docker 运行 SearXNG**
+
    ```bash
    docker run -d \
      --name searxng \
@@ -504,31 +571,7 @@ export BRAVE_API_KEY="your_brave_key"
 
 ---
 
-## 代理管理
-
-### 自动关闭
-
-代理在空闲 5 分钟后自动关闭以节省资源。
-
-```bash
-# 自定义超时时间（秒）
-export DROID_PROXY_IDLE_TIMEOUT=600   # 10 分钟
-export DROID_PROXY_IDLE_TIMEOUT=0     # 禁用自动关闭
-```
-
-### 检查代理状态
-
-```bash
-npx droid-patch proxy-status
-```
-
-输出显示：
-- 代理运行状态
-- 进程 ID
-- Droid 进程检测
-- 空闲超时设置
-
-### 调试模式
+## 调试模式
 
 启用详细日志以排查搜索问题：
 
@@ -547,15 +590,33 @@ npx droid-patch --websearch droid-search
 droid-search  # 直接使用！
 
 # 全功能 droid
-npx droid-patch --is-custom --skip-login --websearch droid-full
+npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full
+
+# 独立模式：websearch + mock 非 LLM API
+npx droid-patch --websearch --standalone droid-local
+
+# 隐私模式：禁用遥测
+npx droid-patch --disable-telemetry droid-private
+
+# 完全本地化：所有功能组合
+npx droid-patch --is-custom --skip-login --websearch --standalone --disable-telemetry droid-full-local
+
+# websearch + 自定义后端
+npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom
 
 # 在当前目录创建独立的修补后二进制文件
 npx droid-patch --skip-login -o . my-droid
 ./my-droid --version
 
+# 列出所有别名及版本信息
+npx droid-patch list
+
 # 清理
-npx droid-patch remove droid-search   # 删除别名和所有相关文件
-npx droid-patch remove ./my-droid     # 删除文件
+npx droid-patch remove droid-search              # 删除单个别名
+npx droid-patch remove --flag=websearch          # 删除所有 websearch 别名
+npx droid-patch remove --flag=standalone         # 删除所有 standalone 别名
+npx droid-patch remove --patch-version=0.4.0     # 按 droid-patch 版本删除
+npx droid-patch clear                            # 删除所有
 ```
 
 ## 许可证