基于 tkinter 的桌面 AI 对话工具，仅依赖 openai>=1.0.0，兼容 OpenAI 协议。支持 DeepSeek / OpenAI / Claude / Gemini / 本地模型，内置 Plan-and-Solve 规划执行、自我纠错、RAG 搜索、多模型辩论等功能。
待补充 —— 欢迎提交 PR 添加截图。建议覆盖以下场景：
- 主界面 +
<plan>规划大纲渲染- 流式输出 + 推理链（灰色 thinking tokens）
- 敏感操作确认栏（橙色横幅）
- 暗色模式
执行复杂任务前，Agent 会先输出 <plan> 规划大纲（紫色高亮），拆解步骤后逐一执行工具，让执行过程对用户透明。
- 13 类错误分析：文件不存在、权限拒绝、沙箱越界、计算错误、JSON 格式错误等
- 渐进式重试：第 1 次简短提示 → 第 2 次详细引导 → 第 3 次切换策略
- 重复调用检测：相同参数重试时自动提醒模型换方案
- 跨轮次错误记忆：同类错误自动复用上次成功的修复策略
- 行动后反思：工具执行完成后自检是否有遗漏，发现缺口继续补全
逐 token 实时渲染。支持推理链（thinking tokens）灰色显示，模型的中间推理过程对用户可见。
| 工具 | 说明 |
|---|---|
list_local_directory |
列出目录结构（Windows 大小写安全） |
read_local_file |
读取文件内容（沙箱保护，仅限工作目录） |
save_to_file |
写入文件（需确认，支持覆盖/追加模式） |
execute_shell |
执行 Shell 命令（需确认，30s 超时） |
web_fetch |
抓取网页文本（仅 http/https，512KB 上限，15s 超时） |
get_current_weather |
查询城市实时天气（数据源：wttr.in，免费无需 Key） |
execute_python_calc |
数学计算（AST 沙箱，防指数溢出） |
rag_search |
BM25 关键词搜索本地知识库 |
rag_build_index |
构建/增量更新项目索引（mtime 变更检测） |
execute_shell 会拦截以下危险模式（大小写不敏感）：
rm -rf / format del /f rd /s
shutdown reboot mkfs dd if=
:(){ :|:& };: (fork bomb)
- BM25 算法：纯 Python 实现，无额外依赖，中英文混合分词
- 限制：BM25 是关键词匹配，不是语义搜索。中文 2-gram 分词在短查询场景下精度有局限，后续计划支持向量检索
- 增量索引：通过 mtime 变更检测，只重建修改过的文件
- 自动触发：Agent 找不到文件时会自动搜索
Shell 执行、文件写入、网页抓取等敏感操作执行前会显示确认栏：
- 同意 — 允许本次操作
- 拒绝 — 拒绝并通知模型换方案
- 同意全部 — 后续敏感操作自动放行（状态栏提示）
| Provider | 默认模型 | 说明 |
|---|---|---|
| DeepSeek | deepseek-v4-pro, deepseek-v4-flash | 默认 Provider |
| OpenAI | gpt-4o, gpt-4o-mini, gpt-4.1 | — |
| OpenRouter | Claude Sonnet 4, Gemini 2.5 Pro, Llama 4 | 自动附带 OpenRouter 请求头 |
| Ollama（本地） | 手动输入，如 qwen2.5:7b |
需本地运行 Ollama 服务 |
| 自定义 | 手动输入 | 任意 OpenAI 兼容 API 地址 |
- 动态 Persona 路由：关键词密度计分，自动切换 Coder / Writer / Default 角色
- 多轮记忆：对话历史持久化，重启后自动恢复最近 50 条
- 上下文压缩：长对话自动摘要（调用轻量 API），保留语义连续性
- 并行工具执行：独立工具调用并发运行（ThreadPoolExecutor，最多 4 线程）
- 工具结果缓存：同一请求中重复调用自动返回缓存
- 多模型辩论：可配置第二模型审阅主模型回复（需在 config 中启用）
- 暗色模式：一键切换，17 色全组件适配
- 对话搜索：Ctrl+F，结果黄色高亮
- 对话导出：Ctrl+S，保存为 Markdown
- 对话分支：Ctrl+B 保存快照，Ctrl+R 恢复
- Token 预算管理：单轮上限 32000 tokens，超限自动中止
- Python 3.8+
tkinter（Windows/macOS 自带；Ubuntu/Debian 需sudo apt install python3-tk）openai>=1.0.0
方式一：下载 EXE（推荐，无需 Python）
从 Releases 下载 v4-agent.exe，双击运行。
方式二：从源码运行
git clone https://github.com/kirisue/v4-agent.git
cd v4-agent
pip install -r requirements.txt
python v4_agent_gui.py在界面顶部设置栏：
- 输入 API Key
- 选择 Provider（DeepSeek / OpenAI / OpenRouter / Ollama / 自定义）
- 选择或手动输入 Model 名称
- 点击保存
配置保存在 v4_agent_config.json（已在 .gitignore 中排除）。
| 快捷键 | 功能 |
|---|---|
| Enter | 发送消息 |
| Shift+Enter | 输入框内换行 |
| Ctrl+F | 搜索对话内容 |
| Ctrl+S | 导出对话为 Markdown |
| Ctrl+B | 保存对话分支点 |
| Ctrl+R | 恢复到最近分支点 |
v4_agent_config.json 完整字段：
{
"api_key": "sk-...",
"model": "deepseek-v4-pro",
"provider": "deepseek",
"custom_base_url": "",
"debate": {
"enabled": false,
"model": "gpt-4o",
"provider": "openai",
"custom_url": ""
}
}| 字段 | 类型 | 说明 |
|---|---|---|
api_key |
string | API Key |
model |
string | 模型名（可手动输入任意值） |
provider |
string | deepseek / openai / openrouter / ollama / custom |
custom_base_url |
string | 自定义 API 地址（仅 custom 时生效） |
debate.enabled |
bool | 是否启用多模型辩论 |
debate.model |
string | 审阅模型名 |
debate.provider |
string | 审阅模型 Provider |
debate.custom_url |
string | 审阅模型自定义地址 |
对话历史保存在 v4_agent_history.json，自动截断到最近 50 条，防止文件无限增长。
┌─ GUI 层 (ChatWindow) ─────────────────────────────────┐
│ │
│ ┌─ 设置栏 ──┐ ┌─ 聊天区 (Text) ──┐ ┌─ 输入栏 ──┐ │
│ │ Provider │ │ user / assistant │ │ Text │ │
│ │ Model │ │ tool_start/result│ │ 发送/清屏 │ │
│ │ Key │ │ planner / error │ └───────────┘ │
│ └───────────┘ │ reasoning / sys │ │
│ └───────────────────┘ │
│ ┌─ 确认栏 (敏感操作) ──┐ ┌─ 状态栏 ──────────────┐ │
│ │ 同意 │ 拒绝 │ 同意全部│ │ 就绪 / 思考中 / Token │ │
│ └──────────────────────┘ └───────────────────────┘ │
│ │
│ _poll_queue() ←── msg_queue ←── run_agent_thread() │
│ │ │ │
│ ▼ ▼ │
│ chat_history ◄── history_sync ── messages[] │
│ │ │ │
│ ▼ ▼ │
│ load/save_history() _compress_context() │
└────────────────────────────────────────────────────────┘
后台线程执行流程:
history_list → Persona 路由 (_route_intent)
→ [system] + history → messages[]
→ while True:
├─ _compress_context() — 长上下文摘要
├─ 流式 API 调用 (stream=True)
│ ├─ reasoning_content → UI 灰色渲染
│ └─ content → UI 流式输出 + plan 回溯重绘
├─ 工具调用?
│ ├─ 确认检查 (_request_permission)
│ ├─ 并行执行 (ThreadPoolExecutor, timeout=30s)
│ ├─ 错误分析 (_analyze_error, 13 类)
│ ├─ 渐进式反馈 + 错误学习
│ └─ 行动后反思 (MISSING? → continue)
└─ 最终回答 → history_sync → done
在项目根目录创建 tools/ 文件夹，放入符合接口的 .py 文件即可自动注册：
# tools/my_tool.py
TOOL_NAME = "my_tool" # 可选，默认用文件名
TOOL_SCHEMA = {
"description": "我的自定义工具",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "查询参数"},
},
"required": ["query"],
},
}
def run(query: str) -> str:
return f"处理结果: {query}"重启后自动出现在工具列表中。
当前限制：
- 仅支持同步
run(**kwargs) -> str接口 - 无异步支持、无结构化错误上报
- 工具抛出异常时会被捕获并触发自动重试
| 版本 | 日期 | 变更 |
|---|---|---|
| v4 | 2026-06 | 初始发布：GUI 聊天窗口 + 流式输出 + 9 工具 + RAG + 暗色模式 + 多 Provider |
v1–v3 为内部迭代版本（CLI → 基础 GUI → 完整 Agent 循环），未公开发布。
MIT — 详见 LICENSE