ZhikunCode 系统架构

Enterprise-Grade AI-Powered Web IDE — Architecture Reference
Java 68.8% React 25.0% Python + CLI 6.0% 134,826 Product Lines 863 Git-Tracked Files · ea0170c
01

项目总览面板

ZhikunCode · Web IDE · 浏览器 + 后端服务 + 分析服务
Java 后端主源码
93,118 行 / 622 文件
Java 测试代码
40,974 行 / 208 文件
React 前端
33,642 行 / 209 文件
Python 服务与 CLI
8,066 行 / 32 文件
技术概览
项目名称ZhikunCode
产品形态AI-Powered Web IDE
产品源代码134,826 行 / 863 个 Git 跟踪文件 · ea0170c / 2026-08-09（不统计本地忽略文件）
测试规模Java + Python 43,176 行 / 226 文件；前端 E2E 24 specs
后端框架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 主源码
93,118 Java 测试
40,974 React 前端
33,642 Python + CLI
8,066
02

三端分离架构总览

核心通信链路
React 前端 33,642 行 · 209 文件 · 36 Store 文件 · 117 TSX 文件（109 非测试） Project 选择 · Run steering · 结构化工具卡片 · STOMP 重连 Java 后端 93,118 行 · 622 文件 · Spring Boot 3.4 Port 8080 · Agent Loop · Permission · MCP · Tools Python 分析服务 8,066 行 · 32 文件 · FastAPI + CLI Port 8000 · 7 能力域 · tree-sitter LLM API MCP Servers Docker 沙箱 文件系统 REST API + WebSocket/STOMP Vite Proxy → :8000
▸ 三端分离架构全景插画
React 前端 33,642 行 · 209 文件 36 Store 117 TSX文件 15 可视化 dispatch 557 363 dispatch.ts · stompClient.ts REST + WS/STOMP HTTP Proxy Java 后端 93,118 行 · 622 文件 · Spring Boot 3.4 Agent Engine 9,003行 Permission 统一授权 + 最终复检 Tool System 40+ 内置 · 动态扩展 MCP Protocol 4传输 5,219行(main) LLM Provider 26文件 3,456行 Multi-Agent 5 类 Agent Bash Security 6层AST 5,620行 Context Mgmt 6层压缩 :8080 Python 分析服务 8,066 行 · 32 文件 · 服务 + CLI Analyzers Services 7 能力域 tree-sitter :8000 LLM APIs MCP Servers Docker 沙箱 文件系统 Java 93,118行 React 33,642行 Python 8,066行 通信链路 外部服务
▶ 5条通信链路详情
#链路协议关键文件
1前端 → Java 后端REST API + WebSocket/STOMPdispatch.ts + stompClient.ts
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 → STOMP/WS → QueryEngine 8步循环 → 流式工具执行 → Zustand 实时更新

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

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

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

User (Browser) REACT FRONTEND 117 TSX文件 36 Stores dispatch.ts stompClient.ts 14 Viz JAVA BACKEND (93,118 lines / 622 files) Agent Loop engine/ · Agent Loop与上下文编排 Permission Analyzer · Grant · Gateway Bash Security 6-layer AST 5,620行 Tool System 40+内置工具 · MCP/插件动态扩展 LLM Provider 26文件 3,456行 MCP Protocol 30文件(main) 5,219行 Multi-Agent 5类 Agent · 受控协作 Context Mgmt 6层压缩 Memory 1,089行 BM25+LLM Skill 1,437行 6级加载 Security 1,248行 黑名单+审计 Sandbox Docker隔离 316行 PYTHON SERVICE + CLI (8,066 lines / 32 files) Analyzers (2,872行) 7 能力域 · 条件 Router Services · 浏览器、Git、文件与复杂度分析 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/ · QueryEngine.java · Agent Loop 与 Run 编排
1
压缩级联 ContextCascade
AutoCompact 状态回写 · 上下文窗口管理 · 触发条件: token数 > 阈值
2
创建流式执行会话 StreamingToolExecutor.newSession
初始化工具执行上下文 · 并行通道就绪
3
API 调用 + 模型降级 LlmProvider.streamChat
流式工具执行(立即启动) · 413二阶段恢复 · 模型降级链
4
收集 API 响应 StreamCollector.buildAssistantMessage
流式chunk聚合 · 工具调用提取 · thinking块处理
5
消费工具结果 并行执行，异步等待
StreamingToolExecutor 调度 → 每个调用进入统一授权/Gateway → 结果按序收集
6
继续/终止判定
end_turn 信号检测 · max_tokens 恢复机制 · StopHook 自定义拦截
7
工具摘要注入 ToolResultSummarizer
长结果截断摘要 · LLM辅助压缩 · 上下文预算控制
8
状态更新 → 回到 Step 1 LOOP
消息历史追加 · 统计更新 · 压缩指标评估 · 循环继续
▸ Agent Loop 8步循环引擎
QueryEngine.java — 8步循环 · 流式工具执行 1 压缩级联 ContextCascade AutoCompact·上下文窗口 2 创建流式会话 StreamingToolExecutor 初始化工具执行上下文 3 API调用+降级 LlmProvider.streamChat 流式执行·413恢复·降级链 ModelTierService · 155行 N级降级链 · 冷却管理 · 健康探测 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调用 执行/循环 判定节点 循环路径 分支决策
▶ 引擎关键特性
流式工具执行

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

413二阶段恢复

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

事务边界

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

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

▸ Step 5.5 Self-Correction Detection · SelfCorrectionLoop.java 395行 · MAX_ATTEMPTS_DEFAULT=3 / MAX_ATTEMPTS_SWE_BENCH=7（场景动态选择）
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（DEFAULT=3 / SWE_BENCH=7）→ 放弃 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() engine/correction/ · 错误检测与修复决策

Run 控制与运行中 Steering

▶ RunExecutionRegistry + RunControlService 运行中输入CAS 终态
1
注册活跃执行
QueryEngine 启动 Run 时向 RunExecutionRegistry 注册 runId、sessionId 与 AbortContext；Registry 只维护当前进程内的活跃映射和取消上下文。
2
运行中输入与 Steering 回执
前端向 /app/run-input 发送 requestId/text，服务端按已认证 Session 查找活跃 Run 并进入内存队列；客户端事件统一为 queued / applied / rejected。
3
取消、进程终止与 checkpoint 分工
AbortContext 提供协作式取消，ManagedProcessRunner 负责超时后的梯度终止；CheckpointService 独立保存子 Agent checkpoint，不属于 Registry 输入队列。
4
CAS 单一终态
RunControlService 通过 compare-and-set 只接受一个 COMPLETED / FAILED / CANCELLED / INTERRUPTED 终态，迟到回调不能覆盖权威结果。
WebSocket / RESTsteer · cancel · resumeSession-bound requestId/text RunExecutionRegistryactive run · steering queuein-memory · cancellation QueryEngineturn boundary 消费输入applied/rejected Run 事件 RunControlServiceCAS terminal state完成 / 失败 / 取消 / 中断 重连恢复完整 Session 消息、最新 Run snapshot/event sequence、活跃工具状态与待处理持久交互
04

统一权限分析、授权与执行准入

authorization/ · V015 Durable Interaction · V019 Permission Grant · V020 Project
▶ STAGE 1: 统一授权与执行主链 11 个职责边界
1
Schema / Tool / PreToolUse
输入补全后执行 Hook；Hook 改写输入时重新执行完整 Schema 与 Tool 校验
2
冻结规范输入
FrozenToolInput · canonical JSON · inputHash
3
Subject + Operation Analyzer
从 Run ancestry 解析 root identity，再按显式 toolName → analyzerId 选择 Analyzer
4
OperationDescriptor + invariant
effect/resource/environment/network/risk；拒绝非法资源字符与敏感继承环境
5
只收紧 Security Hook
只读取冻结输入和已生成事实；可以拒绝，但不能修改输入或扩大授权
6
SAFE_INTERNAL / Grant
精确 SAFE_INTERNAL 由内建策略放行，否则匹配 scope、profile、Analyzer 版本与约束
7
权限模式裁决
DEFAULT / PLAN / ACCEPT_EDITS / DONT_ASK / AUTO_APPROVE；自动批准只替代人工确认，不绕过硬拒绝、安全 Hook、SSRF 防护或部署沙箱。
8
Durable Interaction v3
optionId / descriptorHash / scopeOptions / expectedVersion / deliveryGeneration；ACK 只确认投递，用户决定由数据库 CAS 产生唯一终态
9
声明输出规划
planOutputs() 在 Gateway 前生成无副作用的产物声明；工具并发/work lease 由上游 StreamingToolExecutor 管理
10
最终动态与 Grant 复检
仅在路径、符号链接、风险或授权约束发生安全退化，或 Grant 撤销/过期时拒绝；无害环境变化不得误拒绝
11
ToolExecutionGateway
短事务提交 execution_admitted/tool_started 与声明输出，事务外调用冻结输入对应的 Tool.call()
▶ Grant 能力与继承矩阵 策略参考
A
高风险与复杂 Shell
只允许 ONCE，不创建可复用 Grant
B
Guarded exact Bash
只支持 RUN / SESSION，不支持 WORKSPACE
C
受约束文件能力
安全读与 typed edit 可按约束支持 WORKSPACE
D
未知 MCP / 动态 Tool
GenericMcpAnalyzer · exact ONCE
E
子代理受控继承
root session/root run + DIRECT_ONLY/ROOT_AND_DESCENDANTS
▶ 权限模式与授权范围 5 模式 · ONCE决策 + 3持久Grant范围
✓
授权结果与作用域
权限模式：DEFAULT PLAN ACCEPT_EDITS DONT_ASK AUTO_APPROVE
授权范围：ONCE（一次性决策，不持久化） RUN SESSION WORKSPACE （后三者为持久 Grant 范围）
核心组件: AuthorizationService · OperationAnalyzerRegistry · PermissionGrantRepository · DurableInteractionService · ToolExecutionGateway
证据边界 源码、测试与运行交叉核验
✓
架构事实来源
权限模式、Grant 范围、Project 边界和执行前复检以当前提交中的枚举、服务实现、数据库迁移与自动化测试为权威依据。
↻
运行证据边界
运行日志仅用于内部交叉核验关联上下文、工具链和恢复路径；不公开任务内容、路径、会话标识、时间窗口或运行统计，也不将未覆盖能力标记为日志已验证。
▸ 统一授权与执行准入全景流程
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 v3 options + deliveryGeneration ACK ≠ decision · V015 CAS AuthorizedOperation ALLOW source policy/grant/user Declared Outputs planOutputs() 无副作用预声明 动态环境复检 analyzer.recheck() 仅安全事实退化时拒绝 准入短事务 Grant 最终复检 + 预声明 execution_admitted 提交 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 与继承 5 种权限模式 · 授权范围见 REFERENCE A 无 Grant → 按模式裁决 SAFE file read 可按模式放行 DEFAULT 用户确认 PLAN 只读放行 ACCEPT_EDITS 编辑放行 DONT_ASK 仅 SAFE file read AUTO_APPROVE 硬拒绝仍生效 ROOT_AND_DESC 子代理受控继承 DIRECT_ONLY RUN 不跨 actor 子代理通过 root session/root run 身份直接匹配 Grant 不经过第二套冒泡授权权威 最终结果: AuthorizedOperation / DENY / WAITING_INTERACTION

Grant、权限模式与持久交互

▸ AuthorizationService 裁决与 V015/V019 数据权威
AuthorizationService · PermissionGrantRepository · DurableInteractionService SAFE_INTERNAL → Grant → mode → Durable Interaction；任一允许分支生成 AuthorizedOperation authorizePrepared(Tool, FrozenToolInput, PreparedOperation) root session/root run + operationHash + effect/resource/risk SAFE_INTERNAL exact effect? → POLICY ALLOW YES NO 受约束 Permission Grant 命中? → AuthorizedOperation HIT scope/profile/constraint/analyzerVersion MISS 未命中 Grant → 应用 PermissionMode Mode 阶段（无需用户交互） PLAN / DONT_ASK ACCEPT_EDITS 安全读取/受控编辑可按模式放行；需交互操作不得静默放行 ALLOW（记录授权来源） 模式明确允许 DEFAULT 或需显式确认 Durable Interaction（需要用户决策） optionId + expectedVersion deliveryGeneration + ACK 服务端提供 decision/scope options；同事务 CAS 终态并按需创建 Grant ALLOW（ONCE 或 Grant） ANSWERED allow DENY / EXPIRED DENIED / EXPIRED / UNDELIVERABLE 交互超时 → EXPIRED · DONT_ASK → 结构化拒绝 V015 interaction_requests · CAS 单一交互权威 V019 permission_grants · 约束、过期与撤销

V020 Project 工作空间信任边界

▶ Project 授权、Session 工作目录与路径归一化 V020Fail Closed
1
选择并持久授权 Project
直连本机且显式启用时可使用原生目录选择器；远程、反向代理和生产部署只浏览配置的 allowed roots。服务端保存可查询、切换和撤销的 V020 Project 记录。
2
绑定 Session 默认相对路径根
服务端解析真实、规范化绝对路径并拒绝根目录、符号链接别名、身份重绑定及规范化失败；Session 只接受 projectId，客户端任意 workingDirectory 会被拒绝。
3
越界重新进入授权链
Project 内普通文件读取或编辑是否自动允许取决于权限模式和 Grant；Project 外资源重新经过 Analyzer、AuthorizationService 与 Gateway 最终复检。
4
边界说明
Project 是持久、可撤销的信任范围和默认相对路径根，不是通用 OS 沙箱；Bash、敏感文件和高风险操作始终受独立安全控制。
Project Selection本机 picker / 远程 allowed roots不信任客户端 cwd 字符串 Path Normalizationreal / canonical path符号链接与别名复检 V020 Project Recordpersistent · revocableSession root binding Authorization + Gateway普通文件读写 / 越界复检硬拒绝 / Hook / Sandbox 不变 任意 cwd / 根目录 / 未授权根 / 别名或重绑定 / 规范化失败 → 拒绝绑定
05

Bash 安全模块 — 6层 AST 解析

tool/bash/ · 语义分析、分类、路径和执行前复检
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 → 安全执行入口 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 语义分析 | sandbox 容器隔离 | security Hook与敏感路径保护

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

Docker 沙箱隔离架构 — SandboxManager + SandboxConfig + ToolExecutionGateway 主机环境 (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() AuthorizationService — 沙箱不扩大授权边界 finalDynamicRecheck() → ToolExecutionGateway.execute() 顺序: Analyzer/Grant/Interaction → Gateway 复检与准入事务 → BashTool.call() 沙箱仅是 BashTool 内部的可选执行隔离；不会为文件或 Bash 操作自动授权 Docker 不可用或未启用时不改变 AuthorizationService 的风险、作用域与交互裁决 安全边界: sandboxManager.isSandboxingEnabled() 只选择执行路径，不是授权来源 docker run sandbox/ | 隔离层: read-only FS + network=none + seccomp + mem 512m + timeout 300s | 非root用户: zhikun
06

LLM 多提供商架构

llm/ · Provider注册、能力目录、重试与降级
▶ Provider 抽象层
LlmProviderRegistry (233行) — 提供商注册中心
├── AnthropicProvider (338行) → Claude 系列
└── OpenAiCompatibleProvider (641行)
├── OpenAI GPT
├── 通义千问 (Qwen)
├── DeepSeek（含 deepseek-v4-flash-vision-exp 图片兜底）
├── Moonshot / Kimi
├── 智谱 GLM-5.3
└── Ollama 本地部署
模型别名:
light → qwen3.7-max
standard → qwen3.7-max
premium → qwen3.7-max
百炼 Token Plan → qwen3.8-max / qwen3.8-flash / deepseek-v4-pro-0813 / deepseek-v4-flash-0731（独立 Provider，不进入默认降级链）
▶ 辅助组件
ModelRegistry
125行 · 模型配置注册
MessageParamConverter
272行 · 消息参数转换
ThinkingBudgetCalculator
104行 · thinking预算
LlmErrorClassifier
126行 · 错误分类
RetryPolicy
104行 · 重试策略
ApiKeyRotationManager
密钥轮换管理
LLM 多提供商抽象层架构 LlmProvider 统一接口 chat() / streamChat() / getModels() AnthropicProvider 338行 · Claude 系列 · 独立适配 sonnet-4-6 / opus-4-8 / haiku-4-5 OpenAiCompatibleProvider 641行 · 统一兼容层 OpenAI GPT GPT-5.6-Sol / 5.4-mini 通义千问 Qwen 3.7-max/plus · 3.8-max（百炼） DeepSeek v4 pro/flash · dated（百炼） Moonshot / Kimi kimi-k3 / v1-128k Ollama 本地 llama / qwen-local 智谱 GLM-5.3 glm-5.3 MiniMax-M3 thinking · prompt-cache ModelRegistry 125行 · 模型配置注册中心 · 别名映射 LlmProviderRegistry 233行 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-6 qwen3.7-max deepseek-v4-flash 跨厂商降级 qwen3.7-max qwen3.7-plus deepseek-v4-flash 同族 + 跨厂商 qwen3.7-plus deepseek-v4-flash qwen3.7-max 跨厂商 + 同族 注：未在表中的模型（Claude Opus/Haiku、GPT、Kimi、GLM 等）走 ModelTierService 默认策略，不触发降级链 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 123行 ▸ 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 · 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 模型降级 · 155行
注解@Service
resolveModel()选择最佳可用层级
triggerCooldown()API容量错误 → 冷却管理
reportSuccess()健康探测恢复（3次成功阈值）
冷却策略30分钟默认 · retry-after感知 · 短期重试豁免

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

STOMP over SockJS — UML 时序图 React 前端 stompClient.ts 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 interactionId + optionId/scopeOptions + operationHash + deliveryGeneration SEND /app/interaction-received interactionId + deliveryGeneration → ACK 后启动 300s 决策窗口 用户决定: POST /api/interactions/{id}/decisions（protocol v3 + expectedVersion + optionId） 6 心跳检测 STOMP heartbeat 10s/10s + /app/ping → pong heartbeatScheduler (ws-heartbeat- 线程) 7 断线重连 指数退避 1s→2s→4s→8s→10s 重连 → SockJS /ws + CONNECT + bind-session session_restored → 完整消息/活动 + Run snapshot/event seq + 活跃工具 + 待处理交互 关键配置参数 端点: /ws (SockJS) 心跳: 10s/10s 重连: 1s→10s cap 超时: 10min 消息限: 128KB 缓冲: 1MB 发送超时: 30s Client→Server 12 @MessageMapping Server→Client 25种推送类型 线程池: 4~20 队列: 200 TTL清理: 5min 主要 Client→Server 端点 /app/chat /app/interaction-received /app/permission (v2拒绝) /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 前端 stompClient.ts dispatch.ts useWebSocket.ts 119行

WebSocket/STOMP 实时通信 — 双向消息、结构化卡片与重连对账

▸ 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 #1 sendUserMessage() → /app/chat #2 acknowledgeInteraction() → /app/interaction-received #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/interaction-received /app/interrupt /app/model /app/permission-mode /app/command /app/mcp /app/rewind /app/elicitation /app/ping /app/bind-session /app/permission(v2拒绝) /app/activity-save /app/activity-update Server → Client (MESSAGE) /user/queue/messages convertAndSendToUser() /topic/session/{id} convertAndSend() broadcast /queue/coordinator/{id} CoordinatorEventBus 受控消息类型白名单 (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 协议 v2 → REST v3 错误 /interaction-received deliveryGeneration ACK /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

工具系统

40+ 内置工具 · MCP / 插件 / 平台条件工具动态扩展
▶ 工具分类树
文件操作
ReadFile
WriteFile
EditFile
ListDir
SearchFiles
执行 & 终端
BashTool → Sec §5
TaskTool
NotebookTool
搜索 & 分析
GrepTool
GlobTool
CodeSearchTool
Agent & 协作
SubAgentTool
MemoryTool → §11
McpTool → §7
Web & Git
WebFetchTool
WebSearchTool
GitTool
共 51 个工具实现 · 工具提供 Schema/元数据，生产授权由 Analyzer + AuthorizationService + Gateway 统一负责
▸ 工具分类与执行管道全景
51 个工具 × 5 层执行管道 工具分类树 — 40+ 内置工具 / 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/元数据 + 注册；Analyzer 决定授权事实 L2 ToolExecutionPipeline 执行管道 — 核心编排引擎 参数校验 → 统一授权/Gateway → 执行调度 → 超时控制 L3 StreamingToolExecutor 流式执行器 — 大输出处理 流式输出 → 增量传输 → 内存控制 → 背压 L4 Hook / Callback 钩子层 — 前后置处理 onBefore → 日志/审计 → onAfter → 通知 L5 ToolResult 结果聚合 — 统一输出 格式化 → Snip截断 → JSON封装 → 返回Agent 注册 调用 tool/ 105+文件 ~19,081行 核心执行×8 文件操作×5 代码分析×4 Web×3 监控×3 其他×18
▸ 工具执行 9 阶段管道 · ToolExecutionPipeline · StreamingToolExecutor · VirtualThread并发
ToolExecutionPipeline · 9 阶段执行闭环 · StreamingToolExecutor 并发模型 1 validateSchema JSON Schema V7 验证 networknt json-schema-validator validateSchema(tool, input) 失败: ToolInputValidationException 或降级为警告(non-strict) ToolExecutionPipeline.java L68 2 validateInput 工具自定义验证逻辑 tool.validateInput(ToolInput, ctx) 返回: ValidationResult { isValid, errorCode, errorMessage } 失败: ToolResult.error(...) 2.5 backfillObservableInput() 3 PreToolUse Hook HookRegistry → HookService hookService.executePreToolUse() matcher过滤 → handler执行 HookResult { proceed, message, modifiedInput, modifiedOutput } 拦截: proceed=false → 终止执行 HookService.java · HookRegistry 4 Permission Check 冻结输入 · Subject/Analyzer · Security Hook · 统一授权 AuthorizationService.authorizePrepared() ALLOW → 继续执行 DENY → 终止执行 INTERACTION → 等待数据库终态 ToolExecutionGateway 唯一生产执行入口 输出: AuthorizedOperation（policy/grant/user source） ━━━ PERMISSION GRANTED ━━━ 5 ToolExecutionGateway · 唯一 Tool.call() 入口 并发/VirtualThread 由上游 StreamingToolExecutor 管理 动态复检 → 短事务 Grant/ONCE/预声明/tool_started → 提交 → call() 上游 isConcurrencySafe()=true: 可并行调度，仍逐调用经过授权/Gateway 上游 isConcurrencySafe()=false: 独占调度，不改变权限裁决语义 失败恢复: attemptBashErrorRecovery() (Stage 5c) StreamingToolExecutor.java · 状态机: QUEUED→EXECUTING→COMPLETED→YIELDED 6 PostToolUse Hook PostHook链执行 hookService.executePostToolUse(toolName, output, sid) 可修改输出 / 拦截结果 敏感信息过滤: SensitiveDataFilter 返回: HookResult { modifiedOutput } HookService.java · SensitiveDataFilter 7 ContextModifier CAS循环更新执行上下文 result.getContextModifier() → UnaryOperator CAS更新 ExecutionSession.currentContext 仅非并发安全工具的modifier被应用 maxRetries=100 超时保护 AtomicReference<ToolUseContext> StreamingToolExecutor 并发模型 ExecutionSession · ConcurrentLinkedQueue · AtomicInteger isConcurrency Safe()? true 并行: Read/Glob/Grep/Token* false 独占: BashTool写操作 QUEUED EXECUTING COMPLETED YIELDED yieldCompleted(): 按原始顺序返回 (FIFO缓冲保证) ToolResultSummarizer 结果处理 三级策略 · 旧轮次清理 · Message注入 L1: ≤18K chars → 原样保持 L2: 18K-50K → 头12K+尾3K L3: >50K → LLM摘要(10s超时) 旧轮次清理: currentTurn - messageTurn > 8 → [tool result cleared] SOFT_LIMIT=18K · HARD_LIMIT=50K · LLM降级为截断 · 注入: Message.UserMessage.toolUseResult() ToolResultSummarizer.java · 轻量级模型 · 10s超时 监控指标 (Micrometer) Counter zhiku.tool.executions.total zhiku.tool.executions.errors Timer zhiku.tool.execution_time [tag:tool] Gauge zhiku.tool.virtual_threads.active ExecutionSession 结构: queue: ConcurrentLinkedQueue tracked: CopyOnWriteArrayList active: AtomicInteger currentContext: AtomicReference

插件生命周期 — 发现 · 隔离加载 · 注册 · 执行 · 卸载 — 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行
▸ 工具权限决策模型 — 5种权限模式 · ONCE一次性决策 + 3种持久Grant范围 · 执行前复检
5模式 / ONCE决策 + 3持久Grant范围 DEFAULT · PLAN · ACCEPT_EDITS · DONT_ASK · AUTO_APPROVE DEFAULT — 写操作弹窗确认 PLAN — 仅 SAFE workspace file read ACCEPT_EDITS — 受控工作区文件写 DONT_ASK — 仅 SAFE 文件读，否则拒绝 AUTO_APPROVE — 自动确认，硬拒绝仍生效 一次性决策: ONCE（不持久化） 持久Grant: RUN / SESSION / WORKSPACE 工具元数据(PermissionRequirement，非授权权威): NONE ALWAYS_ASK CONDITIONAL 实际裁决只由 Analyzer、AuthorizationService 与 Gateway 完成 metadata 不得绕过 risk/effect/resource 与最终动态复检 统一授权与执行流程 AuthorizationService + PermissionGrantRepository Schema / Tool 校验 → PreToolUse → 重验 FrozenToolInput → canonical JSON + inputHash SubjectResolver + Analyzer → root identity / facts OperationDescriptor · risk/effect/resource Invariant + 只收紧 Security Hook SAFE_INTERNAL → Grant → 模式 → Interaction AuthorizedOperation → planOutputs() Gateway 动态/Grant 复检 → 短事务 → call() 授权组件: PermissionGrantRepository · 约束化 Grant OperationAnalyzerRegistry · 工具分析器 AuthorizationDiagnostic · 结构化裁决信息 PermissionModeManager · 模式管理 Bash 3层验证 BashCommandClassifier.java Layer 1: READONLY_COMMANDS ~60个纯只读命令 ls, cat, grep, find, wc, head... → 生成 SAFE/GUARDED 分析事实 Layer 2: READONLY_REGEXES 正则匹配只读命令模式 git log/status/diff, docker ps... → 参数级验证后交由 AuthorizationService Layer 3: COMMAND_ALLOWLIST Flag级别白名单验证 含6项安全加固规则 → 未命中 = 需要用户确认 危险/复杂输入 → HIGH + ONCE rm -rf / · chmod 777 · mkfs 不可创建持久 Grant；绝对黑名单直接拒绝 安全保护路径（不可绕过） .git .zhikun .env .ssh .gnupg .aws ← File/Bash Analyzer 与 finalDynamicRecheck 负责路径、链接和动态环境复检 OperationAnalyzerRegistry · PermissionGrantRepository · DurableInteractionService · ToolExecutionGateway 权限系统核心统计 AuthorizationService Bash Parser/Classifier（复用现有实现） OperationAnalyzerRegistry 5模式 · ONCE决策 + 3持久Grant范围 · 2继承策略 关键设计: 冻结输入 · 不变量不可覆盖 · 持久交互CAS · 子Agent按root identity匹配Grant · Gateway最终复检
▸ LSP 协议与编辑器集成 · lsp/ 8文件 · 9种操作 · JSON-RPC over stdio · 多语言支持
L1 前端 Monaco Editor @monaco-editor/react · TypeScript CodeDiagramGenerator.tsx CodeBlock.tsx MemoryEditorPanel.tsx 配置: vs-dark主题 · minimap禁用 · fontSize:12 · wordWrap:on Mermaid编辑+预览 SyntaxHighlighter · 文件编辑 React L2 HTTP 通信层 REST: POST /api/lsp/{operation} 请求: { operation, filePath, line, character } 响应: { result, success } HTTP L3 LSPTool.java implements Tool · 309行 · 文件≤10MB · 位置转换 1-based→0-based goToDefinition → textDocument/definition findReferences → textDocument/references hover → textDocument/hover documentSymbol → textDocument/documentSymbol workspaceSymbol → workspace/symbol goToImplementation → textDocument/implementation prepareCallHierarchy → textDocument/prepareCallHierarchy incomingCalls → callHierarchy/incomingCalls outgoingCalls → callHierarchy/outgoingCalls POSITION_OPERATIONS: goToDefinition, findReferences, hover, goToImplementation, prepareCallHierarchy JSON-RPC L4 LSPServerManager.java 150行 · 多服务器实例管理 · ConcurrentHashMap registerAndStart(config) getServerForFile(filePath) sendRequest(method, params) shutdown() 文件同步: openFile→didOpen · changeFile→didChange · closeFile→didClose serversByExtension: Map<ext, LSPServerInstance> · openedFiles: ConcurrentHashMap.newKeySet() 路由 L5 LSPServerInstance.java + 外部LSP进程 97行 · ProcessBuilder启动子进程 · JSON-RPC over stdio 初始化: initialize request → initialized notification · isRunning() 健康检查 · isIdleTimeout() 空闲超时 sendRequest(method, params) · sendNotification(method, params) · start() / stop() TypeScript LSP Python (Pyright) Java (Eclipse.jdt.ls) stdio LspCallHierarchyService 333行 · 调用层级+降级 LSPTool 309行 · LSPServerManager 150行 · LSPServerInstance 97行 · LspCallHierarchyService 333行 · ChangeImpactAnalyzer 205行 · LspService 76行 · LSPServerConfig 94行
9b

CLI 斜杠命令系统 — 7层交互式框架

command/ 9个核心类 + impl/ 37个实现· 88个已注册命令 · WebSocket STOMP 驱动
Frontend Web UI WebSocket STOMP Parser 69行 Registry 253行 Router 100行 · 6层安全 Execute ×3 模型 CommandResult 5种·CommandType 3种·Virtual Thread 异步
CLI Slash Command Architecture · 7-Layer Interactive Framework WebSocketController.handleSlashCommand() L1 Frontend Web UI · 用户输入层 SlashCommandPicker / ChatInput · 识别 “/” 前缀才触发选器 输入示例： /commit · /model deepseek-r1 · /clear · /help /command [args] ClientMessage L2 WebSocket STOMP · 传输层 @MessageMapping("/command") · type: slash_command · 双向推送 服务端推送： command_result · stream_delta · tool_use_request /app/command STOMP frame L3 SlashCommandParser · 解析层 parse(rawInput) → ParsedCommand { name, args[] } 验证斜杠前缀 · 拆分命令名与参数 · 处理引号转义 parse() 69 行 L4 CommandRegistry · 发现层 findCommand(name) → Optional<Command> · ConcurrentHashMap 名称/别名双索引 suggestSimilar(name) → Levenshtein 距离模糊匹配 · 返回 Top-N 候选 @PostConstruct 自动扫描 Spring Bean · register(Command) · 冲突检查 93 commands 253 行 L5 CommandRouter · 路由与安全层 route(rawInput, context) → CommandResult · 6层安全闸门 ① SlashCommand 解析验证 ② 远程模式·32命令白名单 ③ 桥接模式检查 ④ 认证要求检查 ⑤ FeatureFlag 特性开关 ⑥ getAvailability() 可用性 CommandContext { sessionId, workingDir, currentModel, isAuthenticated, isRemoteMode, isBridgeMode, appState } CommandRouter.java · 任何一层失败 → CommandResult.error() execute(args, context) L6 Execution Layer · 三种执行模型 (CommandType) LOCAL 本地同步执行 execute() → text() /clear /help /status /version /cost /diff PROMPT LLM 驱动 Virtual Thread → QueryEngine 异步 /commit /review /plan /explain /security-scan LOCAL_JSX 前端组件渲染 → jsx(Map) 结构化 /model /config /mcp /permissions /agent L7 Backend Services · 服务依赖层 QueryEngine LLM执行·Agent循环 SessionManager 会话·上下文 ToolRegistry 51工具·调用 ModelRegistry 多提供商路由 PermissionPipe 统一授权 CompactService · 上下文压缩 /compact · 5级级联 · ContextCascade Concurrency · ConcurrentHashMap<String,AtomicBoolean> sessionQueryRunning 同会话防并发 · PROMPT 命令 Virtual Thread 异步 REGISTERED COMMANDS 93 impl/ · 37 files · ~3,141 lines 9 大命令分类 会话 / 上下文 7 · clear context copy export… Git / 代码管理 8 · commit branch pr review… 代码分析 3 · search blame symbols 交互 / 输出 7 · help status compact undo… 配置 / 模型 9 · model config effort theme… 高级功能 11 · memory plan skill mcp… IDE / 集成 13 · bridge ide chrome init… AI 增强 10 · advisor agent buddy fork… 工作流 8 · workflows ultrareview… CommandResult · 5 种返回型 • TEXT 纯文本·直接展示 • PROMPT 提示词·触发 LLM • JSX Map·前端组件渲染 • COMPACT 压缩上下文结果 • ERROR 错误信息·不中断会话 CommandResult.java · 结构化命令结果 Command 接口 · 核心方法 String getName() CommandType getType() List<String> getAliases() Availability getAvailability() execute(args, context) Command.java · PromptCommand · 稳定接口职责 WebSocket 推送消息类型 → 入口：slash_command ClientMessage { rawInput, sid } ← 出口：command_result stream_delta · tool_use_request permission_request · error WebSocketController.java · slash_command / command_result
▶ 文件路径与核心类
command/ 核心接口
Command.java 基础接口
CommandType.java LOCAL / PROMPT / LOCAL_JSX
CommandContext.java 不可变命令上下文 record
CommandResult.java 5 种结构化结果
PromptCommand.java 提示词接口
command/ 调度与解析
SlashCommandParser.java parse()
CommandRegistry.java 命令注册与发现
CommandRouter.java 6 层安全路由
command/impl/ 命令实现集合
websocket/WebSocketController handleSlashCommand()
09c

运行时验证 — 双模 Verifier 多态分发

VerifyJourneyTool · VerifierFactory · Browser/HTTP API · Evidence + STOMP
Java Verifier 接口 Python httpx 异步 能力域感知 8 Action 策略字典 MAX_STEPS=500 Browser 120s · HTTP API 60s · Evidence + STOMP verify_progress
▸ 运行时验证多态分发机制 — VerifierFactory 双模选择
// VerifyJourneyTool.call() → VerifierFactory.selectVerifier() → Browser | HTTP API VerifyJourneyTool.call() Tool 入口 · @ALWAYS_ASK · isOpenWorld=true backend/tool/verify/VerifyJourneyTool.java parse verification_mode VerifierFactory.selectVerifier(req, mode) enum: "browser" | "http_api" | "auto" @Qualifier("browserVerifier") + @Qualifier("httpApiVerifier") "browser" "auto" "http_api" steps.anyMatch action.startsWith ("http_") false true BrowserVerifier verify/BrowserVerifier.java ▸ capability isCapabilityAvailable ("BROWSER_AUTOMATION") ▸ endpoint /api/browser/journey/run ▸ requires PreviewStackDetector + DevServerLauncher.start() ▸ timeout JOURNEY_TIMEOUT = 120s ▸ body session_id="rv-"+sid · viewport record={video,har,trace} HttpApiVerifier verify/HttpApiVerifier.java ▸ capability isCapabilityAvailable ("HTTP_API") ▸ endpoint /api/http/journey/run ▸ requires — no DevServer — 直连 base_url，跳过 stack 探测 ▸ timeout HTTP_JOURNEY_TIMEOUT = 60s ▸ body session_id · base_url · steps record=Map.of() (无录制) JourneyResult verdict / errorMessage → handleVerificationResult() verified · failed · unavailable → EvidenceStore.save() EvidenceBundle (kind=journey) → STOMP /queue/messages verify_progress · verification_result
▸ HTTP API 验证执行管道 — 8 Action 策略字典分发
// HttpApiVerifier (Java) → callIfAvailable → http_journey_run (Python) → HTTP_ACTION_HANDLERS JAVA · backend/verify/ HttpApiVerifier.verify() guard: isCapabilityAvailable("HTTP_API") body = {session_id, base_url, steps} PythonCapabilityAwareClient .callIfAvailable("HTTP_API", endpoint, body, 60s) → Optional<JourneyResponse> 目标 API 服务器 request.base_url e.g. http://127.0.0.1:8080 业务后端 / 第三方 REST POST /api/http/journey/run PYTHON · python-service/src/routers/http_api.py @router.post("/journey/run") async def http_journey_run(request: JourneyRunRequest) 边界防护 MAX_STEPS = 500 MAX_CONTEXT_SIZE_BYTES = 50MB 连接池 async with httpx.AsyncClient(follow_redirects=True) as client: ▸ for i, step in enumerate(request.steps): _resolve_variables(step, context_vars) ${var_name} → context_vars[name] _execute_http_step(...) handler = HTTP_ACTION_HANDLERS.get(action) client.request() httpx → 目标 API → response last_response · context_vars 反馈下一步 step_results.append(StepResultModel) · failed → break (首步失败即停) HTTP_ACTION_HANDLERS dict[str, Callable] · 8 handlers http_get → client.get(url, headers, params) http_post → client.post(url, json/content) http_put → client.put(url, json, headers) http_delete → client.delete(url, headers) — assertions — assert_status last_response.status_code == expected_code assert_json jsonpath_parse(path) .find(body) == expected assert_header expected_substring in last_response.headers[name] — state — set_variable context_vars[name] = jsonpath_parse(path).find(body)[0] → 跨 step 共享变量 dispatch RESULT · 结果回传 StepResultModel index · action · ok duration_ms · error screenshot_base64=None (HTTP) JourneyRunResponse passed · step_results session_id · final_url → Java JourneyResult.from(r) 异常分类（httpx） ConnectError · TimeoutException HTTPError → ok=False · 计入 step.error

验证产物归属与显式发布链路

▶ Artifact declare → seal/hash → verified entry → PublishArtifact → OSS Verified / Partial显式高风险

工具先声明预期输出，执行完成后封存并计算哈希；Manifest 状态可以是 verified，也可以是包含目标已验证条目的 partial。目标条目还需在发布前再次匹配哈希，并在用户明确提出发布和通过一次高风险授权后才能进入 OSS。生成、预览或完成 Run 均不会自动上传。

declareplanOutputs()路径 / 类型 / owner seal + hash普通文件封存size / SHA-256 verified entrymanifest: verified / partial发布前再次验 hash PublishArtifact明确指令 + ONCE敏感内容 / 路径复检 OSS 权威外链私有上传 → 远端校验成功后 public-read 根 Session 与后代 Run 产物归属 候选包括同一持久化根 Session 的根 Run，以及通过 parent_run_id 建立的授权后代 Run；目标条目必须已验证且哈希仍匹配 目录、批量、符号链接、workspace 外路径、凭证与敏感文件拒绝发布
10

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

L0 SnipL1 MicroCompact 183行L2 AutoCompact 1,058行L3 IncrementalCollapse 174行L4 ReactiveCompact 148行 ContextCascade 348行 · 六级级联编排
6 层级联上下文压缩管道 — ContextCascade.java · 统一协调器 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 · 压缩效率监控 IncrementalCollapseManager · 增量折叠

ContextCascade 正常执行流程 — executePreApiCascade

ContextCascade 正常执行流程 — 每次 API 调用前无条件执行 (executePreApiCascade) QueryEngine.executeLoop() Step 1: 调用 ContextCascade.executePreApiCascade() TokenCounter.countTokens() 334行 · 三层精度估算 · 计算当前 token 使用量 L0 Snip SnipService.java · 150行 方法: snipIfNeeded() 动作: 单条工具结果超预算 → 截断中间内容，保留首尾各50% 触发条件: toolResult > contextWindow × 0.3 × 3.5 防止单条超长结果占据上下文 可压缩工具: Read, Bash, Grep, Glob, WebSearch, WebFetch, Edit, Write 无条件继续 ↓ L1 MicroCompact MicroCompactService.java · 183行 方法: microCompact() 动作: 将旧的可压缩工具结果替换为 "[cleared]" 触发: 每次无条件执行 · 保护尾部: 最近10条消息(protectedTail=10) 轻量级操作 — 无 LLM 调用 仅对超过 protectedTail 的历史消息 将 toolResult 内容清空为 [cleared] 无条件继续 ↓ L1.5 ContextCollapse ContextCollapseService.java · 会话折叠 方法: progressiveCollapse() 动作: 三级渐进折叠处理 A. FullRetention: 尾部10条完整保留 B. SummaryRetention: 10-30条截断保留500字符 | C. SkeletonRetention: 30+条仅保留骨架 规则: UserMessage 永远保留原文 CollapseLevel sealed interface 54行 IncrementalCollapseManager 175行 增量折叠: 每10轮触发 检查 token > 85% ↓ L2 AutoCompact ⭐ CompactService.java · 主动压缩 方法: compactMessages() 触发: token使用率 > 85% 阈值 (AUTO_COMPACT_THRESHOLD=0.85) 三区划分: FROZEN → COMPACTION → PRESERVED(最近3轮) 3级降级: ① LLM摘要生成(优先) → ② 关键消息选择(LLM失败) → ③ 尾部截断(最后手段) 目标压缩率: 50% · 摘要上限: 4,096 tokens · BUFFER_TOKENS=13,000 三区划分模型 FROZEN ZONE — 已压缩区不再触碰 COMPACTION ZONE — 历史消息压缩目标 PRESERVED ZONE — 最近3轮完整保留 压缩完成 → API 调用 正常路径结束 · 消息发送至模型 错误恢复路径 (仅 413 错误触发) PromptTooLongRecovery · 148行 API 返回 413 L3 CollapseDrain   目标: contextWindow × 0.5   动作: 激进压缩，仅保留1轮对话 失败 ↓ L4 ReactiveCompact   极度压缩，仅保留1轮 + 最小上下文   仅允许执行一次(防死亡螺旋) · 失败→错误上报 恢复成功 → 重试 API 电路断路器 TokenBudgetTracker 连续3次失败 → 禁用 图例: 正常流程 错误恢复 核心层 仅413触发 L0-L1.5: 每次 API 前无条件执行(低代价) | L2: token > 85% 时触发 | L3-L4: 仅 413 错误恢复

三区划分 — 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

▎Agent Loop 任务执行全链路 — Session 7675c534 实例

Agent Loop 任务执行全链路时序图 — Session 7675c534 12:27:54 → 12:37:03 · 1 次工具调用 · Write 86,063B → 文件 72,416B · totalTokens=96,464 用户 / 前端 WebSocket Client QueryEngine Agent Loop 控制器 LLM Provider DashScope / qwen3.7-max ToolExecutionPipeline 9 阶段执行管线 FileSystem AtomicFileWriter T 12:27:54 ① 用户请求 messageCount=1 maxTurns=200 12:27:54 ② streamChat() effectiveMaxTokens=65536 12:27:55 ③ HTTP 200 · 流开始 SSE chunk_open ④ tool_use_start 12:28:01 · Write ToolInputDelta 流式积累 86,063 字节 · 8m44s ≈ 164 B/s 流速 …积累中… 12:36:45 ⑤ BlockStop 事件 flushToolBlock 触发 12:36:45 ⑥ flushToolBlock(Write, inputLen=86063) ⑦ Stage 1: Schema Validation ✓ deny → ask → checkPermissions → contentLevel → safety → sandbox 12:36:46 ⑧ permission_request → ASK 前端弹出授权确认 12:36:56 ⑨ allow （等待 10s） 12:36:56 ⑩ Stage 5: call AtomicFileWriter 72,416B ⑪ write success · 26ms 12:36:56 ⑫ ToolResult(error=false) · 11,520ms ⑬ Turn 2 · streamChat（携带工具结果） 12:37:03 ⑭ end_turn · TERMINATE_SUCCESS ⑮ message_complete 性能指标 流式积累 8m44s 86KB @ 164 B/s 权限等待 10s 用户授权 allow 文件写入 26ms 72,416 字节落盘 Pipeline 总时 11.5s 含权限等待 10s 总 Token 96,464 2 Turn 累计 端到端 9m09s 12:27:54 → 12:37:03 瓶颈分析 ▸ LLM 流式生成 95.4% ToolExecutionPipeline · 9 阶段执行管线（基于本会话实际命中） Stage 1 validation Schema ✓ Stage 2 deny 未命中黑名单 Stage 3 ask ★ ASK 用户 Stage 4a-c contentLevel safety / sandbox Stage 5 call ★ AtomicFileWriter Stage 6 modeTransform 结果加工 Stage 7 checkPermissions 汇总 → ToolResult
11

辅助系统

▶ 记忆系统 memdir/ · Project记忆与检索
MemdirService598行 — 核心记忆目录管理
MemorySearchEngine197行 — BM25检索(K1=1.2, B=0.75)
MemoryRerankService128行 — LLM精排(3000ms超时降级)
MemoryTool117行 — 工具接口
▶ Skill 系统 14 个内置 Skill · 动态扩展
SkillRegistry14 个内置 Skill，按 BUNDLED / PROJECT / USER / PLUGIN / MANAGED / MCP 六层来源合并，WatchService 热重载
Bundled Catalogcommit · review · fix · test · pr · debug · verify · stuck · remember · software-architecture · csv-data-summarizer · prompt-engineering · test-driven-development · publish-oss
SkillDefinition95行 — record 类型 · SkillSource 枚举 6 值
FrontmatterParser241行 — 简化 YAML 解析 (key: value / 列表项)
FrontmatterData75行 — 16 个 frontmatter 字段
SkillExecutor177行 — inline/fork 分发 · 120s 超时 · Token 预算检查
SkillToolValidator97行 — 参数注入检测 + fork 嵌套深度 ≤3 (allowed-tools 白名单仅声明，运行时未拦截)
▶ 安全模块 security/ · Hook与敏感路径
CommandBlacklistService377行 — 命令黑名单
PathSecurityService433行 — 路径安全
SensitivePathRegistry300行 — 敏感路径注册
SensitiveDataFilter68行 — 数据过滤
SecurityAuditLogger70行 — 审计日志
▶ Docker 沙箱 sandbox/ · 容器隔离
SandboxManager容器隔离执行环境

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

memdir + history + controller + frontend · Project记忆持久化与检索链路 存储层 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 系统加载与执行架构 — 14 个内置 Skill · inline/fork 双模式 · 动态来源合并

高级任务 用户指令 Slash Command Skill 核心引擎 SkillRegistry SkillRegistry.java SkillSource 6 类 · 3 类已加载 SkillDefinition.java · 来源与元数据 元数据解析 FrontmatterParser 240行 FrontmatterData 74行 YAML Frontmatter SkillExecutor SkillExecutor.java inline/fork 分发 · 120s 超时 SkillTool SkillTool.java 125行 Agent ↔ Skill桥接 ArgumentSubstitution.java 113行 · 参数替换引擎 Skill 实现节点池 commit review fix test pr fork (用户定义) ● inline (默认) — 注入当前对话 ● fork — 创建子 Agent 内置 5 个 .md (无 frontmatter · 默认 inline) · 用户/项目 Skill 可声明 fork 结果聚合 输出合并 返回Agent SkillSource 枚举 · 优先级 高→低 1. MANAGED — 企业管理 <预留> 2. USER — ~/.zhikun/skills/ ✓ 3. PROJECT — .zhikun/skills/ ✓ 4. PLUGIN — 插件提供 <预留> 5. BUNDLED — 内置 5 个 ✓ 6. MCP — MCP 构建 <预留> 加载顺序: BUNDLED→PROJECT→USER (后覆盖前) WatchService 热重载 · DEBOUNCE_MS=500 skill/ 9文件 · 1,437行 | SkillRegistry 412行 · FrontmatterParser 241行 · SkillTool 125行 · SkillExecutor 177行 · SkillToolValidator 97行

Skill 系统源码级实现细节 — 按源码字段/常量/路径直引

▸ FrontmatterData 字段 (16)
description · name · allowedTools · argumentHint · arguments · whenToUse · version · model · disableModelInvocation · userInvocable · hooks · effort · context · agent · paths · shell
默认: context=inline · shell=bash · userInvocable=true
▸ SkillExecutor 执行模式
• inline (默认): 渲染后的 prompt 作为用户消息注入当前对话
• fork: 返回 prompt + metadata (agent/model/effort) 供外层 AgentService 创建子代理
• Token 预算检查: 调用 SkillTokenBudget.canConsume()
• 超时: SKILL_TIMEOUT_SECONDS = 120 (CompletableFuture.orTimeout)
▸ SkillToolValidator 安全检查
• MAX_ARG_LENGTH = 2000 字符
• MAX_FORK_NESTING_DEPTH = 3
• 6 个 shell 注入正则: $(...) · `...` · ; cmd · | cmd · && rm · ${...}
• SkillExecutor 集成: validateArgs() ✓ · validateForkPermission() ✓
• allowed-tools 白名单声明 (运行时验证规划中，validate() 当前仅测试覆盖)
▸ WatchService 热重载
• 监听目录: 项目 .zhikun/skills/ (含一级子目录)
• 事件类型: ENTRY_CREATE · ENTRY_MODIFY · ENTRY_DELETE
• 防抖间隔: DEBOUNCE_MS = 500 ms (ScheduledExecutorService)
• 守护线程: skill-file-watcher · skill-watcher-debounce
• CREATE/MODIFY → register · DELETE → 反注册
• PreDestroy 时关闭 WatchService 并停止线程池
稳定职责锚点： SkillRegistry（六层来源与热重载） · SkillDefinition（来源和元数据） · SkillExecutor（预算、超时和 fork） · SkillToolValidator（参数、嵌套和注入检查）。具体源码行号随提交变化，不作为架构契约。

结构化观测、Session 恢复投影与断线恢复

▶ BestEffortObservabilityRecorder、结构化结果与恢复投影 职责分离故障隔离
1
统一 MDC 关联上下文
sid / rid / prid / agent / turn / tool / llm 由整体日志上下文贯穿 Run、父子 Agent、工具和模型调用，不归因于单个 Recorder。
2
结构化外部资源
工具结果投影为可折叠卡片；下载、Artifact 和 OSS 地址携带来源、状态与权威链接，不从日志文本猜测资源。
3
Recorder 故障隔离
BestEffortObservabilityRecorder 使用有界异步队列写补充事件，并记录丢弃、写失败和队列深度指标；失败不升级为工具或 Run 执行失败。
4
重连恢复
session_restored 返回完整 Session 消息、最近活动、最新 Run snapshot/event sequence 和活跃工具状态，并重放待处理的持久交互；前端按绑定代次替换投影。
MDC Correlationsid/rid/prid/agent/turntool / llm BestEffortObservabilityRecordersupplemental event logbounded queue + metrics Session Restoremessages / Run event seqactive tools / pending interactions React Projection结构化结果 / 工具卡片权威下载 / snapshot 替换 补充观测与 Session 恢复是独立支路；工具结构化结果和持久 Run/交互状态保持各自权威
12

多Agent协调系统

5 类内置 Agent · Team / Swarm / SubAgent 三种协作模式
Team模式Swarm模式SubAgent模式 general-purpose · explore · verification · plan · guide
根 Session 身份、授权与验证产物归属

子 Agent 通过 root session / root run 身份匹配受约束 Grant，不建立第二套授权权威。Artifact 保留 agent 与 parent run 关联；显式发布候选来自同一持久化根 Session 的根 Run 与授权后代 Run，目标条目必须已验证且发布前哈希仍匹配。

▸ 多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 并行 · CoordinatorWorkflowEngine 四阶段流水线 SwarmService 484行 · Java 21 Virtual Thread · Caffeine TTL 4h 1. Research → 2. Synthesis 3. Implementation → 4. Verification SwarmWorkerRunner · 333行 WorkerStateTracker · 137行 SwarmState · 203行 · 状态管理 每阶段可并行多个 Worker 阶段间同步屏障（Barrier） SwarmController 299行 · 对外API SubAgent Mode 独立子代理 · root identity 授权继承 SubAgentExecutor 1,032行 · 子代理执行与隔离 AuthorizationSubjectResolver 解析 root session / root run / actor run SubAgent → Subject → Grant root identity 授权继承 → InProcessBackend · 127行 WorkflowPhase · 234行 子Agent独立Agent Loop 按 root session/root run 匹配 Grant 不再存在独立冒泡权限权威 共享基础设施 CoordinatorPromptBuilder 357行 CoordinatorEventBus 151行 CoordinatorService 259行 CoordinatorWorkflow 246行 SwarmConfig 92行 coordinator/ 19文件 + tool/agent/SubAgentExecutor 1,032行 Swarm: Virtual Thread并发 Team: 邮箱通信 授权继承: ROOT_AND_DESCENDANTS

三模式协调对比 — 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 AuthorizationSubjectResolver · root session/root run 四阶段流水线 Research → Synthesis → Implementation → Verification 适用场景 复杂研究型任务 · 需要阶段性交付 · 多Worker协同 并行度阶段内多Worker并行 同步阶段间Barrier同步屏障 SubAgent 模式 独立子代理 · 受约束 Grant 继承 SubAgentExecutor · 1,032行 AgentConcurrencyController · Slot WorktreeManager · Git隔离 DIRECT_ONLY / ROOT_AND_DESCENDANTS 父子授权继承机制 SubAgent → Subject → Grant 适用场景 简单委派任务 · 隔离执行 · Fork复用KV缓存 并行度独立Agent Loop(串行) 匹配root identity + descriptor constraints 模式选择决策 Team: 需要固定角色分工且Worker间需通信 Swarm: 复杂任务需四阶段分解且多Worker并行 SubAgent: 简单独立子任务委派
▸ 多Agent协调深度执行流 · coordinator/ 19文件 4,138行 · Team/Swarm/SubAgent 三模式
Team 模式 · 固定角色分配 TeamManager 137行 · SharedTaskList 174行 · ResultAggregator 101行 CoordinatorService.matchSessionMode() → mode="team" TeamManager.dispatchTasks(teamName, tasks, parentContext) SharedTaskList.addTask() FIFO · ConcurrentLinkedQueue · AtomicLong序列号 Worker-N: SharedTaskList.claimTask(teamName, workerId) FIFO认领 · Iterator遍历 · 原子状态转换 各Worker独立 QueryEngine.execute() TeamMailbox.writeToMailbox(recipientId, senderId, content) broadcast() · ConcurrentLinkedQueue · 109行 ResultAggregator.aggregateResults() 并行等待 → 按序汇聚 · 101行 通信机制: TeamMailbox • writeToMailbox(recipientId, senderId, content) • broadcast(senderId, content) → 全Worker推送 • readMailbox(agentId) → List<MailMessage> • clearMailbox(agentId) → 生命周期清理 InProcessBackend · 127行 · Virtual Thread • executeParallel(requests, ctx, maxConcurrency) • Worker数上限: 1-20 (TeamManager校验) • VirtualThread per Worker · CompletableFuture并行 结果汇聚路径 Worker完成 → AgentResult → List<AgentResult> InProcessBackend.executeParallel() → 阻塞等待全部完成 Swarm 模式 · 动态协商 SwarmService 484行 · SwarmWorkerRunner 333行 · SwarmState 203行 POST /api/swarm → SwarmService.createSwarm(config, sessionId) swarmId = "swarm-" + UUID.randomUUID()[0:8] SwarmState初始化 · Caffeine Cache TTL=4h max=50 POST /api/swarm/{id}/workers → addWorker() workerId = swarmId + "-worker-" + workers.size() SwarmWorkerRunner.startWorker() · VirtualThread AuthorizationService · DurableInteractionService 父 Grant 未命中时创建持久权限交互 QueryEngine.execute() → onWorkerComplete() CoordinatorWorkflowEngine 四阶段 · 446行 Research → Synthesis → Implementation → Verification CoordinatorEventBus · 151行 · STOMP推送 • publishPhaseTransition(swarmId, phase) • STOMP: /user/queue/coordinator/{sessionId} • eventType: phase_transition / mailbox_write • eventType: mailbox_broadcast / worker_complete SwarmService.shutdownSwarm(swarmId) 1. RUNNING → SHUTTING_DOWN → forcePhase() 2. 广播 shutdown_request → 30s异步等待 3. cleanupSwarm() → TERMINATED 4. TeamMailbox.clearMailbox() 5. RUN Grant 仅匹配同一 rootRun，并受 TTL/显式撤销约束 SwarmPhase 状态机 · SwarmState 203行 INITIALIZING → RUNNING → IDLE → SHUTTING_DOWN → TERMINATED WorkerStatus: RUNNING → IDLE / TERMINATED SubAgent 模式 · 父子委托 SubAgentExecutor 1,033行 · AgentConcurrencyController · BackgroundAgentTracker AgentTool.call(input, context) input: {prompt, subagent_type, isolation, model} agentId = "agent-" + UUID[0:8] · run_in_background SubAgentExecutor.executeSync(request, parentContext) AgentConcurrencyController · 并发控制 全局≤30 · 会话≤10 · 嵌套深度≤3 · Semaphore resolveAgentDefinition(agentType) 5种预置: explore / verification / plan general-purpose / guide · 禁用递归: Agent/Team/Task IsolationMode 隔离模式 ├─ NONE: workDir = parentContext.workDir ├─ WORKTREE: WorktreeManager.createWorktree() └─ FORK: SessionManager.forkSession() 复用KV缓存 QueryEngine.execute() · 独立Agent Loop 5min超时(PER_AGENT_TIMEOUT) · 100K字符结果上限 后台模式 (run_in_background=true) • BackgroundAgentTracker.track(agentId) • WebSocket事件: agent_started / agent_completed • /user/queue/{sessionId} · agent_failed • VirtualThread异步 · CompletableFuture 授权继承 · AuthorizationSubjectResolver • SESSION/WORKSPACE: root及后代按相同约束复用 • RUN DIRECT_ONLY: 不被兄弟或后代误用 结果收集 AgentResult(status, result, originalPrompt, metadata) 通信机制对比 TeamMailbox · ConcurrentLinkedQueue · 点对点+广播 CoordinatorEventBus · STOMP WebSocket · 阶段转换事件 BackgroundAgentTracker · WebSocket · agent生命周期事件
13

React 前端架构

209 文件 · 33,642 行 · 117 TSX 文件（109 非测试）· 36 Store
▶ 组件层 117 TSX 文件（109 非测试）· 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行
▶ 状态管理 — 36 个 Store 文件 Zustand + 配套状态模块
coordinatorStoremcpStoreconfigStoreswarmStoremessageStoreplanStoretaskStoresessionStoretoolStorepermissionStore + 26 more store files
▸ 36 个 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广播中间件 — 事件驱动状态同步 连接全部 36 个 Store 文件 · 发布/订阅模式 业务×7 系统×5 UI×4 分析×4 元数据×2 broadcast广播 configStore依赖 约2,846~3,278行

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

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

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

stompClient.ts

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

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

Python 分析服务架构

服务 + CLI · 32 文件 · 8,066 行 · 7 能力域
▶ 分析引擎 analyzers/ · 调用图、影响和路径分析
flow_chart_generator.py657 行
code_path_tracer.py622 行
call_graph_builder.py582 行
sequence_diagram_generator.py527 行
change_impact_analyzer.py416 行
▶ 业务服务 services/ · 浏览器、Git与文件服务
browser_service.py浏览器会话与自动化服务
complexity_analyzer.py515 行
tree_sitter_service.py237 行
browser_models.py119 行 — Pydantic 浏览器数据模型
▶ API 路由 routers/ · 核心与条件路由
/api/analysis434行 /api/browser315行 /api/files276行 /api/code-intel213行 /api/git125行 /api/v1/tokens97行 /api/code-quality95行 /api/tokenizer73行
7个能力域 支持优雅降级
CODE_INTELFILE_PROCESSINGCODE_QUALITYANALYSISGIT_ENHANCEDBROWSER_AUTOMATIONHTTP_API
▸ 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个) → 浏览器渲染展示 32文件 8,066行 · 服务 + CLI 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/ · 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 · 调用图构建 ChangeImpactAnalyzer 变更影响 BFS 传播 · 60s 超时保护 impact_level: direct → indirect → potential IN: file_path+changed_lines → OUT: 影响链路图 change_impact_analyzer.py · 影响分析 (F33) CodePathTracer API 端点扫描 + 正向 BFS 调用路径追踪 Java Spring Boot · Python FastAPI · TS Express IN: entry_file+function → OUT: 层级调用链 code_path_tracer.py · 路径追踪 (F40) SequenceDiagramGenerator Mermaid 时序图 · Controller→Service→Repo 参与者角色映射 · 循环调用检测与截断 IN: API路径/方法签名 → OUT: sequenceDiagram sequence_diagram_generator.py · 时序图 (F35) FlowChartGenerator Mermaid 流程图 · if/loop/try 控制流 tree-sitter AST 解析 · 嵌套深度限制 3 层 IN: target方法体 → OUT: flowchart TD flow_chart_generator.py · 流程图 (F35) 支撑服务层 · services/ TreeSitterService 50+ 语言 AST 统一接口 238行 ComplexityAnalyzer radon+tree-sitter 启发式 516行 FileDetector · GitEnhancedService · BrowserService services/ · 浏览器会话、Git增强、文件检测与复杂度分析 ↓ 被 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 7 能力域 CODE_INTEL · FILE_PROCESSING · CODE_QUALITY · ANALYSIS · GIT_ENHANCED · BROWSER_AUTOMATION · HTTP_API capabilities.py:19 CapabilityDomain · 四层检测: 包导入 + 版本校验 + 系统二进制 + 冒烟测试 · 缺失能力优雅降级 8 路由模块 · 30+ 端点 5 分析器 · 2,872行 10 核心库 · 17 种语言
▸ Java ↔ Python 服务完整调用流 · PythonCapabilityAwareClient · 7能力域 · 指数退避重试
后端 → Python 服务完整调用流 PythonCapabilityAwareClient · ConcurrentHashMap + TTL · 指数退避重试 · 7能力域动态注册 Java 工具层 · Tool.call() Spring Boot 3.4 · :8080 BashTool 命令执行 · 沙箱 GitTool Git增强操作 WebBrowserTool 浏览器自动化 CodeQualityTool 代码质量分析 FileAnalysisTool 文件处理分析 AnalysisTool 代码分析 PythonCapabilityAwareClient callIfAvailable(domain, endpoint, body, type) ① isCapabilityAvailable(domain) ② HttpClient.POST /api/{domain}/{op} ③ ObjectMapper.readValue() → Optional<T> 重试: 3次 · 指数退避: 500ms·1s·2s·4s 连接3s · 读取30s · 重型120s ConcurrentHashMap + TTL · 能力探测 GET /api/health/capabilities → Map<domain, CapabilityStatus> 成功缓存 5min · 失败缓存 30s · refreshIfStale() HTTP 通信层 · 127.0.0.1:8000 Java HttpClient → Python FastAPI POST http://127.0.0.1:8000/api/{domain}/{operation} Content-Type: application/json Body: JSON序列化请求对象 · ObjectMapper 超时: 连接 3s · 普通读取 30s · 重型操作 120s 重试策略: maxRetries=3 · initialDelay=500ms · maxDelay=4s · backoff×2 JSON Response · 200 OK Pydantic BaseModel 序列化 → JSON ← ObjectMapper.readValue(body, TypeReference<T>) → Optional<T> 能力探测 · GET /api/health/capabilities 启动时全量探测 → Caffeine 缓存 → refreshIfStale() 成功 TTL=5min · 失败 TTL=30s · 每次调用前检查 调用时序 1. Tool.call() 触发 2. isCapabilityAvailable(domain) [Caffeine] 3. POST /api/{domain}/{operation} 4. 失败? → 指数退避重试 (500ms→1s→2s→4s) 5. FastAPI 路由分发 → Pydantic 验证 6. 业务处理器执行 7. JSON Response → ObjectMapper 8. Optional<T> 返回调用方 全链路耗时: 普通 <100ms · 代码分析 <2s · 浏览器 <30s 异常降级: 连接拒绝/超时 → Optional.empty() → 工具Fallback Python FastAPI · :8000 uvicorn · Pydantic · 动态路由注册 code-intel · /api/code-intel 代码智能: AST分析 · 符号提取 · 复杂度 files · /api/files 文件处理: 编码检测 · 内容分析 · 统计 git · /api/git Git增强: diff分析 · 影响评估 · 变更追踪 browser · /api/browser 浏览器自动化: Playwright · 截图 · DOM code-quality · /api/code-quality 代码质量: 圈复杂度 · 重复检测 · 规范 analysis · /api/analysis 分析: 变更影响 · 架构图 · 时序图 请求处理管线 FastAPI Router → Pydantic 模型验证 → 业务处理器 → BaseModel 响应序列化 异常: HTTPException → {detail, status_code} GET /api/health/capabilities 返回: {domain: {available, version, features}} 四层检测: 包导入·版本校验·系统二进制·冒烟测试 前端代理 · vite.config.ts /api/git, /api/files, /api/code-quality, /api/analysis → Python :8000 /api → Java :8080 /ws → Java :8080 (WebSocket) 超时配置 连接超时: 3秒 · 普通读取: 30秒 · 重型操作: 120秒 重试: maxRetries=3 · initialDelay=500ms · maxDelay=4000ms 能力域统计 6 域 · 30+ 端点 · 动态注册 优雅降级: 不可用→Optional.empty() capabilities.py · PythonCapabilityAwareClient.java
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 7个能力域 · 按能力条件装载 · venv隔离 前端静态资源 /app/static/ · Spring Boot 托管 React 18.3 Zustand 37 Monaco Editor xterm.js 112组件 · 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 · ea0170c · 2026-08-09 · 134,826 Product Lines · 863 Git-Tracked Files