zhikuncode

🌐 English

<div align="center"> <img src="docs/assets/logo.svg" alt="ZhikunCode" width="120" /> <h1>ZhikunCode</h1> <p><strong>开源 AI 编程助手 — 部署一次，浏览器全流程操控</strong></p> <p>多 Agent 协作 · Docker 自托管 · 国产大模型直连 · 深度安全架构</p> <p> <a href="#-快速开始">快速开始</a> · <a href="#-特性亮点">核心特性</a> · <a href="#-demo">在线演示</a> · <a href="#-公开工程案例">公开工程案例</a> · <a href="#-swe-bench-lite-评测">SWE-bench 评测</a> · <a href="#-cli-工具">CLI 工具</a> · <a href="#-skill技能系统">skill技能系统</a> · <a href="#-插件系统">插件系统</a> · <a href="#-可视化">可视化</a> · <a href="#-记忆系统">记忆系统</a> · <a href="#-竞品对比">竞品对比</a> · <a href="docs/README_EN.md">English</a> </p> <p> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a> <a href="https://github.com/zhikunqingtao/zhikuncode"><img src="https://img.shields.io/badge/Docker-Ready-blue?logo=docker" alt="Docker" /></a> <a href="https://github.com/zhikunqingtao/zhikuncode/stargazers"><img src="https://img.shields.io/github/stars/zhikunqingtao/zhikuncode?style=social" alt="GitHub Stars" /></a> <a href="https://github.com/zhikunqingtao/zhikuncode"><img src="https://img.shields.io/github/last-commit/zhikunqingtao/zhikuncode" alt="Last Commit" /></a> <a href="https://github.com/zhikunqingtao/zhikuncode"><img src="https://img.shields.io/github/languages/code-size/zhikunqingtao/zhikuncode" alt="Code Size" /></a> <a href="https://github.com/zhikunqingtao/zhikuncode/actions/workflows/ci.yml"><img src="https://github.com/zhikunqingtao/zhikuncode/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html"><img src="https://img.shields.io/badge/SWE--bench%20Lite-56.0%25%20(168%2F300)-7a2410?logo=python&logoColor=white" alt="SWE-bench Lite 56.0% (168/300)" /></a> </p> </div>

---

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

🏗️ 查看完整系统架构图 →
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英雄选将）→ · 自动演示（直接进入对局）→ · 了解评测方法 →

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

---

✨ 特性亮点

| | 特性 | 说明 | |---|---|---| | 🌐 | 浏览器全流程操控 | 部署一次，任何设备的浏览器即可完成全流程操作 —— 权限审批、方案协商、任务管控，手机上也能用，无需安装客户端 | | 📁 | Project 与 Run 控制 | 直连本机可选用原生目录选择器，远程部署只浏览配置的 allowed roots；Project 经真实路径规范化并持久授权，Session 拒绝客户端任意 workingDirectory。运行中输入按 Session 投递并返回 queued/applied/rejected，支持取消、包含 INTERRUPTED 的 CAS 单一终态与 WebSocket 恢复 | | 🤖 | 多 Agent 协作 | Team（固定分工）/ Swarm（动态协商）/ SubAgent（主从委派）三种协作模式，复杂任务自动分工 | | 🔒 | 统一授权安全架构 | 所有核心工具统一经过 Tool Gateway：规范化输入冻结 → Operation Analyzer 风险与资源分析 → 系统不变量检查 → RUN/SESSION/WORKSPACE Grant 匹配或持久权限交互 → 执行前动态复检 → 结构化结果审计。高风险操作只允许单次授权；专用 Network/MCP Analyzer 对 SAFE/GUARDED 操作支持按工具记住 RUN/SESSION 授权，未知 MCP/动态工具默认只能单次审批 | | 🇨🇳 | 国产大模型直连 | 千问 / DeepSeek / Moonshot / 智谱GLM / MiniMax 开箱即用，国内网络直连，无需科学上网 | | 🐳 | Docker 一键部署 | docker compose up -d 一条命令启动，数据存本地，完全私有 | | 📤 | 显式 OSS 产物发布（可选） | 通过 /publish-oss 从同一持久化根 Session 的根 Run 或授权后代 Run 中选择已验证条目，发布前再次校验哈希后生成永久公开下载地址；默认关闭、绝不自动上传，每次发布都需要用户明确指令和单次高风险授权 | | ⚡ | 智能上下文管理 | 六层压缩级联（Snip / MicroCompact / ContextCollapse / AutoCompact / CollapseDrain / ReactiveCompact）+ 增量折叠（每10轮自动压缩）+ 413 两阶段恢复（CollapseDrain 激进压缩 → ReactiveCompact 反应式压缩）+ 精确 Token 计数（tiktoken 多模型支持）+ 自纠错循环（SelfCorrectionLoop，编译/测试失败自动诊断修复，最多3次）+ Token三级告警 + 图片上下文治理（大图外置化 → 按需注入 → 预算守卫三层防护），无缝应对超长对话。核心引擎为 ContextCascade 与 QueryEngine | | 📷 | 多模态图片对话 | 支持图片上传输入，模型自动识别图片内容并分析；智能视觉模型路由——当前模型不支持图片时，自动切换至同厂商视觉模型处理，处理完成后无缝切回原模型，遵循"同厂商优先 + 全局兜底"策略。图片预算守卫——大图片（>50KB）自动外置化为轻量 JSON 引用，API 调用前按需注入，两阶段 Token 预算守卫确保多图对话不累积超限（单张≤1.5MB，总量≤2MB，最多 5 张并发注入）。支持的模型：gpt-5.6-sol / gpt-5.4-mini / claude-sonnet-4-6 / claude-opus-4-8 / qwen3.7-plus / kimi-k3 / kimi-k2.7-code / glm-5v-turbo / MiniMax-M3 / openai/gpt-5.6-sol / google/gemini-3.5-flash（单张≤5MB，数量上限因模型而异） | | 🖼️ | 浏览器语义快照 | /snap 命令智能捕获网页完整状态（DOM 结构 + 交互元素），支持富交互页面语义提取，生成结构化 JSON 供 Agent 解析和回放验证 | | 📊 | 实时活动追踪与审批 | Activity Panel 实时记录 AI 工具执行全流程，L1/L2/L3 三层展示体系，Signal 智能标记（auto_approve/review_recommended/needs_review），一键批量审批决策，SQLite 后端持久化，支持会话恢复 | | 🧪 | 运行时验证框架（Runtime Verification） | VerifierFactory 三模态分发（browser/http_api/auto）+ 8 种 HTTP action handler + JSONPath 断言 + 证据链 SQLite 存储 + Feature Flag 双重门控 + 前端实时进度面板 | | 🔍 | RV-4 证据包可视化 | 验证产物 7 类证据（screenshot / command / console / test / video / har / diff）Tab 分栏展示，移动端订阅 STOMP verify_attention 通知一键审批/驳回，REST API /api/evidence/* 提供查询与 Blob 下载 | | 🏆 | SWE-bench Lite 实测 | 单模型 qwen3.7-max + 6 工具闭集（Read/Edit/Write/Bash/Grep/Glob），无网络、无 sub-agent；官方 harness 评测 Resolve 56.0% (168/300)、Patch 生成率 94.7% (284/300)，技术报告 → | | 🚀 | 极致性能 | REST API p50 1.5ms · WS STOMP 握手 2.22ms · 490次真实请求采样验证，核心引擎零外部依赖纯 Java 实现 | | 🏭 | 运行时可靠性 | Run 状态 CAS 原子管理 · 完整 Session 快照、Run event sequence 与待处理持久交互重放 · 进程硬超时+梯度终止 · 作用域 Grant 与子 Agent 受控继承 · Artifact declare→seal→hash 验证及显式发布 · 结构化工具结果生成工具卡片与权威下载链接 · sid/rid/prid/agent/turn/tool/llm 日志关联 · BestEffortObservabilityRecorder 补充事件失败隔离 · Provider 本地预算守卫 |

---

🎬 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

三端服务会同时启动：

| 服务 | 地址 | 说明 | |------|------|------| | Backend | http://localhost:8080 | Java Spring Boot 后端，核心 API | | Python Service | http://localhost:8000 | FastAPI 服务，代码分析 | | Frontend | http://localhost:5173 | React 开发服务器 |

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

<details> <summary><b>手动分别启动各服务</b></summary>

# 后端（从仓库根目录启动，仅适用于直连本机开发）
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

</details>

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”。