ZhikunCode 系统架构

Enterprise-Grade AI-Powered Web IDE — Architecture Reference
Java 68.9% TypeScript 24.6% Python 6.5% 109,548 Lines 837 Files
01

项目总览面板

ZhikunCode · Web IDE · 浏览器 + 后端服务 + 分析服务
Java 后端主源码
75,461 行 / 512 文件
Java 测试代码
27,621 行 / 114 文件
React 前端
26,936 行 / 182 文件
Python 服务
7,151 行 / 29 文件
技术概览
项目名称ZhikunCode
产品形态AI-Powered Web IDE
总代码量109,548 行（含测试 137,169 行）/ 837 文件
后端框架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 + 15个自定义图表组件
代码量分布
Java 主源码
75,461 Java 测试
27,621 React 前端
26,936 Python 服务
7,151
02

三端分离架构总览

核心通信链路
React 前端 26,936 行 · 182 文件 · 30 Zustand Store · 104 组件 · 15 可视化 dispatch.ts 557行 | stompClient.ts 363行 Java 后端 75,461 行 · 512 文件 · Spring Boot 3.4 Port 8080 · Agent Loop · Permission · MCP · Tools Python 分析服务 7,151 行 · 29 文件 · FastAPI Port 8000 · 6 能力域 · tree-sitter LLM API MCP Servers Docker 沙箱 文件系统 REST API + WebSocket/STOMP Vite Proxy → :8000
▸ 三端分离架构全景插画
React 前端 26,936 行 · 182 文件 32 Store 104 组件 15 可视化 dispatch 557 363 dispatch.ts 557行 · stompClient.ts 363行 REST + WS/STOMP HTTP Proxy Java 后端 75,461 行 · 512 文件 · Spring Boot 3.4 Agent Engine 8,873行 Permission 14步 752行 Tool System 105+文件 ~19,081行 MCP Protocol 4传输 5,219行(main) LLM Provider 26文件 3,456行 Multi-Agent 19文件 4,138行 Bash Security 6层AST 5,620行 Context Mgmt 5层压缩 :8080 Python 分析服务 7,151 行 · 29 文件 · FastAPI Analyzers Services 8 Routers tree-sitter :8000 LLM APIs MCP Servers Docker 沙箱 文件系统 Java 75,461行 React 26,936行 Python 7,151行 通信链路 外部服务
▶ 5条通信链路详情
#链路协议关键文件
1前端 → Java 后端REST API + WebSocket/STOMPdispatch.ts (557行) + stompClient.ts (363行)
2前端 → Python 服务Vite Proxy 转发/api/git, /api/files, /api/code-quality, /api/analysis → :8000
3Java → LLMHTTP/SSE StreamLlmProviderRegistry → Anthropic / OpenAiCompatible
4Java → MCP Server4种传输McpClientManager — STDIO/SSE/HTTP/WS
5Java → DockerDocker APISandboxManager — 容器隔离执行
02.5

全链路数据流 — 从用户输入到流式响应

dispatch.ts 557行 → STOMP/WS → QueryEngine 8步循环 → 流式工具执行 → Zustand 实时更新

基于源码验证的端到端请求闭环：用户消息经 STOMP 发送至后端 Agent Loop，LLM 流式响应与工具执行结果通过 WebSocket 实时推送回前端 Zustand Store。

REACT 前端 JAVA 后端 (Agent Loop) 结果回流 用户输入 ChatInput → handleSubmit() stompClient.ts (363行) sendUserMessage('/app/chat') STOMP over SockJS · 心跳10s · 指数退避重连 dispatch.ts (557行) 按 type 分发到 Zustand Store 40+ 消息类型 · 序列号校验 · 跨Store协调 Zustand Store (30个) messageStore · sessionStore · activityStore ... UI 实时渲染 (86 组件) WebSocketController /app/chat → handleChat() · REST API QueryEngine.queryLoop() — 8步循环 (1,404行) ① 压缩级联检查 ContextCascade · MicroCompact ② 创建执行会话 StreamingToolExecutor.newSession() ③ LLM 流式 API 调用 provider.streamChat() · ApiRetry ④ 收集流式响应 StreamCollector → AssistantMessage ⑤ 工具并行执行 Virtual Thread · 即时启动有序返回 ⑤½ 自纠错检测 SelfCorrectionLoop · shouldAbort ⑥ 终止/继续判定 TerminationStrategy · 策略模式 ⑦ 工具摘要注入 ToolResultSummarizer · 截断/清理 ⑧ 状态更新 → 回Step① 回写 QueryLoopState ToolExecutionPipeline — 7阶段 Schema验证 → 自定义验证 → PreHook → 权限检查 → 工具调用 → PostHook → contextModifier ⚡ 流式触发: StreamCollector 在 BlockStop 事件时即时启动工具执行 (不等待完整响应) LLM API (Claude/GPT) LlmProviderRegistry · 多模型支持 Python 分析服务 (:8000) HTTP Proxy · FastAPI · tree-sitter · 6能力域 STOMP 流式推送 /user/queue/messages stream_delta · tool_result · message_complete STOMP /app/chat streamChat() HTTP Proxy handler.push() WS /user/queue/messages → parseMessage() → dispatch() stompClient.ts 363行 dispatch.ts 557行 QueryEngine 1,404行 8步循环 StreamingToolExecutor 286行 ToolExecutionPipeline 597行 7阶段 Python 7,151行
02b

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

User (Browser) REACT FRONTEND 104 Components 30 Zustand dispatch.ts stompClient.ts 14 Viz JAVA BACKEND (75,461 lines) Agent Loop engine/ 8,873行 Permission 14步 2,672行 Bash Security 6-layer AST 5,620行 Tool System 105+文件 ~19,081行 43工具 LLM Provider 26文件 3,456行 MCP Protocol 30文件(main) 5,219行 Multi-Agent 19文件 4,138行 Context Mgmt 5层压缩 Memory 1,089行 BM25+LLM Skill 1,437行 6级加载 Security 1,248行 黑名单+审计 Sandbox Docker隔离 316行 PYTHON SERVICE (7,151 lines) Analyzers (2,872行) 8 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
03

Agent Loop — 8步循环引擎

engine/ 8,873行 · QueryEngine.java 1,404行
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,404行 · 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调用 执行/循环 判定节点 循环路径 分支决策
▶ 引擎关键特性
流式工具执行

流到即执行 · 无需等完整响应

413二阶段恢复

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

事务边界

独立事务语义 · 失败不影响历史

自纠错检测 — 错误感知与自动恢复

▸ Step 5.5 Self-Correction Detection · SelfCorrectionLoop.java 350行 · MAX_ATTEMPTS=3
QueryEngine.java L540-585 → SelfCorrectionLoop.java · 错误检测 → 修复指令生成 → 重试/中止 ① Feature Flag 检查 SELF_CORRECTION_LOOP QueryEngine.java:540 ② 查找 Bash 工具输出 遍历 AssistantMessage 仅处理 name=="Bash" :553 ③ shouldAbort() 检查 错误数↑ | 新文件 | 新类型 SelfCorrectionLoop:145-179 修复引入新错误 → 立即中止 ABORT: resetAttempts ④ detectAndPrepareCorrection() 编译错误优先 → 测试失败次之 SelfCorrectionLoop:68-129 attempts >= MAX_ATTEMPTS(3) → 放弃 CompileErrorParser Java/TS/Python 编译错误识别 优先级 HIGH · SelfCorrectionLoop:86 TestFailureParser JUnit/Jest/Pytest 失败识别 优先级 LOW · SelfCorrectionLoop:105 CorrectionInstruction 生成 instruction ≤ 800 tokens truncateToTokenLimit :246 Token 限制 MAX_INSTRUCTION_TOKENS=800 MAX_STACK_TRACE_LINES=3 重试循环 · QueryEngine.java:566-579 注入纠错 UserMessage correction.instruction() QueryEngine:572-575 incrementAttempts attempts++ (max 3) QueryEngine:577 保存 previousToolOutput 供下轮 shouldAbort 对比 QueryEngine:578 继续 Agent Loop LLM 基于指令重新修复 → Step 1 (下轮循环) 重试循环 (≤3次) — 下轮再次进入 Step 5.5 检查 ✓ 成功: 无错误检出 → 正常继续 Step 6 ✗ 中止: 新错误引入 → resetAttempts :561 ⚠ 超限: attempts≥3 → 放弃修复,继续循环 :72 SelfCorrectionLoop shouldAbort() · isPersistentError() 349行 · engine/correction/
04

14步权限管线

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
skipAllPrompts 模式
全局绕过开关 → 跳过非免疫检查
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行)
▸ 14步权限管线全景流程
PermissionPipeline.java — 752行 · 14步 · 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

AUTO 模式 — LLM 智能权限分类 (AutoModeClassifier · 591行)

▸ AutoModeClassifier 两阶段 XML 分类决策流
AutoModeClassifier.java — 591行 · 两阶段 XML 分类 · LRU缓存 · 4级模型回退 Pipeline Stage 3 case AUTO → FeatureFlag killswitch → classify(tool, input, context) → PermissionDecision classify(Tool, ToolInput, PermissionContext) 工具名 + 命令/参数 + 权限上下文(规则集) consecutiveFailures ≥ 3 ? → ASK (分类器暂停) YES NO LRU 缓存 (容量100) 命中? → 缓存结果 (跳过LLM) HIT key=toolName:inputHash MISS toAutoClassifierInput() 为空?→ALLOW Quick 阶段 (快速判断) max_tokens = 64 stop = ['</block>'] XML输出: <block>no</block>=ALLOW · <block>yes</block>=DENY ALLOW (缓存 + 返回) <block>no</block> <block>yes</block> 或解析失败 Thinking 阶段 (深度推理) max_tokens = 4096 chain-of-thought 推理 <thinking>…</thinking> + <block> + <reason> ALLOW (缓存) no ASK (需用户确认) yes / 解析失败 Timeout(3s) → ASK · 不可用 → fallbackToRuleMatching() LLM: resolveClassifierModel() 4级回退 · chatSync() Prompt: BASE_PROMPT + PERMISSIONS + FEW_SHOT
05

Bash 安全模块 — 6层 AST 解析

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

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

Bash Command Input BashTool.java 559行 → 入口 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,235行 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/ 17文件 · 5,620行 | sandbox/ 2文件 · 316行 | security/ 5文件 · 1,248行 | 总计 24文件 · 7,184行

Docker 沙箱隔离 — 容器级安全边界 — SandboxManager.java 259行 · SandboxConfig.java 57行

Docker 沙箱隔离架构 — SandboxManager + SandboxConfig + PermissionPipeline Step 1j 主机环境 (Host OS) 主机文件系统 /app/data → 持久化数据 (SQLite) ${WORKSPACE_PATH} → 用户代码项目 docker-compose.yml volumes 定义 Docker Daemon docker info → 可用性检测 (缓存) 资源限制 (deploy.resources) memory limit: 4g (docker-compose) memory reservation: 1g 沙箱命令限制: -m 512m (SandboxConfig) SandboxConfig.java:24 memoryLimit SandboxConfig.java:12-57 enabled = false (默认关闭) image = ai-code-assistant-sandbox:latest timeoutSeconds = 300 networkEnabled = false mountMode = "ro" (只读) @ConfigurationProperties(prefix="sandbox") Docker 容器安全边界 (docker run --rm --read-only) 只读根文件系统 (--read-only) / → 只读 (容器根) /workspace → ${mountMode} 挂载 (默认 ro) /tmp → tmpfs rw,noexec,nosuid,size=100m SandboxManager.java:157-160 buildSandboxedProcess() 网络隔离 (--network=none) 默认: 完全禁用网络 networkEnabled=false → --network=none 阻断: curl, wget, nc, ncat, telnet SandboxManager.java:167-169 + :108-110 seccomp 系统调用过滤 --security-opt seccomp=${seccompProfile} SandboxManager.java:172-175 null=Docker默认配置 超时控制 (双重保护) timeout 300s (命令内嵌) + waitFor() SandboxManager.java:178,226-229 destroyForcibly() 命令沙箱路由 — shouldUseSandbox() :91-135 破坏性命令 → 强制沙箱: rm, rmdir, mv, chmod, chown, mkfs, dd, format, fdisk, parted 网络命令 → 强制沙箱: curl, wget, nc, ncat, telnet sudo 包装检测: 解包 sudo 前缀后再匹配首命令令牌 条件: isSandboxingEnabled() = config.enabled && isDockerAvailable() PermissionPipeline Step 1j — Sandbox 权限规则覆盖 evaluateSandboxRules() → PermissionPipeline.java:693-703 条件: sandboxManager.isSandboxingEnabled() == true 效果: FileEdit / FileWrite / Write / Edit / Bash / BashTool → 自动 ALLOW 原因: SANDBOX_OVERRIDE — 沙箱已提供容器级隔离，放宽权限约束 优先级: Step 1i (Classifier) 之后, Step 1k (敏感文件检查) 之前 — 命中即短路返回 docker run sandbox/ 2文件 316行 | 隔离层: read-only FS + network=none + seccomp + mem 512m + timeout 300s | 非root用户: zhikun
06

LLM 多提供商架构

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

模型降级与容错 — 多 Provider 自动切换

ModelTierService 多级模型降级链 ModelTierService.java:65 · ModelDegradationChain.java:28 · ApiRetryService.java:74 · ApiCircuitBreaker.java QueryEngine :303 调用 resolveModel() ModelTierService resolveModel(preferred, tierChain) 冷却检查 → 遍历降级链 → 选择最优可用 Effective Model cooldown=30min · recovery≥3次成功 ModelDegradationChain.DEGRADATION_CHAINS — 最多 3 级降级 (MAX_DEPTH=3) Tier 0 主模型 Tier 1 Tier 2 claude-sonnet-4-20250514 qwen-max deepseek-chat 跨厂商降级 qwen3.6-max-preview qwen3.6-plus qwen-max 同族降级 deepseek-chat qwen-plus qwen-max 跨厂商降级 qwen-max qwen-plus deepseek-chat 混合降级 LlmErrorClassifier 127行 · 6类错误分类 → 触发降级 OVERLOADED 529/503 RATE_LIMITED 429 PROMPT_TOO_LONG 413 AUTH_FAILED 401/403 NETWORK_TIMEOUT UNKNOWN ● 可重试: OVERLOADED / RATE_LIMITED / TIMEOUT ✕ 不可重试: PROMPT_TOO_LONG / AUTH_FAILED 529 → triggerCooldown() → 模型降级链切换 分类基于 HTTP Status + 消息关键词匹配 ApiCircuitBreaker 状态机 156行 · 3态熔断 · FAILURE_THRESHOLD=3 · RECOVERY=60s CLOSED ≥3 fails OPEN 60s后 HALF_OPEN 探测成功 探测失败 熔断 → 拒绝请求 → 快速失败(503) 半开 → 允许探测 → 成功恢复/失败重熔 密钥轮换 + 重试策略 ApiKeyRotationManager 150行 · ModelAwareRetryPolicy 124行 ▸ Round-robin 密钥轮换 Key₁ → Key₂ → Key₃ → ⟲ 循环 429限流 → 冷却60s → 自动跳过 全部冷却 → 选最早解冻Key ▸ ModelAwareRetryPolicy (指数退避+25%jitter) Claude: 5次 | base=60s | 遵循retry-after Qwen: 8次 | base=10s | 忽略retry-after DeepSeek: 6次 | base=20s | 遵循retry-after 恢复: 冷却30min → 健康探测(5min间隔) → 连续3次成功 → 移除冷却

API 密钥轮换 — ApiKeyRotationManager · 150行

API 密钥轮换机制 — Round-robin + 冷却跳过 ApiKeyRotationManager.java · 150行 · ConcurrentHashMap<Key,Instant> 冷却表 · AtomicInteger 轮换索引 Key Pool 密钥池 :30 List<String> apiKeys Key₁ sk-abc1...*** ● 可用 Key₂ sk-def2...*** ⏳ 冷却中 Key₃ sk-ghi3...*** ● 可用 Key_N ...（可扩展） ⟲ Round-robin 轮换 :31 AtomicInteger currentIndex :72 getAndUpdate(i → (i+1) % size) :39 过滤 null/blank · :42 log key数量 getNextKey() 轮换流程 :59-90 · 冷却检查 → 轮换 → 降级选择 :60 apiKeys.isEmpty()? 非空 :63 size==1 → 直接返回 多Key :71 for(attempt=0; attempt<size) :76 cooldown==null || now.isAfter(cooldown) → 返回 全部冷却 :82 所有Key冷却! :83-89 stream().min(cooldownUntil) → 最早解冻 返回可用 Key 冷却管理 CooldownMap :32 ConcurrentHashMap<String, Instant> markRateLimited(key) :109 触发: HTTP 429 限流响应 :111 cooldownUntil.put(key, now+60s) DEFAULT_COOLDOWN = 60s :28 Duration.ofSeconds(60) clearCooldown(key) :128 cooldownUntil.remove(key) hasAvailableKey() :141 anyMatch → cooldown过期? 429! :113 log.warn("API key rate-limited, cooldown until {}: key={}...{}", until, key[0:8], "***")
06a

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感知 · 短期重试豁免

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

STOMP over SockJS — UML 时序图 React 前端 stompClient.ts 363行 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 363行 dispatch.ts 557行 useWebSocket.ts 119行

WebSocket/STOMP 实时通信 — stompClient.ts 363行 · 双向消息流

▸ WebSocket/STOMP 实时通信协议栈 — 源码验证
LAYER 1 · CONNECTION WebSocketConfig.java:79 — registry.addEndpoint("/ws").withSockJS() Browser SockJS Fallback new SockJS('/ws') Spring STOMP Broker SimpleBroker /topic + /queue Transport: 128KB msg 1MB buf · 30s timeout LAYER 2 · STOMP FRAMES @stomp/stompjs · CONNECT headers: Authorization + X-Session-Id CONNECT Bearer + SessionId SUBSCRIBE /user/queue/messages SEND /app/* destinations MESSAGE Server → Client HEARTBEAT 10s in / 10s out ERROR onStompError Frontend · stompClient.ts (363行) #1 sendUserMessage() → /app/chat #2 sendPermissionResponse() → /app/permission #3 sendInterrupt() → /app/interrupt #4 sendSetModel() → /app/model #5 sendSetPermissionMode() → /app/permission-mode #6 sendSlashCommand() → /app/command #7 sendMcpOperation() → /app/mcp #8 sendRewindFiles() → /app/rewind #9 sendElicitationResponse() → /app/elicitation #10 sendPing() → /app/ping #11 bind-session (onConnect) → /app/bind-session SUBSCRIBE: /user/queue/messages → parseMessage() → dispatch() → Zustand Store L165: client.subscribe('/user/queue/messages', ...) Topic Routing · 双向消息流 Client → Server (SEND) Application prefix: /app /app/chat /app/permission /app/interrupt /app/model /app/permission-mode /app/command /app/mcp /app/rewind /app/elicitation /app/ping /app/bind-session /app/permission-bubble /app/activity-save /app/activity-update Server → Client (MESSAGE) /user/queue/messages convertAndSendToUser() /topic/session/{id} convertAndSend() broadcast /queue/coordinator/{id} CoordinatorEventBus 35+ 消息类型白名单 (VALID_MESSAGE_TYPES) stream_delta · thinking_delta · tool_use_start · tool_result permission_request · cost_update · task_update · agent_spawn Backend · WebSocketController.java @MessageMapping 14 handlers /chat L464 → executeQuery() Virtual Thread /permission L748 → allow/deny/allow_always /permission-bubble L785 /interrupt L801 → AgentLoop cancel /model L840 → sessionModels.put() /permission-mode L869 /command L888 → SlashCommand dispatch /mcp L991 → McpClientManager /rewind L1047 → file rollback /elicitation L1069 → ElicitationService /ping L1085 → sendPong() /bind-session L1094 → principal↔sessionId /activity-save L1185 /activity-update L1226 Server Push (messaging.convertAndSend*) SimpMessagingTemplate → /user/queue/messages SimpMessagingTemplate → /topic/session/{id} LAYER 4 · HEARTBEAT & RECONNECT Heartbeat 10s / 10s ws-heartbeat- scheduler 指数退避: 1s → 2s → 4s → 8s → 10s cap RECONNECT_TIMEOUT = 10min · stompClient.ts:107-109 CONNECT Auth Interceptor Bearer Token / Anonymous Principal Inbound Channel Pool core=4 max=20 queue=200
08

MCP 双向协议架构

mcp/ 30文件 5,219行（main/源码，含测试则34文件/6,325行）
McpClientManager · 586行 · 4协议 Client/Server 双向支持 MCP 2024-11-05 规范 生命周期: connect→init→ready→close STDIO · SSE · HTTP · WebSocket
MCP 双向协议架构 · 4种传输层 MCP Client 消费外部工具 McpClientManager · 586行 McpServerConnection · 512行 McpToolAdapter · 252行 McpPromptAdapter · 193行 TokenEncryption · 198行 AES SseHealthChecker · 心跳检测 MCP Server 暴露自身工具 McpServerEntrypoint · 152行 McpServerToolHandler · 129行 McpApprovalService · 审批 传输协议层 STDIO · 157行 SSE · 321行 HTTP Streamable · 307行 WebSocket · 242行 ServerStdio · 195行 mcp/ 30文件(main) · 5,219行 Client 20文件 + Server 4文件 + Transport 6文件 ◀ Client → 外部MCP服务器 外部客户端 → Server ▶ 4种核心传输实现 + 4种扩展类型定义 SSE_IDE · WS_IDE · ZHIKUN_AI_PROXY Client端数据流 Server端数据流 双向传输通道
MCP 协议双向通信架构 · Client/Server · 4种传输 协议版本: MCP 2024-11-05 规范 外部 MCP Servers（被 Client 连接） ZhikunCode · MCP Client 连接外部 MCP Server，调用远程工具 McpClientManager · 586行 Connection 512行 ToolAdapter 252行 Prompt 193行 Encrypt AES-GCM ZhikunCode · MCP Server 暴露本地工具给外部 MCP Client McpServerEntrypoint · 152行 McpServerToolHandler · 129行 McpApprovalService · 审批 ── 4种传输协议通道 ── ⬤ STDIO · 进程管道 ⬤ SSE · 服务端推送 ⬤ HTTP · Streamable ⬤ WebSocket · 全双工 连接生命周期管理 connect → initialize → ready → close 外部 MCP Clients（连接 Server） Client 数据流 Server 数据流 协议通道 生命周期流 MCP 2024-11-05 · McpClientManager 586行 · 4协议
09

工具系统

tool/ 105+文件 ~19,081行 · tool/impl/ — 43个工具
▶ 工具分类树
文件操作
ReadFile
WriteFile
EditFile
ListDir
SearchFiles
执行 & 终端
BashTool → Sec §5
TaskTool
NotebookTool
搜索 & 分析
GrepTool
GlobTool
CodeSearchTool
Agent & 协作
SubAgentTool
MemoryTool → §11
McpTool → §7
Web & Git
WebFetchTool
WebSearchTool
GitTool
共 43 个工具实现 · 每个工具继承 AbstractTool 基类 · 支持权限声明 + Schema 定义 + 流式结果
▸ 工具分类与执行管道全景
43 个工具 × 5 层执行管道 工具分类树 — 43个工具 / 5类 核心执行 (8) BashTool559行 PowerShellTool REPLTool TerminalCaptureTool 文件操作 (5) FileReadTool219行 FileEditTool308行 FileWriteTool GlobTool173行 GrepTool296行 代码分析 (4) GitTool176行 LspTool SnipTool SearchTool Web工具 (3) WebFetchTool385行 WebSearchTool WebBrowserTool 任务监控 (3) MonitorTool229行 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/ 105+文件 ~19,081行 核心执行×8 文件操作×5 代码分析×4 Web×3 监控×3 其他×18

插件生命周期 — 发现 · 隔离加载 · 注册 · 执行 · 卸载 — PluginManager 422行 · PluginLoader 330行 · PluginClassLoader 89行

① 发现 Discovery PluginSystemInit @EventListener L23 @Order(100) 最后加载 loadAllPlugins() · SPI: ServiceLoader · JAR: ~/.zhikun/ plugins/*.jar PluginLoader.java L58 PluginSystemInit.java L34 ② 加载 Load + Validate validateJar() · JAR≤50MB L36 · SPI文件校验 L259 PluginClassLoader · URLClassLoader隔离 · API包→委托父CL · 其他→Fail-Closed PluginClassLoader.java L40 isApiCompatible() L221 ③ 初始化 Initialize createContext() · Logger注入 · Config读取 L275 ext.onLoad(ctx) · VirtualThread执行 · 5s超时 L104 · LoadedPlugin创建 PluginLoader.java L99 PluginExtension.java L68 ④ 注册 Register Components Command→Registry L140 Tool→Registry L149 Hook→Registry L156 MCP→Manager L207 命令前缀: plugin:cmd 钩子超时: 5s L177 虚拟线程池执行 PluginManager.java registerPlugin() L137 ⑤ 运行时 Runtime Execution PreToolUse L338 PostToolUse L345 · 优先级排序执行 · Pattern正则匹配 · ReadLock并发安全 → Agent Loop集成 8种HookEvent executeHooks() L352 ReentrantRWLock L54 ⑥ 卸载 Unload + Cleanup 注销命令 L230 注销工具 L235 注销钩子 L239 注销MCP L242 · onUnload() L249 · 关闭ClassLoader L256 (仅LOCAL) unloadAllPlugins() L227 @PreDestroy L271 PluginClassLoader 隔离边界 · 89行 委托: plugin/tool/command/mcp 四个API包 隔离: 其他宿主类→ClassNotFoundException 放行: java.*/javax.*/slf4j 回退: Spring/Jackson/Jakarta 错误处理与降级路径 validateJar失败→跳过 | API版本不兼容→PluginError | onLoad超时(10s)→skip CLASS_LOAD_FAILED→PluginError | 钩子超时(5s)→allow() | 不阻止主应用 L37 Agent Loop 集成点 QueryEngine→executePreToolUseHooks()→工具执行→executePostToolUseHooks() 8种事件: PRE/POST_TOOL_USE · SESSION_START/END · TASK_COMPLETED ··· 热重载 reloadPlugins() L121 WriteLock → unloadAll → initializePlugins PluginManager 422行 · PluginLoader 330行 · PluginClassLoader 89行 · PluginExtension 79行 · LoadedPlugin 97行 · PluginSystemInitializer 40行 · HookHandler 101行
▸ 工具权限决策模型 — 7种模式 · 7步管线 · 3层Bash验证
7种权限模式 PermissionMode.java 37行 DEFAULT — 写操作弹窗确认 PLAN — 只读自动允许 ACCEPT_EDITS — 文件编辑自动 DONT_ASK — 不弹窗(写→拒绝) BYPASS — 全部自动允许 AUTO — LLM分类器判定(591行) BUBBLE — 子Agent权限冒泡 工具级权限需求(PermissionRequirement): NONE ALWAYS_ASK CONDITIONAL NONE: LspTool, VisualizationTool, WebFetchTool ALWAYS_ASK: FileEdit, Bash(写操作) 7步决策管线 PermissionPipeline.java 752行 1a. deny规则检查 → 命中则拒绝 1b. ask规则 → 命中则弹窗询问 1c. tool.checkPermissions() 1d-1f. 工具拒绝/交互/内容级ask 1g. 安全检查(.git/.env/.ssh) 2a. bypass模式 → 直接允许 2b. alwaysAllow规则 → 允许 3. passthrough → 进入模式分支 辅助组件: PermissionRuleRepository 271行 · 规则存储 PermissionRuleMatcher 253行 · 规则匹配 DenialTrackingService 158行 · 拒绝追踪 PermissionModeManager 155行 · 模式管理 Bash 3层验证 BashCommandClassifier.java 1,235行 Layer 1: READONLY_COMMANDS ~60个纯只读命令 ls, cat, grep, find, wc, head... → 无需参数检查，直接放行 Layer 2: READONLY_REGEXES 正则匹配只读命令模式 git log/status/diff, docker ps... → 模式匹配，参数级验证 Layer 3: COMMAND_ALLOWLIST Flag级别白名单验证 含6项安全加固规则 → 未命中 = 需要用户确认 危险模式强制 ASK rm -rf / · chmod 777 · mkfs 即使BYPASS模式也不可跳过 安全保护路径（不可绕过） .git .zhikun .env .ssh .gnupg .aws ← 即使 SKIP_ALL_PROMPTS 模式也强制检查 AutoModeClassifier 591行 · LLM驱动自动分类 | DangerousRuleStripper 167行 | PluginSettingsSource 120行 | PolicySettingsSource 144行 权限系统核心统计 PermissionPipeline 752行 BashCommandClassifier 1,235行 AutoModeClassifier 591行 7模式 · 7步管线 · 3层验证 关键设计: 安全检查不可被任何模式绕过 · 内容级危险模式强制ASK · BUBBLE模式支持子Agent权限冒泡 · DenialTracking防滥用
10

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

L0 SnipL1 MicroCompact 183行L2 AutoCompact 1,058行L3 IncrementalCollapse 174行L4 ReactiveCompact 148行 ContextCascade 348行 · 五级级联编排
5+1 层级联上下文压缩管道 — ContextCascade.java 348行 · 统一协调器 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 334 行 三层精度估算 ① 字符粗估 ② 类型调整 ③ 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行 ContextCascade348行 CollapseService283行 TokenCounter334行 MicroCompact183行 SnipService150行 辅助文件 BudgetTracker89行 CollapseLevel54行 IncrCollapseManager175行 共 12 个文件 · 2,873 行 200K tokens → 150K → 100K → 60K → 30K → 15K (413) CompactValidator 46行 压缩效果评估 降级决策输入 三级渐进折叠 A: 尾部10条完整保留 B: 10-30条截断500字符 C: 30+仅role+摘要骨架 PromptTooLongRecovery 148行 阶段1: Collapse Drain(激进压缩) 阶段2: 仅保留1轮 + 极度压缩 CompactMetrics 79行 · 压缩效率监控 IncrementalCollapseManager 174行 · 增量折叠

三区划分 — Protected / Compressible / Tail

CompactService · 三区划分 (planCompaction) — CompactService.java L322-L353 消息列表 messages[] (上下文窗口 = contextWindowSize) FROZEN 不可压缩区 compact_boundary 之前的消息 包含历史 COMPACT_SUMMARY 边界: 最后一个 SystemMessage type == COMPACT_SUMMARY L322-L334: compactBoundaryIndex = -1 遍历找最后 COMPACT_SUMMARY splitPoint = max(idx+1, 0) frozen = msgs[0..splitPoint] 策略: 完整保留 绝不压缩 · 含之前的摘要 COMPRESSIBLE 可压缩区 frozen 之后 ~ preserved 之前 对话历史的核心压缩目标 remaining[0..preserveStart] 3级降级策略 (L233-L303): ① LLM 摘要 (L246-L263) ② 关键消息选择 (L265-L288) ③ 尾部截断 1/3 (L293-L302) 策略: LLM → 选择 → 截断 摘要上限 SUMMARY_MAX_TOKENS = 4,096 tokens (L46) PRESERVED 保留区 最近 N 轮用户消息 确保上下文连贯性 findTurnBoundary() L837-L848 关键常量: PRESERVED_RECENT_TURNS = 3 (常规压缩, L49) REACTIVE_PRESERVED_TURNS = 1 (反应式 413 压缩, L52) 策略: 完整保留 从末尾回溯 N 个 UserMessage 压缩触发条件 AUTO_COMPACT_THRESHOLD = 0.85 (L40) tokens / contextWindow > 85% → 触发 COMPACT_TARGET_RATIO = 0.50 (L43) 压缩后目标 = 窗口 50% MIN_MESSAGES_FOR_COMPACT = 5 (L58) AUTOCOMPACT_BUFFER_TOKENS = 13,000 (L55) 压缩执行过程 N 条消息 LLM 摘要 1 条 Summary frozen[] + COMPACT_SUMMARY + preserved[] → buildCompactResultWithSummary() L437-L446 → 文件重注入 reInjectFilesAfterCompact() L861 Token 成本对比 (示例: 200K 上下文窗口) 压缩前 frozen 20K compressible 95K tail 40K ≈ 170K (85% 窗口) 压缩后 frozen 20K 4K tail 40K ≈ 100K (50% 目标) 节省 ~70K tokens ↓ 41% CompactionPlan record (L123-L129) frozenMessages → 不可压缩 compactionMessages → 待压缩 preservedMessages → 已保留 compactionTokens · targetSummaryTokens
11

辅助系统

▶ 记忆系统 memdir/ 5文件 1,089行
MemdirService598行 — 核心记忆目录管理
MemorySearchEngine197行 — BM25检索(K1=1.2, B=0.75)
MemoryRerankService128行 — LLM精排(3000ms超时降级)
MemoryTool117行 — 工具接口
▶ Skill 系统 skill/ 9文件 1,437行
SkillRegistry412行 — 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行

记忆检索-精排流水线 — Query → BM25 召回 → LLM Rerank → Context 注入

存储层 · Storage MemdirService 598行 · 核心记忆目录管理 Markdown Files 持久化 · .md 格式存储 Category Dirs 按 category 目录组织 索引构建 IDF 预计算 · 标题2x加权 检索层 · BM25 Recall User Query searchMemories(q) MemorySearchEngine 197行 · BM25 · K1=1.2 B=0.75 N-gram分词 · CJK · 停用词过滤 Top-K 召回 BM25 候选集 · 评分排序 索引加载 BM25 参数 K1 = 1.2 · B = 0.75 标题权重 2x · IDF 预计算 精排层 · LLM Rerank 候选集 MemoryRerankService 128行 · LLM精排 · 3000ms超时降级 SideQueryService · 512 maxTokens 降级策略 · Fallback Rerank 超时 3000ms → 直接使用 BM25 结果 超时 Context 注入 → SystemPrompt buildMemoryPrompt() · readMemoriesForPrompt → 精排结果注入 LLM 上下文 Pipeline 耗时 BM25: <50ms Rerank: ≤3000ms relevanceScore 排序 · 截断 · 注入

插件系统 SPI 发现与沙箱隔离架构 — plugin/ 14文件 + hook/ 5文件 · ServiceLoader SPI · URLClassLoader 隔离

SPI 服务发现流程 Java ServiceLoader · PluginLoader 330行 内置插件 (Classpath) ServiceLoader.load() 本地JAR插件 ~/.zhikun/plugins/*.jar 市场插件 (Future) Remote Registry PluginManager · 422行 JAR限制: 50MB API版本兼容检查 ReentrantReadWriteLock 热重载线程安全 沙箱隔离架构 PluginClassLoader 89行 · URLClassLoader · Fail-Closed 安全模式 委托父加载器 ✓ com.aicodeassistant.plugin com.aicodeassistant.tool com.aicodeassistant.command com.aicodeassistant.mcp → 隔离不委托 ✗ 其他宿主类 → 不可访问 Fail-Closed 安全默认 插件只能访问公开API → JDK标准库 ✓ java.* / javax.* 委托BootstrapClassLoader 标准库始终安全可用 Hook 拦截链 HookService 337行 · HookRegistry 166行 · 虚拟线程池执行 HookRegistry PreExec Hook PostExec Hook Error Hook Stop Hook HttpHookExecutor 177行 · SSRF防护 SsrfGuard 139行 · URL验证 HookHandler 101行 · 回调处理 插件生命周期 ① 安装 Install ② 加载 Load ③ 运行 Active ④ 卸载 Unload ⑤ 热重载 Reload 加载组件: · 命令 (Command) · 工具 (Tool) · 钩子 (Hook) · MCP Server · LSP Provider 关键类: PluginExtension 79行 LoadedPlugin 97行 PluginManifest 47行 plugin/ 14文件 hook/ 5文件 PluginManager 422行 PluginClassLoader 89行 HookService 337行 SPI发现: ServiceLoader(内置) + JAR扫描(本地) + 市场(规划中) 隔离: URLClassLoader · 委托白名单 · Fail-Closed 安全: SsrfGuard防护 · JAR大小限制50MB · API版本兼容校验 生命周期: 安装→加载→运行→卸载→热重载

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

高级任务 用户指令 Slash Command Skill 核心引擎 SkillRegistry SkillRegistry.java 412行 6级加载源 · Skill发现 SkillDefinition.java 94行 元数据解析 FrontmatterParser 240行 FrontmatterData 74行 YAML Frontmatter SkillExecutor SkillExecutor.java 176行 串行/并行调度 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/ 9文件 · 1,437行 | SkillRegistry 412行 · FrontmatterParser 240行 · SkillTool 125行 · SkillExecutor 176行
12

多Agent协调系统

coordinator/ 19文件 4,138行 + agent/ 10文件 2,409行 = 29个类
Team模式Swarm模式SubAgent模式 coordinator/ 19文件 · SubAgentExecutor 1,032行 · SwarmService 484行
▸ 多Agent协作系统 — Team / Swarm / SubAgent 三模式全景
Leader Agent CoordinatorWorkflowEngine · 446行 Team Mode 多代理并行协作 · 邮箱通信 TeamManager 137行 · 团队成员管理 TeamMailbox 109行 · ConcurrentLinkedQueue Worker Agent A Worker Agent B Worker Agent C SharedTaskList · 174行 ResultAggregator · 101行 Worker 间通过 Mailbox 异步通信 Leader 通过 TaskList 分配任务 结果汇聚至 ResultAggregator Swarm Mode Virtual Thread 并行 · 四阶段流水线 SwarmService 484行 · Java 21 Virtual Thread · Caffeine TTL 4h 1. Research → 2. Synthesis 3. Implement → 4. Verify SwarmWorkerRunner · 329行 WorkerStateTracker · 137行 SwarmState · 203行 · 状态管理 每阶段可并行多个 Worker 阶段间同步屏障（Barrier） SwarmController 299行 · 对外API SubAgent Mode 独立子代理 · 权限冒泡机制 SubAgentExecutor 1,032行 · 子代理执行与隔离 LeaderPermissionBridge 210行 · 权限请求冒泡 SubAgent → Bridge → Leader 权限请求冒泡方向 → InProcessBackend · 127行 WorkflowPhase · 234行 子Agent独立Agent Loop 权限请求冒泡至父Agent BUBBLE模式隔离执行 共享基础设施 CoordinatorPromptBuilder 357行 CoordinatorEventBus 151行 CoordinatorService 259行 CoordinatorWorkflow 246行 SwarmConfig 92行 coordinator/ 19文件 + SubAgentExecutor 1,032行 Swarm: Virtual Thread并发 Team: 邮箱通信 权限冒泡: BUBBLE模式

三模式协调对比 — Team · Swarm · SubAgent

▸ CoordinatorWorkflowEngine 统一调度 — 三模式对比与转换
CoordinatorWorkflowEngine — 统一调度入口 446行 · 四阶段检测 · 不委派理解验证 · 阶段跳跃警告 · WebSocket推送 固定角色分工 复杂流水线 独立子任务 Team 模式 多代理并行 · Leader分配 · 邮箱通信 TeamManager · 137行 TeamMailbox · ConcurrentLinkedQueue SharedTaskList · 174行 · FIFO认领 InProcessBackend · Virtual Thread并行 通信机制 Leader Mailbox Workers 适用场景 前后端拆分 · 固定角色协作 · 测试+开发 并行度Worker数(1-20) 同步异步邮箱 + TaskList FIFO Swarm 模式 Virtual Thread并行 · 四阶段流水线 · 阶段同步 SwarmService · 484行 SwarmWorkerRunner · Virtual Thread SwarmState · Caffeine TTL 4h LeaderPermissionBridge · 210行 四阶段流水线 Research → Synthesis → Implement → Verify 适用场景 复杂研究型任务 · 需要阶段性交付 · 多Worker协同 并行度阶段内多Worker并行 同步阶段间Barrier同步屏障 SubAgent 模式 独立子代理 · 权限冒泡 · BUBBLE模式 SubAgentExecutor · 1,032行 AgentConcurrencyController · Slot WorktreeManager · Git隔离 PermissionModeManager · BUBBLE 权限冒泡机制 SubAgent → Bridge → Parent 适用场景 简单委派任务 · 隔离执行 · Fork复用KV缓存 并行度独立Agent Loop(串行) 同步权限冒泡至父 · 超时5min 模式选择决策 Team: 需要固定角色分工且Worker间需通信 Swarm: 复杂任务需四阶段分解且多Worker并行 SubAgent: 简单独立子任务委派
13

React 前端架构

182文件 26,936行
▶ 组件层 104文件 13,502行 24子目录
visualization ×14 message ×19 status ×9 layout ×6 input ×6 common ×5 settings ×4 dialog ×4 theme ×3 permission ×2 git ×2 browser ×3 apos ×2 command ×2 compact ×1 cost ×1 dashboard ×1 diff ×1 doctor ×1 help ×1 memory ×1 plan ×1 plugins ×1
▶ 15个可视化组件
CodeComplexityTreemap663行 CodePathTracer621行 ChangeImpactGraph570行 APIContractViewer527行 CodeDiagramGenerator407行 AgentDAGChart531行 GitTimeline369行 APISequenceDiagram255行 SchemaViewer235行 MermaidBlock204行 BlameView186行 AgentDAGNode103行 ToolProgressBar99行 MiniLogViewer67行
▶ 状态管理 — 30 个 Zustand Store 约2,846~3,278行(仅业务Store)
coordinatorStoremcpStoreconfigStoreswarmStoremessageStoreplanStoretaskStoresessionStoretoolStorepermissionStore + 19 more stores
▸ 30个 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广播中间件 — 事件驱动状态同步 连接所有30个Store · 发布/订阅模式 业务×7 系统×5 UI×4 分析×4 元数据×2 broadcast广播 configStore依赖 约2,846~3,278行

▸ Store 依赖关系 — dispatch.ts 558行 · 消息分发中枢

dispatch.ts 558行 · 40+消息类型 · 序列号校验 按 type 字段分发到 16 个 Zustand Store UI Store appUiStore 1.9KB dialogStore 1.3KB notificationStore 1.4KB inboxStore 1.2KB featureFlagStore 2.8KB Data Store messageStore 6.8KB ★ sessionStore 2.1KB ★ activityStore 9.4KB costStore 1.1KB permissionStore 1.6KB Business Store taskStore 2.5KB planStore 3.4KB coordinatorStore 8.5KB swarmStore 10.1KB insightStore 7.1KB anomalyStore 3.9KB mcpStore 8.1KB mcpCapabilityStore 5.5KB bridgeStore 2.2KB System Store configStore 9.0KB ★ changeImpactStore 7.5KB codeInsightStore 5.8KB codePathStore 4.4KB complexityStore 4.7KB diagramStore 2.9KB apiContractStore 5.2KB fileTreeStore 2.2KB commandStore 0.7KB toolStore 2.0KB getState() broadcastMiddleware 跨Store协调函数 (dispatch.ts内) 跨Store协调 (源码验证): handlePermissionRequest → permissionStore + sessionStore handleMessageComplete → messageStore + sessionStore handleSessionRestore → 5个Store全量同步 (L497-557) worker_progress → swarmStore + anomalyStore (L302-330) broadcastMiddleware: 跨Tab状态同步 (BroadcastChannel API) 仅 configStore 使用 · 非跨Store依赖 · 防止死循环 UI Store Data Store Business Store System Store dispatch分发 直接依赖(源码) ★=核心Store(被多消息引用) 源码路径: frontend/src/store/

▸ 可视化组件矩阵 — 代码分析 · API契约 · Agent执行

15 Visualization Components · 5,137 LOC · 4 Libraries frontend/src/components/visualization/{backend,shared}/ + message/VisualizationMessage.tsx 代码分析 4 components · 2,261行 CodeComplexityTreemap663行 CodePathTracer621行 ChangeImpactGraph570行 CodeDiagramGenerator407行 Recharts @xyflow×2 Mermaid Monaco Store: complexityStore · codePathStore · changeImpactStore · diagramStore · configStore API契约 3 components · 1,017行 APIContractViewer527行 APISequenceDiagram255行 SchemaViewer235行 Mermaid Pure React Store: apiContractStore · messageStore Agent执行 2个 · 634行 AgentDAGChart531行 AgentDAGNode103行 @xyflow×2 代码洞察 2个 · 555行 GitTimeline369行 BlameView186行 Pure React 共享基础设施 3个 · 370行 MermaidBlock204行 ToolProgressBar99行 MiniLogViewer67行 Mermaid Pure React Store: configStore VisualizationMessage.tsx · 300行 · 入口路由 — 按 viewType 分发到上述 14 个可视化组件 Store: appUiStore + changeImpactStore + codePathStore + complexityStore + apiContractStore (5个Store直连) Zustand Store 数据绑定 9个业务Store · 选择器模式订阅 complexityStore codePathStore changeImpactStore diagramStore apiContractStore messageStore coordinatorStore swarmStore codeInsightStore configStore appUiStore Python分析服务 API 6个REST端点 · Java后端代理 /api/code-quality/complexity /api/code-path/endpoints | /trace /api/analysis/change-impact /api/code-diagrams/generate /api/analysis/openapi/* /api/git/* 代码分析×4 API契约×3 Agent×2 洞察×2 共享×3 入口×1 @xyflow ×4 Recharts Mermaid ×3 Monaco Pure React ×6 Total: 5,137行 Store颜色=所属分类 · 圆点颜色=API对应分类 · 虚线动画=数据流方向 源码路径: frontend/src/components/visualization/ 数据流闭环: 组件 → Zustand Store → fetch() → Java 代理 → Python 分析服务 ▸ CodeComplexityTreemap → complexityStore → /api/code-quality/complexity ▸ CodePathTracer → codePathStore → /api/code-path/endpoints | /trace ▸ ChangeImpactGraph → changeImpactStore → /api/analysis/change-impact ▸ CodeDiagramGenerator → diagramStore → /api/code-diagrams/generate ▸ APIContractViewer → apiContractStore → /api/analysis/openapi/* ▸ GitTimeline → codeInsightStore → /api/git/*

▸ 前端路由架构 — 页面组织与导航结构

SPA 单页应用 · 无 URL 路由 · Tab-based 导航 · Feature Flag 条件渲染 main.tsx → App.tsx → AppLayout → Sidebar(12 Tabs) + Main Content · 无 React Router · 无权限守卫 main.tsx → ThemeProvider → App AppLayout 三栏布局 · 响应式 · 146行 Header Sidebar (Desktop) Drawer (Mobile) Main Content StatusBar MobileStatusBar (Flag) ?sidebar=detached&tab=xxx DialogManager SkillDetailModal Sidebar Tab 导航 12 个视图 Tab · 580行 · Tab切换即"路由" · 无 URL 变更 sessions 会话 tasks 任务 files 文件树 sequence 序列图 dag DAG git Git complexity 复杂度 impact 影响分析 api-docs API文档 diagram 图表生成 code-path 代码路径 apos Activity ⚑ 导航机制: useState<TabType> 切换 · Auto-Routing: appUiStore.pendingVisualizationTab 跨组件跳转 组件渲染: SessionList · TaskPanel · FileTreePanel · APISequenceDiagram · AgentDAGChart · GitTimeline · CodeComplexityTreemap ... Feature Flag 控制 Feature Flag 条件渲染 featureFlagStore · 运行时开关 APOS_ACTIVITY_STREAM APOS_MOBILE_STATUS 控制: Activity Tab 显示/隐藏 · MobileStatusBar 渲染 决策: 无传统路由权限守卫 · 通过 Flag 实现功能灰度发布 URL Query Param 导航 唯一的 URL 级"路由"机制 ?sidebar=detached &tab={TabType} 功能: 新窗口打开 Sidebar 全屏模式 解析: useMemo + URLSearchParams · AppLayout.tsx L30-L38
▶ API 通信层
dispatch.ts 557行

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

stompClient.ts 363行

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

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

Python 分析服务架构

29文件 7,151行
▶ 分析引擎 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.py799 行
complexity_analyzer.py515 行
tree_sitter_service.py237 行
browser_models.py119 行 — Pydantic 浏览器数据模型
▶ API 路由 routers/ 1,526行
/api/analysis434行 /api/browser315行 /api/files276行 /api/code-intel213行 /api/git125行 /api/v1/tokens97行 /api/code-quality95行 /api/tokenizer73行
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 分析报告 → 前端可视化组件 (15个) → 浏览器渲染展示 29文件 7,151行 8个API端点 7个分析器 7个服务 15个前端组件 FastAPI

代码分析能力域 — 分析器 · 服务 · API 端点

Java Backend :8080 httpx.AsyncClient · HTTP REST · JSON analysis.py:17 JAVA_BACKEND_URL · /v3/api-docs 代理 FastAPI :8000 · uvicorn ASGI main.py 路由层 — 8 个模块 · 30+ 端点 routers/*.py · capabilities.py 能力域动态注册 · 四层依赖探测 /api/code-intel POST parse·symbols·deps·map code_intel.py:133-213 /api/analysis diagram·impact·path·openapi analysis.py:79-435 /api/code-quality POST complexity treemap code_quality.py:51-96 /api/files tree·encoding·watch SSE file_processing.py:94-277 /api/git diff·log·blame git_enhanced.py:89-126 /api/browser 15 端点 Playwright browser.py:53-279 /api/v1/tokens estimate·single token_estimator.py:45-97 /api/tokenizer POST count tokenizer.py:48-74 分析器层 — 5 个核心分析器 + 支撑服务 analyzers/ 2,872行 · libcst + networkx + tree-sitter 多语言解析 CallGraphBuilder 调用图构建 · networkx.DiGraph Python(libcst high) Java(ts medium) TS(ts low) IN: project_root → OUT: nx.DiGraph(nodes+edges) call_graph_builder.py · 583行 ChangeImpactAnalyzer 变更影响 BFS 传播 · 60s 超时保护 impact_level: direct → indirect → potential IN: file_path+changed_lines → OUT: 影响链路图 change_impact_analyzer.py · 417行 (F33) CodePathTracer API 端点扫描 + 正向 BFS 调用路径追踪 Java Spring Boot · Python FastAPI · TS Express IN: entry_file+function → OUT: 层级调用链 code_path_tracer.py · 623行 (F40) SequenceDiagramGenerator Mermaid 时序图 · Controller→Service→Repo 参与者角色映射 · 循环调用检测与截断 IN: API路径/方法签名 → OUT: sequenceDiagram sequence_diagram_generator.py · 528行 (F35) FlowChartGenerator Mermaid 流程图 · if/loop/try 控制流 tree-sitter AST 解析 · 嵌套深度限制 3 层 IN: target方法体 → OUT: flowchart TD flow_chart_generator.py · 658行 (F35) 支撑服务层 · services/ TreeSitterService 50+ 语言 AST 统一接口 238行 ComplexityAnalyzer radon+tree-sitter 启发式 516行 FileDetector · GitEnhancedService · BrowserService services/ 总计 1,725行 (含 browser_service 799行) ↓ 被 2/3/4 依赖 核心解析库 tree-sitter ≥0.21.0 AST引擎 libcst ≥1.1.0 CST networkx ≥3.2 图算法 radon ≥6.0.1 CC tiktoken cl100k token playwright ≥1.40 浏览器 chardet 编码检测 httpx async HTTP pygount ≥1.8 统计 17 种语言 · tree-sitter 统一 AST Python · Java · TypeScript · TSX · JavaScript · Go · Rust · Ruby · C++ · C C# · Kotlin · Swift · PHP · Scala · Lua · R tree_sitter_service.py:66 LANG_MAP 前端可视化组件映射 CodeComplexityTreemap ← /api/code-quality/complexity ChangeImpactPanel ← /api/analysis/change-impact 6 能力域 CODE_INTEL · FILE_PROCESSING · CODE_QUALITY · ANALYSIS · GIT_ENHANCED · BROWSER_AUTOMATION capabilities.py:19 CapabilityDomain · 四层检测: 包导入 + 版本校验 + 系统二进制 + 冒烟测试 · 缺失能力优雅降级 8 路由模块 · 30+ 端点 5 分析器 · 2,872行 10 核心库 · 17 种语言
15

部署架构 — 单容器多进程

Single Container · Java主进程托管Python子进程 · 前端静态资源集成 · 日志按日滚动
Single Container — zhikuncode:latest eclipse-temurin:21-jre-jammy · EXPOSE 8080 · HEALTHCHECK /actuator/health Java 主进程 (PID 1) Spring Boot 3.4.13 · :8080 Agent Engine Permission MCP Protocol Tool System PythonProcessManager · 子进程管理 Python 子进程 FastAPI + uvicorn · subprocess Code Analysis Browser Auto Tree-sitter Tokenizer 6个能力域 · 6,661行 · venv隔离 前端静态资源 /app/static/ · Spring Boot 托管 React 18.3 Zustand 37 Monaco Editor xterm.js 104组件 · Vite 5.4 构建 · dist/ spawn static 共享基础设施 Log Rolling app-YYYY-MM-DD-N.log.gz start.sh / stop.sh 一键启停脚本 .env 配置 .env + .env.example Docker Entrypoint docker-entrypoint.sh · 多阶段构建
Docker docker-compose.yml · 单容器多进程架构
Dockerfile + docker-entrypoint.sh → 多阶段构建
Scripts start.sh / stop.sh · 一键启停
Java + Python + 前端三进程统一管理
Logging 日志滚动 · app-YYYY-MM-DD-N.log.gz
按日期+序号自动滚动，gzip 压缩归档
Config 环境配置 · .env + .env.example
集中管理数据库、API Key、端口等环境变量
ZhikunCode Architecture Reference · 109,548 Lines · 837 Files · Generated for CTO Review