ZhikunCode
系统工程架构大图
134,826行 / 863个Git跟踪产品文件 · 40+内置工具 · 14技能 · 5类Agent · 5种权限模式 · ea0170c / 2026-08-09
FRONTEND LAYER · React 33,642行 · 209文件
117 TSX文件（109非测试） · 36 Store文件 · 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门控
状态管理 (36 Store 文件)
messageStore
消息历史/流式
toolStore
工具定义/执行状态
mcpCapabilityStore
MCP能力动态注册
commandStore
Slash命令
coordinatorStore
Swarm协调器
fileTreeStore
文件树状态
activityStore
用户活动追踪
持久化: LocalStorage
跨标签同步: BroadcastChannel
TypeScript强类型
异步中间件支持
实时流式渲染
content_block_delta → 增量文本流
Markdown实时解析+代码高亮
Thinking块可折叠展示
可视化组件
代码路径追踪 · 架构图渲染
数据流可视化 · 多模型切换UI
WebSocket双向流
BACKEND CORE · Java 93,118行 · 622文件 · Spring Boot 3 · Java 21 Virtual Threads
查询引擎（QueryEngine）
QueryEngine.java · 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(冻结输入)
→
→
→
参考矩阵 · 5 种权限模式 / ONCE一次性决策 + 3种持久Grant范围:
DEFAULT
PLAN
ACCEPT_EDITS
DONT_ASK
AUTO_APPROVE
Scope: ONCE · RUN · SESSION · WORKSPACE
HIGH/复杂 Shell/未知 MCP: ONCE | Guarded Bash: RUN/SESSION | 受约束文件能力: SESSION/WORKSPACE
用户批准和 Grant 均不能覆盖 system invariant；无害环境变化不得触发最终误拒绝
LLM 多模型路由
LlmProviderRegistry · ModelRegistry · 模型目录动态扩展
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（默认）| qwen3.8-max（Token Plan可选）
模型目录动态扩展 | 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)
降级链
预定义降级链: qwen3.7-max / qwen3.7-plus / deepseek-v4-flash | Agent与全局默认: qwen3.7-max
工具执行系统
40+内置工具 + 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）
14 内置技能 · 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
publish-oss
WatchService热重载 · 500ms防抖 · SkillDefinition(name, desc, ...)
多Agent协作（Multi-Agent）
5类Agent · general-purpose/explore/verification/plan/guide
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 · STOMP会话与消息控制
权限交互持久流:
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层合成
基础指令层
角色定义 + 工具描述 (40+工具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
单工具串行 · 避免写冲突 · 有状态操作保护
完整14技能清单
Slash Command · 技能描述
/commit 智能提交
/review 代码审查
/fix 智能修复
/test 智能测试
/pr PR助手
/debug 调试诊断
/verify 代码验证
/stuck 脱困诊断
/remember 会话记忆
/publish-oss 产物发布
/software-architecture
/csv-data-summarizer
/prompt-engineering
/test-driven-development
6层优先级加载 · WatchService热重载 · Markdown模板 · 参数化指令
HTTP REST · Playwright
PYTHON SERVICE + CLI · 8,066行 · 32文件 · 7能力域
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
启动流程:
FastAPI 启动 → 4层能力探测 → 动态注册 Router
能力缺失 → 跳过对应Router (graceful degradation)
接口契约:
Java后端 → HTTP REST → Python FastAPI
WebBrowserTool → /browser/* 端点
CodeIntelTool → /code-intel/* 端点
VisualizationTool → /visualization/* 端点
存储:
workspace/screenshots/ 截图存储
Temp files 临时分析产物 · 自动GC
LATEST RUNTIME CONTROL · ea0170c · 2026-08-09
Project · Steering · Verified Artifact · Observability / Recovery
PROJECT / SESSION
CORE
V020 Project Trust Boundary
• 本机 picker / 远程 allowed roots
• canonical / real path 归一化
• Session 固定默认相对路径根
• 任意 cwd / 别名 / 重绑定拒绝
Project 是可撤销信任范围
不是通用 OS 文件沙箱
普通文件读写按模式放行 / 越界复检
RUN STEERING / CAS
CORE
Session → In-memory Active Run
• requestId/text → queued/applied/rejected
• steering queue / turn boundary（内存）
• AbortContext / 进程梯度终止
• RunControlService CAS 单一终态
COMPLETED / FAILED / CANCELLED / INTERRUPTED
迟到回调不能覆盖权威状态
CheckpointService 与输入队列职责分离
VERIFIED ARTIFACT
OPTIONAL
Declare → Seal / Hash → Verify
• verified/partial manifest 中的验证条目
• PublishArtifact 显式高风险授权
• OSS 私有上传 / 远端校验 / 公开
• 权威下载链接结构化返回
同一持久化根 Session 的根 Run
及 parent_run_id 授权后代 Run
默认关闭 · 永不自动上传
OBSERVE / RECOVER
DYNAMIC
BestEffortObservabilityRecorder
• MDC: sid/rid/prid/agent/turn/tool/llm
• 结构化结果 → 工具卡片 / 外部资源
• Recorder 有界补充事件故障隔离
• 完整 Session / Run event seq 恢复
活跃工具状态 / 待处理持久交互重放
补充观测失败不破坏主执行链
WebSocket reconnect · idempotent
5 种权限模式 · ONCE一次性决策 + RUN/SESSION/WORKSPACE持久Grant · 硬拒绝 / Hook / SSRF / 沙箱不变
Java 93,118行 │ React 33,642行 │ Python服务与CLI 8,066行 │ 总计 134,826行
622 Java文件 │ 117 TSX文件（109非测试） │ 40+内置工具 │ 14技能 │ 5类Agent │ 5权限模式 │ 36 Store文件
ZhikunCode System Architecture Blueprint · ea0170c · 2026-08-09 · 产品源码统计口径