ZhikunCode 系统架构

Enterprise-Grade AI-Powered Web IDE — Architecture Reference
Java 71% TypeScript 21% Python 8% 110,646 Lines 660 Files
01

项目总览面板

ZhikunCode · Web IDE · 浏览器 + 后端服务 + 分析服务
Java 后端主源码
65,654 行 / 433 文件
Java 测试代码
18,236 行 / 58 文件
React 前端
19,543 行 / 137 文件
Python 服务
7,213 行 / 32 文件
技术概览
项目名称ZhikunCode
产品形态AI-Powered Web IDE
总代码量110,646 行 / 660 文件
后端框架Spring Boot 3.4 + Java 21
前端框架React 18.3 + Vite 5.4 + Zustand 4.5
分析服务FastAPI + uvicorn + tree-sitter
UI 工具链Tailwind 3.4 + Monaco 0.52 + xterm.js 5.5
可视化Mermaid 11.14 + 14个自定义图表组件
代码量分布
Java 主源码
65,654 Java 测试
18,236 React 前端
19,543 Python 服务
7,213
02

三端分离架构总览

核心通信链路
React 前端 19,543 行 · 137 文件 · 32 Zustand Store · 86 组件 · 14 可视化 dispatch.ts 437行 | stompClient.ts 358行 Java 后端 65,654 行 · 433 文件 · Spring Boot 3.4 Port 8080 · Agent Loop · Permission · MCP · Tools Python 分析服务 7,213 行 · 32 文件 · FastAPI Port 8000 · 6 能力域 · tree-sitter LLM API MCP Servers Docker 沙箱 文件系统 REST API + WebSocket/STOMP Vite Proxy → :8000
▸ 三端分离架构全景插画
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 18步 752行 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行 通信链路 外部服务
▶ 5条通信链路详情
#链路协议关键文件
1前端 → Java 后端REST API + WebSocket/STOMPdispatch.ts (437行) + stompClient.ts (358行)
2前端 → Python 服务Vite Proxy 转发/api/git, /api/files, /api/code-quality, /api/analysis → :8000
3Java → LLMHTTP/SSE StreamLlmProviderRegistry → Anthropic / OpenAiCompatible
4Java → MCP Server5种传输McpClientManager — STDIO/SSE/HTTP/WS/ServerStdio
5Java → DockerDocker APISandboxManager — 容器隔离执行

WebSocket/STOMP 实时通信时序 — 前端↔后端双向通信全景 · 基于源码实证

STOMP over SockJS — UML 时序图 React 前端 stompClient.ts 358行 Spring WebSocket 层 WebSocketConfig 249行 STOMP Broker /topic + /queue 业务服务层 Controller 1,215行 1 连接阶段 SockJS /ws 握手 new SockJS('/ws') → withSockJS() CONNECT Authorization: Bearer token + X-Session-Id StompAuthInterceptor 验证 CONNECTED SessionManager 注册 Principal↔SessionId 2 订阅阶段 SUBSCRIBE /user/queue/messages Broker 注册订阅 → 25种 ServerMessage 推送通道 SEND /app/bind-session 绑定 sessionId → SessionManager.bindSession() 3 用户消息 SEND /app/chat @MessageMapping("/chat") → QueryEngine sendUserMessage(text, attachments, references) 4 流式响应 push("stream_delta") MESSAGE /user/queue/messages stream_delta | thinking_delta | tool_use_start | tool_result ... tool_use_progress message_complete + cost_update + task_update 5 权限交互 permission_request → /user/queue/messages toolName + riskLevel + reason → PermissionDialog SEND /app/permission allow | deny | allow_always → PermissionPipeline 6 心跳检测 STOMP heartbeat 10s/10s + /app/ping → pong heartbeatScheduler (ws-heartbeat- 线程) 7 断线重连 指数退避 1s→2s→4s→8s→10s 重连 → SockJS /ws + CONNECT + re-bind-session 超时 10min → deactivate() · 映射保留供重连 (TTL 10min 清理) 关键配置参数 端点: /ws (SockJS) 心跳: 10s/10s 重连: 1s→10s cap 超时: 10min 消息限: 128KB 缓冲: 1MB 发送超时: 30s Client→Server 12 @MessageMapping Server→Client 25种推送类型 线程池: 4~20 队列: 200 TTL清理: 5min 12 种 Client→Server /app/chat /app/permission /app/permission-bubble /app/interrupt /app/model /app/permission-mode /app/command /app/mcp /app/rewind /app/elicitation /app/ping /app/bind-session WebSocketController.java 后端 websocket/ 4文件 1,755行 WebSocketConfig.java 249行 前端 stompClient.ts 358行 dispatch.ts 437行 useWebSocket.ts 119行
03

Agent Loop — 8步循环引擎

engine/ 5,942行 · QueryEngine.java 1,038行
1
压缩级联 ContextCascade
AutoCompact 状态回写 · 上下文窗口管理 · 触发条件: token数 > 阈值
2
创建流式执行会话 StreamingToolExecutor.newSession
初始化工具执行上下文 · 并行通道就绪
3
API 调用 + 模型降级 LlmProvider.streamChat
流式工具执行(立即启动) · 413二阶段恢复 · 模型降级链
4
收集 API 响应 StreamCollector.buildAssistantMessage
流式chunk聚合 · 工具调用提取 · thinking块处理
5
消费工具结果 并行执行，异步等待
工具权限检查 → 并行执行 → 结果收集 · 事务边界隔离
6
继续/终止判定
end_turn 信号检测 · max_tokens 恢复机制 · StopHook 自定义拦截
7
工具摘要注入 ToolResultSummarizer
长结果截断摘要 · LLM辅助压缩 · 上下文预算控制
8
状态更新 → 回到 Step 1 LOOP
消息历史追加 · 统计更新 · 压缩指标评估 · 循环继续
▸ Agent Loop 8步循环引擎
QueryEngine.java — 1,038行 · 8步循环 · 流式工具执行 1 压缩级联 ContextCascade AutoCompact·上下文窗口 2 创建流式会话 StreamingToolExecutor 初始化工具执行上下文 3 API调用+降级 LlmProvider.streamChat 流式执行·413恢复·降级链 ModelTierService · 156行 N级降级链 · 冷却管理 · 健康探测 4 收集API响应 StreamCollector chunk聚合·工具调用提取 5 消费工具结果 并行执行·异步等待 权限检查→并行→收集 6 继续/终止判定 end_turn·max_tokens StopHook自定义拦截 7 工具摘要注入 ToolResultSummarizer LLM压缩·预算控制 8 状态更新 消息历史追加 统计更新·回到Step1 LOOP Step 6 判定分支 继续循环 有工具调用 → Step7 → Step1 返回结果 end_turn信号 → 输出给用户 错误恢复 max_tokens → 截断 → 重试 核心步骤 LLM API调用 执行/循环 判定节点 循环路径 分支决策
▶ 引擎关键特性
流式工具执行

Step 3 中工具调用流到即执行，不等完整响应

413二阶段恢复

首次截断context → 二次仍失败则模型降级

事务边界

每步执行具有独立事务语义，失败不影响历史

04

18步权限管线

permission/ 11文件 2,672行 · PermissionPipeline.java 752行
▶ STAGE 1: 拒绝 / 询问规则 11 步
1a
deny 规则检查
显式拒绝列表匹配 → 直接 DENY
1b
ask 规则检查
需询问用户列表匹配 → 进入 ASK 流程
1c
工具自身权限检查
tool.checkPermissions() → 工具内置安全约束
1d
工具实现拒绝
工具执行层返回拒绝 → DENY
1e
requiresUserInteraction
标记需要用户交互 → ASK
1f
内容级 ask 规则 优先于 bypass
内容模式匹配 → 强制 ASK，无法被 bypass 跳过
1f-pre
系统级命令黑名单 bypass 免疫
CommandBlacklistService 检查 → 高危命令永久拦截
1f-w
写路径危险文件检查
检测写入 .env / 配置 / 密钥文件 → ASK
1f-b
Bash 危险删除 + 环境变量
rm -rf / export 等危险模式 → ASK
1g
安全检查 bypass 免疫
.git/ .zhikun/ 等敏感目录保护 → 永久拦截
1k
敏感系统文件访问检查
/etc/passwd, ~/.ssh/ 等系统级保护
▶ STAGE 2: 允许规则 5 步
1h
Hook 权限规则注入
StopHook / 外部插件注入的动态权限规则
1i
Classifier 权限规则注入 auto 模式
AutoModeClassifier (591行) 智能分类 → 自动授权
1j
Sandbox 权限规则覆盖
Docker 沙箱环境下 → 放宽权限约束
2a
bypassPermissions 模式
全局绕过开关 → 跳过非免疫检查
2b
alwaysAllow 规则
持久化允许列表匹配 → 直接 ALLOW
▶ STAGE 3: 模式转换 1 步 → 7 模式
3
passthrough → ask，进入模式分支
DEFAULT PLAN ACCEPT_EDITS DONT_ASK BYPASS AUTO BUBBLE
辅助组件: AutoModeClassifier (591行) · PermissionRuleRepository (271行) · PermissionRuleMatcher (253行) · PermissionModeManager (155行)
▸ 18步权限管线全景流程
PermissionPipeline.java — 752行 · 18步 · 3阶段 决策树结构 — 每步匹配即短路返回，不走完所有步骤 · 🔒 = bypass免疫（即使bypass=true也会拦截） STAGE 1: 拒绝 / 询问规则 11 步 — 安全过滤（短路决策树） DENY 返回 ASK 返回 1a deny规则 显式拒绝→DENY findDenyRule() 1b ask规则 需询问→ASK findAskRule() 1c 工具权限 checkPermissions() →DENY/ASK/PASS 1d 工具拒绝 DENY→短路 PermBehavior.DENY 1e 用户交互 requiresInteraction →ASK短路 🔒 1f 内容级ask bypass 免疫 裸shell+危险模式 🔒 1f-pre 命令黑名单 bypass 免疫 ABSOLUTE_DENY/ASK 1f-w 危险文件写入 .env/密钥→DENY/ASK PathSecurityService 1f-b 危险Bash rm -rf/export→ASK env变量篡改检测 🔒 1g 安全检查 bypass 免疫 .git/.zhikun/.env/.ssh 1h Hook规则注入 PreToolUse Hook proceed=false→ASK 1i Classifier注入 仅auto模式 高风险命令→ASK 1j Sandbox覆盖 Docker放宽权限 沙箱内→ALLOW 🔒 1k 敏感文件 bypass 免疫 /etc/passwd ~/.ssh → DENY → ASK 全部通过 → Stage2 🔒 1f · 1f-pre · 1g · 1k = 4步 bypass免疫，无法绕过 仅当 Stage1 全部通过 STAGE 2: 允许规则 2 步 — 授权放行 2a bypass模式 BYPASS/PLAN+bypass → ALLOW 2b alwaysAllow 持久化允许列表 → ALLOW 匹配 → ALLOW 未匹配 → passthrough STAGE 3: 模式转换 passthrough → ask → 7 模式分支 passthrough → ask 只读NONE → ALLOW DEFAULT 用户确认 PLAN 只读放行 ACCEPT_EDITS 编辑放行 DONT_ASK 写→DENY BYPASS 全部放行 AUTO LLM两阶段 BUBBLE 冒泡父Agent AUTO: killswitch检查 → LLM分类 classify() → ALLOW / ASK(降级) 最终决策: ALLOW / DENY / ASK / BUBBLE
05

Bash 安全模块 — 5层 AST 解析

tool/bash/ 13文件 5,091行
AST 解析架构 (递归下降)
parseProgram()
└─ parseStatements(terminator)
└─ parseAndOr()
└─ parsePipeline()
└─ parseCommand()
├─ parseSimpleCommand()
├─ parseIf / While / For
├─ parseFunction
└─ subshell / compound
核心组件
BashParserCore1,117 行 — 递归下降解析器
BashCommandClassifier1,105 行 — 命令分类引擎
BashLexer824 行 — 词法分析器
BashSecurityAnalyzer772 行 — AST 安全扫描
PathValidator341 行 — 路径安全校验
SedValidator204 行 — sed 命令校验
HeredocExtractor196 行 — heredoc 提取
安全分析结果模式: Simple(commands) TooComplex(reason) ParseUnavailable

Bash 安全模块 AST 解析流水线 — 6层纵深防御 · 13文件 5,091行

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行
06

LLM 多提供商架构

llm/ 22文件 2,911行
▶ Provider 抽象层
LlmProviderRegistry (237行) — 提供商注册中心
├── AnthropicProvider (463行) → Claude 系列
└── OpenAiCompatibleProvider (932行)
├── OpenAI GPT
├── 通义千问 (Qwen)
├── DeepSeek
├── Moonshot / Kimi
├── 智谱 GLM-4
└── Ollama 本地部署
模型别名:
light → qwen-plus
standard → qwen3.6-plus
premium → qwen3.6-max-preview
▶ 辅助组件
ModelRegistry
127行 · 模型配置注册
MessageParamConverter
391行 · 消息参数转换
ThinkingBudgetCalculator
104行 · thinking预算
LlmErrorClassifier
154行 · 错误分类
RetryPolicy
97行 · 重试策略
ApiKeyRotationManager
密钥轮换管理
LLM 多提供商抽象层架构 LlmProvider 统一接口 chat() / streamChat() / getModels() AnthropicProvider 463行 · Claude 系列 OpenAiCompatibleProvider 932行 · 统一兼容层 OpenAI GPT GPT-4o / o1 / o3 通义千问 Qwen qwen3.6-max DeepSeek deepseek-chat Google Gemini gemini-2.5-pro Ollama 本地 llama / qwen-local Moonshot / Kimi moonshot-v1 智谱 GLM-4 glm-4-plus ModelRegistry 127行 · 模型配置注册中心 · 别名映射 LlmProviderRegistry 237行 ApiKeyRotation 密钥轮换 Anthropic 独立适配 OpenAI兼容层 (统一5+提供商) 本地部署支持
07

MCP 双向协议架构

mcp/ 30文件 5,219行（main/源码，含测试则34文件/6,325行）
Client 端
McpClientManager586 行 — 生命周期管理
McpServerConnection512 行 — 连接路由
McpToolAdapter252 行 — 工具适配
McpPromptAdapter193 行 — Prompt 适配
TokenEncryptionService245 行 — AES-GCM 加密
SseHealthChecker健康检查
McpApprovalService审批服务
Server 端 + 传输层
Server 端 (mcp/server/):
McpServerEntrypoint (186行) · McpServerToolHandler (152行)
5种传输协议:
STDIO (193行) SSE (378行) HTTP (374行) WebSocket (269行) ServerStdio (241行)
MCP 双向协议架构 · 5种传输层 MCP Client 消费外部工具 McpClientManager · 586行 McpServerConnection · 512行 McpToolAdapter · 252行 McpPromptAdapter · 193行 TokenEncryption · 245行 AES SseHealthChecker · 心跳检测 MCP Server 暴露自身工具 McpServerEntrypoint · 186行 McpServerToolHandler · 152行 McpApprovalService · 审批 传输协议层 STDIO · 193行 SSE · 378行 HTTP Streamable · 374行 WebSocket · 269行 ServerStdio · 241行 mcp/ 30文件(main) · 5,219行 Client 20文件 + Server 4文件 + Transport 6文件 ◀ Client → 外部MCP服务器 外部客户端 → Server ▶ Client端数据流 Server端数据流 双向传输通道
08

多Agent协调系统

coordinator/ 17文件 3,777行 + agent/ 10文件 2,047行 = 29个类
Research
调研阶段
需求分析与信息收集
Synthesis
综合阶段
方案设计与策略制定
Implementation
实施阶段
代码编写与修改
Verification
验证阶段
测试与质量检查
▶ 核心组件详情
CoordinatorWorkflowEngine436行 — 四阶段编排
SubAgentExecutor918行 — 子代理执行(权限冒泡)
SwarmService463行 — 多Agent任务分发
SwarmWorkerRunner332行 — Worker执行引擎
CoordinatorPromptBuilder484行 — Prompt生成
TeamManager137行 — 团队管理
TeamMailbox109行 — 团队邮箱
LeaderPermissionBridge162行 — 权限冒泡机制
▸ 多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阶段编排引擎 LeaderPermissionBridge 162行 — 权限冒泡桥接 ResultAggregator 结果聚合 → Coordinator SubAgentExecutor 918行 · 权限冒泡 ResultAggregator → Coordinator 结果回传 coordinator/ 17文件 3,777行 29个协调类 4阶段工作流 3通信机制 ~35工具/Worker WorkflowPhase.java — sealed interface permits Research | Synthesis | Implementation | Verification · phasePrompt() + allowedTools() + phaseIndex()
09

工具系统

tool/ 144文件 16,815行 · tool/impl/ — 47个工具
▶ 工具分类树
文件操作
ReadFile
WriteFile
EditFile
ListDir
SearchFiles
执行 & 终端
BashTool → Sec §5
TaskTool
NotebookTool
搜索 & 分析
GrepTool
GlobTool
CodeSearchTool
Agent & 协作
SubAgentTool
MemoryTool → §11
McpTool → §7
Web & Git
WebFetchTool
WebSearchTool
GitTool
共 47 个工具实现 · 每个工具继承 AbstractTool 基类 · 支持权限声明 + Schema 定义 + 流式结果
▸ 工具分类与执行管道全景
47 个工具 × 5 层执行管道 工具分类树 — 47个工具 / 5类 核心执行 (8) BashTool792行 PowerShellTool REPLTool TerminalCaptureTool 文件操作 (5) FileReadTool285行 FileEditTool379行 FileWriteTool GlobTool173行 GrepTool380行 代码分析 (4) GitTool244行 LspTool SnipTool SearchTool Web工具 (3) WebFetchTool442行 WebSearchTool WebBrowserTool 任务监控 (3) MonitorTool305行 CronTools + SubAgentTool, McpTool, MemoryTool, NotebookTool ... 执行管道 — 5层栈结构 L1 ToolRegistry 工具注册表 — 工具发现与注册 AbstractTool → Schema定义 + 权限声明 + 注册 L2 ToolExecutionPipeline 执行管道 — 核心编排引擎 参数校验 → 权限检查 → 执行调度 → 超时控制 L3 StreamingToolExecutor 流式执行器 — 大输出处理 流式输出 → 增量传输 → 内存控制 → 背压 L4 Hook / Callback 钩子层 — 前后置处理 onBefore → 日志/审计 → onAfter → 通知 L5 ToolResult 结果聚合 — 统一输出 格式化 → Snip截断 → JSON封装 → 返回Agent 注册 调用 tool/ 144文件 16,815行 核心执行×8 文件操作×5 代码分析×4 Web×3 监控×3 其他×18
10

上下文管理 — 5层压缩策略

L1 Snip
工具结果截断
长输出裁剪
L2 MicroCompact
MicroCompactService
183行 · 轻量压缩
L3 AutoCompact
CompactService
1,058行 · LLM摘要压缩
L4 CollapseDrain
ContextCollapseService
283行 · 折叠排水
L5 ReactiveCompact
413恢复触发
紧急压缩
▶ 核心组件
CompactService1,058 行 — 主压缩引擎，LLM 辅助摘要
ContextCascade340 行 — 级联决策，选择压缩层级
ContextCollapseService283 行 — 折叠排水，保留关键信息
MicroCompactService183 行 — 微压缩，无 LLM 调用
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行 IncrementalCollapseManager 175行 · 增量折叠 · 每10轮触发 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行 IncrCollapseManager175行 共 13 个文件 · 2,932 行
10b

Token 预算与模型策略

▶ IncrementalCollapseManager 增量折叠 · 175行
注解@Service @ConditionalOnProperty(name="context.cascade.incremental-collapse.enabled")
shouldCollapse()累计 turnCount，每10轮触发折叠
recordCollapse()记录折叠段元数据
状态管理会话级 ConcurrentHashMap · 30分钟超时自动清理
▶ ModelTierService 模型降级 · 156行
注解@Service
resolveModel()选择最佳可用层级
triggerCooldown()API容量错误 → 冷却管理
reportSuccess()健康探测恢复（3次成功阈值）
冷却策略30分钟默认 · retry-after感知 · 短期重试豁免
11

辅助系统

▶ 记忆系统 memdir/ 5文件 1,089行
MemdirService598行 — 核心记忆服务
MemorySearchEngine197行 — BM25 + LLM 重排
MemoryRerankService128行 — 重排序
MemoryTool118行 — 工具接口
▶ Skill 系统 skill/ 7文件 1,169行
SkillRegistry468行 — 6级加载源
FrontmatterParserSkill 元数据解析
▶ 安全模块 security/ 5文件 1,248行
CommandBlacklistService377行 — 命令黑名单
PathSecurityService433行 — 路径安全
SensitivePathRegistry300行 — 敏感路径注册
SensitiveDataFilter68行 — 数据过滤
SecurityAuditLogger70行 — 审计日志
▶ Docker 沙箱 sandbox/ 2文件 316行
SandboxManager容器隔离执行环境

记忆系统架构 — BM25检索 · LLM重排序 · 会话历史

memdir/ 5文件 1,089行 + history/ 2文件 455行 + controller/ 2文件 240行 + frontend 1文件 112行 存储层 MEMORY.md 文件持久化 · 25KB上限 · 200行截断 SQLite memories 表 V002迁移 · CRUD · source索引 .zhikun/team-memories/ 团队级共享 · .md 文件扫描 MemoryCategory 4类 EPISODIC事件记忆 SEMANTIC语义知识(默认) PROCEDURAL程序工作流 TEAM团队共享 检索管道 (Query → BM25 → LLM Rerank → Top-K) 用户 Query searchMemories(q, topK) N-gram 分词器 Unigram + Bigram · CJK 停用词过滤 (中英文54个) BM25 评分 k1=1.2 b=0.75 标题2x加权 · IDF预计算 MemorySearchEngine.java 197行 · 纯Java BM25实现 DocumentEntry · ScoredResult Top-20候选 LLM Rerank 精排 MemoryRerankService.java 128行 · SideQueryService调用 3s超时 · 512 maxTokens · 降级兜底 relevanceScore排序 Top-K 精排结果 MemdirService.java 598行 · 核心服务 · 读写删搜 压缩70% · 过期清理90天 接口与注入层 MemoryTool.java 117行 · LLM工具接口 read / write / delete 三操作 MemoryController.java 143行 · /api/memory REST GET/PUT/POST/DELETE · SQLite+MD双源 buildMemoryPrompt() Prompt注入 · Personal+Team readMemoriesForPrompt → SystemPrompt MemoryEditorPanel.tsx 112行 · 前端记忆编辑面板 FileHistoryService.java 359行 · 快照·事务·Rewind回退 注入 写入流程: 对话 → 关键信息提取 → 记忆索引构建 用户对话 消息流入 LLM 信息提取 MemoryTool.write MemdirService writeMemory() · 原子写入 MEMORY.md 追加 · 元数据头 compactMemories() 50K上限 → 保留70%最新 purgeExpiredMemories() 90天过期自动清理 source: AUTO | USER | TOOL 格式: <!-- source:TOOL time:2024-... category:semantic --> Java MemdirService 598行 · SearchEngine 197行 · RerankService 128行 · MemoryTool 117行 · Category 49行 API MemoryController 143行 · FileHistoryCtrl 97行 TSX MemoryEditorPanel 112行

Hook + Plugin 协作扩展机制 — hook/ 5文件 895行 + plugin/ 15文件 1,468行

Hook Registry — 注册表 HookRegistry.java 166行 HookEvent.java 76行 Plugin 加载与管理层 Plugin Loader PluginLoader.java 330行 PluginClassLoader.java 89行 JAR发现 · 隔离ClassLoader PluginManifest.java 47行 Plugin Manager PluginManager.java 422行 PluginSystemInitializer.java 40行 生命周期管理 · 注册/卸载 ReloadPluginsCommand.java 38行 Plugin Lifecycle LoadedPlugin.java 97行 PluginExtension.java 79行 PluginContext.java 25行 PluginLoadResult 27行 · PluginError 47行 插件实例池 — 运行时拦截链 HelloPlugin.java 80行 · 内置示例 builtin/ PluginCommandWrapper 32行 · 命令包装 命令→插件桥接 PluginSourceType 14行 · 来源枚举 LOCAL / REMOTE / BUILTIN HookHandler.java 101行 · Hook执行器 拦截链执行入口 运行时拦截链 — Hook 执行流 JAR 发现 隔离加载 Hook 注册 运行时拦截 SSRF 防护 HookService.java 337行 HttpHookExecutor.java 177行 SsrfGuard.java 139行

Skill 系统任务分解架构 — skill/ 7文件 1,169行 · DAG执行

高级任务 用户指令 Slash Command Skill 核心引擎 SkillRegistry SkillRegistry.java 411行 6级加载源 · Skill发现 SkillDefinition.java 94行 元数据解析 FrontmatterParser 240行 FrontmatterData 74行 YAML Frontmatter SkillExecutor SkillExecutor.java 112行 串行/并行调度 SkillTool SkillTool.java 125行 Agent ↔ Skill桥接 ArgumentSubstitution.java 113行 · 参数替换引擎 Skill 实现节点池 front-design commit review-pr pdf translate ● 串行执行 ● 可并行执行 Markdown Skill文件 · YAML Frontmatter · 动态加载 结果聚合 输出合并 返回Agent 6级加载源 1. 内置 Skill (builtin) 2. 项目 .qoder/skills/ 3. 用户级 ~/.qoder/skills/ 4. 团队共享目录 5. 远程 Registry 6. 动态插件注入 优先级: 低 → 高 skill/ 7文件 · 1,169行 | SkillRegistry 411行 · FrontmatterParser 240行 · SkillTool 125行 · SkillExecutor 112行
12

React 前端架构

137文件 19,543行
▶ 组件层 86文件 13,502行 22子目录
visualization ×14 message ×19 status ×9 layout ×7 input ×6 common ×5 settings ×4 dialog ×4 theme ×3 permission ×2 git ×2
▶ 14个可视化组件
CodeComplexityTreemap663行 CodePathTracer621行 ChangeImpactGraph570行 APIContractViewer527行 CodeDiagramGenerator407行 AgentDAGChart383行 GitTimeline369行 APISequenceDiagram255行 SchemaViewer235行 MermaidBlock204行 BlameView186行 AgentDAGNode103行 ToolProgressBar99行 MiniLogViewer67行
▶ 状态管理 — 32 个 Zustand Store 约2,846~3,278行(仅业务Store)
coordinatorStoremcpStoreconfigStoreswarmStoremessageStoreplanStoretaskStoresessionStoretoolStorepermissionStore + 22 more stores
▸ 32个 Zustand Store 分类与依赖关系
业务领域 Store messageStore sessionStore taskStore permissionStore costStore planStore toolStore messageStore ← permissionStore, costStore 系统集成 Store configStore 8.2KB mcpStore 8.1KB bridgeStore coordinatorStore swarmStore 7.4KB configStore ← 其他所有Store依赖 UI与对话 Store dialogStore notificationStore inboxStore appUiStore 高级分析 Store codeInsightStore complexityStore changeImpactStore codePathStore 元数据 Store apiContractStore fileTreeStore broadcastMiddleware.ts 跨Store广播中间件 — 事件驱动状态同步 连接所有32个Store · 发布/订阅模式 业务×7 系统×5 UI×4 分析×4 元数据×2 broadcast广播 configStore依赖 约2,846~3,278行
▶ API 通信层
dispatch.ts 437行

REST API 统一调度层 · 请求/响应拦截 · 错误重试

stompClient.ts 358行

WebSocket/STOMP 实时通信 · 消息订阅 · 重连机制

技术栈
React 18.3Vite 5.4Zustand 4.5Monaco Editor 0.52xterm.js 5.5Tailwind 3.4Mermaid 11.14
13

Python 分析服务架构

32文件 7,213行
▶ 分析引擎 analyzers/ 2,872行
flow_chart_generator.py657 行
code_path_tracer.py622 行
call_graph_builder.py582 行
sequence_diagram_generator.py527 行
change_impact_analyzer.py416 行
▶ 业务服务 services/ 1,725行
browser_service.py658 行
complexity_analyzer.py515 行
tree_sitter_service.py237 行
▶ API 路由 routers/ 1,526行
/api/analysis434行 /api/browser285行 /api/files276行 /api/code-intel213行 /api/git125行 /api/v1/tokens97行 /api/code-quality95行
6个能力域 支持优雅降级
CODE_INTELFILE_PROCESSINGCODE_QUALITYANALYSISGIT_ENHANCEDBROWSER_AUTOMATION
▸ Python 代码分析引擎架构
FastAPI 应用入口 main.py 3.9KB · uvicorn ASGI 路由层 — 8个API端点 /analyze /complexity /dependencies /metrics /patterns /health /capabilities /batch 分析器层 — 7个核心分析器 complexity_analyzer 圈复杂度分析 · McCabe指标 dependency_analyzer 依赖关系图 · 模块耦合 code_metrics_analyzer 代码指标 · LOC/函数数 pattern_analyzer 代码模式检测 smell_detector 代码异味检测 performance_profiler 性能分析 security_analyzer 安全分析 服务层 — 7个支撑服务 cache_service storage_service notification_svc batch_processor rate_limiter error_handler metrics_exporter Prometheus 输出层 JSON 分析报告 → 前端可视化组件 (14个) → 浏览器渲染展示 32文件 7,213行 8个API端点 7个分析器 7个服务 14个前端组件 FastAPI
14

部署架构

Docker 多阶段构建
# docker-compose.yml 编排
java-backend: Spring Boot 3.4
port: 8080
react-frontend: Vite dev / Nginx prod
port: 5173 (dev) / 80 (prod)
python-service: FastAPI + uvicorn
port: 8000
启停管理
Dockerfile多阶段构建
docker-compose.yml服务编排
docker-entrypoint.sh入口脚本
start.sh一键启动
stop.sh优雅停止
15

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

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 18步 2,672行 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
ZhikunCode Architecture Reference · Open Source · MIT License · github.com/zhikunqingtao/zhikuncode