内容
# QodeX — 本地优先的 LLM 代理和编码 CLI 代理
> **QodeX 是一个开源的 LLM 代理，适用于您的终端 — 一个本地优先、具有代理功能的编码 CLI。** 它默认运行在本地模型（通过 Ollama / LM Studio 的 Qwen3-Coder），并可选地使用 Claude / GPT / Gemini / DeepSeek 作为云端备用。 一个优先考虑隐私的 AI 编码代理，设计用于在您的机器上运行模型，以执行实际的、多步骤的工程任务 — 如果需要，完全离线。
> 如果您正在寻找 **LLM 代理**、**CLI 代理**、**AI 编码代理** 或 **自主终端代理**，而这些代理不会将您的代码发送到他人的云端 — 那就是 QodeX。
**版本 2.4.0** · 100+ 内置工具 · 中文 & 波斯语 · Apache-2.0
[](https://github.com/QodeXcli/QodeX/actions/workflows/ci.yml)
---
## 使它与众不同
大多数代理 CLI **委托给模型** — 它们将工具交给模型，并信任模型正确使用它们。 这适用于前沿模型，但在使用较弱的本地模型时就会失败（循环、未完成的编辑、“完成”但实际上什么也没做）。
QodeX 采取相反的立场：**保护模型。** 一个确定性的防护层围绕循环运行，这样即使较小的本地模型也能产生值得信赖的输出：
- **语法门控** — 每个编辑在写入之前都会被解析；如果语法损坏，则拒绝保存。
- **完成门控** — 模型不能声称“测试通过”或“我已修复”，除非实际运行了测试 / 实际成功了编辑。 不支持的声明会被退回以进行纠正。
- **自动验证** — 在模型认为自己完成时，QodeX 会检测项目类型并运行真正的检查器（`tsc`、`eslint`、`ruff`、`pyright`、`go vet`、`cargo`、`php -l` …）对受影响的文件，并强制反馈任何错误。
- **交互式编辑审批** — 查看红色/绿色差异，并选择接受 / 编辑 / 继续 / 拒绝，然后再写入磁盘（或 `/auto on` 跳过）。
- **Git 支持的沙箱** — 风险工作在隐藏的分支上运行，并带有检查点； 在破坏性命令之前自动快照（`git stash`），然后提供一个命令来回滚。
- **技能安全扫描器** — 从 GitHub 安装的技能会在磁盘上运行前进行提示注入、秘密提取、破坏性 shell 和隐藏 unicode 载荷的扫描。
结果提高了 **下限**（允许较弱的模型交付），而无需更大的模型。
## Token 效率
长时间的代理会话会消耗大量 token 来记录不断增长的历史记录，而 QodeX 通过以下方式将工作上下文保持较小：
- **委托** — 大型文件资源管理器在只读子代理（`task`）中运行，具有 **单独的** 上下文窗口； 只有其摘要返回，因此数十次读取从不堆积在主窗口中。
- **结果老化** — 陈旧的大型工具输出在几轮后被存根（按需重新读取）。
- **压缩** — 历史记录在窗口填充时进行结构化摘要。
- **工具门控** — 每次只发送相关工具模式（问候语显示约 20 个工具，实际任务显示约 50 个工具，共 100+ 个）。
- **选择加入 `context.efficient: true`** 进一步收紧上述所有措施，以适用于较弱的本地模型。
状态栏中的实时 `12.4k/200k ████░░░░░░ 8%` 仪表显示上下文窗口的满度。
## 它能做什么
给 QodeX 一个自然语言任务（中文或波斯语），它就会驱动一个真正的代理循环：
- **读取和编辑代码** — `read_file`、`write_file`、`edit_text`、`edit_symbol`（AST 感知）、`multi_edit`（单文件顺序）、`multi_file_edit`（跨最多 50 个文件原子）。
- **理解代码库** — `ls`、`glob`、`grep`，以及 Tree-sitter 代码图：`project_overview`、`analyze_impact`、`find_callers`、`find_references`、`find_dead_code`、`safe_rename`。
- **运行命令** — `bash`，以及 `code_run` 用于沙箱 Python / Node / TS / PHP / Ruby（在 macOS 上使用 `sandbox-exec`）。
- **驱动真实浏览器** — Playwright 支持的 Chromium：导航、点击、填充、截图、评估 JS、读取控制台 + 页面错误 — 以验证您自己的 UI 更改。
- **管理开发服务器和作业** — `dev_server_start npm run dev` 然后 `browser_navigate http://localhost:5173`；`background_job_start` 用于异步工作，所有操作都在一个会话中。
- **搜索网络** — 默认使用 DuckDuckGo（带有 `lite` 回退 + 重试），或 Tavily / Brave / **Firecrawl**（当您设置密钥时，返回完整的页面 markdown 内联以节省往返）。
- **智能视觉** — `vision_analyze` 自动使用 **您自己的** 具有视觉能力的模型（Gemini、GPT-4o、Claude 或本地 Qwen-VL），当您的主代理或子代理已经可以看到时； 它仅在两者都无法使用时才会启动专用视觉模型。
- **可共享的实时工件** — 构建网页 / React / 仪表盘并使用 `artifact_live` 提供，它在每次编辑时 **热重载**；`share="network"` 将其打开到您的局域网，而 `share="tunnel"` 提供一个 **私有 https 链接**，您的团队可以打开（受令牌保护）— 一个实时 PR 演练或项目仪表盘。
- **权衡和商业分析** — 要求它分析或规划（不编码），它会产生 **决策级输出**：选项 × 加权标准 → 评分比较和一个明确的建议，商业计划结构，无虚构数字。
- **波斯语优先** — 技能自动加载和工具选择理解波斯语提示（تحلیل، دیتابیس， آرتیفکت…），而不仅仅是英文关键词。
- **验证其自身工作** — `auto_fix` 在修复 → 测试循环中运行您的测试命令，带有迭代上限和两次相同失败检测； 自动验证门控运行正确的检查器 **每种语言** 在多语言仓库中（TS **和** Python 都会被检查）。
- **Git** — 状态、差异、日志、分支、提交、创建 PR、发布说明。
- **技能** — 从精选注册表或任何 GitHub 仓库（单个 / 多个 / 目录）安装，安全扫描后进入；`search_skills` 查找它们。
- **子代理和编排** — `task` 委托给单独的模型/窗口；`orchestrate` 运行子代理的 DAG；`gather` 并行扩展读取。
- **MCP** — 连接任何 MCP 兼容的服务器； 其工具加入与内置工具相同的注册表。
- **领域工具** — Docker、数据库、WordPress（`php -l` 校验）、媒体（ffmpeg）、前端/打印、OpenAPI 摘要等。
## 安装
> 需要 **Node 20+**。`dist/` 是在本地构建的（未提交）— 需要执行 `npm run build` 步骤。
```bash
git clone https://github.com/QodeXcli/QodeX.git qodex && cd qodex
npm install
npm run build
npm link # 使 `qodex` 和 `qx` 在 PATH 上可用
```
可选但推荐（浏览器自动化，大约 200 MB 一次）：
```bash
npm install playwright
npx playwright install chromium
```
## 快速开始
```bash
# 设置向导 — 检测本地模型，写入 ~/.qodex/config.yaml
qodex setup
# 或直接启动
qodex
> 读取 package.json 并总结该项目的作用
```
## 配置
存储在 `~/.qodex/config.yaml`。指向 LM Studio 的最小本地模型设置：
```yaml
defaults:
provider: openai
model: qwen/qwen3-coder-next
preferLocal: true
providers:
ollama:
baseUrl: http://localhost:11434
openai:
apiKeyEnv: OPENAI_API_KEY
baseUrl: http://127.0.0.1:1234/v1 # 指向 LM Studio
extraModels:
- id: qwen/qwen3-coder-next
contextWindow: 32768
supportsToolCalls: true
roles:
subagent:
provider: ollama
model: qwen3-coder # 较小的/更快的模型用于委托读取
context:
efficient: false # 在弱本地模型上设置为 true 以节省 token
subagents:
mode: parallel # 关闭 | 顺序 | 并行
```
云提供商是可选的。 网络搜索密钥从环境变量中读取，而不是从配置文件中：
```bash
export TAVILY_API_KEY=tvly-...
export BRAVE_SEARCH_API_KEY=...
export FIRECRAWL_API_KEY=fc-... # 设置 FIRECRAWL_SCRAPE_CONTENT=1 以获取内联 markdown
```
## 内置工具
100+ 个工具，涵盖以下领域 — 在 QodeX 内运行 `/tools` 以获取完整的列表和描述：
| 领域 | 示例 |
|---|---|
| **文件系统** | read_file, write_file, edit_text, edit_symbol, multi_edit, multi_file_edit, ls, glob, grep |
| **Shell 和代码** | bash, code_run |
| **代码图** | project_overview, analyze_impact, find_callers, find_references, find_dead_code, safe_rename, semantic_search |
| **诊断** | 类型/校验检查器（tsc, eslint, ruff, pyright, go vet, cargo, php -l） |
| **Git** | status, diff, log, branch, commit, create_pr, release_notes |
| **网络** | web_search（DuckDuckGo / Tavily / Brave / Firecrawl）、web_fetch、network_check |
| **浏览器** | navigate, click, fill, screenshot, console, evaluate, get_text, wait_for |
| **开发服务器/作业** | dev_server_start/stop/log, background_job_start/status/wait/cancel |
| **技能** | use_skill, search_skills, install_skill（安全扫描） |
| **子代理** | task, orchestrate, gather, present_plan, todo_read/write, auto_fix |
| **视觉** | vision_analyze |
| **领域** | Docker, database, WordPress, media（ffmpeg）, frontend/print, OpenAPI |
| **MCP** | 连接任何 MCP 服务器； 其工具加入注册表 |
## 斜杠命令
```
/help 概述
/network 诊断互联网 + Ollama + LM Studio 连接性
/tools [--all] 按类别列出注册工具
/plan /normal 计划模式（只读） / 返回正常
/auto on|off 自动批准权限
/model <id> 重写此对话的模型
/subagents off|sequential|parallel
/snapshot list|take|restore 管理自动快照
/cost /tokens 代币/成本使用
/index [--force] 构建/刷新代码图
/mcp 列出连接的 MCP 服务器
/sessions /resume <id> /clear /exit
```
以及您放入 `.qodex/commands/` 的任何自定义命令，作为 markdown。
## 端到端示例
```
> 在 src/Header.tsx 中添加一个注销按钮，并验证其有效
```
QodeX 将：读取 `Header.tsx` → 添加按钮（显示为可批准的差异）→ `dev_server_start npm run dev` → `browser_navigate` localhost → 点击按钮 → 检查控制台错误 → 截图 → `vision_analyze` 以确认它看起来正确 → 在受影响的文件上运行类型检查器 → 停止服务器并报告。 一个代理循环，带有上述防护措施贯穿始终。
## 架构说明
- **一个代理循环**，带有每个任务的预算上限（token / 成本 / 墙上时钟 / 迭代），一个连续故障的断路器和自动恢复。
- **能力分层系统** — 前沿模型获得压缩提示； 弱/本地模型保留它们依赖的完整指导（每个会话缓存安全）。
- **每个工具的权限** — 只读工具自动批准； 变更工具一次性询问； “允许一次/会话/模式/始终”选择器。
- **代码图索引** — Tree-sitter 支持，持久化到 `.qodex/codegraph.db`，增量。
- **多提供商路由器** — Ollama、LM Studio、Anthropic、OpenAI、Gemini、DeepSeek、OpenRouter 都是首选。
- **整个 ESM 严格**； **钩子**（工具前/后）用于防护或仪表盘。
## 为什么本地优先
- **当运行 Ollama / LM Studio 时，没有数据离开您的机器** — 对专有代码库有用。
- **更快的迭代** — 每个工具调用的网络延迟为零。
- **离线工作** — `/network` 告诉您什么可用。
- **运行成本为 $0**，如果您有硬件； 云提供商按角色选择（例如，子代理在 Claude 上，视觉在 GPT 上）。
## 状态
积极开发中。 内置工具集和防护层稳定； 预计会有更多的 MCP 集成和权限 UX 改进。 问题和 PR 欢迎。
## 许可证
Apache License 2.0 — 见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
版权所有 2026 7 SEVEN。
