ZhikunCode — Complete System Architecture

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
产品源代码	863 个 Git 跟踪文件 · ea0170c / 2026-08-09（不统计本地忽略文件）
测试规模	Java + Python / 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

三端分离架构总览

核心通信链路

▸ 三端分离架构全景插画

▶ 5条通信链路详情

#	链路	协议	关键文件
1	前端 → Java 后端	REST API + WebSocket/STOMP	dispatch.ts + stompClient.ts
2	前端 → Python 服务	Vite Proxy 转发	/api/git, /api/files, /api/code-quality, /api/analysis → :8000
3	Java → LLM	HTTP/SSE Stream	LlmProviderRegistry → Anthropic / OpenAiCompatible
4	Java → MCP Server	4种传输	McpClientManager — STDIO/SSE/HTTP/WS
5	Java → Docker	Docker API	SandboxManager — 容器隔离执行

02.5

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

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

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

02b

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

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步循环引擎

▶ 引擎关键特性

流式工具执行

完整响应验证后执行 · 工具参数实时预览

413两级压缩 + 条件性媒体恢复

两级压缩 → 条件性媒体恢复 → 耗尽后报错终止

事务边界

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

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

▸ Step 5.5 Self-Correction Detection · SelfCorrectionLoop.java MAX_ATTEMPTS_DEFAULT=3 / MAX_ATTEMPTS_SWE_BENCH=7（场景动态选择）

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 终态，迟到回调不能覆盖权威结果。

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 边界和执行前复检以当前提交中的枚举、服务实现、数据库迁移与自动化测试为权威依据。

↻

运行证据边界

运行日志仅用于内部交叉核验关联上下文、工具链和恢复路径；不公开任务内容、路径、会话标识、时间窗口或运行统计，也不将未覆盖能力标记为日志已验证。

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

Grant、权限模式与持久交互

▸ AuthorizationService 裁决与 V015/V019 数据权威

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、敏感文件和高风险操作始终受独立安全控制。

05

Bash 安全模块 — 6层 AST 解析

tool/bash/ · 语义分析、分类、路径和执行前复检

AST 解析架构 (递归下降)

parseProgram()
└─ parseStatements(terminator)
└─ parseAndOr()
└─ parsePipeline()
└─ parseCommand()
├─ parseSimpleCommand()
├─ parseIf / While / For
├─ parseFunction
└─ subshell / compound

核心组件

BashParserCore递归下降解析器

BashCommandClassifier命令分类引擎

BashLexer词法分析器

BashSecurityAnalyzerAST 安全扫描

PathValidator路径安全校验

SedValidatorsed 命令校验

HeredocExtractorheredoc 提取

安全分析结果模式: Simple(commands) TooComplex(reason) ParseUnavailable

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

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

06

LLM 多提供商架构

llm/ · Provider注册、能力目录、重试与降级

▶ Provider 抽象层

LlmProviderRegistry  — 提供商注册中心
├── AnthropicProvider  → Claude 系列
└── OpenAiCompatibleProvider 
├── OpenAI GPT
├── 通义千问 (Qwen)
├── DeepSeek 直连（deepseek-flash / V4.1 Flash 原生视觉）
├── Moonshot / Kimi
├── 智谱 GLM-5.3
├── ZenMux：Anthropic → Chat Completions；OpenAI / Google / xAI → Responses
└── Ollama 本地部署

模型别名:

light → qwen3.8-max-0902

standard → qwen3.8-max-0902

premium → qwen3.8-max-0902

百炼 Token Plan → qwen3.8-max / qwen3.8-flash / deepseek-v4-pro-0813 / deepseek-v4-flash-0731 / deepseek-v4.1-flash（独立 Provider；服务端 app.model.default 为 V4.1 Flash；前端初始偏好为千问，配置与选择优先）

主对话跟随用户选择；Agent 优先使用显式 model，其次继承父查询模型，最后由 premium 别名兜底；Agent 型 Task 沿用继承与兜底规则。快速查询用 LLM_FAST_MODEL，摘要用独立的 LLM_COMPACT_MODEL，图片兜底用 LLM_VISION_FALLBACK_MODEL；快速查询与图片兜底默认 deepseek-v4.1-flash（百炼），摘要默认 deepseek-flash（DeepSeek 官方直连）。两款默认模型的流式请求与压缩摘要均发送 thinking=enabled、reasoning_effort="max"（DeepSeek 官方直连的非流式快速查询不注入 thinking）。

▶ 辅助组件

ModelRegistry
模型配置注册

MessageParamConverter
消息参数转换

ThinkingBudgetCalculator
thinking预算

LlmErrorClassifier
错误分类

RetryPolicy
重试策略

ApiKeyRotationManager
密钥轮换管理

ZenMux Responses — 推理、工具调用与跨轮状态闭环

▶ 精确模型路由 → 无服务端会话请求 → SSE 终态门禁 → 原始状态续轮内部状态公开脱敏

1

仅四个精确模型进入 /responses

openai/gpt-5.6-sol、openai/gpt-6-astra、google/gemini-3.8-flash、x-ai/grok-4.6。Opus/Fable 与同步调用仍走 Chat Completions。

2

请求不依赖 ZenMux 服务端会话

store:false，不发送 previous_response_id/conversation；请求 encrypted reasoning、并行工具调用与显式输出预算。

3

成功终态后才执行工具

并行函数调用按输出项分桶；只有 response.completed 才交给工具执行器。失败、错误或无终态 EOF 均失败关闭；无函数调用的 max-output incomplete 可恢复。

4

完整输出保存在内部状态块

provider_response_state 按原顺序保存 provider、精确模型、摘要和完整 response.output[]；不新增数据库表。

5

同 provider + model 才权威回放

匹配时原始状态原子回放并独立计入 Token 预算；模型切换或 fallback 时忽略该状态，改用普通文本、thinking 与工具投影。

6

所有公开出口统一脱敏

PublicMessageProjection 覆盖 REST、WebSocket、分页恢复和 JSON/Markdown 导出；原始状态、签名与 encrypted_content 永不离开后端。

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

Provider 的逗号分隔多 Key 配置支持轮换；OpenAiCompatibleProvider 对订阅额度错误标记 Key 冷却，ApiKeyRotationManager 跳过冷却 Key。全部冷却时返回最早恢复的 Key，不保证仍有可用额度；这与模型降级是不同机制。

API 密钥轮换 — ApiKeyRotationManager

06a

Token 预算与模型策略

▶ IncrementalCollapseManager 增量折叠

注解@Service @ConditionalOnProperty(name="context.cascade.incremental-collapse.enabled")

shouldCollapse()累计 turnCount，每10轮触发折叠

recordCollapse()记录折叠段元数据

状态管理会话级 ConcurrentHashMap · 30分钟超时自动清理

▶ ModelTierService 模型降级

注解@Service

resolveModel()选择最佳可用层级

triggerCooldown()API容量错误 → 冷却管理

reportSuccess()健康探测恢复（3次成功阈值）

冷却策略30分钟默认 · retry-after感知 · 短期重试豁免

08

MCP 双向协议架构

mcp/ 30文件（main/源码，含测试则34文件/）

McpClientManager · 4协议 Client/Server 双向支持 MCP 2024-11-05 规范生命周期: connect→init→ready→close STDIO · SSE · HTTP · WebSocket

09

工具系统

40+ 内置工具 · MCP / 插件 / 平台条件工具动态扩展

▶ 工具分类树

文件操作

ReadFile

WriteFile

EditFile

ListDir

SearchFiles

执行 & 终端

BashTool → Sec §5

TaskCreateTool

NotebookEditTool

搜索 & 分析

GrepTool

GlobTool

CodeSearchTool

Agent & 协作

AgentTool

MemoryTool → §11

McpTool → §7

Web & Git

WebFetchTool

WebSearchTool

GitTool

共 51 个工具实现 · 工具提供 Schema/元数据，生产授权由 Analyzer + AuthorizationService + Gateway 统一负责

▸ 工具分类与执行管道全景

9b

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

command/ 9个核心类 + impl/ 37个实现· 88个已注册命令 · WebSocket STOMP 驱动

Frontend Web UI WebSocket STOMP Parser Registry Router 6层安全 Execute ×3 模型 CommandResult 5种·CommandType 3种·Virtual Thread 异步

▶ 文件路径与核心类

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 双模选择

▸ HTTP API 验证执行管道 — 8 Action 策略字典分发

本地文件引用：本机路径与远程 OSS 双路径

▶ GET /api/files/reference-capability → native_path / oss_upload / unavailable 能力判定永久公开警告

native_path · 仅本机安全条件满足

① 直接 loopback、无转发头、启用本地选择器、未配置 allowed roots，且系统选择器可用。

② 前端调用 POST /api/files/pick，并携带 X-Zhikun-Native-Picker: 1。

③ 后端仅返回绝对、canonical、可读普通文件的路径与元数据，不读取或上传内容。

④ 提交为本地文件路径："..."；选择路径不等于授予 Read 工具访问项目外文件。

oss_upload · ECS / 远程 / 代理访问

① OSS 配置可用时，浏览器单选文件并确保目标 Session 已创建。

② POST /api/oss/local-files?fileName=... 以原始请求体流式上传，使用 X-Session-Id 和原始 Content-Type。

③ 提前检查声明长度，读取时再次执行最大 100 MiB 硬截断；临时文件始终清理。

④ SHA-256 幂等对象键 → 私有上传 → 远端校验 → public-read，随后把文件名和 URL 加入提示词。

边界：能力由后端实际访问条件判定，不根据 ECS RAM Role 猜测部署环境。两条路径都不可用时返回 unavailable。远程文件不做扩展名、敏感文件名或内容扫描；对象永久公开，移除标签、切换 Session 或放弃消息均不会删除。该链路与下方需要显式授权的 /publish-oss 产物发布相互独立。

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

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

下图上半部分描述 /publish-oss 产物发布链路：工具先声明预期输出，执行完成后封存并计算哈希；Manifest 状态可以是 verified，也可以是包含目标已验证条目的 partial。目标条目还需在发布前再次匹配哈希，并在用户明确提出发布和通过一次高风险授权后才能进入 OSS。生成、预览或完成 Run 均不会自动上传。下半部分是独立的秒悟发布路径：以工作区快照与 VerifyJourney 证据为依据，不复用 OSS Manifest 作为发布前提。

10

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

L0 SnipL1 MicroCompact L2 AutoCompact L3 IncrementalCollapse L4 ReactiveCompact ContextCascade 六级级联编排

ContextCascade 正常执行流程 — executePreApiCascade

三区划分 — Protected / Compressible / Tail

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

11

辅助系统

▶ 记忆系统 memdir/ · Project记忆与检索

MemdirService核心记忆目录管理

MemorySearchEngineBM25检索(K1=1.2, B=0.75)

MemoryRerankServiceLLM精排(3000ms超时降级)

MemoryTool工具接口

▶ Skill 系统 13 个内置 Skill · 动态扩展

SkillRegistry13 个内置 Skill；BUNDLED → PROJECT → USER 依次注册，同名后者覆盖；项目目录热重载

Bundled Catalogcommit · review · test · pr · debug · verify · remember · software-architecture · csv-data-summarizer · prompt-engineering · test-driven-development · publish-oss · publish-meoo

SkillDefinitionrecord 类型 · SkillSource 六值描述来源，不构成加载优先级

FrontmatterParser简化 YAML 解析 (key: value / 列表项)

FrontmatterData16 个 frontmatter 字段

SkillExecutorSkill 工具的正文 / 元数据返回 · 结果构造等待 120s · 参数校验

SkillToolValidator参数注入检测；当前嵌套深度 ≥3 时拒绝 fork (allowed-tools 白名单仅声明，运行时未拦截)

▶ 安全模块 security/ · Hook与敏感路径

CommandBlacklistService命令黑名单

PathSecurityService路径安全

SensitivePathRegistry敏感路径注册

SensitiveDataFilter数据过滤

SecurityAuditLogger审计日志

▶ Docker 沙箱 sandbox/ · 容器隔离

SandboxManager容器隔离执行环境

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

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

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

Skill 系统加载与执行架构 — 13 个内置 Skill · 工具结果 / 命令提示 · 三类来源加载

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 执行模式

• Skill 工具的 inline：渲染正文通过 tool_result 返回
• fork：返回正文及 agent/model/effort 等元数据，不创建子 Agent
• Web 的 /skill 走 SkillCommand：渲染后由 PROMPT 路径继续当前会话
• 120s 仅限制 inline/fork 的结果构造等待，不含此前解析/渲染或后续模型执行

▸ SkillToolValidator 安全检查

• 每个解析参数：MAX_ARG_LENGTH = 2000 字符
• MAX_FORK_NESTING_DEPTH = 3：当前嵌套深度 ≥3 时拒绝 fork
• 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（BUNDLED → PROJECT → USER 注册与项目热重载） · SkillDefinition（六值来源枚举与元数据） · SkillExecutor（工具正文 / 元数据返回） · SkillCommand（命令提示返回）。加载不设会话累计额度，模型上下文容量保护仍适用；具体源码行号不作为架构契约。

结构化观测、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 和活跃工具状态，并重放待处理的持久交互；前端按绑定代次替换投影。

12

Agent 与后台 Task

5 类 Agent · 同步 / 并行 / 后台委派 · 会话级任务管理

Agent 委派后台 Agent 汇总Task 生命周期

根 Session 身份、授权与验证产物归属

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

▸ 执行架构 — Agent 委派与后台 Task

Agent 执行与交付

▸ 同步 / 后台结果与可叠加的 Worktree 隔离

▸ Task 生命周期 — 准入、执行与实际退出

13

React 前端架构

React · Zustand · 轮次投影 · 响应式工作台

▸ Store 职责与依赖关系

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

▸ 可视化组件矩阵 — 代码分析 · API契约 · 图表组件

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

▶ 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 文件 · 7 能力域

▶ 分析引擎 analyzers/ · 调用图、影响和路径分析

flow_chart_generator.py

code_path_tracer.py

call_graph_builder.py

sequence_diagram_generator.py

change_impact_analyzer.py

▶ 业务服务 services/ · 浏览器、Git与文件服务

browser_service.py浏览器会话与自动化服务

complexity_analyzer.py

tree_sitter_service.py

browser_models.pyPydantic 浏览器数据模型

▶ API 路由 routers/ · 核心与条件路由

/api/analysis /api/browser /api/files /api/code-intel /api/git /api/v1/tokens /api/code-quality /api/tokenizer

7个能力域支持优雅降级

CODE_INTELFILE_PROCESSINGCODE_QUALITYANALYSISGIT_ENHANCEDBROWSER_AUTOMATIONHTTP_API

▸ Python 代码分析引擎架构

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

▸ Java ↔ Python 服务完整调用流 · PythonCapabilityAwareClient · 7能力域 · 指数退避重试

15

部署架构 — 单容器多进程

Single Container · Java主进程托管Python子进程 · 前端静态资源集成 · 日志按日滚动

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 系统架构