🌐 English

ZhikunCode

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

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

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

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

🏗️ 查看完整系统架构图 →
Java Agent Runtime · React 浏览器操作面 · Python Capability Service · 全景可视化

🏆 SWE-bench Lite 技术报告 →
提交命名空间 20260525_zhikuncode · 官方 harness 评测 Resolve 168 / 300 (56.0%) · Patch 生成率 284 / 300 (94.7%)

🎬 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

RV-1 运行时验证依赖：jsonpath-ng（JSONPath 断言引擎）、httpx（异步 HTTP 客户端），已包含在 python-service/requirements.txt 中。

权限数据说明： 当前授权架构以 V015 持久交互和 V019 受约束 Grant 为数据库权威，不读取旧权限表。开发环境升级时直接重建项目数据库，并在新版本中重新授权。

支持的 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

# Zhipu (智谱 GLM)
LLM_PROVIDER_ZHIPU_API_KEY=your-zhipu-api-key-here

# MiniMax
LLM_PROVIDER_MINIMAX_API_KEY=your-minimax-api-key-here

# ZenMux (claude-opus-4.8 / claude-fable-5 / openai/gpt-5.6-sol / google/gemini-3.5-flash, 1M 上下文)
LLM_PROVIDER_ZENMUX_API_KEY=your-zenmux-api-key-here

方式二：单 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 完整重启三端使配置生效。

🏆 SWE-bench Lite 评测

ZhikunCode 已完成 SWE-bench Lite（300 实例，pass@1）官方 harness 评测，Resolve Rate 56.0% (168/300)。所有评测产物（all_preds.jsonl、results.json、metadata.yaml、轨迹）已开源在 docs/swe-bench/20260525/，可第三方复现。

关键指标

仓库级表现（results/resolved_by_repo.json）

工程亮点（每一项均可在源码定位）

• Agent-Loop 显式四相位 ANALYZE→LOCATE→FIX→VERIFY，相位边界由系统提示硬约束（swe_bench.py）
• 六层上下文压缩级联 Snip / MicroCompact / ContextCollapse / AutoCompact / CollapseDrain / ReactiveCompact（ContextCascade.java，源码注释中 Level 1.5 ContextCollapse 为渐进折叠中间层）
• 413 两阶段恢复 CollapseDrain → ReactiveCompact，保障 60 轮会话收敛于上下文窗口内
• 自纠错循环（SelfCorrectionLoop） 编译/测试失败结构化再提示，默认 MAX_ATTEMPTS=3，SWE-bench 模式提升至 7 次（SelfCorrectionLoop.java）

📄 完整方法学与可复现命令见技术报告：https://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html

📊 竞品对比

功能对比

¹ 浏览器全流程操控：部署后任意设备浏览器（包括手机）即可完整操控编码全流程——权限审批、方案协商、任务管控。这与 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 差异化能力展示

🏗️ 架构概览

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 → 宿主机                              │
└──────────────────────────────────────────────────┘

核心引擎（Core Engines）

ZhikunCode 的智能决策由以下核心引擎协同驱动：

Agent Loop 查询循环

ZhikunCode 的 QueryEngine 通过多步迭代循环驱动 Agent 决策与工具执行：

压缩级联（ContextCascade）→ 流式会话创建 → API 调用（含熔断、自适应重试和降级保护）→ 响应收集 → 工具结果消费（ToolExecutionPipeline）→ 终止评估 → 工具摘要注入 → 状态更新

关键子系统：

413 两阶段恢复：当 API 返回 413 (Payload Too Large) 时，自动执行两阶段恢复（源码 ContextCascade.java recoverFromPayloadTooLarge）：

1. Level 3 — CollapseDrain 激进压缩（contextWindow × 0.5 目标）
2. Level 4 — ReactiveCompact 反应式压缩（仅保留 1 轮 + 极度压缩）

🔒 安全架构

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

8 层 Bash 安全沙箱

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

统一工具授权流程

所有核心工具执行都经过同一条不可绕过的授权链：

Schema/Tool 校验
→ 规范化输入冻结
→ Operation Analyzer
→ 系统安全不变量
→ Grant / 权限模式 / 用户交互裁决
→ 获取执行并发槽
→ 路径、符号链接、环境和授权状态最终复检
→ Tool Gateway 执行
→ 结构化 Effect / Result / 审计事件

• 工具使用已冻结的规范输入执行，授权后修改原始参数不会改变实际执行内容。
• 高风险操作只能选择 ONCE，不生成可复用 Grant。
• 可证明安全的 Bash 命令只支持 RUN/SESSION 精确授权，不支持 WORKSPACE 宽授权。
• 受约束的文件读取和编辑可以选择 SESSION/WORKSPACE。
• 未知 MCP 和动态工具默认只能 ONCE；只有专用 Analyzer 才能产生可复用授权。
• network-v1 和 mcp-v1 的 SAFE/GUARDED 操作可选择 RUN/SESSION：保存的 Grant 仅匹配同一工具，输入值可变化；不支持 WORKSPACE，HIGH 风险仍只能 ONCE。
• Grant 不能覆盖保护路径、符号链接逃逸、敏感环境变量和执行前动态变化。
• 用户决策以 SQLite 中的 Interaction CAS 终态为唯一权威。

授权范围与多 Agent 继承

子 Agent 使用 root session、root run 和 actor ancestry 构成的授权主体匹配父会话 Grant。继承只复用相同工具语义和约束，不能扩大路径、命令、风险等级或资源范围。

权限模式

受保护路径

以下路径始终受系统安全不变量保护，权限模式和已保存 Grant 都不能绕过：

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

安全测试

• 权限、Bash、路径、符号链接、WebSocket、并发和数据库 CAS 均有专项测试覆盖

• 包含命令注入、路径穿越、权限绕过等攻击场景

• v9.3 深度防御新增：

  • CWE-22 路径穿越：CoordinatorService.getScratchpadDir sessionId 白名单（11 单测）+ SwarmController.createSwarm teamName 白名单（8 单测），即使上游 URI 拦截被绕过，白名单仍为最终落盘防线
  • 跨用户访问隔离（P2-A）：BrowserReplayController 双层闸门 —— sessionId 格式校验返回 400 + principal 归属校验返回 403，MVP 匿名会话兼容

  v9.3 安全防御汇总：

  防御层级	位置	防护机制	单测数
  P1-2	CoordinatorService.getScratchpadDir	sessionId 白名单 ^[A-Za-z0-9_-]{1,128}$	11
  E1	SwarmController.createSwarm	teamName 白名单 ^[A-Za-z0-9_-]{1,64}$	8
  P2-A	BrowserReplayController	sessionId 格式校验 (400) + principal 归属校验 (403)	—

• 每次代码变更都会执行完整安全测试套件

🧪 质量验证

完整功能测试报告见 ZhikunCode v9.3 全链路测试报告（2026-05-16）

持续集成：

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

当前主干验证结果（2026-07-18）：

• 后端单元/集成测试：2076 tests / 0 failure / 0 error / 48 skipped
• Python pytest：69 PASS
• 前端 vitest：87 PASS / 16 skipped（103 total）
• 静态与构建验证：前端 ESLint、TypeScript 与 Vite 生产构建通过
• 三端启动验证：Backend/SQLite UP、Python health ok、Frontend 首页正常返回

历史专项与 E2E 基线：

• 36 模块 REST/WS/LLM/Session 冒烟：45/45 PASS（42 REST + 1 WS STOMP + 1 LLM 真推理 + 1 Session 持久化）
• E2E 差异化链路：Task 6 多 Agent 协作（CoordinatorEventBus）· Task 7 可视化自动路由（/visualize mermaid/json/text）· Task 8 浏览器语义快照 MVP（/snap）全链路 PASS
• APOS Phase 1 E2E：62 用例（9 模块，含 28 原始功能 + 34 支撑链路）100% PASS，覆盖 Activity 基础 UI / 数据流转 / 三层展示 / Signal 标记 / Feature Flag / 后端 API / 响应式 / 持久化，含 4 Bug 修复回归
• APOS Phase 2 E2E：5 模块 50 用例（变更影响全景 / Pipeline 视图与 DAG / 异常检测与告警 / 移动端响应式 / Phase 2 集成功能）48 PASS / 2 SKIP，通过率 96%
• APOS 风险修复专项：11 用例 100% PASS（工具调用 / 批量操作 / 并发竞态 / API 降级）
• AI Coding 功能增强专项：6 大模块（SelfCorrectionLoop / 精确 Tokenizer / Skill 预算安全 / BashTool 动态超时 / GitDiffTracker / SearchStrategyRouter）33 用例 + 238 单元测试 + 7 集成测试 + Feature Flag 双向验证，100% PASS
• 功能完整性验证：100% 覆盖 v1.0 规划功能

测试框架详情：

性能基线（v9.3，490 次真实请求采样）：

详细测试数据与证据：

• v9.3 完整报告：docs/test-results/v9.3/
• 分模块测试结果：docs/test-results/
• 前端 E2E 脚本：frontend/e2e/
• E2E 截图证据：docs/test-results/screenshots/（42 项）

🎯 skill 技能系统

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

13 个内置技能

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

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 防抖机制监听文件变更。

安全与预算控制：

• Token 预算限制：单 Skill ≤5000 tokens / 会话总计 ≤25000 tokens，防止资源滥用
• 工具白名单：Skill 只能调用 frontmatter 中 allowed_tools 声明的工具
• 注入防护：Shell 注入三向量拦截（$() / 反引号 / 管道），参数长度限制 2000 字符
• Fork 深度控制：fork 模式 Skill 嵌套深度 ≤3 层，防止无限递归

🧩 插件系统

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 响应逐字输出，无需等待完成
• 持久权限交互 — 权限请求先写入 SQLite，再投递到浏览器；刷新或断线重连后可恢复未完成请求
• 服务端终态裁决 — 浏览器只提交服务端下发的选项，允许、拒绝、过期和取消通过数据库 CAS 互斥裁决
• 服务端倒计时 — 权限决策窗口为 300 秒，前端只展示服务端 deadline，不在本地自动伪造拒绝
• 子 Agent 授权复用 — 后代 Agent 在严格约束下复用根会话 SESSION/WORKSPACE Grant，避免重复弹窗
• 状态同步 — Agent 工作状态变化即时反映在 UI 上
• 心跳保活 — 双向 10s 心跳检测，断线自动重连（指数退避 1s→10s）
• 消息保障 — 128KB 消息大小限制，1MB 发送缓冲，30s 发送超时

🌉 Bridge 跨端桥接

ZhikunCode 通过 Bridge 模块提供跨端桥接（Cross-Platform Bridge）能力：

🤖 多 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 精确控制
• Worker 使用根会话授权主体进行权限裁决；符合约束的 SESSION/WORKSPACE Grant 可被后代复用
• 未命中 Grant 的操作通过 Durable Interaction 发送到根会话浏览器，支持 SQLite 持久化、ACK、重连恢复和服务端终态裁决
• 实时状态通过 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） 协议，支持 Client + Server 双向模式，通过 4 种传输方式（StdIO/SSE/WebSocket/HTTP）连接外部 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
}

MCP 协议能力增强

• MCP Roots 安全边界：声明工作区文件系统根，防止 MCP 服务器越界访问
• MCP 长操作进度追踪：实时显示 MCP 工具执行进度，支持用户取消
• MCP Schema 智能压缩：自动压缩大型工具参数描述，减少 LLM 上下文占用

MCP 协议传输层

ZhikunCode 支持 MCP 协议的 Client + Server 双向模式，覆盖 4 种传输方式：

🛠️ 内置工具集

ZhikunCode 提供覆盖开发全流程的内置工具，并支持 MCP 动态扩展：

📈 可视化

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

v9.3 新增：/visualize 命令通过 VisualizationAutoRouter 自动推送三种格式（mermaid / json / text），WS STOMP /app/command 端到端延迟 p50 < 3ms。

⚙️ 配置说明

环境变量

环境变量通过 .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 ⭐