🌐 English

ZhikunCode

开源 AI 编程助手 — 部署一次，浏览器全流程操控

多 Agent 协作 · Docker 自托管 · 国产大模型直连 · 深度安全架构

快速开始 · 核心特性 · 在线演示 · CLI 工具 · skill 技能系统 · 插件系统 · 可视化 · 记忆系统 · 竞品对比 · English

部署到服务器，打开浏览器就能用，手机上也行

🏗️ 查看完整系统架构图 →
三端分离 · 660+ 文件 · 110,646 行代码 · 全景可视化

🎬 Demo

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

https://github.com/user-attachments/assets/bf1f1d3a-4a9b-4d91-af48-97a7d3dd7b8a

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

https://github.com/user-attachments/assets/4b66261b-3258-44bd-82d3-6b2b3bbd4995

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

https://github.com/user-attachments/assets/7b45c5d4-e540-4ffd-80d4-e11502477dba

文件操作

生成游戏

优化代码

多 Agent 协作开发前后端应用

iPad 浏览器全流程操控

⚡ 快速开始

前置准备：获取 LLM API Key

本项目需要 LLM（大语言模型）API Key 才能运行。默认使用阿里云千问（DashScope），国内网络直连。

获取千问 API Key：

1. 访问 阿里云百炼平台 API Key 管理
2. 注册或登录阿里云账号
3. 创建 API Key，复制完整密钥（以 sk- 开头）

千问提供免费额度，足够个人开发使用。也可以使用 DeepSeek、Moonshot/Kimi 等国内服务商，详见下方"支持的 LLM 服务商"。

方式一：Docker 部署（推荐）

只需 3 步，从零到可用：

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

# 2. 配置 API Key
cp .env.example .env
# 编辑 .env，填入你的 LLM API Key（默认使用千问/DashScope，国内直连）

# 3. 启动
docker compose up -d

首次构建说明： 第一次运行会自动构建 Docker 镜像，需要下载依赖并编译，预计耗时 15-30 分钟（取决于网络速度）。后续启动只需几秒。可通过 docker compose logs -f 查看构建进度。

启动完成后，打开浏览器访问 http://localhost:8080 即可使用。

系统要求： Docker 20.10+，Docker Compose V2，建议 4GB+ 内存。

方式二：本地开发

前置条件： JDK 21、Node.js 22+、Python 3.11~3.12（不支持 3.13+）

git clone https://github.com/zhikunqingtao/zhikuncode.git
cd zhikuncode

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 LLM API Key

# 一键启动三端服务
./start.sh

三端服务会同时启动：

# 后端
cd backend && ./mvnw spring-boot:run -DskipTests

# Python 服务
cd python-service
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn src.main:app --host 0.0.0.0 --port 8000

# 前端
cd frontend && npm install && npm run dev

支持的 LLM 服务商

ZhikunCode 支持多 Provider 同时配置（推荐）和单 Provider 两种模式。多 Provider 模式下可在前端自由切换模型：

方式一：多 Provider 配置（推荐）

在 .env 中为每个服务商配置独立的 API Key，前端可自由切换：

# DashScope（千问系列）
LLM_PROVIDER_DASHSCOPE_API_KEY=your-dashscope-key

# DeepSeek
LLM_PROVIDER_DEEPSEEK_API_KEY=your-deepseek-key

# Moonshot (Kimi)
LLM_PROVIDER_MOONSHOT_API_KEY=your-moonshot-key

方式二：单 Provider 配置（向后兼容）

如未配置多 Provider，系统自动回退到单 Provider 模式。在 .env 中配置 LLM_BASE_URL 和 LLM_API_KEY 即可切换：

任何兼容 OpenAI API 格式的服务商都可以接入，只需配置对应的 Base URL 和 API Key。

可选：启用 DashScope 托管 MCP 服务

从最新版本起，为避免未配置阿里云百炼 Key 的用户遭遇启动日志刷屏，默认不启用以下托管在 dashscope.aliyuncs.com 上的 MCP 服务：

ℹ️ 不启用这些 MCP 完全不影响核心对话、代码编辑、本地工具使用。

如需使用（需要阿里云百炼 API Key 且在控制台开通相应 MCP 能力）：

1. 在 .env 中配置 DashScope Key：

   LLM_PROVIDER_DASHSCOPE_API_KEY=sk-xxxxxxxx
   

2. 在 backend/src/main/resources/application.yml 中取消 zhipu-websearch 配置块的注释。
3. 在 configuration/mcp/mcp_capability_registry.json 中把需要的条目 enabled 改为 true。
4. 通过 ./stop.sh && ./start.sh 完整重启三端使配置生效。

📊 竞品对比

功能对比

¹ 浏览器全流程操控：部署后任意设备浏览器（包括手机）即可完整操控编码全流程——权限审批、方案协商、任务管控。这与 Cline/Cursor 的"AI 控制浏览器做自动化测试"是不同的概念。

安全特性对比

说明： 以上对比基于各项目公开文档（截至 2026 年 4 月），AI 编程工具迭代迅速，如有不准确之处欢迎提 Issue 指正。Cline CLI 2.0、Cursor 2.0+、Claude Code Desktop、GitHub Copilot /fleet 等均在快速迭代中。

最新动态（2026 年 4 月）： Claude Code Desktop App 已发布（支持本地+云端混合执行）；Cursor 3.1 新增 Canvas 特性（交互式仪表盘+自定义 UI 组件）；各竞品最新版本号：Aider v0.86+、Cline v1.0.35+、Cursor 3.1+、Claude Code 2.1.119+、GitHub Copilot CLI 1.0.35+。

🏗️ 架构概览

ZhikunCode 采用三端分离架构，Java 后端负责核心编排，React 前端提供交互界面，Python 服务处理代码分析：

┌──────────────────┐      WebSocket / HTTP      ┌──────────────────────┐
│    Frontend       │ ◄────────────────────────► │      Backend          │
│  React 18 + TS    │                            │  Java 21 + Spring    │
│  Vite + Tailwind  │                            │  Boot 3.4            │
│  :5173 (dev)      │                            │  :8080               │
└──────────────────┘                            └──────────┬───────────┘
                                                           │ HTTP
                                                           ▼
                                                ┌──────────────────────┐
                                                │   Python Service      │
                                                │   FastAPI + Uvicorn   │
                                                │   :8000               │
                                                └──────────────────────┘

各层职责

Docker 部署架构

生产环境通过 Docker 单容器部署，三端服务打包在同一个镜像中：

┌─────────────────────────────────────────────────┐
│                Docker Container                  │
│  ┌───────────┐  ┌───────────┐  ┌──────────────┐ │
│  │  Backend   │  │  Python   │  │   Frontend   │ │
│  │  :8080     │  │  :8000    │  │  (静态文件)   │ │
│  └───────────┘  └───────────┘  └──────────────┘ │
│                                                  │
│  Volume: zhikun-data (SQLite + 会话数据)          │
│  Volume: workspace (用户项目代码)                  │
├──────────────────────────────────────────────────┤
│  Port: 8080 → 宿主机                              │
└──────────────────────────────────────────────────┘

Agent Loop 查询循环

ZhikunCode 核心执行引擎 QueryEngine 通过 8 步循环驱动 Agent 决策与工具执行：

压缩级联 → 流式会话创建 → API 调用(含降级保护) → 响应收集 → 工具结果消费 → 继续/终止判定 → 工具摘要注入 → 状态更新

关键子系统：

413 三阶段恢复：当 API 返回 413 (Payload Too Large) 时，自动执行三阶段恢复：

1. Phase 1 — 激进压缩（Context Collapse Drain）
2. Phase 2 — 反应式压缩（Reactive Compact）
3. Phase 3 — 媒体文件剥离（Media Recovery）

🔒 安全架构

安全是 ZhikunCode 的核心设计原则。每一条命令执行前，都要经过多层安全检查。

8 层 Bash 安全沙箱

所有 Shell 命令执行前，必须通过以下 8 层检查：

14 步权限管道

权限管道采用短路返回设计 —— 命中任何拦截规则立即返回，不继续执行：

请求进入
  │
  ├─ 1. Deny 规则检查 ──────────── 命中 → 拒绝
  ├─ 2. Ask 规则检查 ───────────── 命中 → 询问用户
  ├─ 3. 工具自身权限检查 ────────── 工具拒绝 → 阻断
  ├─ 4. 用户交互需求检查 ────────── 需要交互 → 询问
  ├─ 5. 内容级危险检测 ─────────── rm -rf、chmod 777、eval、sudo 等 → 强制询问
  ├─ 6. 写路径安全检查 ─────────── 危险目录、符号链接 → 阻断
  ├─ 7. 危险删除检测 ───────────── rm 危险目标 → 阻断
  ├─ 8. 环境变量检查 ───────────── 非白名单变量 → 阻断
  ├─ 9. Hook 注入检查 ──────────── PreToolUse Hook 可阻断
  ├─ 10. 分类器评估 ────────────── AI 风险评估（AUTO 模式）
  ├─ 11. 沙箱规则评估 ──────────── 沙箱内操作自动放行
  ├─ 12. 紧急杀开关 ────────────── 管理员可临时禁用 AUTO
  ├─ 13. AlwaysAllow 规则 ─────── 匹配白名单 → 放行
  └─ 14. 模式分支决策 ──────────── DEFAULT/PLAN/AUTO/BYPASS 等模式最终决策

受保护路径

以下路径即使在 bypass 模式下也需要用户确认：

• .git — Git 仓库数据
• .env — 环境变量和密钥
• .ssh — SSH 密钥
• .gnupg — GPG 密钥
• .aws — AWS 凭证

安全测试

• 289 项安全测试覆盖全部安全路径
• 包含命令注入、路径穿越、权限绕过等攻击场景
• 每次代码变更都会执行完整安全测试套件

🧪 质量验证

完整功能测试报告见 ZhikunCode 核心功能测试报告 v9.1（2026-05-06）

持续集成：

• GitHub Actions 自动化流水线：每次提交自动执行后端编译验证、前端构建、Python 测试及 Docker 镜像构建

测试覆盖：

• 22 个功能模块完整测试，326 个测试用例
• 结果：321 PASS / 4 PARTIAL / 1 OBSERVE / 0 FAIL，通过率 98.5%
• 自动化框架：JUnit 5 + Vitest + Pytest + Playwright 四层覆盖
• 单元测试体系（v9.1 新增）：277 个测试方法 / 30 个测试文件 / 12 个首次覆盖功能域
• 功能完整性验证：100% 覆盖 v1.0 规划功能

测试框架详情：

详细测试数据与证据：

• 分模块测试结果：docs/test-results/
• 前端 E2E 脚本：frontend/e2e/（含 tc-fe-003~005 等）
• E2E 截图证据：docs/test-results/screenshots/（125+ 张）

🎯 skill 技能系统

ZhikunCode 的 skill 技能系统（Skill System）是一个 Markdown 驱动的可扩展工作流引擎。每个技能就是一个 .md 文件，用 YAML frontmatter 定义元数据，用 Markdown 正文定义执行指令。

6 个内置技能

开箱即用，输入 /技能名 即可调用：

6 级加载源优先级

同名技能按优先级链覆盖，高优先级自动屏蔽低优先级：

managed > user > project > plugin > bundled > mcp

自定义技能

在 ~/.zhikun/skills/ 或项目根目录 .zhikun/skills/ 下创建 .md 文件：

---
description: "将代码翻译为指定语言"
arguments:
  - language
---

# 翻译任务

将用户选中的代码翻译为 {{language}}，保持原有逻辑和注释风格。

调用方式：/translate language=python 或 /translate python

支持的 frontmatter 字段：

技能文件支持热重载 — 保存后自动生效，无需重启服务。底层使用 Java NIO WatchService + 500ms 防抖机制监听文件变更。

🧩 插件系统

ZhikunCode 的插件系统通过标准 Java SPI（ServiceLoader） 机制发现和加载第三方 JAR 插件，提供四大桥接能力：命令注册、工具注册、钩子拦截、MCP 服务器集成。通过 plugin.enabled Feature Flag 控制启停。

四大桥接能力

安全特性

• PluginClassLoader 沙箱隔离 — 插件通过包白名单访问宿主 API：核心 API 包（com.aicodeassistant.plugin.*、tool.*、command.*、mcp.*）、标准库（java.*、javax.*、jdk.*、sun.*、org.slf4j.*）、基础框架（org.springframework.*、com.fasterxml.jackson.*、jakarta.*）。未在白名单中的宿主类访问会抛出 ClassNotFoundException
• 钩子执行超时保护 — Virtual Thread + CompletableFuture.orTimeout(5s)，超时自动放行，防止插件阻塞主流程
• JAR 文件验证 — 加载前校验文件存在性、JAR 格式合法性、大小限制（默认 50MB）、SPI 配置文件（META-INF/services/）完整性
• API 版本兼容检查 — 插件声明 minApiVersion / maxApiVersion，宿主自动校验兼容性

热重载机制

支持运行时重新加载所有插件，无需重启服务：

• 使用 ReentrantReadWriteLock 保证热重载期间的并发安全
• 重载流程：卸载所有插件（注销命令/工具/钩子/MCP + 关闭 ClassLoader）→ 重新扫描加载
• 触发方式：/reload-plugins 斜杠命令 或 REST API

8 种钩子事件类型

插件可注册以下事件钩子，在关键节点执行自定义逻辑：

插件开发指南

开发一个 ZhikunCode 插件只需四步：

1. 实现 PluginExtension SPI 接口

public class MyPlugin implements PluginExtension {
    @Override public String name() { return "my-plugin"; }
    @Override public String version() { return "1.0.0"; }

    @Override
    public List<Command> getCommands() {
        return List.of(/* 自定义命令 */);
    }

    @Override
    public void onLoad(PluginContext ctx) {
        ctx.getLogger().info("Plugin loaded!");
    }
}

2. 在 META-INF/services/ 中注册 SPI

# META-INF/services/com.aicodeassistant.plugin.PluginExtension
com.example.MyPlugin

3. 将 JAR 放入 ~/.zhikun/plugins/ 目录

4. 重启服务或执行 /reload-plugins 热重载

PluginExtension 接口采用默认方法设计 — 最小实现仅需 name() 和 version()，其余能力（命令/工具/钩子/MCP）按需覆写。

🧠 记忆系统

ZhikunCode 内置三层记忆架构，让 AI 助手能够 跨会话记住你的偏好、项目约定和工作流程。

三层记忆架构

记忆分类

基于认知心理学模型的设计分类（实现层面通过文件路径和元数据标签区分），记忆自动归类为四种类型：

自动记忆与搜索

AI 在交互过程中通过内置的 MemoryTool 自动记录和检索记忆：

• 自动写入 — AI 发现重要信息时主动记录（用户偏好、项目规范等）
• 自动加载 — 每次会话启动时自动注入系统提示，无需手动操作
• BM25 搜索 — 纯 Java 实现的 BM25 搜索引擎，支持中英文混合检索（Unigram + Bigram 中文分词）
• 来源追踪 — 支持记忆来源追踪（source 字段），区分 REST API 创建与 LLM 工具创建的记忆
• LLM 重排 — 可选的 LLM 精排服务，BM25 粗筛后由大模型进行相关性精排

项目记忆文件

在项目根目录创建记忆文件，AI 会自动读取并遵循：

# zhikun.md — 项目约定（随代码库提交）

## 编码规范
- Java 方法命名使用 camelCase
- 测试类以 Test 结尾

## 构建流程
- 提交前必须跑 `./mvnw test`
- Commit 采用 Conventional Commits 格式

# zhikun.local.md — 本地配置（不提交，加入 .gitignore）

## 本地环境
- 我的 API Key 在 .env 文件中
- 本地数据库端口: 5432

项目记忆文件向上遍历 5 层目录加载，单文件上限 100KB。zhikun.md 随代码库提交用于团队共享，zhikun.local.md 用于个人本地配置。

安全保护

• 截断保护：个人记忆最多 200 行 / 25KB，防止系统提示 Token 爆炸
• 自动压缩：超出 50,000 字符时自动压缩，保留最新 70%
• 自动过期：90 天未访问的记忆自动清理
• 路径穿越防护：项目记忆写入时校验绝对路径和符号链接

💻 CLI 工具

除了 Web UI，ZhikunCode 还提供完整的命令行能力，覆盖三种场景：

Python CLI（aica）— 终端 AI 编程

aica 是 ZhikunCode 的命令行客户端，设计为 UNIX 管道一等公民：

# 安装
cd python-service
pip install -e ".[cli]"

# 基础使用
aica "帮我重构这个函数"

# 管道输入 — 像 grep/sed 一样组合
cat src/main.py | aica "review this code"

# 结构化输出 + jq 处理
aica -f json "list all API endpoints" | jq '.result'

# 流式输出
aica -f stream-json "refactor this module"

# 继续上次对话
aica --continue "fix the bug we just discussed"

核心特性：

aica 通过 HTTP/SSE 连接 ZhikunCode 后端，共享同一套 Agent 引擎、工具集和安全架构。适合 CI/CD 集成和脚本自动化场景。

35+ 斜杠命令 — Web UI 快捷操作

以下斜杠命令在 Web UI 中使用，aica CLI 通过自然语言 prompt 访问后端 Agent 引擎实现相同能力。

在 Web UI 中输入 / 或按 Ctrl+K 打开命令面板，支持模糊搜索和键盘导航：

命令输入错误时，系统会基于 Levenshtein 距离自动建议相似命令。

📱 浏览器全流程操控

这是 ZhikunCode 的核心差异化特性。与 Cursor、Cline 等需要安装桌面客户端或 IDE 插件的工具不同，ZhikunCode 是一个独立的 Web 应用 —— 部署一次，任何设备的浏览器都能用。

为什么这很重要？

完整的浏览器操控能力

通过浏览器，你可以完成 AI 编程的全部流程：

• 对话式编程 — 输入自然语言需求，Agent 自动生成代码，实时流式输出
• 权限审批 — 每个敏感操作都会弹出审批请求，你可以 允许/拒绝/修改
• 方案协商 — Agent 提出方案后可以在浏览器中讨论、修改、确认
• 任务管控 — 查看任务进度、中断执行、重新分配
• 文件浏览 — 在浏览器中直接查看和导航项目文件树
• Agent 协作可视化 — 多 Agent 模式下实时查看各 Agent 工作状态

实时通信

前后端通过 STOMP over SockJS 保持实时连接（自动协商 WebSocket → xhr-streaming → xhr-polling 降级）：

• 流式输出 — LLM 响应逐字输出，无需等待完成
• 权限冒泡 — 子 Agent 的权限请求实时推送到浏览器
• 状态同步 — Agent 工作状态变化即时反映在 UI 上
• 心跳保活 — 双向 10s 心跳检测，断线自动重连（指数退避 1s→10s）
• 消息保障 — 128KB 消息大小限制，1MB 发送缓冲，30s 发送超时

🤖 多 Agent 协作

ZhikunCode 提供三种 Agent 协作模式和五种类型化 Agent，适用于不同复杂度的任务。

五种内置 Agent 类型

基于 Java 21 sealed interface 实现编译期穷尽性检查，每种 Agent 有独立的工具集、模型偏好和系统提示：

所有子 Agent 均禁止调用 Agent/TeamCreate/TeamDelete 工具，从架构层面防止无限递归。

Team 模式 — 固定分工

预定义角色的团队协作。每个 Agent 有明确的职责和工具集。

┌─────────────┐
│   Leader     │  任务分配与结果聚合
└──────┬──────┘
       │
  ┌────┴────┐
  ▼         ▼
┌──────┐ ┌──────┐
│Agent A│ │Agent B│  并行执行，独立工具集
│后端开发│ │前端开发│
└──────┘ └──────┘

• 适用场景：前后端分离开发、测试+开发协作
• 通过 TeamMailbox 进行 Agent 间异步消息传递（ConcurrentLinkedQueue）
• 通过 SharedTaskList 共享 FIFO 任务队列，支持任务认领与状态追踪
• InProcessBackend 使用 Virtual Thread 并发执行多个 Worker

Swarm 模式 — 动态协商

基于 Java 21 虚拟线程的动态多 Worker 协作，由 Coordinator 编排四阶段工作流：

Research → Synthesis → Implementation → Verification

四阶段严格顺序不可跳过，每个阶段记录时间戳和结果摘要。CoordinatorWorkflow 管理完整的阶段生命周期。

• 适用场景：复杂重构、大规模代码迁移
• Worker 数量动态调整，无需预声明
• 每个 Worker 一个 Virtual Thread，30 分钟超时保护
• Worker 工具集通过 allowList/denyList 精确控制
• 权限冒泡到 UI（LeaderPermissionBridge），60 秒超时自动拒绝防止死锁
• 实时状态通过 STOMP WebSocket 推送到前端
• 活跃 Swarm 使用 Caffeine 缓存管理，4 小时 TTL 自动清理异常实例

SubAgent 模式 — 主从委派

主 Agent 将子任务委派给独立的子 Agent 执行，支持三种隔离级别：

• 支持后台异步执行（BackgroundAgentTracker），通过 WebSocket 推送启动/完成/失败事件
• 单个 Agent 5 分钟超时，结果最大 100,000 字符截断保护

三层并发安全

AgentConcurrencyController 通过 Semaphore + 会话级计数器强制执行三层限制：

槽位通过 RAII 模式（try-with-resources）自动释放，确保异常路径不会泄漏资源。

模型别名路由

Agent 使用三级回退策略解析模型：用户参数 → Agent 类型默认 → 全局默认。通过 application.yml 中的 agent.model-aliases 配置别名映射（如 light → qwen-plus），避免硬编码模型名称，一处配置全局生效。

🧩 MCP 工具扩展

ZhikunCode 实现了标准的 MCP（Model Context Protocol） 协议，支持通过 SSE 传输层连接外部 MCP 服务：

内置 MCP 工具

自定义 MCP 工具

在 configuration/mcp/mcp_capability_registry.json 中注册新的 MCP 工具：

{
  "id": "mcp_your_tool",
  "name": "你的工具名称",
  "toolName": "mcp_server_tool_name",
  "sseUrl": "https://your-mcp-server/sse",
  "domain": "your_domain",
  "category": "MCP_TOOL",
  "enabled": true
}

🛠️ 内置工具集

ZhikunCode 内置 48 个工具 + MCP 动态扩展，覆盖开发全流程：

📈 可视化

ZhikunCode 内置 11 项可视化能力，让 AI 编程过程中的数据和状态一目了然：

⚙️ 配置说明

环境变量

环境变量通过 .env 文件管理。复制 .env.example 后按需修改：

多 Provider 配置（推荐）：

多 Provider 模式下至少配置一个 Provider 的 API Key 即可。前端支持自由切换已配置的 Provider。

单 Provider 配置（向后兼容）：

如 LLM_PROVIDER_* 均为空，系统自动回退到单 Provider 模式。

通用配置：

高级配置：

上下文管理配置（application.yml）：

Docker 资源限制

默认资源配置（可在 docker-compose.yml 中调整）：

注意： 首次构建镜像期间需要更多内存（Maven 编译 + npm build）。如果构建失败，请在 Docker Desktop 设置中增加内存分配至 6GB 以上。运行时容器内存上限为 4GB（可在 docker-compose.yml 中调整）。

❓ FAQ

git clone https://github.com/zhikunqingtao/zhikuncode.git && cd zhikuncode
cp .env.example .env  # 编辑填入 API Key
docker compose up -d  # 启动

# 查看容器状态
docker ps -a

# 查看启动日志（Java 启动通常需要 30-60 秒）
docker logs zhikuncode

# 查看健康检查详情
docker inspect --format='json .State.Health' zhikuncode | python3 -m json.tool

# 实时跟踪日志
docker logs -f zhikuncode

# 进入容器查看日志文件
docker exec -it zhikuncode ls -la /app/log/
docker exec -it zhikuncode tail -100 /app/log/app.log

JAVA_OPTS=-Xms512m -Xmx2048m --enable-preview

ZHIKUN_PORT=9090  # 改为任意未被占用的端口

docker compose down
docker compose up -d

🤝 贡献

我们欢迎任何形式的贡献 —— Bug 修复、新功能、文档改进都可以。

详见 CONTRIBUTING.md。

📄 开源协议

本项目使用 MIT License 开源协议。

📬 联系

• 邮箱： alizhikun@gmail.com
• GitHub Issues： 提交问题

⭐ Star History

如果这个项目对你有帮助，欢迎点个 Star ⭐