开源 · 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 统一授权 + 最终复检 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行 通信链路 外部服务

ZhikunCode 系统工程架构大图

ZhikunCode 系统工程架构大图 115,879行源码 · 17+模型 · 26工具 · 13技能 · Java 21 Virtual Threads · Spring Boot 3 FRONTEND LAYER · TypeScript 28,394行 110 React组件 · 14+ Zustand Stores · STOMP WebSocket WebSocket STOMP 通信层 ↑ Client→Server: 10种上行消息 query | interrupt | permission | tool_result agent_message | memory_action | config_update skill_execute | collaboration_join | collab_action ↓ Server→Client: 25种下行推送 message_start/delta/stop | content_block_* tool_use/result | permission_request/response + 15种状态/协作/错误推送 Monaco Editor 代码编辑 · 语法高亮 · LSP集成 深色主题 · CSS变量驱动适配 权限交互弹窗 CompletableFuture 120秒超时 命令风险分级 · Always Allow V4门控 Zustand 状态管理 (14+ Stores) messageStore消息历史/流式 toolStore工具定义/执行状态 mcpCapabilityStoreMCP能力动态注册 commandStoreSlash命令 coordinatorStoreSwarm协调器 fileTreeStore文件树状态 activityStore用户活动追踪 持久化: LocalStorage 跨标签同步: BroadcastChannel TypeScript强类型 异步中间件支持 实时流式渲染 content_block_delta → 增量文本流 Markdown实时解析+代码高亮 Thinking块可折叠展示 可视化组件 代码路径追踪 · 架构图渲染 数据流可视化 · 多模型切换UI WebSocket双向流 BACKEND CORE · Java 79,639行 · 541文件 · Spring Boot 3 · Java 21 Virtual Threads 查询引擎（QueryEngine） QueryEngine.java · 1,583行 · 8步迭代循环 · MAX_TURNS=200 S1 压缩预检 ContextCascade.executePreApiCascade() L0-L2前置压缩 · 每次API调用前执行 S2 执行器初始化 StreamingToolExecutor.newSession() 并发上下文 · 条件等待 · 优先级调度 S3 LLM流式调用 provider.streamChat() + apiRetryService 模型降级 · Thinking配置 · 413恢复三阶段 S4 流式响应处理 StreamCollector.process() onContent · onToolUse · onMessage S8 状态持久化 state.incrementTurnCount() / setMessages() 轮次计数 · 错误状态 · 后台Agent追踪 S7 结果摘要注入 ToolResultSummarizer.summarize() BUDGET_RATIO=0.3 · FileHistoryService S6 终止判定 TerminationStrategy.evaluate() 轮次/错误/stopReason/token预算 S5 工具执行 ToolExecutionPipeline + AuthorizationService 输入冻结 · 授权裁决 · Gateway 执行 循环 stopReason≠end_turn && hasToolCalls → 继续循环 循环终止条件 ① turn >= config.maxTurns() (DEFAULT_MAX_TURNS=200) ② "end_turn".equals(stopReason) && !hasToolCalls ③ aborted.get() == true（外部abort()调用） ④ totalTokensUsed > tokenBudget ⑤ consecutiveErrors超阈值 入口: QueryEngine.execute(QueryConfig, QueryLoopState, QueryMessageHandler) 返回: QueryResult(messages, turnCount, tokenUsage, terminationReason) 模型降级解析: modelTierService.resolveModel() 413恢复: Phase1 CollapseDrain → Phase2 ReactiveCompact → Phase3 MediaRecovery 重试: apiRetryService.executeWithRetry() 指数退避 统一工具授权与执行准入 AuthorizationService · OperationAnalyzerRegistry · ToolExecutionGateway 2026-07-18 有限运行窗口验证 Phase 1 输入与语义分析 Schema / Tool 校验 校验工具输入契约 PreToolUse Hook 可改输入；修改后完整重验 FrozenToolInput canonical JSON + inputHash Subject + Analyzer root identity + 显式注册 OperationDescriptor effect/resource/risk + invariant → → → → Phase 2 决策顺序（命中即短路） Security Hook 基于冻结事实，只可收紧 SAFE_INTERNAL / 初次 Grant 初次匹配 ALLOW；执行前再复检 PermissionMode ALLOW / DENY / 需要交互 Durable Interaction v3 options + generation；ACK ≠ 决定 AuthorizedOperation 仅 ALLOW 分支生成 → → → → Phase 3 最终复检与执行准入 Declared Outputs planOutputs() 无副作用规划 动态环境复检 仅安全事实退化时拒绝 准入短事务 最终 Grant 复检 + admitted Tool Gateway 提交后 Tool.call(冻结输入) → → → 参考矩阵 · 4 种模式 / 4 种作用域: DEFAULT PLAN ACCEPT_EDITS DONT_ASK ONCE/RUN SESSION WORKSPACE HIGH/复杂 Shell/未知 MCP: ONCE | Guarded Bash: RUN/SESSION | 受约束文件能力: SESSION/WORKSPACE 用户批准和 Grant 均不能覆盖 system invariant；无害环境变化不得触发最终误拒绝 LLM 多模型路由 LlmProviderRegistry · ModelRegistry · 17+模型 Router OpenAI gpt-5.6-sol (1.05M ctx, 128K out, thinking) gpt-5.4-mini (128K ctx, 400K out) Anthropic claude-sonnet-4-6 (16K, thinking) claude-opus-4-8 (16K, thinking) claude-haiku-4-5 (8K) 国产模型 deepseek-v4-pro (384K, thinking) deepseek-v4-flash (384K, thinking) qwen3.7-max (65.5K, thinking) qwen3.7-plus (8K) | kimi-k3 (16K) glm-5.2 (131K) | glm-5v-turbo (131K) ZenMux 聚合 (4端点) anthropic/claude-opus-4.8 (64K) anthropic/claude-fable-5 (64K) openai/gpt-5.6-sol (128K) google/gemini-3.5-flash (65.5K) 本地模型 ollama/* (4K ctx, 8K output) 降级链 30min冷却 → 3次成功恢复 | 三级回退: 用户指定模型 → Agent默认(light/standard/premium) → 全局默认(qwen3.7-max) 工具执行系统 内置工具 + MCP动态工具 · 核心生产调用统一经过 ToolExecutionGateway 文件(5) FileRead FileEdit FileWrite AtomicWriter VersionTracker Bash(3) BashTool 31.7KB TerminalCapture MonitorTool 代码分析(4) GrepTool 12.3K GlobTool 5.5K LspTool CodeIntelTool Git(2) GitTool 7.7K WorktreeTool Web(3) WebBrowser 15.7K WebFetch 15.8K WebSearch 其他(9) Snip Visualization VerifyPlan EnterPlan ExitPlan CronCreate CronDelete CronList CtxInspect Tool接口: getName() | call(ToolInput,ToolUseContext) | getPermissionRequirement() | isReadOnly() | shouldDefer() | alwaysLoad() MCP 双向协议 35文件 · McpClientManager 27.3KB → MCP Client (工具扩展) McpServerConnection → 外部MCP服务器 McpToolAdapter (13.5KB) 工具转译 McpPromptAdapter (7.9KB) Prompt适配 ← MCP Server (对外暴露) IDE/外部客户端 → ZhikunCode能力 CapabilityRegistryService 能力注册 传输层: StdIO | SSE | WebSocket | HTTP流 3 Built-in SSE: WebSearch | WebFetch | Browser Discovery: GET /api/health/capabilities Cache: 5min/30s · graceful fallback 上下文级联压缩（ContextCascade）6层 348行 · 漏斗式精炼 L0 Snip 单条截断 · 保留首尾 · 每次无条件执行 · 30%预算 L1 MicroCompact 旧结果→[cleared] · 尾部10条保护 L1.5 ContextCollapse 激进压缩旧轮次 L2 AutoCompact LLM摘要 · 13K buffer触发 L3 CollapseDrain 413溢出回收 L4 ReactiveCompact max×0.5兜底 阈值 = (contextWindow - contextWindow/4) - 13000 | 连续失败3次 → 断路器熔断 自纠错循环（SelfCorrectionLoop） 396行 · 仓库感知 错误检测 编译优先 → 测试次之 分析错误 ParsedError提取 生成修复指令 ≤800 tokens 验证失败 → 重试 退出条件: ✓ 编译/测试通过 ✗ MAX_ATTEMPTS: 3(默认) / 7(SWE-bench) ✗ 错误恶化: 新错误数↑ / 新文件↑ / 新类型↑ compileErrorParser.parse() testFailureParser.parse() MAX_STACK_TRACE_LINES = 3 shouldAbort(): newErrorCount > prev || newFiles.notEmpty || newTypes.notEmpty 钩子系统（Hook System）三级 HookService.java PreToolUse 输入转换/拒绝；改写后 Schema 与 Tool 完整重验 PostToolUse 工具执行后处理 · 日志记录 · 结果转换 OnMessage 消息生成时过滤 · 增强 · 国际化处理 registerHook(type, cb) · WatchService热重载 记忆目录（Memdir） MemdirService.java · 598行 System Memory User Memory Project Memory Workflow Memory 双路检索: BM25向量化 + 中文分词 + LLM语义增强 会话中动态添加 · 长期持久化 技能系统（Skill System） SkillRegistry.java · 415行 · 13内置技能 · 6层优先级 加载优先级 (高→低): 1.Managed(策略) → 2.User(~/.zhikun/skills/) → 3.Project(.zhikun/skills/) → 4.Plugin → 5.Bundled → 6.MCP 内置技能 (BUILTIN_SKILL_NAMES): commit review fix test pr debug verify stuck remember software-architecture csv-data-summarizer prompt-eng test-driven-dev WatchService热重载 · 500ms防抖 · SkillDefinition(name, desc, ...) 多Agent协作（Multi-Agent） AgentConcurrencyController Leader Agent Coordinator主控 Sub-Agent(s) root identity 匹配父会话 Grant 三级Semaphore并发门控: GLOBAL = 30 (全局最大并发Agent) · L28 PER_SESSION = 10 (单会话上限) · L31 NESTING_DEPTH = 3 (防无限循环) · L34 TIMEOUT=5min · RAII AgentSlot自动释放 模型降级与413恢复 ModelTierService · 二阶段+媒体恢复 413恢复策略: Phase1 CollapseDrain→0.5 → Phase2 ReactiveCompact半 → Phase3 MediaRecovery媒体 降级链: 模型失败 → 30min冷却(标记cold) → 冷却期满自动恢复 3次连续成功 → 确认恢复 → 重置计时器 WebSocket控制器 WebSocketController.java · 1,590行 权限交互持久流: optionId + descriptorHash + scopeOptions + expectedVersion deliveryGeneration ACK 仅确认当前投递，不代表允许 用户决定由 interaction_requests 数据库 CAS 产生唯一终态 提交后唤醒等待者；旧代次 ACK 不能确认新投递 STOMP端点: offline grace → bind-session → session snapshot → 权限模式恢复 运行时验证（APOS）引擎 verify/ 18文件 + apos/ 21文件 = 3,516行 Verifier 接口层 BrowserVerifier (UI行为验证) HttpApiVerifier (API契约验证) CustomVerifier (自定义验证器工厂) EvidenceStore (SHA-256 blob内容寻址去重) 4种证据类别 × 3种判决 × 7种证据类型 三态: verified / failed / unavailable 实时推送: STOMP /topic/verify/{sessionId} 前端: 21个React APOS组件 Verifier.verify(context) → Evidence → EvidenceStore.persist() → STOMP push → React渲染 安全控制与审计支撑 授权主链与横切安全组件分离 Bash Analyzer: CommandBlacklist + Parser/Path 生成命令风险、effect、resource 与可授权约束；绝对黑名单直接拒绝 File Analyzer: PathSecurityService 规范化资源边界；Gateway 执行前重新检查路径、符号链接与授权约束 SensitiveDataFilter: 输出侧纵深防护 PostToolUse 后过滤工具结果，并为 Analyzer 生成脱敏摘要；不负责授权 SecurityAuditLogger: 横切审计记录 [SECURITY-BLOCK] / [SECURITY-PATH] / [SECURITY-AUDIT]；不参与放行 权限主链: FrozenInput → Analyzer facts → AuthorizationService → Gateway final recheck → Tool.call() 跨端桥接（Bridge） bridge/ 9文件 · 1,950行 BridgeServer (394行) — 跨端通信桥 · 设备发现 BridgeApiClient (367行) — 长轮询 · 消息队列 TrustedDeviceManager (197行) — 设备指纹认证 BridgeJwtManager (268行) TokenCostPanel (107行) System Prompt 动态构造引擎 4层合成 基础指令层 角色定义 + 工具描述 (26工具Schema注入) 上下文注入层 项目信息 + Memdir记忆检索 + 文件树 技能加载层 按6层优先级合并 · SkillRegistry动态解析 约束规则层 安全边界 + 输出格式 + PermissionMode约束 PromptBuilder.build() → 基础+上下文+技能+约束 → streamChat(systemPrompt, messages) 运行时韧性控制面板 熔断·退避·降级 三级防护 ApiCircuitBreaker 三态 CLOSED → OPEN → HALF_OPEN · 连续失败阈值→熔断→定时探测→恢复 ApiRetryService (指数退避 + Jitter) executeWithRetry() · baseDelay×2^attempt + random jitter · maxRetries=3 ModelTierService (冷却30min + 3次成功恢复) 模型标记cold → 冷却期满 → 探测请求 → 3次连续成功 → 恢复可用 韧性链: 重试退避→熔断隔离→模型降级 · 防止级联故障 · 自动恢复 可观测性体系 Structured Logging · 链路追踪 · Token监控 Structured Logging (JSON分层输出 · MDC关联) 链路追踪 (SessionId + TurnCount + toolUseId关联) Token消耗监控 (TokenCostPanel · 实时统计 · 模型维度) 技术栈基座 Java 21 · Virtual Threads Spring Boot 3.x Spring WebSocket STOMP Jackson JSON SQLite 数据迁移 Docker容器化 Records · Sealed Types Pattern Matching 编译特性: Records(sealed interface) · Virtual Threads(高并发) · Pattern Matching(简化逻辑) | 数据层: SQLite + FileSystem | 部署: Docker多阶段构建 工具执行管线（ToolExecutionPipeline）9-Stage ToolExecutionPipeline.java L128-304 · 每次生产工具调用必过授权与 Gateway 主路径 Stage 1 SCHEMA_PARSE validateSchema() — JSON Schema 结构校验入口 L128 Stage 1.5 JSON_VALIDATE jsonSchemaValidator — 输入参数格式校验 L128 Stage 2 TOOL_VALIDATE_INPUT tool.validateInput() — 工具自定义校验 L133 Stage 2.5 INPUT_BACKFILL backfillObservable() — 可观测参数自动填充 L143 Stage 3 PRE_HOOK hookService.pre() — 工具执行前置钩子 L153 Stage 4 ◆ PERMISSION_CHECK 冻结输入 → Analyzer → Security Hook → AuthorizationService L187-205 Stage 5 ★ EXECUTE ToolExecutionGateway 复检/准入 → Tool.call()（唯一生产入口） L224-252 Stage 6 POST_HOOK hookService.post() L259 Stage 7 CONTEXT_MODIFIER 返回Result L304 图例: ◆ DENY短路点 (任何一步DENY即返回) ★ 唯一副作用执行点 纯计算/校验阶段 流水线特性: • 单工具串行执行，多工具可并发 • 校验、Hook、Analyzer、模式/交互与最终复检均可拒绝 • Stage 5 委托 Gateway 后才产生外部可观测效果 • PostHook/Modifier 仅处理成功取得的 ToolResult；异常走结构化 catch 分支 L128(Schema)→L133(Validate)→L143(Backfill)→L153(PreHook)→L187(Freeze/Auth)→L224(Gateway)→L259(PostHook)→L304(Modifier) 工具执行管线 APOS→QueryEngine 验证执行结果 Security→AuthorizationService→Gateway 安全纵深 Bridge ↔ 跨端桥接 增量折叠管理器（IncrementalCollapseManager） ├── 触发条件: 每10轮自动压缩 ├── 配置: segment-turns=10 ├── 会话超时: 30min └── 与6层压缩级联联动 executePreApiCascade() → 每次API调用前触发级联压缩 8层Bash安全沙箱（BashSecuritySandbox） BashTool.java 31.7KB · 纵深防御架构 L1 命令解析 管道(|) / 重定向(>) / 子命令($()) / 命令链(&&) 完整识别 L2 黑名单过滤 三级拦截: ABSOLUTE_DENY(绝对禁止) → HIGH_RISK_ASK(高危询问) → AUDIT_LOG(审计) L3 路径遍历检测 ../穿越阻断 + /dev/设备路径 + UNC路径过滤 L4 权限验证 → AuthorizationService 统一裁决 · Gateway 执行前复检 L5 可选 Docker沙箱 授权通过后选择执行路径；默认关闭，不是权限放行来源 L6 参数净化 环境变量白名单(PATH/HOME/LANG) · Shell元字符转义 · 注入防护 L7 输出校验 SensitiveDataFilter 16种脱敏模式 L8 审计日志 SecurityAuditLogger · 完整记录 · 可追溯 安全链: 解析/Analyzer→授权→Gateway复检→可选沙箱执行→脱敏/审计 · 沙箱不能扩大 Grant 或模式边界 多Agent三模式对比 AgentOrchestrationService · 三种协作模式 Team模式 TeamMailbox异步通信 + SharedTaskList + InProcessBackend(Virtual Thread) Leader分派 → Worker异步执行 → Mailbox汇报 → Leader合成结果 Swarm模式 四阶段(Research→Synthesis→Implementation→Verification) + 30min超时 SwarmCoordinator → 阶段流转 → Worker动态调整 → 超时熔断 SubAgent模式 三隔离级别(NONE/WORKTREE/FORK) + BackgroundAgentTracker + 5min超时 父Agent → spawn → 子Agent独立执行 → root session/root run 受控继承 Grant 验证器工厂（VerifierFactory）三模态分发 ├── browser: Playwright端到端测试 (截图+DOM断言+网络拦截) ├── http_api: 8种HTTP action + JSONPath断言 └── auto: 智能切换模式 (根据验证目标自动选择) 证据链: SQLite存储 + 7类证据(screenshot/command/console/test/video/har/diff) Feature Flag: RUNTIME_VERIFICATION + BROWSER_AUTOMATION BM25搜索引擎（纯Java实现） ├── 中英文混合检索 ├── 分词: Unigram + Bigram中文分词 ├── 参数: k1=1.2, b=0.75 ├── 标题2x加权 └── 可选LLM精排（Top-K后重排序） 工具并发模型（isConcurrencySafe） 并行安全 ✓ (VirtualThread并发): Read / Glob / Grep / TokenCount 多工具同时执行 · 共享线程池 · 无状态操作 独占执行 ✗ (顺序队列): BashTool / FileWrite / FileEdit 单工具串行 · 避免写冲突 · 有状态操作保护 完整13技能清单 Slash Command · 技能描述 /commit 智能提交 /review 代码审查 /fix 智能修复 /test 智能测试 /pr PR助手 /debug 调试诊断 /verify 代码验证 /stuck 脱困诊断 /remember 会话记忆 /software-architecture /csv-data-summarizer /prompt-engineering /test-driven-development 6层优先级加载 · WatchService热重载 · Markdown模板 · 参数化指令 HTTP REST · Playwright PYTHON SERVICE · FastAPI 7,846行 · main.py 148L 4-Layer Capability Detection capabilities.py 205L L1: importlib 包导入探针 L2: packaging.Version 版本兼容性检测 L3: shutil.which 二进制探测 L4: async smoke_test 异步烟测验证 测试与质量: pytest框架 · 11+测试文件 · .coverage报告 FastAPI /docs 自动文档 requirements.lock 锁定版本 pyproject.toml 依赖管理 8 Router Modules src/routers/ · 2,162 LOC code_intel file_processing code_quality analysis git_enhanced browser http_api journey 7 Analyzer Services src/services/ · 1,971 LOC tree_sitter 238L call_graph 583L complexity 156L code_path ~400L change_impact ~450L sequence_diagram flow_chart_generator 浏览器自动化: Playwright引擎 · 页面截图/DOM/网络拦截 CLI接口: python-service/cli/ · 数据可视化: SVG/PNG导出 服务架构 FastAPI + Uvicorn 启动流程: main.py:148L → 4层能力探测 → 动态注册Router 能力缺失 → 跳过对应Router (graceful degradation) 接口契约: Java后端 → HTTP REST → Python FastAPI WebBrowserTool → /browser/* 端点 CodeIntelTool → /code-intel/* 端点 VisualizationTool → /visualization/* 端点 存储: workspace/screenshots/ 截图存储 Temp files 临时分析产物 · 自动GC Java 79,639行 │ TypeScript 28,394行 │ Python 7,846行 │ 总计 115,879行 541 Java文件 │ 110 React组件 │ 26工具 │ 13技能 │ 17+模型 │ 14 Stores │ 35 MCP文件 ZhikunCode System Architecture Blueprint · 源码实证驱动 · 所有数据100%来自代码审查

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

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 Analyzer · Grant · Gateway 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阶段编排引擎 AuthorizationSubjectResolver root session/root run — 授权主体解析 ResultAggregator 结果聚合 → Coordinator SubAgentExecutor 受约束 Grant 继承 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 消费工具结果 并行执行·异步等待 并发调度→逐调用授权/Gateway→按序收集 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 行

统一授权与执行准入全景流程

AuthorizationService · OperationAnalyzerRegistry · ToolExecutionGateway 校验/Hook → 冻结输入 → root subject + Analyzer → 只收紧安全 Hook → 授权 → Gateway 复检与执行 STAGE 1: 输入冻结与授权事实 OperationDescriptor 由 Analyzer 基于冻结输入生成 VALIDATION / POLICY DENY WAITING INTERACTION Schema 校验 参数补全与重验 Tool.validateInput() PreToolUse Hook 可改输入 / 可拒绝 改写后完整重验 FrozenToolInput canonical JSON + inputHash 执行输入由冻结字节重建 Subject + Analyzer root identity / analyzerFor() 核心工具漏配即失败 OperationDescriptor operationHash effect/resource/risk + invariant Security Hook 只可收紧 / 可拒绝 基于冻结事实执行 SAFE_INTERNAL 命中即 POLICY ALLOW 未命中才继续 Grant Grant 匹配 命中即 GRANT ALLOW root/scope/profile/constraint Mode / Interaction ALLOW / DENY / v3 options V015 CAS / 可建 Grant AuthorizedOperation ALLOW source policy/grant/user Declared Outputs planOutputs() 无副作用预声明 动态环境复检 analyzer.recheck() 路径/链接/环境 准入短事务 Grant/ONCE + 预声明 写 tool_started 后提交 Tool Gateway 唯一生产入口 事务外 Tool.call(冻结输入) → DENY → ASK 授权通过 → 执行准入 Analyzer 约束、invariant 与最终动态复检始终生效，Grant 不能扩大边界 以下为授权策略参考矩阵，不表示后续运行时阶段 REFERENCE A: Grant 与作用域 受约束复用，不保存 HIGH/复杂 Shell RUN / SESSION Guarded exact Bash / exact file SESSION / WORKSPACE 受约束文件 read/edit capability 匹配 → ALLOW 未匹配 → 模式或交互裁决 REFERENCE B: 模式、Scope 与继承 4 种用户模式 · ALLOW / DENY / INTERACTION 无 Grant → 按模式裁决 SAFE file read 可按模式放行 DEFAULT 用户确认 PLAN 只读放行 ACCEPT_EDITS 编辑放行 DONT_ASK 仅 SAFE file read ONCE 不持久化 ROOT_AND_DESC 子代理受控继承 DIRECT_ONLY RUN 不跨 actor 子代理通过 root session/root run 身份直接匹配 Grant 不经过第二套冒泡授权权威 最终结果: AuthorizedOperation / DENY / WAITING_INTERACTION

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 →
Public engineering audit · Case 01

同一黄金监控任务的双工具执行审计

以真实任务、与登记哈希完全一致的原始运行日志核验及脱敏关键摘录、冻结产物哈希、代码检查和由冻结报告解码的公开脱敏截图，对照 ZhikunCode 与 Codex 的需求澄清、Agent 调度、权限控制和工程交付。完整原始日志与冻结 ZIP 未公开；报告公开负面发现与证据边界，不把单次案例外推为产品或模型排名。

38 条证据 14 个评分维度 离线可读 / 可复算
Public engineering audit · Case 02

12306 候补可视化双工具对比评估

同一 12306 候补可视化任务下的双工具对比评估（ZhikunCode/KimiK3 vs Codex/GPT-5.6 Sol），覆盖需求理解、工程实现与交付质量等 7 个维度，附 11 张实测截图与 38 分钟全程日志取证，评分与证据边界均在报告内公开。

7 维评估 11 张实测截图 38 分钟全程日志取证

核心特性

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

🌐

浏览器全流程操控

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

🐳

Docker 一键部署

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

🇨🇳

国产大模型直连

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

🔒

8 层安全架构

Bash 语义分析 + 统一授权服务 + Tool Gateway 执行前复检，形成 fail-closed 分层控制；当前结论来自源码、测试与有限本地运行验证，不等同于独立安全认证。

🤖

多 Agent 协作

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

🧩

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

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

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

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

8
层 Bash 沙箱
命令白名单、路径约束、超时熔断、资源配额……层层拦截恶意操作
11
个授权职责边界
输入重验、冻结输入、Analyzer/invariant、Security Hook、Grant/模式/交互、输出声明、最终复检与 Gateway 准入
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 开始使用