开源 · MIT License

ZhikunCode

浏览器即操控台，一键部署的 AI 编程助手
多 Agent 协作 · Docker 自托管 · 国产大模型直连 · 数据完全私有

⭐ Star on GitHub 🚀 快速开始

看看它能做什么

一句话生成完整功能，多 Agent 协作完成复杂任务

写入文件

写入文件演示

iPad 浏览器全流程操控

iPad浏览器操控演示

📱 手机开发前后端 TODO 应用完整演示

自动写代码下载小红书视频

📱 项目分析和命令执行演示

📐 深入了解系统架构

Explore the System Architecture

三端分离 · 660+ 文件 · 110,646 行代码

Java Spring Boot
后端引擎 / Backend Engine
React TypeScript
前端交互 / Frontend UI
Python
AI 服务 / AI Service

三端分离架构全景插画

React 前端 19,543 行 · 137 文件 32 Store 86 组件 14 可视化 dispatch 437 358 dispatch.ts 437行 · stompClient.ts 358行 REST + WS/STOMP HTTP Proxy Java 后端 65,654 行 · 433 文件 · Spring Boot 3.4 Agent Engine 5,942行 Permission 18步 752行 Tool System 47工具 16,815行 MCP Protocol 5传输 5,219行(main) LLM Provider 2,911行 Multi-Agent 29类 5,824行 Bash Security 5层AST 5,091行 Context Mgmt 5层压缩 :8080 Python 分析服务 7,213 行 · 32 文件 · FastAPI Analyzers Services 7 Routers tree-sitter :8000 LLM APIs MCP Servers Docker 沙箱 文件系统 Java 65,654行 React 19,543行 Python 7,213行 通信链路 外部服务

全局数据流与模块依赖全景图

User (Browser) REACT FRONTEND 86 Components 32 Zustand dispatch.ts stompClient.ts 14 Viz JAVA BACKEND (65,654 lines) Agent Loop engine/ 5,942行 Permission 18步 2,672行 Bash Security 5-layer AST 5,091行 Tool System 144文件 16,815行 47工具 LLM Provider 22文件 2,911行 MCP Protocol 30文件(main) 5,219行 Multi-Agent 29类 5,824行 Context Mgmt 5层压缩 Memory 1,089行 BM25+LLM Skill 1,169行 6级加载 Security 1,248行 黑名单+审计 Sandbox Docker隔离 316行 PYTHON SERVICE (7,213 lines) Analyzers (2,872行) 7 API Routers (1,526行) Services (1,725行) REST + WS Vite Proxy LLM APIs MCP Servers Docker Engine File System Browser (CDP) Legend: Frontend → Backend Frontend → Python Internal Dependency External Service Call

多Agent协调系统架构全景

Coordinator 指挥中心 CoordinatorService.java — 模式管理 · 仅4个工具 Agent TaskStop SendMessage SyntheticOutput ① Research 信息收集与需求理解 • 调研代码库结构 • 分析需求与上下文 • 收集相关依赖信息 denied: Agent FileEdit FileWrite ② Synthesis 整合分析与方案设计 • 整合调研成果 • 设计技术方案 • 制定实施计划 denied: Agent FileEdit FileWrite ③ Implementation 代码实现与集成 • 并行代码编写 • 多Worker协作实施 • 模块集成与联调 allowed: * (GENERAL_PURPOSE) ④ Verification 测试与验证 • 运行测试套件 • 验证功能正确性 • 质量检查与回归 denied: FileEdit FileWrite 调研完成 方案确定 实施完成 Worker 池 — 并行执行 可用工具: ~35个（除4个内部工具外全部） SwarmWorkerRunner 332行 · Worker生命周期 SwarmService 463行 · Worker池管理 Worker #1 Worker #2 Worker #3 Worker #N 通信与协调机制 TeamMailbox 109行 writeToMailbox() → readMailbox() Worker↔Coordinator 双向消息 SharedTaskList addTask→claimTask→complete 跨Worker任务流转 Scratchpad .zhikun/scratchpad/ 文件交换区 双向 SharedTaskList 任务流转 SharedTaskList.java — addTask/claimTask/completeTask 三步流转 PENDING claim IN_PROGRESS done COMPLETED or FAILED TeamMailbox 消息流 write → poll → read · broadcast() ConcurrentLinkedQueue 无锁实现 关键模块 CoordinatorWorkflowEngine 436行 — 4阶段编排引擎 LeaderPermissionBridge 162行 — 权限冒泡桥接 ResultAggregator 结果聚合 → Coordinator SubAgentExecutor 918行 · 权限冒泡 ResultAggregator → Coordinator 结果回传 coordinator/ 17文件 3,777行 29个协调类 4阶段工作流 3通信机制 ~35工具/Worker WorkflowPhase.java — sealed interface permits Research | Synthesis | Implementation | Verification · phasePrompt() + allowedTools() + phaseIndex()

Agent Loop 8步循环引擎

QueryEngine.java — 1,038行 · 8步循环 · 流式工具执行 1 压缩级联 ContextCascade AutoCompact·上下文窗口 2 创建流式会话 StreamingToolExecutor 初始化工具执行上下文 3 API调用+降级 LlmProvider.streamChat 流式执行·413恢复·降级链 4 收集API响应 StreamCollector chunk聚合·工具调用提取 5 消费工具结果 并行执行·异步等待 权限检查→并行→收集 6 继续/终止判定 end_turn·max_tokens StopHook自定义拦截 7 工具摘要注入 ToolResultSummarizer LLM压缩·预算控制 8 状态更新 消息历史追加 统计更新·回到Step1 LOOP Step 6 判定分支 继续循环 有工具调用 → Step7 → Step1 返回结果 end_turn信号 → 输出给用户 错误恢复 max_tokens → 截断 → 重试 核心步骤 LLM API调用 执行/循环 判定节点 循环路径 分支决策

5+1 层级联上下文压缩管道

5+1 层级联上下文压缩管道 — ContextCascade.java 340行 · 统一协调器 ContextCascade · 编排器 每次 API前 执行 L0-L2 低代价 L3-L4 错误 恢复 L0 Snip SnipService.java 150 行 单条工具结果超预算 → 截断中间保留首尾 触发: toolResult > contextWindow × 0.3 × 3.5 L1 MicroCompact MicroCompactService.java 183 行 旧可压缩工具结果 → 替换为 "[cleared]" 触发: 每次API调用前无条件执行 · protectedTail=10 L1.5 ContextCollapse ContextCollapseService.java 283 行 三级渐进折叠: Full(尾10) → Summary(10-30) → Skeleton(30+) 触发: 每次API调用前 · CollapseLevel sealed interface 54行 L2 AutoCompact ★ CompactService.java 1,058 行 三区划分(冻结/压缩/保留) + 3级降级: LLM摘要 → 关键消息 → 尾截断 触发: tokens > effectiveWindow - 13,000 buffer 阈值: 85% · 目标: 50% · 摘要上限: 4,096 tokens · 保留最近3轮 413 错误 ↓ L3 CollapseDrain CompactService.compact() 激进压缩 → contextWindow × 0.5 目标 触发: API返回413 · 第一次错误恢复尝试 L4 ReactiveCompact CompactService.reactiveCompact() 最后手段 — 仅保留1轮 + 极度压缩 + 防死亡螺旋 触发: L3失败 · 仅允许执行一次 · 失败则完全终止 TokenCounter 257 行 三层精度估算 ① 字符粗估 ② 类型调整 ③ tiktoken精算 中文: 2.0 char/tk JSON: 2.0 char/tk 代码: 3.5 char/tk 混合: 3.5 char/tk 参与所有层级决策 TokenBudget Tracker 89 行 续写预算追踪 完成阈值: 90% 递减检测: 500tk 电路断路器: 连续3次失败 配合L2预算管理 数据流: 原始消息 → Snip截断 → 清除旧结果 → 渐进折叠 → LLM摘要 → 压缩后消息 错误恢复: API 413 → CollapseDrain(50%目标) → 失败 → ReactiveCompact(保留1轮) → 失败 → 终止 压缩系统统计 核心文件 CompactService1,058行 ContextCascade340行 CollapseService283行 TokenCounter257行 MicroCompact183行 SnipService150行 辅助文件 BudgetTracker89行 CollapseLevel54行 共 11 个文件 · 2,698 行

18步权限管线全景流程

PermissionPipeline.java — 752行 · 18步 · 3阶段 决策树结构 — 每步匹配即短路返回，不走完所有步骤 · 🔒 = bypass免疫（即使bypass=true也会拦截） STAGE 1: 拒绝 / 询问规则 11 步 — 安全过滤（短路决策树） DENY 返回 ASK 返回 1a deny规则 显式拒绝→DENY findDenyRule() 1b ask规则 需询问→ASK findAskRule() 1c 工具权限 checkPermissions() →DENY/ASK/PASS 1d 工具拒绝 DENY→短路 PermBehavior.DENY 1e 用户交互 requiresInteraction →ASK短路 🔒 1f 内容级ask bypass 免疫 裸shell+危险模式 🔒 1f-pre 命令黑名单 bypass 免疫 ABSOLUTE_DENY/ASK 1f-w 危险文件写入 .env/密钥→DENY/ASK PathSecurityService 1f-b 危险Bash rm -rf/export→ASK env变量篡改检测 🔒 1g 安全检查 bypass 免疫 .git/.zhikun/.env/.ssh 1h Hook规则注入 PreToolUse Hook proceed=false→ASK 1i Classifier注入 仅auto模式 高风险命令→ASK 1j Sandbox覆盖 Docker放宽权限 沙箱内→ALLOW 🔒 1k 敏感文件 bypass 免疫 /etc/passwd ~/.ssh → DENY → ASK 全部通过 → Stage2 🔒 1f · 1f-pre · 1g · 1k = 4步 bypass免疫，无法绕过 仅当 Stage1 全部通过 STAGE 2: 允许规则 2 步 — 授权放行 2a bypass模式 BYPASS/PLAN+bypass → ALLOW 2b alwaysAllow 持久化允许列表 → ALLOW 匹配 → ALLOW 未匹配 → passthrough STAGE 3: 模式转换 passthrough → ask → 7 模式分支 passthrough → ask 只读NONE → ALLOW DEFAULT 用户确认 PLAN 只读放行 ACCEPT_EDITS 编辑放行 DONT_ASK 写→DENY BYPASS 全部放行 AUTO LLM两阶段 BUBBLE 冒泡父Agent AUTO: killswitch检查 → LLM分类 classify() → ALLOW / ASK(降级) 最终决策: ALLOW / DENY / ASK / BUBBLE

Bash 安全模块 AST 解析流水线

Bash Command Input BashTool.java 515行 → 入口 L1 词法分析 Lexer BashLexer.java 824行 BashToken.java 47行 BashTokenType.java 82行 L2 语法分析 Parser → AST BashParserCore.java 1,116行 BashParser.java 51行 递归下降解析 L3 AST遍历 — 节点分析 + 命令识别 BashAstNode.java 189行 ParseForSecurityResult.java 46行 HeredocExtractor 196行 L4 风险评分 — 危险命令检测 BashSecurityAnalyzer.java 771行 BashCommandClassifier.java 1,105行 L5 路径验证 + 命令校验 PathValidator 341行 SedValidator 204行 ShellStateManager 119行 L6 沙箱隔离执行 SandboxManager 259行 SandboxConfig 57行 Docker容器隔离 危险命令示例 rm -rf / chmod 777 /etc/passwd curl | bash dd if=/dev/zero of=/dev/sda export PATH="" mkfs.ext4 /dev/sda :(){ :|:& };: → DENY / ASK 安全分析结果 Simple → ALLOW TooComplex → ASK ParseUnavailable → DENY 覆盖 CWE 风险指标 CWE-78 命令注入 CWE-94 代码执行 CWE-22 路径穿越 CWE-73 文件劫持 沙箱决策分支 低风险 直接执行 中风险 用户确认 高风险 Sandbox SandboxManager 259行 · Docker隔离 tool/bash/ 13文件 · 5,091行 | sandbox/ 2文件 · 316行 | security/ 5文件 · 1,248行 | 总计 20文件 · 6,655行
🔗 查看完整系统架构图 / View Full Architecture →

核心特性

不是又一个 Copilot 插件，而是独立运行、完整可控的 AI 编程平台

🌐

浏览器全流程操控

部署一次，任何设备浏览器全流程操控。权限审批、方案协商、任务管控，手机和电脑体验一致，无需安装任何客户端。

🐳

Docker 一键部署

docker compose up -d 即可启动。数据完全私有，适合企业内网部署。端口 8080，打开即用。

🇨🇳

国产大模型直连

千问 / DashScope 开箱即用，无需科学上网，国内网络满速响应。也支持 OpenAI 兼容 API。

🔒

8 层安全架构

8 层 Bash 沙箱 + 14 步权限管道 + 289 项安全测试。不是"能跑就行"，而是生产级安全保障。

🤖

多 Agent 协作

Team / Swarm / SubAgent 三种协作模式，处理复杂的跨文件、跨模块任务，效率倍增。

🧩

41 个内置工具 + MCP 动态扩展

文件操作、终端执行、搜索替换、MCP 扩展……开箱即有 41 个内置工具，标准 MCP 协议支持动态扩展。

安全不是附加功能，是核心架构

三层纵深防御，每一层都有明确的职责边界

8
层 Bash 沙箱
命令白名单、路径约束、超时熔断、资源配额……层层拦截恶意操作
14
步权限管道
从用户意图解析到最终执行，14 步流水线确保每一步都经过安全审查
289
项安全测试
覆盖注入攻击、路径穿越、权限提升等场景，CI 管道强制通过

和同类工具对比

独立部署、浏览器驱动、数据私有——这才是我们的核心差异

能力 ZhikunCode Aider Cline Cursor Claude Code Copilot
开源✅✅✅❌❌❌
Web UI✅ 全功能⚠️ Streamlit❌⚠️ Web版✅❌
Docker 自托管✅ 完整 Web 服务⚠️ CLI 容器化❌⚠️ 企业付费❌❌
多 Agent 协作✅ Team/Swarm/Sub❌❌✅ Multi-Agents✅ Sub-Agents✅ Agent Mode
国产大模型直连✅ 原生支持⚠️ 需配置⚠️ 需配置❌❌❌
浏览器全流程操控*✅❌❌❌❌❌
安全沙箱✅ 8层❌❌⚠️ 企业级✅ OS级N/A
MCP 工具扩展✅⚠️ 第三方✅❌✅✅
无需安装客户端✅❌❌⚠️✅❌

* 浏览器全流程操控：部署后任意设备浏览器即可完整操控编码全流程。基于 2025 Q2 各项目公开文档。

3 步开始

从零到可用，只需 1 分钟

# 1. 克隆仓库
git clone https://github.com/zhikunqingtao/zhikuncode.git && cd zhikuncode

# 2. 配置（编辑 .env，填入你的 API Key）
cp .env.example .env

# 3. 启动
docker compose up -d

# 🎉 打开 http://localhost:8080 开始使用