一个模块化的本地能力服务（HTTP），为 zion-next 浏览器端提供高速可调用工具。
项目已重构为模块化架构，解决了原始代码的耦合问题：
zion-local-tools/
├── src/zion_local_tools/
│ ├── __init__.py # 包入口
│ ├── main.py # FastAPI应用入口
│ ├── core/ # 核心模块
│ │ ├── __init__.py
│ │ ├── utils.py # 通用工具函数
│ │ └── cache.py # 缓存管理
│ ├── search/ # 搜索模块
│ │ ├── __init__.py
│ │ ├── service.py # 搜索服务
│ │ └── router.py # 搜索路由
│ ├── files/ # 文件操作模块
│ │ ├── __init__.py
│ │ ├── service.py # 文件服务
│ │ └── router.py # 文件路由
│ ├── bash/ # Bash执行模块
│ │ ├── __init__.py
│ │ ├── service.py # Bash服务
│ │ └── router.py # Bash路由
│ └── config/ # 配置模块
│ ├── __init__.py
│ └── settings.py # 应用配置
├── tests/ # 测试目录
│ ├── __init__.py
│ └── test_core_utils.py # 核心工具测试
├── pyproject.toml # 项目配置
├── run.py # 运行脚本
├── requirements.txt # 依赖文件
├── .gitignore
└── README.md
- ✅ 职责分离：每个功能模块独立，职责清晰
- ✅ 可测试性：模块化设计便于单元测试
- ✅ 可维护性：代码结构清晰，易于扩展
- ✅ 配置管理：统一的配置管理系统
- ✅ 类型提示：完整的类型注解
- ✅ 错误处理：统一的错误处理机制
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate # Windows
pip install -r requirements.txt# 方式1：使用uvicorn直接运行
uvicorn zion_local_tools.main:app --host 127.0.0.1 --port 8765 --reload
# 方式2：使用运行脚本
python run.py
# 方式3：使用原始脚本（兼容性）
bash run.sh# 服务器配置
export ZION_LOCAL_HOST="127.0.0.1"
export ZION_LOCAL_PORT="8765"
# Bash沙箱配置
export ZION_BASH_SANDBOX="1" # 启用沙箱（默认）
export ZION_ALLOW_DANGEROUS="0" # 禁用危险命令（默认）GET /search
- 功能：DuckDuckGo快速搜索
- 参数：
q: string 查询词（必填）k: number 返回条数（默认10，最大50）allowed_domains: 多值或逗号分隔（可选）blocked_domains: 多值或逗号分隔（可选）
- 响应：
{
"query": "python tutorial",
"engine": "duckduckgo",
"cached": false,
"results": [
{ "title": "Python官方教程", "url": "https://docs.python.org/", "snippet": "Python官方文档..." }
]
}GET /files/glob
- 功能：基于glob的快速文件搜索，按修改时间排序返回
- 参数：
pattern: string 文件匹配模式，如**/*.py（必填）path: string 搜索目录（可选，默认当前工作目录）
- 响应：
{
"pattern": "**/*.py",
"path": "/Users/me/project",
"results": ["/Users/me/project/app.py", "/Users/me/project/utils/helpers.py"]
}GET /files/grep
- 功能：内容检索（优先使用ripgrep，若未安装则回退Python正则）
- 参数：
pattern: string 正则表达式（必填）path: string 文件或目录（可选，默认当前工作目录）glob: 多值或逗号分隔，文件过滤（如*.ts,**/*.tsx）output_mode: string 枚举"content" | "files_with_matches" | "count"（默认files_with_matches）B/A/C: number 上下文行数（仅content模式生效）n: boolean 是否显示行号（content模式，默认true）i: boolean 不区分大小写（默认false）type: string 文件类型（rg --type，如js/py/rust等）head_limit: number 仅返回前N行/条目offset: number 跳过前N行/条目multiline: boolean 多行匹配
- 响应（content模式示例）：
{
"pattern": "function\\s+\\w+",
"path": "/repo",
"output_mode": "content",
"results": [
{ "file": "/repo/src/a.ts", "line": 12, "text": "function foo() {" }
]
}POST /bash
- 功能：在本地以bash执行命令，返回stdout/stderr/退出码；支持超时与输出截断
- Body(JSON)：
command: string 要执行的命令（必填）timeout: number 超时毫秒数（可选，默认120000，最大600000）dangerouslyDisableSandbox: boolean 是否禁用沙箱（需要服务端设置ZION_ALLOW_DANGEROUS=1）
- 响应：
{
"ok": true,
"exit_code": 0,
"stdout": "output...",
"stderr": "",
"duration_ms": 1234,
"timeout_ms": 120000,
"truncated": false,
"sandbox": true
}GET /health
- 功能：健康检查
- 响应：
{"ok": true}
GET /
- 功能：API信息
- 响应：显示所有可用端点
默认启用安全沙箱，阻止以下危险操作：
- 系统命令：
sudo,su,rm,chmod,chown,dd,mkfs,mount,shutdown,reboot,systemctl - 包管理器：
apt,yum,pacman,brew - 危险重定向：
>,>> - 管道执行：
curl | sh,wget | bash - 原地编辑：
sed -i
# 启用沙箱（默认）
export ZION_BASH_SANDBOX="1"
# 允许危险命令（谨慎使用）
export ZION_ALLOW_DANGEROUS="1"pip install -e ".[dev]"pytest tests/# 使用black格式化
black src/
# 使用isort排序导入
isort src/
# 使用ruff检查
ruff check src/mypy src/utils.py: 通用工具函数（路径处理、域名处理等）cache.py: TTL缓存管理
service.py: DuckDuckGo搜索服务router.py: 搜索API路由
service.py: glob和grep文件搜索服务router.py: 文件操作API路由
service.py: 安全的Bash命令执行服务router.py: Bash执行API路由
settings.py: 应用配置管理
- 搜索接口：保持不变
/search - 文件接口：从
/glob和/grep改为/files/glob和/files/grep - Bash接口：保持不变
/bash
旧的单文件 app.py 已拆分为模块化结构，新代码位于 src/zion_local_tools/ 目录下。
MIT License
- Fork 项目
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 开启 Pull Request
如有问题或建议，请提交 Issue 或联系维护团队。