🌐 English

ZhikunCode

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

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

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

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

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

🧭 查看完整能力总览 → 交互入口 · Agent / Run · 权限安全 · 工具与 Skill · 验证产物 · 观测恢复

代码快照： ea0170c · 2026-08-09 · Git 跟踪的产品源代码 134,826 行 / 863 文件（Java 93,118 / 622、React 33,642 / 209、Python 服务与 CLI 8,066 / 32；不统计本地忽略文件）

🔎 实时黄金监控：ZhikunCode vs Codex 同题 PK → ZhikunCode × Codex · 同一需求两套实现，14 维评分、过程截图与完整执行记录

🚄 12306 候补全链路可视化：单文件零依赖交付 → ZhikunCode/KimiK3 × Codex/GPT-5.6 Sol · 7 维对比评估，双方产物可直接在线试玩

🎮 5 小时 AI 从零写出可玩的《王者荣耀》网页版 → Kimi K3 · 一次连续开发 5 小时 29 分 · 19 个文件 / 7,979 行纯静态 Three.js · 打开浏览器即可试玩

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

实时黄金监控：ZhikunCode vs Codex 同题 PK

同一个实时黄金监控需求，分别交给 ZhikunCode 与 Codex 从零完成，再按需求理解、开发交互、数据准确性、架构、代码质量、用户体验等 14 个维度打分。报告同时保留双方的优点与缺陷。

• ZhikunCode：Kimi K3 遇到 HTTP 429 后，由用户切换至 GLM-5.2 并在同一逻辑会话中继续。
• Codex：GPT-5.6 Sol，推理强度 High。
• 最终评分 ZhikunCode 68.3、Codex 68.4 —— 两者几乎打成平手。

查看对比报告 → · 下载原始数据 → · 了解评测方法 →

12306 候补全链路可视化：单文件零依赖交付

同一个"12306 候补成功后台全链路"动态可视化需求，分别交给 ZhikunCode 与 Codex 完成，从任务理解、代码质量、动态可视化、架构与数学、用户体验、开发效率、技术实现 7 个维度评估。报告同时保留双方的优点与缺陷。

• ZhikunCode：kimi-k3 交付单文件 HTML，1,061 行、零外部网络依赖，打开就能跑。
• Codex：GPT-5.6 Sol（高推理模式）交付 Next.js 工程，会话截图显示总耗时 27m52s。
• 最终加权评分 ZhikunCode 8.68、Codex 8.45 —— 差距很小，产物风格截然不同。

查看对比报告 → · 产物在线 Demo → · 下载原始数据 → · 了解评测方法 →

5 小时，AI 从零写出可玩的《王者荣耀》网页版

ZhikunCode 使用 Kimi K3 在 2026-08-09 凌晨一次性完成了一个纯静态 Three.js 5v5 MOBA 游戏：选将、对局、AI 队友与敌人全部可玩，打开浏览器就能进。

• 一次连续开发 5 小时 29 分，产出 19 个第一方文件、7,979 行代码。
• 10 个子 Agent 协作分工，覆盖玩法、渲染、AI 行为与关卡资源。
• 纯静态交付，无后端、无外部网络依赖，浏览器直接运行。
• 全过程留痕：43 张截图与 5 段原始录屏，可跟着报告一路下钻。

查看详细案例 → · 在线试玩（5 英雄选将）→ · 自动演示（直接进入对局）→ · 了解评测方法 →

以上案例均为单次任务实测记录，详细方法与数据见各案例报告页。

✨ 特性亮点

🎬 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

# 停止旧进程后启动三端服务
./stop.sh
./start.sh

三端服务会同时启动：

./start.sh 默认把仓库根目录设为 workspace；仅当 allowed roots 和本地 picker 开关都没有非空配置时，才自动启用直连本机目录浏览。

本地工作台使用说明

• 首次使用默认进入简洁工作台；可通过页面顶部随时切换到开发工作台。
• 简洁工作台面向结果，展示当前 Root Run 对应的要求、最终回复、主要成果、待处理事项、近期活动和验收状态，不把旧执行结果混入本轮交付。
• 开发工作台保留完整对话、工具调用、文件、Diff、Git、终端、浏览器、Agent 和证据视图。
• 视图选择保存在当前浏览器中，并支持按 Session 记住选择；切换视图不会中断任务或改变运行状态。
• PDF、图片、文本和 Markdown 等支持在工作台内安全预览；其他文件可切换到开发工作台文件区处理。
• “在文件夹中显示”仅适用于从本机浏览器直连本地 ZhikunCode 的场景。

# 后端（从仓库根目录启动，仅适用于直连本机开发）
export ZHIKUN_DEFAULT_WORKSPACE="$PWD"
export ZHIKUN_LOCAL_PICKER_ENABLED=true
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 127.0.0.1 --port 8000

# 前端（另开终端，从仓库根目录启动）
cd frontend && npm install && npm run dev

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

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

可选：将已验证产物发布到 OSS

ZhikunCode 提供内置 /publish-oss Skill，可从同一持久化根 Session 内的根 Run 与通过 parent_run_id 建立的后代 Run 中选择一个已验证产物条目，发布为 OSS 永久公开下载地址。本功能默认关闭且绝不自动上传：生成文件、完成 Run、预览或打开文件都不会触发上传；每次发布都必须由用户明确提出，并通过一次高风险权限确认。

该功能仅支持通过 ECS 实例 RAM 角色和 IMDSv2 获取自动轮换的 STS 临时凭证，不接受长期 OSS AccessKey。每个部署者都必须配置自己的 Bucket、Region、Endpoint 和 RAM 角色；克隆或启动本仓库不会连接项目维护者的 OSS。

在 ECS 的 .env 中配置以下非敏感参数：

ZHIKUN_OSS_ENABLED=true
ZHIKUN_OSS_ENDPOINT=oss-cn-your-region.aliyuncs.com
ZHIKUN_OSS_REGION=cn-your-region
ZHIKUN_OSS_BUCKET=your-bucket
ZHIKUN_OSS_PREFIX=zhikuncode-artifacts
ZHIKUN_OSS_ECS_ROLE_NAME=your-ecs-ram-role
ZHIKUN_OSS_MAX_FILE_BYTES=104857600
ZHIKUN_OSS_CONNECT_TIMEOUT_MS=10000
ZHIKUN_OSS_REQUEST_TIMEOUT_MS=120000

RAM 角色只应授予目标前缀所需的最小 OSS 权限。不要设置或提交 OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_SESSION_TOKEN 及对应的 ALIBABA_CLOUD_* 长期凭证变量；发布前的配置校验会拒绝这些变量。

使用流程：

1. 在当前持久化根 Session 中生成产物；Manifest 完成 declare → seal/hash → verify 后，状态可以是 verified，也可以是包含目标已验证条目的 partial。
2. 明确输入 /publish-oss <文件路径>，或说明“上传刚生成的产物到 OSS”。
3. 核对确认卡片中的文件名、大小、公开范围和“永久公开”警告后，批准本次操作。
4. 上传成功后使用返回的 OSS 地址下载产物。

安全边界与当前限制：

• 只允许同一持久化根 Session 内根 Run 或授权后代 Run 所声明、目标条目已验证且仍匹配 Manifest 哈希的 workspace 内单个普通文件，默认不超过 100 MiB。
• 拒绝目录、批量上传、符号链接、workspace 外路径、.env、私钥、数据库、凭证配置及检测到敏感内容的文件。
• 对象先私有上传，远端校验成功后才切换为 public-read；失败时清理本次新建的私有对象。
• 返回地址为永久公开下载地址。OSS 默认域名通常会下载 HTML，而不是在浏览器中直接渲染。
• 当前精简版不提供批量发布、发布历史或撤销入口；删除公开对象需要运维人员在 OSS 侧显式执行。
• 本地开发环境没有 ECS 实例元数据凭证，只能测试交互和配置校验；真实上传必须在已绑定 RAM 角色的 ECS 上验收。

支持的 LLM 服务商

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

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

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

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

# DashScope Token Plan（百炼订阅专属 sk-sp- Key，与按量计费 Key 分离）
LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_API_KEY=your-token-plan-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 终态为唯一权威。

文件夹选择与持久授权

Web 新会话必须先选择一个已授权目录。远程和 Docker 部署的目录浏览只展示服务端配置允许的根目录及其子目录；启用本地 picker 的直连本机部署中，内置目录浏览器从默认 workspace 起始，可浏览本机服务进程可读的目录。macOS 和 Windows 还会在系统能力可用时显示原生文件夹选择按钮，系统对话框通常从桌面目录开始；Linux 继续使用内置目录浏览器。Docker 中宿主机的 WORKSPACE_PATH 对应容器内的 /app/workspace。浏览器不能把客户端本地路径直接当作远程服务端路径。

• Project 是一个全局、持久、可撤销的信任范围和默认相对路径根，并不是通用的操作系统文件沙箱；专用文件工具以 Session 的规范化工作目录解析相对路径，范围外路径另行授权并复检。
• DEFAULT 模式下，Project 内的普通文件操作免于重复确认；Project 外的普通请求进入常规授权流程，并可在策略允许时记住授权；敏感文件和高风险操作仍需逐次批准。
• 撤销 Project 会停止后续普通写入的持久自动授权。已有 Session 仍以原目录作为默认相对路径根；安全读取仍按 Session 策略执行，其他受控操作重新进入正常授权流程。
• Session、Query 和文件搜索使用 projectId 或 sessionId；客户端提交任意 workingDirectory 会被拒绝。
• 普通目录和 Git 子目录都可授权；只有所选目录本身就是 Git worktree 根目录时，才提供内置仓库上下文和 Git slash 命令。Bash 不是目录沙箱，但始终走独立的命令授权，不会因 Project 选择而自动获准。
• 后端的 ZHIKUN_LOCAL_PICKER_ENABLED 安全默认值为 false。使用 ./start.sh 本地快速启动时，如果 ZHIKUN_WORKSPACE_ALLOWED_ROOTS 和该变量均无非空配置，脚本会为直连本机桌面场景启用 picker；显式设置 false 或配置 allowed roots 时不会被覆盖或隐式启用。远程、反向代理和生产部署应显式保持关闭并配置 allowed roots。

授权范围与多 Agent 继承

ONCE 是不写入 Grant 仓库的一次性授权决策；RUN、SESSION、WORKSPACE 才是三种持久 Grant 范围。

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

权限模式

AUTO_APPROVE 会取消工具权限确认，远程部署使用时应确认运行账户、文件系统和网络边界符合预期。它不会赋予操作系统之外的新权限，也不会绕过系统安全与部署限制。

受保护路径

以下路径始终受系统安全不变量保护，权限模式和已保存 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 自动化流水线：主 CI 执行后端编译和前端构建；Python 测试当前为非阻塞检查，Docker 镜像验证仅在 main push 时执行。

当前代码本地验证快照（2026-08-13）：

• 后端单元/集成测试：2317 tests / 0 failure / 0 error / 48 skipped
• Python pytest：107 PASS
• 前端 vitest：182 PASS / 16 skipped（198 total）
• 简洁工作台 Playwright E2E：3 / 3 PASS
• 静态与构建验证：TypeScript 与 Vite 生产构建通过

历史专项与 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 正文定义执行指令。

14 个内置技能

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

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

项目记忆仅从所选 Project 根目录加载 zhikun.md 和 zhikun.local.md，不向父目录搜索；单文件上限 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 "帮我重构这个函数"

# 显式授权当前目录（仅 localhost 后端）
aica --working-dir "$PWD" "帮我重构这个函数"

# 远程后端使用已有 Project
aica --server https://example.com --project-id PROJECT_ID "检查项目"

# 管道输入 — 像 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"

未提供 --working-dir、--project-id，且没有通过 --session-id、--continue 或 --resume 选择 Session 时，CLI 使用后端默认 workspace。--working-dir 只适用于 localhost，远程后端应使用 --project-id；两者不能同时使用。

核心特性：

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、standard、premium 默认均为 qwen3.7-max，可通过配置统一调整，避免在 Agent 定义中硬编码模型名称。

🧩 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 提供 40+ 内置工具，并支持 MCP、插件与平台条件工具动态扩展；最终可用集合以当前部署、Feature Flag 和已连接的 MCP Server 为准：

📈 可视化

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 ⭐